sfora-cli 0.9.0 → 0.11.0

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
@@ -38,6 +84,35 @@ export interface Note {
     title: string;
     lastEditedAt: number;
 }
+/** An uploaded project file under the unified Library. */
+export interface Artifact {
+    name: string;
+    mimeType: string;
+    size: number;
+    uploadedBy: string | null;
+    uploadedAt: number;
+    url: string | null;
+}
+/** A GitHub repository attached to a project. Repository content is read-only. */
+export interface Repository {
+    projectRepoId: string;
+    dirname: string;
+    owner: string;
+    repo: string;
+    defaultBranch: string;
+}
+export interface RepositoryTreeEntry {
+    path: string;
+    kind: "file" | "directory" | "submodule";
+    size?: number;
+}
+export interface RepositoryTree {
+    owner: string;
+    repo: string;
+    ref: string;
+    truncated: boolean;
+    entries: RepositoryTreeEntry[];
+}
 /**
  * A pull request entry. Mirrors a row of `GET …/pulls`. Read-only — the source
  * of truth is GitHub; sfora syncs these so agents can see the code work
@@ -71,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 {
@@ -81,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. */
@@ -105,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. */
@@ -121,6 +334,16 @@ export declare class SforaApiClient {
     getProjectLinks(slug: string): Promise<string>;
     /** `PUT …/links.md` — replace the project's links from a markdown list. */
     setProjectLinks(slug: string, markdown: string): Promise<void>;
+    /** `GET …/plan.md` — the project's plan (goal + question buckets). */
+    readMap(slug: string): Promise<string>;
+    readPlan(slug: string): Promise<string>;
+    /**
+     * `PUT …/plan.md` — set the goal. Only the `## the goal` section is
+     * honored; the server names everything it ignored in `ignoredSections`.
+     */
+    writePlan(slug: string, markdown: string): Promise<void>;
+    /** `GET …/asks.md` — coordination asks (read-only projection). */
+    readAsks(slug: string): Promise<string>;
     /**
      * `GET …/posts` or `…/drafts`. `scheduled` lists drafts that have a
      * (future) `scheduledFor` set.
@@ -128,14 +351,37 @@ export declare class SforaApiClient {
     listPosts(projectSlug: string, kind?: PostKind): Promise<Entry[]>;
     /** `GET …/posts/:filename.md` (or `…/drafts/…`). Returns the raw markdown body. */
     readPost(projectSlug: string, filename: string, kind?: PostKind): Promise<string>;
-    /** `PUT …/(posts|drafts)/:filename.md` — create or update from a markdown file. */
-    writePost(projectSlug: string, kind: PostKind, filename: string, markdown: string): Promise<WriteResult>;
+    /** Create a post or upsert a mutable draft from a Markdown file. */
+    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. */
     listNotes(projectSlug: string): Promise<Note[]>;
     /** `GET …/docs/:filename.md`. Returns the raw markdown body. */
     readNote(projectSlug: string, filename: string): Promise<string>;
+    writeNote(projectSlug: string, filename: string, markdown: string): Promise<WriteResult>;
+    deleteNote(projectSlug: string, filename: string): Promise<void>;
+    listArtifacts(projectSlug: string): Promise<Artifact[]>;
+    readArtifact(projectSlug: string, filename: string): Promise<string>;
+    listRepositories(projectSlug: string): Promise<Repository[]>;
+    getRepositoryTree(projectSlug: string, dirname: string): Promise<RepositoryTree>;
+    readRepositoryFile(projectSlug: string, dirname: string, path: string): Promise<string>;
     /** `GET …/pulls` — the project's synced pull requests, open first. */
     listPulls(projectSlug: string): Promise<Pull[]>;
     /**
@@ -190,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). */