viepilot 1.3.1 → 1.8.0

package/lib/viepilot-info.cjs

@@ -0,0 +1,196 @@
+/**
+ * ViePilot bundle metadata for `vp-tools info` (FEAT-008).
+ * Resolves the viepilot package root from the CLI location — no `.viepilot/` project required.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+/**
+ * Walk upward from startDir (and optionally cwd) for package.json with name "viepilot".
+ * @param {string} startDir - e.g. path.join(__dirname, '..') from bin/vp-tools.cjs
+ * @returns {string|null} absolute package root or null
+ */
+function resolveViepilotPackageRoot(startDir) {
+  const tryRoots = [path.resolve(startDir), path.resolve(process.cwd())];
+  const seen = new Set();
+  for (const base of tryRoots) {
+    if (seen.has(base)) continue;
+    seen.add(base);
+    let dir = base;
+    while (dir && dir !== path.dirname(dir)) {
+      const pkgPath = path.join(dir, 'package.json');
+      if (fs.existsSync(pkgPath)) {
+        try {
+          const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+          if (pkg && pkg.name === 'viepilot') {
+            return dir;
+          }
+        } catch (_e) {
+          /* ignore */
+        }
+      }
+      dir = path.dirname(dir);
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} root - viepilot package root
+ * @returns {string|null}
+ */
+function readInstalledVersion(root) {
+  const pkgPath = path.join(root, 'package.json');
+  if (!fs.existsSync(pkgPath)) return null;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    return pkg.version || null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Query npm registry for latest published version (requires network + npm on PATH).
+ * @returns {{ ok: true, version: string } | { ok: false, error: string }}
+ */
+function fetchLatestNpmVersion() {
+  try {
+    const out = execFileSync('npm', ['view', 'viepilot', 'version', '--json'], {
+      encoding: 'utf8',
+      timeout: 15000,
+      windowsHide: true,
+    }).trim();
+    const parsed = JSON.parse(out);
+    const version = typeof parsed === 'string' ? parsed : String(parsed);
+    return { ok: true, version };
+  } catch (e) {
+    return { ok: false, error: e.message || String(e) };
+  }
+}
+
+/**
+ * Parse `version:` from YAML-like frontmatter (first --- block).
+ * @param {string} content
+ * @returns {string}
+ */
+function parseSkillFileVersion(content) {
+  if (typeof content !== 'string' || !content.startsWith('---')) {
+    return 'unspecified';
+  }
+  const end = content.indexOf('\n---', 3);
+  if (end === -1) {
+    return 'unspecified';
+  }
+  const block = content.slice(3, end);
+  const m = block.match(/^version:\s*["']?([^"'\r\n]+)["']?/m);
+  return m ? m[1].trim() : 'unspecified';
+}
+
+/**
+ * @param {string} root - viepilot package root
+ * @returns {Array<{ id: string, version: string, relativePath: string }>}
+ */
+function listSkillsWithVersions(root) {
+  const skillsDir = path.join(root, 'skills');
+  if (!fs.existsSync(skillsDir)) {
+    return [];
+  }
+  const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+  const out = [];
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    const skillFile = path.join(skillsDir, ent.name, 'SKILL.md');
+    if (!fs.existsSync(skillFile)) continue;
+    const content = fs.readFileSync(skillFile, 'utf8');
+    out.push({
+      id: ent.name,
+      version: parseSkillFileVersion(content),
+      relativePath: path.join('skills', ent.name, 'SKILL.md').replace(/\\/g, '/'),
+    });
+  }
+  out.sort((a, b) => a.id.localeCompare(b.id));
+  return out;
+}
+
+const WORKFLOW_SEMVER_NOTE = 'no semver in workflow markdown';
+
+/**
+ * @param {string} root
+ * @returns {Array<{ id: string, relativePath: string, semverInFile: null, note: string }>}
+ */
+function listWorkflows(root) {
+  const wfDir = path.join(root, 'workflows');
+  if (!fs.existsSync(wfDir)) {
+    return [];
+  }
+  const files = fs
+    .readdirSync(wfDir)
+    .filter((f) => f.endsWith('.md'))
+    .sort((a, b) => a.localeCompare(b));
+  return files.map((f) => ({
+    id: f.replace(/\.md$/i, ''),
+    relativePath: path.join('workflows', f).replace(/\\/g, '/'),
+    semverInFile: null,
+    note: WORKFLOW_SEMVER_NOTE,
+  }));
+}
+
+/**
+ * @param {string} root
+ * @returns {string|null}
+ */
+function tryGitHead(root) {
+  try {
+    return execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: root,
+      encoding: 'utf8',
+      timeout: 8000,
+      windowsHide: true,
+    }).trim();
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * @param {string} root
+ * @param {{ includeLatestNpm?: boolean }} [options]
+ */
+function buildInfoReport(root, options = {}) {
+  const includeLatestNpm = options.includeLatestNpm !== false;
+  const installedVersion = readInstalledVersion(root);
+  let pkgName = 'viepilot';
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    if (pkg.name) pkgName = pkg.name;
+  } catch (_e) {
+    /* keep default */
+  }
+
+  const report = {
+    packageRoot: root,
+    packageName: pkgName,
+    installedVersion: installedVersion || 'unknown',
+    latestNpm: includeLatestNpm ? fetchLatestNpmVersion() : { ok: false, error: 'skipped' },
+    gitHead: tryGitHead(root),
+    skills: listSkillsWithVersions(root),
+    workflows: listWorkflows(root),
+  };
+
+  return report;
+}
+
+module.exports = {
+  resolveViepilotPackageRoot,
+  readInstalledVersion,
+  fetchLatestNpmVersion,
+  parseSkillFileVersion,
+  listSkillsWithVersions,
+  listWorkflows,
+  tryGitHead,
+  buildInfoReport,
+  WORKFLOW_SEMVER_NOTE,
+};

package/lib/viepilot-install.cjs

@@ -0,0 +1,427 @@
+/**
+ * ViePilot filesystem install plan — Node implementation (ENH-017 / Phase 28).
+ * Mirrors install.sh steps as a structured plan for dry-run and (later) execution.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { resolveViepilotPackageRoot } = require('./viepilot-info.cjs');
+
+/**
+ * @param {Record<string, string | undefined>} [envSource]
+ * @returns {{ autoYes: boolean, profile: string, addPath: boolean, symlinkSkills: boolean }}
+ */
+function normalizeInstallEnv(envSource = process.env) {
+  return {
+    autoYes: envSource.VIEPILOT_AUTO_YES === '1',
+    profile: envSource.VIEPILOT_INSTALL_PROFILE || 'cursor-ide',
+    addPath: envSource.VIEPILOT_ADD_PATH === '1',
+    symlinkSkills: envSource.VIEPILOT_SYMLINK_SKILLS === '1',
+  };
+}
+
+/**
+ * Same guard as install.sh: README.md + skills/ directory.
+ * @param {string} root - viepilot package root
+ */
+function validateViepilotPackageRoot(root) {
+  const readme = path.join(root, 'README.md');
+  const skillsDir = path.join(root, 'skills');
+  if (!fs.existsSync(readme)) {
+    const err = new Error('Please run this from the viepilot package root (README.md missing)');
+    err.code = 'VIEPILOT_LAYOUT';
+    throw err;
+  }
+  if (!fs.existsSync(skillsDir) || !fs.statSync(skillsDir).isDirectory()) {
+    const err = new Error('Please run this from the viepilot package root (skills/ missing)');
+    err.code = 'VIEPILOT_LAYOUT';
+    throw err;
+  }
+}
+
+/**
+ * @param {string} packageRoot
+ * @returns {string[]}
+ */
+function listSkillDirNames(packageRoot) {
+  const skillsDir = path.join(packageRoot, 'skills');
+  return fs
+    .readdirSync(skillsDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name);
+}
+
+/**
+ * @param {string} packageRoot
+ * @param {string} subdir - relative to package root
+ */
+function listDirEntries(packageRoot, subdir) {
+  const full = path.join(packageRoot, subdir);
+  if (!fs.existsSync(full)) return [];
+  return fs.readdirSync(full, { withFileTypes: true });
+}
+
+/**
+ * Build an ordered install plan (no I/O besides reading source tree layout).
+ *
+ * @param {string} packageRoot - absolute viepilot package root
+ * @param {Record<string, string | undefined>} [envSource] - defaults to process.env
+ * @param {{ wantPathShim?: boolean, overrideHomedir?: string }} [opts] - `overrideHomedir`: absolute fake home for tests only. `wantPathShim`: append /usr/local/bin steps (skipped on Windows at apply time).
+ * @returns {{ version: number, packageRoot: string, env: ReturnType<typeof normalizeInstallEnv>, home: string, paths: object, steps: object[] }}
+ */
+function buildInstallPlan(packageRoot, envSource = process.env, opts = {}) {
+  const root = path.resolve(packageRoot);
+  validateViepilotPackageRoot(root);
+  const env = normalizeInstallEnv(envSource);
+  const home =
+    opts.overrideHomedir != null ? path.resolve(opts.overrideHomedir) : os.homedir();
+  const cursorSkillsDir = path.join(home, '.cursor', 'skills');
+  const viepilotDir = path.join(home, '.cursor', 'viepilot');
+
+  let wantPathShim = opts.wantPathShim;
+  if (wantPathShim === undefined) {
+    wantPathShim = env.autoYes && env.addPath;
+  }
+
+  /** @type {object[]} */
+  const steps = [];
+
+  const mkdirTargets = [
+    cursorSkillsDir,
+    path.join(viepilotDir, 'workflows'),
+    path.join(viepilotDir, 'templates', 'project'),
+    path.join(viepilotDir, 'templates', 'phase'),
+    path.join(viepilotDir, 'bin'),
+    path.join(viepilotDir, 'lib'),
+    path.join(viepilotDir, 'ui-components'),
+  ];
+  for (const dir of mkdirTargets) {
+    steps.push({ kind: 'mkdir', path: dir });
+  }
+
+  for (const name of listSkillDirNames(root)) {
+    const src = path.join(root, 'skills', name);
+    const dest = path.join(cursorSkillsDir, name);
+    if (env.symlinkSkills) {
+      steps.push({
+        kind: 'symlink_dir',
+        target: dest,
+        sourceAbsolute: path.resolve(src),
+      });
+    } else {
+      steps.push({ kind: 'copy_dir', from: src, to: dest });
+    }
+  }
+
+  for (const ent of listDirEntries(root, 'workflows')) {
+    const src = path.join(root, 'workflows', ent.name);
+    const dest = path.join(viepilotDir, 'workflows', ent.name);
+    if (ent.isDirectory()) {
+      steps.push({ kind: 'copy_dir', from: src, to: dest });
+    } else if (ent.isFile()) {
+      steps.push({ kind: 'copy_file', from: src, to: dest });
+    }
+  }
+
+  for (const ent of listDirEntries(root, path.join('templates', 'project'))) {
+    const src = path.join(root, 'templates', 'project', ent.name);
+    const dest = path.join(viepilotDir, 'templates', 'project', ent.name);
+    if (ent.isDirectory()) {
+      steps.push({ kind: 'copy_dir', from: src, to: dest });
+    } else if (ent.isFile()) {
+      steps.push({ kind: 'copy_file', from: src, to: dest });
+    }
+  }
+
+  for (const ent of listDirEntries(root, path.join('templates', 'phase'))) {
+    const src = path.join(root, 'templates', 'phase', ent.name);
+    const dest = path.join(viepilotDir, 'templates', 'phase', ent.name);
+    if (ent.isDirectory()) {
+      steps.push({ kind: 'copy_dir', from: src, to: dest });
+    } else if (ent.isFile()) {
+      steps.push({ kind: 'copy_file', from: src, to: dest });
+    }
+  }
+
+  const uiRoot = path.join(root, 'ui-components');
+  if (fs.existsSync(uiRoot)) {
+    for (const ent of listDirEntries(root, 'ui-components')) {
+      const src = path.join(root, 'ui-components', ent.name);
+      const dest = path.join(viepilotDir, 'ui-components', ent.name);
+      if (ent.isDirectory()) {
+        steps.push({ kind: 'copy_dir', from: src, to: dest });
+      } else if (ent.isFile()) {
+        steps.push({ kind: 'copy_file', from: src, to: dest });
+      }
+    }
+  }
+
+  const binFiles = ['vp-tools.cjs', 'viepilot.cjs'];
+  for (const f of binFiles) {
+    steps.push({
+      kind: 'copy_file',
+      from: path.join(root, 'bin', f),
+      to: path.join(viepilotDir, 'bin', f),
+    });
+  }
+  steps.push({
+    kind: 'copy_file',
+    from: path.join(root, 'lib', 'cli-shared.cjs'),
+    to: path.join(viepilotDir, 'lib', 'cli-shared.cjs'),
+  });
+
+  for (const f of binFiles) {
+    steps.push({
+      kind: 'chmod',
+      path: path.join(viepilotDir, 'bin', f),
+      mode: 0o755,
+    });
+  }
+
+  steps.push({
+    kind: 'note',
+    id: 'cloc_optional',
+    message:
+      'Check optional cloc for README metrics (brew/apt/dnf/choco); installation continues if missing.',
+  });
+
+  if (wantPathShim) {
+    steps.push({
+      kind: 'path_shim',
+      links: [
+        { path: '/usr/local/bin/vp-tools', target: path.join(viepilotDir, 'bin', 'vp-tools.cjs') },
+        { path: '/usr/local/bin/viepilot', target: path.join(viepilotDir, 'bin', 'viepilot.cjs') },
+      ],
+      note: 'Unix typical; on Windows native, PATH shim may be skipped or manual.',
+    });
+  }
+
+  return {
+    version: 1,
+    packageRoot: root,
+    env,
+    home,
+    paths: {
+      cursorSkillsDir,
+      viepilotDir,
+    },
+    steps,
+  };
+}
+
+/**
+ * Human-readable lines for dry-run output.
+ * @param {ReturnType<typeof buildInstallPlan>} plan
+ * @returns {string[]}
+ */
+function formatPlanLines(plan) {
+  const lines = [];
+  lines.push('ViePilot install plan (dry-run)');
+  lines.push(`  packageRoot: ${plan.packageRoot}`);
+  lines.push(`  profile: ${plan.env.profile} (informational; same file set as install.sh)`);
+  lines.push(`  skills: ${plan.paths.cursorSkillsDir}`);
+  lines.push(`  viepilot: ${plan.paths.viepilotDir}`);
+  lines.push('');
+  for (let i = 0; i < plan.steps.length; i++) {
+    const s = plan.steps[i];
+    const n = i + 1;
+    switch (s.kind) {
+      case 'mkdir':
+        lines.push(`${n}. mkdir -p ${s.path}`);
+        break;
+      case 'copy_file':
+        lines.push(`${n}. copy ${s.from} -> ${s.to}`);
+        break;
+      case 'copy_dir':
+        lines.push(`${n}. copyDir ${s.from} -> ${s.to}`);
+        break;
+      case 'symlink_dir':
+        lines.push(`${n}. symlink ${s.target} -> ${s.sourceAbsolute}`);
+        break;
+      case 'chmod':
+        lines.push(`${n}. chmod ${s.mode.toString(8)} ${s.path}`);
+        break;
+      case 'note':
+        lines.push(`${n}. note: ${s.message}`);
+        break;
+      case 'path_shim':
+        lines.push(`${n}. path shim: ${s.links.map((l) => `${l.path} -> ${l.target}`).join('; ')}`);
+        if (s.note) lines.push(`    (${s.note})`);
+        break;
+      default:
+        lines.push(`${n}. ${JSON.stringify(s)}`);
+    }
+  }
+  return lines;
+}
+
+function removePathIfExists(p) {
+  if (fs.existsSync(p)) {
+    fs.rmSync(p, { recursive: true, force: true });
+  }
+}
+
+function ensureDirForFile(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function copyDirRecursive(src, dest) {
+  removePathIfExists(dest);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  if (typeof fs.cpSync === 'function') {
+    fs.cpSync(src, dest, { recursive: true });
+    return;
+  }
+  fs.mkdirSync(dest, { recursive: true });
+  for (const ent of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, ent.name);
+    const d = path.join(dest, ent.name);
+    if (ent.isDirectory()) {
+      copyDirRecursive(s, d);
+    } else {
+      fs.copyFileSync(s, d);
+    }
+  }
+}
+
+function symlinkSkillDir(sourceAbsolute, target) {
+  removePathIfExists(target);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const linkType = process.platform === 'win32' ? 'dir' : 'dir';
+  fs.symlinkSync(sourceAbsolute, target, linkType);
+}
+
+/**
+ * Same messaging as install.sh install_cloc_best_effort (non-blocking; no interactive install here).
+ * @param {ReturnType<typeof normalizeInstallEnv>} env
+ * @returns {string[]}
+ */
+function getClocGuidanceLines(env) {
+  const lines = [];
+  try {
+    const { execFileSync } = require('child_process');
+    execFileSync('cloc', ['--version'], { stdio: 'ignore' });
+    lines.push('  ✓ cloc detected');
+    return lines;
+  } catch (_e) {
+    /* continue */
+  }
+  lines.push('  cloc not found.');
+  lines.push('  README metric auto-sync can still run with fallback, but LOC refresh will be skipped.');
+  lines.push('  Suggested install:');
+  lines.push('    - macOS: brew install cloc');
+  lines.push('    - Ubuntu/Debian: sudo apt-get install -y cloc');
+  lines.push('    - Windows: choco install cloc');
+  if (!env.autoYes) {
+    lines.push('  (Interactive cloc install omitted in Node installer; set AUTO_YES and use OS package manager.)');
+  }
+  return lines;
+}
+
+/**
+ * Apply install plan to disk (or dry-run log only).
+ *
+ * @param {ReturnType<typeof buildInstallPlan>} plan
+ * @param {{ dryRun?: boolean }} [options]
+ * @returns {{ ok: boolean, logs: string[], errors: { step: object, error: Error }[] }}
+ */
+function applyInstallPlan(plan, options = {}) {
+  const dryRun = !!options.dryRun;
+  /** @type {string[]} */
+  const logs = [];
+  /** @type {{ step: object, error: Error }[]} */
+  const errors = [];
+
+  for (const step of plan.steps) {
+    try {
+      switch (step.kind) {
+        case 'mkdir':
+          if (dryRun) logs.push(`[dry-run] mkdir -p ${step.path}`);
+          else fs.mkdirSync(step.path, { recursive: true });
+          break;
+        case 'copy_file':
+          if (dryRun) logs.push(`[dry-run] copy ${step.from} -> ${step.to}`);
+          else {
+            if (!fs.existsSync(step.from)) {
+              throw new Error(`Missing source: ${step.from}`);
+            }
+            ensureDirForFile(step.to);
+            fs.copyFileSync(step.from, step.to);
+          }
+          break;
+        case 'copy_dir':
+          if (dryRun) logs.push(`[dry-run] copyDir ${step.from} -> ${step.to}`);
+          else {
+            if (!fs.existsSync(step.from)) {
+              throw new Error(`Missing source dir: ${step.from}`);
+            }
+            copyDirRecursive(step.from, step.to);
+          }
+          break;
+        case 'symlink_dir':
+          if (dryRun) {
+            logs.push(`[dry-run] symlink ${step.target} -> ${step.sourceAbsolute}`);
+          } else {
+            symlinkSkillDir(step.sourceAbsolute, step.target);
+          }
+          break;
+        case 'chmod':
+          if (dryRun) logs.push(`[dry-run] chmod ${step.mode.toString(8)} ${step.path}`);
+          else {
+            try {
+              fs.chmodSync(step.path, step.mode);
+            } catch (e) {
+              logs.push(`chmod skipped: ${step.path} (${e.message})`);
+            }
+          }
+          break;
+        case 'note':
+          if (step.id === 'cloc_optional') {
+            logs.push(...getClocGuidanceLines(plan.env));
+          } else {
+            logs.push(`note: ${step.message}`);
+          }
+          break;
+        case 'path_shim':
+          if (process.platform === 'win32') {
+            logs.push('path_shim: skipped on Windows (add ~/.cursor/viepilot/bin to PATH manually if needed).');
+            break;
+          }
+          if (dryRun) {
+            logs.push(`[dry-run] path_shim: ${step.links.map((l) => `${l.path} -> ${l.target}`).join('; ')}`);
+            break;
+          }
+          for (const L of step.links) {
+            try {
+              removePathIfExists(L.path);
+              fs.mkdirSync(path.dirname(L.path), { recursive: true });
+              fs.symlinkSync(L.target, L.path, 'file');
+              logs.push(`path_shim: ${L.path} -> ${L.target}`);
+            } catch (e) {
+              logs.push(`path_shim failed ${L.path}: ${e.message} (try sudo or adjust permissions)`);
+            }
+          }
+          break;
+        default:
+          logs.push(`unknown step kind: ${JSON.stringify(step)}`);
+      }
+    } catch (e) {
+      errors.push({ step, error: e });
+      return { ok: false, logs, errors };
+    }
+  }
+
+  return { ok: true, logs, errors };
+}
+
+module.exports = {
+  resolveViepilotPackageRoot,
+  normalizeInstallEnv,
+  validateViepilotPackageRoot,
+  listSkillDirNames,
+  buildInstallPlan,
+  formatPlanLines,
+  applyInstallPlan,
+  getClocGuidanceLines,
+};