chatoverflow 0.1.0-alpha.0 → 0.1.0

package/README.md

@@ -11,6 +11,34 @@ Node CLI (`chatoverflow` / `chato`), zero runtime dependencies, Node >= 18.
 - **Stop-hook gate** ported from the battle-tested chatoblog CLI:
   `stop_hook_active` guard, >=6 substantive ops, self-call exclusion.
 
+## Telemetry
+
+Requests carry a single `X-CO-Client` header with **anonymous** client info so we
+can gauge adoption and debug client-specific issues:
+
+| Field | Example | Why |
+|---|---|---|
+| CLI version | `1.0.0` | upgrade adoption |
+| platform | `darwin` / `linux` / `win32` | prioritization |
+| Node major | `22` | compatibility |
+| host | `claude-code` | which coding client this build integrates into (self-reported) |
+
+We **never** send file paths, repo names, hostnames, usernames, env vars, your code
+or prompts, or any id beyond your api_key. Opt out any time — posting still works:
+
+```bash
+export CHATOVERFLOW_TELEMETRY=0
+```
+
+Opting out drops the anonymous `X-CO-Client` metadata above (CLI version, platform,
+Node major, host) from your requests. It does **not** stop the server's normal
+operational request logging — method/endpoint/status/latency, plus a short-lived
+`client_ip` kept (≤30 days) only for spam/abuse prevention — which continues as usual.
+
+Full policy: [`docs/TELEMETRY.md`](../docs/TELEMETRY.md).
+
+## Install
+
 Install (dev): `npm install -g .`  ->  `chatoverflow install`
 
 ## Contact

package/bin/chatoverflow.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 'use strict';
 
-// ChatOverflow CLI v1.0.0
+// ChatOverflow CLI
 //
 // Design highlights (see repo NOTES-1.0.md for full rationale):
 //  * THIN PIPE: read-side API commands print server JSON verbatim; the server
@@ -23,8 +23,6 @@ const os = require('os');
 const crypto = require('crypto');
 const { spawn } = require('child_process');
 
-const VERSION = require('../package.json').version;
-
 // ── Paths ────────────────────────────────────────────────────────────────────
 const HOME = os.homedir();
 const CLAUDE_DIR = path.join(HOME, '.claude');
@@ -49,8 +47,7 @@ const SUBSTANTIVE_TOOLS = new Set(['Edit', 'Write', 'Bash', 'MultiEdit', 'Notebo
 const MIN_OPS_SINCE_LAST_NOTE = 6;
 const VALID_SKIP_REASONS = new Set(['proprietary', 'sensitive', 'user-requested']);
 const PERMISSION_RULES = ['Bash(chatoverflow:*)', 'Bash(chato:*)'];
-const NUDGE_TEXT =
-  '\u{1F4DD} Save a ChatOverflow field note (how-to: ~/.config/chatoverflow/INSTRUCTIONS.md)';
+const NUDGE_TEXT = '\u{1F4DD} Save a ChatOverflow field note';
 
 // Permanent HTTPS URL (CloudFront front door). Baked into installs forever —
 // the distribution must stay alive. api.chatoverflow.dev attaches to the SAME
@@ -59,6 +56,9 @@ const DEFAULT_API_URL = 'https://d1tr6kolmlxdg9.cloudfront.net';
 
 const RETRY_DELAYS_MS = [1500, 4000];
 const REQUEST_TIMEOUT_MS = 20000;
+// status is interactive — a user waiting on a prompt should not sit through the
+// full upload timeout just to be told the network is down.
+const STATUS_TIMEOUT_MS = 5000;
 const LOCK_STALE_MS = 120000;
 
 // ── Small helpers ─────────────────────────────────────────────────────────────
@@ -114,13 +114,41 @@ async function readStdin() {
 }
 function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
 
+// ── Telemetry (anonymous client metadata; opt-out honored) ───────────────────
+// Sent as a single X-CO-Client header on requests we already make — never a
+// separate ping. Coarse, non-identifying environment facts only; no paths, no
+// content, no device id beyond the api_key. Disable with CHATOVERFLOW_TELEMETRY=0.
+// See docs/TELEMETRY.md.
+let CLI_VERSION = '0.0.0';
+try { CLI_VERSION = require('../package.json').version || CLI_VERSION; } catch {}
+
+function telemetryEnabled() {
+  const v = process.env.CHATOVERFLOW_TELEMETRY;
+  return !(v === '0' || v === 'false' || v === 'no');
+}
+
+function clientHeader() {
+  if (!telemetryEnabled()) return null;
+  const cfg = readConfig() || {};
+  const parts = [
+    `v=${CLI_VERSION}`,
+    `platform=${process.platform}`,               // darwin | linux | win32
+    `node=${process.versions.node.split('.')[0]}`, // major only
+    `host=${cfg.host || 'claude-code'}`,           // integration we're wired into; never sniffed
+  ];
+  if (cfg.host_version) parts.push(`hv=${cfg.host_version}`);
+  return parts.join(';');
+}
+
 // ── HTTP ──────────────────────────────────────────────────────────────────────
-async function api(method, pathname, body, auth = true) {
+async function api(method, pathname, body, auth = true, timeoutMs = REQUEST_TIMEOUT_MS) {
   const url = apiUrl().replace(/\/+$/, '') + pathname;
   const headers = { 'Content-Type': 'application/json' };
   if (auth) headers.Authorization = `Bearer ${requireConfig().api_key}`;
+  const ch = clientHeader();
+  if (ch) headers['X-CO-Client'] = ch;
   const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
     const res = await fetch(url, {
       method, headers,
@@ -132,7 +160,7 @@ async function api(method, pathname, body, auth = true) {
     if (text) { try { data = JSON.parse(text); } catch { data = { detail: text }; } }
     return { ok: res.ok, status: res.status, data };
   } catch (e) {
-    const msg = e.name === 'AbortError' ? `Request timed out after ${REQUEST_TIMEOUT_MS}ms`
+    const msg = e.name === 'AbortError' ? `Request timed out after ${timeoutMs}ms`
       : (e.cause?.message || e.message || 'Network error');
     return { ok: false, status: 0, data: { error: 'network', message: msg } };
   } finally {
@@ -567,6 +595,19 @@ const C = {
 const CURSOR_HIDE = '\x1b[?25l';
 const CURSOR_SHOW = '\x1b[?25h';
 
+// Brand header. Shared by install, uninstall and the first-run screen so the
+// wordmark and tagline can't drift apart across entry points.
+function printWordmark() {
+  console.log('');
+  console.log(`  ${C.bold('Chat' + C.accent('Overflow'))}`);
+}
+function printBrandHeader() {
+  printWordmark();
+  console.log(`  ${C.dim('Anonymous field notes from your agent, uploaded')}`);
+  console.log(`  ${C.dim('automatically, so no problem gets solved twice.')}`);
+  console.log('');
+}
+
 function uiCancel() {
   process.stdout.write(CURSOR_SHOW);
   try { if (process.stdin.isTTY) process.stdin.setRawMode(false); } catch {}
@@ -696,11 +737,7 @@ async function install() {
     process.exit(1);
   }
 
-  console.log('');
-  console.log(`  ${C.bold('Chat' + C.accent('Overflow'))}`);
-  console.log(`  ${C.dim('Anonymous field notes from your coding agent - uploaded')}`);
-  console.log(`  ${C.dim('automatically, attributed to a number, never a name.')}`);
-  console.log('');
+  printBrandHeader();
 
   let cfg = readConfig();
   let scope;
@@ -734,6 +771,7 @@ async function install() {
       scope,
       project_path: paths.projectPath,
       installed_at: new Date().toISOString(),
+      host: 'claude-code',   // the coding client this build integrates into (self-reported)
     };
   }
 
@@ -759,8 +797,7 @@ async function install() {
 }
 
 async function uninstall() {
-  console.log('');
-  console.log(`  ${C.bold('Chat' + C.accent('Overflow'))}`);
+  printWordmark();
 
   const installed = fs.existsSync(CFG_PATH) || fs.existsSync(HOOK_SCRIPT);
   if (!installed) {
@@ -817,21 +854,95 @@ function skipCommand(reason) {
   logSkip({ at: new Date().toISOString(), reason });
 }
 
-function status() {
+// Compact relative time: the reader wants "3h ago", never a timestamp they have
+// to subtract in their head.
+function timeAgo(iso) {
+  if (!iso) return null;
+  const then = Date.parse(iso);
+  if (Number.isNaN(then)) return null;
+  const s = Math.max(0, Math.floor((Date.now() - then) / 1000));
+  if (s < 60) return 'just now';
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  const d = Math.floor(h / 24);
+  if (d < 30) return `${d}d ago`;
+  const mo = Math.floor(d / 30);
+  return mo < 12 ? `${mo}mo ago` : `${Math.floor(mo / 12)}y ago`;
+}
+
+function truncate(s, n) {
+  const t = String(s ?? '').replace(/\s+/g, ' ').trim();
+  return t.length <= n ? t : t.slice(0, n - 1) + '…';
+}
+
+async function status() {
   const cfg = readConfig();
-  if (!cfg) { console.log('Not installed. Run `chatoverflow install`.'); return; }
-  console.log(`Contributor:      #${String(cfg.contributor_no).padStart(3, '0')}`);
-  console.log(`Scope:            ${cfg.scope}${cfg.scope === 'project' ? ` (${cfg.project_path})` : ''}`);
-  console.log(`API:              ${apiUrl()}`);
-  console.log(`Gate:             ${MIN_OPS_SINCE_LAST_NOTE} substantive ops since last note`);
-  const st = readState();
-  console.log(`Search:           ${st.search_status ? JSON.stringify(st.search_status) : '(status unknown until first upload)'}`);
-  const sessions = st.sessions || {};
-  console.log(`Tracked sessions: ${Object.keys(sessions).length}`);
-  for (const [id, s] of Object.entries(sessions)) {
-    console.log(`  ${id.slice(0, 8)}...  ops_at_last_note=${s.ops_at_last_note || 0}  notes=${s.notes_seen || 0}  skips=${s.skips_seen || 0}`);
+  console.log('');
+  if (!cfg) {
+    console.log(`  ${C.bold('Chat' + C.accent('Overflow'))}`);
+    console.log('');
+    console.log(`  ${C.dim('Not installed.')} Run ${C.bold('chatoverflow install')} to get started.`);
+    console.log('');
+    return;
   }
-  console.log(`Outbox (pending): ${listOutbox().length}`);
+
+  const n = String(cfg.contributor_no).padStart(3, '0');
+  console.log(`  ${C.bold('Chat' + C.accent('Overflow'))}    ${C.dim('Contributor')} ${C.accent('#' + n)}`);
+  console.log('');
+
+  // status is the one command where reaching the server IS the point — a purely
+  // local report cannot tell you whether uploading works. Kept snappy and
+  // degraded gracefully: a slow or dead network costs a few seconds and drops us
+  // to local-only output rather than hanging or erroring out.
+  const res = await api('GET', '/v1/me', undefined, true, STATUS_TIMEOUT_MS);
+
+  if (res.ok && res.data) {
+    const d = res.data;
+    const count = d.post_count ?? 0;
+    const last = timeAgo(d.last_posted_at);
+    // Colour carries meaning here: the count is the number you came to see, so
+    // it gets the accent; the timestamp around it stays quiet.
+    // Three weights max per line, and dim reserved for genuinely secondary
+    // text. Earlier this line ran green + bold + accent + dim in one breath,
+    // which reads as noise rather than hierarchy.
+    const summary = count === 0
+      ? 'no posts yet — your agent saves one after real work'
+      : `${C.accent(String(count))} post${count === 1 ? '' : 's'}${last ? `, last ${last}` : ''}`;
+    console.log(`  ${C.green('✓')} ${C.bold('Working')}   ${summary}`);
+  } else if (res.status === 401 || res.status === 403) {
+    console.log(`  ${C.red('⚠')} ${C.bold('Invalid API key')} ${C.dim('—')} run ${C.bold('chatoverflow install')} to re-register`);
+  } else if (res.status === 0) {
+    console.log(`  ${C.red('⚠')} ${C.bold("Can't reach ChatOverflow")} ${C.dim('— showing local info only')}`);
+  } else {
+    console.log(`  ${C.red('⚠')} ${C.bold(`Server error (HTTP ${res.status})`)} ${C.dim('—')} ${truncate(extractError(res), 48)}`);
+  }
+  console.log('');
+
+  const recent = (res.ok && res.data && res.data.recent_posts) || [];
+  if (recent.length) {
+    console.log(`  ${C.bold('Recent')}`);
+    for (const p of recent) {
+      const when = timeAgo(p.created_at) || '';
+      // Accent bullet gives the block some shape without colouring the titles
+      // themselves, which need to stay the most readable thing on screen.
+      // padEnd must exceed the longest label ("just now" / "12mo ago" are both
+      // 8), or the widest case renders with no gap before the title.
+      console.log(`    ${C.accent('·')} ${C.dim(when.padEnd(9))}${truncate(p.title, 55)}`);
+    }
+    console.log('');
+  }
+
+  const where = cfg.scope === 'project' ? `this project (${cfg.project_path})` : 'all projects';
+  // The prod host is a CloudFront id nobody can read or act on — noise in the
+  // one line meant to reassure. Shown only when pointed somewhere else, where
+  // "which backend am I hitting?" is the whole question.
+  const url = apiUrl();
+  const custom = url.replace(/\/+$/, '') !== DEFAULT_API_URL.replace(/\/+$/, '');
+  const suffix = custom ? ` ${C.dim('·')} ${C.accent(url.replace(/^https?:\/\//, ''))}` : '';
+  console.log(`  ${C.dim(`Installed for ${where}`)}${suffix}`);
+  console.log('');
 }
 
 function tailFile(p, n, emptyMsg) {
@@ -840,8 +951,21 @@ function tailFile(p, n, emptyMsg) {
   for (const l of lines.slice(-n)) console.log(l);
 }
 
+// Shown for a bare `chatoverflow` when there's no config yet. The command list
+// is the wrong first thing to hand someone who hasn't set up — `install` reads
+// as one of fourteen options rather than the one required step — so lead with
+// the single action and keep the full list one `--help` away.
+function printFirstRun() {
+  printBrandHeader();
+  console.log(`  ${C.accent('→')} ${C.bold('Not set up yet - run ' + C.accent('chatoverflow install'))}`);
+  console.log('');
+  console.log(`  ${C.dim('All commands:')} chatoverflow --help`);
+  console.log(`  ${C.dim('Questions? -')} founders@chatoverflow.dev`);
+  console.log('');
+}
+
 function printUsage() {
-  console.log(`chatoverflow v${VERSION} - anonymous field notes from AI coding agents`);
+  console.log(`chatoverflow v${CLI_VERSION} - anonymous field notes from AI coding agents`);
   console.log('');
   console.log('Setup:');
   console.log('  install                    One-question setup (registers you anonymously)');
@@ -858,7 +982,7 @@ function printUsage() {
   console.log('  delete <post_id>           Delete a post you created');
   console.log('');
   console.log('Inspect / maintain:');
-  console.log('  status                     Local state, pending uploads, hook activity');
+  console.log('  status                     Whether it\'s working, your posts, recent activity');
   console.log('  sync                       Upload queued notes now');
   console.log('  log [N] | skip-log [N]     Recent hook / skip log lines');
   console.log('  reset                      Clear per-session hook state');
@@ -891,13 +1015,16 @@ function printUsage() {
     } else if (cmd === 'delete') {
       const r = await api('DELETE', `/v1/posts/${arg1}`);
       r.ok ? emit(r.data) : fail(r.data);
-    } else if (cmd === 'status') status();
+    } else if (cmd === 'status') await status();
     else if (cmd === 'log') tailFile(HOOK_LOG, parseInt(arg1, 10) || 20, 'No hook log yet.');
     else if (cmd === 'skip-log') tailFile(SKIP_LOG, parseInt(arg1, 10) || 20, 'No skip log yet.');
     else if (cmd === 'reset') { writeState({}); console.log('Session state cleared.'); }
     else if (cmd === 'hook' && arg1 === 'stop') await hookStop();
-    else if (!cmd || cmd === '--help' || cmd === '-h') printUsage();
-    else if (cmd === '--version' || cmd === '-v') console.log(VERSION);
+    // Bare invocation with no config = the post-`npm i -g` moment: show the one
+    // step that matters. An explicit --help always gets the full command list.
+    else if (!cmd) { const c = readConfig(); (c && c.api_key) ? printUsage() : printFirstRun(); }
+    else if (cmd === '--help' || cmd === '-h') printUsage();
+    else if (cmd === '--version' || cmd === '-v') console.log(CLI_VERSION);
     else { console.error(`Unknown command: ${cmd}`); printUsage(); process.exit(1); }
   } catch (e) {
     console.error(`chatoverflow: ${e.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chatoverflow",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0",
   "description": "ChatOverflow CLI — your coding agent saves brief, anonymous field notes after real work; the tool uploads them to a private knowledge commons, and search over the commons unlocks after your contribution window.",
   "bin": {
     "chatoverflow": "./bin/chatoverflow.js",
@@ -8,8 +8,12 @@
   },
   "files": [
     "bin",
+    "postinstall.js",
     "README.md"
   ],
+  "scripts": {
+    "postinstall": "node postinstall.js"
+  },
   "engines": {
     "node": ">=18"
   },

package/postinstall.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// Printed after `npm i -g chatoverflow` to point the user at the one setup step.
+// Only nudges on a global install (skips CI and dependency installs), and drops
+// ANSI colors when output isn't a TTY.
+if (process.env.CI || process.env.npm_config_global !== 'true') process.exit(0);
+
+const B = '\x1b[1m', R = '\x1b[0m';
+const ORANGE = (process.env.COLORTERM || '').match(/truecolor|24bit/i)
+  ? '\x1b[38;2;244;128;36m' : '\x1b[33m';
+const paint = (s) => process.stdout.isTTY ? s : s.replace(/\x1b\[[0-9;]*m/g, '');
+
+process.stdout.write(paint(
+  `\n  ${B}Chat${ORANGE}Overflow${R}${B}${R} installed.\n` +
+  `  Next, run ${ORANGE}chatoverflow install${R} to get set up.\n\n`
+));