@earendil-works/pi-voice 0.1.0

package/src/settings-menu.ts

@@ -0,0 +1,410 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { testMicrophonePermission } from "./audio.js";
+import { displayLanguage, getCatalogModel } from "./catalog.js";
+import { chineseOutputSummary, isChineseLanguage } from "./chinese.js";
+import {
+  chooseLanguages,
+  createTranscriptionLanguagePicker,
+  transcriptionLanguageSummary,
+} from "./model-picker.js";
+import {
+  chooseMicrophone,
+  microphonePermissionSummary,
+  microphonesEqual,
+  microphoneSummary,
+  type MicrophonePermission,
+} from "./microphone-picker.js";
+import { runModelSelection } from "./onboarding.js";
+import {
+  writeSettings,
+  type ChineseOutput,
+  type MicrophoneSetting,
+  type TranscribeSettings,
+  type TranscriptionLanguage,
+} from "./settings.js";
+import { displayShortcut } from "./shortcut-core.js";
+import { createShortcutPicker } from "./shortcuts.js";
+import {
+  padToWidth,
+  SingleSelectPicker,
+  type SingleSelectChoice,
+} from "./ui-components.js";
+
+const MACOS_MICROPHONE_SETTINGS_URL =
+  "x-apple.systempreferences:com.apple.preference.security?Privacy_Microphone";
+const SETTINGS_LABEL_WIDTH = 25;
+// Text padding (2), cursor gutter (2), label column, and its gap (2).
+const SETTINGS_ROW_OVERHEAD = SETTINGS_LABEL_WIDTH + 6;
+
+type SettingsAction =
+  | "preferred-languages"
+  | "model"
+  | "transcription-language"
+  | "chinese-output"
+  | "microphone"
+  | "shortcut";
+
+type SettingsHomeChoice = SingleSelectChoice<SettingsAction> & {
+  summary: string;
+  /** Render the summary in the error color. */
+  alert?: boolean;
+};
+
+function preferredLanguagesSummary(languages: readonly string[]): string {
+  const names = languages.map(displayLanguage);
+  const visible = names.slice(0, 3).join(", ");
+  return names.length > 3 ? `${visible} +${names.length - 3}` : visible;
+}
+
+function languagesEqual(left: readonly string[], right: readonly string[]): boolean {
+  return left.join("\0") === right.join("\0");
+}
+
+async function saveUpdatedSettings(
+  ctx: ExtensionContext,
+  configured: TranscribeSettings,
+  updated: TranscribeSettings,
+  successMessage?: string,
+): Promise<boolean> {
+  try {
+    await writeSettings(updated);
+    Object.assign(configured, updated);
+    if (successMessage) ctx.ui.notify(successMessage, "info");
+    return true;
+  } catch (error) {
+    ctx.ui.notify(
+      `Could not save settings: ${error instanceof Error ? error.message : String(error)}`,
+      "error",
+    );
+    return false;
+  }
+}
+
+function settingsHomeChoices(
+  configured: TranscribeSettings,
+  permission: MicrophonePermission,
+): SettingsHomeChoice[] {
+  const model = getCatalogModel(configured.model.id)!;
+  const choices: SettingsHomeChoice[] = [
+    {
+      value: "preferred-languages",
+      label: "Preferred languages",
+      summary: preferredLanguagesSummary(configured.preferredLanguages),
+      description: "Languages you speak, used to rank and recommend transcription models",
+    },
+    {
+      value: "model",
+      label: "Model",
+      summary: model.name,
+      description: "Switch between downloaded models, or download a new one",
+    },
+    {
+      value: "transcription-language",
+      label: "Transcription language",
+      summary: transcriptionLanguageSummary(configured.transcriptionLanguage, model),
+      description: "Language expected in recordings, or automatic detection when supported",
+    },
+  ];
+
+  if (
+    isChineseLanguage(configured.transcriptionLanguage) ||
+    configured.preferredLanguages.some(isChineseLanguage)
+  ) {
+    choices.push({
+      value: "chinese-output",
+      label: "Chinese output",
+      summary: chineseOutputSummary(configured.chineseOutput),
+      description: "Character style used for Chinese transcripts",
+    });
+  }
+
+  choices.push(
+    {
+      value: "microphone",
+      label: "Microphone",
+      // A permission problem replaces the device summary so it is visible
+      // from the home screen; selecting the row then goes straight to the
+      // System Settings fix.
+      ...(permission.status === "denied" && process.platform === "darwin"
+        ? {
+            summary: "✗ Access denied",
+            alert: true,
+            description: "Grant microphone access to the terminal application running Pi",
+          }
+        : {
+            summary: microphoneSummary(configured.microphone),
+            description: "Input device used for dictation",
+          }),
+    },
+    {
+      value: "shortcut",
+      label: "Shortcut",
+      summary: displayShortcut(configured.shortcut),
+      description: "Terminal shortcut that starts and stops microphone dictation",
+    },
+  );
+
+  return choices;
+}
+
+async function showSettingsHome(
+  ctx: ExtensionContext,
+  configured: TranscribeSettings,
+  permission: MicrophonePermission,
+): Promise<SettingsAction | undefined> {
+  return ctx.ui.custom<SettingsAction | undefined>((tui, theme, keybindings, done) => {
+    const choices = settingsHomeChoices(configured, permission);
+    const rows = new Map(choices.map((choice) => [choice.value, choice]));
+    return new SingleSelectPicker(
+      tui,
+      theme,
+      keybindings,
+      choices,
+      undefined,
+      {
+        title: "Pi Voice settings",
+        cancelLabel: "close",
+        renderLabel: (choice, active, width) => {
+          const row = rows.get(choice.value);
+          const labelText = padToWidth(choice.label, SETTINGS_LABEL_WIDTH);
+          const label = active ? theme.fg("accent", labelText) : labelText;
+          // Long summaries (language lists, microphone names) truncate so
+          // they never wrap the row and break the column layout.
+          const summary = truncateToWidth(
+            row?.summary ?? "",
+            Math.max(12, width - SETTINGS_ROW_OVERHEAD),
+            "…",
+          );
+          const value = row?.alert
+            ? theme.fg("error", summary)
+            : theme.fg("dim", summary);
+          return `${label}  ${value}`;
+        },
+      },
+      done,
+    );
+  });
+}
+
+async function chooseChineseOutput(
+  ctx: ExtensionContext,
+  current: ChineseOutput,
+): Promise<ChineseOutput | undefined> {
+  const choices: SingleSelectChoice<ChineseOutput>[] = [
+    {
+      value: "simplified",
+      label: "Simplified",
+      description: "Convert Chinese transcripts to simplified characters",
+    },
+    {
+      value: "traditional-taiwan",
+      label: "Traditional (Taiwan)",
+      description: "Use traditional characters and Taiwan conventions",
+    },
+    {
+      value: "traditional-hong-kong",
+      label: "Traditional (Hong Kong)",
+      description: "Use traditional characters and Hong Kong conventions",
+    },
+  ];
+  return ctx.ui.custom<ChineseOutput | undefined>((tui, theme, keybindings, done) =>
+    new SingleSelectPicker(
+      tui,
+      theme,
+      keybindings,
+      choices,
+      current,
+      { title: "Choose Chinese output", cancelLabel: "back" },
+      done,
+    ),
+  );
+}
+
+async function chooseTranscriptionLanguage(
+  ctx: ExtensionContext,
+  configured: TranscribeSettings,
+): Promise<TranscriptionLanguage | undefined> {
+  const model = getCatalogModel(configured.model.id)!;
+  return ctx.ui.custom<TranscriptionLanguage | undefined>(
+    (tui, theme, keybindings, done) =>
+      createTranscriptionLanguagePicker(
+        tui,
+        theme,
+        keybindings,
+        model,
+        configured.transcriptionLanguage,
+        configured.preferredLanguages,
+        done,
+      ),
+  );
+}
+
+async function chooseShortcut(
+  ctx: ExtensionContext,
+  current: string,
+): Promise<string | undefined> {
+  return ctx.ui.custom<string | undefined>((tui, theme, keybindings, done) =>
+    createShortcutPicker(tui, theme, keybindings, current, done),
+  );
+}
+
+export async function openMacOSMicrophoneSettings(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+): Promise<void> {
+  if (process.platform !== "darwin") return;
+  const result = await pi.exec("open", [MACOS_MICROPHONE_SETTINGS_URL]);
+  if (result.code === 0) {
+    ctx.ui.notify(
+      "Enable microphone access for your terminal app, then return to Pi and try recording. A terminal restart may be required.",
+      "info",
+    );
+  } else {
+    ctx.ui.notify(
+      "Could not open System Settings. Open Privacy & Security → Microphone manually.",
+      "error",
+    );
+  }
+}
+
+export async function offerMacOSPermissionHelp(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+): Promise<void> {
+  if (process.platform !== "darwin") return;
+  const openSettings = await ctx.ui.confirm(
+    "Microphone access",
+    "Microphone capture failed. Open macOS Privacy & Security → Microphone settings?",
+  );
+  if (openSettings) await openMacOSMicrophoneSettings(pi, ctx);
+}
+
+export async function showSettingsMenu(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  configured: TranscribeSettings,
+  registeredShortcut: string,
+): Promise<boolean> {
+  if (ctx.mode !== "tui") {
+    ctx.ui.notify("Pi Voice settings require the interactive TUI", "error");
+    return false;
+  }
+
+  let reload = configured.shortcut !== registeredShortcut;
+  // Checked on open and refreshed whenever the Microphone row is activated,
+  // where access problems are surfaced and fixed.
+  let permission = await testMicrophonePermission();
+  while (true) {
+    const action = await showSettingsHome(ctx, configured, permission);
+    if (!action) return reload;
+
+    if (action === "preferred-languages") {
+      const selection = await chooseLanguages(ctx, configured.preferredLanguages, {
+        cancelLabel: "back",
+      });
+      if (!selection || languagesEqual(selection.languages, configured.preferredLanguages)) {
+        continue;
+      }
+      await saveUpdatedSettings(
+        ctx,
+        configured,
+        { ...configured, preferredLanguages: selection.languages },
+        "Preferred languages saved",
+      );
+      continue;
+    }
+
+    if (action === "model") {
+      const updated = await runModelSelection(ctx, {
+        shortcut: configured.shortcut,
+        preferredLanguages: configured.preferredLanguages,
+        transcriptionLanguage: configured.transcriptionLanguage,
+        chineseOutput: configured.chineseOutput,
+        currentModelId: configured.model.id,
+        microphone: configured.microphone,
+        postActivation: "stay",
+        onPreferredLanguagesChange: async (preferredLanguages) => {
+          if (languagesEqual(preferredLanguages, configured.preferredLanguages)) return;
+          const next = { ...configured, preferredLanguages };
+          await writeSettings(next);
+          Object.assign(configured, next);
+          ctx.ui.notify("Preferred languages saved", "info");
+        },
+      });
+      if (updated) Object.assign(configured, updated);
+      continue;
+    }
+
+    if (action === "transcription-language") {
+      const transcriptionLanguage = await chooseTranscriptionLanguage(ctx, configured);
+      if (
+        !transcriptionLanguage ||
+        transcriptionLanguage === configured.transcriptionLanguage
+      ) {
+        continue;
+      }
+      const model = getCatalogModel(configured.model.id)!;
+      const summary = transcriptionLanguageSummary(transcriptionLanguage, model);
+      await saveUpdatedSettings(
+        ctx,
+        configured,
+        { ...configured, transcriptionLanguage },
+        `Transcription language saved as ${summary}`,
+      );
+      continue;
+    }
+
+    if (action === "chinese-output") {
+      const chineseOutput = await chooseChineseOutput(ctx, configured.chineseOutput);
+      if (!chineseOutput || chineseOutput === configured.chineseOutput) continue;
+      const summary = chineseOutputSummary(chineseOutput);
+      await saveUpdatedSettings(
+        ctx,
+        configured,
+        { ...configured, chineseOutput },
+        `Chinese output saved as ${summary}`,
+      );
+      continue;
+    }
+
+    if (action === "microphone") {
+      permission = await testMicrophonePermission();
+      if (permission.status === "denied" && process.platform === "darwin") {
+        // Choosing a device is pointless while capture is blocked; go
+        // straight to the fix.
+        await openMacOSMicrophoneSettings(pi, ctx);
+        continue;
+      }
+      const microphone = await chooseMicrophone(ctx, configured.microphone, permission);
+      if (!microphone || microphonesEqual(microphone, configured.microphone)) continue;
+      const summary = microphoneSummary(microphone);
+      await saveUpdatedSettings(
+        ctx,
+        configured,
+        { ...configured, microphone },
+        `Microphone saved as ${summary}`,
+      );
+      continue;
+    }
+
+    if (action === "shortcut") {
+      const shortcut = await chooseShortcut(ctx, configured.shortcut);
+      if (!shortcut || shortcut === configured.shortcut) continue;
+      const saved = await saveUpdatedSettings(ctx, configured, {
+        ...configured,
+        shortcut,
+      });
+      if (saved) {
+        reload = configured.shortcut !== registeredShortcut;
+        ctx.ui.notify(
+          `Shortcut saved as ${displayShortcut(shortcut)}. It will apply when settings close; other open Pi processes must be reloaded separately.`,
+          "info",
+        );
+      }
+    }
+  }
+}

package/src/settings-path.ts

@@ -0,0 +1,13 @@
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+
+export const SETTINGS_FILENAME = "pi-voice.json";
+export const LEGACY_SETTINGS_FILENAME = "pi-transcribe.json";
+
+export function settingsPath(): string {
+  return join(getAgentDir(), SETTINGS_FILENAME);
+}
+
+export function legacySettingsPath(): string {
+  return join(getAgentDir(), LEGACY_SETTINGS_FILENAME);
+}

package/src/settings.ts

@@ -0,0 +1,235 @@
+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";
+
+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: { type: "transcribe-cpp" };
+  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 validateSettings(value: unknown): TranscribeSettings | undefined {
+  if (!isObject(value) || value.version !== SETTINGS_VERSION) return undefined;
+  if (!isObject(value.backend) || value.backend.type !== "transcribe-cpp") 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: { type: "transcribe-cpp" },
+    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;
+};
+
+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: { 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 },
+  };
+}