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

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

@@ -0,0 +1,390 @@
+import { controllerGenerator, moduleGenerator } from '@nx/nest';
+import { formatFiles, Tree, updateJson } from '@nx/devkit';
+import { Field, isDateField, parseFields } from '../fields';
+import { moduleNames, ModuleNames } from '../naming';
+
+interface ControllerGeneratorOptions {
+  module: string;
+  fields: string;
+  toggleField?: string;
+}
+
+const API_ROOT = 'apps/api';
+
+export default async function controllerGenerator_(
+  tree: Tree,
+  options: ControllerGeneratorOptions,
+) {
+  const names = moduleNames(options.module);
+  const fields = parseFields(options.fields);
+  const dir = `${API_ROOT}/src/app/${names.module}`;
+  const stem = `${dir}/${names.module}`;
+
+  // The Nest generators own the module/controller shell so it cannot drift
+  // from a hand-copied sibling. `skipImport` is required: registration
+  // happens through the generated feature-modules.ts barrel, which globs
+  // apps/api/src/app/*/*.module.ts — the file this generator writes is
+  // picked up automatically by the generate-feature-modules Nx target that
+  // build, typecheck, and test all depend on. Nothing here edits
+  // app.module.ts.
+  await moduleGenerator(tree, {
+    path: stem,
+    skipImport: true,
+    skipFormat: true,
+  });
+  await controllerGenerator(tree, {
+    path: stem,
+    skipImport: true,
+    unitTestRunner: 'none',
+    skipFormat: true,
+  });
+
+  // @nx/nest:controller emits @Controller('<name>') — a base path derived
+  // from the file name. The ts-rest contract already encodes every route's
+  // full path, so leaving it would prefix each route twice.
+  stripControllerBasePath(tree, `${stem}.controller.ts`);
+
+  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, options.toggleField),
+  );
+
+  addApiDependencies(tree, names);
+
+  await formatFiles(tree);
+}
+
+/**
+ * Rewrites the generator's own decorator in place, so the strip is proved
+ * against what it actually emitted rather than assumed from its templates.
+ */
+function stripControllerBasePath(tree: Tree, path: string) {
+  const source = tree.read(path, 'utf-8');
+  if (!source) return;
+  tree.write(path, source.replace(/@Controller\((['"]).*?\1\)/, '@Controller()'));
+}
+
+function controllerFile(
+  names: ModuleNames,
+  fields: Field[],
+  toggleField?: string,
+): string {
+  const { entityPascal, entityCamel, camel, module } = names;
+  const dateFields = fields.filter(isDateField);
+  const wireShape = dateFields.length
+    ? `{ ${dateFields
+        .map(
+          (field) =>
+            `${field.name}${field.nullable ? '?' : ''}: Date | string${field.nullable ? ' | null' : ''}`,
+        )
+        .join('; ')} }`
+    : 'object';
+
+  return `import { Controller, Inject } from '@nestjs/common';
+import { TsRestHandler, tsRestHandler } from '@ts-rest/nest';
+import { ${camel}Contract } from 'contracts';
+import { ${entityPascal}Service } from '${module}-service';
+
+// No base path: the ts-rest contract carries each route's full path, and
+// apps/api/src/main.ts adds the one /api prefix the whole app shares.
+@Controller()
+export class ${names.pascal}Controller {
+  constructor(
+    @Inject(${entityPascal}Service) private readonly ${entityCamel}s: ${entityPascal}Service,
+  ) {}
+
+  @TsRestHandler(${camel}Contract)
+  async handler() {
+    return tsRestHandler(${camel}Contract, {
+      list: async () => ({
+        status: 200 as const,
+        body: await this.${entityCamel}s.list(),
+      }),
+
+      get: async ({ params }) => {
+        try {
+          return {
+            status: 200 as const,
+            body: await this.${entityCamel}s.getById(params.id),
+          };
+        } catch (error) {
+          return notFoundOr(error, params.id);
+        }
+      },
+
+      create: async ({ body }) => ({
+        status: 201 as const,
+        body: await this.${entityCamel}s.create(fromWire(body)),
+      }),
+
+      update: async ({ params, body }) => {
+        try {
+          return {
+            status: 200 as const,
+            body: await this.${entityCamel}s.update(params.id, fromWire(body)),
+          };
+        } catch (error) {
+          return notFoundOr(error, params.id);
+        }
+      },
+
+      remove: async ({ params }) => {
+        try {
+          await this.${entityCamel}s.remove(params.id);
+          return { status: 204 as const, body: undefined };
+        } 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);
+        }
+      },`
+          : ''
+      }
+    });
+  }
+}
+
+/**
+ * The one place a domain error becomes a status code — services throw
+ * ${entityPascal}NotFoundError knowing nothing about HTTP. Matching on
+ * \`name\` rather than \`instanceof\` survives the error class arriving
+ * through a separately bundled copy of ${module}-service.
+ */
+function notFoundOr(error: unknown, id: string) {
+  if (error instanceof Error && error.name === '${entityPascal}NotFoundError') {
+    return {
+      status: 404 as const,
+      body: {
+        error: '${entityPascal}NotFound' as const,
+        message: \`No ${entityCamel} exists with id \${id}.\`,
+      },
+    };
+  }
+  throw error;
+}
+
+/**
+ * The seam the contract's date-mode timestamp union creates: the same
+ * field is a real Date server-side and an ISO string over JSON, so the
+ * contract accepts both and this boundary picks one — the Date the
+ * repository's column type actually stores. Past here nothing re-parses.
+ */
+function fromWire<T extends ${wireShape}>(body: T) {
+  return {
+    ...body,${dateFields
+      .map(
+        (field) =>
+          `\n    ${field.name}: toDate(body.${field.name}),`,
+      )
+      .join('')}
+  };
+}
+
+${
+  dateFields.length
+    ? `function toDate(value: Date | string | null | undefined) {
+  return typeof value === 'string' ? new Date(value) : value;
+}
+`
+    : ''
+}`;
+}
+
+function moduleFile(names: ModuleNames): string {
+  const { entityPascal, entityConstant, pascal, module } = names;
+
+  return `import { Module } from '@nestjs/common';
+import { getDb } from 'db';
+import {
+  ${entityConstant}_REPOSITORY,
+  Drizzle${entityPascal}Repository,
+} from '${module}-repository';
+import { ${entityPascal}Service } from '${module}-service';
+import { ${pascal}Controller } from './${names.module}.controller';
+
+// The composition root for this module, and the only file in apps/api
+// allowed to name a *.adapter (eslint-base.js exempts *.module.ts from the
+// port-discipline rule precisely for this binding).
+//
+// Registration is automatic: tools/generate-feature-modules.cjs globs
+// every module directory's own *.module.ts into feature-modules.ts, which
+// app.module.ts spreads — so this file is never referenced by hand.
+@Module({
+  controllers: [${pascal}Controller],
+  providers: [
+    {
+      provide: ${entityConstant}_REPOSITORY,
+      // getDb is passed unevaluated: the DI container builds every provider
+      // eagerly, and calling it here would open a database connection just
+      // to compile the module — including inside a test.
+      useFactory: () => new Drizzle${entityPascal}Repository(getDb),
+    },
+    {
+      provide: ${entityPascal}Service,
+      inject: [${entityConstant}_REPOSITORY],
+      useFactory: (repository: Drizzle${entityPascal}Repository) =>
+        new ${entityPascal}Service(repository),
+    },
+  ],
+})
+export class ${pascal}Module {}
+`;
+}
+
+function controllerSpecFile(names: ModuleNames, toggleField?: string): string {
+  const { entityPascal, pascal, module } = names;
+
+  return `import { Test } from '@nestjs/testing';
+import { describe, expect, it, vi } from 'vitest';
+import { ${entityPascal}Service } from '${module}-service';
+import { ${pascal}Controller } from './${names.module}.controller';
+
+async function controllerWith(service: Partial<${entityPascal}Service>) {
+  const moduleRef = await Test.createTestingModule({
+    controllers: [${pascal}Controller],
+    providers: [{ provide: ${entityPascal}Service, useValue: service }],
+  }).compile();
+
+  return moduleRef.get(${pascal}Controller);
+}
+
+describe('${pascal}Controller', () => {
+  it('serves the contract without a base path of its own', () => {
+    const path = Reflect.getMetadata('path', ${pascal}Controller);
+
+    expect(path).toBe('/');
+  });
+
+  it('answers list with 200 and the rows the service returned', async () => {
+    const rows = [{ id: 'one' }];
+    const controller = await controllerWith({
+      list: vi.fn(async () => rows as never),
+    });
+
+    const handler = await controller.handler();
+    const response = await handler.list({} as never);
+
+    expect(response).toMatchObject({ status: 200, body: rows });
+  });
+
+  it('maps a not-found domain error to 404 rather than letting it escape', async () => {
+    const notFound = Object.assign(new Error('absent'), {
+      name: '${entityPascal}NotFoundError',
+    });
+    const controller = await controllerWith({
+      getById: vi.fn(async () => {
+        throw notFound;
+      }),
+    });
+
+    const handler = await controller.handler();
+    const response = await handler.get({
+      params: { id: 'missing' },
+    } as never);
+
+    expect(response).toMatchObject({ status: 404 });
+  });
+
+  it('lets an error it has no mapping for propagate', async () => {
+    const boom = new Error('database is on fire');
+    const controller = await controllerWith({
+      getById: vi.fn(async () => {
+        throw boom;
+      }),
+    });
+
+    const handler = await controller.handler();
+
+    await expect(
+      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 });
+  });
+`
+    : ''
+}});
+`;
+}
+
+/**
+ * apps/api reaches the module's service and repository libs, plus the
+ * contract package, by construction — declared here so the first module
+ * through this layer does not leave them unlinked for a later layer to
+ * trip over.
+ */
+function addApiDependencies(tree: Tree, names: ModuleNames) {
+  updateJson(tree, `${API_ROOT}/package.json`, (json) => {
+    json.dependencies = {
+      ...json.dependencies,
+      contracts: 'workspace:*',
+      [`${names.module}-repository`]: 'workspace:*',
+      [`${names.module}-service`]: 'workspace:*',
+    };
+    return json;
+  });
+
+  updateJson(tree, `${API_ROOT}/tsconfig.app.json`, (json) => {
+    const references: { path: string }[] = json.references ?? [];
+    for (const path of [
+      '../../packages/contracts/tsconfig.lib.json',
+      `../../libs/${names.module}/repository/tsconfig.lib.json`,
+      `../../libs/${names.module}/service/tsconfig.lib.json`,
+    ]) {
+      if (!references.some((entry) => entry.path === path)) {
+        references.push({ path });
+      }
+    }
+    json.references = references;
+    return json;
+  });
+}

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

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "HedgehogControllerLayer",
+  "title": "NestJS module and ts-rest controller 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"]
+}

package/workspace/tools/generators/fields.ts

@@ -0,0 +1,160 @@
+/**
+ * The field DSL every layer generator shares, plus the one mapping from a
+ * field type to its Drizzle column, its TypeScript type, and its Zod
+ * schema. Owned here so the seven generators cannot drift from each other
+ * on what `dueDate:timestamp?` means.
+ *
+ * Wire format (the `--fields` option): a comma-separated list of
+ * `name:type` pairs, with a trailing `?` on the type marking the column
+ * nullable — `title:string,done:boolean,dueDate:timestamp?`.
+ *
+ * A `string` takes an optional length in parentheses —
+ * `title:string(500)`, or `title:string(500)?` when it is also nullable.
+ * The value threads to both the Drizzle `varchar` and the Zod `.max()`,
+ * so the two bounds are the same number by construction: a Zod bound that
+ * outran its column would let an over-long value past validation and fail
+ * at the driver as a 500 instead of a 400.
+ */
+
+export type FieldType =
+  | 'string'
+  | 'text'
+  | 'boolean'
+  | 'integer'
+  | 'timestamp';
+
+export interface Field {
+  name: string;
+  type: FieldType;
+  nullable: boolean;
+  /** Max characters for a `string`; undefined on every other type. */
+  length?: number;
+}
+
+/** The `varchar` bound a `string` gets when the field list names none. */
+export const DEFAULT_STRING_LENGTH = 255;
+
+const FIELD_TYPES: readonly FieldType[] = [
+  'string',
+  'text',
+  'boolean',
+  'integer',
+  'timestamp',
+];
+
+export function parseFields(raw: string): Field[] {
+  const fields = raw
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0)
+    .map((entry) => {
+      const [name, rawType] = entry.split(':').map((part) => part.trim());
+      if (!name || !rawType) {
+        throw new Error(
+          `Field "${entry}" is not in name:type form (e.g. title:string, dueDate:timestamp?).`,
+        );
+      }
+      const nullable = rawType.endsWith('?');
+      const bare = nullable ? rawType.slice(0, -1) : rawType;
+
+      const sized = /^(\w+)\((\d+)\)$/.exec(bare);
+      const type = (sized ? sized[1] : bare) as FieldType;
+      const length = sized ? Number(sized[2]) : undefined;
+
+      if (!FIELD_TYPES.includes(type)) {
+        throw new Error(
+          `Field "${entry}" has unknown type "${type}". Known types: ${FIELD_TYPES.join(', ')}.`,
+        );
+      }
+      // A length on anything but `string` has no column to bind to, so it
+      // would be silently dropped — the exact failure mode the syntax
+      // exists to remove. `text` is unbounded by design: cap it and you
+      // want a `string`.
+      if (length !== undefined && type !== 'string') {
+        throw new Error(
+          `Field "${entry}" puts a length on "${type}", which has no length. Only string does (title:string(500)).`,
+        );
+      }
+      if (length !== undefined && length < 1) {
+        throw new Error(`Field "${entry}" has length ${length}; it must be at least 1.`);
+      }
+      if (RESERVED_FIELD_NAMES.includes(name)) {
+        throw new Error(
+          `Field "${name}" collides with a column every table already carries (${RESERVED_FIELD_NAMES.join(', ')}).`,
+        );
+      }
+      return { name, type, nullable, length };
+    });
+
+  if (fields.length === 0) {
+    throw new Error('At least one field is required.');
+  }
+  return fields;
+}
+
+// Columns the schema generator writes on every table — a field list may
+// not redeclare them.
+const RESERVED_FIELD_NAMES = ['id', 'createdAt', 'updatedAt'];
+
+/** snake_case, the database column name for a camelCase field. */
+export function columnName(name: string): string {
+  return name.replace(/[A-Z]/g, (char) => `_${char.toLowerCase()}`);
+}
+
+export function drizzleImports(fields: Field[]): string[] {
+  const imports = new Set<string>(['pgTable', 'uuid', 'timestamp']);
+  for (const field of fields) {
+    imports.add(DRIZZLE_IMPORT[field.type]);
+  }
+  return [...imports].sort();
+}
+
+const DRIZZLE_IMPORT: Record<FieldType, string> = {
+  string: 'varchar',
+  text: 'text',
+  boolean: 'boolean',
+  integer: 'integer',
+  timestamp: 'timestamp',
+};
+
+/** The character bound for a `string`, named or defaulted. */
+export function stringLength(field: Field): number {
+  return field.length ?? DEFAULT_STRING_LENGTH;
+}
+
+export function drizzleColumn(field: Field): string {
+  const column = `'${columnName(field.name)}'`;
+  const base: Record<FieldType, string> = {
+    string: `varchar(${column}, { length: ${stringLength(field)} })`,
+    text: `text(${column})`,
+    boolean: `boolean(${column})`,
+    integer: `integer(${column})`,
+    // `mode: 'date'` keeps the column a real `Date` on the server; the
+    // contract layer's timestamp union is what reconciles that with the
+    // ISO string the same field arrives as over JSON.
+    timestamp: `timestamp(${column}, { mode: 'date', withTimezone: true })`,
+  };
+  const modifiers = field.nullable
+    ? ''
+    : field.type === 'boolean'
+      ? '.notNull().default(false)'
+      : '.notNull()';
+  return `${field.name}: ${base[field.type]}${modifiers},`;
+}
+
+/** True when a field reflects through drizzle-zod as a `z.date()`. */
+export function isDateField(field: Field): boolean {
+  return field.type === 'timestamp';
+}
+
+/** The Zod schema for a field as it appears in a hand-written override. */
+export function zodSchema(field: Field): string {
+  const base: Record<FieldType, string> = {
+    string: `z.string().min(1).max(${stringLength(field)})`,
+    text: 'z.string()',
+    boolean: 'z.boolean()',
+    integer: 'z.number().int()',
+    timestamp: 'timestampSchema',
+  };
+  return field.nullable ? `${base[field.type]}.nullable()` : base[field.type];
+}

package/workspace/tools/generators/generators.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "name": "hedgehog",
+  "version": "0.0.1",
+  "generators": {
+    "schema": {
+      "factory": "./schema/generator",
+      "schema": "./schema/schema.json",
+      "description": "Drizzle table + drizzle-zod pair for one domain module (core.yaml's schema layer)."
+    },
+    "contract": {
+      "factory": "./contract/generator",
+      "schema": "./contract/schema.json",
+      "description": "ts-rest router + error schemas for one domain module (core.yaml's contract layer)."
+    },
+    "repository": {
+      "factory": "./repository/generator",
+      "schema": "./repository/schema.json",
+      "description": "Port interface, DI token, and Drizzle adapter lib for one domain module (core.yaml's repository layer)."
+    },
+    "service": {
+      "factory": "./service/generator",
+      "schema": "./service/schema.json",
+      "description": "Domain service lib with typed domain errors for one domain module (core.yaml's service layer)."
+    },
+    "controller": {
+      "factory": "./controller/generator",
+      "schema": "./controller/schema.json",
+      "description": "NestJS module + ts-rest controller for one domain module (core.yaml's controller layer)."
+    },
+    "hook": {
+      "factory": "./hook/generator",
+      "schema": "./hook/schema.json",
+      "description": "TanStack Query hook set for one domain module (core.yaml's hook layer)."
+    },
+    "screen": {
+      "factory": "./screen/generator",
+      "schema": "./screen/schema.json",
+      "description": "Screen skeleton wired to the hook layer for one domain module (core.yaml's screen layer)."
+    }
+  }
+}