sfora-cli 0.5.0 → 0.7.0

package/README.md

@@ -48,12 +48,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 +67,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 +189,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.js

@@ -73,6 +73,9 @@ function classify(path) {
         if (seg.length === 2)
             return { kind: "projectDir", slug };
         const dir = seg[2];
+        if (dir === "links.md" && seg.length === 3) {
+            return { kind: "linksFile", slug };
+        }
         if (dir === "posts" || dir === "drafts") {
             if (seg.length === 3)
                 return { kind: "postsDir", slug, dir };
@@ -276,6 +279,13 @@ export class SforaFs {
                 catch (e) {
                     throw fromApi(e, "open", normalize(path));
                 }
+            case "linksFile":
+                try {
+                    return await this.#client.getProjectLinks(loc.slug);
+                }
+                catch (e) {
+                    throw fromApi(e, "open", normalize(path));
+                }
             case "root":
             case "projectsDir":
             case "inboxDir":
@@ -306,6 +316,15 @@ export class SforaFs {
         if (loc.kind === "inboxFile" || loc.kind === "meFile") {
             throw eacces("open", norm);
         }
+        if (loc.kind === "linksFile") {
+            try {
+                await this.#client.setProjectLinks(loc.slug, toText(content));
+            }
+            catch (e) {
+                throw fromApi(e, "open", norm);
+            }
+            return;
+        }
         if (loc.kind === "root" ||
             loc.kind === "projectsDir" ||
             loc.kind === "inboxDir" ||
@@ -416,6 +435,10 @@ export class SforaFs {
                 case "inboxFile":
                 case "meFile":
                     return this.#fileStat(new Date());
+                case "linksFile":
+                    if (!(await this.#projectExists(loc.slug)))
+                        throw enoent("stat", norm);
+                    return this.#fileStat(new Date());
                 case "projectDir":
                 case "postsDir":
                 case "boardDir":
@@ -489,6 +512,7 @@ export class SforaFs {
                     return [
                         dirent("board", true),
                         dirent("drafts", true),
+                        dirent("links.md", false),
                         dirent("posts", true),
                     ];
                 case "postsDir": {

package/dist/api-client.d.ts

@@ -75,6 +75,10 @@ export declare class SforaApiClient {
         slug: string;
         name: string;
     }>;
+    /** `GET …/links.md` — the project's external links as markdown. */
+    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 …/posts` or `…/drafts`. `scheduled` lists drafts that have a
      * (future) `scheduledFor` set.
@@ -116,6 +120,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). */

package/dist/api-client.js

@@ -90,6 +90,14 @@ export class SforaApiClient {
         const res = await this.#request("POST", "/v1/fs/projects", JSON.stringify({ name }));
         return (await res.json());
     }
+    /** `GET …/links.md` — the project's external links as markdown. */
+    async getProjectLinks(slug) {
+        return this.#text(`/v1/fs/projects/${encodeURIComponent(slug)}/links.md`);
+    }
+    /** `PUT …/links.md` — replace the project's links from a markdown list. */
+    async setProjectLinks(slug, markdown) {
+        await this.#request("PUT", `/v1/fs/projects/${encodeURIComponent(slug)}/links.md`, markdown);
+    }
     /**
      * `GET …/posts` or `…/drafts`. `scheduled` lists drafts that have a
      * (future) `scheduledFor` set.
@@ -231,6 +239,40 @@ export class SforaApiClient {
             throw await this.#toError(res);
         return (await res.json());
     }
+    // ─── Post actions (comment / react) ─────────────────────────────
+    /** `POST /v1/posts/:postId/comments` — add a comment to a post. */
+    async createComment(postId, body) {
+        const res = await fetch(`${this.#baseUrl}/v1/posts/${encodeURIComponent(postId)}/comments`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.#apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ body }),
+        });
+        if (!res.ok)
+            throw await this.#toError(res);
+        const data = (await res.json());
+        return { id: data.comment?._id ?? "" };
+    }
+    /**
+     * `POST /v1/posts/:postId/reactions` — toggle an emoji reaction on a post.
+     * Returns whether the reaction is now on (`reacted: true`) or off.
+     */
+    async reactToPost(postId, emoji) {
+        const res = await fetch(`${this.#baseUrl}/v1/posts/${encodeURIComponent(postId)}/reactions`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.#apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ emoji }),
+        });
+        if (!res.ok)
+            throw await this.#toError(res);
+        const data = (await res.json());
+        return data.reaction ?? { content: emoji, reacted: true };
+    }
     /** `GET /v1/fs/inbox/mentions.md` — markdown summary of unread mentions. */
     async readInbox() {
         return this.#text("/v1/fs/inbox/mentions.md");

package/dist/cli.js

@@ -24,7 +24,7 @@ const colors = {
     red: "\x1b[31m",
 };
 function parseArgs(argv) {
-    const args = { rest: [], cwd: "/", mcp: false, help: false, draft: false };
+    const args = { rest: [], cwd: "/", mcp: false, help: false, draft: false, json: false };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === "--mcp")
@@ -67,6 +67,8 @@ function parseArgs(argv) {
             args.column = a.slice("--column=".length);
         else if (a === "--draft")
             args.draft = true;
+        else if (a === "--json")
+            args.json = true;
         else if (!a.startsWith("-")) {
             if (!args.command)
                 args.command = a;
@@ -89,15 +91,27 @@ Push markdown straight to sfora:
   sfora task <file.md> [--project <slug>] [--column <name>]   Create a task
   sfora doc  <file.md> [--project <slug>]             Create a doc
 
+Act on a post:
+  sfora comment <post> "<message>"    Comment on a post
+  sfora react <post> <emoji>          Toggle a reaction (👍 🚀 …)
+  (<post> is a post file path or its id)
+
 Projects:
   sfora new "<name>"                  Create a project
   sfora projects                      List your projects
 
-Browse:
+Browse & read:
+  sfora posts <project>               List a project's posts
+  sfora tasks <project>               List a project's board, by column
+  sfora inbox                         Show your unread mentions
+  sfora me                            Show who you're signed in as
   sfora ls [path]                     List a path (default /projects)
   sfora cat <path>                    Print a file's markdown
   sfora                               Open the interactive shell
 
+  Add --json to any list command (projects/posts/tasks/ls/me) for
+  machine-readable output and stable scripting.
+
 Agents & config:
   sfora --mcp [--org <slug>]          Run as an MCP server (for agents)
   sfora mcp-config                    Print an MCP config snippet to paste
@@ -106,6 +120,34 @@ Agents & config:
 Config resolution: flags > env (SFORA_API_KEY / SFORA_URL / SFORA_ORG) >
 ~/.sfora/config.json > default (URL ${DEFAULT_URL}).
 `;
+// In-shell `help` (and `?`). The underlying engine (just-bash) ships its own
+// `help` builtin that prints "just-bash shell builtins" — internal branding we
+// never want users to see, and it can't be overridden via the command registry
+// (it's a hardcoded interpreter builtin). So the REPL intercepts `help` and
+// prints this sfora-native cheat sheet instead.
+const SHELL_HELP = `${colors.bold}sfora shell${colors.reset} ${colors.dim}— your workspace as a markdown filesystem${colors.reset}
+
+Standard tools work against your workspace:
+  ls   cat   grep   find   head   tail   wc   sed   awk   echo   cd   pwd
+
+${colors.dim}Where things live${colors.reset}
+  /projects                          your projects
+  /projects/<slug>/posts/<file>.md   published posts
+  /projects/<slug>/drafts/           drafts
+  /projects/<slug>/board/<col>/      board tasks
+  /projects/<slug>/docs/             docs
+  /inbox/mentions.md                 your mentions
+  /me/api-key                        who you're signed in as
+
+${colors.dim}Try${colors.reset}
+  ls /projects
+  cat /projects/<slug>/posts/<file>.md
+  grep -ri todo /projects
+  echo "# Hello" > /projects/<slug>/posts/hello.md
+
+${colors.dim}Outside the shell${colors.reset}, sfora has verbs: post · task · doc · new · projects   (run ${colors.cyan}sfora --help${colors.reset})
+Type ${colors.cyan}exit${colors.reset} to quit.
+`;
 // `sfora init` — persist url/apiKey/org to ~/.sfora/config.json. Uses flags
 // when given, otherwise prompts (on a TTY), defaulting to any existing config.
 async function runInit(args) {
@@ -263,6 +305,18 @@ async function resolveProject(fs, flag, md) {
         return slugs[0];
     throw new Error(`specify --project <slug>${slugs.length ? ` (yours: ${slugs.join(", ")})` : ""}`);
 }
+// A post reference can be a file path (we read its `id:` frontmatter) or a bare
+// post id. So `sfora comment /projects/x/posts/y.md "hi"` and `sfora comment
+// <id> "hi"` both work.
+async function resolvePostId(fs, ref) {
+    if (!ref.includes("/"))
+        return ref;
+    const md = await fs.readFile(ref, "utf8");
+    const id = frontmatterValue(md, "id");
+    if (!id)
+        throw new Error(`no post id found in ${ref} (is it a post file?)`);
+    return id;
+}
 const VERBS = new Set([
     "projects",
     "new",
@@ -271,12 +325,31 @@ const VERBS = new Set([
     "post",
     "task",
     "doc",
+    "posts",
+    "tasks",
+    "inbox",
+    "mentions",
+    "me",
+    "whoami",
+    "comment",
+    "react",
 ]);
 async function runVerb(args, fs, client) {
     const ok = (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`);
+    const emitJson = (v) => console.log(JSON.stringify(v, null, 2));
+    const plural = (n, w) => `${n} ${w}${n === 1 ? "" : "s"}`;
     if (args.command === "projects") {
-        const slugs = await fs.readdir("/projects");
-        console.log(slugs.length ? slugs.join("\n") : "(no projects)");
+        const projects = await client.listProjects();
+        if (args.json)
+            return emitJson(projects);
+        if (projects.length === 0) {
+            console.log(`${colors.dim}(no projects)${colors.reset}`);
+            return;
+        }
+        const width = Math.max(...projects.map((p) => p.name.length));
+        for (const p of projects) {
+            console.log(`${p.name.padEnd(width)}  ${colors.dim}${p.slug} · ${plural(p.postCount, "post")}${colors.reset}`);
+        }
         return;
     }
     if (args.command === "new") {
@@ -289,6 +362,8 @@ async function runVerb(args, fs, client) {
     }
     if (args.command === "ls") {
         const entries = await fs.readdir(args.rest[0] ?? "/projects");
+        if (args.json)
+            return emitJson(entries);
         console.log(entries.join("\n"));
         return;
     }
@@ -298,6 +373,91 @@ async function runVerb(args, fs, client) {
         process.stdout.write(await fs.readFile(args.rest[0], "utf8"));
         return;
     }
+    if (args.command === "me" || args.command === "whoami") {
+        const text = (await client.readMe()).trim();
+        if (args.json) {
+            const obj = {};
+            for (const ln of text.split("\n")) {
+                const m = /^([a-zA-Z][\w-]*):\s*(.*)$/.exec(ln);
+                if (m)
+                    obj[m[1]] = m[2];
+            }
+            return emitJson(obj);
+        }
+        console.log(text);
+        return;
+    }
+    if (args.command === "inbox" || args.command === "mentions") {
+        const md = (await client.readInbox()).trim();
+        if (args.json)
+            return emitJson({ markdown: md });
+        console.log(md || `${colors.dim}(no unread mentions)${colors.reset}`);
+        return;
+    }
+    if (args.command === "posts") {
+        const slug = args.project ?? args.rest[0];
+        if (!slug)
+            throw new Error("usage: sfora posts <project> [--json]");
+        const entries = await client.listPosts(slug);
+        if (args.json)
+            return emitJson(entries);
+        if (entries.length === 0) {
+            console.log(`${colors.dim}(no posts)${colors.reset}`);
+            return;
+        }
+        for (const e of entries) {
+            const flag = e.isDraft ? `${colors.yellow}draft${colors.reset} ` : "";
+            console.log(`${flag}${e.title}  ${colors.dim}${e.filename}${colors.reset}`);
+        }
+        return;
+    }
+    if (args.command === "tasks") {
+        const slug = args.project ?? args.rest[0];
+        if (!slug)
+            throw new Error("usage: sfora tasks <project> [--json]");
+        const columns = await client.listColumns(slug);
+        const board = await Promise.all(columns.map(async (col) => ({
+            column: col.name,
+            dirname: col.dirname,
+            cards: await client.listCards(slug, col.dirname),
+        })));
+        if (args.json)
+            return emitJson(board);
+        for (const group of board) {
+            console.log(`${colors.bold}${group.column}${colors.reset} ${colors.dim}(${group.cards.length})${colors.reset}`);
+            for (const c of group.cards) {
+                const dot = c.status === "closed"
+                    ? colors.green
+                    : c.status === "active"
+                        ? colors.cyan
+                        : colors.dim;
+                console.log(`  ${dot}●${colors.reset} ${colors.dim}#${c.number}${colors.reset} ${c.title}`);
+            }
+            if (group.cards.length === 0)
+                console.log(`  ${colors.dim}(empty)${colors.reset}`);
+        }
+        return;
+    }
+    if (args.command === "comment") {
+        const ref = args.rest[0];
+        const text = args.rest.slice(1).join(" ").trim();
+        if (!ref || !text)
+            throw new Error('usage: sfora comment <post> "<message>"');
+        const postId = await resolvePostId(fs, ref);
+        await client.createComment(postId, text);
+        ok(`Commented on ${ref}`);
+        return;
+    }
+    if (args.command === "react") {
+        const ref = args.rest[0];
+        const emoji = args.rest[1];
+        if (!ref || !emoji)
+            throw new Error("usage: sfora react <post> <emoji>");
+        const postId = await resolvePostId(fs, ref);
+        const r = await client.reactToPost(postId, emoji);
+        ok(`${r.reacted ? "Reacted" : "Removed reaction"} ${emoji} on ${ref}`);
+        return;
+    }
     // post / task / doc — push a local markdown file into the workspace.
     const file = args.rest[0];
     if (!file) {
@@ -394,7 +554,7 @@ async function main() {
         return;
     }
     const org = settings.org;
-    const { bash } = createSforaShell({ baseUrl, apiKey, org, cwd: args.cwd });
+    const { bash, fs } = createSforaShell({ baseUrl, apiKey, org, cwd: args.cwd });
     // Shell state threaded across exec() calls — just-bash does not persist cwd/env
     // between separate exec()s, so we carry them forward ourselves.
     let cwd = args.cwd;
@@ -418,7 +578,7 @@ async function main() {
     else {
         console.log(`${colors.yellow}warning:${colors.reset} could not reach ${baseUrl} or authenticate — commands may fail.`);
     }
-    console.log(`${colors.dim}Try: ls /projects · cat /projects/<slug>/posts/<file>.md · cat /inbox/mentions.md · 'exit' to quit${colors.reset}\n`);
+    console.log(`${colors.dim}Try: ls /projects · cat /inbox/mentions.md · ${colors.reset}${colors.cyan}help${colors.reset}${colors.dim} for commands · ${colors.reset}${colors.cyan}exit${colors.reset}${colors.dim} to quit${colors.reset}\n`);
     // Iterate stdin as an async iterable. This pattern serializes lines even
     // when stdin is piped (buffered) — the `for await` body completes before the
     // next line is consumed, and EOF naturally falls through to process exit
@@ -427,10 +587,46 @@ async function main() {
     // readline fired 'close' (→ process.exit(0)) while the first exec's PUT was
     // still in flight.
     const isTty = Boolean(process.stdin.isTTY);
+    // Tab completion: command names on the first token, workspace paths after.
+    // Path hits read the live fs, so completing `/projects/<Tab>` lists projects.
+    const COMMANDS = [
+        "ls", "cat", "cd", "pwd", "grep", "find", "echo", "head", "tail", "wc",
+        "sed", "awk", "sort", "uniq", "mkdir", "rm", "mv", "cp", "touch", "help",
+        "exit",
+    ];
+    async function completePath(token) {
+        const slash = token.lastIndexOf("/");
+        const dir = slash >= 0 ? token.slice(0, slash + 1) : "";
+        const prefix = slash >= 0 ? token.slice(slash + 1) : token;
+        const base = dir.startsWith("/")
+            ? dir || "/"
+            : `${cwd.replace(/\/+$/, "")}/${dir}`;
+        let names = [];
+        try {
+            names = await fs.readdir(base || "/");
+        }
+        catch {
+            return [];
+        }
+        return names.filter((n) => n.startsWith(prefix)).map((n) => dir + n);
+    }
+    const completer = (line, cb) => {
+        const tokens = line.split(/\s+/);
+        const last = tokens[tokens.length - 1] ?? "";
+        if (tokens.length <= 1) {
+            const hits = COMMANDS.filter((c) => c.startsWith(last));
+            cb(null, [hits.length ? hits : COMMANDS, last]);
+            return;
+        }
+        completePath(last)
+            .then((hits) => cb(null, [hits, last]))
+            .catch(() => cb(null, [[], last]));
+    };
     const rl = readline.createInterface({
         input: process.stdin,
         output: process.stdout,
         terminal: isTty,
+        completer,
     });
     const promptText = () => `${colors.cyan}sfora${colors.reset}:${colors.blue}${cwd}${colors.reset}$ `;
     // Print the first prompt; subsequent ones are printed after each handled line.
@@ -445,12 +641,21 @@ async function main() {
         }
         if (line === "exit" || line === "quit")
             break;
+        // Show sfora's own help instead of just-bash's builtin help banner.
+        if (line === "help" || line === "?" || line.startsWith("help ")) {
+            process.stdout.write(SHELL_HELP);
+            if (isTty)
+                process.stdout.write(promptText());
+            continue;
+        }
         try {
             const res = await bash.exec(line, { cwd, env });
             if (res.stdout)
                 process.stdout.write(res.stdout);
+            // Rewrite the engine's "bash:" error prefix to "sfora:" so the shell
+            // reads as native — the user never typed `bash`.
             if (res.stderr)
-                process.stderr.write(res.stderr);
+                process.stderr.write(res.stderr.replace(/^bash:/gm, "sfora:"));
             env = res.env;
             cwd = res.env?.PWD ?? cwd;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sfora-cli",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "Your sfora workspace as a markdown filesystem — a CLI + MCP server. Post/task/doc, ls/cat/grep, and a shell so agents operate sfora natively.",
   "keywords": [