@voiden/runner 2.1.0 → 2.2.0

package/dist/index.js

@@ -1,21 +1,44 @@
 #!/usr/bin/env node
 import { program } from 'commander';
-import { readFileSync, existsSync, statSync, writeFileSync, mkdirSync, unlinkSync } from 'fs';
-import { resolve, basename, join, dirname } from 'path';
+import { readFileSync, existsSync, writeFileSync, mkdirSync, unlinkSync } from 'fs';
+import { resolve, relative, basename, join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { readdir } from 'fs/promises';
 import chalk from 'chalk';
 import { runVoidFile } from './runner.js';
+import { resolveFiles } from './discovery.js';
 import { loadEnabledPlugins } from './plugins/loader.js';
 import { exportToCsv } from './report/csv.js';
 import { sendMailReport } from './report/mail.js';
-import { getCorePlugins, findPlugin } from './plugins/registry.js';
+import { getCorePlugins, findPlugin, hasCoreRunner } from './plugins/registry.js';
 import { downloadCoreRunner } from './plugins/loader.js';
 import { fetchCommunityPlugins, findCommunityPlugin, hasCommunityRunner, installCommunityRunner, } from './plugins/community.js';
 import { installPlugin, uninstallPlugin, setPluginEnabled, setPluginVersion, getAllInstalledPlugins, readStore, STORE_DIR, } from './plugins/store.js';
 import { checkForPluginUpdates } from './plugins/updateCheck.js';
+import { getInstalledPluginInfo } from './plugins/versionInfo.js';
+import { parseVoidFile } from './parser.js';
+import { classifyBlockVersion } from '@voiden/executors';
+import { installMcpIntegration, uninstallMcpIntegration, getMcpStatus } from './mcpInstall.js';
+import { RUNNER_SKILL_MARKDOWN } from './skillContent.js';
 import { appendSessionResults, loadSessionResults, clearSession, } from './session.js';
 // ─────────────────────────────────────────────────────────────────────────────
+// Exit codes — a stable, documented contract CI pipelines can branch on.
+//
+//   0  success — all requests passed
+//   1  one or more requests failed (assertions/errors), or --bail /
+//      --fail-on-error triggered — unchanged from prior releases
+//   2  the runner could not execute the run at all: bad CLI args/flags,
+//      missing files, missing plugins, invalid env — a pipeline/config
+//      problem, not an API failure
+//
+// See CHANGELOG.md and docs.voiden.md/docs/developer-tools/voiden-runner/ci-cd
+// ─────────────────────────────────────────────────────────────────────────────
+const EXIT_SUCCESS = 0;
+const EXIT_RUN_FAILURE = 1;
+const EXIT_USAGE_ERROR = 2;
+/** JSON output schema version — bump whenever a field is renamed, removed, or
+ *  reinterpreted (adding a field is not a breaking change and does not need a bump). */
+const JSON_SCHEMA_VERSION = '1';
+// ─────────────────────────────────────────────────────────────────────────────
 // Helpers
 // ─────────────────────────────────────────────────────────────────────────────
 function loadEnvFile(envPath) {
@@ -49,50 +72,6 @@ function formatDuration(ms) {
         return `${ms}ms`;
     return `${(ms / 1000).toFixed(2)}s`;
 }
-/** Recursively collect all .void files under a directory. */
-async function collectVoidFiles(inputPath) {
-    const abs = resolve(inputPath);
-    if (!existsSync(abs))
-        return [];
-    const stat = statSync(abs);
-    if (stat.isFile()) {
-        return abs.endsWith('.void') ? [abs] : [];
-    }
-    if (stat.isDirectory()) {
-        const entries = await readdir(abs, { withFileTypes: true });
-        const results = [];
-        for (const entry of entries) {
-            const full = resolve(abs, entry.name);
-            if (entry.isDirectory()) {
-                results.push(...(await collectVoidFiles(full)));
-            }
-            else if (entry.isFile() && entry.name.endsWith('.void')) {
-                results.push(full);
-            }
-        }
-        return results;
-    }
-    return [];
-}
-/** Expand a list of paths/globs into resolved .void file paths. */
-async function resolveFiles(patterns) {
-    const resolved = [];
-    for (const pattern of patterns) {
-        if (pattern.includes('*')) {
-            const dir = resolve(pattern.replace(/\/?\*.*$/, '') || '.');
-            const entries = await readdir(dir, { withFileTypes: true });
-            for (const entry of entries) {
-                if (entry.isFile() && entry.name.endsWith('.void')) {
-                    resolved.push(resolve(dir, entry.name));
-                }
-            }
-        }
-        else {
-            resolved.push(...(await collectVoidFiles(pattern)));
-        }
-    }
-    return resolved;
-}
 // ─────────────────────────────────────────────────────────────────────────────
 // Spinner
 // ─────────────────────────────────────────────────────────────────────────────
@@ -266,20 +245,71 @@ function printRunSummary(results, totalMs) {
     console.log(DIVIDER);
     console.log();
 }
-function printRunSummaryJson(results, totalMs, activePlugins) {
+/**
+ * Builds the `--json` / `--output-json` payload shape shared by `run` and
+ * `report generate`. `schemaVersion` is the stable contract external tooling
+ * codes against — see the exit-codes comment above for the versioning rule.
+ */
+function buildJsonReport(results, extra = {}) {
     const passed = results.filter(r => r.result.success).length;
-    const output = {
+    return {
+        schemaVersion: JSON_SCHEMA_VERSION,
         summary: {
             total: results.length,
             passed,
             failed: results.length - passed,
-            totalDurationMs: totalMs,
-            activePlugins,
+            ...extra,
         },
         requests: results.map(r => ({ file: r.file, ...r.result })),
     };
+}
+function printRunSummaryJson(results, totalMs, activePlugins) {
+    const output = buildJsonReport(results, { totalDurationMs: totalMs, activePlugins });
     console.log(JSON.stringify(output, null, 2));
 }
+/** Split CHANGELOG.md into per-version entries on "## " headers (newest first, matching file order). */
+function parseChangelog(content) {
+    const lines = content.split('\n');
+    const entries = [];
+    let current = null;
+    for (const line of lines) {
+        const headerMatch = line.match(/^##\s+(\S+)(?:\s+-\s+(.+))?$/);
+        if (headerMatch) {
+            if (current)
+                entries.push(current);
+            current = { version: headerMatch[1], date: headerMatch[2]?.trim(), body: [] };
+            continue;
+        }
+        if (current)
+            current.body.push(line);
+    }
+    if (current)
+        entries.push(current);
+    return entries;
+}
+function renderChangelogEntry(entry) {
+    const header = entry.date ? `${entry.version}  ${chalk.gray(entry.date)}` : entry.version;
+    console.log(chalk.bold.white(`  ${header}`));
+    console.log(DIVIDER);
+    for (const line of entry.body) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const sectionMatch = trimmed.match(/^###\s+(.+)$/);
+        if (sectionMatch) {
+            console.log();
+            console.log(chalk.bold.cyan(`  ${sectionMatch[1]}`));
+            continue;
+        }
+        const bulletMatch = trimmed.match(/^-\s+(.+)$/);
+        if (bulletMatch) {
+            console.log(chalk.gray(`    ·  `) + bulletMatch[1]);
+            continue;
+        }
+        console.log(`  ${trimmed}`);
+    }
+    console.log();
+}
 // ─────────────────────────────────────────────────────────────────────────────
 // Plugin update notices — surfaced after `run` and `plugin` commands so users
 // learn about newer registry versions without having to run `plugin list`.
@@ -303,6 +333,65 @@ async function notifyPluginUpdates() {
         // Informational only — ignore failures (e.g. offline)
     }
 }
+function scanProjectRequirements(files, cwd) {
+    // pluginId → version → files that declared it
+    const usages = new Map();
+    for (const file of files) {
+        let content;
+        try {
+            content = readFileSync(file, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        for (const block of parseVoidFile(content)) {
+            const pluginId = block.attrs?.pluginId;
+            const pluginVersion = block.attrs?.pluginVersion;
+            if (!pluginId || !pluginVersion)
+                continue;
+            if (!usages.has(pluginId))
+                usages.set(pluginId, new Map());
+            const versions = usages.get(pluginId);
+            if (!versions.has(pluginVersion))
+                versions.set(pluginVersion, new Set());
+            versions.get(pluginVersion).add(relative(cwd, file));
+        }
+    }
+    const issues = [];
+    for (const [pluginId, versions] of usages) {
+        for (const [version, fileSet] of versions) {
+            const installed = getInstalledPluginInfo(pluginId);
+            const status = classifyBlockVersion({ pluginId, pluginVersion: version, blockType: '' }, installed);
+            if (status === 'ok')
+                continue;
+            issues.push({ pluginId, requiredVersion: version, installedVersion: installed?.version, status, files: [...fileSet] });
+        }
+    }
+    return issues;
+}
+function printProjectStatus(issues) {
+    if (issues.length === 0)
+        return;
+    console.log();
+    console.log(chalk.yellow(`  ⚠  ${issues.length} plugin${issues.length !== 1 ? 's' : ''} ${issues.length !== 1 ? "don't" : "doesn't"} match what this project needs`));
+    for (const issue of issues) {
+        const have = issue.status === 'not-installed' ? 'not installed'
+            : issue.status === 'disabled' ? 'installed but disabled'
+                : `v${issue.installedVersion} installed`;
+        console.log(chalk.gray(`     ${chalk.bold(issue.pluginId.padEnd(24))} requires v${issue.requiredVersion} — ${have}`));
+        console.log(chalk.gray(`       used in: ${issue.files.join(', ')}`));
+    }
+    console.log(chalk.gray(`     Run: voiden-runner plugin install <name>@<version>`));
+}
+/** Best-effort — never throws, never blocks command output on failure. */
+function notifyProjectStatus(files, cwd) {
+    try {
+        printProjectStatus(scanProjectRequirements(files, cwd));
+    }
+    catch {
+        // Informational only
+    }
+}
 // ─────────────────────────────────────────────────────────────────────────────
 // CLI
 // ─────────────────────────────────────────────────────────────────────────────
@@ -312,6 +401,47 @@ program
     .name('voiden-runner')
     .description('Run .void files headlessly — REST, WebSocket, and gRPC')
     .version(pkg.version);
+// ── voiden-runner changelog ───────────────────────────────────────────────────
+program
+    .command('changelog [version]')
+    .description('Show release notes for voiden-runner — versioned independently of the desktop app\n\n' +
+    '  Examples:\n' +
+    '    voiden-runner changelog            # full history\n' +
+    '    voiden-runner changelog --latest   # most recent release only\n' +
+    '    voiden-runner changelog 2.1.0       # a specific version\n')
+    .option('--latest', 'Show only the most recent release')
+    .action((version, opts) => {
+    const changelogPath = resolve(join(dirname(fileURLToPath(import.meta.url)), '../CHANGELOG.md'));
+    if (!existsSync(changelogPath)) {
+        console.error(chalk.red('  ✗  No CHANGELOG.md found for this install.'));
+        process.exit(EXIT_USAGE_ERROR);
+    }
+    const entries = parseChangelog(readFileSync(changelogPath, 'utf-8'));
+    if (entries.length === 0) {
+        console.log(chalk.gray('  Changelog is empty.'));
+        return;
+    }
+    let toShow = entries;
+    if (version) {
+        const normalized = version.replace(/^v/, '');
+        const match = entries.find(e => e.version.replace(/^v/, '') === normalized);
+        if (!match) {
+            console.error(chalk.red(`  ✗  No changelog entry found for version "${version}".`));
+            console.log(chalk.gray(`     Available: ${entries.map(e => e.version).join(', ')}`));
+            process.exit(EXIT_USAGE_ERROR);
+        }
+        toShow = [match];
+    }
+    else if (opts.latest) {
+        toShow = [entries[0]];
+    }
+    console.log();
+    console.log(chalk.bold.white('  voiden-runner changelog'));
+    console.log();
+    for (const entry of toShow) {
+        renderChangelogEntry(entry);
+    }
+});
 // ── voiden-runner run ─────────────────────────────────────────────────────────
 program
     .command('run <paths...>')
@@ -358,14 +488,14 @@ program
         const envPath = resolve(opts.env);
         if (!existsSync(envPath)) {
             console.error(chalk.red(`Env file not found: ${envPath}`));
-            process.exit(1);
+            process.exit(EXIT_USAGE_ERROR);
         }
         try {
             Object.assign(env, loadEnvFile(envPath));
         }
         catch (err) {
             console.error(chalk.red(`  ✗  ${err.message}`));
-            process.exit(1);
+            process.exit(EXIT_USAGE_ERROR);
         }
     }
     // 2. Individual --env-var overrides
@@ -374,13 +504,13 @@ program
             const eq = pair.indexOf('=');
             if (eq === -1) {
                 console.error(chalk.red(`  ✗  Invalid --env-var format: "${pair}" (expected key=value)`));
-                process.exit(1);
+                process.exit(EXIT_USAGE_ERROR);
             }
             const key = pair.slice(0, eq).trim();
             const val = pair.slice(eq + 1).trim().replace(/^["']|["']$/g, '');
             if (!key) {
                 console.error(chalk.red(`  ✗  Invalid --env-var format: "${pair}" (key cannot be empty)`));
-                process.exit(1);
+                process.exit(EXIT_USAGE_ERROR);
             }
             env[key] = val;
         }
@@ -388,7 +518,7 @@ program
     const resolvedFiles = await resolveFiles(paths);
     if (resolvedFiles.length === 0) {
         console.error(chalk.red('No .void files found at the given path(s)'));
-        process.exit(1);
+        process.exit(EXIT_USAGE_ERROR);
     }
     // --stop-on-failure is a CI-friendly alias for --bail
     const stopOnFailure = opts.bail || opts.stopOnFailure;
@@ -406,11 +536,11 @@ program
     if (opts.mail || opts.mailTo) {
         if (!mailTo) {
             console.error(chalk.red('  ✗  Mail error: no recipient found. Please provide --mail-to or set VOIDEN_MAIL_TO.'));
-            process.exit(1);
+            process.exit(EXIT_USAGE_ERROR);
         }
         if (!smtpHost) {
             console.error(chalk.red('  ✗  Mail keys are missing. Please provide SMTP configuration (VOIDEN_SMTP_HOST).'));
-            process.exit(1);
+            process.exit(EXIT_USAGE_ERROR);
         }
     }
     const runStart = Date.now();
@@ -516,16 +646,7 @@ program
     // ── Output JSON to file (before mail so it can be attached) ──────────────
     let savedJsonPath;
     if (opts.outputJson) {
-        const jsonData = {
-            summary: {
-                total: allResults.length,
-                passed: allResults.filter(r => r.result.success).length,
-                failed: allResults.filter(r => !r.result.success).length,
-                totalDurationMs: totalMs,
-                activePlugins,
-            },
-            requests: allResults.map(r => ({ file: r.file, ...r.result })),
-        };
+        const jsonData = buildJsonReport(allResults, { totalDurationMs: totalMs, activePlugins });
         try {
             mkdirSync(dirname(opts.outputJson), { recursive: true });
             writeFileSync(opts.outputJson, JSON.stringify(jsonData, null, 2) + '\n', 'utf-8');
@@ -566,10 +687,12 @@ program
         console.log(chalk.gray('     (use this exit code in your shell script to abort on failure)'));
         console.log();
     }
-    // Surface plugin update notices — skipped in --json mode so output stays machine-readable
-    if (!opts.json)
+    // Surface plugin update / project-requirements notices — skipped in --json mode so output stays machine-readable
+    if (!opts.json) {
         await notifyPluginUpdates();
-    process.exit(shouldFail ? 1 : 0);
+        notifyProjectStatus(resolvedFiles, process.cwd());
+    }
+    process.exit(shouldFail ? EXIT_RUN_FAILURE : EXIT_SUCCESS);
 });
 // ── voiden-runner session ─────────────────────────────────────────────────────
 const sessionCmd = program
@@ -684,7 +807,7 @@ reportCmd
     const results = loadSessionResults();
     if (results.length === 0) {
         console.error(chalk.red('  ✗  No results found in session. Run some .void files first.'));
-        process.exit(1);
+        process.exit(EXIT_USAGE_ERROR);
     }
     // Load optional .env for report SMTP settings
     const env = { ...process.env };
@@ -703,12 +826,12 @@ reportCmd
     if (opts.mail || opts.mailTo) {
         if (!mailTo) {
             console.error(chalk.red('  ✗  Mail error: no recipient found. Please provide --mail-to or set VOIDEN_MAIL_TO.'));
-            process.exit(1);
+            process.exit(EXIT_USAGE_ERROR);
         }
         const smtpHost = opts.smtpHost || env.VOIDEN_SMTP_HOST;
         if (!smtpHost) {
             console.error(chalk.red('  ✗  Mail keys are missing. Please provide SMTP configuration (VOIDEN_SMTP_HOST).'));
-            process.exit(1);
+            process.exit(EXIT_USAGE_ERROR);
         }
     }
     if (!opts.csv && !opts.outputJson && !mailTo) {
@@ -727,14 +850,7 @@ reportCmd
     }
     let savedJsonPath;
     if (opts.outputJson) {
-        const jsonData = {
-            summary: {
-                total: results.length,
-                passed: results.filter(r => r.result.success).length,
-                failed: results.filter(r => !r.result.success).length,
-            },
-            requests: results.map(r => ({ file: r.file, ...r.result })),
-        };
+        const jsonData = buildJsonReport(results);
         try {
             mkdirSync(dirname(opts.outputJson), { recursive: true });
             writeFileSync(opts.outputJson, JSON.stringify(jsonData, null, 2) + '\n', 'utf-8');
@@ -755,7 +871,7 @@ reportCmd
         if (!smtpHost) {
             console.error(chalk.red('  ✗  SMTP configuration required for email reports.'));
             console.log(chalk.gray('     Set VOIDEN_SMTP_HOST in your environment or use --smtp-host.'));
-            process.exit(1);
+            process.exit(EXIT_USAGE_ERROR);
         }
         console.log(chalk.gray(`  ↑  Sending session report to ${mailTo} …`));
         try {
@@ -778,6 +894,14 @@ reportCmd
         }
     }
 });
+// Splits a `name` or `name@version` CLI arg. Plugin ids are plain slugs (no
+// leading `@`), so splitting on the first `@` is unambiguous.
+function parsePluginTarget(raw) {
+    const at = raw.indexOf('@');
+    if (at <= 0)
+        return { name: raw };
+    return { name: raw.slice(0, at), pinVersion: raw.slice(at + 1) };
+}
 // ── voiden-runner plugin ──────────────────────────────────────────────────────
 const pluginCmd = program
     .command('plugin')
@@ -786,34 +910,58 @@ const pluginCmd = program
 pluginCmd
     .command('install [names...]')
     .description('Install one or more plugins, or all core plugins\n\n' +
-    '  --all installs all core plugins only. Community plugins must be installed by name.\n\n' +
+    '  --all installs all core plugins only. Community plugins must be installed by name.\n' +
+    '  Pin an exact version with name@version (e.g. after `voiden-runner lock`, or to\n' +
+    '  match a "Block ... requires plugin X vY" error).\n\n' +
     '  Examples:\n' +
     '    voiden-runner plugin install --all\n' +
     '    voiden-runner plugin install voiden-scripting\n' +
-    '    voiden-runner plugin install apyhub-explorer\n')
+    '    voiden-runner plugin install voiden-rest-api@1.4.7\n')
     .option('--all', 'Install all core plugins (community plugins must be installed by name)')
-    .action(async (names, opts) => {
+    .action(async (rawNames, opts) => {
     const corePlugins = await getCorePlugins();
     const communityPlugins = await fetchCommunityPlugins();
     const targets = opts.all
-        ? corePlugins.map(p => p.name)
-        : names;
+        ? corePlugins.map(p => ({ name: p.name }))
+        : rawNames.map(parsePluginTarget);
     if (targets.length === 0) {
         console.error(chalk.red('Specify plugin name(s) or use --all'));
         console.log(chalk.gray('  Core: ' + corePlugins.map(p => p.name).join(', ')));
         if (communityPlugins.length > 0) {
             console.log(chalk.gray('  Community (install by name): ' + communityPlugins.map(p => p.id).join(', ')));
         }
-        process.exit(1);
+        process.exit(EXIT_USAGE_ERROR);
     }
     let installedCount = 0;
-    for (const name of targets) {
-        const coreDef = await findPlugin(name);
-        const commDef = !coreDef ? findCommunityPlugin(name, communityPlugins) : undefined;
-        if (!coreDef && !commDef) {
+    for (const { name, pinVersion } of targets) {
+        const foundCoreDef = await findPlugin(name);
+        const foundCommDef = !foundCoreDef ? findCommunityPlugin(name, communityPlugins) : undefined;
+        if (!foundCoreDef && !foundCommDef) {
             console.log(chalk.yellow(`  ⚠  Unknown plugin "${name}" — skipped`));
             continue;
         }
+        // A pinned version overrides the registry's "latest" default — this is what
+        // makes the fix-it command in version-mismatch errors ("plugin install x@y")
+        // actually able to install the exact version a file declares.
+        const coreDef = foundCoreDef && pinVersion ? { ...foundCoreDef, version: pinVersion } : foundCoreDef;
+        const commDef = foundCommDef && pinVersion ? { ...foundCommDef, version: pinVersion } : foundCommDef;
+        // Core plugins: only download if not already bundled/cached — unless a
+        // specific version was pinned, in which case always fetch that version.
+        if (coreDef && (pinVersion || !hasCoreRunner(name))) {
+            process.stdout.write(`  ↓  Downloading runner for ${chalk.bold(name)} …`);
+            try {
+                const ok = await downloadCoreRunner(coreDef.name, coreDef.repo, coreDef.runnerAsset, coreDef.version, false);
+                process.stdout.write('\r' + ' '.repeat(60) + '\r');
+                if (!ok) {
+                    console.log(chalk.red(`  ✗  No "${coreDef.runnerAsset}" asset in release v${coreDef.version} for "${name}"`));
+                    continue;
+                }
+            }
+            catch (err) {
+                process.stdout.write('\r' + chalk.red(`  ✗  Failed to download runner for "${name}": ${err?.message ?? String(err)}\n`));
+                continue;
+            }
+        }
         // Community plugins: download runner.js from the GitHub release first
         if (commDef) {
             process.stdout.write(`  ↓  Downloading runner for ${chalk.bold(name)} …`);
@@ -837,6 +985,13 @@ pluginCmd
             console.log(chalk.green(`  ✓  Installed`) + chalk.bold(` ${name}`) + chalk.gray(`  —  ${description}`));
             installedCount++;
         }
+        else if (pinVersion) {
+            // Re-running install with an explicit pin (e.g. to fix a version-mismatch)
+            // should still record the newly-downloaded version even if already "installed".
+            setPluginVersion(name, coreDef?.version ?? commDef?.version ?? pinVersion);
+            console.log(chalk.green(`  ✓  Installed`) + chalk.bold(` ${name}@${pinVersion}`));
+            installedCount++;
+        }
         else {
             console.log(chalk.gray(`  ·  Already installed`) + ` ${name}`);
         }
@@ -920,17 +1075,44 @@ pluginCmd
         console.log(chalk.gray(`  ${updatedCount} plugin(s) updated.`));
     }
 });
-// voiden-runner plugin uninstall <name>
+// voiden-runner plugin uninstall [names...] --all
 pluginCmd
-    .command('uninstall <name>')
-    .description('Remove an installed plugin\n\n  Example:\n    voiden-runner plugin uninstall voiden-scripting\n')
-    .action((name) => {
-    const removed = uninstallPlugin(name);
-    if (removed) {
-        console.log(chalk.green(`  ✓  Uninstalled`) + ` ${name}`);
+    .command('uninstall [names...]')
+    .description('Remove one or more installed plugins, or all installed plugins\n\n' +
+    '  Examples:\n' +
+    '    voiden-runner plugin uninstall voiden-scripting\n' +
+    '    voiden-runner plugin uninstall apyhub-explorer voiden-scripting\n' +
+    '    voiden-runner plugin uninstall --all\n')
+    .option('--all', 'Uninstall all installed plugins (core and community)')
+    .action(async (names, opts) => {
+    // Core plugins are bundled and enabled by default — they may never have
+    // an explicit store record even though they're clearly active, so --all
+    // (and named uninstalls of a bundled plugin) must include the full core
+    // registry, not just names that already happen to have a store record.
+    const corePlugins = await getCorePlugins();
+    const coreNames = new Set(corePlugins.map(p => p.name));
+    const targets = opts.all
+        ? [...new Set([...coreNames, ...getAllInstalledPlugins().map(p => p.name)])]
+        : names;
+    if (targets.length === 0) {
+        console.error(chalk.red('  Specify plugin name(s) or use --all'));
+        process.exit(EXIT_USAGE_ERROR);
+        return;
     }
-    else {
-        console.log(chalk.yellow(`  ⚠  Plugin "${name}" is not installed`));
+    let removedCount = 0;
+    for (const name of targets) {
+        const removed = uninstallPlugin(name, coreNames.has(name));
+        if (removed) {
+            console.log(chalk.green(`  ✓  Uninstalled`) + ` ${name}`);
+            removedCount++;
+        }
+        else {
+            console.log(chalk.yellow(`  ⚠  Plugin "${name}" is not installed`));
+        }
+    }
+    if (removedCount > 1) {
+        console.log();
+        console.log(chalk.gray(`  ${removedCount} plugin(s) uninstalled.`));
     }
 });
 // voiden-runner plugin enable [name] --all
@@ -944,9 +1126,11 @@ pluginCmd
     .action(async (name, opts) => {
     if (opts.all) {
         const store = readStore();
-        // Re-enable all explicitly disabled plugins (core + community)
+        // Re-enable all explicitly disabled plugins (core + community) — but not
+        // uninstalled ones; bringing those back requires an explicit `plugin
+        // install`, not a blanket --all enable.
         const disabled = Object.entries(store.installedPlugins)
-            .filter(([, r]) => !r.enabled)
+            .filter(([, r]) => !r.enabled && !r.uninstalled)
             .map(([n]) => n);
         // Also ensure all core plugins that were never in the store are treated as enabled (default)
         const disabledCoreNotInStore = [];
@@ -963,14 +1147,14 @@ pluginCmd
     }
     if (!name) {
         console.error(chalk.red('  Specify a plugin name or use --all'));
-        process.exit(1);
+        process.exit(EXIT_USAGE_ERROR);
     }
     const communityPlugins = await fetchCommunityPlugins();
     const commDef = findCommunityPlugin(name, communityPlugins);
     if (commDef && !hasCommunityRunner(name)) {
         console.log(chalk.red(`  ✗  Cannot enable "${name}" — runner not installed`));
         console.log(chalk.gray(`     Run: voiden-runner plugin install ${name}`));
-        process.exit(1);
+        process.exit(EXIT_USAGE_ERROR);
     }
     setPluginEnabled(name, true);
     console.log(chalk.green(`  ✓  Enabled`) + ` ${name}`);
@@ -1005,7 +1189,7 @@ pluginCmd
     }
     if (!name) {
         console.error(chalk.red('  Specify a plugin name or use --all'));
-        process.exit(1);
+        process.exit(EXIT_USAGE_ERROR);
         return;
     }
     setPluginEnabled(name, false);
@@ -1035,10 +1219,16 @@ pluginCmd
     console.log(DIVIDER);
     for (const def of corePlugins) {
         const record = store.installedPlugins[def.name];
-        const isDisabled = record !== undefined && !record.enabled;
-        const statusBadge = isDisabled
-            ? chalk.yellow('  · disabled')
-            : chalk.green('  ✓ enabled');
+        let statusBadge;
+        if (record?.uninstalled) {
+            statusBadge = chalk.gray('  not installed');
+        }
+        else if (record !== undefined && !record.enabled) {
+            statusBadge = chalk.yellow('  · disabled');
+        }
+        else {
+            statusBadge = chalk.green('  ✓ enabled');
+        }
         console.log(`  ${chalk.bold(def.name.padEnd(24))}${statusBadge}${updateBadge(def.name, def.version)}`);
         console.log(chalk.gray(`    ${def.description}`));
     }
@@ -1091,5 +1281,87 @@ pluginCmd
     }
     console.log();
 });
+// ── voiden-runner mcp ─────────────────────────────────────────────────────────
+//
+// Enables the AI-agent loop for CLI-only users (no Voiden app installed):
+// registers @voiden/mcp-server with Claude Code / Codex, and installs a
+// standalone skill teaching the run/verify/write-back workflow. The Voiden
+// app's own Settings toggle does the equivalent for desktop users, reusing
+// the same registration helpers from mcpInstall.ts.
+function resolveMcpTargets(opts) {
+    // Default to both when neither flag is given — a single command should be
+    // enough to "just enable this".
+    if (!opts.claude && !opts.codex)
+        return { claude: true, codex: true };
+    return { claude: Boolean(opts.claude), codex: Boolean(opts.codex) };
+}
+const mcpCmd = program
+    .command('mcp')
+    .description('Enable AI-agent integration — registers @voiden/mcp-server and installs a run/verify skill');
+mcpCmd
+    .command('install')
+    .description('Register @voiden/mcp-server with Claude Code and/or Codex, and install a skill teaching the run/verify/write-back loop.\n\n' +
+    '  Examples:\n' +
+    '    voiden-runner mcp install                                    # both Claude Code and Codex\n' +
+    '    voiden-runner mcp install --claude                           # Claude Code only\n' +
+    '    voiden-runner mcp install -p ./my-project                    # register against a specific project dir (default: cwd)\n' +
+    '    voiden-runner mcp install --local-server ./dist/index.js     # before publishing: point at a local build instead of npx\n')
+    .option('--claude', 'Install for Claude Code only')
+    .option('--codex', 'Install for Codex only')
+    .option('-p, --project <path>', 'Project directory to register the MCP server against', '.')
+    .option('--local-server <path>', 'Use `node <path>` instead of `npx -y @voiden/mcp-server` — for testing against a local build before it\'s published')
+    .action((opts) => {
+    const targets = resolveMcpTargets(opts);
+    const serverCommand = opts.localServer
+        ? { command: 'node', args: [resolve(opts.localServer), resolve(opts.project)] }
+        : undefined;
+    const installed = installMcpIntegration(opts.project, targets, RUNNER_SKILL_MARKDOWN, serverCommand);
+    if (installed.length === 0) {
+        console.log(chalk.yellow('  Nothing to install.'));
+        return;
+    }
+    console.log();
+    for (const target of installed) {
+        console.log(chalk.green(`  ✓  ${target === 'claude' ? 'Claude Code' : 'Codex'}`) + chalk.gray(`  —  skill installed, @voiden/mcp-server registered for ${resolve(opts.project)}`));
+    }
+    if (serverCommand) {
+        console.log(chalk.gray(`  Using local build: node ${serverCommand.args[0]}`));
+    }
+    console.log();
+    console.log(chalk.gray('  Restart Claude Code / Codex (or run /mcp) to pick up the new server.'));
+});
+mcpCmd
+    .command('uninstall')
+    .description('Remove the MCP server registration and skill installed by `mcp install`')
+    .option('--claude', 'Remove Claude Code integration only')
+    .option('--codex', 'Remove Codex integration only')
+    .option('-p, --project <path>', 'Project directory to unregister the MCP server from', '.')
+    .action((opts) => {
+    const targets = resolveMcpTargets(opts);
+    const removed = uninstallMcpIntegration(opts.project, targets);
+    if (removed.length === 0) {
+        console.log(chalk.yellow('  Nothing to remove.'));
+        return;
+    }
+    for (const target of removed) {
+        console.log(chalk.green(`  ✓  Removed`) + chalk.gray(` ${target === 'claude' ? 'Claude Code' : 'Codex'} integration`));
+    }
+});
+mcpCmd
+    .command('status')
+    .description('Show whether the MCP server + skill are installed for this project')
+    .option('-p, --project <path>', 'Project directory to check', '.')
+    .action((opts) => {
+    const status = getMcpStatus(opts.project);
+    console.log();
+    console.log(chalk.bold('  Claude Code'));
+    console.log(`    skill installed:     ${status.claude.skillInstalled ? chalk.green('yes') : chalk.gray('no')}`);
+    console.log(`    server registered:   ${status.claude.serverRegistered ? chalk.green('yes') : chalk.gray('no')}`);
+    console.log();
+    console.log(chalk.bold('  Codex'));
+    console.log(`    skill installed:      ${status.codex.skillInstalled ? chalk.green('yes') : chalk.gray('no')}`);
+    console.log(`    server registered:   ${status.codex.serverRegistered ? chalk.green('yes') : chalk.gray('no')}`);
+    console.log();
+});
 program.parse();
 //# sourceMappingURL=index.js.map