@doriandev/devcc 0.2.0 → 0.3.0

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
+  }
+}

package/src/devcc/init/prompt.ts

@@ -0,0 +1,179 @@
+import { basename } from "node:path"
+import { readSnippet, renderStarterConfig, type ProjectFacts } from "./detect.js"
+
+/**
+ * The prompt that lets a coding agent set up devcc for a project.
+ *
+ * It carries what devcc already detected (so the agent verifies rather than
+ * rediscovers), a draft to start from, the config reference, and firm rules:
+ * never invent commands, never guess hosts, keep verify non-interactive.
+ *
+ * Two delivery modes:
+ * - `write`: an interactive agent edits `.devcc.ts` itself and checks its work
+ *   with `devcc config check` (used by `devcc init --agent`).
+ * - `print`: a headless agent prints the file between markers; devcc validates
+ *   it and asks before writing (used from the dashboard, where the agent has no
+ *   permission to edit files).
+ */
+
+export type SetupPromptMode = "write" | "print"
+
+export const CONFIG_BEGIN_MARKER = "----- BEGIN .devcc.ts -----"
+export const CONFIG_END_MARKER = "----- END .devcc.ts -----"
+
+const REFERENCE = `
+## .devcc.ts reference (all fields optional)
+
+export default {
+  name?: string,                       // header label
+  processes?: [{                       // long-running things devcc starts/stops
+    id, name?, command, args?: string[], cwd?, env?: Record<string, string>,
+    kind?: "service" | "task", autoStart?: boolean, url?: string, port?: number,
+    dependsOn?: string[],              // ids that must be ready first
+    readiness?: { port?: number, host?: string, logPattern?: string, timeoutMs?: number },
+    restartOnCrash?: boolean,
+  }],
+  commands?: [{                        // palette actions
+    id, title, category?, command, args?, cwd?, keywords?: string[],
+    confirm?: true | { title, message }, // REQUIRED for anything destructive
+  }],
+  verify?: (string | { id, name?, command, args?, cwd? })[],
+                                       // strings = command ids, then package.json script names
+  services?: [                         // extra things to watch
+    { id, name?, port, host?, healthPath? } |
+    { id, name?, type: "ollama", baseUrl: "http://host:11434" },
+  ],
+  agents?: { claude?: { command?, args? }, codex?: { command?, args? } },
+  editor?: { command: "code" | "zed" | "cursor" | "webstorm" } | { application: "WebStorm" },
+  terminal?: { application: "iTerm" } | { command, args?, execArgs? },
+  worktrees?: { directory?: string },  // relative to the main worktree, default ".."
+  remoteMachines?: [{ id, name?, host, transport: "ssh", port?, user?, services?: string[] }],
+  refresh?: { system?, services?, git?, clock? },
+}
+
+Everything is spawned as command + args with no shell: never put pipes, &&, env assignments or
+quotes inside a single string. \`command: "pnpm", args: ["run", "dev"]\` is right;
+\`command: "pnpm run dev"\` is wrong.`
+
+function factsSection(facts: ProjectFacts): string {
+  const lines = [
+    `- root: ${facts.rootDir}`,
+    `- name: ${facts.name}`,
+    `- git repository: ${facts.hasGit ? "yes" : "no"}`,
+    `- languages: ${facts.languages.join(", ") || "none detected"}`,
+    `- package manager: ${facts.packageManager ? `${facts.packageManager.manager} (from ${facts.packageManager.source})` : "none (no package.json)"}`,
+    `- monorepo: ${facts.monorepo ?? "no"}`,
+    `- frameworks (by dependency): ${facts.frameworks.map((framework) => `${framework.name} (default port ${framework.port})`).join(", ") || "none recognised"}`,
+    `- notable files: ${facts.files.join(", ") || "none"}`,
+    `- existing devcc config: ${facts.configPath ? basename(facts.configPath) : "none"}`,
+  ]
+  if (facts.scripts.length > 0) {
+    lines.push(`- package.json scripts:`)
+    for (const script of facts.scripts) lines.push(`  - ${script.name}: ${script.command}`)
+  }
+  if (facts.skippedScripts.length > 0) {
+    lines.push(
+      `- left out of verify: ${facts.skippedScripts.map((script) => `${script.name} (${script.reason})`).join(", ")}`,
+    )
+  }
+  return lines.join("\n")
+}
+
+export function buildSetupPrompt(facts: ProjectFacts, mode: SetupPromptMode): string {
+  const existing = facts.configPath ? readSnippet(facts.configPath, 6_000) : null
+  const draft = renderStarterConfig(facts)
+
+  const output =
+    mode === "write"
+      ? `## Deliver
+
+1. ${facts.configPath ? `Update \`${basename(facts.configPath)}\` in place, keeping anything the user wrote that is still correct.` : "Create `.devcc.ts` in the project root."}
+2. Run \`devcc config check\` and fix every issue it reports. Do not stop until it exits 0.
+3. If you added \`verify\`, run \`devcc verify\`. A step that fails because the project itself is broken
+   stays in the list - report it; do not delete checks to make the gate pass.
+4. Finish with a short summary: what you configured, what you deliberately left out, and why.`
+      : `## Deliver
+
+You cannot edit files in this session. Print the complete file, and nothing else between the markers,
+exactly like this:
+
+${CONFIG_BEGIN_MARKER}
+export default {
+  ...
+}
+${CONFIG_END_MARKER}
+
+devcc validates it and asks the user before writing it${facts.configPath ? ` over \`${basename(facts.configPath)}\`` : ""}. After the markers, add
+a short summary: what you configured, what you left out, and why.`
+
+  return `Set up devcc for this project: produce a solid .devcc.ts.
+
+devcc (@doriandev/devcc) is a keyboard-driven terminal dashboard for local development. Its config
+tells it which dev processes it may start, which checks \`devcc verify\` runs as the quality gate, and
+which commands appear in its palette. You are configuring it for the repository in your working
+directory.
+
+## What devcc already detected
+
+${factsSection(facts)}
+
+## Draft from \`devcc init\`
+
+Start from this, but verify every line against the repository - it only knows script names.
+
+\`\`\`ts
+${draft.trimEnd()}
+\`\`\`
+${existing ? `\n## Current config (${basename(facts.configPath ?? "")})\n\n\`\`\`ts\n${existing.trimEnd()}\n\`\`\`\n` : ""}
+## Investigate before writing
+
+- Read package.json (every workspace package in a monorepo), the README, CONTRIBUTING, AGENTS.md or
+  CLAUDE.md, CI workflows (.github/workflows), Makefile/justfile, docker compose files, framework
+  configs (next.config.*, vite.config.*, etc.) and .env.example.
+- Find the real dev servers and their ports. Ports come from scripts, framework config or
+  .env.example - not from defaults when the project overrides them.
+- CI shows what the team treats as the quality gate; mirror it in \`verify\` where it can run locally.
+
+## Rules
+
+- Only use commands that exist in this repository or are the standard CLI of a toolchain it uses. Never
+  invent scripts, binaries or ports.
+- \`processes\`: long-running dev servers, watchers and local infra the developer starts by hand. Use
+  \`readiness\` with the real port (or a \`logPattern\` from the server's actual output) and \`dependsOn\`
+  when one service needs another. In a monorepo, one process per app with \`cwd\`. Do not set
+  \`autoStart\` unless the README says the project is always run that way.
+- \`verify\`: fast to slow (format check, lint, typecheck, tests, build). Every step must be
+  non-interactive, exit on its own, and not modify files (no --watch, --fix or --write). Prefer
+  package.json script names over inline steps.
+- \`commands\`: useful project tasks that are not already scripts devcc shows (migrations, seeding,
+  codegen, docker compose profiles). Anything that deletes, resets, migrates or deploys needs
+  \`confirm: true\`.
+- Never add secrets, tokens, credentials or values from .env files. Never add \`remoteMachines\`,
+  hostnames or IP addresses unless the repository documents them for local development.
+- Leave out \`editor\`, \`terminal\` and \`agents\` unless the repository states a preference; they are
+  personal. Leave out anything you are unsure of rather than guessing - a small correct config beats a
+  large wrong one.
+- Use a plain \`export default { ... }\` object. Import \`defineConfig\` from "@doriandev/devcc" only if that
+  package is already a dependency of this project.
+${REFERENCE}
+
+${output}
+`
+}
+
+/**
+ * Pull the config out of a headless agent's output: the last block between the
+ * markers, with a surrounding code fence removed. Null when there is none.
+ */
+export function extractConfigFromOutput(output: string): string | null {
+  const end = output.lastIndexOf(CONFIG_END_MARKER)
+  if (end === -1) return null
+  const begin = output.lastIndexOf(CONFIG_BEGIN_MARKER, end)
+  if (begin === -1) return null
+  const body = output
+    .slice(begin + CONFIG_BEGIN_MARKER.length, end)
+    .replace(/^\s*```[a-z]*\s*\n/u, "")
+    .replace(/\n\s*```\s*$/u, "")
+    .trim()
+  return body === "" ? null : `${body}\n`
+}

package/src/devcc/services/node.ts

@@ -73,7 +73,7 @@ export class PortService implements ServiceAdapter {
   }
 }
 
-interface FrameworkHint {
+export interface FrameworkHint {
   /** Dependency name to look for in package.json. */
   dependency: string
   id: string
@@ -108,20 +108,26 @@ function dependencyNames(packageJson: Record<string, unknown> | null): Set<strin
   return names
 }
 
+/** Frameworks this project depends on, in hint order, one per port. */
+export function detectFrameworks(packageJson: Record<string, unknown> | null): FrameworkHint[] {
+  const dependencies = dependencyNames(packageJson)
+  const seenPorts = new Set<number>()
+  const found: FrameworkHint[] = []
+  for (const hint of FRAMEWORK_HINTS) {
+    if (!dependencies.has(hint.dependency) || seenPorts.has(hint.port)) continue
+    seenPorts.add(hint.port)
+    found.push(hint)
+  }
+  return found
+}
+
 /**
  * Build port adapters for frameworks this project actually depends on.
  * Nothing is assumed: a project with none of these gets no adapters.
  */
 export function detectNodeServices(packageJson: Record<string, unknown> | null): PortService[] {
-  const dependencies = dependencyNames(packageJson)
-  const seenPorts = new Set<number>()
-  const adapters: PortService[] = []
-
-  for (const hint of FRAMEWORK_HINTS) {
-    if (!dependencies.has(hint.dependency)) continue
-    if (seenPorts.has(hint.port)) continue
-    seenPorts.add(hint.port)
-    adapters.push(
+  return detectFrameworks(packageJson).map(
+    (hint) =>
       new PortService({
         id: hint.id,
         name: hint.name,
@@ -130,8 +136,5 @@ export function detectNodeServices(packageJson: Record<string, unknown> | null):
         healthPath: hint.healthPath,
         onlyWhenListening: true,
       }),
-    )
-  }
-
-  return adapters
+  )
 }

package/src/devcc/views/OverviewView.ts

@@ -95,7 +95,14 @@ export class OverviewView extends View {
     rows.push(blank())
     rows.push(section("Development"))
     if (state.processes.length === 0) {
-      rows.push(info("", "no managed processes - add some in .devcc.ts"))
+      rows.push(
+        info(
+          "",
+          state.project.configPath
+            ? "no managed processes - add some in .devcc.ts"
+            : "no .devcc.ts yet - press / and run “Project: set up .devcc.ts”",
+        ),
+      )
     } else {
       for (const process of state.processes.slice(0, compact ? 4 : 8)) {
         const detail = process.url ?? (process.pid ? `pid ${process.pid}` : "")