@intentius/chant 0.1.17 → 0.1.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/commands/vendor.test.ts

@@ -0,0 +1,148 @@
+import { describe, test, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  vendorPull,
+  vendorCheck,
+  contentHash,
+  scopeArchiveFiles,
+  loadManifest,
+  MANIFEST_FILE,
+} from "./vendor";
+
+let root: string;
+
+function write(rel: string, content: string): void {
+  const full = join(root, rel);
+  mkdirSync(join(full, ".."), { recursive: true });
+  writeFileSync(full, content);
+}
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "chant-vendor-"));
+  // A local "shared pattern" source.
+  write("shared/web-app/index.ts", "export const WebApp = () => ({});\n");
+  write("shared/web-app/README.md", "# pattern\n");
+  // A project that vendors it.
+  writeFileSync(
+    join(root, MANIFEST_FILE),
+    JSON.stringify({
+      vendored: [
+        { name: "web-app", source: { type: "local", path: "shared/web-app" }, target: "vendor/web-app", ref: "v1" },
+      ],
+    }, null, 2),
+  );
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe("vendor pull", () => {
+  test("copies the source into target and records a checksum", async () => {
+    const result = await vendorPull(root);
+    expect(result.success).toBe(true);
+    expect(result.pulled[0].fileCount).toBe(2);
+
+    expect(existsSync(join(root, "vendor/web-app/index.ts"))).toBe(true);
+    expect(readFileSync(join(root, "vendor/web-app/README.md"), "utf-8")).toContain("# pattern");
+
+    // Checksum written back into the manifest.
+    const { manifest } = loadManifest(root);
+    expect(manifest.vendored[0].checksum).toMatch(/^sha256:[0-9a-f]{64}$/);
+  });
+
+  test("pull <name> filters to one entry; unknown name fails", async () => {
+    expect((await vendorPull(root, "web-app")).pulled).toHaveLength(1);
+    const miss = await vendorPull(root, "nope");
+    expect(miss.success).toBe(false);
+    expect(miss.output).toContain("nope");
+  });
+
+  test("fails clearly when the local source is missing", async () => {
+    writeFileSync(
+      join(root, MANIFEST_FILE),
+      JSON.stringify({ vendored: [{ name: "x", source: { type: "local", path: "missing" }, target: "vendor/x" }] }),
+    );
+    await expect(vendorPull(root)).rejects.toThrow(/local source not found/);
+  });
+});
+
+describe("vendor check", () => {
+  test("reports ok right after a pull", async () => {
+    await vendorPull(root);
+    const result = vendorCheck(root);
+    expect(result.drift).toBe(false);
+    expect(result.entries[0].status).toBe("ok");
+  });
+
+  test("detects drift when a vendored file is edited", async () => {
+    await vendorPull(root);
+    writeFileSync(join(root, "vendor/web-app/index.ts"), "// locally edited\n");
+    const result = vendorCheck(root);
+    expect(result.drift).toBe(true);
+    expect(result.entries[0].status).toBe("drifted");
+  });
+
+  test("flags a target deleted after pinning as missing", async () => {
+    await vendorPull(root);
+    rmSync(join(root, "vendor/web-app"), { recursive: true });
+    const result = vendorCheck(root);
+    expect(result.entries[0].status).toBe("missing");
+    expect(result.drift).toBe(true);
+  });
+
+  test("an entry with no checksum is unpinned, not drift", async () => {
+    // Manifest never pulled → no checksum recorded.
+    const result = vendorCheck(root);
+    expect(result.entries[0].status).toBe("unpinned");
+    expect(result.drift).toBe(false);
+  });
+});
+
+describe("manifest validation", () => {
+  test("rejects an invalid manifest", () => {
+    writeFileSync(join(root, MANIFEST_FILE), JSON.stringify({ vendored: [{ name: "x" }] }));
+    expect(() => loadManifest(root)).toThrow(/invalid vendor.json/);
+  });
+
+  test("rejects a floating updatePolicy (pins only)", () => {
+    writeFileSync(
+      join(root, MANIFEST_FILE),
+      JSON.stringify({ vendored: [{ name: "x", source: { type: "local", path: "shared/web-app" }, target: "v/x", updatePolicy: "latest" }] }),
+    );
+    expect(() => loadManifest(root)).toThrow(/invalid vendor.json/);
+  });
+});
+
+describe("contentHash", () => {
+  test("is order-independent and content-sensitive", () => {
+    const a = new Map([["a", Buffer.from("1")], ["b", Buffer.from("2")]]);
+    const b = new Map([["b", Buffer.from("2")], ["a", Buffer.from("1")]]);
+    expect(contentHash(a)).toBe(contentHash(b)); // order doesn't matter
+    const c = new Map([["a", Buffer.from("1")], ["b", Buffer.from("CHANGED")]]);
+    expect(contentHash(a)).not.toBe(contentHash(c));
+  });
+});
+
+describe("scopeArchiveFiles", () => {
+  test("strips the top-level wrapper dir and scopes to a subpath", () => {
+    const raw = new Map([
+      ["repo-main/composites/web-app/index.ts", Buffer.from("a")],
+      ["repo-main/composites/web-app/util.ts", Buffer.from("b")],
+      ["repo-main/ops/deploy.op.ts", Buffer.from("c")],
+      ["repo-main/README.md", Buffer.from("d")],
+    ]);
+    const scoped = scopeArchiveFiles(raw, "composites/web-app");
+    expect([...scoped.keys()].sort()).toEqual(["index.ts", "util.ts"]);
+  });
+
+  test("no subpath keeps everything below the wrapper dir", () => {
+    const raw = new Map([
+      ["repo-main/a.ts", Buffer.from("a")],
+      ["repo-main/sub/b.ts", Buffer.from("b")],
+    ]);
+    expect([...scopeArchiveFiles(raw).keys()].sort()).toEqual(["a.ts", "sub/b.ts"]);
+  });
+});

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/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,6 +12,7 @@ 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 { runGraph } from "./handlers/graph";
@@ -155,6 +156,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)
@@ -291,6 +293,7 @@ const registry: CommandDef[] = [
   { name: "run", handler: runOp },
 
   { name: "graph", handler: runGraph },
+  { name: "vendor", handler: runVendor },
 
   // State subcommands
   { name: "lifecycle snapshot", requiresPlugins: true, handler: runLifecycleSnapshot },