@intentius/chant 0.124.13 → 0.124.15

package/dist/cli/handlers/build.js

@@ -0,0 +1,267 @@
+import { writeFileSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { buildCommand, buildCommandWatch, printErrors, printWarnings, resolveBuildFormat } from "../commands/build.js";
+import { formatError, formatInfo, formatSuccess, formatBold } from "../format.js";
+import { generateComponentsPipeline } from "../../components/cli-support.js";
+import { loadChantConfigUpward } from "../../config.js";
+import { resolveCliBuildParams, parseParamFlags } from "../build-params-cli.js";
+import { findWorkspaceRoot } from "../../project-root.js";
+/**
+ * `chant build --components --generate <lexicon>` — generate mode (#563,
+ * epic #551 Phase 3). Discovers `Component` declarations under `args.path`
+ * and synthesizes a thin CI pipeline for `lexicon` instead of running a
+ * normal lexicon build: no entity discovery, no serializers, no post-synth
+ * checks — those apply to lexicon resources, which is a different input to
+ * a different command path (`chant build` without `--components`).
+ *
+ * chant #1108 — resolves this invocation's declared build-time parameters
+ * (`chant.config.ts`'s `buildParams`, against `--param`/`--params-file`/a
+ * declared `env` mapping) the exact same way `chant build` does
+ * (`resolveCliBuildParams`, shared with `buildCommand`), BEFORE
+ * `generateComponentsPipeline` discovers/imports any `*.component.ts` file.
+ * Before this, `params.*` (`@intentius/chant/params`) was always `{}` under
+ * this command too — generate mode shares `discoverComponents` with `chant
+ * run --components`, so it had the identical gap.
+ *
+ * chant #1117 — loads config by walking up from `args.path` to the project
+ * root (`loadChantConfigUpward`), same as `chant build` proper, instead of
+ * `args.path` alone: a components-only project built from a subdirectory
+ * otherwise never sees the root `chant.config.ts`'s `buildParams` either.
+ */
+async function runGenerateComponents(ctx) {
+    const { args } = ctx;
+    const lexicon = args.generate;
+    const { config } = await loadChantConfigUpward(resolve(args.path)).catch(() => ({ config: {} }));
+    const paramsResolution = resolveCliBuildParams(config.buildParams, {
+        cli: parseParamFlags(args.param),
+        paramsFile: args.paramsFile,
+        verbose: args.verbose,
+    });
+    if (!paramsResolution.success) {
+        for (const message of paramsResolution.errors)
+            console.error(message);
+        return 1;
+    }
+    // A project inside a workspace member gets that member's pipeline (#2542):
+    // path-filtered, run in the member's directory, written to a file named
+    // after the member and recorded as the member's generated file. The
+    // workspace module loads only when a declaration was found, so a project
+    // outside any workspace generates exactly what it did before.
+    const found = findWorkspaceRoot(resolve(args.path));
+    let plan;
+    let memberPipeline;
+    if (found) {
+        memberPipeline = await import("../../workspace/member-pipeline.js");
+        try {
+            plan = memberPipeline.planMemberComponentPipeline({
+                projectDir: resolve(args.path),
+                found,
+                lexicon,
+                env: args.env,
+                promoteTo: args.promoteTo,
+                output: args.output,
+                params: args.param,
+                paramsFile: args.paramsFile,
+                ...(args.waveGate ? { waveGate: { gate: args.waveGate, ...(args.canary?.length ? { canary: args.canary } : {}), ...(args.base ? { base: args.base } : {}) } } : {}),
+                ...(args.prLoop ? { prLoop: { ...(args.gate ? { gate: args.gate } : {}), ...(args.branch ? { branch: args.branch } : {}) } } : {}),
+            });
+        }
+        catch (err) {
+            console.error(formatError({ message: memberPipeline.describeError(err) }));
+            return 1;
+        }
+    }
+    // Which lexicons support generate mode is a property of the loaded lexicon
+    // plugins (those implementing `generateComponentPipeline`, #688), not a
+    // hard-coded core list — `generateComponentsPipeline` returns a descriptive
+    // error when the target lexicon has no generator.
+    const result = await generateComponentsPipeline(args.path, lexicon, {
+        env: args.env,
+        ...(args.promoteTo ? { promoteTo: args.promoteTo } : {}),
+        ...(plan ? { member: plan.member } : {}),
+        // #3049: one job per wave of a gated-wave fan-out instead of one per component.
+        ...(args.waveGate
+            ? { gatedWaves: { gate: args.waveGate, ...(args.canary?.length ? { canary: args.canary } : {}), ...(args.base ? { base: args.base } : {}) } }
+            : {}),
+        // #3183: a plan job per pull request and an apply job per merge.
+        ...(args.prLoop
+            ? { prLoop: { ...(args.gate ? { gate: args.gate } : {}), ...(args.branch ? { branch: args.branch } : {}) } }
+            : {}),
+    }, args.sandbox, paramsResolution.provenance);
+    if (!result.success) {
+        console.error(formatError({ message: result.error ?? "Failed to generate CI pipeline from components" }));
+        return 1;
+    }
+    const yaml = result.yaml ?? "";
+    if (args.format === "json") {
+        console.log(JSON.stringify({
+            stages: result.stages,
+            jobs: result.jobs,
+            yaml,
+            // The environment the generated pipeline deploys (#2046), the
+            // generator's own resolution, forwarded rather than left for a
+            // consumer to re-derive by parsing the YAML back (#2060).
+            ...(result.env ? { env: result.env } : {}),
+            // A workspace member's pipeline (#2542): the member and the file
+            // the pipeline belongs in, relative to the repository root.
+            ...(plan ? { member: plan.member.name, file: plan.file } : {}),
+        }, null, 2));
+    }
+    else if (plan && memberPipeline) {
+        memberPipeline.writeMemberComponentPipeline(plan, yaml);
+        console.error(formatSuccess(`wrote ${formatBold(plan.file)} for member ${formatBold(plan.member.name)}`));
+    }
+    else if (args.output) {
+        const outputPath = resolve(args.output);
+        mkdirSync(dirname(outputPath), { recursive: true });
+        writeFileSync(outputPath, yaml);
+    }
+    else {
+        console.log(yaml);
+    }
+    if (args.verbose || args.output) {
+        console.error(formatSuccess(`Generated ${formatBold(lexicon)} pipeline: ${formatBold(String(result.jobs?.length ?? 0))} job(s) across ${formatBold(String(result.stages?.length ?? 0))} wave(s)`));
+    }
+    return 0;
+}
+export async function runBuild(ctx) {
+    const { args, plugins } = ctx;
+    let { serializers } = ctx;
+    // Generate mode (#563): synthesize CI YAML from components instead of
+    // running a normal lexicon build. Checked first since it does not need
+    // `serializers`/lexicon resources at all.
+    if (args.components && args.generate) {
+        return runGenerateComponents(ctx);
+    }
+    // Filter to a single lexicon when --lexicon is specified
+    if (args.lexicon) {
+        serializers = serializers.filter((s) => s.name === args.lexicon);
+        if (serializers.length === 0) {
+            console.error(formatError({ message: `No serializer found for lexicon "${args.lexicon}". Available: ${ctx.serializers.map((s) => s.name).join(", ")}` }));
+            return 1;
+        }
+    }
+    if (args.format && args.format !== "json" && args.format !== "yaml") {
+        console.error(formatError({ message: `Invalid format for build: ${args.format}. Expected 'json' or 'yaml'.` }));
+        return 1;
+    }
+    // Infer format from the -o extension when --format is not given; an explicit
+    // --format wins but a mismatch warns (#284 bug 1).
+    const { format: buildFormat, warning: formatWarningMsg } = resolveBuildFormat(args.format, args.output);
+    if (formatWarningMsg) {
+        console.error(formatInfo(formatWarningMsg));
+    }
+    // #1064 — `--param name=value`, repeated, into a flat { name: value } record.
+    const params = parseParamFlags(args.param);
+    // `--lexicon-output <lexicon>=<path>`: each named lexicon builds into its own
+    // file. One build per file, over the same project, so every write, check and
+    // diagnostic path is the one a single-lexicon `--lexicon` build already takes.
+    if (args.lexiconOutput?.length) {
+        if (args.watch || args.lexicon) {
+            console.error(formatError({ message: "--lexicon-output cannot be combined with --watch or --lexicon" }));
+            return 1;
+        }
+        const targets = new Map();
+        for (const spec of args.lexiconOutput) {
+            const eq = (spec ?? "").indexOf("=");
+            if (eq <= 0 || eq === spec.length - 1) {
+                console.error(formatError({ message: `Invalid --lexicon-output "${spec}". Expected <lexicon>=<path>.` }));
+                return 1;
+            }
+            const name = spec.slice(0, eq);
+            if (targets.has(name)) {
+                console.error(formatError({ message: `--lexicon-output names lexicon "${name}" twice.` }));
+                return 1;
+            }
+            if (!serializers.some((s) => s.name === name)) {
+                console.error(formatError({ message: `No serializer found for lexicon "${name}". Available: ${serializers.map((s) => s.name).join(", ")}. List the lexicon in chant.config.ts.` }));
+                return 1;
+            }
+            targets.set(name, spec.slice(eq + 1));
+        }
+        const groups = [...targets].map(([name, output]) => ({
+            serializers: serializers.filter((s) => s.name === name),
+            output,
+        }));
+        const rest = serializers.filter((s) => !targets.has(s.name));
+        if (args.output && rest.length > 0)
+            groups.push({ serializers: rest, output: args.output });
+        const seenWarnings = new Set();
+        let failed = false;
+        // One build for every file: each group takes its own lexicons' outputs.
+        const sharedBuild = { serializers };
+        for (const group of groups) {
+            const { format, warning } = resolveBuildFormat(args.format, group.output);
+            if (warning)
+                console.error(formatInfo(warning));
+            const result = await buildCommand({
+                path: args.path,
+                output: group.output,
+                format,
+                serializers: group.serializers,
+                sharedBuild,
+                plugins,
+                verbose: args.verbose,
+                env: args.env,
+                fold: args.fold,
+                sandbox: args.sandbox,
+                foldRank: args.foldRank,
+                foldRankCollapsedFile: args.foldRankCollapsedFile,
+                params: parseParamFlags(args.param),
+                paramsFile: args.paramsFile,
+            });
+            // The lexicons built by another group are not missing serializers.
+            const own = result.warnings.filter((w) => !w.includes("No serializer found for lexicon") && !seenWarnings.has(w));
+            for (const w of own)
+                seenWarnings.add(w);
+            printWarnings(own);
+            printErrors(result.errors);
+            if (!result.success)
+                failed = true;
+        }
+        return failed ? 1 : 0;
+    }
+    if (args.watch) {
+        const cleanup = buildCommandWatch({
+            path: args.path,
+            output: args.output,
+            format: buildFormat,
+            serializers,
+            plugins,
+            fold: args.fold,
+            sandbox: args.sandbox,
+            verbose: args.verbose,
+            params,
+            paramsFile: args.paramsFile,
+        });
+        process.on("SIGINT", () => {
+            cleanup();
+            console.error(formatInfo("\nWatch mode stopped."));
+            process.exit(0);
+        });
+        await new Promise(() => { });
+    }
+    const result = await buildCommand({
+        path: args.path,
+        output: args.output,
+        format: buildFormat,
+        serializers,
+        plugins,
+        verbose: args.verbose,
+        env: args.env,
+        fold: args.fold,
+        sandbox: args.sandbox,
+        foldRank: args.foldRank,
+        foldRankCollapsedFile: args.foldRankCollapsedFile,
+        params,
+        paramsFile: args.paramsFile,
+    });
+    // When --lexicon filters to a subset, suppress "No serializer" warnings for excluded lexicons
+    let warnings = result.warnings;
+    if (args.lexicon) {
+        warnings = warnings.filter((w) => !w.includes('No serializer found for lexicon'));
+    }
+    printWarnings(warnings);
+    printErrors(result.errors);
+    return result.success ? 0 : 1;
+}

package/dist/cli/handlers/carve-apply.js

@@ -0,0 +1,30 @@
+import { carveApply, formatCarveApply } from "../commands/carve-apply.js";
+import { formatError } from "../format.js";
+/**
+ * `chant carve apply --from <tf-dir> --select <address> --env <env> [--stack <name>] [--write]`
+ *
+ * Resolves the ownership marker + graduation runbook. BYOL-honest: no cloud
+ * calls. `--write` saves the graduation doc. No lexicon plugins needed.
+ */
+export async function runCarveApply(ctx) {
+    const { args } = ctx;
+    const result = await carveApply({
+        from: args.migrateFrom, // `--from <terraform-dir>`
+        select: args.selectAddress, // `--select <tf-address>`
+        env: args.env,
+        stack: args.carveStack,
+        statePath: args.statePath,
+        output: args.output,
+        write: args.write,
+        writeSource: args.writeSource,
+    });
+    if (!result.ok) {
+        console.error(formatError({
+            message: result.error ?? "carve apply failed",
+            hint: "chant carve apply --from ./tf --select aws_s3_bucket.assets --env prod",
+        }));
+        return 1;
+    }
+    console.log(formatCarveApply(result));
+    return 0;
+}

package/dist/cli/handlers/carve-bridge.js

@@ -0,0 +1,28 @@
+import { carveBridge, formatCarveBridge } from "../commands/carve-bridge.js";
+import { formatError } from "../format.js";
+/**
+ * `chant carve bridge --from <tf-dir> --select <address> [--output <dir>] [--apply-rewrites]`
+ *
+ * Read-only by default: writes proposed survivor patches + a runbook to an
+ * output dir. `--apply-rewrites` edits the surviving `.tf` in place. Loads no
+ * lexicon plugins — pure Terraform-side analysis.
+ */
+export async function runCarveBridge(ctx) {
+    const { args } = ctx;
+    const result = await carveBridge({
+        from: args.migrateFrom, // `--from <terraform-dir>`
+        select: args.selectAddress, // `--select <tf-address>`
+        statePath: args.statePath,
+        output: args.output,
+        applyRewrites: args.applyRewrites,
+    });
+    if (!result.ok) {
+        console.error(formatError({
+            message: result.error ?? "carve bridge failed",
+            hint: "chant carve bridge --from ./tf --select aws_s3_bucket.assets",
+        }));
+        return 1;
+    }
+    console.log(formatCarveBridge(result));
+    return 0;
+}

package/dist/cli/handlers/carve-emit.js

@@ -0,0 +1,50 @@
+import { carveEmit, formatCarveEmit } from "../commands/carve-emit.js";
+import { liveImportFromPlugins } from "../commands/import.js";
+import { carveEmitLexicons, resolveEmitProvider } from "../../terraform/carve-provider.js";
+import { loadPlugins } from "../plugins.js";
+import { formatError } from "../format.js";
+/**
+ * `chant carve emit --from <tf-dir> --select <address> (--state <tfstate> | --env <env>)`
+ *
+ * Adopts the selected Terraform resource into typed chant source. `--state`
+ * adopts offline from the tfstate (no plugins); `--env` adopts via the live
+ * cloud import path, for which the target lexicon is loaded lazily here — so a
+ * state-only carve never pays the plugin-load cost.
+ */
+export async function runCarveEmit(ctx) {
+    const { args } = ctx;
+    // Load plugins only for the live path; the offline --state path needs none.
+    // Which lexicon comes from the carve provider seam (#2016), resolved off the
+    // selected address's type without parsing the estate — so a second provider
+    // needs no edit here. A type no provider emits falls back to every lexicon
+    // emit can adopt into, and carveEmit refuses the type properly afterwards.
+    let plugins = ctx.plugins;
+    if (!args.statePath && args.env) {
+        const tfType = args.selectAddress?.split(".")[0] ?? "";
+        const lexicon = resolveEmitProvider(tfType)?.lexicon;
+        try {
+            plugins = await loadPlugins(lexicon ? [lexicon] : carveEmitLexicons());
+        }
+        catch {
+            // fall through with whatever ctx provided; carveEmit surfaces a clear error
+        }
+    }
+    const result = await carveEmit({
+        from: args.migrateFrom, // `--from <terraform-dir>`
+        select: args.selectAddress, // `--select <tf-address>`
+        env: args.env,
+        liveName: args.liveName, // `--live-name <cfn-logical-id>`
+        statePath: args.statePath,
+        output: args.output,
+        reportFile: args.reportFile,
+    }, { plugins, liveImport: liveImportFromPlugins });
+    if (!result.ok) {
+        console.error(formatError({
+            message: result.error ?? "carve emit failed",
+            hint: "chant carve emit --from ./tf --select aws_s3_bucket.assets --env prod",
+        }));
+        return 1;
+    }
+    console.log(formatCarveEmit(result));
+    return 0;
+}

package/dist/cli/handlers/carve-status.js

@@ -0,0 +1,26 @@
+import { carveStatus, carveStatusJson, formatCarveStatus } from "../commands/carve-status.js";
+import { formatError } from "../format.js";
+/**
+ * `chant carve status [--from <dir>] [--json]` — the read-only status read
+ * over a tree of carve manifests (#2038). Walks from `--from` (default: cwd),
+ * reports every manifest's target, stage (planned/emitted/bridged/applied)
+ * and path. No plugins, no project, no cloud call.
+ */
+export async function runCarveStatus(ctx) {
+    const { args } = ctx;
+    const result = carveStatus({ from: args.migrateFrom /* `--from <dir>` */ });
+    if (!result.ok) {
+        console.error(formatError({
+            message: result.error ?? "carve status failed",
+            hint: "chant carve status --from ./tf --json",
+        }));
+        return 1;
+    }
+    if (args.json) {
+        console.log(JSON.stringify(carveStatusJson(result), null, 2));
+    }
+    else {
+        console.log(formatCarveStatus(result));
+    }
+    return 0;
+}

package/dist/cli/handlers/carve.js

@@ -0,0 +1,40 @@
+import { carveAdvise, carveJson, formatCarveReport } from "../commands/carve.js";
+import { formatError } from "../format.js";
+/**
+ * `chant carve advise --from <terraform-dir | cdk.out> [--json] [--report <path>]`
+ *
+ * Read-only. Reuses `--from` (shared with migrate/import) for the source dir,
+ * and works out which source it is by looking at the directory (#1056) rather
+ * than adding a second flag. Loads no chant project and no lexicon plugins —
+ * pure analysis of a foreign tree.
+ */
+export async function runCarveAdvise(ctx) {
+    const { args } = ctx;
+    const result = await carveAdvise({
+        from: args.migrateFrom, // `--from <terraform-dir | cdk.out>`
+        statePath: args.statePath, // `--state <tfstate>`
+        reportFile: args.reportFile, // `--report <path>`
+    });
+    if (!result.ok) {
+        console.error(formatError({
+            message: result.error ?? "carve advise failed",
+            hint: "chant carve advise --from ./path/to/terraform   (or ./cdk.out)",
+        }));
+        return 1;
+    }
+    if (args.json) {
+        console.log(JSON.stringify(carveJson(result), null, 2));
+    }
+    else {
+        console.log(formatCarveReport(result));
+    }
+    return 0;
+}
+/** Fallback for `chant carve` with no/unknown subcommand. */
+export async function runCarveUnknown(_ctx) {
+    console.error(formatError({
+        message: "Unknown carve subcommand",
+        hint: "chant carve advise --from <terraform-dir | cdk.out>   (read-only peelability report)",
+    }));
+    return 1;
+}

package/dist/cli/handlers/change-set.js

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs";
+import { CHANGE_SET_CONTRACT, CHANGE_SET_SCHEMA_ID } from "../../change-set.js";
+import { GITHUB_COMMENT_LIMIT, groupChangeSet, renderPlanSummaryMarkdown, renderPlanSummaryText } from "../../plan-summary.js";
+import { formatError } from "../format.js";
+const USAGE = "chant change-set summary <change-set.json> [--format text|json|markdown] [--limit <chars>]";
+/**
+ * `chant change-set summary <file>` (#3188): the grouped plan summary of a
+ * change-set document (`../../change-set.ts`), such as the `document` a
+ * `composeChangeSet` step returns. `--format` picks text (default), json
+ * (the plan-summary schema) or markdown, an MR or PR note of at most
+ * `--limit` characters (default GitHub's comment limit, 65536). Reads one
+ * file; no project, no plugins, no network.
+ */
+export async function runChangeSetSummary(ctx) {
+    const { args } = ctx;
+    const file = args.extraPositional;
+    const format = args.json ? "json" : args.format || "text";
+    const fail = (message) => {
+        console.error(formatError({ message, hint: USAGE }));
+        return 1;
+    };
+    if (!file)
+        return fail("change-set summary needs the change-set document to read");
+    if (format !== "text" && format !== "json" && format !== "markdown")
+        return fail(`--format ${format} is not one of text, json or markdown`);
+    if (args.limit !== undefined && (!Number.isInteger(args.limit) || args.limit < 200))
+        return fail("--limit needs a whole number of characters, at least 200");
+    let doc;
+    try {
+        doc = JSON.parse(readFileSync(file, "utf-8"));
+    }
+    catch (err) {
+        return fail(`cannot read ${file} as JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (doc?.$schema !== CHANGE_SET_SCHEMA_ID || doc.contract !== CHANGE_SET_CONTRACT) {
+        return fail(`${file} is not a change-set document: its $schema is not ${CHANGE_SET_SCHEMA_ID} with contract ${CHANGE_SET_CONTRACT}`);
+    }
+    const summary = groupChangeSet(doc);
+    if (format === "json")
+        console.log(JSON.stringify(summary, null, 2));
+    else if (format === "markdown")
+        process.stdout.write(renderPlanSummaryMarkdown(summary, { limit: args.limit ?? GITHUB_COMMENT_LIMIT }));
+    else
+        process.stdout.write(renderPlanSummaryText(summary));
+    return 0;
+}