@illuminis/comprism 0.1.3 → 0.1.5

package/out/lib/attach.js

@@ -34,10 +34,16 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.unescapePath = unescapePath;
+exports.localProblem = localProblem;
 exports.mentions = mentions;
+exports.startsWithPath = startsWithPath;
 exports.withoutPaths = withoutPaths;
+exports.withoutMentions = withoutMentions;
 exports.upload = upload;
 exports.describe = describe;
+exports.listing = listing;
+exports.projectFiles = projectFiles;
+exports.completeAt = completeAt;
 /**
  * Files handed to a question, from a terminal.
  *
@@ -76,35 +82,90 @@ exports.describe = describe;
 const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
+const gateway_1 = require("./gateway");
 /**
  * Take the shell's escaping back off a path.
  *
  * A dragged file arrives as `/Users/me/My\ Report.pdf`, and a pasted one is
  * often in quotes. Both are the shell's way of saying "this is one thing", and
  * neither is part of the name.
+ *
+ * On Windows a backslash is the folder separator and never an escape: its
+ * terminals quote a dragged path instead. Stripping backslashes there turned
+ * `C:\Users\me\notes.txt` into `C:Usersmenotes.txt`, which was the Windows
+ * failure found in prompt 01.
  */
-function unescapePath(token) {
+function unescapePath(token, platform = process.platform) {
     let out = token.trim();
-    if ((out.startsWith('"') && out.endsWith('"'))
-        || (out.startsWith("'") && out.endsWith("'"))) {
+    if ((out.startsWith('"') && out.endsWith('"') && out.length > 1)
+        || (out.startsWith("'") && out.endsWith("'") && out.length > 1)) {
         out = out.slice(1, -1);
     }
-    else {
+    else if (platform !== 'win32') {
         out = out.replace(/\\(.)/g, '$1');
     }
     return out;
 }
-/** `~/notes.md` against this person's home folder. */
-function expand(file, cwd) {
+const WINDOWS_ABSOLUTE = /^(?:[A-Za-z]:[\\/]|\\\\)/;
+/**
+ * Where a named path points.
+ *
+ * `~/` is this person's home folder. `./` and `../` start from the folder they
+ * are in. Anything else relative starts from the project root (manual 3.1).
+ */
+function expand(file, root, here) {
     const home = os.homedir();
-    const full = file === '~' ? home
-        : file.startsWith('~/') ? path.join(home, file.slice(2))
-            : path.resolve(cwd, file);
-    return full;
+    if (file === '~')
+        return home;
+    if (file.startsWith('~/') || file.startsWith('~\\'))
+        return path.join(home, file.slice(2));
+    if (path.isAbsolute(file) || WINDOWS_ABSOLUTE.test(file))
+        return path.resolve(file);
+    if (/^\.\.?[\\/]/.test(file))
+        return path.resolve(here, file);
+    return path.resolve(root, file);
+}
+/**
+ * What stops a file being attached, checked on this machine before anything is
+ * sent (manual 3.10). Only the four facts the service cannot see: whether the
+ * file is there, is a folder, can be read, or is a link to nothing.
+ */
+function localProblem(file, shown) {
+    let link;
+    try {
+        link = fs.lstatSync(file);
+    }
+    catch {
+        return { code: 'not_found', message: `not found: ${shown}` };
+    }
+    let stat;
+    try {
+        stat = fs.statSync(file);
+    }
+    catch {
+        return link.isSymbolicLink()
+            ? { code: 'broken_link', message: `${shown} points to a file that does not exist` }
+            : { code: 'unreadable', message: `cannot read ${shown}: permission denied` };
+    }
+    if (stat.isDirectory()) {
+        return {
+            code: 'folder',
+            message: `${shown} is a folder. Attach the files you need, or ask the agent to look in it.`,
+        };
+    }
+    try {
+        fs.closeSync(fs.openSync(file, 'r'));
+    }
+    catch {
+        return { code: 'unreadable', message: `cannot read ${shown}: permission denied` };
+    }
+    return undefined;
 }
-function isFile(file) {
+/** Something is on the disk at this path, even a link to nothing. */
+function present(file) {
     try {
-        return fs.statSync(file).isFile();
+        fs.lstatSync(file);
+        return true;
     }
     catch {
         return false;
@@ -113,58 +174,95 @@ function isFile(file) {
 /**
  * Every file the typed line points at, in the order they were named.
  *
- * A token that looks like a path but is not on the disk is left alone and stays
- * part of the question. Somebody writing about a path they plan to create is
- * doing something perfectly ordinary, and refusing their line over it would be
- * the tool arguing with them.
+ * Anything after an `@` is a request to attach, so a problem with it is
+ * reported. Any other path (absolute, `~/`, `./`, `../`, quoted) that is not a
+ * readable file is left alone and stays part of the question: somebody writing
+ * about a path they plan to create, or a folder they want looked at, is doing
+ * something perfectly ordinary.
  */
-function mentions(line, cwd) {
+function mentions(line, root, here = root, platform = process.platform) {
     const found = [];
     const seen = new Set();
-    const consider = (raw, candidate) => {
-        const file = expand(unescapePath(candidate), cwd);
-        if (!isFile(file) || seen.has(file))
-            return;
+    const consider = (raw, candidate, asked) => {
+        const shown = unescapePath(candidate, platform);
+        if (!shown)
+            return false;
+        const file = expand(shown, root, here);
+        if (seen.has(file))
+            return true;
+        const problem = localProblem(file, shown);
+        // A path in a sentence is only attached when it is a readable file, or a
+        // link to nothing (which is plainly a file the person meant).
+        if (!asked && problem && problem.code !== 'broken_link')
+            return false;
         seen.add(file);
-        found.push({ raw, file });
+        found.push({ raw, file, shown, ...(problem ? { problem } : {}) });
+        return true;
     };
     // Quoted first, because a quoted path may contain the spaces that would
     // otherwise end a token, and the quotes are the person saying exactly that.
-    for (const m of line.matchAll(/"([^"]+)"|'([^']+)'/g)) {
-        consider(m[0], m[1] ?? m[2] ?? '');
+    // An `@` straight before the quotes belongs to the same mention.
+    for (const m of line.matchAll(/(@?)(?:"([^"]+)"|'([^']+)')/g)) {
+        consider(m[0], `"${m[2] ?? m[3] ?? ''}"`, m[1] === '@');
     }
     // Then `@`, which is treated generously on purpose.
     //
     // A dragged file arrives escaped and a pasted one is usually quoted, but
     // somebody who TYPES `@` and then a folder with a space in its name has said
     // what they mean as plainly as it can be said. So everything after the `@` is
-    // tried, then the last word is dropped and it is tried again, until a real
-    // file turns up or the words run out. `@/Users/me/My Report.md in one line`
-    // finds the report and leaves the rest of the sentence alone.
-    for (const m of line.matchAll(/(?:^|\s)@(\S.*)$/gm)) {
-        const rest = m[1] ?? '';
-        for (let end = rest.length; end > 0; end = rest.lastIndexOf(' ', end - 1)) {
-            const before = found.length;
-            consider(`@${rest.slice(0, end)}`, rest.slice(0, end));
-            if (found.length > before)
+    // tried, then the last word is dropped and it is tried again, until something
+    // on the disk turns up or the words run out. `@/Users/me/My Report.md in one
+    // line` finds the report and leaves the rest of the sentence alone. When
+    // nothing turns up, the first word is what was named, and it is not found.
+    // Every `@`, each with the rest of the line after it. A single match of
+    // "@ to end of line" swallowed every later `@` on the same line, so
+    // `@a.txt @b.txt` only ever looked at the first.
+    for (const m of line.matchAll(/(?:^|\s)@(?=[^\s"'])/g)) {
+        const rest = (line.slice((m.index ?? 0) + m[0].length).split(/\r?\n/)[0]) ?? '';
+        let hit = false;
+        // Punctuation that closes a sentence is tried off as well as on, because
+        // `@layout.png,` means layout.png. Tried second, so a name that really
+        // ends in one of these is still found first.
+        const trimmed = (text) => text.replace(/[,.:;!?)\]]+$/, '');
+        for (let end = rest.length; end > 0 && !hit; end = rest.lastIndexOf(' ', end - 1)) {
+            for (const candidate of new Set([rest.slice(0, end), trimmed(rest.slice(0, end))])) {
+                if (!candidate || !present(expand(unescapePath(candidate, platform), root, here)))
+                    continue;
+                hit = consider(`@${candidate}`, candidate, true);
                 break;
+            }
+        }
+        if (!hit) {
+            const word = (platform === 'win32' ? /^\S+/ : /^(?:\\.|[^\s\\])+/).exec(rest)?.[0];
+            const named = word ? trimmed(word) || word : '';
+            if (named)
+                consider(`@${named}`, named, true);
         }
     }
     // Then every run of non-space, with `\ ` counting as part of the run rather
-    // than as the end of it. This is the dragged-file case and the `@` case.
-    for (const m of line.matchAll(/(?:\\.|[^\s\\])+/g)) {
+    // than as the end of it (except on Windows, where a backslash is a folder).
+    // This is the dragged-file case.
+    const runs = platform === 'win32' ? /\S+/g : /(?:\\.|[^\s\\])+/g;
+    for (const m of line.matchAll(runs)) {
         const raw = m[0];
-        if (!raw)
+        if (!raw || raw.startsWith('@') || raw.startsWith('"') || raw.startsWith("'"))
             continue;
-        const body = raw.startsWith('@') ? raw.slice(1) : raw;
-        const deliberate = raw.startsWith('@')
-            || /^[/~]/.test(body) || body.startsWith('./') || body.startsWith('../');
+        const deliberate = /^[/~]/.test(raw) || /^\.\.?[\\/]/.test(raw)
+            || WINDOWS_ABSOLUTE.test(raw);
         if (!deliberate)
             continue;
-        consider(raw, body);
+        consider(raw, raw, false);
     }
     return found;
 }
+/** The line begins with an absolute path to something on the disk, as a
+ *  dragged file does, rather than with a slashed command word. */
+function startsWithPath(line, platform = process.platform) {
+    const first = (platform === 'win32' ? /^\S+/ : /^(?:\\.|[^\s\\])+/).exec(line.trim())?.[0];
+    if (!first || !first.startsWith('/') || first.indexOf('/', 1) < 0)
+        return false;
+    return present(unescapePath(first, platform));
+}
 /**
  * The question with the long paths taken out and the file names left in.
  *
@@ -179,13 +277,31 @@ function withoutPaths(line, found) {
         out = out.replace(m.raw, path.basename(m.file));
     return out.replace(/\s{2,}/g, ' ').trim();
 }
+/** The line with every mention taken out: empty when it named files and said
+ *  nothing else, which is a drag and drop waiting for its question. */
+function withoutMentions(line, found) {
+    let out = line;
+    for (const m of found)
+        out = out.replace(m.raw, ' ');
+    return out.replace(/\s+/g, ' ').trim();
+}
+function fromServer(row) {
+    return {
+        id: row.id, filename: row.filename, format: row.format,
+        chars: row.chars, truncated: row.truncated, isImage: row.is_image,
+        sizeBytes: row.size_bytes ?? 0,
+        // An older service sent no summary. The bare facts, never a local verdict.
+        summary: row.summary
+            ?? (row.is_image ? row.format : `${row.format}   ${row.chars} chars`),
+    };
+}
 /**
  * Hand the files to the server and get back the ids the question will carry.
  *
  * One at a time and in order, because the caps are per file and a refusal names
- * which file it is refusing. A file that cannot be read does not stop the
- * others: the person gets their answer about the four that worked, and is told
- * plainly about the one that did not.
+ * which file it is refusing. The service is asked first, by name and size, so a
+ * program file or a file over the limit is refused before a byte of it moves.
+ * A file that cannot be read does not stop the others.
  */
 async function upload(baseUrl, credential, files) {
     const root = baseUrl.replace(/\/+$/, '');
@@ -193,23 +309,27 @@ async function upload(baseUrl, credential, files) {
     const refused = [];
     for (const file of files) {
         try {
-            const form = new FormData();
-            form.append('file', new Blob([fs.readFileSync(file)]), path.basename(file));
-            const res = await fetch(`${root}/api/v1/agent/attachments`, {
-                method: 'POST',
-                headers: { Authorization: `Bearer ${credential}` },
-                body: form,
+            const name = path.basename(file);
+            const size = fs.statSync(file).size;
+            const granted = await (0, gateway_1.ask)({
+                intent: 'attach', prompt: '', attachment: { filename: name, size_bytes: size },
             });
+            if (granted.ok && granted.served !== false && granted.granted === false) {
+                refused.push({ file, why: granted.message || `${name} was not accepted`,
+                    code: granted.refusal ?? undefined });
+                continue;
+            }
+            const pass = granted.ok && granted.served !== false ? granted.upload : null;
+            const where = pass?.upload_path || '/api/v1/agent/attachments';
+            const form = new FormData();
+            form.append('file', new Blob([fs.readFileSync(file)]), name);
+            const res = await fetch(`${root}${where}${pass?.ticket ? `?ticket=${encodeURIComponent(pass.ticket)}` : ''}`, { method: 'POST', headers: { Authorization: `Bearer ${credential}` }, body: form });
             if (!res.ok) {
                 const body = await res.json().catch(() => ({}));
-                refused.push({ file, why: body.detail || `the server said ${res.status}` });
+                refused.push({ file, why: body.detail || `the server said ${res.status}`, code: body.code });
                 continue;
             }
-            const row = await res.json();
-            attached.push({
-                id: row.id, filename: row.filename, format: row.format,
-                chars: row.chars, truncated: row.truncated, isImage: row.is_image,
-            });
+            attached.push(fromServer(await res.json()));
         }
         catch (err) {
             refused.push({ file, why: err.message });
@@ -217,12 +337,59 @@ async function upload(baseUrl, credential, files) {
     }
     return { attached, refused };
 }
-/** What was attached, in one line each, for the person to see before it runs. */
-function describe(a) {
-    if (a.isImage)
-        return `${a.filename}  read as a picture`;
-    const size = a.chars >= 1000
-        ? `${Math.round(a.chars / 1000)}k characters`
-        : `${a.chars} characters`;
-    return `${a.filename}  ${size}${a.truncated ? ', shortened to fit' : ''}`;
+/** One `attached` line per file, names in a column, as manual 3.1 shows. */
+function describe(items) {
+    const width = Math.max(0, ...items.map((a) => a.filename.length));
+    return items.map((a) => `attached  ${a.filename.padEnd(width)}   ${a.summary}`);
+}
+/** The waiting list, numbered for `detach N` (manual 3.6). */
+function listing(items) {
+    const width = Math.max(0, ...items.map((a) => a.filename.length));
+    return items.map((a, i) => `${String(i + 1).padStart(2)}  ${a.filename.padEnd(width)}  ${a.summary}`);
+}
+/** Folders never offered by Tab: nobody attaches from them. */
+const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'out', '__pycache__', '.venv', 'venv']);
+/**
+ * File names from the project for Tab after `@` (manual 3.1).
+ *
+ * A bounded walk, because a completion that takes a second is one nobody uses.
+ */
+function projectFiles(root, limit = 5000) {
+    const out = [];
+    const walk = (dir) => {
+        if (out.length >= limit)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (out.length >= limit)
+                return;
+            if (entry.isDirectory()) {
+                if (entry.name.startsWith('.') || SKIP.has(entry.name))
+                    continue;
+                walk(path.join(dir, entry.name));
+            }
+            else if (entry.isFile()) {
+                out.push(path.relative(root, path.join(dir, entry.name)).split(path.sep).join('/'));
+            }
+        }
+    };
+    walk(root);
+    return out.sort();
+}
+/** What Tab completes the line to, in readline's shape: the choices, and the
+ *  part of the line they replace. */
+function completeAt(line, files) {
+    const m = /(?:^|\s)(@[^\s]*)$/.exec(line);
+    if (!m)
+        return [[], line];
+    const typed = m[1];
+    const prefix = typed.slice(1);
+    const hits = files().filter((f) => f.startsWith(prefix)).map((f) => `@${f}`);
+    return [hits.slice(0, 200), typed];
 }

package/out/lib/clipboard.d.ts

@@ -0,0 +1,23 @@
+/** What reading the clipboard came to. */
+export type Clip = {
+    ok: true;
+    file: string;
+    folder: string;
+} | {
+    ok: false;
+    why: string;
+};
+/** Runs one program and reports its exit, output and whether it was found.
+ *  With `out`, the program's output is written to that file as bytes. */
+export type Runner = (file: string, args: string[], out?: string) => Promise<{
+    code: number;
+    stdout: string;
+    missing: boolean;
+}>;
+/**
+ * Save the clipboard's picture as `clipboard-N.png` in a new temporary folder.
+ * `n` numbers the pastes in one session, so three screenshots are three names.
+ */
+export declare function readClipboardImage(n: number, exec?: Runner, platform?: string): Promise<Clip>;
+/** Remove a paste's temporary folder. Always called, whatever happened. */
+export declare function discard(folder: string): void;

package/out/lib/clipboard.js

@@ -0,0 +1,182 @@
+"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.readClipboardImage = readClipboardImage;
+exports.discard = discard;
+/**
+ * The picture on the clipboard, saved to a temporary file (manual 3.4).
+ *
+ * A terminal cannot hand a program a picture: Ctrl+V and Cmd+V paste text.
+ * So `paste` asks the operating system for the clipboard's picture with the
+ * tool each one already has, writes it to a file in a fresh temporary folder,
+ * and the session attaches that file like any other. The caller removes the
+ * folder straight after the upload; nothing is kept.
+ *
+ *   macOS    osascript, which every Mac has (pngpaste is used when present)
+ *   Linux    wl-paste on Wayland, xclip on X11
+ *   Windows  PowerShell and the .NET clipboard
+ *
+ * Every program is run with an argument list, never a shell string, so
+ * nothing in a path is ever read as a command.
+ */
+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"));
+const run = (file, args, out) => new Promise((resolve) => {
+    (0, node_child_process_1.execFile)(file, args, { encoding: out ? 'buffer' : 'utf8', timeout: 15_000,
+        maxBuffer: 64 * 1024 * 1024 }, (err, stdout) => {
+        const failure = err;
+        if (out && !err && Buffer.isBuffer(stdout))
+            fs.writeFileSync(out, stdout);
+        resolve({
+            code: failure ? (typeof failure.code === 'number' ? failure.code : 1) : 0,
+            stdout: Buffer.isBuffer(stdout) ? '' : String(stdout ?? ''),
+            missing: failure?.code === 'ENOENT',
+        });
+    });
+});
+const SAVE_INSTEAD = 'save the picture and attach its path instead.';
+const NO_IMAGE = 'The clipboard holds no image. Nothing was attached.';
+const TEXT_ONLY = 'The clipboard holds no image, only text. Nothing was attached.';
+function landed(file) {
+    try {
+        return fs.statSync(file).size > 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function mac(file, exec) {
+    const types = await exec('osascript', ['-e', 'clipboard info']);
+    const info = types.stdout;
+    if (!/PNGf|TIFF|JPEG|GIFf|picture/i.test(info)) {
+        return /utf8|string|text/i.test(info) ? TEXT_ONLY : NO_IMAGE;
+    }
+    const quick = await exec('pngpaste', [file]);
+    if (!quick.missing && quick.code === 0 && landed(file))
+        return null;
+    // AppleScript writes the clipboard's PNG straight into the file. The path is
+    // an argument to the script, never part of its text.
+    const script = [
+        'on run argv',
+        'set f to open for access (POSIX file (item 1 of argv)) with write permission',
+        'try',
+        'write (the clipboard as «class PNGf») to f',
+        'end try',
+        'close access f',
+        'end run',
+    ];
+    await exec('osascript', [...script.flatMap((l) => ['-e', l]), file]);
+    return landed(file) ? null : NO_IMAGE;
+}
+async function linux(file, exec) {
+    const wayland = Boolean(process.env.WAYLAND_DISPLAY);
+    const x11 = Boolean(process.env.DISPLAY);
+    if (!wayland && !x11) {
+        return `There is no desktop session here to paste from, so ${SAVE_INSTEAD}`;
+    }
+    if (wayland) {
+        const types = await exec('wl-paste', ['--list-types']);
+        if (!types.missing) {
+            if (!/image\/png/.test(types.stdout)) {
+                return /text\//.test(types.stdout) ? TEXT_ONLY : NO_IMAGE;
+            }
+            const got = await exec('wl-paste', ['--type', 'image/png'], file);
+            return got.code === 0 && landed(file) ? null : NO_IMAGE;
+        }
+    }
+    if (x11) {
+        const targets = await exec('xclip', ['-selection', 'clipboard', '-t', 'TARGETS', '-o']);
+        if (!targets.missing) {
+            if (!/image\/png/.test(targets.stdout)) {
+                return /UTF8_STRING|STRING|text\//.test(targets.stdout) ? TEXT_ONLY : NO_IMAGE;
+            }
+            const got = await exec('xclip', ['-selection', 'clipboard', '-t', 'image/png', '-o'], file);
+            return got.code === 0 && landed(file) ? null : NO_IMAGE;
+        }
+    }
+    return `Pasting a picture needs ${wayland ? 'wl-paste' : 'xclip'}, which is not installed. `
+        + `Install it, or ${SAVE_INSTEAD}`;
+}
+async function windows(file, exec) {
+    // The file name reaches PowerShell as an argument, never inside the script.
+    const script = [
+        'param($out)',
+        'Add-Type -AssemblyName System.Windows.Forms',
+        'Add-Type -AssemblyName System.Drawing',
+        '$img = [System.Windows.Forms.Clipboard]::GetImage()',
+        'if ($img) { $img.Save($out, [System.Drawing.Imaging.ImageFormat]::Png); "image" }',
+        'elseif ([System.Windows.Forms.Clipboard]::ContainsText()) { "text" }',
+        'else { "empty" }',
+    ].join('; ');
+    const got = await exec('powershell.exe', ['-NoProfile', '-STA', '-Command', `& { ${script} }`, file]);
+    if (got.missing)
+        return `Pasting a picture needs PowerShell, which was not found, so ${SAVE_INSTEAD}`;
+    if (/image/.test(got.stdout) && landed(file))
+        return null;
+    return /text/.test(got.stdout) ? TEXT_ONLY : NO_IMAGE;
+}
+/**
+ * Save the clipboard's picture as `clipboard-N.png` in a new temporary folder.
+ * `n` numbers the pastes in one session, so three screenshots are three names.
+ */
+async function readClipboardImage(n, exec = run, platform = process.platform) {
+    const folder = fs.mkdtempSync(path.join(os.tmpdir(), 'comprism-paste-'));
+    const file = path.join(folder, `clipboard-${n}.png`);
+    let why;
+    try {
+        why = platform === 'darwin' ? await mac(file, exec)
+            : platform === 'win32' ? await windows(file, exec)
+                : await linux(file, exec);
+    }
+    catch (err) {
+        why = `The clipboard could not be read (${err.message}), so ${SAVE_INSTEAD}`;
+    }
+    if (why) {
+        discard(folder);
+        return { ok: false, why };
+    }
+    return { ok: true, file, folder };
+}
+/** Remove a paste's temporary folder. Always called, whatever happened. */
+function discard(folder) {
+    try {
+        fs.rmSync(folder, { recursive: true, force: true });
+    }
+    catch {
+        /* already gone */
+    }
+}

package/out/lib/commandlist.d.ts

@@ -0,0 +1,20 @@
+export interface Listed {
+    name: string;
+    description: string;
+    /** `session`, `project skill`, `company skill`, `project command`, ... */
+    source: string;
+}
+export interface CommandList {
+    /** False when the service could not be asked. Nothing below is then known. */
+    ok: boolean;
+    items: Listed[];
+    /** Words the service knows that this version of the tool does not run. */
+    needsUpdate: string[];
+    /** Whether typed requests may be kept on this machine between sessions. */
+    keepHistory: boolean;
+}
+export declare function readOne(root: string, rel: string): string | null;
+export declare function listOne(root: string, rel: string): string[] | null;
+/** Ask the service for this project's list. `words` are the session words
+ *  this tool runs. */
+export declare function fetchCommandList(root: string, words: string[]): Promise<CommandList>;