@qodeca/xezar 0.10.1

package/dist/server/capabilities.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Server capabilities reported by `/api/health` — the UI hides what the server
+ * says isn't there, and the matching endpoints refuse as defense in depth.
+ *
+ * `localHandoff` (cockpit-ui redesign spec §"Deployment modes — local vs
+ * hosted"): the default deployment is `npx @qodeca/xezar` on localhost, where
+ * handing a session off to a local terminal/editor makes sense. On a VPS/remote
+ * box it doesn't: `XEZ_REMOTE=1` (or binding a non-loopback host) switches to
+ * hosted mode — the UI hides every local-machine affordance and the open-in-*
+ * endpoints 409.
+ *
+ * `followups` (spec 007, #444, #471): the global follow-up inbox is **opt-in**
+ * via `XEZ_FOLLOWUPS=1` and off by default. Off, agents are never told to write
+ * `todos.json` (they get `HANDOFF_ONLY_INSTRUCTIONS` and an empty
+ * `XEZ_TODOS_FILE`), the Inbox nav item is gone and the inbox endpoints refuse.
+ * The per-task handoff journal is independent and runs either way.
+ *
+ * `singleProject` (spec 2026-07-21-xez-single-project): the workspace is
+ * deliberately constrained to the launch project when `XEZ_SINGLE_PROJECT=1`.
+ * Like the other opt-in capabilities, activation is strict: no other spelling
+ * enables it.
+ *
+ * `automations` (spec 2026-07-25-github-automations, #801): GitHub automations
+ * are **opt-in** via `XEZ_AUTOMATIONS=1` and off by default. Off, the
+ * `Automations` nav item is gone everywhere it is rendered, the
+ * `/automations*` endpoints refuse, and the workspace scheduler never polls
+ * GitHub — the flag removes the behavior, not only the UI. Activation is
+ * strict, like the two capabilities above. Nothing on disk is touched:
+ * definitions, receipts and high-watermarks survive the flag being off, so
+ * unsetting it and restarting restores the feature wholesale.
+ *
+ * Usage presentation: token counts and monetary cost stay visible by default.
+ * `XEZ_HIDE_TOKEN_USAGE=1` and `XEZ_HIDE_COST=1` hide them independently;
+ * legacy `XEZ_HIDE_TOKEN_METRICS=1` remains the master hide-all switch. None
+ * changes collection, persistence, events, or API run records.
+ */
+import type { Capabilities } from '../contract/index.js';
+/** Canonical hostname of an authority: port and IPv6 brackets removed, IPv6
+ *  expanded, zone id and FQDN trailing dot dropped, lowercased.
+ *  `[::1]:4321` → `0:0:0:0:0:0:0:1`, `localhost.:4321` → `localhost`.
+ *
+ *  Strict by construction: an authority that does not parse as one of the three
+ *  legal shapes returns `''`, which no allowlist matches. Being lax here is a
+ *  security bug, not a convenience — a parser that merely *finds* a loopback
+ *  name inside the header would accept `[::1]@evil.com` or `127.0.0.1:evil.com`. */
+export declare function normalizeHostname(host: string): string;
+/** True for bind hosts that only the local machine can reach. Undefined = the
+ *  default bind (127.0.0.1), hence trusted — this is a *configuration* value we
+ *  chose, not a request header. Do NOT use this on attacker-controlled input;
+ *  use `isLoopbackHostHeader`, which fails closed on a missing host. */
+export declare function isLoopbackHost(host: string | undefined): boolean;
+/** True for a request's `Host`/`Origin` hostname when it names this machine.
+ *  The untrusted-input twin of `isLoopbackHost`: a missing or unparseable host
+ *  is **untrusted** (false), because absent is not the same as "we defaulted to
+ *  loopback" once the value arrives over the wire (#426). */
+export declare function isLoopbackHostHeader(host: string | null | undefined): boolean;
+/** `XEZ_REMOTE=1` or a non-loopback bind host ⇒ hosted mode (no local handoff).
+ *  `XEZ_FOLLOWUPS=1` ⇒ the follow-up inbox exists (#471).
+ *  `XEZ_AUTOMATIONS=1` ⇒ GitHub automations exist (#801).
+ *
+ *  Read per request — cheap, and tests/ops can flip `XEZ_REMOTE` live. `followups` is honest
+ *  per request too, but flipping it ON at runtime is only half a switch: the per-dataDir
+ *  todos watch (step 2.3) is created by an SSE subscription, so connections opened while the
+ *  flag was off never subscribed and get no live inbox updates until they reconnect. Hence
+ *  the UI's "set XEZ_FOLLOWUPS=1 and restart xezar" wording — treat it as a boot-time flag.
+ *
+ *  `automations` carries the same caveat and for the same reason: the workspace scheduler is
+ *  started once, on the server's `listening` event, so flipping the flag on afterwards gates
+ *  the routes open without ever starting the poller. Boot-time flag, same wording. */
+export declare function resolveCapabilities(env?: NodeJS.ProcessEnv, bindHost?: string): Capabilities;

package/dist/server/capabilities.js

@@ -0,0 +1,152 @@
+/**
+ * Server capabilities reported by `/api/health` — the UI hides what the server
+ * says isn't there, and the matching endpoints refuse as defense in depth.
+ *
+ * `localHandoff` (cockpit-ui redesign spec §"Deployment modes — local vs
+ * hosted"): the default deployment is `npx @qodeca/xezar` on localhost, where
+ * handing a session off to a local terminal/editor makes sense. On a VPS/remote
+ * box it doesn't: `XEZ_REMOTE=1` (or binding a non-loopback host) switches to
+ * hosted mode — the UI hides every local-machine affordance and the open-in-*
+ * endpoints 409.
+ *
+ * `followups` (spec 007, #444, #471): the global follow-up inbox is **opt-in**
+ * via `XEZ_FOLLOWUPS=1` and off by default. Off, agents are never told to write
+ * `todos.json` (they get `HANDOFF_ONLY_INSTRUCTIONS` and an empty
+ * `XEZ_TODOS_FILE`), the Inbox nav item is gone and the inbox endpoints refuse.
+ * The per-task handoff journal is independent and runs either way.
+ *
+ * `singleProject` (spec 2026-07-21-xez-single-project): the workspace is
+ * deliberately constrained to the launch project when `XEZ_SINGLE_PROJECT=1`.
+ * Like the other opt-in capabilities, activation is strict: no other spelling
+ * enables it.
+ *
+ * `automations` (spec 2026-07-25-github-automations, #801): GitHub automations
+ * are **opt-in** via `XEZ_AUTOMATIONS=1` and off by default. Off, the
+ * `Automations` nav item is gone everywhere it is rendered, the
+ * `/automations*` endpoints refuse, and the workspace scheduler never polls
+ * GitHub — the flag removes the behavior, not only the UI. Activation is
+ * strict, like the two capabilities above. Nothing on disk is touched:
+ * definitions, receipts and high-watermarks survive the flag being off, so
+ * unsetting it and restarting restores the feature wholesale.
+ *
+ * Usage presentation: token counts and monetary cost stay visible by default.
+ * `XEZ_HIDE_TOKEN_USAGE=1` and `XEZ_HIDE_COST=1` hide them independently;
+ * legacy `XEZ_HIDE_TOKEN_METRICS=1` remains the master hide-all switch. None
+ * changes collection, persistence, events, or API run records.
+ */
+import { followupsEnabled } from '../handoff.js';
+/** Every IPv4 address in 127.0.0.0/8, anchored. Anchoring is load-bearing: a
+ *  `startsWith('127.')` test also matches attacker-controlled *hostnames* like
+ *  `127.0.0.1.evil.com`, which is exactly the DNS-rebinding bypass #426 is
+ *  about — see `isLoopbackHostHeader`. */
+const LOOPBACK_V4 = /^127(?:\.(?:25[0-5]|2[0-4]\d|1?\d?\d)){3}$/;
+/** The IPv6 loopback in the canonical form `expandIpv6` emits. */
+const LOOPBACK_V6 = '0:0:0:0:0:0:0:1';
+/** Expand an IPv6 literal to all 8 groups, lowercase and without leading zeros
+ *  (`::1` → `0:0:0:0:0:0:0:1`), or `null` when it is not a valid literal.
+ *
+ *  Canonicalizing rather than merely *recognizing* matters: `Host` carries
+ *  whatever spelling the client sent, but `new URL().hostname` compresses
+ *  (`[0:0:0:0:0:0:0:1]` → `[::1]`), so the two only compare equal on a common
+ *  form. */
+function expandIpv6(h) {
+    const halves = h.split('::');
+    if (halves.length > 2)
+        return null;
+    let groups;
+    if (halves.length === 2) {
+        const head = halves[0] ? halves[0].split(':') : [];
+        const tail = halves[1] ? halves[1].split(':') : [];
+        if (head.length + tail.length > 7)
+            return null;
+        groups = [...head, ...Array(8 - head.length - tail.length).fill('0'), ...tail];
+    }
+    else {
+        groups = h.split(':');
+    }
+    if (groups.length !== 8 || !groups.every((g) => /^[0-9a-f]{1,4}$/.test(g)))
+        return null;
+    return groups.map((g) => parseInt(g, 16).toString(16)).join(':');
+}
+/** Canonical hostname of an authority: port and IPv6 brackets removed, IPv6
+ *  expanded, zone id and FQDN trailing dot dropped, lowercased.
+ *  `[::1]:4321` → `0:0:0:0:0:0:0:1`, `localhost.:4321` → `localhost`.
+ *
+ *  Strict by construction: an authority that does not parse as one of the three
+ *  legal shapes returns `''`, which no allowlist matches. Being lax here is a
+ *  security bug, not a convenience — a parser that merely *finds* a loopback
+ *  name inside the header would accept `[::1]@evil.com` or `127.0.0.1:evil.com`. */
+export function normalizeHostname(host) {
+    // 1. Bracketed IPv6, optionally with a port: `[::1]`, `[::1%25eth0]:4321`.
+    //    The end anchor is load-bearing — without it `[::1]@evil.com` → `::1`.
+    const bracketed = host.match(/^\[([^\]]+)\](?::\d+)?$/);
+    if (bracketed)
+        return expandIpv6(stripZone(bracketed[1].toLowerCase())) ?? '';
+    // 2. A bare IPv6 literal cannot carry a port (no brackets ⇒ every colon
+    //    belongs to the address), so anything with >1 colon is taken whole.
+    if (host.split(':').length > 2)
+        return expandIpv6(stripZone(host.toLowerCase())) ?? '';
+    // 3. `name` or `name:port`, where the port must actually be digits.
+    const plain = host.match(/^([^:[\]]*)(?::(\d+))?$/);
+    if (plain)
+        return plain[1].toLowerCase().replace(/\.$/, '');
+    return ''; // unparseable ⇒ matches no allowlist
+}
+/** Drop an IPv6 zone id (`fe80::1%eth0`), anchored to the end so a `%` inside a
+ *  registrable hostname can never truncate it down to a loopback name. */
+function stripZone(h) {
+    return h.replace(/%[a-z0-9._~-]+$/, '');
+}
+/** True when the hostname names this machine and nothing else. Expects the
+ *  canonical output of `normalizeHostname`. */
+function isLoopbackName(hostname) {
+    return hostname === 'localhost' || LOOPBACK_V4.test(hostname) || hostname === LOOPBACK_V6;
+}
+/** True for bind hosts that only the local machine can reach. Undefined = the
+ *  default bind (127.0.0.1), hence trusted — this is a *configuration* value we
+ *  chose, not a request header. Do NOT use this on attacker-controlled input;
+ *  use `isLoopbackHostHeader`, which fails closed on a missing host. */
+export function isLoopbackHost(host) {
+    if (!host)
+        return true;
+    return isLoopbackName(normalizeHostname(host));
+}
+/** True for a request's `Host`/`Origin` hostname when it names this machine.
+ *  The untrusted-input twin of `isLoopbackHost`: a missing or unparseable host
+ *  is **untrusted** (false), because absent is not the same as "we defaulted to
+ *  loopback" once the value arrives over the wire (#426). */
+export function isLoopbackHostHeader(host) {
+    if (!host)
+        return false;
+    return isLoopbackName(normalizeHostname(host));
+}
+/** `XEZ_REMOTE=1` or a non-loopback bind host ⇒ hosted mode (no local handoff).
+ *  `XEZ_FOLLOWUPS=1` ⇒ the follow-up inbox exists (#471).
+ *  `XEZ_AUTOMATIONS=1` ⇒ GitHub automations exist (#801).
+ *
+ *  Read per request — cheap, and tests/ops can flip `XEZ_REMOTE` live. `followups` is honest
+ *  per request too, but flipping it ON at runtime is only half a switch: the per-dataDir
+ *  todos watch (step 2.3) is created by an SSE subscription, so connections opened while the
+ *  flag was off never subscribed and get no live inbox updates until they reconnect. Hence
+ *  the UI's "set XEZ_FOLLOWUPS=1 and restart xezar" wording — treat it as a boot-time flag.
+ *
+ *  `automations` carries the same caveat and for the same reason: the workspace scheduler is
+ *  started once, on the server's `listening` event, so flipping the flag on afterwards gates
+ *  the routes open without ever starting the poller. Boot-time flag, same wording. */
+export function resolveCapabilities(env = process.env, bindHost) {
+    const hideAllUsage = env.XEZ_HIDE_TOKEN_METRICS === '1';
+    const tokenUsageMetrics = !hideAllUsage && env.XEZ_HIDE_TOKEN_USAGE !== '1';
+    const costMetrics = !hideAllUsage && env.XEZ_HIDE_COST !== '1';
+    return {
+        localHandoff: env.XEZ_REMOTE !== '1' && isLoopbackHost(bindHost),
+        // Deliberately not re-derived here: RunManager enforces the same predicate,
+        // and two spellings of "is the inbox on" would eventually disagree.
+        followups: followupsEnabled(env),
+        singleProject: env.XEZ_SINGLE_PROJECT === '1',
+        automations: env.XEZ_AUTOMATIONS === '1',
+        tokenMetrics: tokenUsageMetrics && costMetrics,
+        tokenUsageMetrics,
+        costMetrics,
+    };
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/server/capabilities.js.map

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

package/dist/server/checkout.d.ts

@@ -0,0 +1,128 @@
+/** 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;
+}
+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;
+    /** What `gh repo clone` is handed — always the normalized `owner/repo`, so a
+     *  URL spelling can never smuggle flags or a different host past `gh`. */
+    slug: 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;
+/**
+ * Delete a partially-cloned checkout — the ONE destructive path in this module.
+ *
+ * Called only after `mkdir(target)` (non-recursive, so it succeeded only
+ * because the directory did not exist and WE created it). Even with that proof
+ * in hand, every one of these must hold or nothing is deleted:
+ *
+ * - `target` is still a real directory and NOT a symlink (`lstat`, not `stat`):
+ *   between the mkdir and the failure, the directory could have been swapped
+ *   for a link pointing anywhere.
+ * - `projectsDir` and `target` both resolve (`realpath`), and the resolved
+ *   target's PARENT is exactly the resolved checkout root. That is strict
+ *   containment (nothing outside the root) *and* a depth limit (a direct child
+ *   only, never the root itself, never a nested path).
+ *
+ * Any surprise — a vanished path, an unresolvable root, a `rm` that fails —
+ * leaves the directory alone. Leaving a stray folder is a nuisance; deleting
+ * the wrong one is unrecoverable, so every ambiguous case resolves toward "do
+ * nothing".
+ */
+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;
+}>;
+/**
+ * `gh repo clone <owner/repo> <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;
+/** `XEZ_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 `XEZ_DRY_RUN=1`). */
+    run?: CloneRunner;
+}
+/**
+ * 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,296 @@
+import { spawn } from 'node:child_process';
+import { lstat, mkdir, realpath, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+/**
+ * `POST /api/projects/checkout` — the "Add project → Clone from GitHub" flow
+ * (spec 2026-07-20-multi-project-workspace, step 4.3).
+ *
+ * The route itself (server.ts) owns the registry write; this module owns the
+ * only two things that are genuinely dangerous about cloning on the operator's
+ * behalf:
+ *
+ * 1. **Where the clone lands.** The target is always `<projectsDir>/<name>`
+ *    with `name` a single, boring path segment. It is never a nested path,
+ *    never `..`, never absolute — the checkout root is a root, not a starting
+ *    point for traversal.
+ * 2. **What cleanup may delete.** A failed clone must not leave a half-written
+ *    directory behind (a later attempt would trip over it, and registering it
+ *    would put a broken project in the sidebar). But "rm -rf the target" is a
+ *    destructive path reached by a *network failure*, so it is guarded as
+ *    tightly as `fs-browse.ts` guards containment — see `cleanupCheckout`.
+ *
+ * The load-bearing trick for (2) is that the target directory is created HERE,
+ * with a non-recursive `mkdir`, before `gh` ever runs. That single syscall is
+ * both the atomic existence check (EEXIST ⇒ 409, and we never touched what was
+ * there) and the proof of ownership that authorizes cleanup: we only ever
+ * delete a directory this operation is known to have created.
+ */
+/** 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. */
+const ERROR_TAIL_LINES = 6;
+/** `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}` };
+}
+/**
+ * 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('\\');
+}
+/**
+ * Delete a partially-cloned checkout — the ONE destructive path in this module.
+ *
+ * Called only after `mkdir(target)` (non-recursive, so it succeeded only
+ * because the directory did not exist and WE created it). Even with that proof
+ * in hand, every one of these must hold or nothing is deleted:
+ *
+ * - `target` is still a real directory and NOT a symlink (`lstat`, not `stat`):
+ *   between the mkdir and the failure, the directory could have been swapped
+ *   for a link pointing anywhere.
+ * - `projectsDir` and `target` both resolve (`realpath`), and the resolved
+ *   target's PARENT is exactly the resolved checkout root. That is strict
+ *   containment (nothing outside the root) *and* a depth limit (a direct child
+ *   only, never the root itself, never a nested path).
+ *
+ * Any surprise — a vanished path, an unresolvable root, a `rm` that fails —
+ * leaves the directory alone. Leaving a stray folder is a nuisance; deleting
+ * the wrong one is unrecoverable, so every ambiguous case resolves toward "do
+ * nothing".
+ */
+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;
+    }
+}
+/**
+ * `gh repo clone <owner/repo> <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', ['repo', 'clone', ref.slug, dir, '--', '--progress'], {
+        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' },
+    });
+    const tail = [];
+    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.
+    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);
+        }
+    };
+    child.stderr?.setEncoding('utf8');
+    child.stderr?.on('data', consume);
+    child.stdout?.setEncoding('utf8');
+    child.stdout?.on('data', 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) => {
+        signal?.removeEventListener('abort', onAbort);
+        if (code === 0)
+            return finish({ ok: true });
+        // 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 = tail.join('\n').trim();
+        finish({ ok: false, error: detail === '' ? `gh repo clone exited with code ${code}` : detail });
+    });
+});
+/** `XEZ_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(XEZ_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)}` };
+    }
+    if (!opts.projectsDir.startsWith('/')) {
+        return { ok: false, status: 500, error: `checkout root is not an absolute path: ${opts.projectsDir}` };
+    }
+    const root = resolve(opts.projectsDir);
+    const target = join(root, name);
+    // 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 ?? (process.env.XEZ_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