@intentius/chant 0.1.14 → 0.1.16

package/src/cli/handlers/{state.ts → lifecycle.ts}

@@ -1,27 +1,42 @@
 import { resolve } from "node:path";
 import { build } from "../../build";
-import { takeSnapshot } from "../../state/snapshot";
-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 { takeSnapshot } from "../../lifecycle/snapshot";
+import { readSnapshot, readEnvironmentSnapshots, listSnapshots, fetchLifecycle, StaleLifecycleBranchError } from "../../lifecycle/git";
+import { computeBuildDigest, diffDigests } from "../../lifecycle/digest";
+import { diffLive, diffLiveArtifacts, type LiveDiffResult, type LiveArtifactDiffResult } from "../../lifecycle/live-diff";
+import { buildChangeSet, renderChangeSet, type ChangeSet } from "../../lifecycle/change-set";
 import { loadChantConfig } from "../../config";
 import { formatError, formatWarning, formatSuccess, formatBold } from "../format";
 import type { CommandContext } from "../registry";
-import type { StateSnapshot } from "../../state/types";
+import type { LifecycleSnapshot } from "../../lifecycle/types";
 import type { SerializerResult } from "../../serializer";
-import type { LexiconPlugin, ResourceMetadata, ArtifactMetadata } from "../../lexicon";
+import type { ObservationLexicon, ResourceMetadata, ArtifactMetadata } from "../../lexicon";
 import type { BuildResult } from "../../build";
+import type { ParsedArgs } from "../registry";
+import type { ChantConfig } from "../../config";
 
 /**
- * chant state snapshot <environment> [lexicon]
+ * Resolve the build root for a lifecycle command. The project root (where
+ * chant.config.ts lives) is always ".", but the *build* can be scoped to a
+ * subdirectory so a mixed-layout project — chant `src/` next to app code with
+ * import side effects — only synthesizes its infra. Precedence: `--src` flag,
+ * then `config.sourceDir`, then "." (the root). Snapshot/diff/plan all use this
+ * so their build digests stay consistent.
  */
-export async function runStateSnapshot(ctx: CommandContext): Promise<number> {
+function resolveBuildRoot(args: ParsedArgs, config: ChantConfig): string {
+  return resolve(args.src ?? config.sourceDir ?? ".");
+}
+
+/**
+ * chant lifecycle snapshot <environment> [lexicon]
+ */
+export async function runLifecycleSnapshot(ctx: CommandContext): Promise<number> {
   const { args, plugins } = ctx;
   const environment = args.extraPositional;
   const lexiconFilter = args.extraPositional2;
 
   if (!environment) {
-    console.error(formatError({ message: "Environment is required: chant state snapshot <environment> [lexicon]" }));
+    console.error(formatError({ message: "Environment is required: chant lifecycle snapshot <environment> [lexicon]" }));
     return 1;
   }
 
@@ -43,7 +58,7 @@ export async function runStateSnapshot(ctx: CommandContext): Promise<number> {
   const targetSerializers = targetPlugins.map((p) => p.serializer);
 
   // Build first to get entity names and build output
-  const buildResult = await build(projectPath, targetSerializers);
+  const buildResult = await build(resolveBuildRoot(args, config), targetSerializers);
   if (buildResult.errors.length > 0) {
     console.error(formatError({ message: "Build failed — fix errors before taking a snapshot" }));
     return 1;
@@ -62,10 +77,10 @@ export async function runStateSnapshot(ctx: CommandContext): Promise<number> {
   try {
     result = await takeSnapshot(environment, observingPlugins, buildResult);
   } catch (err) {
-    if (err instanceof StaleStateBranchError) {
+    if (err instanceof StaleLifecycleBranchError) {
       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}\`.`,
+        message: `Another snapshot completed for chant/lifecycle after this run started (env: ${environment}).`,
+        hint: `Pull and retry: \`git fetch origin ${"chant/lifecycle"}:${"chant/lifecycle"}\` && \`chant lifecycle snapshot ${environment}\`.`,
       }));
       return 1;
     }
@@ -83,26 +98,26 @@ export async function runStateSnapshot(ctx: CommandContext): Promise<number> {
     const counts = result.snapshots
       .map((s) => `${s.lexicon}(${Object.keys(s.resources).length})`)
       .join(" ");
-    console.error(formatSuccess(`Snapshot saved to chant/state (${counts})`));
+    console.error(formatSuccess(`Snapshot saved to chant/lifecycle (${counts})`));
   }
 
   return result.errors.length > 0 && result.snapshots.length === 0 ? 1 : 0;
 }
 
 /**
- * chant state show <environment> [lexicon]
+ * chant lifecycle show <environment> [lexicon]
  */
-export async function runStateShow(ctx: CommandContext): Promise<number> {
+export async function runLifecycleShow(ctx: CommandContext): Promise<number> {
   const environment = ctx.args.extraPositional;
   const lexiconFilter = ctx.args.extraPositional2;
 
   if (!environment) {
-    console.error(formatError({ message: "Environment is required: chant state show <environment> [lexicon]" }));
+    console.error(formatError({ message: "Environment is required: chant lifecycle show <environment> [lexicon]" }));
     return 1;
   }
 
   // Fetch from remote first
-  await fetchState();
+  await fetchLifecycle();
 
   if (lexiconFilter) {
     const content = await readSnapshot(environment, lexiconFilter);
@@ -111,7 +126,7 @@ export async function runStateShow(ctx: CommandContext): Promise<number> {
       return 1;
     }
 
-    const snapshot: StateSnapshot = JSON.parse(content);
+    const snapshot: LifecycleSnapshot = JSON.parse(content);
     printSnapshotTable(snapshot);
   } else {
     const snapshots = await readEnvironmentSnapshots(environment);
@@ -121,7 +136,7 @@ export async function runStateShow(ctx: CommandContext): Promise<number> {
     }
 
     for (const [lexicon, content] of snapshots) {
-      const snapshot: StateSnapshot = JSON.parse(content);
+      const snapshot: LifecycleSnapshot = JSON.parse(content);
       console.log(`\n${formatBold(`${environment}/${lexicon}`)} — ${Object.keys(snapshot.resources).length} resources — ${snapshot.timestamp}`);
       printSnapshotTable(snapshot);
     }
@@ -131,15 +146,15 @@ export async function runStateShow(ctx: CommandContext): Promise<number> {
 }
 
 /**
- * chant state diff <environment> [lexicon]
+ * chant lifecycle diff <environment> [lexicon]
  */
-export async function runStateDiff(ctx: CommandContext): Promise<number> {
+export async function runLifecycleDiff(ctx: CommandContext): Promise<number> {
   const { args, plugins, serializers } = ctx;
   const environment = args.extraPositional;
   const lexiconFilter = args.extraPositional2;
 
   if (!environment) {
-    console.error(formatError({ message: "Environment is required: chant state diff <environment> [lexicon]" }));
+    console.error(formatError({ message: "Environment is required: chant lifecycle diff <environment> [lexicon]" }));
     return 1;
   }
 
@@ -148,26 +163,26 @@ export async function runStateDiff(ctx: CommandContext): Promise<number> {
     ? plugins.filter((p) => p.name === lexiconFilter).map((p) => p.serializer)
     : serializers;
 
-  // Build to get current state
-  const projectPath = resolve(".");
-  const buildResult = await build(projectPath, targetSerializers);
+  // Build to get current state (from the configured source root, not necessarily ".")
+  const { config } = await loadChantConfig(resolve("."));
+  const buildResult = await build(resolveBuildRoot(args, config), targetSerializers);
   if (buildResult.errors.length > 0) {
     console.error(formatError({ message: "Build failed — fix errors before diffing" }));
     return 1;
   }
 
   // Fetch and read previous snapshot
-  await fetchState();
+  await fetchLifecycle();
 
   const lexicons = lexiconFilter
     ? [lexiconFilter]
     : Array.from(buildResult.manifest.lexicons);
 
   if (args.live) {
-    return runStateDiffLive({ environment, lexicons, plugins, buildResult });
+    return runLifecycleDiffLive({ environment, lexicons, plugins, buildResult });
   }
 
-  return runStateDiffDigest({ environment, lexicons, buildResult });
+  return runLifecycleDiffDigest({ environment, lexicons, buildResult });
 }
 
 interface DigestDiffArgs {
@@ -176,14 +191,14 @@ interface DigestDiffArgs {
   buildResult: BuildResult;
 }
 
-async function runStateDiffDigest(args: DigestDiffArgs): Promise<number> {
+async function runLifecycleDiffDigest(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);
+      const snapshot: LifecycleSnapshot = JSON.parse(content);
       previousDigest = snapshot.digest;
     }
 
@@ -213,11 +228,11 @@ async function runStateDiffDigest(args: DigestDiffArgs): Promise<number> {
 interface LiveDiffArgs {
   environment: string;
   lexicons: string[];
-  plugins: LexiconPlugin[];
+  plugins: ObservationLexicon[];
   buildResult: BuildResult;
 }
 
-async function runStateDiffLive(args: LiveDiffArgs): Promise<number> {
+async function runLifecycleDiffLive(args: LiveDiffArgs): Promise<number> {
   let totalDrift = 0;
   let totalLexiconsChecked = 0;
 
@@ -256,7 +271,7 @@ async function runStateDiffLive(args: LiveDiffArgs): Promise<number> {
           : (rawOutput as SerializerResult).primary;
 
     // Read previous snapshot once; both flows pull what they need.
-    let prevSnapshot: StateSnapshot | undefined;
+    let prevSnapshot: LifecycleSnapshot | undefined;
     const content = await readSnapshot(args.environment, lexiconName);
     if (content) prevSnapshot = JSON.parse(content);
 
@@ -403,12 +418,123 @@ function renderLiveArtifactDiff(lexiconName: string, environment: string, diff:
 }
 
 /**
- * chant state log [environment]
+ * chant lifecycle plan <environment> [lexicon]
+ *
+ * Promote the live diff to a typed, read-only change set: per-entity
+ * create / update / delete / adopt / noop. Strictly read-only — never
+ * mutates, never deploys. Deletes are never proposed without ownership
+ * data (added in #121); an undeclared live resource is `adopt`.
+ */
+export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
+  const { args, plugins, serializers } = ctx;
+  const environment = args.extraPositional;
+  const lexiconFilter = args.extraPositional2;
+
+  if (!environment) {
+    console.error(formatError({ message: "Environment is required: chant lifecycle plan <environment> [lexicon]" }));
+    return 1;
+  }
+
+  const targetSerializers = lexiconFilter
+    ? plugins.filter((p) => p.name === lexiconFilter).map((p) => p.serializer)
+    : serializers;
+
+  const { config } = await loadChantConfig(resolve("."));
+  const buildResult = await build(resolveBuildRoot(args, config), targetSerializers);
+  if (buildResult.errors.length > 0) {
+    console.error(formatError({ message: "Build failed — fix errors before planning" }));
+    return 1;
+  }
+
+  await fetchLifecycle();
+
+  const lexicons = lexiconFilter ? [lexiconFilter] : Array.from(buildResult.manifest.lexicons);
+
+  const merged: ChangeSet = { env: environment, entries: [] };
+  let checked = 0;
+
+  for (const lexiconName of lexicons) {
+    const plugin = plugins.find((p) => p.name === lexiconName);
+    if (!plugin) continue;
+    if (!plugin.describeResources) {
+      // Plan is entity-keyed; artifact-only lexicons have no declared axis.
+      if (!args.json) {
+        console.error(formatWarning({
+          message: `${lexiconName}: lexicon does not implement describeResources — skipping (no declared axis to plan against)`,
+        }));
+      }
+      continue;
+    }
+
+    const declared = new Set<string>();
+    const entities = new Map<string, { entityType: string; props: Record<string, unknown> }>();
+    for (const [name, entity] of 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 = buildResult.outputs.get(lexiconName);
+    const buildOutput =
+      rawOutput === undefined
+        ? ""
+        : typeof rawOutput === "string"
+          ? rawOutput
+          : (rawOutput as SerializerResult).primary;
+
+    let observedNow: Record<string, ResourceMetadata>;
+    try {
+      observedNow = await plugin.describeResources({
+        environment,
+        buildOutput,
+        entityNames: Array.from(declared),
+        entities,
+        owned: args.owned,
+      });
+    } catch (err) {
+      console.error(formatError({
+        message: `${lexiconName}: describeResources failed — ${err instanceof Error ? err.message : String(err)}`,
+      }));
+      continue;
+    }
+
+    const content = await readSnapshot(environment, lexiconName);
+    const observedThen = content ? (JSON.parse(content) as LifecycleSnapshot).resources : undefined;
+
+    const cs = buildChangeSet(environment, { declared, observedNow, observedThen });
+    merged.entries.push(...cs.entries);
+    checked++;
+  }
+
+  if (checked === 0) {
+    console.error(formatWarning({
+      message: "No lexicons implement describeResources — nothing to plan",
+    }));
+    return 1;
+  }
+
+  merged.entries.sort((a, b) => a.name.localeCompare(b.name));
+
+  if (args.json) {
+    console.log(JSON.stringify(merged, null, 2));
+  } else {
+    console.log(renderChangeSet(merged));
+  }
+
+  return 0;
+}
+
+/**
+ * chant lifecycle log [environment]
  */
-export async function runStateLog(ctx: CommandContext): Promise<number> {
+export async function runLifecycleLog(ctx: CommandContext): Promise<number> {
   const environment = ctx.args.extraPositional;
 
-  await fetchState();
+  await fetchLifecycle();
 
   const entries = await listSnapshots({ environment });
   if (entries.length === 0) {
@@ -427,15 +553,15 @@ export async function runStateLog(ctx: CommandContext): Promise<number> {
 /**
  * Fallback for unknown state subcommands.
  */
-export async function runStateUnknown(ctx: CommandContext): Promise<number> {
+export async function runLifecycleUnknown(ctx: CommandContext): Promise<number> {
   console.error(formatError({
     message: `Unknown state subcommand: ${ctx.args.extraPositional ?? ctx.args.path}`,
-    hint: "Available: chant state snapshot, chant state show, chant state diff, chant state log",
+    hint: "Available: chant lifecycle snapshot, chant lifecycle show, chant lifecycle diff, chant lifecycle plan, chant lifecycle log",
   }));
   return 1;
 }
 
-function printSnapshotTable(snapshot: StateSnapshot): void {
+function printSnapshotTable(snapshot: LifecycleSnapshot): void {
   console.log("RESOURCE".padEnd(20) + "TYPE".padEnd(28) + "PHYSICAL ID".padEnd(44) + "STATUS");
   console.log("-".repeat(100));
 

package/src/cli/handlers/misc.ts

@@ -1,6 +1,7 @@
 import { listCommand, printListResult } from "../commands/list";
-import { importCommand, printImportResult } from "../commands/import";
-import { formatError, formatSuccess } from "../format";
+import { importCommand, importFromLive, printImportResult } from "../commands/import";
+import type { ResourceSelector } from "../../lexicon";
+import { formatError, formatSuccess, formatWarning } from "../format";
 import type { CommandContext } from "../registry";
 
 export async function runList(ctx: CommandContext): Promise<number> {
@@ -21,6 +22,34 @@ export async function runList(ctx: CommandContext): Promise<number> {
 }
 
 export async function runImport(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+
+  // `--from <env>` switches import from a template file to a live source.
+  if (args.migrateFrom) {
+    const selector: ResourceSelector | undefined =
+      args.selectType || args.selectName
+        ? { type: args.selectType, name: args.selectName }
+        : undefined;
+
+    // Live config may carry secrets into generated source — warn before writing.
+    console.error(formatWarning({
+      message: "Live import may emit sensitive values (keys, tokens, passwords) into generated source. Review before committing.",
+    }));
+
+    const result = await importFromLive({
+      environment: args.migrateFrom,
+      lexicon: args.lexicon,
+      output: args.output,
+      force: args.force,
+      selector,
+      owned: args.owned,
+      verbatim: args.verbatim,
+    });
+
+    printImportResult(result);
+    return result.success ? 0 : 1;
+  }
+
   const result = await importCommand({
     templatePath: ctx.args.path,
     output: ctx.args.output,

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

@@ -43,6 +43,9 @@ function makeArgs(overrides: Partial<ParsedArgs> = {}): ParsedArgs {
   return {
     command: "run", path: ".",
     format: "", fix: false, watch: false, verbose: false, help: false, live: false,
+    // These suites exercise the Temporal path; local mode is the CLI default,
+    // so opt in explicitly here. Local-mode behavior is covered separately below.
+    temporal: true,
     ...overrides,
   };
 }
@@ -446,3 +449,98 @@ describe("runOp", () => {
     }
   });
 });
+
+// ── local mode dispatcher + guards ──────────────────────────────────────────
+
+function localOp(name: string, steps: unknown[]) {
+  return [name, { config: { name, overview: `${name} overview`, phases: [{ name: "Phase", steps }] } }] as const;
+}
+
+describe("runOp dispatcher", () => {
+  beforeEach(() => {
+    discoverOpsMock.mockReset();
+    loadTemporalClientMock.mockReset();
+    loadChantConfigMock.mockReset();
+    resolveProfileMock.mockReset();
+    existsSyncMock.mockReset();
+    spawnChildMock.mockReset();
+  });
+
+  test("no flag → local executor (no Temporal client or worker spawned)", async () => {
+    discoverOpsMock.mockResolvedValue({
+      ops: new Map([localOp("hello", [{ kind: "activity", fn: "shellCmd", args: { cmd: "true" } }])]),
+      errors: [],
+    });
+    const stderrWrite = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    const exit = await runOp({ args: makeArgs({ path: "hello", temporal: false }), plugins: [], serializers: [] });
+    expect(exit).toBe(0);
+    expect(loadTemporalClientMock).not.toHaveBeenCalled();
+    expect(spawnChildMock).not.toHaveBeenCalled();
+    stderrWrite.mockRestore();
+  });
+
+  test("--temporal → Temporal path (missing worker.ts → exit 1)", async () => {
+    discoverOpsMock.mockResolvedValue({ ops: new Map([makeOp("hello")]), errors: [] });
+    loadChantConfigMock.mockResolvedValue({ config: {} });
+    resolveProfileMock.mockReturnValue({ address: "localhost:7233", namespace: "default", taskQueue: "q" });
+    existsSyncMock.mockReturnValue(false);
+    const stderr = makeStderrSpy();
+    const exit = await runOp({ args: makeArgs({ path: "hello", temporal: true }), plugins: [], serializers: [] });
+    expect(exit).toBe(1);
+    expect(stderr.join("\n")).toContain("worker.ts not found");
+  });
+
+  test("gate in local mode → fast-fail before execution, suggests --temporal", async () => {
+    discoverOpsMock.mockResolvedValue({
+      ops: new Map([localOp("gated", [{ kind: "gate", signalName: "approve-prod" }])]),
+      errors: [],
+    });
+    const stderr = makeStderrSpy();
+    const exit = await runOp({ args: makeArgs({ path: "gated", temporal: false }), plugins: [], serializers: [] });
+    expect(exit).toBe(1);
+    expect(stderr.join("\n")).toContain("--temporal");
+    expect(loadTemporalClientMock).not.toHaveBeenCalled();
+  });
+
+  test("--local and --temporal together → exit 1 before any work", async () => {
+    const stderr = makeStderrSpy();
+    const exit = await runOp({ args: makeArgs({ path: "hello", local: true, temporal: true }), plugins: [], serializers: [] });
+    expect(exit).toBe(1);
+    expect(stderr.join("\n")).toContain("mutually exclusive");
+    expect(discoverOpsMock).not.toHaveBeenCalled();
+    expect(loadTemporalClientMock).not.toHaveBeenCalled();
+  });
+
+  test("--json → structured result on stdout", async () => {
+    discoverOpsMock.mockResolvedValue({
+      ops: new Map([localOp("hello", [{ kind: "activity", fn: "shellCmd", args: { cmd: "true" } }])]),
+      errors: [],
+    });
+    const stdoutWrite = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+    vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    const exit = await runOp({ args: makeArgs({ path: "hello", temporal: false, json: true }), plugins: [], serializers: [] });
+    expect(exit).toBe(0);
+    const printed = stdoutWrite.mock.calls.map((c) => String(c[0])).join("");
+    const parsed = JSON.parse(printed.trim());
+    expect(parsed.op).toBe("hello");
+    expect(parsed.ok).toBe(true);
+    vi.restoreAllMocks();
+  });
+});
+
+describe("Temporal-only subcommand guards", () => {
+  const cases: Array<[string, (ctx: { args: ParsedArgs; plugins: never[]; serializers: never[] }) => Promise<number>]> = [
+    ["list", runOpList],
+    ["status", runOpStatus],
+    ["log", runOpLog],
+    ["signal", runOpSignal],
+    ["cancel", runOpCancel],
+  ];
+
+  test.each(cases)("run %s without --temporal → exit 1 + actionable message", async (_name, handler) => {
+    const stderr = makeStderrSpy();
+    const exit = await handler({ args: makeArgs({ temporal: false, extraPositional: "x", extraPositional2: "y" }), plugins: [], serializers: [] });
+    expect(exit).toBe(1);
+    expect(stderr.join("\n")).toContain("not available in local mode");
+  });
+});