@brainervirus/workit-core 2.8.0 → 3.0.0

package/src/core/uninstall.ts

@@ -1,544 +0,0 @@
-// Uninstall planning + apply (Task 8): the exact inverse of the setup/registration
-// write set. planUninstall is a pure reader — it classifies the installed state
-// and returns the actions apply WOULD perform; applyUninstall dispatches only
-// reviewed plan actions, preserves unrelated user config byte-for-byte
-// (write-only-if-changed), and never touches ~/.config/workit
-// (CA-11, CA-12, CA-13, CA-14). Homes are injectable exactly like setup/doctor
-// path options (D-07): tests pass explicit paths and no default ever resolves
-// to a real user directory in tests.
-import { existsSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { isWorkitPlugin } from "./registration";
-import {
-  claudeWorkitInstalls,
-  findHostExecutable,
-  runHostCommand,
-  type HostCommandRunner,
-} from "./host-install";
-
-export type UninstallHost = "opencode" | "cursor" | "codex" | "pi" | "claude-code";
-
-export type UninstallAction =
-  | { kind: "edit-json-remove"; path: string; detail: string }
-  | { kind: "remove-dir"; path: string; detail: string }
-  /** A host-native uninstall (Claude Code owns its plugin cache and registry). */
-  | {
-      kind: "host-command";
-      path: string;
-      detail: string;
-      command: "claude";
-      args: string[];
-      /** The project a project/local-scope uninstall must run from; null for user scope. */
-      cwd: string | null;
-    };
-
-export type UninstallHostPlan = {
-  host: UninstallHost;
-  installed: boolean;
-  actions: UninstallAction[];
-};
-
-export type UninstallPlan = {
-  hosts: UninstallHostPlan[];
-};
-
-export type UninstallResultStatus = "removed" | "skipped" | "failed";
-
-export type UninstallResultEntry = {
-  host: UninstallHost;
-  path: string;
-  status: UninstallResultStatus;
-  detail?: string;
-};
-
-export type UninstallResult = {
-  ok: boolean;
-  entries: UninstallResultEntry[];
-};
-
-/** Injectable homes mirroring setup's ApplySetupOptions subset (D-07). */
-export type UninstallPaths = {
-  home?: string;
-  env?: NodeJS.ProcessEnv;
-  opencodeConfig?: string;
-  cursorSettings?: string;
-  cursorMcp?: string;
-  cursorPluginDir?: string;
-  /** Injectable host-command runner for host-native uninstall actions. */
-  runHostCommand?: HostCommandRunner;
-  /** Project directory for Claude Code project/local-scope installs (default: process cwd). */
-  cwd?: string;
-};
-
-type ResolvedUninstall = {
-  opencodeConfig: string;
-  cursorSettings: string;
-  cursorMcp: string;
-  cursorPluginDir: string;
-  codexPluginDir: string;
-  piConfig: string;
-};
-
-const resolveUninstallPaths = (options: UninstallPaths = {}): ResolvedUninstall => {
-  // Same chain as setup.ts (parity advisory): explicit option > env.HOME >
-  // homedir. No process.env tier — an ambient HOME must never leak past an
-  // explicitly empty injected env.
-  const home = options.home ?? options.env?.HOME ?? os.homedir();
-  return {
-    opencodeConfig:
-      options.opencodeConfig ?? path.join(home, ".config", "opencode", "opencode.json"),
-    cursorSettings: options.cursorSettings ?? path.join(home, ".cursor", "settings.json"),
-    cursorMcp: options.cursorMcp ?? path.join(home, ".cursor", "mcp.json"),
-    cursorPluginDir:
-      options.cursorPluginDir ?? path.join(home, ".cursor", "plugins", "local", "workit"),
-    codexPluginDir: path.join(home, ".codex", "plugins", "workit"),
-    piConfig: path.join(home, ".pi", "config.json"),
-  };
-};
-
-const isRecord = (v: unknown): v is Record<string, unknown> =>
-  v !== null && typeof v === "object" && !Array.isArray(v);
-
-type Existing =
-  | { kind: "missing" }
-  | { kind: "malformed"; error: string }
-  | { kind: "record"; value: Record<string, unknown> };
-
-const readJsonRecord = (file: string): Existing => {
-  let raw: string;
-  try {
-    raw = readFileSync(file, "utf8");
-  } catch {
-    // A read-permission error (EACCES) must not look like a missing file (same
-    // disambiguation as setup.ts readExisting): classify it malformed so plan
-    // keeps the host installed and apply reports Failed with the path untouched.
-    if (existsSync(file)) return { kind: "malformed", error: `${file} is not readable` };
-    return { kind: "missing" };
-  }
-  try {
-    const value = JSON.parse(raw);
-    return isRecord(value)
-      ? { kind: "record", value }
-      : { kind: "malformed", error: `${file} is not a JSON object` };
-  } catch {
-    return { kind: "malformed", error: `${file} is not valid JSON` };
-  }
-};
-
-// Mirror of mergeCursorEnabledPlugins' strip(): trailing-separator-insensitive
-// comparison that guards the filesystem root.
-const stripTrailingSep = (p: string): string => {
-  const j = path.join(p);
-  return path.dirname(j) === j ? j : j.replace(/[\\/]+$/, "");
-};
-
-const CURSOR_LEGACY_IDENTITIES = ["workflow-toolkit", "local/workflow-toolkit"];
-
-// Inverse of mergeCursorSettings: drop workit identities from enabled_plugins,
-// drop the canonical plugin dir entry from plugin_dirs. Returns the next record
-// plus whether anything changed (plan/apply share this so outcomes match).
-function cleanCursorSettings(
-  settings: Record<string, unknown>,
-  pluginDir: string,
-): { next: Record<string, unknown>; changed: boolean } {
-  const next = { ...settings };
-  let changed = false;
-  if (isRecord(next.enabled_plugins)) {
-    const enabled = { ...next.enabled_plugins };
-    for (const identity of ["workit", ...CURSOR_LEGACY_IDENTITIES]) {
-      if (identity in enabled) {
-        delete enabled[identity];
-        changed = true;
-      }
-    }
-    next.enabled_plugins = enabled;
-  }
-  if (Array.isArray(next.plugin_dirs)) {
-    const canonical = stripTrailingSep(pluginDir);
-    const kept = (next.plugin_dirs as unknown[])
-      .map(String)
-      .filter((d) => stripTrailingSep(d) !== canonical);
-    if (kept.length !== (next.plugin_dirs as unknown[]).length) {
-      next.plugin_dirs = kept;
-      changed = true;
-    }
-  }
-  return { next, changed };
-}
-
-// Inverse of mergeOpenCodeConfig's plugin registration: remove every workit
-// identity from the plugin list.
-function cleanOpenCodeConfig(config: Record<string, unknown>): {
-  next: Record<string, unknown>;
-  changed: boolean;
-} {
-  const next = { ...config };
-  let changed = false;
-  if (Array.isArray(next.plugin)) {
-    const plugins = (next.plugin as unknown[]).map(String);
-    const kept = plugins.filter((p) => !isWorkitPlugin(p));
-    if (kept.length !== plugins.length) {
-      next.plugin = kept;
-      changed = true;
-    }
-  } else if (typeof next.plugin === "string" && isWorkitPlugin(next.plugin)) {
-    delete next.plugin;
-    changed = true;
-  }
-  return { next, changed };
-}
-
-// Inverse of mergeCursorMcp: drop the canonical server name and its legacy twin.
-function cleanCursorMcp(mcp: Record<string, unknown>): {
-  next: Record<string, unknown>;
-  changed: boolean;
-} {
-  const next = { ...mcp };
-  let changed = false;
-  if (isRecord(next.mcpServers)) {
-    const servers = { ...next.mcpServers };
-    for (const name of ["workit", "workflow-toolkit"]) {
-      if (name in servers) {
-        delete servers[name];
-        changed = true;
-      }
-    }
-    next.mcpServers = servers;
-  }
-  return { next, changed };
-}
-
-// Shared edit-json-remove executor for plan parity: parse → clean by target →
-// report change without writing.
-type JsonCleaner = (record: Record<string, unknown>) => {
-  next: Record<string, unknown>;
-  changed: boolean;
-};
-
-function cleanPiConfig(config: Record<string, unknown>): {
-  next: Record<string, unknown>;
-  changed: boolean;
-} {
-  const next = { ...config };
-  let changed = false;
-  for (const key of ["extensions", "skills"] as const) {
-    const value = next[key];
-    if (!Array.isArray(value)) continue;
-    const kept = value.filter((entry) => !String(entry).includes("workit"));
-    if (kept.length !== value.length) {
-      next[key] = kept;
-      changed = true;
-    }
-  }
-  const pi = isRecord(next.pi) ? { ...next.pi } : null;
-  if (pi && Array.isArray(pi.extensions)) {
-    const kept = pi.extensions.filter((entry) => !String(entry).includes("workit"));
-    if (kept.length !== pi.extensions.length) {
-      pi.extensions = kept;
-      next.pi = pi;
-      changed = true;
-    }
-  }
-  return { next, changed };
-}
-
-const jsonCleanerFor = (target: string, res: ResolvedUninstall): JsonCleaner | null => {
-  if (target === res.opencodeConfig) return cleanOpenCodeConfig;
-  if (target === res.cursorSettings) return (r) => cleanCursorSettings(r, res.cursorPluginDir);
-  if (target === res.cursorMcp) return cleanCursorMcp;
-  if (target === res.piConfig) return cleanPiConfig;
-  return null;
-};
-
-/** Pure planner: reports the uninstall actions Apply would perform. Reads host
- *  config files but never writes; ~/.config/workit is never an action target. */
-export function planUninstall(paths: UninstallPaths = {}): UninstallPlan {
-  const res = resolveUninstallPaths(paths);
-
-  const ocExisting = readJsonRecord(res.opencodeConfig);
-  const ocDirty =
-    ocExisting.kind === "malformed" ||
-    (ocExisting.kind === "record" && cleanOpenCodeConfig(ocExisting.value).changed);
-  const opencode: UninstallHostPlan = {
-    host: "opencode",
-    installed: ocDirty,
-    actions: ocDirty
-      ? [
-          {
-            kind: "edit-json-remove",
-            path: res.opencodeConfig,
-            detail: "remove workit plugin entries from opencode.json",
-          },
-        ]
-      : [],
-  };
-
-  const settingsExisting = readJsonRecord(res.cursorSettings);
-  const mcpExisting = readJsonRecord(res.cursorMcp);
-  // A malformed host file is still planned: apply must surface the failure
-  // (file untouched) instead of silently pretending the host is clean.
-  const settingsDirty =
-    settingsExisting.kind === "malformed" ||
-    (settingsExisting.kind === "record" &&
-      cleanCursorSettings(settingsExisting.value, res.cursorPluginDir).changed);
-  const mcpDirty =
-    mcpExisting.kind === "malformed" ||
-    (mcpExisting.kind === "record" && cleanCursorMcp(mcpExisting.value).changed);
-  const dirExists = existsSync(res.cursorPluginDir);
-  const actions: UninstallAction[] = [];
-  if (settingsDirty) {
-    actions.push({
-      kind: "edit-json-remove",
-      path: res.cursorSettings,
-      detail: "remove workit enabled_plugins/plugin_dirs entries from settings.json",
-    });
-  }
-  if (mcpDirty) {
-    actions.push({
-      kind: "edit-json-remove",
-      path: res.cursorMcp,
-      detail: "remove the workit MCP server registration from mcp.json",
-    });
-  }
-  if (dirExists) {
-    actions.push({
-      kind: "remove-dir",
-      path: res.cursorPluginDir,
-      detail: "delete the local workit plugin directory",
-    });
-  }
-  const cursor: UninstallHostPlan = {
-    host: "cursor",
-    installed: settingsDirty || mcpDirty || dirExists,
-    actions,
-  };
-
-  const codexInstalled = existsSync(res.codexPluginDir);
-  const codex: UninstallHostPlan = {
-    host: "codex",
-    installed: codexInstalled,
-    actions: codexInstalled
-      ? [{ kind: "remove-dir", path: res.codexPluginDir, detail: "remove Codex workit plugin dir" }]
-      : [],
-  };
-
-  const piExisting = readJsonRecord(res.piConfig);
-  const piDirty =
-    piExisting.kind === "malformed" ||
-    (piExisting.kind === "record" && cleanPiConfig(piExisting.value).changed);
-  const pi: UninstallHostPlan = {
-    host: "pi",
-    installed: piDirty,
-    actions: piDirty
-      ? [
-          {
-            kind: "edit-json-remove",
-            path: res.piConfig,
-            detail: "remove workit pi extension/skills entries",
-          },
-        ]
-      : [],
-  };
-
-  // Claude Code: one native `claude plugin uninstall <id> --scope <scope>`
-  // per recorded Workit install that applies here (user scope, plus this
-  // project's project/local scope, run from that project). A --plugin-dir
-  // pin is never recorded.
-  const home = paths.home ?? paths.env?.HOME ?? os.homedir();
-  const claudeInstalls = claudeWorkitInstalls(
-    home,
-    paths.env ?? process.env,
-    paths.cwd ?? process.cwd(),
-  );
-  const claude: UninstallHostPlan = {
-    host: "claude-code",
-    installed: claudeInstalls.length > 0,
-    actions: claudeInstalls.map((install) => ({
-      kind: "host-command" as const,
-      path: install.installPath,
-      detail: `claude plugin uninstall ${install.id} --scope ${install.scope}${
-        install.projectPath ? ` (in ${install.projectPath})` : ""
-      }`,
-      command: "claude" as const,
-      args: ["plugin", "uninstall", install.id, "--scope", install.scope],
-      cwd: install.projectPath,
-    })),
-  };
-
-  return { hosts: [opencode, cursor, codex, pi, claude] };
-}
-
-// CA-14 traversal guard: rm -rf is permitted ONLY on the exact resolved
-// canonical <home>/.cursor/plugins/local/workit directory. Any other resolved
-// path (symlinked alias, sibling, traversal) fails closed without touching disk.
-// Belt-and-braces (Task 8 advisory): when both sides resolve, their real paths
-// must agree too — an ancestor symlink swapped in between plan and apply cannot
-// widen the rm target. An unresolvable path falls through to the lexical
-// verdict (apply then reports skipped/failed downstream).
-const canonicalRemoveDirAllowed = (actionPath: string, res: ResolvedUninstall): boolean => {
-  const expected = path.resolve(res.cursorPluginDir);
-  if (
-    !(
-      actionPath === expected &&
-      path.basename(expected) === "workit" &&
-      path.basename(path.dirname(expected)) === "local" &&
-      path.basename(path.dirname(path.dirname(expected))) === "plugins"
-    )
-  ) {
-    return false;
-  }
-  try {
-    return realpathSync(actionPath) === realpathSync(expected);
-  } catch {
-    return true;
-  }
-};
-
-const applyEditJsonRemove = (
-  target: string,
-  cleaner: JsonCleaner,
-): { status: UninstallResultStatus; detail?: string } => {
-  const existing = readJsonRecord(target);
-  if (existing.kind === "malformed") {
-    return { status: "failed", detail: `${existing.error} — file untouched` };
-  }
-  if (existing.kind === "missing") {
-    return { status: "skipped", detail: "file already absent" };
-  }
-  const { next, changed } = cleaner(existing.value);
-  // Only-if-changed: byte-preserving when there is nothing to remove.
-  if (!changed) return { status: "skipped", detail: "no workit entries present" };
-  const serialized = JSON.stringify(next, null, 2) + "\n";
-  // The byte-compare re-read races any external writer; a vanished/unreadable
-  // file between the two reads must fail THIS action, not abort the rest.
-  let current: string;
-  try {
-    current = readFileSync(target, "utf8");
-  } catch (error) {
-    return {
-      status: "failed",
-      detail: `read failed before write: ${error instanceof Error ? error.message : String(error)}`,
-    };
-  }
-  if (current === serialized) {
-    return { status: "skipped", detail: "already clean" };
-  }
-  try {
-    writeFileSync(target, serialized, "utf8");
-  } catch (error) {
-    return {
-      status: "failed",
-      detail: `write failed: ${error instanceof Error ? error.message : String(error)}`,
-    };
-  }
-  return { status: "removed" };
-};
-
-const CLAUDE_PLUGIN_ID = /^workit@[A-Za-z0-9._-]+$/;
-
-/** Runs a reviewed `claude plugin uninstall workit@<marketplace>`; any other
- *  argv is refused, so a tampered plan cannot run an arbitrary command. */
-const applyClaudeUninstall = (
-  action: Extract<UninstallAction, { kind: "host-command" }>,
-  paths: UninstallPaths,
-): { status: UninstallResultStatus; detail?: string } => {
-  const [verb, sub, id, flag, scope, ...rest] = action.args;
-  const projectScoped = scope === "project" || scope === "local";
-  if (
-    action.command !== "claude" ||
-    verb !== "plugin" ||
-    sub !== "uninstall" ||
-    !CLAUDE_PLUGIN_ID.test(id ?? "") ||
-    flag !== "--scope" ||
-    !(scope === "user" || projectScoped) ||
-    rest.length > 0 ||
-    // user scope runs anywhere; project/local only from their project.
-    (projectScoped ? typeof action.cwd !== "string" : action.cwd !== null)
-  )
-    return {
-      status: "failed",
-      detail: `refusing unreviewed host command: ${action.args.join(" ")}`,
-    };
-  const home = paths.home ?? paths.env?.HOME ?? os.homedir();
-  const env = paths.env ?? process.env;
-  const recorded = claudeWorkitInstalls(home, env, action.cwd).some(
-    (install) =>
-      install.id === id &&
-      install.scope === scope &&
-      (install.projectPath === null
-        ? action.cwd === null
-        : path.resolve(install.projectPath) === path.resolve(action.cwd ?? "")),
-  );
-  if (!recorded)
-    return { status: "skipped", detail: `${id} (${scope} scope) is no longer installed` };
-  const executable = findHostExecutable("claude", { home, env });
-  if (!executable && !paths.runHostCommand)
-    return { status: "failed", detail: "claude executable was not found on PATH" };
-  const step = {
-    command: executable ?? "claude",
-    args: action.args,
-    ...(action.cwd === null ? {} : { cwd: action.cwd }),
-    purpose: `Uninstall the Workit Claude Code plugin ${id} (${scope} scope)`,
-  };
-  const result = paths.runHostCommand
-    ? paths.runHostCommand(step)
-    : runHostCommand(step, { home, env });
-  return result.exitCode === 0
-    ? { status: "removed", detail: action.detail }
-    : { status: "failed", detail: result.stderr || `exit ${result.exitCode}` };
-};
-
-/** Applies ONLY the reviewed plan actions with the given path options. Each
- *  planned action yields exactly one result entry; malformed host JSON fails
- *  its own action untouched while the remaining actions proceed (CA-13). */
-export function applyUninstall(plan: UninstallPlan, paths: UninstallPaths = {}): UninstallResult {
-  const res = resolveUninstallPaths(paths);
-  const entries: UninstallResultEntry[] = [];
-  for (const hostPlan of plan.hosts) {
-    for (const action of hostPlan.actions) {
-      let status: UninstallResultStatus;
-      let detail: string | undefined;
-      if (action.kind === "host-command") {
-        const outcome = applyClaudeUninstall(action, paths);
-        status = outcome.status;
-        detail = outcome.detail;
-      } else if (action.kind === "remove-dir") {
-        // Resolve before comparing so ".."/symlink tricks can never widen the rm.
-        const resolved = path.resolve(action.path);
-        const allowed =
-          canonicalRemoveDirAllowed(resolved, res) ||
-          (resolved === path.resolve(res.codexPluginDir) &&
-            path.basename(resolved) === "workit" &&
-            path.basename(path.dirname(resolved)) === "plugins");
-        if (!allowed) {
-          status = "failed";
-          detail = `refusing to remove non-canonical plugin directory: ${resolved}`;
-        } else if (!existsSync(resolved)) {
-          status = "skipped";
-          detail = "directory already absent";
-        } else {
-          try {
-            rmSync(resolved, { recursive: true, force: true });
-            status = "removed";
-          } catch (error) {
-            status = "failed";
-            detail = error instanceof Error ? error.message : String(error);
-          }
-        }
-      } else {
-        const cleaner = jsonCleanerFor(action.path, res);
-        if (cleaner === null) {
-          status = "failed";
-          detail = `${action.path} is not a recognized uninstall target for this host`;
-        } else {
-          const outcome = applyEditJsonRemove(action.path, cleaner);
-          status = outcome.status;
-          detail = outcome.detail;
-        }
-      }
-      entries.push({ host: hostPlan.host, path: action.path, status, detail });
-    }
-  }
-  return { ok: entries.every((e) => e.status !== "failed"), entries };
-}