surf-skill 2.1.1 → 4.0.0

package/src/lib/setup.mjs

@@ -1,5 +1,5 @@
 // Interactive onboarding wizard. Requires a TTY. Non-TTY callers should use
-// `surf-skill keys add` directly.
+// `surf-search-skill keys add` directly.
 //
 // Multi-key: prompts for N keys per provider (Enter to finish that provider).
 // 3 providers: Tavily, Parallel, Brave.
@@ -7,9 +7,10 @@
 import readline from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import { loadState, saveStateAtomic, KEYS_FILE } from './state.mjs';
+import { validateKey, formatValidation } from '../validators/index.mjs';
 
 const BANNER = `
-┌─ surf-skill setup ──────────────────────────────────────
+┌─ surf-search-skill setup ──────────────────────────────────────
 │ Configure API keys. You can add multiple keys per provider
 │ (Enter empty to finish a provider; Enter twice in a row to
 │ skip it entirely).
@@ -26,21 +27,21 @@ const CHEAT_SHEET_TPL = (counts) => `
 ✓ Saved. Now have ${counts.tav} Tavily key${counts.tav === 1 ? '' : 's'}, ${counts.par} Parallel key${counts.par === 1 ? '' : 's'}, ${counts.brv} Brave key${counts.brv === 1 ? '' : 's'}.
 
 Try one of:
-  surf-skill search "your query"
-  surf-skill search "q1" "q2" "q3"                # batch (N queries)
-  surf-skill search "x" --provider brave --mode fast
-  surf-skill extract https://example.com
-  surf-skill keys list
+  surf-search-skill search "your query"
+  surf-search-skill search "q1" "q2" "q3"                # batch (N queries)
+  surf-search-skill search "x" --provider brave --mode fast
+  surf-search-skill extract https://example.com
+  surf-search-skill keys list
 
 Add another key later with:
-  surf-skill keys add --provider <tavily|parallel|brave> <key>
+  surf-search-skill keys add --provider <tavily|parallel|brave> <key>
 
-🛠  IMPORTANT — in each project where you'll use surf-skill, run:
-      surf-skill project-config
+🛠  IMPORTANT — in each project where you'll use surf-search-skill, run:
+      surf-search-skill project-config
    This raises the per-project bash timeout for the harness in that repo.
 
 ⚠  GitHub Copilot CLI users: this step is REQUIRED. Copilot's default bash
-   timeout is 30s and surf-skill needs more (most commands run 3–60s).
+   timeout is 30s and surf-search-skill needs more (most commands run 3–60s).
 
 Docs: SKILL.md  ·  Repo: https://github.com/frederico-kluser/surf-skill
 `;
@@ -74,9 +75,9 @@ async function promptKeys(rl, provider, existing = []) {
 export async function runSetup() {
   if (!stdin.isTTY) {
     const err = new Error(`'setup' requires a TTY. Use:
-  surf-skill keys add --provider tavily <key>
-  surf-skill keys add --provider parallel <key>
-  surf-skill keys add --provider brave <key>`);
+  surf-search-skill keys add --provider tavily <key>
+  surf-search-skill keys add --provider parallel <key>
+  surf-search-skill keys add --provider brave <key>`);
     err.code = 'NO_TTY';
     throw err;
   }
@@ -99,13 +100,47 @@ export async function runSetup() {
   }
 
   if (!newTav.length && !newPar.length && !newBrv.length) {
-    stdout.write('\nNo new keys provided. Rerun with: surf-skill setup\n');
+    stdout.write('\nNo new keys provided. Rerun with: surf-search-skill setup\n');
     return { addedTavily: 0, addedParallel: 0, addedBrave: 0 };
   }
 
-  for (const k of newTav) state.tavily.keys.push(k);
-  for (const k of newPar) state.parallel.keys.push(k);
-  for (const k of newBrv) state.brave.keys.push(k);
+  // Live-validate every freshly collected key before persisting. Invalid
+  // keys are dropped from the batch with a clear message. The user
+  // doesn't waste hours wondering why fallback isn't kicking in.
+  stdout.write('\n— Validating new keys against each provider (1 credit each) —\n');
+  const keptTav = [];
+  for (const k of newTav) {
+    stdout.write(`  tavily ${k.slice(0, 5)}…${k.slice(-4)} → `);
+    const r = await validateKey('tavily', k);
+    stdout.write(formatValidation(r) + '\n');
+    if (r.valid) keptTav.push(k);
+  }
+  const keptPar = [];
+  for (const k of newPar) {
+    stdout.write(`  parallel ${k.slice(0, 5)}…${k.slice(-4)} → `);
+    const r = await validateKey('parallel', k);
+    stdout.write(formatValidation(r) + '\n');
+    if (r.valid) keptPar.push(k);
+  }
+  const keptBrv = [];
+  for (const k of newBrv) {
+    stdout.write(`  brave ${k.slice(0, 5)}…${k.slice(-4)} → `);
+    const r = await validateKey('brave', k);
+    stdout.write(formatValidation(r) + '\n');
+    if (r.valid) keptBrv.push(k);
+  }
+  const dropped = (newTav.length - keptTav.length) + (newPar.length - keptPar.length) + (newBrv.length - keptBrv.length);
+  if (dropped) {
+    stdout.write(`\n⚠ ${dropped} key${dropped === 1 ? '' : 's'} failed validation and were NOT saved.\n`);
+  }
+  if (!keptTav.length && !keptPar.length && !keptBrv.length) {
+    stdout.write('\nNo valid keys to save. Re-run `surf-search-skill setup` with working keys.\n');
+    return { addedTavily: 0, addedParallel: 0, addedBrave: 0, dropped };
+  }
+
+  for (const k of keptTav) state.tavily.keys.push(k);
+  for (const k of keptPar) state.parallel.keys.push(k);
+  for (const k of keptBrv) state.brave.keys.push(k);
   if (state.tavily.keys.length && state.tavily.current >= state.tavily.keys.length) state.tavily.current = 0;
   if (state.parallel.keys.length && state.parallel.current >= state.parallel.keys.length) state.parallel.current = 0;
   if (state.brave.keys.length && state.brave.current >= state.brave.keys.length) state.brave.current = 0;
@@ -118,8 +153,9 @@ export async function runSetup() {
     brv: state.brave.keys.length,
   }));
   return {
-    addedTavily: newTav.length,
-    addedParallel: newPar.length,
-    addedBrave: newBrv.length,
+    addedTavily: keptTav.length,
+    addedParallel: keptPar.length,
+    addedBrave: keptBrv.length,
+    dropped,
   };
 }

package/src/plan/plan-file.mjs

@@ -0,0 +1,170 @@
+// Read, write, and list plan files.
+
+import { existsSync, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { resolvePlansDir } from './plans-dir.mjs';
+import { planFilename, slugify } from './slug.mjs';
+
+/**
+ * Write a plan file. Returns the absolute path written.
+ *
+ * @param {object} plan
+ * @param {string} plan.task - task title (also seeds the slug)
+ * @param {string} plan.context - the "why"
+ * @param {Array<{name:string, value:string, citation?:number}>} [plan.decisions]
+ * @param {Array<string>} [plan.files]
+ * @param {Array<string|{title:string, body?:string}>} [plan.steps]
+ * @param {Array<string>} [plan.verification]
+ * @param {Array<{title:string, url:string}>} [plan.references]
+ * @param {object} [opts]
+ * @param {string} [opts.dir] - override resolvePlansDir()
+ * @param {Date}   [opts.now=new Date()]
+ * @returns {Promise<string>} absolute path of the written file
+ */
+export async function writePlan(plan, opts = {}) {
+  if (!plan || typeof plan !== 'object') throw new Error('writePlan: plan object required');
+  if (!plan.task || typeof plan.task !== 'string') throw new Error('writePlan: plan.task required');
+
+  const dir = opts.dir || await resolvePlansDir();
+  await fs.mkdir(dir, { recursive: true });
+
+  const baseName = planFilename(plan.task, opts.now);
+  // Collision avoidance: -2, -3, etc.
+  let filePath = path.join(dir, baseName);
+  let n = 2;
+  while (existsSync(filePath)) {
+    const noExt = baseName.replace(/\.md$/, '');
+    filePath = path.join(dir, `${noExt}-${n}.md`);
+    n++;
+  }
+
+  const md = renderPlanMarkdown(plan);
+  await fs.writeFile(filePath, md, 'utf8');
+  return filePath;
+}
+
+function renderPlanMarkdown(plan) {
+  const out = [];
+  out.push(`# Plan: ${plan.task.trim()}\n`);
+
+  out.push('## Context\n');
+  out.push(`${(plan.context || '_TBD — describe why this is being done and what success looks like._').trim()}\n`);
+
+  if (plan.decisions && plan.decisions.length) {
+    out.push('\n## Decisions\n');
+    for (const d of plan.decisions) {
+      const citation = d.citation ? `[^${d.citation}]` : '';
+      out.push(`- **${d.name}**: ${d.value}${citation ? ` ${citation}` : ''}`);
+    }
+    out.push('');
+  }
+
+  if (plan.files && plan.files.length) {
+    out.push('\n## Files to modify\n');
+    for (const f of plan.files) out.push(`- \`${f}\``);
+    out.push('');
+  }
+
+  if (plan.steps && plan.steps.length) {
+    out.push('\n## Implementation steps\n');
+    plan.steps.forEach((s, i) => {
+      if (typeof s === 'string') {
+        out.push(`${i + 1}. ${s}`);
+      } else {
+        const title = s.title || `Step ${i + 1}`;
+        const body = s.body ? ` — ${s.body}` : '';
+        out.push(`${i + 1}. **${title}**${body}`);
+      }
+    });
+    out.push('');
+  }
+
+  if (plan.verification && plan.verification.length) {
+    out.push('\n## Verification\n');
+    for (const v of plan.verification) out.push(`- ${v}`);
+    out.push('');
+  }
+
+  if (plan.references && plan.references.length) {
+    out.push('\n## References\n');
+    plan.references.forEach((r, i) => {
+      const n = i + 1;
+      out.push(`[^${n}]: [${r.title}](${r.url})`);
+    });
+    out.push('');
+  }
+
+  return out.join('\n');
+}
+
+/**
+ * Read a plan file by absolute path or by slug substring (resolves against
+ * the active plans dir).
+ *
+ * @param {string} pathOrSlug
+ * @returns {Promise<{path: string, content: string}>}
+ */
+export async function readPlan(pathOrSlug) {
+  let p = pathOrSlug;
+  if (!existsSync(p)) {
+    const dir = await resolvePlansDir({ ensure: false });
+    const matches = (await fs.readdir(dir))
+      .filter(f => f.endsWith('.md') && f.includes(pathOrSlug))
+      .sort()
+      .reverse();
+    if (!matches.length) {
+      throw new Error(`No plan file found matching '${pathOrSlug}' in ${dir}`);
+    }
+    p = path.join(dir, matches[0]);
+  }
+  const content = await fs.readFile(p, 'utf8');
+  return { path: p, content };
+}
+
+/**
+ * List plan files in the active plans dir (newest first).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.dir] - override resolvePlansDir()
+ * @returns {Promise<Array<{path:string, name:string, mtime:Date, size:number, title:string}>>}
+ */
+export async function listPlans(opts = {}) {
+  const dir = opts.dir || await resolvePlansDir({ ensure: false });
+  if (!existsSync(dir)) return [];
+  const files = (await fs.readdir(dir)).filter(f => f.endsWith('.md'));
+  const out = [];
+  for (const name of files) {
+    const p = path.join(dir, name);
+    const st = await fs.stat(p);
+    // Title: first line starting with `# Plan: ` (or just the first line).
+    let title = name.replace(/\.md$/, '');
+    try {
+      const head = (await fs.readFile(p, 'utf8')).split('\n', 5).join('\n');
+      const m = head.match(/^#\s*Plan:\s*(.+)$/m);
+      if (m) title = m[1].trim();
+    } catch {}
+    out.push({ path: p, name, mtime: st.mtime, size: st.size, title });
+  }
+  out.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+  return out;
+}
+
+/**
+ * Create a stub plan file (mostly empty, with placeholders). Used by
+ * `surf-plan-skill new "<task>"` so the user — or the agent — can fill it in.
+ *
+ * @param {string} task
+ * @param {object} [opts]
+ * @returns {Promise<string>} absolute path written
+ */
+export async function newPlanStub(task, opts = {}) {
+  return writePlan({
+    task,
+    context: '_TBD — Phase 1 (project discovery) + Phase 2 (web research) go here._',
+    decisions: [],
+    files: [],
+    steps: [],
+    verification: [],
+    references: [],
+  }, opts);
+}

package/src/plan/plans-dir.mjs

@@ -0,0 +1,46 @@
+// Resolve where plan files should be written.
+//
+// Order:
+//   1. $SURF_PLAN_DIR env var (explicit override — always wins)
+//   2. ./plans/ if it exists in process.cwd()
+//   3. ./.surf-plans/ if it exists in process.cwd()
+//   4. ~/.claude/plans/ (default; creates the dir if missing)
+
+import { existsSync, promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const HOME = os.homedir();
+const HOME_PLANS = path.join(HOME, '.claude', 'plans');
+
+export const DEFAULT_HOME_PLANS = HOME_PLANS;
+
+/**
+ * @param {object} [opts]
+ * @param {string} [opts.cwd=process.cwd()]
+ * @param {boolean} [opts.ensure=true] - create the directory if it doesn't exist
+ * @returns {Promise<string>}
+ */
+export async function resolvePlansDir(opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const ensure = opts.ensure !== false;
+
+  // 1. Explicit override.
+  if (process.env.SURF_PLAN_DIR) {
+    const p = path.resolve(process.env.SURF_PLAN_DIR);
+    if (ensure) await fs.mkdir(p, { recursive: true });
+    return p;
+  }
+
+  // 2. Project-level ./plans/
+  const projectPlans = path.join(cwd, 'plans');
+  if (existsSync(projectPlans)) return projectPlans;
+
+  // 3. Hidden ./.surf-plans/
+  const hidden = path.join(cwd, '.surf-plans');
+  if (existsSync(hidden)) return hidden;
+
+  // 4. Default ~/.claude/plans/
+  if (ensure) await fs.mkdir(HOME_PLANS, { recursive: true });
+  return HOME_PLANS;
+}

package/src/plan/slug.mjs

@@ -0,0 +1,55 @@
+// kebab-case slug from a free-form task title.
+
+const STOP_WORDS = new Set([
+  'a', 'an', 'the', 'and', 'or', 'but', 'for', 'with', 'of', 'in', 'on',
+  'at', 'to', 'from', 'by', 'as', 'is', 'are', 'be', 'do', 'does',
+]);
+
+/**
+ * Build a deterministic kebab-case slug from a task title.
+ * - lowercases
+ * - strips diacritics (ã → a)
+ * - removes punctuation
+ * - drops short stop words
+ * - joins with `-`
+ * - max 50 chars (truncates on word boundary when possible)
+ *
+ * @param {string} title
+ * @returns {string}
+ */
+export function slugify(title) {
+  if (!title || typeof title !== 'string') return 'untitled';
+  // Strip diacritics: NFD + remove combining marks.
+  const ascii = title.normalize('NFD').replace(/[̀-ͯ]/g, '');
+  const tokens = ascii
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, ' ')
+    .split(/\s+/)
+    .filter(t => t && !STOP_WORDS.has(t));
+  if (!tokens.length) return 'untitled';
+  let slug = tokens.join('-').replace(/-+/g, '-').replace(/^-|-$/g, '');
+  if (slug.length > 50) {
+    // Truncate on a hyphen if possible.
+    slug = slug.slice(0, 50);
+    const lastHyphen = slug.lastIndexOf('-');
+    if (lastHyphen > 20) slug = slug.slice(0, lastHyphen);
+  }
+  return slug || 'untitled';
+}
+
+/**
+ * Build a filename: `<slug>-<YYYYMMDD-HHMM>.md`.
+ *
+ * @param {string} title
+ * @param {Date} [now=new Date()]
+ * @returns {string}
+ */
+export function planFilename(title, now = new Date()) {
+  const slug = slugify(title);
+  const y = now.getUTCFullYear();
+  const mo = String(now.getUTCMonth() + 1).padStart(2, '0');
+  const d = String(now.getUTCDate()).padStart(2, '0');
+  const h = String(now.getUTCHours()).padStart(2, '0');
+  const mi = String(now.getUTCMinutes()).padStart(2, '0');
+  return `${slug}-${y}${mo}${d}-${h}${mi}.md`;
+}

package/src/validators/index.mjs

@@ -0,0 +1,129 @@
+// Per-provider key validators.
+//
+// Each validator runs a real 1-credit search call against the provider's
+// API using the existing adapter. If the call returns 200, the key is
+// valid; auth/billing errors mark it invalid; other errors are surfaced
+// with their kind so the caller can decide whether to save anyway.
+//
+// Cost per validation:
+//   - Tavily: 1 credit (~$0.001)
+//   - Parallel: ~1 credit (lite tier)
+//   - Brave: ~$0.003 (metered)
+//
+// This is a one-time cost per added key. Acceptable trade-off for
+// "saved a working key" vs "saved a dead key and discovered hours later".
+
+import { tavilyProvider } from '../lib/providers/tavily.mjs';
+import { parallelProvider } from '../lib/providers/parallel.mjs';
+import { braveProvider } from '../lib/providers/brave.mjs';
+
+const ADAPTERS = {
+  tavily: tavilyProvider,
+  parallel: parallelProvider,
+  brave: braveProvider,
+};
+
+const VERSION = '3.0.1';
+const VALIDATION_QUERY = 'surf-skill key validation ping';
+const TIMEOUT_MS = 20_000;
+
+/**
+ * Validate a single API key by making a live search call.
+ *
+ * @param {string} provider  - 'tavily' | 'parallel' | 'brave'
+ * @param {string} key
+ * @returns {Promise<{
+ *   valid: boolean,
+ *   provider: string,
+ *   latency_ms?: number,
+ *   credits?: number,
+ *   kind?: string,
+ *   statusCode?: number,
+ *   error?: string,
+ * }>}
+ */
+export async function validateKey(provider, key) {
+  const adapter = ADAPTERS[provider];
+  if (!adapter) {
+    return {
+      valid: false,
+      provider,
+      kind: 'unknown_provider',
+      error: `unknown provider: ${provider}. Use: tavily | parallel | brave`,
+    };
+  }
+  if (!key || typeof key !== 'string' || key.length < 8) {
+    return {
+      valid: false,
+      provider,
+      kind: 'malformed',
+      error: 'key is empty or too short',
+    };
+  }
+
+  const ctx = { key, timeout: TIMEOUT_MS, version: VERSION };
+  const t0 = Date.now();
+  try {
+    const result = await adapter.search(
+      { query: VALIDATION_QUERY, max: 1, mode: 'fast' },
+      ctx,
+    );
+    return {
+      valid: true,
+      provider,
+      latency_ms: Date.now() - t0,
+      credits: (result && result.usage && result.usage.credits) || 1,
+    };
+  } catch (e) {
+    return {
+      valid: false,
+      provider,
+      latency_ms: Date.now() - t0,
+      kind: e.kind || 'network',
+      statusCode: e.statusCode,
+      error: e.message || String(e),
+    };
+  }
+}
+
+/**
+ * Validate multiple keys, optionally in parallel.
+ *
+ * @param {Array<{provider: string, key: string}>} items
+ * @param {object} [opts]
+ * @param {boolean} [opts.parallel=false]  - run all validations in parallel
+ * @returns {Promise<Array>}
+ */
+export async function validateAll(items, opts = {}) {
+  if (opts.parallel) {
+    return Promise.all(items.map(it => validateKey(it.provider, it.key)));
+  }
+  const out = [];
+  for (const it of items) out.push(await validateKey(it.provider, it.key));
+  return out;
+}
+
+/**
+ * Human-readable summary of a validation result.
+ *
+ * @param {object} r  - result from validateKey
+ * @returns {string}
+ */
+export function formatValidation(r) {
+  if (r.valid) {
+    return `✓ valid (${r.provider}, HTTP 200, ${r.latency_ms}ms, ${r.credits} credit${r.credits === 1 ? '' : 's'})`;
+  }
+  const kindMap = {
+    auth:            'invalid key (401/403/422)',
+    rate_limit_429:  'rate limit hit — key likely valid but throttled, try again',
+    server_5xx:      "provider's server is down — try again later",
+    network:         'network error reaching provider',
+    malformed:       'key format is invalid',
+    unknown_provider:'unknown provider',
+    not_supported:   'provider does not support this validation method',
+  };
+  const reason = kindMap[r.kind] || r.kind || 'unknown error';
+  const status = r.statusCode ? ` HTTP ${r.statusCode}` : '';
+  const msg = r.error ? ` — ${r.error}` : '';
+  return `✗ ${reason}${status}${msg}`;
+}