sfora-cli 0.9.0 → 0.11.0

package/dist/render.js

@@ -0,0 +1,208 @@
+/**
+ * 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";
+/** `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;

package/dist/watch.js

@@ -0,0 +1,113 @@
+/**
+ * `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 { ndjson, renderPing } from "./render.js";
+/** A watcher that has been unreachable this long is not polling any faster. */
+export const MAX_BACKOFF_MS = 30_000;
+const DEFAULT_BACKOFF_MS = 1_000;
+/**
+ * The kinds this prints as pings.
+ *
+ * A `?doc=` poll returns only these; a `?project=` poll also carries room
+ * messages and ask changes, which are somebody else's stream. Filtering here
+ * rather than asking the server for less keeps one code path for both scopes.
+ */
+function isDocPing(event) {
+    return event.type === "doc.write" || event.type === "doc.delete";
+}
+/**
+ * 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 async function watchLoop(deps, options = {}) {
+    const stopped = options.stopped ?? (() => false);
+    const firstBackoff = options.backoffMs ?? DEFAULT_BACKOFF_MS;
+    let cursor = options.since ?? 0;
+    let backoff = firstBackoff;
+    let declared = false;
+    try {
+        while (!stopped()) {
+            // Beat before the poll, not after: the poll blocks for tens of seconds,
+            // and a row that expires mid-poll would drop the watcher off the roster
+            // for exactly as long as nothing is happening in the document.
+            if (deps.beat) {
+                try {
+                    await deps.beat({});
+                    declared = true;
+                }
+                catch {
+                    // A roster we could not join is not a reason to stop watching.
+                }
+            }
+            let page;
+            try {
+                page = await deps.poll(cursor);
+            }
+            catch (error) {
+                if (stopped())
+                    break;
+                const message = error instanceof Error ? error.message : String(error);
+                deps.warn(`reconnecting in ${Math.round(backoff / 1000)}s — ${message}`);
+                await deps.sleep(backoff);
+                backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+                continue;
+            }
+            // A poll that answered is a poll that works: any earlier trouble is over.
+            backoff = firstBackoff;
+            for (const event of page.events) {
+                if (!isDocPing(event))
+                    continue;
+                deps.write(options.json ? `${ndjson(event)}\n` : `${renderPing(event)}\n`);
+            }
+            // Never backwards: an empty page holds the cursor where it was.
+            cursor = Math.max(cursor, page.cursor);
+        }
+    }
+    finally {
+        // Leave even when the loop is being torn down by an exception — a ghost in
+        // somebody's avatar stack is the one failure a watcher can leave behind.
+        if (declared && deps.beat) {
+            await deps.beat({ leave: true }).catch(() => { });
+        }
+    }
+    return cursor;
+}
+export function parseWatchTarget(target) {
+    const trimmed = target.trim().replace(/\/+$/, "");
+    const segments = trimmed.split("/").filter(Boolean);
+    if (!trimmed.includes("/"))
+        return { kind: "project", slug: trimmed };
+    if (segments.length === 2 && segments[0] === "projects") {
+        return { kind: "project", slug: segments[1] };
+    }
+    return { kind: "path", path: trimmed.startsWith("/") ? trimmed : `/${trimmed}` };
+}

package/dist/web-url.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Where a thing lives on the web — read off the server's answer, never built.
+ *
+ * Card #335. The CLI holds NO route knowledge: it does not know that a document
+ * lives at `/org/<slug>/notes/<id>` or that a card opens as `?detail=card:<id>`,
+ * and it does not know the deployment's web origin. It asks for a path over
+ * `/v1/fs` and prints the link the server put on the answer. That is the whole
+ * contract, and it is why `sfora url` keeps working when the app's routes move.
+ *
+ * The server states it in one of two places, because fs responses come in two
+ * shapes:
+ *
+ *   • a **markdown read** answers with the document's bytes, so the link rides
+ *     in the `X-Sfora-Url` response header — putting it in the file would
+ *     change the canonical bytes every block id is computed over;
+ *   • a **JSON response** (a listing, a `?view=`, a write result) carries a
+ *     top-level `url` field.
+ *
+ * Both are read here so no caller has to care which door it opened.
+ */
+/** The response header a markdown read carries its page link in. */
+export declare const WEB_URL_HEADER = "x-sfora-url";
+/**
+ * The web URL a response names, or null when it names none.
+ *
+ * `body` is the response text when the caller already has it; without it only
+ * the header is consulted. Passing a body that is not JSON is fine — a
+ * markdown read hands its own bytes in and the parse simply fails.
+ */
+export declare function webUrlFromResponse(headers: {
+    get(name: string): string | null;
+}, body?: string): string | null;
+/**
+ * An fs path (`/projects/acme/posts/x.md`) as a `/v1/fs` request path.
+ *
+ * Each segment is encoded on its own so a filename with a space or a `#`
+ * survives, and the separators do not.
+ */
+export declare function fsRequestPath(path: string): string;

package/dist/web-url.js

@@ -0,0 +1,63 @@
+/**
+ * Where a thing lives on the web — read off the server's answer, never built.
+ *
+ * Card #335. The CLI holds NO route knowledge: it does not know that a document
+ * lives at `/org/<slug>/notes/<id>` or that a card opens as `?detail=card:<id>`,
+ * and it does not know the deployment's web origin. It asks for a path over
+ * `/v1/fs` and prints the link the server put on the answer. That is the whole
+ * contract, and it is why `sfora url` keeps working when the app's routes move.
+ *
+ * The server states it in one of two places, because fs responses come in two
+ * shapes:
+ *
+ *   • a **markdown read** answers with the document's bytes, so the link rides
+ *     in the `X-Sfora-Url` response header — putting it in the file would
+ *     change the canonical bytes every block id is computed over;
+ *   • a **JSON response** (a listing, a `?view=`, a write result) carries a
+ *     top-level `url` field.
+ *
+ * Both are read here so no caller has to care which door it opened.
+ */
+/** The response header a markdown read carries its page link in. */
+export const WEB_URL_HEADER = "x-sfora-url";
+/** An absolute `http(s)` URL, or null. Anything else is not a link we print. */
+function absolute(value) {
+    return typeof value === "string" && /^https?:\/\//.test(value) ? value : null;
+}
+/**
+ * The web URL a response names, or null when it names none.
+ *
+ * `body` is the response text when the caller already has it; without it only
+ * the header is consulted. Passing a body that is not JSON is fine — a
+ * markdown read hands its own bytes in and the parse simply fails.
+ */
+export function webUrlFromResponse(headers, body) {
+    const fromHeader = absolute(headers.get(WEB_URL_HEADER));
+    if (fromHeader)
+        return fromHeader;
+    if (!body)
+        return null;
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed && typeof parsed === "object") {
+            return absolute(parsed.url);
+        }
+    }
+    catch {
+        // Not JSON — a markdown body, which says nothing about its page.
+    }
+    return null;
+}
+/**
+ * An fs path (`/projects/acme/posts/x.md`) as a `/v1/fs` request path.
+ *
+ * Each segment is encoded on its own so a filename with a space or a `#`
+ * survives, and the separators do not.
+ */
+export function fsRequestPath(path) {
+    const segments = path
+        .split("/")
+        .filter((s) => s.length > 0)
+        .map(encodeURIComponent);
+    return `/v1/fs${segments.length ? `/${segments.join("/")}` : ""}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sfora-cli",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "Your sfora workspace as a markdown filesystem — a CLI + MCP server. Post/task/doc, ls/cat/grep, and a shell so agents operate sfora natively.",
   "keywords": [
@@ -36,15 +36,16 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc -p .",
-    "dev": "tsx src/cli.ts",
-    "typecheck": "tsc --noEmit"
+    "build": "node scripts/sync-format.mjs && tsc -p .",
+    "dev": "node scripts/sync-format.mjs && tsx src/cli.ts",
+    "typecheck": "node scripts/sync-format.mjs && tsc --noEmit"
   },
   "dependencies": {
-    "just-bash": "^3.0.1",
-    "@modelcontextprotocol/sdk": "^1.0.0"
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "just-bash": "^3.0.1"
   },
   "devDependencies": {
+    "@types/mdast": "^4.0.4",
     "@types/node": "^22.10.0",
     "tsx": "^4.20.3",
     "typescript": "^5.9.3"