dictum-cli 0.1.0

package/src/polisher/templates.ts

@@ -0,0 +1,151 @@
+/**
+ * polisher/templates.ts — resolve polishing templates by name.
+ *
+ * Built-in templates are embedded as text (so they survive `bun build
+ * --compile`). User overrides in ~/.config/dictum/templates/<name>.md take
+ * precedence and are loaded at runtime (added in step 1.4). Frontmatter:
+ *
+ *   ---
+ *   description: ...
+ *   language: en|ru|auto
+ *   ---
+ *   <instruction body>
+ */
+
+import { readdir } from "node:fs/promises"
+import { resolve, sep } from "node:path"
+import type { Template } from "../core/types.ts"
+import agentPromptRaw from "./templates/agent-prompt.md" with { type: "text" }
+import commitRaw from "./templates/commit.md" with { type: "text" }
+import decomposeRaw from "./templates/decompose.md" with { type: "text" }
+import noteRaw from "./templates/note.md" with { type: "text" }
+import specRaw from "./templates/spec.md" with { type: "text" }
+
+// Null prototype: a lookup like BUILTINS["constructor"] must miss instead of
+// returning an inherited Object.prototype member.
+const BUILTINS: Record<string, string> = Object.assign(Object.create(null), {
+  "agent-prompt": agentPromptRaw,
+  commit: commitRaw,
+  decompose: decomposeRaw,
+  note: noteRaw,
+  spec: specRaw,
+})
+
+/** Parse a markdown template (frontmatter + body) into a Template. */
+export function parseTemplate(name: string, raw: string): Template {
+  let description = ""
+  let language = "auto"
+  let body = raw
+
+  const fm = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(raw)
+  if (fm?.[1] !== undefined) {
+    for (const line of fm[1].split(/\r?\n/)) {
+      const m = /^([A-Za-z_][\w-]*)\s*:\s*(.*)$/.exec(line.trim())
+      if (!m) continue
+      const key = m[1]!.toLowerCase()
+      const value = m[2]!.trim().replace(/^["']|["']$/g, "")
+      if (key === "description") description = value
+      else if (key === "language") language = value
+    }
+    body = raw.slice(fm[0].length)
+  }
+
+  return { name, description, language, instruction: body.trim() }
+}
+
+/** Names of the built-in templates. */
+export function builtinTemplateNames(): string[] {
+  return Object.keys(BUILTINS)
+}
+
+/** Resolve a built-in template by name; throws with a helpful list if unknown. */
+export function resolveBuiltinTemplate(name: string): Template {
+  const raw = BUILTINS[name]
+  if (raw === undefined) {
+    throw new Error(`Unknown template '${name}'. Available: ${builtinTemplateNames().join(", ")}`)
+  }
+  return parseTemplate(name, raw)
+}
+
+/**
+ * All template names available: built-ins plus user overrides in `userDir`.
+ * Only valid slugs are advertised — the listing and the resolver share one
+ * validator, so every advertised name is guaranteed to resolve.
+ */
+export async function availableTemplateNames(userDir?: string): Promise<string[]> {
+  const names = new Set(builtinTemplateNames())
+  if (userDir) {
+    try {
+      for (const entry of await readdir(userDir, { withFileTypes: true })) {
+        // Regular files only: a directory named `x.md` must not be advertised
+        // (it can never resolve). Symlinked templates resolve but are not
+        // listed — advertised ⊆ resolvable is the invariant.
+        if (!entry.isFile() || !entry.name.endsWith(".md")) continue
+        const stem = entry.name.slice(0, -3)
+        if (isValidTemplateName(stem)) names.add(stem)
+      }
+    } catch {
+      // user template directory may not exist — ignore
+    }
+  }
+  return [...names].sort()
+}
+
+/**
+ * A template name (the file stem, i.e. the `mode`) is a portable ASCII slug:
+ * starts with a letter/digit/underscore, then word characters, dots or dashes
+ * — no path separators, no `..`, no NULs, no spaces or non-ASCII. Template
+ * titles, descriptions and bodies stay full Unicode; only the technical file
+ * ID is restricted so behavior is identical across Linux/macOS/Windows and a
+ * name can never escape the template directory (`mode` reaches this from the
+ * CLI and from MCP callers). Shared by the resolver and the listing.
+ */
+const SAFE_NAME_RE = /^[A-Za-z0-9_][\w.-]*$/
+
+/** Windows reserves these device names (bare or with any extension). */
+const WINDOWS_RESERVED_RE = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i
+
+/** True when `name` is a portable template slug the resolver will accept. */
+export function isValidTemplateName(name: string): boolean {
+  return SAFE_NAME_RE.test(name) && !name.includes("..") && !WINDOWS_RESERVED_RE.test(name)
+}
+
+function assertSafeTemplateName(name: string): void {
+  if (!name || !isValidTemplateName(name)) {
+    throw new Error(
+      `Invalid template name '${name}': names must be plain file stems without path separators`,
+    )
+  }
+}
+
+/**
+ * Resolve a template by name. A user override at `<userDir>/<name>.md` takes
+ * precedence over the built-in. Throws with the available list if not found,
+ * and rejects names that could traverse outside the template directory.
+ *
+ * Trust model: the user template directory is the user's own config dir and
+ * is treated as trusted — containment is lexical (resolve + prefix), and
+ * symlinks inside it are followed. This blocks caller-controlled traversal
+ * via `mode`; it does not defend against a hostile local filesystem.
+ */
+export async function resolveTemplate(name: string, userDir?: string): Promise<Template> {
+  assertSafeTemplateName(name)
+  if (userDir) {
+    const root = resolve(userDir)
+    const path = resolve(root, `${name}.md`)
+    // Second belt after the name check: the resolved path must stay inside.
+    if (!path.startsWith(root + sep)) {
+      throw new Error(`Invalid template name '${name}': escapes the template directory`)
+    }
+    const file = Bun.file(path)
+    if (await file.exists()) {
+      return parseTemplate(name, await file.text())
+    }
+  }
+  const raw = BUILTINS[name]
+  if (raw !== undefined) {
+    return parseTemplate(name, raw)
+  }
+  const available = await availableTemplateNames(userDir)
+  throw new Error(`Unknown template '${name}'. Available: ${available.join(", ")}`)
+}

package/src/recorder/file.ts

@@ -0,0 +1,35 @@
+/**
+ * recorder/file.ts — a Recorder that reads audio from a WAV file (`--input`).
+ *
+ * Used for testing and SSH/headless flows where there is no microphone. The
+ * input is normalized to canonical PCM16/16k/mono via ffmpeg when needed.
+ */
+
+import { readFile } from "node:fs/promises"
+import type { AudioData, Recorder } from "../core/types.ts"
+import { isCanonical, parseWavFormat, transcodeToCanonical } from "./wav.ts"
+
+export class FileRecorder implements Recorder {
+  constructor(private readonly path: string) {}
+
+  async record(_signal: AbortSignal): Promise<AudioData> {
+    let bytes: Uint8Array
+    try {
+      bytes = new Uint8Array(await readFile(this.path))
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err)
+      throw new Error(`Cannot read input file '${this.path}': ${reason}`)
+    }
+
+    let fmt: ReturnType<typeof parseWavFormat>
+    try {
+      fmt = parseWavFormat(bytes)
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err)
+      throw new Error(`'${this.path}' is not a valid WAV file: ${reason}`)
+    }
+
+    const wav = isCanonical(fmt) ? bytes : await transcodeToCanonical(bytes)
+    return { wav, sampleRate: 16000, channels: 1 }
+  }
+}

package/src/recorder/sox.ts

@@ -0,0 +1,165 @@
+/**
+ * recorder/sox.ts — capture from the microphone via sox `rec`, streaming raw
+ * PCM16 so we can endpoint live (energy VAD) instead of waiting for a file.
+ *
+ * The recording loop (`captureStream`) is pure over a ReadableStream and is
+ * unit-tested with synthetic PCM — no microphone needed. Stops on: the abort
+ * signal (Enter / push-to-talk / SIGINT, wired in cli via ui/keys), an energy
+ * VAD endpoint, or the max-duration cap. Live mic capture is verified manually.
+ */
+
+import type { AudioData, Recorder } from "../core/types.ts"
+import { SilenceDetector, type VadOptions } from "./vad.ts"
+import { pcmToWav } from "./wav.ts"
+
+const SAMPLE_RATE = 16000
+const BYTES_PER_SAMPLE = 2
+const VAD_FRAME_SAMPLES = 320 // 20 ms @ 16 kHz
+
+export type SoxOptions = {
+  /** Binary to invoke; sox ships `rec` as a recording front-end. */
+  bin?: string
+  /** Hard safety cap in seconds. */
+  maxDuration?: number
+  /** Enable energy-based silence auto-stop. */
+  vad?: boolean
+  /** VAD tuning (threshold, silence timeout, …). */
+  vadOptions?: VadOptions
+}
+
+export type CaptureOptions = {
+  signal: AbortSignal
+  /** Optional detector; when present, the loop stops at the speech endpoint. */
+  vad?: SilenceDetector
+  /** Hard byte cap; the loop stops once this many PCM bytes are buffered. */
+  maxBytes: number
+  frameSamples?: number
+}
+
+function concatChunks(chunks: Uint8Array[], total: number): Uint8Array {
+  const out = new Uint8Array(total)
+  let off = 0
+  for (const c of chunks) {
+    out.set(c, off)
+    off += c.length
+  }
+  return out
+}
+
+/** Decode little-endian PCM16 bytes to Int16 samples for energy analysis. */
+function pcm16le(bytes: Uint8Array): Int16Array {
+  const n = bytes.length >> 1
+  const out = new Int16Array(n)
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  for (let i = 0; i < n; i++) out[i] = view.getInt16(i * 2, true)
+  return out
+}
+
+/**
+ * Consume a raw-PCM stream until the signal aborts, the VAD endpoints, or the
+ * byte cap is hit. Returns the accumulated PCM16 bytes. Pure and testable.
+ */
+export async function captureStream(
+  stream: ReadableStream<Uint8Array>,
+  opts: CaptureOptions,
+): Promise<Uint8Array> {
+  const frameBytes = (opts.frameSamples ?? VAD_FRAME_SAMPLES) * BYTES_PER_SAMPLE
+  const chunks: Uint8Array[] = []
+  let total = 0
+  let leftover: Uint8Array = new Uint8Array(0)
+  const reader = stream.getReader()
+  const onAbort = () => {
+    reader.cancel().catch(() => {})
+  }
+  opts.signal.addEventListener("abort", onAbort, { once: true })
+
+  try {
+    while (!opts.signal.aborted) {
+      const { done, value } = await reader.read()
+      if (done || !value) break
+      chunks.push(value)
+      total += value.length
+      if (total >= opts.maxBytes) break
+
+      if (opts.vad) {
+        // frame leftover+value into fixed VAD windows
+        const merged = leftover.length
+          ? concatChunks([leftover, value], leftover.length + value.length)
+          : value
+        let off = 0
+        let endpoint = false
+        while (merged.length - off >= frameBytes) {
+          if (opts.vad.push(pcm16le(merged.subarray(off, off + frameBytes)))) {
+            endpoint = true
+            break
+          }
+          off += frameBytes
+        }
+        leftover = merged.subarray(off)
+        if (endpoint) break
+      }
+    }
+  } finally {
+    opts.signal.removeEventListener("abort", onAbort)
+    reader.releaseLock()
+  }
+  return concatChunks(chunks, total)
+}
+
+export class SoxRecorder implements Recorder {
+  private readonly bin: string
+  private readonly maxDuration: number
+  private readonly vadEnabled: boolean
+  private readonly vadOptions: VadOptions
+
+  constructor(opts: SoxOptions = {}) {
+    this.bin = opts.bin ?? "rec"
+    this.maxDuration = opts.maxDuration ?? 120
+    this.vadEnabled = opts.vad ?? false
+    this.vadOptions = opts.vadOptions ?? {}
+  }
+
+  async record(signal: AbortSignal): Promise<AudioData> {
+    const proc = Bun.spawn(
+      [
+        this.bin,
+        "-q",
+        "-c",
+        "1",
+        "-r",
+        String(SAMPLE_RATE),
+        "-b",
+        "16",
+        "-e",
+        "signed-integer",
+        "-t",
+        "raw",
+        "-", // stream raw PCM to stdout
+      ],
+      { stdin: "ignore", stdout: "pipe", stderr: "pipe" },
+    )
+
+    const vad = this.vadEnabled
+      ? new SilenceDetector({ sampleRate: SAMPLE_RATE, ...this.vadOptions })
+      : undefined
+    const maxBytes = Math.max(1, this.maxDuration * SAMPLE_RATE * BYTES_PER_SAMPLE)
+
+    const captureOpts: CaptureOptions = vad ? { signal, vad, maxBytes } : { signal, maxBytes }
+
+    let pcm: Uint8Array
+    try {
+      pcm = await captureStream(proc.stdout, captureOpts)
+    } finally {
+      proc.kill("SIGINT")
+      await proc.exited
+    }
+
+    if (pcm.length < BYTES_PER_SAMPLE) {
+      const err = (await new Response(proc.stderr).text()).trim()
+      throw new Error(
+        `${this.bin}: no audio captured. ${err || "is sox installed? → apt install sox / brew install sox"}`,
+      )
+    }
+    return { wav: pcmToWav(pcm), sampleRate: 16000, channels: 1 }
+  }
+}

package/src/recorder/vad.ts

@@ -0,0 +1,100 @@
+/**
+ * recorder/vad.ts — energy-based voice-activity endpointing.
+ *
+ * Pure math over PCM16 samples: compute frame energy, and detect the end of an
+ * utterance once trailing silence exceeds a configurable timeout. No I/O, no
+ * project imports — fully unit-testable on synthetic buffers. The live wiring
+ * (feeding frames from the recorder) is done in cli.ts/recorder during step 1.6.
+ */
+
+export type VadOptions = {
+  /** Sample rate of the PCM data (Hz). */
+  sampleRate?: number
+  /** Voicing threshold as normalized RMS in [0, 1]. */
+  energyThreshold?: number
+  /** Stop after this much trailing silence, in seconds. */
+  silenceTimeoutSec?: number
+  /** Minimum cumulative voiced time before endpointing can trigger (ms). */
+  minSpeechMs?: number
+}
+
+const PCM16_FULL_SCALE = 32768
+
+/** Root-mean-square energy of a PCM16 frame, normalized to [0, 1]. */
+export function rmsEnergy(samples: Int16Array): number {
+  if (samples.length === 0) return 0
+  let sumSq = 0
+  for (let i = 0; i < samples.length; i++) {
+    const s = samples[i]! / PCM16_FULL_SCALE
+    sumSq += s * s
+  }
+  return Math.sqrt(sumSq / samples.length)
+}
+
+/**
+ * Streaming endpoint detector. Feed PCM16 frames via push(); it returns true the
+ * first time end-of-speech is detected (≥ silenceTimeout of trailing silence
+ * after at least minSpeechMs of voiced audio).
+ */
+export class SilenceDetector {
+  private readonly sampleRate: number
+  private readonly threshold: number
+  private readonly silenceTimeoutMs: number
+  private readonly minSpeechMs: number
+  private speechMs = 0
+  private silenceMs = 0
+  private started = false
+
+  constructor(opts: VadOptions = {}) {
+    this.sampleRate = opts.sampleRate ?? 16000
+    this.threshold = opts.energyThreshold ?? 0.015
+    this.silenceTimeoutMs = (opts.silenceTimeoutSec ?? 2.0) * 1000
+    this.minSpeechMs = opts.minSpeechMs ?? 100
+  }
+
+  /** True once trailing silence after speech reaches the timeout. */
+  push(frame: Int16Array): boolean {
+    if (frame.length === 0) return false
+    const frameMs = (frame.length / this.sampleRate) * 1000
+    const voiced = rmsEnergy(frame) >= this.threshold
+    if (voiced) {
+      this.speechMs += frameMs
+      this.silenceMs = 0
+      if (this.speechMs >= this.minSpeechMs) this.started = true
+    } else if (this.started) {
+      this.silenceMs += frameMs
+      if (this.silenceMs >= this.silenceTimeoutMs) return true
+    }
+    return false
+  }
+
+  /** Whether enough voiced audio has been seen to consider speech started. */
+  get hasStarted(): boolean {
+    return this.started
+  }
+
+  reset(): void {
+    this.speechMs = 0
+    this.silenceMs = 0
+    this.started = false
+  }
+}
+
+/**
+ * Batch helper: run the detector over a whole PCM16 buffer in fixed frames and
+ * return the sample index at which endpointing fires, or null if it never does.
+ */
+export function detectEndpoint(
+  samples: Int16Array,
+  opts: VadOptions & { frameMs?: number } = {},
+): number | null {
+  const sampleRate = opts.sampleRate ?? 16000
+  const frameMs = opts.frameMs ?? 20
+  const frameSize = Math.max(1, Math.round((sampleRate * frameMs) / 1000))
+  const detector = new SilenceDetector(opts)
+  for (let i = 0; i < samples.length; i += frameSize) {
+    const end = Math.min(i + frameSize, samples.length)
+    if (detector.push(samples.subarray(i, end))) return end
+  }
+  return null
+}

package/src/recorder/wav.ts

@@ -0,0 +1,150 @@
+/**
+ * recorder/wav.ts — minimal RIFF/WAVE parsing and canonicalization helpers.
+ *
+ * Part of the recorder module. Depends only on Node/Bun built-ins (and ffmpeg
+ * at runtime for transcoding non-canonical inputs). The canonical format used
+ * across Dictum is PCM16, 16 kHz, mono — see core/types.ts AudioData.
+ */
+
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+
+export type WavFormat = {
+  audioFormat: number // 1 = PCM
+  channels: number
+  sampleRate: number
+  bitsPerSample: number
+}
+
+const CANONICAL_RATE = 16000
+const CANONICAL_CHANNELS = 1
+const CANONICAL_BITS = 16
+
+function readFourCC(bytes: Uint8Array, offset: number): string {
+  return String.fromCharCode(
+    bytes[offset]!,
+    bytes[offset + 1]!,
+    bytes[offset + 2]!,
+    bytes[offset + 3]!,
+  )
+}
+
+/**
+ * Parse the `fmt ` chunk of a WAV file. Tolerates extra chunks (LIST, fact, …)
+ * appearing before `data`. Throws on a non-RIFF/WAVE input.
+ */
+export function parseWavFormat(bytes: Uint8Array): WavFormat {
+  if (bytes.length < 12 || readFourCC(bytes, 0) !== "RIFF" || readFourCC(bytes, 8) !== "WAVE") {
+    throw new Error("Not a RIFF/WAVE file")
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+  let offset = 12
+  while (offset + 8 <= bytes.length) {
+    const id = readFourCC(bytes, offset)
+    const size = view.getUint32(offset + 4, true)
+    const body = offset + 8
+    if (id === "fmt ") {
+      return {
+        audioFormat: view.getUint16(body, true),
+        channels: view.getUint16(body + 2, true),
+        sampleRate: view.getUint32(body + 4, true),
+        bitsPerSample: view.getUint16(body + 14, true),
+      }
+    }
+    // chunks are word-aligned (pad to even length)
+    offset = body + size + (size % 2)
+  }
+  throw new Error("WAV is missing a 'fmt ' chunk")
+}
+
+function writeAscii(buf: Uint8Array, offset: number, text: string): void {
+  for (let i = 0; i < text.length; i++) buf[offset + i] = text.charCodeAt(i)
+}
+
+/**
+ * Wrap raw PCM16 little-endian bytes in a canonical WAV container (44-byte
+ * header). Defaults to 16 kHz mono — the format Dictum captures.
+ */
+export function pcmToWav(
+  pcm: Uint8Array,
+  opts: { sampleRate?: number; channels?: number } = {},
+): Uint8Array {
+  const sampleRate = opts.sampleRate ?? CANONICAL_RATE
+  const channels = opts.channels ?? CANONICAL_CHANNELS
+  const bitsPerSample = CANONICAL_BITS
+  const blockAlign = (channels * bitsPerSample) / 8
+  const byteRate = sampleRate * blockAlign
+  const dataSize = pcm.length
+
+  const buf = new Uint8Array(44 + dataSize)
+  const view = new DataView(buf.buffer)
+  writeAscii(buf, 0, "RIFF")
+  view.setUint32(4, 36 + dataSize, true)
+  writeAscii(buf, 8, "WAVE")
+  writeAscii(buf, 12, "fmt ")
+  view.setUint32(16, 16, true) // fmt chunk size (PCM)
+  view.setUint16(20, 1, true) // audioFormat = PCM
+  view.setUint16(22, channels, true)
+  view.setUint32(24, sampleRate, true)
+  view.setUint32(28, byteRate, true)
+  view.setUint16(32, blockAlign, true)
+  view.setUint16(34, bitsPerSample, true)
+  writeAscii(buf, 36, "data")
+  view.setUint32(40, dataSize, true)
+  buf.set(pcm, 44)
+  return buf
+}
+
+/** True when the WAV is already PCM16 / 16 kHz / mono. */
+export function isCanonical(fmt: WavFormat): boolean {
+  return (
+    fmt.audioFormat === 1 &&
+    fmt.channels === CANONICAL_CHANNELS &&
+    fmt.sampleRate === CANONICAL_RATE &&
+    fmt.bitsPerSample === CANONICAL_BITS
+  )
+}
+
+/**
+ * Transcode arbitrary WAV bytes into canonical PCM16/16k/mono using ffmpeg.
+ * Used only when the input is not already canonical.
+ */
+export async function transcodeToCanonical(bytes: Uint8Array): Promise<Uint8Array> {
+  const dir = await mkdtemp(join(tmpdir(), "dictum-wav-"))
+  const inPath = join(dir, "in.wav")
+  const outPath = join(dir, "out.wav")
+  try {
+    await writeFile(inPath, bytes)
+    const proc = Bun.spawn(
+      [
+        "ffmpeg",
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-y",
+        "-i",
+        inPath,
+        "-ar",
+        String(CANONICAL_RATE),
+        "-ac",
+        String(CANONICAL_CHANNELS),
+        "-sample_fmt",
+        "s16",
+        "-f",
+        "wav",
+        outPath,
+      ],
+      { stdout: "pipe", stderr: "pipe" },
+    )
+    const code = await proc.exited
+    if (code !== 0) {
+      const err = await new Response(proc.stderr).text()
+      throw new Error(`ffmpeg transcode failed (exit ${code}): ${err.trim() || "unknown error"}`)
+    }
+    const out = await readFile(outPath)
+    return new Uint8Array(out)
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+}