@skyf0xx/hedgehog 0.1.5 → 0.1.7

package/README.md

@@ -124,6 +124,7 @@ Hedgehog is a package of agents and skills. An opinionated stack is used so the
 | Backend | NestJS | Modules naturally mirror Hedgehog's build progression. |
 | ORM | Drizzle + drizzle-zod | Database schema is the single source of truth. |
 | Database | PostgreSQL | Simple, relational, predictable. |
+| Local infra | Docker Compose | Postgres/Redis run identically on every machine. |
 | Platform | Railway | Infrastructure is available from the first commit. |
 | API contract | ts-rest | Contracts are code, not documentation. |
 | Validation | Zod | One schema for runtime and compile time. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo.",
   "type": "module",
   "repository": {
@@ -13,6 +13,9 @@
   "bin": {
     "hedgehog": "bin/cli.mjs"
   },
+  "scripts": {
+    "release": "npm version patch -m \"chore: bump version to %s\""
+  },
   "files": [
     "bin",
     "src/agents",

package/src/skills/hedgehog-bootstrap/SKILL.md

@@ -29,6 +29,7 @@ One opinionated stack, applied the same way on every project:
 | Backend framework | NestJS |
 | ORM | Drizzle (+ `drizzle-zod`) |
 | Database | PostgreSQL |
+| Local infra | Docker Compose (Postgres + Redis) |
 | Platform | Railway |
 | API contract | ts-rest |
 | Validation | Zod |
@@ -106,6 +107,13 @@ project misconfiguration or a corrupted pnpm store — check **Known issue:
 esbuild postinstall version mismatch** below first; this is a known,
 deterministic collision, not something to misdiagnose from scratch.
 
+Confirm Docker is available (`docker --version`) before step 1. Local
+Postgres/Redis run through Docker Compose on every host OS — see **Local
+infra: Docker, always** below. No Docker installed: stop and point the
+user to installing Docker Desktop (macOS/Windows) or Docker
+Engine (Linux) rather than falling back to a natively-installed
+Postgres/Redis.
+
 ## Steps (run in sequence, one commit per step)
 
 ### 1. Nx workspace + `packages/config`
@@ -134,6 +142,18 @@ root; if present, delete it and run `pnpm install` to regenerate
 `pnpm-lock.yaml` before continuing to step 2. Don't assume `nx init`
 respects the locked package manager — verify.
 
+`nx init` also does not create `pnpm-workspace.yaml`. Without it, pnpm
+doesn't recognize `packages/*` or `apps/*` as workspace members —
+`pnpm add -w` fails with `ERR_PNPM_ADDING_TO_ROOT`-adjacent errors, and
+cross-package `pnpm add` for a lib silently installs to the wrong place.
+Create it manually right after `nx init`, before the first `pnpm add`:
+
+```yaml
+packages:
+  - 'packages/*'
+  - 'apps/*'
+```
+
 Then generate the first lib. The **first** `@nx/js:lib` call materializes
 the whole workspace shape (`tsconfig.base.json`, root `eslint.config.mjs`,
 `.prettierrc`, `vitest.workspace.ts`, the `packages/` layout, and the
@@ -150,7 +170,16 @@ files:
 - `packages/config/eslint-base.js` — flat config, extended by every
   app/lib. Include `@nx/enforce-module-boundaries` and `depConstraints`
   from Enforcement wiring below, verbatim.
-- `packages/config/prettier.js` — includes `prettier-plugin-tailwindcss`.
+- `packages/config/prettier.js` — **don't** add `prettier-plugin-tailwindcss`
+  here. The plugin parses every file prettier touches (not just files with
+  Tailwind classes) and throws (`TypeError: e.charAt is not a function` /
+  `a.startsWith is not a function`) on any file when no Tailwind config is
+  resolvable yet — which is every project from step 1 through step 5, since
+  Tailwind doesn't arrive until `apps/web` in step 6. Loading it globally
+  here breaks `nx format:write` and any bare `prettier --check` for the
+  first five steps of every project. Add the plugin to `apps/web`'s own
+  prettier setup (extending this base config) once Tailwind exists, not to
+  the shared base.
 - `packages/config/env.schema.ts` — the Zod env schema from Enforcement
   wiring below (`DATABASE_URL`, `BETTER_AUTH_SECRET`, `REDIS_URL`,
   `NODE_ENV`; extend per project as new infra is added later).
@@ -158,6 +187,53 @@ files:
   declares the project tags table below (`scope:*`, `type:*`) as comments
   or a lookup, so every later generator step tags its project correctly.
 
+Root `eslint.config.mjs` is itself ESM (`.mjs`), which surfaces a Node
+warning ("Module type of file... is not specified") unless the root
+`package.json` declares `"type": "module"`. Setting that is correct and
+worth doing — but it changes how Node resolves *every* plain `.js` file
+in the repo from CommonJS to ESM by default. Several files later steps
+generate are CommonJS (`require`/`module.exports`) and will break with
+`ReferenceError: require is not defined` or `module is not defined` the
+moment `"type": "module"` is set: `apps/*/webpack.config.js`,
+`commitlint.config.js`, and any hand-written CommonJS tool script (e.g.
+`tools/phase-gate.js`). Rename each to `.cjs` as it's created (or convert
+its content to ESM, as `next.config.js` supports natively via
+`export default`) rather than discovering the break later when `nx
+graph` or a generator that depends on the project graph fails
+opaquely — Nx surfaces this as "Failed to process project graph" pointing
+at the offending file, not as a module-system explanation.
+
+Add a root `docker-compose.yml` provisioning Postgres and Redis for local
+dev, regardless of host OS (macOS, Windows, Linux) — see **Local infra:
+Docker, always** below for why this isn't optional. `DATABASE_URL` and
+`REDIS_URL` in `.env` point at the compose services from the first
+commit, matching the env schema below.
+
+```yaml
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: app
+    ports:
+      - '5432:5432'
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - '6379:6379'
+    volumes:
+      - redis-data:/data
+
+volumes:
+  postgres-data:
+  redis-data:
+```
+
 Add an `esbuild` override to root `package.json` in this step, before step
 2 installs `drizzle-kit` — see **Known issue: esbuild postinstall version
 mismatch** below for why.
@@ -209,6 +285,20 @@ structured logging. Call `loadEnv()` at the top of `apps/api/src/main.ts`.
 Tag: `scope:api`. No controllers beyond a health check — domain
 controllers arrive per module in Phase A.
 
+`@nx/nest:app` also scaffolds a companion `apps/api-e2e` project wired to
+Jest (`jest.config.cts`), not Vitest — inconsistent with the locked stack.
+Convert it: delete the Jest config, add a `vitest.config.mts` (mirroring
+`packages/db`'s), and give `apps/api-e2e`'s `tsconfig.spec.json` the same
+`composite`/`declaration` treatment as above. Rename its target from the
+plugin-inferred `test` to an explicit `e2e` — an HTTP e2e suite needs a
+live server (`dependsOn: ["api:build", "api:serve"]`), and if it keeps the
+default `test` name, `nx affected -t test` (what lefthook's pre-commit
+hook runs on every commit, per the Commit gate below) will try to boot a
+server on every commit. Exclude `apps/api-e2e` from the `@nx/vitest`
+plugin's auto-inference in `nx.json` (`"exclude": ["apps/api-e2e/**"]` on
+that plugin entry) so it stops registering a `test` target for this
+project at all, keeping only the manually-defined `e2e` target.
+
 Commit: `feat(api): nest shell + global guard + pino`
 
 ### 5. `apps/worker` — BullMQ seam (Redis, no consumers yet)
@@ -230,17 +320,73 @@ Commit: `feat(worker): bullmq seam, no consumers`
 ```bash
 npx nx g @nx/next:app apps/web
 pnpm add @tanstack/react-query
-pnpm dlx shadcn@latest init
 ```
 
-Wire the TanStack Query provider at the root layout. `shadcn init` writes
-`apps/web`'s base theme (CSS variables for color, radius, light/dark
-mode) — set the actual palette here, once, rather than leaving ShadCN's
-placeholder values for `ui-builder` to inherit unnoticed on the first
-screen. Light/dark mode toggle wiring belongs here too, not as a
-per-screen decision later. No screens or hooks yet — Phase B doesn't
+**Do not run `pnpm dlx shadcn@latest init` (or `shadcn add`) against
+`apps/web` directly.** The shadcn CLI hard-requires a `package.json` in
+its target directory to detect the project; an Nx-generated app under
+this stack has no per-app `package.json` (dependencies live at the
+workspace root). Finding none, the CLI's default behavior is to offer —
+and on `--yes`, silently proceed — to scaffold a *brand-new*
+`create-next-app` project **inside** `apps/web`, complete with its own
+nested `.git`, its own lockfile, and its own `package.json`. This doesn't
+error; it succeeds and leaves a corrupted nested project (e.g.
+`apps/web/web/`) that has to be manually detected and deleted. There is
+currently no supported non-interactive flag that makes shadcn's CLI
+target an existing package-json-less directory in place.
+
+Build the base theme by hand instead: write `apps/web/components.json`
+directly (style, aliases, `tailwind.css` path — the `css` field), add
+`class-variance-authority`, `clsx`, `tailwind-merge`, `lucide-react`, and
+`@radix-ui/react-slot` as dependencies, write `apps/web/src/lib/utils.ts`
+(the standard `cn()` helper), and hand-write the CSS variable theme block
+(light/dark, using shadcn's published default token values) into
+`apps/web`'s global stylesheet. Individual components (e.g. `button.tsx`)
+can then be hand-written from shadcn's published source for that
+component — small, stable, well-known files — rather than fetched via the
+CLI. Set the actual palette here, once, rather than leaving placeholder
+values for `ui-builder` to inherit unnoticed on the first screen. Light/
+dark mode toggle wiring belongs here too, not as a per-screen decision
+later.
+
+Wire the TanStack Query provider at the root layout (App Router: a
+`'use client'` `Providers` wrapper component, since the root layout
+itself is a server component). No screens or hooks yet — Phase B doesn't
 start until Phase A closes for at least one module. Tag: `scope:web`.
 
+**Set `NODE_ENV` explicitly on the `build` target, or the production
+build silently runs in dev mode under Nx.** Nx's task runner sets
+`NODE_ENV=development` by default for every task unless a target
+overrides it — including a plain `nx:run-commands` target running `next
+build`. Next.js's production build pipeline assumes `NODE_ENV=production`;
+running it under `development` produces a build that compiles and
+appears to succeed on individual pages but crashes prerendering the
+auto-generated `/_global-error` route with `TypeError: Cannot read
+properties of null (reading 'useContext')` — a React-internals mismatch
+from the dev/prod build split, not an app bug. This only reproduces
+through `nx run web:build`; the identical `next build --webpack` run
+directly from `apps/web` succeeds, because a bare shell has no `NODE_ENV`
+set and Next defaults it correctly itself — which makes the symptom look
+Nx-specific and environment-related rather than what it is (a task-runner
+default silently overriding a value the build assumes). Set it on the
+`build` target only, in `apps/web/project.json`:
+
+```json
+{
+  "targets": {
+    "build": {
+      "options": {
+        "command": "next build --webpack",
+        "env": { "NODE_ENV": "production" }
+      }
+    }
+  }
+}
+```
+
+Leave `dev` alone — it correctly wants `NODE_ENV=development`, which is
+also what Nx already defaults it to.
+
 Commit: `feat(web): next shell + query provider + base theme`
 
 ### 7. `apps/mobile` — Expo shell (only if mobile is in scope)
@@ -315,6 +461,51 @@ e.g. `libs/orders/port`, `libs/orders/repository`, `libs/orders/service`.
 Building out of order (a controller before a service exists, a hook
 reaching into `apps/api` directly) fails `nx lint`.
 
+The rule list above is illustrative, not exhaustive — `@nx/enforce-
+module-boundaries` denies by default for any project whose tag isn't
+named as a `sourceTag` in some `depConstraints` entry ("A project without
+tags matching at least one constraint cannot depend on any libraries").
+`packages/db` (`scope:db`, `type:adapter`) and `apps/api` (`scope:api`)
+both hit this the moment they're generated and tagged in steps 2 and 4,
+because neither `type:adapter` nor `scope:api` has an entry above. Add
+constraints for every tag combination as it's introduced, not only the
+ones in the illustrative list — at minimum `type:adapter` (needs
+`type:util`, for `packages/config`) and `scope:api` (needs `type:port`,
+`type:service`, `type:util` — never `scope:db` directly; `apps/api`
+reaches storage through a module's repository/service, not by importing
+`packages/db` itself).
+
+### Typecheck target (required before the commit gate can work)
+
+`lefthook.yml`'s pre-commit below runs `nx affected -t typecheck`, but
+`@nx/js:lib` and `@nx/nest:app` don't register a `typecheck` target on
+their own — it only exists once the `@nx/js/typescript` plugin is
+registered in `nx.json`, added in step 1 alongside the eslint and
+vitest plugins:
+
+```json
+{
+  "plugin": "@nx/js/typescript",
+  "options": { "typecheck": { "targetName": "typecheck" } }
+}
+```
+
+Registering the plugin isn't sufficient on its own, either: `tsc
+--build`'s composite-project mode (what the inferred `typecheck` target
+actually runs) requires every `tsconfig.lib.json` and `tsconfig.spec.json`
+it touches to set `"composite": true` and `"declaration": true`. The
+generators don't set these — every `@nx/js:lib` and `@nx/nest:app`
+project needs both added by hand to `tsconfig.lib.json` /
+`tsconfig.app.json` and `tsconfig.spec.json` right after generation, or
+`nx run <proj>:typecheck` fails immediately with `TS5069: Option
+'emitDeclarationOnly' cannot be specified without specifying option
+'declaration' or option 'composite'`. If a project's spec file imports
+from its own lib source (the common case), `tsconfig.spec.json` also
+needs an explicit `references` entry pointing at `tsconfig.lib.json`, or
+`tsc` reports `TS6307: File '...' is not listed within the file list of
+project`. Do this for `packages/config` in step 1 so the pattern is
+established before every later step repeats it.
+
 ### Commit gate (lefthook + commitlint)
 
 Enforces one coherent change, tested, conventionally committed. Runs on
@@ -441,10 +632,30 @@ One shared config, extended everywhere:
 
 - `packages/config/eslint-base.js` — flat config, extended by every
   app/lib.
-- `packages/config/prettier.js` — includes `prettier-plugin-tailwindcss`.
+- `packages/config/prettier.js` — the shared base, *without*
+  `prettier-plugin-tailwindcss` (see step 1 — it belongs in `apps/web`'s
+  own config once Tailwind exists, not the shared base).
 
 A per-app override request signals to fix the base config at the source.
 
+## Local infra: Docker, always
+
+Postgres and Redis run through the `docker-compose.yml` from step 1 on
+every project, on every host OS — macOS, Windows, Linux alike. This isn't
+a convenience default; it's what makes "clone the repo, run the stack"
+mechanically true regardless of who's building. A natively-installed
+Postgres or Redis (Homebrew, an existing Windows service, a system
+package) is a per-machine setup step that isn't in the commit history and
+isn't reproducible on the next machine — exactly the kind of
+tribal-knowledge dependency Hedgehog's enforcement exists to remove.
+
+Don't offer a "native install" path as an alternative, even if a
+contributor already has Postgres running locally for another project. One
+mechanism, every machine: `docker compose up -d` before `pnpm install`,
+every time. If Docker genuinely can't run on a target machine, that's a
+platform-support gap to raise, not a reason to quietly fall back to a
+native install for that one contributor.
+
 ## Known issue: esbuild postinstall version mismatch
 
 `@nx/vite` (step 1) declares `esbuild` as an *optional* peer dependency
@@ -494,3 +705,7 @@ gated by lefthook, each its own commit.
 - Each of the 7 steps is its own commit, in order — same unit-of-work
   discipline as every other step in the discipline, even though this is
   infra rather than a domain module.
+- Local Postgres/Redis always run through the `docker-compose.yml` from
+  step 1, on every host OS. Never substitute a natively-installed
+  Postgres/Redis, even to match a contributor's existing local setup —
+  see **Local infra: Docker, always**.

package/src/templates/CLAUDE.md

@@ -81,11 +81,13 @@ steps from memory:
 ### Stack (locked)
 
 Nx monorepo · pnpm · **NestJS** (all domain logic + DB access) · **Drizzle**
-(+ `drizzle-zod`) · **PostgreSQL** · Railway · **ts-rest** contracts · **Zod**
-validation · **Better Auth** · **TanStack Query** hooks · **Next.js** + ShadCN
-+ Tailwind (web, UI only) · Expo + React Native Reusables + NativeWind
-(mobile, optional) · **BullMQ + Redis** (queues) · Pino logging · Vitest +
-Playwright (tests) · Conventional Commits + commitlint + lefthook · Sentry.
+(+ `drizzle-zod`) · **PostgreSQL** · **Docker Compose** (local Postgres +
+Redis, every host OS) · Railway · **ts-rest** contracts · **Zod**
+validation · **Better Auth** · **TanStack Query** hooks · **Next.js** +
+ShadCN + Tailwind (web, UI only) · Expo + React Native Reusables +
+NativeWind (mobile, optional) · **BullMQ + Redis** (queues) · Pino logging ·
+Vitest + Playwright (tests) · Conventional Commits + commitlint + lefthook ·
+Sentry.
 
 Don't substitute libraries. If a package or generator name changed
 upstream, verify against current docs before running — don't swap in a
@@ -94,6 +96,7 @@ different library.
 ### Layout
 
 ```
+docker-compose.yml   local Postgres + Redis — every host OS, no native install
 apps/
   web        Next.js — UI only
   mobile     Expo — optional
@@ -130,6 +133,9 @@ docs/
   (lefthook gate).
 - **Fix wrong steps at the source** via the Correction Protocol — never a
   downstream workaround.
+- **Local Postgres/Redis always run through `docker-compose.yml`**, on
+  every host OS. Never a natively-installed Postgres/Redis, even to match
+  a contributor's existing local setup.
 - **`packages/config` is the single source** for shared config. A per-app
   override request means fix the base config, not add an override.
 

package/src/templates/TODO.md

@@ -10,7 +10,7 @@ has one, written by planner at Intake. -->
  
 ## Bootstrap
  
-- [ ] Nx workspace + `packages/config`
+- [ ] Nx workspace + `packages/config` (incl. `docker-compose.yml` for local Postgres/Redis)
 - [ ] `packages/db` — Drizzle client
 - [ ] `packages/auth` — Better Auth config
 - [ ] `apps/api` — Nest shell, global guard, Pino