sfora-cli 0.15.0 → 0.17.0

package/README.md

@@ -400,12 +400,30 @@ Reads outside `projects/<slug>/(posts|drafts)`, `inbox/mentions.md`, and
 `me/api-key` return `ENOENT`; writes outside the post/draft dirs return `EACCES`.
 ```
 
+## Attachments — `sfora attachments`
+
+A post's screenshots and files are listed in its frontmatter by `cat`, as one JSON
+line: `attachments: [{"id","name","type","size"}]`. To get the files:
+
+```bash
+sfora attachments /projects/acme/posts/2026-10-06-errors.md               # list them
+sfora attachments /projects/acme/posts/2026-10-06-errors.md --out ./shots # write them
+```
+
+`--out` writes each file under its own name (only the last path segment is
+kept, and clashes become `shot-2.png`). It checks each file's type and size
+against the list and prints one local path per line, so an agent can open the
+images. A file over 20 MB, or one that doesn't match the list, is skipped with a
+line on stderr, and the command exits 1. Inside the shell, `attachments <post>`
+lists only. Over MCP, the `attachments` and `attachment` tools return images as
+image content.
+
 ## macOS and shared local operations
 
 The desktop app and npm CLI use the same Node-only `sfora-cli/local-core`
 operations. `sfora desktop path/to/file.md` opens a local file in the installed
 Sfora macOS app. `sfora open` continues to open Sfora web URLs. npm installation
-still requires Node 20+; the desktop distribution bundles its own CLI runtime.
+still requires Node 22.13+; the desktop distribution bundles its own CLI runtime.
 Both read the existing `~/.sfora/config.json` profiles. Config writes are atomic
 and process-locked; no account is required for local files or local skill scans.
 
@@ -466,3 +484,64 @@ changes appear here only after publication; use `skills push` or the project
 workbench to change a bundle. Cloud installations record both the immutable
 bundle hash and numeric `sourceVersion`; resolving “latest” pins that version
 before downloading so concurrent publications cannot mix provenance and bytes.
+
+
+### Persistent local skill inventory
+
+Requires Node 22.13 or later. Desktop and CLI share a private SQLite catalogue at `~/.sfora/skills/catalog.sqlite`. Skill names and content hashes are not identity; separate local copies remain separate until explicitly linked.
+
+```sh
+sfora skills roots add ~/.my-skills "My skills"
+sfora skills roots add-project ~/Developer/my-project "My project"
+sfora skills roots --json
+sfora skills inventory --json
+sfora skills roots remove <root-id>
+```
+
+Registered roots and local identities survive restart. Removing a root only removes tracking. Missing or inaccessible skills retain last-known metadata and an unavailable state. `skills scan --json` retains its array result; `skills inventory --json` includes scan warnings. SQLite handles concurrent clients and transaction rollback. Do not edit or delete the catalogue to rebuild observations. Explicit cloud bindings and read-only transfer previews share this catalogue. Transfer execution and recovery remain separate mission increments.
+
+
+### Explicit cloud bindings and transfer previews
+
+```sh
+sfora skills bind <location-id> <cloud-name> --project my-project
+sfora skills bindings --json
+sfora skills status <binding-id> --json
+sfora skills plan <binding-id> push --json
+sfora skills plan <binding-id> pull --json
+sfora skills relocate <location-id> /new/skill-folder
+```
+
+Take the location ID from `skills inventory`. Linking verifies the authenticated member, deployment, organization, project and cloud skill ID. Names are lookup hints. A same-name replacement cannot silently take over a binding. Relocation preserves identity after an explicitly chosen folder move; register the destination discovery root first.
+
+Explicit adoption of equal, verified published and local content establishes a baseline. Differing content starts with an unknown baseline, or preserves an existing confirmed baseline. Status compares fresh local bytes and a pinned published cloud revision against that baseline. It distinguishes synchronized, local changed, remote changed, conflict, missing and unavailable content. An unavailable cloud request exits with an error and never reports synchronization.
+
+Plans contain exact IDs, local and remote hashes, published version, draft revision and per-file byte/mode metadata. They perform no writes. Unknown baselines, conflicts, existing cloud drafts and unverified local ownership block automatic replacement. CLI previews verify ownership against both the installation receipt and the current filesystem object. A replaced link, file or locally edited copy is never treated as an unchanged managed directory. Reviewed pushes can be executed through the journal below. Recovery for local pull/install mutations and migration of the older transfer commands remain tracked by #470 and #472.
+
+The first write upgrades catalogue schema 1 to 2 transactionally after making a private SQLite-consistent `.v1-<id>.sqlite` backup beside the catalogue. Read-only inspection can read schema 1 without upgrading it. Older clients fail closed after an upgrade; update the desktop app and CLI together. Keep the backup until the updated clients have been verified.
+
+
+### Guarded pushes and recovery
+
+```sh
+sfora skills plan <binding-id> push --json > push-plan.json
+sfora skills queue push-plan.json
+sfora skills apply <operation-id>
+sfora skills operations --json
+sfora skills recover <operation-id>
+sfora skills cancel <unstarted-operation-id>
+sfora skills plan-install <cloud-name> --project my-project --skills-target /existing/parent
+```
+
+`apply push-plan.json` queues and starts a push in one command. A reviewed plan is rechecked against current local content, the explicit binding, published version and draft revision. The server must advertise identity-checked writes; the client refuses to apply against an older server. Existing cloud drafts and changed review tokens stop the operation.
+
+The private `~/.sfora/skills/operations.sqlite` journal commits intent before requests and reserves the qualified cloud target across upload/publication. A live worker cannot be recovered by another process. Recover an interrupted worker's operation before starting another operation on its target. Lost responses produce a durable `needs-attention` outcome. Recovery checks whether the exact intended next draft or publication landed before retrying, and a separate confirmation receipt covers interruption during the local baseline commit. Completed operations are not republished. Cancelling is supported only before work starts; it does not pretend to undo remote effects.
+
+`plan-install` produces a read-only preview for a new, empty destination and blocks occupied destinations. Pull and installation previews can be queued and applied through the same journal. Local updates preserve the previous directory in an operation-specific backup; recovery verifies ownership and staged content before continuing, and preserves external edits. Backups and staged snapshots remain available for inspection. An interruption between creating a destination and recording its owner requires inspection rather than guessing ownership. The older `push`, `pull` and `install` commands retain their existing behavior; use `plan`/`apply` for binding-aware update safety. Use `skills apply-batch ids.json` or `skills recover-batch ids.json` with a JSON array of operation IDs. Outcomes are retained per item and completed work is not replayed. Ctrl-C stops after the current item and cancels unstarted items. In the macOS app, Skills → Transfers reviews the same device-wide queue before running or recovering selected plans.
+
+The desktop keeps a cached local skill inventory and watches registered/agent folders. Known file changes re-read only affected skills; new paths and periodic reconciliation repair missed events. Refresh requests a full reconciliation. Removed or inaccessible folders keep their stable identity and last known metadata. Watchers are hints, not authority for transfer planning, which always rechecks current files.
+
+
+In the macOS app, **On this Mac → Push to Sfora / Update local copy** opens a project chooser and a **Review changes** dialog. Published cloud skills offer **Install on this Mac**, followed by the native destination picker and the same review. No CLI plan file is needed. Opening a review creates no binding or queued operation; confirmation rechecks current content and records the durable transfer. Matching unlinked copies can be explicitly linked. Different unlinked copies remain blocked rather than receiving an invented baseline.
+
+A first publication continues into the existing project draft editor. After successful publication, the original local copy is linked only if its files still match the published version. A failed link does not turn a successful publication into a failed result. Transfers remains the history/recovery view, including work queued from the CLI.

package/dist/agent-webhook.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `sfora agent webhook <name> --url <address> --events <a,b> | --clear`
+ * (card #811, the CLI follow-up). Sets an agent's webhook with YOUR key, under
+ * the same rule as Settings → Agents: the agent's owner or a workspace
+ * owner/admin. An agent's key is refused by the server (an agent never sets a
+ * webhook). Pure: a client in, the text and the exit code out.
+ */
+import type { SforaApiClient } from "./api-client.js";
+import type { CommandOutput } from "./block-commands.js";
+/** Every event the webhook fan-out emits; the server's list (convex/lib/webhookEvents.ts). */
+export declare const WEBHOOK_EVENTS: readonly ["message.created", "mention", "post.created", "post.commented"];
+export declare const AGENT_WEBHOOK_USAGE = "usage: sfora agent webhook <name> [--url <https://\u2026>] [--events <a,b>] | --clear [--json]";
+type WebhookClient = Pick<SforaApiClient, "setAgentWebhook">;
+export declare function agentWebhookCommand(client: WebhookClient, rest: string[], opts: {
+    webhookUrl?: string;
+    events?: string;
+    clear?: boolean;
+    json?: boolean;
+}): Promise<CommandOutput>;
+export {};

package/dist/agent-webhook.js

@@ -0,0 +1,42 @@
+/** Every event the webhook fan-out emits; the server's list (convex/lib/webhookEvents.ts). */
+export const WEBHOOK_EVENTS = ["message.created", "mention", "post.created", "post.commented"];
+export const AGENT_WEBHOOK_USAGE = "usage: sfora agent webhook <name> [--url <https://…>] [--events <a,b>] | --clear [--json]";
+export async function agentWebhookCommand(client, rest, opts) {
+    const fail = (message, exitCode = 1) => ({ stdout: "", stderr: `${message}\n`, exitCode });
+    const [sub, name] = rest;
+    if (sub !== "webhook" || !name)
+        return fail(AGENT_WEBHOOK_USAGE, 2);
+    if (opts.clear && (opts.webhookUrl !== undefined || opts.events !== undefined)) {
+        return fail("--clear removes the webhook; give it alone", 2);
+    }
+    if (!opts.clear && opts.webhookUrl === undefined && opts.events === undefined) {
+        return fail(`nothing to change — give --url, --events or --clear\n${AGENT_WEBHOOK_USAGE}`, 2);
+    }
+    let events;
+    if (opts.events !== undefined) {
+        events = opts.events.split(",").map((e) => e.trim()).filter(Boolean);
+        const unknown = events.filter((e) => !WEBHOOK_EVENTS.includes(e));
+        if (unknown.length)
+            return fail(`unknown event ${unknown.join(", ")} — use one of: ${WEBHOOK_EVENTS.join(", ")}`, 2);
+    }
+    let result;
+    try {
+        result = await client.setAgentWebhook(name, opts.clear ? { clear: true } : { ...(opts.webhookUrl !== undefined ? { url: opts.webhookUrl } : {}), ...(events ? { events } : {}) });
+    }
+    catch (e) {
+        // The server's refusal as it said it: not a person, not yours, no such agent.
+        return fail(e instanceof Error ? e.message : String(e));
+    }
+    if (opts.json)
+        return { stdout: `${JSON.stringify(result, null, 2)}\n`, stderr: "", exitCode: 0 };
+    const evts = result.events.length ? result.events.join(", ") : "none";
+    return {
+        stdout: result.webhookUrl
+            ? `✓ ${result.agent}'s webhook: ${result.webhookUrl} · events: ${evts}\n`
+            : opts.clear
+                ? `✓ ${result.agent}'s webhook removed\n`
+                : `✓ ${result.agent} has no webhook URL yet · events: ${evts} — add one with --url\n`,
+        stderr: "",
+        exitCode: 0,
+    };
+}

package/dist/api-client.d.ts

@@ -311,6 +311,13 @@ export interface SforaApiConfig {
      * The server sanitizes it and ignores it where it means nothing.
      */
     clientLabel?: string;
+    /**
+     * How the client is on the line (card #815, D11). The CLI's MCP server and
+     * the hosted /mcp route pass "mcp", sent as `X-Sfora-Transport: mcp` beside
+     * the client label, so usage can tell an MCP tool call from a terminal
+     * command. Omitted, no header is sent — the CLI's own requests.
+     */
+    transport?: "mcp";
 }
 /** Non-2xx response from the fs API. Carries the HTTP status + machine code so SforaFs can map it to an errno. */
 export declare class SforaApiError extends Error {
@@ -341,6 +348,32 @@ export interface BlockView {
     lang?: string;
 }
 /** `GET …?view=blocks` — the addressable view of a document. */
+/** The `_backlinks` door's answer — see `readBacklinks`. */
+export interface BacklinksView {
+    target: {
+        kind: string;
+        id: string;
+        title: string;
+    };
+    truncated: boolean;
+    backlinks: Array<{
+        kind: string;
+        title: string;
+        token: string | null;
+        url: string | null;
+        anchors: string[];
+    }>;
+}
+/** One file attached to a post — `GET <post>/attachments` (card #822). */
+export interface AttachmentRow {
+    id: string;
+    name: string;
+    /** The media type the uploader's browser reported. */
+    type: string;
+    size: number;
+    width?: number;
+    height?: number;
+}
 export interface BlocksView {
     /** The fs path these blocks are OF — what to GET for the document itself. */
     canonical: string;
@@ -451,6 +484,26 @@ export declare class SforaApiClient {
      * `/v1/fs` URL: the CLI does not build routes.
      */
     readBlocks(fsPath: string): Promise<BlocksView>;
+    /**
+     * `GET <fs path>/_backlinks` — what links to a doc, post or task, as the
+     * agent may see it (card #682): each source with the `[[…]]` token to paste
+     * and the anchors it links to.
+     */
+    readBacklinks(fsPath: string): Promise<BacklinksView>;
+    /**
+     * `GET <post path>/attachments` — the files attached to a post (card #822).
+     * The path is the post's fs path, as for every other door here.
+     */
+    listAttachments(fsPath: string): Promise<AttachmentRow[]>;
+    /**
+     * `GET <post path>/attachments/<id>` — one file's bytes, streamed through the
+     * API with this key (no storage URL is ever handed out). `type` is the
+     * served Content-Type, so a caller can hold it against the listing.
+     */
+    downloadAttachment(fsPath: string, id: string): Promise<{
+        bytes: Uint8Array;
+        type: string;
+    }>;
     /**
      * `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.
@@ -613,6 +666,19 @@ export declare class SforaApiClient {
         joined: boolean;
         already: boolean;
     }>;
+    /**
+     * `PUT /v1/agents/:name/webhook` (card #811) — set or clear an agent's
+     * webhook with a PERSON's key, under the same rule as Settings.
+     */
+    setAgentWebhook(name: string, body: {
+        url?: string;
+        events?: string[];
+        clear?: boolean;
+    }): Promise<{
+        agent: string;
+        webhookUrl: string | null;
+        events: string[];
+    }>;
     /** `GET /api/rooms/:id/messages` — history, newest first (server cap: 100). */
     listRoomMessages(roomId: string, limit?: number): Promise<MessagesPage>;
     /** `POST /api/rooms/:id/messages` with `{ body }` — send markdown. */
@@ -621,6 +687,21 @@ export declare class SforaApiClient {
     client?: string): Promise<{
         messageId: string;
     }>;
+    /**
+     * `POST /api/rooms/:id/typing` with `{ ttlSeconds? }` — say this agent is
+     * working on a reply in the room (card #668). The server clamps the expiry
+     * to 5–120 s (default 30); send again to extend. `{ stop: true }` is the
+     * `DELETE` that ends it; sending a message in the room also ends it.
+     * Agents only, in a room they are a member of.
+     */
+    typing(roomId: string, opts?: {
+        ttlSeconds?: number;
+    } | {
+        stop: true;
+    }): Promise<{
+        typing: boolean;
+        until?: number;
+    }>;
     /**
      * `POST /api/presence` with `{ roomId?, client? }` — one presence beat.
      *
@@ -652,6 +733,22 @@ export declare class SforaApiClient {
     }): Promise<{
         askId: string;
     }>;
+    /**
+     * `POST /api/asks/:askId/claim` — take an open ask atomically. A 409 means
+     * someone else holds it (their name is in the message) or it is no longer
+     * open; the server owns that race, this only carries the answer.
+     */
+    claimAsk(askId: string): Promise<{
+        ok: boolean;
+        askId: string;
+        state: string;
+    }>;
+    /** `POST /api/asks/:askId/resolve` with `{ resolution? }` — report it done. */
+    resolveAsk(askId: string, resolution?: string): Promise<{
+        ok: boolean;
+        askId: string;
+        state: string;
+    }>;
     /** `GET /v1/fs/inbox/mentions.md` — markdown summary of unread mentions. */
     readInbox(): Promise<string>;
     /** `GET /v1/fs/me/api-key` — text identity (no key material). */

package/dist/api-client.js

@@ -96,6 +96,7 @@ export class SforaApiClient {
     #apiKey;
     #actAs;
     #clientLabel;
+    #transport;
     /**
      * What the LAST response said about itself, beyond the data it carried.
      *
@@ -116,6 +117,7 @@ export class SforaApiClient {
         this.#apiKey = config.apiKey;
         this.#actAs = config.actAs;
         this.#clientLabel = config.clientLabel;
+        this.#transport = config.transport;
     }
     /** What the last response said about itself, consumed. */
     takeResponseInfo() {
@@ -158,6 +160,8 @@ export class SforaApiClient {
             headers["X-Sfora-Act-As"] = this.#actAs;
         if (this.#clientLabel)
             headers["X-Sfora-Client"] = this.#clientLabel;
+        if (this.#transport)
+            headers["X-Sfora-Transport"] = this.#transport;
         if (body !== undefined)
             headers["Content-Type"] = contentType;
         let res;
@@ -310,6 +314,34 @@ export class SforaApiClient {
     async readBlocks(fsPath) {
         return this.#json(`${fsRequestPath(fsPath)}?view=blocks`);
     }
+    /**
+     * `GET <fs path>/_backlinks` — what links to a doc, post or task, as the
+     * agent may see it (card #682): each source with the `[[…]]` token to paste
+     * and the anchors it links to.
+     */
+    async readBacklinks(fsPath) {
+        return this.#json(`${fsRequestPath(fsPath.replace(/\/+$/, ""))}/_backlinks`);
+    }
+    /**
+     * `GET <post path>/attachments` — the files attached to a post (card #822).
+     * The path is the post's fs path, as for every other door here.
+     */
+    async listAttachments(fsPath) {
+        const data = await this.#json(`${fsRequestPath(fsPath.replace(/\/+$/, ""))}/attachments`);
+        return data.attachments;
+    }
+    /**
+     * `GET <post path>/attachments/<id>` — one file's bytes, streamed through the
+     * API with this key (no storage URL is ever handed out). `type` is the
+     * served Content-Type, so a caller can hold it against the listing.
+     */
+    async downloadAttachment(fsPath, id) {
+        const res = await this.#request("GET", `${fsRequestPath(fsPath.replace(/\/+$/, ""))}/attachments/${encodeURIComponent(id)}`);
+        return {
+            bytes: new Uint8Array(await res.arrayBuffer()),
+            type: res.headers.get("content-type") ?? "",
+        };
+    }
     /**
      * `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.
@@ -614,6 +646,14 @@ export class SforaApiClient {
         const res = await this.#request("POST", `/api/rooms/${encodeURIComponent(roomId)}/join`);
         return this.#jsonFrom(res);
     }
+    /**
+     * `PUT /v1/agents/:name/webhook` (card #811) — set or clear an agent's
+     * webhook with a PERSON's key, under the same rule as Settings.
+     */
+    async setAgentWebhook(name, body) {
+        const res = await this.#request("PUT", `/v1/agents/${encodeURIComponent(name)}/webhook`, JSON.stringify(body), undefined, "application/json");
+        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}`);
@@ -627,6 +667,20 @@ export class SforaApiClient {
         const res = await this.#request("POST", `/api/rooms/${encodeURIComponent(roomId)}/messages`, JSON.stringify({ body, client }), undefined, "application/json");
         return this.#jsonFrom(res);
     }
+    /**
+     * `POST /api/rooms/:id/typing` with `{ ttlSeconds? }` — say this agent is
+     * working on a reply in the room (card #668). The server clamps the expiry
+     * to 5–120 s (default 30); send again to extend. `{ stop: true }` is the
+     * `DELETE` that ends it; sending a message in the room also ends it.
+     * Agents only, in a room they are a member of.
+     */
+    async typing(roomId, opts = {}) {
+        const path = `/api/rooms/${encodeURIComponent(roomId)}/typing`;
+        const res = "stop" in opts
+            ? await this.#request("DELETE", path)
+            : await this.#request("POST", path, JSON.stringify(opts.ttlSeconds !== undefined ? { ttlSeconds: opts.ttlSeconds } : {}), undefined, "application/json");
+        return this.#jsonFrom(res);
+    }
     /**
      * `POST /api/presence` with `{ roomId?, client? }` — one presence beat.
      *
@@ -658,6 +712,20 @@ export class SforaApiClient {
         const res = await this.#request("POST", "/api/asks", JSON.stringify(body), undefined, "application/json");
         return this.#jsonFrom(res);
     }
+    /**
+     * `POST /api/asks/:askId/claim` — take an open ask atomically. A 409 means
+     * someone else holds it (their name is in the message) or it is no longer
+     * open; the server owns that race, this only carries the answer.
+     */
+    async claimAsk(askId) {
+        const res = await this.#request("POST", `/api/asks/${encodeURIComponent(askId)}/claim`, "{}", undefined, "application/json");
+        return this.#jsonFrom(res);
+    }
+    /** `POST /api/asks/:askId/resolve` with `{ resolution? }` — report it done. */
+    async resolveAsk(askId, resolution) {
+        const res = await this.#request("POST", `/api/asks/${encodeURIComponent(askId)}/resolve`, JSON.stringify(resolution !== undefined ? { resolution } : {}), 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/ask.d.ts

@@ -73,3 +73,54 @@ export type AskWaitResult = {
  * and other asks' traffic pass through silently.
  */
 export declare function askWaitLoop(deps: AskWaitDeps, options: AskWaitOptions): Promise<AskWaitResult>;
+export declare const ASK_ACTIONS: readonly ["claim", "resolve"];
+export type AskAction = (typeof ASK_ACTIONS)[number];
+export declare const ASK_ACTION_USAGE = "usage: sfora ask claim <ask-id> | sfora ask resolve <ask-id> [-m \"<resolution>\"] [--json]";
+/**
+ * `sfora ask claim <id>` / `sfora ask resolve <id>`, or `null` for a question.
+ *
+ * The same verb creates asks, so the subcommand is taken only when it cannot
+ * be a question: the first word is exactly `claim` or `resolve`, exactly one
+ * more word follows (the id), and no `--option` was given (a claim never has
+ * options, a question to pick from always does). `sfora ask "claim the
+ * domain?"` arrives as ONE word and stays a question; so does
+ * `sfora ask claim the domain`.
+ */
+export declare function parseAskAction(rest: string[], options?: string[]): {
+    action: AskAction;
+    askId: string;
+} | null;
+/**
+ * The words of a refusal. The `/api/asks` doors answer `{ "error": "<words>" }`
+ * (convex/http.ts errorResponse), which the client keeps as the raw body; this
+ * reads the words back out so the terminal says "Already claimed by Ada", not
+ * a JSON blob.
+ */
+export declare function refusalText(e: unknown): string;
+type AskActionClient = {
+    claimAsk(askId: string): Promise<{
+        askId?: string;
+        state?: string;
+    }>;
+    resolveAsk(askId: string, resolution?: string): Promise<{
+        askId?: string;
+        state?: string;
+    }>;
+};
+/**
+ * Claim or resolve one ask and say what happened in one line (or JSON).
+ *
+ * The server owns every rule: a 409 says someone else holds the ask (with
+ * their name), or that it is a question only a human answers, or that it is
+ * no longer open; a 403 says only the claimant may resolve it. Those come back
+ * as they were said, on stderr, exit 1.
+ */
+export declare function askActionCommand(client: AskActionClient, action: AskAction, askId: string, opts?: {
+    resolution?: string;
+    json?: boolean;
+}): Promise<{
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}>;
+export {};

package/dist/ask.js

@@ -117,3 +117,73 @@ export async function askWaitLoop(deps, options) {
     }
     return { outcome: "stopped" };
 }
+// ─── Claim and resolve (the coordination half) ───────────────────────
+export const ASK_ACTIONS = ["claim", "resolve"];
+export const ASK_ACTION_USAGE = 'usage: sfora ask claim <ask-id> | sfora ask resolve <ask-id> [-m "<resolution>"] [--json]';
+/**
+ * `sfora ask claim <id>` / `sfora ask resolve <id>`, or `null` for a question.
+ *
+ * The same verb creates asks, so the subcommand is taken only when it cannot
+ * be a question: the first word is exactly `claim` or `resolve`, exactly one
+ * more word follows (the id), and no `--option` was given (a claim never has
+ * options, a question to pick from always does). `sfora ask "claim the
+ * domain?"` arrives as ONE word and stays a question; so does
+ * `sfora ask claim the domain`.
+ */
+export function parseAskAction(rest, options = []) {
+    if (rest.length !== 2 || options.length > 0)
+        return null;
+    const [word, askId] = rest;
+    if (!ASK_ACTIONS.includes(word))
+        return null;
+    if (!askId.trim())
+        return null;
+    return { action: word, askId: askId.trim() };
+}
+/**
+ * The words of a refusal. The `/api/asks` doors answer `{ "error": "<words>" }`
+ * (convex/http.ts errorResponse), which the client keeps as the raw body; this
+ * reads the words back out so the terminal says "Already claimed by Ada", not
+ * a JSON blob.
+ */
+export function refusalText(e) {
+    const data = e?.data;
+    if (data && typeof data.message !== "string" && typeof data.error === "string")
+        return data.error;
+    return e instanceof Error ? e.message : String(e);
+}
+/**
+ * Claim or resolve one ask and say what happened in one line (or JSON).
+ *
+ * The server owns every rule: a 409 says someone else holds the ask (with
+ * their name), or that it is a question only a human answers, or that it is
+ * no longer open; a 403 says only the claimant may resolve it. Those come back
+ * as they were said, on stderr, exit 1.
+ */
+export async function askActionCommand(client, action, askId, opts = {}) {
+    if (action === "claim" && opts.resolution !== undefined) {
+        return { stdout: "", stderr: `-m is for resolve; claim takes only the id\n${ASK_ACTION_USAGE}\n`, exitCode: 2 };
+    }
+    let result;
+    try {
+        result =
+            action === "claim"
+                ? await client.claimAsk(askId)
+                : await client.resolveAsk(askId, opts.resolution);
+    }
+    catch (e) {
+        return { stdout: "", stderr: `could not ${action} ask ${askId}: ${refusalText(e)}\n`, exitCode: 1 };
+    }
+    const state = result.state ?? (action === "claim" ? "claimed" : "resolved");
+    if (opts.json) {
+        return {
+            stdout: `${JSON.stringify({ askId, state, ...(action === "resolve" && opts.resolution !== undefined ? { resolution: opts.resolution } : {}) })}\n`,
+            stderr: "",
+            exitCode: 0,
+        };
+    }
+    const line = action === "claim"
+        ? `✓ Claimed ask ${askId} — it's yours; run \`sfora ask resolve ${askId} -m "…"\` when done`
+        : `✓ Resolved ask ${askId}${opts.resolution ? ` · ${opts.resolution}` : ""}`;
+    return { stdout: `${line}\n`, stderr: "", exitCode: 0 };
+}

package/dist/attachments-node.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The disk `sfora attachments --out` writes to — the Node half of
+ * attachments.ts, kept apart so that module stays importable where there is
+ * no local filesystem (the hosted MCP route).
+ */
+import type { AttachmentIo } from "./attachments.js";
+export declare const nodeAttachmentIo: AttachmentIo;

package/dist/attachments-node.js

@@ -0,0 +1,15 @@
+/**
+ * The disk `sfora attachments --out` writes to — the Node half of
+ * attachments.ts, kept apart so that module stays importable where there is
+ * no local filesystem (the hosted MCP route).
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+export const nodeAttachmentIo = {
+    mkdir: async (dir) => {
+        await mkdir(dir, { recursive: true });
+    },
+    writeFile: (path, bytes) => writeFile(path, bytes),
+    // Absolute, so the printed path opens from anywhere.
+    join: (dir, name) => join(resolve(dir), name),
+};