sfora-cli 0.10.0 → 0.11.0

package/dist/cli.js

@@ -11,22 +11,16 @@ import { spawn } from "node:child_process";
 import { readFile as readLocalFile } from "node:fs/promises";
 import { basename } from "node:path";
 import { taskUploadFilename } from "./format/taskUploadFilename.js";
-import { createSforaShell, createLocalShell, SforaApiClient } from "./index.js";
+import { createSforaShell, createLocalShell, } from "./index.js";
+import { openerCommand } from "./opener.js";
+import { blocksCommand, presenceNotice, putCommand, } from "./block-commands.js";
+import { colors, renderWriteEffect, urlLine, PRESENCE_NOTE } from "./render.js";
+import { parseWatchTarget, watchLoop } from "./watch.js";
 import { LocalWorkspace, initWorkspace, findWorkspace, migrateWorkspaceStages, } from "./local/workspace.js";
 import { runMcpServer } from "./mcp-server.js";
 import { readConfig, writeConfig, resolveSettings, upsertProfile, effectiveProfiles, DEFAULT_URL, } from "./config.js";
-const colors = {
-    reset: "\x1b[0m",
-    bold: "\x1b[1m",
-    dim: "\x1b[2m",
-    cyan: "\x1b[36m",
-    green: "\x1b[32m",
-    yellow: "\x1b[33m",
-    blue: "\x1b[34m",
-    red: "\x1b[31m",
-};
 function parseArgs(argv) {
-    const args = { rest: [], cwd: "/", mcp: false, help: false, draft: false, json: false, local: false, cloud: false };
+    const args = { rest: [], cwd: "/", mcp: false, help: false, draft: false, json: false, local: false, cloud: false, self: false };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === "--mcp")
@@ -79,6 +73,16 @@ function parseArgs(argv) {
             args.local = true;
         else if (a === "--cloud")
             args.cloud = true;
+        else if (a === "--block")
+            args.block = argv[++i];
+        else if (a.startsWith("--block="))
+            args.block = a.slice("--block=".length);
+        else if (a === "--self")
+            args.self = true;
+        else if (a === "--wait")
+            args.wait = Number.parseInt(argv[++i] ?? "", 10);
+        else if (a.startsWith("--wait="))
+            args.wait = Number.parseInt(a.slice("--wait=".length), 10);
         else if (!a.startsWith("-")) {
             if (!args.command)
                 args.command = a;
@@ -121,11 +125,23 @@ Browse & read:
   sfora me                            Show who you're signed in as
   sfora ls [path]                     List a path (default /projects)
   sfora cat <path>                    Print a file's markdown
+  sfora url <path>                    Print the web URL for a path
+  sfora open <path>                   Open that URL in your browser
   sfora                               Open the interactive shell
 
   Add --json to any list command (projects/posts/tasks/ls/me) for
   machine-readable output and stable scripting.
 
+Write, and watch others write:
+  sfora blocks <path>                 List a document's addressable blocks
+  sfora put <path> <file.md>          Write a file (add --block <id> for one block)
+  sfora put <path> --block <id> -     …or pipe the block's markdown on stdin
+  sfora watch <path-or-project>       Stream write pings (add --json for NDJSON)
+
+  Every write prints what it did — "changed" (with how many block ids
+  survived) or "no change". Watching and writing make you visible in the
+  document; watch --self also shows your own writes.
+
 Agents & config:
   sfora --mcp [--org <slug>]          Run as an MCP server (for agents)
   sfora mcp-config                    Print an MCP config snippet to paste
@@ -145,6 +161,11 @@ const SHELL_HELP = `${colors.bold}sfora shell${colors.reset} ${colors.dim}— yo
 Standard tools work against your workspace:
   ls   cat   grep   find   head   tail   wc   sed   awk   echo   cd   pwd
 
+${colors.dim}And three of sfora's own${colors.reset}
+  blocks <path>              the blocks a --block write can aim at
+  put <path> [file|-]        write a file (--block <id> writes one block)
+  url <path>                 where it lives on the web
+
 ${colors.dim}Where things live${colors.reset}
   /projects                          your projects
   /projects/<slug>/posts/<file>.md   published posts
@@ -160,6 +181,8 @@ ${colors.dim}Try${colors.reset}
   find /projects/<slug>/library -type f
   grep -ri todo /projects
   echo "# Hello" > /projects/<slug>/posts/hello.md
+  blocks /projects/<slug>/docs/spec.md
+  echo "A rewritten paragraph." | put /projects/<slug>/docs/spec.md --block <id>
 
 ${colors.dim}Outside the shell${colors.reset}, sfora has verbs: post · task · doc · new · projects   (run ${colors.cyan}sfora --help${colors.reset})
 Type ${colors.cyan}exit${colors.reset} to quit.
@@ -199,13 +222,9 @@ async function runInit(args) {
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function openBrowser(url) {
-    const cmd = process.platform === "darwin"
-        ? "open"
-        : process.platform === "win32"
-            ? "start"
-            : "xdg-open";
+    const { command, args } = openerCommand(process.platform, url);
     try {
-        spawn(cmd, [url], { stdio: "ignore", detached: true }).unref();
+        spawn(command, args, { stdio: "ignore", detached: true }).unref();
     }
     catch {
         /* best effort — the URL is printed for manual opening */
@@ -384,6 +403,11 @@ const VERBS = new Set([
     "new",
     "ls",
     "cat",
+    "url",
+    "open",
+    "blocks",
+    "put",
+    "watch",
     "post",
     "task",
     "doc",
@@ -398,8 +422,29 @@ const VERBS = new Set([
 ]);
 async function runVerb(args, fs, client) {
     const ok = (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`);
+    // The prose confirmation, suppressed under --json: a script parsing stdout
+    // must find JSON there and nothing else.
+    const said = (msg) => {
+        if (!args.json)
+            ok(msg);
+    };
     const emitJson = (v) => console.log(JSON.stringify(v, null, 2));
     const plural = (n, w) => `${n} ${w}${n === 1 ? "" : "s"}`;
+    /**
+     * The link the LAST request reported, as one dim line — on stderr.
+     *
+     * stderr and not stdout, deliberately: `sfora cat x.md > x.md` and
+     * `sfora ls | wc -l` are the reason those verbs exist, and a link mixed into
+     * stdout would corrupt the first and miscount the second. A human sees both
+     * streams; a pipe sees only the bytes it asked for. Suppressed under --json
+     * for the same reason.
+     */
+    const showUrl = () => {
+        const { url } = client.takeResponseInfo();
+        if (url && !args.json)
+            process.stderr.write(`${urlLine(url)}\n`);
+        return url;
+    };
     if (args.command === "projects") {
         const projects = await client.listProjects();
         if (args.json)
@@ -427,14 +472,62 @@ async function runVerb(args, fs, client) {
         if (args.json)
             return emitJson(entries);
         console.log(entries.join("\n"));
+        showUrl();
         return;
     }
     if (args.command === "cat") {
         if (!args.rest[0])
             throw new Error("usage: sfora cat <path>");
         process.stdout.write(await fs.readFile(args.rest[0], "utf8"));
+        showUrl();
+        return;
+    }
+    // `url` and `open` are the same question — where does this live on the web —
+    // asked once and answered by the server. The CLI holds no route table.
+    if (args.command === "url" || args.command === "open") {
+        const path = args.rest[0];
+        if (!path)
+            throw new Error(`usage: sfora ${args.command} <path>`);
+        const url = await client.resolveWebUrl(path);
+        if (!url) {
+            throw new Error(`${path} has no page on the web — files, repositories and the derived ` +
+                "views (README, mentions) are read through the fs only");
+        }
+        if (args.json)
+            return emitJson({ path, url });
+        console.log(url);
+        if (args.command === "open")
+            openBrowser(url);
         return;
     }
+    // `blocks` and `put` are the shell's own commands, run without the shell.
+    // One implementation (block-commands.ts) so the two doors cannot drift.
+    if (args.command === "blocks") {
+        if (!args.rest[0])
+            throw new Error("usage: sfora blocks <path> [--json]");
+        return writeCommandOutput(await blocksCommand(client, args.rest[0], { json: args.json }));
+    }
+    if (args.command === "put") {
+        const path = args.rest[0];
+        if (!path) {
+            throw new Error("usage: sfora put <path> [<file.md>|-] [--block <id>] [--json]");
+        }
+        const source = args.rest[1];
+        const body = source && source !== "-"
+            ? await readLocalFile(source, "utf8")
+            : await readStdin();
+        return writeCommandOutput(await putCommand(client, path, body, {
+            blockId: args.block,
+            json: args.json,
+            presence: runPresence,
+        }));
+    }
+    if (args.command === "watch") {
+        if (!args.rest[0]) {
+            throw new Error("usage: sfora watch <path-or-project> [--json] [--self] [--wait <secs>]");
+        }
+        return runWatch(args, client, args.rest[0]);
+    }
     if (args.command === "me" || args.command === "whoami") {
         const text = (await client.readMe()).trim();
         if (args.json) {
@@ -533,12 +626,14 @@ async function runVerb(args, fs, client) {
     if (args.command === "post") {
         const dir = args.draft ? "drafts" : "posts";
         await fs.writeFile(`/projects/${project}/${dir}/${name}`, md);
-        ok(`${args.draft ? "Drafted" : "Posted"} to ${project} · ${name}`);
+        said(`${args.draft ? "Drafted" : "Posted"} to ${project} · ${name}`);
+        reportWrite(client, args.json);
         return;
     }
     if (args.command === "doc") {
         await fs.writeFile(`/projects/${project}/library/documents/${name}`, md);
-        ok(`Doc saved to ${project} · ${name}`);
+        said(`Doc saved to ${project} · ${name}`);
+        reportWrite(client, args.json);
         return;
     }
     if (args.command === "task") {
@@ -557,10 +652,190 @@ async function runVerb(args, fs, client) {
             col = cols.find((c) => c.replace(/^\d+-/, "") === want) ?? col;
         }
         await fs.writeFile(`/projects/${project}/board/${col}/${name}`, md);
-        ok(`Task created in ${project} / ${col} · ${name}`);
+        said(`Task created in ${project} / ${col} · ${name}`);
+        reportWrite(client, args.json);
         return;
     }
 }
+/**
+ * What a write DID — printed after every one of them (card #333).
+ *
+ * Three lines at most, all on stderr and all dim, in the order a reader needs
+ * them: the effect (did the bytes move, and did the block ids survive), the
+ * page, and — once per process — the fact that writing put you on the
+ * document's roster. `announcedPresence` is module-level rather than per-call
+ * because "once" means once per run, not once per document.
+ */
+/**
+ * `sfora watch <target>` — the long-poll, wired to the real process.
+ *
+ * Everything decision-shaped lives in `watch.ts`; this resolves what is being
+ * watched, opens the roster, and arranges for ^C to close it. The two are
+ * separate so the loop can be tested without a signal handler or a socket.
+ */
+async function runWatch(args, client, target) {
+    const parsed = parseWatchTarget(target);
+    const wait = Number.isFinite(args.wait) ? args.wait : undefined;
+    // A document watch needs the entity id `/v1/events?doc=` takes, and the
+    // server states it in `?view=blocks` — the CLI does not read it out of the
+    // file. A project watch needs only the slug it was given.
+    let docId;
+    if (parsed.kind === "path") {
+        const resolved = await client.resolveDocId(parsed.path);
+        if (!resolved) {
+            throw new Error(`${parsed.path} has no document behind it to watch — point watch at a ` +
+                "post, draft, document or board card, or at a project");
+        }
+        docId = resolved;
+    }
+    // Presence, if this path has a roster. Asked rather than inferred: a `422`
+    // is the server saying "no roster here", and posts and cards get one.
+    let canBeat = parsed.kind === "path";
+    const beat = async ({ leave }) => {
+        if (!canBeat || parsed.kind !== "path")
+            return;
+        const roster = await client.declarePresence(parsed.path, {
+            kind: "viewing",
+            leave,
+        });
+        if (roster === null)
+            canBeat = false;
+    };
+    // Start at NOW, not at the retained backlog: `watch` is a live channel, and
+    // opening one should not replay a day of history nobody was waiting for.
+    const since = Date.now();
+    let stop = false;
+    // ^C HAS TO REACH THE SOCKET. Registering a handler suppresses Node's own
+    // SIGINT exit, so a handler that only sets a flag turns ^C into "stop after
+    // the current long-poll finishes" — up to `--wait` seconds of a terminal
+    // that says "^C to stop" and does not, with further ^Cs inert because the
+    // default handler is gone. The user's remaining exit is ^\, which kills the
+    // process outright, skips the `finally`, and leaves exactly the roster ghost
+    // the watch exists to avoid. Aborting the in-flight request is what makes
+    // the first ^C land: the poll rejects at once, the loop sees `stopped()`,
+    // and the `finally` retracts presence on the way out.
+    const inFlight = new AbortController();
+    let signalled = false;
+    const onSignal = (signal) => {
+        stop = true;
+        inFlight.abort();
+        // A second one is the impatient case — the leave request is hanging too,
+        // or the network is gone. Stand down and let the default behaviour end the
+        // process; the ghost expires on its own in ~90 seconds.
+        if (signalled) {
+            process.off("SIGINT", onSignal);
+            process.off("SIGTERM", onSignal);
+            process.kill(process.pid, signal);
+            return;
+        }
+        signalled = true;
+    };
+    process.on("SIGINT", onSignal);
+    process.on("SIGTERM", onSignal);
+    if (!args.json) {
+        process.stderr.write(`${colors.dim}watching ${parsed.kind === "project" ? `project ${parsed.slug}` : parsed.path}${args.self ? "" : " (not your own writes)"} — ^C to stop${colors.reset}\n`);
+    }
+    try {
+        await watchLoop({
+            poll: (cursor) => client.pollEvents({
+                since: cursor,
+                wait,
+                doc: docId,
+                project: parsed.kind === "project" ? parsed.slug : undefined,
+                includeSelf: args.self,
+                signal: inFlight.signal,
+            }),
+            beat: parsed.kind === "path" ? beat : undefined,
+            write: (text) => process.stdout.write(text),
+            // Warnings on stderr so `--json` stdout stays parseable NDJSON.
+            warn: (text) => process.stderr.write(`${colors.dim}${text}${colors.reset}\n`),
+            sleep,
+        }, { json: args.json, since, stopped: () => stop });
+    }
+    finally {
+        process.off("SIGINT", onSignal);
+        process.off("SIGTERM", onSignal);
+    }
+}
+/**
+ * A shared command's result, on the real streams.
+ *
+ * The exit code is honoured rather than thrown: a 409 re-aim table is a
+ * complete, useful answer that happens to mean "try again", and turning it back
+ * into an exception would put the CLI's generic `error:` prefix in front of a
+ * table that already explains itself.
+ */
+function writeCommandOutput(out) {
+    if (out.stdout)
+        process.stdout.write(out.stdout);
+    if (out.stderr)
+        process.stderr.write(out.stderr);
+    if (out.exitCode !== 0)
+        process.exitCode = out.exitCode;
+}
+/** Everything piped in, as text. Empty when nothing was. */
+async function readStdin() {
+    if (process.stdin.isTTY)
+        return "";
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+/**
+ * The trailing dim lines after a shell line: what a write did, and where it
+ * lives.
+ *
+ * Gated on the command, not on "did the last request name anything", and that
+ * is deliberate. A `grep -ri todo /projects` reads dozens of files, and the
+ * link of whichever happened to be read LAST would be a link to a document the
+ * user never asked about. So the rule is narrow and stated: a write always
+ * reports its effect (that is card #333's whole point — a splice can store
+ * nothing, and silence would read as success), and a link is offered only
+ * after the two commands whose subject is one path.
+ *
+ * `put`, `blocks` and `url` consume the info themselves, so nothing here
+ * double-prints them.
+ */
+function reportShellLine(line, client) {
+    const { url, effect, present } = client.takeResponseInfo();
+    const verb = line.trim().split(/\s+/)[0];
+    const effectLine = renderWriteEffect(effect);
+    if (effectLine)
+        process.stderr.write(`  ${effectLine}\n`);
+    if (url && (effect || verb === "cat" || verb === "ls")) {
+        process.stderr.write(`  ${urlLine(url)}\n`);
+    }
+    if (present && runPresence.claim()) {
+        process.stderr.write(`  ${colors.dim}${PRESENCE_NOTE}${colors.reset}\n`);
+    }
+}
+/**
+ * The run's one "you are visible" announcement.
+ *
+ * Module-level because a run IS this process, and shared with the shell's own
+ * `put` (it is handed to `createSforaShell`) because otherwise the interactive
+ * session has two latches — the shell command's and this one — and says the
+ * line twice for what is one fact.
+ */
+const runPresence = presenceNotice();
+function reportWrite(client, json) {
+    const { url, effect, present } = client.takeResponseInfo();
+    if (json) {
+        process.stdout.write(`${JSON.stringify({ url, present, ...(effect ?? {}) })}\n`);
+        return;
+    }
+    const line = renderWriteEffect(effect);
+    if (line)
+        process.stderr.write(`  ${line}\n`);
+    if (url)
+        process.stderr.write(`  ${urlLine(url)}\n`);
+    // Only a DOCUMENT write puts you on a roster, and the server is what says so.
+    if (present && runPresence.claim()) {
+        process.stderr.write(`  ${colors.dim}${PRESENCE_NOTE}${colors.reset}\n`);
+    }
+}
 // ─── Local mode (a .sfora/ directory — no server, no account) ─────
 const LOCAL_ONLY_HINT = "cloud command — run it with --cloud (after `sfora login`), or outside the .sfora/ repo";
 async function runLocalVerb(args, root) {
@@ -749,13 +1024,17 @@ async function main() {
     }
     // Structured verbs — the workspace as a markdown filesystem.
     if (args.command && VERBS.has(args.command)) {
-        const { fs } = createSforaShell({
+        // ONE client for the verb: `SforaFs` reads and writes through it, and the
+        // verbs read back off it what the last response reported (the page, the
+        // effect report). A second client would be watching a different
+        // conversation and would always answer "nothing".
+        const { fs, client } = createSforaShell({
             baseUrl,
             apiKey,
             org: settings.org ?? "",
             actAs: args.as,
+            presence: runPresence,
         });
-        const client = new SforaApiClient({ baseUrl, apiKey, actAs: args.as });
         try {
             await runVerb(args, fs, client);
         }
@@ -783,7 +1062,13 @@ async function main() {
         return;
     }
     const org = settings.org;
-    const { bash, fs } = createSforaShell({ baseUrl, apiKey, org, cwd: args.cwd });
+    const { bash, fs, client } = createSforaShell({
+        baseUrl,
+        apiKey,
+        org,
+        cwd: args.cwd,
+        presence: runPresence,
+    });
     // Pre-flight: confirm auth + connectivity and greet with the resolved identity.
     let identity = "";
     try {
@@ -804,9 +1089,11 @@ async function main() {
         console.log(`${colors.yellow}warning:${colors.reset} could not reach ${baseUrl} or authenticate — commands may fail.`);
     }
     console.log(`${colors.dim}Try: ls /projects · cat /inbox/mentions.md · ${colors.reset}${colors.cyan}help${colors.reset}${colors.dim} for commands · ${colors.reset}${colors.cyan}exit${colors.reset}${colors.dim} to quit${colors.reset}\n`);
-    await runShell(bash, fs, SHELL_HELP, args.cwd);
+    await runShell(bash, fs, SHELL_HELP, args.cwd, client);
 }
-async function runShell(bash, fs, helpText, initialCwd) {
+async function runShell(bash, fs, helpText, initialCwd, 
+/** Absent in local mode — there is no server, so nothing reports a link. */
+client) {
     // Shell state threaded across exec() calls — just-bash does not persist cwd/env
     // between separate exec()s, so we carry them forward ourselves.
     let cwd = initialCwd;
@@ -825,6 +1112,8 @@ async function runShell(bash, fs, helpText, initialCwd) {
         "ls", "cat", "cd", "pwd", "grep", "find", "echo", "head", "tail", "wc",
         "sed", "awk", "sort", "uniq", "mkdir", "rm", "mv", "cp", "touch", "help",
         "exit",
+        // sfora's own, registered on the cloud shell (see `sforaShellCommands`).
+        "blocks", "put", "url",
     ];
     async function completePath(token) {
         const slash = token.lastIndexOf("/");
@@ -888,6 +1177,8 @@ async function runShell(bash, fs, helpText, initialCwd) {
             // reads as native — the user never typed `bash`.
             if (res.stderr)
                 process.stderr.write(res.stderr.replace(/^bash:/gm, "sfora:"));
+            if (client)
+                reportShellLine(line, client);
             env = res.env;
             cwd = res.env?.PWD ?? cwd;
         }

package/dist/format/blockSplice.d.ts

@@ -0,0 +1,135 @@
+/**
+ * One block of a source string: its byte range, and its identity.
+ *
+ * `key` is what "unchanged" means. Two blocks with the same key are the same
+ * block for splice purposes and the old one's bytes win. A caller that keys by
+ * raw text gets a byte-exact diff (and no canonicalization softening at all);
+ * a caller that keys by a position-stripped parse gets the semantic diff this
+ * module exists to serve.
+ */
+export interface SourceBlock {
+    /** Byte offset of the block's first byte. */
+    start: number;
+    /** One past the block's last byte. */
+    end: number;
+    /** Identity under whatever equality the caller decided on. */
+    key: string;
+}
+/** Why a splice gave up and handed back the new source whole. */
+export type BlockSpliceFallback = "none"
+/** One side has no blocks at all — there is nothing to preserve or to keep. */
+ | "no-blocks"
+/** A block list was out of order, overlapping, or out of bounds. */
+ | "unusable-blocks";
+export interface BlockSpliceResult {
+    /** The bytes to store. */
+    source: string;
+    /** Old blocks that kept their bytes. */
+    kept: number;
+    /** Blocks written from the new source. */
+    rewritten: number;
+    /** Set when the result is just `newSource`. */
+    fallback: BlockSpliceFallback;
+}
+/**
+ * Above this many DP cells the middle region is treated as one changed run
+ * instead of being aligned properly.
+ *
+ * The prefix/suffix trim below already handles the shape a real edit has — one
+ * changed region, everything before and after it identical — in linear time,
+ * so the quadratic pass only ever runs on a genuinely scattered diff. 250k
+ * cells is a 500-block-by-500-block middle, which is a document nobody has;
+ * past it the splice degrades to exactly what open-knowledge's
+ * `map-driven-splice.ts` does at every size (one over-wide contiguous splice),
+ * which is correct, merely less preserving.
+ *
+ * Exported so the test that pins the boundary can build the block lists either
+ * side of it from this number rather than from a second copy of it: a budget
+ * quietly raised past a hard-coded 500×500 would leave a test that still
+ * passes while asserting nothing about the fallback.
+ */
+export declare const ALIGNMENT_CELL_BUDGET = 250000;
+/**
+ * A run of blocks that is either kept from old or written from new.
+ *
+ * `kept: true` means every block in the range keyed identically on both sides,
+ * one for one, so `oldTo - oldFrom === newTo - newFrom` and the i-th old block
+ * IS the i-th new block. `kept: false` means the two ranges are the region the
+ * alignment could not explain: they may be different lengths, and nothing here
+ * says which old block became which new one — that judgement belongs to the
+ * consumer, because the splice does not need it and a rebinding ledger does.
+ */
+export interface BlockRun {
+    kept: boolean;
+    /** Half-open index range into the old block list. */
+    oldFrom: number;
+    oldTo: number;
+    /** Half-open index range into the new block list. */
+    newFrom: number;
+    newTo: number;
+}
+/**
+ * How much of the correspondence was actually computed.
+ *
+ * `"exact"` is a real alignment: every block that survives unchanged is inside
+ * a kept run. `"budget"` says the middle region was past
+ * `ALIGNMENT_CELL_BUDGET` and was handed back as one changed run without being
+ * looked at, so blocks that did survive are sitting inside it unrecognised.
+ * The splice does not care — an over-wide changed run is merely less
+ * preserving — but a consumer that reads a changed run as "these blocks were
+ * edited" would be stating something the alignment never checked, so the
+ * degradation is reported rather than inferred from the run shapes.
+ */
+export type BlockAlignmentQuality = "exact" | "budget";
+/** The old↔new block correspondence, and how far it was actually worked out. */
+export interface BlockAlignment {
+    /**
+     * Alternating kept/changed runs covering both lists end to end: every index
+     * of `oldBlocks` appears in exactly one run's old range, every index of
+     * `newBlocks` in exactly one run's new range, both in ascending order.
+     */
+    runs: BlockRun[];
+    quality: BlockAlignmentQuality;
+}
+/**
+ * Assemble the bytes to store from `oldSource` and `newSource`.
+ *
+ * The contract, in order of how much it matters:
+ *
+ * 1. If every key matches, the result is `oldSource` byte-for-byte. Not
+ *    "equivalent to" — identical, including its trailing newline or lack of
+ *    one. A save that changed nothing must reach the store as no change at
+ *    all, or the whole exercise is decorative.
+ * 2. A block whose key changed contributes its NEW bytes, together with the
+ *    gap bytes on either side of it, because a new or deleted block has to be
+ *    able to bring its own blank lines.
+ * 3. A block whose key did not change contributes its OLD bytes, and so do
+ *    the gaps between two such blocks.
+ * 4. The bytes outside every block — leading whitespace, the trailing
+ *    newline — belong to no block, so they follow the block nearest them: old
+ *    if that first/last block was kept, new if it was rewritten. Kept-at-the-
+ *    edge is what makes rule 1 exact; rewritten-at-the-edge is what lets a
+ *    document that really was replaced arrive with its own final newline
+ *    instead of inheriting the absence of one.
+ */
+export declare function spliceBlocks(oldSource: string, newSource: string, oldBlocks: readonly SourceBlock[], newBlocks: readonly SourceBlock[]): BlockSpliceResult;
+/**
+ * Split both block lists into alternating kept/changed runs — the old↔new
+ * correspondence, on its own, with no bytes involved.
+ *
+ * Common prefix and suffix first — that is the entire diff for a normal edit
+ * and it costs one pass. What is left in the middle gets a longest-common-
+ * subsequence alignment so that two edits with untouched blocks between them
+ * keep those blocks' bytes; open-knowledge's version collapses that case into
+ * one over-wide splice, and it is the one thing here worth doing better than
+ * the reference, because "find and replace in three places" is an ordinary
+ * afternoon and it should not rewrite the paragraphs in between.
+ *
+ * Public because it is most of a rebinding ledger and it already runs on every
+ * write. `spliceBlocks` reads it for bytes; a caller that has derived an
+ * identity from the same keys reads it for what became what. Only `key` is
+ * consulted, so a caller holding keys and no offsets can ask this directly —
+ * the offset sanity `spliceBlocks` insists on is a slicing concern, not an
+ * alignment one.
+ */
+export declare function alignBlockRuns(oldBlocks: readonly SourceBlock[], newBlocks: readonly SourceBlock[]): BlockAlignment;