cli4ai 1.2.0 → 1.2.2

package/dist/commands/remotes.js

@@ -0,0 +1,196 @@
+/**
+ * Remote hosts management command.
+ *
+ * Manage connections to remote cli4ai instances for distributed execution.
+ */
+import { output, outputError, log } from '../lib/cli.js';
+import { getRemotes, getRemote, addRemote, updateRemote, removeRemote, RemoteNotFoundError, RemoteAlreadyExistsError, InvalidRemoteUrlError } from '../core/remotes.js';
+import { testRemoteConnection, remoteListPackages } from '../core/remote-client.js';
+// ═══════════════════════════════════════════════════════════════════════════
+// LIST REMOTES
+// ═══════════════════════════════════════════════════════════════════════════
+export async function remotesListCommand() {
+    const remotes = getRemotes();
+    if (remotes.length === 0) {
+        output({ remotes: [], message: 'No remotes configured. Use "cli4ai remotes add <name> <url>" to add one.' });
+        return;
+    }
+    output({
+        remotes: remotes.map(r => ({
+            name: r.name,
+            url: r.url,
+            description: r.description,
+            hasApiKey: !!r.apiKey,
+            addedAt: r.addedAt,
+            lastConnected: r.lastConnected
+        }))
+    });
+}
+export async function remotesAddCommand(name, url, options) {
+    try {
+        const remote = addRemote(name, url, {
+            apiKey: options.apiKey,
+            description: options.description
+        });
+        log(`Added remote: ${remote.name} -> ${remote.url}`);
+        // Test connection if requested
+        if (options.test !== false) {
+            log('Testing connection...');
+            const result = await testRemoteConnection(name);
+            if (result.success) {
+                log(`Connection successful: ${result.message}`);
+                output({
+                    remote: {
+                        name: remote.name,
+                        url: remote.url,
+                        description: remote.description,
+                        hasApiKey: !!remote.apiKey
+                    },
+                    connectionTest: result
+                });
+            }
+            else {
+                log(`Warning: Connection failed - ${result.message}`);
+                log('The remote was added but could not be reached. Check the URL and try again.');
+                output({
+                    remote: {
+                        name: remote.name,
+                        url: remote.url,
+                        description: remote.description,
+                        hasApiKey: !!remote.apiKey
+                    },
+                    connectionTest: result
+                });
+            }
+        }
+        else {
+            output({
+                remote: {
+                    name: remote.name,
+                    url: remote.url,
+                    description: remote.description,
+                    hasApiKey: !!remote.apiKey
+                }
+            });
+        }
+    }
+    catch (err) {
+        if (err instanceof RemoteAlreadyExistsError) {
+            outputError('ALREADY_EXISTS', `Remote "${err.remoteName}" already exists. Use "cli4ai remotes update" to modify it.`);
+        }
+        if (err instanceof InvalidRemoteUrlError) {
+            outputError('INVALID_INPUT', `Invalid URL "${err.url}": ${err.reason}`);
+        }
+        throw err;
+    }
+}
+export async function remotesUpdateCommand(name, options) {
+    try {
+        // Check if any update provided
+        if (!options.url && !options.apiKey && !options.description) {
+            outputError('INVALID_INPUT', 'No updates provided. Use --url, --api-key, or --description.');
+        }
+        const remote = updateRemote(name, options);
+        output({
+            updated: true,
+            remote: {
+                name: remote.name,
+                url: remote.url,
+                description: remote.description,
+                hasApiKey: !!remote.apiKey
+            }
+        });
+    }
+    catch (err) {
+        if (err instanceof RemoteNotFoundError) {
+            outputError('NOT_FOUND', `Remote "${err.remoteName}" not found`);
+        }
+        if (err instanceof InvalidRemoteUrlError) {
+            outputError('INVALID_INPUT', `Invalid URL "${err.url}": ${err.reason}`);
+        }
+        throw err;
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// REMOVE REMOTE
+// ═══════════════════════════════════════════════════════════════════════════
+export async function remotesRemoveCommand(name) {
+    try {
+        removeRemote(name);
+        output({ removed: true, name });
+    }
+    catch (err) {
+        if (err instanceof RemoteNotFoundError) {
+            outputError('NOT_FOUND', `Remote "${err.remoteName}" not found`);
+        }
+        throw err;
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// SHOW REMOTE
+// ═══════════════════════════════════════════════════════════════════════════
+export async function remotesShowCommand(name) {
+    const remote = getRemote(name);
+    if (!remote) {
+        outputError('NOT_FOUND', `Remote "${name}" not found`);
+    }
+    output({
+        name: remote.name,
+        url: remote.url,
+        description: remote.description,
+        hasApiKey: !!remote.apiKey,
+        addedAt: remote.addedAt,
+        lastConnected: remote.lastConnected
+    });
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// TEST REMOTE
+// ═══════════════════════════════════════════════════════════════════════════
+export async function remotesTestCommand(name) {
+    const remote = getRemote(name);
+    if (!remote) {
+        outputError('NOT_FOUND', `Remote "${name}" not found`);
+    }
+    log(`Testing connection to ${remote.name} (${remote.url})...`);
+    const result = await testRemoteConnection(name);
+    if (result.success) {
+        log(`Connection successful!`);
+        output({
+            name,
+            url: remote.url,
+            connected: true,
+            ...result.details
+        });
+    }
+    else {
+        log(`Connection failed: ${result.message}`);
+        output({
+            name,
+            url: remote.url,
+            connected: false,
+            error: result.message
+        });
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// LIST PACKAGES ON REMOTE
+// ═══════════════════════════════════════════════════════════════════════════
+export async function remotesPackagesCommand(name) {
+    const remote = getRemote(name);
+    if (!remote) {
+        outputError('NOT_FOUND', `Remote "${name}" not found`);
+    }
+    try {
+        const result = await remoteListPackages(name);
+        output({
+            remote: name,
+            packages: result.packages
+        });
+    }
+    catch (err) {
+        if (err instanceof Error) {
+            outputError('API_ERROR', `Failed to list packages on remote "${name}": ${err.message}`);
+        }
+        throw err;
+    }
+}

package/dist/commands/remove.d.ts

@@ -0,0 +1,8 @@
+/**
+ * cli4ai remove - Uninstall packages
+ */
+interface RemoveOptions {
+    global?: boolean;
+}
+export declare function removeCommand(packages: string[], options: RemoveOptions): Promise<void>;
+export {};

package/dist/commands/remove.js

@@ -0,0 +1,61 @@
+/**
+ * cli4ai remove - Uninstall packages
+ */
+import { existsSync, rmSync, lstatSync, unlinkSync } from 'fs';
+import { resolve } from 'path';
+import { output, outputError, log } from '../lib/cli.js';
+import { PACKAGES_DIR, LOCAL_PACKAGES_DIR } from '../core/config.js';
+import { unlockPackage } from '../core/lockfile.js';
+import { unlinkPackage as unlinkFromPath } from '../core/link.js';
+const PKG_NAME_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+export async function removeCommand(packages, options) {
+    const results = [];
+    const errors = [];
+    const targetDir = options.global ? PACKAGES_DIR : resolve(process.cwd(), LOCAL_PACKAGES_DIR);
+    const projectDir = process.cwd();
+    for (const pkg of packages) {
+        if (!PKG_NAME_PATTERN.test(pkg)) {
+            errors.push({ package: pkg, error: 'Invalid package name' });
+            continue;
+        }
+        const pkgPath = resolve(targetDir, pkg);
+        if (!existsSync(pkgPath)) {
+            errors.push({ package: pkg, error: 'Not installed' });
+            continue;
+        }
+        try {
+            const stat = lstatSync(pkgPath);
+            if (stat.isSymbolicLink()) {
+                unlinkSync(pkgPath);
+            }
+            else {
+                rmSync(pkgPath, { recursive: true });
+            }
+            results.push({ name: pkg, path: pkgPath });
+            if (options.global) {
+                // Remove from PATH
+                unlinkFromPath(pkg);
+                log(`- ${pkg} (unlinked from PATH)`);
+            }
+            else {
+                log(`- ${pkg}`);
+                // Update lockfile (only for local/project installs)
+                unlockPackage(projectDir, pkg);
+            }
+        }
+        catch (err) {
+            errors.push({
+                package: pkg,
+                error: err instanceof Error ? err.message : String(err)
+            });
+        }
+    }
+    if (errors.length > 0 && results.length === 0) {
+        outputError('INSTALL_ERROR', 'Failed to remove packages', { errors });
+    }
+    output({
+        removed: results,
+        errors: errors.length > 0 ? errors : undefined,
+        location: options.global ? 'global' : 'local'
+    });
+}

package/dist/commands/routines.d.ts

@@ -0,0 +1,29 @@
+/**
+ * cli4ai routines - Manage and run routines
+ */
+interface RoutinesListOptions {
+    global?: boolean;
+    json?: boolean;
+}
+interface RoutinesRunOptions {
+    global?: boolean;
+    var?: string[];
+    dryRun?: boolean;
+}
+interface RoutinesCreateOptions {
+    global?: boolean;
+    type?: 'yaml' | 'json' | 'bash';
+}
+export declare function routinesListCommand(options: RoutinesListOptions): Promise<void>;
+export declare function routinesCreateCommand(name: string, options: RoutinesCreateOptions): Promise<void>;
+export declare function routinesRunCommand(name: string, args: string[], options: RoutinesRunOptions): Promise<void>;
+export declare function routinesShowCommand(name: string, options: {
+    global?: boolean;
+}): Promise<void>;
+export declare function routinesRemoveCommand(name: string, options: {
+    global?: boolean;
+}): Promise<void>;
+export declare function routinesEditCommand(name: string, options: {
+    global?: boolean;
+}): Promise<void>;
+export {};

package/dist/commands/routines.js

@@ -0,0 +1,363 @@
+/**
+ * cli4ai routines - Manage and run routines
+ */
+import { spawn, spawnSync } from 'child_process';
+import { readFileSync, writeFileSync, existsSync, chmodSync, rmSync } from 'fs';
+import { resolve } from 'path';
+import { stringify as stringifyYaml } from 'yaml';
+import { output, outputError, log } from '../lib/cli.js';
+import { ensureCli4aiHome, ensureLocalDir, ROUTINES_DIR, LOCAL_ROUTINES_DIR } from '../core/config.js';
+import { getGlobalRoutines, getLocalRoutines, resolveRoutine, validateRoutineName } from '../core/routines.js';
+import { loadRoutineDefinition, dryRunRoutine, runRoutine, RoutineParseError, RoutineValidationError, RoutineTemplateError } from '../core/routine-engine.js';
+function ensureValidRoutineName(name) {
+    try {
+        validateRoutineName(name);
+    }
+    catch (err) {
+        outputError('INVALID_INPUT', err instanceof Error ? err.message : String(err), { name });
+    }
+}
+function normalizeEnvSegment(value) {
+    return value
+        .trim()
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+}
+function parseVars(vars) {
+    const result = {};
+    if (!vars)
+        return result;
+    for (const entry of vars) {
+        const eq = entry.indexOf('=');
+        if (eq <= 0) {
+            outputError('INVALID_INPUT', `Invalid --var (expected KEY=value): ${entry}`);
+        }
+        const key = entry.slice(0, eq).trim();
+        const value = entry.slice(eq + 1);
+        if (!key) {
+            outputError('INVALID_INPUT', `Invalid --var (empty key): ${entry}`);
+        }
+        result[key] = value;
+    }
+    return result;
+}
+function varsToEnv(vars) {
+    const env = {};
+    for (const [key, value] of Object.entries(vars)) {
+        const envKey = `CLI4AI_VAR_${normalizeEnvSegment(key)}`;
+        env[envKey] = value;
+    }
+    return env;
+}
+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')));
+    });
+}
+export async function routinesListCommand(options) {
+    const local = options.global ? [] : getLocalRoutines(process.cwd());
+    const global = getGlobalRoutines();
+    const routines = [];
+    const seen = new Set();
+    for (const r of local) {
+        routines.push(r);
+        seen.add(r.name);
+    }
+    for (const r of global) {
+        if (!seen.has(r.name)) {
+            routines.push(r);
+            seen.add(r.name);
+        }
+    }
+    if (options.json || !process.stdout.isTTY) {
+        output({
+            routines: routines.map(r => ({
+                name: r.name,
+                kind: r.kind,
+                scope: r.scope,
+                path: r.path
+            })),
+            count: routines.length
+        });
+        return;
+    }
+    if (routines.length === 0) {
+        console.log('No routines found');
+        console.log('\nCreate one: cli4ai routines create <name>\n');
+        return;
+    }
+    console.log(`\nRoutines (${routines.length}):\n`);
+    for (const r of routines) {
+        const scopeTag = r.scope === 'local' ? '' : ' (global)';
+        console.log(`  ${r.name}${scopeTag}  [${r.kind}]`);
+        console.log(`    ${r.path}`);
+    }
+    console.log('');
+}
+function getTargetDir(global, projectDir) {
+    if (global) {
+        ensureCli4aiHome();
+        return ROUTINES_DIR;
+    }
+    ensureLocalDir(projectDir);
+    return resolve(projectDir, LOCAL_ROUTINES_DIR);
+}
+export async function routinesCreateCommand(name, options) {
+    ensureValidRoutineName(name);
+    const projectDir = process.cwd();
+    const type = options.type ?? 'yaml';
+    if (type !== 'yaml' && type !== 'bash' && type !== 'json') {
+        outputError('INVALID_INPUT', `Invalid routine type: ${type}`, {
+            allowed: ['yaml', 'json', 'bash']
+        });
+    }
+    const dir = getTargetDir(!!options.global, projectDir);
+    const suffixMap = {
+        yaml: '.routine.yaml',
+        json: '.routine.json',
+        bash: '.routine.sh'
+    };
+    const suffix = suffixMap[type];
+    const filePath = resolve(dir, `${name}${suffix}`);
+    if (existsSync(filePath)) {
+        outputError('INVALID_INPUT', `Routine already exists: ${name}`, { path: filePath });
+    }
+    if (type === 'yaml') {
+        const template = {
+            version: 1,
+            name,
+            description: 'TODO: describe this routine',
+            vars: {},
+            steps: [],
+            result: '{{steps}}'
+        };
+        writeFileSync(filePath, stringifyYaml(template));
+    }
+    else if (type === 'json') {
+        const template = {
+            version: 1,
+            name,
+            description: 'TODO: describe this routine',
+            vars: {},
+            steps: [],
+            result: '{{steps}}'
+        };
+        writeFileSync(filePath, JSON.stringify(template, null, 2) + '\n');
+    }
+    else {
+        const template = `#!/usr/bin/env bash
+set -euo pipefail
+
+# Example:
+#   cli4ai run github trending
+#
+# Vars passed via --var KEY=value are available as env vars:
+#   CLI4AI_VAR_KEY=value
+
+echo "TODO: implement ${name}" 1>&2
+`;
+        writeFileSync(filePath, template);
+        try {
+            chmodSync(filePath, 0o755);
+        }
+        catch { }
+    }
+    output({
+        action: 'create',
+        name,
+        type,
+        scope: options.global ? 'global' : 'local',
+        path: filePath
+    });
+}
+export async function routinesRunCommand(name, args, options) {
+    ensureValidRoutineName(name);
+    const routine = resolveRoutine(name, process.cwd(), { globalOnly: options.global });
+    if (!routine) {
+        outputError('NOT_FOUND', `Routine not found: ${name}`, {
+            hint: options.global
+                ? 'Create a global routine in ~/.cli4ai/routines'
+                : 'Create a routine in ./.cli4ai/routines or ~/.cli4ai/routines'
+        });
+    }
+    const vars = parseVars(options.var);
+    // Structured routines (YAML or JSON) use the routine engine
+    const isStructured = routine.kind === 'yaml' || routine.kind === 'json';
+    if (options.dryRun) {
+        if (isStructured) {
+            try {
+                const def = loadRoutineDefinition(routine.path);
+                const plan = await dryRunRoutine(def, vars, process.cwd());
+                output({
+                    kind: routine.kind,
+                    scope: routine.scope,
+                    path: routine.path,
+                    ...plan
+                });
+                return;
+            }
+            catch (err) {
+                if (err instanceof RoutineParseError) {
+                    outputError('PARSE_ERROR', err.message, { path: err.path });
+                }
+                if (err instanceof RoutineValidationError || err instanceof RoutineTemplateError) {
+                    outputError('INVALID_INPUT', err.message, err.details);
+                }
+                throw err;
+            }
+        }
+        const plan = {
+            routine: routine.name,
+            kind: routine.kind,
+            scope: routine.scope,
+            path: routine.path,
+            vars,
+            exec: { cmd: 'bash', args: [routine.path, ...args] }
+        };
+        if (!process.stdout.isTTY) {
+            output(plan);
+            return;
+        }
+        console.log(`\nRoutine: ${routine.name} [${routine.kind}]`);
+        console.log(`Path:    ${routine.path}`);
+        console.log(`Vars:    ${Object.keys(vars).length ? JSON.stringify(vars) : '(none)'}`);
+        console.log(`\nWould run:\n  bash ${routine.path}${args.length ? ' ' + args.join(' ') : ''}\n`);
+        return;
+    }
+    if (isStructured) {
+        try {
+            const def = loadRoutineDefinition(routine.path);
+            const summary = await runRoutine(def, vars, process.cwd());
+            output({
+                kind: routine.kind,
+                scope: routine.scope,
+                path: routine.path,
+                ...summary
+            });
+            process.exit(summary.exitCode);
+        }
+        catch (err) {
+            if (err instanceof RoutineParseError) {
+                outputError('PARSE_ERROR', err.message, { path: err.path });
+            }
+            if (err instanceof RoutineValidationError || err instanceof RoutineTemplateError) {
+                outputError('INVALID_INPUT', err.message, err.details);
+            }
+            throw err;
+        }
+    }
+    const startTime = Date.now();
+    const isTTY = process.stdout.isTTY;
+    const varEnv = varsToEnv(vars);
+    const child = spawn('bash', [routine.path, ...args], {
+        cwd: process.cwd(),
+        stdio: isTTY ? 'inherit' : ['pipe', 'pipe', 'pipe'],
+        env: {
+            ...process.env,
+            ...varEnv,
+            C4AI_ROUTINE_NAME: routine.name,
+            C4AI_ROUTINE_PATH: routine.path
+        }
+    });
+    if (isTTY) {
+        const exitCode = await new Promise((resolve) => {
+            child.on('close', (code) => resolve(code ?? 0));
+            child.on('error', (err) => outputError('API_ERROR', `Failed to execute routine: ${err.message}`));
+        });
+        process.exit(exitCode);
+    }
+    // Non-TTY: capture and emit single JSON summary.
+    const stdoutPromise = child.stdout ? collectStream(child.stdout) : Promise.resolve('');
+    const stderrPromise = child.stderr ? collectStream(child.stderr) : Promise.resolve('');
+    if (child.stderr) {
+        child.stderr.on('data', (chunk) => {
+            process.stderr.write(chunk);
+        });
+    }
+    const exitCode = await new Promise((resolve) => {
+        child.on('close', (code) => resolve(code ?? 0));
+        child.on('error', (err) => outputError('API_ERROR', `Failed to execute routine: ${err.message}`));
+    });
+    const [stdout, stderr] = await Promise.all([stdoutPromise, stderrPromise]);
+    output({
+        routine: routine.name,
+        kind: routine.kind,
+        scope: routine.scope,
+        status: exitCode === 0 ? 'success' : 'failed',
+        exitCode,
+        durationMs: Date.now() - startTime,
+        stdout,
+        stderr
+    });
+    process.exit(exitCode);
+}
+export async function routinesShowCommand(name, options) {
+    ensureValidRoutineName(name);
+    const routine = resolveRoutine(name, process.cwd(), { globalOnly: options.global });
+    if (!routine) {
+        outputError('NOT_FOUND', `Routine not found: ${name}`);
+    }
+    const content = readFileSync(routine.path, 'utf-8');
+    if (!process.stdout.isTTY) {
+        output({ routine: routine.name, kind: routine.kind, scope: routine.scope, path: routine.path, content });
+        return;
+    }
+    log(`\n${routine.path}\n`);
+    process.stdout.write(content);
+    if (!content.endsWith('\n'))
+        process.stdout.write('\n');
+}
+export async function routinesRemoveCommand(name, options) {
+    ensureValidRoutineName(name);
+    const routine = resolveRoutine(name, process.cwd(), { globalOnly: options.global });
+    if (!routine) {
+        outputError('NOT_FOUND', `Routine not found: ${name}`);
+    }
+    rmSync(routine.path, { force: true });
+    output({
+        action: 'remove',
+        name: routine.name,
+        scope: routine.scope,
+        kind: routine.kind,
+        path: routine.path
+    });
+}
+export async function routinesEditCommand(name, options) {
+    ensureValidRoutineName(name);
+    const routine = resolveRoutine(name, process.cwd(), { globalOnly: options.global });
+    if (!routine) {
+        outputError('NOT_FOUND', `Routine not found: ${name}`);
+    }
+    const editor = process.env.VISUAL || process.env.EDITOR;
+    if (!editor || !process.stdout.isTTY || !process.stdin.isTTY) {
+        output({
+            action: 'edit',
+            name: routine.name,
+            path: routine.path,
+            hint: editor ? 'Run your editor with the path above' : 'Set $EDITOR (or $VISUAL) to enable `cli4ai routines edit`'
+        });
+        return;
+    }
+    // SECURITY: Parse editor command to prevent shell injection
+    // Common editors may have arguments like "code --wait" or "vim -c 'set nu'"
+    // We split on spaces but this is a simple approach; complex cases should use exec wrapper
+    const editorParts = editor.trim().split(/\s+/);
+    const editorCmd = editorParts[0];
+    const editorArgs = [...editorParts.slice(1), routine.path];
+    // Validate editor command doesn't contain shell metacharacters in the base command
+    if (!/^[a-zA-Z0-9_.\-\/]+$/.test(editorCmd)) {
+        outputError('INVALID_INPUT', 'Invalid $EDITOR value - contains unsafe characters', {
+            editor: editorCmd,
+            hint: 'Set $EDITOR to a simple command like "vim", "nano", or "code --wait"'
+        });
+    }
+    const result = spawnSync(editorCmd, editorArgs, {
+        stdio: 'inherit'
+        // SECURITY: shell: false (default) prevents command injection
+    });
+    process.exit(result.status ?? 1);
+}

package/dist/commands/run.d.ts

@@ -0,0 +1,12 @@
+/**
+ * cli4ai run - Execute a tool command
+ */
+interface RunOptions {
+    env?: string[];
+    scope?: string;
+    sandbox?: boolean;
+    remote?: string;
+    timeout?: string;
+}
+export declare function runCommand(packageName: string, command: string | undefined, args: string[], options: RunOptions): Promise<void>;
+export {};