looply-cli 0.0.0-stage → 0.2.0

package/dist/source-cmd.js

@@ -0,0 +1,684 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXIT = exports.SOURCE_USAGE = void 0;
+exports.kindForFile = kindForFile;
+exports.clientRefFor = clientRefFor;
+exports.sourceCommand = sourceCommand;
+exports.anchorLabel = anchorLabel;
+exports.dispositionLabel = dispositionLabel;
+exports.attestationLabel = attestationLabel;
+exports.renderSource = renderSource;
+exports.renderCoverage = renderCoverage;
+exports.nodeSourceDeps = nodeSourceDeps;
+const crypto_1 = require("crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const core_1 = require("@looply/core");
+const index_for_head_1 = require("./index-for-head");
+const machine_store_1 = require("./machine-store");
+const pdf_text_1 = require("./pdf-text");
+const server_client_1 = require("./server-client");
+const source_verdict_1 = require("./source-verdict");
+/**
+ * `looply source` — hand a document to the project from the machine that holds it.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHY THIS IS A CLI VERB AND NOT A PHONE SCREEN
+ *
+ * A plan lives beside the repository, on the developer's disk. Handing it over
+ * is a file operation, and the machine that holds the file is the natural
+ * caller — the same reason project creation is a machine act. The phone reads
+ * what was handed over; it does not type documents.
+ *
+ * ⚠️ LOCAL REFUSALS COME FIRST. The kind is decided from the extension, the
+ * file is read, and the same `whyUnreadable` and size bound the server applies
+ * are applied HERE, before pairing is even looked at — so a person gets the
+ * real answer ("no text layer", "this file has a NUL byte") without a network
+ * round trip, and an unpaired machine is told to pair only when the document
+ * itself was fine.
+ *
+ * A PDF is read HERE, on the machine that holds it (`pdf-text.ts`): its text
+ * layer goes to the server page by page, and the file's own sha256 travels
+ * beside it as provenance. A scanned PDF — no text layer — is refused with
+ * the reason, never sent as an empty document.
+ *
+ * 🔴 THE CONTENT IS DATA. Nothing in this file interprets the document. The
+ * text goes to the server verbatim; the server derives the statements with the
+ * same extractor the fixture tests hold to account.
+ *
+ * `clientRef` is derived from the content's sha256, so running the command
+ * twice on the same file is the same request twice — the server answers with
+ * the source it already has and this prints "already stored".
+ *
+ * `looply source reconcile <id>` measures where each requirement stands against
+ * THIS repository: the project index of HEAD's tree (the same one a run
+ * builds) is read here, `@looply/core`'s reconciler decides — absent, a
+ * candidate place to look, conflicting, or blocked — and the result is handed
+ * over keyed by the tree. Nothing here, on the machine or on the server, says
+ * "implemented": that is a person's attestation with evidence, a later verb.
+ */
+exports.SOURCE_USAGE = `usage:
+  looply source add <file> [--name <name>]   hand a Markdown (.md), plain-text (.txt) or PDF (.pdf, with a text layer) document to this project
+  looply source list                         what this project has been given
+  looply source show <id>                    one source: its statements, what each one IS, where it came from, and where each requirement stands
+  looply source reconcile <id>               measure where each requirement stands against this repository (HEAD's tree), and record it
+  looply source coverage <id>                which requirements no goal serves, which are served, and which a person evidenced
+  looply source plan <id> [--dry-run]        propose goals from this document’s requirements, grouped by its headings, and set them
+  looply source verdict <id>                 the final verdict on the integrated tree: COMPLETE, or every unmet requirement
+`;
+/** Exit codes, in the sysexits tradition the rest of the CLI follows for 64. */
+exports.EXIT = {
+    ok: 0,
+    refused: 1,
+    usage: 64,
+    unreadable: 65,
+    noInput: 66,
+    unavailable: 69,
+};
+/** Which kind a file is, decided from its extension alone — and by name what it is not. */
+function kindForFile(path) {
+    const ext = (0, node_path_1.extname)(path).toLowerCase();
+    if (ext === '.md' || ext === '.markdown')
+        return { ok: true, kind: 'markdown' };
+    if (ext === '.txt' || ext === '.text')
+        return { ok: true, kind: 'text' };
+    if (ext === '.pdf')
+        return { ok: true, kind: 'pdf' };
+    const shown = ext === '' ? 'a file with no extension' : `${ext} files`;
+    return { ok: false, because: `${shown} are not supported; Markdown (.md), plain text (.txt) and PDF (.pdf) are` };
+}
+/** The idempotency key for a document: its own bytes. */
+function clientRefFor(sha256) {
+    return `cli:${sha256}`;
+}
+async function sourceCommand(argv, deps) {
+    const [sub, ...rest] = argv;
+    if (sub === 'add')
+        return add(rest, deps);
+    if (sub === 'list')
+        return list(deps);
+    if (sub === 'show')
+        return show(rest, deps);
+    if (sub === 'reconcile')
+        return reconcile(rest, deps);
+    if (sub === 'coverage')
+        return coverage(rest, deps);
+    if (sub === 'plan')
+        return plan(rest, deps);
+    if (sub === 'verdict')
+        return verdict(rest, deps);
+    deps.err(sub === undefined ? exports.SOURCE_USAGE : `looply source: unknown subcommand ${JSON.stringify(sub)}\n\n${exports.SOURCE_USAGE}`);
+    return exports.EXIT.usage;
+}
+async function add(argv, deps) {
+    const nameAt = argv.indexOf('--name');
+    const nameGiven = nameAt >= 0 ? argv[nameAt + 1] : undefined;
+    const positional = argv
+        .filter((_, i) => nameAt < 0 || (i !== nameAt && i !== nameAt + 1))
+        .filter((a) => !a.startsWith('--'));
+    const file = positional[0];
+    if (!file) {
+        deps.err(`looply source add: which file?\n\n${exports.SOURCE_USAGE}`);
+        return exports.EXIT.usage;
+    }
+    if (nameAt >= 0 && !nameGiven) {
+        deps.err('looply source add: --name needs a value');
+        return exports.EXIT.usage;
+    }
+    // 1. The kind, by name — before reading anything.
+    const kind = kindForFile(file);
+    if (!kind.ok) {
+        deps.err(`looply source add: ${kind.because}`);
+        return exports.EXIT.unreadable;
+    }
+    // 2. The bytes, where they live — and for a PDF, its text layer, read here.
+    const absolute = (0, node_path_1.resolve)(deps.cwd(), file);
+    let content;
+    let pages;
+    let originSha256;
+    if (kind.kind === 'pdf') {
+        let bytes;
+        try {
+            bytes = deps.readBytes(absolute);
+        }
+        catch {
+            deps.err(`looply source add: cannot read ${absolute}`);
+            return exports.EXIT.noInput;
+        }
+        const read = await deps.pdfPages(bytes);
+        if (!read.ok) {
+            deps.err(`looply source add: ${read.because}`);
+            return exports.EXIT.unreadable;
+        }
+        pages = read.pages;
+        originSha256 = (0, crypto_1.createHash)('sha256').update(bytes).digest('hex');
+        // ⚠️ THE SAME RULE THE SERVER STORES BY, called rather than repeated — the
+        // byte count printed below is then the one the server will hold, instead of
+        // a second composition that only a person comparing them by eye could catch
+        // drifting.
+        content = (0, core_1.pdfContent)(pages);
+    }
+    else {
+        try {
+            content = deps.readFile(absolute);
+        }
+        catch {
+            deps.err(`looply source add: cannot read ${absolute}`);
+            return exports.EXIT.noInput;
+        }
+    }
+    // 3. The same refusals the server would make, made here first.
+    for (const [where, text] of pages ? pages.map((p) => [`page ${p.page}: `, p.text]) : [['', content]]) {
+        const because = (0, core_1.whyUnreadable)(text);
+        if (because !== null && !(pages && text.trim().length === 0)) {
+            deps.err(`looply source add: ${where}${because}`);
+            return exports.EXIT.unreadable;
+        }
+    }
+    const { sha256, byteLength } = (0, core_1.sourceDigest)(content);
+    if (byteLength > core_1.MAX_SOURCE_BYTES) {
+        deps.err(`looply source add: the file is ${byteLength} bytes of text; the limit is ${core_1.MAX_SOURCE_BYTES}`);
+        return exports.EXIT.unreadable;
+    }
+    // 4. Only now: who am I, and which project is this?
+    const who = deps.identity();
+    if (who.kind === 'unpaired') {
+        deps.err('looply source add: this machine is not paired yet — run `looply pair` first');
+        return exports.EXIT.unavailable;
+    }
+    if (who.kind === 'unregistered') {
+        deps.err('looply source add: this repository is not registered with the server yet — run `looply daemon --once` here first');
+        return exports.EXIT.unavailable;
+    }
+    const name = (nameGiven ?? (0, node_path_1.basename)(file)).trim();
+    try {
+        const r = await deps.client(who.serverUrl, who.token).createSource(who.projectId, {
+            clientRef: clientRefFor(originSha256 ?? sha256),
+            name,
+            kind: kind.kind,
+            ...(pages ? { pages, originSha256 } : { content }),
+        });
+        const n = r.statements.length;
+        deps.out(`source ${r.source.id}  ${r.source.kind}  ${n} statement${n === 1 ? '' : 's'}  sha256 ${r.source.sha256.slice(0, 12)}…  ${r.deduplicated ? '(already stored)' : '(stored)'}`);
+        deps.out(pages
+            ? `  ${name}: ${pages.length} page${pages.length === 1 ? '' : 's'} of text layer, ${byteLength} bytes; file sha256 ${(originSha256 ?? '').slice(0, 12)}…. \`looply source list\` shows what this project has been given.`
+            : `  ${name}: ${byteLength} bytes, verbatim. \`looply source list\` shows what this project has been given.`);
+        return exports.EXIT.ok;
+    }
+    catch (e) {
+        return reportServerError('add', e, deps);
+    }
+}
+async function list(deps) {
+    const who = deps.identity();
+    if (who.kind === 'unpaired') {
+        deps.err('looply source list: this machine is not paired yet — run `looply pair` first');
+        return exports.EXIT.unavailable;
+    }
+    if (who.kind === 'unregistered') {
+        deps.err('looply source list: this repository is not registered with the server yet — run `looply daemon --once` here first');
+        return exports.EXIT.unavailable;
+    }
+    try {
+        const r = await deps.client(who.serverUrl, who.token).sources(who.projectId);
+        if (r.sources.length === 0) {
+            deps.out('no sources yet — hand one over with: looply source add <file>');
+            return exports.EXIT.ok;
+        }
+        deps.out('sources for this project, newest first:');
+        for (const s of r.sources) {
+            deps.out(`  ${s.id}  ${s.kind.padEnd(8)}  ${String(s.byteLength).padStart(8)} bytes  ${s.name}  ${s.createdAt}`);
+        }
+        return exports.EXIT.ok;
+    }
+    catch (e) {
+        return reportServerError('list', e, deps);
+    }
+}
+/** Where a statement is, in the reader's own terms: `p2 L4-5` for a pdf, `L7` otherwise. */
+function anchorLabel(s) {
+    const lines = s.anchor.lineStart === s.anchor.lineEnd ? `L${s.anchor.lineStart}` : `L${s.anchor.lineStart}-${s.anchor.lineEnd}`;
+    return s.anchor.page === undefined ? lines : `p${s.anchor.page} ${lines}`;
+}
+const firstLine = (text, max = 96) => {
+    const line = text.split('\n')[0] ?? '';
+    return line.length > max ? `${line.slice(0, max - 1)}…` : line;
+};
+/** Where a requirement stands, on one line under it: what was found, or why nothing could be said. */
+function dispositionLabel(d) {
+    const first = d.anchors[0];
+    const at = first === undefined ? '' : `${first.path}${first.line === undefined ? '' : `:${first.line}`}`;
+    const more = d.anchors.length - 1;
+    const kept = d.candidatesTotal > d.anchors.length ? ` (${d.candidatesTotal} in all, ${d.anchors.length} kept)` : '';
+    switch (d.disposition) {
+        case 'candidate':
+            return `candidate    ${at}${more > 0 ? `  +${more} more` : ''}${kept} — a place to look, not evidence`;
+        case 'absent':
+            return `absent       nothing in the repository names: ${d.terms.join(', ')}`;
+        case 'conflicting':
+            return `conflicting  contradicted by #${d.conflictsWith ?? '?'} — the document disagrees with itself`;
+        case 'blocked':
+            return d.rule === 'only-unparsed'
+                ? `blocked      only unparsed files name it: ${d.anchors.map((a) => a.path).join(', ')}${kept}`
+                : d.rule === 'no-index'
+                    ? 'blocked      no project index could be built'
+                    : d.rule === 'nothing-parsed'
+                        ? // Says what was wrong with the INSTRUMENT, because that is what a person
+                            // has to fix. "nothing names it" would send them looking at the document.
+                            'blocked      no file in this repository could be parsed — nothing was searched'
+                        : 'blocked      nothing to look for (no terms)';
+        default:
+            return `${d.disposition}  (attested by a person)`;
+    }
+}
+/** A person's word, on one line: what they said, who, at which tree, and the first place they pointed at. */
+function attestationLabel(a, earlierTree) {
+    const first = a.anchors[0];
+    const at = first === undefined ? '' : ` — ${first.path}${first.line === undefined ? '' : `:${first.line}`}${a.anchors.length > 1 ? `  +${a.anchors.length - 1} more` : ''}`;
+    return `attested ${a.disposition} by ${a.attestedBy} at tree ${a.treeSha.slice(0, 12)}…${at}${earlierTree ? '  (attested at an EARLIER tree than the latest measurement)' : ''}`;
+}
+/**
+ * One source, as a person reads it: requirements first (what is forbidden
+ * marked as such), then constraints, questions, exclusions (which need
+ * authority), duplicates pointing at their first occurrence, and how much is
+ * context. Every line carries its anchor so the document can be opened to it;
+ * every requirement and constraint carries where it stands against the
+ * repository, when that was measured.
+ */
+function renderSource(detail) {
+    const { source, statements, classifications, classifierVersion, dispositions, reconciledAt, attestations } = detail;
+    const standing = new Map(dispositions.map((d) => [d.ordinal, d]));
+    const words = new Map(attestations.map((a) => [a.ordinal, a]));
+    const byOrdinal = new Map(statements.map((s) => [s.ordinal, s]));
+    const out = [];
+    out.push(`source ${source.id}  ${source.name}  ${source.kind}  ${statements.length} statement${statements.length === 1 ? '' : 's'}  sha256 ${source.sha256.slice(0, 12)}…${source.originSha256 ? `  file ${source.originSha256.slice(0, 12)}…` : ''}`);
+    if (classifierVersion === null || classifications.length === 0) {
+        out.push('  not classified yet — run: looply source classify <id> (or hand it over again)');
+        for (const s of statements)
+            out.push(`  #${s.ordinal}  ${anchorLabel(s).padEnd(10)} ${firstLine(s.text)}`);
+        return out;
+    }
+    out.push(`  classified by rules, version ${classifierVersion}. What each statement IS — not whether the repository does it.`);
+    out.push(reconciledAt === null
+        ? `  not reconciled against the repository yet — run: looply source reconcile ${source.id}`
+        : `  reconciled at tree ${reconciledAt.treeSha.slice(0, 12)}… (reconciler v${reconciledAt.reconcilerVersion}): a candidate is a place to look, not evidence; nothing here says implemented.`);
+    const group = (cls) => classifications.filter((c) => c.class === cls);
+    const line = (c, tag) => {
+        const s = byOrdinal.get(c.ordinal);
+        return `  #${String(c.ordinal).padEnd(3)} ${tag.padEnd(9)} ${(s ? anchorLabel(s) : '?').padEnd(10)} ${s ? firstLine(s.text) : '(statement missing)'}`;
+    };
+    // A person's word first, dated by its tree against the latest measurement; the measurement under it.
+    const stands = (c) => {
+        const s = (0, core_1.standingOf)(standing.get(c.ordinal), words.get(c.ordinal), reconciledAt?.treeSha ?? null);
+        if (s.kind === 'unreconciled')
+            return [];
+        if (s.kind === 'measured')
+            return [`       ↳ ${dispositionLabel(s.measured)}`];
+        return [`       ↳ ${attestationLabel(s.attestation, s.earlierTree)}`, ...(s.measured === undefined ? [] : [`         ${dispositionLabel(s.measured)}`])];
+    };
+    const reqs = group('requirement');
+    out.push(`requirements (${reqs.length}):`);
+    /**
+     * 🔴 THE WORD THE DOCUMENT USED, NOT THE STRONGEST ONE AVAILABLE. Every modal
+     * printed as MUST until now, so a reader could not tell an obligation from a
+     * recommendation — and under strict Programme Mode only one of those can block
+     * a COMPLETE. `isMandatory` decides it in one place for every consumer.
+     */
+    for (const c of reqs) {
+        const strong = (0, core_1.isMandatory)(c);
+        const negative = c.polarity === 'negative';
+        const label = strong ? (negative ? 'MUST NOT' : 'MUST') : negative ? 'SHOULD NOT' : 'SHOULD';
+        out.push(line(c, label), ...stands(c));
+    }
+    const cons = group('constraint');
+    out.push(`constraints (${cons.length}):`);
+    for (const c of cons)
+        out.push(line(c, 'limit'), ...stands(c));
+    const qs = group('question');
+    out.push(`questions (${qs.length}) — answers are missing information, not missing authority:`);
+    for (const c of qs) {
+        out.push(line(c, 'ask'));
+        /**
+         * 🔴 WHAT THE SAME STATEMENT DID SETTLE, IF ANYTHING.
+         *
+         * *"The retry limit must be configurable; the default is TBD"* is one
+         * question and one decided obligation, and printing only the first shows a
+         * person a document that decided less than it did. The classifier records
+         * both halves; this is where the second one stops being invisible.
+         */
+        if (c.unresolved?.settled !== undefined)
+            out.push(`      settled: ${c.unresolved.settled}`);
+    }
+    const exs = group('exclusion');
+    out.push(`exclusions (${exs.length}) — excluding scope needs authority:`);
+    for (const c of exs)
+        out.push(line(c, 'excluded'));
+    const dups = group('duplicate');
+    if (dups.length > 0) {
+        out.push(`duplicates (${dups.length}):`);
+        for (const c of dups)
+            out.push(line(c, `= #${c.duplicateOf ?? '?'}`));
+    }
+    const ctx = group('context');
+    out.push(`context: ${ctx.length} statement${ctx.length === 1 ? '' : 's'} (headings, code, prose that demands nothing)`);
+    return out;
+}
+async function show(argv, deps) {
+    const id = argv.find((a) => !a.startsWith('--'));
+    if (!id) {
+        deps.err(`looply source show: which source?\n\n${exports.SOURCE_USAGE}`);
+        return exports.EXIT.usage;
+    }
+    const who = deps.identity();
+    if (who.kind === 'unpaired') {
+        deps.err('looply source show: this machine is not paired yet — run `looply pair` first');
+        return exports.EXIT.unavailable;
+    }
+    if (who.kind === 'unregistered') {
+        deps.err('looply source show: this repository is not registered with the server yet — run `looply daemon --once` here first');
+        return exports.EXIT.unavailable;
+    }
+    try {
+        const detail = await deps.client(who.serverUrl, who.token).sourceDetail(who.projectId, id);
+        for (const l of renderSource(detail))
+            deps.out(l);
+        return exports.EXIT.ok;
+    }
+    catch (e) {
+        return reportServerError('show', e, deps);
+    }
+}
+/**
+ * Measure where each requirement of a source stands against THIS repository,
+ * and hand the measurement over keyed by HEAD's tree.
+ *
+ * ⚠️ THE REPOSITORY COMES FIRST, BEFORE PAIRING: a directory that is not a
+ * repository with a commit has no tree to key a measurement by, and a person
+ * is told that before being told to pair. The index is the run's own
+ * (`index-for-head.ts`), so this and a run measure the same thing.
+ */
+async function reconcile(argv, deps) {
+    const id = argv.find((a) => !a.startsWith('--'));
+    if (!id) {
+        deps.err(`looply source reconcile: which source?\n\n${exports.SOURCE_USAGE}`);
+        return exports.EXIT.usage;
+    }
+    const index = await deps.index(deps.cwd());
+    if (!index.ok) {
+        deps.err(`looply source reconcile: ${index.because}`);
+        return exports.EXIT.unreadable;
+    }
+    const who = deps.identity();
+    if (who.kind === 'unpaired') {
+        deps.err('looply source reconcile: this machine is not paired yet — run `looply pair` first');
+        return exports.EXIT.unavailable;
+    }
+    if (who.kind === 'unregistered') {
+        deps.err('looply source reconcile: this repository is not registered with the server yet — run `looply daemon --once` here first');
+        return exports.EXIT.unavailable;
+    }
+    try {
+        const client = deps.client(who.serverUrl, who.token);
+        const detail = await client.sourceDetail(who.projectId, id);
+        if (detail.classifierVersion === null) {
+            deps.err(`looply source reconcile: source ${id} was never classified, so nothing says which statements are requirements — hand it over again first`);
+            return exports.EXIT.refused;
+        }
+        const dispositions = (0, core_1.reconcileStatements)({
+            statements: detail.statements,
+            classifications: detail.classifications,
+            index: index.snapshot,
+        });
+        const r = await client.reconcileSource(who.projectId, id, {
+            treeSha: index.treeSha,
+            reconcilerVersion: core_1.RECONCILER_VERSION,
+            dispositions,
+        });
+        const n = (kind) => r.dispositions.filter((d) => d.disposition === kind).length;
+        deps.out(`source ${id}  reconciled at tree ${index.treeSha.slice(0, 12)}…  ${r.dispositions.length} requirement${r.dispositions.length === 1 ? '' : 's'}/constraint${r.dispositions.length === 1 ? '' : 's'} measured  ${r.created ? '(recorded)' : '(already on record for this tree)'}`);
+        deps.out(`  candidate ${n('candidate')} · absent ${n('absent')} · conflicting ${n('conflicting')} · blocked ${n('blocked')} — a candidate is a place to look, not evidence; nothing here says implemented. \`looply source show ${id}\` lists them.`);
+        return exports.EXIT.ok;
+    }
+    catch (e) {
+        return reportServerError('reconcile', e, deps);
+    }
+}
+/**
+ * What is covered and by whom, as a person reads it: what NOBODY serves first,
+ * then what is served but not yet evidenced, then partial, then evidenced —
+ * each with its anchor and the goals that name it. Nothing here counts a
+ * finished queue as coverage.
+ */
+function renderCoverage(c) {
+    const n = c.requirements.length;
+    const out = [];
+    out.push(`coverage of ${c.sourceId}  ${c.name}  ${n} requirement${n === 1 ? '' : 's'}/constraint${n === 1 ? '' : 's'}  ${c.reconciledAt === null ? 'not measured against the repository yet' : `measured at tree ${c.reconciledAt.treeSha.slice(0, 12)}…`}`);
+    const line = (r) => {
+        const a = { ordinal: r.ordinal, kind: 'paragraph', text: r.text, anchor: r.anchor };
+        const who = r.goals.length === 0 ? '' : ` — ${r.goals.map((g) => `${g.id} (${g.state} v${g.version})`).join(', ')}`;
+        /**
+         * 🔴 THE WORD THE DOCUMENT USED — the same correction `show` already had.
+         *
+         * This read `r.class === 'requirement' ? 'MUST' : 'limit'`, so every
+         * advisory printed as an obligation. `show` asks `isMandatory`; this could
+         * not, because the row did not carry the answer. It does now.
+         */
+        const label = r.class !== 'requirement'
+            ? 'limit'
+            : r.mandatory
+                ? r.negative
+                    ? 'MUST NOT'
+                    : 'MUST'
+                : r.negative
+                    ? 'SHOULD NOT'
+                    : 'SHOULD';
+        return `  #${String(r.ordinal).padEnd(3)} ${label.padEnd(6)} ${anchorLabel(a).padEnd(10)} ${firstLine(r.text)}${who}`;
+    };
+    const group = (kind) => c.requirements.filter((r) => r.coverage === kind);
+    const section = (title, kind) => {
+        const rows = group(kind);
+        out.push(`${title} (${rows.length}):`);
+        for (const r of rows)
+            out.push(line(r));
+    };
+    section('unserved — no goal names these', 'unserved');
+    section('served, not yet evidenced', 'served');
+    section('partial — a person said so', 'partial');
+    section('evidenced — a person attested implemented-and-evidenced at the measured tree', 'evidenced');
+    section('evidenced at an EARLIER tree than the latest measurement', 'evidenced-at-an-earlier-tree');
+    return out;
+}
+async function coverage(argv, deps) {
+    const id = argv.find((a) => !a.startsWith('--'));
+    if (!id) {
+        deps.err(`looply source coverage: which source?\n\n${exports.SOURCE_USAGE}`);
+        return exports.EXIT.usage;
+    }
+    const who = deps.identity();
+    if (who.kind === 'unpaired') {
+        deps.err('looply source coverage: this machine is not paired yet — run `looply pair` first');
+        return exports.EXIT.unavailable;
+    }
+    if (who.kind === 'unregistered') {
+        deps.err('looply source coverage: this repository is not registered with the server yet — run `looply daemon --once` here first');
+        return exports.EXIT.unavailable;
+    }
+    try {
+        const c = await deps.client(who.serverUrl, who.token).coverage(who.projectId, id);
+        for (const l of renderCoverage(c))
+            deps.out(l);
+        return exports.EXIT.ok;
+    }
+    catch (e) {
+        return reportServerError('coverage', e, deps);
+    }
+}
+/**
+ * Turn a document into goals.
+ *
+ * 🔴 THE PROPOSAL IS THE PRODUCT’S, NOT THE OPERATOR’S. `proposeGoals` reads the
+ * document’s own heading structure and groups its requirements under it; nothing
+ * here writes goal text by hand. Every goal carries the requirement ordinals it
+ * serves, so `looply source coverage` can answer which requirements a goal is for
+ * without anybody restating the link.
+ *
+ * ⚠️ `--dry-run` PRINTS AND WRITES NOTHING, and it is the first thing a person
+ * should run. An import that sets twenty goals is not something to discover after
+ * the fact.
+ *
+ * ⚠️ RE-RUNNING IS SAFE AND SAYS SO. `clientRef` is derived from the ordinals, and
+ * `POST /goals` is idempotent on it, so a second run reports every goal as
+ * `already set` rather than doubling the list. The count of each is printed
+ * because a silent no-op and a silent double look identical from the outside.
+ */
+async function plan(argv, deps) {
+    const dryRun = argv.includes('--dry-run');
+    const id = argv.find((a) => !a.startsWith('--'));
+    if (!id) {
+        deps.err(`looply source plan: which source?\n\n${exports.SOURCE_USAGE}`);
+        return exports.EXIT.usage;
+    }
+    const who = deps.identity();
+    if (who.kind === 'unpaired') {
+        deps.err('looply source plan: this machine is not paired yet — run `looply pair` first');
+        return exports.EXIT.unavailable;
+    }
+    if (who.kind === 'unregistered') {
+        deps.err('looply source plan: this repository is not registered with the server yet — run `looply daemon --once` here first');
+        return exports.EXIT.unavailable;
+    }
+    const client = deps.client(who.serverUrl, who.token);
+    let detail;
+    try {
+        detail = await client.sourceDetail(who.projectId, id);
+    }
+    catch (e) {
+        return reportServerError('plan', e, deps);
+    }
+    const proposed = (0, core_1.proposeGoals)({
+        sourceId: detail.source.id,
+        statements: detail.statements,
+        classifications: detail.classifications,
+    });
+    if (proposed.length === 0) {
+        deps.out(`source ${detail.source.id}  ${detail.source.name}  no requirements or constraints — nothing to propose`);
+        return exports.EXIT.ok;
+    }
+    const served = proposed.reduce((n, p) => n + p.requirements.length, 0);
+    deps.out(`source ${detail.source.id}  ${detail.source.name}  ${proposed.length} goal${proposed.length === 1 ? "" : "s"} proposed, ` +
+        `serving ${served} requirement${served === 1 ? "" : "s"}, grouped by the document’s headings`);
+    for (const p of proposed) {
+        deps.out(`  ${p.clientRef}`);
+        for (const line of p.text.split(`\n`))
+            deps.out(`    ${line}`);
+    }
+    if (dryRun) {
+        deps.out('  --dry-run: nothing was set. Run without it to set these goals.');
+        return exports.EXIT.ok;
+    }
+    let created = 0;
+    let already = 0;
+    for (const p of proposed) {
+        try {
+            const r = await client.createGoal(who.projectId, {
+                clientRef: p.clientRef,
+                text: p.text,
+                // The full canonical address of every obligation, table rows included —
+                // never rebuilt from bare ordinals, which is how a row lost its `row`.
+                requirements: [...p.requirements],
+            });
+            if (r.deduplicated)
+                already += 1;
+            else
+                created += 1;
+            deps.out(`  ${r.deduplicated ? "already set" : "set"}  ${r.goal.id}  ${p.clientRef}`);
+        }
+        catch (e) {
+            // 🔴 STOPS AT THE FIRST REFUSAL, and reports what was already set. Carrying
+            // on would leave a half-imported document with no record of where it broke,
+            // and a re-run is safe precisely because the refs are deterministic.
+            deps.err(`looply source plan: stopped after ${created} set, ${already} already set`);
+            return reportServerError('plan', e, deps);
+        }
+    }
+    deps.out(`  ${created} set, ${already} already set`);
+    return exports.EXIT.ok;
+}
+/**
+ * The owner's definition of done, asked of the whole document on the last integrated commit
+ * (`source-verdict.ts`). Exit 0 only for COMPLETE; 1 names what is unmet; 69 when nothing can be
+ * judged — never a verdict read from a lookup that failed.
+ */
+async function verdict(argv, deps) {
+    const id = argv.find((a) => !a.startsWith('--'));
+    if (!id) {
+        deps.err(`looply source verdict: which source?\n\n${exports.SOURCE_USAGE}`);
+        return exports.EXIT.usage;
+    }
+    const who = deps.identity();
+    if (who.kind === 'unpaired') {
+        deps.err('looply source verdict: this machine is not paired yet — run `looply pair` first');
+        return exports.EXIT.unavailable;
+    }
+    if (who.kind === 'unregistered') {
+        deps.err('looply source verdict: this repository is not registered with the server yet — run `looply daemon --once` here first');
+        return exports.EXIT.unavailable;
+    }
+    if (deps.verdict === undefined) {
+        deps.err('looply source verdict: this build cannot read the integration lane');
+        return exports.EXIT.unavailable;
+    }
+    try {
+        const v = await (0, source_verdict_1.sourceVerdict)(id, deps.verdict(deps.cwd(), who));
+        for (const line of (0, source_verdict_1.renderVerdict)(id, v))
+            deps.out(line);
+        return v.kind === 'unavailable' ? exports.EXIT.unavailable : v.complete ? exports.EXIT.ok : exports.EXIT.refused;
+    }
+    catch (e) {
+        // F33: nothing judged is never NOT COMPLETE (1) — every failure to judge is 69, whatever threw.
+        deps.err(`looply source verdict: could not judge — ${e.message}`);
+        return exports.EXIT.unavailable;
+    }
+}
+function reportServerError(verb, e, deps) {
+    if (e instanceof server_client_1.ServerError) {
+        if (e.status === 0) {
+            deps.err(`looply source ${verb}: ${e.message}`);
+            return exports.EXIT.unavailable;
+        }
+        deps.err(`looply source ${verb}: the server refused (${e.status}): ${e.message}`);
+        return exports.EXIT.refused;
+    }
+    throw e;
+}
+/* istanbul ignore next — real fs, real identity file, real client; the logic is tested through deps */
+function nodeSourceDeps() {
+    return {
+        cwd: () => process.cwd(),
+        readFile: (p) => (0, node_fs_1.readFileSync)(p, 'utf8'),
+        readBytes: (p) => new Uint8Array((0, node_fs_1.readFileSync)(p)),
+        pdfPages: (bytes) => (0, pdf_text_1.extractPdfPages)(bytes),
+        identity: () => {
+            const store = new machine_store_1.MachineStore((0, machine_store_1.machineFilePath)());
+            let identity;
+            try {
+                identity = store.load();
+            }
+            catch {
+                return { kind: 'unpaired' };
+            }
+            if (!identity)
+                return { kind: 'unpaired' };
+            const projectId = store.projectFor((0, machine_store_1.repoPathHash)(process.cwd(), (t) => (0, crypto_1.createHash)('sha256').update(t, 'utf8').digest('hex')));
+            if (!projectId)
+                return { kind: 'unregistered' };
+            return { kind: 'ok', serverUrl: identity.serverUrl, token: identity.token, projectId };
+        },
+        index: (cwd) => (0, index_for_head_1.indexForHead)(cwd),
+        client: (serverUrl, token) => new server_client_1.ServerClient({ baseUrl: serverUrl }).withToken(token),
+        out: (line) => process.stdout.write(line + '\n'),
+        err: (line) => process.stderr.write(line + '\n'),
+        verdict: (cwd, who) => (0, source_verdict_1.nodeVerdictDeps)(cwd, who),
+    };
+}
+//# sourceMappingURL=source-cmd.js.map