sfora-cli 0.1.0

package/dist/config.d.ts

@@ -0,0 +1,19 @@
+export interface SforaConfig {
+    url?: string;
+    apiKey?: string;
+    org?: string;
+}
+export declare const CONFIG_PATH: string;
+export declare const DEFAULT_URL = "http://localhost:2222";
+export declare function readConfig(): Promise<SforaConfig>;
+export declare function writeConfig(cfg: SforaConfig): Promise<string>;
+export interface ResolvedSettings {
+    url: string;
+    apiKey: string | undefined;
+    org: string | undefined;
+}
+export declare function resolveSettings(flags: {
+    url?: string;
+    apiKey?: string;
+    org?: string;
+}, cfg: SforaConfig): ResolvedSettings;

package/dist/config.js

@@ -0,0 +1,39 @@
+/**
+ * Persisted CLI config at ~/.sfora/config.json so you don't pass
+ * SFORA_API_KEY / SFORA_URL on every invocation. Resolution precedence:
+ * explicit flags > environment > config file > built-in default.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readFile, writeFile, mkdir, chmod } from "node:fs/promises";
+const CONFIG_DIR = join(homedir(), ".sfora");
+export const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+export const DEFAULT_URL = "http://localhost:2222";
+export async function readConfig() {
+    try {
+        const raw = await readFile(CONFIG_PATH, "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export async function writeConfig(cfg) {
+    await mkdir(CONFIG_DIR, { recursive: true });
+    await writeFile(CONFIG_PATH, `${JSON.stringify(cfg, null, 2)}\n`, "utf8");
+    // The file holds an API key — keep it owner-readable only.
+    await chmod(CONFIG_PATH, 0o600).catch(() => { });
+    return CONFIG_PATH;
+}
+// First non-empty value (treats "" / undefined as unset).
+function pick(...vals) {
+    return vals.find((v) => v != null && v !== "");
+}
+export function resolveSettings(flags, cfg) {
+    return {
+        url: pick(flags.url, process.env.SFORA_URL, cfg.url) ?? DEFAULT_URL,
+        apiKey: pick(flags.apiKey, process.env.SFORA_API_KEY, cfg.apiKey),
+        org: pick(flags.org, process.env.SFORA_ORG, cfg.org),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * sfora — a real bash shell mounted on sfora posts.
+ *
+ * `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.
+ */
+import { Bash } from "just-bash";
+import { SforaFs } from "./SforaFs.js";
+export interface CreateSforaShellOptions {
+    /** Base URL of the sfora deployment, e.g. `http://localhost:2222`. */
+    baseUrl: string;
+    /** Agent API key (`sk_…`). The key is org-scoped server-side. */
+    apiKey: string;
+    /**
+     * Workspace/org slug. The API key already determines the org, so this is used
+     * for display (banner/prompt) and to document intent rather than routing.
+     */
+    org: string;
+    /** Initial working directory inside the virtual fs. Defaults to `/`. */
+    cwd?: string;
+}
+export interface SforaShell {
+    bash: Bash;
+    fs: SforaFs;
+}
+export declare function createSforaShell(options: CreateSforaShellOptions): SforaShell;
+export { SforaFs } from "./SforaFs.js";
+export { SforaApiClient, SforaApiError, type SforaApiConfig, type Project, type Entry, type PostKind, type WriteResult, } from "./api-client.js";

package/dist/index.js

@@ -0,0 +1,26 @@
+/**
+ * sfora — a real bash shell mounted on sfora posts.
+ *
+ * `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.
+ */
+import { Bash } from "just-bash";
+import { SforaApiClient } from "./api-client.js";
+import { SforaFs } from "./SforaFs.js";
+export function createSforaShell(options) {
+    const client = new SforaApiClient({
+        baseUrl: options.baseUrl,
+        apiKey: options.apiKey,
+    });
+    const fs = new SforaFs(client);
+    // Disable just-bash's in-process defense-in-depth sandbox. It defaults on and
+    // hardens against *untrusted* scripts by blocking globals like `WeakRef` —
+    // which undici's `fetch` uses internally, so it would break every network-backed
+    // fs call. sfora runs the user's / agent's own commands against their own
+    // workspace over HTTPS, so this hardening is unnecessary here.
+    const bash = new Bash({ fs, cwd: options.cwd ?? "/", defenseInDepth: false });
+    return { bash, fs };
+}
+export { SforaFs } from "./SforaFs.js";
+export { SforaApiClient, SforaApiError, } from "./api-client.js";

package/dist/mcp-server.d.ts

@@ -0,0 +1,14 @@
+/**
+ * MCP stdio server exposing a single `bash` tool. Each tool call runs the
+ * command through one persistent {@link createSforaShell} instance, with cwd/env
+ * carried across calls (just-bash doesn't persist them itself), so an agent's
+ * `cd` and `export` survive between tool invocations.
+ *
+ * stdout is the JSON-RPC channel — all human-facing logging goes to stderr.
+ */
+export interface RunMcpServerOptions {
+    baseUrl: string;
+    apiKey: string;
+    org: string;
+}
+export declare function runMcpServer(options: RunMcpServerOptions): Promise<void>;

package/dist/mcp-server.js

@@ -0,0 +1,88 @@
+/**
+ * MCP stdio server exposing a single `bash` tool. Each tool call runs the
+ * command through one persistent {@link createSforaShell} instance, with cwd/env
+ * carried across calls (just-bash doesn't persist them itself), so an agent's
+ * `cd` and `export` survive between tool invocations.
+ *
+ * stdout is the JSON-RPC channel — all human-facing logging goes to stderr.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { createSforaShell } from "./index.js";
+const TOOL_DESCRIPTION = `Run a bash command against the sfora workspace — a Unix-style view where every post, task, and doc is a markdown file:
+  - /projects/<slug>/posts/<file>.md            published posts
+  - /projects/<slug>/drafts/<file>.md           your drafts
+  - /projects/<slug>/board/<NN-col>/<NNNN>.md   tasks (kanban cards), by column
+  - /projects/<slug>/docs/<file>.md             docs / notes
+  - /inbox/mentions.md                          unread mentions
+  - /me/api-key                                 your identity
+Examples: 'ls /projects', 'cat /projects/web/board/01-todo/*.md', 'grep -ri TODO /projects', 'echo "# Fix login\\nstatus: active" > /projects/web/board/01-todo/fix.md'.
+Write a file to create or update the entity (frontmatter sets fields like status/priority/assignees/due). cwd and environment persist across calls.`;
+export async function runMcpServer(options) {
+    const { bash } = createSforaShell({
+        baseUrl: options.baseUrl,
+        apiKey: options.apiKey,
+        org: options.org,
+    });
+    // Persistent shell state across tool calls.
+    let cwd = "/";
+    let env;
+    const server = new Server({ name: "sfora", version: "0.1.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: [
+            {
+                name: "bash",
+                description: TOOL_DESCRIPTION,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        command: {
+                            type: "string",
+                            description: "The bash command line to execute.",
+                        },
+                    },
+                    required: ["command"],
+                },
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        if (request.params.name !== "bash") {
+            return {
+                content: [
+                    { type: "text", text: `Unknown tool: ${request.params.name}` },
+                ],
+                isError: true,
+            };
+        }
+        const rawArgs = request.params.arguments;
+        const command = typeof rawArgs?.command === "string" ? rawArgs.command : "";
+        if (!command.trim()) {
+            return {
+                content: [{ type: "text", text: "Missing required 'command' argument." }],
+                isError: true,
+            };
+        }
+        try {
+            const res = await bash.exec(command, { cwd, env });
+            env = res.env;
+            cwd = res.env?.PWD ?? cwd;
+            const text = res.stderr ? `${res.stdout}${res.stderr}` : res.stdout;
+            return {
+                content: [{ type: "text", text: text.length > 0 ? text : "(no output)" }],
+                isError: res.exitCode !== 0,
+            };
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            return {
+                content: [{ type: "text", text: message }],
+                isError: true,
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write(`sfora MCP server ready (org: ${options.org || "—"}, ${options.baseUrl})\n`);
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "sfora-cli",
+  "version": "0.1.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.",
+  "keywords": [
+    "sfora",
+    "mcp",
+    "model-context-protocol",
+    "agents",
+    "ai",
+    "cli",
+    "markdown",
+    "project-management"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/wavyrai/sfora/tree/master/packages/sfora#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wavyrai/sfora.git",
+    "directory": "packages/sfora"
+  },
+  "bugs": {
+    "url": "https://github.com/wavyrai/sfora/issues"
+  },
+  "bin": {
+    "sfora": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "just-bash": "^3.0.1",
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.20.3",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}