@pocketcoder/host 0.0.2

package/dist/services/command-runner.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Command runner service.
+ *
+ * Executes shell commands in a project directory using execa with
+ * streaming output, timeout enforcement, and output size truncation.
+ */
+export interface CommandOutputCallback {
+    (event: {
+        stdoutChunk?: string;
+        stderrChunk?: string;
+    }): void;
+}
+export interface CommandResult {
+    exitCode: number | null;
+    signal?: string;
+    durationMs: number;
+    truncated: boolean;
+    outputPreview: string;
+}
+/**
+ * Execute a command in the given project directory.
+ *
+ * Streams stdout/stderr chunks via the onOutput callback.
+ * Returns the final result with exit code, signal, duration, and truncation info.
+ */
+export declare function executeCommand(requestId: string, projectId: string, command: string, cwd: string, onOutput: CommandOutputCallback): Promise<CommandResult>;
+/**
+ * Cancel a running command by requestId.
+ * Sends SIGTERM to the process.
+ *
+ * @returns true if the command was found and killed, false if not found
+ */
+export declare function cancelCommand(requestId: string): boolean;
+/**
+ * Check if a command is currently running.
+ */
+export declare function isCommandRunning(requestId: string): boolean;
+/**
+ * Get the count of running commands for a specific project.
+ */
+export declare function getRunningCommandCount(projectId: string): number;
+/**
+ * Kill all running commands (used during shutdown).
+ */
+export declare function killAllCommands(): void;
+//# sourceMappingURL=command-runner.d.ts.map

package/dist/services/command-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-runner.d.ts","sourceRoot":"","sources":["../../src/services/command-runner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,MAAM,WAAW,qBAAqB;IACpC,CAAC,KAAK,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC/D;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AAYD;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,qBAAqB,GAC9B,OAAO,CAAC,aAAa,CAAC,CA2GxB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CASxD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQhE;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAMtC"}

package/dist/services/command-runner.js

@@ -0,0 +1,151 @@
+/**
+ * Command runner service.
+ *
+ * Executes shell commands in a project directory using execa with
+ * streaming output, timeout enforcement, and output size truncation.
+ */
+import { execa } from "execa";
+import { COMMAND_TIMEOUT_MS, MAX_COMMAND_OUTPUT } from "@pocketcoder/shared/constants";
+import { logger } from "../utils/logger.js";
+/** Map of requestId → running command */
+const runningCommands = new Map();
+/**
+ * Execute a command in the given project directory.
+ *
+ * Streams stdout/stderr chunks via the onOutput callback.
+ * Returns the final result with exit code, signal, duration, and truncation info.
+ */
+export async function executeCommand(requestId, projectId, command, cwd, onOutput) {
+    const startTime = Date.now();
+    let totalOutputBytes = 0;
+    let truncated = false;
+    let outputPreview = "";
+    const subprocess = execa(command, {
+        cwd,
+        shell: true,
+        timeout: COMMAND_TIMEOUT_MS,
+        reject: false,
+        buffer: false,
+    });
+    runningCommands.set(requestId, { subprocess, requestId, projectId });
+    // Stream stdout
+    if (subprocess.stdout) {
+        subprocess.stdout.on("data", (chunk) => {
+            if (truncated)
+                return;
+            const chunkStr = chunk.toString("utf-8");
+            const chunkBytes = chunk.length;
+            if (totalOutputBytes + chunkBytes > MAX_COMMAND_OUTPUT) {
+                truncated = true;
+                // Send remaining portion that fits
+                const remaining = MAX_COMMAND_OUTPUT - totalOutputBytes;
+                if (remaining > 0) {
+                    const partial = chunk.subarray(0, remaining).toString("utf-8");
+                    onOutput({ stdoutChunk: partial });
+                    outputPreview += partial;
+                }
+                return;
+            }
+            totalOutputBytes += chunkBytes;
+            onOutput({ stdoutChunk: chunkStr });
+            // Keep first portion for output_preview
+            if (outputPreview.length < 1024) {
+                outputPreview += chunkStr.slice(0, 1024 - outputPreview.length);
+            }
+        });
+    }
+    // Stream stderr
+    if (subprocess.stderr) {
+        subprocess.stderr.on("data", (chunk) => {
+            if (truncated)
+                return;
+            const chunkStr = chunk.toString("utf-8");
+            const chunkBytes = chunk.length;
+            if (totalOutputBytes + chunkBytes > MAX_COMMAND_OUTPUT) {
+                truncated = true;
+                const remaining = MAX_COMMAND_OUTPUT - totalOutputBytes;
+                if (remaining > 0) {
+                    const partial = chunk.subarray(0, remaining).toString("utf-8");
+                    onOutput({ stderrChunk: partial });
+                    outputPreview += partial;
+                }
+                return;
+            }
+            totalOutputBytes += chunkBytes;
+            onOutput({ stderrChunk: chunkStr });
+            if (outputPreview.length < 1024) {
+                outputPreview += chunkStr.slice(0, 1024 - outputPreview.length);
+            }
+        });
+    }
+    try {
+        const result = await subprocess;
+        const durationMs = Date.now() - startTime;
+        runningCommands.delete(requestId);
+        return {
+            exitCode: result.exitCode ?? null,
+            signal: result.signal ?? undefined,
+            durationMs,
+            truncated,
+            outputPreview: outputPreview.slice(0, 1024),
+        };
+    }
+    catch (err) {
+        const durationMs = Date.now() - startTime;
+        runningCommands.delete(requestId);
+        // execa rejects on timeout when reject is false? Actually no —
+        // reject: false means it won't reject on non-zero exit codes or signals.
+        // It still might reject on truly exceptional cases (spawn errors).
+        logger.error(`Command execution error for ${requestId}: ${err instanceof Error ? err.message : String(err)}`);
+        return {
+            exitCode: null,
+            durationMs,
+            truncated,
+            outputPreview: outputPreview.slice(0, 1024),
+        };
+    }
+}
+/**
+ * Cancel a running command by requestId.
+ * Sends SIGTERM to the process.
+ *
+ * @returns true if the command was found and killed, false if not found
+ */
+export function cancelCommand(requestId) {
+    const running = runningCommands.get(requestId);
+    if (!running) {
+        return false;
+    }
+    logger.info(`Cancelling command ${requestId}`);
+    running.subprocess.kill("SIGTERM");
+    return true;
+}
+/**
+ * Check if a command is currently running.
+ */
+export function isCommandRunning(requestId) {
+    return runningCommands.has(requestId);
+}
+/**
+ * Get the count of running commands for a specific project.
+ */
+export function getRunningCommandCount(projectId) {
+    let count = 0;
+    for (const cmd of runningCommands.values()) {
+        if (cmd.projectId === projectId) {
+            count++;
+        }
+    }
+    return count;
+}
+/**
+ * Kill all running commands (used during shutdown).
+ */
+export function killAllCommands() {
+    for (const [requestId, cmd] of runningCommands) {
+        logger.info(`Killing command ${requestId} during shutdown`);
+        cmd.subprocess.kill("SIGTERM");
+    }
+    runningCommands.clear();
+}
+//# sourceMappingURL=command-runner.js.map

package/dist/services/command-runner.js.map

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

package/dist/services/file-watcher.d.ts

@@ -0,0 +1,35 @@
+/**
+ * File watcher service using chokidar.
+ * Watches project directories for changes, debounces events,
+ * and emits fs_changed messages with sequence tracking.
+ */
+import type { FsChangedEvent } from "@pocketcoder/shared";
+export type FsChangedCallback = (event: FsChangedEvent) => void;
+export interface FileWatcherOptions {
+    projectId: string;
+    projectPath: string;
+    onFsChanged: FsChangedCallback;
+    /** Override debounce ms for testing. Defaults to FS_DEBOUNCE_MIN_MS (250). */
+    debounceMs?: number;
+}
+export declare class FileWatcher {
+    private watcher;
+    private pendingChanges;
+    private debounceTimer;
+    private readonly projectId;
+    private readonly projectPath;
+    private readonly onFsChanged;
+    private readonly debounceMs;
+    constructor(options: FileWatcherOptions);
+    /** Start watching the project directory. */
+    start(): void;
+    /** Stop watching and flush any pending changes. */
+    stop(): Promise<void>;
+    /** Whether the watcher is currently active. */
+    get isWatching(): boolean;
+    /** Schedule a debounced flush of pending changes. */
+    private scheduleFlush;
+    /** Flush pending changes as an fs_changed event. */
+    private flush;
+}
+//# sourceMappingURL=file-watcher.d.ts.map

package/dist/services/file-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-watcher.d.ts","sourceRoot":"","sources":["../../src/services/file-watcher.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAY,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAgCpE,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;AAEhE,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,cAAc,CAAkB;IACxC,OAAO,CAAC,aAAa,CAA8C;IACnE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,OAAO,EAAE,kBAAkB;IAOvC,4CAA4C;IAC5C,KAAK,IAAI,IAAI;IA6Bb,mDAAmD;IAC7C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB3B,+CAA+C;IAC/C,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,qDAAqD;IACrD,OAAO,CAAC,aAAa;IAUrB,oDAAoD;IACpD,OAAO,CAAC,KAAK;CA4Bd"}

package/dist/services/file-watcher.js

@@ -0,0 +1,133 @@
+/**
+ * File watcher service using chokidar.
+ * Watches project directories for changes, debounces events,
+ * and emits fs_changed messages with sequence tracking.
+ */
+import { relative } from "node:path";
+import { watch } from "chokidar";
+import { MAX_CHANGES_PER_EVENT, FS_DEBOUNCE_MIN_MS } from "@pocketcoder/shared/constants";
+import { incrementSeq } from "../db/repositories/fs-state.js";
+import { logger } from "../utils/logger.js";
+/** Chokidar event names mapped to FsChange kinds. */
+const EVENT_KIND_MAP = {
+    add: "create",
+    addDir: "create",
+    change: "modify",
+    unlink: "delete",
+    unlinkDir: "delete",
+};
+/**
+ * Ignored patterns from PRD § 6 - File Watcher (chokidar).
+ * Chokidar v4 uses exact string matching for string matchers,
+ * so we use RegExp for glob-like patterns.
+ */
+const IGNORED_PATTERNS = [
+    /(?:^|[/\\])node_modules(?:[/\\]|$)/,
+    /(?:^|[/\\])\.git(?:[/\\]|$)/,
+    /(?:^|[/\\])dist(?:[/\\]|$)/,
+    /(?:^|[/\\])build(?:[/\\]|$)/,
+    /(?:^|[/\\])\.next(?:[/\\]|$)/,
+    /(?:^|[/\\])\.turbo(?:[/\\]|$)/,
+    /(?:^|[/\\])\.cache(?:[/\\]|$)/,
+    /(?:^|[/\\])coverage(?:[/\\]|$)/,
+    /\.log$/,
+    /(?:^|[/\\])(?:pnpm-lock\.yaml|package-lock\.json|yarn\.lock)$/,
+];
+export class FileWatcher {
+    watcher = null;
+    pendingChanges = [];
+    debounceTimer = null;
+    projectId;
+    projectPath;
+    onFsChanged;
+    debounceMs;
+    constructor(options) {
+        this.projectId = options.projectId;
+        this.projectPath = options.projectPath;
+        this.onFsChanged = options.onFsChanged;
+        this.debounceMs = options.debounceMs ?? FS_DEBOUNCE_MIN_MS;
+    }
+    /** Start watching the project directory. */
+    start() {
+        if (this.watcher)
+            return;
+        this.watcher = watch(this.projectPath, {
+            ignored: IGNORED_PATTERNS,
+            persistent: true,
+            ignoreInitial: true,
+        });
+        this.watcher.on("all", (event, filePath) => {
+            const kind = EVENT_KIND_MAP[event];
+            if (!kind)
+                return;
+            const relativePath = relative(this.projectPath, filePath);
+            // Skip empty paths (the root directory itself)
+            if (!relativePath)
+                return;
+            this.pendingChanges.push({ kind, path: relativePath });
+            this.scheduleFlush();
+        });
+        this.watcher.on("error", (err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.error(`File watcher error for project ${this.projectId}: ${message}`);
+        });
+        logger.info(`File watcher started for project ${this.projectId} at ${this.projectPath}`);
+    }
+    /** Stop watching and flush any pending changes. */
+    async stop() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        // Flush remaining changes before closing
+        if (this.pendingChanges.length > 0) {
+            this.flush();
+        }
+        if (this.watcher) {
+            await this.watcher.close();
+            this.watcher = null;
+        }
+        logger.info(`File watcher stopped for project ${this.projectId}`);
+    }
+    /** Whether the watcher is currently active. */
+    get isWatching() {
+        return this.watcher !== null && !this.watcher.closed;
+    }
+    /** Schedule a debounced flush of pending changes. */
+    scheduleFlush() {
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        this.debounceTimer = setTimeout(() => {
+            this.debounceTimer = null;
+            this.flush();
+        }, this.debounceMs);
+    }
+    /** Flush pending changes as an fs_changed event. */
+    flush() {
+        if (this.pendingChanges.length === 0)
+            return;
+        const changes = this.pendingChanges;
+        this.pendingChanges = [];
+        const changesTruncated = changes.length > MAX_CHANGES_PER_EVENT;
+        const truncatedChanges = changesTruncated ? changes.slice(0, MAX_CHANGES_PER_EVENT) : changes;
+        const seq = incrementSeq(this.projectId);
+        const event = {
+            type: "fs_changed",
+            sessionId: this.projectId,
+            payload: {
+                seq,
+                changes: truncatedChanges,
+                ...(changesTruncated ? { changesTruncated: true } : {}),
+            },
+        };
+        try {
+            this.onFsChanged(event);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            logger.error(`Error in fs_changed callback for project ${this.projectId}: ${msg}`);
+        }
+    }
+}
+//# sourceMappingURL=file-watcher.js.map

package/dist/services/file-watcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-watcher.js","sourceRoot":"","sources":["../../src/services/file-watcher.ts"],"names":[],"mappings":"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"}

package/dist/services/filesystem.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Filesystem service for listing, reading, and writing files within a project.
+ */
+import type { FsNode } from "@pocketcoder/shared";
+/**
+ * Validates that a resolved path is within the project root.
+ * Prevents path traversal and symlink escapes.
+ */
+export declare function validatePathWithinProject(projectPath: string, relativePath: string): Promise<string>;
+/**
+ * Validates a path without requiring the target to exist (for new files).
+ * Checks the parent directory is within the project root.
+ */
+export declare function validateParentWithinProject(projectPath: string, relativePath: string): Promise<string>;
+export declare class PathEscapeError extends Error {
+    constructor(message: string);
+}
+export declare class FileTooLargeError extends Error {
+    size: number;
+    limit: number;
+    constructor(size: number, limit: number);
+}
+export declare class UnsupportedFormatError extends Error {
+    constructor(message: string);
+}
+export declare class FileNotFoundError extends Error {
+    constructor(filePath: string);
+}
+export declare class ContentTooLargeError extends Error {
+    size: number;
+    limit: number;
+    constructor(size: number, limit: number);
+}
+/**
+ * Write a file within a project directory.
+ * Creates parent directories if createDirs is true.
+ * Returns path, size, and mtime.
+ * Throws ContentTooLargeError if content exceeds MAX_WRITE_SIZE (1MB).
+ * Throws PathEscapeError if path is outside project root.
+ */
+export declare function writeFile(projectPath: string, relativePath: string, content: string, createDirs?: boolean): Promise<{
+    path: string;
+    size: number;
+    mtime: string;
+}>;
+/**
+ * Read a file within a project directory.
+ * Returns content, encoding, size, and mtime.
+ * Throws FileTooLargeError if file exceeds MAX_FILE_SIZE (10MB).
+ * Throws UnsupportedFormatError if file is binary.
+ * Throws FileNotFoundError if file does not exist.
+ * Throws PathEscapeError if path is outside project root.
+ */
+export declare function readFile(projectPath: string, relativePath: string): Promise<{
+    content: string;
+    encoding: string;
+    size: number;
+    mtime: string;
+}>;
+/**
+ * List directory contents at a given path within a project.
+ * Returns FsNode[] with lazy loading (depth parameter).
+ */
+export declare function listDirectory(projectPath: string, relativePath: string, depth?: number): Promise<{
+    children: FsNode[];
+    truncated: boolean;
+}>;
+//# sourceMappingURL=filesystem.d.ts.map

package/dist/services/filesystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.d.ts","sourceRoot":"","sources":["../../src/services/filesystem.ts"],"names":[],"mappings":"AAAA;;GAEG;AAYH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAGlD;;;GAGG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC,CAkBjB;AAED;;;GAGG;AACH,wBAAsB,2BAA2B,CAC/C,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC,CAWjB;AAED,qBAAa,eAAgB,SAAQ,KAAK;gBAC5B,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;gBACF,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAMxC;AAED,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM;CAI5B;AAED,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,QAAQ,EAAE,MAAM;CAI7B;AAED,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;gBACF,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;CAMxC;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,OAAc,GACzB,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CA6BxD;AAED;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAC5B,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAwC7E;AAeD;;;GAGG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,KAAK,GAAE,MAAU,GAChB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAAC,CAqBrD"}