sfora-cli 0.10.0 → 0.12.0

package/dist/chat.d.ts

@@ -0,0 +1,89 @@
+/**
+ * `sfora rooms` / `sfora join` / `sfora chat` — the room in the terminal.
+ *
+ * Humans and agents are the same member model in the same rooms, and this is
+ * how either sits in the conversation from a terminal. Everything
+ * decision-shaped lives here as pure functions (name resolution, message
+ * formatting, the tail loop) so it can be tested with canned data; `cli.ts`
+ * owns the process — readline, signals, the real streams.
+ *
+ * The live tail rides `/v1/events`, the same long-poll `sfora watch` uses: the
+ * feed carries a `message` event for every room the caller is in (never their
+ * own posts), so a new message is a wake, not a poll schedule. The event's
+ * preview is clipped server-side at 280 chars, so the loop treats it as a
+ * DOORBELL only — on any message event for this room it refetches the recent
+ * page and prints what it has not printed yet, deduped by message id. That is
+ * also what makes the caller's own sends (echoed by the send itself) never
+ * print twice.
+ */
+import type { AgentEventsPage, ChatMessage, Room } from "./api-client.js";
+/** How `sfora rooms` and `sfora join` spell a room name as an argument. */
+export declare function roomSlug(name: string): string;
+export type RoomMatch = {
+    kind: "match";
+    room: Room;
+} | {
+    kind: "ambiguous";
+    candidates: Room[];
+} | {
+    kind: "none";
+};
+/**
+ * The room a reference names: exact name or slug first (case-insensitive),
+ * then an unambiguous prefix of either. Ambiguity is reported, not guessed —
+ * sending a message into the wrong room is the failure this exists to prevent.
+ * A joined room beats an unjoined one on an otherwise-tied exact match.
+ */
+export declare function resolveRoomRef(rooms: Room[], ref: string): RoomMatch;
+/** House rule: a displayed name leads with a capital, wherever it renders. */
+export declare function capitalizeName(name: string): string;
+/**
+ * A chat timestamp, relative — a room is read as a conversation, and "3m ago"
+ * is how a conversation tells time. Beyond a week the date says it better.
+ */
+export declare function relativeTime(ts: number, now: number): string;
+/**
+ * A message body for a terminal: markdown, lightly dressed. Headings read
+ * bold, fence delimiters and blockquote markers go dim; everything else is
+ * printed as the author wrote it — the CLI prints what the server sends, and
+ * markdown is already a terminal-legible format.
+ */
+export declare function renderChatBody(markdown: string): string;
+/**
+ * One message: `Author  3m ago`, then the body indented under it. The author
+ * is bold because it is the line's anchor; the time is dim because it is
+ * context, not content.
+ */
+export declare function renderChatMessage(msg: ChatMessage, now: number): string;
+/** `sfora rooms` — one row per room; unjoined rows carry their join hint. */
+export declare function renderRoomList(rooms: Room[]): string;
+/** Everything the tail loop needs from the outside world. */
+export interface ChatTailDeps {
+    /** One `/v1/events` long-poll. Rejects on a drop — the loop backs off. */
+    poll(since: number): Promise<AgentEventsPage>;
+    /** The room's recent page, any order — refetched when the doorbell rings. */
+    fetchRecent(): Promise<ChatMessage[]>;
+    /** Print one message the reader has not seen. */
+    print(message: ChatMessage): void;
+    /** A warning, never mixed into the transcript. */
+    warn(text: string): void;
+    sleep(ms: number): Promise<void>;
+}
+export interface ChatTailOptions {
+    roomId: string;
+    /** Message ids already on screen — history, and the caller's own sends. */
+    seen: Set<string>;
+    /** Events cursor to start from (the CLI starts at "now"). */
+    since: number;
+    stopped?: () => boolean;
+    backoffMs?: number;
+}
+/**
+ * Poll until stopped, printing new messages in this room as they arrive.
+ *
+ * The same three rules `watchLoop` holds, held here for the same reasons: the
+ * cursor survives reconnects and only moves forward, drops back off (doubling
+ * to {@link MAX_BACKOFF_MS}) and recover fast, and nothing prints twice — the
+ * `seen` set is the single ledger, shared with the prompt's own sends.
+ */
+export declare function chatTailLoop(deps: ChatTailDeps, options: ChatTailOptions): Promise<number>;

package/dist/chat.js

@@ -0,0 +1,189 @@
+/**
+ * `sfora rooms` / `sfora join` / `sfora chat` — the room in the terminal.
+ *
+ * Humans and agents are the same member model in the same rooms, and this is
+ * how either sits in the conversation from a terminal. Everything
+ * decision-shaped lives here as pure functions (name resolution, message
+ * formatting, the tail loop) so it can be tested with canned data; `cli.ts`
+ * owns the process — readline, signals, the real streams.
+ *
+ * The live tail rides `/v1/events`, the same long-poll `sfora watch` uses: the
+ * feed carries a `message` event for every room the caller is in (never their
+ * own posts), so a new message is a wake, not a poll schedule. The event's
+ * preview is clipped server-side at 280 chars, so the loop treats it as a
+ * DOORBELL only — on any message event for this room it refetches the recent
+ * page and prints what it has not printed yet, deduped by message id. That is
+ * also what makes the caller's own sends (echoed by the send itself) never
+ * print twice.
+ */
+import { colors } from "./render.js";
+import { MAX_BACKOFF_MS } from "./watch.js";
+const dim = (text) => `${colors.dim}${text}${colors.reset}`;
+// ─── Room resolution ─────────────────────────────────────────────────
+/** How `sfora rooms` and `sfora join` spell a room name as an argument. */
+export function roomSlug(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "");
+}
+/**
+ * The room a reference names: exact name or slug first (case-insensitive),
+ * then an unambiguous prefix of either. Ambiguity is reported, not guessed —
+ * sending a message into the wrong room is the failure this exists to prevent.
+ * A joined room beats an unjoined one on an otherwise-tied exact match.
+ */
+export function resolveRoomRef(rooms, ref) {
+    const want = ref.trim().toLowerCase().replace(/^#/, "");
+    if (!want)
+        return { kind: "none" };
+    const bySlug = roomSlug(want);
+    const exact = rooms.filter((r) => r.name.toLowerCase() === want || roomSlug(r.name) === bySlug);
+    if (exact.length === 1)
+        return { kind: "match", room: exact[0] };
+    if (exact.length > 1) {
+        const joined = exact.filter((r) => r.joined);
+        if (joined.length === 1)
+            return { kind: "match", room: joined[0] };
+        return { kind: "ambiguous", candidates: exact };
+    }
+    const prefix = rooms.filter((r) => r.name.toLowerCase().startsWith(want) ||
+        roomSlug(r.name).startsWith(bySlug));
+    if (prefix.length === 1)
+        return { kind: "match", room: prefix[0] };
+    if (prefix.length > 1)
+        return { kind: "ambiguous", candidates: prefix };
+    return { kind: "none" };
+}
+// ─── Message formatting ──────────────────────────────────────────────
+/** House rule: a displayed name leads with a capital, wherever it renders. */
+export function capitalizeName(name) {
+    return name ? name.charAt(0).toUpperCase() + name.slice(1) : name;
+}
+/**
+ * A chat timestamp, relative — a room is read as a conversation, and "3m ago"
+ * is how a conversation tells time. Beyond a week the date says it better.
+ */
+export function relativeTime(ts, now) {
+    const diff = Math.max(0, now - ts);
+    const minutes = Math.floor(diff / 60_000);
+    if (minutes < 1)
+        return "just now";
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    if (days < 7)
+        return `${days}d ago`;
+    // The reader's LOCAL date — toISOString would name yesterday for an
+    // evening timestamp anywhere east of UTC.
+    const d = new Date(ts);
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+/**
+ * A message body for a terminal: markdown, lightly dressed. Headings read
+ * bold, fence delimiters and blockquote markers go dim; everything else is
+ * printed as the author wrote it — the CLI prints what the server sends, and
+ * markdown is already a terminal-legible format.
+ */
+export function renderChatBody(markdown) {
+    let inFence = false;
+    return markdown
+        .replace(/\s+$/, "")
+        .split("\n")
+        .map((line) => {
+        if (/^\s*(```|~~~)/.test(line)) {
+            inFence = !inFence;
+            return `  ${dim(line)}`;
+        }
+        if (inFence)
+            return `  ${line}`;
+        if (/^#{1,6}\s/.test(line)) {
+            return `  ${colors.bold}${line}${colors.reset}`;
+        }
+        if (/^\s*>/.test(line))
+            return `  ${dim(line)}`;
+        return `  ${line}`;
+    })
+        .join("\n");
+}
+/**
+ * One message: `Author  3m ago`, then the body indented under it. The author
+ * is bold because it is the line's anchor; the time is dim because it is
+ * context, not content.
+ */
+export function renderChatMessage(msg, now) {
+    const author = capitalizeName(msg.author?.name ?? "Unknown");
+    const header = `${colors.bold}${author}${colors.reset}  ${dim(relativeTime(msg._creationTime, now))}`;
+    return `${header}\n${renderChatBody(msg.body)}`;
+}
+/** `sfora rooms` — one row per room; unjoined rows carry their join hint. */
+export function renderRoomList(rooms) {
+    if (rooms.length === 0)
+        return dim("(no rooms)");
+    const width = Math.max(...rooms.map((r) => r.name.length));
+    return rooms
+        .map((room) => {
+        const marker = room.joined
+            ? `${colors.green}●${colors.reset}`
+            : dim("○");
+        const meta = room.joined
+            ? dim(room.type)
+            : dim(`${room.type} · not joined — sfora join ${roomSlug(room.name)}`);
+        return `  ${marker} ${room.name.padEnd(width)}  ${meta}`;
+    })
+        .join("\n");
+}
+/**
+ * Poll until stopped, printing new messages in this room as they arrive.
+ *
+ * The same three rules `watchLoop` holds, held here for the same reasons: the
+ * cursor survives reconnects and only moves forward, drops back off (doubling
+ * to {@link MAX_BACKOFF_MS}) and recover fast, and nothing prints twice — the
+ * `seen` set is the single ledger, shared with the prompt's own sends.
+ */
+export async function chatTailLoop(deps, options) {
+    const stopped = options.stopped ?? (() => false);
+    const firstBackoff = options.backoffMs ?? 1_000;
+    let cursor = options.since;
+    let backoff = firstBackoff;
+    while (!stopped()) {
+        let page;
+        try {
+            page = await deps.poll(cursor);
+        }
+        catch (error) {
+            if (stopped())
+                break;
+            const message = error instanceof Error ? error.message : String(error);
+            deps.warn(`reconnecting in ${Math.round(backoff / 1000)}s — ${message}`);
+            await deps.sleep(backoff);
+            backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+            continue;
+        }
+        backoff = firstBackoff;
+        const rang = page.events.some((e) => e.type === "message" && e.roomId === options.roomId);
+        if (rang) {
+            try {
+                const recent = await deps.fetchRecent();
+                const fresh = recent
+                    .filter((m) => !options.seen.has(m._id))
+                    .sort((a, b) => a._creationTime - b._creationTime);
+                for (const msg of fresh) {
+                    options.seen.add(msg._id);
+                    deps.print(msg);
+                }
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                deps.warn(`could not fetch new messages — ${message}`);
+            }
+        }
+        // Never backwards: an empty page holds the cursor where it was.
+        cursor = Math.max(cursor, page.cursor);
+    }
+    return cursor;
+}

package/dist/cli-args.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The CLI's argument grammar, as a pure function.
+ *
+ * Lifted out of `cli.ts` so it can be tested: importing `cli.ts` runs
+ * `main()`, which is exactly what a test must not do. Nothing here reads the
+ * process — argv in, a parsed shape out.
+ */
+export interface CliArgs {
+    command?: string;
+    rest: string[];
+    org?: string;
+    cwd: string;
+    mcp: boolean;
+    help: boolean;
+    url?: string;
+    key?: string;
+    bot?: string;
+    as?: string;
+    web?: string;
+    project?: string;
+    column?: string;
+    draft: boolean;
+    json: boolean;
+    local: boolean;
+    cloud: boolean;
+    block?: string;
+    self: boolean;
+    wait?: number;
+    message?: string;
+    limit?: number;
+}
+export declare function parseArgs(argv: string[]): CliArgs;

package/dist/cli-args.js

@@ -0,0 +1,88 @@
+/**
+ * The CLI's argument grammar, as a pure function.
+ *
+ * Lifted out of `cli.ts` so it can be tested: importing `cli.ts` runs
+ * `main()`, which is exactly what a test must not do. Nothing here reads the
+ * process — argv in, a parsed shape out.
+ */
+export function parseArgs(argv) {
+    const args = { rest: [], cwd: "/", mcp: false, help: false, draft: false, json: false, local: false, cloud: false, self: 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 === "--bot" || a === "--agent")
+            args.bot = argv[++i];
+        else if (a.startsWith("--bot="))
+            args.bot = a.slice("--bot=".length);
+        else if (a.startsWith("--agent="))
+            args.bot = a.slice("--agent=".length);
+        else if (a === "--as")
+            args.as = argv[++i];
+        else if (a.startsWith("--as="))
+            args.as = a.slice("--as=".length);
+        else if (a === "--web")
+            args.web = argv[++i];
+        else if (a.startsWith("--web="))
+            args.web = a.slice("--web=".length);
+        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 === "--json")
+            args.json = true;
+        else if (a === "--local")
+            args.local = true;
+        else if (a === "--cloud")
+            args.cloud = true;
+        else if (a === "--block")
+            args.block = argv[++i];
+        else if (a.startsWith("--block="))
+            args.block = a.slice("--block=".length);
+        else if (a === "--self")
+            args.self = true;
+        else if (a === "--wait")
+            args.wait = Number.parseInt(argv[++i] ?? "", 10);
+        else if (a.startsWith("--wait="))
+            args.wait = Number.parseInt(a.slice("--wait=".length), 10);
+        else if (a === "-m" || a === "--message")
+            args.message = argv[++i];
+        else if (a.startsWith("--message="))
+            args.message = a.slice("--message=".length);
+        else if (a === "-n" || a === "--limit")
+            args.limit = Number.parseInt(argv[++i] ?? "", 10);
+        else if (a.startsWith("--limit="))
+            args.limit = Number.parseInt(a.slice("--limit=".length), 10);
+        else if (!a.startsWith("-")) {
+            if (!args.command)
+                args.command = a;
+            else
+                args.rest.push(a);
+        }
+    }
+    return args;
+}