sfora-cli 0.10.0 → 0.12.0

package/dist/render.d.ts

@@ -0,0 +1,162 @@
+/**
+ * What the CLI prints — as pure functions, so it can be tested.
+ *
+ * Everything here takes data and returns a string. No I/O, no process, no
+ * colours decided by a TTY check: the caller writes the result. That is what
+ * lets `render.test.ts` assert on a 409 re-aim table or a blocks listing
+ * without a server, a terminal, or a snapshot of the whole command.
+ *
+ * The rule these follow, from the mission's binding: THE CLI PRINTS WHAT THE
+ * SERVER SENDS. Nothing here computes a URL, a route, or a block id — each
+ * comes off a response and is formatted.
+ */
+import type { BlockConflict, BlockView, BlocksView, PresenceView, WriteEffect } from "./api-client.js";
+export declare const colors: {
+    reset: string;
+    bold: string;
+    dim: string;
+    cyan: string;
+    green: string;
+    yellow: string;
+    blue: string;
+    red: string;
+};
+/**
+ * A link, as one quiet line.
+ *
+ * Dim and unadorned because it is an offer, not an instruction: the line a
+ * reader's eye skips until the moment they want it, and a terminal that
+ * hyperlinks URLs makes it clickable without any markup from us.
+ */
+export declare function urlLine(url: string): string;
+/** The first line of a block's text, collapsed and clipped for one row. */
+export declare function blockSummary(block: BlockView, width?: number): string;
+/**
+ * `sfora blocks <path>` — the addressable view, one row per block.
+ *
+ * The id comes FIRST because it is the only column anyone retypes: the next
+ * command is `sfora put <path> --block <id>`, and a listing that buries the id
+ * makes the reader hunt for it.
+ *
+ * `writable: false` is stated, not omitted, and it is stated as "read-only"
+ * rather than by leaving the row out. Those blocks are real — the frontmatter
+ * fence, the title heading — they occupy lines the reader can see in the file,
+ * and hiding them would make the listing disagree with `cat`.
+ */
+export declare function renderBlocks(view: BlocksView): string;
+/**
+ * The 409 a `?block=` write gets: the id named nothing, here is what the
+ * document has now.
+ *
+ * A table and not a message, because the recovery IS the payload: the server
+ * already sent the current blocks, so the fix is one glance and one retry
+ * rather than a second `sfora blocks` round trip. The retry line is spelled
+ * out with the real path for the same reason.
+ *
+ * THE COLUMNS ARE THE PAYLOAD'S — id, line, preview — and not `sfora blocks`'s.
+ * The two lists describe different bytes (see {@link BlockSummary}): every id
+ * here already resolves at the write door, so there is no writable/read-only
+ * distinction to draw and no node type in the payload to draw one with. An
+ * earlier version of this function reached for both anyway and printed
+ * `undefined  read-only` on every row, which inverted the one fact the table
+ * exists to convey. `line` earns the column it took: it is where in the file
+ * the caller is holding to look, and it is the field that tells two blocks with
+ * the same opening words apart.
+ */
+export declare function renderBlockConflict(conflict: BlockConflict, fsPath: string): string;
+/**
+ * The effect report, as one line — printed after EVERY write.
+ *
+ * A bare "saved" is a lie the CLI used to tell: sfora's write door splices, so
+ * a PUT of bytes that parse the same as the stored ones stores nothing and
+ * `changed: false` is a normal answer. Saying so is the difference between an
+ * agent that knows its edit landed and one that assumes it did.
+ *
+ * The rebind counts describe the blocks the document had BEFORE this write:
+ * `total` of them, of which `rebound` are the same block under a new id and
+ * `orphaned` are blocks nothing in the new document can be shown to be. The
+ * rest kept the id they had, which is the number worth leading with — it is
+ * what tells a reader whether their block addresses still work.
+ */
+export declare function renderWriteEffect(effect: WriteEffect | null): string | null;
+/**
+ * The one-time "you are visible" note.
+ *
+ * Writing DECLARES PRESENCE server-side — the document's roster shows the
+ * writer, and a human with it open sees them. That is a fact about the user's
+ * visibility to other people, so it is said out loud rather than left to be
+ * discovered in the UI; once per run, because said on every write it would be
+ * noise and the second one teaches nothing.
+ */
+export declare const PRESENCE_NOTE = "you are visible as editing this document";
+/**
+ * `sfora where` — one sentence per person, and a link they can be met at.
+ *
+ * A SENTENCE, not a table. The answer to "where is Thijs" is read once and
+ * acted on immediately ("open that document"), so it is written the way it
+ * would be said: *Thijs is editing test-document.md — <url>*. A columnar
+ * listing would be denser and would make the reader assemble the sentence
+ * themselves.
+ *
+ * The block id rides in parentheses only when somebody claimed one. Humans
+ * are present at document level today (the editor has no cheap source-offset
+ * mapping), so an always-present column would be empty on most rows and read
+ * as a fault rather than as an absence of claim.
+ *
+ * Grouped runs, no headers: two people in one document print as two adjacent
+ * lines naming the same file. The repetition is the grouping, and it costs
+ * nothing to scan — where a header would cost a line per document and break
+ * `sfora where | grep` into a two-line lookup.
+ */
+export declare function renderPresence(view: PresenceView): string;
+/**
+ * `sfora where --json` — one flat record per person-in-a-document, per line.
+ *
+ * FLAT, where the wire shape is grouped. NDJSON's contract is that a line is a
+ * record, and the record a consumer of this wants is "who is where": grouping
+ * would make a line's shape depend on how many people happened to be in one
+ * file, and `jq -r .url` would stop working. The document's fields are copied
+ * onto each line rather than referenced, so no line needs another to be read.
+ */
+export declare function presenceRecords(view: PresenceView): unknown[];
+/** One `doc.write` / `doc.delete` ping from `/v1/events`, as one line. */
+export interface DocPing {
+    type: "doc.write" | "doc.delete";
+    ts: number;
+    docType?: string;
+    docId?: string;
+    title?: string;
+    path?: string;
+    url?: string;
+    author?: string;
+    authorType?: "human" | "agent";
+    changed?: boolean;
+    deleted?: boolean;
+    restricted?: boolean;
+    blockIds?: {
+        rebound: number;
+        orphaned: number;
+        total: number;
+    };
+}
+/** `HH:MM:SS` in the reader's own timezone — a ping is read as it lands. */
+export declare function pingTime(ts: number): string;
+/**
+ * `time · author · doc · what changed · url` — one ping, one line.
+ *
+ * A RESTRICTED ping keeps its shape and loses its pointer: the server
+ * delivered the fact (a document you are watching moved, by whom) and withheld
+ * the title and the link because they belong to somebody's draft. Printing
+ * "(restricted)" rather than dropping the line is the honest half — a watch
+ * that went silent would look broken.
+ */
+export declare function renderPing(ping: DocPing): string;
+/**
+ * The NDJSON line for one ping — the machine half of `sfora watch --json`.
+ *
+ * The SERVER'S event object, verbatim, plus nothing. A CLI that reshaped it
+ * would become a second schema to keep in step with `/v1/events`, and the one
+ * consumer that matters here (an agent piping this into a program) is better
+ * served by the wire shape it can also get from the HTTP door directly.
+ */
+export declare function ndjson(event: unknown): string;

package/dist/render.js

@@ -0,0 +1,280 @@
+/**
+ * What the CLI prints — as pure functions, so it can be tested.
+ *
+ * Everything here takes data and returns a string. No I/O, no process, no
+ * colours decided by a TTY check: the caller writes the result. That is what
+ * lets `render.test.ts` assert on a 409 re-aim table or a blocks listing
+ * without a server, a terminal, or a snapshot of the whole command.
+ *
+ * The rule these follow, from the mission's binding: THE CLI PRINTS WHAT THE
+ * SERVER SENDS. Nothing here computes a URL, a route, or a block id — each
+ * comes off a response and is formatted.
+ */
+export 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",
+};
+const dim = (text) => `${colors.dim}${text}${colors.reset}`;
+/**
+ * A link, as one quiet line.
+ *
+ * Dim and unadorned because it is an offer, not an instruction: the line a
+ * reader's eye skips until the moment they want it, and a terminal that
+ * hyperlinks URLs makes it clickable without any markup from us.
+ */
+export function urlLine(url) {
+    return dim(url);
+}
+/** One line of text, collapsed and clipped to a column. */
+function oneLine(text, width) {
+    const firstLine = text.split("\n").find((l) => l.trim()) ?? "";
+    const flat = firstLine.replace(/\s+/g, " ").trim();
+    return flat.length > width ? `${flat.slice(0, width - 1)}…` : flat;
+}
+/** The first line of a block's text, collapsed and clipped for one row. */
+export function blockSummary(block, width = 56) {
+    return oneLine(block.text ?? "", width);
+}
+function pad(text, width) {
+    return text.length >= width ? text : text + " ".repeat(width - text.length);
+}
+/**
+ * `sfora blocks <path>` — the addressable view, one row per block.
+ *
+ * The id comes FIRST because it is the only column anyone retypes: the next
+ * command is `sfora put <path> --block <id>`, and a listing that buries the id
+ * makes the reader hunt for it.
+ *
+ * `writable: false` is stated, not omitted, and it is stated as "read-only"
+ * rather than by leaving the row out. Those blocks are real — the frontmatter
+ * fence, the title heading — they occupy lines the reader can see in the file,
+ * and hiding them would make the listing disagree with `cat`.
+ */
+export function renderBlocks(view) {
+    const lines = [];
+    if (view.unaddressable) {
+        return [
+            `${colors.yellow}no addressable blocks${colors.reset}`,
+            dim(view.unaddressable),
+            ...(view.url ? [urlLine(view.url)] : []),
+        ].join("\n");
+    }
+    if (view.blocks.length === 0) {
+        lines.push(dim("(no blocks)"));
+    }
+    else {
+        const idWidth = Math.max(...view.blocks.map((b) => b.id.length));
+        const typeWidth = Math.max(...view.blocks.map((b) => b.type.length));
+        for (const block of view.blocks) {
+            const row = `${pad(block.id, idWidth)}  ${dim(pad(block.type, typeWidth))}  ${blockSummary(block)}`;
+            lines.push(block.writable ? row : `${dim(row)}  ${dim("read-only")}`);
+        }
+        const writable = view.blocks.filter((b) => b.writable).length;
+        lines.push(dim(`${view.blocks.length} block${view.blocks.length === 1 ? "" : "s"} · ${writable} writable`));
+    }
+    if (view.url)
+        lines.push(urlLine(view.url));
+    return lines.join("\n");
+}
+/**
+ * The 409 a `?block=` write gets: the id named nothing, here is what the
+ * document has now.
+ *
+ * A table and not a message, because the recovery IS the payload: the server
+ * already sent the current blocks, so the fix is one glance and one retry
+ * rather than a second `sfora blocks` round trip. The retry line is spelled
+ * out with the real path for the same reason.
+ *
+ * THE COLUMNS ARE THE PAYLOAD'S — id, line, preview — and not `sfora blocks`'s.
+ * The two lists describe different bytes (see {@link BlockSummary}): every id
+ * here already resolves at the write door, so there is no writable/read-only
+ * distinction to draw and no node type in the payload to draw one with. An
+ * earlier version of this function reached for both anyway and printed
+ * `undefined  read-only` on every row, which inverted the one fact the table
+ * exists to convey. `line` earns the column it took: it is where in the file
+ * the caller is holding to look, and it is the field that tells two blocks with
+ * the same opening words apart.
+ */
+export function renderBlockConflict(conflict, fsPath) {
+    const lines = [
+        `${colors.yellow}that block is gone${colors.reset} ${dim("— somebody changed it since you read it")}`,
+        dim(conflict.message),
+        "",
+    ];
+    if (conflict.blocks.length === 0) {
+        lines.push(dim("(the document has no addressable blocks now)"));
+    }
+    else {
+        lines.push(dim("the document has these blocks now:"));
+        const idWidth = Math.max(...conflict.blocks.map((b) => b.id.length));
+        const lineWidth = Math.max(...conflict.blocks.map((b) => `${b.line}`.length));
+        for (const block of conflict.blocks) {
+            const at = `${" ".repeat(lineWidth - `${block.line}`.length)}${block.line}`;
+            lines.push(`  ${pad(block.id, idWidth)}  ${dim(`line ${at}`)}  ${oneLine(block.preview, 48)}`);
+        }
+        lines.push("", dim(`re-aim with: sfora put ${fsPath} --block <id>`));
+    }
+    return lines.join("\n");
+}
+/**
+ * The effect report, as one line — printed after EVERY write.
+ *
+ * A bare "saved" is a lie the CLI used to tell: sfora's write door splices, so
+ * a PUT of bytes that parse the same as the stored ones stores nothing and
+ * `changed: false` is a normal answer. Saying so is the difference between an
+ * agent that knows its edit landed and one that assumes it did.
+ *
+ * The rebind counts describe the blocks the document had BEFORE this write:
+ * `total` of them, of which `rebound` are the same block under a new id and
+ * `orphaned` are blocks nothing in the new document can be shown to be. The
+ * rest kept the id they had, which is the number worth leading with — it is
+ * what tells a reader whether their block addresses still work.
+ */
+export function renderWriteEffect(effect) {
+    if (!effect)
+        return null;
+    if (!effect.changed) {
+        return dim("no change — the stored bytes already matched");
+    }
+    const counts = effect.blockIds;
+    if (!counts || counts.total === 0)
+        return dim("changed");
+    const kept = counts.total - counts.rebound - counts.orphaned;
+    const parts = [`${kept} of ${counts.total} block ids kept`];
+    if (counts.rebound)
+        parts.push(`${counts.rebound} moved`);
+    if (counts.orphaned)
+        parts.push(`${counts.orphaned} orphaned`);
+    return dim(`changed · ${parts.join(" · ")}`);
+}
+/**
+ * The one-time "you are visible" note.
+ *
+ * Writing DECLARES PRESENCE server-side — the document's roster shows the
+ * writer, and a human with it open sees them. That is a fact about the user's
+ * visibility to other people, so it is said out loud rather than left to be
+ * discovered in the UI; once per run, because said on every write it would be
+ * noise and the second one teaches nothing.
+ */
+export const PRESENCE_NOTE = "you are visible as editing this document";
+/**
+ * `sfora where` — one sentence per person, and a link they can be met at.
+ *
+ * A SENTENCE, not a table. The answer to "where is Thijs" is read once and
+ * acted on immediately ("open that document"), so it is written the way it
+ * would be said: *Thijs is editing test-document.md — <url>*. A columnar
+ * listing would be denser and would make the reader assemble the sentence
+ * themselves.
+ *
+ * The block id rides in parentheses only when somebody claimed one. Humans
+ * are present at document level today (the editor has no cheap source-offset
+ * mapping), so an always-present column would be empty on most rows and read
+ * as a fault rather than as an absence of claim.
+ *
+ * Grouped runs, no headers: two people in one document print as two adjacent
+ * lines naming the same file. The repetition is the grouping, and it costs
+ * nothing to scan — where a header would cost a line per document and break
+ * `sfora where | grep` into a two-line lookup.
+ */
+export function renderPresence(view) {
+    const lines = [];
+    const totalHere = view.documents.reduce((n, d) => n + d.here.length, 0);
+    if (totalHere === 0) {
+        return dim(view.member
+            ? `${view.member.name} isn't in a document right now`
+            : "nobody is in a document right now");
+    }
+    for (const doc of view.documents) {
+        for (const who of doc.here) {
+            lines.push(presenceLine(doc, who));
+        }
+    }
+    return lines.join("\n");
+}
+function presenceLine(doc, who) {
+    const where = who.block
+        ? `${doc.filename} ${dim(`(block ${who.block})`)}`
+        : doc.filename;
+    return `${who.name} is ${who.kind} ${where} ${dim("—")} ${urlLine(doc.url)}`;
+}
+/**
+ * `sfora where --json` — one flat record per person-in-a-document, per line.
+ *
+ * FLAT, where the wire shape is grouped. NDJSON's contract is that a line is a
+ * record, and the record a consumer of this wants is "who is where": grouping
+ * would make a line's shape depend on how many people happened to be in one
+ * file, and `jq -r .url` would stop working. The document's fields are copied
+ * onto each line rather than referenced, so no line needs another to be read.
+ */
+export function presenceRecords(view) {
+    const records = [];
+    for (const doc of view.documents) {
+        for (const who of doc.here) {
+            records.push({
+                memberId: who.memberId,
+                name: who.name,
+                type: who.type,
+                kind: who.kind,
+                block: who.block,
+                lastSeenAt: who.lastSeenAt,
+                ttlSeconds: view.ttlSeconds,
+                docId: doc.docId,
+                title: doc.title,
+                filename: doc.filename,
+                path: doc.path,
+                project: doc.project.slug,
+                url: doc.url,
+            });
+        }
+    }
+    return records;
+}
+/** `HH:MM:SS` in the reader's own timezone — a ping is read as it lands. */
+export function pingTime(ts) {
+    return new Date(ts).toTimeString().slice(0, 8);
+}
+/**
+ * `time · author · doc · what changed · url` — one ping, one line.
+ *
+ * A RESTRICTED ping keeps its shape and loses its pointer: the server
+ * delivered the fact (a document you are watching moved, by whom) and withheld
+ * the title and the link because they belong to somebody's draft. Printing
+ * "(restricted)" rather than dropping the line is the honest half — a watch
+ * that went silent would look broken.
+ */
+export function renderPing(ping) {
+    const who = ping.author ?? "someone";
+    const what = ping.restricted
+        ? dim("(a document you can't open)")
+        : (ping.title ?? ping.path ?? ping.docId ?? "a document");
+    const parts = [dim(pingTime(ping.ts)), who, what];
+    if (ping.type === "doc.delete") {
+        parts.push(`${colors.yellow}deleted${colors.reset}`);
+    }
+    else {
+        const counts = ping.blockIds;
+        parts.push(dim(counts && counts.total
+            ? `${counts.total - counts.rebound - counts.orphaned} of ${counts.total} block ids kept`
+            : "edited"));
+    }
+    if (ping.url)
+        parts.push(urlLine(ping.url));
+    return parts.join(dim(" · "));
+}
+/**
+ * The NDJSON line for one ping — the machine half of `sfora watch --json`.
+ *
+ * The SERVER'S event object, verbatim, plus nothing. A CLI that reshaped it
+ * would become a second schema to keep in step with `/v1/events`, and the one
+ * consumer that matters here (an agent piping this into a program) is better
+ * served by the wire shape it can also get from the HTTP door directly.
+ */
+export function ndjson(event) {
+    return JSON.stringify(event);
+}

package/dist/shell-commands.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The sfora-native commands inside the shell: `blocks`, `put`, `url`.
+ *
+ * Card #333's "and the fs shell equivalent". The shell already writes whole
+ * files (`echo '# Title' > /projects/x/docs/y.md` is a PUT), but it had no way
+ * to aim at ONE block, and no way to see what a write did. These three close
+ * that gap without teaching the shell anything new about routes: they are the
+ * same functions the CLI verbs call.
+ *
+ * `put` reads its body from a file argument or from STDIN, which is what makes
+ * it shell-shaped — `sed 's/foo/bar/' <(…) | put /projects/x/docs/y.md --block
+ * k7f3a2cx` is the loop this exists for.
+ */
+import type { Command } from "just-bash";
+import type { SforaApiClient } from "./api-client.js";
+import { type PresenceNotice } from "./block-commands.js";
+/** Flags these commands understand, split from the positional arguments. */
+interface ParsedArgs {
+    positional: string[];
+    blockId?: string;
+    json: boolean;
+}
+export declare function parseShellArgs(args: string[]): ParsedArgs;
+/**
+ * The three commands, bound to the client the shell's fs already uses.
+ *
+ * `presence` is the RUN's latch, not the shell's: an interactive session
+ * prints the presence note from two places (a `put` command, and the trailing
+ * report after any line that wrote), and both must count as the same "once".
+ * A caller that passes none gets a fresh one, so a standalone shell still says
+ * it exactly once.
+ */
+export declare function sforaShellCommands(client: SforaApiClient, presence?: PresenceNotice): Command[];
+export {};

package/dist/shell-commands.js

@@ -0,0 +1,108 @@
+/**
+ * The sfora-native commands inside the shell: `blocks`, `put`, `url`.
+ *
+ * Card #333's "and the fs shell equivalent". The shell already writes whole
+ * files (`echo '# Title' > /projects/x/docs/y.md` is a PUT), but it had no way
+ * to aim at ONE block, and no way to see what a write did. These three close
+ * that gap without teaching the shell anything new about routes: they are the
+ * same functions the CLI verbs call.
+ *
+ * `put` reads its body from a file argument or from STDIN, which is what makes
+ * it shell-shaped — `sed 's/foo/bar/' <(…) | put /projects/x/docs/y.md --block
+ * k7f3a2cx` is the loop this exists for.
+ */
+import { decodeBytesToUtf8 } from "just-bash";
+import { blocksCommand, presenceNotice, putCommand, resolveFsPath, urlCommand, } from "./block-commands.js";
+export function parseShellArgs(args) {
+    const parsed = { positional: [], json: false };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (a === "--json")
+            parsed.json = true;
+        else if (a === "--block")
+            parsed.blockId = args[++i];
+        else if (a.startsWith("--block=")) {
+            parsed.blockId = a.slice("--block=".length);
+        }
+        else
+            parsed.positional.push(a);
+    }
+    return parsed;
+}
+const toExec = (out) => ({
+    stdout: out.stdout,
+    stderr: out.stderr,
+    exitCode: out.exitCode,
+});
+const usage = (text) => ({
+    stdout: "",
+    stderr: `${text}\n`,
+    exitCode: 2,
+});
+/**
+ * The body of a `put`: a file argument read through the shell's own fs, or
+ * whatever arrived on stdin.
+ *
+ * `-` is spelled out as "stdin" because a pipeline that produced nothing and a
+ * caller that forgot the body are the same empty string, and the write door
+ * refuses an empty `--block` body with a message about truncated pipes. Being
+ * explicit at the call site is how the shell keeps that refusal meaningful.
+ */
+async function putBody(ctx, fileArg, stdin) {
+    if (fileArg && fileArg !== "-") {
+        const path = resolveFsPath(ctx.cwd, fileArg);
+        const content = await ctx.fs.readFile(path, "utf8");
+        return typeof content === "string"
+            ? content
+            : new TextDecoder().decode(content);
+    }
+    return stdin;
+}
+/**
+ * The three commands, bound to the client the shell's fs already uses.
+ *
+ * `presence` is the RUN's latch, not the shell's: an interactive session
+ * prints the presence note from two places (a `put` command, and the trailing
+ * report after any line that wrote), and both must count as the same "once".
+ * A caller that passes none gets a fresh one, so a standalone shell still says
+ * it exactly once.
+ */
+export function sforaShellCommands(client, presence = presenceNotice()) {
+    return [
+        {
+            name: "blocks",
+            async execute(args, ctx) {
+                const { positional, json } = parseShellArgs(args);
+                if (!positional[0])
+                    return usage("usage: blocks <path> [--json]");
+                return toExec(await blocksCommand(client, resolveFsPath(ctx.cwd, positional[0]), {
+                    json,
+                }));
+            },
+        },
+        {
+            name: "put",
+            async execute(args, ctx) {
+                const { positional, blockId, json } = parseShellArgs(args);
+                if (!positional[0]) {
+                    return usage("usage: put <path> [<file>|-] [--block <id>] [--json]  (body from stdin when no file)");
+                }
+                // `ctx.stdin` is just-bash's opaque byte string, not a buffer: the
+                // engine's own decoder is the only correct way to read it as text.
+                const body = await putBody(ctx, positional[1], decodeBytesToUtf8(ctx.stdin));
+                return toExec(await putCommand(client, resolveFsPath(ctx.cwd, positional[0]), body, { blockId, json, presence }));
+            },
+        },
+        {
+            name: "url",
+            async execute(args, ctx) {
+                const { positional, json } = parseShellArgs(args);
+                if (!positional[0])
+                    return usage("usage: url <path> [--json]");
+                return toExec(await urlCommand(client, resolveFsPath(ctx.cwd, positional[0]), {
+                    json,
+                }));
+            },
+        },
+    ];
+}

package/dist/watch.d.ts

@@ -0,0 +1,79 @@
+/**
+ * `sfora watch` — a document as a channel.
+ *
+ * Card #332. `/v1/events` has been the agent wake-up transport since 2026-07;
+ * card #328 taught it `doc.write`, and this is the consumer that makes a write
+ * into a ping somebody actually sees. Point it at a document and every edit
+ * anybody makes to it arrives as a line; point it at a project and every
+ * document in the project does.
+ *
+ * FOUR THINGS THIS OWNS, and each is here rather than in `cli.ts` because each
+ * is a rule with a reason:
+ *
+ *  1. **The cursor survives reconnects.** A dropped connection is normal on a
+ *     long-poll; losing the cursor with it would replay pings already printed,
+ *     or (worse, with `since=0`) dump a day of backlog. It is a variable in
+ *     this loop and it only ever moves forward.
+ *  2. **Backoff on drops, reset on success.** A server that is down must not be
+ *     hammered by a watcher that reconnects instantly, and a watcher that
+ *     backed off must not stay slow once the server is back.
+ *  3. **Presence while watching.** Reading a document IS being in it, so the
+ *     watch declares `viewing` and re-declares on each poll — the roster row
+ *     expires ~90s after the last beat and the poll cadence is well inside
+ *     that. Paths with no roster (a post, a card, a project) simply get no
+ *     declaration; the server says which those are, not the CLI.
+ *  4. **Leaving on exit.** A watch that ended and left a row behind would show
+ *     a ghost in somebody's avatar stack for a minute and a half.
+ *
+ * The loop takes its I/O as arguments so a test can drive it with canned pages
+ * and a fake clock. Nothing here touches `process`.
+ */
+import type { AgentEventsPage } from "./api-client.js";
+/** Everything the loop needs from the outside world. */
+export interface WatchDeps {
+    /** One long-poll. Rejects on a dropped connection — the loop backs off. */
+    poll(since: number): Promise<AgentEventsPage>;
+    /** Say "viewing" (or retract). Absent when the target has no roster. */
+    beat?(options: {
+        leave?: boolean;
+    }): Promise<void>;
+    /** Where a printed line goes. */
+    write(text: string): void;
+    /** Where a warning goes — never mixed into `--json` output. */
+    warn(text: string): void;
+    sleep(ms: number): Promise<void>;
+}
+export interface WatchOptions {
+    /** NDJSON instead of prose: one event object per line, the server's shape. */
+    json?: boolean;
+    /** Where to start. 0 replays the retained backlog; the CLI starts at "now". */
+    since?: number;
+    /** Stop when this returns true — a signal, or a counter in a test. */
+    stopped?: () => boolean;
+    /** First backoff step, doubling to {@link MAX_BACKOFF_MS}. */
+    backoffMs?: number;
+}
+/** A watcher that has been unreachable this long is not polling any faster. */
+export declare const MAX_BACKOFF_MS = 30000;
+/**
+ * Poll until stopped, printing what arrives.
+ *
+ * Returns the cursor it reached, which is what makes the loop testable: a test
+ * asserts that a reconnect resumed from it rather than from zero.
+ */
+export declare function watchLoop(deps: WatchDeps, options?: WatchOptions): Promise<number>;
+/**
+ * What `sfora watch <target>` is watching: one document, or a project.
+ *
+ * A path names a document (`/projects/acme/docs/x.md`); a bare word names a
+ * project, and so does the project's own directory, since `/projects/acme` is
+ * how the fs spells it.
+ */
+export type WatchTarget = {
+    kind: "project";
+    slug: string;
+} | {
+    kind: "path";
+    path: string;
+};
+export declare function parseWatchTarget(target: string): WatchTarget;