@ontrails/trails 1.0.0-beta.0

package/src/__tests__/create.test.ts

@@ -0,0 +1,349 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+
+import { Result } from '@ontrails/core';
+
+import { addSurface } from '../trails/add-surface.js';
+import { addVerify } from '../trails/add-verify.js';
+import { createRoute } from '../trails/create.js';
+import { createScaffold } from '../trails/create-scaffold.js';
+import { isInsideProject } from '../trails/project.js';
+
+type Starter = 'empty' | 'entity' | 'hello';
+type Surface = 'cli' | 'mcp';
+
+const makeTempProject = (): string =>
+  join(
+    tmpdir(),
+    `trails-blaze-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
+  );
+
+const readJson = (dir: string, relativePath: string): Record<string, unknown> =>
+  JSON.parse(readFileSync(join(dir, relativePath), 'utf8')) as Record<
+    string,
+    unknown
+  >;
+
+const readText = (dir: string, relativePath: string): string =>
+  readFileSync(join(dir, relativePath), 'utf8');
+
+const expectPaths = (
+  dir: string,
+  relativePaths: readonly string[],
+  expected: boolean
+): void => {
+  for (const relativePath of relativePaths) {
+    expect(existsSync(join(dir, relativePath))).toBe(expected);
+  }
+};
+
+const expectContainsAll = (
+  content: string,
+  snippets: readonly string[]
+): void => {
+  for (const snippet of snippets) {
+    expect(content).toContain(snippet);
+  }
+};
+
+const expectOk = <T>(result: Result<T, Error>): T => {
+  if (result.isErr()) {
+    throw result.error;
+  }
+  return result.value;
+};
+
+const expectErr = <T>(result: Result<T, Error>): Error => {
+  if (result.isOk()) {
+    throw new Error('Expected error result');
+  }
+  return result.error;
+};
+
+const runFollow = async (
+  id: string,
+  input: unknown
+): Promise<Result<unknown, Error>> => {
+  switch (id) {
+    case 'create.scaffold': {
+      return await createScaffold.implementation(input as never, {} as never);
+    }
+    case 'add.surface': {
+      return await addSurface.implementation(input as never, {} as never);
+    }
+    case 'add.verify': {
+      return await addVerify.implementation(input as never, {} as never);
+    }
+    default: {
+      return Result.err(new Error(`Unknown follow target: ${id}`));
+    }
+  }
+};
+
+const runBlaze = (
+  projectDir: string,
+  overrides?: Partial<{
+    starter: Starter;
+    surfaces: readonly Surface[];
+    verify: boolean;
+  }>
+) =>
+  createRoute.implementation(
+    {
+      dir: dirname(projectDir),
+      name: basename(projectDir),
+      starter: overrides?.starter ?? 'hello',
+      surfaces: [...(overrides?.surfaces ?? ['cli'])],
+      verify: overrides?.verify ?? true,
+    },
+    { follow: runFollow } as never
+  );
+
+const setupMinimalProject = (dir: string): void => {
+  mkdirSync(join(dir, 'src'), { recursive: true });
+  mkdirSync(join(dir, '.trails'), { recursive: true });
+  writeFileSync(
+    join(dir, 'src', 'app.ts'),
+    "import { topo } from '@ontrails/core';\nexport const app = topo('test');\n"
+  );
+  writeFileSync(
+    join(dir, 'package.json'),
+    JSON.stringify(
+      { dependencies: { '@ontrails/core': 'workspace:*' }, name: 'test' },
+      null,
+      2
+    )
+  );
+};
+
+const assertDefaultProjectFiles = (dir: string): void => {
+  expectPaths(
+    dir,
+    [
+      'package.json',
+      'tsconfig.json',
+      '.gitignore',
+      '.oxlintrc.json',
+      '.oxfmtrc.jsonc',
+      'src/app.ts',
+      '.trails',
+      'src/cli.ts',
+      'src/trails/hello.ts',
+      '__tests__/examples.test.ts',
+      'lefthook.yml',
+    ],
+    true
+  );
+};
+
+const assertCliPackage = (dir: string): void => {
+  const pkg = readJson(dir, 'package.json');
+  expect(pkg['name']).toBe(basename(dir));
+
+  const deps = pkg['dependencies'] as Record<string, string>;
+  expect(deps['@ontrails/core']).toBe('workspace:*');
+  expect(deps['@ontrails/cli']).toBe('workspace:*');
+  expect(deps['commander']).toBeDefined();
+
+  const devDeps = pkg['devDependencies'] as Record<string, string>;
+  expect(devDeps['@ontrails/testing']).toBe('workspace:*');
+  expect(devDeps['@ontrails/warden']).toBe('workspace:*');
+};
+
+const assertHelloApp = (dir: string): void => {
+  expectContainsAll(readText(dir, 'src/app.ts'), [
+    'topo',
+    `'${basename(dir)}'`,
+    'hello',
+  ]);
+  expectContainsAll(readText(dir, 'src/trails/hello.ts'), [
+    "import { Result, trail } from '@ontrails/core'",
+    'return Result.ok({ message:',
+  ]);
+};
+
+const assertEntityStarter = (dir: string): void => {
+  expectPaths(
+    dir,
+    [
+      'src/trails/entity.ts',
+      'src/trails/search.ts',
+      'src/trails/onboard.ts',
+      'src/events/entity-events.ts',
+      'src/store.ts',
+    ],
+    true
+  );
+  expectPaths(dir, ['src/trails/hello.ts'], false);
+  expectContainsAll(readText(dir, 'src/app.ts'), [
+    "import * as entity from './trails/entity.js'",
+    "import * as search from './trails/search.js'",
+    "import * as onboard from './trails/onboard.js'",
+    "import * as entityEvents from './events/entity-events.js'",
+  ]);
+  expectContainsAll(readText(dir, 'src/trails/entity.ts'), [
+    "import { Result, trail } from '@ontrails/core'",
+    'return Result.ok({ id: input.id, name:',
+    "return Result.ok({ id: '1', name: input.name })",
+  ]);
+  expectContainsAll(readText(dir, 'src/trails/search.ts'), [
+    "import { Result, trail } from '@ontrails/core'",
+    'return Result.ok({ results: [] })',
+  ]);
+  expectContainsAll(readText(dir, 'src/trails/onboard.ts'), [
+    "import { Result, hike } from '@ontrails/core'",
+    'return Result.ok({ onboarded: true })',
+  ]);
+};
+
+const assertMcpSurface = (dir: string): void => {
+  expectPaths(dir, ['src/mcp.ts'], true);
+  expectPaths(dir, ['src/cli.ts'], false);
+  expectContainsAll(readText(dir, 'src/mcp.ts'), [
+    "import { blaze } from '@ontrails/mcp'",
+    'await blaze(app)',
+  ]);
+
+  const deps = readJson(dir, 'package.json')['dependencies'] as Record<
+    string,
+    string
+  >;
+  expect(deps['@ontrails/mcp']).toBe('workspace:*');
+  expect(deps['@ontrails/cli']).toBeUndefined();
+};
+
+const assertVerifySkipped = (dir: string): void => {
+  expectPaths(dir, ['__tests__/examples.test.ts', 'lefthook.yml'], false);
+  expect(readJson(dir, 'package.json')['devDependencies']).toBeUndefined();
+};
+
+const assertEmptyStarter = (dir: string): void => {
+  expectPaths(dir, ['src/trails/.gitkeep'], true);
+  expectPaths(dir, ['src/trails/hello.ts'], false);
+  const appContent = readText(dir, 'src/app.ts');
+  expect(appContent).toContain(`topo('${basename(dir)}')`);
+  expect(appContent).not.toContain('import * as');
+};
+
+const withTempProject = async (
+  assertion: (dir: string) => Promise<void>
+): Promise<void> => {
+  const dir = makeTempProject();
+  try {
+    await assertion(dir);
+  } finally {
+    rmSync(dir, { force: true, recursive: true });
+  }
+};
+
+describe('trails blaze', () => {
+  describe('create mode', () => {
+    test('generates project structure with defaults', async () => {
+      await withTempProject(async (dir) => {
+        expectOk(await runBlaze(dir));
+        assertDefaultProjectFiles(dir);
+        assertCliPackage(dir);
+        assertHelloApp(dir);
+      });
+    });
+
+    test('generates with entity starter', async () => {
+      await withTempProject(async (dir) => {
+        expectOk(await runBlaze(dir, { starter: 'entity' }));
+        assertEntityStarter(dir);
+      });
+    });
+
+    test('generates with MCP surface', async () => {
+      await withTempProject(async (dir) => {
+        expectOk(await runBlaze(dir, { surfaces: ['mcp'] }));
+        assertMcpSurface(dir);
+      });
+    });
+
+    test('skips verification when verify is false', async () => {
+      await withTempProject(async (dir) => {
+        expectOk(await runBlaze(dir, { verify: false }));
+        assertVerifySkipped(dir);
+      });
+    });
+
+    test('generates with empty starter', async () => {
+      await withTempProject(async (dir) => {
+        expectOk(await runBlaze(dir, { starter: 'empty' }));
+        assertEmptyStarter(dir);
+      });
+    });
+  });
+
+  describe('add-surface mode', () => {
+    test('adds MCP to existing project', async () => {
+      await withTempProject(async (dir) => {
+        setupMinimalProject(dir);
+        const result = expectOk(
+          await addSurface.implementation({ dir, surface: 'mcp' }, {} as never)
+        );
+
+        expect(result.created).toBe('src/mcp.ts');
+        expect(result.dependency).toBe('@ontrails/mcp');
+        expectPaths(dir, ['src/mcp.ts'], true);
+        expectContainsAll(readText(dir, 'src/mcp.ts'), [
+          "import { blaze } from '@ontrails/mcp'",
+        ]);
+        const deps = readJson(dir, 'package.json')['dependencies'] as Record<
+          string,
+          string
+        >;
+        expect(deps['@ontrails/mcp']).toBe('workspace:*');
+      });
+    });
+
+    test('detects already-blazed surface', async () => {
+      await withTempProject(async (dir) => {
+        mkdirSync(join(dir, 'src'), { recursive: true });
+        mkdirSync(join(dir, '.trails'), { recursive: true });
+        writeFileSync(join(dir, 'src', 'mcp.ts'), 'existing content');
+
+        const error = expectErr(
+          await addSurface.implementation({ dir, surface: 'mcp' }, {} as never)
+        );
+        expect(error.message).toBe('MCP is already blazed. Nothing to do.');
+      });
+    });
+  });
+});
+
+describe('isInsideProject', () => {
+  test('detects .trails directory', async () => {
+    await withTempProject(async (dir) => {
+      mkdirSync(join(dir, '.trails'), { recursive: true });
+      expect(await isInsideProject(dir)).toBe(true);
+    });
+  });
+
+  test('detects topo in src/', async () => {
+    await withTempProject(async (dir) => {
+      mkdirSync(join(dir, 'src'), { recursive: true });
+      writeFileSync(
+        join(dir, 'src', 'app.ts'),
+        "import { topo } from '@ontrails/core';\nexport const app = topo('app');\n"
+      );
+      expect(await isInsideProject(dir)).toBe(true);
+    });
+  });
+
+  test('returns false for empty directory', async () => {
+    await withTempProject(async (dir) => {
+      mkdirSync(dir, { recursive: true });
+      expect(await isInsideProject(dir)).toBe(false);
+    });
+  });
+});

package/src/__tests__/guide.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { AnyTrail } from '@ontrails/core';
+import { trail, topo, Result } from '@ontrails/core';
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Test fixtures
+// ---------------------------------------------------------------------------
+
+const helloTrail = trail('hello', {
+  description: 'Say hello',
+  detours: {
+    NotFoundError: ['search'],
+  },
+  examples: [
+    {
+      expected: { message: 'Hello, world!' },
+      input: {},
+      name: 'Default greeting',
+    },
+    {
+      expected: { message: 'Hello, Trails!' },
+      input: { name: 'Trails' },
+      name: 'Named greeting',
+    },
+  ],
+  implementation: (input) => {
+    const name = input.name ?? 'world';
+    return Result.ok({ message: `Hello, ${name}!` });
+  },
+  input: z.object({ name: z.string().optional() }),
+  output: z.object({ message: z.string() }),
+  readOnly: true,
+});
+
+const app = topo('test-app', { hello: helloTrail });
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('trails guide', () => {
+  test('lists trails with descriptions', () => {
+    const items = app.list();
+    expect(items.length).toBe(1);
+
+    const [hello] = items;
+    expect(hello).toBeDefined();
+    expect(hello?.id).toBe('hello');
+
+    expect((hello as AnyTrail).description).toBe('Say hello');
+  });
+
+  test('trail detail includes examples', () => {
+    const item = app.get('hello') as AnyTrail;
+    expect(item).toBeDefined();
+    expect(item.examples).toBeDefined();
+    expect(item.examples?.length).toBe(2);
+    expect(item.examples?.[0]?.name).toBe('Default greeting');
+  });
+
+  test('JSON output for trail is valid', () => {
+    const t = app.get('hello') as AnyTrail;
+    expect(t).toBeDefined();
+
+    const json = JSON.stringify({
+      description: t.description,
+      detours: t.detours,
+      examples: t.examples,
+      id: t.id,
+      kind: t.kind,
+    });
+
+    const parsed = JSON.parse(json) as Record<string, unknown>;
+    expect(parsed['id']).toBe('hello');
+    expect(parsed['kind']).toBe('trail');
+    expect(parsed['description']).toBe('Say hello');
+  });
+
+  test('non-existent trail returns undefined from topo', () => {
+    const item = app.get('does-not-exist');
+    expect(item).toBeUndefined();
+  });
+
+  test('detours are accessible on trail', () => {
+    const t = app.get('hello') as AnyTrail;
+    expect(t).toBeDefined();
+    expect(t.detours?.['NotFoundError']).toEqual(['search']);
+  });
+});

package/src/__tests__/load-app.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, test } from 'bun:test';
+import { resolve } from 'node:path';
+
+import { loadApp } from '../trails/load-app.js';
+
+describe('loadApp', () => {
+  test('resolves relative module paths from cwd', async () => {
+    // import.meta.dir is src/__tests__/, go up two to get apps/trails/
+    const cwd = resolve(import.meta.dir, '../..');
+    const app = await loadApp('./src/app.ts', cwd);
+
+    expect(app.name).toBe('trails');
+    expect(app.get('survey')).toBeDefined();
+  });
+});

package/src/__tests__/survey.test.ts

@@ -0,0 +1,161 @@
+import { describe, expect, test } from 'bun:test';
+
+import { topo, trail, Result } from '@ontrails/core';
+import {
+  generateSurfaceMap,
+  hashSurfaceMap,
+  diffSurfaceMaps,
+} from '@ontrails/schema';
+import type { SurfaceMap } from '@ontrails/schema';
+import { z } from 'zod';
+
+import { generateBriefReport } from '../trails/survey.js';
+import type { BriefReport } from '../trails/survey.js';
+
+// ---------------------------------------------------------------------------
+// Test fixtures
+// ---------------------------------------------------------------------------
+
+const helloTrail = trail('hello', {
+  description: 'Say hello',
+  detours: {
+    NotFoundError: ['search'],
+  },
+  examples: [
+    {
+      expected: { message: 'Hello, world!' },
+      input: {},
+      name: 'Default greeting',
+    },
+  ],
+  implementation: (input) => {
+    const name = input.name ?? 'world';
+    return Result.ok({ message: `Hello, ${name}!` });
+  },
+  input: z.object({ name: z.string().optional() }),
+  output: z.object({ message: z.string() }),
+  readOnly: true,
+});
+
+const byeTrail = trail('bye', {
+  description: 'Say goodbye',
+  implementation: (input) => Result.ok({ message: `Goodbye, ${input.name}!` }),
+  input: z.object({ name: z.string() }),
+  output: z.object({ message: z.string() }),
+});
+
+const app = topo('test-app', { bye: byeTrail, hello: helloTrail });
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('trails survey', () => {
+  test('generateSurfaceMap includes all trails', () => {
+    const surfaceMap = generateSurfaceMap(app);
+    expect(surfaceMap.entries.length).toBe(2);
+    const ids = surfaceMap.entries.map((e) => e.id);
+    expect(ids).toContain('hello');
+    expect(ids).toContain('bye');
+  });
+
+  test('surface map entries have expected fields', () => {
+    const surfaceMap = generateSurfaceMap(app);
+    const hello = surfaceMap.entries.find((e) => e.id === 'hello');
+    expect(hello).toBeDefined();
+    expect(hello?.kind).toBe('trail');
+    expect(hello?.readOnly).toBe(true);
+    expect(hello?.exampleCount).toBe(1);
+  });
+
+  test('JSON output is valid JSON', () => {
+    const surfaceMap = generateSurfaceMap(app);
+    const json = JSON.stringify(surfaceMap, null, 2);
+    const parsed = JSON.parse(json) as SurfaceMap;
+    expect(parsed.version).toBe('1.0');
+    expect(parsed.entries.length).toBe(2);
+  });
+
+  test('hashSurfaceMap produces stable hash', () => {
+    const surfaceMap = generateSurfaceMap(app);
+    const hash1 = hashSurfaceMap(surfaceMap);
+    const hash2 = hashSurfaceMap(surfaceMap);
+    expect(hash1).toBe(hash2);
+    // SHA-256 hex
+    expect(hash1.length).toBe(64);
+  });
+
+  test('diffSurfaceMaps detects added trails', () => {
+    const prev = generateSurfaceMap(topo('test', { hello: helloTrail }));
+    const curr = generateSurfaceMap(app);
+    const diff = diffSurfaceMaps(prev, curr);
+
+    expect(diff.info.length).toBeGreaterThan(0);
+    const addedBye = diff.info.find((e) => e.id === 'bye');
+    expect(addedBye).toBeDefined();
+    expect(addedBye?.change).toBe('added');
+  });
+
+  test('diffSurfaceMaps detects removed trails', () => {
+    const prev = generateSurfaceMap(app);
+    const curr = generateSurfaceMap(topo('test', { hello: helloTrail }));
+    const diff = diffSurfaceMaps(prev, curr);
+
+    expect(diff.hasBreaking).toBe(true);
+    const removedBye = diff.breaking.find((e) => e.id === 'bye');
+    expect(removedBye).toBeDefined();
+    expect(removedBye?.change).toBe('removed');
+  });
+
+  test('diffSurfaceMaps returns empty for identical maps', () => {
+    const map = generateSurfaceMap(app);
+    const diff = diffSurfaceMaps(map, map);
+    expect(diff.entries.length).toBe(0);
+    expect(diff.hasBreaking).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Brief mode (formerly scout)
+// ---------------------------------------------------------------------------
+
+describe('trails survey --brief', () => {
+  test('produces a valid capability report', () => {
+    const report = generateBriefReport(app);
+    expect(report.name).toBe('test-app');
+    expect(report.contractVersion).toBe('2026-03');
+  });
+
+  test('report includes correct trail count', () => {
+    const report = generateBriefReport(app);
+    expect(report.trails).toBe(2);
+    expect(report.hikes).toBe(0);
+    expect(report.events).toBe(0);
+  });
+
+  test('detects features in use', () => {
+    const report = generateBriefReport(app);
+    expect(report.features.outputSchemas).toBe(true);
+    expect(report.features.examples).toBe(true);
+    expect(report.features.detours).toBe(true);
+    expect(report.features.hikes).toBe(false);
+    expect(report.features.events).toBe(false);
+  });
+
+  test('JSON output is valid', () => {
+    const report = generateBriefReport(app);
+    const json = JSON.stringify(report, null, 2);
+    const parsed = JSON.parse(json) as BriefReport;
+    expect(parsed.name).toBe('test-app');
+    expect(parsed.trails).toBe(2);
+  });
+
+  test('empty app reports zero features', () => {
+    const emptyApp = topo('empty', {});
+    const report = generateBriefReport(emptyApp);
+    expect(report.trails).toBe(0);
+    expect(report.features.outputSchemas).toBe(false);
+    expect(report.features.examples).toBe(false);
+    expect(report.features.detours).toBe(false);
+  });
+});

package/src/__tests__/warden.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { formatWardenReport, runWarden } from '@ontrails/warden';
+
+const makeTempDir = (): string => {
+  const dir = join(
+    tmpdir(),
+    `trails-warden-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
+  );
+  mkdirSync(dir, { recursive: true });
+  return dir;
+};
+
+describe('trails warden', () => {
+  test('runs lint + drift checks and produces a report', async () => {
+    const dir = makeTempDir();
+    try {
+      writeFileSync(
+        join(dir, 'good.ts'),
+        `trail("hello", {
+  implementation: async (input, ctx) => {
+    return Result.ok({ message: "hi" });
+  }
+})`
+      );
+
+      const report = await runWarden({ rootDir: dir });
+      expect(report.diagnostics).toBeDefined();
+      expect(typeof report.errorCount).toBe('number');
+      expect(typeof report.warnCount).toBe('number');
+      expect(typeof report.passed).toBe('boolean');
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('lintOnly skips drift detection', async () => {
+    const dir = makeTempDir();
+    try {
+      writeFileSync(join(dir, 'empty.ts'), 'export {}');
+      const report = await runWarden({ lintOnly: true, rootDir: dir });
+      expect(report.drift).toBeNull();
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('driftOnly skips lint rules', async () => {
+    const dir = makeTempDir();
+    try {
+      writeFileSync(
+        join(dir, 'bad.ts'),
+        `trail("x", {
+  implementation: async () => { throw new Error("boom"); }
+})`
+      );
+      const report = await runWarden({ driftOnly: true, rootDir: dir });
+      expect(report.diagnostics.length).toBe(0);
+      expect(report.drift).not.toBeNull();
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('formatWardenReport produces human-readable output', async () => {
+    const report = await runWarden({ rootDir: '/dev/null' });
+    const output = formatWardenReport(report);
+    expect(output).toContain('Warden Report');
+    expect(typeof output).toBe('string');
+  });
+});