@intentius/chant 0.1.17 → 0.1.19

package/src/cli/commands/vendor.ts

@@ -0,0 +1,263 @@
+/**
+ * `chant vendor` — pull reusable patterns (composites as source, Ops, init
+ * templates, example skeletons) from a remote source into your own repo, pinned
+ * and auditable.
+ *
+ * This is for patterns you copy in and **own/adapt**, recorded in a manifest
+ * (`vendor.json`) with a checksum so provenance is verifiable. It is NOT a
+ * package manager: lexicons stay npm dependencies (the typed API you import,
+ * never edit). Vendoring exists for the source npm handles badly — code you want
+ * in-repo, reviewable in diffs, and adaptable.
+ *
+ * Reuses the existing fetch/extract infra (`codegen/fetch.ts`); the only new
+ * machinery is the manifest + copy-to-repo + checksum.
+ */
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { z } from "zod";
+import { fetchWithRetry, extractFromTar, extractFromZip } from "../../codegen/fetch";
+
+// ── Manifest schema ─────────────────────────────────────────────────────────
+
+const SourceSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("local"), path: z.string().min(1) }),
+  z.object({ type: z.literal("archive"), url: z.string().url(), subpath: z.string().optional() }),
+]);
+
+const EntrySchema = z.object({
+  /** Stable identity for the vendored artifact (used by `pull <name>`). */
+  name: z.string().min(1),
+  source: SourceSchema,
+  /** Path in your repo to write the pulled content. */
+  target: z.string().min(1),
+  /** The pin — a git tag / version label, for provenance (informational). */
+  ref: z.string().optional(),
+  /** sha256 of the pulled content. Written by `pull`, verified by `check`. */
+  checksum: z.string().optional(),
+  /** Only "pin" (explicit-bump) is supported; floating refs are out of scope. */
+  updatePolicy: z.literal("pin").optional(),
+});
+
+export const VendorManifestSchema = z.object({
+  vendored: z.array(EntrySchema),
+});
+
+export type VendorEntry = z.infer<typeof EntrySchema>;
+export type VendorManifest = z.infer<typeof VendorManifestSchema>;
+
+export const MANIFEST_FILE = "vendor.json";
+
+// ── Content hashing ───────────────────────────────────────────────────────��─
+
+/**
+ * Deterministic sha256 over a file set — independent of fetch/extract order.
+ * Hashes each `path\0content\0` in sorted-path order.
+ */
+export function contentHash(files: Map<string, Buffer>): string {
+  const h = createHash("sha256");
+  for (const path of [...files.keys()].sort()) {
+    h.update(path);
+    h.update("\0");
+    h.update(files.get(path)!);
+    h.update("\0");
+  }
+  return `sha256:${h.digest("hex")}`;
+}
+
+// ── Source resolution → a { relpath → bytes } file set ──────────────────────
+
+/** Walk a local directory into a relpath→bytes map (or a single file). */
+function readLocal(absPath: string): Map<string, Buffer> {
+  const files = new Map<string, Buffer>();
+  const stat = statSync(absPath);
+  if (stat.isFile()) {
+    files.set(absPath.split(sep).pop()!, readFileSync(absPath));
+    return files;
+  }
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile()) {
+        files.set(relative(absPath, full).split(sep).join("/"), readFileSync(full));
+      }
+    }
+  };
+  walk(absPath);
+  return files;
+}
+
+/** Fetch + extract an archive (tar.gz/tgz/zip), scoped to an optional subpath. */
+async function readArchive(url: string, subpath?: string): Promise<Map<string, Buffer>> {
+  const resp = await fetchWithRetry(url);
+  const bytes = new Uint8Array(await resp.arrayBuffer());
+
+  let raw: Map<string, Buffer>;
+  if (url.endsWith(".zip")) {
+    raw = await extractFromZip(Buffer.from(bytes));
+  } else {
+    // .tar.gz / .tgz — gunzip then untar (matches fetchAndExtractTar).
+    const { gunzipSync } = await import("fflate");
+    raw = extractFromTar(gunzipSync(bytes));
+  }
+
+  return scopeArchiveFiles(raw, subpath);
+}
+
+/**
+ * Normalize an extracted archive: strip the single top-level wrapper directory
+ * (e.g. "repo-main/") that archives commonly add, then scope to `subpath`.
+ * Pure — separated from the network fetch so the scoping is unit-testable.
+ */
+export function scopeArchiveFiles(
+  raw: Map<string, Buffer>,
+  subpath?: string,
+): Map<string, Buffer> {
+  const prefix = subpath ? subpath.replace(/^\/+|\/+$/g, "") + "/" : "";
+  const files = new Map<string, Buffer>();
+  for (const [name, data] of raw) {
+    const slash = name.indexOf("/");
+    const rel = slash >= 0 ? name.slice(slash + 1) : name;
+    if (!rel || !rel.startsWith(prefix)) continue;
+    const local = rel.slice(prefix.length);
+    if (local) files.set(local, data);
+  }
+  return files;
+}
+
+async function resolveSource(entry: VendorEntry, manifestDir: string): Promise<Map<string, Buffer>> {
+  if (entry.source.type === "local") {
+    const abs = resolve(manifestDir, entry.source.path);
+    if (!existsSync(abs)) throw new Error(`local source not found: ${entry.source.path}`);
+    return readLocal(abs);
+  }
+  return readArchive(entry.source.url, entry.source.subpath);
+}
+
+// ── File I/O ────────────────────────────────────────────────────────────────
+
+function writeFiles(targetDir: string, files: Map<string, Buffer>): void {
+  if (existsSync(targetDir)) rmSync(targetDir, { recursive: true });
+  for (const [rel, data] of files) {
+    const full = join(targetDir, rel);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, data);
+  }
+}
+
+function readTarget(targetDir: string): Map<string, Buffer> {
+  if (!existsSync(targetDir)) return new Map();
+  return readLocal(targetDir);
+}
+
+// ── Manifest load/save ────────────────────────────────────────────────────��─
+
+export function loadManifest(manifestDir: string): { manifest: VendorManifest; path: string } {
+  const path = join(manifestDir, MANIFEST_FILE);
+  if (!existsSync(path)) {
+    throw new Error(`no ${MANIFEST_FILE} found in ${manifestDir}`);
+  }
+  const parsed = VendorManifestSchema.safeParse(JSON.parse(readFileSync(path, "utf-8")));
+  if (!parsed.success) {
+    throw new Error(`invalid ${MANIFEST_FILE}: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`);
+  }
+  return { manifest: parsed.data, path };
+}
+
+function saveManifest(path: string, manifest: VendorManifest): void {
+  writeFileSync(path, JSON.stringify(manifest, null, 2) + "\n");
+}
+
+// ── pull ─────────────────────────────────────────────────────────────────��──
+
+export interface VendorPullResult {
+  success: boolean;
+  pulled: Array<{ name: string; target: string; checksum: string; fileCount: number }>;
+  output: string;
+}
+
+/**
+ * Pull each vendored entry (or just `only`): resolve the source, write it into
+ * `target`, and record the content checksum back into the manifest.
+ */
+export async function vendorPull(manifestDir: string, only?: string): Promise<VendorPullResult> {
+  const { manifest, path } = loadManifest(manifestDir);
+  const entries = only ? manifest.vendored.filter((e) => e.name === only) : manifest.vendored;
+  if (only && entries.length === 0) {
+    return { success: false, pulled: [], output: `no vendored entry named "${only}"` };
+  }
+
+  const pulled: VendorPullResult["pulled"] = [];
+  for (const entry of entries) {
+    const files = await resolveSource(entry, manifestDir);
+    const checksum = contentHash(files);
+    writeFiles(resolve(manifestDir, entry.target), files);
+    entry.checksum = checksum;
+    pulled.push({ name: entry.name, target: entry.target, checksum, fileCount: files.size });
+  }
+  saveManifest(path, manifest);
+
+  const output = pulled
+    .map((p) => `  ${p.name} → ${p.target} (${p.fileCount} file(s), ${p.checksum.slice(0, 19)}…)`)
+    .join("\n");
+  return { success: true, pulled, output };
+}
+
+// ── check ────────────────────────────────────────────────────────────────��──
+
+export interface VendorCheckResult {
+  success: boolean;
+  /** True if any vendored target diverged from its recorded checksum. */
+  drift: boolean;
+  entries: Array<{ name: string; status: "ok" | "drifted" | "unpinned" | "missing" }>;
+  output: string;
+}
+
+/**
+ * Verify each target's working copy against its recorded checksum. Editing
+ * vendored files is allowed — `check` only reports that they diverged from the
+ * pin. The caller decides whether drift is fatal (CI) or a warning (local).
+ */
+export function vendorCheck(manifestDir: string): VendorCheckResult {
+  const { manifest } = loadManifest(manifestDir);
+  const entries: VendorCheckResult["entries"] = [];
+  let drift = false;
+
+  for (const entry of manifest.vendored) {
+    const targetAbs = resolve(manifestDir, entry.target);
+    if (!entry.checksum) {
+      entries.push({ name: entry.name, status: "unpinned" });
+      continue;
+    }
+    if (!existsSync(targetAbs)) {
+      entries.push({ name: entry.name, status: "missing" });
+      drift = true;
+      continue;
+    }
+    const actual = contentHash(readTarget(targetAbs));
+    if (actual === entry.checksum) {
+      entries.push({ name: entry.name, status: "ok" });
+    } else {
+      entries.push({ name: entry.name, status: "drifted" });
+      drift = true;
+    }
+  }
+
+  const label: Record<string, string> = {
+    ok: "ok",
+    drifted: "DRIFTED (working copy differs from the pin)",
+    unpinned: "unpinned — run `chant vendor pull` to record a checksum",
+    missing: "MISSING — target not found; run `chant vendor pull`",
+  };
+  const output = entries.map((e) => `  ${e.name}: ${label[e.status]}`).join("\n");
+  return { success: !drift, drift, entries, output };
+}

package/src/cli/handlers/build.ts

@@ -44,6 +44,7 @@ export async function runBuild(ctx: CommandContext): Promise<number> {
     serializers,
     plugins,
     verbose: args.verbose,
+    env: args.env,
   });
 
   // When --lexicon filters to a subset, suppress "No serializer" warnings for excluded lexicons

package/src/cli/handlers/graph.ts

@@ -1,8 +1,21 @@
+import { resolve } from "node:path";
 import { discoverOps } from "../../op/discover";
-import { formatError } from "../format";
+import { discover } from "../../discovery/index";
+import { partitionByLexicon, computeStackGraph } from "../../build";
+import { formatError, formatWarning, formatBold } from "../format";
 import type { CommandContext } from "../registry";
 
-export async function runGraph(_ctx: CommandContext): Promise<number> {
+/**
+ * `chant graph` — the Op dependency graph by default; `--stacks` renders the
+ * cross-stack apply-ordering graph (edges, order, waves) chant computes from
+ * cross-lexicon references.
+ */
+export async function runGraph(ctx: CommandContext): Promise<number> {
+  if (ctx.args.stacks) return runStackGraph(ctx);
+  return runOpGraph();
+}
+
+async function runOpGraph(): Promise<number> {
   const { ops, errors } = await discoverOps();
   for (const err of errors) console.error(formatError({ message: err }));
 
@@ -21,3 +34,43 @@ export async function runGraph(_ctx: CommandContext): Promise<number> {
   if (!hasEdges) console.log("No Op dependencies");
   return 0;
 }
+
+async function runStackGraph(ctx: CommandContext): Promise<number> {
+  const projectPath = resolve(ctx.args.path === "." ? "." : ctx.args.path);
+  const result = await discover(projectPath);
+  if (result.errors.length > 0) {
+    for (const e of result.errors) console.error(formatError({ message: e.message }));
+    return 1;
+  }
+
+  const lexicons = [...partitionByLexicon(result.entities).keys()];
+  const graph = computeStackGraph(result.entities, lexicons);
+
+  if (ctx.args.json) {
+    console.log(JSON.stringify(graph, null, 2));
+    return graph.cycles.length > 0 ? 1 : 0;
+  }
+
+  if (graph.nodes.length === 0) {
+    console.log("No stacks found");
+    return 0;
+  }
+
+  console.log(formatBold("Apply order (waves apply top-to-bottom; a wave's stacks are parallel-safe):"));
+  graph.waves.forEach((wave, i) => console.log(`  ${i + 1}. ${wave.join(", ")}`));
+
+  if (graph.edges.length > 0) {
+    console.log(formatBold("\nDependencies (consumer → producer):"));
+    for (const { from, to } of graph.edges) console.log(`  ${from} → ${to}`);
+  } else {
+    console.log("\nNo cross-stack dependencies — all stacks are independent.");
+  }
+
+  if (graph.cycles.length > 0) {
+    for (const cycle of graph.cycles) {
+      console.error(formatWarning({ message: `Dependency cycle among stacks: ${cycle.join(" ↔ ")}` }));
+    }
+    return 1;
+  }
+  return 0;
+}

package/src/cli/handlers/lifecycle.ts

@@ -5,6 +5,7 @@ import { readSnapshot, readEnvironmentSnapshots, listSnapshots, fetchLifecycle,
 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 { affectedStacks } from "../../lifecycle/affected";
 import { loadChantConfig } from "../../config";
 import { formatError, formatWarning, formatSuccess, formatBold } from "../format";
 import type { CommandContext } from "../registry";
@@ -576,3 +577,59 @@ function printSnapshotTable(snapshot: LifecycleSnapshot): void {
     );
   }
 }
+
+/**
+ * chant lifecycle affected --base <ref> [--head <ref>] [--include-dependents] [--json]
+ *
+ * Read-only: report which stacks a change affects (directly-changed via artifact
+ * diff, dependents via the cross-stack graph, external-input as indeterminate).
+ * Returns the set; fanning plan/apply over it is an Op the user composes.
+ */
+export async function runLifecycleAffected(ctx: CommandContext): Promise<number> {
+  const { args, plugins } = ctx;
+  if (!args.base) {
+    console.error(formatError({
+      message: "Base ref is required: chant lifecycle affected --base <ref> [--head <ref>] [--include-dependents]",
+    }));
+    return 1;
+  }
+
+  const { config } = await loadChantConfig(resolve("."));
+  const projectPath = resolveBuildRoot(args, config);
+
+  let result;
+  try {
+    result = await affectedStacks({
+      projectPath,
+      serializers: plugins.map((p) => p.serializer),
+      baseRef: args.base,
+      headRef: args.head,
+      includeDependents: args.includeDependents,
+    });
+  } catch (err) {
+    console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    return 1;
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return 0;
+  }
+
+  if (result.changed.length === 0 && result.dependents.length === 0) {
+    console.error(formatSuccess("No stacks affected"));
+  } else {
+    console.log(formatBold("Directly changed:"));
+    console.log(result.changed.length ? result.changed.map((s) => `  ${s}`).join("\n") : "  (none)");
+    if (args.includeDependents) {
+      console.log(formatBold("\nDependents (consume a changed stack):"));
+      console.log(result.dependents.length ? result.dependents.map((s) => `  ${s}`).join("\n") : "  (none)");
+    }
+  }
+  if (result.indeterminate.length > 0) {
+    console.error(formatWarning({
+      message: `External-input stacks — cannot confirm from source: ${result.indeterminate.join(", ")}`,
+    }));
+  }
+  return 0;
+}

package/src/cli/handlers/vendor.ts

@@ -0,0 +1,61 @@
+import { resolve } from "node:path";
+import { vendorPull, vendorCheck } from "../commands/vendor";
+import { formatError, formatSuccess, formatWarning } from "../format";
+import type { CommandContext } from "../registry";
+
+/**
+ * `chant vendor [pull|check]` — pull pinned, checksummed patterns into the repo,
+ * or check vendored targets against their recorded pin. Defaults to `pull`.
+ *
+ * The manifest (`vendor.json`) lives in the current directory.
+ */
+export async function runVendor(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  // `chant vendor` → pull; `chant vendor pull|check [name]`.
+  const sub = args.path === "." ? "pull" : args.path;
+  const manifestDir = resolve(".");
+
+  if (sub === "pull") {
+    try {
+      const result = await vendorPull(manifestDir, args.extraPositional);
+      if (!result.success) {
+        console.error(formatError({ message: result.output }));
+        return 1;
+      }
+      console.log(result.output);
+      console.error(formatSuccess(`Vendored ${result.pulled.length} artifact(s)`));
+      return 0;
+    } catch (err) {
+      console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+      return 1;
+    }
+  }
+
+  if (sub === "check") {
+    try {
+      const result = vendorCheck(manifestDir);
+      console.log(result.output);
+      if (!result.drift) {
+        console.error(formatSuccess("All vendored artifacts match their pin"));
+        return 0;
+      }
+      // Drift is allowed (you may edit vendored files); fail only in CI so a
+      // pipeline catches unrecorded changes, warn locally.
+      if (process.env.CI) {
+        console.error(formatError({ message: "Vendored content drifted from the manifest pin" }));
+        return 1;
+      }
+      console.error(formatWarning({ message: "Vendored content drifted from the manifest pin (run `chant vendor pull` to re-pin)" }));
+      return 0;
+    } catch (err) {
+      console.error(formatError({ message: err instanceof Error ? err.message : String(err) }));
+      return 1;
+    }
+  }
+
+  console.error(formatError({
+    message: `Unknown vendor subcommand: ${sub}`,
+    hint: "Available: chant vendor pull [name], chant vendor check",
+  }));
+  return 1;
+}

package/src/cli/main.ts

@@ -12,8 +12,9 @@ import { runDevGenerate, runDevPublish, runDevOnboard, runDevCheckLexicon, runDe
 import { runServeLsp, runServeMcp, runServeUnknown } from "./handlers/serve";
 import { runInit, runInitLexicon } from "./handlers/init";
 import { runList, runDescribe, runImport, runUpdate, runDoctor } from "./handlers/misc";
+import { runVendor } from "./handlers/vendor";
 import { runMigrate } from "./handlers/migrate";
-import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecyclePlan, runLifecycleLog, runLifecycleUnknown } from "./handlers/lifecycle";
+import { runLifecycleSnapshot, runLifecycleShow, runLifecycleDiff, runLifecyclePlan, runLifecycleAffected, runLifecycleLog, runLifecycleUnknown } from "./handlers/lifecycle";
 import { runGraph } from "./handlers/graph";
 import { runOp, runOpList, runOpStatus, runOpSignal, runOpCancel, runOpLog } from "./handlers/run";
 
@@ -50,6 +51,7 @@ export function parseArgs(args: string[]): ParsedArgs {
     reportFile: undefined,
     skill: undefined,
     src: undefined,
+    env: undefined,
   };
 
   let i = 0;
@@ -114,6 +116,16 @@ export function parseArgs(args: string[]): ParsedArgs {
       result.skill = args[++i];
     } else if (arg === "--src") {
       result.src = args[++i];
+    } else if (arg === "--env") {
+      result.env = args[++i];
+    } else if (arg === "--stacks") {
+      result.stacks = true;
+    } else if (arg === "--base") {
+      result.base = args[++i];
+    } else if (arg === "--head") {
+      result.head = args[++i];
+    } else if (arg === "--include-dependents") {
+      result.includeDependents = true;
     } else if (arg === "--local") {
       result.local = true;
     } else if (arg === "--temporal") {
@@ -155,6 +167,7 @@ Commands:
   lint                  Check specifications for issues
   list                  List discovered entities
   describe              Show the effective config for one component
+  vendor                Pull pinned, checksummed patterns into your repo
   import                Import external template into TypeScript
   migrate <file>        Translate a workflow between lexicons
                         (default: --from github --to gitlab)
@@ -167,7 +180,7 @@ Ops:
   run cancel <name>     Cancel the active workflow run (requires --force)
   run log <name>        Show run history for an Op
 
-  graph                 Show Op dependency graph
+  graph                 Show Op dependency graph (--stacks for cross-stack order)
 
 Lifecycle (alias: lc):
   lifecycle snapshot <env>  Query API, save metadata to orphan branch
@@ -175,6 +188,7 @@ Lifecycle (alias: lc):
   lifecycle diff <env>      Compare current build against last snapshot
                             --live: query cloud now and detect drift
   lifecycle plan <env>      Typed change set (create/update/delete/adopt) vs live
+  lifecycle affected        Stacks a change affects (--base <ref> [--include-dependents])
                             --json: emit the ChangeSet as JSON
   lifecycle log [env]       History of lifecycle snapshots
 
@@ -199,6 +213,7 @@ Options:
                         - list: text (default) or json
                         - lint: stylish (default), json, or sarif
   -d, --lexicon <name>  Build only the specified lexicon (e.g. aws, gitlab)
+      --env <name>      Environment for organizational policy evaluation (build)
   -t, --template <name> Init template (e.g. node-pipeline, docker-build)
   --skill <name>        Init: install only this skill from the lexicon
   --fix                 Auto-fix fixable issues (lint command)
@@ -291,12 +306,14 @@ const registry: CommandDef[] = [
   { name: "run", handler: runOp },
 
   { name: "graph", handler: runGraph },
+  { name: "vendor", handler: runVendor },
 
   // State subcommands
   { name: "lifecycle snapshot", requiresPlugins: true, handler: runLifecycleSnapshot },
   { name: "lifecycle show", handler: runLifecycleShow },
   { name: "lifecycle diff", requiresPlugins: true, handler: runLifecycleDiff },
   { name: "lifecycle plan", requiresPlugins: true, handler: runLifecyclePlan },
+  { name: "lifecycle affected", requiresPlugins: true, handler: runLifecycleAffected },
   { name: "lifecycle log", handler: runLifecycleLog },
 
   // Serve subcommands

package/src/cli/registry.ts

@@ -53,6 +53,16 @@ export interface ParsedArgs {
   verbatim?: boolean;
   /** `chant lifecycle … --src <dir>` — build root override for lifecycle commands */
   src?: string;
+  /** `chant build --env <name>` — environment for organizational policy evaluation */
+  env?: string;
+  /** `chant graph --stacks` — render the cross-stack apply-ordering graph */
+  stacks?: boolean;
+  /** `chant lifecycle affected --base <ref>` — base git ref to diff against */
+  base?: string;
+  /** `chant lifecycle affected --head <ref>` — head git ref (default: working tree) */
+  head?: string;
+  /** `chant lifecycle affected --include-dependents` — add downstream consumers */
+  includeDependents?: boolean;
 }
 
 /**

package/src/index.ts

@@ -32,6 +32,7 @@ export * from "./lint/declarative";
 export * from "./lint/selectors";
 export * from "./lint/named-checks";
 export * from "./lint/post-synth";
+export * from "./lint/policy";
 export * from "./lint/rule-loader";
 export * from "./lint/discover";
 export * from "./import/parser";