@pellux/goodvibes-toolchain 1.11.0

package/dist/config.js

@@ -0,0 +1,62 @@
+/**
+ * toolchain.config contract.
+ *
+ * Every GoodVibes repo keeps a small `toolchain.config.json` (or a
+ * `toolchain.config.ts` that default-exports a {@link ToolchainConfig}) at its
+ * root. The published `@pellux/goodvibes-toolchain` package holds the behavior;
+ * the config holds the repo-specific values (package names, binary matrix,
+ * coverage floors, publish ordering) so one implementation serves every repo.
+ *
+ * The full contract and per-repo examples are documented in
+ * `docs/release-and-publishing.md` (SDK repo).
+ */
+export const DEFAULT_SDK_PACKAGE = '@pellux/goodvibes-sdk';
+export const DEFAULT_LOCKFILE = 'bun.lock';
+export const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
+export const DEFAULT_POLL_INTERVAL_MS = 20_000;
+export const DEFAULT_DEADLINE_MS = 1_800_000;
+// Default transient-error posture: the GitHub API's observed flaky mode makes
+// single-shot calls fail a meaningful fraction of the time, so every call gets
+// ~8 bounded attempts with sleeps in the 5-10s band before its status is final.
+export const DEFAULT_RETRY_ATTEMPTS = 8;
+export const DEFAULT_RETRY_DELAY_MS = 7_000;
+/** Fill an SdkPinConfig with the conventional defaults for any missing field. */
+export function resolveSdkPinConfig(partial) {
+    const sdkPackage = partial?.sdkPackage ?? DEFAULT_SDK_PACKAGE;
+    return {
+        sdkPackage,
+        pinSource: partial?.pinSource ?? 'dependencies',
+        lockfile: partial?.lockfile ?? DEFAULT_LOCKFILE,
+        overlayMarker: partial?.overlayMarker ?? `node_modules/${sdkPackage}/.local-sdk-overlay.json`,
+        sourceRoots: partial?.sourceRoots ?? ['src'],
+        enforceExportsMap: partial?.enforceExportsMap ?? false,
+    };
+}
+/** Fill a PerJobGreenConfig from a partial plus required identity fields. */
+export function resolvePerJobGreenConfig(partial) {
+    return {
+        owner: partial.owner,
+        repo: partial.repo,
+        workflow: partial.workflow ?? 'ci.yml',
+        event: partial.event ?? 'push',
+        pollIntervalMs: partial.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+        deadlineMs: partial.deadlineMs ?? DEFAULT_DEADLINE_MS,
+        retryAttempts: partial.retryAttempts ?? DEFAULT_RETRY_ATTEMPTS,
+        retryDelayMs: partial.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS,
+    };
+}
+/**
+ * Parse a JSON toolchain config. Kept separate from disk I/O so callers can
+ * validate a config object from any source (file, env, test fixture).
+ */
+export function parseToolchainConfig(raw) {
+    const value = JSON.parse(raw);
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('toolchain.config must be a JSON object.');
+    }
+    const record = value;
+    if (typeof record.packageName !== 'string' || record.packageName.length === 0) {
+        throw new Error('toolchain.config.packageName is required and must be a non-empty string.');
+    }
+    return value;
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @pellux/goodvibes-toolchain
+ *
+ * Shared GoodVibes CI/CD tooling. The published library exports every tool as a
+ * policy function with injectable effects (so callers and tests supply their own
+ * I/O), plus the {@link ToolchainConfig} contract that parameterizes each repo.
+ * The package also ships a thin CLI per tool (see `bin` in package.json).
+ */
+export * from './config.js';
+export * from './lib/effects.js';
+export * from './lib/load-config.js';
+export * from './lib/sdk-pin-gate.js';
+export * from './lib/build-binaries.js';
+export * from './lib/release-cut.js';
+export * from './lib/coverage-gate.js';
+export * from './lib/verification-ledger.js';
+export * from './lib/post-build-smoke.js';
+export * from './lib/package-install-check.js';
+export * from './lib/publish-package.js';
+export * from './lib/per-job-green.js';
+export * from './lib/changelog-gate.js';
+export * from './lib/sha256sums.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,0BAA0B,CAAC;AACzC,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,22 @@
+/**
+ * @pellux/goodvibes-toolchain
+ *
+ * Shared GoodVibes CI/CD tooling. The published library exports every tool as a
+ * policy function with injectable effects (so callers and tests supply their own
+ * I/O), plus the {@link ToolchainConfig} contract that parameterizes each repo.
+ * The package also ships a thin CLI per tool (see `bin` in package.json).
+ */
+export * from './config.js';
+export * from './lib/effects.js';
+export * from './lib/load-config.js';
+export * from './lib/sdk-pin-gate.js';
+export * from './lib/build-binaries.js';
+export * from './lib/release-cut.js';
+export * from './lib/coverage-gate.js';
+export * from './lib/verification-ledger.js';
+export * from './lib/post-build-smoke.js';
+export * from './lib/package-install-check.js';
+export * from './lib/publish-package.js';
+export * from './lib/per-job-green.js';
+export * from './lib/changelog-gate.js';
+export * from './lib/sha256sums.js';

package/dist/lib/build-binaries.d.ts

@@ -0,0 +1,45 @@
+/**
+ * build-binaries — compiles standalone binaries for the configured matrix.
+ *
+ * Absorbs tui/build.ts and agent/build.ts. The TUI's daemon leg (a second
+ * `bun build --compile` of a daemon entrypoint per target) is config-driven:
+ * a target/build with a `daemonEntrypoint` + `daemonArtifact` builds two
+ * binaries, one without builds one. Native addons (sqlite-vec) stay `--external`
+ * and are copied beside the binary; a same-platform miss is fatal, a
+ * cross-target miss triggers an `npm pack` + `tar` fetch.
+ */
+import type { Exec, Logger } from './effects.js';
+import type { BinaryTarget, BuildConfig } from '../config.js';
+/** Resolve which targets to build and whether the daemon leg is forced off/only. */
+export interface TargetSelection {
+    readonly targets: readonly BinaryTarget[];
+    readonly daemonOnly: boolean;
+}
+/**
+ * Resolve the target selection from argv against the matrix.
+ * - `--all` → every target.
+ * - `--target <key>` → that target; a `daemon-<key>` alias forces daemon-only.
+ * - `--daemon-only` → daemon leg only.
+ * - none → the native `${platform}-${arch}` row.
+ */
+export declare function resolveTargets(argv: readonly string[], config: BuildConfig, nativeKey: string): TargetSelection;
+/** Construct the `bun build --compile` argv for one entrypoint. */
+export declare function buildCompileArgs(entrypoint: string, bunTarget: string, outfile: string, externals: readonly string[]): string[];
+export interface BuildOutcome {
+    readonly key: string;
+    readonly ok: boolean;
+    readonly detail: string;
+}
+export interface RunBuildOptions {
+    readonly cwd: string;
+    readonly config: BuildConfig;
+    readonly selection: TargetSelection;
+    readonly nativeKey: string;
+    /** Copies a resolved native addon into place; returns false if it could not be provided. Injected so the real fs copy stays out of the policy. */
+    readonly provideAddon?: (target: BinaryTarget, sameHost: boolean) => boolean;
+    readonly exec?: Exec;
+    readonly logger?: Logger;
+}
+/** Compile the selected targets. Returns one outcome per target. */
+export declare function runBuildBinaries(options: RunBuildOptions): BuildOutcome[];
+//# sourceMappingURL=build-binaries.d.ts.map

package/dist/lib/build-binaries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-binaries.d.ts","sourceRoot":"","sources":["../../src/lib/build-binaries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE9D,oFAAoF;AACpF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,CAwB/G;AAED,mEAAmE;AACnE,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAI/H;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kJAAkJ;IAClJ,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,OAAO,KAAK,OAAO,CAAC;IAC7E,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,oEAAoE;AACpE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,YAAY,EAAE,CAyCzE"}

package/dist/lib/build-binaries.js

@@ -0,0 +1,98 @@
+/**
+ * build-binaries — compiles standalone binaries for the configured matrix.
+ *
+ * Absorbs tui/build.ts and agent/build.ts. The TUI's daemon leg (a second
+ * `bun build --compile` of a daemon entrypoint per target) is config-driven:
+ * a target/build with a `daemonEntrypoint` + `daemonArtifact` builds two
+ * binaries, one without builds one. Native addons (sqlite-vec) stay `--external`
+ * and are copied beside the binary; a same-platform miss is fatal, a
+ * cross-target miss triggers an `npm pack` + `tar` fetch.
+ */
+import { realExec, consoleLogger } from './effects.js';
+/**
+ * Resolve the target selection from argv against the matrix.
+ * - `--all` → every target.
+ * - `--target <key>` → that target; a `daemon-<key>` alias forces daemon-only.
+ * - `--daemon-only` → daemon leg only.
+ * - none → the native `${platform}-${arch}` row.
+ */
+export function resolveTargets(argv, config, nativeKey) {
+    const byKey = new Map(config.targets.map((t) => [t.key, t]));
+    let daemonOnly = argv.includes('--daemon-only');
+    if (argv.includes('--all')) {
+        return { targets: config.targets, daemonOnly };
+    }
+    const targetIdx = argv.indexOf('--target');
+    if (targetIdx !== -1) {
+        let name = argv[targetIdx + 1];
+        if (!name)
+            throw new Error('--target requires a value');
+        if (name.startsWith('daemon-')) {
+            daemonOnly = true;
+            name = name.slice('daemon-'.length).replace(/^macos-/, 'darwin-');
+        }
+        const target = byKey.get(name);
+        if (!target)
+            throw new Error(`Unknown target: ${name}`);
+        return { targets: [target], daemonOnly };
+    }
+    const native = byKey.get(nativeKey);
+    if (!native)
+        throw new Error(`Unsupported host target: ${nativeKey}`);
+    return { targets: [native], daemonOnly };
+}
+/** Construct the `bun build --compile` argv for one entrypoint. */
+export function buildCompileArgs(entrypoint, bunTarget, outfile, externals) {
+    const args = ['build', entrypoint, '--compile', `--target=${bunTarget}`, '--outfile', outfile];
+    for (const ext of externals)
+        args.push('--external', ext);
+    return args;
+}
+/** Compile the selected targets. Returns one outcome per target. */
+export function runBuildBinaries(options) {
+    const exec = options.exec ?? realExec;
+    const logger = options.logger ?? consoleLogger;
+    const { config, selection, cwd } = options;
+    for (const cmd of config.prebuild) {
+        const [bin, ...args] = cmd;
+        if (!bin)
+            continue;
+        const res = exec(bin, args, { cwd });
+        if (res.status !== 0)
+            throw new Error(`prebuild failed: ${cmd.join(' ')}\n${res.stderr}`);
+    }
+    const outcomes = [];
+    for (const target of selection.targets) {
+        const externals = target.nativeAddonPackage ? [target.nativeAddonPackage] : [];
+        let ok = true;
+        let detail = '';
+        if (!selection.daemonOnly) {
+            const outfile = `${config.outDir}/${target.appArtifact}`;
+            const args = buildCompileArgs(config.appEntrypoint, target.bunTarget, outfile, externals);
+            const res = exec('bun', args, { cwd });
+            if (res.status !== 0) {
+                ok = false;
+                detail = `app compile failed (${res.status})`;
+            }
+        }
+        if (ok && config.daemonEntrypoint && target.daemonArtifact) {
+            const outfile = `${config.outDir}/${target.daemonArtifact}`;
+            const args = buildCompileArgs(config.daemonEntrypoint, target.bunTarget, outfile, externals);
+            const res = exec('bun', args, { cwd });
+            if (res.status !== 0) {
+                ok = false;
+                detail = `daemon compile failed (${res.status})`;
+            }
+        }
+        if (ok && target.nativeAddonPackage && target.nativeAddonFile && options.provideAddon) {
+            const provided = options.provideAddon(target, target.key === options.nativeKey);
+            if (!provided) {
+                ok = false;
+                detail = `native addon ${target.nativeAddonPackage}/${target.nativeAddonFile} unavailable`;
+            }
+        }
+        outcomes.push({ key: target.key, ok, detail: ok ? 'built' : detail });
+        logger.info(`[build-binaries] ${target.key}: ${ok ? 'OK' : `FAILED — ${detail}`}`);
+    }
+    return outcomes;
+}

package/dist/lib/changelog-gate.d.ts

@@ -0,0 +1,18 @@
+/**
+ * changelog-gate — asserts CHANGELOG.md carries a section for a version.
+ *
+ * Supports both heading conventions in the estate: `## [1.2.3]` (SDK/TUI
+ * bracketed) and `## 1.2.3` (agent plain). Pure over injected text.
+ */
+export type ChangelogHeading = 'bracket' | 'plain' | 'either';
+/** Build the anchored header matcher for a version under the given convention. */
+export declare function changelogHeaderPattern(version: string, heading: ChangelogHeading): RegExp;
+/** True when `changelog` contains a section for `version`. */
+export declare function hasChangelogSection(changelog: string, version: string, heading?: ChangelogHeading): boolean;
+export interface ChangelogGateResult {
+    readonly ok: boolean;
+    readonly detail: string;
+}
+/** Gate a changelog for a version; returns a structured result (no process exit). */
+export declare function runChangelogGate(changelog: string, version: string, heading?: ChangelogHeading): ChangelogGateResult;
+//# sourceMappingURL=changelog-gate.d.ts.map

package/dist/lib/changelog-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changelog-gate.d.ts","sourceRoot":"","sources":["../../src/lib/changelog-gate.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAM9D,kFAAkF;AAClF,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAKzF;AAED,8DAA8D;AAC9D,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,gBAA2B,GAAG,OAAO,CAErH;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,qFAAqF;AACrF,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,gBAA2B,GAAG,mBAAmB,CAQ9H"}

package/dist/lib/changelog-gate.js

@@ -0,0 +1,32 @@
+/**
+ * changelog-gate — asserts CHANGELOG.md carries a section for a version.
+ *
+ * Supports both heading conventions in the estate: `## [1.2.3]` (SDK/TUI
+ * bracketed) and `## 1.2.3` (agent plain). Pure over injected text.
+ */
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Build the anchored header matcher for a version under the given convention. */
+export function changelogHeaderPattern(version, heading) {
+    const v = escapeRegExp(version);
+    if (heading === 'bracket')
+        return new RegExp(`^##\\s*\\[${v}\\]`, 'm');
+    if (heading === 'plain')
+        return new RegExp(`^##\\s*${v}(?:\\s|$|-)`, 'm');
+    return new RegExp(`^##\\s*(?:\\[${v}\\]|${v}(?:\\s|$|-))`, 'm');
+}
+/** True when `changelog` contains a section for `version`. */
+export function hasChangelogSection(changelog, version, heading = 'either') {
+    return changelogHeaderPattern(version, heading).test(changelog);
+}
+/** Gate a changelog for a version; returns a structured result (no process exit). */
+export function runChangelogGate(changelog, version, heading = 'either') {
+    const ok = hasChangelogSection(changelog, version, heading);
+    return {
+        ok,
+        detail: ok
+            ? `CHANGELOG contains a section for ${version}`
+            : `CHANGELOG is missing a section for ${version}. Add a "## ${heading === 'plain' ? version : `[${version}]`} - YYYY-MM-DD" heading before releasing.`,
+    };
+}

package/dist/lib/coverage-gate.d.ts

@@ -0,0 +1,25 @@
+/**
+ * coverage-gate — aggregate (single-process) coverage ratchet.
+ *
+ * Parses Bun's text coverage table ("All files | %Funcs | %Lines") and enforces
+ * per-repo floors. Test failures in the single-process run are reported as a
+ * note but do not fail the coverage gate (correctness is gated elsewhere).
+ */
+import type { CoverageConfig } from '../config.js';
+export interface CoverageSummary {
+    readonly funcsPct: number;
+    readonly linesPct: number;
+}
+/** Extract the aggregate `All files` row percentages from Bun coverage output. */
+export declare function parseCoverageSummary(output: string): CoverageSummary | null;
+/** Extract a Bun "N fail" count from the run output, if present. */
+export declare function parseFailCount(output: string): number;
+export interface CoverageGateResult {
+    readonly ok: boolean;
+    readonly summary: CoverageSummary | null;
+    readonly failCount: number;
+    readonly detail: string;
+}
+/** Evaluate coverage output against the configured floors. */
+export declare function evaluateCoverageGate(output: string, config: Pick<CoverageConfig, 'funcsFloor' | 'linesFloor'>): CoverageGateResult;
+//# sourceMappingURL=coverage-gate.d.ts.map

package/dist/lib/coverage-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-gate.d.ts","sourceRoot":"","sources":["../../src/lib/coverage-gate.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAInD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,kFAAkF;AAClF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAY3E;AAED,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,8DAA8D;AAC9D,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,cAAc,EAAE,YAAY,GAAG,YAAY,CAAC,GAAG,kBAAkB,CAelI"}

package/dist/lib/coverage-gate.js

@@ -0,0 +1,46 @@
+/**
+ * coverage-gate — aggregate (single-process) coverage ratchet.
+ *
+ * Parses Bun's text coverage table ("All files | %Funcs | %Lines") and enforces
+ * per-repo floors. Test failures in the single-process run are reported as a
+ * note but do not fail the coverage gate (correctness is gated elsewhere).
+ */
+const ANSI = /\x1b\[[0-9;]*m/g;
+/** Extract the aggregate `All files` row percentages from Bun coverage output. */
+export function parseCoverageSummary(output) {
+    const clean = output.replace(ANSI, '');
+    for (const line of clean.split('\n')) {
+        if (!line.trimStart().startsWith('All files'))
+            continue;
+        const cells = line.split('|').map((c) => c.trim());
+        const funcs = Number.parseFloat(cells[1] ?? '');
+        const lines = Number.parseFloat(cells[2] ?? '');
+        if (Number.isFinite(funcs) && Number.isFinite(lines)) {
+            return { funcsPct: funcs, linesPct: lines };
+        }
+    }
+    return null;
+}
+/** Extract a Bun "N fail" count from the run output, if present. */
+export function parseFailCount(output) {
+    const match = /^\s*(\d+)\s+fail\s*$/m.exec(output.replace(ANSI, ''));
+    return match?.[1] ? Number.parseInt(match[1], 10) : 0;
+}
+/** Evaluate coverage output against the configured floors. */
+export function evaluateCoverageGate(output, config) {
+    const summary = parseCoverageSummary(output);
+    const failCount = parseFailCount(output);
+    if (!summary) {
+        return { ok: false, summary: null, failCount, detail: 'no coverage table found in output — did the run crash?' };
+    }
+    const funcsOk = summary.funcsPct >= config.funcsFloor;
+    const linesOk = summary.linesPct >= config.linesFloor;
+    const ok = funcsOk && linesOk;
+    const parts = [
+        `Funcs ${summary.funcsPct.toFixed(2)}% (floor ${config.funcsFloor}) ${funcsOk ? 'OK' : 'BELOW'}`,
+        `Lines ${summary.linesPct.toFixed(2)}% (floor ${config.linesFloor}) ${linesOk ? 'OK' : 'BELOW'}`,
+    ];
+    if (failCount > 0)
+        parts.push(`note: ${failCount} single-process test failure(s) (cross-file interference debt; gated elsewhere)`);
+    return { ok, summary, failCount, detail: parts.join('; ') };
+}

package/dist/lib/effects.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Injectable effect boundaries.
+ *
+ * Every tool is a policy function that takes its effects as parameters, so unit
+ * tests drive it with in-memory stubs (no network, no real git mutation, no
+ * child processes). The thin bins wire the real Node/Bun implementations.
+ */
+/** Result of running a subprocess. */
+export interface ExecResult {
+    readonly status: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/** Runs a subprocess to completion and returns captured output. Never throws on non-zero exit. */
+export type Exec = (command: string, args: readonly string[], options?: {
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+}) => ExecResult;
+/** Minimal read-only filesystem seam. */
+export interface FsReader {
+    readonly exists: (path: string) => boolean;
+    readonly readText: (path: string) => string;
+    readonly readDir: (path: string) => readonly string[];
+    readonly isExecutable: (path: string) => boolean;
+}
+/** An HTTP GET returning a parsed JSON body plus the transport status. */
+export interface HttpResponse {
+    readonly status: number;
+    readonly body: unknown;
+}
+export type HttpGetJson = (url: string, headers: Readonly<Record<string, string>>) => Promise<HttpResponse>;
+/** Structured logger seam (tests capture lines; bins print to console). */
+export interface Logger {
+    readonly info: (line: string) => void;
+    readonly warn: (line: string) => void;
+    readonly error: (line: string) => void;
+}
+/** Sleep seam so pollers are deterministic in tests. */
+export type Sleep = (ms: number) => Promise<void>;
+/** Real subprocess runner: captures stdout/stderr, reports the exit status without throwing. */
+export declare const realExec: Exec;
+/** Real filesystem reader rooted at an absolute base directory. */
+export declare function realFsReader(root: string): FsReader;
+/** Real HTTP GET returning parsed JSON. Non-2xx does not throw — the status is reported so callers can branch (e.g. 503 fallback). */
+export declare const realHttpGetJson: HttpGetJson;
+/** Console-backed logger. */
+export declare const consoleLogger: Logger;
+/** In-memory logger for tests. */
+export declare function captureLogger(): Logger & {
+    readonly lines: string[];
+};
+export declare const realSleep: Sleep;
+//# sourceMappingURL=effects.d.ts.map

package/dist/lib/effects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effects.d.ts","sourceRoot":"","sources":["../../src/lib/effects.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,sCAAsC;AACtC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,kGAAkG;AAClG,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAE,KAAK,UAAU,CAAC;AAEnJ,yCAAyC;AACzC,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,MAAM,EAAE,CAAC;IACtD,QAAQ,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CAClD;AAED,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AACD,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAE5G,2EAA2E;AAC3E,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAED,wDAAwD;AACxD,MAAM,MAAM,KAAK,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAElD,gGAAgG;AAChG,eAAO,MAAM,QAAQ,EAAE,IAkBtB,CAAC;AAEF,mEAAmE;AACnE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAcnD;AAED,sIAAsI;AACtI,eAAO,MAAM,eAAe,EAAE,WAU7B,CAAC;AAEF,6BAA6B;AAC7B,eAAO,MAAM,aAAa,EAAE,MAI3B,CAAC;AAEF,kCAAkC;AAClC,wBAAgB,aAAa,IAAI,MAAM,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAA;CAAE,CAQrE;AAED,eAAO,MAAM,SAAS,EAAE,KAAqD,CAAC"}

package/dist/lib/effects.js

@@ -0,0 +1,78 @@
+/**
+ * Injectable effect boundaries.
+ *
+ * Every tool is a policy function that takes its effects as parameters, so unit
+ * tests drive it with in-memory stubs (no network, no real git mutation, no
+ * child processes). The thin bins wire the real Node/Bun implementations.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+/** Real subprocess runner: captures stdout/stderr, reports the exit status without throwing. */
+export const realExec = (command, args, options = {}) => {
+    try {
+        const stdout = execFileSync(command, args, {
+            cwd: options.cwd,
+            env: options.env ?? process.env,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        return { status: 0, stdout, stderr: '' };
+    }
+    catch (error) {
+        const err = error;
+        return {
+            status: typeof err.status === 'number' ? err.status : 1,
+            stdout: err.stdout ? err.stdout.toString() : '',
+            stderr: err.stderr ? err.stderr.toString() : '',
+        };
+    }
+};
+/** Real filesystem reader rooted at an absolute base directory. */
+export function realFsReader(root) {
+    const at = (path) => resolve(root, path);
+    return {
+        exists: (path) => existsSync(at(path)),
+        readText: (path) => readFileSync(at(path), 'utf8'),
+        readDir: (path) => readdirSync(at(path)),
+        isExecutable: (path) => {
+            try {
+                return (statSync(at(path)).mode & 0o111) !== 0;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+/** Real HTTP GET returning parsed JSON. Non-2xx does not throw — the status is reported so callers can branch (e.g. 503 fallback). */
+export const realHttpGetJson = async (url, headers) => {
+    const response = await fetch(url, { headers });
+    const text = await response.text();
+    let body = null;
+    try {
+        body = text.length > 0 ? JSON.parse(text) : null;
+    }
+    catch {
+        body = text;
+    }
+    return { status: response.status, body };
+};
+/** Console-backed logger. */
+export const consoleLogger = {
+    info: (line) => console.log(line),
+    warn: (line) => console.warn(line),
+    error: (line) => console.error(line),
+};
+/** In-memory logger for tests. */
+export function captureLogger() {
+    const lines = [];
+    return {
+        lines,
+        info: (line) => lines.push(line),
+        warn: (line) => lines.push(line),
+        error: (line) => lines.push(line),
+    };
+}
+export const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));

package/dist/lib/load-config.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Disk loader for toolchain.config. Kept separate from config.ts so the
+ * contract types stay import-safe in environments without a filesystem.
+ */
+import { type ToolchainConfig } from '../config.js';
+/** Load `toolchain.config.json` from a repo root. Throws if absent or invalid. */
+export declare function loadToolchainConfig(root?: string): ToolchainConfig;
+//# sourceMappingURL=load-config.d.ts.map

package/dist/lib/load-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-config.d.ts","sourceRoot":"","sources":["../../src/lib/load-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAAE,KAAK,eAAe,EAAwB,MAAM,cAAc,CAAC;AAE1E,kFAAkF;AAClF,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,MAAsB,GAAG,eAAe,CAMjF"}

package/dist/lib/load-config.js

@@ -0,0 +1,15 @@
+/**
+ * Disk loader for toolchain.config. Kept separate from config.ts so the
+ * contract types stay import-safe in environments without a filesystem.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseToolchainConfig } from '../config.js';
+/** Load `toolchain.config.json` from a repo root. Throws if absent or invalid. */
+export function loadToolchainConfig(root = process.cwd()) {
+    const path = resolve(root, 'toolchain.config.json');
+    if (!existsSync(path)) {
+        throw new Error(`toolchain.config.json not found at ${path}. See @pellux/goodvibes-toolchain docs for the contract.`);
+    }
+    return parseToolchainConfig(readFileSync(path, 'utf8'));
+}

package/dist/lib/package-install-check.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 type { Exec, FsReader, Logger } from './effects.js';
+import type { PublishPackageConfig } from '../config.js';
+export interface PathPolicyResult {
+    readonly ok: boolean;
+    readonly missing: readonly string[];
+    readonly forbidden: readonly string[];
+    readonly oversize: boolean;
+}
+/** Check a packed file list + unpacked size against the tarball policy. Pure. */
+export declare function evaluateTarballPaths(files: readonly string[], unpackedBytes: number, config: Pick<PublishPackageConfig, 'requiredTarballPaths' | 'forbiddenTarballPrefixes' | 'maxTarballBytes'>): PathPolicyResult;
+export interface BinCheckResult {
+    readonly name: string;
+    readonly ok: boolean;
+    readonly issues: readonly string[];
+}
+/** Verify one bin shim: present, executable, and has the expected shebang. */
+export declare function evaluateBinShim(fs: FsReader, path: string, name: string, shebang: string): BinCheckResult;
+/** Parse `npm pack --json` output into a file list and unpacked size. */
+export declare function parseNpmPack(output: string): {
+    files: string[];
+    unpackedBytes: number;
+};
+export interface InstallCheckOptions {
+    readonly cwd: string;
+    readonly config: PublishPackageConfig;
+    readonly bins?: readonly {
+        readonly name: string;
+        readonly path: string;
+        readonly shebang: string;
+    }[];
+    readonly exec?: Exec;
+    readonly fs?: FsReader;
+    readonly logger?: Logger;
+}
+export interface InstallCheckResult {
+    readonly ok: boolean;
+    readonly issues: readonly string[];
+}
+/** Run the full static install check. */
+export declare function runPackageInstallCheck(options: InstallCheckOptions): InstallCheckResult;
+//# sourceMappingURL=package-install-check.d.ts.map

package/dist/lib/package-install-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-install-check.d.ts","sourceRoot":"","sources":["../../src/lib/package-install-check.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEzD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,iFAAiF;AACjF,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,sBAAsB,GAAG,0BAA0B,GAAG,iBAAiB,CAAC,GAC1G,gBAAgB,CAMlB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,CASzG;AAQD,yEAAyE;AACzE,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,CAOvF;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACtG,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,yCAAyC;AACzC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CAyBvF"}