@intentius/chant 0.1.5 → 0.1.7

package/src/cli/mcp/state-tools.ts

@@ -6,8 +6,6 @@ import { build } from "../../build";
 import { computeBuildDigest, diffDigests } from "../../state/digest";
 import { takeSnapshot } from "../../state/snapshot";
 import type { StateSnapshot } from "../../state/types";
-import { discoverSpells } from "../../spell/discovery";
-
 export interface ToolRegistration {
   definition: ToolDefinition;
   handler: ToolHandler;
@@ -87,52 +85,3 @@ export function createDiffTool(plugins: LexiconPlugin[]): ToolRegistration {
   };
 }
 
-/**
- * Create spell-done tool definition and handler
- */
-export function createSpellDoneTool(): ToolRegistration {
-  return {
-    definition: {
-      name: "spell-done",
-      description: "Mark a spell task as done",
-      inputSchema: {
-        type: "object",
-        properties: {
-          name: { type: "string", description: "Spell name" },
-          taskNumber: { type: "number", description: "Task number (1-based)" },
-        },
-        required: ["name", "taskNumber"],
-      },
-    },
-    handler: async (params) => {
-      const { readFileSync, writeFileSync } = await import("node:fs");
-      const { spells } = await discoverSpells();
-      const name = params.name as string;
-      const taskNumber = params.taskNumber as number;
-      const spell = spells.get(name);
-      if (!spell) return `Spell "${name}" not found`;
-      if (taskNumber < 1 || taskNumber > spell.definition.tasks.length) {
-        return `Invalid task number ${taskNumber}`;
-      }
-      const task = spell.definition.tasks[taskNumber - 1];
-      if (task.done) return `Task ${taskNumber} is already done`;
-
-      const content = readFileSync(spell.filePath, "utf-8");
-      let count = 0;
-      const rewritten = content.replace(
-        /task\(("[^"]*"|'[^']*'|`[^`]*`)((?:\s*,\s*\{[^}]*\})?)\)/g,
-        (match, desc, opts) => {
-          count++;
-          if (count !== taskNumber) return match;
-          if (opts && opts.includes("done:")) {
-            return match.replace(/done:\s*false/, "done: true");
-          }
-          return `task(${desc}, { done: true })`;
-        },
-      );
-      if (rewritten === content) return `Could not rewrite task ${taskNumber}`;
-      writeFileSync(spell.filePath, rewritten);
-      return `Task ${taskNumber} marked done: "${task.description}"`;
-    },
-  };
-}

package/src/cli/registry.ts

@@ -18,6 +18,8 @@ export interface ParsedArgs {
   watch: boolean;
   verbose: boolean;
   help: boolean;
+  profile?: string;
+  report?: boolean;
 }
 
 /**

package/src/composite.ts

@@ -95,11 +95,16 @@ export function Composite<P, M extends CompositeMembers = CompositeMembers>(
       }
     }
 
-    const instance: CompositeInstance<M> = {
-      [COMPOSITE_MARKER]: true,
-      members,
-      _definition: definition,
-    };
+    // Define `members` and `_definition` as non-enumerable so spreading a
+    // composite instance (`...someComposite`) only exposes the actual member
+    // resources, not the framework's bookkeeping properties. Without this, a
+    // parent composite that does `...childResult` ends up with a `members` key
+    // pointing at the child's CompositeMembers record — not a Declarable —
+    // which then trips the parent's own member validation.
+    const instance = {} as CompositeInstance<M>;
+    Object.defineProperty(instance, COMPOSITE_MARKER, { value: true, enumerable: false });
+    Object.defineProperty(instance, "members", { value: members, enumerable: false });
+    Object.defineProperty(instance, "_definition", { value: definition, enumerable: false });
 
     return Object.assign(instance, members) as CompositeInstance<M> & M;
   }) as CompositeDefinition<P, M>;

package/src/index.ts

@@ -60,4 +60,7 @@ export * from "./lsp/types";
 export * from "./lsp/lexicon-providers";
 export * from "./mcp/types";
 export * from "./state/index";
-export * from "./spell/index";
+// Op builders — use explicit exports to avoid collision with the core `build` function
+export { Op, phase, activity, gate, kubectlApply, helmInstall, waitForStack,
+         gitlabPipeline, stateSnapshot, shell, teardown, OpResource } from "./op/index";
+export type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep } from "./op/index";

package/src/op/builders.ts

@@ -0,0 +1,96 @@
+import { OpResource } from "./resource";
+import type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep } from "./types";
+
+// ── Core builders ─────────────────────────────────────────────────────────────
+
+/**
+ * Declare a named, phased Temporal workflow.
+ *
+ * @example
+ * ```ts
+ * export default Op({
+ *   name: "alb-deploy",
+ *   overview: "Build and deploy the ALB multi-service stack",
+ *   phases: [
+ *     phase("Build", [build("examples/gitlab-aws-alb-infra")], { parallel: true }),
+ *     phase("Deploy", [kubectlApply("dist/alb-infra.yaml")]),
+ *   ],
+ * });
+ * ```
+ */
+export function Op(config: OpConfig): InstanceType<typeof OpResource> {
+  return new OpResource(config as unknown as Record<string, unknown>);
+}
+
+/** Define a named execution phase containing one or more steps. */
+export function phase(
+  name: string,
+  steps: StepDefinition[],
+  opts?: { parallel?: boolean },
+): PhaseDefinition {
+  return { name, steps, ...(opts?.parallel ? { parallel: true } : {}) };
+}
+
+/** Reference a pre-built or custom activity by function name. */
+export function activity(
+  fn: string,
+  args?: Record<string, unknown>,
+  profile?: ActivityStep["profile"],
+): ActivityStep {
+  return {
+    kind: "activity",
+    fn,
+    ...(args && Object.keys(args).length > 0 ? { args } : {}),
+    ...(profile ? { profile } : {}),
+  };
+}
+
+/** Insert a human gate — the workflow pauses until the named signal is received. */
+export function gate(
+  signalName: string,
+  opts?: { timeout?: string; description?: string },
+): GateStep {
+  return {
+    kind: "gate",
+    signalName,
+    ...(opts?.timeout ? { timeout: opts.timeout } : {}),
+    ...(opts?.description ? { description: opts.description } : {}),
+  };
+}
+
+// ── Pre-built activity shortcuts ──────────────────────────────────────────────
+
+/** Run `npm run build` (or `chant build`) in the given project directory. */
+export const build = (path: string, opts?: Record<string, unknown>): ActivityStep =>
+  activity("chantBuild", { path, ...opts });
+
+/** Run `kubectl apply -f <manifest>`. Uses `longInfra` profile. */
+export const kubectlApply = (manifest: string, opts?: Record<string, unknown>): ActivityStep =>
+  activity("kubectlApply", { manifest, ...opts }, "longInfra");
+
+/** Run `helm upgrade --install`. Uses `longInfra` profile. */
+export const helmInstall = (
+  name: string,
+  chart: string,
+  opts?: { values?: string; namespace?: string; [k: string]: unknown },
+): ActivityStep => activity("helmInstall", { name, chart, ...opts }, "longInfra");
+
+/** Poll for stack readiness (kubectl rollout, CloudFormation complete, etc). Uses `k8sWait` profile. */
+export const waitForStack = (name: string, opts?: Record<string, unknown>): ActivityStep =>
+  activity("waitForStack", { name, ...opts }, "k8sWait");
+
+/** Trigger and wait for a GitLab CI pipeline to complete. Uses `longInfra` profile. */
+export const gitlabPipeline = (name: string, opts?: Record<string, unknown>): ActivityStep =>
+  activity("gitlabPipeline", { name, ...opts }, "longInfra");
+
+/** Take a chant state snapshot for the given environment. */
+export const stateSnapshot = (env: string): ActivityStep =>
+  activity("stateSnapshot", { env });
+
+/** Run an arbitrary shell command. */
+export const shell = (cmd: string, opts?: { env?: Record<string, string> }): ActivityStep =>
+  activity("shellCmd", { cmd, ...opts });
+
+/** Run `chant teardown` in the given project directory. Uses `longInfra` profile. */
+export const teardown = (path: string): ActivityStep =>
+  activity("chantTeardown", { path }, "longInfra");

package/src/op/discover.test.ts

@@ -0,0 +1,43 @@
+import { describe, test, expect, vi, beforeEach } from "vitest";
+import { discoverOps } from "./discover";
+
+// Mock getRuntime to return git root pointing at the repo root
+vi.mock("../runtime-adapter", () => ({
+  getRuntime: () => ({
+    spawn: async (cmd: string[]) => {
+      if (cmd[0] === "git" && cmd[1] === "rev-parse") {
+        // Return the actual repo root so the test can find the example op file
+        const { execFile } = await import("node:child_process");
+        const { promisify } = await import("node:util");
+        const execFileAsync = promisify(execFile);
+        const { stdout } = await execFileAsync("git", ["rev-parse", "--show-toplevel"]);
+        return { stdout: stdout.trim(), stderr: "", exitCode: 0 };
+      }
+      return { stdout: "", stderr: "", exitCode: 0 };
+    },
+  }),
+}));
+
+describe("discoverOps", () => {
+  test("discovers alb-deploy.op.ts from examples/", async () => {
+    const { ops, errors } = await discoverOps();
+    expect(errors).toHaveLength(0);
+    expect(ops.has("alb-deploy")).toBe(true);
+  });
+
+  test("discovered Op has correct config shape", async () => {
+    const { ops } = await discoverOps();
+    const op = ops.get("alb-deploy");
+    expect(op).toBeDefined();
+    expect(op!.config.name).toBe("alb-deploy");
+    expect(Array.isArray(op!.config.phases)).toBe(true);
+    expect(op!.config.phases.length).toBeGreaterThan(0);
+    expect(typeof op!.config.overview).toBe("string");
+  });
+
+  test("filePath points to the .op.ts source file", async () => {
+    const { ops } = await discoverOps();
+    const op = ops.get("alb-deploy");
+    expect(op!.filePath).toMatch(/alb-deploy\.op\.ts$/);
+  });
+});

package/src/op/discover.ts

@@ -0,0 +1,89 @@
+import { getRuntime } from "../runtime-adapter";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+import type { OpConfig } from "./types";
+
+export interface DiscoveredOp {
+  config: OpConfig;
+  filePath: string;
+}
+
+export interface OpDiscoveryResult {
+  ops: Map<string, DiscoveredOp>;
+  errors: string[];
+}
+
+async function findGitRoot(cwd?: string): Promise<string> {
+  const rt = getRuntime();
+  const result = await rt.spawn(["git", "rev-parse", "--show-toplevel"], { cwd });
+  if (result.exitCode !== 0) throw new Error("Not in a git repository");
+  return result.stdout.trim();
+}
+
+async function collectOpFiles(dir: string): Promise<string[]> {
+  const files: string[] = [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return files;
+  }
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules" && entry.name !== "dist") {
+      files.push(...await collectOpFiles(fullPath));
+    } else if (
+      entry.isFile() &&
+      entry.name.endsWith(".op.ts") &&
+      !entry.name.endsWith(".test.ts") &&
+      !entry.name.endsWith(".spec.ts")
+    ) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+
+/**
+ * Discover all Op definitions from *.op.ts files under the git root.
+ */
+export async function discoverOps(opts?: { cwd?: string }): Promise<OpDiscoveryResult> {
+  const errors: string[] = [];
+  const ops = new Map<string, DiscoveredOp>();
+
+  const gitRoot = await findGitRoot(opts?.cwd);
+  const files = await collectOpFiles(gitRoot);
+
+  const nameToFile = new Map<string, string>();
+
+  for (const filePath of files) {
+    try {
+      const mod = await import(filePath);
+      const entity = mod.default;
+
+      if (!entity || typeof entity !== "object") {
+        errors.push(`${filePath}: default export is not an object`);
+        continue;
+      }
+
+      const config = entity.props as OpConfig | undefined;
+
+      if (!config || typeof config.name !== "string" || !Array.isArray(config.phases)) {
+        errors.push(`${filePath}: default export is not a valid Op (missing name or phases)`);
+        continue;
+      }
+
+      if (nameToFile.has(config.name)) {
+        errors.push(`Duplicate Op name "${config.name}" in ${filePath} and ${nameToFile.get(config.name)}`);
+        continue;
+      }
+
+      nameToFile.set(config.name, filePath);
+      ops.set(config.name, { config, filePath });
+    } catch (err) {
+      errors.push(`${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  return { ops, errors };
+}

package/src/op/index.ts

@@ -0,0 +1,6 @@
+export { Op, phase, activity, gate, build, kubectlApply, helmInstall, waitForStack,
+         gitlabPipeline, stateSnapshot, shell, teardown } from "./builders";
+export { OpResource } from "./resource";
+export type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep } from "./types";
+export { discoverOps } from "./discover";
+export type { DiscoveredOp, OpDiscoveryResult } from "./discover";

package/src/op/op.test.ts

@@ -0,0 +1,199 @@
+/**
+ * Core Op builder tests.
+ */
+
+import { describe, expect, it } from "vitest";
+import { Op, phase, activity, gate, build, kubectlApply, helmInstall,
+         waitForStack, gitlabPipeline, stateSnapshot, shell, teardown } from "./builders";
+import { DECLARABLE_MARKER, type Declarable } from "../declarable";
+
+// ── Op() ──────────────────────────────────────────────────────────────────────
+
+describe("Op()", () => {
+  function opProps(op: Declarable): Record<string, unknown> {
+    return (op as unknown as { props: Record<string, unknown> }).props;
+  }
+
+  it("returns a Declarable with correct lexicon and entityType", () => {
+    const op = Op({ name: "my-op", overview: "Test op", phases: [] });
+    expect(op[DECLARABLE_MARKER]).toBe(true);
+    expect(op.lexicon).toBe("temporal");
+    expect(op.entityType).toBe("Temporal::Op");
+    expect(op.kind).toBe("resource");
+  });
+
+  it("stores name and overview in props", () => {
+    const op = Op({ name: "deploy-op", overview: "Deploy infra", phases: [] });
+    const props = opProps(op);
+    expect(props.name).toBe("deploy-op");
+    expect(props.overview).toBe("Deploy infra");
+  });
+
+  it("stores phases in props", () => {
+    const p = phase("Build", [build("path/to/project")]);
+    const op = Op({ name: "op", overview: "o", phases: [p] });
+    const props = opProps(op);
+    expect(Array.isArray(props.phases)).toBe(true);
+    expect((props.phases as unknown[]).length).toBe(1);
+  });
+
+  it("stores optional depends in props", () => {
+    const op = Op({ name: "second-op", overview: "o", phases: [], depends: ["first-op"] });
+    const props = opProps(op);
+    expect(props.depends).toEqual(["first-op"]);
+  });
+
+  it("stores optional onFailure in props", () => {
+    const compensation = phase("Rollback", [shell("echo rollback")]);
+    const op = Op({ name: "op", overview: "o", phases: [], onFailure: [compensation] });
+    const props = opProps(op);
+    expect(Array.isArray(props.onFailure)).toBe(true);
+  });
+
+  it("stores optional taskQueue in props", () => {
+    const op = Op({ name: "op", overview: "o", phases: [], taskQueue: "custom-queue" });
+    const props = opProps(op);
+    expect(props.taskQueue).toBe("custom-queue");
+  });
+});
+
+// ── phase() ───────────────────────────────────────────────────────────────────
+
+describe("phase()", () => {
+  it("returns correct shape with name and steps", () => {
+    const p = phase("Deploy", [build("./")]);
+    expect(p.name).toBe("Deploy");
+    expect(p.steps).toHaveLength(1);
+  });
+
+  it("sets parallel: true when passed as option", () => {
+    const p = phase("Build", [build("a"), build("b")], { parallel: true });
+    expect(p.parallel).toBe(true);
+  });
+
+  it("omits parallel key when not set", () => {
+    const p = phase("Build", [build("a")]);
+    expect("parallel" in p).toBe(false);
+  });
+});
+
+// ── activity() ────────────────────────────────────────────────────────────────
+
+describe("activity()", () => {
+  it("returns ActivityStep with kind 'activity'", () => {
+    const a = activity("myFn");
+    expect(a.kind).toBe("activity");
+    expect(a.fn).toBe("myFn");
+  });
+
+  it("includes args when provided", () => {
+    const a = activity("myFn", { key: "val" });
+    expect(a.args).toEqual({ key: "val" });
+  });
+
+  it("omits args key when no args provided", () => {
+    const a = activity("myFn");
+    expect("args" in a).toBe(false);
+  });
+
+  it("includes profile when provided", () => {
+    const a = activity("myFn", {}, "longInfra");
+    expect(a.profile).toBe("longInfra");
+  });
+
+  it("omits profile key when not provided", () => {
+    const a = activity("myFn");
+    expect("profile" in a).toBe(false);
+  });
+});
+
+// ── gate() ────────────────────────────────────────────────────────────────────
+
+describe("gate()", () => {
+  it("returns GateStep with kind 'gate' and signalName", () => {
+    const g = gate("dns-delegation");
+    expect(g.kind).toBe("gate");
+    expect(g.signalName).toBe("dns-delegation");
+  });
+
+  it("includes timeout when provided", () => {
+    const g = gate("approval", { timeout: "24h" });
+    expect(g.timeout).toBe("24h");
+  });
+
+  it("includes description when provided", () => {
+    const g = gate("approval", { description: "Awaiting DNS delegation" });
+    expect(g.description).toBe("Awaiting DNS delegation");
+  });
+
+  it("omits timeout and description when not provided", () => {
+    const g = gate("sig");
+    expect("timeout" in g).toBe(false);
+    expect("description" in g).toBe(false);
+  });
+});
+
+// ── Pre-built shortcuts ───────────────────────────────────────────────────────
+
+describe("pre-built shortcuts", () => {
+  it("build() produces chantBuild activity with path arg", () => {
+    const a = build("./my-project");
+    expect(a.kind).toBe("activity");
+    expect(a.fn).toBe("chantBuild");
+    expect(a.args?.path).toBe("./my-project");
+  });
+
+  it("build() uses default fastIdempotent profile (no profile key)", () => {
+    const a = build("./p");
+    expect("profile" in a).toBe(false);
+  });
+
+  it("kubectlApply() produces kubectlApply activity with longInfra profile", () => {
+    const a = kubectlApply("dist/infra.yaml");
+    expect(a.fn).toBe("kubectlApply");
+    expect(a.args?.manifest).toBe("dist/infra.yaml");
+    expect(a.profile).toBe("longInfra");
+  });
+
+  it("helmInstall() produces helmInstall activity with name and chart", () => {
+    const a = helmInstall("my-release", "charts/app");
+    expect(a.fn).toBe("helmInstall");
+    expect(a.args?.name).toBe("my-release");
+    expect(a.args?.chart).toBe("charts/app");
+    expect(a.profile).toBe("longInfra");
+  });
+
+  it("waitForStack() produces waitForStack activity with k8sWait profile", () => {
+    const a = waitForStack("my-stack");
+    expect(a.fn).toBe("waitForStack");
+    expect(a.args?.name).toBe("my-stack");
+    expect(a.profile).toBe("k8sWait");
+  });
+
+  it("gitlabPipeline() produces gitlabPipeline activity with longInfra profile", () => {
+    const a = gitlabPipeline("group/project");
+    expect(a.fn).toBe("gitlabPipeline");
+    expect(a.args?.name).toBe("group/project");
+    expect(a.profile).toBe("longInfra");
+  });
+
+  it("stateSnapshot() produces stateSnapshot activity with env arg", () => {
+    const a = stateSnapshot("prod");
+    expect(a.fn).toBe("stateSnapshot");
+    expect(a.args?.env).toBe("prod");
+    expect("profile" in a).toBe(false);
+  });
+
+  it("shell() produces shellCmd activity with cmd arg", () => {
+    const a = shell("echo hello");
+    expect(a.fn).toBe("shellCmd");
+    expect(a.args?.cmd).toBe("echo hello");
+  });
+
+  it("teardown() produces chantTeardown activity with longInfra profile", () => {
+    const a = teardown("./project");
+    expect(a.fn).toBe("chantTeardown");
+    expect(a.args?.path).toBe("./project");
+    expect(a.profile).toBe("longInfra");
+  });
+});

package/src/op/resource.ts

@@ -0,0 +1,8 @@
+import { createResource } from "../runtime";
+
+/**
+ * The Declarable resource backing an Op definition.
+ * entityType: "Temporal::Op", lexicon: "temporal"
+ * Discovered automatically alongside infra files — no pipeline changes needed.
+ */
+export const OpResource = createResource("Temporal::Op", "temporal", {});

package/src/op/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Op type definitions — the data model for a named, phased Temporal workflow.
+ *
+ * These types are intentionally free of Temporal SDK imports so they can live
+ * in core without pulling in @temporalio/* as a dependency.
+ */
+
+export interface OpConfig {
+  /** Kebab-case identifier. Used as the workflow function name (camelCase) and output directory name. */
+  name: string;
+  /** Human-readable description shown in `chant run list` and deployment reports. */
+  overview: string;
+  /** Temporal task queue. Defaults to `name`. */
+  taskQueue?: string;
+  /** Temporal namespace. Defaults to chant.config.ts defaultProfile's namespace. */
+  namespace?: string;
+  /** Ordered list of execution phases. */
+  phases: PhaseDefinition[];
+  /** Other Op names that must be complete before this Op can run. */
+  depends?: string[];
+  /** Compensation phases executed on terminal failure (run in reverse order). */
+  onFailure?: PhaseDefinition[];
+  /** Search attributes to upsert at workflow start. */
+  searchAttributes?: Record<string, string>;
+}
+
+export interface PhaseDefinition {
+  /** Display name shown in progress output and Temporal UI. */
+  name: string;
+  /** Ordered steps within the phase. */
+  steps: StepDefinition[];
+  /** Run all steps concurrently via Promise.all. Default: false. */
+  parallel?: boolean;
+}
+
+export type StepDefinition = ActivityStep | GateStep;
+
+export interface ActivityStep {
+  kind: "activity";
+  /** Name of the exported activity function in the pre-built activity library. */
+  fn: string;
+  /** Arguments passed to the activity function. */
+  args?: Record<string, unknown>;
+  /**
+   * Key from TEMPORAL_ACTIVITY_PROFILES controlling timeout + retry.
+   * Default: "fastIdempotent"
+   */
+  profile?: "fastIdempotent" | "longInfra" | "k8sWait" | "humanGate";
+}
+
+export interface GateStep {
+  kind: "gate";
+  /** Signal name. The generated workflow waits for this signal before continuing. */
+  signalName: string;
+  /** Temporal duration string. Default: "48h". */
+  timeout?: string;
+  /** Human-readable description of the action required to unblock this gate. */
+  description?: string;
+}
+