sfora-cli 0.10.0 → 0.12.0

package/dist/cli.js

@@ -11,83 +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, ndjson, presenceRecords, renderPresence, 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 };
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === "--mcp")
-            args.mcp = true;
-        else if (a === "--help" || a === "-h")
-            args.help = true;
-        else if (a === "--org")
-            args.org = argv[++i];
-        else if (a.startsWith("--org="))
-            args.org = a.slice("--org=".length);
-        else if (a === "--cwd")
-            args.cwd = argv[++i] ?? "/";
-        else if (a.startsWith("--cwd="))
-            args.cwd = a.slice("--cwd=".length);
-        else if (a === "--url")
-            args.url = argv[++i];
-        else if (a.startsWith("--url="))
-            args.url = a.slice("--url=".length);
-        else if (a === "--key")
-            args.key = argv[++i];
-        else if (a.startsWith("--key="))
-            args.key = a.slice("--key=".length);
-        else if (a === "--bot" || a === "--agent")
-            args.bot = argv[++i];
-        else if (a.startsWith("--bot="))
-            args.bot = a.slice("--bot=".length);
-        else if (a.startsWith("--agent="))
-            args.bot = a.slice("--agent=".length);
-        else if (a === "--as")
-            args.as = argv[++i];
-        else if (a.startsWith("--as="))
-            args.as = a.slice("--as=".length);
-        else if (a === "--web")
-            args.web = argv[++i];
-        else if (a.startsWith("--web="))
-            args.web = a.slice("--web=".length);
-        else if (a === "--project")
-            args.project = argv[++i];
-        else if (a.startsWith("--project="))
-            args.project = a.slice("--project=".length);
-        else if (a === "--column")
-            args.column = argv[++i];
-        else if (a.startsWith("--column="))
-            args.column = a.slice("--column=".length);
-        else if (a === "--draft")
-            args.draft = true;
-        else if (a === "--json")
-            args.json = true;
-        else if (a === "--local")
-            args.local = true;
-        else if (a === "--cloud")
-            args.cloud = true;
-        else if (!a.startsWith("-")) {
-            if (!args.command)
-                args.command = a;
-            else
-                args.rest.push(a);
-        }
-    }
-    return args;
-}
+import { parseArgs } from "./cli-args.js";
+import { chatTailLoop, renderChatMessage, renderRoomList, resolveRoomRef, roomSlug, } from "./chat.js";
 const HELP = `sfora — the CLI for your sfora workspace
 
 Get started (no account needed):
@@ -121,11 +54,33 @@ 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.
 
+Chat:
+  sfora rooms                         List rooms (● joined · ○ open to join)
+  sfora join <room>                   Join an open room
+  sfora chat <room> [-n <count>]      Read the room, then type to talk —
+                                      new messages stream in live
+  sfora chat <room> -m "text"         Send one message and exit (for scripts
+                                      and agents)
+
+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)
+  sfora where [name]                  Who's in which document right now
+
+  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. "where" is a read only —
+  asking never puts you in a document.
+
 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 +100,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 +120,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 +161,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 +342,12 @@ const VERBS = new Set([
     "new",
     "ls",
     "cat",
+    "url",
+    "open",
+    "blocks",
+    "put",
+    "watch",
+    "where",
     "post",
     "task",
     "doc",
@@ -395,11 +359,35 @@ const VERBS = new Set([
     "whoami",
     "comment",
     "react",
+    "rooms",
+    "join",
+    "chat",
 ]);
 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 +415,115 @@ 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]);
+    }
+    // `where` — the reverse of presence. Card #345.
+    //
+    // Nothing is declared by running it: the server answers a query and the CLI
+    // prints it. That matters enough to be a property of the verb rather than a
+    // note about it — `sfora where` is the command an agent runs to find out
+    // where a human is working, and a version of it that joined the roster would
+    // make an agent appear in a document it had only asked about.
+    //
+    // The name is the whole argument list. `--as` composes for free (it is a
+    // header on the client, so `sfora where --as bot` asks as the bot and gets
+    // the bot's visibility), and no `--project` filter exists because the answer
+    // is already scoped to what this key can open.
+    if (args.command === "where") {
+        const view = await client.listPresence(args.rest[0]);
+        if (args.json) {
+            // NDJSON, matching `watch --json`: one record per line, no wrapper. A
+            // pretty-printed object would break `sfora where --json | jq -r .url`
+            // for the same reason it would there.
+            for (const record of presenceRecords(view)) {
+                process.stdout.write(`${ndjson(record)}\n`);
+            }
+            return;
+        }
+        console.log(renderPresence(view));
+        return;
+    }
+    // Chat — the same rooms the app shows, from the terminal. Humans and agents
+    // are the same member model, so this is how either sits in the conversation.
+    if (args.command === "rooms") {
+        const rooms = await client.listRooms(true);
+        if (args.json)
+            return emitJson(rooms);
+        console.log(renderRoomList(rooms));
+        return;
+    }
+    if (args.command === "join") {
+        if (!args.rest[0])
+            throw new Error("usage: sfora join <room>");
+        const room = await resolveRoomOrThrow(client, args.rest[0]);
+        const result = await client.joinRoom(room._id);
+        if (args.json)
+            return emitJson({ ...result, roomId: room._id, name: room.name });
+        ok(result.already
+            ? `Already in #${roomSlug(room.name)}`
+            : `Joined #${roomSlug(room.name)}`);
+        return;
+    }
+    if (args.command === "chat") {
+        if (!args.rest[0]) {
+            throw new Error('usage: sfora chat <room> [-n <count>] [-m "text"]');
+        }
+        return runChat(args, client);
+    }
     if (args.command === "me" || args.command === "whoami") {
         const text = (await client.readMe()).trim();
         if (args.json) {
@@ -533,12 +622,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,9 +648,344 @@ 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);
+    }
+}
+/**
+ * The room a reference names, or a thrown explanation.
+ *
+ * Resolution reads `?all=1` so an unjoined room can still be found — `sfora
+ * join dogfood` has to work before the caller is in it. Ambiguity throws with
+ * the candidates rather than guessing: sending into the wrong room is the
+ * failure worth a retype.
+ */
+async function resolveRoomOrThrow(client, ref) {
+    const rooms = await client.listRooms(true);
+    const match = resolveRoomRef(rooms, ref);
+    if (match.kind === "match")
+        return match.room;
+    if (match.kind === "ambiguous") {
+        throw new Error(`'${ref}' matches several rooms — say which:\n` +
+            match.candidates.map((r) => `  ${roomSlug(r.name)}`).join("\n"));
+    }
+    throw new Error(`no room matches '${ref}' — run \`sfora rooms\` to see them`);
+}
+/**
+ * `sfora chat <room>` — the room in the terminal, wired to the real process.
+ *
+ * Everything decision-shaped (name resolution, formatting, the tail loop)
+ * lives in `chat.ts` where it is tested; this owns readline, ^C, and the two
+ * modes: `-m` sends one message and exits (what scripts and agents use), bare
+ * `chat` prints history and opens a prompt with a live tail above it.
+ */
+async function runChat(args, client) {
+    const room = await resolveRoomOrThrow(client, args.rest[0]);
+    const tag = `#${roomSlug(room.name)}`;
+    const isTty = Boolean(process.stdin.isTTY);
+    if (!room.joined) {
+        // Offered inline on a terminal; stated as the fix everywhere else — a
+        // script cannot answer a question, so it gets the command instead.
+        if (args.message !== undefined || !isTty) {
+            throw new Error(`you have not joined ${tag} — run \`sfora join ${roomSlug(room.name)}\` first`);
+        }
+        const ask = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        const answer = await new Promise((res) => ask.question(`You have not joined ${tag} — join? (y/n) `, res));
+        ask.close();
+        if (!/^y(es)?$/i.test(answer.trim()))
+            return;
+        await client.joinRoom(room._id);
+        console.log(`${colors.green}✓${colors.reset} Joined ${tag}`);
+    }
+    // One-shot send.
+    if (args.message !== undefined) {
+        const text = args.message.trim();
+        if (!text)
+            throw new Error('usage: sfora chat <room> -m "text"');
+        const { messageId } = await client.sendRoomMessage(room._id, text);
+        if (args.json) {
+            console.log(JSON.stringify({ messageId, roomId: room._id }, null, 2));
+            return;
+        }
+        console.log(`${colors.green}✓${colors.reset} Sent to ${tag}`);
         return;
     }
+    // History, oldest first — the page arrives newest-first.
+    const limit = Number.isFinite(args.limit) && args.limit > 0
+        ? Math.min(args.limit, 100)
+        : 30;
+    // Seed the seen set from as many messages as the tail's refetch pulls (20):
+    // with -n below that, the doorbell would otherwise "discover" older history
+    // and flood it as if it had just arrived. Print only the asked-for n.
+    const history = await client.listRoomMessages(room._id, Math.max(limit, 20));
+    const seeded = history.page.slice().reverse();
+    const seen = new Set(seeded.map((m) => m._id));
+    const messages = seeded.slice(-limit);
+    if (messages.length === 0) {
+        console.log(`${colors.dim}(no messages yet)${colors.reset}`);
+    }
+    for (const msg of messages)
+        console.log(renderChatMessage(msg, Date.now()));
+    process.stderr.write(`${colors.dim}${tag} — type to send · /quit (or ^C) to leave${colors.reset}\n`);
+    // The prompt and the tail share one screen: an arriving message clears the
+    // prompt line, prints, and readline redraws the prompt with whatever was
+    // being typed. `readline.clearLine` over anything fancier — robust beats
+    // pretty at 80 columns.
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: isTty,
+    });
+    rl.setPrompt(`${colors.cyan}${tag}${colors.reset} `);
+    const printAbove = (text) => {
+        if (isTty) {
+            readline.clearLine(process.stdout, 0);
+            readline.cursorTo(process.stdout, 0);
+        }
+        process.stdout.write(`${text}\n`);
+        if (isTty)
+            rl.prompt(true);
+    };
+    // ^C has to reach the socket, same as `watch`: the long-poll hangs for tens
+    // of seconds, and a flag alone would leave a terminal that says it stopped
+    // and hasn't. Closing readline ends the line iterator; aborting the request
+    // ends the poll; the loop sees `stopped()` and returns.
+    let stop = false;
+    const inFlight = new AbortController();
+    rl.on("SIGINT", () => rl.close());
+    rl.on("close", () => {
+        stop = true;
+        inFlight.abort();
+    });
+    const wait = Number.isFinite(args.wait) ? args.wait : undefined;
+    const tail = chatTailLoop({
+        poll: (since) => client.pollEvents({ since, wait, signal: inFlight.signal }),
+        fetchRecent: async () => (await client.listRoomMessages(room._id, 20)).page,
+        print: (msg) => printAbove(renderChatMessage(msg, Date.now())),
+        warn: (text) => printAbove(`${colors.dim}${text}${colors.reset}`),
+        sleep,
+    }, {
+        roomId: room._id,
+        seen,
+        // Cursor on SERVER time: the newest history message's _creationTime.
+        // A client clock running fast would otherwise open a blind window at
+        // startup; any overlap re-delivery is absorbed by the seen set.
+        since: history.page[0]?._creationTime ?? Date.now(),
+        stopped: () => stop,
+    });
+    if (isTty)
+        rl.prompt();
+    for await (const input of rl) {
+        const line = input.trim();
+        if (!line) {
+            if (isTty)
+                rl.prompt();
+            continue;
+        }
+        if (line === "/quit" || line === "/exit" || line === "/q")
+            break;
+        try {
+            // The send's own echo is the typed line still on screen; recording the
+            // id keeps the tail's refetch from printing it a second time.
+            const { messageId } = await client.sendRoomMessage(room._id, line);
+            seen.add(messageId);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            process.stderr.write(`${colors.red}error:${colors.reset} ${msg}\n`);
+        }
+        if (isTty)
+            rl.prompt();
+    }
+    stop = true;
+    inFlight.abort();
+    rl.close();
+    await tail.catch(() => { });
+    if (isTty)
+        console.log("");
+}
+/**
+ * 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";
@@ -749,13 +1175,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 +1213,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 +1240,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 +1263,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 +1328,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;
         }