@illuminis/comprism 0.1.3 → 0.1.5

package/out/lib/output.d.ts

@@ -0,0 +1,48 @@
+/**
+ * How a one request job writes its result for a script (manual 10.2, 10.3,
+ * Appendix B).
+ *
+ * Nothing here decides how a job ended. The service sends a reason word and
+ * the table that turns reason words into exit numbers, and this looks the word
+ * up. The only numbers known here are for the endings that happen when the
+ * service never answered: a typing mistake, no sign in, no connection, Ctrl+C.
+ */
+export type Format = 'text' | 'json' | 'stream';
+export interface OutputChoice {
+    format: Format;
+    /** Only the answer on standard output, even at a terminal (10.2). */
+    quiet: boolean;
+    /** Standard output is a file or a pipe: only the result goes there. */
+    plain: boolean;
+}
+export declare const FORMATS: Format[];
+/** Read `--output` and `--quiet`. Null format means a value nobody accepts. */
+export declare function outputChoice(args: string[]): OutputChoice | {
+    bad: string;
+};
+/** Whether progress belongs on standard error rather than standard output. */
+export declare function progressToErr(o: OutputChoice): boolean;
+/** The exit number for a reason, from the service's table when it sent one. */
+export declare function exitFor(reason: string, table?: Record<string, number> | null): number;
+/** The result object for an ending the service never saw, in its published
+ *  shape: every field present, nothing known left as anything but null. */
+export declare function localResult(reason: string, error: string): Record<string, unknown>;
+/**
+ * Read a JSON file named on the line (`--schema`, `--config`): a permitted
+ * local read. The service decides what the contents mean.
+ */
+export declare function readJsonFile(path: string, flagName: string): {
+    value: Record<string, unknown>;
+} | {
+    bad: string;
+};
+/** Print the result object as one line of JSON on standard output. */
+export declare function printJson(result: Record<string, unknown>): void;
+/**
+ * Refuse a flag this command does not know (Appendix B, exit 2).
+ *
+ * `known` lists flags that take a value; `switches` lists flags that do not.
+ * A word that is a flag's value is skipped, so a request that happens to
+ * follow `--model` is never read as a flag.
+ */
+export declare function unknownFlag(args: string[], known: string[], switches: string[]): string | null;

package/out/lib/output.js

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * How a one request job writes its result for a script (manual 10.2, 10.3,
+ * Appendix B).
+ *
+ * Nothing here decides how a job ended. The service sends a reason word and
+ * the table that turns reason words into exit numbers, and this looks the word
+ * up. The only numbers known here are for the endings that happen when the
+ * service never answered: a typing mistake, no sign in, no connection, Ctrl+C.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FORMATS = void 0;
+exports.outputChoice = outputChoice;
+exports.progressToErr = progressToErr;
+exports.exitFor = exitFor;
+exports.localResult = localResult;
+exports.readJsonFile = readJsonFile;
+exports.printJson = printJson;
+exports.unknownFlag = unknownFlag;
+/** Endings that happen before or without the service. Appendix B numbers,
+ *  which never change between versions. */
+const LOCAL = {
+    done: 0, incomplete: 1, usage: 2, signed_out: 3, unreachable: 6, unknown: 7,
+    interrupted: 130, output_closed: 141,
+};
+exports.FORMATS = ['text', 'json', 'stream'];
+/** Read `--output` and `--quiet`. Null format means a value nobody accepts. */
+function outputChoice(args) {
+    const at = args.indexOf('--output');
+    const value = at === -1 ? 'text' : String(args[at + 1] ?? '');
+    if (!exports.FORMATS.includes(value)) {
+        return { bad: `--output takes ${exports.FORMATS.join(' or ')}.` };
+    }
+    return {
+        format: value,
+        quiet: args.includes('--quiet'),
+        plain: !process.stdout.isTTY,
+    };
+}
+/** Whether progress belongs on standard error rather than standard output. */
+function progressToErr(o) {
+    return o.format !== 'text' || o.quiet || o.plain;
+}
+/** The exit number for a reason, from the service's table when it sent one. */
+function exitFor(reason, table) {
+    const sent = table?.[reason];
+    if (typeof sent === 'number')
+        return sent;
+    return LOCAL[reason] ?? 1;
+}
+/** The result object for an ending the service never saw, in its published
+ *  shape: every field present, nothing known left as anything but null. */
+function localResult(reason, error) {
+    return {
+        status: reason, error, exit: exitFor(reason), session: null, job: null, result: null,
+        verified: null, changed_files: [], refused: [],
+        cost: { actual_usd: null, baseline_usd: null, baseline_model: null }, steps: null,
+    };
+}
+/**
+ * Read a JSON file named on the line (`--schema`, `--config`): a permitted
+ * local read. The service decides what the contents mean.
+ */
+function readJsonFile(path, flagName) {
+    const fs = require('fs');
+    let text;
+    try {
+        text = fs.readFileSync(path, 'utf8');
+    }
+    catch {
+        return { bad: `${flagName} ${path}: there is no such file.` };
+    }
+    try {
+        const value = JSON.parse(text);
+        if (!value || typeof value !== 'object' || Array.isArray(value)) {
+            return { bad: `${flagName} ${path}: the file must hold one JSON object.` };
+        }
+        return { value: value };
+    }
+    catch {
+        return { bad: `${flagName} ${path}: the file is not valid JSON.` };
+    }
+}
+/** Print the result object as one line of JSON on standard output. */
+function printJson(result) {
+    process.stdout.write(JSON.stringify(result) + '\n');
+}
+/**
+ * Refuse a flag this command does not know (Appendix B, exit 2).
+ *
+ * `known` lists flags that take a value; `switches` lists flags that do not.
+ * A word that is a flag's value is skipped, so a request that happens to
+ * follow `--model` is never read as a flag.
+ */
+function unknownFlag(args, known, switches) {
+    for (let i = 0; i < args.length; i += 1) {
+        const a = String(args[i] ?? '');
+        if (known.includes(a)) {
+            i += 1;
+            continue;
+        }
+        if (switches.includes(a))
+            continue;
+        if (/^--?[A-Za-z]/.test(a) && !a.includes(' '))
+            return a;
+    }
+    return null;
+}

package/out/lib/picker.d.ts

@@ -0,0 +1 @@
+export declare function pick(entries: Array<string | string[]>, hint: string, start?: number, numbered?: boolean): Promise<number | null>;

package/out/lib/picker.js

@@ -0,0 +1,158 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pick = pick;
+/**
+ * Choosing one thing from a list with the arrow keys.
+ *
+ * Each entry is one or more lines: the first is its name, the rest are quieter
+ * detail. Entries are separated by a blank line so each reads as its own item.
+ * Up and Down move, Enter picks, Esc (or Ctrl+C) leaves without picking.
+ *
+ * Only as many entries as fit the window are drawn, and the view follows the
+ * marker, so a long list scrolls instead of running off the screen (which would
+ * leave the redraw writing over lines it can no longer reach). Every line is
+ * cut to the window's width for the same reason: a wrapped line throws the
+ * redraw off by one. Off a terminal there is nothing to move through, so it
+ * returns null and the caller falls back to its typed form.
+ *
+ * With `numbered`, every entry carries its number, and typing a number moves
+ * the marker straight to it. A list of two hundred sessions is not something
+ * anybody should have to arrow through to reach the one they can already see.
+ */
+const node_readline_1 = __importDefault(require("node:readline"));
+const ui = __importStar(require("./ui"));
+const CSI = `${String.fromCharCode(27)}[`;
+function pick(entries, hint, start = 0, numbered = false) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY || entries.length === 0)
+        return Promise.resolve(null);
+    const items = entries.map((e) => (Array.isArray(e) ? e : [e]));
+    const width = Math.max(20, (process.stdout.columns || 100) - 6);
+    const cut = (s) => (s.length > width ? `${s.slice(0, width - 3)}...` : s);
+    const tall = Math.max(...items.map((i) => i.length)) + 1;
+    // Room for the entries, the hint and a line either side.
+    const fits = Math.max(1, Math.floor(((process.stdout.rows || 24) - 4) / tall));
+    let at = Math.min(Math.max(0, start), items.length - 1);
+    let top = 0;
+    let drawn = 0;
+    // The number typed so far, when the entries are numbered.
+    let typed = '';
+    const digits = String(items.length).length;
+    const label = (i, line) => (numbered ? `${String(i + 1).padStart(digits)}. ${line}` : line);
+    const draw = () => {
+        if (at < top)
+            top = at;
+        if (at >= top + fits)
+            top = at - fits + 1;
+        if (drawn)
+            process.stdout.write(`${CSI}${drawn}A\r`);
+        const lines = [];
+        if (top > 0)
+            lines.push(ui.c.dim(`    ${top} more above`));
+        items.slice(top, top + fits).forEach((item, k) => {
+            const i = top + k;
+            const chosen = i === at;
+            item.forEach((line, n) => {
+                if (n === 0) {
+                    const name = cut(label(i, line));
+                    lines.push(chosen ? `  ${ui.c.bold(ui.c.blue(`▸ ${name}`))}` : `    ${ui.c.bold(name)}`);
+                }
+                else
+                    lines.push(`    ${ui.c.dim(cut(numbered ? `${' '.repeat(digits + 2)}${line}` : line))}`);
+            });
+            lines.push('');
+        });
+        const below = items.length - (top + fits);
+        if (below > 0)
+            lines.push(ui.c.dim(`    ${below} more below`));
+        lines.push(`  ${ui.c.dim(hint)}${typed ? `   ${ui.c.bold(`number ${typed}`)}` : ''}`);
+        // The same height every time, so the next redraw lands exactly on this one.
+        while (lines.length < drawn)
+            lines.push('');
+        process.stdout.write(`${lines.map((l) => `${CSI}2K${l}`).join('\n')}\n`);
+        drawn = lines.length;
+    };
+    return new Promise((resolve) => {
+        node_readline_1.default.emitKeypressEvents(process.stdin);
+        const wasRaw = process.stdin.isRaw;
+        process.stdin.setRawMode(true);
+        process.stdin.resume();
+        const done = (choice) => {
+            process.stdin.off('keypress', onKey);
+            process.stdin.setRawMode(wasRaw);
+            process.stdin.pause();
+            resolve(choice);
+        };
+        const onKey = (s, key) => {
+            if (!key && !(numbered && /^[0-9]$/.test(s ?? '')))
+                return;
+            if (numbered && /^[0-9]$/.test(s ?? '')) {
+                // A number past the end starts again from this digit, so a mistyped
+                // number is corrected by typing the right one, not by clearing first.
+                const next = Number(typed + s) <= items.length ? typed + s : s;
+                const n = Number(next);
+                typed = n >= 1 && n <= items.length ? next : '';
+                if (typed)
+                    at = n - 1;
+                draw();
+            }
+            else if (numbered && key.name === 'backspace' && typed) {
+                typed = typed.slice(0, -1);
+                if (typed)
+                    at = Number(typed) - 1;
+                draw();
+            }
+            else if (key.name === 'up' || key.name === 'k') {
+                typed = '';
+                at = Math.max(0, at - 1);
+                draw();
+            }
+            else if (key.name === 'down' || key.name === 'j') {
+                typed = '';
+                at = Math.min(items.length - 1, at + 1);
+                draw();
+            }
+            else if (key.name === 'return')
+                done(at);
+            else if (key.name === 'escape' || key.name === 'q' || (key.ctrl && key.name === 'c'))
+                done(null);
+        };
+        process.stdin.on('keypress', onKey);
+        draw();
+    });
+}

package/out/lib/project-ops.d.ts

@@ -0,0 +1,19 @@
+import { type GatewayReply } from "./gateway";
+import { type ProjectFacts } from "./project";
+export type Intent = "instructions" | "config" | "memory" | "worktrees" | "hooks";
+export declare function useSessionFolder(folder: string | null): void;
+/** The project for this command: the session's folder, the saved default, or
+ *  the folder you are in. */
+export declare function currentProject(): Promise<ProjectFacts>;
+/** One file inside the project, as text, or undefined. Never a secrets file,
+ *  never outside the project, never anything large. */
+export declare function readInside(root: string, rel: string): string | undefined;
+/** The files among `names` that exist, keyed by the name asked for. */
+export declare function readSome(root: string, names: string[]): Record<string, string>;
+/** Ask the service, and print what it wrote. Returns null when refused or
+ *  unreachable, after saying so; the caller sets the exit status. */
+export declare function call(intent: Intent, op: string, payload: Record<string, unknown>, facts?: ProjectFacts, quiet?: boolean): Promise<GatewayReply | null>;
+/** Write one settings key into a project settings file, keeping everything else. */
+export declare function writeSetting(root: string, file: string, key: string, value: unknown): void;
+/** Open files in the person's editor and wait for it to close. */
+export declare function openEditor(files: string[]): Promise<boolean>;

package/out/lib/project-ops.js

@@ -0,0 +1,146 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSessionFolder = useSessionFolder;
+exports.currentProject = currentProject;
+exports.readInside = readInside;
+exports.readSome = readSome;
+exports.call = call;
+exports.writeSetting = writeSetting;
+exports.openEditor = openEditor;
+/**
+ * The project operations, from a terminal (manual 2.5 to 2.11).
+ *
+ * A local helper: it reads the files the service asks for, writes the files the
+ * service says to write, and prints the lines the service wrote. Which files
+ * count, what they mean and every word shown are the service's.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const gateway_1 = require("./gateway");
+const project_1 = require("./project");
+const paths_1 = require("../executor/paths");
+const ui = __importStar(require("./ui"));
+const out = (s = "") => process.stdout.write(s + "\n");
+/** The largest file sent. An instruction or settings file is a page, not a book. */
+const MAX_FILE_BYTES = 64 * 1024;
+/** The folder a session moved to with `project <path>`, when it has. */
+let sessionFolder = null;
+function useSessionFolder(folder) { sessionFolder = folder; }
+/** The project for this command: the session's folder, the saved default, or
+ *  the folder you are in. */
+async function currentProject() {
+    const { currentWorkspace } = await Promise.resolve().then(() => __importStar(require("../commands/settings")));
+    const found = (0, project_1.checkFolder)(sessionFolder ?? currentWorkspace().path);
+    return (0, project_1.resolveProject)(found.ok ? found.path : process.cwd());
+}
+/** One file inside the project, as text, or undefined. Never a secrets file,
+ *  never outside the project, never anything large. */
+function readInside(root, rel) {
+    if ((0, paths_1.isSecret)(rel))
+        return undefined;
+    const full = path.resolve(root, rel);
+    const realRoot = fs.realpathSync(root);
+    try {
+        const real = fs.realpathSync(full);
+        if (real !== realRoot && !real.startsWith(realRoot + path.sep))
+            return undefined;
+        const st = fs.statSync(real);
+        if (!st.isFile() || st.size > MAX_FILE_BYTES)
+            return undefined;
+        return fs.readFileSync(real, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The files among `names` that exist, keyed by the name asked for. */
+function readSome(root, names) {
+    const files = {};
+    for (const n of names) {
+        const body = readInside(root, n);
+        if (body !== undefined)
+            files[n] = body;
+    }
+    return files;
+}
+/** Ask the service, and print what it wrote. Returns null when refused or
+ *  unreachable, after saying so; the caller sets the exit status. */
+async function call(intent, op, payload, facts, quiet = false) {
+    const reply = await (0, gateway_1.ask)({
+        intent, prompt: "", op, payload: { ...(facts ? (0, project_1.asWire)(facts) : {}), ...payload },
+    });
+    if (!reply.ok || reply.served === false) {
+        out(ui.fail(reply.served === false
+            ? "Your workspace is running an older build that does not answer this yet."
+            : `Your workspace could not be reached: ${reply.message || "no answer"}`));
+        return null;
+    }
+    if (reply.granted === false) {
+        out(ui.fail(reply.message || "Refused."));
+        return null;
+    }
+    if (!quiet)
+        for (const line of reply.lines ?? [])
+            out(line);
+    return reply;
+}
+/** Write one settings key into a project settings file, keeping everything else. */
+function writeSetting(root, file, key, value) {
+    const full = path.join(root, file);
+    let data = {};
+    try {
+        const parsed = JSON.parse(fs.readFileSync(full, "utf8"));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+            data = parsed;
+    }
+    catch { /* a new file, or one that did not parse: start clean */ }
+    if (value === null || value === undefined)
+        delete data[key];
+    else
+        data[key] = value;
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, JSON.stringify(data, null, 2) + "\n");
+}
+/** Open files in the person's editor and wait for it to close. */
+async function openEditor(files) {
+    const { machineSettings } = await Promise.resolve().then(() => __importStar(require("./machine")));
+    const editor = process.env.VISUAL || process.env.EDITOR || machineSettings().editor
+        || (process.platform === "win32" ? "notepad" : "vi");
+    const { spawnSync } = await Promise.resolve().then(() => __importStar(require("node:child_process")));
+    const [cmd, ...args] = editor.split(" ").filter(Boolean);
+    const r = spawnSync(cmd, [...args, ...files], { stdio: "inherit", shell: process.platform === "win32" });
+    return r.status === 0;
+}

package/out/lib/project.d.ts

@@ -0,0 +1,28 @@
+export interface ProjectFacts {
+    /** The repository root, or the folder itself outside a repository. Real path. */
+    root: string;
+    /** Where the person was standing, relative to `root`. Empty at the root. */
+    start: string;
+    /** Null outside a repository, or when HEAD is not on a branch. */
+    branch: string | null;
+    /** Folders the person named, real paths, never the root itself. */
+    added: string[];
+    home: string;
+    /** `owner/name` of the GitHub repository `origin` points at, or null. The
+     *  service needs it for pull requests, issues and CI (manual 5.18 to 5.21). */
+    repository?: string | null;
+}
+/** `owner/name` from a GitHub remote address, in any of its spellings. */
+export declare function githubRepository(remote: string | null): string | null;
+/** A folder the person named, or the reason it cannot be used. */
+export declare function checkFolder(raw: string): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    why: string;
+};
+/** The project for a job started in `startDir`, with any added folders. */
+export declare function resolveProject(startDir: string, added?: string[]): ProjectFacts;
+/** The facts as the service reads them, on the job and on the session line. */
+export declare function asWire(p: ProjectFacts, mode?: string): Record<string, unknown>;

package/out/lib/project.js

@@ -0,0 +1,114 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.githubRepository = githubRepository;
+exports.checkFolder = checkFolder;
+exports.resolveProject = resolveProject;
+exports.asWire = asWire;
+/**
+ * Where a job works, as this machine sees it (manual 2.1 to 2.3).
+ *
+ * A local helper and nothing more: it observes the folder, the Git repository
+ * around it and the branch, because only this machine can. The service decides
+ * what those facts mean, stores them on the job and writes the line a person
+ * reads. Nothing here decides whether a path may be touched; the executor's
+ * check in `executor/paths.ts` does that immediately before each action.
+ */
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+/** `owner/name` from a GitHub remote address, in any of its spellings. */
+function githubRepository(remote) {
+    // `github.com`, or an SSH alias such as `github-work` set up for a second account.
+    const m = /(?:^|[@/])github[\w.-]*[:/]([\w.-]+)\/([\w.-]+?)(?:\.git)?\/?$/.exec((remote ?? "").trim());
+    return m ? `${m[1]}/${m[2]}` : null;
+}
+/** A folder the person named, or the reason it cannot be used. */
+function checkFolder(raw) {
+    const expanded = raw.replace(/^~(?=$|[\\/])/, os.homedir());
+    const resolved = path.resolve(expanded);
+    if (!fs.existsSync(resolved))
+        return { ok: false, why: `There is no folder at ${resolved}.` };
+    if (!fs.statSync(resolved).isDirectory())
+        return { ok: false, why: `${resolved} is a file, not a folder.` };
+    return { ok: true, path: fs.realpathSync(resolved) };
+}
+/** Git's output, or null when git failed or this is not a repository. */
+function git(args, cwd) {
+    try {
+        // An argument list, never a shell string, so it behaves the same on Windows.
+        return (0, node_child_process_1.execFileSync)("git", args, {
+            cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/** The project for a job started in `startDir`, with any added folders. */
+function resolveProject(startDir, added = []) {
+    const start = fs.realpathSync(startDir);
+    // The way up to the repository root and the way back down, relative, rather
+    // than the root's absolute name. Git spells an absolute path its own way (on
+    // Windows, long names where the temp folder has short ones), and comparing two
+    // spellings of one folder reads as two folders.
+    const where = git(["rev-parse", "--show-cdup", "--show-prefix"], start);
+    const [up = "", down = ""] = where === null ? [] : where.split(/\r?\n/);
+    const root = where === null ? start : fs.realpathSync(path.resolve(start, up || "."));
+    const branch = where === null
+        ? null : (git(["symbolic-ref", "--short", "-q", "HEAD"], root) ?? "").trim() || null;
+    const extra = [...new Set(added.map((a) => fs.realpathSync(a)))].filter((a) => a !== root);
+    return {
+        root,
+        start: down.replace(/\/+$/, ""),
+        branch,
+        added: extra,
+        home: os.homedir(),
+        repository: where === null ? null : githubRepository(git(["remote", "get-url", "origin"], root)),
+    };
+}
+/** The facts as the service reads them, on the job and on the session line. */
+function asWire(p, mode) {
+    return {
+        project_root: p.root,
+        start_folder: p.start,
+        branch: p.branch,
+        added_folders: p.added,
+        home: p.home,
+        ...(p.repository ? { repository: p.repository } : {}),
+        ...(mode ? { permission_mode: mode } : {}),
+    };
+}

package/out/lib/prompt.d.ts

@@ -2,6 +2,9 @@
 export declare function closePrompt(): void;
 /** Ask a question and wait for the answer. */
 export declare function ask(prompt: string): Promise<string>;
+/** Ask, telling a cancel (Ctrl+C, input closed) apart from an empty answer:
+ *  null is "never mind", "" is Enter. */
+export declare function askOrCancel(prompt: string): Promise<string | null>;
 /**
  * Ask for a secret, and do not put it on the screen.
  *