boxdown 1.0.0

package/src/main.ts

@@ -0,0 +1,362 @@
+import { existsSync } from 'node:fs'
+
+import { codingAgentFromCommand, type CodingAgentCli } from './coding-agents.ts'
+import { doctorHasFailures, formatDoctorText, runDoctorChecks } from './doctor.ts'
+import { startDevcontainer, printPortHint, openShell, openCodingAgentCli, ensureContainerSshRuntime, runSshdProxy, refreshContainerGhAuth, refreshContainerCodingAgentClis, findRunningContainerId, findWorkspaceContainer, stopWorkspaceContainer, removeWorkspaceContainer, listWorkspaceContainers } from './devcontainer.ts'
+import { createWorkspaceListEntries, formatWorkspaceListText } from './list.ts'
+import { listWorkspaceMetadata, writeWorkspaceMetadata } from './metadata.ts'
+import { createWorkspaceContext, defaultDataRoot } from './paths.ts'
+import { defaultSshAlias, installSshConfig } from './ssh-config.ts'
+import { createStatusInfo, formatStatusText, statusIsHealthy } from './status.ts'
+
+export type BoxdownCommand =
+  | 'help'
+  | 'start'
+  | 'list'
+  | 'status'
+  | 'stop'
+  | 'down'
+  | 'doctor'
+  | 'ssh-config-install'
+  | 'ssh-proxy'
+  | 'refresh-gh-token'
+  | 'refresh-gh-token-running'
+  | 'coding-agent'
+
+export interface ParsedCli {
+  command: BoxdownCommand
+  agent?: CodingAgentCli
+  agentArgs?: string[]
+  workspace?: string
+  alias?: string
+  recreate: boolean
+  json: boolean
+}
+
+export const USAGE = `Usage:
+  boxdown start [--workspace <path>] [--recreate]
+  boxdown codex [--workspace <path>] [--recreate] [-- <codex args...>]
+  boxdown claude [--workspace <path>] [--recreate] [-- <claude args...>]
+  boxdown cc [--workspace <path>] [--recreate] [-- <claude args...>]
+  boxdown opencode [--workspace <path>] [--recreate] [-- <opencode args...>]
+  boxdown antigravity [--workspace <path>] [--recreate] [-- <agy args...>]
+  boxdown list [--json]
+  boxdown status [--workspace <path>] [--alias <name>] [--json]
+  boxdown stop [--workspace <path>]
+  boxdown down [--workspace <path>]
+  boxdown doctor [--workspace <path>]
+  boxdown ssh-config install [--workspace <path>] [--alias <name>]
+  boxdown ssh-proxy [--workspace <path>] [--alias <name>]
+  boxdown refresh-gh-token [--workspace <path>]
+  boxdown refresh-gh-token-running [--workspace <path>]
+
+Commands:
+  start                     Start or reuse the workspace devcontainer, then open
+                            an interactive shell inside it. Alias: shell.
+  codex                     Start or reuse the devcontainer, then launch Codex.
+  claude                    Start or reuse the devcontainer, then launch Claude
+                            Code. Alias: cc.
+  opencode                  Start or reuse the devcontainer, then launch
+                            OpenCode.
+  antigravity               Start or reuse the devcontainer, then launch
+                            Antigravity CLI (agy).
+  list                      List Boxdown-known devcontainer workspaces from any
+                            directory.
+  status                    Show workspace state, generated paths, SSH key paths,
+                            and the matching devcontainer state.
+  stop                      Stop the workspace devcontainer if it is running.
+  down                      Remove the workspace devcontainer. Keeps Boxdown
+                            cache, generated config, data, and SSH keys.
+  doctor                    Check required host tools and Boxdown assets.
+  ssh-config install        Install or update an SSH host alias for the workspace
+                            devcontainer.
+  ssh-proxy                 Internal command used by the generated SSH
+                            ProxyCommand. Starts or reuses the devcontainer and
+                            bridges SSH over docker exec.
+  refresh-gh-token          Start or reuse the devcontainer, then copy host
+                            GitHub CLI auth into the container when available.
+  refresh-gh-token-running  Refresh GitHub CLI auth only if the workspace
+                            devcontainer is already running.
+
+Options:
+  --workspace <path>  Target project directory. Defaults to the current directory.
+  --alias <name>      SSH host alias. Defaults to <repo-name>-devcontainer.
+  --recreate          Remove the existing devcontainer before starting.
+  --json              Print JSON output. Supported by status and list.
+  --help, -h          Show help.
+`
+
+export function commandWritesWorkspaceMetadata (command: BoxdownCommand): boolean {
+  return [
+    'start',
+    'ssh-config-install',
+    'ssh-proxy',
+    'refresh-gh-token',
+    'refresh-gh-token-running',
+    'coding-agent'
+  ].includes(command)
+}
+
+export function parseCliArgs (argv: string[]): ParsedCli {
+  const args = [...argv]
+  let workspace: string | undefined
+  let alias: string | undefined
+  let recreate = false
+  let json = false
+  let passthroughArgs: string[] | undefined
+  const positional: string[] = []
+
+  function parsed (command: BoxdownCommand): ParsedCli {
+    if (json && command !== 'status' && command !== 'list') {
+      throw new Error('--json is only supported with status and list')
+    }
+
+    if (passthroughArgs !== undefined) {
+      throw new Error('-- passthrough is only supported with coding-agent commands')
+    }
+
+    return { command, workspace, alias, recreate, json }
+  }
+
+  function parsedCodingAgent (agent: CodingAgentCli): ParsedCli {
+    if (json) {
+      throw new Error('--json is only supported with status and list')
+    }
+
+    return {
+      command: 'coding-agent',
+      agent,
+      agentArgs: passthroughArgs ?? [],
+      workspace,
+      alias,
+      recreate,
+      json
+    }
+  }
+
+  while (args.length > 0) {
+    const arg = args.shift()
+
+    if (arg === undefined) {
+      break
+    }
+
+    if (arg === '--') {
+      passthroughArgs = args.splice(0)
+      break
+    }
+
+    if (arg === '--help' || arg === '-h') {
+      return parsed('help')
+    }
+
+    if (arg === '--workspace') {
+      const value = args.shift()
+      if (value === undefined) {
+        throw new Error('--workspace requires a value')
+      }
+      workspace = value
+      continue
+    }
+
+    if (arg === '--alias') {
+      const value = args.shift()
+      if (value === undefined) {
+        throw new Error('--alias requires a value')
+      }
+      alias = value
+      continue
+    }
+
+    if (arg === '--recreate') {
+      recreate = true
+      continue
+    }
+
+    if (arg === '--json') {
+      json = true
+      continue
+    }
+
+    if (arg.startsWith('-')) {
+      throw new Error(`Unknown option: ${arg}`)
+    }
+
+    positional.push(arg)
+  }
+
+  if (positional.length === 0) {
+    return parsed('help')
+  }
+
+  if (positional[0] === 'start' || positional[0] === 'shell') {
+    return parsed('start')
+  }
+
+  const codingAgent = codingAgentFromCommand(positional[0] ?? '')
+  if (codingAgent !== undefined) {
+    if (positional.length > 1) {
+      throw new Error('Coding-agent CLI arguments must come after --')
+    }
+
+    return parsedCodingAgent(codingAgent)
+  }
+
+  if (positional[0] === 'list' && positional.length === 1) {
+    return parsed('list')
+  }
+
+  if (positional[0] === 'status' && positional.length === 1) {
+    return parsed('status')
+  }
+
+  if (positional[0] === 'stop' && positional.length === 1) {
+    return parsed('stop')
+  }
+
+  if (positional[0] === 'down' && positional.length === 1) {
+    return parsed('down')
+  }
+
+  if (positional[0] === 'doctor' && positional.length === 1) {
+    return parsed('doctor')
+  }
+
+  if (positional[0] === 'ssh-config') {
+    if (positional.length === 1 || (positional[1] === 'install' && positional.length === 2)) {
+      return parsed('ssh-config-install')
+    }
+
+    throw new Error(`Unknown ssh-config command: ${positional.slice(1).join(' ')}. Usage: boxdown ssh-config [install] [--workspace <path>] [--alias <name>]`)
+  }
+
+  if (positional[0] === 'ssh-proxy' && positional.length === 1) {
+    return parsed('ssh-proxy')
+  }
+
+  if (positional[0] === 'refresh-gh-token' && positional.length === 1) {
+    return parsed('refresh-gh-token')
+  }
+
+  if (positional[0] === 'refresh-gh-token-running' && positional.length === 1) {
+    return parsed('refresh-gh-token-running')
+  }
+
+  throw new Error(`Unknown command: ${positional.join(' ')}`)
+}
+
+export async function runCli (argv: string[] = process.argv.slice(2)): Promise<number> {
+  try {
+    const parsed = parseCliArgs(argv)
+
+    if (parsed.command === 'help') {
+      process.stdout.write(USAGE)
+      return 0
+    }
+
+    if (parsed.command === 'list') {
+      const metadata = listWorkspaceMetadata(defaultDataRoot())
+      const containers = await listWorkspaceContainers()
+      const entries = createWorkspaceListEntries(metadata, containers, existsSync)
+
+      if (parsed.json) {
+        process.stdout.write(`${JSON.stringify(entries, null, 2)}\n`)
+      } else {
+        process.stdout.write(formatWorkspaceListText(entries))
+      }
+
+      return 0
+    }
+
+    const context = createWorkspaceContext({ workspace: parsed.workspace })
+    const alias = parsed.alias ?? defaultSshAlias(context.workspaceBasename)
+    const aliasSource = parsed.alias === undefined ? 'default' : 'provided'
+
+    if (commandWritesWorkspaceMetadata(parsed.command)) {
+      writeWorkspaceMetadata(context, alias)
+    }
+
+    if (parsed.command === 'ssh-config-install') {
+      await installSshConfig(context, alias)
+      return 0
+    }
+
+    if (parsed.command === 'status') {
+      const container = await findWorkspaceContainer(context)
+      const status = createStatusInfo(context, alias, container, existsSync, { aliasSource })
+
+      if (parsed.json) {
+        process.stdout.write(`${JSON.stringify(status, null, 2)}\n`)
+      } else {
+        process.stdout.write(formatStatusText(status, { color: true }))
+      }
+
+      return statusIsHealthy(status) ? 0 : 1
+    }
+
+    if (parsed.command === 'stop') {
+      await stopWorkspaceContainer(context)
+      return 0
+    }
+
+    if (parsed.command === 'down') {
+      await removeWorkspaceContainer(context)
+      return 0
+    }
+
+    if (parsed.command === 'doctor') {
+      const checks = await runDoctorChecks(context)
+      process.stdout.write(formatDoctorText(checks))
+      return doctorHasFailures(checks) ? 1 : 0
+    }
+
+    if (!existsSync(context.assetsDevcontainerDir)) {
+      throw new Error(`Missing Boxdown devcontainer assets: ${context.assetsDevcontainerDir}`)
+    }
+
+    if (parsed.command === 'ssh-proxy') {
+      await installSshConfig(context, alias, { quiet: true })
+      const containerId = await startDevcontainer(context, {
+        recreate: parsed.recreate,
+        proxyMode: true,
+        reuseRunning: true
+      })
+      await refreshContainerCodingAgentClis(context, true)
+      await ensureContainerSshRuntime(context)
+      return runSshdProxy(containerId)
+    }
+
+    if (parsed.command === 'refresh-gh-token-running') {
+      const containerId = await findRunningContainerId(context)
+      if (containerId === undefined) {
+        throw new Error(`No running devcontainer found for: ${context.workspaceFolder}`)
+      }
+      await refreshContainerGhAuth(context)
+      return 0
+    }
+
+    if (parsed.command === 'refresh-gh-token') {
+      await startDevcontainer(context)
+      await refreshContainerGhAuth(context)
+      return 0
+    }
+
+    if (parsed.command === 'coding-agent') {
+      const agent = parsed.agent
+      if (agent === undefined) {
+        throw new Error('Missing coding-agent command')
+      }
+
+      await startDevcontainer(context, { recreate: parsed.recreate })
+      await refreshContainerCodingAgentClis(context, false, [agent])
+      return openCodingAgentCli(context, agent, parsed.agentArgs ?? [])
+    }
+
+    const containerId = await startDevcontainer(context, { recreate: parsed.recreate })
+    await printPortHint(context, containerId)
+    return openShell(context)
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+    return 1
+  }
+}

package/src/metadata.ts

@@ -0,0 +1,84 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { WorkspaceContext } from './paths.ts'
+
+export const WORKSPACE_METADATA_VERSION = 1
+
+export interface WorkspaceMetadata {
+  version: 1
+  workspaceId: string
+  workspaceFolder: string
+  workspaceBasename: string
+  sshAlias: string
+  firstSeenAt: string
+  lastSeenAt: string
+}
+
+function isWorkspaceMetadata (value: unknown): value is WorkspaceMetadata {
+  if (value === null || typeof value !== 'object') {
+    return false
+  }
+
+  const candidate = value as Record<string, unknown>
+
+  return candidate.version === WORKSPACE_METADATA_VERSION &&
+    typeof candidate.workspaceId === 'string' &&
+    typeof candidate.workspaceFolder === 'string' &&
+    typeof candidate.workspaceBasename === 'string' &&
+    typeof candidate.sshAlias === 'string' &&
+    typeof candidate.firstSeenAt === 'string' &&
+    typeof candidate.lastSeenAt === 'string'
+}
+
+export function workspaceMetadataPath (context: WorkspaceContext): string {
+  return join(context.workspaceDataDir, 'metadata.json')
+}
+
+export function readWorkspaceMetadataFile (path: string): WorkspaceMetadata {
+  const parsed = JSON.parse(readFileSync(path, 'utf8')) as unknown
+
+  if (!isWorkspaceMetadata(parsed)) {
+    throw new Error(`Invalid Boxdown workspace metadata: ${path}`)
+  }
+
+  return parsed
+}
+
+export function writeWorkspaceMetadata (context: WorkspaceContext, sshAlias: string, now = new Date()): WorkspaceMetadata {
+  const metadataPath = workspaceMetadataPath(context)
+  const timestamp = now.toISOString()
+  let firstSeenAt = timestamp
+
+  if (existsSync(metadataPath)) {
+    firstSeenAt = readWorkspaceMetadataFile(metadataPath).firstSeenAt
+  }
+
+  const metadata: WorkspaceMetadata = {
+    version: WORKSPACE_METADATA_VERSION,
+    workspaceId: context.workspaceId,
+    workspaceFolder: context.workspaceFolder,
+    workspaceBasename: context.workspaceBasename,
+    sshAlias,
+    firstSeenAt,
+    lastSeenAt: timestamp
+  }
+
+  mkdirSync(context.workspaceDataDir, { recursive: true })
+  writeFileSync(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`)
+  return metadata
+}
+
+export function listWorkspaceMetadata (dataRoot: string): WorkspaceMetadata[] {
+  const workspacesDir = join(dataRoot, 'workspaces')
+
+  if (!existsSync(workspacesDir)) {
+    return []
+  }
+
+  return readdirSync(workspacesDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => join(workspacesDir, entry.name, 'metadata.json'))
+    .filter((metadataPath) => existsSync(metadataPath))
+    .map((metadataPath) => readWorkspaceMetadataFile(metadataPath))
+}

package/src/paths.ts

@@ -0,0 +1,117 @@
+import { createHash } from 'node:crypto'
+import { existsSync, realpathSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { basename, dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { PACKAGE_NAME } from './constants.ts'
+
+export interface WorkspaceContextOptions {
+  workspace?: string
+  cwd?: string
+  env?: NodeJS.ProcessEnv
+  packageRoot?: string
+  assetsDevcontainerDir?: string
+}
+
+export interface WorkspaceContext {
+  workspaceFolder: string
+  workspaceBasename: string
+  workspaceId: string
+  packageRoot: string
+  assetsDevcontainerDir: string
+  cacheRoot: string
+  dataRoot: string
+  workspaceCacheDir: string
+  workspaceDataDir: string
+  generatedConfigPath: string
+  hostAgentsDir: string
+  sshKeyDir: string
+  sshKeyPath: string
+  sshPublicKeyPath: string
+  sshPublicKeyRuntimeDir: string
+  sshPublicKeyRuntimePath: string
+}
+
+export function packageRootFromImportMeta (importMetaUrl = import.meta.url): string {
+  return dirname(dirname(fileURLToPath(importMetaUrl)))
+}
+
+export function workspaceIdFor (workspaceFolder: string): string {
+  return createHash('sha256').update(workspaceFolder).digest('hex').slice(0, 16)
+}
+
+export function resolveWorkspaceFolder (workspace: string | undefined, cwd = process.cwd()): string {
+  const candidate = resolve(cwd, workspace ?? '.')
+
+  if (!existsSync(candidate)) {
+    throw new Error(`Workspace does not exist: ${candidate}`)
+  }
+
+  if (!statSync(candidate).isDirectory()) {
+    throw new Error(`Workspace is not a directory: ${candidate}`)
+  }
+
+  return realpathSync(candidate)
+}
+
+export function defaultCacheRoot (env: NodeJS.ProcessEnv = process.env): string {
+  if (env.BOXDOWN_CACHE_HOME) {
+    return env.BOXDOWN_CACHE_HOME
+  }
+
+  if (env.XDG_CACHE_HOME) {
+    return join(env.XDG_CACHE_HOME, PACKAGE_NAME)
+  }
+
+  return join(homedir(), '.cache', PACKAGE_NAME)
+}
+
+export function defaultDataRoot (env: NodeJS.ProcessEnv = process.env): string {
+  if (env.BOXDOWN_DATA_HOME) {
+    return env.BOXDOWN_DATA_HOME
+  }
+
+  if (env.XDG_DATA_HOME) {
+    return join(env.XDG_DATA_HOME, PACKAGE_NAME)
+  }
+
+  return join(homedir(), '.local', 'share', PACKAGE_NAME)
+}
+
+export function defaultHostAgentsDir (env: NodeJS.ProcessEnv = process.env): string {
+  return join(env.HOME ?? homedir(), '.agents')
+}
+
+export function createWorkspaceContext (options: WorkspaceContextOptions = {}): WorkspaceContext {
+  const env = options.env ?? process.env
+  const workspaceFolder = resolveWorkspaceFolder(options.workspace, options.cwd)
+  const workspaceBasename = basename(workspaceFolder)
+  const workspaceId = workspaceIdFor(workspaceFolder)
+  const packageRoot = options.packageRoot ?? packageRootFromImportMeta()
+  const assetsDevcontainerDir = options.assetsDevcontainerDir ?? env.BOXDOWN_DEVCONTAINER_ASSETS_DIR ?? join(packageRoot, 'assets', 'devcontainer')
+  const cacheRoot = defaultCacheRoot(env)
+  const dataRoot = defaultDataRoot(env)
+  const hostAgentsDir = defaultHostAgentsDir(env)
+  const workspaceCacheDir = join(cacheRoot, 'workspaces', workspaceId)
+  const workspaceDataDir = join(dataRoot, 'workspaces', workspaceId)
+
+  return {
+    workspaceFolder,
+    workspaceBasename,
+    workspaceId,
+    packageRoot,
+    assetsDevcontainerDir,
+    cacheRoot,
+    dataRoot,
+    workspaceCacheDir,
+    workspaceDataDir,
+    generatedConfigPath: join(workspaceCacheDir, 'devcontainer.json'),
+    hostAgentsDir,
+    sshKeyDir: join(workspaceDataDir, 'ssh'),
+    sshKeyPath: join(workspaceDataDir, 'ssh', 'id_ed25519'),
+    sshPublicKeyPath: join(workspaceDataDir, 'ssh', 'id_ed25519.pub'),
+    sshPublicKeyRuntimeDir: join(workspaceDataDir, 'ssh-public'),
+    sshPublicKeyRuntimePath: join(workspaceDataDir, 'ssh-public', 'id_ed25519.pub')
+  }
+}

package/src/process.ts

@@ -0,0 +1,94 @@
+import { spawn } from 'node:child_process'
+
+export interface BufferedCommandOptions {
+  cwd?: string
+  env?: NodeJS.ProcessEnv
+  input?: string
+  mirrorStdout?: 'stdout' | 'stderr' | false
+  mirrorStderr?: 'stdout' | 'stderr' | false
+}
+
+export interface CommandResult {
+  code: number
+  stdout: string
+  stderr: string
+}
+
+function mergedEnv (env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  return {
+    ...process.env,
+    ...(env ?? {})
+  }
+}
+
+function writeChunk (target: 'stdout' | 'stderr' | false, chunk: Buffer): void {
+  if (target === 'stdout') {
+    process.stdout.write(chunk)
+  } else if (target === 'stderr') {
+    process.stderr.write(chunk)
+  }
+}
+
+export function runBuffered (command: string, args: string[], options: BufferedCommandOptions = {}): Promise<CommandResult> {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: mergedEnv(options.env),
+      stdio: ['pipe', 'pipe', 'pipe']
+    })
+
+    const stdoutChunks: Buffer[] = []
+    const stderrChunks: Buffer[] = []
+
+    child.stdout.on('data', (chunk: Buffer) => {
+      stdoutChunks.push(chunk)
+      writeChunk(options.mirrorStdout ?? 'stdout', chunk)
+    })
+
+    child.stderr.on('data', (chunk: Buffer) => {
+      stderrChunks.push(chunk)
+      writeChunk(options.mirrorStderr ?? 'stderr', chunk)
+    })
+
+    child.on('error', (error) => {
+      resolve({
+        code: 127,
+        stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+        stderr: `${Buffer.concat(stderrChunks).toString('utf8')}${error.message}\n`
+      })
+    })
+
+    child.on('close', (code) => {
+      resolve({
+        code: code ?? 1,
+        stdout: Buffer.concat(stdoutChunks).toString('utf8'),
+        stderr: Buffer.concat(stderrChunks).toString('utf8')
+      })
+    })
+
+    if (options.input !== undefined) {
+      child.stdin.end(options.input)
+    } else {
+      child.stdin.end()
+    }
+  })
+}
+
+export function runInteractive (command: string, args: string[], options: Pick<BufferedCommandOptions, 'cwd' | 'env'> = {}): Promise<number> {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: mergedEnv(options.env),
+      stdio: 'inherit'
+    })
+
+    child.on('error', (error) => {
+      process.stderr.write(`${error.message}\n`)
+      resolve(127)
+    })
+
+    child.on('close', (code) => {
+      resolve(code ?? 1)
+    })
+  })
+}