@carto-knowledge/runner 0.1.0

package/.turbo/turbo-typecheck.log

@@ -0,0 +1,6 @@
+
+> @carto/runner@0.1.0 typecheck /Users/pureicis/dev/carto/frontend_v1/packages/carto-runner
+> bun x tsc --noEmit
+
+../carto-commands/src/librarian/chat.ts(39,21): error TS2339: Property 'folderId' does not exist on type 'CreateConversationRequest'.
+ ELIFECYCLE  Command failed with exit code 2.

package/bun.lock

@@ -0,0 +1,40 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@carto/runner",
+      "dependencies": {
+        "@carto-knowledge/commands": "file:../carto-commands",
+        "@carto-knowledge/core": "file:../carto-core",
+        "clipanion": "^4.0.0-rc.4",
+      },
+      "devDependencies": {
+        "@types/bun": "latest",
+        "typescript": "^5.4.0",
+      },
+    },
+  },
+  "packages": {
+    "@carto-knowledge/commands": ["@carto-knowledge/commands@file:../carto-commands", { "dependencies": { "@carto-knowledge/core": "file:../carto-core", "clipanion": "^4.0.0-rc.4" }, "devDependencies": { "@types/bun": "latest", "@types/node": "^22.0.0", "typescript": "^5.4.0" } }],
+
+    "@carto-knowledge/core": ["@carto-knowledge/core@file:../carto-core", { "dependencies": { "zod": "^3.23.0" }, "devDependencies": { "@types/bun": "latest", "typescript": "^5.4.0" } }],
+
+    "@types/bun": ["@types/bun@1.3.6", "", { "dependencies": { "bun-types": "1.3.6" } }, "sha512-uWCv6FO/8LcpREhenN1d1b6fcspAB+cefwD7uti8C8VffIv0Um08TKMn98FynpTiU38+y2dUO55T11NgDt8VAA=="],
+
+    "@types/node": ["@types/node@22.19.7", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-MciR4AKGHWl7xwxkBa6xUGxQJ4VBOmPTF7sL+iGzuahOFaO0jHCsuEfS80pan1ef4gWId1oWOweIhrDEYLuaOw=="],
+
+    "bun-types": ["bun-types@1.3.6", "", { "dependencies": { "@types/node": "*" } }, "sha512-OlFwHcnNV99r//9v5IIOgQ9Uk37gZqrNMCcqEaExdkVq3Avwqok1bJFmvGMCkCE0FqzdY8VMOZpfpR3lwI+CsQ=="],
+
+    "clipanion": ["clipanion@4.0.0-rc.4", "", { "dependencies": { "typanion": "^3.8.0" } }, "sha512-CXkMQxU6s9GklO/1f714dkKBMu1lopS1WFF0B8o4AxPykR1hpozxSiUZ5ZUeBjfPgCWqbcNOtZVFhB8Lkfp1+Q=="],
+
+    "typanion": ["typanion@3.14.0", "", {}, "sha512-ZW/lVMRabETuYCd9O9ZvMhAh8GslSqaUjxmK/JLPCh6l73CvLBiuXswj/+7LdnWOgYsQ130FqLzFz5aGT4I3Ug=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@6.21.0", "", {}, "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ=="],
+
+    "zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
+
+    "@carto-knowledge/commands/@carto-knowledge/core": ["@carto-knowledge/core@file:../carto-core", {}],
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@carto-knowledge/runner",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "typecheck": "bun x tsc --noEmit"
+  },
+  "dependencies": {
+    "@carto-knowledge/core": "^0.1.0",
+    "@carto-knowledge/commands": "^0.1.0",
+    "clipanion": "^4.0.0-rc.4"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.4.0"
+  }
+}

package/src/allowlist.test.ts

@@ -0,0 +1,78 @@
+// ABOUTME: Tests for command allowlist validation
+// ABOUTME: Validates command filtering for tool-mode execution
+
+import { describe, it, expect } from 'bun:test';
+import { checkAllowlist, DEFAULT_ALLOWLIST, WRITE_ALLOWLIST } from './allowlist';
+
+describe('checkAllowlist', () => {
+  it('allows exact match', () => {
+    const result = checkAllowlist('folder tree', { commands: ['folder tree'] });
+    expect(result.allowed).toBe(true);
+    expect(result.error).toBeUndefined();
+  });
+
+  it('allows case-insensitive match', () => {
+    const result = checkAllowlist('FOLDER TREE', { commands: ['folder tree'] });
+    expect(result.allowed).toBe(true);
+  });
+
+  it('rejects non-matching command', () => {
+    const result = checkAllowlist('folder delete', { commands: ['folder tree'] });
+    expect(result.allowed).toBe(false);
+    expect(result.error?.code).toBe('COMMAND_NOT_ALLOWED');
+    expect(result.error?.message).toContain('folder delete');
+    expect(result.error?.message).toContain('folder tree');
+  });
+
+  it('allows prefix match', () => {
+    const result = checkAllowlist('folder tree', { commands: ['folder'] });
+    expect(result.allowed).toBe(true);
+  });
+
+  it('handles empty allowlist', () => {
+    const result = checkAllowlist('anything', { commands: [] });
+    expect(result.allowed).toBe(false);
+  });
+
+  it('trims whitespace', () => {
+    const result = checkAllowlist('  folder tree  ', { commands: ['folder tree'] });
+    expect(result.allowed).toBe(true);
+  });
+
+  it('allows multiple commands in allowlist', () => {
+    const result = checkAllowlist('item search', { commands: ['folder tree', 'item search', 'librarian chat'] });
+    expect(result.allowed).toBe(true);
+  });
+
+  it('does not allow partial command name match', () => {
+    // 'fold' should not match 'folder tree'
+    const result = checkAllowlist('fold', { commands: ['folder tree'] });
+    expect(result.allowed).toBe(false);
+  });
+});
+
+describe('DEFAULT_ALLOWLIST', () => {
+  it('includes read-only operations', () => {
+    expect(DEFAULT_ALLOWLIST.commands).toContain('folder tree');
+    expect(DEFAULT_ALLOWLIST.commands).toContain('folder list');
+    expect(DEFAULT_ALLOWLIST.commands).toContain('item search');
+    expect(DEFAULT_ALLOWLIST.commands).toContain('item get');
+  });
+
+  it('does not include write operations', () => {
+    expect(DEFAULT_ALLOWLIST.commands).not.toContain('folder create');
+    expect(DEFAULT_ALLOWLIST.commands).not.toContain('item create');
+  });
+});
+
+describe('WRITE_ALLOWLIST', () => {
+  it('includes all read operations', () => {
+    for (const cmd of DEFAULT_ALLOWLIST.commands) {
+      expect(WRITE_ALLOWLIST.commands).toContain(cmd);
+    }
+  });
+
+  it('includes write operations', () => {
+    expect(WRITE_ALLOWLIST.commands).toContain('folder create');
+  });
+});

package/src/allowlist.ts

@@ -0,0 +1,75 @@
+// ABOUTME: Validates commands against an allowlist for tool-mode execution
+// ABOUTME: Prevents unauthorized command execution in Worker context
+
+export interface AllowlistConfig {
+  commands: string[];  // e.g., ['folder tree', 'item search']
+}
+
+export interface AllowlistResult {
+  allowed: boolean;
+  error?: {
+    code: 'COMMAND_NOT_ALLOWED';
+    message: string;
+  };
+}
+
+/**
+ * Checks if a command matches the allowlist.
+ *
+ * Defensive validation:
+ * - Normalizes command path (lowercase, trim)
+ * - Supports prefix matching for subcommands
+ */
+export function checkAllowlist(
+  commandPath: string,
+  config: AllowlistConfig
+): AllowlistResult {
+  const normalizedPath = commandPath.toLowerCase().trim();
+
+  // Check exact match
+  if (config.commands.some(cmd => cmd.toLowerCase() === normalizedPath)) {
+    return { allowed: true };
+  }
+
+  // Check prefix match (e.g., 'folder' allows 'folder tree', 'folder create')
+  if (config.commands.some(cmd => normalizedPath.startsWith(cmd.toLowerCase() + ' '))) {
+    return { allowed: true };
+  }
+
+  return {
+    allowed: false,
+    error: {
+      code: 'COMMAND_NOT_ALLOWED',
+      message: `Command '${commandPath}' is not in the allowlist. ` +
+        `Allowed commands: ${config.commands.join(', ')}`,
+    },
+  };
+}
+
+/**
+ * Default allowlist for Worker tool mode.
+ * Read-only operations by default.
+ */
+export const DEFAULT_ALLOWLIST: AllowlistConfig = {
+  commands: [
+    'folder tree',
+    'folder list',
+    'item search',
+    'item get',
+    'librarian chat',
+  ],
+};
+
+/**
+ * Extended allowlist including write operations.
+ * Use when agent needs to modify data.
+ */
+export const WRITE_ALLOWLIST: AllowlistConfig = {
+  commands: [
+    ...DEFAULT_ALLOWLIST.commands,
+    'folder create',
+    'folder move',
+    'item create',
+    'item assign',
+  ],
+};

package/src/envelope.ts

@@ -0,0 +1,62 @@
+// 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

@@ -0,0 +1,12 @@
+// 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

@@ -0,0 +1,69 @@
+// 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);
+  });
+});

package/src/runner.ts

@@ -0,0 +1,169 @@
+// 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

@@ -0,0 +1,90 @@
+// 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

@@ -0,0 +1,83 @@
+// 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

@@ -0,0 +1,75 @@
+// 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

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