@yemi33/minions 0.1.1554 → 0.1.1556

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.1556 (2026-04-27)
+
+### Other
+- docs: document comprehensive minions remove
+
+## 0.1.1555 (2026-04-27)
+
+### Features
+- comprehensive minions remove (CLI + dashboard)
+
 ## 0.1.1554 (2026-04-27)
 
 ### Fixes

package/README.md

@@ -129,7 +129,7 @@ minions work "Explore the codebase and document the architecture"
 | `minions version` | Show installed vs package version |
 | `minions scan [dir] [depth]` | Scan for git repos and multi-select to add (default: ~, depth 3) |
 | `minions add <dir>` | Link a single project (auto-detects settings from git, prompts to confirm) |
-| `minions remove <dir>` | Unlink a project |
+| `minions remove <dir-or-name> [--keep-data \| --purge --force]` | Unlink a project: cancels pending work items, drains dispatch + kills active agents, cleans worktrees, disables linked schedules, archives `projects/<name>/` to `projects/.archived/<name>-YYYYMMDD/`. Use `--keep-data` to leave the data dir in place, or `--purge --force` to delete it. |
 | `minions list` | List all linked projects with descriptions |
 | `minions start` | Start engine daemon (ticks every 60s, auto-syncs MCP servers) |
 | `minions stop` | Stop the engine |

package/dashboard/js/settings.js

@@ -87,7 +87,10 @@ async function openSettings() {
     '<div style="display:flex;flex-direction:column;gap:12px;margin-bottom:16px">' +
     (data.projects || []).map(function(p) {
       return '<div style="border:1px solid var(--border);border-radius:6px;padding:10px 12px">' +
-        '<div style="font-size:12px;font-weight:600;margin-bottom:8px">' + escHtml(p.name) + '</div>' +
+        '<div style="display:flex;align-items:center;justify-content:space-between;margin-bottom:8px">' +
+          '<div style="font-size:12px;font-weight:600">' + escHtml(p.name) + '</div>' +
+          '<button onclick="MinionsSettings.removeProject(\'' + escHtml(p.name) + '\')" style="font-size:9px;padding:2px 8px;background:transparent;color:var(--red);border:1px solid var(--red);border-radius:3px;cursor:pointer">Remove</button>' +
+        '</div>' +
         '<div style="display:flex;flex-direction:column;gap:6px">' +
         settingsToggle('Discover from PRs', 'set-ws-prs-' + p.name, p.workSources.pullRequests.enabled, 'Discovery gate: scan repo for open PRs and surface them as review tasks. Independent of ADO/GitHub polling — does not affect already-tracked PRs.') +
         settingsToggle('Discover from Work Items', 'set-ws-wi-' + p.name, p.workSources.workItems.enabled, 'Auto-discover work from ADO/GitHub work items') +
@@ -404,4 +407,30 @@ async function resetSettingsToDefaults() {
   }
 }
 
-window.MinionsSettings = { openSettings, saveSettings, addProject, resetSettingsToDefaults };
+async function removeProject(name) {
+  if (!confirm('Remove project "' + name + '"? Pending work cancels, active agents are killed, data dir is archived to projects/.archived/.')) return;
+  showToast('cmd-toast', 'Removing project "' + name + '"...', true);
+  try {
+    const res = await fetch('/api/projects/remove', {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name })
+    });
+    const d = await res.json().catch(() => ({}));
+    if (!res.ok || !d.ok) {
+      showToast('cmd-toast', 'Remove failed: ' + (d.error || 'unknown'), false);
+      return;
+    }
+    var parts = ['Removed "' + name + '"'];
+    if (d.cancelledItems) parts.push(d.cancelledItems + ' WI cancelled');
+    if (d.drainedDispatches) parts.push(d.drainedDispatches + ' dispatch drained');
+    if (d.cleanedWorktrees) parts.push(d.cleanedWorktrees + ' worktree(s) cleaned');
+    if (d.archivedTo) parts.push('archived to ' + d.archivedTo);
+    if (d.pipelineRefs?.length) parts.push('! pipelines still reference: ' + d.pipelineRefs.join(', '));
+    showToast('cmd-toast', parts.join(' — '), true);
+    setTimeout(() => openSettings(), 600);
+  } catch (e) {
+    showToast('cmd-toast', 'Error: ' + e.message, false);
+  }
+}
+
+window.MinionsSettings = { openSettings, saveSettings, addProject, removeProject, resetSettingsToDefaults };

package/dashboard.js

@@ -1346,59 +1346,7 @@ function jsonReply(res, code, data, req) {
  * @param {(entry) => boolean} matchFn - return true for entries to remove
  * @returns {number} count of removed entries
  */
-function cleanDispatchEntries(matchFn) {
-  const dispatchPath = path.join(MINIONS_DIR, 'engine', 'dispatch.json');
-  const engineDir = path.join(MINIONS_DIR, 'engine');
-  try {
-    let removed = 0;
-    // Collect PIDs and file paths inside the lock, execute kills outside
-    const pidsToKill = [];
-    const filesToDelete = [];
-    mutateJsonFileLocked(dispatchPath, (dispatch) => {
-      dispatch.pending = Array.isArray(dispatch.pending) ? dispatch.pending : [];
-      dispatch.active = Array.isArray(dispatch.active) ? dispatch.active : [];
-      dispatch.completed = Array.isArray(dispatch.completed) ? dispatch.completed : [];
-      for (const queue of ['pending', 'active', 'completed']) {
-        const before = dispatch[queue].length;
-        if (queue === 'active') {
-          for (const d of dispatch[queue]) {
-            if (!matchFn(d)) continue;
-            // Collect PID and cleanup paths — actual I/O happens after lock release
-            const pidFile = path.join(engineDir, `pid-${d.id}.pid`);
-            try {
-              const pid = parseInt(fs.readFileSync(pidFile, 'utf8').trim());
-              if (pid) pidsToKill.push(pid);
-            } catch { /* PID file may not exist */ }
-            filesToDelete.push(pidFile);
-            filesToDelete.push(path.join(engineDir, 'tmp', `prompt-${d.id}.md`));
-            filesToDelete.push(path.join(engineDir, 'tmp', `sysprompt-${d.id}.md`));
-            filesToDelete.push(path.join(engineDir, 'tmp', `sysprompt-${d.id}.md.tmp`));
-          }
-        }
-        dispatch[queue] = dispatch[queue].filter(d => !matchFn(d));
-        removed += before - dispatch[queue].length;
-      }
-      return dispatch;
-    }, { defaultValue: { pending: [], active: [], completed: [] } });
-    // Kill processes outside the lock — these can take hundreds of ms on Windows
-    for (const pid of pidsToKill) {
-      try {
-        const safePid = shared.validatePid(pid);
-        if (process.platform === 'win32') {
-          const { execFileSync } = require('child_process');
-          execFileSync('taskkill', ['/PID', String(safePid), '/T'], { stdio: 'pipe', timeout: 5000, windowsHide: true });
-        } else {
-          process.kill(safePid, 'SIGTERM');
-        }
-      } catch { /* process may already be dead */ }
-    }
-    // Clean up files outside the lock
-    for (const fp of filesToDelete) {
-      try { fs.unlinkSync(fp); } catch { /* file may not exist */ }
-    }
-    return removed;
-  } catch { return 0; }
-}
+const { cleanDispatchEntries } = require('./engine/dispatch');
 
 // ── Engine Restart Helpers (used by watchdog + API) ─────────────────────────
 
@@ -3938,6 +3886,20 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
+  async function handleProjectsRemove(req, res) {
+    try {
+      const body = await readBody(req);
+      const target = body.name || body.path;
+      if (!target) return jsonReply(res, 400, { error: 'name or path required' });
+      const { removeProject } = require('./engine/projects');
+      const result = removeProject(target, { keepData: body.keepData === true, purge: body.purge === true });
+      if (!result.ok) return jsonReply(res, result.error?.includes('No project') ? 404 : 400, result);
+      reloadConfig();
+      invalidateStatusCache();
+      return jsonReply(res, 200, result);
+    } catch (e) { return jsonReply(res, 400, { error: e.message }); }
+  }
+
   async function handleProjectsScan(req, res) {
     try {
       const body = await readBody(req);
@@ -5227,6 +5189,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     { method: 'POST', path: '/api/projects/scan', desc: 'Scan a directory for git repos', params: 'path?, depth?', handler: handleProjectsScan },
     { method: 'POST', path: '/api/projects/confirm-token', desc: 'Mint a single-use UUID token required to add a non-repo path (SEC-05)', handler: handleProjectsConfirmToken },
     { method: 'POST', path: '/api/projects/add', desc: 'Auto-discover and add a project to config (name validated SEC-04; path validated SEC-05)', params: 'path, name?, allowNonRepo?, confirmToken?', handler: handleProjectsAdd },
+    { method: 'POST', path: '/api/projects/remove', desc: 'Unlink a project: cancels WIs, drains dispatch, kills agents, cleans worktrees, archives data dir', params: 'name or path, keepData?, purge?', handler: handleProjectsRemove },
 
     // Bug Filing
     { method: 'POST', path: '/api/issues/create', desc: 'File a bug on the Minions repo (yemi33/minions)', params: 'title, description?, labels?', handler: handleFileBug },

package/engine/dispatch.js

@@ -330,6 +330,85 @@ function cancelPendingDispatchesForPr(prId) {
   return cancelled;
 }
 
+/**
+ * Remove dispatch entries matching a predicate from pending/active/completed.
+ * For matched active entries, kills the agent process and deletes its
+ * pid file + prompt sidecars in engine/tmp/. Lock callback only mutates state;
+ * kills and unlinks happen after release.
+ *
+ * @param {(entry) => boolean} matchFn
+ * @returns {number} count of removed entries
+ */
+function cleanDispatchEntries(matchFn) {
+  const dispatchPath = path.join(MINIONS_DIR, 'engine', 'dispatch.json');
+  const engineDir = path.join(MINIONS_DIR, 'engine');
+  let removed = 0;
+  const pidsToKill = [];
+  const filesToDelete = [];
+  try {
+    mutateJsonFileLocked(dispatchPath, (dispatch) => {
+      for (const queue of ['pending', 'active', 'completed']) {
+        dispatch[queue] = Array.isArray(dispatch[queue]) ? dispatch[queue] : [];
+        const before = dispatch[queue].length;
+        if (queue === 'active') {
+          for (const d of dispatch[queue]) {
+            if (!matchFn(d)) continue;
+            const pidFile = path.join(engineDir, `pid-${d.id}.pid`);
+            try {
+              const pid = parseInt(fs.readFileSync(pidFile, 'utf8').trim());
+              if (pid) pidsToKill.push(pid);
+            } catch { /* PID file may not exist */ }
+            filesToDelete.push(pidFile);
+            filesToDelete.push(path.join(engineDir, 'tmp', `prompt-${d.id}.md`));
+            filesToDelete.push(path.join(engineDir, 'tmp', `sysprompt-${d.id}.md`));
+            filesToDelete.push(path.join(engineDir, 'tmp', `sysprompt-${d.id}.md.tmp`));
+          }
+        }
+        dispatch[queue] = dispatch[queue].filter(d => !matchFn(d));
+        removed += before - dispatch[queue].length;
+      }
+      return dispatch;
+    }, { defaultValue: { pending: [], active: [], completed: [] } });
+  } catch { return 0; }
+  // Kill processes outside the lock — taskkill on Windows can take hundreds of ms
+  for (const pid of pidsToKill) {
+    try {
+      const safePid = shared.validatePid(pid);
+      if (process.platform === 'win32') {
+        const { execFileSync } = require('child_process');
+        execFileSync('taskkill', ['/PID', String(safePid), '/T'], { stdio: 'pipe', timeout: 5000, windowsHide: true });
+      } else {
+        process.kill(safePid, 'SIGTERM');
+      }
+    } catch { /* may already be dead */ }
+  }
+  for (const fp of filesToDelete) {
+    try { fs.unlinkSync(fp); } catch { /* may not exist */ }
+  }
+  return removed;
+}
+
+/**
+ * Cancel pending/queued work items matching a predicate. Done items pass through.
+ * Sets status=CANCELLED + _cancelledBy=reason. Returns count cancelled.
+ */
+function cancelPendingWorkItems(wiPath, matchFn, reason) {
+  if (!fs.existsSync(wiPath)) return 0;
+  let cancelled = 0;
+  try {
+    mutateWorkItems(wiPath, items => {
+      for (const w of items) {
+        if (!matchFn(w)) continue;
+        if (w.status !== WI_STATUS.PENDING && w.status !== WI_STATUS.QUEUED) continue;
+        w.status = WI_STATUS.CANCELLED;
+        if (reason) w._cancelledBy = reason;
+        cancelled++;
+      }
+    });
+  } catch { /* file unwritable */ }
+  return cancelled;
+}
+
 // ─── Exports ─────────────────────────────────────────────────────────────────
 
 module.exports = {
@@ -340,4 +419,6 @@ module.exports = {
   writeInboxAlert,
   updateAgentStatus,
   cancelPendingDispatchesForPr,
+  cleanDispatchEntries,
+  cancelPendingWorkItems,
 };

package/engine/projects.js

@@ -0,0 +1,158 @@
+/**
+ * engine/projects.js — Project lifecycle (currently: comprehensive remove).
+ *
+ * Used by both the CLI (minions.js) and the dashboard (handleProjectsRemove)
+ * so removal semantics stay identical regardless of entry point.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const shared = require('./shared');
+const dispatch = require('./dispatch');
+const { MINIONS_DIR } = shared;
+
+/**
+ * @param {object} d - dispatch entry
+ * @returns {string} project name from any of the three meta shapes the engine
+ *   uses (item.project, project.name, project string)
+ */
+function _dispatchProjectName(d) {
+  return d?.meta?.item?.project || d?.meta?.project?.name || d?.meta?.project || '';
+}
+
+/**
+ * Remove a project: cancel pending work items, drain dispatch + kill agents,
+ * clean worktrees, disable project-targeted schedules, archive (or purge) the
+ * data directory, then unlink from config.json.
+ *
+ * @param {string} target - Project name or localPath
+ * @param {object} [options]
+ * @param {'archive'|'keep'|'purge'} [options.dataMode='archive']
+ *   archive: move projects/<name>/ to projects/.archived/<name>-YYYYMMDD/
+ *   keep:    leave projects/<name>/ in place
+ *   purge:   rm -rf projects/<name>/
+ * @returns {object} summary { ok, project, cancelledItems, killedAgents,
+ *   drainedDispatches, cleanedWorktrees, disabledSchedules, archivedTo,
+ *   purgedDataDir, pipelineRefs[], warnings[] } or { ok:false, error }
+ */
+function removeProject(target, options = {}) {
+  const dataMode = options.dataMode || (options.purge ? 'purge' : (options.keepData ? 'keep' : 'archive'));
+  const summary = {
+    ok: false,
+    project: null,
+    cancelledItems: 0,
+    drainedDispatches: 0, // includes active dispatches whose agent processes were killed
+    cleanedWorktrees: 0,
+    disabledSchedules: 0,
+    pipelineRefs: [],
+    archivedTo: null,
+    purgedDataDir: false,
+    warnings: [],
+  };
+
+  const configPath = path.join(MINIONS_DIR, 'config.json');
+  let config;
+  try { config = JSON.parse(fs.readFileSync(configPath, 'utf8')); }
+  catch (e) { return { ...summary, error: 'Failed to read config: ' + e.message }; }
+
+  const project = (config.projects || []).find(p =>
+    p.name === target || path.resolve(p.localPath || '') === path.resolve(target));
+  if (!project) {
+    const available = (config.projects || []).map(p => p.name).join(', ') || '(none)';
+    return { ...summary, error: `No project linked matching: ${target}. Available: ${available}` };
+  }
+  summary.project = { name: project.name, localPath: project.localPath };
+
+  // 1. Cancel pending/queued work items linked to this project (project-local
+  //    file + central). Done items are preserved as history.
+  for (const wiPath of [
+    path.join(MINIONS_DIR, 'projects', project.name, 'work-items.json'),
+    path.join(MINIONS_DIR, 'work-items.json'),
+  ]) {
+    summary.cancelledItems += dispatch.cancelPendingWorkItems(
+      wiPath,
+      w => !w.project || w.project === project.name,
+      'project-removed',
+    );
+  }
+
+  // 2. Drain dispatch — also kills active agent processes and unlinks pid +
+  //    prompt sidecars in engine/tmp/, matching what plan delete does.
+  summary.drainedDispatches = dispatch.cleanDispatchEntries(
+    d => _dispatchProjectName(d) === project.name,
+  );
+
+  // 3. Clean up worktrees under this project's worktree root, honoring
+  //    config.engine.worktreeRoot (mirrors lifecycle.js cleanupPlanWorktrees).
+  if (project.localPath) {
+    try {
+      const wtRoot = path.resolve(project.localPath, config.engine?.worktreeRoot || '../worktrees');
+      if (fs.existsSync(wtRoot)) {
+        for (const dir of fs.readdirSync(wtRoot)) {
+          try {
+            if (shared.removeWorktree(path.join(wtRoot, dir), project.localPath, wtRoot)) {
+              summary.cleanedWorktrees++;
+            }
+          } catch { /* best effort */ }
+        }
+      }
+    } catch (e) { summary.warnings.push('worktree cleanup: ' + e.message); }
+  }
+
+  // 4. Disable schedules whose `project` field targets this project
+  //    specifically. Don't touch schedules with project='any' or unset.
+  if (Array.isArray(config.schedules)) {
+    for (const s of config.schedules) {
+      if (s.project === project.name && s.enabled !== false) {
+        s.enabled = false;
+        summary.disabledSchedules++;
+      }
+    }
+  }
+
+  // 5. Surface pipelines that reference this project so the user can review
+  //    them. Don't auto-modify — user intent there is unclear.
+  try {
+    const { getPipelines } = require('./pipeline');
+    for (const p of getPipelines() || []) {
+      const refs = [
+        ...(p.monitoredResources || []),
+        ...((p.stages || []).flatMap(s => s.monitoredResources || [])),
+      ];
+      if (refs.some(r => r && (r.project === project.name || r._project === project.name))) {
+        summary.pipelineRefs.push(p.id);
+      }
+    }
+  } catch { /* pipelines optional */ }
+
+  // 6. Remove from config.json (and persist any schedule disables)
+  config.projects = (config.projects || []).filter(p => p.name !== project.name);
+  try { fs.writeFileSync(configPath, JSON.stringify(config, null, 2)); }
+  catch (e) { return { ...summary, error: 'Failed to write config: ' + e.message }; }
+
+  // 7. Move (or purge) projects/<name>/ — preserves PR/work-item history by
+  //    default so a re-add can pick up where it left off.
+  const dataDir = path.join(MINIONS_DIR, 'projects', project.name);
+  if (fs.existsSync(dataDir)) {
+    if (dataMode === 'purge') {
+      try { fs.rmSync(dataDir, { recursive: true, force: true }); summary.purgedDataDir = true; }
+      catch (e) { summary.warnings.push('purge data dir: ' + e.message); }
+    } else if (dataMode === 'archive') {
+      try {
+        const archiveRoot = path.join(MINIONS_DIR, 'projects', '.archived');
+        fs.mkdirSync(archiveRoot, { recursive: true });
+        const stamp = new Date().toISOString().slice(0, 10).replace(/-/g, '');
+        let archived = path.join(archiveRoot, project.name + '-' + stamp);
+        let n = 1;
+        while (fs.existsSync(archived)) archived = path.join(archiveRoot, project.name + '-' + stamp + '-' + (++n));
+        fs.renameSync(dataDir, archived);
+        summary.archivedTo = path.relative(MINIONS_DIR, archived).replace(/\\/g, '/');
+      } catch (e) { summary.warnings.push('archive data dir: ' + e.message); }
+    }
+  }
+
+  summary.ok = true;
+  return summary;
+}
+
+module.exports = { removeProject };

package/minions.js

@@ -206,20 +206,27 @@ async function addProject(targetDir) {
   console.log(`    node ${MINIONS_HOME}/engine.js status   # Status\n`);
 }
 
-function removeProject(targetDir) {
-  const target = path.resolve(targetDir);
-  const config = loadConfig();
-  const before = (config.projects || []).length;
-  config.projects = (config.projects || []).filter(p => path.resolve(p.localPath) !== target);
-  const after = config.projects.length;
-
-  if (before === after) {
-    console.log(`  No project linked at ${target}`);
-  } else {
-    saveConfig(config);
-    console.log(`  Removed project at ${target}`);
-    console.log(`  Remaining projects: ${config.projects.length}`);
+function removeProject(target, options = {}) {
+  const { removeProject: doRemove } = require('./engine/projects');
+  // CLI accepts a path; project lookup also matches by name as a convenience
+  const result = doRemove(path.resolve(target), options);
+  if (!result.ok) {
+    console.log('  ' + (result.error || 'Removal failed'));
+    rl.close();
+    process.exitCode = 1;
+    return;
   }
+
+  const lines = [`  Removed project: ${result.project.name} (${result.project.localPath})`];
+  if (result.cancelledItems) lines.push(`    cancelled ${result.cancelledItems} pending work item(s)`);
+  if (result.drainedDispatches) lines.push(`    drained ${result.drainedDispatches} dispatch entr${result.drainedDispatches === 1 ? 'y' : 'ies'} (active agents killed)`);
+  if (result.cleanedWorktrees) lines.push(`    cleaned ${result.cleanedWorktrees} worktree(s)`);
+  if (result.disabledSchedules) lines.push(`    disabled ${result.disabledSchedules} schedule(s)`);
+  if (result.archivedTo) lines.push(`    archived data → ${result.archivedTo}`);
+  if (result.purgedDataDir) lines.push(`    purged data directory`);
+  if (result.pipelineRefs.length) lines.push(`    ! pipeline(s) still reference this project: ${result.pipelineRefs.join(', ')}`);
+  for (const w of result.warnings) lines.push(`    warn: ${w}`);
+  console.log(lines.join('\n'));
   rl.close();
 }
 
@@ -498,9 +505,18 @@ const commands = {
     addProject(dir).catch(e => { console.error(e); process.exit(1); });
   },
   remove: () => {
-    const dir = rest[0];
-    if (!dir) { console.log('Usage: node minions remove <project-dir>'); process.exit(1); }
-    removeProject(dir);
+    const positional = rest.filter(a => !a.startsWith('--'));
+    const dir = positional[0];
+    if (!dir) {
+      console.log('Usage: node minions remove <project-dir-or-name> [--keep-data | --purge]');
+      process.exit(1);
+    }
+    const options = { keepData: rest.includes('--keep-data'), purge: rest.includes('--purge') };
+    if (options.purge && !rest.includes('--force')) {
+      console.log(`  --purge will permanently delete projects/<name>/. Re-run with --force to confirm.`);
+      process.exit(1);
+    }
+    removeProject(dir, options);
   },
   list: () => listProjects(),
   scan: () => scanAndAdd({ root: rest[0], depth: rest[1] })
@@ -516,7 +532,9 @@ if (cmd && commands[cmd]) {
   console.log('    init                    Initialize minions and scan for repos');
   console.log('    scan [dir] [depth]      Scan for git repos and multi-select to add');
   console.log('    add <project-dir>       Link a single project');
-  console.log('    remove <project-dir>    Unlink a project');
+  console.log('    remove <project-dir-or-name> [--keep-data | --purge --force]');
+  console.log('                            Unlink: cancels WIs, drains dispatch, kills agents,');
+  console.log('                            cleans worktrees, archives data dir to projects/.archived/');
   console.log('    list                    List linked projects\n');
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1554",
+  "version": "0.1.1556",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"