@1a35e1/sonar-cli 0.2.0 → 0.3.4

package/dist/lib/client.js

@@ -1,54 +1,81 @@
 import { getApiUrl, getToken } from './config.js';
+const MAX_RETRIES = Math.max(0, Number(process.env.SONAR_MAX_RETRIES) || 3);
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function retryDelay(attempt) {
+    const base = Math.min(1000 * 2 ** attempt, 10_000);
+    return base + Math.random() * 500;
+}
 /**
  * Execute a GraphQL request against the Sonar API.
  *
+ * Retries transient failures (network errors, 5xx) with jittered exponential
+ * backoff.  Deterministic failures (4xx, GraphQL errors) throw immediately.
+ * Control retries via SONAR_MAX_RETRIES env var (default 3, 0 to disable).
+ *
  * 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").
+ * process never hangs silently when the server is unresponsive.
  */
 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);
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        let res;
+        try {
+            if (flags.debug) {
+                console.error(url, query, variables);
+            }
+            res = await fetch(url, {
+                method: 'POST',
+                signal: controller.signal,
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${token}`,
+                },
+                body: JSON.stringify({ query, variables }),
+            });
         }
-        res = await fetch(url, {
-            method: 'POST',
-            signal: controller.signal,
-            headers: {
-                'Content-Type': 'application/json',
-                Authorization: `Bearer ${token}`,
-            },
-            body: JSON.stringify({ query, variables }),
-        });
-    }
-    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.');
+        catch (err) {
+            clearTimeout(timer);
+            if (attempt < MAX_RETRIES) {
+                if (flags.debug)
+                    console.error(`Retry ${attempt + 1}/${MAX_RETRIES} after network error`);
+                await sleep(retryDelay(attempt));
+                continue;
+            }
+            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.');
         }
-        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));
+        finally {
+            clearTimeout(timer);
         }
-        throw new Error(`HTTP ${res.status}: ${res.statusText}`);
-    }
-    const json = (await res.json());
-    if (json.errors && json.errors.length > 0) {
-        throw new Error(json.errors[0].message);
+        // 5xx — transient, retry
+        if (res.status >= 500 && attempt < MAX_RETRIES) {
+            if (flags.debug)
+                console.error(`Retry ${attempt + 1}/${MAX_RETRIES} after HTTP ${res.status}`);
+            await sleep(retryDelay(attempt));
+            continue;
+        }
+        // 4xx — deterministic, throw immediately
+        if (!res.ok) {
+            if (flags.debug) {
+                console.error(JSON.stringify(await res.json(), null, 2));
+            }
+            throw new Error(`HTTP ${res.status}: ${res.statusText}`);
+        }
+        const json = (await res.json());
+        if (json.errors && json.errors.length > 0) {
+            throw new Error(json.errors[0].message);
+        }
+        return json.data;
     }
-    return json.data;
+    throw new Error('Unexpected retry exhaustion');
 }

package/dist/lib/config.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { DB_PATH } from './db.js';
 const CONFIG_DIR = join(homedir(), '.sonar');
 const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
 export function readConfig() {
@@ -24,8 +25,8 @@ export function deleteConfig() {
     }
 }
 export function deleteDatabase() {
-    if (existsSync(join(CONFIG_DIR, 'database.sqlite'))) {
-        unlinkSync(join(CONFIG_DIR, 'database.sqlite'));
+    if (existsSync(DB_PATH)) {
+        unlinkSync(DB_PATH);
     }
 }
 export function writeConfig(config) {

package/dist/lib/data-queries.js

@@ -48,12 +48,10 @@ export const SUGGESTIONS_QUERY = `
 `;
 export const INTERESTS_QUERY = `
   query DataInterests {
-    projects {
+    topics {
       id: nanoId
       name
       description
-      keywords
-      relatedTopics
       createdAt
       updatedAt
     }

package/dist/lib/skill.js

@@ -3,7 +3,7 @@ import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
 const SKILL_CONTENT = `---
 name: sonar
-description: Sonar CLI — manage interests, suggestions, indexing jobs, and account config for the Sonar social intelligence platform. Use when the user asks about their Sonar account, wants to create/list interests, check suggestions, trigger indexing, or configure the CLI.
+description: Sonar CLI — view and triage your feed, manage topics, trigger refresh jobs, and manage local Sonar config/data.
 homepage: https://sonar.sh
 user-invocable: true
 allowed-tools: Bash
@@ -13,261 +13,101 @@ metadata: {"openclaw":{"emoji":"📡","primaryEnv":"SONAR_API_KEY","requires":{"
 
 # Sonar CLI
 
-Sonar is a social intelligence platform. Use the \`sonar\` CLI to manage the user's account.
+All commands are invoked as: \`sonar <command> [subcommand] [flags]\`.
 
-All commands are invoked as: \`sonar <command> [subcommand] [flags]\`
-
----
-
-## Account & Config
+## Core usage
 
 \`\`\`bash
-# Show account info, plan usage, and suggestion counts
-sonar account
-
-# Show current CLI config (API URL, vendor, token presence)
-sonar config
-
-# Set AI vendor preference for --from-prompt (saved to ~/.sonar/config.json)
-sonar config set vendor openai      # or: anthropic
-
-# Initialise workspace from environment variables
-# Requires: SONAR_API_KEY
-sonar config setup
+# Default view (combined ranked stream from feed + inbox)
+sonar
+sonar --hours 24
+sonar --days 3
+sonar --kind default            # default | bookmarks | followers | following
+sonar --limit 50
+sonar --render card             # card | table
+sonar --width 100
+sonar --json
+sonar --no-interactive
 \`\`\`
 
----
-
-## Interests
-
-Interests are named topic areas with keywords and related topics that drive suggestion matching.
+## Topic management
 
 \`\`\`bash
-# List all interests
-sonar interests
-
-# Create manually
-sonar interests create --name "AI Agents" --description "LLM-based agents and tooling" \\
-  --keywords "agents,llm,tools,mcp" --topics "machine learning,AI safety"
-
-# Generate fields from a natural language prompt (uses OPENAI_API_KEY or ANTHROPIC_API_KEY)
-sonar interests create --from-prompt "I want to follow the Rust ecosystem and systems programming"
-
-# Generate with a specific vendor (overrides config preference)
-sonar interests create --from-prompt "DeFi and crypto protocols" --vendor anthropic
-
-# Update an existing interest (full replace)
-sonar interests update --id <id> --name "New Name" --keywords "kw1,kw2"
-
-# Add keywords to an existing interest (fetches current, merges, sends full list)
-sonar interests update --id <id> --add-keywords "mcp,a2a,langgraph"
-
-# Remove keywords from an existing interest
-sonar interests update --id <id> --remove-keywords "old-term,deprecated-kw"
-
-# Add and remove keywords in one shot
-sonar interests update --id <id> --add-keywords "vibe-coding" --remove-keywords "cursor"
-
-# Same flags work for related topics
-sonar interests update --id <id> --add-topics "AI safety" --remove-topics "machine learning"
-
-# Combine keyword/topic patching with a name change
-sonar interests update --id <id> --name "New Name" --add-keywords "new-kw"
-
-# Regenerate all fields from a new prompt (replaces everything)
-sonar interests update --id <id> --from-prompt "Rust and WebAssembly tooling"
-
-# Output raw JSON (agent-friendly)
-sonar interests --json
+# List topics
+sonar topics
+sonar topics --json
+
+# Add/update topics
+sonar topics add "AI agents"
+sonar topics add "Rust systems programming" --description "..."
+sonar topics edit --id <topic_id> --name "New Name"
+sonar topics edit --id <topic_id> --description "Updated description"
+sonar topics edit --id <topic_id> --json
 \`\`\`
 
-**AI vendor resolution order:**
-1. \`--vendor\` flag
-2. \`SONAR_AI_VENDOR\` environment variable
-3. \`vendor\` in \`~/.sonar/config.json\` (set via \`sonar config set vendor\`)
-4. Defaults to \`openai\`
-
-Required env vars: \`OPENAI_API_KEY\` (OpenAI) or \`ANTHROPIC_API_KEY\` (Anthropic)
-
----
-
-## Feed
-
-Scored tweet feed from your social network, filtered by interests.
+## Pipeline and triage
 
 \`\`\`bash
-# Show feed (default: last 12h, limit 20, card layout)
-sonar feed
-
-# Time window
-sonar feed --hours 24
-sonar feed --days 3
-
-# Limit results
-sonar feed --limit 50
-
-# Output layout
-sonar feed --render card    # default — rich card view
-sonar feed --render table   # compact table view
-sonar feed --width 100      # card body width in columns
-
-# Raw JSON output (agent-friendly)
-sonar feed --json
+# Trigger full refresh pipeline
+sonar refresh
+
+# Monitor account + queues
+sonar status
+sonar status --watch
+sonar status --json
+
+# Suggestion actions
+sonar archive --id <suggestion_id>
+sonar later --id <suggestion_id>
+sonar skip --id <suggestion_id>
 \`\`\`
 
----
-
-## Suggestions (inbox)
+## Config and local data
 
 \`\`\`bash
-# List suggestions (default: inbox, limit 20)
-sonar inbox
-
-# Filter by status
-sonar inbox --status inbox
-sonar inbox --status later
-sonar inbox --status replied
-sonar inbox --status archived
-
-# Change limit
-sonar inbox --limit 50
-
-# Update a suggestion's status (positional id replaced with --id flag)
-sonar inbox read --id <id>
-sonar inbox skip --id <id>
-sonar inbox later --id <id>
-sonar inbox archive --id <id>
-
-# Raw JSON output
-sonar inbox --json
-\`\`\`
-
----
-
-## Ingest
-
-Trigger background jobs to ingest data.
-
-\`\`\`bash
-# Trigger specific jobs
-sonar ingest tweets        # Ingest recent tweets from social graph
-sonar ingest bookmarks     # Ingest X bookmarks (requires OAuth token)
-sonar interests match      # Match interests against ingested tweets (default: last 24h)
-
-# Match tweet window (capped by plan: free=3d, pro=7d, enterprise=14d)
-sonar interests match --days 1   # default
-sonar interests match --days 3   # broader window (free plan max)
-sonar interests match --days 7   # pro plan max
-
-# Show current job queue counts (one-shot)
-sonar monitor
-
-# Live polling view of job queues
-sonar monitor --watch
-\`\`\`
-
----
-
-## Local Data
-
-Sync feed, suggestions, and interests to a local SQLite DB (\`~/.sonar/data.db\`) for offline querying.
-
-\`\`\`bash
-# Full download — wipes and repopulates ~/.sonar/data.db
+# Show and setup config
+sonar config
+sonar config setup key=<API_KEY>
+sonar config env
+sonar config set vendor openai
+sonar config set vendor anthropic
+sonar config set feed-render card
+sonar config set feed-width 100
+
+# Local sqlite data
 sonar config data download
-
-# Incremental sync — upserts records newer than last sync
 sonar config data sync
-
-# Open an interactive sqlite3 REPL
+sonar config data path
 sonar config data sql
+sonar config data backup [--out <path>]
+sonar config data restore --from <backup_path> [--to <path>]
+sonar config data verify [--path <db_path>]
 
-# Print path to the local DB file
-sonar config data path
+# Export this skill file
+sonar config skill --install
 \`\`\`
 
-### Schema
-
-\`\`\`sql
--- Core tweet content (shared by feed and suggestions)
-tweets (
-  id TEXT PRIMARY KEY,       -- Sonar tweet UUID
-  xid TEXT,                  -- Twitter/X tweet ID
-  text TEXT,
-  created_at TEXT,
-  like_count INTEGER,
-  retweet_count INTEGER,
-  reply_count INTEGER,
-  author_username TEXT,
-  author_display_name TEXT,
-  author_followers_count INTEGER,
-  author_following_count INTEGER
-)
+## Other commands
 
--- Feed items (scored, keyword-matched tweets)
-feed_items (
-  tweet_id TEXT PRIMARY KEY, -- FK → tweets.id
-  score REAL,
-  matched_keywords TEXT,     -- JSON array of strings
-  synced_at TEXT
-)
-
--- Inbox suggestions
-suggestions (
-  suggestion_id TEXT PRIMARY KEY,
-  tweet_id TEXT,             -- FK → tweets.id
-  score REAL,
-  status TEXT,               -- INBOX | READ | SKIPPED | LATER | ARCHIVED
-  relevance TEXT,
-  projects_matched TEXT,     -- JSON (count of matched interests)
-  metadata TEXT,             -- JSON
-  synced_at TEXT
-)
-
--- Interests (topics/keywords that drive matching)
-interests (
-  id TEXT PRIMARY KEY,       -- nanoId
-  name TEXT,
-  description TEXT,
-  keywords TEXT,             -- JSON array
-  topics TEXT,               -- JSON array
-  created_at TEXT,
-  updated_at TEXT,
-  synced_at TEXT
-)
+\`\`\`bash
+# Queue bookmark sync
+sonar sync bookmarks
 
--- Internal sync state
-sync_state (
-  key TEXT PRIMARY KEY,      -- e.g. "last_synced_at"
-  value TEXT
-)
+# Delete local config + local DB (requires explicit confirmation)
+sonar config nuke --confirm
 \`\`\`
 
----
-
-## Environment Variables
+## Environment variables
 
 | Variable | Purpose |
 |---|---|
-| \`SONAR_API_KEY\` | API key for authentication (overrides config file) |
-| \`SONAR_API_URL\` | Backend URL (default: \`http://localhost:8000/graphql\`) |
-| \`SONAR_AI_VENDOR\` | AI vendor for \`--from-prompt\` (overrides config file) |
+| \`SONAR_API_KEY\` | API key for auth (overrides config file token) |
+| \`SONAR_API_URL\` | Backend URL (defaults to production GraphQL endpoint) |
+| \`SONAR_AI_VENDOR\` | Vendor override for AI-assisted operations (\`openai\` or \`anthropic\`) |
+| \`SONAR_FEED_RENDER\` | Default feed renderer override |
+| \`SONAR_FEED_WIDTH\` | Default card width override |
 | \`OPENAI_API_KEY\` | Required when vendor is \`openai\` |
 | \`ANTHROPIC_API_KEY\` | Required when vendor is \`anthropic\` |
-
----
-
-## Config file
-
-Stored at \`~/.sonar/config.json\`:
-
-\`\`\`json
-{
-  "token": "snr_...",
-  "apiUrl": "https://api.sonar.sh/graphql",
-  "vendor": "openai"
-}
-\`\`\`
 `;
 const DEFAULT_INSTALL_PATH = join(homedir(), '.claude', 'skills', 'sonar', 'SKILL.md');
 export function writeSkillTo(dest, install) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@1a35e1/sonar-cli",
-  "version": "0.2.0",
-  "description": "X/Twitter social graph CLI for signal filtering and curation",
+  "version": "0.3.4",
+  "description": "X social graph CLI for signal filtering and curation",
   "type": "module",
   "bin": {
     "sonar": "dist/cli.js"
@@ -13,6 +13,10 @@
   "engines": {
     "node": ">=20"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/1a35e1/sonar-cli"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -44,6 +48,12 @@
     "types": "graphql-codegen --config codegen.ts",
     "sonar": "tsx src/cli.ts",
     "build": "tsc",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "drift:schema:check": "node scripts/check-schema-drift.mjs",
+    "drift:surface:update": "node scripts/update-command-surface-snapshot.mjs",
+    "drift:surface:check": "node scripts/check-command-surface-snapshot.mjs",
+    "drift:docs:check": "node scripts/check-doc-command-parity.mjs",
+    "drift:data:check": "node scripts/check-data-compat.mjs",
+    "drift:check": "pnpm drift:surface:check && pnpm drift:docs:check && pnpm drift:data:check && pnpm drift:schema:check"
   }
 }

package/dist/commands/account.js

@@ -1,75 +0,0 @@
-import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
-import { useEffect, useState } from 'react';
-import zod from 'zod';
-import { Box, Text } from 'ink';
-import { formatDistanceToNow } from 'date-fns';
-import { gql } from '../lib/client.js';
-import { Spinner } from '../components/Spinner.js';
-import { AccountCard } from '../components/AccountCard.js';
-export const options = zod.object({
-    json: zod.boolean().default(false).describe('Raw JSON output'),
-    debug: zod.boolean().default(false).describe('Debug mode'),
-});
-const QUERY = `
-  query Status {
-    me {
-      accountId
-      email
-      xHandle
-      xid
-      isPayingCustomer
-      indexingAccounts
-      indexedTweets
-      pendingEmbeddings
-      twitterIndexedAt
-      refreshedSuggestionsAt
-    }
-    suggestionCounts {
-      inbox
-      later
-      replied
-      read
-      skipped
-      archived
-      total
-    }
-    usage {
-      plan
-      interests { used limit atLimit }
-      apiKeys { used limit atLimit }
-      bookmarksEnabled
-      socialGraphDegrees
-      socialGraphMaxUsers
-      suggestionRefreshes { used limit atLimit resetsAt }
-    }
-  }
-`;
-export default function Account({ options: flags }) {
-    const [data, setData] = useState(null);
-    const [error, setError] = useState(null);
-    useEffect(() => {
-        async function run() {
-            try {
-                const result = await gql(QUERY, {}, { debug: flags.debug });
-                if (flags.json) {
-                    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
-                    process.exit(0);
-                }
-                setData(result);
-            }
-            catch (err) {
-                if (flags.debug) {
-                    console.error(JSON.stringify(err, null, 2));
-                }
-                setError(err instanceof Error ? err.message : String(err));
-            }
-        }
-        run();
-    }, []);
-    if (error)
-        return _jsxs(Text, { color: "red", children: ["Error: ", error] });
-    if (!data)
-        return _jsx(Spinner, { label: "Fetching account..." });
-    const { me, suggestionCounts, usage } = data;
-    return (_jsxs(Box, { flexDirection: "column", gap: 1, children: [me ? _jsx(AccountCard, { me: me }) : (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, color: "cyan", children: "Account" }), _jsx(Text, { dimColor: true, children: "Not authenticated" })] })), usage && (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, color: "cyan", children: "Plan" }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "plan: " }), _jsx(Text, { color: usage.plan === 'free' ? 'yellow' : 'green', children: usage.plan })] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "interests: " }), _jsxs(Text, { color: usage.interests.atLimit ? 'red' : undefined, children: [usage.interests.used, usage.interests.limit !== null ? `/${usage.interests.limit}` : ''] })] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "api keys: " }), _jsxs(Text, { color: usage.apiKeys.atLimit ? 'red' : undefined, children: [usage.apiKeys.used, usage.apiKeys.limit !== null ? `/${usage.apiKeys.limit}` : ''] })] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "bookmarks: " }), usage.bookmarksEnabled ? _jsx(Text, { color: "green", children: "enabled" }) : _jsx(Text, { dimColor: true, children: "upgrade to unlock" })] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "social graph: " }), usage.socialGraphDegrees, " degree", usage.socialGraphDegrees !== 1 ? 's' : '', usage.socialGraphMaxUsers !== null ? `, up to ${usage.socialGraphMaxUsers.toLocaleString()} users` : ', unlimited'] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "suggestion refreshes: " }), usage.suggestionRefreshes.limit !== null ? (_jsxs(_Fragment, { children: [_jsxs(Text, { color: usage.suggestionRefreshes.atLimit ? 'red' : undefined, children: [usage.suggestionRefreshes.used, "/", usage.suggestionRefreshes.limit] }), usage.suggestionRefreshes.resetsAt && (_jsxs(Text, { dimColor: true, children: [' ', "(resets ", formatDistanceToNow(new Date(usage.suggestionRefreshes.resetsAt), { addSuffix: true }), ")"] }))] })) : (_jsx(Text, { color: "green", children: "unlimited" }))] })] })), _jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { bold: true, color: "cyan", children: "Suggestions" }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "inbox: " }), _jsx(Text, { color: suggestionCounts.inbox > 0 ? 'green' : undefined, children: suggestionCounts.inbox })] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "later: " }), suggestionCounts.later] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "replied: " }), suggestionCounts.replied] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "archived: " }), suggestionCounts.archived] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "total: " }), suggestionCounts.total] })] })] }));
-}