boxdown 1.0.0 → 1.2.0

package/dist/main.d.mts

@@ -4,21 +4,512 @@ type CodingAgentCommandAlias = CodingAgentCli | 'cc';
 declare function codingAgentFromCommand(command: string): CodingAgentCli | undefined;
 declare function codingAgentBinary(agent: CodingAgentCli): string;
 //#endregion
+//#region src/paths.d.ts
+interface WorkspaceContextOptions {
+  workspace?: string;
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  packageRoot?: string;
+  assetsDevcontainerDir?: string;
+}
+interface WorkspaceContext {
+  workspaceFolder: string;
+  workspaceBasename: string;
+  workspaceId: string;
+  packageRoot: string;
+  assetsDevcontainerDir: string;
+  cacheRoot: string;
+  dataRoot: string;
+  workspaceCacheDir: string;
+  workspaceDataDir: string;
+  generatedConfigPath: string;
+  hostAgentsDir: string;
+  hostCodexAuthPath: string;
+  hostGitconfigPath: string;
+  hostGitconfigSnapshotDir: string;
+  hostGitconfigSnapshotPath: string;
+  gitSigningStateDir: string;
+  gitSigningPublicKeyPath: string;
+  sshKeyDir: string;
+  sshKeyPath: string;
+  sshPublicKeyPath: string;
+  sshPublicKeyRuntimeDir: string;
+  sshPublicKeyRuntimePath: string;
+  workspaceLogPath: string;
+}
+interface WorkspaceContextIdentity {
+  workspaceFolder: string;
+  workspaceBasename: string;
+  workspaceId: string;
+}
+declare function packageRootFromImportMeta(importMetaUrl?: string): string;
+declare function workspaceIdFor(workspaceFolder: string): string;
+declare function resolveWorkspaceFolder(workspace: string | undefined, cwd?: string): string;
+declare function defaultCacheRoot(env?: NodeJS.ProcessEnv): string;
+declare function defaultDataRoot(env?: NodeJS.ProcessEnv): string;
+declare function defaultHostAgentsDir(env?: NodeJS.ProcessEnv): string;
+declare function defaultHostCodexAuthPath(env?: NodeJS.ProcessEnv): string;
+declare function defaultHostGitconfigPath(env?: NodeJS.ProcessEnv): string;
+declare function createWorkspaceContextFromIdentity(identity: WorkspaceContextIdentity, options?: Omit<WorkspaceContextOptions, 'workspace' | 'cwd'>): WorkspaceContext;
+declare function createWorkspaceContext(options?: WorkspaceContextOptions): WorkspaceContext;
+//#endregion
+//#region src/doctor.d.ts
+type DoctorLevel = 'ok' | 'fail' | 'warn';
+interface DoctorCheck {
+  name: string;
+  level: DoctorLevel;
+  message: string;
+}
+interface DoctorCommandResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+type DoctorCommandRunner = (command: string, args: string[]) => Promise<DoctorCommandResult>;
+interface RunDoctorChecksOptions {
+  includeOptional?: boolean;
+  includeDockerMountProbe?: boolean;
+  runCommand?: DoctorCommandRunner;
+}
+declare function runDoctorChecks(context: WorkspaceContext, options?: RunDoctorChecksOptions): Promise<DoctorCheck[]>;
+declare function doctorHasFailures(checks: DoctorCheck[]): boolean;
+declare function formatDoctorText(checks: DoctorCheck[]): string;
+//#endregion
+//#region src/logging.d.ts
+type LogStreamName = 'stdout' | 'stderr' | 'boxdown';
+interface WorkspaceCommandLoggerOptions {
+  redactions?: string[];
+  now?: () => Date;
+}
+interface LoggedCommand {
+  stream: (stream: Extract<LogStreamName, 'stdout' | 'stderr'>, chunk: Buffer | string) => void;
+  error: (error: unknown) => void;
+  finish: (code: number) => void;
+}
+declare class WorkspaceCommandLogger {
+  #private;
+  readonly logPath: string;
+  readonly workspaceFolder: string;
+  constructor(context: Pick<WorkspaceContext, 'workspaceFolder' | 'workspaceLogPath'>, options?: WorkspaceCommandLoggerOptions);
+  addRedaction(value: string): void;
+  disable(): void;
+  section(title: string, details?: Record<string, string | number | boolean | undefined>): void;
+  boxdown(chunk: Buffer | string): void;
+  startCommand(command: string, args: string[], options?: {
+    cwd?: string;
+  }): LoggedCommand;
+}
+declare function createWorkspaceCommandLogger(context: Pick<WorkspaceContext, 'workspaceFolder' | 'workspaceLogPath'>, options?: WorkspaceCommandLoggerOptions): WorkspaceCommandLogger;
+declare function withLoggedProcessOutput<T>(logger: WorkspaceCommandLogger, action: () => Promise<T>): Promise<T>;
+//#endregion
+//#region src/process.d.ts
+interface BufferedCommandOptions {
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  input?: string;
+  mirrorStdout?: 'stdout' | 'stderr' | false;
+  mirrorStderr?: 'stdout' | 'stderr' | false;
+  logger?: WorkspaceCommandLogger;
+  onStdout?: (chunk: Buffer) => void;
+  onStderr?: (chunk: Buffer) => void;
+}
+interface CommandResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+declare function buildHostToolPath(env?: NodeJS.ProcessEnv): string;
+declare function runBuffered(command: string, args: string[], options?: BufferedCommandOptions): Promise<CommandResult>;
+declare function runInteractive(command: string, args: string[], options?: Pick<BufferedCommandOptions, 'cwd' | 'env' | 'logger'>): Promise<number>;
+//#endregion
+//#region src/progress.d.ts
+type ProgressOutputTarget = 'stdout' | 'stderr';
+type ProgressMode = 'interactive' | 'verbose' | 'none';
+type ProgressWriter = (target: ProgressOutputTarget, message: string) => void;
+type ProgressRawWriter = (target: ProgressOutputTarget, message: string) => void;
+interface ProgressReporterOptions {
+  mode?: ProgressMode;
+  verbose?: boolean;
+  target?: ProgressOutputTarget;
+  write?: ProgressWriter;
+  writeRaw?: ProgressRawWriter;
+  isTTY?: boolean;
+  spinnerFrames?: readonly string[];
+  spinnerIntervalMs?: number;
+}
+interface ProgressCommandOptions extends Pick<BufferedCommandOptions, 'cwd' | 'env' | 'input'> {
+  logger?: BufferedCommandOptions['logger'];
+  progress?: ProgressReporter;
+  verboseStdout?: ProgressOutputTarget | false;
+  verboseStderr?: ProgressOutputTarget | false;
+  spinnerLabel?: string;
+  stepId?: string;
+}
+interface ResolveProgressModeOptions {
+  verbose?: boolean;
+  json?: boolean;
+  target?: ProgressOutputTarget;
+  env?: NodeJS.ProcessEnv;
+  isTTY?: boolean;
+}
+type ProgressStepState = 'pending' | 'running' | 'complete' | 'failed' | 'skipped';
+interface ProgressStepDefinition {
+  id: string;
+  label: string;
+}
+declare function resolveProgressMode(options?: ResolveProgressModeOptions): ProgressMode;
+declare class ProgressReporter {
+  #private;
+  readonly mode: ProgressMode;
+  readonly verbose: boolean;
+  readonly target: ProgressOutputTarget;
+  constructor(options?: ProgressReporterOptions);
+  section(title: string): void;
+  end(): void;
+  item(message: string): void;
+  detail(message: string): void;
+  warn(message: string): void;
+  marker(message: string): void;
+  setSteps(steps: readonly ProgressStepDefinition[]): void;
+  isChecklistActive(): boolean;
+  startStep(id: string): void;
+  completeStep(id: string): void;
+  failStep(id: string): void;
+  skipStep(id: string): void;
+  hasStep(id: string): boolean;
+  startSpinner(message: string): void;
+  tickSpinner(): void;
+  stopSpinner(status?: 'complete' | 'clear'): void;
+  commandEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+}
+declare function createProgress(options?: ProgressReporterOptions): ProgressReporter;
+declare function progressMarkerLine(message: string): string;
+declare function formatCommandFailure(label: string, result: CommandResult, options?: {
+  tailLines?: number;
+}): string;
+declare function runProgressCommand(label: string, command: string, args: string[], options?: ProgressCommandOptions): Promise<CommandResult>;
+declare function assertProgressCommandSucceeded(label: string, result: CommandResult, message: string): void;
+//#endregion
+//#region src/status.d.ts
+type SshAliasSource = 'default' | 'provided';
+type SshManagedBlockState = 'missing' | 'installed' | 'outdated';
+interface ContainerSummary {
+  id: string;
+  name?: string;
+  state?: string;
+  status?: string;
+  localFolder?: string;
+}
+interface StatusInfo {
+  workspace: {
+    folder: string;
+    basename: string;
+    id: string;
+  };
+  ssh: {
+    alias: string;
+    aliasSource: SshAliasSource;
+    configPath: string;
+    configExists: boolean;
+    managedBlockState: SshManagedBlockState;
+    keyPath: string;
+    keyExists: boolean;
+    publicKeyPath: string;
+    publicKeyExists: boolean;
+    publicKeyRuntimePath: string;
+    publicKeyRuntimeExists: boolean;
+  };
+  paths: {
+    cacheRoot: string;
+    dataRoot: string;
+    workspaceCacheDir: string;
+    workspaceDataDir: string;
+    generatedConfigPath: string;
+    generatedConfigExists: boolean;
+    logPath: string;
+    logExists: boolean;
+    assetsDevcontainerDir: string;
+    assetsDevcontainerExists: boolean;
+  };
+  container: {
+    found: boolean;
+    running: boolean;
+    id?: string;
+    name?: string;
+    state?: string;
+    status?: string;
+  };
+}
+interface SshConfigStatus {
+  configPath: string;
+  configExists: boolean;
+  managedBlockState: SshManagedBlockState;
+}
+declare function parseDockerPsJsonLines(output: string): ContainerSummary[];
+declare function inspectSshConfigStatus(context: WorkspaceContext, alias: string, configPath: string, exists: (path: string) => boolean, readFile?: (path: string) => string): SshConfigStatus;
+declare function createStatusInfo(context: WorkspaceContext, alias: string, container: ContainerSummary | undefined, exists: (path: string) => boolean, options?: {
+  aliasSource?: SshAliasSource;
+  sshConfigPath?: string;
+  readFile?: (path: string) => string;
+}): StatusInfo;
+declare function statusIsHealthy(status: StatusInfo): boolean;
+declare function formatStatusText(status: StatusInfo, options?: {
+  color?: boolean;
+}): string;
+//#endregion
+//#region src/devcontainer.d.ts
+interface StartOptions {
+  recreate?: boolean;
+  proxyMode?: boolean;
+  progress?: ProgressReporter;
+  logger?: WorkspaceCommandLogger;
+  reuseRunning?: boolean;
+}
+interface ContainerCommandOptions {
+  progress?: ProgressReporter;
+  logger?: WorkspaceCommandLogger;
+}
+interface TunnelPortForward {
+  localPort: number;
+  remotePort: number;
+}
+interface SshTunnelOptions {
+  bindAddress?: string;
+  remoteHost?: string;
+}
+interface DockerImageInfo {
+  id: string;
+  name?: string;
+}
+declare function parseContainerIdFromUpOutput(output: string): string | undefined;
+declare function findWorkspaceContainer(context: WorkspaceContext, options?: {
+  logger?: WorkspaceCommandLogger;
+}): Promise<ContainerSummary | undefined>;
+declare function listWorkspaceContainers(): Promise<ContainerSummary[] | undefined>;
+declare function findRunningContainerId(context: WorkspaceContext, options?: {
+  logger?: WorkspaceCommandLogger;
+}): Promise<string | undefined>;
+declare function inspectContainerImage(containerId: string, options?: {
+  logger?: WorkspaceCommandLogger;
+}): Promise<DockerImageInfo | undefined>;
+declare function stopWorkspaceContainer(context: WorkspaceContext, options?: {
+  logger?: WorkspaceCommandLogger;
+}): Promise<void>;
+declare function removeWorkspaceContainer(context: WorkspaceContext, options?: {
+  logger?: WorkspaceCommandLogger;
+}): Promise<void>;
+declare function removeContainerById(containerId: string, options?: {
+  volumes?: boolean;
+  logger?: WorkspaceCommandLogger;
+}): Promise<void>;
+declare function removeDockerImage(imageId: string, options?: {
+  logger?: WorkspaceCommandLogger;
+}): Promise<boolean>;
+declare function startDevcontainer(context: WorkspaceContext, options?: StartOptions): Promise<string>;
+declare function printPortHint(context: WorkspaceContext, containerId: string, options?: {
+  logger?: WorkspaceCommandLogger;
+}): Promise<void>;
+declare function openShell(context: WorkspaceContext, options?: {
+  logger?: WorkspaceCommandLogger;
+}): Promise<number>;
+declare function codingAgentDevcontainerExecArgs(context: WorkspaceContext, agent: CodingAgentCli, agentArgs?: string[]): string[];
+declare function openCodingAgentCli(context: WorkspaceContext, agent: CodingAgentCli, agentArgs?: string[], options?: {
+  logger?: WorkspaceCommandLogger;
+}): Promise<number>;
+declare function ensureContainerSshRuntime(context: WorkspaceContext, options?: ContainerCommandOptions): Promise<void>;
+declare function refreshContainerCodingAgentClis(context: WorkspaceContext, proxyMode?: boolean, agents?: CodingAgentCli[], options?: ContainerCommandOptions): Promise<void>;
+declare function ensureContainerCodingAgentCli(context: WorkspaceContext, agent: CodingAgentCli, options?: ContainerCommandOptions): Promise<void>;
+declare function runSshdProxy(containerId: string, options?: {
+  logger?: WorkspaceCommandLogger;
+}): Promise<number>;
+declare function sshTunnelArgs(alias: string, ports: TunnelPortForward[], options?: SshTunnelOptions): string[];
+declare function openSshTunnel(alias: string, ports: TunnelPortForward[], options?: SshTunnelOptions & {
+  logger?: WorkspaceCommandLogger;
+}): Promise<number>;
+declare function refreshContainerGhAuth(context: WorkspaceContext, options?: ContainerCommandOptions): Promise<void>;
+//#endregion
+//#region src/cli-style.d.ts
+declare const ansi: {
+  readonly bold: "\u001B[1m";
+  readonly cyan: "\u001B[36m";
+  readonly dim: "\u001B[2m";
+  readonly green: "\u001B[32m";
+  readonly red: "\u001B[31m";
+  readonly yellow: "\u001B[33m";
+  readonly reset: "\u001B[0m";
+};
+type CliColor = keyof typeof ansi;
+declare function color(value: string, colorName: CliColor): string;
+declare function selectedMark(): string;
+declare function emptyMark(isFocused: boolean): string;
+declare function promptRail(): string;
+declare function formatPromptTitle(title: string): string;
+declare function formatPromptEnd(): string;
+declare function formatPromptLabel(label: string, isFocused: boolean): string;
+declare function formatPromptDetailLine(detail: string): string;
+//#endregion
+//#region src/interactive-prompts.d.ts
+interface MultiSelectDescriptionSegment {
+  text: string;
+  color: CliColor;
+}
+interface MultiSelectChoice<T extends string> {
+  value: T;
+  label: string;
+  description: string;
+  focusedDescription?: readonly MultiSelectDescriptionSegment[];
+}
+type MultiSelectPromptResult<T extends string> = {
+  status: 'selected';
+  values: T[];
+} | {
+  status: 'skipped';
+  values: [];
+} | {
+  status: 'cancelled';
+  values: [];
+} | {
+  status: 'non-interactive';
+  values: [];
+};
+type PromptInput = NodeJS.ReadableStream & {
+  isTTY?: boolean;
+  setRawMode?: (mode: boolean) => void;
+  resume: () => PromptInput;
+  pause: () => PromptInput;
+};
+type PromptOutput = NodeJS.WritableStream & {
+  isTTY?: boolean;
+  columns?: number;
+};
+interface MultiSelectPromptOptions<T extends string> {
+  title: string;
+  choices: readonly MultiSelectChoice<T>[];
+  skipLabel: string;
+  summaryLabel?: string;
+  input?: PromptInput;
+  output?: PromptOutput;
+  env?: NodeJS.ProcessEnv;
+}
+type TextPromptResult = {
+  status: 'submitted';
+  value: string;
+} | {
+  status: 'cancelled';
+  value?: undefined;
+} | {
+  status: 'non-interactive';
+  value?: undefined;
+};
+interface TextPromptOptions {
+  title: string;
+  details?: readonly string[];
+  defaultValue?: string;
+  summaryLabel: string;
+  validate?: (value: string) => string | undefined;
+  input?: PromptInput;
+  output?: PromptOutput;
+  env?: NodeJS.ProcessEnv;
+}
+type ConfirmPromptResult = {
+  status: 'confirmed';
+} | {
+  status: 'denied';
+} | {
+  status: 'cancelled';
+} | {
+  status: 'non-interactive';
+};
+interface ConfirmPromptOptions {
+  title: string;
+  details?: readonly string[];
+  confirmLabel: string;
+  cancelLabel: string;
+  summaryLabel: string;
+  input?: PromptInput;
+  output?: PromptOutput;
+  env?: NodeJS.ProcessEnv;
+}
+declare function canPromptInteractively(input: PromptInput, output: PromptOutput, env: NodeJS.ProcessEnv): boolean;
+declare function promptMultiSelect<T extends string>(options: MultiSelectPromptOptions<T>): Promise<MultiSelectPromptResult<T>>;
+declare function promptText(options: TextPromptOptions): Promise<TextPromptResult>;
+declare function promptConfirm(options: ConfirmPromptOptions): Promise<ConfirmPromptResult>;
+//#endregion
+//#region src/ssh-config.d.ts
+declare function defaultSshAlias(workspaceBasename: string): string;
+declare function validateSshAlias(alias: string): void;
+declare function defaultSshConfigPath(env?: NodeJS.ProcessEnv): string;
+declare function buildProxyCommand(context: WorkspaceContext, alias: string): string;
+declare function buildSshConfigBlock(context: WorkspaceContext, alias: string): string;
+declare function replaceSshConfigBlock(existingConfig: string, alias: string, block: string): string;
+declare function removeSshConfigBlock(existingConfig: string, alias: string): string;
+declare function installSshConfig(context: WorkspaceContext, alias: string, options?: {
+  quiet?: boolean;
+  configPath?: string;
+}): Promise<void>;
+declare function uninstallSshConfig(alias: string, options?: {
+  quiet?: boolean;
+  configPath?: string;
+}): boolean;
+//#endregion
+//#region src/ssh-install-targets.d.ts
+type SshConfigInstallTarget = 'codex' | 'claude';
+interface SshInstallTargetDefinition {
+  value: SshConfigInstallTarget;
+  label: string;
+  description: string;
+  flag: string;
+  install: (context: WorkspaceContext, alias: string, options?: SshInstallTargetInstallOptions) => Promise<void> | void;
+}
+interface SshInstallTargetInstallOptions {
+  quiet?: boolean;
+}
+declare const SSH_INSTALL_TARGETS: readonly SshInstallTargetDefinition[];
+declare function supportedSshInstallTargetsText(): string;
+declare function sshInstallTargetFlagHintsText(): string;
+declare function isSshConfigInstallTarget(value: string): value is SshConfigInstallTarget;
+declare function dedupeSshInstallTargets(targets: readonly SshConfigInstallTarget[]): SshConfigInstallTarget[];
+declare function installSshInstallTarget(context: WorkspaceContext, alias: string, targetValue: SshConfigInstallTarget, options?: SshInstallTargetInstallOptions): Promise<void>;
+//#endregion
 //#region src/main.d.ts
-type BoxdownCommand = 'help' | 'start' | 'list' | 'status' | 'stop' | 'down' | 'doctor' | 'ssh-config-install' | 'ssh-proxy' | 'refresh-gh-token' | 'refresh-gh-token-running' | 'coding-agent';
+type BoxdownCommand = 'help' | 'version' | 'setup' | 'start' | 'list' | 'status' | 'stop' | 'down' | 'purge' | 'doctor' | 'ssh-install' | 'ssh-uninstall' | 'ssh-proxy' | 'tunnel' | 'refresh-gh-token' | 'refresh-gh-token-running' | 'coding-agent';
 interface ParsedCli {
   command: BoxdownCommand;
   agent?: CodingAgentCli;
   agentArgs?: string[];
   workspace?: string;
+  workspaces?: string[];
   alias?: string;
+  targets?: SshConfigInstallTarget[];
+  tunnelPorts?: TunnelPortForward[];
   recreate: boolean;
   json: boolean;
+  details?: boolean;
+  verbose: boolean;
 }
-declare const USAGE = "Usage:\n  boxdown start [--workspace <path>] [--recreate]\n  boxdown codex [--workspace <path>] [--recreate] [-- <codex args...>]\n  boxdown claude [--workspace <path>] [--recreate] [-- <claude args...>]\n  boxdown cc [--workspace <path>] [--recreate] [-- <claude args...>]\n  boxdown opencode [--workspace <path>] [--recreate] [-- <opencode args...>]\n  boxdown antigravity [--workspace <path>] [--recreate] [-- <agy args...>]\n  boxdown list [--json]\n  boxdown status [--workspace <path>] [--alias <name>] [--json]\n  boxdown stop [--workspace <path>]\n  boxdown down [--workspace <path>]\n  boxdown doctor [--workspace <path>]\n  boxdown ssh-config install [--workspace <path>] [--alias <name>]\n  boxdown ssh-proxy [--workspace <path>] [--alias <name>]\n  boxdown refresh-gh-token [--workspace <path>]\n  boxdown refresh-gh-token-running [--workspace <path>]\n\nCommands:\n  start                     Start or reuse the workspace devcontainer, then open\n                            an interactive shell inside it. Alias: shell.\n  codex                     Start or reuse the devcontainer, then launch Codex.\n  claude                    Start or reuse the devcontainer, then launch Claude\n                            Code. Alias: cc.\n  opencode                  Start or reuse the devcontainer, then launch\n                            OpenCode.\n  antigravity               Start or reuse the devcontainer, then launch\n                            Antigravity CLI (agy).\n  list                      List Boxdown-known devcontainer workspaces from any\n                            directory.\n  status                    Show workspace state, generated paths, SSH key paths,\n                            and the matching devcontainer state.\n  stop                      Stop the workspace devcontainer if it is running.\n  down                      Remove the workspace devcontainer. Keeps Boxdown\n                            cache, generated config, data, and SSH keys.\n  doctor                    Check required host tools and Boxdown assets.\n  ssh-config install        Install or update an SSH host alias for the workspace\n                            devcontainer.\n  ssh-proxy                 Internal command used by the generated SSH\n                            ProxyCommand. Starts or reuses the devcontainer and\n                            bridges SSH over docker exec.\n  refresh-gh-token          Start or reuse the devcontainer, then copy host\n                            GitHub CLI auth into the container when available.\n  refresh-gh-token-running  Refresh GitHub CLI auth only if the workspace\n                            devcontainer is already running.\n\nOptions:\n  --workspace <path>  Target project directory. Defaults to the current directory.\n  --alias <name>      SSH host alias. Defaults to <repo-name>-devcontainer.\n  --recreate          Remove the existing devcontainer before starting.\n  --json              Print JSON output. Supported by status and list.\n  --help, -h          Show help.\n";
+interface RunCliOptions {
+  promptInput?: PromptInput;
+  promptOutput?: PromptOutput;
+  env?: NodeJS.ProcessEnv;
+  runDoctorChecks?: typeof runDoctorChecks;
+  setupWorkspace?: typeof setupWorkspace;
+}
+declare const USAGE = "Usage:\n  boxdown setup [--workspace <path>] [--alias <name>] [--recreate] [--target <name>]...\n  boxdown start [--workspace <path>] [--recreate]\n  boxdown codex [--workspace <path>] [--recreate] [-- <codex args...>]\n  boxdown claude [--workspace <path>] [--recreate] [-- <claude args...>]\n  boxdown opencode [--workspace <path>] [--recreate] [-- <opencode args...>]\n  boxdown antigravity [--workspace <path>] [--recreate] [-- <agy args...>]\n  boxdown list [--details] [--json|--format json]\n  boxdown status [--workspace <path>] [--alias <name>] [--json|--format json]\n  boxdown stop [--workspace <path>]\n  boxdown down [--workspace <path>]...\n  boxdown purge [--workspace <path|ssh-alias|repo>] [--alias <name>]\n  boxdown doctor [--workspace <path>]\n  boxdown ssh install [--workspace <path>] [--alias <name>] [--target <name>]...\n  boxdown ssh uninstall [--workspace <path>] [--alias <name>]\n  boxdown ssh-proxy [--workspace <path>] [--alias <name>]\n  boxdown tunnel [--port <port>] [--port <local:remote>] [--workspace <path>] [--alias <name>]\n  boxdown refresh-gh-token [--workspace <path>]\n  boxdown refresh-gh-token-running [--workspace <path>]\n\nCommands:\n  setup                     Prepare the workspace devcontainer and SSH/app\n                            integration without opening a shell.\n  start, shell              Start or reuse the workspace devcontainer, then open\n                            an interactive shell inside it.\n  codex                     Start or reuse the devcontainer, then launch Codex.\n  claude, cc                Start or reuse the devcontainer, then launch Claude\n                            Code.\n  opencode                  Start or reuse the devcontainer, then launch\n                            OpenCode, installing it first when needed.\n  antigravity               Start or reuse the devcontainer, then launch\n                            Antigravity CLI (agy), installing it first when\n                            needed.\n  list                      List Boxdown-known devcontainer workspaces from any\n                            directory.\n  status                    Show workspace state, generated paths, SSH key paths,\n                            and the matching devcontainer state.\n  stop                      Stop the workspace devcontainer if it is running.\n  down                      Remove the workspace devcontainer. Keeps Boxdown\n                            cache, generated config, data, and SSH keys.\n  purge                     Remove the workspace devcontainer, exact Docker\n                            image, managed SSH/app config, and Boxdown\n                            cache/data for this workspace. Prompts for\n                            tracked workspaces from untracked directories.\n  doctor                    Check required host tools and Boxdown assets.\n  ssh install               Install or update an SSH host alias for the workspace\n                            devcontainer.\n  ssh uninstall             Remove Boxdown's managed SSH host alias block and\n                            matching Codex/Claude app entries.\n  ssh-proxy                 Internal command used by the generated SSH\n                            ProxyCommand. Starts or reuses the devcontainer and\n                            bridges SSH over docker exec.\n  tunnel                    Start or reuse the devcontainer, then keep an SSH\n                            local port tunnel open for host/browser access.\n  refresh-gh-token          Start or reuse the devcontainer, then copy host\n                            GitHub CLI auth into the container when available.\n  refresh-gh-token-running  Refresh GitHub CLI auth only if the workspace\n                            devcontainer is already running.\n\nOptions:\n  --workspace <path>  Target project directory. Defaults to the current directory.\n                      Repeatable with down. With purge, also accepts PATH,\n                      SSH ALIAS, or an unambiguous REPO from boxdown list.\n                      Without --workspace, purge only targets the current\n                      directory when it is tracked; otherwise interactive\n                      terminals prompt for tracked workspaces.\n  --alias <name>      SSH host alias. Defaults to <repo-name>-devcontainer.\n  --target <name>     Optional SSH install target. Repeatable. Supported by\n                      setup and ssh install: codex, claude.\n  --port <port>       Tunnel a local port to the same remote port, or use\n                      <local:remote>. Repeatable. Supported by tunnel.\n  --recreate          Remove the existing devcontainer before starting.\n  --json              Print JSON output. Supported by status and list.\n  --format json       Print JSON output. Equivalent to --json.\n  --details           Print detailed human list output. Supported by list.\n  --verbose           Stream raw Docker, devcontainer, and hook command output.\n                      Lifecycle commands append the same managed output to the\n                      per-workspace command log either way.\n  --help, -h          Show help.\n  --version, -v       Show version.\n";
 declare function commandWritesWorkspaceMetadata(command: BoxdownCommand): boolean;
 declare function parseCliArgs(argv: string[]): ParsedCli;
-declare function runCli(argv?: string[]): Promise<number>;
+declare function parseTunnelPort(value: string): TunnelPortForward;
+declare function parseTunnelPortList(value: string): TunnelPortForward[];
+interface SetupWorkspaceOptions {
+  recreate?: boolean;
+  targets?: SshConfigInstallTarget[];
+  progress?: ProgressReporter;
+  logger?: WorkspaceCommandLogger;
+  start?: typeof startDevcontainer;
+  installSsh?: typeof installSshConfig;
+  installTarget?: typeof installSshInstallTarget;
+}
+declare function setupWorkspace(context: WorkspaceContext, alias: string, options?: SetupWorkspaceOptions): Promise<void>;
+declare function runCli(argv?: string[], options?: RunCliOptions): Promise<number>;
 //#endregion
-export { BoxdownCommand, ParsedCli, USAGE, commandWritesWorkspaceMetadata, parseCliArgs, runCli };
+export { BoxdownCommand, ParsedCli, RunCliOptions, USAGE, commandWritesWorkspaceMetadata, parseCliArgs, parseTunnelPort, parseTunnelPortList, runCli, setupWorkspace };
 //# sourceMappingURL=main.d.mts.map

package/dist/main.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.mts","names":[],"sources":["../src/coding-agents.ts","../src/main.ts"],"mappings":";KAAY,cAAA;AAAA,KACA,uBAAA,GAA0B,cAAA;AAAA,iBAUtB,sBAAA,CAAwB,OAAA,WAAkB,cAAA;AAAA,iBAI1C,iBAAA,CAAmB,KAAA,EAAO,cAAA;;;KCJ9B,cAAA;AAAA,UAcK,SAAA;EACf,OAAA,EAAS,cAAA;EACT,KAAA,GAAQ,cAAA;EACR,SAAA;EACA,SAAA;EACA,KAAA;EACA,QAAA;EACA,IAAA;AAAA;AAAA,cAGW,KAAA;AAAA,iBAqDG,8BAAA,CAAgC,OAAA,EAAS,cAAA;AAAA,iBAWzC,YAAA,CAAc,IAAA,aAAiB,SAAA;AAAA,iBAoJzB,MAAA,CAAQ,IAAA,cAAyC,OAAA"}
+{"version":3,"file":"main.d.mts","names":[],"sources":["../src/coding-agents.ts","../src/paths.ts","../src/doctor.ts","../src/logging.ts","../src/process.ts","../src/progress.ts","../src/status.ts","../src/devcontainer.ts","../src/cli-style.ts","../src/interactive-prompts.ts","../src/ssh-config.ts","../src/ssh-install-targets.ts","../src/main.ts"],"mappings":"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"}

package/dist/main.mjs

@@ -1,3 +1,3 @@
-import { i as runCli, n as commandWritesWorkspaceMetadata, r as parseCliArgs, t as USAGE } from "./main-ZFTrSVgt.mjs";
+import { a as parseTunnelPortList, i as parseTunnelPort, n as commandWritesWorkspaceMetadata, o as runCli, r as parseCliArgs, s as setupWorkspace, t as USAGE } from "./main-XMBsKjIK.mjs";
 
-export { USAGE, commandWritesWorkspaceMetadata, parseCliArgs, runCli };
+export { USAGE, commandWritesWorkspaceMetadata, parseCliArgs, parseTunnelPort, parseTunnelPortList, runCli, setupWorkspace };

package/docs/README.md

@@ -19,6 +19,7 @@ repository.
 ## Feature Docs
 
 - [Feature index](./features/README.md)
+- [Setup command](./features/setup.md)
 - [Start command](./features/start-and-shell.md)
 - [Lifecycle commands](./features/lifecycle.md)
 - [SSH config and proxy workflow](./features/ssh-config-and-proxy.md)

package/docs/architecture.md

@@ -38,6 +38,28 @@ Per-workspace state is keyed by a hash of the resolved workspace path. This
 prevents collisions between repositories with the same basename in different
 folders.
 
+## External App Integrations
+
+External app configuration is optional. `boxdown setup` and `boxdown ssh
+install` ask about optional targets in interactive terminals, while
+non-interactive runs skip them unless `--target` is provided. For example,
+`boxdown setup --target codex` or `boxdown ssh install --target codex` writes
+Codex app remote project configuration under `~/.codex/codex-app/config.json`,
+and `--target claude` writes Claude app SSH remote configuration under
+`~/Library/Application Support/Claude/ssh_configs.json`, but neither file
+becomes Boxdown workspace state.
+
+Boxdown writes the Codex app config entry needed to point Codex at the
+Boxdown-managed SSH alias and canonical container-side project path,
+`/workspaces/<repo-name>`. On install, it migrates matching older
+`/home/node/<repo-name>` project entries for the same alias. On uninstall, it
+removes matching Codex app/sidebar entries for both the canonical and legacy
+paths. Other Codex global state remains Codex-owned.
+
+Boxdown writes the Claude SSH remote entry needed to point Claude at the same
+Boxdown-managed SSH alias. On uninstall, it removes that matching Claude SSH
+remote and trusted-host entry.
+
 ## Container Asset Mounts
 
 The generated config mounts `assets/devcontainer/` read-only into the container
@@ -47,6 +69,10 @@ When the host has `~/.agents`, the generated config also mounts it read-only at
 `/home/node/.agents` so host-global agent configuration is available inside the
 container without being copied into target repositories.
 
+When the host has file-backed Codex auth at `~/.codex/auth.json`, the generated
+config mounts that single file read-only at `/home/node/.codex/auth.json`. It
+does not mount the full host `~/.codex` directory.
+
 The container receives only a public SSH key mount. The private host key stays
 on the host and is referenced from the user's SSH config.
 
@@ -58,6 +84,12 @@ shared mounted utility: post-create runs an immediate install/update, while
 post-start and SSH proxy setup run throttled best-effort refreshes for
 already-running containers.
 
+Baseline Python is also lifecycle-owned. The devcontainer installs Debian
+`python3`, `python3-venv`, `python3-pip`, and `pipx` during post-create instead
+of using the Dev Containers Python feature, which keeps the image layer smaller
+and avoids shipping Python dev-tool virtualenvs in every container. uv remains a
+separate feature and does not provide the system Python runtime by default.
+
 Tool refreshes are container-side behavior, not generated config schema.
 Failures should warn without making the devcontainer unusable. SSH proxy
 refresh output must stay off stdout because stdout carries SSH traffic. Locking

package/docs/development.md

@@ -3,7 +3,7 @@
 ## Requirements
 
 - Node.js 24 or newer.
-- pnpm 10.26 or newer.
+- pnpm 11 or newer.
 - Docker for manual container workflow testing.
 - OpenSSH tools for SSH config and proxy testing.
 - GitHub CLI for `refresh-gh-token` workflow testing.
@@ -20,8 +20,9 @@ Run the CLI from source:
 
 ```sh
 pnpm run start -- --help
+pnpm run start -- setup --workspace /path/to/project
 pnpm run start -- start --workspace /path/to/project
-pnpm run start -- ssh-config install --workspace /path/to/project
+pnpm run start -- ssh install --workspace /path/to/project
 ```
 
 The published binary is `boxdown`, but local development goes through
@@ -51,9 +52,15 @@ Use `--workspace` while developing so you do not accidentally target the
 Boxdown repo itself:
 
 ```sh
-pnpm run start -- start --workspace ~/projects/repos/example
-pnpm run start -- ssh-config install --workspace ~/projects/repos/example
+pnpm run start -- setup --workspace ~/projects/repos/example
+pnpm run start -- setup --workspace ~/projects/repos/example --target codex
+pnpm run start -- setup --workspace ~/projects/repos/example --target claude
 ```
 
-Starting a real container writes Boxdown state under user cache/data directories
-and may pull images or install the Dev Containers CLI.
+In an interactive terminal, `ssh install` asks whether to install optional SSH
+targets. Add `--target codex` or `--target claude` when testing an app target
+explicitly, or set `CI=1` when you want to exercise the non-interactive skip
+path.
+
+Setting up a real container writes Boxdown state under user cache/data
+directories and may pull images or install the Dev Containers CLI.