@intentius/chant-lexicon-temporal 0.1.5 → 0.1.8

package/src/op/serializer.ts

@@ -0,0 +1,349 @@
+/**
+ * Op serializer — generates Temporal workflow, worker, and activities files
+ * for each Temporal::Op entity.
+ *
+ * For an Op named "alb-deploy" it emits three files under dist/ops/alb-deploy/:
+ *   workflow.ts   — the Temporal workflow function
+ *   activities.ts — re-exports from the pre-built activity library
+ *   worker.ts     — bootstrap worker that reads chant.config.ts
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep } from "@intentius/chant/op";
+
+// ── Name helpers ──────────────────────────────────────────────────────────────
+
+function kebabToCamel(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+function workflowFnName(opName: string): string {
+  return kebabToCamel(opName) + "Workflow";
+}
+
+function signalVarName(signalName: string): string {
+  // "gate-dns-delegation" → "resumeDnsDelegation"
+  const withoutGate = signalName.startsWith("gate-") ? signalName.slice(5) : signalName;
+  return "resume" + kebabToCamel(withoutGate).replace(/^./, (c) => c.toUpperCase());
+}
+
+// ── Type helpers ──────────────────────────────────────────────────────────────
+
+function isActivityStep(s: StepDefinition): s is ActivityStep {
+  return s.kind === "activity";
+}
+
+function isGateStep(s: StepDefinition): s is GateStep {
+  return s.kind === "gate";
+}
+
+function effectiveProfile(step: ActivityStep): string {
+  return step.profile ?? "fastIdempotent";
+}
+
+// ── Workflow code generation ──────────────────────────────────────────────────
+
+function collectActivitySteps(phases: PhaseDefinition[]): ActivityStep[] {
+  return phases.flatMap((p) => p.steps.filter(isActivityStep));
+}
+
+function groupByProfile(steps: ActivityStep[]): Map<string, Set<string>> {
+  const map = new Map<string, Set<string>>();
+  for (const step of steps) {
+    const prof = effectiveProfile(step);
+    if (!map.has(prof)) map.set(prof, new Set());
+    map.get(prof)!.add(step.fn);
+  }
+  return map;
+}
+
+function generateWorkflow(config: OpConfig): string {
+  const allActivitySteps = [
+    ...collectActivitySteps(config.phases),
+    ...(config.onFailure ? collectActivitySteps(config.onFailure) : []),
+  ];
+
+  const byProfile = groupByProfile(allActivitySteps);
+
+  const allGateSteps = [
+    ...config.phases.flatMap((p) => p.steps.filter(isGateStep)),
+    ...(config.onFailure ?? []).flatMap((p) => p.steps.filter(isGateStep)),
+  ];
+
+  const fnName = workflowFnName(config.name);
+
+  const lines: string[] = [
+    "// Generated by chant — do not edit directly.",
+    `// Source: ${config.name}.op.ts`,
+    "import { proxyActivities, condition, defineSignal, setHandler, upsertSearchAttributes } from '@temporalio/workflow';",
+    "import { TEMPORAL_ACTIVITY_PROFILES } from '@intentius/chant-lexicon-temporal';",
+    "import type * as activities from './activities';",
+    "",
+  ];
+
+  // proxyActivities per profile
+  if (byProfile.size === 0) {
+    lines.push("// No activities defined.");
+    lines.push("");
+  } else {
+    for (const [prof, fns] of byProfile) {
+      const destructured = [...fns].join(", ");
+      lines.push(`const { ${destructured} } = proxyActivities<typeof activities>(`);
+      lines.push(`  TEMPORAL_ACTIVITY_PROFILES.${prof},`);
+      lines.push(`);`);
+    }
+    lines.push("");
+  }
+
+  // Gate signals declarations
+  if (allGateSteps.length > 0) {
+    for (const gate of allGateSteps) {
+      const varName = signalVarName(gate.signalName);
+      lines.push(`const ${varName} = defineSignal<[]>(${JSON.stringify(gate.signalName)});`);
+    }
+    lines.push("");
+  }
+
+  // Workflow function
+  lines.push(`export async function ${fnName}(): Promise<void> {`);
+
+  // Initial search attributes — OpName plus any user-provided attrs.
+  // Each value is wrapped in a single-element array (classic
+  // upsertSearchAttributes API takes arrays).
+  const initialAttrs: Record<string, string[]> = {
+    OpName: [config.name],
+  };
+  for (const [k, v] of Object.entries(config.searchAttributes ?? {})) {
+    initialAttrs[k] = [v];
+  }
+  lines.push(`  upsertSearchAttributes(${JSON.stringify(initialAttrs)});`);
+  lines.push("");
+
+  // Counter for outcome-attribute capture variables (workflow-scoped).
+  let resultCounter = 0;
+  const nextResultVar = (): string => `__r${resultCounter++}`;
+
+  // Build a `String(<var>?.<from-path>)` fragment from a dot-path.
+  const stringifyFromPath = (varName: string, from?: string): string => {
+    if (!from) return `String(${varName})`;
+    const parts = from.split(".");
+    return `String(${varName}?.${parts.join("?.")})`;
+  };
+
+  // Emit `upsertSearchAttributes({ <name>: [<expr>] })` for an outcome attr.
+  const emitOutcomeUpsert = (
+    step: ActivityStep,
+    varName: string,
+    indent = "  ",
+  ): string | null => {
+    if (!step.outcomeAttribute) return null;
+    const { name, from } = step.outcomeAttribute;
+    return `${indent}upsertSearchAttributes({ ${JSON.stringify(name)}: [${stringifyFromPath(varName, from)}] });`;
+  };
+
+  const renderPhases = (phases: PhaseDefinition[]) => {
+    for (const phase of phases) {
+      const phaseLines: string[] = [];
+      phaseLines.push(`  // Phase: ${phase.name}`);
+      phaseLines.push(`  upsertSearchAttributes({ Phase: ${JSON.stringify([phase.name])} });`);
+
+      const activitySteps = phase.steps.filter(isActivityStep);
+      const gateSteps = phase.steps.filter(isGateStep);
+
+      if (phase.parallel && activitySteps.length > 1) {
+        // Capture results into an array if any step has an outcome attribute,
+        // otherwise just await Promise.all without the destructure.
+        const anyOutcome = activitySteps.some((s) => s.outcomeAttribute);
+        if (anyOutcome) {
+          const vars = activitySteps.map(() => nextResultVar());
+          phaseLines.push(`  const [${vars.join(", ")}] = await Promise.all([`);
+          for (let i = 0; i < activitySteps.length; i++) {
+            const step = activitySteps[i];
+            const argsStr = step.args && Object.keys(step.args).length > 0
+              ? JSON.stringify(step.args)
+              : "{}";
+            phaseLines.push(`    ${step.fn}(${argsStr}),`);
+          }
+          phaseLines.push("  ]);");
+          for (let i = 0; i < activitySteps.length; i++) {
+            const upsert = emitOutcomeUpsert(activitySteps[i], vars[i]);
+            if (upsert) phaseLines.push(upsert);
+          }
+        } else {
+          phaseLines.push("  await Promise.all([");
+          for (const step of activitySteps) {
+            const argsStr = step.args && Object.keys(step.args).length > 0
+              ? JSON.stringify(step.args)
+              : "{}";
+            phaseLines.push(`    ${step.fn}(${argsStr}),`);
+          }
+          phaseLines.push("  ]);");
+        }
+      } else {
+        for (const step of activitySteps) {
+          const argsStr = step.args && Object.keys(step.args).length > 0
+            ? JSON.stringify(step.args)
+            : "{}";
+          if (step.outcomeAttribute) {
+            const v = nextResultVar();
+            phaseLines.push(`  const ${v} = await ${step.fn}(${argsStr});`);
+            const upsert = emitOutcomeUpsert(step, v);
+            if (upsert) phaseLines.push(upsert);
+          } else {
+            phaseLines.push(`  await ${step.fn}(${argsStr});`);
+          }
+        }
+      }
+
+      for (const gateStep of gateSteps) {
+        const varName = signalVarName(gateStep.signalName);
+        const timeout = gateStep.timeout ?? "48h";
+        if (gateStep.description) {
+          phaseLines.push(`  // Gate: ${gateStep.signalName} — ${gateStep.description}`);
+        } else {
+          phaseLines.push(`  // Gate: ${gateStep.signalName}`);
+        }
+        phaseLines.push(`  let ${varName}Cleared = false;`);
+        phaseLines.push(`  setHandler(${varName}, () => { ${varName}Cleared = true; });`);
+        phaseLines.push(`  await condition(() => ${varName}Cleared, ${JSON.stringify(timeout)});`);
+      }
+
+      lines.push(...phaseLines);
+      lines.push("");
+    }
+  };
+
+  renderPhases(config.phases);
+
+  if (config.onFailure && config.onFailure.length > 0) {
+    lines.push("  // onFailure compensation (executed on terminal failure only)");
+    renderPhases(config.onFailure);
+  }
+
+  lines.push("}");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+// ── Activities re-export ──────────────────────────────────────────────────────
+
+function generateActivities(): string {
+  return [
+    "// Generated by chant — do not edit directly.",
+    "// Re-exports all pre-built activity implementations.",
+    "export * from '@intentius/chant-lexicon-temporal/op/activities';",
+    "",
+  ].join("\n");
+}
+
+// ── Worker bootstrap ──────────────────────────────────────────────────────────
+
+function generateWorker(config: OpConfig): string {
+  const taskQueue = config.taskQueue ?? config.name;
+
+  return [
+    "// Generated by chant — do not edit directly.",
+    `// Run: npx tsx ops/${config.name}/worker.ts`,
+    "import { Worker, NativeConnection } from '@temporalio/worker';",
+    "import { fileURLToPath } from 'url';",
+    "import * as activities from './activities.js';",
+    "",
+    "async function run(): Promise<void> {",
+    "  const { default: chantConfig } = await import('../../chant.config.js');",
+    "",
+    `  const profileName = process.env.TEMPORAL_PROFILE ?? chantConfig.temporal?.defaultProfile ?? 'local';`,
+    "  const profile = chantConfig.temporal?.profiles?.[profileName];",
+    "",
+    "  if (!profile) {",
+    "    console.error(",
+    `      \`Unknown Temporal profile "\${profileName}". Available: \${Object.keys(chantConfig.temporal?.profiles ?? {}).join(', ')}\`,`,
+    "    );",
+    "    process.exit(1);",
+    "  }",
+    "",
+    "  const apiKey =",
+    "    typeof profile.apiKey === 'object' && profile.apiKey !== null",
+    "      ? process.env[(profile.apiKey as { env: string }).env]",
+    "      : (profile.apiKey as string | undefined);",
+    "",
+    "  const connection = await NativeConnection.connect({",
+    "    address: profile.address,",
+    "    ...(profile.tls && {",
+    "      tls: typeof profile.tls === 'object' ? profile.tls : {},",
+    "      metadata: apiKey ? { Authorization: `Bearer ${apiKey}` } : {},",
+    "    }),",
+    "  });",
+    "",
+    "  const worker = await Worker.create({",
+    "    connection,",
+    "    namespace: profile.namespace,",
+    `    taskQueue: profile.taskQueue ?? ${JSON.stringify(taskQueue)},`,
+    "    workflowsPath: fileURLToPath(new URL('./workflow.js', import.meta.url)),",
+    "    activities,",
+    "  });",
+    "",
+    `  console.log(\`Worker ready — polling task queue: \${profile.taskQueue ?? ${JSON.stringify(taskQueue)}}\`);`,
+    "  await worker.run();",
+    "}",
+    "",
+    "run().catch((err: unknown) => {",
+    "  console.error(err);",
+    "  process.exit(1);",
+    "});",
+    "",
+  ].join("\n");
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+function getProps(entity: Declarable): Record<string, unknown> {
+  if ("props" in entity && typeof entity.props === "object" && entity.props !== null) {
+    return entity.props as Record<string, unknown>;
+  }
+  return {};
+}
+
+/**
+ * Serialize a map of Temporal::Op entities into generated file content.
+ *
+ * Returns a map of relative output paths → file content.
+ * e.g. `{ "ops/alb-deploy/workflow.ts": "...", ... }`
+ *
+ * Throws if a `depends` reference names an Op that is not in the entity map.
+ */
+export function serializeOps(ops: Map<string, Declarable>): Record<string, string> {
+  const knownNames = new Set<string>();
+
+  // First pass: collect all names
+  for (const [, entity] of ops) {
+    const props = getProps(entity) as OpConfig;
+    if (props.name) knownNames.add(props.name);
+  }
+
+  const files: Record<string, string> = {};
+
+  for (const [, entity] of ops) {
+    const config = getProps(entity) as OpConfig;
+
+    if (!config.name) {
+      throw new Error("Op entity missing required `name` field.");
+    }
+
+    // Validate depends
+    for (const dep of config.depends ?? []) {
+      if (!knownNames.has(dep)) {
+        throw new Error(
+          `Op "${config.name}" depends on unknown Op "${dep}". Known Ops: ${[...knownNames].join(", ")}`,
+        );
+      }
+    }
+
+    const dir = `ops/${config.name}`;
+    files[`${dir}/workflow.ts`] = generateWorkflow(config);
+    files[`${dir}/activities.ts`] = generateActivities();
+    files[`${dir}/worker.ts`] = generateWorker(config);
+  }
+
+  return files;
+}

package/src/plugin.test.ts

@@ -32,7 +32,7 @@ describe("temporal plugin", () => {
     const tools = temporalPlugin.mcpTools?.();
     expect(Array.isArray(tools)).toBe(true);
     expect(tools?.length).toBe(1);
-    expect(tools?.[0].name).toBe("diff");
+    expect(tools?.[0].name).toBe("temporal:diff");
   });
 
   it("mcpResources() returns at least 2 resources including resource-catalog", () => {
@@ -40,7 +40,7 @@ describe("temporal plugin", () => {
     expect(Array.isArray(resources)).toBe(true);
     expect((resources?.length ?? 0)).toBeGreaterThanOrEqual(2);
     const uris = resources?.map((r) => r.uri);
-    expect(uris).toContain("resource-catalog");
+    expect(uris).toContain("temporal:resource-catalog");
   });
 
   it("skills() returns 2 skill entries", () => {

package/src/plugin.ts

@@ -103,6 +103,7 @@ export const temporalPlugin: LexiconPlugin = {
       createDiffTool(
         temporalSerializer,
         "Compare current Temporal build output (docker-compose.yml, temporal-setup.sh, schedules/) against previous version",
+        "temporal",
       ),
     ];
   },
@@ -114,6 +115,7 @@ export const temporalPlugin: LexiconPlugin = {
         "Temporal Resource Types",
         "All supported Temporal resource types: TemporalServer, TemporalNamespace, SearchAttribute, TemporalSchedule",
         "lexicon-temporal.json",
+        "temporal",
       ),
       {
         uri: "examples/dev-server",
@@ -283,4 +285,9 @@ export const temporalPlugin: LexiconPlugin = {
     const { generateDocs } = await import("./codegen/docs");
     return generateDocs(options);
   },
+
+  async describeResources(options) {
+    const { describeResources } = await import("./describe-resources");
+    return describeResources(options);
+  },
 };

package/src/serializer.test.ts

@@ -289,4 +289,43 @@ describe("temporal serializer", () => {
     const result = temporalSerializer.serialize(entities) as { primary: string; files: Record<string, string> };
     expect(result.files["temporal-setup.sh"]).toContain("set -euo pipefail");
   });
+
+  // ── Temporal::Op ──────────────────────────────────────────────────
+
+  function makeOp(name: string, phases: unknown[] = []): [string, Record<string, unknown>] {
+    return [name, makeEntity("Temporal::Op", { name, overview: `${name} op`, phases })];
+  }
+
+  it("includes ops/<name>/workflow.ts when an Op entity is present", () => {
+    const entities = new Map([makeOp("alb-deploy")]);
+    const result = temporalSerializer.serialize(entities) as { primary: string; files: Record<string, string> };
+    expect(typeof result).toBe("object");
+    expect(result.files["ops/alb-deploy/workflow.ts"]).toBeDefined();
+  });
+
+  it("includes ops/<name>/activities.ts and worker.ts for each Op", () => {
+    const entities = new Map([makeOp("my-op")]);
+    const result = temporalSerializer.serialize(entities) as { primary: string; files: Record<string, string> };
+    expect(result.files["ops/my-op/activities.ts"]).toBeDefined();
+    expect(result.files["ops/my-op/worker.ts"]).toBeDefined();
+  });
+
+  it("still returns SerializerResult (not plain string) when only Op entities present", () => {
+    const entities = new Map([makeOp("op")]);
+    const result = temporalSerializer.serialize(entities);
+    expect(typeof result).toBe("object");
+  });
+
+  it("combines Op files with schedule and namespace files in mixed entities", () => {
+    const entities = new Map([
+      makeServer(),
+      makeNamespace("default"),
+      makeSchedule("weekly"),
+      makeOp("deploy-op"),
+    ]);
+    const result = temporalSerializer.serialize(entities) as { primary: string; files: Record<string, string> };
+    expect(result.files["ops/deploy-op/workflow.ts"]).toBeDefined();
+    expect(result.files["temporal-setup.sh"]).toBeDefined();
+    expect(result.files["schedules/weekly.ts"]).toBeDefined();
+  });
 });

package/src/serializer.ts

@@ -14,6 +14,7 @@
 import type { Declarable } from "@intentius/chant/declarable";
 import type { Serializer, SerializerResult } from "@intentius/chant/serializer";
 import type { TemporalServerProps, TemporalNamespaceProps, SearchAttributeProps, TemporalScheduleProps } from "./resources";
+import { serializeOps } from "./op/serializer";
 
 // ── Helpers ─────────────────────────────────────────────────────────
 
@@ -263,6 +264,7 @@ export const temporalSerializer: Serializer = {
     const namespaces = new Map<string, Declarable>();
     const searchAttrs = new Map<string, Declarable>();
     const schedules = new Map<string, Declarable>();
+    const ops = new Map<string, Declarable>();
 
     for (const [name, entity] of entities) {
       const et = entityType(entity);
@@ -270,21 +272,17 @@ export const temporalSerializer: Serializer = {
       else if (et === "Temporal::Namespace") namespaces.set(name, entity);
       else if (et === "Temporal::SearchAttribute") searchAttrs.set(name, entity);
       else if (et === "Temporal::Schedule") schedules.set(name, entity);
+      else if (et === "Temporal::Op") ops.set(name, entity);
     }
 
     const primary = serializeDockerCompose(servers);
 
-    const hasExtraFiles =
-      servers.size > 0 ||   // always emit helm-values when a server exists
-      namespaces.size > 0 ||
-      searchAttrs.size > 0 ||
-      schedules.size > 0;
-
-    // Only-server case: no extra files needed beyond docker-compose → return string
+    // Only-server case with no Ops: no extra files needed beyond docker-compose → return string
     if (
       namespaces.size === 0 &&
       searchAttrs.size === 0 &&
-      schedules.size === 0
+      schedules.size === 0 &&
+      ops.size === 0
     ) {
       return primary;
     }
@@ -305,6 +303,10 @@ export const temporalSerializer: Serializer = {
       files[`schedules/${scheduleId}.ts`] = serializeSchedule(scheduleId, props);
     }
 
+    if (ops.size > 0) {
+      Object.assign(files, serializeOps(ops));
+    }
+
     return { primary, files };
   },
 };