feat(codegen-ts): JSON template-spec shape + parser + schema (CLI-port contract)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LuZWKnWzYGVnESijL7uuky

Author: dmealing

server/typescript/packages/codegen-ts/src/template-codegen/template-spec.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://metaobjects.dev/schema/template-spec.json",
+  "title": "MetaObjects template-codegen spec",
+  "description": "Declarative Mustache template-generator spec (SP-1). Consumed by the CLI ports (C#/Python) and TS.",
+  "type": "object",
+  "required": ["generators"],
+  "additionalProperties": false,
+  "properties": {
+    "generators": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "template", "scope", "outputPattern"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "template": { "type": "string", "minLength": 1 },
+          "scope": { "enum": ["perEntity", "perPackage", "perModel"] },
+          "outputPattern": { "type": "string", "minLength": 1 },
+          "format": { "enum": ["text", "html", "xml", "csv", "json", "markdown", "spreadsheet"] },
+          "target": { "type": "string", "minLength": 1 }
+        }
+      }
+    }
+  }
+}

server/typescript/packages/codegen-ts/src/template-codegen/template-spec.ts

@@ -0,0 +1,67 @@
+// The declarative JSON template-spec the CLI ports (C#/Python) consume, and TS
+// can spread into `generators`. The JSON shape is the cross-port contract
+// (SP-1 §4); a JSON Schema (template-spec.schema.json) sits beside it.
+import type { RenderFormat } from "@metaobjectsdev/render";
+import type { Generator } from "../generator.js";
+import { templateGenerator, type TemplateScope } from "../generators/template-generator.js";
+
+const SCOPES = ["perEntity", "perPackage", "perModel"] as const satisfies readonly TemplateScope[];
+
+export interface TemplateSpecEntry {
+  name: string;
+  template: string;
+  scope: TemplateScope;
+  outputPattern: string;
+  format?: RenderFormat;
+  target?: string;
+}
+export interface TemplateSpecFile { generators: TemplateSpecEntry[]; }
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Validate + narrow an untyped JSON value into a TemplateSpecFile. Throws on
+ *  any shape violation (missing/empty required string, bad scope, non-object). */
+export function parseTemplateSpec(json: unknown): TemplateSpecFile {
+  if (!isRecord(json) || !Array.isArray(json.generators)) {
+    throw new Error("template-spec: expected an object with a `generators` array");
+  }
+  const generators = json.generators.map((raw, i): TemplateSpecEntry => {
+    if (!isRecord(raw)) throw new Error(`template-spec generators[${i}]: expected an object`);
+    for (const key of ["name", "template", "scope", "outputPattern"] as const) {
+      if (typeof raw[key] !== "string" || raw[key] === "") {
+        throw new Error(`template-spec generators[${i}]: missing or empty required string '${key}'`);
+      }
+    }
+    if (!SCOPES.includes(raw.scope as TemplateScope)) {
+      throw new Error(
+        `template-spec generators[${i}]: scope must be one of ${SCOPES.join(" | ")}, got '${String(raw.scope)}'`,
+      );
+    }
+    const entry: TemplateSpecEntry = {
+      name: raw.name as string,
+      template: raw.template as string,
+      scope: raw.scope as TemplateScope,
+      outputPattern: raw.outputPattern as string,
+    };
+    if (typeof raw.format === "string") entry.format = raw.format as RenderFormat;
+    if (typeof raw.target === "string") entry.target = raw.target;
+    return entry;
+  });
+  return { generators };
+}
+
+/** Map a parsed spec into runnable Generators (one templateGenerator per entry). */
+export function templateSpecToGenerators(spec: TemplateSpecFile): Generator[] {
+  return spec.generators.map((e) =>
+    templateGenerator({
+      name: e.name,
+      template: e.template,
+      scope: e.scope,
+      outputPattern: e.outputPattern,
+      ...(e.format !== undefined ? { format: e.format } : {}),
+      ...(e.target !== undefined ? { target: e.target } : {}),
+    }),
+  );
+}

server/typescript/packages/codegen-ts/test/template-codegen/template-spec.test.ts

@@ -0,0 +1,45 @@
+import { describe, test, expect } from "bun:test";
+import { parseTemplateSpec, templateSpecToGenerators } from "../../src/template-codegen/template-spec.js";
+import schema from "../../src/template-codegen/template-spec.schema.json" with { type: "json" };
+
+const VALID = {
+  generators: [
+    { name: "svc", template: "service/entity", scope: "perEntity", outputPattern: "{name}.service.ts" },
+    { name: "reg", template: "app/registry", scope: "perModel", outputPattern: "registry.ts", format: "text" },
+  ],
+};
+
+describe("parseTemplateSpec", () => {
+  test("accepts a valid spec", () => {
+    const spec = parseTemplateSpec(VALID);
+    expect(spec.generators.length).toBe(2);
+    expect(spec.generators[0]!.scope).toBe("perEntity");
+    expect(spec.generators[1]!.format).toBe("text");
+  });
+  test("rejects an unknown scope", () => {
+    expect(() => parseTemplateSpec({ generators: [{ name: "x", template: "t", scope: "perThing", outputPattern: "x" }] }))
+      .toThrow(/scope/i);
+  });
+  test("rejects a missing required field", () => {
+    expect(() => parseTemplateSpec({ generators: [{ name: "x", template: "t", scope: "perModel" }] }))
+      .toThrow(/outputPattern/i);
+  });
+  test("rejects a non-object", () => {
+    expect(() => parseTemplateSpec(null)).toThrow();
+  });
+});
+
+describe("templateSpecToGenerators", () => {
+  test("maps each entry to a Generator with the entry name", () => {
+    const gens = templateSpecToGenerators(parseTemplateSpec(VALID));
+    expect(gens.map((g) => g.name)).toEqual(["svc", "reg"]);
+  });
+});
+
+describe("schema ↔ parser drift", () => {
+  test("schema enumerates the same scopes the parser accepts", () => {
+    const scopeEnum = (schema as { properties: { generators: { items: { properties: { scope: { enum: string[] } } } } } })
+      .properties.generators.items.properties.scope.enum;
+    expect(scopeEnum).toEqual(["perEntity", "perPackage", "perModel"]);
+  });
+});