rovecode 0.4.0-beta.2 → 0.4.0

package/src/plugins/cli.ts

@@ -0,0 +1,123 @@
+/** `rovecode plugin …` — list · add · remove · enable · disable · trust · untrust · show. A pure
+ *  command function over injected cwd/home/output so tests drive it without a process; cli/main.ts
+ *  wires `case "plugin"` to it with process.cwd() and rovecodeHome(). Nothing here imports plugin
+ *  code: `show` and `list` read manifests and folder digests only, so an untrusted project plugin can
+ *  be inspected before it is ever run — that inspection is what `trust` asks the human to do. */
+
+import { relative } from "node:path";
+import { rovecodeHome } from "../providers/auth.ts";
+import { discoverPlugins, type DiscoveredPlugin, type PluginScope } from "./discover.ts";
+import { addPlugin, removePlugin, scopeRoot, setPluginEnabled, trustPlugin, untrustPlugin, type Spawn } from "./install.ts";
+import { contributions } from "./manifest.ts";
+import { pluginFiles, statePath } from "./state.ts";
+
+export interface PluginCliDeps {
+  cwd?: string;
+  home?: string;
+  out?: (line: string) => void;
+  err?: (line: string) => void;
+  spawn?: Spawn;
+}
+
+export const PLUGIN_USAGE = [
+  "usage: rovecode plugin <command>",
+  "  list                       every plugin in ~/.rovecode/plugins and .rovecode/plugins, with its status",
+  "  init <name> [--project]    scaffold a new plugin folder (manifest, entry, test, README) ready for `plugin add`",
+  "  test [path]                validate + activate a plugin in a dry harness, then run its plugin.test.ts",
+  "  add <folder|git-url> [--project] [--force]",
+  "                             copy (or shallow-clone) a plugin into the user scope, or this repo's .rovecode/plugins",
+  "  remove <name> [--project]  delete the installed copy",
+  "  enable <name> · disable <name>",
+  "                             switch a plugin off/on in every scope (~/.rovecode/plugins.json)",
+  "  trust <name>               approve a PROJECT plugin's current files on this machine — until they change",
+  "  untrust <name>             withdraw that approval",
+  "  show <name>                manifest, files and what it contributes, without running any of it",
+  "status: active · disabled · untrusted (project plugin not yet approved here) · broken (see problems)",
+].join("\n");
+
+const flag = (args: string[], name: string): boolean => args.includes(name);
+const words = (args: string[]): string[] => args.filter((a) => !a.startsWith("--"));
+
+export async function cmdPlugin(args: string[], deps: PluginCliDeps = {}): Promise<number> {
+  const cwd = deps.cwd ?? process.cwd(), home = deps.home ?? rovecodeHome();
+  const out = deps.out ?? ((l) => console.log(l)), err = deps.err ?? ((l) => console.error(l));
+  const [sub = "list", ...rest] = args;
+  const scope: PluginScope = flag(rest, "--project") ? "project" : "user";
+  const name = words(rest)[0];
+  switch (sub) {
+    case "init": return await import("./init.ts").then((m) => m.cmdPluginInit(words(rest), { cwd, out, err }));
+    case "test": return await import("./init.ts").then((m) => m.cmdPluginTest(words(rest)[0], { cwd, home, out, err }));
+    case "list": case "ls": {
+      const { plugins, warnings } = discoverPlugins(cwd, { home });
+      if (plugins.length === 0) { out(`no plugins. add one: rovecode plugin add <folder|git-url>   (user: ${scopeRoot("user", cwd, home)}, project: ${relative(cwd, scopeRoot("project", cwd, home)) || "."})`); }
+      for (const p of plugins) out(row(p));
+      for (const w of warnings) err(`warning: ${w}`);
+      return 0;
+    }
+    case "add": {
+      const src = name;
+      if (!src) { err(PLUGIN_USAGE); return 2; }
+      const r = await addPlugin(src, { cwd, home, scope, force: flag(rest, "--force"), ...(deps.spawn ? { spawn: deps.spawn } : {}) });
+      if (!r.ok) { err(`plugin add: ${r.error}`); return 1; }
+      out(`added ${r.name}@${r.manifest.version} (${r.scope}) → ${r.dir}`);
+      for (const c of contributions(r.manifest)) out(`  ${c}`);
+      if (r.scope === "project") out(`  trusted on this machine (recorded in ${statePath(home)}); a change to its files will ask again`);
+      out("restart rovecode to load it — plugins are read once per process, like hooks");
+      return 0;
+    }
+    case "remove": case "rm": {
+      if (!name) { err(PLUGIN_USAGE); return 2; }
+      const r = removePlugin(name, { cwd, home, scope });
+      if (!r.ok) { err(`plugin remove: ${r.error}`); return 1; }
+      out(`removed ${name} (${scope}) from ${r.dir}`);
+      return 0;
+    }
+    case "enable": case "disable": {
+      if (!name) { err(PLUGIN_USAGE); return 2; }
+      const known = discoverPlugins(cwd, { home }).plugins.some((p) => p.name === name);
+      if (!known) err(`warning: no installed plugin named "${name}" — the setting is recorded anyway`);
+      const path = setPluginEnabled(name, sub === "enable", home);
+      out(`${name} ${sub}d (${path})`);
+      return 0;
+    }
+    case "trust": {
+      if (!name) { err(PLUGIN_USAGE); return 2; }
+      const p = discoverPlugins(cwd, { home }).plugins.find((x) => x.name === name && x.scope === "project");
+      if (!p) { err(`plugin trust: no project plugin "${name}" under ${scopeRoot("project", cwd, home)}`); return 1; }
+      if (p.manifest === null) { err(`plugin trust: "${name}" is broken — fix it first:`); for (const w of p.problems) err(`  ${w}`); return 1; }
+      const r = trustPlugin(name, { cwd, home });
+      if (!r.ok) { err(`plugin trust: ${r.error}`); return 1; }
+      out(`trusted ${name}@${p.manifest.version} — ${pluginFiles(p.dir).length} files, digest ${r.digest.slice(0, 12)}…`);
+      for (const c of contributions(p.manifest)) out(`  ${c}`);
+      out("it loads on the next start; `rovecode plugin show " + name + "` lists every file it brings");
+      return 0;
+    }
+    case "untrust": {
+      if (!name) { err(PLUGIN_USAGE); return 2; }
+      out(untrustPlugin(name, { cwd, home }) ? `untrusted ${name}` : `${name} was not trusted`);
+      return 0;
+    }
+    case "show": case "info": {
+      if (!name) { err(PLUGIN_USAGE); return 2; }
+      const p = discoverPlugins(cwd, { home }).plugins.find((x) => x.name === name);
+      if (!p) { err(`plugin show: no plugin "${name}"`); return 1; }
+      out(row(p));
+      out(`  folder:  ${p.dir}`);
+      if (p.digest) out(`  digest:  ${p.digest}`);
+      if (p.manifest) for (const c of contributions(p.manifest)) out(`  ${c}`);
+      for (const f of pluginFiles(p.dir)) out(`  - ${f}`);
+      for (const w of p.problems) out(`  ! ${w}`);
+      if (p.status === "untrusted") out(`  run \`rovecode plugin trust ${p.name}\` after reading the files above`);
+      return 0;
+    }
+    case "help": case "--help": case "-h": out(PLUGIN_USAGE); return 0;
+    default: err(`unknown plugin command "${sub}"\n${PLUGIN_USAGE}`); return 2;
+  }
+}
+
+/** one list row: `name@version  scope  status  — description` */
+export function row(p: DiscoveredPlugin): string {
+  const v = p.manifest ? `@${p.manifest.version}` : "";
+  const desc = p.manifest?.description ? ` — ${p.manifest.description}` : "";
+  return `${(p.name + v).padEnd(28)} ${p.scope.padEnd(8)} ${p.status.padEnd(9)}${desc}`.trimEnd();
+}

package/src/plugins/discover.ts

@@ -0,0 +1,108 @@
+/** Plugins: discovery. Two roots — `~/.rovecode/plugins/<name>/` (user) and `<cwd>/.rovecode/plugins/
+ *  <name>/` (project) — each subfolder with a `plugin.json` is a plugin. Sync and filesystem-only:
+ *  nothing is imported here, so `rovecode plugin list` can show a hostile plugin without running it.
+ *
+ *  Status decides what load.ts may do with a plugin:
+ *    active     — will be imported and wired
+ *    disabled   — the human switched it off (plugins.json)
+ *    untrusted  — a PROJECT plugin whose folder digest the human has not approved on this machine;
+ *                 listed, never imported (state.ts explains why the record lives in the user home)
+ *    broken     — no usable manifest; listed with its reasons so the author can fix it
+ *  Same name in both roots: the project copy shadows the user copy (the commands loader's rule) and
+ *  says so. ROVECODE_NO_PLUGINS=1 skips discovery the way ROVECODE_NO_HOOKS=1 skips hooks. */
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { rovecodeHome } from "../providers/auth.ts";
+import { normalizeEntry, type McpServerConfig } from "../mcp/config.ts";
+import { MANIFEST_FILE, parseManifest, type PluginManifest } from "./manifest.ts";
+import { isDir, isTrusted, loadState, pluginDigest, type PluginState } from "./state.ts";
+
+export type PluginScope = "user" | "project";
+export type PluginStatus = "active" | "disabled" | "untrusted" | "broken";
+
+export interface DiscoveredPlugin {
+  name: string;
+  /** absolute plugin folder */
+  dir: string;
+  scope: PluginScope;
+  manifest: PluginManifest | null;
+  status: PluginStatus;
+  /** folder digest (state.ts); null when the folder could not be walked */
+  digest: string | null;
+  /** why it is broken / what the manifest dropped — the author's fix list */
+  problems: string[];
+  /** the declarative halves, resolved here because they need no code run: the runtime wires them
+   *  synchronously at construction (the commands and skills loaders, the MCP config) and only the
+   *  entry module waits for load.ts. Filled for every plugin with a manifest; the runtime reads
+   *  them for ACTIVE ones only. */
+  commandsDir: string | null;
+  skillsDir: string | null;
+  mcp: McpServerConfig[];
+}
+
+export interface DiscoverOptions { home?: string; state?: PluginState }
+export interface Discovered { plugins: DiscoveredPlugin[]; warnings: string[] }
+
+/** the two roots, project last so it shadows; one root when cwd IS the home (commands.ts idiom) */
+export function pluginRoots(cwd: string, home: string): [PluginScope, string][] {
+  const user = join(home, "plugins"), project = join(cwd, ".rovecode", "plugins");
+  return resolve(user) === resolve(project) ? [["project", project]] : [["user", user], ["project", project]];
+}
+
+export function discoverPlugins(cwd: string, opts: DiscoverOptions = {}): Discovered {
+  const out: Discovered = { plugins: [], warnings: [] };
+  if (process.env.ROVECODE_NO_PLUGINS === "1") return out;
+  const home = opts.home ?? rovecodeHome();
+  const state = opts.state ?? loadState(home);
+  const byName = new Map<string, DiscoveredPlugin>();
+  for (const [scope, root] of pluginRoots(cwd, home)) {
+    if (!isDir(root)) continue;
+    let names: string[];
+    try { names = readdirSync(root).sort(); } catch (e) { out.warnings.push(`${root}: cannot list — ${(e as Error).message}`); continue; }
+    for (const folder of names) {
+      const dir = join(root, folder);
+      if (!isDir(dir) || !existsSync(join(dir, MANIFEST_FILE))) continue; // a stray file or a folder without a manifest is not a plugin
+      const p = readPlugin(dir, folder, scope, state);
+      const prev = byName.get(p.name);
+      if (prev) out.warnings.push(`${dir}: plugin "${p.name}" shadows ${prev.dir} (project over user)`);
+      byName.set(p.name, p);
+      for (const w of p.problems) out.warnings.push(w);
+    }
+  }
+  out.plugins = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+  return out;
+}
+
+/** one folder → its DiscoveredPlugin: manifest, status, digest, and the declarative halves resolved
+ *  (a named commands/skills dir must exist; MCP entries go through the same normalizer as mcp.json) */
+export function readPlugin(dir: string, folder: string, scope: PluginScope, state: PluginState): DiscoveredPlugin {
+  const file = join(dir, MANIFEST_FILE);
+  const problems: string[] = [];
+  let manifest: PluginManifest | null = null;
+  try { manifest = parseManifest(readFileSync(file, "utf8"), file, problems); }
+  catch (e) { problems.push(`${file}: cannot read — ${(e as Error).message}`); }
+  let digest: string | null = null;
+  try { digest = pluginDigest(dir); } catch { digest = null; }
+  const name = manifest?.name ?? folder;
+  if (manifest && manifest.name !== folder) problems.push(`${file}: name "${manifest.name}" differs from its folder "${folder}" — the manifest name is the plugin's identity`);
+  let status: PluginStatus;
+  if (manifest === null) status = "broken";
+  else if (state.disabled.includes(name)) status = "disabled";
+  else if (scope === "project" && (digest === null || !isTrusted(state, dir, digest))) status = "untrusted";
+  else status = "active";
+  const tag = `plugin ${name}`;
+  const commandsDir = manifest ? dirOrProblem(dir, manifest.commands, `${tag}: commands`, problems) : null;
+  const skillsDir = manifest ? dirOrProblem(dir, manifest.skills, `${tag}: skills`, problems) : null;
+  const mcp: McpServerConfig[] = [];
+  if (manifest?.mcp) for (const [n, raw] of Object.entries(manifest.mcp)) { const c = normalizeEntry(n, raw, file, problems); if (c) mcp.push(c); }
+  return { name, dir, scope, manifest, status, digest, problems, commandsDir, skillsDir, mcp };
+}
+
+function dirOrProblem(base: string, rel: string | undefined, what: string, problems: string[]): string | null {
+  if (!rel) return null;
+  const p = join(base, rel);
+  try { if (statSync(p).isDirectory()) return p; } catch { /* below */ }
+  problems.push(`${what} directory "${rel}" does not exist — ignored`);
+  return null;
+}

package/src/plugins/index.ts

@@ -0,0 +1,50 @@
+/** Plugins (the package, not the surface). A plugin is a folder with a `plugin.json` that bundles what
+ *  rovecode can already be extended with — an in-process module of tools and hooks, custom commands,
+ *  skills, MCP servers — so one `rovecode plugin add` installs all of it, `plugin list` shows all of it,
+ *  and a project can ship its own under `.rovecode/plugins/` behind a per-machine trust step.
+ *
+ *  Module map: manifest.ts (plugin.json → PluginManifest) · state.ts (~/.rovecode/plugins.json:
+ *  disabled + trusted digests) · discover.ts (the two roots → DiscoveredPlugin with a status, no code
+ *  run) · load.ts (import + validate the active ones → typed contributions) · install.ts (the human's
+ *  verbs) · cli.ts (`rovecode plugin …`). `loadPlugins` is the one call the runtime makes. */
+
+import { rovecodeHome } from "../providers/auth.ts";
+import { discoverPlugins, type DiscoveredPlugin } from "./discover.ts";
+import { activatePlugins, type LoadedPlugin } from "./load.ts";
+import { loadState } from "./state.ts";
+
+export type { PluginManifest } from "./manifest.ts";
+export { PLUGIN_API_VERSION, MANIFEST_FILE, parseManifest, contributions } from "./manifest.ts";
+export type { PluginState } from "./state.ts";
+export { loadState, saveState, statePath, pluginDigest, pluginFiles } from "./state.ts";
+export type { DiscoveredPlugin, PluginScope, PluginStatus } from "./discover.ts";
+export { discoverPlugins, pluginRoots } from "./discover.ts";
+export type { LoadedPlugin, PluginModule, PluginCtx } from "./load.ts";
+export { activatePlugins, DEFAULT_PLUGIN_TIMEOUT_MS } from "./load.ts";
+export { addPlugin, removePlugin, setPluginEnabled, trustPlugin, untrustPlugin, scopeRoot, isGitSource } from "./install.ts";
+export { cmdPlugin, PLUGIN_USAGE } from "./cli.ts";
+
+export interface LoadPluginsOptions { home?: string; timeoutMs?: number }
+export interface LoadedPlugins {
+  /** every discovered plugin, active ones carrying their contributions */
+  plugins: LoadedPlugin[];
+  /** discovery + activation notes, in order — for the boot transcript */
+  warnings: string[];
+}
+
+/** discover, then activate the active ones; the runtime's single entry point */
+export async function loadPlugins(cwd: string, opts: LoadPluginsOptions = {}): Promise<LoadedPlugins> {
+  const home = opts.home ?? rovecodeHome();
+  const found = discoverPlugins(cwd, { home, state: loadState(home) });
+  const act = await activatePlugins(found.plugins, { cwd, home, ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}) });
+  return { plugins: act.plugins, warnings: [...found.warnings, ...act.warnings] };
+}
+
+/** one line per plugin the boot transcript can echo: `plugins: 2 active (safety-net, notes) · 1 untrusted (acme)` */
+export function summarizePlugins(p: readonly Pick<DiscoveredPlugin, "name" | "status">[]): string | null {
+  if (p.length === 0) return null;
+  const by = (s: DiscoveredPlugin["status"]): string[] => p.filter((x) => x.status === s).map((x) => x.name);
+  const parts: string[] = [];
+  for (const s of ["active", "untrusted", "disabled", "broken"] as const) { const n = by(s); if (n.length) parts.push(`${n.length} ${s} (${n.join(", ")})`); }
+  return `plugins: ${parts.join(" · ")}`;
+}

package/src/plugins/init.ts

@@ -0,0 +1,140 @@
+/** `rovecode plugin init` + `rovecode plugin test` (F4, sdk-blueprint.md §6).
+ *
+ *  init: scaffolds a plugin folder (manifest with an empty permissions declaration, a
+ *  tool+hook entry, a bun:test file, a README) into <cwd>/<name> — or straight into a
+ *  scope with --project. Nothing is installed; `plugin add` is the install step.
+ *
+ *  test: the development loop — parse the manifest, activate the plugin in a dry harness
+ *  (activatePlugins against a synthetic discovery entry, cwd = a throwaway tmp dir so a
+ *  misbehaving module cannot touch the repo), report every contribution and warning, then
+ *  run the plugin's own plugin.test.ts under `bun test` when present. Exit codes: 2 usage,
+ *  1 validation/activation problems or failing tests, 0 clean. */
+
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseManifest, contributions, PLUGIN_API_VERSION, MANIFEST_FILE, type PluginManifest } from "./manifest.ts";
+import { activatePlugins } from "./load.ts";
+import type { DiscoveredPlugin } from "./discover.ts";
+
+interface Out { cwd: string; out: (l: string) => void; err: (l: string) => void }
+
+const NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+const ENTRY_TS = `/** <name> — a rovecode plugin. The default export is the whole contract:
+ *  api (PLUGIN_API_VERSION), tools (Tool[] or a factory), hooks (HookSet).
+ *  Docs: docs/design/sdk-blueprint.md §6 */
+import type { Tool, HookSet } from "rovecode/core"; // resolved by rovecode at load time
+
+const hello: Tool = {
+  schema: {
+    name: "<tool>_hello",
+    description: "Says hello from the <name> plugin.",
+    args: { type: "object", properties: { who: { type: "string" } } },
+  },
+  kind: "read", // read = no workspace effect; kinds map to policy actions (see plugin.json permissions)
+  // sequential: false — concurrent with siblings in a batch; only stateful tools go sequential
+  async execute(args) {
+    const a = args as { who?: string };
+    return { ok: true, output: \`hello, \${typeof a.who === "string" ? a.who : "world"}!\` };
+  },
+};
+
+const hooks: HookSet = {
+  // pre_tool: async ({ tool }) => tool === "bash" ? { deny: "nope" } : undefined,
+};
+
+export default { api: ${PLUGIN_API_VERSION}, tools: [hello], hooks };
+`;
+
+const TEST_TS = `/** The plugin's own tests — \`rovecode plugin test\` runs this file under bun:test. */
+import { test, expect } from "bun:test";
+import plugin from "./index.ts";
+
+test("module shape", () => {
+  expect(plugin.api).toBe(${PLUGIN_API_VERSION});
+  expect(Array.isArray(plugin.tools)).toBe(true);
+});
+
+test("hello tool", async () => {
+  const tool = (plugin.tools ?? [])[0]!;
+  const out = await tool.execute({ who: "tests" }, {} as never);
+  expect(out.ok).toBe(true);
+  expect(out.output).toContain("hello, tests!");
+});
+`;
+
+const README_MD = (name: string): string => `# ${name}
+
+A rovecode plugin.
+
+- \\\"permissions\\\" in plugin.json declares the policy actions its tools may take
+  (file.read, file.write, shell.exec, spawn, memory.write, net.fetch). A tool whose
+  kind is not declared is refused at run time — the list is a promise, not a comment.
+- Develop: \\\`rovecode plugin test .\\\` in this folder.
+- Install: \\\`rovecode plugin add .\\\` (user scope) or \\\`rovecode plugin add . --project\\\`.
+`;
+
+export async function cmdPluginInit(words: string[], o: Out): Promise<number> {
+  const name = words[0];
+  if (!name || !NAME_RE.test(name)) { o.err(`plugin init: name must match ${NAME_RE}`); return 2; }
+  const dir = join(o.cwd, name);
+  if (existsSync(dir)) { o.err(`plugin init: ${dir} already exists`); return 1; }
+  mkdirSync(dir, { recursive: true });
+  const manifest = {
+    name,
+    version: "0.1.0",
+    description: `${name} plugin`,
+    api: PLUGIN_API_VERSION,
+    entry: "index.ts",
+    permissions: [] as string[],
+  };
+  writeFileSync(join(dir, MANIFEST_FILE), JSON.stringify(manifest, null, 2) + "\n");
+  writeFileSync(join(dir, "index.ts"), ENTRY_TS.replaceAll("<name>", name).replaceAll("<tool>", name.replaceAll("-", "_")));
+  writeFileSync(join(dir, "plugin.test.ts"), TEST_TS);
+  writeFileSync(join(dir, "README.md"), README_MD(name));
+  o.out(`scaffolded ${name} at ${dir}`);
+  o.out(`next: rovecode plugin test ${dir}   ·   rovecode plugin add ${dir}`);
+  return 0;
+}
+
+export async function cmdPluginTest(path: string | undefined, o: { cwd: string; home: string; out: (l: string) => void; err: (l: string) => void }): Promise<number> {
+  const dir = resolve(o.cwd, path ?? ".");
+  const mf = join(dir, MANIFEST_FILE);
+  if (!existsSync(mf)) { o.err(`plugin test: no ${MANIFEST_FILE} in ${dir}`); return 2; }
+  const warnings: string[] = [];
+  const manifest = parseManifest(readFileSync(mf, "utf8"), mf, warnings);
+  if (!manifest) { for (const w of warnings) o.err(w); return 1; }
+  o.out(`manifest ok: ${manifest.name}@${manifest.version} (api ${manifest.api})`);
+  for (const c of contributions(manifest)) o.out(`  ${c}`);
+
+  // dry activation: cwd is a throwaway dir, so a module that writes "to the project" writes nowhere real
+  const scratch = mkdtempSync(join(tmpdir(), "rovecode-plugintest-"));
+  try {
+    const discovered: DiscoveredPlugin = {
+      dir, name: manifest.name, scope: "project", status: "active", manifest,
+      digest: null, problems: [], commandsDir: null, skillsDir: null, mcp: [],
+    };
+    const { plugins, warnings: aw } = await activatePlugins([discovered], { cwd: scratch, home: scratch });
+    for (const w of aw) o.err(`warning: ${w}`);
+    const p = plugins[0];
+    const tools = p?.tools ?? [];
+    o.out(`activated: ${tools.length} tool(s)${tools.length ? ` [${tools.map((t) => `${t.schema.name}:${t.kind}`).join(", ")}]` : ""}, hooks ${p?.hooks ? "yes" : "none"}`);
+    if (aw.length > 0) return 1;
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+
+  const testFile = join(dir, "plugin.test.ts");
+  if (existsSync(testFile)) {
+    o.out(`running ${testFile} …`);
+    const proc = Bun.spawn([process.execPath, "test", testFile], { cwd: dir, stdout: "inherit", stderr: "inherit" });
+    const code = await proc.exited;
+    if (code !== 0) { o.err(`plugin.test.ts failed (exit ${code})`); return 1; }
+  } else {
+    o.out("no plugin.test.ts — add one for `plugin test` to exercise behavior, not just shape");
+  }
+  o.out("plugin test: ok");
+  return 0;
+}

package/src/plugins/install.ts

@@ -0,0 +1,184 @@
+/** Plugins: the human's verbs — add, remove, enable, disable, trust. Each is a small filesystem
+ *  operation plus a plugins.json edit; none imports plugin code (that is load.ts, at runtime, after
+ *  these decisions). `add` takes a folder or a git URL: a URL is cloned shallow into a temp folder and
+ *  from there on treated exactly like a folder (validated BEFORE anything is copied into place — a
+ *  folder without a usable manifest never lands in ~/.rovecode/plugins). Adding into the project scope
+ *  records the folder's digest as trusted: the human ran the command, that is the yes. */
+
+import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve, sep } from "node:path";
+import { pluginRoots, type PluginScope } from "./discover.ts";
+import { MANIFEST_FILE, parseManifest, type PluginManifest } from "./manifest.ts";
+import { isDir, loadState, pluginDigest, saveState, trustKey } from "./state.ts";
+
+export type Spawn = (cmd: string[], cwd: string) => Promise<{ code: number; stderr: string }>;
+/** the copy step, injectable for one reason: a test cannot otherwise arrange a copy that fails PART WAY
+ *  through, which is the only failure the staging directory exists to survive. A real half-copy needs a
+ *  full disk or a locked file; a fake one needs three lines. */
+export type CopyTree = (from: string, to: string, filter: (path: string) => boolean) => void;
+export interface InstallOptions {
+  cwd: string;
+  home: string;
+  scope: PluginScope;
+  /** replace an existing plugin of the same name */
+  force?: boolean;
+  /** the plugin's folder INSIDE the source, when the source is a repository that publishes several.
+   *
+   *  Every real plugin is one: rovecode's own three live in `plugins/safety-net`, `plugins/notes` and
+   *  `plugins/conventional-commits`, and a catalog could not install any of them while `add` only looked
+   *  at the clone root. Rejected rather than normalised: an absolute path, a drive letter, or any `..`
+   *  segment — a subfolder that climbs out of the clone is an attempt, not a typo. */
+  subfolder?: string;
+  /** see {@link CopyTree} — real installs never pass this */
+  copy?: CopyTree;
+  /** Clones already made during THIS command, keyed by `cloneKey`. One monorepo publishes all three
+   *  first-party plugins, so installing them today clones the same repository three times — measured at
+   *  15.5 s per plugin install, 28.3 s for a project-scope one. The map is opened per command and disposed
+   *  with `disposeCloneCache`; nothing here caches across commands, because a clone that outlives the
+   *  command it was made for is a stale tree waiting to be installed from. */
+  cloneCache?: Map<string, string>;
+  /** how `git clone` runs; default Bun.spawn — tests inject one that never touches the network */
+  spawn?: Spawn;
+}
+
+/** The key a clone is cached under.
+ *
+ *  `ref` is not something `addPlugin` takes yet — pinning is not implemented — but it is part of the key
+ *  from the start, and deliberately so: a cache keyed on the URL alone hands back the wrong tree the day
+ *  two refs of one repository are in play, and that bug would appear in a feature far away from here. With
+ *  the key in one function, whoever adds pinning changes this and every caller inherits it. */
+export const cloneKey = (source: string, ref?: string): string => `${source}#${ref ?? ""}`;
+
+/** Remove every clone a command made. Call it in a `finally`: a half-written clone that outlives its
+ *  command is litter in %TEMP% that nobody will ever look at again. */
+export function disposeCloneCache(cache: Map<string, string> | undefined): void {
+  if (cache === undefined) return;
+  for (const dir of cache.values()) rmSync(dir, { recursive: true, force: true });
+  cache.clear();
+}
+export type AddResult = { ok: true; name: string; dir: string; scope: PluginScope; manifest: PluginManifest } | { ok: false; error: string };
+
+const GIT_URL_RE = /^(?:https?:\/\/|git@|ssh:\/\/|git:\/\/)|\.git$/i;
+export const isGitSource = (s: string): boolean => GIT_URL_RE.test(s) && !existsSync(s);
+
+const defaultSpawn: Spawn = async (cmd, cwd) => {
+  const proc = Bun.spawn(cmd, { cwd, stdout: "ignore", stderr: "pipe", stdin: "ignore" });
+  const stderr = await new Response(proc.stderr).text();
+  return { code: await proc.exited, stderr };
+};
+
+/** the folder a scope's plugins live in */
+export function scopeRoot(scope: PluginScope, cwd: string, home: string): string {
+  return pluginRoots(cwd, home).find(([s]) => s === scope)?.[1] ?? join(home, "plugins");
+}
+
+/** true for a symbolic link; an entry we cannot stat is treated as one and skipped */
+function isSymlink(p: string): boolean {
+  try { return lstatSync(p).isSymbolicLink(); } catch { return true; }
+}
+
+export async function addPlugin(source: string, opts: InstallOptions): Promise<AddResult> {
+  let src = source, tmp: string | null = null;
+  const copy: CopyTree = opts.copy ?? ((from, to, filter) => cpSync(from, to, { recursive: true, filter }));
+  try {
+    if (isGitSource(source)) {
+      const key = cloneKey(source);
+      const cached = opts.cloneCache?.get(key);
+      if (cached !== undefined && isDir(cached)) {
+        src = cached;                       // owned by the cache, so `tmp` stays null and nothing is removed
+      } else {
+        tmp = mkdtempSync(join(tmpdir(), "rovecode-plugin-"));
+        const r = await (opts.spawn ?? defaultSpawn)(["git", "clone", "--depth", "1", "--quiet", "--", source, "."], tmp);
+        if (r.code !== 0) return { ok: false, error: `git clone failed (exit ${r.code})${r.stderr.trim() ? `: ${r.stderr.trim().split("\n").at(-1)}` : ""}` };
+        src = tmp;
+        if (opts.cloneCache !== undefined) { opts.cloneCache.set(key, tmp); tmp = null; }   // ownership moves
+      }
+    }
+    src = resolve(src);
+    if (opts.subfolder !== undefined && opts.subfolder !== "") {
+      const sub = opts.subfolder.split("\\").join("/");
+      if (sub.startsWith("/") || /^[A-Za-z]:/.test(sub) || sub.split("/").includes("..")) {
+        return { ok: false, error: `subfolder "${opts.subfolder}" escapes the source` };
+      }
+      const inner = resolve(join(src, sub));
+      // resolve() alone is not the check: it happily returns a path outside src for a crafted input
+      if (inner !== src && !inner.startsWith(src + sep)) return { ok: false, error: `subfolder "${opts.subfolder}" escapes the source` };
+      if (!isDir(inner)) return { ok: false, error: `${source}: no folder "${opts.subfolder}" inside it` };
+      src = inner;
+    }
+    if (!isDir(src)) return { ok: false, error: `${source}: not a directory` };
+    const file = join(src, MANIFEST_FILE);
+    if (!existsSync(file)) return { ok: false, error: `${source}: no ${MANIFEST_FILE} — a plugin is a folder with a manifest` };
+    const warnings: string[] = [];
+    const manifest = parseManifest(readFileSync(file, "utf8"), file, warnings);
+    if (manifest === null) return { ok: false, error: warnings.join("; ") || `${file}: invalid manifest` };
+    const root = scopeRoot(opts.scope, opts.cwd, opts.home);
+    const dest = join(root, manifest.name);
+    if (resolve(dest) === src) return { ok: false, error: `${source} is already the installed copy` };
+    if (existsSync(dest) && !opts.force) return { ok: false, error: `plugin "${manifest.name}" already exists at ${dest} (use --force to replace)` };
+    // Copied beside the target and swapped in. `rmSync(dest)` then `cpSync` reads naturally and is wrong:
+    // between those two lines the plugin does not exist, and anything that ends the copy early — a full
+    // disk, a file another process holds open on Windows, ^C during `market update --all` — has already
+    // deleted a working plugin and leaves a half-written folder wearing its name. Rename is the one step
+    // the filesystem will not perform half way.
+    mkdirSync(root, { recursive: true });
+    const staging = mkdtempSync(join(root, `.rovecode-add-${manifest.name}-`));
+    try {
+      copy(src, staging, (p) => !/(?:^|[\\/])(?:node_modules|\.git)(?:[\\/]|$)/.test(p) && !isSymlink(p));
+      if (existsSync(dest)) rmSync(dest, { recursive: true, force: true });
+      renameSync(staging, dest);
+    } catch (e) {
+      // a returned error, not a thrown one: every other way this function fails is a value, and `market
+      // install a b c` should report which one could not be copied and carry on with the rest
+      return { ok: false, error: `could not install "${manifest.name}" into ${dest}: ${e instanceof Error ? e.message : String(e)}` };
+    } finally {
+      rmSync(staging, { recursive: true, force: true });   // already gone once the rename succeeded
+    }
+    if (opts.scope === "project") { // the human installed it: trust this exact content on this machine
+      const state = loadState(opts.home);
+      state.trusted[trustKey(dest)] = pluginDigest(dest);
+      saveState(opts.home, state);
+    }
+    return { ok: true, name: manifest.name, dir: dest, scope: opts.scope, manifest };
+  } finally {
+    if (tmp) rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+export function removePlugin(name: string, opts: { cwd: string; home: string; scope: PluginScope }): { ok: true; dir: string } | { ok: false; error: string } {
+  const dir = join(scopeRoot(opts.scope, opts.cwd, opts.home), name);
+  if (!isDir(dir)) return { ok: false, error: `no ${opts.scope} plugin "${name}" at ${dir}` };
+  rmSync(dir, { recursive: true, force: true });
+  const state = loadState(opts.home);
+  delete state.trusted[trustKey(dir)];
+  saveState(opts.home, state);
+  return { ok: true, dir };
+}
+
+export function setPluginEnabled(name: string, enabled: boolean, home: string): string {
+  const state = loadState(home);
+  state.disabled = state.disabled.filter((n) => n !== name);
+  if (!enabled) state.disabled.push(name);
+  return saveState(home, state);
+}
+
+/** approve a project plugin's CURRENT content; a later change to any file asks again */
+export function trustPlugin(name: string, opts: { cwd: string; home: string }): { ok: true; dir: string; digest: string } | { ok: false; error: string } {
+  const dir = join(scopeRoot("project", opts.cwd, opts.home), name);
+  if (!isDir(dir) || !existsSync(join(dir, MANIFEST_FILE))) return { ok: false, error: `no project plugin "${name}" under ${scopeRoot("project", opts.cwd, opts.home)}` };
+  const digest = pluginDigest(dir);
+  const state = loadState(opts.home);
+  state.trusted[trustKey(dir)] = digest;
+  saveState(opts.home, state);
+  return { ok: true, dir, digest };
+}
+
+export function untrustPlugin(name: string, opts: { cwd: string; home: string }): boolean {
+  const dir = join(scopeRoot("project", opts.cwd, opts.home), name);
+  const state = loadState(opts.home);
+  const had = trustKey(dir) in state.trusted;
+  delete state.trusted[trustKey(dir)];
+  saveState(opts.home, state);
+  return had;
+}