@intentius/chant-lexicon-temporal 0.1.6 → 0.1.8

package/src/describe-resources.ts

@@ -0,0 +1,300 @@
+/**
+ * Live introspection of a Temporal cluster — implements the
+ * LexiconPlugin.describeResources() contract for the temporal lexicon.
+ *
+ * Connects to the cluster identified by the chant config profile that
+ * matches the current environment (falls back to defaultProfile), then lists:
+ *   - Namespaces        via workflowService.listNamespaces
+ *   - SearchAttributes  via operatorService.listSearchAttributes (per namespace)
+ *   - Schedules         via scheduleClient.list (per namespace)
+ *
+ * Results are keyed by server-side identifier (e.g. "namespace/prod",
+ * "searchAttribute/prod/Project", "schedule/prod/daily-report"). Mapping back
+ * to chant entity names is a separate concern (would need entity props passed
+ * through the plugin contract).
+ */
+
+import { loadChantConfig } from "@intentius/chant/config";
+import {
+  loadTemporalClient,
+  connectionOptions,
+  resolveProfile,
+  type WorkerProfile,
+} from "@intentius/chant/cli/handlers/run-client";
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+
+interface NamespaceListResponse {
+  namespaces?: Array<{
+    namespaceInfo?: {
+      name?: string;
+      state?: number | string;
+      description?: string;
+      ownerEmail?: string;
+    } | null;
+    config?: {
+      workflowExecutionRetentionTtl?: { seconds?: number | bigint | { toNumber(): number } } | null;
+    } | null;
+    isGlobalNamespace?: boolean;
+  }>;
+  nextPageToken?: Uint8Array | null;
+}
+
+interface SearchAttributesResponse {
+  customAttributes?: Record<string, number | string> | null;
+  systemAttributes?: Record<string, number | string> | null;
+}
+
+interface ScheduleSummary {
+  scheduleId?: string;
+  spec?: { cronExpressions?: string[] } | null;
+  action?: { type?: string; workflowType?: string } | null;
+  state?: { paused?: boolean; note?: string } | null;
+}
+
+interface RichConnection {
+  workflowService: {
+    listNamespaces(req: { pageSize?: number; nextPageToken?: Uint8Array }): Promise<NamespaceListResponse>;
+  };
+  operatorService: {
+    listSearchAttributes(req: { namespace: string }): Promise<SearchAttributesResponse>;
+  };
+  close?(): Promise<void>;
+}
+
+interface RichClient {
+  scheduleClient: {
+    list(opts: { namespace?: string }): AsyncIterable<ScheduleSummary>;
+  };
+}
+
+interface RichClientModule {
+  Connection: { connect(opts: Record<string, unknown>): Promise<RichConnection> };
+  Client: new (opts: { connection: RichConnection; namespace?: string }) => RichClient;
+}
+
+const NAMESPACE_STATE_NAMES: Record<number, string> = {
+  0: "UNSPECIFIED",
+  1: "REGISTERED",
+  2: "DEPRECATED",
+  3: "DELETED",
+};
+
+const VALUE_TYPE_NAMES: Record<number, string> = {
+  0: "Unspecified",
+  1: "Text",
+  2: "Keyword",
+  3: "Int",
+  4: "Double",
+  5: "Bool",
+  6: "Datetime",
+  7: "KeywordList",
+};
+
+function namespaceStateToString(state: number | string | undefined): string {
+  if (typeof state === "string") return state;
+  if (typeof state === "number") return NAMESPACE_STATE_NAMES[state] ?? `STATE_${state}`;
+  return "UNKNOWN";
+}
+
+function valueTypeToString(t: number | string | undefined): string {
+  if (typeof t === "string") return t;
+  if (typeof t === "number") return VALUE_TYPE_NAMES[t] ?? `TYPE_${t}`;
+  return "Unknown";
+}
+
+function retentionTtlToSeconds(
+  ttl: { seconds?: number | bigint | { toNumber(): number } } | null | undefined,
+): number | undefined {
+  if (!ttl?.seconds) return undefined;
+  const s = ttl.seconds;
+  if (typeof s === "number") return s;
+  if (typeof s === "bigint") return Number(s);
+  if (typeof s === "object" && "toNumber" in s) return s.toNumber();
+  return undefined;
+}
+
+function resolveProfileForEnv(
+  config: Record<string, unknown>,
+  environment: string,
+): WorkerProfile {
+  // Try env-named profile first, fall back to defaultProfile.
+  try {
+    return resolveProfile(config, environment);
+  } catch {
+    return resolveProfile(config);
+  }
+}
+
+async function paginateNamespaces(connection: RichConnection): Promise<NonNullable<NamespaceListResponse["namespaces"]>> {
+  const all: NonNullable<NamespaceListResponse["namespaces"]> = [];
+  let nextPageToken: Uint8Array | undefined;
+  do {
+    const res = await connection.workflowService.listNamespaces({
+      pageSize: 100,
+      ...(nextPageToken && { nextPageToken }),
+    });
+    if (res.namespaces) all.push(...res.namespaces);
+    nextPageToken = res.nextPageToken && res.nextPageToken.length > 0 ? res.nextPageToken : undefined;
+  } while (nextPageToken);
+  return all;
+}
+
+/**
+ * Build reverse-lookup maps from server-side identifiers back to chant
+ * entity names, using the `entities` map passed via the plugin contract.
+ *
+ * Mapping rules:
+ *   - Namespace:       props.name              -> entity name
+ *   - SearchAttribute: <ns>/<props.name>       -> entity name
+ *   - Schedule:        <ns>/<props.scheduleId> -> entity name
+ *
+ * For SearchAttribute, the namespace defaults to the *first declared
+ * Temporal::Namespace's name* if the entity itself doesn't pin one — this
+ * matches the serializer's behavior when emitting registration commands.
+ */
+function buildEntityIndex(
+  entities: Map<string, { entityType: string; props: Record<string, unknown> }>,
+): {
+  namespaceByName: Map<string, string>;
+  searchAttrByKey: Map<string, string>;
+  scheduleByKey: Map<string, string>;
+  defaultNamespace?: string;
+} {
+  const namespaceByName = new Map<string, string>();
+  const searchAttrByKey = new Map<string, string>();
+  const scheduleByKey = new Map<string, string>();
+  let defaultNamespace: string | undefined;
+
+  for (const [entityName, { entityType, props }] of entities) {
+    if (entityType === "Temporal::Namespace") {
+      const nsName = (props.name as string) || "";
+      if (nsName) {
+        namespaceByName.set(nsName, entityName);
+        if (!defaultNamespace) defaultNamespace = nsName;
+      }
+    }
+  }
+
+  for (const [entityName, { entityType, props }] of entities) {
+    if (entityType === "Temporal::SearchAttribute") {
+      const attrName = (props.name as string) || "";
+      const ns = (props.namespace as string) || defaultNamespace || "";
+      if (attrName && ns) searchAttrByKey.set(`${ns}/${attrName}`, entityName);
+    } else if (entityType === "Temporal::Schedule") {
+      const scheduleId = (props.scheduleId as string) || "";
+      const ns = (props.namespace as string) || defaultNamespace || "";
+      if (scheduleId && ns) scheduleByKey.set(`${ns}/${scheduleId}`, entityName);
+    }
+  }
+
+  return { namespaceByName, searchAttrByKey, scheduleByKey, defaultNamespace };
+}
+
+export async function describeResources(options: {
+  environment: string;
+  buildOutput: string;
+  entityNames: string[];
+  entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+}): Promise<Record<string, ResourceMetadata>> {
+  const { config } = await loadChantConfig(process.cwd());
+  const profile = resolveProfileForEnv(config as Record<string, unknown>, options.environment);
+
+  const mod = (await loadTemporalClient()) as unknown as RichClientModule;
+  const connection = await mod.Connection.connect(connectionOptions(profile));
+  const client = new mod.Client({ connection });
+
+  const idx = buildEntityIndex(options.entities);
+  const result: Record<string, ResourceMetadata> = {};
+
+  // Map a server-side identifier to a chant entity name when possible;
+  // otherwise fall back to the server-side prefixed key (orphan).
+  const keyForNamespace = (name: string): string =>
+    idx.namespaceByName.get(name) ?? `namespace/${name}`;
+  const keyForSearchAttr = (ns: string, attr: string): string =>
+    idx.searchAttrByKey.get(`${ns}/${attr}`) ?? `searchAttribute/${ns}/${attr}`;
+  const keyForSchedule = (ns: string, scheduleId: string): string =>
+    idx.scheduleByKey.get(`${ns}/${scheduleId}`) ?? `schedule/${ns}/${scheduleId}`;
+
+  try {
+    const namespaces = await paginateNamespaces(connection);
+
+    for (const ns of namespaces) {
+      const name = ns.namespaceInfo?.name;
+      if (!name) continue;
+
+      result[keyForNamespace(name)] = {
+        type: "Temporal::Namespace",
+        physicalId: name,
+        status: namespaceStateToString(ns.namespaceInfo?.state),
+        attributes: pruneUndefined({
+          description: ns.namespaceInfo?.description,
+          ownerEmail: ns.namespaceInfo?.ownerEmail,
+          isGlobalNamespace: ns.isGlobalNamespace,
+          retentionSeconds: retentionTtlToSeconds(ns.config?.workflowExecutionRetentionTtl ?? undefined),
+        }),
+      };
+
+      // SearchAttributes — failure on one namespace shouldn't abort others.
+      try {
+        const sa = await connection.operatorService.listSearchAttributes({ namespace: name });
+        for (const [attrName, valueType] of Object.entries(sa.customAttributes ?? {})) {
+          result[keyForSearchAttr(name, attrName)] = {
+            type: "Temporal::SearchAttribute",
+            physicalId: `${name}/${attrName}`,
+            status: "REGISTERED",
+            attributes: {
+              valueType: valueTypeToString(valueType),
+              namespace: name,
+            },
+          };
+        }
+      } catch (err) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[temporal] failed to list search attributes for namespace "${name}": ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+      }
+
+      // Schedules — same fail-soft policy.
+      try {
+        for await (const s of client.scheduleClient.list({ namespace: name })) {
+          if (!s.scheduleId) continue;
+          result[keyForSchedule(name, s.scheduleId)] = {
+            type: "Temporal::Schedule",
+            physicalId: `${name}/${s.scheduleId}`,
+            status: s.state?.paused ? "PAUSED" : "ACTIVE",
+            attributes: pruneUndefined({
+              namespace: name,
+              workflowType: s.action?.workflowType,
+              cronExpressions: s.spec?.cronExpressions,
+              note: s.state?.note,
+            }),
+          };
+        }
+      } catch (err) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[temporal] failed to list schedules for namespace "${name}": ${
+            err instanceof Error ? err.message : String(err)
+          }`,
+        );
+      }
+    }
+  } finally {
+    if (typeof connection.close === "function") {
+      try { await connection.close(); } catch { /* best-effort */ }
+    }
+  }
+
+  return result;
+}
+
+function pruneUndefined<T extends Record<string, unknown>>(obj: T): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined) out[k] = v;
+  }
+  return out;
+}

package/src/index.ts

@@ -27,6 +27,8 @@ export { TemporalDevStack } from "./composites/dev-stack";
 export type { TemporalDevStackConfig, TemporalDevStackResources } from "./composites/dev-stack";
 export { TemporalCloudStack } from "./composites/cloud-stack";
 export type { TemporalCloudStackConfig, TemporalCloudStackResources } from "./composites/cloud-stack";
+export { WatchOp } from "./composites/watch-op";
+export type { WatchOpConfig, WatchOpResources } from "./composites/watch-op";
 
 // Op builders (re-exported from core for single-import convenience)
 export {

package/src/op/activities/index.ts

@@ -16,8 +16,8 @@ export type { GitlabPipelineArgs } from "./gitlab";
 export { shellCmd } from "./shell";
 export type { ShellCmdArgs } from "./shell";
 
-export { stateSnapshot } from "./state";
-export type { StateSnapshotArgs } from "./state";
+export { stateSnapshot, stateDiff } from "./state";
+export type { StateSnapshotArgs, StateDiffArgs, StateDiffResult } from "./state";
 
 export { chantTeardown } from "./teardown";
 export type { ChantTeardownArgs } from "./teardown";

package/src/op/activities/state.ts

@@ -17,3 +17,69 @@ export async function stateSnapshot(args: StateSnapshotArgs): Promise<void> {
   if (stdout) console.log(stdout);
   if (stderr) console.error(stderr);
 }
+
+export interface StateDiffArgs {
+  /** Environment name (e.g. "dev", "staging", "prod"). */
+  env: string;
+  /**
+   * When true, run `chant state diff <env> --live` (queries cloud APIs).
+   * When false (default), run digest-only diff against the last snapshot.
+   */
+  live?: boolean;
+}
+
+export interface StateDiffResult {
+  /** Combined stdout + stderr from the chant command. */
+  output: string;
+  /** Process exit code (0 = success). */
+  exitCode: number;
+  /**
+   * True when the diff output contains any drift indicators
+   * (MISSING / ORPHAN / DRIFTED / DISAPPEARED section headers from
+   * `chant state diff --live`).
+   */
+  drifted: boolean;
+}
+
+/**
+ * Section headers emitted by `chant state diff --live` that indicate a
+ * non-empty drift category. See packages/core/src/cli/handlers/state.ts.
+ */
+const DRIFT_HEADERS = [
+  "MISSING",
+  "ORPHAN",
+  "DISAPPEARED",
+  "DRIFTED",
+  "ARTIFACTS ADDED",
+  "ARTIFACTS REMOVED",
+  "ARTIFACTS CHANGED",
+];
+
+function detectDrift(output: string): boolean {
+  return DRIFT_HEADERS.some((h) => output.includes(`${h} (`) || output.includes(`\n${h}`));
+}
+
+/**
+ * Run `chant state diff <env>` and return the output + structured drift
+ * flag. Read-only; intended for use inside watch/observation workflows.
+ * Uses fastIdempotent profile.
+ *
+ * The `drifted` field is computed by scanning the output for any of the
+ * MISSING / ORPHAN / DRIFTED / DISAPPEARED section headers documented in
+ * cli/state.mdx. Pair with `outcomeAttribute: { name: "Drift", from: "drifted" }`
+ * on a WatchOp activity step to surface drift as a workflow search attribute.
+ */
+export async function stateDiff(args: StateDiffArgs): Promise<StateDiffResult> {
+  const liveFlag = args.live ? " --live" : "";
+  try {
+    const { stdout, stderr } = await execAsync(`chant state diff ${args.env}${liveFlag}`);
+    const output = `${stdout}${stderr}`.trim();
+    if (output) console.log(output);
+    return { output, exitCode: 0, drifted: detectDrift(output) };
+  } catch (err) {
+    const e = err as { code?: number; stdout?: string; stderr?: string };
+    const output = `${e.stdout ?? ""}${e.stderr ?? ""}`.trim();
+    if (output) console.error(output);
+    return { output, exitCode: e.code ?? 1, drifted: detectDrift(output) };
+  }
+}

package/src/op/op-serializer.test.ts

@@ -194,6 +194,23 @@ describe("serializeOps()", () => {
       const wf = serializeOps(ops)["ops/op/workflow.ts"];
       expect(wf).toContain("// Phase: Build and Test");
     });
+
+    it("renders onFailure compensation phases after main phases", () => {
+      const ops = new Map([
+        makeOp({
+          name: "safe-op", overview: "o",
+          phases: [
+            { name: "Deploy", steps: [{ kind: "activity", fn: "helmInstall", args: { name: "r", chart: "c" } }] },
+          ],
+          onFailure: [
+            { name: "Rollback", steps: [{ kind: "activity", fn: "helmInstall", args: { name: "r", chart: "c" } }] },
+          ],
+        }),
+      ]);
+      const wf = serializeOps(ops)["ops/safe-op/workflow.ts"];
+      expect(wf).toContain("onFailure compensation");
+      expect(wf).toContain("// Phase: Rollback");
+    });
   });
 
   // ── activities.ts ───────────────────────────────────────────────────────────
@@ -274,4 +291,218 @@ describe("serializeOps()", () => {
       expect(() => serializeOps(ops)).toThrow(/nonexistent-op/);
     });
   });
+
+  // ── Auto-emit upsertSearchAttributes (#28) ──────────────────────────────────
+
+  describe("upsertSearchAttributes auto-emit", () => {
+    function countOccurrences(haystack: string, needle: string): number {
+      return haystack.split(needle).length - 1;
+    }
+
+    it("imports upsertSearchAttributes from @temporalio/workflow", () => {
+      const ops = new Map([
+        makeOp({ name: "op", overview: "o", phases: [{ name: "Phase1", steps: [] }] }),
+      ]);
+      const wf = serializeOps(ops)["ops/op/workflow.ts"];
+      expect(wf).toMatch(
+        /import \{[^}]*\bupsertSearchAttributes\b[^}]*\} from '@temporalio\/workflow'/,
+      );
+    });
+
+    it("3-phase Op with no searchAttributes emits exactly 4 upsert calls", () => {
+      const ops = new Map([
+        makeOp({
+          name: "deploy",
+          overview: "o",
+          phases: [
+            { name: "init", steps: [] },
+            { name: "apply", steps: [] },
+            { name: "verify", steps: [] },
+          ],
+        }),
+      ]);
+      const wf = serializeOps(ops)["ops/deploy/workflow.ts"];
+
+      expect(countOccurrences(wf, "upsertSearchAttributes(")).toBe(4);
+      // Initial call: OpName only, no Phase yet
+      expect(wf).toContain('upsertSearchAttributes({"OpName":["deploy"]});');
+      // Phase upserts at each phase boundary
+      expect(wf).toContain('upsertSearchAttributes({ Phase: ["init"] });');
+      expect(wf).toContain('upsertSearchAttributes({ Phase: ["apply"] });');
+      expect(wf).toContain('upsertSearchAttributes({ Phase: ["verify"] });');
+    });
+
+    it("merges user-provided searchAttributes into the initial call (each value as a 1-element array)", () => {
+      const ops = new Map([
+        makeOp({
+          name: "deploy",
+          overview: "o",
+          phases: [{ name: "Build", steps: [] }],
+          searchAttributes: { Region: "us-east-1", Environment: "prod" },
+        }),
+      ]);
+      const wf = serializeOps(ops)["ops/deploy/workflow.ts"];
+
+      expect(wf).toContain(
+        'upsertSearchAttributes({"OpName":["deploy"],"Region":["us-east-1"],"Environment":["prod"]});',
+      );
+    });
+
+    it("single-phase Op produces exactly 2 upsert calls", () => {
+      const ops = new Map([
+        makeOp({
+          name: "tiny",
+          overview: "o",
+          phases: [{ name: "Only", steps: [] }],
+        }),
+      ]);
+      const wf = serializeOps(ops)["ops/tiny/workflow.ts"];
+
+      expect(countOccurrences(wf, "upsertSearchAttributes(")).toBe(2);
+    });
+
+    it("emits Phase upserts inside onFailure compensation phases", () => {
+      const ops = new Map([
+        makeOp({
+          name: "deploy",
+          overview: "o",
+          phases: [{ name: "Apply", steps: [] }],
+          onFailure: [
+            { name: "Rollback", steps: [] },
+            { name: "Notify", steps: [] },
+          ],
+        }),
+      ]);
+      const wf = serializeOps(ops)["ops/deploy/workflow.ts"];
+
+      // 1 initial + 1 Apply + 2 onFailure phases = 4
+      expect(countOccurrences(wf, "upsertSearchAttributes(")).toBe(4);
+      expect(wf).toContain('upsertSearchAttributes({ Phase: ["Rollback"] });');
+      expect(wf).toContain('upsertSearchAttributes({ Phase: ["Notify"] });');
+    });
+  });
+
+  // ── outcomeAttribute (#41) ──────────────────────────────────────────────────
+
+  describe("outcomeAttribute auto-emit", () => {
+    it("captures activity result and emits an upsert with from-path", () => {
+      const ops = new Map([
+        makeOp({
+          name: "watch",
+          overview: "watch",
+          phases: [
+            {
+              name: "Diff",
+              steps: [
+                { kind: "activity", fn: "stateDiff", args: { env: "prod" }, outcomeAttribute: { name: "Drift", from: "drifted" } },
+              ],
+            },
+          ],
+        }),
+      ]);
+      const wf = serializeOps(ops)["ops/watch/workflow.ts"];
+      expect(wf).toContain('const __r0 = await stateDiff({"env":"prod"});');
+      expect(wf).toContain('upsertSearchAttributes({ "Drift": [String(__r0?.drifted)] });');
+    });
+
+    it("stringifies whole result when from is omitted", () => {
+      const ops = new Map([
+        makeOp({
+          name: "watch",
+          overview: "watch",
+          phases: [
+            {
+              name: "Check",
+              steps: [
+                { kind: "activity", fn: "checkSomething", outcomeAttribute: { name: "Status" } },
+              ],
+            },
+          ],
+        }),
+      ]);
+      const wf = serializeOps(ops)["ops/watch/workflow.ts"];
+      expect(wf).toContain('upsertSearchAttributes({ "Status": [String(__r0)] });');
+    });
+
+    it("nested from-path uses optional-chain stringify", () => {
+      const ops = new Map([
+        makeOp({
+          name: "watch",
+          overview: "watch",
+          phases: [
+            {
+              name: "Inspect",
+              steps: [
+                { kind: "activity", fn: "deepInspect", outcomeAttribute: { name: "Ok", from: "result.healthy" } },
+              ],
+            },
+          ],
+        }),
+      ]);
+      const wf = serializeOps(ops)["ops/watch/workflow.ts"];
+      expect(wf).toContain('upsertSearchAttributes({ "Ok": [String(__r0?.result?.healthy)] });');
+    });
+
+    it("counter is workflow-scoped: multiple outcome attrs use __r0, __r1, ...", () => {
+      const ops = new Map([
+        makeOp({
+          name: "watch",
+          overview: "watch",
+          phases: [
+            { name: "A", steps: [{ kind: "activity", fn: "first", outcomeAttribute: { name: "FirstResult" } }] },
+            { name: "B", steps: [{ kind: "activity", fn: "second", outcomeAttribute: { name: "SecondResult" } }] },
+          ],
+        }),
+      ]);
+      const wf = serializeOps(ops)["ops/watch/workflow.ts"];
+      expect(wf).toContain("const __r0 = await first(");
+      expect(wf).toContain("const __r1 = await second(");
+      expect(wf).toContain('upsertSearchAttributes({ "FirstResult": [String(__r0)] });');
+      expect(wf).toContain('upsertSearchAttributes({ "SecondResult": [String(__r1)] });');
+    });
+
+    it("activities without outcomeAttribute keep the bare-await form", () => {
+      const ops = new Map([
+        makeOp({
+          name: "mixed",
+          overview: "mixed",
+          phases: [
+            {
+              name: "Mix",
+              steps: [
+                { kind: "activity", fn: "noOutcome" },
+                { kind: "activity", fn: "withOutcome", outcomeAttribute: { name: "Result" } },
+              ],
+            },
+          ],
+        }),
+      ]);
+      const wf = serializeOps(ops)["ops/mixed/workflow.ts"];
+      expect(wf).toContain("await noOutcome({});");
+      expect(wf).toContain("const __r0 = await withOutcome({});");
+    });
+
+    it("parallel phase with outcome attrs destructures Promise.all results", () => {
+      const ops = new Map([
+        makeOp({
+          name: "fan",
+          overview: "fan",
+          phases: [
+            {
+              name: "Parallel",
+              parallel: true,
+              steps: [
+                { kind: "activity", fn: "alpha", outcomeAttribute: { name: "AlphaOk", from: "ok" } },
+                { kind: "activity", fn: "beta", outcomeAttribute: { name: "BetaOk", from: "ok" } },
+              ],
+            },
+          ],
+        }),
+      ]);
+      const wf = serializeOps(ops)["ops/fan/workflow.ts"];
+      expect(wf).toContain("const [__r0, __r1] = await Promise.all([");
+      expect(wf).toContain('upsertSearchAttributes({ "AlphaOk": [String(__r0?.ok)] });');
+      expect(wf).toContain('upsertSearchAttributes({ "BetaOk": [String(__r1?.ok)] });');
+    });
+  });
 });