sfora-cli 0.1.0

package/dist/api-client.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Tiny fetch wrapper around sfora's `/v1/fs/*` agent-filesystem endpoints
+ * (Unix Phase A — see docs/agent-fs.md). Every request authenticates with the
+ * agent API key as a Bearer token; the key is org-scoped server-side, so no org
+ * id travels in the path.
+ *
+ * This module is deliberately transport-only: it knows the routes and their
+ * JSON/markdown shapes, and it surfaces non-2xx responses as {@link SforaApiError}.
+ * Path/virtual-filesystem semantics live in SforaFs.
+ */
+/** Which post collection a route addresses. `scheduled` is `drafts` filtered to rows with a future `scheduledFor`. */
+export type PostKind = "posts" | "drafts" | "scheduled";
+/** A project the caller belongs to. Mirrors `GET /v1/fs/projects`. */
+export interface Project {
+    slug: string;
+    name: string;
+    postCount: number;
+}
+/** A post/draft file entry. Mirrors a row of `GET …/posts` or `…/drafts`. */
+export interface Entry {
+    filename: string;
+    title: string;
+    publishedAt: number;
+    scheduledFor?: number;
+    isDraft: boolean;
+}
+/** Result of a successful `PUT` (create/update). */
+export interface WriteResult {
+    filename: string;
+    id: string;
+}
+/** A column directory under `/projects/<slug>/board/`. `dirname` is `NN-<slug>`. */
+export interface BoardColumn {
+    dirname: string;
+    name: string;
+    color: string;
+    position: number;
+    cardCount: number;
+}
+/** A card file under `/projects/<slug>/board/<col>/`. `filename` is `NNNN-<slug>.md`. */
+export interface BoardCardEntry {
+    filename: string;
+    number: number;
+    title: string;
+    status: "drafted" | "active" | "closed";
+    lastActivityAt: number;
+}
+/** Result of `PUT …/board/<col>/<filename>.md`. */
+export interface CardWriteResult {
+    filename: string;
+    id: string;
+    number: number;
+    /** New column dirname — set when frontmatter `column:` or `status:` moved the card. */
+    movedTo?: string;
+}
+export interface SforaApiConfig {
+    /** e.g. `https://your-sfora.com` or `http://localhost:2222`. Trailing slashes are trimmed. */
+    baseUrl: string;
+    /** Agent API key (`sk_…`). Sent as `Authorization: Bearer <apiKey>`. */
+    apiKey: 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 {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export declare class SforaApiClient {
+    #private;
+    constructor(config: SforaApiConfig);
+    /** `GET /v1/fs/projects` */
+    listProjects(): Promise<Project[]>;
+    /**
+     * `GET …/posts` or `…/drafts`. `scheduled` lists drafts that have a
+     * (future) `scheduledFor` set.
+     */
+    listPosts(projectSlug: string, kind?: PostKind): Promise<Entry[]>;
+    /** `GET …/posts/:filename.md` (or `…/drafts/…`). Returns the raw markdown body. */
+    readPost(projectSlug: string, filename: string, kind?: PostKind): Promise<string>;
+    /** `PUT …/(posts|drafts)/:filename.md` — create or update from a markdown file. */
+    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 …/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. */
+    listCards(projectSlug: string, columnDir: string): Promise<BoardCardEntry[]>;
+    /** `GET …/board/:column/:filename.md`. Returns the raw markdown body. */
+    readCard(projectSlug: string, columnDir: string, filename: string): Promise<string>;
+    /**
+     * `PUT …/board/:column/:filename.md` — create or update a card.
+     *
+     * If the file already exists in a different column (matched by frontmatter
+     * `id:` or by card number embedded in the filename), the server treats this
+     * as a move and reports the canonical `movedTo` dirname.
+     */
+    writeCard(projectSlug: string, columnDir: string, filename: string, markdown: string): Promise<CardWriteResult>;
+    /** `DELETE …/board/:column/:filename.md` — archives the card. */
+    deleteCard(projectSlug: string, columnDir: string, filename: string): Promise<void>;
+    /** `PUT …/board/:column` with an empty body — create a new column at the end. */
+    createColumn(projectSlug: string, name: string): Promise<BoardColumn>;
+    /**
+     * `POST …/board/:column/_rename` with `{ name }` — renames the column,
+     * preserving its cards. The new dirname is in the response.
+     */
+    renameColumn(projectSlug: string, columnDir: string, newName: string): Promise<BoardColumn>;
+    /** `DELETE …/board/:column` — column must be empty. */
+    deleteColumn(projectSlug: string, columnDir: string): Promise<void>;
+    /**
+     * `POST …/board/:fromCol/:filename.md/_move` with `{ toColumn }` — moves a
+     * card across columns without changing its body. Used by `mv` in the shell.
+     */
+    moveCard(projectSlug: string, fromCol: string, filename: string, toCol: string): Promise<CardWriteResult>;
+    /** `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). */
+    readMe(): Promise<string>;
+}

package/dist/api-client.js

@@ -0,0 +1,237 @@
+/**
+ * Tiny fetch wrapper around sfora's `/v1/fs/*` agent-filesystem endpoints
+ * (Unix Phase A — see docs/agent-fs.md). Every request authenticates with the
+ * agent API key as a Bearer token; the key is org-scoped server-side, so no org
+ * id travels in the path.
+ *
+ * This module is deliberately transport-only: it knows the routes and their
+ * JSON/markdown shapes, and it surfaces non-2xx responses as {@link SforaApiError}.
+ * Path/virtual-filesystem semantics live in SforaFs.
+ */
+/** Non-2xx response from the fs API. Carries the HTTP status + machine code so SforaFs can map it to an errno. */
+export class SforaApiError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.name = "SforaApiError";
+        this.status = status;
+        this.code = code;
+    }
+}
+/** The route segment a `PostKind` maps to. `scheduled` reads/writes through the drafts route. */
+function routeBase(kind) {
+    return kind === "posts" ? "posts" : "drafts";
+}
+export class SforaApiClient {
+    #baseUrl;
+    #apiKey;
+    constructor(config) {
+        this.#baseUrl = config.baseUrl.replace(/\/+$/, "");
+        this.#apiKey = config.apiKey;
+    }
+    // ─── HTTP plumbing ──────────────────────────────────────────────
+    async #request(method, path, body) {
+        const headers = Object.create(null);
+        headers.Authorization = `Bearer ${this.#apiKey}`;
+        if (body !== undefined)
+            headers["Content-Type"] = "text/markdown";
+        let res;
+        try {
+            res = await fetch(`${this.#baseUrl}${path}`, { method, headers, body });
+        }
+        catch (e) {
+            // Network/DNS/connection failures — surface as a 0-status error so the
+            // fs layer can translate it (and the CLI can show a connect hint).
+            const message = e instanceof Error ? e.message : String(e);
+            throw new SforaApiError(0, "network_error", message);
+        }
+        if (!res.ok)
+            throw await this.#toError(res);
+        return res;
+    }
+    async #toError(res) {
+        const text = await res.text().catch(() => "");
+        let code = "bad_request";
+        let message = text || res.statusText;
+        if (text) {
+            try {
+                const parsed = JSON.parse(text);
+                if (parsed && typeof parsed === "object") {
+                    const obj = parsed;
+                    if (typeof obj.error === "string")
+                        code = obj.error;
+                    if (typeof obj.message === "string")
+                        message = obj.message;
+                }
+            }
+            catch {
+                // Non-JSON error body — keep the raw text as the message.
+            }
+        }
+        return new SforaApiError(res.status, code, message);
+    }
+    async #json(path) {
+        const res = await this.#request("GET", path);
+        return (await res.json());
+    }
+    async #text(path) {
+        const res = await this.#request("GET", path);
+        return res.text();
+    }
+    // ─── Endpoints ──────────────────────────────────────────────────
+    /** `GET /v1/fs/projects` */
+    async listProjects() {
+        const data = await this.#json("/v1/fs/projects");
+        return data.projects;
+    }
+    /**
+     * `GET …/posts` or `…/drafts`. `scheduled` lists drafts that have a
+     * (future) `scheduledFor` set.
+     */
+    async listPosts(projectSlug, kind = "posts") {
+        const base = routeBase(kind);
+        const slug = encodeURIComponent(projectSlug);
+        const data = await this.#json(`/v1/fs/projects/${slug}/${base}`);
+        const entries = (base === "posts" ? data.posts : data.drafts) ?? [];
+        if (kind === "scheduled") {
+            return entries.filter((e) => typeof e.scheduledFor === "number");
+        }
+        return entries;
+    }
+    /** `GET …/posts/:filename.md` (or `…/drafts/…`). Returns the raw markdown body. */
+    async readPost(projectSlug, filename, kind = "posts") {
+        const base = routeBase(kind);
+        const slug = encodeURIComponent(projectSlug);
+        const file = encodeURIComponent(filename);
+        return this.#text(`/v1/fs/projects/${slug}/${base}/${file}`);
+    }
+    /** `PUT …/(posts|drafts)/:filename.md` — create or update from a markdown file. */
+    async writePost(projectSlug, kind, filename, markdown) {
+        const base = routeBase(kind);
+        const slug = encodeURIComponent(projectSlug);
+        const file = encodeURIComponent(filename);
+        const res = await this.#request("PUT", `/v1/fs/projects/${slug}/${base}/${file}`, markdown);
+        const data = (await res.json());
+        return { filename: data.filename, id: data.id };
+    }
+    /** `DELETE …/(posts|drafts)/:filename.md` — soft-deletes the matched post. */
+    async deletePost(projectSlug, kind, filename) {
+        const base = routeBase(kind);
+        const slug = encodeURIComponent(projectSlug);
+        const file = encodeURIComponent(filename);
+        await this.#request("DELETE", `/v1/fs/projects/${slug}/${base}/${file}`);
+    }
+    // ─── Kanban board ────────────────────────────────────────────────
+    /** `GET …/board` — list the project's columns (auto-creates the board on first call). */
+    async listColumns(projectSlug) {
+        const slug = encodeURIComponent(projectSlug);
+        const data = await this.#json(`/v1/fs/projects/${slug}/board`);
+        return data.columns;
+    }
+    /** `GET …/board/:column` — list cards in a column. `column` is the `NN-slug` dirname. */
+    async listCards(projectSlug, columnDir) {
+        const slug = encodeURIComponent(projectSlug);
+        const col = encodeURIComponent(columnDir);
+        const data = await this.#json(`/v1/fs/projects/${slug}/board/${col}`);
+        return data.cards;
+    }
+    /** `GET …/board/:column/:filename.md`. Returns the raw markdown body. */
+    async readCard(projectSlug, columnDir, filename) {
+        const slug = encodeURIComponent(projectSlug);
+        const col = encodeURIComponent(columnDir);
+        const file = encodeURIComponent(filename);
+        return this.#text(`/v1/fs/projects/${slug}/board/${col}/${file}`);
+    }
+    /**
+     * `PUT …/board/:column/:filename.md` — create or update a card.
+     *
+     * If the file already exists in a different column (matched by frontmatter
+     * `id:` or by card number embedded in the filename), the server treats this
+     * as a move and reports the canonical `movedTo` dirname.
+     */
+    async writeCard(projectSlug, columnDir, filename, markdown) {
+        const slug = encodeURIComponent(projectSlug);
+        const col = encodeURIComponent(columnDir);
+        const file = encodeURIComponent(filename);
+        const res = await this.#request("PUT", `/v1/fs/projects/${slug}/board/${col}/${file}`, markdown);
+        return (await res.json());
+    }
+    /** `DELETE …/board/:column/:filename.md` — archives the card. */
+    async deleteCard(projectSlug, columnDir, filename) {
+        const slug = encodeURIComponent(projectSlug);
+        const col = encodeURIComponent(columnDir);
+        const file = encodeURIComponent(filename);
+        await this.#request("DELETE", `/v1/fs/projects/${slug}/board/${col}/${file}`);
+    }
+    /** `PUT …/board/:column` with an empty body — create a new column at the end. */
+    async createColumn(projectSlug, name) {
+        const slug = encodeURIComponent(projectSlug);
+        // The server slugifies `name` to derive the directory; we send it as a
+        // single-field JSON body to keep the spec consistent with future fields.
+        const res = await fetch(`${this.#baseUrl}/v1/fs/projects/${slug}/board`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.#apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ name }),
+        });
+        if (!res.ok)
+            throw await this.#toError(res);
+        return (await res.json());
+    }
+    /**
+     * `POST …/board/:column/_rename` with `{ name }` — renames the column,
+     * preserving its cards. The new dirname is in the response.
+     */
+    async renameColumn(projectSlug, columnDir, newName) {
+        const slug = encodeURIComponent(projectSlug);
+        const col = encodeURIComponent(columnDir);
+        const res = await fetch(`${this.#baseUrl}/v1/fs/projects/${slug}/board/${col}/_rename`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.#apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ name: newName }),
+        });
+        if (!res.ok)
+            throw await this.#toError(res);
+        return (await res.json());
+    }
+    /** `DELETE …/board/:column` — column must be empty. */
+    async deleteColumn(projectSlug, columnDir) {
+        const slug = encodeURIComponent(projectSlug);
+        const col = encodeURIComponent(columnDir);
+        await this.#request("DELETE", `/v1/fs/projects/${slug}/board/${col}`);
+    }
+    /**
+     * `POST …/board/:fromCol/:filename.md/_move` with `{ toColumn }` — moves a
+     * card across columns without changing its body. Used by `mv` in the shell.
+     */
+    async moveCard(projectSlug, fromCol, filename, toCol) {
+        const slug = encodeURIComponent(projectSlug);
+        const from = encodeURIComponent(fromCol);
+        const file = encodeURIComponent(filename);
+        const res = await fetch(`${this.#baseUrl}/v1/fs/projects/${slug}/board/${from}/${file}/_move`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.#apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ toColumn: toCol }),
+        });
+        if (!res.ok)
+            throw await this.#toError(res);
+        return (await res.json());
+    }
+    /** `GET /v1/fs/inbox/mentions.md` — markdown summary of unread mentions. */
+    async readInbox() {
+        return this.#text("/v1/fs/inbox/mentions.md");
+    }
+    /** `GET /v1/fs/me/api-key` — text identity (no key material). */
+    async readMe() {
+        return this.#text("/v1/fs/me/api-key");
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * sfora — interactive REPL (and `--mcp` launcher) for a bash shell
+ * mounted on your sfora posts.
+ *
+ *   SFORA_API_KEY=sk_… SFORA_URL=http://localhost:2222 sfora --org test
+ *   sfora --mcp        # MCP stdio server for Claude/Cursor
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+/**
+ * sfora — interactive REPL (and `--mcp` launcher) for a bash shell
+ * mounted on your sfora posts.
+ *
+ *   SFORA_API_KEY=sk_… SFORA_URL=http://localhost:2222 sfora --org test
+ *   sfora --mcp        # MCP stdio server for Claude/Cursor
+ */
+import * as readline from "node:readline";
+import { spawn } from "node:child_process";
+import { createSforaShell } from "./index.js";
+import { runMcpServer } from "./mcp-server.js";
+import { readConfig, writeConfig, resolveSettings, DEFAULT_URL, } from "./config.js";
+const colors = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    cyan: "\x1b[36m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    blue: "\x1b[34m",
+    red: "\x1b[31m",
+};
+function parseArgs(argv) {
+    const args = { cwd: "/", mcp: false, help: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--mcp")
+            args.mcp = true;
+        else if (a === "--help" || a === "-h")
+            args.help = true;
+        else if (a === "--org")
+            args.org = argv[++i];
+        else if (a.startsWith("--org="))
+            args.org = a.slice("--org=".length);
+        else if (a === "--cwd")
+            args.cwd = argv[++i] ?? "/";
+        else if (a.startsWith("--cwd="))
+            args.cwd = a.slice("--cwd=".length);
+        else if (a === "--url")
+            args.url = argv[++i];
+        else if (a.startsWith("--url="))
+            args.url = a.slice("--url=".length);
+        else if (a === "--key")
+            args.key = argv[++i];
+        else if (a.startsWith("--key="))
+            args.key = a.slice("--key=".length);
+        else if (a === "--agent")
+            args.agent = argv[++i];
+        else if (a.startsWith("--agent="))
+            args.agent = a.slice("--agent=".length);
+        else if (a === "--web")
+            args.web = argv[++i];
+        else if (a.startsWith("--web="))
+            args.web = a.slice("--web=".length);
+        else if (!a.startsWith("-") && !args.command)
+            args.command = a;
+    }
+    return args;
+}
+const HELP = `sfora — a bash shell over your sfora workspace (and an MCP server)
+
+Usage:
+  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
+
+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
+`;
+// `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) {
+    const cfg = await readConfig();
+    let url = args.url ?? process.env.SFORA_URL;
+    let key = args.key ?? process.env.SFORA_API_KEY;
+    let org = args.org ?? process.env.SFORA_ORG;
+    const isTty = Boolean(process.stdin.isTTY);
+    if (isTty && (!url || !key || !org)) {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        const ask = (q, def) => new Promise((res) => rl.question(def ? `${q} [${def}]: ` : `${q}: `, (a) => res(a.trim() || def || "")));
+        url = url ?? (await ask("Deployment URL", cfg.url ?? DEFAULT_URL));
+        key = key ?? (await ask("Agent API key (sfora_ak_…)", cfg.apiKey));
+        org = org ?? (await ask("Default org slug", cfg.org));
+        rl.close();
+    }
+    url = url || cfg.url || DEFAULT_URL;
+    if (!key) {
+        process.stderr.write(`${colors.red}error:${colors.reset} an API key is required.\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const path = await writeConfig({ url, apiKey: key, org: org || cfg.org });
+    console.log(`${colors.green}✓${colors.reset} Saved ${path}`);
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+function openBrowser(url) {
+    const cmd = process.platform === "darwin"
+        ? "open"
+        : process.platform === "win32"
+            ? "start"
+            : "xdg-open";
+    try {
+        spawn(cmd, [url], { stdio: "ignore", detached: true }).unref();
+    }
+    catch {
+        /* best effort — the URL is printed for manual opening */
+    }
+}
+// `sfora login` — browser device flow. Starts a request, opens the approval
+// page, polls until the human approves, then saves the minted key.
+async function runLogin(args, baseUrl) {
+    const base = baseUrl.replace(/\/+$/, "");
+    let start;
+    try {
+        const res = await fetch(`${base}/v1/cli/start`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ agent: args.agent }),
+        });
+        if (!res.ok)
+            throw new Error(`start failed (${res.status})`);
+        start = (await res.json());
+    }
+    catch (e) {
+        process.stderr.write(`${colors.red}error:${colors.reset} could not reach ${base} — ${e instanceof Error ? e.message : String(e)}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const webOverride = args.web ?? process.env.SFORA_WEB_URL;
+    const verifyUrl = webOverride
+        ? `${webOverride.replace(/\/+$/, "")}/cli?code=${encodeURIComponent(start.userCode)}`
+        : start.verifyUrl;
+    console.log(`\n${colors.bold}Authorize the sfora CLI${colors.reset}` +
+        (args.agent ? ` ${colors.dim}(agent: ${args.agent})${colors.reset}` : "") +
+        `\n  ${colors.cyan}${verifyUrl}${colors.reset}\n  ${colors.dim}code: ${start.userCode}${colors.reset}\n`);
+    openBrowser(verifyUrl);
+    process.stdout.write(`${colors.dim}Waiting for approval…${colors.reset}`);
+    const deadline = Date.now() + 10 * 60 * 1000;
+    while (Date.now() < deadline) {
+        await sleep(2000);
+        let data;
+        try {
+            const res = await fetch(`${base}/v1/cli/poll`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ deviceCode: start.deviceCode }),
+            });
+            data = (await res.json());
+        }
+        catch {
+            process.stdout.write(".");
+            continue;
+        }
+        if (data.status === "approved" && data.apiKey) {
+            const path = await writeConfig({
+                url: base,
+                apiKey: data.apiKey,
+                org: data.orgSlug ?? undefined,
+            });
+            console.log(`\n${colors.green}✓${colors.reset} Logged in as ${data.name ?? "you"}${data.orgSlug ? ` ${colors.dim}(${data.orgSlug})${colors.reset}` : ""} — saved ${path}`);
+            return;
+        }
+        if (data.status === "expired" || data.status === "unknown") {
+            console.log(`\n${colors.red}Login ${data.status}.${colors.reset} Run \`sfora login\` again.`);
+            process.exitCode = 1;
+            return;
+        }
+        process.stdout.write(".");
+    }
+    console.log(`\n${colors.red}Timed out waiting for approval.${colors.reset}`);
+    process.exitCode = 1;
+}
+// `sfora mcp-config` — print a ready-to-paste MCP server entry.
+function printMcpConfig(s) {
+    const snippet = {
+        mcpServers: {
+            sfora: {
+                command: "npx",
+                args: ["-y", "sfora-cli", "--mcp", ...(s.org ? ["--org", s.org] : [])],
+                env: {
+                    SFORA_API_KEY: s.apiKey ?? "sfora_ak_…",
+                    SFORA_URL: s.url,
+                },
+            },
+        },
+    };
+    process.stdout.write(`${JSON.stringify(snippet, null, 2)}\n`);
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        process.stdout.write(HELP);
+        return;
+    }
+    if (args.command === "init") {
+        await runInit(args);
+        return;
+    }
+    const cfg = await readConfig();
+    const settings = resolveSettings({ url: args.url, apiKey: args.key, org: args.org }, cfg);
+    const { url: baseUrl, apiKey } = settings;
+    if (args.command === "mcp-config") {
+        printMcpConfig(settings);
+        return;
+    }
+    if (args.command === "login") {
+        await runLogin(args, baseUrl);
+        return;
+    }
+    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`);
+        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 ?? "" });
+        return;
+    }
+    if (!settings.org) {
+        process.stderr.write(`${colors.red}error:${colors.reset} no org — pass --org <slug>, set SFORA_ORG, or run \`sfora init\`.\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const org = settings.org;
+    const { bash } = 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;
+    let env;
+    // Pre-flight: confirm auth + connectivity and greet with the resolved identity.
+    let identity = "";
+    try {
+        identity = (await bash.exec("cat /me/api-key", { cwd, env })).stdout.trim();
+    }
+    catch {
+        identity = "";
+    }
+    console.log(`${colors.cyan}${colors.bold}sfora${colors.reset} ${colors.dim}— bash over ${baseUrl} (org: ${org})${colors.reset}`);
+    if (identity) {
+        const who = identity
+            .split("\n")
+            .find((l) => l.startsWith("name:"));
+        if (who)
+            console.log(`${colors.dim}${who.trim()}${colors.reset}`);
+    }
+    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`);
+    // 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
+    // AFTER any in-flight bash.exec / HTTP write resolves. The earlier
+    // `rl.question` + `void handleLine()` shape lost piped writes because
+    // readline fired 'close' (→ process.exit(0)) while the first exec's PUT was
+    // still in flight.
+    const isTty = Boolean(process.stdin.isTTY);
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: isTty,
+    });
+    const promptText = () => `${colors.cyan}sfora${colors.reset}:${colors.blue}${cwd}${colors.reset}$ `;
+    // Print the first prompt; subsequent ones are printed after each handled line.
+    if (isTty)
+        process.stdout.write(promptText());
+    for await (const input of rl) {
+        const line = input.trim();
+        if (!line) {
+            if (isTty)
+                process.stdout.write(promptText());
+            continue;
+        }
+        if (line === "exit" || line === "quit")
+            break;
+        try {
+            const res = await bash.exec(line, { cwd, env });
+            if (res.stdout)
+                process.stdout.write(res.stdout);
+            if (res.stderr)
+                process.stderr.write(res.stderr);
+            env = res.env;
+            cwd = res.env?.PWD ?? cwd;
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            process.stderr.write(`${colors.red}${message}${colors.reset}\n`);
+        }
+        if (isTty)
+            process.stdout.write(promptText());
+    }
+    rl.close();
+    if (isTty)
+        console.log("");
+}
+main().catch((e) => {
+    const message = e instanceof Error ? e.message : String(e);
+    process.stderr.write(`${colors.red}fatal:${colors.reset} ${message}\n`);
+    process.exit(1);
+});