@intentius/chant 0.124.12 → 0.124.14

package/dist/testing.js

@@ -0,0 +1,295 @@
+/**
+ * `@intentius/chant/testing` (#1224) — the live-stack test harness.
+ *
+ * A vitest suite deploys a real instance of its project once, asserts against
+ * it, and tears it down — emulator-locally on a dev machine, real-cloud in CI,
+ * with the same suite text. One call composes machinery that already exists:
+ *
+ * - **build** — the same programmatic path `chant build` takes: config
+ *   resolution (`buildParams` + the ownership marker) mirrored from the CLI,
+ *   then `build()` over the project's own serializers.
+ * - **apply** — an additive `nativeApply` per built lexicon output, run
+ *   in-process through the local Op executor (`runOpLocally`). `deleteMode`
+ *   is `"never"`: a test deploy creates and updates, nothing else.
+ * - **destroy** — #1222's marker-scoped teardown (`executeTeardown`), called
+ *   in-process for exactly this suite's environment. Stateless by design:
+ *   a crashed suite's environment is recovered by calling destroy again (or
+ *   `chant lifecycle teardown <env> --yes`).
+ * - **assertLive** (#1857) — `describeResources()` against exactly one
+ *   declared entity, turned into a pass or a thrown failure. Preserves
+ *   #1089's tri-state rather than collapsing it: NOT-OBSERVED throws {@link
+ *   UnobservedAssertionError}, never a silent pass and never an ordinary
+ *   failure, because chant could not read the entity is not the same claim
+ *   as chant read it and it is gone.
+ *
+ * ## Isolation
+ *
+ * Every deploy targets its own environment: `test-<suite>-<nonce>` by default
+ * ({@link testEnvName}), so parallel CI jobs never collide. The environment
+ * is the teardown key — everything the deploy stamps carries the ownership
+ * marker `{ stack, env }`, and `destroy()` selects on that identity and
+ * nothing else. A project that declares `environments` must legalize the
+ * dynamic names with a pattern entry (#1221):
+ *
+ * ```ts
+ * environments: ["dev", "prod", { name: "test-*", endpoint: "http://localhost:4566" }]
+ * ```
+ *
+ * ## Emulators
+ *
+ * The harness is emulator-aware the same way `--live` reads are (#1166): the
+ * target environment's declared `endpoint` is injected into each lexicon's
+ * ambient endpoint variable (`AWS_ENDPOINT_URL`, …) for the apply and the
+ * teardown — unless the variable is already set. Ambient always wins, so the
+ * env vars `chant emulator up --json` reports (#920) take precedence when
+ * exported, and a CI job pointing the identical suite at a real account just
+ * leaves both unset.
+ */
+import { basename, join, resolve } from "node:path";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { build } from "./build.js";
+import { isResourceDeclarable } from "./declarable.js";
+import { loadChantConfigUpward, resolveOwnershipStack, } from "./config.js";
+import { resolveBuildParams } from "./build-params.js";
+import { ENV_VAR, unknownEnvError } from "./env.js";
+import { applyLiveEndpoint } from "./live-endpoint.js";
+import { loadPlugins, resolveProjectLexicons, collectBuildRootContributors } from "./cli/plugins.js";
+import { runOpLocally } from "./op/local-executor.js";
+import { loadActivities, loadProfiles } from "./op/activity-registry.js";
+import { executeTeardown } from "./lifecycle/teardown.js";
+import { assertLiveEntity, LiveAssertionError, UnobservedAssertionError, } from "./lifecycle/assert-live.js";
+export { LiveAssertionError, UnobservedAssertionError };
+/**
+ * Which `nativeApply` target deploys each lexicon's built output. Only these
+ * lexicons have a native apply mechanism; an output from any other lexicon
+ * (helm values, a CI pipeline file, …) is returned to the caller but not
+ * applied — deploying it is not what a live-stack test means by "deploy".
+ */
+const APPLY_TARGETS = {
+    aws: "cloudformation",
+    k8s: "kubectl",
+    azure: "arm",
+    gcp: "gcp",
+    fly: "fly",
+};
+/**
+ * Thrown by {@link DeployedStack.destroy} when the environment cannot be
+ * called clean: candidates still `failed` after the retry pass, or the plan
+ * had holes (#1089 — parts of the estate could not be read, so "nothing
+ * left" would be a claim about what was readable, not about the environment).
+ * Carries the full report for diagnosis.
+ */
+export class TeardownIncompleteError extends Error {
+    constructor(report) {
+        const failed = report.outcomes.filter((o) => o.outcome === "failed");
+        const parts = [];
+        if (failed.length > 0) {
+            parts.push(`${failed.length} candidate(s) failed to delete: ` +
+                failed.map((o) => `${o.lexicon}/${o.name}${o.detail ? ` (${o.detail})` : ""}`).join(", "));
+        }
+        if (report.plan.holes.length > 0) {
+            parts.push(`${report.plan.holes.length} hole(s) — resources chant may own but could not read: ` +
+                report.plan.holes.map((h) => `${h.lexicon}/${h.name} (${h.reason})`).join(", "));
+        }
+        super(`teardown of "${report.environment}" is incomplete — ${parts.join("; ")}`);
+        this.report = report;
+        this.name = "TeardownIncompleteError";
+    }
+}
+/**
+ * The default environment name for one suite run: `test-<suite>-<nonce>`.
+ * The `test-` prefix is what a project's `"test-*"` pattern entry (#1221)
+ * legalizes; the nonce keeps parallel CI jobs of the same suite apart.
+ */
+export function testEnvName(suite) {
+    const slug = suite
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 24)
+        .replace(/-+$/, "") || "suite";
+    const nonce = Math.random().toString(36).slice(2, 8).padEnd(6, "0");
+    return `test-${slug}-${nonce}`;
+}
+/** JSON output starts with a brace/bracket; everything else is written as YAML. */
+function outputExtension(content) {
+    const head = content.trimStart();
+    return head.startsWith("{") || head.startsWith("[") ? ".json" : ".yaml";
+}
+/**
+ * Write each lexicon's built output to a scratch directory and return the
+ * primary file path per lexicon. Secondary files (a multi-file serializer
+ * result) land beside the primary under their own names.
+ */
+function writeOutputs(outputs, env) {
+    const dir = mkdtempSync(join(tmpdir(), `chant-testing-${env}-`));
+    const paths = new Map();
+    for (const [lexicon, output] of outputs) {
+        const primary = typeof output === "string" ? output : output.primary;
+        const path = join(dir, `${lexicon}${outputExtension(primary)}`);
+        writeFileSync(path, primary);
+        if (typeof output !== "string" && output.files) {
+            for (const [name, content] of Object.entries(output.files)) {
+                writeFileSync(join(dir, basename(name)), content);
+            }
+        }
+        paths.set(lexicon, path);
+    }
+    return paths;
+}
+/**
+ * Deploy a live instance of the project in `dir` for one test suite.
+ *
+ * Build (the CLI's own config resolution: `buildParams`, ownership marker,
+ * build roots) + additive apply (one `nativeApply` per built output with a
+ * native mechanism, via the local Op executor). Returns the handle the suite
+ * holds: outputs, entities, the environment name, and `destroy`.
+ *
+ * The ownership marker stamped on every resource is `{ stack: ownership.stack,
+ * env: <this deploy's environment> }` — the marker env always follows the
+ * suite environment, whatever `ownership.env` in config says, because the
+ * marker is the only thing `destroy()` selects on. A project with no
+ * `ownership.stack` is refused up front: a deploy that stamps nothing is a
+ * deploy nothing can sweep.
+ *
+ * Failures are thrown, never returned: build errors, unresolved parameters,
+ * an illegal environment name, and a failed apply (the local executor's
+ * `OpRunFailure`) all reject the returned promise.
+ */
+export async function deployStack(options) {
+    const dir = resolve(options.dir);
+    const { config, configPath } = await loadChantConfigUpward(dir);
+    const env = options.env ?? testEnvName(options.suite ?? basename(dir));
+    const envError = unknownEnvError(env, config.environments);
+    if (envError) {
+        throw new Error(`${envError} The harness derives per-run environment names — declare a "test-*" pattern entry ` +
+            `in chant.config.ts's environments to legalize them (#1221).`);
+    }
+    const stack = resolveOwnershipStack(config);
+    if (stack === undefined) {
+        throw new Error(`${dir}: this project declares no ownership.stack — the harness's destroy() is marker-scoped ` +
+            `and would have nothing to select on. Set ownership: { stack: "<name>" } in chant.config.ts.`);
+    }
+    const marker = { stack, env };
+    const plugins = options.plugins ?? (await loadPlugins(await resolveProjectLexicons(dir)));
+    // Build parameters, resolved as `chant build --param ...` resolves them.
+    // A project whose config maps `env` to a build parameter gets this deploy's
+    // environment automatically, unless the caller passed one explicitly.
+    const cli = {};
+    for (const [name, value] of Object.entries(options.params ?? {}))
+        cli[name] = String(value);
+    if (config.buildParams && "env" in config.buildParams && !("env" in cli))
+        cli.env = env;
+    const resolution = resolveBuildParams(config.buildParams, { cli, env: process.env });
+    if (resolution.errors.length > 0) {
+        throw new Error(`${dir}: build parameters did not resolve —\n  ${resolution.errors.join("\n  ")}`);
+    }
+    const projectRoot = configPath ? resolve(configPath, "..") : dir;
+    const configRecord = config;
+    // Env-aware source branches on env() (#505) during discovery — scope the
+    // variable to the build and restore whatever the shell had.
+    const priorEnv = process.env[ENV_VAR];
+    let result;
+    try {
+        process.env[ENV_VAR] = env;
+        result = await build(dir, plugins.map((p) => p.serializer), undefined, {
+            ownership: marker,
+            config: configRecord,
+            lexicons: plugins.map((p) => p.name),
+            intrinsics: plugins.flatMap((p) => p.intrinsics?.() ?? []),
+            buildParams: resolution.provenance,
+            buildRoots: collectBuildRootContributors(plugins, configRecord, projectRoot),
+        });
+    }
+    finally {
+        if (priorEnv === undefined)
+            delete process.env[ENV_VAR];
+        else
+            process.env[ENV_VAR] = priorEnv;
+    }
+    if (result.errors.length > 0) {
+        const messages = result.errors.map((e) => e.message);
+        throw new Error(`${dir}: build failed —\n  ${messages.join("\n  ")}`);
+    }
+    // One additive apply step per built output with a native mechanism.
+    const targets = { ...APPLY_TARGETS, ...options.applyTargets };
+    const paths = writeOutputs(result.outputs, env);
+    const steps = [];
+    for (const [lexicon, path] of paths) {
+        const target = targets[lexicon];
+        if (!target)
+            continue;
+        steps.push({
+            kind: "activity",
+            fn: "nativeApply",
+            args: { target, env, output: path, deleteMode: "never" },
+            profile: "longInfra",
+        });
+    }
+    if (steps.length === 0) {
+        throw new Error(`${dir}: nothing to deploy — no built output has a native apply target ` +
+            `(built: ${[...result.outputs.keys()].join(", ") || "none"}; targets exist for: ${Object.keys(targets).join(", ")}).`);
+    }
+    const op = {
+        name: `deploy-${env}`,
+        overview: `test harness deploy of ${dir} into ${env}`,
+        phases: [{ name: "Deploy", steps }],
+    };
+    const activities = options.activities ?? (await loadActivities(plugins.map((p) => p.name)));
+    const profiles = options.profiles ?? (await loadProfiles());
+    // The environment's declared endpoint (#1166) applies to the deploy the way
+    // it applies to a --live read — and ambient always wins, so exported
+    // `chant emulator up --json` vars take precedence.
+    const applied = applyLiveEndpoint(config.environments, env, plugins);
+    try {
+        await runOpLocally(op, activities, profiles);
+    }
+    finally {
+        applied.restore();
+    }
+    const assertLive = async (name, assertOptions = {}) => {
+        const entity = result.entities.get(name);
+        if (!entity) {
+            throw new LiveAssertionError(`assertLive("${name}"): no such entity — this deploy built ${[...result.entities.keys()].join(", ") || "nothing"}.`);
+        }
+        const entityPlugin = plugins.find((p) => p.name === entity.lexicon);
+        if (!entityPlugin) {
+            throw new LiveAssertionError(`assertLive("${name}"): no loaded lexicon named "${entity.lexicon}".`);
+        }
+        const entityOutput = result.outputs.get(entity.lexicon);
+        const entityBuildOutput = entityOutput === undefined ? "" : typeof entityOutput === "string" ? entityOutput : entityOutput.primary;
+        const props = isResourceDeclarable(entity) ? (entity.props ?? {}) : {};
+        const endpointForAssert = applyLiveEndpoint(config.environments, env, plugins);
+        try {
+            return await assertLiveEntity({
+                plugin: entityPlugin,
+                name,
+                entityType: entity.entityType,
+                props,
+                buildOutput: entityBuildOutput,
+                environment: env,
+                marker,
+                ...assertOptions,
+            });
+        }
+        finally {
+            endpointForAssert.restore();
+        }
+    };
+    const destroy = async () => {
+        const endpointForTeardown = applyLiveEndpoint(config.environments, env, plugins);
+        let report;
+        try {
+            report = await executeTeardown({ environment: env, stack, plugins });
+        }
+        finally {
+            endpointForTeardown.restore();
+        }
+        const failed = report.outcomes.some((o) => o.outcome === "failed");
+        if (failed || report.plan.holes.length > 0)
+            throw new TeardownIncompleteError(report);
+        return report;
+    };
+    return { outputs: result.outputs, entities: result.entities, env, assertLive, destroy };
+}

package/dist/toml-emit.js

@@ -0,0 +1,153 @@
+/**
+ * TOML emitter.
+ *
+ * Converts JavaScript objects to TOML document strings.
+ * Handles scalars, tables, arrays, array of tables, and inline tables.
+ */
+import { escapeKey, sortKeys } from "./toml-utils.js";
+/**
+ * Emit a JavaScript object as a TOML document string.
+ *
+ * - Top-level scalars, arrays of scalars → bare key-value pairs.
+ * - Nested objects → `[section]` tables.
+ * - Arrays of objects → `[[section]]` array of tables.
+ * - Deeply nested objects → `[parent.child]` dotted sections.
+ */
+export function emitTOML(value, options) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("emitTOML expects a plain object at the top level");
+    }
+    const lines = [];
+    if (options?.header) {
+        for (const line of options.header.split("\n")) {
+            lines.push(`# ${line}`);
+        }
+        lines.push("");
+    }
+    const obj = value;
+    emitTable(obj, [], lines, options?.keyOrder);
+    // Trim trailing blank lines, ensure single trailing newline
+    while (lines.length > 0 && lines[lines.length - 1] === "") {
+        lines.pop();
+    }
+    return lines.join("\n") + "\n";
+}
+/**
+ * Emit a TOML table (recursively handles nested tables and array of tables).
+ */
+function emitTable(obj, path, lines, keyOrder) {
+    const keys = sortKeys(Object.keys(obj), keyOrder);
+    // First pass: emit all scalar / inline values
+    for (const key of keys) {
+        const val = obj[key];
+        if (val === undefined)
+            continue;
+        if (isTableValue(val))
+            continue; // handled in second pass
+        if (isArrayOfTables(val))
+            continue; // handled in second pass
+        lines.push(`${escapeKey(key)} = ${emitValue(val)}`);
+    }
+    // Second pass: emit nested tables
+    for (const key of keys) {
+        const val = obj[key];
+        if (val === undefined)
+            continue;
+        if (isArrayOfTables(val)) {
+            const arr = val;
+            for (const item of arr) {
+                lines.push("");
+                const sectionPath = [...path, key];
+                lines.push(`[[${sectionPath.map(escapeKey).join(".")}]]`);
+                emitTable(item, sectionPath, lines, keyOrder);
+            }
+        }
+        else if (isTableValue(val)) {
+            lines.push("");
+            const sectionPath = [...path, key];
+            lines.push(`[${sectionPath.map(escapeKey).join(".")}]`);
+            emitTable(val, sectionPath, lines, keyOrder);
+        }
+    }
+}
+/**
+ * Check if a value should be emitted as a `[table]` section.
+ */
+function isTableValue(val) {
+    return (typeof val === "object" &&
+        val !== null &&
+        !Array.isArray(val) &&
+        !(val instanceof Date));
+}
+/**
+ * Check if a value is an array of tables (`[[section]]`).
+ */
+function isArrayOfTables(val) {
+    if (!Array.isArray(val) || val.length === 0)
+        return false;
+    return val.every((item) => typeof item === "object" && item !== null && !Array.isArray(item) && !(item instanceof Date));
+}
+/**
+ * Emit a TOML value (scalar, array of scalars, inline table).
+ */
+function emitValue(val) {
+    if (val === null || val === undefined) {
+        return '""'; // TOML has no null — emit empty string
+    }
+    if (typeof val === "boolean") {
+        return val ? "true" : "false";
+    }
+    if (typeof val === "number") {
+        if (Number.isInteger(val))
+            return String(val);
+        return String(val);
+    }
+    if (typeof val === "string") {
+        return emitString(val);
+    }
+    if (val instanceof Date) {
+        return val.toISOString();
+    }
+    if (Array.isArray(val)) {
+        if (val.length === 0)
+            return "[]";
+        // Array of scalars → inline array
+        const items = val.map((item) => emitValue(item));
+        const inline = `[${items.join(", ")}]`;
+        if (inline.length <= 80)
+            return inline;
+        // Multi-line array for long content
+        const multiLines = val.map((item) => `  ${emitValue(item)},`);
+        return "[\n" + multiLines.join("\n") + "\n]";
+    }
+    // Inline table for non-table contexts (shouldn't normally reach here
+    // because isTableValue is checked first, but handles edge cases)
+    if (typeof val === "object") {
+        const entries = Object.entries(val);
+        if (entries.length === 0)
+            return "{}";
+        const pairs = entries.map(([k, v]) => `${escapeKey(k)} = ${emitValue(v)}`);
+        return `{ ${pairs.join(", ")} }`;
+    }
+    return String(val);
+}
+/**
+ * Emit a TOML string with proper quoting.
+ */
+function emitString(val) {
+    // Use basic strings with escaping for most values
+    if (val.includes("\n") || val.includes("\r")) {
+        // Multi-line basic string
+        const escaped = val
+            .replace(/\\/g, "\\\\")
+            .replace(/"""/g, '\\"""');
+        return `"""\n${escaped}"""`;
+    }
+    // Regular basic string
+    const escaped = val
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\t/g, "\\t")
+        .replace(/\r/g, "\\r");
+    return `"${escaped}"`;
+}