surf-skill 2.1.0 → 4.0.0

package/bin/surf.mjs

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+// `surf` — bundle wrapper for surf-search-skill + surf-plan-skill.
+//
+// Running `surf` with no args launches an interactive setup that:
+//   1. Verifies both skills are installed (symlinks present)
+//   2. Lists currently-configured keys per provider
+//   3. Offers an interactive menu: add / list / remove / doctor / quit
+//   4. EVERY key added is validated LIVE against the provider's API
+//      before being saved (1-credit cost, ~1-3s per validation)
+//
+// This is the friendliest entry point. `surf-search-skill` and `surf-plan-skill`
+// remain available for power users and scripts.
+
+import readline from 'node:readline/promises';
+import { stdin, stdout, stderr } from 'node:process';
+import { existsSync, promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { loadState, saveStateAtomic, KEYS_FILE, PROVIDERS } from '../src/lib/state.mjs';
+import { validateKey, formatValidation } from '../src/validators/index.mjs';
+import { HARNESS_DIRS } from '../src/lib/harness-install.mjs';
+
+const VERSION = '4.0.0';
+
+const HELP = `surf — multi-skill setup & validation
+
+Bundles surf-search-skill (multi-provider web search) and surf-plan-skill
+(research-driven execution planning) into one command.
+
+Commands:
+  (no args)              Interactive setup wizard (add keys with live validation)
+  add                    Add a key (you'll be asked for provider + key)
+  list                   List configured keys (masked) + last-known state
+  validate [provider]    Re-validate all keys (or just one provider's)
+  remove <provider> <i>  Remove key #i from provider
+  doctor                 Diagnostics: skills installed? keys valid? harness symlinks?
+  --help, -h             Show this help
+  --version, -v          Show version
+
+Power-user CLIs (also installed):
+  surf-search-skill ...         The search engine (search/extract/crawl/map/research)
+  surf-plan-skill ...    The planning skill (list/show/new/doctor)
+
+Keys live in:        ${KEYS_FILE} (chmod 600)
+Plans live in:       ~/.claude/plans/<slug>-<timestamp>.md (or ./plans/)
+SKILL.md (search):   ~/.agents/skills/surf-search-skill/SKILL.md
+SKILL.md (planning): ~/.agents/skills/surf-plan-skill/SKILL.md
+`;
+
+function out(s = '') {
+  stdout.write(s + (s.endsWith('\n') ? '' : '\n'));
+}
+function err(s) {
+  stderr.write(s + (s.endsWith('\n') ? '' : '\n'));
+}
+function mask(key) {
+  if (!key || key.length < 8) return key;
+  return key.slice(0, 5) + '…' + key.slice(-4);
+}
+function fmtBytes(n) {
+  if (n < 1024) return `${n}B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}KB`;
+  return `${(n / 1024 / 1024).toFixed(1)}MB`;
+}
+
+async function detectSkills() {
+  const home = os.homedir();
+  const skillsToCheck = ['surf-search-skill', 'surf-plan-skill'];
+  const found = {};
+  for (const skill of skillsToCheck) {
+    found[skill] = { dirs: [] };
+    for (const dir of HARNESS_DIRS) {
+      const link = path.join(dir, skill);
+      if (existsSync(link)) {
+        try {
+          const stat = await fs.lstat(link);
+          found[skill].dirs.push({
+            path: link,
+            isSymlink: stat.isSymbolicLink(),
+            isDir: stat.isDirectory(),
+          });
+        } catch {}
+      }
+    }
+  }
+  return found;
+}
+
+async function cmdList() {
+  const state = await loadState();
+  out(`**Keys** (config: \`${KEYS_FILE}\`, chmod 600)`);
+  out(`last_ok_provider: \`${state.last_ok_provider || 'none yet'}\``);
+  out('');
+  for (const p of PROVIDERS) {
+    const ps = state[p];
+    out(`## ${p} (${ps.keys.length} key${ps.keys.length === 1 ? '' : 's'})`);
+    if (!ps.keys.length) {
+      out(`  _no keys — add with \`surf add\`_`);
+      continue;
+    }
+    for (let i = 0; i < ps.keys.length; i++) {
+      const isCur = i === ps.current ? ' (current)' : '';
+      const burned = ps.burned.find(b => b.index === i);
+      const burn = burned ? ` BURNED:${burned.reason} at ${burned.at.slice(0, 16)}` : '';
+      out(`  [${i}] ${mask(ps.keys[i])}${isCur}${burn}`);
+    }
+  }
+}
+
+async function cmdValidate(providerFilter) {
+  const state = await loadState();
+  let any = false;
+  for (const p of PROVIDERS) {
+    if (providerFilter && p !== providerFilter) continue;
+    const ps = state[p];
+    if (!ps.keys.length) continue;
+    any = true;
+    out(`\n## ${p}`);
+    for (let i = 0; i < ps.keys.length; i++) {
+      stdout.write(`  [${i}] ${mask(ps.keys[i])} → `);
+      const r = await validateKey(p, ps.keys[i]);
+      out(formatValidation(r));
+    }
+  }
+  if (!any) out(providerFilter ? `No keys for ${providerFilter}.` : 'No keys configured. Add one with `surf add`.');
+}
+
+async function cmdRemove(args) {
+  const [provider, indexStr] = args;
+  if (!provider || indexStr == null) {
+    err('Usage: surf remove <provider> <index>');
+    process.exit(1);
+  }
+  if (!PROVIDERS.includes(provider)) {
+    err(`Unknown provider: ${provider}. Use: ${PROVIDERS.join('|')}`);
+    process.exit(1);
+  }
+  const idx = Number(indexStr);
+  const state = await loadState();
+  const ps = state[provider];
+  if (!Number.isInteger(idx) || idx < 0 || idx >= ps.keys.length) {
+    err(`Invalid index ${indexStr}; ${provider} has ${ps.keys.length} key${ps.keys.length === 1 ? '' : 's'} (0-${ps.keys.length - 1}).`);
+    process.exit(1);
+  }
+  const removed = ps.keys.splice(idx, 1)[0];
+  ps.burned = ps.burned.filter(b => b.index !== idx).map(b => ({ ...b, index: b.index > idx ? b.index - 1 : b.index }));
+  if (ps.current >= ps.keys.length) ps.current = 0;
+  await saveStateAtomic(state);
+  out(`✓ removed ${provider} key #${idx} (${mask(removed)})`);
+}
+
+async function cmdAdd(rl) {
+  rl = rl || readline.createInterface({ input: stdin, output: stdout });
+  let closeRl = !arguments.length;
+  try {
+    out('');
+    let provider = '';
+    while (!PROVIDERS.includes(provider)) {
+      provider = (await rl.question(`Provider [${PROVIDERS.join('/')}]: `)).trim().toLowerCase();
+      if (!PROVIDERS.includes(provider)) out(`  (unknown: ${provider}. Try: ${PROVIDERS.join(', ')})`);
+    }
+    const key = (await rl.question(`${provider} key: `)).trim();
+    if (!key) { out('(empty — cancelled)'); return; }
+
+    const state = await loadState();
+    const ps = state[provider];
+    if (ps.keys.includes(key)) {
+      out(`  ℹ already configured at index ${ps.keys.indexOf(key)} — skipping`);
+      return;
+    }
+
+    out(`  validating against ${provider} API (1 credit, ~2s)…`);
+    const r = await validateKey(provider, key);
+    out(`  ${formatValidation(r)}`);
+    if (!r.valid) {
+      out('  → key NOT saved. Try `surf add` again with a different key.');
+      process.exitCode = 1;
+      return;
+    }
+
+    ps.keys.push(key);
+    if (ps.keys.length === 1) ps.current = 0;
+    await saveStateAtomic(state);
+    out(`✓ saved as ${provider} key #${ps.keys.length - 1}. Total ${provider}: ${ps.keys.length}.`);
+  } finally {
+    if (closeRl) rl.close();
+  }
+}
+
+async function cmdDoctor() {
+  out('## Skills');
+  const found = await detectSkills();
+  for (const [skill, info] of Object.entries(found)) {
+    if (!info.dirs.length) {
+      out(`  ✗ ${skill}: NOT found in any harness skill dir`);
+      out(`    → reinstall: npm i -g surf-skill@latest`);
+      process.exitCode = 1;
+    } else {
+      const sample = info.dirs[0];
+      out(`  ✓ ${skill}: ${info.dirs.length} harness${info.dirs.length === 1 ? '' : 'es'}`);
+      for (const d of info.dirs) out(`      ${d.path}${d.isSymlink ? ' (symlink)' : ''}`);
+    }
+  }
+
+  out('\n## Keys');
+  const state = await loadState();
+  const totals = PROVIDERS.map(p => ({ p, n: state[p].keys.length, burned: state[p].burned.length }));
+  for (const t of totals) {
+    const status = t.n === 0 ? '⚠ no keys' : t.burned ? `${t.n} key(s), ${t.burned} burned` : `${t.n} key(s) ✓`;
+    out(`  ${t.p.padEnd(10)} ${status}`);
+  }
+  if (totals.every(t => t.n === 0)) {
+    out('\n  → Run `surf` to add your first key.');
+    process.exitCode = 2;
+  }
+
+  out('\n## Plans');
+  const plansDir = path.join(os.homedir(), '.claude', 'plans');
+  if (existsSync(plansDir)) {
+    const files = (await fs.readdir(plansDir)).filter(f => f.endsWith('.md'));
+    out(`  ${files.length} plan file${files.length === 1 ? '' : 's'} in ${plansDir}`);
+  } else {
+    out(`  ${plansDir} not created yet`);
+  }
+}
+
+async function interactiveMenu() {
+  out('');
+  out('┌─ surf — multi-skill setup & validation ─────────────────');
+  out(`│ Skills detected:`);
+  const found = await detectSkills();
+  for (const [skill, info] of Object.entries(found)) {
+    const status = info.dirs.length ? `✓ ${info.dirs.length} harness${info.dirs.length === 1 ? '' : 'es'}` : '✗ NOT INSTALLED';
+    out(`│   ${skill.padEnd(20)} ${status}`);
+  }
+
+  const state = await loadState();
+  const counts = PROVIDERS.map(p => `${p} ${state[p].keys.length}`).join(', ');
+  out(`│ Keys: ${counts}`);
+  out(`│ Config: ${KEYS_FILE}`);
+  out('└──────────────────────────────────────────────────────────');
+  out('');
+
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    while (true) {
+      out('What do you want to do?');
+      out('  [1] Add a key (with live validation)');
+      out('  [2] List + revalidate all keys');
+      out('  [3] Remove a key');
+      out('  [4] Diagnostics (skills + symlinks + dirs)');
+      out('  [q] Quit');
+      const choice = (await rl.question('> ')).trim().toLowerCase();
+      out('');
+      if (choice === '1' || choice === 'add') {
+        await cmdAdd(rl);
+      } else if (choice === '2' || choice === 'list') {
+        await cmdValidate();
+      } else if (choice === '3' || choice === 'remove') {
+        const provider = (await rl.question(`Provider [${PROVIDERS.join('/')}]: `)).trim();
+        const idx = (await rl.question('Index: ')).trim();
+        await cmdRemove([provider, idx]).catch(e => err(`✗ ${e.message}`));
+      } else if (choice === '4' || choice === 'doctor') {
+        await cmdDoctor();
+      } else if (choice === 'q' || choice === 'quit' || choice === 'exit' || !choice) {
+        out('bye 🌊');
+        return;
+      } else {
+        out(`(unknown choice: ${choice})`);
+      }
+      out('');
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+const [, , cmd, ...rest] = process.argv;
+
+try {
+  if (!cmd) {
+    if (!stdin.isTTY) {
+      err(`surf requires a TTY for interactive setup. Use a subcommand:
+  surf add | list | validate | remove <provider> <i> | doctor`);
+      process.exit(1);
+    }
+    await interactiveMenu();
+  } else if (cmd === '--help' || cmd === '-h') {
+    out(HELP);
+  } else if (cmd === '--version' || cmd === '-v') {
+    out(VERSION);
+  } else if (cmd === 'add') {
+    if (!stdin.isTTY) {
+      err('`surf add` is interactive and requires a TTY. Use `surf-search-skill keys add --provider X <key>` for scripts.');
+      process.exit(1);
+    }
+    await cmdAdd();
+  } else if (cmd === 'list') {
+    await cmdList();
+  } else if (cmd === 'validate') {
+    await cmdValidate(rest[0]);
+  } else if (cmd === 'remove') {
+    await cmdRemove(rest);
+  } else if (cmd === 'doctor') {
+    await cmdDoctor();
+  } else {
+    err(`Unknown command: ${cmd}. Try 'surf --help'.`);
+    process.exit(1);
+  }
+} catch (e) {
+  err(`❌ Error: ${e.message || String(e)}`);
+  process.exit(1);
+}

package/package.json

@@ -1,29 +1,35 @@
 {
   "name": "surf-skill",
-  "version": "2.1.0",
-  "description": "Multi-provider web skill (Tavily + Parallel AI + Brave Search) for AI coding agents — CLI + Node library + Anthropic Agent Skill. Auto-fallback, multi-key rotation, --mode tiers, per-project timeout config.",
+  "version": "4.0.0",
+  "description": "Multi-skill bundle for AI coding agents: surf-search-skill (multi-provider web search via Tavily + Parallel + Brave) + surf-plan-skill (research-driven execution planning). Includes `surf` interactive setup with live key validation, automatic provider fallback, multi-key rotation, --mode tiers, per-project timeout config, and a Node library.",
   "type": "module",
   "main": "./src/index.mjs",
   "exports": {
     ".": "./src/index.mjs",
+    "./plan": "./src/plan/plan-file.mjs",
+    "./validators": "./src/validators/index.mjs",
     "./package.json": "./package.json"
   },
   "bin": {
-    "surf-skill": "./bin/surf-skill.mjs"
+    "surf": "./bin/surf.mjs",
+    "surf-skill": "./bin/surf-skill.mjs",
+    "surf-plan-skill": "./bin/surf-plan-skill.mjs"
   },
   "files": [
     "bin/",
     "src/",
+    "skills/",
     "references/",
     "SKILL.md",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "logo.png"
   ],
   "scripts": {
     "postinstall": "node ./src/install/postinstall.mjs || true",
     "preuninstall": "node ./src/install/preuninstall.mjs || true",
-    "test:syntax": "node --check bin/surf-skill.mjs && for f in src/index.mjs src/env.mjs src/install/*.mjs src/lib/*.mjs src/lib/providers/*.mjs src/lib/api/*.mjs; do node --check \"$f\" || exit 1; done && echo syntax-ok"
+    "test:syntax": "node --check bin/surf.mjs && node --check bin/surf-search-skill.mjs && node --check bin/surf-plan-skill.mjs && for f in src/index.mjs src/env.mjs src/install/*.mjs src/lib/*.mjs src/lib/providers/*.mjs src/lib/api/*.mjs src/plan/*.mjs src/validators/*.mjs; do node --check \"$f\" || exit 1; done && echo syntax-ok"
   },
   "engines": {
     "node": ">=18"
@@ -35,6 +41,10 @@
     "brave-search",
     "web-search",
     "connector",
+    "planning",
+    "spec-driven",
+    "research-driven",
+    "execution-plan",
     "claude-code",
     "copilot-cli",
     "pi-coding-agent",

package/references/parallel-api.md

@@ -102,7 +102,7 @@ Returns **HTTP 202** with `{ run_id, status: "queued" \| "running", is_active, p
 }
 ```
 
-Processor mapping used by `surf-skill research`:
+Processor mapping used by `surf-search-skill research`:
 
 | `--model` | Parallel processor |
 |---|---|

package/references/plan-workflow.md

@@ -0,0 +1,137 @@
+# surf-plan-skill workflow — deeper docs
+
+This file expands on the 6-phase workflow defined in `SKILL.md`. It's
+for humans reviewing the methodology, not for the agent (which only
+reads SKILL.md).
+
+## The 6 phases
+
+### Phase 0 — preflight
+
+Why: if `surf-search-skill` is missing, web research is impossible, and the
+plan would just be the agent's training-time hallucinations dressed up
+in markdown. Halt is the right move.
+
+How: `surf-search-skill --version` exits 0 → continue. Exits non-zero or
+command not found → halt with install instructions.
+
+### Phase 1 — project discovery
+
+Why: plans that skip this duplicate existing code. ~5 minutes of
+reading saves hours of integration pain.
+
+How:
+1. `CLAUDE.md`, `AGENTS.md`, `README.md` — house style + constraints.
+2. Package manifest — language, framework, deps.
+3. Glob the source tree (2 levels deep).
+4. Identify 2–3 existing patterns / utilities the new feature should
+   reuse.
+5. Note relevant configs (eslint, tsconfig, docker, ci).
+
+Output: agent's mental model of "what already exists" + file paths.
+
+### Phase 2 — baseline web research
+
+Why: ground the plan in 2026 best practices, not 2024 training data.
+
+How: ONE batched `surf-search-skill search` with 3 queries. Distill:
+- 3 dominant approaches
+- 2–3 common mistakes
+- 1–2 security/performance gotchas
+
+Cost: ~6 credits (Tavily) + ~10 s. Acceptable for any non-trivial plan.
+
+### Phase 3 — open the conversation
+
+Why: the user needs to see you've done your homework before they
+answer questions.
+
+How: ≤8 lines. What you read + what the web says + how many questions
+you have.
+
+### Phase 4 — clarifying questions
+
+Why: even after research, certain decisions require the user's
+preference (e.g., "Redis or Postgres for the queue?", "do we need
+multi-tenancy from day one?").
+
+How:
+- For each question: targeted `surf-search-skill search --max 2` first.
+- AskUserQuestion with options informed by the search.
+- Max 5 total.
+
+Anti-pattern: asking the user to choose between options that the agent
+just made up. Search first; pick options from real approaches.
+
+### Phase 5 — synthesis research
+
+Why: verify the user's choices against the very-latest state of the
+art. Catches "you chose X but X v2 dropped support for Y last month".
+
+How: ONE batched search with the user's chosen approach. ~6 credits.
+If contradictions appear, flag them BEFORE writing the plan.
+
+### Phase 6 — write the plan
+
+Why: a plan file is a contract. It's reviewable, executable, and
+auditable. Chat history is none of those.
+
+How: Markdown with the structure from SKILL.md. Required sections:
+Context, Decisions, Files, Steps, Verification, References.
+
+Citations use Markdown footnote syntax `[^N]: [Title](URL)` — renders
+in GitHub, GitLab, Bitbucket, Cursor, Plannotator, and most other
+viewers.
+
+## Cost discipline
+
+A typical plan uses:
+- 1 batch (Phase 2): 3 queries, ~6 credits, ~10 s
+- 3–5 targeted (Phase 4): 1 query each, ~5 credits, ~3 s each
+- 1 batch (Phase 5): 2–3 queries, ~5 credits, ~8 s
+
+Total: ~15–20 credits, ~30 s of network time. On Tavily free tier
+(1k credits/month), that's ~50 plans per month for free.
+
+## Anti-patterns explained
+
+**Verbose research summary section**
+A "Research Findings" section dumping every URL with snippet is noise
+— it inflates the plan, distracts the executor, and ages instantly.
+Synthesize: the plan has Decisions with footnotes; that's the
+research's role in the final document.
+
+**Aesthetic questions**
+"What color theme?" / "Should we name it FooBar or BarFoo?" — these
+aren't planning questions. Defer to the execution phase.
+
+**Single-source citations**
+If every decision footnotes the same URL, the research was shallow.
+Diversify: aim for 1 citation per major source category (vendor docs,
+community blog, security advisory, benchmark, etc.).
+
+**Plans without file paths**
+"Update the controller layer" is not a plan, it's a wish. Phase 1
+exists so the plan can say `src/controllers/user.ts:42`.
+
+**Surveys (>5 questions)**
+Beyond 5 questions, the user fatigues and starts answering "whatever".
+If you genuinely need more, the task is too big — slice it.
+
+## Plan file conventions
+
+- File name: `<slug>-<YYYYMMDD-HHMM>.md`. Slug is kebab-case, ≤50 chars.
+- Slug collision: append `-2`, `-3`, etc.
+- Title in `# Plan: ...` matches the slug.
+- Footnote order: in the order they're first cited.
+- URLs: full https links, no trackers or auth tokens.
+- Code references: `path/to/file.ext:LINE` format, parseable by most IDEs.
+
+## What surf-plan-skill is NOT
+
+- Not an execution engine. Once the plan is written, hand it to another
+  tool/agent/human.
+- Not a project manager. It's per-task, not multi-task.
+- Not a code generator. It writes a plan, not code.
+- Not a replacement for Plan Mode. Plan Mode is more interactive but
+  ephemeral and without web research. They complement.