browser-broker 0.1.0

package/dist/src/cli/image.js

@@ -0,0 +1,274 @@
+import fs from 'node:fs/promises';
+import { fetchArtifact } from "../service/artifacts.js";
+import { hashKey } from "../service/keys.js";
+export const IMAGE_USAGE = [
+    'broker image — write the bytes of one recorded image to a file.',
+    '',
+    'Usage:',
+    '  broker image --lease-key <key> --capture <id> --out <file>',
+    '  broker image --lease-key <key> --overlay <comparison-id> --out <file>',
+    '  broker image --lease-key <key> --region <comparison-id> --index <n> --side before|after --out <file>',
+    '',
+    'Exactly one artifact is named, always by the identifier of a row:',
+    '  --capture <id>     a capture, by its own identifier',
+    '  --overlay <id>     a comparison’s full-frame image with the changed regions outlined',
+    '  --region <id>      one changed region from a comparison, cut from either side',
+    '  --index <n>        which region, from the ordered list; defaults to 0, the largest',
+    '  --side before|after  which capture the crop comes from; defaults to after',
+    '',
+    '  --out <file>       where to write the bytes. Required.',
+    '  --json             one JSON document, for something reading rather than someone',
+    '',
+    'Whether the bytes are a whole capture or a crop, they arrive the same way.',
+].join('\n');
+/** The three ways to name an artifact, and the request each builds. */
+const SELECTORS = ['--capture', '--overlay', '--region'];
+function needsValue(flag) {
+    return { ok: false, message: `${flag} needs an identifier after it.` };
+}
+/**
+ * Parse the arguments after `image`.
+ *
+ * **An unrecognised flag refuses rather than being ignored**, matching `diffs`:
+ * ignoring one would serve an artifact nobody asked for and print a result that
+ * looks like an answer.
+ *
+ * **Exactly one selector is required.** Two would make the command choose, and
+ * a command that silently prefers one flag over another when given both is one
+ * whose behaviour has to be learned rather than read.
+ */
+export function parseImageArguments(argv) {
+    let leaseKey;
+    let out;
+    let json = false;
+    let index;
+    let side;
+    const selected = [];
+    for (let at = 0; at < argv.length; at += 1) {
+        const argument = argv[at] ?? '';
+        if (argument === '--json') {
+            json = true;
+            continue;
+        }
+        if (argument === '--lease-key' || argument === '--out') {
+            const value = argv[at + 1];
+            if (value === undefined || value.startsWith('--')) {
+                return {
+                    ok: false,
+                    message: argument === '--out'
+                        ? '--out needs a file to write to.'
+                        : '--lease-key needs your lease key after it.',
+                };
+            }
+            if (argument === '--out') {
+                out = value;
+            }
+            else {
+                leaseKey = value;
+            }
+            at += 1;
+            continue;
+        }
+        if (argument === '--index') {
+            const raw = argv[at + 1];
+            if (raw === undefined) {
+                return { ok: false, message: '--index needs a number after it.' };
+            }
+            const value = Number(raw);
+            if (!Number.isInteger(value) || value < 0) {
+                return {
+                    ok: false,
+                    message: `--index takes a whole number of at least zero; got ${JSON.stringify(raw)}.`,
+                };
+            }
+            index = value;
+            at += 1;
+            continue;
+        }
+        if (argument === '--side') {
+            const raw = argv[at + 1];
+            if (raw !== 'before' && raw !== 'after') {
+                return {
+                    ok: false,
+                    message: `--side takes "before" or "after"; got ${JSON.stringify(raw ?? '')}. A crop is cut from one capture or the other.`,
+                };
+            }
+            side = raw;
+            at += 1;
+            continue;
+        }
+        const selector = SELECTORS.find((each) => each === argument);
+        if (selector !== undefined) {
+            const value = argv[at + 1];
+            if (value === undefined || value.startsWith('--')) {
+                return needsValue(selector);
+            }
+            selected.push({ flag: selector, id: value });
+            at += 1;
+            continue;
+        }
+        return {
+            ok: false,
+            message: `Unrecognised option: ${argument}`,
+        };
+    }
+    if (leaseKey === undefined) {
+        return {
+            ok: false,
+            message: '--lease-key is required. An image belongs to the lease that took it, so there is no way to ask for one without saying which lease is asking.',
+        };
+    }
+    if (selected.length === 0) {
+        return {
+            ok: false,
+            message: `Name one artifact: ${SELECTORS.join(', ')}. Each takes the identifier of a row.`,
+        };
+    }
+    if (selected.length > 1) {
+        return {
+            ok: false,
+            message: `Name exactly one artifact; got ${selected.map((each) => each.flag).join(' and ')}.`,
+        };
+    }
+    if (out === undefined) {
+        return {
+            ok: false,
+            message: '--out is required: this command writes the bytes to a file rather than to the terminal, because an image on a terminal is not an image.',
+        };
+    }
+    const chosen = selected[0];
+    // `--index` and `--side` describe a region and mean nothing otherwise.
+    // Refused rather than ignored, for the same reason an unrecognised flag is:
+    // a caller who passed them expects them to have done something.
+    if (chosen.flag !== '--region' && (index !== undefined || side !== undefined)) {
+        return {
+            ok: false,
+            message: `--index and --side describe which region to cut, so they only apply to --region; got ${chosen.flag}.`,
+        };
+    }
+    if (chosen.flag === '--capture') {
+        return { ok: true, leaseKey, request: { kind: 'capture', captureId: chosen.id }, out, json };
+    }
+    if (chosen.flag === '--overlay') {
+        return {
+            ok: true,
+            leaseKey,
+            request: { kind: 'overlay', comparisonId: chosen.id },
+            out,
+            json,
+        };
+    }
+    return {
+        ok: true,
+        leaseKey,
+        request: {
+            kind: 'region',
+            comparisonId: chosen.id,
+            // The list is ordered largest first (§1.9), so the first region is the
+            // one a person almost always wants and is the only defensible default.
+            index: index ?? 0,
+            side: side ?? 'after',
+        },
+        out,
+        json,
+    };
+}
+/** How a capture row is found. The captures table is the pipeline's. */
+export function captureLookup(db) {
+    return {
+        find: (captureId) => {
+            const row = db
+                .prepare('SELECT claim_id AS claimId, path FROM captures WHERE id = ?')
+                .get(captureId);
+            return row === undefined ? null : { claimId: row.claimId, path: row.path };
+        },
+    };
+}
+/** Exit codes, matching the dispatcher's own (`cli/index.ts`). */
+export const IMAGE_EXIT = { served: 0, malformed: 2, refused: 3 };
+/**
+ * Run the command.
+ *
+ * **The lease is resolved by hashing the key**, exactly as every keyed call
+ * does. A claim that cannot be found refuses with the *same* sentence as an
+ * artifact that is not yours, and that is deliberate rather than lazy: §1.9
+ * requires the non-disclosing wording "so probing cannot discover another
+ * lease's files", and a distinguishable "no such lease" would let a caller
+ * with a wrong key learn which identifiers exist.
+ *
+ * **This does not extend the lease**, and the difference from the ten
+ * operations is the point. §3.1: "every tool except the first takes the lease
+ * key, and every call carrying the key extends the lease" — that rule is about
+ * the *agent* surface, where a call is evidence the caller is still working.
+ * This is a person reading a file that has already been written; a lease is not
+ * kept alive by somebody looking at a picture it took.
+ */
+export async function runImage(argv, options) {
+    const { db, streams } = options;
+    const parsed = parseImageArguments(argv);
+    if (!parsed.ok) {
+        streams.err(parsed.message);
+        streams.err('');
+        streams.err(IMAGE_USAGE);
+        return IMAGE_EXIT.malformed;
+    }
+    // Looked up by hash. The key itself is never compared or printed (§5.6).
+    const claim = db
+        .prepare('SELECT id FROM claims WHERE key_hash = ?')
+        .get(hashKey(parsed.leaseKey));
+    const outcome = claim === undefined
+        ? null
+        : await fetchArtifact({
+            db,
+            artifacts: options.artifacts,
+            claimId: claim.id,
+            captures: captureLookup(db),
+            request: parsed.request,
+        });
+    if (outcome === null || !outcome.served) {
+        // One sentence for "not yours" and for "not there", and for a key that
+        // names no lease. Three distinguishable answers here would be three ways
+        // to enumerate what exists.
+        const refusal = outcome === null
+            ? { reason: 'not_found', message: NOT_FOUND_MESSAGE }
+            : outcome.refusal;
+        if (parsed.json) {
+            streams.out(JSON.stringify({ outcome: 'refused', reason: refusal.reason, message: refusal.message }));
+        }
+        else {
+            streams.err(`refused (artifact.${refusal.reason}): ${refusal.message}`);
+        }
+        return IMAGE_EXIT.refused;
+    }
+    const write = options.write ?? ((destination, bytes) => fs.writeFile(destination, bytes));
+    await write(parsed.out, outcome.artifact.bytes);
+    // **The identical report for every kind.** A capture and a crop differ in
+    // what they are a picture of and in nothing else a caller can observe here.
+    if (parsed.json) {
+        streams.out(JSON.stringify({
+            outcome: 'served',
+            value: {
+                // The stored path, which is relative to the artifact root and is
+                // therefore safe to report: §1.7a's rule is that no absolute path is
+                // reported, because an absolute path names one machine.
+                path: outcome.artifact.path,
+                bytes: outcome.artifact.bytes.byteLength,
+                writtenTo: parsed.out,
+            },
+        }));
+    }
+    else {
+        streams.out(`Wrote ${String(outcome.artifact.bytes.byteLength)} bytes to ${parsed.out} (from ${outcome.artifact.path}).`);
+    }
+    return IMAGE_EXIT.served;
+}
+/**
+ * The sentence used when the key names no lease.
+ *
+ * Imported rather than respelled would be better, but the artifacts module's
+ * constant is about an artifact and this is about a key that matched nothing —
+ * two different situations that must produce **one indistinguishable answer**.
+ * A test asserts the two strings are byte-identical, so the requirement is
+ * checked rather than trusted to whoever edits one of them next.
+ */
+export const NOT_FOUND_MESSAGE = 'No artifact with that identifier belongs to this lease.';