@doriandev/devcc 0.1.2 → 0.3.0

package/src/devcc/automation.ts

@@ -0,0 +1,409 @@
+import { spawn } from "node:child_process"
+import { writeFileSync } from "node:fs"
+import { basename, join } from "node:path"
+import { createAgentAdapters } from "./agents/agents.js"
+import { loadConfig, loadConfigFile, type LoadedConfig } from "./core/config.js"
+import { EnvironmentService, type EnvironmentSnapshot } from "./environment/EnvironmentService.js"
+import { GitService } from "./git/GitService.js"
+import { worktreeLabel } from "./git/worktrees.js"
+import { detectProject, renderStarterConfig, starterConfig } from "./init/detect.js"
+import { buildSetupPrompt } from "./init/prompt.js"
+import { errorMessage } from "./utils/errors.js"
+import { pluralise } from "./utils/format.js"
+import { createLogger } from "./utils/logger.js"
+import { detectPackageManager, readPackageJson, readScripts } from "./utils/packageManager.js"
+import { tildify } from "./utils/paths.js"
+import {
+  createSpawnExecutor,
+  isVerifyIssue,
+  resolveVerifySteps,
+  runVerification,
+  summariseVerify,
+  type StepExecutor,
+  type VerifyReport,
+} from "./verify/verify.js"
+
+/**
+ * Non-interactive commands for scripts and AI agents: `devcc verify`,
+ * `devcc worktree list`, `devcc env`. None of them load the TUI, so they run on
+ * plain Node without FFI. With `--json`, stdout carries exactly one JSON
+ * document and nothing else; diagnostics go to stderr.
+ */
+
+export interface AutomationIo {
+  stdout: (text: string) => void
+  stderr: (text: string) => void
+}
+
+export interface AutomationOptions {
+  rootDir: string
+  json: boolean
+  io?: AutomationIo
+  /** Injected for tests; defaults to spawning each step. */
+  executor?: StepExecutor
+  signal?: AbortSignal
+}
+
+export const EXIT_OK = 0
+export const EXIT_FAILED = 1
+/** Misconfiguration or misuse: nothing was verified. */
+export const EXIT_USAGE = 2
+
+const processIo: AutomationIo = {
+  stdout: (text) => process.stdout.write(text),
+  stderr: (text) => process.stderr.write(text),
+}
+
+function printJson(io: AutomationIo, value: unknown): void {
+  io.stdout(`${JSON.stringify(value, null, 2)}\n`)
+}
+
+// ---------------------------------------------------------------------------
+// devcc verify
+// ---------------------------------------------------------------------------
+
+export async function verifyCommand(options: AutomationOptions): Promise<number> {
+  const io = options.io ?? processIo
+  const { rootDir, json } = options
+
+  const packageJson = readPackageJson(rootDir)
+  const packageManager = detectPackageManager({ rootDir, packageJson, userAgent: undefined }).manager
+  const loaded = await loadConfig(rootDir)
+  const { steps, issues } = resolveVerifySteps(loaded.config.verify, {
+    commands: loaded.config.commands,
+    scripts: readScripts(packageJson),
+    packageManager,
+  })
+
+  // A dropped or unresolvable verify entry must fail the gate: silently running
+  // fewer checks than configured would let a broken project pass.
+  const blocking = [
+    ...loaded.issues.filter((issue) => issue.startsWith("Failed to load") || isVerifyIssue(issue)),
+    ...issues,
+  ]
+  if (steps.length === 0 && blocking.length === 0) {
+    blocking.push(
+      loaded.filePath
+        ? `No verification steps: add verify: ["lint", "test"] to ${tildify(loaded.filePath)}`
+        : 'No verification steps: create .devcc.ts with verify: ["lint", "test"]',
+    )
+  }
+  if (blocking.length > 0) {
+    if (json) printJson(io, { ok: false, error: "configuration", issues: blocking })
+    else for (const issue of blocking) io.stderr(`devcc verify: ${issue}\n`)
+    return EXIT_USAGE
+  }
+
+  if (!json) io.stdout(`devcc verify · ${tildify(rootDir)} · ${steps.length} step(s)\n\n`)
+
+  const executor = options.executor ?? createSpawnExecutor({ rootDir })
+  let printed = 0
+  const report = await runVerification(steps, executor, {
+    signal: options.signal,
+    onProgress: (progress) => {
+      if (json) return
+      for (; printed < progress.length; printed += 1) {
+        const step = progress[printed]
+        if (!step || step.status === "pending") break
+        if (step.status === "running") {
+          io.stdout(`→ ${step.name}: ${[step.command, ...step.args].join(" ")}\n`)
+          break
+        }
+        io.stdout(stepLine(step))
+        if (step.status === "failed") io.stdout(failureOutput(step))
+      }
+    },
+  })
+
+  if (json) {
+    printJson(io, { ...report, rootDir, summary: summariseVerify(report) })
+  } else {
+    for (const step of report.steps.slice(printed)) if (step.status === "skipped") io.stdout(stepLine(step))
+    io.stdout(`\n${report.ok ? "✓" : "✗"} ${summariseVerify(report)} in ${seconds(report.durationMs)}\n`)
+  }
+  return report.ok ? EXIT_OK : EXIT_FAILED
+}
+
+function stepLine(step: VerifyReport["steps"][number]): string {
+  const mark = step.status === "passed" ? "✓" : step.status === "skipped" ? "-" : "✗"
+  const detail =
+    step.status === "skipped"
+      ? "skipped"
+      : [
+          seconds(step.durationMs),
+          step.exitCode !== null && step.exitCode !== 0 ? `exit ${step.exitCode}` : undefined,
+          step.error,
+        ]
+          .filter(Boolean)
+          .join(" · ")
+  return `${mark} ${step.name} (${detail})\n`
+}
+
+/** The tail of a failed step's output, indented under it. */
+function failureOutput(step: VerifyReport["steps"][number], maxLines = 60): string {
+  const text = [step.stdout, step.stderr]
+    .filter((part) => part.trim() !== "")
+    .join("\n")
+    .trimEnd()
+  if (text === "") return ""
+  const lines = text.split("\n")
+  const shown = lines.slice(-maxLines)
+  const header = lines.length > maxLines ? [`… ${lines.length - maxLines} earlier line(s) omitted`] : []
+  return `${[...header, ...shown].map((line) => `    ${line}`).join("\n")}\n`
+}
+
+function seconds(ms: number): string {
+  return `${(ms / 1000).toFixed(1)}s`
+}
+
+// ---------------------------------------------------------------------------
+// devcc worktree list
+// ---------------------------------------------------------------------------
+
+export async function worktreeListCommand(options: AutomationOptions): Promise<number> {
+  const io = options.io ?? processIo
+  const git = new GitService({ rootDir: options.rootDir, logger: createLogger(options.rootDir).child("git") })
+  try {
+    const worktrees = await git.listWorktrees()
+    if (options.json) {
+      printJson(io, { rootDir: options.rootDir, worktrees })
+      return EXIT_OK
+    }
+    const width = Math.max(...worktrees.map((worktree) => worktreeLabel(worktree).length), 6)
+    for (const worktree of worktrees) {
+      const flags = [
+        worktree.isMain ? "main" : undefined,
+        worktree.locked ? "locked" : undefined,
+        worktree.prunable ? "prunable" : undefined,
+      ].filter(Boolean)
+      io.stdout(
+        `${worktree.isCurrent ? "*" : " "} ${worktreeLabel(worktree).padEnd(width)}  ${tildify(worktree.path)}${
+          flags.length > 0 ? `  [${flags.join(", ")}]` : ""
+        }\n`,
+      )
+    }
+    return EXIT_OK
+  } catch (error) {
+    const message = errorMessage(error)
+    if (options.json) printJson(io, { error: message, rootDir: options.rootDir, worktrees: [] })
+    else io.stderr(`devcc worktree list: ${message}\n`)
+    return EXIT_FAILED
+  }
+}
+
+// ---------------------------------------------------------------------------
+// devcc env
+// ---------------------------------------------------------------------------
+
+export async function envCommand(
+  options: AutomationOptions & { environment?: EnvironmentService },
+): Promise<number> {
+  const io = options.io ?? processIo
+  const environment = options.environment ?? new EnvironmentService({ rootDir: options.rootDir })
+  const snapshot = await environment.refresh()
+  if (options.json) {
+    const { checking: _checking, ...rest } = snapshot
+    printJson(io, { rootDir: options.rootDir, ...rest })
+  } else {
+    io.stdout(formatEnvironment(snapshot))
+  }
+  return EXIT_OK
+}
+
+export function formatEnvironment(snapshot: EnvironmentSnapshot): string {
+  const lines: string[] = ["TOOLS"]
+  const nameWidth = Math.max(...snapshot.tools.map((tool) => tool.name.length), 4) + 2
+  for (const tool of snapshot.tools) {
+    const mark = !tool.installed ? "·" : tool.status === "ready" ? "✓" : tool.status === "warning" ? "⚠" : "✗"
+    const value = tool.installed ? (tool.version ?? "installed") : "not installed"
+    const note = tool.installed && tool.message ? `  ${tool.message}` : ""
+    lines.push(`  ${mark} ${tool.name.padEnd(nameWidth)}${value}${note}`)
+  }
+
+  if (snapshot.mise.installed) {
+    lines.push("", "RUNTIMES (mise)")
+    if (snapshot.mise.error) lines.push(`  ⚠ ${snapshot.mise.error}`)
+    else if (snapshot.mise.runtimes.length === 0) lines.push("  no tools pinned for this project")
+    for (const runtime of snapshot.mise.runtimes) {
+      lines.push(
+        `  ${runtime.tool.padEnd(nameWidth + 2)}${runtime.version}${runtime.installed ? "" : "  (not installed)"}`,
+      )
+    }
+  }
+
+  const { direnv } = snapshot
+  if (direnv.installed || direnv.rcPath) {
+    lines.push("", "DIRENV")
+    if (direnv.error) lines.push(`  ⚠ ${direnv.error}`)
+    if (direnv.rcPath) {
+      lines.push(`  .envrc    ${tildify(direnv.rcPath)}`)
+      if (direnv.installed) {
+        lines.push(`  approval  ${direnv.approval}`)
+        lines.push(`  loaded    ${direnv.loaded ? "yes" : "no"}`)
+      }
+    } else {
+      lines.push("  no .envrc for this project")
+    }
+  }
+  return `${lines.join("\n")}\n`
+}
+
+// ---------------------------------------------------------------------------
+// devcc config check
+// ---------------------------------------------------------------------------
+
+/** Everything wrong with a loaded config, including verify names that resolve to nothing. */
+export function configProblems(rootDir: string, loaded: LoadedConfig): string[] {
+  const packageJson = readPackageJson(rootDir)
+  const { issues } = resolveVerifySteps(loaded.config.verify, {
+    commands: loaded.config.commands,
+    scripts: readScripts(packageJson),
+    packageManager: detectPackageManager({ rootDir, packageJson }).manager,
+  })
+  return [...loaded.issues, ...issues]
+}
+
+function configSummary(loaded: LoadedConfig) {
+  const { config } = loaded
+  return {
+    processes: config.processes.length,
+    commands: config.commands.length,
+    verify: config.verify.length,
+    services: config.services.length,
+    remoteMachines: config.remoteMachines.length,
+  }
+}
+
+export async function configCheckCommand(options: AutomationOptions): Promise<number> {
+  const io = options.io ?? processIo
+  const loaded = await loadConfig(options.rootDir)
+  if (!loaded.filePath) {
+    const issue = "No devcc config found (run `devcc init` to create .devcc.ts)"
+    if (options.json) printJson(io, { ok: false, file: null, issues: [issue] })
+    else io.stderr(`devcc config check: ${issue}\n`)
+    return EXIT_FAILED
+  }
+
+  const problems = configProblems(options.rootDir, loaded)
+  const summary = configSummary(loaded)
+  if (options.json) {
+    printJson(io, { ok: problems.length === 0, file: loaded.filePath, issues: problems, summary })
+  } else if (problems.length > 0) {
+    io.stderr(`✗ ${basename(loaded.filePath)} has ${problems.length} issue(s):\n`)
+    for (const problem of problems) io.stderr(`  - ${problem}\n`)
+  } else {
+    const labels: Record<keyof typeof summary, [string, string]> = {
+      processes: ["process", "processes"],
+      commands: ["command", "commands"],
+      verify: ["verify step", "verify steps"],
+      services: ["service", "services"],
+      remoteMachines: ["remote machine", "remote machines"],
+    }
+    const parts = (Object.entries(summary) as [keyof typeof summary, number][])
+      .filter(([, count]) => count > 0)
+      .map(([field, count]) => pluralise(count, ...labels[field]))
+    io.stdout(`✓ ${basename(loaded.filePath)} is valid${parts.length > 0 ? `: ${parts.join(", ")}` : ""}\n`)
+  }
+  return problems.length === 0 ? EXIT_OK : EXIT_FAILED
+}
+
+// ---------------------------------------------------------------------------
+// devcc init
+// ---------------------------------------------------------------------------
+
+export interface InitOptions extends AutomationOptions {
+  /** Replace an existing .devcc.ts with the starter. */
+  force?: boolean
+  /** Print the agent setup prompt instead of writing anything. */
+  printPrompt?: boolean
+  /** Start this agent interactively with the setup prompt. */
+  agent?: string
+  /** Injected for tests. */
+  isTTY?: boolean
+  runInteractive?: (command: string, args: string[], cwd: string) => Promise<number>
+}
+
+function runInteractive(command: string, args: string[], cwd: string): Promise<number> {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd, stdio: "inherit" })
+    child.once("error", (error) => {
+      process.stderr.write(`devcc init: could not start ${command}: ${error.message}\n`)
+      resolve(EXIT_FAILED)
+    })
+    child.once("exit", (code) => resolve(code ?? EXIT_FAILED))
+  })
+}
+
+/**
+ * `devcc init`: write a starter .devcc.ts from what can be detected.
+ * `--prompt` prints the agent setup prompt; `--agent <id>` opens that agent
+ * interactively with it, so the user watches and approves its edits.
+ */
+export async function initCommand(options: InitOptions): Promise<number> {
+  const io = options.io ?? processIo
+  const { rootDir } = options
+  const facts = detectProject(rootDir)
+
+  if (options.printPrompt) {
+    io.stdout(buildSetupPrompt(facts, "write"))
+    return EXIT_OK
+  }
+
+  if (options.agent) {
+    const loaded = await loadConfig(rootDir)
+    const adapters = createAgentAdapters(loaded.config.agents)
+    const adapter = adapters.find((candidate) => candidate.id === options.agent)
+    if (!adapter?.interactiveArgs) {
+      const available = adapters
+        .filter((candidate) => candidate.interactiveArgs)
+        .map((candidate) => candidate.id)
+      io.stderr(`devcc init: --agent must be one of: ${available.join(", ")}\n`)
+      return EXIT_USAGE
+    }
+    if (!(options.isTTY ?? process.stdout.isTTY)) {
+      io.stderr(
+        "devcc init --agent needs an interactive terminal. Use `devcc init --prompt` to get the prompt instead.\n",
+      )
+      return EXIT_USAGE
+    }
+    if (!(await adapter.detect())) {
+      io.stderr(`devcc init: ${adapter.name} is not installed (\`${adapter.command}\` was not found)\n`)
+      return EXIT_FAILED
+    }
+    io.stdout(`Starting ${adapter.name} to set up devcc for ${facts.name}…\n`)
+    const run = options.runInteractive ?? runInteractive
+    return run(adapter.command, adapter.interactiveArgs(buildSetupPrompt(facts, "write")), rootDir)
+  }
+
+  if (facts.configPath && !options.force) {
+    io.stderr(
+      `devcc init: ${basename(facts.configPath)} already exists.\n` +
+        "  Improve it with an agent:  devcc init --agent claude   (or codex)\n" +
+        "  Replace it with a starter: devcc init --force\n",
+    )
+    return EXIT_USAGE
+  }
+
+  const target = join(rootDir, ".devcc.ts")
+  writeFileSync(target, renderStarterConfig(facts), "utf8")
+  const loaded = await loadConfigFile(target)
+  const problems = configProblems(rootDir, loaded)
+  const starter = starterConfig(facts)
+
+  io.stdout(`Created ${tildify(target)}\n`)
+  if (facts.configPath && facts.configPath !== target) {
+    io.stdout(`  note: .devcc.ts takes precedence over ${basename(facts.configPath)}, which is now ignored\n`)
+  }
+  io.stdout(
+    `  processes: ${starter.processes.map((entry) => entry.name).join(", ") || "none detected"}\n` +
+      `  verify:    ${starter.verify.map((entry) => (typeof entry === "string" ? entry : entry.id)).join(", ") || "none detected"}\n`,
+  )
+  for (const problem of problems) io.stderr(`  ⚠ ${problem}\n`)
+  io.stdout(
+    "\nNext:\n" +
+      "  devcc init --agent claude   let an agent read the project and refine it (or codex)\n" +
+      "  devcc init --prompt         print that prompt for any other agent\n" +
+      "  devcc config check          validate after editing\n",
+  )
+  return problems.length === 0 ? EXIT_OK : EXIT_FAILED
+}

package/src/devcc/cli.ts

@@ -8,8 +8,16 @@
  * bypassed it.
  */
 import { createRequire } from "node:module"
+import { resolve } from "node:path"
 import { pathToFileURL } from "node:url"
-import { App } from "./app/App.js"
+import {
+  configCheckCommand,
+  envCommand,
+  EXIT_USAGE,
+  initCommand,
+  verifyCommand,
+  worktreeListCommand,
+} from "./automation.js"
 import { errorMessage } from "./utils/errors.js"
 import { findProjectRoot } from "./utils/paths.js"
 
@@ -17,6 +25,12 @@ interface CliArgs {
   cwd?: string
   help: boolean
   version: boolean
+  json: boolean
+  force: boolean
+  prompt: boolean
+  agent?: string
+  /** Subcommand and its arguments, e.g. `["worktree", "list"]`. */
+  positionals: string[]
 }
 
 /**
@@ -37,11 +51,25 @@ function readVersion(): string {
 const VERSION = readVersion()
 
 function parseArgs(argv: readonly string[]): CliArgs {
-  const args: CliArgs = { help: false, version: false }
+  const args: CliArgs = {
+    help: false,
+    version: false,
+    json: false,
+    force: false,
+    prompt: false,
+    positionals: [],
+  }
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index]
     if (arg === "--help" || arg === "-h") args.help = true
     else if (arg === "--version" || arg === "-v") args.version = true
+    else if (arg === "--json") args.json = true
+    else if (arg === "--force") args.force = true
+    else if (arg === "--prompt") args.prompt = true
+    else if (arg === "--agent") {
+      args.agent = argv[index + 1]
+      index += 1
+    } else if (arg?.startsWith("--agent=")) args.agent = arg.slice("--agent=".length)
     else if (arg === "--cwd" || arg === "-C") {
       const value = argv[index + 1]
       if (value) {
@@ -50,6 +78,8 @@ function parseArgs(argv: readonly string[]): CliArgs {
       }
     } else if (arg?.startsWith("--cwd=")) {
       args.cwd = arg.slice("--cwd=".length)
+    } else if (arg !== undefined && !arg.startsWith("-")) {
+      args.positionals.push(arg)
     }
   }
   return args
@@ -58,13 +88,25 @@ function parseArgs(argv: readonly string[]): CliArgs {
 const USAGE = `dev command center ${VERSION}
 
 Usage:
-  devcc [options]
+  devcc [options]                 Open the dashboard
+  devcc verify [--json]           Run the project's verify steps; exit 0 only if all pass
+  devcc worktree list [--json]    List git worktrees
+  devcc env [--json]              Report tools, mise runtimes and direnv status
+  devcc init                      Write a starter .devcc.ts from what is detected
+  devcc init --agent <claude|codex>  Let an agent inspect the project and set up .devcc.ts
+  devcc init --prompt             Print that setup prompt for any other agent
+  devcc config check [--json]     Validate the project's devcc config
 
 Options:
   -C, --cwd <dir>   Project directory (default: nearest project root)
+      --json        Machine-readable output (verify, worktree list, env, config check)
+      --force       init: replace an existing .devcc.ts
   -h, --help        Show this help
   -v, --version     Show the version
 
+Exit codes (verify):
+  0  every step passed   1  a step failed   2  nothing to verify / bad config
+
 Environment:
   DEVCC_LOG_LEVEL   debug | info | warn | error | silent (default: info)
 
@@ -84,11 +126,28 @@ export async function main(argv: readonly string[] = process.argv.slice(2)): Pro
     return 0
   }
 
+  const [command, ...rest] = args.positionals
+  if (command !== undefined) {
+    const rootDir = args.cwd ? resolve(args.cwd) : findProjectRoot()
+    const options = { rootDir, json: args.json }
+    if (command === "verify" && rest.length === 0) return runVerifyCli(options)
+    if (command === "worktree" && rest.length === 1 && rest[0] === "list") return worktreeListCommand(options)
+    if (command === "env" && rest.length === 0) return envCommand(options)
+    if (command === "init" && rest.length === 0) {
+      return initCommand({ ...options, force: args.force, printPrompt: args.prompt, agent: args.agent })
+    }
+    if (command === "config" && rest.length === 1 && rest[0] === "check") return configCheckCommand(options)
+    process.stderr.write(`devcc: unknown command "${args.positionals.join(" ")}"\n\n${USAGE}`)
+    return EXIT_USAGE
+  }
+
   if (!process.stdout.isTTY) {
     process.stderr.write("devcc needs an interactive terminal (stdout is not a TTY).\n")
     return 1
   }
 
+  // Loaded lazily: OpenTUI needs FFI, which the automation commands above do not.
+  const { App } = await import("./app/App.js")
   const app = new App({ cwd: args.cwd ? args.cwd : findProjectRoot() })
 
   try {
@@ -107,6 +166,21 @@ export async function main(argv: readonly string[] = process.argv.slice(2)): Pro
   }
 }
 
+/** Ctrl+C stops the running step instead of leaving it orphaned. */
+async function runVerifyCli(options: { rootDir: string; json: boolean }): Promise<number> {
+  const controller = new AbortController()
+  const onSignal = () => controller.abort()
+  process.once("SIGINT", onSignal)
+  process.once("SIGTERM", onSignal)
+  try {
+    const code = await verifyCommand({ ...options, signal: controller.signal })
+    return controller.signal.aborted ? 130 : code
+  } finally {
+    process.off("SIGINT", onSignal)
+    process.off("SIGTERM", onSignal)
+  }
+}
+
 const entry = process.argv[1]
 const isDirectRun = entry !== undefined && import.meta.url === pathToFileURL(entry).href
 

package/src/devcc/components/Sidebar.ts

@@ -16,6 +16,7 @@ export const SIDEBAR_ITEMS: readonly SidebarItem[] = [
   { id: "services", label: "Services" },
   { id: "scripts", label: "Scripts" },
   { id: "git", label: "Git" },
+  { id: "worktrees", label: "Worktrees" },
   { id: "logs", label: "Logs" },
   { id: "dependencies", label: "Dependencies" },
   { id: "system", label: "System" },

package/src/devcc/components/primitives.ts

@@ -98,6 +98,9 @@ export class RowList {
     })
     this.box.onSizeChange = () => {
       const visible = this.visibleCount
+      // The first setRows can happen before layout, when the viewport is one
+      // row tall; re-derive the scroll position now that the real height is known.
+      this.ensureVisible()
       this.paint()
       if (visible !== this.lastVisibleCount) {
         this.lastVisibleCount = visible

package/src/devcc/core/commands.ts

@@ -1,5 +1,9 @@
+import type { AgentManager } from "../agents/agents.js"
+import type { RemoteMachineConfig } from "./config.js"
 import type { DependencyService } from "../deps/DependencyService.js"
+import type { EnvironmentService } from "../environment/EnvironmentService.js"
 import type { GitService } from "../git/GitService.js"
+import type { GitWorktree } from "../git/worktrees.js"
 import type { LogStore } from "../logs/LogBuffer.js"
 import type { ProcessManager } from "../processes/ProcessManager.js"
 import type { ServiceManager } from "../services/ServiceManager.js"
@@ -23,6 +27,8 @@ export interface CommandContext {
   logs: LogStore
   system: SystemMonitor
   deps: DependencyService
+  agents: AgentManager
+  environment: EnvironmentService
 
   navigate: (view: ViewId) => void
   notify: (level: NotificationLevel, message: string, detail?: string) => void
@@ -43,6 +49,34 @@ export interface CommandContext {
   switchProject: (path: string) => Promise<void>
   /** Close an open project, stopping what devcc started there. Defaults to the current one. */
   closeProject: (path?: string) => Promise<void>
+
+  /**
+   * The worktree commands act on: the one selected in the Worktrees view, or
+   * the worktree devcc is running in. Undefined outside a git repository.
+   */
+  selectedWorktree: () => GitWorktree | undefined
+  /** Prompt for branch, base and path, then `git worktree add`. */
+  createWorktree: () => Promise<void>
+  /** Confirmed, never forced `git worktree remove`. */
+  removeWorktree: (worktree: GitWorktree) => Promise<void>
+  /** Prompt for a task and start the agent in the worktree (default: the selected one). */
+  launchAgent: (agentId: string, worktree?: GitWorktree) => Promise<void>
+  openInEditor: (path: string) => Promise<void>
+  openInTerminal: (path: string) => Promise<void>
+  /** Run the project's verification steps; output lands in Logs. */
+  runVerify: () => Promise<void>
+  /** Remote machines declared in config. */
+  remoteMachines: () => RemoteMachineConfig[]
+  /** Open an interactive SSH session in a terminal. */
+  sshTo: (machineId: string) => Promise<void>
+  /**
+   * Set up `.devcc.ts`: `"starter"` writes the detected starter; an agent id
+   * asks that agent to inspect the project and propose one, which devcc
+   * validates and writes only after confirmation.
+   */
+  setUpConfig: (how: "starter" | (string & {})) => Promise<void>
+  /** Re-read the config, rebuilding the project session (confirms if processes run). */
+  reloadConfig: () => Promise<void>
   quit: () => void
 }