kiku-agent 1.3.1 → 1.3.3

package/server/agent/tests/cliAutomation.test.js

@@ -0,0 +1,158 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseCliArgs, resolveModelFallbackWarning } from '../cli.js';
+import { isColorDisabled, setColorDisabled, ansiForeground, ansiBackground } from '../theme.js';
+import { C } from '../ui.js';
+import { PACKAGE_VERSION } from '../version.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const cliPath = path.resolve(__dirname, '../cli.js');
+
+test('parseCliArgs parses standard flags correctly', () => {
+  const opts1 = parseCliArgs(['--print', '-q', 'hello world']);
+  assert.equal(opts1.print, true);
+  assert.equal(opts1.query, 'hello world');
+  assert.equal(opts1.output, 'text');
+
+  const opts2 = parseCliArgs(['-p', '--output', 'json', 'test query']);
+  assert.equal(opts2.print, true);
+  assert.equal(opts2.output, 'json');
+  assert.equal(opts2.query, 'test query');
+
+  const opts3 = parseCliArgs(['--plain', '--no-color']);
+  assert.equal(opts3.plain, true);
+  assert.equal(opts3.noColor, true);
+
+  const opts4 = parseCliArgs(['--provider', 'openai', '--model', 'gpt-5.6-luna', '--thinking', 'hide']);
+  assert.equal(opts4.provider, 'openai');
+  assert.equal(opts4.model, 'gpt-5.6-luna');
+  assert.equal(opts4.thinking, 'hide');
+});
+
+test('parseCliArgs enforces valid output format', () => {
+  
+  const textOpts = parseCliArgs(['--output', 'text']);
+  assert.equal(textOpts.output, 'text');
+
+  const jsonOpts = parseCliArgs(['--output', 'json']);
+  assert.equal(jsonOpts.output, 'json');
+  assert.equal(jsonOpts.print, true);
+});
+
+test('parseCliArgs handles --n-gpu-layers, --gpu-offload, and --threads flags', () => {
+  const opts1 = parseCliArgs(['--n-gpu-layers', '29', '--threads', '8']);
+  assert.equal(opts1.gpuOffload, '29');
+  assert.equal(opts1.nGpuLayers, '29');
+  assert.equal(opts1.cpuThreads, 8);
+
+  const opts2 = parseCliArgs(['--gpu-offload', 'max', '--cpu-threads', '4']);
+  assert.equal(opts2.gpuOffload, 'max');
+  assert.equal(opts2.cpuThreads, 4);
+
+  const opts3 = parseCliArgs(['-ngl', '0']);
+  assert.equal(opts3.gpuOffload, '0');
+  assert.equal(opts3.nGpuLayers, '0');
+});
+
+test('isColorDisabled and setColorDisabled honor NO_COLOR standards', () => {
+  setColorDisabled(true);
+  assert.equal(isColorDisabled(), true);
+  assert.equal(ansiForeground('255;110;180'), '');
+  assert.equal(ansiBackground('12;12;14'), '');
+  assert.equal(C.reset, '');
+  assert.equal(C.bold, '');
+  assert.equal(C.sakura, '');
+  assert.equal(C.white, '');
+
+  setColorDisabled(false);
+  assert.equal(isColorDisabled(), false);
+  assert.notEqual(C.reset, '');
+  assert.notEqual(C.bold, '');
+  assert.ok(C.sakura.includes('\x1b[38;2;'));
+
+  setColorDisabled(null);
+});
+
+test('CLI process exits with code 0 on --version', () => {
+  const res = spawnSync(process.execPath, [cliPath, '--version'], { encoding: 'utf8' });
+  assert.equal(res.status, 0);
+  assert.equal(res.stdout.trim(), PACKAGE_VERSION);
+});
+
+test('CLI process exits with code 0 and skips welcome hero on --help --plain', () => {
+  const res = spawnSync(process.execPath, [cliPath, '--help', '--plain'], { encoding: 'utf8' });
+  assert.equal(res.status, 0);
+  assert.ok(res.stdout.includes('CLI Flags & Options'));
+  assert.ok(res.stdout.includes('--print'));
+  assert.ok(res.stdout.includes('--output'));
+ 
+  assert.equal(/\x1b\[[0-9;]*m/.test(res.stdout), false);
+});
+
+test('CLI process exits with code 3 on unknown option', () => {
+  const res = spawnSync(process.execPath, [cliPath, '--unknown-option-xyz'], { encoding: 'utf8' });
+  assert.equal(res.status, 3);
+  assert.ok(res.stderr.includes('Unknown option: --unknown-option-xyz'));
+});
+
+test('CLI process exits with code 3 on invalid --output format', () => {
+  const res = spawnSync(process.execPath, [cliPath, '--output', 'yaml'], { encoding: 'utf8' });
+  assert.equal(res.status, 3);
+  assert.ok(res.stderr.includes('Invalid --output format: yaml'));
+});
+
+test('CLI process exits with code 2 and outputs valid JSON envelope when server unreachable', () => {
+  const res = spawnSync(process.execPath, [cliPath, '--url', 'http://127.0.0.1:9999/v1', '-q', 'test query', '--output', 'json'], { encoding: 'utf8' });
+  assert.equal(res.status, 2);
+  const payload = JSON.parse(res.stdout);
+  assert.equal(payload.version, PACKAGE_VERSION);
+  assert.equal(payload.status, 'error');
+  assert.equal(payload.query, 'test query');
+  assert.ok(payload.error);
+  assert.ok(Array.isArray(payload.tools));
+  assert.ok(payload.metrics && typeof payload.metrics.durationMs === 'number');
+});
+
+test('CLI process exits with code 2 and outputs clean stderr message on --print when server unreachable', () => {
+  const res = spawnSync(process.execPath, [cliPath, '--url', 'http://127.0.0.1:9999/v1', '-q', 'test query', '--print'], { encoding: 'utf8' });
+  assert.equal(res.status, 2);
+  assert.ok(res.stderr.includes('Error: Cannot reach'));
+  assert.equal(/\x1b\[[0-9;]*m/.test(res.stderr), false);
+});
+
+test('CLI process ingests piped stdin as query', () => {
+  const res = spawnSync(process.execPath, [cliPath, '--url', 'http://127.0.0.1:9999/v1', '--output', 'json'], {
+    input: 'query from piped stdin',
+    encoding: 'utf8'
+  });
+  assert.equal(res.status, 2);
+  const payload = JSON.parse(res.stdout);
+  assert.equal(payload.query, 'query from piped stdin');
+});
+
+test('resolveModelFallbackWarning never reports a null requested model', () => {
+  assert.equal(
+    resolveModelFallbackWarning({ usedFallback: true, requestedModel: 'google/gemma-4-e4b', selectedModel: 'other/model' }, { model: null }),
+    null,
+    'no --model flag means no explicit request, so no fallback warning'
+  );
+  assert.equal(
+    resolveModelFallbackWarning({ usedFallback: false, selectedModel: 'google/gemma-4-e4b' }, { model: 'google/gemma-4-e4b' }),
+    null,
+    'exact match must not warn'
+  );
+  assert.deepEqual(
+    resolveModelFallbackWarning({ usedFallback: true, requestedModel: 'custom/model', selectedModel: 'google/gemma-4-e4b' }, { model: 'custom/model' }),
+    { requested: 'custom/model', selected: 'google/gemma-4-e4b' }
+  );
+  assert.deepEqual(
+    resolveModelFallbackWarning({ usedFallback: true, selectedModel: 'google/gemma-4-e4b' }, { model: 'custom/model' }),
+    { requested: 'custom/model', selected: 'google/gemma-4-e4b' },
+    'falls back to the raw --model flag when the resolver omits the normalized name'
+  );
+});
+

package/server/agent/tests/cloudProviders.test.js

@@ -0,0 +1,322 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { CLOUD_PROVIDERS, resolveDefaultProvider, getProvider, getProviderList, getRecommendedModels, normalizeProviderModel } from '../config.js';
+import { LLMClient, LMStudioClient } from '../llmClient.js';
+import { ModelManager } from '../modelManager.js';
+import { routeCommand } from '../commands.js';
+
+test('cloud providers registry exposes all canonical cloud providers and defaults', () => {
+  const expected = ['lmstudio', 'vllm', 'ollama', 'openai', 'openrouter', 'groq', 'deepseek', 'gemini', 'anthropic', 'custom'];
+  for (const id of expected) {
+    assert.ok(CLOUD_PROVIDERS[id], `Provider "${id}" must be registered in CLOUD_PROVIDERS`);
+    assert.ok(CLOUD_PROVIDERS[id].baseUrl !== undefined);
+    assert.ok(CLOUD_PROVIDERS[id].defaultModel);
+    assert.ok(CLOUD_PROVIDERS[id].docUrl, `Provider "${id}" must have a docUrl`);
+    assert.ok(CLOUD_PROVIDERS[id].apiRefUrl, `Provider "${id}" must have an apiRefUrl`);
+    assert.ok(Array.isArray(CLOUD_PROVIDERS[id].recommendedModels), `Provider "${id}" must have recommendedModels array`);
+    assert.ok(CLOUD_PROVIDERS[id].recommendedModels.length > 0, `Provider "${id}" must have at least one recommended model`);
+  }
+});
+
+test('provider helper functions return correct definitions and models', () => {
+  const list = getProviderList();
+  assert.equal(list.length, 10);
+
+  const groq = getProvider('groq');
+  assert.equal(groq.id, 'groq');
+  assert.equal(groq.name, 'Groq Cloud');
+  assert.ok(groq.defaultModel === 'openai/gpt-oss-120b' || groq.defaultModel === 'openai/gpt-oss-20b');
+  assert.deepEqual(
+    groq.recommendedModels.map(model => model.id),
+    ['openai/gpt-oss-120b', 'openai/gpt-oss-20b']
+  );
+  assert.equal(normalizeProviderModel('groq', 'gpt-oss-120b'), 'openai/gpt-oss-120b');
+
+  const models = getRecommendedModels('gemini');
+  assert.equal(getProvider('gemini').defaultModel, 'gemini-3.7-flash');
+  assert.deepEqual(models.map(m => m.id), ['gemini-3.7-flash', 'gemini-3.5-flash-lite', 'gemini-3.6-flash']);
+  assert.equal(normalizeProviderModel('gemini', 'gemini-3.1-pro'), 'gemini-3.1-pro-preview');
+
+  const openaiModels = getRecommendedModels('openai');
+  assert.equal(getProvider('openai').defaultModel, 'gpt-5.6-luna');
+  assert.deepEqual(openaiModels.map(m => m.id), ['gpt-5.6-luna', 'gpt-5.6-terra', 'gpt-5.6-sol']);
+  assert.equal(normalizeProviderModel('openai', 'o3-mini'), 'gpt-5.6-luna');
+
+  assert.equal(getProvider('openrouter').defaultModel, 'openrouter/auto');
+  assert.equal(normalizeProviderModel('openrouter', 'auto'), 'openrouter/auto');
+
+  assert.equal(getProvider('deepseek').defaultModel, 'deepseek-v4-flash');
+  assert.equal(getProvider('deepseek').baseUrl, 'https://api.deepseek.com');
+  assert.equal(normalizeProviderModel('deepseek', 'deepseek-chat'), 'deepseek-v4-flash');
+  assert.equal(normalizeProviderModel('deepseek', 'deepseek-reasoner'), 'deepseek-v4-flash');
+
+  const lmstudioModels = getRecommendedModels('lmstudio');
+  assert.ok(lmstudioModels.some(m => m.id.startsWith('google/gemma-4-e4b')));
+  assert.ok(lmstudioModels.some(m => m.id.includes('Q4_K_M') || m.id === 'google/gemma-4-e4b'));
+  assert.ok(lmstudioModels.some(m => m.id.includes('Q6_K')));
+  assert.ok(lmstudioModels.some(m => m.id.includes('Q8_0')));
+  assert.equal(normalizeProviderModel('lmstudio', 'q8_0'), 'google/gemma-4-e4b-Q8_0');
+  assert.equal(normalizeProviderModel('lmstudio', 'q8'), 'google/gemma-4-e4b-Q8_0');
+  assert.equal(normalizeProviderModel('lmstudio', 'q6_k'), 'google/gemma-4-e4b-Q6_K');
+  assert.equal(normalizeProviderModel('lmstudio', 'q4_k_m'), 'google/gemma-4-e4b-Q4_K_M');
+  assert.equal(normalizeProviderModel('lmstudio', 'gemma'), 'google/gemma-4-e4b');
+
+  const vllm = getProvider('vllm');
+  assert.equal(vllm.id, 'vllm');
+  assert.equal(vllm.name, 'vLLM (Local / WSL)');
+  assert.equal(vllm.isLocal, true);
+  assert.ok(vllm.platformNotice.includes('You cannot install vLLM natively on Windows'));
+  assert.equal(normalizeProviderModel('vllm', 'gemma'), 'google/gemma-4-e4b');
+  assert.equal(normalizeProviderModel('vllm', 'qwen'), 'Qwen/Qwen2.5-7B-Instruct');
+
+  const ollama = getProvider('ollama');
+  assert.equal(ollama.id, 'ollama');
+  assert.equal(ollama.name, 'Ollama (Local)');
+  assert.equal(ollama.isLocal, true);
+  assert.equal(ollama.defaultModel, 'qwen2.5:7b');
+  assert.equal(normalizeProviderModel('ollama', 'qwen'), 'qwen2.5:7b');
+  assert.equal(normalizeProviderModel('ollama', 'llama'), 'llama3.1:8b');
+});
+
+test('LLMClient initializes with specified provider and supports switching', () => {
+  const client = new LLMClient({
+    provider: 'openai',
+    apiKey: 'sk-test-key-123',
+  });
+
+  const info = client.getProviderInfo();
+  assert.equal(info.provider, 'openai');
+  assert.equal(info.baseUrl, 'https://api.openai.com/v1');
+  assert.equal(info.hasApiKey, true);
+  assert.equal(info.isLocal, false);
+  assert.ok(info.docUrl);
+  assert.ok(info.pricingSummary);
+
+  const headers = client._buildHeaders();
+  assert.equal(headers['Authorization'], 'Bearer sk-test-key-123');
+
+  client.switchProvider('gemini', { apiKey: 'AIzaSy-test-key' });
+  assert.equal(client.provider, 'gemini');
+  assert.equal(client.baseUrl, 'https://generativelanguage.googleapis.com/v1beta/openai');
+  const geminiHeaders = client._buildHeaders();
+  assert.equal(geminiHeaders['Authorization'], 'Bearer AIzaSy-test-key');
+  assert.equal(geminiHeaders['x-goog-api-key'], 'AIzaSy-test-key');
+
+  client.switchProvider('groq', { apiKey: 'gsk-test-456' });
+  assert.equal(client.provider, 'groq');
+  assert.equal(client.baseUrl, 'https://api.groq.com/openai/v1');
+  assert.equal(client.apiKey, 'gsk-test-456');
+
+  client.switchProvider('openrouter', { apiKey: 'sk-or-test' });
+  const orHeaders = client._buildHeaders();
+  assert.equal(orHeaders['Authorization'], 'Bearer sk-or-test');
+  assert.ok(orHeaders['HTTP-Referer']);
+  assert.equal(orHeaders['X-OpenRouter-Title'], 'Kiku Agent');
+  assert.equal(orHeaders['X-Title'], undefined);
+});
+
+test('LLMClient setApiKey and setModel update state dynamically', () => {
+  const client = new LLMClient({ provider: 'groq', apiKey: '' });
+  assert.equal(client.apiKey, '');
+
+  client.setApiKey('gsk-new-key-789');
+  assert.equal(client.apiKey, 'gsk-new-key-789');
+
+  client.setModel('gpt-oss-120b');
+  assert.equal(client.model, 'openai/gpt-oss-120b');
+});
+
+test('LMStudioClient alias maintains backward compatibility with existing code', () => {
+  const legacyClient = new LMStudioClient({
+    baseUrl: 'http://127.0.0.1:1234/v1',
+    model: 'google/gemma-4-e4b',
+  });
+  assert.equal(legacyClient.baseUrl, 'http://127.0.0.1:1234/v1');
+  assert.equal(legacyClient.model, 'google/gemma-4-e4b');
+});
+
+test('/provider command displays status, list, models, info, test, and switches provider', async () => {
+  const client = new LLMClient({ provider: 'lmstudio' });
+  const agent = { client };
+
+  const statusRes = await routeCommand('/provider status', { client, agent, sub: 'status' });
+  assert.equal(statusRes, 'HANDLED');
+
+  const listRes = await routeCommand('/provider list', { client, agent, sub: 'list' });
+  assert.equal(listRes, 'HANDLED');
+
+  const modelsRes = await routeCommand('/provider models groq', { client, agent, sub: 'models', extra: 'groq' });
+  assert.equal(modelsRes, 'HANDLED');
+
+  const infoRes = await routeCommand('/provider info openai', { client, agent, sub: 'info', extra: 'openai' });
+  assert.equal(infoRes, 'HANDLED');
+
+  const setKeyRes = await routeCommand('/provider setkey groq gsk-runtime-key', {
+    client, agent, sub: 'setkey', extra: 'groq gsk-runtime-key', parts: ['/provider', 'setkey', 'groq', 'gsk-runtime-key']
+  });
+  assert.equal(setKeyRes, 'HANDLED');
+
+  const useRes = await routeCommand('/provider use groq gpt-oss-120b', {
+    client, agent, sub: 'use', extra: 'groq gpt-oss-120b', parts: ['/provider', 'use', 'groq', 'gpt-oss-120b']
+  });
+  assert.equal(useRes, 'HANDLED');
+  assert.equal(client.provider, 'groq');
+  assert.equal(client.model, 'openai/gpt-oss-120b');
+});
+
+test('LLMClient rejects unknown providers instead of silently using LM Studio', () => {
+  assert.throws(
+    () => new LLMClient({ provider: 'typo-provider' }),
+    /Unknown provider "typo-provider"/
+  );
+});
+
+test('Anthropic client uses native Messages API and normalizes tool use', async () => {
+  const originalFetch = globalThis.fetch;
+  let capturedUrl;
+  let capturedBody;
+  globalThis.fetch = async (url, options) => {
+    capturedUrl = url;
+    capturedBody = JSON.parse(options.body);
+    return new Response(JSON.stringify({
+      content: [
+        { type: 'tool_use', id: 'toolu_1', name: 'search_works', input: { query: 'In Blossom' } }
+      ],
+      usage: { input_tokens: 10, output_tokens: 5 }
+    }), { status: 200, headers: { 'Content-Type': 'application/json' } });
+  };
+  try {
+    const client = new LLMClient({ provider: 'anthropic', apiKey: 'sk-ant-test' });
+    const response = await client.chat({
+      messages: [{ role: 'system', content: 'Use tools.' }, { role: 'user', content: 'Find In Blossom.' }],
+      tools: [{ type: 'function', function: { name: 'search_works', description: 'Search works', parameters: { type: 'object', properties: { query: { type: 'string' } } } } }],
+      stream: false,
+    });
+    assert.equal(capturedUrl, 'https://api.anthropic.com/v1/messages');
+    assert.equal(capturedBody.system, 'Use tools.');
+    assert.equal(capturedBody.tools[0].input_schema.type, 'object');
+    assert.equal(response.tool_calls[0].function.name, 'search_works');
+    assert.deepEqual(JSON.parse(response.tool_calls[0].function.arguments), { query: 'In Blossom' });
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('GPT-5.6 Chat Completions payload uses supported token and tool fields', async () => {
+  const originalFetch = globalThis.fetch;
+  let payload;
+  globalThis.fetch = async (_url, options) => {
+    payload = JSON.parse(options.body);
+    return new Response(JSON.stringify({
+      choices: [{ message: { role: 'assistant', content: 'ok' } }],
+    }), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  };
+
+  try {
+    const client = new LLMClient({ provider: 'openai', apiKey: 'sk-test' });
+    await client.chat({
+      messages: [{ role: 'user', content: 'hello' }],
+      tools: [{ type: 'function', function: { name: 'test_tool', parameters: { type: 'object' } } }],
+      stream: false,
+    });
+    assert.equal(payload.model, 'gpt-5.6-luna');
+    assert.equal(payload.max_completion_tokens, 8192);
+    assert.equal(payload.max_tokens, undefined);
+    assert.equal(payload.temperature, undefined);
+    assert.equal(payload.tool_choice, 'auto');
+    assert.equal(payload.tools.length, 1);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('/model recommend displays recommended models for active provider', async () => {
+  const client = new LLMClient({ provider: 'gemini' });
+  const agent = { client };
+
+  const recRes = await routeCommand('/model recommend', { client, agent, sub: 'recommend' });
+  assert.equal(recRes, 'HANDLED');
+});
+
+test('LLMClient checkConnection auto-detects loaded Q8_0 model in LM Studio and syncs model ID', async () => {
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = async (url) => {
+    if (url.endsWith('/models')) {
+      return new Response(JSON.stringify({
+        data: [
+          { id: 'bartowski/gemma-4-e4b-GGUF/gemma-4-e4b-Q4_K_M.gguf', state: 'not_loaded' },
+          { id: 'bartowski/gemma-4-e4b-GGUF/gemma-4-e4b-Q8_0.gguf', state: 'loaded' },
+        ]
+      }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+    return new Response('{}', { status: 200 });
+  };
+
+  try {
+    const client = new LLMClient({ provider: 'lmstudio', model: 'google/gemma-4-e4b' });
+    const health = await client.checkConnection();
+    assert.equal(health.connected, true);
+    assert.equal(health.activeLoadedModel, 'bartowski/gemma-4-e4b-GGUF/gemma-4-e4b-Q8_0.gguf');
+    assert.equal(health.activeModel, 'bartowski/gemma-4-e4b-GGUF/gemma-4-e4b-Q8_0.gguf');
+    assert.equal(health.isModelAvailable, true);
+    assert.equal(client.model, 'bartowski/gemma-4-e4b-GGUF/gemma-4-e4b-Q8_0.gguf');
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('LLMClient checkConnection probes keyless local custom OpenAI-compatible endpoints', async () => {
+  const originalFetch = globalThis.fetch;
+  let probed = false;
+  globalThis.fetch = async (url) => {
+    if (url.endsWith('/models')) {
+      probed = true;
+      return new Response(JSON.stringify({ data: [{ id: 'google/gemma-4-e4b', state: 'loaded' }] }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+    return new Response('{}', { status: 200 });
+  };
+
+  try {
+    const client = new LLMClient({ provider: 'custom', baseUrl: 'http://127.0.0.1:1234/v1', apiKey: '' });
+    const health = await client.checkConnection();
+    assert.equal(probed, true);
+    assert.equal(health.connected, true);
+    assert.deepEqual(health.models, ['google/gemma-4-e4b']);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('LLMClient checkConnection still requires an API key for remote custom gateways', async () => {
+  const originalFetch = globalThis.fetch;
+  let probed = false;
+  globalThis.fetch = async () => {
+    probed = true;
+    return new Response('{}', { status: 200 });
+  };
+
+  try {
+    const client = new LLMClient({ provider: 'custom', baseUrl: 'https://gateway.example.com/v1', apiKey: '' });
+    const health = await client.checkConnection();
+    assert.equal(probed, false);
+    assert.equal(health.connected, false);
+    assert.match(health.error, /No API key configured/);
+    assert.match(health.error, /LLM_API_KEY/);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test('custom provider envKey points at the API key variable', () => {
+  assert.equal(CLOUD_PROVIDERS.custom.envKey, 'LLM_API_KEY');
+});

package/server/agent/tests/commandInput.test.js

@@ -0,0 +1,24 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { allowlistedValue, boundedInteger, parseCommandInput, tokenizeCommandInput } from '../commandInput.js';
+
+test('command parser supports multilingual quoted values, flags, and comparison segments', () => {
+  const parsed = parseCommandInput('/compare "บุปผารักอลวน" -- "花戎" --type work --limit=4');
+  assert.equal(parsed.command, '/compare');
+  assert.deepEqual(parsed.segments, ['บุปผารักอลวน', '花戎']);
+  assert.equal(parsed.flags.type, 'work');
+  assert.equal(parsed.flags.limit, '4');
+});
+
+test('command parser rejects oversized or unterminated input', () => {
+  assert.throws(() => tokenizeCommandInput(`/find "${'a'.repeat(600)}`), /500 characters/);
+  assert.throws(() => tokenizeCommandInput('/find "In Blossom'), /unclosed quote/);
+});
+
+test('command value validators reject values outside their contracts', () => {
+  assert.equal(boundedInteger('7', 1, 1, 20), 7);
+  assert.throws(() => boundedInteger('0', 1, 1, 20), /1 to 20/);
+  assert.equal(allowlistedValue('SONG', ['work', 'song'], 'work'), 'song');
+  assert.throws(() => allowlistedValue('file', ['work', 'song'], 'work'), /work, song/);
+});