dictum-cli 0.1.0

package/src/sink/clipboard.ts

@@ -0,0 +1,153 @@
+/**
+ * sink/clipboard.ts — copy text to the system clipboard.
+ *
+ * Mechanism selection:
+ *   - SSH session (SSH_CONNECTION / SSH_TTY)  → OSC52 escape sequence to the
+ *     terminal (works through SSH; the local terminal emulator receives it).
+ *   - Wayland (WAYLAND_DISPLAY + wl-copy)     → wl-copy
+ *   - macOS (pbcopy)                          → pbcopy
+ *   - X11 (xclip)                             → xclip -selection clipboard
+ *   - otherwise                               → error with an actionable hint.
+ *
+ * tmux is handled by wrapping OSC52 in a DCS passthrough when $TMUX is set.
+ */
+
+import { closeSync, openSync, writeSync } from "node:fs"
+import type { Sink } from "../core/types.ts"
+
+type Which = (bin: string) => string | null
+
+const ESC = "\x1b"
+const BEL = "\x07"
+
+export type ClipboardMechanism =
+  | { kind: "osc52"; label: string }
+  | { kind: "command"; label: string; argv: string[] }
+  | { kind: "none"; label: string }
+
+function isSshSession(env: NodeJS.ProcessEnv): boolean {
+  return Boolean(env.SSH_CONNECTION || env.SSH_TTY)
+}
+
+/** Pick the clipboard mechanism for the current environment. */
+export function detectClipboard(
+  env: NodeJS.ProcessEnv = process.env,
+  which: Which = (b) => Bun.which(b),
+  hasTty: boolean = Boolean(process.stdout.isTTY || process.stderr.isTTY),
+): ClipboardMechanism {
+  // OSC52 writes an escape sequence to the terminal — without an interactive
+  // TTY (cron, CI, `ssh host cmd`) there is nowhere to write. In that case
+  // fall through: X11 forwarding / a local display may still provide a
+  // clipboard tool that works.
+  const ssh = isSshSession(env)
+  if (ssh && hasTty) {
+    return { kind: "osc52", label: "OSC52 (SSH session)" }
+  }
+  if (env.WAYLAND_DISPLAY && which("wl-copy")) {
+    return { kind: "command", label: "wl-copy (wayland)", argv: ["wl-copy"] }
+  }
+  if (which("pbcopy")) {
+    return { kind: "command", label: "pbcopy (macOS)", argv: ["pbcopy"] }
+  }
+  if (env.DISPLAY && which("xclip")) {
+    return {
+      kind: "command",
+      label: "xclip (x11)",
+      argv: ["xclip", "-selection", "clipboard"],
+    }
+  }
+  if (ssh) {
+    return {
+      kind: "none",
+      label: "SSH session without an interactive terminal (OSC52 unavailable)",
+    }
+  }
+  // A display-bound tool on PATH without a display would fail at copy time
+  // ("Can't open display") — report it as unavailable, not as ok.
+  if (which("wl-copy") || which("xclip")) {
+    return {
+      kind: "none",
+      label: "clipboard tool found, but no display (DISPLAY/WAYLAND_DISPLAY unset)",
+    }
+  }
+  return { kind: "none", label: "no clipboard tool found" }
+}
+
+/**
+ * Build an OSC52 clipboard escape sequence for `text`. When `tmux` is true the
+ * sequence is wrapped in a tmux DCS passthrough so it reaches the outer terminal.
+ * Format: ESC ] 52 ; c ; <base64> BEL
+ */
+export function buildOsc52(text: string, opts: { tmux?: boolean } = {}): string {
+  const b64 = Buffer.from(text, "utf8").toString("base64")
+  const seq = `${ESC}]52;c;${b64}${BEL}`
+  if (opts.tmux) {
+    // tmux passthrough: ESC P tmux; <payload with ESC doubled> ESC \
+    const inner = seq.replaceAll(ESC, ESC + ESC)
+    return `${ESC}Ptmux;${inner}${ESC}\\`
+  }
+  return seq
+}
+
+/**
+ * Write an OSC52 sequence to the controlling terminal. Prefers /dev/tty; falls
+ * back to stderr only when it's a TTY. Returns false when no real terminal is
+ * reachable (a pipe / cron) so the caller can advise --stdout instead of
+ * littering escape bytes into the output.
+ */
+function writeToTerminal(seq: string): boolean {
+  try {
+    const fd = openSync("/dev/tty", "w")
+    try {
+      writeSync(fd, seq)
+    } finally {
+      closeSync(fd)
+    }
+    return true
+  } catch {
+    if (process.stderr.isTTY) {
+      process.stderr.write(seq)
+      return true
+    }
+    return false
+  }
+}
+
+export class ClipboardSink implements Sink {
+  constructor(
+    private readonly env: NodeJS.ProcessEnv = process.env,
+    private readonly which: Which = (b) => Bun.which(b),
+  ) {}
+
+  async emit(text: string): Promise<void> {
+    const mech = detectClipboard(this.env, this.which)
+    if (mech.kind === "osc52") {
+      const ok = writeToTerminal(buildOsc52(text, { tmux: Boolean(this.env.TMUX) }))
+      if (!ok) {
+        throw new Error(
+          "Clipboard over SSH (OSC52) needs an interactive terminal. " +
+            "Use --stdout to pipe the result (e.g. `dictum --stdout | claude`).",
+        )
+      }
+      return
+    }
+    if (mech.kind === "command") {
+      const proc = Bun.spawn(mech.argv, { stdin: "pipe", stdout: "ignore", stderr: "pipe" })
+      proc.stdin.write(text)
+      await proc.stdin.end()
+      const code = await proc.exited
+      if (code !== 0) {
+        const err = (await new Response(proc.stderr).text()).trim()
+        throw new Error(
+          `clipboard command '${mech.argv[0]}' failed (exit ${code})${err ? `: ${err}` : ""}`,
+        )
+      }
+      return
+    }
+    // Lead with the detector's diagnosis — "OSC52 needs an interactive
+    // terminal" must not be answered with "OSC52 is automatic".
+    throw new Error(
+      `Clipboard unavailable: ${mech.label}. Use --stdout, or install xclip / wl-clipboard.`,
+    )
+  }
+}

package/src/sink/factory.ts

@@ -0,0 +1,31 @@
+/**
+ * sink/factory.ts — build a Sink from a target name.
+ *
+ * Validates the name (human-readable error on a bad config/env value) and
+ * constructs the matching sink. Imports only core/types.ts and sibling sink
+ * files (own module).
+ */
+
+import type { Sink } from "../core/types.ts"
+import { ClipboardSink } from "./clipboard.ts"
+import { StdoutSink } from "./stdout.ts"
+
+export const VALID_SINKS = ["clipboard", "stdout"] as const
+export type SinkName = (typeof VALID_SINKS)[number]
+
+function isValidName(name: string): name is SinkName {
+  return (VALID_SINKS as readonly string[]).includes(name)
+}
+
+/** Construct the named Sink; throws on an unknown target. */
+export function createSink(name: string): Sink {
+  if (!isValidName(name)) {
+    throw new Error(`Unknown sink '${name}'. Valid: ${VALID_SINKS.join(", ")}`)
+  }
+  switch (name) {
+    case "clipboard":
+      return new ClipboardSink()
+    case "stdout":
+      return new StdoutSink()
+  }
+}

package/src/sink/stdout.ts

@@ -0,0 +1,17 @@
+/**
+ * sink/stdout.ts — a Sink that writes the final text to stdout.
+ *
+ * Suited for shell pipes: `dictum --stdout | claude`. A trailing newline is
+ * added unless the text already ends with one.
+ */
+
+import type { Sink } from "../core/types.ts"
+
+export class StdoutSink implements Sink {
+  async emit(text: string): Promise<void> {
+    const out = text.endsWith("\n") ? text : `${text}\n`
+    await new Promise<void>((resolve, reject) => {
+      process.stdout.write(out, (err) => (err ? reject(err) : resolve()))
+    })
+  }
+}

package/src/stt/factory.ts

@@ -0,0 +1,89 @@
+/**
+ * stt/factory.ts — build an STTProvider from configuration.
+ *
+ * Providers are tried in the configured order. transcribe() health-checks each
+ * candidate and falls back to the next when one is unhealthy or errors, so a
+ * dead primary (e.g. local server down) transparently fails over to a cloud
+ * backend. Imports only core/types.ts and sibling stt files (own module).
+ */
+
+import type { AudioData, STTProvider } from "../core/types.ts"
+import { LocalHttpStt } from "./local_http.ts"
+import { OpenAiCompatStt } from "./openai_compat.ts"
+
+export const VALID_STT_PROVIDERS = ["local_http", "openai_compat"] as const
+export type SttProviderName = (typeof VALID_STT_PROVIDERS)[number]
+
+/** Structural config the factory needs (mirrors Config["stt"], no import). */
+export type SttFactoryConfig = {
+  providers: string[]
+  local_http: { baseUrl: string }
+  openai_compat: { baseUrl: string; apiKey: string; model: string; language: string }
+}
+
+export type NamedProvider = { name: SttProviderName; provider: STTProvider }
+
+function isValidName(name: string): name is SttProviderName {
+  return (VALID_STT_PROVIDERS as readonly string[]).includes(name)
+}
+
+function instantiate(name: SttProviderName, cfg: SttFactoryConfig): STTProvider {
+  switch (name) {
+    case "local_http":
+      return new LocalHttpStt({ baseUrl: cfg.local_http.baseUrl })
+    case "openai_compat":
+      return new OpenAiCompatStt({
+        baseUrl: cfg.openai_compat.baseUrl,
+        apiKey: cfg.openai_compat.apiKey,
+        model: cfg.openai_compat.model,
+        language: cfg.openai_compat.language,
+      })
+  }
+}
+
+/** Build the ordered list of named providers, validating each name. */
+export function buildSttProviders(cfg: SttFactoryConfig): NamedProvider[] {
+  if (cfg.providers.length === 0) {
+    throw new Error("No STT providers configured ([stt].providers is empty)")
+  }
+  return cfg.providers.map((name) => {
+    if (!isValidName(name)) {
+      throw new Error(`Unknown STT provider '${name}'. Valid: ${VALID_STT_PROVIDERS.join(", ")}`)
+    }
+    return { name, provider: instantiate(name, cfg) }
+  })
+}
+
+/** An STTProvider that fails over across an ordered list of backends. */
+export class FallbackStt implements STTProvider {
+  constructor(private readonly providers: NamedProvider[]) {}
+
+  async health(): Promise<boolean> {
+    for (const p of this.providers) {
+      if (await p.provider.health()) return true
+    }
+    return false
+  }
+
+  async transcribe(audio: AudioData): Promise<string> {
+    const errors: string[] = []
+    for (const p of this.providers) {
+      const healthy = await p.provider.health()
+      if (!healthy) {
+        errors.push(`${p.name}: unhealthy`)
+        continue
+      }
+      try {
+        return await p.provider.transcribe(audio)
+      } catch (err) {
+        errors.push(`${p.name}: ${err instanceof Error ? err.message : String(err)}`)
+      }
+    }
+    throw new Error(`All STT providers failed:\n  - ${errors.join("\n  - ")}`)
+  }
+}
+
+/** Construct the composite STTProvider from config. */
+export function createSttProvider(cfg: SttFactoryConfig): STTProvider {
+  return new FallbackStt(buildSttProviders(cfg))
+}

package/src/stt/local_http.ts

@@ -0,0 +1,75 @@
+/**
+ * stt/local_http.ts — STTProvider for a local GigaAM-compatible HTTP server.
+ *
+ * Contract:
+ *   GET  {base}/health      -> { loaded: boolean, ... }
+ *   POST {base}/transcribe  body { path: string } -> { text: string, duration?: number }
+ *
+ * The server reads audio by filesystem path, so we materialize the WAV to a
+ * temp file on this host before posting. Same-host only.
+ */
+
+import { mkdtemp, rm, writeFile } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import type { AudioData, STTProvider } from "../core/types.ts"
+
+export type LocalHttpOptions = {
+  baseUrl: string
+  /** Per-request timeout in milliseconds. */
+  timeoutMs?: number
+}
+
+export class LocalHttpStt implements STTProvider {
+  private readonly baseUrl: string
+  private readonly timeoutMs: number
+
+  constructor(opts: LocalHttpOptions) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "")
+    this.timeoutMs = opts.timeoutMs ?? 60000
+  }
+
+  async health(): Promise<boolean> {
+    try {
+      const res = await fetch(`${this.baseUrl}/health`, {
+        signal: AbortSignal.timeout(Math.min(this.timeoutMs, 5000)),
+      })
+      if (!res.ok) return false
+      const body = (await res.json()) as { loaded?: boolean }
+      return body.loaded === true
+    } catch {
+      return false
+    }
+  }
+
+  async transcribe(audio: AudioData): Promise<string> {
+    const dir = await mkdtemp(join(tmpdir(), "dictum-stt-"))
+    const wavPath = join(dir, "audio.wav")
+    try {
+      await writeFile(wavPath, audio.wav)
+      let res: Response
+      try {
+        res = await fetch(`${this.baseUrl}/transcribe`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ path: wavPath }),
+          signal: AbortSignal.timeout(this.timeoutMs),
+        })
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err)
+        throw new Error(`local STT request to ${this.baseUrl} failed: ${reason}`)
+      }
+      if (!res.ok) {
+        const detail = (await res.text()).trim()
+        throw new Error(`local STT returned ${res.status}${detail ? `: ${detail}` : ""}`)
+      }
+      const body = (await res.json()) as { text?: unknown }
+      if (typeof body.text !== "string") {
+        throw new Error("local STT response missing 'text' field")
+      }
+      return body.text.trim()
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  }
+}

package/src/stt/openai_compat.ts

@@ -0,0 +1,83 @@
+/**
+ * stt/openai_compat.ts — STTProvider for OpenAI-compatible transcription APIs.
+ *
+ * Works with OpenAI, Groq, and local whisper-servers exposing
+ *   POST {base}/v1/audio/transcriptions   (multipart: file, model, language)
+ *   GET  {base}/v1/models                 (used as a liveness/auth probe)
+ *
+ * Sends the WAV in-memory as multipart form data; no temp file needed.
+ */
+
+import type { AudioData, STTProvider } from "../core/types.ts"
+
+export type OpenAiCompatOptions = {
+  baseUrl: string
+  apiKey: string
+  model: string
+  /** Optional language hint (ISO code). Empty = let the server auto-detect. */
+  language: string
+  /** Per-request timeout in milliseconds. */
+  timeoutMs?: number
+}
+
+export class OpenAiCompatStt implements STTProvider {
+  private readonly baseUrl: string
+  private readonly apiKey: string
+  private readonly model: string
+  private readonly language: string
+  private readonly timeoutMs: number
+
+  constructor(opts: OpenAiCompatOptions) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "")
+    this.apiKey = opts.apiKey
+    this.model = opts.model
+    this.language = opts.language
+    this.timeoutMs = opts.timeoutMs ?? 60000
+  }
+
+  private authHeaders(): Record<string, string> {
+    return this.apiKey ? { authorization: `Bearer ${this.apiKey}` } : {}
+  }
+
+  async health(): Promise<boolean> {
+    try {
+      const res = await fetch(`${this.baseUrl}/v1/models`, {
+        headers: this.authHeaders(),
+        signal: AbortSignal.timeout(Math.min(this.timeoutMs, 5000)),
+      })
+      return res.ok
+    } catch {
+      return false
+    }
+  }
+
+  async transcribe(audio: AudioData): Promise<string> {
+    const form = new FormData()
+    form.append("file", new Blob([audio.wav], { type: "audio/wav" }), "audio.wav")
+    form.append("model", this.model)
+    form.append("response_format", "json")
+    if (this.language) form.append("language", this.language)
+
+    let res: Response
+    try {
+      res = await fetch(`${this.baseUrl}/v1/audio/transcriptions`, {
+        method: "POST",
+        headers: this.authHeaders(),
+        body: form,
+        signal: AbortSignal.timeout(this.timeoutMs),
+      })
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err)
+      throw new Error(`OpenAI-compatible STT request to ${this.baseUrl} failed: ${reason}`)
+    }
+    if (!res.ok) {
+      const detail = (await res.text()).trim()
+      throw new Error(`OpenAI-compatible STT returned ${res.status}${detail ? `: ${detail}` : ""}`)
+    }
+    const body = (await res.json()) as { text?: unknown }
+    if (typeof body.text !== "string") {
+      throw new Error("OpenAI-compatible STT response missing 'text' field")
+    }
+    return body.text.trim()
+  }
+}

package/src/ui/choose.ts

@@ -0,0 +1,95 @@
+/**
+ * ui/choose.ts — interactive selection between the user's original words and the
+ * polished candidate.
+ *
+ * Dictum proposes a polished prompt rather than blindly replacing the input: on
+ * an interactive terminal it shows both and asks which to emit, with the option
+ * to regenerate a fresh polish. Pipes (`dictum | claude`, `echo … | dictum`) and
+ * `--auto` skip this entirely and emit the polished text directly — cli.ts
+ * decides and only wires a chooser in when appropriate.
+ *
+ * Imported only by cli.ts (assembly layer). Depends only on core/types.ts.
+ */
+
+import { createInterface } from "node:readline/promises"
+import type { ChoiceContext, Chooser } from "../core/types.ts"
+
+export type ChoiceAction = "original" | "polished" | "regenerate" | "unknown"
+
+/** Question shown when asking for a choice. */
+export const CHOICE_PROMPT = "Keep [p]olished (default), [o]riginal, or [r]egenerate? "
+
+/** Hint repeated after an unrecognized key. */
+export const CHOICE_HINT = "Please answer o / p / r (or Enter for polished)."
+
+/** Map a raw keypress / line to a choice action. Pure, for testing. */
+export function parseChoiceKey(input: string): ChoiceAction {
+  const k = input.trim().toLowerCase()
+  if (k === "" || k === "p" || k === "polished") return "polished"
+  if (k === "o" || k === "original") return "original"
+  if (k === "r" || k === "regenerate") return "regenerate"
+  return "unknown"
+}
+
+/** Render the side-by-side preview block (original + polished). Pure, for testing. */
+export function formatPreview(original: string, polished: string, note?: string): string {
+  const lines = ["", "── your words ──", original, "", "── polished ──", polished]
+  if (note) lines.push("", note)
+  lines.push("")
+  return lines.join("\n")
+}
+
+/** Injectable I/O so the interactive loop can be unit-tested without a real TTY. */
+export type ChooserIo = {
+  /** Display a line/block (goes to stderr in production, keeping stdout clean). */
+  write: (s: string) => void
+  /** Prompt and read one line; resolves to null on EOF (Ctrl-D). */
+  readLine: (prompt: string) => Promise<string | null>
+}
+
+/**
+ * Drive the choose loop over an injectable I/O. Returns the text to emit.
+ * EOF (stdin closed) accepts the current polished default.
+ */
+export async function interactiveChoose(ctx: ChoiceContext, io: ChooserIo): Promise<string> {
+  let polished = ctx.polished
+  io.write(formatPreview(ctx.original, polished, ctx.annotate?.(polished)))
+
+  while (true) {
+    const line = await io.readLine(CHOICE_PROMPT)
+    if (line === null) return polished // EOF → accept the polished default
+    const action = parseChoiceKey(line)
+    if (action === "original") return ctx.original
+    if (action === "polished") return polished
+    if (action === "regenerate") {
+      io.write("\nRegenerating…\n")
+      polished = await ctx.regenerate()
+      io.write(formatPreview(ctx.original, polished, ctx.annotate?.(polished)))
+      continue
+    }
+    io.write(`${CHOICE_HINT}\n`)
+  }
+}
+
+/**
+ * Build a Chooser bound to the real terminal: reads keys from stdin, renders the
+ * prompt on stderr so stdout stays clean for the result.
+ */
+export function terminalChooser(): Chooser {
+  return (ctx) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr })
+    const io: ChooserIo = {
+      write: (s) => {
+        process.stderr.write(s)
+      },
+      readLine: async (prompt) => {
+        try {
+          return await rl.question(prompt)
+        } catch {
+          return null // stream closed / aborted
+        }
+      },
+    }
+    return interactiveChoose(ctx, io).finally(() => rl.close())
+  }
+}

package/src/ui/keys.ts

@@ -0,0 +1,110 @@
+/**
+ * ui/keys.ts — produce a "stop recording" AbortSignal from the keyboard.
+ *
+ * Modes:
+ *   - enter : press Enter to stop (reliable everywhere; the default).
+ *   - vad   : recorder auto-stops on silence; Enter still stops early.
+ *   - ptt   : hold Space to talk, release to stop (raw stdin; release is
+ *             inferred from the auto-repeat gap — terminal-dependent, so it's
+ *             best-effort and verified manually).
+ *
+ * Ctrl-C always stops. This module is imported only by cli.ts (assembly layer);
+ * the recorder never depends on it — it just receives the AbortSignal.
+ */
+
+export type StopMode = "enter" | "vad" | "ptt"
+
+export type StopController = {
+  signal: AbortSignal
+  dispose: () => void
+}
+
+/** Release is inferred when no Space byte arrives within this window (ms). */
+const PTT_RELEASE_MS = 400
+
+/** The instruction line shown while recording. Pure, for display + tests. */
+export function stopHint(mode: StopMode): string {
+  switch (mode) {
+    case "enter":
+      return "press Enter to stop"
+    case "vad":
+      return "speak — auto-stops on silence (Enter to stop now)"
+    case "ptt":
+      return "hold Space to talk, release to stop"
+  }
+}
+
+export type StopControllerOptions = {
+  /** Whole-operation cancel (SIGINT); aborting it also stops recording. */
+  parent?: AbortSignal
+  /** Where to print the instruction hint (default stderr, keeps stdout clean). */
+  hintStream?: { write(s: string): unknown }
+}
+
+/**
+ * Wire stdin to an AbortController for the given stop mode. Returns the signal
+ * plus a dispose() that detaches listeners and restores the terminal. Safe to
+ * call in a non-interactive environment (it simply won't receive key events).
+ */
+export function createStopController(
+  mode: StopMode,
+  opts: StopControllerOptions = {},
+): StopController {
+  const controller = new AbortController()
+  const stdin = process.stdin
+  const hint = opts.hintStream ?? process.stderr
+  let releaseTimer: ReturnType<typeof setTimeout> | undefined
+
+  const abort = () => {
+    if (!controller.signal.aborted) controller.abort()
+  }
+
+  if (opts.parent) {
+    if (opts.parent.aborted) abort()
+    else opts.parent.addEventListener("abort", abort, { once: true })
+  }
+
+  const onData = (chunk: Buffer) => {
+    if (chunk.includes(0x03)) {
+      abort() // Ctrl-C
+      return
+    }
+    if (mode === "ptt") {
+      if (chunk.includes(0x20)) {
+        if (releaseTimer) clearTimeout(releaseTimer)
+        releaseTimer = setTimeout(abort, PTT_RELEASE_MS)
+      }
+      return
+    }
+    // enter / vad: stop on Enter (LF or CR)
+    if (chunk.includes(0x0a) || chunk.includes(0x0d)) abort()
+  }
+
+  let attached = false
+  try {
+    if (stdin.isTTY && mode === "ptt") stdin.setRawMode?.(true)
+    stdin.resume()
+    stdin.on("data", onData)
+    attached = true
+  } catch {
+    // stdin unavailable (non-interactive) — recorder still stops via VAD/cap.
+  }
+
+  const dispose = () => {
+    if (releaseTimer) clearTimeout(releaseTimer)
+    if (attached) {
+      stdin.off("data", onData)
+      try {
+        if (stdin.isTTY) stdin.setRawMode?.(false)
+      } catch {
+        // ignore
+      }
+      stdin.pause()
+    }
+    if (opts.parent) opts.parent.removeEventListener("abort", abort)
+  }
+  controller.signal.addEventListener("abort", dispose, { once: true })
+
+  hint.write(`${stopHint(mode)}\n`)
+  return { signal: controller.signal, dispose }
+}