@skyf0xx/hedgehog-core-full-stack-app 1.0.0

package/workspace/pnpm-workspace.yaml

@@ -0,0 +1,7 @@
+packages:
+  - 'packages/*'
+  - 'apps/*'
+  # Domain libs land as libs/<module>/<layer> during Phase A. Declared up
+  # front so the first module through the repository layer doesn't have to
+  # edit this file before pnpm will link its workspace:* deps.
+  - 'libs/*/*'

package/workspace/tools/generate-feature-modules.cjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/**
+ * Regenerates apps/api/src/app/feature-modules.ts — the barrel that lists
+ * every domain module's NestJS `@Module` class for AppModule to import.
+ *
+ * Written as CommonJS (`.cjs`) deliberately: root `package.json` sets
+ * `"type": "module"`, so a plain `.js` file here would be parsed as ESM
+ * and `require`/`module.exports` below would fail with "require is not
+ * defined".
+ *
+ * Why generated rather than hand-edited: the controller layer's scope is
+ * `apps/api/src/app/{module}/**` (core.yaml) — module-disjoint by
+ * construction, so two modules' controller tasks never touch the same
+ * file. AppModule itself is exclusive: true / once (see core.yaml), so it
+ * can't carry a per-module edit either. A file that every module's
+ * controller task hand-edited (even one line each) would sit outside
+ * every task's declared scope, invisible to the scheduler's conflict
+ * check (src/db/conflict.mjs only compares declared scope globs) — two
+ * concurrent module builds editing it would look conflict-free to the
+ * scheduler while actually racing on one file. Generating it instead
+ * removes the shared edit entirely: every module writes only inside its
+ * own `apps/api/src/app/{module}/` directory (a `{module}.module.ts`
+ * file, discovered here by naming convention), and this script is the
+ * only thing that ever writes feature-modules.ts.
+ *
+ * Convention: any file matching apps/api/src/app/*\/*.module.ts (module
+ * directories only, one level deep — not app.module.ts itself) is treated
+ * as a domain module and must have a named export ending in "Module".
+ *
+ * Run via the `generate-feature-modules` Nx target, which `test` and
+ * `build` 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', 'api', 'src', 'app');
+const OUTPUT_FILE = path.join(APP_DIR, 'feature-modules.ts');
+const HEADER =
+  '// GENERATED FILE — do not hand-edit. Regenerated by\n' +
+  '// tools/generate-feature-modules.cjs (the generate-feature-modules Nx\n' +
+  '// target, which test and build depend on) from every\n' +
+  "// apps/api/src/app/*/*.module.ts file on disk. A module directory's\n" +
+  '// controller layer only ever creates its own *.module.ts inside its own\n' +
+  '// directory — never edits this file.\n';
+
+function findModuleFiles() {
+  if (!fs.existsSync(APP_DIR)) return [];
+  const entries = fs.readdirSync(APP_DIR, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const moduleDir = path.join(APP_DIR, entry.name);
+    for (const file of fs.readdirSync(moduleDir)) {
+      if (file.endsWith('.module.ts')) {
+        files.push(path.join(entry.name, file.replace(/\.ts$/, '')));
+      }
+    }
+  }
+  return files.sort();
+}
+
+function exportNameFor(relativePath) {
+  // "tasks/tasks.module" -> "TasksModule". Every domain module generator
+  // (Nx's @nx/nest:module or hand-authored) names its class
+  // `<PascalCase>Module` to match the file's own `<kebab>.module.ts` name
+  // — the same convention @nx/nest itself uses.
+  const base = path.basename(relativePath).replace(/\.module$/, '');
+  const pascal = base
+    .split('-')
+    .map((seg) => seg.charAt(0).toUpperCase() + seg.slice(1))
+    .join('');
+  return `${pascal}Module`;
+}
+
+function main() {
+  const moduleFiles = findModuleFiles();
+  const imports = [];
+  const names = [];
+
+  for (const relativePath of moduleFiles) {
+    const importName = exportNameFor(relativePath);
+    imports.push(`import { ${importName} } from './${relativePath}';`);
+    names.push(importName);
+  }
+
+  const body =
+    names.length > 0
+      ? `export const featureModules = [${names.join(', ')}];\n`
+      : 'export const featureModules = [];\n';
+
+  const content =
+    HEADER +
+    (imports.length > 0 ? '\n' + imports.join('\n') + '\n' : '') +
+    '\n' +
+    body;
+
+  fs.writeFileSync(OUTPUT_FILE, content);
+  console.log(
+    `Generated ${path.relative(process.cwd(), OUTPUT_FILE)} with ${names.length} feature module(s).`,
+  );
+}
+
+main();

package/workspace/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/workspace/tools/generators/contract/generator.ts

@@ -0,0 +1,336 @@
+import { formatFiles, Tree } from '@nx/devkit';
+import { Field, isDateField, parseFields, zodSchema } from '../fields';
+import { appendBarrelExport, generateLibShell } from '../lib-shell';
+import { moduleNames, ModuleNames } from '../naming';
+
+interface ContractGeneratorOptions {
+  module: string;
+  fields: string;
+  toggleField?: string;
+}
+
+const PACKAGE_ROOT = 'packages/contracts';
+
+export default async function contractGenerator(
+  tree: Tree,
+  options: ContractGeneratorOptions,
+) {
+  const names = moduleNames(options.module);
+  const fields = parseFields(options.fields);
+
+  await generateLibShell(tree, {
+    directory: PACKAGE_ROOT,
+    importName: 'contracts',
+    tags: ['scope:contracts', 'type:contract'],
+    dependencies: {
+      '@ts-rest/core': '3.53.0-rc.1',
+      zod: '^4.4.3',
+    },
+  });
+
+  writeTimestampSchema(tree);
+
+  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, options.toggleField),
+  );
+  tree.write(`${dir}/index.ts`, barrelFile(names));
+  tree.write(
+    `${dir}/${names.module}.spec.ts`,
+    specFile(names, fields, options.toggleField),
+  );
+
+  appendBarrelExport(tree, `${PACKAGE_ROOT}/src/index.ts`, `./${names.module}/index`);
+
+  await formatFiles(tree);
+}
+
+/**
+ * The shared half of the date-mode rule: a `timestamp` column declared
+ * `mode: 'date'` reflects through `createSelectSchema` as `z.date()`, which
+ * the server satisfies with a real `Date` and the browser never can — JSON
+ * carries it as an ISO string. Neither side alone is right, and no
+ * `.transform()` satisfies both, so the contract accepts the union.
+ */
+function writeTimestampSchema(tree: Tree) {
+  const path = `${PACKAGE_ROOT}/src/timestamp.ts`;
+  if (tree.exists(path)) return;
+
+  tree.write(
+    path,
+    `import { z } from 'zod';
+
+export const timestampSchema = z.union([z.date(), z.iso.datetime()]);
+
+export type Timestamp = z.infer<typeof timestampSchema>;
+`,
+  );
+  appendBarrelExport(tree, `${PACKAGE_ROOT}/src/index.ts`, './timestamp');
+}
+
+function entitySchemaFile(names: ModuleNames, fields: Field[]): string {
+  const bodyFields = fields
+    .map((field) => `  ${field.name}: ${zodSchema(field)},`)
+    .join('\n');
+  const createFields = fields
+    .map(
+      (field) =>
+        `  ${field.name}: ${zodSchema(field)}${field.nullable ? '.optional()' : ''},`,
+    )
+    .join('\n');
+
+  return `import { z } from 'zod';
+import { timestampSchema } from '../timestamp';
+
+export const ${names.entityCamel}Schema = z.object({
+  id: z.uuid(),
+${bodyFields}
+  createdAt: timestampSchema,
+  updatedAt: timestampSchema,
+});
+
+export const create${names.entityPascal}Schema = z.object({
+${createFields}
+});
+
+export const update${names.entityPascal}Schema = create${names.entityPascal}Schema.partial();
+
+export type ${names.entityPascal} = z.infer<typeof ${names.entityCamel}Schema>;
+export type Create${names.entityPascal} = z.infer<typeof create${names.entityPascal}Schema>;
+export type Update${names.entityPascal} = z.infer<typeof update${names.entityPascal}Schema>;
+`;
+}
+
+function errorSchemaFile(names: ModuleNames): string {
+  return `import { z } from 'zod';
+
+export const ${names.entityCamel}NotFoundSchema = z.object({
+  error: z.literal('${names.entityPascal}NotFound'),
+  message: z.string(),
+});
+
+export const ${names.entityCamel}BadRequestSchema = z.object({
+  error: z.literal('${names.entityPascal}BadRequest'),
+  message: z.string(),
+});
+
+export type ${names.entityPascal}NotFound = z.infer<typeof ${names.entityCamel}NotFoundSchema>;
+export type ${names.entityPascal}BadRequest = z.infer<typeof ${names.entityCamel}BadRequestSchema>;
+`;
+}
+
+/**
+ * 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 {
+  ${names.entityCamel}Schema,
+  create${names.entityPascal}Schema,
+  update${names.entityPascal}Schema,
+} from './${names.module}.schema';
+import {
+  ${names.entityCamel}BadRequestSchema,
+  ${names.entityCamel}NotFoundSchema,
+} from './${names.module}.errors';
+
+const c = initContract();
+
+export const ${names.camel}Contract = c.router(
+  {
+    list: {
+      method: 'GET',
+      path: '/${names.module}',
+      responses: {
+        200: z.array(${names.entityCamel}Schema),
+      },
+      summary: 'List every ${names.entityCamel}',
+    },
+    get: {
+      method: 'GET',
+      path: '/${names.module}/:id',
+      pathParams: z.object({ id: z.uuid() }),
+      responses: {
+        200: ${names.entityCamel}Schema,
+        404: ${names.entityCamel}NotFoundSchema,
+      },
+      summary: 'Fetch one ${names.entityCamel} by id',
+    },
+    create: {
+      method: 'POST',
+      path: '/${names.module}',
+      body: create${names.entityPascal}Schema,
+      responses: {
+        201: ${names.entityCamel}Schema,
+        400: ${names.entityCamel}BadRequestSchema,
+      },
+      summary: 'Create a ${names.entityCamel}',
+    },
+    update: {
+      method: 'PATCH',
+      path: '/${names.module}/:id',
+      pathParams: z.object({ id: z.uuid() }),
+      body: update${names.entityPascal}Schema,
+      responses: {
+        200: ${names.entityCamel}Schema,
+        400: ${names.entityCamel}BadRequestSchema,
+        404: ${names.entityCamel}NotFoundSchema,
+      },
+      summary: 'Update a ${names.entityCamel}',
+    },
+    remove: {
+      method: 'DELETE',
+      path: '/${names.module}/:id',
+      pathParams: z.object({ id: z.uuid() }),
+      responses: {
+        204: c.noBody(),
+        404: ${names.entityCamel}NotFoundSchema,
+      },
+      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.
+    strictStatusCodes: true,
+  },
+);
+`;
+}
+
+function barrelFile(names: ModuleNames): string {
+  return `export * from './${names.module}.contract';
+export * from './${names.module}.errors';
+export * from './${names.module}.schema';
+`;
+}
+
+function specFile(
+  names: ModuleNames,
+  fields: Field[],
+  toggleField?: string,
+): string {
+  const dateField = fields.find(isDateField);
+  const requiredField = fields.find((field) => !field.nullable);
+
+  return `import { describe, expect, it } from 'vitest';
+import {
+  ${names.camel}Contract,
+  ${names.entityCamel}Schema,
+  create${names.entityPascal}Schema,
+} from './index';
+
+const sample = ${sampleLiteral(names, fields)};
+
+describe('${names.camel} contract', () => {
+  it('exposes the full CRUD route set under /${names.module}', () => {
+    expect(${names.camel}Contract.list.method).toBe('GET');
+    expect(${names.camel}Contract.list.path).toBe('/${names.module}');
+    expect(${names.camel}Contract.get.path).toBe('/${names.module}/:id');
+    expect(${names.camel}Contract.create.method).toBe('POST');
+    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();
+  });
+
+  it('accepts the same row as JSON, where every timestamp is an ISO string', () => {
+    const overTheWire = {
+      ...sample,${dateField ? `\n      ${dateField.name}: sample.${dateField.name}.toISOString(),` : ''}
+      createdAt: sample.createdAt.toISOString(),
+      updatedAt: sample.updatedAt.toISOString(),
+    };
+
+    expect(${names.entityCamel}Schema.parse(overTheWire)).toBeDefined();
+  });
+${
+  requiredField
+    ? `
+  it('rejects a create body missing ${requiredField.name}', () => {
+    const rest = { ...createInput } as Partial<typeof createInput>;
+    delete rest.${requiredField.name};
+
+    expect(create${names.entityPascal}Schema.safeParse(rest).success).toBe(false);
+  });
+`
+    : ''
+}});
+
+const createInput = ${createLiteral(fields)};
+`;
+}
+
+const SAMPLE_UUID = '00000000-0000-4000-8000-000000000000';
+
+function sampleLiteral(names: ModuleNames, fields: Field[]): string {
+  const entries = [
+    `id: '${SAMPLE_UUID}'`,
+    ...fields.map((field) => `${field.name}: ${sampleValue(field)}`),
+    'createdAt: new Date()',
+    'updatedAt: new Date()',
+  ];
+  return `{\n  ${entries.join(',\n  ')},\n}`;
+}
+
+function createLiteral(fields: Field[]): string {
+  const entries = fields
+    .filter((field) => !field.nullable)
+    .map((field) => `${field.name}: ${sampleValue(field)}`);
+  return `{\n  ${entries.join(',\n  ')},\n}`;
+}
+
+function sampleValue(field: Field): string {
+  const byType: Record<string, string> = {
+    string: `'sample'`,
+    text: `'sample'`,
+    boolean: 'false',
+    integer: '1',
+    timestamp: 'new Date()',
+  };
+  return byType[field.type] ?? 'null';
+}

package/workspace/tools/generators/contract/schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "HedgehogContractLayer",
+  "title": "ts-rest contract for one domain module",
+  "type": "object",
+  "properties": {
+    "module": {
+      "type": "string",
+      "description": "Domain module name, plural kebab-case (e.g. tasks, order-items).",
+      "$default": { "$source": "argv", "index": 0 },
+      "x-prompt": "Domain module name (plural kebab-case)?"
+    },
+    "fields": {
+      "type": "string",
+      "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"]
+}