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

package/workspace/tools/generators/screen/generator.ts

@@ -0,0 +1,218 @@
+import { formatFiles, Tree, updateJson } from '@nx/devkit';
+import { moduleNames, ModuleNames } from '../naming';
+
+interface ScreenGeneratorOptions {
+  module: string;
+}
+
+const WEB_ROOT = 'apps/web';
+
+/**
+ * Deliberately a skeleton: it wires the hook layer to a route and leaves
+ * placeholders for the list, the filter shell, the empty state, and the
+ * create/edit form. Layout, information hierarchy, and every other UX
+ * judgment belong to ux-planner's rationale and front-end-eng's build, not
+ * to a template that would make every module's screen look identical
+ * before anyone decided it should.
+ */
+export default async function screenGenerator(
+  tree: Tree,
+  options: ScreenGeneratorOptions,
+) {
+  const names = moduleNames(options.module);
+  const dir = `${WEB_ROOT}/src/app/${names.module}`;
+
+  tree.write(`${dir}/page.tsx`, pageFile(names));
+  tree.write(`${dir}/${names.module}-screen.tsx`, screenFile(names));
+  tree.write(`${dir}/${names.module}-form.tsx`, formFile(names));
+  tree.write(`${dir}/${names.module}-screen.spec.tsx`, specFile(names));
+
+  addWebDependencies(tree);
+
+  await formatFiles(tree);
+}
+
+function pageFile(names: ModuleNames): string {
+  return `import { ${names.pascal}Screen } from './${names.module}-screen';
+
+export default function ${names.pascal}Page() {
+  return <${names.pascal}Screen />;
+}
+`;
+}
+
+function screenFile(names: ModuleNames): string {
+  const { pascal, camel, entityPascal } = names;
+
+  return `'use client';
+
+import { useState } from 'react';
+import { useRemove${entityPascal}, use${pascal} } from 'hooks';
+import { ${pascal}Form } from './${names.module}-form';
+
+export function ${pascal}Screen() {
+  const { data, isPending, isError } = use${pascal}();
+  const remove${entityPascal} = useRemove${entityPascal}();
+  const [editingId, setEditingId] = useState<string | null>(null);
+
+  if (isPending) {
+    return <p>Loading ${names.module}…</p>;
+  }
+
+  if (isError) {
+    return <p>${pascal} could not be loaded.</p>;
+  }
+
+  const ${camel} = data ?? [];
+
+  return (
+    <main>
+      <header>
+        <h1>${pascal}</h1>
+        {/* Filter and tab shell — front-end-eng decides which facets a
+            ${names.entityCamel} is filtered by, from ux-planner's rationale. */}
+        <nav aria-label="${pascal} filters" />
+      </header>
+
+      <${pascal}Form
+        editingId={editingId}
+        onDone={() => setEditingId(null)}
+      />
+
+      {${camel}.length === 0 ? (
+        <p>No ${names.module} yet.</p>
+      ) : (
+        <ul>
+          {${camel}.map((${names.entityCamel}) => (
+            <li key={${names.entityCamel}.id}>
+              <button type="button" onClick={() => setEditingId(${names.entityCamel}.id)}>
+                Edit
+              </button>
+              <button
+                type="button"
+                onClick={() => remove${entityPascal}.mutate(${names.entityCamel}.id)}
+              >
+                Delete
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+    </main>
+  );
+}
+`;
+}
+
+function formFile(names: ModuleNames): string {
+  const { pascal, entityPascal, entityCamel } = names;
+
+  return `'use client';
+
+import { useCreate${entityPascal} } from 'hooks';
+
+interface ${pascal}FormProps {
+  editingId: string | null;
+  onDone: () => void;
+}
+
+export function ${pascal}Form({ editingId, onDone }: ${pascal}FormProps) {
+  const create${entityPascal} = useCreate${entityPascal}();
+
+  return (
+    <form
+      aria-label={editingId ? 'Edit ${entityCamel}' : 'Create ${entityCamel}'}
+      onSubmit={(event) => {
+        event.preventDefault();
+        onDone();
+      }}
+    >
+      {/* Fields, validation feedback, and submit affordance are
+          front-end-eng's, built against the contract's own create/update
+          schema rather than duplicated here. */}
+      <button type="submit" disabled={create${entityPascal}.isPending}>
+        Save
+      </button>
+    </form>
+  );
+}
+`;
+}
+
+function specFile(names: ModuleNames): string {
+  const { pascal, entityPascal } = names;
+
+  return `import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { ${pascal}Screen } from './${names.module}-screen';
+
+// Hoisted above the import above by Vitest, which is what lets the screen
+// render against stubbed hooks instead of a live API.
+vi.mock('hooks', () => ({
+  use${pascal}: vi.fn(() => ({ data: [], isPending: false, isError: false })),
+  useCreate${entityPascal}: vi.fn(() => ({ isPending: false, mutate: vi.fn() })),
+  useRemove${entityPascal}: vi.fn(() => ({ isPending: false, mutate: vi.fn() })),
+}));
+
+function renderScreen() {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <${pascal}Screen />
+    </QueryClientProvider>,
+  );
+}
+
+describe('${pascal}Screen', () => {
+  it('renders the empty state when the hook returns no rows', () => {
+    renderScreen();
+
+    expect(screen.getByText(/no ${names.module} yet/i)).toBeInTheDocument();
+  });
+
+  it('renders the filter shell and the create form', () => {
+    renderScreen();
+
+    expect(
+      screen.getByRole('navigation', { name: /${names.module} filters/i }),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole('form', { name: /create /i }),
+    ).toBeInTheDocument();
+  });
+});
+`;
+}
+
+/**
+ * apps/web consumes the hook package as TypeScript source, so the
+ * dependency and the project reference both have to exist before the
+ * screen's own import resolves.
+ */
+function addWebDependencies(tree: Tree) {
+  updateJson(tree, `${WEB_ROOT}/package.json`, (json) => {
+    json.dependencies = {
+      ...json.dependencies,
+      contracts: 'workspace:*',
+      hooks: 'workspace:*',
+    };
+    return json;
+  });
+
+  for (const config of ['tsconfig.json', 'tsconfig.spec.json']) {
+    updateJson(tree, `${WEB_ROOT}/${config}`, (json) => {
+      const references: { path: string }[] = json.references ?? [];
+      for (const path of ['../../packages/contracts', '../../packages/hooks']) {
+        if (!references.some((entry) => entry.path === path)) {
+          references.push({ path });
+        }
+      }
+      json.references = references;
+      return json;
+    });
+  }
+}

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

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "HedgehogScreenLayer",
+  "title": "Screen skeleton 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)?"
+    }
+  },
+  "required": ["module"]
+}

package/workspace/tools/generators/service/generator.ts

@@ -0,0 +1,270 @@
+import { formatFiles, Tree } from '@nx/devkit';
+import { generateLibShell } from '../lib-shell';
+import { moduleNames, ModuleNames } from '../naming';
+
+interface ServiceGeneratorOptions {
+  module: string;
+  toggleField?: string;
+}
+
+export default async function serviceGenerator(
+  tree: Tree,
+  options: ServiceGeneratorOptions,
+) {
+  const names = moduleNames(options.module);
+  const root = `libs/${names.module}/service`;
+
+  await generateLibShell(tree, {
+    directory: root,
+    importName: `${names.module}-service`,
+    tags: [`scope:${names.module}`, 'type:service'],
+    dependencies: { [`${names.module}-repository`]: 'workspace:*' },
+    references: ['../repository/tsconfig.lib.json'],
+  });
+
+  tree.write(`${root}/src/lib/${names.entityKebab}.errors.ts`, errorsFile(names));
+  tree.write(
+    `${root}/src/lib/${names.entityKebab}.service.ts`,
+    serviceFile(names, options.toggleField),
+  );
+  tree.write(
+    `${root}/src/lib/${names.entityKebab}.service.spec.ts`,
+    serviceSpecFile(names, options.toggleField),
+  );
+  tree.write(`${root}/src/index.ts`, barrelFile(names));
+
+  await formatFiles(tree);
+}
+
+/**
+ * A distinct `name` on each error is what the controller layer switches on
+ * to pick a status code — `instanceof` alone does not survive the class
+ * identity being duplicated across a bundling boundary.
+ */
+function errorsFile(names: ModuleNames): string {
+  const { entityPascal, entityCamel } = names;
+
+  return `export class ${entityPascal}NotFoundError extends Error {
+  override readonly name = '${entityPascal}NotFoundError';
+
+  constructor(readonly id: string) {
+    super(\`No ${entityCamel} exists with id \${id}.\`);
+  }
+}
+
+export class ${entityPascal}InvalidStateError extends Error {
+  override readonly name = '${entityPascal}InvalidStateError';
+
+  constructor(message: string) {
+    super(message);
+  }
+}
+`;
+}
+
+/**
+ * The flip is computed from the row this transaction just read, never
+ * from a value the caller supplied: the client has no way to send a
+ * stale one, so two toggles racing against each other serialize into two
+ * flips instead of both writing the same value and losing one.
+ */
+function toggleMethod(names: ModuleNames, toggleField: string): string {
+  const { entityPascal, entityCamel } = names;
+
+  return `
+
+  async toggle${entityPascal}(id: string): Promise<${entityPascal}> {
+    return this.${entityCamel}s.transaction(async (repository) => {
+      const existing = await repository.findById(id);
+      if (!existing) {
+        throw new ${entityPascal}NotFoundError(id);
+      }
+      const updated = await repository.update(id, {
+        ${toggleField}: !existing.${toggleField},
+      } as ${entityPascal}Patch);
+      if (!updated) {
+        throw new ${entityPascal}NotFoundError(id);
+      }
+      return updated;
+    });
+  }`;
+}
+
+function serviceFile(names: ModuleNames, toggleField?: string): string {
+  const { entityPascal, entityCamel, entityKebab, module } = names;
+
+  return `import type {
+  ${entityPascal},
+  ${entityPascal}Draft,
+  ${entityPascal}Patch,
+  ${entityPascal}Repository,
+} from '${module}-repository';
+import { ${entityPascal}NotFoundError } from './${entityKebab}.errors';
+
+/**
+ * Domain logic only — the ts-rest contract has already validated every
+ * input by the time a method here runs, so nothing re-parses.
+ */
+export class ${entityPascal}Service {
+  constructor(private readonly ${entityCamel}s: ${entityPascal}Repository) {}
+
+  async list(): Promise<${entityPascal}[]> {
+    return this.${entityCamel}s.findAll();
+  }
+
+  async getById(id: string): Promise<${entityPascal}> {
+    const ${entityCamel} = await this.${entityCamel}s.findById(id);
+    if (!${entityCamel}) {
+      throw new ${entityPascal}NotFoundError(id);
+    }
+    return ${entityCamel};
+  }
+
+  async create(draft: ${entityPascal}Draft): Promise<${entityPascal}> {
+    return this.${entityCamel}s.create(draft);
+  }
+
+  async update(id: string, patch: ${entityPascal}Patch): Promise<${entityPascal}> {
+    // Read-then-write is two operations against one row, so it runs in one
+    // transaction: without it a concurrent delete between the two leaves
+    // update() returning undefined for a row this method already proved
+    // present.
+    return this.${entityCamel}s.transaction(async (repository) => {
+      const existing = await repository.findById(id);
+      if (!existing) {
+        throw new ${entityPascal}NotFoundError(id);
+      }
+      const updated = await repository.update(id, patch);
+      if (!updated) {
+        throw new ${entityPascal}NotFoundError(id);
+      }
+      return updated;
+    });
+  }
+
+  async remove(id: string): Promise<void> {
+    const removed = await this.${entityCamel}s.remove(id);
+    if (!removed) {
+      throw new ${entityPascal}NotFoundError(id);
+    }
+  }${toggleField ? toggleMethod(names, toggleField) : ''}
+}
+`;
+}
+
+function serviceSpecFile(names: ModuleNames, toggleField?: string): string {
+  const { entityPascal, entityCamel, entityKebab } = names;
+
+  return `import { describe, expect, it, vi } from 'vitest';
+import type { ${entityPascal}Repository } from '${names.module}-repository';
+import { ${entityPascal}NotFoundError } from './${entityKebab}.errors';
+import { ${entityPascal}Service } from './${entityKebab}.service';
+
+function repositoryDouble(
+  overrides: Partial<${entityPascal}Repository> = {},
+): ${entityPascal}Repository {
+  const repository: ${entityPascal}Repository = {
+    findAll: vi.fn(async () => []),
+    findById: vi.fn(async () => undefined),
+    create: vi.fn(async (draft) => ({ id: 'created', ...draft }) as never),
+    update: vi.fn(async () => undefined),
+    remove: vi.fn(async () => false),
+    transaction: vi.fn(async (work) => work(repository)),
+    ...overrides,
+  };
+  return repository;
+}
+
+describe('${entityPascal}Service', () => {
+  it('throws a named domain error when a ${entityCamel} is absent', async () => {
+    const service = new ${entityPascal}Service(repositoryDouble());
+
+    await expect(service.getById('missing')).rejects.toBeInstanceOf(
+      ${entityPascal}NotFoundError,
+    );
+    await expect(service.getById('missing')).rejects.toMatchObject({
+      name: '${entityPascal}NotFoundError',
+    });
+  });
+
+  it('returns the row the repository found, unparsed', async () => {
+    const row = { id: 'present' } as never;
+    const service = new ${entityPascal}Service(
+      repositoryDouble({ findById: vi.fn(async () => row) }),
+    );
+
+    await expect(service.getById('present')).resolves.toBe(row);
+  });
+
+  it('runs a read-then-write update inside one transaction', async () => {
+    const repository = repositoryDouble({
+      findById: vi.fn(async () => ({ id: 'present' }) as never),
+      update: vi.fn(async () => ({ id: 'present' }) as never),
+    });
+    const service = new ${entityPascal}Service(repository);
+
+    await service.update('present', {} as never);
+
+    expect(repository.transaction).toHaveBeenCalledOnce();
+  });
+
+  it('turns a delete that matched nothing into a not-found error', async () => {
+    const service = new ${entityPascal}Service(repositoryDouble());
+
+    await expect(service.remove('missing')).rejects.toBeInstanceOf(
+      ${entityPascal}NotFoundError,
+    );
+  });
+${
+  toggleField
+    ? `
+  it('derives the new ${toggleField} from stored state, not from the caller', async () => {
+    const repository = repositoryDouble({
+      findById: vi.fn(async () => ({ id: 'present', ${toggleField}: true }) as never),
+      update: vi.fn(async (_id, patch) => ({ id: 'present', ...patch }) as never),
+    });
+    const service = new ${entityPascal}Service(repository);
+
+    await service.toggle${entityPascal}('present');
+
+    expect(repository.update).toHaveBeenCalledWith('present', {
+      ${toggleField}: false,
+    });
+    expect(repository.transaction).toHaveBeenCalledOnce();
+  });
+
+  it('flips twice back to the original value, so no flip is lost', async () => {
+    let stored = false;
+    const repository = repositoryDouble({
+      findById: vi.fn(async () => ({ id: 'present', ${toggleField}: stored }) as never),
+      update: vi.fn(async (_id, patch) => {
+        stored = (patch as { ${toggleField}: boolean }).${toggleField};
+        return { id: 'present', ${toggleField}: stored } as never;
+      }),
+    });
+    const service = new ${entityPascal}Service(repository);
+
+    await service.toggle${entityPascal}('present');
+    expect(stored).toBe(true);
+    await service.toggle${entityPascal}('present');
+    expect(stored).toBe(false);
+  });
+
+  it('rejects a toggle against a ${entityCamel} that is not there', async () => {
+    const service = new ${entityPascal}Service(repositoryDouble());
+
+    await expect(service.toggle${entityPascal}('missing')).rejects.toBeInstanceOf(
+      ${entityPascal}NotFoundError,
+    );
+  });
+`
+    : ''
+}});
+`;
+}
+
+function barrelFile(names: ModuleNames): string {
+  return `export * from './lib/${names.entityKebab}.errors';
+export * from './lib/${names.entityKebab}.service';
+`;
+}

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

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "HedgehogServiceLayer",
+  "title": "Domain service 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)?"
+    },
+    "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"]
+}

package/workspace/tools/phase-gate.cjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * Phase gate: "Phase A closes before Phase B opens", enforced in CI.
+ *
+ * Blocks a PR that introduces a `feat(<module>): hooks` or
+ * `feat(<module>): screen-*` commit for a module with no prior
+ * `feat(<module>): api` commit already on the branch (or on the base
+ * branch it diverged from).
+ *
+ * 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".
+ */
+const { execFileSync } = require('node:child_process');
+
+// git without a shell: `base` comes from the environment
+// (GITHUB_BASE_REF is set from the pull request's branch name, which a
+// fork controls), so the range reaches git as one literal argument
+// rather than as text a shell reparses.
+function getCommitSubjects(base) {
+  const range = base ? `${base}..HEAD` : 'HEAD';
+  const out = execFileSync('git', ['log', '--format=%s', range], {
+    encoding: 'utf8',
+  });
+  return out.split('\n').filter(Boolean);
+}
+
+function main() {
+  const base =
+    process.env.PHASE_GATE_BASE || process.env.GITHUB_BASE_REF || 'origin/main';
+
+  let subjects;
+  try {
+    subjects = getCommitSubjects(base);
+  } catch {
+    // Base ref not resolvable (e.g. shallow clone, no such ref) — fall
+    // back to the full local history rather than failing the check for
+    // an unrelated git plumbing reason.
+    subjects = getCommitSubjects(null);
+  }
+
+  const phaseBRe = /^feat\(([a-z0-9-]+)\): (hooks|screen-[\w-]+)/;
+  const phaseARe = (mod) => new RegExp(`^feat\\(${mod}\\): api\\b`);
+
+  const violations = [];
+
+  for (const subject of subjects) {
+    const match = subject.match(phaseBRe);
+    if (!match) continue;
+
+    const mod = match[1];
+    const hasPhaseACommit = subjects.some((s) => phaseARe(mod).test(s));
+
+    if (!hasPhaseACommit) {
+      violations.push({ subject, mod });
+    }
+  }
+
+  if (violations.length > 0) {
+    console.error(
+      'Phase gate failed: Phase B commit(s) with no prior Phase A "api" commit:',
+    );
+    for (const { subject, mod } of violations) {
+      console.error(
+        `  - "${subject}" (module: ${mod}) — expected a prior "feat(${mod}): api" commit`,
+      );
+    }
+    process.exit(1);
+  }
+
+  console.log(
+    'Phase gate passed: every Phase B commit has a prior Phase A "api" commit.',
+  );
+}
+
+main();

package/workspace/tsconfig.base.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "importHelpers": true,
+    "isolatedModules": true,
+    "lib": ["es2022"],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "noEmitOnError": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noUnusedLocals": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "es2022",
+    "customConditions": ["app"]
+  }
+}

package/workspace/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compileOnSave": false,
+  "files": [],
+  "references": [
+    {
+      "path": "./packages/config"
+    },
+    {
+      "path": "./packages/db"
+    },
+    {
+      "path": "./apps/api-e2e"
+    },
+    {
+      "path": "./apps/api"
+    },
+    {
+      "path": "./apps/web"
+    },
+    {
+      "path": "./apps/web-e2e"
+    }
+  ]
+}

package/workspace/vitest.workspace.ts

@@ -0,0 +1,4 @@
+export default [
+  '**/vite.config.{mjs,js,ts,mts}',
+  '**/vitest.config.{mjs,js,ts,mts}',
+];