@pattern-stack/codegen 0.6.0 → 0.6.1

package/src/patterns/library/activity.pattern.ts

@@ -0,0 +1,32 @@
+/**
+ * ActivityPattern — replaces `family: activity`.
+ *
+ * Activity entities represent time-bounded interactions (calls, meetings,
+ * emails). The base repository/service expose date-range + opportunity +
+ * user-scoped lookups on top of the standard CRUD methods.
+ *
+ * Class names, import paths, and inherited-method strings match the
+ * legacy `FAMILY_MAP` entry verbatim so PATTERN-5's template swap produces
+ * byte-identical output.
+ */
+
+import { definePattern } from '../pattern-definition.js';
+
+export const ActivityPattern = definePattern({
+	name: 'Activity',
+	extends: ['Base'],
+	repositoryClass: 'ActivityEntityRepository',
+	serviceClass: 'ActivityEntityService',
+	repositoryImport: '@shared/base-classes/activity-entity-repository',
+	serviceImport: '@shared/base-classes/activity-entity-service',
+	repositoryInheritedMethods: [
+		'findById, findByIds, list, count, exists, create, update, delete, upsertMany',
+		'findByDateRange, findByUserId, findByOpportunityId, findRecentByOpportunityId',
+	],
+	serviceInheritedMethods: [
+		'findById, findByIds, list, count, exists, create, update, delete',
+		'findByDateRange, findByUserId, findByOpportunityId, findRecentByOpportunityId',
+	],
+	description:
+		'Time-bounded interaction entities — date-range + opportunity scoped lookups',
+});

package/src/patterns/library/base.pattern.ts

@@ -0,0 +1,28 @@
+/**
+ * BasePattern — identity pattern for the `extends` chain.
+ *
+ * Contributes no columns, no implied behaviors, and no config. Its only
+ * purpose is to anchor the inheritance hierarchy so every other pattern
+ * can declare `extends: ['Base']` and codegen can resolve that to a
+ * concrete `BaseRepository` / `BaseService` reference.
+ *
+ * Matches the existing `family: base` entry in
+ * `templates/entity/new/clean-lite-ps/prompt-extension.js` verbatim.
+ */
+
+import { definePattern } from '../pattern-definition.js';
+
+export const BasePattern = definePattern({
+	name: 'Base',
+	repositoryClass: 'BaseRepository',
+	serviceClass: 'BaseService',
+	repositoryImport: '@shared/base-classes/base-repository',
+	serviceImport: '@shared/base-classes/base-service',
+	repositoryInheritedMethods: [
+		'findById, findByIds, list, count, exists, create, update, delete, upsertMany',
+	],
+	serviceInheritedMethods: [
+		'findById, findByIds, list, count, exists, create, update, delete',
+	],
+	description: 'Identity pattern — base CRUD, no extra columns or methods',
+});

package/src/patterns/library/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Library pattern bootstrap — imports every shipped pattern and registers
+ * it with the shared library registry. Side-effect-only module: importing
+ * this barrel is what pre-registers `Base`, `Synced`, `Activity`,
+ * `Knowledge`, and `Metadata`.
+ *
+ * Adding a new library pattern is two edits: create the `*.pattern.ts`
+ * file and add the import+register pair below.
+ */
+
+import { registerLibraryPattern } from '../registry.js';
+import { ActivityPattern } from './activity.pattern.js';
+import { BasePattern } from './base.pattern.js';
+import { KnowledgePattern } from './knowledge.pattern.js';
+import { MetadataPattern } from './metadata.pattern.js';
+import { SyncedPattern } from './synced.pattern.js';
+
+registerLibraryPattern(BasePattern);
+registerLibraryPattern(SyncedPattern);
+registerLibraryPattern(ActivityPattern);
+registerLibraryPattern(KnowledgePattern);
+registerLibraryPattern(MetadataPattern);
+
+export {
+	ActivityPattern,
+	BasePattern,
+	KnowledgePattern,
+	MetadataPattern,
+	SyncedPattern,
+};

package/src/patterns/library/knowledge.pattern.ts

@@ -0,0 +1,31 @@
+/**
+ * KnowledgePattern — replaces `family: knowledge`.
+ *
+ * Knowledge entities hold long-form content with a workflow status and
+ * semantic-search support (vectors, pending/approved states). The base
+ * classes expose `semanticSearch`, pending-by-opportunity lookups, and
+ * batch status updates.
+ *
+ * Class names, import paths, and inherited-method strings match the
+ * legacy `FAMILY_MAP` entry verbatim.
+ */
+
+import { definePattern } from '../pattern-definition.js';
+
+export const KnowledgePattern = definePattern({
+	name: 'Knowledge',
+	extends: ['Base'],
+	repositoryClass: 'KnowledgeEntityRepository',
+	serviceClass: 'KnowledgeEntityService',
+	repositoryImport: '@shared/base-classes/knowledge-entity-repository',
+	serviceImport: '@shared/base-classes/knowledge-entity-service',
+	repositoryInheritedMethods: [
+		'findById, findByIds, list, count, exists, create, update, delete, upsertMany',
+		'semanticSearch, findPendingByOpportunityId, updateStatus, updateStatusBatch',
+	],
+	serviceInheritedMethods: [
+		'findById, findByIds, list, count, exists, create, update, delete',
+		'semanticSearch, findPendingByOpportunityId, updateStatus, updateStatusBatch',
+	],
+	description: 'Knowledge entities — semantic search + workflow status',
+});

package/src/patterns/library/metadata.pattern.ts

@@ -0,0 +1,31 @@
+/**
+ * MetadataPattern — replaces `family: metadata`.
+ *
+ * Metadata entities represent history-tracked auxiliary rows attached to a
+ * parent entity (audit trails, custom-field values, change logs). The base
+ * classes expose entity-id + type scoped lookups and history listing.
+ *
+ * Class names, import paths, and inherited-method strings match the
+ * legacy `FAMILY_MAP` entry verbatim.
+ */
+
+import { definePattern } from '../pattern-definition.js';
+
+export const MetadataPattern = definePattern({
+	name: 'Metadata',
+	extends: ['Base'],
+	repositoryClass: 'MetadataEntityRepository',
+	serviceClass: 'MetadataEntityService',
+	repositoryImport: '@shared/base-classes/metadata-entity-repository',
+	serviceImport: '@shared/base-classes/metadata-entity-service',
+	repositoryInheritedMethods: [
+		'findById, findByIds, list, count, exists, create, update, delete, upsertMany',
+		'findByEntityIdAndType, listByEntityId, listHistoryByEntityId',
+	],
+	serviceInheritedMethods: [
+		'findById, findByIds, list, count, exists, create, update, delete',
+		'findByEntityIdAndType, listByEntityId, listHistoryByEntityId',
+	],
+	description:
+		'History-tracked metadata rows — entity-id + type scoped lookups',
+});

package/src/patterns/library/synced.pattern.ts

@@ -0,0 +1,34 @@
+/**
+ * SyncedPattern — adds external-system sync columns and methods.
+ *
+ * Replaces the legacy `family: synced` entry in
+ * `templates/entity/new/clean-lite-ps/prompt-extension.js`. Class names,
+ * import paths, and inherited-method comment lines are preserved verbatim
+ * so PATTERN-5's template swap produces byte-identical output for
+ * pre-existing `family: synced` fixtures.
+ *
+ * Implies `external_id_tracking` — the behavior that contributes the
+ * `external_id`, `provider`, and `provider_metadata` columns to the table.
+ * An entity declaring `pattern: Synced` need not re-declare the behavior.
+ */
+
+import { definePattern } from '../pattern-definition.js';
+
+export const SyncedPattern = definePattern({
+	name: 'Synced',
+	extends: ['Base'],
+	repositoryClass: 'SyncedEntityRepository',
+	serviceClass: 'SyncedEntityService',
+	repositoryImport: '@shared/base-classes/synced-entity-repository',
+	serviceImport: '@shared/base-classes/synced-entity-service',
+	repositoryInheritedMethods: [
+		'findById, findByIds, list, count, exists, create, update, delete, upsertMany',
+		'findByExternalId, findAllByUserId, findVisibleByUserId, syncUpsert',
+	],
+	serviceInheritedMethods: [
+		'findById, findByIds, list, count, exists, create, update, delete',
+		'findByExternalId, findAllByUserId, findVisibleByUserId',
+	],
+	impliedBehaviors: ['external_id_tracking'],
+	description: 'External CRM/system sync columns and syncUpsert methods',
+});

package/src/patterns/pattern-definition.ts

@@ -0,0 +1,280 @@
+/**
+ * Pattern Definition — pure metadata record returned by an identity function.
+ *
+ * `definePattern()` is the registration artifact for both library-shipped and
+ * app-defined patterns. It carries only names + import paths for the classes
+ * a generated entity should extend — never the class constructors themselves.
+ * This keeps the codegen pipeline free of TS class-evaluation cost and avoids
+ * `reflect-metadata`, which lets the Hygen subprocess cheaply rebuild the
+ * registry (see `src/cli/shared/hygen.ts` — the registry loads twice per
+ * `entity new` invocation).
+ *
+ * Two pattern kinds share this surface:
+ *   - **domain** (default; ADR-031) — `PatternDefinition`. Contributes
+ *     repository/service base classes, columns, behaviors to entities that
+ *     declare `pattern:`/`patterns:` in YAML.
+ *   - **orchestration** (ADR-032) — `OrchestrationPatternDefinition`. Declares
+ *     a DI registry + optional dispatcher scaffold. Not entity-attached;
+ *     codegen emits a NestJS module under `src/orchestration/` instead.
+ *
+ * See `docs/adrs/ADR-031-app-defined-patterns.md` §"Decision 1" for the
+ * domain binding surface and `docs/adrs/ADR-032-orchestration-patterns.md`
+ * for the orchestration kind.
+ */
+
+import type { ZodSchema } from 'zod';
+
+/**
+ * A column a pattern contributes to every entity that declares it.
+ *
+ * Column-level conflicts between patterns, between a pattern and an
+ * entity-declared field, or between a pattern and a behavior-contributed
+ * field are codegen-time hard errors; see
+ * `src/patterns/validate-composition.ts`.
+ */
+export interface PatternColumnContribution {
+	/** snake_case column name — matches the database column */
+	name: string;
+	/** Drizzle column type string, e.g. "varchar(255)" or "text" */
+	type: string;
+}
+
+/**
+ * Discriminator for the two pattern shapes. Default is `"domain"` to preserve
+ * Phase 1 (ADR-031) behaviour — every existing PatternDefinition without a
+ * `kind` field continues to register as a domain pattern.
+ */
+export type PatternKind = 'domain' | 'orchestration';
+
+/**
+ * The full pattern metadata record. Every `definePattern({...})` call
+ * returns a value of this shape; the library and consumer registries
+ * store these and look them up by `name`.
+ */
+export interface PatternDefinition<TConfig = unknown> {
+	/** Unique name used in YAML — e.g. `pattern: Synced` */
+	name: string;
+
+	/**
+	 * ADR-032: defaults to `"domain"`. Phase 3 adds `"orchestration"` as a
+	 * disjoint shape (see `OrchestrationPatternDefinition`). Domain
+	 * `PatternDefinition` instances must omit this field or set it to
+	 * `"domain"`; the loader routes orchestration values to a separate map.
+	 */
+	kind?: 'domain';
+
+	/**
+	 * Built-in patterns this extends, by name. Phase 1 supports single-depth
+	 * chains only — a pattern may `extends: ['Synced']` but the transitive
+	 * chain is not yet resolved. Multi-depth inheritance is deferred until
+	 * a real consumer asks.
+	 */
+	extends?: string[];
+
+	/** Constructor name codegen emits in the generated repo's `extends` clause */
+	repositoryClass?: string;
+	/** Constructor name codegen emits in the generated service's `extends` clause */
+	serviceClass?: string;
+
+	/**
+	 * Fully-qualified TypeScript path alias the consumer's tsconfig resolves.
+	 * Library patterns use the consumer-installed runtime base class path
+	 * (e.g. `@shared/base-classes/synced-entity-repository`); app patterns
+	 * use whatever alias the consumer has configured (e.g. `@/patterns/...`).
+	 */
+	repositoryImport?: string;
+	/** Same as `repositoryImport` but for the service base class */
+	serviceImport?: string;
+
+	/**
+	 * Documentation-only method-signature strings emitted as comments in the
+	 * generated repo. Exist purely so app authors reading the generated file
+	 * see what their concrete class inherits without jumping to the base.
+	 */
+	repositoryInheritedMethods?: string[];
+	/** Same as `repositoryInheritedMethods` but for the service base class */
+	serviceInheritedMethods?: string[];
+
+	/**
+	 * Columns this pattern adds to every entity that declares it. Used by
+	 * the composition validator to detect column-name collisions.
+	 */
+	columns?: PatternColumnContribution[];
+
+	/**
+	 * Behaviors this pattern implicitly enables. Entity YAML need not
+	 * re-declare them; duplicates across patterns are silent-deduped.
+	 */
+	impliedBehaviors?: string[];
+
+	/**
+	 * Zod schema that validates the per-entity `config:` block for this
+	 * pattern at parse time. When absent, entities may not supply a `config:`
+	 * entry for this pattern and codegen emits no `patternConfig` property.
+	 */
+	configSchema?: ZodSchema<TConfig>;
+
+	/** One-line description for codegen help output and error messages */
+	description?: string;
+}
+
+/**
+ * Identity function that returns its argument unchanged. The body is trivial
+ * on purpose — the whole point is to give TypeScript a hook for generic
+ * inference on `TConfig` while leaving the runtime value a plain object
+ * registered by the codegen loader.
+ */
+export function definePattern<TConfig = unknown>(
+	def: PatternDefinition<TConfig>,
+): PatternDefinition<TConfig> {
+	return def;
+}
+
+/**
+ * Shape check for values produced by `import()`ing an app pattern file.
+ * The registry loader runs this on every exported value it finds; only
+ * values that pass are registered.
+ *
+ * We keep this deliberately loose — a `name` string is the whole
+ * requirement — because a pattern that contributes neither columns nor
+ * class references is still a *valid* identity pattern (e.g. `BasePattern`
+ * exists to anchor the `extends` chain without contributing anything).
+ * Stricter shape rules belong in the registry's "at-least-one-contribution"
+ * check, not here.
+ *
+ * This function is intentionally **kind-agnostic** — both
+ * `PatternDefinition` (domain) and `OrchestrationPatternDefinition`
+ * (orchestration) pass. The discriminator routing happens in the loader
+ * via `isOrchestrationPattern()`/`isDomainPattern()`.
+ */
+export function isPatternDefinition(val: unknown): val is PatternDefinition {
+	return (
+		typeof val === 'object' &&
+		val !== null &&
+		'name' in val &&
+		typeof (val as { name: unknown }).name === 'string'
+	);
+}
+
+// ============================================================================
+// Orchestration kind (ADR-032)
+// ============================================================================
+
+/**
+ * One registry's declarative shape. ADR-032 §"The Proposal".
+ *
+ * Phase 3-1 records this; Phase 3-2 codegen reads it to emit token files,
+ * provider blocks, and dispatcher overload signatures. Phase 3-1 validates
+ * only what is statically checkable from this record alone — see
+ * `validate-orchestration.ts` for the rules and their deferral notes.
+ */
+export interface OrchestrationRegistrySpec {
+	/**
+	 * Identifier for co-keyed sibling registries (ADR-032 Phase 3-2/3, O-1).
+	 *
+	 * The PRIMARY registry never carries a `name` — its tokens / methods are
+	 * derived from the pattern name alone (`${PATTERN_CONST}_REGISTRY`,
+	 * `select(...)`). Each co-keyed sibling MUST carry an explicit `name`
+	 * which the emitter uppercases for the token suffix and PascalCases for
+	 * the dispatcher method suffix:
+	 *
+	 *   `coKeyedRegistries: [{ name: 'auth', valueType: 'IAuthStrategy' ... }]`
+	 *   ⇒ `CRM_PORTS_AUTH_REGISTRY` token + `selectAuth(...)` method.
+	 *
+	 * No auto-stripping of "I" prefix or "Strategy/Port/Adapter/Provider"
+	 * suffixes — authors pick what reads right.
+	 */
+	name?: string;
+	/**
+	 * Type alias the consumer's tsconfig resolves (e.g. `"CrmAdapterDomain"`).
+	 * Phase 3-1 stores this string verbatim. Resolution that the path actually
+	 * imports a concrete TS enum is deferred to Phase 3-2 emission, where
+	 * codegen will need to read the consumer's source tree.
+	 */
+	keyType: string;
+	/**
+	 * Module specifier the emitter writes into `import type { keyType } from
+	 * '<keyTypeImport>'`. Required at Phase 3-2 emission; the generator emits
+	 * `pattern_missing_import_path` if absent. (ADR-032 Phase 3-2 §3.4 / O-3.)
+	 */
+	keyTypeImport?: string;
+	/** Same shape as `keyType` — the registry's value-type interface ref. */
+	valueType: string;
+	/** Module specifier for `valueType` import. See `keyTypeImport`. */
+	valueTypeImport?: string;
+	entries: ReadonlyArray<{
+		/** Stable string key — must be unique within this registry. */
+		key: string;
+		/**
+		 * Concrete provider class name (NOT a DI token string). Codegen will
+		 * import this and use it as the constructor injectable.
+		 * Phase 3-1 records it; Phase 3-2 verifies it resolves.
+		 */
+		provider: string;
+		/** Module specifier for `provider` import. See `keyTypeImport`. */
+		providerImport?: string;
+	}>;
+}
+
+/**
+ * Orchestration pattern — declarative DI registry + optional dispatcher
+ * scaffold. ADR-032 §"The Proposal" + Decisions 1-8.
+ *
+ * Disjoint from `PatternDefinition` (domain): no columns, no
+ * repository/service base class, no entity-level patternConfig. Composition
+ * with domain patterns happens only at the DI layer in the consumer's
+ * generated code, not in entity YAML.
+ */
+export interface OrchestrationPatternDefinition {
+	name: string;
+	kind: 'orchestration';
+	/** Primary registry (always present). */
+	registry: OrchestrationRegistrySpec;
+	/**
+	 * Sibling registries that share the primary registry's key space.
+	 * ADR-032 Decision 2 — co-keyed groups are a first-class field.
+	 * Validator enforces matching `keyType` across the group.
+	 */
+	coKeyedRegistries?: ReadonlyArray<OrchestrationRegistrySpec>;
+	/** Optional dispatcher scaffold spec (ADR-032 Decision 4 + 5). */
+	dispatcher?: {
+		/** Class name to emit (e.g. `"CrmPortsDispatcher"`). */
+		className: string;
+		/**
+		 * Method name the consumer overrides in their subclass to fill the
+		 * assembly body (ADR-032 Decision 5).
+		 */
+		assemblySlot: string;
+	};
+	/** One-line description for help output and error messages. */
+	description?: string;
+}
+
+/** Union for callers that need to handle both shapes. */
+export type AnyPatternDefinition =
+	| PatternDefinition
+	| OrchestrationPatternDefinition;
+
+export function isOrchestrationPattern(
+	def: AnyPatternDefinition,
+): def is OrchestrationPatternDefinition {
+	return (def as { kind?: PatternKind }).kind === 'orchestration';
+}
+
+export function isDomainPattern(
+	def: AnyPatternDefinition,
+): def is PatternDefinition {
+	return !isOrchestrationPattern(def);
+}
+
+/**
+ * Identity function that returns its argument unchanged — orchestration
+ * counterpart to `definePattern()`. The body is trivial on purpose; the
+ * point is to give TypeScript a hook so consumer fixtures get full
+ * compile-time checking against `OrchestrationPatternDefinition`.
+ */
+export function defineOrchestrationPattern(
+	def: OrchestrationPatternDefinition,
+): OrchestrationPatternDefinition {
+	return def;
+}