@hellix-ai/cubes 0.2.2 → 0.3.0

package/dist/form.js

@@ -0,0 +1,309 @@
+// The New session form, in a terminal - the web dialog's questions, in the web dialog's terms.
+//
+// ⚠ ASKED FOR: "it should ask me which org, and all the other session creation form stuff, and any
+// future session creation feature must be supported also here".
+//
+// So this mirrors web/src/pages/SessionsPage.tsx `NewSessionDialog` field for field, with the same
+// defaults and the same rules between fields:
+//   • a GROUP pre-selects its default repositories (until you pick some yourself - here, by asking
+//     the group first);
+//   • the ORG's model list, with its default model listed once and meaning "follow the default";
+//   • an AGENT that declares a model decides the model (two that disagree leave it to you), and
+//     exactly one agent puts `--agent "<name>"` into the extra CLI args, where you can see it;
+//   • the RUNNER preselected is the one the server would resolve, and the choice on screen is sent;
+//   • Remote Control defaults ON, as in the dialog.
+// The server re-checks every one of these (the create route is the authority); this only asks.
+//
+// "ANY FUTURE FEATURE" is enforced, not hoped for: `SPEC_FIELDS` must name every field of the
+// request, TypeScript refuses this file if `SessionSpec` gains one it does not, and
+// test/form.test.ts reads the web's own `SessionSpec` (web/src/cubes/cubesApi.ts) and fails when
+// the two disagree. A field the dialog grows therefore cannot ship without this form learning it.
+import { CliError } from "./auth.js";
+/** How this CLI fills each field of the request. EVERY key, so a new field is a compile error here
+ *  until somebody decides how the terminal asks for it. */
+export const SPEC_FIELDS = {
+    title: "asked (--title)",
+    repoIds: "asked (--repo, repeatable)",
+    groupId: "asked (--group)",
+    cubeDefId: "asked (--cube)",
+    cubeInputs: "asked per cube input (--input name=value)",
+    agentNames: "asked (--agent, repeatable)",
+    model: "asked (--model)",
+    runnerId: "asked (--runner)",
+    rcEnabled: "asked (--rc / --no-rc)",
+    cliArgs: "asked (--cli-args)",
+    packageId: "--package (the dialog does not offer it)",
+    mcpServers: "--mcp-config FILE (the dialog does not offer it)",
+    hooks: "--hooks FILE (the dialog does not offer it)",
+    repoId: "superseded by repoIds; never sent",
+    importId: "the uploaded conversation (cubes import)",
+};
+export const TITLE_MAX = 80;
+/** web/src/cubes/agentCliArg.ts, the same text: one agent's flag. */
+export function agentFlag(name) {
+    return `--agent "${name}"`;
+}
+/** web/src/cubes/agentCliArg.ts `withAgentFlag`: `args` with its `--agent` set to `name`, or
+ *  removed when `name` is null; the rest of the field is left alone. */
+export function withAgentFlag(args, name) {
+    const stripped = args
+        .replace(/(^|\s)--agent(?:=(?:"[^"]*"|'[^']*'|\S*)|\s+(?:"[^"]*"|'[^']*'|[^\s-]\S*)?)?(?=\s|$)/g, "$1")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (!name)
+        return stripped;
+    return stripped ? `${stripped} ${agentFlag(name)}` : agentFlag(name);
+}
+/** web/src/cubes/agentModelLock.ts: the model the picked agents decide, if they agree on one.
+ *  `inherit` and blank are "no opinion"; strings are compared exactly. */
+export function agentModelLock(picks) {
+    const order = [];
+    const by = new Map();
+    for (const p of picks) {
+        const v = (p.model ?? "").trim();
+        if (!v || v.toLowerCase() === "inherit")
+            continue;
+        const seen = by.get(v);
+        if (seen)
+            seen.push(p.name);
+        else {
+            by.set(v, [p.name]);
+            order.push(v);
+        }
+    }
+    if (order.length === 0)
+        return { kind: "free" };
+    if (order.length === 1)
+        return { kind: "locked", model: order[0], by: by.get(order[0]) };
+    return { kind: "conflict", choices: order.map((m) => ({ model: m, by: by.get(m) })) };
+}
+const joinNames = (n) => (n.length <= 1 ? n[0] ?? "" : `${n.slice(0, -1).join(", ")} and ${n[n.length - 1]}`);
+/** A thing named on the command line: its id, or its name (case-insensitively), exactly one. */
+function byNameOrId(items, want, nameOf, what) {
+    const w = want.trim().toLowerCase();
+    const hit = items.filter((t) => t.id.toLowerCase() === w);
+    const named = hit.length ? hit : items.filter((t) => nameOf(t).some((n) => n.toLowerCase() === w));
+    if (named.length === 1)
+        return named[0];
+    if (named.length > 1)
+        throw new CliError(`"${want}" names ${named.length} ${what}s - use its id`);
+    const known = items.slice(0, 12).map((t) => nameOf(t)[0]).join(", ");
+    throw new CliError(`no ${what} "${want}"${items.length ? ` (there is: ${known}${items.length > 12 ? ", ..." : ""})` : ` - this org has none`}`);
+}
+const quiet = (p) => p.catch(() => null);
+/**
+ * Ask everything the New session dialog asks, take what the command line already answered, and return
+ * the request. `ask` is the terminal (or, for --yes, a prompter that takes every default).
+ */
+export async function sessionForm(api, ask, flags, ctx = {}) {
+    // Everything the dialog reads on open, at once. A list that cannot be read omits its question,
+    // exactly as the dialog omits a picker it could not fill - except repositories, where "could not
+    // ask" must not read as "you have none".
+    const [repos, groupsRes, models, runnersRes, cubes, agentRepo] = await Promise.all([
+        quiet(api.get("/scm/repos")),
+        quiet(api.get("/session-groups")),
+        quiet(api.get("/org/models")),
+        quiet(api.get("/org/runners")),
+        quiet(api.get("/node-defs")),
+        quiet(api.get("/scm/agent-repo")),
+    ]);
+    const groups = groupsRes?.groups ?? [];
+    const runners = (runnersRes?.runners ?? []).filter((r) => r.enabled);
+    // ── title ──
+    let title = flags.title?.trim() ?? "";
+    const suggested = (ctx.suggestedTitle ?? "").replace(/\s+/g, " ").trim().slice(0, TITLE_MAX);
+    while (!title) {
+        title = (await ask.text("Title", suggested || undefined)).trim();
+        if (!title)
+            ask.note("  a session needs a title");
+    }
+    if (title.length > TITLE_MAX)
+        throw new CliError(`the title is ${title.length} characters; at most ${TITLE_MAX}`);
+    // ── group (asked before the repositories, because it pre-selects them) ──
+    let group = null;
+    if (flags.group)
+        group = byNameOrId(groups, flags.group, (g) => [g.name], "group");
+    else if (groups.length) {
+        group = await ask.select("Group", [
+            { label: "No group", value: null },
+            ...groups.map((g) => ({ label: g.name, value: g, hint: g.repo_ids?.length ? `${g.repo_ids.length} default repo${g.repo_ids.length === 1 ? "" : "s"}` : undefined })),
+        ], 0);
+    }
+    // ── repositories (optional) ──
+    let repoIds = [];
+    if (flags.repos?.length) {
+        if (!repos)
+            throw new CliError("could not read this org's repositories to look those up");
+        repoIds = [...new Set(flags.repos.map((r) => byNameOrId(repos, r, (x) => [x.full_name, x.full_name.split("/").pop() ?? ""], "repository").id))];
+    }
+    else if (repos === null) {
+        repoIds = group?.repo_ids ?? [];
+        ask.note(`Couldn't load your repositories. This is not the same as having none${repoIds.length ? " - the group's defaults will still be checked out" : ""}.`);
+    }
+    else if (!repos.length) {
+        ask.note("No repositories connected - this session will start in an empty working directory.");
+    }
+    else {
+        const hints = new Set((ctx.repoHints ?? []).map((h) => h.toLowerCase()));
+        const defaults = new Set(group?.repo_ids ?? []);
+        for (const r of repos)
+            if (hints.has(r.full_name.toLowerCase()))
+                defaults.add(r.id);
+        const choices = repos.map((r) => ({
+            label: r.full_name, value: r.id,
+            hint: hints.has(r.full_name.toLowerCase()) ? "this conversation's checkout" : undefined,
+        }));
+        repoIds = await ask.multi("Repositories (each is checked out into its own folder; none = an empty directory)", choices, repos.flatMap((r, i) => (defaults.has(r.id) ? [i] : [])));
+    }
+    // ── start from a cube (optional) ──
+    let cube = null;
+    {
+        let pick = null;
+        if (flags.cube) {
+            if (!cubes)
+                throw new CliError("could not read this org's cube library to look that up");
+            pick = byNameOrId(cubes, flags.cube, (c) => [c.name], "cube");
+        }
+        else if (cubes?.length) {
+            pick = await ask.select("Start from a cube (its prompt is the session's next turn)", [
+                { label: "No cube", value: null },
+                ...cubes.map((c) => ({ label: c.name, value: c, hint: c.description ? c.description.slice(0, 60) : undefined })),
+            ], 0);
+        }
+        if (pick) {
+            const def = await api.get(`/node-defs/${encodeURIComponent(pick.id)}`);
+            const inputs = {};
+            for (const inp of def.inputs ?? []) {
+                const given = flags.inputs?.[inp.name];
+                inputs[inp.name] = given !== undefined ? given : await ask.text(`  ${inp.title || inp.name}`, inp.default);
+            }
+            for (const k of Object.keys(flags.inputs ?? {})) {
+                if (!(def.inputs ?? []).some((i) => i.name === k))
+                    throw new CliError(`the cube "${def.name}" has no input "${k}"`);
+            }
+            cube = { defId: def.id, name: def.name, inputs };
+        }
+        else if (flags.inputs && Object.keys(flags.inputs).length) {
+            throw new CliError("--input fills a cube's inputs; pass --cube too");
+        }
+    }
+    // ── agents (optional; only when the org has an agents repository) ──
+    let agents = [];
+    {
+        const catalog = agentRepo?.repo
+            ? await quiet(api.get(`/scm/repos/${encodeURIComponent(agentRepo.repo.repoId)}/agents`))
+            : null;
+        // A name declared by two files is a name nobody can pick - the dialog shows it disabled.
+        const count = new Map();
+        for (const a of catalog?.agents ?? [])
+            count.set(a.name, (count.get(a.name) ?? 0) + 1);
+        const pickable = (catalog?.agents ?? []).filter((a) => count.get(a.name) === 1);
+        if (flags.agents?.length) {
+            if (!catalog)
+                throw new CliError("this org has no agents repository to pick agents from");
+            agents = flags.agents.map((n) => {
+                if ((count.get(n) ?? 0) > 1)
+                    throw new CliError(`the agent "${n}" is declared by more than one file in the agents repository`);
+                const a = pickable.find((x) => x.name === n);
+                if (!a)
+                    throw new CliError(`no agent "${n}" (there is: ${pickable.map((x) => x.name).join(", ") || "none"})`);
+                return a;
+            });
+        }
+        else if (pickable.length) {
+            agents = await ask.multi("Agents it can delegate to", pickable.map((a) => ({
+                label: a.name, value: a,
+                hint: [a.model && a.model !== "inherit" ? a.model : "", (a.description ?? "").slice(0, 50)].filter(Boolean).join(" - ") || undefined,
+            })), []);
+        }
+    }
+    // ── model ──
+    let model = null;
+    const lock = agentModelLock(agents);
+    if (lock.kind === "locked") {
+        if (flags.model && flags.model !== lock.model) {
+            throw new CliError(`${joinNames(lock.by)} declares ${lock.model}, so the session starts on it; drop --model or the agent`);
+        }
+        model = lock.model;
+        ask.note(`Model: ${lock.model} (set by ${joinNames(lock.by)})`);
+    }
+    else {
+        if (lock.kind === "conflict") {
+            ask.note(`${lock.choices.map((c) => `${joinNames(c.by)} asks for ${c.model}`).join("; ")}. They disagree, so this stays your choice - each agent still runs on the model it declares.`);
+        }
+        if (flags.model) {
+            model = flags.model === "default" ? null : flags.model;
+        }
+        else if (models?.options?.length) {
+            const def = models.defaultModel ?? models.platformDefault ?? null;
+            const listed = !!def && models.options.some((m) => m.id === def);
+            // The default model listed ONCE: its own row, tagged default, meaning "follow the default".
+            const choices = listed
+                ? models.options.map((m) => ({ label: m.label, value: m.id === def ? null : m.id, hint: m.id === def ? "default" : undefined }))
+                : [{ label: def ? def : "Default", value: null, hint: "default" }, ...models.options.map((m) => ({ label: m.label, value: m.id }))];
+            model = await ask.select("Model", choices, Math.max(0, choices.findIndex((c) => c.value === null)));
+        }
+    }
+    // ── where it runs ──
+    let runnerId = null;
+    if (runners.length) {
+        const q = new URLSearchParams();
+        if (group)
+            q.set("groupId", group.id);
+        const resolved = await quiet(api.get(`/org/runners/resolve${q.size ? `?${q}` : ""}`));
+        if (resolved?.problem)
+            ask.note(`Runner: ${resolved.problem}`);
+        if (flags.runner)
+            runnerId = byNameOrId(runners, flags.runner, (r) => [r.name], "runner").id;
+        else {
+            const def = Math.max(0, runners.findIndex((r) => r.id === resolved?.runnerId));
+            const sourceHint = { group: "the group's", org: "the org default", only: "the only one", package: "the package's", folder: "the folder's" };
+            runnerId = await ask.select("Runner", runners.map((r) => ({
+                label: r.name, value: r.id,
+                hint: r.id === resolved?.runnerId ? sourceHint[resolved.source] ?? undefined : undefined,
+            })), def);
+        }
+    }
+    // ── Remote Control (on by default, as in the dialog) ──
+    const rcEnabled = flags.rc ?? await ask.confirm("Remote Control (run /login, then /rc, once it starts)", true);
+    // ── extra claude CLI args ──
+    const sole = agents.length === 1 ? agents[0].name : null;
+    let cliArgs = withAgentFlag(flags.cliArgs ?? "", sole);
+    if (flags.cliArgs === undefined)
+        cliArgs = (await ask.text("Extra claude CLI args", cliArgs || undefined)).trim();
+    const spec = {
+        title,
+        model,
+        repoIds,
+        cliArgs: cliArgs || null,
+        groupId: group?.id ?? null,
+        ...(rcEnabled ? { rcEnabled: true } : {}),
+        ...(cube ? { cubeDefId: cube.defId, cubeInputs: cube.inputs } : {}),
+        ...(agents.length ? { agentNames: agents.map((a) => a.name) } : {}),
+        ...(runnerId ? { runnerId } : {}),
+        ...(flags.packageId ? { packageId: flags.packageId } : {}),
+        ...(flags.mcpServers ? { mcpServers: flags.mcpServers } : {}),
+        ...(flags.hooks ? { hooks: flags.hooks } : {}),
+    };
+    // What a person reads before saying yes, in names rather than ids.
+    const repoName = new Map((repos ?? []).map((r) => [r.id, r.full_name]));
+    const summary = [`  Title    ${title}`];
+    summary.push(`  Repos    ${repoIds.length ? repoIds.map((id) => repoName.get(id) ?? id).join(", ") : "none (an empty directory)"}`);
+    if (group)
+        summary.push(`  Group    ${group.name}`);
+    if (cube)
+        summary.push(`  Cube     ${cube.name}`);
+    if (agents.length)
+        summary.push(`  Agents   ${agents.map((a) => a.name).join(", ")}`);
+    const labelOf = (id) => models?.options?.find((m) => m.id === id)?.label ?? id;
+    const orgDefault = models?.defaultModel ?? models?.platformDefault ?? null;
+    summary.push(`  Model    ${model ? labelOf(model) : orgDefault ? `${labelOf(orgDefault)} (the org default)` : "the org default"}`);
+    if (runnerId)
+        summary.push(`  Runner   ${runners.find((r) => r.id === runnerId)?.name ?? runnerId}`);
+    summary.push(`  Remote   ${rcEnabled ? "on" : "off"}`);
+    if (cliArgs)
+        summary.push(`  Args     ${cliArgs}`);
+    if (flags.packageId)
+        summary.push(`  Package  ${flags.packageId}`);
+    return { spec, summary };
+}

package/dist/local.js

@@ -0,0 +1,251 @@
+// The Claude Code conversations on THIS computer: finding one to import, and filing an exported one
+// where `claude --resume` will find it.
+//
+// Claude Code keeps one JSONL per conversation at
+//
+//     <config dir>/projects/<escaped cwd>/<conversation id>.jsonl
+//
+// where the config dir is $CLAUDE_CONFIG_DIR or ~/.claude, and the escaped cwd is the directory the
+// conversation ran in with every character that is not a letter or a digit replaced by "-" (the same
+// rule the Cubes server uses for a session's own transcripts). Subagent transcripts live in a
+// directory beside the file and are not part of the conversation `--resume` reads, so they are neither
+// listed nor carried.
+//
+// Nothing here parses a conversation beyond its first and last few kilobytes: enough to say where it
+// ran and what it was about, so a person can tell one from another in a list.
+import { existsSync } from "node:fs";
+import { mkdir, open, readdir, rename, stat, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join, resolve, sep } from "node:path";
+import { CliError } from "./auth.js";
+export function claudeConfigDir(env = process.env) {
+    return env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+}
+/** Claude Code's project-directory name for a working directory. */
+export function escapeCwd(cwd) {
+    return cwd.replace(/[^A-Za-z0-9]/g, "-");
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const isConversationId = (s) => UUID.test(s);
+/** Every conversation file, newest first, without reading inside any of them. */
+export async function listConversationFiles(configDir) {
+    const root = join(configDir, "projects");
+    let dirs;
+    try {
+        dirs = await readdir(root);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const d of dirs) {
+        let names;
+        try {
+            names = await readdir(join(root, d));
+        }
+        catch {
+            continue;
+        }
+        for (const n of names) {
+            if (!n.endsWith(".jsonl"))
+                continue;
+            const id = n.slice(0, -".jsonl".length);
+            if (!UUID.test(id))
+                continue;
+            const path = join(root, d, n);
+            try {
+                const st = await stat(path);
+                if (!st.isFile() || st.size === 0)
+                    continue;
+                out.push({ id, path, bytes: st.size, mtime: st.mtimeMs });
+            }
+            catch { /* vanished between the listing and the stat */ }
+        }
+    }
+    return out.sort((a, b) => b.mtime - a.mtime);
+}
+const PEEK = 64 * 1024;
+async function readWindow(path, from, len) {
+    const fh = await open(path, "r");
+    try {
+        const buf = Buffer.alloc(len);
+        const { bytesRead } = await fh.read(buf, 0, len, from);
+        return buf.subarray(0, bytesRead).toString("utf8");
+    }
+    finally {
+        await fh.close().catch(() => { });
+    }
+}
+/** Lines that are whole JSON records. A window cuts its first and last line; those are dropped. */
+function records(text, cutHead, cutTail) {
+    const lines = text.split("\n");
+    if (cutHead)
+        lines.shift();
+    if (cutTail)
+        lines.pop();
+    const out = [];
+    for (const l of lines) {
+        if (!l)
+            continue;
+        try {
+            const r = JSON.parse(l);
+            if (r && typeof r === "object" && !Array.isArray(r))
+                out.push(r);
+        }
+        catch { /* a line still being written */ }
+    }
+    return out;
+}
+/** The text a person typed in a user record, or null for tool results, commands and meta turns. */
+function typedText(rec) {
+    if (rec.type !== "user" || rec.isMeta === true || rec.isSidechain === true)
+        return null;
+    const content = rec.message?.content;
+    let text = null;
+    if (typeof content === "string")
+        text = content;
+    else if (Array.isArray(content)) {
+        const first = content.find((b) => b && typeof b === "object" && b.type === "text");
+        if (first && typeof first.text === "string")
+            text = first.text;
+    }
+    if (!text)
+        return null;
+    const t = text.trim();
+    // Slash commands and their output are recorded as tagged user turns; they are not what it was about.
+    if (!t || t.startsWith("<") || t.startsWith("Caveat:"))
+        return null;
+    return t.replace(/\s+/g, " ");
+}
+/** Read what a conversation says about itself from its head and its tail. */
+export async function describeConversation(f) {
+    const head = records(await readWindow(f.path, 0, Math.min(PEEK, f.bytes)), false, f.bytes > PEEK);
+    const tailFrom = Math.max(0, f.bytes - PEEK);
+    const tail = tailFrom > 0 ? records(await readWindow(f.path, tailFrom, PEEK), true, false) : head;
+    let cwd = null;
+    let gitBranch = null;
+    let firstPrompt = null;
+    for (const r of head) {
+        if (!cwd && typeof r.cwd === "string")
+            cwd = r.cwd;
+        if (!gitBranch && typeof r.gitBranch === "string" && r.gitBranch)
+            gitBranch = r.gitBranch;
+        if (!firstPrompt)
+            firstPrompt = typedText(r);
+        if (cwd && firstPrompt)
+            break;
+    }
+    // Titles are re-recorded as a conversation goes on; the LAST one of each kind is the current one,
+    // and a name the person chose outranks one Claude made up.
+    const last = {};
+    for (const r of [...head, ...tail]) {
+        if (r.type === "custom-title" && typeof r.customTitle === "string")
+            last.custom = r.customTitle;
+        else if (r.type === "agent-name" && typeof r.agentName === "string")
+            last.agent = r.agentName;
+        else if (r.type === "ai-title" && typeof r.aiTitle === "string")
+            last.ai = r.aiTitle;
+        else if (r.type === "summary" && typeof r.summary === "string")
+            last.summary = r.summary;
+        if (typeof r.cwd === "string")
+            cwd = r.cwd;
+    }
+    const title = (last.custom ?? last.agent ?? last.ai ?? last.summary ?? "").trim() || null;
+    return { ...f, cwd, gitBranch, title, firstPrompt };
+}
+/** The conversations worth offering, most recent first: those that ran in `cwd` ahead of the rest. */
+export async function recentConversations(configDir, opts = {}) {
+    const limit = opts.limit ?? 20;
+    const files = await listConversationFiles(configDir);
+    const here = opts.cwd ? join(configDir, "projects", escapeCwd(resolve(opts.cwd))) : null;
+    const ordered = here
+        ? [...files.filter((f) => f.path.startsWith(`${here}${sep}`)), ...files.filter((f) => !f.path.startsWith(`${here}${sep}`))]
+        : files;
+    return Promise.all(ordered.slice(0, limit).map(describeConversation));
+}
+/**
+ * Turn what someone typed into ONE conversation: a path to a .jsonl, its id, or the start of its id
+ * (4+ characters). Ambiguity is an error naming the candidates, never a guess.
+ */
+export async function resolveConversation(configDir, query) {
+    const q = query.trim();
+    if (!q)
+        throw new CliError("which conversation? pass its id, the start of it, or the path to its .jsonl");
+    if (q.endsWith(".jsonl") || q.includes("/") || q.includes("\\")) {
+        const path = resolve(q);
+        let st;
+        try {
+            st = await stat(path);
+        }
+        catch {
+            throw new CliError(`no such file: ${path}`);
+        }
+        const id = basename(path).replace(/\.jsonl$/, "");
+        if (!UUID.test(id))
+            throw new CliError(`${basename(path)} is not named like a Claude Code conversation (<uuid>.jsonl)`);
+        return describeConversation({ id, path, bytes: st.size, mtime: st.mtimeMs });
+    }
+    const files = await listConversationFiles(configDir);
+    const lower = q.toLowerCase();
+    const hits = files.filter((f) => f.id.toLowerCase() === lower);
+    const pre = hits.length ? hits : lower.length >= 4 ? files.filter((f) => f.id.toLowerCase().startsWith(lower)) : [];
+    if (pre.length === 1)
+        return describeConversation(pre[0]);
+    if (pre.length > 1) {
+        const ids = pre.slice(0, 8).map((f) => `  ${f.id}  ${f.path}`).join("\n");
+        throw new CliError(`"${q}" matches ${pre.length} conversations:\n${ids}\nuse more of the id`);
+    }
+    throw new CliError(`no conversation matches "${q}" in ${join(configDir, "projects")}`);
+}
+/** Where `claude --resume <id>`, run in `cwd`, looks for a conversation. */
+export function exportTarget(configDir, cwd, conversationId) {
+    return join(configDir, "projects", escapeCwd(resolve(cwd)), `${conversationId}.jsonl`);
+}
+/**
+ * Put a downloaded conversation in place, safely.
+ *
+ * ⚠ NEVER OVER LOCAL WORK. Exporting the same session twice is the ordinary case and simply brings the
+ * file up to date - but if the copy already here has turns the download does not (it was continued on
+ * this computer since the last export), replacing it would delete them. So an existing file is
+ * replaced only when it is a PREFIX of the download, unless `force`.
+ */
+export async function placeExport(downloaded, target, force) {
+    await mkdir(join(target, ".."), { recursive: true });
+    if (existsSync(target)) {
+        const [here, there] = await Promise.all([stat(target), stat(downloaded)]);
+        if (!force) {
+            const prefix = here.size <= there.size && await isPrefix(target, downloaded, here.size);
+            if (!prefix) {
+                await rm(downloaded, { force: true });
+                throw new CliError(`${target} already exists and has turns this export does not - it was continued on this computer. `
+                    + "Pass --force to replace it, or --dir to export it under another directory.");
+            }
+            if (here.size === there.size) {
+                await rm(downloaded, { force: true });
+                return "unchanged";
+            }
+        }
+        await rename(downloaded, target);
+        return "updated";
+    }
+    await rename(downloaded, target);
+    return "created";
+}
+async function isPrefix(a, b, len) {
+    const [fa, fb] = await Promise.all([open(a, "r"), open(b, "r")]);
+    try {
+        const size = 1024 * 1024;
+        const ba = Buffer.alloc(size);
+        const bb = Buffer.alloc(size);
+        for (let at = 0; at < len; at += size) {
+            const n = Math.min(size, len - at);
+            const [ra, rb] = await Promise.all([fa.read(ba, 0, n, at), fb.read(bb, 0, n, at)]);
+            if (ra.bytesRead !== n || rb.bytesRead !== n || !ba.subarray(0, n).equals(bb.subarray(0, n)))
+                return false;
+        }
+        return true;
+    }
+    finally {
+        await Promise.all([fa.close(), fb.close()]).catch(() => { });
+    }
+}

package/dist/prompt.js

@@ -0,0 +1,117 @@
+// Asking questions in a terminal: line-based, numbered, Enter takes the default.
+//
+// Deliberately not a full-screen picker. The session form runs before anything is attached, in
+// whatever terminal the person has (Warp, a plain ssh, a CI log when piped), and a numbered list read
+// with one line of input works in every one of them. Questions go to stderr so stdout stays clean.
+//
+// Behind an interface so the form can be driven by a script in tests.
+import { createInterface } from "node:readline/promises";
+import { CliError } from "./auth.js";
+/** "1 3", "1,3", "2-4", "1, 3-5" -> zero-based indexes, or null when it does not parse. */
+export function parseNumbers(answer, count) {
+    const out = new Set();
+    for (const part of answer.split(/[\s,]+/).filter(Boolean)) {
+        const m = /^(\d+)(?:-(\d+))?$/.exec(part);
+        if (!m)
+            return null;
+        const a = Number(m[1]);
+        const b = m[2] ? Number(m[2]) : a;
+        if (a < 1 || b > count || a > b)
+            return null;
+        for (let i = a; i <= b; i++)
+            out.add(i - 1);
+    }
+    return [...out].sort((x, y) => x - y);
+}
+export function terminalPrompter(input = process.stdin, output = process.stderr, color = !process.env.NO_COLOR && !!output.isTTY) {
+    const dim = (t) => (color ? `\x1b[2m${t}\x1b[0m` : t);
+    const bold = (t) => (color ? `\x1b[1m${t}\x1b[0m` : t);
+    const ask = async (q) => {
+        const rl = createInterface({ input, output, terminal: input.isTTY ?? false });
+        // Ctrl-C at a question leaves the whole command, not just the question.
+        rl.on("SIGINT", () => { rl.close(); output.write("\n"); process.exit(130); });
+        try {
+            return (await rl.question(q)).trim();
+        }
+        catch (e) {
+            // Ctrl-D (end of input) at a question: nothing more is coming, so stop here, plainly.
+            if (e.code === "ABORT_ERR")
+                throw new CliError("cancelled - nothing was started");
+            throw e;
+        }
+        finally {
+            rl.close();
+        }
+    };
+    const list = (choices, marked) => {
+        const w = String(choices.length).length;
+        choices.forEach((c, i) => {
+            const mark = marked(i) ? "*" : " ";
+            output.write(`  ${mark} ${String(i + 1).padStart(w)}) ${c.label}${c.hint ? `  ${dim(c.hint)}` : ""}\n`);
+        });
+    };
+    return {
+        async text(question, def) {
+            const a = await ask(`${bold(question)}${def ? ` ${dim(`[${def}]`)}` : ""}: `);
+            return a || def || "";
+        },
+        async confirm(question, def) {
+            for (;;) {
+                const a = (await ask(`${bold(question)} ${dim(def ? "[Y/n]" : "[y/N]")} `)).toLowerCase();
+                if (!a)
+                    return def;
+                if (a === "y" || a === "yes")
+                    return true;
+                if (a === "n" || a === "no")
+                    return false;
+            }
+        },
+        async select(question, choices, def = 0) {
+            if (!choices.length)
+                throw new CliError(`nothing to choose from for "${question}"`);
+            output.write(`${bold(question)}\n`);
+            list(choices, (i) => i === def);
+            for (;;) {
+                const a = await ask(`  ${dim(`number, Enter for ${def + 1}`)}: `);
+                if (!a)
+                    return choices[def].value;
+                const n = Number(a);
+                if (Number.isInteger(n) && n >= 1 && n <= choices.length)
+                    return choices[n - 1].value;
+                output.write(`  ${dim(`pick 1-${choices.length}`)}\n`);
+            }
+        },
+        async multi(question, choices, defs) {
+            output.write(`${bold(question)}\n`);
+            list(choices, (i) => defs.includes(i));
+            for (;;) {
+                const a = await ask(`  ${dim(`numbers like "1 3" or "2-4", - for none, Enter keeps ${defs.length ? "the * ones" : "none"}`)}: `);
+                if (!a)
+                    return defs.map((i) => choices[i].value);
+                if (a === "-")
+                    return [];
+                const picked = parseNumbers(a, choices.length);
+                if (picked)
+                    return picked.map((i) => choices[i].value);
+                output.write(`  ${dim(`numbers between 1 and ${choices.length}`)}\n`);
+            }
+        },
+        note(line) {
+            output.write(`${dim(line)}\n`);
+        },
+    };
+}
+/** For `--yes` and for scripts: every question takes its default, and says so. */
+export function defaultsPrompter(output = process.stderr) {
+    return {
+        text: async (_q, def) => def ?? "",
+        confirm: async (_q, def) => def,
+        select: async (q, choices, def = 0) => {
+            if (!choices.length)
+                throw new CliError(`nothing to choose from for "${q}"`);
+            return choices[def].value;
+        },
+        multi: async (_q, choices, defs) => defs.map((i) => choices[i].value),
+        note: (line) => { output.write(`${line}\n`); },
+    };
+}