sfora-cli 0.9.0 → 0.11.0

package/dist/block-commands.js

@@ -0,0 +1,155 @@
+/**
+ * `blocks`, `put` and `url` — one implementation, two front doors.
+ *
+ * Card #333. These three run identically as CLI verbs (`sfora put …`) and as
+ * commands inside the interactive shell (`put …`), and they do it by being
+ * written once here: each takes its arguments and returns
+ * `{ stdout, stderr, exitCode }`, which is exactly what just-bash's `Command`
+ * interface wants and exactly what the CLI writes to its own streams.
+ *
+ * WHY STREAMS AND AN EXIT CODE RATHER THAN PRINTING. A shell command that
+ * printed to `process.stdout` would escape the pipeline — `blocks x.md | grep
+ * heading` would print everything and pipe nothing. Returning the text makes
+ * both callers correct and makes the tests below assert on a value instead of
+ * spying on the process.
+ *
+ * The split against `render.ts` is the usual one: this module talks to the
+ * server and decides what to say; `render.ts` decides how it looks.
+ */
+import { blockConflictFrom, SforaApiError, } from "./api-client.js";
+import { colors, renderBlockConflict, renderBlocks, renderWriteEffect, urlLine, PRESENCE_NOTE, } from "./render.js";
+const ok = (stdout, stderr = "") => ({
+    stdout,
+    stderr,
+    exitCode: 0,
+});
+const fail = (stderr) => ({
+    stdout: "",
+    stderr: stderr.endsWith("\n") ? stderr : `${stderr}\n`,
+    exitCode: 1,
+});
+export function presenceNotice() {
+    let said = false;
+    return {
+        claim() {
+            if (said)
+                return false;
+            said = true;
+            return true;
+        },
+    };
+}
+/** An absolute fs path from a possibly-relative one plus the shell's cwd. */
+export function resolveFsPath(cwd, path) {
+    if (path.startsWith("/"))
+        return path;
+    const parts = `${cwd}/${path}`.split("/");
+    const out = [];
+    for (const part of parts) {
+        if (!part || part === ".")
+            continue;
+        if (part === "..")
+            out.pop();
+        else
+            out.push(part);
+    }
+    return `/${out.join("/")}`;
+}
+/** Turn an API failure into the message a person should read. */
+function apiMessage(error) {
+    if (error instanceof SforaApiError) {
+        return error.status === 0
+            ? `could not reach the server — ${error.message}`
+            : error.message;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * `blocks <path>` — what a `?block=` write can aim at.
+ *
+ * This is the read that makes single-block writing usable: the ids are
+ * fingerprints over the document's bytes, so they are stable until somebody
+ * changes that block, and `writable` says which of them the write door will
+ * actually accept (a frontmatter fence and a title heading are served but not
+ * stored, so their ids address nothing).
+ */
+export async function blocksCommand(client, fsPath, options = {}) {
+    try {
+        const view = await client.readBlocks(fsPath);
+        // The view already carries `url` and `renderBlocks` prints it, so consume
+        // the recorded info here: an unconsumed link would be printed a second
+        // time by whatever ran this command.
+        client.takeResponseInfo();
+        return ok(options.json
+            ? `${JSON.stringify(view, null, 2)}\n`
+            : `${renderBlocks(view)}\n`);
+    }
+    catch (error) {
+        return fail(`${colors.red}error:${colors.reset} ${apiMessage(error)}`);
+    }
+}
+/**
+ * `put <path>` — write a file, or with `--block <id>` exactly one block of it.
+ *
+ * Always reports the EFFECT, never a bare "saved". sfora's write door splices:
+ * a PUT of bytes that parse the same as the stored ones stores nothing, and
+ * `changed: false` is the honest and frequent answer to a `GET`-edit-`PUT`
+ * loop that reformatted more than it meant to.
+ *
+ * A 409 is the interesting failure and it is not really a failure: block ids
+ * are content-derived, so "this id resolves to nothing" means somebody changed
+ * that block since you read it. The server sends the document's current blocks
+ * with the refusal, so the recovery is printed as a table to re-aim from,
+ * rather than as an error to go re-investigate.
+ */
+export async function putCommand(client, fsPath, body, options = {}) {
+    try {
+        const result = await client.writePath(fsPath, body, {
+            blockId: options.blockId,
+        });
+        const info = client.takeResponseInfo();
+        if (options.json)
+            return ok(`${JSON.stringify(result, null, 2)}\n`);
+        // The confirmation is a REPORT, not data — so stderr, which keeps
+        // `put … | something` from feeding a downstream command an ANSI receipt,
+        // and keeps `put --json` the only thing that ever reaches stdout.
+        const lines = [
+            `${colors.green}✓${colors.reset} ${options.blockId
+                ? `Wrote block ${options.blockId} of ${result.path ?? fsPath}`
+                : `Wrote ${result.path ?? fsPath}`}`,
+        ];
+        const effect = renderWriteEffect(info.effect);
+        if (effect)
+            lines.push(`  ${effect}`);
+        if (info.url)
+            lines.push(`  ${urlLine(info.url)}`);
+        // Presence is a fact about being SEEN, so it is said once and only when the
+        // server reports it — document writes declare it, posts and cards do not.
+        // `claim()` is behind the `present` check so a write that reported no
+        // roster cannot spend the run's one announcement on nothing.
+        if (info.present && (options.presence?.claim() ?? true)) {
+            lines.push(`  ${colors.dim}${PRESENCE_NOTE}${colors.reset}`);
+        }
+        return ok("", `${lines.join("\n")}\n`);
+    }
+    catch (error) {
+        const conflict = blockConflictFrom(error);
+        if (conflict)
+            return fail(renderBlockConflict(conflict, fsPath));
+        return fail(`${colors.red}error:${colors.reset} ${apiMessage(error)}`);
+    }
+}
+/** `url <path>` — the page, printed. See `web-url.ts` for who knows the route. */
+export async function urlCommand(client, fsPath, options = {}) {
+    try {
+        const url = await client.resolveWebUrl(fsPath);
+        client.takeResponseInfo(); // printed below; do not leave it for a caller
+        if (!url) {
+            return fail(`${colors.red}error:${colors.reset} ${fsPath} has no page on the web`);
+        }
+        return ok(options.json ? `${JSON.stringify({ path: fsPath, url })}\n` : `${url}\n`);
+    }
+    catch (error) {
+        return fail(`${colors.red}error:${colors.reset} ${apiMessage(error)}`);
+    }
+}

package/dist/cli.js

@@ -10,22 +10,17 @@ import * as readline from "node:readline";
 import { spawn } from "node:child_process";
 import { readFile as readLocalFile } from "node:fs/promises";
 import { basename } from "node:path";
-import { createSforaShell, createLocalShell, SforaApiClient } from "./index.js";
+import { taskUploadFilename } from "./format/taskUploadFilename.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")
@@ -78,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;
@@ -120,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
@@ -144,20 +161,28 @@ 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
   /projects/<slug>/drafts/           drafts
   /projects/<slug>/board/<col>/      board tasks
-  /projects/<slug>/docs/             docs
+  /projects/<slug>/library/          documents, files, and repositories
   /inbox/mentions.md                 your mentions
   /me/api-key                        who you're signed in as
 
 ${colors.dim}Try${colors.reset}
   ls /projects
   cat /projects/<slug>/posts/<file>.md
+  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.
@@ -197,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 */
@@ -382,6 +403,11 @@ const VERBS = new Set([
     "new",
     "ls",
     "cat",
+    "url",
+    "open",
+    "blocks",
+    "put",
+    "watch",
     "post",
     "task",
     "doc",
@@ -396,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)
@@ -425,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) {
@@ -526,16 +621,19 @@ async function runVerb(args, fs, client) {
     const md = await readLocalFile(file, "utf8");
     const project = await resolveProject(fs, args.project, md);
     const base = basename(file);
-    const name = base.endsWith(".md") ? base : `${base}.md`;
+    const sourceName = base.endsWith(".md") ? base : `${base}.md`;
+    const name = args.command === "task" ? taskUploadFilename(sourceName) : sourceName;
     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}/docs/${name}`, md);
-        ok(`Doc saved to ${project} · ${name}`);
+        await fs.writeFile(`/projects/${project}/library/documents/${name}`, md);
+        said(`Doc saved to ${project} · ${name}`);
+        reportWrite(client, args.json);
         return;
     }
     if (args.command === "task") {
@@ -554,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) {
@@ -746,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);
         }
@@ -780,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 {
@@ -801,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;
@@ -822,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("/");
@@ -885,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/__tests__/byteStable.d.ts

@@ -0,0 +1,5 @@
+export type RoundTrip = (source: string) => string;
+export declare const documentRoundTrip: RoundTrip;
+export declare function assertByteStable(source: string, roundTrip?: RoundTrip): void;
+export declare function assertRoundTripIdentity(source: string, roundTrip?: RoundTrip): void;
+export declare function isByteStable(source: string, roundTrip?: RoundTrip): boolean;