@intentius/chant 0.124.12 → 0.124.14

package/dist/components/sandbox/driver.js

@@ -0,0 +1,93 @@
+import { join, resolve } from "node:path";
+import { params as currentBuildParams } from "../../params.js";
+import { sendFunctionSource } from "../../discovery/sandbox/driver.js";
+import { chantSourceDir } from "../../ts-loader.js";
+/**
+ * chant #1051 — generates the source of the "driver" module that runs INSIDE
+ * the sandboxed child for component discovery. Mirrors `../../discovery/
+ * sandbox/driver.ts`'s shape (chant #1045 Phase 2) but is materially simpler:
+ * a `Component` is plain JSON (no `AttrRef` cross-references to resolve), so
+ * there is no equivalent of `resolveAttrRefs`/`encodeEntitySet` here — the
+ * driver hands back its collected components with a bare, structural
+ * `JSON.stringify` over the IPC channel (see `./run.ts`'s `send`).
+ *
+ * Like the entity driver, every file is imported via a LITERAL string
+ * specifier dynamic `import()` — not a variable — so esbuild's bundler can
+ * trace and inline it into ONE self-contained module graph (see `../../
+ * discovery/sandbox/driver.ts`'s doc for why that's verified to lower to a
+ * lazily-invoked local module initializer, not a runtime resolution). That
+ * single module graph is what lets `collectComponents`'s duplicate-name check
+ * (`../discover.ts`) run over real, live object identity — "the same
+ * component re-exported under two bindings" only detects correctly when both
+ * bindings really do resolve to the same in-memory object, which requires
+ * every `*.component.ts` file for one discovery call to share one module
+ * cache inside a single child (see `../discover.ts`'s `collectComponents` doc
+ * for the full identity-correctness argument).
+ */
+// #3878: the TypeScript source, also when this module runs compiled from dist/.
+const HERE = chantSourceDir(import.meta.url);
+const COMPONENTS_DIR = join(HERE, "..");
+/** Absolute paths to chant's OWN trusted modules the generated driver imports — resolved relative to THIS file's own location on disk, exactly like `../../discovery/sandbox/driver.ts` does for the entity path (works whether chant runs from the monorepo or a consumer's `node_modules`). */
+const DISCOVER_MODULE = join(COMPONENTS_DIR, "discover.ts");
+const CHILD_ERRORS_MODULE = join(COMPONENTS_DIR, "..", "discovery", "sandbox", "child-errors.ts");
+// chant #1108 — same re-binding the entity driver does (see ../../discovery/
+// sandbox/driver.ts's PARAMS_MODULE doc): the child's copy of the shared
+// `params` object starts empty, so a `*.component.ts` file importing
+// `@intentius/chant/params` would otherwise see `{}` under sandboxed
+// discovery no matter what the parent resolved.
+const PARAMS_MODULE = join(COMPONENTS_DIR, "..", "params.ts");
+/** Escape a value for embedding as a JS/TS source-level literal. */
+function lit(value) {
+    return JSON.stringify(value);
+}
+/**
+ * Generate the component driver module's full TypeScript source. Written to
+ * a tmp file and bundled (`../../discovery/sandbox/bundle.ts`'s `bundleDriver`
+ * — generic, reused as-is) before being handed to a sandboxed child — never
+ * executed directly by the parent process.
+ */
+export function generateComponentDriverSource(options) {
+    const { files } = options;
+    const lines = [
+        `import { collectComponents } from ${lit(DISCOVER_MODULE)};`,
+        `import { classifyChildError } from ${lit(CHILD_ERRORS_MODULE)};`,
+        `import { setBuildParams } from ${lit(PARAMS_MODULE)};`,
+        `import { writeSync } from "node:fs";`,
+        ``,
+        // chant #1108 — snapshot of the parent's resolved build-time parameter
+        // values (scalars only), bound before any component file is imported.
+        `setBuildParams(${lit({ ...currentBuildParams })});`,
+        ``,
+        // chant#2461 — awaits the send and fails loudly if it cannot be delivered.
+        ...sendFunctionSource(),
+        ``,
+        `async function main() {`,
+        `  const modules = [];`,
+        `  const errors = [];`,
+    ];
+    for (const file of files) {
+        // `file` (as discovered by `findComponentFiles`, `../discover.ts`) may be
+        // relative to whatever cwd-relative `path` `discoverComponents` was
+        // called with — `chant list --components examples/foo` never resolves
+        // its argument before discovery, matching the unsandboxed import loop's
+        // own tolerance for that (`pathToFileURL(resolve(filePath)).href`, see
+        // `../discover.ts`'s `importAndCollectComponents`). A bare relative
+        // string hits Node's *bare-specifier* (package) resolution instead of
+        // being treated as a path, so only the import target — never the `file`
+        // key `collectComponents` dedupes and reports by — is resolved to an
+        // absolute filesystem path here, in THIS (parent) process, before being
+        // embedded as a literal in the bundled child (mirrors `../../discovery/
+        // sandbox/driver.ts`'s own literal-specifier `import()`s, which are
+        // likewise plain absolute paths, not `file://` URLs — kept that way
+        // rather than converting to a URL since esbuild's bundler is only
+        // verified to trace/inline a literal filesystem-path specifier).
+        const absoluteFile = resolve(file);
+        lines.push(`  try {`, `    const mod = await import(${lit(absoluteFile)});`, `    modules.push({ file: ${lit(file)}, exports: mod });`, `  } catch (err) {`, `    errors.push(classifyChildError(${lit(file)}, err).toJSON());`, `  }`);
+    }
+    lines.push(``, `  const collected = collectComponents(modules);`, `  for (const err of collected.errors) errors.push(err.toJSON());`, ``, 
+    // Plain JSON: no entity-wire codec needed (see this module's doc + chant
+    // #1051's issue — `projectToJson`, ../component.ts, already proves the
+    // bare JSON.parse(JSON.stringify()) round-trip for a Component).
+    `  const components = [];`, `  for (const [name, discovered] of collected.components) {`, `    components.push({ name, component: discovered.component, exportName: discovered.exportName, filePath: discovered.filePath });`, `  }`, `  await send({ components, errors });`, `}`, ``, `main().catch((err) =>`, `  send({ components: [], errors: [classifyChildError("", err).toJSON()], fatal: true }),`, `);`);
+    return lines.join("\n");
+}

package/dist/components/sandbox/run.js

@@ -0,0 +1,115 @@
+import { fork } from "node:child_process";
+import { realpathSync, rmSync } from "node:fs";
+import { resolve } from "node:path";
+import { bundleDriver } from "../../discovery/sandbox/bundle.js";
+import { classifyChildError } from "../../discovery/sandbox/child-errors.js";
+import { settleOnExitAfterChannelDrains } from "../../discovery/sandbox/fork.js";
+import { DiscoveryError } from "../../errors.js";
+import { generateComponentDriverSource } from "./driver.js";
+/** How long to wait for the sandboxed child to report back before treating it as hung and killing it. Generous, matching the entity path's own budget. */
+const CHILD_TIMEOUT_MS = 120000;
+function isChildResponse(value) {
+    return typeof value === "object" && value !== null && "components" in value && "errors" in value;
+}
+/**
+ * Import `files` (every discovered `*.component.ts` file) together, isolated,
+ * in one sandboxed child process, and collect their `Component`-shaped
+ * exports — including the duplicate-name check, which runs INSIDE the child
+ * over live objects before anything is serialized (`../discover.ts`'s
+ * `collectComponents`, bundled into the driver).
+ *
+ * @param files - Absolute paths to every discovered `*.component.ts` file.
+ * @param buildRoot - The directory `discoverComponents` was pointed at — used
+ *   to compute the project-directory read allowance, mirroring `../../
+ *   discovery/sandbox/run.ts`.
+ */
+export async function discoverComponentsSandboxed(files, buildRoot) {
+    if (files.length === 0) {
+        return { components: new Map(), errors: [], bundleMs: 0, bundleBytes: 0 };
+    }
+    const driverSource = generateComponentDriverSource({ files });
+    const { bundlePath, bundleDir, externalReadPaths, durationMs, bytes } = await bundleDriver(driverSource);
+    try {
+        let projectRealpath;
+        try {
+            projectRealpath = realpathSync(resolve(buildRoot));
+        }
+        catch {
+            projectRealpath = resolve(buildRoot);
+        }
+        const response = await runChildProcess(bundlePath, bundleDir, projectRealpath, externalReadPaths);
+        const errors = (response.errors ?? []).map((e) => new DiscoveryError(e.file, e.message, e.type));
+        if (response.fatal) {
+            return { components: new Map(), errors, bundleMs: durationMs, bundleBytes: bytes };
+        }
+        const components = new Map();
+        for (const entry of response.components ?? []) {
+            components.set(entry.name, {
+                component: entry.component,
+                exportName: entry.exportName,
+                filePath: entry.filePath,
+            });
+        }
+        return { components, errors, bundleMs: durationMs, bundleBytes: bytes };
+    }
+    catch (err) {
+        return {
+            components: new Map(),
+            errors: [classifyChildError("", err, "import")],
+            bundleMs: durationMs,
+            bundleBytes: bytes,
+        };
+    }
+    finally {
+        rmSync(bundleDir, { recursive: true, force: true });
+    }
+}
+/** Fork the bundle under `--permission`, with a scrubbed environment, and resolve with its one IPC message (or reject on crash/timeout/fork error). Mirrors `../../discovery/sandbox/run.ts`'s `runChildProcess`. */
+function runChildProcess(bundlePath, bundleDir, projectRealpath, externalReadPaths) {
+    return new Promise((resolvePromise, reject) => {
+        const readAllowances = [bundleDir, projectRealpath, ...externalReadPaths].map((p) => `--allow-fs-read=${p}`);
+        const child = fork(bundlePath, [], {
+            execArgv: ["--permission", ...readAllowances],
+            // chant #1051 — Node's Permission Model does not gate `process.env`;
+            // scrubbing it here is the only way to keep the ambient environment out
+            // of untrusted project source's reach, exactly as the entity path does.
+            env: { PATH: process.env.PATH ?? "" },
+            stdio: ["ignore", "pipe", "pipe", "ipc"],
+        });
+        let settled = false;
+        let stderrBuf = "";
+        const timeout = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill();
+            reject(new Error(`sandboxed component discovery timed out after ${CHILD_TIMEOUT_MS}ms`));
+        }, CHILD_TIMEOUT_MS);
+        child.stderr?.on("data", (chunk) => {
+            stderrBuf += chunk.toString();
+        });
+        child.on("message", (msg) => {
+            if (settled || !isChildResponse(msg))
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            resolvePromise(msg);
+        });
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            reject(err);
+        });
+        // chant#2461 — a payload can still be in the IPC socket when the exit is
+        // handled; see settleOnExitAfterChannelDrains.
+        settleOnExitAfterChannelDrains(child, (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            reject(new Error(`sandboxed component discovery child exited before reporting results (code ${code}, signal ${signal})${stderrBuf.trim() ? `: ${stderrBuf.trim()}` : ""}`));
+        });
+    });
+}

package/dist/components/starter-plugin.js

@@ -0,0 +1,104 @@
+/**
+ * The starter verb set (epic #551, #554/#557/#558), wrapped as a
+ * `CapabilityPlugin` (#559) — the built-in, always-loaded plugin that
+ * carries every Phase 1 capability forward under the Phase 2 plugin
+ * contract with **no behavior change**.
+ *
+ * Migration path from Phase 1 to Phase 2: Phase 1 (`createCapabilityRegistry`,
+ * ./registry.ts) constructed a `CapabilityRegistry` by registering each
+ * starter verb directly. Phase 2 introduces `CapabilityPlugin` as the
+ * discoverable, typed package contract (./capability-plugin.ts) that
+ * mirrors how lexicons are packaged (../lexicon.ts). Rather than rewrite the
+ * starter verbs, this module packages the *exact same* verb list as one
+ * `CapabilityPlugin` named "starter" — so:
+ *
+ *  - `createCapabilityRegistry()` (./registry.ts) now builds its registry by
+ *    registering `starterCapabilityPlugin.capabilities()` instead of calling
+ *    `registry.register(...)` once per verb inline. Same kinds, same
+ *    instances, same order, same resulting registry — verified by
+ *    ./registry.test.ts, unchanged.
+ *  - `buildCapabilityRegistry()` (./capability-plugin-loader.ts), the new
+ *    Phase 2 entry point, always loads this plugin first, then layers any
+ *    additional third-party capability plugins on top by `kind`.
+ *  - The driver (./driver.ts) and every pilot (./pilots/*.pilot.ts) consume
+ *    only a `CapabilityRegistry` instance and never construct one directly
+ *    from verb modules, so neither needed to change for this migration —
+ *    the compatibility guarantee #559 asks for.
+ */
+import { dockerBuildCapability, zipPackageCapability, jvmBuildCapability, generateSbomCapability, signCapability, attestProvenanceCapability, verifyCapability, scanVulnerabilitiesCapability, vulnGateCapability, waitClusterHealthyCapability, waitEndpointCapability, healthGateCapability, shellCapability, ensureSecretCapability, wranglerDeployCapability, wranglerVersionsPromoteCapability, r2SyncCapability, } from "./verbs/index.js";
+import { ownPackageVersion } from "./capability-plugin.js";
+/**
+ * Every `kind` in the starter verb set, grouped by family, per epic #551 and
+ * docs/components/capabilities.mdx. Source of truth (moved here from
+ * ./registry.ts in #559 to avoid a module cycle: ./registry.ts's
+ * `createCapabilityRegistry` depends on `starterCapabilityPlugin`, so this
+ * plugin module cannot depend back on ./registry.ts). Re-exported from
+ * ./registry.ts unchanged for existing importers.
+ */
+export const STARTER_VERB_FAMILIES = {
+    build: ["docker-build", "zip-package", "jvm-build"],
+    // `extract-config-bom` parses a synthesized CloudFormation template, so it
+    // moved to the aws lexicon (#684) alongside the other AWS leaves; core's sbom
+    // family keeps only the agnostic, artifact-type-keyed `generate-sbom`.
+    sbom: ["generate-sbom"],
+    supplyChainSecurity: ["sign", "attest-provenance", "verify"],
+    supplyChainPolicy: ["scan-vulnerabilities", "vuln-gate"],
+    // Only the *agnostic* wait/verify verbs are in the starter set; the
+    // cloud-specific waits (`wait-for-stack`/`wait-steady-state`/`wait-job`) are
+    // contributed by the relevant lexicon (aws) — see docs/components/cloud-boundary.
+    waitVerify: ["wait-cluster-healthy", "wait-endpoint", "health-gate"],
+    // generated-once secret materialization (#1829, epic #1365): read-then-write,
+    // present means done; the k8s store adapter is #1830.
+    secrets: ["ensure-secret"],
+    escapeHatch: ["shell"],
+    // The Cloudflare Workers apply leaves (#1293, epic #1296) — placed in core
+    // rather than a cloudflare lexicon (decided explicitly, see ./verbs/wrangler.ts's
+    // module doc): the epic cedes the Workers plane to `wrangler` entirely, and
+    // there is no cloudflare lexicon for these three verbs to live in. Revisit
+    // if/when the zone-plane lexicon (#1294) lands.
+    cloudflare: ["wrangler-deploy", "wrangler-versions-promote", "r2-sync"],
+};
+/**
+ * Every starter-set verb, in the same registration order Phase 1's
+ * `createCapabilityRegistry` used. Listed individually (not as a shared
+ * array literal) for the same reason Phase 1 registered them individually:
+ * each capability's own `In`/`Out` generics must be inferred from its own
+ * type, not widened to a lossy common supertype.
+ */
+function starterCapabilities() {
+    return [
+        dockerBuildCapability,
+        zipPackageCapability,
+        jvmBuildCapability,
+        generateSbomCapability,
+        signCapability,
+        attestProvenanceCapability,
+        verifyCapability,
+        scanVulnerabilitiesCapability,
+        vulnGateCapability,
+        waitClusterHealthyCapability,
+        waitEndpointCapability,
+        healthGateCapability,
+        ensureSecretCapability,
+        shellCapability,
+        wranglerDeployCapability,
+        wranglerVersionsPromoteCapability,
+        r2SyncCapability,
+    ];
+}
+/**
+ * The built-in capability plugin carrying the entire Phase 1 starter verb
+ * set forward under the Phase 2 contract. Always loaded first by
+ * `buildCapabilityRegistry` (./capability-plugin-loader.ts).
+ */
+export const starterCapabilityPlugin = {
+    name: "starter",
+    // The core package's own version (#1505) — lockstep releases bump it, so a
+    // literal here would go stale every `just release`. A getter, so the
+    // package.json read happens on first access rather than at import time.
+    get version() {
+        return ownPackageVersion(import.meta.url);
+    },
+    capabilities: starterCapabilities,
+    families: () => STARTER_VERB_FAMILIES,
+};

package/dist/components/verbs/__tests__/mock-cloud-executor.js

@@ -0,0 +1,68 @@
+/**
+ * `MockCloudExecutor` — an in-memory fake of the *agnostic* `CloudExecutor`
+ * (../cloud-executor.ts) for tests: the `docker` build/push client and the
+ * Neo4j bolt probe, the two clients core still owns. No live docker, ever, in
+ * a test run — every method records its call and returns a canned result.
+ *
+ * The AWS clients' mock moved to the aws lexicon alongside their
+ * implementations (`@intentius/chant-lexicon-aws/components`).
+ */
+/** Build a fresh mock agnostic `CloudExecutor`. Every method is deterministic and synchronous-fast — no real polling delay. */
+export function createMockCloudExecutor(options = {}) {
+    const calls = [];
+    const record = (client, method, args) => calls.push({ client, method, args });
+    const clusters = new Map(Object.entries(options.clusters ?? {}).map(([k, v]) => [k, v.healthyCount ?? Number.MAX_SAFE_INTEGER]));
+    const docker = {
+        async build(args) {
+            record("docker", "build", args);
+            if (options.failDocker)
+                throw new Error(`docker build failed for ${args.context}`);
+            return { digest: `sha256:${fakeDigest("build", args.context, args.tag)}` };
+        },
+        async save(args) {
+            record("docker", "save", args);
+        },
+        async load(args) {
+            record("docker", "load", args);
+            return { digest: `sha256:${fakeDigest("load", args.inFile)}` };
+        },
+        async tag(args) {
+            record("docker", "tag", args);
+        },
+        async push(args) {
+            record("docker", "push", args);
+            if (options.failDocker)
+                throw new Error(`docker push failed for ${args.image}`);
+            return { digest: `sha256:${fakeDigest("push", args.image)}` };
+        },
+        async remoteDigest(image) {
+            record("docker", "remoteDigest", image);
+            return `sha256:${fakeDigest("remote", image)}`;
+        },
+    };
+    const neo4j = {
+        async probe(args) {
+            record("neo4j", "probe", args);
+            const endpoints = args.cluster
+                .split(",")
+                .map((s) => s.trim())
+                .filter(Boolean);
+            const healthy = clusters.get(args.cluster) ?? endpoints.length;
+            return { healthyCount: Math.min(healthy, endpoints.length), total: endpoints.length };
+        },
+    };
+    return {
+        executor: { docker, neo4j },
+        calls,
+        setClusterHealth: (cluster, healthyCount) => clusters.set(cluster, healthyCount),
+    };
+}
+/** Deterministic fake digest suffix derived from its inputs — stable across calls with the same args, distinct otherwise. */
+function fakeDigest(...parts) {
+    let hash = 0;
+    const input = parts.join("|");
+    for (let i = 0; i < input.length; i++) {
+        hash = (hash * 31 + input.charCodeAt(i)) | 0;
+    }
+    return Math.abs(hash).toString(16).padStart(8, "0").repeat(4).slice(0, 64);
+}

package/dist/components/verbs/__tests__/mock-process-runner.js

@@ -0,0 +1,45 @@
+/**
+ * `MockProcessRunner` — an in-memory fake of `ProcessRunner`
+ * (../process-runner.ts) for tests. No live `syft`/`buildx`/
+ * `cyclonedx-maven`/`cdxgen`/`oras`, no child process spawned at all: every
+ * call is recorded, and `run`/`available` return scripted results — the same
+ * convention `../__tests__/mock-cloud-executor.ts` uses for `CloudExecutor`.
+ *
+ * Every test that exercises a #610 real backend (`ToolSbomGenerator`,
+ * `OrasReferrerLookup`, `publish-image`'s referrer-attach step) builds one
+ * `MockProcessRunner`, scripts which tools are "installed" and what each
+ * command's canned stdout is, and passes it in — never touching the real,
+ * `child_process`-backed runner.
+ */
+/** Build a fresh mock `ProcessRunner`. Every method is deterministic and synchronous-fast — no real process spawned, no real delay. */
+export function createMockProcessRunner(options = {}) {
+    const calls = [];
+    const tools = new Map(Object.entries(options.tools ?? {}));
+    const responses = new Map(Object.entries(options.responses ?? {}));
+    const failures = new Map(Object.entries(options.failures ?? {}));
+    const defaultAvailable = options.defaultAvailable ?? true;
+    const runner = {
+        async run(command, runOptions) {
+            calls.push({ command, options: runOptions });
+            for (const [substring, message] of failures) {
+                if (command.includes(substring))
+                    throw new Error(message);
+            }
+            for (const [substring, stdout] of responses) {
+                if (command.includes(substring))
+                    return { stdout, stderr: "" };
+            }
+            return { stdout: "", stderr: "" };
+        },
+        async available(tool) {
+            calls.push({ command: `command -v ${tool}` });
+            return tools.has(tool) ? tools.get(tool) : defaultAvailable;
+        },
+    };
+    return {
+        runner,
+        calls,
+        setAvailable: (tool, available) => tools.set(tool, available),
+        setResponse: (commandSubstring, stdout) => responses.set(commandSubstring, stdout),
+    };
+}

package/dist/components/verbs/__tests__/mock-sbom-generator.js

@@ -0,0 +1,56 @@
+/**
+ * `MockSbomGenerator` — an in-memory fake of `SbomGenerator`
+ * (../sbom-generator.ts) for tests. No live `syft`/`docker buildx`/
+ * `cyclonedx-maven`/`cdxgen`, no network: every method records its call and
+ * returns a deterministic, canned `SbomDocument` derived from its inputs, the
+ * same convention `../__tests__/mock-cloud-executor.ts` uses for
+ * `CloudExecutor` (a fake digest suffix derived from the call's arguments,
+ * stable across calls with the same args).
+ *
+ * Every test that exercises `generate-sbom` (../sbom.ts) builds one
+ * `MockSbomGenerator` and passes it to `createGenerateSbomCapability`,
+ * never touching a real scanner.
+ */
+import { SBOM_MEDIA_TYPES, DEFAULT_SBOM_FORMAT } from "../sbom-generator.js";
+/** Build a fresh mock `SbomGenerator`. Every method is deterministic and synchronous-fast — no real scan delay. */
+export function createMockSbomGenerator(options = {}) {
+    const calls = [];
+    const record = (method, args) => calls.push({ method, args });
+    function fakeSbom(kind, subject, format, generatorName) {
+        const resolvedFormat = format ?? DEFAULT_SBOM_FORMAT;
+        return {
+            format: resolvedFormat,
+            mediaType: SBOM_MEDIA_TYPES[resolvedFormat],
+            bytes: JSON.stringify({ fake: true, kind, subject, format: resolvedFormat }),
+            packageCount: options.packageCount ?? 3,
+            generator: options.generatorName ?? generatorName,
+        };
+    }
+    const generator = {
+        async forImage(input) {
+            record("forImage", input);
+            if (options.fail)
+                throw new Error(`sbom generation failed for image ${input.imagePath}`);
+            return fakeSbom("image", input.imagePath, input.format, "mock-buildkit");
+        },
+        async forJar(input) {
+            record("forJar", input);
+            if (options.fail)
+                throw new Error(`sbom generation failed for jar ${input.jarPath}`);
+            return fakeSbom("jar", input.jarPath, input.format, "mock-syft");
+        },
+        async forZip(input) {
+            record("forZip", input);
+            if (options.fail)
+                throw new Error(`sbom generation failed for zip ${input.zipPath}`);
+            return fakeSbom("zip", input.zipPath, input.format, "mock-syft");
+        },
+        async forDir(input) {
+            record("forDir", input);
+            if (options.fail)
+                throw new Error(`sbom generation failed for dir ${input.path}`);
+            return fakeSbom("dir", input.path, input.format, "mock-cdxgen");
+        },
+    };
+    return { generator, calls };
+}