@pellux/goodvibes-toolchain 1.11.0

package/README.md

@@ -0,0 +1,50 @@
+# @pellux/goodvibes-toolchain
+
+Shared GoodVibes CI/CD toolchain. One published home for the release, publish,
+and verification scripts that used to live as 2–3 parallel copies across the
+`goodvibes-tui`, `goodvibes-agent`, `goodvibes-webui`, and `goodvibes-sdk`
+repos. Repo-specific values live in each repo's `toolchain.config.json`; the
+behavior lives here, so every repo maintains one implementation instead of
+several drifting ones.
+
+## Tools
+
+Each tool ships as a library policy function (with injectable I/O for testing)
+and a thin CLI (`bin` entry):
+
+- **sdk-pin-gate** — pin ⇄ lockfile ⇄ installed tri-agreement plus a non-npm
+  import sweep and an optional exports-map check.
+- **build-binaries** — `bun build --compile` across a target matrix, with an
+  optional daemon leg and native-addon copy/cross-fetch, all config-driven.
+- **release-cut** — prepare/bump/changelog/tag only. Never re-runs gates (CI
+  owns validation).
+- **coverage-gate** — aggregate coverage ratchet against per-repo floors.
+- **verification-ledger** — totals math and JSON/Markdown rendering of a
+  repo-collected verification inventory.
+- **post-build-smoke** — boots a compiled binary and checks its version banner.
+- **package-install-check** — static `npm pack` tarball + bin-shim policy check.
+- **publish-package** — idempotent `npm publish` plus a propagation poll.
+- **per-job-green** — verifies a commit's push-CI run concluded with every job
+  green, with a 503-resilient check-suites fallback. The by-reference
+  validation primitive.
+- **changelog-gate** — asserts CHANGELOG carries a section for a version.
+- **sha256sums** — generate/verify a `SHA256SUMS` manifest over release assets.
+
+## Config
+
+See `docs/release-and-publishing.md` in the SDK repo for the full
+`toolchain.config.json` contract and per-repo examples. Import the
+`ToolchainConfig` type from `@pellux/goodvibes-toolchain` for editor help.
+
+## Usage
+
+```ts
+import { runSdkPinGate, realFsReader, loadToolchainConfig } from '@pellux/goodvibes-toolchain';
+
+const config = loadToolchainConfig();
+const results = runSdkPinGate(realFsReader(process.cwd()), config.sdkPin);
+```
+
+Every function accepts its effects (exec, fs, http, sleep, logger) as
+parameters, so unit tests drive them with in-memory stubs — no network and no
+real git mutations.

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

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=build-binaries.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build-binaries.d.ts","sourceRoot":"","sources":["../../src/bin/build-binaries.ts"],"names":[],"mappings":""}

package/dist/bin/build-binaries.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { loadToolchainConfig } from '../lib/load-config.js';
+import { realExec, consoleLogger } from '../lib/effects.js';
+import { resolveTargets, runBuildBinaries } from '../lib/build-binaries.js';
+const root = process.cwd();
+const config = loadToolchainConfig(root);
+if (!config.build) {
+    consoleLogger.error('build-binaries: no `build` section in toolchain.config.json');
+    process.exit(1);
+}
+const build = config.build;
+const nativeKey = `${process.platform === 'darwin' ? 'darwin' : process.platform}-${process.arch}`;
+/** Copy the native addon beside the binary; same-host miss is fatal, cross-target miss fetches via npm pack + tar. */
+function provideAddon(target, sameHost) {
+    if (!target.nativeAddonPackage || !target.nativeAddonFile)
+        return true;
+    const destDir = resolve(root, build.addonOutDir, target.nativeAddonPackage);
+    const dest = join(destDir, target.nativeAddonFile);
+    const source = resolve(root, 'node_modules', target.nativeAddonPackage, target.nativeAddonFile);
+    mkdirSync(destDir, { recursive: true });
+    if (existsSync(source)) {
+        copyFileSync(source, dest);
+        return true;
+    }
+    if (sameHost) {
+        consoleLogger.error(`[build-binaries] native addon missing for host target ${target.key}; run install`);
+        return false;
+    }
+    const versionPkg = resolve(root, 'node_modules', 'sqlite-vec', 'package.json');
+    if (!existsSync(versionPkg))
+        return false;
+    const version = JSON.parse(readFileSync(versionPkg, 'utf8')).version;
+    const tmp = mkdtempSync(join(tmpdir(), 'gv-addon-'));
+    try {
+        const pack = realExec('npm', ['pack', `${target.nativeAddonPackage}@${version}`, '--pack-destination', tmp]);
+        if (pack.status !== 0)
+            return false;
+        const tarball = pack.stdout.trim().split('\n').pop();
+        if (!tarball)
+            return false;
+        const untar = realExec('tar', ['-xzf', join(tmp, tarball), '-C', tmp]);
+        if (untar.status !== 0)
+            return false;
+        const extracted = join(tmp, 'package', target.nativeAddonFile);
+        if (!existsSync(extracted))
+            return false;
+        copyFileSync(extracted, dest);
+        return true;
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}
+try {
+    const selection = resolveTargets(process.argv.slice(2), build, nativeKey);
+    const outcomes = runBuildBinaries({ cwd: root, config: build, selection, nativeKey, provideAddon, logger: consoleLogger });
+    const failed = outcomes.filter((o) => !o.ok);
+    consoleLogger.info(`build-binaries: ${outcomes.length - failed.length}/${outcomes.length} target(s) built`);
+    process.exit(failed.length > 0 ? 1 : 0);
+}
+catch (error) {
+    consoleLogger.error(`build-binaries: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+}

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

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=changelog-gate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"changelog-gate.d.ts","sourceRoot":"","sources":["../../src/bin/changelog-gate.ts"],"names":[],"mappings":""}

package/dist/bin/changelog-gate.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { consoleLogger } from '../lib/effects.js';
+import { runChangelogGate } from '../lib/changelog-gate.js';
+const root = process.cwd();
+const versionArg = process.argv.find((a) => /^\d+\.\d+\.\d+/.test(a));
+const version = versionArg ?? JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8')).version;
+const headingArg = process.argv.includes('--plain') ? 'plain' : process.argv.includes('--bracket') ? 'bracket' : 'either';
+const changelog = readFileSync(resolve(root, 'CHANGELOG.md'), 'utf8');
+const result = runChangelogGate(changelog, version, headingArg);
+consoleLogger.info(`changelog-gate: ${result.detail}`);
+process.exit(result.ok ? 0 : 1);

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

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=coverage-gate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-gate.d.ts","sourceRoot":"","sources":["../../src/bin/coverage-gate.ts"],"names":[],"mappings":""}

package/dist/bin/coverage-gate.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { loadToolchainConfig } from '../lib/load-config.js';
+import { realExec, consoleLogger } from '../lib/effects.js';
+import { evaluateCoverageGate } from '../lib/coverage-gate.js';
+const root = process.cwd();
+const config = loadToolchainConfig(root);
+if (!config.coverage) {
+    consoleLogger.error('coverage-gate: no `coverage` section in toolchain.config.json');
+    process.exit(1);
+}
+const [bin, ...args] = config.coverage.command;
+if (!bin) {
+    consoleLogger.error('coverage-gate: coverage.command is empty');
+    process.exit(1);
+}
+const run = realExec(bin, args, { cwd: root });
+const result = evaluateCoverageGate(`${run.stdout}\n${run.stderr}`, config.coverage);
+consoleLogger.info(`coverage-gate: ${result.detail}`);
+process.exit(result.ok ? 0 : 1);

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

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=package-install-check.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"package-install-check.d.ts","sourceRoot":"","sources":["../../src/bin/package-install-check.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { loadToolchainConfig } from '../lib/load-config.js';
+import { consoleLogger } from '../lib/effects.js';
+import { runPackageInstallCheck } from '../lib/package-install-check.js';
+const root = process.cwd();
+const config = loadToolchainConfig(root);
+if (!config.publish) {
+    consoleLogger.error('package-install-check: no `publish` section in toolchain.config.json');
+    process.exit(1);
+}
+const result = runPackageInstallCheck({ cwd: root, config: config.publish, logger: consoleLogger });
+for (const issue of result.issues)
+    consoleLogger.error(`  - ${issue}`);
+process.exit(result.ok ? 0 : 1);

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

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=per-job-green.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"per-job-green.d.ts","sourceRoot":"","sources":["../../src/bin/per-job-green.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { appendFileSync } from 'node:fs';
+import { realHttpGetJson, realSleep, consoleLogger } from '../lib/effects.js';
+import { verifyPerJobGreen } from '../lib/per-job-green.js';
+import { resolvePerJobGreenConfig } from '../config.js';
+function argValue(flag) {
+    const idx = process.argv.indexOf(flag);
+    return idx !== -1 ? process.argv[idx + 1] : undefined;
+}
+const repoSlug = argValue('--repo') ?? process.env.GITHUB_REPOSITORY ?? '';
+const [owner, repo] = repoSlug.split('/');
+const sha = argValue('--sha') ?? process.env.GITHUB_SHA;
+if (!owner || !repo || !sha) {
+    consoleLogger.error('per-job-green: --repo <owner/repo> (or GITHUB_REPOSITORY) and --sha (or GITHUB_SHA) are required');
+    process.exit(2);
+}
+function intArg(flag) {
+    const raw = argValue(flag);
+    if (raw === undefined)
+        return undefined;
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isFinite(value) || value <= 0) {
+        consoleLogger.error(`per-job-green: ${flag} must be a positive integer (got '${raw}')`);
+        process.exit(2);
+    }
+    return value;
+}
+const retryAttempts = intArg('--retry-attempts');
+const retryDelayMs = intArg('--retry-delay-ms');
+// Size --deadline-ms UNDER the enclosing CI job's timeout cap so an exhausted
+// wait produces the tool's honest named verdict (deadline-exceeded) instead of
+// a raw job kill with no verdict at all.
+const deadlineMs = intArg('--deadline-ms');
+const config = resolvePerJobGreenConfig({
+    owner,
+    repo,
+    workflow: argValue('--workflow') ?? 'ci.yml',
+    event: argValue('--event') ?? 'push',
+    ...(retryAttempts !== undefined ? { retryAttempts } : {}),
+    ...(retryDelayMs !== undefined ? { retryDelayMs } : {}),
+    ...(deadlineMs !== undefined ? { deadlineMs } : {}),
+});
+const token = process.env.GH_TOKEN ?? process.env.GITHUB_TOKEN;
+const result = await verifyPerJobGreen({ http: realHttpGetJson, sleep: realSleep, logger: consoleLogger, now: () => Date.now(), ...(token ? { token } : {}) }, config, sha);
+consoleLogger.info(`per-job-green: ${result.reason}`);
+if (result.failures.length > 0)
+    consoleLogger.info(`  non-green: ${result.failures.join(', ')}`);
+if (result.ok && result.runId === null) {
+    consoleLogger.warn('per-job-green: verdict is green but the run id is UNRESOLVED — run_id output is empty; artifact restores keyed on it must fail fast rather than download from the wrong run');
+}
+if (process.env.GITHUB_OUTPUT) {
+    appendFileSync(process.env.GITHUB_OUTPUT, `run_id=${result.runId ?? ''}\nhead_sha=${result.headSha ?? ''}\nok=${result.ok}\n`);
+}
+process.exit(result.ok ? 0 : 1);

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

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=post-build-smoke.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"post-build-smoke.d.ts","sourceRoot":"","sources":["../../src/bin/post-build-smoke.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { loadToolchainConfig } from '../lib/load-config.js';
+import { consoleLogger } from '../lib/effects.js';
+import { runPostBuildSmoke } from '../lib/post-build-smoke.js';
+const root = process.cwd();
+const config = loadToolchainConfig(root);
+if (!config.smoke) {
+    consoleLogger.error('post-build-smoke: no `smoke` section in toolchain.config.json');
+    process.exit(1);
+}
+const binaryIdx = process.argv.indexOf('--binary');
+const binary = binaryIdx !== -1 ? process.argv[binaryIdx + 1] : undefined;
+const result = runPostBuildSmoke({ binary: binary ?? config.smoke.binaryDefault, config: config.smoke, logger: consoleLogger });
+process.exit(result.ok ? 0 : 1);

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

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=publish-package.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"publish-package.d.ts","sourceRoot":"","sources":["../../src/bin/publish-package.ts"],"names":[],"mappings":""}

package/dist/bin/publish-package.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadToolchainConfig } from '../lib/load-config.js';
+import { consoleLogger } from '../lib/effects.js';
+import { runPublishPackage, pollPropagation } from '../lib/publish-package.js';
+const root = process.cwd();
+const config = loadToolchainConfig(root);
+if (!config.publish) {
+    consoleLogger.error('publish-package: no `publish` section in toolchain.config.json');
+    process.exit(1);
+}
+const version = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8')).version;
+const dryRun = process.argv.includes('--dry-run');
+const registry = process.env.GOODVIBES_PUBLISH_REGISTRY ?? config.publish.defaultRegistry;
+const result = runPublishPackage({ cwd: root, name: config.publish.packageName, version, registry, dryRun, logger: consoleLogger });
+consoleLogger.info(`publish-package: ${result.detail}`);
+if (!result.ok)
+    process.exit(1);
+if (!dryRun && !result.skipped && process.argv.includes('--poll')) {
+    const prop = await pollPropagation({ name: config.publish.packageName, version, registry, logger: consoleLogger });
+    consoleLogger.info(`publish-package: ${prop.detail}`);
+    process.exit(prop.ok ? 0 : 1);
+}
+process.exit(0);

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

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=release-cut.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"release-cut.d.ts","sourceRoot":"","sources":["../../src/bin/release-cut.ts"],"names":[],"mappings":""}

package/dist/bin/release-cut.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadToolchainConfig } from '../lib/load-config.js';
+import { consoleLogger } from '../lib/effects.js';
+import { runReleaseCut } from '../lib/release-cut.js';
+const root = process.cwd();
+const config = loadToolchainConfig(root);
+if (!config.releaseCut) {
+    consoleLogger.error('release-cut: no `releaseCut` section in toolchain.config.json');
+    process.exit(1);
+}
+const bump = process.argv.includes('--major') ? 'major' : process.argv.includes('--minor') ? 'minor' : 'patch';
+const dryRun = process.argv.includes('--dry-run');
+const notesIdx = process.argv.indexOf('--notes-file');
+const notes = notesIdx !== -1 && process.argv[notesIdx + 1]
+    ? readFileSync(resolve(root, process.argv[notesIdx + 1]), 'utf8').split('\n').filter((l) => l.trim().length > 0)
+    : [];
+try {
+    const result = runReleaseCut({ cwd: root, bump, config: config.releaseCut, notes, dryRun, logger: consoleLogger });
+    consoleLogger.info(`release-cut: prepared ${result.tag}${result.committed ? ' (committed + tagged)' : ' (dry-run)'}`);
+    process.exit(0);
+}
+catch (error) {
+    consoleLogger.error(`release-cut: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+}

package/dist/bin/sdk-pin-gate.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=sdk-pin-gate.d.ts.map

package/dist/bin/sdk-pin-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-pin-gate.d.ts","sourceRoot":"","sources":["../../src/bin/sdk-pin-gate.ts"],"names":[],"mappings":""}

package/dist/bin/sdk-pin-gate.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { loadToolchainConfig } from '../lib/load-config.js';
+import { realFsReader, consoleLogger } from '../lib/effects.js';
+import { runSdkPinGate } from '../lib/sdk-pin-gate.js';
+const root = process.cwd();
+const config = loadToolchainConfig(root);
+const results = runSdkPinGate(realFsReader(root), config.sdkPin);
+let failed = 0;
+for (const result of results) {
+    consoleLogger.info(`${result.ok ? 'PASS' : 'FAIL'}  ${result.id} — ${result.detail}`);
+    if (!result.ok)
+        failed += 1;
+}
+consoleLogger.info(`sdk-pin-gate: ${results.length - failed}/${results.length} gates passed`);
+process.exit(failed > 0 ? 1 : 0);

package/dist/bin/sha256sums.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=sha256sums.d.ts.map

package/dist/bin/sha256sums.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sha256sums.d.ts","sourceRoot":"","sources":["../../src/bin/sha256sums.ts"],"names":[],"mappings":""}

package/dist/bin/sha256sums.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { consoleLogger } from '../lib/effects.js';
+import { generateSha256Sums, verifySha256Sums } from '../lib/sha256sums.js';
+const root = process.cwd();
+const readBytes = (path) => (existsSync(resolve(root, path)) ? new Uint8Array(readFileSync(resolve(root, path))) : null);
+const hashBytes = (bytes) => createHash('sha256').update(bytes).digest('hex');
+function argValue(flag) {
+    const idx = process.argv.indexOf(flag);
+    return idx !== -1 ? process.argv[idx + 1] : undefined;
+}
+const verifyPath = argValue('--verify');
+if (verifyPath) {
+    const result = verifySha256Sums(readFileSync(resolve(root, verifyPath), 'utf8'), readBytes, hashBytes);
+    if (!result.ok) {
+        if (result.missing.length > 0)
+            consoleLogger.error(`sha256sums: missing ${result.missing.join(', ')}`);
+        if (result.mismatched.length > 0)
+            consoleLogger.error(`sha256sums: mismatched ${result.mismatched.join(', ')}`);
+        process.exit(1);
+    }
+    consoleLogger.info('sha256sums: all assets verified');
+    process.exit(0);
+}
+const outPath = argValue('--out') ?? 'SHA256SUMS.txt';
+const assets = process.argv.slice(2).filter((a) => !a.startsWith('--') && a !== outPath && a !== verifyPath);
+const entries = assets.map((path) => ({ name: basename(path), path }));
+const result = generateSha256Sums(entries, readBytes, hashBytes);
+if (!result.ok) {
+    consoleLogger.error(`sha256sums: refusing to write — missing asset(s): ${result.missing.join(', ')}`);
+    process.exit(1);
+}
+writeFileSync(resolve(root, outPath), result.manifest);
+consoleLogger.info(`sha256sums: wrote ${entries.length} checksum(s) to ${outPath}`);
+process.exit(0);

package/dist/bin/verification-ledger.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=verification-ledger.d.ts.map

package/dist/bin/verification-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification-ledger.d.ts","sourceRoot":"","sources":["../../src/bin/verification-ledger.ts"],"names":[],"mappings":""}

package/dist/bin/verification-ledger.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { consoleLogger } from '../lib/effects.js';
+import { renderLedgerJson, renderLedgerMarkdown } from '../lib/verification-ledger.js';
+function argValue(flag) {
+    const idx = process.argv.indexOf(flag);
+    return idx !== -1 ? process.argv[idx + 1] : undefined;
+}
+const root = process.cwd();
+const areasPath = argValue('--areas');
+if (!areasPath) {
+    consoleLogger.error('verification-ledger: --areas <file.json> is required (the repo-collected area inventory)');
+    process.exit(1);
+}
+const areas = JSON.parse(readFileSync(resolve(root, areasPath), 'utf8'));
+const json = process.argv.includes('--json');
+const rendered = json ? renderLedgerJson(areas) : renderLedgerMarkdown(areas);
+const outDir = argValue('--out');
+if (outDir) {
+    writeFileSync(resolve(root, outDir, 'verification-ledger.json'), renderLedgerJson(areas));
+    writeFileSync(resolve(root, outDir, 'verification-ledger.md'), renderLedgerMarkdown(areas));
+    consoleLogger.info(`verification-ledger: wrote verification-ledger.{json,md} to ${outDir}`);
+}
+else {
+    consoleLogger.info(rendered);
+}
+process.exit(0);

package/dist/config.d.ts

@@ -0,0 +1,147 @@
+/**
+ * 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).
+ */
+/** Where the SDK dependency pin lives and how the pin gate is parameterized. */
+export interface SdkPinConfig {
+    /** npm name of the pinned SDK package, e.g. `@pellux/goodvibes-sdk`. */
+    readonly sdkPackage: string;
+    /** Manifest group the pin is read from. TUI/webui use `dependencies`; the agent bundles the SDK as a `devDependencies` pin. */
+    readonly pinSource: 'dependencies' | 'devDependencies';
+    /** Lockfile whose text must resolve the pin, e.g. `bun.lock`. */
+    readonly lockfile: string;
+    /** Path (relative to repo root) of the dev-link overlay marker whose presence blocks a cut. */
+    readonly overlayMarker: string;
+    /** Source roots scanned for non-npm SDK imports. */
+    readonly sourceRoots: readonly string[];
+    /** When true, also assert every SDK subpath import resolves to a key in the installed package's `exports` map (webui browser-bundle gate). */
+    readonly enforceExportsMap: boolean;
+}
+/** One row of the compiled-binary build matrix. */
+export interface BinaryTarget {
+    /** Canonical key, e.g. `linux-x64`. */
+    readonly key: string;
+    /** `bun build --compile --target` value, e.g. `bun-linux-x64`. */
+    readonly bunTarget: string;
+    /** Primary binary output name, e.g. `goodvibes-linux-x64`. */
+    readonly appArtifact: string;
+    /** Optional second binary (the TUI daemon leg), e.g. `goodvibes-daemon-linux-x64`. */
+    readonly daemonArtifact?: string;
+    /** Optional native-addon package that stays `--external` and is copied beside the binary, e.g. `sqlite-vec-linux-x64`. */
+    readonly nativeAddonPackage?: string;
+    /** Native-addon filename, e.g. `vec0.so` / `vec0.dylib`. */
+    readonly nativeAddonFile?: string;
+}
+/** build-binaries parameters. */
+export interface BuildConfig {
+    /** Primary compile entrypoint, e.g. `src/main.ts`. */
+    readonly appEntrypoint: string;
+    /** Optional daemon compile entrypoint (present only for repos with a daemon leg), e.g. `src/daemon/cli.ts`. */
+    readonly daemonEntrypoint?: string;
+    /** Output directory for binaries, e.g. `dist`. */
+    readonly outDir: string;
+    /** Directory for copied native addons, e.g. `dist/lib`. */
+    readonly addonOutDir: string;
+    /** The build matrix. */
+    readonly targets: readonly BinaryTarget[];
+    /** Commands run once before compiling (each a full argv), e.g. `[["bun","run","scripts/prebuild.ts"]]`. */
+    readonly prebuild: readonly (readonly string[])[];
+}
+/** coverage-gate ratchet floors and the coverage command. */
+export interface CoverageConfig {
+    readonly funcsFloor: number;
+    readonly linesFloor: number;
+    /** argv that emits Bun's text coverage table, e.g. `["bun","test","--coverage","src"]`. */
+    readonly command: readonly string[];
+}
+/** post-build-smoke parameters. */
+export interface SmokeConfig {
+    /** Expected `--version` banner prefix, e.g. `goodvibes-agent `. */
+    readonly bannerPrefix: string;
+    /** Substrings whose presence in output signals a packaging failure, e.g. `["sqlite-vec","$bunfs/root"]`. */
+    readonly forbiddenStrings: readonly string[];
+    /**
+     * Default binary path when `--binary` is not passed. Serves LOCAL CLI runs
+     * only — CI matrix legs each build a different suffixed artifact, so the
+     * reusable binary-matrix workflow always passes the leg's own `--binary`.
+     */
+    readonly binaryDefault: string;
+}
+/** release-cut parameters (prepare/bump/changelog/tag only — never re-runs gates). */
+export interface ReleaseCutConfig {
+    /** Branch a cut is allowed from, e.g. `main`. */
+    readonly branch: string;
+    /** Extra `package.json` paths (beyond root) whose version is stamped, e.g. platform-package manifests. */
+    readonly versionFiles: readonly string[];
+    /** Commands that sync generated version surfaces after the bump, e.g. `[["bun","run","scripts/prebuild.ts"]]`. */
+    readonly syncCommands: readonly (readonly string[])[];
+    /** Paths staged into the release commit. */
+    readonly commitPaths: readonly string[];
+    /** `bracket` → `## [x.y.z] - DATE`; `plain` → `## x.y.z - DATE`. */
+    readonly changelogHeading: 'bracket' | 'plain';
+    /** `first-separator` inserts the new section after the first `---`; `top` prepends above all sections. */
+    readonly changelogInsertMarker: 'first-separator' | 'top';
+}
+/** publish-package parameters. */
+export interface PublishPackageConfig {
+    readonly packageName: string;
+    readonly defaultRegistry: string;
+    /** Tarball paths that must be present (all of them). */
+    readonly requiredTarballPaths: readonly string[];
+    /** Tarball path prefixes that must be absent. */
+    readonly forbiddenTarballPrefixes: readonly string[];
+    /** Hard cap on unpacked tarball size in bytes. */
+    readonly maxTarballBytes: number;
+}
+/** per-job-green parameters. */
+export interface PerJobGreenConfig {
+    readonly owner: string;
+    readonly repo: string;
+    /** Workflow file whose run is verified, e.g. `ci.yml`. */
+    readonly workflow: string;
+    /** Triggering event to match, e.g. `push`. */
+    readonly event: string;
+    readonly pollIntervalMs: number;
+    readonly deadlineMs: number;
+    /** Bounded retry attempts applied to EVERY GitHub API call before its status is treated as final. */
+    readonly retryAttempts: number;
+    /** Sleep between retry attempts. */
+    readonly retryDelayMs: number;
+}
+/** The complete repo config. All sections are optional so a repo declares only the tools it uses. */
+export interface ToolchainConfig {
+    /** npm name of the repo's primary package, e.g. `@pellux/goodvibes-tui`. */
+    readonly packageName: string;
+    readonly sdkPin?: SdkPinConfig;
+    readonly build?: BuildConfig;
+    readonly coverage?: CoverageConfig;
+    readonly smoke?: SmokeConfig;
+    readonly releaseCut?: ReleaseCutConfig;
+    readonly publish?: PublishPackageConfig;
+    readonly perJobGreen?: PerJobGreenConfig;
+}
+export declare const DEFAULT_SDK_PACKAGE = "@pellux/goodvibes-sdk";
+export declare const DEFAULT_LOCKFILE = "bun.lock";
+export declare const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+export declare const DEFAULT_POLL_INTERVAL_MS = 20000;
+export declare const DEFAULT_DEADLINE_MS = 1800000;
+export declare const DEFAULT_RETRY_ATTEMPTS = 8;
+export declare const DEFAULT_RETRY_DELAY_MS = 7000;
+/** Fill an SdkPinConfig with the conventional defaults for any missing field. */
+export declare function resolveSdkPinConfig(partial: Partial<SdkPinConfig> | undefined): SdkPinConfig;
+/** Fill a PerJobGreenConfig from a partial plus required identity fields. */
+export declare function resolvePerJobGreenConfig(partial: Partial<PerJobGreenConfig> & Pick<PerJobGreenConfig, 'owner' | 'repo'>): PerJobGreenConfig;
+/**
+ * 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 declare function parseToolchainConfig(raw: string): ToolchainConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}