@soleri/core 9.0.4 → 9.3.0

package/src/chat/output-compressor.test.ts

@@ -0,0 +1,164 @@
+/**
+ * Output Compressor — colocated tests.
+ *
+ * Covers: generic compressor, registry (exact + prefix match),
+ * JSON-aware compression, array/string truncation, plain text fallback.
+ */
+
+import { describe, test, expect, beforeEach } from 'vitest';
+import {
+  createOutputCompressor,
+  registerCompressor,
+  clearCompressors,
+} from './output-compressor.js';
+
+describe('OutputCompressor', () => {
+  beforeEach(() => {
+    clearCompressors();
+  });
+
+  describe('createOutputCompressor', () => {
+    test('returns short output unchanged', () => {
+      const compress = createOutputCompressor({ maxLength: 1000 });
+      const output = 'short text';
+      expect(compress('any_tool', output)).toBe(output);
+    });
+
+    test('truncates long plain text', () => {
+      const compress = createOutputCompressor({ maxLength: 50 });
+      const output = 'x'.repeat(200);
+      const result = compress('tool', output);
+      expect(result.length).toBeLessThan(200);
+      expect(result).toContain('truncated');
+    });
+
+    test('compresses long JSON arrays', () => {
+      const compress = createOutputCompressor({
+        maxLength: 500,
+        maxArrayItems: 2,
+      });
+      const data = Array.from({ length: 20 }, (_, i) => ({ id: i, name: `item-${i}` }));
+      const output = JSON.stringify(data);
+      const result = compress('tool', output);
+      const parsed = JSON.parse(result.split('\n... (compressed')[0]);
+      expect(parsed.length).toBeLessThanOrEqual(3); // 2 items + "... +18 more"
+    });
+
+    test('compresses long strings in JSON when output exceeds limit', () => {
+      const compress = createOutputCompressor({
+        maxLength: 100, // force compression by setting limit below output size
+        maxStringLength: 20,
+      });
+      const data = { description: 'a'.repeat(500) };
+      const output = JSON.stringify(data);
+      // output is ~516 chars, exceeds 100
+      const result = compress('tool', output);
+      const cleanResult = result.split('\n... (compressed')[0];
+      const parsed = JSON.parse(cleanResult);
+      expect(parsed.description.length).toBeLessThan(500);
+      expect(parsed.description).toContain('chars');
+    });
+
+    test('preserves numbers and booleans in JSON', () => {
+      const compress = createOutputCompressor({ maxLength: 5000 });
+      const data = { count: 42, active: true, label: null };
+      const output = JSON.stringify(data);
+      // Output is small — returned unchanged, still valid JSON
+      const result = compress('tool', output);
+      const parsed = JSON.parse(result);
+      expect(parsed.count).toBe(42);
+      expect(parsed.active).toBe(true);
+      expect(parsed.label).toBeNull();
+    });
+
+    test('respects overrideMax parameter', () => {
+      const compress = createOutputCompressor({ maxLength: 10000 });
+      const output = 'x'.repeat(200);
+      const result = compress('tool', output, 50);
+      expect(result.length).toBeLessThan(200);
+      expect(result).toContain('truncated');
+    });
+  });
+
+  describe('registry', () => {
+    test('exact match uses registered compressor', () => {
+      registerCompressor('vault_search', (output) => `[compressed] ${output.slice(0, 10)}`);
+      const compress = createOutputCompressor({ maxLength: 10 });
+      const result = compress('vault_search', 'x'.repeat(100));
+      expect(result.startsWith('[compressed]')).toBe(true);
+    });
+
+    test('prefix match uses registered compressor', () => {
+      registerCompressor('salvador.', (output, max) => output.slice(0, max));
+      const compress = createOutputCompressor({ maxLength: 20 });
+      const result = compress('salvador.vault', 'x'.repeat(100), 15);
+      expect(result).toBe('x'.repeat(15));
+    });
+
+    test('exact match takes priority over prefix', () => {
+      registerCompressor('tool_', () => 'prefix');
+      registerCompressor('tool_exact', () => 'exact');
+      const compress = createOutputCompressor({ maxLength: 10 });
+      expect(compress('tool_exact', 'x'.repeat(100))).toBe('exact');
+    });
+
+    test('clearCompressors removes all', () => {
+      registerCompressor('a', () => 'a');
+      registerCompressor('b', () => 'b');
+      clearCompressors();
+      const compress = createOutputCompressor({ maxLength: 10 });
+      const result = compress('a', 'x'.repeat(100));
+      expect(result).not.toBe('a');
+    });
+  });
+
+  describe('edge cases', () => {
+    test('handles empty string', () => {
+      const compress = createOutputCompressor();
+      expect(compress('tool', '')).toBe('');
+    });
+
+    test('handles invalid JSON gracefully', () => {
+      const compress = createOutputCompressor({ maxLength: 20 });
+      const result = compress('tool', '{not valid json' + 'x'.repeat(100));
+      expect(result).toContain('truncated');
+    });
+
+    test('handles nested objects with compression triggered', () => {
+      const compress = createOutputCompressor({
+        maxLength: 500, // large enough for compressed result to fit
+        maxStringLength: 10,
+      });
+      const data = {
+        level1: {
+          level2: {
+            deep: 'a'.repeat(600),
+          },
+        },
+      };
+      const output = JSON.stringify(data);
+      // output is ~640 chars, exceeds 500, triggers compression
+      const result = compress('tool', output);
+      // Compressed string should be shorter than original
+      expect(result.length).toBeLessThan(output.length);
+      // The deep value should have been truncated
+      expect(result).toContain('chars');
+    });
+
+    test('compresses arrays within objects when limit exceeded', () => {
+      const compress = createOutputCompressor({
+        maxLength: 200, // large enough for compressed output
+        maxArrayItems: 2,
+      });
+      // Use objects in the array so total JSON is over 200 chars
+      const data = {
+        items: Array.from({ length: 50 }, (_, i) => ({ id: i, label: `item-${i}` })),
+      };
+      const output = JSON.stringify(data);
+      // output is well over 200 chars
+      const result = compress('tool', output);
+      expect(result.length).toBeLessThan(output.length);
+      expect(result).toContain('+48 more');
+    });
+  });
+});

package/src/claudemd/compose.test.ts

@@ -0,0 +1,178 @@
+import { describe, it, expect } from 'vitest';
+import {
+  composeCLAUDEmd,
+  FORMAT_VERSION,
+  OPEN_MARKER,
+  CLOSE_MARKER,
+  USER_ZONE_OPEN,
+  USER_ZONE_CLOSE,
+} from './compose.js';
+import type { AgentMeta, FacadeInstructions } from './types.js';
+import type { FacadeConfig } from '../facades/types.js';
+
+const agent: AgentMeta = {
+  id: 'alpha',
+  name: 'Alpha',
+  activationPhrase: 'Hello, Alpha!',
+  deactivationPhrase: 'Goodbye, Alpha!',
+  activateCommand: 'alpha_core op:activate',
+  deactivateCommand: 'alpha_core op:deactivate',
+};
+
+const facades: FacadeConfig[] = [
+  {
+    name: 'alpha_core',
+    description: 'Core',
+    ops: [
+      { name: 'health', description: 'h', auth: 'read', handler: async () => ({}) },
+      { name: 'search', description: 's', auth: 'read', handler: async () => ({}) },
+      { name: 'capture', description: 'c', auth: 'write', handler: async () => ({}) },
+      { name: 'delete', description: 'd', auth: 'admin', handler: async () => ({}) },
+      { name: 'list', description: 'l', auth: 'read', handler: async () => ({}) },
+      { name: 'extra', description: 'e', auth: 'read', handler: async () => ({}) },
+    ],
+  },
+];
+
+describe('compose — constants', () => {
+  it('FORMAT_VERSION is a positive integer', () => {
+    expect(FORMAT_VERSION).toBeGreaterThan(0);
+    expect(Number.isInteger(FORMAT_VERSION)).toBe(true);
+  });
+
+  it('markers contain version', () => {
+    expect(OPEN_MARKER).toContain(`v${FORMAT_VERSION}`);
+  });
+});
+
+describe('composeCLAUDEmd', () => {
+  it('wraps output in open/close markers', () => {
+    const result = composeCLAUDEmd(agent, facades);
+    expect(result.startsWith(OPEN_MARKER)).toBe(true);
+    expect(result.endsWith(CLOSE_MARKER)).toBe(true);
+  });
+
+  it('renders activation and deactivation commands', () => {
+    const result = composeCLAUDEmd(agent, facades);
+    expect(result).toContain('Hello, Alpha!');
+    expect(result).toContain('Goodbye, Alpha!');
+    expect(result).toContain('alpha_core op:activate');
+    expect(result).toContain('alpha_core op:deactivate');
+  });
+
+  it('renders session start with agent id', () => {
+    const result = composeCLAUDEmd(agent, facades);
+    expect(result).toContain('alpha_core op:session_start');
+    expect(result).toContain('On EVERY new session');
+  });
+
+  it('renders facade table with max 5 ops and ellipsis for extra', () => {
+    const result = composeCLAUDEmd(agent, facades);
+    expect(result).toContain('| `alpha_core` |');
+    expect(result).toContain('`health`');
+    // 6 ops but table shows max 5 + ellipsis
+    expect(result).toContain('...');
+  });
+
+  it('renders all ops when facade has <= 5 ops', () => {
+    const smallFacade: FacadeConfig[] = [
+      {
+        name: 'beta_core',
+        description: 'Beta',
+        ops: [
+          { name: 'op1', description: 'o', auth: 'read', handler: async () => ({}) },
+          { name: 'op2', description: 'o', auth: 'read', handler: async () => ({}) },
+        ],
+      },
+    ];
+    const result = composeCLAUDEmd(agent, smallFacade);
+    expect(result).toContain('`op1`');
+    expect(result).toContain('`op2`');
+    expect(result).not.toContain('...');
+  });
+
+  it('uses keyOps from facadeInstructions when provided', () => {
+    const instructions = new Map<string, FacadeInstructions>([
+      [
+        'alpha_core',
+        {
+          heading: 'Core Rules',
+          keyOps: ['health', 'capture'],
+        },
+      ],
+    ]);
+    const result = composeCLAUDEmd(agent, facades, { facadeInstructions: instructions });
+    // Only keyOps should appear in the table row
+    expect(result).toContain('`health`');
+    expect(result).toContain('`capture`');
+    // 'search' is NOT a keyOp, so should not be in the table row for that facade
+    const tableRow = result.split('\n').find((l) => l.includes('`alpha_core`'));
+    expect(tableRow).not.toContain('`search`');
+  });
+
+  it('sorts global instructions by priority (low number = first)', () => {
+    const ag: AgentMeta = {
+      ...agent,
+      globalInstructions: [
+        { heading: 'Later', content: 'second', priority: 99 },
+        { heading: 'First', content: 'first', priority: 1 },
+        { heading: 'Middle', content: 'middle' }, // default 50
+      ],
+    };
+    const result = composeCLAUDEmd(ag, facades);
+    const firstIdx = result.indexOf('## First');
+    const middleIdx = result.indexOf('## Middle');
+    const laterIdx = result.indexOf('## Later');
+    expect(firstIdx).toBeLessThan(middleIdx);
+    expect(middleIdx).toBeLessThan(laterIdx);
+  });
+
+  it('renders facade behavioral rules sorted by priority', () => {
+    const instructions = new Map<string, FacadeInstructions>([
+      ['z_facade', { heading: 'Zed Rules', rules: ['Rule Z'], priority: 90 }],
+      ['a_facade', { heading: 'Ace Rules', rules: ['Rule A'], priority: 10 }],
+    ]);
+    const result = composeCLAUDEmd(agent, facades, { facadeInstructions: instructions });
+    expect(result.indexOf('## Ace Rules')).toBeLessThan(result.indexOf('## Zed Rules'));
+  });
+
+  it('renders facade rule templates', () => {
+    const instructions = new Map<string, FacadeInstructions>([
+      [
+        'alpha_core',
+        {
+          heading: 'Templates',
+          templates: { 'Example Plan': '```\nplan content\n```' },
+        },
+      ],
+    ]);
+    const result = composeCLAUDEmd(agent, facades, { facadeInstructions: instructions });
+    expect(result).toContain('### Example Plan');
+    expect(result).toContain('plan content');
+  });
+
+  it('includes user zone when includeUserZone is true', () => {
+    const result = composeCLAUDEmd(agent, facades, { includeUserZone: true });
+    expect(result).toContain(USER_ZONE_OPEN);
+    expect(result).toContain(USER_ZONE_CLOSE);
+  });
+
+  it('omits user zone by default', () => {
+    const result = composeCLAUDEmd(agent, facades);
+    expect(result).not.toContain(USER_ZONE_OPEN);
+  });
+
+  it('handles empty facades array', () => {
+    const result = composeCLAUDEmd(agent, []);
+    expect(result).toContain('| Facade | Key Ops |');
+    // No facade rows beyond the header
+    expect(result).toContain(OPEN_MARKER);
+    expect(result).toContain(CLOSE_MARKER);
+  });
+
+  it('handles agent with no globalInstructions', () => {
+    const result = composeCLAUDEmd(agent, facades);
+    // Should still produce valid output
+    expect(result).toContain('## Alpha Mode');
+  });
+});

package/src/claudemd/compose.ts

@@ -42,7 +42,7 @@ function renderSessionStart(agent: AgentMeta): string {
     '### Session Start Protocol',
     '',
     'On EVERY new session:',
-    `1. Register project: \`${agent.id}_core op:register params:{ projectPath: "." }\``,
+    `1. Start session: \`${agent.id}_core op:session_start params:{ projectPath: "." }\``,
     '2. Check activation response for `persistence.status`, `vault.connected`',
     `3. Check for plans in \`executing\` state — remind user to reconcile`,
   ].join('\n');

package/src/claudemd/inject.test.ts

@@ -0,0 +1,201 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { join } from 'node:path';
+import { mkdtempSync, rmSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { injectCLAUDEmd, removeCLAUDEmd, hasCLAUDEmdBlock, extractUserZone } from './inject.js';
+import { OPEN_MARKER, CLOSE_MARKER, USER_ZONE_OPEN, USER_ZONE_CLOSE } from './compose.js';
+
+function block(content: string): string {
+  return `${OPEN_MARKER}\n${content}\n${CLOSE_MARKER}`;
+}
+
+describe('extractUserZone', () => {
+  it('returns trimmed inner content', () => {
+    const input = `prefix\n${USER_ZONE_OPEN}\n  hello world  \n${USER_ZONE_CLOSE}\nsuffix`;
+    expect(extractUserZone(input)).toBe('hello world');
+  });
+
+  it('returns null when zone is empty', () => {
+    expect(extractUserZone(`${USER_ZONE_OPEN}\n  \n${USER_ZONE_CLOSE}`)).toBeNull();
+  });
+
+  it('returns null when no open marker', () => {
+    expect(extractUserZone(`no markers here ${USER_ZONE_CLOSE}`)).toBeNull();
+  });
+
+  it('returns null when close marker precedes open', () => {
+    expect(extractUserZone(`${USER_ZONE_CLOSE} before ${USER_ZONE_OPEN}`)).toBeNull();
+  });
+
+  it('returns null for empty string', () => {
+    expect(extractUserZone('')).toBeNull();
+  });
+});
+
+describe('injectCLAUDEmd', () => {
+  let dir: string;
+  let fp: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'inject-'));
+    fp = join(dir, 'CLAUDE.md');
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('creates a new file when none exists', () => {
+    const res = injectCLAUDEmd(fp, block('new'));
+    expect(res).toEqual({ success: true, action: 'injected', message: expect.any(String) });
+    expect(readFileSync(fp, 'utf-8')).toContain('new');
+  });
+
+  it('appends block to existing file without markers', () => {
+    writeFileSync(fp, '# Existing\n');
+    const res = injectCLAUDEmd(fp, block('appended'));
+    expect(res.action).toBe('injected');
+    const content = readFileSync(fp, 'utf-8');
+    expect(content).toContain('# Existing');
+    expect(content).toContain('appended');
+  });
+
+  it('replaces existing block and reports diff', () => {
+    writeFileSync(fp, `before\n${block('old')}\nafter`);
+    const res = injectCLAUDEmd(fp, block('new'));
+    expect(res.action).toBe('replaced');
+    expect(res.diffDetected).toBe(true);
+    const content = readFileSync(fp, 'utf-8');
+    expect(content).toContain('new');
+    expect(content).not.toContain('old');
+    expect(content).toContain('before');
+    expect(content).toContain('after');
+  });
+
+  it('skips write when block is identical', () => {
+    const b = block('same');
+    writeFileSync(fp, b);
+    const res = injectCLAUDEmd(fp, b);
+    expect(res.action).toBe('skipped');
+    expect(res.diffDetected).toBe(false);
+  });
+
+  it('preserves user zone content on replacement', () => {
+    const existing =
+      `${OPEN_MARKER}\n` +
+      `${USER_ZONE_OPEN}\nmy custom stuff\n${USER_ZONE_CLOSE}\n` +
+      `${CLOSE_MARKER}`;
+    writeFileSync(fp, existing);
+
+    const newBlock =
+      `${OPEN_MARKER}\nupdated body\n` +
+      `${USER_ZONE_OPEN}\n\n${USER_ZONE_CLOSE}\n` +
+      `${CLOSE_MARKER}`;
+    const res = injectCLAUDEmd(fp, newBlock);
+    expect(res.success).toBe(true);
+    expect(readFileSync(fp, 'utf-8')).toContain('my custom stuff');
+  });
+
+  it('migrates legacy <!-- agent:mode --> markers', () => {
+    writeFileSync(fp, '<!-- agent:mode -->\nlegacy\n<!-- /agent:mode -->');
+    const res = injectCLAUDEmd(fp, block('migrated'));
+    expect(res.action).toBe('replaced');
+    const content = readFileSync(fp, 'utf-8');
+    expect(content).toContain(OPEN_MARKER);
+    expect(content).not.toContain('legacy');
+  });
+
+  it('migrates legacy <!-- salvador:mode --> markers', () => {
+    writeFileSync(fp, '<!-- salvador:mode -->\nold sal\n<!-- /salvador:mode -->');
+    const res = injectCLAUDEmd(fp, block('new engine'));
+    expect(res.action).toBe('replaced');
+    expect(readFileSync(fp, 'utf-8')).toContain('new engine');
+  });
+
+  it('returns error result on write failure', () => {
+    // Point to a directory — writeFileSync will fail
+    const res = injectCLAUDEmd(dir, block('fail'));
+    expect(res.success).toBe(false);
+    expect(res.action).toBe('error');
+    expect(res.message).toContain('Injection failed');
+  });
+});
+
+describe('removeCLAUDEmd', () => {
+  let dir: string;
+  let fp: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'remove-'));
+    fp = join(dir, 'CLAUDE.md');
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('removes block and keeps surrounding text', () => {
+    writeFileSync(fp, `# Head\n\n${block('body')}\n\n# Foot\n`);
+    const res = removeCLAUDEmd(fp);
+    expect(res.action).toBe('removed');
+    const content = readFileSync(fp, 'utf-8');
+    expect(content).toContain('# Head');
+    expect(content).toContain('# Foot');
+    expect(content).not.toContain(OPEN_MARKER);
+  });
+
+  it('returns not_present when file has no block', () => {
+    writeFileSync(fp, 'plain text');
+    expect(removeCLAUDEmd(fp).action).toBe('not_present');
+  });
+
+  it('returns not_present when file does not exist', () => {
+    expect(removeCLAUDEmd(fp).action).toBe('not_present');
+  });
+
+  it('removes legacy markers too', () => {
+    writeFileSync(fp, '<!-- agent:mode -->\nold\n<!-- /agent:mode -->');
+    const res = removeCLAUDEmd(fp);
+    expect(res.action).toBe('removed');
+    expect(readFileSync(fp, 'utf-8')).not.toContain('old');
+  });
+
+  it('returns error on write failure', () => {
+    const res = removeCLAUDEmd(join(dir, 'nonexistent-dir', 'file.md'));
+    // file does not exist so returns not_present (not an error)
+    expect(res.action).toBe('not_present');
+  });
+});
+
+describe('hasCLAUDEmdBlock', () => {
+  let dir: string;
+  let fp: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'has-'));
+    fp = join(dir, 'CLAUDE.md');
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('returns true when current markers present', () => {
+    writeFileSync(fp, block('content'));
+    expect(hasCLAUDEmdBlock(fp)).toBe(true);
+  });
+
+  it('returns true for legacy markers', () => {
+    writeFileSync(fp, '<!-- agent:mode -->\nx\n<!-- /agent:mode -->');
+    expect(hasCLAUDEmdBlock(fp)).toBe(true);
+  });
+
+  it('returns false for plain file', () => {
+    writeFileSync(fp, 'no markers');
+    expect(hasCLAUDEmdBlock(fp)).toBe(false);
+  });
+
+  it('returns false for missing file', () => {
+    expect(hasCLAUDEmdBlock(join(dir, 'nope.md'))).toBe(false);
+  });
+});