sfora-cli 0.15.0 → 0.17.0

package/dist/cli.js

@@ -8,22 +8,28 @@
  */
 import { CLI_VERSION } from "./version.js";
 import { runSkillsCommand, SKILLS_HELP } from "./skills-command.js";
+import { agentWebhookCommand } from "./agent-webhook.js";
 import * as readline from "node:readline";
 import { spawn } from "node:child_process";
 import { realpath, readFile as readLocalFile } from "node:fs/promises";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { basename } from "node:path";
 import { taskUploadFilename } from "./format/taskUploadFilename.js";
 import { createSforaShell, createLocalShell, SforaApiError, } from "./index.js";
-import { askWaitLoop, reshapeCandidatesError, validateAskOptions, } from "./ask.js";
+import { askActionCommand, askWaitLoop, parseAskAction, reshapeCandidatesError, validateAskOptions, } from "./ask.js";
 import { openerCommand } from "./opener.js";
-import { blocksCommand, presenceNotice, putCommand, } from "./block-commands.js";
+import { blocksCommand, backlinksCommand, presenceNotice, putCommand, } from "./block-commands.js";
 import { colors, ndjson, presenceRecords, renderPresence, renderWriteEffect, urlLine, PRESENCE_NOTE, } from "./render.js";
-import { parseWatchTarget, watchLoop } from "./watch.js";
+import { editingPresence, myBlockIn, parseWatchTarget, watchLoop } from "./watch.js";
 import { LocalWorkspace, initWorkspace, findWorkspace, migrateWorkspaceStages, } from "./local/workspace.js";
 import { runMcpServer } from "./mcp-server.js";
 import { readConfig, updateConfig, resolveSettings, upsertProfile, effectiveProfiles, profileKey, DEFAULT_URL, } from "./config.js";
 import { parseArgs } from "./cli-args.js";
-import { awaitReplyLoop, capitalizeName, chatMessageJson, chatTailLoop, detectClient, renderChatMessage, renderRoomList, resolveRoomRef, roomSlug, } from "./chat.js";
+import { awaitReplyLoop, capitalizeName, chatMessageJson, chatMode, chatTailLoop, detectClient, renderChatMessage, renderRoomList, resolveRoomRef, roomSlug, } from "./chat.js";
+import { typingCommand } from "./typing.js";
+import { attachmentsCommand } from "./attachments.js";
+import { nodeAttachmentIo } from "./attachments-node.js";
 const HELP = `sfora — the CLI for your sfora workspace
 
 Get started (no account needed):
@@ -57,6 +63,9 @@ Browse & read:
   sfora me                            Show who you're signed in as
   sfora ls [path]                     List a path (default /projects)
   sfora cat <path>                    Print a file's markdown
+  sfora attachments <post>            List a post's attachments (screenshots, files)
+  sfora attachments <post> --out <dir>
+                                      Download them into <dir>; prints each path
   sfora url <path>                    Print the web URL for a path
   sfora open <path>                   Open that URL in your browser
   sfora desktop <file.md>             Open local Markdown in Sfora for macOS
@@ -69,7 +78,9 @@ Chat:
   sfora rooms                         List rooms (● joined · ○ open to join)
   sfora join <room>                   Join an open room
   sfora chat <room> [-n <count>]      Read the room, then type to talk —
-                                      new messages stream in live
+                                      new messages stream in live. Without
+                                      a terminal (agents, pipes) it prints
+                                      the history and exits (--json: NDJSON)
   sfora chat <room> -m "text"         Send one message and exit (for scripts
                                       and agents)
   sfora chat <room> --follow          Tail the room without a prompt — for
@@ -78,6 +89,10 @@ Chat:
                                       Send, then wait for the next message
                                       back and print it — --timeout <secs>
                                       stops waiting (exit code 2)
+  sfora typing <room> [--for <secs>]  Agents: show the room you're working on
+                                      a reply (30s by default, 5–120; run
+                                      again to extend). It ends when you send
+                                      there, or with --stop
 
   Chat shows others what's on the line: the CLI reports itself in presence,
   and a coding agent is named automatically (Claude Code, Codex, Cursor and
@@ -97,13 +112,23 @@ Ask a human:
                                       the choice (give secs to stop waiting)
   Add --project <slug> or --room <room> to say where it belongs; --json for
   scripts (--wait prints a second JSON line when the answer lands).
+  sfora ask claim <ask-id>            Take an open ask before working on it —
+                                      fails if someone else holds it
+  sfora ask resolve <ask-id> [-m "<resolution>"]
+                                      Report the ask done (the claimant, or
+                                      an admin). Ids: sfora cat
+                                      /projects/<slug>/asks.md
 
 Write, and watch others write:
   sfora blocks <path>                 List a document's addressable blocks
   sfora put <path> <file.md>          Write a file (add --block <id> for one block)
   sfora put <path> --block <id> -     …or pipe the block's markdown on stdin
   sfora watch <path-or-project>       Stream write pings (add --json for NDJSON)
+  sfora watch <doc> --block <id>      …and show as editing that block: prints
+                                      who is here, again when that changes,
+                                      and leaves on exit (ids: sfora blocks)
   sfora where [name]                  Who's in which document right now
+  sfora backlinks <path>              What links to a doc, post or task
 
   Every write prints what it did — "changed" (with how many block ids
   survived) or "no change". Watching and writing make you visible in the
@@ -111,6 +136,13 @@ Write, and watch others write:
   asking never puts you in a document.
 
 Agents & config:
+  sfora agent webhook <name> --url <https://…> --events <a,b>
+                                      Set an agent's webhook with your key (its
+                                      owner, or a workspace owner/admin). Events:
+                                      message.created, mention, post.created,
+                                      post.commented. --clear removes it. Here
+                                      --url is the webhook's address; set the
+                                      API's with SFORA_URL
   sfora --mcp [--org <slug>]          Run as an MCP server (for agents)
   sfora mcp-config                    Print an MCP config snippet to paste
   sfora contexts                      List saved deployment+org keys (● = active)
@@ -129,10 +161,12 @@ const SHELL_HELP = `${colors.bold}sfora shell${colors.reset} ${colors.dim}— yo
 Standard tools work against your workspace:
   ls   cat   grep   find   head   tail   wc   sed   awk   echo   cd   pwd
 
-${colors.dim}And three of sfora's own${colors.reset}
+${colors.dim}And five of sfora's own${colors.reset}
   blocks <path>              the blocks a --block write can aim at
   put <path> [file|-]        write a file (--block <id> writes one block)
   url <path>                 where it lives on the web
+  backlinks <path>           what links to it, with the token to paste
+  attachments <post>         the files attached to a post
 
 ${colors.dim}Where things live${colors.reset}
   /projects                          your projects
@@ -366,6 +400,8 @@ const VERBS = new Set([
     "open",
     "blocks",
     "put",
+    "backlinks",
+    "attachments",
     "watch",
     "where",
     "post",
@@ -382,7 +418,9 @@ const VERBS = new Set([
     "rooms",
     "join",
     "chat",
+    "typing",
     "ask",
+    "agent",
 ]);
 async function runVerb(args, fs, client) {
     const ok = (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`);
@@ -471,6 +509,21 @@ async function runVerb(args, fs, client) {
             throw new Error("usage: sfora blocks <path> [--json]");
         return writeCommandOutput(await blocksCommand(client, args.rest[0], { json: args.json }));
     }
+    if (args.command === "backlinks") {
+        if (!args.rest[0])
+            throw new Error("usage: sfora backlinks <path> [--json]");
+        return writeCommandOutput(await backlinksCommand(client, args.rest[0], { json: args.json }));
+    }
+    if (args.command === "attachments") {
+        if (!args.rest[0]) {
+            throw new Error("usage: sfora attachments <post> [--out <dir>] [--json]");
+        }
+        return writeCommandOutput(await attachmentsCommand(client, args.rest[0], {
+            out: args.out,
+            json: args.json,
+            io: nodeAttachmentIo,
+        }));
+    }
     if (args.command === "put") {
         const path = args.rest[0];
         if (!path) {
@@ -489,7 +542,7 @@ async function runVerb(args, fs, client) {
     }
     if (args.command === "watch") {
         if (!args.rest[0]) {
-            throw new Error("usage: sfora watch <path-or-project> [--json] [--self] [--wait <secs>]");
+            throw new Error("usage: sfora watch <path-or-project> [--block <id>] [--json] [--self] [--wait <secs>]");
         }
         return runWatch(args, client, args.rest[0]);
     }
@@ -546,9 +599,55 @@ async function runVerb(args, fs, client) {
         }
         return runChat(args, client);
     }
+    if (args.command === "typing") {
+        const out = await typingCommand(client, args.rest[0], {
+            // `--for` is parsed once for `ask --for <member>`; here it is seconds.
+            seconds: args.target,
+            stop: args.stop,
+            json: args.json,
+        });
+        if (out.stdout)
+            process.stdout.write(out.stdout);
+        if (out.stderr)
+            process.stderr.write(out.stderr);
+        if (out.exitCode !== 0)
+            process.exitCode = out.exitCode;
+        return;
+    }
     if (args.command === "ask") {
+        // `ask claim <id>` / `ask resolve <id>` only when it cannot be a question
+        // (see parseAskAction); everything else creates an ask, as it always has.
+        const action = parseAskAction(args.rest, args.option);
+        if (action) {
+            const out = await askActionCommand(client, action.action, action.askId, {
+                resolution: args.message,
+                json: args.json,
+            });
+            if (out.stdout)
+                process.stdout.write(out.stdout);
+            if (out.stderr)
+                process.stderr.write(out.stderr);
+            if (out.exitCode !== 0)
+                process.exitCode = out.exitCode;
+            return;
+        }
         return runAsk(args, client);
     }
+    if (args.command === "agent") {
+        const out = await agentWebhookCommand(client, args.rest, {
+            webhookUrl: args.webhookUrl,
+            events: args.events,
+            clear: args.clear,
+            json: args.json,
+        });
+        if (out.stdout)
+            process.stdout.write(out.stdout);
+        if (out.stderr)
+            process.stderr.write(out.stderr);
+        if (out.exitCode !== 0)
+            process.exitCode = out.exitCode;
+        return;
+    }
     if (args.command === "me" || args.command === "whoami") {
         const text = (await client.readMe()).trim();
         if (args.json) {
@@ -712,7 +811,7 @@ async function runWatch(args, client, target) {
     // Presence, if this path has a roster. Asked rather than inferred: a `422`
     // is the server saying "no roster here", and posts and cards get one.
     let canBeat = parsed.kind === "path";
-    const beat = async ({ leave }) => {
+    let beat = async ({ leave }) => {
         if (!canBeat || parsed.kind !== "path")
             return;
         const roster = await client.declarePresence(parsed.path, {
@@ -722,6 +821,25 @@ async function runWatch(args, client, target) {
         if (roster === null)
             canBeat = false;
     };
+    // `--block <id>`: the editor of one block, not a viewer of the document.
+    // Declared once up front so a path with no roster, or an id that names no
+    // block, is a clear refusal instead of a watch that never shows up.
+    if (args.block !== undefined) {
+        if (parsed.kind !== "path") {
+            throw new Error(`--block needs a document path, not a project — sfora watch /projects/${parsed.slug}/docs/<file>.md --block <id>`);
+        }
+        const path = parsed.path;
+        const editing = editingPresence({
+            declare: (o) => client.declarePresence(path, o),
+            // A read, not a declare: where the server holds MY claim now, so the
+            // watch follows a block whose id an edit changed.
+            whereAmI: async () => myBlockIn(await client.listPresence("self"), { docId, path }),
+            write: (text) => process.stdout.write(text),
+            warn: (text) => process.stderr.write(`${colors.dim}${text}${colors.reset}\n`),
+        }, { path, block: args.block, json: args.json });
+        await editing.start();
+        beat = editing.beat;
+    }
     // Start at NOW, not at the retained backlog: `watch` is a live channel, and
     // opening one should not replay a day of history nobody was waiting for.
     const since = Date.now();
@@ -754,7 +872,7 @@ async function runWatch(args, client, target) {
     process.on("SIGINT", onSignal);
     process.on("SIGTERM", onSignal);
     if (!args.json) {
-        process.stderr.write(`${colors.dim}watching ${parsed.kind === "project" ? `project ${parsed.slug}` : parsed.path}${args.self ? "" : " (not your own writes)"} — ^C to stop${colors.reset}\n`);
+        process.stderr.write(`${colors.dim}watching ${parsed.kind === "project" ? `project ${parsed.slug}` : parsed.path}${args.block !== undefined ? `, editing block ${args.block}` : ""}${args.self ? "" : " (not your own writes)"} — ^C to stop${colors.reset}\n`);
     }
     try {
         await watchLoop({
@@ -868,6 +986,20 @@ async function runChat(args, client) {
     const seen = new Set(seeded.map((m) => m._id));
     const pendingSendBodies = new Set();
     const messages = seeded.slice(-limit);
+    // No terminal on stdin (an agent, a pipe): read the room and exit. Opening
+    // the prompt there would wait on stdin for EOF and send what it read.
+    if (chatMode({ message: args.message, follow: args.follow, stdinIsTty: isTty }) === "read") {
+        if (args.json) {
+            for (const msg of messages)
+                console.log(chatMessageJson(msg));
+            return;
+        }
+        if (messages.length === 0)
+            console.log(`${colors.dim}(no messages yet)${colors.reset}`);
+        for (const msg of messages)
+            console.log(renderChatMessage(msg, Date.now()));
+        return;
+    }
     if (messages.length === 0) {
         console.log(`${colors.dim}(no messages yet)${colors.reset}`);
     }
@@ -1476,12 +1608,17 @@ ${colors.dim}Try${colors.reset}
 Everything is git-versioned with your repo. ${colors.dim}Connect a team later with${colors.reset} ${colors.cyan}sfora login${colors.reset}.
 Type ${colors.cyan}exit${colors.reset} to quit.
 `;
-async function main() {
-    if (["--version", "-v"].includes(process.argv[2] ?? "")) {
+/**
+ * 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 async function runCli(argv) {
+    if (["--version", "-v"].includes(argv[0] ?? "")) {
         console.log(`sfora-cli ${CLI_VERSION}`);
         return;
     }
-    const args = parseArgs(process.argv.slice(2));
+    const args = parseArgs(argv);
     if (args.help) {
         process.stdout.write(HELP + "\n" + SKILLS_HELP);
         return;
@@ -1537,7 +1674,8 @@ async function main() {
     }
     // Local mode — a .sfora/ workspace in (an ancestor of) cwd wins, unless the
     // user explicitly targets the cloud (--cloud / --url / --org / --key / --bot).
-    const cloudIntent = args.cloud || !!args.url || !!args.org || !!args.key || !!args.bot;
+    // `agent …` is cloud-only: agents and their webhooks live in a workspace.
+    const cloudIntent = args.cloud || !!args.url || !!args.org || !!args.key || !!args.bot || args.command === "agent";
     const localRoot = cloudIntent
         ? undefined
         : await findWorkspace(process.cwd());
@@ -1674,7 +1812,7 @@ client) {
         "sed", "awk", "sort", "uniq", "mkdir", "rm", "mv", "cp", "touch", "help",
         "exit",
         // sfora's own, registered on the cloud shell (see `sforaShellCommands`).
-        "blocks", "put", "url",
+        "blocks", "put", "url", "backlinks", "attachments",
     ];
     async function completePath(token) {
         const slash = token.lastIndexOf("/");
@@ -1754,8 +1892,37 @@ client) {
     if (isTty)
         console.log("");
 }
-main().catch((e) => {
-    const message = e instanceof Error ? e.message : String(e);
-    process.stderr.write(`${colors.red}fatal:${colors.reset} ${message}\n`);
-    process.exit(1);
-});
+/**
+ * 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 function isEntryPoint(entry = process.argv[1], self = import.meta.url) {
+    if (!entry)
+        return false;
+    let me;
+    try {
+        me = realpathSync(fileURLToPath(self));
+    }
+    catch {
+        return false;
+    }
+    // `node dist/cli` (no extension) names the same file as `node dist/cli.js`.
+    for (const candidate of [entry, `${entry}.js`]) {
+        try {
+            if (realpathSync(candidate) === me)
+                return true;
+        }
+        catch {
+            // not this spelling
+        }
+    }
+    return false;
+}
+if (isEntryPoint()) {
+    runCli(process.argv.slice(2)).catch((e) => {
+        const message = e instanceof Error ? e.message : String(e);
+        process.stderr.write(`${colors.red}fatal:${colors.reset} ${message}\n`);
+        process.exit(1);
+    });
+}

package/dist/format/linkUrls.d.ts

@@ -0,0 +1,2 @@
+export declare function looksLikeEntityUrl(url: string): boolean;
+export declare function scanBodyLinkUrls(body: string): string[];

package/dist/format/linkUrls.js

@@ -0,0 +1,48 @@
+// GENERATED by scripts/sync-format.mjs from packages/markdown/src — DO NOT EDIT.
+// Edit packages/markdown/src and re-run the sync (any sfora-cli build does it).
+// Markdown links that can name a workspace entity — card #682 (fault B6).
+//
+// ONE scanner for both sides: the graph (`convex/references.ts`, through the
+// `convex/lib/linkUrls.ts` shim) indexes exactly the URLs the reader asks
+// `references.resolveTokens` about, so a path link cannot be live in one and
+// dead in the other.
+import { codeSpanMask, fencedRegions, isEscaped, lineText, } from "./lint/lintSource.js";
+// Markdown links (`[text](url)`, not images) whose URL could name a workspace
+// entity: an fs path (`/projects/<slug>/docs/<file>.md`, `./other.md`) or an
+// app URL (`/org/<slug>/notes/<id>`, …). Same code geometry as the token
+// scanner, so a link quoted in code is prose, not a link. Card #682 (B6):
+// these used to be dead hrefs and no edge.
+const MD_LINK_RE = /(!?)\[(?:[^\]\\]|\\.)*\]\(\s*<?([^\s)>]+)>?(?:\s+"[^"]*")?\s*\)/g;
+const ENTITY_URL_RE = /^(?:https?:\/\/[^/]+)?\/org\/[^/]+\/(?:notes|posts|projects\/[^/]+\/(?:board\?detail=card:|pulls\/))/;
+export function looksLikeEntityUrl(url) {
+    const bare = url.split("#")[0];
+    if (ENTITY_URL_RE.test(bare))
+        return true;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(bare))
+        return false; // http:, mailto:, …
+    return /\.md$/i.test(bare.split("?")[0]);
+}
+export function scanBodyLinkUrls(body) {
+    const lines = body.split("\n");
+    const fenced = new Set();
+    for (const region of fencedRegions(lines)) {
+        for (let i = region.open; i <= region.close; i++)
+            fenced.add(i);
+    }
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        if (fenced.has(i))
+            continue;
+        const line = lineText(lines, i);
+        const mask = codeSpanMask(line);
+        MD_LINK_RE.lastIndex = 0;
+        let m;
+        while ((m = MD_LINK_RE.exec(line)) !== null) {
+            if (m[1] === "!" || mask[m.index] || isEscaped(line, m.index))
+                continue;
+            if (looksLikeEntityUrl(m[2]))
+                out.push(m[2]);
+        }
+    }
+    return out;
+}

package/dist/format/postMarkdown.d.ts

@@ -17,6 +17,17 @@ export interface MarkdownAuthor {
     name: string;
     type: "human" | "agent";
 }
+/**
+ * A file attached to the post (card #822). Listed in the frontmatter so an
+ * agent reading the post knows it is there; the bytes are fetched from
+ * `<post path>/attachments/<id>`, never inlined.
+ */
+export interface MarkdownAttachment {
+    id: string;
+    name: string;
+    type: string;
+    size: number;
+}
 export interface MarkdownProject {
     _id: string;
     name: string;
@@ -28,5 +39,5 @@ export interface ParsedMarkdownPost {
     frontmatter: Record<string, string | string[]>;
 }
 export declare function mdFilename(post: MarkdownPostInput): string;
-export declare function postToMarkdown(post: MarkdownPostInput, author: MarkdownAuthor | null, project: MarkdownProject | null, commentsCount: number): string;
+export declare function postToMarkdown(post: MarkdownPostInput, author: MarkdownAuthor | null, project: MarkdownProject | null, commentsCount: number, attachments?: MarkdownAttachment[]): string;
 export declare function parseMarkdownPost(md: string): ParsedMarkdownPost;

package/dist/format/postMarkdown.js

@@ -29,7 +29,7 @@ export function mdFilename(post) {
     return `${datePart(post)}-${slugify(post.title)}.md`;
 }
 // ─── Serialize + parse ─────────────────────────────────────────────
-export function postToMarkdown(post, author, project, commentsCount) {
+export function postToMarkdown(post, author, project, commentsCount, attachments = []) {
     const { text, names } = renderMentions(post.body);
     const fm = serializeFrontmatter([
         ["id", post._id],
@@ -47,7 +47,14 @@ export function postToMarkdown(post, author, project, commentsCount) {
         ["comments", String(commentsCount)],
         ["mentions", names],
     ]);
-    return buildDocument(fm, post.title, text);
+    // One line of JSON — valid YAML flow, and a JSON.parse away for an agent.
+    // The tiny frontmatter YAML holds only flat string arrays, so objects ride
+    // as JSON rather than stretching it. Omitted when there are none, so a post
+    // without files reads byte-for-byte as it always has.
+    const attachmentLine = attachments.length
+        ? `\nattachments: ${JSON.stringify(attachments.map(({ id, name, type, size }) => ({ id, name, type, size })))}`
+        : "";
+    return buildDocument(fm + attachmentLine, post.title, text);
 }
 // Parse a markdown file back to post fields (shared document parser).
 export function parseMarkdownPost(md) {

package/dist/index.d.ts

@@ -7,7 +7,7 @@
  * workspace. The CLI also exposes first-class verbs (post/task/doc) and an MCP
  * server so agents operate sfora natively.
  */
-import { Bash, ReadWriteFs } from "just-bash";
+import { Bash, ReadWriteFs, type CommandName } from "just-bash";
 import { SforaApiClient } from "./api-client.js";
 import { SforaFs } from "./SforaFs.js";
 import { type PresenceNotice } from "./block-commands.js";
@@ -31,13 +31,32 @@ export interface CreateSforaShellOptions {
      * that made them — the CLI passes `detectClient(process.env, --client)`.
      */
     clientLabel?: string;
+    /** "mcp" from an MCP server (card #815, D11): sent as `X-Sfora-Transport`. */
+    transport?: "mcp";
     /**
      * The run's "you are visible" latch. Pass one when something OUTSIDE this
      * shell can print the note too — the CLI does, after any line that wrote —
      * so the two share a single "once". Omitted, the shell owns its own.
      */
     presence?: PresenceNotice;
+    /**
+     * Restrict the shell to these built-in commands. Omitted, every built-in is
+     * available — the CLI and local shells run on the user's own machine with
+     * the user's own key. The hosted /mcp route passes
+     * {@link hostedShellCommands} (card #628).
+     */
+    commands?: CommandName[];
 }
+/**
+ * Built-ins the HOSTED shell does not offer (card #628). `yq` is the only path
+ * to the TOML parser just-bash 3.0.1 inlines (smol-toml <= 1.6.1,
+ * GHSA-7w5x-hrqm-74c2: a malformed document hangs the parser). The fixed
+ * just-bash (3.4.x) cannot be adopted yet: its redirections write every target
+ * empty first, which the fs API rejects, so the parser is removed instead.
+ */
+export declare const HOSTED_SHELL_EXCLUDED: readonly string[];
+/** Every built-in this just-bash registers, minus {@link HOSTED_SHELL_EXCLUDED}. */
+export declare function hostedShellCommands(): CommandName[];
 export interface SforaShell {
     bash: Bash;
     fs: SforaFs;
@@ -66,6 +85,7 @@ export interface LocalShell {
  */
 export declare function createLocalShell(root: string, cwd?: string): LocalShell;
 export { SforaFs } from "./SforaFs.js";
+export { cloudToolDescription } from "./mcp-description.js";
 export { LocalWorkspace, initWorkspace, findWorkspace, WORKSPACE_DIR, type TaskEntry, type TaskWriteResult, } from "./local/workspace.js";
 export * from "./format/index.js";
 export { SforaApiClient, SforaApiError, blockConflictFrom, writeEffectFrom, type SforaApiConfig, type Project, type Entry, type PostKind, type WriteResult, type WriteOptions, type WriteEffect, type RebindCounts, type ResponseInfo, type BlockView, type BlocksView, type BlockConflict, type BlockSummary, type AgentEvent, type AgentEventsPage, type DocPresence, type DocPresenceMember, } from "./api-client.js";
@@ -73,6 +93,8 @@ export { WEB_URL_HEADER, fsRequestPath, webUrlFromResponse, } from "./web-url.js
 export { openerCommand, type OpenerCommand } from "./opener.js";
 export { blocksCommand, putCommand, urlCommand, resolveFsPath, presenceNotice, type CommandOutput, type PresenceNotice, } from "./block-commands.js";
 export { sforaShellCommands, parseShellArgs } from "./shell-commands.js";
+export { ATTACHMENT_MAX_BYTES, ATTACHMENT_TOOLS, attachmentToolResult, attachmentsCommand, isAttachmentTool, safeAttachmentName, type AttachmentIo, type McpContent, type McpToolResult, } from "./attachments.js";
+export type { AttachmentRow } from "./api-client.js";
 export { watchLoop, parseWatchTarget, MAX_BACKOFF_MS, type WatchDeps, type WatchOptions, type WatchTarget, } from "./watch.js";
 export { renderPing, renderBlocks, renderBlockConflict, renderWriteEffect, ndjson, type DocPing, } from "./render.js";
 export { KNOWN_CLIENTS, detectClient, sanitizeClientSlug, chatMessageJson, chatTailLoop, awaitReplyLoop, type ChatTailDeps, type ChatTailOptions, type AwaitReplyDeps, type AwaitReplyOptions, type AwaitReplyResult, } from "./chat.js";

package/dist/index.js

@@ -7,17 +7,30 @@
  * workspace. The CLI also exposes first-class verbs (post/task/doc) and an MCP
  * server so agents operate sfora natively.
  */
-import { Bash, ReadWriteFs } from "just-bash";
+import { Bash, ReadWriteFs, getCommandNames } from "just-bash";
 import { SforaApiClient } from "./api-client.js";
 import { SforaFs } from "./SforaFs.js";
 import { sforaShellCommands } from "./shell-commands.js";
 import { presenceNotice } from "./block-commands.js";
+/**
+ * Built-ins the HOSTED shell does not offer (card #628). `yq` is the only path
+ * to the TOML parser just-bash 3.0.1 inlines (smol-toml <= 1.6.1,
+ * GHSA-7w5x-hrqm-74c2: a malformed document hangs the parser). The fixed
+ * just-bash (3.4.x) cannot be adopted yet: its redirections write every target
+ * empty first, which the fs API rejects, so the parser is removed instead.
+ */
+export const HOSTED_SHELL_EXCLUDED = ["yq"];
+/** Every built-in this just-bash registers, minus {@link HOSTED_SHELL_EXCLUDED}. */
+export function hostedShellCommands() {
+    return getCommandNames().filter((name) => !HOSTED_SHELL_EXCLUDED.includes(name));
+}
 export function createSforaShell(options) {
     const client = new SforaApiClient({
         baseUrl: options.baseUrl,
         apiKey: options.apiKey,
         actAs: options.actAs,
         clientLabel: options.clientLabel,
+        transport: options.transport,
     });
     const presence = options.presence ?? presenceNotice();
     const fs = new SforaFs(client);
@@ -34,6 +47,7 @@ export function createSforaShell(options) {
         // rather than special-cased in the REPL so they compose like every other
         // command: `blocks x.md | grep heading`, `sed … | put x.md --block <id>`.
         customCommands: sforaShellCommands(client, presence),
+        ...(options.commands ? { commands: options.commands } : {}),
     });
     return { bash, fs, client, presence };
 }
@@ -49,6 +63,7 @@ export function createLocalShell(root, cwd = "/") {
     return { bash, fs };
 }
 export { SforaFs } from "./SforaFs.js";
+export { cloudToolDescription } from "./mcp-description.js";
 export { LocalWorkspace, initWorkspace, findWorkspace, WORKSPACE_DIR, } from "./local/workspace.js";
 export * from "./format/index.js";
 export { SforaApiClient, SforaApiError, blockConflictFrom, writeEffectFrom, } from "./api-client.js";
@@ -56,6 +71,7 @@ export { WEB_URL_HEADER, fsRequestPath, webUrlFromResponse, } from "./web-url.js
 export { openerCommand } from "./opener.js";
 export { blocksCommand, putCommand, urlCommand, resolveFsPath, presenceNotice, } from "./block-commands.js";
 export { sforaShellCommands, parseShellArgs } from "./shell-commands.js";
+export { ATTACHMENT_MAX_BYTES, ATTACHMENT_TOOLS, attachmentToolResult, attachmentsCommand, isAttachmentTool, safeAttachmentName, } from "./attachments.js";
 export { watchLoop, parseWatchTarget, MAX_BACKOFF_MS, } from "./watch.js";
 export { renderPing, renderBlocks, renderBlockConflict, renderWriteEffect, ndjson, } from "./render.js";
 export { KNOWN_CLIENTS, detectClient, sanitizeClientSlug, chatMessageJson, chatTailLoop, awaitReplyLoop, } from "./chat.js";

package/dist/local-core/files.d.ts

@@ -17,7 +17,7 @@ export interface LocalMarkdownSnapshot {
 export declare function readLocalMarkdown(path: string): Promise<LocalMarkdownSnapshot>;
 export declare function saveLocalMarkdown(path: string, content: string, expectedRevision: string): Promise<LocalMarkdownSnapshot>;
 /** Save As creates a new path only. Replacing an existing file requires its current revision. */
-export declare function atomicCreate(path: string, content: string | Uint8Array): Promise<string>;
+export declare function atomicCreate(path: string, content: string | Uint8Array, mode?: number): Promise<string>;
 export declare function saveNewLocalMarkdown(path: string, content: string): Promise<LocalMarkdownSnapshot>;
 /** Watch the parent so atomic replacement by another editor remains observable. */
 export declare function watchLocalMarkdown(path: string, onChange: () => void): FSWatcher;

package/dist/local-core/files.js

@@ -82,11 +82,11 @@ export async function saveLocalMarkdown(path, content, expectedRevision) {
     });
 }
 /** Save As creates a new path only. Replacing an existing file requires its current revision. */
-export async function atomicCreate(path, content) {
+export async function atomicCreate(path, content, mode = 0o600) {
     const destination = join(await realpath(dirname(resolve(path))), basename(path));
     const temporary = `${destination}.${randomUUID()}.tmp`;
     try {
-        await atomicWrite(temporary, content);
+        await atomicWrite(temporary, content, mode);
         // Hard link publishes atomically and fails EEXIST instead of overwriting a raced save.
         await link(temporary, destination);
     }

package/dist/local-core/index.d.ts

@@ -2,3 +2,15 @@
  * Renderers must obtain native dialog grants; never expose these as arbitrary IPC paths. */
 export * from "./files.js";
 export * from "./skills.js";
+export * from "./skill-domain.js";
+export * from "./skill-discovery.js";
+export * from "./skill-store.js";
+export * from "./skill-service.js";
+export * from "./skill-sync.js";
+export * from "./skill-operations.js";
+export { SKILL_AGENT_ADAPTERS, projectSkillSources } from "./skill-adapters.js";
+export type { SkillAgentAdapter } from "./skill-adapters.js";
+export * from "./skill-local-executor.js";
+export * from "./skill-executor.js";
+export { SkillIndex } from './skill-index.js';
+export { SkillReviewService, type SkillReview } from './skill-review.js';

package/dist/local-core/index.js

@@ -2,3 +2,14 @@
  * Renderers must obtain native dialog grants; never expose these as arbitrary IPC paths. */
 export * from "./files.js";
 export * from "./skills.js";
+export * from "./skill-domain.js";
+export * from "./skill-discovery.js";
+export * from "./skill-store.js";
+export * from "./skill-service.js";
+export * from "./skill-sync.js";
+export * from "./skill-operations.js";
+export { SKILL_AGENT_ADAPTERS, projectSkillSources } from "./skill-adapters.js";
+export * from "./skill-local-executor.js";
+export * from "./skill-executor.js";
+export { SkillIndex } from './skill-index.js';
+export { SkillReviewService } from './skill-review.js';