@vladpazych/dexter 0.1.0

package/src/meta/cli.ts

@@ -0,0 +1,340 @@
+/**
+ * createCLI — the extension API for consumer repos.
+ *
+ * Consumer repos import this factory and compose their own CLI
+ * with custom commands and hook extensions on top of dexter's core.
+ */
+
+import { render } from "../output/index.ts"
+import type { OutputMode } from "../output/types.ts"
+
+import { isControlError } from "./errors.ts"
+import { findRepoRoot } from "./lib/paths.ts"
+import { parseFormat } from "./lib/format.ts"
+import {
+  presentQuery,
+  presentGit,
+  presentCommit,
+  presentEval,
+  presentPackages,
+  presentSetup,
+  presentTranscripts,
+  presentError,
+} from "./lib/present.ts"
+import { createControlPorts } from "./adapters/index.ts"
+import { createControlService, type ControlService } from "./domain/service.ts"
+
+import { onPreBash } from "./hooks/on-pre-bash.ts"
+import { onPostWrite } from "./hooks/on-post-write.ts"
+import { onPostRead } from "./hooks/on-post-read.ts"
+import {
+  onSessionStart,
+  onPostBash,
+  onStop,
+  onPromptSubmit,
+  onNotification,
+  onPreCompact,
+  onToolFailure,
+  onSubagentStart,
+  onSubagentStop,
+  onSessionEnd,
+  onPermissionRequest,
+} from "./hooks/stubs.ts"
+
+import type { HookInput } from "./lib/stdin.ts"
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export type HookContext = {
+  root: string
+  service: ControlService
+}
+
+export type HookOutput = {
+  additionalContext?: string
+} | void
+
+export type CLIConfig = {
+  commands?: Record<string, (args: string[], ctx: HookContext) => Promise<void> | void>
+  hooks?: {
+    "pre-bash"?: { deny?: Array<{ pattern: RegExp; hint: string }> }
+    "post-read"?: (input: HookInput, ctx: HookContext) => HookOutput | Promise<HookOutput>
+    "post-write"?: (input: HookInput, ctx: HookContext) => HookOutput | Promise<HookOutput>
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Core hook dispatch
+// ---------------------------------------------------------------------------
+
+const CORE_HOOKS: Record<string, () => Promise<void>> = {
+  "on-pre-bash": onPreBash,
+  "on-post-write": onPostWrite,
+  "on-post-read": onPostRead,
+  "on-session-start": onSessionStart,
+  "on-post-bash": onPostBash,
+  "on-stop": onStop,
+  "on-prompt-submit": onPromptSubmit,
+  "on-notification": onNotification,
+  "on-pre-compact": onPreCompact,
+  "on-tool-failure": onToolFailure,
+  "on-subagent-start": onSubagentStart,
+  "on-subagent-stop": onSubagentStop,
+  "on-session-end": onSessionEnd,
+  "on-permission-request": onPermissionRequest,
+}
+
+// ---------------------------------------------------------------------------
+// Output helpers
+// ---------------------------------------------------------------------------
+
+function output(text: string, mode: OutputMode): void {
+  if (mode === "cli") {
+    console.log(text)
+  } else {
+    console.log(text)
+  }
+}
+
+function outputError(err: unknown, mode: OutputMode): void {
+  if (isControlError(err)) {
+    output(render(presentError(err), mode), mode)
+  } else {
+    const message = err instanceof Error ? err.message : String(err)
+    console.error(message)
+  }
+  process.exit(1)
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createCLI(config: CLIConfig = {}) {
+  return {
+    async run(): Promise<void> {
+      const [, , cmd, ...rawArgs] = process.argv
+
+      // Hook commands — delegate to core handler
+      if (cmd?.startsWith("on-")) {
+        const handler = CORE_HOOKS[cmd]
+        if (handler) {
+          await handler()
+          return
+        }
+        // Unknown hook — silent exit
+        process.exit(0)
+      }
+
+      // Everything below needs repo root + service
+      let root: string
+      try {
+        root = findRepoRoot()
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err))
+        process.exit(1)
+      }
+
+      const ports = createControlPorts(root)
+      const service = createControlService(ports)
+      const ctx: HookContext = { root, service }
+
+      // Parse format flags
+      const { mode, rest: args } = parseFormat(rawArgs)
+
+      try {
+        // Custom commands first (override built-in)
+        if (cmd && config.commands?.[cmd]) {
+          await config.commands[cmd](args, ctx)
+          return
+        }
+
+        // Built-in domain commands
+        switch (cmd) {
+          case "commit": {
+            const [message, ...files] = args
+            if (!message) {
+              console.error('Usage: commit "message" file1 file2 ...')
+              process.exit(1)
+            }
+            const result = await service.commit({ message, files })
+            output(render(presentCommit(result), mode), mode)
+            break
+          }
+
+          case "rules": {
+            const scopes = args.length > 0 ? args : ["."]
+            const result = service.rules(scopes)
+            output(render(presentQuery(result), mode), mode)
+            break
+          }
+
+          case "diff": {
+            const scopes = args.length > 0 ? args : ["."]
+            const result = service.diff(scopes)
+            output(render(presentQuery(result), mode), mode)
+            break
+          }
+
+          case "commits": {
+            const scopes = args.length > 0 ? args : ["."]
+            const result = service.commits(scopes)
+            output(render(presentQuery(result), mode), mode)
+            break
+          }
+
+          case "lint": {
+            const changed = args.includes("--changed")
+            const scopes = args.filter((a) => a !== "--changed")
+            const result = await service.lint(scopes, { changed })
+            output(render(presentQuery(result), mode), mode)
+            if (result.what === "lint" && result.data.errorCount > 0) process.exit(1)
+            break
+          }
+
+          case "typecheck": {
+            const result = await service.typecheck(args)
+            output(render(presentQuery(result), mode), mode)
+            if (result.what === "typecheck" && result.data.errorCount > 0) process.exit(1)
+            break
+          }
+
+          case "test": {
+            const result = await service.test(args)
+            output(render(presentQuery(result), mode), mode)
+            if (result.what === "test" && result.data.errorCount > 0) process.exit(1)
+            break
+          }
+
+          case "blame": {
+            const file = args[0]
+            if (!file) {
+              console.error("Usage: blame <file> [startLine:endLine]")
+              process.exit(1)
+            }
+            let lines: [number, number] | undefined
+            if (args[1]) {
+              const parts = args[1].split(":")
+              if (parts.length === 2) {
+                lines = [parseInt(parts[0]!, 10), parseInt(parts[1]!, 10)]
+              }
+            }
+            const result = service.blame(file, lines)
+            output(render(presentGit(result), mode), mode)
+            break
+          }
+
+          case "pickaxe": {
+            const pattern = args[0]
+            if (!pattern) {
+              console.error("Usage: pickaxe <pattern> [--regex] [scopes...]")
+              process.exit(1)
+            }
+            const regex = args.includes("--regex")
+            const scopes = args.slice(1).filter((a) => a !== "--regex")
+            const result = service.pickaxe(pattern, { regex, scopes: scopes.length > 0 ? scopes : undefined })
+            output(render(presentGit(result), mode), mode)
+            break
+          }
+
+          case "bisect": {
+            const testCmd = args[0]
+            const goodIdx = args.indexOf("--good")
+            const badIdx = args.indexOf("--bad")
+            const good = goodIdx >= 0 ? args[goodIdx + 1] : undefined
+            const bad = badIdx >= 0 ? args[badIdx + 1] : undefined
+            if (!testCmd || !good) {
+              console.error("Usage: bisect <test-cmd> --good <ref> [--bad <ref>]")
+              process.exit(1)
+            }
+            const result = await service.bisect(testCmd, good, bad)
+            output(render(presentGit(result), mode), mode)
+            break
+          }
+
+          case "eval": {
+            const code = args.join(" ")
+            const result = await service.eval({ code })
+            output(render(presentEval(result), mode), mode)
+            if (!result.ok) process.exit(1)
+            break
+          }
+
+          case "setup": {
+            const result = service.setup()
+            output(render(presentSetup(result), mode), mode)
+            break
+          }
+
+          case "transcripts": {
+            const skillIdx = args.indexOf("--skill")
+            const minutesIdx = args.indexOf("--minutes")
+            const skill = skillIdx >= 0 ? args[skillIdx + 1] : undefined
+            const minutes = minutesIdx >= 0 ? parseInt(args[minutesIdx + 1]!, 10) : undefined
+            const result = service.transcripts({ skill, minutes })
+            output(render(presentTranscripts(result), mode), mode)
+            break
+          }
+
+          case "packages": {
+            const packages = service.discoverPackages()
+            output(render(presentPackages(packages), mode), mode)
+            break
+          }
+
+          case "format": {
+            // Prettier formatting
+            const scopes = args.length > 0 ? args : ["."]
+            const formatResult = await service.lint(scopes) // HACK: reuses lint, should be separate
+            output(render(presentQuery(formatResult), mode), mode)
+            break
+          }
+
+          case "--help":
+          case "-h":
+          case "help":
+          case undefined: {
+            const commands = [
+              "commit   — quality-gated atomic commit",
+              "rules    — CLAUDE.md cascade for scopes",
+              "diff     — git status + diff for scopes",
+              "commits  — recent commit history",
+              "lint     — ESLint across workspace",
+              "typecheck — TypeScript checking",
+              "test     — run tests",
+              "blame    — structured git blame",
+              "pickaxe  — find commits by pattern",
+              "bisect   — binary search for bad commit",
+              "eval     — sandboxed TypeScript REPL",
+              "setup    — configure .claude/settings",
+              "transcripts — list subagent transcripts",
+              "packages — list workspace packages",
+            ]
+
+            if (config.commands) {
+              for (const name of Object.keys(config.commands)) {
+                commands.push(`${name}   — (custom)`)
+              }
+            }
+
+            console.log(`dexter meta — agentic development toolkit\n`)
+            console.log(`Commands:`)
+            for (const c of commands) {
+              console.log(`  ${c}`)
+            }
+            console.log(`\nFlags: --format cli|json|xml|md  --json  --xml  --md`)
+            break
+          }
+
+          default:
+            console.error(`Unknown command: ${cmd}`)
+            process.exit(1)
+        }
+      } catch (err) {
+        outputError(err, mode)
+      }
+    },
+  }
+}

package/src/meta/domain/bisect.ts

@@ -0,0 +1,126 @@
+/**
+ * Git bisect — automated binary search for the first bad commit.
+ */
+
+import type { ControlPorts } from "../ports.ts"
+import type { BisectMatch, GitResult } from "../types.ts"
+import { ControlError } from "../errors.ts"
+
+const DEFAULT_TIMEOUT = 5 * 60 * 1000
+
+/** Parse the first-bad-commit output from git bisect run. */
+function parseFirstBad(output: string, ports: ControlPorts): BisectMatch {
+  const match = output.match(/([0-9a-f]{40}) is the first bad commit/)
+  if (!match) {
+    throw new ControlError("bisect_inconclusive", "bisect did not identify a bad commit", [
+      "The test command may not distinguish good from bad correctly",
+      "Ensure the command exits 0 for good, non-zero for bad",
+    ])
+  }
+
+  const fullHash = match[1]!
+  const hash = fullHash.slice(0, 8)
+
+  const show = ports.git.run(["show", "--format=%an%n%ai%n%s", "--stat", fullHash])
+  const showLines = show.success ? show.stdout.split("\n").filter(Boolean) : []
+  const author = showLines[0] ?? ""
+  const rawDate = showLines[1] ?? ""
+  const message = showLines[2] ?? ""
+
+  let date: string
+  try {
+    date = new Date(rawDate).toISOString().slice(0, 10)
+  } catch {
+    date = rawDate
+  }
+
+  const diffResult = ports.git.run(["show", "--format=", "--patch", fullHash])
+  const diff = diffResult.success ? diffResult.stdout.trim() : ""
+
+  return { hash, author, date, message, diff }
+}
+
+export async function bisect(
+  ports: ControlPorts,
+  test: string,
+  good: string,
+  bad?: string,
+  timeout?: number,
+): Promise<GitResult> {
+  if (!test) {
+    throw new ControlError("empty_test", "bisect requires a test command", [
+      "Usage: bisect <test-cmd> --good <ref>",
+      "The command should exit 0 for good commits, non-zero for bad",
+    ])
+  }
+
+  if (!good) {
+    throw new ControlError("no_good_ref", "bisect requires a good (known-working) ref", [
+      "Usage: bisect <test-cmd> --good <ref> [--bad <ref>]",
+      'Example: bisect "bun test test/foo.test.ts" --good HEAD~20',
+    ])
+  }
+
+  const badRef = bad ?? "HEAD"
+
+  const goodCheck = ports.git.run(["rev-parse", "--verify", good])
+  if (!goodCheck.success) {
+    throw new ControlError("bad_ref", `invalid good ref: ${good}`, [
+      `git rev-parse --verify ${good} failed`,
+      "Use a commit hash, branch name, tag, or relative ref like HEAD~10",
+    ])
+  }
+
+  if (bad) {
+    const badCheck = ports.git.run(["rev-parse", "--verify", bad])
+    if (!badCheck.success) {
+      throw new ControlError("bad_ref", `invalid bad ref: ${bad}`, [`git rev-parse --verify ${bad} failed`])
+    }
+  }
+
+  const bisectCheck = ports.git.run(["bisect", "log"])
+  if (bisectCheck.success && bisectCheck.stdout.includes("git bisect start")) {
+    throw new ControlError("bisect_active", "a bisect session is already in progress", [
+      "Run `git bisect reset` to end the current session first",
+    ])
+  }
+
+  try {
+    const start = ports.git.run(["bisect", "start"])
+    if (!start.success) {
+      throw new ControlError("bisect_start_failed", `git bisect start failed: ${start.stderr.trim()}`, [])
+    }
+
+    const markBad = ports.git.run(["bisect", "bad", badRef])
+    if (!markBad.success) {
+      throw new ControlError("bisect_mark_failed", `git bisect bad ${badRef} failed: ${markBad.stderr.trim()}`, [])
+    }
+
+    const markGood = ports.git.run(["bisect", "good", good])
+    if (!markGood.success) {
+      throw new ControlError("bisect_mark_failed", `git bisect good ${good} failed: ${markGood.stderr.trim()}`, [])
+    }
+
+    const output = await new Promise<string>((resolve) => {
+      const lines: string[] = []
+      const handle = ports.process.spawn({
+        cmd: "git",
+        args: ["bisect", "run", "sh", "-c", test],
+        cwd: ports.root,
+        timeout: timeout ?? DEFAULT_TIMEOUT,
+      })
+      handle.onLine("stdout", (line) => lines.push(line))
+      handle.onLine("stderr", (line) => lines.push(line))
+      handle.wait().then((code) => {
+        if (code === null) {
+          lines.push("bisect timed out")
+        }
+        resolve(lines.join("\n"))
+      })
+    })
+
+    return { what: "bisect", match: parseFirstBad(output, ports) }
+  } finally {
+    ports.git.run(["bisect", "reset"])
+  }
+}

package/src/meta/domain/blame.ts

@@ -0,0 +1,136 @@
+/**
+ * Git blame — structured per-line attribution with range grouping.
+ */
+
+import type { ControlPorts } from "../ports.ts"
+import type { BlameRange, GitResult } from "../types.ts"
+import { ControlError } from "../errors.ts"
+
+type PorcelainEntry = {
+  commit: string
+  author: string
+  date: string
+  message: string
+  line: number
+  content: string
+}
+
+/** Parse git blame --line-porcelain output into individual entries. */
+function parsePorcelain(raw: string): PorcelainEntry[] {
+  const entries: PorcelainEntry[] = []
+  const lines = raw.split("\n")
+  let i = 0
+
+  while (i < lines.length) {
+    const header = lines[i]!
+    const match = header.match(/^([0-9a-f]{40})\s+\d+\s+(\d+)/)
+    if (!match) {
+      i++
+      continue
+    }
+
+    const commit = match[1]!.slice(0, 8)
+    const line = parseInt(match[2]!, 10)
+    let author = ""
+    let date = ""
+    let message = ""
+    let content = ""
+
+    i++
+    while (i < lines.length) {
+      const cur = lines[i]!
+      if (cur.startsWith("\t")) {
+        content = cur.slice(1)
+        i++
+        break
+      }
+      if (cur.startsWith("author ")) author = cur.slice(7)
+      else if (cur.startsWith("author-time ")) {
+        const ts = parseInt(cur.slice(12), 10)
+        date = new Date(ts * 1000).toISOString().slice(0, 10)
+      } else if (cur.startsWith("summary ")) message = cur.slice(8)
+      i++
+    }
+
+    entries.push({ commit, author, date, message, line, content })
+  }
+
+  return entries
+}
+
+/** Group consecutive entries from the same commit into ranges. */
+function groupRanges(entries: PorcelainEntry[]): BlameRange[] {
+  if (entries.length === 0) return []
+
+  const ranges: BlameRange[] = []
+  let current: BlameRange = {
+    commit: entries[0]!.commit,
+    author: entries[0]!.author,
+    date: entries[0]!.date,
+    message: entries[0]!.message,
+    startLine: entries[0]!.line,
+    endLine: entries[0]!.line,
+    content: [entries[0]!.content],
+  }
+
+  for (let i = 1; i < entries.length; i++) {
+    const entry = entries[i]!
+    if (entry.commit === current.commit && entry.line === current.endLine + 1) {
+      current.endLine = entry.line
+      current.content.push(entry.content)
+    } else {
+      ranges.push(current)
+      current = {
+        commit: entry.commit,
+        author: entry.author,
+        date: entry.date,
+        message: entry.message,
+        startLine: entry.line,
+        endLine: entry.line,
+        content: [entry.content],
+      }
+    }
+  }
+  ranges.push(current)
+  return ranges
+}
+
+export function blame(ports: ControlPorts, file: string, lines?: [number, number]): GitResult {
+  const fullPath = `${ports.root}/${file}`
+  if (!ports.fs.exists(fullPath)) {
+    throw new ControlError("file_not_found", `file not found: ${file}`, [
+      "Provide a path relative to repo root",
+      "Example: blame meta/src/types.ts",
+    ])
+  }
+
+  const args = ["blame", "--line-porcelain"]
+
+  if (lines) {
+    args.push(`-L`, `${lines[0]},${lines[1]}`)
+  }
+
+  const ignoreRevsPath = `${ports.root}/.git-blame-ignore-revs`
+  if (ports.fs.exists(ignoreRevsPath)) {
+    args.push("--ignore-revs-file", ".git-blame-ignore-revs")
+  }
+
+  args.push("--", file)
+
+  const result = ports.git.run(args)
+  if (!result.success) {
+    throw new ControlError(
+      "blame_failed",
+      `git blame failed: ${result.stderr.trim()}`,
+      [
+        "Check that the file is tracked by git",
+        lines ? `Line range ${lines[0]}:${lines[1]} may be out of bounds` : "",
+      ].filter(Boolean),
+    )
+  }
+
+  const entries = parsePorcelain(result.stdout)
+  const ranges = groupRanges(entries)
+
+  return { what: "blame", file, ranges }
+}