@pellux/goodvibes-toolchain 1.11.0

package/dist/lib/package-install-check.js

@@ -0,0 +1,66 @@
+/**
+ * package-install-check — static verification of a package as it would install.
+ *
+ * Inspects the `npm pack --json --dry-run` tarball for required and forbidden
+ * paths and a size cap, and verifies each bin shim exists, is executable, and
+ * carries the expected shebang. Static — the actual install-into-temp smoke is
+ * a separate tool/CI job.
+ */
+import { realExec, realFsReader, consoleLogger } from './effects.js';
+/** Check a packed file list + unpacked size against the tarball policy. Pure. */
+export function evaluateTarballPaths(files, unpackedBytes, config) {
+    const present = new Set(files);
+    const missing = config.requiredTarballPaths.filter((p) => !present.has(p));
+    const forbidden = files.filter((f) => config.forbiddenTarballPrefixes.some((prefix) => f.startsWith(prefix)));
+    const oversize = unpackedBytes > config.maxTarballBytes;
+    return { ok: missing.length === 0 && forbidden.length === 0 && !oversize, missing, forbidden, oversize };
+}
+/** Verify one bin shim: present, executable, and has the expected shebang. */
+export function evaluateBinShim(fs, path, name, shebang) {
+    const issues = [];
+    if (!fs.exists(path)) {
+        return { name, ok: false, issues: [`bin ${name} missing at ${path}`] };
+    }
+    if (!fs.isExecutable(path))
+        issues.push(`bin ${name} is not executable`);
+    const text = fs.readText(path);
+    if (!text.startsWith(shebang))
+        issues.push(`bin ${name} does not start with "${shebang}"`);
+    return { name, ok: issues.length === 0, issues };
+}
+/** Parse `npm pack --json` output into a file list and unpacked size. */
+export function parseNpmPack(output) {
+    const parsed = JSON.parse(output);
+    const first = parsed[0];
+    return {
+        files: (first?.files ?? []).map((f) => f.path),
+        unpackedBytes: first?.unpackedSize ?? first?.size ?? 0,
+    };
+}
+/** Run the full static install check. */
+export function runPackageInstallCheck(options) {
+    const exec = options.exec ?? realExec;
+    const fs = options.fs ?? realFsReader(options.cwd);
+    const logger = options.logger ?? consoleLogger;
+    const issues = [];
+    for (const bin of options.bins ?? []) {
+        const result = evaluateBinShim(fs, bin.path, bin.name, bin.shebang);
+        issues.push(...result.issues);
+    }
+    const pack = exec('npm', ['pack', '--json', '--dry-run'], { cwd: options.cwd });
+    if (pack.status !== 0) {
+        issues.push(`npm pack --dry-run failed: ${pack.stderr.trim().slice(0, 300)}`);
+        return { ok: false, issues };
+    }
+    const { files, unpackedBytes } = parseNpmPack(pack.stdout);
+    const policy = evaluateTarballPaths(files, unpackedBytes, options.config);
+    if (policy.missing.length > 0)
+        issues.push(`missing required tarball path(s): ${policy.missing.join(', ')}`);
+    if (policy.forbidden.length > 0)
+        issues.push(`forbidden tarball path(s): ${policy.forbidden.slice(0, 5).join(', ')}`);
+    if (policy.oversize)
+        issues.push(`tarball exceeds ${options.config.maxTarballBytes} bytes`);
+    const ok = issues.length === 0;
+    logger.info(ok ? `[package-install-check] OK (${files.length} files)` : `[package-install-check] ${issues.length} issue(s)`);
+    return { ok, issues };
+}

package/dist/lib/per-job-green.d.ts

@@ -0,0 +1,54 @@
+/**
+ * per-job-green — the by-reference validation primitive.
+ *
+ * Given a commit SHA, find that commit's push-CI run for a named workflow, wait
+ * for it to complete, and assert EVERY job concluded `success` (per-job green,
+ * never the rollup). Generalizes the agent repo's bespoke poll, which asserted
+ * only the rollup plus one hard-coded job name.
+ *
+ * Transient-error posture: EVERY GitHub API call (runs listing, per-run jobs,
+ * check-suites, check-runs) goes through a bounded retry loop (default 8
+ * attempts with 7s sleeps, configurable) before its status is treated as
+ * final — the API's known flaky mode makes single-shot calls fail a meaningful
+ * fraction of the time. When the runs listing stays unavailable after retries,
+ * the Checks API (`check-suites` / `check-runs` on the commit) is the fallback.
+ * "No run found yet" is never a failure — it waits and polls. Only an exhausted
+ * retry budget on a needed endpoint, a non-green job, or the deadline produces
+ * a failure, and each names its source honestly.
+ */
+import type { HttpGetJson, Logger, Sleep } from './effects.js';
+import type { PerJobGreenConfig } from '../config.js';
+export interface PerJobGreenResult {
+    readonly ok: boolean;
+    /** The resolved Actions run id, when one was found. */
+    readonly runId: number | null;
+    /** Head SHA the resolved run actually built (for the artifact-integrity handoff). */
+    readonly headSha: string | null;
+    /** Names of jobs/checks that did not conclude `success`. */
+    readonly failures: readonly string[];
+    /** Which source produced the verdict. */
+    readonly source: 'actions' | 'check-suites' | 'none';
+    readonly reason: string;
+}
+export interface PerJobGreenDeps {
+    readonly http: HttpGetJson;
+    readonly sleep: Sleep;
+    readonly logger: Logger;
+    /** Milliseconds since epoch; injectable so the deadline is deterministic in tests. */
+    readonly now: () => number;
+    /** GitHub API origin. Defaults to https://api.github.com. */
+    readonly apiBase?: string;
+    /** Bearer token for the API. */
+    readonly token?: string;
+}
+/**
+ * Extract the Actions run id from a check-run's details_url. Actions-created
+ * check runs point at `https://github.com/{owner}/{repo}/actions/runs/{run_id}/job/{job_id}`.
+ */
+export declare function runIdFromDetailsUrl(detailsUrl: string | undefined): number | null;
+/**
+ * Verify `sha`'s push-CI run is per-job green. Polls until the run completes or
+ * the deadline passes. Deterministic under injected `http`/`sleep`/`now`.
+ */
+export declare function verifyPerJobGreen(deps: PerJobGreenDeps, config: PerJobGreenConfig, sha: string): Promise<PerJobGreenResult>;
+//# sourceMappingURL=per-job-green.d.ts.map

package/dist/lib/per-job-green.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"per-job-green.d.ts","sourceRoot":"","sources":["../../src/lib/per-job-green.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAgB,MAAM,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,cAAc,GAAG,MAAM,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sFAAsF;IACtF,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,gCAAgC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAiGD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAIjF;AAgFD;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,iBAAiB,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAyDjI"}

package/dist/lib/per-job-green.js

@@ -0,0 +1,247 @@
+/**
+ * per-job-green — the by-reference validation primitive.
+ *
+ * Given a commit SHA, find that commit's push-CI run for a named workflow, wait
+ * for it to complete, and assert EVERY job concluded `success` (per-job green,
+ * never the rollup). Generalizes the agent repo's bespoke poll, which asserted
+ * only the rollup plus one hard-coded job name.
+ *
+ * Transient-error posture: EVERY GitHub API call (runs listing, per-run jobs,
+ * check-suites, check-runs) goes through a bounded retry loop (default 8
+ * attempts with 7s sleeps, configurable) before its status is treated as
+ * final — the API's known flaky mode makes single-shot calls fail a meaningful
+ * fraction of the time. When the runs listing stays unavailable after retries,
+ * the Checks API (`check-suites` / `check-runs` on the commit) is the fallback.
+ * "No run found yet" is never a failure — it waits and polls. Only an exhausted
+ * retry budget on a needed endpoint, a non-green job, or the deadline produces
+ * a failure, and each names its source honestly.
+ */
+function headers(token) {
+    const base = {
+        Accept: 'application/vnd.github+json',
+        'X-GitHub-Api-Version': '2022-11-28',
+        'User-Agent': 'goodvibes-toolchain-per-job-green',
+    };
+    if (token)
+        base.Authorization = `Bearer ${token}`;
+    return base;
+}
+function asArray(value, key) {
+    if (value && typeof value === 'object') {
+        const field = value[key];
+        if (Array.isArray(field))
+            return field;
+    }
+    return [];
+}
+/** Statuses worth retrying: server errors, rate limiting, and transport failures. */
+function isTransientStatus(status) {
+    return status === 0 || status === 429 || status >= 500;
+}
+/**
+ * GET with the tool's bounded transient-error retry. Every API call in this
+ * module goes through here; a thrown transport error counts as status 0 and is
+ * retried like a 5xx. Returns the last response once a definitive (non-
+ * transient) status arrives or the retry budget is exhausted.
+ */
+async function getWithRetry(deps, config, url, label) {
+    let last = { status: 0, body: null };
+    for (let attempt = 1; attempt <= config.retryAttempts; attempt++) {
+        try {
+            last = await deps.http(url, headers(deps.token));
+        }
+        catch (error) {
+            last = { status: 0, body: error instanceof Error ? error.message : String(error) };
+        }
+        if (!isTransientStatus(last.status))
+            return last;
+        if (attempt < config.retryAttempts) {
+            deps.logger.warn(`[per-job-green] ${label}: transient ${last.status} (attempt ${attempt}/${config.retryAttempts}); retrying in ${config.retryDelayMs}ms`);
+            await deps.sleep(config.retryDelayMs);
+        }
+    }
+    deps.logger.warn(`[per-job-green] ${label}: still ${last.status} after ${config.retryAttempts} attempt(s)`);
+    return last;
+}
+/** Find the newest push run of the configured workflow for `sha`. Returns null if none exists yet. */
+async function resolveRun(deps, config, sha) {
+    const base = deps.apiBase ?? 'https://api.github.com';
+    const url = `${base}/repos/${config.owner}/${config.repo}/actions/runs?head_sha=${sha}&event=${config.event}&per_page=50`;
+    const res = await getWithRetry(deps, config, url, 'actions runs listing');
+    if (res.status !== 200)
+        return { run: null, status: res.status };
+    const runs = asArray(res.body, 'workflow_runs')
+        .filter((r) => r.path?.endsWith(`/${config.workflow}`) || r.name === config.workflow);
+    if (runs.length === 0)
+        return { run: null, status: res.status };
+    const newest = [...runs].sort((a, b) => (b.created_at ?? '').localeCompare(a.created_at ?? ''))[0] ?? null;
+    return { run: newest, status: res.status };
+}
+/** Enumerate every job of a completed run and collect the ones that are not `success`. */
+async function evaluateRunJobs(deps, config, runId) {
+    const base = deps.apiBase ?? 'https://api.github.com';
+    const url = `${base}/repos/${config.owner}/${config.repo}/actions/runs/${runId}/jobs?per_page=100`;
+    const res = await getWithRetry(deps, config, url, `actions run ${runId} jobs`);
+    if (res.status !== 200) {
+        // Honest failure naming the endpoint: the retry budget is exhausted (or the
+        // status is definitively non-200), so the per-job conclusions are unknowable.
+        return [`actions run ${runId} jobs endpoint returned ${res.status} after ${config.retryAttempts} attempt(s)`];
+    }
+    const jobs = asArray(res.body, 'jobs');
+    if (jobs.length === 0)
+        return ['no-jobs-reported'];
+    return jobs.filter((j) => j.conclusion !== 'success').map((j) => `${j.name} (${j.conclusion ?? j.status ?? 'unknown'})`);
+}
+/**
+ * Extract the Actions run id from a check-run's details_url. Actions-created
+ * check runs point at `https://github.com/{owner}/{repo}/actions/runs/{run_id}/job/{job_id}`.
+ */
+export function runIdFromDetailsUrl(detailsUrl) {
+    if (!detailsUrl)
+        return null;
+    const match = /\/actions\/runs\/(\d+)(?:\/|$)/.exec(detailsUrl);
+    return match?.[1] ? Number.parseInt(match[1], 10) : null;
+}
+/**
+ * Resolve the fallback run id to the TARGET workflow's run.
+ *
+ * Discriminator: neither the check-run nor the check-suite REST payload carries
+ * a workflow-file field, so each candidate run id (parsed from Actions
+ * details_urls) is confirmed against the single-run endpoint
+ * `GET /actions/runs/{id}`, whose `path` names the workflow file. A candidate
+ * is accepted only when its confirmed path matches `config.workflow`.
+ *
+ * Availability compromise: when the commit carries exactly ONE distinct
+ * candidate and its confirmation is UNAVAILABLE (any non-200 — i.e. not a
+ * CONFIRMED mismatch), the sole candidate is accepted: no ambiguity exists on
+ * the commit, and demanding confirmation during the very Actions-API outage the
+ * fallback exists for would gut it. With MULTIPLE candidates, confirmation is
+ * required — an unconfirmable set resolves to null (UNRESOLVED), never a guess.
+ */
+async function resolveFallbackRunId(deps, config, candidateIds) {
+    const distinct = [...new Set(candidateIds)];
+    if (distinct.length === 0)
+        return null;
+    const base = deps.apiBase ?? 'https://api.github.com';
+    let unavailable = 0;
+    for (const id of distinct) {
+        const res = await getWithRetry(deps, config, `${base}/repos/${config.owner}/${config.repo}/actions/runs/${id}`, `actions run ${id} workflow confirmation`);
+        if (res.status !== 200) {
+            unavailable += 1;
+            continue;
+        }
+        const path = res.body?.path;
+        if (typeof path === 'string' && (path === config.workflow || path.endsWith(`/${config.workflow}`))) {
+            return id;
+        }
+    }
+    if (distinct.length === 1 && unavailable === 1) {
+        deps.logger.warn(`[per-job-green] sole fallback run candidate ${distinct[0]} accepted without workflow confirmation (confirmation endpoint unavailable; no ambiguity on this commit)`);
+        return distinct[0] ?? null;
+    }
+    return null;
+}
+/** Checks-API fallback: assess per-check conclusions for the commit when the Actions API is 503-ing. */
+async function evaluateCheckSuites(deps, config, sha) {
+    const base = deps.apiBase ?? 'https://api.github.com';
+    const suitesUrl = `${base}/repos/${config.owner}/${config.repo}/commits/${sha}/check-suites`;
+    const suitesRes = await getWithRetry(deps, config, suitesUrl, 'check-suites');
+    if (suitesRes.status !== 200)
+        return null;
+    const suites = asArray(suitesRes.body, 'check_suites');
+    if (suites.length === 0)
+        return null;
+    if (suites.some((s) => s.status !== 'completed'))
+        return null; // still running — let the caller keep polling
+    const runsUrl = `${base}/repos/${config.owner}/${config.repo}/commits/${sha}/check-runs?per_page=100`;
+    const runsRes = await getWithRetry(deps, config, runsUrl, 'check-runs');
+    if (runsRes.status !== 200)
+        return null;
+    const checks = asArray(runsRes.body, 'check_runs');
+    const failures = checks
+        .filter((c) => c.conclusion !== 'success' && c.conclusion !== 'neutral' && c.conclusion !== 'skipped')
+        .map((c) => `${c.name} (${c.conclusion ?? 'unknown'})`);
+    // Downstream artifact restores need the Actions run id even on this path.
+    // Actions-created check runs carry it in details_url. Resolution must be
+    // workflow-filtered (a commit can carry check runs from several push
+    // workflows); see resolveFallbackRunId for the exact discriminator. When no
+    // candidate resolves to the target workflow, runId stays null and the caller
+    // must treat the handoff as unresolved (the bin surfaces run_id= empty;
+    // release pipelines hard-fail their artifact restore honestly instead of
+    // misdirecting it).
+    const candidates = checks.map((c) => runIdFromDetailsUrl(c.details_url)).filter((id) => id !== null);
+    const runId = await resolveFallbackRunId(deps, config, candidates);
+    const runIdNote = runId === null ? '; run id UNRESOLVED from check-run details' : `; run id ${runId} resolved from check-run details`;
+    return {
+        ok: failures.length === 0,
+        runId,
+        headSha: sha,
+        failures,
+        source: 'check-suites',
+        reason: failures.length === 0
+            ? `check-suites fallback: all ${checks.length} checks green for ${sha}${runIdNote}`
+            : `check-suites fallback: ${failures.length} check(s) not green`,
+    };
+}
+/**
+ * Verify `sha`'s push-CI run is per-job green. Polls until the run completes or
+ * the deadline passes. Deterministic under injected `http`/`sleep`/`now`.
+ */
+export async function verifyPerJobGreen(deps, config, sha) {
+    const start = deps.now();
+    const deadline = start + config.deadlineMs;
+    while (true) {
+        const { run, status } = await resolveRun(deps, config, sha);
+        if (isTransientStatus(status)) {
+            // The runs listing stayed unavailable through its whole retry budget —
+            // try the Checks API before falling back to another poll cycle.
+            deps.logger.warn(`[per-job-green] Actions API unavailable (${status}) after retries — trying check-suites fallback for ${sha}`);
+            const fallback = await evaluateCheckSuites(deps, config, sha);
+            if (fallback)
+                return fallback;
+            deps.logger.warn('[per-job-green] check-suites fallback inconclusive; will retry');
+        }
+        else if (run) {
+            if (run.status === 'completed') {
+                if (run.conclusion !== 'success') {
+                    // Rollup already failed — still enumerate jobs for an actionable message.
+                    const failures = await evaluateRunJobs(deps, config, run.id);
+                    return {
+                        ok: false,
+                        runId: run.id,
+                        headSha: run.head_sha ?? sha,
+                        failures: failures.length > 0 ? failures : [`run conclusion ${run.conclusion ?? 'unknown'}`],
+                        source: 'actions',
+                        reason: `run ${run.id} concluded ${run.conclusion ?? 'unknown'}`,
+                    };
+                }
+                const failures = await evaluateRunJobs(deps, config, run.id);
+                return {
+                    ok: failures.length === 0,
+                    runId: run.id,
+                    headSha: run.head_sha ?? sha,
+                    failures,
+                    source: 'actions',
+                    reason: failures.length === 0
+                        ? `run ${run.id} is per-job green for ${run.head_sha ?? sha}`
+                        : `run ${run.id} has ${failures.length} non-green job(s)`,
+                };
+            }
+            deps.logger.info(`[per-job-green] run ${run.id} is ${run.status ?? 'pending'}; waiting`);
+        }
+        else {
+            deps.logger.info(`[per-job-green] no ${config.workflow} push run found yet for ${sha}; waiting`);
+        }
+        if (deps.now() >= deadline) {
+            return {
+                ok: false,
+                runId: run?.id ?? null,
+                headSha: run?.head_sha ?? null,
+                failures: ['deadline-exceeded'],
+                source: run ? 'actions' : 'none',
+                reason: `timed out after ${config.deadlineMs}ms waiting for ${config.workflow} to complete on ${sha}`,
+            };
+        }
+        await deps.sleep(config.pollIntervalMs);
+    }
+}

package/dist/lib/post-build-smoke.d.ts

@@ -0,0 +1,24 @@
+/**
+ * post-build-smoke — proves a freshly compiled binary boots.
+ *
+ * Runs `<binary> --version`, asserts the expected banner prefix, and rejects
+ * output containing packaging-failure sentinels (e.g. `sqlite-vec`,
+ * `$bunfs/root`) that mean a native addon or module failed to bundle.
+ */
+import type { Exec, ExecResult, Logger } from './effects.js';
+import type { SmokeConfig } from '../config.js';
+export interface SmokeResult {
+    readonly ok: boolean;
+    readonly detail: string;
+}
+/** Evaluate a captured `--version` run against the smoke policy. Pure. */
+export declare function evaluateSmokeOutput(result: ExecResult, config: Pick<SmokeConfig, 'bannerPrefix' | 'forbiddenStrings'>): SmokeResult;
+export interface RunSmokeOptions {
+    readonly binary: string;
+    readonly config: SmokeConfig;
+    readonly exec?: Exec;
+    readonly logger?: Logger;
+}
+/** Run the version smoke against a binary path. */
+export declare function runPostBuildSmoke(options: RunSmokeOptions): SmokeResult;
+//# sourceMappingURL=post-build-smoke.d.ts.map

package/dist/lib/post-build-smoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-build-smoke.d.ts","sourceRoot":"","sources":["../../src/lib/post-build-smoke.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,cAAc,GAAG,kBAAkB,CAAC,GAAG,WAAW,CAanI;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,mDAAmD;AACnD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,eAAe,GAAG,WAAW,CAQvE"}

package/dist/lib/post-build-smoke.js

@@ -0,0 +1,33 @@
+/**
+ * post-build-smoke — proves a freshly compiled binary boots.
+ *
+ * Runs `<binary> --version`, asserts the expected banner prefix, and rejects
+ * output containing packaging-failure sentinels (e.g. `sqlite-vec`,
+ * `$bunfs/root`) that mean a native addon or module failed to bundle.
+ */
+import { realExec, consoleLogger } from './effects.js';
+/** Evaluate a captured `--version` run against the smoke policy. Pure. */
+export function evaluateSmokeOutput(result, config) {
+    const combined = `${result.stdout}\n${result.stderr}`;
+    if (result.status !== 0) {
+        return { ok: false, detail: `binary exited ${result.status}: ${combined.trim().slice(0, 400)}` };
+    }
+    const forbidden = config.forbiddenStrings.find((s) => combined.includes(s));
+    if (forbidden) {
+        return { ok: false, detail: `output contains packaging-failure sentinel "${forbidden}"` };
+    }
+    if (!result.stdout.trimStart().startsWith(config.bannerPrefix)) {
+        return { ok: false, detail: `version banner does not start with "${config.bannerPrefix}": ${result.stdout.trim().slice(0, 200)}` };
+    }
+    return { ok: true, detail: `version banner OK: ${result.stdout.trim().slice(0, 120)}` };
+}
+/** Run the version smoke against a binary path. */
+export function runPostBuildSmoke(options) {
+    const exec = options.exec ?? realExec;
+    const logger = options.logger ?? consoleLogger;
+    logger.info(`[post-build-smoke] ${options.binary} --version`);
+    const result = exec(options.binary, ['--version']);
+    const evaluated = evaluateSmokeOutput(result, options.config);
+    (evaluated.ok ? logger.info : logger.error)(`[post-build-smoke] ${evaluated.detail}`);
+    return evaluated;
+}

package/dist/lib/publish-package.d.ts

@@ -0,0 +1,45 @@
+/**
+ * publish-package — idempotent npm publish + post-publish propagation poll.
+ *
+ * One implementation of the publish concern with a single set of constants.
+ * Idempotency: if the exact name@version is already on the registry, skip
+ * (re-runs are safe). Propagation poll: after publish, wait until the registry
+ * actually serves the new version before downstream jobs depend on it.
+ */
+import type { Exec, Logger, Sleep } from './effects.js';
+/** Query the published version of name@version; null when absent (or on error). */
+export declare function getPublishedVersion(exec: Exec, name: string, version: string, registry: string): string | null;
+export interface PublishOptions {
+    readonly cwd: string;
+    readonly name: string;
+    readonly version: string;
+    readonly registry?: string;
+    readonly dryRun?: boolean;
+    readonly exec?: Exec;
+    readonly logger?: Logger;
+}
+export interface PublishResult {
+    readonly ok: boolean;
+    readonly skipped: boolean;
+    readonly detail: string;
+}
+/** Publish the package in `cwd`, skipping if already published. */
+export declare function runPublishPackage(options: PublishOptions): PublishResult;
+export interface PropagationOptions {
+    readonly name: string;
+    readonly version: string;
+    readonly registry?: string;
+    readonly attempts?: number;
+    readonly delayMs?: number;
+    readonly exec?: Exec;
+    readonly sleep?: Sleep;
+    readonly logger?: Logger;
+}
+export interface PropagationResult {
+    readonly ok: boolean;
+    readonly attempts: number;
+    readonly detail: string;
+}
+/** Poll the registry until name@version resolves, or attempts are exhausted. */
+export declare function pollPropagation(options: PropagationOptions): Promise<PropagationResult>;
+//# sourceMappingURL=publish-package.d.ts.map

package/dist/lib/publish-package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-package.d.ts","sourceRoot":"","sources":["../../src/lib/publish-package.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAIxD,mFAAmF;AACnF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK9G;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CAsBxE;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,gFAAgF;AAChF,wBAAsB,eAAe,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAiB7F"}

package/dist/lib/publish-package.js

@@ -0,0 +1,58 @@
+/**
+ * publish-package — idempotent npm publish + post-publish propagation poll.
+ *
+ * One implementation of the publish concern with a single set of constants.
+ * Idempotency: if the exact name@version is already on the registry, skip
+ * (re-runs are safe). Propagation poll: after publish, wait until the registry
+ * actually serves the new version before downstream jobs depend on it.
+ */
+import { realExec, consoleLogger, realSleep } from './effects.js';
+import { DEFAULT_REGISTRY } from '../config.js';
+/** Query the published version of name@version; null when absent (or on error). */
+export function getPublishedVersion(exec, name, version, registry) {
+    const res = exec('npm', ['view', `${name}@${version}`, 'version', '--registry', registry]);
+    if (res.status !== 0)
+        return null;
+    const out = res.stdout.trim();
+    return out.length > 0 ? out : null;
+}
+/** Publish the package in `cwd`, skipping if already published. */
+export function runPublishPackage(options) {
+    const exec = options.exec ?? realExec;
+    const logger = options.logger ?? consoleLogger;
+    const registry = options.registry ?? DEFAULT_REGISTRY;
+    if (options.dryRun) {
+        const res = exec('npm', ['pack', '--json'], { cwd: options.cwd });
+        return { ok: res.status === 0, skipped: false, detail: res.status === 0 ? 'dry-run pack ok' : `dry-run pack failed: ${res.stderr.trim()}` };
+    }
+    const already = getPublishedVersion(exec, options.name, options.version, registry);
+    if (already === options.version) {
+        logger.info(`[publish-package] ${options.name}@${options.version} already published — skipping`);
+        return { ok: true, skipped: true, detail: 'already published' };
+    }
+    const res = exec('npm', ['publish', '--access', 'public', '--registry', registry], { cwd: options.cwd });
+    if (res.status !== 0) {
+        return { ok: false, skipped: false, detail: `npm publish failed: ${res.stderr.trim().slice(0, 400)}` };
+    }
+    logger.info(`[publish-package] published ${options.name}@${options.version}`);
+    return { ok: true, skipped: false, detail: 'published' };
+}
+/** Poll the registry until name@version resolves, or attempts are exhausted. */
+export async function pollPropagation(options) {
+    const exec = options.exec ?? realExec;
+    const sleep = options.sleep ?? realSleep;
+    const logger = options.logger ?? consoleLogger;
+    const registry = options.registry ?? DEFAULT_REGISTRY;
+    const attempts = options.attempts ?? 48;
+    const delayMs = options.delayMs ?? 5000;
+    for (let attempt = 1; attempt <= attempts; attempt++) {
+        const published = getPublishedVersion(exec, options.name, options.version, registry);
+        if (published === options.version) {
+            return { ok: true, attempts: attempt, detail: `${options.name}@${options.version} resolvable after ${attempt} attempt(s)` };
+        }
+        logger.info(`[publish-package] propagation ${attempt}/${attempts}: ${options.name}@${options.version} not yet resolvable`);
+        if (attempt < attempts)
+            await sleep(delayMs);
+    }
+    return { ok: false, attempts, detail: `${options.name}@${options.version} did not propagate within ${attempts} attempt(s)` };
+}

package/dist/lib/release-cut.d.ts

@@ -0,0 +1,52 @@
+/**
+ * release-cut — local release preparation ONLY.
+ *
+ * Per the CI/CD design's principle 4 (CI owns validation), this tool never
+ * re-runs gates. It: guards a clean tree on the release branch, bumps the
+ * version across the root and configured manifests, runs the repo's version-
+ * sync commands, prepends a CHANGELOG section, commits, and creates an
+ * annotated tag. Validation happened on the push CI run; the tag is cut from an
+ * already-green tree and verified by-reference downstream.
+ */
+import type { Exec, Logger } from './effects.js';
+import type { ReleaseCutConfig } from '../config.js';
+export type BumpKind = 'patch' | 'minor' | 'major';
+export interface Semver {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+}
+/** Parse an exact X.Y.Z string; throws on anything else. */
+export declare function parseSemver(version: string): Semver;
+/** Compute the next version for a bump kind. */
+export declare function nextVersion(current: string, kind: BumpKind): string;
+/** Render a CHANGELOG section heading for a version. */
+export declare function changelogHeading(version: string, style: 'bracket' | 'plain', date: string): string;
+/** Build a full CHANGELOG section body from a heading and notes/commit lines. */
+export declare function buildChangelogSection(version: string, style: 'bracket' | 'plain', date: string, bodyLines: readonly string[]): string;
+/**
+ * Insert a new section into changelog text. `top` prepends above the first
+ * `## ` heading; `first-separator` inserts after the first `---` line.
+ */
+export declare function insertChangelogSection(changelog: string, section: string, marker: 'first-separator' | 'top'): string;
+export interface ReleaseCutOptions {
+    readonly cwd: string;
+    readonly bump: BumpKind;
+    readonly config: ReleaseCutConfig;
+    readonly notes?: readonly string[];
+    readonly date?: string;
+    readonly dryRun?: boolean;
+    readonly exec?: Exec;
+    readonly logger?: Logger;
+}
+export interface ReleaseCutResult {
+    readonly version: string;
+    readonly tag: string;
+    readonly committed: boolean;
+}
+/**
+ * Perform a release cut. Uses real fs writes + the injected exec (git) against
+ * `cwd`; tests drive it against a temp-dir git fixture.
+ */
+export declare function runReleaseCut(options: ReleaseCutOptions): ReleaseCutResult;
+//# sourceMappingURL=release-cut.d.ts.map

package/dist/lib/release-cut.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-cut.d.ts","sourceRoot":"","sources":["../../src/lib/release-cut.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAEnD,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,4DAA4D;AAC5D,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAInD;AAED,gDAAgD;AAChD,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAKnE;AAED,wDAAwD;AACxD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAElG;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAGrI;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,KAAK,GAAG,MAAM,CAUpH;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAqBD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CA6C1E"}