sfora-cli 0.9.0 → 0.11.0

package/dist/format/wikiLinks.d.ts

@@ -0,0 +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 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

@@ -0,0 +1,266 @@
+// 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).
+// The `[[…]]` wiki-link grammar — sfora's cross-entity link token, and the one
+// place its prefix table lives.
+//
+//   [[<postId>]]            → a post (bare, no prefix)
+//   [[n:<noteId>]]          → a doc / note
+//   [[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]]`, 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
+// (src/lib/utils/markdown.ts), and, by hand-copy, the mobile preprocessor
+// (packages/mobile/src/lib/markdown-tokens.ts — outside the pnpm workspace).
+// Prefix → kind, longest-first so `pr:` is tried before any future `p:`.
+export const WIKI_LINK_PREFIXES = [
+    ["pr:", "pr"],
+    ["gh:", "pr"],
+    ["n:", "note"],
+    ["c:", "card"],
+];
+// The prefix to WRITE for a kind when building a canonical token. Note `gh:` is
+// an accepted input alias for `pr:` but is never emitted.
+export const WIKI_LINK_PREFIX_FOR = {
+    post: "",
+    card: "c:",
+    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;
+}
+// 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 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.
+export function parseWikiTarget(target) {
+    for (const [prefix, kind] of WIKI_LINK_PREFIXES) {
+        if (target.startsWith(prefix)) {
+            return { kind, id: target.slice(prefix.length) };
+        }
+    }
+    return { kind: "post", id: target };
+}
+// 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 = wikiTokenPattern();
+    let m;
+    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 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/mcp-server.js

@@ -14,9 +14,12 @@ const TOOL_DESCRIPTION = `Run a bash command against the sfora workspace — a U
   - /projects/<slug>/posts/<file>.md            published posts
   - /projects/<slug>/drafts/<file>.md           your drafts
   - /projects/<slug>/board/<NN-stage>/<NNNN>.md tasks (kanban cards), by stage
-  - /projects/<slug>/docs/<file>.md             docs / notes
+  - /projects/<slug>/library/documents/<file>.md workspace documents (writable)
+  - /projects/<slug>/library/files/<file>        uploaded files (read-only)
+  - /projects/<slug>/library/repositories/<repo> project source trees (read-only)
   - /projects/<slug>/pulls/<number>.md          pull requests (diff + linked work), read-only
-  - /projects/<slug>/plan.md                    the goal + open questions
+  - /projects/<slug>/plan.md                    the goal + open questions (write to set the goal)
+  - /projects/<slug>/asks.md                    coordination asks, read-only
   - /inbox/mentions.md                          unread mentions
   - /me/api-key                                 your identity
 Every board is the same four fixed columns — 01-triage / 02-todo / 03-in-progress / 04-done. There is no column management; move a card into 04-done to close it. Question cards (kind: question) map their stage to the plan: triage = fuzzy, todo = up for grabs, in-progress = claimed, done = decided.

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] };
+}

package/dist/render.d.ts

@@ -0,0 +1,132 @@
+/**
+ * What the CLI prints — as pure functions, so it can be tested.
+ *
+ * Everything here takes data and returns a string. No I/O, no process, no
+ * colours decided by a TTY check: the caller writes the result. That is what
+ * lets `render.test.ts` assert on a 409 re-aim table or a blocks listing
+ * without a server, a terminal, or a snapshot of the whole command.
+ *
+ * The rule these follow, from the mission's binding: THE CLI PRINTS WHAT THE
+ * SERVER SENDS. Nothing here computes a URL, a route, or a block id — each
+ * comes off a response and is formatted.
+ */
+import type { BlockConflict, BlockView, BlocksView, WriteEffect } from "./api-client.js";
+export declare const colors: {
+    reset: string;
+    bold: string;
+    dim: string;
+    cyan: string;
+    green: string;
+    yellow: string;
+    blue: string;
+    red: string;
+};
+/**
+ * A link, as one quiet line.
+ *
+ * Dim and unadorned because it is an offer, not an instruction: the line a
+ * reader's eye skips until the moment they want it, and a terminal that
+ * hyperlinks URLs makes it clickable without any markup from us.
+ */
+export declare function urlLine(url: string): string;
+/** The first line of a block's text, collapsed and clipped for one row. */
+export declare function blockSummary(block: BlockView, width?: number): string;
+/**
+ * `sfora blocks <path>` — the addressable view, one row per block.
+ *
+ * The id comes FIRST because it is the only column anyone retypes: the next
+ * command is `sfora put <path> --block <id>`, and a listing that buries the id
+ * makes the reader hunt for it.
+ *
+ * `writable: false` is stated, not omitted, and it is stated as "read-only"
+ * rather than by leaving the row out. Those blocks are real — the frontmatter
+ * fence, the title heading — they occupy lines the reader can see in the file,
+ * and hiding them would make the listing disagree with `cat`.
+ */
+export declare function renderBlocks(view: BlocksView): string;
+/**
+ * The 409 a `?block=` write gets: the id named nothing, here is what the
+ * document has now.
+ *
+ * A table and not a message, because the recovery IS the payload: the server
+ * already sent the current blocks, so the fix is one glance and one retry
+ * rather than a second `sfora blocks` round trip. The retry line is spelled
+ * out with the real path for the same reason.
+ *
+ * THE COLUMNS ARE THE PAYLOAD'S — id, line, preview — and not `sfora blocks`'s.
+ * The two lists describe different bytes (see {@link BlockSummary}): every id
+ * here already resolves at the write door, so there is no writable/read-only
+ * distinction to draw and no node type in the payload to draw one with. An
+ * earlier version of this function reached for both anyway and printed
+ * `undefined  read-only` on every row, which inverted the one fact the table
+ * exists to convey. `line` earns the column it took: it is where in the file
+ * the caller is holding to look, and it is the field that tells two blocks with
+ * the same opening words apart.
+ */
+export declare function renderBlockConflict(conflict: BlockConflict, fsPath: string): string;
+/**
+ * The effect report, as one line — printed after EVERY write.
+ *
+ * A bare "saved" is a lie the CLI used to tell: sfora's write door splices, so
+ * a PUT of bytes that parse the same as the stored ones stores nothing and
+ * `changed: false` is a normal answer. Saying so is the difference between an
+ * agent that knows its edit landed and one that assumes it did.
+ *
+ * The rebind counts describe the blocks the document had BEFORE this write:
+ * `total` of them, of which `rebound` are the same block under a new id and
+ * `orphaned` are blocks nothing in the new document can be shown to be. The
+ * rest kept the id they had, which is the number worth leading with — it is
+ * what tells a reader whether their block addresses still work.
+ */
+export declare function renderWriteEffect(effect: WriteEffect | null): string | null;
+/**
+ * The one-time "you are visible" note.
+ *
+ * Writing DECLARES PRESENCE server-side — the document's roster shows the
+ * writer, and a human with it open sees them. That is a fact about the user's
+ * visibility to other people, so it is said out loud rather than left to be
+ * discovered in the UI; once per run, because said on every write it would be
+ * noise and the second one teaches nothing.
+ */
+export declare const PRESENCE_NOTE = "you are visible as editing this document";
+/** One `doc.write` / `doc.delete` ping from `/v1/events`, as one line. */
+export interface DocPing {
+    type: "doc.write" | "doc.delete";
+    ts: number;
+    docType?: string;
+    docId?: string;
+    title?: string;
+    path?: string;
+    url?: string;
+    author?: string;
+    authorType?: "human" | "agent";
+    changed?: boolean;
+    deleted?: boolean;
+    restricted?: boolean;
+    blockIds?: {
+        rebound: number;
+        orphaned: number;
+        total: number;
+    };
+}
+/** `HH:MM:SS` in the reader's own timezone — a ping is read as it lands. */
+export declare function pingTime(ts: number): string;
+/**
+ * `time · author · doc · what changed · url` — one ping, one line.
+ *
+ * A RESTRICTED ping keeps its shape and loses its pointer: the server
+ * delivered the fact (a document you are watching moved, by whom) and withheld
+ * the title and the link because they belong to somebody's draft. Printing
+ * "(restricted)" rather than dropping the line is the honest half — a watch
+ * that went silent would look broken.
+ */
+export declare function renderPing(ping: DocPing): string;
+/**
+ * The NDJSON line for one ping — the machine half of `sfora watch --json`.
+ *
+ * The SERVER'S event object, verbatim, plus nothing. A CLI that reshaped it
+ * would become a second schema to keep in step with `/v1/events`, and the one
+ * consumer that matters here (an agent piping this into a program) is better
+ * served by the wire shape it can also get from the HTTP door directly.
+ */
+export declare function ndjson(event: unknown): string;