@yemi33/minions 0.1.2178 → 0.1.2180

package/engine/preflight.js

@@ -9,6 +9,7 @@
  */
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const { execSync, execFileSync } = require('child_process');
 
@@ -666,12 +667,272 @@ function doctor(minionsHome) {
   });
 }
 
+/**
+ * Harness propagation diagnostic for `minions doctor --harness` (plan item #1
+ * of `seamless-user-repo-harness-invocation`, PRD `P-a3f9b2c1`). Iterates
+ * every registered runtime and prints every dir / file the engine would
+ * surface to a spawned agent today, grouped by scope label
+ * (`user` / `project:<name>` / `personal` / `minions`). Missing on-disk paths
+ * are flagged with `⚠` but do not fail the command — they're listed so the
+ * operator can decide whether to create / populate the dir or leave it as-is
+ * for this host.
+ *
+ * The diagnostic is intentionally read-only and side-effect-free: no mutation
+ * of config, cache files, or worktrees. Exits non-zero only on a true
+ * runtime/config error (e.g. registry refuses to resolve a registered
+ * runtime). See `docs/harness-propagation.md` for the full contract.
+ *
+ * Pure-ish: `homeDir` and `existsFn` are injectable for tests so a temp
+ * sandbox can assert the "missing path" branch without touching the real
+ * `~/.claude` / `~/.copilot` dirs.
+ */
+function _resolveProjectsForHarness(minionsHome) {
+  const configPath = path.join(minionsHome, 'config.json');
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    const projects = Array.isArray(config.projects) ? config.projects : [];
+    return {
+      config,
+      projects: projects.filter(p => p && p.name && p.localPath && !String(p.name).startsWith('YOUR_')),
+    };
+  } catch {
+    return { config: null, projects: [] };
+  }
+}
+
+function _padRight(s, len) {
+  s = String(s);
+  if (s.length >= len) return s;
+  return s + ' '.repeat(len - s.length);
+}
+
+function _formatHarnessLine(absPath, scopeLabel, exists) {
+  const marker = exists ? '✓' : '⚠';
+  const pathCol = _padRight(absPath, 56);
+  const scopeCol = `[${scopeLabel}]`;
+  const suffix = exists ? '' : '   (missing on disk)';
+  return `      ${marker} ${pathCol} ${scopeCol}${suffix}`;
+}
+
+function _runtimeHarnessRows(runtime, { homeDir, projects, existsFn }) {
+  const rows = {
+    userAssetDirs: [],
+    skillRootsUser: [],
+    skillRootsProject: [],
+    skillWriteTargets: [],
+    commandRootsUser: [],
+    commandRootsProject: [],
+    mcpConfigUser: [],
+    mcpConfigProject: [],
+  };
+  if (typeof runtime.getUserAssetDirs === 'function') {
+    try {
+      for (const d of runtime.getUserAssetDirs({ homeDir }) || []) {
+        if (!d) continue;
+        rows.userAssetDirs.push({ path: d, scope: 'user', exists: existsFn(d) });
+      }
+    } catch { /* adapter optional fields */ }
+  }
+  if (typeof runtime.getSkillRoots === 'function') {
+    try {
+      for (const root of runtime.getSkillRoots({ homeDir }) || []) {
+        if (!root || !root.dir) continue;
+        if (root.scope === 'project') continue; // user call shouldn't return project rows, but be defensive
+        rows.skillRootsUser.push({ path: root.dir, scope: root.scope || 'user', exists: existsFn(root.dir) });
+      }
+    } catch { /* */ }
+    for (const project of projects) {
+      try {
+        for (const root of runtime.getSkillRoots({ homeDir, project }) || []) {
+          if (!root || !root.dir || root.scope !== 'project') continue;
+          rows.skillRootsProject.push({
+            path: root.dir,
+            scope: `project:${root.projectName || project.name}`,
+            exists: existsFn(root.dir),
+          });
+        }
+      } catch { /* */ }
+    }
+  }
+  if (typeof runtime.getSkillWriteTargets === 'function') {
+    try {
+      const targets = runtime.getSkillWriteTargets({ homeDir }) || {};
+      if (targets.personal) {
+        rows.skillWriteTargets.push({ path: targets.personal, scope: 'personal', exists: existsFn(targets.personal) });
+      }
+    } catch { /* */ }
+    for (const project of projects) {
+      try {
+        const targets = runtime.getSkillWriteTargets({ homeDir, project }) || {};
+        if (targets.project) {
+          rows.skillWriteTargets.push({
+            path: targets.project,
+            scope: `project:${project.name}`,
+            exists: existsFn(targets.project),
+          });
+        }
+      } catch { /* */ }
+    }
+  }
+  if (typeof runtime.getCommandRoots === 'function') {
+    try {
+      for (const root of runtime.getCommandRoots({ homeDir }) || []) {
+        if (!root || !root.dir) continue;
+        if (root.scope === 'project') continue;
+        rows.commandRootsUser.push({ path: root.dir, scope: root.scope || 'user', exists: existsFn(root.dir) });
+      }
+    } catch { /* */ }
+    for (const project of projects) {
+      try {
+        for (const root of runtime.getCommandRoots({ homeDir, project }) || []) {
+          if (!root || !root.dir || root.scope !== 'project') continue;
+          rows.commandRootsProject.push({
+            path: root.dir,
+            scope: `project:${root.projectName || project.name}`,
+            exists: existsFn(root.dir),
+          });
+        }
+      } catch { /* */ }
+    }
+  }
+  if (typeof runtime.getMcpConfigPaths === 'function') {
+    try {
+      for (const entry of runtime.getMcpConfigPaths({ homeDir }) || []) {
+        if (!entry || !entry.file) continue;
+        if (entry.scope === 'project') continue;
+        rows.mcpConfigUser.push({ path: entry.file, scope: entry.scope || 'user', exists: existsFn(entry.file) });
+      }
+    } catch { /* */ }
+    for (const project of projects) {
+      try {
+        for (const entry of runtime.getMcpConfigPaths({ homeDir, project }) || []) {
+          if (!entry || !entry.file || entry.scope !== 'project') continue;
+          rows.mcpConfigProject.push({
+            path: entry.file,
+            scope: `project:${entry.projectName || project.name}`,
+            exists: existsFn(entry.file),
+          });
+        }
+      } catch { /* */ }
+    }
+  }
+  return rows;
+}
+
+function _computeAddDirSnapshot(runtime, { minionsHome, homeDir, existsFn }) {
+  let computeAddDirs;
+  try { ({ computeAddDirs } = require('./spawn-agent')); }
+  catch { return null; }
+  if (typeof computeAddDirs !== 'function') return null;
+  let dirs = [];
+  try { dirs = computeAddDirs({ runtime, minionsDir: minionsHome, homeDir, exists: existsFn }) || []; }
+  catch { return null; }
+  return dirs.map(d => {
+    let scope = 'user';
+    if (path.resolve(d) === path.resolve(minionsHome)) scope = 'minions';
+    return { path: d, scope, exists: existsFn(d) };
+  });
+}
+
+function runHarnessDoctor(minionsHome, opts = {}) {
+  const homeDir = opts.homeDir || os.homedir();
+  const existsFn = opts.existsFn || fs.existsSync;
+  const out = opts.out || (line => console.log(line));
+
+  let registry;
+  try { registry = require('./runtimes'); }
+  catch (e) {
+    out(`Minions Harness Propagation`);
+    out(`  Could not load runtime registry: ${e.message}`);
+    return false;
+  }
+  const runtimeNames = registry.listRuntimes();
+  const { config, projects } = _resolveProjectsForHarness(minionsHome);
+  const defaultCli = (config && config.engine && config.engine.defaultCli) || 'copilot';
+
+  out('Minions Harness Propagation');
+  if (projects.length === 0) {
+    out('  (no real projects configured — project-scope rows will be empty)');
+  } else {
+    out(`  Projects: ${projects.map(p => p.name).join(', ')}`);
+  }
+
+  let hardError = false;
+  for (const runtimeName of runtimeNames) {
+    out('');
+    out(`  Runtime: ${runtimeName}`);
+    let runtime;
+    try { runtime = registry.resolveRuntime(runtimeName); }
+    catch (e) {
+      out(`    Could not resolve adapter: ${e.message}`);
+      hardError = true;
+      continue;
+    }
+    const rows = _runtimeHarnessRows(runtime, { homeDir, projects, existsFn });
+
+    out('    User asset dirs (--add-dir to agents):');
+    if (rows.userAssetDirs.length === 0) out('      (adapter does not expose getUserAssetDirs)');
+    for (const r of rows.userAssetDirs) out(_formatHarnessLine(r.path, r.scope, r.exists));
+
+    out('    Skill roots (CLI native discovery):');
+    if (rows.skillRootsUser.length === 0 && rows.skillRootsProject.length === 0) {
+      out('      (adapter does not expose getSkillRoots)');
+    }
+    for (const r of rows.skillRootsUser) out(_formatHarnessLine(r.path, r.scope, r.exists));
+    for (const r of rows.skillRootsProject) out(_formatHarnessLine(r.path, r.scope, r.exists));
+
+    out('    Skill write targets (auto-extract destinations):');
+    if (rows.skillWriteTargets.length === 0) {
+      out('      (adapter does not expose getSkillWriteTargets)');
+    }
+    for (const r of rows.skillWriteTargets) out(_formatHarnessLine(r.path, r.scope, r.exists));
+
+    out('    Slash commands (CLI native discovery):');
+    if (rows.commandRootsUser.length === 0 && rows.commandRootsProject.length === 0) {
+      out('      (adapter does not expose getCommandRoots)');
+    }
+    for (const r of rows.commandRootsUser) out(_formatHarnessLine(r.path, r.scope, r.exists));
+    for (const r of rows.commandRootsProject) out(_formatHarnessLine(r.path, r.scope, r.exists));
+
+    out('    MCP config files:');
+    if (rows.mcpConfigUser.length === 0 && rows.mcpConfigProject.length === 0) {
+      out('      (adapter does not expose getMcpConfigPaths)');
+    }
+    for (const r of rows.mcpConfigUser) out(_formatHarnessLine(r.path, r.scope, r.exists));
+    for (const r of rows.mcpConfigProject) out(_formatHarnessLine(r.path, r.scope, r.exists));
+  }
+
+  out('');
+  out(`  Worktree --add-dir snapshot (engine fleet default: ${defaultCli}):`);
+  let defaultRuntime = null;
+  try { defaultRuntime = registry.resolveRuntime(defaultCli); }
+  catch { /* preflight handles unknown-runtime errors; here we just skip */ }
+  if (!defaultRuntime) {
+    out('    (cannot resolve fleet-default runtime — see `minions doctor` for details)');
+  } else {
+    const snapshot = _computeAddDirSnapshot(defaultRuntime, { minionsHome, homeDir, existsFn });
+    if (!snapshot || snapshot.length === 0) {
+      out('    (no dirs attached — engine/spawn-agent.js unavailable or adapter has no asset dirs)');
+    } else {
+      for (const r of snapshot) out(_formatHarnessLine(r.path, r.scope, r.exists));
+    }
+  }
+
+  out('');
+  out('  All harness paths surveyed. Missing on-disk paths are warnings, not failures —');
+  out('  they\'re listed so you can decide whether to create the dir, populate it, or');
+  out('  ignore it for this host.');
+  out('');
+  return !hardError;
+}
+
 module.exports = {
   findClaudeBinary,
   runPreflight,
   printPreflight,
   checkOrExit,
   doctor,
+  runHarnessDoctor,
   // Exposed for unit tests (P-9e8a3f1d) — engine code MUST go through
   // runPreflight/doctor, never these helpers directly.
   _distinctRuntimes,
@@ -682,4 +943,8 @@ module.exports = {
   _fetchCliHelpText,
   _checkBypassFlagSupported,
   _bypassFlagResults,
+  // Exposed for harness-propagation doctor unit tests (P-a3f9b2c1).
+  _runtimeHarnessRows,
+  _computeAddDirSnapshot,
+  _formatHarnessLine,
 };