@intentius/chant 0.57.0 → 0.58.0

package/src/cli/handlers/run-client.ts

@@ -1,219 +0,0 @@
-/** Subset of WorkerProfile fields used by `chant run`. */
-export interface WorkerProfile {
-  address: string;
-  namespace: string;
-  taskQueue: string;
-  tls?: boolean | { serverNameOverride?: string };
-  apiKey?: string | { env: string };
-  autoStart?: boolean;
-}
-
-export interface TemporalClientModule {
-  Connection: {
-    connect(opts: Record<string, unknown>): Promise<unknown>;
-  };
-  Client: new (opts: Record<string, unknown>) => TemporalClientHandle;
-}
-
-export interface TemporalClientHandle {
-  workflow: {
-    start(workflowFn: unknown, opts: Record<string, unknown>): Promise<WorkflowHandleRaw>;
-    getHandle(workflowId: string): WorkflowHandleRaw;
-    list(opts?: Record<string, unknown>): AsyncIterable<WorkflowExecutionInfo>;
-  };
-}
-
-export interface WorkflowHandleRaw {
-  workflowId: string;
-  firstExecutionRunId?: string;
-  result(): Promise<unknown>;
-  describe(): Promise<WorkflowExecutionDescription>;
-  fetchHistory(): Promise<WorkflowHistoryRaw>;
-  signal(signalName: string, ...args: unknown[]): Promise<void>;
-  query<T = unknown>(queryName: string, ...args: unknown[]): Promise<T>;
-  cancel(): Promise<void>;
-}
-
-export interface WorkflowExecutionDescription {
-  workflowId: string;
-  runId: string;
-  status: { name: string };
-  startTime: Date;
-  closeTime?: Date;
-  taskQueue: string;
-  type: { name: string };
-}
-
-export interface WorkflowExecutionInfo {
-  workflowId: string;
-  runId: string;
-  type: { name: string };
-  status: { name: string };
-  startTime: Date;
-  closeTime?: Date;
-}
-
-export interface WorkflowHistoryRaw {
-  events?: HistoryEvent[];
-}
-
-/**
- * `eventType` is the short PascalCase form (`"ActivityTaskScheduled"`, not
- * the wire enum's `"EVENT_TYPE_ACTIVITY_TASK_SCHEDULED"`) and `eventId`/
- * `scheduledEventId` are decimal strings — the shape {@link fetchNormalizedHistory}
- * produces, not `WorkflowHandleRaw.fetchHistory()`'s own raw return value.
- */
-export interface HistoryEvent {
-  eventId?: string;
-  eventType?: string;
-  eventTime?: Date;
-  activityTaskCompletedEventAttributes?: { scheduledEventId?: string };
-  activityTaskScheduledEventAttributes?: { activityId?: string; activityType?: { name?: string } };
-  activityTaskFailedEventAttributes?: { scheduledEventId?: string; failure?: { message?: string } };
-  workflowExecutionCompletedEventAttributes?: unknown;
-  workflowExecutionFailedEventAttributes?: { failure?: { message?: string } };
-}
-
-/**
- * `WorkflowHandleRaw.fetchHistory()` returns the Temporal wire proto
- * untouched: `eventType` is the numeric enum, `eventId`/`scheduledEventId`
- * are `Long` instances, `eventTime` is a `{seconds, nanos}` protobuf
- * Timestamp — none of them comparable or constructible the way the rest of
- * this file (and run-report.ts, op-progress.ts) needs. The proto message's
- * own `toJSON()` is what turns enums into their string name and `Long`s into
- * decimal strings, so a JSON round-trip is the normalization step; only
- * `eventTime` then needs a further Timestamp-to-Date conversion.
- */
-export async function fetchNormalizedHistory(handle: WorkflowHandleRaw): Promise<WorkflowHistoryRaw> {
-  const raw = (await handle.fetchHistory()) as unknown as { events?: unknown[] };
-  const events = JSON.parse(JSON.stringify(raw.events ?? [])) as Array<Record<string, unknown>>;
-  return { events: events.map(normalizeHistoryEvent) };
-}
-
-/** `"EVENT_TYPE_ACTIVITY_TASK_SCHEDULED"` → `"ActivityTaskScheduled"`. A value that isn't ALL_CAPS_WITH_UNDERSCORES (e.g. already-short test fixture data) passes through unchanged, so normalizing twice is a no-op. */
-function shortEventType(raw: unknown): string | undefined {
-  if (typeof raw !== "string" || raw.length === 0) return undefined;
-  if (!/^[A-Z][A-Z0-9_]*$/.test(raw)) return raw;
-  const stripped = raw.startsWith("EVENT_TYPE_") ? raw.slice("EVENT_TYPE_".length) : raw;
-  return stripped
-    .split("_")
-    .filter(Boolean)
-    .map((w) => w[0] + w.slice(1).toLowerCase())
-    .join("");
-}
-
-/** Accepts a protobuf `{seconds, nanos}` Timestamp (its `seconds` a decimal string post-JSON-round-trip), an ISO string (already-normalized test fixture data, or the same value normalized twice), or a `Date`. */
-function protoTimestampToDate(ts: unknown): Date | undefined {
-  if (!ts) return undefined;
-  if (ts instanceof Date) return ts;
-  if (typeof ts === "string") {
-    const d = new Date(ts);
-    return Number.isNaN(d.getTime()) ? undefined : d;
-  }
-  if (typeof ts !== "object") return undefined;
-  const seconds = Number((ts as { seconds?: unknown }).seconds);
-  const nanos = Number((ts as { nanos?: unknown }).nanos ?? 0);
-  if (!Number.isFinite(seconds)) return undefined;
-  return new Date(seconds * 1000 + Math.floor(nanos / 1e6));
-}
-
-/** `undefined`/`null` stays `undefined`; anything else (a decimal string post-JSON-round-trip, or a bare number/Long from an un-round-tripped test fixture) becomes a string — `scheduledEventId` is joined against `eventId` as a Map key, and a number `7` and a string `"7"` are different keys. */
-function idString(v: unknown): string | undefined {
-  return v === undefined || v === null ? undefined : String(v);
-}
-
-function normalizeHistoryEvent(raw: Record<string, unknown>): HistoryEvent {
-  const scheduled = raw.activityTaskScheduledEventAttributes as
-    | { activityId?: unknown; activityType?: { name?: string } }
-    | undefined;
-  const completed = raw.activityTaskCompletedEventAttributes as { scheduledEventId?: unknown } | undefined;
-  const failed = raw.activityTaskFailedEventAttributes as
-    | { scheduledEventId?: unknown; failure?: { message?: string } }
-    | undefined;
-
-  return {
-    eventId: idString(raw.eventId),
-    eventType: shortEventType(raw.eventType),
-    eventTime: protoTimestampToDate(raw.eventTime),
-    ...(scheduled
-      ? { activityTaskScheduledEventAttributes: { activityId: idString(scheduled.activityId), activityType: scheduled.activityType } }
-      : {}),
-    ...(completed
-      ? { activityTaskCompletedEventAttributes: { scheduledEventId: idString(completed.scheduledEventId) } }
-      : {}),
-    ...(failed
-      ? { activityTaskFailedEventAttributes: { scheduledEventId: idString(failed.scheduledEventId), failure: failed.failure } }
-      : {}),
-    workflowExecutionCompletedEventAttributes: raw.workflowExecutionCompletedEventAttributes,
-    workflowExecutionFailedEventAttributes: raw.workflowExecutionFailedEventAttributes as HistoryEvent["workflowExecutionFailedEventAttributes"],
-  };
-}
-
-/**
- * Dynamically import @temporalio/client from the user's project node_modules.
- * Fails with a helpful message if not installed.
- */
-export async function loadTemporalClient(): Promise<TemporalClientModule> {
-  try {
-    // Use variable to prevent tsc from statically resolving the optional dep
-    const mod = "@temporalio/client";
-    return await import(mod) as unknown as TemporalClientModule;
-  } catch {
-    throw new Error(
-      '@temporalio/client is not installed. Run: npm install @temporalio/client',
-    );
-  }
-}
-
-/**
- * Build a Temporal Connection.connect() options object from a worker profile.
- */
-export function connectionOptions(profile: WorkerProfile): Record<string, unknown> {
-  const apiKey =
-    typeof profile.apiKey === "object" && profile.apiKey !== null
-      ? process.env[(profile.apiKey as { env: string }).env]
-      : (profile.apiKey as string | undefined);
-
-  return {
-    address: profile.address,
-    ...(profile.tls && {
-      tls: typeof profile.tls === "object" ? profile.tls : {},
-      metadata: apiKey ? { Authorization: `Bearer ${apiKey}` } : {},
-    }),
-  };
-}
-
-/**
- * Deterministic workflow ID for an Op — allows status/signal/cancel/log
- * without storing run IDs locally.
- */
-export function resolveWorkflowId(opName: string): string {
-  return `chant-op-${opName}`;
-}
-
-/**
- * Resolve a named profile from the chant config.
- * Falls back to defaultProfile then "local".
- */
-export function resolveProfile(
-  config: Record<string, unknown>,
-  profileName?: string,
-): WorkerProfile {
-  // #1344 — the temporal lexicon declares this namespace and core validates it
-  // at load, so this reads a checked value rather than asserting one.
-  const temporal = (config as { temporal?: Record<string, unknown> }).temporal;
-  if (!temporal?.profiles) {
-    throw new Error(
-      'No temporal.profiles found in chant.config.ts. Add a profile to use `chant run`.',
-    );
-  }
-  const profiles = temporal.profiles as Record<string, WorkerProfile>;
-  const name = profileName ?? (temporal.defaultProfile as string | undefined) ?? "local";
-  const profile = profiles[name];
-  if (!profile) {
-    throw new Error(
-      `Temporal profile "${name}" not found. Available: ${Object.keys(profiles).join(", ")}`,
-    );
-  }
-  return profile;
-}

package/src/cli/handlers/run-report.test.ts

@@ -1,62 +0,0 @@
-import { describe, test, expect } from "vitest";
-import { generateReport } from "./run-report";
-import type { OpConfig } from "../../op/types";
-import type { WorkflowExecutionDescription, WorkflowHistoryRaw, HistoryEvent } from "./run-client";
-
-function scheduled(eventId: string, fn: string): HistoryEvent {
-  return {
-    eventId,
-    eventType: "ActivityTaskScheduled",
-    eventTime: new Date(0),
-    activityTaskScheduledEventAttributes: { activityId: eventId, activityType: { name: fn } },
-  };
-}
-function completed(scheduledEventId: string): HistoryEvent {
-  return {
-    eventType: "ActivityTaskCompleted",
-    eventTime: new Date(1000),
-    activityTaskCompletedEventAttributes: { scheduledEventId },
-  };
-}
-
-const desc: WorkflowExecutionDescription = {
-  workflowId: "wf", runId: "r1", status: { name: "COMPLETED" },
-  startTime: new Date(0), closeTime: new Date(2000), taskQueue: "q", type: { name: "opWorkflow" },
-};
-
-describe("generateReport", () => {
-  test("two steps calling the same activity each get their own row (no last-wins collision, chant #1676)", () => {
-    const config: OpConfig = {
-      name: "op", overview: "o",
-      phases: [{ name: "P1", steps: [{ kind: "activity", fn: "dup" }, { kind: "activity", fn: "dup" }] }],
-    };
-    const history: WorkflowHistoryRaw = {
-      events: [scheduled("1", "dup"), completed("1"), scheduled("2", "dup"), completed("2")],
-    };
-    const md = generateReport("op", config, desc, history);
-    // Both rows present — the prior fn-name join would have produced one
-    // row for "dup" (the second scheduled event overwriting the first).
-    const dupRows = md.split("\n").filter((line) => line.includes("| P1 | dup |"));
-    expect(dupRows).toHaveLength(2);
-    expect(dupRows.every((line) => line.includes("✓ completed"))).toBe(true);
-  });
-
-  test("a declared step with no matching history is reported skipped, not a phantom 'running' row", () => {
-    const config: OpConfig = {
-      name: "op", overview: "o",
-      phases: [
-        { name: "P1", steps: [{ kind: "activity", fn: "a" }] },
-        { name: "P2", steps: [{ kind: "activity", fn: "b" }] },
-      ],
-      onFailure: [{ name: "C1", steps: [{ kind: "activity", fn: "comp" }] }],
-    };
-    const history: WorkflowHistoryRaw = { events: [scheduled("1", "a"), completed("1"), scheduled("2", "b"), completed("2")] };
-    const md = generateReport("op", config, desc, history);
-    expect(md).toContain("| P1 | a | 1.0s | ✓ completed |");
-    expect(md).toContain("| P2 | b | 1.0s | ✓ completed |");
-    // The timeline table is scoped to config.phases only (unchanged from
-    // before this fix) — onFailure phases never appear in it regardless of
-    // whether they ran.
-    expect(md).not.toContain("C1");
-  });
-});

package/src/cli/handlers/run-report.ts

@@ -1,122 +0,0 @@
-import { writeFileSync, mkdirSync } from "node:fs";
-import { join, dirname } from "node:path";
-import type { OpConfig } from "../../op/types";
-import type { WorkflowExecutionDescription, WorkflowHistoryRaw, HistoryEvent } from "./run-client";
-import { extractStepRecords } from "./op-progress";
-
-interface ActivityRecord {
-  name: string;
-  durationMs?: number;
-  status: "completed" | "failed" | "skipped";
-  error?: string;
-}
-
-interface PhaseRecord {
-  name: string;
-  activities: ActivityRecord[];
-}
-
-function formatDuration(ms: number): string {
-  if (ms < 1000) return `${ms}ms`;
-  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
-  const mins = Math.floor(ms / 60_000);
-  const secs = Math.round((ms % 60_000) / 1000);
-  return secs > 0 ? `${mins}m ${secs}s` : `${mins}m`;
-}
-
-/**
- * Group `extractStepRecords`' flat, declared-order step list back into
- * per-phase rows for the markdown table. `final` (a closed workflow has
- * every settled step it's ever going to have) decides whether an unmatched
- * declared step is reported "skipped" or simply omitted for now — see
- * `extractStepRecords`'s own doc.
- */
-function extractPhaseRecords(config: OpConfig, history: WorkflowHistoryRaw, final: boolean): PhaseRecord[] {
-  const byPhase = new Map<string, ActivityRecord[]>();
-  for (const phase of config.phases) byPhase.set(phase.name, []);
-
-  for (const step of extractStepRecords(config, history, { final })) {
-    const status = step.status === "ok" ? "completed" : step.status === "fail" ? "failed" : "skipped";
-    const list = byPhase.get(step.phase) ?? (byPhase.set(step.phase, []), byPhase.get(step.phase)!);
-    list.push({ name: step.fn, durationMs: step.durationMs, status, ...(step.error ? { error: step.error } : {}) });
-  }
-
-  return config.phases.map((phase) => ({ name: phase.name, activities: byPhase.get(phase.name) ?? [] }));
-}
-
-export function generateReport(
-  opName: string,
-  config: OpConfig,
-  description: WorkflowExecutionDescription,
-  history: WorkflowHistoryRaw,
-): string {
-  const lines: string[] = [];
-
-  const status = description.status.name;
-  const startTime = description.startTime;
-  const closeTime = description.closeTime;
-  const durationMs = closeTime ? closeTime.getTime() - startTime.getTime() : undefined;
-
-  lines.push(`# Deployment Report: ${opName}`);
-  lines.push("");
-  lines.push("## Overview");
-  lines.push("");
-  lines.push(`| Field | Value |`);
-  lines.push(`|---|---|`);
-  lines.push(`| Op | ${opName} |`);
-  lines.push(`| Overview | ${config.overview} |`);
-  lines.push(`| Status | **${status}** |`);
-  lines.push(`| Workflow ID | ${description.workflowId} |`);
-  lines.push(`| Run ID | ${description.runId} |`);
-  lines.push(`| Start | ${startTime.toISOString()} |`);
-  if (closeTime) lines.push(`| End | ${closeTime.toISOString()} |`);
-  if (durationMs !== undefined) lines.push(`| Duration | ${formatDuration(durationMs)} |`);
-  lines.push("");
-
-  lines.push("## Timeline");
-  lines.push("");
-  lines.push("| Phase | Activity | Duration | Status |");
-  lines.push("|---|---|---|---|");
-
-  const phases = extractPhaseRecords(config, history, Boolean(closeTime));
-  for (const phase of phases) {
-    if (phase.activities.length === 0) {
-      lines.push(`| ${phase.name} | — | — | — |`);
-    }
-    for (const act of phase.activities) {
-      const dur = act.durationMs !== undefined ? formatDuration(act.durationMs) : "—";
-      const statusEmoji = act.status === "completed" ? "✓" : act.status === "failed" ? "✗" : "○";
-      lines.push(`| ${phase.name} | ${act.name} | ${dur} | ${statusEmoji} ${act.status} |`);
-    }
-  }
-  lines.push("");
-
-  // Errors section
-  const failedEvents = (history.events ?? []).filter(
-    (e): e is HistoryEvent & Required<Pick<HistoryEvent, "activityTaskFailedEventAttributes">> =>
-      e.eventType === "ActivityTaskFailed" && !!e.activityTaskFailedEventAttributes,
-  );
-
-  if (failedEvents.length > 0) {
-    lines.push("## Errors");
-    lines.push("");
-    for (const event of failedEvents) {
-      const msg = event.activityTaskFailedEventAttributes?.failure?.message ?? "unknown";
-      lines.push(`- ${msg}`);
-    }
-    lines.push("");
-  }
-
-  lines.push(`---`);
-  lines.push(`*Generated by chant at ${new Date().toISOString()}*`);
-  lines.push("");
-
-  return lines.join("\n");
-}
-
-export function writeReport(opName: string, markdown: string): string {
-  const outPath = join("dist", `${opName}-report.md`);
-  mkdirSync(dirname(outPath), { recursive: true });
-  writeFileSync(outPath, markdown, "utf-8");
-  return outPath;
-}

package/src/components/temporal-codegen-loader.ts

@@ -1,41 +0,0 @@
-/**
- * Dynamic loader for the durable component → Temporal codegen (#589, epic
- * #551 §5/§8). The actual `serializeComponent` generator lives in
- * `@intentius/chant-lexicon-temporal` (`src/component-op/serializer.ts`),
- * mirroring `Temporal::Op` codegen — core never statically depends on the
- * Temporal lexicon, the same boundary `../op/activity-registry.ts`'s
- * `loadActivities`/`loadProfiles` already keep for Op activities.
- */
-
-import type { DriverComponent } from "./driver";
-
-/** Target environment (and env-config) baked into the generated workflow at compile time — see `serializeComponent`'s docstring in the Temporal lexicon for why this can't be resolved at workflow-run time instead. */
-export interface ComponentTemporalCodegenOptions {
-  env?: string;
-  vars?: Record<string, unknown>;
-}
-
-export interface ComponentTemporalCodegen {
-  /** Serialize one component into `{ "components/<name>/workflow.ts": "...", ... }`. */
-  serializeComponent(component: DriverComponent, options?: ComponentTemporalCodegenOptions): Record<string, string>;
-  /** Deterministic workflow function name for a component (mirrors the generated `export async function <fn>()`). */
-  componentWorkflowFnName(componentName: string): string;
-}
-
-/**
- * Dynamically import the Temporal lexicon's component codegen. Throws a
- * friendly error if the lexicon is not installed — the durable component
- * path needs the generator even though discovery/local execution never do.
- */
-export async function loadComponentTemporalCodegen(): Promise<ComponentTemporalCodegen> {
-  try {
-    // Variable specifier so tsc does not statically resolve the optional dep.
-    const spec = "@intentius/chant-lexicon-temporal/component-op/serializer";
-    return (await import(spec)) as unknown as ComponentTemporalCodegen;
-  } catch (err) {
-    throw new Error(
-      "no durable component codegen available — install `@intentius/chant-lexicon-temporal` " +
-        `to run components with --temporal (${err instanceof Error ? err.message : String(err)})`,
-    );
-  }
-}

package/src/lint/rules/comp/comp004-gate-needs-temporal.ts

@@ -1,66 +0,0 @@
-/**
- * COMP004: gate-needs-temporal
- *
- * Flags a `gate` step anywhere in a component's composition — a durable,
- * human-approval wait that cannot run on the local in-process executor (see
- * ../../../components/driver.ts's `DriverGateUnsupportedError` and
- * docs/components/orchestration.mdx's "Temporal is optional" aside: "gates ...
- * require the durable (Temporal) execution backend").
- *
- * The component contract has no per-component backend/executor field (the
- * backend is chosen per *run*, via `chant run --temporal`, per epic #551 §8 —
- * intentionally not part of the declaration, so the same component graduates
- * to Temporal without changing its definition). That means lint cannot tell,
- * from the declaration alone, whether a given `gate` will actually run under
- * Temporal when this component is deployed — every `gate` is a standing
- * "this component needs the durable backend" fact worth surfacing, not a
- * mistake to silently allow. Acknowledge it explicitly with a **file-level**
- * disable directive once the durable backend is genuinely intended (see
- * lint-rules/disable-directives.mdx) — a COMP* diagnostic carries no real
- * line/column (it is reported for the whole component; see
- * ../../component-checks.ts), so only the file-level `chant-disable` form is
- * honored for these rules — `-line`/`-next-line` do not suppress a COMP*
- * diagnostic (see ../../../cli/commands/lint.ts's
- * `runComponentCheckDiagnostics`):
- *
- * ```ts
- * // chant-disable COMP004 -- graduates to --temporal for the human approval wait
- * ```
- *
- * Triggers on: any `gate` step in `deploy`/`rollback` with no matching
- * file-level disable directive.
- * OK: a component with no `gate` steps at all, or a `gate` whose file-level
- * disable directive documents the Temporal graduation.
- */
-
-import type { ComponentCheck, ComponentCheckContext, ComponentCheckDiagnostic } from "../../component-checks";
-import { walkComponent } from "./support";
-
-export const comp004GateNeedsTemporalRule: ComponentCheck = {
-  id: "COMP004",
-  severity: "error",
-  category: "correctness",
-  description: "A gate step requires the durable (Temporal) execution backend — it cannot run on the local executor",
-  check(ctx: ComponentCheckContext): ComponentCheckDiagnostic[] {
-    const diagnostics: ComponentCheckDiagnostic[] = [];
-
-    for (const [name, { component, filePath }] of ctx.components) {
-      const { gates } = walkComponent(component);
-      for (const { gate, phaseName } of gates) {
-        diagnostics.push({
-          checkId: "COMP004",
-          severity: "error",
-          component: name,
-          file: filePath,
-          message:
-            `Component "${name}": gate "${gate.signalName}" (phase "${phaseName}") requires the durable (Temporal) ` +
-            `execution backend — it cannot run on the local in-process executor. If this component is meant to run ` +
-            `with "chant run --temporal", suppress with a file-level "// chant-disable COMP004 -- <reason>" comment ` +
-            `anywhere in this file to document that intent explicitly.`,
-        });
-      }
-    }
-
-    return diagnostics;
-  },
-};