cli4ai 1.0.3 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cli4ai",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "The package manager for AI CLI tools - cli4ai.com",
   "type": "module",
   "bin": {
@@ -16,7 +16,8 @@
   "dependencies": {
     "commander": "^14.0.0",
     "cron-parser": "^4.9.0",
-    "semver": "^7.6.0"
+    "semver": "^7.6.0",
+    "yaml": "^2.8.2"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/cli.ts

@@ -34,6 +34,16 @@ import {
   schedulerHistoryCommand,
   schedulerRunCommand
 } from './commands/scheduler.js';
+import {
+  remotesListCommand,
+  remotesAddCommand,
+  remotesUpdateCommand,
+  remotesRemoveCommand,
+  remotesShowCommand,
+  remotesTestCommand,
+  remotesPackagesCommand
+} from './commands/remotes.js';
+import { serveCommand } from './commands/serve.js';
 
 export function createProgram(): Command {
   const program = new Command()
@@ -94,6 +104,10 @@ export function createProgram(): Command {
     .command('run <package> [command] [args...]')
     .description('Run a tool command')
     .option('-e, --env <vars...>', 'Environment variables (KEY=value)')
+    .option('--scope <level>', 'Permission scope: read, write, or full (default: full)')
+    .option('--sandbox', 'Run in sandboxed environment with restricted file system access')
+    .option('-r, --remote <name>', 'Execute on a remote cli4ai service')
+    .option('--timeout <ms>', 'Timeout in milliseconds')
     // Allow passing tool flags through (e.g. `cli4ai run chrome screenshot --full-page`)
     .allowUnknownOption(true)
     .addHelpText('after', `
@@ -101,10 +115,23 @@ export function createProgram(): Command {
 Examples:
   cli4ai run github trending
   cli4ai run chrome screenshot https://example.com --full-page
+  cli4ai run github list-issues --scope read
+  cli4ai run untrusted-pkg process --sandbox
+  cli4ai run browser screenshot --remote chrome-server
 
 Pass-through:
   Use "--" to pass flags that would otherwise be parsed by cli4ai:
   cli4ai run <pkg> <cmd> -- --help
+
+Security:
+  --scope read    Only allow read operations (no mutations)
+  --scope write   Allow write operations
+  --scope full    Full access (default)
+  --sandbox       Restrict file system access to temp directories
+
+Remote Execution:
+  --remote <name>  Execute on a configured remote service
+                   Use "cli4ai remotes add" to configure remotes
 `)
     .action(withErrorHandling(runCommand));
 
@@ -236,7 +263,7 @@ Pass-through:
     .command('create <name>')
     .description('Create a new routine')
     .option('-g, --global', 'Create routine globally')
-    .option('--type <type>', 'Routine type (bash, json)', 'bash')
+    .option('--type <type>', 'Routine type (yaml, json, bash)', 'yaml')
     .action(withErrorHandling(routinesCreateCommand));
 
   routines
@@ -302,5 +329,81 @@ Pass-through:
     .description('Manually trigger a scheduled routine')
     .action(withErrorHandling(schedulerRunCommand));
 
+  // ═══════════════════════════════════════════════════════════════════════════
+  // REMOTE EXECUTION
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  program
+    .command('serve')
+    .description('Start cli4ai as a remote service')
+    .option('-p, --port <port>', 'Port to listen on', '4100')
+    .option('-H, --host <host>', 'Host to bind to', '0.0.0.0')
+    .option('-k, --api-key <key>', 'API key for authentication')
+    .option('--scope <levels>', 'Comma-separated allowed scopes (read,write,full)')
+    .option('--cwd <dir>', 'Working directory for execution')
+    .addHelpText('after', `
+
+Examples:
+  cli4ai serve                           # Start on port 4100
+  cli4ai serve --port 8080               # Start on port 8080
+  cli4ai serve --api-key mysecretkey     # Require API key
+  cli4ai serve --scope read,write        # Restrict to read/write operations
+
+The service exposes these endpoints:
+  GET  /health              - Service health check
+  GET  /packages            - List available packages
+  GET  /packages/:name      - Get package info
+  POST /run                 - Execute a tool
+  POST /routines/:name/run  - Run a routine
+`)
+    .action(withErrorHandling(serveCommand));
+
+  const remotes = program
+    .command('remotes')
+    .description('Manage remote cli4ai services');
+
+  remotes
+    .command('list')
+    .alias('ls')
+    .description('List configured remotes')
+    .action(withErrorHandling(remotesListCommand));
+
+  remotes
+    .command('add <name> <url>')
+    .description('Add a remote service')
+    .option('-k, --api-key <key>', 'API key for authentication')
+    .option('-d, --description <desc>', 'Description of this remote')
+    .option('--no-test', 'Skip connection test')
+    .action(withErrorHandling(remotesAddCommand));
+
+  remotes
+    .command('update <name>')
+    .description('Update a remote service')
+    .option('-u, --url <url>', 'New URL')
+    .option('-k, --api-key <key>', 'New API key')
+    .option('-d, --description <desc>', 'New description')
+    .action(withErrorHandling(remotesUpdateCommand));
+
+  remotes
+    .command('remove <name>')
+    .alias('rm')
+    .description('Remove a remote')
+    .action(withErrorHandling(remotesRemoveCommand));
+
+  remotes
+    .command('show <name>')
+    .description('Show remote details')
+    .action(withErrorHandling(remotesShowCommand));
+
+  remotes
+    .command('test <name>')
+    .description('Test connection to a remote')
+    .action(withErrorHandling(remotesTestCommand));
+
+  remotes
+    .command('packages <name>')
+    .description('List packages on a remote')
+    .action(withErrorHandling(remotesPackagesCommand));
+
   return program;
 }

package/src/commands/remotes.ts

@@ -0,0 +1,253 @@
+/**
+ * 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(): Promise<void> {
+  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
+    }))
+  });
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ADD REMOTE
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface AddRemoteOptions {
+  apiKey?: string;
+  description?: string;
+  test?: boolean;
+}
+
+export async function remotesAddCommand(
+  name: string,
+  url: string,
+  options: AddRemoteOptions
+): Promise<void> {
+  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;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// UPDATE REMOTE
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface UpdateRemoteOptions {
+  url?: string;
+  apiKey?: string;
+  description?: string;
+}
+
+export async function remotesUpdateCommand(
+  name: string,
+  options: UpdateRemoteOptions
+): Promise<void> {
+  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: string): Promise<void> {
+  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: string): Promise<void> {
+  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: string): Promise<void> {
+  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: string): Promise<void> {
+  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/src/commands/routines.ts

@@ -5,6 +5,7 @@
 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, type RoutineInfo } from '../core/routines.js';
@@ -23,7 +24,7 @@ interface RoutinesRunOptions {
 
 interface RoutinesCreateOptions {
   global?: boolean;
-  type?: 'json' | 'bash';
+  type?: 'yaml' | 'json' | 'bash';
 }
 
 function ensureValidRoutineName(name: string): void {
@@ -139,22 +140,37 @@ function getTargetDir(global: boolean, projectDir: string): string {
 export async function routinesCreateCommand(name: string, options: RoutinesCreateOptions): Promise<void> {
   ensureValidRoutineName(name);
   const projectDir = process.cwd();
-  const type = options.type ?? 'bash';
-  if (type !== 'bash' && type !== 'json') {
+  const type = options.type ?? 'yaml';
+  if (type !== 'yaml' && type !== 'bash' && type !== 'json') {
     outputError('INVALID_INPUT', `Invalid routine type: ${type}`, {
-      allowed: ['bash', 'json']
+      allowed: ['yaml', 'json', 'bash']
     });
   }
   const dir = getTargetDir(!!options.global, projectDir);
 
-  const suffix = type === 'json' ? '.routine.json' : '.routine.sh';
+  const suffixMap: Record<string, string> = {
+    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 === 'json') {
+  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,
@@ -208,8 +224,11 @@ export async function routinesRunCommand(
 
   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 (routine.kind === 'json') {
+    if (isStructured) {
       try {
         const def = loadRoutineDefinition(routine.path);
         const plan = await dryRunRoutine(def, vars, process.cwd());
@@ -252,7 +271,7 @@ export async function routinesRunCommand(
     return;
   }
 
-  if (routine.kind === 'json') {
+  if (isStructured) {
     try {
       const def = loadRoutineDefinition(routine.path);
       const summary = await runRoutine(def, vars, process.cwd());

package/src/commands/run.ts

@@ -2,11 +2,17 @@
  * cli4ai run - Execute a tool command
  */
 
-import { outputError } from '../lib/cli.js';
-import { executeTool, ExecuteToolError } from '../core/execute.js';
+import { output, outputError, log } from '../lib/cli.js';
+import { executeTool, ExecuteToolError, type ScopeLevel } from '../core/execute.js';
+import { remoteRunTool, RemoteConnectionError, RemoteApiError } from '../core/remote-client.js';
+import { getRemote } from '../core/remotes.js';
 
 interface RunOptions {
   env?: string[];
+  scope?: string;
+  sandbox?: boolean;
+  remote?: string;
+  timeout?: string;
 }
 
 export async function runCommand(
@@ -26,6 +32,77 @@ export async function runCommand(
     }
   }
 
+  // Validate scope option
+  let scope: ScopeLevel = 'full';
+  if (options.scope) {
+    const validScopes: ScopeLevel[] = ['read', 'write', 'full'];
+    if (!validScopes.includes(options.scope as ScopeLevel)) {
+      outputError('INVALID_INPUT', `Invalid scope: ${options.scope}`, {
+        validScopes,
+        hint: 'Use --scope read, --scope write, or --scope full'
+      });
+    }
+    scope = options.scope as ScopeLevel;
+  }
+
+  // Parse timeout
+  let timeout: number | undefined;
+  if (options.timeout) {
+    timeout = parseInt(options.timeout, 10);
+    if (isNaN(timeout) || timeout < 0) {
+      outputError('INVALID_INPUT', 'Timeout must be a positive number (milliseconds)');
+    }
+  }
+
+  // Remote execution
+  if (options.remote) {
+    const remote = getRemote(options.remote);
+    if (!remote) {
+      outputError('NOT_FOUND', `Remote "${options.remote}" not found`, {
+        hint: 'Use "cli4ai remotes add <name> <url>" to configure a remote'
+      });
+    }
+
+    log(`Executing on remote: ${remote.name} (${remote.url})`);
+
+    try {
+      const result = await remoteRunTool(options.remote, {
+        package: packageName,
+        command,
+        args,
+        env: Object.keys(extraEnv).length > 0 ? extraEnv : undefined,
+        timeout,
+        scope
+      });
+
+      // Output stdout/stderr
+      if (result.stdout) {
+        process.stdout.write(result.stdout);
+      }
+      if (result.stderr) {
+        process.stderr.write(result.stderr);
+      }
+
+      process.exitCode = result.exitCode;
+
+      if (!result.success && result.error) {
+        log(`Remote error: ${result.error.message}`);
+      }
+
+      return;
+    } catch (err) {
+      if (err instanceof RemoteConnectionError) {
+        outputError('NETWORK_ERROR', err.message, { remote: options.remote, url: remote.url });
+      }
+      if (err instanceof RemoteApiError) {
+        outputError(err.code, err.message, err.details);
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      outputError('API_ERROR', message);
+    }
+  }
+
+  // Local execution
   try {
     const result = await executeTool({
       packageName,
@@ -33,7 +110,10 @@ export async function runCommand(
       args,
       cwd: process.cwd(),
       env: extraEnv,
-      capture: 'inherit'
+      capture: 'inherit',
+      timeoutMs: timeout,
+      scope,
+      sandbox: options.sandbox ?? false
     });
     process.exitCode = result.exitCode;
     return;

package/src/commands/serve.ts

@@ -0,0 +1,66 @@
+/**
+ * Serve command - Start cli4ai as a remote service.
+ *
+ * Allows other cli4ai instances to execute tools on this machine.
+ */
+
+import { output, outputError, log } from '../lib/cli.js';
+import { startService, type StartServiceOptions } from '../server/service.js';
+import type { ScopeLevel } from '../core/execute.js';
+
+export interface ServeCommandOptions {
+  port?: string;
+  host?: string;
+  apiKey?: string;
+  scope?: string;
+  cwd?: string;
+}
+
+export async function serveCommand(options: ServeCommandOptions): Promise<void> {
+  const serviceOptions: StartServiceOptions = {
+    cwd: options.cwd ?? process.cwd()
+  };
+
+  // Parse port
+  if (options.port) {
+    const port = parseInt(options.port, 10);
+    if (isNaN(port) || port < 1 || port > 65535) {
+      outputError('INVALID_INPUT', 'Port must be a number between 1 and 65535');
+    }
+    serviceOptions.port = port;
+  }
+
+  // Parse host
+  if (options.host) {
+    serviceOptions.host = options.host;
+  }
+
+  // API key
+  if (options.apiKey) {
+    serviceOptions.apiKey = options.apiKey;
+  }
+
+  // Parse allowed scopes
+  if (options.scope) {
+    const scopes = options.scope.split(',').map(s => s.trim()) as ScopeLevel[];
+    const validScopes: ScopeLevel[] = ['read', 'write', 'full'];
+
+    for (const scope of scopes) {
+      if (!validScopes.includes(scope)) {
+        outputError('INVALID_INPUT', `Invalid scope "${scope}". Must be one of: read, write, full`);
+      }
+    }
+
+    serviceOptions.allowedScopes = scopes;
+  }
+
+  try {
+    await startService(serviceOptions);
+    output({ status: 'stopped' });
+  } catch (err) {
+    if (err instanceof Error) {
+      outputError('API_ERROR', err.message);
+    }
+    throw err;
+  }
+}