crewly 1.20.131 → 1.20.133

package/dist/cli/backend/src/services/skill-setup/skill-setup-runner.service.d.ts

@@ -0,0 +1,338 @@
+/**
+ * Skill setup runner — performs a skill's `setup` block, idempotently.
+ *
+ * Every step is checked first and reported "already satisfied" when it is,
+ * so running setup twice is cheap and changes nothing the second time. A step
+ * that is missing is installed and then checked again; "installed" is only
+ * reported when the re-check passes.
+ *
+ * Safety properties (specs/skill-auto-install.md):
+ * - **Never hangs on a password prompt.** Every child gets a closed stdin;
+ *   apt-get runs only as root or through `sudo -n` (passwordless sudo). With
+ *   neither, the step fails at once with a message saying what to run by hand.
+ * - **Downloads are verified before they are used.** A file is streamed to a
+ *   temp name next to its destination, its size and sha256 are compared with
+ *   the manifest, and only then renamed into place. A mismatch deletes the
+ *   temp file and fails the step.
+ * - **One setup per skill at a time.** Concurrent calls in this process share
+ *   one run; another process (the CLI while the backend installs) waits on a
+ *   lock file under `$CREWLY_HOME/skill-setup/locks/`. A lock whose pid is
+ *   gone, or that is older than LOCK_STALE_MS, is reclaimed.
+ * - **Everything is logged** to `$CREWLY_HOME/logs/skill-setup/<skill>.log`,
+ *   including the full output of every install command.
+ *
+ * @module services/skill-setup/skill-setup-runner.service
+ */
+import type { RunCommand } from '../harness/harness.types.js';
+import { type OsFamily, type SkillSetupManifest, type SkillSetupStep } from './skill-setup-manifest.js';
+/** Final state of one step. */
+export type StepStatus = 'satisfied' | 'installed' | 'missing' | 'failed' | 'skipped';
+/** Progress phases reported while a step runs, plus its final state. */
+export type ProgressPhase = 'checking' | 'installing' | 'downloading' | 'waiting' | StepStatus;
+/** A progress event (also written to the log). */
+export interface SetupProgressEvent {
+    skillId: string;
+    /** Step id, or `setup` for whole-run events */
+    stepId: string;
+    phase: ProgressPhase;
+    message: string;
+}
+/** Outcome of one step. */
+export interface StepResult {
+    id: string;
+    type: SkillSetupStep['type'];
+    status: StepStatus;
+    message: string;
+    optional: boolean;
+}
+/** Outcome of a setup run. */
+export interface SetupResult {
+    skillId: string;
+    /** True when every required step is satisfied or installed */
+    success: boolean;
+    /** True when nothing was installed (checks only) */
+    checkOnly: boolean;
+    steps: StepResult[];
+    /** Log file path (empty for check-only runs, which do not log) */
+    logFile: string;
+    durationMs: number;
+    /** Message of the first required step that failed or is missing */
+    error?: string;
+}
+/** Input to {@link SkillSetupRunner.runSetup}. */
+export interface RunSetupInput {
+    /** Skill id (used for the lock, log and default venv name) */
+    skillId: string;
+    /** Absolute skill directory (install scripts are resolved inside it) */
+    skillDir: string;
+    manifest: SkillSetupManifest;
+    /** Only check; never install (no lock, no log) */
+    checkOnly?: boolean;
+    onProgress?: (event: SetupProgressEvent) => void;
+}
+/** Size and hash of a downloaded file. */
+export interface DownloadResult {
+    bytes: number;
+    sha256: string;
+}
+/**
+ * Download `url` to `destPath`, hashing as it streams.
+ *
+ * @param url - Source URL
+ * @param destPath - File to write (created/truncated)
+ * @param onBytes - Called with the running byte count
+ * @param stallTimeoutMs - Abort when no bytes arrive for this long
+ * @returns Bytes written and their sha256
+ * @throws On HTTP errors, stalls and write errors
+ */
+export type DownloadFile = (url: string, destPath: string, onBytes: (received: number) => void, stallTimeoutMs: number) => Promise<DownloadResult>;
+/** Injectable dependencies. */
+export interface SkillSetupRunnerDeps {
+    run?: RunCommand;
+    download?: DownloadFile;
+    osFamily?: () => OsFamily;
+    isRoot?: () => boolean;
+    crewlyHome?: () => string;
+    homeDir?: () => string;
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+    pid?: number;
+    isPidAlive?: (pid: number) => boolean;
+    /** Free bytes on the filesystem holding `dir`, or null when unknown */
+    freeBytes?: (dir: string) => number | null;
+    sleep?: (ms: number) => Promise<void>;
+    lockPollMs?: number;
+    lockWaitMs?: number;
+    /** Directories searched for commands after PATH (default: Homebrew + system dirs) */
+    extraCommandDirs?: readonly string[];
+    /** Where to look for `brew` when it is not on PATH */
+    brewCandidates?: readonly string[];
+}
+/**
+ * Detect the OS family.
+ *
+ * @returns `darwin`, `debian` (Linux with /etc/debian_version) or `linux`
+ */
+export declare function detectOsFamily(): OsFamily;
+/**
+ * Whether a pid belongs to a running process.
+ *
+ * @param pid - Process id
+ * @returns True when signal 0 can be delivered (or is refused with EPERM)
+ */
+export declare function isPidAlive(pid: number): boolean;
+/**
+ * Download with fetch, streaming to disk and hashing on the way.
+ *
+ * @param url - Source URL (redirects are followed)
+ * @param destPath - Destination file
+ * @param onBytes - Progress callback (running byte count)
+ * @param stallTimeoutMs - Abort after this long without data
+ * @returns Bytes and sha256
+ * @throws On HTTP errors, stalls and write errors
+ */
+export declare const defaultDownload: DownloadFile;
+/** Error raised when another process holds a skill's setup lock for too long. */
+export declare class SetupLockTimeoutError extends Error {
+    readonly skillId: string;
+    readonly holderPid: number;
+    /**
+     * @param skillId - Skill whose lock is held
+     * @param holderPid - Pid recorded in the lock file
+     */
+    constructor(skillId: string, holderPid: number);
+}
+/** Runs setup manifests. */
+export declare class SkillSetupRunner {
+    private readonly run;
+    private readonly download;
+    private readonly osFamily;
+    private readonly isRoot;
+    private readonly crewlyHome;
+    private readonly homeDir;
+    private readonly env;
+    private readonly now;
+    private readonly pid;
+    private readonly pidAlive;
+    private readonly freeBytes;
+    private readonly sleep;
+    private readonly lockPollMs;
+    private readonly lockWaitMs;
+    private readonly extraCommandDirs;
+    private readonly brewCandidates;
+    /** Setup runs in flight in this process, by skill id */
+    private readonly inflight;
+    /**
+     * @param deps - Injectable dependencies (all optional)
+     */
+    constructor(deps?: SkillSetupRunnerDeps);
+    /**
+     * Path of a skill's setup log.
+     *
+     * @param skillId - Skill id
+     * @returns `$CREWLY_HOME/logs/skill-setup/<id>.log`
+     */
+    logFileFor(skillId: string): string;
+    /**
+     * Expand `~/` and `$CREWLY_HOME/` in a manifest path.
+     *
+     * @param p - Manifest path
+     * @returns Absolute path
+     */
+    expandPath(p: string): string;
+    /**
+     * Perform (or only check) a setup manifest.
+     *
+     * Concurrent calls for the same skill in this process share one run.
+     *
+     * @param input - Skill id, directory, manifest, mode and progress callback
+     * @returns Per-step results; never rejects for step failures
+     *
+     * @example
+     * ```ts
+     * const result = await runner.runSetup({ skillId: 'transcribe-audio', skillDir, manifest });
+     * if (!result.success) console.error(result.error, 'see', result.logFile);
+     * ```
+     */
+    runSetup(input: RunSetupInput): Promise<SetupResult>;
+    /**
+     * Run every step (under the lock unless check-only).
+     *
+     * @param input - Run input
+     * @returns The result
+     */
+    private execute;
+    /**
+     * Dispatch one step.
+     *
+     * @param step - Step
+     * @param input - Run input
+     * @param emit - Progress emitter
+     * @returns Step result
+     */
+    private runStep;
+    /**
+     * Build a step result.
+     *
+     * @param step - Step
+     * @param status - Final status
+     * @param message - Message
+     * @returns The result
+     */
+    private stepResult;
+    /**
+     * PATH used for checks and installs: `$CREWLY_HOME/bin`, the process PATH,
+     * then the usual system and Homebrew dirs (a backend started by launchd or
+     * systemd often lacks /opt/homebrew/bin).
+     *
+     * @returns PATH string
+     */
+    private searchPath;
+    /**
+     * Environment for child processes.
+     *
+     * @param extra - Additional variables
+     * @returns Environment
+     */
+    private childEnv;
+    /**
+     * Run a command, streaming its output into the log.
+     *
+     * @param logFile - Log file ('' = do not log)
+     * @param skillId - Skill id
+     * @param stepId - Step id
+     * @param command - Executable
+     * @param args - Arguments
+     * @param timeoutMs - Timeout
+     * @param env - Environment
+     * @returns Exit code and combined output
+     */
+    private exec;
+    /**
+     * What satisfies a command check, if anything.
+     *
+     * @param step - Command step
+     * @returns A description of the match, or null
+     */
+    private commandPresent;
+    /**
+     * How this process can run apt-get.
+     *
+     * @param packages - Packages (for the hint)
+     * @returns The command + argument prefix, or an error message
+     */
+    private aptAccess;
+    /**
+     * The value handed to install scripts in CREWLY_SUDO: '' (root),
+     * 'sudo -n' (passwordless sudo) or 'unavailable'.
+     *
+     * @returns Sudo mode
+     */
+    private sudoMode;
+    /**
+     * Check, install and re-check a command dependency.
+     *
+     * @param step - Command step
+     * @param input - Run input
+     * @param emit - Progress emitter
+     * @returns Step result
+     */
+    private runCommandStep;
+    /**
+     * Check, download, verify and place a file.
+     *
+     * @param step - File step
+     * @param input - Run input
+     * @param emit - Progress emitter
+     * @returns Step result
+     */
+    private runFileStep;
+    /**
+     * Check, create and fill a Python virtualenv.
+     *
+     * @param step - Python step
+     * @param input - Run input
+     * @param emit - Progress emitter
+     * @returns Step result
+     */
+    private runPythonStep;
+    /**
+     * Take the per-skill lock file, waiting while another live process holds it.
+     *
+     * @param skillId - Skill id
+     * @param onWait - Called once when the lock is busy
+     * @returns A release function
+     * @throws SetupLockTimeoutError when the holder does not finish in lockWaitMs
+     */
+    private acquireLock;
+    /**
+     * Append a timestamped line to a log file.
+     *
+     * @param logFile - Log file
+     * @param skillId - Skill id
+     * @param stepId - Step id
+     * @param message - Message
+     */
+    private log;
+    /**
+     * Append text to a log file (best effort).
+     *
+     * @param logFile - Log file
+     * @param text - Text
+     */
+    private appendRaw;
+}
+/**
+ * Human-readable byte size.
+ *
+ * @param bytes - Size
+ * @returns e.g. "547.4 MB"
+ */
+export declare function formatSize(bytes: number): string;
+/**
+ * The process-wide runner (shares in-flight runs across callers).
+ *
+ * @returns The runner
+ */
+export declare function getSkillSetupRunner(): SkillSetupRunner;
+//# sourceMappingURL=skill-setup-runner.service.d.ts.map

package/dist/cli/backend/src/services/skill-setup/skill-setup-runner.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-setup-runner.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/skill-setup/skill-setup-runner.service.ts"],"names":[],"mappings":"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"}