cli4ai 1.0.3 → 1.1.0

package/src/core/config.ts

@@ -104,6 +104,12 @@ export interface Config {
     port: number;
   };
 
+  // Audit logging configuration
+  audit: {
+    /** Enable audit logging for MCP tool calls */
+    enabled: boolean;
+  };
+
   // Telemetry (future)
   telemetry: boolean;
 }
@@ -128,6 +134,9 @@ export const DEFAULT_CONFIG: Config = {
     transport: 'stdio',
     port: 3100
   },
+  audit: {
+    enabled: true
+  },
   telemetry: false
 };
 
@@ -197,6 +206,12 @@ function deepMerge(target: Config, source: Partial<Config>): Config {
       port: source.mcp.port ?? target.mcp.port
     };
   }
+  // Deep merge audit config
+  if (source.audit !== undefined) {
+    result.audit = {
+      enabled: source.audit.enabled ?? target.audit.enabled
+    };
+  }
 
   return result;
 }
@@ -334,7 +349,14 @@ export function addLocalRegistry(path: string): void {
  */
 export function removeLocalRegistry(path: string): void {
   const absolutePath = resolve(path);
-  const safePath = validateSymlinkTarget(absolutePath) ?? absolutePath;
+
+  // SECURITY: Validate symlink target consistently with addLocalRegistry
+  const safePath = validateSymlinkTarget(absolutePath);
+  if (!safePath) {
+    outputError('INVALID_INPUT', `Registry path points to an unsafe location: ${absolutePath}`, {
+      hint: 'Symlinks must point to directories within safe locations'
+    });
+  }
 
   let removed = false;
   updateConfig((config) => {
@@ -536,7 +558,7 @@ export function getGlobalPackages(): InstalledPackage[] {
           name: manifest.name,
           version: manifest.version,
           path: safePath,
-          source: 'local', // TODO: track actual source
+          source: 'registry',
           installedAt: new Date().toISOString()
         });
       } catch {

package/src/core/execute.ts

@@ -31,6 +31,14 @@ function expandTilde(path: string): string {
 
 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;
@@ -41,6 +49,10 @@ export interface ExecuteToolOptions {
   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 {
@@ -348,6 +360,39 @@ function buildRuntimeCommand(entryPath: string, cmdArgs: string[]): { execCmd: s
   return { execCmd: 'node', execArgs: [entryPath, ...cmdArgs], runtime: 'node' };
 }
 
+/**
+ * Build security environment variables for scope and sandbox restrictions
+ */
+function buildSecurityEnv(
+  scope: ScopeLevel,
+  sandbox: boolean,
+  cwd: string
+): Record<string, string> {
+  const env: Record<string, string> = {};
+
+  // 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(): Promise<void> {
   if (!commandExists('node')) {
     log('⚠️  Node.js is required to run this tool\n');
@@ -409,6 +454,19 @@ export async function executeTool(options: ExecuteToolOptions): Promise<ExecuteT
 
   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: string[] = [];
+    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',
@@ -421,6 +479,7 @@ export async function executeTool(options: ExecuteToolOptions): Promise<ExecuteT
         C4AI_PACKAGE_NAME: pkg.name,
         C4AI_ENTRY: entryPath,
         ...secretsEnv,
+        ...securityEnv,
         ...(options.env ?? {})
       }
     });
@@ -453,6 +512,7 @@ export async function executeTool(options: ExecuteToolOptions): Promise<ExecuteT
       C4AI_PACKAGE_NAME: pkg.name,
       C4AI_ENTRY: entryPath,
       ...secretsEnv,
+      ...securityEnv,
       ...(options.env ?? {})
     }
   });

package/src/core/link.ts

@@ -204,6 +204,21 @@ export function isPackageLinked(packageName: string): boolean {
  * Get PATH setup instructions
  */
 export function getPathInstructions(): string {
+  if (process.platform === 'win32') {
+    return `
+To use globally installed cli4ai packages from anywhere, add the bin directory to your PATH:
+
+  ${C4AI_BIN}
+
+On Windows, you can:
+1. Use System Settings > Edit environment variables (GUI)
+2. Or run in PowerShell (current session): $env:PATH += ";${C4AI_BIN}"
+3. Or run in PowerShell (permanent): [Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";${C4AI_BIN}", "User")
+
+Then restart your terminal.
+`.trim();
+  }
+
   const shell = process.env.SHELL || '/bin/bash';
   const isZsh = shell.includes('zsh');
   const rcFile = isZsh ? '~/.zshrc' : '~/.bashrc';
@@ -226,5 +241,6 @@ Or start a new terminal session.
  */
 export function isBinInPath(): boolean {
   const pathEnv = process.env.PATH || '';
-  return pathEnv.split(':').some(p => resolve(p) === C4AI_BIN);
+  const separator = process.platform === 'win32' ? ';' : ':';
+  return pathEnv.split(separator).some(p => resolve(p) === C4AI_BIN);
 }

package/src/core/remote-client.ts

@@ -0,0 +1,419 @@
+/**
+ * Remote client for executing cli4ai commands on remote hosts.
+ *
+ * This module provides functions to call remote cli4ai services
+ * configured via `cli4ai remotes add`.
+ */
+
+import { request as httpRequest, type RequestOptions, type OutgoingHttpHeaders } from 'http';
+import { request as httpsRequest } from 'https';
+import { getRemoteOrThrow, updateRemoteLastConnected, type RemoteHost } from './remotes.js';
+import type { ScopeLevel } from './execute.js';
+import type { RoutineRunSummary } from './routine-engine.js';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TYPES
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface RemoteRunOptions {
+  /** Package name to execute */
+  package: string;
+  /** Command within the package */
+  command?: string;
+  /** Arguments to pass */
+  args?: string[];
+  /** Environment variables */
+  env?: Record<string, string>;
+  /** Standard input to pass */
+  stdin?: string;
+  /** Timeout in milliseconds */
+  timeout?: number;
+  /** Scope level for execution */
+  scope?: ScopeLevel;
+}
+
+export interface RemoteRunResult {
+  success: boolean;
+  exitCode: number;
+  stdout?: string;
+  stderr?: string;
+  durationMs: number;
+  error?: {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+  };
+}
+
+export interface RemoteHealthResult {
+  status: 'ok';
+  hostname: string;
+  version: string;
+  uptime: number;
+}
+
+export interface RemotePackageInfo {
+  name: string;
+  version: string;
+  description?: string;
+  commands?: Record<string, { description: string }>;
+}
+
+export interface RemotePackageList {
+  packages: Array<{
+    name: string;
+    version: string;
+    path: string;
+    source: 'local' | 'registry';
+  }>;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ERRORS
+// ═══════════════════════════════════════════════════════════════════════════
+
+export class RemoteConnectionError extends Error {
+  constructor(
+    public remoteName: string,
+    public url: string,
+    message: string
+  ) {
+    super(`Failed to connect to remote "${remoteName}" at ${url}: ${message}`);
+    this.name = 'RemoteConnectionError';
+  }
+}
+
+export class RemoteApiError extends Error {
+  constructor(
+    public remoteName: string,
+    public statusCode: number,
+    public code: string,
+    message: string,
+    public details?: Record<string, unknown>
+  ) {
+    super(`Remote "${remoteName}" error [${code}]: ${message}`);
+    this.name = 'RemoteApiError';
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HTTP CLIENT
+// ═══════════════════════════════════════════════════════════════════════════
+
+interface HttpResponse {
+  statusCode: number;
+  body: string;
+}
+
+function makeRequest(
+  url: URL,
+  method: string,
+  headers: Record<string, string>,
+  body?: string,
+  timeoutMs: number = 30000
+): Promise<HttpResponse> {
+  return new Promise((resolve, reject) => {
+    const isHttps = url.protocol === 'https:';
+    const requestFn = isHttps ? httpsRequest : httpRequest;
+
+    const reqHeaders: OutgoingHttpHeaders = {
+      ...headers,
+      'Content-Type': 'application/json'
+    };
+
+    if (body) {
+      reqHeaders['Content-Length'] = Buffer.byteLength(body);
+    }
+
+    const options: RequestOptions = {
+      method,
+      hostname: url.hostname,
+      port: url.port || (isHttps ? 443 : 80),
+      path: url.pathname + url.search,
+      headers: reqHeaders,
+      timeout: timeoutMs
+    };
+
+    const req = requestFn(options, (res) => {
+      const chunks: Buffer[] = [];
+      res.on('data', (chunk) => chunks.push(Buffer.from(chunk)));
+      res.on('end', () => {
+        resolve({
+          statusCode: res.statusCode ?? 500,
+          body: Buffer.concat(chunks).toString('utf-8')
+        });
+      });
+    });
+
+    req.on('error', (err) => {
+      reject(err);
+    });
+
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error('Request timeout'));
+    });
+
+    if (body) {
+      req.write(body);
+    }
+
+    req.end();
+  });
+}
+
+function buildHeaders(remote: RemoteHost): Record<string, string> {
+  const headers: Record<string, string> = {
+    'Accept': 'application/json'
+  };
+
+  if (remote.apiKey) {
+    headers['X-API-Key'] = remote.apiKey;
+  }
+
+  return headers;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CLIENT FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Check health of a remote service
+ */
+export async function remoteHealth(remoteName: string): Promise<RemoteHealthResult> {
+  const remote = getRemoteOrThrow(remoteName);
+  const url = new URL('/health', remote.url);
+
+  try {
+    const response = await makeRequest(url, 'GET', buildHeaders(remote));
+
+    if (response.statusCode !== 200) {
+      const error = JSON.parse(response.body)?.error;
+      throw new RemoteApiError(
+        remoteName,
+        response.statusCode,
+        error?.code ?? 'API_ERROR',
+        error?.message ?? 'Unknown error',
+        error?.details
+      );
+    }
+
+    const data = JSON.parse(response.body) as RemoteHealthResult;
+    updateRemoteLastConnected(remoteName);
+
+    return data;
+  } catch (err) {
+    if (err instanceof RemoteApiError) throw err;
+    throw new RemoteConnectionError(
+      remoteName,
+      remote.url,
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+}
+
+/**
+ * List packages on a remote
+ */
+export async function remoteListPackages(remoteName: string): Promise<RemotePackageList> {
+  const remote = getRemoteOrThrow(remoteName);
+  const url = new URL('/packages', remote.url);
+
+  try {
+    const response = await makeRequest(url, 'GET', buildHeaders(remote));
+
+    if (response.statusCode !== 200) {
+      const error = JSON.parse(response.body)?.error;
+      throw new RemoteApiError(
+        remoteName,
+        response.statusCode,
+        error?.code ?? 'API_ERROR',
+        error?.message ?? 'Unknown error',
+        error?.details
+      );
+    }
+
+    updateRemoteLastConnected(remoteName);
+    return JSON.parse(response.body) as RemotePackageList;
+  } catch (err) {
+    if (err instanceof RemoteApiError) throw err;
+    throw new RemoteConnectionError(
+      remoteName,
+      remote.url,
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+}
+
+/**
+ * Get package info from a remote
+ */
+export async function remotePackageInfo(remoteName: string, packageName: string): Promise<RemotePackageInfo | null> {
+  const remote = getRemoteOrThrow(remoteName);
+  const url = new URL(`/packages/${encodeURIComponent(packageName)}`, remote.url);
+
+  try {
+    const response = await makeRequest(url, 'GET', buildHeaders(remote));
+
+    if (response.statusCode === 404) {
+      return null;
+    }
+
+    if (response.statusCode !== 200) {
+      const error = JSON.parse(response.body)?.error;
+      throw new RemoteApiError(
+        remoteName,
+        response.statusCode,
+        error?.code ?? 'API_ERROR',
+        error?.message ?? 'Unknown error',
+        error?.details
+      );
+    }
+
+    updateRemoteLastConnected(remoteName);
+    return JSON.parse(response.body) as RemotePackageInfo;
+  } catch (err) {
+    if (err instanceof RemoteApiError) throw err;
+    throw new RemoteConnectionError(
+      remoteName,
+      remote.url,
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+}
+
+/**
+ * Run a tool on a remote
+ */
+export async function remoteRunTool(remoteName: string, options: RemoteRunOptions): Promise<RemoteRunResult> {
+  const remote = getRemoteOrThrow(remoteName);
+  const url = new URL('/run', remote.url);
+
+  const body = JSON.stringify({
+    package: options.package,
+    command: options.command,
+    args: options.args,
+    env: options.env,
+    stdin: options.stdin,
+    timeout: options.timeout,
+    scope: options.scope
+  });
+
+  // Use longer timeout for execution (tool timeout + network overhead)
+  const requestTimeout = (options.timeout ?? 30000) + 10000;
+
+  try {
+    const response = await makeRequest(url, 'POST', buildHeaders(remote), body, requestTimeout);
+
+    const data = JSON.parse(response.body);
+
+    // Check for API-level error
+    if (data.error && response.statusCode >= 400 && response.statusCode !== 500) {
+      throw new RemoteApiError(
+        remoteName,
+        response.statusCode,
+        data.error.code ?? 'API_ERROR',
+        data.error.message ?? 'Unknown error',
+        data.error.details
+      );
+    }
+
+    updateRemoteLastConnected(remoteName);
+
+    // Return the run result (may indicate success: false for tool failure)
+    return data as RemoteRunResult;
+  } catch (err) {
+    if (err instanceof RemoteApiError) throw err;
+    throw new RemoteConnectionError(
+      remoteName,
+      remote.url,
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+}
+
+/**
+ * Run a routine on a remote
+ */
+export async function remoteRunRoutine(
+  remoteName: string,
+  routineName: string,
+  vars?: Record<string, string>
+): Promise<RoutineRunSummary> {
+  const remote = getRemoteOrThrow(remoteName);
+  const url = new URL(`/routines/${encodeURIComponent(routineName)}/run`, remote.url);
+
+  const body = vars ? JSON.stringify({ vars }) : '{}';
+
+  try {
+    const response = await makeRequest(url, 'POST', buildHeaders(remote), body, 300000); // 5 min timeout for routines
+
+    if (response.statusCode === 404) {
+      throw new RemoteApiError(
+        remoteName,
+        404,
+        'NOT_FOUND',
+        `Routine not found: ${routineName}`
+      );
+    }
+
+    const data = JSON.parse(response.body);
+
+    if (data.error && response.statusCode >= 400) {
+      throw new RemoteApiError(
+        remoteName,
+        response.statusCode,
+        data.error.code ?? 'API_ERROR',
+        data.error.message ?? 'Unknown error',
+        data.error.details
+      );
+    }
+
+    updateRemoteLastConnected(remoteName);
+    return data as RoutineRunSummary;
+  } catch (err) {
+    if (err instanceof RemoteApiError) throw err;
+    throw new RemoteConnectionError(
+      remoteName,
+      remote.url,
+      err instanceof Error ? err.message : String(err)
+    );
+  }
+}
+
+/**
+ * Test connection to a remote
+ */
+export async function testRemoteConnection(remoteName: string): Promise<{ success: boolean; message: string; details?: Record<string, unknown> }> {
+  try {
+    const health = await remoteHealth(remoteName);
+    return {
+      success: true,
+      message: `Connected to ${health.hostname}`,
+      details: {
+        hostname: health.hostname,
+        version: health.version,
+        uptime: health.uptime
+      }
+    };
+  } catch (err) {
+    if (err instanceof RemoteConnectionError) {
+      return {
+        success: false,
+        message: err.message
+      };
+    }
+    if (err instanceof RemoteApiError) {
+      return {
+        success: false,
+        message: `${err.code}: ${err.message}`,
+        details: err.details
+      };
+    }
+    return {
+      success: false,
+      message: err instanceof Error ? err.message : String(err)
+    };
+  }
+}