@moretea-labs/forge 1.5.0-rc.1

package/src/cli/commands/repository.ts

@@ -0,0 +1,224 @@
+import { Command } from 'commander';
+import { executeRepositoryCommand } from '../repositories/command-executor';
+import { bindRepositoryEntities } from '../repositories/entity-migration';
+import { withControllerLock } from '../repositories/locks';
+import { bootstrapLocalProject, diagnoseLatestLocalProjectSource } from '../repositories/local-project-onboarding';
+import {
+  disableRepository,
+  focusRepository,
+  getRepository,
+  getRepositoryFocus,
+  listRepositories,
+  refreshRepository,
+  registerRepository,
+  removeRepository,
+  repositorySummary,
+  resolveRepositorySelection,
+  updateRepository,
+  validateRepository,
+} from '../repositories/registry';
+import { ensureRepositoryRuntimeStorage } from '../repositories/runtime-storage';
+import type { RepositoryRecord } from '../repositories/types';
+import { buildControllerWorkbench } from '../repositories/workbench';
+import { createUmbrellaIssue, getUmbrellaIssue, listUmbrellaIssues, updateUmbrellaTask } from '../repositories/umbrella';
+
+function output(value: unknown, json: boolean): void {
+  if (json) console.log(JSON.stringify(value, null, 2));
+  else console.log(typeof value === 'string' ? value : JSON.stringify(value, null, 2));
+}
+
+function common(command: Command): Command {
+  return command
+    .option('--controller-home <path>', 'Controller global data directory')
+    .option('--json', 'Output JSON');
+}
+
+function initializeRepository(repository: RepositoryRecord, controllerHome?: string) {
+  const runtimeStorage = ensureRepositoryRuntimeStorage(repository, controllerHome);
+  const migration = bindRepositoryEntities(repository);
+  return { repository, runtimeStorage, migration };
+}
+
+export function buildRepositoryCommand(): Command {
+  const command = new Command('repo').description('Register and inspect repositories managed by the global Controller');
+
+  common(command.command('register')
+    .description('Register a Git repository without relying on the Controller startup directory')
+    .argument('<path>', 'Repository checkout path')
+    .option('--name <display-name>', 'Display name')
+    .option('--remote <url>', 'Override remote URL')
+    .option('--default-branch <branch>', 'Override default branch'))
+    .action((path: string, opts: { controllerHome?: string; name?: string; remote?: string; defaultBranch?: string; json?: boolean }) => {
+      const repository = registerRepository({ path, controllerHome: opts.controllerHome, displayName: opts.name, remoteUrl: opts.remote, defaultBranch: opts.defaultBranch });
+      output(initializeRepository(repository, opts.controllerHome), opts.json === true);
+    });
+
+  common(command.command('diagnose-local')
+    .description('Read-only diagnosis for picking the latest local project source tree among sibling directories')
+    .argument('<path>', 'Absolute local project path')
+    .option('--repo-id <repo-id>', 'Registered repository to diagnose instead of the path'))
+    .action((path: string, opts: { controllerHome?: string; repoId?: string; json?: boolean }) => {
+      output(diagnoseLatestLocalProjectSource({ path, repoId: opts.repoId, controllerHome: opts.controllerHome }), opts.json === true);
+    });
+
+  common(command.command('bootstrap-local')
+    .description('Safely initialize and optionally register a trusted non-Git local project directory')
+    .argument('<path>', 'Absolute local project path')
+    .option('--name <display-name>', 'Display name')
+    .option('--default-branch <branch>', 'Default branch when Git is initialized')
+    .option('--mode <mode>', 'Bootstrap mode: init_git_only, init_git_and_register, replace_registration')
+    .option('--replace-registered-repo-id <repo-id>', 'Reuse an existing repoId when replacing a stale registration')
+    .requiredOption('--confirm-authorization', 'Required confirmation for local project bootstrap'))
+    .action((path: string, opts: {
+      controllerHome?: string;
+      name?: string;
+      defaultBranch?: string;
+      mode?: 'init_git_only' | 'init_git_and_register' | 'replace_registration';
+      replaceRegisteredRepoId?: string;
+      confirmAuthorization?: boolean;
+      json?: boolean;
+    }) => {
+      output(bootstrapLocalProject({
+        path,
+        controllerHome: opts.controllerHome,
+        displayName: opts.name,
+        defaultBranch: opts.defaultBranch,
+        mode: opts.mode,
+        replaceRegisteredRepoId: opts.replaceRegisteredRepoId,
+        confirmAuthorization: opts.confirmAuthorization === true,
+      }), opts.json === true);
+    });
+
+  common(command.command('list').description('List registered repositories')
+    .option('--all', 'Include removed audit records'))
+    .action((opts: { controllerHome?: string; all?: boolean; json?: boolean }) => {
+      const repositories = listRepositories(opts.controllerHome, { includeRemoved: opts.all === true });
+      output({ repositories: repositories.map(repositorySummary), focus: getRepositoryFocus(opts.controllerHome) }, opts.json === true);
+    });
+
+  common(command.command('inspect').description('Inspect one repository')
+    .argument('<repo-id>', 'Stable repository ID'))
+    .action((repoId: string, opts: { controllerHome?: string; json?: boolean }) => {
+      output(getRepository(repoId, opts.controllerHome, { includeRemoved: true }), opts.json === true);
+    });
+
+  common(command.command('validate').description('Validate checkout identity, runtime storage, and legacy entities')
+    .argument('<repo-id>', 'Stable repository ID'))
+    .action((repoId: string, opts: { controllerHome?: string; json?: boolean }) => {
+      const repository = getRepository(repoId, opts.controllerHome, { includeRemoved: true });
+      output({ validation: validateRepository(repoId, opts.controllerHome), ...initializeRepository(repository, opts.controllerHome) }, opts.json === true);
+    });
+
+  common(command.command('command')
+    .description('Preview or confirm one repository-scoped local command with Git snapshots and audit evidence')
+    .argument('<repo-id>', 'Stable repository ID')
+    .requiredOption('--cmd <command>', 'Command to inspect or execute inside the selected repository')
+    .option('--checkout-id <checkout-id>', 'Select a registered checkout')
+    .option('--cwd <path>', 'Repository-relative working directory', '.')
+    .option('--confirm-token <token>', 'Confirm the exact plan returned by the latest preview')
+    .option('--dry-run', 'Classify and preview without executing')
+    .option('--timeout-ms <milliseconds>', 'Execution timeout', (value) => Number.parseInt(value, 10))
+    .option('--max-output-bytes <bytes>', 'Maximum captured output', (value) => Number.parseInt(value, 10)))
+    .action((repoId: string, opts: {
+      controllerHome?: string;
+      checkoutId?: string;
+      cmd: string;
+      cwd?: string;
+      confirmToken?: string;
+      dryRun?: boolean;
+      timeoutMs?: number;
+      maxOutputBytes?: number;
+      json?: boolean;
+    }) => {
+      const repository = resolveRepositorySelection({
+        repoId,
+        checkoutId: opts.checkoutId,
+        controllerHome: opts.controllerHome,
+        allowSoleRepository: false,
+      });
+      const result = withControllerLock(
+        opts.controllerHome ?? '',
+        { scope: 'repository', repoId: repository.repoId },
+        'cli:repo-command',
+        () => executeRepositoryCommand(opts.controllerHome ?? '', repository, {
+          command: opts.cmd,
+          cwd: opts.cwd,
+          authorization: opts.confirmToken ? 'confirmed_plan' : undefined,
+          approvalToken: opts.confirmToken,
+          dryRun: opts.dryRun === true,
+          timeoutMs: opts.timeoutMs,
+          maxOutputBytes: opts.maxOutputBytes,
+        }),
+        Math.min(Math.max(Math.trunc(opts.timeoutMs ?? 120000) + 30000, 60000), 960000),
+      );
+      output(result, opts.json === true);
+      if (result.status === 'approval_required') process.exitCode = 3;
+      else if (result.status === 'executed' && result.ok === false) process.exitCode = 1;
+    });
+
+  common(command.command('update').description('Update repository metadata')
+    .argument('<repo-id>', 'Stable repository ID')
+    .option('--name <display-name>', 'Display name')
+    .option('--default-branch <branch>', 'Default branch')
+    .option('--enable', 'Enable repository'))
+    .action((repoId: string, opts: { controllerHome?: string; name?: string; defaultBranch?: string; enable?: boolean; json?: boolean }) => {
+      output(updateRepository(repoId, { displayName: opts.name, defaultBranch: opts.defaultBranch, enabled: opts.enable === true ? true : undefined }, opts.controllerHome), opts.json === true);
+    });
+
+  common(command.command('refresh').description('Refresh Git, remote metadata, runtime storage, and legacy ownership')
+    .argument('<repo-id>', 'Stable repository ID'))
+    .action((repoId: string, opts: { controllerHome?: string; json?: boolean }) => {
+      const repository = refreshRepository(repoId, opts.controllerHome);
+      output(initializeRepository(repository, opts.controllerHome), opts.json === true);
+    });
+
+  common(command.command('disable').description('Disable new execution while retaining history')
+    .argument('<repo-id>', 'Stable repository ID'))
+    .action((repoId: string, opts: { controllerHome?: string; json?: boolean }) => output(disableRepository(repoId, opts.controllerHome), opts.json === true));
+
+  common(command.command('remove').description('Soft-remove a repository while retaining Controller audit state')
+    .argument('<repo-id>', 'Stable repository ID'))
+    .action((repoId: string, opts: { controllerHome?: string; json?: boolean }) => output(removeRepository(repoId, opts.controllerHome), opts.json === true));
+
+  common(command.command('focus').description('Set an interactive UI preference; never used as an execution security boundary')
+    .argument('[repo-id]', 'Stable repository ID; omit to clear focus'))
+    .action((repoId: string | undefined, opts: { controllerHome?: string; json?: boolean }) => output(focusRepository(repoId, opts.controllerHome), opts.json === true));
+
+  common(command.command('workbench').description('Show global or repository-scoped Workbench state')
+    .option('--repo-id <repo-id>', 'Filter to one repository')
+    .option('--all', 'Include disabled and removed audit records'))
+    .action((opts: { controllerHome?: string; repoId?: string; all?: boolean; json?: boolean }) => {
+      output(buildControllerWorkbench(opts.controllerHome ?? '', { repoId: opts.repoId, includeRemoved: opts.all === true }), opts.json === true);
+    });
+
+  const umbrella = command.command('umbrella').description('Coordinate a multi-repository work item while keeping every executable Task repository-local');
+  common(umbrella.command('list')).action((opts: { controllerHome?: string; json?: boolean }) => output(listUmbrellaIssues(opts.controllerHome), opts.json === true));
+  common(umbrella.command('inspect').argument('<umbrella-id>')).action((id: string, opts: { controllerHome?: string; json?: boolean }) => output(getUmbrellaIssue(id, opts.controllerHome), opts.json === true));
+  common(umbrella.command('create')
+    .argument('<umbrella-id>')
+    .requiredOption('--title <title>')
+    .option('--summary <summary>')
+    .requiredOption('--task <repoId:taskId:title...>', 'Repeat for each repository task', (value, previous: string[]) => [...previous, value], []))
+    .action((id: string, opts: { controllerHome?: string; title: string; summary?: string; task: string[]; json?: boolean }) => {
+      const tasks = opts.task.map((value) => {
+        const [repoId, taskId, ...title] = value.split(':');
+        if (!repoId || !taskId || title.length === 0) throw new Error(`invalid --task value: ${value}`);
+        return { repoId, taskId, title: title.join(':') };
+      });
+      output(createUmbrellaIssue({ controllerHome: opts.controllerHome, umbrellaId: id, title: opts.title, summary: opts.summary, tasks }), opts.json === true);
+    });
+  common(umbrella.command('update-task')
+    .argument('<umbrella-id>')
+    .requiredOption('--repo-id <repo-id>')
+    .requiredOption('--task-id <task-id>')
+    .requiredOption('--status <status>')
+    .option('--run-id <run-id>')
+    .option('--commit <sha>')
+    .option('--rollback-ref <ref>')
+    .option('--error <message>'))
+    .action((id: string, opts: { controllerHome?: string; repoId: string; taskId: string; status: any; runId?: string; commit?: string; rollbackRef?: string; error?: string; json?: boolean }) => {
+      output(updateUmbrellaTask({ controllerHome: opts.controllerHome, umbrellaId: id, repoId: opts.repoId, taskId: opts.taskId, status: opts.status, runId: opts.runId, commitSha: opts.commit, rollbackRef: opts.rollbackRef, error: opts.error }), opts.json === true);
+    });
+
+  return command;
+}

package/src/cli/commands/run.ts

@@ -0,0 +1,23 @@
+import { Command } from 'commander';
+import { listHelperIds, runHelper } from '../runtime/helper-runner';
+
+export function buildRunCommand(): Command {
+  const run = new Command('run')
+    .description('Run a bundled forge workflow helper')
+    .allowUnknownOption(true);
+
+  run
+    .argument('<helper>', 'Helper id, for example check-task-workflow')
+    .argument('[args...]', 'Arguments passed to the helper')
+    .action((helper: string, args: string[]) => {
+      const result = runHelper({ helper, args });
+      if (result.stderr && result.reason !== 'ok') {
+        console.error(result.stderr);
+        const helpers = listHelperIds();
+        if (helpers.length > 0) console.error(`known helpers: ${helpers.join(', ')}`);
+      }
+      process.exit(result.exitCode);
+    });
+
+  return run;
+}

package/src/cli/commands/runtime.ts

@@ -0,0 +1,191 @@
+import { Command } from 'commander';
+import { existsSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { resolveControllerHome } from '../repositories/controller-home';
+import { findExecutionJob, listActiveExecutionJobs, listExecutionJobs } from '../../runtime/execution/jobs/store';
+import { readJobEvents } from '../../runtime/evidence/event-ledger';
+import { getRepository, listRepositories } from '../repositories/registry';
+import { executeReadOnlyDiagnostic, isReadOnlyDiagnosticTool } from '../../runtime/diagnostics/read-only-tool';
+import { readRepositoryProjection } from '../../runtime/projections/materialized-view';
+import { listOccurrences, listSchedules } from '../../runtime/workflow/schedules/store';
+import { observeRuntimeStatus } from '../../runtime/root/status';
+import { readMcpServiceBearerToken } from '../mcp/auth';
+import { publishRuntimeRelease } from '../../runtime/root/release-store';
+import { installForgeRuntimeService } from '../../runtime/root/service';
+import { assertRuntimeReleaseFiles, stageRuntimeReleaseFromCandidateSource } from '../../runtime/root/release-materialize';
+
+function output(value: unknown, json = true): void {
+  console.log(json ? JSON.stringify(value, null, 2) : String(value));
+}
+
+export function buildRuntimeCommand(): Command {
+  const command = new Command('runtime').description('Inspect the canonical Runtime and durable execution state');
+
+  const service = command.command('service')
+    .description('Install the macOS launchd owner for the single Forge Runtime root process');
+
+  service.command('install')
+    .description('Build an immutable Runtime release and install the single launchd Runtime service owner')
+    .requiredOption('--controller-home <path>', 'Explicit Controller Home')
+    .requiredOption('--repo <path>', 'Repository root used as the immutable release source')
+    .option('--host <host>', 'MCP listener host', '127.0.0.1')
+    .option('--port <port>', 'MCP listener port', '8765')
+    .option('--stage-only', 'Build and validate the immutable Runtime release without publishing or activating it')
+    .option('--auth-token-file <path>', 'Raw bearer token file (defaults to controllerHome/mcp/runtime-token, created from the MCP bearer token when missing)')
+    .option('--exclusive-work-id <id>', 'Persistently admit only this P0 Work while migration is active')
+    .option('--node-executable <path>', 'Executable launchd uses to run the Forge Runtime service runner', process.execPath)
+    .option('--runner-path <path>', 'Forge Runtime service runner entry', join(resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..'), 'bin', 'forge-runtime-service.mjs'))
+    .action(async (opts: {
+      controllerHome: string;
+      repo: string;
+      host: string;
+      port: string;
+      authTokenFile?: string;
+      exclusiveWorkId?: string;
+      nodeExecutable: string;
+      runnerPath: string;
+      stageOnly?: boolean;
+    }) => {
+      const home = resolveControllerHome(opts.controllerHome);
+      const repoRoot = resolve(opts.repo);
+      if (!existsSync(repoRoot)) throw new Error(`RUNTIME_SERVICE_REPOSITORY_MISSING: ${repoRoot}`);
+      const port = Number(opts.port);
+      if (!Number.isInteger(port) || port < 1 || port > 65_535) throw new Error('RUNTIME_SERVICE_PORT_INVALID');
+
+      const staged = stageRuntimeReleaseFromCandidateSource({ controllerHome: home, sourceRoot: repoRoot });
+      assertRuntimeReleaseFiles(staged);
+      if (opts.stageOnly === true) {
+        output({
+          status: 'staged',
+          release: {
+            releaseId: staged.releaseId,
+            sourceCommit: staged.sourceCommit,
+            artifactIdentity: staged.artifactIdentity,
+            manifestPath: staged.manifestPath,
+            manifestSha256: staged.manifestSha256,
+          },
+          next: `forge recovery activate-runtime --controller-home ${home} --release-manifest ${staged.manifestPath}`,
+        });
+        return;
+      }
+
+      const tokenPath = resolve(opts.authTokenFile ?? join(home, 'mcp', 'runtime-token'));
+      if (!existsSync(tokenPath)) {
+        const token = readMcpServiceBearerToken(home, repoRoot);
+        if (!token) throw new Error('RUNTIME_SERVICE_AUTH_TOKEN_UNAVAILABLE: run forge mcp setup chatgpt first');
+        writeFileSync(tokenPath, `${token}\n`, { mode: 0o600 });
+      }
+
+      const authority = publishRuntimeRelease(home, staged.manifestPath, `runtime-service-install-${Date.now()}`);
+      const paths = await installForgeRuntimeService({
+        config: {
+          schemaVersion: 1,
+          controllerHome: home,
+          repositoryRoot: repoRoot,
+          host: opts.host,
+          port,
+          authTokenFile: tokenPath,
+          ...(opts.exclusiveWorkId?.trim() ? { exclusiveWorkId: opts.exclusiveWorkId.trim() } : {}),
+        },
+        runnerPath: resolve(opts.runnerPath),
+        nodeExecutable: resolve(opts.nodeExecutable),
+      });
+      output({
+        status: 'installed',
+        release: {
+          releaseId: staged.releaseId,
+          sourceCommit: staged.sourceCommit,
+          artifactIdentity: staged.artifactIdentity,
+          manifestPath: staged.manifestPath,
+          manifestSha256: staged.manifestSha256,
+          authorityRevision: authority.revision,
+        },
+        service: {
+          label: paths.label,
+          plist: paths.installedPlistPath,
+          config: paths.configPath,
+        },
+        next: `forge runtime status --controller-home ${home}`,
+      });
+    });
+
+  command.command('status')
+    .description('Read the Runtime Root status projection, active durable Jobs, and materialized repository projections')
+    .requiredOption('--controller-home <path>', 'Explicit Controller Home')
+    .option('--json', 'Output JSON')
+    .action((opts: { controllerHome: string; json?: boolean }) => {
+      const home = resolveControllerHome(opts.controllerHome);
+      const runtime = observeRuntimeStatus(home);
+      const repositories = listRepositories(home, { includeRemoved: true });
+      const value = {
+        runtime,
+        activeJobs: listActiveExecutionJobs(home),
+        repositories: repositories.map((repository) => readRepositoryProjection(home, repository.repoId)),
+      };
+      if (opts.json) return output(value);
+      console.log([
+        `runtime: ${runtime.running ? 'running' : 'not running'}`,
+        `ready: ${String(runtime.ready)}`,
+        `instance: ${runtime.snapshot?.runtimeInstanceId ?? 'none'}`,
+        `release: ${runtime.snapshot?.releaseId ?? 'none'}`,
+        `reasons: ${runtime.reasonCodes.join(', ') || 'none'}`,
+      ].join('\n'));
+    });
+
+  command.command('job')
+    .description('Inspect one durable Execution Job and its event ledger')
+    .argument('<job-id>', 'Execution Job ID')
+    .option('--controller-home <path>', 'Controller state root')
+    .action((jobId: string, opts: { controllerHome?: string }) => {
+      const home = resolveControllerHome(opts.controllerHome);
+      const job = findExecutionJob(home, jobId);
+      if (!job) throw new Error(`JOB_NOT_FOUND: ${jobId}`);
+      output({ job, events: readJobEvents(home, job.repoId, job.jobId) });
+    });
+
+  command.command('jobs')
+    .description('List durable Execution Jobs')
+    .option('--controller-home <path>', 'Controller state root')
+    .option('--repo-id <id>', 'Repository id')
+    .option('--limit <count>', 'Maximum records', '100')
+    .action((opts: { controllerHome?: string; repoId?: string; limit?: string }) => {
+      const home = resolveControllerHome(opts.controllerHome);
+      if (opts.repoId) return output({ jobs: listExecutionJobs(home, opts.repoId, Number(opts.limit ?? 100)) });
+      output({ jobs: listActiveExecutionJobs(home) });
+    });
+
+  command.command('diagnostic-read', { hidden: true })
+    .description('Internal isolated read-only diagnostic process entry')
+    .requiredOption('--controller-home <path>', 'Controller state root')
+    .requiredOption('--repo-id <id>', 'Repository id')
+    .requiredOption('--tool <name>', 'Read-only diagnostic tool name')
+    .requiredOption('--args-base64 <payload>', 'Base64url JSON arguments')
+    .action(async (opts: { controllerHome: string; repoId: string; tool: string; argsBase64: string }) => {
+      const home = resolveControllerHome(opts.controllerHome);
+      const repository = getRepository(opts.repoId, home);
+      if (!repository) throw new Error(`REPOSITORY_NOT_FOUND: ${opts.repoId}`);
+      if (!isReadOnlyDiagnosticTool(opts.tool)) throw new Error(`DIAGNOSTIC_TOOL_UNSUPPORTED: ${opts.tool}`);
+      let args: Record<string, unknown>;
+      try {
+        const decoded = JSON.parse(Buffer.from(opts.argsBase64, 'base64url').toString('utf8')) as unknown;
+        if (!decoded || typeof decoded !== 'object' || Array.isArray(decoded)) throw new Error('arguments must be a JSON object');
+        args = decoded as Record<string, unknown>;
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`DIAGNOSTIC_ARGUMENTS_INVALID: ${detail}`);
+      }
+      process.stdout.write(JSON.stringify(await executeReadOnlyDiagnostic(opts.tool, home, repository, args)));
+    });
+
+  command.command('schedules')
+    .description('List bounded Schedules and Occurrences')
+    .requiredOption('--repo-id <id>', 'Repository id')
+    .option('--controller-home <path>', 'Controller state root')
+    .action((opts: { controllerHome?: string; repoId: string }) => {
+      const home = resolveControllerHome(opts.controllerHome);
+      output({ schedules: listSchedules(home, opts.repoId), occurrences: listOccurrences(home, opts.repoId, undefined, 100) });
+    });
+
+  return command;
+}