@moretea-labs/forge 1.5.0-rc.1

package/src/cli/repositories/types.ts

@@ -0,0 +1,155 @@
+export type RepositoryType = 'git' | 'bare' | 'local-git' | 'unknown';
+export type RepositoryStateStorageStrategy = 'controller-home' | 'repository-local' | 'hybrid';
+export type RepositoryCheckoutLifecycle = 'active' | 'removed' | 'archived';
+export type LocalProjectBootstrapMode = 'init_git_only' | 'init_git_and_register' | 'replace_registration';
+
+export interface GitHubRepositoryMapping {
+  owner: string;
+  repo: string;
+  repository?: string;
+  projectOwner?: string;
+  projectNumber?: number;
+  statusField?: string;
+  labels?: string[];
+  pluginEnabled?: boolean;
+  syncMode?: 'manual' | 'checkpoint';
+  includeTasks?: boolean;
+  issueSyncEnabled?: boolean;
+  cloudAgentSupported?: boolean;
+  authenticationCapability?: 'unknown' | 'available' | 'unavailable';
+}
+
+export interface RepositoryCheckout {
+  checkoutId: string;
+  localRoot: string;
+  canonicalRoot: string;
+  worktree: boolean;
+  branch: string | null;
+  createdAt: string;
+  updatedAt: string;
+  lastSeenAt: string;
+  /** Missing on legacy records and interpreted as active. */
+  lifecycle?: RepositoryCheckoutLifecycle;
+  removedAt?: string;
+  archivedAt?: string;
+  lifecycleReason?: string;
+}
+
+export interface RepositoryRecord {
+  schemaVersion: 1;
+  repoId: string;
+  displayName: string;
+  localRoot: string;
+  canonicalRoot: string;
+  activeCheckoutId: string;
+  checkouts: RepositoryCheckout[];
+  remoteUrl?: string;
+  canonicalRemote?: string;
+  github?: GitHubRepositoryMapping;
+  defaultBranch?: string;
+  repositoryType: RepositoryType;
+  enabled: boolean;
+  createdAt: string;
+  updatedAt: string;
+  lastSeenAt: string;
+  configurationPath: string;
+  stateStorageStrategy: RepositoryStateStorageStrategy;
+  disabledAt?: string;
+  removedAt?: string;
+}
+
+export interface RepositoryRegistry {
+  schemaVersion: 1;
+  repositories: RepositoryRecord[];
+  updatedAt: string;
+}
+
+export interface RepositorySummary {
+  repoId: string;
+  displayName: string;
+  enabled: boolean;
+  localRoot: string;
+  canonicalRoot: string;
+  checkoutId: string;
+  remoteUrl?: string;
+  github?: GitHubRepositoryMapping;
+  defaultBranch?: string;
+  repositoryType: RepositoryType;
+  lastSeenAt: string;
+  removedAt?: string;
+}
+
+export interface RepositoryValidation {
+  repoId: string;
+  checkoutId: string;
+  ok: boolean;
+  rootExists: boolean;
+  gitRepository: boolean;
+  identityMatches: boolean;
+  canonicalRoot: string;
+  canonicalRemote?: string;
+  registryCanonicalRemote?: string;
+  githubRemoteRepository?: string;
+  githubMappingMatches?: boolean;
+  errors: string[];
+  warnings: string[];
+  checkedAt: string;
+}
+
+export interface EntityMigrationReport {
+  repoId: string;
+  checkoutId: string;
+  scanned: number;
+  updated: number;
+  unresolved: number;
+  files: string[];
+  errors: Array<{ path: string; error: string }>;
+}
+
+export interface LocalProjectCandidate {
+  path: string;
+  canonicalPath?: string;
+  name: string;
+  family: string;
+  exists: boolean;
+  hasGit: boolean;
+  markerKinds: string[];
+  markerPaths: string[];
+  visibleEntryCount: number;
+  fileCount: number;
+  recentActivityAt?: string;
+  stale: boolean;
+  staleReasons: string[];
+  score: number;
+  repoId?: string;
+  displayName?: string;
+  recommended: boolean;
+}
+
+export interface LocalProjectLatestSourceDiagnosis {
+  inputPath: string;
+  family: string;
+  repoId?: string;
+  noMutation: true;
+  candidates: LocalProjectCandidate[];
+  recommendedPath?: string;
+  recommendedRepoId?: string;
+  warnings: string[];
+}
+
+export interface LocalProjectBootstrapResult {
+  path: string;
+  mode: LocalProjectBootstrapMode;
+  createdGit: boolean;
+  createdGitignore: boolean;
+  idempotent: boolean;
+  markers: string[];
+  markerPaths: string[];
+  repository?: RepositoryRecord;
+  replacedRegistration?: {
+    repoId: string;
+    previousCanonicalRoot: string;
+    previousCheckoutId: string;
+  };
+  next: string;
+}

package/src/cli/repositories/umbrella.ts

@@ -0,0 +1,134 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { ensureControllerHome } from './controller-home';
+import { getRepository } from './registry';
+
+export type UmbrellaTaskStatus = 'planned' | 'running' | 'succeeded' | 'failed' | 'blocked' | 'cancelled';
+
+export interface UmbrellaRepositoryTask {
+  taskId: string;
+  repoId: string;
+  issueId?: string;
+  title: string;
+  status: UmbrellaTaskStatus;
+  runIds: string[];
+  commitSha?: string;
+  rollbackRef?: string;
+  error?: string;
+  updatedAt: string;
+}
+
+export interface UmbrellaIssue {
+  schemaVersion: 1;
+  umbrellaId: string;
+  title: string;
+  summary: string;
+  status: 'planned' | 'running' | 'partial' | 'failed' | 'done' | 'cancelled';
+  tasks: UmbrellaRepositoryTask[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+function root(controllerHome?: string): string {
+  return join(ensureControllerHome(controllerHome), 'umbrella-issues');
+}
+
+function pathFor(controllerHome: string | undefined, umbrellaId: string): string {
+  return join(root(controllerHome), `${umbrellaId.replace(/[^a-zA-Z0-9._-]+/g, '-')}.json`);
+}
+
+function atomicJson(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+  renameSync(temp, path);
+}
+
+function deriveStatus(tasks: UmbrellaRepositoryTask[]): UmbrellaIssue['status'] {
+  if (tasks.every((task) => task.status === 'cancelled')) return 'cancelled';
+  if (tasks.every((task) => task.status === 'succeeded')) return 'done';
+  if (tasks.some((task) => task.status === 'failed') && tasks.some((task) => task.status === 'succeeded')) return 'partial';
+  if (tasks.some((task) => task.status === 'failed')) return 'failed';
+  if (tasks.some((task) => task.status === 'running')) return 'running';
+  if (tasks.some((task) => task.status === 'blocked')) return 'partial';
+  return 'planned';
+}
+
+export function createUmbrellaIssue(input: {
+  controllerHome?: string;
+  umbrellaId: string;
+  title: string;
+  summary?: string;
+  tasks: Array<{ taskId: string; repoId: string; title: string; issueId?: string }>;
+}): UmbrellaIssue {
+  if (input.tasks.length < 2) throw new Error('UMBRELLA_REQUIRES_MULTIPLE_REPOSITORIES');
+  const repoIds = new Set(input.tasks.map((task) => task.repoId));
+  if (repoIds.size < 2) throw new Error('UMBRELLA_REQUIRES_MULTIPLE_REPOSITORIES');
+  for (const repoId of repoIds) getRepository(repoId, input.controllerHome);
+  const path = pathFor(input.controllerHome, input.umbrellaId);
+  if (existsSync(path)) throw new Error(`umbrella issue already exists: ${input.umbrellaId}`);
+  const timestamp = new Date().toISOString();
+  const issue: UmbrellaIssue = {
+    schemaVersion: 1,
+    umbrellaId: input.umbrellaId,
+    title: input.title,
+    summary: input.summary ?? '',
+    status: 'planned',
+    tasks: input.tasks.map((task) => ({
+      ...task,
+      status: 'planned',
+      runIds: [],
+      updatedAt: timestamp,
+    })),
+    createdAt: timestamp,
+    updatedAt: timestamp,
+  };
+  atomicJson(path, issue);
+  return issue;
+}
+
+export function getUmbrellaIssue(umbrellaId: string, controllerHome?: string): UmbrellaIssue {
+  const path = pathFor(controllerHome, umbrellaId);
+  if (!existsSync(path)) throw new Error(`umbrella issue not found: ${umbrellaId}`);
+  return JSON.parse(readFileSync(path, 'utf-8')) as UmbrellaIssue;
+}
+
+export function listUmbrellaIssues(controllerHome?: string): UmbrellaIssue[] {
+  const directory = root(controllerHome);
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+    .map((entry) => getUmbrellaIssue(entry.name.slice(0, -5), controllerHome))
+    .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
+export function updateUmbrellaTask(input: {
+  controllerHome?: string;
+  umbrellaId: string;
+  taskId: string;
+  repoId: string;
+  status: UmbrellaTaskStatus;
+  runId?: string;
+  commitSha?: string;
+  rollbackRef?: string;
+  error?: string;
+}): UmbrellaIssue {
+  const issue = getUmbrellaIssue(input.umbrellaId, input.controllerHome);
+  const index = issue.tasks.findIndex((task) => task.taskId === input.taskId && task.repoId === input.repoId);
+  if (index < 0) throw new Error(`umbrella task not found: ${input.repoId}/${input.taskId}`);
+  const timestamp = new Date().toISOString();
+  const previous = issue.tasks[index];
+  issue.tasks[index] = {
+    ...previous,
+    status: input.status,
+    runIds: input.runId && !previous.runIds.includes(input.runId) ? [...previous.runIds, input.runId] : previous.runIds,
+    commitSha: input.commitSha ?? previous.commitSha,
+    rollbackRef: input.rollbackRef ?? previous.rollbackRef,
+    error: input.error,
+    updatedAt: timestamp,
+  };
+  issue.status = deriveStatus(issue.tasks);
+  issue.updatedAt = timestamp;
+  atomicJson(pathFor(input.controllerHome, input.umbrellaId), issue);
+  return issue;
+}

package/src/cli/repositories/workbench.ts

@@ -0,0 +1,140 @@
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { getRepositoryFocus, listRepositories, repositorySummary, validateRepository } from './registry';
+import { ensureRepositoryRuntimeStorage } from './runtime-storage';
+import type { RepositoryRecord } from './types';
+
+export interface WorkbenchRunSummary {
+  repoId: string;
+  checkoutId: string;
+  runId: string;
+  issueId?: string;
+  taskId?: string;
+  status?: string;
+  executionMode?: string;
+  repoRoot: string;
+  executionRoot?: string;
+  worktreePath?: string;
+  branch?: string | null;
+  baseRevision?: string | null;
+  updatedAt?: string;
+}
+
+function readJson(path: string): Record<string, unknown> | undefined {
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8')) as Record<string, unknown>;
+  } catch (_error) {
+    return undefined;
+  }
+}
+
+function listIssues(root: string): Record<string, unknown>[] {
+  const result: Record<string, unknown>[] = [];
+  for (const directory of [join(root, 'tasks', 'issues'), join(root, '.ai', 'harness', 'ephemeral-issues')]) {
+    if (!existsSync(directory)) continue;
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith('.issue.json')) continue;
+      const issue = readJson(join(directory, entry.name));
+      if (issue) result.push(issue);
+    }
+  }
+  return result;
+}
+
+function listRuns(record: RepositoryRecord): WorkbenchRunSummary[] {
+  const root = join(record.canonicalRoot, '.ai', 'harness', 'jobs');
+  if (!existsSync(root)) return [];
+  const result: WorkbenchRunSummary[] = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const meta = readJson(join(root, entry.name, 'meta.json'));
+    if (!meta) continue;
+    result.push({
+      repoId: typeof meta.repoId === 'string' ? meta.repoId : record.repoId,
+      checkoutId: typeof meta.checkoutId === 'string' ? meta.checkoutId : record.activeCheckoutId,
+      runId: typeof meta.runId === 'string' ? meta.runId : entry.name,
+      issueId: typeof meta.issueId === 'string' ? meta.issueId : undefined,
+      taskId: typeof meta.taskId === 'string' ? meta.taskId : undefined,
+      status: typeof meta.status === 'string' ? meta.status : undefined,
+      executionMode: typeof meta.executionMode === 'string' ? meta.executionMode : undefined,
+      repoRoot: typeof meta.repoRoot === 'string' ? meta.repoRoot : record.canonicalRoot,
+      executionRoot: typeof meta.executionRoot === 'string' ? meta.executionRoot : undefined,
+      worktreePath: typeof meta.worktreePath === 'string'
+        ? meta.worktreePath
+        : typeof meta.worktree === 'string' ? meta.worktree : undefined,
+      branch: typeof meta.branch === 'string' || meta.branch === null ? meta.branch as string | null : undefined,
+      baseRevision: typeof meta.baseRevision === 'string' || meta.baseRevision === null
+        ? meta.baseRevision as string | null
+        : undefined,
+      updatedAt: typeof meta.finishedAt === 'string'
+        ? meta.finishedAt
+        : typeof meta.startedAt === 'string'
+          ? meta.startedAt
+          : typeof meta.createdAt === 'string' ? meta.createdAt : undefined,
+    });
+  }
+  return result.sort((a, b) => String(b.updatedAt ?? '').localeCompare(String(a.updatedAt ?? '')));
+}
+
+function countWorklog(root: string): number {
+  for (const path of [
+    join(root, '.ai', 'harness', 'controller', 'worklog.jsonl'),
+    join(root, '.ai', 'harness', 'worklog.jsonl'),
+  ]) {
+    if (!existsSync(path)) continue;
+    try {
+      return readFileSync(path, 'utf-8').split(/\r?\n/).filter((line) => line.trim()).length;
+    } catch (_error) {
+      return 0;
+    }
+  }
+  return 0;
+}
+
+export function buildControllerWorkbench(
+  controllerHome: string,
+  options: { repoId?: string; includeRemoved?: boolean } = {},
+) {
+  const records = listRepositories(controllerHome, { includeRemoved: options.includeRemoved === true })
+    .filter((record) => !options.repoId || record.repoId === options.repoId);
+  if (options.repoId && records.length === 0) throw new Error(`repository not found: ${options.repoId}`);
+  const repositories = records.map((record) => {
+    const runtimeStorage = ensureRepositoryRuntimeStorage(record, controllerHome);
+    const issues = listIssues(record.canonicalRoot);
+    const runs = listRuns(record);
+    const activeRuns = runs.filter((run) => ['queued', 'running', 'waiting_for_user'].includes(run.status ?? ''));
+    return {
+      repository: repositorySummary(record),
+      health: validateRepository(record.repoId, controllerHome),
+      runtimeStorage,
+      counts: {
+        issues: issues.length,
+        tasks: issues.reduce((total, issue) => total + (Array.isArray(issue.tasks) ? issue.tasks.length : 0), 0),
+        runs: runs.length,
+        activeRuns: activeRuns.length,
+        worklogEvents: countWorklog(record.canonicalRoot),
+      },
+      activeRuns,
+    };
+  });
+  const activeRuns = repositories.flatMap((entry) => entry.activeRuns)
+    .sort((a, b) => String(b.updatedAt ?? '').localeCompare(String(a.updatedAt ?? '')));
+  return {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    mode: options.repoId ? 'repository' : 'global',
+    selectedRepoId: options.repoId,
+    focusRepoId: getRepositoryFocus(controllerHome).repoId,
+    repositories,
+    activeRuns,
+    totals: repositories.reduce((total, entry) => ({
+      repositories: total.repositories + 1,
+      enabledRepositories: total.enabledRepositories + (entry.repository.enabled ? 1 : 0),
+      issues: total.issues + entry.counts.issues,
+      tasks: total.tasks + entry.counts.tasks,
+      runs: total.runs + entry.counts.runs,
+      activeRuns: total.activeRuns + entry.counts.activeRuns,
+      worklogEvents: total.worklogEvents + entry.counts.worklogEvents,
+    }), { repositories: 0, enabledRepositories: 0, issues: 0, tasks: 0, runs: 0, activeRuns: 0, worklogEvents: 0 }),
+  };
+}

package/src/cli/repositories/worktree-storage.ts

@@ -0,0 +1,137 @@
+import { createHash } from 'crypto';
+import { existsSync, mkdirSync, realpathSync } from 'fs';
+import { homedir } from 'os';
+import { basename, dirname, join, relative, resolve } from 'path';
+import { durableControllerHome } from './controller-home';
+import type { RepositoryRecord } from './types';
+
+export const MANAGED_WORKTREE_HOME_ENV = 'FORGE_WORKTREE_HOME';
+
+function comparablePath(value: string): string {
+  const resolved = resolve(value).replace(/\\/g, '/');
+  const normalized = process.platform === 'darwin' && resolved.startsWith('/var/')
+    ? `/private${resolved}`
+    : resolved;
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+/** Resolve symlinked existing ancestors even when the final path does not exist yet. */
+export function canonicalManagedPath(value: string): string {
+  let cursor = resolve(value);
+  const tail: string[] = [];
+  while (!existsSync(cursor)) {
+    const parent = dirname(cursor);
+    if (parent === cursor) break;
+    tail.unshift(basename(cursor));
+    cursor = parent;
+  }
+  let canonicalBase = cursor;
+  try { canonicalBase = realpathSync(cursor); } catch { /* resolved fallback */ }
+  return resolve(canonicalBase, ...tail);
+}
+
+export function managedPathInside(parent: string, candidate: string): boolean {
+  const rel = relative(comparablePath(canonicalManagedPath(parent)), comparablePath(canonicalManagedPath(candidate)));
+  return rel === '' || (!rel.startsWith('..') && !rel.startsWith('/') && !rel.startsWith('\\'));
+}
+
+export function registeredRepositoryRoots(records: RepositoryRecord[]): string[] {
+  const roots = new Set<string>();
+  for (const record of records) {
+    // A RepositoryRecord's canonical roots and non-worktree checkouts are source
+    // authorities that a Controller-owned storage root must never contain or
+    // live beneath. Git worktree checkouts are occupants of managed storage,
+    // not additional storage-boundary authorities; including them here makes
+    // the parent managed root reject itself after the first allocation.
+    const activeSourceCheckoutRoots = record.checkouts
+      .filter((checkout) => (
+        !checkout.worktree
+        && checkout.lifecycle !== 'removed'
+        && checkout.lifecycle !== 'archived'
+      ))
+      .flatMap((checkout) => [checkout.localRoot, checkout.canonicalRoot]);
+    for (const candidate of [record.localRoot, record.canonicalRoot, ...activeSourceCheckoutRoots]) {
+      if (!candidate?.trim()) continue;
+      roots.add(canonicalManagedPath(candidate));
+    }
+  }
+  return [...roots];
+}
+
+function overlapsRegisteredRoot(candidate: string, roots: string[]): string | undefined {
+  return roots.find((root) => managedPathInside(root, candidate) || managedPathInside(candidate, root));
+}
+
+function controllerNamespace(controllerHome: string): string {
+  return createHash('sha256')
+    .update(canonicalManagedPath(durableControllerHome(controllerHome)))
+    .digest('hex')
+    .slice(0, 16);
+}
+
+function globalWorktreeBase(env: NodeJS.ProcessEnv): string {
+  const xdg = env.XDG_STATE_HOME?.trim();
+  return xdg
+    ? join(xdg, 'forge', 'managed-worktrees')
+    : join(homedir(), '.forge', 'managed-worktrees');
+}
+
+/**
+ * Resolve a stable Controller-owned worktree root that is disjoint from every
+ * registered repository checkout. A repo-local self-host Controller Home is
+ * therefore never reused as the worktree parent.
+ */
+export function managedWorktreeStorageRoot(
+  controllerHome: string,
+  records: RepositoryRecord[],
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const roots = registeredRepositoryRoots(records);
+  const namespace = controllerNamespace(controllerHome);
+  const explicit = env[MANAGED_WORKTREE_HOME_ENV]?.trim();
+  const candidates = explicit
+    ? [join(resolve(explicit), namespace)]
+    : [
+      join(durableControllerHome(controllerHome), 'managed-worktrees'),
+      join(globalWorktreeBase(env), namespace),
+    ];
+
+  for (const raw of candidates) {
+    const candidate = canonicalManagedPath(raw);
+    const overlap = overlapsRegisteredRoot(candidate, roots);
+    if (overlap) {
+      if (explicit) {
+        throw new Error(`MANAGED_WORKTREE_HOME_OVERLAPS_REPOSITORY: ${candidate} overlaps ${overlap}`);
+      }
+      continue;
+    }
+    mkdirSync(candidate, { recursive: true });
+    return candidate;
+  }
+  throw new Error('MANAGED_WORKTREE_HOME_UNAVAILABLE: no stable path is disjoint from every registered repository root');
+}
+
+function safeSegment(value: string, fallback: string): string {
+  return value.trim().replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^[.-]+|[.-]+$/g, '').slice(0, 100) || fallback;
+}
+
+export function managedWorktreePath(
+  controllerHome: string,
+  repoId: string,
+  identity: string,
+  records: RepositoryRecord[],
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const storageRoot = managedWorktreeStorageRoot(controllerHome, records, env);
+  const candidate = canonicalManagedPath(join(
+    storageRoot,
+    safeSegment(repoId, 'repository'),
+    safeSegment(identity, 'worktree'),
+  ));
+  if (!managedPathInside(storageRoot, candidate)) {
+    throw new Error(`MANAGED_WORKTREE_PATH_ESCAPE: ${candidate}`);
+  }
+  const overlap = overlapsRegisteredRoot(candidate, registeredRepositoryRoots(records));
+  if (overlap) throw new Error(`MANAGED_WORKTREE_PATH_OVERLAPS_REPOSITORY: ${candidate} overlaps ${overlap}`);
+  return candidate;
+}