@vladpazych/dexter 0.1.0

package/src/meta/lib/present.ts

@@ -0,0 +1,231 @@
+/**
+ * Presenter layer — domain results → Node trees.
+ *
+ * Pure functions. Each converts a typed domain result into a document tree
+ * that renders polymorphically via dexter's output module.
+ */
+
+import { block, field, heading, list, text } from "../../output/index.ts"
+import type { Node } from "../../output/index.ts"
+
+import type {
+  CommitResult,
+  EvalResult,
+  GitResult,
+  Package,
+  QueryResult,
+  SetupResult,
+  TranscriptsResult,
+} from "../types.ts"
+import type { ControlError } from "../errors.ts"
+
+// --- Query ---
+
+function presentRules(result: Extract<QueryResult, { what: "rules" }>): Node {
+  return block(
+    "rules",
+    ...result.data.map((scope) =>
+      block(
+        "scope",
+        { path: scope.path },
+        heading(scope.path),
+        field("cascade", list("ref", ...scope.cascade.map((c) => text(c)))),
+      ),
+    ),
+  )
+}
+
+function presentDiff(result: Extract<QueryResult, { what: "diff" }>): Node {
+  return block(
+    "diff",
+    ...result.data.map((scope) => {
+      const parts: Node[] = [heading(scope.path)]
+      if (scope.status) parts.push(field("status", scope.status))
+      if (scope.diff) parts.push(field("diff", scope.diff))
+      return block("scope", { path: scope.path }, ...parts)
+    }),
+  )
+}
+
+function presentCommits(result: Extract<QueryResult, { what: "commits" }>): Node {
+  const children: Node[] = result.data.map((scope) =>
+    block(
+      "scope",
+      { path: scope.path },
+      heading(scope.path),
+      field("log", list("entry", ...scope.log.map((l) => text(l)))),
+    ),
+  )
+  if (result.recent.length > 0) {
+    children.push(
+      block(
+        "recent-commits",
+        heading("Recent Commits"),
+        field("entries", list("entry", ...result.recent.map((l) => text(l)))),
+      ),
+    )
+  }
+  return block("commits", ...children)
+}
+
+function presentCheck(result: Extract<QueryResult, { what: "lint" | "typecheck" | "test" }>): Node {
+  const { what, data } = result
+  const children: Node[] = [field("errorCount", data.errorCount)]
+  if (data.errors.length > 0) {
+    children.push(field("errors", list("error", ...data.errors.map((e) => text(e.summary)))))
+  }
+  if (data.raw) {
+    children.push(field("raw", data.raw))
+  }
+  return block(what, ...children)
+}
+
+export function presentQuery(result: QueryResult): Node {
+  switch (result.what) {
+    case "rules":
+      return presentRules(result)
+    case "diff":
+      return presentDiff(result)
+    case "commits":
+      return presentCommits(result)
+    case "lint":
+    case "typecheck":
+    case "test":
+      return presentCheck(result)
+  }
+}
+
+// --- Git ---
+
+function presentBlame(result: Extract<GitResult, { what: "blame" }>): Node {
+  return block(
+    "blame",
+    { file: result.file },
+    heading(result.file),
+    ...result.ranges.map((r) =>
+      block(
+        "range",
+        { commit: r.commit, lines: `${r.startLine}-${r.endLine}` },
+        field("commit", r.commit),
+        field("author", r.author),
+        field("date", r.date),
+        field("message", r.message),
+        field("lines", `${r.startLine}-${r.endLine}`),
+        field("content", r.content.join("\n")),
+      ),
+    ),
+  )
+}
+
+function presentPickaxe(result: Extract<GitResult, { what: "pickaxe" }>): Node {
+  if (result.matches.length === 0) {
+    return block("pickaxe", { pattern: result.pattern }, field("matches", "none"))
+  }
+  return block(
+    "pickaxe",
+    { pattern: result.pattern },
+    ...result.matches.map((m) =>
+      block(
+        "match",
+        { hash: m.hash },
+        field("hash", m.hash),
+        field("author", m.author),
+        field("date", m.date),
+        field("message", m.message),
+        field("diff", m.diff),
+      ),
+    ),
+  )
+}
+
+function presentBisect(result: Extract<GitResult, { what: "bisect" }>): Node {
+  const m = result.match
+  return block(
+    "bisect",
+    { hash: m.hash },
+    field("hash", m.hash),
+    field("author", m.author),
+    field("date", m.date),
+    field("message", m.message),
+    field("diff", m.diff),
+  )
+}
+
+export function presentGit(result: GitResult): Node {
+  switch (result.what) {
+    case "blame":
+      return presentBlame(result)
+    case "pickaxe":
+      return presentPickaxe(result)
+    case "bisect":
+      return presentBisect(result)
+  }
+}
+
+// --- Commit ---
+
+export function presentCommit(result: CommitResult): Node {
+  return block(
+    "commit",
+    field("hash", result.hash),
+    field("message", result.message),
+    field("files", list("file", ...result.files.map((f) => text(f)))),
+  )
+}
+
+// --- Eval ---
+
+export function presentEval(result: EvalResult): Node {
+  const children: Node[] = []
+  if (result.stdout) children.push(field("stdout", result.stdout))
+  if (result.stderr) children.push(field("stderr", result.stderr))
+  return block("eval", { ok: String(result.ok) }, ...children)
+}
+
+// --- Packages ---
+
+export function presentPackages(packages: Package[]): Node {
+  return list(
+    "package",
+    ...packages.map((pkg) => block("package", field("name", pkg.shortName), field("dir", pkg.relDir))),
+  )
+}
+
+// --- Setup ---
+
+export function presentSetup(result: SetupResult): Node {
+  return block("setup", field("settings", result.settingsPath), field("bin", result.binPath))
+}
+
+// --- Transcripts ---
+
+export function presentTranscripts(result: TranscriptsResult): Node {
+  if (result.entries.length === 0) {
+    return block("transcripts", { project: result.projectSlug }, field("entries", "none"))
+  }
+  return block(
+    "transcripts",
+    { project: result.projectSlug },
+    ...result.entries.map((entry) =>
+      block(
+        "transcript",
+        { agentId: entry.agentId },
+        field("path", entry.path),
+        field("skill", entry.skill),
+        field("session", entry.sessionId),
+        field("timestamp", entry.timestamp),
+        field("size", entry.size),
+      ),
+    ),
+  )
+}
+
+// --- Error ---
+
+export function presentError(err: ControlError): Node {
+  const children: Node[] = [field("code", err.code), field("message", text(err.message, "red"))]
+  if (err.hints.length > 0) {
+    children.push(field("hints", list("hint", ...err.hints.map((h) => text(h)))))
+  }
+  return block("error", ...children)
+}

package/src/meta/lib/spec-links.ts

@@ -0,0 +1,83 @@
+/**
+ * Spec link validation.
+ *
+ * Validates markdown links [text](path.md) in CLAUDE.md and .md files.
+ *
+ * Paths resolve as:
+ * - /path/file.md   Root-absolute (from repo root)
+ * - ./path/file.md  Relative (from file's directory)
+ * - path/file.md    Relative (from file's directory)
+ */
+
+import { existsSync } from "node:fs"
+import { basename, dirname, join, resolve } from "node:path"
+
+export type SpecLink = {
+  type: "link"
+  path: string
+  line: number
+}
+
+export type BrokenLink = SpecLink & {
+  resolved: string
+}
+
+/** Check if a file participates in the spec system */
+export function isSpecFile(filePath: string): boolean {
+  if (basename(filePath) === "CLAUDE.md") return true
+  if (filePath.endsWith(".md")) return true
+  return false
+}
+
+/** Extract markdown links to .md files */
+export function extractSpecLinks(content: string): SpecLink[] {
+  const links: SpecLink[] = []
+  const lines = content.split("\n")
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!
+    const lineNum = i + 1
+
+    const linkRegex = /\[[^\]]*\]\(([^)]+\.md)\)/g
+    let match
+    while ((match = linkRegex.exec(line)) !== null) {
+      const path = match[1]!
+      if (path.startsWith("http://") || path.startsWith("https://")) continue
+      links.push({ type: "link", path, line: lineNum })
+    }
+  }
+
+  return links
+}
+
+/** Resolve a spec link path to absolute filesystem path */
+export function resolveSpecPath(linkPath: string, fromFile: string, repoRoot: string): string {
+  if (linkPath.startsWith("/")) {
+    return join(repoRoot, linkPath)
+  }
+  return resolve(dirname(fromFile), linkPath)
+}
+
+/** Find all broken links in a spec file */
+export function findBrokenLinks(filePath: string, content: string, repoRoot: string): BrokenLink[] {
+  const links = extractSpecLinks(content)
+  const broken: BrokenLink[] = []
+
+  for (const link of links) {
+    const resolved = resolveSpecPath(link.path, filePath, repoRoot)
+    if (!existsSync(resolved)) {
+      broken.push({ ...link, resolved })
+    }
+  }
+
+  return broken
+}
+
+/** Format broken links for hook context output */
+export function formatBrokenLinks(broken: BrokenLink[]): string {
+  const lines = ["=== Broken Spec Links ==="]
+  for (const link of broken) {
+    lines.push(`Warning: [...](${link.path}) -> not found (line ${link.line})`)
+  }
+  return lines.join("\n")
+}

package/src/meta/lib/stdin.ts

@@ -0,0 +1,56 @@
+/**
+ * Utilities for reading hook input from stdin
+ */
+
+/**
+ * Read all input from stdin
+ */
+export async function readStdin(): Promise<string> {
+  return Bun.stdin.text()
+}
+
+/**
+ * Parse JSON from stdin, returning null on parse error
+ */
+export async function readJsonStdin<T>(): Promise<T | null> {
+  const input = await readStdin()
+  if (!input.trim()) return null
+
+  try {
+    return JSON.parse(input) as T
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Hook input structure from Claude Code
+ */
+export type HookInput = {
+  /** Session identifier for correlation */
+  session_id?: string
+  /** The tool name that triggered the hook */
+  tool_name?: string
+  /** Tool input parameters */
+  tool_input?: Record<string, unknown>
+  /** Tool output (for PostToolUse) */
+  tool_output?: unknown
+}
+
+/**
+ * Extract file path from hook input
+ */
+export function getFilePath(input: HookInput | null): string | null {
+  if (!input?.tool_input) return null
+  const filePath = input.tool_input.file_path
+  return typeof filePath === "string" ? filePath : null
+}
+
+/**
+ * Extract command from Bash hook input
+ */
+export function getCommand(input: HookInput | null): string | null {
+  if (!input?.tool_input) return null
+  const command = input.tool_input.command
+  return typeof command === "string" ? command : null
+}

package/src/meta/ports.ts

@@ -0,0 +1,50 @@
+/**
+ * Port interfaces — what control domain needs from the outside world.
+ *
+ * Adapters implement these. Domain functions accept ControlPorts.
+ */
+
+export type SpawnResult = { success: boolean; stdout: string; stderr: string }
+
+export type GitPort = {
+  run(args: string[], env?: Record<string, string>): SpawnResult
+  checkIgnore(file: string): boolean
+}
+
+export type FsPort = {
+  exists(path: string): boolean
+  readFile(path: string): string
+  writeFile(path: string, content: string): void
+  readDir(path: string): Array<{ name: string; isDirectory: boolean }>
+  unlink(path: string): void
+  mkdir(path: string): void
+}
+
+export type ProcessHandle = {
+  onLine(stream: "stdout" | "stderr", cb: (line: string) => void): void
+  wait(): Promise<number | null>
+}
+
+export type ProcessPort = {
+  spawn(params: {
+    cmd: string
+    args: string[]
+    cwd: string
+    env?: Record<string, string>
+    timeout?: number
+  }): ProcessHandle
+}
+
+export type GlobPort = {
+  match(pattern: string, candidates: string[]): string[]
+}
+
+export type ControlPorts = {
+  git: GitPort
+  fs: FsPort
+  process: ProcessPort
+  glob: GlobPort
+  tmpdir: () => string
+  homedir: () => string
+  root: string
+}

package/src/meta/types.ts

@@ -0,0 +1,113 @@
+/**
+ * Domain types — command parameters, results, and shared contracts.
+ */
+
+export type CommitParams = {
+  message: string
+  files: string[]
+}
+
+export type CommitResult = {
+  hash: string
+  message: string
+  files: string[]
+}
+
+export type QualityCheck = {
+  name: string
+  status: "pass" | "fail"
+  output: string
+}
+
+export type QualityResult = {
+  passed: boolean
+  checks: QualityCheck[]
+}
+
+export type SetupResult = {
+  settingsPath: string
+  binPath: string
+}
+
+// --- eval ---
+
+export type EvalParams = { code: string; timeout?: number }
+export type EvalResult = { ok: boolean; stdout: string; stderr: string }
+
+// --- transcripts ---
+
+export type TranscriptsParams = { skill?: string; minutes?: number }
+
+export type TranscriptEntry = {
+  path: string
+  agentId: string
+  sessionId: string
+  skill: string
+  timestamp: string
+  size: number
+}
+
+export type TranscriptsResult = {
+  projectSlug: string
+  entries: TranscriptEntry[]
+}
+
+// --- packages ---
+
+export type Package = {
+  name: string
+  shortName: string
+  dir: string
+  relDir: string
+  scripts: Record<string, string>
+}
+
+// --- blame / pickaxe / bisect ---
+
+export type BlameRange = {
+  commit: string
+  author: string
+  date: string
+  message: string
+  startLine: number
+  endLine: number
+  content: string[]
+}
+
+export type PickaxeMatch = {
+  hash: string
+  author: string
+  date: string
+  message: string
+  diff: string
+}
+
+export type BisectMatch = {
+  hash: string
+  author: string
+  date: string
+  message: string
+  diff: string
+}
+
+export type GitResult =
+  | { what: "blame"; file: string; ranges: BlameRange[] }
+  | { what: "pickaxe"; pattern: string; matches: PickaxeMatch[] }
+  | { what: "bisect"; match: BisectMatch }
+
+// --- rules / diff / commits / lint / typecheck / test ---
+
+export type RulesScope = { path: string; cascade: string[] }
+export type DiffScope = { path: string; status: string; diff: string }
+export type CommitsScope = { path: string; log: string[] }
+
+export type CheckError = { line: number; summary: string }
+export type CheckData = { errorCount: number; errors: CheckError[]; raw: string }
+
+export type QueryResult =
+  | { what: "rules"; scopes: string[]; data: RulesScope[] }
+  | { what: "diff"; scopes: string[]; data: DiffScope[] }
+  | { what: "commits"; scopes: string[]; data: CommitsScope[]; recent: string[] }
+  | { what: "lint"; scopes: string[]; data: CheckData }
+  | { what: "typecheck"; scopes: string[]; data: CheckData }
+  | { what: "test"; scopes: string[]; data: CheckData }

package/src/output/build.ts

@@ -0,0 +1,56 @@
+/**
+ * Builder functions — construct document trees from domain data.
+ *
+ * Pure functions returning immutable nodes.
+ */
+
+import type { BlockNode, FieldNode, HeadingNode, ListNode, Node, Primitive, Style, TextNode } from "./types.ts"
+
+/** Styled text content. */
+export function text(value: string, style?: Style): TextNode {
+  return style ? { kind: "text", value, style } : { kind: "text", value }
+}
+
+/** Key-value pair. Primitives preserved for JSON type fidelity. */
+export function field(label: string, value: Primitive | Node): FieldNode {
+  return { kind: "field", label, value }
+}
+
+function isNode(x: unknown): x is Node {
+  return typeof x === "object" && x !== null && "kind" in x
+}
+
+/**
+ * Semantic container with tag and optional attributes.
+ *
+ * ```ts
+ * block("commit", field("hash", "abc"))
+ * block("scope", { path: "meta/src" }, field("status", "clean"))
+ * ```
+ */
+export function block(tag: string, ...args: (Node | Record<string, string>)[]): BlockNode {
+  if (args.length > 0 && args[0] !== undefined && !isNode(args[0])) {
+    return { kind: "block", tag, attrs: args[0] as Record<string, string>, children: args.slice(1) as Node[] }
+  }
+  return { kind: "block", tag, children: args as Node[] }
+}
+
+/**
+ * Ordered collection. Optional tag names individual items in XML.
+ *
+ * ```ts
+ * list(text("a.ts"), text("b.ts"))
+ * list("file", text("a.ts"), text("b.ts"))  // XML: <file>a.ts</file><file>b.ts</file>
+ * ```
+ */
+export function list(...args: (string | Node)[]): ListNode {
+  if (typeof args[0] === "string") {
+    return { kind: "list", tag: args[0], items: args.slice(1) as Node[] }
+  }
+  return { kind: "list", items: args as Node[] }
+}
+
+/** Display heading — renders in CLI and Markdown, omitted in JSON and XML. */
+export function heading(value: string): HeadingNode {
+  return { kind: "heading", text: value }
+}

package/src/output/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Polymorphic output — build once, render to any format.
+ */
+
+// Types
+export type {
+  BlockNode,
+  FieldNode,
+  HeadingNode,
+  ListNode,
+  Node,
+  OutputMode,
+  Primitive,
+  Style,
+  TextNode,
+} from "./types.ts"
+
+// Builders
+export { block, field, heading, list, text } from "./build.ts"
+
+// Renderers
+export { render } from "./render.ts"
+export { toValue } from "./render-json.ts"
+export { escapeXml } from "./render-xml.ts"