@pattern-stack/codegen 0.17.2 → 0.18.0

package/README.md

@@ -138,6 +138,104 @@ modules/{plural}/
   use-cases/                       FindById, List, declarative queries
 ```
 
+**Frontend** (`generate.frontend: true`) — see [Frontend generation](#frontend-generation) below.
+
+## Frontend generation
+
+Gated entirely by `generate.frontend` (default `false`; the scanner sets it
+`true` when it finds an `apps/frontend/` directory). When on, the `entity new`
+post-step (and therefore `gen-all`) renders the **complete frontend tree from the
+full entity set in one pass** — a TypeScript emitter (`src/emitters/frontend/`),
+not hygen templates. Re-running is idempotent: every file is a complete-file
+write with a `@generated` banner, no inject/anchor machinery, no overwrite
+prompts (ADR-038).
+
+Output lands under `locations.frontendGenerated` (default
+`apps/frontend/src/generated/`):
+
+```
+generated/
+  index.ts                 whole-set barrel (+ version-pairing comment)
+  config.ts                per-entity sync modes + runtime overrides
+  query-client.ts          shared TanStack QueryClient
+  api/<entity>.ts          REST client → the generated NestJS controllers
+  collections/<entity>.ts  createCollection, branched on the entity's sync mode
+  entities/<entity>.ts     createEntityHooks({ collection, api }) wiring
+  store/index.ts           createStore over the full set (+ resolvers, lookups)
+  fields/<entity>.ts       field metadata (FieldMeta, <entity>Fields)
+```
+
+Entity types and Zod schemas are **imported** from `locations.dbEntities`
+(default `@repo/db/entities`), not re-emitted. The emitter imports the plain
+class name — `import type { <Class> } from '<dbEntities>/<name>'` — so
+`dbEntities` is the contract: it MUST export the entity type under its plain
+`<Class>` name (e.g. `Contact`, not `ContactEntity`). If your db package only
+exports `<Class>Entity`, that is the one knob to change in the emitter.
+
+The hook/mutation/store/provider logic is consumed from
+`@pattern-stack/frontend-patterns` (`createEntityHooks`, `createStore`) — the
+generated files are thin wiring. **The consumer's frontend installs that package
+plus the paired TanStack libraries.** `project init` adds the version-pairing
+deps to `apps/frontend/package.json` when `generate.frontend: true` (idempotent
+merge — only missing keys added, existing version ranges preserved); when no
+frontend package.json exists it prints the list to install. `@pattern-stack/codegen`
+itself gains no runtime dependency.
+
+| Package | Range |
+|---|---|
+| `@pattern-stack/frontend-patterns` | `^0.2.0-alpha.18` |
+| `@tanstack/react-db` | `^0.1.55` |
+| `@tanstack/electric-db-collection` | `^0.2.11` |
+| `@tanstack/query-db-collection` | `^1.0.6` |
+| `@tanstack/react-query` | `^5.0.0` |
+
+### `frontend:` config block
+
+All knobs are inert unless `generate.frontend: true`. Defaults shown; the block
+is optional (fully defaulted when absent):
+
+```yaml
+frontend:
+  auth:
+    function: getAuthorizationHeader   # auth-header fn; null DISABLES the header
+  parsers:                             # Electric column-type → parser fn source
+    timestamptz: '(date: string) => new Date(date)'
+  sync:
+    mode: electric          # global default sync mode (api | electric)
+    shapeUrl: /v1/shape      # Electric shape base path
+    useTableParam: true      # emit `params: { table }` shape-URL form
+    columnMapper: snakeCamelMapper   # Electric column mapper fn; null to omit
+    columnMapperNeedsCall: true      # call the mapper (fn()) vs reference (fn)
+    apiBaseUrlImport: null   # when set, import API_BASE_URL from it as baseURL
+    apiUrl: /api             # REST base path when no apiBaseUrlImport
+```
+
+`null`-disables convention: an **absent** `auth.function` defaults to
+`getAuthorizationHeader`; an **explicit `null`** disables it entirely (no header
+lines emitted). Likewise `sync.columnMapper: null` omits the Electric mapper.
+
+### Per-entity sync mode (`entity.sync`)
+
+Each entity may override the global `frontend.sync.mode` inside its `entity:`
+block (sibling to `surface:`/`context:`):
+
+```yaml
+entity:
+  name: contact
+  plural: contacts
+  table: contacts
+  sync: api        # api | electric — overrides frontend.sync.mode for this entity
+```
+
+`api` wires `queryCollectionOptions` (REST via TanStack Query); `electric` wires
+`electricCollectionOptions` (real-time shape sync). Absent → the global default.
+`offline` (Electric + Dexie) is deferred — the schema rejects it.
+
+Cross-entity FK names (file, plural, class, collection var) are resolved against
+the **target entity's own YAML** via the registry — never re-pluralized from a
+string at emit time (so an explicit `plural:` like `person`→`persons` is honored
+by every consumer).
+
 ## Integration Codegen (provider/adapter + assembly + read primitive)
 
 When an entity carries a `surface:` tag and `definitions/providers/*.yaml` exist,
@@ -261,9 +359,14 @@ naming:
   terminology:
     command: use-case
     query: use-case
+
+# frontend:                      # inert unless generate.frontend: true
+#   ...                          # see "Frontend generation" above for the full block
 ```
 
-Auto-detect your project's conventions with `codegen project scan`.
+The `frontend:` block (auth, parsers, sync) is documented under
+[Frontend generation](#frontend-generation). Auto-detect your project's
+conventions with `codegen project scan`.
 
 ## Using in Your Project
 
@@ -276,6 +379,7 @@ See [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md) for a walkthrough of enti
 ```
 src/                        Generator source code
   cli/                      Clipanion CLI (noun-verb architecture)
+  emitters/                 TypeScript emitters (integration, frontend — ADR-038)
   analyzer/                 Graph building, consistency checking
   parser/                   YAML loading, cross-reference resolution
   scanner/                  Project pattern detection
@@ -287,7 +391,7 @@ src/                        Generator source code
 runtime/                    Code shipped into consumer projects
   base-classes/             BaseRepository, BaseService, pattern bases
   subsystems/               Events, Jobs, Cache, Storage
-templates/                  Hygen EJS templates
+templates/                  Hygen EJS templates (backend pipelines)
 test/                       Baseline snapshots, scaffold integration, smoke test
 docs/                       ADRs, consumer setup, getting started
 ```

package/dist/{chunk-65MO75WM.js → chunk-2VGVSL2D.js}

@@ -1,22 +1,22 @@
 import {
   BRIDGE_DELIVERY_JOB_TYPE
-} from "./chunk-R6F6KFIL.js";
+} from "./chunk-TBGTMALE.js";
 import {
   bridgeDelivery
 } from "./chunk-2TVVBC53.js";
 import {
-  JOBS_WAKE_CHANNEL,
-  pgNotify
-} from "./chunk-Q6LRJ4VI.js";
+  jobRuns
+} from "./chunk-OKXZ63IA.js";
 import {
   JOBS_LISTEN_NOTIFY
 } from "./chunk-ZPL74UQN.js";
+import {
+  JOBS_WAKE_CHANNEL,
+  pgNotify
+} from "./chunk-Q6LRJ4VI.js";
 import {
   BRIDGE_REGISTRY
 } from "./chunk-4LH67P4U.js";
-import {
-  jobRuns
-} from "./chunk-OKXZ63IA.js";
 import {
   __decorateClass,
   __decorateParam
@@ -151,4 +151,4 @@ BridgeOutboxDrainHook = __decorateClass([
 export {
   BridgeOutboxDrainHook
 };
-//# sourceMappingURL=chunk-65MO75WM.js.map
+//# sourceMappingURL=chunk-2VGVSL2D.js.map

package/dist/{chunk-VNBC3VXM.js → chunk-3A34R6CI.js}

@@ -1,6 +1,3 @@
-import {
-  MissingTenantIdError
-} from "./chunk-T4BIIU5E.js";
 import {
   clampLimit,
   decodeKeysetCursor,
@@ -8,12 +5,15 @@ import {
   toJobRunSummary
 } from "./chunk-L3LZWWSX.js";
 import {
-  JOBS_MULTI_TENANT,
-  JOB_ORCHESTRATOR
-} from "./chunk-ZPL74UQN.js";
+  MissingTenantIdError
+} from "./chunk-T4BIIU5E.js";
 import {
   jobRuns
 } from "./chunk-OKXZ63IA.js";
+import {
+  JOBS_MULTI_TENANT,
+  JOB_ORCHESTRATOR
+} from "./chunk-ZPL74UQN.js";
 import {
   DRIZZLE
 } from "./chunk-U64T4YZE.js";
@@ -198,4 +198,4 @@ DrizzleJobRunService = __decorateClass([
 export {
   DrizzleJobRunService
 };
-//# sourceMappingURL=chunk-VNBC3VXM.js.map
+//# sourceMappingURL=chunk-3A34R6CI.js.map

package/dist/{chunk-I6UXRJ3Q.js → chunk-43SBT72G.js}

@@ -1,9 +1,9 @@
-import {
-  WebhookChangeSource
-} from "./chunk-TIZXQU26.js";
 import {
   PollChangeSource
 } from "./chunk-4MF3HKJA.js";
+import {
+  WebhookChangeSource
+} from "./chunk-TIZXQU26.js";
 
 // runtime/subsystems/integration/build-change-source.ts
 function buildChangeSource(cfg, fetch, middlewares = []) {
@@ -26,4 +26,4 @@ function buildChangeSource(cfg, fetch, middlewares = []) {
 export {
   buildChangeSource
 };
-//# sourceMappingURL=chunk-I6UXRJ3Q.js.map
+//# sourceMappingURL=chunk-43SBT72G.js.map

package/dist/{chunk-7OVCARTQ.js → chunk-5RT7JGKT.js}

@@ -4,14 +4,14 @@ import {
 import {
   JOB_ORCHESTRATOR
 } from "./chunk-ZPL74UQN.js";
-import {
-  EVENT_BUS
-} from "./chunk-H5NH7KPE.js";
 import {
   BRIDGE_DELIVERY_REPO,
   BRIDGE_MULTI_TENANT,
   BRIDGE_REGISTRY
 } from "./chunk-4LH67P4U.js";
+import {
+  EVENT_BUS
+} from "./chunk-H5NH7KPE.js";
 import {
   DRIZZLE
 } from "./chunk-U64T4YZE.js";
@@ -106,4 +106,4 @@ EventFlowService = __decorateClass([
 export {
   EventFlowService
 };
-//# sourceMappingURL=chunk-7OVCARTQ.js.map
+//# sourceMappingURL=chunk-5RT7JGKT.js.map

package/dist/{chunk-E6PLM6QG.js → chunk-7MMS36AN.js}

@@ -5,23 +5,23 @@ import {
   JobTypeNotFoundError,
   MissingTenantIdError
 } from "./chunk-T4BIIU5E.js";
-import {
-  JOBS_WAKE_CHANNEL,
-  pgNotify
-} from "./chunk-Q6LRJ4VI.js";
 import {
   keySelectorToTemplate,
   resolveJobKey
 } from "./chunk-7P5ODGLA.js";
-import {
-  JOBS_LISTEN_NOTIFY,
-  JOBS_MULTI_TENANT
-} from "./chunk-ZPL74UQN.js";
 import {
   jobRuns,
   jobSteps,
   jobs
 } from "./chunk-OKXZ63IA.js";
+import {
+  JOBS_LISTEN_NOTIFY,
+  JOBS_MULTI_TENANT
+} from "./chunk-ZPL74UQN.js";
+import {
+  JOBS_WAKE_CHANNEL,
+  pgNotify
+} from "./chunk-Q6LRJ4VI.js";
 import {
   DRIZZLE
 } from "./chunk-U64T4YZE.js";
@@ -393,4 +393,4 @@ export {
   evaluateKeyTemplate,
   DrizzleJobOrchestrator
 };
-//# sourceMappingURL=chunk-E6PLM6QG.js.map
+//# sourceMappingURL=chunk-7MMS36AN.js.map

package/dist/{chunk-4MVGAMUA.js → chunk-BK5ICA2F.js}

@@ -1,12 +1,12 @@
+import {
+  STORAGE
+} from "./chunk-NYBCQZC7.js";
 import {
   LocalStorageBackend
 } from "./chunk-JWNHNUYL.js";
 import {
   MemoryStorageBackend
 } from "./chunk-3SZFUTXE.js";
-import {
-  STORAGE
-} from "./chunk-NYBCQZC7.js";
 import {
   __decorateClass
 } from "./chunk-2E224ZSN.js";
@@ -37,4 +37,4 @@ StorageModule = __decorateClass([
 export {
   StorageModule
 };
-//# sourceMappingURL=chunk-4MVGAMUA.js.map
+//# sourceMappingURL=chunk-BK5ICA2F.js.map

package/dist/{chunk-VDL5CJ5C.js → chunk-C5E7H553.js}

@@ -1,18 +1,18 @@
-import {
-  JOBS_WAKE_CHANNEL,
-  PgNotifyListener
-} from "./chunk-Q6LRJ4VI.js";
 import {
   JOB_HANDLER_REGISTRY
 } from "./chunk-7P5ODGLA.js";
+import {
+  jobRuns
+} from "./chunk-OKXZ63IA.js";
 import {
   JOB_ORCHESTRATOR,
   JOB_RUN_SERVICE,
   JOB_STEP_SERVICE
 } from "./chunk-ZPL74UQN.js";
 import {
-  jobRuns
-} from "./chunk-OKXZ63IA.js";
+  JOBS_WAKE_CHANNEL,
+  PgNotifyListener
+} from "./chunk-Q6LRJ4VI.js";
 import {
   tokenKey
 } from "./chunk-GYGNEQSC.js";
@@ -528,4 +528,4 @@ export {
   buildStaleSweepQuery,
   JobWorker
 };
-//# sourceMappingURL=chunk-VDL5CJ5C.js.map
+//# sourceMappingURL=chunk-C5E7H553.js.map

package/dist/{chunk-IOQMMH6C.js → chunk-CFFTPWHM.js}

@@ -349,7 +349,14 @@ var EntityConfigSchema = z.object({
   context: z.string().regex(
     /^[a-z][a-z0-9_]*$/,
     "context must be lowercase snake_case (e.g. 'integration')"
-  ).optional()
+  ).optional(),
+  // ADR-038: per-entity frontend sync mode. Overrides global frontend.sync.mode.
+  //   'api'      → queryCollectionOptions (REST via TanStack Query)
+  //   'electric' → electricCollectionOptions (real-time shape sync)
+  // 'offline' (Electric + Dexie) is deferred — see
+  // docs/specs/2026-06-04-frontend-pipeline-rebuild.md OQ-6.
+  // Sibling to `surface:`/`context:`; lives inside the `entity:` block.
+  sync: z.enum(["api", "electric"]).optional()
 }).strict().refine((d) => !(d.pattern && d.patterns), {
   message: "'pattern' and 'patterns' are mutually exclusive"
 });
@@ -1320,6 +1327,7 @@ function transformToEntity(result) {
     patterns: definition.entity.patterns,
     patternConfig: definition.entity.config,
     scopeable: definition.entity.scopeable ?? false,
+    expose: definition.entity.expose ?? ["repository", "rest", "trpc"],
     folderStructure: definition.entity.folder_structure ?? "nested",
     fields: /* @__PURE__ */ new Map(),
     relationships: /* @__PURE__ */ new Map(),
@@ -1664,9 +1672,75 @@ function resolveRelationshipReferences(relationshipDefs, entities) {
   return issues;
 }
 
+// src/parser/entity-registry.ts
+import { resolve as resolve3 } from "path";
+var camelCase = (s) => s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+var pascalCase = (s) => {
+  const camel = camelCase(s);
+  return camel.charAt(0).toUpperCase() + camel.slice(1);
+};
+function loadErrorToIssue2(error) {
+  const issues = [
+    {
+      severity: "error",
+      type: "parse_error",
+      message: error.error,
+      path: error.filePath
+    }
+  ];
+  if (error.details) {
+    for (const detail of error.details) {
+      issues.push({
+        severity: "error",
+        type: "schema_error",
+        message: detail,
+        path: error.filePath
+      });
+    }
+  }
+  return issues;
+}
+function loadEntityRegistry(entitiesDir) {
+  const registry = /* @__PURE__ */ new Map();
+  const issues = [];
+  const resolvedDir = resolve3(entitiesDir);
+  let files;
+  try {
+    files = findYamlFiles(resolvedDir);
+  } catch {
+    issues.push({
+      severity: "error",
+      type: "parse_error",
+      message: `Failed to read directory: ${resolvedDir}`,
+      path: resolvedDir
+    });
+    return { registry, issues };
+  }
+  for (const filePath of files) {
+    const result = loadEntityFromYaml(filePath);
+    if (!result.success) {
+      issues.push(...loadErrorToIssue2(result));
+      continue;
+    }
+    const { entity } = result.definition;
+    registry.set(entity.name, {
+      name: entity.name,
+      plural: entity.plural,
+      // authoritative — never derived
+      table: entity.table,
+      className: pascalCase(entity.name),
+      classNamePlural: pascalCase(entity.plural),
+      camelName: camelCase(entity.name),
+      pluralCamelName: camelCase(entity.plural),
+      sync: entity.sync ?? null
+    });
+  }
+  return { registry, issues };
+}
+
 // src/parser/validate-providers.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "fs";
-import { isAbsolute, join as join2, resolve as resolve3 } from "path";
+import { isAbsolute, join as join2, resolve as resolve4 } from "path";
 import ts from "typescript";
 function collectEntitySurfaces(entities) {
   const surfaces = /* @__PURE__ */ new Set();
@@ -1698,7 +1772,7 @@ function resolveModuleFile(importPath, opts) {
     }
   }
   if (base === null) {
-    base = isAbsolute(importPath) ? importPath : resolve3(opts.sourceRoot, importPath);
+    base = isAbsolute(importPath) ? importPath : resolve4(opts.sourceRoot, importPath);
   }
   const candidates = [
     base,
@@ -3999,6 +4073,7 @@ export {
   detectYamlType,
   loadEntities,
   loadRelationships,
+  loadEntityRegistry,
   collectEntitySurfaces,
   validateProviders,
   buildDomainGraph,
@@ -4049,4 +4124,4 @@ export {
   analyzeDomain,
   validateEntities
 };
-//# sourceMappingURL=chunk-IOQMMH6C.js.map
+//# sourceMappingURL=chunk-CFFTPWHM.js.map