sfora-cli 0.1.0 → 0.2.0

package/README.md

@@ -1,14 +1,19 @@
-# sfora
+# sfora-cli
 
-A real **bash shell + MCP server over your sfora workspace** — where every
-post, task, and doc is a markdown file. `ls` / `cat` / `grep` / `echo >` / `rm`
-all work against them over sfora's `/v1/fs` agent API. Ships both an interactive
-REPL (`sfora`) and an **MCP stdio server** (`--mcp`) so agents in Claude / Cursor
-get the same shell as a tool — they're first-class operators, not an integration.
+**Your sfora workspace as a markdown filesystem** — a Linear for your agents.
+Every post, task, and doc is a markdown file under `/projects/<slug>/…`, so you
+(and your agents) can `post`, `task`, `doc`, `ls`, `cat`, and `grep` your work —
+or `echo >` straight into it. Ships first-class verbs, an interactive shell, and
+an **MCP server** (`--mcp`) so agents in Claude / Cursor operate sfora natively.
 
-It's built on [`just-bash`](https://www.npmjs.com/package/just-bash) (a sandboxed
-TypeScript bash interpreter) with a custom `Fs` backend, `SforaFs`, that lazily
-maps filesystem operations onto HTTP calls.
+```bash
+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
+```
+
+Under the hood it maps a Unix view onto sfora's `/v1/fs` HTTP API (a sandboxed
+shell interpreter backs the interactive mode).
 
 ```
 /

package/dist/cli.js

@@ -8,6 +8,8 @@
  */
 import * as readline from "node:readline";
 import { spawn } from "node:child_process";
+import { readFile as readLocalFile } from "node:fs/promises";
+import { basename } from "node:path";
 import { createSforaShell } from "./index.js";
 import { runMcpServer } from "./mcp-server.js";
 import { readConfig, writeConfig, resolveSettings, DEFAULT_URL, } from "./config.js";
@@ -22,7 +24,7 @@ const colors = {
     red: "\x1b[31m",
 };
 function parseArgs(argv) {
-    const args = { cwd: "/", mcp: false, help: false };
+    const args = { rest: [], cwd: "/", mcp: false, help: false, draft: false };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === "--mcp")
@@ -53,32 +55,48 @@ function parseArgs(argv) {
             args.web = argv[++i];
         else if (a.startsWith("--web="))
             args.web = a.slice("--web=".length);
-        else if (!a.startsWith("-") && !args.command)
-            args.command = a;
+        else if (a === "--project")
+            args.project = argv[++i];
+        else if (a.startsWith("--project="))
+            args.project = a.slice("--project=".length);
+        else if (a === "--column")
+            args.column = argv[++i];
+        else if (a.startsWith("--column="))
+            args.column = a.slice("--column=".length);
+        else if (a === "--draft")
+            args.draft = true;
+        else if (!a.startsWith("-")) {
+            if (!args.command)
+                args.command = a;
+            else
+                args.rest.push(a);
+        }
     }
     return args;
 }
-const HELP = `sfora — a bash shell over your sfora workspace (and an MCP server)
+const HELP = `sfora — the CLI for your sfora workspace
 
-Usage:
+Get started:
   sfora login [--agent <name>]        Authorize via the browser (saves a key)
-  sfora init                          Save URL + API key + org manually
-  sfora [--org <slug>] [--cwd <path>] Interactive shell
-  sfora --mcp [--org <slug>]          MCP stdio server (for agents)
-  sfora mcp-config                    Print an MCP config snippet to paste
 
-Config (resolution: flags > env > ~/.sfora/config.json > default):
-  SFORA_API_KEY   Agent API key (sfora_ak_…)   [required]
-  SFORA_URL       Deployment base URL          [default ${DEFAULT_URL}]
-  SFORA_ORG       Default org slug
+Push markdown straight to sfora:
+  sfora post <file.md> [--project <slug>] [--draft]   Publish (or draft) a post
+  sfora task <file.md> [--project <slug>] [--column <name>]   Create a task
+  sfora doc  <file.md> [--project <slug>]             Create a doc
+
+Browse:
+  sfora projects                      List your projects
+  sfora ls [path]                     List a path (default /projects)
+  sfora cat <path>                    Print a file's markdown
+  sfora                               Open the interactive shell
 
-Options:
-  --org <slug>    Workspace/org slug (shown in the prompt)
-  --cwd <path>    Starting directory in the virtual fs (default /)
-  --url <url>     Override the deployment URL
-  --key <key>     Override the API key
-  --mcp           Run as an MCP server over stdio instead of a REPL
-  -h, --help      Show this help
+Agents & config:
+  sfora --mcp [--org <slug>]          Run as an MCP server (for agents)
+  sfora mcp-config                    Print an MCP config snippet to paste
+  sfora init                          Save URL + API key + org manually
+
+Config resolution: flags > env (SFORA_API_KEY / SFORA_URL / SFORA_ORG) >
+~/.sfora/config.json > default (URL ${DEFAULT_URL}).
 `;
 // `sfora init` — persist url/apiKey/org to ~/.sfora/config.json. Uses flags
 // when given, otherwise prompts (on a TTY), defaulting to any existing config.
@@ -202,6 +220,90 @@ function printMcpConfig(s) {
     };
     process.stdout.write(`${JSON.stringify(snippet, null, 2)}\n`);
 }
+// ─── Structured verbs (post / task / doc / ls / cat / projects) ──
+// These talk to the workspace over the same /v1/fs the app + agents use, so the
+// CLI is a real product interface — not a generic shell.
+function frontmatterValue(md, key) {
+    const m = md.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!m)
+        return undefined;
+    const line = m[1]
+        .split("\n")
+        .find((l) => l.trim().toLowerCase().startsWith(`${key}:`));
+    if (!line)
+        return undefined;
+    return line
+        .slice(line.indexOf(":") + 1)
+        .trim()
+        .replace(/^["']|["']$/g, "");
+}
+async function resolveProject(fs, flag, md) {
+    const chosen = flag ?? frontmatterValue(md, "project");
+    if (chosen)
+        return chosen;
+    const slugs = await fs.readdir("/projects").catch(() => []);
+    if (slugs.length === 1)
+        return slugs[0];
+    throw new Error(`specify --project <slug>${slugs.length ? ` (yours: ${slugs.join(", ")})` : ""}`);
+}
+const VERBS = new Set(["projects", "ls", "cat", "post", "task", "doc"]);
+async function runVerb(args, fs) {
+    const ok = (msg) => console.log(`${colors.green}✓${colors.reset} ${msg}`);
+    if (args.command === "projects") {
+        const slugs = await fs.readdir("/projects");
+        console.log(slugs.length ? slugs.join("\n") : "(no projects)");
+        return;
+    }
+    if (args.command === "ls") {
+        const entries = await fs.readdir(args.rest[0] ?? "/projects");
+        console.log(entries.join("\n"));
+        return;
+    }
+    if (args.command === "cat") {
+        if (!args.rest[0])
+            throw new Error("usage: sfora cat <path>");
+        process.stdout.write(await fs.readFile(args.rest[0], "utf8"));
+        return;
+    }
+    // post / task / doc — push a local markdown file into the workspace.
+    const file = args.rest[0];
+    if (!file) {
+        throw new Error(`usage: sfora ${args.command} <file.md> [--project <slug>]`);
+    }
+    const md = await readLocalFile(file, "utf8");
+    const project = await resolveProject(fs, args.project, md);
+    const base = basename(file);
+    const name = base.endsWith(".md") ? base : `${base}.md`;
+    if (args.command === "post") {
+        const dir = args.draft ? "drafts" : "posts";
+        await fs.writeFile(`/projects/${project}/${dir}/${name}`, md);
+        ok(`${args.draft ? "Drafted" : "Posted"} to ${project} · ${name}`);
+        return;
+    }
+    if (args.command === "doc") {
+        await fs.writeFile(`/projects/${project}/docs/${name}`, md);
+        ok(`Doc saved to ${project} · ${name}`);
+        return;
+    }
+    if (args.command === "task") {
+        const cols = await fs
+            .readdir(`/projects/${project}/board`)
+            .catch(() => []);
+        if (cols.length === 0)
+            throw new Error(`no board columns in ${project}`);
+        let col = cols[0];
+        if (args.column) {
+            const want = args.column
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/g, "-")
+                .replace(/^-|-$/g, "");
+            col = cols.find((c) => c.replace(/^\d+-/, "") === want) ?? col;
+        }
+        await fs.writeFile(`/projects/${project}/board/${col}/${name}`, md);
+        ok(`Task created in ${project} / ${col} · ${name}`);
+        return;
+    }
+}
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (args.help) {
@@ -225,10 +327,26 @@ async function main() {
     }
     if (!apiKey) {
         process.stderr.write(`${colors.red}error:${colors.reset} no API key found.\n` +
-            `Run \`sfora init\` to save one, or set SFORA_API_KEY.\n`);
+            `Run \`sfora login\` to authorize, or \`sfora init\` to set one.\n`);
         process.exitCode = 1;
         return;
     }
+    // Structured verbs — the workspace as a markdown filesystem.
+    if (args.command && VERBS.has(args.command)) {
+        const { fs } = createSforaShell({
+            baseUrl,
+            apiKey,
+            org: settings.org ?? "",
+        });
+        try {
+            await runVerb(args, fs);
+        }
+        catch (e) {
+            process.stderr.write(`${colors.red}error:${colors.reset} ${e instanceof Error ? e.message : String(e)}\n`);
+            process.exitCode = 1;
+        }
+        return;
+    }
     // MCP mode: stdout is the protocol channel — never write logs there.
     if (args.mcp) {
         await runMcpServer({ baseUrl, apiKey, org: settings.org ?? "" });
@@ -253,7 +371,7 @@ async function main() {
     catch {
         identity = "";
     }
-    console.log(`${colors.cyan}${colors.bold}sfora${colors.reset} ${colors.dim}— bash over ${baseUrl} (org: ${org})${colors.reset}`);
+    console.log(`${colors.cyan}${colors.bold}sfora${colors.reset} ${colors.dim}— your workspace as a markdown filesystem · ${baseUrl} (org: ${org})${colors.reset}`);
     if (identity) {
         const who = identity
             .split("\n")

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 /**
- * sfora — a real bash shell mounted on sfora posts.
+ * sfora — your workspace as a markdown filesystem.
  *
- * `createSforaShell` wires the `/v1/fs` HTTP API into a {@link SforaFs} and
- * hands it to a just-bash {@link Bash} instance, so `ls`/`cat`/`grep`/`echo >`
- * all work against your workspace's posts.
+ * Every post, task, and doc is a markdown file under `/projects/<slug>/…`.
+ * `createSforaShell` wires the `/v1/fs` HTTP API into a {@link SforaFs} and a
+ * sandboxed shell interpreter, so `ls`/`cat`/`grep`/`echo >` work against your
+ * workspace. The CLI also exposes first-class verbs (post/task/doc) and an MCP
+ * server so agents operate sfora natively.
  */
 import { Bash } from "just-bash";
 import { SforaFs } from "./SforaFs.js";

package/dist/index.js

@@ -1,9 +1,11 @@
 /**
- * sfora — a real bash shell mounted on sfora posts.
+ * sfora — your workspace as a markdown filesystem.
  *
- * `createSforaShell` wires the `/v1/fs` HTTP API into a {@link SforaFs} and
- * hands it to a just-bash {@link Bash} instance, so `ls`/`cat`/`grep`/`echo >`
- * all work against your workspace's posts.
+ * Every post, task, and doc is a markdown file under `/projects/<slug>/…`.
+ * `createSforaShell` wires the `/v1/fs` HTTP API into a {@link SforaFs} and a
+ * sandboxed shell interpreter, so `ls`/`cat`/`grep`/`echo >` work against your
+ * workspace. The CLI also exposes first-class verbs (post/task/doc) and an MCP
+ * server so agents operate sfora natively.
  */
 import { Bash } from "just-bash";
 import { SforaApiClient } from "./api-client.js";

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "sfora-cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
-  "description": "A real bash shell + MCP server over your sfora workspace — every post, task, and doc is a markdown file your agents can ls/cat/grep/write.",
+  "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": [
     "sfora",
     "mcp",