@rcrsr/rill 0.8.0 → 0.8.2

package/dist/ext/exec/index.js

@@ -0,0 +1,168 @@
+/**
+ * exec Extension Factory
+ *
+ * Provides sandboxed command execution via allowlist/blocklist security controls.
+ * Each declared command becomes a function with argument validation and process isolation.
+ */
+import { runCommand, } from './runner.js';
+// ============================================================
+// FACTORY
+// ============================================================
+/**
+ * Create exec extension with sandboxed command execution.
+ *
+ * Generates one host function per declared command.
+ * Each function validates arguments and spawns processes with security controls.
+ * Returns dispose() function to abort in-flight processes.
+ *
+ * @param config - Command definitions and defaults
+ * @returns ExtensionResult with command functions and dispose
+ *
+ * @example
+ * ```typescript
+ * const execExt = createExecExtension({
+ *   commands: {
+ *     git: {
+ *       binary: 'git',
+ *       allowedArgs: ['status', '--short', 'log'],
+ *       cwd: '/home/user/repo'
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export function createExecExtension(config) {
+    // Apply defaults
+    const globalTimeout = config.timeout ?? 30000; // 30s
+    const globalMaxOutputSize = config.maxOutputSize ?? 1048576; // 1MB
+    const inheritEnv = config.inheritEnv ?? false;
+    // Track in-flight processes for dispose
+    const abortControllers = [];
+    // Helper: get effective timeout (command-specific or global)
+    const getTimeout = (commandConfig) => {
+        return commandConfig.timeout ?? globalTimeout;
+    };
+    // Helper: get effective maxBuffer (command-specific or global)
+    const getMaxBuffer = (commandConfig) => {
+        return commandConfig.maxBuffer ?? globalMaxOutputSize;
+    };
+    // Helper: get effective env (merge parent env if inheritEnv, then overlay command env)
+    const getEnv = (commandConfig) => {
+        if (!inheritEnv && !commandConfig.env) {
+            return undefined; // No env needed
+        }
+        const baseEnv = {};
+        // Copy process.env if inheritEnv is true, filtering out undefined
+        if (inheritEnv) {
+            for (const [key, value] of Object.entries(process.env)) {
+                if (value !== undefined) {
+                    baseEnv[key] = value;
+                }
+            }
+        }
+        // Overlay command-specific env
+        if (commandConfig.env) {
+            Object.assign(baseEnv, commandConfig.env);
+        }
+        return baseEnv;
+    };
+    // ============================================================
+    // GENERATE COMMAND FUNCTIONS
+    // ============================================================
+    const functions = {};
+    for (const [commandName, commandConfig] of Object.entries(config.commands)) {
+        // Create function for this command
+        const commandFn = async (args) => {
+            // Extract args and stdin from RillValue array
+            const argsParam = args[0] ?? [];
+            const stdinParam = args[1];
+            // Convert args to string array
+            const stringArgs = argsParam.map((arg) => String(arg));
+            // Create abort controller for this execution
+            const controller = new AbortController();
+            abortControllers.push(controller);
+            try {
+                // Build effective config with merged defaults
+                const effectiveConfig = {
+                    ...commandConfig,
+                    timeout: getTimeout(commandConfig),
+                    maxBuffer: getMaxBuffer(commandConfig),
+                    env: getEnv(commandConfig),
+                };
+                // Execute command
+                const result = await runCommand(commandName, effectiveConfig, stringArgs, stdinParam, controller.signal);
+                // Return as dict
+                return {
+                    stdout: result.stdout,
+                    stderr: result.stderr,
+                    exitCode: result.exitCode,
+                };
+            }
+            finally {
+                // Remove from tracking list
+                const index = abortControllers.indexOf(controller);
+                if (index !== -1) {
+                    abortControllers.splice(index, 1);
+                }
+            }
+        };
+        // Add to functions object with HostFunctionDefinition structure
+        functions[commandName] = {
+            params: [
+                {
+                    name: 'args',
+                    type: 'list',
+                    description: 'Command arguments',
+                    defaultValue: [],
+                },
+                {
+                    name: 'stdin',
+                    type: 'string',
+                    description: 'Standard input data',
+                    defaultValue: '',
+                },
+            ],
+            fn: commandFn,
+            description: commandConfig.description ?? `Execute ${commandName} command`,
+            returnType: 'dict',
+        };
+    }
+    // ============================================================
+    // INTROSPECTION FUNCTION
+    // ============================================================
+    const commands = async () => {
+        const result = [];
+        for (const [name, commandConfig] of Object.entries(config.commands)) {
+            result.push({
+                name,
+                description: commandConfig.description ?? '',
+            });
+        }
+        return result;
+    };
+    functions['commands'] = {
+        params: [],
+        fn: commands,
+        description: 'List all configured commands',
+        returnType: 'list',
+    };
+    // ============================================================
+    // DISPOSE FUNCTION
+    // ============================================================
+    const dispose = async () => {
+        // Abort all in-flight processes
+        for (const controller of abortControllers) {
+            controller.abort();
+        }
+        // Clear tracking array
+        abortControllers.length = 0;
+    };
+    // ============================================================
+    // EXTENSION RESULT
+    // ============================================================
+    return {
+        ...functions,
+        dispose,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/ext/exec/index.js.map

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

package/dist/ext/exec/runner.d.ts

@@ -0,0 +1,62 @@
+/**
+ * exec Extension Runner
+ *
+ * Handles process spawning with argument validation and security controls.
+ * Uses child_process.execFile() for shell injection prevention.
+ */
+/** Command configuration with security controls */
+export interface CommandConfig {
+    /** Binary executable path */
+    readonly binary: string;
+    /** Optional timeout in milliseconds */
+    readonly timeout?: number | undefined;
+    /** Optional output size limit in bytes */
+    readonly maxBuffer?: number | undefined;
+    /** Allowed arguments (allowlist mode) */
+    readonly allowedArgs?: readonly string[] | undefined;
+    /** Blocked arguments (blocklist mode) */
+    readonly blockedArgs?: readonly string[] | undefined;
+    /** Working directory for command execution */
+    readonly cwd?: string | undefined;
+    /** Environment variables for command */
+    readonly env?: Record<string, string> | undefined;
+    /** Whether command accepts stdin */
+    readonly stdin?: boolean | undefined;
+    /** Optional description for introspection */
+    readonly description?: string | undefined;
+}
+/** Command execution result */
+export interface CommandResult {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: number;
+}
+/**
+ * Execute command with process spawning and security controls.
+ *
+ * Uses execFile() to prevent shell injection attacks.
+ * Validates arguments against allowlist/blocklist rules.
+ * Returns stdout, stderr, and exit code (non-zero exit is not an error).
+ *
+ * @param commandName - Command name for error messages
+ * @param config - Command configuration with security rules
+ * @param args - Command arguments
+ * @param stdinData - Optional stdin data
+ * @param signal - Optional AbortSignal for cancellation
+ * @returns Command result with stdout, stderr, and exitCode
+ * @throws RuntimeError RILL-R004 for validation failures
+ * @throws RuntimeError RILL-R012 for timeout
+ * @throws RuntimeError RILL-R004 for output size limit exceeded
+ * @throws RuntimeError RILL-R004 for binary not found
+ *
+ * @example
+ * ```typescript
+ * const result = await runCommand('git', {
+ *   binary: 'git',
+ *   allowedArgs: ['status', '--short']
+ * }, ['status', '--short']);
+ * // Returns: { stdout: "...", stderr: "", exitCode: 0 }
+ * ```
+ */
+export declare function runCommand(commandName: string, config: CommandConfig, args: readonly string[], stdinData?: string | undefined, signal?: AbortSignal | undefined): Promise<CommandResult>;
+//# sourceMappingURL=runner.d.ts.map

package/dist/ext/exec/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../src/ext/exec/runner.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC5B,6BAA6B;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,0CAA0C;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,yCAAyC;IACzC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACrD,yCAAyC;IACzC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACrD,8CAA8C;IAC9C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,wCAAwC;IACxC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAClD,oCAAoC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,6CAA6C;IAC7C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED,+BAA+B;AAC/B,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAgFD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,UAAU,CAC9B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,EACrB,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,EAC9B,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,GAC/B,OAAO,CAAC,aAAa,CAAC,CAoIxB"}

package/dist/ext/exec/runner.js

@@ -0,0 +1,168 @@
+/**
+ * exec Extension Runner
+ *
+ * Handles process spawning with argument validation and security controls.
+ * Uses child_process.execFile() for shell injection prevention.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { RuntimeError } from '../../error-classes.js';
+const execFileAsync = promisify(execFile);
+// ============================================================
+// VALIDATION
+// ============================================================
+/**
+ * Validate arguments against allowlist/blocklist rules.
+ *
+ * @param args - Command arguments to validate
+ * @param config - Command configuration with security rules
+ * @param commandName - Command name for error messages
+ * @throws RuntimeError RILL-R004 if validation fails
+ */
+function validateArgs(args, config, commandName) {
+    const { allowedArgs, blockedArgs } = config;
+    // Allowlist mode: every arg must be in allowedArgs
+    if (allowedArgs !== undefined) {
+        for (const arg of args) {
+            if (!allowedArgs.includes(arg)) {
+                // EC-14: Arg not in allowlist
+                throw new RuntimeError('RILL-R004', `arg "${arg}" not permitted for command "${commandName}"`, undefined, { commandName, arg, allowedArgs });
+            }
+        }
+    }
+    // Blocklist mode: no arg can be in blockedArgs
+    if (blockedArgs !== undefined) {
+        for (const arg of args) {
+            if (blockedArgs.includes(arg)) {
+                // EC-15: Arg in blocklist
+                throw new RuntimeError('RILL-R004', `arg "${arg}" is blocked for command "${commandName}"`, undefined, { commandName, arg, blockedArgs });
+            }
+        }
+    }
+}
+/**
+ * Check if stdin is supported by the command.
+ *
+ * @param config - Command configuration
+ * @param commandName - Command name for error messages
+ * @param hasStdin - Whether stdin was provided
+ * @throws RuntimeError RILL-R004 if stdin not supported but provided
+ */
+function validateStdin(config, commandName, hasStdin) {
+    if (hasStdin && !config.stdin) {
+        // EC-19: stdin not supported
+        throw new RuntimeError('RILL-R004', `command "${commandName}" does not support stdin`, undefined, { commandName });
+    }
+}
+// ============================================================
+// EXECUTION
+// ============================================================
+/**
+ * Execute command with process spawning and security controls.
+ *
+ * Uses execFile() to prevent shell injection attacks.
+ * Validates arguments against allowlist/blocklist rules.
+ * Returns stdout, stderr, and exit code (non-zero exit is not an error).
+ *
+ * @param commandName - Command name for error messages
+ * @param config - Command configuration with security rules
+ * @param args - Command arguments
+ * @param stdinData - Optional stdin data
+ * @param signal - Optional AbortSignal for cancellation
+ * @returns Command result with stdout, stderr, and exitCode
+ * @throws RuntimeError RILL-R004 for validation failures
+ * @throws RuntimeError RILL-R012 for timeout
+ * @throws RuntimeError RILL-R004 for output size limit exceeded
+ * @throws RuntimeError RILL-R004 for binary not found
+ *
+ * @example
+ * ```typescript
+ * const result = await runCommand('git', {
+ *   binary: 'git',
+ *   allowedArgs: ['status', '--short']
+ * }, ['status', '--short']);
+ * // Returns: { stdout: "...", stderr: "", exitCode: 0 }
+ * ```
+ */
+export async function runCommand(commandName, config, args, stdinData, signal) {
+    // Validate arguments against security rules
+    validateArgs(args, config, commandName);
+    // Validate stdin support
+    validateStdin(config, commandName, stdinData !== undefined);
+    // Prepare execFile options
+    const options = {
+        encoding: 'utf8',
+    };
+    if (config.timeout !== undefined) {
+        options.timeout = config.timeout;
+    }
+    if (config.maxBuffer !== undefined) {
+        options.maxBuffer = config.maxBuffer;
+    }
+    // Add cwd if provided
+    if (config.cwd !== undefined) {
+        options.cwd = config.cwd;
+    }
+    // Add env if provided
+    if (config.env !== undefined) {
+        options.env = config.env;
+    }
+    // Add stdin data if provided
+    if (stdinData !== undefined) {
+        options.input = stdinData;
+    }
+    // Add abort signal if provided
+    if (signal !== undefined) {
+        options.signal = signal;
+    }
+    try {
+        // Execute command using execFile (no shell interpolation)
+        const { stdout, stderr } = await execFileAsync(config.binary, args, options);
+        return {
+            stdout: String(stdout || ''),
+            stderr: String(stderr || ''),
+            exitCode: 0,
+        };
+    }
+    catch (err) {
+        // Handle execution errors
+        if (err && typeof err === 'object') {
+            const execError = err;
+            // EC-16: Binary not found
+            if (execError.code === 'ENOENT') {
+                throw new RuntimeError('RILL-R004', `binary not found: ${config.binary}`, undefined, { commandName, binary: config.binary });
+            }
+            // EC-18: Output exceeds limit (check multiple conditions)
+            const isMaxBufferError = execError.code === 'ERR_CHILD_PROCESS_STDOUT_MAXBUFFER' ||
+                execError.code === 'ERR_CHILD_PROCESS_STDERR_MAXBUFFER' ||
+                (execError.message &&
+                    execError.message.toLowerCase().includes('maxbuffer')) ||
+                (execError.killed === true &&
+                    execError.signal === 'SIGTERM' &&
+                    config.maxBuffer !== undefined);
+            if (isMaxBufferError) {
+                throw new RuntimeError('RILL-R004', `command output exceeds size limit`, undefined, { commandName, maxBuffer: config.maxBuffer });
+            }
+            // EC-17: Timeout (must check after maxBuffer to avoid confusion)
+            if (execError.killed === true && execError.signal === 'SIGTERM') {
+                const timeoutMs = config.timeout || 0;
+                throw new RuntimeError('RILL-R012', `command "${commandName}" timed out (${timeoutMs}ms)`, undefined, { commandName, timeoutMs });
+            }
+            // Non-zero exit code: return as CommandResult (not an error)
+            if ('stdout' in execError && 'stderr' in execError) {
+                // Extract exit code from error
+                const exitCode = 'code' in err && typeof err.code === 'number'
+                    ? err.code
+                    : 1;
+                return {
+                    stdout: String(execError.stdout || ''),
+                    stderr: String(execError.stderr || ''),
+                    exitCode,
+                };
+            }
+        }
+        // Unknown error: re-throw
+        throw err;
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/ext/exec/runner.js.map

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

package/dist/ext/fetch/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Fetch Extension Factory
+ *
+ * Creates host functions for HTTP requests based on endpoint configuration.
+ * Scripts call endpoints with positional args or single dict argument.
+ * All URLs are constructed from config - scripts cannot specify arbitrary URLs.
+ */
+import type { ExtensionResult } from '../../runtime/ext/extensions.js';
+/** Parameter definition for endpoint */
+export interface EndpointParam {
+    readonly name: string;
+    readonly type: 'string' | 'number' | 'bool' | 'dict';
+    readonly required?: boolean | undefined;
+    readonly location: 'path' | 'query' | 'body' | 'header';
+    readonly defaultValue?: string | number | boolean | undefined;
+}
+/** Endpoint configuration with parameter declarations */
+export interface EndpointConfig {
+    readonly method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    readonly path: string;
+    readonly params?: EndpointParam[] | undefined;
+    readonly headers?: Record<string, string> | undefined;
+    readonly body?: 'json' | 'form' | 'text' | undefined;
+    readonly responseFormat?: 'json' | 'text' | undefined;
+    readonly responseShape?: 'body' | 'full' | undefined;
+    readonly description?: string | undefined;
+}
+/** Fetch extension configuration */
+export interface FetchConfig {
+    readonly baseUrl: string;
+    readonly headers?: Record<string, string> | (() => Record<string, string>) | undefined;
+    readonly timeout?: number | undefined;
+    readonly retries?: number | undefined;
+    readonly retryDelay?: number | undefined;
+    readonly maxConcurrent?: number | undefined;
+    readonly responseFormat?: 'json' | 'text' | undefined;
+    readonly responseShape?: 'body' | 'full' | undefined;
+    readonly endpoints: Record<string, EndpointConfig>;
+}
+/**
+ * Create fetch extension with generated endpoint functions.
+ *
+ * Each endpoint in config becomes a host function.
+ * Scripts call endpoints with positional args or single dict.
+ * All URLs constructed from config - scripts cannot create arbitrary URLs.
+ *
+ * @param config - Fetch configuration with endpoints
+ * @returns ExtensionResult with endpoint functions and introspection
+ * @throws Error on invalid configuration
+ *
+ * @example
+ * ```typescript
+ * const api = createFetchExtension({
+ *   baseUrl: 'https://api.example.com',
+ *   endpoints: {
+ *     getUser: {
+ *       method: 'GET',
+ *       path: '/users/:id',
+ *       params: [
+ *         { name: 'id', type: 'string', location: 'path' }
+ *       ]
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare function createFetchExtension(config: FetchConfig): ExtensionResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/ext/fetch/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/ext/fetch/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAmBvE,wCAAwC;AACxC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;IACxD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CAC/D;AAED,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,EAAE,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IACtD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACtD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED,oCAAoC;AACpC,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EACb,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACtB,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAC9B,SAAS,CAAC;IACd,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACtD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACpD;AAgID;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,eAAe,CAoKzE"}