sfora-cli 0.10.0 → 0.12.0

package/dist/format/textStats.js

@@ -0,0 +1,80 @@
+// 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).
+/**
+ * Document statistics for editor footers.
+ *
+ * Word counting splits with `Intl.Segmenter` where it exists: whitespace
+ * splitting reports one word for an entire Chinese or Japanese sentence, which
+ * is the bug open-knowledge's `selection-stats.ts` fixes the same way. The
+ * fallback keeps that property by counting CJK ideographs individually.
+ *
+ * Token count is a chars/4 heuristic, not a tokenizer — always render it with a
+ * leading `~` so it never reads as exact.
+ */
+const CJK = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u;
+const CJK_GLOBAL = new RegExp(CJK.source, "gu");
+const LATIN_WORD = /[\p{L}\p{N}][\p{L}\p{N}'’_-]*/gu;
+const CHARS_PER_TOKEN = 4;
+let segmenter;
+function wordSegmenter() {
+    if (segmenter !== undefined)
+        return segmenter;
+    const ctor = Intl
+        .Segmenter;
+    segmenter = ctor ? new ctor(undefined, { granularity: "word" }) : null;
+    return segmenter;
+}
+/**
+ * Words in a chunk of Markdown. Punctuation-only segments (`#`, `*`, `|`) are
+ * not word-like, so Markdown syntax drops out without a stripping pass.
+ */
+export function countWords(text) {
+    if (text.trim().length === 0)
+        return 0;
+    const prose = withoutUrls(text);
+    const seg = wordSegmenter();
+    if (seg) {
+        let words = 0;
+        let previousWasWord = false;
+        let pendingJoiner = false;
+        for (const part of seg.segment(prose)) {
+            if (part.isWordLike) {
+                // UAX #29 breaks on a hyphen, so "well-known" arrives as two segments.
+                // Rejoin it: people read a hyphenated compound as one word.
+                if (!(pendingJoiner && previousWasWord))
+                    words++;
+                previousWasWord = true;
+                pendingJoiner = false;
+                continue;
+            }
+            pendingJoiner = part.segment === "-" || part.segment === "_";
+            if (!pendingJoiner)
+                previousWasWord = false;
+        }
+        return words;
+    }
+    const cjk = prose.match(CJK_GLOBAL)?.length ?? 0;
+    let latin = 0;
+    for (const match of prose.matchAll(LATIN_WORD)) {
+        if (!CJK.test(match[0]))
+            latin++;
+    }
+    return latin + cjk;
+}
+/**
+ * Link destinations are addresses, not prose — a document of links should not
+ * report a word count inflated by its own URLs.
+ */
+function withoutUrls(text) {
+    return text.replace(/\]\([^)\n]*\)/g, "]").replace(/<?\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, " ");
+}
+/** Rough token count: ~4 characters per token, the usual English-prose ratio. */
+export function estimateTokens(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return 0;
+    return Math.max(1, Math.round(trimmed.length / CHARS_PER_TOKEN));
+}
+export function documentStats(text) {
+    return { words: countWords(text), tokens: estimateTokens(text) };
+}

package/dist/format/wikiLinks.d.ts

@@ -1,19 +1,78 @@
 export type WikiLinkKind = "post" | "card" | "note" | "pr";
 export declare const WIKI_LINK_PREFIXES: ReadonlyArray<readonly [prefix: string, kind: WikiLinkKind]>;
 export declare const WIKI_LINK_PREFIX_FOR: Readonly<Record<WikiLinkKind, string>>;
+export declare const WIKI_EMBED_MARKER = "!";
+export declare const BLOCK_ANCHOR_MARKER = "^";
 export declare function buildWikiLink(kind: WikiLinkKind, id: string, label: string): string;
+export declare function buildWikiEmbed(kind: WikiLinkKind, id: string, label: string): string;
+export declare function cleanWikiTarget(value: string): string;
+export declare function cleanWikiLabel(value: string): string;
+export declare function cleanWikiAnchor(value: string): string;
+/**
+ * Split a target-with-anchor into its two halves, honouring the prefix table.
+ *
+ * The `#` is only a separator after at least one character of the BARE id, and
+ * that is not a nicety — `[[c:#42]]` is the existing "card by number" form
+ * (`parseWikiTarget` yields `{kind:"card", id:"#42"}`). Splitting on the first
+ * `#` anywhere would turn it into a link to the prefix `c:` with an anchor of
+ * `42`, silently unlinking every task referenced by number. So: find the
+ * prefix, then look for a `#` past the first character after it.
+ *
+ * An empty anchor (`[[n:abc#]]`) is NOT an anchor. The trailing `#` stays part
+ * of the target, which resolves to nothing and renders as the muted
+ * unknown-entity text the grammar already gives any unresolvable target —
+ * open-knowledge's tokenizer takes the same position from the other side, by
+ * refusing to close a wiki link on a zero-length anchor at all.
+ */
+export declare function splitWikiAnchor(target: string): {
+    target: string;
+    anchor: string | null;
+};
+/**
+ * The BLOCK id an anchor addresses, or null when the anchor names a heading.
+ *
+ * One character decides it, and the split is done here rather than at each
+ * consumer so "does this token point at a block" has one answer. Three cases
+ * are deliberate:
+ *
+ *   `^k7f3a2cx`  → `"k7f3a2cx"`. The ordinal form of a duplicated block,
+ *                 `^k7f3a2cx.2`, comes back whole — the dot is part of the id
+ *                 (`fingerprintBlocks`), not a fourth separator.
+ *   `Rollout`   → null. A heading, and the reader slugs it as it always has.
+ *   `^`         → null. A marker with nothing after it addresses no block, the
+ *                 same position `splitWikiAnchor` takes on `[[n:abc#]]`: an
+ *                 empty half is not a half. It stays a (meaningless) heading
+ *                 anchor rather than becoming a block id of `""`, because an id
+ *                 nothing can resolve is worse than an anchor that resolves to
+ *                 no heading.
+ *
+ * The cost, stated: a heading whose text genuinely begins with `^` cannot be
+ * addressed as a heading. That is inherent in a one-character prefix and it is
+ * Obsidian's trade too; the alternative — a separate segment — would have every
+ * consumer of `anchor` learn a new shape to gain a case nobody writes.
+ */
+export declare function blockAnchorId(anchor: string | null | undefined): string | null;
+/** The anchor bytes that address `blockId` — the inverse of `blockAnchorId`. */
+export declare function blockAnchor(blockId: string): string;
+/** Re-join a target and anchor into the bytes that go between the brackets. */
+export declare function joinWikiAnchor(target: string, anchor: string | null | undefined): string;
 export interface WikiLink {
     kind: WikiLinkKind;
     id: string;
     target: string;
+    anchor: string | null;
+    blockId: string | null;
     label: string;
     hasLabel: boolean;
+    embed: boolean;
 }
 export declare function wikiLinkPattern(): RegExp;
-export declare function parseWikiToken(raw: string): WikiLink;
+export declare function wikiTokenPattern(): RegExp;
+export declare function parseWikiToken(raw: string, embed?: boolean): WikiLink;
 export declare function parseWikiTarget(target: string): {
     kind: WikiLinkKind;
     id: string;
 };
 export declare function parseWikiLinks(body: string): WikiLink[];
 export declare function matchWikiToken(text: string): WikiLink | null;
+export declare function matchWikiEmbed(text: string): WikiLink | null;

package/dist/format/wikiLinks.js

@@ -8,7 +8,33 @@
 //   [[c:<cardId>]]          → a task / card  (also accepts `c:#42` / `c:42`)
 //   [[pr:<n>]] / [[gh:<n>]] → a pull request
 //
-// Any form may carry a display label after a pipe: `[[c:42|Fix login]]`.
+// Any form may carry a display label after a pipe: `[[c:42|Fix login]]`, and
+// any form may point INTO its target at a heading, after a hash:
+//
+//   [[n:<noteId>#<heading>]]
+//   [[n:<noteId>#<heading>|Label]]
+//
+// The three segments are ordered — target, then anchor, then label — which is
+// what lets a `#` inside a label stay an ordinary character and a `|` after an
+// anchor still open the label.
+//
+// The anchor has TWO readings, told apart by one character:
+//
+//   [[n:<noteId>#Rollout]]     → a heading, matched through `toAnchorSlug`
+//   [[n:<noteId>#^k7f3a2cx]]    → a BLOCK, matched by its derived fingerprint
+//
+// The `^` is Obsidian's spelling and it is a prefix rather than a separate
+// segment on purpose: a block id and a heading slug are the same KIND of thing
+// — a place inside the target — so they share the anchor position, the anchor
+// splitter, the anchor cleaner and the label rule, and no consumer has to learn
+// a fourth segment to keep up. Card #325, against
+// `docs/research/durable-block-ids-design.md` card 7.
+//
+// A leading `!` turns any of those forms into an EMBED — `![[c:42]]` — which
+// says "show the thing here" rather than "point at it". The bang is the only
+// difference: everything after it is the same three segments, read by the same
+// splitters and written by the same sanitizers, so an embed can never disagree
+// with a link about what a target or an anchor is. Card #298.
 //
 // Pure string transforms — no React, no Convex, no Node. Consumers: the Convex
 // reference indexer (convex/references.ts), the web renderer
@@ -29,29 +55,173 @@ export const WIKI_LINK_PREFIX_FOR = {
     note: "n:",
     pr: "pr:",
 };
+// The one byte that separates an embed from a link, named so no consumer has
+// to spell `"!"` and mean "the embed marker".
+export const WIKI_EMBED_MARKER = "!";
+// The one byte that separates a BLOCK anchor from a heading anchor, named for
+// the same reason. `#^k7f3a2cx` addresses a block by the fingerprint
+// `@sfora/markdown/blockIds` derives from its content; `#Rollout` addresses a
+// heading by its slug.
+export const BLOCK_ANCHOR_MARKER = "^";
 // Build the canonical `[[<prefix><id>|<label>]]` form. The label is sanitized:
 // `[`, `]`, and `|` inside it would break the token grammar.
 export function buildWikiLink(kind, id, label) {
     const clean = label.replace(/[[\]|]/g, " ").trim() || "Untitled";
     return `[[${WIKI_LINK_PREFIX_FOR[kind]}${id}|${clean}]]`;
 }
+// The same token with the embed marker in front. Built by delegating rather
+// than by re-spelling the brackets: an embed is a link with a bang, and the day
+// `buildWikiLink` learns a fourth segment this keeps up for free.
+export function buildWikiEmbed(kind, id, label) {
+    return `${WIKI_EMBED_MARKER}${buildWikiLink(kind, id, label)}`;
+}
+// The two sanitizers that guard the token's own grammar on the WRITE side, and
+// the one place they live. Both halves of `[[target|label]]` pass through one
+// of them, and the two halves are not treated alike:
+//
+//   target  loses `[`, `]`, `|`; newlines and tabs FOLD to a space. Interior
+//           spaces stay — posts and notes resolve by exact title
+//           (`resolveRefToken` in convex/references.ts), so stripping them
+//           turns `[[The card]]` into a reference that can never match.
+//   label   loses the same three characters plus newlines outright. It is
+//           display text, so a fold would invent whitespace the title
+//           never had.
+//
+// Two callers, one spelling: the walker's write path
+// (`editorWalker/toMdast.ts`) and the live paste/typing path
+// (`src/components/editor/extensions/work-link.ts`). They were separate copies
+// until card #255 — the walker's had witnesses and the extension's did not,
+// which is the shape where one copy drifts and nothing says so.
+export function cleanWikiTarget(value) {
+    return value
+        .replace(/[[\]|]/g, "")
+        .replace(/[\r\n\t]+/g, " ")
+        .trim();
+}
+export function cleanWikiLabel(value) {
+    return value.replace(/[[\]|\r\n]/g, "").trim();
+}
+// The anchor's cleaner, and it is a THIRD one rather than a reuse of either
+// above, for a reason worth stating: the anchor is the only segment whose own
+// separator can appear inside it. A `#` surviving into an anchor would give
+// `[[a#b#c]]` two readings, and the split below takes the first `#` — so the
+// write side removes the character the read side would trip over, exactly as
+// `cleanWikiTarget` removes the `|` that would open a label.
+//
+// Otherwise it follows the TARGET, not the label: interior spaces stay, and
+// newlines/tabs fold to a space. An anchor is matched against heading text
+// (`toAnchorSlug` collapses the spaces at resolve time), so `#Open questions`
+// must stay two words rather than becoming `Openquestions`.
+export function cleanWikiAnchor(value) {
+    return value
+        .replace(/[[\]|#]/g, "")
+        .replace(/[\r\n\t]+/g, " ")
+        .trim();
+}
+/**
+ * Split a target-with-anchor into its two halves, honouring the prefix table.
+ *
+ * The `#` is only a separator after at least one character of the BARE id, and
+ * that is not a nicety — `[[c:#42]]` is the existing "card by number" form
+ * (`parseWikiTarget` yields `{kind:"card", id:"#42"}`). Splitting on the first
+ * `#` anywhere would turn it into a link to the prefix `c:` with an anchor of
+ * `42`, silently unlinking every task referenced by number. So: find the
+ * prefix, then look for a `#` past the first character after it.
+ *
+ * An empty anchor (`[[n:abc#]]`) is NOT an anchor. The trailing `#` stays part
+ * of the target, which resolves to nothing and renders as the muted
+ * unknown-entity text the grammar already gives any unresolvable target —
+ * open-knowledge's tokenizer takes the same position from the other side, by
+ * refusing to close a wiki link on a zero-length anchor at all.
+ */
+export function splitWikiAnchor(target) {
+    const prefix = WIKI_LINK_PREFIXES.find(([p]) => target.startsWith(p))?.[0] ?? "";
+    const hash = target.indexOf("#", prefix.length + 1);
+    if (hash < 0)
+        return { target, anchor: null };
+    const anchor = target.slice(hash + 1).trim();
+    if (!anchor)
+        return { target, anchor: null };
+    return { target: target.slice(0, hash).trim(), anchor };
+}
+/**
+ * The BLOCK id an anchor addresses, or null when the anchor names a heading.
+ *
+ * One character decides it, and the split is done here rather than at each
+ * consumer so "does this token point at a block" has one answer. Three cases
+ * are deliberate:
+ *
+ *   `^k7f3a2cx`  → `"k7f3a2cx"`. The ordinal form of a duplicated block,
+ *                 `^k7f3a2cx.2`, comes back whole — the dot is part of the id
+ *                 (`fingerprintBlocks`), not a fourth separator.
+ *   `Rollout`   → null. A heading, and the reader slugs it as it always has.
+ *   `^`         → null. A marker with nothing after it addresses no block, the
+ *                 same position `splitWikiAnchor` takes on `[[n:abc#]]`: an
+ *                 empty half is not a half. It stays a (meaningless) heading
+ *                 anchor rather than becoming a block id of `""`, because an id
+ *                 nothing can resolve is worse than an anchor that resolves to
+ *                 no heading.
+ *
+ * The cost, stated: a heading whose text genuinely begins with `^` cannot be
+ * addressed as a heading. That is inherent in a one-character prefix and it is
+ * Obsidian's trade too; the alternative — a separate segment — would have every
+ * consumer of `anchor` learn a new shape to gain a case nobody writes.
+ */
+export function blockAnchorId(anchor) {
+    if (!anchor || !anchor.startsWith(BLOCK_ANCHOR_MARKER))
+        return null;
+    return anchor.slice(BLOCK_ANCHOR_MARKER.length).trim() || null;
+}
+/** The anchor bytes that address `blockId` — the inverse of `blockAnchorId`. */
+export function blockAnchor(blockId) {
+    return `${BLOCK_ANCHOR_MARKER}${blockId}`;
+}
+/** Re-join a target and anchor into the bytes that go between the brackets. */
+export function joinWikiAnchor(target, anchor) {
+    return anchor ? `${target}#${anchor}` : target;
+}
 // A fresh global matcher each call: a shared /g regex carries `lastIndex`
 // between callers and would silently skip tokens.
+//
+// This one matches the BRACKETS ONLY, bang excluded, and that is load-bearing
+// rather than an oversight. `canonicalizeReferences` (convex/references.ts)
+// rewrites the span this pattern reports, so a span that had swallowed the bang
+// would rewrite an embed into a link on the first canonicalisation pass. Reach
+// for `wikiTokenPattern()` when the bang is part of what you are reading.
 export function wikiLinkPattern() {
     return /\[\[([^\]]+)\]\]/g;
 }
-// Split a token body (the text between `[[` and `]]`) into target + label.
-export function parseWikiToken(raw) {
+// Link and embed together: the marker in group 1, the token body in group 2.
+// The `!` is optional, so every `[[…]]` this finds `wikiLinkPattern()` finds
+// too — the two never disagree about where a token is, only about whether the
+// bang belongs to it.
+export function wikiTokenPattern() {
+    return /(!?)\[\[([^\]]+)\]\]/g;
+}
+// Split a token body (the text between `[[` and `]]`) into target + anchor +
+// label. Order matters: the pipe is found first, so a `#` in a label is just a
+// character; then the anchor is split off what is left.
+//
+// `embed` is passed IN rather than sniffed: the body between the brackets is
+// identical either way, and the caller is the only one holding the bang.
+export function parseWikiToken(raw, embed = false) {
     const pipe = raw.indexOf("|");
-    const target = (pipe >= 0 ? raw.slice(0, pipe) : raw).trim();
+    const written = (pipe >= 0 ? raw.slice(0, pipe) : raw).trim();
     const explicit = pipe >= 0 ? raw.slice(pipe + 1).trim() : "";
+    const { target, anchor } = splitWikiAnchor(written);
     const { kind, id } = parseWikiTarget(target);
     return {
         kind,
         id,
         target,
+        anchor,
+        blockId: blockAnchorId(anchor),
+        // Still the TARGET, not the target-plus-anchor. A label-less
+        // `[[n:abc#Rollout]]` displays the doc's resolved title (or its id), the
+        // same as `[[n:abc]]` does — the anchor is a destination, not a name.
         label: explicit || target,
         hasLabel: explicit.length > 0,
+        embed,
     };
 }
 // Classify a target (prefix included) into its kind + bare identifier.
@@ -63,18 +233,34 @@ export function parseWikiTarget(target) {
     }
     return { kind: "post", id: target };
 }
-// Every `[[…]]` token in a body, in document order, not deduped.
+// Every `[[…]]` and `![[…]]` token in a body, in document order, not deduped.
+//
+// Embeds are INCLUDED, each flagged by its own `embed`. Callers that build the
+// links graph want them: `![[c:42]]` references the card exactly as `[[c:42]]`
+// does, and dropping embeds here would unlink every entity a document shows
+// instead of naming.
 export function parseWikiLinks(body) {
     const out = [];
-    const re = wikiLinkPattern();
+    const re = wikiTokenPattern();
     let m;
-    while ((m = re.exec(body)) !== null)
-        out.push(parseWikiToken(m[1]));
+    while ((m = re.exec(body)) !== null) {
+        out.push(parseWikiToken(m[2], m[1] === WIKI_EMBED_MARKER));
+    }
     return out;
 }
-// Parse a string that must be EXACTLY one token and nothing else — the test
+// Parse a string that must be EXACTLY one LINK and nothing else — the test
 // behind "this whole line is a single link, so unfurl it as a card".
+//
+// Strict about the bang on purpose: an embed on its own line is a different
+// rendering decision (it shows the entity because the author asked, not because
+// the line happened to hold one link), and the two callers of this in the
+// reader would otherwise stop being able to tell them apart.
 export function matchWikiToken(text) {
     const m = /^\[\[([^\]]+)\]\]$/.exec(text.trim());
     return m ? parseWikiToken(m[1]) : null;
 }
+// The same test for an embed: exactly `![[…]]`, nothing else on the line.
+export function matchWikiEmbed(text) {
+    const m = /^!\[\[([^\]]+)\]\]$/.exec(text.trim());
+    return m ? parseWikiToken(m[1], true) : null;
+}

package/dist/index.d.ts

@@ -8,7 +8,9 @@
  * server so agents operate sfora natively.
  */
 import { Bash, ReadWriteFs } from "just-bash";
+import { SforaApiClient } from "./api-client.js";
 import { SforaFs } from "./SforaFs.js";
+import { type PresenceNotice } from "./block-commands.js";
 export interface CreateSforaShellOptions {
     /** Base URL of the sfora deployment, e.g. `http://localhost:2222`. */
     baseUrl: string;
@@ -23,10 +25,27 @@ export interface CreateSforaShellOptions {
     cwd?: string;
     /** Act/post as an owned agent, using this key (sent as `X-Sfora-Act-As`). */
     actAs?: string;
+    /**
+     * 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;
 }
 export interface SforaShell {
     bash: Bash;
     fs: SforaFs;
+    /**
+     * The transport the shell and fs share.
+     *
+     * Exposed so the CLI can read what the LAST request reported about itself —
+     * the page a response named, the effect report a write returned — without
+     * making a second one. `IFileSystem` has nowhere to put either, and a
+     * separately-constructed client would be watching a different conversation.
+     */
+    client: SforaApiClient;
+    /** The latch the shell's commands announce presence through. */
+    presence: PresenceNotice;
 }
 export declare function createSforaShell(options: CreateSforaShellOptions): SforaShell;
 export interface LocalShell {
@@ -43,4 +62,10 @@ export declare function createLocalShell(root: string, cwd?: string): LocalShell
 export { SforaFs } from "./SforaFs.js";
 export { LocalWorkspace, initWorkspace, findWorkspace, WORKSPACE_DIR, type TaskEntry, type TaskWriteResult, } from "./local/workspace.js";
 export * from "./format/index.js";
-export { SforaApiClient, SforaApiError, type SforaApiConfig, type Project, type Entry, type PostKind, type WriteResult, } from "./api-client.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";
+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 { 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";

package/dist/index.js

@@ -10,20 +10,31 @@
 import { Bash, ReadWriteFs } 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";
 export function createSforaShell(options) {
     const client = new SforaApiClient({
         baseUrl: options.baseUrl,
         apiKey: options.apiKey,
         actAs: options.actAs,
     });
+    const presence = options.presence ?? presenceNotice();
     const fs = new SforaFs(client);
     // Disable just-bash's in-process defense-in-depth sandbox. It defaults on and
     // hardens against *untrusted* scripts by blocking globals like `WeakRef` —
     // which undici's `fetch` uses internally, so it would break every network-backed
     // fs call. sfora runs the user's / agent's own commands against their own
     // workspace over HTTPS, so this hardening is unnecessary here.
-    const bash = new Bash({ fs, cwd: options.cwd ?? "/", defenseInDepth: false });
-    return { bash, fs };
+    const bash = new Bash({
+        fs,
+        cwd: options.cwd ?? "/",
+        defenseInDepth: false,
+        // sfora's own verbs, inside the shell (card #333). They are registered
+        // 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),
+    });
+    return { bash, fs, client, presence };
 }
 /**
  * Shell over a local `.sfora/` workspace — the OSS serverless mode. The same
@@ -39,4 +50,10 @@ export function createLocalShell(root, cwd = "/") {
 export { SforaFs } from "./SforaFs.js";
 export { LocalWorkspace, initWorkspace, findWorkspace, WORKSPACE_DIR, } from "./local/workspace.js";
 export * from "./format/index.js";
-export { SforaApiClient, SforaApiError, } from "./api-client.js";
+export { SforaApiClient, SforaApiError, blockConflictFrom, writeEffectFrom, } from "./api-client.js";
+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 { watchLoop, parseWatchTarget, MAX_BACKOFF_MS, } from "./watch.js";
+export { renderPing, renderBlocks, renderBlockConflict, renderWriteEffect, ndjson, } from "./render.js";

package/dist/opener.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Handing a URL to the desktop — the one command per platform, as data.
+ *
+ * Split out from the spawn so it can be tested: what a test can meaningfully
+ * assert about `sfora open` is that it builds the RIGHT command for the
+ * platform, not that a browser appeared. `openerCommand` is pure, so the three
+ * platforms are three assertions; `openUrl` is the four-line side effect that
+ * cannot be, and holds nothing worth testing.
+ */
+export interface OpenerCommand {
+    command: string;
+    args: string[];
+}
+/**
+ * The opener for a platform, as `NodeJS.Process["platform"]` spells it.
+ *
+ * Windows is the case worth stating: `start` is not an executable, it is a
+ * `cmd.exe` builtin, so spawning it directly fails with ENOENT. It has to be
+ * run THROUGH cmd — and the empty string after `start` is not padding: `start`
+ * reads its first quoted argument as the new window's TITLE, so a URL in quotes
+ * would open a console window titled with the link instead of the link.
+ */
+export declare function openerCommand(platform: NodeJS.Platform | string, url: string): OpenerCommand;

package/dist/opener.js

@@ -0,0 +1,26 @@
+/**
+ * Handing a URL to the desktop — the one command per platform, as data.
+ *
+ * Split out from the spawn so it can be tested: what a test can meaningfully
+ * assert about `sfora open` is that it builds the RIGHT command for the
+ * platform, not that a browser appeared. `openerCommand` is pure, so the three
+ * platforms are three assertions; `openUrl` is the four-line side effect that
+ * cannot be, and holds nothing worth testing.
+ */
+/**
+ * The opener for a platform, as `NodeJS.Process["platform"]` spells it.
+ *
+ * Windows is the case worth stating: `start` is not an executable, it is a
+ * `cmd.exe` builtin, so spawning it directly fails with ENOENT. It has to be
+ * run THROUGH cmd — and the empty string after `start` is not padding: `start`
+ * reads its first quoted argument as the new window's TITLE, so a URL in quotes
+ * would open a console window titled with the link instead of the link.
+ */
+export function openerCommand(platform, url) {
+    if (platform === "darwin")
+        return { command: "open", args: [url] };
+    if (platform === "win32") {
+        return { command: "cmd", args: ["/c", "start", "", url] };
+    }
+    return { command: "xdg-open", args: [url] };
+}