@pattern-stack/codegen 0.10.1 → 0.11.0

package/templates/entity/new/frontend/collections/collection.ejs.t

@@ -12,7 +12,32 @@ const hasApiBaseUrl = !!frontend.sync.apiBaseUrlImport;
 const shapeUrlExpr = hasApiBaseUrl
   ? '`${API_BASE_URL}/' + plural + '`'
   : '`' + frontend.sync.shapeUrl + '/' + plural + '`';
+// REST list endpoint for 'api' sync mode
+const apiUrlExpr = hasApiBaseUrl
+  ? '`${API_BASE_URL}/' + plural + '`'
+  : '`' + frontend.sync.apiUrl + '/' + plural + '`';
+const schemaPrefix = frontend.collections?.schemaPrefix ?? 'schema.';
 -%>
+<% if (frontend.sync.mode === 'api') { -%>
+export const <%= camelName %>Collection = createCollection(
+	queryCollectionOptions({
+		id: '<%= plural %>',
+		queryKey: ['<%= plural %>'],
+		queryClient,
+		queryFn: async () => {
+			const res = await fetch(<%- apiUrlExpr %><% if (frontend.auth.function) { %>, {
+				headers: { Authorization: <%= frontend.auth.function %>() },
+			}<% } %>);
+			if (!res.ok) {
+				throw new Error(`GET <%= plural %> → ${res.status} ${res.statusText}`);
+			}
+			return res.json();
+		},
+		getKey: (item) => item.id,
+		schema: <%= schemaPrefix %><%= camelName %>Schema,
+	}),
+);
+<% } else { -%>
 export const <%= camelName %>Collection = createCollection(
 	electricCollectionOptions({
 		id: '<%= plural %>',
@@ -53,9 +78,9 @@ export const <%= camelName %>Collection = createCollection(
 <% } -%>
 <% } -%>
 		},
-<% const schemaPrefix = frontend.collections?.schemaPrefix ?? 'schema.'; -%>
 		schema: <%= schemaPrefix %><%= camelName %>Schema,
 		getKey: (item) => item.id,
 	}),
 );
 <% } -%>
+<% } -%>

package/templates/entity/new/frontend/collections/collections-base.ejs.t

@@ -3,6 +3,16 @@ to: <%= locations.frontendCollections.path %>/collections.ts
 skip_if: <%= !frontendEnabled %>
 force: false
 ---
+<% if (frontend.sync.mode === 'api') { -%>
+/**
+ * REST-backed Collections (TanStack Query)
+ * Generated by entity codegen - do not edit directly
+ */
+
+import { queryCollectionOptions } from '@tanstack/query-db-collection';
+import { createCollection } from '@tanstack/react-db';
+import { queryClient } from '<%= frontend.sync.queryClientImport ?? './query-client' %>';
+<% } else { -%>
 /**
  * Electric SQL Collections
  * Generated by entity codegen - do not edit directly
@@ -13,6 +23,7 @@ import { createCollection } from '@tanstack/react-db';
 <% if (frontend.sync.columnMapper) { -%>
 import { <%= frontend.sync.columnMapper %> } from '@electric-sql/client';
 <% } -%>
+<% } -%>
 <% if (frontend.auth.function) { -%>
 import { <%= frontend.auth.function %> } from '<%= locations.frontendCollectionsAuth.import %>';
 <% } -%>

package/templates/entity/new/frontend/entity/combined.ejs.t

@@ -31,14 +31,19 @@ const returnKeySingular = generate.hookReturnStyle === 'named' ? camelName : 'da
 <% if (generate.mutations && (exposeTrpc || exposeRepository)) { -%>
 import { useState, useCallback } from 'react';
 <% } -%>
-<% if (frontend.sync.columnMapper) { -%>
+<% if (frontend.sync.mode !== 'api' && frontend.sync.columnMapper) { -%>
 import { <%= frontend.sync.columnMapper %> } from '@electric-sql/client';
 <% } -%>
 import { <%= camelName %>Schema, type <%= importedTypeName %> } from '<%= locations.dbEntities.import %><% if (!locations.dbEntities.barrelExport) { %>/<%= name %><% } %>';
 <% if (exposeTrpc) { -%>
 import { trpc } from '<%= locations.trpcClient.import %>';
 <% } -%>
+<% if (frontend.sync.mode === 'api') { -%>
+import { queryCollectionOptions } from '@tanstack/query-db-collection';
+import { queryClient } from '<%= frontend.sync.queryClientImport ?? './query-client' %>';
+<% } else { -%>
 import { electricCollectionOptions } from '@tanstack/electric-db-collection';
+<% } -%>
 import { createCollection<% if (generate.hookStyle === 'useLiveQuery') { %>, useLiveQuery, eq<% } %> } from '@tanstack/react-db';
 <% if (generate.fieldMetadata) { -%>
 import type { FieldMeta, FieldType, FieldImportance } from '<%= locations.frontendFieldMetaTypes.import %>/field-meta';
@@ -118,7 +123,31 @@ export type <%= className %>Resolved = <%= className %>;
 // Without this filter, soft-deleted records will reappear after Electric sync.
 <% } -%>
 
+<%
+// REST list endpoint for 'api' sync mode
+const hasApiBaseUrl = !!frontend.sync.apiBaseUrlImport;
+const apiUrlExpr = hasApiBaseUrl
+  ? '`${API_BASE_URL}/' + plural + '`'
+  : '`' + frontend.sync.apiUrl + '/' + plural + '`';
+-%>
 export const <%= collectionVar %> = createCollection(
+<% if (frontend.sync.mode === 'api') { -%>
+	queryCollectionOptions({
+		id: '<%= plural %>',
+		queryKey: ['<%= plural %>'],
+		queryClient,
+		queryFn: async () => {
+			const res = await fetch(<%- apiUrlExpr %><% if (frontend.auth.function) { %>, {
+				headers: { Authorization: <%= frontend.auth.function %>() },
+			}<% } %>);
+			if (!res.ok) {
+				throw new Error(`GET <%= plural %> → ${res.status} ${res.statusText}`);
+			}
+			return res.json();
+		},
+		getKey: (item) => item.id,
+		schema: <%= camelName %>Schema,
+<% } else { -%>
 	electricCollectionOptions({
 		id: '<%= plural %>',
 		shapeOptions: {
@@ -168,6 +197,7 @@ export const <%= collectionVar %> = createCollection(
 		},
 		schema: <%= camelName %>Schema,
 		getKey: (item) => item.id,
+<% } -%>
 <% if (generate.mutations && (exposeTrpc || exposeRepository)) { -%>
 <% if (exposeTrpc) { -%>
 		onInsert: async ({ transaction }) => {

package/templates/entity/new/prompt.js

@@ -305,7 +305,7 @@ export default {
 
     // v2 blocks (optional — absent in v1 entities)
     const queriesBlock = definition.queries || null;
-    const syncBlock = definition.sync || null;
+    const integrationBlock = definition.integration || null;
     const eventsBlock = definition.events || null;
     // EVT-7: emits is semantically 3-valued — undefined (fallback path),
     // [] (explicit opt-out), or string[] (typed emission). Preserve the
@@ -579,7 +579,7 @@ export default {
       moduleToController: importHelpers.moduleToController(fileNames.controller.replace('.ts', '')),
       // OPENAPI-2: module imports DTO file to register Zod schemas at onModuleInit.
       moduleToDto: importHelpers.moduleToDto(fileNames.dto.replace('.ts', '')),
-      // ADR-033.1: sync-source module imports the entity type from the
+      // ADR-033.1: integration-source module imports the entity type from the
       // domain barrel for the IChangeSource<T> type parameter.
       moduleToDomain: importHelpers.moduleToDomain(),
       // From controller (presentation/rest/) to queries/commands
@@ -1136,7 +1136,7 @@ export default {
     const hasOrderedQuery = processedQueries.some((q) => q.hasOrder);
 
     // ============================================================================
-    // v2: Sync
+    // v2: Integration
     // ============================================================================
 
     // ADR-033.1 / ADR-033.2: provider-keyed detection block.
@@ -1150,18 +1150,18 @@ export default {
     // Render the per-entity DetectionConfigs map as a TS object literal.
     // JSON.stringify produces valid TS for the canonical DetectionConfig shape
     // (strings, numbers, booleans, arrays, plain objects). Provider keys keep
-    // YAML insertion order. Used by sync-source.ejs.t.
+    // YAML insertion order. Used by integration-source.ejs.t.
     const detectionConfigsLiteral = hasDetection
       ? JSON.stringify(detectionBlock, null, 2)
       : '{}';
 
-    const hasSyncBlock = syncBlock != null;
-    const syncElectric = hasSyncBlock ? (syncBlock.electric ?? false) : false;
-    const rawSyncProviders = hasSyncBlock ? (syncBlock.providers ?? {}) : {};
-    const hasSyncProviders = Object.keys(rawSyncProviders).length > 0;
+    const hasIntegrationBlock = integrationBlock != null;
+    const integrationElectric = hasIntegrationBlock ? (integrationBlock.electric ?? false) : false;
+    const rawIntegrationProviders = hasIntegrationBlock ? (integrationBlock.providers ?? {}) : {};
+    const hasIntegrationProviders = Object.keys(rawIntegrationProviders).length > 0;
 
-    const syncProviders = hasSyncProviders
-      ? Object.entries(rawSyncProviders).map(([providerName, cfg]) => {
+    const integrationProviders = hasIntegrationProviders
+      ? Object.entries(rawIntegrationProviders).map(([providerName, cfg]) => {
           // Normalize field_mapping: { local: key, remote: value }[]
           const rawMapping = cfg.field_mapping ?? {};
           const fieldMapping = Object.entries(rawMapping).map(([local, remote]) => ({
@@ -1488,6 +1488,18 @@ export default {
             : 'getAuthorizationHeader',
         },
         sync: {
+          // Read transport for the generated collection:
+          //   'electric' (default) → electricCollectionOptions (real-time shape sync)
+          //   'api'                → queryCollectionOptions (REST via TanStack Query)
+          // Additive + default-off: existing consumers are unaffected. The rest of
+          // the store (hooks/useLiveQuery, resolve, mutations) is mode-agnostic.
+          mode: frontendSync.mode ?? 'electric',
+          // 'api' mode only: REST base path; the list endpoint is `${apiUrl}/${plural}`
+          // (or `${API_BASE_URL}/${plural}` when apiBaseUrlImport is set).
+          apiUrl: frontendSync.apiUrl ?? '/api',
+          // 'api' mode only: import path for the shared TanStack QueryClient.
+          // null → a sibling './query-client' is assumed (consumer-provided).
+          queryClientImport: frontendSync.queryClientImport ?? null,
           shapeUrl: frontendSync.shapeUrl ?? '/v1/shape',
           useTableParam: frontendSync.useTableParam ?? true,
           // Column mapper for snake_case to camelCase conversion (e.g., 'snakeCamelMapper')
@@ -1609,11 +1621,11 @@ export default {
       hasMultiFieldQuery,
       hasOrderedQuery,
 
-      // Sync
-      hasSyncBlock,
-      syncElectric,
-      hasSyncProviders,
-      syncProviders,
+      // Integration
+      hasIntegrationBlock,
+      integrationElectric,
+      hasIntegrationProviders,
+      integrationProviders,
 
       // Detection (ADR-033.1 / ADR-033.2 typed provider artifacts)
       hasDetection,

package/templates/junction/new/entity.ejs.t

@@ -91,7 +91,7 @@ export const <%= tableVarName %> = pgTable(
     // surrogate id). Role is part of the junction's identity — the same pair
     // with two different roles is two distinct rows (e.g. a contact who is both
     // `champion` and `decision_maker` on one opportunity). This is the
-    // ON CONFLICT target for syncUpsert on role-bearing junctions.
+    // ON CONFLICT target for integrationUpsert on role-bearing junctions.
     primaryKey({ columns: [table.<%= leftColumnCamel %>, table.<%= rightColumnCamel %>, table.role] }),
 <%_ } else { _%>
     // Composite primary key on the two FK columns (Q4 resolution: no surrogate id)

package/templates/junction/new/prompt.js

@@ -378,23 +378,23 @@ export default {
     const rightEntityCamel = camelCase(rightEntity);
 
     // ======================================================================
-    // Inbound-sync write surface (#374)
+    // Inbound-integration write surface (#374)
     // ======================================================================
-    // The junction sync identity is the tuple (leftId, rightId[, role]); its
+    // The junction integration identity is the tuple (leftId, rightId[, role]); its
     // externalId is a COMPOSITE string. Both parent FKs resolve strictly. FK
     // write-keys use `${camelCase(entity)}ExternalId` (matches the reference).
 
-    const leftSyncWriteKey = `${leftEntityCamel}ExternalId`;
-    const rightSyncWriteKey = `${rightEntityCamel}ExternalId`;
+    const leftIntegrationWriteKey = `${leftEntityCamel}ExternalId`;
+    const rightIntegrationWriteKey = `${rightEntityCamel}ExternalId`;
     const roleColumnCamel = hasRole ? 'role' : null;
     // Role TS type — literal union from the enum choices, else absent.
     const roleTsType = hasRole
       ? roleChoices.map((c) => `'${c}'`).join(' | ')
       : null;
 
-    // JunctionSyncConfig literal fields. refTable is emitted as a live table
+    // JunctionIntegrationConfig literal fields. refTable is emitted as a live table
     // identifier (leftTable/rightTable) by the template.
-    const syncConfig = {
+    const integrationConfig = {
       leftColumn: leftColumnCamel,
       leftRefTable: leftTable,
       rightColumn: rightColumnCamel,
@@ -402,17 +402,17 @@ export default {
       roleColumn: roleColumnCamel,
     };
 
-    // TSyncWrite fields: both parent external ids + optional role + userId.
-    const syncWriteFields = [
-      { name: leftSyncWriteKey, tsType: 'string' },
-      { name: rightSyncWriteKey, tsType: 'string' },
+    // TIntegrationWrite fields: both parent external ids + optional role + userId.
+    const integrationWriteFields = [
+      { name: leftIntegrationWriteKey, tsType: 'string' },
+      { name: rightIntegrationWriteKey, tsType: 'string' },
       ...(hasRole ? [{ name: 'role', tsType: roleTsType }] : []),
       { name: 'userId', tsType: 'string' },
     ];
 
-    // TSyncProjection fields: composite id + local FK columns + optional role +
+    // TIntegrationProjection fields: composite id + local FK columns + optional role +
     // timestamps. No surrogate id column on a junction.
-    const syncProjectionFields = [
+    const integrationProjectionFields = [
       { name: 'id', tsType: 'string' },
       { name: leftColumnCamel, tsType: 'string' },
       { name: rightColumnCamel, tsType: 'string' },
@@ -423,15 +423,15 @@ export default {
 
     // Parent-table imports for the FK resolvers, deduped (#368). Junction
     // endpoints are distinct by schema, so two imports unless they collide.
-    const syncParentImports = [];
-    const seenSyncImports = new Set();
+    const integrationParentImports = [];
+    const seenIntegrationImports = new Set();
     for (const imp of [
       { table: leftTable, importPath: leftEntityImportFromJunction },
       { table: rightTable, importPath: rightEntityImportFromJunction },
     ]) {
-      if (seenSyncImports.has(imp.table)) continue;
-      seenSyncImports.add(imp.table);
-      syncParentImports.push(imp);
+      if (seenIntegrationImports.has(imp.table)) continue;
+      seenIntegrationImports.add(imp.table);
+      integrationParentImports.push(imp);
     }
 
     // ======================================================================
@@ -523,16 +523,16 @@ export default {
       rightTable,
 
       // ──────────────────────────────────────────────────────────────────
-      // Inbound-sync write surface (#374)
+      // Inbound-integration write surface (#374)
       // ──────────────────────────────────────────────────────────────────
-      leftSyncWriteKey,
-      rightSyncWriteKey,
+      leftIntegrationWriteKey,
+      rightIntegrationWriteKey,
       roleColumnCamel,
       roleTsType,
-      junctionSyncConfig: syncConfig,
-      syncWriteFields,
-      syncProjectionFields,
-      syncParentImports,
+      junctionIntegrationConfig: integrationConfig,
+      integrationWriteFields,
+      integrationProjectionFields,
+      integrationParentImports,
 
       // ──────────────────────────────────────────────────────────────────
       // CGP-60 — fan-out locals

package/templates/junction/new/repository.ejs.t

@@ -7,41 +7,41 @@ import { Injectable, Inject } from '@nestjs/common';
 import { eq } from 'drizzle-orm';
 import { DRIZZLE } from '@shared/constants/tokens';
 import type { DrizzleClient } from '@shared/types/drizzle';
-import { JunctionSyncRepository } from '@shared/base-classes/junction-sync-repository';
-import type { JunctionSyncConfig } from '@shared/base-classes/junction-sync-repository';
-<%_ syncParentImports.forEach((imp) => { _%>
+import { JunctionIntegrationRepository } from '@shared/base-classes/junction-integration-repository';
+import type { JunctionIntegrationConfig } from '@shared/base-classes/junction-integration-repository';
+<%_ integrationParentImports.forEach((imp) => { _%>
 import { <%= imp.table %> } from '<%= imp.importPath %>';
 <%_ }); _%>
 import { <%= tableVarName %>, type <%= classNames.entity %> } from './<%= name %>.entity';
 
 /**
- * Canonical fields a synced <%= name %> junction write carries (#374). BOTH
+ * Canonical fields a integrated <%= name %> junction write carries (#374). BOTH
  * parent FKs are named by their vendor external ids and resolved STRICTLY in
  * the tx (a missing parent throws → the orchestrator records a failed item and
  * continues). `userId` is run context (no column on the junction).
  */
-export interface <%= classNames.entity %>SyncWrite {
-<%_ syncWriteFields.forEach((f) => { _%>
+export interface <%= classNames.entity %>IntegrationWrite {
+<%_ integrationWriteFields.forEach((f) => { _%>
   readonly <%= f.name %>: <%- f.tsType %>;
 <%_ }); _%>
 }
 
 /**
- * Canonical-projected view of a <%= name %> junction row, keyed for the sync
+ * Canonical-projected view of a <%= name %> junction row, keyed for the integration
  * differ (#374). `id` is the COMPOSITE externalId (the junction has no
  * surrogate id); the FKs are the LOCAL resolved uuids.
  */
-export interface <%= classNames.entity %>SyncProjection {
-<%_ syncProjectionFields.forEach((f) => { _%>
+export interface <%= classNames.entity %>IntegrationProjection {
+<%_ integrationProjectionFields.forEach((f) => { _%>
   readonly <%= f.name %>: <%- f.tsType %>;
 <%_ }); _%>
 }
 
 @Injectable()
-export class <%= classNames.repository %> extends JunctionSyncRepository<
+export class <%= classNames.repository %> extends JunctionIntegrationRepository<
   <%= classNames.entity %>,
-  <%= classNames.entity %>SyncWrite,
-  <%= classNames.entity %>SyncProjection
+  <%= classNames.entity %>IntegrationWrite,
+  <%= classNames.entity %>IntegrationProjection
 > {
   readonly table = <%= tableVarName %>;
 
@@ -53,12 +53,12 @@ export class <%= classNames.repository %> extends JunctionSyncRepository<
     userTracking: false,
   };
 
-  // Inbound-sync write surface (#374). Both endpoints resolve strictly against
+  // Inbound-integration write surface (#374). Both endpoints resolve strictly against
   // the live parent tables; role-bearing junctions conflict on (left,right,role).
-  protected readonly syncConfig: JunctionSyncConfig = {
-    left: { column: '<%= junctionSyncConfig.leftColumn %>', refTable: <%= junctionSyncConfig.leftRefTable %> },
-    right: { column: '<%= junctionSyncConfig.rightColumn %>', refTable: <%= junctionSyncConfig.rightRefTable %> },
-    roleColumn: <%- junctionSyncConfig.roleColumn ? `'${junctionSyncConfig.roleColumn}'` : 'null' %>,
+  protected readonly integrationConfig: JunctionIntegrationConfig = {
+    left: { column: '<%= junctionIntegrationConfig.leftColumn %>', refTable: <%= junctionIntegrationConfig.leftRefTable %> },
+    right: { column: '<%= junctionIntegrationConfig.rightColumn %>', refTable: <%= junctionIntegrationConfig.rightRefTable %> },
+    roleColumn: <%- junctionIntegrationConfig.roleColumn ? `'${junctionIntegrationConfig.roleColumn}'` : 'null' %>,
   };
 
   constructor(@Inject(DRIZZLE) db: DrizzleClient) {
@@ -102,7 +102,7 @@ export class <%= classNames.repository %> extends JunctionSyncRepository<
     return rows as <%= classNames.entity %>[];
   }
 
-  // Inherited from JunctionSyncRepository (+ BaseRepository):
+  // Inherited from JunctionIntegrationRepository (+ BaseRepository):
   //   findById, findByIds, list, count, exists, create, update, delete, upsertMany
-  //   syncUpsertOne, findByExternalIdProjected, softDeleteByExternalId
+  //   integrationUpsertOne, findByExternalIdProjected, softDeleteByExternalId
 }

package/templates/subsystem/auth/auth-oauth-state.schema.ejs.t

@@ -3,7 +3,7 @@ to: "<%= schemaPath %>"
 force: true
 ---
 <%- typeof generatedBanner !== 'undefined' ? generatedBanner : '' %>
-// Schema barrel append tracked in #284 — same gap as events/jobs/sync today.
+// Schema barrel append tracked in #284 — same gap as events/jobs/integration today.
 /**
  * Drizzle schema for the `auth_oauth_state` table — backs the
  * `DrizzleOAuthStateStore` (`state-store.drizzle-backend.ts`).
@@ -21,7 +21,7 @@ force: true
  *   - `expires_at`  — TTL boundary; entries past this are treated as absent.
  *
  * Convention: schema files live at the root of the subsystem dir
- * (mirrors `cache.schema.ts`, `sync-audit.schema.ts`, `domain-events.schema.ts`).
+ * (mirrors `cache.schema.ts`, `integration-audit.schema.ts`, `domain-events.schema.ts`).
  */
 import { pgTable, text, timestamp } from 'drizzle-orm/pg-core';
 import type { InferSelectModel } from 'drizzle-orm';

package/templates/subsystem/auth-config/prompt.js

@@ -5,7 +5,7 @@
  * config-block inject step independently — `subsystem install auth --force`
  * preserves an existing `auth:` block by skipping this action; pass
  * `--force-config` to opt into regeneration. Mirrors `events-config` /
- * `sync-config` / `observability-config` exactly.
+ * `integration-config` / `observability-config` exactly.
  *
  * Invoked via:
  *   bunx hygen subsystem auth-config --configPath <abs>

package/templates/subsystem/auth-integrations/app-module-hook.ejs.t

@@ -2,15 +2,15 @@
 to: "<%= appModulePath %>"
 inject: true
 append: true
-skip_if: "IntegrationsAuthModule"
+skip_if: "ConnectionsAuthModule"
 ---
 
-// TODO: Register IntegrationsAuthModule (vendored from auth-integrations starter)
+// TODO: Register ConnectionsAuthModule (vendored from auth-integrations starter)
 // Add to AppModule.imports AFTER AuthModule:
 //
-//   import { IntegrationsAuthModule } from '@shared/integrations/integrations-auth.module';
+//   import { ConnectionsAuthModule } from '@shared/connections/connections-auth.module';
 //   // ...
-//   IntegrationsAuthModule,
+//   ConnectionsAuthModule,
 //
 // Requires AuthModule.forRoot(...) registered first (provides ENCRYPTION_KEY).
-// Run `cdp entity new integration` to scaffold the codegen layer the adapters import.
+// Run `cdp entity new connection` to scaffold the codegen layer the adapters import.

package/templates/subsystem/bridge/prompt.js

@@ -3,7 +3,7 @@
  *
  * Locals resolved by the CLI (src/cli/shared/bridge-scaffold-locals.ts) and
  * forwarded as CLI args. This prompt.js coerces boolean-ish strings back into
- * JS booleans for parity with events / sync (Hygen args arrive as strings).
+ * JS booleans for parity with events / integration (Hygen args arrive as strings).
  *
  * Invoked via:
  *   bunx hygen subsystem bridge \