PaperClipAI/cli/src/commands/worktree-lib.ts

import { randomInt } from "node:crypto";
import path from "node:path";
import type { PaperclipConfig } from "../config/schema.js";
import { expandHomePrefix } from "../config/home.js";

export const DEFAULT_WORKTREE_HOME = "~/.paperclip-worktrees";
export const WORKTREE_SEED_MODES = ["minimal", "full"] as const;
export const WORKTREE_SEED_MANIFEST = "seed-manifest.json";
export const WORKTREE_SEED_PENDING_MARKER = "seed-pending";
export const WORKTREE_SEED_COMPLETE_MARKER = "seed-complete";
export const WORKTREE_SEED_LOCK_MARKER = "seed.lock";

export type WorktreeSeedMode = (typeof WORKTREE_SEED_MODES)[number];

export const WORKTREE_SEED_PHASES = [
  "pending",
  "source_validation",
  "snapshot",
  "restore",
  "migrations",
  "execution_quarantine",
  "routine_pause",
  "workspace_rebind",
  "post_restore_validation",
  "complete",
] as const;

export type WorktreeSeedPhase = (typeof WORKTREE_SEED_PHASES)[number];
export type WorktreeSeedState = "pending" | "running" | "verified" | "failed";

export type WorktreeSeedManifest = {
  version: 2;
  source: {
    instanceId: string;
    configPath: string;
  };
  snapshotAt: string | null;
  seedMode: WorktreeSeedMode;
  migrationRevision: string | null;
  targetInstanceId: string;
  phase: WorktreeSeedPhase;
  state: WorktreeSeedState;
  attemptId: string;
  startedAt: string | null;
  finishedAt: string | null;
  diagnostics: Array<{
    phase: WorktreeSeedPhase;
    status: "started" | "succeeded" | "failed";
    at: string;
    message?: string;
  }>;
};

export type WorktreeSeedPlan = {
  mode: WorktreeSeedMode;
  excludedTables: string[];
  nullifyColumns: Record<string, string[]>;
};

const MINIMAL_WORKTREE_EXCLUDED_TABLES = [
  "activity_log",
  "agent_runtime_state",
  "agent_task_sessions",
  "agent_wakeup_requests",
  "cost_events",
  "heartbeat_run_events",
  "heartbeat_runs",
  "workspace_runtime_services",
];

const MINIMAL_WORKTREE_NULLIFIED_COLUMNS: Record<string, string[]> = {
  issues: ["checkout_run_id", "execution_run_id"],
};

export type WorktreeLocalPaths = {
  cwd: string;
  repoConfigDir: string;
  configPath: string;
  envPath: string;
  homeDir: string;
  instanceId: string;
  instanceRoot: string;
  contextPath: string;
  embeddedPostgresDataDir: string;
  backupDir: string;
  logDir: string;
  secretsKeyFilePath: string;
  storageDir: string;
};

export type WorktreeUiBranding = {
  name: string;
  color: string;
};

export type WorktreeSeedMarkerPaths = {
  manifest: string;
  pending: string;
  complete: string;
  lock: string;
};

export function resolveWorktreeSeedMarkerPaths(configPath: string): WorktreeSeedMarkerPaths {
  const configDir = path.dirname(path.resolve(configPath));
  return {
    manifest: path.resolve(configDir, WORKTREE_SEED_MANIFEST),
    pending: path.resolve(configDir, WORKTREE_SEED_PENDING_MARKER),
    complete: path.resolve(configDir, WORKTREE_SEED_COMPLETE_MARKER),
    lock: path.resolve(configDir, WORKTREE_SEED_LOCK_MARKER),
  };
}

export function isWorktreeSeedMode(value: string): value is WorktreeSeedMode {
  return (WORKTREE_SEED_MODES as readonly string[]).includes(value);
}

export function resolveWorktreeSeedPlan(mode: WorktreeSeedMode): WorktreeSeedPlan {
  if (mode === "full") {
    return {
      mode,
      excludedTables: [],
      nullifyColumns: {},
    };
  }
  return {
    mode,
    excludedTables: [...MINIMAL_WORKTREE_EXCLUDED_TABLES],
    nullifyColumns: {
      ...MINIMAL_WORKTREE_NULLIFIED_COLUMNS,
    },
  };
}

function nonEmpty(value: string | null | undefined): string | null {
  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
}

export function sanitizeWorktreeInstanceId(rawValue: string): string {
  const trimmed = rawValue.trim().toLowerCase();
  const normalized = trimmed
    .replace(/[^a-z0-9_-]+/g, "-")
    .replace(/-+/g, "-")
    .replace(/^[-_]+|[-_]+$/g, "");
  return normalized || "worktree";
}

export function resolveSuggestedWorktreeName(cwd: string, explicitName?: string): string {
  return nonEmpty(explicitName) ?? path.basename(path.resolve(cwd));
}

function hslComponentToHex(n: number): string {
  return Math.round(Math.max(0, Math.min(255, n)))
    .toString(16)
    .padStart(2, "0");
}

function hslToHex(hue: number, saturation: number, lightness: number): string {
  const s = Math.max(0, Math.min(100, saturation)) / 100;
  const l = Math.max(0, Math.min(100, lightness)) / 100;
  const c = (1 - Math.abs((2 * l) - 1)) * s;
  const h = ((hue % 360) + 360) % 360;
  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
  const m = l - (c / 2);

  let r = 0;
  let g = 0;
  let b = 0;

  if (h < 60) {
    r = c;
    g = x;
  } else if (h < 120) {
    r = x;
    g = c;
  } else if (h < 180) {
    g = c;
    b = x;
  } else if (h < 240) {
    g = x;
    b = c;
  } else if (h < 300) {
    r = x;
    b = c;
  } else {
    r = c;
    b = x;
  }

  return `#${hslComponentToHex((r + m) * 255)}${hslComponentToHex((g + m) * 255)}${hslComponentToHex((b + m) * 255)}`;
}

export function generateWorktreeColor(): string {
  return hslToHex(randomInt(0, 360), 68, 56);
}

export function resolveWorktreeLocalPaths(opts: {
  cwd: string;
  homeDir?: string;
  instanceId: string;
}): WorktreeLocalPaths {
  const cwd = path.resolve(opts.cwd);
  const homeDir = path.resolve(expandHomePrefix(opts.homeDir ?? DEFAULT_WORKTREE_HOME));
  const instanceRoot = path.resolve(homeDir, "instances", opts.instanceId);
  const repoConfigDir = path.resolve(cwd, ".paperclip");
  return {
    cwd,
    repoConfigDir,
    configPath: path.resolve(repoConfigDir, "config.json"),
    envPath: path.resolve(repoConfigDir, ".env"),
    homeDir,
    instanceId: opts.instanceId,
    instanceRoot,
    contextPath: path.resolve(homeDir, "context.json"),
    embeddedPostgresDataDir: path.resolve(instanceRoot, "db"),
    backupDir: path.resolve(instanceRoot, "data", "backups"),
    logDir: path.resolve(instanceRoot, "logs"),
    secretsKeyFilePath: path.resolve(instanceRoot, "secrets", "master.key"),
    storageDir: path.resolve(instanceRoot, "data", "storage"),
  };
}

export function rewriteLocalUrlPort(rawUrl: string | undefined, port: number): string | undefined {
  if (!rawUrl) return undefined;
  try {
    const parsed = new URL(rawUrl);
    // The URL API normalizes default ports like :80/:443 to "", so treat them as stable URLs.
    if (!parsed.port) return rawUrl;
    parsed.port = String(port);
    return parsed.toString();
  } catch {
    return rawUrl;
  }
}

export function buildWorktreeConfig(input: {
  sourceConfig: PaperclipConfig | null;
  paths: WorktreeLocalPaths;
  serverPort: number;
  databasePort: number;
  now?: Date;
}): PaperclipConfig {
  const { sourceConfig, paths, serverPort, databasePort } = input;
  const nowIso = (input.now ?? new Date()).toISOString();

  const source = sourceConfig;
  const authPublicBaseUrl = rewriteLocalUrlPort(source?.auth.publicBaseUrl, serverPort);

  return {
    $meta: {
      version: 1,
      updatedAt: nowIso,
      source: "configure",
    },
    ...(source?.llm ? { llm: source.llm } : {}),
    database: {
      mode: "embedded-postgres",
      embeddedPostgresDataDir: paths.embeddedPostgresDataDir,
      embeddedPostgresPort: databasePort,
      backup: {
        enabled: false,
        intervalMinutes: source?.database.backup.intervalMinutes ?? 60,
        retentionDays: source?.database.backup.retentionDays ?? 30,
        dir: paths.backupDir,
      },
    },
    logging: {
      mode: source?.logging.mode ?? "file",
      logDir: paths.logDir,
    },
    server: {
      deploymentMode: source?.server.deploymentMode ?? "local_trusted",
      exposure: source?.server.exposure ?? "private",
      ...(source?.server.bind ? { bind: source.server.bind } : {}),
      ...(source?.server.customBindHost ? { customBindHost: source.server.customBindHost } : {}),
      host: source?.server.host ?? "127.0.0.1",
      port: serverPort,
      allowedHostnames: source?.server.allowedHostnames ?? [],
      serveUi: source?.server.serveUi ?? true,
    },
    auth: {
      baseUrlMode: source?.auth.baseUrlMode ?? "auto",
      ...(authPublicBaseUrl ? { publicBaseUrl: authPublicBaseUrl } : {}),
      disableSignUp: source?.auth.disableSignUp ?? false,
    },
    telemetry: {
      enabled: source?.telemetry?.enabled ?? true,
    },
    storage: {
      provider: source?.storage.provider ?? "local_disk",
      localDisk: {
        baseDir: paths.storageDir,
      },
      s3: {
        bucket: source?.storage.s3.bucket ?? "paperclip",
        region: source?.storage.s3.region ?? "us-east-1",
        endpoint: source?.storage.s3.endpoint,
        prefix: source?.storage.s3.prefix ?? "",
        forcePathStyle: source?.storage.s3.forcePathStyle ?? false,
      },
    },
    secrets: {
      provider: source?.secrets.provider ?? "local_encrypted",
      strictMode: source?.secrets.strictMode ?? false,
      localEncrypted: {
        keyFilePath: paths.secretsKeyFilePath,
      },
    },
  };
}

export function buildWorktreeEnvEntries(
  paths: WorktreeLocalPaths,
  branding?: WorktreeUiBranding,
): Record<string, string> {
  return {
    PAPERCLIP_HOME: paths.homeDir,
    PAPERCLIP_INSTANCE_ID: paths.instanceId,
    PAPERCLIP_CONFIG: paths.configPath,
    PAPERCLIP_CONTEXT: paths.contextPath,
    PAPERCLIP_IN_WORKTREE: "true",
    PAPERCLIP_DB_BACKUP_ENABLED: "false",
    ...(branding?.name ? { PAPERCLIP_WORKTREE_NAME: branding.name } : {}),
    ...(branding?.color ? { PAPERCLIP_WORKTREE_COLOR: branding.color } : {}),
  };
}

function shellEscape(value: string): string {
  return `'${value.replaceAll("'", `'\"'\"'`)}'`;
}

export function formatShellExports(entries: Record<string, string>): string {
  return Object.entries(entries)
    .filter(([, value]) => typeof value === "string" && value.trim().length > 0)
    .map(([key, value]) => `export ${key}=${shellEscape(value)}`)
    .join("\n");
}