@intentius/chant 0.124.12 → 0.124.14

package/dist/op/activities/forge-pull-request.js

@@ -0,0 +1,82 @@
+/**
+ * Where chant's own pull-request paths open their pull request (#3798).
+ *
+ * `reconcilePr`'s `pull-request` mode, `lexiconUpgrade`, rollback and
+ * `proposeWorkspaceUpgrade` open a pull request with `gh pr`. `gh pr create`,
+ * `view`, `edit` and `list` speak GitHub's GraphQL API, which Forgejo does not
+ * serve, so #3780's `GH_HOST` sends them to the right Forgejo instance only
+ * for them to fail there. GitLab has no `gh` at all. On those two forges each
+ * path opens, finds and edits its pull request over REST through
+ * `../../pr-forge.ts` instead. GitHub, and a run outside any CI job, keep
+ * `gh` and the operator's own `gh auth login`.
+ *
+ * The forge and its token come from the CI job's environment
+ * ({@link forgeTargetFromEnv}). The repository is the one the checkout's
+ * remote names, when that remote is on the job's forge, so a path working in
+ * another checkout than the job's own still opens its pull request there.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { detectForge, forgeClient, forgeTargetFromEnv } from "../../pr-forge.js";
+import { remoteHost } from "./gh-host.js";
+const execFileAsync = promisify(execFile);
+/** The repository path a git remote URL names: `owner/name`, or `group/sub/name` on GitLab. */
+export function remoteRepoPath(url) {
+    const u = url?.trim();
+    if (!u)
+        return undefined;
+    const scp = /^[^@/\s]+@[^:/\s]+:(?!\/)(.+)$/.exec(u);
+    let path;
+    if (scp)
+        path = scp[1];
+    else {
+        try {
+            path = new URL(u).pathname;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const out = path.replace(/^\/+/, "").replace(/\/+$/, "").replace(/\.git$/, "");
+    return out.includes("/") ? out : undefined;
+}
+const gitRemoteUrl = async (cwd, remote) => {
+    try {
+        return (await execFileAsync("git", ["remote", "get-url", remote], { cwd })).stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The REST client a pull request is opened through, or undefined when `gh`
+ * serves: on GitHub, and outside a CI job. A Forgejo or GitLab job that lacks
+ * a token or a repository throws `ForgeEnvironmentError` naming it, where
+ * `gh pr` would have failed on GraphQL.
+ */
+export async function restPullRequestForge(env = process.env, opts = {}) {
+    const kind = detectForge(env);
+    if (kind !== "forgejo" && kind !== "gitlab")
+        return undefined;
+    const target = forgeTargetFromEnv(env, { kind });
+    if (opts.cwd) {
+        const url = await (opts.remoteUrl ?? gitRemoteUrl)(opts.cwd, opts.remote ?? "origin");
+        const path = remoteRepoPath(url);
+        if (path && remoteHost(url) === target.host)
+            target.repo = path;
+    }
+    return forgeClient(target, opts.fetch);
+}
+/**
+ * Open a pull request for `spec.head`, or bring the open one's title and
+ * body in line with `spec`. An open one already current is left alone.
+ */
+export async function upsertPullRequest(forge, spec) {
+    const open = await forge.findPullRequest(spec.head);
+    if (!open)
+        return { action: "opened", pr: await forge.openPullRequest(spec) };
+    if (open.title === spec.title && open.body.trim() === spec.body.trim())
+        return { action: "unchanged", pr: open };
+    const edited = await forge.editPullRequest(open.number, { title: spec.title, body: spec.body });
+    return { action: "updated", pr: edited ?? { ...open, title: spec.title, body: spec.body } };
+}

package/dist/op/activities/gh-host.js

@@ -0,0 +1,78 @@
+/**
+ * The host a `gh` call that names none should go to (#3780).
+ *
+ * `gh pr create`, `gh pr view`, `gh label create` and `gh issue create` take
+ * neither a URL nor a host. Outside a checkout they go to github.com; inside
+ * one, `gh` matches the git remotes against the hosts it knows, which in a CI
+ * job is github.com alone, so a GitHub Enterprise Server or Forgejo remote is
+ * not taken for a GitHub host at all. `GH_HOST` names the host for those calls,
+ * and `gh` then reads `GH_ENTERPRISE_TOKEN` for it rather than `GH_TOKEN`
+ * (#2333), so the job's token is copied across when the job set only that.
+ *
+ * The host is the job's forge when the run is a GitHub Actions or Forgejo
+ * Actions job (`GITHUB_SERVER_URL`, `FORGEJO_SERVER_URL` first), else the
+ * `origin` remote's. github.com, or a host nothing names, leaves the
+ * environment as it was, so github.com runs are unchanged. A `GH_HOST` already
+ * set is the caller's choice and is kept.
+ *
+ * `gh pr` speaks GraphQL, which Forgejo does not serve, so on Forgejo this
+ * makes those calls reach the right instance and fail there by name rather
+ * than on github.com.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/** The host of a git remote URL: `https://host/o/r`, `ssh://git@host:22/o/r`, or `git@host:o/r`. */
+export function remoteHost(url) {
+    const u = url?.trim();
+    if (!u)
+        return undefined;
+    const scp = /^[^@/\s]+@([^:/\s]+):(?!\/)/.exec(u);
+    if (scp)
+        return scp[1].toLowerCase();
+    try {
+        const parsed = new URL(u);
+        // An ssh port is not part of the host gh knows; an http(s) one is.
+        return (parsed.protocol === "ssh:" ? parsed.hostname : parsed.host).toLowerCase() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The forge host a CI job names, or undefined outside a GitHub Actions or Forgejo Actions job. */
+function jobHost(env) {
+    return remoteHost(env.FORGEJO_SERVER_URL) ?? remoteHost(env.GITHUB_SERVER_URL);
+}
+/**
+ * `env` with `GH_HOST` set to `host` when it is not github.com, and
+ * `GH_ENTERPRISE_TOKEN` set from `GH_TOKEN` or `GITHUB_TOKEN` when neither
+ * enterprise variable is. Pure, for tests and for callers that know the host.
+ */
+export function ghEnvForHost(env, host) {
+    if (env.GH_HOST?.trim() || !host || host === "github.com")
+        return env;
+    const out = { ...env, GH_HOST: host };
+    const token = env.GH_TOKEN?.trim() || env.GITHUB_TOKEN?.trim();
+    if (token && !env.GH_ENTERPRISE_TOKEN?.trim() && !env.GITHUB_ENTERPRISE_TOKEN?.trim())
+        out.GH_ENTERPRISE_TOKEN = token;
+    return out;
+}
+/**
+ * The environment to run a host-less `gh` call with: {@link ghEnvForHost}
+ * for the job's forge, or for `origin`'s host in `cwd` outside a CI job.
+ */
+export async function ghHostEnv(env = process.env, cwd) {
+    if (env.GH_HOST?.trim())
+        return env;
+    let host = jobHost(env);
+    if (!host) {
+        try {
+            const { stdout } = await execFileAsync("git", ["remote", "get-url", "origin"], cwd ? { cwd } : {});
+            host = remoteHost(stdout);
+        }
+        catch {
+            host = undefined;
+        }
+    }
+    return ghEnvForHost(env, host);
+}

package/dist/op/activities/guard-validate.js

@@ -0,0 +1,165 @@
+/**
+ * guardValidate — chant #522: reuse an existing CloudFormation Guard rules
+ * pack as a first-class Op step, instead of reimplementing compliance packs
+ * as native `WAW` rules.
+ *
+ * chant already emits standard CloudFormation `template.json` (no
+ * chant-specific translation), so an org's existing `.guard` files run
+ * against it unchanged: this activity is a thin shell around
+ * `cfn-guard validate -r <rules> -d <template> --output-format json`, run
+ * through the runtime adapter's `spawn` (never `node:child_process`
+ * directly — see `lexicons/aws/src/plugin.ts`'s `exportResources` for the
+ * same seam, and `../../import/live-export-io.test.ts` for how a test mocks
+ * it). `cfn-guard` is an operational dependency, not a `chant build`
+ * dependency — nothing here runs inside the pure core.
+ *
+ * Mirrors `./policy.ts`'s `policyGate`: `report` is the only finding-mode
+ * today (the type only admits that one value; `issue`/`pull-request` modes
+ * are a follow-up, chant #522), and an error-severity finding throws
+ * (a non-retryable activity failure) so the run exits non-zero — the same gate
+ * CI relies on to fail the pipeline — and the same activity blocks an `ApplyOp`
+ * when placed before it.
+ */
+import { resolve } from "node:path";
+import { nonRetryableFailure } from "../activity-failure.js";
+/**
+ * Recursively collect message-shaped string values anywhere inside a parsed
+ * cfn-guard `not_compliant` entry. cfn-guard's exact JSON nesting for a
+ * violation's human message has shifted across versions (Unary/Clause/Check
+ * wrappers, `messages.custom_message` vs `messages.error`, …); rather than
+ * betting on one fixed path that a version bump silently breaks, this walks
+ * the whole entry and takes every message-shaped string it finds — the same
+ * "degrade, don't false-negative" instinct `defaultGitlabRefResolver`
+ * (`./pipeline-audit.ts`) uses for a resolver failure.
+ */
+function collectMessages(value, out = [], seen = new Set()) {
+    if (typeof value !== "object" || value === null)
+        return out;
+    if (Array.isArray(value)) {
+        for (const v of value)
+            collectMessages(v, out, seen);
+        return out;
+    }
+    for (const [key, v] of Object.entries(value)) {
+        if (typeof v === "string" && /^(message|custom_message|error)$/i.test(key) && v.trim() && !seen.has(v)) {
+            seen.add(v);
+            out.push(v);
+        }
+        else {
+            collectMessages(v, out, seen);
+        }
+    }
+    return out;
+}
+/** Collect every string value found under a `*path*`-shaped key, anywhere in the entry. */
+function collectPaths(value, out = []) {
+    if (typeof value !== "object" || value === null)
+        return out;
+    if (Array.isArray(value)) {
+        for (const v of value)
+            collectPaths(v, out);
+        return out;
+    }
+    for (const [key, v] of Object.entries(value)) {
+        if (typeof v === "string" && /path/i.test(key))
+            out.push(v);
+        else
+            collectPaths(v, out);
+    }
+    return out;
+}
+/**
+ * Best-effort CloudFormation logical id for a violation: cfn-guard reports
+ * the offending property as a template path such as
+ * `/Resources/MyBucket/Properties/...`. Pull the segment right after
+ * `Resources` from the first path-shaped string found, if any.
+ */
+function findEntity(value) {
+    for (const p of collectPaths(value)) {
+        const m = /Resources[./]([A-Za-z0-9]+)/.exec(p);
+        if (m)
+            return m[1];
+    }
+    return undefined;
+}
+/**
+ * Map cfn-guard's `--output-format json` report to chant-shaped findings.
+ * Exported and tested directly (independent of `spawn`) — same split
+ * `collectPipelineRefs`/`pipelineSupplyChainAudit` (`./pipeline-audit.ts`)
+ * use between pure mapping and the orchestrating activity.
+ *
+ * Throws if `stdout` is not parseable JSON — a cfn-guard invocation that
+ * didn't run with `--output-format json` (a bad rules path, a version too
+ * old to support it) is a setup problem, not "zero violations"; reporting
+ * a clean run here would be a false negative.
+ */
+export function parseGuardFindings(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch (err) {
+        throw new Error(`cfn-guard did not return parseable JSON (guardValidate always passes --output-format json) — ` +
+            `${err instanceof Error ? err.message : String(err)}\nraw output:\n${stdout}`);
+    }
+    const fileReports = Array.isArray(parsed) ? parsed : [parsed];
+    const findings = [];
+    for (const report of fileReports) {
+        const notCompliant = report?.not_compliant ?? [];
+        for (const entry of notCompliant) {
+            const rule = entry?.Rule?.name ??
+                entry?.name ??
+                "unknown-rule";
+            const messages = collectMessages(entry);
+            const message = messages.length > 0 ? `cfn-guard rule "${rule}" violated: ${messages.join("; ")}` : `cfn-guard rule "${rule}" violated`;
+            const entity = findEntity(entry);
+            findings.push({ rule, severity: "error", message, ...(entity ? { entity } : {}) });
+        }
+    }
+    return findings;
+}
+function renderSummary(findings, template, rules) {
+    if (findings.length === 0)
+        return `## cfn-guard\n\n${template} is compliant with ${rules}.\n`;
+    let out = `## cfn-guard\n\n${findings.length} violation(s) in ${template} against ${rules}:\n\n`;
+    out += "| Rule | Entity | Message |\n|---|---|---|\n";
+    for (const f of findings)
+        out += `| ${f.rule} | ${f.entity ?? ""} | ${f.message} |\n`;
+    return out;
+}
+/**
+ * Run an external CloudFormation Guard rules pack against the project's
+ * built CloudFormation template. `report` mode: prints a summary, and
+ * throws (non-retryable) when any rule is violated, so the local executor
+ * (`chant run`) exits non-zero and CI fails the pipeline — the same shape
+ * `policyGate` uses to block an apply. A clean run passes through.
+ *
+ * A plain activity on every runtime, not a `gate` step.
+ */
+export async function guardValidate(args, _signal) {
+    const mode = args.onFinding ?? "report";
+    if (mode !== "report") {
+        throw new Error(`guardValidate: onFinding "${mode}" is not implemented — only "report" runs today ` +
+            `(chant #522 leaves issue/pull-request modes to a follow-up).`);
+    }
+    const projectPath = args.path ?? ".";
+    const template = args.template ?? resolve(projectPath, "template.json");
+    const binary = args.binary ?? "cfn-guard";
+    const { getRuntime } = await import("../../runtime-adapter.js");
+    const rt = getRuntime();
+    const result = await rt.spawn([binary, "validate", "-r", args.rules, "-d", template, "--output-format", "json"]);
+    if (result.stdout.trim() === "" && result.stderr.trim() !== "") {
+        throw new Error(`cfn-guard ("${binary}") produced no output — ${result.stderr.trim()}\n` +
+            `Install cfn-guard (https://github.com/aws-cloudformation/cloudformation-guard) or pass { binary } ` +
+            `to point at an existing install.`);
+    }
+    const findings = parseGuardFindings(result.stdout);
+    const summary = renderSummary(findings, template, args.rules);
+    if (findings.length > 0) {
+        console.log(summary);
+        const detail = findings.map((f) => `[${f.rule}]${f.entity ? ` ${f.entity}:` : ""} ${f.message}`).join("; ");
+        throw nonRetryableFailure(`cfn-guard blocked the build — ${findings.length} violation(s) against ${args.rules}: ${detail}`, "GuardViolation");
+    }
+    console.log(`[guard] ${template} is compliant with ${args.rules}`);
+    return { findings, summary };
+}

package/dist/op/activities/http-check.js

@@ -0,0 +1,40 @@
+import { sleep } from "../activity-runtime.js";
+/** Whether a status satisfies the expectation (exact if given, else any 2xx). Pure. */
+export function statusOk(status, expected) {
+    return expected === undefined ? status >= 200 && status < 300 : status === expected;
+}
+/**
+ * Assert an HTTP endpoint responds as expected — a typed verify step, the modeled
+ * replacement for `shell("curl -fs ...")`. Fails (throwing) if the status or body
+ * doesn't match after the allowed retries. `fetchFn` is injectable for tests.
+ * Uses fastIdempotent profile — 5m timeout.
+ */
+export async function httpCheck(args, signal, fetchFn = fetch) {
+    const retries = args.retries ?? 0;
+    const intervalMs = args.intervalMs ?? 1000;
+    let lastErr = "";
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        if (signal?.aborted)
+            throw new Error("httpCheck aborted");
+        try {
+            const res = await fetchFn(args.url, { method: args.method ?? "GET", signal });
+            const body = args.contains !== undefined ? await res.text() : "";
+            if (!statusOk(res.status, args.status)) {
+                lastErr = `status ${res.status} (want ${args.status ?? "2xx"})`;
+            }
+            else if (args.contains !== undefined && !body.includes(args.contains)) {
+                lastErr = `body missing "${args.contains}"`;
+            }
+            else {
+                console.log(`httpCheck OK: ${args.url} (${res.status})`);
+                return { status: res.status };
+            }
+        }
+        catch (e) {
+            lastErr = e instanceof Error ? e.message : String(e);
+        }
+        if (attempt < retries)
+            await sleep(intervalMs, signal);
+    }
+    throw new Error(`httpCheck failed for ${args.url}: ${lastErr}`);
+}

package/dist/op/activities/index.js

@@ -0,0 +1,59 @@
+export { chantBuild } from "./build.js";
+// kubectl activity relocated to the k8s lexicon (#809) — loadActivities(["k8s"])
+// provides kubectlApply. The kubectlApply step builder stays in core.
+// helm activity relocated to the helm lexicon (#809) — loadActivities(["helm"])
+// provides helmInstall. The helmInstall step builder stays in core.
+export { waitForStack } from "./wait.js";
+// gitlab activity relocated to the gitlab lexicon (#809) — loadActivities(["gitlab"])
+// provides gitlabPipeline. The gitlabPipeline step builder stays in core.
+export { shellCmd } from "./shell.js";
+export { httpCheck, statusOk } from "./http-check.js";
+export { sourceArchive, releasePlan, releaseRecord } from "./source-release.js";
+export { releaseRollbackPlan, releaseRollbackRecord } from "./source-rollback.js";
+export { lifecycleSnapshot, lifecycleDiff } from "./lifecycle.js";
+export { composeChangeSet, lifecyclePlanChangeSet, readChangeSetPart } from "./change-set.js";
+export { chantTeardown } from "./teardown.js";
+export { envTeardown } from "./env-teardown.js";
+// k3d activities relocated to the k8s lexicon (#809), then to their own k3d
+// lexicon (#1410) — loadActivities(["k3d"]) provides k3dUp/k3dDown. The step
+// builders stay in core.
+// Sprites (Fly product) moved to the fly lexicon — a lexicon owns its own
+// product's activities. `loadActivities(["fly"])` now provides the sprite
+// activities + the spritzer emulator lifecycle. See lexicons/fly/src/op/activities.
+//
+// Cloud/k8s-specific activities likewise live in their own lexicons (aws → floci,
+// gcp → gcpApply, azure → az group, k8s → kubectl/k3d/argo) and are loaded from
+// there by the activity registry per the project's configured lexicons. What is
+// here is the product-agnostic base every runtime needs, core's own since #2114:
+// the registry imports this module statically, so a project that installs
+// nothing but chant still resolves every step below.
+export { reconcilePr, commentMarker, pullRequestContextFrom, resolvePullRequestContext, mergeRequestContextFrom, gitlabNoteTokenFrom, } from "./reconcile.js";
+export { nativeApply, compensateApply, hasNativeRollback } from "./apply.js";
+// argo activity (waitForArgoSync) relocated to the k8s lexicon (#809) —
+// loadActivities(["k8s"]) provides it. Argo CD is Kubernetes-native.
+export { policyGate } from "./policy.js";
+export { guardValidate, parseGuardFindings } from "./guard-validate.js";
+export { workEvidence } from "./work-evidence.js";
+export { workflowSupplyChainAudit, collectAuditRefs, defaultActionRefResolver } from "./workflow-audit.js";
+export { pipelineSupplyChainAudit, collectPipelineRefs, defaultGitlabRefResolver } from "./pipeline-audit.js";
+export { convergeTick, planConvergeTick } from "./converge.js";
+export { lexiconUpgrade, isPinned, isRolling, severityToLabel, upgradeBranchName, upgradePrTitle, buildUpgradeSummary, } from "./lexicon-upgrade.js";
+// The behaviour prediction and the pull-request finding built on it (#2358).
+// Only the two activities and the pure helpers are re-exported: the registry
+// collects every exported function as an activity, so `createBehaviourFinding`
+// and `checkoutBase` stay on the module.
+export { predictBehaviour, behaviourFinding, behaviourFindingMarker, declaredEdgeCoverage, baseRefFrom, headRefFrom, noBaseRefMessage, noContributedRowsMessage, } from "./predict-behaviour.js";
+// The propose-only template upgrade (#2550). Loads the workspace code on first
+// call only, so importing this module loads nothing under `workspace/`.
+export { proposeWorkspaceUpgrade } from "./propose-upgrade.js";
+// The forward coverage check over an Op's own diff (#2773). Loads the
+// workspace code on first call only, like proposeWorkspaceUpgrade.
+export { changeCoverage } from "./change-coverage.js";
+// Ask a decision point and record the answer (ws-058, #2740). Core's since
+// #2828, next to the decision points: the systemone lexicon that held it is
+// gone. Only the activity is re-exported, since the registry collects every
+// exported function; `runDecide` and its seams stay on the module, which
+// loads the workspace code on first call.
+export { decide } from "./decide.js";
+// The factory reference Op's rules and hooks (#3406, ws-087): `factoryOp` in ../factory.ts declares them.
+export { factoryPick, factoryReady, factoryAsk, factoryBuild, factoryCheck, factoryRecord } from "./factory.js";