@moretea-labs/forge 1.5.0-rc.1

package/src/cli/commands/install.ts

@@ -0,0 +1,86 @@
+/**
+ * `forge install|uninstall --target codex|claude|both --location global|local`
+ *
+ * Resolves --target to AgentTarget list, calls target install/uninstall for
+ * each, prints WriteResult lines. Idempotent: re-run with no diff returns
+ * `action: 'unchanged'` or `action: 'not-found'` (verified by
+ * tests/cli/install.test.ts).
+ *
+ * Target/location matrix:
+ *   - codex + global → writes ~/.codex/hooks.json
+ *   - codex + local  → exit 2 (Codex has no project-local hook concept)
+ *   - claude + global → writes ~/.claude/settings.json
+ *   - claude + local  → writes <cwd>/.claude/settings.json (Phase 1C concern)
+ *   - both + global   → codex + claude
+ *   - both + local    → codex skipped silently, claude installed
+ */
+
+import type { Location } from '../installer/types';
+import { ALL_TARGETS, getTarget, listTargetIds } from '../installer/targets/registry';
+
+export type InstallTargetSpec = 'codex' | 'claude' | 'both';
+
+export interface InstallCommandOptions {
+  target: InstallTargetSpec;
+  location: Location;
+}
+
+export interface InstallCommandResult {
+  exitCode: number;
+  lines: string[];
+}
+
+type AdapterAction = 'install' | 'uninstall';
+
+function resolveTargets(spec: InstallTargetSpec) {
+  if (spec === 'both') return [...ALL_TARGETS];
+  const t = getTarget(spec);
+  if (!t) {
+    throw new Error(
+      `forge install: unknown --target "${spec}" (known: ${listTargetIds().join(', ')}, both)`,
+    );
+  }
+  return [t];
+}
+
+function runAdapterAction(action: AdapterAction, opts: InstallCommandOptions): InstallCommandResult {
+  const targets = resolveTargets(opts.target);
+  const lines: string[] = [];
+  let exitCode = 0;
+
+  for (const target of targets) {
+    if (!target.supportsLocation(opts.location)) {
+      if (opts.target === 'both') {
+        lines.push(`[${target.id}] skipped: --location ${opts.location} not supported`);
+        continue;
+      }
+      lines.push(`[${target.id}] error: --location ${opts.location} not supported`);
+      exitCode = 2;
+      continue;
+    }
+    try {
+      const result = action === 'install'
+        ? target.install(opts.location, {})
+        : target.uninstall(opts.location);
+      for (const file of result.files) {
+        lines.push(`[${target.id}] ${file.action}: ${file.path}`);
+      }
+      for (const note of result.notes ?? []) {
+        lines.push(`[${target.id}] note: ${note}`);
+      }
+    } catch (err) {
+      lines.push(`[${target.id}] error: ${(err as Error).message}`);
+      if (exitCode === 0) exitCode = 1;
+    }
+  }
+
+  return { exitCode, lines };
+}
+
+export function runInstall(opts: InstallCommandOptions): InstallCommandResult {
+  return runAdapterAction('install', opts);
+}
+
+export function runUninstall(opts: InstallCommandOptions): InstallCommandResult {
+  return runAdapterAction('uninstall', opts);
+}

package/src/cli/commands/mcp.ts

@@ -0,0 +1,315 @@
+import { Command } from 'commander';
+import { isAbsolute, relative } from 'path';
+import { createMcpToolContext } from '../mcp/server';
+import { startMcpHttp } from '../mcp/transports/http';
+import { startMcpStdio } from '../mcp/transports/stdio';
+import { callMcpTool } from '../mcp/tools';
+import { callAccessTool } from '../mcp/access-tools';
+import { assertControllerLifecycleOwner } from '../controller/lifecycle-authority';
+import { bindInheritedRuntimeWriteClaimFromEnvironment } from '../../runtime/root/write-fence';
+import {
+  runMcpDoctor,
+  runMcpPrintGuide,
+  runMcpSetupChatgpt,
+  runMcpSetupCodex,
+} from '../mcp/setup';
+
+export interface McpServeOptions {
+  repo?: string;
+  controllerHome?: string;
+  transport: string;
+  host: string;
+  port: string;
+  profile: string;
+  auth?: string;
+  enableChatgptBrowser?: boolean;
+  enableDevRunner?: boolean;
+  devRunnerAgents?: string;
+  devRunnerTimeoutMs?: string;
+  devRunnerMaxTimeoutMs?: string;
+  toolset?: 'core' | 'advanced' | 'full';
+}
+
+interface McpAccessOptions {
+  repo?: string;
+  controllerHome?: string;
+  repoId?: string;
+  allRepositories?: boolean;
+  mode?: string;
+  confirmAuthorization?: boolean;
+  confirmationText?: string;
+}
+
+interface McpSetupChatgptOptions {
+  repo?: string;
+  host?: string;
+  port?: string;
+  endpoint?: string;
+  serverName?: string;
+}
+
+interface McpSetupCodexOptions {
+  repo?: string;
+  scope?: string;
+  dryRun?: boolean;
+}
+
+
+interface McpPrepareGoalOptions {
+  repo?: string;
+  prd: string;
+  sprint: string;
+  referenceRepo?: string;
+  extraInstructions?: string;
+  overwrite?: boolean;
+}
+
+function parsePort(value: string): number {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    throw new Error(`invalid --port "${value}"`);
+  }
+  return port;
+}
+
+function parsePositiveIntegerOption(name: string, value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`invalid --${name} "${value}"`);
+  return parsed;
+}
+
+async function runMcpAction(action: () => void | Promise<void>): Promise<void> {
+  try {
+    await action();
+  } catch (error) {
+    console.error(`forge mcp: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(2);
+  }
+}
+
+async function runRepositoryAccessCommand(
+  toolName: 'repository_access_get' | 'repository_access_set',
+  rawOpts: McpAccessOptions,
+): Promise<void> {
+  const ctx = createMcpToolContext({
+    repo: rawOpts.repo ?? '.',
+    controllerHome: rawOpts.controllerHome,
+    profile: 'controller',
+    toolset: 'core',
+  });
+  const result = callAccessTool(ctx, toolName, {
+    repo_id: rawOpts.repoId,
+    all_repositories: rawOpts.allRepositories === true,
+    mode: rawOpts.mode,
+    confirm_authorization: rawOpts.confirmAuthorization === true,
+    confirmation_text: rawOpts.confirmationText,
+  });
+  if (!result) throw new Error(`ACCESS_POLICY_FAILED: unsupported access tool ${toolName}`);
+  const firstContent = result.content[0];
+  const payload = result.structuredContent
+    ?? JSON.parse(firstContent?.type === 'text' ? firstContent.text : '{}');
+  const error = (payload as { error?: { code?: string; message?: string } }).error;
+  if (result.isError || error) {
+    throw new Error(`${error?.code ?? 'ACCESS_POLICY_FAILED'}: ${error?.message ?? 'repository access operation failed'}`);
+  }
+  console.log(JSON.stringify(payload, null, 2));
+}
+
+async function prepareCodexGoalFromSprint(rawOpts: McpPrepareGoalOptions): Promise<string[]> {
+  const ctx = createMcpToolContext({ repo: rawOpts.repo ?? '.', profile: 'planner' });
+  const prdPath = toRepoRelativeInput(ctx.repoRoot, rawOpts.prd);
+  const sprintPath = toRepoRelativeInput(ctx.repoRoot, rawOpts.sprint);
+  const result = await callMcpTool(ctx, 'prepare_codex_goal_from_sprint', {
+    prd_path: prdPath,
+    sprint_path: sprintPath,
+    goal_prd_path: rawOpts.prd,
+    goal_sprint_path: rawOpts.sprint,
+    reference_repo: rawOpts.referenceRepo,
+    extra_instructions: rawOpts.extraInstructions,
+    overwrite: rawOpts.overwrite === true,
+  });
+  const firstContent = result.content[0];
+  const payload = JSON.parse(firstContent?.type === 'text' ? firstContent.text : '{}');
+  if (payload.error) {
+    throw new Error(`${payload.error.code}: ${payload.error.message}`);
+  }
+  return [
+    `[forge mcp] Codex goal: ${payload.path}`,
+    '[forge mcp] Host-native /goal prompt:',
+    '',
+    String(payload.prompt ?? '').trimEnd(),
+  ];
+}
+
+function toRepoRelativeInput(repoRoot: string, path: string): string {
+  if (!isAbsolute(path)) return path;
+  const relativePath = relative(repoRoot, path).split('\\').join('/');
+  if (relativePath === '' || relativePath.startsWith('../') || relativePath === '..') return path;
+  return relativePath;
+}
+
+export function buildMcpCommand(): Command {
+  const mcp = new Command('mcp').description('Run and configure the forge MCP workflow sidecar');
+
+  mcp
+    .command('serve')
+    .description('Start the forge MCP server')
+    .option('--repo <path>', 'Repository root to expose through the selected MCP profile', '.')
+    .option('--controller-home <path>', 'Controller state root; defaults to repo _ops/controller-home when present')
+    .option('--transport <transport>', 'Transport: stdio|http', 'stdio')
+    .option('--host <host>', 'HTTP bind host', '127.0.0.1')
+    .option('--port <port>', 'HTTP bind port', '8765')
+    .option('--profile <profile>', 'MCP profile: planner|executor|orchestrator|controller', 'controller')
+    .option('--toolset <toolset>', 'Controller toolset: core|advanced|full (default core; advanced/full are explicit compatibility profiles)')
+    .option('--auth <mode>', 'HTTP auth mode: oauth|bearer', 'oauth')
+    .option('--enable-chatgpt-browser', 'Expose tools that operate the user logged-in ChatGPT Web browser session')
+    .option('--enable-dev-runner', 'Enable local Codex/Claude task runners for controller or orchestrator profiles')
+    .option('--dev-runner-agents <agents>', 'Comma-separated dev runner agents: codex,claude')
+    .option('--dev-runner-timeout-ms <ms>', 'Default local agent timeout in milliseconds (default: 3600000)')
+    .option('--dev-runner-max-timeout-ms <ms>', 'Maximum per-run timeout in milliseconds (default: 43200000)')
+    .action(async (rawOpts: McpServeOptions) => {
+      await runMcpAction(async () => {
+        bindInheritedRuntimeWriteClaimFromEnvironment();
+        const devRunnerTimeoutMs = parsePositiveIntegerOption('dev-runner-timeout-ms', rawOpts.devRunnerTimeoutMs);
+        const devRunnerMaxTimeoutMs = parsePositiveIntegerOption('dev-runner-max-timeout-ms', rawOpts.devRunnerMaxTimeoutMs);
+        if (rawOpts.transport === 'stdio') {
+          await startMcpStdio({
+            repo: rawOpts.repo,
+            controllerHome: rawOpts.controllerHome,
+            profile: rawOpts.profile,
+            toolset: rawOpts.toolset,
+            enableChatgptBrowser: rawOpts.enableChatgptBrowser === true,
+            enableDevRunner: rawOpts.enableDevRunner,
+            devRunnerAgents: rawOpts.devRunnerAgents,
+            devRunnerTimeoutMs,
+            devRunnerMaxTimeoutMs,
+          });
+          return;
+        }
+        if (rawOpts.transport === 'http') {
+          if (rawOpts.profile === 'controller') assertControllerLifecycleOwner('Controller MCP HTTP server');
+          await startMcpHttp({
+            repo: rawOpts.repo,
+            controllerHome: rawOpts.controllerHome,
+            profile: rawOpts.profile,
+            toolset: rawOpts.toolset,
+            host: rawOpts.host,
+            port: parsePort(rawOpts.port),
+            auth: rawOpts.auth,
+            enableChatgptBrowser: rawOpts.enableChatgptBrowser === true,
+            enableDevRunner: rawOpts.enableDevRunner,
+            devRunnerAgents: rawOpts.devRunnerAgents,
+            devRunnerTimeoutMs,
+            devRunnerMaxTimeoutMs,
+          });
+          return;
+        }
+        throw new Error(`serve: invalid --transport "${rawOpts.transport}" (expected: stdio, http)`);
+      });
+    });
+
+  mcp
+    .command('doctor')
+    .description('Check forge MCP setup status')
+    .option('--repo <path>', 'Repository root to inspect', '.')
+    .option('--json', 'Output JSON instead of human-readable text')
+    .action((rawOpts: { repo?: string; json?: boolean }) => {
+      void runMcpAction(() => {
+        const result = runMcpDoctor(rawOpts);
+        console.log(result.lines.join('\n'));
+      });
+    });
+
+  const setup = new Command('setup').description('Generate MCP setup files for ChatGPT or Codex');
+
+  setup
+    .command('chatgpt')
+    .description('Generate ChatGPT Connector local config and manual setup guide')
+    .option('--repo <path>', 'Repository root to configure', '.')
+    .option('--host <host>', 'Local MCP HTTP bind host', '127.0.0.1')
+    .option('--port <port>', 'Local MCP HTTP bind port', '8765')
+    .option('--endpoint <url>', 'Stable public HTTPS /mcp endpoint to store in ignored local config')
+    .option('--server-name <name>', 'ChatGPT Connector/MCP server name to record in ignored local config')
+    .action((rawOpts: McpSetupChatgptOptions) => {
+      void runMcpAction(() => {
+        const result = runMcpSetupChatgpt(rawOpts);
+        console.log(result.lines.join('\n'));
+      });
+    });
+
+  setup
+    .command('codex')
+    .description('Patch Codex MCP config for forge')
+    .option('--repo <path>', 'Repository root to configure', '.')
+    .option('--scope <scope>', 'Config scope: project|user', 'project')
+    .option('--dry-run', 'Print planned changes without writing files')
+    .action((rawOpts: McpSetupCodexOptions) => {
+      void runMcpAction(() => {
+        const result = runMcpSetupCodex(rawOpts);
+        console.log(result.lines.join('\n'));
+      });
+    });
+
+  mcp.addCommand(setup);
+
+  const access = new Command('access').description('Read or change repository Request / Full Access permission levels');
+
+  access
+    .command('get')
+    .description('Read the access mode for one registered repository')
+    .option('--repo <path>', 'Repository root used to resolve controllerHome', '.')
+    .option('--controller-home <path>', 'Controller state root; defaults to repo _ops/controller-home when present')
+    .option('--repo-id <id>', 'Stable registered repository id')
+    .action((rawOpts: McpAccessOptions) => {
+      void runMcpAction(() => runRepositoryAccessCommand('repository_access_get', rawOpts));
+    });
+
+  access
+    .command('set')
+    .description('Set Request or Full Access for one repository or every enabled repository')
+    .option('--repo <path>', 'Repository root used to resolve controllerHome', '.')
+    .option('--controller-home <path>', 'Controller state root; defaults to repo _ops/controller-home when present')
+    .option('--repo-id <id>', 'Stable registered repository id; cannot be combined with --all-repositories')
+    .option('--all-repositories', 'Apply to every enabled registered repository')
+    .requiredOption('--mode <mode>', 'Access mode: request|full_access')
+    .option('--confirm-authorization', 'Confirm the access policy write')
+    .option('--confirmation-text <text>', 'Legacy optional confirmation text; access changes require --confirm-authorization')
+    .action((rawOpts: McpAccessOptions) => {
+      void runMcpAction(() => runRepositoryAccessCommand('repository_access_set', rawOpts));
+    });
+
+  mcp.addCommand(access);
+
+
+  mcp
+    .command('prepare-goal')
+    .description('Prepare .ai/harness/handoff/codex-goal.md and print a host-native /goal prompt from a PRD and checklist Sprint')
+    .option('--repo <path>', 'Repository root to configure', '.')
+    .requiredOption('--prd <path>', 'PRD path to read')
+    .requiredOption('--sprint <path>', 'Checklist Sprint path to execute')
+    .option('--reference-repo <path>', 'Read-only reference repo path to include in the Goal')
+    .option('--extra-instructions <text>', 'Additional bounded execution instruction for Codex')
+    .option('--overwrite', 'Replace an existing Codex goal handoff')
+    .action((rawOpts: McpPrepareGoalOptions) => {
+      void runMcpAction(async () => {
+        const lines = await prepareCodexGoalFromSprint(rawOpts);
+        console.log(lines.join('\n'));
+      });
+    });
+
+  mcp
+    .command('print-chatgpt-guide')
+    .description('Print the ChatGPT Connector setup guide')
+    .option('--repo <path>', 'Repository root to inspect', '.')
+    .option('--endpoint <url>', 'Public HTTPS /mcp endpoint to include in the guide')
+    .option('--write', 'Write docs/forge-chatgpt-mcp-setup.md')
+    .action((rawOpts: { repo?: string; endpoint?: string; write?: boolean }) => {
+      void runMcpAction(() => {
+        const result = runMcpPrintGuide(rawOpts);
+        console.log(result.lines.join('\n'));
+      });
+    });
+
+  return mcp;
+}

package/src/cli/commands/migrate.ts

@@ -0,0 +1,154 @@
+/**
+ * `forge migrate` — convert legacy project-level hook adapters to the
+ * global CLI pattern (dry-run default; --apply commits).
+ *
+ * Targets two legacy file shapes:
+ *   - <repo>/.codex/hooks.json       (Phase 0 / pre-CLI Codex adapter)
+ *   - <repo>/.claude/settings.json   (Phase 0 / pre-CLI Claude adapter, hooks segment)
+ *
+ * Identification: any hook command containing `run-hook.sh` substring is treated
+ * as a legacy project-level entry. Phase 0 prototype + canary observations
+ * confirmed this is the stable signature. User-authored sibling hooks (e.g.
+ * `rtk hook claude`) do not match and survive migration.
+ *
+ * Safety:
+ *   - --dry-run is default; --apply explicitly mutates.
+ *   - Per-file backup before --apply: <file>.forge-migrate-backup.
+ *   - If the file's hooks segment becomes empty after removal, the field is
+ *     dropped entirely (cleaner for Claude settings.json which has non-hook config).
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { atomicWriteFileSync, formatJson, readJsonOrEmpty } from '../installer/shared';
+import type { HookEntry, HooksByEvent } from '../installer/managed-entries';
+
+const LEGACY_TAG = 'run-hook.sh';
+
+export interface MigrateOptions {
+  cwd?: string;
+  apply?: boolean;
+}
+
+export interface MigratePlanFile {
+  path: string;
+  legacyEntriesFound: number;
+  legacyEntries: Array<{ event: string; command: string }>;
+  action: 'no-op' | 'remove' | 'remove-and-clean-hooks-segment';
+}
+
+export interface MigratePlan {
+  files: MigratePlanFile[];
+  apply: boolean;
+}
+
+interface SettingsOrHooksFile {
+  hooks?: HooksByEvent;
+  [key: string]: unknown;
+}
+
+function isLegacyEntry(entry: HookEntry): boolean {
+  if (!entry || !Array.isArray(entry.hooks)) return false;
+  return entry.hooks.some(
+    (h) => typeof h?.command === 'string' && h.command.includes(LEGACY_TAG),
+  );
+}
+
+function stripLegacyEntries(existing: HooksByEvent | undefined): {
+  cleaned: HooksByEvent;
+  removed: Array<{ event: string; command: string }>;
+} {
+  const cleaned: HooksByEvent = {};
+  const removed: Array<{ event: string; command: string }> = [];
+  if (!existing) return { cleaned, removed };
+  for (const [event, entries] of Object.entries(existing)) {
+    const kept: HookEntry[] = [];
+    for (const entry of entries ?? []) {
+      if (isLegacyEntry(entry)) {
+        removed.push({ event, command: entry.hooks?.[0]?.command ?? '(unknown)' });
+      } else {
+        kept.push(entry);
+      }
+    }
+    if (kept.length > 0) cleaned[event] = kept;
+  }
+  return { cleaned, removed };
+}
+
+function planForFile(filePath: string): MigratePlanFile | null {
+  if (!fs.existsSync(filePath)) return null;
+  const data = readJsonOrEmpty<SettingsOrHooksFile>(filePath);
+  const { cleaned, removed } = stripLegacyEntries(data.hooks);
+  if (removed.length === 0) {
+    return { path: filePath, legacyEntriesFound: 0, legacyEntries: [], action: 'no-op' };
+  }
+  const action: MigratePlanFile['action'] =
+    Object.keys(cleaned).length === 0 ? 'remove-and-clean-hooks-segment' : 'remove';
+  return {
+    path: filePath,
+    legacyEntriesFound: removed.length,
+    legacyEntries: removed,
+    action,
+  };
+}
+
+function applyForFile(filePath: string): void {
+  const backupPath = `${filePath}.forge-migrate-backup`;
+  if (!fs.existsSync(backupPath)) {
+    fs.copyFileSync(filePath, backupPath);
+  }
+  const data = readJsonOrEmpty<SettingsOrHooksFile>(filePath);
+  const { cleaned } = stripLegacyEntries(data.hooks);
+  const next: SettingsOrHooksFile = { ...data, hooks: cleaned };
+  if (Object.keys(cleaned).length === 0) {
+    delete (next as Record<string, unknown>).hooks;
+  }
+  atomicWriteFileSync(filePath, formatJson(next));
+}
+
+export function runMigrate(opts: MigrateOptions = {}): MigratePlan {
+  const cwd = opts.cwd ?? process.cwd();
+  const apply = opts.apply === true;
+  const files: MigratePlanFile[] = [];
+  const candidates = [
+    path.join(cwd, '.codex/hooks.json'),
+    path.join(cwd, '.claude/settings.json'),
+  ];
+  for (const filePath of candidates) {
+    const plan = planForFile(filePath);
+    if (!plan) continue;
+    files.push(plan);
+    if (apply && plan.action !== 'no-op') {
+      applyForFile(filePath);
+    }
+  }
+  return { files, apply };
+}
+
+export function formatMigratePlan(plan: MigratePlan, asJson = false): string {
+  if (asJson) return JSON.stringify(plan, null, 2);
+  const lines: string[] = [];
+  lines.push(plan.apply ? '--apply mode (mutating)' : '--dry-run mode (no changes)');
+  lines.push('');
+  if (plan.files.length === 0) {
+    lines.push('  no legacy hook files found in current repo');
+  }
+  for (const f of plan.files) {
+    if (f.action === 'no-op') {
+      lines.push(`  ${f.path}: no legacy entries`);
+    } else {
+      lines.push(`  ${f.path}: ${f.legacyEntriesFound} legacy entries (${f.action})`);
+      for (const e of f.legacyEntries) {
+        const cmd = e.command.length > 80 ? `${e.command.slice(0, 80)}…` : e.command;
+        lines.push(`    - ${e.event}: ${cmd}`);
+      }
+    }
+  }
+  lines.push('');
+  if (plan.apply) {
+    lines.push('Backups created: <file>.forge-migrate-backup');
+  } else {
+    lines.push('Re-run with --apply to commit.');
+  }
+  return lines.join('\n');
+}

package/src/cli/commands/plugin.ts

@@ -0,0 +1,74 @@
+import { spawnSync } from 'child_process';
+import { randomUUID } from 'crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync } from 'fs';
+import { dirname, isAbsolute, join, resolve, sep } from 'path';
+import { fileURLToPath } from 'url';
+import { Command } from 'commander';
+import { resolveControllerHome, controllerSystemRoot } from '../repositories/controller-home';
+import { installExternalPluginRegistration, listExternalPluginRegistrations, type ExternalPluginRegistrationInput } from '../../runtime/plugins/external-registration';
+import { createDesktopOperatorRegistrationInput } from '../../runtime/plugins/desktop-operator-registration';
+import { controllerPluginRepository, getAssistantPluginManifest, syncAssistantPluginRegistry } from '../../runtime/plugins/store';
+
+interface RegistryEntry { id:string; name:string; version:string; description:string; repository:string; ref:string; installer:string; platforms:NodeJS.Platform[]; }
+interface Registry { schemaVersion:1; plugins:RegistryEntry[]; }
+interface CliOptions { json?:boolean; controllerHome?:string; refresh?:boolean; }
+const packageRoot=resolve(dirname(fileURLToPath(import.meta.url)),'../../..');
+const registryPath=join(packageRoot,'assets','plugin-registry.v1.json');
+
+function registry():Registry{
+  const value=JSON.parse(readFileSync(registryPath,'utf8')) as Registry;
+  if(value.schemaVersion!==1||!Array.isArray(value.plugins))throw new Error('PLUGIN_CATALOG_INVALID');
+  const ids=new Set<string>();
+  for(const plugin of value.plugins){
+    if(!/^[a-z][a-z0-9_]{1,63}$/.test(plugin.id)||ids.has(plugin.id))throw new Error(`PLUGIN_CATALOG_INVALID_ID: ${plugin.id}`);
+    if(!plugin.repository.startsWith('https://github.com/moretea-labs/')||!plugin.repository.endsWith('.git'))throw new Error(`PLUGIN_CATALOG_UNTRUSTED_REPOSITORY: ${plugin.id}`);
+    if(!/^v\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(plugin.ref))throw new Error(`PLUGIN_CATALOG_UNPINNED_REF: ${plugin.id}`);
+    if(plugin.installer!=='forge-plugin-install.mjs')throw new Error(`PLUGIN_CATALOG_INSTALLER_INVALID: ${plugin.id}`);
+    ids.add(plugin.id);
+  }
+  return value;
+}
+function within(root:string,relative:string):string{const target=resolve(root,relative);const base=`${resolve(root)}${sep}`;if(target!==resolve(root)&&!target.startsWith(base))throw new Error('PLUGIN_INSTALL_PATH_ESCAPE');return target;}
+function run(command:string,args:string[],cwd:string,timeoutMs=120000):string{
+  const result=spawnSync(command,args,{cwd,encoding:'utf8',timeout:timeoutMs,maxBuffer:32*1024*1024,shell:false,windowsHide:true});
+  if(result.error)throw new Error(`PLUGIN_INSTALL_COMMAND_FAILED: ${result.error.message}`);
+  if(result.status!==0)throw new Error(`PLUGIN_INSTALL_COMMAND_FAILED: ${command} exited ${result.status}: ${String(result.stderr||result.stdout).slice(-4000)}`);
+  return String(result.stdout??'');
+}
+function installerJson(stdout:string):Record<string,unknown>{
+  const lines=stdout.split(/\r?\n/).map(x=>x.trim()).filter(Boolean);
+  for(let i=lines.length-1;i>=0;i--){try{const x=JSON.parse(lines[i]);if(x&&typeof x==='object'&&!Array.isArray(x)&&x.schemaVersion===1)return x;}catch{}}
+  throw new Error('PLUGIN_INSTALLER_OUTPUT_INVALID');
+}
+function registrationFrom(result:Record<string,unknown>,entry:RegistryEntry):ExternalPluginRegistrationInput{
+  if(result.registration){const input=result.registration as ExternalPluginRegistrationInput;if(input.pluginId!==entry.id)throw new Error('PLUGIN_INSTALLER_ID_MISMATCH');if(input.pluginVersion!==entry.version)throw new Error('PLUGIN_INSTALLER_VERSION_MISMATCH');return input;}
+  const facts=result.providerInstall as Record<string,unknown>|undefined;
+  if(!facts||facts.kind!=='desktop_operator'||entry.id!=='desktop_operator')throw new Error('PLUGIN_INSTALLER_REGISTRATION_MISSING');
+  if(facts.pluginVersion!==entry.version||facts.protocolVersion!=='1.0')throw new Error('PLUGIN_INSTALLER_PROVIDER_VERSION_MISMATCH');
+  const socketPath=typeof facts.socketPath==='string'?facts.socketPath:'';const launchAgentLabel=typeof facts.launchAgentLabel==='string'?facts.launchAgentLabel:'';const expectedProgramContains=typeof facts.expectedProgramContains==='string'?facts.expectedProgramContains:'';
+  if(!isAbsolute(socketPath)||!launchAgentLabel||!expectedProgramContains)throw new Error('PLUGIN_INSTALLER_PROVIDER_FACTS_INVALID');
+  return createDesktopOperatorRegistrationInput({socketPath,launchAgentLabel,expectedProgramContains,pluginVersion:entry.version,protocolVersion:'1.0'});
+}
+function install(entry:RegistryEntry,controllerHome:string):Record<string,unknown>{
+  if(!entry.platforms.includes(process.platform))throw new Error(`PLUGIN_PLATFORM_UNSUPPORTED: ${entry.id}/${process.platform}`);
+  const packagesRoot=join(controllerSystemRoot(controllerHome),'plugins','packages');mkdirSync(packagesRoot,{recursive:true,mode:0o700});
+  const finalRoot=join(packagesRoot,entry.id),stage=join(packagesRoot,`.${entry.id}.${randomUUID()}.staging`),backup=join(packagesRoot,`.${entry.id}.${randomUUID()}.backup`);let backed=false;
+  try{
+    run('git',['clone','--depth','1','--branch',entry.ref,'--single-branch',entry.repository,stage],packagesRoot);
+    const manifestPath=within(stage,'forge-plugin.json'),installerBefore=within(stage,entry.installer);if(!existsSync(manifestPath)||!existsSync(installerBefore))throw new Error(`PLUGIN_PACKAGE_INCOMPLETE: ${entry.id}`);
+    const manifest=JSON.parse(readFileSync(manifestPath,'utf8')) as Record<string,unknown>;if(manifest.id!==entry.id||manifest.version!==entry.version)throw new Error(`PLUGIN_PACKAGE_IDENTITY_MISMATCH: ${entry.id}`);
+    if(existsSync(finalRoot)){renameSync(finalRoot,backup);backed=true;}renameSync(stage,finalRoot);
+    const result=installerJson(run(process.execPath,[within(finalRoot,entry.installer)],finalRoot,180000));
+    const installed=installExternalPluginRegistration(controllerHome,registrationFrom(result,entry));
+    const repository=controllerPluginRepository(controllerHome);syncAssistantPluginRegistry(controllerHome,repository);const plugin=getAssistantPluginManifest(controllerHome,repository,entry.id);
+    if(backed)rmSync(backup,{recursive:true,force:true});
+    return{pluginId:entry.id,version:entry.version,packageRoot:finalRoot,registrationRevision:installed.revision,enabled:plugin.enabled,health:plugin.health};
+  }catch(error){rmSync(stage,{recursive:true,force:true});if(backed&&existsSync(finalRoot))rmSync(finalRoot,{recursive:true,force:true});if(backed&&existsSync(backup))renameSync(backup,finalRoot);throw error;}
+}
+export function buildPluginCommand():Command{
+  const root=new Command('plugin').description('Discover and install trusted Forge plugins');
+  root.command('catalog').description('List official plugins').option('--json','Output JSON').action((o:CliOptions)=>{const items=registry().plugins.map(x=>({...x,compatible:x.platforms.includes(process.platform)}));if(o.json)console.log(JSON.stringify({schemaVersion:1,platform:process.platform,plugins:items},null,2));else items.forEach(x=>console.log(`${x.id}\t${x.version}\t${x.compatible?'compatible':'unsupported'}\t${x.name}`));});
+  root.command('list').description('List installed external plugins').option('--json','Output JSON').option('--controller-home <path>','Override Controller Home').option('--refresh','Probe providers').action((o:CliOptions)=>{const home=resolveControllerHome(o.controllerHome),repo=controllerPluginRepository(home);if(o.refresh)syncAssistantPluginRegistry(home,repo);const items=listExternalPluginRegistrations(home).map(r=>{let health:unknown;try{health=getAssistantPluginManifest(home,repo,r.pluginId).health;}catch(e){health={state:'error',message:e instanceof Error?e.message:String(e)};}return{pluginId:r.pluginId,version:r.pluginVersion,provider:r.provider,enabled:r.enabled,transport:r.transport.kind,health};});if(o.json)console.log(JSON.stringify({schemaVersion:1,plugins:items},null,2));else if(!items.length)console.log('No external Forge plugins installed.');else items.forEach(x=>console.log(`${x.pluginId}\t${x.version}\t${x.enabled?'enabled':'disabled'}\t${(x.health as {state?:string})?.state??'unknown'}`));});
+  root.command('install <plugin-id>').description('Install/update an official plugin from a pinned public release').option('--json','Output JSON').option('--controller-home <path>','Override Controller Home').action((id:string,o:CliOptions)=>{const entry=registry().plugins.find(x=>x.id===id);if(!entry)throw new Error(`PLUGIN_NOT_IN_OFFICIAL_CATALOG: ${id}`);const result=install(entry,resolveControllerHome(o.controllerHome));if(o.json)console.log(JSON.stringify(result,null,2));else console.log(`Installed ${entry.name} ${entry.version} (${(result.health as {state?:string})?.state??'unknown'}).`);});
+  return root;
+}