@autorag/librarian 2.10.6 → 2.12.0

package/dist/cli/open-target.d.ts

@@ -0,0 +1,9 @@
+import { spawn } from "node:child_process";
+type SpawnFn = typeof spawn;
+/**
+ * Open what a clicked TUI citation points at. A local file goes to Dazzi
+ * (`dazzi <path>` shows it in its folder); when Dazzi is not installed or
+ * refuses, and for web links, the platform's default opener takes over.
+ */
+export declare function openCitationTarget(url: string, spawnFn?: SpawnFn): void;
+export {};

package/dist/cli/setup.d.ts

@@ -1,3 +1,5 @@
+import { type ResolvedFileeBinary, type ResolveFileeBinaryOptions } from "../convert/index.js";
+import { type HisterServiceDeps, type HisterSetupReport } from "../datasource/skills/hister/setup.js";
 import { type EmbeddingBackend, type ManagedEmbedder } from "../embedding/index.js";
 import { type FileLockHandle } from "../filesystem/file-lock.js";
 export type SetupDatasourceState = "configured" | "skipped" | "blocked";
@@ -15,12 +17,25 @@ export interface SetupEmbeddingReport {
     /** Why no embedding backend is available. */
     readonly reason?: string;
 }
+export type SetupFileeState = "installed" | "cached" | "path" | "configured" | "skipped" | "failed";
+/** The Filee command line behind `convert_files`; setup installs it unless the operator opted out. */
+export interface SetupFileeReport {
+    readonly state: SetupFileeState;
+    readonly path?: string;
+    readonly reason?: string;
+}
 export interface SetupReport {
     readonly ok: boolean;
     readonly mode: "semantic" | "bm25";
     readonly embedding: SetupEmbeddingReport;
     readonly datasources: readonly SetupDatasourceReport[];
     readonly remediation?: string;
+    /** One entry per configured `hister` datasource; absent when none is configured. */
+    readonly hister?: HisterSetupReport;
+    /** Every configured `hister` datasource, when there is more than one. */
+    readonly histers?: readonly HisterSetupReport[];
+    /** Present on every run; `skipped` when `filee.enabled` or `filee.autoInstall` is false. */
+    readonly filee?: SetupFileeReport;
     readonly changed: boolean;
 }
 export interface SetupDeps {
@@ -30,9 +45,15 @@ export interface SetupDeps {
     readonly pathExists?: (path: string) => boolean;
     readonly executable?: (name: string) => string | undefined;
     readonly acquireLock?: (path: string) => FileLockHandle;
+    /** Hister's config path, health, restart and reindex; defaults to the real programs. */
+    readonly hister?: HisterServiceDeps;
+    /** Finds or installs filee-cli; defaults to the pinned release download. */
+    readonly filee?: (options: Pick<ResolveFileeBinaryOptions, "executable" | "autoInstall">) => Promise<ResolvedFileeBinary>;
 }
 export declare function runSetup(options: {
     configPath: string;
     workspacePath: string;
+    /** Write Hister's `semantic_search` to the shared embedding model (and restart/reindex it). Off by default. */
+    syncHister?: boolean;
     deps?: SetupDeps;
 }): Promise<SetupReport>;

package/dist/convert/cli.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Conversions can legitimately take a long time (video transcodes, big PDFs,
+ * HWP → PDF), so the default budget is generous. Callers may lower it per call.
+ */
+export declare const DEFAULT_FILEE_TIMEOUT_MS: number;
+export interface FileeConvertRequest {
+    /** Files, folders or wildcards. Relative paths are resolved against `cwd`. Any location is allowed. */
+    readonly inputs: readonly string[];
+    /** Target format id or extension (`pdf`, `docx`, `webp`, `mp3`, ...). See {@link listFileeFormats}. */
+    readonly to: string;
+    /** Save here instead of next to each source. */
+    readonly outputDir?: string;
+    /** Include sub folders of folder inputs. */
+    readonly recursive?: boolean;
+    /** 1-100, for lossy image formats. */
+    readonly quality?: number;
+    /** Replace an existing output file. Without it (and without `skipExisting`) a number is added to the new name. */
+    readonly overwrite?: boolean;
+    /** Leave an existing output file alone. */
+    readonly skipExisting?: boolean;
+    /** Give the output the modified time of its source. */
+    readonly keepDates?: boolean;
+}
+export interface FileeFileResult {
+    readonly source: string;
+    readonly state: "done" | "skipped" | "failed" | "cancelled" | (string & {});
+    readonly outputs: readonly string[];
+    readonly error?: string;
+    readonly notice?: string;
+}
+export interface FileeConvertResult {
+    readonly preset: string;
+    readonly target: string;
+    readonly converted: number;
+    readonly skipped: number;
+    readonly failed: number;
+    readonly files: readonly FileeFileResult[];
+}
+export interface FileeCliRun {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+}
+export interface FileeCliOptions {
+    /** Path to `filee` (or `filee-cli`). Default: found on PATH. */
+    readonly executable?: string;
+    readonly cwd?: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    /**
+     * Folder for Filee's settings and downloaded engines (`FILEE_DATA_DIR`), so a
+     * run neither reads nor writes the user's own Filee app settings.
+     */
+    readonly dataDir?: string;
+    /** `false` never downloads filee-cli when none is found. Default true. See `resolveFileeOptions`. */
+    readonly autoInstall?: boolean;
+    /** Test seam: replaces the spawn. */
+    readonly run?: (args: readonly string[]) => Promise<FileeCliRun>;
+}
+export declare class FileeCliError extends Error {
+    constructor(message: string);
+}
+/**
+ * Convert files with the `filee` command. Exit 0 (all converted) and 1 (some
+ * failed) both return the per-file report; wrong arguments, an unknown format,
+ * a missing input and "nothing to convert" throw {@link FileeCliError}.
+ */
+export declare function convertWithFilee(request: FileeConvertRequest, options?: FileeCliOptions): Promise<FileeConvertResult>;
+/** `filee formats [format]`: every format, or what one format converts to. */
+export declare function listFileeFormats(format?: string, options?: FileeCliOptions): Promise<string>;
+/**
+ * Find the Filee command line on `PATH`. POSIX installs link it as `filee`
+ * (or leave `filee-cli`). On Windows the PATH entry is the `cli\filee.cmd`
+ * shim, which Node cannot spawn directly; its target is `filee-cli.exe` one
+ * folder up. `filee.exe` is the tray app, never the command line.
+ */
+export declare function resolveFileeExecutable(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string | undefined;

package/dist/convert/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./cli.js";
+export * from "./installer.js";
+export * from "./matrix.js";
+export * from "./relate.js";

package/dist/convert/installer.d.ts

@@ -0,0 +1,84 @@
+import { type FileeCliOptions } from "./cli.js";
+/**
+ * filee-cli is NomaDamas' CLI-only redistribution of KnifeLemon/Filee
+ * (MIT, https://github.com/NomaDamas/filee-cli). It is a self-contained .NET
+ * program that must run as a separate process, so AutoRAG downloads the pinned
+ * release archive, checks its SHA-256, and unpacks it under
+ * `<AUTORAG_HOME>/tools/filee-cli/<version>/`. Nothing is linked or bundled.
+ * Filee's own engines (FFmpeg, Pandoc, LibreOffice, ...) are fetched by
+ * filee-cli itself on first use.
+ */
+export declare const FILEE_CLI_VERSION = "2.0.0-2";
+export interface FileeCliAsset {
+    readonly name: string;
+    readonly url: string;
+    readonly sha256: string;
+}
+/** SHA-256 values come from the release's `SHA256SUMS`. Keyed by `<platform>-<arch>`. */
+export declare const FILEE_CLI_ASSETS: Readonly<Record<string, FileeCliAsset>>;
+export declare class FileeInstallError extends Error {
+    constructor(message: string);
+}
+export declare function selectFileeAsset(platform: NodeJS.Platform, arch: NodeJS.Architecture, assets?: Readonly<Record<string, FileeCliAsset>>): FileeCliAsset;
+export declare function fileeBinaryName(platform?: NodeJS.Platform): string;
+export interface EnsureFileeBinaryOptions {
+    /** AutoRAG home; the install lives at `<home>/tools/filee-cli/<version>/`. Default: the resolved AutoRAG home. */
+    readonly home?: string;
+    readonly platform?: NodeJS.Platform;
+    readonly arch?: NodeJS.Architecture;
+    /** Test seam: pinned assets. */
+    readonly assets?: Readonly<Record<string, FileeCliAsset>>;
+    /** Test seam: fetch `url` into `destination`. */
+    readonly download?: (url: string, destination: string) => Promise<void>;
+    /** Test seam: unpack `archive` into `directory`. */
+    readonly extract?: (archive: string, directory: string) => Promise<void>;
+}
+export interface InstalledFileeBinary {
+    readonly binaryPath: string;
+    readonly source: "installed" | "cached";
+}
+/**
+ * Make sure the pinned filee-cli is unpacked in the AutoRAG home. Idempotent;
+ * concurrent callers in one process share a single install, and concurrent
+ * processes race on an atomic rename (the loser discards its copy).
+ */
+export declare function ensureFileeBinary(options?: EnsureFileeBinaryOptions): Promise<InstalledFileeBinary>;
+export interface ResolveFileeBinaryOptions {
+    readonly home?: string;
+    /** `filee.binaryPath` from config. */
+    readonly executable?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    /** `false` never downloads. Default true. */
+    readonly autoInstall?: boolean;
+    readonly installer?: Omit<EnsureFileeBinaryOptions, "home">;
+}
+export interface ResolvedFileeBinary {
+    readonly path: string;
+    readonly source: "configured" | "path" | "installed" | "cached";
+}
+/**
+ * Where the Filee command line comes from, in order: the configured path, a
+ * `filee`/`filee-cli` on PATH, then the managed copy (installed on demand).
+ */
+export declare function resolveFileeBinary(options?: ResolveFileeBinaryOptions): Promise<ResolvedFileeBinary>;
+/**
+ * Fill in `executable` for a conversion call: the configured path, a PATH
+ * install, or the managed copy (downloaded on first use unless `autoInstall`
+ * is false). Options that already carry a `run` seam are returned unchanged.
+ */
+export declare function resolveFileeOptions(options: FileeCliOptions, deps?: Pick<ResolveFileeBinaryOptions, "home" | "env" | "installer">): Promise<FileeCliOptions>;
+export type WarmFileeOutcome = {
+    readonly state: ResolvedFileeBinary["source"];
+    readonly path: string;
+} | {
+    readonly state: "skipped";
+} | {
+    readonly state: "failed";
+    readonly reason: string;
+};
+/**
+ * Start-of-session prefetch so the first `convert_files` call does not wait for
+ * an 85 MB download. Never throws: a failure here resurfaces, with its reason,
+ * on the first real conversion.
+ */
+export declare function warmFileeBinary(options: FileeCliOptions | false, deps?: Pick<ResolveFileeBinaryOptions, "home" | "env" | "installer">): Promise<WarmFileeOutcome>;

package/dist/convert/matrix.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What `filee-cli` can convert, grouped so the model can plan any conversion
+ * without a tool call. Generated from `filee-cli formats <format>` for every
+ * source format (v2.0.0); `test/live-e2e/filee-matrix.test.ts` re-checks every
+ * claim against the real binary, so a Filee upgrade that changes a route fails
+ * there instead of silently misleading the model.
+ *
+ * A route `source family -> group` means EVERY format in the source family can
+ * become EVERY format in the group (a format never converts to itself). Some
+ * targets need an engine that Filee downloads on first use (LibreOffice, Pandoc,
+ * Ghostscript, FFmpeg, calibre); the guide says so instead of listing them apart.
+ */
+export declare const SOURCE_FAMILIES: Readonly<Record<string, readonly string[]>>;
+export declare const TARGET_GROUPS: Readonly<Record<string, readonly string[]>>;
+export declare const ROUTES: Readonly<Record<string, {
+    readonly groups: readonly string[];
+    readonly formats: readonly string[];
+}>>;
+/** Every format in `family`, or undefined for an unknown family. */
+export declare function familyMembers(family: string): readonly string[] | undefined;
+/** Every target a source family can reach: its groups expanded, plus its single formats. */
+export declare function reachableTargets(family: string): readonly string[];
+/**
+ * Compact conversion guide for the system prompt: families, target groups, the
+ * route table, and the rules that decide whether a chain is needed.
+ */
+export declare function renderConversionGuide(): string;

package/dist/convert/relate.d.ts

@@ -0,0 +1,30 @@
+import { type DupeyCliOptions, type DupeyCompareResult } from "../dupey/index.js";
+import { type FileeCliOptions, type FileeConvertRequest, type FileeConvertResult } from "./cli.js";
+/** What `dupey scan` would say about a converted copy and its source. */
+export type ConvertedCopyRelation = DupeyCompareResult | {
+    readonly relation: "unavailable";
+    readonly reason: string;
+};
+export interface ConvertedCopyLink {
+    readonly source: string;
+    readonly output: string;
+    readonly dupey: ConvertedCopyRelation;
+}
+export interface ConvertAndRelateResult {
+    readonly result: FileeConvertResult;
+    /** One entry per output file written by a successful conversion. Empty when dupey is disabled. */
+    readonly links: readonly ConvertedCopyLink[];
+}
+export interface ConvertAndRelateOptions {
+    readonly filee?: FileeCliOptions;
+    /** `false` skips the duplicate-family check. */
+    readonly dupey?: DupeyCliOptions | false;
+}
+/**
+ * Convert, then ask dupey whether each output is a duplicate-family member of
+ * its source. A converted copy has the same text in another format, which is
+ * exactly what dupey's families describe; the comparison uses dupey's own
+ * thresholds so it agrees with a later `dupey scan` of the directory.
+ * A dupey that cannot run never fails the conversion.
+ */
+export declare function convertAndRelate(request: FileeConvertRequest, options?: ConvertAndRelateOptions): Promise<ConvertAndRelateResult>;