@chenguangyao/devflow-kit 0.1.43

package/src/cli/commands/skills.js

@@ -0,0 +1,457 @@
+'use strict';
+const fs = require('fs/promises');
+const fsSync = require('fs');
+const path = require('path');
+const log = require('../../utils/log.js');
+
+const SKILLS_DIR = path.join(__dirname, '..', '..', '..', 'skills');
+
+/**
+ * NAMESPACE — every skill we ship is grouped under this folder so the IDE
+ * skill directory stays tidy:
+ *
+ *   ~/.cursor/skills/
+ *   ├── devflow-kit/        ← symlink to ~/.devflow/skills/devflow-kit for user installs
+ *   │   ├── apply/SKILL.md
+ *   │   ├── archive/SKILL.md
+ *   │   └── ...
+ *   └── superpowers/        ← unrelated 3rd-party skills, untouched
+ *
+ * Cursor & Claude Code both walk subdirectories looking for SKILL.md, so
+ * nesting one level deeper is transparent at runtime.
+ *
+ * The set of ALL skill directory names we ship — used by both userSkillsInstalled
+ * (probe) and the legacy migration path. Keep in sync with skills/ folder.
+ */
+const NAMESPACE = 'devflow-kit';
+const USER_SKILLS_SOURCE = '~/.devflow/skills/devflow-kit';
+const SHIPPED_SKILLS = [
+  'apply',
+  'archive',
+  'brainstorm',
+  'ci-fix',
+  'code-review',
+  'complexity-grading',
+  'deliver',
+  'dependency-upgrade',
+  'df-orchestrator',
+  'frontend-quality',
+  'handoff-resume',
+  'plan',
+  'requirement-analysis',
+  'security-hardening',
+  'tech-spec',
+  'test-spec',
+  'verify',
+];
+
+const PROJECT_TARGET_MAP = {
+  claude:    '.claude/skills',
+  cursor:    '.cursor/skills',
+  agents:    '.agents/skills',
+  cwd:       'skills',
+};
+
+const USER_TARGET_MAP = {
+  'claude-user': '~/.claude/skills',
+  'cursor-user': '~/.cursor/skills',
+  'agents-user': '~/.agents/skills',
+};
+
+const TARGET_MAP = { ...PROJECT_TARGET_MAP, ...USER_TARGET_MAP, user: '~/.claude/skills' };
+
+const USER_SCOPE_TARGETS = ['cursor-user', 'claude-user', 'agents-user'];
+const OWNERSHIP_MARKER = '.devflow-skill';
+const DEVFLOW_OWNED_RE = /\bdevflow(?:-kit)?\b|\/df:|`devflow\b/i;
+
+function expand(p) {
+  return p.startsWith('~') ? path.join(process.env.HOME || '', p.slice(1)) : p;
+}
+
+function displayPath(root, dest, absolute) {
+  if (typeof dest === 'string' && dest.startsWith('~')) {
+    const tail = absolute.slice(expand(dest).length);
+    return dest + tail;
+  }
+  return path.relative(root, absolute) || absolute;
+}
+
+/**
+ * Detect whether user-wide skills are already present.
+ *
+ * Probes both layouts (older flat installs from 0.1.x, and current namespaced
+ * installs) so existing users aren't told they have nothing installed just
+ * because the layout changed.
+ */
+function userSkillsInstalled() {
+  return USER_SCOPE_TARGETS.every((k) => {
+    const root = expand(TARGET_MAP[k]);
+    return (
+      fsSync.existsSync(path.join(root, NAMESPACE, 'df-orchestrator', 'SKILL.md')) ||
+      fsSync.existsSync(path.join(root, 'df-orchestrator', 'SKILL.md'))
+    );
+  });
+}
+
+/**
+ * Detect a legacy flat install (skills sitting at the root of `parent`).
+ * Returns the list of shipped skills found at the flat layer.
+ */
+function detectLegacyFlat(parent) {
+  if (!fsSync.existsSync(parent)) return [];
+  return SHIPPED_SKILLS.filter((name) =>
+    isDevflowOwnedFlatSkill(parent, name)
+  );
+}
+
+function isDevflowOwnedFlatSkill(parent, name) {
+  const dir = path.join(parent, name);
+  const skillFile = path.join(dir, 'SKILL.md');
+  if (!fsSync.existsSync(skillFile)) return false;
+  if (fsSync.existsSync(path.join(dir, OWNERSHIP_MARKER))) return true;
+
+  try {
+    const body = fsSync.readFileSync(skillFile, 'utf8');
+    return DEVFLOW_OWNED_RE.test(body);
+  } catch (_) {
+    return false;
+  }
+}
+
+/**
+ * Move a flat install into the namespace folder. Conservative:
+ *  - Only touches directories whose names are in SHIPPED_SKILLS.
+ *  - Refuses to overwrite a pre-existing namespace dir (safer to delete first).
+ */
+async function migrateFlatToNamespace(parent, { quiet = false } = {}) {
+  const flat = detectLegacyFlat(parent);
+  if (!flat.length) return { moved: 0, skills: [] };
+  const nsRoot = path.join(parent, NAMESPACE);
+  await fs.mkdir(nsRoot, { recursive: true });
+  let moved = 0;
+  for (const name of flat) {
+    const from = path.join(parent, name);
+    const to = path.join(nsRoot, name);
+    if (fsSync.existsSync(to)) {
+      // Namespace already has this skill — drop the flat copy to dedupe
+      await fs.rm(from, { recursive: true, force: true });
+      if (!quiet) log.dim(`migrated: ${name} (already in ${NAMESPACE}, removed flat copy)`);
+    } else {
+      await fs.rename(from, to);
+      await writeOwnershipMarker(to);
+      if (!quiet) log.ok(`migrated: ${name} → ${NAMESPACE}/${name}`);
+    }
+    moved++;
+  }
+  return { moved, skills: flat };
+}
+
+async function run({ sub, flags = {}, positional = [], cwd }) {
+  const action = sub || positional[0] || 'install';
+  if (action === 'list') {
+    const entries = await fs.readdir(SKILLS_DIR, { withFileTypes: true });
+    for (const e of entries) {
+      if (e.isDirectory()) log.raw(`  - ${e.name}`);
+    }
+    return;
+  }
+  if (action === 'status') return runStatus();
+  if (action === 'uninstall') return runUninstall(flags);
+  if (action === 'migrate') return runMigrate(flags);
+  if (action !== 'install') {
+    log.error('usage: devflow skills <install|status|uninstall|migrate> [--scope=user|project] [--target=<...>]');
+    process.exitCode = 2; return;
+  }
+
+  const root = cwd || process.cwd();
+  const scope = flags.scope;
+
+  let targetKeys;
+  if (flags.target) {
+    targetKeys = String(flags.target).split(',').map((s) => s.trim()).filter(Boolean);
+  } else if (scope === 'user') {
+    targetKeys = USER_SCOPE_TARGETS;
+  } else if (scope === 'project') {
+    targetKeys = ['cursor', 'claude', 'agents'];
+  } else {
+    targetKeys = ['cursor', 'claude', 'agents'];
+  }
+
+  const dests = [];
+  if (flags.dest) {
+    dests.push({ key: '(custom)', dest: flags.dest });
+  } else {
+    for (const k of targetKeys) {
+      const d = TARGET_MAP[k];
+      if (!d) { log.error(`unknown target: ${k}`); process.exitCode = 2; return; }
+      dests.push({ key: k, dest: d });
+    }
+  }
+
+  const linkMode = !flags.copy && (scope === 'user' || targetKeys.some((k) => k.endsWith('-user')))
+    ? 'central'
+    : 'copy';
+  const summary = await installToDests(root, dests, { quiet: flags.quiet, linkMode });
+  for (const s of summary) log.info(`${s.count} skills → ${s.path}`);
+
+  if (scope === 'user' || targetKeys.some((k) => k.endsWith('-user'))) {
+    log.raw('');
+    if (linkMode === 'central') {
+      log.dim(`user-wide install complete. skills are stored once at ${USER_SKILLS_SOURCE} and linked into IDE dirs.`);
+    } else {
+      log.dim('user-wide install complete. you can now run `devflow init` in any repo without re-installing skills.');
+    }
+  }
+}
+
+async function runStatus() {
+  log.raw('skill installation status:');
+  const checks = [];
+  for (const [key, p] of Object.entries(TARGET_MAP)) {
+    if (key === 'cwd' || key === 'user') continue;
+    const parent = expand(p);
+    const nsRoot = path.join(parent, NAMESPACE);
+    const ns = fsSync.existsSync(path.join(nsRoot, 'df-orchestrator', 'SKILL.md'));
+    const flat = fsSync.existsSync(path.join(parent, 'df-orchestrator', 'SKILL.md'));
+    const linked = ns && isSymlink(nsRoot);
+    const layout = ns ? `${NAMESPACE}/${linked ? ` -> ${fsSync.readlinkSync(nsRoot)}` : ''}` : (flat ? '(flat — legacy)' : '');
+    checks.push({ key, path: parent, exists: ns || flat, layout });
+  }
+  for (const c of checks) {
+    const tag = c.exists ? '[ok]' : '[ — ]';
+    const layoutStr = c.layout ? `  ${c.layout}` : '';
+    log.raw(`  ${tag.padEnd(6)} ${c.key.padEnd(14)} ${c.path}${layoutStr}`);
+  }
+  log.raw('');
+  if (userSkillsInstalled()) {
+    log.ok('user-wide skills detected — `devflow init` will skip per-project skill copy.');
+    // Surface migration recommendation if any flat layout was detected
+    const anyFlat = checks.some((c) => c.exists && c.layout.includes('legacy'));
+    if (anyFlat) {
+      log.warn(`legacy flat layout detected; run \`devflow skills migrate --scope=user\` to consolidate into ${NAMESPACE}/`);
+    }
+  } else {
+    log.dim('user-wide skills NOT installed. recommend: `devflow skills install --scope=user` (one-time).');
+  }
+}
+
+async function runUninstall(flags) {
+  const scope = flags.scope || 'user';
+  const targetKeys = scope === 'user' ? USER_SCOPE_TARGETS : ['cursor', 'claude', 'agents'];
+  const root = process.cwd();
+  for (const k of targetKeys) {
+    const dest = TARGET_MAP[k];
+    if (!dest) continue;
+    const parent = dest.startsWith('~') ? expand(dest) : path.resolve(root, dest);
+    if (!fsSync.existsSync(parent)) { log.dim(`${k}: not present (skip)`); continue; }
+
+    const nsDir = path.join(parent, NAMESPACE);
+    const removedNs = fsSync.existsSync(nsDir) || isSymlink(nsDir);
+    if (removedNs) await removePath(nsDir);
+
+    let removedFlat = 0;
+    for (const name of SHIPPED_SKILLS) {
+      const flatDir = path.join(parent, name);
+      if (fsSync.existsSync(flatDir)) {
+        await fs.rm(flatDir, { recursive: true, force: true });
+        removedFlat++;
+      }
+    }
+    if (removedNs || removedFlat) {
+      const parts = [];
+      if (removedNs) parts.push(`${NAMESPACE}/`);
+      if (removedFlat) parts.push(`${removedFlat} flat skill(s)`);
+      log.ok(`removed: ${k} → ${parent} (${parts.join(' + ')})`);
+    } else {
+      log.dim(`${k}: nothing to remove`);
+    }
+  }
+  if (scope === 'user') {
+    const central = expand(USER_SKILLS_SOURCE);
+    const removedCentral = fsSync.existsSync(central) || isSymlink(central);
+    if (removedCentral) {
+      await removePath(central);
+      log.ok(`removed: central skills → ${central}`);
+    }
+  }
+}
+
+async function runMigrate(flags) {
+  const scope = flags.scope || 'user';
+  const targetKeys = scope === 'user' ? USER_SCOPE_TARGETS : ['cursor', 'claude', 'agents'];
+  const root = process.cwd();
+  let totalMoved = 0;
+  for (const k of targetKeys) {
+    const dest = TARGET_MAP[k];
+    if (!dest) continue;
+    const parent = dest.startsWith('~') ? expand(dest) : path.resolve(root, dest);
+    if (!fsSync.existsSync(parent)) { log.dim(`${k}: parent dir not present (skip)`); continue; }
+    const flat = detectLegacyFlat(parent);
+    if (!flat.length) { log.dim(`${k}: no legacy flat skills under ${parent} (skip)`); continue; }
+    log.info(`${k}: migrating ${flat.length} flat skill(s) under ${parent} → ${NAMESPACE}/`);
+    const { moved } = await migrateFlatToNamespace(parent, { quiet: flags.quiet });
+    totalMoved += moved;
+  }
+  if (totalMoved === 0) {
+    log.dim('nothing to migrate.');
+  } else {
+    log.ok(`migration complete: ${totalMoved} skill(s) moved into ${NAMESPACE}/`);
+  }
+}
+
+/**
+ * Install all shipped skills into each destination, grouped under NAMESPACE.
+ *
+ * If a destination already has a flat (legacy) layout, auto-migrate it first
+ * so users don't end up with duplicate skills (one flat + one namespaced).
+ *
+ * linkMode:
+ *  - copy:    each destination gets a real namespace directory
+ *  - central: skills are copied once into ~/.devflow/skills/devflow-kit and
+ *             every destination namespace becomes a symlink to that source
+ */
+async function installToDests(root, dests, { quiet = false, linkMode = 'copy' } = {}) {
+  const entries = (await fs.readdir(SKILLS_DIR, { withFileTypes: true }))
+    .filter((e) => e.isDirectory());
+  const useCentral = linkMode === 'central';
+  const centralDir = expand(USER_SKILLS_SOURCE);
+  let centralCount = entries.length;
+  if (useCentral) {
+    centralCount = await copyShippedSkills(centralDir, entries);
+  }
+
+  const out = [];
+  for (const { key, dest } of dests) {
+    const parent = dest.startsWith('~')
+      ? expand(dest)
+      : path.resolve(root, dest);
+    await fs.mkdir(parent, { recursive: true });
+
+    // Auto-migrate flat → namespace before installing fresh, to avoid duplicates
+    if (detectLegacyFlat(parent).length) {
+      if (!quiet) log.warn(`flat layout detected under ${displayPath(root, dest, parent)} — auto-migrating into ${NAMESPACE}/`);
+      await migrateFlatToNamespace(parent, { quiet });
+    }
+
+    const nsDir = path.join(parent, NAMESPACE);
+    if (useCentral) {
+      const linked = await replaceWithSymlink(nsDir, centralDir);
+      if (!quiet) {
+        const action = linked ? 'skill-link' : 'skill-copy';
+        log.ok(`${action}: ${displayPath(root, dest, nsDir)} → ${centralDir}`);
+      }
+      out.push({ key, path: displayPath(root, dest, nsDir), count: centralCount, linked });
+      continue;
+    }
+
+    if (isSymlink(nsDir)) await fs.unlink(nsDir);
+    await fs.mkdir(nsDir, { recursive: true });
+
+    let count = 0;
+    for (const e of entries) {
+      const src = path.join(SKILLS_DIR, e.name);
+      const dst = path.join(nsDir, e.name);
+      await copyDir(src, dst);
+      await writeOwnershipMarker(dst);
+      count++;
+      if (!quiet) log.ok(`skill: ${e.name} → ${displayPath(root, dest, dst)}`);
+    }
+    out.push({ key, path: displayPath(root, dest, nsDir), count });
+  }
+  return out;
+}
+
+async function installForInit(root, targets, { quiet = false } = {}) {
+  const dests = targets
+    .map((k) => ({ key: k, dest: TARGET_MAP[k] }))
+    .filter((x) => !!x.dest);
+  if (!dests.length) return [];
+  return installToDests(root, dests, { quiet, linkMode: 'copy' });
+}
+
+async function copyShippedSkills(dst, entries) {
+  const tmp = `${dst}.tmp-${process.pid}-${Date.now()}`;
+  await fs.rm(tmp, { recursive: true, force: true });
+  await fs.mkdir(tmp, { recursive: true });
+
+  let count = 0;
+  for (const e of entries) {
+    const src = path.join(SKILLS_DIR, e.name);
+    const skillDst = path.join(tmp, e.name);
+    await copyDir(src, skillDst);
+    await writeOwnershipMarker(skillDst);
+    count++;
+  }
+  await fs.writeFile(path.join(tmp, OWNERSHIP_MARKER), 'devflow-kit\n');
+
+  await removePath(dst);
+  await fs.mkdir(path.dirname(dst), { recursive: true });
+  await fs.rename(tmp, dst);
+  return count;
+}
+
+async function replaceWithSymlink(target, source) {
+  await removePath(target);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  try {
+    await fs.symlink(source, target, process.platform === 'win32' ? 'junction' : 'dir');
+    return true;
+  } catch (_) {
+    await copyDir(source, target);
+    return false;
+  }
+}
+
+async function removePath(p) {
+  let st;
+  try {
+    st = await fs.lstat(p);
+  } catch (_) {
+    return;
+  }
+  if (st.isSymbolicLink()) {
+    await fs.unlink(p);
+  } else {
+    await fs.rm(p, { recursive: true, force: true });
+  }
+}
+
+function isSymlink(p) {
+  try {
+    return fsSync.lstatSync(p).isSymbolicLink();
+  } catch (_) {
+    return false;
+  }
+}
+
+async function copyDir(src, dst) {
+  await fs.mkdir(dst, { recursive: true });
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  for (const e of entries) {
+    const s = path.join(src, e.name);
+    const d = path.join(dst, e.name);
+    if (e.isDirectory()) await copyDir(s, d);
+    else await fs.copyFile(s, d);
+  }
+}
+
+async function writeOwnershipMarker(dir) {
+  await fs.writeFile(path.join(dir, OWNERSHIP_MARKER), 'devflow-kit\n');
+}
+
+module.exports = {
+  run,
+  installForInit,
+  installToDests,
+  userSkillsInstalled,
+  detectLegacyFlat,
+  migrateFlatToNamespace,
+  isDevflowOwnedFlatSkill,
+  NAMESPACE,
+  SHIPPED_SKILLS,
+  TARGET_MAP,
+  PROJECT_TARGET_MAP,
+  USER_TARGET_MAP,
+  USER_SCOPE_TARGETS,
+  USER_SKILLS_SOURCE,
+};