@prustogi/buddy 0.3.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@prustogi/buddy",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.3.0",
+  "description": "A friendly onboarding agent for GitHub Copilot CLI and Claude Code CLI. Helps newcomers understand any code repository. Stores portable, git-friendly knowledge in .buddy/.",
+  "keywords": [
+    "copilot",
+    "claude",
+    "cli",
+    "onboarding",
+    "documentation",
+    "agent",
+    "buddy"
+  ],
+  "license": "MIT",
+  "author": "Buddy Contributors",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "buddy": "bin/buddy.js"
+  },
+  "main": "src/lib/index.js",
+  "files": [
+    "bin/",
+    "src/",
+    "agents/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "start": "node bin/buddy.js"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  }
+}

package/src/commands/agent.js

@@ -0,0 +1,138 @@
+import { existsSync, mkdirSync, copyFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { agentPromptPath, claudeAgentPromptPath, findRepoRoot } from '../lib/paths.js';
+
+// Install destinations auto-discovered by each CLI:
+//   Copilot CLI repo:  <repoRoot>/.github/agents/buddy.md
+//   Copilot CLI user:  ~/.copilot/agents/buddy.md
+//   Claude Code repo:  <repoRoot>/.claude/agents/buddy.md
+//   Claude Code user:  ~/.claude/agents/buddy.md
+
+function destForCopilot(scope, repoRoot) {
+  if (scope === 'user') return join(homedir(), '.copilot', 'agents', 'buddy.md');
+  return join(repoRoot, '.github', 'agents', 'buddy.md');
+}
+
+function destForClaude(scope, repoRoot) {
+  if (scope === 'user') return join(homedir(), '.claude', 'agents', 'buddy.md');
+  return join(repoRoot, '.claude', 'agents', 'buddy.md');
+}
+
+function installTo(src, dest, force) {
+  if (!existsSync(src)) throw new Error(`agent prompt not found at ${src}`);
+  const destDir = join(dest, '..');
+  if (!existsSync(destDir)) mkdirSync(destDir, { recursive: true });
+
+  if (existsSync(dest)) {
+    if (!force) {
+      const a = readFileSync(src, 'utf8');
+      const b = readFileSync(dest, 'utf8');
+      if (a === b) return { dest, action: 'already-installed' };
+      return { dest, action: 'exists-different', src };
+    }
+    copyFileSync(src, dest);
+    return { dest, action: 'overwritten' };
+  }
+  copyFileSync(src, dest);
+  return { dest, action: 'created' };
+}
+
+export function installAgent({ scope = 'repo', force = false, repoRoot } = {}) {
+  const root = repoRoot || findRepoRoot();
+  const dest = destForCopilot(scope, root);
+  return installTo(agentPromptPath(), dest, force);
+}
+
+export function installClaudeAgent({ scope = 'repo', force = false, repoRoot } = {}) {
+  const root = repoRoot || findRepoRoot();
+  const dest = destForClaude(scope, root);
+  return installTo(claudeAgentPromptPath(), dest, force);
+}
+
+function printInstallResult(result, label) {
+  if (result.action === 'already-installed') {
+    console.log(`✓ ${label} agent already installed at ${result.dest}`);
+  } else if (result.action === 'exists-different') {
+    console.log(`! ${label} agent already exists at ${result.dest} (different version).`);
+    console.log('  Re-run with --force to overwrite.');
+    return false;
+  } else {
+    const verb = result.action === 'overwritten' ? 'Overwrote' : 'Installed';
+    console.log(`🤝 ${verb} ${label} agent at ${result.dest}`);
+  }
+  return true;
+}
+
+function listAgents(repoRoot) {
+  const root = repoRoot || findRepoRoot();
+  const locations = [
+    { label: 'Copilot CLI (repo)', path: destForCopilot('repo', root) },
+    { label: 'Copilot CLI (user)', path: destForCopilot('user', root) },
+    { label: 'Claude Code (repo)', path: destForClaude('repo', root) },
+    { label: 'Claude Code (user)', path: destForClaude('user', root) },
+  ];
+  console.log('Buddy agent locations:');
+  for (const loc of locations) {
+    const status = existsSync(loc.path) ? '✓ installed' : '✗ not installed';
+    console.log(`  ${status}  ${loc.label}`);
+    console.log(`              ${loc.path}`);
+  }
+}
+
+export async function agentCommand(subcommand, opts = {}) {
+  const sub = subcommand || 'install';
+  const scope = opts.user ? 'user' : 'repo';
+  const repoRoot = findRepoRoot();
+
+  if (sub === 'path') {
+    console.log('Copilot CLI agent:', agentPromptPath());
+    console.log('Claude Code agent:', claudeAgentPromptPath());
+    return;
+  }
+
+  if (sub === 'list') {
+    listAgents(repoRoot);
+    return;
+  }
+
+  if (sub === 'install') {
+    const forClaude = opts.claude || opts.all;
+    const forCopilot = !opts.claude || opts.all;
+    let anyFailed = false;
+
+    if (forCopilot) {
+      const result = installAgent({ scope, force: !!opts.force, repoRoot });
+      const ok = printInstallResult(result, 'Copilot CLI');
+      if (!ok) anyFailed = true;
+    }
+
+    if (forClaude) {
+      const result = installClaudeAgent({ scope, force: !!opts.force, repoRoot });
+      const ok = printInstallResult(result, 'Claude Code');
+      if (!ok) anyFailed = true;
+    }
+
+    if (anyFailed) {
+      process.exitCode = 1;
+      return;
+    }
+
+    console.log('');
+    if (forCopilot && !forClaude) {
+      console.log('Next: launch Copilot CLI in this repo and run:');
+      console.log('  /agent          (then pick "buddy")');
+    } else if (forClaude && !forCopilot) {
+      console.log('Next: launch Claude Code in this repo and run:');
+      console.log('  @buddy  (or mention Buddy naturally in your prompt)');
+    } else {
+      console.log('Next steps:');
+      console.log('  Copilot CLI:  /agent  (then pick "buddy")');
+      console.log('  Claude Code:  @buddy  (or mention Buddy naturally in your prompt)');
+    }
+    return;
+  }
+
+  console.error(`buddy: unknown agent subcommand "${sub}". Use: install [--claude] [--all] [--user] [--force] | list | path`);
+  process.exit(1);
+}

package/src/commands/init.js

@@ -0,0 +1,101 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { findRepoRoot, buddyDir, templatesDir, isDir } from '../lib/paths.js';
+import { copyTree } from '../lib/scaffold.js';
+import { readManifest, writeManifest, defaultManifest } from '../lib/manifest.js';
+import { hasGit, headCommit } from '../lib/git.js';
+import { openFile } from '../lib/opener.js';
+import { installAgent, installClaudeAgent } from './agent.js';
+
+export async function initCommand(opts) {
+  const repoRoot = findRepoRoot();
+  const buddy = buddyDir(repoRoot);
+  const homePage = join(buddy, 'README_FOR_HUMANS.md');
+  const alreadyExisted = isDir(buddy);
+
+  if (alreadyExisted && !opts.force) {
+    console.log(`✓ .buddy/ already exists at ${buddy}`);
+    console.log('  Treating it as the source of truth. Nothing to scaffold.');
+    maybeInstallAgent(repoRoot, opts);
+    autoOpenHome(homePage, opts);
+    return;
+  }
+
+  if (!isDir(buddy)) mkdirSync(buddy, { recursive: true });
+
+  const { created, skipped } = copyTree(templatesDir(), buddy);
+
+  const manifest = readManifest(buddy) || defaultManifest();
+  manifest.last_run_timestamp = new Date().toISOString();
+  if (hasGit(repoRoot)) {
+    manifest.last_indexed_commit = headCommit(repoRoot);
+  }
+  manifest.key_outputs_updated = ['init'];
+  writeManifest(buddy, manifest);
+
+  console.log(`🎉 Buddy initialized at ${buddy}`);
+  console.log(`   Files created: ${created.length}, skipped (already present): ${skipped.length}`);
+  if (manifest.last_indexed_commit) {
+    console.log(`   Indexed commit: ${manifest.last_indexed_commit.slice(0, 8)}`);
+  } else {
+    console.log('   (No git repo detected — fine. Buddy will fall back to file mtimes.)');
+  }
+
+  maybeInstallAgent(repoRoot, opts);
+
+  console.log('');
+  console.log('Next steps:');
+  console.log('  Copilot CLI:  /agent  →  pick "buddy"  →  "Scan this repo and fill in .buddy/"');
+  console.log('  Claude Code:  @buddy  →  "Scan this repo and fill in .buddy/"');
+
+  autoOpenHome(homePage, opts);
+}
+
+function maybeInstallAgent(repoRoot, opts) {
+  if (opts.installAgent === false) return;
+  const scope = opts.userAgent ? 'user' : 'repo';
+
+  // Install for Copilot CLI
+  try {
+    const result = installAgent({ scope, repoRoot });
+    if (result.action === 'already-installed') {
+      console.log(`✓ Copilot CLI agent already installed at ${result.dest}`);
+    } else if (result.action === 'exists-different') {
+      console.log(`! Copilot CLI agent at ${result.dest} differs — run "buddy agent install --force" to update.`);
+    } else {
+      console.log(`🤝 Installed Copilot CLI agent at ${result.dest}`);
+    }
+  } catch (err) {
+    console.log(`! Could not install Copilot CLI agent: ${err.message}`);
+  }
+
+  // Install for Claude Code
+  try {
+    const result = installClaudeAgent({ scope, repoRoot });
+    if (result.action === 'already-installed') {
+      console.log(`✓ Claude Code agent already installed at ${result.dest}`);
+    } else if (result.action === 'exists-different') {
+      console.log(`! Claude Code agent at ${result.dest} differs — run "buddy agent install --claude --force" to update.`);
+    } else {
+      console.log(`🤝 Installed Claude Code agent at ${result.dest}`);
+    }
+  } catch (err) {
+    console.log(`! Could not install Claude Code agent: ${err.message}`);
+  }
+}
+
+function autoOpenHome(homePage, opts) {
+  if (opts.open === false) {
+    console.log(`\n📖 Home page: ${homePage}`);
+    return;
+  }
+  const result = openFile(homePage, { silent: true });
+  if (result.opened) {
+    console.log(`\n📖 Opened home page: ${homePage}`);
+  } else {
+    console.log(`\n📖 Home page: ${homePage}`);
+    if (result.reason && result.reason !== 'BUDDY_NO_OPEN=1') {
+      console.log(`   (Could not auto-open: ${result.reason})`);
+    }
+  }
+}

package/src/commands/link.js

@@ -0,0 +1,70 @@
+import { readFileSync, writeFileSync, existsSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { findRepoRoot, buddyDir, isDir } from '../lib/paths.js';
+import { redactUrl } from '../lib/redact.js';
+import { readManifest, writeManifest, defaultManifest } from '../lib/manifest.js';
+
+export async function linkCommand(rawUrl, opts) {
+  const repoRoot = findRepoRoot();
+  const buddy = buddyDir(repoRoot);
+
+  if (!isDir(buddy)) {
+    console.error('buddy: no .buddy/ here. Run "buddy init" first.');
+    process.exit(1);
+  }
+
+  const { url, redacted, warnings } = redactUrl(rawUrl);
+  for (const w of warnings) console.log(`⚠️  ${w}`);
+
+  const entry = {
+    title: opts.title || inferTitle(url),
+    url,
+    description: opts.desc || '',
+    tags: (opts.tags || '').split(',').map((s) => s.trim()).filter(Boolean),
+    relevance: opts.relevance || 'helpful',
+    added_by: process.env.USER || process.env.USERNAME || 'unknown',
+    added_at: new Date().toISOString(),
+    redacted,
+  };
+
+  // Update INDEX/links.json
+  const linksJsonPath = join(buddy, 'INDEX', 'links.json');
+  const existing = existsSync(linksJsonPath)
+    ? safeJson(readFileSync(linksJsonPath, 'utf8'), { links: [] })
+    : { links: [] };
+  existing.links.push(entry);
+  writeFileSync(linksJsonPath, JSON.stringify(existing, null, 2) + '\n', 'utf8');
+
+  // Append to LINKS.md (human-friendly)
+  const linksMd = join(buddy, 'LINKS.md');
+  const block =
+    `\n### ${entry.title}\n` +
+    `- **URL:** ${entry.url}\n` +
+    `- **Why it matters:** ${entry.description || '(add a short note)'}\n` +
+    `- **Tags:** ${entry.tags.join(', ') || '(none)'}\n` +
+    `- **Relevance:** ${entry.relevance}\n` +
+    `- **Added:** ${entry.added_at} by ${entry.added_by}\n`;
+  appendFileSync(linksMd, block, 'utf8');
+
+  // Update manifest timestamp
+  const manifest = readManifest(buddy) || defaultManifest();
+  manifest.last_link_update_timestamp = entry.added_at;
+  writeManifest(buddy, manifest);
+
+  console.log(`📎 Saved link: ${entry.title}`);
+  console.log(`   ${entry.url}`);
+  console.log('   (Note: Buddy stores link metadata only — it has not read the linked page.)');
+}
+
+function safeJson(text, fallback) {
+  try { return JSON.parse(text); } catch { return fallback; }
+}
+
+function inferTitle(url) {
+  try {
+    const u = new URL(url);
+    return `${u.hostname}${u.pathname}`.replace(/\/$/, '') || u.hostname;
+  } catch {
+    return url.slice(0, 60);
+  }
+}

package/src/commands/open.js

@@ -0,0 +1,66 @@
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { findRepoRoot, buddyDir, isDir } from '../lib/paths.js';
+import { openFile } from '../lib/opener.js';
+
+const ALIASES = {
+  home: 'README_FOR_HUMANS.md',
+  readme: 'README_FOR_HUMANS.md',
+  'getting-started': 'GETTING_STARTED.md',
+  setup: 'GETTING_STARTED.md',
+  architecture: 'ARCHITECTURE.md',
+  arch: 'ARCHITECTURE.md',
+  stack: 'TECH_STACK.md',
+  'tech-stack': 'TECH_STACK.md',
+  integrations: 'INTEGRATIONS.md',
+  changelog: 'CHANGELOG_SUMMARY.md',
+  links: 'LINKS.md',
+  map: 'MAP/repo_map.md',
+  entry: 'MAP/entry_points.md',
+  'entry-points': 'MAP/entry_points.md',
+  flow: 'MAP/data_flow.md',
+  'data-flow': 'MAP/data_flow.md',
+  questions: 'NOTES/open_questions.md',
+  assumptions: 'NOTES/assumptions.md',
+};
+
+export async function openCommand(doc, opts) {
+  const repoRoot = findRepoRoot();
+  const buddy = buddyDir(repoRoot);
+
+  if (!isDir(buddy)) {
+    console.error(`buddy: no .buddy/ found at ${buddy}`);
+    console.error('  Run "buddy init" first.');
+    process.exit(1);
+  }
+
+  const target = doc ? resolveDoc(doc) : 'README_FOR_HUMANS.md';
+  const filePath = join(buddy, target);
+
+  if (!existsSync(filePath)) {
+    console.error(`buddy: not found in .buddy/ — ${target}`);
+    process.exit(1);
+  }
+
+  if (opts.open === false) {
+    console.log(filePath);
+    return;
+  }
+
+  const result = openFile(filePath, { silent: true });
+  if (result.opened) {
+    console.log(`📖 Opened ${target}`);
+  } else {
+    console.log(filePath);
+    if (result.reason && result.reason !== 'BUDDY_NO_OPEN=1') {
+      console.log(`(Could not auto-open: ${result.reason})`);
+    }
+  }
+}
+
+function resolveDoc(name) {
+  const key = name.toLowerCase().replace(/\.md$/, '');
+  if (ALIASES[key]) return ALIASES[key];
+  // Allow direct path inside .buddy/
+  return name;
+}

package/src/commands/precheck.js

@@ -0,0 +1,65 @@
+import { findRepoRoot, buddyDir, isDir } from '../lib/paths.js';
+import { readManifest } from '../lib/manifest.js';
+import { hasGit, headCommit, changedFilesSince, workingTreeChanges } from '../lib/git.js';
+
+// Heuristics: which doc(s) might be stale based on which files changed.
+const RULES = [
+  { match: /(^|\/)package\.json$|^requirements\.txt$|^pyproject\.toml$|^go\.mod$|^Cargo\.toml$|^pom\.xml$|^build\.gradle/, doc: 'TECH_STACK.md' },
+  { match: /^README\.md$|^docs?\//i, doc: 'README_FOR_HUMANS.md' },
+  { match: /^Dockerfile$|docker-compose|\.env|config\//i, doc: 'INTEGRATIONS.md' },
+  { match: /^src\//, doc: 'MAP/repo_map.md' },
+  { match: /(server|main|index|app|cli)\.(js|ts|py|go|rs|java)$/i, doc: 'MAP/entry_points.md' },
+  { match: /(routes?|controllers?|handlers?|api)\//i, doc: 'MAP/data_flow.md' },
+  { match: /\.github\/|Makefile|justfile/i, doc: 'GETTING_STARTED.md' },
+];
+
+export async function precheckCommand() {
+  const repoRoot = findRepoRoot();
+  const buddy = buddyDir(repoRoot);
+
+  if (!isDir(buddy)) {
+    console.log('❌ No .buddy/ here. Run "buddy init" first.');
+    return;
+  }
+  if (!hasGit(repoRoot)) {
+    console.log('⚠️  No git detected — precheck needs git history.');
+    return;
+  }
+
+  const manifest = readManifest(buddy);
+  const last = manifest && manifest.last_indexed_commit;
+  if (!last) {
+    console.log('💡 No prior index. Ask Buddy to scan this repo first.');
+    return;
+  }
+
+  const head = headCommit(repoRoot);
+  const committed = changedFilesSince(last, repoRoot);
+  const working = workingTreeChanges(repoRoot);
+  const allPaths = [
+    ...committed.map((c) => c.path),
+    ...working.map((w) => w.path),
+  ];
+
+  console.log(`🔍 Files changed since .buddy was last updated (commit ${last.slice(0, 8)} → ${head.slice(0, 8)}):`);
+  if (allPaths.length === 0) {
+    console.log('   (none)');
+    console.log('\n✅ .buddy/ should still be current.');
+    return;
+  }
+  for (const p of allPaths.slice(0, 30)) console.log(`   ${p}`);
+  if (allPaths.length > 30) console.log(`   …and ${allPaths.length - 30} more`);
+
+  const stale = new Set();
+  stale.add('CHANGELOG_SUMMARY.md'); // always
+  for (const p of allPaths) {
+    for (const rule of RULES) {
+      if (rule.match.test(p)) stale.add(rule.doc);
+    }
+  }
+
+  console.log('\nLikely-stale Buddy docs:');
+  for (const doc of stale) console.log(`   .buddy/${doc}`);
+
+  console.log('\n💡 In Copilot CLI: ask Buddy "update buddy for my changes".');
+}

package/src/commands/status.js

@@ -0,0 +1,49 @@
+import { findRepoRoot, buddyDir, isDir } from '../lib/paths.js';
+import { readManifest } from '../lib/manifest.js';
+import { hasGit, headCommit, changedFilesSince } from '../lib/git.js';
+
+export async function statusCommand() {
+  const repoRoot = findRepoRoot();
+  const buddy = buddyDir(repoRoot);
+
+  if (!isDir(buddy)) {
+    console.log('❌ No .buddy/ in this repo. Run "buddy init".');
+    return;
+  }
+
+  const manifest = readManifest(buddy);
+  if (!manifest) {
+    console.log('⚠️  .buddy/ exists but manifest.json is missing or unreadable.');
+    return;
+  }
+
+  console.log(`📦 Buddy at ${buddy}`);
+  console.log(`   Last run:           ${manifest.last_run_timestamp || '(never)'}`);
+  console.log(`   Last indexed commit: ${manifest.last_indexed_commit || '(none)'}`);
+
+  if (!hasGit(repoRoot)) {
+    console.log('   (No git in this repo — skipping diff.)');
+    return;
+  }
+
+  const head = headCommit(repoRoot);
+  console.log(`   Current HEAD:        ${head ? head.slice(0, 8) : '(unknown)'}`);
+
+  if (!manifest.last_indexed_commit) {
+    console.log('\n💡 Buddy has never indexed this repo. Ask Buddy in Copilot CLI: "scan this repo".');
+    return;
+  }
+
+  if (head === manifest.last_indexed_commit) {
+    console.log('\n✅ .buddy/ is current with HEAD.');
+    return;
+  }
+
+  const changes = changedFilesSince(manifest.last_indexed_commit, repoRoot);
+  console.log(`\n🔍 ${changes.length} file(s) changed since last index:`);
+  for (const c of changes.slice(0, 20)) {
+    console.log(`   ${c.status}  ${c.path}`);
+  }
+  if (changes.length > 20) console.log(`   …and ${changes.length - 20} more`);
+  console.log('\n💡 In Copilot CLI: ask Buddy "update buddy for my changes".');
+}

package/src/lib/git.js

@@ -0,0 +1,40 @@
+import { execFileSync } from 'node:child_process';
+
+function runGit(args, cwd) {
+  try {
+    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function hasGit(cwd) {
+  return runGit(['rev-parse', '--is-inside-work-tree'], cwd) === 'true';
+}
+
+export function headCommit(cwd) {
+  return runGit(['rev-parse', 'HEAD'], cwd);
+}
+
+export function changedFilesSince(commit, cwd) {
+  if (!commit) return [];
+  const out = runGit(['diff', '--name-status', `${commit}..HEAD`], cwd);
+  if (!out) return [];
+  return out
+    .split('\n')
+    .map((line) => {
+      const parts = line.split('\t');
+      if (parts.length < 2) return null;
+      return { status: parts[0].trim(), path: parts.slice(1).join('\t').trim() };
+    })
+    .filter(Boolean);
+}
+
+export function workingTreeChanges(cwd) {
+  const out = runGit(['status', '--porcelain'], cwd);
+  if (!out) return [];
+  return out.split('\n').map((line) => ({
+    status: line.slice(0, 2).trim(),
+    path: line.slice(3).trim(),
+  }));
+}

package/src/lib/index.js

@@ -0,0 +1,6 @@
+export * from './paths.js';
+export * from './git.js';
+export * from './redact.js';
+export * from './manifest.js';
+export * from './opener.js';
+export * from './scaffold.js';

package/src/lib/manifest.js

@@ -0,0 +1,32 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function manifestPath(buddyRoot) {
+  return join(buddyRoot, 'manifest.json');
+}
+
+export function readManifest(buddyRoot) {
+  const p = manifestPath(buddyRoot);
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeManifest(buddyRoot, manifest) {
+  const p = manifestPath(buddyRoot);
+  writeFileSync(p, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+}
+
+export function defaultManifest() {
+  return {
+    schema_version: 1,
+    last_indexed_commit: null,
+    last_run_timestamp: new Date().toISOString(),
+    files_scanned_count: 0,
+    key_outputs_updated: [],
+    last_link_update_timestamp: null,
+  };
+}

package/src/lib/opener.js

@@ -0,0 +1,44 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { platform } from 'node:os';
+
+// Open a file with the OS default app (or $EDITOR/$VISUAL when set).
+// Returns { opened: boolean, command: string|null, reason: string|null }.
+export function openFile(filePath, { silent = false } = {}) {
+  if (process.env.BUDDY_NO_OPEN === '1') {
+    return { opened: false, command: null, reason: 'BUDDY_NO_OPEN=1' };
+  }
+
+  if (!existsSync(filePath)) {
+    return { opened: false, command: null, reason: `File not found: ${filePath}` };
+  }
+
+  const editor = process.env.VISUAL || process.env.EDITOR;
+  if (editor) {
+    return launch(editor, [filePath], silent);
+  }
+
+  const p = platform();
+  if (p === 'win32') {
+    // Use cmd /c start so we don't block. Empty string is the window title.
+    return launch('cmd', ['/c', 'start', '', filePath], silent);
+  }
+  if (p === 'darwin') {
+    return launch('open', [filePath], silent);
+  }
+  return launch('xdg-open', [filePath], silent);
+}
+
+function launch(cmd, args, silent) {
+  try {
+    const child = spawn(cmd, args, {
+      detached: true,
+      stdio: silent ? 'ignore' : 'inherit',
+      shell: false,
+    });
+    child.unref();
+    return { opened: true, command: `${cmd} ${args.join(' ')}`, reason: null };
+  } catch (err) {
+    return { opened: false, command: cmd, reason: err.message };
+  }
+}