@doriandev/devcc 0.1.2 → 0.3.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,25 @@
  */
 
 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 {
+  configCheckCommand,
+  envCommand,
+  initCommand,
+  verifyCommand,
+  worktreeListCommand,
+} from "./automation.js"
+export { detectProject, renderStarterConfig, starterConfig, type ProjectFacts } from "./init/detect.js"
+export { buildSetupPrompt, extractConfigFromOutput, type SetupPromptMode } from "./init/prompt.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"
@@ -17,12 +36,17 @@ export {
   loadConfig,
   validateConfig,
   findConfigFile,
+  loadConfigFile,
   CONFIG_FILENAMES,
   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 +72,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 +145,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 +169,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/init/detect.ts

@@ -0,0 +1,268 @@
+import { existsSync, readFileSync } from "node:fs"
+import { basename, join } from "node:path"
+import { findConfigFile } from "../core/config.js"
+import type { ProcessDefinition } from "../processes/ManagedProcess.js"
+import { detectFrameworks } from "../services/node.js"
+import {
+  detectPackageManager,
+  readPackageJson,
+  readScripts,
+  runScriptArgs,
+  type PackageManager,
+  type PackageManagerDetection,
+  type PackageScript,
+} from "../utils/packageManager.js"
+import type { VerifyEntry } from "../verify/verify.js"
+
+/**
+ * Project detection for `devcc init` and the agent setup prompt.
+ *
+ * Only facts that can be read from the repository are collected - nothing is
+ * executed and nothing is guessed. The starter config built from them is
+ * deliberately conservative: a script is only used when it exists.
+ */
+
+export interface ProjectFacts {
+  rootDir: string
+  name: string
+  /** Existing config file, if any. */
+  configPath: string | null
+  hasGit: boolean
+  /** Null when there is no package.json. */
+  packageManager: PackageManagerDetection | null
+  scripts: PackageScript[]
+  frameworks: { name: string; dependency: string; port: number }[]
+  /** Script chosen to run the app in development. */
+  devScript?: string
+  /** Scripts suitable for `verify`, in the order they should run. */
+  verifyScripts: string[]
+  /** Scripts that look like verification but were left out, with the reason. */
+  skippedScripts: { name: string; reason: string }[]
+  monorepo: string | null
+  languages: ("node" | "rust" | "go" | "python")[]
+  /** Notable files present at the root (compose file, .envrc, mise.toml, Makefile, ...). */
+  files: string[]
+}
+
+type Exists = (path: string) => boolean
+
+const DEV_SCRIPTS = ["dev", "start:dev", "develop", "serve"] as const
+
+/** Verify categories in run order; the first matching script name in each wins. */
+const VERIFY_CATEGORIES: readonly (readonly string[])[] = [
+  ["format:check", "format-check", "fmt:check", "prettier:check", "check:format", "lint:format"],
+  ["lint"],
+  ["typecheck", "type-check", "check-types", "types:check", "tsc"],
+  ["test:ci", "test:run", "test:unit", "test"],
+  ["build"],
+]
+
+/** Aggregate scripts used only when no individual checks exist. */
+const AGGREGATE_SCRIPTS = ["verify", "ci", "check", "validate"] as const
+
+const NOTABLE_FILES = [
+  "compose.yaml",
+  "compose.yml",
+  "docker-compose.yml",
+  "docker-compose.yaml",
+  ".envrc",
+  "mise.toml",
+  ".mise.toml",
+  ".tool-versions",
+  ".env.example",
+  "Makefile",
+  "turbo.json",
+  "nx.json",
+  "pnpm-workspace.yaml",
+  "Cargo.toml",
+  "go.mod",
+  "pyproject.toml",
+  "AGENTS.md",
+  "CLAUDE.md",
+] as const
+
+/** Why a script cannot be a verify step, or null when it can. */
+export function unsuitableForVerify(command: string): string | null {
+  if (/--watch\b|\bwatch\b/u.test(command)) return "runs in watch mode"
+  if (/no test specified/u.test(command)) return "is npm's placeholder"
+  if (/--fix\b|--write\b/u.test(command)) return "modifies files"
+  return null
+}
+
+export function detectProject(rootDir: string, exists: Exists = existsSync): ProjectFacts {
+  const packageJson = readPackageJson(rootDir)
+  const scripts = readScripts(packageJson)
+  const byName = new Map(scripts.map((script) => [script.name, script.command]))
+
+  const verifyScripts: string[] = []
+  const skippedScripts: { name: string; reason: string }[] = []
+  for (const category of VERIFY_CATEGORIES) {
+    for (const name of category) {
+      const command = byName.get(name)
+      if (command === undefined) continue
+      const reason = unsuitableForVerify(command)
+      if (reason) {
+        skippedScripts.push({ name, reason })
+        continue
+      }
+      verifyScripts.push(name)
+      break
+    }
+  }
+  if (verifyScripts.length === 0) {
+    const aggregate = AGGREGATE_SCRIPTS.find((name) => {
+      const command = byName.get(name)
+      return command !== undefined && unsuitableForVerify(command) === null
+    })
+    if (aggregate) verifyScripts.push(aggregate)
+  }
+
+  const files = NOTABLE_FILES.filter((file) => exists(join(rootDir, file)))
+  const languages: ProjectFacts["languages"] = []
+  if (packageJson) languages.push("node")
+  if (files.includes("Cargo.toml")) languages.push("rust")
+  if (files.includes("go.mod")) languages.push("go")
+  if (files.includes("pyproject.toml")) languages.push("python")
+
+  const monorepo = files.includes("pnpm-workspace.yaml")
+    ? "pnpm workspaces"
+    : files.includes("turbo.json")
+      ? "Turborepo"
+      : files.includes("nx.json")
+        ? "Nx"
+        : packageJson?.workspaces
+          ? "package.json workspaces"
+          : null
+
+  return {
+    rootDir,
+    name: typeof packageJson?.name === "string" ? packageJson.name : basename(rootDir),
+    configPath: findConfigFile(rootDir, exists),
+    hasGit: exists(join(rootDir, ".git")),
+    packageManager: packageJson ? detectPackageManager({ rootDir, packageJson, fileExists: exists }) : null,
+    scripts,
+    frameworks: detectFrameworks(packageJson).map((hint) => ({
+      name: hint.name,
+      dependency: hint.dependency,
+      port: hint.port,
+    })),
+    devScript: DEV_SCRIPTS.find((name) => byName.has(name)),
+    verifyScripts,
+    skippedScripts,
+    monorepo,
+    languages,
+    files,
+  }
+}
+
+/** Inline verify steps for non-Node projects, using each toolchain's standard commands. */
+function toolchainVerify(facts: ProjectFacts): VerifyEntry[] {
+  if (facts.verifyScripts.length > 0) return facts.verifyScripts
+  if (facts.languages.includes("rust")) {
+    return [
+      { id: "fmt", name: "cargo fmt", command: "cargo", args: ["fmt", "--check"] },
+      { id: "clippy", name: "cargo clippy", command: "cargo", args: ["clippy", "--all-targets"] },
+      { id: "test", name: "cargo test", command: "cargo", args: ["test"] },
+    ]
+  }
+  if (facts.languages.includes("go")) {
+    return [
+      { id: "vet", name: "go vet", command: "go", args: ["vet", "./..."] },
+      { id: "test", name: "go test", command: "go", args: ["test", "./..."] },
+      { id: "build", name: "go build", command: "go", args: ["build", "./..."] },
+    ]
+  }
+  return []
+}
+
+export interface StarterConfig {
+  processes: ProcessDefinition[]
+  verify: VerifyEntry[]
+}
+
+export function starterConfig(facts: ProjectFacts): StarterConfig {
+  const processes: ProcessDefinition[] = []
+  const manager: PackageManager | undefined = facts.packageManager?.manager
+  if (manager && facts.devScript) {
+    const framework = facts.frameworks[0]
+    processes.push({
+      id: "dev",
+      name: framework?.name ?? `${manager} ${facts.devScript}`,
+      command: manager,
+      args: runScriptArgs(manager, facts.devScript),
+      ...(framework ? { url: `localhost:${framework.port}`, readiness: { port: framework.port } } : {}),
+    })
+  }
+  return { processes, verify: toolchainVerify(facts) }
+}
+
+/** Render the starter as a `.devcc.ts` file. Plain object: no dependency on devcc is required. */
+export function renderStarterConfig(facts: ProjectFacts, date = new Date()): string {
+  const starter = starterConfig(facts)
+  const lines = [
+    `/**`,
+    ` * devcc configuration for ${facts.name}, generated by \`devcc init\` on ${date.toISOString().slice(0, 10)}.`,
+    ` *`,
+    ` * Everything here is optional. Check it with \`devcc config check\`; refine it with`,
+    ` * \`devcc init --agent claude\` (or codex). Reference: https://www.npmjs.com/package/@doriandev/devcc`,
+    ` */`,
+    `export default {`,
+  ]
+
+  if (starter.processes.length > 0) {
+    lines.push(`  processes: ${literal(starter.processes, 2)},`, ``)
+  } else {
+    lines.push(
+      `  // processes: [{ id: "web", command: "pnpm", args: ["dev"], readiness: { port: 3000 } }],`,
+      ``,
+    )
+  }
+
+  if (starter.verify.length > 0) {
+    lines.push(`  // \`devcc verify\` runs these in order and exits 0 only if all pass.`)
+    lines.push(`  verify: ${literal(starter.verify, 2)},`, ``)
+  } else {
+    lines.push(`  // verify: ["lint", "test"],`, ``)
+  }
+
+  lines.push(
+    `  // editor: { command: "code" },`,
+    `  // agents: { claude: { args: ["--permission-mode", "acceptEdits"] } },`,
+    `}`,
+    ``,
+  )
+  return lines.join("\n")
+}
+
+/** A TypeScript object literal: identifier keys unquoted, values JSON-encoded. */
+export function literal(value: unknown, indent = 0): string {
+  const pad = " ".repeat(indent)
+  const inner = " ".repeat(indent + 2)
+  if (Array.isArray(value)) {
+    if (value.every((item) => typeof item !== "object" || item === null)) {
+      return `[${value.map((item) => literal(item)).join(", ")}]`
+    }
+    return `[\n${value.map((item) => `${inner}${literal(item, indent + 2)},`).join("\n")}\n${pad}]`
+  }
+  if (typeof value === "object" && value !== null) {
+    const entries = Object.entries(value).filter(([, entry]) => entry !== undefined)
+    const rendered = entries.map(
+      ([key, entry]) =>
+        `${/^[A-Za-z_$][\w$]*$/u.test(key) ? key : JSON.stringify(key)}: ${literal(entry, indent + 2)}`,
+    )
+    const oneLine = `{ ${rendered.join(", ")} }`
+    if (oneLine.length + indent <= 100 && !oneLine.includes("\n")) return oneLine
+    return `{\n${rendered.map((entry) => `${inner}${entry},`).join("\n")}\n${pad}}`
+  }
+  return JSON.stringify(value)
+}
+
+/** Short file contents for the prompt, so the agent starts from real data. */
+export function readSnippet(path: string, maxLength = 2_000): string | null {
+  try {
+    const text = readFileSync(path, "utf8")
+    return text.length > maxLength ? `${text.slice(0, maxLength)}\n…` : text
+  } catch {
+    return null
+  }
+}