sfora-cli 0.10.0 → 0.12.0

package/dist/api-client.js

@@ -8,41 +8,156 @@
  * JSON/markdown shapes, and it surfaces non-2xx responses as {@link SforaApiError}.
  * Path/virtual-filesystem semantics live in SforaFs.
  */
+import { fsRequestPath, webUrlFromResponse } from "./web-url.js";
+/** The effect report in a parsed response body, or null when there is none. */
+export function writeEffectFrom(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    const obj = body;
+    if (typeof obj.changed !== "boolean")
+        return null;
+    const counts = obj.blockIds;
+    const blockIds = counts &&
+        typeof counts.rebound === "number" &&
+        typeof counts.orphaned === "number" &&
+        typeof counts.total === "number"
+        ? { rebound: counts.rebound, orphaned: counts.orphaned, total: counts.total }
+        : undefined;
+    return blockIds ? { changed: obj.changed, blockIds } : { changed: obj.changed };
+}
 /** Non-2xx response from the fs API. Carries the HTTP status + machine code so SforaFs can map it to an errno. */
 export class SforaApiError extends Error {
     status;
     code;
-    constructor(status, code, message) {
+    /**
+     * The parsed error body, when there was one.
+     *
+     * Some refusals are USEFUL, not merely informative: a 409 from a `?block=`
+     * write carries the document's current blocks so the caller can re-aim
+     * without a second round trip. Throwing away everything but the message
+     * would make the CLI ask for that page again. Untyped here because the fs
+     * error envelope is `{ error, message }` plus whatever the specific refusal
+     * adds; {@link blockConflictFrom} is the typed reader for the one shape the
+     * CLI acts on.
+     */
+    data;
+    constructor(status, code, message, data) {
         super(message);
         this.name = "SforaApiError";
         this.status = status;
         this.code = code;
+        this.data = data;
     }
 }
+/** The 409 recovery payload inside an error, or null for any other failure. */
+export function blockConflictFrom(error) {
+    if (!(error instanceof SforaApiError) || error.status !== 409)
+        return null;
+    const data = error.data;
+    if (!data || !Array.isArray(data.blocks))
+        return null;
+    return {
+        message: typeof data.message === "string" ? data.message : error.message,
+        block: typeof data.block === "string" ? data.block : undefined,
+        // Narrowed row by row rather than cast wholesale. A cast is what let the
+        // renderer print `undefined` in a column the payload never had: the shape
+        // was ASSERTED to match `?view=blocks` and never checked against the wire.
+        // Anything that is not a summary is dropped, so a server that grows the
+        // payload cannot make the table lie.
+        blocks: data.blocks.filter(isBlockSummary),
+    };
+}
+function isBlockSummary(row) {
+    if (!row || typeof row !== "object")
+        return false;
+    const b = row;
+    return (typeof b.id === "string" &&
+        typeof b.line === "number" &&
+        typeof b.preview === "string");
+}
 /** The route segment a `PostKind` maps to. `scheduled` reads/writes through the drafts route. */
 function routeBase(kind) {
     return kind === "posts" ? "posts" : "drafts";
 }
+/** `?block=<id>` when one was asked for, and nothing at all when it wasn't. */
+function blockQuery(options) {
+    return options?.blockId
+        ? `?block=${encodeURIComponent(options.blockId)}`
+        : "";
+}
 export class SforaApiClient {
     #baseUrl;
     #apiKey;
     #actAs;
+    /**
+     * What the LAST response said about itself, beyond the data it carried.
+     *
+     * Two facts live here and both are for the human at the terminal: the page
+     * the response names (card #335) and the effect report a markdown write
+     * returns (card #333). Recorded rather than returned because the callers
+     * that print them — `sfora cat`, `sfora ls`, `sfora post/task/doc`, the
+     * shell — reach the API through `SforaFs`, which speaks `IFileSystem` and
+     * has nowhere in its signatures to put either. A second request to fetch
+     * them would double every read to print one dim line.
+     *
+     * {@link takeResponseInfo} CLEARS it, so a command can never print a link or
+     * an effect belonging to an earlier one.
+     */
+    #lastInfo = { url: null, effect: null, present: false };
     constructor(config) {
         this.#baseUrl = config.baseUrl.replace(/\/+$/, "");
         this.#apiKey = config.apiKey;
         this.#actAs = config.actAs;
     }
+    /** What the last response said about itself, consumed. */
+    takeResponseInfo() {
+        const info = this.#lastInfo;
+        this.#lastInfo = { url: null, effect: null, present: false };
+        return info;
+    }
+    /**
+     * The web page an fs path is read on, or null when it has none.
+     *
+     * One request, and the ONLY route knowledge involved is the server's: this
+     * reads the path the caller gave and reports the link the answer carried.
+     * A directory listing answers in JSON, a document in markdown with the link
+     * in a header, and {@link webUrlFromResponse} covers both.
+     */
+    async resolveWebUrl(fsPath) {
+        const res = await this.#request("GET", fsRequestPath(fsPath));
+        const fromHeader = webUrlFromResponse(res.headers);
+        if (fromHeader)
+            return fromHeader;
+        const type = res.headers.get("content-type") ?? "";
+        if (!type.includes("json"))
+            return null;
+        return webUrlFromResponse(res.headers, await res.text());
+    }
     // ─── HTTP plumbing ──────────────────────────────────────────────
-    async #request(method, path, body) {
+    async #request(method, path, body, 
+    /**
+     * Cancels the request in flight. Only the long-poll passes one: it is the
+     * single call that blocks for tens of seconds, so it is the single call
+     * where "stop" has to mean the socket and not just a flag the caller will
+     * read after it returns.
+     */
+    signal, 
+    /** The fs surface speaks markdown; the /api chat endpoints speak JSON. */
+    contentType = "text/markdown") {
         const headers = Object.create(null);
         headers.Authorization = `Bearer ${this.#apiKey}`;
         if (this.#actAs)
             headers["X-Sfora-Act-As"] = this.#actAs;
         if (body !== undefined)
-            headers["Content-Type"] = "text/markdown";
+            headers["Content-Type"] = contentType;
         let res;
         try {
-            res = await fetch(`${this.#baseUrl}${path}`, { method, headers, body });
+            res = await fetch(`${this.#baseUrl}${path}`, {
+                method,
+                headers,
+                body,
+                signal,
+            });
         }
         catch (e) {
             // Network/DNS/connection failures — surface as a 0-status error so the
@@ -52,16 +167,39 @@ export class SforaApiClient {
         }
         if (!res.ok)
             throw await this.#toError(res);
+        // Markdown reads carry their page link in a header; JSON responses carry it
+        // in the body, and `#jsonFrom` picks it up there. Set on every response so
+        // one that names no entity CLEARS what an earlier one left behind.
+        this.#lastInfo = {
+            url: webUrlFromResponse(res.headers),
+            effect: null,
+            present: false,
+        };
         return res;
     }
+    /** Parse a JSON response, remembering the page and effect report it names. */
+    async #jsonFrom(res) {
+        const text = await res.text();
+        const parsed = JSON.parse(text);
+        this.#lastInfo = {
+            url: webUrlFromResponse(res.headers, text),
+            effect: writeEffectFrom(parsed),
+            present: !!parsed &&
+                typeof parsed === "object" &&
+                parsed.present === true,
+        };
+        return parsed;
+    }
     async #toError(res) {
         const text = await res.text().catch(() => "");
         let code = "bad_request";
         let message = text || res.statusText;
+        let data;
         if (text) {
             try {
                 const parsed = JSON.parse(text);
                 if (parsed && typeof parsed === "object") {
+                    data = parsed;
                     const obj = parsed;
                     if (typeof obj.error === "string")
                         code = obj.error;
@@ -73,11 +211,10 @@ export class SforaApiClient {
                 // Non-JSON error body — keep the raw text as the message.
             }
         }
-        return new SforaApiError(res.status, code, message);
+        return new SforaApiError(res.status, code, message, data);
     }
-    async #json(path) {
-        const res = await this.#request("GET", path);
-        return (await res.json());
+    async #json(path, signal) {
+        return this.#jsonFrom(await this.#request("GET", path, undefined, signal));
     }
     async #text(path) {
         const res = await this.#request("GET", path);
@@ -92,7 +229,7 @@ export class SforaApiClient {
     /** `POST /v1/fs/projects` — create a project; the caller becomes its lead. */
     async createProject(name) {
         const res = await this.#request("POST", "/v1/fs/projects", JSON.stringify({ name }));
-        return (await res.json());
+        return this.#jsonFrom(res);
     }
     /** `GET …/links.md` — the project's external links as markdown. */
     async getProjectLinks(slug) {
@@ -143,13 +280,36 @@ export class SforaApiClient {
         return this.#text(`/v1/fs/projects/${slug}/${base}/${file}`);
     }
     /** Create a post or upsert a mutable draft from a Markdown file. */
-    async writePost(projectSlug, kind, filename, markdown) {
+    async writePost(projectSlug, kind, filename, markdown, options) {
         const base = routeBase(kind);
         const slug = encodeURIComponent(projectSlug);
         const file = encodeURIComponent(filename);
-        const res = await this.#request("PUT", `/v1/fs/projects/${slug}/${base}/${file}`, markdown);
-        const data = (await res.json());
-        return { filename: data.filename, id: data.id };
+        const res = await this.#request("PUT", `/v1/fs/projects/${slug}/${base}/${file}${blockQuery(options)}`, markdown);
+        // The WHOLE report, not just `{ filename, id }`: `changed` and the rebind
+        // counts are what card #333 prints after every write, and narrowing here
+        // would throw them away one layer below the caller that needs them.
+        return this.#jsonFrom(res);
+    }
+    /**
+     * `GET …?view=blocks` on any fs path with a stored markdown body — the
+     * addressable view a `?block=` write aims into.
+     *
+     * The path is the caller's fs path (`/projects/acme/docs/x.md`), not a
+     * `/v1/fs` URL: the CLI does not build routes.
+     */
+    async readBlocks(fsPath) {
+        return this.#json(`${fsRequestPath(fsPath)}?view=blocks`);
+    }
+    /**
+     * `PUT <fs path>` — the generic write door, so the CLI can put to any path
+     * (and to a single block of it) without a per-entity method.
+     *
+     * A 409 from a `?block=` write throws a {@link SforaApiError} carrying the
+     * server's recovery payload; read it with {@link blockConflictFrom}.
+     */
+    async writePath(fsPath, markdown, options) {
+        const res = await this.#request("PUT", `${fsRequestPath(fsPath)}${blockQuery(options)}`, markdown);
+        return this.#jsonFrom(res);
     }
     /** `DELETE …/(posts|drafts)/:filename.md` — soft-deletes the matched post. */
     async deletePost(projectSlug, kind, filename) {
@@ -175,7 +335,7 @@ export class SforaApiClient {
         const slug = encodeURIComponent(projectSlug);
         const file = encodeURIComponent(filename);
         const res = await this.#request("PUT", `/v1/fs/projects/${slug}/library/documents/${file}`, markdown);
-        return (await res.json());
+        return await this.#jsonFrom(res);
     }
     async deleteNote(projectSlug, filename) {
         const slug = encodeURIComponent(projectSlug);
@@ -232,7 +392,14 @@ export class SforaApiClient {
     async getBoardMeta(projectSlug) {
         const slug = encodeURIComponent(projectSlug);
         const data = await this.#json(`/v1/fs/projects/${slug}/board`);
-        return { publicSlug: data.publicSlug ?? null, columns: data.columns };
+        return {
+            publicSlug: data.publicSlug ?? null,
+            columns: data.columns,
+            // Kept, not derived. The roadmap projection quotes this verbatim, and
+            // rebuilding it here from `publicSlug` would put the hostname back in
+            // the CLI — which is the whole thing the server sending it prevents.
+            publicUrl: data.publicUrl ?? null,
+        };
     }
     /** `GET …/board` — list the project's columns (auto-creates the board on first call). */
     async listColumns(projectSlug) {
@@ -264,7 +431,7 @@ export class SforaApiClient {
         const col = encodeURIComponent(columnDir);
         const file = encodeURIComponent(filename);
         const res = await this.#request("PUT", `/v1/fs/projects/${slug}/board/${col}/${file}`, markdown);
-        return (await res.json());
+        return await this.#jsonFrom(res);
     }
     /** `DELETE …/board/:column/:filename.md` — archives the card. */
     async deleteCard(projectSlug, columnDir, filename) {
@@ -288,7 +455,7 @@ export class SforaApiClient {
         });
         if (!res.ok)
             throw await this.#toError(res);
-        return (await res.json());
+        return await this.#jsonFrom(res);
     }
     /**
      * `POST …/board/:column/_rename` with `{ name }` — renames the column,
@@ -307,7 +474,7 @@ export class SforaApiClient {
         });
         if (!res.ok)
             throw await this.#toError(res);
-        return (await res.json());
+        return await this.#jsonFrom(res);
     }
     /** `DELETE …/board/:column` — column must be empty. */
     async deleteColumn(projectSlug, columnDir) {
@@ -333,7 +500,7 @@ export class SforaApiClient {
         });
         if (!res.ok)
             throw await this.#toError(res);
-        return (await res.json());
+        return await this.#jsonFrom(res);
     }
     // ─── Post actions (comment / react) ─────────────────────────────
     /** `POST /v1/posts/:postId/comments` — add a comment to a post. */
@@ -348,7 +515,7 @@ export class SforaApiClient {
         });
         if (!res.ok)
             throw await this.#toError(res);
-        const data = (await res.json());
+        const data = await this.#jsonFrom(res);
         return { id: data.comment?._id ?? "" };
     }
     /**
@@ -366,9 +533,110 @@ export class SforaApiClient {
         });
         if (!res.ok)
             throw await this.#toError(res);
-        const data = (await res.json());
+        const data = await this.#jsonFrom(res);
         return data.reaction ?? { content: emoji, reacted: true };
     }
+    // ─── Live docs: the roster and the ping stream ───────────────────
+    /**
+     * `POST <path>/_presence` — say you are in a document.
+     *
+     * Returns `null` when the path has no roster. The CLI does not decide which
+     * paths those are: it asks, and a `422` is the server's named refusal
+     * ("posts and board cards have markdown bodies but nobody has one open in a
+     * document editor"). Every other failure is thrown as usual.
+     */
+    async declarePresence(fsPath, options = {}) {
+        const params = new URLSearchParams();
+        if (options.kind)
+            params.set("kind", options.kind);
+        if (options.block)
+            params.set("block", options.block);
+        if (options.leave)
+            params.set("leave", "");
+        const query = params.toString();
+        try {
+            const res = await this.#request("POST", `${fsRequestPath(fsPath)}/_presence${query ? `?${query}` : ""}`);
+            return this.#jsonFrom(res);
+        }
+        catch (error) {
+            if (error instanceof SforaApiError && error.status === 422)
+                return null;
+            throw error;
+        }
+    }
+    /**
+     * `GET /v1/presence` — where everybody is right now.
+     *
+     * The reverse of {@link declarePresence}, and a pure read: asking never
+     * enrols the asker in anything. `member` takes an id, a name, or `self`.
+     *
+     * Documents the key cannot open are absent from the answer — the server
+     * filters, the CLI prints. That is why this returns everything it is given
+     * rather than filtering again here.
+     */
+    async listPresence(member) {
+        const query = member ? `?member=${encodeURIComponent(member)}` : "";
+        return this.#json(`/v1/presence${query}`);
+    }
+    /**
+     * `GET /v1/events` — the long-poll. Blocks server-side until something
+     * happens or the wait budget elapses, then answers with a cursor to poll
+     * from next.
+     *
+     * `signal` is not optional in spirit: this is the ONE request in the client
+     * that is designed to hang, so a caller that cannot cancel it cannot stop.
+     * `sfora watch` aborts it from its ^C handler, which is the difference
+     * between a terminal that says "^C to stop" and one that does.
+     */
+    async pollEvents(params) {
+        const query = new URLSearchParams({ since: String(params.since) });
+        if (params.wait !== undefined)
+            query.set("wait", String(params.wait));
+        if (params.doc)
+            query.set("doc", params.doc);
+        if (params.project)
+            query.set("project", params.project);
+        // `?self=include` is the server's spelling; the default is to exclude your
+        // own writes, matching the message branch's "don't wake on your own".
+        if (params.includeSelf)
+            query.set("self", "include");
+        return this.#json(`/v1/events?${query.toString()}`, params.signal);
+    }
+    /**
+     * The entity id behind an fs path — what `/v1/events?doc=` wants.
+     *
+     * Read off `?view=blocks`, which states the document's identity in its
+     * `document` field, rather than parsed out of the file's frontmatter: the
+     * projection is the server saying which row these bytes are.
+     */
+    async resolveDocId(fsPath) {
+        const view = await this.readBlocks(fsPath);
+        return view.document?.id ?? null;
+    }
+    // ─── Chat (rooms + messages) ─────────────────────────────────────
+    /**
+     * `GET /api/rooms` — the caller's rooms. `all` adds open-but-unjoined rooms
+     * (`joined: false`), so the room can be found before it is joined.
+     */
+    async listRooms(all = false) {
+        return this.#json(`/api/rooms${all ? "?all=1" : ""}`);
+    }
+    /** `POST /api/rooms/:id/join` — self-join an open room. Idempotent. */
+    async joinRoom(roomId) {
+        const res = await this.#request("POST", `/api/rooms/${encodeURIComponent(roomId)}/join`);
+        return this.#jsonFrom(res);
+    }
+    /** `GET /api/rooms/:id/messages` — history, newest first (server cap: 100). */
+    async listRoomMessages(roomId, limit = 30) {
+        return this.#json(`/api/rooms/${encodeURIComponent(roomId)}/messages?limit=${limit}`);
+    }
+    /** `POST /api/rooms/:id/messages` with `{ body }` — send markdown. */
+    async sendRoomMessage(roomId, body) {
+        // Through #request like every other call, so network failures surface as
+        // SforaApiError(0, "network_error") and `--as` rides the shared headers.
+        const res = await this.#request("POST", `/api/rooms/${encodeURIComponent(roomId)}/messages`, JSON.stringify({ body }), undefined, "application/json");
+        return this.#jsonFrom(res);
+    }
     /** `GET /v1/fs/inbox/mentions.md` — markdown summary of unread mentions. */
     async readInbox() {
         return this.#text("/v1/fs/inbox/mentions.md");

package/dist/block-commands.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `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 { type SforaApiClient } from "./api-client.js";
+export interface CommandOutput {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/**
+ * "Once per run" as a value rather than a module-level flag.
+ *
+ * The presence note ("you are visible as editing this document") is a fact
+ * about the user's visibility to other people, so it is said out loud — but
+ * said on every write it is noise, and the second one teaches nothing. "Once"
+ * therefore has to be remembered somewhere, and the somewhere cannot be a
+ * `let` inside `putCommand` (per call is not once) nor a module-level flag
+ * (per PROCESS, which makes the second test in a file depend on the first, and
+ * which the interactive shell and the `put` verb would each keep their own of
+ * — announcing twice).
+ *
+ * A run owns one of these and hands it to everything that might say the line.
+ */
+export interface PresenceNotice {
+    /** True the first time the note is worth printing, false forever after. */
+    claim(): boolean;
+}
+export declare function presenceNotice(): PresenceNotice;
+/** An absolute fs path from a possibly-relative one plus the shell's cwd. */
+export declare function resolveFsPath(cwd: string, path: string): string;
+/**
+ * `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 declare function blocksCommand(client: SforaApiClient, fsPath: string, options?: {
+    json?: boolean;
+}): Promise<CommandOutput>;
+/**
+ * `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 declare function putCommand(client: SforaApiClient, fsPath: string, body: string, options?: {
+    blockId?: string;
+    json?: boolean;
+    /**
+     * The run's presence latch. Omitted means "this call is the run" — a
+     * single `sfora put` announces, which is exactly once.
+     */
+    presence?: PresenceNotice;
+}): Promise<CommandOutput>;
+/** `url <path>` — the page, printed. See `web-url.ts` for who knows the route. */
+export declare function urlCommand(client: SforaApiClient, fsPath: string, options?: {
+    json?: boolean;
+}): Promise<CommandOutput>;

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)}`);
+    }
+}