@vladpazych/dexter 0.1.0

package/bin/dexter

@@ -0,0 +1,6 @@
+#!/bin/sh
+# Dexter CLI entry point.
+# Delegates to the TypeScript source via Bun — no build step.
+
+DIR="$(cd "${0%/*}" 2>/dev/null && pwd)"
+exec bun run "$DIR/../src/cli.ts" "$@"

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@vladpazych/dexter",
+  "version": "0.1.0",
+  "description": "Agentic development toolkit — output rendering, env config, CLI framework for Claude Code hooks",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vladpazych/dexter.git",
+    "directory": "packages/dexter"
+  },
+  "type": "module",
+  "files": [
+    "src",
+    "bin"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./meta": "./src/meta/index.ts",
+    "./output": "./src/output/index.ts",
+    "./env": "./src/env/index.ts",
+    "./pipe": "./src/pipe/index.ts",
+    "./terminal": "./src/terminal/index.ts",
+    "./claude": "./src/claude/index.ts",
+    "./config/eslint": "./src/config/eslint.js",
+    "./config/tsconfig/base.json": "./src/config/tsconfig/base.json",
+    "./config/tsconfig/node.json": "./src/config/tsconfig/node.json",
+    "./config/tsconfig/react.json": "./src/config/tsconfig/react.json"
+  },
+  "bin": {
+    "dexter": "./bin/dexter"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1"
+  }
+}

package/src/claude/index.ts

@@ -0,0 +1,6 @@
+/**
+ * Claude management — .claude/ folder scaffolding, settings, hook wiring.
+ */
+
+// TODO: Implement
+export {}

package/src/cli.ts

@@ -0,0 +1,39 @@
+/**
+ * Dexter standalone CLI — scaffolding and utilities.
+ *
+ * Usage:
+ *   dexter init          Scaffold meta/ + .claude/ in current repo
+ *   dexter version       Print version
+ */
+
+import { version } from "./version.js"
+
+const [, , cmd] = process.argv
+
+switch (cmd) {
+  case "init":
+    console.log("dexter init — not yet implemented")
+    break
+
+  case "version":
+  case "--version":
+  case "-v":
+    console.log(version)
+    break
+
+  case "--help":
+  case "-h":
+  case undefined:
+    console.log(`dexter v${version} — agentic development toolkit
+
+Usage: dexter <command>
+
+Commands:
+  init       Scaffold meta/ + .claude/ in current repo
+  version    Print version`)
+    break
+
+  default:
+    console.error(`Unknown command: ${cmd}`)
+    process.exit(1)
+}

package/src/env/define.ts

@@ -0,0 +1,190 @@
+/**
+ * App-owned configuration from environment variables.
+ *
+ * Each app declares its schema via defineConfig(), which reads process.env,
+ * validates types, enforces required fields, and returns a typed object.
+ * Metadata is attached via Symbol for printConfig() to read.
+ */
+
+import { validateBoolean, validateEnum, validateNumber, validatePort, validateString, validateUrl } from "./validate.ts"
+
+// ============================================================================
+// TYPES — schema definition
+// ============================================================================
+
+type EnvType = "string" | "port" | "url" | "number" | "boolean" | "enum"
+
+type FieldDef = {
+  readonly env: string
+  readonly type?: EnvType
+  readonly values?: readonly string[]
+  readonly default?: unknown
+  readonly required?: boolean
+  readonly sensitive?: boolean
+}
+
+export type Schema = { readonly [key: string]: FieldDef | Schema }
+
+// ============================================================================
+// TYPES — output inference
+// ============================================================================
+
+/** Map field's `type` property to the TypeScript value type. */
+type FieldValueType<F> = F extends { type: "port" | "number" }
+  ? number
+  : F extends { type: "boolean" }
+    ? boolean
+    : F extends { type: "enum"; values: readonly (infer V)[] }
+      ? V
+      : string
+
+/** True when the field is guaranteed to have a value (required or defaulted). */
+type IsPresent<F> = F extends { required: true }
+  ? true
+  : F extends { default: undefined }
+    ? false
+    : F extends { default: unknown }
+      ? true
+      : false
+
+/** Output type for a single field: value type, optionally undefined. */
+type FieldOutput<F> = IsPresent<F> extends true ? FieldValueType<F> : FieldValueType<F> | undefined
+
+/** Recursive output type for the entire schema. */
+export type ConfigOutput<S> = {
+  -readonly [K in keyof S]: S[K] extends { env: string } ? FieldOutput<S[K]> : ConfigOutput<S[K]>
+}
+
+// ============================================================================
+// METADATA — hidden on config object for printConfig
+// ============================================================================
+
+export const CONFIG_META = Symbol.for("dexter.config.meta")
+
+export type FieldMeta = {
+  path: string
+  env: string
+  sensitive: boolean
+  type: EnvType
+  values?: readonly string[]
+  required: boolean
+  hasDefault: boolean
+}
+
+export type ConfigMeta = {
+  name?: string
+  fields: FieldMeta[]
+}
+
+// ============================================================================
+// ERROR
+// ============================================================================
+
+export class ConfigError extends Error {
+  readonly issues: string[]
+
+  constructor(issues: string[]) {
+    super(`Invalid environment configuration\n${issues.map((i) => `  ${i}`).join("\n")}`)
+    this.name = "ConfigError"
+    this.issues = issues
+  }
+}
+
+// ============================================================================
+// RUNTIME
+// ============================================================================
+
+function isField(value: unknown): value is FieldDef {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "env" in value &&
+    typeof (value as Record<string, unknown>).env === "string"
+  )
+}
+
+function coerce(raw: string, type: EnvType, values?: readonly string[]): unknown {
+  switch (type) {
+    case "string":
+      return validateString(raw)
+    case "port":
+      return validatePort(raw)
+    case "number":
+      return validateNumber(raw)
+    case "boolean":
+      return validateBoolean(raw)
+    case "url":
+      return validateUrl(raw)
+    case "enum":
+      return validateEnum(raw, values ?? [])
+  }
+}
+
+export function defineConfig<const S extends Schema>(schema: S): ConfigOutput<S>
+export function defineConfig<const S extends Schema>(name: string, schema: S): ConfigOutput<S>
+export function defineConfig<const S extends Schema>(nameOrSchema: string | S, maybeSchema?: S): ConfigOutput<S> {
+  const name = typeof nameOrSchema === "string" ? nameOrSchema : undefined
+  const schema = typeof nameOrSchema === "string" ? maybeSchema! : nameOrSchema
+
+  const errors: string[] = []
+  const fields: FieldMeta[] = []
+
+  function walk(obj: Record<string, unknown>, path: string[]): Record<string, unknown> {
+    const result: Record<string, unknown> = {}
+
+    for (const [key, def] of Object.entries(obj)) {
+      if (isField(def)) {
+        const fieldPath = [...path, key].join(".")
+        const type: EnvType = (def.type as EnvType) ?? "string"
+
+        fields.push({
+          path: fieldPath,
+          env: def.env,
+          sensitive: def.sensitive ?? false,
+          type,
+          values: def.values,
+          required: def.required ?? false,
+          hasDefault: "default" in def,
+        })
+
+        const raw = process.env[def.env]
+
+        if (raw === undefined || raw === "") {
+          if (def.required) {
+            errors.push(`${def.env}: required but not set`)
+          } else if ("default" in def) {
+            result[key] = def.default
+          } else {
+            result[key] = undefined
+          }
+          continue
+        }
+
+        try {
+          result[key] = coerce(raw, type, def.values)
+        } catch (msg) {
+          errors.push(`${def.env}: ${msg}`)
+        }
+      } else {
+        result[key] = walk(def as Record<string, unknown>, [...path, key])
+      }
+    }
+
+    return result
+  }
+
+  const config = walk(schema as unknown as Record<string, unknown>, [])
+
+  if (errors.length > 0) {
+    throw new ConfigError(errors)
+  }
+
+  Object.defineProperty(config, CONFIG_META, {
+    value: { name, fields } satisfies ConfigMeta,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  })
+
+  return config as ConfigOutput<S>
+}

package/src/env/index.ts

@@ -0,0 +1,10 @@
+// Loading: dotenv plumbing
+export type { LoadResult } from "./loader.ts"
+export { applyEnv, loadEnv, parseEnvFile } from "./loader.ts"
+
+// Config: app-owned schema, validation, metadata
+export type { ConfigMeta, ConfigOutput, FieldMeta, Schema } from "./define.ts"
+export { CONFIG_META, ConfigError, defineConfig } from "./define.ts"
+
+// Print: formatted output with sensitive masking
+export { formatConfig, printConfig } from "./print.ts"

package/src/env/loader.ts

@@ -0,0 +1,61 @@
+/**
+ * Load environment variables from .env files.
+ * Order: .env (defaults) → .env.local (overrides)
+ */
+
+import { existsSync, readFileSync } from "node:fs"
+import { join } from "node:path"
+
+export type LoadResult = {
+  env: Record<string, string>
+  sources: Record<string, string>
+}
+
+/** Parse a plain key=value .env file. Ignores comments and empty lines. */
+export function parseEnvFile(filePath: string): Record<string, string> {
+  if (!existsSync(filePath)) return {}
+  const content = readFileSync(filePath, "utf-8")
+  const result: Record<string, string> = {}
+
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim()
+    if (trimmed.startsWith("#") || trimmed === "") continue
+
+    const match = trimmed.match(/^([A-Z][A-Z0-9_]*)=(.*)$/)
+    if (match) {
+      let value = match[2]
+      if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1)
+      }
+      result[match[1]] = value
+    }
+  }
+
+  return result
+}
+
+export function loadEnv(rootDir: string): LoadResult {
+  const env: Record<string, string> = {}
+  const sources: Record<string, string> = {}
+
+  const merge = (filename: string) => {
+    const values = parseEnvFile(join(rootDir, filename))
+    for (const [key, value] of Object.entries(values)) {
+      if (value !== "") {
+        env[key] = value
+        sources[key] = filename
+      }
+    }
+  }
+
+  merge(".env")
+  merge(".env.local")
+
+  return { env, sources }
+}
+
+export function applyEnv(env: Record<string, string>): void {
+  for (const [key, value] of Object.entries(env)) {
+    process.env[key] = value
+  }
+}

package/src/env/print.ts

@@ -0,0 +1,98 @@
+/**
+ * Config printing with sensitive value masking.
+ *
+ * Reads metadata attached by defineConfig() via CONFIG_META symbol.
+ * Nested schema keys become section headers in the output.
+ */
+
+import { c } from "../terminal/colors.ts"
+import { CONFIG_META, type ConfigMeta, type FieldMeta } from "./define.ts"
+
+const MASK = "••••"
+const UNSET = "—"
+const BOX_TOP = "┌"
+const BOX_MID = "│"
+const BOX_BOT = "└"
+
+function getMeta(config: unknown): ConfigMeta | undefined {
+  if (typeof config === "object" && config !== null && CONFIG_META in config) {
+    return (config as Record<symbol, unknown>)[CONFIG_META] as ConfigMeta
+  }
+  return undefined
+}
+
+function formatValue(raw: unknown, field: FieldMeta): string {
+  if (raw === undefined || raw === null) return c.gray(UNSET)
+  if (field.sensitive) return c.gray(MASK)
+  return String(raw)
+}
+
+function getNestedValue(obj: unknown, path: string): unknown {
+  let current = obj
+  for (const key of path.split(".")) {
+    if (typeof current !== "object" || current === null) return undefined
+    current = (current as Record<string, unknown>)[key]
+  }
+  return current
+}
+
+/**
+ * Format config as a printable string with sections and masking.
+ */
+export function formatConfig(config: unknown, name?: string): string {
+  const meta = getMeta(config)
+  if (!meta) return String(config)
+
+  const label = name ?? meta.name ?? "config"
+  const lines: string[] = []
+
+  lines.push(`${c.gray(BOX_TOP)} ${c.bolded(label)}`)
+
+  // Group fields by their first path segment (section)
+  const sections = new Map<string, FieldMeta[]>()
+  for (const field of meta.fields) {
+    const parts = field.path.split(".")
+    const section = parts.length > 1 ? parts[0] : ""
+    const existing = sections.get(section) ?? []
+    existing.push(field)
+    sections.set(section, existing)
+  }
+
+  // Find longest label for alignment
+  const allLabels = meta.fields.map((f) => {
+    const parts = f.path.split(".")
+    return parts[parts.length - 1]
+  })
+  const maxLen = Math.max(...allLabels.map((l) => l.length))
+
+  let first = true
+  for (const [section, fields] of sections) {
+    if (!first) lines.push(c.gray(BOX_MID))
+    first = false
+
+    if (section) {
+      lines.push(`${c.gray(BOX_MID)} ${c.cyan(section)}`)
+    }
+
+    for (const field of fields) {
+      const parts = field.path.split(".")
+      const key = parts[parts.length - 1]
+      const indent = section ? "  " : ""
+      const value = getNestedValue(config, field.path)
+      const formatted = formatValue(value, field)
+      const padding = " ".repeat(maxLen - key.length + 2)
+
+      lines.push(`${c.gray(BOX_MID)} ${indent}${c.gray(key)}${padding}${formatted}`)
+    }
+  }
+
+  lines.push(c.gray(BOX_BOT))
+  return lines.join("\n")
+}
+
+/**
+ * Print config to stdout with sections and sensitive value masking.
+ */
+export function printConfig(config: unknown, name?: string): void {
+  console.log(formatConfig(config, name))
+}

package/src/env/validate.ts

@@ -0,0 +1,46 @@
+/**
+ * Pure validators for environment variable types.
+ * Each returns the coerced value or throws a descriptive message.
+ */
+
+export function validateString(value: string): string {
+  return value
+}
+
+export function validatePort(value: string): number {
+  const n = parseInt(value, 10)
+  if (isNaN(n) || n < 1 || n > 65535) {
+    throw `expected port number (1–65535), got "${value}"`
+  }
+  return n
+}
+
+export function validateNumber(value: string): number {
+  const n = parseFloat(value)
+  if (isNaN(n)) {
+    throw `expected number, got "${value}"`
+  }
+  return n
+}
+
+export function validateBoolean(value: string): boolean {
+  if (value === "true" || value === "1") return true
+  if (value === "false" || value === "0") return false
+  throw `expected true/false/1/0, got "${value}"`
+}
+
+export function validateUrl(value: string): string {
+  try {
+    new URL(value)
+    return value
+  } catch {
+    throw `expected valid URL, got "${value}"`
+  }
+}
+
+export function validateEnum(value: string, allowed: readonly string[]): string {
+  if (!allowed.includes(value)) {
+    throw `expected ${allowed.join(" | ")}, got "${value}"`
+  }
+  return value
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @vladpazych/dexter — agentic development toolkit.
+ *
+ * Subpath exports:
+ *   dexter/meta     — CLI factory, hook framework, domain commands
+ *   dexter/output   — polymorphic structured output (block, field, render)
+ *   dexter/env      — env file loading
+ *   dexter/pipe     — pipe utilities
+ *   dexter/terminal — terminal helpers
+ *   dexter/claude   — .claude folder management
+ */
+
+export { version } from "./version.ts"
+
+// Re-export top-level env utilities for convenience
+export { applyEnv, loadEnv } from "./env/index.ts"

package/src/meta/adapters/fs.ts

@@ -0,0 +1,22 @@
+/**
+ * FsPort adapter — wraps Node fs for file system operations.
+ */
+
+import { existsSync, readFileSync, writeFileSync, readdirSync, unlinkSync, mkdirSync } from "node:fs"
+
+import type { FsPort } from "../ports.ts"
+
+export function createNodeFs(): FsPort {
+  return {
+    exists: (path) => existsSync(path),
+    readFile: (path) => readFileSync(path, "utf-8"),
+    writeFile: (path, content) => writeFileSync(path, content),
+    readDir: (path) =>
+      readdirSync(path, { withFileTypes: true }).map((d) => ({
+        name: d.name,
+        isDirectory: d.isDirectory(),
+      })),
+    unlink: (path) => unlinkSync(path),
+    mkdir: (path) => mkdirSync(path, { recursive: true }),
+  }
+}

package/src/meta/adapters/git.ts

@@ -0,0 +1,29 @@
+/**
+ * GitPort adapter — wraps Bun.spawnSync for git operations.
+ */
+
+import type { GitPort } from "../ports.ts"
+
+export function createBunGit(): GitPort {
+  return {
+    run(args, env) {
+      const result = Bun.spawnSync(["git", ...args], {
+        stdout: "pipe",
+        stderr: "pipe",
+        env: env ? { ...process.env, ...env } : undefined,
+      })
+      return {
+        success: result.success,
+        stdout: result.stdout.toString(),
+        stderr: result.stderr.toString(),
+      }
+    },
+    checkIgnore(file) {
+      const result = Bun.spawnSync(["git", "check-ignore", "-q", "--", file], {
+        stdout: "pipe",
+        stderr: "pipe",
+      })
+      return result.success
+    },
+  }
+}

package/src/meta/adapters/glob.ts

@@ -0,0 +1,14 @@
+/**
+ * GlobPort adapter — wraps Bun.Glob for pattern matching.
+ */
+
+import type { GlobPort } from "../ports.ts"
+
+export function createBunGlob(): GlobPort {
+  return {
+    match(pattern, candidates) {
+      const glob = new Bun.Glob(pattern)
+      return candidates.filter((f) => glob.match(f))
+    },
+  }
+}

package/src/meta/adapters/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Adapter wiring — creates ControlPorts from real implementations.
+ */
+
+import { homedir, tmpdir } from "node:os"
+
+import type { ControlPorts } from "../ports.ts"
+
+import { createBunGit } from "./git.ts"
+import { createNodeFs } from "./fs.ts"
+import { createNodeProcess } from "./process.ts"
+import { createBunGlob } from "./glob.ts"
+
+export function createControlPorts(root: string): ControlPorts {
+  return {
+    git: createBunGit(),
+    fs: createNodeFs(),
+    process: createNodeProcess(),
+    glob: createBunGlob(),
+    tmpdir: () => tmpdir(),
+    homedir: () => homedir(),
+    root,
+  }
+}

package/src/meta/adapters/process.ts

@@ -0,0 +1,40 @@
+/**
+ * ProcessPort adapter — wraps child_process.spawn + readline for streaming output.
+ */
+
+import { spawn } from "node:child_process"
+import { createInterface } from "node:readline"
+
+import type { ProcessPort } from "../ports.ts"
+
+export function createNodeProcess(): ProcessPort {
+  return {
+    spawn({ cmd, args, cwd, env, timeout }) {
+      const child = spawn(cmd, args, {
+        cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: env ? { ...process.env, ...env } : undefined,
+      })
+
+      let timer: ReturnType<typeof setTimeout> | undefined
+      if (timeout) {
+        timer = setTimeout(() => child.kill(), timeout)
+      }
+
+      return {
+        onLine(stream, cb) {
+          const source = stream === "stdout" ? child.stdout : child.stderr
+          createInterface({ input: source }).on("line", cb)
+        },
+        wait() {
+          return new Promise((resolve) => {
+            child.on("close", (code) => {
+              if (timer) clearTimeout(timer)
+              resolve(code)
+            })
+          })
+        },
+      }
+    },
+  }
+}