ekohacks 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ekohacks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# ekohacks
+
+The EkoHacks CLI: our everyday operations, automated one small command at a time.
+
+We run a distributed team shipping open source to npm with strict TDD and trunk based development. Every operation we repeat by hand gets written down first, run by hand until it is boring, and then encoded here. The first one is releasing: the manual process lives in [EkoLite's RELEASING.md](https://github.com/ekohacks/ekolite/blob/main/RELEASING.md), and `ekohacks release` is that document as a command.
+
+## Status
+
+The release command is built: the four stories in [`stories/`](stories/) are implemented, each delivered red first — a failing test is committed and reviewed before any production code exists. The suite is the specification. The acceptance test for the whole is the next real EkoLite release, run with `ekohacks release <version>`.
+
+## How this is built
+
+- A tested core policy behind nullable infrastructure, in the style of [James Shore's Testing Without Mocks](https://www.jamesshore.com/v2/projects/nullables): real wrappers around `git`, `gh` and `npm`, each with a `createNull()` that answers with configurable responses and records what was asked of it. No mocks, no spies.
+- The CLI layer stays thin. Everything worth testing lives below it.
+- TypeScript on Node 24, tests with Vitest, nothing bundled.

package/dist/cli.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// The thin shell: read the repo's files, wire the real wrappers, print one line per
+// check and per step, exit 0 only when the command ran to its end. Everything worth
+// testing lives below.
+import { readFileSync } from 'node:fs';
+import { createInterface } from 'node:readline/promises';
+import { GhWrapper } from './infrastructure/gh.js';
+import { GitWrapper } from './infrastructure/git.js';
+import { NpmWrapper } from './infrastructure/npm.js';
+import { ProcessRunner } from './infrastructure/process.js';
+import { cut } from './logic/cut.js';
+import { preflight } from './logic/preflight.js';
+import { release } from './logic/release.js';
+import { ship } from './logic/ship.js';
+const argv = process.argv.slice(2);
+const yes = argv.includes('--yes');
+const [command, ...rest] = argv.filter((arg) => arg !== '--yes');
+const first = rest[0];
+const subcommand = first === 'preflight' || first === 'cut' || first === 'ship' ? first : undefined;
+const version = subcommand === undefined ? first : rest[1];
+if (command !== 'release' || version === undefined) {
+    console.error('usage: ekohacks release [preflight|cut|ship] <version> [--yes]');
+    process.exit(2);
+}
+const read = (file) => readFileSync(file, 'utf8');
+const changelog = read('CHANGELOG.md');
+const pkg = JSON.parse(read('package.json')).name;
+const confirm = async (question) => {
+    const readline = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await readline.question(`${question} (y/n) `);
+    readline.close();
+    return answer.trim().toLowerCase() === 'y';
+};
+const narrate = (line) => console.log(`  ${line}`);
+if (subcommand === undefined) {
+    const result = await release({
+        version,
+        changelog,
+        lockfile: read('package-lock.json'),
+        pkg,
+        git: GitWrapper.create(),
+        npm: NpmWrapper.create(),
+        gh: GhWrapper.create(),
+        runner: ProcessRunner.create(),
+        confirm,
+        narrate,
+        yes,
+    });
+    if ('stopped' in result) {
+        console.error(`stopped: ${result.stopped}`);
+        process.exit(1);
+    }
+    process.exit(0);
+}
+if (subcommand === 'ship') {
+    const result = await ship({
+        version,
+        changelog,
+        pkg,
+        gh: GhWrapper.create(),
+        npm: NpmWrapper.create(),
+        confirm,
+        narrate,
+    });
+    if ('stopped' in result) {
+        console.error(`stopped: ${result.stopped}`);
+        process.exit(1);
+    }
+    process.exit(0);
+}
+const report = await preflight({
+    version,
+    pkg,
+    changelog,
+    lockfile: read('package-lock.json'),
+    npm: NpmWrapper.create(),
+    git: GitWrapper.create(),
+    runner: ProcessRunner.create(),
+});
+for (const check of report.checks) {
+    console.log(check.passed ? `  ok    ${check.name}` : `  FAIL  ${check.name}: ${check.reason}`);
+}
+if (subcommand === 'preflight') {
+    process.exit(report.checks.every((check) => check.passed) ? 0 : 1);
+}
+const result = await cut({
+    version,
+    changelog,
+    report,
+    git: GitWrapper.create(),
+    npm: NpmWrapper.create(),
+    gh: GhWrapper.create(),
+    narrate,
+});
+if ('stopped' in result) {
+    console.error(`stopped: ${result.stopped}`);
+    process.exit(1);
+}
+process.exit(0);

package/dist/infrastructure/gh.js

@@ -0,0 +1,234 @@
+import { execFile } from 'node:child_process';
+const bucketFor = (check) => !check.concluded ? 'pending' : check.passed ? 'pass' : 'fail';
+// Wraps the GitHub surface the CLI needs, behind the gh cli. Real and null share every
+// line above the bottom layer: create() shells out to gh, createNull() answers gh-shaped
+// output from configured state and never talks to GitHub; the real side is proven by a
+// real release rather than a faked GitHub. checkRounds configures successive answers to
+// checks(): each call takes the next round, and the last round repeats, so a test can
+// walk a PR from pending to concluded.
+export class GhWrapper {
+    static create({ cwd = process.cwd() } = {}) {
+        return new GhWrapper((args) => new Promise((resolve) => {
+            execFile('gh', args, { cwd }, (error, stdout, stderr) => {
+                const exitCode = error === null ? 0 : 1;
+                resolve({ exitCode, stdout, stderr });
+            });
+        }));
+    }
+    static createNull({ prNumber = 1, checkRounds = [[]], waitingRunRounds = [undefined], runRounds = [{ concluded: true, passed: true, url: 'https://github.com/nulled/nulled' }], } = {}) {
+        let round = 0;
+        let runRound = 0;
+        let waitingRound = 0;
+        return new GhWrapper((args) => {
+            if (args[0] === 'run' && args[1] === 'view') {
+                const index = Math.min(runRound, runRounds.length - 1);
+                runRound += 1;
+                const state = runRounds[index] ?? { concluded: true, passed: true, url: '' };
+                const row = {
+                    status: state.concluded ? 'completed' : 'in_progress',
+                    conclusion: !state.concluded ? '' : state.passed ? 'success' : 'failure',
+                    url: state.url,
+                };
+                return Promise.resolve({ exitCode: 0, stdout: `${JSON.stringify(row)}\n`, stderr: '' });
+            }
+            if (args[0] === 'run' && args[1] === 'list') {
+                const index = Math.min(waitingRound, waitingRunRounds.length - 1);
+                waitingRound += 1;
+                const waiting = waitingRunRounds[index];
+                const rows = waiting === undefined ? [] : [{ databaseId: waiting }];
+                return Promise.resolve({ exitCode: 0, stdout: `${JSON.stringify(rows)}\n`, stderr: '' });
+            }
+            if (args[0] === 'api' && args[1]?.endsWith('pending_deployments') === true) {
+                const rows = [{ environment: { id: 1, name: 'release' } }];
+                return Promise.resolve({ exitCode: 0, stdout: `${JSON.stringify(rows)}\n`, stderr: '' });
+            }
+            if (args[0] === 'pr' && args[1] === 'create') {
+                return Promise.resolve({
+                    exitCode: 0,
+                    stdout: `https://github.com/nulled/nulled/pull/${prNumber}\n`,
+                    stderr: '',
+                });
+            }
+            if (args[0] === 'pr' && args[1] === 'checks') {
+                const index = Math.min(round, checkRounds.length - 1);
+                round += 1;
+                const rows = (checkRounds[index] ?? []).map((check) => ({
+                    name: check.name,
+                    bucket: bucketFor(check),
+                }));
+                if (rows.length === 0) {
+                    return Promise.resolve({
+                        exitCode: 1,
+                        stdout: '',
+                        stderr: "no checks reported on the 'release/v0.5.0' branch",
+                    });
+                }
+                return Promise.resolve({ exitCode: 0, stdout: `${JSON.stringify(rows)}\n`, stderr: '' });
+            }
+            return Promise.resolve({ exitCode: 0, stdout: '', stderr: '' });
+        });
+    }
+    runGh;
+    constructor(runGh) {
+        this.runGh = runGh;
+    }
+    openTrackers = [];
+    trackOpens() {
+        const tracker = [];
+        this.openTrackers.push(tracker);
+        return { data: tracker };
+    }
+    async openPr(options) {
+        const result = await this.runGh([
+            'pr',
+            'create',
+            '--title',
+            options.title,
+            '--body',
+            options.body,
+        ]);
+        if (result.exitCode !== 0) {
+            throw new Error(`gh pr create failed:\n${result.stderr}`);
+        }
+        const url = result.stdout.match(/\/pull\/(\d+)/);
+        if (url === null) {
+            throw new Error(`gh pr create answered no pr url:\n${result.stdout}`);
+        }
+        for (const tracker of this.openTrackers) {
+            tracker.push(options);
+        }
+        return { number: Number(url[1]) };
+    }
+    async waitingRun(workflow) {
+        const result = await this.runGh([
+            'run',
+            'list',
+            '--workflow',
+            workflow,
+            '--status',
+            'waiting',
+            '--json',
+            'databaseId',
+            '--limit',
+            '1',
+        ]);
+        if (result.exitCode !== 0) {
+            throw new Error(`gh run list failed:\n${result.stderr}`);
+        }
+        const rows = JSON.parse(result.stdout);
+        const first = rows[0];
+        return first === undefined ? undefined : { id: first.databaseId };
+    }
+    approvalTrackers = [];
+    trackApprovals() {
+        const tracker = [];
+        this.approvalTrackers.push(tracker);
+        return { data: tracker };
+    }
+    // The gate approval is the one raw API call in the flow: the pending deployments
+    // endpoint wants the run's waiting environment ids back, marked approved.
+    async approveRun(runId) {
+        const path = `repos/{owner}/{repo}/actions/runs/${runId}/pending_deployments`;
+        const pending = await this.runGh(['api', path]);
+        if (pending.exitCode !== 0) {
+            throw new Error(`gh api ${path} failed:\n${pending.stderr}`);
+        }
+        const rows = JSON.parse(pending.stdout);
+        const approval = await this.runGh([
+            'api',
+            '-X',
+            'POST',
+            path,
+            ...rows.flatMap((row) => ['-F', `environment_ids[]=${row.environment.id}`]),
+            '-f',
+            'state=approved',
+            '-f',
+            'comment=approved by ekohacks release ship',
+        ]);
+        if (approval.exitCode !== 0) {
+            throw new Error(`gh api -X POST ${path} failed:\n${approval.stderr}`);
+        }
+        for (const tracker of this.approvalTrackers) {
+            tracker.push(runId);
+        }
+    }
+    async run(runId) {
+        const result = await this.runGh([
+            'run',
+            'view',
+            String(runId),
+            '--json',
+            'status,conclusion,url',
+        ]);
+        if (result.exitCode !== 0) {
+            throw new Error(`gh run view ${runId} failed:\n${result.stderr}`);
+        }
+        const row = JSON.parse(result.stdout);
+        return {
+            concluded: row.status === 'completed',
+            passed: row.conclusion === 'success',
+            url: row.url,
+        };
+    }
+    // gh pr checks exits non-zero while checks are pending or failing, so the answer is in
+    // stdout, not the exit code. Right after a PR opens it exits non-zero with "no checks
+    // reported" until CI registers — that is an empty round, not an error.
+    async checks(prNumber) {
+        const result = await this.runGh(['pr', 'checks', String(prNumber), '--json', 'name,bucket']);
+        if (result.stdout.trim() === '') {
+            if (result.stderr.includes('no checks reported')) {
+                return [];
+            }
+            if (result.exitCode !== 0) {
+                throw new Error(`gh pr checks ${prNumber} failed:\n${result.stderr}`);
+            }
+            return [];
+        }
+        const rows = JSON.parse(result.stdout);
+        return rows.map((row) => ({
+            name: row.name,
+            concluded: row.bucket !== 'pending',
+            passed: row.bucket === 'pass' || row.bucket === 'skipping',
+        }));
+    }
+    releaseTrackers = [];
+    trackReleases() {
+        const tracker = [];
+        this.releaseTrackers.push(tracker);
+        return { data: tracker };
+    }
+    async createRelease(options) {
+        const result = await this.runGh([
+            'release',
+            'create',
+            options.tag,
+            '--target',
+            'main',
+            '--title',
+            options.title,
+            '--notes',
+            options.notes,
+        ]);
+        if (result.exitCode !== 0) {
+            throw new Error(`gh release create ${options.tag} failed:\n${result.stderr}`);
+        }
+        for (const tracker of this.releaseTrackers) {
+            tracker.push(options);
+        }
+    }
+    mergeTrackers = [];
+    trackMerges() {
+        const tracker = [];
+        this.mergeTrackers.push(tracker);
+        return { data: tracker };
+    }
+    async mergePr(prNumber) {
+        const result = await this.runGh(['pr', 'merge', String(prNumber), '--squash']);
+        if (result.exitCode !== 0) {
+            throw new Error(`gh pr merge ${prNumber} failed:\n${result.stderr}`);
+        }
+        for (const tracker of this.mergeTrackers) {
+            tracker.push(prNumber);
+        }
+    }
+}

package/dist/infrastructure/git.js

@@ -0,0 +1,70 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+// Wraps the local git surface the CLI needs. Real and null share every line above the
+// bottom layer: create() shells out to git, createNull() answers from configured output,
+// so the null behaves exactly like the real thing without running git.
+export class GitWrapper {
+    static create({ cwd = process.cwd() } = {}) {
+        return new GitWrapper(async (args) => {
+            const { stdout } = await execFileAsync('git', args, { cwd });
+            return stdout;
+        });
+    }
+    static createNull({ branch = 'main', dirty = false, behindOrigin = false, existingBranches = [], } = {}) {
+        const outputs = {
+            'rev-parse --abbrev-ref HEAD': `${branch}\n`,
+            'status --porcelain': dirty ? ' M some-file.ts\n' : '',
+            'rev-parse main': behindOrigin ? 'local\n' : 'shared\n',
+            'rev-parse origin/main': 'shared\n',
+        };
+        for (const existing of existingBranches) {
+            outputs[`branch --list ${existing}`] = `  ${existing}\n`;
+        }
+        return new GitWrapper((args) => Promise.resolve(outputs[args.join(' ')] ?? ''));
+    }
+    runGit;
+    constructor(runGit) {
+        this.runGit = runGit;
+    }
+    async currentBranch() {
+        return (await this.runGit(['rev-parse', '--abbrev-ref', 'HEAD'])).trim();
+    }
+    async workingTreeClean() {
+        return (await this.runGit(['status', '--porcelain'])).trim() === '';
+    }
+    // git branch --list exits 0 whether or not the branch exists, so this never trips the
+    // real runner's throw-on-nonzero; existence is in the output.
+    async branchExists(branch) {
+        return (await this.runGit(['branch', '--list', branch])).trim() !== '';
+    }
+    async mainInSyncWithOrigin() {
+        await this.runGit(['fetch', 'origin', 'main']);
+        const local = (await this.runGit(['rev-parse', 'main'])).trim();
+        const remote = (await this.runGit(['rev-parse', 'origin/main'])).trim();
+        return local === remote;
+    }
+    actionTrackers = [];
+    trackActions() {
+        const tracker = [];
+        this.actionTrackers.push(tracker);
+        return { data: tracker };
+    }
+    record(action) {
+        for (const tracker of this.actionTrackers) {
+            tracker.push(action);
+        }
+    }
+    async createBranch(branch) {
+        await this.runGit(['switch', '-c', branch]);
+        this.record({ action: 'createBranch', branch });
+    }
+    async commitAll(message) {
+        await this.runGit(['commit', '--all', '--message', message]);
+        this.record({ action: 'commitAll', message });
+    }
+    async push() {
+        await this.runGit(['push', '--set-upstream', 'origin', 'HEAD']);
+        this.record({ action: 'push' });
+    }
+}

package/dist/infrastructure/npm.js

@@ -0,0 +1,60 @@
+import { execFile } from 'node:child_process';
+// Wraps the npm registry surface the CLI needs. Real and null share every line above the
+// bottom layer: create() shells out to npm, createNull() answers from a configured map of
+// package name to published version, so the null never touches the network.
+export class NpmWrapper {
+    static create({ cwd = process.cwd() } = {}) {
+        return new NpmWrapper((args) => new Promise((resolve) => {
+            execFile('npm', args, { cwd }, (error, stdout, stderr) => {
+                const exitCode = error === null ? 0 : 1;
+                resolve({ exitCode, stdout, stderr });
+            });
+        }));
+    }
+    static createNull({ publishedVersions = {}, } = {}) {
+        const rounds = {};
+        return new NpmWrapper((args) => {
+            if (args[0] === 'version') {
+                return Promise.resolve({ exitCode: 0, stdout: `v${args[1]}\n`, stderr: '' });
+            }
+            const pkg = args[1] ?? '';
+            const configured = publishedVersions[pkg];
+            if (configured === undefined) {
+                return Promise.resolve({ exitCode: 1, stdout: '', stderr: `npm error code E404 ${pkg}` });
+            }
+            const list = Array.isArray(configured) ? configured : [configured];
+            const index = Math.min(rounds[pkg] ?? 0, list.length - 1);
+            rounds[pkg] = index + 1;
+            return Promise.resolve({ exitCode: 0, stdout: `${list[index]}\n`, stderr: '' });
+        });
+    }
+    runNpm;
+    constructor(runNpm) {
+        this.runNpm = runNpm;
+    }
+    bumpTrackers = [];
+    trackBumps() {
+        const tracker = [];
+        this.bumpTrackers.push(tracker);
+        return { data: tracker };
+    }
+    async bumpVersion(version) {
+        const result = await this.runNpm(['version', version, '--no-git-tag-version']);
+        if (result.exitCode !== 0) {
+            throw new Error(`npm version ${version} failed:\n${result.stderr}`);
+        }
+        for (const tracker of this.bumpTrackers) {
+            tracker.push(version);
+        }
+    }
+    async publishedVersion(pkg) {
+        const result = await this.runNpm(['view', pkg, 'version']);
+        if (result.exitCode === 0) {
+            return result.stdout.trim();
+        }
+        if (result.stderr.includes('E404')) {
+            return undefined;
+        }
+        throw new Error(`npm view ${pkg} failed:\n${result.stderr}`);
+    }
+}

package/dist/infrastructure/process.js

@@ -0,0 +1,23 @@
+import { exec } from 'node:child_process';
+// Wraps the child processes the CLI shells out to. create() runs the command through a
+// real shell and answers its exit code; the null answers configured exit codes per
+// command, exit 0 when unconfigured, and never spawns anything.
+export class ProcessRunner {
+    static create({ cwd = process.cwd() } = {}) {
+        return new ProcessRunner((command) => new Promise((resolve) => {
+            const child = exec(command, { cwd });
+            child.on('error', () => resolve({ exitCode: 1 }));
+            child.on('exit', (code) => resolve({ exitCode: code ?? 1 }));
+        }));
+    }
+    static createNull({ commands = {} } = {}) {
+        return new ProcessRunner((command) => Promise.resolve(commands[command] ?? { exitCode: 0 }));
+    }
+    runCommand;
+    constructor(runCommand) {
+        this.runCommand = runCommand;
+    }
+    run(command) {
+        return this.runCommand(command);
+    }
+}

package/dist/logic/changelog.js

@@ -0,0 +1,15 @@
+// Finds the changelog entry for a version: the lines between its `## X.Y.Z` heading and
+// the next `## ` heading, without the heading itself. The heading is dropped because the
+// entry's consumers already carry the version: a GitHub Release titles itself vX.Y.Z, so
+// its notes start straight at the entry body.
+export const changelogEntryFor = (log, version) => {
+    const lines = log.split('\n');
+    const heading = lines.indexOf(`## ${version}`);
+    if (heading === -1) {
+        return undefined;
+    }
+    const body = lines.slice(heading + 1);
+    const nextHeading = body.findIndex((line) => line.startsWith('## '));
+    const entry = nextHeading === -1 ? body : body.slice(0, nextHeading);
+    return entry.join('\n').trim();
+};

package/dist/logic/cut.js

@@ -0,0 +1,47 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { changelogEntryFor } from './changelog.js';
+import { GhWrapper } from '../infrastructure/gh.js';
+import { GitWrapper } from '../infrastructure/git.js';
+import { NpmWrapper } from '../infrastructure/npm.js';
+// The mechanical middle of RELEASING.md as a policy: branch, bump, commit, push, open the
+// release PR, wait for CI, merge on green. It refuses to start unless preflight passed,
+// and every stop names the reason so a human can pick up by hand. The caller supplies the
+// wrappers and hears each step through narrate.
+export const cut = async ({ version, changelog, report, git, npm, gh, narrate, confirm = () => Promise.resolve(true), pollDelayMs = 15_000, }) => {
+    const failed = report.checks.filter((check) => !check.passed);
+    if (failed.length > 0) {
+        return { stopped: `preflight failed: ${failed.map((check) => check.name).join(', ')}` };
+    }
+    const branch = `release/v${version}`;
+    if (await git.branchExists(branch)) {
+        return { stopped: `branch ${branch} already exists from an earlier cut` };
+    }
+    await git.createBranch(branch);
+    narrate(`branched ${branch}`);
+    await npm.bumpVersion(version);
+    narrate(`bumped to ${version}`);
+    const message = `chore: release ${version}`;
+    await git.commitAll(message);
+    narrate(`committed ${message}`);
+    await git.push();
+    narrate('pushed');
+    const body = changelogEntryFor(changelog, version) ?? '';
+    const { number } = await gh.openPr({ title: message, body });
+    narrate(`opened pr #${number}`);
+    let checks = await gh.checks(number);
+    while (checks.length === 0 || checks.some((check) => !check.concluded)) {
+        narrate('waiting for checks');
+        await delay(pollDelayMs);
+        checks = await gh.checks(number);
+    }
+    const failing = checks.find((check) => !check.passed);
+    if (failing !== undefined) {
+        return { stopped: `check ${failing.name} failed` };
+    }
+    if (!(await confirm(`merge pr #${number}?`))) {
+        return { stopped: 'merge not approved' };
+    }
+    await gh.mergePr(number);
+    narrate(`merged pr #${number}`);
+    return { merged: number };
+};

package/dist/logic/preflight.js

@@ -0,0 +1,64 @@
+import { changelogEntryFor } from './changelog.js';
+import { GitWrapper } from '../infrastructure/git.js';
+import { NpmWrapper } from '../infrastructure/npm.js';
+import { ProcessRunner } from '../infrastructure/process.js';
+const SMOKE_COMMAND = 'npm run test:package';
+// The "Before cutting" checklist from RELEASING.md as a policy: each check answers with
+// its name and, when it fails, the reason a human needs to fix it. The caller supplies
+// file contents and wrappers; the policy only judges.
+export const preflight = async ({ version, changelog, npm, pkg, git, lockfile, runner, }) => {
+    const entry = changelogEntryFor(changelog, version);
+    const changelogCheck = entry === undefined
+        ? {
+            name: 'changelog entry',
+            passed: false,
+            reason: `no ## ${version} heading in the changelog`,
+        }
+        : { name: 'changelog entry', passed: true };
+    const published = await npm.publishedVersion(pkg);
+    const versionCheck = published === version
+        ? { name: 'version is new', passed: false, reason: `${version} is already published` }
+        : { name: 'version is new', passed: true };
+    const branch = await git.currentBranch();
+    const branchCheck = branch === 'main'
+        ? { name: 'on main', passed: true }
+        : { name: 'on main', passed: false, reason: `on ${branch}, not main` };
+    const inSync = await git.mainInSyncWithOrigin();
+    const syncCheck = inSync
+        ? { name: 'in sync with origin', passed: true }
+        : {
+            name: 'in sync with origin',
+            passed: false,
+            reason: 'main does not match origin/main',
+        };
+    const treeClean = await git.workingTreeClean();
+    const treeCheck = treeClean
+        ? { name: 'clean working tree', passed: true }
+        : {
+            name: 'clean working tree',
+            passed: false,
+            reason: 'uncommitted changes in the working tree',
+        };
+    const lockfileCheck = lockfile.includes('npmmirror')
+        ? {
+            name: 'lockfile registry',
+            passed: false,
+            reason: 'lockfile resolves packages outside registry.npmjs.org',
+        }
+        : { name: 'lockfile registry', passed: true };
+    const smoke = await runner.run(SMOKE_COMMAND);
+    const smokeCheck = smoke.exitCode === 0
+        ? { name: 'package smoke', passed: true }
+        : { name: 'package smoke', passed: false, reason: `${SMOKE_COMMAND} failed` };
+    return {
+        checks: [
+            changelogCheck,
+            versionCheck,
+            branchCheck,
+            syncCheck,
+            treeCheck,
+            lockfileCheck,
+            smokeCheck,
+        ],
+    };
+};

package/dist/logic/release.js

@@ -0,0 +1,45 @@
+import { cut } from './cut.js';
+import { preflight } from './preflight.js';
+import { ship } from './ship.js';
+import { GhWrapper } from '../infrastructure/gh.js';
+import { GitWrapper } from '../infrastructure/git.js';
+import { NpmWrapper } from '../infrastructure/npm.js';
+import { ProcessRunner } from '../infrastructure/process.js';
+// The whole of RELEASING.md as one command: preflight, cut, ship in order, stopping at
+// the first failure with that stage's own reason. No stage's logic lives here — this
+// policy only composes the three and decides which pauses --yes may skip: the merge and
+// the Release. The gate always asks.
+export const release = async ({ version, changelog, lockfile, pkg, git, npm, gh, runner, confirm, narrate, yes = false, pollDelayMs, findRunAttempts, registryAttempts, }) => {
+    const report = await preflight({ version, changelog, npm, pkg, git, lockfile, runner });
+    for (const check of report.checks) {
+        narrate(check.passed ? `ok ${check.name}` : `FAIL ${check.name}: ${check.reason}`);
+    }
+    const skippable = yes ? () => Promise.resolve(true) : confirm;
+    const cutResult = await cut({
+        version,
+        changelog,
+        report,
+        git,
+        npm,
+        gh,
+        narrate,
+        confirm: skippable,
+        pollDelayMs,
+    });
+    if ('stopped' in cutResult) {
+        return cutResult;
+    }
+    return ship({
+        version,
+        changelog,
+        pkg,
+        gh,
+        npm,
+        confirm,
+        confirmRelease: skippable,
+        narrate,
+        pollDelayMs,
+        findRunAttempts,
+        registryAttempts,
+    });
+};

package/dist/logic/ship.js

@@ -0,0 +1,52 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { changelogEntryFor } from './changelog.js';
+import { GhWrapper } from '../infrastructure/gh.js';
+import { NpmWrapper } from '../infrastructure/npm.js';
+// The tail of RELEASING.md as a policy: cut the GitHub Release, approve the publish
+// gate, follow the run to green, and only report success once the registry serves the
+// version. The one human decision stays human: the gate is never approved without the
+// confirm answering yes.
+export const ship = async ({ version, changelog, pkg, gh, npm, confirm, confirmRelease = () => Promise.resolve(true), narrate, pollDelayMs = 15_000, findRunAttempts = 8, registryAttempts = 20, workflow = 'publish.yml', }) => {
+    const tag = `v${version}`;
+    if (!(await confirmRelease(`cut release ${tag}?`))) {
+        return { stopped: 'release not approved' };
+    }
+    const notes = changelogEntryFor(changelog, version) ?? '';
+    await gh.createRelease({ tag, title: tag, notes });
+    narrate(`release ${tag} cut`);
+    // The run takes a few seconds to appear after the release event, so a miss here is
+    // usually the race, not a missing workflow: ask again briefly before giving up.
+    let waiting = await gh.waitingRun(workflow);
+    for (let attempt = 1; waiting === undefined && attempt < findRunAttempts; attempt += 1) {
+        narrate('waiting for the publish run to appear');
+        await delay(pollDelayMs);
+        waiting = await gh.waitingRun(workflow);
+    }
+    if (waiting === undefined) {
+        return { stopped: 'no waiting publish run' };
+    }
+    if (!(await confirm(`approve the release gate for run #${waiting.id}?`))) {
+        return { stopped: 'gate not approved' };
+    }
+    await gh.approveRun(waiting.id);
+    narrate(`gate approved for run #${waiting.id}`);
+    let state = await gh.run(waiting.id);
+    while (!state.concluded) {
+        narrate('waiting for the publish run');
+        await delay(pollDelayMs);
+        state = await gh.run(waiting.id);
+    }
+    if (!state.passed) {
+        return { stopped: `publish run failed: ${state.url}` };
+    }
+    narrate('publish run green');
+    for (let attempt = 0; attempt < registryAttempts; attempt += 1) {
+        if ((await npm.publishedVersion(pkg)) === version) {
+            narrate(`registry serves ${pkg}@${version}`);
+            return { shipped: version };
+        }
+        narrate('waiting for the registry');
+        await delay(pollDelayMs);
+    }
+    return { stopped: `registry never served ${pkg}@${version}` };
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "ekohacks",
+  "version": "0.1.0",
+  "description": "The EkoHacks CLI: our everyday operations, automated one small command at a time.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ekohacks/cli.git"
+  },
+  "license": "MIT",
+  "author": "ekohacks",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest --watch",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepare": "husky",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm test",
+    "test:changed": "vitest run --changed origin/main",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:package": "scripts/test-package.sh"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.2.1",
+    "@commitlint/config-conventional": "^21.2.0",
+    "@types/node": "^26.1.1",
+    "husky": "^9.1.7",
+    "prettier": "^3.9.5",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "bin": {
+    "ekohacks": "dist/cli.js"
+  }
+}