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

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

@@ -0,0 +1,291 @@
+import { formatFiles, Tree } from '@nx/devkit';
+import { appendBarrelExport, generateLibShell } from '../lib-shell';
+import { moduleNames, ModuleNames } from '../naming';
+
+interface HookGeneratorOptions {
+  module: string;
+  toggleField?: string;
+}
+
+const PACKAGE_ROOT = 'packages/hooks';
+
+export default async function hookGenerator(
+  tree: Tree,
+  options: HookGeneratorOptions,
+) {
+  const names = moduleNames(options.module);
+
+  await generateLibShell(tree, {
+    directory: PACKAGE_ROOT,
+    importName: 'hooks',
+    tags: ['scope:hooks', 'type:hook'],
+    dependencies: {
+      '@tanstack/react-query': '^5.101.4',
+      '@ts-rest/core': '3.53.0-rc.1',
+      contracts: 'workspace:*',
+    },
+    references: ['../contracts/tsconfig.lib.json'],
+  });
+
+  writeApiBaseUrl(tree);
+
+  const dir = `${PACKAGE_ROOT}/src/${names.module}`;
+  tree.write(`${dir}/${names.module}.client.ts`, clientFile(names));
+  tree.write(`${dir}/${names.module}.keys.ts`, keysFile(names));
+  tree.write(
+    `${dir}/use-${names.module}.ts`,
+    hooksFile(names, options.toggleField),
+  );
+  tree.write(`${dir}/index.ts`, barrelFile(names));
+  tree.write(
+    `${dir}/${names.module}.spec.ts`,
+    specFile(names, options.toggleField),
+  );
+
+  appendBarrelExport(tree, `${PACKAGE_ROOT}/src/index.ts`, `./${names.module}/index`);
+
+  await formatFiles(tree);
+}
+
+/**
+ * Read at call time rather than captured at module load: this package is
+ * consumed as TypeScript source by both apps/web (where Next inlines
+ * NEXT_PUBLIC_API_BASE_URL at build time) and Vitest (where it is absent),
+ * and a module-scope read would freeze the test-time fallback into the app.
+ */
+function writeApiBaseUrl(tree: Tree) {
+  const path = `${PACKAGE_ROOT}/src/api-base-url.ts`;
+  if (tree.exists(path)) return;
+
+  tree.write(
+    path,
+    `export function apiBaseUrl(): string {
+  return process.env.NEXT_PUBLIC_API_BASE_URL ?? 'http://localhost:3333/api';
+}
+`,
+  );
+  appendBarrelExport(tree, `${PACKAGE_ROOT}/src/index.ts`, './api-base-url');
+}
+
+function clientFile(names: ModuleNames): string {
+  return `import { initClient } from '@ts-rest/core';
+import { ${names.camel}Contract } from 'contracts';
+import { apiBaseUrl } from '../api-base-url';
+
+export function ${names.camel}Client() {
+  return initClient(${names.camel}Contract, { baseUrl: apiBaseUrl() });
+}
+
+export type ${names.pascal}Client = ReturnType<typeof ${names.camel}Client>;
+`;
+}
+
+/**
+ * A factory rather than loose string arrays: every mutation below
+ * invalidates through the same keys, so a rename that misses one is a
+ * compile error instead of a cache that silently stops refreshing.
+ */
+function keysFile(names: ModuleNames): string {
+  return `export const ${names.camel}Keys = {
+  all: () => ['${names.module}'] as const,
+  lists: () => [...${names.camel}Keys.all(), 'list'] as const,
+  details: () => [...${names.camel}Keys.all(), 'detail'] as const,
+  detail: (id: string) => [...${names.camel}Keys.details(), id] as const,
+};
+`;
+}
+
+function hooksFile(names: ModuleNames, toggleField?: string): string {
+  const { camel, pascal, entityPascal } = names;
+
+  return `import {
+  useMutation,
+  useQuery,
+  useQueryClient,
+} from '@tanstack/react-query';
+import type { Create${entityPascal}, Update${entityPascal} } from 'contracts';
+import { ${camel}Client, type ${pascal}Client } from './${names.module}.client';
+import { ${camel}Keys } from './${names.module}.keys';
+
+const client: ${pascal}Client = ${camel}Client();
+
+export function use${pascal}() {
+  return useQuery({
+    queryKey: ${camel}Keys.lists(),
+    queryFn: async () => {
+      const response = await client.list();
+      if (response.status !== 200) {
+        throw new Error('Failed to load ${names.module}.');
+      }
+      return response.body;
+    },
+  });
+}
+
+export function use${entityPascal}(id: string) {
+  return useQuery({
+    queryKey: ${camel}Keys.detail(id),
+    queryFn: async () => {
+      const response = await client.get({ params: { id } });
+      if (response.status !== 200) {
+        throw new Error(\`Failed to load ${names.entityCamel} \${id}.\`);
+      }
+      return response.body;
+    },
+    enabled: id.length > 0,
+  });
+}
+
+export function useCreate${entityPascal}() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (body: Create${entityPascal}) => {
+      const response = await client.create({ body });
+      if (response.status !== 201) {
+        throw new Error('Failed to create the ${names.entityCamel}.');
+      }
+      return response.body;
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ${camel}Keys.lists() });
+    },
+  });
+}
+
+export function useUpdate${entityPascal}() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async ({
+      id,
+      ...body
+    }: Update${entityPascal} & { id: string }) => {
+      const response = await client.update({ params: { id }, body });
+      if (response.status !== 200) {
+        throw new Error(\`Failed to update ${names.entityCamel} \${id}.\`);
+      }
+      return response.body;
+    },
+    onSuccess: (_result, variables) => {
+      queryClient.invalidateQueries({ queryKey: ${camel}Keys.lists() });
+      queryClient.invalidateQueries({
+        queryKey: ${camel}Keys.detail(variables.id),
+      });
+    },
+  });
+}
+
+export function useRemove${entityPascal}() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (id: string) => {
+      const response = await client.remove({ params: { id } });
+      if (response.status !== 204) {
+        throw new Error(\`Failed to delete ${names.entityCamel} \${id}.\`);
+      }
+      return id;
+    },
+    onSuccess: (id) => {
+      queryClient.invalidateQueries({ queryKey: ${camel}Keys.lists() });
+      queryClient.removeQueries({ queryKey: ${camel}Keys.detail(id) });
+    },
+  });
+}${
+    toggleField
+      ? `
+
+/**
+ * Sends the id and nothing else. The server reads the current
+ * ${toggleField} and flips it inside one transaction, so a stale row in
+ * this cache cannot overwrite a newer state — which is what computing
+ * the new value here from a cached row would do, losing one of any two
+ * flips that raced.
+ */
+export function useToggle${entityPascal}() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: async (id: string) => {
+      const response = await client.toggle({ params: { id } });
+      if (response.status !== 200) {
+        throw new Error(\`Failed to toggle ${names.entityCamel} \${id}.\`);
+      }
+      return response.body;
+    },
+    onSuccess: (_result, id) => {
+      queryClient.invalidateQueries({ queryKey: ${camel}Keys.lists() });
+      queryClient.invalidateQueries({ queryKey: ${camel}Keys.detail(id) });
+    },
+  });
+}`
+      : ''
+  }
+`;
+}
+
+function barrelFile(names: ModuleNames): string {
+  return `export * from './${names.module}.client';
+export * from './${names.module}.keys';
+export * from './use-${names.module}';
+`;
+}
+
+function specFile(names: ModuleNames, toggleField?: string): string {
+  const { camel, entityPascal } = names;
+
+  return `import { describe, expect, it } from 'vitest';
+import { ${camel}Keys } from './${names.module}.keys';
+import {
+  useCreate${entityPascal},
+  useRemove${entityPascal},
+  useUpdate${entityPascal},
+  use${names.pascal},
+} from './use-${names.module}';
+
+describe('${camel} query keys', () => {
+  it('nests every key under one invalidation root', () => {
+    expect(${camel}Keys.all()).toEqual(['${names.module}']);
+    expect(${camel}Keys.lists()).toEqual(['${names.module}', 'list']);
+    expect(${camel}Keys.detail('abc')).toEqual([
+      '${names.module}',
+      'detail',
+      'abc',
+    ]);
+  });
+
+  it('keeps a detail key inside the details prefix, so one call clears both', () => {
+    const detail = ${camel}Keys.detail('abc');
+
+    expect(detail.slice(0, 2)).toEqual(${camel}Keys.details());
+  });
+});
+
+describe('${camel} hooks', () => {
+  it('exposes the query and mutation set the screen layer consumes', () => {
+    expect(use${names.pascal}).toBeTypeOf('function');
+    expect(useCreate${entityPascal}).toBeTypeOf('function');
+    expect(useUpdate${entityPascal}).toBeTypeOf('function');
+    expect(useRemove${entityPascal}).toBeTypeOf('function');
+  });${
+    toggleField
+      ? `
+
+  it('exposes a dedicated ${toggleField} toggle', async () => {
+    const { useToggle${entityPascal} } = await import('./use-${names.module}');
+
+    expect(useToggle${entityPascal}).toBeTypeOf('function');
+  });
+
+  it('routes the toggle at a server endpoint that takes no body', async () => {
+    const { ${camel}Contract } = await import('contracts');
+
+    expect(${camel}Contract.toggle.method).toBe('POST');
+    expect(String(${camel}Contract.toggle.body)).toBe('Symbol(ContractNoBody)');
+  });`
+      : ''
+  }
+});
+`;
+}

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

@@ -0,0 +1,19 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "HedgehogHookLayer",
+  "title": "TanStack Query hook set 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/generators/lib-shell.ts

@@ -0,0 +1,124 @@
+import { libraryGenerator } from '@nx/js';
+import { joinPathFragments, Tree, updateJson } from '@nx/devkit';
+
+/**
+ * The `@nx/js:lib` call every first-arrival layer makes, plus the
+ * corrections this workspace's conventions need on top of the generator's
+ * defaults. Owned here so `contract`, `repository`, `service`, and `hook`
+ * cannot drift on the shell they land.
+ *
+ * Two of those corrections are load-bearing:
+ *
+ * - `@nx/js:lib` writes `module`/`moduleResolution: "nodenext"` into the
+ *   generated tsconfigs and a `.js` extension onto the barrel's own
+ *   relative import. Turbopack cannot resolve a nodenext-style `.js`
+ *   specifier across a pnpm workspace-package boundary, which is why
+ *   `tsconfig.base.json` pins esnext/bundler — a per-package nodenext
+ *   override reintroduces exactly that break for anything `apps/web`
+ *   imports.
+ * - The generated `package.json` carries no `nx.tags`, and
+ *   `packages/config/eslint-base.js`'s `depConstraints` are keyed
+ *   entirely on tags: an untagged project satisfies no constraint and
+ *   fails `@nx/enforce-module-boundaries` on its first workspace import.
+ */
+export interface LibShellOptions {
+  directory: string;
+  importName: string;
+  tags: string[];
+  dependencies?: Record<string, string>;
+  /** tsconfig.lib.json project references, as paths relative to the lib. */
+  references?: string[];
+}
+
+export async function generateLibShell(tree: Tree, options: LibShellOptions) {
+  if (tree.exists(joinPathFragments(options.directory, 'package.json'))) {
+    applyShellConventions(tree, options);
+    return;
+  }
+
+  await libraryGenerator(tree, {
+    directory: options.directory,
+    name: options.importName,
+    bundler: 'none',
+    unitTestRunner: 'vitest',
+    // `linter: 'eslint'` would land a per-package eslint.config.mjs and a
+    // project.json whose empty `tags: []` takes precedence over the
+    // package.json tags below — silently emptying the tag set every
+    // depConstraint in packages/config/eslint-base.js keys on. The root
+    // eslint.config.mjs already covers every project in the workspace.
+    linter: 'none',
+    skipFormat: true,
+  });
+
+  // The generator's placeholder lib + README carry no domain content and
+  // are replaced wholesale by the layer's own files.
+  for (const placeholder of [
+    `${options.directory}/src/lib/${options.importName}.ts`,
+    `${options.directory}/src/lib/${options.importName}.spec.ts`,
+    `${options.directory}/README.md`,
+    `${options.directory}/project.json`,
+    `${options.directory}/eslint.config.mjs`,
+  ]) {
+    if (tree.exists(placeholder)) tree.delete(placeholder);
+  }
+
+  applyShellConventions(tree, options);
+}
+
+function applyShellConventions(tree: Tree, options: LibShellOptions) {
+  updateJson(
+    tree,
+    joinPathFragments(options.directory, 'package.json'),
+    (json) => {
+      json.nx = { ...(json.nx ?? {}), tags: options.tags };
+      if (options.dependencies) {
+        json.dependencies = { ...(json.dependencies ?? {}), ...options.dependencies };
+      }
+      return json;
+    },
+  );
+
+  for (const config of ['tsconfig.lib.json', 'tsconfig.spec.json']) {
+    const path = joinPathFragments(options.directory, config);
+    if (!tree.exists(path)) continue;
+    updateJson(tree, path, (json) => {
+      delete json.compilerOptions?.module;
+      delete json.compilerOptions?.moduleResolution;
+      return json;
+    });
+  }
+
+  if (options.references?.length) {
+    const path = joinPathFragments(options.directory, 'tsconfig.lib.json');
+    updateJson(tree, path, (json) => {
+      const existing: { path: string }[] = json.references ?? [];
+      for (const reference of options.references ?? []) {
+        if (!existing.some((entry) => entry.path === reference)) {
+          existing.push({ path: reference });
+        }
+      }
+      json.references = existing;
+      return json;
+    });
+  }
+}
+
+/**
+ * A barrel line free of the `.js` extension `@nx/js:lib`'s own barrel uses
+ * (see the nodenext note above).
+ */
+export function appendBarrelExport(tree: Tree, barrelPath: string, target: string) {
+  const line = `export * from '${target}';`;
+  const current = tree.read(barrelPath, 'utf-8') ?? '';
+  if (current.includes(line)) return;
+
+  const lines = current
+    .split('\n')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0 && entry !== 'export {};')
+    // The generator's own placeholder barrel line points at a lib file
+    // this shell deleted.
+    .filter((entry) => !/^export \* from '\.\/lib\//.test(entry));
+
+  tree.write(barrelPath, `${[...lines, line].sort().join('\n')}\n`);
+}

package/workspace/tools/generators/naming.ts

@@ -0,0 +1,84 @@
+/**
+ * Every name a layer generator derives from one module name, in one place.
+ *
+ * A domain module is one table (see `.claude/skills/hedgehog-loop`'s Domain
+ * Module Pattern), named in plural kebab-case — `tasks`, `order-items`. The
+ * entity names below are its singular form, which is what a type, a domain
+ * error, and a service method are named after.
+ */
+
+export interface ModuleNames {
+  /** `order-items` — the module name as core.yaml's `{module}` token. */
+  module: string;
+  /** `orderItems` — the Drizzle table export and query-key root. */
+  camel: string;
+  /** `OrderItems` — the NestJS module/controller class prefix. */
+  pascal: string;
+  /** `order-item` — singular kebab, for a singular file name. */
+  entityKebab: string;
+  /** `orderItem` — singular camel, for a variable or a route param. */
+  entityCamel: string;
+  /** `OrderItem` — singular pascal, for the entity type and its errors. */
+  entityPascal: string;
+  /** `order_items` — the Postgres table name. */
+  tableName: string;
+  /** `ORDER_ITEM` — the singular constant case, for a DI token name. */
+  entityConstant: string;
+}
+
+export function moduleNames(module: string): ModuleNames {
+  const normalized = module.trim().toLowerCase();
+  if (!/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(normalized)) {
+    throw new Error(
+      `Module name "${module}" must be lower kebab-case (e.g. tasks, order-items).`,
+    );
+  }
+  const segments = normalized.split('-');
+  const entitySegments = segments.map((segment, index) =>
+    index === segments.length - 1 ? singular(segment) : segment,
+  );
+
+  return {
+    module: normalized,
+    camel: toCamel(segments),
+    pascal: toPascal(segments),
+    entityKebab: entitySegments.join('-'),
+    entityCamel: toCamel(entitySegments),
+    entityPascal: toPascal(entitySegments),
+    tableName: segments.join('_'),
+    entityConstant: entitySegments.join('_').toUpperCase(),
+  };
+}
+
+function toCamel(segments: string[]): string {
+  return segments
+    .map((segment, index) => (index === 0 ? segment : capitalize(segment)))
+    .join('');
+}
+
+function toPascal(segments: string[]): string {
+  return segments.map(capitalize).join('');
+}
+
+function capitalize(segment: string): string {
+  return segment.charAt(0).toUpperCase() + segment.slice(1);
+}
+
+/**
+ * English plural-to-singular for the shapes a table name actually takes.
+ * A module whose singular this gets wrong is a rename away from correct —
+ * the entity name is cosmetic to every gate, unlike the module name, which
+ * core.yaml's scope globs key on.
+ */
+function singular(word: string): string {
+  if (word.endsWith('ies') && word.length > 3) {
+    return `${word.slice(0, -3)}y`;
+  }
+  if (/(s|x|z|ch|sh)es$/.test(word)) {
+    return word.slice(0, -2);
+  }
+  if (word.endsWith('s') && !word.endsWith('ss')) {
+    return word.slice(0, -1);
+  }
+  return word;
+}

package/workspace/tools/generators/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@hedgehog/generators",
+  "version": "0.0.1",
+  "private": true,
+  "generators": "./generators.json"
+}