cli4ai 1.2.0 → 1.2.1

package/dist/core/execute.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Tool execution helper used by `cli4ai run` and routines.
+ *
+ * This refactors the core execution logic so callers can either:
+ * - inherit stdio (interactive `cli4ai run`)
+ * - capture output (routines / orchestration)
+ */
+export type ExecuteCaptureMode = 'inherit' | 'pipe';
+/**
+ * Permission scope levels for tool execution
+ * - read: Only allow read operations (no mutations)
+ * - write: Allow write operations but no destructive actions
+ * - full: Full access (default)
+ */
+export type ScopeLevel = 'read' | 'write' | 'full';
+export interface ExecuteToolOptions {
+    packageName: string;
+    command?: string;
+    args: string[];
+    cwd: string;
+    env?: Record<string, string>;
+    stdin?: string;
+    capture: ExecuteCaptureMode;
+    timeoutMs?: number;
+    teeStderr?: boolean;
+    /** Permission scope for the tool */
+    scope?: ScopeLevel;
+    /** Run in sandboxed environment with restricted file system access */
+    sandbox?: boolean;
+}
+export interface ExecuteToolResult {
+    exitCode: number;
+    durationMs: number;
+    stdout?: string;
+    stderr?: string;
+    packagePath: string;
+    entryPath: string;
+    runtime: 'node';
+}
+export declare class ExecuteToolError extends Error {
+    code: string;
+    details?: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, details?: Record<string, unknown> | undefined);
+}
+/**
+ * Execute a tool command.
+ *
+ * - When capture === 'inherit', the child inherits stdio (interactive).
+ * - When capture === 'pipe', stdout/stderr can be captured and returned.
+ */
+export declare function executeTool(options: ExecuteToolOptions): Promise<ExecuteToolResult>;

package/dist/core/execute.js

@@ -0,0 +1,475 @@
+/**
+ * Tool execution helper used by `cli4ai run` and routines.
+ *
+ * This refactors the core execution logic so callers can either:
+ * - inherit stdio (interactive `cli4ai run`)
+ * - capture output (routines / orchestration)
+ */
+import { spawn, spawnSync } from 'child_process';
+import { resolve } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { createInterface } from 'readline';
+import { platform, homedir } from 'os';
+import { log } from '../lib/cli.js';
+import { findPackage } from './config.js';
+import { loadManifest } from './manifest.js';
+import { getSecret } from './secrets.js';
+/**
+ * Expand ~ to home directory in paths
+ */
+function expandTilde(path) {
+    if (path.startsWith('~/')) {
+        return resolve(homedir(), path.slice(2));
+    }
+    if (path === '~') {
+        return homedir();
+    }
+    return path;
+}
+export class ExecuteToolError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'ExecuteToolError';
+    }
+}
+// Known system tools and how to install them
+const INSTALL_COMMANDS = {
+    'yt-dlp': {
+        check: 'yt-dlp --version',
+        install: {
+            darwin: 'brew install yt-dlp',
+            linux: 'pipx install yt-dlp || sudo apt install -y pipx && pipx install yt-dlp',
+            win32: 'pip install yt-dlp'
+        },
+        description: 'YouTube video/audio downloader'
+    },
+    'gh': {
+        check: 'gh --version',
+        install: {
+            darwin: 'brew install gh',
+            linux: 'sudo apt install gh -y',
+            win32: 'winget install GitHub.cli'
+        },
+        description: 'GitHub CLI'
+    },
+    'ffmpeg': {
+        check: 'ffmpeg -version',
+        install: {
+            darwin: 'brew install ffmpeg',
+            linux: 'sudo apt install ffmpeg -y',
+            win32: 'winget install FFmpeg.FFmpeg'
+        },
+        description: 'Media processing tool'
+    },
+    'node': {
+        check: 'node --version',
+        install: {
+            darwin: 'brew install node',
+            linux: 'curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs',
+            win32: 'winget install OpenJS.NodeJS.LTS'
+        },
+        description: 'JavaScript runtime'
+    }
+};
+/**
+ * Check if a command exists on the system
+ */
+function commandExists(cmd) {
+    // Use spawnSync with argument array to prevent command injection
+    const os = platform();
+    if (os === 'win32') {
+        const result = spawnSync('where', [cmd], { stdio: 'pipe' });
+        return result.status === 0;
+    }
+    const result = spawnSync('which', [cmd], { stdio: 'pipe' });
+    return result.status === 0;
+}
+/**
+ * Prompt user for confirmation
+ */
+async function confirm(message) {
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stderr
+    });
+    return new Promise((resolve) => {
+        rl.question(`${message} [y/N] `, (answer) => {
+            rl.close();
+            resolve(answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes');
+        });
+    });
+}
+/**
+ * Try to install a system dependency
+ */
+async function installDependency(name) {
+    const info = INSTALL_COMMANDS[name];
+    if (!info) {
+        log(`⚠️  Unknown dependency: ${name}`);
+        log(`   Please install it manually`);
+        return false;
+    }
+    const os = platform();
+    const installCmd = info.install[os];
+    if (!installCmd) {
+        log(`⚠️  No install command for ${name} on ${os}`);
+        return false;
+    }
+    log(`\n📦 ${name} - ${info.description}`);
+    log(`   Install command: ${installCmd}\n`);
+    // SECURITY: Warn about curl|bash pattern
+    if (installCmd.includes('curl') && (installCmd.includes('| bash') || installCmd.includes('|bash'))) {
+        log(`⚠️  SECURITY WARNING: This command downloads and executes a script from the internet.`);
+        log(`   Only proceed if you trust the source (${name}).\n`);
+    }
+    const shouldInstall = await confirm(`Install ${name}?`);
+    if (!shouldInstall)
+        return false;
+    log(`\nInstalling ${name}...`);
+    try {
+        // Use spawnSync with shell:true for complex install commands (from trusted INSTALL_COMMANDS list)
+        // This is safe because installCmd comes from hardcoded list, not user input
+        const result = spawnSync(installCmd, {
+            stdio: 'inherit',
+            shell: true
+        });
+        if (result.status === 0) {
+            log(`✓ ${name} installed successfully\n`);
+            return true;
+        }
+        log(`✗ Failed to install ${name}`);
+        log(`  Try running manually: ${installCmd}\n`);
+        return false;
+    }
+    catch {
+        log(`✗ Failed to install ${name}`);
+        log(`  Try running manually: ${installCmd}\n`);
+        return false;
+    }
+}
+/**
+ * Check and install missing peer dependencies
+ */
+async function checkPeerDependencies(pkgPath) {
+    // Try to load cli4ai.json for peer dependencies
+    const cli4aiPath = resolve(pkgPath, 'cli4ai.json');
+    let peerDeps = {};
+    if (existsSync(cli4aiPath)) {
+        try {
+            const cli4ai = JSON.parse(readFileSync(cli4aiPath, 'utf-8'));
+            peerDeps = cli4ai.peerDependencies || {};
+        }
+        catch { }
+    }
+    const missing = [];
+    for (const dep of Object.keys(peerDeps)) {
+        // Skip npm packages (they start with @ or contain /)
+        if (dep.startsWith('@') || dep.includes('/'))
+            continue;
+        if (!commandExists(dep)) {
+            missing.push(dep);
+        }
+    }
+    if (missing.length === 0)
+        return;
+    log(`\n⚠️  Missing system dependencies: ${missing.join(', ')}\n`);
+    for (const dep of missing) {
+        const installed = await installDependency(dep);
+        if (!installed) {
+            throw new ExecuteToolError('MISSING_DEPENDENCY', `Cannot run without ${dep}`, {
+                dependency: dep,
+                packagePath: pkgPath
+            });
+        }
+    }
+}
+/**
+ * Prompt for a secret value
+ */
+async function promptSecret(key, description) {
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stderr
+    });
+    if (description) {
+        log(`  ${description}`);
+    }
+    return new Promise((resolve) => {
+        if (process.stdin.isTTY) {
+            // Hide input
+            process.stderr.write(`  Enter ${key}: `);
+            let value = '';
+            process.stdin.setRawMode(true);
+            process.stdin.resume();
+            process.stdin.setEncoding('utf8');
+            const onData = (char) => {
+                if (char === '\n' || char === '\r') {
+                    process.stdin.setRawMode(false);
+                    process.stdin.removeListener('data', onData);
+                    process.stderr.write('\n');
+                    rl.close();
+                    resolve(value);
+                }
+                else if (char === '\u0003') {
+                    process.exit(1);
+                }
+                else if (char === '\u007F') {
+                    if (value.length > 0)
+                        value = value.slice(0, -1);
+                }
+                else {
+                    value += char;
+                }
+            };
+            process.stdin.on('data', onData);
+        }
+        else {
+            rl.question(`  Enter ${key}: `, (answer) => {
+                rl.close();
+                resolve(answer);
+            });
+        }
+    });
+}
+/**
+ * Check required secrets and prompt for missing ones
+ */
+async function checkAndPromptSecrets(pkgPath, pkgName) {
+    const cli4aiPath = resolve(pkgPath, 'cli4ai.json');
+    const secretsEnv = {};
+    if (!existsSync(cli4aiPath))
+        return secretsEnv;
+    let envDefs = {};
+    try {
+        const cli4ai = JSON.parse(readFileSync(cli4aiPath, 'utf-8'));
+        envDefs = cli4ai.env || {};
+    }
+    catch {
+        return secretsEnv;
+    }
+    const missingRequired = [];
+    for (const [key, def] of Object.entries(envDefs)) {
+        // SECURITY: Use package-scoped secret lookup (tries scoped first, then global)
+        const value = getSecret(key, pkgName);
+        if (value) {
+            secretsEnv[key] = value;
+        }
+        else if (def.required) {
+            missingRequired.push({ key, description: def.description });
+        }
+    }
+    if (missingRequired.length === 0)
+        return secretsEnv;
+    log(`\n⚠️  Missing required secrets for ${pkgName}:\n`);
+    // Import setSecret dynamically to avoid circular dependency issues
+    const { setSecret } = await import('./secrets.js');
+    for (const { key, description } of missingRequired) {
+        const value = await promptSecret(key, description);
+        if (!value) {
+            throw new ExecuteToolError('ENV_MISSING', `${key} is required to run ${pkgName}`, {
+                package: pkgName,
+                secret: key,
+                hint: `Set it with: cli4ai secrets set ${key} --scope ${pkgName}`
+            });
+        }
+        // Expand ~ to home directory for paths
+        const expandedValue = expandTilde(value);
+        // SECURITY: Store secret scoped to package
+        setSecret(key, expandedValue, pkgName);
+        secretsEnv[key] = expandedValue;
+        log(`  ✓ ${key} saved to vault (scoped to ${pkgName})\n`);
+    }
+    log('');
+    return secretsEnv;
+}
+function buildRuntimeCommand(entryPath, cmdArgs) {
+    // Use tsx for TypeScript files, node for JavaScript
+    if (entryPath.endsWith('.ts') || entryPath.endsWith('.tsx')) {
+        return { execCmd: 'npx', execArgs: ['tsx', entryPath, ...cmdArgs], runtime: 'node' };
+    }
+    return { execCmd: 'node', execArgs: [entryPath, ...cmdArgs], runtime: 'node' };
+}
+/**
+ * Build security environment variables for scope and sandbox restrictions
+ */
+function buildSecurityEnv(scope, sandbox, cwd) {
+    const env = {};
+    // Set scope environment variable for tools to respect
+    env.CLI4AI_SCOPE = scope;
+    // Sandbox restrictions
+    if (sandbox) {
+        env.CLI4AI_SANDBOX = '1';
+        // Restrict file system access to temp directories and package directory
+        // Tools should check these env vars and restrict their operations
+        const tmpDir = process.env.TMPDIR || process.env.TMP || process.env.TEMP || '/tmp';
+        env.CLI4AI_SANDBOX_ALLOWED_PATHS = [
+            tmpDir,
+            cwd, // Allow access to current working directory
+        ].join(':');
+        // Restrict network access in sandbox mode
+        // Tools should check this and limit network operations
+        env.CLI4AI_SANDBOX_NETWORK = 'restricted';
+    }
+    return env;
+}
+async function ensureRuntimeAvailable() {
+    if (!commandExists('node')) {
+        log('⚠️  Node.js is required to run this tool\n');
+        const installed = await installDependency('node');
+        if (!installed) {
+            throw new ExecuteToolError('MISSING_DEPENDENCY', 'Node.js is required', {
+                hint: 'Install Node.js: https://nodejs.org/en/download/'
+            });
+        }
+    }
+}
+function collectStream(stream) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        stream.on('data', (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk))));
+        stream.on('error', reject);
+        stream.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+    });
+}
+/**
+ * Execute a tool command.
+ *
+ * - When capture === 'inherit', the child inherits stdio (interactive).
+ * - When capture === 'pipe', stdout/stderr can be captured and returned.
+ */
+export async function executeTool(options) {
+    const startTime = Date.now();
+    const invocationDir = options.cwd;
+    const pkg = findPackage(options.packageName, invocationDir);
+    if (!pkg) {
+        throw new ExecuteToolError('NOT_FOUND', `Package not found: ${options.packageName}`, {
+            hint: 'Run "cli4ai list" to see installed packages, or "cli4ai add <package>" to install'
+        });
+    }
+    const manifest = loadManifest(pkg.path);
+    await ensureRuntimeAvailable();
+    await checkPeerDependencies(pkg.path);
+    const secretsEnv = await checkAndPromptSecrets(pkg.path, options.packageName);
+    const entryPath = resolve(pkg.path, manifest.entry);
+    if (!existsSync(entryPath)) {
+        throw new ExecuteToolError('NOT_FOUND', `Entry point not found: ${entryPath}`, {
+            manifest: resolve(pkg.path, 'cli4ai.json')
+        });
+    }
+    const cmdArgs = [];
+    if (options.command)
+        cmdArgs.push(options.command);
+    cmdArgs.push(...options.args);
+    const { execCmd, execArgs, runtime } = buildRuntimeCommand(entryPath, cmdArgs);
+    const teeStderr = options.teeStderr ?? true;
+    // Build security environment for scope and sandbox
+    const scope = options.scope ?? 'full';
+    const sandbox = options.sandbox ?? false;
+    const securityEnv = buildSecurityEnv(scope, sandbox, invocationDir);
+    // Log security restrictions if active
+    if (scope !== 'full' || sandbox) {
+        const restrictions = [];
+        if (scope !== 'full')
+            restrictions.push(`scope=${scope}`);
+        if (sandbox)
+            restrictions.push('sandbox=enabled');
+        log(`🔒 Security: ${restrictions.join(', ')}`);
+    }
+    if (options.capture === 'inherit') {
+        const proc = spawn(execCmd, execArgs, {
+            stdio: 'inherit',
+            cwd: invocationDir,
+            env: {
+                ...process.env,
+                INIT_CWD: process.env.INIT_CWD ?? invocationDir,
+                CLI4AI_CWD: invocationDir,
+                C4AI_PACKAGE_DIR: pkg.path,
+                C4AI_PACKAGE_NAME: pkg.name,
+                C4AI_ENTRY: entryPath,
+                ...secretsEnv,
+                ...securityEnv,
+                ...(options.env ?? {})
+            }
+        });
+        const exitCode = await new Promise((resolve, reject) => {
+            proc.on('close', (code) => resolve(code ?? 0));
+            proc.on('error', (err) => {
+                reject(new ExecuteToolError('API_ERROR', `Failed to execute: ${err.message}`));
+            });
+        });
+        return {
+            exitCode,
+            durationMs: Date.now() - startTime,
+            packagePath: pkg.path,
+            entryPath,
+            runtime
+        };
+    }
+    // capture === 'pipe'
+    const proc = spawn(execCmd, execArgs, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        cwd: invocationDir,
+        env: {
+            ...process.env,
+            INIT_CWD: process.env.INIT_CWD ?? invocationDir,
+            CLI4AI_CWD: invocationDir,
+            C4AI_PACKAGE_DIR: pkg.path,
+            C4AI_PACKAGE_NAME: pkg.name,
+            C4AI_ENTRY: entryPath,
+            ...secretsEnv,
+            ...securityEnv,
+            ...(options.env ?? {})
+        }
+    });
+    if (options.stdin !== undefined) {
+        proc.stdin.write(options.stdin);
+        proc.stdin.end();
+    }
+    else {
+        // Don’t block on stdin if nothing is provided
+        proc.stdin.end();
+    }
+    if (teeStderr && proc.stderr) {
+        proc.stderr.on('data', (chunk) => {
+            process.stderr.write(chunk);
+        });
+    }
+    const stdoutPromise = proc.stdout ? collectStream(proc.stdout) : Promise.resolve('');
+    const stderrPromise = proc.stderr ? collectStream(proc.stderr) : Promise.resolve('');
+    let timeout;
+    if (options.timeoutMs && options.timeoutMs > 0) {
+        timeout = setTimeout(() => {
+            try {
+                proc.kill('SIGTERM');
+            }
+            catch { }
+            setTimeout(() => {
+                try {
+                    proc.kill('SIGKILL');
+                }
+                catch { }
+            }, 250);
+        }, options.timeoutMs);
+    }
+    const exitCode = await new Promise((resolve, reject) => {
+        proc.on('close', (code) => resolve(code ?? 0));
+        proc.on('error', (err) => reject(new ExecuteToolError('API_ERROR', `Failed to execute: ${err.message}`)));
+    }).finally(() => {
+        if (timeout)
+            clearTimeout(timeout);
+    });
+    const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
+    return {
+        exitCode,
+        durationMs: Date.now() - startTime,
+        stdout,
+        stderr,
+        packagePath: pkg.path,
+        entryPath,
+        runtime
+    };
+}

package/dist/core/link.d.ts

@@ -0,0 +1,39 @@
+/**
+ * PATH linking for global packages
+ *
+ * Creates executable symlinks in ~/.cli4ai/bin/ that can be added to PATH
+ */
+import { type Manifest } from './manifest.js';
+export declare const C4AI_BIN: string;
+/**
+ * Ensure bin directory exists
+ */
+export declare function ensureBinDir(): void;
+/**
+ * Create executable wrapper script for a package
+ *
+ * Creates a shell script that invokes `cli4ai run <package> [args]`
+ */
+export declare function linkPackage(manifest: Manifest, packagePath: string): string;
+/**
+ * Create direct executable wrapper that runs the tool directly
+ *
+ * This is faster than going through cli4ai run
+ */
+export declare function linkPackageDirect(manifest: Manifest, packagePath: string): string;
+/**
+ * Remove executable link for a package
+ */
+export declare function unlinkPackage(packageName: string): boolean;
+/**
+ * Check if a package is linked
+ */
+export declare function isPackageLinked(packageName: string): boolean;
+/**
+ * Get PATH setup instructions
+ */
+export declare function getPathInstructions(): string;
+/**
+ * Check if bin directory is in PATH
+ */
+export declare function isBinInPath(): boolean;