@soederpop/luca 0.1.2 → 0.2.1

package/dist/node/features/runpod.d.ts

@@ -0,0 +1,527 @@
+import { z } from 'zod';
+import { Feature } from '../feature';
+export declare const RunpodStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$loose>;
+export type RunpodState = z.infer<typeof RunpodStateSchema>;
+export declare const RunpodOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    dataCenterId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type RunpodOptions = z.infer<typeof RunpodOptionsSchema>;
+/**
+ * RunPod feature — manage GPU cloud pods, templates, volumes, and SSH connections via the RunPod REST API.
+ *
+ * Provides a complete interface for provisioning and managing RunPod GPU instances.
+ * Supports creating pods from templates, managing network storage volumes, SSH access
+ * via the SecureShell feature, file transfers, and polling for pod readiness.
+ *
+ * @extends Feature
+ *
+ * @example
+ * ```typescript
+ * const runpod = container.feature('runpod', { enable: true })
+ * const pod = await runpod.createPod({ gpuTypeId: 'NVIDIA RTX 4090', templateId: 'abc123' })
+ * const ready = await runpod.waitForPod(pod.id)
+ * const shell = await runpod.getShell(pod.id)
+ * await shell.exec('nvidia-smi')
+ * ```
+ */
+export declare class Runpod extends Feature<RunpodState, RunpodOptions> {
+    static shortcut: "features.runpod";
+    static envVars: string[];
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        apiKey: z.ZodOptional<z.ZodString>;
+        dataCenterId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    private _resolvedRunpodctlPath;
+    /** The proc feature used for executing CLI commands like runpodctl. */
+    get proc(): import("./proc.js").ChildProcess;
+    /** Resolve the runpodctl binary path via `which`, caching the result. */
+    get runpodctlPath(): string;
+    /** RunPod API key from options or the RUNPOD_API_KEY environment variable. */
+    get apiKey(): string;
+    /** Preferred data center ID, defaults to 'US-TX-3'. */
+    get dataCenterId(): string;
+    private api;
+    /**
+     * List available pod templates.
+     *
+     * @param options - Filter options for templates
+     * @param options.includePublic - Include public community templates (default: false)
+     * @param options.includeRunpod - Include RunPod official templates (default: true)
+     * @returns Array of template info objects
+     *
+     * @example
+     * ```typescript
+     * const templates = await runpod.listTemplates({ includeRunpod: true })
+     * console.log(templates.map(t => t.name))
+     * ```
+     */
+    listTemplates(options?: {
+        includePublic?: boolean;
+        includeRunpod?: boolean;
+    }): Promise<TemplateInfo[]>;
+    /**
+     * Get details for a specific template by ID.
+     *
+     * @param templateId - The template ID to look up
+     * @returns Template info object
+     *
+     * @example
+     * ```typescript
+     * const template = await runpod.getTemplate('abc123')
+     * console.log(template.imageName)
+     * ```
+     */
+    getTemplate(templateId: string): Promise<TemplateInfo>;
+    /**
+     * Create a new GPU pod on RunPod.
+     *
+     * @param options - Pod configuration options
+     * @returns The created pod info
+     *
+     * @example
+     * ```typescript
+     * const pod = await runpod.createPod({
+     *   gpuTypeId: 'NVIDIA RTX 4090',
+     *   templateId: 'abc123',
+     *   volumeInGb: 50,
+     * })
+     * console.log(`Pod ${pod.id} created`)
+     * ```
+     */
+    createPod(options: CreatePodOptions): Promise<PodInfo>;
+    /**
+     * Stop a running pod.
+     *
+     * @param podId - The pod ID to stop
+     * @returns API response
+     *
+     * @example
+     * ```typescript
+     * await runpod.stopPod('pod-abc123')
+     * ```
+     */
+    stopPod(podId: string): Promise<any>;
+    /**
+     * Start a stopped pod.
+     *
+     * @param podId - The pod ID to start
+     * @returns API response
+     *
+     * @example
+     * ```typescript
+     * await runpod.startPod('pod-abc123')
+     * ```
+     */
+    startPod(podId: string): Promise<any>;
+    /**
+     * Permanently delete a pod.
+     *
+     * @param podId - The pod ID to remove
+     * @returns API response
+     *
+     * @example
+     * ```typescript
+     * await runpod.removePod('pod-abc123')
+     * ```
+     */
+    removePod(podId: string): Promise<any>;
+    /**
+     * Get all pods via the REST API.
+     *
+     * @param filters - Optional filters for name, image, or status
+     * @param filters.name - Filter by pod name
+     * @param filters.imageName - Filter by Docker image name
+     * @param filters.desiredStatus - Filter by status (RUNNING, EXITED, TERMINATED)
+     * @returns Array of pod info objects
+     *
+     * @example
+     * ```typescript
+     * const pods = await runpod.getpods({ desiredStatus: 'RUNNING' })
+     * console.log(pods.map(p => `${p.name}: ${p.desiredStatus}`))
+     * ```
+     */
+    getpods(filters?: {
+        name?: string;
+        imageName?: string;
+        desiredStatus?: string;
+    }): Promise<RestPodInfo[]>;
+    /**
+     * Get detailed pod info via the REST API.
+     *
+     * Returns richer data than the CLI-based `getPodInfo`, including port mappings and public IP.
+     *
+     * @param podId - The pod ID to look up
+     * @returns Detailed pod info with port mappings, costs, and GPU details
+     *
+     * @example
+     * ```typescript
+     * const pod = await runpod.getPod('pod-abc123')
+     * console.log(`${pod.name} - ${pod.desiredStatus} - $${pod.costPerHr}/hr`)
+     * ```
+     */
+    getPod(podId: string): Promise<RestPodInfo>;
+    /**
+     * Poll until a pod reaches a desired status.
+     *
+     * @param podId - The pod ID to monitor
+     * @param status - Target status to wait for (default: 'RUNNING')
+     * @param options - Polling configuration
+     * @param options.interval - Polling interval in ms (default: 5000)
+     * @param options.timeout - Max wait time in ms (default: 300000)
+     * @returns The pod info once it reaches the target status
+     * @throws If the pod does not reach the target status within the timeout
+     *
+     * @example
+     * ```typescript
+     * const pod = await runpod.createPod({ gpuTypeId: 'NVIDIA RTX 4090', templateId: 'abc' })
+     * const ready = await runpod.waitForPod(pod.id, 'RUNNING', { timeout: 120000 })
+     * ```
+     */
+    waitForPod(podId: string, status?: string, { interval, timeout }?: {
+        interval?: number | undefined;
+        timeout?: number | undefined;
+    }): Promise<RestPodInfo>;
+    /**
+     * List all network storage volumes on your account.
+     *
+     * @returns Array of volume info objects
+     *
+     * @example
+     * ```typescript
+     * const volumes = await runpod.listVolumes()
+     * console.log(volumes.map(v => `${v.name}: ${v.size}GB`))
+     * ```
+     */
+    listVolumes(): Promise<VolumeInfo[]>;
+    /**
+     * Get details for a specific network volume.
+     *
+     * @param volumeId - The volume ID to look up
+     * @returns Volume info object
+     *
+     * @example
+     * ```typescript
+     * const vol = await runpod.getVolume('vol-abc123')
+     * console.log(`${vol.name}: ${vol.size}GB in ${vol.dataCenterId}`)
+     * ```
+     */
+    getVolume(volumeId: string): Promise<VolumeInfo>;
+    /**
+     * Create a new network storage volume.
+     *
+     * @param options - Volume configuration
+     * @returns The created volume info
+     *
+     * @example
+     * ```typescript
+     * const vol = await runpod.createVolume({ name: 'my-models', size: 100 })
+     * console.log(`Created volume ${vol.id}`)
+     * ```
+     */
+    createVolume(options: CreateVolumeOptions): Promise<VolumeInfo>;
+    /**
+     * Delete a network storage volume.
+     *
+     * @param volumeId - The volume ID to delete
+     * @returns API response
+     *
+     * @example
+     * ```typescript
+     * await runpod.removeVolume('vol-abc123')
+     * ```
+     */
+    removeVolume(volumeId: string): Promise<any>;
+    /**
+     * Create an SSH connection to a pod using the runpodctl CLI.
+     *
+     * Prefer `getShell()` which uses the REST API and is more reliable.
+     *
+     * @param podId - The pod ID to connect to
+     * @returns A SecureShell feature instance connected to the pod
+     *
+     * @example
+     * ```typescript
+     * const shell = await runpod.createRemoteShell('pod-abc123')
+     * const output = await shell.exec('nvidia-smi')
+     * ```
+     */
+    createRemoteShell(podId: string): Promise<import("./secure-shell.js").SecureShell>;
+    /**
+     * Get an SSH connection to a pod using the REST API.
+     *
+     * Uses port mappings and public IP from the REST API, which is more reliable
+     * than the CLI-based `createRemoteShell`.
+     *
+     * @param podId - The pod ID to connect to
+     * @returns A SecureShell feature instance connected to the pod
+     * @throws If no SSH port mapping or public IP is found
+     *
+     * @example
+     * ```typescript
+     * const shell = await runpod.getShell('pod-abc123')
+     * const output = await shell.exec('ls /workspace')
+     * ```
+     */
+    getShell(podId: string): Promise<import("./secure-shell.js").SecureShell>;
+    /**
+     * Ensure a file exists on a pod's filesystem. If missing, kicks off a background
+     * download via a helper script and polls until the file appears.
+     *
+     * @param podId - The pod ID
+     * @param remotePath - Absolute path on the pod where the file should exist
+     * @param fallbackUrl - URL to download from (inside the pod) if the file doesn't exist
+     * @param options.pollInterval - How often to check in ms (default 5000)
+     * @param options.timeout - Max time to wait for download in ms (default 600000 / 10 min)
+     * @param options.onProgress - Called each poll with current file size in bytes
+     * @returns Object with `existed` (was already there) and `path`
+     *
+     * @example
+     * ```ts
+     * await runpod.ensureFileExists(
+     *   podId,
+     *   '/workspace/ComfyUI/models/checkpoints/juggernaut_xl.safetensors',
+     *   'https://civitai.com/api/download/models/456789',
+     *   { onProgress: (bytes) => console.log(`${(bytes / 1e9).toFixed(2)} GB downloaded`) }
+     * )
+     * ```
+     */
+    ensureFileExists(podId: string, remotePath: string, fallbackUrl: string, options?: {
+        pollInterval?: number;
+        timeout?: number;
+        onProgress?: (bytes: number) => void;
+    }): Promise<{
+        existed: boolean;
+        path: string;
+    }>;
+    /**
+     * Get the public HTTP proxy URLs for a pod's exposed HTTP ports.
+     *
+     * @param podId - The pod ID
+     * @returns Array of public proxy URLs
+     *
+     * @example
+     * ```typescript
+     * const urls = await runpod.getPodHttpURLs('pod-abc123')
+     * // ['https://pod-abc123-8888.proxy.runpod.net']
+     * ```
+     */
+    getPodHttpURLs(podId: string): Promise<string[]>;
+    /**
+     * List all pods using the runpodctl CLI.
+     *
+     * Parses the tabular output from `runpodctl get pod`. For richer data, use `getpods()`.
+     *
+     * @param detailed - Reserved for future use
+     * @returns Array of pod info objects
+     *
+     * @example
+     * ```typescript
+     * const pods = await runpod.listPods()
+     * pods.forEach(p => console.log(`${p.name} (${p.gpu}): ${p.status}`))
+     * ```
+     */
+    listPods(detailed?: boolean): Promise<PodInfo[]>;
+    /**
+     * Get pod info using the runpodctl CLI.
+     *
+     * For richer data including port mappings and public IP, use `getPod()`.
+     *
+     * @param podId - The pod ID to look up
+     * @returns Pod info parsed from CLI output
+     *
+     * @example
+     * ```typescript
+     * const info = await runpod.getPodInfo('pod-abc123')
+     * console.log(`${info.name}: ${info.status}`)
+     * ```
+     */
+    getPodInfo(podId: string): Promise<PodInfo>;
+    /**
+     * List available secure GPU types with pricing.
+     *
+     * Uses the runpodctl CLI to query available secure cloud GPUs, filtering out reserved instances.
+     *
+     * @returns Array of GPU info with type, memory, CPU count, and pricing
+     *
+     * @example
+     * ```typescript
+     * const gpus = await runpod.listSecureGPUs()
+     * gpus.forEach(g => console.log(`${g.gpuType}: $${g.ondemandPrice}/hr`))
+     * ```
+     */
+    listSecureGPUs(): Promise<{
+        gpuType: string | undefined;
+        memory: number;
+        cpuCount: number;
+        spotPrice: number;
+        ondemandPrice: number;
+    }[]>;
+}
+export default Runpod;
+type PortInfo = {
+    ip: string;
+    internal: number;
+    external: number;
+    serviceType: string;
+    isPublic: boolean;
+};
+/**
+ * {
+  "id": "vv32fbi9y21cxz",
+  "name": "RunPod Stable Diffusion",
+  "gpu": "1 RTX 4090",
+  "imageName": "runpod/stable-diffusion:web-ui-10.2.1",
+  "status": "RUNNING",
+  "podType": "RESERVED",
+  "cpu": "21",
+  "memory": "41",
+  "containerDisk": "10",
+  "volumeDisk": "0",
+  "spotPrice": "0.690",
+  "ports": [
+    {
+      "ip": "100.65.22.197",
+      "internal": "60014",
+      "external": "8888",
+      "serviceType": "http",
+      "isPublic": false
+    },
+    {
+      "ip": "100.65.22.197",
+      "internal": "60013",
+      "external": "19123",
+      "serviceType": "http",
+      "isPublic": false
+    },
+    {
+      "ip": "203.57.40.89",
+      "internal": "10020",
+      "external": "22",
+      "serviceType": "tcp",
+      "isPublic": true
+    },
+    {
+      "ip": "100.65.22.197",
+      "internal": "60015",
+      "external": "3001",
+      "serviceType": "http",
+      "isPublic": false
+    }
+  ]
+}
+*/
+type PodInfo = {
+    id: string;
+    name: string;
+    gpu: string;
+    imageName: string;
+    status: string;
+    podType: string;
+    cpu: string;
+    memory: string;
+    containerDisk: string;
+    volumeDisk: string;
+    spotPrice: string;
+    ports: PortInfo[];
+};
+type TemplateInfo = {
+    id: string;
+    name: string;
+    category: string;
+    imageName: string;
+    isPublic: boolean;
+    isRunpod: boolean;
+    isServerless: boolean;
+    containerDiskInGb: number;
+    volumeInGb: number;
+    volumeMountPath: string;
+    ports: string[];
+    env: Record<string, string>;
+    readme: string;
+};
+type VolumeInfo = {
+    id: string;
+    name: string;
+    size: number;
+    dataCenterId: string;
+};
+type CreateVolumeOptions = {
+    /** Display name for the volume */
+    name: string;
+    /** Size in GB */
+    size: number;
+    /** Data center to create in (defaults to feature's dataCenterId) */
+    dataCenterId?: string;
+};
+type RestPodInfo = {
+    id: string;
+    name: string;
+    desiredStatus: 'RUNNING' | 'EXITED' | 'TERMINATED';
+    costPerHr: number;
+    adjustedCostPerHr: number;
+    gpu: {
+        id: string;
+        count: number;
+        displayName: string;
+    };
+    machine: {
+        dataCenterId: string;
+        location: string;
+        gpuTypeId: string;
+    };
+    /** Public IP for SSH/TCP connections */
+    publicIp: string | null;
+    ports: string[];
+    /** Maps internal port (e.g. "22") to external port number (e.g. 22122) */
+    portMappings: Record<string, number> | null;
+    containerDiskInGb: number;
+    volumeInGb: number;
+    memoryInGb: number;
+    vcpuCount: number;
+    image: string;
+};
+type CreatePodOptions = {
+    /** Pod display name (default: 'luca-pod') */
+    name?: string;
+    /** Docker image name to run */
+    imageName?: string;
+    /** GPU type ID or array of acceptable GPU types */
+    gpuTypeId: string | string[];
+    /** Number of GPUs to allocate (default: 1) */
+    gpuCount?: number;
+    /** Template ID to use for pod configuration */
+    templateId?: string;
+    /** Cloud type: 'SECURE' for dedicated or 'COMMUNITY' for shared (default: 'SECURE') */
+    cloudType?: 'SECURE' | 'COMMUNITY';
+    /** Container disk size in GB (default: 50) */
+    containerDiskInGb?: number;
+    /** Persistent volume size in GB (default: 20) */
+    volumeInGb?: number;
+    /** Mount path for the volume (default: '/workspace') */
+    volumeMountPath?: string;
+    /** Port mappings like ['8888/http', '22/tcp'] */
+    ports?: string[];
+    /** Environment variables to set in the container */
+    env?: Record<string, string>;
+    /** Whether the pod can be preempted for spot pricing */
+    interruptible?: boolean;
+    /** ID of an existing network volume to attach */
+    networkVolumeId?: string;
+    /** Minimum RAM per GPU in GB */
+    minRAMPerGPU?: number;
+};
+//# sourceMappingURL=runpod.d.ts.map

package/dist/node/features/runpod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runpod.d.ts","sourceRoot":"","sources":["../../../src/node/features/runpod.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAGpC,eAAO,MAAM,iBAAiB;;iBAAgC,CAAA;AAC9D,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAE3D,eAAO,MAAM,mBAAmB;;;;;;;iBAG9B,CAAA;AACF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAA;AAE/D;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,MAAO,SAAQ,OAAO,CAAC,WAAW,EAAE,aAAa,CAAC;IAC7D,OAAgB,QAAQ,EAAG,iBAAiB,CAAS;IACrD,OAAgB,OAAO,WAAqB;IAC5C,OAAgB,WAAW;;sBAAoB;IAC/C,OAAgB,aAAa;;;;;;;sBAAsB;IAGpD,OAAO,CAAC,sBAAsB,CAAsB;IAEpD,uEAAuE;IACvE,IAAI,IAAI,qCAEP;IAED,yEAAyE;IACzE,IAAI,aAAa,IAAI,MAAM,CAQ1B;IAED,8EAA8E;IAC9E,IAAI,MAAM,WAET;IAED,uDAAuD;IACvD,IAAI,YAAY,WAEf;IAED,OAAO,CAAC,GAAG;IAYX;;;;;;;;;;;;;OAaG;IACG,aAAa,CAAC,OAAO,GAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAShH;;;;;;;;;;;OAWG;IACG,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAI5D;;;;;;;;;;;;;;;OAeG;IACG,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAsB5D;;;;;;;;;;OAUG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM;IAI3B;;;;;;;;;;OAUG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM;IAI5B;;;;;;;;;;OAUG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM;IAI7B;;;;;;;;;;;;;;OAcG;IACG,OAAO,CAAC,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAIlH;;;;;;;;;;;;;OAaG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAIjD;;;;;;;;;;;;;;;;OAgBG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,MAAkB,EAAE,EAAE,QAAe,EAAE,OAAgB,EAAE;;;KAAK,GAAG,OAAO,CAAC,WAAW,CAAC;IAY7H;;;;;;;;;;OAUG;IACG,WAAW,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAI1C;;;;;;;;;;;OAWG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAItD;;;;;;;;;;;OAWG;IACG,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC;IAWrE;;;;;;;;;;OAUG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM;IAInC;;;;;;;;;;;;;OAaG;IACG,iBAAiB,CAAC,KAAK,EAAE,MAAM;IAgBrC;;;;;;;;;;;;;;;OAeG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM;IAoB5B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,gBAAgB,CACrB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE;QACR,YAAY,CAAC,EAAE,MAAM,CAAA;QACrB,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;KAC/B,GACJ,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IA2D9C;;;;;;;;;;;OAWG;IACG,cAAc,CAAC,KAAK,EAAE,MAAM;IAMlC;;;;;;;;;;;;;OAaG;IACG,QAAQ,CAAC,QAAQ,UAAQ,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IA0BpD;;;;;;;;;;;;;OAaG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAyBjD;;;;;;;;;;;;OAYG;IACG,cAAc;;;;;;;CAmBpB;AAED,eAAe,MAAM,CAAA;AAyCrB,KAAK,QAAQ,GAAG;IACf,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA4CE;AAEF,KAAK,OAAO,GAAG;IACd,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,QAAQ,EAAE,CAAA;CACjB,CAAA;AAED,KAAK,YAAY,GAAG;IACnB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,OAAO,CAAA;IACjB,QAAQ,EAAE,OAAO,CAAA;IACjB,YAAY,EAAE,OAAO,CAAA;IACrB,iBAAiB,EAAE,MAAM,CAAA;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,eAAe,EAAE,MAAM,CAAA;IACvB,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC3B,MAAM,EAAE,MAAM,CAAA;CACd,CAAA;AAED,KAAK,UAAU,GAAG;IACjB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,YAAY,EAAE,MAAM,CAAA;CACpB,CAAA;AAED,KAAK,mBAAmB,GAAG;IAC1B,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED,KAAK,WAAW,GAAG;IAClB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,aAAa,EAAE,SAAS,GAAG,QAAQ,GAAG,YAAY,CAAA;IAClD,SAAS,EAAE,MAAM,CAAA;IACjB,iBAAiB,EAAE,MAAM,CAAA;IACzB,GAAG,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAA;IACvD,OAAO,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IACtE,wCAAwC;IACxC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAA;IAC3C,iBAAiB,EAAE,MAAM,CAAA;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;CACb,CAAA;AAED,KAAK,gBAAgB,GAAG;IACvB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,+BAA+B;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,mDAAmD;IACnD,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC5B,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,uFAAuF;IACvF,SAAS,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAA;IAClC,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;IAChB,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,wDAAwD;IACxD,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,iDAAiD;IACjD,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,gCAAgC;IAChC,YAAY,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA"}

package/dist/node/features/secure-shell.d.ts

@@ -0,0 +1,145 @@
+import { z } from 'zod';
+import { Feature } from '../feature.js';
+export declare const SecureShellStateSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    connected: z.ZodBoolean;
+}, z.core.$loose>;
+export type SecureShellState = z.infer<typeof SecureShellStateSchema>;
+export declare const SecureShellOptionsSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    _cacheKey: z.ZodOptional<z.ZodString>;
+    cached: z.ZodOptional<z.ZodBoolean>;
+    enable: z.ZodOptional<z.ZodBoolean>;
+    host: z.ZodOptional<z.ZodString>;
+    port: z.ZodOptional<z.ZodNumber>;
+    username: z.ZodOptional<z.ZodString>;
+    password: z.ZodOptional<z.ZodString>;
+    key: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SecureShellOptions = z.infer<typeof SecureShellOptionsSchema>;
+/**
+ * SecureShell Feature -- SSH command execution and SCP file transfers.
+ *
+ * Uses the system `ssh` and `scp` binaries to run commands on remote hosts
+ * and transfer files. Supports key-based and password-based authentication
+ * through the container's `proc` feature.
+ *
+ * @example
+ * ```typescript
+ * const ssh = container.feature('secureShell', {
+ *   host: '192.168.1.100',
+ *   username: 'deploy',
+ *   key: '~/.ssh/id_ed25519',
+ * })
+ *
+ * if (await ssh.testConnection()) {
+ *   const uptime = await ssh.exec('uptime')
+ *   console.log(uptime)
+ * }
+ * ```
+ *
+ * @extends Feature
+ */
+export declare class SecureShell extends Feature<SecureShellState, SecureShellOptions> {
+    static shortcut: "features.secureShell";
+    static stateSchema: z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        connected: z.ZodBoolean;
+    }, z.core.$loose>;
+    static optionsSchema: z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        _cacheKey: z.ZodOptional<z.ZodString>;
+        cached: z.ZodOptional<z.ZodBoolean>;
+        enable: z.ZodOptional<z.ZodBoolean>;
+        host: z.ZodOptional<z.ZodString>;
+        port: z.ZodOptional<z.ZodNumber>;
+        username: z.ZodOptional<z.ZodString>;
+        password: z.ZodOptional<z.ZodString>;
+        key: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    get initialState(): SecureShellState;
+    private _resolvedSshPath;
+    private _resolvedScpPath;
+    /**
+     * Get the proc feature for executing shell commands
+     */
+    private get proc();
+    /** Resolved path to the ssh binary */
+    get sshPath(): string;
+    /** Resolved path to the scp binary */
+    get scpPath(): string;
+    /**
+     * Validate that required options are provided
+     */
+    private validateOptions;
+    /**
+     * Build SSH connection string with authentication options
+     */
+    private buildSSHConnectionString;
+    /**
+     * Build SCP connection string for file transfers
+     */
+    private buildSCPConnectionString;
+    /**
+     * Test the SSH connection by running a simple echo command on the remote host.
+     *
+     * Updates `state.connected` based on the result.
+     *
+     * @returns `true` if the connection succeeds, `false` otherwise (never throws)
+     *
+     * @example
+     * ```typescript
+     * const ssh = container.feature('secureShell', { host: 'example.com', username: 'admin', key: '~/.ssh/id_rsa' })
+     * const ok = await ssh.testConnection()
+     * if (!ok) console.error('SSH connection failed')
+     * ```
+     */
+    testConnection(): Promise<boolean>;
+    /**
+     * Executes a command on the remote host.
+     *
+     * @param command - The command to execute on the remote shell
+     * @returns The trimmed stdout output of the command
+     * @throws {Error} When the SSH command exits with a non-zero code
+     *
+     * @example
+     * ```typescript
+     * const ssh = container.feature('secureShell', { host: 'example.com', username: 'admin', key: '~/.ssh/id_rsa' })
+     * const listing = await ssh.exec('ls -la /var/log')
+     * console.log(listing)
+     * ```
+     */
+    exec(command: string): Promise<string>;
+    /**
+     * Downloads a file from the remote host via SCP.
+     *
+     * @param source - The source file path on the remote host
+     * @param target - The target file path on the local machine
+     * @returns A confirmation message or the scp stdout output
+     * @throws {Error} When the SCP transfer fails
+     *
+     * @example
+     * ```typescript
+     * const ssh = container.feature('secureShell', { host: 'example.com', username: 'admin', key: '~/.ssh/id_rsa' })
+     * await ssh.download('/var/log/app.log', './logs/app.log')
+     * ```
+     */
+    download(source: string, target: string): Promise<string>;
+    /**
+     * Uploads a file to the remote host via SCP.
+     *
+     * @param source - The source file path on the local machine
+     * @param target - The target file path on the remote host
+     * @returns A confirmation message or the scp stdout output
+     * @throws {Error} When the SCP transfer fails
+     *
+     * @example
+     * ```typescript
+     * const ssh = container.feature('secureShell', { host: 'example.com', username: 'admin', key: '~/.ssh/id_rsa' })
+     * await ssh.upload('./build/app.tar.gz', '/opt/releases/app.tar.gz')
+     * ```
+     */
+    upload(source: string, target: string): Promise<string>;
+}
+export default SecureShell;
+//# sourceMappingURL=secure-shell.d.ts.map

package/dist/node/features/secure-shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secure-shell.d.ts","sourceRoot":"","sources":["../../../src/node/features/secure-shell.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAEvC,eAAO,MAAM,sBAAsB;;;iBAGjC,CAAA;AACF,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAA;AAErE,eAAO,MAAM,wBAAwB;;;;;;;;;;iBAWnC,CAAA;AACF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAEzE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,WAAY,SAAQ,OAAO,CAAC,gBAAgB,EAAE,kBAAkB,CAAC;IAC5E,OAAgB,QAAQ,EAAG,sBAAsB,CAAS;IAC1D,OAAgB,WAAW;;;sBAAyB;IACpD,OAAgB,aAAa;;;;;;;;;;sBAA2B;IAGzD,IAAa,YAAY,IAAI,gBAAgB,CAK5C;IAED,OAAO,CAAC,gBAAgB,CAAsB;IAC9C,OAAO,CAAC,gBAAgB,CAAsB;IAE9C;;OAEG;IACH,OAAO,KAAK,IAAI,GAEf;IAED,sCAAsC;IACtC,IAAI,OAAO,IAAI,MAAM,CAQpB;IAED,sCAAsC;IACtC,IAAI,OAAO,IAAI,MAAM,CAQpB;IAED;;OAEG;IACH,OAAO,CAAC,eAAe;IAYvB;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAiBhC;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAehC;;;;;;;;;;;;;OAaG;IACG,cAAc,IAAI,OAAO,CAAC,OAAO,CAAC;IAkBxC;;;;;;;;;;;;;OAaG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmB5C;;;;;;;;;;;;;OAaG;IACG,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiB/D;;;;;;;;;;;;;OAaG;IACG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAgB7D;AAED,eAAe,WAAW,CAAA"}