@hearsay-tools/squawk 0.0.0-stage → 0.17.0-pr3058.5683

package/dist/server/checkout-progress.js

@@ -0,0 +1,27 @@
+/** Recovery cache for the clone and new-project dialogs, never an authority for the mutation's result. */
+export class CheckoutProgressCache {
+    now;
+    values = new Map();
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    prune() {
+        for (const [key, value] of this.values)
+            if (this.now() - value.at >= 5 * 60_000)
+                this.values.delete(key);
+    }
+    record(progress) {
+        if (!progress.checkoutId)
+            return;
+        this.prune();
+        this.values.delete(progress.checkoutId);
+        this.values.set(progress.checkoutId, { at: this.now(), progress: { ...progress, ...(progress.line ? { line: progress.line.slice(-4096) } : {}), ...(progress.error ? { error: progress.error.slice(-4096) } : {}), ...(progress.warning ? { warning: progress.warning.slice(0, 4096) } : {}) } });
+        while (this.values.size > 128)
+            this.values.delete(this.values.keys().next().value);
+    }
+    get(id) {
+        this.prune();
+        return this.values.get(id)?.progress ?? null;
+    }
+}
+//# sourceMappingURL=checkout-progress.js.map

package/dist/server/checkout-progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-progress.js","sourceRoot":"","sources":["../../src/server/checkout-progress.ts"],"names":[],"mappings":"AAEA,0GAA0G;AAC1G,MAAM,OAAO,qBAAqB;IAEH,GAAG;IADf,MAAM,GAAG,IAAI,GAAG,EAA2D,CAAC;IAC7F,YAA6B,GAAG,GAAG,IAAI,CAAC,GAAG;mBAAd,GAAG;IAAc,CAAC;IACvC,KAAK;QACX,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM;YAAE,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,EAAE,IAAI,CAAC,GAAG,MAAM;gBAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3G,CAAC;IACD,MAAM,CAAC,QAA+B;QACpC,IAAI,CAAC,QAAQ,CAAC,UAAU;YAAE,OAAO;QACjC,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,EAAE,GAAG,QAAQ,EAAE,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;QAClS,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,GAAG,GAAG;YAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAM,CAAC,CAAC;IACtF,CAAC;IACD,GAAG,CAAC,EAAU;QACZ,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,QAAQ,IAAI,IAAI,CAAC;IAC/C,CAAC;CACF"}

package/dist/server/checkout.d.ts

@@ -0,0 +1,153 @@
+/** Progress lines kept for the error message. `git clone` is chatty and the
+ *  useful part of a failure is always at the end. */
+export declare const ERROR_TAIL_LINES = 6;
+/** Keep complete progress lines and a bounded error tail; callers choose when to flush. */
+export declare function createProgressLineSplitter(onLine: (line: string) => void): {
+    tail: string[];
+    consume: (chunk: string) => void;
+    readonly pending: string;
+    flush(): void;
+};
+/** Validate and resolve the checkout target before any filesystem work. */
+export declare function checkoutTarget(projectsDir: string, name: string): {
+    ok: false;
+    status: 500;
+    error: string;
+    root?: never;
+    target?: never;
+} | {
+    ok?: never;
+    status?: never;
+    error?: never;
+    root: string;
+    target: string;
+};
+/** One `checkout-progress` SSE payload (workspace-level event, step 2.8's bus).
+ *  `checkoutId` is echoed from the request so a cockpit only renders its own
+ *  clone — two tabs cloning at once share the one workspace stream. */
+export interface CheckoutProgressEvent {
+    checkoutId?: string;
+    /** The target folder name, so a payload is readable without the id too. */
+    name: string;
+    phase: 'cloning' | 'done' | 'error';
+    /** One line of `git clone` progress (present on `cloning`). */
+    line?: string;
+    /** Human-readable failure (present on `error`). */
+    error?: string;
+    /** New-project flow only: on `done`, what did not finish (see `create-project.ts`). */
+    warning?: string;
+}
+export type CheckoutFailure = {
+    ok: false;
+    status: 400 | 409 | 500;
+    error: string;
+}
+/** `gh` is missing or unauthenticated — the spec's `{ error, reason }`
+ *  degradation, mirroring the GitHub pane's contract. */
+ | {
+    ok: false;
+    status: 503;
+    error: string;
+    reason: string;
+};
+export type CheckoutResult = {
+    ok: true;
+    target: string;
+    name: string;
+} | CheckoutFailure;
+/** A GitHub repo reference the clone flow accepts. */
+export interface RepoRef {
+    owner: string;
+    repo: string;
+    /** Normalized identity used in messages and dry-run output. */
+    slug: string;
+    /** What `gh repo clone` is handed. Always reconstructed from validated
+     *  segments rather than preserving user input. Forcing HTTPS is load-bearing:
+     *  a machine configured with `gh config set git_protocol ssh` may have an
+     *  OAuth token authorized for an organization's SAML policy while its SSH key
+     *  is not. Passing only `owner/repo` silently selects that rejected key.
+     *  The resulting HTTPS `origin` needs a credential path of its own after the
+     *  clone — see `persistGhCredentialHelper`. */
+    cloneUrl: string;
+}
+/**
+ * Parse `owner/repo`, `https://github.com/owner/repo(.git)`, `git@github.com:owner/repo.git`
+ * or `github.com/owner/repo` into a normalized ref. `null` when it is not a
+ * GitHub repo reference — the route answers 400 rather than handing an
+ * arbitrary string to `gh`.
+ *
+ * Only github.com: `gh repo clone` would happily take an enterprise host, but
+ * this flow's contract (and its `gh`-availability degradation) is GitHub's, and
+ * silently accepting `evil.example/owner/repo` would make the "which host am I
+ * cloning from" question unanswerable from the dialog.
+ */
+export declare function parseRepoRef(input: string): RepoRef | null;
+/**
+ * Validate the target folder name (the dialog lets the user edit it, and it
+ * defaults to the repo name).
+ *
+ * A name is one path segment and nothing else. `.` / `..` and anything with a
+ * separator are rejected outright rather than sanitized: a silently rewritten
+ * name would clone somewhere other than the path the dialog previewed, which
+ * is the one thing a checkout target must never do. A leading dot is refused
+ * too — a project named `.ssh` under the checkout root is not a project.
+ */
+export declare function isValidCheckoutName(name: string): boolean;
+/**
+ * Remove only an attempt-owned real directory whose canonical parent is the checkout root.
+ * Refuse symlinks, the root itself and uncertain paths. Return false on any check or removal
+ * failure.
+ */
+export declare function cleanupCheckout(projectsDir: string, target: string): Promise<boolean>;
+/** Injected so the tests can drive a fake clone without a network or a `gh`
+ *  binary. `dir` already exists (we created it); the runner clones INTO it. */
+export type CloneRunner = (ref: RepoRef, dir: string, onLine: (line: string) => void, signal: AbortSignal | undefined) => Promise<{
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+    notFound?: boolean;
+}>;
+/** Kept pure so the SAML-safe transport choice is pinned without spawning a
+ * real GitHub process in the unit suite. */
+export declare function ghCloneArgs(ref: RepoRef, dir: string): string[];
+/** PR #968: the `git config --local` argument lists that route github.com HTTPS
+ *  credentials through `gh`. Reset inherited helpers first, as gh setup-git does.
+ *  Shared with the new-project flow (`create-project.ts`). */
+export declare const GH_CREDENTIAL_HELPER_CONFIG: readonly (readonly string[])[];
+/**
+ * `gh repo clone <validated HTTPS URL> <dir> -- --progress`.
+ *
+ * `spawn`, not `execFile`, because the whole point of this route is that the
+ * dialog sees progress while it happens: `git clone --progress` writes its
+ * counters to stderr, and each line becomes a `checkout-progress` event.
+ * (`--progress` is needed explicitly — git suppresses it when stderr is not a
+ * TTY, which it never is here.)
+ */
+export declare const ghCloneRunner: CloneRunner;
+/** `CEZ_DRY_RUN=1` — a fake clone so the dialog (and the tests) can exercise
+ *  the whole flow offline: a few progress lines and a plausible repo on disk.
+ *  It writes only INSIDE the directory the caller already created. */
+export declare const dryRunCloneRunner: CloneRunner;
+export interface CheckoutOptions {
+    /** Raw user input: `owner/repo` or a GitHub URL. */
+    url: string;
+    /** Target folder name; defaults to the repo name. */
+    name?: string | undefined;
+    /** The checkout root, ALREADY `~`-expanded by the caller. */
+    projectsDir: string;
+    onProgress: (event: CheckoutProgressEvent) => void;
+    checkoutId?: string | undefined;
+    signal?: AbortSignal | undefined;
+    /** Test seam; defaults to `gh` (or the dry-run fake under `CEZ_DRY_RUN=1`). */
+    run?: CloneRunner | undefined;
+}
+/**
+ * Clone a GitHub repo into `<projectsDir>/<name>`, streaming progress.
+ *
+ * Answers only when the clone has finished (the spec's "long-running: answers
+ * when the clone finishes"); the dialog's liveness comes from `onProgress`.
+ * On any failure the partially-written directory is removed and NOTHING is
+ * registered — registration is the caller's job, and only on `ok: true`.
+ */
+export declare function checkoutRepo(opts: CheckoutOptions): Promise<CheckoutResult>;

package/dist/server/checkout.js

@@ -0,0 +1,323 @@
+import { productEnv } from '../core/product-env.js';
+import { execFile, spawn } from 'node:child_process';
+import { lstat, mkdir, realpath, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+/**
+ * Clone into one validated direct child of projectsDir. Reserve the directory with non-recursive
+ * mkdir before cloning; only guarded cleanup may remove a failed attempt. The route owns
+ * registration.
+ */
+/** How long a clone may run before it is killed. Long enough for a large repo
+ *  on a slow link, short enough that a hung `gh` (an auth prompt that will
+ *  never be answered — `gh` is non-interactive here, but a proxy can still
+ *  stall) does not pin a request forever. */
+const CLONE_TIMEOUT_MS = 10 * 60_000;
+/** Progress lines kept for the error message. `git clone` is chatty and the
+ *  useful part of a failure is always at the end. */
+export const ERROR_TAIL_LINES = 6;
+/** Keep complete progress lines and a bounded error tail; callers choose when to flush. */
+export function createProgressLineSplitter(onLine) {
+    const tail = [];
+    let pending = '';
+    const consume = (chunk) => {
+        pending += chunk;
+        const parts = pending.split(/\r\n|\r|\n/);
+        pending = parts.pop() ?? '';
+        for (const part of parts) {
+            const line = part.trim();
+            if (line === '')
+                continue;
+            tail.push(line);
+            if (tail.length > ERROR_TAIL_LINES)
+                tail.shift();
+            onLine(line);
+        }
+    };
+    return {
+        tail,
+        consume,
+        get pending() { return pending; },
+        flush() { if (pending !== '')
+            consume('\n'); },
+    };
+}
+/** Validate and resolve the checkout target before any filesystem work. */
+export function checkoutTarget(projectsDir, name) {
+    if (!projectsDir.startsWith('/')) {
+        return { ok: false, status: 500, error: `checkout root is not an absolute path: ${projectsDir}` };
+    }
+    const root = resolve(projectsDir);
+    const target = join(root, name);
+    return { root, target };
+}
+/** `owner` and `repo` as GitHub itself allows them: alphanumerics, `-`, `_`,
+ *  `.`. Deliberately strict — this string becomes a `gh` argv entry and half of
+ *  a filesystem path, and every character outside this set is someone trying
+ *  something. */
+const NAME_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/**
+ * Parse `owner/repo`, `https://github.com/owner/repo(.git)`, `git@github.com:owner/repo.git`
+ * or `github.com/owner/repo` into a normalized ref. `null` when it is not a
+ * GitHub repo reference — the route answers 400 rather than handing an
+ * arbitrary string to `gh`.
+ *
+ * Only github.com: `gh repo clone` would happily take an enterprise host, but
+ * this flow's contract (and its `gh`-availability degradation) is GitHub's, and
+ * silently accepting `evil.example/owner/repo` would make the "which host am I
+ * cloning from" question unanswerable from the dialog.
+ */
+export function parseRepoRef(input) {
+    const trimmed = input.trim();
+    if (trimmed === '' || trimmed.length > 512)
+        return null;
+    // Strip the scheme/host spellings down to `owner/repo`, then validate ONE
+    // shape. Doing it the other way round (a regex per spelling) is how a fourth
+    // spelling eventually gets a weaker check than the other three.
+    let path = trimmed;
+    const ssh = /^(?:ssh:\/\/)?git@github\.com[:/](.+)$/.exec(path);
+    if (ssh?.[1])
+        path = ssh[1];
+    else {
+        const https = /^(?:https?:\/\/)?(?:www\.)?github\.com\/(.+)$/.exec(path);
+        if (https?.[1])
+            path = https[1];
+    }
+    path = path.replace(/\/+$/, '').replace(/\.git$/, '');
+    const parts = path.split('/');
+    if (parts.length !== 2)
+        return null;
+    const [owner, repo] = parts;
+    if (!owner || !repo || !NAME_SEGMENT.test(owner) || !NAME_SEGMENT.test(repo))
+        return null;
+    return {
+        owner,
+        repo,
+        slug: `${owner}/${repo}`,
+        cloneUrl: `https://github.com/${owner}/${repo}.git`,
+    };
+}
+/**
+ * Validate the target folder name (the dialog lets the user edit it, and it
+ * defaults to the repo name).
+ *
+ * A name is one path segment and nothing else. `.` / `..` and anything with a
+ * separator are rejected outright rather than sanitized: a silently rewritten
+ * name would clone somewhere other than the path the dialog previewed, which
+ * is the one thing a checkout target must never do. A leading dot is refused
+ * too — a project named `.ssh` under the checkout root is not a project.
+ */
+export function isValidCheckoutName(name) {
+    return name.length <= 128 && NAME_SEGMENT.test(name) && !name.includes('/') && !name.includes('\\');
+}
+/**
+ * Remove only an attempt-owned real directory whose canonical parent is the checkout root.
+ * Refuse symlinks, the root itself and uncertain paths. Return false on any check or removal
+ * failure.
+ */
+export async function cleanupCheckout(projectsDir, target) {
+    let realRoot;
+    let realTarget;
+    try {
+        const info = await lstat(target);
+        if (!info.isDirectory() || info.isSymbolicLink())
+            return false;
+        realRoot = await realpath(projectsDir);
+        realTarget = await realpath(target);
+    }
+    catch {
+        return false; // gone, or unresolvable — either way, not ours to remove
+    }
+    if (realTarget === realRoot)
+        return false;
+    if (dirname(realTarget) !== realRoot)
+        return false;
+    try {
+        await rm(realTarget, { recursive: true, force: true });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Kept pure so the SAML-safe transport choice is pinned without spawning a
+ * real GitHub process in the unit suite. */
+export function ghCloneArgs(ref, dir) {
+    // gh still uses its configured SSH preference when adding/fetching a fork's
+    // parent after the clone. Git writes --config before the initial fetch, so
+    // that subsequent fetch (and later pushes) also uses the OAuth HTTPS grant.
+    // Keep this in the new repository; never change the user's global settings.
+    return ['repo', 'clone', ref.cloneUrl, dir, '--', '--progress',
+        '--config', 'url.https://github.com/.insteadOf=git@github.com:'];
+}
+/** PR #968: the `git config --local` argument lists that route github.com HTTPS
+ *  credentials through `gh`. Reset inherited helpers first, as gh setup-git does.
+ *  Shared with the new-project flow (`create-project.ts`). */
+export const GH_CREDENTIAL_HELPER_CONFIG = [
+    ['--replace-all', 'credential.https://github.com.helper', ''],
+    ['--add', 'credential.https://github.com.helper', '!gh auth git-credential'],
+];
+/** PR #968: gh injects credentials only for the clone command. Persist the
+ * helper locally so subsequent raw git pushes (including task worktrees) use
+ * the same OAuth grant. */
+async function persistGhCredentialHelper(dir) {
+    for (const args of GH_CREDENTIAL_HELPER_CONFIG) {
+        const ok = await new Promise((resolvePromise) => {
+            execFile('git', ['-C', dir, 'config', '--local', ...args], { timeout: 10_000 }, (err) => resolvePromise(!err));
+        });
+        if (!ok)
+            return false;
+    }
+    return true;
+}
+/**
+ * `gh repo clone <validated HTTPS URL> <dir> -- --progress`.
+ *
+ * `spawn`, not `execFile`, because the whole point of this route is that the
+ * dialog sees progress while it happens: `git clone --progress` writes its
+ * counters to stderr, and each line becomes a `checkout-progress` event.
+ * (`--progress` is needed explicitly — git suppresses it when stderr is not a
+ * TTY, which it never is here.)
+ */
+export const ghCloneRunner = (ref, dir, onLine, signal) => new Promise((resolvePromise) => {
+    const child = spawn('gh', ghCloneArgs(ref, dir), {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: CLONE_TIMEOUT_MS,
+        // No inherited stdin and `GH_PROMPT_DISABLED`: an unauthenticated `gh`
+        // must fail with a message the dialog can show, not block on a prompt
+        // nobody can see.
+        env: { ...process.env, GH_PROMPT_DISABLED: '1', GIT_TERMINAL_PROMPT: '0' },
+    });
+    let settled = false;
+    const finish = (result) => {
+        if (settled)
+            return;
+        settled = true;
+        resolvePromise(result);
+    };
+    // The client hung up (dialog closed, tab gone). Kill the clone rather than
+    // let it keep writing into a directory nobody is waiting for — the caller
+    // then takes the failure path, which cleans up.
+    const onAbort = () => {
+        child.kill('SIGTERM');
+        finish({ ok: false, error: 'checkout cancelled' });
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    // git's progress is carriage-return-separated, not newline-separated —
+    // splitting on `\n` alone would buffer the whole "Receiving objects" phase
+    // into one line delivered at the end, which is exactly the silent spinner
+    // this stream exists to avoid.
+    const lines = createProgressLineSplitter(onLine);
+    child.stderr?.setEncoding('utf8');
+    child.stderr?.on('data', lines.consume);
+    child.stdout?.setEncoding('utf8');
+    child.stdout?.on('data', lines.consume);
+    child.on('error', (err) => {
+        signal?.removeEventListener('abort', onAbort);
+        // ENOENT is the `gh`-not-installed case, which the route degrades on
+        // rather than reports as a clone failure.
+        const notFound = err.code === 'ENOENT';
+        finish({ ok: false, error: err.message, notFound });
+    });
+    child.on('close', (code) => {
+        // gh may exit without a newline after the authorization URL.
+        lines.flush();
+        signal?.removeEventListener('abort', onAbort);
+        if (code === 0) {
+            void persistGhCredentialHelper(dir).then((ok) => finish(ok
+                ? { ok: true }
+                : { ok: false, error: 'Could not configure GitHub credentials for the checkout. Check directory permissions and retry.' }));
+            return;
+        }
+        // The tail of gh/git's own output IS the error message — `gh` writes
+        // "could not find repository", "authentication required" and the network
+        // errors itself, and paraphrasing them would only lose detail.
+        const detail = lines.tail.join('\n').trim();
+        finish({ ok: false, error: detail === '' ? `gh repo clone exited with code ${code}` : detail });
+    });
+});
+/** `CEZ_DRY_RUN=1` — a fake clone so the dialog (and the tests) can exercise
+ *  the whole flow offline: a few progress lines and a plausible repo on disk.
+ *  It writes only INSIDE the directory the caller already created. */
+export const dryRunCloneRunner = async (ref, dir, onLine) => {
+    onLine(`Cloning into '${dir}'...`);
+    onLine('remote: Enumerating objects: 3, done.');
+    // A `.git` directory so the registered project probes as a git repo the way
+    // a real clone would — the point of the dry run is the same shape, not the
+    // same bytes.
+    await mkdir(join(dir, '.git'), { recursive: true });
+    await writeFile(join(dir, 'README.md'), `# ${ref.repo}\n\n(CEZ_DRY_RUN=1 fake clone)\n`, 'utf8');
+    onLine('Receiving objects: 100% (3/3), done.');
+    return { ok: true };
+};
+/**
+ * Clone a GitHub repo into `<projectsDir>/<name>`, streaming progress.
+ *
+ * Answers only when the clone has finished (the spec's "long-running: answers
+ * when the clone finishes"); the dialog's liveness comes from `onProgress`.
+ * On any failure the partially-written directory is removed and NOTHING is
+ * registered — registration is the caller's job, and only on `ok: true`.
+ */
+export async function checkoutRepo(opts) {
+    const ref = parseRepoRef(opts.url);
+    if (!ref) {
+        return { ok: false, status: 400, error: `not a GitHub repository: ${opts.url.trim().slice(0, 200)}` };
+    }
+    const name = (opts.name ?? '').trim() === '' ? ref.repo : (opts.name ?? '').trim();
+    if (!isValidCheckoutName(name)) {
+        return { ok: false, status: 400, error: `not a valid folder name: ${name.slice(0, 200)}` };
+    }
+    const destination = checkoutTarget(opts.projectsDir, name);
+    if (destination.ok === false)
+        return destination;
+    const { root, target } = destination;
+    // The checkout root is created on demand — a fresh install has never had one,
+    // and failing "clone" because a directory the user never asked about is
+    // missing would be an odd first experience. Its writability is validated on
+    // `PUT /api/workspace/config`; a failure here is reported as one.
+    try {
+        await mkdir(root, { recursive: true });
+    }
+    catch (err) {
+        return { ok: false, status: 500, error: `checkout root is not writable: ${errText(err)}` };
+    }
+    // THE ownership token (see the module docstring): non-recursive, so it
+    // succeeds only when it created the directory itself. EEXIST is the spec's
+    // 409 — and note nothing has touched the existing directory to learn that.
+    try {
+        await mkdir(target);
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            return { ok: false, status: 409, error: `folder already exists: ${target}` };
+        }
+        return { ok: false, status: 500, error: `could not create ${target}: ${errText(err)}` };
+    }
+    const emit = (event) => opts.onProgress({ ...event, name, ...(opts.checkoutId ? { checkoutId: opts.checkoutId } : {}) });
+    const run = opts.run ?? (productEnv('DRY_RUN') === '1' ? dryRunCloneRunner : ghCloneRunner);
+    let outcome;
+    try {
+        outcome = await run(ref, target, (line) => emit({ phase: 'cloning', line }), opts.signal);
+    }
+    catch (err) {
+        // A runner that throws is still a failed clone — same cleanup, same shape.
+        outcome = { ok: false, error: errText(err) };
+    }
+    if (!outcome.ok) {
+        // Cleanup FIRST, then answer: the dialog's "try again" must not race a
+        // directory that is still on disk (it would get the 409 instead).
+        await cleanupCheckout(root, target);
+        if (outcome.notFound) {
+            const reason = 'gh CLI not found — install it and run `gh auth login`';
+            emit({ phase: 'error', error: reason });
+            return { ok: false, status: 503, error: reason, reason };
+        }
+        emit({ phase: 'error', error: outcome.error });
+        return { ok: false, status: 500, error: outcome.error };
+    }
+    emit({ phase: 'done' });
+    return { ok: true, target, name };
+}
+function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=checkout.js.map

package/dist/server/checkout.js.map

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

package/dist/server/cockpit-ownership.d.ts

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+declare const ownerSchema: z.ZodObject<{
+    pid: z.ZodNumber;
+    token: z.ZodString;
+    startToken: z.ZodOptional<z.ZodString>;
+    url: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Owner = z.infer<typeof ownerSchema>;
+export declare class CockpitAlreadyRunningError extends Error {
+    constructor(dataDir: string, owner?: Owner, unreadableLock?: string);
+}
+/** The migration fence and its journal: beside both directory names, so moving one never moves them. */
+export declare const MIGRATION_FENCE_FILE = "squawk-migration.lock";
+export declare const MIGRATION_JOURNAL_FILE = "squawk-migration.json";
+/** A project's fence and journal paths; none for a data directory that is not `<root>/.ai/{cezar,squawk}`. */
+export declare function migrationFencePaths(dataDir: string): {
+    lock: string;
+    journal: string;
+} | undefined;
+export declare class ProjectMigrationFencedError extends Error {
+    readonly reason: 'migrating' | 'journal' | 'unreadable';
+    readonly path: string;
+    constructor(reason: 'migrating' | 'journal' | 'unreadable', path: string, owner?: Owner);
+}
+/**
+ * Why no new operation may touch the project of `dataDir`: a live or unreadable fence (this
+ * process's own fence included) or an unfinished journal. Dormant cost: two `lstat` calls.
+ * A dead owner without a journal admits; the next fence claim reclaims its file.
+ */
+export declare function projectAdmissionRefusal(dataDir: string): ProjectMigrationFencedError | undefined;
+export declare function assertProjectAdmitted(dataDir: string): void;
+/**
+ * The write backstop under every store write, claim and save: true while a fence or a journal
+ * refuses this project, outside the fence holder's own work. Offline, the migration CLI refuses
+ * while any cockpit it can see serves the project; this stops the writes of one it cannot see (a
+ * cockpit of another home that has the project registered). A skipped write is logged once per
+ * fence. Dormant cost: two `lstat` calls.
+ */
+export declare function projectWriteRefused(dataDir: string): boolean;
+/** A CLI write: the project's migration admission is checked right before `write` runs. A CLI
+ *  path runs each write that follows an await through it, not only its first one. */
+export declare function admittedWrite<T>(dataDir: string, write: () => T): T;
+/** A durable commit refused by the backstop writes nothing and throws, as on a closed store. */
+export declare function assertProjectWritable(dataDir: string): void;
+/** Whether this process holds the live migration fence of `dataDir`'s project: the project
+ *  migration engine runs only under a fence its own process holds. */
+export declare function holdsProjectFence(dataDir: string): boolean;
+/**
+ * Run `work` as the holder of `fence`: admission and the write backstop pass for this project
+ * inside it, and only inside it, so a cockpit that recovers a journal still refuses its own other
+ * requests for the project meanwhile.
+ */
+export declare function asFenceHolder<T>(fence: Pick<ProjectMigrationFence, 'lock'>, work: () => T): T;
+/** Run `work` unless the project is fenced or has an unfinished journal; then answer `refused`. */
+export declare function withProjectAdmission<T, R>(dataDir: string, work: () => Promise<T>, refused: (error: ProjectMigrationFencedError) => R): Promise<T | R>;
+/** A task that is not terminal: it keeps a project from being fenced for a migration. */
+export interface LiveProjectTask {
+    id: string;
+    title: string;
+    state: string;
+}
+/** The fence was refused: tasks are live. Nothing was claimed or moved. */
+export declare class ProjectMigrationBusyError extends Error {
+    readonly tasks: readonly LiveProjectTask[];
+    readonly project: string;
+    constructor(tasks: readonly LiveProjectTask[], project: string);
+}
+/** A held migration fence: exclusive until `release`, which never removes another owner's claim. */
+export interface ProjectMigrationFence {
+    lock: string;
+    journal: string;
+    release(): void;
+}
+/** The live cockpit other than this process that owns `dataDir`, if any: its pid and, once it
+ *  listens, its URL. Read-only: nothing is claimed. */
+export declare function anotherCockpitOwner(dataDir: string): {
+    pid: number;
+    url?: string;
+} | undefined;
+/** Whether a live cockpit other than this process owns `dataDir`. Read-only: nothing is claimed. */
+export declare function ownedByAnotherCockpit(dataDir: string): boolean;
+/** One owner per cockpit process, shared by boot and lazy project contexts. */
+export declare class CockpitOwnership {
+    private readonly owned;
+    /** Migration fences this instance holds, by lock path. */
+    private readonly fences;
+    private url;
+    /** A long-lived process claim may be borrowed without changing its lifetime. */
+    owns(dataDir: string): boolean;
+    acquire(dataDir: string): Promise<void>;
+    /** `forFence`: the claim a fence holder takes first, which an unfinished journal does not stop. */
+    private claimProject;
+    /** Refuse a fenced project, unless the fence is this instance's own. */
+    private checkMigrationFence;
+    /**
+     * Take the project's exclusive migration fence, offline: own the project (taking `cockpit.lock`
+     * when this instance does not hold it), so no cockpit boots on or builds it, then claim the
+     * fence, so no other process is admitted. Right after the claim, `liveTasks` runs as the holder;
+     * any live task releases the fence and throws `ProjectMigrationBusyError`. Held until `release`.
+     */
+    fenceProject(dataDir: string, options: {
+        liveTasks: () => readonly LiveProjectTask[];
+    }): Promise<ProjectMigrationFence>;
+    /** The claim this instance holds in `directory`, if any. */
+    private ownedClaim;
+    /** A live owner under the project's other directory name; the claimed directory is not checked. */
+    private checkFallbackOwner;
+    publishUrl(url: string): void;
+    /** Only at process exit: managers may still have asynchronous work after dispose. */
+    releaseAll(): void;
+}
+export {};