sfora-cli 0.9.0 → 0.11.0

package/dist/api-client.js

@@ -8,32 +8,140 @@
  * 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) {
         const headers = Object.create(null);
         headers.Authorization = `Bearer ${this.#apiKey}`;
         if (this.#actAs)
@@ -42,7 +150,12 @@ export class SforaApiClient {
             headers["Content-Type"] = "text/markdown";
         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 +165,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 +209,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 +227,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) {
@@ -102,6 +237,25 @@ export class SforaApiClient {
     async setProjectLinks(slug, markdown) {
         await this.#request("PUT", `/v1/fs/projects/${encodeURIComponent(slug)}/links.md`, markdown);
     }
+    /** `GET …/plan.md` — the project's plan (goal + question buckets). */
+    // The map as a file: derived, read-only (a PUT is refused server-side).
+    async readMap(slug) {
+        return this.#text(`/v1/fs/projects/${encodeURIComponent(slug)}/map.md`);
+    }
+    async readPlan(slug) {
+        return this.#text(`/v1/fs/projects/${encodeURIComponent(slug)}/plan.md`);
+    }
+    /**
+     * `PUT …/plan.md` — set the goal. Only the `## the goal` section is
+     * honored; the server names everything it ignored in `ignoredSections`.
+     */
+    async writePlan(slug, markdown) {
+        await this.#request("PUT", `/v1/fs/projects/${encodeURIComponent(slug)}/plan.md`, markdown);
+    }
+    /** `GET …/asks.md` — coordination asks (read-only projection). */
+    async readAsks(slug) {
+        return this.#text(`/v1/fs/projects/${encodeURIComponent(slug)}/asks.md`);
+    }
     /**
      * `GET …/posts` or `…/drafts`. `scheduled` lists drafts that have a
      * (future) `scheduledFor` set.
@@ -123,14 +277,37 @@ export class SforaApiClient {
         const file = encodeURIComponent(filename);
         return this.#text(`/v1/fs/projects/${slug}/${base}/${file}`);
     }
-    /** `PUT …/(posts|drafts)/:filename.md` — create or update from a markdown file. */
-    async writePost(projectSlug, kind, filename, markdown) {
+    /** Create a post or upsert a mutable draft from a Markdown file. */
+    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) {
@@ -143,14 +320,52 @@ export class SforaApiClient {
     /** `GET …/docs` — the project's notes, most-recently-edited first. */
     async listNotes(projectSlug) {
         const slug = encodeURIComponent(projectSlug);
-        const data = await this.#json(`/v1/fs/projects/${slug}/docs`);
+        const data = await this.#json(`/v1/fs/projects/${slug}/library/documents`);
         return data.docs ?? [];
     }
     /** `GET …/docs/:filename.md`. Returns the raw markdown body. */
     async readNote(projectSlug, filename) {
         const slug = encodeURIComponent(projectSlug);
         const file = encodeURIComponent(filename);
-        return this.#text(`/v1/fs/projects/${slug}/docs/${file}`);
+        return this.#text(`/v1/fs/projects/${slug}/library/documents/${file}`);
+    }
+    async writeNote(projectSlug, filename, markdown) {
+        const slug = encodeURIComponent(projectSlug);
+        const file = encodeURIComponent(filename);
+        const res = await this.#request("PUT", `/v1/fs/projects/${slug}/library/documents/${file}`, markdown);
+        return await this.#jsonFrom(res);
+    }
+    async deleteNote(projectSlug, filename) {
+        const slug = encodeURIComponent(projectSlug);
+        const file = encodeURIComponent(filename);
+        await this.#request("DELETE", `/v1/fs/projects/${slug}/library/documents/${file}`);
+    }
+    // ─── Unified project Library ────────────────────────────────────
+    async listArtifacts(projectSlug) {
+        const slug = encodeURIComponent(projectSlug);
+        const data = await this.#json(`/v1/fs/projects/${slug}/library/files`);
+        return data.artifacts ?? [];
+    }
+    async readArtifact(projectSlug, filename) {
+        const slug = encodeURIComponent(projectSlug);
+        const file = encodeURIComponent(filename);
+        return this.#text(`/v1/fs/projects/${slug}/library/files/${file}`);
+    }
+    async listRepositories(projectSlug) {
+        const slug = encodeURIComponent(projectSlug);
+        const data = await this.#json(`/v1/fs/projects/${slug}/library/repositories`);
+        return data.repositories ?? [];
+    }
+    async getRepositoryTree(projectSlug, dirname) {
+        const slug = encodeURIComponent(projectSlug);
+        const repo = encodeURIComponent(dirname);
+        return this.#json(`/v1/fs/projects/${slug}/library/repositories/${repo}`);
+    }
+    async readRepositoryFile(projectSlug, dirname, path) {
+        const slug = encodeURIComponent(projectSlug);
+        const repo = encodeURIComponent(dirname);
+        const file = path.split("/").map(encodeURIComponent).join("/");
+        return this.#text(`/v1/fs/projects/${slug}/library/repositories/${repo}/${file}`);
     }
     // ─── Pull requests (read-only) ───────────────────────────────────
     /** `GET …/pulls` — the project's synced pull requests, open first. */
@@ -175,7 +390,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) {
@@ -207,7 +429,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) {
@@ -231,7 +453,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,
@@ -250,7 +472,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) {
@@ -276,7 +498,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. */
@@ -291,7 +513,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 ?? "" };
     }
     /**
@@ -309,9 +531,72 @@ 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/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;
+    }
     /** `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>;