cloudforge-agent 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kenzo ARAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# CloudForge Agent
+
+Lightweight agent that connects your server to [CloudForge](https://cloud-forge.me) — remote AI coding from anywhere.
+
+CloudForge Agent runs on your server and establishes an outbound WebSocket connection to CloudForge. Your code stays on your server; CloudForge only relays terminal I/O, file operations, and Git commands.
+
+## Features
+
+- **Terminal sessions** via node-pty (full PTY support)
+- **File operations** — browse, read, write files remotely
+- **Git integration** — status, add, commit, push, pull, diff, branch management
+- **Outbound-only connection** — no firewall or port forwarding needed
+- **Auto-reconnection** with exponential backoff
+- **Heartbeat** with system info reporting
+
+## Requirements
+
+- Node.js >= 18
+- A CloudForge account and server token (get one at [cloud-forge.me](https://cloud-forge.me))
+
+## Installation
+
+### npx (quickest)
+
+```bash
+npx cloudforge-agent --token YOUR_TOKEN
+```
+
+### npm global install
+
+```bash
+npm install -g cloudforge-agent
+cloudforge-agent --token YOUR_TOKEN
+```
+
+### From source
+
+```bash
+git clone https://github.com/rascal-3/cloudforge-agent.git
+cd cloudforge-agent
+npm install
+npm run build
+npm start -- --token YOUR_TOKEN
+```
+
+### Docker
+
+```bash
+docker run -d \
+  --name cloudforge-agent \
+  --restart unless-stopped \
+  -v /path/to/projects:/home/user \
+  cloudforge/agent:latest \
+  --token YOUR_TOKEN
+```
+
+## Usage
+
+```bash
+cloudforge-agent --token YOUR_TOKEN [options]
+```
+
+### Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--token` | Server authentication token (required) | — |
+| `--server` | CloudForge server URL | `https://cloud-forge.me` |
+| `--home` | Home directory for terminal sessions | `~` |
+| `--debug` | Enable debug logging | `false` |
+
+### Environment variables
+
+You can also configure via environment variables or a `.env` file:
+
+```bash
+CLOUDFORGE_TOKEN=your_token
+CLOUDFORGE_SERVER=https://cloud-forge.me
+CLOUDFORGE_HOME=/home/user
+CLOUDFORGE_DEBUG=true
+```
+
+## How it works
+
+```
+┌─────────────────────┐          ┌─────────────────────┐
+│   Your Browser      │          │   Your Server        │
+│   (CloudForge UI)   │          │                      │
+│                     │          │   CloudForge Agent   │
+│   Terminal ─────────┤          ├──── node-pty         │
+│   File Tree ────────┤  WebSocket│──── File I/O        │
+│   Git Panel ────────┤◄────────►├──── Git CLI          │
+│   Code Editor ──────┤          │                      │
+└─────────────────────┘          └─────────────────────┘
+                    ▲                    │
+                    │   CloudForge SaaS  │
+                    └── relay only ──────┘
+```
+
+- Agent connects **outbound** to CloudForge (no inbound ports needed)
+- All code stays on your server
+- CloudForge relays commands between your browser and the agent
+
+## Supported AI Coding Tools
+
+CloudForge works with any CLI tool running in the terminal:
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (Anthropic)
+- [Codex CLI](https://github.com/openai/codex) (OpenAI)
+- [Gemini CLI](https://github.com/google/gemini-cli) (Google)
+- [Aider](https://aider.chat/)
+- Any other terminal-based tool
+
+## Development
+
+```bash
+npm install
+npm run dev      # watch mode with tsx
+npm run build    # compile TypeScript
+npm run typecheck
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/config.d.ts

@@ -0,0 +1,35 @@
+/**
+ * CloudForge Agent Configuration
+ */
+export interface AgentConfig {
+    token: string;
+    serverUrl: string;
+    heartbeatInterval: number;
+    reconnectDelay: number;
+    maxReconnectDelay: number;
+    shell: string;
+    homeDir: string;
+    debug: boolean;
+}
+/**
+ * Create agent configuration from environment and CLI options
+ */
+export declare function createConfig(options: {
+    token?: string;
+    serverUrl?: string;
+    debug?: boolean;
+}): AgentConfig;
+/**
+ * Get system information for heartbeat
+ */
+export declare function getSystemInfo(): {
+    os: string;
+    hostname: string;
+    platform: string;
+    arch: string;
+    nodeVersion: string;
+    homeDir: string;
+    shell: string;
+};
+export declare const VERSION = "0.1.0";
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAQH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,iBAAiB,EAAE,MAAM,CAAA;IACzB,cAAc,EAAE,MAAM,CAAA;IACtB,iBAAiB,EAAE,MAAM,CAAA;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,OAAO,CAAA;CACf;AAiBD;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE;IACpC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB,GAAG,WAAW,CAsBd;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI;IAC/B,EAAE,EAAE,MAAM,CAAA;IACV,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;CACd,CAUA;AAED,eAAO,MAAM,OAAO,UAAU,CAAA"}

package/dist/config.js

@@ -0,0 +1,59 @@
+/**
+ * CloudForge Agent Configuration
+ */
+import { config as dotenvConfig } from 'dotenv';
+import os from 'os';
+// Load .env file if exists
+dotenvConfig();
+const DEFAULT_SERVER_URL = 'https://cloud-forge.me';
+const DEFAULT_HEARTBEAT_INTERVAL = 30000; // 30 seconds
+const DEFAULT_RECONNECT_DELAY = 1000; // 1 second
+const MAX_RECONNECT_DELAY = 30000; // 30 seconds
+/**
+ * Get the default shell for the current platform
+ */
+function getDefaultShell() {
+    if (process.platform === 'win32') {
+        return process.env.COMSPEC || 'cmd.exe';
+    }
+    return process.env.SHELL || '/bin/bash';
+}
+/**
+ * Create agent configuration from environment and CLI options
+ */
+export function createConfig(options) {
+    const token = options.token || process.env.CLOUDFORGE_TOKEN;
+    if (!token) {
+        throw new Error('Agent token is required. Use --token flag or set CLOUDFORGE_TOKEN environment variable.');
+    }
+    // Validate token format (cf_ prefix + 32 hex chars)
+    if (!/^cf_[a-f0-9]{32}$/.test(token)) {
+        throw new Error('Invalid token format. Token should start with "cf_" followed by 32 hex characters.');
+    }
+    return {
+        token,
+        serverUrl: options.serverUrl || process.env.CLOUDFORGE_SERVER_URL || DEFAULT_SERVER_URL,
+        heartbeatInterval: DEFAULT_HEARTBEAT_INTERVAL,
+        reconnectDelay: DEFAULT_RECONNECT_DELAY,
+        maxReconnectDelay: MAX_RECONNECT_DELAY,
+        shell: getDefaultShell(),
+        homeDir: os.homedir(),
+        debug: options.debug || process.env.CLOUDFORGE_DEBUG === 'true',
+    };
+}
+/**
+ * Get system information for heartbeat
+ */
+export function getSystemInfo() {
+    return {
+        os: `${os.type()} ${os.release()}`,
+        hostname: os.hostname(),
+        platform: process.platform,
+        arch: process.arch,
+        nodeVersion: process.version,
+        homeDir: os.homedir(),
+        shell: getDefaultShell(),
+    };
+}
+export const VERSION = '0.1.0';
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,IAAI,YAAY,EAAE,MAAM,QAAQ,CAAA;AAC/C,OAAO,EAAE,MAAM,IAAI,CAAA;AAEnB,2BAA2B;AAC3B,YAAY,EAAE,CAAA;AAad,MAAM,kBAAkB,GAAG,wBAAwB,CAAA;AACnD,MAAM,0BAA0B,GAAG,KAAK,CAAA,CAAC,aAAa;AACtD,MAAM,uBAAuB,GAAG,IAAI,CAAA,CAAC,WAAW;AAChD,MAAM,mBAAmB,GAAG,KAAK,CAAA,CAAC,aAAa;AAE/C;;GAEG;AACH,SAAS,eAAe;IACtB,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,SAAS,CAAA;IACzC,CAAC;IACD,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,IAAI,WAAW,CAAA;AACzC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,OAI5B;IACC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAA;IAE3D,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,yFAAyF,CAAC,CAAA;IAC5G,CAAC;IAED,oDAAoD;IACpD,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CAAC,oFAAoF,CAAC,CAAA;IACvG,CAAC;IAED,OAAO;QACL,KAAK;QACL,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,qBAAqB,IAAI,kBAAkB;QACvF,iBAAiB,EAAE,0BAA0B;QAC7C,cAAc,EAAE,uBAAuB;QACvC,iBAAiB,EAAE,mBAAmB;QACtC,KAAK,EAAE,eAAe,EAAE;QACxB,OAAO,EAAE,EAAE,CAAC,OAAO,EAAE;QACrB,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,KAAK,MAAM;KAChE,CAAA;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa;IAS3B,OAAO;QACL,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE;QAClC,QAAQ,EAAE,EAAE,CAAC,QAAQ,EAAE;QACvB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,WAAW,EAAE,OAAO,CAAC,OAAO;QAC5B,OAAO,EAAE,EAAE,CAAC,OAAO,EAAE;QACrB,KAAK,EAAE,eAAe,EAAE;KACzB,CAAA;AACH,CAAC;AAED,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAA"}

package/dist/files.d.ts

@@ -0,0 +1,84 @@
+/**
+ * CloudForge Agent File Manager
+ * Manages file operations for remote file access
+ */
+import type { AgentConfig } from './config.js';
+export interface FileEntry {
+    name: string;
+    path: string;
+    type: 'file' | 'directory' | 'symlink' | 'other';
+    size: number;
+    modified: string;
+    permissions: string;
+}
+export interface ReadFileResult {
+    path: string;
+    content: string;
+    encoding: 'utf8' | 'base64';
+    size: number;
+    isBinary: boolean;
+}
+export interface WriteFileResult {
+    path: string;
+    success: boolean;
+    bytesWritten: number;
+}
+export interface FileOperationResult {
+    path: string;
+    success: boolean;
+    error?: string;
+}
+export declare class FileManager {
+    private config;
+    private basePath;
+    constructor(config: AgentConfig);
+    /**
+     * Validate and resolve a path, preventing directory traversal attacks
+     */
+    private resolvePath;
+    /**
+     * Check if a file is binary based on extension
+     */
+    private isBinaryFile;
+    /**
+     * Convert file stats to permissions string
+     */
+    private formatPermissions;
+    /**
+     * Get file type from stats
+     */
+    private getFileType;
+    /**
+     * List directory contents
+     */
+    list(dirPath: string): Promise<FileEntry[]>;
+    /**
+     * Read file contents
+     */
+    read(filePath: string): Promise<ReadFileResult>;
+    /**
+     * Write file contents
+     */
+    write(filePath: string, content: string, encoding?: 'utf8' | 'base64'): Promise<WriteFileResult>;
+    /**
+     * Delete a file or directory
+     */
+    delete(targetPath: string, recursive?: boolean): Promise<FileOperationResult>;
+    /**
+     * Create a directory
+     */
+    mkdir(dirPath: string, recursive?: boolean): Promise<FileOperationResult>;
+    /**
+     * Rename/move a file or directory
+     */
+    rename(fromPath: string, toPath: string): Promise<FileOperationResult>;
+    /**
+     * Get file/directory stats
+     */
+    stat(targetPath: string): Promise<FileEntry | null>;
+    /**
+     * Check if path exists
+     */
+    exists(targetPath: string): Promise<boolean>;
+}
+//# sourceMappingURL=files.d.ts.map

package/dist/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAgB9C,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAA;IAChD,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAA;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,OAAO,CAAA;IAChB,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,QAAQ,CAAQ;gBAEZ,MAAM,EAAE,WAAW;IAK/B;;OAEG;IACH,OAAO,CAAC,WAAW;IAqBnB;;OAEG;IACH,OAAO,CAAC,YAAY;IAKpB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAQzB;;OAEG;IACH,OAAO,CAAC,WAAW;IAOnB;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAyCjD;;OAEG;IACG,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAsCrD;;OAEG;IACG,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,GAAG,QAAiB,GAAG,OAAO,CAAC,eAAe,CAAC;IA6B9G;;OAEG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,GAAE,OAAe,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA2B1F;;OAEG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,OAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAgBrF;;OAEG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAmB5E;;OAEG;IACG,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAsBzD;;OAEG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CASnD"}

package/dist/files.js

@@ -0,0 +1,285 @@
+/**
+ * CloudForge Agent File Manager
+ * Manages file operations for remote file access
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import chalk from 'chalk';
+// Maximum file size to read (5MB)
+const MAX_FILE_SIZE = 5 * 1024 * 1024;
+// Binary file extensions
+const BINARY_EXTENSIONS = new Set([
+    '.png', '.jpg', '.jpeg', '.gif', '.webp', '.ico', '.svg',
+    '.pdf', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx',
+    '.zip', '.tar', '.gz', '.rar', '.7z',
+    '.exe', '.dll', '.so', '.dylib',
+    '.mp3', '.mp4', '.avi', '.mkv', '.mov',
+    '.ttf', '.otf', '.woff', '.woff2',
+    '.pyc', '.class', '.o', '.a',
+]);
+export class FileManager {
+    config;
+    basePath;
+    constructor(config) {
+        this.config = config;
+        this.basePath = config.homeDir;
+    }
+    /**
+     * Validate and resolve a path, preventing directory traversal attacks
+     */
+    resolvePath(requestedPath) {
+        // Expand ~ to home directory
+        let expanded = requestedPath;
+        if (expanded === '~' || expanded.startsWith('~/')) {
+            expanded = expanded.replace('~', os.homedir());
+        }
+        // Normalize the path
+        const normalized = path.normalize(expanded);
+        // If it's an absolute path, use it directly
+        // If it's relative, resolve from basePath
+        const resolved = path.isAbsolute(normalized)
+            ? normalized
+            : path.resolve(this.basePath, normalized);
+        // For security, we don't restrict to basePath - the agent runs on user's server
+        // User already has full access to their filesystem via terminal
+        return resolved;
+    }
+    /**
+     * Check if a file is binary based on extension
+     */
+    isBinaryFile(filePath) {
+        const ext = path.extname(filePath).toLowerCase();
+        return BINARY_EXTENSIONS.has(ext);
+    }
+    /**
+     * Convert file stats to permissions string
+     */
+    formatPermissions(mode) {
+        const perms = ['---', '--x', '-w-', '-wx', 'r--', 'r-x', 'rw-', 'rwx'];
+        const user = perms[(mode >> 6) & 7];
+        const group = perms[(mode >> 3) & 7];
+        const other = perms[mode & 7];
+        return `${user}${group}${other}`;
+    }
+    /**
+     * Get file type from stats
+     */
+    getFileType(stats) {
+        if (stats.isFile())
+            return 'file';
+        if (stats.isDirectory())
+            return 'directory';
+        if (stats.isSymbolicLink())
+            return 'symlink';
+        return 'other';
+    }
+    /**
+     * List directory contents
+     */
+    async list(dirPath) {
+        const resolvedPath = this.resolvePath(dirPath);
+        if (this.config.debug) {
+            console.log(chalk.gray(`Files list: ${resolvedPath}`));
+        }
+        const entries = await fs.readdir(resolvedPath, { withFileTypes: true });
+        const results = [];
+        for (const entry of entries) {
+            try {
+                const entryPath = path.join(resolvedPath, entry.name);
+                const stats = await fs.stat(entryPath);
+                results.push({
+                    name: entry.name,
+                    path: entryPath,
+                    type: this.getFileType(stats),
+                    size: stats.size,
+                    modified: stats.mtime.toISOString(),
+                    permissions: this.formatPermissions(stats.mode),
+                });
+            }
+            catch (err) {
+                // Skip entries we can't stat (permission denied, etc.)
+                if (this.config.debug) {
+                    console.log(chalk.yellow(`Cannot stat: ${entry.name}`));
+                }
+            }
+        }
+        // Sort: directories first, then files, alphabetically
+        results.sort((a, b) => {
+            if (a.type === 'directory' && b.type !== 'directory')
+                return -1;
+            if (a.type !== 'directory' && b.type === 'directory')
+                return 1;
+            return a.name.localeCompare(b.name);
+        });
+        return results;
+    }
+    /**
+     * Read file contents
+     */
+    async read(filePath) {
+        const resolvedPath = this.resolvePath(filePath);
+        if (this.config.debug) {
+            console.log(chalk.gray(`File read: ${resolvedPath}`));
+        }
+        // Check file size first
+        const stats = await fs.stat(resolvedPath);
+        if (stats.size > MAX_FILE_SIZE) {
+            throw new Error(`File too large (${stats.size} bytes). Maximum size is ${MAX_FILE_SIZE} bytes.`);
+        }
+        const isBinary = this.isBinaryFile(resolvedPath);
+        if (isBinary) {
+            // Read as base64 for binary files
+            const buffer = await fs.readFile(resolvedPath);
+            return {
+                path: resolvedPath,
+                content: buffer.toString('base64'),
+                encoding: 'base64',
+                size: stats.size,
+                isBinary: true,
+            };
+        }
+        else {
+            // Read as UTF-8 for text files
+            const content = await fs.readFile(resolvedPath, 'utf8');
+            return {
+                path: resolvedPath,
+                content,
+                encoding: 'utf8',
+                size: stats.size,
+                isBinary: false,
+            };
+        }
+    }
+    /**
+     * Write file contents
+     */
+    async write(filePath, content, encoding = 'utf8') {
+        const resolvedPath = this.resolvePath(filePath);
+        if (this.config.debug) {
+            console.log(chalk.gray(`File write: ${resolvedPath}`));
+        }
+        // Ensure parent directory exists
+        const dir = path.dirname(resolvedPath);
+        await fs.mkdir(dir, { recursive: true });
+        if (encoding === 'base64') {
+            const buffer = Buffer.from(content, 'base64');
+            await fs.writeFile(resolvedPath, buffer);
+            return {
+                path: resolvedPath,
+                success: true,
+                bytesWritten: buffer.length,
+            };
+        }
+        else {
+            await fs.writeFile(resolvedPath, content, 'utf8');
+            return {
+                path: resolvedPath,
+                success: true,
+                bytesWritten: Buffer.byteLength(content, 'utf8'),
+            };
+        }
+    }
+    /**
+     * Delete a file or directory
+     */
+    async delete(targetPath, recursive = false) {
+        const resolvedPath = this.resolvePath(targetPath);
+        if (this.config.debug) {
+            console.log(chalk.gray(`File delete: ${resolvedPath}, recursive=${recursive}`));
+        }
+        try {
+            const stats = await fs.stat(resolvedPath);
+            if (stats.isDirectory()) {
+                if (recursive) {
+                    await fs.rm(resolvedPath, { recursive: true, force: true });
+                }
+                else {
+                    await fs.rmdir(resolvedPath);
+                }
+            }
+            else {
+                await fs.unlink(resolvedPath);
+            }
+            return { path: resolvedPath, success: true };
+        }
+        catch (err) {
+            const error = err;
+            return { path: resolvedPath, success: false, error: error.message };
+        }
+    }
+    /**
+     * Create a directory
+     */
+    async mkdir(dirPath, recursive = true) {
+        const resolvedPath = this.resolvePath(dirPath);
+        if (this.config.debug) {
+            console.log(chalk.gray(`Mkdir: ${resolvedPath}`));
+        }
+        try {
+            await fs.mkdir(resolvedPath, { recursive });
+            return { path: resolvedPath, success: true };
+        }
+        catch (err) {
+            const error = err;
+            return { path: resolvedPath, success: false, error: error.message };
+        }
+    }
+    /**
+     * Rename/move a file or directory
+     */
+    async rename(fromPath, toPath) {
+        const resolvedFrom = this.resolvePath(fromPath);
+        const resolvedTo = this.resolvePath(toPath);
+        if (this.config.debug) {
+            console.log(chalk.gray(`Rename: ${resolvedFrom} -> ${resolvedTo}`));
+        }
+        try {
+            // Ensure parent directory of destination exists
+            await fs.mkdir(path.dirname(resolvedTo), { recursive: true });
+            await fs.rename(resolvedFrom, resolvedTo);
+            return { path: resolvedTo, success: true };
+        }
+        catch (err) {
+            const error = err;
+            return { path: resolvedTo, success: false, error: error.message };
+        }
+    }
+    /**
+     * Get file/directory stats
+     */
+    async stat(targetPath) {
+        const resolvedPath = this.resolvePath(targetPath);
+        if (this.config.debug) {
+            console.log(chalk.gray(`Stat: ${resolvedPath}`));
+        }
+        try {
+            const stats = await fs.stat(resolvedPath);
+            return {
+                name: path.basename(resolvedPath),
+                path: resolvedPath,
+                type: this.getFileType(stats),
+                size: stats.size,
+                modified: stats.mtime.toISOString(),
+                permissions: this.formatPermissions(stats.mode),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Check if path exists
+     */
+    async exists(targetPath) {
+        const resolvedPath = this.resolvePath(targetPath);
+        try {
+            await fs.access(resolvedPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=files.js.map

package/dist/files.js.map

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