@intentius/chant 0.1.7 → 0.1.9

package/src/cli/handlers/state.test.ts

@@ -0,0 +1,409 @@
+import { describe, test, expect, vi, beforeEach } from "vitest";
+import { createMockPlugin, staticDescribeResources, staticListArtifacts } from "@intentius/chant-test-utils";
+import type { LexiconPlugin, ResourceMetadata } from "../../lexicon";
+import type { BuildResult } from "../../build";
+import type { ParsedArgs } from "../registry";
+
+const buildMock = vi.fn();
+const fetchStateMock = vi.fn();
+const readSnapshotMock = vi.fn();
+const readEnvironmentSnapshotsMock = vi.fn();
+const listSnapshotsMock = vi.fn();
+const takeSnapshotMock = vi.fn();
+const loadChantConfigMock = vi.fn();
+
+vi.mock("../../build", () => ({ build: (...args: unknown[]) => buildMock(...args) }));
+vi.mock("../../state/git", () => ({
+  fetchState: () => fetchStateMock(),
+  readSnapshot: (...args: unknown[]) => readSnapshotMock(...args),
+  readEnvironmentSnapshots: (...args: unknown[]) => readEnvironmentSnapshotsMock(...args),
+  listSnapshots: (...args: unknown[]) => listSnapshotsMock(...args),
+}));
+vi.mock("../../state/snapshot", () => ({
+  takeSnapshot: (...args: unknown[]) => takeSnapshotMock(...args),
+}));
+vi.mock("../../config", () => ({
+  loadChantConfig: (...args: unknown[]) => loadChantConfigMock(...args),
+}));
+
+const { runStateDiff, runStateSnapshot, runStateShow, runStateLog, runStateUnknown } = await import("./state");
+
+function makeArgs(overrides: Partial<ParsedArgs>): ParsedArgs {
+  return {
+    command: "state",
+    path: "diff",
+    format: "",
+    fix: false,
+    watch: false,
+    verbose: false,
+    help: false,
+    live: false,
+    ...overrides,
+  };
+}
+
+function makeBuildResult(entitiesByLexicon: Record<string, string[]>): BuildResult {
+  const entities = new Map();
+  for (const [lexicon, names] of Object.entries(entitiesByLexicon)) {
+    for (const name of names) {
+      entities.set(name, { lexicon, entityType: `${lexicon}::Mock`, 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;
+}
+
+const meta = (overrides: Partial<ResourceMetadata> = {}): ResourceMetadata => ({
+  type: "AWS::S3::Bucket",
+  status: "CREATE_COMPLETE",
+  physicalId: "bucket-1",
+  ...overrides,
+});
+
+describe("runStateDiff --live", () => {
+  let stdoutSpy: ReturnType<typeof vi.spyOn>;
+  let stderrSpy: ReturnType<typeof vi.spyOn>;
+  let stdoutBuf: string[];
+  let stderrBuf: string[];
+
+  beforeEach(() => {
+    stdoutBuf = [];
+    stderrBuf = [];
+    stdoutSpy = vi.spyOn(console, "log").mockImplementation((s: string) => { stdoutBuf.push(s); });
+    stderrSpy = vi.spyOn(console, "error").mockImplementation((s: string) => { stderrBuf.push(s); });
+    buildMock.mockReset();
+    fetchStateMock.mockReset();
+    readSnapshotMock.mockReset();
+  });
+
+  test("surfaces drift between previous snapshot and live state", async () => {
+    buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"] }));
+    fetchStateMock.mockResolvedValue(undefined);
+    readSnapshotMock.mockResolvedValue(JSON.stringify({
+      lexicon: "aws",
+      environment: "prod",
+      commit: "abc",
+      timestamp: "2026-04-01T00:00:00Z",
+      resources: { bucket: meta({ status: "CREATE_COMPLETE" }) },
+    }));
+
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({
+        name: "aws",
+        describeResources: staticDescribeResources({
+          bucket: meta({ status: "UPDATE_COMPLETE" }),
+        }),
+      }),
+    ];
+
+    const ctx = {
+      args: makeArgs({ command: "state", path: "diff", extraPositional: "prod", live: true }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    };
+
+    const exit = await runStateDiff(ctx);
+
+    expect(exit).toBe(0);
+    const output = stdoutBuf.join("\n");
+    expect(output).toContain("DRIFTED");
+    expect(output).toContain("bucket");
+    expect(output).toContain("status:");
+    expect(output).toContain("CREATE_COMPLETE");
+    expect(output).toContain("UPDATE_COMPLETE");
+  });
+
+  test("warns and skips lexicons without describeResources", async () => {
+    buildMock.mockResolvedValue(makeBuildResult({ k8s: ["pod"] }));
+    fetchStateMock.mockResolvedValue(undefined);
+    readSnapshotMock.mockResolvedValue(null);
+
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({ name: "k8s" }),
+    ];
+
+    const ctx = {
+      args: makeArgs({ command: "state", path: "diff", extraPositional: "prod", live: true }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    };
+
+    const exit = await runStateDiff(ctx);
+
+    expect(exit).toBe(1);
+    const stderr = stderrBuf.join("\n");
+    expect(stderr).toContain("k8s");
+    expect(stderr).toContain("does not implement describeResources");
+  });
+
+  test("--live with a listArtifacts-only plugin diffs artifacts (no resources path)", async () => {
+    buildMock.mockResolvedValue(makeBuildResult({ helm: [] }));
+    fetchStateMock.mockResolvedValue(undefined);
+    // Previous snapshot has no artifact entry for the new release → expect ARTIFACTS ADDED
+    readSnapshotMock.mockResolvedValue(JSON.stringify({
+      lexicon: "helm",
+      environment: "prod",
+      commit: "x",
+      timestamp: "t",
+      resources: {},
+      artifacts: {},
+    }));
+
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({
+        name: "helm",
+        listArtifacts: staticListArtifacts({
+          "release/default/web": { type: "Helm::Release", physicalId: "default/web", status: "deployed" },
+        }),
+      }),
+    ];
+
+    const ctx = {
+      args: makeArgs({ command: "state", path: "diff", extraPositional: "prod", live: true }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    };
+
+    const exit = await runStateDiff(ctx);
+
+    expect(exit).toBe(0);
+    const output = stdoutBuf.join("\n");
+    expect(output).toContain("ARTIFACTS ADDED");
+    expect(output).toContain("release/default/web");
+  });
+
+  test("legacy digest mode still works without --live", async () => {
+    buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"] }));
+    fetchStateMock.mockResolvedValue(undefined);
+    readSnapshotMock.mockResolvedValue(null);
+
+    const plugins: LexiconPlugin[] = [createMockPlugin({ name: "aws" })];
+
+    const ctx = {
+      args: makeArgs({ command: "state", path: "diff", extraPositional: "prod", live: false }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    };
+
+    const exit = await runStateDiff(ctx);
+
+    expect(exit).toBe(0);
+    const output = stdoutBuf.join("\n");
+    expect(output).toContain("aws");
+    expect(output).toContain("bucket");
+    expect(output).toContain("added");
+  });
+});
+
+describe("runStateSnapshot", () => {
+  let stdoutBuf: string[];
+  let stderrBuf: string[];
+
+  beforeEach(() => {
+    stdoutBuf = [];
+    stderrBuf = [];
+    vi.spyOn(console, "log").mockImplementation((s: string) => { stdoutBuf.push(s); });
+    vi.spyOn(console, "error").mockImplementation((s: string) => { stderrBuf.push(s); });
+    buildMock.mockReset();
+    takeSnapshotMock.mockReset();
+    loadChantConfigMock.mockReset();
+    loadChantConfigMock.mockResolvedValue({ config: { environments: ["prod"] } });
+  });
+
+  test("missing environment arg → exit 1 with helpful message", async () => {
+    const ctx = {
+      args: makeArgs({ command: "state", path: "snapshot" }),
+      plugins: [],
+      serializers: [],
+    };
+    const exit = await runStateSnapshot(ctx);
+    expect(exit).toBe(1);
+    expect(stderrBuf.join("\n")).toContain("Environment is required");
+  });
+
+  test("environment not in config → exit 1", async () => {
+    const ctx = {
+      args: makeArgs({ command: "state", path: "snapshot", extraPositional: "unknown" }),
+      plugins: [],
+      serializers: [],
+    };
+    const exit = await runStateSnapshot(ctx);
+    expect(exit).toBe(1);
+    expect(stderrBuf.join("\n")).toContain('Unknown environment "unknown"');
+  });
+
+  test("no plugins implement describeResources → exit 1 with hint", async () => {
+    buildMock.mockResolvedValue(makeBuildResult({ aws: ["x"] }));
+    const plugins: LexiconPlugin[] = [createMockPlugin({ name: "aws" })];
+    const ctx = {
+      args: makeArgs({ command: "state", path: "snapshot", extraPositional: "prod" }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    };
+    const exit = await runStateSnapshot(ctx);
+    expect(exit).toBe(1);
+    expect(stderrBuf.join("\n")).toContain("No plugins implement describeResources");
+  });
+
+  test("happy path: writes snapshot via takeSnapshot and reports counts", async () => {
+    buildMock.mockResolvedValue(makeBuildResult({ aws: ["bucket"] }));
+    takeSnapshotMock.mockResolvedValue({
+      snapshots: [{ lexicon: "aws", environment: "prod", resources: { bucket: meta() } }],
+      commit: "sha",
+      warnings: [],
+      errors: [],
+    });
+    const plugins: LexiconPlugin[] = [
+      createMockPlugin({
+        name: "aws",
+        describeResources: staticDescribeResources({ bucket: meta() }),
+      }),
+    ];
+    const ctx = {
+      args: makeArgs({ command: "state", path: "snapshot", extraPositional: "prod" }),
+      plugins,
+      serializers: plugins.map((p) => p.serializer),
+    };
+    const exit = await runStateSnapshot(ctx);
+    expect(exit).toBe(0);
+    expect(stderrBuf.join("\n")).toContain("Snapshot saved");
+    expect(takeSnapshotMock).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("runStateShow", () => {
+  let stdoutBuf: string[];
+  let stderrBuf: string[];
+
+  beforeEach(() => {
+    stdoutBuf = [];
+    stderrBuf = [];
+    vi.spyOn(console, "log").mockImplementation((s: string) => { stdoutBuf.push(s); });
+    vi.spyOn(console, "error").mockImplementation((s: string) => { stderrBuf.push(s); });
+    fetchStateMock.mockReset();
+    readSnapshotMock.mockReset();
+    readEnvironmentSnapshotsMock.mockReset();
+  });
+
+  test("missing environment arg → exit 1", async () => {
+    const ctx = {
+      args: makeArgs({ command: "state", path: "show" }),
+      plugins: [], serializers: [],
+    };
+    expect(await runStateShow(ctx)).toBe(1);
+    expect(stderrBuf.join("\n")).toContain("Environment is required");
+  });
+
+  test("specific lexicon: prints snapshot table when found", async () => {
+    fetchStateMock.mockResolvedValue(undefined);
+    readSnapshotMock.mockResolvedValue(JSON.stringify({
+      lexicon: "aws", environment: "prod", commit: "x", timestamp: "t",
+      resources: { bucket: { type: "AWS::S3::Bucket", physicalId: "b-1", status: "OK" } },
+    }));
+    const ctx = {
+      args: makeArgs({ command: "state", path: "show", extraPositional: "prod", extraPositional2: "aws" }),
+      plugins: [], serializers: [],
+    };
+    expect(await runStateShow(ctx)).toBe(0);
+    const out = stdoutBuf.join("\n");
+    expect(out).toContain("bucket");
+    expect(out).toContain("AWS::S3::Bucket");
+  });
+
+  test("specific lexicon: returns 1 when no snapshot found", async () => {
+    fetchStateMock.mockResolvedValue(undefined);
+    readSnapshotMock.mockResolvedValue(null);
+    const ctx = {
+      args: makeArgs({ command: "state", path: "show", extraPositional: "prod", extraPositional2: "aws" }),
+      plugins: [], serializers: [],
+    };
+    expect(await runStateShow(ctx)).toBe(1);
+    expect(stderrBuf.join("\n")).toContain("No snapshot found");
+  });
+
+  test("no lexicon: lists all lexicons in env", async () => {
+    fetchStateMock.mockResolvedValue(undefined);
+    readEnvironmentSnapshotsMock.mockResolvedValue(new Map([
+      ["aws", JSON.stringify({ lexicon: "aws", environment: "prod", commit: "x", timestamp: "t", resources: {} })],
+      ["gcp", JSON.stringify({ lexicon: "gcp", environment: "prod", commit: "x", timestamp: "t", resources: {} })],
+    ]));
+    const ctx = {
+      args: makeArgs({ command: "state", path: "show", extraPositional: "prod" }),
+      plugins: [], serializers: [],
+    };
+    expect(await runStateShow(ctx)).toBe(0);
+    const out = stdoutBuf.join("\n");
+    expect(out).toContain("prod/aws");
+    expect(out).toContain("prod/gcp");
+  });
+});
+
+describe("runStateLog", () => {
+  let stdoutBuf: string[];
+  let stderrBuf: string[];
+
+  beforeEach(() => {
+    stdoutBuf = [];
+    stderrBuf = [];
+    vi.spyOn(console, "log").mockImplementation((s: string) => { stdoutBuf.push(s); });
+    vi.spyOn(console, "error").mockImplementation((s: string) => { stderrBuf.push(s); });
+    fetchStateMock.mockReset();
+    listSnapshotsMock.mockReset();
+  });
+
+  test("returns 1 with message when no entries exist", async () => {
+    fetchStateMock.mockResolvedValue(undefined);
+    listSnapshotsMock.mockResolvedValue([]);
+    const ctx = {
+      args: makeArgs({ command: "state", path: "log" }),
+      plugins: [], serializers: [],
+    };
+    expect(await runStateLog(ctx)).toBe(1);
+    expect(stderrBuf.join("\n")).toContain("No state snapshots");
+  });
+
+  test("prints commit / date / message rows for each entry", async () => {
+    fetchStateMock.mockResolvedValue(undefined);
+    listSnapshotsMock.mockResolvedValue([
+      { commit: "abcdef1234567890", date: "2026-05-01T00:00:00Z", message: "Snapshot prod" },
+      { commit: "fedcba9876543210", date: "2026-05-02T00:00:00Z", message: "Snapshot staging" },
+    ]);
+    const ctx = {
+      args: makeArgs({ command: "state", path: "log" }),
+      plugins: [], serializers: [],
+    };
+    expect(await runStateLog(ctx)).toBe(0);
+    const out = stdoutBuf.join("\n");
+    expect(out).toContain("abcdef1");
+    expect(out).toContain("Snapshot prod");
+    expect(out).toContain("Snapshot staging");
+  });
+});
+
+describe("runStateUnknown", () => {
+  test("returns 1 with subcommand list", async () => {
+    const stderrBuf: string[] = [];
+    vi.spyOn(console, "error").mockImplementation((s: string) => { stderrBuf.push(s); });
+    const ctx = {
+      args: makeArgs({ command: "state", path: "garbage" }),
+      plugins: [], serializers: [],
+    };
+    expect(await runStateUnknown(ctx)).toBe(1);
+    const stderr = stderrBuf.join("\n");
+    expect(stderr).toContain("snapshot");
+    expect(stderr).toContain("show");
+    expect(stderr).toContain("diff");
+    expect(stderr).toContain("log");
+  });
+});

package/src/cli/handlers/state.ts

@@ -1,12 +1,16 @@
 import { resolve } from "node:path";
 import { build } from "../../build";
 import { takeSnapshot } from "../../state/snapshot";
-import { readSnapshot, readEnvironmentSnapshots, listSnapshots, fetchState } from "../../state/git";
+import { readSnapshot, readEnvironmentSnapshots, listSnapshots, fetchState, StaleStateBranchError } from "../../state/git";
 import { computeBuildDigest, diffDigests } from "../../state/digest";
+import { diffLive, diffLiveArtifacts, type LiveDiffResult, type LiveArtifactDiffResult } from "../../state/live-diff";
 import { loadChantConfig } from "../../config";
 import { formatError, formatWarning, formatSuccess, formatBold } from "../format";
 import type { CommandContext } from "../registry";
 import type { StateSnapshot } from "../../state/types";
+import type { SerializerResult } from "../../serializer";
+import type { LexiconPlugin, ResourceMetadata, ArtifactMetadata } from "../../lexicon";
+import type { BuildResult } from "../../build";
 
 /**
  * chant state snapshot <environment> [lexicon]
@@ -45,16 +49,28 @@ export async function runStateSnapshot(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
-  const pluginsWithDescribe = targetPlugins.filter((p) => p.describeResources);
-  if (pluginsWithDescribe.length === 0) {
+  const observingPlugins = targetPlugins.filter((p) => p.describeResources || p.listArtifacts);
+  if (observingPlugins.length === 0) {
     console.error(formatError({
-      message: "No plugins implement describeResources",
+      message: "No plugins implement describeResources or listArtifacts",
       hint: lexiconFilter ? `Lexicon "${lexiconFilter}" does not support state snapshots` : undefined,
     }));
     return 1;
   }
 
-  const result = await takeSnapshot(environment, pluginsWithDescribe, buildResult);
+  let result;
+  try {
+    result = await takeSnapshot(environment, observingPlugins, buildResult);
+  } catch (err) {
+    if (err instanceof StaleStateBranchError) {
+      console.error(formatError({
+        message: `Another snapshot completed for chant/state after this run started (env: ${environment}).`,
+        hint: `Pull and retry: \`git fetch origin ${"chant/state"}:${"chant/state"}\` && \`chant state snapshot ${environment}\`.`,
+      }));
+      return 1;
+    }
+    throw err;
+  }
 
   for (const w of result.warnings) {
     console.error(formatWarning({ message: w }));
@@ -132,7 +148,7 @@ export async function runStateDiff(ctx: CommandContext): Promise<number> {
     ? plugins.filter((p) => p.name === lexiconFilter).map((p) => p.serializer)
     : serializers;
 
-  // Build to get current digest
+  // Build to get current state
   const projectPath = resolve(".");
   const buildResult = await build(projectPath, targetSerializers);
   if (buildResult.errors.length > 0) {
@@ -140,8 +156,6 @@ export async function runStateDiff(ctx: CommandContext): Promise<number> {
     return 1;
   }
 
-  const currentDigest = computeBuildDigest(buildResult);
-
   // Fetch and read previous snapshot
   await fetchState();
 
@@ -149,8 +163,24 @@ export async function runStateDiff(ctx: CommandContext): Promise<number> {
     ? [lexiconFilter]
     : Array.from(buildResult.manifest.lexicons);
 
-  for (const lexicon of lexicons) {
-    const content = await readSnapshot(environment, lexicon);
+  if (args.live) {
+    return runStateDiffLive({ environment, lexicons, plugins, buildResult });
+  }
+
+  return runStateDiffDigest({ environment, lexicons, buildResult });
+}
+
+interface DigestDiffArgs {
+  environment: string;
+  lexicons: string[];
+  buildResult: BuildResult;
+}
+
+async function runStateDiffDigest(args: DigestDiffArgs): Promise<number> {
+  const currentDigest = computeBuildDigest(args.buildResult);
+
+  for (const lexicon of args.lexicons) {
+    const content = await readSnapshot(args.environment, lexicon);
     let previousDigest = undefined;
     if (content) {
       const snapshot: StateSnapshot = JSON.parse(content);
@@ -180,6 +210,198 @@ export async function runStateDiff(ctx: CommandContext): Promise<number> {
   return 0;
 }
 
+interface LiveDiffArgs {
+  environment: string;
+  lexicons: string[];
+  plugins: LexiconPlugin[];
+  buildResult: BuildResult;
+}
+
+async function runStateDiffLive(args: LiveDiffArgs): Promise<number> {
+  let totalDrift = 0;
+  let totalLexiconsChecked = 0;
+
+  for (const lexiconName of args.lexicons) {
+    const plugin = args.plugins.find((p) => p.name === lexiconName);
+    if (!plugin) continue;
+
+    if (!plugin.describeResources && !plugin.listArtifacts) {
+      console.error(formatWarning({
+        message: `${lexiconName}: lexicon does not implement describeResources or listArtifacts — skipping (use without --live for digest diff)`,
+      }));
+      continue;
+    }
+
+    // Build per-lexicon entity index
+    const declared = new Set<string>();
+    const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
+    for (const [name, entity] of args.buildResult.entities) {
+      if (entity.lexicon === lexiconName) {
+        declared.add(name);
+        entities.set(name, {
+          entityType: entity.entityType,
+          props: ("props" in entity && entity.props != null
+            ? entity.props
+            : {}) as Record<string, unknown>,
+        });
+      }
+    }
+
+    const rawOutput = args.buildResult.outputs.get(lexiconName);
+    const buildOutput =
+      rawOutput === undefined
+        ? ""
+        : typeof rawOutput === "string"
+          ? rawOutput
+          : (rawOutput as SerializerResult).primary;
+
+    // Read previous snapshot once; both flows pull what they need.
+    let prevSnapshot: StateSnapshot | undefined;
+    const content = await readSnapshot(args.environment, lexiconName);
+    if (content) prevSnapshot = JSON.parse(content);
+
+    let lexiconChecked = false;
+
+    // ── Resources path (entity-keyed) ──────────────────────────────────────
+    if (plugin.describeResources) {
+      let observedNow: Record<string, ResourceMetadata>;
+      try {
+        observedNow = await plugin.describeResources({
+          environment: args.environment,
+          buildOutput,
+          entityNames: Array.from(declared),
+          entities,
+        });
+      } catch (err) {
+        console.error(formatError({
+          message: `${lexiconName}: describeResources failed — ${err instanceof Error ? err.message : String(err)}`,
+        }));
+        continue;
+      }
+      const observedThen = prevSnapshot?.resources;
+      const diff = diffLive({ declared, observedNow, observedThen });
+      totalDrift += diff.driftedSinceSnapshot.length + diff.missing.length + diff.orphan.length + diff.disappeared.length;
+      renderLiveDiff(lexiconName, args.environment, diff);
+      lexiconChecked = true;
+    }
+
+    // ── Artifacts path (context-keyed) ─────────────────────────────────────
+    if (plugin.listArtifacts) {
+      let observedNow: Record<string, ArtifactMetadata>;
+      try {
+        observedNow = await plugin.listArtifacts({ environment: args.environment, entities });
+      } catch (err) {
+        console.error(formatError({
+          message: `${lexiconName}: listArtifacts failed — ${err instanceof Error ? err.message : String(err)}`,
+        }));
+        continue;
+      }
+      const observedThen = prevSnapshot?.artifacts;
+      const adiff = diffLiveArtifacts({ observedNow, observedThen });
+      totalDrift += adiff.added.length + adiff.removed.length + adiff.changed.length;
+      renderLiveArtifactDiff(lexiconName, args.environment, adiff);
+      lexiconChecked = true;
+    }
+
+    if (lexiconChecked) totalLexiconsChecked++;
+  }
+
+  if (totalLexiconsChecked === 0) {
+    console.error(formatWarning({
+      message: "No lexicons implement describeResources or listArtifacts — nothing to diff in --live mode",
+    }));
+    return 1;
+  }
+
+  if (totalDrift === 0) {
+    console.error(formatSuccess(`No drift detected across ${totalLexiconsChecked} lexicon(s)`));
+  }
+
+  return 0;
+}
+
+function renderLiveDiff(lexiconName: string, environment: string, diff: LiveDiffResult): void {
+  const counts =
+    `${diff.missing.length} missing, ${diff.orphan.length} orphan, ` +
+    `${diff.disappeared.length} disappeared, ${diff.newlyObserved.length} newly observed, ` +
+    `${diff.driftedSinceSnapshot.length} drifted, ${diff.unchanged.length} unchanged`;
+
+  console.log(`\n${formatBold(lexiconName)} — environment: ${environment}`);
+  console.log(counts);
+  console.log("-".repeat(80));
+
+  if (diff.missing.length > 0) {
+    console.log(formatBold("\nMISSING (declared, not in cloud):"));
+    for (const name of diff.missing) console.log(`  - ${name}`);
+  }
+  if (diff.orphan.length > 0) {
+    console.log(formatBold("\nORPHAN (in cloud, not declared):"));
+    for (const name of diff.orphan) console.log(`  - ${name}`);
+  }
+  if (diff.disappeared.length > 0) {
+    console.log(formatBold("\nDISAPPEARED (in last snapshot, gone now):"));
+    for (const name of diff.disappeared) console.log(`  - ${name}`);
+  }
+  if (diff.newlyObserved.length > 0) {
+    console.log(formatBold("\nNEWLY OBSERVED (declared, observed, no prior snapshot):"));
+    for (const name of diff.newlyObserved) console.log(`  - ${name}`);
+  }
+  if (diff.driftedSinceSnapshot.length > 0) {
+    console.log(formatBold("\nDRIFTED (changed since last snapshot):"));
+    for (const drift of diff.driftedSinceSnapshot) {
+      console.log(`  - ${drift.name} (${drift.type})`);
+      for (const change of drift.changes) {
+        const oldStr = formatValue(change.oldValue);
+        const newStr = formatValue(change.newValue);
+        console.log(`      ${change.path}: ${oldStr} → ${newStr}`);
+      }
+    }
+  }
+}
+
+function formatValue(v: unknown): string {
+  if (v === undefined) return "<unset>";
+  if (typeof v === "string") return v.length > 60 ? v.slice(0, 57) + "..." : v;
+  const json = JSON.stringify(v);
+  return json.length > 60 ? json.slice(0, 57) + "..." : json;
+}
+
+function renderLiveArtifactDiff(lexiconName: string, environment: string, diff: LiveArtifactDiffResult): void {
+  // Skip emission entirely when there's nothing to show — keeps the output
+  // clean for lexicons that only implement describeResources.
+  if (diff.added.length === 0 && diff.removed.length === 0 && diff.changed.length === 0 && diff.unchanged.length === 0) {
+    return;
+  }
+
+  const counts =
+    `${diff.added.length} added, ${diff.removed.length} removed, ` +
+    `${diff.changed.length} changed, ${diff.unchanged.length} unchanged`;
+
+  console.log(`\n${formatBold(lexiconName)} (artifacts) — environment: ${environment}`);
+  console.log(counts);
+  console.log("-".repeat(80));
+
+  if (diff.added.length > 0) {
+    console.log(formatBold("\nARTIFACTS ADDED (in cloud now, not in last snapshot):"));
+    for (const name of diff.added) console.log(`  - ${name}`);
+  }
+  if (diff.removed.length > 0) {
+    console.log(formatBold("\nARTIFACTS REMOVED (in last snapshot, gone now):"));
+    for (const name of diff.removed) console.log(`  - ${name}`);
+  }
+  if (diff.changed.length > 0) {
+    console.log(formatBold("\nARTIFACTS CHANGED (metadata differs since last snapshot):"));
+    for (const drift of diff.changed) {
+      console.log(`  - ${drift.name} (${drift.type})`);
+      for (const change of drift.changes) {
+        const oldStr = formatValue(change.oldValue);
+        const newStr = formatValue(change.newValue);
+        console.log(`      ${change.path}: ${oldStr} → ${newStr}`);
+      }
+    }
+  }
+}
+
 /**
  * chant state log [environment]
  */