dictum-cli 0.1.0

package/src/polisher/layered.ts

@@ -0,0 +1,43 @@
+/**
+ * polisher/layered.ts — offline and two-layer polishers over rules.ts.
+ *
+ * RulesPolisher: deterministic cleanup only — works with no LLM, no network,
+ * no API key. The fully-offline mode.
+ *
+ * LayeredPolisher: the two-layer strategy (borrowed from the wider prompt-
+ * optimizer ecosystem): a deterministic analyzer decides whether the LLM is
+ * needed at all. Drafts that already score at or above the threshold take the
+ * fast offline path (normalize only); everything else goes to the wrapped LLM
+ * polisher. Saves latency, tokens and privacy on already-good prompts.
+ *
+ * Imports only core/types.ts and sibling polisher files.
+ */
+
+import type { Polisher, Template } from "../core/types.ts"
+import { analyzePrompt, normalizeText } from "./rules.ts"
+
+/** Offline polisher: deterministic normalization, no LLM involved. */
+export class RulesPolisher implements Polisher {
+  async polish(text: string, _template: Template): Promise<string> {
+    return normalizeText(text)
+  }
+}
+
+export type LayeredOptions = {
+  /** Skip the LLM when the draft already scores at or above this (0–100). */
+  scoreThreshold: number
+}
+
+/** Two-layer polisher: rule-based gate in front of a wrapped LLM polisher. */
+export class LayeredPolisher implements Polisher {
+  constructor(
+    private readonly inner: Polisher,
+    private readonly opts: LayeredOptions,
+  ) {}
+
+  async polish(text: string, template: Template): Promise<string> {
+    const analysis = analyzePrompt(text)
+    if (analysis.score >= this.opts.scoreThreshold) return normalizeText(text)
+    return this.inner.polish(text, template)
+  }
+}

package/src/polisher/openai_compat.ts

@@ -0,0 +1,76 @@
+/**
+ * polisher/openai_compat.ts — Polisher backed by an OpenAI-compatible
+ * Chat Completions API (OpenAI, Groq, local LLM servers, OpenRouter, …).
+ *
+ *   POST {base}/v1/chat/completions
+ *   headers: authorization: Bearer <key>, content-type
+ *   body: { model, messages: [{role:"system", instruction}, {role:"user", text}] }
+ *   response: { choices: [{message: {content}}] }
+ */
+
+import type { Polisher, Template } from "../core/types.ts"
+
+export type OpenAiCompatPolisherOptions = {
+  apiKey: string
+  model: string
+  baseUrl: string
+  /** Request timeout in milliseconds. */
+  timeoutMs?: number
+}
+
+type ChatResponse = {
+  choices?: Array<{ message?: { content?: string } }>
+  error?: { message?: string }
+}
+
+export class OpenAiCompatPolisher implements Polisher {
+  private readonly apiKey: string
+  private readonly model: string
+  private readonly baseUrl: string
+  private readonly timeoutMs: number
+
+  constructor(opts: OpenAiCompatPolisherOptions) {
+    this.apiKey = opts.apiKey
+    this.model = opts.model
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "")
+    this.timeoutMs = opts.timeoutMs ?? 60000
+  }
+
+  async polish(text: string, template: Template): Promise<string> {
+    if (!this.apiKey) {
+      throw new Error("OpenAI-compatible polisher needs an API key — set OPENAI_API_KEY")
+    }
+
+    let res: Response
+    try {
+      res = await fetch(`${this.baseUrl}/v1/chat/completions`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${this.apiKey}`,
+        },
+        body: JSON.stringify({
+          model: this.model,
+          messages: [
+            { role: "system", content: template.instruction },
+            { role: "user", content: text },
+          ],
+        }),
+        signal: AbortSignal.timeout(this.timeoutMs),
+      })
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err)
+      throw new Error(`OpenAI-compatible request failed: ${reason}`)
+    }
+
+    const body = (await res.json().catch(() => ({}))) as ChatResponse
+    if (!res.ok) {
+      const detail = body.error?.message ?? ""
+      throw new Error(`OpenAI-compatible API returned ${res.status}${detail ? `: ${detail}` : ""}`)
+    }
+
+    const out = body.choices?.[0]?.message?.content?.trim() ?? ""
+    if (!out) throw new Error("OpenAI-compatible API returned an empty response")
+    return out
+  }
+}

package/src/polisher/rules.ts

@@ -0,0 +1,332 @@
+/**
+ * polisher/rules.ts — deterministic prompt analysis and normalization.
+ *
+ * The offline layer of the polisher: pure functions, no network, no LLM.
+ * `analyzePrompt` scores a draft 0–100 across five dimensions and lists its
+ * weak spots; `normalizeText` applies conservative mechanical cleanup (filler
+ * interjections, duplicated words, whitespace). Used by RulesPolisher and
+ * LayeredPolisher (layered.ts) and by assembly layers (CLI --format json,
+ * MCP analyze_prompt) to attach scores and rationale to results.
+ *
+ * Heuristics are intentionally thin and transparent: the strength of Dictum's
+ * polishing stays in the LLM layer; this layer provides a fast, private,
+ * dependency-free baseline and a stable score. Imports no project modules.
+ *
+ * NOTE on regexes: JS `\b` is ASCII-only and never matches inside Cyrillic
+ * text, so word detection uses Unicode token scanning and letter-class
+ * lookarounds instead.
+ */
+
+export type PromptDimension = "clarity" | "specificity" | "structure" | "actionability" | "context"
+
+export type PromptAnalysis = {
+  /** Total score normalized to 0–100 (sum of five 0–10 dimensions × 2). */
+  score: number
+  /** Per-dimension scores, each 0–10. */
+  dimensions: Record<PromptDimension, number>
+  /** Human-readable weak spots (dimensions scoring ≤ 6), worst first. */
+  issues: string[]
+}
+
+const clamp = (n: number, lo: number, hi: number): number => Math.min(hi, Math.max(lo, n))
+
+/** Unicode-aware word tokens (letters/digits plus path-ish glue chars). */
+const WORD_RE = /[\p{L}\p{N}][\p{L}\p{N}_./\\-]*/gu
+
+function tokenize(text: string): string[] {
+  return text.toLowerCase().match(WORD_RE) ?? []
+}
+
+/** Count non-overlapping matches of `re` in `text` (a fresh lastIndex each call). */
+function countMatches(text: string, re: RegExp): number {
+  return (text.match(re) ?? []).length
+}
+
+// ── Dictation-noise vocabulary (ru + en) ────────────────────────────────────
+
+/** Single-token fillers, matched against lowercased tokens. */
+const FILLER_TOKENS = new Set([
+  // ru
+  "эм",
+  "эмм",
+  "ээ",
+  "эээ",
+  "мм",
+  "ммм",
+  "ну",
+  "вот",
+  "типа",
+  "короче",
+  "значит",
+  // en
+  "um",
+  "umm",
+  "uh",
+  "uhh",
+  "erm",
+  "err",
+  "hmm",
+  "basically",
+  "kinda",
+  "sorta",
+])
+
+/** Multi-word filler phrases, counted on the lowercased text. */
+const FILLER_PHRASES = /(?:как бы|в общем|это самое|то есть как его|you know|i mean|sort of)/gu
+
+/** Self-correction / false-start markers. */
+const FALSE_STARTS =
+  /(?:вернее|точнее|нет,? стой|не так|отмени это|scratch that|actually,? no|wait,? no)/giu
+
+/** Immediately repeated word (case-insensitive), e.g. "это это надо". */
+const DUP_WORD = /(?<![\p{L}\p{N}])([\p{L}\p{N}]+)(?:\s+\1)+(?![\p{L}\p{N}])/giu
+
+// ── Concreteness signals ────────────────────────────────────────────────────
+
+const FILE_PATH = /[\w./\\-]+\.(?:ts|tsx|js|jsx|py|rs|go|md|json|toml|yaml|yml|css|html|wav|sh)\b/gi
+const NUMBER = /(?<![\p{L}])\d+(?:[.,]\d+)?(?![\p{L}])/gu
+const CODE_IDENT = /(?:[a-z0-9]+_[a-z0-9_]+|[a-z]+[A-Z][A-Za-z]*|--[a-z][\w-]+)/g
+const QUOTED = /(?:"[^"\n]{2,}"|'[^'\n]{2,}'|`[^`\n]+`|«[^»\n]{2,}»)/g
+const URL = /https?:\/\/\S+/gi
+
+const VAGUE_PHRASES =
+  /(?:это самое|та штука|эта штука|эта фигня|что-то такое|как-то так|что-нибудь такое|that thing|this thing|some stuff|stuff like that|something like that)/giu
+
+// ── Task-shape signals ──────────────────────────────────────────────────────
+
+/** Imperative task verbs (ru stems + en), lowercased token prefixes. */
+const TASK_VERB_PREFIXES = [
+  // ru (stems cover imperative + infinitive forms)
+  "сдела",
+  "добав",
+  "исправ",
+  "поправ",
+  "почин",
+  "напиш",
+  "написа",
+  "созда",
+  "провер",
+  "обнов",
+  "удал",
+  "убер",
+  "переимен",
+  "рефактор",
+  "зарефактор",
+  "настро",
+  "запуст",
+  "реализ",
+  "внедр",
+  "поменя",
+  "измен",
+  // ru — analytical / explanatory (asking to explain or analyze is a task too)
+  "разбер",
+  "покаж",
+  "проанализ",
+  "опиш",
+  "объясн",
+  "расскаж",
+  "оцен",
+  "сравн",
+  "уточн",
+  "сформулир",
+  "исслед",
+  "изуч",
+  "прораб",
+  // en
+  "add",
+  "fix",
+  "write",
+  "creat",
+  "implement",
+  "updat",
+  "remov",
+  "delet",
+  "renam",
+  "refactor",
+  "make",
+  "check",
+  "build",
+  "run",
+  "set",
+  "chang",
+  "test",
+  // en — analytical / explanatory
+  "explain",
+  "describ",
+  "analyz",
+  "show",
+  "summar",
+  "compar",
+  "evaluat",
+  "clarif",
+]
+
+const DELIVERABLE_STEMS = [
+  // ru
+  "тест",
+  "функци",
+  "команд",
+  "файл",
+  "баг",
+  "скрипт",
+  "кнопк",
+  "эндпоинт",
+  "документ",
+  "коммит",
+  "релиз",
+  "модул",
+  "шаблон",
+  "конфиг",
+  // en
+  "test",
+  "function",
+  "command",
+  "file",
+  "bug",
+  "script",
+  "button",
+  "endpoint",
+  "doc",
+  "commit",
+  "release",
+  "module",
+  "template",
+  "config",
+  "feature",
+  "page",
+  "api",
+]
+
+const OUTPUT_MARKERS =
+  /(?:верни|выведи|выдай|в виде|формат|таблиц|списком|return|output|print|as a list|as json|as markdown)/giu
+
+const CONSTRAINT_MARKERS =
+  /(?:чтобы|должн|если|кроме|не лома|не трога|не меня|используй|без изменения|only|must|should|unless|except|don'?t touch|keep the|while keeping|use )/giu
+
+const ENV_MARKERS =
+  /(?:bun|node|python|typescript|javascript|react|linux|macos|windows|docker|порт|port|верси|version|v\d+)/giu
+
+const ACCEPTANCE_MARKERS =
+  /(?:критери|приемк|приёмк|провер|зелён|done when|acceptance|verify|passes|should pass|works when)/giu
+
+// ── Scoring ─────────────────────────────────────────────────────────────────
+
+function scoreClarity(text: string, tokens: string[]): number {
+  const fillers =
+    tokens.filter((t) => FILLER_TOKENS.has(t)).length +
+    countMatches(text.toLowerCase(), FILLER_PHRASES)
+  const falseStarts = countMatches(text, FALSE_STARTS)
+  const dups = countMatches(text, DUP_WORD)
+  return clamp(Math.round(10 - (fillers * 1.5 + falseStarts * 2 + dups * 2)), 0, 10)
+}
+
+function scoreSpecificity(text: string): number {
+  const concrete =
+    countMatches(text, FILE_PATH) +
+    countMatches(text, NUMBER) +
+    countMatches(text, CODE_IDENT) +
+    countMatches(text, QUOTED) +
+    countMatches(text, URL)
+  const vague = countMatches(text, VAGUE_PHRASES)
+  return clamp(4 + Math.min(6, concrete) - vague * 2, 0, 10)
+}
+
+function startsWithTaskVerb(tokens: string[]): boolean {
+  return tokens.slice(0, 3).some((t) => TASK_VERB_PREFIXES.some((stem) => t.startsWith(stem)))
+}
+
+function scoreStructure(text: string, tokens: string[]): number {
+  let score = 0
+  if (startsWithTaskVerb(tokens)) score += 3
+  if (/^\s*(?:[-*•]|\d+[.)])\s/m.test(text)) score += 2
+  if (text.length > 200 && text.includes("\n")) score += 1
+  const sentences = text
+    .split(/[.!?\n]+/)
+    .map((s) => tokenize(s).length)
+    .filter((n) => n > 0)
+  const avg = sentences.length ? sentences.reduce((a, b) => a + b, 0) / sentences.length : 0
+  if (avg > 0 && avg <= 25) score += 2
+  if (sentences.some((n) => n > 60)) score -= 2
+  if (tokens.length >= 3 && tokens.length <= 400) score += 2
+  return clamp(score, 0, 10)
+}
+
+function scoreActionability(text: string, tokens: string[]): number {
+  let score = 0
+  if (tokens.some((t) => TASK_VERB_PREFIXES.some((stem) => t.startsWith(stem)))) score += 4
+  if (tokens.some((t) => DELIVERABLE_STEMS.some((stem) => t.startsWith(stem)))) score += 3
+  if (countMatches(text, OUTPUT_MARKERS) > 0) score += 3
+  return clamp(score, 0, 10)
+}
+
+function scoreContext(text: string): number {
+  let score = 0
+  score += Math.min(6, countMatches(text, CONSTRAINT_MARKERS) * 2)
+  if (countMatches(text, ENV_MARKERS) > 0) score += 2
+  if (countMatches(text, ACCEPTANCE_MARKERS) > 0) score += 2
+  return clamp(score, 0, 10)
+}
+
+const ISSUE_MESSAGES: Record<PromptDimension, string> = {
+  clarity: "dictation noise survives — filler words, false starts or repeated words",
+  specificity: "few concrete details (files, names, numbers) or vague references",
+  structure: "no task-first structure — lead with an imperative, bullet multiple requirements",
+  actionability: "the task verb or the expected deliverable is unclear",
+  context: "no constraints or acceptance criteria to verify the result against",
+}
+
+/**
+ * Score a prompt draft 0–100 across five equally-weighted dimensions.
+ * Deterministic: the same text always produces the same analysis.
+ */
+export function analyzePrompt(text: string): PromptAnalysis {
+  const tokens = tokenize(text)
+  if (tokens.length === 0) {
+    return {
+      score: 0,
+      dimensions: { clarity: 0, specificity: 0, structure: 0, actionability: 0, context: 0 },
+      issues: ["empty prompt"],
+    }
+  }
+  const dimensions: Record<PromptDimension, number> = {
+    clarity: scoreClarity(text, tokens),
+    specificity: scoreSpecificity(text),
+    structure: scoreStructure(text, tokens),
+    actionability: scoreActionability(text, tokens),
+    context: scoreContext(text),
+  }
+  const issues = (Object.entries(dimensions) as [PromptDimension, number][])
+    .filter(([, v]) => v <= 6)
+    .sort((a, b) => a[1] - b[1])
+    .map(([dim, v]) => `${ISSUE_MESSAGES[dim]} (${dim} ${v}/10)`)
+  const total = Object.values(dimensions).reduce((a, b) => a + b, 0) * 2
+  return { score: total, dimensions, issues }
+}
+
+// ── Normalization ───────────────────────────────────────────────────────────
+
+/**
+ * Unambiguous filler interjections only (эм / ммм / um / uh …) with an optional
+ * trailing comma. Meaning-bearing words like «ну» or "like" are deliberately
+ * left alone — removal is conservative; real rewriting is the LLM's job.
+ */
+const STRIP_FILLERS =
+  /(?<![\p{L}\p{N}])(?:э+м+|э{2,}|м{2,}|у+м+|um+|uh+|erm|err|h+m+)(?![\p{L}\p{N}]),?\s*/giu
+
+/**
+ * Conservative mechanical cleanup of a dictated draft: strip unambiguous filler
+ * interjections, collapse immediately-repeated words and runs of whitespace,
+ * capitalize the first letter. Never rewrites content — deterministic and safe
+ * to apply to any text.
+ */
+export function normalizeText(text: string): string {
+  let out = text
+  out = out.replace(STRIP_FILLERS, "")
+  out = out.replace(DUP_WORD, "$1")
+  out = out.replace(/[^\S\n]+/g, " ") // collapse spaces/tabs, keep newlines
+  out = out.replace(/\n{3,}/g, "\n\n")
+  out = out.replace(/ ([,.!?;:])/g, "$1") // no space before punctuation
+  out = out.trim()
+  if (out.length > 0) out = out[0]!.toUpperCase() + out.slice(1)
+  return out
+}

package/src/polisher/templates/agent-prompt.md

@@ -0,0 +1,18 @@
+---
+description: Turn a rough spoken thought into a clear, structured prompt for an AI coding agent
+language: auto
+---
+You are a prompt editor. The user dictated a rough thought out loud and it was transcribed by speech-to-text, so it may contain filler words, false starts, and transcription noise.
+
+Rewrite it into a single clear, well-structured prompt suitable for an AI coding agent:
+
+1. Lead with the task: one short imperative sentence stating what to do.
+2. Preserve the user's intent and every concrete detail — names, numbers, file paths, identifiers, error messages — verbatim. Never invent details that were not said.
+3. If the thought contains several requirements or constraints, group them into a short bulleted list; otherwise keep it to one or two sentences.
+4. If the expected outcome or output format is clearly implied (a fixed bug, a passing test, a new command, a document), state it explicitly in one line.
+5. Remove filler, repetition, and self-corrections; resolve vague references ("it", "that thing") to the concrete referent when the transcript makes it unambiguous.
+6. If one critical detail is clearly missing and cannot be inferred, append a single line starting with "Open question:" instead of guessing.
+
+Write the result in the same language as the transcript. Output ONLY the rewritten prompt — no preamble, no explanations, no surrounding quotes or code fences.
+
+Transcript:

package/src/polisher/templates/commit.md

@@ -0,0 +1,13 @@
+---
+description: Turn a spoken description of code changes into a Conventional Commits message
+language: auto
+---
+You are a commit-message writer. The user dictated a rough description of the changes they made, transcribed by speech-to-text, so it may contain filler and transcription noise.
+
+Write a Conventional Commits message:
+- A subject line `type(scope): summary` — type is one of feat, fix, docs, style, refactor, perf, test, build, ci, chore; scope is optional; summary is imperative, lowercase, no trailing period, ≤ 72 chars.
+- Optionally, a blank line then a short body explaining what and why, as bullet points if there are several distinct changes.
+
+Write in the same language as the transcript, but keep the Conventional Commits type prefix in English. Output ONLY the commit message — no preamble, no surrounding quotes or code fences.
+
+Transcript:

package/src/polisher/templates/decompose.md

@@ -0,0 +1,20 @@
+---
+description: Break a rough task description into an ordered list of atomic, dependency-tracked subtasks
+language: auto
+---
+You are a task decomposer. The user dictated or typed a rough description of a task; dictated text may contain filler words, false starts, and transcription noise.
+
+Break it into an ordered list of atomic, independently-actionable subtasks for an AI coding agent. Preserve the user's intent and every concrete detail (names, numbers, file paths, identifiers) verbatim; never invent subtasks, files, or requirements that were not stated or clearly implied. Order subtasks so that each one only depends on subtasks that come before it. Use this Markdown structure:
+
+## Subtasks
+A numbered list. For each subtask give:
+- **Title**: a short imperative sentence — what to do.
+- **Touches**: files or areas it is expected to affect, inferred from the transcript; if none can be inferred, write "unclear — infer from codebase".
+- **Depends on**: the numbers of earlier subtasks it requires, or "none".
+
+## Open questions
+Genuinely ambiguous points that block correct decomposition — how to split the work, unclear ordering, or missing scope — each on its own line starting with "Open question:". Omit this section if there are none.
+
+Write in the same language as the input. Output ONLY the decomposition in Markdown — no preamble, no explanations, no surrounding code fences.
+
+Transcript:

package/src/polisher/templates/note.md

@@ -0,0 +1,11 @@
+---
+description: Turn a rough spoken thought into a clean, structured Markdown note
+language: auto
+---
+You are a note editor. The user dictated a rough thought out loud, transcribed by speech-to-text, so it may contain filler words, false starts, and transcription noise.
+
+Rewrite it into a clean, well-structured Markdown note. Preserve all concrete details. Remove filler and repetition. Use a short title heading and bullet points or short paragraphs as appropriate; keep it faithful to what was said — do not invent content.
+
+Write in the same language as the transcript. Output ONLY the note in Markdown — no preamble, no explanations, no surrounding code fences.
+
+Transcript:

package/src/polisher/templates/spec.md

@@ -0,0 +1,29 @@
+---
+description: Expand a rough thought into a compact task spec with acceptance criteria
+language: auto
+---
+You are a spec writer. The user dictated or typed a rough description of a task; dictated text may contain filler words, false starts, and transcription noise.
+
+Expand it into a compact, actionable spec for an AI coding agent. Preserve the user's intent and every concrete detail (names, numbers, file paths, identifiers) verbatim; never invent requirements that were not stated or clearly implied. Use this Markdown structure, omitting any section that would be empty:
+
+## Task
+One or two imperative sentences: what to build or change.
+
+## Context
+Known constraints and relevant facts taken from the user's words (stack, files, environment).
+
+## Requirements
+- Bulleted, testable requirements — each a single verifiable statement.
+
+## Acceptance criteria
+- How to verify the task is done: observable checks, commands to run, expected outputs.
+
+## Out of scope
+What the user explicitly excluded, if anything.
+
+## Open questions
+Critical unknowns worth resolving before or while working, if any.
+
+Write in the same language as the input. Output ONLY the spec in Markdown — no preamble, no explanations, no surrounding code fences.
+
+Transcript: