@tychenjiajun/pi-voice 0.0.0-stage → 0.2.0

package/src/settings.ts

@@ -0,0 +1,273 @@
+import { readFile, rename, unlink, writeFile } from "node:fs/promises";
+import {
+  languageIdentity,
+  getCatalogModel,
+  resolveModelLanguage,
+  type CatalogModel,
+} from "./catalog.js";
+import { DEFAULT_SHORTCUT, normalizeShortcut } from "./shortcut-core.js";
+import { legacySettingsPath, settingsPath } from "./settings-path.js";
+
+const SETTINGS_VERSION = 1;
+
+export type MicrophoneSetting =
+  | { type: "system-default" }
+  | { type: "device"; name: string; occurrence: number };
+
+export const DEFAULT_MICROPHONE: MicrophoneSetting = { type: "system-default" };
+
+export type ChineseOutput = "simplified" | "traditional-taiwan" | "traditional-hong-kong";
+
+/**
+ * Where recordings are transcribed. `transcribe-cpp` runs a local catalog
+ * model; `openai-asr` uploads to any OpenAI-compatible chat-completions ASR
+ * endpoint via the `input_audio` content block. The local catalog model stays
+ * configured in both cases and acts as the fallback when the remote call fails.
+ */
+export type BackendSettings =
+  | { type: "transcribe-cpp" }
+  | { type: "openai-asr"; baseUrl: string; model: string; apiKeyEnv: string };
+
+function defaultChineseOutput(): ChineseOutput {
+  const locale = Intl.DateTimeFormat().resolvedOptions().locale;
+  const subtags = locale.toLowerCase().split("-");
+  if (subtags.includes("hk") || subtags.includes("mo")) return "traditional-hong-kong";
+  if (subtags.includes("tw") || subtags.includes("hant")) return "traditional-taiwan";
+  return "simplified";
+}
+
+/** "auto" asks a capable model to detect the language; otherwise this is a language code. */
+export type TranscriptionLanguage = string;
+
+export type TranscribeSettings = {
+  version: 1;
+  backend: BackendSettings;
+  shortcut: string;
+  preferredLanguages: string[];
+  transcriptionLanguage: TranscriptionLanguage;
+  chineseOutput: ChineseOutput;
+  microphone: MicrophoneSetting;
+  model: {
+    source: "catalog";
+    id: string;
+    path: string;
+  };
+};
+
+type SettingsReadResult = {
+  settings?: TranscribeSettings;
+  warning?: string;
+};
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeLanguages(value: unknown): string[] | undefined {
+  if (!Array.isArray(value) || !value.every((language) => typeof language === "string")) {
+    return undefined;
+  }
+  const languages = [...new Set(value.map(languageIdentity).filter(Boolean))];
+  return languages.length > 0 ? languages : undefined;
+}
+
+function validateChineseOutput(value: unknown): ChineseOutput {
+  return value === "simplified" ||
+    value === "traditional-taiwan" ||
+    value === "traditional-hong-kong"
+    ? value
+    : defaultChineseOutput();
+}
+
+function validateMicrophone(value: unknown): MicrophoneSetting | undefined {
+  if (!isObject(value)) return undefined;
+  if (value.type === "system-default") return { type: "system-default" };
+  if (
+    value.type !== "device" ||
+    typeof value.name !== "string" ||
+    !value.name.trim() ||
+    !Number.isInteger(value.occurrence) ||
+    (value.occurrence as number) < 0
+  ) {
+    return undefined;
+  }
+  return { type: "device", name: value.name, occurrence: value.occurrence as number };
+}
+
+function defaultTranscriptionLanguage(
+  model: CatalogModel,
+  preferredLanguages: readonly string[] = [],
+): TranscriptionLanguage {
+  if (model.capabilities.languageDetection) return "auto";
+  for (const language of preferredLanguages) {
+    const code = resolveModelLanguage(model, language);
+    if (code) return code;
+  }
+  return model.languages[0] ?? "en";
+}
+
+/** Keep an exact model language when possible; otherwise choose a safe default. */
+export function transcriptionLanguageForModel(
+  value: unknown,
+  model: CatalogModel,
+  preferredLanguages: readonly string[] = [],
+): TranscriptionLanguage {
+  if (typeof value === "string") {
+    if (value === "auto" && model.capabilities.languageDetection) return value;
+    if (value !== "auto") {
+      const code = resolveModelLanguage(model, value);
+      if (code) return code;
+    }
+  }
+  return defaultTranscriptionLanguage(model, preferredLanguages);
+}
+
+function validateBackend(value: unknown): BackendSettings | undefined {
+  if (!isObject(value)) return undefined;
+  if (value.type === "transcribe-cpp") return { type: "transcribe-cpp" };
+  if (value.type === "openai-asr") {
+    // Deliberately lenient here: settings are validated on every read, and a
+    // slightly odd base URL should surface as a request error, not as "invalid
+    // settings" that silently drops the whole configuration.
+    if (typeof value.baseUrl !== "string" || !value.baseUrl.trim()) return undefined;
+    if (typeof value.model !== "string" || !value.model.trim()) return undefined;
+    if (
+      typeof value.apiKeyEnv !== "string" ||
+      !/^[A-Za-z_][A-Za-z0-9_]*$/.test(value.apiKeyEnv.trim())
+    ) {
+      return undefined;
+    }
+    return {
+      type: "openai-asr",
+      baseUrl: value.baseUrl.trim(),
+      model: value.model.trim(),
+      apiKeyEnv: value.apiKeyEnv.trim(),
+    };
+  }
+  return undefined;
+}
+
+function validateSettings(value: unknown): TranscribeSettings | undefined {
+  if (!isObject(value) || value.version !== SETTINGS_VERSION) return undefined;
+  const backend = validateBackend(value.backend);
+  if (!backend) return undefined;
+  const shortcut =
+    typeof value.shortcut === "string" ? normalizeShortcut(value.shortcut) : undefined;
+  if (!shortcut) return undefined;
+  if (!isObject(value.model) || value.model.source !== "catalog") return undefined;
+  if (typeof value.model.id !== "string") return undefined;
+  const model = getCatalogModel(value.model.id);
+  if (!model) return undefined;
+  if (typeof value.model.path !== "string" || value.model.path.length === 0) return undefined;
+
+  const preferredLanguages = normalizeLanguages(value.preferredLanguages);
+  const microphone = validateMicrophone(value.microphone);
+  if (!preferredLanguages || !microphone) return undefined;
+
+  return {
+    version: SETTINGS_VERSION,
+    backend,
+    shortcut,
+    preferredLanguages,
+    transcriptionLanguage: transcriptionLanguageForModel(
+      value.transcriptionLanguage,
+      model,
+      preferredLanguages,
+    ),
+    chineseOutput: validateChineseOutput(value.chineseOutput),
+    microphone,
+    model: {
+      source: "catalog",
+      id: value.model.id,
+      path: value.model.path,
+    },
+  };
+}
+
+async function readSettingsFile(path: string): Promise<SettingsReadResult> {
+  try {
+    const parsed: unknown = JSON.parse(await readFile(path, "utf8"));
+    const settings = validateSettings(parsed);
+    return settings
+      ? { settings }
+      : { warning: `Invalid settings in ${path}; configuration is required.` };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    return {
+      warning: `Could not read ${path}: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+export async function readSettings(): Promise<SettingsReadResult> {
+  const currentPath = settingsPath();
+  const current = await readSettingsFile(currentPath);
+  if (current.settings || current.warning) return current;
+
+  const legacyPath = legacySettingsPath();
+  const legacy = await readSettingsFile(legacyPath);
+  if (!legacy.settings) return legacy;
+
+  try {
+    await writeSettings(legacy.settings);
+    await unlink(legacyPath).catch((error: NodeJS.ErrnoException) => {
+      if (error.code !== "ENOENT") throw error;
+    });
+    return { settings: legacy.settings };
+  } catch (error) {
+    return {
+      settings: legacy.settings,
+      warning: `Loaded legacy settings from ${legacyPath}, but could not migrate them to ${currentPath}: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+export async function writeSettings(settings: TranscribeSettings): Promise<void> {
+  const path = settingsPath();
+  const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+  const content = `${JSON.stringify(settings, null, 2)}\n`;
+
+  try {
+    await writeFile(temporaryPath, content, { encoding: "utf8", mode: 0o600 });
+    await rename(temporaryPath, path);
+  } catch (error) {
+    await unlink(temporaryPath).catch(() => undefined);
+    throw error;
+  }
+}
+
+type ModelSettingsOptions = {
+  shortcut?: string;
+  preferredLanguages?: readonly string[];
+  transcriptionLanguage?: TranscriptionLanguage;
+  chineseOutput?: ChineseOutput;
+  microphone?: MicrophoneSetting;
+  /** Preserved across model re-selection; defaults to the local backend. */
+  backend?: BackendSettings;
+};
+
+export function settingsForModel(
+  modelId: string,
+  modelPath: string,
+  options: ModelSettingsOptions = {},
+): TranscribeSettings {
+  const model = getCatalogModel(modelId);
+  if (!model) throw new Error(`Unknown catalog model: ${modelId}`);
+  const preferredLanguages = [
+    ...new Set((options.preferredLanguages ?? ["en"]).map(languageIdentity)),
+  ];
+  return {
+    version: SETTINGS_VERSION,
+    backend: options.backend ?? { type: "transcribe-cpp" },
+    shortcut: options.shortcut ?? DEFAULT_SHORTCUT,
+    preferredLanguages,
+    transcriptionLanguage: transcriptionLanguageForModel(
+      options.transcriptionLanguage,
+      model,
+      preferredLanguages,
+    ),
+    chineseOutput: options.chineseOutput ?? defaultChineseOutput(),
+    microphone: { ...(options.microphone ?? DEFAULT_MICROPHONE) },
+    model: { source: "catalog", id: modelId, path: modelPath },
+  };
+}

package/src/shortcut-core.ts

@@ -0,0 +1,85 @@
+export const DEFAULT_SHORTCUT = "ctrl+alt+z";
+
+/** Widget slot shared by the startup status and the recording meter. */
+export const STATUS_WIDGET_KEY = "pi-voice-meter";
+
+const MODIFIER_ORDER = ["ctrl", "shift", "alt", "super"] as const;
+const SPECIAL_KEYS = new Set([
+  "escape",
+  "enter",
+  "tab",
+  "space",
+  "backspace",
+  "delete",
+  "insert",
+  "home",
+  "end",
+  "pageup",
+  "pagedown",
+  "up",
+  "down",
+  "left",
+  "right",
+]);
+const SYMBOL_KEYS = new Set(["`", "-", "=", "[", "]", "\\", ";", "'", ",", ".", "/"]);
+
+export function normalizeShortcut(input: string): string | undefined {
+  const parts = input
+    .trim()
+    .toLowerCase()
+    .replaceAll("option", "alt")
+    .replaceAll("command", "super")
+    .replaceAll("cmd", "super")
+    .split("+")
+    .map((part) => part.trim())
+    .filter(Boolean);
+  if (parts.length === 0) return undefined;
+
+  const key = parts.at(-1)!;
+  const modifiers = parts.slice(0, -1);
+  if (new Set(modifiers).size !== modifiers.length) return undefined;
+  if (
+    modifiers.some(
+      (modifier) =>
+        !MODIFIER_ORDER.includes(modifier as (typeof MODIFIER_ORDER)[number]),
+    )
+  ) {
+    return undefined;
+  }
+
+  const isLetter = /^[a-z]$/.test(key);
+  const isDigit = /^\d$/.test(key);
+  const isFunction = /^f(?:[1-9]|1[0-2])$/.test(key);
+  const isSpecial = SPECIAL_KEYS.has(key);
+  const isSymbol = SYMBOL_KEYS.has(key);
+  if (!isLetter && !isDigit && !isFunction && !isSpecial && !isSymbol) return undefined;
+
+  // Bare printable keys would make normal editor input impossible.
+  if (modifiers.length === 0 && !isFunction) return undefined;
+  // Shift-only printable keys are also normal text input.
+  if (
+    modifiers.length === 1 &&
+    modifiers[0] === "shift" &&
+    (isLetter || isDigit || isSymbol)
+  ) {
+    return undefined;
+  }
+
+  const ordered = MODIFIER_ORDER.filter((modifier) => modifiers.includes(modifier));
+  return [
+    ...ordered,
+    key === "pageup" ? "pageUp" : key === "pagedown" ? "pageDown" : key,
+  ].join("+");
+}
+
+export function displayShortcut(shortcut: string): string {
+  return shortcut
+    .split("+")
+    .map((part) => {
+      if (process.platform === "darwin" && part.toLowerCase() === "alt") return "Option";
+      return part.length === 1
+        ? part.toUpperCase()
+        : `${part[0]?.toUpperCase()}${part.slice(1)}`;
+    })
+    .join("+");
+}

package/src/shortcuts.ts

@@ -0,0 +1,167 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  Container,
+  parseKey,
+  Spacer,
+  Text,
+  truncateToWidth,
+  type Component,
+  type KeybindingsManager,
+  type TUI,
+} from "@earendil-works/pi-tui";
+import {
+  DEFAULT_SHORTCUT,
+  displayShortcut,
+  normalizeShortcut,
+} from "./shortcut-core.js";
+import { VoiceKeys } from "./keybindings.js";
+import { panelBorder } from "./ui-components.js";
+
+type UiTheme = ExtensionContext["ui"]["theme"];
+type Conflict = { description: string };
+type Phase =
+  | { kind: "waiting" }
+  | { kind: "preview"; normalized: string; conflicts: Conflict[] }
+  | { kind: "error"; message: string };
+
+// Pi exposes its resolved built-in bindings here, but not shortcuts owned by
+// other extensions. Pi reports those collisions when it reloads.
+function findConflicts(kb: KeybindingsManager, shortcut: string): Conflict[] {
+  const resolved = kb.getResolvedBindings();
+  const result: Conflict[] = [];
+  for (const [id, keys] of Object.entries(resolved)) {
+    if (keys === undefined) continue;
+    const keyList: string[] = Array.isArray(keys) ? keys : [keys];
+    if (keyList.includes(shortcut)) {
+      const def = kb.getDefinition(id as never);
+      if (def?.description) result.push({ description: def.description });
+    }
+  }
+  return result;
+}
+
+export function createShortcutPicker(
+  tui: TUI,
+  theme: UiTheme,
+  keybindings: KeybindingsManager,
+  current: string,
+  done: (shortcut: string | undefined) => void,
+): Component {
+  const keys = new VoiceKeys(keybindings);
+  let phase: Phase = { kind: "waiting" };
+  const container = new Container();
+
+  function rebuild(): void {
+    container.clear();
+    container.addChild(panelBorder(theme));
+    container.addChild(new Spacer(1));
+    container.addChild(
+      new Text(theme.fg("accent", theme.bold("Record keyboard shortcut")), 1, 0),
+    );
+    container.addChild(
+      new Text(theme.fg("muted", `Current: ${displayShortcut(current)}`), 1, 0),
+    );
+    container.addChild(new Spacer(1));
+
+    if (phase.kind === "preview") {
+      container.addChild(
+        new Text(theme.fg("accent", displayShortcut(phase.normalized)), 1, 0),
+      );
+      if (phase.conflicts.length > 0) {
+        container.addChild(
+          new Text(
+            theme.fg(
+              "warning",
+              `Built-in conflict: ${phase.conflicts.map((conflict) => conflict.description).join(", ")}. Pi may override or reject this shortcut.`,
+            ),
+            1,
+            0,
+          ),
+        );
+      }
+      container.addChild(new Spacer(1));
+      container.addChild(
+        new Text(
+          `${keys.hint("tui.select.confirm", "keep")}  ${keys.hint("voice.shortcut.useDefault", "default")}  ${theme.fg("dim", "press another shortcut to replace")}  ${keys.hint("tui.select.cancel", "back")}`,
+          1,
+          0,
+        ),
+      );
+    } else {
+      if (phase.kind === "error") {
+        container.addChild(new Text(theme.fg("error", phase.message), 1, 0));
+        container.addChild(new Spacer(1));
+      }
+      container.addChild(
+        new Text(theme.fg("muted", "Press a key combination…"), 1, 0),
+      );
+      container.addChild(new Spacer(1));
+      container.addChild(
+        new Text(
+          `${keys.hint("voice.shortcut.useDefault", `default (${displayShortcut(DEFAULT_SHORTCUT)})`)}  ${keys.hint("tui.select.cancel", "back")}`,
+          1,
+          0,
+        ),
+      );
+    }
+
+    container.addChild(new Spacer(1));
+    container.addChild(panelBorder(theme));
+  }
+
+  rebuild();
+
+  return {
+    wantsKeyRelease: false,
+
+    render(width: number): string[] {
+      return container.render(width).map((line) => truncateToWidth(line, width, ""));
+    },
+
+    handleInput(data: string): void {
+      if (keys.matches(data, "tui.select.cancel")) {
+        done(undefined);
+        return;
+      }
+
+      if (keys.matches(data, "tui.select.confirm")) {
+        if (phase.kind === "preview") done(phase.normalized);
+        return;
+      }
+
+      if (keys.matches(data, "voice.shortcut.useDefault")) {
+        phase = {
+          kind: "preview",
+          normalized: DEFAULT_SHORTCUT,
+          conflicts: findConflicts(keybindings, DEFAULT_SHORTCUT),
+        };
+        rebuild();
+        tui.requestRender();
+        return;
+      }
+
+      const parsed = parseKey(data);
+      if (!parsed) return;
+
+      const normalized = normalizeShortcut(parsed);
+      if (!normalized) {
+        phase = {
+          kind: "error",
+          message: `${displayShortcut(parsed)} is not valid. Use a modifier such as Ctrl or Alt, or a function key.`,
+        };
+      } else {
+        phase = {
+          kind: "preview",
+          normalized,
+          conflicts: findConflicts(keybindings, normalized),
+        };
+      }
+      rebuild();
+      tui.requestRender();
+    },
+
+    invalidate(): void {
+      rebuild();
+    },
+  };
+}

package/src/startup-shortcut.ts

@@ -0,0 +1,24 @@
+import { readFileSync } from "node:fs";
+import { DEFAULT_SHORTCUT, normalizeShortcut } from "./shortcut-core.js";
+import { legacySettingsPath, settingsPath } from "./settings-path.js";
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Read only the setting Pi needs while synchronously registering the extension. */
+export function readShortcutForRegistration(): string {
+  for (const path of [settingsPath(), legacySettingsPath()]) {
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+      if (!isObject(parsed) || parsed.version !== 1 || typeof parsed.shortcut !== "string") {
+        return DEFAULT_SHORTCUT;
+      }
+      return normalizeShortcut(parsed.shortcut) ?? DEFAULT_SHORTCUT;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+      return DEFAULT_SHORTCUT;
+    }
+  }
+  return DEFAULT_SHORTCUT;
+}

package/src/transcript-preview.ts

@@ -0,0 +1,52 @@
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
+import type { VoiceKeys } from "./keybindings.js";
+
+/** A bounded read-only view. Clipping never changes the underlying transcript. */
+export class TranscriptPreview {
+  private content = "";
+  private text = new Text("", 1, 0);
+  private offset = 0;
+  private lineCount = 1;
+  private pageSize = 1;
+
+  constructor(private readonly keys: VoiceKeys) {}
+
+  setText(content: string): void {
+    if (this.content === content) return;
+    this.content = content;
+    this.text.setText(content);
+    this.offset = 0;
+  }
+
+  invalidate(): void { this.text.invalidate(); }
+
+  render(width: number, height: number, muted: (text: string) => string): string[] {
+    const rows = Math.max(1, height);
+    const lines = this.content ? this.text.render(width) : [" ".repeat(width)];
+    this.lineCount = lines.length;
+    const clipped = lines.length > rows;
+    this.pageSize = Math.max(1, rows - (clipped && rows > 1 ? 1 : 0));
+    this.offset = Math.max(0, Math.min(this.offset, lines.length - this.pageSize));
+    const visible = lines.slice(this.offset, this.offset + this.pageSize);
+    if (clipped && rows > 1) {
+      visible.push(truncateToWidth(
+        muted(` ${this.offset + 1}–${this.offset + visible.length} / ${lines.length} lines · ${this.keys.navLabel()} / ${this.keys.keyText(["tui.select.pageUp", "tui.select.pageDown"])} scroll`), width,
+      ));
+    }
+    return visible;
+  }
+
+  handleInput(data: string): boolean {
+    if (this.lineCount <= this.pageSize) return false;
+    let offset = this.offset;
+    if (this.keys.matches(data, "tui.select.up")) offset--;
+    else if (this.keys.matches(data, "tui.select.down")) offset++;
+    else if (this.keys.matches(data, "tui.select.pageUp")) offset -= this.pageSize;
+    else if (this.keys.matches(data, "tui.select.pageDown")) offset += this.pageSize;
+    else if (this.keys.matches(data, "voice.scroll.top")) offset = 0;
+    else if (this.keys.matches(data, "voice.scroll.bottom")) offset = this.lineCount - this.pageSize;
+    else return false;
+    this.offset = Math.max(0, Math.min(offset, this.lineCount - this.pageSize));
+    return true;
+  }
+}