@caoscompanybr/merlin 3.5.0

package/.merlin-core/tools/disable-module.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/**
+ * disable-module.mjs — the Merlin Modules disable/uninstall orchestrator (§7.5).
+ *
+ * "Flag-off ≠ uninstall": a naive disable leaves functions/schedulers/webhooks/data
+ * alive, and re-enabling over half-torn-down state corrupts it. So disable is a
+ * distinct, **reversible** lifecycle (disable flag → pause schedulers → revoke
+ * webhooks → archive-not-delete), and the destructive teardown is a **separate
+ * HIGH-stake `--purge`**. Mirror of provision-module: framework-generic, dry-run by
+ * default, dispatched by `deploy_kind`.
+ *
+ *  - `framework-skill` (EXECUTES): on --apply, removes the id from config/modules.enabled[].
+ *  - cloud deploy_kinds (PLAN-EMIT): drive a Deployer (default PlanOnlyDeployer prints
+ *    the reversible teardown; `--purge` adds the irreversible delete step). Real
+ *    execution is delegated to the platform adapter / operator runbook.
+ *
+ * Note (platform-side): a disabled module's functions must short-circuit on the flag
+ * (the invocation guard) — the framework cannot add guards to platform functions.
+ *
+ *   node disable-module.mjs --module=scraping [--apply]
+ *   node disable-module.mjs --module=editorial --workspace=ws-x [--apply] [--purge]
+ *
+ * @module tools/disable-module
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadCatalog } from "./modules-catalog.mjs";
+import { disableModule as deactivateInConfig } from "./lib/modules-activation.mjs";
+import { PlanOnlyDeployer } from "./lib/deployer.mjs";
+
+const FRAMEWORK_CORE = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/**
+ * @param {object} opts
+ * @param {string} opts.moduleId @param {string} [opts.projectRoot]
+ * @param {string} [opts.merlinCore] @param {string} [opts.modulesDir]
+ * @param {string} [opts.workspace] - REQUIRED for cloud deploy_kinds
+ * @param {string} [opts.firebaseProject]
+ * @param {boolean} [opts.apply=false] @param {boolean} [opts.purge=false]
+ * @param {object} [opts.deployer] @param {function} [opts.log]
+ */
+export async function disableModule(opts = {}) {
+  const { moduleId, apply = false, purge = false } = opts;
+  const projectRoot = opts.projectRoot || process.cwd();
+  const merlinCore = opts.merlinCore || join(projectRoot, ".merlin-core");
+  const modulesDir = opts.modulesDir || join(merlinCore, "modules");
+  const log = opts.log || (() => {});
+  const deployer = opts.deployer || new PlanOnlyDeployer({ log });
+
+  if (!moduleId) return { ok: false, error: "missing --module" };
+
+  const catalog = loadCatalog({ modulesDir, merlinCore });
+  const manifest = catalog.modules.find((m) => m.id === moduleId);
+  if (!manifest) {
+    return {
+      ok: false,
+      moduleId,
+      error: `module "${moduleId}" not found or invalid in ${modulesDir}`,
+    };
+  }
+
+  const base = { moduleId, deploy_kind: manifest.deploy_kind, purge };
+
+  // --- framework-skill: EXECUTES (config soft-toggle) ---
+  if (manifest.deploy_kind === "framework-skill") {
+    const deactivation = deactivateInConfig(projectRoot, moduleId, { apply });
+    if (deactivation.error) {
+      return { ...base, ok: false, deactivation, error: deactivation.error };
+    }
+    return {
+      ...base,
+      ok: true,
+      applied: Boolean(apply && deactivation.changed),
+      deactivation,
+    };
+  }
+
+  // Only `firebase` has a teardown path today (the Deployer contract is
+  // Firebase-shaped). Other cloud kinds tear down via their own operator
+  // runbooks; refuse rather than emit a bogus Firebase teardown plan.
+  if (manifest.deploy_kind !== "firebase") {
+    return {
+      ...base,
+      ok: false,
+      error: `deploy_kind '${manifest.deploy_kind}' has no teardown path yet — only framework-skill and firebase are supported`,
+    };
+  }
+
+  // --- cloud deploy_kinds: PLAN-EMIT (require explicit workspace) ---
+  if (!opts.workspace) {
+    return {
+      ...base,
+      ok: false,
+      error:
+        "explicit --workspace is required for a cloud deploy_kind (no tenant default)",
+    };
+  }
+
+  const ctx = {
+    workspace: opts.workspace,
+    firebaseProject: opts.firebaseProject,
+    apply,
+  };
+  const steps = [];
+  steps.push(await deployer.disableFlag(manifest, ctx)); // reversible
+  steps.push(await deployer.pauseSchedulers(manifest, ctx));
+  steps.push(await deployer.revokeWebhooks(manifest, ctx));
+  steps.push(await deployer.archiveData(manifest, ctx));
+  if (purge) steps.push(await deployer.purge(manifest, ctx)); // irreversible — only with --purge
+  const executed = steps.some((s) => s && s.executed);
+
+  return {
+    ...base,
+    ok: true,
+    workspace: opts.workspace,
+    reversible: !purge,
+    steps,
+    applied: Boolean(apply && executed),
+    note:
+      deployer instanceof PlanOnlyDeployer
+        ? `plan-only: cloud teardown delegated to the platform adapter / operator runbook${purge ? " — PURGE is IRREVERSIBLE" : ""}`
+        : undefined,
+  };
+}
+
+// --- CLI ---
+if (process.argv[1] && process.argv[1].endsWith("disable-module.mjs")) {
+  const args = process.argv.slice(2);
+  const val = (flag) => {
+    const eq = args.find((a) => a.startsWith(`${flag}=`));
+    if (eq) return eq.split("=").slice(1).join("=");
+    const i = args.indexOf(flag);
+    return i >= 0 && args[i + 1] && !args[i + 1].startsWith("--")
+      ? args[i + 1]
+      : undefined;
+  };
+  const result = await disableModule({
+    projectRoot: process.cwd(),
+    merlinCore: FRAMEWORK_CORE,
+    moduleId: val("--module"),
+    workspace: val("--workspace"),
+    firebaseProject: val("--firebase-project"),
+    apply: args.includes("--apply"),
+    purge: args.includes("--purge"),
+    log: (m) => console.log(m),
+  });
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(result.ok ? 0 : 1);
+}

package/.merlin-core/tools/lib/deployer.mjs

@@ -0,0 +1,131 @@
+/**
+ * deployer.mjs — the Deployer adapter seam (v3.5).
+ *
+ * The framework is generic and holds no tenant cloud credentials, so it does NOT
+ * execute cloud `deploy_kind`s. Instead provision-module.mjs drives a Deployer:
+ * the framework ships `PlanOnlyDeployer` (prints the exact command each step WOULD
+ * run, executes nothing), and the platform (`caos-company-platform`) implements a
+ * real adapter later. The plan a PlanOnlyDeployer prints IS the spec that adapter
+ * implements.
+ *
+ * Deployer contract (each method takes (manifest, ctx) and returns a step result
+ * `{ name, command, executed }`, except `probe` which returns a verify verdict):
+ *   deployFunctions, composeAndDeployRules, setSecrets, deployHosting, seed,
+ *   probe, flipFlagAndWriteInstalledModules.
+ *
+ * @module tools/lib/deployer
+ */
+
+const proj = (ctx) => ctx.firebaseProject || "<firebase-project>";
+
+export class PlanOnlyDeployer {
+  constructor({ log } = {}) {
+    this.log = log || (() => {});
+    this.steps = [];
+  }
+
+  _plan(name, command) {
+    const step = { name, command, executed: false };
+    this.steps.push(step);
+    this.log(`  PLAN ${name}: ${command}`);
+    return step;
+  }
+
+  async deployFunctions(m, ctx) {
+    const codebase = (m.tenant && m.tenant.functions_codebase) || m.id;
+    return this._plan(
+      "functions",
+      `firebase deploy --only functions:${codebase} --project ${proj(ctx)}`,
+    );
+  }
+
+  async composeAndDeployRules(m, ctx) {
+    return this._plan(
+      "rules",
+      `compose-rules --enabled …,${m.id} (test gate) && firebase deploy --only firestore:rules,firestore:indexes --project ${proj(ctx)}`,
+    );
+  }
+
+  async setSecrets(m, ctx) {
+    const secrets =
+      ((m.tenant && m.tenant.secrets) || []).join(",") || "<none>";
+    return this._plan(
+      "secrets",
+      `firebase functions:secrets:set ${secrets} --project ${proj(ctx)}`,
+    );
+  }
+
+  async deployHosting(m, ctx) {
+    const target =
+      m.tenant && m.tenant.frontend && m.tenant.frontend.hosting_target;
+    return this._plan(
+      "hosting",
+      target
+        ? `firebase deploy --only hosting:${target} --project ${proj(ctx)}`
+        : "(no hosting target — in-platform SPA)",
+    );
+  }
+
+  async seed(m, ctx) {
+    const script = (m.tenant && m.tenant.seed_script) || `seed-${m.id}.mjs`;
+    return this._plan("seed", `${script} --apply --workspace=${ctx.workspace}`);
+  }
+
+  async probe() {
+    // verifyModule's cloud path — planned, never executed by PlanOnlyDeployer.
+    return {
+      ok: false,
+      planned: true,
+      checks: [
+        { name: "function-probe", ok: false, detail: "planned: callable ping" },
+        { name: "rules-read", ok: false, detail: "planned: rules get()" },
+        { name: "secret-present", ok: false, detail: "planned: secret exists" },
+      ],
+    };
+  }
+
+  async flipFlagAndWriteInstalledModules(m, ctx) {
+    return this._plan(
+      "activate",
+      `set modules.${m.id}=true (dot-path merge, never clobber) + write installedModules/${m.id} for workspace ${ctx.workspace}`,
+    );
+  }
+
+  // --- teardown (disable/uninstall, §7.5) — all reversible except purge ---
+
+  async disableFlag(m, ctx) {
+    return this._plan(
+      "disable-flag",
+      `set modules.${m.id}=false (dot-path merge) + installedModules/${m.id}.status="disabled" (NEVER delete the doc) for workspace ${ctx.workspace}`,
+    );
+  }
+
+  async pauseSchedulers(m, ctx) {
+    return this._plan(
+      "pause-schedulers",
+      `pause scheduled functions for ${m.id} (project ${proj(ctx)}) — stop crons from firing on disabled data`,
+    );
+  }
+
+  async revokeWebhooks(m, ctx) {
+    return this._plan(
+      "revoke-webhooks",
+      `revoke/rotate inbound webhook secrets for ${m.id} (project ${proj(ctx)}) — stop external mutations`,
+    );
+  }
+
+  async archiveData(m, ctx) {
+    return this._plan(
+      "archive-data",
+      `mark ${m.id} data archived (NOT deleted) in workspace ${ctx.workspace} — re-enable stays safe`,
+    );
+  }
+
+  async purge(m, ctx) {
+    // HIGH-stake destructive teardown — emitted only under --purge.
+    return this._plan(
+      "purge",
+      `DELETE functions:${(m.tenant && m.tenant.functions_codebase) || m.id} + collections ${((m.tenant && m.tenant.collections) || []).join(",") || "<none>"} + secrets for ${m.id} (project ${proj(ctx)}) — IRREVERSIBLE`,
+    );
+  }
+}

package/.merlin-core/tools/lib/modules-activation.mjs

@@ -0,0 +1,225 @@
+/**
+ * modules-activation.mjs — read/write the L2 soft-activation list for Merlin
+ * Modules (`modules.enabled[]` in project-config.yaml).
+ *
+ * This is **module soft-activation** — distinct from core/licensing/activation.js
+ * (which is *license* activation). Different dir, different concern.
+ *
+ * `framework-skill` modules activate by being listed here (NOT a Firestore flag).
+ * provision-module.mjs calls `enableModule()` as the final step of a passing
+ * provision. Reads merge L2 (project-config.yaml) + L3 (local-config.yaml);
+ * writes target L2. To preserve the heavily-commented YAML we do a surgical text
+ * insertion rather than a parse → dump round-trip (which would drop comments).
+ *
+ * @module tools/lib/modules-activation
+ */
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import yaml from "js-yaml";
+
+const configPath = (projectRoot) =>
+  join(projectRoot, ".merlin-core", "project-config.yaml");
+const localConfigPath = (projectRoot) =>
+  join(projectRoot, ".merlin-core", "local-config.yaml");
+
+function readEnabledFrom(file) {
+  if (!existsSync(file)) return [];
+  let doc;
+  try {
+    doc = yaml.load(readFileSync(file, "utf8")) || {};
+  } catch {
+    return [];
+  }
+  const enabled = doc && doc.modules && doc.modules.enabled;
+  return Array.isArray(enabled)
+    ? enabled.filter((x) => typeof x === "string")
+    : [];
+}
+
+/** The effective enabled set: L2 (project-config) ∪ L3 (local-config). */
+export function readEnabledModules(projectRoot) {
+  return [
+    ...new Set([
+      ...readEnabledFrom(configPath(projectRoot)),
+      ...readEnabledFrom(localConfigPath(projectRoot)),
+    ]),
+  ];
+}
+
+/**
+ * Surgically insert `- <id>` into the `modules.enabled` list of a YAML string.
+ * Handles two shapes of the `enabled:` key under a top-level `modules:` block:
+ *   (A) `  enabled: []`        → converts to a block list
+ *   (B) `  enabled:` + items   → appends after the last item
+ * Returns the new text, or null if the `modules.enabled` key was not found.
+ */
+export function insertEnabled(text, id) {
+  const lines = text.split("\n");
+  const modIdx = lines.findIndex((l) => /^modules:\s*$/.test(l));
+  if (modIdx === -1) return null;
+
+  // Find `enabled:` within the indented modules block.
+  let enIdx = -1;
+  let enIndent = "";
+  for (let i = modIdx + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === "") continue;
+    const indentMatch = line.match(/^(\s+)/);
+    if (!indentMatch) break; // dedented back to col 0 → left the modules block
+    const m = line.match(/^(\s+)enabled:\s*(\[\s*\])?\s*$/);
+    if (m) {
+      enIdx = i;
+      enIndent = m[1];
+      break;
+    }
+  }
+  if (enIdx === -1) return null;
+
+  const itemIndent = enIndent + "  ";
+  const isInlineEmpty = /\[\s*\]\s*$/.test(lines[enIdx]);
+
+  if (isInlineEmpty) {
+    lines[enIdx] = `${enIndent}enabled:`;
+    lines.splice(enIdx + 1, 0, `${itemIndent}- ${id}`);
+    return lines.join("\n");
+  }
+
+  // Block form: find the last contiguous item line under enabled:.
+  let lastItem = enIdx;
+  for (let i = enIdx + 1; i < lines.length; i++) {
+    if (lines[i].startsWith(`${itemIndent}- `)) {
+      lastItem = i;
+    } else if (lines[i].trim() === "") {
+      continue;
+    } else {
+      break;
+    }
+  }
+  lines.splice(lastItem + 1, 0, `${itemIndent}- ${id}`);
+  return lines.join("\n");
+}
+
+/**
+ * Add `id` to L2 `modules.enabled`. Idempotent. Dry-run by default.
+ * @returns {{changed:boolean, apply:boolean, enabled:string[], diff:string|null, error?:string}}
+ */
+export function enableModule(projectRoot, id, { apply = false } = {}) {
+  const file = configPath(projectRoot);
+  const current = readEnabledFrom(file);
+
+  if (current.includes(id)) {
+    return { changed: false, apply, enabled: current, diff: null };
+  }
+
+  if (!existsSync(file)) {
+    return {
+      changed: false,
+      apply,
+      enabled: current,
+      diff: null,
+      error: `project-config.yaml not found at ${file}`,
+    };
+  }
+
+  const text = readFileSync(file, "utf8");
+  const next = insertEnabled(text, id);
+  if (next === null) {
+    return {
+      changed: false,
+      apply,
+      enabled: current,
+      diff: null,
+      error: "could not locate `modules.enabled` in project-config.yaml",
+    };
+  }
+
+  const diff = `+ modules.enabled: + ${id}`;
+  if (!apply) {
+    return { changed: true, apply: false, enabled: [...current, id], diff };
+  }
+
+  writeFileSync(file, next);
+  return { changed: true, apply: true, enabled: [...current, id], diff };
+}
+
+/**
+ * Remove `- <id>` from the `modules.enabled` list of a YAML string. If that was
+ * the last item, collapse `enabled:` back to `enabled: []`. Returns the new text,
+ * or null if the key was not found. Mirror of insertEnabled.
+ */
+export function removeEnabled(text, id) {
+  const lines = text.split("\n");
+  const modIdx = lines.findIndex((l) => /^modules:\s*$/.test(l));
+  if (modIdx === -1) return null;
+
+  let enIdx = -1;
+  let enIndent = "";
+  for (let i = modIdx + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === "") continue;
+    if (!/^\s/.test(line)) break; // dedented out of the modules block
+    const m = line.match(/^(\s+)enabled:\s*(\[\s*\])?\s*$/);
+    if (m) {
+      enIdx = i;
+      enIndent = m[1];
+      break;
+    }
+  }
+  if (enIdx === -1) return null;
+
+  const itemIndent = enIndent + "  ";
+  const itemRe = new RegExp(`^${itemIndent}- ${id}\\s*$`);
+  const removeAt = lines.findIndex((l, i) => i > enIdx && itemRe.test(l));
+  if (removeAt === -1) return null; // id not present
+  lines.splice(removeAt, 1);
+
+  // If no items remain under enabled:, collapse back to an inline empty list.
+  const anyItem = lines.some(
+    (l, i) => i > enIdx && l.startsWith(`${itemIndent}- `),
+  );
+  if (!anyItem) lines[enIdx] = `${enIndent}enabled: []`;
+  return lines.join("\n");
+}
+
+/**
+ * Remove `id` from L2 `modules.enabled`. Idempotent. Dry-run by default.
+ * @returns {{changed:boolean, apply:boolean, enabled:string[], diff:string|null, error?:string}}
+ */
+export function disableModule(projectRoot, id, { apply = false } = {}) {
+  const file = configPath(projectRoot);
+  const current = readEnabledFrom(file);
+
+  if (!current.includes(id)) {
+    return { changed: false, apply, enabled: current, diff: null };
+  }
+  if (!existsSync(file)) {
+    return {
+      changed: false,
+      apply,
+      enabled: current,
+      diff: null,
+      error: `project-config.yaml not found at ${file}`,
+    };
+  }
+
+  const text = readFileSync(file, "utf8");
+  const next = removeEnabled(text, id);
+  if (next === null) {
+    return {
+      changed: false,
+      apply,
+      enabled: current,
+      diff: null,
+      error: "could not remove from `modules.enabled` in project-config.yaml",
+    };
+  }
+
+  const remaining = current.filter((x) => x !== id);
+  const diff = `- modules.enabled: - ${id}`;
+  if (!apply) {
+    return { changed: true, apply: false, enabled: remaining, diff };
+  }
+  writeFileSync(file, next);
+  return { changed: true, apply: true, enabled: remaining, diff };
+}

package/.merlin-core/tools/merlin-tools.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * Merlin-Tools CLI -- Deterministic operations for Merlin framework.
+ *
+ * Provides reliable, repeatable operations that don't need LLM parsing.
+ * All output is JSON by default (machine-readable). Use --human for
+ * formatted output.
+ *
+ * Usage:
+ *   node .merlin-core/tools/merlin-tools.js <command> [args...]
+ *
+ * Commands:
+ *   index                     Rebuild thoughts INDEX.json and INDEX.md
+ *   archive [--days N]        Archive terminal thoughts to .archive/ (--dry-run)
+ *   state [key] [value]       Read or write context bridge state
+ *   frontmatter <file>        Extract YAML frontmatter from markdown file
+ *   list-agents               List all registered agents
+ *   list-skills               List all skills with activation keywords
+ *   validate <type> <file>    Validate file against schema
+ *   yolo on|off               Toggle YOLO mode
+ *   doc-sync                  Synchronize documentation
+ *   migrate-alkimia [path]    Migrate .synapse/ dirs to .alkimia/
+ *   upgrade <path>            Upgrade a satellite project to current version
+ *   eval-skill <name>         Evaluate a skill against its evals
+ *   modules                   List + validate the Merlin Modules catalog
+ *   provision --module=<id>   Provision (unlock) a Merlin Module (dry-run default)
+ *   disable --module=<id>     Disable/uninstall a Merlin Module (reversible; --purge to delete)
+ *
+ * Flags:
+ *   --human                   Format output for humans (tables, colors)
+ *   --help                    Show this help message
+ *
+ * @module tools/merlin-tools
+ * @version 3.0.0
+ */
+
+"use strict";
+
+const path = require("path");
+
+// Resolve project root (tools lives at .merlin-core/tools/)
+const PROJECT_ROOT = path.resolve(__dirname, "..", "..");
+
+const COMMANDS = {
+  index: "./commands/index-thoughts",
+  archive: "./commands/archive-thoughts",
+  state: "./commands/state",
+  frontmatter: "./commands/frontmatter",
+  "list-agents": "./commands/list",
+  "list-skills": "./commands/list",
+  validate: "./commands/validate",
+  yolo: "./commands/yolo",
+  "doc-sync": "./commands/doc-sync",
+  "migrate-alkimia": "./commands/migrate-alkimia",
+  upgrade: "./commands/upgrade",
+  install: "./commands/install",
+  convert: "./commands/convert",
+  backup: "./commands/backup",
+  "eval-skill": "./commands/eval-skill",
+  "sync-bridges": "./commands/sync-bridges",
+  "validate-recipes": "./commands/validate-recipes",
+  "certify-process": "./commands/certify-process",
+  "run-process": "./commands/run-process",
+  "install-remote-approve": "./commands/install-remote-approve",
+  heartbeat: "./commands/heartbeat",
+  cron: "./commands/cron",
+  "prune-feedback": "./commands/prune-feedback",
+  modules: "./commands/modules",
+  provision: "./commands/provision",
+  disable: "./commands/disable",
+  activate: "./commands/activate",
+  license: "./commands/license",
+};
+
+function showHelp() {
+  console.log(
+    `
+Merlin-Tools CLI v3.0.0 — Deterministic operations for Merlin framework
+
+Usage: node .merlin-core/tools/merlin-tools.js <command> [args...]
+
+Commands:
+  index                     Rebuild thoughts INDEX.json and INDEX.md
+  archive [--days N]        Archive terminal thoughts to .archive/ (--dry-run)
+  state [key] [value]       Read or write context bridge state
+  frontmatter <file>        Extract YAML frontmatter from markdown file
+  list-agents               List all registered agents
+  list-skills               List all skills with activation keywords
+  validate <type> <file>    Validate file against schema (skill|agent|command|workflow)
+  migrate-alkimia [path]    Migrate .synapse/ dirs to .alkimia/ (--all, --dry-run)
+  upgrade <path>            Upgrade a satellite project to current Merlin version (--dry-run, --flatten-nesting)
+  install [path]            Install Merlin into a project (auto-detects source; defaults target to cwd)
+  convert [path]            Convert a project to Merlin (no existing .merlin-core/ in target)
+  backup [path]             Backup project-owned data to .merlin-backups/latest/ (--dry-run)
+  eval-skill <name>         Evaluate a skill against its evals/evals.json test cases
+  sync-bridges              Regenerate .claude/commands/ from .merlin-core/commands/ (--dry-run)
+  certify-process <file>    Run the 6-gate certification pipeline on a PROCESSO (--rehearsed, --approve "Name")
+  run-process <slug>        Execute a certified PROCESSO locally — dry-run by default (--live to execute)
+  install-remote-approve [path]  Enable remote Approve/Deny for a project (--tools, --dashboard-url, --disable)
+  heartbeat run             Run a single proactive heartbeat beat (v3.4 autonomy)
+  cron <list|add|run|remove|due|watchdog>  Manage native scheduled agent turns (v3.4)
+  prune-feedback [--limit N] [--dry-run]   Enforce FIFO-N retention on feedback (v3.4)
+  modules                   List + validate the Merlin Modules catalog + framework refs (v3.5)
+  provision --module=<id>   Provision (unlock) a Merlin Module — dispatched by deploy_kind, dry-run default (v3.5)
+  disable --module=<id>     Disable/uninstall a Merlin Module — reversible teardown; --purge for the irreversible delete (v3.5)
+  activate <KEY> --email <e>  Redeem a license key on this machine (v3.5)
+  license [--refresh]       Show cached license status, or --refresh to heartbeat now (v3.5)
+
+Flags:
+  --human                   Format output for humans
+  --help                    Show this help message
+  `.trim(),
+  );
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes("--help")) {
+    showHelp();
+    process.exit(0);
+  }
+
+  const command = args[0];
+  const commandArgs = args.slice(1);
+  const humanMode = commandArgs.includes("--human");
+  const filteredArgs = commandArgs.filter((a) => a !== "--human");
+
+  const modulePath = COMMANDS[command];
+  if (!modulePath) {
+    console.error(`Unknown command: ${command}`);
+    console.error(`Run with --help to see available commands.`);
+    process.exit(1);
+  }
+
+  try {
+    const mod = require(modulePath);
+    const result = await mod.run(command, filteredArgs, PROJECT_ROOT);
+
+    if (humanMode && typeof mod.formatHuman === "function") {
+      console.log(mod.formatHuman(result));
+    } else {
+      console.log(JSON.stringify(result, null, 2));
+    }
+
+    process.exit(0);
+  } catch (error) {
+    console.error(JSON.stringify({ error: error.message }, null, 2));
+    process.exit(1);
+  }
+}
+
+main();