@moretea-labs/forge 1.7.2 → 1.8.0

package/src/cli/commands/computer.ts

@@ -0,0 +1,437 @@
+import { spawnSync } from 'child_process';
+import { existsSync, rmSync } from 'fs';
+import { join } from 'path';
+import { Command } from 'commander';
+import {
+  COMPUTER_BROWSER_AUTOMATION_CAPABILITY,
+  COMPUTER_CAPTURE_CAPABILITY,
+  COMPUTER_CONSOLE_UNLOCK_CAPABILITY,
+  COMPUTER_ELEMENT_ACTION_CAPABILITY,
+  COMPUTER_ELEMENT_OBSERVE_CAPABILITY,
+  COMPUTER_INPUT_CAPABILITY,
+  COMPUTER_OBSERVE_CAPABILITY,
+  type ComputerCapabilityId,
+} from '../../../packages/protocols/computer/index';
+import { resolveControllerHome, controllerSystemRoot } from '../repositories/controller-home';
+import { getExternalPluginRegistration, removeExternalPluginRegistration } from '../../runtime/plugins/external-registration';
+import {
+  readControllerStoredPluginManifest,
+  removeControllerPluginManifestProjection,
+  syncControllerPluginManifest,
+} from '../../runtime/plugins/store';
+import {
+  installOfficialPlugin,
+  officialPluginCatalogEntry,
+  pluginCatalogCompatibility,
+  withOfficialPluginLifecycleLock,
+} from './plugin';
+
+export const COMPUTER_PROVIDER_PLUGIN_ID = 'desktop_operator';
+const COMPUTER_PRODUCT_ID = 'computer';
+
+interface ComputerCliOptions {
+  controllerHome?: string;
+  json?: boolean;
+  purge?: boolean;
+}
+
+export interface ComputerProviderHealth {
+  state: string;
+  ready: boolean;
+  probed: boolean;
+  errors: string[];
+  warnings: string[];
+  details?: Record<string, unknown>;
+}
+
+export interface ComputerProviderStatus {
+  implementation: 'Forge Desktop Operator';
+  pluginId: typeof COMPUTER_PROVIDER_PLUGIN_ID;
+  installedVersion?: string;
+  protocolVersion?: string;
+  catalogVersion: string;
+  enabled: boolean;
+  updateAvailable: boolean;
+  releaseIndependent: true;
+  transport?: string;
+  lifecycle?: string;
+  health: ComputerProviderHealth;
+}
+
+export type ComputerCapabilityState = 'ready' | 'missing' | 'degraded' | 'unsupported';
+
+export interface ComputerCapabilityStatus {
+  capabilityId: ComputerCapabilityId;
+  provider: 'browser' | 'desktop_operator';
+  supported: boolean;
+  ready: boolean;
+  state: ComputerCapabilityState;
+  reason?: string;
+}
+
+export interface ComputerStatusReport {
+  schemaVersion: 1;
+  product: typeof COMPUTER_PRODUCT_ID;
+  platform: NodeJS.Platform;
+  supported: boolean;
+  partial: boolean;
+  installed: boolean;
+  ready: boolean;
+  capabilities: ComputerCapabilityStatus[];
+  provider: ComputerProviderStatus;
+  compatibilityReason?: string;
+}
+
+export interface ComputerDoctorReport {
+  schemaVersion: 1;
+  product: typeof COMPUTER_PRODUCT_ID;
+  ok: boolean;
+  status: ComputerStatusReport;
+  checks: Array<{ id: string; state: 'pass' | 'warn' | 'fail'; message: string }>;
+}
+
+function catalogEntry() {
+  const entry = officialPluginCatalogEntry(COMPUTER_PROVIDER_PLUGIN_ID);
+  if (!entry) throw new Error('COMPUTER_PROVIDER_CATALOG_ENTRY_MISSING');
+  return entry;
+}
+
+function providerPackageRoot(controllerHome: string): string {
+  return join(controllerSystemRoot(controllerHome), 'plugins', 'packages', COMPUTER_PROVIDER_PLUGIN_ID);
+}
+
+function unavailableHealth(state: string, message: string): ComputerProviderHealth {
+  return {
+    state,
+    ready: false,
+    probed: false,
+    errors: [message],
+    warnings: [],
+  };
+}
+
+function providerHealth(controllerHome: string): ComputerProviderHealth {
+  const registration = getExternalPluginRegistration(controllerHome, COMPUTER_PROVIDER_PLUGIN_ID);
+  if (!registration) return unavailableHealth('not_installed', 'Computer macOS provider is not installed.');
+  const stored = readControllerStoredPluginManifest(controllerHome, COMPUTER_PROVIDER_PLUGIN_ID);
+  if (!stored) {
+    return unavailableHealth('unprobed', 'Computer provider health has not been recorded yet; run forge computer doctor.');
+  }
+  const health = stored.health;
+  return {
+    state: health.state,
+    ready: health.ready,
+    probed: health.probed,
+    errors: [...health.errors],
+    warnings: [...health.warnings],
+    details: health.details ? { ...health.details } : undefined,
+  };
+}
+
+function browserCapabilityStatus(input: {
+  compatibility: ReturnType<typeof pluginCatalogCompatibility>;
+  registration: ReturnType<typeof getExternalPluginRegistration>;
+  health: ComputerProviderHealth;
+}): ComputerCapabilityStatus {
+  if (!input.compatibility.compatible) {
+    return {
+      capabilityId: COMPUTER_BROWSER_AUTOMATION_CAPABILITY,
+      provider: 'desktop_operator',
+      supported: false,
+      ready: false,
+      state: 'unsupported',
+      reason: `No native Computer browser provider is available: ${input.compatibility.reason}`,
+    };
+  }
+
+  if (!input.registration) {
+    return {
+      capabilityId: COMPUTER_BROWSER_AUTOMATION_CAPABILITY,
+      provider: 'browser',
+      supported: true,
+      ready: false,
+      state: 'missing',
+      reason: 'Native Browser compatibility mechanics require the installed macOS Computer provider.',
+    };
+  }
+  const ready = input.registration.enabled && input.health.ready;
+  return {
+    capabilityId: COMPUTER_BROWSER_AUTOMATION_CAPABILITY,
+    provider: 'browser',
+    supported: true,
+    ready,
+    state: ready ? 'ready' : 'degraded',
+    reason: ready ? undefined : (input.health.errors[0] ?? input.health.warnings[0] ?? `Native Browser compatibility health is ${input.health.state}.`),
+  };
+}
+
+function desktopCapabilityStatus(
+  capabilityId: typeof COMPUTER_OBSERVE_CAPABILITY | typeof COMPUTER_INPUT_CAPABILITY | typeof COMPUTER_CONSOLE_UNLOCK_CAPABILITY | typeof COMPUTER_CAPTURE_CAPABILITY | typeof COMPUTER_ELEMENT_OBSERVE_CAPABILITY | typeof COMPUTER_ELEMENT_ACTION_CAPABILITY,
+  compatibility: ReturnType<typeof pluginCatalogCompatibility>,
+  registration: ReturnType<typeof getExternalPluginRegistration>,
+  health: ComputerProviderHealth,
+): ComputerCapabilityStatus {
+  if (!compatibility.compatible) return { capabilityId, provider: 'desktop_operator', supported: false, ready: false, state: 'unsupported', reason: compatibility.reason };
+  if (!registration) return { capabilityId, provider: 'desktop_operator', supported: true, ready: false, state: 'missing', reason: 'Native Computer provider is not installed.' };
+  const declared = registration.capabilities.some((capability) => capability.capabilityId === capabilityId);
+  const ready = registration.enabled && health.ready && declared;
+  return {
+    capabilityId,
+    provider: 'desktop_operator',
+    supported: true,
+    ready,
+    state: ready ? 'ready' : 'degraded',
+    reason: ready ? undefined : (!declared
+      ? `Installed native Computer provider does not declare ${capabilityId}.`
+      : (health.errors[0] ?? health.warnings[0] ?? `Native Computer provider health is ${health.state}.`)),
+  };
+}
+
+export function readComputerStatus(options: { controllerHome?: string; platform?: NodeJS.Platform } = {}): ComputerStatusReport {
+  const controllerHome = resolveControllerHome(options.controllerHome);
+  const platform = options.platform ?? process.platform;
+  const entry = catalogEntry();
+  const compatibility = pluginCatalogCompatibility(entry, platform);
+  const registration = getExternalPluginRegistration(controllerHome, COMPUTER_PROVIDER_PLUGIN_ID);
+  const health = providerHealth(controllerHome);
+  const installedVersion = registration?.pluginVersion;
+  const provider: ComputerProviderStatus = {
+    implementation: 'Forge Desktop Operator',
+    pluginId: COMPUTER_PROVIDER_PLUGIN_ID,
+    installedVersion,
+    protocolVersion: registration?.protocolVersion,
+    catalogVersion: entry.version,
+    enabled: registration?.enabled === true,
+    updateAvailable: Boolean(installedVersion && installedVersion !== entry.version),
+    releaseIndependent: true,
+    transport: registration?.transport.kind,
+    lifecycle: registration?.lifecycle?.kind,
+    health,
+  };
+  const capabilities = [
+    browserCapabilityStatus({ compatibility, registration, health }),
+    desktopCapabilityStatus(COMPUTER_OBSERVE_CAPABILITY, compatibility, registration, health),
+    desktopCapabilityStatus(COMPUTER_INPUT_CAPABILITY, compatibility, registration, health),
+    desktopCapabilityStatus(COMPUTER_CONSOLE_UNLOCK_CAPABILITY, compatibility, registration, health),
+    desktopCapabilityStatus(COMPUTER_CAPTURE_CAPABILITY, compatibility, registration, health),
+    desktopCapabilityStatus(COMPUTER_ELEMENT_OBSERVE_CAPABILITY, compatibility, registration, health),
+    desktopCapabilityStatus(COMPUTER_ELEMENT_ACTION_CAPABILITY, compatibility, registration, health),
+  ];
+  const supportedCapabilities = capabilities.filter((capability) => capability.supported);
+  return {
+    schemaVersion: 1,
+    product: COMPUTER_PRODUCT_ID,
+    platform,
+    supported: supportedCapabilities.length > 0,
+    partial: supportedCapabilities.length > 0 && supportedCapabilities.length < capabilities.length,
+    installed: Boolean(registration),
+    ready: capabilities.every((capability) => capability.ready),
+    capabilities,
+    provider,
+    compatibilityReason: compatibility.reason,
+  };
+}
+
+export function runComputerSetup(options: { controllerHome?: string; platform?: NodeJS.Platform } = {}): {
+  installed: Record<string, unknown>;
+  status: ComputerStatusReport;
+} {
+  const controllerHome = resolveControllerHome(options.controllerHome);
+  const compatibility = pluginCatalogCompatibility(catalogEntry(), options.platform ?? process.platform);
+  if (!compatibility.compatible) {
+    throw new Error(`COMPUTER_PROVIDER_UNAVAILABLE_ON_PLATFORM: ${compatibility.reason}. Forge has no installable native Computer provider for this platform.`);
+  }
+  const installed = installOfficialPlugin(COMPUTER_PROVIDER_PLUGIN_ID, controllerHome);
+  return { installed, status: readComputerStatus({ controllerHome, platform: options.platform }) };
+}
+
+export function runComputerUpdate(options: { controllerHome?: string; platform?: NodeJS.Platform } = {}) {
+  return runComputerSetup(options);
+}
+
+export function runComputerDoctor(options: { controllerHome?: string; platform?: NodeJS.Platform } = {}): ComputerDoctorReport {
+  const controllerHome = resolveControllerHome(options.controllerHome);
+  const platform = options.platform ?? process.platform;
+  const compatibility = pluginCatalogCompatibility(catalogEntry(), platform);
+  // A stale macOS registration must never launch a synchronous socket probe on a
+  // platform where the provider cannot execute. Status remains a stored-state read.
+  if (compatibility.compatible && getExternalPluginRegistration(controllerHome, COMPUTER_PROVIDER_PLUGIN_ID)) {
+    syncControllerPluginManifest(controllerHome, COMPUTER_PROVIDER_PLUGIN_ID);
+  }
+  const status = readComputerStatus({ controllerHome, platform });
+  const checks: ComputerDoctorReport['checks'] = [];
+  checks.push({
+    id: 'platform',
+    state: status.partial ? 'warn' : (status.supported ? 'pass' : 'fail'),
+    message: status.partial
+      ? `Computer has partial capability support on ${status.platform}; capability details are reported individually.`
+      : (status.supported ? `Computer capabilities are supported on ${status.platform}.` : `Computer is unsupported on ${status.platform}.`),
+  });
+  for (const capability of status.capabilities) {
+    checks.push({
+      id: `capability:${capability.capabilityId}`,
+      state: capability.ready ? 'pass' : (capability.supported ? 'fail' : 'warn'),
+      message: capability.ready ? `${capability.capabilityId} is ready.` : (capability.reason ?? `${capability.capabilityId} is ${capability.state}.`),
+    });
+  }
+  const nativeProviderSupported = status.capabilities.some((capability) => capability.provider === 'desktop_operator' && capability.supported);
+  checks.push({
+    id: 'installed',
+    state: nativeProviderSupported ? (status.installed ? 'pass' : 'fail') : 'warn',
+    message: nativeProviderSupported
+      ? (status.installed ? `Native Computer provider ${status.provider.installedVersion ?? 'unknown'} is installed.` : 'Native Computer provider is not installed.')
+      : `Native Desktop Computer provider is not part of the supported capability set on ${status.platform}.`,
+  });
+  if (status.installed && compatibility.compatible) {
+    checks.push({
+      id: 'registration',
+      state: status.provider.enabled ? 'pass' : 'fail',
+      message: status.provider.enabled
+        ? 'Computer provider registration is enabled.'
+        : 'Computer provider registration is disabled.',
+    });
+    checks.push({
+      id: 'release',
+      state: status.provider.updateAvailable ? 'warn' : 'pass',
+      message: status.provider.updateAvailable
+        ? `Computer provider ${status.provider.installedVersion ?? 'unknown'} differs from pinned ${status.provider.catalogVersion}; run forge computer update.`
+        : `Computer provider matches pinned ${status.provider.catalogVersion}.`,
+    });
+    checks.push({
+      id: 'provider-health',
+      state: status.provider.health.ready
+        ? 'pass'
+        : (status.provider.health.state === 'degraded' ? 'warn' : 'fail'),
+      message: status.provider.health.errors[0]
+        ?? status.provider.health.warnings[0]
+        ?? `Computer provider health is ${status.provider.health.state}.`,
+    });
+  } else if (status.installed) {
+    checks.push({
+      id: 'provider-platform',
+      state: 'warn',
+      message: `Installed Computer provider is incompatible with ${status.platform}; its live health probe was intentionally skipped.`,
+    });
+  }
+  return {
+    schemaVersion: 1,
+    product: COMPUTER_PRODUCT_ID,
+    ok: checks.every((check) => check.state !== 'fail'),
+    status,
+    checks,
+  };
+}
+
+function runProviderUninstaller(scriptPath: string, packageRoot: string, purge: boolean): void {
+  const result = spawnSync('/bin/bash', [scriptPath, ...(purge ? ['--purge'] : [])], {
+    cwd: packageRoot,
+    encoding: 'utf8',
+    timeout: 120_000,
+    maxBuffer: 8 * 1024 * 1024,
+    shell: false,
+    windowsHide: true,
+  });
+  if (result.error) throw new Error(`COMPUTER_PROVIDER_UNINSTALL_FAILED: ${result.error.message}`);
+  if (result.status !== 0) {
+    throw new Error(`COMPUTER_PROVIDER_UNINSTALL_FAILED: provider uninstaller exited ${result.status}: ${String(result.stderr || result.stdout).slice(-4000)}`);
+  }
+}
+
+export function runComputerUninstall(options: { controllerHome?: string; purge?: boolean } = {}): {
+  removed: boolean;
+  purged: boolean;
+} {
+  const controllerHome = resolveControllerHome(options.controllerHome);
+  return withOfficialPluginLifecycleLock(controllerHome, COMPUTER_PROVIDER_PLUGIN_ID, () => {
+    const registration = getExternalPluginRegistration(controllerHome, COMPUTER_PROVIDER_PLUGIN_ID);
+    const packageRoot = providerPackageRoot(controllerHome);
+    if (!registration && !existsSync(packageRoot)) return { removed: false, purged: options.purge === true };
+    const scriptPath = join(packageRoot, 'scripts', 'uninstall.sh');
+    if (registration && !existsSync(scriptPath)) {
+      throw new Error('COMPUTER_PROVIDER_UNINSTALLER_MISSING: refusing to forget a registered provider while its native uninstall lifecycle cannot be proven.');
+    }
+    if (existsSync(scriptPath)) runProviderUninstaller(scriptPath, packageRoot, options.purge === true);
+    if (registration) {
+      removeExternalPluginRegistration(controllerHome, COMPUTER_PROVIDER_PLUGIN_ID, { expectedRevision: registration.revision });
+    }
+    rmSync(packageRoot, { recursive: true, force: true });
+    removeControllerPluginManifestProjection(controllerHome, COMPUTER_PROVIDER_PLUGIN_ID);
+    return { removed: true, purged: options.purge === true };
+  });
+}
+
+export function formatComputerStatus(report: ComputerStatusReport): string {
+  const lines = [
+    `Computer: ${report.ready ? 'ready' : (report.partial ? 'partial' : 'not ready')}`,
+    ...report.capabilities.map((capability) => `capability ${capability.capabilityId}: ${capability.state}`),
+    `native provider: Forge Desktop Operator ${report.provider.installedVersion ?? 'not installed'}${report.provider.updateAvailable ? ` (pinned ${report.provider.catalogVersion})` : ''}`,
+    `native service: ${report.provider.health.state}`,
+    `native protocol: ${report.provider.protocolVersion ?? 'n/a'}`,
+    'provider release: independent',
+  ];
+  if (report.provider.health.errors[0]) lines.push(`error: ${report.provider.health.errors[0]}`);
+  else if (report.provider.health.warnings[0]) lines.push(`warning: ${report.provider.health.warnings[0]}`);
+  if (report.compatibilityReason) lines.push(`compatibility: ${report.compatibilityReason}`);
+  return lines.join('\n');
+}
+
+export function formatComputerDoctor(report: ComputerDoctorReport): string {
+  return [
+    formatComputerStatus(report.status),
+    '',
+    ...report.checks.map((check) => `${check.state.toUpperCase()} ${check.id}: ${check.message}`),
+  ].join('\n');
+}
+
+export function buildComputerCommand(): Command {
+  const root = new Command('computer').description('Manage Forge Computer and its native platform provider');
+  root.command('status')
+    .description('Show Computer capability and native provider status')
+    .option('--json', 'Output JSON')
+    .option('--controller-home <path>', 'Override Controller Home')
+    .action((options: ComputerCliOptions) => {
+      const report = readComputerStatus(options);
+      console.log(options.json ? JSON.stringify(report, null, 2) : formatComputerStatus(report));
+    });
+  root.command('setup')
+    .description('Install or repair the pinned native Computer provider')
+    .option('--json', 'Output JSON')
+    .option('--controller-home <path>', 'Override Controller Home')
+    .action((options: ComputerCliOptions) => {
+      const result = runComputerSetup(options);
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatComputerStatus(result.status));
+    });
+  root.command('update')
+    .description('Update the native Computer provider to the Forge-pinned release')
+    .option('--json', 'Output JSON')
+    .option('--controller-home <path>', 'Override Controller Home')
+    .action((options: ComputerCliOptions) => {
+      const result = runComputerUpdate(options);
+      console.log(options.json ? JSON.stringify(result, null, 2) : formatComputerStatus(result.status));
+    });
+  root.command('doctor')
+    .description('Diagnose Computer provider compatibility, registration, release, and health')
+    .option('--json', 'Output JSON')
+    .option('--controller-home <path>', 'Override Controller Home')
+    .action((options: ComputerCliOptions) => {
+      const report = runComputerDoctor(options);
+      console.log(options.json ? JSON.stringify(report, null, 2) : formatComputerDoctor(report));
+      if (!report.ok) process.exitCode = 1;
+    });
+  root.command('uninstall')
+    .description('Uninstall the native Computer provider while retaining provider state by default')
+    .option('--purge', 'Also remove Desktop Operator provider state')
+    .option('--json', 'Output JSON')
+    .option('--controller-home <path>', 'Override Controller Home')
+    .action((options: ComputerCliOptions) => {
+      const result = runComputerUninstall(options);
+      if (options.json) {
+        console.log(JSON.stringify({ schemaVersion: 1, product: COMPUTER_PRODUCT_ID, ...result }, null, 2));
+      } else {
+        console.log(result.removed
+          ? `Computer provider uninstalled${result.purged ? ' and state purged' : ''}.`
+          : 'Computer provider is not installed.');
+      }
+    });
+  return root;
+}

package/src/cli/commands/doctor.ts

@@ -16,6 +16,8 @@ import { CLI_VERSION } from './status';
 import { runSecurityScan, type SecurityScanReport } from './security';
 import { isOptIn, resolveHooksDir, resolveRepoRoot } from '../hook/runtime';
 import { ROUTES } from '../hook/route-registry';
+import { resolveControllerHome } from '../repositories/controller-home';
+import { createSetupBootstrapControlApi } from './bootstrap-control';
 
 const TRUST_STATE_LINE = /^\[hooks\.state\."[^"]+\/\.codex\/hooks\.json:/;
 const PACKAGE_NAME = '@moretea-labs/forge';
@@ -384,6 +386,20 @@ function checkSecurityConfig(report: SecurityScanReport): DoctorCheckResult {
   };
 }
 
+function checkBootstrapLifecycle(): DoctorCheckResult {
+  const id = 'bootstrap-lifecycle';
+  const describe = 'V2 instance bootstrap lifecycle';
+  const snapshot = createSetupBootstrapControlApi({ controllerHome: resolveControllerHome() }).read();
+  if (!snapshot) return { id, describe, status: 'warn', detail: 'bootstrap lifecycle has not started; remediation=forge setup' };
+  if (snapshot.status === 'ready') return { id, describe, status: 'ok', detail: `bootstrap revision ${snapshot.revision} is ready` };
+  const fatal = snapshot.blockers.some((blocker) => blocker.kind === 'failed' || blocker.kind === 'unsupported');
+  const first = snapshot.blockers[0];
+  return {
+    id, describe, status: fatal ? 'fail' : 'warn',
+    detail: `${snapshot.status}; revision=${snapshot.revision}; ${first?.summary ?? 'setup is incomplete'}; remediation=${first?.actionIds[0] ?? 'forge setup next'}`,
+  };
+}
+
 function checkHookScriptDrift(cwd: string): DoctorCheckResult {
   const id = 'repo-hook-scripts';
   const describe = 'Active hook runtime scripts match the route registry';
@@ -396,7 +412,7 @@ function checkHookScriptDrift(cwd: string): DoctorCheckResult {
       id,
       describe,
       status: 'na',
-      detail: 'repo is not opted in (.ai/harness/workflow-contract.json missing)',
+      detail: 'repo is not opted in (forge.config.json missing; legacy .ai/harness marker also absent)',
     };
   }
 
@@ -452,6 +468,7 @@ export function runDoctor(cwd: string = process.cwd()): DoctorReport {
   checks.push(checkCodegraphIndex(codegraphProbe));
   checks.push(checkSecurityConfig(securityReport));
   checks.push(checkHookScriptDrift(cwd));
+  checks.push(checkBootstrapLifecycle());
   for (const plugin of REGISTERED_CHECKS) {
     const r = plugin.run();
     checks.push({ id: plugin.id, describe: plugin.describe, ...r });