@the-open-engine/zeroshot 6.38.0 → 6.39.0

package/src/legacy-lib/completion.ts

@@ -0,0 +1,148 @@
+import os = require('os');
+import path = require('path');
+import type { Command, Option } from 'commander';
+import omelette = require('omelette');
+import clustersRegistry = require('./clusters-registry');
+
+interface ClustersRegistryFacade {
+  readClustersFileSync(storageDir: string): unknown;
+}
+
+interface CompletionDependencies {
+  listClusterIds?: () => unknown;
+}
+
+const { readClustersFileSync }: ClustersRegistryFacade = clustersRegistry;
+
+const CLUSTER_ID_COMMANDS = new Set([
+  'attach',
+  'export',
+  'finish',
+  'kill',
+  'logs',
+  'resume',
+  'status',
+  'stop',
+]);
+
+function commandNames(command: Command): string[] {
+  return [command.name(), ...command.aliases()];
+}
+
+function visibleCommands(command: Command): Command[] {
+  return command.createHelp().visibleCommands(command);
+}
+
+function visibleOptions(command: Command): Option[] {
+  return command.createHelp().visibleOptions(command);
+}
+
+function optionNames(option: Option): string[] {
+  return [option.short, option.long].filter((name): name is string => Boolean(name));
+}
+
+function findSubcommand(command: Command, token: string): Command | undefined {
+  return visibleCommands(command).find((candidate) => commandNames(candidate).includes(token));
+}
+
+function findOption(command: Command, token: string): Option | undefined {
+  const optionToken = token.split('=', 1)[0] ?? '';
+  return visibleOptions(command).find((option) => optionNames(option).includes(optionToken));
+}
+
+function parseCompletionLine(line: string): { completed: string[]; current: string } {
+  const trailingSpace = /\s$/.test(line);
+  const tokens = line.trim().split(/\s+/).filter(Boolean);
+  tokens.shift();
+  const current = trailingSpace ? '' : (tokens.pop() ?? '');
+  return { completed: tokens, current };
+}
+
+function resolveCommandContext(
+  program: Command,
+  tokens: string[]
+): { command: Command; commandPath: string } {
+  let command = program;
+  const pathParts: string[] = [];
+  let expectsOptionValue = false;
+  let sawPositional = false;
+
+  for (const token of tokens) {
+    if (expectsOptionValue) {
+      expectsOptionValue = false;
+      continue;
+    }
+
+    const option = findOption(command, token);
+    if (option) {
+      expectsOptionValue = !token.includes('=') && (option.required || option.optional);
+      continue;
+    }
+    if (token.startsWith('-')) continue;
+
+    const subcommand = sawPositional ? undefined : findSubcommand(command, token);
+    if (subcommand) {
+      command = subcommand;
+      pathParts.push(subcommand.name());
+      continue;
+    }
+    sawPositional = true;
+  }
+
+  return { command, commandPath: pathParts.join(' ') };
+}
+
+function defaultListClusterIds(): string[] {
+  const homeDir =
+    process.env.ZEROSHOT_HOME || process.env.HOME || process.env.USERPROFILE || os.homedir();
+  const registry = readClustersFileSync(path.join(homeDir, '.zeroshot'));
+  // Preserve the legacy failure behavior if a corrupt registry is not an object.
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  return Object.keys(registry as object);
+}
+
+function safeDynamicIds(commandPath: string, listClusterIds: () => unknown): string[] {
+  if (!CLUSTER_ID_COMMANDS.has(commandPath)) return [];
+  try {
+    const ids = listClusterIds();
+    if (!Array.isArray(ids)) return [];
+    const unknownIds: unknown[] = ids;
+    return unknownIds.filter((id): id is string => typeof id === 'string' && id.length > 0);
+  } catch {
+    return [];
+  }
+}
+
+function getCompletionCandidates(
+  program: Command,
+  line: string,
+  deps: CompletionDependencies = {}
+): string[] {
+  const { completed, current } = parseCompletionLine(line);
+  const { command, commandPath } = resolveCommandContext(program, completed);
+  const listClusterIds = deps.listClusterIds || defaultListClusterIds;
+  const candidates = [
+    ...visibleCommands(command).flatMap(commandNames),
+    ...visibleOptions(command).flatMap(optionNames),
+    ...safeDynamicIds(commandPath, listClusterIds),
+  ];
+
+  return [...new Set(candidates)].filter((candidate) => candidate.startsWith(current));
+}
+
+function setupCompletion(
+  program: Command,
+  deps: CompletionDependencies = {}
+): ReturnType<typeof omelette> {
+  const complete = omelette('zeroshot');
+  complete.on('complete', (_fragment, data) => {
+    data.reply(getCompletionCandidates(program, data.line, deps));
+  });
+  complete.init();
+  return complete;
+}
+
+export = {
+  getCompletionCandidates,
+  setupCompletion,
+};

package/src/legacy-lib/compose-utils.ts

@@ -0,0 +1,102 @@
+/**
+ * Docker Compose teardown resolution for worktree cleanup.
+ *
+ * Zeroshot never runs `docker compose up` — any compose file found in a worktree
+ * belongs to the target repo, not to zeroshot. Tearing it down is only safe when
+ * the resolved Compose project name is scoped to the worktree directory itself
+ * (i.e. nothing pins it to the host's real, possibly-already-running project).
+ */
+
+import fs = require('fs');
+import path = require('path');
+import yaml = require('js-yaml');
+
+const COMPOSE_FILENAMES = [
+  'docker-compose.yml',
+  'docker-compose.yaml',
+  'compose.yml',
+  'compose.yaml',
+] as const;
+
+interface ComposeTeardownResolution {
+  readonly args?: string[];
+  readonly composePath?: string;
+  readonly reason?: string;
+  readonly shouldTeardown: boolean;
+}
+
+/**
+ * Reproduce Docker Compose's default project-name normalization
+ * (compose-go NormalizeProjectName: lowercase -> keep [a-z0-9_-] -> trim leading '_'/'-').
+ */
+function normalizeComposeProjectName(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]/g, '')
+    .replace(/^[-_]+/, '');
+}
+
+/**
+ * Decide whether it's safe to run `docker compose down` in a worktree, and with what args.
+ * Never includes `--volumes` — automatic cleanup must not delete named volumes.
+ * Skips teardown entirely when the Compose project name is pinned (top-level `name:`
+ * in the compose file, or `COMPOSE_PROJECT_NAME` env var), since that resolves to a
+ * shared/host project zeroshot did not create.
+ */
+function resolveWorktreeComposeTeardown(worktreePath: string): ComposeTeardownResolution {
+  let composePath: string | null = null;
+  for (const filename of COMPOSE_FILENAMES) {
+    const candidate = path.join(worktreePath, filename);
+    if (fs.existsSync(candidate)) {
+      composePath = candidate;
+      break;
+    }
+  }
+
+  if (!composePath) {
+    return { shouldTeardown: false, reason: 'no compose file' };
+  }
+
+  if (
+    typeof process.env.COMPOSE_PROJECT_NAME === 'string' &&
+    process.env.COMPOSE_PROJECT_NAME.trim() !== ''
+  ) {
+    return {
+      shouldTeardown: false,
+      reason: 'pinned compose project name (shared host project)',
+      composePath,
+    };
+  }
+
+  try {
+    const contents = fs.readFileSync(composePath, 'utf8');
+    const parsed = yaml.load(contents);
+    if (parsed && typeof parsed === 'object' && Reflect.get(parsed, 'name')) {
+      return {
+        shouldTeardown: false,
+        reason: 'pinned compose project name (shared host project)',
+        composePath,
+      };
+    }
+  } catch {
+    // Fail safe: if the compose file can't be read/parsed, we cannot confirm project
+    // identity is worktree-scoped, so never tear down.
+    return { shouldTeardown: false, reason: 'compose file unreadable or unparsable', composePath };
+  }
+
+  return {
+    shouldTeardown: true,
+    composePath,
+    args: [
+      'compose',
+      '-p',
+      normalizeComposeProjectName(path.basename(worktreePath)),
+      'down',
+      '--remove-orphans',
+      '--timeout',
+      '10',
+    ],
+  };
+}
+
+export = { resolveWorktreeComposeTeardown, normalizeComposeProjectName };

package/src/legacy-lib/detached-startup.ts

@@ -0,0 +1,449 @@
+import fs = require('fs');
+import os = require('os');
+import path = require('path');
+
+interface LockOptions {
+  lockfilePath: string;
+  stale: number;
+  retries: {
+    retries: number;
+    minTimeout: number;
+    maxTimeout: number;
+    randomize: boolean;
+  };
+}
+
+type ReleaseLock = () => Promise<void>;
+
+interface LockfileFacade {
+  lock(filePath: string, options: LockOptions): Promise<ReleaseLock>;
+}
+
+interface RunOptions extends Record<string, unknown> {
+  autoMerge?: unknown;
+  closeIssue?: unknown;
+  docker?: unknown;
+  mergeQueue?: unknown;
+  pr?: unknown;
+  prBase?: unknown;
+  ship?: unknown;
+  worktree?: unknown;
+}
+
+interface RunPlan {
+  isolation: 'none' | 'worktree' | 'docker';
+  delivery: 'none' | 'pr' | 'ship';
+  autoMerge: boolean;
+}
+
+interface RunPlanFacade {
+  resolveRunPlan(options?: RunOptions): Readonly<RunPlan>;
+}
+
+interface ProcessLivenessFacade {
+  isProcessRunning(pid: unknown): boolean;
+}
+
+interface IsolationManagerFacade {
+  getDetachedSetupResources(clusterId: string): unknown;
+}
+
+interface ClusterRecord extends Record<string, unknown> {
+  createdAt?: number;
+  id?: string;
+  pid?: number | null;
+  resumeDaemonPid?: number | null;
+  setupLogPath?: string | null;
+  state?: string;
+}
+
+type ClusterRegistry = Record<string, ClusterRecord>;
+type ClusterUpdater = (clusters: ClusterRegistry) => ClusterRegistry | void;
+
+interface DetachedSetupParams {
+  clusterId: string;
+  pid?: number;
+  storageDir?: string;
+  logPath?: string | null;
+  worktree?: unknown;
+  runOptions?: RunOptions;
+  cwd?: string;
+}
+
+interface ClusterIdentityParams {
+  clusterId: string;
+  storageDir?: string;
+}
+
+interface SetupFailureParams extends ClusterIdentityParams {
+  error: unknown;
+  logPath?: string | null;
+}
+
+interface ResumePatchParams extends ClusterIdentityParams {
+  daemonPid: number;
+}
+
+interface RegistrationWaitParams extends ClusterIdentityParams {
+  timeoutMs?: number;
+  pollMs?: number;
+  daemonPid?: number;
+  logPath?: string | null;
+}
+
+interface OwnershipWaitParams extends ResumePatchParams {
+  timeoutMs?: number;
+  pollMs?: number;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const lockfile: LockfileFacade = require('proper-lockfile');
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const runPlan: RunPlanFacade = require('./run-plan');
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const processLiveness: ProcessLivenessFacade = require('./process-liveness');
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const IsolationManager: IsolationManagerFacade = require('../src/isolation-manager');
+
+const { resolveRunPlan } = runPlan;
+const { isProcessRunning } = processLiveness;
+
+const DEFAULT_WAIT_TIMEOUT_SECONDS = 180;
+const DEFAULT_WAIT_POLL_MS = 1000;
+const CLUSTERS_LOCK_STALE_MS = 5000;
+const DEFAULT_OWNERSHIP_TIMEOUT_MS = 10000;
+
+function isClusterRegistry(value: unknown): value is ClusterRegistry {
+  return value !== null && typeof value === 'object';
+}
+
+function hasErrorCode(error: unknown, code: string): boolean {
+  return error !== null && typeof error === 'object' && 'code' in error && error.code === code;
+}
+
+function getStorageDir(storageDir?: string | null): string {
+  return storageDir || path.join(os.homedir(), '.zeroshot');
+}
+
+function getClustersFilePath(storageDir?: string | null): string {
+  return path.join(getStorageDir(storageDir), 'clusters.json');
+}
+
+function resolveWaitTimeoutMs(waitTimeoutSeconds: unknown): number {
+  const parsed = Number(waitTimeoutSeconds);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return DEFAULT_WAIT_TIMEOUT_SECONDS * 1000;
+  }
+  return Math.floor(parsed * 1000);
+}
+
+// Kept as an alias: this module used to carry its own copy of this check.
+const isProcessAlive = isProcessRunning;
+
+function isClusterRegistered(clusterId: string, storageDir?: string): boolean {
+  const clustersFile = getClustersFilePath(storageDir);
+  if (!fs.existsSync(clustersFile)) {
+    return false;
+  }
+
+  try {
+    const raw = fs.readFileSync(clustersFile, 'utf8');
+    const parsed: unknown = JSON.parse(raw);
+    return isClusterRegistry(parsed) && Boolean(parsed[clusterId]);
+  } catch {
+    return false;
+  }
+}
+
+function ensureStorageDir(storageDir?: string): string {
+  const resolvedStorageDir = getStorageDir(storageDir);
+  fs.mkdirSync(resolvedStorageDir, { recursive: true });
+  return resolvedStorageDir;
+}
+
+function ensureClustersFile(storageDir?: string): string {
+  const resolvedStorageDir = ensureStorageDir(storageDir);
+  const clustersFile = getClustersFilePath(resolvedStorageDir);
+  try {
+    fs.writeFileSync(clustersFile, '{}', { flag: 'wx', mode: 0o600 });
+  } catch (error: unknown) {
+    if (!hasErrorCode(error, 'EEXIST')) {
+      throw error;
+    }
+  }
+  return clustersFile;
+}
+
+function readClustersFile(clustersFile: string): ClusterRegistry {
+  try {
+    const parsed: unknown = JSON.parse(fs.readFileSync(clustersFile, 'utf8'));
+    return isClusterRegistry(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+async function updateClustersFile(
+  storageDir: string | undefined,
+  updater: ClusterUpdater
+): Promise<ClusterRegistry> {
+  const clustersFile = ensureClustersFile(storageDir);
+  const lockfilePath = path.join(path.dirname(clustersFile), 'clusters.json.lock');
+  let release: ReleaseLock | undefined;
+
+  try {
+    release = await lockfile.lock(clustersFile, {
+      lockfilePath,
+      stale: CLUSTERS_LOCK_STALE_MS,
+      retries: {
+        retries: 20,
+        minTimeout: 100,
+        maxTimeout: 250,
+        randomize: true,
+      },
+    });
+
+    const clusters = readClustersFile(clustersFile);
+    const updated = updater(clusters) || clusters;
+    fs.writeFileSync(clustersFile, JSON.stringify(updated, null, 2));
+    return updated;
+  } finally {
+    if (release) {
+      await release();
+    }
+  }
+}
+
+async function registerDetachedSetupCluster({
+  clusterId,
+  pid,
+  storageDir,
+  logPath,
+  worktree,
+  runOptions = {},
+  cwd,
+}: DetachedSetupParams): Promise<void> {
+  const plan = resolveRunPlan(runOptions);
+  const setupResources =
+    plan.isolation === 'docker' ? IsolationManager.getDetachedSetupResources(clusterId) : null;
+  await updateClustersFile(storageDir, (clusters) => {
+    clusters[clusterId] = {
+      id: clusterId,
+      state: 'setup',
+      createdAt: Date.now(),
+      pid: typeof pid === 'number' && Number.isInteger(pid) ? pid : null,
+      setupLogPath: logPath || null,
+      setupStartedAt: Date.now(),
+      setupStage: 'starting',
+      autoPr: plan.delivery !== 'none',
+      prOptions: runOptions.prBase
+        ? {
+            prBase: runOptions.prBase,
+            mergeQueue: runOptions.mergeQueue || false,
+            closeIssue: runOptions.closeIssue || null,
+            autoMerge: plan.autoMerge,
+            cwd: cwd || null,
+          }
+        : null,
+      worktree: worktree || null,
+      config: null,
+      issue: null,
+      isolation: null,
+      agentStates: [],
+      failureInfo: null,
+      setupResources,
+      provisional: true,
+    };
+    return clusters;
+  });
+}
+
+async function removeDetachedSetupCluster({
+  clusterId,
+  storageDir,
+}: ClusterIdentityParams): Promise<void> {
+  await updateClustersFile(storageDir, (clusters) => {
+    delete clusters[clusterId];
+    return clusters;
+  });
+}
+
+async function markDetachedSetupFailed({
+  clusterId,
+  storageDir,
+  error,
+  logPath,
+}: SetupFailureParams): Promise<void> {
+  await updateClustersFile(storageDir, (clusters) => {
+    const existing = clusters[clusterId] || { id: clusterId, createdAt: Date.now() };
+    clusters[clusterId] = {
+      ...existing,
+      state: 'failed',
+      pid: null,
+      setupLogPath: existing.setupLogPath || logPath || null,
+      setupFinishedAt: Date.now(),
+      failureInfo: {
+        type: 'setup',
+        error: error instanceof Error ? error.message : String(error),
+        timestamp: Date.now(),
+      },
+      provisional: true,
+    };
+    return clusters;
+  });
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function formatLogHint(logPath?: string | null): string {
+  return logPath ? ` Check log: ${logPath}` : '';
+}
+
+async function waitForClusterRegistration({
+  clusterId,
+  timeoutMs,
+  pollMs = DEFAULT_WAIT_POLL_MS,
+  storageDir,
+  daemonPid,
+  logPath,
+}: RegistrationWaitParams): Promise<{ ready: true; elapsedMs: number }> {
+  const effectiveTimeoutMs =
+    typeof timeoutMs === 'number' && Number.isFinite(timeoutMs) && timeoutMs > 0
+      ? timeoutMs
+      : DEFAULT_WAIT_TIMEOUT_SECONDS * 1000;
+  const startedAt = Date.now();
+  const deadline = startedAt + effectiveTimeoutMs;
+  const logHint = formatLogHint(logPath);
+
+  while (Date.now() < deadline) {
+    if (isClusterRegistered(clusterId, storageDir)) {
+      return { ready: true, elapsedMs: Date.now() - startedAt };
+    }
+
+    if (daemonPid && !isProcessAlive(daemonPid)) {
+      throw new Error(
+        `Detached daemon exited before cluster "${clusterId}" registered in storage.${logHint}`
+      );
+    }
+
+    await sleep(pollMs);
+  }
+
+  const timeoutSeconds = Math.ceil(effectiveTimeoutMs / 1000);
+  throw new Error(
+    `Timed out after ${timeoutSeconds}s waiting for cluster "${clusterId}" to appear in status/list.${logHint}`
+  );
+}
+
+/**
+ * Atomically claim the right to resume-daemon an existing cluster record.
+ * Ownership for the handoff is tracked separately from cluster.pid/state so
+ * orchestrator.resume() can still perform its own eligibility check.
+ */
+async function patchDetachedResumeCluster({
+  clusterId,
+  daemonPid,
+  storageDir,
+}: ResumePatchParams): Promise<void> {
+  await updateClustersFile(storageDir, (clusters) => {
+    const existing = clusters[clusterId];
+    if (!existing) {
+      throw new Error(`Cannot start resume daemon: cluster "${clusterId}" not found in registry`);
+    }
+    if (existing.resumeDaemonPid && isProcessRunning(existing.resumeDaemonPid)) {
+      const ownership = `Cluster "${clusterId}" already has a live resume daemon`;
+      throw new Error(
+        `${ownership} (PID ${existing.resumeDaemonPid}); refusing to start a second one`
+      );
+    }
+    if (existing.state === 'running' && existing.pid && isProcessRunning(existing.pid)) {
+      throw new Error(
+        `Cluster "${clusterId}" is already running (PID ${existing.pid}); refusing to start a second resume daemon`
+      );
+    }
+    clusters[clusterId] = { ...existing, resumeDaemonPid: daemonPid };
+    return clusters;
+  });
+}
+
+/**
+ * Undo a resume handoff that did not complete so a dead daemon cannot leave
+ * the cluster stuck in a running state.
+ */
+async function revertDetachedResumeCluster({
+  clusterId,
+  storageDir,
+  error,
+}: SetupFailureParams): Promise<void> {
+  await updateClustersFile(storageDir, (clusters) => {
+    const existing = clusters[clusterId];
+    if (!existing) return clusters;
+    clusters[clusterId] = {
+      ...existing,
+      state: 'failed',
+      pid: null,
+      resumeDaemonPid: null,
+      failureInfo: {
+        type: 'resume-daemon',
+        error: error instanceof Error ? error.message : String(error),
+        timestamp: Date.now(),
+      },
+    };
+    return clusters;
+  });
+}
+
+function getRegisteredResumeDaemonPid(clusterId: string, storageDir?: string): number | null {
+  const clustersFile = getClustersFilePath(storageDir);
+  if (!fs.existsSync(clustersFile)) {
+    return null;
+  }
+  try {
+    const parsed: unknown = JSON.parse(fs.readFileSync(clustersFile, 'utf8'));
+    if (!isClusterRegistry(parsed)) {
+      return null;
+    }
+    return parsed[clusterId]?.resumeDaemonPid ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Daemon-side half of the resume handoff: wait until the registry shows this
+ * process's PID as resumeDaemonPid before touching the cluster.
+ */
+async function waitForResumeOwnership({
+  clusterId,
+  daemonPid,
+  storageDir,
+  timeoutMs = DEFAULT_OWNERSHIP_TIMEOUT_MS,
+  pollMs = DEFAULT_WAIT_POLL_MS,
+}: OwnershipWaitParams): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (getRegisteredResumeDaemonPid(clusterId, storageDir) === daemonPid) {
+      return true;
+    }
+    await sleep(pollMs);
+  }
+  return getRegisteredResumeDaemonPid(clusterId, storageDir) === daemonPid;
+}
+
+export = {
+  DEFAULT_WAIT_TIMEOUT_SECONDS,
+  getClustersFilePath,
+  getRegisteredResumeDaemonPid,
+  isClusterRegistered,
+  isProcessAlive,
+  markDetachedSetupFailed,
+  patchDetachedResumeCluster,
+  registerDetachedSetupCluster,
+  removeDetachedSetupCluster,
+  resolveWaitTimeoutMs,
+  revertDetachedResumeCluster,
+  waitForClusterRegistration,
+  waitForResumeOwnership,
+};