@skyf0xx/hedgehog 4.3.0 → 4.3.4

package/src/db/rebuild.mjs

@@ -43,6 +43,67 @@ function intentExists(db, id) {
   return db.prepare('SELECT 1 FROM intents WHERE id = ?').get(id) !== undefined;
 }
 
+// A rebuild's result is a pure function of the committed sources
+// (`.hedgehog/intents/`, core.yaml, overrides, git history), so the
+// derived graph is cleared before replay rather than replayed on top of
+// whatever the DB already held. Without this, an intent file that was
+// renamed or deleted leaves its tasks behind: the scheduler then sees a
+// ghost task whose scope overlaps the real one and holds the real one
+// back, producing a graph no set of committed intents describes.
+//
+// Deleting `intents` cascades through requirements, tasks,
+// task_requirements, dependencies, artifacts and verifications — every
+// one of which this run re-derives. `debt` and `friction` are the
+// exception: they are operator-recorded notes with no committed source,
+// so they are carried across by task id (deterministic, so a note
+// re-attaches to the same task the replay recompiles). A note whose task
+// no longer exists in the new graph has nowhere to live and is reported
+// rather than silently dropped.
+function clearDerivedGraph(db) {
+  const debt = db.prepare('SELECT task_id, note, logged_at FROM debt').all();
+  const friction = db.prepare('SELECT task_id, note, logged_at FROM friction').all();
+
+  db.prepare('DELETE FROM intents').run();
+  // `friction.task_id` is ON DELETE SET NULL rather than CASCADE, so its
+  // rows outlive the delete above. Clear them too and let restoreNotes be
+  // the single writer, so a note is not duplicated against its own copy.
+  db.prepare('DELETE FROM friction').run();
+
+  return { debt, friction };
+}
+
+function restoreNotes(db, { debt, friction }) {
+  const taskExists = db.prepare('SELECT 1 FROM tasks WHERE id = ?');
+  const insertDebt = db.prepare(
+    'INSERT INTO debt (task_id, note, logged_at) VALUES (?, ?, ?)',
+  );
+  const insertFriction = db.prepare(
+    'INSERT INTO friction (task_id, note, logged_at) VALUES (?, ?, ?)',
+  );
+
+  const orphaned = [];
+
+  for (const row of debt) {
+    if (taskExists.get(row.task_id) === undefined) {
+      orphaned.push({ kind: 'debt', taskId: row.task_id, note: row.note });
+      continue;
+    }
+    insertDebt.run(row.task_id, row.note, row.logged_at);
+  }
+
+  for (const row of friction) {
+    // friction.task_id is nullable — an unattached note always survives.
+    if (row.task_id !== null && taskExists.get(row.task_id) === undefined) {
+      insertFriction.run(null, row.note, row.logged_at);
+      orphaned.push({ kind: 'friction', taskId: row.task_id, note: row.note });
+      continue;
+    }
+    insertFriction.run(row.task_id, row.note, row.logged_at);
+  }
+
+  return orphaned;
+}
+
 // Topological sort over `depends_on`, tie-broken by the file order above
 // so two runs over the same directory always replay identically.
 //
@@ -71,9 +132,9 @@ function orderIntentsForReplay(records, isSatisfied) {
 
     const entry = byId.get(id);
     if (!entry) {
-      // Not a file in this directory. Fine if the DB already has it
-      // (rebuild tolerates an already-populated DB); otherwise the edge
-      // points at nothing and would fail the FOREIGN KEY.
+      // Not a file in this directory, and the derived graph was cleared
+      // before replay, so the edge points at nothing and would fail the
+      // FOREIGN KEY.
       if (isSatisfied(id)) return;
       throw new Error(
         `intent "${requiredBy}" depends_on "${id}", which has no intent file in ` +
@@ -98,12 +159,6 @@ function orderIntentsForReplay(records, isSatisfied) {
 // Reads every intent file, normalizes it, orders the set by depends_on,
 // and inserts the rows. Read-only with respect to the files themselves.
 //
-// The insert is unconditional (an intent id is never re-added through
-// `intent add` in normal use), so rebuild — the one caller that must also
-// tolerate an already-populated DB, per "re-derive from source-of-truth
-// after suspected corruption" — skips any intent whose id is already
-// present rather than letting the UNIQUE constraint fail the whole run.
-//
 // Ordering is resolved for the whole set BEFORE any row is written, so a
 // cycle or a dangling depends_on fails the run without having half-built
 // the graph.
@@ -232,10 +287,9 @@ function markCompletedTasks(db, commitSubjects) {
   const setComplete = db.prepare("UPDATE tasks SET status = 'complete' WHERE id = ?");
   for (const id of complete) setComplete.run(id);
 
-  // Rebuild also runs against an already-populated DB ("after suspected
-  // corruption"), where a once-task may be sitting at `complete` from
-  // before a re-entry pass added work under it. Reconcile it back rather
-  // than leaving the stale status untouched.
+  // A once-task can be marked complete by the loop above and then fail
+  // one of the extra conditions on a later pass of the fixpoint walk.
+  // Reconcile it back rather than leaving the stale status untouched.
   const reopen = db.prepare(
     "UPDATE tasks SET status = 'planned' WHERE id = ? AND status = 'complete'",
   );
@@ -268,6 +322,8 @@ export async function rebuildDb(
 ) {
   applySchema(db);
 
+  const notes = clearDerivedGraph(db);
+
   const intentsReplayed = await replayIntents(db, intentsDir);
 
   const core = await loadCore(corePath);
@@ -277,7 +333,9 @@ export async function rebuildDb(
   const commitSubjects = loadCommitSubjects();
   const tasksMarkedComplete = markCompletedTasks(db, commitSubjects);
 
+  const orphanedNotes = restoreNotes(db, notes);
+
   const drift = detectDrift(db, core, { overrides });
 
-  return { intentsReplayed, tasksMarkedComplete, drift };
+  return { intentsReplayed, tasksMarkedComplete, orphanedNotes, drift };
 }

package/src/golden-cores/full-stack-app/apps/web/package.json

@@ -21,6 +21,18 @@
     "prettier-plugin-tailwindcss": "^0.7.4"
   },
   "nx": {
+    "targets": {
+      "generate-module-routes": {
+        "executor": "nx:run-commands",
+        "cache": true,
+        "inputs": ["{projectRoot}/src/app/*/page.tsx"],
+        "outputs": ["{projectRoot}/src/app/module-routes.ts"],
+        "options": {
+          "command": "node tools/generate-module-routes.cjs",
+          "cwd": "{workspaceRoot}"
+        }
+      }
+    },
     "tags": ["scope:web"]
   }
 }

package/src/golden-cores/full-stack-app/apps/web/src/app/module-routes.ts

@@ -0,0 +1,13 @@
+// GENERATED FILE — do not hand-edit. Regenerated by
+// tools/generate-module-routes.cjs (the generate-module-routes Nx
+// target, which build, typecheck and test depend on) from every
+// apps/web/src/app/*/page.tsx file on disk. A module's screen layer
+// only ever creates its own page.tsx inside its own directory —
+// never edits this file or the root page.
+
+export interface ModuleRoute {
+  href: string;
+  label: string;
+}
+
+export const moduleRoutes: ModuleRoute[] = [];

package/src/golden-cores/full-stack-app/apps/web/src/app/page.tsx

@@ -1,6 +1,13 @@
+import Link from 'next/link';
 import { Button } from '@/components/ui/button';
 import { ThemeToggle } from '@/components/theme-toggle';
+import { moduleRoutes } from './module-routes';
 
+// The index of everything built so far. `moduleRoutes` is generated from
+// the route directories on disk (tools/generate-module-routes.cjs), so a
+// module's screen layer only writes its own apps/web/src/app/<module>/
+// and this page picks it up — no task ever edits this file, which is what
+// keeps it outside every module-scoped layer's ALLOWED SCOPE.
 export default function Index() {
   return (
     <div className="flex min-h-screen flex-col items-center justify-center gap-6 p-8">
@@ -8,7 +15,20 @@ export default function Index() {
         <h1 className="text-2xl font-semibold">Hedgehog</h1>
         <ThemeToggle />
       </div>
-      <Button>Get started</Button>
+
+      {moduleRoutes.length === 0 ? (
+        <p className="text-muted-foreground max-w-prose text-center text-sm">
+          No modules yet. Each one you build gets a route here.
+        </p>
+      ) : (
+        <nav className="flex flex-wrap items-center justify-center gap-3">
+          {moduleRoutes.map((route) => (
+            <Button key={route.href} asChild variant="outline">
+              <Link href={route.href}>{route.label}</Link>
+            </Button>
+          ))}
+        </nav>
+      )}
     </div>
   );
 }

package/src/golden-cores/full-stack-app/nx.json

@@ -2,14 +2,18 @@
   "$schema": "./node_modules/nx/schemas/nx-schema.json",
   "targetDefaults": {
     "build": {
-      "cache": true
+      "cache": true,
+      "dependsOn": ["generate-module-routes"]
+    },
+    "dev": {
+      "dependsOn": ["generate-module-routes"]
     },
     "test": {
       "cache": true,
-      "dependsOn": ["^build", "generate-feature-modules"]
+      "dependsOn": ["^build", "generate-feature-modules", "generate-module-routes"]
     },
     "typecheck": {
-      "dependsOn": ["generate-feature-modules"]
+      "dependsOn": ["generate-feature-modules", "generate-module-routes"]
     },
     "lint": {
       "cache": true

package/src/golden-cores/full-stack-app/packages/db/src/lib/db.ts

@@ -19,7 +19,21 @@ let client: NodePgDatabase | undefined;
 export function getPool(): Pool {
   if (!pool) {
     const env = loadEnv();
-    pool = new Pool({ connectionString: env.DATABASE_URL });
+    pool = new Pool({
+      connectionString: env.DATABASE_URL,
+      // A wedged connection surfaces as a query error rather than a hang.
+      connectionTimeoutMillis: 10_000,
+      idleTimeoutMillis: 30_000,
+    });
+    // `pg` emits 'error' on the pool when an *idle* client's connection dies
+    // (Postgres restart, failover, laptop sleep). Node terminates the process
+    // on an unhandled 'error' event, so without this listener a routine
+    // database blip crashes the API. `pg` has already discarded the bad
+    // client by the time this fires: the next query opens a fresh connection,
+    // so logging and swallowing is the recovery.
+    pool.on('error', (err) => {
+      console.error('idle postgres client error', err);
+    });
   }
   return pool;
 }

package/src/golden-cores/full-stack-app/tools/generate-module-routes.cjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * Regenerates apps/web/src/app/module-routes.ts — the list of every
+ * domain module's route for the root page to link.
+ *
+ * Written as CommonJS (`.cjs`) for the same reason as its sibling
+ * generate-feature-modules.cjs: root `package.json` sets `"type":
+ * "module"`, so a plain `.js` file here would be parsed as ESM.
+ *
+ * Why generated rather than hand-edited: the screen layer's scope is
+ * `apps/web/src/app/{module}/**` (core.yaml) — module-disjoint by
+ * construction, and `validateCore` requires that `{module}` on a
+ * module-axis core, so `apps/web/src/app/page.tsx` one level up is
+ * outside every layer's scope. Without this the root page can never
+ * learn about the modules built beneath it: a finished build ships a
+ * landing page with no route into the app it just built. This is the
+ * same shape as the API's feature-modules barrel, and gets the same
+ * answer — a shared file no module-scoped task can safely touch is
+ * generated, never hand-edited.
+ *
+ * Convention: any apps/web/src/app/<segment>/page.tsx (route directories
+ * only, one level deep — not the root page.tsx itself) is a module
+ * route. Next.js route groups and private directories are skipped:
+ * `(group)` does not appear in the URL, and `_private`/`.`-prefixed
+ * directories are not routes at all.
+ *
+ * Run via the `generate-module-routes` Nx target, which build, typecheck
+ * and test depend on (nx.json targetDefaults) — never run by hand as
+ * part of normal development.
+ */
+const fs = require('node:fs');
+const path = require('node:path');
+
+const APP_DIR = path.join(__dirname, '..', 'apps', 'web', 'src', 'app');
+const OUTPUT_FILE = path.join(APP_DIR, 'module-routes.ts');
+const HEADER =
+  '// GENERATED FILE — do not hand-edit. Regenerated by\n' +
+  '// tools/generate-module-routes.cjs (the generate-module-routes Nx\n' +
+  '// target, which build, typecheck and test depend on) from every\n' +
+  "// apps/web/src/app/*/page.tsx file on disk. A module's screen layer\n" +
+  '// only ever creates its own page.tsx inside its own directory —\n' +
+  '// never edits this file or the root page.\n';
+
+function findRouteDirs() {
+  if (!fs.existsSync(APP_DIR)) return [];
+  const entries = fs.readdirSync(APP_DIR, { withFileTypes: true });
+  const routes = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    // `(group)` is a route group — it organises files without adding a
+    // URL segment, so it is not a route. `_x` and `.x` are conventions
+    // for "not a route" too.
+    if (/^[(_.]/.test(entry.name)) continue;
+    if (fs.existsSync(path.join(APP_DIR, entry.name, 'page.tsx'))) {
+      routes.push(entry.name);
+    }
+  }
+  return routes.sort();
+}
+
+/** "order-items" -> "Order items" — a label, not a class name. */
+function labelFor(segment) {
+  const spaced = segment.replace(/-/g, ' ');
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+
+function main() {
+  const routes = findRouteDirs();
+
+  const entries = routes
+    .map((segment) => `  { href: '/${segment}', label: '${labelFor(segment)}' },`)
+    .join('\n');
+
+  const body =
+    `export interface ModuleRoute {\n` +
+    `  href: string;\n` +
+    `  label: string;\n` +
+    `}\n\n` +
+    (routes.length > 0
+      ? `export const moduleRoutes: ModuleRoute[] = [\n${entries}\n];\n`
+      : `export const moduleRoutes: ModuleRoute[] = [];\n`);
+
+  fs.writeFileSync(OUTPUT_FILE, HEADER + '\n' + body);
+  console.log(
+    `Generated ${path.relative(process.cwd(), OUTPUT_FILE)} with ${routes.length} module route(s).`,
+  );
+}
+
+main();

package/src/golden-cores/full-stack-app/tools/generators/contract/generator.ts

@@ -6,6 +6,7 @@ import { moduleNames, ModuleNames } from '../naming';
 interface ContractGeneratorOptions {
   module: string;
   fields: string;
+  toggleField?: string;
 }
 
 const PACKAGE_ROOT = 'packages/contracts';
@@ -32,9 +33,15 @@ export default async function contractGenerator(
   const dir = `${PACKAGE_ROOT}/src/${names.module}`;
   tree.write(`${dir}/${names.module}.schema.ts`, entitySchemaFile(names, fields));
   tree.write(`${dir}/${names.module}.errors.ts`, errorSchemaFile(names));
-  tree.write(`${dir}/${names.module}.contract.ts`, contractFile(names));
+  tree.write(
+    `${dir}/${names.module}.contract.ts`,
+    contractFile(names, options.toggleField),
+  );
   tree.write(`${dir}/index.ts`, barrelFile(names));
-  tree.write(`${dir}/${names.module}.spec.ts`, specFile(names, fields));
+  tree.write(
+    `${dir}/${names.module}.spec.ts`,
+    specFile(names, fields, options.toggleField),
+  );
 
   appendBarrelExport(tree, `${PACKAGE_ROOT}/src/index.ts`, `./${names.module}/index`);
 
@@ -115,7 +122,34 @@ export type ${names.entityPascal}BadRequest = z.infer<typeof ${names.entityCamel
 `;
 }
 
-function contractFile(names: ModuleNames): string {
+/**
+ * The toggle route carries `c.noBody()` deliberately: the new value is
+ * derived from stored state on the server, inside the service's existing
+ * transaction. A route that took the current value as a body would be a
+ * read-modify-write with the read served from the client's cache, so two
+ * toggles racing from one stale row would both write the same value and
+ * lose a flip.
+ *
+ * `@ts-rest/core` generates no `body` parameter for a `c.noBody()` route,
+ * so the call site is `client.toggle({ params: { id } })` — passing
+ * `body: undefined` is a compile error.
+ */
+function toggleRoute(names: ModuleNames): string {
+  return `    toggle: {
+      method: 'POST',
+      path: '/${names.module}/:id/toggle',
+      pathParams: z.object({ id: z.uuid() }),
+      body: c.noBody(),
+      responses: {
+        200: ${names.entityCamel}Schema,
+        404: ${names.entityCamel}NotFoundSchema,
+      },
+      summary: 'Flip a ${names.entityCamel} from its stored state',
+    },
+`;
+}
+
+function contractFile(names: ModuleNames, toggleField?: string): string {
   return `import { initContract } from '@ts-rest/core';
 import { z } from 'zod';
 import {
@@ -182,7 +216,7 @@ export const ${names.camel}Contract = c.router(
       },
       summary: 'Delete a ${names.entityCamel}',
     },
-  },
+${toggleField ? toggleRoute(names) : ''}  },
   {
     // apps/api sets /api as a global prefix at runtime (apps/api/src/main.ts),
     // so the paths above stay prefix-free and the client adds the base URL.
@@ -199,7 +233,11 @@ export * from './${names.module}.schema';
 `;
 }
 
-function specFile(names: ModuleNames, fields: Field[]): string {
+function specFile(
+  names: ModuleNames,
+  fields: Field[],
+  toggleField?: string,
+): string {
   const dateField = fields.find(isDateField);
   const requiredField = fields.find((field) => !field.nullable);
 
@@ -221,7 +259,22 @@ describe('${names.camel} contract', () => {
     expect(${names.camel}Contract.update.method).toBe('PATCH');
     expect(${names.camel}Contract.remove.method).toBe('DELETE');
   });
-
+${
+  toggleField
+    ? `
+  it('takes no body on toggle, so a stale client value cannot overwrite state', () => {
+    expect(${names.camel}Contract.toggle.method).toBe('POST');
+    expect(${names.camel}Contract.toggle.path).toBe('/${names.module}/:id/toggle');
+    // c.noBody() is a marker symbol at runtime; what it buys is a client
+    // call signature with no body parameter at all, so the new ${toggleField}
+    // can only be derived server-side.
+    expect(String(${names.camel}Contract.toggle.body)).toBe(
+      'Symbol(ContractNoBody)',
+    );
+  });
+`
+    : ''
+}
   it('accepts a server-side row, where every timestamp is a Date', () => {
     expect(${names.entityCamel}Schema.parse(sample)).toBeDefined();
   });

package/src/golden-cores/full-stack-app/tools/generators/contract/schema.json

@@ -12,8 +12,12 @@
     },
     "fields": {
       "type": "string",
-      "description": "The same name:type list the schema layer was generated with; a trailing ? marks the field nullable.",
+      "description": "The same name:type list the schema layer was generated with; a trailing ? marks the field nullable, and string takes an optional length (title:string(500)).",
       "x-prompt": "Fields (name:type, comma-separated)?"
+    },
+    "toggleField": {
+      "type": "string",
+      "description": "A boolean field from the schema layer to expose as a server-side toggle. Pass the same value to the schema, contract, service, controller, and hook layers. Omit when the module has none."
     }
   },
   "required": ["module", "fields"]

package/src/golden-cores/full-stack-app/tools/generators/controller/generator.ts

@@ -6,6 +6,7 @@ import { moduleNames, ModuleNames } from '../naming';
 interface ControllerGeneratorOptions {
   module: string;
   fields: string;
+  toggleField?: string;
 }
 
 const API_ROOT = 'apps/api';
@@ -43,9 +44,15 @@ export default async function controllerGenerator_(
   // full path, so leaving it would prefix each route twice.
   stripControllerBasePath(tree, `${stem}.controller.ts`);
 
-  tree.write(`${stem}.controller.ts`, controllerFile(names, fields));
+  tree.write(
+    `${stem}.controller.ts`,
+    controllerFile(names, fields, options.toggleField),
+  );
   tree.write(`${stem}.module.ts`, moduleFile(names));
-  tree.write(`${stem}.controller.spec.ts`, controllerSpecFile(names));
+  tree.write(
+    `${stem}.controller.spec.ts`,
+    controllerSpecFile(names, options.toggleField),
+  );
 
   addApiDependencies(tree, names);
 
@@ -62,7 +69,11 @@ function stripControllerBasePath(tree: Tree, path: string) {
   tree.write(path, source.replace(/@Controller\((['"]).*?\1\)/, '@Controller()'));
 }
 
-function controllerFile(names: ModuleNames, fields: Field[]): string {
+function controllerFile(
+  names: ModuleNames,
+  fields: Field[],
+  toggleField?: string,
+): string {
   const { entityPascal, entityCamel, camel, module } = names;
   const dateFields = fields.filter(isDateField);
   const wireShape = dateFields.length
@@ -129,7 +140,25 @@ export class ${names.pascal}Controller {
         } catch (error) {
           return notFoundOr(error, params.id);
         }
-      },
+      },${
+        toggleField
+          ? `
+
+      // The id is the whole request: the service reads the current value
+      // and flips it inside its own transaction, so there is no client
+      // value here that could be stale.
+      toggle: async ({ params }) => {
+        try {
+          return {
+            status: 200 as const,
+            body: await this.${entityCamel}s.toggle${entityPascal}(params.id),
+          };
+        } catch (error) {
+          return notFoundOr(error, params.id);
+        }
+      },`
+          : ''
+      }
     });
   }
 }
@@ -170,10 +199,14 @@ function fromWire<T extends ${wireShape}>(body: T) {
   };
 }
 
-function toDate(value: Date | string | null | undefined) {
+${
+  dateFields.length
+    ? `function toDate(value: Date | string | null | undefined) {
   return typeof value === 'string' ? new Date(value) : value;
 }
-`;
+`
+    : ''
+}`;
 }
 
 function moduleFile(names: ModuleNames): string {
@@ -217,7 +250,7 @@ export class ${pascal}Module {}
 `;
 }
 
-function controllerSpecFile(names: ModuleNames): string {
+function controllerSpecFile(names: ModuleNames, toggleField?: string): string {
   const { entityPascal, pascal, module } = names;
 
   return `import { Test } from '@nestjs/testing';
@@ -285,7 +318,41 @@ describe('${pascal}Controller', () => {
       handler.get({ params: { id: 'any' } } as never),
     ).rejects.toBe(boom);
   });
-});
+${
+  toggleField
+    ? `
+  it('passes only the id to the service, so no client value reaches the write', async () => {
+    const toggle${entityPascal} = vi.fn(async () => ({ id: 'one' }) as never);
+    const controller = await controllerWith({ toggle${entityPascal} });
+
+    const handler = await controller.handler();
+    const response = await handler.toggle({
+      params: { id: 'one' },
+    } as never);
+
+    expect(toggle${entityPascal}).toHaveBeenCalledWith('one');
+    expect(response).toMatchObject({ status: 200 });
+  });
+
+  it('maps a not-found on toggle to 404', async () => {
+    const controller = await controllerWith({
+      toggle${entityPascal}: vi.fn(async () => {
+        throw Object.assign(new Error('absent'), {
+          name: '${entityPascal}NotFoundError',
+        });
+      }),
+    });
+
+    const handler = await controller.handler();
+    const response = await handler.toggle({
+      params: { id: 'missing' },
+    } as never);
+
+    expect(response).toMatchObject({ status: 404 });
+  });
+`
+    : ''
+}});
 `;
 }
 

package/src/golden-cores/full-stack-app/tools/generators/controller/schema.json

@@ -12,8 +12,12 @@
     },
     "fields": {
       "type": "string",
-      "description": "The same name:type list the schema layer was generated with; a trailing ? marks the field nullable.",
+      "description": "The same name:type list the schema layer was generated with; a trailing ? marks the field nullable, and string takes an optional length (title:string(500)).",
       "x-prompt": "Fields (name:type, comma-separated)?"
+    },
+    "toggleField": {
+      "type": "string",
+      "description": "A boolean field from the schema layer to expose as a server-side toggle. Pass the same value to the schema, contract, service, controller, and hook layers. Omit when the module has none."
     }
   },
   "required": ["module", "fields"]