sfora-cli 0.16.0 → 0.17.0

package/dist/attachments.js

@@ -0,0 +1,254 @@
+/**
+ * `attachments <post>` — the files a person attached to a post (card #822).
+ *
+ * Three doors, one module: the `sfora attachments` verb (list, or write the
+ * files with `--out`), the shell's `attachments` command (list only — the
+ * shell's fs is the workspace, not the disk), and the MCP tools' list and
+ * fetch, where an image comes back as image content a vision client can see.
+ *
+ * Every byte is fetched through the API with the caller's key; the server
+ * applies the post's own read rule, so nothing here decides access. What this
+ * module does decide is what lands on disk: a name that cannot leave the
+ * `--out` directory, and a file whose type and size match what was listed.
+ *
+ * No `node:` imports, so the hosted MCP route can import it; the CLI hands in
+ * the disk through {@link AttachmentIo} (see attachments-node.ts).
+ */
+import { SforaApiError } from "./api-client.js";
+import { colors } from "./render.js";
+/**
+ * The server's limit (Convex's HTTP response cap, checked against the stored
+ * size). Mirrored here so a listed file over it is skipped without a request.
+ */
+export const ATTACHMENT_MAX_BYTES = 20 * 1024 * 1024;
+const ok = (stdout, stderr = "") => ({ stdout, stderr, exitCode: 0 });
+const fail = (stderr, stdout = "") => ({
+    stdout,
+    stderr: stderr.endsWith("\n") ? stderr : `${stderr}\n`,
+    exitCode: 1,
+});
+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);
+}
+function humanSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/**
+ * A file name that is safe to write inside one directory: the last path
+ * segment only (either separator), no control characters, no leading dots,
+ * and unique among the names already `taken` (`shot.png`, `shot-2.png`, …).
+ * An empty result falls back to `attachment-<id>`.
+ */
+export function safeAttachmentName(name, id, taken) {
+    const base = (name.split(/[\\/]/).pop() ?? "")
+        .replace(/[\u0000-\u001f\u007f]/g, "")
+        .trim()
+        .replace(/^\.+/, "")
+        .slice(0, 200);
+    const chosen = base || `attachment-${id}`;
+    const dot = chosen.lastIndexOf(".");
+    const [stem, ext] = dot > 0 ? [chosen.slice(0, dot), chosen.slice(dot)] : [chosen, ""];
+    let candidate = chosen;
+    for (let n = 2; taken.has(candidate.toLowerCase()); n++)
+        candidate = `${stem}-${n}${ext}`;
+    taken.add(candidate.toLowerCase());
+    return candidate;
+}
+/** The media type without parameters, lowercased: `image/png; x=y` → `image/png`. */
+const essence = (type) => type.split(";")[0].trim().toLowerCase();
+/**
+ * Whether a download is what the listing promised. The server serves a type
+ * it does not trust as `application/octet-stream`, so that is accepted for
+ * any listed type; anything else must match exactly, as must the byte count.
+ */
+function mismatch(row, got) {
+    const served = essence(got.type);
+    if (served !== essence(row.type) && served !== "application/octet-stream") {
+        return `served as ${served || "no type"}, listed as ${row.type}`;
+    }
+    if (got.bytes.byteLength !== row.size) {
+        return `${got.bytes.byteLength} bytes, listed as ${row.size}`;
+    }
+    return null;
+}
+/**
+ * `sfora attachments <post> [--out <dir>] [--json]`.
+ *
+ * Without `--out` it lists. With it, it writes each file into the directory
+ * and prints one local path per line (so an agent can open the images); a
+ * file that is too large, or does not match its listing, is skipped with a
+ * line on stderr and the command exits 1 after writing the rest.
+ */
+export async function attachmentsCommand(client, fsPath, options = {}) {
+    let rows;
+    try {
+        rows = await client.listAttachments(fsPath);
+        client.takeResponseInfo();
+    }
+    catch (error) {
+        return fail(`${colors.red}error:${colors.reset} ${apiMessage(error)}`);
+    }
+    if (options.out === undefined) {
+        if (options.json)
+            return ok(`${JSON.stringify(rows, null, 2)}\n`);
+        if (rows.length === 0)
+            return ok(`${colors.dim}(no attachments)${colors.reset}\n`);
+        const width = Math.max(...rows.map((r) => r.name.length));
+        const lines = rows.map((r) => `${r.name.padEnd(width)}  ${colors.dim}${r.type} · ${humanSize(r.size)} · ${r.id}${colors.reset}`);
+        return ok(`${lines.join("\n")}\n`);
+    }
+    const io = options.io;
+    if (!io)
+        return fail("attachments --out needs a local disk (use the sfora CLI)");
+    await io.mkdir(options.out);
+    const taken = new Set();
+    const written = [];
+    const problems = [];
+    for (const row of rows) {
+        if (row.size > ATTACHMENT_MAX_BYTES) {
+            problems.push(`${row.name}: too large to download (${humanSize(row.size)}; the limit is ${humanSize(ATTACHMENT_MAX_BYTES)})`);
+            continue;
+        }
+        let got;
+        try {
+            got = await client.downloadAttachment(fsPath, row.id);
+        }
+        catch (error) {
+            problems.push(`${row.name}: ${apiMessage(error)}`);
+            continue;
+        }
+        const wrong = mismatch(row, got);
+        if (wrong) {
+            problems.push(`${row.name}: not written — ${wrong}`);
+            continue;
+        }
+        const path = io.join(options.out, safeAttachmentName(row.name, row.id, taken));
+        await io.writeFile(path, got.bytes);
+        written.push({ ...row, path });
+    }
+    const stdout = options.json
+        ? `${JSON.stringify(written, null, 2)}\n`
+        : written.map((w) => `${w.path}\n`).join("");
+    if (problems.length) {
+        return fail(problems.map((p) => `${colors.red}error:${colors.reset} ${p}`).join("\n"), stdout);
+    }
+    return ok(stdout);
+}
+/** The two tools both MCP servers list, so their schemas cannot drift. */
+export const ATTACHMENT_TOOLS = [
+    {
+        name: "attachments",
+        description: "List the files attached to a post (screenshots, documents). Pass the post's path, e.g. /projects/web/posts/2026-10-06-errors.md. Returns JSON rows { id, name, type, size }; fetch one with the `attachment` tool.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "The post's absolute path under /projects/<slug>/posts/ (or drafts/)." },
+            },
+            required: ["path"],
+        },
+    },
+    {
+        name: "attachment",
+        description: "Fetch one attachment of a post by id (from the `attachments` tool). Images come back as image content you can look at; text files as text; other files as a description only.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "The post's absolute path." },
+                id: { type: "string", description: "The attachment id from the `attachments` list." },
+            },
+            required: ["path", "id"],
+        },
+    },
+];
+export const isAttachmentTool = (name) => name === "attachments" || name === "attachment";
+/**
+ * The largest image the MCP fetch returns as image content: 3 MB. Base64
+ * makes it ~4 MB of JSON, which fits the hosted route's 4.5 MB response
+ * limit (a Vercel function), and it is under the 5 MB a Claude image may
+ * be. Larger images are metadata plus a pointer to `attachments --out`.
+ */
+export const MCP_IMAGE_MAX_BYTES = 3 * 1024 * 1024;
+/** How much of a text file the MCP fetch inlines: 256 KB, decoded as UTF-8; the rest is cut with a note. */
+export const MCP_TEXT_MAX_BYTES = 256 * 1024;
+// Exactly these are inlined as text. Everything else — SVG and HTML
+// included, which are markup a client might render — is metadata only.
+const TEXT_TYPES = new Set(["text/plain", "text/markdown", "text/csv", "application/json"]);
+// The image types vision clients accept.
+const IMAGE_TYPES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
+function base64(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    }
+    return btoa(binary);
+}
+/**
+ * Answer an MCP call to `attachments` (no id) or `attachment` (with one).
+ * Errors are results with `isError`, never throws: the servers return them
+ * as tool output the agent can read and act on.
+ */
+export async function attachmentToolResult(client, args) {
+    const error = (text) => ({ content: [{ type: "text", text }], isError: true });
+    const path = typeof args.path === "string" ? args.path.trim() : "";
+    if (!path.startsWith("/"))
+        return error("Pass the post's absolute path, e.g. /projects/web/posts/<file>.md.");
+    try {
+        const rows = await client.listAttachments(path);
+        if (args.id === undefined) {
+            return { content: [{ type: "text", text: JSON.stringify(rows, null, 2) }], isError: false };
+        }
+        const row = rows.find((r) => r.id === args.id);
+        if (!row)
+            return error(`No attachment ${String(args.id)} on ${path}. Its attachments: ${rows.map((r) => r.id).join(", ") || "none"}.`);
+        const label = `${row.name} (${row.type}, ${humanSize(row.size)})`;
+        const type = essence(row.type);
+        const metadataOnly = (why) => ({
+            content: [{ type: "text", text: `${label}: ${why}. Download it with: sfora attachments ${path} --out <dir>` }],
+            isError: false,
+        });
+        // An image is all or nothing; a text file is cut at MCP_TEXT_MAX_BYTES,
+        // so it may be fetched up to the API's own cap.
+        const cap = IMAGE_TYPES.has(type) ? MCP_IMAGE_MAX_BYTES : TEXT_TYPES.has(type) ? ATTACHMENT_MAX_BYTES : 0;
+        if (cap === 0)
+            return metadataOnly("not an image or a plain-text file, so it is not shown here");
+        // The listed size first, so an oversized file is never fetched; the
+        // download is then held to that size exactly (`mismatch`).
+        if (row.size > cap) {
+            return metadataOnly(`larger than the ${humanSize(cap)} this tool returns`);
+        }
+        const got = await client.downloadAttachment(path, row.id);
+        const wrong = mismatch(row, got);
+        if (wrong)
+            return error(`${label}: refused — ${wrong}.`);
+        if (IMAGE_TYPES.has(type)) {
+            return {
+                content: [
+                    { type: "text", text: label },
+                    { type: "image", data: base64(got.bytes), mimeType: type },
+                ],
+                isError: false,
+            };
+        }
+        const cut = got.bytes.byteLength > MCP_TEXT_MAX_BYTES;
+        // `stream: true` holds back a UTF-8 sequence the cut split, rather than
+        // ending the text on a replacement character.
+        const text = new TextDecoder().decode(got.bytes.subarray(0, MCP_TEXT_MAX_BYTES), { stream: cut });
+        const note = cut
+            ? `\n\n[truncated: the first ${humanSize(MCP_TEXT_MAX_BYTES)} of ${humanSize(got.bytes.byteLength)}. The whole file: sfora attachments ${path} --out <dir>]`
+            : "";
+        return {
+            content: [{ type: "text", text: `${label}\n\n${text}${note}` }],
+            isError: false,
+        };
+    }
+    catch (e) {
+        return error(apiMessage(e));
+    }
+}

package/dist/block-commands.d.ts

@@ -83,3 +83,13 @@ export declare function putCommand(client: SforaApiClient, fsPath: string, body:
 export declare function urlCommand(client: SforaApiClient, fsPath: string, options?: {
     json?: boolean;
 }): Promise<CommandOutput>;
+/**
+ * `backlinks <path>` — what links to a doc, post or task (card #682).
+ *
+ * The same rows as the app's "Linked from", scoped to what this member may
+ * read, each with the token to paste. Plain text is one line per source;
+ * `--json` is the door's answer as served.
+ */
+export declare function backlinksCommand(client: SforaApiClient, fsPath: string, options?: {
+    json?: boolean;
+}): Promise<CommandOutput>;

package/dist/block-commands.js

@@ -154,3 +154,31 @@ export async function urlCommand(client, fsPath, options = {}) {
         return fail(`${colors.red}error:${colors.reset} ${apiMessage(error)}`);
     }
 }
+/**
+ * `backlinks <path>` — what links to a doc, post or task (card #682).
+ *
+ * The same rows as the app's "Linked from", scoped to what this member may
+ * read, each with the token to paste. Plain text is one line per source;
+ * `--json` is the door's answer as served.
+ */
+export async function backlinksCommand(client, fsPath, options = {}) {
+    try {
+        const view = await client.readBacklinks(fsPath);
+        client.takeResponseInfo();
+        if (options.json)
+            return ok(`${JSON.stringify(view, null, 2)}\n`);
+        const n = view.backlinks.length;
+        const head = `${view.target.title} — linked from ${n} ${n === 1 ? "place" : "places"}${view.truncated ? " (and more)" : ""}`;
+        const lines = view.backlinks.map((row) => {
+            const where = row.anchors.length
+                ? ` ${colors.dim}${row.anchors.map((a) => `#${a}`).join(" ")}${colors.reset}`
+                : "";
+            const token = row.token ? `  ${colors.dim}${row.token}${colors.reset}` : "";
+            return `  ${row.kind.padEnd(7)} ${row.title}${where}${token}`;
+        });
+        return ok(`${[head, ...lines].join("\n")}\n`);
+    }
+    catch (error) {
+        return fail(`${colors.red}error:${colors.reset} ${apiMessage(error)}`);
+    }
+}

package/dist/chat.d.ts

@@ -90,6 +90,21 @@ export declare function renderChatMessage(msg: ChatMessage, now: number): string
  * capitalization is a display rule, and this line is for a program.
  */
 export declare function chatMessageJson(msg: ChatMessage): string;
+/**
+ * What `sfora chat <room>` does with the flags it got and the stdin it has.
+ *
+ * `-m` sends; `--follow` tails. Otherwise a terminal gets the interactive
+ * room (history, then type to talk), and anything else (an agent harness, a
+ * pipe, cron) gets the history and an exit. Without that last rule a
+ * non-TTY stdin held the process open waiting for EOF, and every line that
+ * did arrive on it was SENT to the room: reading must never post.
+ */
+export type ChatMode = "send" | "follow" | "read" | "interactive";
+export declare function chatMode(opts: {
+    message?: string;
+    follow?: boolean;
+    stdinIsTty: boolean;
+}): ChatMode;
 /** `sfora rooms` — one row per room; unjoined rows carry their join hint. */
 export declare function renderRoomList(rooms: Room[]): string;
 /** Everything the tail loop needs from the outside world. */

package/dist/chat.js

@@ -214,6 +214,13 @@ export function chatMessageJson(msg) {
         ...(msg.sentVia ? { sentVia: msg.sentVia } : {}),
     });
 }
+export function chatMode(opts) {
+    if (opts.message !== undefined)
+        return "send";
+    if (opts.follow)
+        return "follow";
+    return opts.stdinIsTty ? "interactive" : "read";
+}
 /** `sfora rooms` — one row per room; unjoined rows carry their join hint. */
 export function renderRoomList(rooms) {
     if (rooms.length === 0)

package/dist/cli-args.d.ts

@@ -7,6 +7,8 @@
  */
 export interface CliArgs {
     skillsTarget?: string;
+    harness?: string;
+    dryRun: boolean;
     skillVersion?: number;
     expectedVersion?: number;
     expectedRevision?: number;
@@ -40,5 +42,10 @@ export interface CliArgs {
     option: string[];
     target?: string;
     room?: string;
+    stop: boolean;
+    out?: string;
+    webhookUrl?: string;
+    events?: string;
+    clear: boolean;
 }
 export declare function parseArgs(argv: string[]): CliArgs;

package/dist/cli-args.js

@@ -6,7 +6,7 @@
  * process — argv in, a parsed shape out.
  */
 export function parseArgs(argv) {
-    const args = { rest: [], cwd: "/", mcp: false, help: false, draft: false, json: false, local: false, cloud: false, self: false, waitFlag: false, follow: false, awaitReply: false, option: [] };
+    const args = { rest: [], cwd: "/", mcp: false, help: false, draft: false, json: false, local: false, cloud: false, self: false, waitFlag: false, follow: false, awaitReply: false, option: [], stop: false, clear: false, dryRun: false };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === "--mcp")
@@ -15,6 +15,14 @@ export function parseArgs(argv) {
             args.help = true;
         else if (a === "--skills-target")
             args.skillsTarget = argv[++i];
+        else if (a.startsWith("--skills-target="))
+            args.skillsTarget = a.slice("--skills-target=".length);
+        else if (a === "--harness")
+            args.harness = argv[++i];
+        else if (a.startsWith("--harness="))
+            args.harness = a.slice("--harness=".length);
+        else if (a === "--dry-run")
+            args.dryRun = true;
         else if (a === "--version")
             args.skillVersion = Number(argv[++i]);
         else if (a === "--expected-version")
@@ -99,6 +107,8 @@ export function parseArgs(argv) {
             args.limit = Number.parseInt(a.slice("--limit=".length), 10);
         else if (a === "--follow")
             args.follow = true;
+        else if (a === "--stop")
+            args.stop = true;
         else if (a === "--await-reply")
             args.awaitReply = true;
         else if (a === "--timeout")
@@ -120,6 +130,16 @@ export function parseArgs(argv) {
             args.target = argv[++i];
         else if (a.startsWith("--for="))
             args.target = a.slice("--for=".length);
+        else if (a === "--out")
+            args.out = argv[++i];
+        else if (a.startsWith("--out="))
+            args.out = a.slice("--out=".length);
+        else if (a === "--events")
+            args.events = argv[++i];
+        else if (a.startsWith("--events="))
+            args.events = a.slice("--events=".length);
+        else if (a === "--clear")
+            args.clear = true;
         else if (a === "--room")
             args.room = argv[++i];
         else if (a.startsWith("--room="))
@@ -131,5 +151,12 @@ export function parseArgs(argv) {
                 args.rest.push(a);
         }
     }
+    // `sfora agent webhook <name> --url …`: the spec's --url is the WEBHOOK's
+    // address. It must not also become the API base (that would send the call
+    // to the receiver), so it moves; the API base comes from SFORA_URL/config.
+    if (args.command === "agent" && args.rest[0] === "webhook" && args.url !== undefined) {
+        args.webhookUrl = args.url;
+        args.url = undefined;
+    }
     return args;
 }

package/dist/cli.d.ts

@@ -6,4 +6,15 @@
  *   SFORA_API_KEY=sk_… SFORA_URL=http://localhost:2222 sfora --org test
  *   sfora --mcp        # MCP stdio server for Claude/Cursor
  */
-export {};
+/**
+ * The whole CLI for one argv (what follows `sfora`). Exported so a harness can
+ * drive the real command table in-process; the bin below calls it with
+ * `process.argv.slice(2)`.
+ */
+export declare function runCli(argv: string[]): Promise<void>;
+/**
+ * True when this module is the process entry point. Compared through realpath:
+ * npm's bin shim and `npx` reach dist/cli.js through symlinks, and those must
+ * still run; an `import` of this module (a test, a harness) must not.
+ */
+export declare function isEntryPoint(entry?: string | undefined, self?: string): boolean;