@flowcodex/core 0.3.0

package/tests/path-resolver.test.ts

@@ -0,0 +1,91 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { promises as fsp } from 'node:fs';
+import { DefaultPathResolver, safeResolve, safeResolveReal } from '../src/infrastructure/path-resolver.js';
+
+const TMP = path.join(os.tmpdir(), `fcx-test-${Date.now()}`);
+
+beforeEach(async () => {
+  await fsp.mkdir(TMP, { recursive: true });
+  await fsp.mkdir(path.join(TMP, 'subdir'), { recursive: true });
+  await fsp.writeFile(path.join(TMP, 'file.txt'), 'hello');
+});
+
+afterEach(async () => {
+  await fsp.rm(TMP, { recursive: true, force: true });
+});
+
+describe('DefaultPathResolver', () => {
+  it('detects project root from a directory with a marker', () => {
+    const resolver = new DefaultPathResolver({ projectRoot: TMP, cwd: TMP });
+    expect(resolver.projectRoot).toBe(TMP);
+  });
+
+  it('resolve joins cwd with input', () => {
+    const resolver = new DefaultPathResolver({ projectRoot: TMP, cwd: TMP });
+    const resolved = resolver.resolve('file.txt');
+    expect(resolved).toContain('file.txt');
+  });
+
+  it('isInsideRoot returns true for paths inside project', () => {
+    const resolver = new DefaultPathResolver({ projectRoot: TMP, cwd: TMP });
+    expect(resolver.isInsideRoot(path.join(TMP, 'file.txt'))).toBe(true);
+  });
+
+  it('isInsideRoot returns false for paths outside', () => {
+    const resolver = new DefaultPathResolver({ projectRoot: TMP, cwd: TMP });
+    expect(resolver.isInsideRoot('/etc/passwd')).toBe(false);
+    expect(resolver.isInsideRoot(path.join(os.homedir(), 'secret'))).toBe(false);
+  });
+
+  it('ensureInsideRoot throws for outside path', () => {
+    const resolver = new DefaultPathResolver({ projectRoot: TMP, cwd: TMP });
+    expect(() => resolver.ensureInsideRoot('/etc/passwd')).toThrow(/outside the project root/);
+  });
+
+  it('ensureInsideRoot returns path for inside path', () => {
+    const resolver = new DefaultPathResolver({ projectRoot: TMP, cwd: TMP });
+    const inside = path.join(TMP, 'file.txt');
+    expect(resolver.ensureInsideRoot(inside)).toBe(inside);
+  });
+});
+
+describe('safeResolve', () => {
+  it('resolves a relative path inside root', async () => {
+    const result = await safeResolve('file.txt', TMP, TMP);
+    expect(result).toBe(path.join(TMP, 'file.txt'));
+  });
+
+  it('resolves a subdirectory path', async () => {
+    const result = await safeResolve('subdir/file.txt', TMP, TMP);
+    expect(result).toBe(path.join(TMP, 'subdir', 'file.txt'));
+  });
+
+  it('throws for path escape via ..', async () => {
+    await expect(safeResolve('../etc/passwd', TMP, TMP)).rejects.toThrow(/outside the project root/);
+  });
+
+  it('throws for absolute path outside root', async () => {
+    await expect(safeResolve('/etc/passwd', TMP, TMP)).rejects.toThrow(/outside the project root/);
+  });
+});
+
+describe('safeResolveReal', () => {
+  it('resolves existing file inside root', async () => {
+    const result = await safeResolveReal('file.txt', TMP, TMP);
+    expect(result).toBe(path.join(TMP, 'file.txt'));
+  });
+
+  it('resolves non-existing path inside root (walks to ancestor)', async () => {
+    const result = await safeResolveReal('subdir/newfile.txt', TMP, TMP);
+    expect(result).toBe(path.join(TMP, 'subdir', 'newfile.txt'));
+  });
+
+  it('throws for symlink escape', async () => {
+    const linkPath = path.join(TMP, 'evil-link');
+    const target = os.tmpdir();
+    await fsp.symlink(target, linkPath, 'dir');
+    await expect(safeResolveReal('evil-link/file.txt', TMP, TMP)).rejects.toThrow(/outside|escape/i);
+  });
+});

package/tests/permission-policy.test.ts

@@ -0,0 +1,174 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { promises as fsp } from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { DefaultPermissionPolicy, matchGlob } from '../src/security/permission-policy.js';
+import type { Tool } from '../src/types/tool.js';
+import { EventBus } from '../src/kernel/events.js';
+
+function makeTool(overrides: Partial<Tool> = {}): Tool {
+  return {
+    name: 'bash',
+    description: 'run',
+    inputSchema: { type: 'object' },
+    permission: 'confirm',
+    mutating: true,
+    riskTier: 'destructive',
+    subjectKey: 'command',
+    capabilities: ['shell.arbitrary'],
+    async execute() {
+      return 'ok';
+    },
+    ...overrides,
+  };
+}
+
+describe('matchGlob', () => {
+  it('matches literal', () => {
+    expect(matchGlob('pnpm install', 'pnpm install')).toBe(true);
+  });
+  it('matches trailing *', () => {
+    expect(matchGlob('pnpm *', 'pnpm install')).toBe(true);
+    expect(matchGlob('pnpm *', 'npm install')).toBe(false);
+  });
+  it('matches ** across separators', () => {
+    expect(matchGlob('src/**', 'src/foo/bar.ts')).toBe(true);
+    expect(matchGlob('src/**', 'lib/foo.ts')).toBe(false);
+  });
+  it('matches bare * against anything non-empty', () => {
+    expect(matchGlob('*', 'anything')).toBe(true);
+  });
+});
+
+describe('DefaultPermissionPolicy', () => {
+  let homeDir: string;
+  let projectRoot: string;
+
+  beforeEach(async () => {
+    homeDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'fc-trust-home-'));
+    projectRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'fc-trust-proj-'));
+  });
+  afterEach(async () => {
+    await fsp.rm(homeDir, { recursive: true, force: true });
+    await fsp.rm(projectRoot, { recursive: true, force: true });
+  });
+
+  async function newPolicy(): Promise<DefaultPermissionPolicy> {
+    const p = new DefaultPermissionPolicy({ homeDir, projectRoot });
+    await p.load();
+    return p;
+  }
+
+  it('returns tool default permission when no rules match', async () => {
+    const p = await newPolicy();
+    const d = await p.evaluate(makeTool({ permission: 'auto', capabilities: undefined }), { command: 'ls' });
+    expect(d.permission).toBe('auto');
+  });
+
+  it('deny rule beats allow rule and default', async () => {
+    const p = await newPolicy();
+    await p.deny({ tool: 'bash', pattern: 'rm *' });
+    await p.allowOnce({ tool: 'bash', pattern: 'rm *' });
+    const d = await p.evaluate(makeTool(), { command: 'rm -rf x' });
+    expect(d.permission).toBe('deny');
+  });
+
+  it('session denyOnce beats trust allow', async () => {
+    const p = await newPolicy();
+    await p.trust({ tool: 'bash', pattern: 'pnpm *' });
+    p.denyOnce({ tool: 'bash', pattern: 'pnpm *' });
+    const d = await p.evaluate(makeTool(), { command: 'pnpm install' });
+    expect(d.permission).toBe('deny');
+  });
+
+  it('trust allow downgrades confirm to auto', async () => {
+    const p = await newPolicy();
+    await p.trust({ tool: 'bash', pattern: 'pnpm *' });
+    const d = await p.evaluate(makeTool(), { command: 'pnpm install' });
+    expect(d.permission).toBe('auto');
+    expect(d.source).toBe('trust');
+  });
+
+  it('session allowOnce downgrades confirm to auto for this session', async () => {
+    const p = await newPolicy();
+    p.allowOnce({ tool: 'bash', pattern: 'pnpm *' });
+    const d = await p.evaluate(makeTool(), { command: 'pnpm install' });
+    expect(d.permission).toBe('auto');
+    expect(d.source).toBe('user');
+  });
+
+  it('YOLO downgrades confirm to auto for non-destructive tools', async () => {
+    const p = await newPolicy();
+    p.setYolo(true);
+    const tool = makeTool({ permission: 'confirm', riskTier: 'standard' });
+    const d = await p.evaluate(tool, { path: 'src/x.ts' });
+    expect(d.permission).toBe('auto');
+    expect(d.source).toBe('yolo');
+  });
+
+  it('YOLO downgrades ALL confirms to auto, including destructive', async () => {
+    const p = await newPolicy();
+    p.setYolo(true);
+    const d = await p.evaluate(makeTool(), { command: 'rm -rf x' });
+    expect(d.permission).toBe('auto');
+    expect(d.source).toBe('yolo');
+  });
+
+  it('YOLO never bypasses explicit deny rules', async () => {
+    const p = await newPolicy();
+    await p.deny({ tool: 'bash', pattern: 'rm *' });
+    p.setYolo(true);
+    const d = await p.evaluate(makeTool(), { command: 'rm -rf x' });
+    expect(d.permission).toBe('deny');
+  });
+
+  it('dangerous-cap auto tool escalates to confirm when YOLO off', async () => {
+    const p = await newPolicy();
+    const tool = makeTool({ name: 'nettool', permission: 'auto', subjectKey: 'url', capabilities: ['net.outbound'], riskTier: 'safe' });
+    const d = await p.evaluate(tool, { url: 'https://x' });
+    expect(d.permission).toBe('confirm');
+  });
+
+  it('persists trust rules to home trust.json and reloads', async () => {
+    const p = await newPolicy();
+    await p.trust({ tool: 'bash', pattern: 'git *' });
+    const raw = await fsp.readFile(path.join(homeDir, 'trust.json'), 'utf8');
+    const parsed = JSON.parse(raw);
+    expect(parsed.allow).toContainEqual({ tool: 'bash', pattern: 'git *' });
+
+    const p2 = new DefaultPermissionPolicy({ homeDir, projectRoot });
+    await p2.load();
+    const d = await p2.evaluate(makeTool(), { command: 'git status' });
+    expect(d.permission).toBe('auto');
+  });
+
+  it('emits permission.persisted event', async () => {
+    const events = new EventBus();
+    const p = new DefaultPermissionPolicy({ homeDir, projectRoot, events });
+    await p.load();
+    const seen: unknown[] = [];
+    events.on('permission.persisted', (e) => seen.push(e));
+    await p.trust({ tool: 'bash', pattern: 'ls *' });
+    expect(seen).toEqual([{ action: 'allow', tool: 'bash', pattern: 'ls *', scope: 'trust' }]);
+  });
+
+  it('subject undefined (no subjectKey) only matches * rules', async () => {
+    const p = await newPolicy();
+    await p.trust({ tool: 'patch', pattern: '*' });
+    const tool = makeTool({ name: 'patch', permission: 'confirm', subjectKey: undefined, capabilities: undefined });
+    const d = await p.evaluate(tool, { diff: '...' });
+    expect(d.permission).toBe('auto');
+  });
+
+  it('project-local trust file merges (cannot weaken home deny)', async () => {
+    await fsp.mkdir(path.join(projectRoot, '.flowcodex'), { recursive: true });
+    await fsp.writeFile(
+      path.join(projectRoot, '.flowcodex', 'trust.json'),
+      JSON.stringify({ allow: [{ tool: 'bash', pattern: 'rm *' }], deny: [], yolo: false }),
+    );
+    const p = await newPolicy();
+    await p.deny({ tool: 'bash', pattern: 'rm *' });
+    const d = await p.evaluate(makeTool(), { command: 'rm -rf x' });
+    expect(d.permission).toBe('deny');
+  });
+});

package/tests/pipeline.test.ts

@@ -0,0 +1,193 @@
+import { describe, it, expect } from 'vitest';
+import { Pipeline, type Middleware } from '../src/kernel/pipeline.js';
+
+const mw = <T>(name: string, fn: (v: T) => T): Middleware<T> => ({
+  name,
+  handler: async (v, next) => next(fn(v)),
+});
+
+describe('Pipeline', () => {
+  describe('basic execution', () => {
+    it('runs an empty pipeline returning input', async () => {
+      const p = new Pipeline<number>();
+      expect(await p.run(42)).toBe(42);
+    });
+
+    it('runs a single middleware', async () => {
+      const p = new Pipeline<number>();
+      p.use(mw('double', (v) => v * 2));
+      expect(await p.run(5)).toBe(10);
+    });
+
+    it('runs middleware in order', async () => {
+      const p = new Pipeline<number>();
+      p.use(mw('add1', (v) => v + 1));
+      p.use(mw('mul2', (v) => v * 2));
+      expect(await p.run(3)).toBe(8);
+    });
+
+    it('middleware can short-circuit by not calling next', async () => {
+      const p = new Pipeline<string>();
+      p.use({
+        name: 'stop',
+        handler: async () => 'stopped',
+      });
+      p.use(mw('never', () => 'should-not-run'));
+      expect(await p.run('input')).toBe('stopped');
+    });
+  });
+
+  describe('duplicate name', () => {
+    it('throws on duplicate name', () => {
+      const p = new Pipeline<number>();
+      p.use(mw('a', (v) => v));
+      expect(() => p.use(mw('a', (v) => v))).toThrow(/already registered/);
+    });
+  });
+
+  describe('prepend', () => {
+    it('prepends middleware before existing', async () => {
+      const p = new Pipeline<number>();
+      p.use(mw('second', (v) => v + 100));
+      p.prepend(mw('first', (v) => v + 1));
+      expect(await p.run(0)).toBe(101);
+      expect(p.list()).toEqual(['first', 'second']);
+    });
+  });
+
+  describe('insertAt', () => {
+    it('inserts at a specific index', async () => {
+      const p = new Pipeline<number>();
+      p.use(mw('a', (v) => v + 1));
+      p.use(mw('c', (v) => v + 3));
+      p.insertAt(1, mw('b', (v) => v + 2));
+      expect(p.list()).toEqual(['a', 'b', 'c']);
+      expect(await p.run(0)).toBe(6);
+    });
+
+    it('clamps out-of-range index', () => {
+      const p = new Pipeline<number>();
+      p.use(mw('a', (v) => v));
+      p.insertAt(999, mw('b', (v) => v));
+      expect(p.list()).toEqual(['a', 'b']);
+    });
+  });
+
+  describe('insertBefore / insertAfter', () => {
+    it('inserts before target', () => {
+      const p = new Pipeline<number>();
+      p.use(mw('a', (v) => v));
+      p.use(mw('c', (v) => v));
+      p.insertBefore('c', mw('b', (v) => v));
+      expect(p.list()).toEqual(['a', 'b', 'c']);
+    });
+
+    it('inserts after target', () => {
+      const p = new Pipeline<number>();
+      p.use(mw('a', (v) => v));
+      p.use(mw('c', (v) => v));
+      p.insertAfter('a', mw('b', (v) => v));
+      expect(p.list()).toEqual(['a', 'b', 'c']);
+    });
+
+    it('throws when target not found (non-optional)', () => {
+      const p = new Pipeline<number>();
+      expect(() => p.insertBefore('missing', mw('x', (v) => v))).toThrow(/not found/);
+    });
+
+    it('silently no-ops when optional and target missing', () => {
+      const p = new Pipeline<number>();
+      p.insertBefore('missing', mw('x', (v) => v), { optional: true });
+      expect(p.list()).toEqual([]);
+    });
+  });
+
+  describe('replace', () => {
+    it('replaces a middleware by name', async () => {
+      const p = new Pipeline<number>();
+      p.use(mw('a', (v) => v + 1));
+      p.replace('a', mw('a', (v) => v + 100));
+      expect(await p.run(0)).toBe(100);
+    });
+  });
+
+  describe('remove', () => {
+    it('removes a middleware by name', () => {
+      const p = new Pipeline<number>();
+      p.use(mw('a', (v) => v));
+      p.use(mw('b', (v) => v));
+      p.remove('a');
+      expect(p.list()).toEqual(['b']);
+    });
+  });
+
+  describe('size', () => {
+    it('returns chain length', () => {
+      const p = new Pipeline<number>();
+      p.use(mw('a', (v) => v));
+      p.use(mw('b', (v) => v));
+      expect(p.size()).toBe(2);
+    });
+  });
+
+  describe('error handler', () => {
+    it('swallows error when handler returns swallow', async () => {
+      const p = new Pipeline<number>();
+      p.use(mw('safe', (v) => v + 1));
+      p.use({
+        name: 'crash',
+        handler: async () => { throw new Error('boom'); },
+      });
+      p.use(mw('after', (v) => v + 100));
+      p.setErrorHandler(() => 'swallow');
+      const result = await p.run(0);
+      expect(result).toBe(1);
+    });
+
+    it('rethrows when handler returns rethrow', async () => {
+      const p = new Pipeline<number>();
+      p.use({
+        name: 'crash',
+        handler: async () => { throw new Error('boom'); },
+      });
+      p.setErrorHandler(() => 'rethrow');
+      await expect(p.run(0)).rejects.toThrow('boom');
+    });
+
+    it('error handler receives middleware name and error', async () => {
+      const p = new Pipeline<number>();
+      p.use({
+        name: 'crash',
+        handler: async () => { throw new Error('boom'); },
+      });
+      let receivedName = '';
+      let receivedErr: unknown = null;
+      p.setErrorHandler((ev) => {
+        receivedName = ev.middleware;
+        receivedErr = ev.err;
+        return 'swallow';
+      });
+      await p.run(0);
+      expect(receivedName).toBe('crash');
+      expect(receivedErr).toBeInstanceOf(Error);
+    });
+  });
+
+  describe('asReadonly', () => {
+    it('returns a frozen view with live chain', () => {
+      const p = new Pipeline<number>();
+      p.use(mw('a', (v) => v));
+      const ro = p.asReadonly();
+      p.use(mw('b', (v) => v));
+      expect(ro.size).toBe(2);
+      expect(ro.list()).toEqual(['a', 'b']);
+    });
+
+    it('readonly run delegates to pipeline', async () => {
+      const p = new Pipeline<number>();
+      p.use(mw('double', (v) => v * 2));
+      const ro = p.asReadonly();
+      expect(await ro.run(5)).toBe(10);
+    });
+  });
+});