@intentius/chant 0.1.6 → 0.1.8

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

@@ -1,4 +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, RetryPolicy } from "./types";
+export type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep } from "./types";
+export { discoverOps } from "./discover";
+export type { DiscoveredOp, OpDiscoveryResult } from "./discover";

package/src/op/types.ts

@@ -46,6 +46,19 @@ export interface ActivityStep {
    * Default: "fastIdempotent"
    */
   profile?: "fastIdempotent" | "longInfra" | "k8sWait" | "humanGate";
+  /**
+   * Surface this activity's return value as a workflow search attribute.
+   *
+   * The serializer captures the awaited result into a temporary, then emits
+   * `upsertSearchAttributes({ <name>: [String(<from-path>)] })` immediately
+   * after. Useful for filtering runs by outcome (e.g. `Drift: "true"/"false"`
+   * from a stateDiff activity).
+   *
+   * `from` is a dot-path into the return value (e.g. `"drifted"` for
+   * `{ drifted: boolean }`); when omitted, the whole return value is
+   * stringified.
+   */
+  outcomeAttribute?: { name: string; from?: string };
 }
 
 export interface GateStep {
@@ -58,9 +71,3 @@ export interface GateStep {
   description?: string;
 }
 
-export interface RetryPolicy {
-  initialInterval?: string;
-  backoffCoefficient?: number;
-  maximumAttempts?: number;
-  maximumInterval?: string;
-}

package/src/state/digest.test.ts

@@ -0,0 +1,117 @@
+import { describe, test, expect } from "vitest";
+import { computeBuildDigest, diffDigests, hashProps } from "./digest";
+import type { BuildResult } from "../build";
+import type { BuildDigest } from "./types";
+
+function makeBuildResult(entitiesByLexicon: Record<string, Array<{ name: string; type: string; props: unknown }>>): BuildResult {
+  const entities = new Map();
+  for (const [lexicon, list] of Object.entries(entitiesByLexicon)) {
+    for (const item of list) {
+      entities.set(item.name, { lexicon, entityType: item.type, props: item.props });
+    }
+  }
+  return {
+    outputs: new Map(Object.keys(entitiesByLexicon).map((l) => [l, "{}"])),
+    entities,
+    dependencies: new Map(),
+    errors: [],
+    warnings: [],
+    manifest: {
+      lexicons: Object.keys(entitiesByLexicon),
+      outputs: {},
+      deployOrder: Object.keys(entitiesByLexicon),
+    },
+    sourceFileCount: 1,
+  } as unknown as BuildResult;
+}
+
+describe("hashProps", () => {
+  test("produces the same hash for identical props", () => {
+    expect(hashProps({ a: 1, b: 2 })).toBe(hashProps({ a: 1, b: 2 }));
+  });
+
+  test("is order-independent (sorted JSON serialization)", () => {
+    expect(hashProps({ a: 1, b: 2 })).toBe(hashProps({ b: 2, a: 1 }));
+  });
+
+  test("produces different hashes for different props", () => {
+    expect(hashProps({ a: 1 })).not.toBe(hashProps({ a: 2 }));
+  });
+});
+
+describe("computeBuildDigest", () => {
+  test("emits one entry per entity with type, lexicon, and propsHash", () => {
+    const buildResult = makeBuildResult({
+      aws: [{ name: "bucket", type: "AWS::S3::Bucket", props: { name: "data" } }],
+    });
+    const digest = computeBuildDigest(buildResult);
+    expect(digest.resources["bucket"]).toMatchObject({
+      type: "AWS::S3::Bucket",
+      lexicon: "aws",
+      propsHash: expect.any(String),
+    });
+  });
+
+  test("missing props default to empty object", () => {
+    const buildResult = makeBuildResult({ aws: [{ name: "x", type: "T", props: undefined }] });
+    const digest = computeBuildDigest(buildResult);
+    expect(digest.resources["x"].propsHash).toBe(hashProps({}));
+  });
+
+  test("mirrors the build manifest's deployOrder and outputs", () => {
+    const buildResult = makeBuildResult({
+      aws: [{ name: "b", type: "T", props: {} }],
+      gcp: [{ name: "g", type: "T", props: {} }],
+    });
+    const digest = computeBuildDigest(buildResult);
+    expect(digest.deployOrder).toEqual(["aws", "gcp"]);
+    expect(digest.outputs).toEqual({});
+  });
+});
+
+describe("diffDigests", () => {
+  function makeDigest(resources: Record<string, string>): BuildDigest {
+    const out: BuildDigest["resources"] = {};
+    for (const [name, propsHash] of Object.entries(resources)) {
+      out[name] = { type: "T", lexicon: "aws", propsHash };
+    }
+    return { resources: out, dependencies: {}, outputs: {}, deployOrder: [] };
+  }
+
+  test("no previous digest → everything is added", () => {
+    const result = diffDigests(makeDigest({ a: "x", b: "y" }), undefined);
+    expect(result.added).toEqual(["a", "b"]);
+    expect(result.removed).toEqual([]);
+    expect(result.changed).toEqual([]);
+    expect(result.unchanged).toEqual([]);
+  });
+
+  test("identical digests → all unchanged", () => {
+    const d = makeDigest({ a: "x" });
+    const result = diffDigests(d, d);
+    expect(result.unchanged).toEqual(["a"]);
+    expect(result.added).toEqual([]);
+    expect(result.changed).toEqual([]);
+    expect(result.removed).toEqual([]);
+  });
+
+  test("different propsHash → changed", () => {
+    const result = diffDigests(makeDigest({ a: "x2" }), makeDigest({ a: "x1" }));
+    expect(result.changed).toEqual(["a"]);
+  });
+
+  test("resource gone from current → removed", () => {
+    const result = diffDigests(makeDigest({}), makeDigest({ a: "x" }));
+    expect(result.removed).toEqual(["a"]);
+  });
+
+  test("mixed: added + removed + changed + unchanged", () => {
+    const previous = makeDigest({ a: "x1", b: "y", c: "z" });
+    const current = makeDigest({ a: "x2", b: "y", d: "w" });
+    const result = diffDigests(current, previous);
+    expect(result.added.sort()).toEqual(["d"]);
+    expect(result.changed.sort()).toEqual(["a"]);
+    expect(result.unchanged.sort()).toEqual(["b"]);
+    expect(result.removed.sort()).toEqual(["c"]);
+  });
+});

package/src/state/git.test.ts

@@ -0,0 +1,191 @@
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  writeSnapshot,
+  readSnapshot,
+  readEnvironmentSnapshots,
+  listSnapshots,
+  getHeadCommit,
+  pushState,
+  StaleStateBranchError,
+} from "./git";
+
+function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  return { stdout: r.stdout ?? "", exitCode: r.status ?? -1 };
+}
+
+async function initRepo(dir: string): Promise<void> {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "test@chant.dev"], dir);
+  git(["config", "user.name", "Test"], dir);
+  // Need at least one commit so HEAD exists.
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(["add", "README.md"], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+}
+
+describe("state/git", () => {
+  test("writeSnapshot creates the orphan branch and writes JSON addressable by readSnapshot", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const json = JSON.stringify({ resources: { bucket: { type: "T", status: "OK" } } });
+      const sha = await writeSnapshot("prod", "aws", json, { cwd: dir });
+      expect(sha).toMatch(/^[0-9a-f]{40}$/);
+
+      const out = await readSnapshot("prod", "aws", { cwd: dir });
+      expect(out).not.toBeNull();
+      expect(JSON.parse(out!)).toEqual(JSON.parse(json));
+    });
+  });
+
+  test("readSnapshot returns null for missing env/lexicon", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const out = await readSnapshot("prod", "aws", { cwd: dir });
+      expect(out).toBeNull();
+    });
+  });
+
+  test("subsequent writes preserve other env+lexicon entries", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: dir });
+      await writeSnapshot("prod", "gcp", JSON.stringify({ b: 2 }), { cwd: dir });
+      await writeSnapshot("staging", "aws", JSON.stringify({ c: 3 }), { cwd: dir });
+
+      expect(await readSnapshot("prod", "aws", { cwd: dir })).toBeTruthy();
+      expect(await readSnapshot("prod", "gcp", { cwd: dir })).toBeTruthy();
+      expect(await readSnapshot("staging", "aws", { cwd: dir })).toBeTruthy();
+    });
+  });
+
+  test("re-writing the same env+lexicon updates the entry rather than duplicating", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await writeSnapshot("prod", "aws", JSON.stringify({ v: 1 }), { cwd: dir });
+      await writeSnapshot("prod", "aws", JSON.stringify({ v: 2 }), { cwd: dir });
+      const out = await readSnapshot("prod", "aws", { cwd: dir });
+      expect(JSON.parse(out!)).toEqual({ v: 2 });
+    });
+  });
+
+  test("readEnvironmentSnapshots returns all lexicons for an env", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: dir });
+      await writeSnapshot("prod", "gcp", JSON.stringify({ b: 2 }), { cwd: dir });
+      const all = await readEnvironmentSnapshots("prod", { cwd: dir });
+      expect([...all.keys()].sort()).toEqual(["aws", "gcp"]);
+    });
+  });
+
+  test("listSnapshots returns commit history of the orphan branch", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await writeSnapshot("prod", "aws", JSON.stringify({ v: 1 }), { cwd: dir });
+      await writeSnapshot("prod", "aws", JSON.stringify({ v: 2 }), { cwd: dir });
+      const log = await listSnapshots({ cwd: dir });
+      expect(log.length).toBe(2);
+      expect(log[0].commit).toMatch(/^[0-9a-f]{40}$/);
+    });
+  });
+
+  test("getHeadCommit returns the working-branch HEAD sha", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const head = await getHeadCommit({ cwd: dir });
+      expect(head).toMatch(/^[0-9a-f]{40}$/);
+    });
+  });
+
+  // ── Concurrent push rejection (#30) ─────────────────────────────────────────
+
+  /**
+   * Build a "remote ↔ clone" pair where `clone` has `remote` configured as
+   * `origin`. Returns the clone path; the caller writes snapshots there.
+   */
+  async function setupClonePair(): Promise<{ clonePath: string; remotePath: string; cleanup: () => Promise<void> }> {
+    const remotePath = join(import.meta.dirname ?? "/tmp", `chant-state-remote-${Date.now()}-${Math.random()}`);
+    const clonePath = join(import.meta.dirname ?? "/tmp", `chant-state-clone-${Date.now()}-${Math.random()}`);
+    const { mkdir, rm } = await import("node:fs/promises");
+    await mkdir(remotePath, { recursive: true });
+    git(["init", "-q", "--bare", "-b", "main"], remotePath);
+    git(["clone", "-q", remotePath, clonePath], import.meta.dirname ?? "/tmp");
+    git(["config", "user.email", "test@chant.dev"], clonePath);
+    git(["config", "user.name", "Test"], clonePath);
+    writeFileSync(join(clonePath, "README.md"), "fixture\n");
+    git(["add", "README.md"], clonePath);
+    git(["commit", "-q", "-m", "init"], clonePath);
+    git(["push", "-q", "origin", "main"], clonePath);
+    return {
+      clonePath,
+      remotePath,
+      cleanup: async () => {
+        await rm(remotePath, { recursive: true, force: true });
+        await rm(clonePath, { recursive: true, force: true });
+      },
+    };
+  }
+
+  test("first push to remote succeeds (no remote ref yet)", async () => {
+    const { clonePath, cleanup } = await setupClonePair();
+    try {
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: clonePath });
+      const ok = await pushState({ cwd: clonePath });
+      expect(ok).toBe(true);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test("subsequent push from same clone (after fetch) succeeds via lease", async () => {
+    const { clonePath, cleanup } = await setupClonePair();
+    try {
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: clonePath });
+      expect(await pushState({ cwd: clonePath })).toBe(true);
+
+      // Pull the remote ref into local remote-tracking, then commit + push again
+      git(["fetch", "-q", "origin", "+refs/heads/chant/state:refs/remotes/origin/chant/state"], clonePath);
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 2 }), { cwd: clonePath });
+      expect(await pushState({ cwd: clonePath })).toBe(true);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test("concurrent write rejected: second push throws StaleStateBranchError", async () => {
+    // Simulate two concurrent operators by setting up two clones of the same remote.
+    const { clonePath: cloneA, remotePath, cleanup } = await setupClonePair();
+    const cloneB = join(import.meta.dirname ?? "/tmp", `chant-state-clone-b-${Date.now()}-${Math.random()}`);
+    try {
+      git(["clone", "-q", remotePath, cloneB], import.meta.dirname ?? "/tmp");
+      git(["config", "user.email", "test@chant.dev"], cloneB);
+      git(["config", "user.name", "Test"], cloneB);
+
+      // Operator A writes + pushes first.
+      await writeSnapshot("prod", "aws", JSON.stringify({ a: 1 }), { cwd: cloneA });
+      expect(await pushState({ cwd: cloneA })).toBe(true);
+
+      // Operator B writes from the same baseline (chant/state doesn't exist
+      // on cloneB's remote-tracking yet) and tries to push — should fail
+      // with StaleStateBranchError because A's push moved the remote ref.
+      await writeSnapshot("staging", "gcp", JSON.stringify({ b: 2 }), { cwd: cloneB });
+      await expect(pushState({ cwd: cloneB })).rejects.toBeInstanceOf(StaleStateBranchError);
+    } finally {
+      await cleanup();
+      const { rm } = await import("node:fs/promises");
+      await rm(cloneB, { recursive: true, force: true });
+    }
+  });
+
+  test("StaleStateBranchError carries the expected SHA used as the lease", async () => {
+    const err = new StaleStateBranchError(null, "stale info: ...");
+    expect(err.name).toBe("StaleStateBranchError");
+    expect(err.expected).toBeNull();
+    expect(err.message).toContain("moved");
+  });
+});

package/src/state/git.ts

@@ -22,13 +22,8 @@ export async function writeSnapshot(
   const rt = getRuntime();
   const cwd = opts?.cwd;
 
-  // 1. Write blob
-  const hashResult = await rt.spawn(
-    ["git", "hash-object", "-w", "--stdin"],
-    { cwd },
-  );
-  // hash-object reads from stdin, but spawn doesn't support piping directly.
-  // Use a shell pipeline instead.
+  // 1. Write blob — hash-object reads from stdin, but spawn() doesn't expose
+  // a stdin handle, so we run via a shell pipeline (`echo … | git hash-object`).
   const blobResult = await rt.spawn(
     ["sh", "-c", `echo '${json.replace(/'/g, "'\\''")}' | git hash-object -w --stdin`],
     { cwd },
@@ -179,20 +174,77 @@ export async function listSnapshots(
 }
 
 /**
- * Push the state branch to remote.
+ * Thrown by pushState when the remote chant/state branch has moved since
+ * the local snapshot was prepared — i.e. another snapshot for this or a
+ * different env was pushed concurrently. The caller should fetch and retry.
+ */
+export class StaleStateBranchError extends Error {
+  readonly expected: string | null;
+  constructor(expected: string | null, stderr: string) {
+    super(
+      "chant/state remote branch has moved since this run started — " +
+      "another snapshot was pushed concurrently. " +
+      `git stderr: ${stderr.trim()}`,
+    );
+    this.name = "StaleStateBranchError";
+    this.expected = expected;
+  }
+}
+
+/**
+ * Look up the remote-tracking SHA for chant/state, if any. Returns null when
+ * the remote ref doesn't exist locally yet (e.g. first-ever snapshot).
+ */
+export async function getRemoteStateBranchSha(
+  remote: string,
+  opts?: { cwd?: string },
+): Promise<string | null> {
+  const rt = getRuntime();
+  const ref = `refs/remotes/${remote}/${STATE_BRANCH}`;
+  const result = await rt.spawn(["git", "rev-parse", "--verify", ref], { cwd: opts?.cwd });
+  if (result.exitCode !== 0) return null;
+  return result.stdout.trim() || null;
+}
+
+/**
+ * Push the state branch to remote with --force-with-lease.
+ *
+ * If the remote chant/state ref has advanced past the local remote-tracking
+ * SHA captured at the start of this push, the push is rejected and we throw
+ * StaleStateBranchError so the caller can surface a recovery hint.
+ *
+ * Returns false (without throwing) only when no remote is configured at all.
  */
 export async function pushState(opts?: { cwd?: string }): Promise<boolean> {
   const rt = getRuntime();
-  // Check if remote exists
   const remoteResult = await rt.spawn(["git", "remote"], { cwd: opts?.cwd });
   if (remoteResult.exitCode !== 0 || !remoteResult.stdout.trim()) return false;
 
   const remote = remoteResult.stdout.trim().split("\n")[0];
+
+  // Capture the lease SHA — if null, the remote ref doesn't exist yet
+  // (first-time push) and we send `--force-with-lease=ref:` (empty SHA),
+  // which git interprets as "ref does not exist on remote".
+  const expected = await getRemoteStateBranchSha(remote, opts);
+  const lease = `refs/heads/${STATE_BRANCH}:${expected ?? ""}`;
+
   const pushResult = await rt.spawn(
-    ["git", "push", remote, `${STATE_BRANCH}:${STATE_BRANCH}`],
+    ["git", "push", `--force-with-lease=${lease}`, remote, `${STATE_BRANCH}:${STATE_BRANCH}`],
     { cwd: opts?.cwd },
   );
-  return pushResult.exitCode === 0;
+
+  if (pushResult.exitCode !== 0) {
+    const stderr = pushResult.stderr ?? "";
+    if (
+      stderr.includes("stale info") ||
+      stderr.includes("rejected") ||
+      stderr.includes("non-fast-forward")
+    ) {
+      throw new StaleStateBranchError(expected, stderr);
+    }
+    return false;
+  }
+  return true;
 }
 
 /**