surf-skill 2.0.0

package/src/lib/flags.mjs

@@ -0,0 +1,63 @@
+// Generic helpers: flag parsing, string ops, key masking.
+
+export function parseFlags(argv) {
+  const pos = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const k = a.slice(2);
+      const next = argv[i + 1];
+      if (!next || next.startsWith('--')) flags[k] = true;
+      else { flags[k] = next; i++; }
+    } else {
+      pos.push(a);
+    }
+  }
+  return { pos, flags };
+}
+
+export function clamp(n, min, max) {
+  return Math.min(Math.max(n, min), max);
+}
+
+export function ceilDiv(a, b) {
+  return Math.ceil(a / b);
+}
+
+export function splitList(s) {
+  return typeof s === 'string' ? s.split(',').map(x => x.trim()).filter(Boolean) : undefined;
+}
+
+export function trunc(s, n) {
+  if (!s) return '';
+  return s.length > n ? s.slice(0, n) + '…' : s;
+}
+
+export function flat(v) {
+  if (v == null) return '';
+  if (typeof v === 'string') return v;
+  return flat(v.message) || flat(v.error) || flat(v.detail) || JSON.stringify(v);
+}
+
+export function maskKey(key) {
+  if (!key || typeof key !== 'string') return '<empty>';
+  if (key.length <= 9) return key.slice(0, 2) + '…' + key.slice(-2);
+  return key.slice(0, 5) + '…' + key.slice(-4);
+}
+
+export function sleep(ms) {
+  return new Promise(r => setTimeout(r, ms));
+}
+
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+export function compactObject(obj) {
+  const out = {};
+  for (const k of Object.keys(obj)) {
+    if (obj[k] !== undefined) out[k] = obj[k];
+  }
+  return out;
+}

package/src/lib/format.mjs

@@ -0,0 +1,110 @@
+// Markdown formatters that consume the NORMALIZED result envelope:
+//   { provider, operation, data, usage, latency_ms, raw }
+
+import { trunc } from './flags.mjs';
+
+const MAX_RAW = Number(process.env.SURF_MAX_CONTENT_CHARS || process.env.TAVILY_MAX_CONTENT_CHARS) || 1500;
+
+function footer(envelope) {
+  const c = envelope.usage && envelope.usage.credits;
+  const bits = [`provider: ${envelope.provider}`];
+  if (envelope.latency_ms != null) bits.push(`${envelope.latency_ms}ms`);
+  if (c != null) bits.push(`credits: ${c}`);
+  return `\n_${bits.join(' · ')}_\n`;
+}
+
+export function fmtSearch(envelope) {
+  const r = envelope.data;
+  let md = `# Search: ${r.query || ''}\n\n`;
+  if (r.answer) md += `**Answer:** ${r.answer}\n\n`;
+  (r.results || []).forEach((it, i) => {
+    md += `## [${i + 1}] ${it.title || it.url}\n${it.url}\n`;
+    if (it.score != null) md += `*score: ${typeof it.score === 'number' ? it.score.toFixed(2) : it.score}*\n`;
+    if (it.published_date) md += `*published: ${it.published_date}*\n`;
+    md += `\n${trunc(it.content || '', MAX_RAW)}\n\n`;
+    if (it.raw_content) {
+      md += `<details><summary>raw</summary>\n\n${trunc(it.raw_content, 3000)}\n\n</details>\n\n`;
+    }
+  });
+  md += footer(envelope);
+  return md;
+}
+
+export function fmtExtract(envelope) {
+  const r = envelope.data;
+  let md = '# Extracted content\n\n';
+  (r.results || []).forEach((it, i) => {
+    md += `## [${i + 1}] ${it.url}\n`;
+    if (it.title) md += `**${it.title}**\n`;
+    md += `\n${trunc(it.raw_content, 3000)}\n\n`;
+  });
+  if (r.failed && r.failed.length) {
+    md += `\n**Failed:**\n`;
+    for (const f of r.failed) md += `- ${f.url} — ${f.reason}\n`;
+  }
+  md += footer(envelope);
+  return md;
+}
+
+export function fmtCrawl(envelope) {
+  const r = envelope.data;
+  let md = `# Crawl: ${r.base_url || ''}\n\n`;
+  (r.results || []).forEach((it, i) => {
+    md += `## [${i + 1}] ${it.url}\n\n`;
+    if (it.raw_content) md += `${trunc(it.raw_content, MAX_RAW)}\n\n`;
+  });
+  md += footer(envelope);
+  return md;
+}
+
+export function fmtMap(envelope) {
+  const r = envelope.data;
+  let md = `# Map: ${r.base_url || ''}\n\n`;
+  for (const u of r.urls || []) md += `- ${u}\n`;
+  md += footer(envelope);
+  return md;
+}
+
+export function fmtResearchStart(envelope) {
+  const r = envelope.data;
+  return [
+    `**Research started**`,
+    `- request_id: \`${r.request_id}\``,
+    `- model: ${r.model || '—'}`,
+    `- status: ${r.status}`,
+    '',
+    `Poll with: \`surf-skill research-poll ${r.request_id}\``,
+    footer(envelope),
+  ].join('\n');
+}
+
+export function fmtResearchPoll(envelope) {
+  const r = envelope.data;
+  if (r.status !== 'completed') {
+    return `Research **${r.status}** (request_id=\`${r.request_id}\`)${r.error ? '\n\nerror: ' + r.error : ''}${footer(envelope)}`;
+  }
+  let md = `# Research report\n\n${r.content || ''}\n\n`;
+  if (r.sources && r.sources.length) {
+    md += `## Sources\n`;
+    r.sources.forEach((s, i) => { md += `${i + 1}. [${s.title || s.url}](${s.url})\n`; });
+  }
+  md += footer(envelope);
+  return md;
+}
+
+export function fmtUsage(envelope) {
+  return JSON.stringify(envelope.data, null, 2);
+}
+
+export function formatFor(envelope) {
+  switch (envelope.operation) {
+    case 'search': return fmtSearch(envelope);
+    case 'extract': return fmtExtract(envelope);
+    case 'crawl': return fmtCrawl(envelope);
+    case 'map': return fmtMap(envelope);
+    case 'research-start': return fmtResearchStart(envelope);
+    case 'research-poll': return fmtResearchPoll(envelope);
+    case 'usage': return fmtUsage(envelope);
+    default: return JSON.stringify(envelope, null, 2);
+  }
+}

package/src/lib/harness-install.mjs

@@ -0,0 +1,149 @@
+// Cross-OS skill registration helpers used by postinstall / preuninstall.
+//
+// Strategy:
+//   - Symlink the package root into each harness's skill dir
+//     (~/.claude/skills/surf-skill, ~/.agents/skills/surf-skill, etc.)
+//   - On Windows: try fs.symlink with type='junction' first (no admin needed
+//     for directories). If EPERM/ENOSYS, fall back to recursive copy.
+//   - Idempotent: re-running fixes stale symlinks, leaves user copies alone.
+
+import { existsSync, promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const home = os.homedir();
+
+// Harness skill directories (per published docs as of 2026-05).
+// Order: canonical first, then per-harness.
+export const HARNESS_DIRS = [
+  path.join(home, '.agents', 'skills'),       // OpenCode + GH Copilot CLI canonical
+  path.join(home, '.claude', 'skills'),       // Claude Code
+  path.join(home, '.codex', 'skills'),        // OpenAI Codex CLI
+  path.join(home, '.pi', 'agent', 'skills'),  // Pi Coding Agent
+];
+
+// Legacy names from earlier versions that should be removed on upgrade.
+const LEGACY_NAMES = ['tavily', 'surf', 'tvly'];
+
+export async function symlinkOrCopy(target, link) {
+  // If link already exists, decide whether to replace it.
+  if (existsSync(link)) {
+    try {
+      const stat = await fs.lstat(link);
+      if (stat.isSymbolicLink()) {
+        const cur = await fs.readlink(link);
+        if (path.resolve(cur) === path.resolve(target)) return { action: 'kept-symlink' };
+        await fs.unlink(link);
+      } else {
+        // User has a non-symlink there (probably their own copy). Leave alone.
+        return { action: 'preserved-existing' };
+      }
+    } catch (e) {
+      // lstat failed; assume the path is corrupt — try to remove.
+      try { await fs.rm(link, { recursive: true, force: true }); } catch {}
+    }
+  }
+
+  // Try symlink first (junction on Windows works without admin).
+  try {
+    const type = process.platform === 'win32' ? 'junction' : 'dir';
+    await fs.symlink(target, link, type);
+    return { action: 'symlinked' };
+  } catch (e) {
+    if (e.code !== 'EPERM' && e.code !== 'ENOSYS' && e.code !== 'EEXIST') {
+      throw e;
+    }
+    // Fallback: recursive copy (Windows without dev mode).
+    await fs.cp(target, link, { recursive: true });
+    return { action: 'copied' };
+  }
+}
+
+export async function unlinkIfOurs(link, expectedTarget) {
+  if (!existsSync(link)) return false;
+  try {
+    const stat = await fs.lstat(link);
+    if (stat.isSymbolicLink()) {
+      const cur = await fs.readlink(link);
+      if (path.resolve(cur) === path.resolve(expectedTarget)) {
+        await fs.unlink(link);
+        return true;
+      }
+      return false;
+    }
+    // Non-symlink: likely a user copy. Don't delete.
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+export async function installSkill(pkgRoot) {
+  const results = [];
+  for (const dir of HARNESS_DIRS) {
+    try {
+      await fs.mkdir(dir, { recursive: true });
+      const link = path.join(dir, 'surf-skill');
+      const r = await symlinkOrCopy(pkgRoot, link);
+      results.push({ dir: link, ...r });
+    } catch (e) {
+      results.push({ dir, action: 'error', error: e.message });
+    }
+  }
+  return results;
+}
+
+export async function uninstallSkill(pkgRoot) {
+  const results = [];
+  for (const dir of HARNESS_DIRS) {
+    const link = path.join(dir, 'surf-skill');
+    try {
+      const removed = await unlinkIfOurs(link, pkgRoot);
+      results.push({ dir: link, removed });
+    } catch (e) {
+      results.push({ dir: link, removed: false, error: e.message });
+    }
+  }
+  return results;
+}
+
+export async function cleanupLegacy() {
+  const results = [];
+  for (const dir of HARNESS_DIRS) {
+    for (const name of LEGACY_NAMES) {
+      const link = path.join(dir, name);
+      // Use lstat (not existsSync) so we also catch broken symlinks pointing
+      // at paths that no longer exist (e.g. from a removed prior install).
+      try {
+        const stat = await fs.lstat(link);
+        if (stat.isSymbolicLink()) {
+          await fs.unlink(link);
+          results.push({ removed: link });
+        }
+      } catch (e) {
+        if (e.code !== 'ENOENT') throw e;
+      }
+    }
+  }
+  return results;
+}
+
+export async function ensureKeysSkeleton() {
+  const cfgDir = path.join(home, '.config', 'surf');
+  await fs.mkdir(cfgDir, { recursive: true });
+  const file = path.join(cfgDir, 'keys.json');
+  if (!existsSync(file)) {
+    const skeleton = {
+      schema_version: 1,
+      tavily: { keys: [], current: 0, burned: [] },
+      parallel: { keys: [], current: 0, burned: [] },
+      last_ok_provider: null,
+    };
+    await fs.writeFile(file, JSON.stringify(skeleton, null, 2) + '\n');
+    if (process.platform !== 'win32') {
+      try { await fs.chmod(file, 0o600); } catch {}
+    }
+    return { created: file };
+  }
+  return { existed: file };
+}

package/src/lib/keys-cmd.mjs

@@ -0,0 +1,138 @@
+// `surf-skill keys` subcommands: add, remove, list (status), reset, clear.
+
+import { loadState, saveStateAtomic, clearBurned, PROVIDERS, KEYS_FILE } from './state.mjs';
+import { maskKey } from './flags.mjs';
+
+function nextResetIso(burnedAt) {
+  const d = new Date(burnedAt);
+  if (Number.isNaN(d.getTime())) return '—';
+  const next = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + 1, 1, 0, 0, 0));
+  return next.toISOString();
+}
+
+function requireProvider(flags, allowAll = false) {
+  const p = flags.provider;
+  if (!p) {
+    if (allowAll && flags.all) return null;
+    throw new Error(`--provider <${PROVIDERS.join('|')}> is required`);
+  }
+  if (!PROVIDERS.includes(p)) {
+    throw new Error(`unknown provider '${p}' (valid: ${PROVIDERS.join(', ')})`);
+  }
+  return p;
+}
+
+export async function keysAdd(pos, flags) {
+  const provider = requireProvider(flags);
+  const key = pos[0];
+  if (!key) throw new Error('Usage: surf-skill keys add --provider <name> <key>');
+  const state = await loadState();
+  if (state[provider].keys.includes(key)) {
+    return { provider, added: false, reason: 'already exists', state };
+  }
+  state[provider].keys.push(key);
+  if (state[provider].keys.length === 1) state[provider].current = 0;
+  await saveStateAtomic(state);
+  return { provider, added: true, index: state[provider].keys.length - 1, state };
+}
+
+export async function keysRemove(pos, flags) {
+  const provider = requireProvider(flags);
+  const target = pos[0];
+  if (target == null) throw new Error('Usage: surf-skill keys remove --provider <name> <index|key>');
+  const state = await loadState();
+  const keys = state[provider].keys;
+  let idx = -1;
+  if (/^\d+$/.test(String(target))) {
+    idx = Number(target);
+  } else {
+    idx = keys.indexOf(target);
+  }
+  if (idx < 0 || idx >= keys.length) throw new Error(`no key at '${target}' for provider '${provider}'`);
+  keys.splice(idx, 1);
+  // adjust current and burned indices
+  if (state[provider].current >= keys.length) state[provider].current = 0;
+  state[provider].burned = state[provider].burned
+    .filter(b => b.index !== idx)
+    .map(b => (b.index > idx ? { ...b, index: b.index - 1 } : b));
+  await saveStateAtomic(state);
+  return { provider, removed: true, index: idx, state };
+}
+
+export async function keysList(_pos, flags) {
+  const state = await loadState();
+  if (flags.json) return { json: true, state };
+  const lines = [];
+  lines.push(`**Surf keys** (config: \`${KEYS_FILE}\`)`);
+  lines.push(`last_ok_provider: \`${state.last_ok_provider || 'none'}\`\n`);
+  for (const p of PROVIDERS) {
+    const pp = state[p];
+    const burnedIdx = new Set(pp.burned.map(b => b.index));
+    lines.push(`## ${p} (${pp.keys.length} key${pp.keys.length === 1 ? '' : 's'})`);
+    if (!pp.keys.length) {
+      lines.push(`_no keys — add with \`surf-skill keys add --provider ${p} <key>\`_\n`);
+      continue;
+    }
+    pp.keys.forEach((k, i) => {
+      const flags = [];
+      if (i === pp.current) flags.push('current');
+      if (burnedIdx.has(i)) flags.push('burned');
+      lines.push(`- [${i}] ${maskKey(k)}${flags.length ? '  *(' + flags.join(', ') + ')*' : ''}`);
+    });
+    if (pp.burned.length) {
+      lines.push('');
+      lines.push(`**Burned:**`);
+      for (const b of pp.burned) {
+        lines.push(`- index ${b.index} — reason: ${b.reason}, at ${b.at}, auto-reset on ${nextResetIso(b.at)}`);
+      }
+    }
+    lines.push('');
+  }
+  return { text: lines.join('\n') };
+}
+
+export async function keysReset(_pos, flags) {
+  const state = await loadState();
+  const provider = flags.provider ? requireProvider(flags) : null;
+  clearBurned(state, provider);
+  await saveStateAtomic(state);
+  return { provider, reset: true, state };
+}
+
+export async function keysClear(_pos, flags) {
+  if (!flags.yes) {
+    const tty = process.stdin && process.stdin.isTTY;
+    if (!tty) {
+      const err = new Error('non-interactive: pass --yes to confirm destructive clear');
+      err.code = 'NEEDS_YES';
+      throw err;
+    }
+  }
+  const state = await loadState();
+  if (flags.all) {
+    for (const p of PROVIDERS) state[p] = { keys: [], current: 0, burned: [] };
+    state.last_ok_provider = null;
+  } else {
+    const provider = requireProvider(flags);
+    state[provider] = { keys: [], current: 0, burned: [] };
+    if (state.last_ok_provider === provider) state.last_ok_provider = null;
+  }
+  await saveStateAtomic(state);
+  return { cleared: true, state };
+}
+
+export async function runKeysSubcommand(sub, pos, flags) {
+  switch (sub) {
+    case 'add': return keysAdd(pos, flags);
+    case 'remove':
+    case 'rm':
+    case 'delete': return keysRemove(pos, flags);
+    case 'list':
+    case 'ls':
+    case 'status': return keysList(pos, flags);
+    case 'reset': return keysReset(pos, flags);
+    case 'clear': return keysClear(pos, flags);
+    default:
+      throw new Error(`unknown 'surf-skill keys' subcommand: '${sub}'. Valid: add, remove, list, reset, clear`);
+  }
+}

package/src/lib/progress.mjs

@@ -0,0 +1,81 @@
+// Progress logger — writes one self-contained line per event to stderr.
+//
+// Design constraints (researched 2026-05-20):
+//   - stdout stays clean (the LLM/pipe parses JSON or Markdown there).
+//   - stderr is line-based, unbuffered, plain text. NO ANSI animation,
+//     NO `\r` rewrites — those become noise in non-TTY captures and
+//     burn tokens when the agent reads back the stderr at the end of
+//     the bash call.
+//   - Each line is self-contained: `[surf HH:MM:SS] SYMBOL message`.
+//     Agents can grep these lines; humans can read them.
+//   - `SURF_QUIET=1` env or setSilent(true) silences output (for tests
+//     and scripts that capture stderr).
+//
+// Symbols (Unicode, fits any terminal):
+//   ▸ start of an operation/attempt
+//   ✓ success
+//   ✗ failure
+//   ↻ retry / backoff
+//   ⓘ informational
+//   ⚠ warning / soft issue (e.g. key burned)
+//   ⏱ timing / summary
+
+import { stderr } from 'node:process';
+
+const SYMBOLS = {
+  start:   '▸',
+  success: '✓',
+  fail:    '✗',
+  retry:   '↻',
+  info:    'ⓘ',
+  warn:    '⚠',
+  done:    '⏱',
+};
+
+let silent = process.env.SURF_QUIET === '1';
+
+export function setSilent(v) {
+  silent = !!v;
+}
+
+export function isSilent() {
+  return silent;
+}
+
+function ts() {
+  const d = new Date();
+  const hh = String(d.getUTCHours()).padStart(2, '0');
+  const mm = String(d.getUTCMinutes()).padStart(2, '0');
+  const ss = String(d.getUTCSeconds()).padStart(2, '0');
+  return `${hh}:${mm}:${ss}`;
+}
+
+function write(symbolKey, msg) {
+  if (silent) return;
+  const sym = SYMBOLS[symbolKey] || '·';
+  stderr.write(`[surf ${ts()}] ${sym} ${msg}\n`);
+}
+
+export const progress = {
+  start:   (msg) => write('start', msg),
+  success: (msg) => write('success', msg),
+  fail:    (msg) => write('fail', msg),
+  retry:   (msg) => write('retry', msg),
+  info:    (msg) => write('info', msg),
+  warn:    (msg) => write('warn', msg),
+  done:    (msg) => write('done', msg),
+};
+
+// Convenience: time an async block. Emits start/done with elapsed.
+export async function timed(label, fn) {
+  const t0 = Date.now();
+  progress.start(label);
+  try {
+    const r = await fn();
+    progress.done(`${label} (${Date.now() - t0}ms)`);
+    return r;
+  } catch (e) {
+    progress.fail(`${label} (${Date.now() - t0}ms): ${e.message || e}`);
+    throw e;
+  }
+}

package/src/lib/project-config.mjs

@@ -0,0 +1,145 @@
+// `surf-skill project-config` — writes per-project harness config to raise
+// the bash timeout that the harness uses. Detects which harness is in use
+// from the presence of `.github/`, `.claude/`, `.pi/` in the cwd. With
+// --harness, forces a specific target.
+
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import readline from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+
+export const HARNESSES = ['copilot', 'claude', 'pi'];
+
+const PATCHES = {
+  copilot: {
+    file: '.github/copilot-hooks.json',
+    patch: { timeoutSec: 300 },
+    why: 'GH Copilot CLI default bash timeout is 30s — surf-skill needs more.',
+  },
+  claude: {
+    // .claude/settings.local.json is gitignored by Anthropic convention.
+    file: '.claude/settings.local.json',
+    patch: {
+      env: {
+        BASH_DEFAULT_TIMEOUT_MS: '300000',
+        BASH_MAX_TIMEOUT_MS: '600000',
+      },
+    },
+    why: 'Claude Code default bash timeout is 120s; raising to 300s.',
+  },
+  pi: {
+    file: '.pi/settings.json',
+    patch: {
+      env: {
+        PI_BASH_DEFAULT_TIMEOUT_SECONDS: '300',
+        PI_BASH_MAX_TIMEOUT_SECONDS: '600',
+      },
+    },
+    why: 'Pi Coding Agent default bash timeout is 120s; raising to 300s.',
+  },
+};
+
+function isPlainObject(v) {
+  return v && typeof v === 'object' && !Array.isArray(v);
+}
+
+function deepMerge(target, source) {
+  if (!isPlainObject(target)) return source;
+  if (!isPlainObject(source)) return source;
+  for (const k of Object.keys(source)) {
+    if (isPlainObject(source[k])) {
+      target[k] = deepMerge(isPlainObject(target[k]) ? target[k] : {}, source[k]);
+    } else {
+      target[k] = source[k];
+    }
+  }
+  return target;
+}
+
+async function mergeJsonFile(absPath, patch) {
+  await mkdir(dirname(absPath), { recursive: true });
+  let current = {};
+  if (existsSync(absPath)) {
+    try { current = JSON.parse(await readFile(absPath, 'utf8')); } catch { current = {}; }
+  }
+  const merged = deepMerge(current, patch);
+  await writeFile(absPath, JSON.stringify(merged, null, 2) + '\n');
+  return { wrote: absPath, patch, merged };
+}
+
+export function detectHarnesses(cwd) {
+  const found = [];
+  if (existsSync(join(cwd, '.github'))) found.push('copilot');
+  if (existsSync(join(cwd, '.claude'))) found.push('claude');
+  if (existsSync(join(cwd, '.pi'))) found.push('pi');
+  return found;
+}
+
+async function promptHarness() {
+  if (!stdin.isTTY) {
+    const err = new Error(
+      "project-config could not detect any harness directory and stdin is not a TTY. " +
+      "Pass --harness <copilot|claude|pi|all>."
+    );
+    err.code = 'PROJECT_CONFIG_NO_TTY';
+    throw err;
+  }
+  const rl = readline.createInterface({ input: stdin, output: stdout });
+  try {
+    const a = (await rl.question(
+      'No harness directory detected here. Which harness? [copilot/claude/pi/all]: '
+    )).trim().toLowerCase();
+    if (a === 'all') return [...HARNESSES];
+    if (HARNESSES.includes(a)) return [a];
+    throw Object.assign(new Error(`unknown harness '${a}'`), { code: 'PROJECT_CONFIG_BAD_HARNESS' });
+  } finally {
+    rl.close();
+  }
+}
+
+export async function runProjectConfig(_pos, flags = {}, cwd = process.cwd()) {
+  let targets;
+  if (flags.harness) {
+    if (flags.harness === 'all') {
+      targets = [...HARNESSES];
+    } else if (HARNESSES.includes(flags.harness)) {
+      targets = [flags.harness];
+    } else {
+      throw Object.assign(
+        new Error(`unknown --harness '${flags.harness}'; valid: ${HARNESSES.join(', ')}, all`),
+        { code: 'PROJECT_CONFIG_BAD_HARNESS' }
+      );
+    }
+  } else {
+    const detected = detectHarnesses(cwd);
+    targets = detected.length ? detected : await promptHarness();
+  }
+
+  const results = [];
+  for (const t of targets) {
+    const spec = PATCHES[t];
+    const abs = resolve(cwd, spec.file);
+    const r = await mergeJsonFile(abs, spec.patch);
+    results.push({ harness: t, file: r.wrote, why: spec.why });
+  }
+
+  return { cwd, targets, results };
+}
+
+export function formatProjectConfigResult(result, { json = false } = {}) {
+  if (json) return JSON.stringify(result, null, 2);
+  const lines = [`✓ surf-skill project-config in ${result.cwd}`];
+  for (const r of result.results) {
+    lines.push(`  • ${r.harness}: wrote ${r.file}`);
+    lines.push(`      ${r.why}`);
+  }
+  lines.push('');
+  if (result.targets.includes('copilot')) {
+    lines.push('ℹ Commit .github/copilot-hooks.json so teammates inherit the timeout.');
+  }
+  if (result.targets.includes('claude')) {
+    lines.push('ℹ .claude/settings.local.json is .gitignored by convention (per-user).');
+  }
+  return lines.join('\n');
+}