@pattern-stack/codegen 0.6.5 → 0.6.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pattern-stack/codegen",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "description": "Entity-driven code generation for full-stack TypeScript applications",
   "license": "MIT",
   "type": "module",

package/runtime/subsystems/auth/auth.tokens.ts

@@ -23,7 +23,7 @@
  * `HUBSPOT_AUTH_STRATEGY`) by each integration module — this subsystem does
  * not mandate a single `AUTH_STRATEGY` token because an app typically has
  * many concurrent strategies, one per provider. They are dispatched through
- * `STRATEGY_REGISTRY` (a `ReadonlyMap<slug, ProviderStrategy>`), populated
+ * `STRATEGY_REGISTRY` (a `ReadonlyMap<slug, IProviderStrategy>`), populated
  * by per-provider modules via a `useFactory` provider.
  */
 export const ENCRYPTION_KEY = Symbol('ENCRYPTION_KEY');

package/runtime/subsystems/auth/backends/encryption-key/env.ts

@@ -6,7 +6,7 @@
  * ciphertexts — prevents replay-style inference. Auth tag enforces integrity;
  * any tampering throws on decrypt.
  *
- * Key source: `TOKEN_ENCRYPTION_KEY` env var, 32 bytes base64-encoded.
+ * Key source: `INTEGRATION_TOKEN_ENCRYPTION_KEY` env var, 32 bytes base64-encoded.
  * Generate via `openssl rand -base64 32`.
  *
  * Future backend: `kms.ts` (AWS/GCP KMS) for production deployments that
@@ -18,7 +18,7 @@ import type { IEncryptionKey } from '../../protocols/encryption-key';
 export interface EnvEncryptionKeyOptions {
   /** Defaults to `process.env`. Tests inject a fixture. */
   env?: NodeJS.ProcessEnv;
-  /** Defaults to `'TOKEN_ENCRYPTION_KEY'`. */
+  /** Defaults to `'INTEGRATION_TOKEN_ENCRYPTION_KEY'`. */
   envVar?: string;
 }
 
@@ -32,7 +32,7 @@ export class EnvEncryptionKey implements IEncryptionKey {
 
   constructor(opts: EnvEncryptionKeyOptions = {}) {
     const env = opts.env ?? process.env;
-    const envVar = opts.envVar ?? 'TOKEN_ENCRYPTION_KEY';
+    const envVar = opts.envVar ?? 'INTEGRATION_TOKEN_ENCRYPTION_KEY';
     const raw = env[envVar];
     if (!raw) {
       throw new Error(

package/runtime/subsystems/auth/controllers/auth.controller.ts

@@ -9,7 +9,7 @@
  *     302-redirects to the post-connect path.
  *
  * Hexagonal seams:
- *   - `STRATEGY_REGISTRY` (ReadonlyMap<slug, ProviderStrategy>) — dispatch.
+ *   - `STRATEGY_REGISTRY` (ReadonlyMap<slug, IProviderStrategy>) — dispatch.
  *     Concrete per-provider strategies live consumer-side and contribute
  *     entries via a `useFactory` in the consumer's app module.
  *   - `AUTH_USER_CONTEXT` (IUserContext) — resolves "who is this request"
@@ -44,7 +44,7 @@ import type { AuthModuleOptions } from '../auth.module';
 import type { IOAuthStateStore } from '../protocols/oauth-state-store';
 import type { IUserContext } from '../protocols/user-context';
 import type {
-  ProviderStrategy,
+  IProviderStrategy,
   ProviderStrategyRegistry,
 } from '../protocols/provider-strategy';
 import type { IIntegrationGrantSink } from '../protocols/integration-store';
@@ -131,7 +131,7 @@ export class AuthController {
     );
   }
 
-  private requireStrategy(slug: string): ProviderStrategy {
+  private requireStrategy(slug: string): IProviderStrategy {
     const strategy = this.registry.get(slug);
     if (!strategy) {
       throw new HttpException(

package/runtime/subsystems/auth/index.ts

@@ -29,7 +29,7 @@
  *   type IIntegrationGrantSink,
  *   type IntegrationGrantInput,
  *   type IUserContext,
- *   type ProviderStrategy,
+ *   type IProviderStrategy,
  *   type ProviderStrategyRegistry,
  *   type ExchangedTokens,
  * } from '@pattern-stack/codegen/runtime/subsystems/auth';
@@ -58,7 +58,7 @@ export type {
 } from './protocols/integration-store';
 export type { IUserContext } from './protocols/user-context';
 export type {
-  ProviderStrategy,
+  IProviderStrategy,
   ProviderStrategyRegistry,
   ExchangedTokens,
 } from './protocols/provider-strategy';

package/runtime/subsystems/auth/protocols/auth-strategy.ts

@@ -7,7 +7,7 @@
  * `OAuth2RefreshStrategy` template-method base in `../runtime/`.
  *
  * See `docs/adrs/ADR-031-auth-subsystem.md` and
- * `docs/gate-1-auth-extraction-findings.md` (inbound from dealbrain-v2) for
+ * `docs/gate-1-auth-extraction-findings.md` (extraction-source findings) for
  * the rationale.
  */
 

package/runtime/subsystems/auth/protocols/integration-store.ts

@@ -6,7 +6,7 @@
  * those rows — consumers implement these narrow ports against whatever
  * `integrations` table their app uses.
  *
- * In dealbrain-v2 (the extraction source) both ports are satisfied by a
+ * In the extraction-source app both ports are satisfied by a
  * pair of thin adapters over `IntegrationService` + `RefreshIntegrationUseCase`.
  * The codegen-patterns `examples/auth-integrations/` starter (separate PR)
  * ships a canonical `integration.yaml` whose generated service + use case
@@ -70,7 +70,7 @@ export interface IIntegrationTokenWriter {
  * authorize-code callback (i.e. the user just connected a new provider, or
  * re-connected an existing one).
  *
- * `AuthController.callback` invokes this after `ProviderStrategy.exchangeCodeForTokens`.
+ * `AuthController.callback` invokes this after `IProviderStrategy.exchangeCodeForTokens`.
  * The subsystem itself never imports a concrete `IntegrationsService` — the
  * consumer's `auth-integrations` starter (or any equivalent) adapts this
  * port. Keeps the auth subsystem standalone: a non-codegen consumer can

package/runtime/subsystems/auth/protocols/provider-strategy.ts

@@ -1,5 +1,5 @@
 /**
- * Auth subsystem — `ProviderStrategy` contract.
+ * Auth subsystem — `IProviderStrategy` contract.
  *
  * Extension of `OAuth2RefreshStrategy` (which already covers the refresh
  * path) that adds the two methods needed by the connect/callback dance:
@@ -11,11 +11,18 @@
  * stay consumer-side per ADR-031 ("every app has different combinations").
  * They typically subclass `OAuth2RefreshStrategy` for the refresh path and
  * implement these two methods structurally — that satisfies
- * `ProviderStrategy` because TS lets interfaces extend classes by type.
+ * `IProviderStrategy` because TS lets interfaces extend classes by type.
  *
  * AuthController never imports a concrete strategy — it injects the
- * `STRATEGY_REGISTRY` (a `ReadonlyMap<provider-slug, ProviderStrategy>`)
+ * `STRATEGY_REGISTRY` (a `ReadonlyMap<provider-slug, IProviderStrategy>`)
  * and dispatches by slug.
+ *
+ * **Naming convention:** interfaces that describe behavioral ports use the
+ * `I` prefix (`IProviderStrategy`, `IIntegrationReader`, `IUserContext`,
+ * `IOAuthStateStore`, `IEncryptionKey`). Plain data types / DTOs (e.g.
+ * `ExchangedTokens`, `DecryptedIntegration`, `IntegrationGrantInput`) do
+ * not. Abstract template-method classes (e.g. `OAuth2RefreshStrategy`) also
+ * do not — the `I` is for interfaces only.
  */
 import type { OAuth2RefreshStrategy } from '../runtime/oauth2-refresh.strategy';
 
@@ -29,7 +36,7 @@ export interface ExchangedTokens {
   providerMetadata?: Record<string, unknown>;
 }
 
-export interface ProviderStrategy extends OAuth2RefreshStrategy {
+export interface IProviderStrategy extends OAuth2RefreshStrategy {
   buildAuthorizeUrl(args: { state: string; redirectUri: string }): string;
   exchangeCodeForTokens(args: {
     code: string;
@@ -38,4 +45,4 @@ export interface ProviderStrategy extends OAuth2RefreshStrategy {
 }
 
 /** The DI value type behind the `STRATEGY_REGISTRY` token. */
-export type ProviderStrategyRegistry = ReadonlyMap<string, ProviderStrategy>;
+export type ProviderStrategyRegistry = ReadonlyMap<string, IProviderStrategy>;

package/runtime/subsystems/auth/runtime/oauth2-refresh.strategy.ts

@@ -2,8 +2,8 @@
  * Abstract base class for OAuth2 refresh-token strategies.
  *
  * Template-method pattern: `resolve()` is concrete; four small hooks inject
- * provider specifics. Validated across two providers in dealbrain-v2
- * (SalesforceAuthStrategy, HubSpotAuthStrategy) before extraction here — see
+ * provider specifics. Validated across two providers (Salesforce, HubSpot)
+ * in the extraction-source app before being extracted here — see
  * `docs/gate-1-auth-extraction-findings.md` for the "build first, extract
  * later" evidence.
  *

package/runtime/subsystems/auth/runtime/session-expired.error.ts

@@ -8,8 +8,8 @@
  * the `isSessionExpiredError` predicate to decide whether to force-refresh
  * and retry once.
  *
- * This discriminator replaces the SFDC-only `instanceof` check from
- * dealbrain-v2's original `withAuthRetry`. See
+ * This discriminator replaces the SFDC-only `instanceof` check from the
+ * extraction-source app's original `withAuthRetry`. See
  * `docs/gate-1-auth-extraction-findings.md` (recommendation 4).
  */
 export class SessionExpiredError extends Error {

package/runtime/subsystems/auth/runtime/with-auth-retry.ts

@@ -6,7 +6,7 @@
  * on the refreshed token propagates rather than looping, so transient
  * adapter bugs can't hang the caller.
  *
- * Generalisation over dealbrain's original SFDC-specific version: the
+ * Generalisation over the extraction source's SFDC-specific original: the
  * session-expired classifier is injected. Providers mark their session-
  * expired errors (via `instanceof` of a marker class, or by setting a known
  * property) and pass a classifier matching that shape.

package/runtime/subsystems/index.ts

@@ -82,7 +82,7 @@ export type {
   IIntegrationGrantSink,
   IntegrationGrantInput,
   IUserContext,
-  ProviderStrategy,
+  IProviderStrategy,
   ProviderStrategyRegistry,
   ExchangedTokens,
   AuthCredentials,

package/runtime/subsystems/sync/deep-equal.differ.ts

@@ -5,7 +5,7 @@
  * per-field diff (`{ from, to }`) for every field whose value changed.
  * Returns `'noop'` when the record is unchanged.
  *
- * Design decisions (extracted from dealbrain-v2 + HS-9 findings):
+ * Design decisions (extracted from the upstream consumer + HS-9 findings):
  *
  * 1. **Ignore list** — row metadata that sinks/services stamp unconditionally
  *    so upstream cannot reasonably disagree:

package/runtime/subsystems/sync/execute-sync.use-case.ts

@@ -41,7 +41,7 @@
  * is strictly provider-agnostic:
  *   - `entityType` is `string` throughout; no `'opportunity' | 'account' | ...`
  *     narrowing leaks into the use case
- *   - dealbrain's `SyncRunRecorderService` class injection replaced with the
+ *   - the upstream consumer's `SyncRunRecorderService` class injection replaced with the
  *     `ISyncRunRecorder` protocol (backend lands in SYNC-4)
  */
 import { Inject, Injectable, Logger, Optional } from '@nestjs/common';

package/runtime/subsystems/sync/sync-change-source.protocol.ts

@@ -6,7 +6,7 @@
  * depend on a specific backend implementation.
  *
  * Three detection modes (poll / cdc / webhook) converge on this single port
- * per ADR-0002 (dealbrain-v2). Per-mode differences live in the
+ * per ADR-0002 (the upstream consumer). Per-mode differences live in the
  * `Change.source` / `dedupKey` / `providerChangedFields` metadata fields,
  * not in separate ports.
  *

package/runtime/subsystems/sync/sync-cursor-store.memory-backend.ts

@@ -21,7 +21,7 @@
  * could occur. Tests that want to assert per-tenant isolation should
  * target the Drizzle backend.
  *
- * Not shipped in dealbrain-v2; this is a subsystem-first addition for the
+ * Not shipped in the upstream consumer; this is a subsystem-first addition for the
  * test surface. Consumed by:
  *   - SYNC-5 unit tests (`ExecuteSyncUseCase` against synthetic sources)
  *   - SYNC-6 module tests (`SyncModule.forRoot({ backend: 'memory' })`)

package/runtime/subsystems/sync/sync-loopback.protocol.ts

@@ -14,10 +14,9 @@
  * a backend in Phase 1; consumers that need loopback suppression provide
  * their own (redis-hashed, memory TTL, etc.).
  *
- * `entityType` is `string` (not a union) — per dealbrain-v2's HS-9 findings
- * the CRM-specific narrowing `'opportunity' | 'account' | 'contact'` bled
- * into the port and had to be removed. Consumers narrow internally if they
- * want.
+ * `entityType` is `string` (not a union) — per HS-9 findings the
+ * CRM-specific narrowing `'opportunity' | 'account' | 'contact'` bled into
+ * the port and had to be removed. Consumers narrow internally if they want.
  */
 
 export interface ILoopbackFingerprintStore<T = unknown> {

package/runtime/subsystems/sync/sync-run-recorder.drizzle-backend.ts

@@ -1,7 +1,7 @@
 /**
  * DrizzleSyncRunRecorder — Drizzle-backed `ISyncRunRecorder` (SYNC-4).
  *
- * Generic write path only — extracted from dealbrain-v2's
+ * Generic write path only — extracted from the source app's
  * `SyncRunRecorderService`, minus CRM-specific convenience methods. Those
  * stay consumer-owned; the subsystem ships the substrate.
  *

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

@@ -17,5 +17,5 @@ skip_if: "AuthModule"
 //     redirectUriBase: process.env.AUTH_REDIRECT_URI_BASE ?? '<%= redirectUriBase %>',
 //   }),
 //
-// Requires TOKEN_ENCRYPTION_KEY in your environment (see .env.config).
+// Requires INTEGRATION_TOKEN_ENCRYPTION_KEY in your environment (see .env.config).
 // Provide an IUserContext adapter (your app's session/JWT scheme).

package/templates/subsystem/auth/env-config.ejs.t

@@ -2,19 +2,19 @@
 to: "<%= envConfigPath %>"
 inject: true
 append: true
-skip_if: "TOKEN_ENCRYPTION_KEY"
+skip_if: "INTEGRATION_TOKEN_ENCRYPTION_KEY"
 ---
 
 # OAuth integration token encryption key — 32 bytes base64 (AES-256-GCM).
 # DO NOT REUSE this dev value in prod. To regenerate locally:
 #   node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
 # Re-running `codegen subsystem install auth` does NOT rotate this key —
-# `skip_if: "TOKEN_ENCRYPTION_KEY"` blocks the inject intentionally, because
-# silently rotating would invalidate every encrypted token already in the
-# consumer's `integrations` table. Rotation is a separate, auditable op.
+# `skip_if: "INTEGRATION_TOKEN_ENCRYPTION_KEY"` blocks the inject intentionally,
+# because silently rotating would invalidate every encrypted token already in
+# the consumer's `integrations` table. Rotation is a separate, auditable op.
 # In production: store the key in `secrets/secrets.yaml` (or your secret
 # manager) and have your deploy pipeline materialise it into the env at
 # boot — this `.env.config` line should be a placeholder, not the source.
-TOKEN_ENCRYPTION_KEY=<%= tokenEncryptionKey %>
+INTEGRATION_TOKEN_ENCRYPTION_KEY=<%= tokenEncryptionKey %>
 # Public base URL where OAuth providers redirect back. Override in staging/prod.
 AUTH_REDIRECT_URI_BASE=<%= redirectUriBase %>

package/templates/subsystem/auth/prompt.js

@@ -21,9 +21,9 @@
  *   - `app-module-hook.ejs.t` — appends a TODO comment block to
  *     app.module.ts directing the human to register
  *     `AuthModule.forRoot({ ... })`. Same convention as observability.
- *   - `env-config.ejs.t` — appends `TOKEN_ENCRYPTION_KEY=<b64>` and
- *     `AUTH_REDIRECT_URI_BASE=<url>` to `.env.config`. Idempotent via
- *     `skip_if: "TOKEN_ENCRYPTION_KEY"` — re-running install does NOT
+ *   - `env-config.ejs.t` — appends `INTEGRATION_TOKEN_ENCRYPTION_KEY=<b64>`
+ *     and `AUTH_REDIRECT_URI_BASE=<url>` to `.env.config`. Idempotent via
+ *     `skip_if: "INTEGRATION_TOKEN_ENCRYPTION_KEY"` — re-running install does NOT
  *     regenerate the key (rotation is a separate operation).
  *
  * Auth has NO `multi_tenant` knob (see auth-scaffold-locals.ts docstring).

package/templates/subsystem/auth-config/codegen-config-auth-block.ejs.t

@@ -6,7 +6,7 @@ skip_if: "auth:"
 ---
 
 auth:
-  # ── Encryption key (TOKEN_ENCRYPTION_KEY from .env.config) ──
+  # ── Encryption key (INTEGRATION_TOKEN_ENCRYPTION_KEY from .env.config) ──
   encryption_key: env
 
   # ── OAuth state store (drizzle for prod, memory for tests) ──