sfora-cli 0.10.0 → 0.12.0

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.10.0",
+  "version": "0.12.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": [