charness 3.1.0 → 3.3.0

package/dist/stt/sttConfigEdit.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sttLanguagePresets = exports.sttIdleMinutesPresets = exports.sttTimeoutPercentPresets = exports.sttTimeoutBasePresets = void 0;
+exports.moveSttEngine = moveSttEngine;
+exports.toggleSttEngineDisabled = toggleSttEngineDisabled;
+exports.setSttEngineTimeout = setSttEngineTimeout;
+exports.setSttEngineApiKey = setSttEngineApiKey;
+exports.removeSttEngine = removeSttEngine;
+exports.addSttEngine = addSttEngine;
+exports.enableLocalSttEngine = enableLocalSttEngine;
+exports.dropLocalSttEngine = dropLocalSttEngine;
+exports.setSttLanguage = setSttLanguage;
+exports.setSttIdleMinutes = setSttIdleMinutes;
+exports.setSttWorkers = setSttWorkers;
+exports.normaliseSttUrl = normaliseSttUrl;
+const sttSettings_1 = require("./sttSettings");
+/**
+ * @description The edits `/stt` makes to `stt.json`, as pure functions: each takes the current settings and
+ * returns the next ones (or a named refusal), validated by the same schema a hand edit goes through — a button
+ * can never write a file the loader would refuse.
+ */
+exports.sttTimeoutBasePresets = [5, 10, 20, 30];
+exports.sttTimeoutPercentPresets = [10, 25, 50, 100];
+/** Minutes the local engine may idle; `0` is "never exits". */
+exports.sttIdleMinutesPresets = [5, 15, 30, 60, 0];
+exports.sttLanguagePresets = [sttSettings_1.gigaamLanguage, 'en', 'uk', 'de', 'fr', 'es'];
+const baseUrlSuffixRe = /\/v1\/?$/;
+const transcriptionsPath = '/v1/audio/transcriptions';
+const transcriptionsPathRe = /\/audio\/transcriptions\/?$/;
+function finalize(config) {
+    const validation = (0, sttSettings_1.validateSttConfig)(config);
+    return validation.ok ? { ok: true, config: validation.config } : { ok: false, reason: 'invalidValue' };
+}
+function findEngineIndex(config, engineId) {
+    return config.engines.findIndex((engine) => engine.id === engineId);
+}
+function replaceEngine(config, engineId, change) {
+    const index = findEngineIndex(config, engineId);
+    if (index < 0)
+        return { ok: false, reason: 'unknownEngine' };
+    return finalize({ ...config, engines: config.engines.map((engine, position) => (position === index ? change(engine) : engine)) });
+}
+/** @description Move an engine one place earlier (`-1`) or later (`1`); at the end of the list it stays. */
+function moveSttEngine(config, engineId, direction) {
+    const index = findEngineIndex(config, engineId);
+    if (index < 0)
+        return { ok: false, reason: 'unknownEngine' };
+    const target = index + direction;
+    if (target < 0 || target >= config.engines.length)
+        return { ok: true, config };
+    const engines = [...config.engines];
+    [engines[index], engines[target]] = [engines[target], engines[index]];
+    return finalize({ ...config, engines });
+}
+/** @description Switch an engine between "use" and "don't use" without removing it. */
+function toggleSttEngineDisabled(config, engineId) {
+    return replaceEngine(config, engineId, (engine) => {
+        const { isDisabled: _wasDisabled, ...rest } = engine;
+        return engine.isDisabled ? rest : { ...rest, isDisabled: true };
+    });
+}
+/** @description Change one half of an engine's timeout; the other half keeps its value (default `10 s + 25 %`). */
+function setSttEngineTimeout(config, engineId, change, currentTimeout) {
+    return replaceEngine(config, engineId, (engine) => ({ ...engine, timeout: { ...(engine.timeout ?? currentTimeout), ...change } }));
+}
+/** @description Set (or replace) an engine's API key. */
+function setSttEngineApiKey(config, engineId, apiKey) {
+    return replaceEngine(config, engineId, (engine) => ({ ...engine, apiKey }));
+}
+function removeSttEngine(config, engineId) {
+    if (findEngineIndex(config, engineId) < 0)
+        return { ok: false, reason: 'unknownEngine' };
+    return finalize({ ...config, engines: config.engines.filter((engine) => engine.id !== engineId) });
+}
+/**
+ * @description Add an engine with a fresh id: the local one goes FIRST (it is the point of installing it), the
+ * others last. The local engine can be listed once; the list holds at most {@link sttEngineLimit}.
+ */
+function addSttEngine(config, spec) {
+    if (config.engines.length >= sttSettings_1.sttEngineLimit)
+        return { ok: false, reason: 'full' };
+    if (spec.kind === 'gigaam' && config.engines.some((engine) => engine.kind === 'gigaam'))
+        return { ok: false, reason: 'alreadyListed' };
+    const engineId = (0, sttSettings_1.createSttEngineId)(spec.kind, new Set(config.engines.map((engine) => engine.id)));
+    const engine = spec.kind === 'gigaam'
+        ? { id: engineId, kind: 'gigaam' }
+        : spec.kind === 'url'
+            ? { id: engineId, kind: 'url', url: spec.url, ...(spec.apiKey ? { apiKey: spec.apiKey } : {}) }
+            : { id: engineId, kind: spec.kind, apiKey: spec.apiKey };
+    const engines = spec.kind === 'gigaam' ? [engine, ...config.engines] : [...config.engines, engine];
+    const result = finalize({ ...config, engines });
+    return result.ok ? { ...result, engineId } : result;
+}
+/**
+ * @description After the local engine is installed: put it first when the chain does not name it yet, else just
+ * make sure it is switched on where it already stands.
+ */
+function enableLocalSttEngine(config) {
+    const existing = config.engines.find((engine) => engine.kind === 'gigaam');
+    if (!existing)
+        return addSttEngine(config, { kind: 'gigaam' });
+    return existing.isDisabled ? toggleSttEngineDisabled(config, existing.id) : { ok: true, config };
+}
+/** @description Drop the local engine from the chain (its files are removed by the caller). */
+function dropLocalSttEngine(config) {
+    return finalize({ ...config, engines: config.engines.filter((engine) => engine.kind !== 'gigaam') });
+}
+function setSttLanguage(config, language) {
+    return finalize({ ...config, language });
+}
+function setSttIdleMinutes(config, idleMinutes) {
+    return finalize({ ...config, gigaam: { ...config.gigaam, idleMinutes } });
+}
+function setSttWorkers(config, workers) {
+    return finalize({ ...config, gigaam: { ...config.gigaam, workers } });
+}
+/**
+ * @description Turn what the operator typed into the endpoint URL: it must be http(s) and carry no login (a key
+ * has its own step). A base address (`http://host:8000`, `…/v1`) gets `/v1/audio/transcriptions` appended; an
+ * address that already names `…/audio/transcriptions` is kept as typed, and so is any other path (a proxy
+ * under its own prefix).
+ */
+function normaliseSttUrl(input) {
+    let parsed;
+    try {
+        parsed = new URL(input.trim());
+    }
+    catch {
+        return { ok: false, reason: 'invalid' };
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+        return { ok: false, reason: 'invalid' };
+    if (parsed.username || parsed.password)
+        return { ok: false, reason: 'credentials' };
+    parsed.hash = '';
+    const trimmedPath = parsed.pathname.replace(/\/+$/, '');
+    if (transcriptionsPathRe.test(trimmedPath))
+        return { ok: true, url: parsed.toString() };
+    if (trimmedPath === '' || baseUrlSuffixRe.test(parsed.pathname)) {
+        parsed.pathname = `${trimmedPath.replace(baseUrlSuffixRe, '')}${transcriptionsPath}`;
+    }
+    return { ok: true, url: parsed.toString() };
+}
+//# sourceMappingURL=sttConfigEdit.js.map

package/dist/stt/sttConfigEdit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sttConfigEdit.js","sourceRoot":"","sources":["../../src/stt/sttConfigEdit.ts"],"names":[],"mappings":"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"}

package/dist/stt/sttInstall.d.ts

@@ -0,0 +1,147 @@
+/**
+ * @description The install of the local speech engine: a private Python venv
+ * under `<DATA_DIR>/stt` holding the pinned `onnx-asr` + `soundfile`, and the
+ * GigaAM model fetched into a private Hugging Face cache — nothing is shared
+ * with, or written into, the operator's Python. There is NO user-facing command:
+ * the bot runs this from `/stt` ("Add engine → GigaAM (local)") or, when `stt.json`
+ * names the local engine, at boot; both launch the detached `sttInstallEntry`.
+ */
+/** Must equal `SCRIPT_VERSION` in `stt/gigaam_sidecar.py` (a unit test holds them together). */
+export declare const gigaamScriptVersion = "1";
+/** The one place the pinned packages are named. */
+export declare const gigaamPinnedRequirements: readonly string[];
+/** The int8 e2e-rnnt files as fetched (216 MiB: the 215 MB encoder, decoder, joint, vocab), the progress denominator. */
+export declare const gigaamModelApproxBytes: number;
+/** Where everything of the local engine lives under a data dir. */
+export interface SttPaths {
+    root: string;
+    venvDir: string;
+    venvPython: string;
+    /** `HF_HOME` of the sidecar and of the install's model fetch. */
+    hfHome: string;
+    uvCacheDir: string;
+    markerFile: string;
+    lockDir: string;
+    installLog: string;
+    progressFile: string;
+}
+export declare function getSttPaths(dataDir: string): SttPaths;
+/**
+ * @description The sidecar script that ships in the package's `stt/` dir, two
+ * levels above this module (`src/stt` under tsx, `dist/stt` once built).
+ */
+export declare function getSidecarScriptPath(): string;
+/** What the host offers: `uv`, and/or a `python3` with the venv module. */
+export interface SttInstallFacts {
+    uvPath: string | null;
+    python3: {
+        path: string;
+        major: number;
+        minor: number;
+        hasVenvSupport: boolean;
+    } | null;
+    paths: SttPaths;
+}
+export interface SttInstallCommand {
+    command: string;
+    args: string[];
+    /** Shown to the operator while it runs. */
+    phase: 'creatingEnvironment' | 'installingPackages';
+}
+export type SttInstallPlan = {
+    ok: true;
+    tool: 'uv' | 'pip';
+    commands: SttInstallCommand[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare const missingPythonToolError: string;
+/**
+ * @description Decide how to build the venv: `uv` first (it needs no `ensurepip`
+ * and can fetch a Python), else a `python3` >= 3.10 that can create a venv with
+ * pip, else an error naming what is missing.
+ */
+export declare function planSttInstall(facts: SttInstallFacts): SttInstallPlan;
+/** @description Look at the host: where `uv` and a usable `python3` are. */
+export declare function detectSttInstallFacts(paths: SttPaths, env?: NodeJS.ProcessEnv): SttInstallFacts;
+/** @name SttInstallMarker @description `installed.json`: what the venv was built from. */
+export interface SttInstallMarker {
+    scriptVersion: string;
+    pins: string[];
+    installedAt: string;
+}
+/**
+ * @description Whether the local engine is ready to start: the marker names the
+ * script version and pins this build ships, and the venv's interpreter is still
+ * there. Cheap and synchronous — it runs for every voice note.
+ */
+export declare function isGigaamInstalled(dataDir: string): boolean;
+/** @description An install job is running right now (its lock is held by a live process, not stale). */
+export declare function isGigaamInstalling(dataDir: string, nowMs?: number): boolean;
+export type SttInstallPhase = 'creatingEnvironment' | 'installingPackages' | 'downloadingModel' | 'checking' | 'done' | 'failed';
+/** @name SttInstallProgress @description One progress report; `failed` carries the error and the log tail. */
+export interface SttInstallProgress {
+    phase: SttInstallPhase;
+    detail: string;
+    /** Bytes of the model cache so far (during `downloadingModel` / `checking`). */
+    bytesDownloaded: number;
+    error?: string;
+    logTail?: string[];
+}
+/**
+ * @description The last complete progress report in the text of the progress
+ * file (one JSON object per line); a torn last line from a crash is skipped.
+ */
+export declare function getLastSttInstallProgress(text: string): SttInstallProgress | null;
+export declare function readSttInstallProgress(dataDir: string): SttInstallProgress | null;
+/** @description "120/217 MB" — the download line of the progress report. */
+export declare function formatDownloadDetail(bytesDownloaded: number): string;
+export interface SttCommandResult {
+    exitCode: number | null;
+    /** Everything the command printed to stdout. */
+    stdout: string;
+}
+/** Runs one install command with its output appended to the log; replaceable in tests. */
+export type SttCommandRunner = (command: string, args: string[], options: {
+    env: NodeJS.ProcessEnv;
+    logFile: string;
+    timeoutMs: number;
+}) => Promise<SttCommandResult>;
+export declare const runSttCommand: SttCommandRunner;
+export interface SttInstallOptions {
+    onProgress?: (progress: SttInstallProgress) => void;
+    /** Rebuild the venv even when the marker says it is current. */
+    force?: boolean;
+    env?: NodeJS.ProcessEnv;
+    /** Seams for tests. */
+    runCommand?: SttCommandRunner;
+    detectFacts?: (paths: SttPaths, env: NodeJS.ProcessEnv) => SttInstallFacts;
+    downloadPollIntervalMs?: number;
+    nowMs?: () => number;
+}
+export type SttInstallResult = {
+    ok: true;
+    wasAlreadyInstalled: boolean;
+} | {
+    ok: false;
+    reason: 'locked' | 'failed';
+    error: string;
+    logTail: string[];
+};
+/**
+ * @description Build the venv, install the pinned packages and fetch the model
+ * (`--check` loads it and recognises a second of silence, so a broken download
+ * is caught here, not by the first voice). Idempotent: a current marker means
+ * nothing to do unless `force`. One install at a time per data dir (a lock
+ * directory; a stale one or a dead owner's is replaced). Child output goes to
+ * `install.log`; a failure returns its last lines.
+ */
+export declare function runSttInstall(dataDir: string, options?: SttInstallOptions): Promise<SttInstallResult>;
+/**
+ * @description Delete the local engine's files (venv, model cache, uv cache,
+ * marker, install log). Refuses while an install runs. The caller stops the
+ * sidecar first.
+ */
+export declare function removeSttInstall(dataDir: string): boolean;
+//# sourceMappingURL=sttInstall.d.ts.map

package/dist/stt/sttInstall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sttInstall.d.ts","sourceRoot":"","sources":["../../src/stt/sttInstall.ts"],"names":[],"mappings":"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"}