soja-cli 1.4.0

package/dist/git/cli-git.js

@@ -0,0 +1,363 @@
+import { spawn } from 'node:child_process';
+import { diagnose } from './diagnose.js';
+import { terminalSafe } from '../utils/text.js';
+import { GitError, } from './types.js';
+const FIELD = '\x1f';
+const RECORD = '\x1e';
+const LOG_FORMAT = `--format=%H${FIELD}%h${FIELD}%s${FIELD}%an${FIELD}%at${RECORD}`;
+/** Never block waiting for credentials unless running interactively. */
+const NON_INTERACTIVE = {
+    GIT_TERMINAL_PROMPT: '0',
+    GCM_INTERACTIVE: 'never',
+    GH_PROMPT_DISABLED: '1',
+};
+/**
+ * GitClient backed by the `git` and `gh` executables. Arguments are passed as
+ * an array (no shell). Output is forced to English so failures can be
+ * recognized; changing commands stream to the live console.
+ */
+export class CliGit {
+    console;
+    binaries;
+    constructor(console, binaries = { git: 'git', gh: 'gh' }) {
+        this.console = console;
+        this.binaries = binaries;
+    }
+    // ── Read-only ───────────────────────────────────────────────────────────
+    async repositoryRoot(path) {
+        const result = await this.git(['-C', path, 'rev-parse', '--show-toplevel'], { allowFailure: true });
+        return result.code === 0 ? result.stdout.trim() : null;
+    }
+    async currentBranch(root) {
+        const result = await this.git(['-C', root, 'symbolic-ref', '--quiet', '--short', 'HEAD'], { allowFailure: true });
+        return result.code === 0 ? result.stdout.trim() : null;
+    }
+    async branchExists(root, branch) {
+        const result = await this.git(['-C', root, 'show-ref', '--verify', '--quiet', `refs/heads/${branch}`], {
+            allowFailure: true,
+        });
+        return result.code === 0;
+    }
+    async isValidBranchName(root, branch) {
+        const result = await this.git(['-C', root, 'check-ref-format', '--branch', branch], { allowFailure: true });
+        return result.code === 0;
+    }
+    async uncommittedChanges(root) {
+        return (await this.changedFiles(root)).length;
+    }
+    async commitsOnlyOn(root, branch, limit) {
+        // With --branches, --exclude patterns are matched without the refs/heads/ prefix.
+        const result = await this.git(['-C', root, 'log', LOG_FORMAT, `--max-count=${limit}`, `refs/heads/${branch}`, '--not', `--exclude=${branch}`, '--branches'], { allowFailure: true });
+        return result.code === 0 ? parseLog(result.stdout) : [];
+    }
+    async commitsMatching(root, pattern, limit) {
+        const result = await this.git(['-C', root, 'log', LOG_FORMAT, `--max-count=${limit}`, '--branches', '--regexp-ignore-case', '--extended-regexp', `--grep=${pattern}`], { allowFailure: true });
+        return result.code === 0 ? parseLog(result.stdout) : [];
+    }
+    async originUrl(root) {
+        const result = await this.git(['-C', root, 'remote', 'get-url', 'origin'], { allowFailure: true });
+        return result.code === 0 ? result.stdout.trim() || null : null;
+    }
+    async changedFiles(root) {
+        const result = await this.git(['-C', root, 'status', '--porcelain=v1', '-z', '--untracked-files=all']);
+        return parseStatus(result.stdout);
+    }
+    async isMerging(root) {
+        const result = await this.git(['-C', root, 'rev-parse', '--quiet', '--verify', 'MERGE_HEAD'], { allowFailure: true });
+        return result.code === 0;
+    }
+    async isMergedInto(root, branch, into) {
+        const result = await this.git(['-C', root, 'merge-base', '--is-ancestor', `refs/heads/${branch}`, `refs/heads/${into}`], {
+            allowFailure: true,
+        });
+        return result.code === 0;
+    }
+    async resolveCommit(root, ref) {
+        const result = await this.git(['-C', root, 'rev-parse', '--quiet', '--verify', `${ref}^{commit}`], { allowFailure: true });
+        return result.code === 0 ? result.stdout.trim() : null;
+    }
+    async countCommits(root, from, to) {
+        const result = await this.git(['-C', root, 'rev-list', '--count', `${from}..${to}`], { allowFailure: true });
+        return result.code === 0 ? Number(result.stdout.trim()) || 0 : 0;
+    }
+    async recentCommits(root, branch, options) {
+        const range = options.since ? `${options.since}..refs/heads/${branch}` : `refs/heads/${branch}`;
+        const result = await this.git(['-C', root, 'log', `--format=%H${FIELD}%P${FIELD}%B${RECORD}`, `--max-count=${options.limit}`, range], { allowFailure: true });
+        if (result.code !== 0)
+            return [];
+        return result.stdout
+            .split(RECORD)
+            .map((record) => record.replace(/^\n+/, ''))
+            .filter((record) => record.trim())
+            .flatMap((record) => {
+            const [hash, parents, message] = record.split(FIELD);
+            return hash ? [{ hash: hash.trim(), parents: (parents ?? '').split(' ').filter(Boolean), message: (message ?? '').trim() }] : [];
+        });
+    }
+    async defaultBranch(root) {
+        const head = await this.git(['-C', root, 'symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], {
+            allowFailure: true,
+        });
+        const remoteDefault = head.code === 0 ? head.stdout.trim().replace(/^origin\//, '') : null;
+        for (const candidate of [remoteDefault, 'main', 'master']) {
+            if (candidate && (await this.branchExists(root, candidate)))
+                return candidate;
+        }
+        return null;
+    }
+    // ── Changing the repository (streamed) ─────────────────────────────────
+    async createBranch(root, branch, from) {
+        await this.git(['-C', root, 'switch', '--create', branch, ...(from ? [from] : [])], {
+            stream: true,
+            failure: `Could not create ${branch}.`,
+        });
+    }
+    async switchBranch(root, branch) {
+        await this.git(['-C', root, 'switch', branch], { stream: true, failure: `Could not switch to ${branch}.` });
+    }
+    async commit(root, message, files) {
+        // `add -A` records new, modified and deleted files. The old side of a rename
+        // no longer exists anywhere, so it only goes to the commit pathspec, where
+        // `--only` includes its removal and ignores anything else already staged.
+        const current = files.map((file) => file.path);
+        const all = [...new Set(files.flatMap((file) => (file.previousPath ? [file.path, file.previousPath] : [file.path])))];
+        await this.git(['-C', root, 'add', '--all', '--', ...current], { stream: true, failure: 'Could not stage the files.' });
+        await this.git(['-C', root, 'commit', '--only', '-m', message, '--', ...all], {
+            stream: true,
+            failure: 'Could not commit.',
+        });
+        return (await this.git(['-C', root, 'rev-parse', 'HEAD'])).stdout.trim();
+    }
+    async merge(root, branch, into, message) {
+        await this.switchBranch(root, into);
+        await this.git(['-C', root, 'merge', '--no-ff', '--no-edit', '-m', message, branch], {
+            stream: true,
+            failure: `Could not merge ${branch} into ${into}.`,
+        });
+        return (await this.git(['-C', root, 'rev-parse', 'HEAD'])).stdout.trim();
+    }
+    async abortMerge(root) {
+        await this.git(['-C', root, 'merge', '--abort'], { stream: true, failure: 'Could not abort the merge.' });
+    }
+    async deleteBranch(root, branch, force) {
+        await this.git(['-C', root, 'branch', force ? '-D' : '-d', branch], {
+            stream: true,
+            failure: `Could not delete ${branch}.`,
+        });
+    }
+    async push(root, branch, options = {}) {
+        const args = ['-C', root, 'push', '--set-upstream', 'origin', branch];
+        if (options.interactive) {
+            await this.attached(this.binaries.git, args, `Could not push ${branch}.`);
+            return;
+        }
+        await this.git(args, { stream: true, failure: `Could not push ${branch}.` });
+    }
+    async createPullRequest(root, request, options = {}) {
+        const args = ['pr', 'create', '--base', request.base, '--head', request.head, '--title', request.title, '--body', request.body];
+        if (options.interactive) {
+            await this.attached(this.binaries.gh, args, 'Could not open the pull request.', root);
+            const view = await this.run(this.binaries.gh, ['pr', 'view', request.head, '--json', 'url', '--jq', '.url'], {
+                cwd: root,
+                allowFailure: true,
+            });
+            return view.stdout.trim();
+        }
+        const result = await this.run(this.binaries.gh, args, { cwd: root, stream: true, failure: 'Could not open the pull request.' });
+        return result.stdout.match(/https?:\/\/\S+/)?.[0] ?? result.stdout.trim();
+    }
+    async loginGitHub() {
+        await this.attached(this.binaries.gh, ['auth', 'login'], 'GitHub login did not finish.');
+    }
+    async pullRequestFor(root, branch) {
+        // `gh pr view <branch>` only finds open ones; the list also finds merged and closed.
+        const result = await this.run(this.binaries.gh, ['pr', 'list', '--head', branch, '--state', 'all', '--limit', '1', '--json', PR_FIELDS], { cwd: root, failure: 'Could not read the pull request from GitHub.' });
+        return parsePullRequests(result.stdout)[0] ?? null;
+    }
+    async pullRequests(root, limit) {
+        const result = await this.run(this.binaries.gh, ['pr', 'list', '--state', 'all', '--limit', String(limit), '--json', PR_FIELDS], { cwd: root, failure: 'Could not read pull requests from GitHub.' });
+        return parsePullRequests(result.stdout);
+    }
+    async mergePullRequest(root, number, options) {
+        const args = ['pr', 'merge', String(number), '--merge', ...(options.deleteBranch ? ['--delete-branch'] : [])];
+        await this.run(this.binaries.gh, args, { cwd: root, stream: true, failure: `Could not merge pull request #${number}.` });
+    }
+    // ── Process plumbing ────────────────────────────────────────────────────
+    git(args, options = {}) {
+        return this.run(this.binaries.git, args, options);
+    }
+    run(binary, args, options = {}) {
+        if (options.stream)
+            this.console?.write('command', `$ ${describeCommand(binary, args)}`);
+        return new Promise((resolve, reject) => {
+            let stdout = '';
+            let stderr = '';
+            const child = spawn(binary, args, {
+                cwd: options.cwd,
+                env: { ...process.env, ...NON_INTERACTIVE, LC_ALL: 'C', LANG: 'C', ...options.env },
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            const timer = setTimeout(() => child.kill('SIGTERM'), 120_000);
+            child.stdout.on('data', (chunk) => {
+                const text = chunk.toString();
+                stdout += text;
+                if (options.stream)
+                    this.console?.write('stdout', text);
+            });
+            child.stderr.on('data', (chunk) => {
+                const text = chunk.toString();
+                stderr += text;
+                if (options.stream)
+                    this.console?.write('stderr', text);
+            });
+            child.on('error', (error) => {
+                clearTimeout(timer);
+                reject(missingBinary(binary, error));
+            });
+            child.on('close', (exitCode) => {
+                clearTimeout(timer);
+                const code = exitCode ?? 1;
+                if (code !== 0 && !options.allowFailure) {
+                    const found = diagnose(`${stderr}\n${stdout}`, options.failure ?? `${binary} failed.`);
+                    if (options.stream)
+                        this.console?.write('error', found.message);
+                    reject(new GitError(found.message, { code: found.code, suggestions: found.suggestions }));
+                    return;
+                }
+                resolve({ code, stdout, stderr });
+            });
+        });
+    }
+    /**
+     * Runs attached to the real terminal, so Git, ssh or gh can prompt for
+     * credentials. Output goes straight to the terminal, not to the console.
+     */
+    attached(binary, args, failure, cwd) {
+        this.console?.write('command', `$ ${describeCommand(binary, args)}  (interactive)`);
+        return new Promise((resolve, reject) => {
+            const child = spawn(binary, args, { cwd, stdio: 'inherit', env: process.env });
+            child.on('error', (error) => reject(missingBinary(binary, error)));
+            child.on('close', (code) => {
+                if (code === 0) {
+                    this.console?.write('info', 'Finished in the terminal.');
+                    resolve();
+                }
+                else {
+                    this.console?.write('error', `${failure} (exit ${code ?? 'signal'})`);
+                    reject(new GitError(failure, { suggestions: ['Check the messages printed in the terminal.'] }));
+                }
+            });
+        });
+    }
+}
+/** `git -C /repo commit -m x` → `git commit -m x` (the repository is implied). */
+function describeCommand(binary, args) {
+    const shown = args.filter((_, index) => args[index] !== '-C' && args[index - 1] !== '-C');
+    return [binary.split('/').at(-1) ?? binary, ...shown.map((arg) => (/\s/.test(arg) ? JSON.stringify(arg) : arg))].join(' ');
+}
+function missingBinary(binary, error) {
+    if (error.code !== 'ENOENT')
+        return error;
+    return binary.endsWith('gh')
+        ? new GitError('The GitHub CLI (gh) is not installed.', {
+            code: 'gh_missing',
+            suggestions: ['Install it from https://cli.github.com, then run `gh auth login`.'],
+        })
+        : new GitError('Git is not installed or not on your PATH.', { code: 'not_installed', cause: error });
+}
+const KINDS = {
+    M: 'modified',
+    A: 'added',
+    D: 'deleted',
+    R: 'renamed',
+    C: 'copied',
+    T: 'typechange',
+};
+/** Parses `git status --porcelain=v1 -z`. */
+export function parseStatus(output) {
+    const entries = output.split('\0');
+    const files = [];
+    for (let index = 0; index < entries.length; index += 1) {
+        const entry = entries[index];
+        if (!entry || entry.length < 4)
+            continue;
+        const x = entry[0] ?? ' ';
+        const y = entry[1] ?? ' ';
+        const path = entry.slice(3);
+        if (x === '?' && y === '?') {
+            files.push({ path, kind: 'untracked', staged: false });
+            continue;
+        }
+        const conflicted = x === 'U' || y === 'U' || (x === 'A' && y === 'A') || (x === 'D' && y === 'D');
+        const code = x !== ' ' ? x : y;
+        const file = { path, kind: conflicted ? 'conflicted' : (KINDS[code] ?? 'modified'), staged: x !== ' ' && x !== '?' };
+        if (x === 'R' || x === 'C') {
+            // In -z mode the original path follows as its own entry.
+            const previous = entries[index + 1];
+            if (previous)
+                file.previousPath = previous;
+            index += 1;
+        }
+        files.push(file);
+    }
+    return files;
+}
+function parseLog(output) {
+    return output
+        .split(RECORD)
+        .map((record) => record.trim())
+        .filter(Boolean)
+        .flatMap((record) => {
+        const [hash, shortHash, subject, author, timestamp] = record.split(FIELD);
+        if (!hash || !shortHash || subject === undefined || !author || !timestamp)
+            return [];
+        // Commits pulled from others can carry escape sequences in their messages.
+        return [{ hash, shortHash, subject: terminalSafe(subject), author: terminalSafe(author), date: new Date(Number(timestamp) * 1000) }];
+    });
+}
+const PR_FIELDS = 'number,url,title,state,isDraft,baseRefName,headRefName,headRefOid,reviewDecision,mergeable,statusCheckRollup,mergedAt';
+const PASSED = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED']);
+const FAILED = new Set(['FAILURE', 'ERROR', 'CANCELLED', 'TIMED_OUT', 'ACTION_REQUIRED', 'STARTUP_FAILURE', 'STALE']);
+/** Parses `gh pr list --json …`. Text from GitHub is made terminal-safe (anyone can title a PR). */
+export function parsePullRequests(output) {
+    const rows = JSON.parse(output || '[]');
+    return rows.map((row) => ({
+        number: row.number,
+        url: terminalSafe(row.url),
+        title: terminalSafe(row.title),
+        state: row.state === 'MERGED' ? 'merged' : row.state === 'CLOSED' ? 'closed' : 'open',
+        draft: row.isDraft ?? false,
+        base: terminalSafe(row.baseRefName),
+        head: terminalSafe(row.headRefName),
+        headSha: row.headRefOid ?? '',
+        review: reviewState(row.reviewDecision),
+        mergeable: row.mergeable === 'MERGEABLE' ? 'mergeable' : row.mergeable === 'CONFLICTING' ? 'conflicting' : 'unknown',
+        checks: summarizeChecks(row.statusCheckRollup ?? []),
+        mergedAt: row.mergedAt ? new Date(row.mergedAt) : null,
+    }));
+}
+function reviewState(decision) {
+    if (decision === 'APPROVED')
+        return 'approved';
+    if (decision === 'CHANGES_REQUESTED')
+        return 'changes_requested';
+    if (decision === 'REVIEW_REQUIRED')
+        return 'review_required';
+    return null;
+}
+function summarizeChecks(checks) {
+    const summary = { total: checks.length, passed: 0, failed: 0, pending: 0, failing: [] };
+    for (const check of checks) {
+        // Check runs report a conclusion once completed; commit statuses report a state.
+        const outcome = check.__typename === 'StatusContext' || check.state ? check.state : check.status === 'COMPLETED' ? check.conclusion : 'PENDING';
+        if (outcome && PASSED.has(outcome))
+            summary.passed += 1;
+        else if (outcome && FAILED.has(outcome)) {
+            summary.failed += 1;
+            summary.failing.push(terminalSafe(check.name ?? check.context ?? 'check'));
+        }
+        else
+            summary.pending += 1;
+    }
+    return summary;
+}

package/dist/git/console.js

@@ -0,0 +1,37 @@
+import { terminalSafe } from '../utils/text.js';
+/**
+ * Live record of what SOJA runs in Git. Mutating commands and their output
+ * stream here line by line; the interface subscribes to show it as it happens.
+ * Keeps the last `capacity` lines in memory (never written to disk).
+ */
+export class GitConsole {
+    capacity;
+    lines = [];
+    listeners = new Set();
+    counter = 0;
+    constructor(capacity = 500) {
+        this.capacity = capacity;
+    }
+    write(kind, text) {
+        for (const part of terminalSafe(text.replace(/\r/g, '\n')).split('\n')) {
+            if (!part.trim())
+                continue;
+            this.lines.push({ id: (this.counter += 1), kind, text: part, at: new Date() });
+        }
+        if (this.lines.length > this.capacity)
+            this.lines = this.lines.slice(-this.capacity);
+        for (const listener of this.listeners)
+            listener();
+    }
+    /** Lines written after `afterId` (0 for all). */
+    since(afterId = 0) {
+        return this.lines.filter((line) => line.id > afterId);
+    }
+    get lastId() {
+        return this.counter;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+}

package/dist/git/diagnose.js

@@ -0,0 +1,145 @@
+import { terminalSafe } from '../utils/text.js';
+const RULES = [
+    {
+        test: /CONFLICT|Automatic merge failed|fix conflicts/i,
+        diagnose: () => ({
+            code: 'merge_conflict',
+            message: 'The merge has conflicts.',
+            suggestions: [
+                'Resolve the conflicted files in your editor, then `git add` them and `git commit`.',
+                'Or abort the merge to go back to how things were (SOJA: a, or `git merge --abort`).',
+            ],
+        }),
+    },
+    {
+        test: /not fully merged/i,
+        diagnose: () => ({
+            code: 'not_merged',
+            message: 'The branch has commits that are not merged anywhere.',
+            suggestions: ['Merge it first, or confirm deleting it anyway (those commits will be lost).'],
+        }),
+    },
+    {
+        test: /nothing to commit|no changes added to commit|nothing added to commit/i,
+        diagnose: () => ({ code: 'nothing_to_commit', message: 'There is nothing to commit.', suggestions: ['Change some files first.'] }),
+    },
+    {
+        test: /would be overwritten|commit your changes or stash them|Please commit or stash/i,
+        diagnose: () => ({
+            code: 'dirty_worktree',
+            message: 'You have uncommitted changes that Git would overwrite.',
+            suggestions: ['Commit them from SOJA (C), or run `git stash` and try again.'],
+        }),
+    },
+    {
+        test: /Please tell me who you are|Author identity unknown|empty ident name/i,
+        diagnose: () => ({
+            code: 'identity_unknown',
+            message: 'Git does not know who you are.',
+            suggestions: ['git config --global user.name "Your Name"', 'git config --global user.email "you@example.com"'],
+        }),
+    },
+    {
+        test: /Authentication failed|could not read Username|terminal prompts disabled|Permission denied \(publickey|Host key verification failed|invalid username or password|returned error: 403/i,
+        diagnose: () => ({
+            code: 'auth_required',
+            message: 'Git needs your credentials for the remote.',
+            suggestions: [
+                'Retry interactively: SOJA pauses so Git can ask for them (i).',
+                'Or set up an SSH key or a credential helper, e.g. `gh auth setup-git`.',
+            ],
+        }),
+    },
+    {
+        test: /Could not resolve host|unable to access|Network is unreachable|Connection timed out|Connection refused|Could not read from remote repository/i,
+        diagnose: () => ({
+            code: 'offline',
+            message: 'Could not reach the remote.',
+            suggestions: ['Check your connection. Commit, merge and branches keep working offline.'],
+        }),
+    },
+    {
+        test: /\[rejected\]|non-fast-forward|fetch first|failed to push some refs/i,
+        diagnose: () => ({
+            code: 'rejected',
+            message: 'The remote has commits you do not have.',
+            suggestions: ['Run `git pull --rebase` on this branch, then push again.'],
+        }),
+    },
+    {
+        test: /none of the git remotes configured for this repository point to a known GitHub host|no git remotes found/i,
+        diagnose: () => ({
+            code: 'not_github',
+            message: 'This repository is not on GitHub.',
+            suggestions: ['Pull requests and checks need an `origin` on GitHub. Local Git keeps working.'],
+        }),
+    },
+    {
+        test: /error connecting to|dial tcp|i\/o timeout|no such host/i,
+        diagnose: () => ({
+            code: 'offline',
+            message: 'Could not reach GitHub.',
+            suggestions: ['Check your connection. Commit, merge and branches keep working offline.'],
+        }),
+    },
+    {
+        test: /required status check|Required status checks|review is required|At least \d+ approving review|base branch policy prohibits the merge/i,
+        diagnose: () => ({
+            code: 'blocked',
+            message: 'The repository rules do not allow merging this pull request yet.',
+            suggestions: ['It needs passing checks or approvals first. See the pull request on GitHub.'],
+        }),
+    },
+    {
+        test: /cannot be cleanly created|merge conflict between base and head/i,
+        diagnose: () => ({
+            code: 'merge_conflict',
+            message: 'GitHub cannot merge this pull request: it conflicts with its base.',
+            suggestions: ['Merge the base into the branch locally, fix the conflicts, commit and push.'],
+        }),
+    },
+    {
+        test: /'origin' does not appear to be a git repository|No such remote|No configured push destination/i,
+        diagnose: () => ({
+            code: 'no_remote',
+            message: 'This repository has no `origin` remote.',
+            suggestions: ['Add one: `git remote add origin <url>`.'],
+        }),
+    },
+    {
+        test: /a pull request for branch .* already exists/i,
+        diagnose: (output) => ({
+            code: 'pr_exists',
+            message: 'A pull request for this branch already exists.',
+            suggestions: [output.match(/https?:\/\/\S+/)?.[0] ?? 'See it with `gh pr view --web`.'],
+        }),
+    },
+    {
+        test: /gh auth login|not logged in|authentication token|HTTP 401/i,
+        diagnose: () => ({
+            code: 'gh_auth',
+            message: 'The GitHub CLI is not logged in.',
+            suggestions: ['Log in now: SOJA pauses and runs `gh auth login` (i).'],
+        }),
+    },
+];
+/** Turns Git's (or gh's) output into a friendly message and next steps. */
+export function diagnose(raw, fallback) {
+    const output = terminalSafe(raw);
+    for (const rule of RULES)
+        if (rule.test.test(output))
+            return rule.diagnose(output);
+    const line = output
+        .split('\n')
+        .map((text) => text.trim())
+        .find((text) => text && !text.startsWith('hint:'));
+    const detail = line?.replace(/^(fatal|error):\s*/i, '');
+    return {
+        code: 'failed',
+        message: detail ? `${fallback} ${capitalize(detail)}` : fallback,
+        suggestions: ['See the Git log above for the full output.'],
+    };
+}
+function capitalize(text) {
+    return text.charAt(0).toUpperCase() + text.slice(1);
+}

package/dist/git/merge-evidence.js

@@ -0,0 +1,23 @@
+/**
+ * Finds the commit in a base branch that shows `branch` was merged into it,
+ * even after the branch was deleted:
+ *  - a merge commit naming the branch or the task ("Merge branch 'fix/SOJA-12-…'",
+ *    "Merge pull request #5 from you/fix/SOJA-12-…", "Merge SOJA-12: …"), or
+ *  - a GitHub squash merge ("… (SOJA-12) (#5)"), which SOJA's PR titles produce.
+ * Plain commits that merely mention the task on the base branch do not count.
+ */
+export function findMergeEvidence(commits, target) {
+    const mentionsTask = new RegExp(`${escapeRegex(target.ref)}([^0-9]|$)`, 'i');
+    for (const commit of commits) {
+        const isMerge = commit.parents.length > 1;
+        if (isMerge && (commit.message.includes(target.branch) || mentionsTask.test(commit.message)))
+            return commit.hash;
+        const subject = commit.message.split('\n')[0] ?? '';
+        if (!isMerge && /\(#\d+\)\s*$/.test(subject) && mentionsTask.test(subject))
+            return commit.hash;
+    }
+    return null;
+}
+function escapeRegex(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/git/releases.js

@@ -0,0 +1,95 @@
+import { spawn } from 'node:child_process';
+import { mkdtempSync, readdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { GitError } from './types.js';
+export class GhReleases {
+    repository;
+    gh;
+    constructor(repository, gh = 'gh') {
+        this.repository = repository;
+        this.gh = gh;
+    }
+    async latest() {
+        const output = await run(this.gh, ['release', 'view', '--repo', this.repository, '--json', 'tagName', '--jq', '.tagName']);
+        return output.trim();
+    }
+    async download(tag) {
+        const dir = mkdtempSync(join(tmpdir(), 'soja-update-'));
+        await run(this.gh, ['release', 'download', tag, '--repo', this.repository, '--pattern', 'soja-cli-*.tgz', '--dir', dir]);
+        const file = readdirSync(dir).find((name) => name.endsWith('.tgz'));
+        if (!file)
+            throw new GitError(`Release ${tag} has no package to install.`, { suggestions: ['It may still be building; try again in a few minutes.'] });
+        return join(dir, file);
+    }
+    install(packagePath) {
+        return new Promise((resolve, reject) => {
+            const child = spawn('npm', ['install', '--global', packagePath], { stdio: 'inherit' });
+            child.on('error', reject);
+            child.on('close', (code) => code === 0 ? resolve() : reject(new GitError('npm could not install the update.', { suggestions: ['Check the npm messages above (a global prefix may need permissions).'] })));
+        });
+    }
+}
+/** Public release metadata and tarballs from npm; no GitHub account is needed to update. */
+export class NpmReleases {
+    packageName;
+    constructor(packageName = 'soja-cli') {
+        this.packageName = packageName;
+    }
+    async latest() {
+        const response = await fetch(`https://registry.npmjs.org/${encodeURIComponent(this.packageName)}/latest`, {
+            headers: { accept: 'application/vnd.npm.install-v1+json' },
+            signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok)
+            throw new GitError(`npm registry returned ${response.status} while checking for updates.`);
+        const data = await response.json();
+        if (typeof data.version !== 'string' || !/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(data.version))
+            throw new GitError('npm registry returned an invalid SOJA version.');
+        return data.version;
+    }
+    async download(tag) {
+        const version = tag.replace(/^v/, '');
+        if (!/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(version))
+            throw new GitError('Invalid SOJA update version.');
+        const dir = mkdtempSync(join(tmpdir(), 'soja-update-'));
+        const output = await run('npm', ['pack', `${this.packageName}@${version}`, '--json', '--pack-destination', dir]);
+        let filename;
+        try {
+            filename = JSON.parse(output)[0]?.filename;
+        }
+        catch { /* handled below */ }
+        if (!filename || filename.includes('/') || filename.includes('\\') || !filename.endsWith('.tgz') || !readdirSync(dir).includes(filename)) {
+            throw new GitError(`npm did not provide a valid package for SOJA ${version}.`);
+        }
+        return join(dir, filename);
+    }
+    install(packagePath) {
+        return new Promise((resolve, reject) => {
+            const child = spawn('npm', ['install', '--global', packagePath], { stdio: 'inherit' });
+            child.on('error', reject);
+            child.on('close', (code) => code === 0 ? resolve() : reject(new GitError('npm could not install the update.', { suggestions: ['Check the npm messages above (a global prefix may need permissions).'] })));
+        });
+    }
+}
+function run(binary, args) {
+    return new Promise((resolve, reject) => {
+        let stdout = '';
+        let stderr = '';
+        const child = spawn(binary, args, { stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, GH_PROMPT_DISABLED: '1' } });
+        child.stdout.on('data', (chunk) => (stdout += chunk.toString()));
+        child.stderr.on('data', (chunk) => (stderr += chunk.toString()));
+        child.on('error', (error) => reject(error.code === 'ENOENT'
+            ? new GitError(binary === 'gh' ? 'The GitHub CLI (gh) is not installed.' : `${binary} is not installed.`, { code: binary === 'gh' ? 'gh_missing' : 'failed', suggestions: binary === 'gh' ? ['Install it from https://cli.github.com, then run `gh auth login`.'] : [] })
+            : error));
+        child.on('close', (code) => {
+            if (code === 0)
+                return resolve(stdout);
+            const auth = binary === 'gh' && /gh auth login|not logged in|HTTP 401|HTTP 404/i.test(stderr);
+            reject(new GitError(auth ? 'GitHub did not let SOJA read its releases.' : `${binary} failed: ${stderr.trim().split('\n')[0] ?? ''}`, {
+                code: auth ? 'gh_auth' : 'failed',
+                suggestions: auth ? ['Run `gh auth login` with an account that can see the SOJA repository.'] : [],
+            }));
+        });
+    });
+}