@intentius/chant 0.1.14 → 0.1.16

package/src/codegen/fetch.ts

@@ -20,6 +20,66 @@ export interface FetchConfig {
   cacheTtlMs?: number;
 }
 
+// ── Transient-aware fetch ──────────────────────────────────────────
+
+/**
+ * HTTP statuses worth retrying. These are transient: a gateway hiccup,
+ * a rate limit, or an overloaded upstream — not a permanent 404/403.
+ */
+const RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
+
+const DEFAULT_RETRIES = 4;
+const DEFAULT_BACKOFF_MS = 1000;
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Fetch a URL, retrying on transient failures (network errors and
+ * retryable HTTP statuses) with exponential backoff.
+ *
+ * Permanent failures (e.g. 404, 403) are not retried — they throw on the
+ * first response. The returned response is guaranteed `ok`.
+ *
+ * `init` is passed through to `fetch` on every attempt, so callers that
+ * need request headers (e.g. the GitHub API `Accept` header) or an abort
+ * signal get retries without duplicating the loop.
+ */
+export async function fetchWithRetry(
+  url: string,
+  retries = DEFAULT_RETRIES,
+  backoffMs = DEFAULT_BACKOFF_MS,
+  init?: RequestInit,
+): Promise<Response> {
+  let lastError: Error | undefined;
+
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    if (attempt > 0) {
+      const delay = backoffMs * 2 ** (attempt - 1);
+      debug(`retrying ${url} (attempt ${attempt}/${retries}) after ${delay}ms: ${lastError?.message}`);
+      await sleep(delay);
+    }
+
+    let response: Response;
+    try {
+      response = init === undefined ? await fetch(url) : await fetch(url, init);
+    } catch (e) {
+      // Network-level failure (DNS, connection reset, timeout). Transient.
+      lastError = e instanceof Error ? e : new Error(String(e));
+      continue;
+    }
+
+    if (response.ok) return response;
+
+    const err = new Error(`Download from ${url} returned ${response.status}`);
+    if (!RETRYABLE_STATUSES.has(response.status)) throw err;
+    lastError = err;
+  }
+
+  throw lastError ?? new Error(`Download from ${url} failed after ${retries} retries`);
+}
+
 // ── Fetch with cache ───────────────────────────────────────────────
 
 const DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
@@ -46,11 +106,7 @@ export async function fetchWithCache(config: FetchConfig, force = false): Promis
     }
   }
 
-  const response = await fetch(config.url);
-  if (!response.ok) {
-    throw new Error(`Download from ${config.url} returned ${response.status}`);
-  }
-
+  const response = await fetchWithRetry(config.url);
   const arrayBuffer = await response.arrayBuffer();
   const data = Buffer.from(arrayBuffer);
 
@@ -205,11 +261,7 @@ export async function fetchAndExtractTar(
     }
   }
 
-  const resp = await fetch(config.url);
-  if (!resp.ok) {
-    throw new Error(`Tarball download from ${config.url} returned ${resp.status}`);
-  }
-
+  const resp = await fetchWithRetry(config.url);
   const compressed = new Uint8Array(await resp.arrayBuffer());
   const { gunzipSync } = await import("fflate");
   const tarData = gunzipSync(compressed);

package/src/config.ts

@@ -2,6 +2,7 @@ import { existsSync } from "fs";
 import { join } from "path";
 import { z } from "zod";
 import type { LintConfig } from "./lint/config";
+import type { OwnershipMarker } from "./ownership";
 
 /**
  * Zod schema for ChantConfig validation.
@@ -9,7 +10,13 @@ import type { LintConfig } from "./lint/config";
 export const ChantConfigSchema = z.object({
   lexicons: z.array(z.string().min(1)).optional(),
   environments: z.array(z.string().min(1)).optional(),
+  sourceDir: z.string().min(1).optional(),
   lint: z.record(z.string(), z.unknown()).optional(),
+  ownership: z.object({
+    stack: z.string().min(1).optional(),
+    env: z.string().min(1).optional(),
+    enabled: z.boolean().optional(),
+  }).optional(),
 }).passthrough();
 
 /**
@@ -24,8 +31,32 @@ export interface ChantConfig {
   /** Environment names (e.g. ["staging", "prod"]) */
   environments?: string[];
 
+  /**
+   * Directory (relative to the project root) that holds the chant infrastructure
+   * source. Lifecycle commands (`snapshot`/`diff`/`plan`) build from here instead
+   * of the project root, so a mixed-layout project — chant `src/` alongside app
+   * code that has import side effects — can scope the build to just the infra.
+   * Defaults to "." (the project root). The `--src` flag overrides it.
+   */
+  sourceDir?: string;
+
   /** Lint configuration (rules, extends, overrides, plugins) */
   lint?: LintConfig;
+
+  /**
+   * Opt-in cloud-side ownership marking. When `stack` is set (and `enabled`
+   * is not false), the serializer stamps a chant ownership marker carrying
+   * this stack/env identity onto every supported resource. See {@link
+   * resolveOwnershipMarker}.
+   */
+  ownership?: {
+    /** Stack identity stamped onto resources (required to enable stamping). */
+    stack?: string;
+    /** Optional environment identity. */
+    env?: string;
+    /** Set false to disable stamping even when `stack` is present. */
+    enabled?: boolean;
+  };
 }
 
 /**
@@ -71,6 +102,16 @@ export async function loadChantConfig(dir: string): Promise<ResolvedConfig> {
   return { config: DEFAULT_CHANT_CONFIG };
 }
 
+/**
+ * Resolve the ownership marker to stamp from project config, or undefined when
+ * ownership marking is off (no `stack`, or `enabled: false`).
+ */
+export function resolveOwnershipMarker(config: ChantConfig): OwnershipMarker | undefined {
+  const o = config.ownership;
+  if (!o || !o.stack || o.enabled === false) return undefined;
+  return { stack: o.stack, env: o.env };
+}
+
 /**
  * Validate and normalize a raw config object into ChantConfig shape.
  */

package/src/detectLexicon.test.ts

@@ -238,12 +238,12 @@ describe("detectLexicons", () => {
     const file = join(testDir, "infra.ts");
     await writeFile(
       file,
-      `import {\n  Namespace,\n  Service,\n} from "@intentius/chant-lexicon-k8s";\nimport {\n  FlywayProject,\n  Environment,\n} from "@intentius/chant-lexicon-flyway";\n\nexport const ns = new Namespace({});`
+      `import {\n  Namespace,\n  Service,\n} from "@intentius/chant-lexicon-k8s";\nimport {\n  HelmRelease,\n  HelmChart,\n} from "@intentius/chant-lexicon-helm";\n\nexport const ns = new Namespace({});`
     );
 
     const result = await detectLexicons([file]);
     expect(result).toContain("k8s");
-    expect(result).toContain("flyway");
+    expect(result).toContain("helm");
     expect(result).toHaveLength(2);
   });
 

package/src/index.ts

@@ -59,8 +59,8 @@ export * from "./child-project";
 export * from "./lsp/types";
 export * from "./lsp/lexicon-providers";
 export * from "./mcp/types";
-export * from "./state/index";
+export * from "./lifecycle/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";
+         gitlabPipeline, lifecycleSnapshot, shell, teardown, OpResource } from "./op/index";
 export type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep } from "./op/index";

package/src/lexicon-export.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, test } from "vitest";
+import type {
+  LexiconPlugin,
+  ObservationLexicon,
+  ExportedTemplate,
+  ResourceSelector,
+} from "./lexicon";
+import type { TypeScriptGenerator } from "./import/generator";
+import type { TemplateIR } from "./import/parser";
+
+// A throwaway generator standing in for any lexicon's real templateGenerator().
+const generator: TypeScriptGenerator = {
+  generate(ir: TemplateIR) {
+    return ir.resources.map((r) => ({
+      path: `${r.logicalId}.ts`,
+      content: `export const ${r.logicalId} = ${JSON.stringify(r.properties)};`,
+    }));
+  },
+};
+
+// A minimal lexicon that implements live export — the acceptance shape.
+const exportingLexicon: Pick<LexiconPlugin, "name" | "exportResources"> = {
+  name: "fake",
+  async exportResources(opts: {
+    environment: string;
+    selector?: ResourceSelector;
+    owned?: boolean;
+  }): Promise<ExportedTemplate> {
+    const selector = opts.selector;
+    const all: ExportedTemplate = {
+      resources: [
+        { logicalId: "Bucket", type: "Fake::Bucket", properties: { versioning: true } },
+        { logicalId: "Queue", type: "Fake::Queue", properties: { fifo: false } },
+      ],
+      parameters: [],
+      metadata: { environment: opts.environment, owned: opts.owned ?? false },
+    };
+    if (!selector) return all;
+    return {
+      ...all,
+      resources: all.resources.filter(
+        (r) =>
+          (selector.type === undefined || r.type === selector.type) &&
+          (selector.name === undefined || r.logicalId === selector.name),
+      ),
+    };
+  },
+};
+
+describe("exportResources contract (#113)", () => {
+  test("an ExportedTemplate feeds templateGenerator() unchanged", async () => {
+    const ir = await exportingLexicon.exportResources!({ environment: "prod" });
+    // ExportedTemplate is structurally a TemplateIR — no adapter needed.
+    const files = generator.generate(ir);
+    expect(files.map((f) => f.path)).toEqual(["Bucket.ts", "Queue.ts"]);
+    expect(files[0].content).toContain("versioning");
+  });
+
+  test("selector narrows the exported set", async () => {
+    const ir = await exportingLexicon.exportResources!({
+      environment: "prod",
+      selector: { name: "Queue" },
+    });
+    expect(ir.resources).toHaveLength(1);
+    expect(ir.resources[0].logicalId).toBe("Queue");
+  });
+
+  test("owned is accepted but inert (carried into metadata, no filtering yet)", async () => {
+    const ir = await exportingLexicon.exportResources!({ environment: "prod", owned: true });
+    expect(ir.metadata?.owned).toBe(true);
+    expect(ir.resources).toHaveLength(2);
+  });
+
+  test("type separation: observation view cannot reach exportResources", () => {
+    // A full plugin is assignable to the narrowed observation view…
+    const full = exportingLexicon as unknown as LexiconPlugin;
+    const observed: ObservationLexicon = full;
+    // …but exportResources is not visible on it. Compile-time guarantee:
+    // @ts-expect-error exportResources is omitted from ObservationLexicon
+    void observed.exportResources;
+    expect(typeof observed.name).toBe("string");
+  });
+
+  test("type separation: scrubbed metadata is not an ExportedTemplate", () => {
+    // A ResourceMetadata-shaped object lacks resources/parameters, so it can
+    // never be passed where an ExportedTemplate (full config) is expected.
+    const scrubbed = { type: "Fake::Bucket", status: "OK" };
+    // @ts-expect-error observation metadata is not a full-fidelity export
+    const asExport: ExportedTemplate = scrubbed;
+    expect(asExport).toBeDefined();
+  });
+});

package/src/lexicon.ts

@@ -2,7 +2,7 @@ import type { Serializer } from "./serializer";
 import type { LintRule } from "./lint/rule";
 import type { RuleSpec } from "./lint/declarative";
 import type { PostSynthCheck } from "./lint/post-synth";
-import type { TemplateParser } from "./import/parser";
+import type { TemplateParser, TemplateIR } from "./import/parser";
 import type { TypeScriptGenerator } from "./import/generator";
 import type { ArtifactIntegrity } from "./lexicon-integrity";
 import type { CompletionContext, CompletionItem, HoverContext, HoverInfo, CodeActionContext, CodeAction } from "./lsp/types";
@@ -267,6 +267,13 @@ export interface LexiconPlugin {
     buildOutput: string;
     entityNames: string[];
     entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
+    /**
+     * Restrict the result to chant-owned resources (those carrying the
+     * ownership marker, #119). Where a lexicon has no durable marker channel,
+     * it must log that ownership is unavailable rather than silently returning
+     * everything.
+     */
+    owned?: boolean;
   }): Promise<Record<string, ResourceMetadata>>;
 
   /**
@@ -274,22 +281,87 @@ export interface LexiconPlugin {
    *
    * Use this for lexicons whose chant entities describe *authoring*
    * primitives rather than 1:1 cloud resources — e.g. Helm (charts vs
-   * releases), Docker (Compose vs running containers), Flyway (migration
-   * scripts vs applied migrations). The contract is context-keyed: given an
-   * environment, list all artifacts visible there. There is no `declared`
-   * comparison axis — `state diff --live` reports added/removed/changed
-   * between snapshots, not vs. declared.
+   * releases), Docker (Compose vs running containers). The contract is
+   * context-keyed: given an environment, list all artifacts visible there.
+   * There is no `declared` comparison axis — `state diff --live` reports
+   * added/removed/changed between snapshots, not vs. declared.
    *
    * `entities` is passed for cases where the lexicon needs to know what
-   * was declared in order to enumerate (e.g. Flyway needs the declared
-   * `Flyway::Environment` entities to know which DBs to query).
+   * was declared in order to scope its enumeration (e.g. a per-tenant
+   * runtime where the declared entities name which tenants to query).
    */
   listArtifacts?(options: {
     environment: string;
     entities: Map<string, { entityType: string; props: Record<string, unknown> }>;
   }): Promise<Record<string, ArtifactMetadata>>;
+
+  // Live export (cloud → code)
+  /**
+   * Export full-fidelity import IR from a live API — the cloud→code primitive
+   * that lets chant regenerate TypeScript from running cloud/cluster state.
+   *
+   * Deliberately separate from {@link describeResources}: that returns scrubbed
+   * *output* metadata for diffing, this returns full *input* config — enough to
+   * regenerate a resource, and therefore possibly containing secrets. The
+   * scrubbing boundary stays single-purpose; never overload one method for both.
+   *
+   * The return type {@link ExportedTemplate} is branded distinct from the
+   * observation types so a full-fidelity export can never flow into the
+   * observation/`state` code paths by accident.
+   *
+   * `owned` is accepted now but inert until ownership marking exists (#119/#120).
+   *
+   * `verbatim` controls fidelity: by default an implementation strips
+   * server-defaulted and server-managed fields to reach the declared shape
+   * (the form a user would have authored). `verbatim: true` keeps them. Targets
+   * whose live config is already the declared shape (e.g. a CloudFormation
+   * original template) may ignore it.
+   */
+  exportResources?(options: {
+    environment: string;
+    selector?: ResourceSelector;
+    owned?: boolean;
+    verbatim?: boolean;
+  }): Promise<ExportedTemplate>;
+}
+
+/**
+ * The observation view of a lexicon — every capability except live export.
+ *
+ * State/observation code (snapshots, `state diff --live`) consumes lexicons
+ * through this type so that `exportResources` is unreachable from those paths:
+ * a full-fidelity {@link ExportedTemplate} (which may carry secrets) must never
+ * be read where scrubbed {@link ResourceMetadata} is expected. A full
+ * {@link LexiconPlugin} is assignable to this type; accessing `exportResources`
+ * on it is a compile error.
+ */
+export type ObservationLexicon = Omit<LexiconPlugin, "exportResources">;
+
+/**
+ * Narrows which live resources {@link LexiconPlugin.exportResources} and the
+ * `owned` filter operate on. Both fields are optional; omit to export all.
+ */
+export interface ResourceSelector {
+  /** Restrict to a single chant resource type (e.g. "AWS::S3::Bucket"). */
+  readonly type?: string;
+  /** Restrict to a single resource name. */
+  readonly name?: string;
 }
 
+/**
+ * Full-fidelity import IR read from a live API, branded distinct from the
+ * scrubbed observation metadata. It IS a {@link TemplateIR} — it feeds the
+ * existing `templateGenerator()` unchanged — but the phantom brand keeps it
+ * from being passed where observation metadata is expected, and keeps
+ * observation metadata from being passed where an export is expected.
+ *
+ * The brand is type-only; nothing is added at runtime.
+ */
+export type ExportedTemplate = TemplateIR & {
+  /** Phantom marker — never present at runtime. */
+  readonly __fidelity?: "full-config";
+};
+
 /**
  * Metadata about a deployed resource, returned by describeResources.
  */
@@ -304,6 +376,13 @@ export interface ResourceMetadata {
   lastUpdated?: string;
   /** Cloud-assigned output properties */
   attributes?: Record<string, unknown>;
+  /**
+   * Live ownership verdict from the resource's marker (#119/#120), when the
+   * lexicon could determine it. `owned` = carries chant's marker; `foreign` =
+   * no marker. Absent = the lexicon has no marker channel here. The change set
+   * reads this — never the snapshot — to decide whether an orphan is a delete.
+   */
+  ownership?: "owned" | "foreign";
 }
 
 /**
@@ -311,7 +390,7 @@ export interface ResourceMetadata {
  * as ResourceMetadata; the conceptual distinction is whether the lexicon's
  * chant entities have 1:1 runtime equivalents (resources) or whether the
  * runtime artifacts are created by tooling outside chant's entity model
- * (artifacts — e.g. Helm releases, Docker containers, Flyway migrations).
+ * (artifacts — e.g. Helm releases, Docker containers).
  */
 export interface ArtifactMetadata {
   /** Artifact type (e.g. Helm::Release, Docker::Container) */

package/src/lifecycle/change-set.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, test } from "vitest";
+import { buildChangeSet, renderChangeSet, summarize } from "./change-set";
+import type { ResourceMetadata } from "../lexicon";
+
+const meta = (over: Partial<ResourceMetadata> = {}): ResourceMetadata => ({
+  type: "Fake::Resource",
+  status: "OK",
+  ...over,
+});
+
+describe("buildChangeSet (#118)", () => {
+  test("declared but not live → create", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["bucket"]),
+      observedNow: {},
+      observedThen: undefined,
+    });
+    const e = cs.entries.find((x) => x.name === "bucket")!;
+    expect(e.action).toBe("create");
+    expect(e.evidence).toEqual({ declared: true, inSnapshot: false, live: false });
+    expect(e.ownership).toBe("unknown");
+  });
+
+  test("declared and live with drift since snapshot → update with deltas", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["queue"]),
+      observedNow: { queue: meta({ status: "ACTIVE" }) },
+      observedThen: { queue: meta({ status: "CREATING" }) },
+    });
+    const e = cs.entries.find((x) => x.name === "queue")!;
+    expect(e.action).toBe("update");
+    expect(e.deltas).toEqual([{ path: "status", oldValue: "CREATING", newValue: "ACTIVE" }]);
+  });
+
+  test("declared and live, unchanged → noop", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["queue"]),
+      observedNow: { queue: meta({ status: "ACTIVE" }) },
+      observedThen: { queue: meta({ status: "ACTIVE" }) },
+    });
+    expect(cs.entries.find((x) => x.name === "queue")!.action).toBe("noop");
+  });
+
+  test("live but undeclared, no ownership data → adopt, never delete", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(),
+      observedNow: { orphan: meta() },
+      observedThen: undefined,
+    });
+    const e = cs.entries.find((x) => x.name === "orphan")!;
+    expect(e.action).toBe("adopt");
+    expect(e.ownership).toBe("unknown");
+  });
+
+  test("owned orphan → delete (#121)", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(),
+      observedNow: { orphan: meta({ ownership: "owned" }) },
+      observedThen: undefined,
+    });
+    const e = cs.entries.find((x) => x.name === "orphan")!;
+    expect(e.action).toBe("delete");
+    expect(e.ownership).toBe("owned");
+  });
+
+  test("foreign orphan → adopt, never delete (#121)", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(),
+      observedNow: { orphan: meta({ ownership: "foreign" }) },
+      observedThen: undefined,
+    });
+    const e = cs.entries.find((x) => x.name === "orphan")!;
+    expect(e.action).toBe("adopt");
+    expect(e.ownership).toBe("foreign");
+  });
+
+  test("snapshot is never load-bearing: ownership/delete ignores observedThen", () => {
+    // The same live orphan, once with a rich snapshot and once with none.
+    // The delete decision must depend only on the LIVE ownership marker, so the
+    // result must be identical regardless of what the snapshot says.
+    const withSnapshot = buildChangeSet("prod", {
+      declared: new Set(),
+      observedNow: { orphan: meta({ ownership: "owned" }) },
+      observedThen: { orphan: meta({ ownership: "foreign", status: "STALE" }) },
+    });
+    const withoutSnapshot = buildChangeSet("prod", {
+      declared: new Set(),
+      observedNow: { orphan: meta({ ownership: "owned" }) },
+      observedThen: undefined,
+    });
+    const a = withSnapshot.entries.find((x) => x.name === "orphan")!;
+    const b = withoutSnapshot.entries.find((x) => x.name === "orphan")!;
+    expect(a.action).toBe("delete");
+    expect(a.ownership).toBe("owned");
+    expect(a.action).toBe(b.action);
+    expect(a.ownership).toBe(b.ownership);
+  });
+
+  test("never proposes a delete without ownership data", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["a"]),
+      observedNow: { b: meta(), c: meta() }, // two orphans
+      observedThen: { b: meta(), c: meta() },
+    });
+    expect(cs.entries.some((e) => e.action === "delete")).toBe(false);
+    expect(cs.entries.filter((e) => e.action === "adopt").map((e) => e.name)).toEqual(["b", "c"]);
+  });
+
+  test("only in snapshot (gone now, undeclared) → noop", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(),
+      observedNow: {},
+      observedThen: { ghost: meta() },
+    });
+    expect(cs.entries.find((x) => x.name === "ghost")!.action).toBe("noop");
+  });
+
+  test("entries are sorted by name", () => {
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["z", "a", "m"]),
+      observedNow: {},
+      observedThen: undefined,
+    });
+    expect(cs.entries.map((e) => e.name)).toEqual(["a", "m", "z"]);
+  });
+});
+
+describe("summarize / renderChangeSet", () => {
+  const cs = buildChangeSet("prod", {
+    declared: new Set(["create-me", "keep-me"]),
+    observedNow: { "keep-me": meta(), orphan: meta() },
+    observedThen: { "keep-me": meta() },
+  });
+
+  test("summarize counts each action", () => {
+    const counts = summarize(cs);
+    expect(counts.create).toBe(1);
+    expect(counts.noop).toBe(1);
+    expect(counts.adopt).toBe(1);
+    expect(counts.delete).toBe(0);
+  });
+
+  test("render shows the env and grouped sections", () => {
+    const out = renderChangeSet(cs);
+    expect(out).toContain("Plan for prod");
+    expect(out).toContain("CREATE:");
+    expect(out).toContain("create-me");
+    expect(out).toContain("ADOPT:");
+    expect(out).toContain("orphan");
+  });
+});