cognitive-core 0.1.0 → 0.2.0

package/references/agent-workspace/tests/handle.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import { WorkspaceManager } from '../src/manager.js';
+import type { WorkspaceHandle } from '../src/handle.js';
+
+describe('WorkspaceHandle', () => {
+  let baseDir: string;
+  let manager: WorkspaceManager;
+  let handle: WorkspaceHandle;
+
+  beforeEach(async () => {
+    baseDir = await fs.mkdtemp(path.join(os.tmpdir(), 'ws-handle-'));
+    manager = new WorkspaceManager({ baseDir });
+    handle = await manager.create('handle-test');
+  });
+
+  afterEach(async () => {
+    await fs.rm(baseDir, { recursive: true, force: true });
+  });
+
+  describe('dir()', () => {
+    it('returns path for known sections', () => {
+      expect(handle.dir('input')).toBe(path.join(handle.path, 'input'));
+      expect(handle.dir('output')).toBe(path.join(handle.path, 'output'));
+      expect(handle.dir('resources')).toBe(path.join(handle.path, 'resources'));
+      expect(handle.dir('scratch')).toBe(path.join(handle.path, 'scratch'));
+    });
+
+    it('throws for unknown sections', () => {
+      expect(() => handle.dir('unknown')).toThrow('Unknown section "unknown"');
+    });
+
+    it('works with additional dirs', async () => {
+      const h = await manager.create('test', { additionalDirs: ['skills'] });
+      expect(h.dir('skills')).toBe(path.join(h.path, 'skills'));
+    });
+  });
+
+  describe('convenience accessors', () => {
+    it('provides inputDir, outputDir, resourcesDir, scratchDir', () => {
+      expect(handle.inputDir).toBe(path.join(handle.path, 'input'));
+      expect(handle.outputDir).toBe(path.join(handle.path, 'output'));
+      expect(handle.resourcesDir).toBe(path.join(handle.path, 'resources'));
+      expect(handle.scratchDir).toBe(path.join(handle.path, 'scratch'));
+    });
+  });
+
+  describe('JSON round-trip', () => {
+    it('writes and reads JSON through the handle', async () => {
+      await handle.writeJson('input', 'config.json', { model: 'gpt-4' });
+      const data = await handle.readJson('input', 'config.json');
+      expect(data).toEqual({ model: 'gpt-4' });
+    });
+
+    it('writes and reads JSON with schema validation', async () => {
+      await handle.writeJson('output', 'result.json', { score: 0.95 });
+
+      const schema = {
+        parse(data: unknown) {
+          const obj = data as Record<string, number>;
+          if (typeof obj.score !== 'number') throw new Error('score required');
+          return obj;
+        },
+      };
+
+      const data = await handle.readJson('output', 'result.json', { schema });
+      expect(data).toEqual({ score: 0.95 });
+    });
+  });
+
+  describe('JSONL round-trip', () => {
+    it('writes and reads JSONL through the handle', async () => {
+      const items = [{ step: 1 }, { step: 2 }];
+      await handle.writeJsonl('scratch', 'log.jsonl', items);
+      const result = await handle.readJsonl('scratch', 'log.jsonl');
+      expect(result).toEqual(items);
+    });
+  });
+
+  describe('Markdown round-trip', () => {
+    it('writes and reads markdown with frontmatter', async () => {
+      await handle.writeMarkdown('output', 'report.md', {
+        frontmatter: { title: 'Report', version: 1 },
+        body: '# Summary\n\nAll good.',
+      });
+
+      const doc = await handle.readMarkdown('output', 'report.md');
+      expect(doc.frontmatter).toEqual({ title: 'Report', version: 1 });
+      expect(doc.body).toContain('# Summary');
+    });
+  });
+
+  describe('Raw round-trip', () => {
+    it('writes and reads raw content', async () => {
+      await handle.writeRaw('scratch', 'notes.txt', 'Remember this');
+      const content = await handle.readRaw('scratch', 'notes.txt');
+      expect(content).toBe('Remember this');
+    });
+  });
+
+  describe('listFiles', () => {
+    it('lists files in a section', async () => {
+      await handle.writeRaw('input', 'a.txt', 'a');
+      await handle.writeRaw('input', 'b.txt', 'b');
+
+      const files = await handle.listFiles('input');
+      expect(files.sort()).toEqual(['a.txt', 'b.txt']);
+    });
+  });
+
+  describe('readJsonDir', () => {
+    it('reads all JSON files in a subdirectory', async () => {
+      await handle.writeJson('output', 'results/a.json', { x: 1 });
+      await handle.writeJson('output', 'results/b.json', { x: 2 });
+
+      const map = await handle.readJsonDir('output', 'results');
+      expect(map.size).toBe(2);
+      expect(map.get('a.json')).toEqual({ x: 1 });
+    });
+  });
+
+  describe('validateOutput', () => {
+    it('validates output files via the handle', async () => {
+      await handle.writeJson('output', 'result.json', { ok: true });
+
+      const result = await handle.validateOutput({
+        files: [{ path: 'result.json', format: 'json', required: true }],
+      });
+
+      expect(result.valid).toBe(true);
+    });
+
+    it('reports missing required output files', async () => {
+      const result = await handle.validateOutput({
+        files: [{ path: 'missing.json', format: 'json', required: true }],
+      });
+
+      expect(result.valid).toBe(false);
+      expect(result.errors[0].message).toContain('Required file missing');
+    });
+  });
+});

package/references/agent-workspace/tests/manager.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import { WorkspaceManager } from '../src/manager.js';
+
+describe('WorkspaceManager', () => {
+  let baseDir: string;
+  let manager: WorkspaceManager;
+
+  beforeEach(async () => {
+    baseDir = await fs.mkdtemp(path.join(os.tmpdir(), 'ws-test-'));
+    manager = new WorkspaceManager({ baseDir });
+  });
+
+  afterEach(async () => {
+    await fs.rm(baseDir, { recursive: true, force: true });
+  });
+
+  describe('create', () => {
+    it('creates a workspace with default directories', async () => {
+      const handle = await manager.create('test-task');
+
+      expect(handle.id).toMatch(/^test-task-/);
+      expect(handle.createdAt).toBeInstanceOf(Date);
+
+      // Verify all default dirs exist
+      for (const dir of ['input', 'output', 'resources', 'scratch']) {
+        const stat = await fs.stat(path.join(handle.path, dir));
+        expect(stat.isDirectory()).toBe(true);
+      }
+    });
+
+    it('creates additional directories when specified', async () => {
+      const handle = await manager.create('test-task', {
+        additionalDirs: ['skills', 'logs'],
+      });
+
+      for (const dir of ['input', 'output', 'resources', 'scratch', 'skills', 'logs']) {
+        const stat = await fs.stat(path.join(handle.path, dir));
+        expect(stat.isDirectory()).toBe(true);
+      }
+    });
+
+    it('writes workspace metadata', async () => {
+      const handle = await manager.create('my-task');
+      const metaRaw = await fs.readFile(path.join(handle.path, '.workspace.json'), 'utf-8');
+      const meta = JSON.parse(metaRaw);
+
+      expect(meta.id).toBe(handle.id);
+      expect(meta.taskType).toBe('my-task');
+      expect(meta.dirs).toEqual(['input', 'output', 'resources', 'scratch']);
+    });
+
+    it('includes additional dirs in metadata', async () => {
+      const handle = await manager.create('my-task', { additionalDirs: ['custom'] });
+      const metaRaw = await fs.readFile(path.join(handle.path, '.workspace.json'), 'utf-8');
+      const meta = JSON.parse(metaRaw);
+
+      expect(meta.dirs).toEqual(['input', 'output', 'resources', 'scratch', 'custom']);
+    });
+  });
+
+  describe('cleanup', () => {
+    it('removes the workspace directory', async () => {
+      const handle = await manager.create('test-task');
+      await manager.cleanup(handle);
+
+      await expect(fs.access(handle.path)).rejects.toThrow();
+    });
+  });
+
+  describe('list', () => {
+    it('returns empty array when no workspaces exist', async () => {
+      const handles = await manager.list();
+      expect(handles).toEqual([]);
+    });
+
+    it('lists all created workspaces', async () => {
+      await manager.create('task-a');
+      await manager.create('task-b');
+
+      const handles = await manager.list();
+      expect(handles).toHaveLength(2);
+      expect(handles.map((h) => h.id).sort()).toEqual(
+        expect.arrayContaining([expect.stringMatching(/^task-a-/), expect.stringMatching(/^task-b-/)]),
+      );
+    });
+
+    it('does not list cleaned-up workspaces', async () => {
+      const a = await manager.create('task-a');
+      await manager.create('task-b');
+      await manager.cleanup(a);
+
+      const handles = await manager.list();
+      expect(handles).toHaveLength(1);
+      expect(handles[0].id).toMatch(/^task-b-/);
+    });
+  });
+
+  describe('pruneStale', () => {
+    it('removes workspaces older than maxAgeMs', async () => {
+      await manager.create('old-task');
+
+      // Prune everything older than 0ms (i.e. everything)
+      const pruned = await manager.pruneStale(0);
+      expect(pruned).toBe(1);
+
+      const handles = await manager.list();
+      expect(handles).toHaveLength(0);
+    });
+
+    it('keeps workspaces newer than maxAgeMs', async () => {
+      await manager.create('new-task');
+
+      // Prune things older than 1 hour
+      const pruned = await manager.pruneStale(60 * 60 * 1000);
+      expect(pruned).toBe(0);
+
+      const handles = await manager.list();
+      expect(handles).toHaveLength(1);
+    });
+  });
+});

package/references/agent-workspace/tests/readers.test.ts

@@ -0,0 +1,205 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import {
+  readJson,
+  readJsonl,
+  readJsonDir,
+  readMarkdown,
+  readRaw,
+  listFiles,
+} from '../src/index.js';
+
+describe('Readers', () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await fs.mkdtemp(path.join(os.tmpdir(), 'ws-readers-'));
+  });
+
+  afterEach(async () => {
+    await fs.rm(dir, { recursive: true, force: true });
+  });
+
+  describe('readJson', () => {
+    it('reads and parses a JSON file', async () => {
+      await fs.writeFile(path.join(dir, 'data.json'), '{"key": "value"}');
+      const data = await readJson(dir, 'data.json');
+      expect(data).toEqual({ key: 'value' });
+    });
+
+    it('validates with a schema', async () => {
+      await fs.writeFile(path.join(dir, 'data.json'), '{"key": "value"}');
+
+      const schema = {
+        parse(data: unknown) {
+          const obj = data as Record<string, string>;
+          if (typeof obj.key !== 'string') throw new Error('key must be string');
+          return obj;
+        },
+      };
+
+      const data = await readJson(dir, 'data.json', { schema });
+      expect(data).toEqual({ key: 'value' });
+    });
+
+    it('throws when schema validation fails', async () => {
+      await fs.writeFile(path.join(dir, 'data.json'), '{"key": 123}');
+
+      const schema = {
+        parse(data: unknown) {
+          const obj = data as Record<string, unknown>;
+          if (typeof obj.key !== 'string') throw new Error('key must be string');
+          return obj;
+        },
+      };
+
+      await expect(readJson(dir, 'data.json', { schema })).rejects.toThrow('key must be string');
+    });
+
+    it('throws when file does not exist', async () => {
+      await expect(readJson(dir, 'nonexistent.json')).rejects.toThrow();
+    });
+  });
+
+  describe('readJsonl', () => {
+    it('reads and parses a JSONL file', async () => {
+      await fs.writeFile(path.join(dir, 'data.jsonl'), '{"a":1}\n{"b":2}\n{"c":3}\n');
+      const items = await readJsonl(dir, 'data.jsonl');
+      expect(items).toEqual([{ a: 1 }, { b: 2 }, { c: 3 }]);
+    });
+
+    it('validates each line with a schema', async () => {
+      await fs.writeFile(path.join(dir, 'data.jsonl'), '{"n":1}\n{"n":2}\n');
+
+      const schema = {
+        parse(data: unknown) {
+          const obj = data as Record<string, number>;
+          if (typeof obj.n !== 'number') throw new Error('n must be number');
+          return obj;
+        },
+      };
+
+      const items = await readJsonl(dir, 'data.jsonl', { schema });
+      expect(items).toEqual([{ n: 1 }, { n: 2 }]);
+    });
+
+    it('throws with line number on validation failure', async () => {
+      await fs.writeFile(path.join(dir, 'data.jsonl'), '{"n":1}\n{"n":"bad"}\n');
+
+      const schema = {
+        parse(data: unknown) {
+          const obj = data as Record<string, unknown>;
+          if (typeof obj.n !== 'number') throw new Error('n must be number');
+          return obj;
+        },
+      };
+
+      await expect(readJsonl(dir, 'data.jsonl', { schema })).rejects.toThrow(
+        'JSONL validation failed at line 2',
+      );
+    });
+  });
+
+  describe('readJsonDir', () => {
+    it('reads all JSON files in a directory', async () => {
+      const sub = path.join(dir, 'results');
+      await fs.mkdir(sub);
+      await fs.writeFile(path.join(sub, 'a.json'), '{"x":1}');
+      await fs.writeFile(path.join(sub, 'b.json'), '{"x":2}');
+      await fs.writeFile(path.join(sub, 'c.txt'), 'not json'); // should be skipped
+
+      const result = await readJsonDir(dir, 'results');
+      expect(result.size).toBe(2);
+      expect(result.get('a.json')).toEqual({ x: 1 });
+      expect(result.get('b.json')).toEqual({ x: 2 });
+    });
+  });
+
+  describe('readMarkdown', () => {
+    it('reads markdown with YAML frontmatter', async () => {
+      await fs.writeFile(
+        path.join(dir, 'doc.md'),
+        '---\ntitle: Hello\ntags:\n  - a\n  - b\n---\n\n# Content\n',
+      );
+
+      const doc = await readMarkdown(dir, 'doc.md');
+      expect(doc.frontmatter).toEqual({ title: 'Hello', tags: ['a', 'b'] });
+      expect(doc.body).toBe('# Content\n');
+    });
+
+    it('reads markdown without frontmatter', async () => {
+      await fs.writeFile(path.join(dir, 'plain.md'), '# No frontmatter\n');
+
+      const doc = await readMarkdown(dir, 'plain.md');
+      expect(doc.frontmatter).toEqual({});
+      expect(doc.body).toBe('# No frontmatter\n');
+    });
+
+    it('validates frontmatter with a schema', async () => {
+      await fs.writeFile(
+        path.join(dir, 'doc.md'),
+        '---\ntitle: Test\n---\n\nBody.\n',
+      );
+
+      const schema = {
+        parse(data: unknown) {
+          const obj = data as Record<string, string>;
+          if (!obj.title) throw new Error('title required');
+          return obj;
+        },
+      };
+
+      const doc = await readMarkdown(dir, 'doc.md', { frontmatterSchema: schema });
+      expect(doc.frontmatter).toEqual({ title: 'Test' });
+    });
+
+    it('throws when frontmatter schema fails', async () => {
+      await fs.writeFile(
+        path.join(dir, 'doc.md'),
+        '---\nfoo: bar\n---\n\nBody.\n',
+      );
+
+      const schema = {
+        parse(data: unknown) {
+          const obj = data as Record<string, string>;
+          if (!obj.title) throw new Error('title required');
+          return obj;
+        },
+      };
+
+      await expect(readMarkdown(dir, 'doc.md', { frontmatterSchema: schema })).rejects.toThrow(
+        'title required',
+      );
+    });
+  });
+
+  describe('readRaw', () => {
+    it('reads a file as a raw string', async () => {
+      await fs.writeFile(path.join(dir, 'data.txt'), 'hello world');
+      const content = await readRaw(dir, 'data.txt');
+      expect(content).toBe('hello world');
+    });
+  });
+
+  describe('listFiles', () => {
+    it('lists files recursively', async () => {
+      await fs.mkdir(path.join(dir, 'sub'), { recursive: true });
+      await fs.writeFile(path.join(dir, 'a.txt'), '');
+      await fs.writeFile(path.join(dir, 'sub', 'b.txt'), '');
+
+      const files = await listFiles(dir);
+      expect(files.sort()).toEqual(['a.txt', 'sub/b.txt'].sort());
+    });
+
+    it('lists files under a subpath', async () => {
+      const sub = path.join(dir, 'nested');
+      await fs.mkdir(sub);
+      await fs.writeFile(path.join(sub, 'file.txt'), '');
+
+      const files = await listFiles(dir, 'nested');
+      expect(files).toEqual(['nested/file.txt']);
+    });
+  });
+});

package/references/agent-workspace/tests/validation.test.ts

@@ -0,0 +1,196 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import { validateOutput } from '../src/validation.js';
+import type { OutputSpec } from '../src/types.js';
+
+describe('validateOutput', () => {
+  let outputDir: string;
+
+  beforeEach(async () => {
+    outputDir = await fs.mkdtemp(path.join(os.tmpdir(), 'ws-validation-'));
+  });
+
+  afterEach(async () => {
+    await fs.rm(outputDir, { recursive: true, force: true });
+  });
+
+  it('passes when all required files exist and are valid', async () => {
+    await fs.writeFile(path.join(outputDir, 'result.json'), '{"ok": true}');
+
+    const spec: OutputSpec = {
+      files: [{ path: 'result.json', format: 'json', required: true }],
+    };
+
+    const result = await validateOutput(outputDir, spec);
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('fails when a required file is missing', async () => {
+    const spec: OutputSpec = {
+      files: [
+        {
+          path: 'missing.json',
+          format: 'json',
+          required: true,
+          description: 'The main result',
+        },
+      ],
+    };
+
+    const result = await validateOutput(outputDir, spec);
+    expect(result.valid).toBe(false);
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0].message).toContain('Required file missing');
+    expect(result.errors[0].message).toContain('The main result');
+  });
+
+  it('skips missing optional files without error', async () => {
+    const spec: OutputSpec = {
+      files: [{ path: 'optional.json', format: 'json', required: false }],
+    };
+
+    const result = await validateOutput(outputDir, spec);
+    expect(result.valid).toBe(true);
+    expect(result.errors).toHaveLength(0);
+  });
+
+  it('validates JSON files with a schema', async () => {
+    await fs.writeFile(path.join(outputDir, 'result.json'), '{"count": "not a number"}');
+
+    const spec: OutputSpec = {
+      files: [
+        {
+          path: 'result.json',
+          format: 'json',
+          required: true,
+          schema: {
+            parse(data: unknown) {
+              const obj = data as Record<string, unknown>;
+              if (typeof obj.count !== 'number') throw new Error('count must be a number');
+              return obj;
+            },
+          },
+        },
+      ],
+    };
+
+    const result = await validateOutput(outputDir, spec);
+    expect(result.valid).toBe(false);
+    expect(result.errors[0].message).toContain('Schema validation failed');
+    expect(result.errors[0].message).toContain('count must be a number');
+  });
+
+  it('validates JSONL files with a schema (per-item)', async () => {
+    await fs.writeFile(
+      path.join(outputDir, 'steps.jsonl'),
+      '{"step":1}\n{"step":"bad"}\n',
+    );
+
+    const spec: OutputSpec = {
+      files: [
+        {
+          path: 'steps.jsonl',
+          format: 'jsonl',
+          required: true,
+          schema: {
+            parse(data: unknown) {
+              const obj = data as Record<string, unknown>;
+              if (typeof obj.step !== 'number') throw new Error('step must be number');
+              return obj;
+            },
+          },
+        },
+      ],
+    };
+
+    const result = await validateOutput(outputDir, spec);
+    expect(result.valid).toBe(false);
+    expect(result.errors[0].message).toContain('Schema validation failed');
+  });
+
+  it('runs custom validate callback', async () => {
+    await fs.writeFile(path.join(outputDir, 'result.json'), '{"score": 0.3}');
+
+    const spec: OutputSpec = {
+      files: [
+        {
+          path: 'result.json',
+          format: 'json',
+          required: true,
+          validate: (content) => {
+            const obj = content as Record<string, number>;
+            return obj.score >= 0.5;
+          },
+        },
+      ],
+    };
+
+    const result = await validateOutput(outputDir, spec);
+    expect(result.valid).toBe(false);
+    expect(result.errors[0].message).toContain('Custom validation returned false');
+  });
+
+  it('catches errors thrown by custom validate callback', async () => {
+    await fs.writeFile(path.join(outputDir, 'result.json'), '{"data": null}');
+
+    const spec: OutputSpec = {
+      files: [
+        {
+          path: 'result.json',
+          format: 'json',
+          required: true,
+          validate: () => {
+            throw new Error('Data cannot be null');
+          },
+        },
+      ],
+    };
+
+    const result = await validateOutput(outputDir, spec);
+    expect(result.valid).toBe(false);
+    expect(result.errors[0].message).toContain('Custom validation threw');
+    expect(result.errors[0].message).toContain('Data cannot be null');
+  });
+
+  it('validates markdown files', async () => {
+    await fs.writeFile(
+      path.join(outputDir, 'report.md'),
+      '---\ntitle: Report\n---\n\n# Summary\n',
+    );
+
+    const spec: OutputSpec = {
+      files: [{ path: 'report.md', format: 'markdown', required: true }],
+    };
+
+    const result = await validateOutput(outputDir, spec);
+    expect(result.valid).toBe(true);
+  });
+
+  it('validates raw files', async () => {
+    await fs.writeFile(path.join(outputDir, 'output.txt'), 'some text');
+
+    const spec: OutputSpec = {
+      files: [{ path: 'output.txt', format: 'raw', required: true }],
+    };
+
+    const result = await validateOutput(outputDir, spec);
+    expect(result.valid).toBe(true);
+  });
+
+  it('collects multiple errors', async () => {
+    const spec: OutputSpec = {
+      files: [
+        { path: 'a.json', format: 'json', required: true },
+        { path: 'b.json', format: 'json', required: true },
+        { path: 'c.json', format: 'json', required: false },
+      ],
+    };
+
+    const result = await validateOutput(outputDir, spec);
+    expect(result.valid).toBe(false);
+    expect(result.errors).toHaveLength(2); // a.json and b.json missing, c.json optional
+  });
+});