@doriandev/devcc 0.1.2 → 0.3.0

package/src/devcc/services/remote.ts

@@ -0,0 +1,306 @@
+import type { RemoteMachineConfig } from "../core/config.js"
+import { findExecutable, firstLine, type Exec, type Which } from "../environment/tools.js"
+import { exec, probeTcpPort } from "../utils/exec.js"
+import type { ScopedLogger } from "../utils/logger.js"
+import type { ServiceAdapter, ServiceSnapshot, ServiceStatus, ServiceStatusItem } from "./types.js"
+
+/**
+ * Remote development machines and Tailscale.
+ *
+ * Both are observed, never managed: devcc resolves hosts through the user's own
+ * SSH configuration, checks reachability, and reads Tailscale's structured
+ * status. Opening a session is a separate, explicit action (see `platform/`).
+ */
+
+const REMOTE_REFRESH_MS = 60_000
+const TAILSCALE_REFRESH_MS = 30_000
+
+// ---------------------------------------------------------------------------
+// SSH configuration
+// ---------------------------------------------------------------------------
+
+export interface SshTarget {
+  hostname: string
+  port: number
+  user?: string
+}
+
+/** Arguments for `ssh -G`, which prints the effective config without connecting. */
+export function sshConfigArgs(machine: Pick<RemoteMachineConfig, "host" | "port" | "user">): string[] {
+  const args = ["-G"]
+  if (machine.port) args.push("-p", String(machine.port))
+  if (machine.user) args.push("-l", machine.user)
+  args.push(machine.host)
+  return args
+}
+
+/** Parse the `key value` lines of `ssh -G`. */
+export function parseSshConfig(output: string): Partial<SshTarget> {
+  const target: Partial<SshTarget> = {}
+  for (const line of output.split("\n")) {
+    const [key, ...rest] = line.trim().split(/\s+/u)
+    const value = rest.join(" ")
+    if (!value) continue
+    if (key === "hostname") target.hostname = value
+    else if (key === "port" && Number.isInteger(Number(value))) target.port = Number(value)
+    else if (key === "user") target.user = value
+  }
+  return target
+}
+
+/** The destination `ssh` should connect to: the alias, so the user's config applies in full. */
+export function sshDestination(machine: Pick<RemoteMachineConfig, "host" | "user">): string {
+  return machine.user ? `${machine.user}@${machine.host}` : machine.host
+}
+
+// ---------------------------------------------------------------------------
+// Tailscale
+// ---------------------------------------------------------------------------
+
+export interface TailscaleNode {
+  hostName: string
+  /** MagicDNS name without the trailing dot. */
+  dnsName: string
+  ips: string[]
+  online: boolean
+  os?: string
+}
+
+export interface TailscaleStatus {
+  backendState: string
+  connected: boolean
+  self?: TailscaleNode
+  peers: TailscaleNode[]
+  tailnet?: string
+}
+
+function asNode(value: unknown): TailscaleNode | undefined {
+  if (typeof value !== "object" || value === null) return undefined
+  const node = value as Record<string, unknown>
+  return {
+    hostName: typeof node.HostName === "string" ? node.HostName : "",
+    dnsName: typeof node.DNSName === "string" ? node.DNSName.replace(/\.$/u, "") : "",
+    ips: Array.isArray(node.TailscaleIPs)
+      ? node.TailscaleIPs.filter((ip): ip is string => typeof ip === "string")
+      : [],
+    online: node.Online === true,
+    os: typeof node.OS === "string" ? node.OS : undefined,
+  }
+}
+
+/** Parse `tailscale status --json`. Returns null for output that is not a status object. */
+export function parseTailscaleStatus(output: string): TailscaleStatus | null {
+  let data: unknown
+  try {
+    data = JSON.parse(output)
+  } catch {
+    return null
+  }
+  if (typeof data !== "object" || data === null) return null
+  const status = data as Record<string, unknown>
+  const backendState = typeof status.BackendState === "string" ? status.BackendState : "Unknown"
+  const peerRecord = typeof status.Peer === "object" && status.Peer !== null ? status.Peer : {}
+  const tailnet = (status.CurrentTailnet as { Name?: unknown } | undefined)?.Name
+  return {
+    backendState,
+    connected: backendState === "Running",
+    self: asNode(status.Self),
+    peers: Object.values(peerRecord)
+      .map(asNode)
+      .filter((node): node is TailscaleNode => node !== undefined),
+    tailnet: typeof tailnet === "string" ? tailnet : undefined,
+  }
+}
+
+/** Find the tailnet peer a configured host refers to: MagicDNS name, short name, host name or IP. */
+export function findTailscalePeer(status: TailscaleStatus, host: string): TailscaleNode | undefined {
+  const wanted = host.toLowerCase().replace(/\.$/u, "")
+  return status.peers.find((peer) => {
+    const dns = peer.dnsName.toLowerCase()
+    return (
+      dns === wanted ||
+      dns.split(".")[0] === wanted ||
+      peer.hostName.toLowerCase() === wanted ||
+      peer.ips.includes(host)
+    )
+  })
+}
+
+export interface TailscaleServiceOptions {
+  /** Hosts of configured remote machines, shown when they are tailnet peers. */
+  machines?: readonly RemoteMachineConfig[]
+  run?: Exec
+  which?: Which
+  logger?: ScopedLogger
+}
+
+const TAILSCALE_APP_CLI = "/Applications/Tailscale.app/Contents/MacOS/Tailscale"
+
+export class TailscaleService implements ServiceAdapter {
+  readonly id = "tailscale"
+  readonly name = "Tailscale"
+  readonly category = "remote" as const
+  readonly refreshIntervalMs = TAILSCALE_REFRESH_MS
+
+  private readonly run: Exec
+  private readonly which: Which
+  private last: TailscaleStatus | null = null
+
+  constructor(private readonly options: TailscaleServiceOptions = {}) {
+    this.run = options.run ?? exec
+    this.which = options.which ?? ((command) => findExecutable(command))
+  }
+
+  /** The most recent parsed status, for remote machines to look up peers. */
+  getLastStatus(): TailscaleStatus | null {
+    return this.last
+  }
+
+  private command(): string | undefined {
+    return this.which("tailscale") ?? this.which(TAILSCALE_APP_CLI)
+  }
+
+  async detect(): Promise<boolean> {
+    return this.command() !== undefined
+  }
+
+  async getStatus(): Promise<ServiceStatus> {
+    const checkedAt = new Date()
+    const command = this.command()
+    if (!command) return { state: "unavailable", detail: "not installed", checkedAt }
+
+    const result = await this.run(command, ["status", "--json"], {
+      timeoutMs: 4_000,
+      logger: this.options.logger,
+    })
+    const status = parseTailscaleStatus(result.stdout)
+    this.last = status
+    if (!status) {
+      const reason = result.timedOut ? "no answer" : (firstLine(result.stderr) ?? "status unavailable")
+      return { state: "unknown", detail: reason, checkedAt }
+    }
+
+    const items: ServiceStatusItem[] = []
+    for (const machine of this.options.machines ?? []) {
+      const peer = findTailscalePeer(status, machine.host)
+      if (!peer) continue
+      items.push({
+        name: machine.name,
+        state: peer.online ? "running" : "stopped",
+        detail: `${peer.dnsName || peer.hostName} · ${peer.online ? "online" : "offline"}`,
+      })
+    }
+
+    if (!status.connected) {
+      return { state: "stopped", detail: `disconnected (${status.backendState})`, items, checkedAt }
+    }
+    const online = status.peers.filter((peer) => peer.online).length
+    return {
+      state: "running",
+      endpoint: status.self?.dnsName || status.self?.ips[0],
+      detail: `connected · ${online}/${status.peers.length} peers online`,
+      items,
+      checkedAt,
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Remote machines
+// ---------------------------------------------------------------------------
+
+export interface RemoteMachineServiceOptions {
+  machine: RemoteMachineConfig
+  run?: Exec
+  probe?: (port: number, host: string, timeoutMs: number) => Promise<boolean>
+  /** Current Tailscale status, when the Tailscale adapter has one. */
+  tailscale?: () => TailscaleStatus | null
+  /** Status of an associated service by id. */
+  service?: (id: string) => ServiceSnapshot | undefined
+  logger?: ScopedLogger
+}
+
+export function remoteServiceId(machineId: string): string {
+  return `remote:${machineId}`
+}
+
+/**
+ * A configured remote machine as a service: reachability of its SSH port, the
+ * effective target from `ssh -G`, Tailscale presence and associated services.
+ * It connects to nothing but the TCP port, and only once a minute while polling.
+ */
+export class RemoteMachineService implements ServiceAdapter {
+  readonly id: string
+  readonly name: string
+  readonly category = "remote" as const
+  readonly refreshIntervalMs = REMOTE_REFRESH_MS
+
+  private readonly run: Exec
+  private readonly probe: (port: number, host: string, timeoutMs: number) => Promise<boolean>
+  private target: SshTarget | null = null
+
+  constructor(private readonly options: RemoteMachineServiceOptions) {
+    this.id = remoteServiceId(options.machine.id)
+    this.name = options.machine.name
+    this.run = options.run ?? exec
+    this.probe = options.probe ?? probeTcpPort
+  }
+
+  get machine(): RemoteMachineConfig {
+    return this.options.machine
+  }
+
+  async detect(): Promise<boolean> {
+    return true
+  }
+
+  /** Effective host/port/user, resolved once through `ssh -G` and cached. */
+  async resolveTarget(): Promise<SshTarget> {
+    if (this.target) return this.target
+    const { machine } = this.options
+    const result = await this.run("ssh", sshConfigArgs(machine), {
+      timeoutMs: 3_000,
+      logger: this.options.logger,
+    })
+    const parsed = result.ok ? parseSshConfig(result.stdout) : {}
+    const target: SshTarget = {
+      hostname: parsed.hostname ?? machine.host,
+      port: machine.port ?? parsed.port ?? 22,
+      user: machine.user ?? parsed.user,
+    }
+    if (result.ok) this.target = target
+    return target
+  }
+
+  async getStatus(): Promise<ServiceStatus> {
+    const checkedAt = new Date()
+    const { machine } = this.options
+    const target = await this.resolveTarget()
+    const endpoint = `${target.user ? `${target.user}@` : ""}${target.hostname}:${target.port}`
+
+    const startedAt = Date.now()
+    const reachable = await this.probe(target.port, target.hostname, 2_000)
+    const latencyMs = Date.now() - startedAt
+
+    const tailscale = this.options.tailscale?.()
+    const peer = tailscale
+      ? (findTailscalePeer(tailscale, machine.host) ?? findTailscalePeer(tailscale, target.hostname))
+      : undefined
+
+    const items: ServiceStatusItem[] = (machine.services ?? []).map((serviceId) => {
+      const snapshot = this.options.service?.(serviceId)
+      return snapshot
+        ? { name: snapshot.name, state: snapshot.status.state, detail: snapshot.status.detail }
+        : { name: serviceId, state: "unknown" as const, detail: "not checked yet" }
+    })
+
+    const detail = [
+      reachable ? `ssh reachable · ${latencyMs}ms` : "ssh unreachable",
+      peer ? `tailscale ${peer.online ? "online" : "offline"}` : undefined,
+    ]
+      .filter(Boolean)
+      .join(" · ")
+
+    return { state: reachable ? "running" : "stopped", endpoint, detail, items, checkedAt }
+  }
+}

package/src/devcc/services/types.ts

@@ -31,11 +31,19 @@ export interface ServiceActionContext {
   confirm: (title: string, message: string) => Promise<boolean>
 }
 
+export type ServiceCategory = "container" | "database" | "runtime" | "ai" | "web" | "remote"
+
 export interface ServiceAdapter {
   id: string
   name: string
   /** Grouping label shown in the Services view. */
-  category: "container" | "database" | "runtime" | "ai" | "web"
+  category: ServiceCategory
+  /**
+   * Minimum time between polled status checks. Remote and slow adapters set
+   * this so an open dashboard does not generate constant network traffic; an
+   * explicit refresh always checks immediately.
+   */
+  refreshIntervalMs?: number
 
   /** Cheap check: is this service relevant to this project/host at all? */
   detect: () => Promise<boolean>

package/src/devcc/utils/exec.ts

@@ -1,5 +1,6 @@
 import { spawn, type SpawnOptions } from "node:child_process"
 import { connect } from "node:net"
+import type { ScopedLogger } from "./logger.js"
 
 /**
  * Small, safe process helpers.
@@ -17,6 +18,11 @@ export interface ExecOptions {
   maxBuffer?: number
   input?: string
   signal?: AbortSignal
+  /**
+   * When given, each run is logged at debug level: executable, arguments, cwd,
+   * duration, exit code and failure reason. The environment is never logged.
+   */
+  logger?: ScopedLogger
 }
 
 export interface ExecResult {
@@ -41,7 +47,15 @@ export function exec(
   args: readonly string[] = [],
   options: ExecOptions = {},
 ): Promise<ExecResult> {
-  const { cwd, env, timeoutMs = DEFAULT_EXEC_TIMEOUT_MS, maxBuffer = 1024 * 1024, input, signal } = options
+  const {
+    cwd,
+    env,
+    timeoutMs = DEFAULT_EXEC_TIMEOUT_MS,
+    maxBuffer = 1024 * 1024,
+    input,
+    signal,
+    logger,
+  } = options
 
   return new Promise<ExecResult>((resolve) => {
     const startedAt = Date.now()
@@ -64,7 +78,17 @@ export function exec(
       settled = true
       clearTimeout(timer)
       signal?.removeEventListener("abort", onAbort)
-      resolve({ ...result, durationMs: Date.now() - startedAt })
+      const durationMs = Date.now() - startedAt
+      logger?.debug("exec", {
+        command,
+        args,
+        cwd,
+        durationMs,
+        code: result.code,
+        ...(result.timedOut ? { timedOut: true } : {}),
+        ...(result.spawnError ? { error: result.spawnError.message } : {}),
+      })
+      resolve({ ...result, durationMs })
     }
 
     const timer = setTimeout(() => {

package/src/devcc/verify/verify.ts

@@ -0,0 +1,316 @@
+import { spawn } from "node:child_process"
+import { isAbsolute, resolve } from "node:path"
+import type { CommandConfigEntry } from "../core/config.js"
+import { runScriptArgs, type PackageManager } from "../utils/packageManager.js"
+
+/**
+ * Project verification: the quality gate behind `devcc verify`.
+ *
+ * Steps are resolved from config (a command id, a package.json script, or an
+ * inline command) and run sequentially. The loop is independent of how a step
+ * executes, so the CLI can spawn directly while the TUI runs the same steps
+ * through the ProcessManager and gets log capture for free.
+ */
+
+export interface VerifyStepConfig {
+  id: string
+  name?: string
+  command: string
+  args?: string[]
+  cwd?: string
+}
+
+/** A command id or package.json script name, or an inline step. */
+export type VerifyEntry = string | VerifyStepConfig
+
+export interface VerifyStep {
+  id: string
+  name: string
+  command: string
+  args: string[]
+  cwd?: string
+  source: "command" | "script" | "inline"
+}
+
+export interface ResolveVerifyContext {
+  commands: readonly CommandConfigEntry[]
+  scripts: readonly { name: string }[]
+  packageManager: PackageManager
+}
+
+export interface ResolvedVerify {
+  steps: VerifyStep[]
+  issues: string[]
+}
+
+/**
+ * Turn config entries into runnable steps. A string names a configured
+ * command first, then a package.json script, so `verify: ["lint", "test"]`
+ * works without repeating what `package.json` already says.
+ */
+export function resolveVerifySteps(
+  entries: readonly VerifyEntry[],
+  context: ResolveVerifyContext,
+): ResolvedVerify {
+  const steps: VerifyStep[] = []
+  const issues: string[] = []
+
+  for (const entry of entries) {
+    if (typeof entry !== "string") {
+      steps.push({
+        id: entry.id,
+        name: entry.name ?? entry.id,
+        command: entry.command,
+        args: entry.args ?? [],
+        cwd: entry.cwd,
+        source: "inline",
+      })
+      continue
+    }
+
+    const command = context.commands.find((candidate) => candidate.id === entry)
+    if (command) {
+      steps.push({
+        id: entry,
+        name: command.title,
+        command: command.command,
+        args: command.args ?? [],
+        cwd: command.cwd,
+        source: "command",
+      })
+      continue
+    }
+
+    if (context.scripts.some((script) => script.name === entry)) {
+      steps.push({
+        id: entry,
+        name: entry,
+        command: context.packageManager,
+        args: runScriptArgs(context.packageManager, entry),
+        source: "script",
+      })
+      continue
+    }
+
+    issues.push(`verify: "${entry}" is neither a command id nor a package.json script`)
+  }
+
+  const seen = new Set<string>()
+  for (const step of steps) {
+    if (seen.has(step.id)) issues.push(`verify: step "${step.id}" is listed more than once`)
+    seen.add(step.id)
+  }
+
+  return { steps, issues }
+}
+
+/** Config issues about `verify`, which must block a run rather than silently shrink it. */
+export function isVerifyIssue(issue: string): boolean {
+  return issue.startsWith("verify") || issue.startsWith('"verify"')
+}
+
+export type VerifyStepStatus = "pending" | "running" | "passed" | "failed" | "skipped"
+
+export interface VerifyStepResult {
+  id: string
+  name: string
+  command: string
+  args: string[]
+  status: VerifyStepStatus
+  exitCode: number | null
+  durationMs: number
+  stdout: string
+  stderr: string
+  /** Why the step could not run or was stopped (spawn error, signal, cancellation). */
+  error?: string
+}
+
+export interface VerifyReport {
+  ok: boolean
+  passed: number
+  failed: number
+  skipped: number
+  total: number
+  durationMs: number
+  steps: VerifyStepResult[]
+}
+
+export interface StepOutcome {
+  exitCode: number | null
+  stdout?: string
+  stderr?: string
+  error?: string
+}
+
+export type StepExecutor = (step: VerifyStep, signal: AbortSignal) => Promise<StepOutcome>
+
+export interface RunVerificationOptions {
+  /** Called whenever a step changes state, with the full current list. */
+  onProgress?: (steps: readonly VerifyStepResult[]) => void
+  signal?: AbortSignal
+}
+
+/**
+ * Run every step in order. A failing step does not stop the run: the report
+ * shows every failure at once. Cancelling marks the remaining steps skipped.
+ */
+export async function runVerification(
+  steps: readonly VerifyStep[],
+  execute: StepExecutor,
+  options: RunVerificationOptions = {},
+): Promise<VerifyReport> {
+  const startedAt = Date.now()
+  const signal = options.signal ?? new AbortController().signal
+  const results: VerifyStepResult[] = steps.map((step) => ({
+    id: step.id,
+    name: step.name,
+    command: step.command,
+    args: step.args,
+    status: "pending",
+    exitCode: null,
+    durationMs: 0,
+    stdout: "",
+    stderr: "",
+  }))
+  const progress = () => options.onProgress?.(results.map((result) => ({ ...result })))
+
+  for (const [index, step] of steps.entries()) {
+    const result = results[index] as VerifyStepResult
+    if (signal.aborted) {
+      result.status = "skipped"
+      result.error = "cancelled"
+      continue
+    }
+
+    result.status = "running"
+    progress()
+    const stepStart = Date.now()
+    let outcome: StepOutcome
+    try {
+      outcome = await execute(step, signal)
+    } catch (error) {
+      outcome = { exitCode: null, error: error instanceof Error ? error.message : String(error) }
+    }
+
+    result.durationMs = Date.now() - stepStart
+    result.exitCode = outcome.exitCode
+    result.stdout = outcome.stdout ?? ""
+    result.stderr = outcome.stderr ?? ""
+    if (outcome.error) result.error = outcome.error
+    result.status = outcome.exitCode === 0 && !outcome.error ? "passed" : "failed"
+    progress()
+  }
+  if (signal.aborted) progress()
+
+  const passed = results.filter((result) => result.status === "passed").length
+  const failed = results.filter((result) => result.status === "failed").length
+  const skipped = results.filter((result) => result.status === "skipped").length
+  return {
+    ok: failed === 0 && skipped === 0 && results.length > 0,
+    passed,
+    failed,
+    skipped,
+    total: results.length,
+    durationMs: Date.now() - startedAt,
+    steps: results,
+  }
+}
+
+/** One-line summary: `5/5 passed` or `3/5 passed, 2 failed (lint, test)`. */
+export function summariseVerify(
+  report: Pick<VerifyReport, "passed" | "failed" | "skipped" | "total" | "steps">,
+): string {
+  const parts = [`${report.passed}/${report.total} passed`]
+  if (report.failed > 0) {
+    const names = report.steps.filter((step) => step.status === "failed").map((step) => step.name)
+    parts.push(`${report.failed} failed (${names.join(", ")})`)
+  }
+  if (report.skipped > 0) parts.push(`${report.skipped} skipped`)
+  return parts.join(", ")
+}
+
+// eslint-disable-next-line no-control-regex
+const ANSI_PATTERN = /\u001b\[[0-?]*[ -/]*[@-~]|\u001b\][^\u0007]*(?:\u0007|\u001b\\)/gu
+
+/** Remove terminal escape sequences, so JSON and logs stay plain text. */
+export function stripAnsi(text: string): string {
+  return text.replace(ANSI_PATTERN, "")
+}
+
+/** Keep the end of a long output, where test runners and compilers put the verdict. */
+export function keepTail(text: string, maxLength: number): string {
+  if (text.length <= maxLength) return text
+  return `…[${text.length - maxLength} characters truncated]\n${text.slice(-maxLength)}`
+}
+
+export interface SpawnExecutorOptions {
+  rootDir: string
+  env?: NodeJS.ProcessEnv
+  /** Characters of stdout/stderr kept per step (default 200k, from the end). */
+  maxOutput?: number
+  /** Live output, e.g. to mirror a failing step. */
+  onOutput?: (step: VerifyStep, chunk: string, stream: "stdout" | "stderr") => void
+}
+
+/**
+ * Executor for the CLI: `spawn(command, args)` in the project, colour disabled,
+ * output captured (tail kept) and ANSI-stripped. No shell, no timeout - a test
+ * suite takes as long as it takes - but an abort signal stops the child.
+ */
+export function createSpawnExecutor(options: SpawnExecutorOptions): StepExecutor {
+  const maxOutput = options.maxOutput ?? 200_000
+  return (step, signal) =>
+    new Promise<StepOutcome>((resolvePromise) => {
+      const cwd = step.cwd
+        ? isAbsolute(step.cwd)
+          ? step.cwd
+          : resolve(options.rootDir, step.cwd)
+        : options.rootDir
+      let stdout = ""
+      let stderr = ""
+      const append = (current: string, chunk: string) => {
+        const next = current + chunk
+        return next.length > maxOutput * 2 ? next.slice(-maxOutput) : next
+      }
+
+      const child = spawn(step.command, step.args, {
+        cwd,
+        env: { ...(options.env ?? process.env), FORCE_COLOR: "0", NO_COLOR: "1" },
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+      })
+
+      const onAbort = () => child.kill("SIGTERM")
+      signal.addEventListener("abort", onAbort, { once: true })
+
+      child.stdout.setEncoding("utf8")
+      child.stdout.on("data", (chunk: string) => {
+        stdout = append(stdout, chunk)
+        options.onOutput?.(step, chunk, "stdout")
+      })
+      child.stderr.setEncoding("utf8")
+      child.stderr.on("data", (chunk: string) => {
+        stderr = append(stderr, chunk)
+        options.onOutput?.(step, chunk, "stderr")
+      })
+
+      let settled = false
+      const finish = (outcome: StepOutcome) => {
+        if (settled) return
+        settled = true
+        signal.removeEventListener("abort", onAbort)
+        resolvePromise({
+          ...outcome,
+          stdout: keepTail(stripAnsi(stdout), maxOutput),
+          stderr: keepTail(stripAnsi(stderr), maxOutput),
+        })
+      }
+
+      child.once("error", (error) => finish({ exitCode: null, error: error.message }))
+      child.once("close", (code, closeSignal) => {
+        if (signal.aborted) finish({ exitCode: code, error: "cancelled" })
+        else if (closeSignal) finish({ exitCode: code, error: `terminated by ${closeSignal}` })
+        else finish({ exitCode: code })
+      })
+    })
+}