@withtruing/companion 0.0.0-stage → 0.13.0

package/dist/local-scan.js

@@ -0,0 +1,243 @@
+/**
+ * Zero-AI-call local grounding — see the companion plan's Section 4. Phase 1 keeps this to
+ * exactly what verify_module needs (a file listing, and the commit the checkout is at); the
+ * fuller monorepo-summarization/caching design in that section is scoped to a later phase, not
+ * required for the narrowest end-to-end slice this phase ships.
+ */
+import { execFile } from 'node:child_process';
+import { readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export const REPOSITORY_IDENTITY_MESSAGES = {
+    remote_ambiguous: 'Could not choose a git remote. Pass --remote <name>.',
+    remote_unsupported: 'This repository uses a remote URL that is not supported.',
+    branch_unknown: 'Could not determine the default branch. Pass --branch <name>.',
+};
+export const REMOTE_TROUBLESHOOTING_HINT = 'Run `git remote -v` in this folder to see your remotes.';
+export class RepositoryIdentityError extends Error {
+    code;
+    constructor(code) {
+        super(REPOSITORY_IDENTITY_MESSAGES[code]);
+        this.code = code;
+        this.name = 'RepositoryIdentityError';
+    }
+}
+function unsupported() {
+    throw new RepositoryIdentityError('remote_unsupported');
+}
+function canonicalPath(rawPath, github) {
+    const path = rawPath.replace(/^\/+/, '').replace(/\.git$/, '');
+    const segments = path.split('/');
+    if (segments.some((segment) => segment === '' || segment === '.' || segment === '..'))
+        unsupported();
+    if (!/^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)+$/.test(path))
+        unsupported();
+    if (github && segments.length !== 2)
+        unsupported();
+    return github ? path.toLowerCase() : path;
+}
+export function parseRemoteUrl(remoteUrl) {
+    let host;
+    let port;
+    let rawPath;
+    if (/^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(remoteUrl)
+        && !remoteUrl.startsWith('https://') && !remoteUrl.startsWith('ssh://'))
+        unsupported();
+    if (remoteUrl.startsWith('https://') || remoteUrl.startsWith('ssh://')) {
+        const rawPathMatch = /^[A-Za-z]+:\/\/[^/]+\/(.*?)(?:[?#]|$)/.exec(remoteUrl);
+        if (!rawPathMatch || rawPathMatch[1].split('/').some((segment) => segment === '' || segment === '.' || segment === '..')) {
+            unsupported();
+        }
+        let parsed;
+        try {
+            parsed = new URL(remoteUrl);
+        }
+        catch {
+            unsupported();
+        }
+        if ((parsed.protocol !== 'https:' && parsed.protocol !== 'ssh:') || parsed.search || parsed.hash)
+            unsupported();
+        host = parsed.hostname.toLowerCase();
+        if (!host)
+            unsupported();
+        const parsedPort = parsed.port ? Number(parsed.port) : null;
+        const defaultPort = parsed.protocol === 'https:' ? 443 : 22;
+        port = parsedPort === null || parsedPort === defaultPort ? null : parsedPort;
+        rawPath = rawPathMatch[1];
+    }
+    else {
+        const match = /^(?:[^@/:]+@)?([^/:]+):(.+)$/.exec(remoteUrl);
+        if (!match || /^[A-Za-z]:[\\/]/.test(remoteUrl))
+            unsupported();
+        host = match[1].toLowerCase();
+        port = null;
+        rawPath = match[2];
+    }
+    const github = host === 'github.com';
+    return { host, port: github ? null : port, path: canonicalPath(rawPath, github) };
+}
+async function git(repoPath, args) {
+    const { stdout } = await execFileAsync('git', args, { cwd: repoPath, windowsHide: true });
+    return stdout.trim();
+}
+async function validBranch(repoPath, branch) {
+    try {
+        await execFileAsync('git', ['check-ref-format', '--branch', branch], { cwd: repoPath, windowsHide: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function repositoryIdentity(repoPath, options = {}) {
+    try {
+        const remotes = (await git(repoPath, ['remote'])).split('\n').filter(Boolean);
+        const remote = options.remote
+            ?? (remotes.includes('origin') ? 'origin' : remotes.length === 1 ? remotes[0] : undefined);
+        if (!remote || !remotes.includes(remote))
+            throw new RepositoryIdentityError('remote_ambiguous');
+        let remoteUrl;
+        try {
+            remoteUrl = await git(repoPath, ['remote', 'get-url', remote]);
+        }
+        catch {
+            throw new RepositoryIdentityError('remote_unsupported');
+        }
+        const parsed = parseRemoteUrl(remoteUrl);
+        let defaultBranch = options.branch;
+        if (!defaultBranch) {
+            try {
+                const symbolic = await git(repoPath, ['symbolic-ref', '--short', `refs/remotes/${remote}/HEAD`]);
+                const prefix = `${remote}/`;
+                defaultBranch = symbolic.startsWith(prefix) ? symbolic.slice(prefix.length) : undefined;
+            }
+            catch {
+                // Fall through to main/master remote refs.
+            }
+        }
+        if (!defaultBranch) {
+            for (const candidate of ['main', 'master']) {
+                try {
+                    await execFileAsync('git', ['show-ref', '--verify', '--quiet', `refs/remotes/${remote}/${candidate}`], { cwd: repoPath, windowsHide: true });
+                    defaultBranch = candidate;
+                    break;
+                }
+                catch {
+                    // Try the next fallback.
+                }
+            }
+        }
+        if (!defaultBranch || !(await validBranch(repoPath, defaultBranch))) {
+            throw new RepositoryIdentityError('branch_unknown');
+        }
+        return { ...parsed, defaultBranch, remote };
+    }
+    catch (error) {
+        if (error instanceof RepositoryIdentityError)
+            throw error;
+        throw new RepositoryIdentityError('remote_unsupported');
+    }
+}
+export async function repositoryTopLevel(folder) {
+    try {
+        const topLevel = await git(folder, ['rev-parse', '--show-toplevel']);
+        return topLevel || null;
+    }
+    catch {
+        return null;
+    }
+}
+export const GIT_UNAVAILABLE_MESSAGE = 'git is not available on PATH for this companion process — open a new terminal where `git --version` works, then restart the companion.';
+export function repositoryMissingReason(repoPath) {
+    return `The project folder \`${repoPath}\` does not exist on this machine. Re-run \`connect\` with \`--path\` pointing at the repository's current location.`;
+}
+export function spawnFailureCode(error) {
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const candidate = error;
+    if (typeof candidate.code === 'string')
+        return candidate.code;
+    return spawnFailureCode(candidate.cause);
+}
+export async function checkRepositoryReadiness(repoPath) {
+    try {
+        if (!(await stat(repoPath)).isDirectory()) {
+            return { state: 'repository_missing', reason: repositoryMissingReason(repoPath) };
+        }
+    }
+    catch (error) {
+        const code = spawnFailureCode(error);
+        if (code === 'ENOENT' || code === 'ENOTDIR') {
+            return { state: 'repository_missing', reason: repositoryMissingReason(repoPath) };
+        }
+        return {
+            state: 'not_a_repository',
+            reason: `${repoPath} doesn't look like a git repository (git rev-parse failed there).`,
+        };
+    }
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: repoPath, windowsHide: true });
+        if (stdout.trim() === 'true')
+            return { state: 'ready' };
+    }
+    catch (error) {
+        const code = spawnFailureCode(error);
+        if (code === 'ENOENT' || code === 'EACCES') {
+            return { state: 'git_unavailable', reason: GIT_UNAVAILABLE_MESSAGE };
+        }
+    }
+    return {
+        state: 'not_a_repository',
+        reason: `${repoPath} doesn't look like a git repository (git rev-parse failed there).`,
+    };
+}
+/** NUL-delimited tracked paths preserve unusual filenames exactly. Gitlinks remain visible so
+ *  the snapshot-boundary check can reject unbound submodules before a repository-read task runs. */
+export async function listRepoFiles(repoPath) {
+    const { stdout } = await execFileAsync('git', ['ls-files', '-z'], { cwd: repoPath, maxBuffer: 64 * 1024 * 1024, windowsHide: true });
+    return parseNullDelimitedPaths(stdout);
+}
+export function parseNullDelimitedPaths(stdout) {
+    return stdout.split('\0').filter((path) => path.length > 0);
+}
+export async function currentCommit(repoPath) {
+    const { stdout } = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: repoPath, windowsHide: true });
+    return stdout.trim();
+}
+/** Confirms repoPath is actually inside a git working tree before doing anything else — a clear
+ *  "this path isn't a git repo" failure beats a confusing ENOENT deep inside listRepoFiles. */
+export async function assertIsRepo(repoPath) {
+    try {
+        await execFileAsync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: repoPath, windowsHide: true });
+    }
+    catch {
+        throw new Error(`${repoPath} doesn't look like a git repository (git rev-parse failed there).`);
+    }
+}
+function findFile(paths, basenames) {
+    const wanted = new Set(basenames.map((n) => n.toLowerCase()));
+    const matches = paths.filter((p) => wanted.has(p.split('/').pop().toLowerCase()));
+    matches.sort((a, b) => a.split('/').length - b.split('/').length); // prefer a shallower match, same tie-break as bootstrap.ts's own findFile
+    return matches[0];
+}
+async function readTextFile(repoPath, relPath) {
+    try {
+        return await readFile(join(repoPath, relPath), 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+export async function buildLocalRepoContext(repoPath) {
+    const fileList = await listRepoFiles(repoPath);
+    const readmePath = findFile(fileList, ['README.md', 'readme.md', 'Readme.md']);
+    const changelogPath = findFile(fileList, ['CHANGELOG.md', 'changelog.md']);
+    const packagePath = findFile(fileList, ['package.json']);
+    const [readme, changelog, packageJson] = await Promise.all([
+        readmePath ? readTextFile(repoPath, readmePath) : Promise.resolve(null),
+        changelogPath ? readTextFile(repoPath, changelogPath) : Promise.resolve(null),
+        packagePath ? readTextFile(repoPath, packagePath) : Promise.resolve(null),
+    ]);
+    return { fileList, readme, changelog, packageJson };
+}

package/dist/managed-repo.js

@@ -0,0 +1,408 @@
+/**
+ * The companion's own copy of a GitHub repo, for people who don't keep the code on their computer
+ * (`connect --repo owner/name`). The copy is an ordinary full clone under <config dir>/repos/, so
+ * every existing read path (git-range fetch, sandbox worktrees, shipment reads) serves it exactly
+ * as it serves a user's own checkout. This module owns making, checking and deleting that copy,
+ * the environment for background network Git calls, and a small per-copy state file that records
+ * whether background fetches still reach GitHub.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, isAbsolute, join, relative, resolve } from 'node:path';
+import { parseRemoteUrl } from './local-scan.js';
+export class ManagedRepoError extends Error {
+}
+/** Background Git network calls (fetch) must never open a prompt or a Git Credential Manager
+ *  window from the hidden service: they either work with the sign-in already saved, or fail. */
+export function networkGitEnvironment(parent = process.env) {
+    return { ...parent, GIT_TERMINAL_PROMPT: '0', GCM_INTERACTIVE: 'never' };
+}
+/** Supplies a GitHub token to Git for one process only. The URL-scoped header never reaches the
+ * remote URL or a config file, and trace variables are removed so Git cannot print the header. */
+export function githubAuthEnvironment(token, parent = process.env) {
+    const environment = networkGitEnvironment(parent);
+    const countText = environment.GIT_CONFIG_COUNT;
+    const parsedCount = countText !== undefined && /^(0|[1-9][0-9]*)$/.test(countText)
+        ? Number(countText)
+        : 0;
+    const count = Number.isSafeInteger(parsedCount) ? parsedCount : 0;
+    environment.GIT_CONFIG_COUNT = String(count + 1);
+    environment[`GIT_CONFIG_KEY_${count}`] = 'http.https://github.com/.extraHeader';
+    environment[`GIT_CONFIG_VALUE_${count}`] = `Authorization: Basic ${Buffer.from(`x-access-token:${token}`).toString('base64')}`;
+    for (const name of ['GIT_TRACE', 'GIT_TRACE_CURL', 'GIT_TRACE_PACKET', 'GIT_CURL_VERBOSE', 'GIT_TRACE_REDACT']) {
+        delete environment[name];
+    }
+    return environment;
+}
+const OWNER = /^[A-Za-z0-9-]+$/;
+const NAME = /^[A-Za-z0-9._-]+$/;
+const NOT_GITHUB_MESSAGE = 'The --repo option works with GitHub repos only, written as owner/name '
+    + '(for example fynchconsulting/product-console) or as the repo\'s https://github.com/... link.';
+/** Accepts `owner/name`, `owner/name.git`, and `https://github.com/owner/name[.git][/]`. */
+export function parseGitHubRepo(input) {
+    let value = input.trim();
+    const link = /^https:\/\/([^/?#]+)\/(.*)$/i.exec(value);
+    if (link) {
+        if (link[1].toLowerCase() !== 'github.com')
+            throw new ManagedRepoError(NOT_GITHUB_MESSAGE);
+        value = link[2];
+    }
+    else if (/^[a-z][a-z\d+.-]*:/i.test(value) || value.includes('@')) {
+        throw new ManagedRepoError(NOT_GITHUB_MESSAGE);
+    }
+    value = value.replace(/\/$/, '');
+    const parts = value.split('/');
+    if (parts.length !== 2)
+        throw new ManagedRepoError(NOT_GITHUB_MESSAGE);
+    const owner = parts[0];
+    const name = parts[1].replace(/\.git$/i, '');
+    if (!OWNER.test(owner) || !NAME.test(name) || name === '.' || name === '..') {
+        throw new ManagedRepoError(NOT_GITHUB_MESSAGE);
+    }
+    return { owner, name };
+}
+export function githubLabel(repo) {
+    return `${repo.owner}/${repo.name}`;
+}
+export function githubCloneUrl(repo) {
+    return `https://github.com/${repo.owner}/${repo.name}.git`;
+}
+function sanitizeSegment(value) {
+    const cleaned = value.replace(/[^A-Za-z0-9._-]/g, '_').toLowerCase();
+    return cleaned === '.' || cleaned === '..' || !cleaned ? '_' : cleaned;
+}
+/** GitHub names are case-insensitive, so the folder is lowercased: `Owner/Repo` and `owner/repo`
+ *  share one copy on every file system. */
+export function managedCopyFolderName(repo) {
+    return `github.com__${sanitizeSegment(repo.owner)}__${sanitizeSegment(repo.name)}`;
+}
+export function managedCopyPath(reposDir, repo) {
+    return join(resolve(reposDir), managedCopyFolderName(repo));
+}
+/** Best-effort owner/name for a copy whose config entry has no label. */
+export function labelFromCopyPath(repoPath) {
+    const match = /^github\.com__(.+?)__(.+)$/.exec(basename(repoPath));
+    return match ? `${match[1]}/${match[2]}` : basename(repoPath);
+}
+const MAX_CAPTURED_STDERR = 16_384;
+/** `stdio: 'inherit'` lets Git (and Git Credential Manager) talk to the person directly; stderr
+ *  is still teed to the terminal and captured so a failure can be explained in one line. */
+function runGit(cwd, args, options = {}) {
+    const interactive = options.stdio === 'inherit';
+    options.observeArgs?.(args);
+    return new Promise((done) => {
+        const child = spawn('git', args, {
+            cwd,
+            env: options.env ?? process.env,
+            stdio: interactive ? ['inherit', 'inherit', 'pipe'] : ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.setEncoding('utf8').on('data', (chunk) => { stdout += chunk; });
+        child.stderr?.setEncoding('utf8').on('data', (chunk) => {
+            if (interactive)
+                process.stderr.write(chunk);
+            if (stderr.length < MAX_CAPTURED_STDERR)
+                stderr += chunk.slice(0, MAX_CAPTURED_STDERR - stderr.length);
+        });
+        child.on('error', (error) => done({ code: null, stdout, stderr: stderr || error.message }));
+        child.on('close', (code) => done({ code, stdout, stderr }));
+    });
+}
+export async function gitAvailable() {
+    const result = await runGit(process.cwd(), ['--version']);
+    return result.code === 0;
+}
+// ---------------------------------------------------------------------------------------------
+// Sign-in problems and the per-copy state file
+const SIGN_IN_PATTERNS = [
+    /authentication failed/i,
+    /could not read (username|password)/i,
+    /terminal prompts disabled/i,
+    /repository not found/i,
+    /returned error: 40[13]\b/i,
+    /\bHTTP\/?[\d.]*\s+40[13]\b/i,
+    /\b40[13] (unauthorized|forbidden)\b/i,
+    /invalid username or (password|token)/i,
+    /permission denied \(publickey\)/i,
+];
+export function isSignInProblem(stderr) {
+    return SIGN_IN_PATTERNS.some((pattern) => pattern.test(stderr));
+}
+/** One short line for a person: credentials in URLs are redacted, Git's own prefixes dropped. */
+export function shortGitProblem(stderr) {
+    if (isSignInProblem(stderr))
+        return 'GitHub did not accept the sign-in on this computer for this repo';
+    const lines = stderr
+        .split(/\r?\n/)
+        .map((line) => line.replace(/(https?:\/\/)[^\s/@]+@/gi, '$1[redacted]@').trim())
+        .filter((line) => line && !/^(remote:|hint:)/i.test(line));
+    const line = lines.at(-1)?.replace(/^(fatal|error):\s*/i, '') ?? '';
+    return (line || 'Git could not reach GitHub').slice(0, 200);
+}
+export function managedStatePath(repoPath) {
+    return `${resolve(repoPath)}.state.json`;
+}
+export function readManagedState(repoPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(managedStatePath(repoPath), 'utf8'));
+        return {
+            lastUpdatedAt: typeof parsed.lastUpdatedAt === 'string' ? parsed.lastUpdatedAt : undefined,
+            signInNeeded: parsed.signInNeeded === true,
+            reconnectInConsole: parsed.reconnectInConsole === true,
+            lastProblem: typeof parsed.lastProblem === 'string' ? parsed.lastProblem : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Merges one fetch outcome into the state file. A failure that isn't about sign-in (no network,
+ *  GitHub down) leaves signInNeeded as it was. Never throws: a state write must not fail a task. */
+export function recordManagedFetch(repoPath, outcome, now = new Date()) {
+    const previous = readManagedState(repoPath) ?? { signInNeeded: false };
+    const signInProblem = isSignInProblem(outcome.stderr ?? '');
+    const next = outcome.ok
+        ? { lastUpdatedAt: now.toISOString(), signInNeeded: false }
+        : {
+            lastUpdatedAt: previous.lastUpdatedAt,
+            signInNeeded: signInProblem || previous.signInNeeded,
+            reconnectInConsole: signInProblem
+                ? outcome.reconnectInConsole === true
+                : previous.reconnectInConsole,
+            lastProblem: shortGitProblem(outcome.stderr ?? ''),
+        };
+    try {
+        writeFileSync(managedStatePath(repoPath), `${JSON.stringify(next, null, 2)}\n`);
+    }
+    catch {
+        // Best-effort.
+    }
+    return next;
+}
+const watchedCopies = new Map();
+function watchKey(repoPath) {
+    const resolved = resolve(repoPath);
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+/** Called by `run` for each managed connection, so the fetches the read paths already make are
+ *  recorded for that copy. Fetches in any other folder are not recorded. */
+export function watchManagedCopy(repoPath, label, log, getToken) {
+    const existing = watchedCopies.get(watchKey(repoPath));
+    watchedCopies.set(watchKey(repoPath), {
+        label,
+        log,
+        getToken,
+        lastTokenReason: undefined,
+        signInEpisodeLogged: existing?.signInEpisodeLogged ?? false,
+    });
+}
+export function forgetManagedCopies() {
+    watchedCopies.clear();
+}
+async function tokenFrom(getToken) {
+    if (!getToken)
+        return null;
+    try {
+        return await getToken();
+    }
+    catch {
+        return null;
+    }
+}
+/** Returns a fresh environment for each background fetch. Token lookup is best-effort so an old
+ * Console, network trouble, or an unwatched checkout keeps the existing local-sign-in fallback. */
+export async function managedFetchEnvironment(repoPath) {
+    const watched = watchedCopies.get(watchKey(repoPath));
+    if (!watched?.getToken)
+        return networkGitEnvironment();
+    try {
+        const response = await watched.getToken();
+        watched.lastTokenReason = response.reason;
+        return response.token === null ? networkGitEnvironment() : githubAuthEnvironment(response.token);
+    }
+    catch {
+        watched.lastTokenReason = undefined;
+        return networkGitEnvironment();
+    }
+}
+/** Every background fetch reports here. A no-op for folders that aren't a watched managed copy;
+ *  otherwise records the state file and logs a sign-in problem once per episode. Never throws. */
+export function reportBackgroundFetch(repoPath, outcome) {
+    try {
+        const watched = watchedCopies.get(watchKey(repoPath));
+        if (!watched)
+            return;
+        const reconnectInConsole = watched.lastTokenReason === 'github_reconnect_needed';
+        recordManagedFetch(repoPath, { ...outcome, reconnectInConsole });
+        if (outcome.ok) {
+            watched.signInEpisodeLogged = false;
+        }
+        else if (isSignInProblem(outcome.stderr ?? '') && !watched.signInEpisodeLogged) {
+            watched.signInEpisodeLogged = true;
+            watched.log(reconnectInConsole
+                ? `GitHub sign-in needed for ${watched.label}. Reconnect GitHub in the Console.`
+                : `GitHub sign-in needed for ${watched.label}. On this computer, run: truing signin`);
+        }
+    }
+    catch {
+        // Reporting is best-effort; the read path's own result is what matters.
+    }
+}
+// ---------------------------------------------------------------------------------------------
+// Making, refreshing and deleting the copy
+function samePath(a, b) {
+    const left = resolve(a);
+    const right = resolve(b);
+    return process.platform === 'win32' ? left.toLowerCase() === right.toLowerCase() : left === right;
+}
+/** True only when `path` is the top of its own Git repo and its origin is this GitHub repo. */
+export async function isCopyOf(path, repo) {
+    const top = await runGit(path, ['rev-parse', '--show-toplevel']);
+    if (top.code !== 0)
+        return false;
+    try {
+        if (!samePath(realpathSync(top.stdout.trim()), realpathSync(path)))
+            return false;
+    }
+    catch {
+        return false;
+    }
+    const origin = await runGit(path, ['config', '--get', 'remote.origin.url']);
+    if (origin.code !== 0)
+        return false;
+    try {
+        const parsed = parseRemoteUrl(origin.stdout.trim());
+        return parsed.host === 'github.com' && parsed.path === `${repo.owner}/${repo.name}`.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+}
+async function runGitWithTokenRetry(cwd, args, token, label, options, beforeRetry) {
+    const stdio = options.stdio ?? 'inherit';
+    const run = options.runGitForTest ?? runGit;
+    const initialEnvironment = token === null
+        ? (options.networkEnvironmentWithoutToken ? networkGitEnvironment() : undefined)
+        : githubAuthEnvironment(token);
+    let result = await run(cwd, args, {
+        stdio,
+        ...(initialEnvironment ? { env: initialEnvironment } : {}),
+        observeArgs: options.observeGitArgs,
+    });
+    const retry = options.retryWithoutTokenOnSignInProblem ?? stdio === 'inherit';
+    if (token !== null && retry && result.code !== 0 && isSignInProblem(result.stderr)) {
+        options.output?.log(`The Console's GitHub connection didn't work for ${label}. Trying the sign-in on this computer instead.`);
+        beforeRetry?.();
+        result = await run(cwd, args, { stdio, observeArgs: options.observeGitArgs });
+    }
+    return result;
+}
+/** A fetch the person is watching: prompts and the GitHub sign-in window are allowed. */
+export async function interactiveFetch(repoPath, getToken, options = {}) {
+    const token = await tokenFrom(getToken);
+    const result = await runGitWithTokenRetry(repoPath, ['fetch', 'origin'], token, labelFromCopyPath(repoPath), {
+        ...options,
+        output: options.output ?? console,
+        networkEnvironmentWithoutToken: (options.stdio ?? 'inherit') === 'quiet',
+    });
+    const outcome = { ok: result.code === 0, stderr: result.stderr };
+    recordManagedFetch(repoPath, outcome);
+    return outcome;
+}
+export async function prepareManagedCopy(options) {
+    const output = options.output ?? console;
+    const label = githubLabel(options.repo);
+    const dest = managedCopyPath(options.reposDir, options.repo);
+    const stdio = options.stdio ?? 'inherit';
+    if (existsSync(dest)) {
+        if (!(await isCopyOf(dest, options.repo))) {
+            throw new ManagedRepoError(`There's already a folder at ${dest} that isn't the companion's copy of ${label}. `
+                + 'Move or delete that folder yourself, then run this command again.');
+        }
+        output.log(`Using the companion's existing copy of ${label} and bringing it up to date.`);
+        const fetched = await interactiveFetch(dest, options.getToken, {
+            stdio,
+            output,
+            observeGitArgs: options.observeGitArgs,
+            retryWithoutTokenOnSignInProblem: options.retryWithoutTokenOnSignInProblem,
+            runGitForTest: options.runGitForTest,
+        });
+        return { path: dest, created: false, fetchOk: fetched.ok };
+    }
+    mkdirSync(resolve(options.reposDir), { recursive: true });
+    const token = await tokenFrom(options.getToken);
+    output.log(token === null
+        ? `Making the companion's own copy of ${label}. If a browser window asks you to sign in to GitHub, do that once.`
+        : `Making the companion's own copy of ${label}. Using your GitHub connection from the Console.`);
+    const githubUrl = githubCloneUrl(options.repo);
+    const cloneArgs = [
+        '-c', 'core.longpaths=true', 'clone', '--origin', 'origin',
+        ...(options.branch ? ['--branch', options.branch] : []),
+        '--', options.cloneUrl ?? githubUrl, dest,
+    ];
+    const clone = await runGitWithTokenRetry(resolve(options.reposDir), cloneArgs, token, label, {
+        stdio,
+        output,
+        observeGitArgs: options.observeGitArgs,
+        retryWithoutTokenOnSignInProblem: options.retryWithoutTokenOnSignInProblem,
+        runGitForTest: options.runGitForTest,
+    }, () => {
+        // The folder did not exist before this clone, so anything there now is the clone's own.
+        rmSync(dest, { recursive: true, force: true, maxRetries: 3 });
+    });
+    const configured = clone.code === 0
+        && (await runGit(dest, ['config', 'core.longpaths', 'true'])).code === 0
+        && (options.cloneUrl === undefined || options.cloneUrl === githubUrl
+            || (await runGit(dest, ['remote', 'set-url', 'origin', githubUrl])).code === 0);
+    if (!configured) {
+        // The folder did not exist before this clone, so anything there now is the clone's own.
+        rmSync(dest, { recursive: true, force: true, maxRetries: 3 });
+        throw new ManagedRepoError(`Couldn't copy ${label} from GitHub. Check that your GitHub account can open this repo in the browser, then run this command again.`);
+    }
+    recordManagedFetch(dest, { ok: true });
+    return { path: dest, created: true };
+}
+/** Deletes a managed copy and its state file. Refuses anything that does not resolve to a folder
+ *  directly inside reposDir. Returns false when there was nothing to delete. */
+export async function removeManagedCopy(repoPath, reposDir) {
+    const root = resolve(reposDir);
+    const target = resolve(repoPath);
+    const inside = (base, candidate) => {
+        const rel = relative(base, candidate);
+        return !!rel && !rel.startsWith('..') && !isAbsolute(rel) && !/[\\/]/.test(rel);
+    };
+    if (!inside(root, target)) {
+        throw new ManagedRepoError(`Not removing ${target}: it isn't inside the companion's own repos folder.`);
+    }
+    if (!existsSync(target)) {
+        rmSync(managedStatePath(target), { force: true });
+        return false;
+    }
+    if (lstatSync(target).isSymbolicLink()
+        || (existsSync(root) && !inside(realpathSync(root), realpathSync(target)))) {
+        throw new ManagedRepoError(`Not removing ${target}: it points outside the companion's own repos folder.`);
+    }
+    await runGit(target, ['worktree', 'prune']);
+    rmSync(target, { recursive: true, force: true, maxRetries: 3 });
+    rmSync(managedStatePath(target), { force: true });
+    return true;
+}
+export function relativeTime(iso, now = new Date()) {
+    if (!iso)
+        return 'not yet';
+    const ms = now.getTime() - Date.parse(iso);
+    if (!Number.isFinite(ms))
+        return 'not yet';
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes < 1)
+        return 'just now';
+    if (minutes < 60)
+        return `${minutes} minute${minutes === 1 ? '' : 's'} ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours} hour${hours === 1 ? '' : 's'} ago`;
+    const days = Math.floor(hours / 24);
+    return `${days} day${days === 1 ? '' : 's'} ago`;
+}