@vladpazych/dexter 0.1.0

package/src/meta/hooks/on-post-read.ts

@@ -0,0 +1,61 @@
+import { basename } from "node:path"
+
+import { block, text, render } from "../../output/index.ts"
+import { readJsonStdin, getFilePath, type HookInput } from "../lib/stdin.ts"
+import { findRepoRoot } from "../lib/paths.ts"
+import { isSpecFile, findBrokenLinks, formatBrokenLinks } from "../lib/spec-links.ts"
+
+function xml(name: string, content: string): string {
+  return render(block(name, text(content)), "xml")
+}
+
+export async function onPostRead(): Promise<void> {
+  const input = await readJsonStdin<HookInput>()
+  const filePath = getFilePath(input)
+
+  if (!filePath) return
+
+  let root: string
+  try {
+    root = findRepoRoot()
+  } catch {
+    return
+  }
+
+  const sections: string[] = []
+
+  if (isSpecFile(filePath)) {
+    try {
+      const content = await Bun.file(filePath).text()
+      const broken = findBrokenLinks(filePath, content, root)
+
+      if (broken.length > 0) {
+        sections.push(xml("spec-links", formatBrokenLinks(broken)))
+      }
+    } catch {
+      // File might have been deleted or unreadable
+    }
+  }
+
+  const name = basename(filePath)
+  if (name === "CLAUDE.md") {
+    sections.push(xml("before-writing", "load /markdown skill · llm audience · claude-md document"))
+  } else if (name === "README.md") {
+    sections.push(xml("before-writing", "load /markdown skill · human audience · readme document"))
+  } else if (name === "SKILL.md") {
+    sections.push(xml("before-writing", "load /markdown skill · llm audience · skill document"))
+  } else if (name === "OOUX.md") {
+    sections.push(xml("before-writing", "load /ooux skill before modifying OOUX spec"))
+  }
+
+  if (sections.length > 0) {
+    console.log(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "PostToolUse",
+          additionalContext: sections.join("\n") + "\n",
+        },
+      }),
+    )
+  }
+}

package/src/meta/hooks/on-post-write.ts

@@ -0,0 +1,65 @@
+import { block, text, render } from "../../output/index.ts"
+import { readJsonStdin, getFilePath, type HookInput } from "../lib/stdin.ts"
+import { shouldLint, runESLint } from "../lib/eslint.ts"
+import { findRepoRoot, isInsideRepo } from "../lib/paths.ts"
+import { isSpecFile, findBrokenLinks, formatBrokenLinks } from "../lib/spec-links.ts"
+
+function xml(name: string, content: string): string {
+  return render(block(name, text(content)), "xml")
+}
+
+export async function onPostWrite(): Promise<void> {
+  const input = await readJsonStdin<HookInput>()
+  const filePath = getFilePath(input)
+  if (!filePath) return
+
+  let root: string
+  try {
+    root = findRepoRoot()
+  } catch {
+    return
+  }
+
+  if (!isInsideRepo(filePath, root)) return
+
+  const sections: string[] = []
+
+  if (shouldLint(filePath)) {
+    try {
+      const remaining = runESLint(filePath)
+      if (remaining) {
+        sections.push(xml("lint", remaining))
+      }
+    } catch {
+      // ESLint might not be available or fail
+    }
+  }
+
+  if (isSpecFile(filePath)) {
+    try {
+      const content = await Bun.file(filePath).text()
+      const broken = findBrokenLinks(filePath, content, root)
+
+      if (broken.length > 0) {
+        sections.push(xml("spec-links", formatBrokenLinks(broken)))
+      }
+    } catch {
+      // File might have been deleted or unreadable
+    }
+  }
+
+  sections.push(xml("commit", `commit in meaningful chunks · ./meta/run commit "<reason>" <files>`))
+
+  if (sections.length > 0) {
+    console.log(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "PostToolUse",
+          additionalContext: sections.join("\n"),
+        },
+      }),
+    )
+  }
+
+  process.exit(0)
+}

package/src/meta/hooks/on-pre-bash.ts

@@ -0,0 +1,69 @@
+import { readJsonStdin, getCommand, type HookInput } from "../lib/stdin.ts"
+
+/** Patterns to deny with hints */
+const DENY_PATTERNS = [
+  { pattern: /^git\s+(add)(\s|$)/, hint: "Use: /commit skill" },
+  { pattern: /^git\s+commit(?!\s+--no-verify)(\s|$)/, hint: "Use: /commit skill" },
+  { pattern: /^git\s+push\s+.*--force/, hint: "Force push not allowed. Use revert instead." },
+  { pattern: /^git\s+reset\s+--hard/, hint: "Hard reset not allowed. Use revert instead." },
+  { pattern: /^git\s+clean\s+-f/, hint: "git clean -f not allowed. Remove files explicitly." },
+  { pattern: /^git\s+checkout\s+\.$/, hint: "Discard all changes not allowed. Be explicit about files." },
+]
+
+async function isInConflictResolution(): Promise<boolean> {
+  try {
+    const result = Bun.spawnSync(["git", "rev-parse", "--git-dir"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    })
+    if (!result.success) return false
+    const gitDir = result.stdout.toString().trim()
+
+    const conflictIndicators = [
+      `${gitDir}/rebase-merge`,
+      `${gitDir}/rebase-apply`,
+      `${gitDir}/MERGE_HEAD`,
+      `${gitDir}/CHERRY_PICK_HEAD`,
+    ]
+
+    for (const indicator of conflictIndicators) {
+      if (await Bun.file(indicator).exists()) {
+        return true
+      }
+    }
+
+    return false
+  } catch {
+    return false
+  }
+}
+
+export async function onPreBash(): Promise<void> {
+  const input = await readJsonStdin<HookInput>()
+  const command = getCommand(input)
+
+  if (!command) {
+    process.exit(0)
+  }
+
+  for (const { pattern, hint } of DENY_PATTERNS) {
+    if (pattern.test(command)) {
+      if (await isInConflictResolution()) {
+        process.exit(0)
+      }
+
+      console.log(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: `Raw git command blocked: ${command}. ${hint}`,
+          },
+        }),
+      )
+      process.exit(0)
+    }
+  }
+
+  process.exit(0)
+}

package/src/meta/hooks/stubs.ts

@@ -0,0 +1,51 @@
+/**
+ * Stub hook handlers — silent exit 0.
+ *
+ * Extension points for consumer repos to override via createCLI hooks config.
+ */
+
+import { readJsonStdin, type HookInput } from "../lib/stdin.ts"
+
+export async function onSessionStart(): Promise<void> {}
+
+export async function onPostBash(): Promise<void> {
+  await readJsonStdin<HookInput>()
+  process.exit(0)
+}
+
+export async function onStop(): Promise<void> {}
+
+export async function onPromptSubmit(): Promise<void> {
+  await readJsonStdin<HookInput>()
+  process.exit(0)
+}
+
+export async function onNotification(): Promise<void> {
+  await readJsonStdin<HookInput>()
+}
+
+export async function onPreCompact(): Promise<void> {
+  await readJsonStdin<HookInput>()
+}
+
+export async function onToolFailure(): Promise<void> {
+  await readJsonStdin<HookInput>()
+}
+
+export async function onSubagentStart(): Promise<void> {
+  await readJsonStdin<HookInput>()
+}
+
+export async function onSubagentStop(): Promise<void> {
+  await readJsonStdin<HookInput>()
+  process.exit(0)
+}
+
+export async function onSessionEnd(): Promise<void> {
+  await readJsonStdin<HookInput>()
+}
+
+export async function onPermissionRequest(): Promise<void> {
+  await readJsonStdin<HookInput>()
+  process.exit(0)
+}

package/src/meta/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Meta framework — createCLI factory, hook protocol, domain commands.
+ *
+ * Consumer repos use this to wire project-specific commands and hook extensions
+ * on top of the universal agentic development toolkit.
+ */
+
+// Factory
+export { createCLI } from "./cli.ts"
+export type { CLIConfig, HookContext, HookOutput } from "./cli.ts"
+
+// Error handling
+export { ControlError, isControlError } from "./errors.ts"
+
+// Utilities for custom commands
+export { parseFormat } from "./lib/format.ts"
+export type { ParsedFormat } from "./lib/format.ts"
+export { findRepoRoot } from "./lib/paths.ts"
+export { getActor, isLLM, isHuman } from "./lib/actor.ts"
+
+// Types
+export type { HookInput } from "./lib/stdin.ts"
+export type {
+  CommitParams,
+  CommitResult,
+  QueryResult,
+  GitResult,
+  Package,
+  EvalParams,
+  EvalResult,
+  SetupResult,
+  TranscriptsParams,
+  TranscriptsResult,
+} from "./types.ts"
+export type { ControlPorts, GitPort, FsPort, ProcessPort, GlobPort } from "./ports.ts"
+export type { ControlService } from "./domain/service.ts"

package/src/meta/lib/actor.ts

@@ -0,0 +1,53 @@
+/**
+ * Actor detection and mode constraints.
+ *
+ * CLAUDECODE=1 indicates LLM agent context.
+ * Absence indicates human context.
+ */
+
+export type Actor = "llm" | "human"
+
+/** Detect current actor from environment */
+export function getActor(): Actor {
+  return process.env.CLAUDECODE === "1" ? "llm" : "human"
+}
+
+/** True if running in LLM agent context */
+export function isLLM(): boolean {
+  return getActor() === "llm"
+}
+
+/** True if running in human context */
+export function isHuman(): boolean {
+  return getActor() === "human"
+}
+
+/**
+ * Output mode constraints by actor.
+ *
+ * LLM: minimal output, inline only, never TUI/interactive
+ * Human: supports inline and interactive
+ */
+export interface ActorOutputMode {
+  /** Use minimal output (no decorations, progress bars, etc.) */
+  minimal: boolean
+  /** Allow interactive prompts */
+  interactive: boolean
+  /** Allow TUI (full-screen terminal UI) */
+  tui: boolean
+}
+
+export function getOutputMode(): ActorOutputMode {
+  if (isLLM()) {
+    return {
+      minimal: true,
+      interactive: false,
+      tui: false,
+    }
+  }
+  return {
+    minimal: false,
+    interactive: true,
+    tui: true,
+  }
+}

package/src/meta/lib/eslint.ts

@@ -0,0 +1,58 @@
+/**
+ * ESLint integration for post-write hooks.
+ *
+ * Auto-fixes a file, returns remaining (unfixable) violations as text.
+ */
+
+import { dirname, join } from "node:path"
+import { existsSync } from "node:fs"
+
+/** Walk up from filePath to find the nearest directory containing package.json */
+function findPackageRoot(filePath: string): string | undefined {
+  let dir = dirname(filePath)
+  while (dir !== dirname(dir)) {
+    if (existsSync(join(dir, "package.json"))) return dir
+    dir = dirname(dir)
+  }
+  return undefined
+}
+
+/** Auto-fix a file, return remaining violations as text (empty string = clean) */
+export function runESLint(filePath: string): string {
+  const cwd = findPackageRoot(filePath)
+  const result = Bun.spawnSync(["bunx", "eslint", "--fix", "--no-warn-ignored", filePath], {
+    stdout: "pipe",
+    stderr: "pipe",
+    ...(cwd && { cwd }),
+  })
+
+  // eslint prints remaining (unfixable) violations to stdout
+  return result.stdout.toString().trim()
+}
+
+/** Check if a file should be linted */
+export function shouldLint(filePath: string): boolean {
+  if (!filePath.endsWith(".ts") && !filePath.endsWith(".tsx")) {
+    return false
+  }
+
+  const skipPatterns = [
+    "/node_modules/",
+    "/dist/",
+    "/.next/",
+    "/coverage/",
+    ".d.ts",
+    "/routeTree.gen.ts",
+    "/storybook-static/",
+    "/.storybook/",
+    "/.vite/",
+  ]
+
+  for (const pattern of skipPatterns) {
+    if (filePath.includes(pattern)) {
+      return false
+    }
+  }
+
+  return true
+}

package/src/meta/lib/format.ts

@@ -0,0 +1,55 @@
+/**
+ * Format flag parsing — extracts output mode from CLI args.
+ *
+ * Supports `--format cli|json|xml|md` and `--json` shorthand.
+ * Format flags must appear before `--` separator.
+ */
+
+import type { OutputMode } from "../../output/types.ts"
+
+const VALID_MODES = new Set<OutputMode>(["cli", "json", "xml", "md"])
+
+export type ParsedFormat = {
+  mode: OutputMode
+  rest: string[]
+}
+
+/**
+ * Extract format flag from args, return mode + remaining args.
+ *
+ * Scans only args before `--` separator. Default mode: `cli`.
+ */
+export function parseFormat(args: string[]): ParsedFormat {
+  let mode: OutputMode = "cli"
+  const rest: string[] = []
+  const ddIndex = args.indexOf("--")
+  const flagRegion = ddIndex >= 0 ? ddIndex : args.length
+
+  for (let i = 0; i < args.length; i++) {
+    if (i < flagRegion) {
+      if (args[i] === "--json") {
+        mode = "json"
+        continue
+      }
+      if (args[i] === "--xml") {
+        mode = "xml"
+        continue
+      }
+      if (args[i] === "--md") {
+        mode = "md"
+        continue
+      }
+      if (args[i] === "--format" && i + 1 < flagRegion) {
+        const candidate = args[i + 1] as OutputMode
+        if (VALID_MODES.has(candidate)) {
+          mode = candidate
+          i++ // skip value
+          continue
+        }
+      }
+    }
+    rest.push(args[i]!)
+  }
+
+  return { mode, rest }
+}

package/src/meta/lib/paths.ts

@@ -0,0 +1,36 @@
+/**
+ * Path utilities for finding repo root.
+ */
+
+import { existsSync, realpathSync } from "node:fs"
+import { dirname, join } from "node:path"
+
+/**
+ * Find the repo root by looking for CLAUDE.md, starting from CWD.
+ * Returns absolute path or throws if not found.
+ */
+export function findRepoRoot(): string {
+  let dir = process.cwd()
+
+  while (dir !== dirname(dir)) {
+    if (existsSync(join(dir, "CLAUDE.md"))) {
+      return dir
+    }
+    dir = dirname(dir)
+  }
+
+  throw new Error("error: not in a repo (no CLAUDE.md found)")
+}
+
+/**
+ * Check if a file path is inside the repo root.
+ * Resolves symlinks — files behind symlinks pointing outside are excluded.
+ */
+export function isInsideRepo(filePath: string, root: string): boolean {
+  try {
+    const real = realpathSync(filePath)
+    return real.startsWith(root + "/") || real === root
+  } catch {
+    return false
+  }
+}