@pattern-stack/codegen 0.17.2 → 0.19.0

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.19.0] — 2026-06-05
+
+**Providers catalog emission + planned providers** (ADR-038 follow-on;
+swe-brain consumer-test finding — the Connections surface hand-duplicated
+provider knowledge that `definitions/providers/*.yaml` already owns).
+
+### Added
+
+- **Frontend providers catalog (`generated/providers.ts`)** — emitted by the
+  frontend whole-set emitter when `definitions/providers/` exists (entity-only
+  consumers see no new file; the root barrel gains the export conditionally).
+  `PROVIDERS` (flat, slug-sorted) + `PROVIDER_CATALOG` (grouped by
+  `display.category` into the ordered `frontend.catalog.categories`). Providers
+  are gen-time knowledge — the catalog is emitted, not queried.
+- **`display:` block on the provider schema** (`category`, `blurb`, `hint`) —
+  presentation metadata consumed only by the catalog emission; backend
+  provider/adapter codegen ignores it.
+- **`status: active | planned` on the provider schema** (default `active`).
+  `planned` providers are roadmap stubs: catalog tile only — `auth`/`client`
+  optional, surface closed-set + import pre-flight cross-checks skipped (slug
+  uniqueness still enforced), and ALL backend emission (provider modules,
+  adapters, assemblies) filters them out. Flip to `active` when the
+  integration lands.
+- **`frontend.catalog.categories`** in `codegen.config.yaml` — ordered display
+  groups (`id`, `name`, `blurb`) the catalog renders.
+
+### Changed
+
+- `generateProviderModule` / `generateAdapterScaffold` now take
+  `ActiveProviderDefinition` (auth/client guaranteed); use the exported
+  `isActiveProvider` guard to narrow.
+
 ## [0.17.2] — 2026-06-04
 
 **Shutdown leak fix** (LISTEN-NOTIFY-2; swe-brain dogfood). With

package/README.md

@@ -138,6 +138,155 @@ 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)
+  providers.ts             providers catalog — only when definitions/providers/ exists
+```
+
+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).
+
+### Providers catalog (`providers.ts`)
+
+Providers are gen-time knowledge (`definitions/providers/<slug>.yaml`,
+RFC-0001) — the provider set changes only when code deploys — so the frontend
+catalog is **emitted, not queried**. When the project has provider definitions,
+the emitter renders `generated/providers.ts`:
+
+- `PROVIDERS` — every provider, flat (active + planned), slug-sorted:
+  `{ provider, name, planned, surfaces, blurb?, hint? }`. Join live rows on
+  `provider` (the canonical slug, e.g. `Connection.provider`).
+- `PROVIDER_CATALOG` — grouped into `frontend.catalog.categories` (config
+  order) via each provider's `display.category`. Uncategorized providers
+  appear only in `PROVIDERS`.
+
+Two provider-YAML additions feed it:
+
+```yaml
+# definitions/providers/google.yaml (active — full definition)
+slug: google
+display_name: Google Workspace
+display:
+  category: google-workspace     # joins frontend.catalog.categories[].id
+  hint: connect                  # optional sub-line on an unconnected tile
+surfaces: [calendar, mail, transcript]
+auth: { ... }                    # required for active providers
+client: { ... }
+
+# definitions/providers/github.yaml (planned — roadmap stub)
+slug: github
+display_name: GitHub
+status: planned                  # catalog tile only; NO backend emission,
+display:                         # no auth/client required, surface + import
+  category: source-control       # cross-checks skipped
+surfaces: [source_control]
+```
+
+```yaml
+# codegen.config.yaml — the ordered display groups
+frontend:
+  catalog:
+    categories:
+      - id: source-control
+        name: Source Control & Issues
+        blurb: Repositories, pull requests, issues, and project planning
+```
+
+When the integration for a `planned` provider lands, flip it to `status:
+active` (or drop the key) and add `auth`/`client` — the definitions tree is
+the integration roadmap.
+
 ## Integration Codegen (provider/adapter + assembly + read primitive)
 
 When an entity carries a `surface:` tag and `definitions/providers/*.yaml` exist,
@@ -261,9 +410,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 +430,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 +442,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/consumer-skills/codegen/SKILL.md

@@ -55,6 +55,38 @@ generation run the two barrels are rewritten and you wire them into
 | React to an event with a durable async job (the event-to-job bridge) | the `bridge` skill |
 | Pull/push data from an external system (`IChangeSource` / `IIntegrationSink`) | the `integration` skill |
 
+## Frontend generation (`generate.frontend: true`)
+
+When on, `entity new` (and `--all`) ends with a **whole-set frontend emitter**
+(ADR-038): the complete data layer is rendered into
+`locations.frontendGenerated` (default `apps/frontend/src/generated/`) from the
+full entity set — REST api client, TanStack DB collections (per-entity
+`sync: api | electric`), `createEntityHooks` wiring, field metadata, a
+plural-keyed `createStore`, `config.ts`, `query-client.ts`, root barrel. Every
+file is a complete write with a `@generated` banner; re-runs are byte-identical.
+
+Non-obvious bits:
+
+- **The dbEntities contract**: generated files import the plain `<Class>` type
+  AND a `<camel>Schema` Zod schema from `locations.dbEntities` per entity. If
+  the backend doesn't emit such a package (clean-lite-ps doesn't), the consumer
+  provides a shim barrel re-exporting each module's Output DTO.
+- **The consumer mounts two providers** in the app root, both from generated
+  code: `QueryClientProvider(queryClient)` ▸ `EntityStoreProvider(store)`
+  (`EntityStoreProvider` from `@pattern-stack/frontend-patterns`).
+- **Version pairing**: the emitted imports require
+  `@pattern-stack/frontend-patterns` + four TanStack packages — the exact
+  ranges are listed in the generated `index.ts` header comment.
+- **Path aliases are assumed**: default imports use `@/…` (and your
+  `locations.*.import` values) — wire tsconfig `paths` + the bundler alias.
+- **Providers catalog**: when `definitions/providers/` exists, the emitter also
+  renders `providers.ts` — `PROVIDERS` (flat) + `PROVIDER_CATALOG` (grouped by
+  each provider's `display.category` into `frontend.catalog.categories`).
+  Providers are gen-time knowledge: the catalog is emitted, never queried, and
+  never hand-duplicated in the frontend. `status: planned` provider YAMLs are
+  roadmap stubs — catalog tile only, no auth/client needed, skipped by all
+  backend emission.
+
 ## CLI quick reference
 
 ```bash

package/consumer-skills/entities/SKILL.md

@@ -48,6 +48,8 @@ module — plus an entry in the `GENERATED_MODULES` and schema barrels.
 entity:
   name: account            # singular snake_case
   pattern: Synced          # Base | Synced | Activity | Metadata | Knowledge (or app-defined)
+  # sync: api              # frontend collection mode (api | electric) — overrides
+  #                        # frontend.sync.mode; only meaningful with generate.frontend: true
 
 fields:
   name:

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-T6SCOJF4.js → chunk-7LKAMLV4.js}

@@ -1,15 +1,15 @@
 import {
   EnvEncryptionKey
 } from "./chunk-IP4OO26U.js";
-import {
-  AuthController
-} from "./chunk-SZVPIHWE.js";
 import {
   DrizzleOAuthStateStore
 } from "./chunk-N5OTOWTP.js";
 import {
   MemoryOAuthStateStore
 } from "./chunk-QLTJSCE6.js";
+import {
+  AuthController
+} from "./chunk-SZVPIHWE.js";
 import {
   AUTH_OPTIONS,
   ENCRYPTION_KEY,
@@ -89,4 +89,4 @@ AuthModule = __decorateClass([
 export {
   AuthModule
 };
-//# sourceMappingURL=chunk-T6SCOJF4.js.map
+//# sourceMappingURL=chunk-7LKAMLV4.js.map

package/dist/{chunk-IOQMMH6C.js → chunk-F7KN3U6U.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"
 });
@@ -1004,6 +1011,12 @@ var ClientSchema = z5.object({
   class: ImportRefSchema,
   base_url: z5.string().url("client.base_url must be an absolute URL")
 }).strict();
+var DisplaySchema = z5.object({
+  category: z5.string().optional(),
+  blurb: z5.string().optional(),
+  // Sub-line shown on an unconnected ("available") tile.
+  hint: z5.string().optional()
+}).strict();
 var ProviderDefinitionSchema = z5.object({
   // Provider id — the canonical string used as detection: keys, audit rows,
   // subscription rows. kebab/lower; unique across definitions/providers/
@@ -1013,19 +1026,49 @@ var ProviderDefinitionSchema = z5.object({
     "slug must be kebab-case lower (e.g. 'google', 'hubspot')"
   ),
   display_name: z5.string().optional(),
-  auth: AuthSchema,
-  client: ClientSchema,
+  // Lifecycle: 'active' providers drive backend provider/adapter emission
+  // and require auth + client. 'planned' providers are roadmap stubs — they
+  // appear in the frontend catalog (as unconnectable tiles) but are skipped
+  // by all backend emission and by the surface/import cross-checks, so a
+  // stub can exist before its surface has entities or its strategy/client
+  // are written.
+  status: z5.enum(["active", "planned"]).default("active"),
+  // Frontend catalog presentation (see DisplaySchema).
+  display: DisplaySchema.optional(),
+  // Required iff status === 'active'; see superRefine below.
+  auth: AuthSchema.optional(),
+  client: ClientSchema.optional(),
   // Surfaces this provider serves (ADR-0006: surfaces span contexts — one
   // Google OAuth feeds calendar+mail+transcript). Each must reference a real
   // `surface:` declared on some entity; that cross-check is in
-  // validate-providers.ts. Non-empty enforced here.
+  // validate-providers.ts (skipped for 'planned'). Non-empty enforced here.
   surfaces: z5.array(z5.string()).min(1, "surfaces must list at least one surface"),
   // Optional auth lifecycle hints consumed by provider-module emission (D2).
   // `refresh_behavior` is left as a free string in D1 — its domain firms up
   // when D2 consumes it; carrying it now keeps the YAML lossless.
   token_lifetime: z5.number().int().positive().optional(),
   refresh_behavior: z5.string().optional()
-}).strict();
+}).strict().superRefine((def, ctx) => {
+  if (def.status === "active") {
+    if (!def.auth) {
+      ctx.addIssue({
+        code: z5.ZodIssueCode.custom,
+        message: "auth is required when status is 'active'",
+        path: ["auth"]
+      });
+    }
+    if (!def.client) {
+      ctx.addIssue({
+        code: z5.ZodIssueCode.custom,
+        message: "client is required when status is 'active'",
+        path: ["client"]
+      });
+    }
+  }
+});
+function isActiveProvider(def) {
+  return def.status !== "planned";
+}
 
 // src/utils/yaml-loader.ts
 function loadEntityFromYaml(filePath) {
@@ -1320,6 +1363,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 +1708,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 +1808,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,
@@ -1769,6 +1879,7 @@ function validateProviders(providers, opts) {
   }
   for (const { definition, filePath } of providers) {
     const { slug } = definition;
+    if (definition.status === "planned") continue;
     for (const surface of definition.surfaces) {
       if (!knownSurfaces.has(surface)) {
         const known = [...knownSurfaces].sort().join(", ") || "(none declared)";
@@ -1790,6 +1901,7 @@ function validateProviders(providers, opts) {
         sourceRoot: opts.sourceRoot,
         aliases: opts.aliases
       };
+      if (!isActiveProvider(definition)) continue;
       const refs = [
         { field: "auth.strategy", ref: definition.auth.strategy },
         { field: "client.class", ref: definition.client.class }
@@ -3990,6 +4102,7 @@ export {
   validateJunctionDefinition,
   safeValidateJunctionDefinition,
   parseImportRef,
+  isActiveProvider,
   loadEntityFromYaml,
   loadEntitiesFromYaml,
   loadRelationshipFromYaml,
@@ -3999,6 +4112,7 @@ export {
   detectYamlType,
   loadEntities,
   loadRelationships,
+  loadEntityRegistry,
   collectEntitySurfaces,
   validateProviders,
   buildDomainGraph,
@@ -4049,4 +4163,4 @@ export {
   analyzeDomain,
   validateEntities
 };
-//# sourceMappingURL=chunk-IOQMMH6C.js.map
+//# sourceMappingURL=chunk-F7KN3U6U.js.map