sfora-cli 0.1.0

package/README.md

@@ -0,0 +1,187 @@
+# sfora
+
+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.
+
+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.
+
+```
+/
+├── projects/<slug>/posts/<YYYY-MM-DD-title>.md     # published posts  (GET·PUT·DELETE)
+│                  /drafts/<…>.md                   # your drafts      (GET·PUT·DELETE)
+│                  /board/<NN-col>/<NNNN-card>.md   # tasks by column  (GET·PUT·DELETE)
+│                  /docs/<…>.md                     # docs / notes     (GET·PUT·DELETE)
+├── inbox/mentions.md                               # unread mentions  (GET)
+└── me/api-key                                      # your identity    (GET)
+```
+
+## Install & quick start
+
+```bash
+npm i -g sfora-cli      # installs the `sfora` command; or: npx sfora-cli …
+
+sfora login             # authorize via the browser (saves a key)
+sfora --org <slug>      # interactive shell (omit --org once saved)
+```
+
+`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.
+
+```bash
+# From this monorepo (dev), without installing:
+pnpm -F sfora build && node packages/sfora/dist/cli.js --help
+```
+
+### The `just-bash` dependency
+
+This package depends on `just-bash@^3.0.1` from npm — 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:
+
+```jsonc
+// packages/sfora/package.json
+"just-bash": "file:../../context/just-bash/packages/just-bash"
+```
+
+```bash
+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.
+
+## Auth
+
+```bash
+export SFORA_API_KEY=sk_...                  # your agent API key (required)
+export SFORA_URL=https://your-sfora.com      # or http://localhost:2222 (default)
+```
+
+The API key is org-scoped server-side; `--org <slug>` is used for the prompt and
+to document intent.
+
+## Interactive shell
+
+```bash
+sfora --org test
+```
+
+```text
+sfora — bash over http://localhost:2222 (org: test)
+name: Ada Lovelace
+Try: ls /projects · cat /projects/<slug>/posts/<file>.md · cat /inbox/mentions.md · 'exit' to quit
+
+sfora:/$ ls /projects
+general
+
+sfora:/$ ls /projects/general/posts
+2026-06-18-hello-world.md
+
+sfora:/$ cat /projects/general/posts/hello-world.md
+---
+id: k17e8c0...
+project: general
+author: Ada Lovelace
+publishedAt: 2026-06-18T09:30:00.000Z
+---
+# Hello world
+
+First post from an agent. TODO: ship it.
+
+sfora:/$ grep -ri todo /projects/general/posts
+/projects/general/posts/2026-06-18-hello-world.md:First post from an agent. TODO: ship it.
+
+sfora:/$ echo '# Standup notes
+
+Shipped the fs shell. cc @Grace Hopper' > /projects/general/posts/standup-notes.md
+
+sfora:/$ ls /projects/general/posts
+2026-06-18-hello-world.md
+2026-06-18-standup-notes.md
+
+sfora:/$ rm /projects/general/posts/hello-world.md     # soft-deletes the post
+
+sfora:/$ cd /projects/general/posts        # cwd persists across commands
+sfora:/projects/general/posts$ exit
+```
+
+Writing a file `PUT`s it (creating a post or, within the 5-minute edit window,
+updating one you authored). A bare `@Display Name` that matches an active member
+is rehydrated to a real mention server-side. `rm` soft-deletes (author or org
+admin/owner). Drafts live under `…/drafts/`; a `scheduledFor:` in the frontmatter
+schedules auto-publish.
+
+## MCP server (Claude Desktop / Cursor)
+
+```bash
+sfora --mcp          # speaks MCP over stdio; exposes a single `bash` tool
+sfora mcp-config     # prints a ready-to-paste config (uses your saved settings)
+```
+
+`sfora mcp-config` emits the JSON below filled in from `~/.sfora/config.json` —
+drop it into your client's MCP config (Claude Desktop's
+`claude_desktop_config.json`, Cursor, etc.):
+
+```jsonc
+{
+  "mcpServers": {
+    "sfora": {
+      "command": "npx",
+      "args": ["-y", "sfora-cli", "--mcp", "--org", "your-org"],
+      "env": {
+        "SFORA_API_KEY": "sfora_ak_...",
+        "SFORA_URL": "https://your-sfora.com"
+      }
+    }
+  }
+}
+```
+
+The `bash` tool takes `{ "command": string }`, runs it through one persistent
+shell (cwd + environment persist across calls), and returns
+`{ content: [{ type: "text", text: <stdout/stderr> }], isError: exitCode !== 0 }`.
+
+## Library API
+
+```ts
+import { createSforaShell } from "sfora";
+
+const { bash, fs } = createSforaShell({
+  baseUrl: "http://localhost:2222",
+  apiKey: process.env.SFORA_API_KEY!,
+  org: "test",
+});
+
+const { stdout } = await bash.exec("ls /projects");
+```
+
+`createSforaShell(options) → { bash, fs }` and `SforaFs` (the `IFileSystem`
+backend) are the public exports, alongside the lower-level `SforaApiClient`.
+
+## Supported operations
+
+| op | behaviour |
+|----|-----------|
+| `ls`, `readdir` | directory listings via `/v1/fs/projects/…` (cached ~5s) |
+| `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 |
+| `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 |
+
+Reads outside `projects/<slug>/(posts|drafts)`, `inbox/mentions.md`, and
+`me/api-key` return `ENOENT`; writes outside the post/draft dirs return `EACCES`.
+```

package/dist/SforaFs.d.ts

@@ -0,0 +1,59 @@
+/**
+ * A {@link IFileSystem} backed by sfora's `/v1/fs` HTTP API. Posts appear as a
+ * Unix tree:
+ *
+ *   /
+ *   ├── projects/<slug>/posts/<YYYY-MM-DD-title>.md   (lazy → GET …/posts/…)
+ *   │                  /drafts/<…>.md                 (lazy → GET …/drafts/…)
+ *   ├── inbox/mentions.md                             (lazy → GET …/inbox)
+ *   └── me/api-key                                    (lazy → GET …/me/api-key)
+ *
+ * Reads are lazy: directory listings hit the API (cached ~5s so back-to-back
+ * `ls && cat` doesn't double-fetch), and file bodies are only fetched when read.
+ * Writes `PUT` markdown; `rm` of a post file soft-deletes it. Everything else
+ * (symlinks, cross-file cp/mv, mkdir of new projects) is denied to match the
+ * read/append/create surface the backend actually supports.
+ *
+ * Error messages follow the `ERRNO: text, op 'path'` convention just-bash maps
+ * back onto shell-visible errors.
+ */
+import type { BufferEncoding, CpOptions, FileContent, FsStat, IFileSystem, MkdirOptions, RmOptions } from "just-bash";
+import { SforaApiClient } from "./api-client.js";
+interface ReadFileOptions {
+    encoding?: BufferEncoding | null;
+}
+interface WriteFileOptions {
+    encoding?: BufferEncoding;
+}
+interface DirentEntry {
+    name: string;
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+}
+export declare class SforaFs implements IFileSystem {
+    #private;
+    constructor(client: SforaApiClient);
+    readFile(path: string, options?: ReadFileOptions | BufferEncoding): Promise<string>;
+    readFileBuffer(path: string): Promise<Uint8Array>;
+    writeFile(path: string, content: FileContent, _options?: WriteFileOptions | BufferEncoding): Promise<void>;
+    appendFile(path: string, content: FileContent, options?: WriteFileOptions | BufferEncoding): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FsStat>;
+    lstat(path: string): Promise<FsStat>;
+    readdirWithFileTypes(path: string): Promise<DirentEntry[]>;
+    readdir(path: string): Promise<string[]>;
+    mkdir(path: string, _options?: MkdirOptions): Promise<void>;
+    rm(path: string, options?: RmOptions): Promise<void>;
+    cp(src: string, _dest: string, _options?: CpOptions): Promise<void>;
+    mv(src: string, dest: string): Promise<void>;
+    symlink(_target: string, linkPath: string): Promise<void>;
+    link(_existingPath: string, newPath: string): Promise<void>;
+    readlink(path: string): Promise<string>;
+    resolvePath(base: string, path: string): string;
+    realpath(path: string): Promise<string>;
+    getAllPaths(): string[];
+    chmod(_path: string, _mode: number): Promise<void>;
+    utimes(_path: string, _atime: Date, _mtime: Date): Promise<void>;
+}
+export {};