@carto-knowledge/runner 0.2.3 → 0.2.5

package/src/envelope.ts

@@ -1,62 +0,0 @@
-// ABOUTME: Wraps CLI command outputs in structured JSON envelopes
-// ABOUTME: Provides consistent response format for Mastra tool integration
-
-export interface CommandError {
-  code: string;
-  message: string;
-}
-
-export interface CommandOutput<T = unknown> {
-  ok: boolean;
-  command: string;
-  result?: T;
-  error?: CommandError;
-  requestId?: string;
-  schemaVersion: 1;
-}
-
-/**
- * Creates a successful output envelope.
- */
-export function successEnvelope<T>(
-  command: string,
-  result: T,
-  requestId?: string
-): CommandOutput<T> {
-  return {
-    ok: true,
-    command,
-    result,
-    requestId,
-    schemaVersion: 1,
-  };
-}
-
-/**
- * Creates an error output envelope.
- */
-export function errorEnvelope(
-  command: string,
-  error: CommandError,
-  requestId?: string
-): CommandOutput<never> {
-  return {
-    ok: false,
-    command,
-    error,
-    requestId,
-    schemaVersion: 1,
-  };
-}
-
-/**
- * Common error codes for CLI operations.
- */
-export const ErrorCodes = {
-  COMMAND_NOT_ALLOWED: 'COMMAND_NOT_ALLOWED',
-  COMMAND_NOT_FOUND: 'COMMAND_NOT_FOUND',
-  INVALID_ARGUMENTS: 'INVALID_ARGUMENTS',
-  AUTH_ERROR: 'AUTH_ERROR',
-  EXECUTION_ERROR: 'EXECUTION_ERROR',
-  PARSE_ERROR: 'PARSE_ERROR',
-} as const;

package/src/index.ts

@@ -1,12 +0,0 @@
-// ABOUTME: Public API for @carto/runner package
-// ABOUTME: Exports in-process runner and supporting utilities
-
-export { runInProcess } from './runner';
-export type { RunOptions } from './runner';
-export type { CommandOutput } from './envelope';
-export { successEnvelope, errorEnvelope, ErrorCodes } from './envelope';
-export { tokenize, extractCommandPath } from './tokenizer';
-export { checkAllowlist, DEFAULT_ALLOWLIST, WRITE_ALLOWLIST } from './allowlist';
-export type { AllowlistConfig } from './allowlist';
-export { WorkerRuntime, CliRuntime } from './runtime';
-export type { CartoRuntime } from './runtime';

package/src/runner.test.ts

@@ -1,95 +0,0 @@
-// ABOUTME: Tests for in-process CLI runner
-// ABOUTME: Validates command execution without subprocess spawning
-
-import { describe, it, expect } from 'bun:test';
-import { runInProcess } from './runner';
-
-describe('runInProcess', () => {
-  const baseOptions = {
-    authToken: 'test-token',
-    apiBaseUrl: 'https://api.carto.so',
-  };
-
-  it('returns error for empty command', async () => {
-    const result = await runInProcess('', baseOptions);
-    expect(result.ok).toBe(false);
-    expect(result.error?.code).toBe('INVALID_ARGUMENTS');
-  });
-
-  it('returns error for whitespace-only command', async () => {
-    const result = await runInProcess('   ', baseOptions);
-    expect(result.ok).toBe(false);
-    expect(result.error?.code).toBe('INVALID_ARGUMENTS');
-  });
-
-  it('returns error for missing auth token', async () => {
-    const result = await runInProcess('folder tree', {
-      ...baseOptions,
-      authToken: '',
-    });
-    expect(result.ok).toBe(false);
-    expect(result.error?.code).toBe('AUTH_ERROR');
-  });
-
-  it('returns error for disallowed command', async () => {
-    const result = await runInProcess('admin delete-all', {
-      ...baseOptions,
-      allowlist: { commands: ['folder tree'] },
-    });
-    expect(result.ok).toBe(false);
-    expect(result.error?.code).toBe('COMMAND_NOT_ALLOWED');
-    expect(result.error?.message).toContain('admin delete-all');
-  });
-
-  it('includes requestId in response', async () => {
-    const result = await runInProcess('folder tree', {
-      ...baseOptions,
-      requestId: 'req-123',
-      allowlist: { commands: ['folder tree'] },
-    });
-    expect(result.requestId).toBe('req-123');
-  });
-
-  it('extracts correct command path from disallowed command error', async () => {
-    // Test with a disallowed command to verify path extraction without network
-    const result = await runInProcess('folder tree --library test', {
-      ...baseOptions,
-      allowlist: { commands: ['item search'] }, // folder tree not allowed
-    });
-    expect(result.command).toBe('folder tree');
-  });
-
-  it('includes schemaVersion in error response', async () => {
-    const result = await runInProcess('folder tree', {
-      ...baseOptions,
-      allowlist: { commands: [] }, // Empty allowlist to trigger error
-    });
-    expect(result.schemaVersion).toBe(1);
-  });
-
-  it('extracts folder restructure command path from disallowed command error', async () => {
-    const result = await runInProcess(
-      'folder restructure --library 00000000-0000-0000-0000-000000000001 --item-folder-map "{\\"item-1\\":\\"folder-a\\"}"',
-      {
-        ...baseOptions,
-        allowlist: { commands: ['folder tree'] },
-      }
-    );
-
-    expect(result.ok).toBe(false);
-    expect(result.command).toBe('folder restructure');
-  });
-
-  it('extracts folder create-tree command path from disallowed command error', async () => {
-    const result = await runInProcess(
-      'folder create-tree --library 00000000-0000-0000-0000-000000000001 --spec "{\\"name\\":\\"Root\\",\\"children\\":[]}"',
-      {
-        ...baseOptions,
-        allowlist: { commands: ['folder tree'] },
-      }
-    );
-
-    expect(result.ok).toBe(false);
-    expect(result.command).toBe('folder create-tree');
-  });
-});

package/src/runner.ts

@@ -1,169 +0,0 @@
-// ABOUTME: Executes CLI commands in-process without subprocess spawning
-// ABOUTME: Designed for Cloudflare Worker compatibility
-
-import { Cli } from 'clipanion';
-import { tokenize, extractCommandPath } from './tokenizer';
-import { checkAllowlist, AllowlistConfig, DEFAULT_ALLOWLIST } from './allowlist';
-import { successEnvelope, errorEnvelope, CommandOutput, ErrorCodes } from './envelope';
-import { WorkerRuntime } from './runtime';
-import { allCommands } from '@carto-knowledge/commands';
-import { CartoClient } from '@carto-knowledge/core';
-
-export interface RunOptions {
-  /** Correlation ID for tracing */
-  requestId?: string;
-
-  /** Auth token for API calls */
-  authToken: string;
-
-  /** Base URL for Carto API */
-  apiBaseUrl: string;
-
-  /** Command allowlist (defaults to read-only operations) */
-  allowlist?: AllowlistConfig;
-}
-
-/**
- * Executes a CLI command in-process.
- *
- * Designed for Worker runtime:
- * - No subprocess spawning
- * - Captures output to memory streams
- * - Forces JSON output and non-interactive mode
- * - Validates against allowlist
- *
- * @param commandLine - Command string, e.g., "folder tree --library my-lib"
- * @param options - Execution options including auth and allowlist
- * @returns Structured command output envelope
- */
-export async function runInProcess(
-  commandLine: string,
-  options: RunOptions
-): Promise<CommandOutput> {
-  const { requestId, authToken, apiBaseUrl, allowlist = DEFAULT_ALLOWLIST } = options;
-
-  // Defensive: Validate inputs
-  if (!commandLine || typeof commandLine !== 'string') {
-    return errorEnvelope('', {
-      code: ErrorCodes.INVALID_ARGUMENTS,
-      message: 'commandLine must be a non-empty string',
-    }, requestId);
-  }
-
-  if (!authToken) {
-    return errorEnvelope('', {
-      code: ErrorCodes.AUTH_ERROR,
-      message: 'authToken is required',
-    }, requestId);
-  }
-
-  // Parse command line
-  const tokens = tokenize(commandLine.trim());
-
-  if (tokens.length === 0) {
-    return errorEnvelope('', {
-      code: ErrorCodes.INVALID_ARGUMENTS,
-      message: 'Empty command line',
-    }, requestId);
-  }
-
-  const commandPath = extractCommandPath(tokens);
-
-  // Check allowlist
-  const allowlistResult = checkAllowlist(commandPath, allowlist);
-  if (!allowlistResult.allowed) {
-    return errorEnvelope(commandPath, allowlistResult.error!, requestId);
-  }
-
-  // Force tool-mode flags
-  const augmentedTokens = [
-    ...tokens,
-    '--format', 'json',
-  ];
-
-  // Create CLI instance
-  const cli = new Cli({
-    binaryName: 'carto',
-    enableCapture: true,
-  });
-
-  // Register all commands
-  for (const CommandClass of allCommands) {
-    cli.register(CommandClass);
-  }
-
-  // Capture output to memory using simple buffers (Worker-compatible)
-  let stdoutData = '';
-  let stderrData = '';
-
-  const stdout = {
-    write(chunk: string | Uint8Array): boolean {
-      stdoutData += typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk);
-      return true;
-    },
-  };
-
-  const stderr = {
-    write(chunk: string | Uint8Array): boolean {
-      stderrData += typeof chunk === 'string' ? chunk : new TextDecoder().decode(chunk);
-      return true;
-    },
-  };
-
-  // Create runtime and client
-  const runtime = new WorkerRuntime(authToken, apiBaseUrl);
-  const client = new CartoClient({
-    baseUrl: apiBaseUrl,
-    getAuthToken: async () => authToken,
-  });
-
-  // Create context matching CartoCommandContext
-  // Type assertion needed because we use minimal stream stubs for Worker compatibility
-  // Clipanion only uses the write() method at runtime
-  const context = {
-    stdin: process.stdin,
-    stdout,
-    stderr,
-    env: {},
-    colorDepth: 1,
-    client,
-    runtime,
-  } as unknown as Parameters<typeof cli.run>[1];
-
-  try {
-    const exitCode = await cli.run(augmentedTokens, context);
-    const output = stdoutData.trim();
-    const errorOutput = stderrData.trim();
-
-    if (exitCode === 0) {
-      // Parse JSON output from command
-      try {
-        const result = output ? JSON.parse(output) : null;
-        return successEnvelope(commandPath, result, requestId);
-      } catch {
-        // Command succeeded but output wasn't JSON (shouldn't happen in tool mode)
-        return successEnvelope(commandPath, { text: output }, requestId);
-      }
-    } else {
-      // Command failed
-      return errorEnvelope(commandPath, {
-        code: ErrorCodes.EXECUTION_ERROR,
-        message: errorOutput || output || `Command exited with code ${exitCode}`,
-      }, requestId);
-    }
-  } catch (error) {
-    // Unexpected error during execution
-    const message = error instanceof Error ? error.message : String(error);
-    console.error(`[carto-cli] Execution error for '${commandPath}':`, error);
-
-    return errorEnvelope(commandPath, {
-      code: ErrorCodes.EXECUTION_ERROR,
-      message,
-    }, requestId);
-  }
-}
-
-// Re-export for convenience
-export { DEFAULT_ALLOWLIST, WRITE_ALLOWLIST } from './allowlist';
-export type { AllowlistConfig } from './allowlist';
-export type { CommandOutput } from './envelope';

package/src/runtime.ts

@@ -1,90 +0,0 @@
-// ABOUTME: Abstracts runtime differences between CLI and Worker execution
-// ABOUTME: Provides consistent interface for auth, logging, and config
-
-export interface CartoRuntime {
-  // Authentication
-  getAuthToken(): Promise<string>;
-
-  // API access
-  apiBaseUrl: string;
-
-  // Environment flags
-  isInteractive: boolean;
-  isToolMode: boolean;
-
-  // Logging (respects --quiet, routes to correct streams)
-  log(message: string): void;
-  warn(message: string): void;
-  error(message: string): void;
-}
-
-/**
- * Worker runtime - receives auth from request context.
- * Non-interactive, always tool mode.
- */
-export class WorkerRuntime implements CartoRuntime {
-  isInteractive = false;
-  isToolMode = true;
-
-  constructor(
-    private authToken: string,
-    public apiBaseUrl: string,
-  ) {}
-
-  async getAuthToken(): Promise<string> {
-    return this.authToken;
-  }
-
-  log(message: string): void {
-    console.log(`[carto-cli] ${message}`);
-  }
-
-  warn(message: string): void {
-    console.warn(`[carto-cli] ${message}`);
-  }
-
-  error(message: string): void {
-    console.error(`[carto-cli] ${message}`);
-  }
-}
-
-/**
- * CLI runtime - reads from config file or env vars.
- * Interactive when terminal attached.
- *
- * Compatible with both Bun and Node.js runtimes.
- */
-export class CliRuntime implements CartoRuntime {
-  isInteractive: boolean;
-  isToolMode = false;
-
-  constructor(
-    private config: { apiBaseUrl: string; authToken?: string },
-  ) {
-    // Works in both Bun and Node.js
-    this.isInteractive = process.stdout.isTTY ?? false;
-  }
-
-  get apiBaseUrl(): string {
-    return this.config.apiBaseUrl;
-  }
-
-  async getAuthToken(): Promise<string> {
-    if (!this.config.authToken) {
-      throw new Error('Not authenticated. Run `carto auth login` first.');
-    }
-    return this.config.authToken;
-  }
-
-  log(message: string): void {
-    console.log(message);
-  }
-
-  warn(message: string): void {
-    console.warn(message);
-  }
-
-  error(message: string): void {
-    console.error(message);
-  }
-}

package/src/tokenizer.test.ts

@@ -1,83 +0,0 @@
-// ABOUTME: Tests for command line tokenizer
-// ABOUTME: Validates parsing of quoted strings and shell-like arguments
-
-import { describe, it, expect } from 'bun:test';
-import { tokenize, extractCommandPath } from './tokenizer';
-
-describe('tokenize', () => {
-  it('splits simple command', () => {
-    expect(tokenize('folder tree')).toEqual(['folder', 'tree']);
-  });
-
-  it('handles single quotes', () => {
-    expect(tokenize("--name 'My Folder'")).toEqual(['--name', 'My Folder']);
-  });
-
-  it('handles double quotes', () => {
-    expect(tokenize('--name "My Folder"')).toEqual(['--name', 'My Folder']);
-  });
-
-  it('handles mixed quotes', () => {
-    expect(tokenize(`--a "foo" --b 'bar'`)).toEqual(['--a', 'foo', '--b', 'bar']);
-  });
-
-  it('handles escaped quotes', () => {
-    expect(tokenize(`--name "Test\\'s Folder"`)).toEqual(['--name', "Test's Folder"]);
-  });
-
-  it('handles empty input', () => {
-    expect(tokenize('')).toEqual([]);
-  });
-
-  it('handles multiple spaces', () => {
-    expect(tokenize('folder   tree')).toEqual(['folder', 'tree']);
-  });
-
-  it('handles tabs', () => {
-    expect(tokenize('folder\ttree')).toEqual(['folder', 'tree']);
-  });
-
-  it('handles leading and trailing whitespace', () => {
-    expect(tokenize('  folder tree  ')).toEqual(['folder', 'tree']);
-  });
-
-  it('handles quoted string with equals sign', () => {
-    expect(tokenize('--filter="status=active"')).toEqual(['--filter=status=active']);
-  });
-
-  it('handles empty quoted string', () => {
-    expect(tokenize('--name ""')).toEqual(['--name', '']);
-  });
-
-  it('handles complex real-world command', () => {
-    expect(tokenize('folder create --library my-lib --name "Research Papers" --color blue')).toEqual([
-      'folder', 'create', '--library', 'my-lib', '--name', 'Research Papers', '--color', 'blue'
-    ]);
-  });
-});
-
-describe('extractCommandPath', () => {
-  it('extracts command before options', () => {
-    expect(extractCommandPath(['folder', 'tree', '--library', 'x'])).toBe('folder tree');
-  });
-
-  it('handles no options', () => {
-    expect(extractCommandPath(['folder', 'tree'])).toBe('folder tree');
-  });
-
-  it('handles single command', () => {
-    expect(extractCommandPath(['help'])).toBe('help');
-  });
-
-  it('handles empty tokens', () => {
-    expect(extractCommandPath([])).toBe('');
-  });
-
-  it('stops at first option', () => {
-    expect(extractCommandPath(['item', 'search', '-q', 'hello', '--format', 'json'])).toBe('item search');
-  });
-
-  it('handles three-level command', () => {
-    expect(extractCommandPath(['librarian', 'chat', 'start', '--library', 'x'])).toBe('librarian chat start');
-  });
-});

package/src/tokenizer.ts

@@ -1,75 +0,0 @@
-// ABOUTME: Tokenizes command line strings for in-process CLI execution
-// ABOUTME: Handles quoted strings and shell-like argument parsing
-
-/**
- * Tokenizes a command line string, handling quoted strings.
- *
- * Examples:
- * - "folder tree" => ['folder', 'tree']
- * - "--name 'My Folder'" => ['--name', 'My Folder']
- * - '--name "My Folder"' => ['--name', 'My Folder']
- * - "folder create --name 'Test's Folder'" => handles escaped quotes
- */
-export function tokenize(commandLine: string): string[] {
-  const tokens: string[] = [];
-  let current = '';
-  let inQuote: string | null = null;
-  let escaped = false;
-
-  for (let i = 0; i < commandLine.length; i++) {
-    const char = commandLine[i];
-
-    if (escaped) {
-      current += char;
-      escaped = false;
-      continue;
-    }
-
-    if (char === '\\') {
-      escaped = true;
-      continue;
-    }
-
-    if (inQuote) {
-      if (char === inQuote) {
-        // Empty quoted string should still produce a token
-        tokens.push(current);
-        current = '';
-        inQuote = null;
-      } else {
-        current += char;
-      }
-    } else if (char === '"' || char === "'") {
-      inQuote = char;
-    } else if (char === ' ' || char === '\t') {
-      if (current) {
-        tokens.push(current);
-        current = '';
-      }
-    } else {
-      current += char;
-    }
-  }
-
-  if (current) {
-    tokens.push(current);
-  }
-
-  return tokens;
-}
-
-/**
- * Extracts the command path from tokens (before any options).
- *
- * Examples:
- * - ['folder', 'tree', '--library', 'x'] => 'folder tree'
- * - ['item', 'search', '-q', 'hello'] => 'item search'
- */
-export function extractCommandPath(tokens: string[]): string {
-  const path: string[] = [];
-  for (const token of tokens) {
-    if (token.startsWith('-')) break;
-    path.push(token);
-  }
-  return path.join(' ');
-}

package/tsconfig.json

@@ -1,15 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ESNext",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "noEmit": true,
-    "declaration": true,
-    "declarationMap": true,
-    "types": ["bun-types"]
-  },
-  "include": ["src/**/*"]
-}