sfora-cli 0.10.0 → 0.11.0

package/README.md

@@ -11,6 +11,7 @@ sfora new "Acme"                          # create a project
 sfora post plan.md --project acme        # push a markdown plan as a post
 sfora task spec.md --project acme         # …or a task on the board
 sfora cat /projects/acme/board/01-todo/0042-fix-login.md
+sfora url /projects/acme/docs/kickoff.md  # where it lives on the web
 ```
 
 Under the hood it maps a Unix view onto sfora's `/v1/fs` HTTP API (a sandboxed
@@ -211,6 +212,144 @@ backend) are the public exports, alongside the lower-level `SforaApiClient`.
 
 ## Supported operations
 
+## Blocks — write one paragraph, not the file
+
+A markdown body is addressable: every top-level block has an id that is a
+fingerprint over its bytes, so `sfora blocks` lists them and
+`sfora put --block <id>` replaces exactly one and leaves every other byte alone.
+
+```bash
+$ sfora blocks /projects/acme/docs/kickoff.md
+kfrontmat  yaml       id: k17e8c0...                         read-only
+k7f3a2cx   heading    # Kickoff                              read-only
+kq8w1zzp   paragraph  The hill chart is the one view that a…
+3 blocks · 1 writable
+https://www.sfora.ai/org/acme/notes/k17e8c0...
+
+$ echo "A rewritten paragraph." | sfora put /projects/acme/docs/kickoff.md --block kq8w1zzp
+✓ Wrote block kq8w1zzp of /v1/fs/projects/acme/library/documents/kickoff.md
+  changed · 3 of 4 block ids kept · 1 moved
+  https://www.sfora.ai/org/acme/notes/k17e8c0...
+  you are visible as editing this document
+```
+
+`read-only` blocks are real lines you can see in the file — the frontmatter
+fence, the title heading — that the write door does not store, so their ids
+address nothing. Aim at a writable one.
+
+**Every write prints what it did.** sfora's write door splices: a PUT of bytes
+that parse the same as the stored ones stores nothing, so `no change — the
+stored bytes already matched` is a real and frequent answer to a
+read-edit-write loop that reformatted more than it meant to. When bytes did
+move, the line says how many block ids survived it.
+
+**A stale id is not an error, it is a re-aim.** Block ids are derived from
+content, so "this id resolves to nothing" means somebody changed that block
+since you read it. The server sends the document's current blocks with the
+refusal, and the CLI prints them:
+
+```
+that block is gone — somebody changed it since you read it
+Block kq8w1zzp is not in this document any more.
+
+the document has these blocks now:
+  k7f3a2cx  line 1  ## Agenda
+  kt2p9lmx  line 3  A rewritten paragraph.
+  kb91xz4q  line 5  ```json
+
+re-aim with: sfora put /projects/acme/docs/kickoff.md --block <id>
+```
+
+The columns differ from `sfora blocks` on purpose. That listing describes what
+a READ serves — frontmatter, the title heading, and `writable` to say which of
+those the write door can reach. This one is what the write door FOUND, which is
+the document's stored body: every id here already resolves, so there is no
+read-only row to mark, and `line` is where in the file to look.
+
+`blocks`, `put` and `url` are also commands **inside the shell**, so the body
+can come from a pipeline:
+
+```text
+sfora:/$ blocks /projects/acme/docs/kickoff.md | grep paragraph
+sfora:/$ sed 's/hill chart/hill/' draft.md | put /projects/acme/docs/kickoff.md --block kq8w1zzp
+```
+
+Writing a document also makes you **visible in it** — the app's avatar stack
+shows you editing, with the block you aimed at. The CLI says so once per run.
+
+## Watch — a document as a channel
+
+`sfora watch` long-polls the workspace and prints every write as it lands. Point
+it at one document, or at a whole project.
+
+```bash
+$ sfora watch /projects/acme/docs/kickoff.md
+watching /projects/acme/docs/kickoff.md (not your own writes) — ^C to stop
+14:22:07 · Ada Lovelace · Kickoff · 4 of 5 block ids kept · https://www.sfora.ai/org/acme/notes/k17e8c0...
+14:24:19 · Dogfood Bot · Kickoff · edited · https://www.sfora.ai/org/acme/notes/k17e8c0...
+
+$ sfora watch acme --json | jq -r 'select(.docType == "note") | .title'
+```
+
+* `--json` writes **NDJSON** — one event per line (schema below).
+* Your own writes are excluded by default; `--self` includes them.
+* `--wait <secs>` sets the per-request long-poll budget (0–50, default 25).
+* Watching a document makes you **visible in it** as a viewer; ^C aborts the
+  open long-poll and retracts you on the way out, rather than leaving a ghost
+  in the avatar stack for 90 seconds. It lands immediately — it does not wait
+  out the `--wait` budget. A second ^C gives up on the retraction and exits
+  now.
+* A dropped connection reconnects with exponential backoff to 30s and resumes
+  from the cursor already reached — no replayed pings, no lost ones.
+
+### The NDJSON schema
+
+Each line is the server's `/v1/events` object, **verbatim** — the CLI reshapes
+nothing, so one parser reads the CLI's stream and the HTTP door's pages alike.
+
+| field | |
+|---|---|
+| `type` | `"doc.write"` or `"doc.delete"` |
+| `ts` | epoch ms — also the cursor value |
+| `docType` | `"note"` · `"post"` · `"card"` |
+| `docId` | the entity id |
+| `projectId` | the project it lives in |
+| `title`, `path` | the document's title and fs path |
+| `url` | the page it can be read on |
+| `author`, `authorId`, `authorType` | who wrote |
+| `changed` | always `true` — a write that changed nothing never pings |
+| `blockIds` | `{ rebound, orphaned, total }` for the version before this write |
+| `deleted` | `doc.delete` only; `blockIds` is then absent |
+| `restricted` | the ping is real, its pointer was withheld — see below |
+
+A **restricted** ping has no `title`, `path` or `url`: the document is somebody's
+unpublished draft. The event is still delivered, because a watch that went
+silent would look connected and be deaf.
+
+Warnings (reconnects) go to stderr, so `--json` stdout stays parseable.
+
+## Links — `sfora url` · `sfora open`
+
+Every workspace thing has a page. The server says where; the CLI prints it.
+
+```bash
+sfora url /projects/acme/library/documents/kickoff.md
+# https://www.sfora.ai/org/acme/notes/k17e8c0...
+
+sfora open /projects/acme/board/02-todo/0042-fix-login.md   # …and opens it
+sfora url /projects/acme/board --json                       # { "path": …, "url": … }
+```
+
+The CLI holds **no route table and no hostname**. It asks for the path you gave
+and reads the link off the answer — a markdown read carries it in the
+`X-Sfora-Url` header, a JSON one in a `url` field — so links stay right when the
+app's routes move, and a dev deployment hands out dev links.
+
+`ls`, `cat` and the write verbs print the same link as one dim line **on
+stderr**, so `sfora cat x.md > x.md` and `sfora ls | wc -l` stay byte-clean.
+Paths with no page of their own (uploaded files, repository trees, your inbox)
+print nothing, and `sfora url` on one says so.
+
 | op | behaviour |
 |----|-----------|
 | `ls`, `readdir` | directory listings via `/v1/fs/projects/…` (cached ~5s) |

package/dist/SforaFs.js

@@ -413,12 +413,14 @@ export class SforaFs {
         const columns = meta.columns
             .slice()
             .sort((a, b) => a.position - b.position);
-        const out = [
-            `# ${project.name} roadmap`,
-            "",
-            `> https://www.sfora.ai/roadmap/${meta.publicSlug}`,
-            "",
-        ];
+        // The share link is the SERVER'S (`publicUrl` off `GET …/board`), not a
+        // hostname glued onto the slug here: which origin a deployment serves its
+        // pages from is the deployment's business, and a CLI pointed at a laptop or
+        // a preview would otherwise quote the production one. An older server that
+        // does not send it leaves the heading and the columns, minus the line.
+        const out = [`# ${project.name} roadmap`, ""];
+        if (meta.publicUrl)
+            out.push(`> ${meta.publicUrl}`, "");
         for (const col of columns) {
             out.push(`## ${col.name}`, "");
             const cards = await this.#listCards(slug, col.dirname);

package/dist/api-client.d.ts

@@ -24,10 +24,56 @@ export interface Entry {
     scheduledFor?: number;
     isDraft: boolean;
 }
+/**
+ * How many block ids survived a write, from the server's rebinding ledger.
+ *
+ * Absent rather than zeroed when the door computed no correspondence — a
+ * create has no previous version to rebind from.
+ */
+export interface RebindCounts {
+    rebound: number;
+    orphaned: number;
+    total: number;
+}
+/**
+ * The effect report every markdown write returns: did the stored bytes move,
+ * and what happened to the block ids if so.
+ *
+ * The reason a write reports this at all is that sfora's write door SPLICES —
+ * a PUT of bytes that parse the same as the stored ones stores nothing, so
+ * `changed: false` is a real and common answer, and a bare `201` would read as
+ * "saved" for a write that did nothing.
+ */
+export interface WriteEffect {
+    changed: boolean;
+    blockIds?: RebindCounts;
+}
+/** What the last response said about itself. See `takeResponseInfo`. */
+export interface ResponseInfo {
+    /** The absolute web page the response named, if any (card #335). */
+    url: string | null;
+    /** The effect report, when the response was a markdown write (card #333). */
+    effect: WriteEffect | null;
+    /**
+     * The write put the caller on the document's roster.
+     *
+     * Only document writes declare presence server-side — posts and cards have
+     * markdown bodies but nobody has one open in a document editor — so this
+     * comes off the response rather than being inferred from the path shape.
+     */
+    present: boolean;
+}
+/** The effect report in a parsed response body, or null when there is none. */
+export declare function writeEffectFrom(body: unknown): WriteEffect | null;
 /** Result of a successful `PUT` (create/update). */
-export interface WriteResult {
+export interface WriteResult extends Partial<WriteEffect> {
     filename: string;
     id: string;
+    /** The fs path the write landed at — canonical, which may differ from the URL. */
+    path?: string;
+    /** The web page it can be read on. */
+    url?: string;
+    created?: boolean;
 }
 /**
  * A note (doc) file entry. Mirrors a row of `GET …/docs`. Notes have stable
@@ -100,6 +146,14 @@ export interface BoardColumn {
 export interface BoardMeta {
     publicSlug: string | null;
     columns: BoardColumn[];
+    /**
+     * The shared roadmap's public page, or `null` when the board isn't shared.
+     *
+     * The slug next to it is the identifier; this is the LINK, and it comes from
+     * the server for the same reason every other one does — the hostname is the
+     * deployment's, not the CLI's.
+     */
+    publicUrl?: string | null;
 }
 /** A card file under `/projects/<slug>/board/<col>/`. `filename` is `NNNN-<slug>.md`. */
 export interface BoardCardEntry {
@@ -110,12 +164,52 @@ export interface BoardCardEntry {
     lastActivityAt: number;
 }
 /** Result of `PUT …/board/<col>/<filename>.md`. */
-export interface CardWriteResult {
+export interface CardWriteResult extends Partial<WriteEffect> {
     filename: string;
     id: string;
     number: number;
     /** New column dirname — set when frontmatter `column:` or `status:` moved the card. */
     movedTo?: string;
+    path?: string;
+    /** The web page it can be read on. */
+    url?: string;
+    created?: boolean;
+}
+/** One member in a document right now. Mirrors a row of `here`. */
+export interface DocPresenceMember {
+    memberId: string;
+    name: string;
+    type: "human" | "agent";
+    kind: "viewing" | "editing";
+    blockId?: string;
+    lastSeenAt: number;
+}
+/** `POST <doc>/_presence` — the roster, after your own declaration landed. */
+export interface DocPresence {
+    document: string;
+    url?: string;
+    present: boolean;
+    block: string | null;
+    blockResolved: boolean | null;
+    here: DocPresenceMember[];
+}
+/**
+ * One event off `/v1/events`.
+ *
+ * Deliberately loose beyond the fields the CLI prints: the feed carries room
+ * messages and ask state-changes as well as document writes, and a client that
+ * enumerated every field would have to be edited each time the server learns a
+ * new kind. `--json` forwards the object verbatim for exactly this reason.
+ */
+export interface AgentEvent {
+    type: string;
+    ts: number;
+    [key: string]: unknown;
+}
+/** A page of the long-poll: what happened, and where to poll from next. */
+export interface AgentEventsPage {
+    events: AgentEvent[];
+    cursor: number;
 }
 export interface SforaApiConfig {
     /** e.g. `https://your-sfora.com` or `http://localhost:2222`. Trailing slashes are trimmed. */
@@ -134,11 +228,101 @@ export interface SforaApiConfig {
 export declare class SforaApiError extends Error {
     readonly status: number;
     readonly code: string;
-    constructor(status: number, code: string, message: string);
+    /**
+     * The parsed error body, when there was one.
+     *
+     * Some refusals are USEFUL, not merely informative: a 409 from a `?block=`
+     * write carries the document's current blocks so the caller can re-aim
+     * without a second round trip. Throwing away everything but the message
+     * would make the CLI ask for that page again. Untyped here because the fs
+     * error envelope is `{ error, message }` plus whatever the specific refusal
+     * adds; {@link blockConflictFrom} is the typed reader for the one shape the
+     * CLI acts on.
+     */
+    readonly data?: unknown;
+    constructor(status: number, code: string, message: string, data?: unknown);
+}
+/** One block, as `?view=blocks` describes it. */
+export interface BlockView {
+    id: string;
+    writable: boolean;
+    type: string;
+    lines: [number, number];
+    text: string;
+    depth?: number;
+    lang?: string;
+}
+/** `GET …?view=blocks` — the addressable view of a document. */
+export interface BlocksView {
+    /** The fs path these blocks are OF — what to GET for the document itself. */
+    canonical: string;
+    note: string;
+    document?: {
+        id?: string;
+        title?: string;
+        lastEditedAt?: string;
+    };
+    blocks: BlockView[];
+    /** Present when block extents could not be determined; `blocks` is then empty. */
+    unaddressable?: string;
+    /** The web page the document is read on (card #335). */
+    url?: string;
+}
+/**
+ * One block, as a 409 lists it.
+ *
+ * A DIFFERENT SHAPE from {@link BlockView}, and the difference is not an
+ * oversight on either side. `?view=blocks` projects what the read serves — the
+ * frontmatter envelope, the title heading, the mdast type of each node, and
+ * `writable` to say which of those the write door can actually resolve. The
+ * 409 lists what the write door FOUND, which is the document's stored body:
+ * every id in it resolves by construction, so there is no `writable` to report
+ * and no envelope block to report it about. Three fields, one line each in the
+ * re-aim table: which id, where it is, what it says.
+ */
+export interface BlockSummary {
+    id: string;
+    /** 1-based line the block starts on, in the stored body. */
+    line: number;
+    /** The block's first non-empty line, clipped by the server. */
+    preview: string;
+}
+/**
+ * The recovery payload on a 409 from a `?block=` write: the id no longer
+ * resolves, and here is what the document has NOW so the caller can re-aim.
+ */
+export interface BlockConflict {
+    message: string;
+    /** The id that was aimed at. */
+    block?: string;
+    blocks: BlockSummary[];
+}
+/** The 409 recovery payload inside an error, or null for any other failure. */
+export declare function blockConflictFrom(error: unknown): BlockConflict | null;
+/** Options every markdown write door takes. */
+export interface WriteOptions {
+    /**
+     * Write ONE block instead of the whole file — the id from `?view=blocks`.
+     *
+     * The body is then that block's markdown, with no frontmatter and no title:
+     * a block write edits prose and never a document's state.
+     */
+    blockId?: string;
 }
 export declare class SforaApiClient {
     #private;
     constructor(config: SforaApiConfig);
+    /** What the last response said about itself, consumed. */
+    takeResponseInfo(): ResponseInfo;
+    /**
+     * The web page an fs path is read on, or null when it has none.
+     *
+     * One request, and the ONLY route knowledge involved is the server's: this
+     * reads the path the caller gave and reports the link the answer carried.
+     * A directory listing answers in JSON, a document in markdown with the link
+     * in a header, and {@link webUrlFromResponse} covers both.
+     */
+    resolveWebUrl(fsPath: string): Promise<string | null>;
     /** `GET /v1/fs/projects` */
     listProjects(): Promise<Project[]>;
     /** `POST /v1/fs/projects` — create a project; the caller becomes its lead. */
@@ -168,7 +352,23 @@ export declare class SforaApiClient {
     /** `GET …/posts/:filename.md` (or `…/drafts/…`). Returns the raw markdown body. */
     readPost(projectSlug: string, filename: string, kind?: PostKind): Promise<string>;
     /** Create a post or upsert a mutable draft from a Markdown file. */
-    writePost(projectSlug: string, kind: PostKind, filename: string, markdown: string): Promise<WriteResult>;
+    writePost(projectSlug: string, kind: PostKind, filename: string, markdown: string, options?: WriteOptions): Promise<WriteResult>;
+    /**
+     * `GET …?view=blocks` on any fs path with a stored markdown body — the
+     * addressable view a `?block=` write aims into.
+     *
+     * The path is the caller's fs path (`/projects/acme/docs/x.md`), not a
+     * `/v1/fs` URL: the CLI does not build routes.
+     */
+    readBlocks(fsPath: string): Promise<BlocksView>;
+    /**
+     * `PUT <fs path>` — the generic write door, so the CLI can put to any path
+     * (and to a single block of it) without a per-entity method.
+     *
+     * A 409 from a `?block=` write throws a {@link SforaApiError} carrying the
+     * server's recovery payload; read it with {@link blockConflictFrom}.
+     */
+    writePath(fsPath: string, markdown: string, options?: WriteOptions): Promise<WriteResult & Partial<CardWriteResult>>;
     /** `DELETE …/(posts|drafts)/:filename.md` — soft-deletes the matched post. */
     deletePost(projectSlug: string, kind: PostKind, filename: string): Promise<void>;
     /** `GET …/docs` — the project's notes, most-recently-edited first. */
@@ -236,6 +436,45 @@ export declare class SforaApiClient {
         content: string;
         reacted: boolean;
     }>;
+    /**
+     * `POST <path>/_presence` — say you are in a document.
+     *
+     * Returns `null` when the path has no roster. The CLI does not decide which
+     * paths those are: it asks, and a `422` is the server's named refusal
+     * ("posts and board cards have markdown bodies but nobody has one open in a
+     * document editor"). Every other failure is thrown as usual.
+     */
+    declarePresence(fsPath: string, options?: {
+        kind?: "viewing" | "editing";
+        block?: string;
+        leave?: boolean;
+    }): Promise<DocPresence | null>;
+    /**
+     * `GET /v1/events` — the long-poll. Blocks server-side until something
+     * happens or the wait budget elapses, then answers with a cursor to poll
+     * from next.
+     *
+     * `signal` is not optional in spirit: this is the ONE request in the client
+     * that is designed to hang, so a caller that cannot cancel it cannot stop.
+     * `sfora watch` aborts it from its ^C handler, which is the difference
+     * between a terminal that says "^C to stop" and one that does.
+     */
+    pollEvents(params: {
+        since: number;
+        wait?: number;
+        doc?: string;
+        project?: string;
+        includeSelf?: boolean;
+        signal?: AbortSignal;
+    }): Promise<AgentEventsPage>;
+    /**
+     * The entity id behind an fs path — what `/v1/events?doc=` wants.
+     *
+     * Read off `?view=blocks`, which states the document's identity in its
+     * `document` field, rather than parsed out of the file's frontmatter: the
+     * projection is the server saying which row these bytes are.
+     */
+    resolveDocId(fsPath: string): Promise<string | null>;
     /** `GET /v1/fs/inbox/mentions.md` — markdown summary of unread mentions. */
     readInbox(): Promise<string>;
     /** `GET /v1/fs/me/api-key` — text identity (no key material). */