cognitive-core 0.2.1 → 0.2.3

package/references/agent-workspace/package.json

@@ -1,54 +0,0 @@
-{
-  "name": "agent-workspace",
-  "version": "0.1.3",
-  "description": "Filesystem workspace management for agents — directory structure, typed I/O, and validation",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
-    }
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build",
-    "version:patch": "npm version patch && git push && git push --tags",
-    "version:minor": "npm version minor && git push && git push --tags",
-    "version:major": "npm version major && git push && git push --tags",
-    "publish:npm": "npm run build && npm publish"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/alexngai/agent-workspace.git"
-  },
-  "license": "MIT",
-  "author": "Alex Ngai",
-  "dependencies": {
-    "yaml": "^2.7.0"
-  },
-  "devDependencies": {
-    "@types/node": "^20.11.0",
-    "tsup": "^8.0.0",
-    "typescript": "^5.3.0",
-    "vitest": "^3.0.0"
-  }
-}

package/references/agent-workspace/src/handle.ts

@@ -1,122 +0,0 @@
-import * as path from 'path';
-import { writeJson, writeJsonl } from './writers/json.js';
-import { writeMarkdown } from './writers/markdown.js';
-import { writeRaw, copyDir, symlink } from './writers/raw.js';
-import { readJson, readJsonl, readJsonDir, type ReadJsonOptions } from './readers/json.js';
-import { readMarkdown, type ReadMarkdownOptions } from './readers/markdown.js';
-import { readRaw, listFiles } from './readers/raw.js';
-import { validateOutput } from './validation.js';
-import type { MarkdownDocument, OutputSpec, ValidationResult } from './types.js';
-
-export class WorkspaceHandle {
-  readonly id: string;
-  readonly path: string;
-  readonly createdAt: Date;
-  private readonly dirs: string[];
-
-  constructor(id: string, workspacePath: string, dirs: string[], createdAt: Date) {
-    this.id = id;
-    this.path = workspacePath;
-    this.dirs = dirs;
-    this.createdAt = createdAt;
-  }
-
-  /** Get the absolute path to a section directory. */
-  dir(section: string): string {
-    if (!this.dirs.includes(section)) {
-      throw new Error(
-        `Unknown section "${section}". Available: ${this.dirs.join(', ')}`,
-      );
-    }
-    return path.join(this.path, section);
-  }
-
-  // -- Convenience accessors for default dirs --
-
-  get inputDir(): string {
-    return path.join(this.path, 'input');
-  }
-  get outputDir(): string {
-    return path.join(this.path, 'output');
-  }
-  get resourcesDir(): string {
-    return path.join(this.path, 'resources');
-  }
-  get scratchDir(): string {
-    return path.join(this.path, 'scratch');
-  }
-
-  // -- Writers --
-
-  async writeJson(section: string, filePath: string, data: unknown): Promise<void> {
-    return writeJson(this.dir(section), filePath, data);
-  }
-
-  async writeJsonl(section: string, filePath: string, items: unknown[]): Promise<void> {
-    return writeJsonl(this.dir(section), filePath, items);
-  }
-
-  async writeMarkdown(section: string, filePath: string, doc: MarkdownDocument): Promise<void> {
-    return writeMarkdown(this.dir(section), filePath, doc);
-  }
-
-  async writeRaw(section: string, filePath: string, content: string): Promise<void> {
-    return writeRaw(this.dir(section), filePath, content);
-  }
-
-  async copyDir(section: string, destName: string, srcPath: string): Promise<void> {
-    return copyDir(this.dir(section), destName, srcPath);
-  }
-
-  async symlink(section: string, linkName: string, targetPath: string): Promise<void> {
-    return symlink(this.dir(section), linkName, targetPath);
-  }
-
-  // -- Readers --
-
-  async readJson<T = unknown>(
-    section: string,
-    filePath: string,
-    options?: ReadJsonOptions<T>,
-  ): Promise<T> {
-    return readJson(this.dir(section), filePath, options);
-  }
-
-  async readJsonl<T = unknown>(
-    section: string,
-    filePath: string,
-    options?: ReadJsonOptions<T>,
-  ): Promise<T[]> {
-    return readJsonl(this.dir(section), filePath, options);
-  }
-
-  async readMarkdown<T = Record<string, unknown>>(
-    section: string,
-    filePath: string,
-    options?: ReadMarkdownOptions<T>,
-  ): Promise<MarkdownDocument<T>> {
-    return readMarkdown(this.dir(section), filePath, options);
-  }
-
-  async readRaw(section: string, filePath: string): Promise<string> {
-    return readRaw(this.dir(section), filePath);
-  }
-
-  async listFiles(section: string, subPath: string = ''): Promise<string[]> {
-    return listFiles(this.dir(section), subPath);
-  }
-
-  async readJsonDir<T = unknown>(
-    section: string,
-    subPath: string,
-    options?: ReadJsonOptions<T>,
-  ): Promise<Map<string, T>> {
-    return readJsonDir(this.dir(section), subPath, options);
-  }
-
-  // -- Validation --
-
-  async validateOutput(spec: OutputSpec): Promise<ValidationResult> {
-    return validateOutput(this.outputDir, spec);
-  }
-}

package/references/agent-workspace/src/index.ts

@@ -1,32 +0,0 @@
-// Core classes
-export { WorkspaceManager } from './manager.js';
-export { WorkspaceHandle } from './handle.js';
-
-// Validation
-export { validateOutput } from './validation.js';
-
-// Standalone writer functions (for consumers who manage their own dirs)
-export { writeJson, writeJsonl } from './writers/json.js';
-export { writeMarkdown } from './writers/markdown.js';
-export { writeRaw, copyDir, symlink } from './writers/raw.js';
-
-// Standalone reader functions
-export { readJson, readJsonl, readJsonDir } from './readers/json.js';
-export { readMarkdown } from './readers/markdown.js';
-export { readRaw, listFiles } from './readers/raw.js';
-
-// Types
-export type {
-  Schema,
-  CreateWorkspaceOptions,
-  WorkspaceManagerConfig,
-  WorkspaceMeta,
-  MarkdownDocument,
-  OutputFileSpec,
-  OutputSpec,
-  ValidationError,
-  ValidationResult,
-} from './types.js';
-
-export type { ReadJsonOptions } from './readers/json.js';
-export type { ReadMarkdownOptions } from './readers/markdown.js';

package/references/agent-workspace/src/manager.ts

@@ -1,102 +0,0 @@
-import * as fs from 'fs/promises';
-import * as path from 'path';
-import * as os from 'os';
-import * as crypto from 'crypto';
-import { WorkspaceHandle } from './handle.js';
-import type { CreateWorkspaceOptions, WorkspaceManagerConfig, WorkspaceMeta } from './types.js';
-
-const DEFAULT_DIRS = ['input', 'output', 'resources', 'scratch'];
-const META_FILE = '.workspace.json';
-
-export class WorkspaceManager {
-  private readonly baseDir: string;
-  private readonly prefix: string;
-
-  constructor(config: WorkspaceManagerConfig = {}) {
-    this.baseDir = config.baseDir ?? os.tmpdir();
-    this.prefix = config.prefix ?? 'agent-workspaces';
-  }
-
-  /** Root directory that contains all workspaces. */
-  private get root(): string {
-    return path.join(this.baseDir, this.prefix);
-  }
-
-  /** Create a new workspace with standard + optional additional directories. */
-  async create(taskType: string, options: CreateWorkspaceOptions = {}): Promise<WorkspaceHandle> {
-    const id = `${taskType}-${Date.now()}-${crypto.randomUUID().slice(0, 8)}`;
-    const workspacePath = path.join(this.root, id);
-
-    const allDirs = [...DEFAULT_DIRS, ...(options.additionalDirs ?? [])];
-
-    // Create all directories in parallel
-    await fs.mkdir(workspacePath, { recursive: true });
-    await Promise.all(
-      allDirs.map((dir) => fs.mkdir(path.join(workspacePath, dir), { recursive: true })),
-    );
-
-    const meta: WorkspaceMeta = {
-      id,
-      taskType,
-      createdAt: new Date().toISOString(),
-      dirs: allDirs,
-    };
-
-    await fs.writeFile(path.join(workspacePath, META_FILE), JSON.stringify(meta, null, 2));
-
-    return new WorkspaceHandle(id, workspacePath, allDirs, new Date(meta.createdAt));
-  }
-
-  /** Remove a workspace from disk. */
-  async cleanup(handle: WorkspaceHandle): Promise<void> {
-    await fs.rm(handle.path, { recursive: true, force: true });
-  }
-
-  /** List all workspace handles under the managed root. */
-  async list(): Promise<WorkspaceHandle[]> {
-    try {
-      const entries = await fs.readdir(this.root, { withFileTypes: true });
-      const handles: WorkspaceHandle[] = [];
-
-      for (const entry of entries) {
-        if (!entry.isDirectory()) continue;
-        const metaPath = path.join(this.root, entry.name, META_FILE);
-        try {
-          const raw = await fs.readFile(metaPath, 'utf-8');
-          const meta: WorkspaceMeta = JSON.parse(raw);
-          handles.push(
-            new WorkspaceHandle(
-              meta.id,
-              path.join(this.root, entry.name),
-              meta.dirs,
-              new Date(meta.createdAt),
-            ),
-          );
-        } catch {
-          // Skip directories without valid metadata
-        }
-      }
-
-      return handles;
-    } catch {
-      // Root doesn't exist yet — no workspaces
-      return [];
-    }
-  }
-
-  /** Remove workspaces older than `maxAgeMs` milliseconds. */
-  async pruneStale(maxAgeMs: number): Promise<number> {
-    const handles = await this.list();
-    const cutoff = Date.now() - maxAgeMs;
-    let pruned = 0;
-
-    for (const handle of handles) {
-      if (handle.createdAt.getTime() <= cutoff) {
-        await this.cleanup(handle);
-        pruned++;
-      }
-    }
-
-    return pruned;
-  }
-}

package/references/agent-workspace/src/readers/json.ts

@@ -1,71 +0,0 @@
-import * as fs from 'fs/promises';
-import * as path from 'path';
-import type { Schema } from '../types.js';
-
-export interface ReadJsonOptions<T = unknown> {
-  schema?: Schema<T>;
-}
-
-/** Read and parse a JSON file. Optionally validate against a schema. */
-export async function readJson<T = unknown>(
-  dir: string,
-  filePath: string,
-  options?: ReadJsonOptions<T>,
-): Promise<T> {
-  const fullPath = path.join(dir, filePath);
-  const raw = await fs.readFile(fullPath, 'utf-8');
-  const data = JSON.parse(raw);
-
-  if (options?.schema) {
-    return options.schema.parse(data);
-  }
-
-  return data as T;
-}
-
-/** Read a JSONL file and return an array of parsed objects. Optionally validate each item. */
-export async function readJsonl<T = unknown>(
-  dir: string,
-  filePath: string,
-  options?: ReadJsonOptions<T>,
-): Promise<T[]> {
-  const fullPath = path.join(dir, filePath);
-  const raw = await fs.readFile(fullPath, 'utf-8');
-  const lines = raw.trimEnd().split('\n').filter((line) => line.length > 0);
-
-  return lines.map((line, index) => {
-    const data = JSON.parse(line);
-    if (options?.schema) {
-      try {
-        return options.schema.parse(data);
-      } catch (err) {
-        throw new Error(
-          `JSONL validation failed at line ${index + 1}: ${err instanceof Error ? err.message : String(err)}`,
-        );
-      }
-    }
-    return data as T;
-  });
-}
-
-/**
- * Read all JSON files in a directory, returning a Map of filename → parsed content.
- * Optionally validate each file against a schema.
- */
-export async function readJsonDir<T = unknown>(
-  dir: string,
-  subPath: string,
-  options?: ReadJsonOptions<T>,
-): Promise<Map<string, T>> {
-  const fullDir = path.join(dir, subPath);
-  const entries = await fs.readdir(fullDir);
-  const result = new Map<string, T>();
-
-  for (const entry of entries) {
-    if (!entry.endsWith('.json')) continue;
-    const data = await readJson<T>(fullDir, entry, options);
-    result.set(entry, data);
-  }
-
-  return result;
-}

package/references/agent-workspace/src/readers/markdown.ts

@@ -1,37 +0,0 @@
-import * as fs from 'fs/promises';
-import * as path from 'path';
-import { parse as yamlParse } from 'yaml';
-import type { MarkdownDocument, Schema } from '../types.js';
-
-export interface ReadMarkdownOptions<T = Record<string, unknown>> {
-  /** Schema to validate/parse the frontmatter. */
-  frontmatterSchema?: Schema<T>;
-}
-
-/** Read a markdown file, parsing YAML frontmatter if present. */
-export async function readMarkdown<T = Record<string, unknown>>(
-  dir: string,
-  filePath: string,
-  options?: ReadMarkdownOptions<T>,
-): Promise<MarkdownDocument<T>> {
-  const fullPath = path.join(dir, filePath);
-  const raw = await fs.readFile(fullPath, 'utf-8');
-
-  const match = raw.match(/^---\n([\s\S]*?)\n---\n\n?([\s\S]*)$/);
-
-  let frontmatter: T;
-  let body: string;
-
-  if (match) {
-    const parsed = yamlParse(match[1]);
-    frontmatter = options?.frontmatterSchema ? options.frontmatterSchema.parse(parsed) : parsed;
-    body = match[2];
-  } else {
-    frontmatter = (options?.frontmatterSchema
-      ? options.frontmatterSchema.parse({})
-      : {}) as T;
-    body = raw;
-  }
-
-  return { frontmatter, body };
-}

package/references/agent-workspace/src/readers/raw.ts

@@ -1,27 +0,0 @@
-import * as fs from 'fs/promises';
-import * as path from 'path';
-
-/** Read a file as a raw string. */
-export async function readRaw(dir: string, filePath: string): Promise<string> {
-  const fullPath = path.join(dir, filePath);
-  return fs.readFile(fullPath, 'utf-8');
-}
-
-/** List files in a section subdirectory, returning paths relative to the directory. */
-export async function listFiles(dir: string, subPath: string = ''): Promise<string[]> {
-  const fullDir = path.join(dir, subPath);
-  const entries = await fs.readdir(fullDir, { withFileTypes: true });
-  const files: string[] = [];
-
-  for (const entry of entries) {
-    const relative = path.join(subPath, entry.name);
-    if (entry.isDirectory()) {
-      const nested = await listFiles(dir, relative);
-      files.push(...nested);
-    } else {
-      files.push(relative);
-    }
-  }
-
-  return files;
-}

package/references/agent-workspace/src/types.ts

@@ -1,68 +0,0 @@
-/**
- * Minimal schema interface — anything with a `parse` method works (Zod, Joi, custom).
- * `parse` should throw on invalid data.
- */
-export interface Schema<T = unknown> {
-  parse(data: unknown): T;
-}
-
-/** Options for creating a workspace. */
-export interface CreateWorkspaceOptions {
-  /** Extra top-level directories to create alongside the defaults. */
-  additionalDirs?: string[];
-}
-
-/** Configuration for WorkspaceManager. */
-export interface WorkspaceManagerConfig {
-  /** Base directory where workspaces are created. Defaults to `os.tmpdir()`. */
-  baseDir?: string;
-  /** Namespace prefix for the workspaces directory. Defaults to `'agent-workspaces'`. */
-  prefix?: string;
-}
-
-/** Metadata persisted alongside a workspace. */
-export interface WorkspaceMeta {
-  id: string;
-  taskType: string;
-  createdAt: string;
-  dirs: string[];
-}
-
-/** Markdown document with optional YAML frontmatter. */
-export interface MarkdownDocument<T = Record<string, unknown>> {
-  frontmatter: T;
-  body: string;
-}
-
-/** Specification for a single expected output file. */
-export interface OutputFileSpec {
-  /** Path relative to the output directory. */
-  path: string;
-  /** Expected file format. */
-  format: 'json' | 'jsonl' | 'markdown' | 'raw';
-  /** Whether the file must exist. */
-  required: boolean;
-  /** Human-readable description (included in error messages). */
-  description?: string;
-  /** Schema for JSON / JSONL validation — must have a `parse` method that throws on invalid data. */
-  schema?: Schema;
-  /** Custom validation function. Throw or return false to indicate failure. */
-  validate?: (content: unknown) => boolean | Promise<boolean>;
-}
-
-/** Full output specification. */
-export interface OutputSpec {
-  files: OutputFileSpec[];
-}
-
-/** A single validation error. */
-export interface ValidationError {
-  path: string;
-  message: string;
-}
-
-/** Result of output validation. */
-export interface ValidationResult {
-  valid: boolean;
-  errors: ValidationError[];
-}

package/references/agent-workspace/src/validation.ts

@@ -1,93 +0,0 @@
-import * as fs from 'fs/promises';
-import * as path from 'path';
-import { readJson, readJsonl } from './readers/json.js';
-import { readMarkdown } from './readers/markdown.js';
-import { readRaw } from './readers/raw.js';
-import type { OutputFileSpec, OutputSpec, ValidationError, ValidationResult } from './types.js';
-
-/** Validate that expected output files exist and pass schema / custom validation. */
-export async function validateOutput(
-  outputDir: string,
-  spec: OutputSpec,
-): Promise<ValidationResult> {
-  const errors: ValidationError[] = [];
-
-  for (const fileSpec of spec.files) {
-    const fullPath = path.join(outputDir, fileSpec.path);
-
-    // Check existence
-    try {
-      await fs.access(fullPath);
-    } catch {
-      if (fileSpec.required) {
-        const desc = fileSpec.description ? ` (${fileSpec.description})` : '';
-        errors.push({
-          path: fileSpec.path,
-          message: `Required file missing${desc}`,
-        });
-      }
-      continue;
-    }
-
-    // Read and validate content
-    try {
-      const content = await readFileByFormat(outputDir, fileSpec);
-
-      // Schema validation
-      if (fileSpec.schema) {
-        try {
-          if (fileSpec.format === 'jsonl' && Array.isArray(content)) {
-            for (const item of content) {
-              fileSpec.schema.parse(item);
-            }
-          } else {
-            fileSpec.schema.parse(content);
-          }
-        } catch (err) {
-          errors.push({
-            path: fileSpec.path,
-            message: `Schema validation failed: ${err instanceof Error ? err.message : String(err)}`,
-          });
-        }
-      }
-
-      // Custom validate callback
-      if (fileSpec.validate) {
-        try {
-          const result = await fileSpec.validate(content);
-          if (result === false) {
-            errors.push({
-              path: fileSpec.path,
-              message: 'Custom validation returned false',
-            });
-          }
-        } catch (err) {
-          errors.push({
-            path: fileSpec.path,
-            message: `Custom validation threw: ${err instanceof Error ? err.message : String(err)}`,
-          });
-        }
-      }
-    } catch (err) {
-      errors.push({
-        path: fileSpec.path,
-        message: `Failed to read file: ${err instanceof Error ? err.message : String(err)}`,
-      });
-    }
-  }
-
-  return { valid: errors.length === 0, errors };
-}
-
-async function readFileByFormat(outputDir: string, spec: OutputFileSpec): Promise<unknown> {
-  switch (spec.format) {
-    case 'json':
-      return readJson(outputDir, spec.path);
-    case 'jsonl':
-      return readJsonl(outputDir, spec.path);
-    case 'markdown':
-      return readMarkdown(outputDir, spec.path);
-    case 'raw':
-      return readRaw(outputDir, spec.path);
-  }
-}

package/references/agent-workspace/src/writers/json.ts

@@ -1,17 +0,0 @@
-import * as fs from 'fs/promises';
-import * as path from 'path';
-
-/** Write a JSON file (pretty-printed). */
-export async function writeJson(dir: string, filePath: string, data: unknown): Promise<void> {
-  const fullPath = path.join(dir, filePath);
-  await fs.mkdir(path.dirname(fullPath), { recursive: true });
-  await fs.writeFile(fullPath, JSON.stringify(data, null, 2) + '\n');
-}
-
-/** Write a JSONL file (one JSON object per line). */
-export async function writeJsonl(dir: string, filePath: string, items: unknown[]): Promise<void> {
-  const fullPath = path.join(dir, filePath);
-  await fs.mkdir(path.dirname(fullPath), { recursive: true });
-  const content = items.map((item) => JSON.stringify(item)).join('\n') + '\n';
-  await fs.writeFile(fullPath, content);
-}

package/references/agent-workspace/src/writers/markdown.ts

@@ -1,27 +0,0 @@
-import * as fs from 'fs/promises';
-import * as path from 'path';
-import { stringify as yamlStringify } from 'yaml';
-import type { MarkdownDocument } from '../types.js';
-
-/** Write a markdown file with optional YAML frontmatter. */
-export async function writeMarkdown(
-  dir: string,
-  filePath: string,
-  doc: MarkdownDocument,
-): Promise<void> {
-  const fullPath = path.join(dir, filePath);
-  await fs.mkdir(path.dirname(fullPath), { recursive: true });
-
-  let content = '';
-  if (doc.frontmatter && Object.keys(doc.frontmatter).length > 0) {
-    content += '---\n' + yamlStringify(doc.frontmatter).trimEnd() + '\n---\n\n';
-  }
-  content += doc.body;
-
-  // Ensure trailing newline
-  if (!content.endsWith('\n')) {
-    content += '\n';
-  }
-
-  await fs.writeFile(fullPath, content);
-}

package/references/agent-workspace/src/writers/raw.ts

@@ -1,22 +0,0 @@
-import * as fs from 'fs/promises';
-import * as path from 'path';
-
-/** Write raw string content to a file. */
-export async function writeRaw(dir: string, filePath: string, content: string): Promise<void> {
-  const fullPath = path.join(dir, filePath);
-  await fs.mkdir(path.dirname(fullPath), { recursive: true });
-  await fs.writeFile(fullPath, content);
-}
-
-/** Recursively copy a directory into the workspace. */
-export async function copyDir(dir: string, destName: string, srcPath: string): Promise<void> {
-  const fullDest = path.join(dir, destName);
-  await fs.cp(srcPath, fullDest, { recursive: true });
-}
-
-/** Create a symlink inside the workspace pointing to an external path. */
-export async function symlink(dir: string, linkName: string, targetPath: string): Promise<void> {
-  const fullLink = path.join(dir, linkName);
-  await fs.mkdir(path.dirname(fullLink), { recursive: true });
-  await fs.symlink(targetPath, fullLink);
-}