import type { Paths } from "./paths.js"; import { type ToolExecResult } from "./tools.js"; export declare const DEFAULT_REGISTRY = "https://registry.npmjs.org"; /** How long the registry's answer stands; after that the next command asks again, in the background. */ export declare const UPDATE_CHECK_INTERVAL_MS: number; export declare const UPDATE_CACHE_FILENAME = "update-check.json"; export declare const UPDATE_LOCK_FILENAME = "update.lock"; /** In `/logs`: the package manager's output from the last background install. */ export declare const UPDATE_LOG_FILENAME = "update.log"; export declare const RELEASES_URL = "https://github.com/MeterApp/skillhook/releases"; /** A background install of one version that failed is tried again after a day; `skillhook update --install` tries now. */ export declare const AUTO_INSTALL_RETRY_MS: number; /** An update lock older than this was left by a process that died. */ export declare const UPDATE_LOCK_STALE_MS: number; export declare const INSTALL_TIMEOUT_MS: number; /** `/update-check.json`: what the registry said last time, so most commands never wait for the network. */ export interface UpdateCache { checked_at: string; latest: string | null; /** The version that ran the check; a cache written by another version is ignored. */ current: string; /** Kept across versions, so the version it installed can say so once. */ last_install?: InstallRecord; } /** The last install skillhook ran itself: in the background (`auto_update`) or for `skillhook update --install`. */ export interface InstallRecord { version: string; /** The version that installed it. */ from: string; at: string; ok: boolean; /** One line; the package manager's output is in `/logs/update.log`. */ error?: string; /** A person has been told (at a terminal, or by `update --install` itself). */ announced?: boolean; } export interface UpdateStatus { current: string; /** Newest version on the registry, or null when unknown (never checked, offline, disabled). */ latest: string | null; available: boolean; checked_at: string | null; /** The check was skipped because of the environment or `update_check: false`. */ disabled: boolean; /** The answer comes from the cache file rather than a fresh request. */ cached: boolean; } interface ParsedVersion { major: number; minor: number; patch: number; prerelease: (string | number)[]; } export declare function parseVersion(text: string): ParsedVersion | null; /** Semantic-version ordering; build metadata is ignored and unparseable strings sort lowest. */ export declare function compareVersions(a: string, b: string): -1 | 0 | 1; export declare function isNewerVersion(candidate: string, current?: string): boolean; /** `SKILLHOOK_NO_UPDATE_CHECK=1`, the conventional `NO_UPDATE_NOTIFIER=1`, `CI`, or `"update_check": false` in skillhook.json. */ export declare function updateChecksDisabled(env?: NodeJS.ProcessEnv, config?: { update_check?: boolean; }): boolean; /** `"auto_update": false` in skillhook.json keeps the check and the notices but installs nothing by itself. */ export declare function autoUpdateEnabled(config?: { auto_update?: boolean; }): boolean; /** `SKILLHOOK_NPM_REGISTRY` for mirrors and tests; otherwise the public registry. */ export declare function registryUrl(env?: NodeJS.ProcessEnv): string; export interface FetchLatestOptions { registry?: string; name?: string; timeoutMs?: number; signal?: AbortSignal; fetchImpl?: typeof fetch; } /** The registry's `latest` dist-tag, or null on any problem (offline, 404, timeout, garbage). Never throws. */ export declare function fetchLatestVersion(options?: FetchLatestOptions): Promise; export declare function updateCacheFile(paths: Paths): string; export declare function readUpdateCache(paths: Paths): UpdateCache | undefined; /** The last install skillhook ran itself, whichever version wrote the cache. */ export declare function lastInstall(paths: Paths): InstallRecord | undefined; /** Records an install in the cache (merged: the registry's answer stays). */ export declare function recordInstall(paths: Paths, record: InstallRecord): void; /** Marks the last install as told, so the "updated itself" line shows once. */ export declare function markInstallAnnounced(paths: Paths): void; /** True when the last install tried `version` recently enough that the background update should not try it again yet. */ export declare function attemptedRecently(record: InstallRecord | undefined, version: string, now?: number): boolean; /** What the last check found, without touching the network. */ export declare function updateStatusFromCache(paths: Paths): UpdateStatus; export interface CheckForUpdateOptions { env?: NodeJS.ProcessEnv; config?: { update_check?: boolean; }; /** Ask the registry even when the cached answer is fresh or checks are disabled. */ force?: boolean; timeoutMs?: number; signal?: AbortSignal; fetchImpl?: typeof fetch; now?: number; } /** * Cached for 24 hours in `/update-check.json`. A lookup that fails keeps the previous answer and is not retried * before the next interval, so an offline machine does not pay for the check on every command. */ export declare function checkForUpdate(paths: Paths, options?: CheckForUpdateOptions): Promise; export type InstallMethod = "npm" | "pnpm" | "yarn" | "bun" | "volta" | "npx" | "project" | "source"; export interface InstallInfo { method: InstallMethod; /** argv that upgrades this install; absent when the user has to do it by hand (source checkout, npx cache, a project's dependency). */ command?: string[]; /** The same as one line for humans. */ display: string; /** Why skillhook cannot run `command` itself: the global directory is not writable by this user. */ blocked?: string; } export interface DetectInstallOptions { platform?: NodeJS.Platform; /** The Node binary running skillhook: the npm beside it installs into the same prefix. */ execPath?: string; exists?: (file: string) => boolean; writable?: (dir: string) => boolean; } /** * Guesses how skillhook was installed from where this file lives, so an upgrade goes through the same package manager * into the same place: a global npm install (`/lib/node_modules`, `/node_modules` on Windows, with the * `skillhook` command beside it; installed again with `--prefix`), pnpm, bun, yarn or Volta, an npx cache, a project's * dependency or a git checkout. */ export declare function detectInstall(modulePath?: string, version?: string, options?: DetectInstallOptions): InstallInfo; export declare function releaseNotesUrl(version: string): string; /** Three lines for stderr: what is new, how to get it, where to read about it. */ export declare function formatUpdateNotice(status: UpdateStatus, install?: InstallInfo): string; export interface ApplyUpdateOptions { env?: NodeJS.ProcessEnv; /** Run the package manager that installed skillhook (only when a newer version exists). */ install?: boolean; /** After an install, restart the background service when it runs and has no jobs in progress (default true; the server's own route passes false). */ restartService?: boolean; timeoutMs?: number; fetchImpl?: typeof fetch; /** Injectable for tests. */ runInstall?: (target: InstallInfo) => Promise<{ code: number; stdout: string; stderr: string; }>; } export interface ApplyUpdateResult { ok: boolean; current: string; latest: string | null; available: boolean; checked_at: string | null; registry: string; cached: boolean; install: { method: InstallInfo["method"]; command: string; }; release_notes: string | null; installed: boolean; service_restarted: boolean; service_note: string | null; /** Why nothing could be installed (the registry did not answer, a source checkout, the package manager failed). */ error?: string; } /** The update check and, when asked, the upgrade: what `skillhook update`, `POST /update` and the MCP tool `check_update` share. */ export declare function applyUpdate(paths: Paths, options?: ApplyUpdateOptions): Promise; export interface UpdateNoticePlan { /** The cache is older than the interval. */ stale: boolean; /** Start `skillhook update --refresh` in the background: the cache is stale, or a newer version waits to be installed. */ refresh: boolean; /** At a terminal, after the command: a newer version skillhook will not install by itself (npx, a checkout, a project's copy, a directory this user cannot write, `auto_update: false`, a failed install). */ notice?: string; /** At a terminal, once: the background update installed the version now running. */ announce?: string; } /** * What a command does about updates, from the cache alone (no network): whether to start the background update, and * what to tell a person at a terminal afterwards. A newer version the background update installs needs no word until * it is the one running. */ export declare function planUpdateNotice(paths: Paths, options?: { env?: NodeJS.ProcessEnv; config?: { update_check?: boolean; auto_update?: boolean; }; now?: number; install?: InstallInfo; }): UpdateNoticePlan; /** * Starts `skillhook update --refresh` detached: the registry check and, with `auto_update` on, the install (see * `runBackgroundUpdate`), so the command that asked never waits for either. Returns false when there is nothing to run * (source checkout) or nowhere to write. */ export declare function spawnBackgroundRefresh(paths: Paths, env?: NodeJS.ProcessEnv, cliPath?: string | undefined): boolean; /** One background update at a time: `/update.lock`, created exclusively; a lock left by a process that died is broken. */ export declare function acquireUpdateLock(paths: Paths, now?: number): boolean; export declare function releaseUpdateLock(paths: Paths): void; /** Runs the install with its output in `logFile` (truncated each time); resolves with the exit code, never throws. */ export declare function runInstallLogged(target: InstallInfo, logFile: string, timeoutMs?: number): Promise<{ code: number; error?: string; }>; export interface BackgroundUpdateOptions { env?: NodeJS.ProcessEnv; /** skillhook.json as written (`update_check`, `auto_update`). */ config?: { update_check?: boolean; auto_update?: boolean; }; now?: number; timeoutMs?: number; fetchImpl?: typeof fetch; /** Injectable for tests. */ target?: InstallInfo; install?: (target: InstallInfo) => Promise<{ code: number; error?: string; }>; } /** * What `skillhook update --refresh` does (commands and `serve` start it detached): ask the registry and, with * `auto_update` on, install a newer version with the package manager that installed this one. The next command runs it; * the background service restarts itself onto it once no job is running (`serve`). Only a version the registry has * just named is installed, one update runs at a time, and a version that failed is tried again after a day. */ export declare function runBackgroundUpdate(paths: Paths, options?: BackgroundUpdateOptions): Promise; /** The version installed on disk now, which a running server may not be (it read its package.json when it started). */ export declare function installedVersion(file?: string | URL): string | undefined; export type InstalledConfigCheck = /** The installed version loaded this home's skillhook.json. */ { ok: true; } /** The installed version exited non-zero on this home's skillhook.json: restarting onto it would crash-loop. */ | { ok: false; error: string; } /** The check could not run (spawn error or timeout): nothing is known, so callers keep the previous behaviour. */ | { ok: undefined; error: string; }; /** * Asks the skillhook installed on disk whether it accepts this home's config before a running server restarts onto it * (a new version can reject keys the running one accepted; 0.16.0 rejected `accounts.*.usage_login` and launchd * restarted the daemon 128 times). Runs ` config show --json` with this home in SKILLHOOK_HOME. */ export declare function installedAcceptsConfig(paths: Pick, options?: { cli?: string; execPath?: string; args?: string[]; env?: NodeJS.ProcessEnv; timeoutMs?: number; }): Promise; export interface PluginRefresh { host: "Claude Code" | "Codex"; /** `skillhook@` */ id: string; ok: boolean; detail: string; } export interface RefreshPluginsOptions { /** The commands skillhook runs them with (`runners.claude.command`, `runners.codex.command`). */ claude: string | string[]; codex: string | string[]; /** The environment to run them with; its PATH decides what is found. */ env: Record; plugin?: string; /** Injectable for tests. */ exec?: (command: string, args: string[], timeoutMs: number) => Promise; } /** * What `skillhook update --install` does for the plugin: wherever Claude Code has it installed, refresh that * marketplace and update the plugin (`claude plugin marketplace update`, `claude plugin update`); wherever Codex has it, * refresh the marketplace snapshot (`codex plugin marketplace upgrade`). A host that is missing, or does not have the * plugin, is skipped without a word. */ export declare function refreshPlugins(options: RefreshPluginsOptions): Promise; export {};