@ontrails/core 1.0.0-beta.0

package/src/__tests__/layer.test.ts

@@ -0,0 +1,224 @@
+/* oxlint-disable require-await -- adapter mocks and layer wrappers satisfy async interfaces without awaiting */
+import { describe, test, expect } from 'bun:test';
+
+import { z } from 'zod';
+
+import type {
+  IndexAdapter,
+  StorageAdapter,
+  CacheAdapter,
+  SearchOptions,
+  SearchResult,
+  StorageOptions,
+} from '../adapters';
+import type { HealthStatus, HealthResult, HealthCheck } from '../health';
+import { composeLayers } from '../layer';
+import type { Layer } from '../layer';
+import { Result } from '../result';
+import { trail } from '../trail';
+import type { TrailContext } from '../types';
+
+const stubCtx: TrailContext = {
+  requestId: 'test-layer',
+  signal: AbortSignal.timeout(5000),
+};
+
+const echoTrail = trail('echo', {
+  implementation: (input) => Result.ok({ value: input.value }),
+  input: z.object({ value: z.string() }),
+  markers: { domain: 'test' },
+  output: z.object({ value: z.string() }),
+});
+
+// ---------------------------------------------------------------------------
+// Layer tests
+// ---------------------------------------------------------------------------
+
+describe('Layer', () => {
+  test('single layer wraps implementation', async () => {
+    const prefixLayer: Layer = {
+      name: 'prefix',
+      wrap(_trail, impl) {
+        return async (input, ctx) => {
+          const result = await impl(input, ctx);
+          return result.map((out) => ({
+            ...out,
+            value: `prefixed:${(out as { value: string }).value}`,
+          }));
+        };
+      },
+    };
+
+    const wrapped = composeLayers(
+      [prefixLayer],
+      echoTrail,
+      echoTrail.implementation
+    );
+    const result = await wrapped({ value: 'hello' }, stubCtx);
+
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toEqual({ value: 'prefixed:hello' });
+  });
+
+  test('multiple layers compose in outermost-first order', async () => {
+    const log: string[] = [];
+
+    const outer: Layer = {
+      name: 'outer',
+      wrap(_trail, impl) {
+        return async (input, ctx) => {
+          log.push('outer:before');
+          const r = await impl(input, ctx);
+          log.push('outer:after');
+          return r;
+        };
+      },
+    };
+
+    const inner: Layer = {
+      name: 'inner',
+      wrap(_trail, impl) {
+        return async (input, ctx) => {
+          log.push('inner:before');
+          const r = await impl(input, ctx);
+          log.push('inner:after');
+          return r;
+        };
+      },
+    };
+
+    const wrapped = composeLayers(
+      [outer, inner],
+      echoTrail,
+      echoTrail.implementation
+    );
+    await wrapped({ value: 'x' }, stubCtx);
+
+    expect(log).toEqual([
+      'outer:before',
+      'inner:before',
+      'inner:after',
+      'outer:after',
+    ]);
+  });
+
+  test('layer can short-circuit without calling inner implementation', async () => {
+    const shortCircuit: Layer = {
+      name: 'short-circuit',
+      wrap() {
+        return async () => Result.err(new Error('blocked'));
+      },
+    };
+
+    const wrapped = composeLayers(
+      [shortCircuit],
+      echoTrail,
+      echoTrail.implementation
+    );
+    const result = await wrapped({ value: 'hello' }, stubCtx);
+
+    expect(result.isErr()).toBe(true);
+    const err = result as unknown as { error: Error };
+    expect(err.error.message).toBe('blocked');
+  });
+
+  test('layer can inspect trail markers', () => {
+    let capturedDomain: unknown;
+
+    const inspectLayer: Layer = {
+      name: 'inspect',
+      wrap(t, impl) {
+        capturedDomain = t.markers?.['domain'];
+        return impl;
+      },
+    };
+
+    composeLayers([inspectLayer], echoTrail, echoTrail.implementation);
+
+    expect(capturedDomain).toBe('test');
+  });
+
+  test('empty layers array returns implementation unchanged', () => {
+    const wrapped = composeLayers([], echoTrail, echoTrail.implementation);
+    expect(wrapped).toBe(echoTrail.implementation);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Health types (compile-time verification)
+// ---------------------------------------------------------------------------
+
+describe('health types', () => {
+  test('HealthResult satisfies the interface', () => {
+    const check: HealthCheck = {
+      latency: 12,
+      message: 'ok',
+      status: 'healthy',
+    };
+    const result: HealthResult = {
+      checks: { db: check },
+      status: 'healthy',
+      uptime: 3600,
+      version: '1.0.0',
+    };
+
+    expect(result.status).toBe('healthy');
+    expect(result.checks['db']?.status).toBe('healthy');
+  });
+
+  test('HealthStatus union is exhaustive', () => {
+    const statuses: HealthStatus[] = ['healthy', 'degraded', 'unhealthy'];
+    expect(statuses).toHaveLength(3);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Adapter types (compile-time verification)
+// ---------------------------------------------------------------------------
+
+describe('adapter types', () => {
+  test('IndexAdapter mock satisfies the interface', () => {
+    const mock: IndexAdapter = {
+      index: async () => Result.ok(),
+      remove: async () => Result.ok(),
+      search: async () => Result.ok([]),
+    };
+    expect(mock.index).toBeDefined();
+    expect(mock.search).toBeDefined();
+    expect(mock.remove).toBeDefined();
+  });
+
+  test('StorageAdapter mock satisfies the interface', () => {
+    const mock: StorageAdapter = {
+      delete: async () => Result.ok(),
+      get: async () => Result.ok('value'),
+      has: async () => Result.ok(true),
+      set: async () => Result.ok(),
+    };
+    expect(mock.has).toBeDefined();
+  });
+
+  test('CacheAdapter mock satisfies the interface', () => {
+    const mock: CacheAdapter = {
+      clear: async () => Result.ok(),
+      delete: async () => Result.ok(),
+      get: async () => Result.ok(),
+      set: async () => Result.ok(),
+    };
+    expect(mock.clear).toBeDefined();
+  });
+
+  test('SearchOptions and SearchResult satisfy their shapes', () => {
+    const opts: SearchOptions = { filters: { tag: 'a' }, limit: 10, offset: 0 };
+    const hit: SearchResult = {
+      document: { title: 'x' },
+      id: '1',
+      score: 0.95,
+    };
+    const sopts: StorageOptions = { ttl: 5000 };
+
+    expect(opts.limit).toBe(10);
+    expect(hit.score).toBe(0.95);
+    expect(sopts.ttl).toBe(5000);
+  });
+});

package/src/__tests__/path-security.test.ts

@@ -0,0 +1,114 @@
+import { describe, test, expect } from 'bun:test';
+import { resolve, join } from 'node:path';
+
+import { PermissionError } from '../errors.js';
+import { securePath, isPathSafe, resolveSafePath } from '../path-security.js';
+
+// ---------------------------------------------------------------------------
+// securePath
+// ---------------------------------------------------------------------------
+
+describe('securePath', () => {
+  const base = '/project/workspace';
+
+  test('resolves a simple relative path', () => {
+    const result = securePath(base, 'src/index.ts');
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toBe(resolve(base, 'src/index.ts'));
+  });
+
+  test('resolves nested paths', () => {
+    const result = securePath(base, 'src/../lib/utils.ts');
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toBe(resolve(base, 'lib/utils.ts'));
+  });
+
+  test('accepts the base directory itself', () => {
+    const result = securePath(base, '.');
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toBe(resolve(base));
+  });
+
+  test('rejects path traversal with ..', () => {
+    const result = securePath(base, '../../etc/passwd');
+    expect(result.isErr()).toBe(true);
+    const err = result as unknown as { error: PermissionError };
+    expect(err.error).toBeInstanceOf(PermissionError);
+    expect(err.error.message).toContain('Path traversal detected');
+  });
+
+  test('rejects absolute paths outside base', () => {
+    const result = securePath(base, '/etc/passwd');
+    expect(result.isErr()).toBe(true);
+    const err = result as unknown as { error: PermissionError };
+    expect(err.error).toBeInstanceOf(PermissionError);
+  });
+
+  test('rejects sneaky traversal (subdir/../../..)', () => {
+    const result = securePath(base, 'src/../../..');
+    expect(result.isErr()).toBe(true);
+  });
+
+  test('allows paths that mention .. but stay inside', () => {
+    const result = securePath(base, 'src/../src/file.ts');
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toBe(resolve(base, 'src/file.ts'));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// isPathSafe
+// ---------------------------------------------------------------------------
+
+describe('isPathSafe', () => {
+  const base = '/project/workspace';
+
+  test('returns true for child paths', () => {
+    expect(isPathSafe(base, 'src/index.ts')).toBe(true);
+  });
+
+  test('returns true for the base directory', () => {
+    expect(isPathSafe(base, '.')).toBe(true);
+  });
+
+  test('returns false for traversal', () => {
+    expect(isPathSafe(base, '../secret')).toBe(false);
+  });
+
+  test('returns false for absolute paths outside base', () => {
+    expect(isPathSafe(base, '/tmp/evil')).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveSafePath
+// ---------------------------------------------------------------------------
+
+describe('resolveSafePath', () => {
+  const base = '/project/workspace';
+
+  test('joins multiple segments safely', () => {
+    const result = resolveSafePath(base, 'src', 'lib', 'utils.ts');
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toBe(join(resolve(base), 'src', 'lib', 'utils.ts'));
+  });
+
+  test('rejects when segments escape the base', () => {
+    const result = resolveSafePath(base, 'src', '../../../etc');
+    expect(result.isErr()).toBe(true);
+    const err = result as unknown as { error: PermissionError };
+    expect(err.error).toBeInstanceOf(PermissionError);
+  });
+
+  test('handles single segment', () => {
+    const result = resolveSafePath(base, 'file.txt');
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toBe(resolve(base, 'file.txt'));
+  });
+
+  test('handles empty segments', () => {
+    const result = resolveSafePath(base);
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toBe(resolve(base));
+  });
+});

package/src/__tests__/patterns.test.ts

@@ -0,0 +1,273 @@
+import { describe, test, expect } from 'bun:test';
+
+import { z } from 'zod';
+
+import {
+  paginationFields,
+  paginatedOutput,
+  bulkOutput,
+  timestampFields,
+  dateRangeFields,
+  sortFields,
+  statusFields,
+  changeOutput,
+  progressFields,
+} from '../patterns/index.js';
+
+// ---------------------------------------------------------------------------
+// paginationFields
+// ---------------------------------------------------------------------------
+
+describe('paginationFields', () => {
+  const schema = paginationFields();
+
+  test('applies defaults for empty input', () => {
+    const result = schema.parse({});
+    expect(result).toEqual({ limit: 20, offset: 0 });
+  });
+
+  test('accepts explicit values', () => {
+    const result = schema.parse({ cursor: 'abc', limit: 50, offset: 10 });
+    expect(result).toEqual({ cursor: 'abc', limit: 50, offset: 10 });
+  });
+
+  test('rejects non-number limit', () => {
+    expect(() => schema.parse({ limit: 'ten' })).toThrow();
+  });
+
+  test('rejects non-string cursor', () => {
+    expect(() => schema.parse({ cursor: 123 })).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// paginatedOutput
+// ---------------------------------------------------------------------------
+
+describe('paginatedOutput', () => {
+  const schema = paginatedOutput(z.string());
+
+  test('parses valid paginated data', () => {
+    const data = {
+      hasMore: true,
+      items: ['a', 'b'],
+      nextCursor: 'x',
+      total: 10,
+    };
+    expect(schema.parse(data)).toEqual(data);
+  });
+
+  test('allows missing nextCursor', () => {
+    const data = { hasMore: false, items: [], total: 0 };
+    expect(schema.parse(data)).toEqual(data);
+  });
+
+  test('rejects wrong item type', () => {
+    expect(() =>
+      schema.parse({ hasMore: false, items: [1], total: 1 })
+    ).toThrow();
+  });
+
+  test('rejects missing total', () => {
+    expect(() => schema.parse({ hasMore: false, items: [] })).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// bulkOutput
+// ---------------------------------------------------------------------------
+
+describe('bulkOutput', () => {
+  const schema = bulkOutput(z.object({ id: z.number() }));
+
+  test('parses valid bulk result', () => {
+    const data = {
+      failed: 0,
+      items: [{ id: 1 }, { id: 2 }],
+      succeeded: 2,
+    };
+    expect(schema.parse(data)).toEqual(data);
+  });
+
+  test('parses bulk result with errors', () => {
+    const data = {
+      errors: [{ index: 1, message: 'duplicate' }],
+      failed: 1,
+      items: [{ id: 1 }],
+      succeeded: 1,
+    };
+    expect(schema.parse(data)).toEqual(data);
+  });
+
+  test('rejects missing succeeded field', () => {
+    expect(() => schema.parse({ failed: 0, items: [] })).toThrow();
+  });
+
+  test('rejects invalid error shape', () => {
+    expect(() =>
+      schema.parse({
+        errors: [{ bad: true }],
+        failed: 0,
+        items: [],
+        succeeded: 0,
+      })
+    ).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// timestampFields
+// ---------------------------------------------------------------------------
+
+describe('timestampFields', () => {
+  const schema = timestampFields();
+
+  test('parses valid timestamps', () => {
+    const data = {
+      createdAt: '2024-01-01T00:00:00Z',
+      updatedAt: '2024-06-01T00:00:00Z',
+    };
+    expect(schema.parse(data)).toEqual(data);
+  });
+
+  test('rejects missing createdAt', () => {
+    expect(() => schema.parse({ updatedAt: '2024-01-01' })).toThrow();
+  });
+
+  test('rejects non-string values', () => {
+    expect(() => schema.parse({ createdAt: 123, updatedAt: 456 })).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// dateRangeFields
+// ---------------------------------------------------------------------------
+
+describe('dateRangeFields', () => {
+  const schema = dateRangeFields();
+
+  test('parses empty object (both optional)', () => {
+    expect(schema.parse({})).toEqual({});
+  });
+
+  test('parses with both fields', () => {
+    const data = { since: '2024-01-01', until: '2024-12-31' };
+    expect(schema.parse(data)).toEqual(data);
+  });
+
+  test('parses with only since', () => {
+    expect(schema.parse({ since: '2024-01-01' })).toEqual({
+      since: '2024-01-01',
+    });
+  });
+
+  test('rejects non-string values', () => {
+    expect(() => schema.parse({ since: 42 })).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// sortFields
+// ---------------------------------------------------------------------------
+
+describe('sortFields', () => {
+  const schema = sortFields(['name', 'createdAt', 'updatedAt']);
+
+  test('applies default sortOrder', () => {
+    const result = schema.parse({});
+    expect(result).toEqual({ sortOrder: 'asc' });
+  });
+
+  test('accepts valid sortBy and sortOrder', () => {
+    const result = schema.parse({ sortBy: 'name', sortOrder: 'desc' });
+    expect(result).toEqual({ sortBy: 'name', sortOrder: 'desc' });
+  });
+
+  test('rejects sortBy not in allowed list', () => {
+    expect(() => schema.parse({ sortBy: 'email' })).toThrow();
+  });
+
+  test('rejects invalid sortOrder', () => {
+    expect(() => schema.parse({ sortOrder: 'up' })).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// statusFields
+// ---------------------------------------------------------------------------
+
+describe('statusFields', () => {
+  const schema = statusFields();
+
+  test('parses each valid status', () => {
+    for (const s of [
+      'pending',
+      'running',
+      'completed',
+      'failed',
+      'cancelled',
+    ] as const) {
+      expect(schema.parse({ status: s })).toEqual({ status: s });
+    }
+  });
+
+  test('rejects invalid status', () => {
+    expect(() => schema.parse({ status: 'unknown' })).toThrow();
+  });
+
+  test('rejects missing status', () => {
+    expect(() => schema.parse({})).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// changeOutput
+// ---------------------------------------------------------------------------
+
+describe('changeOutput', () => {
+  const schema = changeOutput(z.object({ name: z.string() }));
+
+  test('parses with both before and after', () => {
+    const data = { after: { name: 'new' }, before: { name: 'old' } };
+    expect(schema.parse(data)).toEqual(data);
+  });
+
+  test('parses with only after (before is optional)', () => {
+    const data = { after: { name: 'created' } };
+    expect(schema.parse(data)).toEqual(data);
+  });
+
+  test('rejects missing after', () => {
+    expect(() => schema.parse({ before: { name: 'old' } })).toThrow();
+  });
+
+  test('rejects invalid schema shape', () => {
+    expect(() => schema.parse({ after: { name: 123 } })).toThrow();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// progressFields
+// ---------------------------------------------------------------------------
+
+describe('progressFields', () => {
+  const schema = progressFields();
+
+  test('parses valid progress', () => {
+    const data = { current: 5, percentage: 50, total: 10 };
+    expect(schema.parse(data)).toEqual(data);
+  });
+
+  test('allows missing percentage', () => {
+    const data = { current: 3, total: 10 };
+    expect(schema.parse(data)).toEqual(data);
+  });
+
+  test('rejects missing current', () => {
+    expect(() => schema.parse({ total: 10 })).toThrow();
+  });
+
+  test('rejects non-number values', () => {
+    expect(() => schema.parse({ current: 'five', total: 10 })).toThrow();
+  });
+});