@skyf0xx/hedgehog 4.2.0 → 4.2.2

package/src/golden-cores/full-stack-app/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/src/golden-cores/full-stack-app/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/src/golden-cores/full-stack-app/tools/generators/service/generator.ts

@@ -0,0 +1,194 @@
+import { formatFiles, Tree } from '@nx/devkit';
+import { generateLibShell } from '../lib-shell';
+import { moduleNames, ModuleNames } from '../naming';
+
+interface ServiceGeneratorOptions {
+  module: 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));
+  tree.write(
+    `${root}/src/lib/${names.entityKebab}.service.spec.ts`,
+    serviceSpecFile(names),
+  );
+  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);
+  }
+}
+`;
+}
+
+function serviceFile(names: ModuleNames): 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);
+    }
+  }
+}
+`;
+}
+
+function serviceSpecFile(names: ModuleNames): 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,
+    );
+  });
+});
+`;
+}
+
+function barrelFile(names: ModuleNames): string {
+  return `export * from './lib/${names.entityKebab}.errors';
+export * from './lib/${names.entityKebab}.service';
+`;
+}

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

@@ -0,0 +1,15 @@
+{
+  "$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)?"
+    }
+  },
+  "required": ["module"]
+}

package/src/skills/hedgehog-bootstrap-full-stack-app-core/SKILL.md

@@ -48,9 +48,16 @@ copied to the repo root:
   line to (in that layer's scope — see `core.yaml`). Tagged `scope:db`,
   `type:adapter`.
 - `apps/api/` — Nest shell, `nestjs-pino` wired, CORS enabled for
-  `WEB_ORIGIN`, health check only, no domain controllers. `apps/api-e2e`
-  already converted to Vitest with an explicit `e2e` target. Tagged
-  `scope:api`.
+  `WEB_ORIGIN`, health check only, no domain controllers. Vitest wired
+  (`vitest.config.mts`, `tsconfig.spec.json` with
+  `experimentalDecorators`/`emitDecoratorMetadata` for `Test.createTestingModule`),
+  with a smoke test (`app.module.spec.ts`) instantiating `AppModule`.
+  `apps/api/src/app/feature-modules.ts` is a generated barrel — see
+  **The controller barrel** below — that `AppModule` imports and spreads
+  into its `imports`, so no domain module's controller layer ever edits
+  `app.module.ts`. Depends on `packages/db` (the controller layer imports
+  it by construction). `apps/api-e2e` already converted to Vitest with an
+  explicit `e2e` target. Tagged `scope:api`.
 - `apps/web/` — `.env.example` (`NEXT_PUBLIC_API_BASE_URL`, copied to
   `apps/web/.env.local` in step 4 — Next loads env files from the app
   directory, so the root `.env` never reaches it; the value carries
@@ -59,9 +66,14 @@ copied to the repo root:
   `cn()` util, CSS variable theme, light/dark toggle via an inline
   pre-hydration script + a client-side `ThemeToggle`), TanStack Query
   provider at the root layout, `prettier-plugin-tailwindcss` scoped to
-  its own `.prettierrc.js`. Tagged `scope:web`. `apps/web-e2e` (Playwright,
-  scaffolded automatically by `@nx/next:app`) gets its own `e2e` target by
-  default — no rename needed, unlike `apps/api-e2e`.
+  its own `.prettierrc.js`. Vitest wired for jsdom (`vitest.config.mts`
+  with the `@vitejs/plugin-react` plugin and the `@/*` -> `./src/*` alias
+  apps/web/tsconfig.json already declares, `tsconfig.spec.json`,
+  `src/test-setup.ts` loading `@testing-library/jest-dom`'s matchers),
+  with a smoke test (`theme-toggle.spec.tsx`) rendering and clicking
+  `ThemeToggle` via Testing Library. Tagged `scope:web`. `apps/web-e2e`
+  (Playwright, scaffolded automatically by `@nx/next:app`) gets its own
+  `e2e` target by default — no rename needed, unlike `apps/api-e2e`.
 - The full `@nx/enforce-module-boundaries` `depConstraints` list for
   exactly these tags, matching the project shape `core.yaml`'s layer
   sequence actually produces — plus the `no-restricted-imports` rules that
@@ -80,6 +92,46 @@ copied to the repo root:
 from the committed `pnpm-lock.yaml`, which is a fast resolve against a
 locked graph, not a fresh solve.
 
+## The controller barrel
+
+`apps/api/src/app/app.module.ts` never takes a per-module edit.
+`core.yaml`'s controller layer scope is `apps/api/src/app/{module}/**` —
+module-disjoint by construction, so two modules' controller tasks never
+touch the same file — but `app.module.ts` itself sits outside every
+module's scope, and `src/db/core.mjs`'s `validateCore` rejects a
+non-exclusive layer whose scope omits `{module}` on a module-axis core,
+so the controller layer's scope can't be widened to include it either. A
+file two concurrent module builds both hand-edited would also be
+invisible to the scheduler's conflict check (`src/db/conflict.mjs` only
+compares each task's own declared scope globs), so even a single shared
+line to append to would race undetected.
+
+`apps/api/src/app/feature-modules.ts` solves this by never being
+hand-edited at all: `tools/generate-feature-modules.cjs` globs
+`apps/api/src/app/*/*.module.ts` and writes it as a generated barrel — a
+literal `import { XModule } from './x/x.module'` per domain module found,
+plus an exported `featureModules` array — every time the
+`generate-feature-modules` Nx target runs. `AppModule` imports that one
+generated file and spreads `featureModules` into its own `imports`. A
+module's controller layer only ever creates its own `{module}.module.ts`
+inside its own `apps/api/src/app/{module}/` directory — always in scope,
+never colliding with any other module's controller task. In the shipped
+core, no domain module exists yet, so the glob finds nothing and
+`feature-modules.ts` exports an empty array.
+
+`generate-feature-modules` is wired as an explicit Nx target on `apps/api`
+(`apps/api/package.json`'s `nx.targets`), cached, with `build` declaring
+it as a `dependsOn`; `test` and `typecheck` pick it up the same way
+through `nx.json`'s `targetDefaults` (a project with no matching target,
+such as `db` or `web`, silently skips a missing `dependsOn` entry rather
+than failing). Static imports rather than a runtime directory scan:
+`apps/api` builds through `NxAppWebpackPlugin`, which bundles by
+statically walking `main.ts`'s import graph — a file never reached by a
+static `import`/`require` is dropped from the bundle entirely, so a
+runtime `fs.readdirSync` scan for sibling files would find nothing in the
+built output even though the same scan works when Vitest runs the same
+source directly. Generating literal imports keeps both paths identical.
+
 ## Steps
 
 ### 1. Confirm this hasn't already run
@@ -271,6 +323,15 @@ bug by "cleaning up" what looks like an unnecessary pin or directive.
   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.
+- **`apps/web/vitest.config.mts` needs `environment: 'jsdom'`, the
+  `@vitejs/plugin-react` plugin, and the `@/*` -> `./src/*` alias resolved
+  explicitly.** `@nx/next:app --unitTestRunner=vitest` generates a
+  Node-flavored config with no JSX plugin and no alias resolution — wrong
+  for a React app, and Vitest doesn't read `tsconfig.json`'s `paths` on
+  its own. `apps/web/src/test-setup.ts` (loading
+  `@testing-library/jest-dom/vitest`) is wired as the config's
+  `setupFiles` entry so `toBeInTheDocument()` and friends resolve in every
+  spec without a per-file import.
 - **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