@1a35e1/sonar-cli 0.1.3 → 0.2.1

package/README.md

@@ -46,8 +46,8 @@ Ingest your first `tweets` and check to `monitor` progress.
 ```sh
 sonar ingest tweets
 
-sonar ingest monitor
-sonar ingest monitor --watch
+sonar monitor
+sonar monitor --watch
 ```
 
 ---

package/dist/commands/config/data/backup.js

@@ -0,0 +1,74 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import zod from 'zod';
+import { Text } from 'ink';
+import { existsSync, mkdirSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import Database from 'better-sqlite3';
+import { DB_PATH } from '../../../lib/db.js';
+import { integrityCheck } from './utils.js';
+export const options = zod.object({
+    out: zod.string().optional().describe('Backup output path (default: ~/.sonar/data-backup-<timestamp>.db)'),
+    json: zod.boolean().default(false).describe('Raw JSON output'),
+});
+function ts() {
+    const d = new Date();
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getUTCFullYear()}${p(d.getUTCMonth() + 1)}${p(d.getUTCDate())}${p(d.getUTCHours())}${p(d.getUTCMinutes())}${p(d.getUTCSeconds())}`;
+}
+export default function DataBackup({ options: flags }) {
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        async function run() {
+            try {
+                if (!existsSync(DB_PATH))
+                    throw new Error(`source database not found: ${DB_PATH}`);
+                // Use trimmed value for the actual output path to avoid confusing
+                // filesystem errors from leading/trailing whitespace.
+                const trimmedOut = flags.out?.trim();
+                const out = trimmedOut && trimmedOut.length > 0
+                    ? trimmedOut
+                    : join(dirname(DB_PATH), `${basename(DB_PATH, '.db')}-backup-${ts()}.db`);
+                mkdirSync(dirname(out), { recursive: true });
+                // Use SQLite's online backup API (better-sqlite3 wraps the C-level
+                // sqlite3_backup_* functions) instead of a plain filesystem copy.
+                // This works correctly under concurrent writes: it iterates over DB
+                // pages in a consistent snapshot without requiring an exclusive lock
+                // and without needing a prior WAL checkpoint.
+                const db = new Database(DB_PATH);
+                try {
+                    await db.backup(out);
+                }
+                finally {
+                    db.close();
+                }
+                const check = integrityCheck(out);
+                if (check !== 'ok')
+                    throw new Error(`backup integrity check failed: ${check}`);
+                const result = { ok: true, source: DB_PATH, backup: out };
+                if (flags.json) {
+                    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+                }
+                else {
+                    process.stdout.write(`Backup complete: ${out}\n`);
+                }
+                process.exit(0);
+            }
+            catch (e) {
+                setError(e instanceof Error ? e.message : String(e));
+            }
+        }
+        run();
+    }, []);
+    useEffect(() => {
+        if (!error)
+            return;
+        if (flags.json) {
+            process.stderr.write(`${error}\n`);
+            process.exit(1);
+        }
+    }, [error, flags.json]);
+    if (error)
+        return flags.json ? _jsx(_Fragment, {}) : _jsxs(Text, { color: "red", children: ["Error: ", error] });
+    return flags.json ? _jsx(_Fragment, {}) : _jsx(Text, { dimColor: true, children: "Creating backup..." });
+}

package/dist/commands/config/data/restore.js

@@ -0,0 +1,86 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import zod from 'zod';
+import { Text } from 'ink';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { DB_PATH } from '../../../lib/db.js';
+import { integrityCheck, copyDbWithSidecars } from './utils.js';
+export const options = zod.object({
+    from: zod.string().describe('Backup database path to restore from'),
+    to: zod.string().optional().describe('Target database path (default: local sonar DB path)'),
+    json: zod.boolean().default(false).describe('Raw JSON output'),
+});
+export default function DataRestore({ options: flags }) {
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        try {
+            const src = resolve(flags.from);
+            const dst = resolve(flags.to ?? DB_PATH);
+            // Guard: prevent copying a file onto itself, which would corrupt the DB.
+            if (src === dst) {
+                throw new Error(`Source and destination resolve to the same path: ${src}\n` +
+                    'Specify a different --to path.');
+            }
+            if (!existsSync(src))
+                throw new Error(`backup not found: ${src}`);
+            // Verify the backup is healthy before touching anything.
+            const srcCheck = integrityCheck(src);
+            if (srcCheck !== 'ok')
+                throw new Error(`backup integrity check failed: ${srcCheck}`);
+            mkdirSync(dirname(dst), { recursive: true });
+            // Snapshot the current DB — including WAL/SHM sidecars — so we have
+            // a complete, self-consistent point-in-time snapshot to roll back to if
+            // anything goes wrong during the restore.
+            const preRestore = existsSync(dst) ? `${dst}.pre-restore.${Date.now()}` : null;
+            if (preRestore) {
+                copyDbWithSidecars(dst, preRestore);
+            }
+            // Copy backup → destination (main DB + any sidecars).
+            copyDbWithSidecars(src, dst);
+            // Verify the restored DB before declaring success.
+            const dstCheck = integrityCheck(dst);
+            if (dstCheck !== 'ok') {
+                // The restored file is corrupt. Roll back to the pre-restore snapshot
+                // so we don't leave the user with a broken local database.
+                if (preRestore && existsSync(preRestore)) {
+                    copyDbWithSidecars(preRestore, dst);
+                    for (const ext of ['-wal', '-shm']) {
+                        rmSync(`${preRestore}${ext}`, { force: true });
+                    }
+                    rmSync(preRestore, { force: true });
+                    throw new Error(`Restored database failed integrity check (${dstCheck}). ` +
+                        'Rolled back to the previous database — your data is intact.');
+                }
+                throw new Error(`restored database integrity check failed: ${dstCheck}`);
+            }
+            // Clean up the pre-restore snapshot on success.
+            if (preRestore) {
+                for (const ext of ['-wal', '-shm']) {
+                    rmSync(`${preRestore}${ext}`, { force: true });
+                }
+                rmSync(preRestore, { force: true });
+            }
+            const result = { ok: true, from: src, to: dst };
+            if (flags.json)
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            else
+                process.stdout.write(`Restore complete: ${src} -> ${dst}\n`);
+            process.exit(0);
+        }
+        catch (e) {
+            setError(e instanceof Error ? e.message : String(e));
+        }
+    }, []);
+    useEffect(() => {
+        if (!error)
+            return;
+        if (flags.json) {
+            process.stderr.write(`${error}\n`);
+            process.exit(1);
+        }
+    }, [error, flags.json]);
+    if (error)
+        return flags.json ? _jsx(_Fragment, {}) : _jsxs(Text, { color: "red", children: ["Error: ", error] });
+    return flags.json ? _jsx(_Fragment, {}) : _jsx(Text, { dimColor: true, children: "Restoring database..." });
+}

package/dist/commands/config/data/utils.js

@@ -0,0 +1,39 @@
+/**
+ * Shared utilities for the data backup/restore/verify commands.
+ */
+import { copyFileSync, existsSync, rmSync } from 'node:fs';
+import Database from 'better-sqlite3';
+/**
+ * Run SQLite's built-in integrity_check pragma on the given database file.
+ * Returns `'ok'` when the database is healthy.
+ *
+ * The DB handle is always closed — even when the pragma throws — so callers
+ * never have to worry about leaked file descriptors.
+ */
+export function integrityCheck(path) {
+    const db = new Database(path, { readonly: true });
+    try {
+        const rows = db.pragma('integrity_check');
+        const first = Object.values(rows[0] ?? {})[0];
+        return String(first ?? 'unknown');
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Copy a SQLite DB file together with any WAL / SHM sidecars that exist.
+ * If a sidecar does not exist at the source it is removed from the destination
+ * (so that the destination remains self-consistent).
+ */
+export function copyDbWithSidecars(src, dst) {
+    copyFileSync(src, dst);
+    for (const ext of ['-wal', '-shm']) {
+        if (existsSync(`${src}${ext}`)) {
+            copyFileSync(`${src}${ext}`, `${dst}${ext}`);
+        }
+        else {
+            rmSync(`${dst}${ext}`, { force: true });
+        }
+    }
+}

package/dist/commands/config/data/verify.js

@@ -0,0 +1,44 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import zod from 'zod';
+import { Text } from 'ink';
+import { existsSync } from 'node:fs';
+import { DB_PATH } from '../../../lib/db.js';
+import { integrityCheck } from './utils.js';
+export const options = zod.object({
+    path: zod.string().optional().describe('Database path (default: local sonar DB path)'),
+    json: zod.boolean().default(false).describe('Raw JSON output'),
+});
+export default function DataVerify({ options: flags }) {
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        try {
+            const path = flags.path ?? DB_PATH;
+            if (!existsSync(path))
+                throw new Error(`database not found: ${path}`);
+            const result = integrityCheck(path);
+            const ok = result === 'ok';
+            if (flags.json) {
+                process.stdout.write(`${JSON.stringify({ ok, path, integrity: result }, null, 2)}\n`);
+            }
+            else {
+                process.stdout.write(ok ? `Integrity check passed: ${path}\n` : `Integrity check failed: ${path} (${result})\n`);
+            }
+            process.exit(ok ? 0 : 1);
+        }
+        catch (e) {
+            setError(e instanceof Error ? e.message : String(e));
+        }
+    }, []);
+    useEffect(() => {
+        if (!error)
+            return;
+        if (flags.json) {
+            process.stderr.write(`${error}\n`);
+            process.exit(1);
+        }
+    }, [error, flags.json]);
+    if (error)
+        return flags.json ? _jsx(_Fragment, {}) : _jsxs(Text, { color: "red", children: ["Error: ", error] });
+    return flags.json ? _jsx(_Fragment, {}) : _jsx(Text, { dimColor: true, children: "Verifying database..." });
+}

package/dist/commands/feed.js

@@ -36,6 +36,19 @@ export default function Feed({ options: flags }) {
                     kind: flags.kind ?? 'default',
                 });
                 if (flags.json) {
+                    if (result.feed.length === 0) {
+                        const kind = flags.kind ?? 'default';
+                        process.stderr.write([
+                            '[sonar feed] Empty result — possible causes:',
+                            kind === 'bookmarks'
+                                ? '  • No bookmarks ingested yet. Run: sonar ingest bookmarks'
+                                : `  • No tweets matched your interests in the last ${windowLabel(flags.hours, flags.days)}.`,
+                            '  • Check interests are configured: sonar interests',
+                            '  • Ingest may be stale: sonar ingest tweets && sonar monitor',
+                            '  • Widen the window: sonar feed --hours 48',
+                            '  • Account/quota status: sonar account',
+                        ].join('\n') + '\n');
+                    }
                     process.stdout.write(`${JSON.stringify(result.feed, null, 2)}\n`);
                     process.exit(0);
                 }
@@ -54,7 +67,8 @@ export default function Feed({ options: flags }) {
         return _jsx(Spinner, { label: "Fetching feed..." });
     }
     if (data.length === 0) {
-        return _jsx(Text, { dimColor: true, children: "No tweets found in this window." });
+        const kind = flags.kind ?? 'default';
+        return (_jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsx(Text, { color: "yellow", children: "No tweets found." }), kind === 'bookmarks' ? (_jsxs(Box, { flexDirection: "column", gap: 0, children: [_jsx(Text, { dimColor: true, children: "Your bookmarks feed is empty. Things to check:" }), _jsxs(Text, { dimColor: true, children: ["  1. Ingest bookmarks first:  ", _jsx(Text, { color: "cyan", children: "sonar ingest bookmarks" })] }), _jsxs(Text, { dimColor: true, children: ["  2. Then monitor progress:   ", _jsx(Text, { color: "cyan", children: "sonar monitor --watch" })] })] })) : (_jsxs(Box, { flexDirection: "column", gap: 0, children: [_jsxs(Text, { dimColor: true, children: ["No ", kind === 'followers' ? 'follower' : kind === 'following' ? 'following' : 'network', " tweets matched your interests in the last ", _jsx(Text, { color: "white", children: windowLabel(flags.hours, flags.days) }), "."] }), _jsx(Text, { dimColor: true, children: "Things to check:" }), _jsxs(Text, { dimColor: true, children: ["  1. Widen the window:         ", _jsx(Text, { color: "cyan", children: "sonar feed --hours 48" }), " or ", _jsx(Text, { color: "cyan", children: "--days 7" })] }), _jsxs(Text, { dimColor: true, children: ["  2. Check interests exist:    ", _jsx(Text, { color: "cyan", children: "sonar interests" })] }), _jsxs(Text, { dimColor: true, children: ["  3. Trigger ingest if stale:  ", _jsx(Text, { color: "cyan", children: "sonar ingest tweets" })] }), _jsxs(Text, { dimColor: true, children: ["  4. Check ingest progress:    ", _jsx(Text, { color: "cyan", children: "sonar monitor" })] }), _jsxs(Text, { dimColor: true, children: ["  5. Run matching:             ", _jsx(Text, { color: "cyan", children: "sonar interests match" })] })] })), _jsxs(Text, { dimColor: true, children: ["Account status and quota: ", _jsx(Text, { color: "cyan", children: "sonar account" })] })] }));
     }
     if (flags.interactive) {
         return _jsx(InteractiveFeedSession, { items: data, vendor: getVendor(flags.vendor) });

package/dist/commands/inbox/index.js

@@ -56,6 +56,16 @@ export default function Inbox({ options: flags }) {
                     limit: flags.limit,
                 });
                 if (flags.json) {
+                    if (result.suggestions.length === 0) {
+                        const statusLabel = flags.all ? 'all statuses' : (flags.status ?? 'inbox');
+                        process.stderr.write([
+                            `[sonar inbox] Empty result for status=${statusLabel} — possible causes:`,
+                            '  • No interests defined. Run: sonar interests create --from-prompt "..."',
+                            '  • Ingest and matching have not run. Run: sonar ingest tweets && sonar interests match',
+                            '  • All inbox items were already actioned. Try: sonar inbox --all',
+                            '  • Account/quota issue. Run: sonar account',
+                        ].join('\n') + '\n');
+                    }
                     process.stdout.write(JSON.stringify(result.suggestions, null, 2) + '\n');
                     process.exit(0);
                 }
@@ -74,7 +84,8 @@ export default function Inbox({ options: flags }) {
         return _jsx(Spinner, { label: "Fetching inbox..." });
     }
     if (data.length === 0) {
-        return _jsx(Text, { dimColor: true, children: "Inbox is empty." });
+        const statusLabel = flags.all ? 'all statuses' : (flags.status ?? 'inbox');
+        return (_jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsxs(Text, { color: "yellow", children: ["Inbox is empty", statusLabel !== 'all statuses' ? ` (status: ${statusLabel})` : '', "."] }), _jsxs(Box, { flexDirection: "column", gap: 0, children: [_jsx(Text, { dimColor: true, children: "Things to check:" }), flags.status && !flags.all && (_jsxs(Text, { dimColor: true, children: ["  1. Broaden scope:            ", _jsx(Text, { color: "cyan", children: "sonar inbox --all" })] })), _jsxs(Text, { dimColor: true, children: ["  ", flags.status && !flags.all ? '2' : '1', ". Interests defined?       ", _jsx(Text, { color: "cyan", children: "sonar interests" })] }), _jsxs(Text, { dimColor: true, children: ["  ", flags.status && !flags.all ? '3' : '2', ". Ingest recent tweets:    ", _jsx(Text, { color: "cyan", children: "sonar ingest tweets" })] }), _jsxs(Text, { dimColor: true, children: ["  ", flags.status && !flags.all ? '4' : '3', ". Run interest matching:   ", _jsx(Text, { color: "cyan", children: "sonar interests match" })] }), _jsxs(Text, { dimColor: true, children: ["  ", flags.status && !flags.all ? '5' : '4', ". Monitor job progress:    ", _jsx(Text, { color: "cyan", children: "sonar monitor" })] })] }), _jsxs(Text, { dimColor: true, children: ["Account status and quota: ", _jsx(Text, { color: "cyan", children: "sonar account" })] })] }));
     }
     if (flags.interactive) {
         return _jsx(InteractiveInboxSession, { items: data, vendor: getVendor(flags.vendor) });

package/dist/commands/index.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Text, Box } from 'ink';
 export default function Index() {
-    return (_jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsx(Text, { bold: true, children: "Sonar CLI" }), _jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "Commands:" }), _jsx(Text, { children: "  feed          Scored tweet feed from your network" }), _jsx(Text, { children: "  inbox         Suggestions matching your interests" }), _jsx(Text, { children: "  interests     Manage interests" }), _jsx(Text, { children: "  \u2514\u2500\u2500 create    Create a new interest" }), _jsx(Text, { children: "  \u2514\u2500\u2500 update    Update an interest" }), _jsx(Text, { children: "  \u2514\u2500\u2500 match     Match interests to ingested tweets" }), _jsx(Text, { children: "  ingest        Ingest tweets and bookmarks" }), _jsx(Text, { children: "  \u2514\u2500\u2500 tweets    Ingest recent tweets from social graph" }), _jsx(Text, { children: "  \u2514\u2500\u2500 bookmarks Ingest X bookmarks" }), _jsx(Text, { children: "  monitor       Job queue monitor and account status" }), _jsx(Text, { children: "  config        Show or set CLI config" }), _jsx(Text, { children: "  account       Account info and plan usage" })] }), _jsxs(Text, { dimColor: true, children: ["Run ", _jsx(Text, { color: "cyan", children: "sonar <command> --help" }), " for command-specific options."] })] }));
+    return (_jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsx(Text, { bold: true, children: "Sonar CLI" }), _jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "Commands:" }), _jsx(Text, { children: "  feed          Scored tweet feed from your network" }), _jsx(Text, { children: "  inbox         Suggestions matching your interests" }), _jsx(Text, { children: "  interests     Manage interests" }), _jsx(Text, { children: "  \u2514\u2500\u2500 create    Create a new interest" }), _jsx(Text, { children: "  \u2514\u2500\u2500 update    Update an interest" }), _jsx(Text, { children: "  \u2514\u2500\u2500 match     Match interests to ingested tweets" }), _jsx(Text, { children: "  ingest        Ingest tweets and bookmarks" }), _jsx(Text, { children: "  \u2514\u2500\u2500 tweets    Ingest recent tweets from social graph" }), _jsx(Text, { children: "  \u2514\u2500\u2500 bookmarks Ingest X bookmarks" }), _jsx(Text, { children: "  monitor       Job queue monitor and account status" }), _jsx(Text, { children: "  config        Show or set CLI config" }), _jsx(Text, { children: "  account       Account info and plan usage" }), _jsx(Text, { children: "  quickstart    First-run setup wizard" })] }), _jsxs(Text, { dimColor: true, children: ["Run ", _jsx(Text, { color: "cyan", children: "sonar <command> --help" }), " for command-specific options."] })] }));
 }

package/dist/commands/ingest/bookmarks.js

@@ -1,13 +1,28 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { Box, Text } from 'ink';
 import { gql } from '../../lib/client.js';
 import { Spinner } from '../../components/Spinner.js';
 import { RefreshTip } from '../../components/RefreshTip.js';
+/** How long (ms) to wait for the ingest mutation before giving up. */
+const INGEST_TIMEOUT_MS = 15_000;
 export default function IndexBookmarks() {
     const [queued, setQueued] = useState(null);
     const [error, setError] = useState(null);
+    const [timedOut, setTimedOut] = useState(false);
+    const deadlineRef = useRef(null);
     useEffect(() => {
+        // Hard wall-clock timeout — catches cases where the gql call itself
+        // hangs (e.g. server accepts the connection but never sends a response).
+        deadlineRef.current = setTimeout(() => {
+            setTimedOut(true);
+            setError(`Ingest trigger timed out after ${INGEST_TIMEOUT_MS / 1000}s.\n` +
+                'The server accepted the request but did not respond in time.\n' +
+                'Next steps:\n' +
+                '  • Run "sonar monitor" — the job may still be queued\n' +
+                '  • Check SONAR_API_URL points to the correct endpoint\n' +
+                '  • Verify the server is healthy and retry');
+        }, INGEST_TIMEOUT_MS);
         async function run() {
             try {
                 const res = await gql(`
@@ -15,17 +30,26 @@ export default function IndexBookmarks() {
             indexBookmarks
           }
         `);
+                if (deadlineRef.current)
+                    clearTimeout(deadlineRef.current);
                 setQueued(res.indexBookmarks);
             }
             catch (err) {
+                if (deadlineRef.current)
+                    clearTimeout(deadlineRef.current);
                 setError(err instanceof Error ? err.message : String(err));
             }
         }
         run();
+        return () => {
+            if (deadlineRef.current)
+                clearTimeout(deadlineRef.current);
+        };
     }, []);
-    if (error)
-        return _jsxs(Text, { color: "red", children: ["Error: ", error] });
+    if (error) {
+        return (_jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsxs(Text, { color: timedOut ? 'yellow' : 'red', children: [timedOut ? '⚠ ' : 'Error: ', error] }), timedOut && (_jsxs(Text, { dimColor: true, children: ["Tip: run ", _jsx(Text, { color: "cyan", children: "sonar monitor" }), " to check whether the job was queued despite the timeout."] }))] }));
+    }
     if (queued === null)
         return _jsx(Spinner, { label: "Triggering bookmark indexing..." });
-    return (_jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsxs(Text, { children: [_jsx(Text, { color: "cyan", children: "index_bookmarks: " }), _jsx(Text, { children: queued ? '✓ queued' : '✗ failed' })] }), _jsx(RefreshTip, {})] }));
+    return (_jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsxs(Text, { children: [_jsx(Text, { color: "cyan", children: "index_bookmarks: " }), _jsx(Text, { children: queued ? '✓ queued' : '✗ failed to queue — check server logs' })] }), !queued && (_jsxs(Text, { dimColor: true, children: ["The server returned false. Verify your API key and account status with ", _jsx(Text, { color: "cyan", children: "sonar account" }), "."] })), _jsx(RefreshTip, {})] }));
 }

package/dist/commands/ingest/tweets.js

@@ -1,13 +1,28 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { Box, Text } from 'ink';
 import { gql } from '../../lib/client.js';
 import { Spinner } from '../../components/Spinner.js';
 import { RefreshTip } from '../../components/RefreshTip.js';
+/** How long (ms) to wait for the ingest mutation before giving up. */
+const INGEST_TIMEOUT_MS = 15_000;
 export default function IndexTweets() {
     const [queued, setQueued] = useState(null);
     const [error, setError] = useState(null);
+    const [timedOut, setTimedOut] = useState(false);
+    const deadlineRef = useRef(null);
     useEffect(() => {
+        // Hard wall-clock timeout — catches cases where the gql call itself
+        // hangs (e.g. server accepts the connection but never sends a response).
+        deadlineRef.current = setTimeout(() => {
+            setTimedOut(true);
+            setError(`Ingest trigger timed out after ${INGEST_TIMEOUT_MS / 1000}s.\n` +
+                'The server accepted the request but did not respond in time.\n' +
+                'Next steps:\n' +
+                '  • Run "sonar monitor" — the job may still be queued\n' +
+                '  • Check SONAR_API_URL points to the correct endpoint\n' +
+                '  • Verify the server is healthy and retry');
+        }, INGEST_TIMEOUT_MS);
         async function run() {
             try {
                 const res = await gql(`
@@ -15,17 +30,26 @@ export default function IndexTweets() {
             indexTweets
           }
         `);
+                if (deadlineRef.current)
+                    clearTimeout(deadlineRef.current);
                 setQueued(res.indexTweets);
             }
             catch (err) {
+                if (deadlineRef.current)
+                    clearTimeout(deadlineRef.current);
                 setError(err instanceof Error ? err.message : String(err));
             }
         }
         run();
+        return () => {
+            if (deadlineRef.current)
+                clearTimeout(deadlineRef.current);
+        };
     }, []);
-    if (error)
-        return _jsxs(Text, { color: "red", children: ["Error: ", error] });
+    if (error) {
+        return (_jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsxs(Text, { color: timedOut ? 'yellow' : 'red', children: [timedOut ? '⚠ ' : 'Error: ', error] }), timedOut && (_jsxs(Text, { dimColor: true, children: ["Tip: run ", _jsx(Text, { color: "cyan", children: "sonar monitor" }), " to check whether the job was queued despite the timeout."] }))] }));
+    }
     if (queued === null)
         return _jsx(Spinner, { label: "Triggering tweet indexing..." });
-    return (_jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsxs(Text, { children: [_jsx(Text, { color: "cyan", children: "index_tweets: " }), _jsx(Text, { children: queued ? '✓ queued' : '✗ failed' })] }), _jsx(RefreshTip, {})] }));
+    return (_jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsxs(Text, { children: [_jsx(Text, { color: "cyan", children: "index_tweets: " }), _jsx(Text, { children: queued ? '✓ queued' : '✗ failed to queue — check server logs' })] }), !queued && (_jsxs(Text, { dimColor: true, children: ["The server returned false. Verify your API key and account status with ", _jsx(Text, { color: "cyan", children: "sonar account" }), "."] })), _jsx(RefreshTip, {})] }));
 }

package/dist/commands/interests/create.js

@@ -1,9 +1,9 @@
-import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useState } from 'react';
 import zod from 'zod';
 import { Box, Text } from 'ink';
 import { gql } from '../../lib/client.js';
-import { generateInterest } from '../../lib/ai.js';
+import { generateInterest, OPENAI_TIMEOUT_MS, ANTHROPIC_TIMEOUT_MS } from '../../lib/ai.js';
 import { getVendor } from '../../lib/config.js';
 import { Spinner } from '../../components/Spinner.js';
 export const options = zod.object({
@@ -44,6 +44,12 @@ const CREATE_MUTATION = `
 export default function InterestsCreate({ options: flags }) {
     const [data, setData] = useState(null);
     const [error, setError] = useState(null);
+    useEffect(() => {
+        if (!error || !flags.json)
+            return;
+        process.stderr.write(`${error}\n`);
+        process.exit(1);
+    }, [error, flags.json]);
     useEffect(() => {
         async function run() {
             try {
@@ -82,11 +88,18 @@ export default function InterestsCreate({ options: flags }) {
         }
         run();
     }, []);
-    if (error)
+    if (error) {
+        if (flags.json)
+            return _jsx(_Fragment, {});
         return _jsxs(Text, { color: "red", children: ["Error: ", error] });
+    }
     if (!data) {
+        if (flags.json)
+            return _jsx(_Fragment, {});
+        const vendor = getVendor(flags.vendor);
+        const timeoutSec = (vendor === 'openai' ? OPENAI_TIMEOUT_MS : ANTHROPIC_TIMEOUT_MS) / 1000;
         const label = flags.fromPrompt
-            ? `Generating interest via ${getVendor(flags.vendor)}...`
+            ? `Generating interest via ${vendor}... (may take up to ${timeoutSec}s${vendor === 'openai' ? ' with web search' : ''})`
             : 'Creating interest...';
         return _jsx(Spinner, { label: label });
     }

package/dist/commands/interests/update.js

@@ -1,9 +1,9 @@
-import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useState } from 'react';
 import zod from 'zod';
 import { Box, Text } from 'ink';
 import { gql } from '../../lib/client.js';
-import { generateInterest } from '../../lib/ai.js';
+import { generateInterest, OPENAI_TIMEOUT_MS, ANTHROPIC_TIMEOUT_MS } from '../../lib/ai.js';
 import { getVendor } from '../../lib/config.js';
 import { Spinner } from '../../components/Spinner.js';
 export const options = zod.object({
@@ -70,6 +70,12 @@ async function fetchById(id) {
 export default function InterestsUpdate({ options: flags }) {
     const [data, setData] = useState(null);
     const [error, setError] = useState(null);
+    useEffect(() => {
+        if (!error || !flags.json)
+            return;
+        process.stderr.write(`${error}\n`);
+        process.exit(1);
+    }, [error, flags.json]);
     useEffect(() => {
         async function run() {
             try {
@@ -128,14 +134,19 @@ export default function InterestsUpdate({ options: flags }) {
         }
         run();
     }, []);
-    if (error)
+    if (error) {
+        if (flags.json)
+            return _jsx(_Fragment, {});
         return _jsxs(Text, { color: "red", children: ["Error: ", error] });
+    }
     if (!data) {
+        if (flags.json)
+            return _jsx(_Fragment, {});
+        const vendor = getVendor(flags.vendor);
+        const timeoutSec = (vendor === 'openai' ? OPENAI_TIMEOUT_MS : ANTHROPIC_TIMEOUT_MS) / 1000;
         const label = flags.fromPrompt
-            ? `Generating interest via ${getVendor(flags.vendor)}...`
-            : (flags.addKeywords || flags.removeKeywords || flags.addTopics || flags.removeTopics)
-                ? 'Updating interest...'
-                : 'Updating interest...';
+            ? `Generating interest via ${vendor}... (may take up to ${timeoutSec}s${vendor === 'openai' ? ' with web search' : ''})`
+            : 'Updating interest...';
         return _jsx(Spinner, { label: label });
     }
     return (_jsxs(Box, { flexDirection: "column", gap: 0, children: [_jsxs(Box, { gap: 2, children: [_jsx(Text, { bold: true, color: "cyan", children: data.name }), _jsxs(Text, { dimColor: true, children: ["v", data.version, " \u00B7 ", data.id, " \u00B7 updated"] })] }), data.description && _jsx(Text, { dimColor: true, children: data.description }), data.keywords && data.keywords.length > 0 && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: "keywords:" }), _jsx(Text, { children: data.keywords.join(', ') })] })), data.relatedTopics && data.relatedTopics.length > 0 && (_jsxs(Box, { gap: 1, children: [_jsx(Text, { dimColor: true, children: "topics:  " }), _jsx(Text, { children: data.relatedTopics.join(', ') })] }))] }));

package/dist/commands/monitor.js

@@ -24,9 +24,12 @@ export default function Monitor({ options: flags }) {
         const token = getToken();
         const baseUrl = getApiUrl().replace(/\/graphql$/, '');
         async function fetchStatus() {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), 10_000);
             try {
                 const [statusRes, meRes] = await Promise.all([
                     fetch(`${baseUrl}/indexing/status`, {
+                        signal: controller.signal,
                         headers: { Authorization: `Bearer ${token}` },
                     }),
                     gql(`
@@ -46,6 +49,7 @@ export default function Monitor({ options: flags }) {
             }
           `),
                 ]);
+                clearTimeout(timer);
                 if (!statusRes.ok)
                     throw new Error(`HTTP ${statusRes.status} from ${baseUrl}`);
                 const status = await statusRes.json();
@@ -53,7 +57,15 @@ export default function Monitor({ options: flags }) {
                 setError(null);
             }
             catch (err) {
-                setError(err instanceof Error ? err.message : String(err));
+                clearTimeout(timer);
+                if (err instanceof DOMException && err.name === 'AbortError') {
+                    setError('Monitor request timed out (10s). ' +
+                        'The server may be overloaded. ' +
+                        'Check SONAR_API_URL or retry without --watch.');
+                }
+                else {
+                    setError(err instanceof Error ? err.message : String(err));
+                }
             }
         }
         fetchStatus();

package/dist/commands/quickstart.js

@@ -0,0 +1,231 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { Box, Text, useApp, useInput } from 'ink';
+import { gql } from '../lib/client.js';
+import { readConfig } from '../lib/config.js';
+import { Spinner } from '../components/Spinner.js';
+// ─── Queries / Mutations ──────────────────────────────────────────────────────
+const BOOTSTRAP_QUERY = `
+  query QuickstartBootstrap {
+    me {
+      xHandle
+    }
+    projects {
+      id: nanoId
+    }
+  }
+`;
+const CREATE_MUTATION = `
+  mutation CreateOrUpdateInterest(
+    $nanoId: String
+    $name: String!
+    $description: String
+    $keywords: [String!]
+    $relatedTopics: [String!]
+  ) {
+    createOrUpdateProject(input: {
+      nanoId: $nanoId
+      name: $name
+      description: $description
+      keywords: $keywords
+      relatedTopics: $relatedTopics
+    }) {
+      nanoId
+    }
+  }
+`;
+const INGEST_MUTATION = `
+  mutation IndexTweets {
+    indexTweets
+  }
+`;
+const INBOX_QUERY = `
+  query QuickstartInbox($status: SuggestionStatus, $limit: Int) {
+    suggestions(status: $status, limit: $limit) {
+      suggestionId
+      score
+      projectsMatched
+      status
+      tweet {
+        xid
+        text
+        createdAt
+        user {
+          displayName
+          username
+        }
+      }
+    }
+  }
+`;
+// ─── Starter interest suggestions ────────────────────────────────────────────
+/**
+ * Returns 3 sensible starter interest drafts. In the future this could use
+ * the user's X bio / pinned tweet, but for now these are broadly useful
+ * defaults for the typical Sonar user (tech-forward Twitter crowd).
+ */
+function buildStarterSuggestions(_xHandle) {
+    return [
+        {
+            name: 'AI and machine learning',
+            description: 'Breakthroughs, papers, tools, and discussion around AI, LLMs, and machine learning.',
+            keywords: ['LLM', 'AI agents', 'machine learning', 'GPT', 'fine-tuning', 'inference'],
+            relatedTopics: ['artificial intelligence', 'deep learning', 'foundation models'],
+        },
+        {
+            name: 'Software engineering and developer tools',
+            description: 'New frameworks, libraries, OSS releases, and engineering practices worth tracking.',
+            keywords: ['open source', 'TypeScript', 'Rust', 'developer tools', 'CLI', 'API design'],
+            relatedTopics: ['software development', 'devex', 'programming'],
+        },
+        {
+            name: 'Tech startups and product launches',
+            description: 'Funding rounds, product launches, founder insights, and market moves in tech.',
+            keywords: ['startup', 'YC', 'product launch', 'founder', 'seed round', 'SaaS'],
+            relatedTopics: ['venture capital', 'entrepreneurship', 'B2B software'],
+        },
+    ];
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function relativeTime(dateStr) {
+    const ts = new Date(dateStr).getTime();
+    if (isNaN(ts))
+        return '?';
+    const diff = Math.max(0, Date.now() - ts);
+    const mins = Math.floor(diff / 60000);
+    if (mins < 60)
+        return `${mins}m`;
+    const hours = Math.floor(mins / 60);
+    if (hours < 24)
+        return `${hours}h`;
+    return `${Math.floor(hours / 24)}d`;
+}
+function hasToken() {
+    if (process.env.SONAR_API_KEY?.trim())
+        return true;
+    const config = readConfig();
+    return Boolean(config.token?.trim());
+}
+// ─── Sub-renders ──────────────────────────────────────────────────────────────
+function UnauthenticatedView() {
+    return (_jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsx(Text, { bold: true, color: "yellow", children: "\u26A0  Not authenticated" }), _jsxs(Text, { children: ["Sonar needs an API key to get started. Get one at", ' ', _jsx(Text, { color: "cyan", children: "https://sonar.8640p.info" })] }), _jsxs(Box, { flexDirection: "column", gap: 0, children: [_jsx(Text, { dimColor: true, children: "Then run one of:" }), _jsxs(Text, { children: ["  ", _jsx(Text, { color: "cyan", children: "SONAR_API_KEY=<key> sonar quickstart" }), "  (one-off)"] }), _jsxs(Text, { children: ["  ", _jsx(Text, { color: "cyan", children: "sonar config setup --key <key>" }), "          (persist to ~/.sonar/config.json)"] })] })] }));
+}
+function ConfirmView({ me, suggestions, onConfirm, onAbort, }) {
+    useInput((input, key) => {
+        if (key.return || input === 'y' || input === 'Y') {
+            onConfirm();
+        }
+        else if (input === 'n' || input === 'N' || key.escape) {
+            onAbort();
+        }
+    });
+    return (_jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsxs(Box, { gap: 1, children: [_jsx(Text, { bold: true, color: "cyan", children: "Welcome to Sonar," }), _jsxs(Text, { bold: true, children: ["@", me.xHandle, "!"] })] }), _jsx(Text, { children: "You have no interests set up yet. Here are 3 starter suggestions to get your inbox going:" }), suggestions.map((s, i) => (_jsxs(Box, { flexDirection: "column", gap: 0, paddingLeft: 2, children: [_jsxs(Box, { gap: 1, children: [_jsxs(Text, { color: "cyan", children: [i + 1, "."] }), _jsx(Text, { bold: true, children: s.name })] }), _jsx(Box, { paddingLeft: 4, children: _jsx(Text, { dimColor: true, children: s.description }) }), _jsxs(Box, { gap: 1, paddingLeft: 4, children: [_jsx(Text, { dimColor: true, children: "keywords:" }), _jsx(Text, { dimColor: true, children: s.keywords.slice(0, 4).join(', ') })] })] }, s.name))), _jsxs(Box, { marginTop: 1, gap: 1, children: [_jsx(Text, { dimColor: true, children: "Create these interests and kick off indexing?" }), _jsx(Text, { bold: true, color: "cyan", children: "[Y/n]" })] }), _jsxs(Text, { dimColor: true, children: ["tip: customise later with", ' ', _jsx(Text, { color: "cyan", children: "sonar interests create --from-prompt \"...\"" })] })] }));
+}
+function CreatingView({ suggestions, progress }) {
+    return (_jsxs(Box, { flexDirection: "column", gap: 0, children: [_jsxs(Box, { gap: 1, marginBottom: 1, children: [_jsx(Text, { bold: true, children: "Setting up interests" }), _jsxs(Text, { dimColor: true, children: ["(", progress, "/", suggestions.length, ")"] })] }), suggestions.map((s, i) => (_jsxs(Box, { gap: 1, children: [i < progress ? (_jsx(Text, { color: "green", children: "\u2713" })) : i === progress ? (_jsx(Spinner, { label: "" })) : (_jsx(Text, { dimColor: true, children: "\u00B7" })), _jsx(Text, { dimColor: i > progress, color: i < progress ? 'green' : undefined, children: s.name })] }, s.name)))] }));
+}
+function InboxView({ items, created }) {
+    if (items.length === 0) {
+        return (_jsxs(Box, { flexDirection: "column", gap: 1, children: [created ? (_jsx(Text, { color: "green", children: "\u2713 Interests created and indexing triggered!" })) : (_jsx(Text, { color: "green", children: "\u2713 Your interests are set up \u2014 indexing is in progress." })), _jsxs(Box, { flexDirection: "column", gap: 0, children: [_jsx(Text, { children: "Your inbox is empty right now \u2014 indexing takes a few minutes." }), _jsxs(Text, { dimColor: true, children: ["Check back shortly with: ", _jsx(Text, { color: "cyan", children: "sonar inbox" })] })] }), _jsxs(Box, { flexDirection: "column", gap: 0, children: [_jsxs(Text, { dimColor: true, children: ["Monitor indexing progress: ", _jsx(Text, { color: "cyan", children: "sonar monitor" })] }), _jsxs(Text, { dimColor: true, children: ["Browse your full inbox: ", _jsx(Text, { color: "cyan", children: "sonar inbox" })] }), _jsxs(Text, { dimColor: true, children: ["Edit interests: ", _jsx(Text, { color: "cyan", children: "sonar interests" })] })] })] }));
+    }
+    return (_jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsx(Text, { color: "green", children: "\u2713 You're all set! Here's your inbox:" }), items.slice(0, 10).map((s) => {
+                const handle = s.tweet.user.username ?? s.tweet.user.displayName;
+                return (_jsxs(Box, { flexDirection: "column", gap: 0, children: [_jsxs(Box, { gap: 2, children: [_jsx(Text, { color: "cyan", children: relativeTime(s.tweet.createdAt) }), _jsx(Text, { color: "green", children: s.score.toFixed(2) }), _jsxs(Text, { dimColor: true, children: ["@", handle] })] }), _jsx(Box, { paddingLeft: 2, width: 80, children: _jsx(Text, { wrap: "wrap", dimColor: true, children: s.tweet.text.replace(/\n/g, ' ').slice(0, 120) }) })] }, s.suggestionId));
+            }), items.length > 10 && (_jsxs(Text, { dimColor: true, children: ["\u2026 and ", items.length - 10, " more. Run ", _jsx(Text, { color: "cyan", children: "sonar inbox" }), " to see all."] })), _jsxs(Text, { dimColor: true, children: ["Interactive mode: ", _jsx(Text, { color: "cyan", children: "sonar inbox --interactive" }), '  ·  ', "Full inbox: ", _jsx(Text, { color: "cyan", children: "sonar inbox" })] })] }));
+}
+// ─── Main component ───────────────────────────────────────────────────────────
+export default function Quickstart() {
+    const { exit } = useApp();
+    const [phase, setPhase] = useState({ type: 'loading' });
+    const abortedRef = useRef(false);
+    const confirmedRef = useRef(false);
+    // ── Bootstrap: check auth + fetch me + projects ──────────────────────────
+    useEffect(() => {
+        if (!hasToken()) {
+            setPhase({ type: 'unauthenticated' });
+            return;
+        }
+        async function bootstrap() {
+            try {
+                const result = await gql(BOOTSTRAP_QUERY);
+                if (!result.me) {
+                    setPhase({ type: 'unauthenticated' });
+                    return;
+                }
+                // If interests already exist, jump straight to inbox
+                if (result.projects.length > 0) {
+                    const inbox = await gql(INBOX_QUERY, {
+                        status: 'INBOX',
+                        limit: 20,
+                    });
+                    setPhase({ type: 'inbox', items: inbox.suggestions, created: false });
+                    return;
+                }
+                // No interests — propose starters
+                const suggestions = buildStarterSuggestions(result.me.xHandle);
+                setPhase({ type: 'confirm', me: result.me, suggestions });
+            }
+            catch (err) {
+                setPhase({ type: 'error', message: err instanceof Error ? err.message : String(err) });
+            }
+        }
+        bootstrap();
+    }, []);
+    // ── Create interests + ingest (triggered from confirm handler) ────────────
+    const handleConfirm = async (suggestions) => {
+        if (confirmedRef.current)
+            return;
+        confirmedRef.current = true;
+        setPhase({ type: 'creating', suggestions, progress: 0 });
+        try {
+            // Create each interest sequentially so progress counter is accurate
+            for (let i = 0; i < suggestions.length; i++) {
+                if (abortedRef.current)
+                    return;
+                const s = suggestions[i];
+                await gql(CREATE_MUTATION, {
+                    nanoId: null,
+                    name: s.name,
+                    description: s.description,
+                    keywords: s.keywords,
+                    relatedTopics: s.relatedTopics,
+                });
+                setPhase({ type: 'creating', suggestions, progress: i + 1 });
+            }
+            // Trigger ingest
+            setPhase({ type: 'ingesting' });
+            await gql(INGEST_MUTATION);
+            // Fetch initial inbox (may be empty — that's fine)
+            const inbox = await gql(INBOX_QUERY, {
+                status: 'INBOX',
+                limit: 20,
+            });
+            setPhase({ type: 'inbox', items: inbox.suggestions, created: true });
+        }
+        catch (err) {
+            setPhase({ type: 'error', message: err instanceof Error ? err.message : String(err) });
+        }
+    };
+    const handleAbort = () => {
+        abortedRef.current = true;
+        process.stdout.write('\nAborted. Run sonar quickstart again whenever you\'re ready.\n');
+        exit();
+    };
+    // ── Render ─────────────────────────────────────────────────────────────────
+    switch (phase.type) {
+        case 'loading':
+            return _jsx(Spinner, { label: "Loading your Sonar profile..." });
+        case 'unauthenticated':
+            return _jsx(UnauthenticatedView, {});
+        case 'error':
+            return (_jsxs(Box, { flexDirection: "column", gap: 1, children: [_jsxs(Text, { color: "red", children: ["Error: ", phase.message] }), _jsxs(Text, { dimColor: true, children: ["Check your connection and API key, then retry: ", _jsx(Text, { color: "cyan", children: "sonar quickstart" })] })] }));
+        case 'confirm':
+            return (_jsx(ConfirmView, { me: phase.me, suggestions: phase.suggestions, onConfirm: () => handleConfirm(phase.suggestions), onAbort: handleAbort }));
+        case 'creating':
+            return _jsx(CreatingView, { suggestions: phase.suggestions, progress: phase.progress });
+        case 'ingesting':
+            return _jsx(Spinner, { label: "Triggering tweet indexing..." });
+        case 'inbox':
+            return _jsx(InboxView, { items: phase.items, created: phase.created });
+    }
+}

package/dist/lib/ai.js

@@ -27,8 +27,46 @@ Given a user's prompt, expand it into a rich interest profile and return a JSON
 Optimise every field for semantic density and current relevance, not readability.
 
 Respond ONLY with valid JSON, no markdown, no explanation.`;
+// OpenAI uses web_search_preview which can legitimately take 30-60 s.
+export const OPENAI_TIMEOUT_MS = 90_000;
+// Anthropic calls are simpler — 60 s is generous.
+export const ANTHROPIC_TIMEOUT_MS = 60_000;
+/**
+ * Wraps fetch() with an AbortController timeout that covers the full response
+ * cycle — headers AND body. The processResponse callback receives the Response
+ * and is responsible for consuming the body (e.g. calling res.json()). The
+ * timer is kept alive until processResponse resolves or rejects, ensuring a
+ * stalled body download is caught just like a stalled connection.
+ */
+async function fetchWithTimeout(url, init, timeoutMs, vendorLabel, processResponse) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, { ...init, signal: controller.signal });
+        return await processResponse(res);
+    }
+    catch (err) {
+        if (err instanceof DOMException && err.name === 'AbortError') {
+            const lines = [
+                `${vendorLabel} request timed out after ${timeoutMs / 1000}s.`,
+                'Possible causes:',
+                '  • The AI provider is overloaded or rate-limiting you',
+                '  • Your network connection is slow or unstable',
+            ];
+            if (vendorLabel.toLowerCase().includes('openai')) {
+                lines.push('  • The web_search tool (OpenAI) took longer than usual');
+            }
+            lines.push('Try again in a moment, or use --vendor to switch providers.');
+            throw new Error(lines.join('\n'));
+        }
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 async function callOpenAI(prompt, apiKey) {
-    const res = await fetch('https://api.openai.com/v1/responses', {
+    return fetchWithTimeout('https://api.openai.com/v1/responses', {
         method: 'POST',
         headers: {
             'Content-Type': 'application/json',
@@ -40,22 +78,23 @@ async function callOpenAI(prompt, apiKey) {
             instructions: SYSTEM_PROMPT,
             input: prompt,
         }),
+    }, OPENAI_TIMEOUT_MS, 'OpenAI', async (res) => {
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({}));
+            throw new Error(`OpenAI error: ${err?.error?.message ?? res.status}`);
+        }
+        const data = await res.json();
+        const text = data.output
+            ?.filter((b) => b.type === 'message')
+            .flatMap((b) => b.content)
+            .filter((c) => c.type === 'output_text')
+            .map((c) => c.text)
+            .join('') ?? '';
+        return JSON.parse(extractJSON(text));
     });
-    if (!res.ok) {
-        const err = await res.json().catch(() => ({}));
-        throw new Error(`OpenAI error: ${err?.error?.message ?? res.status}`);
-    }
-    const data = await res.json();
-    const text = data.output
-        ?.filter((b) => b.type === 'message')
-        .flatMap((b) => b.content)
-        .filter((c) => c.type === 'output_text')
-        .map((c) => c.text)
-        .join('') ?? '';
-    return JSON.parse(extractJSON(text));
 }
 async function callAnthropic(prompt, apiKey) {
-    const res = await fetch('https://api.anthropic.com/v1/messages', {
+    return fetchWithTimeout('https://api.anthropic.com/v1/messages', {
         method: 'POST',
         headers: {
             'Content-Type': 'application/json',
@@ -68,20 +107,21 @@ async function callAnthropic(prompt, apiKey) {
             system: SYSTEM_PROMPT,
             messages: [{ role: 'user', content: prompt }],
         }),
+    }, ANTHROPIC_TIMEOUT_MS, 'Anthropic', async (res) => {
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({}));
+            throw new Error(`Anthropic error: ${err?.error?.message ?? res.status}`);
+        }
+        const data = await res.json();
+        return JSON.parse(extractJSON(data.content[0].text));
     });
-    if (!res.ok) {
-        const err = await res.json().catch(() => ({}));
-        throw new Error(`Anthropic error: ${err?.error?.message ?? res.status}`);
-    }
-    const data = await res.json();
-    return JSON.parse(extractJSON(data.content[0].text));
 }
 const REPLY_SYSTEM_PROMPT = `You are a concise, contextual tweet reply writer. Write a single reply tweet (max 280 characters) that is natural, engaging, and relevant to the original tweet. Do not use hashtags unless essential. Do not include any explanation or preamble. Return only valid JSON with a single "reply" field containing the reply text.`;
 async function callOpenAIReply(tweetText, userPrompt, apiKey) {
     const userContent = userPrompt
         ? `Original tweet: "${tweetText}"\n\nAngle for reply: ${userPrompt}`
         : `Original tweet: "${tweetText}"\n\nWrite a thoughtful reply.`;
-    const res = await fetch('https://api.openai.com/v1/chat/completions', {
+    return fetchWithTimeout('https://api.openai.com/v1/chat/completions', {
         method: 'POST',
         headers: {
             'Content-Type': 'application/json',
@@ -94,20 +134,21 @@ async function callOpenAIReply(tweetText, userPrompt, apiKey) {
                 { role: 'user', content: userContent },
             ],
         }),
+    }, OPENAI_TIMEOUT_MS, 'OpenAI', async (res) => {
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({}));
+            throw new Error(`OpenAI error: ${err?.error?.message ?? res.status}`);
+        }
+        const data = await res.json();
+        const text = data.choices?.[0]?.message?.content ?? '';
+        return JSON.parse(extractJSON(text));
     });
-    if (!res.ok) {
-        const err = await res.json().catch(() => ({}));
-        throw new Error(`OpenAI error: ${err?.error?.message ?? res.status}`);
-    }
-    const data = await res.json();
-    const text = data.choices?.[0]?.message?.content ?? '';
-    return JSON.parse(extractJSON(text));
 }
 async function callAnthropicReply(tweetText, userPrompt, apiKey) {
     const userContent = userPrompt
         ? `Original tweet: "${tweetText}"\n\nAngle for reply: ${userPrompt}`
         : `Original tweet: "${tweetText}"\n\nWrite a thoughtful reply.`;
-    const res = await fetch('https://api.anthropic.com/v1/messages', {
+    return fetchWithTimeout('https://api.anthropic.com/v1/messages', {
         method: 'POST',
         headers: {
             'Content-Type': 'application/json',
@@ -120,13 +161,14 @@ async function callAnthropicReply(tweetText, userPrompt, apiKey) {
             system: REPLY_SYSTEM_PROMPT,
             messages: [{ role: 'user', content: userContent }],
         }),
+    }, ANTHROPIC_TIMEOUT_MS, 'Anthropic', async (res) => {
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({}));
+            throw new Error(`Anthropic error: ${err?.error?.message ?? res.status}`);
+        }
+        const data = await res.json();
+        return JSON.parse(extractJSON(data.content[0].text));
     });
-    if (!res.ok) {
-        const err = await res.json().catch(() => ({}));
-        throw new Error(`Anthropic error: ${err?.error?.message ?? res.status}`);
-    }
-    const data = await res.json();
-    return JSON.parse(extractJSON(data.content[0].text));
 }
 export async function generateReply(tweetText, userPrompt, vendor) {
     if (vendor === 'openai') {

package/dist/lib/client.js

@@ -1,14 +1,27 @@
 import { getApiUrl, getToken } from './config.js';
+/**
+ * Execute a GraphQL request against the Sonar API.
+ *
+ * A hard timeout (default 20 s) is applied via AbortController so that the
+ * process never hangs silently when the server is unresponsive.  The timeout
+ * is intentionally surfaced as a distinct error so callers can give operators
+ * an actionable message (e.g. "check server health / retry").
+ */
 export async function gql(query, variables = {}, flags = {}) {
     const token = getToken();
     const url = getApiUrl();
+    const timeoutMs = flags.timeoutMs ?? 20_000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
     let res;
     try {
         if (flags.debug) {
             console.error(url, query, variables);
         }
+        console.log('url', url);
         res = await fetch(url, {
             method: 'POST',
+            signal: controller.signal,
             headers: {
                 'Content-Type': 'application/json',
                 Authorization: `Bearer ${token}`,
@@ -16,9 +29,18 @@ export async function gql(query, variables = {}, flags = {}) {
             body: JSON.stringify({ query, variables }),
         });
     }
-    catch {
+    catch (err) {
+        clearTimeout(timer);
+        if (err instanceof DOMException && err.name === 'AbortError') {
+            throw new Error(`Request timed out after ${timeoutMs / 1000}s. ` +
+                'The server may be overloaded or unreachable. ' +
+                'Check SONAR_API_URL, your network connection, and retry.');
+        }
         throw new Error('Unable to reach server, please try again shortly.');
     }
+    finally {
+        clearTimeout(timer);
+    }
     if (!res.ok) {
         if (flags.debug) {
             console.error(JSON.stringify(await res.json(), null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1a35e1/sonar-cli",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "X/Twitter social graph CLI for signal filtering and curation",
   "type": "module",
   "bin": {