@illuminis/comprism 0.1.3 → 0.1.5

package/out/lib/prompt.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.closePrompt = closePrompt;
 exports.ask = ask;
+exports.askOrCancel = askOrCancel;
 exports.askHidden = askHidden;
 exports.freeText = freeText;
 exports.subject = subject;
@@ -24,6 +25,11 @@ function open() {
             output: process.stdout,
             terminal: process.stdin.isTTY === true,
         });
+        // Ctrl+C closes it. The next question then opens a new one instead of
+        // asking a closed reader, which threw and ended the whole program.
+        const mine = reader;
+        mine.once('close', () => { if (reader === mine)
+            reader = null; });
     }
     return reader;
 }
@@ -35,7 +41,33 @@ function closePrompt() {
 /** Ask a question and wait for the answer. */
 function ask(prompt) {
     return new Promise((resolve) => {
-        open().question(prompt, (answer) => resolve(answer.trim()));
+        const r = open();
+        // Standard input closed before a line arrived: nothing was said. Without
+        // this the process simply ran out of work and exited 0, so a script that
+        // piped in nothing was told it had succeeded (manual Appendix B).
+        // Input that had already ended before this reader opened never says so
+        // again, so the last chance is the moment nothing else is left to wait on.
+        const closed = () => resolve('');
+        r.once('close', closed);
+        process.once('beforeExit', closed);
+        r.question(prompt, (answer) => {
+            r.off('close', closed);
+            process.off('beforeExit', closed);
+            resolve(answer.trim());
+        });
+    });
+}
+/** Ask, telling a cancel (Ctrl+C, input closed) apart from an empty answer:
+ *  null is "never mind", "" is Enter. */
+function askOrCancel(prompt) {
+    return new Promise((resolve) => {
+        const r = open();
+        const closed = () => resolve(null);
+        r.once('close', closed);
+        r.question(prompt, (answer) => {
+            r.off('close', closed);
+            resolve(answer.trim());
+        });
     });
 }
 /**
@@ -73,12 +105,14 @@ function askHidden(prompt) {
         process.stdout.write(`\r${prompt}${"\u2022".repeat(inner.line.length)}`);
     };
     return new Promise((resolve) => {
+        // Ctrl+C at the password is "never mind", answered as nothing, never a crash.
+        reader.once('close', () => { inner._writeToOutput = asItWas; resolve(''); });
         reader.question(prompt, (answer) => {
             // Put readline back the way it was, whatever happened, or every later
             // question on this reader would come out as dots.
             inner._writeToOutput = asItWas;
             process.stdout.write("\n");
-            resolve(answer.trim());
+            resolve(answer);
         });
     });
 }

package/out/lib/queue.d.ts

@@ -0,0 +1,13 @@
+import { type GatewayReply } from "./gateway";
+export declare function queue(op: string, payload?: Record<string, unknown>): Promise<GatewayReply>;
+/** The limits and mode typed on the line, for the service to hold (10.17). */
+export declare function limitsFrom(args: string[]): Record<string, unknown>;
+export declare const workerLog: () => string;
+/** Whether this machine's runner is going, and its process number. */
+export declare function workerRunning(): number | null;
+export declare function notePid(): void;
+/** Start the runner in the background when it is not running. */
+export declare function ensureWorker(): {
+    pid: number;
+    started: boolean;
+};

package/out/lib/queue.js

@@ -0,0 +1,116 @@
+"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.workerLog = void 0;
+exports.queue = queue;
+exports.limitsFrom = limitsFrom;
+exports.workerRunning = workerRunning;
+exports.notePid = notePid;
+exports.ensureWorker = ensureWorker;
+/**
+ * Jobs nobody is sitting at, from this side (manual 10.17 to 10.19).
+ *
+ * The service holds the schedules, the triggers and the queue, and decides what
+ * is due and what may run where. This file asks it, and keeps one runner going
+ * on this machine to take what the service offers.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const gateway_1 = require("./gateway");
+const config_1 = require("./config");
+const self_1 = require("./self");
+async function queue(op, payload = {}) {
+    return (0, gateway_1.ask)({
+        intent: "queue", prompt: "", op,
+        payload: { tz_minutes: -new Date().getTimezoneOffset(), ...payload },
+    });
+}
+/** The limits and mode typed on the line, for the service to hold (10.17). */
+function limitsFrom(args) {
+    const value = (name) => {
+        const at = args.indexOf(name);
+        return at === -1 ? undefined : args[at + 1];
+    };
+    const out = {};
+    if (value("--mode"))
+        out.mode = value("--mode");
+    if (value("--max-spend"))
+        out.max_spend = Number(value("--max-spend"));
+    if (value("--max-steps"))
+        out.max_steps = Number(value("--max-steps"));
+    if (value("--max-minutes"))
+        out.max_minutes = Number(value("--max-minutes"));
+    return out;
+}
+const pidFile = () => path.join((0, config_1.homeDir)(), "worker.pid");
+const workerLog = () => path.join((0, config_1.homeDir)(), "worker.log");
+exports.workerLog = workerLog;
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether this machine's runner is going, and its process number. */
+function workerRunning() {
+    try {
+        const pid = Number(fs.readFileSync(pidFile(), "utf8").trim());
+        return pid && alive(pid) ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+function notePid() {
+    fs.mkdirSync((0, config_1.homeDir)(), { recursive: true });
+    fs.writeFileSync(pidFile(), String(process.pid));
+}
+/** Start the runner in the background when it is not running. */
+function ensureWorker() {
+    const running = workerRunning();
+    if (running)
+        return { pid: running, started: false };
+    fs.mkdirSync((0, config_1.homeDir)(), { recursive: true });
+    const log = fs.openSync((0, exports.workerLog)(), "a");
+    const child = (0, child_process_1.spawn)(...(0, self_1.selfLaunch)(["worker"]), {
+        detached: true, stdio: ["ignore", log, log], env: { ...process.env, NO_COLOR: "1" },
+    });
+    child.unref();
+    return { pid: child.pid ?? 0, started: true };
+}

package/out/lib/readiness.d.ts

@@ -28,3 +28,22 @@ export interface Readiness {
 }
 /** What this machine can and cannot do, and how to close the gap. */
 export declare function check(): Readiness;
+/** One checked item: its line, whether it is required, and the fix. */
+export interface Finding {
+    ok: boolean;
+    required: boolean;
+    line: string;
+    fix?: string;
+}
+/** The system this is, in the words its owner would use. */
+export declare function systemName(): string;
+/**
+ * Everything `comprism check` reports (manual 1.6).
+ *
+ * Required: Node 22 or newer (built in for the install script and Python
+ * installs), a sign in, and a service that answers. Anything
+ * else is optional and never makes the check fail. Whether the service still
+ * accepts this machine is asked of the service itself, on the same session
+ * operation `status` uses, so the two can never disagree.
+ */
+export declare function diagnose(): Promise<Finding[]>;

package/out/lib/readiness.js

@@ -1,4 +1,37 @@
 "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 };
 };
@@ -7,6 +40,8 @@ exports.REQUIREMENTS = void 0;
 exports.present = present;
 exports.howToInstall = howToInstall;
 exports.check = check;
+exports.systemName = systemName;
+exports.diagnose = diagnose;
 /**
  * What this machine needs before the work can be done on it, and what to type
  * when something is missing.
@@ -38,6 +73,10 @@ exports.check = check;
  */
 const node_child_process_1 = require("node:child_process");
 const node_os_1 = __importDefault(require("node:os"));
+const install_1 = require("../commands/install");
+const connection_1 = require("./connection");
+const gateway_1 = require("./gateway");
+const node_fs_1 = __importDefault(require("node:fs"));
 exports.REQUIREMENTS = [
     {
         purpose: 'working with a repository',
@@ -57,7 +96,11 @@ exports.REQUIREMENTS = [
 /** Is this program on the machine, by name, without running anything of theirs. */
 function present(program) {
     try {
-        (0, node_child_process_1.execFileSync)('/usr/bin/env', ['which', program], { stdio: 'ignore' });
+        // Windows has no /usr/bin/env, so every program read as missing there.
+        if (node_os_1.default.platform() === 'win32')
+            (0, node_child_process_1.execFileSync)('where', [program], { stdio: 'ignore' });
+        else
+            (0, node_child_process_1.execFileSync)('/usr/bin/env', ['which', program], { stdio: 'ignore' });
         return true;
     }
     catch {
@@ -105,3 +148,129 @@ function check() {
     }
     return { ready: missing.length === 0, lines, fix: howToInstall(missing) };
 }
+/** The system this is, in the words its owner would use. */
+function systemName() {
+    try {
+        if (node_os_1.default.platform() === 'darwin') {
+            const v = (0, node_child_process_1.execFileSync)('sw_vers', ['-productVersion'], { stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
+            return `macOS ${v} ${node_os_1.default.arch()}`;
+        }
+        if (node_os_1.default.platform() === 'linux') {
+            const release = node_fs_1.default.readFileSync('/etc/os-release', 'utf8').match(/^PRETTY_NAME="?([^"\n]+)"?/m);
+            return `${release ? release[1] : 'Linux'} ${node_os_1.default.arch()}`;
+        }
+        if (node_os_1.default.platform() === 'win32')
+            return `${node_os_1.default.version()} ${node_os_1.default.arch()}`;
+    }
+    catch { /* fall through to the plain name */ }
+    return `${node_os_1.default.type()} ${node_os_1.default.release()} ${node_os_1.default.arch()}`;
+}
+function version(program, args) {
+    try {
+        const text = (0, node_child_process_1.execFileSync)(program, args, { stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+        return text.match(/\d+\.\d+(\.\d+)?/)?.[0] ?? '';
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Everything `comprism check` reports (manual 1.6).
+ *
+ * Required: Node 22 or newer (built in for the install script and Python
+ * installs), a sign in, and a service that answers. Anything
+ * else is optional and never makes the check fail. Whether the service still
+ * accepts this machine is asked of the service itself, on the same session
+ * operation `status` uses, so the two can never disagree.
+ */
+async function diagnose() {
+    const found = [];
+    found.push({ ok: true, required: false, line: systemName() });
+    // Which proxy and certificate file are in use (manual 1.11).
+    const proxy = process.env.HTTPS_PROXY || process.env.https_proxy || process.env.HTTP_PROXY || process.env.http_proxy;
+    if (proxy) {
+        const bypass = process.env.NO_PROXY || process.env.no_proxy;
+        found.push({ ok: true, required: false, line: `proxy ${proxy.replace(/\/\/[^@/]*@/, '//***@')}`
+                + (bypass ? `, not used for ${bypass}` : '') });
+    }
+    const caFile = process.env.NODE_EXTRA_CA_CERTS;
+    if (caFile) {
+        const fs = await Promise.resolve().then(() => __importStar(require('fs')));
+        found.push(fs.existsSync(caFile)
+            ? { ok: true, required: false, line: `extra certificate authorities from ${caFile}` }
+            : { ok: false, required: true, line: `NODE_EXTRA_CA_CERTS names ${caFile}, which does not exist`,
+                fix: 'point NODE_EXTRA_CA_CERTS at your company certificate authority file' });
+    }
+    const node = process.versions.node;
+    const major = Number(node.split('.')[0]);
+    // The install script and Python installs carry their own Node (manual 1.1),
+    // so the line says so rather than asking for a Node nobody installed.
+    const { installMethod, isStandalone } = await Promise.resolve().then(() => __importStar(require('./self')));
+    if (isStandalone()) {
+        const how = installMethod() === 'script' ? 'the install script' : 'Python (pip)';
+        found.push({ ok: true, required: true, line: `installed with ${how}; Node ${node} is built in, nothing else needed` });
+    }
+    else
+        found.push(major >= 22
+            ? { ok: true, required: true, line: `Node ${node} (22 or newer needed)` }
+            : { ok: false, required: true, line: `Node ${node} is too old: 22 or newer needed`,
+                fix: 'install Node 22 or newer from https://nodejs.org' });
+    const connection = (0, connection_1.readConnection)();
+    if (!connection?.url || !connection.workspaceKey) {
+        found.push({ ok: false, required: true, line: 'not signed in', fix: 'comprism login' });
+    }
+    else {
+        const started = Date.now();
+        const reply = await (0, gateway_1.ask)({ intent: 'session', prompt: '' });
+        const ms = Date.now() - started;
+        if (!reply.ok && !reply.httpStatus && /certificate problem/.test(reply.message || '')) {
+            found.push({ ok: false, required: true, line: `service at ${connection.url}: ${reply.message}`,
+                fix: 'set NODE_EXTRA_CA_CERTS to your company certificate authority file' });
+        }
+        else if (!reply.ok && !reply.httpStatus) {
+            found.push({ ok: false, required: true, line: `service at ${connection.url} did not answer`,
+                fix: 'check your network, then comprism status' });
+        }
+        else if (reply.httpStatus === 401 || (reply.ok && reply.session && !reply.session.signed_in)) {
+            found.push({ ok: false, required: true, line: "signed out: this machine's key was revoked or has expired",
+                fix: 'comprism login' });
+            found.push({ ok: true, required: true, line: `service reachable in ${ms} ms` });
+        }
+        else {
+            found.push({ ok: true, required: true,
+                line: `signed in to ${reply.session?.company || connection.url}` });
+            found.push({ ok: true, required: true, line: `service reachable in ${ms} ms` });
+        }
+    }
+    const { powershellProfiles } = await Promise.resolve().then(() => __importStar(require('../commands/install')));
+    const profile = [...powershellProfiles(), ...(0, install_1.shellProfiles)()].find(install_1.profileHasSetup);
+    const home = node_os_1.default.homedir();
+    if (profile) {
+        found.push({ ok: true, required: false,
+            line: `shell profile line present in ${profile.startsWith(home) ? `~${profile.slice(home.length)}` : profile}` });
+    }
+    else if (node_os_1.default.platform() === 'win32') {
+        found.push({ ok: false, required: false,
+            line: 'no PowerShell profile line, so other AI tools here are not measured', fix: 'comprism install' });
+    }
+    else {
+        found.push({ ok: false, required: false, line: 'no shell profile line, so other AI tools here are not measured',
+            fix: 'comprism install' });
+    }
+    const git = version('git', ['--version']);
+    found.push(git !== null
+        ? { ok: true, required: false, line: `git ${git}` }
+        : { ok: false, required: false, line: 'git not found: reading, branching and committing a project will not work',
+            fix: howToInstall(['git']) });
+    const rg = version('rg', ['--version']);
+    found.push(rg !== null
+        ? { ok: true, required: false, line: `ripgrep ${rg}` }
+        : { ok: false, required: false, line: 'ripgrep not found: searches will be slower',
+            fix: howToInstall(['ripgrep']) });
+    const pdf = exports.REQUIREMENTS[1];
+    found.push(pdf.anyOf.some(present)
+        ? { ok: true, required: false, line: 'a PDF reader' }
+        : { ok: false, required: false, line: `no PDF reader: ${pdf.without} will not work`,
+            fix: howToInstall(['pdftotext']) });
+    return found;
+}

package/out/lib/self.d.ts

@@ -0,0 +1,23 @@
+/** True when running as the ready to run program rather than under Node. */
+export declare function isStandalone(): boolean;
+/** Where the install script keeps the program: `~/.comprism/bin`. */
+export declare function standaloneBinDir(): string;
+export type InstallMethod = "script" | "npm" | "python";
+/**
+ * Which of the three install options put this copy here.
+ *
+ * The program is only ever distributed two ways, so where it sits decides it:
+ * in `~/.comprism/bin` it came from the install script, anywhere else pip put
+ * it. Under Node it came from npm.
+ */
+export declare function installMethod(): InstallMethod;
+/** The command and arguments that start another copy of this tool. */
+export declare function selfLaunch(args: string[], nodeFlags?: string[]): [string, string[]];
+/**
+ * A file shipped beside the code, as a path on disk.
+ *
+ * Under npm it sits in the package. Inside the program it is carried as an
+ * asset and written once to `~/.comprism/assets`, because the programs it is
+ * handed to (Python, for the reader script) need a real file.
+ */
+export declare function shippedFile(name: string, packagePath: string): string;

package/out/lib/self.js

@@ -0,0 +1,124 @@
+"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.isStandalone = isStandalone;
+exports.standaloneBinDir = standaloneBinDir;
+exports.installMethod = installMethod;
+exports.selfLaunch = selfLaunch;
+exports.shippedFile = shippedFile;
+/**
+ * How this copy of the tool was installed, and how it starts another copy of
+ * itself (manual 1.1).
+ *
+ * The same code ships two ways. Through npm it is a script that Node runs, so
+ * `process.argv[1]` is the script and a second copy is `node <script> <args>`.
+ * Through the install script and the Python package it is one ready to run
+ * program with Node built in, where `process.argv[1]` is the program again and
+ * a second copy is just `<program> <args>`. Passing the program's own path as
+ * the first argument there would read as a command called "/Users/me/...", so
+ * every place that starts a copy of the tool asks here instead of guessing.
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("./config");
+let sea;
+/** True when running as the ready to run program rather than under Node. */
+function isStandalone() {
+    if (sea === undefined) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            sea = Boolean(require("node:sea").isSea());
+        }
+        catch {
+            sea = false;
+        }
+    }
+    return sea;
+}
+/** Where the install script keeps the program: `~/.comprism/bin`. */
+function standaloneBinDir() {
+    return path.join((0, config_1.homeDir)(), "bin");
+}
+/**
+ * Which of the three install options put this copy here.
+ *
+ * The program is only ever distributed two ways, so where it sits decides it:
+ * in `~/.comprism/bin` it came from the install script, anywhere else pip put
+ * it. Under Node it came from npm.
+ */
+function installMethod() {
+    if (!isStandalone())
+        return "npm";
+    try {
+        const here = fs.realpathSync(process.execPath);
+        const bin = fs.realpathSync(standaloneBinDir());
+        if (path.dirname(here) === bin)
+            return "script";
+    }
+    catch {
+        // No `~/.comprism/bin`: not an install script install.
+    }
+    return "python";
+}
+/** The command and arguments that start another copy of this tool. */
+function selfLaunch(args, nodeFlags = []) {
+    if (isStandalone())
+        return [process.execPath, args];
+    return [process.execPath, [...nodeFlags, process.argv[1] ?? "", ...args]];
+}
+/**
+ * A file shipped beside the code, as a path on disk.
+ *
+ * Under npm it sits in the package. Inside the program it is carried as an
+ * asset and written once to `~/.comprism/assets`, because the programs it is
+ * handed to (Python, for the reader script) need a real file.
+ */
+function shippedFile(name, packagePath) {
+    if (!isStandalone())
+        return packagePath;
+    const target = path.join((0, config_1.homeDir)(), "assets", name);
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const text = require("node:sea").getAsset(name, "utf8");
+        if (!fs.existsSync(target) || fs.readFileSync(target, "utf8") !== text) {
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.writeFileSync(target, text);
+        }
+    }
+    catch {
+        // An asset that cannot be written leaves the caller's own fallback in charge.
+    }
+    return target;
+}

package/out/lib/sessions.d.ts

@@ -0,0 +1,19 @@
+import type { GatewayReply } from './gateway';
+/** Ask the service one sessions question, with where this machine is. */
+export declare function sessions(op: 'list' | 'resume' | 'latest' | 'opened' | 'rename' | 'branch' | 'export' | 'by_pr' | 'remote_on' | 'remote_poll' | 'remote_off' | 'lease' | 'read' | 'steering' | 'steer', extra?: Record<string, unknown>, folder?: string): Promise<GatewayReply>;
+/** Why a sessions question got no answer, in the service's words when it has them. */
+export declare function failure(reply: GatewayReply): string;
+/** The exit number for a sessions question that got no answer (Appendix B). */
+export declare function exitFor(reply: GatewayReply): number;
+/**
+ * Choose one line with the arrow keys; Enter picks, Esc or Ctrl+C leaves.
+ * Resolves with the index chosen, or null. Without a terminal it asks for a
+ * number instead, so a script is never left waiting on keys it cannot send.
+ */
+export declare function pick(lines: string[]): Promise<number | null>;
+/**
+ * `comprism sessions` and its words (manual 8.5 to 8.7, 8.10). Every answer,
+ * every line and every refusal is the service's; the export is written to
+ * standard output exactly as it came, so `> session.md` holds the file.
+ */
+export declare function cmdSessions(args: string[]): Promise<number>;