jeopi-utils 16.2.14 → 16.2.17

package/dist/types/abortable.d.ts

@@ -0,0 +1,32 @@
+export declare class AbortError extends Error {
+    constructor(signal: AbortSignal);
+}
+/**
+ * Abortable async iteration over a {@link ReadableStream}. Reads the source
+ * reader directly and yields each chunk, so the consumer's `for await` drives a
+ * single read loop with no intermediate stream or per-chunk enqueue.
+ *
+ * Unlike `stream.pipeThrough(..., { signal })`, this explicitly cancels the
+ * source reader on abort or early `break`, propagating HTTP-client disconnects
+ * and watchdog timeouts to the backend request instead of only stopping the
+ * local consumer. On abort it throws {@link AbortError}; the lock is released
+ * on completion, abort, throw, or early exit. The source is cancelled only on
+ * abort or early exit — never on natural EOF.
+ */
+export declare function abortableSource<T>(stream: ReadableStream<T>, signal?: AbortSignal): AsyncGenerator<T>;
+/**
+ * Runs a promise-returning function (`pr`). If the given AbortSignal is aborted before or during
+ * execution, the promise is rejected with a standard error.
+ *
+ * @param signal - Optional AbortSignal to cancel the operation
+ * @param pr - Function returning a promise to run
+ * @returns Promise resolving as `pr` would, or rejecting on abort
+ */
+export declare function untilAborted<T>(signal: AbortSignal | undefined | null, pr: Promise<T> | (() => Promise<T>)): Promise<T>;
+/**
+ * Memoizes a function with no arguments, calling it once and caching the result.
+ *
+ * @param fn - Function to be called once
+ * @returns A function that returns the cached result of `fn`
+ */
+export declare function once<T>(fn: () => T): () => T;

package/dist/types/async.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Wrap a promise with a timeout and optional abort signal.
+ * Rejects with the given message if the timeout fires first.
+ * Cleans up all listeners on settlement.
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, message: string, signal?: AbortSignal): Promise<T>;

package/dist/types/binary.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Classify an in-memory byte header as binary (non-UTF-8-text).
+ *
+ * Binary when the header contains a NUL byte (true binary, plus UTF-16/UTF-32
+ * text whose ASCII range is NUL-padded) or when it is not valid UTF-8. The
+ * decode runs in streaming mode so a multibyte sequence truncated at the header
+ * boundary is tolerated, while any genuinely invalid byte still fails — matching
+ * the strict `fatal` decode the `local://`/`ssh://` read paths already use.
+ */
+export declare function isProbablyBinaryHeader(header: Uint8Array): boolean;
+/**
+ * Sniff the first {@link BINARY_SNIFF_BYTES} of `filePath` and report whether it
+ * is binary (non-UTF-8-text). See {@link isProbablyBinaryHeader} for the rule.
+ */
+export declare function isProbablyBinary(filePath: string, maxBytes?: number): Promise<boolean>;
+/** Synchronous {@link isProbablyBinary}. */
+export declare function isProbablyBinarySync(filePath: string, maxBytes?: number): boolean;

package/dist/types/cli.d.ts

@@ -0,0 +1,117 @@
+export interface FlagDescriptor<K extends "string" | "boolean" | "integer" = "string" | "boolean" | "integer"> {
+    kind: K;
+    description?: string;
+    char?: string;
+    default?: unknown;
+    multiple?: boolean;
+    options?: readonly string[];
+    required?: boolean;
+}
+export interface ArgDescriptor {
+    kind: "string";
+    description?: string;
+    required?: boolean;
+    multiple?: boolean;
+    options?: readonly string[];
+}
+interface FlagInput {
+    description?: string;
+    char?: string;
+    default?: unknown;
+    multiple?: boolean;
+    options?: readonly string[];
+    required?: boolean;
+}
+interface ArgInput {
+    description?: string;
+    required?: boolean;
+    multiple?: boolean;
+    options?: readonly string[];
+}
+/** Builders that match the `Flags.*()` / `Args.*()` API from oclif. */
+export declare const Flags: {
+    string<T extends FlagInput>(opts?: T): FlagDescriptor<"string"> & T;
+    boolean<T extends FlagInput>(opts?: T): FlagDescriptor<"boolean"> & T;
+    integer<T extends FlagInput & {
+        default?: number;
+    }>(opts?: T): FlagDescriptor<"integer"> & T;
+};
+export declare const Args: {
+    string<T extends ArgInput>(opts?: T): ArgDescriptor & T;
+};
+type FlagValue<D extends FlagDescriptor> = D["kind"] extends "boolean" ? D extends {
+    default: boolean;
+} ? boolean : boolean | undefined : D["kind"] extends "integer" ? D extends {
+    default: number;
+} ? number : number | undefined : D extends {
+    multiple: true;
+} ? string[] | undefined : string | undefined;
+type ArgValue<D extends ArgDescriptor> = D extends {
+    multiple: true;
+} ? string[] | undefined : string | undefined;
+type FlagValues<T extends Record<string, FlagDescriptor>> = {
+    [K in keyof T]: FlagValue<T[K]>;
+};
+type ArgValues<T extends Record<string, ArgDescriptor>> = {
+    [K in keyof T]: ArgValue<T[K]>;
+};
+export interface ParseOutput<F extends Record<string, FlagDescriptor> = Record<string, FlagDescriptor>, A extends Record<string, ArgDescriptor> = Record<string, ArgDescriptor>> {
+    flags: FlagValues<F>;
+    args: ArgValues<A>;
+    argv: string[];
+}
+export interface CommandCtor {
+    new (argv: string[], config: CliConfig): Command;
+    description?: string;
+    hidden?: boolean;
+    strict?: boolean;
+    aliases?: string[];
+    examples?: string[];
+    flags?: Record<string, FlagDescriptor>;
+    args?: Record<string, ArgDescriptor>;
+}
+/** Configuration passed to every command instance and help renderers. */
+export interface CliConfig {
+    bin: string;
+    version: string;
+    /** All registered commands keyed by their canonical name. */
+    commands: Map<string, CommandCtor>;
+}
+/** Minimal Command base matching the oclif surface we use. */
+export declare abstract class Command {
+    argv: string[];
+    config: CliConfig;
+    constructor(argv: string[], config: CliConfig);
+    abstract run(): Promise<void>;
+    /**
+     * Parse argv against the static `flags` and `args` declared on the
+     * concrete command class. Returns a typed `{ flags, args, argv }` object.
+     */
+    parse<C extends CommandCtor>(_Cmd: C): Promise<ParseOutput<NonNullable<C["flags"]> extends Record<string, FlagDescriptor> ? NonNullable<C["flags"]> : Record<string, FlagDescriptor>, NonNullable<C["args"]> extends Record<string, ArgDescriptor> ? NonNullable<C["args"]> : Record<string, ArgDescriptor>>>;
+}
+/** Render full root help: header, default command details, subcommand list. */
+export declare function renderRootHelp(config: CliConfig): void;
+/** Render help for a single command. */
+export declare function renderCommandHelp(bin: string, id: string, Cmd: CommandCtor): void;
+/** A lazily-loaded command: canonical name, loader, and optional aliases. */
+export interface CommandEntry {
+    name: string;
+    load: () => Promise<CommandCtor>;
+    aliases?: string[];
+}
+export interface RunOptions {
+    bin: string;
+    version: string;
+    argv: string[];
+    commands: CommandEntry[];
+    /** Custom help renderer. Receives fully-populated config. */
+    help?: (config: CliConfig) => Promise<void> | void;
+}
+/**
+ * Main entry point — replaces `run()` from @oclif/core.
+ *
+ * Each command is explicitly registered with a lazy loader.
+ * No filesystem scanning, no plugin system, no package.json reading.
+ */
+export declare function run(opts: RunOptions): Promise<void>;
+export {};

package/dist/types/color.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Color manipulation utilities for hex colors.
+ *
+ * @example
+ * ```ts
+ * import { hexToHsv, hsvToHex } from "jeopi-utils";
+ *
+ * // Rotate the hue by 90°
+ * const hsv = hexToHsv("#4ade80");
+ * hsv.h = (hsv.h + 90) % 360;
+ * const newHex = hsvToHex(hsv);
+ * ```
+ */
+export interface HSV {
+    /** Hue in degrees (0-360) */
+    h: number;
+    /** Saturation (0-1) */
+    s: number;
+    /** Value/brightness (0-1) */
+    v: number;
+}
+export interface RGB {
+    /** Red (0-255) */
+    r: number;
+    /** Green (0-255) */
+    g: number;
+    /** Blue (0-255) */
+    b: number;
+}
+/**
+ * Parse a hex color string to RGB.
+ * Supports #RGB, #RRGGBB formats.
+ */
+export declare function hexToRgb(hex: string): RGB;
+/**
+ * Convert RGB to hex color string.
+ */
+export declare function rgbToHex(rgb: RGB): string;
+/**
+ * Convert RGB to HSV.
+ */
+export declare function rgbToHsv(rgb: RGB): HSV;
+/**
+ * Convert HSV to RGB.
+ */
+export declare function hsvToRgb(hsv: HSV): RGB;
+/**
+ * Convert hex color to HSV.
+ */
+export declare function hexToHsv(hex: string): HSV;
+/**
+ * Convert HSV to hex color.
+ */
+export declare function hsvToHex(hsv: HSV): string;
+/**
+ * Shift the hue of a hex color by a given number of degrees.
+ */
+export declare function shiftHue(hex: string, degrees: number): string;
+export interface HSVAdjustment {
+    /** Hue shift in degrees (additive) */
+    h?: number;
+    /** Saturation multiplier */
+    s?: number;
+    /** Value/brightness multiplier */
+    v?: number;
+}
+/**
+ * Adjust HSV components of a hex color.
+ *
+ * @param hex - Hex color string (#RGB or #RRGGBB)
+ * @param adj - Adjustments: h is additive degrees, s and v are multipliers
+ * @returns New hex color string
+ *
+ * @example
+ * ```ts
+ * // Shift hue +60°, reduce saturation to 71%
+ * adjustHsv("#00ff88", { h: 60, s: 0.71 }) // "#4a9eff"
+ * ```
+ */
+export declare function adjustHsv(hex: string, adj: HSVAdjustment): string;
+/**
+ * Convert HSL (h: 0-360, s: 0-1, l: 0-1) to a CSS hex string.
+ */
+export declare function hslToHex(h: number, s: number, l: number): string;
+/**
+ * Perceptual luma (gamma-encoded BT.709 weights over raw sRGB), normalized to 0..1.
+ *
+ * Accepts a hex string (`#rgb` / `#rrggbb`) or a 256-color palette index; returns
+ * `undefined` for var refs, empty strings, or anything unparseable.
+ *
+ * Cheap and good enough for a light/dark *classification* threshold. NOT suitable
+ * for contrast ratios — use {@link relativeLuminance} for those.
+ */
+export declare function colorLuma(value: string | number): number | undefined;
+/**
+ * WCAG 2.x relative luminance (BT.709 weights over linearized sRGB), normalized to
+ * 0..1. This is the value the WCAG contrast-ratio formula expects.
+ *
+ * Accepts a hex string (`#rgb` / `#rrggbb`) or a 256-color palette index; returns
+ * `undefined` for var refs, empty strings, or anything unparseable.
+ */
+export declare function relativeLuminance(value: string | number): number | undefined;

package/dist/types/dirs.d.ts

@@ -0,0 +1,289 @@
+/**
+ * Centralized path helpers for jeopi config directories.
+ *
+ * Uses PI_CONFIG_DIR (default ".jeopi") for the config root and
+ * PI_CODING_AGENT_DIR to override the agent directory.
+ *
+ * On Linux, if XDG_DATA_HOME / XDG_STATE_HOME / XDG_CACHE_HOME environment
+ * variables are set, paths are redirected to XDG-compliant locations under
+ * $XDG_*_HOME/jeopi/. This requires running `jeopi config init-xdg` first to
+ * move data to the new locations. No filesystem existence checks are performed
+ * — if the env var is set, jeopi trusts that the migration has been done.
+ */
+/** App name (e.g. "jeopi") */
+export declare const APP_NAME: string;
+/** Config directory name (e.g. ".jeopi") */
+export declare const CONFIG_DIR_NAME: string;
+/** Pre-rebrand config directory name, kept only to detect and migrate unmigrated installs. */
+export declare const LEGACY_CONFIG_DIR_NAME: string;
+/** Version (e.g. "1.0.0") */
+export declare const VERSION: string;
+/** Minimum Bun version */
+export declare const MIN_BUN_VERSION: string;
+/**
+ * Normalize and validate a profile name. Returns `undefined` for the implicit
+ * default (empty string, whitespace, or the explicit "default" sentinel) and
+ * throws for syntactically invalid or platform-reserved names.
+ *
+ * Exported so consumers of `jeopi-utils/dirs` (CLI bootstrap, tests,
+ * downstream tools) can validate user input without re-deriving the rules.
+ */
+export declare function normalizeProfileName(profile: string | undefined): string | undefined;
+/**
+ * Resolve the active profile from the two profile env vars. `JEOPI_PROFILE` is
+ * the canonical variable and takes precedence; `PI_PROFILE` is the legacy
+ * compatibility fallback, consulted only when `JEOPI_PROFILE` is undefined. An
+ * explicitly-empty `JEOPI_PROFILE` therefore selects the default profile rather
+ * than silently inheriting `PI_PROFILE`. Delegates validation/normalization to
+ * {@link normalizeProfileName} (which throws on a syntactically invalid value).
+ */
+export declare function resolveProfileEnv(jeopi: string | undefined, pi: string | undefined): string | undefined;
+export declare function resolveEquivalentPath(inputPath: string): string;
+export declare function normalizePathForComparison(inputPath: string): string;
+export declare function pathIsWithin(root: string, candidate: string): boolean;
+export declare function relativePathWithinRoot(root: string, candidate: string): string | null;
+/** Get the project directory. */
+export declare function getProjectDir(): string;
+/** Set the project directory. */
+export declare function setProjectDir(dir: string): void;
+/**
+ * Whether `dir` resolves to an existing directory. Any stat failure — a deleted
+ * path (ENOENT), permission error, or a non-directory — returns `false`, so
+ * callers can decide whether a directory is safe to `chdir` into or adopt as a
+ * working directory before {@link setProjectDir} throws on it.
+ */
+export declare function directoryExists(dir: string): Promise<boolean>;
+/** Get the config directory name relative to home (e.g. ".jeopi" or PI_CONFIG_DIR override). */
+export declare function getConfigDirName(): string;
+/** Get the config agent directory name relative to home (e.g. ".jeopi/agent" or PI_CONFIG_DIR + "/agent"). */
+export declare function getConfigAgentDirName(): string;
+/**
+ * Rebuild the dirs resolver from the current environment, reusing the profile
+ * resolved at module load. Directory-affecting keys (XDG_*_HOME and, in default
+ * mode, `PI_CODING_AGENT_DIR`) loaded from a profile/agent `.env` only reach
+ * `process.env` *after* this module froze the resolver at import time, so
+ * `env.ts` calls this once after applying its `.env` files. The agent `.env`
+ * location derives from the profile name + home before this runs, so the
+ * rebuild re-reads only the directory vars, never the profile selection. The
+ * `preProfileAgentDirEnv` snapshot is intentionally left untouched.
+ */
+export declare function refreshDirsFromEnv(): void;
+/** Get the config root directory (~/.jeopi). */
+export declare function getConfigRootDir(): string;
+/**
+ * Whether an unmigrated pre-rebrand config directory exists at `~/.omp` while
+ * the new `~/.jeopi` root does not. Read-only — never renames anything. Used
+ * by CLI startup to print a one-time migration hint and by `{APP_NAME} config
+ * migrate-legacy` to decide whether there is anything to do.
+ *
+ * Always `false` when `PI_CONFIG_DIR` is set: an explicit override means the
+ * user already manages their own directory name and the legacy default is
+ * irrelevant.
+ */
+export declare function hasUnmigratedLegacyConfigDir(): boolean;
+/**
+ * Rename `~/.omp` to `~/.jeopi` in place, carrying over auth, sessions,
+ * settings, and every profile in one atomic move. Explicit and opt-in
+ * (`{APP_NAME} config migrate-legacy`) — never invoked automatically at
+ * module load or from {@link DirResolver}, so a running process never renames
+ * a directory another concurrent process might have open.
+ *
+ * Throws if `PI_CONFIG_DIR` is set, if `~/.omp` does not exist, or if
+ * `~/.jeopi` already exists (refuses to clobber). Callers own reporting;
+ * this performs the single `fs.renameSync` and nothing else — no cache
+ * invalidation, since the resolver reads `os.homedir()` fresh on next use.
+ */
+export declare function migrateLegacyConfigDir(): {
+    from: string;
+    to: string;
+};
+/** Set the coding agent directory. Creates a fresh resolver, invalidating all cached paths. */
+export declare function setAgentDir(dir: string): void;
+/**
+ * Test-only: reset the pre-profile `PI_CODING_AGENT_DIR` snapshot to whatever
+ * the current environment looks like. Cross-suite test pollution can otherwise
+ * leak a stale snapshot through `setAgentDir` and corrupt `setProfile(undefined)`
+ * restore semantics. Production code MUST NOT call this — the snapshot's
+ * lifecycle is owned by `setAgentDir` / `setProfile` and a runtime caller has
+ * no business clearing it.
+ */
+export declare function __resetProfileSnapshotForTests(): void;
+/**
+ * Test-only: rebuild profile + directory state from the current process env.
+ * Production code keeps the module-load profile stable; tests that mutate
+ * `setAgentDir`/`setProfile` need an exact restore point after they put env vars
+ * back.
+ */
+export declare function __resetDirsFromEnvForTests(): void;
+/** Activate a named profile. Passing undefined or "default" returns to the default profile. */
+export declare function setProfile(profile: string | undefined): void;
+/** Get the active named profile. Undefined means the default profile. */
+export declare function getActiveProfile(): string | undefined;
+/** Resolve the config root that backs a profile without activating it. */
+export declare function getProfileRootDir(profile: string | undefined): string;
+/** Get the agent config directory (~/.jeopi/agent). */
+export declare function getAgentDir(): string;
+/** Get the project-local config directory (.jeopi). */
+export declare function getProjectAgentDir(cwd?: string): string;
+/** Get the reports directory (~/.jeopi/reports). */
+export declare function getReportsDir(): string;
+/** Get the logs directory (~/.jeopi/logs). */
+export declare function getLogsDir(): string;
+/** Get the path to a dated log file (~/.jeopi/logs/jeopi.YYYY-MM-DD.log). */
+export declare function getLogPath(date?: Date): string;
+/**
+ * Get the plugins directory (~/.jeopi/plugins or its XDG equivalent).
+ *
+ * No-arg form (production callers) goes through the XDG-aware DirResolver so
+ * reads and writes always agree. The optional `home` parameter is for test
+ * isolation: when it differs from `os.homedir()` it short-circuits the resolver
+ * and returns `<home>/<configDir>/plugins` so tests with a temp HOME get a
+ * deterministic path. Passing `os.homedir()` explicitly is identical to the
+ * no-arg form — XDG semantics are preserved.
+ */
+export declare function getPluginsDir(home?: string): string;
+/** Where npm installs packages (~/.jeopi/plugins/node_modules). */
+export declare function getPluginsNodeModules(home?: string): string;
+/** Plugin manifest (~/.jeopi/plugins/package.json). */
+export declare function getPluginsPackageJson(home?: string): string;
+/** Plugin lock file (~/.jeopi/plugins/omp-plugins.lock.json). */
+export declare function getPluginsLockfile(home?: string): string;
+/** Get the remote mount directory (~/.jeopi/remote). */
+export declare function getRemoteDir(): string;
+/**
+ * Relocate the base directory for agent-managed worktrees (PR checkouts, task
+ * isolation, and `jeopi worktree` cleanup all read the same base). Driven by the
+ * `worktree.base` setting in coding-agent; pass `undefined`/empty to clear and
+ * fall back to `JEOPI_WORKTREE_DIR` or the `~/.jeopi/wt` default.
+ *
+ * `~` is expanded and a relative path is rejected (see {@link resolveWorktreeBase}).
+ * Returns the absolute path that took effect, or `undefined` if the input was
+ * cleared or rejected — callers can warn on a non-empty input that returns
+ * `undefined`.
+ */
+export declare function setWorktreesDir(dir: string | undefined): string | undefined;
+/**
+ * Get the agent-managed worktrees directory. Resolution order: the
+ * `JEOPI_WORKTREE_DIR` env var, then the {@link setWorktreesDir} override (the
+ * `worktree.base` setting), then the `~/.jeopi/wt` default. The env var and the
+ * override are both `~`-expanded and must be absolute; a relative value is
+ * ignored and resolution falls through.
+ */
+export declare function getWorktreesDir(): string;
+/** Get the SSH control socket directory (~/.jeopi/ssh-control). */
+export declare function getSshControlDir(): string;
+/** Get the remote host info directory (~/.jeopi/remote-host). */
+export declare function getRemoteHostDir(): string;
+/** Get the managed Python venv directory (~/.jeopi/python-env). */
+export declare function getPythonEnvDir(): string;
+/** Get the shared Python gateway state directory (~/.jeopi/agent/python-gateway; XDG default: $XDG_STATE_HOME/jeopi/python-gateway). */
+export declare function getPythonGatewayDir(): string;
+/** Get the puppeteer sandbox directory (~/.jeopi/puppeteer). */
+export declare function getPuppeteerDir(): string;
+/** Get DOCS_RS cache directory () */
+export declare function getDocsRsCacheDir(): string;
+/**Get AutoQa db directory */
+export declare function getAutoQaDbDir(): string;
+/**
+ * Stable 7-character hex digest of an absolute filesystem path.
+ *
+ * Used to pack the project identity into a single short fs-safe segment
+ * (e.g. PR-checkout and task-isolation worktree dirs under `~/.jeopi/wt/`).
+ * Bun.hash is non-cryptographic — collision space is ~2^28, which is fine
+ * for naming a handful of repos on a single machine. Same input on the
+ * same Bun runtime yields the same output.
+ */
+export declare function hashPath(absPath: string): string;
+/** Get the path to a single worktree directory (~/.jeopi/wt/<segment>). */
+export declare function getWorktreeDir(segment: string): string;
+/** Get the GPU cache path (~/.jeopi/gpu_cache.json). */
+export declare function getGpuCachePath(): string;
+/**
+ * Get the GitHub view cache database path (~/.jeopi/cache/github-cache.db).
+ * Honors the `JEOPI_GITHUB_CACHE_DB` env var when set so tests can isolate the
+ * cache file without touching the rest of the config root.
+ */
+export declare function getGithubCacheDbPath(): string;
+/**
+ * Get the encrypted auth-broker snapshot cache path (~/.jeopi/cache/auth-broker-snapshot.enc).
+ * Honors the `JEOPI_AUTH_BROKER_SNAPSHOT_CACHE` env var when set so tests and
+ * operators can isolate or relocate the cache file.
+ */
+export declare function getAuthBrokerSnapshotCachePath(): string;
+/** Get the local FastEmbed model cache directory (~/.jeopi/cache/fastembed). */
+export declare function getFastembedCacheDir(): string;
+/** Get the on-demand fastembed runtime install root (~/.jeopi/cache/fastembed-runtime). */
+export declare function getFastembedRuntimeDir(): string;
+/** Get the natives directory (~/.jeopi/natives). */
+export declare function getNativesDir(): string;
+/** Get the stats database path (~/.jeopi/stats.db). */
+export declare function getStatsDbPath(): string;
+/** Get the autoresearch state directory (~/.jeopi/autoresearch). */
+export declare function getAutoresearchDir(): string;
+/** Get the per-project autoresearch state directory (~/.jeopi/autoresearch/<encoded-project>). */
+export declare function getAutoresearchProjectDir(encodedProject: string): string;
+/** Get the per-project autoresearch SQLite database path (~/.jeopi/autoresearch/<encoded-project>.db). */
+export declare function getAutoresearchDbPath(encodedProject: string): string;
+/** Get the per-run artifact directory (~/.jeopi/autoresearch/<encoded-project>/runs/<runId>). */
+export declare function getAutoresearchRunDir(encodedProject: string, runId: number): string;
+/** Get the path to agent.db (SQLite database for settings and auth storage). */
+export declare function getAgentDbPath(agentDir?: string): string;
+/** Get the last-seen-changelog-version marker file (~/.jeopi/agent/last-changelog-version). */
+export declare function getLastChangelogVersionPath(agentDir?: string): string;
+/** Get the path to history.db (SQLite database for session history). */
+export declare function getHistoryDbPath(agentDir?: string): string;
+/** Get the path to models.db (model cache database). */
+export declare function getModelDbPath(agentDir?: string): string;
+/** Get the tiny title model cache directory (~/.jeopi/agent/cache/tiny-models). */
+export declare function getTinyModelsCacheDir(agentDir?: string): string;
+/** Get the document conversion cache directory (~/.jeopi/agent/cache/document-conversions; XDG default: $XDG_CACHE_HOME/jeopi/cache/document-conversions). */
+export declare function getDocumentConversionCacheDir(agentDir?: string): string;
+/** Get the sessions directory (~/.jeopi/agent/sessions). */
+export declare function getSessionsDir(agentDir?: string): string;
+/** Get the content-addressed blob store directory (~/.jeopi/agent/blobs). */
+export declare function getBlobsDir(agentDir?: string): string;
+/** Get the custom themes directory (~/.jeopi/agent/themes). */
+export declare function getCustomThemesDir(agentDir?: string): string;
+/** Get the tools directory (~/.jeopi/agent/tools). */
+export declare function getToolsDir(agentDir?: string): string;
+/** Get the slash commands directory (~/.jeopi/agent/commands). */
+export declare function getCommandsDir(agentDir?: string): string;
+/** Get the prompts directory (~/.jeopi/agent/prompts). */
+export declare function getPromptsDir(agentDir?: string): string;
+/** Get the user-level Python modules directory (~/.jeopi/agent/modules). */
+export declare function getAgentModulesDir(agentDir?: string): string;
+/** Get the memories directory (~/.jeopi/agent/memories). */
+export declare function getMemoriesDir(agentDir?: string): string;
+/** Get the terminal sessions directory (~/.jeopi/agent/terminal-sessions). */
+export declare function getTerminalSessionsDir(agentDir?: string): string;
+/** Get the crash log path (~/.jeopi/agent/jeopi-crash.log). */
+export declare function getCrashLogPath(agentDir?: string): string;
+/** Get the debug log path (~/.jeopi/agent/jeopi-debug.log). */
+export declare function getDebugLogPath(agentDir?: string): string;
+/** Get the project-level Python modules directory (.jeopi/modules). */
+export declare function getProjectModulesDir(cwd?: string): string;
+/** Get the project-level prompts directory (.jeopi/prompts). */
+export declare function getProjectPromptsDir(cwd?: string): string;
+/** Get the project-level plugin overrides path (.jeopi/plugin-overrides.json). */
+export declare function getProjectPluginOverridesPath(cwd?: string): string;
+/** Get the primary MCP config file path (first candidate). */
+export declare function getMCPConfigPath(scope: "user" | "project", cwd?: string): string;
+/** Get the SSH config file path. */
+export declare function getSSHConfigPath(scope: "user" | "project", cwd?: string): string;
+/**
+ * Persistent per-install UUID stored at `~/.jeopi/install-id`.
+ *
+ * Generated lazily on first call and persisted with `O_CREAT|O_EXCL` so
+ * concurrent first-call races don't clobber each other (loser re-reads the
+ * winner's id). Survives independently of agent state: deleting
+ * `~/.jeopi/agent/` does not regenerate it. Server-side dedup for grievance
+ * pushes (and similar telemetry) keys on this id.
+ *
+ * Anchored to the base config root (`~/.jeopi/install-id`) regardless of the
+ * active profile: install identity is per-install, not per-profile, so every
+ * profile shares one id and the global cache stays correct no matter the
+ * profile / `getInstallId` call order.
+ */
+export declare function getInstallId(): string;
+/** Test-only: clear cached install id. Never call from production code. */
+export declare function __resetInstallIdCacheForTests(): void;

package/dist/types/env.d.ts

@@ -0,0 +1,74 @@
+export * from "./worker-host";
+/**
+ * Strict shell-identifier shape. Used for dotenv keys we accept into
+ * `Bun.env` — those should be referenceable as `$NAME` from POSIX shells,
+ * so we reject anything outside `[A-Za-z_][A-Za-z0-9_]*`.
+ */
+export declare function isValidEnvName(name: string): boolean;
+/**
+ * The only names that are genuinely unsafe to forward to a native `execve`
+ * spawn: empty, containing `=` (would corrupt the `KEY=VALUE` framing) or
+ * NUL (terminates the C string mid-entry). Windows ships standard variables
+ * whose names contain parentheses (e.g. `ProgramFiles(x86)`, `CommonProgramFiles(x86)`)
+ * — those MUST survive the scrub so downstream resolvers (Git Bash discovery
+ * in `procmgr.ts`, etc.) can still read them.
+ */
+export declare function isSafeEnvName(name: string): boolean;
+export declare function isSafeEnvValue(value: string): boolean;
+export declare function isMacosMallocStackLoggingEnvName(name: string): boolean;
+export declare function filterProcessEnv(env: Record<string, string | undefined>): Record<string, string>;
+/**
+ * Parses a .env file synchronously and extracts key-value string pairs.
+ * Ignores lines that are empty or start with '#'. Trims whitespace.
+ * Allows values to be quoted with single or double quotes.
+ * Returns an object of key-value pairs.
+ */
+export declare function parseEnvFile(filePath: string): Record<string, string>;
+/**
+ * Intentional re-export of Bun.env.
+ *
+ * All users should import this env module (import { $env } from "jeopi-utils")
+ * before using environment variables. This ensures that .env files have been loaded and
+ * overrides (project, home) have been applied, so $env always reflects the correct values.
+ */
+export declare const $env: Record<string, string>;
+/**
+ * Resolve the first environment variable value from the given keys.
+ * @param keys - The keys to resolve.
+ * @returns The first environment variable value, or undefined if no value is found.
+ */
+export declare function $pickenv(...keys: string[]): string | undefined;
+/**
+ * Parses a positive decimal integer from `$env[name]`.
+ * Empty, invalid, NaN, zero, or negative values return `defaultValue`.
+ */
+export declare function $envpos(name: string, defaultValue: number): number;
+/** True when `BUN_ENV` or `NODE_ENV` is the string `test`. */
+export declare function isBunTestRuntime(): boolean;
+/**
+ * True when real-terminal side effects must be suppressed: stdout escape/frame
+ * writes, stdin raw-mode + resume, CSI/OSC capability probes, SIGWINCH, window
+ * title changes, and emergency restore. Defaults to {@link isBunTestRuntime} so
+ * `bun test` launched inside a real TTY never paints the TUI, leaks probe
+ * queries, or hijacks the developer's stdin; production runtimes stay
+ * interactive.
+ *
+ * Terminal-contract tests that must exercise the real I/O path opt out with
+ * `setTerminalHeadless(false)` and restore it afterwards.
+ */
+export declare function isTerminalHeadless(): boolean;
+/**
+ * Override the {@link isTerminalHeadless} default and return the previous value
+ * so callers can restore exact prior state (`const prev = setTerminalHeadless(false); … setTerminalHeadless(prev);`).
+ */
+export declare function setTerminalHeadless(headless: boolean): boolean;
+/**
+ * True when this code is running inside a `bun build --compile` standalone
+ * binary. Detects via the embedded virtual-filesystem path markers
+ * (`$bunfs`, `~BUN`, or its URL-encoded form `%7EBUN`) in `import.meta.url`,
+ * which Bun rewrites for every module bundled into the executable. The
+ * `PI_COMPILED` env var (set by the build script's `--define`) is checked
+ * first for cheap fast-path detection.
+ */
+export declare function isCompiledBinary(): boolean;
+export declare function $flag(name: string, def?: boolean): boolean;