Content
# lhs-shared
Shared foundation packages for the **LocalHighStreet** platform. All domain service repositories (`lhs-commerce`, `lhs-consumer`, `lhs-merchant`, etc.) consume packages from this monorepo via GitHub Packages.
---
## Table of Contents
- [Architecture](#architecture)
- [Packages](#packages)
- [MCP Servers](#mcp-servers)
- [Prerequisites](#prerequisites)
- [Getting Started](#getting-started)
- [Development](#development)
- [Testing](#testing)
- [Prisma](#prisma)
- [Publishing](#publishing)
- [Consuming Packages](#consuming-packages)
- [CI/CD](#cicd)
- [Project Structure](#project-structure)
- [Contributing](#contributing)
---
## Architecture
`lhs-shared` is a npm workspaces monorepo containing four core packages and eleven MCP (Model Context Protocol) servers. The core packages provide shared utilities, types, a Prisma database client, and a developer CLI that are consumed by all downstream LocalHighStreet services.
```
lhs-shared
├── packages/
│ ├── shared/ → Utilities, logger, error types, middleware
│ ├── types/ → Shared TypeScript type definitions
│ ├── prisma-client/ → Prisma schema, generated client, migrations
│ └── cli/ → lhs-cli developer tool
└── mcp-servers/ → 11 domain-specific MCP servers
```
Reference: TRD-REPO-SPLIT-001 sections 5.11, 6, 8.
---
## Packages
| Package | Path | Description |
|---------|------|-------------|
| `@localhighstreets/shared` | `packages/shared/` | Shared utilities, logger, error types, middleware, validation, formatting, geo, crypto, date, retry, and cache helpers |
| `@localhighstreets/types` | `packages/types/` | Shared TypeScript type definitions across the platform |
| `@localhighstreets/prisma-client` | `packages/prisma-client/` | Prisma schema (~9,300 lines), generated client, migrations, and seeds |
| `@localhighstreets/cli` | `packages/cli/` | `lhs-cli` developer CLI for direct API access with intelligent caching |
---
## MCP Servers
Eleven domain-specific MCP servers live under `mcp-servers/`, each with its own `package.json`:
| Server | Port | Domain |
|--------|------|--------|
| `platform-core` | 3001 | Authentication, user management, locations, system monitoring |
| `commerce` | 3002 | Products, categories, inventory, orders |
| `merchant` | 3003 | Store management, analytics |
| `consumer` | 3004 | User profiles, shopping, personalisation |
| `loyalty` | 3005 | Traditional/community loyalty, rewards |
| `ai-services` | 3006 | Content generation, sentiment analysis, recommendations |
| `content` | 3007 | Content moderation, digital assets, themes |
| `integration` | 3008 | Third-party platforms, webhooks, sync |
| `security` | 3009 | Security monitoring, threat detection, access control |
| `analytics` | 3010 | Business intelligence, performance monitoring |
| `thesys` | — | System domain server |
See [`mcp-servers/README.md`](mcp-servers/README.md) for detailed server documentation.
---
## Prerequisites
- **Node.js** >= 20.0.0
- **npm** (ships with Node)
- **PostgreSQL** (for Prisma migrations and seeds)
- A GitHub Personal Access Token with `read:packages` scope (for consuming packages)
---
## Getting Started
```bash
# Clone the repository
git clone https://github.com/phillonc/lhs-shared.git
cd lhs-shared
# Install the pre-commit hook (blocks files > 25 MB)
git config core.hooksPath .githooks
# Install all workspace dependencies (also runs prisma generate via postinstall)
npm install
# Build all packages
npm run build
# Run all tests
npm run test
```
---
## Development
### Workspace Scripts
Run these from the repository root:
| Command | Description |
|---------|-------------|
| `npm install` | Install all dependencies and generate Prisma client |
| `npm run build` | Build all packages |
| `npm run test` | Run all test suites |
| `npm run lint` | Lint all packages |
| `npm run prisma:generate` | Regenerate the Prisma client |
| `npm run prisma:validate` | Validate the Prisma schema |
### Working on Individual Packages
```bash
# Build a single package
npm run build --workspace=packages/shared
# Watch mode (shared package)
npm run watch --workspace=packages/shared
# Run tests for a single package
npm run test --workspace=packages/cli
# Run CLI in dev mode
npm run dev --workspace=packages/cli
```
### MCP Servers
```bash
cd mcp-servers
# Install all server dependencies
npm run install:all
# Build all servers
npm run build:all
# Start all servers
npm run dev:all
# Check server health
npm run status
# Stop all servers
npm run stop:all
```
### Branch Naming
| Prefix | Use |
|--------|-----|
| `feat/<description>` | New features |
| `fix/<description>` | Bug fixes |
| `chore/<description>` | Maintenance tasks |
| `claude/<description>-<id>` | AI-assisted branches |
---
## Testing
Tests use **Jest** with `ts-jest`. The global coverage threshold is **40%**.
```bash
# Run all tests
npm run test
# Run tests with coverage (CLI package)
npm run test:coverage --workspace=packages/cli
# Watch mode (CLI package)
npm run test:watch --workspace=packages/cli
```
Test files follow the patterns: `**/__tests__/**/*.test.ts`, `**/*.test.ts`, `**/*.spec.ts`.
---
## Prisma
The Prisma schema lives at `packages/prisma-client/schema.prisma`. The generated client (`packages/prisma-client/generated/`) is **never committed** — it is regenerated automatically during `npm install` via the `postinstall` script.
```bash
# Validate the schema
npm run prisma:validate
# Generate the client
npm run prisma:generate
# Create a new migration (requires DATABASE_URL)
npm run migrate:dev --workspace=packages/prisma-client
# Deploy migrations to production
npm run migrate:deploy --workspace=packages/prisma-client
# Seed the database
npm run seed --workspace=packages/prisma-client
```
### Prisma CLI version — pinned to 6.19.3 (do not use Prisma 7)
The schema uses the Prisma ≤6 datasource style (`url = env("DATABASE_URL")` in
`schema.prisma`). **Prisma 7 rejects this with error P1012** ("The datasource
property `url` is no longer supported in schema files"), so any environment
that resolves the latest Prisma CLI — e.g. a bare `npx prisma generate` on a
fresh checkout, or a consumer repo with its own Prisma 7 install — cannot
validate or generate from this schema.
The CLI and client are therefore pinned to **exactly `6.19.3`** in
`packages/prisma-client/package.json`, and the repo scripts
(`npm run prisma:validate`, `npm run prisma:generate` after `npm install`)
always use the pinned version.
**Consumer repos** (`lhs-content-media`, `lhs-loyalty`, `lhs-merchant`, …)
generating a client from the schema shipped inside
`node_modules/@localhighstreets/prisma-client/` must invoke the pinned CLI explicitly —
do not rely on whatever `prisma` version the consuming repo resolves:
```bash
npx -y prisma@6.19.3 generate --schema=node_modules/@localhighstreets/prisma-client/schema.prisma
```
Equivalent pinned scripts are available inside the package itself:
`npm run generate:pinned` / `npm run validate:pinned`
(`--workspace=packages/prisma-client`). Note that Prisma 6 requires
`DATABASE_URL` to be set (any syntactically valid PostgreSQL URL is enough)
even for `validate`; no database connection is made.
Migrating the schema itself to the Prisma 7 config style (moving the URL to
`prisma.config.ts`) is deliberately NOT done here: a schema without a
datasource `url` is invalid for Prisma 5/6 consumers, so one schema file
cannot satisfy both sides. The pin keeps every consumer on the working path.
### Environment Variables
| Variable | Required For | Description |
|----------|-------------|-------------|
| `DATABASE_URL` | Migrations, seeds | PostgreSQL connection string |
| `NODE_AUTH_TOKEN` | Publishing, consuming | GitHub PAT with `packages` scope |
---
## Publishing
Publishing is **automatic** when a `v*.*.*` tag is pushed to `main`. The GitHub Actions workflow builds all packages and publishes them to GitHub Packages with restricted access.
### Manual Publishing
```bash
export NODE_AUTH_TOKEN=<your-github-pat>
npm run build
npm publish --workspaces --access restricted
```
---
## Consuming Packages
Downstream services must configure their `.npmrc` to resolve the `@localhighstreet` scope from GitHub Packages:
```ini
@localhighstreets:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
```
Then install as usual:
```bash
npm install @localhighstreets/shared @localhighstreets/types @localhighstreets/prisma-client
```
---
## CI/CD
Two GitHub Actions workflows are configured:
### CI (`ci.yml`)
- **Triggers:** Push or PR to `main` / `develop`
- **Steps:** Install, Prisma validate, Lint, Build, Test
- **Environment:** Node.js 20
### Publish (`publish.yml`)
- **Triggers:** Tags matching `v*.*.*`
- **Action:** Publishes all workspaces to GitHub Packages
---
## Project Structure
```
lhs-shared/
├── .github/workflows/ # CI and publish pipelines
├── .githooks/ # Pre-commit hook (25 MB file limit)
├── mcp-servers/ # 11 domain MCP servers
│ ├── platform-core/
│ ├── commerce/
│ ├── merchant/
│ ├── consumer/
│ ├── loyalty/
│ ├── ai-services/
│ ├── content/
│ ├── integration/
│ ├── security/
│ ├── analytics/
│ └── thesys/
├── packages/
│ ├── shared/ # @localhighstreets/shared
│ ├── types/ # @localhighstreets/types
│ ├── prisma-client/ # @localhighstreets/prisma-client
│ └── cli/ # @localhighstreets/cli
├── .eslintrc.js # ESLint + TypeScript config
├── .npmrc # GitHub Packages registry
├── jest.config.js # Jest config (ts-jest, 40% coverage)
├── tsconfig.json # Root TypeScript config (ES2022, strict)
├── package.json # Workspace root
├── CLAUDE.md # AI agent context
└── README.md # This file
```
---
## Contributing
1. Create a feature branch from `main` (`feat/`, `fix/`, or `chore/` prefix).
2. Install the pre-commit hook: `git config core.hooksPath .githooks`.
3. Make focused, incremental changes.
4. Run `npm run build` and `npm run test` before committing.
5. If you touched the Prisma schema, run `npm run prisma:validate`.
6. Do **not** commit `packages/prisma-client/generated/` or files larger than 25 MB.
7. Use descriptive commit messages.
8. Open a pull request targeting `main`.
