@ailoud/providers 1.0.0-dev.1

package/dist/process/pager.js

@@ -0,0 +1,69 @@
+import { spawn } from 'node:child_process';
+/**
+ * Output longer than this goes through a pager, when there is a terminal to
+ * page on. Below it, paging would put a full-screen program in front of
+ * something that already fitted.
+ */
+export const PAGER_LINE_THRESHOLD = 30;
+/**
+ * Whether this output should be paged at all.
+ *
+ * Never when stdout is not a terminal. A redirect or a pipe wants the bytes,
+ * and handing them to `less` would either hang waiting for a keypress nobody
+ * can give or write escape sequences into a file. This is the same
+ * distinction `show` already draws between the frame and the payload.
+ *
+ * Also never when PAGER is set to the empty string, which is the
+ * conventional way to say "do not page".
+ */
+export function shouldPage(text, isTTY, env = process.env) {
+    if (!isTTY)
+        return false;
+    if (env['PAGER'] === '')
+        return false;
+    return text.split('\n').length > PAGER_LINE_THRESHOLD;
+}
+/**
+ * Shows `text` in the user's pager, resolving when they leave it.
+ *
+ * Uses the system pager rather than scrolling in-process. Up, down, page
+ * keys, search, and quitting on `q` all arrive already implemented and
+ * already behaving the way the user's other tools do -- git, man and less
+ * itself -- which is what "native" means here. A hand-rolled scroller would
+ * be a worse version of `less` that nobody had configured.
+ *
+ * Defaults to `less -R`: -R lets colour through rather than printing escape
+ * sequences literally. LESS is set only if the user has not, so their own
+ * configuration keeps winning.
+ *
+ * Falls back to writing the text out plainly if the pager cannot be started
+ * at all -- a machine without `less` should still be able to read a
+ * transcript.
+ */
+export async function page(text, write, env = process.env) {
+    const command = env['PAGER'] ?? 'less';
+    const [program, ...args] = command.split(/\s+/).filter((part) => part !== '');
+    if (program === undefined) {
+        write(text);
+        return;
+    }
+    await new Promise((resolve) => {
+        const child = spawn(program, args, {
+            // The pager owns the terminal while it runs: it needs the real stdout
+            // to draw on and the real stdin to read keys from. Only its input is a
+            // pipe, because that is what we are filling.
+            stdio: ['pipe', 'inherit', 'inherit'],
+            env: { ...env, ...(env['LESS'] === undefined ? { LESS: '-R' } : {}) },
+        });
+        child.on('error', () => {
+            // No pager on this machine. Printing beats failing.
+            write(text);
+            resolve();
+        });
+        // EPIPE, which is what quitting the pager early looks like from here. It
+        // is the user saying "I have read enough", not a failure.
+        child.stdin.on('error', () => undefined);
+        child.on('close', () => resolve());
+        child.stdin.end(text);
+    });
+}

package/dist/process/run.d.ts

@@ -0,0 +1,35 @@
+export interface RunResult {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface RunOptions {
+    readonly timeoutMs?: number;
+    /**
+     * Written to the child's stdin, which is then closed.
+     *
+     * The reason this exists: a prompt carrying a transcript does not fit in an
+     * argument. ARG_MAX is about a megabyte on macOS, less once the environment
+     * is counted, and a few hours of speech passes it -- the spawn then fails
+     * with E2BIG, which is a failure the user can do nothing about.
+     */
+    readonly stdin?: string;
+}
+export declare function run(command: string, args: readonly string[], options?: RunOptions): Promise<RunResult>;
+/**
+ * Runs a command with the parent's stdio, so anything it prints -- including
+ * a sudo password prompt -- reaches the real terminal. run() above buffers
+ * output instead, which is exactly wrong here: the prompt would vanish into
+ * a buffer and the user would stare at a hung terminal.
+ *
+ * Returns the exit code rather than throwing on a non-zero one: a failed
+ * install is a reportable outcome for provisioning, not an exception --
+ * one failed action must not abandon the rest of the plan.
+ *
+ * Deliberately has no timeout, unlike run(): a hard bound would kill a
+ * legitimate wait at a password prompt. The consequence is that with
+ * nothing real attached to stdin (no TTY), this can wait indefinitely, so
+ * callers must not invoke it non-interactively -- a later task enforces
+ * that at the call site.
+ */
+export declare function runInteractive(command: string, args: readonly string[]): Promise<number>;

package/dist/process/run.js

@@ -0,0 +1,101 @@
+import { spawn } from 'node:child_process';
+import { constants } from 'node:os';
+import { EnvironmentError, FailureError } from '@ailoud/core';
+const DEFAULT_TIMEOUT_MS = 30 * 60_000;
+/**
+ * `code` is null exactly when the child died from a signal rather than
+ * exiting on its own -- e.g. a user pressing Ctrl-C at a sudo password
+ * prompt. Collapsing that to a fixed sentinel like -1 or 1 makes "you
+ * cancelled" indistinguishable from "the command genuinely failed with
+ * that exit code", which is the wrong thing to report to someone trying to
+ * understand what just happened. 128 + signal number is the same mapping
+ * shells use (`$?` after a Ctrl-C'd command is 130, i.e. 128 + SIGINT's 2),
+ * so callers get a value that is both unambiguous and already familiar.
+ */
+function exitCodeForClose(code, signal) {
+    if (code !== null)
+        return code;
+    if (signal !== null)
+        return 128 + (constants.signals[signal] ?? 0);
+    return -1;
+}
+export function run(command, args, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    return new Promise((resolve, reject) => {
+        // shell: false is the default and must stay that way: paths reaching this
+        // function come from user input, and a shell would interpret them.
+        const child = spawn(command, [...args], { shell: false });
+        if (options.stdin !== undefined) {
+            // EPIPE if the child exits before reading it all -- which is a normal
+            // way for a child to behave, not an error worth failing the run over.
+            child.stdin.on('error', () => { });
+            child.stdin.end(options.stdin, 'utf8');
+        }
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+        }, timeoutMs);
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            if (error.code === 'ENOENT') {
+                reject(new EnvironmentError(`${command} was not found on PATH. Install it, or set its path in the ailoud config; run "ailoud doctor" for details.`));
+                return;
+            }
+            reject(error);
+        });
+        child.on('close', (code, signal) => {
+            clearTimeout(timer);
+            if (timedOut) {
+                // A timeout is not "the machine is not set up": the binary was
+                // found and started fine, it just did not finish in the time this
+                // one call allowed. That is a failure of this particular run, not
+                // of the environment, so it is a FailureError (exit 1) rather than
+                // an EnvironmentError (exit 3) -- there is no "fix" for doctor to
+                // report, only a run that needs to be retried, given more time, or
+                // investigated as its own problem.
+                reject(new FailureError(`${command} timed out after ${timeoutMs} ms and was killed`));
+                return;
+            }
+            resolve({ code: exitCodeForClose(code, signal), stdout, stderr });
+        });
+    });
+}
+/**
+ * Runs a command with the parent's stdio, so anything it prints -- including
+ * a sudo password prompt -- reaches the real terminal. run() above buffers
+ * output instead, which is exactly wrong here: the prompt would vanish into
+ * a buffer and the user would stare at a hung terminal.
+ *
+ * Returns the exit code rather than throwing on a non-zero one: a failed
+ * install is a reportable outcome for provisioning, not an exception --
+ * one failed action must not abandon the rest of the plan.
+ *
+ * Deliberately has no timeout, unlike run(): a hard bound would kill a
+ * legitimate wait at a password prompt. The consequence is that with
+ * nothing real attached to stdin (no TTY), this can wait indefinitely, so
+ * callers must not invoke it non-interactively -- a later task enforces
+ * that at the call site.
+ */
+export function runInteractive(command, args) {
+    return new Promise((resolve, reject) => {
+        // shell: false for the same reason as run() above: these paths come
+        // from user input, and a shell would interpret them.
+        const child = spawn(command, [...args], { shell: false, stdio: 'inherit' });
+        child.on('error', (error) => {
+            reject(new EnvironmentError(`could not run "${command}": ${error instanceof Error ? error.message : String(error)}`));
+        });
+        // See exitCodeForClose above run(): the same code-vs-signal ambiguity
+        // applies here, and matters more, since Ctrl-C at a sudo prompt is the
+        // expected way a user cancels this specific function.
+        child.on('close', (code, signal) => resolve(exitCodeForClose(code, signal)));
+    });
+}

package/dist/provision/download.d.ts

@@ -0,0 +1,19 @@
+export interface DownloadOptions {
+    readonly onProgress?: (received: number, total: number | null) => void;
+    readonly fetchImpl?: typeof fetch;
+}
+/**
+ * Downloads `url` to `targetPath`, atomically.
+ *
+ * The body streams into `<targetPath>.part` and is renamed onto the target
+ * only once it is complete. A 465 MB model interrupted at 300 MB must never
+ * leave a file that `doctor` reports as present -- that failure would
+ * resurface far away, as whisper failing to load a model, and be miserable
+ * to trace back to a dropped connection.
+ *
+ * Completeness is judged against the response's own Content-Length, not
+ * against a size compiled into ailoud: an upstream reupload should not be able
+ * to make installation fail. When the server advertises no length, the
+ * stream ending cleanly is all there is to go on, and that is accepted.
+ */
+export declare function downloadFile(url: string, targetPath: string, options?: DownloadOptions): Promise<void>;

package/dist/provision/download.js

@@ -0,0 +1,80 @@
+import { createWriteStream } from 'node:fs';
+import { access, mkdir, rename, rm } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { dirname } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { FailureError } from '@ailoud/core';
+async function exists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Downloads `url` to `targetPath`, atomically.
+ *
+ * The body streams into `<targetPath>.part` and is renamed onto the target
+ * only once it is complete. A 465 MB model interrupted at 300 MB must never
+ * leave a file that `doctor` reports as present -- that failure would
+ * resurface far away, as whisper failing to load a model, and be miserable
+ * to trace back to a dropped connection.
+ *
+ * Completeness is judged against the response's own Content-Length, not
+ * against a size compiled into ailoud: an upstream reupload should not be able
+ * to make installation fail. When the server advertises no length, the
+ * stream ending cleanly is all there is to go on, and that is accepted.
+ */
+export async function downloadFile(url, targetPath, options = {}) {
+    if (await exists(targetPath))
+        return;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const partPath = `${targetPath}.part`;
+    await mkdir(dirname(targetPath), { recursive: true });
+    const response = await fetchImpl(url);
+    if (!response.ok) {
+        throw new FailureError(`download failed for ${url}: HTTP ${response.status}`);
+    }
+    if (response.body === null) {
+        throw new FailureError(`download failed for ${url}: the response had no body`);
+    }
+    const header = response.headers.get('content-length');
+    // Number('') is 0, not NaN, so an empty header must be rejected by hand
+    // before the numeric check below; a header that is otherwise not a
+    // finite, non-negative number (non-numeric or negative) carries no usable
+    // length either. Treat all of these the same as "no length advertised"
+    // rather than as a total of 0, which would fail every download that
+    // completed fine just because the server sent junk.
+    const parsedHeader = header === null || header.trim() === '' ? NaN : Number(header);
+    const total = Number.isFinite(parsedHeader) && parsedHeader >= 0 ? parsedHeader : null;
+    let received = 0;
+    try {
+        const source = Readable.fromWeb(response.body);
+        source.on('data', (chunk) => {
+            received += chunk.length;
+            options.onProgress?.(received, total);
+        });
+        await pipeline(source, createWriteStream(partPath));
+        if (total !== null && received !== total) {
+            const direction = received < total ? 'incomplete' : 'longer than advertised';
+            throw new FailureError(`download ${direction} for ${url}: expected ${total} bytes, received ${received}`);
+        }
+        await rename(partPath, targetPath);
+    }
+    catch (error) {
+        try {
+            await rm(partPath, { force: true });
+        }
+        catch {
+            // Cleanup failing (e.g. EACCES, EBUSY, a full disk on unlink) must not
+            // replace the original error -- that original is the whole reason
+            // this function exists: the network drop or truncation that explains
+            // why the model is missing. A user seeing an unlink error instead
+            // would have no idea their download actually died.
+        }
+        throw error;
+    }
+}

package/dist/provision/llamaInstall.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The llama.cpp build ailoud installs. Pinned, never "latest", for the same
+ * reason the whisper.cpp and sherpa-onnx pins exist: two people running the
+ * same `ailoud setup` a week apart must get the same binary, and an upstream
+ * change must not be able to break installation for everyone at once.
+ */
+export declare const LLAMA_VERSION = "b10712";
+/**
+ * The prebuilt archive for this platform and CPU.
+ *
+ * Every target ailoud supports is published here -- macOS on both
+ * architectures, Ubuntu on both -- which is a happier position than the
+ * diarizer, where generic Linux arm64 simply does not exist.
+ */
+export declare function llamaTarballUrl(platform: NodeJS.Platform, arch: string): string;
+export interface InstallLlamaOptions {
+    readonly platform: NodeJS.Platform;
+    readonly arch: string;
+    readonly dataDir: string;
+    readonly interactive: boolean;
+    readonly useBrew: boolean;
+    readonly onProgress?: (received: number, total: number | null) => void;
+}
+export interface InstallLlamaResult {
+    /** Absolute path to llama-cli, or null when brew put it on PATH. */
+    readonly binary: string | null;
+    /** True when the install was skipped because there was no terminal for it. */
+    readonly skipped: boolean;
+}
+/**
+ * Installs llama.cpp and reports where its binary ended up.
+ *
+ * `binary: null` after a brew install, for the same reason the whisper
+ * installer returns null there: brew puts llama-cli on PATH where the config
+ * default already finds it, and writing an absolute Cellar path into the
+ * user's config would break on their next `brew upgrade`.
+ */
+export declare function installLlama(options: InstallLlamaOptions): Promise<InstallLlamaResult>;

package/dist/provision/llamaInstall.js

@@ -0,0 +1,75 @@
+import { mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { FailureError } from '@ailoud/core';
+import { run, runInteractive } from '../process/run.js';
+import { downloadFile } from './download.js';
+/**
+ * The llama.cpp build ailoud installs. Pinned, never "latest", for the same
+ * reason the whisper.cpp and sherpa-onnx pins exist: two people running the
+ * same `ailoud setup` a week apart must get the same binary, and an upstream
+ * change must not be able to break installation for everyone at once.
+ */
+export const LLAMA_VERSION = 'b10712';
+const RELEASES = 'https://github.com/ggml-org/llama.cpp/releases/download';
+/**
+ * The prebuilt archive for this platform and CPU.
+ *
+ * Every target ailoud supports is published here -- macOS on both
+ * architectures, Ubuntu on both -- which is a happier position than the
+ * diarizer, where generic Linux arm64 simply does not exist.
+ */
+export function llamaTarballUrl(platform, arch) {
+    const target = platform === 'darwin' && (arch === 'arm64' || arch === 'x64')
+        ? `macos-${arch}`
+        : platform === 'linux' && (arch === 'arm64' || arch === 'x64')
+            ? `ubuntu-${arch}`
+            : null;
+    if (target === null) {
+        throw new FailureError(`no prebuilt llama.cpp is published for ${platform} ${arch}; build it from source and set ` +
+            '"llm.llamaCpp.binary" to the resulting llama-cli, or set "llm.provider" to a hosted ' +
+            'model instead');
+    }
+    return `${RELEASES}/${LLAMA_VERSION}/llama-${LLAMA_VERSION}-bin-${target}.tar.gz`;
+}
+/**
+ * Installs llama.cpp and reports where its binary ended up.
+ *
+ * `binary: null` after a brew install, for the same reason the whisper
+ * installer returns null there: brew puts llama-cli on PATH where the config
+ * default already finds it, and writing an absolute Cellar path into the
+ * user's config would break on their next `brew upgrade`.
+ */
+export async function installLlama(options) {
+    const { platform, arch, dataDir } = options;
+    if (options.useBrew) {
+        if (!options.interactive) {
+            // brew can stop to ask about Xcode tools or directory ownership, and
+            // there is no terminal here to answer on. runInteractive has no timeout
+            // by design, so this would hang rather than fail.
+            return { binary: null, skipped: true };
+        }
+        const code = await runInteractive('brew', ['install', 'llama.cpp']);
+        if (code !== 0)
+            throw new FailureError(`"brew install llama.cpp" exited with code ${code}`);
+        return { binary: null, skipped: false };
+    }
+    const url = llamaTarballUrl(platform, arch);
+    const root = join(dataDir, 'llama', LLAMA_VERSION);
+    const archive = join(dataDir, 'llama', `llama-${LLAMA_VERSION}-${arch}.tar.gz`);
+    await mkdir(root, { recursive: true });
+    await downloadFile(url, archive, {
+        ...(options.onProgress === undefined ? {} : { onProgress: options.onProgress }),
+    });
+    // .tar.gz here, unlike sherpa's .tar.bz2: -xzf, not -xjf.
+    const extract = await run('tar', ['-xzf', archive, '-C', root, '--strip-components=1']);
+    if (extract.code !== 0) {
+        throw new FailureError(`extracting ${archive} failed: ${extract.stderr.trim()}`);
+    }
+    await rm(archive, { force: true });
+    // Verified against the real archive rather than assumed: it holds a single
+    // top-level directory with llama-cli sitting directly inside it, beside the
+    // shared libraries it loads. So --strip-components=1 lands the binary at
+    // the root, and the tree must stay intact -- moving the binary out would
+    // leave its libraries behind.
+    return { binary: join(root, 'llama-cli'), skipped: false };
+}

package/dist/provision/packageManager.d.ts

@@ -0,0 +1,50 @@
+export type PackageManager = 'brew' | 'apt-get';
+export interface InstallCommand {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly needsSudo: boolean;
+    /**
+     * A non-zero exit from this step is reported but does not abandon the
+     * steps after it. `apt-get update` is the case this exists for: refreshing
+     * the package lists can fail on one unreachable third-party repository
+     * while the install that follows still succeeds from the repositories that
+     * did refresh, so treating it as fatal would block an install that works.
+     */
+    readonly optional?: boolean;
+}
+/** The exact command line, as it must appear in the consent plan and in logs. */
+export declare function formatInstallCommand(command: InstallCommand): string;
+/** Injected in tests; in production it asks the real filesystem via the real PATH. */
+export type BinaryProbe = (name: string) => Promise<boolean>;
+/**
+ * Which package manager ailoud may drive on this platform, or null.
+ *
+ * Only the managers this project has verified are listed: brew on macOS,
+ * apt-get on Debian and Ubuntu. Adding dnf or pacman is a one-line change
+ * plus a verification pass on that distribution -- guessing at their flags
+ * from memory is how an installer breaks somebody's machine.
+ */
+export declare function detectPackageManager(platform: NodeJS.Platform, probe?: BinaryProbe): Promise<PackageManager | null>;
+/**
+ * The exact commands ailoud would run to install ffmpeg, in order.
+ *
+ * A list rather than a single command because apt needs two: on a
+ * container-fresh Debian or Ubuntu `/var/lib/apt/lists` is empty, and
+ * `apt-get install` there exits 100 with nothing a user could act on. The
+ * refresh is part of the install, and being a separate command means it
+ * also appears verbatim in the consent plan -- ailoud never runs a command
+ * the user did not read first.
+ *
+ * brew deliberately refuses to run under sudo, and apt-get requires it.
+ * `needsSudo` is surfaced so the caller can warn before a password prompt
+ * appears, and can skip the action entirely when there is no terminal to
+ * type a password into.
+ */
+export declare function ffmpegInstallCommands(manager: PackageManager): readonly InstallCommand[];
+/**
+ * The exact commands ailoud would run to install whisper.cpp through a package
+ * manager, which is only ever brew: there is no apt package for whisper.cpp,
+ * so on Linux ailoud downloads the project's own prebuilt release tarball
+ * instead and this list is empty.
+ */
+export declare function whisperInstallCommands(manager: PackageManager): readonly InstallCommand[];

package/dist/provision/packageManager.js

@@ -0,0 +1,66 @@
+import { run } from '../process/run.js';
+/** The exact command line, as it must appear in the consent plan and in logs. */
+export function formatInstallCommand(command) {
+    return [command.command, ...command.args].join(' ');
+}
+const realProbe = async (name) => {
+    try {
+        const result = await run(name, ['--version'], { timeoutMs: 10_000 });
+        return result.code === 0;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Which package manager ailoud may drive on this platform, or null.
+ *
+ * Only the managers this project has verified are listed: brew on macOS,
+ * apt-get on Debian and Ubuntu. Adding dnf or pacman is a one-line change
+ * plus a verification pass on that distribution -- guessing at their flags
+ * from memory is how an installer breaks somebody's machine.
+ */
+export async function detectPackageManager(platform, probe = realProbe) {
+    const candidates = platform === 'darwin' ? ['brew'] : platform === 'linux' ? ['apt-get'] : [];
+    for (const candidate of candidates) {
+        if (await probe(candidate))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * The exact commands ailoud would run to install ffmpeg, in order.
+ *
+ * A list rather than a single command because apt needs two: on a
+ * container-fresh Debian or Ubuntu `/var/lib/apt/lists` is empty, and
+ * `apt-get install` there exits 100 with nothing a user could act on. The
+ * refresh is part of the install, and being a separate command means it
+ * also appears verbatim in the consent plan -- ailoud never runs a command
+ * the user did not read first.
+ *
+ * brew deliberately refuses to run under sudo, and apt-get requires it.
+ * `needsSudo` is surfaced so the caller can warn before a password prompt
+ * appears, and can skip the action entirely when there is no terminal to
+ * type a password into.
+ */
+export function ffmpegInstallCommands(manager) {
+    if (manager === 'brew') {
+        return [{ command: 'brew', args: ['install', 'ffmpeg'], needsSudo: false }];
+    }
+    return [
+        { command: 'sudo', args: ['apt-get', 'update'], needsSudo: true, optional: true },
+        { command: 'sudo', args: ['apt-get', 'install', '-y', 'ffmpeg'], needsSudo: true },
+    ];
+}
+/**
+ * The exact commands ailoud would run to install whisper.cpp through a package
+ * manager, which is only ever brew: there is no apt package for whisper.cpp,
+ * so on Linux ailoud downloads the project's own prebuilt release tarball
+ * instead and this list is empty.
+ */
+export function whisperInstallCommands(manager) {
+    if (manager === 'brew') {
+        return [{ command: 'brew', args: ['install', 'whisper-cpp'], needsSudo: false }];
+    }
+    return [];
+}

package/dist/provision/sherpaInstall.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The sherpa-onnx release ailoud installs. Pinned, never "latest": two people
+ * running `ailoud setup` a week apart must get the same binary, and an
+ * upstream change must not be able to break installation for everyone at
+ * once. Bumping this is a reviewable commit.
+ */
+export declare const SHERPA_VERSION = "v1.13.6";
+/**
+ * The prebuilt tarball for this platform and CPU.
+ *
+ * Only macOS arm64 and Linux x64 are covered: those are the two generic
+ * shared-library builds this release publishes. Linux arm64 has no
+ * equivalent -- the only aarch64 assets in this release are vendor NPU
+ * builds (axcl, axera, rknn) that do not run on an ordinary ARM machine, so
+ * that target is refused rather than handed a binary that cannot execute.
+ */
+export declare function sherpaTarballUrl(platform: NodeJS.Platform, arch: string): string;
+export interface InstallSherpaOptions {
+    readonly platform: NodeJS.Platform;
+    readonly arch: string;
+    readonly dataDir: string;
+    readonly onProgress?: (received: number, total: number | null) => void;
+}
+/**
+ * Installs the sherpa-onnx diarizer and returns the absolute path to its
+ * binary.
+ *
+ * The extracted tree is kept intact, exactly like the whisper.cpp tree in
+ * whisperInstall.ts: the binary is invoked by absolute path from inside
+ * `<dataDir>/sherpa/<SHERPA_VERSION>/`, not copied or symlinked elsewhere,
+ * because it ran correctly during the design spike only when left next to
+ * whatever else the archive placed alongside it.
+ */
+export declare function installSherpa(options: InstallSherpaOptions): Promise<string>;

package/dist/provision/sherpaInstall.js

@@ -0,0 +1,78 @@
+import { mkdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { FailureError } from '@ailoud/core';
+import { run } from '../process/run.js';
+import { downloadFile } from './download.js';
+/**
+ * The sherpa-onnx release ailoud installs. Pinned, never "latest": two people
+ * running `ailoud setup` a week apart must get the same binary, and an
+ * upstream change must not be able to break installation for everyone at
+ * once. Bumping this is a reviewable commit.
+ */
+export const SHERPA_VERSION = 'v1.13.6';
+const RELEASES = 'https://github.com/k2-fsa/sherpa-onnx/releases/download';
+/**
+ * The prebuilt tarball for this platform and CPU.
+ *
+ * Only macOS arm64 and Linux x64 are covered: those are the two generic
+ * shared-library builds this release publishes. Linux arm64 has no
+ * equivalent -- the only aarch64 assets in this release are vendor NPU
+ * builds (axcl, axera, rknn) that do not run on an ordinary ARM machine, so
+ * that target is refused rather than handed a binary that cannot execute.
+ */
+export function sherpaTarballUrl(platform, arch) {
+    if (platform === 'darwin') {
+        if (arch !== 'arm64') {
+            // Name the way out, not just the obstacle: this release has no Intel
+            // Mac asset at all, so the only route is building from source.
+            throw new FailureError(`no prebuilt sherpa-onnx diarizer is published for macOS ${arch}; only macOS arm64 is ` +
+                'packaged in this release. Build sherpa-onnx from source for this CPU and set ' +
+                '"stt.diarization.binary" to the resulting sherpa-onnx-offline-speaker-diarization ' +
+                'binary');
+        }
+        return `${RELEASES}/${SHERPA_VERSION}/sherpa-onnx-${SHERPA_VERSION}-onnxruntime-1.24.4-osx-arm64-shared.tar.bz2`;
+    }
+    if (platform === 'linux') {
+        if (arch !== 'x64') {
+            // Name the way out, not just the obstacle: a user on Linux arm64 has
+            // no automated route at all (see the vendor-NPU note above) and needs
+            // to know building from source is the supported answer, plus which
+            // config key to point at the result.
+            throw new FailureError(`no usable sherpa-onnx diarizer is published for Linux ${arch}; the only aarch64 ` +
+                'assets in this release are vendor NPU builds that do not run on a generic ARM ' +
+                'machine. Build sherpa-onnx from source for this CPU and set "stt.diarization.binary" ' +
+                'to the resulting sherpa-onnx-offline-speaker-diarization binary');
+        }
+        return `${RELEASES}/${SHERPA_VERSION}/sherpa-onnx-${SHERPA_VERSION}-linux-x64-shared.tar.bz2`;
+    }
+    throw new FailureError(`no prebuilt sherpa-onnx diarizer is published for ${platform}; build sherpa-onnx from ` +
+        'source and set "stt.diarization.binary" to the resulting ' +
+        'sherpa-onnx-offline-speaker-diarization binary');
+}
+/**
+ * Installs the sherpa-onnx diarizer and returns the absolute path to its
+ * binary.
+ *
+ * The extracted tree is kept intact, exactly like the whisper.cpp tree in
+ * whisperInstall.ts: the binary is invoked by absolute path from inside
+ * `<dataDir>/sherpa/<SHERPA_VERSION>/`, not copied or symlinked elsewhere,
+ * because it ran correctly during the design spike only when left next to
+ * whatever else the archive placed alongside it.
+ */
+export async function installSherpa(options) {
+    const { platform, arch, dataDir } = options;
+    const url = sherpaTarballUrl(platform, arch);
+    const root = join(dataDir, 'sherpa', SHERPA_VERSION);
+    const archive = join(dataDir, 'sherpa', `sherpa-${SHERPA_VERSION}-${platform}-${arch}.tar.bz2`);
+    await mkdir(root, { recursive: true });
+    await downloadFile(url, archive, { onProgress: options.onProgress });
+    // --strip-components=1 drops the "sherpa-onnx-<version>-.../" wrapper so
+    // `bin/`, `lib/`, etc. land directly in `root`. The archive is .tar.bz2,
+    // not .tar.gz -- the flag is -xjf, not -xzf.
+    const extract = await run('tar', ['-xjf', archive, '-C', root, '--strip-components=1']);
+    if (extract.code !== 0) {
+        throw new FailureError(`extracting ${archive} failed: ${extract.stderr.trim()}`);
+    }
+    await rm(archive, { force: true });
+    return join(root, 'bin', 'sherpa-onnx-offline-speaker-diarization');
+}