@pattern-stack/codegen 0.12.0 → 0.12.2

package/CHANGELOG.md

@@ -4,6 +4,66 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.12.2] — 2026-05-31
+
+Track D consumer-CLI fix. The 0.12.0/0.12.1 generator was correct in the
+hermetic D7 path but broke for real consumers driving it through the CLI. Two
+schema/loader bugs plus a DX gap that masked the first. No swe-brain YAML change
+is required — consumer YAML already wrote the keys in the natural place; the
+schema is now corrected to match.
+
+### Fixed
+
+- **`entity.surface` / `entity.context` schema level.** `surface:` and
+  `context:` were defined at the ROOT of `EntityDefinitionSchema` (sibling of
+  `entity:`/`fields:`), but consumers naturally write them INSIDE the `entity:`
+  block (next to `pattern:`/`name:`/`table:`). Because the `entity:` block is
+  `.strict()`, those YAMLs were rejected with "Unrecognized key(s) in object:
+  'surface' at 'entity'". The fields now live in `EntityConfigSchema` and are
+  read as `entity.surface` / `entity.context`. Clean break — root-level
+  placement no longer validates. Read sites updated:
+  `collectEntitySurfaces` (`validate-providers.ts`), `collectEntitiesBySurface`
+  (`adapter-emission-generator.ts`), the provider surface cross-check
+  (`entity.ts`), and the clean-lite-ps output-subfolder consumer
+  (`prompt-extension.js` `buildCleanLitePsLocals`).
+- **Entity `--all` discovery no longer globs `definitions/providers/`.** With
+  `entities_dir: definitions`, the recursive YAML walk pulled provider files
+  into the entity loader, where they fail entity validation. Entity discovery
+  (`findYamlFiles`, `loadEntities`, `listEntityYamls`) now excludes the
+  configured providers dir (`paths.providers`, default `definitions/providers`).
+  Provider files route only through `ProviderDefinitionSchema`.
+
+### Changed
+
+- **`entity new --dry-run` surfaces the Zod detail.** The failure path printed
+  only "Validation failed for <file>"; it now emits the same per-issue Zod
+  diagnostics as `entity validate`, so a misplaced key reports which key/level
+  is wrong (the DX gap that hid the `entity.surface` rejection).
+
+## [0.12.1] — 2026-05-31
+
+Track D (provider/adapter integration codegen) discoverability fix. The 0.12.0
+generator wiring is correct and shipped — provider + adapter emission runs as a
+post-step of `codegen entity new` whenever `definitions/providers/*.yaml` exist
+— but nothing in the CLI surfaced that, so consumers searched `--help` for a
+`provider` / `integration` / `gen` command, found none, and mistook a working
+feature for a publish gap. Docs-and-help only; no generator behavior changed.
+
+### Changed
+
+- **`codegen entity new --help`** now documents every post-generation step it
+  runs (event / bridge / orchestration / **provider + adapter (Track D)**
+  codegen), including Track D's trigger (`definitions/providers/*.yaml`), output
+  paths (`<backendSrc>/integrations/{providers,}`), emit-once semantics, and an
+  explicit note that there is no standalone `provider` / `integration` / `gen`
+  command — Track D is driven entirely by re-running `entity new`.
+- **`codegen entity` summary hints** now surface a Track D regen hint when the
+  project has a providers directory — a discoverability path that does not
+  require reading `entity new --help`.
+- **Integration domain skill** (`protocols-and-ports.md`, `SKILL.md`) documents
+  the Track D invocation, the skip-when-no-providers-dir behavior, and that the
+  generated scaffold (not the `.d.ts`) is ground truth for adapter port shape.
+
 ## [0.12.0] — 2026-05-31
 
 Integration codegen retarget (RFC-0001): a **provider/adapter/surface** model
@@ -12,8 +72,11 @@ for integration codegen, plus a **surface-package framework**. Additive over
 is unchanged. The one breaking item (the ADR-033.2 per-entity provider tuples)
 has no consumers. Consumers adopt by adding `definitions/providers/*.yaml` and
 regenerating. Ships alongside four independently-versioned **surface packages**
-(`@pattern-stack/codegen-{crm,calendar,mail,transcript}`) publishing fresh at
-`0.1.0`.
+(`@pattern-stack/codegen-{crm,calendar,mail,transcript}`) at `0.1.1`. (Their
+initial `0.1.0` release peer-depended on `@pattern-stack/codegen` `^0.11.0`,
+which predates the `./subsystems` export they require; `0.1.1` corrects the peer
+to `^0.12.0`. The peer source fix merged with 0.12.0 but the version bump was
+missed — this completes it.)
 
 ### ⚠ BREAKING CHANGES
 
@@ -41,7 +104,7 @@ regenerating. Ships alongside four independently-versioned **surface packages**
     conformance helper (on the `/testing` subpath).
   - **`@pattern-stack/codegen-{calendar,mail,transcript}`** — incremental-read
     interaction surfaces (`CalendarPort` / `MailPort` / `TranscriptPort`,
-    canonical types, capability descriptors). Independently versioned (`0.1.0`).
+    canonical types, capability descriptors). Independently versioned (`0.1.1`).
 - **Track D — provider/adapter integration codegen (RFC-0001).**
   - `definitions/providers/<provider>.yaml` — providers as first-class
     declarative artifacts (slug, auth strategy, client, surfaces); Zod schema +

package/dist/src/cli/index.js

@@ -30,14 +30,17 @@ import { join, resolve } from "path";
 function isYaml(name) {
   return name.endsWith(".yaml") || name.endsWith(".yml");
 }
-function findYamlFiles(dir) {
+function findYamlFiles(dir, opts) {
   const root = resolve(dir);
   const out = [];
+  const excluded = new Set((opts?.excludeDirs ?? []).map((d) => resolve(d)));
   const walk = (current) => {
     for (const entry of readdirSync(current, { withFileTypes: true })) {
       if (entry.isDirectory()) {
         if (entry.name.startsWith(".")) continue;
-        walk(join(current, entry.name));
+        const child = join(current, entry.name);
+        if (excluded.has(resolve(child))) continue;
+        walk(child);
       } else if (isYaml(entry.name)) {
         out.push(join(current, entry.name));
       }
@@ -2312,7 +2315,37 @@ var EntityConfigSchema = z3.object({
   // JOB-7: marks this entity as a valid scope target for job scoping.
   // Drives the generated ScopeEntityType union in
   // runtime/subsystems/jobs/generated/scope-entity-type.ts.
-  scopeable: z3.boolean().optional()
+  scopeable: z3.boolean().optional(),
+  // RFC-0001 §1/§8: the integration *surface* this entity belongs to
+  // (e.g. 'calendar', 'mail', 'crm'). Surfaces span provider contexts
+  // (ADR-0006) — one Google OAuth feeds calendar+mail+transcript. The union
+  // of `surface:` values across all entity YAML is the closed set that a
+  // provider's `surfaces:` must be a subset of (cross-checked in
+  // src/parser/validate-providers.ts). Optional: entities without an
+  // integration surface omit it. The surface-package *emission* convention
+  // is Track C (#329); this field is only the declarative input both tracks
+  // read. Lives inside the `entity:` block (next to `pattern:`/`name:`/`table:`).
+  surface: z3.string().optional(),
+  // Bounded-context declaration (ADR-0004) — "which bounded context this
+  // entity belongs to". This is the DURABLE decision; it is a plain
+  // bounded-context slug, NOT a folder knob. Different features consume it:
+  //
+  //   - #403 (the FIRST consumer): drives the generated code's
+  //     module output folder. clean-lite-ps nests the entity's module under
+  //     `<modules>/<context>/<entity>/` so same-context entities group
+  //     together; untagged entities stay flat (`<modules>/<entity>/`).
+  //   - ADR-0004 (deferred): a later `naming: prefix | schema` knob reads
+  //     this SAME field to drive the Postgres physical layout —
+  //     `prefix` → `pgTable('<context>__<table>')`, then the flip to
+  //     `schema` → `pgSchema('<context>').table('<table>')`. NOT wired here.
+  //
+  // Sibling to `surface:` and orthogonal to it (ADR-0006): context = model
+  // cohesion (which domain), surface = vendor composition (which integration).
+  // Lives inside the `entity:` block (next to `pattern:`/`name:`/`table:`).
+  context: z3.string().regex(
+    /^[a-z][a-z0-9_]*$/,
+    "context must be lowercase snake_case (e.g. 'integration')"
+  ).optional()
 }).strict().refine((d) => !(d.pattern && d.patterns), {
   message: "'pattern' and 'patterns' are mutually exclusive"
 });
@@ -2465,36 +2498,11 @@ var EntityDefinitionSchema = z3.object({
   // appear in `integration.providers` — see the superRefine on
   // `EntityDefinitionSchema` below.
   detection: z3.record(z3.string(), DetectionConfigSchema).optional(),
-  // RFC-0001 §1/§8: the integration *surface* this entity belongs to
-  // (e.g. 'calendar', 'mail', 'crm'). Surfaces span provider contexts
-  // (ADR-0006) — one Google OAuth feeds calendar+mail+transcript. The union
-  // of `surface:` values across all entity YAML is the closed set that a
-  // provider's `surfaces:` must be a subset of (cross-checked in
-  // src/parser/validate-providers.ts). Optional: entities without an
-  // integration surface omit it. The surface-package *emission* convention
-  // is Track C (#329); this field is only the declarative input both tracks
-  // read.
-  surface: z3.string().optional(),
-  // Bounded-context declaration (ADR-0004) — "which bounded context this
-  // entity belongs to". This is the DURABLE decision; it is a plain
-  // bounded-context slug, NOT a folder knob. Different features consume it:
-  //
-  //   - #403 (this PR, the FIRST consumer): drives the generated code's
-  //     module output folder. clean-lite-ps nests the entity's module under
-  //     `<modules>/<context>/<entity>/` so same-context entities group
-  //     together; untagged entities stay flat (`<modules>/<entity>/`).
-  //   - ADR-0004 (deferred): a later `naming: prefix | schema` knob reads
-  //     this SAME field to drive the Postgres physical layout —
-  //     `prefix` → `pgTable('<context>__<table>')`, then the flip to
-  //     `schema` → `pgSchema('<context>').table('<table>')`. NOT wired here;
-  //     #403 makes no table/column/schema changes.
-  //
-  // Sibling to `surface:` and orthogonal to it (ADR-0006): context = model
-  // cohesion (which domain), surface = vendor composition (which integration).
-  context: z3.string().regex(
-    /^[a-z][a-z0-9_]*$/,
-    "context must be lowercase snake_case (e.g. 'integration')"
-  ).optional(),
+  // NOTE: `surface:` and `context:` moved INTO EntityConfigSchema (the
+  // `entity:` block) in 0.12.2 — consumers write them next to
+  // `pattern:`/`name:`/`table:`, which is the natural place. They are
+  // read via `entity.surface` / `entity.context`. Clean break: no
+  // root-level placement is accepted.
   // v2: Domain event declarations (CODEGEN-EVOLUTION-PLAN Phase 2)
   // Generates typed event classes, handlers, and queue registration
   events: z3.array(EventDeclarationSchema).optional(),
@@ -3409,13 +3417,13 @@ function loadErrorToIssue(error) {
   }
   return issues;
 }
-function loadEntities(entitiesDir) {
+function loadEntities(entitiesDir, opts) {
   const entities = [];
   const issues = [];
   const resolvedDir = resolve2(entitiesDir);
   let files;
   try {
-    files = findYamlFiles(resolvedDir);
+    files = findYamlFiles(resolvedDir, { excludeDirs: opts?.excludeDirs });
   } catch (err) {
     issues.push({
       severity: "error",
@@ -3650,7 +3658,7 @@ import ts from "typescript";
 function collectEntitySurfaces(entities) {
   const surfaces = /* @__PURE__ */ new Set();
   for (const e of entities) {
-    if (e.surface) surfaces.add(e.surface);
+    if (e.entity.surface) surfaces.add(e.entity.surface);
   }
   return surfaces;
 }
@@ -6019,8 +6027,8 @@ function collectEntities(entitiesDir) {
     entities.push({
       name: def.entity.name,
       plural: def.entity.plural,
-      // #403: top-level `context:` nests the module folder; undefined → flat.
-      context: def.context
+      // #403: `entity.context:` nests the module folder; undefined → flat.
+      context: def.entity.context
     });
   }
   entities.sort((a, b) => a.name.localeCompare(b.name));
@@ -8297,10 +8305,11 @@ function generatedBanner(sourceDesc) {
 function collectEntitiesBySurface(entities) {
   const bySurface = /* @__PURE__ */ new Map();
   for (const e of entities) {
-    if (!e.surface) continue;
-    const list = bySurface.get(e.surface) ?? [];
+    const surface = e.entity.surface;
+    if (!surface) continue;
+    const list = bySurface.get(surface) ?? [];
     list.push(e.entity.name);
-    bySurface.set(e.surface, list);
+    bySurface.set(surface, list);
   }
   for (const [surface, list] of bySurface) {
     bySurface.set(surface, [...list].sort());
@@ -8668,9 +8677,15 @@ function printInfo(msg) {
 }
 
 // src/cli/commands/entity.ts
-function listEntityYamls2(dir) {
+function resolveProvidersDir(ctx) {
+  const fromConfig = ctx.config?.paths?.providers;
+  return fromConfig != null ? path13.resolve(ctx.cwd, fromConfig) : path13.resolve(ctx.cwd, "definitions/providers");
+}
+function listEntityYamls2(dir, providersDir) {
   if (!fs9.existsSync(dir)) return [];
-  return findYamlFiles(dir);
+  return findYamlFiles(dir, {
+    excludeDirs: providersDir ? [providersDir] : []
+  });
 }
 function summarizePatternLabel(entity) {
   if (typeof entity.pattern === "string" && entity.pattern.length > 0) {
@@ -8709,7 +8724,7 @@ async function summary(ctx) {
       ]
     };
   }
-  const files = listEntityYamls2(ctx.entitiesDir);
+  const files = listEntityYamls2(ctx.entitiesDir, resolveProvidersDir(ctx));
   const rows = files.map(summarizeEntityFile).filter((r) => r !== null);
   const patterns = new Set(rows.map((r) => r.pattern));
   const queryCount = rows.reduce((sum, r) => sum + r.queries, 0);
@@ -8740,20 +8755,45 @@ async function hints(ctx) {
       }
     ];
   }
-  return [
+  const baseHints = [
     { command: "codegen entity new <file>", description: "Generate one entity" },
     { command: "codegen entity new --all", description: "Regenerate all entities" },
     { command: "codegen entity validate", description: "Validate YAML definitions" },
     { command: "codegen entity list", description: "List entities as a table" }
   ];
+  const providersDir = ctx.config?.paths?.providers != null ? path13.resolve(
+    ctx.cwd,
+    ctx.config.paths.providers
+  ) : path13.resolve(ctx.cwd, "definitions/providers");
+  if (fs9.existsSync(providersDir)) {
+    baseHints.push({
+      command: "codegen entity new --all",
+      description: "Regenerate provider modules + adapter scaffolds (Track D)"
+    });
+  }
+  return baseHints;
 }
 var EntityNewCommand = class extends Command2 {
   static paths = [["entity", "new"]];
   static usage = Command2.Usage({
     description: "Generate code for one or more entities from YAML",
+    details: `
+			Generates Clean Architecture code for the named entity (or all entities with \`--all\`), then runs the post-generation codegen steps that share this entrypoint:
+
+			- **Event codegen** \u2014 \`AppDomainEvent\` union + typed bus from \`events/*.yaml\`.
+			- **Bridge registry** \u2014 when the bridge subsystem is installed.
+			- **Orchestration modules** \u2014 from orchestration patterns.
+			- **Provider + adapter codegen (Track D, RFC-0001)** \u2014 when \`definitions/providers/*.yaml\` exist, emits one provider module per file into \`<backendSrc>/integrations/providers/\` and the matching adapter scaffolds + \`@generated\` files into \`<backendSrc>/integrations/\`. Author-owned scaffolds are emit-once (never overwritten); \`@generated\` files re-emit each run. With no providers dir the step is silently skipped.
+
+			There is no separate \`provider\`, \`integration\`, or \`gen\` command \u2014 Track D codegen is driven entirely by re-running \`entity new\`. The \`just gen\` / \`just gen-all\` recipes are thin wrappers over it.
+		`,
     examples: [
       ["Generate a single entity", "codegen entity new entities/contact.yaml"],
       ["Regenerate all entities", "codegen entity new --all"],
+      [
+        "Regenerate everything incl. provider/adapter codegen",
+        "codegen entity new --all"
+      ],
       ["Preview without writing", "codegen entity new entities/contact.yaml --dry-run"]
     ]
   });
@@ -8781,7 +8821,7 @@ var EntityNewCommand = class extends Command2 {
     let targets = [];
     if (this.all) {
       const dir = ctx.entitiesDir ?? path13.resolve(ctx.cwd, "entities");
-      targets = listEntityYamls2(dir);
+      targets = listEntityYamls2(dir, resolveProvidersDir(ctx));
       if (targets.length === 0) {
         printError(`No entity YAML files found in ${dir}`);
         return 1;
@@ -8799,12 +8839,15 @@ var EntityNewCommand = class extends Command2 {
       if (result.success) {
         validated.push({ file, name: result.definition.entity.name });
       } else {
-        invalid.push({ file, message: result.error });
+        invalid.push({ file, message: result.error, details: result.details });
       }
     }
     if (invalid.length > 0 && !this.continueOnError) {
       for (const i of invalid) {
         printError(`${path13.basename(i.file)} \u2014 ${i.message}`);
+        for (const detail of i.details ?? []) {
+          printError(`   \u2022 ${detail}`);
+        }
       }
       if (!isJsonMode()) {
         return 1;
@@ -8812,7 +8855,9 @@ var EntityNewCommand = class extends Command2 {
     }
     const entitiesDirForEmits = ctx.entitiesDir ?? path13.resolve(ctx.cwd, "entities");
     const eventsDirForEmits = resolveEventsDir(ctx);
-    const allEntitiesForEmits = loadEntities(entitiesDirForEmits).entities;
+    const allEntitiesForEmits = loadEntities(entitiesDirForEmits, {
+      excludeDirs: [resolveProvidersDir(ctx)]
+    }).entities;
     const validatedNames = new Set(validated.map((v) => v.name));
     const emitsTargetEntities = allEntitiesForEmits.filter(
       (e) => validatedNames.has(e.name)
@@ -9144,19 +9189,16 @@ var EntityNewCommand = class extends Command2 {
     }
     let providerResult = null;
     try {
-      const providersDir = ctx.config?.paths?.providers != null ? path13.resolve(
-        ctx.cwd,
-        ctx.config.paths.providers
-      ) : path13.resolve(ctx.cwd, "definitions/providers");
+      const providersDir = resolveProvidersDir(ctx);
       const providerOutputRoot = path13.resolve(
         ctx.cwd,
         backendSrcForHandlers,
         "integrations/providers"
       );
       const entitySurfaces = fs9.existsSync(entitiesDir) ? collectEntitySurfaces(
-        loadEntitiesFromYaml(findYamlFiles(entitiesDir)).successes.map(
-          (s) => s.definition
-        )
+        loadEntitiesFromYaml(
+          findYamlFiles(entitiesDir, { excludeDirs: [providersDir] })
+        ).successes.map((s) => s.definition)
       ) : /* @__PURE__ */ new Set();
       const tsAliases = resolveTsconfigAliases(ctx.cwd);
       providerResult = generateProviderModules({
@@ -9194,9 +9236,9 @@ var EntityNewCommand = class extends Command2 {
           backendSrcForHandlers,
           "integrations"
         );
-        const entityDefs = fs9.existsSync(entitiesDir) ? loadEntitiesFromYaml(findYamlFiles(entitiesDir)).successes.map(
-          (s) => s.definition
-        ) : [];
+        const entityDefs = fs9.existsSync(entitiesDir) ? loadEntitiesFromYaml(
+          findYamlFiles(entitiesDir, { excludeDirs: [providersDir] })
+        ).successes.map((s) => s.definition) : [];
         const loadedProviders = loadProvidersFromYaml(
           findYamlFiles(providersDir)
         ).successes.map((s) => ({
@@ -9342,7 +9384,7 @@ var EntityListCommand = class extends Command2 {
       printError("No entities directory found.");
       return 1;
     }
-    const files = listEntityYamls2(ctx.entitiesDir);
+    const files = listEntityYamls2(ctx.entitiesDir, resolveProvidersDir(ctx));
     const rows = files.map(summarizeEntityFile).filter((r) => r !== null).filter((r) => this.pattern ? r.pattern === this.pattern : true);
     if (isJsonMode()) {
       printJson({