@flowcodex/core 0.3.0

package/tests/tool-registry.test.ts

@@ -0,0 +1,143 @@
+import { describe, it, expect } from 'vitest';
+import { ToolRegistry } from '../src/execution/tool-registry.js';
+import type { Tool } from '../src/types/tool.js';
+
+function makeTool(name: string): Tool {
+  return {
+    name,
+    description: `Test tool ${name}`,
+    inputSchema: { type: 'object', properties: { x: { type: 'string' } }, required: ['x'] },
+    permission: 'auto',
+    mutating: false,
+    async execute() {
+      return { ok: true };
+    },
+  };
+}
+
+describe('ToolRegistry', () => {
+  it('should register and get a tool', () => {
+    const reg = new ToolRegistry();
+    const tool = makeTool('foo');
+    reg.register(tool, 'core');
+    expect(reg.get('foo')).toBe(tool);
+    expect(reg.has('foo')).toBe(true);
+    expect(reg.size).toBe(1);
+  });
+
+  it('should throw on duplicate registration', () => {
+    const reg = new ToolRegistry();
+    reg.register(makeTool('foo'), 'core');
+    expect(() => reg.register(makeTool('foo'), 'core')).toThrow('already registered');
+  });
+
+  it('tryRegister should return false on conflict', () => {
+    const reg = new ToolRegistry();
+    expect(reg.tryRegister(makeTool('foo'), 'core')).toBe(true);
+    expect(reg.tryRegister(makeTool('foo'), 'core')).toBe(false);
+  });
+
+  it('registerDefault should be no-op if exists', () => {
+    const reg = new ToolRegistry();
+    const t1 = makeTool('foo');
+    const t2 = makeTool('foo');
+    reg.registerDefault(t1, 'core');
+    reg.registerDefault(t2, 'plugin');
+    expect(reg.get('foo')).toBe(t1);
+  });
+
+  it('registerAll should register multiple tools silently', () => {
+    const reg = new ToolRegistry();
+    reg.registerAll([makeTool('a'), makeTool('b'), makeTool('a')], 'core');
+    expect(reg.size).toBe(2);
+  });
+
+  it('override should replace existing tool', () => {
+    const reg = new ToolRegistry();
+    const t1 = makeTool('foo');
+    const t2 = makeTool('foo');
+    reg.register(t1, 'core');
+    reg.override('foo', t2, 'plugin');
+    expect(reg.get('foo')).toBe(t2);
+    expect(reg.ownerOf('foo')).toBe('plugin');
+  });
+
+  it('override should throw if not registered', () => {
+    const reg = new ToolRegistry();
+    expect(() => reg.override('missing', makeTool('missing'), 'core')).toThrow('not registered');
+  });
+
+  it('list should return all tools', () => {
+    const reg = new ToolRegistry();
+    reg.register(makeTool('a'), 'core');
+    reg.register(makeTool('b'), 'core');
+    expect(reg.list().map((t) => t.name).sort()).toEqual(['a', 'b']);
+  });
+
+  it('listWithOwner should include owner', () => {
+    const reg = new ToolRegistry();
+    reg.register(makeTool('a'), 'core');
+    reg.register(makeTool('b'), 'plugin');
+    const entries = reg.listWithOwner();
+    expect(entries).toHaveLength(2);
+    const aEntry = entries.find((e) => e.tool.name === 'a');
+    expect(aEntry?.owner).toBe('core');
+  });
+
+  it('clone should produce independent copy', () => {
+    const reg = new ToolRegistry();
+    reg.register(makeTool('a'), 'core');
+    const copy = reg.clone();
+    copy.register(makeTool('b'), 'core');
+    expect(reg.size).toBe(1);
+    expect(copy.size).toBe(2);
+  });
+
+  it('totalEstDefTokens should be positive', () => {
+    const reg = new ToolRegistry();
+    reg.register(makeTool('a'), 'core');
+    expect(reg.totalEstDefTokens).toBeGreaterThan(0);
+  });
+});
+
+describe('ToolRegistry.filter', () => {
+  function makeTieredTool(name: string, tier: 'essential' | 'extended' | undefined): Tool {
+    return {
+      name,
+      description: `Tool ${name}`,
+      inputSchema: { type: 'object' },
+      permission: 'auto',
+      mutating: false,
+      tier,
+      async execute() {
+        return {};
+      },
+    };
+  }
+
+  it('removes tools that do not match the predicate', () => {
+    const reg = new ToolRegistry();
+    reg.register(makeTieredTool('a', 'essential'), 'core');
+    reg.register(makeTieredTool('b', 'extended'), 'core');
+    reg.register(makeTieredTool('c', 'essential'), 'core');
+    const counts = reg.filter((t) => t.tier === 'essential');
+    expect(counts).toEqual({ total: 3, kept: 2 });
+    expect(reg.has('a')).toBe(true);
+    expect(reg.has('b')).toBe(false);
+    expect(reg.has('c')).toBe(true);
+  });
+
+  it('returns zero counts for empty registry', () => {
+    const reg = new ToolRegistry();
+    const counts = reg.filter(() => true);
+    expect(counts).toEqual({ total: 0, kept: 0 });
+  });
+
+  it('keeps all when predicate is always true', () => {
+    const reg = new ToolRegistry();
+    reg.register(makeTieredTool('a', 'essential'), 'core');
+    reg.register(makeTieredTool('b', 'extended'), 'core');
+    const counts = reg.filter(() => true);
+    expect(counts).toEqual({ total: 2, kept: 2 });
+  });
+});

package/tests/tracer.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest';
+import { NoopTracer, NoopSpan } from '../src/infrastructure/tracer.js';
+
+describe('NoopTracer', () => {
+  it('startSpan returns a NoopSpan', () => {
+    const tracer = new NoopTracer();
+    const span = tracer.startSpan('test');
+    expect(span).toBeInstanceOf(NoopSpan);
+  });
+
+  it('startSpan with attrs does not throw', () => {
+    const tracer = new NoopTracer();
+    expect(() => tracer.startSpan('test', { key: 'value' })).not.toThrow();
+  });
+});
+
+describe('NoopSpan', () => {
+  it('setAttribute returns this (chainable)', () => {
+    const span = new NoopSpan();
+    expect(span.setAttribute('key', 'value')).toBe(span);
+  });
+
+  it('recordError does not throw', () => {
+    const span = new NoopSpan();
+    expect(() => span.recordError(new Error('test'))).not.toThrow();
+  });
+
+  it('end does not throw', () => {
+    const span = new NoopSpan();
+    expect(() => span.end()).not.toThrow();
+  });
+});

package/tests/ulid.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import { ulid, ulidTime, isUlid } from '../src/utils/ulid.js';
+
+describe('ulid', () => {
+  it('generates a 26-character string', () => {
+    const id = ulid();
+    expect(id).toHaveLength(26);
+  });
+
+  it('generates valid ULID characters only', () => {
+    for (let i = 0; i < 100; i++) {
+      const id = ulid();
+      expect(isUlid(id)).toBe(true);
+    }
+  });
+
+  it('is sortable by time', () => {
+    const a = ulid(1700000000000);
+    const b = ulid(1700000000001);
+    expect(a < b).toBe(true);
+  });
+
+  it('same millisecond produces monotonic increment', () => {
+    const now = Date.now();
+    const a = ulid(now);
+    const b = ulid(now);
+    expect(a < b).toBe(true);
+  });
+
+  it('different times produce different ids', () => {
+    const ids = new Set<string>();
+    for (let i = 0; i < 1000; i++) {
+      ids.add(ulid(1700000000000 + i));
+    }
+    expect(ids.size).toBe(1000);
+  });
+
+  it('ulidTime extracts the timestamp', () => {
+    const now = 1700000000123;
+    const id = ulid(now);
+    expect(ulidTime(id)).toBe(now);
+  });
+
+  it('isUlid returns false for invalid strings', () => {
+    expect(isUlid('short')).toBe(false);
+    expect(isUlid('0O0I0O0I0O0O0I0O0I0O0I0O0I')).toBe(false); // contains O and I
+    expect(isUlid('')).toBe(false);
+  });
+
+  it('ulidTime throws for invalid ULID', () => {
+    expect(() => ulidTime('invalid')).toThrow();
+  });
+});

package/tests/version-check.test.ts

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest';
+import { compareVersions, fetchLatestVersion, checkForUpdate } from '../src/utils/version-check.js';
+
+describe('compareVersions', () => {
+  it('equal versions return 0', () => {
+    expect(compareVersions('1.0.0', '1.0.0')).toBe(0);
+  });
+  it('older current returns -1', () => {
+    expect(compareVersions('1.0.0', '1.0.1')).toBe(-1);
+  });
+  it('newer current returns 1', () => {
+    expect(compareVersions('2.0.0', '1.0.0')).toBe(1);
+  });
+  it('handles different segment counts', () => {
+    expect(compareVersions('1.0', '1.0.1')).toBe(-1);
+  });
+});
+
+describe('fetchLatestVersion', () => {
+  it('returns version from successful response', async () => {
+    const mockFetch = async (): Promise<Response> =>
+      new Response(JSON.stringify({ version: '0.3.0' }), { status: 200 }) as Response;
+    const result = await fetchLatestVersion('@flowcodex/cli', { fetchImpl: mockFetch as typeof fetch });
+    expect(result).toBe('0.3.0');
+  });
+  it('returns undefined on 404', async () => {
+    const mockFetch = async (): Promise<Response> => new Response('Not Found', { status: 404 }) as Response;
+    const result = await fetchLatestVersion('@flowcodex/cli', { fetchImpl: mockFetch as typeof fetch });
+    expect(result).toBeUndefined();
+  });
+  it('returns undefined on network error', async () => {
+    const mockFetch = async (): Promise<Response> => { throw new Error('network'); };
+    const result = await fetchLatestVersion('@flowcodex/cli', { fetchImpl: mockFetch as typeof fetch });
+    expect(result).toBeUndefined();
+  });
+});
+
+describe('checkForUpdate', () => {
+  it('returns updateAvailable true when latest is newer', async () => {
+    const mockFetch = async (): Promise<Response> =>
+      new Response(JSON.stringify({ version: '0.3.0' }), { status: 200 }) as Response;
+    const info = await checkForUpdate('0.2.2', '@flowcodex/cli', { fetchImpl: mockFetch as typeof fetch });
+    expect(info?.updateAvailable).toBe(true);
+    expect(info?.latest).toBe('0.3.0');
+  });
+  it('returns updateAvailable false when current', async () => {
+    const mockFetch = async (): Promise<Response> =>
+      new Response(JSON.stringify({ version: '0.2.2' }), { status: 200 }) as Response;
+    const info = await checkForUpdate('0.2.2', '@flowcodex/cli', { fetchImpl: mockFetch as typeof fetch });
+    expect(info?.updateAvailable).toBe(false);
+  });
+  it('returns undefined when fetch fails', async () => {
+    const mockFetch = async (): Promise<Response> => { throw new Error('network'); };
+    const info = await checkForUpdate('0.2.2', '@flowcodex/cli', { fetchImpl: mockFetch as typeof fetch });
+    expect(info).toBeUndefined();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "composite": false,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/tsup.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+  entry: {
+    index: 'src/index.ts',
+    'kernel/index': 'src/kernel/index.ts',
+  },
+  format: ['esm'],
+  target: 'es2024',
+  platform: 'node',
+  dts: true,
+  clean: true,
+  sourcemap: true,
+  treeshake: true,
+  splitting: false,
+});