@skyf0xx/hedgehog 0.1.19 → 0.1.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyf0xx/hedgehog",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "Install the Hedgehog build discipline (agents + skills) into a repo.",
   "type": "module",
   "repository": {

package/src/agents/front-end-eng.md

@@ -36,7 +36,15 @@ when a new package needs wiring into a consumer's dependencies.
 
 - **Step 6 (hook)**: build the TanStack Query hook in `packages/hooks`,
   wrapping the ts-rest contract client. One hook per contract operation,
-  typed end to end from the Zod contract.
+  typed end to end from the Zod contract. The client's base URL comes
+  from a `NEXT_PUBLIC_`-prefixed env var (added to
+  `packages/config/env.schema.ts` if it isn't there yet) — never a
+  hardcoded `http://localhost:<port>` literal, even as a "temporary"
+  fallback. `apps/api`'s dev port is `3333` (see `hedgehog-bootstrap-core`
+  — chosen specifically to not collide with `apps/web`'s `next dev`
+  default of `3000`); a literal fallback drifts out of sync with that the
+  moment either port changes and produces a silent 404 that looks like a
+  routing bug, not a config bug.
 - **Step 7 (screen)**: build the screen/component in `apps/web` and/or
   `apps/mobile`, consuming the hook and `ux-planner`'s rationale for that
   module (screen inventory, interaction pattern, information hierarchy).
@@ -77,3 +85,10 @@ when a new package needs wiring into a consumer's dependencies.
 - No inline styles, no CSS modules — Tailwind utilities only.
 - If the contract doesn't cover what the screen needs, stop and flag it
   as a Correction Protocol case rather than reaching past the contract.
+- After editing anything under `packages/hooks/src` (or any other
+  workspace package a running dev server consumes), run
+  `nx run hooks:build` before checking the change in a browser. Next/Expo
+  resolve workspace packages through `package.json`'s `main`/`exports`
+  fields, which point at `dist/`, not live `src/` — a stale `dist/` means
+  the dev server keeps serving the pre-edit code with no error, no
+  warning, and no indication the fix didn't take.

package/src/golden-core/.env.example

@@ -0,0 +1,4 @@
+# Copy to .env for local dev. Matches docker-compose.yml's Postgres
+# service — no edits needed unless you've changed those credentials.
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/app
+NODE_ENV=development

package/src/golden-core/apps/api/package.json

@@ -84,6 +84,8 @@
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
     "@nestjs/platform-express": "^11.0.0",
+    "@ts-rest/core": "3.53.0-rc.1",
+    "@ts-rest/nest": "3.53.0-rc.1",
     "reflect-metadata": "^0.2.0",
     "rxjs": "^7.8.0",
     "tslib": "^2.3.0",

package/src/golden-core/apps/api/src/main.ts

@@ -10,7 +10,10 @@ async function bootstrap() {
   app.useLogger(app.get(Logger));
   const globalPrefix = 'api';
   app.setGlobalPrefix(globalPrefix);
-  const port = process.env.PORT || 3000;
+  // Defaults to 3333, not 3000 — `apps/web`'s `next dev` also defaults to
+  // 3000, and both apps run side by side in local dev (see root `dev`
+  // script), so the api needs a distinct default port to avoid colliding.
+  const port = process.env.PORT || 3333;
   await app.listen(port);
   app
     .get(Logger)

package/src/golden-core/apps/api-e2e/src/support/global-setup.ts

@@ -7,7 +7,7 @@ export default async function setup() {
   console.log('\nSetting up...\n');
 
   const host = process.env.HOST ?? 'localhost';
-  const port = process.env.PORT ? Number(process.env.PORT) : 3000;
+  const port = process.env.PORT ? Number(process.env.PORT) : 3333;
   await waitForPortOpen(port, { host });
 
   return async function teardown() {

package/src/golden-core/apps/api-e2e/src/support/test-setup.ts

@@ -2,5 +2,5 @@ import axios from 'axios';
 
 // Configure axios for tests to use.
 const host = process.env.HOST ?? 'localhost';
-const port = process.env.PORT ?? '3000';
+const port = process.env.PORT ?? '3333';
 axios.defaults.baseURL = `http://${host}:${port}`;

package/src/golden-core/package.json

@@ -3,6 +3,9 @@
   "private": true,
   "type": "module",
   "packageManager": "pnpm@9.0.0",
+  "scripts": {
+    "dev": "docker compose up -d && nx run-many --target=serve,dev --projects=api,web --parallel"
+  },
   "devDependencies": {
     "@commitlint/cli": "^21.2.1",
     "@commitlint/config-conventional": "^21.2.0",

package/src/golden-core/pnpm-lock.yaml

@@ -212,6 +212,12 @@ importers:
       '@nestjs/platform-express':
         specifier: ^11.0.0
         version: 11.1.28(@nestjs/common@11.1.28(reflect-metadata@0.2.2)(rxjs@7.8.1))(@nestjs/core@11.1.28)
+      '@ts-rest/core':
+        specifier: 3.53.0-rc.1
+        version: 3.53.0-rc.1(@types/node@22.20.1)
+      '@ts-rest/nest':
+        specifier: 3.53.0-rc.1
+        version: 3.53.0-rc.1(@nestjs/common@11.1.28(reflect-metadata@0.2.2)(rxjs@7.8.1))(@nestjs/core@11.1.28(@nestjs/common@11.1.28(reflect-metadata@0.2.2)(rxjs@7.8.1))(@nestjs/platform-express@11.1.28)(reflect-metadata@0.2.2)(rxjs@7.8.1))(@ts-rest/core@3.53.0-rc.1(@types/node@22.20.1))(rxjs@7.8.1)
       config:
         specifier: workspace:*
         version: link:../../packages/config
@@ -284,6 +290,9 @@ importers:
 
   packages/config:
     dependencies:
+      '@ts-rest/core':
+        specifier: 3.53.0-rc.1
+        version: 3.53.0-rc.1(@types/node@22.20.1)
       zod:
         specifier: ^4.0.0
         version: 4.4.3
@@ -4515,6 +4524,28 @@ packages:
         integrity: sha512-OvjF+z51L3ov0OyAU0duzsYuvO01PH7x4t6DJx+guahgTnBHkhJdG7soQeTSFLWN3efnHyibZ4Z8l2EuWwJN3A==,
       }
 
+  '@ts-rest/core@3.53.0-rc.1':
+    resolution:
+      {
+        integrity: sha512-hDMXqKHSys6w+kXFW1Q6EvN8QgRvtXKXJ2TpYByKI4TquaPjiTOv99aLD26X4LNRzdna8Ci1PVyzr0jYZv0oNQ==,
+      }
+    peerDependencies:
+      '@types/node': ^18.18.7 || >=20.8.4
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
+  '@ts-rest/nest@3.53.0-rc.1':
+    resolution:
+      {
+        integrity: sha512-tiuxTwXElFrAGFiUpqn78HmGgVY848D5s+uz/wCQwzRgPsfEneeZwOnEtxvXyrAp6tS5VtbVIxrI/kD+yR2zjw==,
+      }
+    peerDependencies:
+      '@nestjs/common': ^9.0.0 || ^10.0.0 || ^11.0.0
+      '@nestjs/core': ^9.0.0 || ^10.0.0 || ^11.0.0
+      '@ts-rest/core': 3.53.0-rc.1
+      rxjs: ^7.1.0
+
   '@tybys/wasm-util@0.10.3':
     resolution:
       {
@@ -16814,6 +16845,17 @@ snapshots:
 
   '@tokenizer/token@0.3.0': {}
 
+  '@ts-rest/core@3.53.0-rc.1(@types/node@22.20.1)':
+    optionalDependencies:
+      '@types/node': 22.20.1
+
+  '@ts-rest/nest@3.53.0-rc.1(@nestjs/common@11.1.28(reflect-metadata@0.2.2)(rxjs@7.8.1))(@nestjs/core@11.1.28(@nestjs/common@11.1.28(reflect-metadata@0.2.2)(rxjs@7.8.1))(@nestjs/platform-express@11.1.28)(reflect-metadata@0.2.2)(rxjs@7.8.1))(@ts-rest/core@3.53.0-rc.1(@types/node@22.20.1))(rxjs@7.8.1)':
+    dependencies:
+      '@nestjs/common': 11.1.28(reflect-metadata@0.2.2)(rxjs@7.8.1)
+      '@nestjs/core': 11.1.28(@nestjs/common@11.1.28(reflect-metadata@0.2.2)(rxjs@7.8.1))(@nestjs/platform-express@11.1.28)(reflect-metadata@0.2.2)(rxjs@7.8.1)
+      '@ts-rest/core': 3.53.0-rc.1(@types/node@22.20.1)
+      rxjs: 7.8.1
+
   '@tybys/wasm-util@0.10.3':
     dependencies:
       tslib: 2.8.1

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

@@ -168,7 +168,11 @@ pnpm add better-auth @thallesp/nestjs-better-auth
 Configure the Drizzle adapter against `packages/db`. Add
 `BETTER_AUTH_SECRET: z.string().min(32)` to `packages/config/env.schema.ts`
 now (it doesn't exist in the core schema `hedgehog-bootstrap-core`
-landed). Tag: `scope:auth`, `type:adapter`.
+landed), and add a matching `BETTER_AUTH_SECRET=` line with a generated
+value to the root `.env.example` — a schema entry with no `.env.example`
+line reproduces the exact `loadEnv()` crash-on-boot that
+`hedgehog-bootstrap-core`'s `DATABASE_URL` entry exists to prevent, just
+for this var instead. Tag: `scope:auth`, `type:adapter`.
 
 Also wire the global auth guard on `apps/api`: `pnpm add
 @thallesp/nestjs-better-auth` there too and register the guard
@@ -196,7 +200,12 @@ pnpm add bullmq ioredis
 Add a `redis` service to the root `docker-compose.yml`
 `hedgehog-bootstrap-core` landed (Postgres-only until now) and
 `REDIS_URL: z.string().url()` to `packages/config/env.schema.ts` (it
-doesn't exist in the core schema):
+doesn't exist in the core schema), plus a matching `REDIS_URL=` line in
+the root `.env.example` pointing at that same `docker-compose.yml`
+service (e.g. `redis://localhost:6379`) — same reasoning as
+`BETTER_AUTH_SECRET` above, a schema entry without a `.env.example` line
+just moves the `loadEnv()` crash-on-boot to this var instead of fixing
+the class of bug:
 
 ```yaml
   redis:

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

@@ -27,12 +27,15 @@ Everything under `src/golden-core/` in the installed Hedgehog package,
 copied to the repo root:
 
 - Root: `nx.json`, `pnpm-workspace.yaml`, `package.json` (with the
-  `pnpm.overrides.esbuild` pin and `packageManager` field),
-  `eslint.config.mjs`, `docker-compose.yml` (Postgres only — Redis joins
-  later, only if the Queue add-on turns on), `lefthook.yml`,
-  `commitlint.config.cjs`, `tools/phase-gate.cjs`,
-  `.github/workflows/phase-gate.yml`, `tsconfig.base.json`,
-  `pnpm-lock.yaml`.
+  `pnpm.overrides.esbuild` pin, `packageManager` field, and a `dev`
+  script — `docker compose up -d && nx run-many --target=serve,dev
+  --projects=api,web --parallel` — so a fresh clone has one command that
+  brings up Postgres and both apps together), `eslint.config.mjs`,
+  `docker-compose.yml` (Postgres only — Redis joins later, only if the
+  Queue add-on turns on), `.env.example` (`DATABASE_URL`/`NODE_ENV`,
+  copied to `.env` in step 4), `lefthook.yml`, `commitlint.config.cjs`,
+  `tools/phase-gate.cjs`, `.github/workflows/phase-gate.yml`,
+  `tsconfig.base.json`, `pnpm-lock.yaml`.
 - `packages/config/` — `eslint-base.js`, `prettier.js` (no
   `prettier-plugin-tailwindcss` — that's `apps/web`'s own config, already
   wired), `env.schema.ts` (core fields only: `DATABASE_URL`, `NODE_ENV`).
@@ -96,9 +99,17 @@ lands" above should be on disk.
 
 ```bash
 pnpm install
+cp .env.example .env
 docker compose up -d
 ```
 
+`.env` is gitignored and never shipped — `.env.example` is the committed
+template (`DATABASE_URL` matching `docker-compose.yml`'s Postgres
+credentials, `NODE_ENV=development`). Skipping the copy means
+`packages/config`'s `loadEnv()` fails its Zod check the moment `apps/api`
+boots (`DATABASE_URL` missing) — a confusing crash to debug live instead
+of one line here.
+
 `pnpm install` resolves against the committed `pnpm-lock.yaml` — this
 should be fast and produce no lockfile changes. A lockfile diff here
 means the shipped `pnpm-lock.yaml` doesn't match `package.json` — that's
@@ -191,6 +202,17 @@ bug by "cleaning up" what looks like an unnecessary pin or directive.
   is ESM (`export default`), and without a matching `"type": "module"`
   Node emits a `MODULE_TYPELESS_PACKAGE_JSON` warning on every prettier
   invocation touching that directory.
+- **`apps/api`'s dev port defaults to 3333, not 3000.** `apps/web`'s
+  `next dev` also defaults to port 3000, and the root `dev` script runs
+  both side by side (`nx run-many --target=serve,dev
+  --projects=api,web`). If `apps/api/src/main.ts` ever falls back to
+  `process.env.PORT || 3000`, whichever process binds the port second
+  either crashes or is silently unreachable, and every API call from the
+  web client 404s against Next's own dev server instead (Next has no
+  matching route, so it serves its catch-all 404 page rather than a
+  connection error — easy to mistake for a routing bug in the api
+  itself). Keep `apps/api`'s fallback at `3333` and don't let it drift
+  back to matching Next's default.
 - **No `NODE_ENV=production` build-target override needed** (Nx
   23.1.0, Next 16.1.7). Targets are inferred from
   `package.json`/`next.config.js` via the `@nx/next` plugin, with no

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

@@ -164,7 +164,12 @@ When a downstream step reveals an upstream step was wrong:
 1. Stop.
 2. Patch the upstream step directly, in place.
 3. Fast-forward every dependent step that breaks, each its own small
-   commit.
+   commit. If the patched step lives in a workspace package (e.g.
+   `packages/hooks`, `packages/contracts`) that a running `web`/`mobile`
+   dev server consumes, run that package's `nx run <pkg>:build` before
+   re-verifying — the dev server resolves the package's built `dist/`,
+   not its `src/`, so an unbuilt patch looks unchanged to anything
+   downstream even though the source is fixed.
 4. The commit messages are the explanation.
 5. Resume the loop.