@pattern-stack/codegen 0.18.0 → 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

@@ -163,6 +163,7 @@ generated/
   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`
@@ -236,6 +237,56 @@ 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,

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-X6BP6LI5.js → chunk-235ZMMJR.js}

@@ -1,9 +1,9 @@
 import {
   JobWorker
-} from "./chunk-C5E7H553.js";
+} from "./chunk-VDL5CJ5C.js";
 import {
   JobsDomainModule
-} from "./chunk-EWYI5GGJ.js";
+} from "./chunk-AZLUWG5S.js";
 import {
   BootValidationError,
   ReservedPoolViolationError
@@ -290,4 +290,4 @@ export {
   JobWorkerOrchestrator,
   JobWorkerModule
 };
-//# sourceMappingURL=chunk-X6BP6LI5.js.map
+//# sourceMappingURL=chunk-235ZMMJR.js.map

package/dist/{chunk-BK5ICA2F.js → chunk-4MVGAMUA.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-BK5ICA2F.js.map
+//# sourceMappingURL=chunk-4MVGAMUA.js.map

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

@@ -1,22 +1,22 @@
 import {
   BRIDGE_DELIVERY_JOB_TYPE
-} from "./chunk-TBGTMALE.js";
+} from "./chunk-R6F6KFIL.js";
 import {
   bridgeDelivery
 } from "./chunk-2TVVBC53.js";
-import {
-  jobRuns
-} from "./chunk-OKXZ63IA.js";
-import {
-  JOBS_LISTEN_NOTIFY
-} from "./chunk-ZPL74UQN.js";
 import {
   JOBS_WAKE_CHANNEL,
   pgNotify
 } from "./chunk-Q6LRJ4VI.js";
+import {
+  JOBS_LISTEN_NOTIFY
+} from "./chunk-ZPL74UQN.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-2VGVSL2D.js.map
+//# sourceMappingURL=chunk-65MO75WM.js.map

package/dist/{chunk-NXHL5YII.js → chunk-7LKAMLV4.js}

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

package/dist/{chunk-5RT7JGKT.js → chunk-7OVCARTQ.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-5RT7JGKT.js.map
+//# sourceMappingURL=chunk-7OVCARTQ.js.map

package/dist/{chunk-EWYI5GGJ.js → chunk-AZLUWG5S.js}

@@ -1,24 +1,24 @@
-import {
-  MemoryJobOrchestrator
-} from "./chunk-VQOAATIG.js";
-import {
-  MemoryJobStepService
-} from "./chunk-PNZSGAB2.js";
 import {
   DrizzleJobRunService
-} from "./chunk-3A34R6CI.js";
+} from "./chunk-VNBC3VXM.js";
 import {
   MemoryJobRunService
-} from "./chunk-IN3EWFB4.js";
-import {
-  MemoryJobStore
-} from "./chunk-SNQ3TOWP.js";
+} from "./chunk-BHZP6LOV.js";
 import {
   DrizzleJobStepService
 } from "./chunk-DV4RV2DC.js";
 import {
   DrizzleJobOrchestrator
-} from "./chunk-7MMS36AN.js";
+} from "./chunk-E6PLM6QG.js";
+import {
+  MemoryJobOrchestrator
+} from "./chunk-VQOAATIG.js";
+import {
+  MemoryJobStepService
+} from "./chunk-PNZSGAB2.js";
+import {
+  MemoryJobStore
+} from "./chunk-SNQ3TOWP.js";
 import {
   BULLMQ_CONNECTION,
   BULLMQ_RESOLVED_CONFIG,
@@ -114,4 +114,4 @@ JobsDomainModule = __decorateClass([
 export {
   JobsDomainModule
 };
-//# sourceMappingURL=chunk-EWYI5GGJ.js.map
+//# sourceMappingURL=chunk-AZLUWG5S.js.map

package/dist/{chunk-RKNW56RU.js → chunk-B34G6PHD.js}

@@ -1,19 +1,19 @@
+import {
+  clampEventLimit,
+  decodeEventCursor,
+  encodeEventCursor
+} from "./chunk-UQ5EHOH2.js";
 import {
   EVENTS_WAKE_CHANNEL,
   PgNotifyListener,
   pgNotify
 } from "./chunk-Q6LRJ4VI.js";
-import {
-  BRIDGE_OUTBOX_DRAIN_HOOK
-} from "./chunk-4LH67P4U.js";
 import {
   EVENTS_MODULE_OPTIONS
 } from "./chunk-H5NH7KPE.js";
 import {
-  clampEventLimit,
-  decodeEventCursor,
-  encodeEventCursor
-} from "./chunk-UQ5EHOH2.js";
+  BRIDGE_OUTBOX_DRAIN_HOOK
+} from "./chunk-4LH67P4U.js";
 import {
   domainEvents
 } from "./chunk-OFRRBC7M.js";
@@ -393,4 +393,4 @@ DrizzleEventBus = __decorateClass([
 export {
   DrizzleEventBus
 };
-//# sourceMappingURL=chunk-RKNW56RU.js.map
+//# sourceMappingURL=chunk-B34G6PHD.js.map

package/dist/{chunk-IN3EWFB4.js → chunk-BHZP6LOV.js}

@@ -1,15 +1,15 @@
 import {
   MemoryJobStore
 } from "./chunk-SNQ3TOWP.js";
+import {
+  MissingTenantIdError
+} from "./chunk-T4BIIU5E.js";
 import {
   clampLimit,
   decodeKeysetCursor,
   encodeKeysetCursor,
   toJobRunSummary
 } from "./chunk-L3LZWWSX.js";
-import {
-  MissingTenantIdError
-} from "./chunk-T4BIIU5E.js";
 import {
   JOBS_MULTI_TENANT,
   JOB_ORCHESTRATOR
@@ -209,4 +209,4 @@ function compareBy(a, b, order) {
 export {
   MemoryJobRunService
 };
-//# sourceMappingURL=chunk-IN3EWFB4.js.map
+//# sourceMappingURL=chunk-BHZP6LOV.js.map

package/dist/{chunk-W2UIDI3R.js → chunk-CLWBNXKF.js}

@@ -1,12 +1,12 @@
 import {
   JOB_RUN_SERVICE
 } from "./chunk-ZPL74UQN.js";
-import {
-  BRIDGE_DELIVERY_REPO
-} from "./chunk-4LH67P4U.js";
 import {
   EVENT_READ_PORT
 } from "./chunk-H5NH7KPE.js";
+import {
+  BRIDGE_DELIVERY_REPO
+} from "./chunk-4LH67P4U.js";
 import {
   INTEGRATION_CURSOR_STORE,
   INTEGRATION_RUN_RECORDER
@@ -181,4 +181,4 @@ ObservabilityService = __decorateClass([
 export {
   ObservabilityService
 };
-//# sourceMappingURL=chunk-W2UIDI3R.js.map
+//# sourceMappingURL=chunk-CLWBNXKF.js.map

package/dist/{chunk-7MMS36AN.js → chunk-E6PLM6QG.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 {
-  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";
+  jobRuns,
+  jobSteps,
+  jobs
+} from "./chunk-OKXZ63IA.js";
 import {
   DRIZZLE
 } from "./chunk-U64T4YZE.js";
@@ -393,4 +393,4 @@ export {
   evaluateKeyTemplate,
   DrizzleJobOrchestrator
 };
-//# sourceMappingURL=chunk-7MMS36AN.js.map
+//# sourceMappingURL=chunk-E6PLM6QG.js.map

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

@@ -1011,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/
@@ -1020,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) {
@@ -1843,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)";
@@ -1864,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 }
@@ -4064,6 +4102,7 @@ export {
   validateJunctionDefinition,
   safeValidateJunctionDefinition,
   parseImportRef,
+  isActiveProvider,
   loadEntityFromYaml,
   loadEntitiesFromYaml,
   loadRelationshipFromYaml,
@@ -4124,4 +4163,4 @@ export {
   analyzeDomain,
   validateEntities
 };
-//# sourceMappingURL=chunk-CFFTPWHM.js.map
+//# sourceMappingURL=chunk-F7KN3U6U.js.map