@vladpazych/dexter 0.1.0

package/src/meta/domain/quality.ts

@@ -0,0 +1,145 @@
+/**
+ * Quality gates — auto-fix then gate before commit.
+ *
+ * Prettier and ESLint run in fix mode (deterministic, always safe).
+ * Typecheck is gate-only (no auto-fix possible).
+ */
+
+import { join, relative } from "node:path"
+
+import type { ControlPorts } from "../ports.ts"
+import type { Package, QualityCheck, QualityResult } from "../types.ts"
+
+import { discoverPackages, filterByFiles } from "./workspace.ts"
+
+const SKIP_PATTERNS = ["node_modules/", "dist/", ".next/", "coverage/", ".d.ts", "routeTree.gen.ts"]
+
+const LINT_EXTS = [".ts", ".tsx"]
+const FORMAT_EXTS = [".ts", ".tsx", ".js", ".jsx", ".json", ".md", ".css", ".html", ".yaml", ".yml"]
+const TYPECHECK_EXTS = [".ts", ".tsx"]
+
+function hasExt(file: string, exts: string[]): boolean {
+  return exts.some((ext) => file.endsWith(ext))
+}
+
+function isSkipped(file: string): boolean {
+  return SKIP_PATTERNS.some((p) => file.includes(p))
+}
+
+export function isLintable(file: string): boolean {
+  return hasExt(file, LINT_EXTS) && !isSkipped(file)
+}
+
+export function isFormattable(file: string): boolean {
+  return hasExt(file, FORMAT_EXTS) && !isSkipped(file)
+}
+
+export function isTypecheckable(file: string): boolean {
+  return hasExt(file, TYPECHECK_EXTS) && !isSkipped(file)
+}
+
+function collectOutput(ports: ControlPorts, cmd: string, args: string[], cwd: string): Promise<QualityCheck> {
+  return new Promise((resolve) => {
+    const lines: string[] = []
+    const handle = ports.process.spawn({ cmd, args, cwd })
+
+    handle.onLine("stdout", (line) => lines.push(line))
+    handle.onLine("stderr", (line) => lines.push(line))
+
+    handle.wait().then((code) => {
+      resolve({
+        name: `${cmd} ${args[0] ?? ""}`.trim(),
+        status: code === 0 ? "pass" : "fail",
+        output: lines.join("\n"),
+      })
+    })
+  })
+}
+
+function scopedTypecheck(ports: ControlPorts, pkg: Package, committedFiles: string[]): Promise<QualityCheck> {
+  return new Promise((resolve) => {
+    const lines: string[] = []
+    const handle = ports.process.spawn({ cmd: "bun", args: ["run", "typecheck"], cwd: pkg.dir })
+
+    handle.onLine("stdout", (line) => lines.push(line))
+    handle.onLine("stderr", (line) => lines.push(line))
+
+    handle.wait().then((code) => {
+      const name = `typecheck (${pkg.shortName})`
+
+      if (code === 0) {
+        resolve({ name, status: "pass", output: "" })
+        return
+      }
+
+      // Filter to errors in committed files only
+      const relFiles = committedFiles
+        .filter((f) => f.startsWith(pkg.relDir + "/"))
+        .map((f) => f.slice(pkg.relDir.length + 1))
+
+      const relevant = lines.filter((line) => relFiles.some((f) => line.startsWith(f + "(")))
+
+      resolve({
+        name,
+        status: relevant.length > 0 ? "fail" : "pass",
+        output: relevant.join("\n"),
+      })
+    })
+  })
+}
+
+export async function checkQuality(ports: ControlPorts, files: string[]): Promise<QualityResult> {
+  const checks: Promise<QualityCheck>[] = []
+
+  const existing = files.filter((f) => ports.fs.exists(join(ports.root, f)))
+  const lintFiles = existing.filter(isLintable)
+  const formatFiles = existing.filter(isFormattable)
+
+  const packages = discoverPackages(ports)
+
+  // ESLint on lintable files — package-aware routing
+  if (lintFiles.length > 0) {
+    const lintAffected = filterByFiles(packages, lintFiles, ports.root)
+    const pkgWithConfig = lintAffected.filter((pkg) => ports.fs.exists(join(pkg.dir, "eslint.config.js")))
+    const pkgFiles = new Set<string>()
+
+    for (const pkg of pkgWithConfig) {
+      const pkgSpecific = lintFiles.filter((f) => f.startsWith(pkg.relDir + "/"))
+      for (const f of pkgSpecific) pkgFiles.add(f)
+      if (pkgSpecific.length > 0) {
+        const relFiles = pkgSpecific.map((f) => relative(pkg.relDir, f))
+        checks.push(collectOutput(ports, "bunx", ["eslint", "--fix", "--no-warn-ignored", ...relFiles], pkg.dir))
+      }
+    }
+
+    const rootLintFiles = lintFiles.filter((f) => !pkgFiles.has(f))
+    if (rootLintFiles.length > 0) {
+      checks.push(collectOutput(ports, "bunx", ["eslint", "--fix", "--no-warn-ignored", ...rootLintFiles], ports.root))
+    }
+  }
+
+  // Prettier on all formattable files
+  if (formatFiles.length > 0) {
+    checks.push(collectOutput(ports, "bunx", ["prettier", "--write", ...formatFiles], ports.root))
+  }
+
+  // Typecheck per affected package — scoped to committed files only
+  const tsFiles = existing.filter(isTypecheckable)
+  if (tsFiles.length > 0) {
+    const affected = filterByFiles(packages, tsFiles, ports.root)
+    for (const pkg of affected) {
+      if ("typecheck" in pkg.scripts) {
+        checks.push(scopedTypecheck(ports, pkg, tsFiles))
+      }
+    }
+  }
+
+  if (checks.length === 0) {
+    return { passed: true, checks: [] }
+  }
+
+  const results = await Promise.all(checks)
+  const passed = results.every((c) => c.status === "pass")
+
+  return { passed, checks: results }
+}

package/src/meta/domain/rules.ts

@@ -0,0 +1,21 @@
+/**
+ * Query: rules — governing CLAUDE.md cascade for given scopes.
+ */
+
+import type { ControlPorts } from "../ports.ts"
+import type { QueryResult, RulesScope } from "../types.ts"
+import { resolveCascade, scopeToDir } from "./scope-context.ts"
+
+export function rules(ports: ControlPorts, scopes: string[]): QueryResult {
+  const data: RulesScope[] = []
+
+  for (const scope of scopes) {
+    const dir = scopeToDir(scope)
+    const cascade = resolveCascade(ports, dir)
+    if (cascade.length > 0) {
+      data.push({ path: scope, cascade })
+    }
+  }
+
+  return { what: "rules", scopes, data }
+}

package/src/meta/domain/scope-context.ts

@@ -0,0 +1,63 @@
+/**
+ * Scope utilities — resolve CLAUDE.md cascade from scope strings.
+ */
+
+import { join } from "node:path"
+
+import type { ControlPorts } from "../ports.ts"
+
+/**
+ * Extract the directory prefix from a scope string.
+ *
+ * - File path: strip filename → directory
+ * - Glob: extract non-glob prefix
+ * - Directory: as-is (strip trailing slash)
+ */
+export function scopeToDir(scope: string): string {
+  // Strip trailing slash for consistency
+  const clean = scope.replace(/\/+$/, "")
+
+  // Glob: take directory prefix before first glob character
+  if (/[*?{]/.test(clean)) {
+    const idx = clean.search(/[*?{]/)
+    const prefix = clean.slice(0, idx).replace(/\/+$/, "")
+    return prefix || "."
+  }
+
+  // File: if last segment has a dot, treat as file → strip to parent
+  const lastSlash = clean.lastIndexOf("/")
+  const lastSegment = lastSlash >= 0 ? clean.slice(lastSlash + 1) : clean
+  if (lastSegment.includes(".")) {
+    return lastSlash >= 0 ? clean.slice(0, lastSlash) : "."
+  }
+
+  return clean || "."
+}
+
+/**
+ * Walk from root to target directory, collecting CLAUDE.md paths that exist.
+ * Returns @-prefixed references in cascade order: root first, most specific last.
+ */
+export function resolveCascade(ports: ControlPorts, dir: string): string[] {
+  const refs: string[] = []
+
+  // Always check root CLAUDE.md
+  if (ports.fs.exists(join(ports.root, "CLAUDE.md"))) {
+    refs.push("@CLAUDE.md")
+  }
+
+  // Walk each segment of the directory path
+  if (dir !== ".") {
+    const segments = dir.split("/").filter(Boolean)
+    let current = ""
+
+    for (const segment of segments) {
+      current = current ? `${current}/${segment}` : segment
+      if (ports.fs.exists(join(ports.root, current, "CLAUDE.md"))) {
+        refs.push(`@${current}/CLAUDE.md`)
+      }
+    }
+  }
+
+  return refs
+}

package/src/meta/domain/service.ts

@@ -0,0 +1,68 @@
+/**
+ * Control service factory — wires domain functions to ports.
+ */
+
+import type { ControlPorts } from "../ports.ts"
+import type {
+  CommitParams,
+  CommitResult,
+  QueryResult,
+  GitResult,
+  SetupResult,
+  EvalParams,
+  EvalResult,
+  Package,
+  TranscriptsParams,
+  TranscriptsResult,
+} from "../types.ts"
+
+import { commit } from "./commit.ts"
+import { rules } from "./rules.ts"
+import { diff } from "./diff.ts"
+import { commits } from "./commits.ts"
+import { lint } from "./lint.ts"
+import { typecheck } from "./typecheck.ts"
+import { test } from "./test.ts"
+import { blame } from "./blame.ts"
+import { pickaxe } from "./pickaxe.ts"
+import { bisect } from "./bisect.ts"
+import { setup } from "./setup.ts"
+import { evaluate } from "./eval.ts"
+import { transcripts } from "./transcripts.ts"
+import { discoverPackages } from "./workspace.ts"
+
+export type ControlService = {
+  commit(params: CommitParams): Promise<CommitResult>
+  rules(scopes: string[]): QueryResult
+  diff(scopes: string[]): QueryResult
+  commits(scopes: string[]): QueryResult
+  lint(scopes: string[], opts?: { changed?: boolean }): Promise<QueryResult>
+  typecheck(scopes: string[]): Promise<QueryResult>
+  test(scopes: string[]): Promise<QueryResult>
+  blame(file: string, lines?: [number, number]): GitResult
+  pickaxe(pattern: string, opts?: { regex?: boolean; scopes?: string[] }): GitResult
+  bisect(test: string, good: string, bad?: string, timeout?: number): Promise<GitResult>
+  setup(): SetupResult
+  eval(params: EvalParams): Promise<EvalResult>
+  transcripts(params: TranscriptsParams): TranscriptsResult
+  discoverPackages(): Package[]
+}
+
+export function createControlService(ports: ControlPorts): ControlService {
+  return {
+    commit: (params) => commit(ports, params),
+    rules: (scopes) => rules(ports, scopes),
+    diff: (scopes) => diff(ports, scopes),
+    commits: (scopes) => commits(ports, scopes),
+    lint: (scopes, opts) => lint(ports, scopes, opts),
+    typecheck: (scopes) => typecheck(ports, scopes),
+    test: (scopes) => test(ports, scopes),
+    blame: (file, lines) => blame(ports, file, lines),
+    pickaxe: (pattern, opts) => pickaxe(ports, pattern, opts),
+    bisect: (testCmd, good, bad, timeout) => bisect(ports, testCmd, good, bad, timeout),
+    setup: () => setup(ports),
+    eval: (params) => evaluate(ports, params),
+    transcripts: (params) => transcripts(ports, params),
+    discoverPackages: () => discoverPackages(ports),
+  }
+}

package/src/meta/domain/setup.ts

@@ -0,0 +1,34 @@
+/**
+ * Setup domain logic — configures Claude Code local settings.
+ */
+
+import { join } from "node:path"
+
+import type { ControlPorts } from "../ports.ts"
+import type { SetupResult } from "../types.ts"
+
+type LocalSettings = {
+  env?: Record<string, string>
+  [key: string]: unknown
+}
+
+export function setup(ports: ControlPorts): SetupResult {
+  const settingsPath = join(ports.root, ".claude/settings.local.json")
+  const binPath = join(ports.root, ".claude/bin")
+
+  let settings: LocalSettings = {}
+  if (ports.fs.exists(settingsPath)) {
+    try {
+      settings = JSON.parse(ports.fs.readFile(settingsPath)) as LocalSettings
+    } catch {
+      // Invalid JSON, start fresh
+    }
+  }
+
+  settings.env = settings.env ?? {}
+  settings.env.PATH = `${binPath}:$PATH`
+
+  ports.fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n")
+
+  return { settingsPath, binPath }
+}

package/src/meta/domain/test.ts

@@ -0,0 +1,72 @@
+/**
+ * Query: test — run bun test with explicit test file paths.
+ */
+
+import type { ControlPorts } from "../ports.ts"
+import type { QueryResult, Package } from "../types.ts"
+import { discoverPackages, filterByFiles, filterByScript } from "./workspace.ts"
+import { extractErrors } from "./format.ts"
+
+export async function test(ports: ControlPorts, scopes: string[]): Promise<QueryResult> {
+  const packages = discoverPackages(ports)
+
+  const { FORCE_COLOR: _, ...parentEnv } = process.env as Record<string, string>
+  const env: Record<string, string> = { ...parentEnv, NO_COLOR: "1" }
+
+  if (scopes.length === 0) {
+    const withTest = filterByScript(packages, "test")
+    if (withTest.length === 0) {
+      return { what: "test", scopes, data: { errorCount: 0, errors: [], raw: "" } }
+    }
+    const results = await Promise.all(withTest.map((pkg) => runTestScript(ports, pkg, env)))
+    const raw = results.filter(Boolean).join("\n")
+    return { what: "test", scopes, data: extractErrors(raw) }
+  }
+
+  const affected = filterByFiles(packages, scopes, ports.root)
+
+  if (affected.length === 0) {
+    return { what: "test", scopes, data: { errorCount: 0, errors: [], raw: "" } }
+  }
+
+  const results = await Promise.all(
+    affected.map((pkg) => {
+      const testFiles = scopes.filter((s) => s.startsWith(pkg.relDir + "/"))
+      return runTests(ports, pkg, testFiles, env)
+    }),
+  )
+
+  const raw = results.filter(Boolean).join("\n")
+  return { what: "test", scopes, data: extractErrors(raw) }
+}
+
+function runTestScript(ports: ControlPorts, pkg: Package, env: Record<string, string>): Promise<string> {
+  return new Promise((resolve) => {
+    const lines: string[] = []
+    const handle = ports.process.spawn({ cmd: "bun", args: ["run", "test"], cwd: pkg.dir, env })
+    handle.onLine("stdout", (line) => lines.push(line))
+    handle.onLine("stderr", (line) => lines.push(line))
+    handle.wait().then(() => resolve(lines.join("\n")))
+  })
+}
+
+function runTests(
+  ports: ControlPorts,
+  pkg: Package,
+  testFiles: string[],
+  env: Record<string, string>,
+): Promise<string> {
+  return new Promise((resolve) => {
+    const lines: string[] = []
+    const relFiles = testFiles.map((f) => f.slice(pkg.relDir.length + 1))
+    const handle = ports.process.spawn({
+      cmd: "bun",
+      args: ["test", ...relFiles],
+      cwd: pkg.dir,
+      env,
+    })
+    handle.onLine("stdout", (line) => lines.push(line))
+    handle.onLine("stderr", (line) => lines.push(line))
+    handle.wait().then(() => resolve(lines.join("\n")))
+  })
+}

package/src/meta/domain/transcripts.ts

@@ -0,0 +1,88 @@
+/**
+ * Transcripts — find and list Claude Code subagent transcripts.
+ */
+
+import { join } from "node:path"
+
+import type { ControlPorts } from "../ports.ts"
+import type { TranscriptEntry, TranscriptsParams, TranscriptsResult } from "../types.ts"
+
+const DEFAULT_MINUTES = 120
+const SKILL_DIR_PATTERN = /Base directory for this skill:.*\/\.claude\/skills\/([^/\n]+)/
+
+/** Derive Claude Code project slug from absolute repo root path. */
+function projectSlug(root: string): string {
+  return "-" + root.replace(/\//g, "-").replace(/^-/, "")
+}
+
+/** Extract skill name from first JSONL line's message content. */
+function extractSkill(firstLine: string): string {
+  try {
+    const data = JSON.parse(firstLine)
+    const content = data?.message?.content
+    const text = typeof content === "string" ? content : Array.isArray(content) ? (content[0]?.text ?? "") : ""
+    const match = SKILL_DIR_PATTERN.exec(text)
+    return match?.[1] ?? "task"
+  } catch {
+    return "unknown"
+  }
+}
+
+export function transcripts(ports: ControlPorts, params: TranscriptsParams): TranscriptsResult {
+  const { skill, minutes = DEFAULT_MINUTES } = params
+  const slug = projectSlug(ports.root)
+  const basePath = join(ports.homedir(), ".claude", "projects", slug)
+
+  if (!ports.fs.exists(basePath)) {
+    return { projectSlug: slug, entries: [] }
+  }
+
+  const cutoff = new Date(Date.now() - minutes * 60 * 1000)
+  const entries: TranscriptEntry[] = []
+
+  const sessions = ports.fs.readDir(basePath)
+  for (const session of sessions) {
+    if (!session.isDirectory) continue
+
+    const subagentsPath = join(basePath, session.name, "subagents")
+    if (!ports.fs.exists(subagentsPath)) continue
+
+    const files = ports.fs.readDir(subagentsPath)
+    for (const file of files) {
+      if (file.isDirectory || !file.name.endsWith(".jsonl")) continue
+
+      const filePath = join(subagentsPath, file.name)
+      const content = ports.fs.readFile(filePath)
+      const firstLine = content.slice(0, content.indexOf("\n"))
+      if (!firstLine) continue
+
+      let timestamp: string
+      let agentId: string
+      try {
+        const meta = JSON.parse(firstLine)
+        timestamp = meta.timestamp ?? ""
+        agentId = meta.agentId ?? file.name.replace("agent-", "").replace(".jsonl", "")
+      } catch {
+        continue
+      }
+
+      if (timestamp && new Date(timestamp) < cutoff) continue
+
+      const skillName = extractSkill(firstLine)
+      if (skill && skillName !== skill) continue
+
+      entries.push({
+        path: filePath,
+        agentId,
+        sessionId: session.name,
+        skill: skillName,
+        timestamp,
+        size: content.length,
+      })
+    }
+  }
+
+  entries.sort((a, b) => (b.timestamp > a.timestamp ? 1 : b.timestamp < a.timestamp ? -1 : 0))
+
+  return { projectSlug: slug, entries }
+}

package/src/meta/domain/typecheck.ts

@@ -0,0 +1,41 @@
+/**
+ * Query: typecheck — run tsc across workspace packages matching scope.
+ */
+
+import type { ControlPorts } from "../ports.ts"
+import type { QueryResult } from "../types.ts"
+import { discoverPackages, filterByScript } from "./workspace.ts"
+import { extractErrors } from "./format.ts"
+
+export async function typecheck(ports: ControlPorts, scopes: string[]): Promise<QueryResult> {
+  const packages = discoverPackages(ports)
+
+  const matching =
+    scopes.length === 0
+      ? packages
+      : packages.filter((pkg) => scopes.some((s) => pkg.relDir.startsWith(s) || s.startsWith(pkg.relDir + "/")))
+  const withScript = filterByScript(matching, "typecheck")
+
+  if (withScript.length === 0) {
+    return { what: "typecheck", scopes, data: { errorCount: 0, errors: [], raw: "" } }
+  }
+
+  const { FORCE_COLOR: _, ...parentEnv } = process.env as Record<string, string>
+  const env: Record<string, string> = { ...parentEnv, NO_COLOR: "1" }
+
+  const results = await Promise.all(
+    withScript.map(
+      (pkg) =>
+        new Promise<string>((resolve) => {
+          const lines: string[] = []
+          const handle = ports.process.spawn({ cmd: "bun", args: ["run", "typecheck"], cwd: pkg.dir, env })
+          handle.onLine("stdout", (line) => lines.push(line))
+          handle.onLine("stderr", (line) => lines.push(line))
+          handle.wait().then(() => resolve(lines.join("\n")))
+        }),
+    ),
+  )
+
+  const raw = results.filter(Boolean).join("\n")
+  return { what: "typecheck", scopes, data: extractErrors(raw) }
+}

package/src/meta/domain/workspace.ts

@@ -0,0 +1,78 @@
+/**
+ * Workspace discovery — reads package.json workspaces globs and builds Package list.
+ */
+
+import { basename, join, relative } from "node:path"
+
+import type { ControlPorts } from "../ports.ts"
+import type { Package } from "../types.ts"
+
+/**
+ * Discover all workspace packages from root package.json.
+ * Supports `prefix/*` globs (e.g. "apps/*", "lib/*") and bare directories (e.g. "meta").
+ */
+export function discoverPackages(ports: ControlPorts): Package[] {
+  const rootPkg = JSON.parse(ports.fs.readFile(join(ports.root, "package.json"))) as {
+    workspaces?: string[]
+  }
+
+  const globs = rootPkg.workspaces ?? []
+  const packages: Package[] = []
+
+  for (const glob of globs) {
+    if (glob.endsWith("/*")) {
+      // Glob: enumerate subdirectories
+      const prefix = glob.slice(0, -2)
+      const prefixDir = join(ports.root, prefix)
+
+      let entries: Array<{ name: string; isDirectory: boolean }>
+      try {
+        entries = ports.fs.readDir(prefixDir).filter((d) => d.isDirectory)
+      } catch {
+        continue
+      }
+
+      for (const entry of entries.map((d) => d.name).sort()) {
+        const pkg = readPackage(ports, join(prefixDir, entry))
+        if (pkg) packages.push(pkg)
+      }
+    } else if (!glob.includes("*")) {
+      // Bare directory: single package (skip unsupported globs like "packages/**")
+      const pkg = readPackage(ports, join(ports.root, glob))
+      if (pkg) packages.push(pkg)
+    }
+  }
+
+  return packages.sort((a, b) => a.relDir.localeCompare(b.relDir))
+}
+
+function readPackage(ports: ControlPorts, dir: string): Package | null {
+  try {
+    const pkg = JSON.parse(ports.fs.readFile(join(dir, "package.json"))) as {
+      name?: string
+      scripts?: Record<string, string>
+    }
+    return {
+      name: pkg.name ?? basename(dir),
+      shortName: basename(dir),
+      dir,
+      relDir: relative(ports.root, dir),
+      scripts: pkg.scripts ?? {},
+    }
+  } catch {
+    return null
+  }
+}
+
+export function filterByScope(packages: Package[], scope: string): Package[] {
+  return packages.filter((p) => p.relDir.startsWith(scope))
+}
+
+export function filterByScript(packages: Package[], script: string): Package[] {
+  return packages.filter((p) => script in p.scripts)
+}
+
+export function filterByFiles(packages: Package[], files: string[], root: string): Package[] {
+  const relFiles = files.map((f) => (f.startsWith("/") ? relative(root, f) : f))
+  return packages.filter((pkg) => relFiles.some((f) => f.startsWith(pkg.relDir + "/")))
+}

package/src/meta/errors.ts

@@ -0,0 +1,19 @@
+/**
+ * Domain error — typed error with machine-readable code and human-readable hints.
+ */
+
+export class ControlError extends Error {
+  readonly code: string
+  readonly hints: string[]
+
+  constructor(code: string, message: string, hints: string[] = []) {
+    super(message)
+    this.name = "ControlError"
+    this.code = code
+    this.hints = hints
+  }
+}
+
+export function isControlError(err: unknown): err is ControlError {
+  return err instanceof ControlError
+}