buildhive-agent 1.0.0-beta.12 → 1.0.0-beta.13

package/dist/cacheServer/index.d.ts

@@ -33,7 +33,7 @@ export interface CacheServerOptions {
 }
 /**
  * Hit/miss/bytes snapshot of the cache server's runtime counters.
- * Row 18b Wave 3 / S6 — consumed by the agent's cacheStatsReporter.
+ * Row 18b Wave 3 / S6 — exposed via the cache server's getStats().
  */
 export interface CacheServerStats {
     /** Number of GET /cache requests that returned 200 (cache hit). */

package/dist/cli-handlers.d.ts

@@ -0,0 +1,233 @@
+/**
+ * cli-handlers — the bodies of every `buildhive-agent <cmd>` action.
+ *
+ * 2026-06-10 (agent-coverage refinement 2B): hoisted out of the inline
+ * `.action(async …)` closures in cli.ts so the dispatch layer is testable
+ * in-process. cli.ts keeps the commander wiring + entrypoint guard and calls
+ * these handlers with production defaults; tests inject fakes through each
+ * handler's `deps` parameter and an `exit` that throws `CliExit` instead of
+ * terminating the runner.
+ *
+ * Behavior contract: every user-facing string, exit code, and side-effect
+ * order is preserved verbatim from the pre-refactor cli.ts (the dist-spawn
+ * suites cli-routing/cli-flags-published pin several of them).
+ */
+import { spawn as spawnDefault } from 'child_process';
+import { loadConfig as loadConfigDefault } from './config/index.js';
+/**
+ * Canonical config path. The loader (`config/loader.ts`) probes
+ * `buildhive-agent.json` first, so this MUST match. Two filenames historically
+ * existed (`config.json` from `init`, `buildhive-agent.json` from `register`)
+ * — unified onto one (Sprint B B4).
+ */
+export declare const CONFIG_PATH: string;
+/**
+ * Thrown by a test-injected `exit` in place of `process.exit`. Production
+ * never constructs this (the default exit terminates the process), but the
+ * outer catch blocks below re-throw it so a test's exit signal is never
+ * swallowed into the generic error→exit(1) path.
+ */
+export declare class CliExit extends Error {
+    readonly code: number;
+    constructor(code: number);
+}
+/** Output/exit seams shared by every handler. Defaults are the real console/process. */
+export interface CmdIo {
+    readonly out?: (...args: unknown[]) => void;
+    readonly warnOut?: (...args: unknown[]) => void;
+    readonly errOut?: (...args: unknown[]) => void;
+    readonly exit?: (code: number) => never;
+}
+/** Subset of fs.promises the handlers touch — injectable for tests. */
+export interface FsLike {
+    readonly access: (path: string) => Promise<void>;
+    readonly readFile: (path: string, encoding: 'utf-8' | 'utf8') => Promise<string>;
+    readonly unlink: (path: string) => Promise<void>;
+}
+/** `init` — STUB during Phase 10 pivot (row 17a). Exit 2 = intentionally not implemented. */
+export declare function runInitCmd(deps?: CmdIo): Promise<void>;
+/**
+ * Commander option parser for `--jobs <n>`. Exported so the boundary rules
+ * (positive integer, ≤64 cap — each slot is a ~200MB runner-dir copy) are
+ * unit-testable without spawning the binary.
+ */
+export declare function parseJobsOption(v: string): number;
+export interface StartCmdOpts {
+    readonly config?: string;
+    readonly owner?: string;
+    readonly repo?: string;
+    readonly jobs?: number;
+}
+export interface StartCmdDeps extends CmdIo {
+    readonly runStartFn?: (opts: {
+        owner?: string;
+        repo?: string;
+        maxConcurrentJobs?: number;
+    }) => Promise<{
+        exitCode: number;
+    }>;
+}
+/** `start` — launches the runner supervisor (row 17b). */
+export declare function runStartCmd(opts: StartCmdOpts, deps?: StartCmdDeps): Promise<void>;
+export interface StopCmdDeps extends CmdIo {
+    readonly fsImpl?: FsLike;
+    readonly killFn?: (pid: number, signal: NodeJS.Signals | 0) => void;
+    readonly sleepFn?: (ms: number) => Promise<void>;
+    readonly pidFile?: string;
+}
+/** `stop` — SIGTERM the daemon by PID file, poll ≤15s, SIGKILL fallback. */
+export declare function runStopCmd(deps?: StopCmdDeps): Promise<void>;
+export interface StatusCmdDeps extends CmdIo {
+    readonly loadConfigFn?: typeof loadConfigDefault;
+    readonly fsImpl?: FsLike;
+    readonly killFn?: (pid: number, signal: NodeJS.Signals | 0) => void;
+    readonly pidFile?: string;
+}
+/** `status` — print config summary + running/PID state. */
+export declare function runStatusCmd(deps?: StatusCmdDeps): Promise<void>;
+export interface ConfigCmdDeps extends CmdIo {
+    readonly fsImpl?: FsLike;
+    readonly defaultConfigPath?: string;
+}
+/** `config` — print the config file with the apiKey masked to its last 4 chars. */
+export declare function runConfigCmd(opts: {
+    config?: string;
+}, deps?: ConfigCmdDeps): Promise<void>;
+export interface TestCmdDeps extends CmdIo {
+    readonly loadConfigFn?: typeof loadConfigDefault;
+    /** Factory for the connectivity probe — default lazy-imports BuildHiveApiClient. */
+    readonly makeApiClient?: (platformUrl: string) => Promise<{
+        testConnection(): Promise<boolean>;
+    }>;
+}
+/** `test` — connectivity probe against the platform /health endpoint. */
+export declare function runTestCmd(deps?: TestCmdDeps): Promise<void>;
+export interface LogsCmdDeps extends CmdIo {
+    readonly fsImpl?: FsLike;
+    readonly spawnFn?: typeof spawnDefault;
+    readonly logFile?: string;
+    /** Seam for the follow-mode Ctrl+C hook (default registers on process). */
+    readonly registerSigint?: (handler: () => void) => void;
+}
+/** `logs` — print the last N lines, or `tail -f` in follow mode. */
+export declare function runLogsCmd(opts: {
+    follow?: boolean;
+    lines: string;
+}, deps?: LogsCmdDeps): Promise<void>;
+export interface DoctorCmdDeps extends CmdIo {
+    readonly runDoctorFn?: () => Promise<{
+        exitCode: number;
+    }>;
+}
+/** `doctor` — diagnostic checks; implementation lives in ./doctor/. */
+export declare function runDoctorCmd(deps?: DoctorCmdDeps): Promise<void>;
+export interface ServiceInstallCmdDeps extends CmdIo {
+    readonly installServiceFn?: (opts: {
+        mode: 'system' | 'user';
+        cliEntryPath: string;
+    }) => Promise<{
+        paths: {
+            plistPath: string;
+            workingDirectory: string;
+            logDir: string;
+        };
+        bootstrapStdout: string;
+    }>;
+    readonly resolveCliEntry?: () => string;
+}
+/** `service:install` — LaunchAgent default; `--system` LaunchDaemon opt-in. */
+export declare function runServiceInstallCmd(opts: {
+    system?: boolean;
+    cliEntry?: string;
+}, deps?: ServiceInstallCmdDeps): Promise<void>;
+export interface ServiceUninstallCmdDeps extends CmdIo {
+    readonly uninstallServiceFn?: (opts: {
+        mode: 'system' | 'user';
+    }) => Promise<void>;
+}
+/** `service:uninstall` — idempotent (missing service is not an error). */
+export declare function runServiceUninstallCmd(opts: {
+    system?: boolean;
+}, deps?: ServiceUninstallCmdDeps): Promise<void>;
+export interface ServiceStatusCmdDeps extends CmdIo {
+    readonly getServiceStatusFn?: (opts: {
+        mode: 'system' | 'user';
+    }) => Promise<{
+        plistFilePresent: boolean;
+        loaded: boolean;
+        state: string | null;
+        lastExitReason: string | null;
+        paths: {
+            plistPath: string;
+        };
+    }>;
+}
+/** `service:status` — exit 0 when loaded, 1 otherwise. */
+export declare function runServiceStatusCmd(opts: {
+    system?: boolean;
+}, deps?: ServiceStatusCmdDeps): Promise<void>;
+export interface ServiceMigrateCmdDeps extends CmdIo {
+    readonly detectLegacyInstallFn?: () => Promise<{
+        hasAnyToClean: boolean;
+        hasAnyLegacy: boolean;
+        macOSLaunchDaemon: {
+            plistPresent: boolean;
+            installDirPresent: boolean;
+            logDirPresent: boolean;
+        };
+        userScopeState: {
+            envFilePresent: boolean;
+        };
+        ephemeral: {
+            tmpDirPresent: boolean;
+        };
+        linux: {
+            systemdUnitPresent: boolean;
+            configDirPresent: boolean;
+        };
+    }>;
+    readonly migrateToLaunchAgentFn?: (opts: {
+        cliEntryPath: string;
+        targetMode: 'system' | 'user';
+        sudoPasswordPrompt: () => Promise<string>;
+    }) => Promise<{
+        cleaned: {
+            launchDaemonBootout: boolean;
+            plistRemoved: boolean;
+            installDirRemoved: boolean;
+            envFileRemoved: boolean;
+            tmpDirRemoved: boolean;
+            systemdUnitRemoved: boolean;
+        };
+        installed: boolean;
+        newPlistPath: string | null;
+        skipped: ReadonlyArray<{
+            path: string;
+            reason: string;
+        }>;
+    }>;
+    readonly resolveCliEntry?: () => string;
+    readonly sudoPasswordPromptFn?: () => Promise<string>;
+}
+/** `service:migrate` — legacy LaunchDaemon → LaunchAgent (AGT-G2). */
+export declare function runServiceMigrateCmd(opts: {
+    system?: boolean;
+    dryRun?: boolean;
+    cliEntry?: string;
+}, deps?: ServiceMigrateCmdDeps): Promise<void>;
+export interface JoinCmdDeps extends CmdIo {
+    readonly loadConfigFn?: typeof loadConfigDefault;
+    readonly runJoinFn?: (opts: {
+        token: string;
+        platformUrl: string;
+    }) => Promise<{
+        exitCode: number;
+    }>;
+}
+/**
+ * `join <token>` — row 17c zero-GH enrollment. platformUrl precedence:
+ * --url flag > config.platformUrl > https://api.buildhive.app.
+ */
+export declare function runJoinCmd(token: string, opts: {
+    url?: string;
+}, deps?: JoinCmdDeps): Promise<void>;