@doriandev/devcc 0.1.2 → 0.2.0

package/src/devcc/git/worktrees.ts

@@ -0,0 +1,256 @@
+import { basename, isAbsolute, relative, resolve } from "node:path"
+
+/**
+ * Pure helpers for `git worktree`.
+ *
+ * Parsing, argument construction and validation live here so they can be
+ * tested without a repository; `GitService` only runs the commands.
+ */
+
+export interface GitWorktree {
+  /** Absolute path of the worktree's top-level directory. */
+  path: string
+  /** Short branch name (`feature/x`), absent when detached or bare. */
+  branch?: string
+  /** Full commit hash of HEAD; empty for a bare repository. */
+  head: string
+  bare: boolean
+  detached: boolean
+  locked: boolean
+  lockedReason?: string
+  prunable: boolean
+  prunableReason?: string
+  /** The first entry git reports: the repository's main worktree. */
+  isMain: boolean
+  /** The worktree devcc is running in. */
+  isCurrent: boolean
+}
+
+/**
+ * Parse `git worktree list --porcelain` (optionally with `-z`).
+ *
+ * Records are separated by a blank line (a double NUL with `-z`). Unknown keys
+ * are ignored and records without a `worktree` line are dropped, so output from
+ * a newer git with extra attributes still parses.
+ *
+ * Format reference: `man git-worktree`, "Porcelain Format".
+ */
+export function parseWorktreeList(output: string, currentPath?: string): GitWorktree[] {
+  const nulSeparated = output.includes("\0")
+  const lines = nulSeparated ? output.split("\0") : output.split("\n").map((line) => line.replace(/\r$/u, ""))
+
+  const worktrees: GitWorktree[] = []
+  let record: GitWorktree | null = null
+
+  const flush = () => {
+    if (record && record.path !== "") worktrees.push(record)
+    record = null
+  }
+
+  for (const line of lines) {
+    if (line === "") {
+      flush()
+      continue
+    }
+
+    const space = line.indexOf(" ")
+    const key = space === -1 ? line : line.slice(0, space)
+    const value = space === -1 ? "" : line.slice(space + 1)
+
+    if (key === "worktree") {
+      flush()
+      record = {
+        path: value,
+        head: "",
+        bare: false,
+        detached: false,
+        locked: false,
+        prunable: false,
+        isMain: worktrees.length === 0,
+        isCurrent: false,
+      }
+      continue
+    }
+
+    // Attributes before any `worktree` line are malformed; skip them.
+    const current = record
+    if (!current) continue
+
+    switch (key) {
+      case "HEAD":
+        current.head = value
+        break
+      case "branch":
+        current.branch = value.replace(/^refs\/heads\//u, "")
+        break
+      case "bare":
+        current.bare = true
+        break
+      case "detached":
+        current.detached = true
+        break
+      case "locked":
+        current.locked = true
+        if (value) current.lockedReason = value
+        break
+      case "prunable":
+        current.prunable = true
+        if (value) current.prunableReason = value
+        break
+      default:
+        break
+    }
+  }
+  flush()
+
+  // The first record is the main worktree even if it followed malformed lines.
+  for (const [index, worktree] of worktrees.entries()) worktree.isMain = index === 0
+
+  return currentPath ? markCurrent(worktrees, currentPath) : worktrees
+}
+
+/**
+ * Flag the worktree containing `currentPath`. The deepest match wins, so a
+ * worktree nested inside the main checkout is attributed correctly.
+ */
+export function markCurrent(worktrees: GitWorktree[], currentPath: string): GitWorktree[] {
+  let best: GitWorktree | undefined
+  for (const worktree of worktrees) {
+    if (worktree.bare || !isInside(currentPath, worktree.path)) continue
+    if (!best || worktree.path.length > best.path.length) best = worktree
+  }
+  return worktrees.map((worktree) => ({ ...worktree, isCurrent: worktree === best }))
+}
+
+/** True when `path` is `parent` or somewhere below it. */
+export function isInside(path: string, parent: string): boolean {
+  const rel = relative(resolve(parent), resolve(path))
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel))
+}
+
+/** Display label: the branch, or a short hash when detached. */
+export function worktreeLabel(worktree: GitWorktree): string {
+  if (worktree.bare) return "(bare)"
+  if (worktree.branch) return worktree.branch
+  return worktree.head ? `detached @ ${worktree.head.slice(0, 7)}` : "(unknown)"
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/u
+
+/**
+ * Validate a branch name against git's ref rules (`man git-check-ref-format`),
+ * plus a leading-dash check so a name can never be read as an option.
+ * Returns a human-readable problem, or null when the name is acceptable.
+ */
+export function validateBranchName(name: string): string | null {
+  if (name.trim() === "") return "Branch name is empty"
+  if (name !== name.trim() || /\s/u.test(name)) return "Branch name cannot contain whitespace"
+  if (CONTROL_CHARS.test(name)) return "Branch name cannot contain control characters"
+  if (name.startsWith("-")) return "Branch name cannot start with '-'"
+  if (name === "@") return "Branch name cannot be '@'"
+  if (/[~^:?*[\\]/u.test(name)) return "Branch name cannot contain ~ ^ : ? * [ or \\"
+  if (name.includes("..")) return "Branch name cannot contain '..'"
+  if (name.includes("@{")) return "Branch name cannot contain '@{'"
+  if (name.includes("//")) return "Branch name cannot contain '//'"
+  if (name.startsWith("/") || name.endsWith("/")) return "Branch name cannot start or end with '/'"
+  if (name.endsWith(".")) return "Branch name cannot end with '.'"
+  for (const segment of name.split("/")) {
+    if (segment.startsWith(".")) return "Branch name segments cannot start with '.'"
+    if (segment.endsWith(".lock")) return "Branch name segments cannot end with '.lock'"
+  }
+  return null
+}
+
+/** A base ref is passed straight to git, so only rule out option-like or broken input. */
+export function validateRef(ref: string): string | null {
+  if (ref.trim() === "") return "Base ref is empty"
+  if (ref.startsWith("-")) return "Base ref cannot start with '-'"
+  if (/\s/u.test(ref) || CONTROL_CHARS.test(ref)) return "Base ref cannot contain whitespace"
+  return null
+}
+
+/**
+ * Validate a destination directory for a new worktree. `exists` is injected
+ * so the check is testable; git itself refuses a non-empty existing directory,
+ * but refusing early gives a clearer message.
+ */
+export function validateWorktreePath(path: string, exists: (path: string) => boolean): string | null {
+  if (path.trim() === "") return "Worktree path is empty"
+  if (CONTROL_CHARS.test(path)) return "Worktree path cannot contain control characters"
+  if (!isAbsolute(path)) return "Worktree path must be absolute"
+  if (exists(path)) return `${path} already exists`
+  return null
+}
+
+/** Directory-safe form of a branch name: `feature/ai-agents` -> `feature-ai-agents`. */
+export function branchSlug(branch: string): string {
+  return (
+    branch
+      .replace(/[^A-Za-z0-9._-]+/gu, "-")
+      .replace(/-+/gu, "-")
+      .replace(/^[-.]+|[-.]+$/gu, "") || "worktree"
+  )
+}
+
+/**
+ * Where a new worktree goes by default: `<directory>/<repo>-<branch>`, with
+ * `directory` relative to the main worktree (default: its parent).
+ */
+export function defaultWorktreePath(mainWorktreePath: string, branch: string, directory = ".."): string {
+  return resolve(mainWorktreePath, directory, `${basename(mainWorktreePath)}-${branchSlug(branch)}`)
+}
+
+// ---------------------------------------------------------------------------
+// Argument construction
+// ---------------------------------------------------------------------------
+
+export interface CreateWorktreeRequest {
+  /** Absolute destination directory. */
+  path: string
+  branch: string
+  /** Start point for a new branch. Ignored when checking out an existing branch. */
+  base?: string
+  /** True to create `branch` (`-b`); false to check out an existing one. */
+  createBranch: boolean
+}
+
+/**
+ * Arguments for `git worktree add`. Everything user-provided comes after `--`
+ * or as the value of `-b`, and each value is its own argv entry, so nothing can
+ * be interpreted as an option or split by a shell.
+ */
+export function worktreeAddArgs(request: CreateWorktreeRequest): string[] {
+  if (request.createBranch) {
+    const args = ["worktree", "add", "-b", request.branch, "--", request.path]
+    if (request.base) args.push(request.base)
+    return args
+  }
+  return ["worktree", "add", "--", request.path, request.branch]
+}
+
+/** Arguments for `git worktree remove`. Never `--force`: git's safety check stands. */
+export function worktreeRemoveArgs(path: string): string[] {
+  return ["worktree", "remove", "--", path]
+}
+
+/**
+ * Decide whether a worktree may be removed before asking git. `busy` lists
+ * directories where devcc is still running something (agents, processes).
+ * Returns the reason for refusing, or null when removal may proceed.
+ */
+export function removalBlocker(worktree: GitWorktree, busy: readonly string[] = []): string | null {
+  if (worktree.isMain) return "The main worktree cannot be removed"
+  if (worktree.isCurrent) return "devcc is running in this worktree; open another project first"
+  if (worktree.bare) return "A bare repository is not a removable worktree"
+  if (worktree.locked) {
+    return `Worktree is locked${worktree.lockedReason ? `: ${worktree.lockedReason}` : ""}; unlock it with git first`
+  }
+  const running = busy.find((dir) => isInside(dir, worktree.path))
+  if (running) return `Something devcc started is still running in ${worktree.path}; stop it first`
+  return null
+}

package/src/devcc/index.ts

@@ -7,6 +7,17 @@
  */
 
 export { App, type AppOptions } from "./app/App.js"
+export { createControlPlaneCommands } from "./app/controlPlaneCommands.js"
+export {
+  AgentManager,
+  BUILTIN_AGENTS,
+  createAgentAdapters,
+  type AgentAdapter,
+  type AgentConfig,
+  type AgentLaunchOptions,
+  type AgentSession,
+} from "./agents/agents.js"
+export { envCommand, verifyCommand, worktreeListCommand } from "./automation.js"
 export { createBuiltinCommands, createConfigCommands, createScriptCommands } from "./app/builtinCommands.js"
 export { HELP_SECTIONS, VIEW_SHORTCUTS } from "./app/keymap.js"
 export { theme, glyphs, processStatusStyle, serviceStateStyle } from "./app/theme.js"
@@ -21,8 +32,12 @@ export {
   DEFAULT_REFRESH,
   type CommandConfigEntry,
   type DevccConfig,
+  type EditorConfig,
+  type RemoteMachineConfig,
   type ResolvedConfig,
   type ServiceConfigEntry,
+  type TerminalConfig,
+  type WorktreesConfig,
 } from "./core/config.js"
 export { TypedEmitter, Subscriptions, type Unsubscribe } from "./core/events.js"
 export {
@@ -48,7 +63,32 @@ export {
   type UpdateSeverity,
 } from "./deps/parse.js"
 
-export { GitService, type GitSnapshot } from "./git/GitService.js"
+export { EnvironmentService, type EnvironmentSnapshot } from "./environment/EnvironmentService.js"
+export {
+  parseDirenvStatus,
+  parseMiseLs,
+  type DirenvStatus,
+  type MiseStatus,
+  type RuntimeVersion,
+} from "./environment/integrations.js"
+export {
+  DEFAULT_TOOLS,
+  detectTool,
+  findExecutable,
+  type ToolDefinition,
+  type ToolStatus,
+} from "./environment/tools.js"
+
+export { GitService, type CreateWorktreeInput, type GitSnapshot } from "./git/GitService.js"
+export {
+  defaultWorktreePath,
+  parseWorktreeList,
+  removalBlocker,
+  validateBranchName,
+  worktreeAddArgs,
+  worktreeRemoveArgs,
+  type GitWorktree,
+} from "./git/worktrees.js"
 export {
   parseCommits,
   parsePorcelainV2,
@@ -96,7 +136,14 @@ export {
 export { ServiceManager } from "./services/ServiceManager.js"
 export { DockerService, findComposeFile, parseComposePs } from "./services/docker.js"
 export { PortService, detectNodeServices } from "./services/node.js"
-export { OllamaService } from "./services/ollama.js"
+export { mergeOllamaModels, OllamaService, type OllamaModel } from "./services/ollama.js"
+export {
+  parseTailscaleStatus,
+  RemoteMachineService,
+  TailscaleService,
+  type TailscaleStatus,
+} from "./services/remote.js"
+export { editorCommand, launchDetached, sshCommand, terminalCommand } from "./platform/launch.js"
 export { PostgresService, parsePostgresUrl } from "./services/postgres.js"
 export { RedisService, parseRedisUrl } from "./services/redis.js"
 export type { ServiceAdapter, ServiceSnapshot, ServiceState, ServiceStatus } from "./services/types.js"
@@ -113,3 +160,11 @@ export {
   type PackageManager,
 } from "./utils/packageManager.js"
 export { findProjectRoot } from "./utils/paths.js"
+export {
+  createSpawnExecutor,
+  resolveVerifySteps,
+  runVerification,
+  type VerifyEntry,
+  type VerifyReport,
+  type VerifyStep,
+} from "./verify/verify.js"

package/src/devcc/platform/launch.ts

@@ -0,0 +1,125 @@
+import { spawn } from "node:child_process"
+import type { EditorConfig, RemoteMachineConfig, TerminalConfig } from "../core/config.js"
+import { sshDestination } from "../services/remote.js"
+import { DevccError } from "../utils/errors.js"
+
+/**
+ * Opening things outside devcc: editors, terminals, SSH sessions.
+ *
+ * Every launch is an executable plus an argv array, detached from devcc so
+ * closing the dashboard never closes your editor. macOS conventions (`open`,
+ * `open -a`) are used only when running on macOS; elsewhere a configured
+ * command is required.
+ */
+
+export interface LaunchCommand {
+  command: string
+  args: string[]
+}
+
+export type Platform = NodeJS.Platform
+
+/** Replace `{path}` inside individual arguments. Never joins arguments into a string. */
+export function substitutePath(args: readonly string[], path: string): string[] {
+  return args.map((arg) => arg.split("{path}").join(path))
+}
+
+export function editorCommand(
+  path: string,
+  editor: EditorConfig | undefined,
+  platform: Platform = process.platform,
+): LaunchCommand {
+  if (editor?.command) return { command: editor.command, args: [...(editor.args ?? []), path] }
+  if (editor?.application) {
+    if (platform !== "darwin") {
+      throw new DevccError({
+        scope: "command",
+        message: `editor.application only works on macOS; set editor.command`,
+      })
+    }
+    return { command: "open", args: ["-a", editor.application, path] }
+  }
+  throw new DevccError({
+    scope: "command",
+    message: "No editor configured",
+    detail: 'Set editor: { command: "code" } (or zed, cursor, webstorm) in .devcc.ts',
+  })
+}
+
+export function terminalCommand(
+  path: string,
+  terminal: TerminalConfig | undefined,
+  platform: Platform = process.platform,
+): LaunchCommand {
+  if (terminal?.command) {
+    const args = terminal.args ?? ["{path}"]
+    return { command: terminal.command, args: substitutePath(args, path) }
+  }
+  if (platform === "darwin") {
+    return { command: "open", args: ["-a", terminal?.application ?? "Terminal", path] }
+  }
+  throw new DevccError({
+    scope: "command",
+    message: "No terminal configured",
+    detail: 'Set terminal: { command: "wezterm", args: ["start", "--cwd", "{path}"] } in .devcc.ts',
+  })
+}
+
+/**
+ * An interactive SSH session needs a terminal. On macOS `open ssh://host`
+ * hands the URL to the default terminal, which runs `ssh` with the user's own
+ * config for that alias. Elsewhere the configured terminal runs `ssh`.
+ */
+export function sshCommand(
+  machine: Pick<RemoteMachineConfig, "host" | "user" | "port">,
+  terminal: TerminalConfig | undefined,
+  platform: Platform = process.platform,
+): LaunchCommand {
+  if (terminal?.command && terminal.execArgs) {
+    const port = machine.port ? ["-p", String(machine.port)] : []
+    return {
+      command: terminal.command,
+      args: [...terminal.execArgs, "ssh", ...port, sshDestination(machine)],
+    }
+  }
+  if (platform === "darwin") {
+    const user = machine.user ? `${encodeURIComponent(machine.user)}@` : ""
+    const port = machine.port ? `:${machine.port}` : ""
+    return { command: "open", args: [`ssh://${user}${machine.host}${port}`] }
+  }
+  throw new DevccError({
+    scope: "command",
+    message: "No terminal configured for SSH",
+    detail: 'Set terminal: { command: "wezterm", execArgs: ["start", "--"] } in .devcc.ts',
+  })
+}
+
+/**
+ * Start a GUI or launcher process detached from devcc. Resolves once it has
+ * spawned (not when it exits); rejects with a readable error if it cannot start.
+ */
+export function launchDetached(launch: LaunchCommand, cwd?: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let child
+    try {
+      child = spawn(launch.command, launch.args, { cwd, detached: true, stdio: "ignore", windowsHide: true })
+    } catch (error) {
+      reject(toLaunchError(launch, error))
+      return
+    }
+    child.once("error", (error) => reject(toLaunchError(launch, error)))
+    child.once("spawn", () => {
+      child.unref()
+      resolve()
+    })
+  })
+}
+
+function toLaunchError(launch: LaunchCommand, error: unknown): DevccError {
+  const code = (error as NodeJS.ErrnoException).code
+  return new DevccError({
+    scope: "command",
+    message: code === "ENOENT" ? `\`${launch.command}\` was not found` : `Could not run ${launch.command}`,
+    cause: error,
+  })
+}

package/src/devcc/services/ServiceManager.ts

@@ -35,6 +35,8 @@ export class ServiceManager extends TypedEmitter<ServiceManagerEvents> {
   private readonly adapters = new Map<string, ServiceAdapter>()
   private readonly detected = new Set<string>()
   private readonly snapshots = new Map<string, ServiceSnapshot>()
+  /** When each adapter was last asked for its status. */
+  private readonly checkedAt = new Map<string, number>()
   private timer: NodeJS.Timeout | null = null
   private refreshing = false
   private readonly intervalMs: number
@@ -92,7 +94,7 @@ export class ServiceManager extends TypedEmitter<ServiceManagerEvents> {
 
   start(): void {
     if (this.timer) return
-    this.timer = setInterval(() => void this.refresh(), this.intervalMs)
+    this.timer = setInterval(() => void this.refresh({ polled: true }), this.intervalMs)
     this.timer.unref?.()
   }
 
@@ -102,14 +104,24 @@ export class ServiceManager extends TypedEmitter<ServiceManagerEvents> {
     this.timer = null
   }
 
-  /** Refresh all detected adapters concurrently. Overlapping calls are skipped. */
-  async refresh(): Promise<ServiceSnapshot[]> {
+  /**
+   * Refresh all detected adapters concurrently. Overlapping calls are skipped.
+   * A `polled` refresh (the timer) skips adapters whose `refreshIntervalMs`
+   * has not elapsed; an explicit refresh checks everything.
+   */
+  async refresh(options: { polled?: boolean } = {}): Promise<ServiceSnapshot[]> {
     if (this.refreshing) return this.list()
     this.refreshing = true
     try {
+      const now = Date.now()
       const targets = [...this.detected]
         .map((id) => this.adapters.get(id))
         .filter((a): a is ServiceAdapter => !!a)
+        .filter((adapter) => {
+          if (!options.polled || !adapter.refreshIntervalMs) return true
+          return now - (this.checkedAt.get(adapter.id) ?? 0) >= adapter.refreshIntervalMs
+        })
+      for (const adapter of targets) this.checkedAt.set(adapter.id, now)
 
       await Promise.all(
         targets.map(async (adapter) => {