feat: add cpToInstance and cpFromInstance functions

Add manually-maintained cp functionality to the SDK for copying files
to/from running instances. This is placed in src/lib/ directory following
the SDK's convention for custom extensions.

Features:
- cpToInstance: Copy local file/directory to instance
- cpFromInstance: Copy file/directory from instance to local
- WebSocket-based streaming with JSON control messages
- Supports files and recursive directory operations
- Handles symlinks, permissions, and modification times
- Chunked binary data transfer for efficient streaming

Adds ws as a peer dependency for WebSocket support.

Author: rgarcia

package.json

@@ -26,13 +26,16 @@
     "lint": "./scripts/lint",
     "fix": "./scripts/format"
   },
-  "dependencies": {},
+  "dependencies": {
+    "ws": "^8.14.0"
+  },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.0",
     "@swc/core": "^1.3.102",
     "@swc/jest": "^0.2.29",
     "@types/jest": "^29.4.0",
     "@types/node": "^20.17.6",
+    "@types/ws": "^8.5.10",
     "@typescript-eslint/eslint-plugin": "8.31.1",
     "@typescript-eslint/parser": "8.31.1",
     "eslint": "^9.39.1",

src/lib/cp.ts

@@ -0,0 +1,359 @@
+/**
+ * Copy operations for transferring files to/from running instances.
+ *
+ * This module provides functions for copying files between the local filesystem
+ * and running hypeman instances, similar to `docker cp`.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Configuration for copy operations.
+ */
+export interface CpConfig {
+  /** Base URL for the hypeman API */
+  baseURL: string;
+  /** API key (JWT token) for authentication */
+  apiKey: string;
+}
+
+/**
+ * Options for copying files to an instance.
+ */
+export interface CpToInstanceOptions {
+  /** Instance ID to copy to */
+  instanceId: string;
+  /** Local source path */
+  srcPath: string;
+  /** Destination path in guest */
+  dstPath: string;
+  /** Optional: override file mode/permissions */
+  mode?: number;
+}
+
+/**
+ * Options for copying files from an instance.
+ */
+export interface CpFromInstanceOptions {
+  /** Instance ID to copy from */
+  instanceId: string;
+  /** Source path in guest */
+  srcPath: string;
+  /** Local destination path */
+  dstPath: string;
+  /** Follow symbolic links */
+  followLinks?: boolean;
+}
+
+interface CpRequest {
+  direction: 'to' | 'from';
+  guest_path: string;
+  is_dir?: boolean;
+  mode?: number;
+  follow_links?: boolean;
+}
+
+interface CpFileHeader {
+  type: 'header';
+  path: string;
+  mode: number;
+  is_dir: boolean;
+  is_symlink?: boolean;
+  link_target?: string;
+  size: number;
+  mtime: number;
+}
+
+interface CpEndMarker {
+  type: 'end';
+  final: boolean;
+}
+
+interface CpResult {
+  type: 'result';
+  success: boolean;
+  error?: string;
+  bytes_written?: number;
+}
+
+interface CpError {
+  type: 'error';
+  message: string;
+  path?: string;
+}
+
+type CpMessage = CpFileHeader | CpEndMarker | CpResult | CpError;
+
+/**
+ * Builds the WebSocket URL for the cp endpoint.
+ */
+function buildWsURL(baseURL: string, instanceId: string): string {
+  const url = new URL(baseURL);
+  url.pathname = `/instances/${instanceId}/cp`;
+
+  if (url.protocol === 'https:') {
+    url.protocol = 'wss:';
+  } else if (url.protocol === 'http:') {
+    url.protocol = 'ws:';
+  }
+
+  return url.toString();
+}
+
+/**
+ * Copy a file or directory to a running instance.
+ *
+ * @example
+ * ```typescript
+ * import { cpToInstance } from 'hypeman/lib/cp';
+ *
+ * await cpToInstance({
+ *   baseURL: 'https://api.hypeman.dev',
+ *   apiKey: 'your-api-key',
+ * }, {
+ *   instanceId: 'inst_123',
+ *   srcPath: './local-file.txt',
+ *   dstPath: '/app/file.txt',
+ * });
+ * ```
+ */
+export async function cpToInstance(cfg: CpConfig, opts: CpToInstanceOptions): Promise<void> {
+  // Check if WebSocket is available (Node.js vs browser)
+  const WebSocket = getWebSocket();
+
+  const wsURL = buildWsURL(cfg.baseURL, opts.instanceId);
+
+  // Get file stats
+  const stats = fs.statSync(opts.srcPath);
+  const isDir = stats.isDirectory();
+  const mode = opts.mode ?? stats.mode & 0o777;
+
+  // Connect to WebSocket
+  const ws = new WebSocket(wsURL, {
+    headers: {
+      Authorization: `Bearer ${cfg.apiKey}`,
+    },
+  });
+
+  return new Promise((resolve, reject) => {
+    ws.on('open', () => {
+      // Send initial request
+      const req: CpRequest = {
+        direction: 'to',
+        guest_path: opts.dstPath,
+        is_dir: isDir,
+        mode: mode,
+      };
+      ws.send(JSON.stringify(req));
+
+      if (isDir) {
+        // For directories, just send end marker
+        ws.send(JSON.stringify({ type: 'end' }));
+      } else {
+        // Stream file content
+        const fileStream = fs.createReadStream(opts.srcPath, {
+          highWaterMark: 32 * 1024,
+        });
+
+        fileStream.on('data', (chunk: Buffer) => {
+          ws.send(chunk);
+        });
+
+        fileStream.on('end', () => {
+          ws.send(JSON.stringify({ type: 'end' }));
+        });
+
+        fileStream.on('error', (err) => {
+          ws.close();
+          reject(err);
+        });
+      }
+    });
+
+    ws.on('message', (data: Buffer | string) => {
+      try {
+        const msg = JSON.parse(data.toString()) as CpMessage;
+
+        if (msg.type === 'result') {
+          if (msg.success) {
+            ws.close();
+            resolve();
+          } else {
+            ws.close();
+            reject(new Error(`Copy failed: ${msg.error}`));
+          }
+        } else if (msg.type === 'error') {
+          ws.close();
+          reject(new Error(`Copy error at ${msg.path}: ${msg.message}`));
+        }
+      } catch (e) {
+        // Ignore non-JSON messages
+      }
+    });
+
+    ws.on('error', (err) => {
+      reject(err);
+    });
+
+    ws.on('close', (code, reason) => {
+      if (code !== 1000) {
+        reject(new Error(`WebSocket closed: ${code} ${reason}`));
+      }
+    });
+  });
+}
+
+/**
+ * Copy a file or directory from a running instance.
+ *
+ * @example
+ * ```typescript
+ * import { cpFromInstance } from 'hypeman/lib/cp';
+ *
+ * await cpFromInstance({
+ *   baseURL: 'https://api.hypeman.dev',
+ *   apiKey: 'your-api-key',
+ * }, {
+ *   instanceId: 'inst_123',
+ *   srcPath: '/app/output.txt',
+ *   dstPath: './local-output.txt',
+ * });
+ * ```
+ */
+export async function cpFromInstance(cfg: CpConfig, opts: CpFromInstanceOptions): Promise<void> {
+  const WebSocket = getWebSocket();
+  const wsURL = buildWsURL(cfg.baseURL, opts.instanceId);
+
+  const ws = new WebSocket(wsURL, {
+    headers: {
+      Authorization: `Bearer ${cfg.apiKey}`,
+    },
+  });
+
+  return new Promise((resolve, reject) => {
+    let currentFile: fs.WriteStream | null = null;
+    let currentHeader: CpFileHeader | null = null;
+
+    ws.on('open', () => {
+      // Send initial request
+      const req: CpRequest = {
+        direction: 'from',
+        guest_path: opts.srcPath,
+        follow_links: opts.followLinks ?? false,
+      };
+      ws.send(JSON.stringify(req));
+    });
+
+    ws.on('message', (data: Buffer | string) => {
+      // Try to parse as JSON first
+      if (typeof data === 'string' || (Buffer.isBuffer(data) && !isBinaryData(data))) {
+        try {
+          const msg = JSON.parse(data.toString()) as CpMessage;
+
+          switch (msg.type) {
+            case 'header': {
+              // Close previous file if any
+              if (currentFile) {
+                currentFile.close();
+                currentFile = null;
+              }
+
+              currentHeader = msg as CpFileHeader;
+              const targetPath = path.join(opts.dstPath, currentHeader.path);
+
+              if (currentHeader.is_dir) {
+                fs.mkdirSync(targetPath, { recursive: true, mode: currentHeader.mode });
+              } else if (currentHeader.is_symlink && currentHeader.link_target) {
+                try {
+                  fs.unlinkSync(targetPath);
+                } catch {
+                  // Ignore if doesn't exist
+                }
+                fs.symlinkSync(currentHeader.link_target, targetPath);
+              } else {
+                fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+                currentFile = fs.createWriteStream(targetPath, { mode: currentHeader.mode });
+              }
+              break;
+            }
+
+            case 'end': {
+              const endMsg = msg as CpEndMarker;
+              if (currentFile) {
+                currentFile.close();
+                // Set modification time
+                if (currentHeader && currentHeader.mtime > 0) {
+                  const targetPath = path.join(opts.dstPath, currentHeader.path);
+                  const mtime = new Date(currentHeader.mtime * 1000);
+                  fs.utimesSync(targetPath, mtime, mtime);
+                }
+                currentFile = null;
+                currentHeader = null;
+              }
+
+              if (endMsg.final) {
+                ws.close();
+                resolve();
+              }
+              break;
+            }
+
+            case 'error': {
+              const errMsg = msg as CpError;
+              ws.close();
+              reject(new Error(`Copy error at ${errMsg.path}: ${errMsg.message}`));
+              break;
+            }
+          }
+
+          return;
+        } catch {
+          // Not JSON, treat as binary data
+        }
+      }
+
+      // Binary data - write to current file
+      if (currentFile && Buffer.isBuffer(data)) {
+        currentFile.write(data);
+      }
+    });
+
+    ws.on('error', (err) => {
+      if (currentFile) {
+        currentFile.close();
+      }
+      reject(err);
+    });
+
+    ws.on('close', (code, reason) => {
+      if (currentFile) {
+        currentFile.close();
+      }
+      if (code !== 1000) {
+        reject(new Error(`WebSocket closed: ${code} ${reason}`));
+      }
+    });
+  });
+}
+
+/**
+ * Helper to determine if data looks like binary (not JSON).
+ */
+function isBinaryData(data: Buffer): boolean {
+  // If it starts with '{' or '[', it's likely JSON
+  if (data.length > 0 && (data[0] === 0x7b || data[0] === 0x5b)) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Get WebSocket implementation (works in Node.js).
+ */
+function getWebSocket(): typeof import('ws') {
+  // In Node.js, we use the 'ws' package
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  return require('ws');
+}
+

src/lib/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Manually-maintained library functionality.
+ *
+ * This directory contains custom functionality that extends the auto-generated SDK.
+ * Files in this directory are not modified by the Stainless generator.
+ */
+
+export * from './cp';
+