sfora-cli 0.6.0 → 0.8.0

package/README.md

@@ -39,6 +39,32 @@ sfora                   # interactive shell — explore /projects, cat, grep
 One CLI for everyone: the default identity is **you**; add `--bot <name>` to any
 command to run as that bot.
 
+## Local mode — no account, no server
+
+`sfora init --local` turns the current repo into a workspace: a `.sfora/`
+directory where tasks, posts, and docs are plain markdown files — versioned
+with your code, reviewable in PRs, greppable, offline.
+
+```bash
+sfora init --local       # scaffold .sfora/ (board columns, posts/, docs/)
+sfora task plan.md       # → .sfora/board/01-todo/0001-<slug>.md
+sfora tasks              # board by column (add --json for scripting)
+sfora                    # shell over the files — and `mv` between column
+                         # dirs IS a card move
+sfora --mcp              # MCP server over the local workspace
+```
+
+```
+.sfora/
+├── board/01-todo/0001-fix-login.md   # tasks — NNNN-<slug>.md per column
+├── posts/2026-07-02-standup.md       # posts — YYYY-MM-DD-<slug>.md
+└── docs/architecture.md              # docs
+```
+
+It's the exact same format the cloud serves, so connecting a team later is just
+`sfora login` — inside a `.sfora/` repo the CLI targets the local files;
+add `--cloud` (or `--org`) to reach your cloud workspace from there.
+
 `sfora init` writes `~/.sfora/config.json` (chmod 600). Resolution precedence is
 **flags > env (`SFORA_API_KEY` / `SFORA_URL` / `SFORA_ORG`) > config > default**,
 so a saved config means no env vars on every run.
@@ -48,12 +74,14 @@ so a saved config means no env vars on every run.
 pnpm -F sfora build && node packages/sfora/dist/cli.js --help
 ```
 
-### The `just-bash` dependency
+### The shell engine
 
-This package depends on `just-bash@^3.0.1` from npm — no extra steps needed.
+The sfora shell is a real POSIX-style shell mounted on your workspace. It's
+powered by an embedded interpreter (the `just-bash` package, `^3.0.1`) — a
+normal npm dependency, no extra steps needed.
 
-If you're working against an **unpublished** `just-bash` (e.g. the copy in
-`context/just-bash`), point the dependency at it and build it first:
+If you're working against an **unpublished** build of the engine (e.g. the copy
+in `context/just-bash`), point the dependency at it and build it first:
 
 ```jsonc
 // packages/sfora/package.json
@@ -65,11 +93,11 @@ cd context/just-bash && pnpm install && pnpm build   # produces dist/bundle/*
 cd ../../ && pnpm install
 ```
 
-> Note: `createSforaShell` constructs the `Bash` instance with
-> `defenseInDepth: false`. just-bash's in-process hardening (which blocks globals
-> like `WeakRef`) defaults on and would break `fetch` (undici uses `WeakRef`
-> internally). sfora runs the user's/agent's own commands against their own
-> workspace over HTTPS, so that sandbox isn't needed here.
+> Note: `createSforaShell` constructs the shell with `defenseInDepth: false`.
+> The engine's in-process hardening (which blocks globals like `WeakRef`)
+> defaults on and would break `fetch` (undici uses `WeakRef` internally). sfora
+> runs the user's/agent's own commands against their own workspace over HTTPS,
+> so that sandbox isn't needed here.
 
 ## Auth
 
@@ -187,7 +215,7 @@ backend) are the public exports, alongside the lower-level `SforaApiClient`.
 | `cat`, read | lazy `GET` of the markdown body (fetched only when read) |
 | `echo >`, write | `PUT` markdown → create/update a post or draft |
 | `rm`, unlink | `DELETE` → soft-delete (author or org admin/owner) |
-| `cd`, `pwd`, `grep`, `find`, pipes, … | all the just-bash builtins/commands |
+| `cd`, `pwd`, `grep`, `find`, pipes, … | all the standard shell builtins/commands |
 | `mkdir` | no-op on known dirs; denied elsewhere (can't create projects) |
 | `chmod`, `utimes` | accepted no-ops (permissions/mtime are server-owned) |
 | symlinks, `cp`, `mv` | denied (`EPERM`) — no backend operation |

package/dist/SforaFs.d.ts

@@ -5,6 +5,9 @@
  *   /
  *   ├── projects/<slug>/posts/<YYYY-MM-DD-title>.md   (lazy → GET …/posts/…)
  *   │                  /drafts/<…>.md                 (lazy → GET …/drafts/…)
+ *   │                  /docs/<slug>.md                (lazy → GET …/docs/…)
+ *   │                  /pulls/<number>.md             (lazy → GET …/pulls/…, read-only)
+ *   │                  /public/roadmap.md             (rendered from …/board)
  *   ├── inbox/mentions.md                             (lazy → GET …/inbox)
  *   └── me/api-key                                    (lazy → GET …/me/api-key)
  *

package/dist/SforaFs.js

@@ -5,6 +5,9 @@
  *   /
  *   ├── projects/<slug>/posts/<YYYY-MM-DD-title>.md   (lazy → GET …/posts/…)
  *   │                  /drafts/<…>.md                 (lazy → GET …/drafts/…)
+ *   │                  /docs/<slug>.md                (lazy → GET …/docs/…)
+ *   │                  /pulls/<number>.md             (lazy → GET …/pulls/…, read-only)
+ *   │                  /public/roadmap.md             (rendered from …/board)
  *   ├── inbox/mentions.md                             (lazy → GET …/inbox)
  *   └── me/api-key                                    (lazy → GET …/me/api-key)
  *
@@ -83,6 +86,28 @@ function classify(path) {
                 return { kind: "postFile", slug, dir, filename: seg[3] };
             }
         }
+        if (dir === "docs") {
+            if (seg.length === 3)
+                return { kind: "docsDir", slug };
+            if (seg.length === 4)
+                return { kind: "docFile", slug, filename: seg[3] };
+        }
+        if (dir === "pulls") {
+            if (seg.length === 3)
+                return { kind: "pullsDir", slug };
+            if (seg.length === 4) {
+                const number = Number.parseInt(seg[3], 10);
+                if (Number.isFinite(number))
+                    return { kind: "pullFile", slug, number };
+            }
+        }
+        if (dir === "public") {
+            if (seg.length === 3)
+                return { kind: "publicDir", slug };
+            if (seg.length === 4 && seg[3] === "roadmap.md") {
+                return { kind: "roadmapFile", slug };
+            }
+        }
         if (dir === "board") {
             if (seg.length === 3)
                 return { kind: "boardDir", slug };
@@ -142,6 +167,8 @@ export class SforaFs {
     // Sync snapshots for getAllPaths() (glob support) — updated as lists resolve.
     #projectSlugs = [];
     #entrySnapshots = new Map();
+    // Slugs whose board is shared publicly — gates the `public/` projection.
+    #sharedSlugs = new Set();
     constructor(client) {
         this.#client = client;
     }
@@ -179,15 +206,50 @@ export class SforaFs {
         this.#cache.delete(`${dir}:${slug}`);
         this.#cache.delete("projects"); // postCount changes
     }
+    // ─── notes (docs) cache ──────────────────────────────────────────
+    #listNotes(slug) {
+        const key = `docs:${slug}`;
+        return this.#cached(key, async () => {
+            const notes = await this.#client.listNotes(slug);
+            this.#entrySnapshots.set(`/projects/${slug}/docs`, notes.map((n) => n.filename));
+            return notes;
+        });
+    }
+    // ─── pull requests cache (read-only) ─────────────────────────────
+    #listPulls(slug) {
+        const key = `pulls:${slug}`;
+        return this.#cached(key, async () => {
+            const pulls = await this.#client.listPulls(slug);
+            this.#entrySnapshots.set(`/projects/${slug}/pulls`, pulls.map((p) => `${p.number}.md`));
+            return pulls;
+        });
+    }
+    async #matchPull(slug, number) {
+        const pulls = await this.#listPulls(slug);
+        return pulls.find((p) => p.number === number);
+    }
     // ─── board caches ────────────────────────────────────────────────
-    #listColumns(slug) {
+    /** Cached `GET …/board`: sharing state (`publicSlug`) + columns, one fetch. */
+    #boardMeta(slug) {
         const key = `columns:${slug}`;
         return this.#cached(key, async () => {
-            const columns = await this.#client.listColumns(slug);
-            this.#entrySnapshots.set(`/projects/${slug}/board`, columns.map((c) => c.dirname));
-            return columns;
+            const meta = await this.#client.getBoardMeta(slug);
+            this.#entrySnapshots.set(`/projects/${slug}/board`, meta.columns.map((c) => c.dirname));
+            // Keep a sync snapshot of which boards are shared, for getAllPaths().
+            if (meta.publicSlug)
+                this.#sharedSlugs.add(slug);
+            else
+                this.#sharedSlugs.delete(slug);
+            return meta;
         });
     }
+    async #listColumns(slug) {
+        return (await this.#boardMeta(slug)).columns;
+    }
+    /** The board's public roadmap slug, or null when it isn't shared. */
+    async #publicSlug(slug) {
+        return (await this.#boardMeta(slug)).publicSlug;
+    }
     #listCards(slug, column) {
         const key = `cards:${slug}/${column}`;
         return this.#cached(key, async () => {
@@ -247,6 +309,53 @@ export class SforaFs {
         return (entries.find((e) => e.filename === filename) ??
             entries.find((e) => fileSlug(e.filename) === want));
     }
+    async #matchNote(slug, filename) {
+        const notes = await this.#listNotes(slug);
+        const want = fileSlug(filename);
+        return (notes.find((n) => n.filename === filename) ??
+            notes.find((n) => fileSlug(n.filename) === want));
+    }
+    // ─── public roadmap render ───────────────────────────────────────
+    /**
+     * Render a shared board as a single markdown roadmap: one `##` section per
+     * column (position order), each card a `-` list item, with the live public URL
+     * under the heading. Built from the same board fetch the `/board/` tree uses.
+     *
+     * Only shared boards render — an unshared board (`publicSlug == null`) ENOENTs,
+     * matching the gated `public/` projection.
+     */
+    async #renderRoadmap(slug) {
+        const roadmapPath = `/projects/${slug}/public/roadmap.md`;
+        const projects = await this.#listProjects();
+        const project = projects.find((p) => p.slug === slug);
+        if (!project)
+            throw enoent("open", roadmapPath);
+        const meta = await this.#boardMeta(slug);
+        if (meta.publicSlug == null)
+            throw enoent("open", roadmapPath);
+        const columns = meta.columns
+            .slice()
+            .sort((a, b) => a.position - b.position);
+        const out = [
+            `# ${project.name} roadmap`,
+            "",
+            `> https://www.sfora.ai/roadmap/${meta.publicSlug}`,
+            "",
+        ];
+        for (const col of columns) {
+            out.push(`## ${col.name}`, "");
+            const cards = await this.#listCards(slug, col.dirname);
+            if (cards.length === 0) {
+                out.push("_No cards yet._", "");
+            }
+            else {
+                for (const card of cards)
+                    out.push(`- ${card.title}`);
+                out.push("");
+            }
+        }
+        return `${out.join("\n").trimEnd()}\n`;
+    }
     // ─── reads ───────────────────────────────────────────────────────
     async #readText(path) {
         const loc = classify(path);
@@ -265,6 +374,27 @@ export class SforaFs {
                 catch (e) {
                     throw fromApi(e, "open", normalize(path));
                 }
+            case "docFile":
+                try {
+                    return await this.#client.readNote(loc.slug, loc.filename);
+                }
+                catch (e) {
+                    throw fromApi(e, "open", normalize(path));
+                }
+            case "pullFile":
+                try {
+                    return await this.#client.readPull(loc.slug, loc.number);
+                }
+                catch (e) {
+                    throw fromApi(e, "open", normalize(path));
+                }
+            case "roadmapFile":
+                try {
+                    return await this.#renderRoadmap(loc.slug);
+                }
+                catch (e) {
+                    throw fromApi(e, "open", normalize(path));
+                }
             case "inboxFile":
                 try {
                     return await this.#client.readInbox();
@@ -292,8 +422,11 @@ export class SforaFs {
             case "meDir":
             case "projectDir":
             case "postsDir":
+            case "docsDir":
+            case "pullsDir":
             case "boardDir":
             case "boardColumnDir":
+            case "publicDir":
                 throw eisdir("read", normalize(path));
             default:
                 throw enoent("open", normalize(path));
@@ -331,8 +464,11 @@ export class SforaFs {
             loc.kind === "meDir" ||
             loc.kind === "projectDir" ||
             loc.kind === "postsDir" ||
+            loc.kind === "docsDir" ||
+            loc.kind === "pullsDir" ||
             loc.kind === "boardDir" ||
-            loc.kind === "boardColumnDir") {
+            loc.kind === "boardColumnDir" ||
+            loc.kind === "publicDir") {
             throw eisdir("open", norm);
         }
         if (loc.kind === "postFile") {
@@ -383,14 +519,25 @@ export class SforaFs {
                     return true;
                 case "projectDir":
                 case "postsDir":
+                case "docsDir":
+                case "pullsDir":
                 case "boardDir":
                     return await this.#projectExists(loc.slug);
+                case "publicDir":
+                case "roadmapFile":
+                    // Only present when the board is shared publicly.
+                    return ((await this.#projectExists(loc.slug)) &&
+                        (await this.#publicSlug(loc.slug)) != null);
                 case "boardColumnDir":
                     return ((await this.#projectExists(loc.slug)) &&
                         (await this.#columnExists(loc.slug, loc.column)));
                 case "postFile":
                     return (await this.#matchEntry(loc.slug, loc.dir, loc.filename)) !==
                         undefined;
+                case "docFile":
+                    return (await this.#matchNote(loc.slug, loc.filename)) !== undefined;
+                case "pullFile":
+                    return (await this.#matchPull(loc.slug, loc.number)) !== undefined;
                 case "boardCardFile":
                     return ((await this.#matchCard(loc.slug, loc.column, loc.filename)) !==
                         undefined);
@@ -441,10 +588,24 @@ export class SforaFs {
                     return this.#fileStat(new Date());
                 case "projectDir":
                 case "postsDir":
+                case "docsDir":
+                case "pullsDir":
                 case "boardDir":
                     if (!(await this.#projectExists(loc.slug)))
                         throw enoent("stat", norm);
                     return this.#dirStat();
+                case "publicDir":
+                    if (!(await this.#projectExists(loc.slug)))
+                        throw enoent("stat", norm);
+                    if ((await this.#publicSlug(loc.slug)) == null)
+                        throw enoent("stat", norm);
+                    return this.#dirStat();
+                case "roadmapFile":
+                    if (!(await this.#projectExists(loc.slug)))
+                        throw enoent("stat", norm);
+                    if ((await this.#publicSlug(loc.slug)) == null)
+                        throw enoent("stat", norm);
+                    return this.#fileStat(new Date());
                 case "boardColumnDir":
                     if (!(await this.#projectExists(loc.slug)))
                         throw enoent("stat", norm);
@@ -458,6 +619,18 @@ export class SforaFs {
                         throw enoent("stat", norm);
                     return this.#fileStat(new Date(entry.publishedAt || Date.now()));
                 }
+                case "docFile": {
+                    const note = await this.#matchNote(loc.slug, loc.filename);
+                    if (!note)
+                        throw enoent("stat", norm);
+                    return this.#fileStat(new Date(note.lastEditedAt || Date.now()));
+                }
+                case "pullFile": {
+                    const pull = await this.#matchPull(loc.slug, loc.number);
+                    if (!pull)
+                        throw enoent("stat", norm);
+                    return this.#fileStat(new Date(pull.updatedAt || Date.now()));
+                }
                 case "boardCardFile": {
                     const card = await this.#matchCard(loc.slug, loc.column, loc.filename);
                     if (!card)
@@ -505,20 +678,50 @@ export class SforaFs {
                     return [dirent("mentions.md", false)];
                 case "meDir":
                     return [dirent("api-key", false)];
-                case "projectDir":
+                case "projectDir": {
                     if (!(await this.#projectExists(loc.slug))) {
                         throw enoent("scandir", norm);
                     }
-                    return [
+                    const entries = [
                         dirent("board", true),
+                        dirent("docs", true),
                         dirent("drafts", true),
                         dirent("links.md", false),
                         dirent("posts", true),
+                        dirent("pulls", true),
                     ];
+                    // `public/` only appears once the board is shared publicly.
+                    if ((await this.#publicSlug(loc.slug)) != null) {
+                        entries.push(dirent("public", true));
+                    }
+                    return entries;
+                }
                 case "postsDir": {
                     const entries = await this.#listEntries(loc.slug, loc.dir);
                     return entries.map((e) => dirent(e.filename, false));
                 }
+                case "docsDir": {
+                    if (!(await this.#projectExists(loc.slug))) {
+                        throw enoent("scandir", norm);
+                    }
+                    const notes = await this.#listNotes(loc.slug);
+                    return notes.map((n) => dirent(n.filename, false));
+                }
+                case "pullsDir": {
+                    if (!(await this.#projectExists(loc.slug))) {
+                        throw enoent("scandir", norm);
+                    }
+                    const pulls = await this.#listPulls(loc.slug);
+                    return pulls.map((p) => dirent(`${p.number}.md`, false));
+                }
+                case "publicDir":
+                    if (!(await this.#projectExists(loc.slug))) {
+                        throw enoent("scandir", norm);
+                    }
+                    if ((await this.#publicSlug(loc.slug)) == null) {
+                        throw enoent("scandir", norm);
+                    }
+                    return [dirent("roadmap.md", false)];
                 case "boardDir": {
                     if (!(await this.#projectExists(loc.slug))) {
                         throw enoent("scandir", norm);
@@ -539,7 +742,10 @@ export class SforaFs {
                 case "inboxFile":
                 case "meFile":
                 case "postFile":
+                case "docFile":
+                case "pullFile":
                 case "boardCardFile":
+                case "roadmapFile":
                     throw enotdir("scandir", norm);
                 default:
                     throw enoent("scandir", norm);
@@ -565,7 +771,10 @@ export class SforaFs {
                 return;
             case "projectDir":
             case "postsDir":
+            case "docsDir":
+            case "pullsDir":
             case "boardDir":
+            case "publicDir":
                 if (await this.#projectExists(loc.slug))
                     return;
                 throw eacces("mkdir", norm);
@@ -649,6 +858,11 @@ export class SforaFs {
             }
             case "inboxFile":
             case "meFile":
+            case "docFile":
+            case "pullFile":
+            case "roadmapFile":
+                // Read-only surfaces (notes aren't deletable through the fs yet; the
+                // roadmap is a projection; pulls are owned by GitHub).
                 throw eacces("unlink", norm);
             case "root":
             case "projectsDir":
@@ -656,7 +870,10 @@ export class SforaFs {
             case "meDir":
             case "projectDir":
             case "postsDir":
+            case "docsDir":
+            case "pullsDir":
             case "boardDir":
+            case "publicDir":
                 // Top-level structural dirs can't be removed.
                 if (options?.recursive)
                     throw eperm("rm", norm);
@@ -767,7 +984,14 @@ export class SforaFs {
             paths.add(`/projects/${slug}`);
             paths.add(`/projects/${slug}/posts`);
             paths.add(`/projects/${slug}/drafts`);
+            paths.add(`/projects/${slug}/docs`);
+            paths.add(`/projects/${slug}/pulls`);
             paths.add(`/projects/${slug}/board`);
+            // `public/` is only real for boards known to be shared.
+            if (this.#sharedSlugs.has(slug)) {
+                paths.add(`/projects/${slug}/public`);
+                paths.add(`/projects/${slug}/public/roadmap.md`);
+            }
         }
         for (const [dirPath, filenames] of this.#entrySnapshots) {
             for (const name of filenames)

package/dist/api-client.d.ts

@@ -29,6 +29,33 @@ export interface WriteResult {
     filename: string;
     id: string;
 }
+/**
+ * A note (doc) file entry. Mirrors a row of `GET …/docs`. Notes have stable
+ * `<slug>.md` filenames (no date prefix) and no draft concept.
+ */
+export interface Note {
+    filename: string;
+    title: string;
+    lastEditedAt: number;
+}
+/**
+ * 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
+ * alongside posts/tasks/docs.
+ */
+export interface Pull {
+    number: number;
+    title: string;
+    state: "open" | "closed" | "merged";
+    draft: boolean;
+    author: string;
+    head: string;
+    base: string;
+    url: string;
+    additions?: number;
+    deletions?: number;
+    updatedAt: number;
+}
 /** A column directory under `/projects/<slug>/board/`. `dirname` is `NN-<slug>`. */
 export interface BoardColumn {
     dirname: string;
@@ -37,6 +64,14 @@ export interface BoardColumn {
     position: number;
     cardCount: number;
 }
+/**
+ * Board sharing state + columns. Mirrors `GET …/board`. `publicSlug` is the
+ * board's public roadmap slug, or `null` when the board isn't shared publicly.
+ */
+export interface BoardMeta {
+    publicSlug: string | null;
+    columns: BoardColumn[];
+}
 /** A card file under `/projects/<slug>/board/<col>/`. `filename` is `NNNN-<slug>.md`. */
 export interface BoardCardEntry {
     filename: string;
@@ -58,6 +93,13 @@ export interface SforaApiConfig {
     baseUrl: string;
     /** Agent API key (`sk_…`). Sent as `Authorization: Bearer <apiKey>`. */
     apiKey: string;
+    /**
+     * Act as another agent you own (or any, if you're an org admin), using this
+     * key. Sent as `X-Sfora-Act-As: <name-or-id>`. Lets one authorized CLI
+     * attribute work to different agents — run several on one device without a
+     * key per agent.
+     */
+    actAs?: string;
 }
 /** Non-2xx response from the fs API. Carries the HTTP status + machine code so SforaFs can map it to an errno. */
 export declare class SforaApiError extends Error {
@@ -90,6 +132,22 @@ export declare class SforaApiClient {
     writePost(projectSlug: string, kind: PostKind, filename: string, markdown: string): Promise<WriteResult>;
     /** `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>;
+    /** `GET …/pulls` — the project's synced pull requests, open first. */
+    listPulls(projectSlug: string): Promise<Pull[]>;
+    /**
+     * `GET …/pulls/:number` — one PR as markdown: metadata, the cards it resolves,
+     * and the unified diff. Returns the raw markdown body.
+     */
+    readPull(projectSlug: string, number: number): Promise<string>;
+    /**
+     * `GET …/board` — board sharing state + columns (auto-creates the board on
+     * first call). `publicSlug` is null unless the board is shared publicly.
+     */
+    getBoardMeta(projectSlug: string): Promise<BoardMeta>;
     /** `GET …/board` — list the project's columns (auto-creates the board on first call). */
     listColumns(projectSlug: string): Promise<BoardColumn[]>;
     /** `GET …/board/:column` — list cards in a column. `column` is the `NN-slug` dirname. */
@@ -120,6 +178,18 @@ export declare class SforaApiClient {
      * card across columns without changing its body. Used by `mv` in the shell.
      */
     moveCard(projectSlug: string, fromCol: string, filename: string, toCol: string): Promise<CardWriteResult>;
+    /** `POST /v1/posts/:postId/comments` — add a comment to a post. */
+    createComment(postId: string, body: string): Promise<{
+        id: string;
+    }>;
+    /**
+     * `POST /v1/posts/:postId/reactions` — toggle an emoji reaction on a post.
+     * Returns whether the reaction is now on (`reacted: true`) or off.
+     */
+    reactToPost(postId: string, emoji: string): Promise<{
+        content: string;
+        reacted: boolean;
+    }>;
     /** `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). */