@1a35e1/sonar-cli 0.1.2 → 0.2.0

package/README.md

@@ -20,7 +20,7 @@ This cli has been designed to handover indexing and consumption to agents.
 Install the CLI
 
 ```sh
-pnpm add -g @1a35e1/sonar-cli
+pnpm add -g @1a35e1/sonar-cli@latest
 ```
 
 Register your API key.

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 ingest 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 ingest 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 ingest 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 ingest 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/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 ingest 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 ingest 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 ingest 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 ingest 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/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,7 +1,18 @@
 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) {
@@ -9,6 +20,7 @@ export async function gql(query, variables = {}, flags = {}) {
         }
         res = await fetch(url, {
             method: 'POST',
+            signal: controller.signal,
             headers: {
                 'Content-Type': 'application/json',
                 Authorization: `Bearer ${token}`,
@@ -16,9 +28,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.2",
+  "version": "0.2.0",
   "description": "X/Twitter social graph CLI for signal filtering and curation",
   "type": "module",
   "bin": {
@@ -22,6 +22,7 @@
     "graphql": "^16.12.0",
     "graphql-request": "^7.4.0",
     "ink": "^6",
+    "ink-link": "^5.0.0",
     "ink-table": "^3.1.0",
     "pastel": "^3.0.0",
     "react": "^19",
@@ -34,7 +35,6 @@
     "@types/node": "^22",
     "@types/react": "^19",
     "biome": "^0.3.3",
-    "ink-link": "^5.0.0",
     "tsx": "^4",
     "typescript": "^5"
   },