agentic-orchestrator 0.1.0

package/apps/control-plane/src/application/services/feature-deletion-service.ts

@@ -0,0 +1,459 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { nowIso, pathExists } from '../../core/fs.js';
+import { runGit } from '../../core/git.js';
+import { ERROR_CODES } from '../../core/error-codes.js';
+import { fail } from '../../core/response.js';
+import type { RuntimeSessionsSnapshot } from '../../core/runtime-sessions.js';
+
+type AnyRecord = Record<string, unknown>;
+type RemoveBranchMode = 'none' | 'safe' | 'force';
+
+interface DeleteOptions {
+  dryRun?: boolean;
+  confirm?: boolean;
+  removeWorktree?: boolean;
+  removeBranch?: string | null;
+}
+
+export interface FeatureDeleteSummary {
+  feature_dir_removed: boolean;
+  worktree_removed: boolean;
+  branch_removed: boolean;
+  index_updated: boolean;
+  locks_released: string[];
+  blocked_queue_entries_removed: number;
+  runtime_session_assignment_removed: boolean;
+}
+
+export interface FeatureDeletePlan {
+  feature_dir_exists: boolean;
+  feature_files: {
+    spec_md: boolean;
+    state_md: boolean;
+    plan_json: boolean;
+    qa_test_index_json: boolean;
+    decisions_md: boolean;
+    logs_dir: boolean;
+    evidence_dir: boolean;
+  };
+  index_membership: {
+    active: boolean;
+    blocked: boolean;
+    merged: boolean;
+  };
+  locks: {
+    state_held: string[];
+    index_held_resources: string[];
+  };
+  blocked_queue_entries: number;
+  runtime_session_assignment_exists: boolean;
+  worktree_exists: boolean;
+  branch_exists: boolean;
+  remove_worktree: boolean;
+  remove_branch: RemoveBranchMode;
+}
+
+export interface FeatureDeleteResult {
+  data: {
+    feature_id: string;
+    dry_run: boolean;
+    plan: FeatureDeletePlan;
+    applied?: FeatureDeleteSummary;
+    summary: FeatureDeleteSummary;
+  };
+}
+
+function normalizeSet(array: string[]): string[] {
+  return [...new Set(array)].sort((a, b) => a.localeCompare(b));
+}
+
+function asRecord(value: unknown): AnyRecord {
+  return value && typeof value === 'object' ? (value as AnyRecord) : {};
+}
+
+function asStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter((item): item is string => typeof item === 'string');
+}
+
+function isFeatureId(value: string): boolean {
+  return /^[a-z0-9_][a-z0-9_-]*$/.test(value);
+}
+
+function readBranchMode(value: string | null | undefined): RemoveBranchMode | null {
+  if (value == null || value.length === 0) {
+    return 'none';
+  }
+  if (value === 'none' || value === 'safe' || value === 'force') {
+    return value;
+  }
+  return null;
+}
+
+function readHeldLocksFromState(frontMatter: AnyRecord): string[] {
+  const locks = asRecord(frontMatter.locks);
+  return normalizeSet(asStringArray(locks.held));
+}
+
+function readLockResourcesFromIndex(index: AnyRecord, featureId: string): string[] {
+  const held: string[] = [];
+  const locks = asRecord(index.locks);
+  const lockLeases = asRecord(index.lock_leases);
+
+  for (const [resource, holder] of Object.entries(locks)) {
+    if (holder === featureId) {
+      held.push(resource);
+    }
+  }
+
+  for (const [resource, lease] of Object.entries(lockLeases)) {
+    const leaseRecord = asRecord(lease);
+    if (leaseRecord.holder === featureId) {
+      held.push(resource);
+    }
+  }
+
+  return normalizeSet(held);
+}
+
+function makeEmptySummary(): FeatureDeleteSummary {
+  return {
+    feature_dir_removed: false,
+    worktree_removed: false,
+    branch_removed: false,
+    index_updated: false,
+    locks_released: [],
+    blocked_queue_entries_removed: 0,
+    runtime_session_assignment_removed: false
+  };
+}
+
+function normalizeFeatureSessions(runtimeSessions: RuntimeSessionsSnapshot): Record<string, unknown> {
+  return runtimeSessions.feature_sessions && typeof runtimeSessions.feature_sessions === 'object'
+    ? (runtimeSessions.feature_sessions as unknown as Record<string, unknown>)
+    : {};
+}
+
+export interface FeatureDeletionServicePort {
+  getRepoRoot(): string;
+  featurePath(featureId: string): string;
+  worktreePath(featureId: string): string;
+  statePath(featureId: string): string;
+  readState(featureId: string): Promise<{ frontMatter: AnyRecord; body: string }>;
+  withIndexLock<T>(operation: () => Promise<T>): Promise<T>;
+  readIndex(): Promise<AnyRecord>;
+  writeIndex(index: AnyRecord): Promise<void>;
+  normalizeRuntimeSessions(value: unknown, at?: string): RuntimeSessionsSnapshot;
+  isRunLeaseFresh(runtimeSessions: RuntimeSessionsSnapshot): boolean;
+  locksRelease(resource: string, featureId: string): Promise<unknown>;
+}
+
+export class FeatureDeletionService {
+  private readonly port: FeatureDeletionServicePort;
+
+  constructor(port: FeatureDeletionServicePort) {
+    this.port = port;
+  }
+
+  async featureDelete(featureId: string | null, options: DeleteOptions = {}): Promise<FeatureDeleteResult> {
+    if (!featureId) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.INVALID_ARGUMENT, 'feature_id is required', {
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+    if (!isFeatureId(featureId)) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.INVALID_ARGUMENT, 'feature_id format is invalid', {
+          feature_id: featureId,
+          expected_pattern: '^[a-z0-9_][a-z0-9_-]*$',
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+
+    const branchMode = readBranchMode(options.removeBranch);
+    if (!branchMode) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.INVALID_ARGUMENT, 'remove_branch must be one of none|safe|force', {
+          remove_branch: options.removeBranch,
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+
+    const dryRun = options.dryRun ?? true;
+    const confirm = options.confirm ?? false;
+    const removeWorktree = options.removeWorktree ?? true;
+    if (!dryRun && !confirm) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.INVALID_ARGUMENT, 'confirm must be true when dry_run is false', {
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+
+    const featurePath = this.port.featurePath(featureId);
+    const statePath = this.port.statePath(featureId);
+    const worktreePath = this.port.worktreePath(featureId);
+    const repoRoot = this.port.getRepoRoot();
+    const featureFiles = {
+      spec_md: await pathExists(path.join(featurePath, 'spec.md')),
+      state_md: await pathExists(path.join(featurePath, 'state.md')),
+      plan_json: await pathExists(path.join(featurePath, 'plan.json')),
+      qa_test_index_json: await pathExists(path.join(featurePath, 'qa_test_index.json')),
+      decisions_md: await pathExists(path.join(featurePath, 'decisions.md')),
+      logs_dir: await pathExists(path.join(featurePath, 'logs')),
+      evidence_dir: await pathExists(path.join(featurePath, 'evidence'))
+    };
+    const featureDirExists = await pathExists(featurePath);
+    const worktreeExists = await pathExists(worktreePath);
+    const branchExists = await this.branchExists(repoRoot, featureId);
+
+    const stateFrontMatter = await this.loadStateFrontMatter(featureId, statePath);
+    const stateHeldLocks = readHeldLocksFromState(stateFrontMatter);
+
+    const indexSnapshot = await this.port.readIndex();
+    const runtimeSessions = this.port.normalizeRuntimeSessions(indexSnapshot.runtime_sessions);
+    if (this.hasFreshRunLease(runtimeSessions)) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.RUN_ALREADY_ACTIVE, 'Cannot delete feature while a run lease is active', {
+          active_run_id: runtimeSessions.run_id,
+          owner_instance_id: runtimeSessions.owner_instance_id,
+          lease_expires_at: runtimeSessions.lease_expires_at,
+          stale: false,
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+
+    const blockedQueueEntries = asStringArray(
+      asArray(indexSnapshot.blocked_queue).map((entry) => {
+        const record = asRecord(entry);
+        return typeof record.feature_id === 'string' && record.feature_id === featureId ? featureId : null;
+      })
+    ).length;
+
+    const indexMembership = {
+      active: asStringArray(indexSnapshot.active).includes(featureId),
+      blocked: asStringArray(indexSnapshot.blocked).includes(featureId),
+      merged: asStringArray(indexSnapshot.merged).includes(featureId)
+    };
+
+    const runtimeFeatureSessions = normalizeFeatureSessions(runtimeSessions);
+    const runtimeSessionAssignmentExists = Object.prototype.hasOwnProperty.call(
+      runtimeFeatureSessions,
+      featureId
+    );
+    const indexHeldLocks = readLockResourcesFromIndex(indexSnapshot, featureId);
+
+    const plan: FeatureDeletePlan = {
+      feature_dir_exists: featureDirExists,
+      feature_files: featureFiles,
+      index_membership: indexMembership,
+      locks: {
+        state_held: stateHeldLocks,
+        index_held_resources: indexHeldLocks
+      },
+      blocked_queue_entries: blockedQueueEntries,
+      runtime_session_assignment_exists: runtimeSessionAssignmentExists,
+      worktree_exists: worktreeExists,
+      branch_exists: branchExists,
+      remove_worktree: removeWorktree,
+      remove_branch: branchMode
+    };
+
+    const summary = makeEmptySummary();
+    if (dryRun) {
+      return {
+        data: {
+          feature_id: featureId,
+          dry_run: true,
+          plan,
+          summary
+        }
+      };
+    }
+
+    for (const resource of indexHeldLocks) {
+      await this.port.locksRelease(resource, featureId);
+      summary.locks_released.push(resource);
+    }
+    summary.locks_released = normalizeSet(summary.locks_released);
+
+    const indexUpdate = await this.port.withIndexLock(async () => {
+      const index = await this.port.readIndex();
+      let changed = false;
+      let blockedQueueRemoved = 0;
+      let runtimeSessionRemoved = false;
+
+      const active = asStringArray(index.active);
+      const nextActive = active.filter((item) => item !== featureId);
+      if (nextActive.length !== active.length) {
+        index.active = normalizeSet(nextActive);
+        changed = true;
+      }
+
+      const blocked = asStringArray(index.blocked);
+      const nextBlocked = blocked.filter((item) => item !== featureId);
+      if (nextBlocked.length !== blocked.length) {
+        index.blocked = normalizeSet(nextBlocked);
+        changed = true;
+      }
+
+      const merged = asStringArray(index.merged);
+      const nextMerged = merged.filter((item) => item !== featureId);
+      if (nextMerged.length !== merged.length) {
+        index.merged = normalizeSet(nextMerged);
+        changed = true;
+      }
+
+      const blockedQueue = asArray(index.blocked_queue);
+      const nextBlockedQueue = blockedQueue.filter((entry) => {
+        const record = asRecord(entry);
+        return record.feature_id !== featureId;
+      });
+      blockedQueueRemoved = blockedQueue.length - nextBlockedQueue.length;
+      if (blockedQueueRemoved > 0) {
+        index.blocked_queue = nextBlockedQueue;
+        changed = true;
+      }
+
+      const locks = asRecord(index.locks);
+      for (const [resource, holder] of Object.entries(locks)) {
+        if (holder === featureId) {
+          locks[resource] = null;
+          changed = true;
+        }
+      }
+      index.locks = locks;
+
+      const lockLeases = asRecord(index.lock_leases);
+      for (const [resource, lease] of Object.entries(lockLeases)) {
+        const leaseRecord = asRecord(lease);
+        if (leaseRecord.holder === featureId) {
+          lockLeases[resource] = null;
+          changed = true;
+        }
+      }
+      index.lock_leases = lockLeases;
+
+      const nextRuntimeSessions = this.port.normalizeRuntimeSessions(index.runtime_sessions);
+      const featureSessions = normalizeFeatureSessions(nextRuntimeSessions);
+      if (Object.prototype.hasOwnProperty.call(featureSessions, featureId)) {
+        delete featureSessions[featureId];
+        nextRuntimeSessions.feature_sessions = featureSessions as RuntimeSessionsSnapshot['feature_sessions'];
+        runtimeSessionRemoved = true;
+        changed = true;
+      }
+      index.runtime_sessions = nextRuntimeSessions;
+
+      if (changed) {
+        const version = typeof index.version === 'number' ? index.version : 0;
+        index.version = version + 1;
+        index.updated_at = nowIso();
+        await this.port.writeIndex(index);
+      }
+
+      return {
+        changed,
+        blockedQueueRemoved,
+        runtimeSessionRemoved
+      };
+    });
+
+    summary.index_updated = indexUpdate.changed;
+    summary.blocked_queue_entries_removed = indexUpdate.blockedQueueRemoved;
+    summary.runtime_session_assignment_removed = indexUpdate.runtimeSessionRemoved;
+
+    if (featureDirExists) {
+      await fs.rm(featurePath, { recursive: true, force: true });
+      summary.feature_dir_removed = true;
+    }
+
+    if (removeWorktree && worktreeExists) {
+      const removeWorktreeResult = await runGit(repoRoot, ['worktree', 'remove', '--force', worktreePath]);
+      if (removeWorktreeResult.code !== 0) {
+        throw {
+          normalizedResponse: fail(ERROR_CODES.GIT_FAILURE, 'Failed to remove feature worktree', {
+            feature_id: featureId,
+            stderr: removeWorktreeResult.stderr,
+            retryable: false,
+            requires_human: true
+          }, {
+            command: ['git', 'worktree', 'remove', '--force', worktreePath],
+            exit_code: removeWorktreeResult.code
+          })
+        };
+      }
+      summary.worktree_removed = true;
+    }
+
+    if (branchMode !== 'none' && branchExists) {
+      const args = branchMode === 'safe' ? ['branch', '-d', featureId] : ['branch', '-D', featureId];
+      const removeBranchResult = await runGit(repoRoot, args);
+      if (removeBranchResult.code !== 0) {
+        throw {
+          normalizedResponse: fail(ERROR_CODES.GIT_FAILURE, 'Failed to remove feature branch', {
+            feature_id: featureId,
+            remove_branch: branchMode,
+            stderr: removeBranchResult.stderr,
+            retryable: false,
+            requires_human: true
+          }, {
+            command: ['git', ...args],
+            exit_code: removeBranchResult.code
+          })
+        };
+      }
+      summary.branch_removed = true;
+    }
+
+    return {
+      data: {
+        feature_id: featureId,
+        dry_run: false,
+        plan,
+        applied: summary,
+        summary
+      }
+    };
+  }
+
+  private hasFreshRunLease(runtimeSessions: RuntimeSessionsSnapshot): boolean {
+    const hasLease =
+      runtimeSessions.run_id !== 'none' && runtimeSessions.owner_instance_id !== 'none';
+    return hasLease && this.port.isRunLeaseFresh(runtimeSessions);
+  }
+
+  private async loadStateFrontMatter(featureId: string, statePath: string): Promise<AnyRecord> {
+    if (!(await pathExists(statePath))) {
+      return {};
+    }
+
+    try {
+      const state = await this.port.readState(featureId);
+      return asRecord(state.frontMatter);
+    } catch {
+      return {};
+    }
+  }
+
+  private async branchExists(repoRoot: string, featureId: string): Promise<boolean> {
+    const branch = await runGit(repoRoot, ['show-ref', '--verify', `refs/heads/${featureId}`]);
+    return branch.code === 0;
+  }
+}
+
+function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}

package/apps/control-plane/src/application/services/feature-lifecycle-service.ts

@@ -0,0 +1,177 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { atomicWriteJson, nowIso, pathExists, stableHash } from '../../core/fs.js';
+import { fail } from '../../core/response.js';
+import { ERROR_CODES } from '../../core/error-codes.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyRecord = Record<string, any>;
+
+type FeatureContext = {
+  actorType: string;
+  actorId: string;
+};
+
+function normalizeSet(array: string[]): string[] {
+  return [...new Set(array)].sort((a, b) => a.localeCompare(b));
+}
+
+function normalizeRepoPathForState(repoRoot: string, absolutePath: string): string {
+  const relative = path.relative(repoRoot, absolutePath).replaceAll('\\\\', '/');
+  if (!relative || relative === '.') {
+    return '.';
+  }
+  return relative;
+}
+
+export interface FeatureLifecycleServicePort {
+  getRepoRoot(): string;
+  getFeaturesDir(): string;
+  featurePath(featureId: string): string;
+  statePath(featureId: string): string;
+  qaIndexPath(featureId: string): string;
+  decisionsPath(featureId: string): string;
+  specPath(featureId: string): string;
+  ensureFeatureLayout(featureId: string): Promise<void>;
+  repoEnsureWorktree(featureId: string): Promise<{ data: { worktree_path_abs: string } }>;
+  makeDefaultState(featureId: string, branch: string, worktreePath: string): AnyRecord;
+  writeState(featureId: string, frontMatter: AnyRecord, body?: string): Promise<void>;
+  withIndexLock<T>(operation: () => Promise<T>): Promise<T>;
+  readIndex(): Promise<AnyRecord>;
+  writeIndex(index: AnyRecord): Promise<void>;
+  featureStateGet(featureId: string): Promise<{ data: { front_matter: AnyRecord; body: string } }>;
+  planGet(featureId: string): Promise<{ data: { plan: unknown } }>;
+  qaTestIndexGet(featureId: string): Promise<{ data: unknown }>;
+  evidenceLatest(featureId: string): Promise<{ data: { latest?: unknown | null } }>;
+}
+
+export class FeatureLifecycleService {
+  private readonly port: FeatureLifecycleServicePort;
+
+  constructor(port: FeatureLifecycleServicePort) {
+    this.port = port;
+  }
+
+  async featureDiscoverSpecs(): Promise<{ data: { specs: Array<{ feature_id: string; spec_path: string }> } }> {
+    const discovered: Array<{ feature_id: string; spec_path: string }> = [];
+    const repoRoot = this.port.getRepoRoot();
+    const featuresDir = this.port.getFeaturesDir();
+
+    if (!(await pathExists(featuresDir))) {
+      return { data: { specs: [] } };
+    }
+
+    const entries = await fs.readdir(featuresDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+      const specPath = path.join(featuresDir, entry.name, 'spec.md');
+      if (await pathExists(specPath)) {
+        discovered.push({
+          feature_id: entry.name,
+          spec_path: normalizeRepoPathForState(repoRoot, specPath)
+        });
+      }
+    }
+
+    discovered.sort((a, b) => a.feature_id.localeCompare(b.feature_id));
+    return { data: { specs: discovered } };
+  }
+
+  async featureInit(featureId: string | null): Promise<{
+    data: { feature_id: string | null; initialized: boolean; worktree_path: string };
+  }> {
+    if (!featureId) {
+      throw {
+        normalizedResponse: fail(ERROR_CODES.INVALID_ARGUMENT, 'feature_id is required', {
+          retryable: false,
+          requires_human: true
+        })
+      };
+    }
+
+    const repoRoot = this.port.getRepoRoot();
+    await this.port.ensureFeatureLayout(featureId);
+    const worktreeResult = await this.port.repoEnsureWorktree(featureId);
+
+    const stateFileExists = await pathExists(this.port.statePath(featureId));
+    if (!stateFileExists) {
+      const defaultState = this.port.makeDefaultState(featureId, featureId, worktreeResult.data.worktree_path_abs);
+      await this.port.writeState(featureId, defaultState, '## Activity\n\nInitialized feature.\n');
+    }
+
+    const qaIndexExists = await pathExists(this.port.qaIndexPath(featureId));
+    if (!qaIndexExists) {
+      await atomicWriteJson(this.port.qaIndexPath(featureId), {
+        feature_id: featureId,
+        version: 1,
+        source_diff_ref: stableHash('empty'),
+        items: []
+      });
+    }
+
+    await this.port.withIndexLock(async () => {
+      const index = await this.port.readIndex();
+      index.active = normalizeSet([...(index.active ?? []), featureId]);
+      index.blocked = normalizeSet((index.blocked ?? []).filter((id: string) => id !== featureId));
+      index.version += 1;
+      index.updated_at = nowIso();
+      await this.port.writeIndex(index);
+    });
+
+    return {
+      data: {
+        feature_id: featureId,
+        initialized: true,
+        worktree_path: normalizeRepoPathForState(repoRoot, worktreeResult.data.worktree_path_abs)
+      }
+    };
+  }
+
+  async featureGetContext(featureId: string): Promise<{
+    data: {
+      feature_id: string;
+      spec: string;
+      state: unknown;
+      plan: unknown;
+      qa_test_index: unknown;
+      latest_evidence: unknown;
+    };
+  }> {
+    const state = await this.port.featureStateGet(featureId);
+    const plan = await this.port.planGet(featureId);
+    const qaIndex = await this.port.qaTestIndexGet(featureId);
+    const evidence = await this.port.evidenceLatest(featureId);
+    const specText = await fs.readFile(this.port.specPath(featureId), 'utf8').catch(() => '');
+
+    return {
+      data: {
+        feature_id: featureId,
+        spec: specText,
+        state: state.data,
+        plan: plan.data.plan,
+        qa_test_index: qaIndex.data,
+        latest_evidence: evidence.data?.latest ?? null
+      }
+    };
+  }
+
+  async featureLogAppend(
+    featureId: string,
+    note: string,
+    context: FeatureContext
+  ): Promise<{ data: { feature_id: string; appended: boolean; log_path: string } }> {
+    const repoRoot = this.port.getRepoRoot();
+    const logPath = this.port.decisionsPath(featureId);
+    const line = `- ${nowIso()} [${context.actorType}:${context.actorId}] ${note}\n`;
+    await fs.appendFile(logPath, line, 'utf8');
+    return {
+      data: {
+        feature_id: featureId,
+        appended: true,
+        log_path: normalizeRepoPathForState(repoRoot, logPath)
+      }
+    };
+  }
+}