@ontrails/trails 1.0.0-beta.14 → 1.0.0-beta.16

package/src/__tests__/topo-dev.test.ts

@@ -1,424 +0,0 @@
-/* oxlint-disable max-statements */
-
-import { describe, expect, test } from 'bun:test';
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  rmSync,
-  writeFileSync,
-} from 'node:fs';
-import { join, resolve } from 'node:path';
-
-import type { Result } from '@ontrails/core';
-import { openReadTrailsDb } from '@ontrails/core/internal/trails-db';
-import { createDevStore } from '@ontrails/tracker';
-
-import { devCleanTrail } from '../trails/dev-clean.js';
-import { devResetTrail } from '../trails/dev-reset.js';
-import { devStatsTrail } from '../trails/dev-stats.js';
-import { guideTrail } from '../trails/guide.js';
-import { surveyTrail } from '../trails/survey.js';
-import { topoExportTrail } from '../trails/topo-export.js';
-import { topoHistoryTrail } from '../trails/topo-history.js';
-import { topoPinTrail } from '../trails/topo-pin.js';
-import { topoShowTrail } from '../trails/topo-show.js';
-import { topoTrail } from '../trails/topo.js';
-import { topoUnpinTrail } from '../trails/topo-unpin.js';
-import { topoVerifyTrail } from '../trails/topo-verify.js';
-
-const repoTempDir = (): string =>
-  join(
-    resolve(import.meta.dir, '../..'),
-    '.tmp-tests',
-    `topo-dev-${Date.now()}-${Math.random().toString(36).slice(2)}`
-  );
-
-const expectOk = <T>(result: Result<T, Error>): T => {
-  if (result.isErr()) {
-    throw result.error;
-  }
-  return result.value;
-};
-
-const expectErr = <E extends Error>(result: Result<unknown, E>): E => {
-  if (result.isOk()) {
-    throw new Error('expected result to be an error');
-  }
-  return result.error;
-};
-
-const moduleInput = { module: './src/app.ts' } as const;
-
-const writeAppFixture = (dir: string): void => {
-  mkdirSync(join(dir, 'src'), { recursive: true });
-  writeFileSync(
-    join(dir, 'src', 'app.ts'),
-    `import { Result, provision, topo, trail } from '@ontrails/core';
-import { z } from 'zod';
-
-const hello = trail('hello', {
-  blaze: async (input) => Result.ok({ message: \`Hello, \${input.name ?? 'world'}!\` }),
-  crosses: ['goodbye'],
-  examples: [{ input: {}, name: 'Default greeting' }],
-  input: z.object({ name: z.string().optional() }),
-  intent: 'read',
-  output: z.object({ message: z.string() }),
-  provisions: [
-    provision('db.main', {
-      create: () => Result.ok({ source: 'factory' }),
-    }),
-  ],
-});
-
-const goodbye = trail('goodbye', {
-  blaze: async () => Result.ok({ ok: true }),
-  input: z.object({}),
-  intent: 'write',
-  output: z.object({ ok: z.boolean() }),
-});
-
-const [dbMain] = hello.provisions;
-if (!dbMain) {
-  throw new Error('expected hello to declare db.main');
-}
-
-export const app = topo('fixture-app', { dbMain, goodbye, hello });
-`
-  );
-};
-
-describe('topo and dev trails', () => {
-  test('topo surfaces current summary, detail, and export/verify flow', async () => {
-    const dir = repoTempDir();
-
-    try {
-      writeAppFixture(dir);
-
-      const summary = expectOk(
-        await topoTrail.blaze(moduleInput, { cwd: dir } as never)
-      );
-      expect(summary.app.name).toBe('fixture-app');
-      expect(summary.list.count).toBe(2);
-      expect(summary.list.provisionCount).toBe(1);
-      expect(summary.lockExists).toBe(false);
-
-      const detail = expectOk(
-        await topoShowTrail.blaze({ ...moduleInput, id: 'hello' }, {
-          cwd: dir,
-        } as never)
-      );
-      expect(detail.id).toBe('hello');
-      expect(detail.provisions).toEqual(['db.main']);
-
-      const exportResult = expectOk(
-        await topoExportTrail.blaze(moduleInput, { cwd: dir } as never)
-      );
-      expect(exportResult.hash).toHaveLength(64);
-      expect(existsSync(join(dir, '.trails', '_trailhead.json'))).toBe(true);
-      expect(existsSync(join(dir, '.trails', 'trails.lock'))).toBe(true);
-      expect(
-        JSON.parse(readFileSync(join(dir, '.trails', 'trails.lock'), 'utf8'))
-      ).toMatchObject({
-        hash: exportResult.hash,
-        version: 1,
-      });
-
-      writeFileSync(
-        join(dir, '.trails', 'trailhead.lock'),
-        readFileSync(join(dir, '.trails', 'trails.lock'), 'utf8')
-      );
-      rmSync(join(dir, '.trails', 'trails.lock'));
-
-      const legacySummary = expectOk(
-        await topoTrail.blaze(moduleInput, { cwd: dir } as never)
-      );
-      expect(legacySummary.lockExists).toBe(true);
-
-      const verifyResult = expectOk(
-        await topoVerifyTrail.blaze(moduleInput, { cwd: dir } as never)
-      );
-      expect(verifyResult.stale).toBe(false);
-
-      writeFileSync(join(dir, '.trails', 'trailhead.lock'), 'stale\n');
-      const verifyError = expectErr(
-        await topoVerifyTrail.blaze(moduleInput, { cwd: dir } as never)
-      );
-      expect(verifyError.message).toContain('trails.lock is stale');
-    } finally {
-      rmSync(dir, { force: true, recursive: true });
-    }
-  });
-
-  test('survey and guide read current topo state through the shared topo store', async () => {
-    const dir = repoTempDir();
-
-    try {
-      writeAppFixture(dir);
-
-      const surveyList = expectOk(
-        await surveyTrail.blaze({ module: './src/app.ts' }, {
-          cwd: dir,
-        } as never)
-      );
-      expect(surveyList).toMatchObject({
-        count: 2,
-        provisionCount: 1,
-      });
-
-      const surveyBrief = expectOk(
-        await surveyTrail.blaze({ brief: true, module: './src/app.ts' }, {
-          cwd: dir,
-        } as never)
-      );
-      expect(surveyBrief).toMatchObject({
-        features: {
-          examples: true,
-          outputSchemas: true,
-          provisions: true,
-        },
-        name: 'fixture-app',
-        trails: 2,
-      });
-
-      const surveyDetail = expectOk(
-        await surveyTrail.blaze({ module: './src/app.ts', trailId: 'hello' }, {
-          cwd: dir,
-        } as never)
-      );
-      expect(surveyDetail).toMatchObject({
-        id: 'hello',
-        provisions: ['db.main'],
-      });
-
-      const guideList = expectOk(
-        await guideTrail.blaze({ module: './src/app.ts' }, {
-          cwd: dir,
-        } as never)
-      );
-      expect(guideList).toEqual([
-        {
-          description: '(no description)',
-          exampleCount: 0,
-          id: 'goodbye',
-          kind: 'trail',
-        },
-        {
-          description: '(no description)',
-          exampleCount: 1,
-          id: 'hello',
-          kind: 'trail',
-        },
-      ]);
-
-      const guideDetail = expectOk(
-        await guideTrail.blaze({ module: './src/app.ts', trailId: 'hello' }, {
-          cwd: dir,
-        } as never)
-      );
-      expect(guideDetail).toMatchObject({
-        description: null,
-        examples: [
-          {
-            input: {},
-            name: 'Default greeting',
-          },
-        ],
-        id: 'hello',
-        kind: 'trail',
-      });
-    } finally {
-      rmSync(dir, { force: true, recursive: true });
-    }
-  });
-
-  test('pinning, history, unpinning, and dev maintenance work against shared trails.db', async () => {
-    const dir = repoTempDir();
-
-    try {
-      writeAppFixture(dir);
-
-      const firstPin = expectOk(
-        await topoPinTrail.blaze({ ...moduleInput, name: 'before-auth' }, {
-          cwd: dir,
-        } as never)
-      );
-      expect(firstPin.pin.name).toBe('before-auth');
-      expect(firstPin.pin.saveId).toBe(firstPin.save.id);
-
-      const firstExport = expectOk(
-        await topoExportTrail.blaze(moduleInput, { cwd: dir } as never)
-      );
-      const secondExport = expectOk(
-        await topoExportTrail.blaze(moduleInput, { cwd: dir } as never)
-      );
-      expect(firstExport.hash).toBe(secondExport.hash);
-      expect(
-        JSON.parse(readFileSync(join(dir, '.trails', 'trails.lock'), 'utf8'))
-      ).toMatchObject({
-        hash: secondExport.hash,
-        version: 1,
-      });
-
-      const projectionDb = openReadTrailsDb({ rootDir: dir });
-      try {
-        const pinnedRows = projectionDb
-          .query<{ count: number }, [string]>(
-            'SELECT COUNT(*) as count FROM topo_trails WHERE save_id = ?'
-          )
-          .get(firstPin.save.id);
-        const exportedRows = projectionDb
-          .query<{ count: number }, [string]>(
-            'SELECT COUNT(*) as count FROM topo_trails WHERE save_id = ?'
-          )
-          .get(firstExport.save.id);
-        const projectedSaves = projectionDb
-          .query<{ count: number }, []>(
-            'SELECT COUNT(DISTINCT save_id) as count FROM topo_trails'
-          )
-          .get();
-        const cachedSchemas = projectionDb
-          .query<{ count: number }, []>(
-            'SELECT COUNT(*) as count FROM topo_schemas'
-          )
-          .get();
-
-        expect(pinnedRows?.count).toBe(2);
-        expect(exportedRows?.count).toBe(2);
-        expect(projectedSaves?.count).toBe(3);
-        expect(cachedSchemas?.count).toBeGreaterThanOrEqual(9);
-      } finally {
-        projectionDb.close();
-      }
-
-      const store = createDevStore({ rootDir: dir });
-      try {
-        store.write({
-          attrs: {},
-          endedAt: Date.now() - 1000,
-          id: 'track-1',
-          kind: 'trail',
-          name: 'hello',
-          rootId: 'track-1',
-          startedAt: Date.now() - 10_000,
-          status: 'ok',
-          traceId: 'trace-1',
-          trailId: 'hello',
-          trailhead: 'cli',
-        });
-        store.write({
-          attrs: {},
-          endedAt: Date.now() - 500,
-          id: 'track-2',
-          kind: 'trail',
-          name: 'goodbye',
-          rootId: 'track-2',
-          startedAt: Date.now() - 20_000,
-          status: 'err',
-          traceId: 'trace-2',
-          trailId: 'goodbye',
-          trailhead: 'cli',
-        });
-      } finally {
-        store.close();
-      }
-
-      const history = expectOk(
-        await topoHistoryTrail.blaze({}, { cwd: dir } as never)
-      );
-      expect(history.pinCount).toBe(1);
-      expect(history.saveCount).toBeGreaterThanOrEqual(3);
-      expect(history.pins[0]?.saveId).toBe(firstPin.save.id);
-      expect(
-        history.saves.some((save) => save.id === secondExport.save.id)
-      ).toBe(true);
-
-      const stats = expectOk(
-        await devStatsTrail.blaze({}, { cwd: dir } as never)
-      );
-      expect(stats.topo.pinCount).toBe(1);
-      expect(stats.tracker.recordCount).toBe(2);
-
-      const cleanPreview = expectOk(
-        await devCleanTrail.blaze({ dryRun: true, saves: 0, trackAgeMs: 0 }, {
-          cwd: dir,
-        } as never)
-      );
-      expect(cleanPreview.dryRun).toBe(true);
-      expect(cleanPreview.removed.topoSaves).toBeGreaterThanOrEqual(2);
-      expect(cleanPreview.removed.trackRecords).toBe(2);
-
-      const cleanResult = expectOk(
-        await devCleanTrail.blaze(
-          { dryRun: false, saves: 0, trackAgeMs: 0, yes: true },
-          { cwd: dir } as never
-        )
-      );
-      expect(cleanResult.removed.trackRecords).toBe(2);
-      expect(cleanResult.remaining.pinCount).toBe(1);
-
-      const unpinPreview = expectOk(
-        await topoUnpinTrail.blaze({ dryRun: true, name: 'before-auth' }, {
-          cwd: dir,
-        } as never)
-      );
-      expect(unpinPreview.dryRun).toBe(true);
-      expect(unpinPreview.pin?.name).toBe('before-auth');
-
-      const unpinResult = expectOk(
-        await topoUnpinTrail.blaze(
-          { dryRun: false, name: 'before-auth', yes: true },
-          { cwd: dir } as never
-        )
-      );
-      expect(unpinResult.removed).toBe(true);
-
-      const resetPreview = expectOk(
-        await devResetTrail.blaze({ dryRun: true }, { cwd: dir } as never)
-      );
-      expect(resetPreview.dryRun).toBe(true);
-      expect(resetPreview.removedFiles).toContain('.trails/trails.db');
-
-      const resetResult = expectOk(
-        await devResetTrail.blaze({ dryRun: false, yes: true }, {
-          cwd: dir,
-        } as never)
-      );
-      expect(resetResult.removedFiles).toContain('.trails/trails.db');
-      expect(existsSync(join(dir, '.trails', 'trails.db'))).toBe(false);
-      expect(
-        readFileSync(join(dir, '.trails', 'trails.lock'), 'utf8').length
-      ).toBeGreaterThan(0);
-    } finally {
-      rmSync(dir, { force: true, recursive: true });
-    }
-  });
-
-  test('dev clean stays side-effect free when no local state exists', async () => {
-    const dir = repoTempDir();
-
-    try {
-      mkdirSync(dir, { recursive: true });
-
-      const preview = expectOk(
-        await devCleanTrail.blaze({ dryRun: true }, { cwd: dir } as never)
-      );
-      expect(preview.dryRun).toBe(true);
-      expect(preview.removed.topoSaves).toBe(0);
-      expect(preview.removed.trackRecords).toBe(0);
-      expect(existsSync(join(dir, '.trails', 'trails.db'))).toBe(false);
-
-      const applied = expectOk(
-        await devCleanTrail.blaze({ dryRun: false, yes: true }, {
-          cwd: dir,
-        } as never)
-      );
-      expect(applied.dryRun).toBe(false);
-      expect(applied.removed.topoSaves).toBe(0);
-      expect(applied.removed.trackRecords).toBe(0);
-      expect(existsSync(join(dir, '.trails', 'trails.db'))).toBe(false);
-    } finally {
-      rmSync(dir, { force: true, recursive: true });
-    }
-  });
-});

package/src/__tests__/warden.test.ts

@@ -1,74 +0,0 @@
-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", {
-  blaze: 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", {
-  blaze: 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');
-  });
-});

package/src/trails/add-trailhead.ts

@@ -1,121 +0,0 @@
-/**
- * `add.trailhead` trail -- Add a trailhead to an existing project.
- *
- * Generates the CLI or MCP entry point and updates package.json dependencies.
- */
-
-import { existsSync, mkdirSync } from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
-
-import { Result, trail } from '@ontrails/core';
-import { z } from 'zod';
-
-import { findTopoPath } from './project.js';
-
-const generateCliEntry = (appImportPath: string): string =>
-  `import { trailhead } from '@ontrails/cli/commander';
-
-import { app } from '${appImportPath}';
-
-trailhead(app);
-`;
-
-const generateMcpEntry = (appImportPath: string): string =>
-  `import { trailhead } from '@ontrails/mcp';
-
-import { app } from '${appImportPath}';
-
-await trailhead(app);
-`;
-
-/** Resolve the entry file for a trailhead. */
-const getEntryFile = (trailhead: 'cli' | 'mcp'): string =>
-  trailhead === 'cli' ? 'src/cli.ts' : 'src/mcp.ts';
-
-// ---------------------------------------------------------------------------
-// Trail definition
-// ---------------------------------------------------------------------------
-
-/** Patch deps and optionally bin in a parsed package.json. */
-const patchPkgDeps = (
-  pkg: Record<string, unknown>,
-  trailhead: 'cli' | 'mcp',
-  cwd: string
-): string => {
-  const depName = trailhead === 'cli' ? '@ontrails/cli' : '@ontrails/mcp';
-  const deps = (pkg['dependencies'] ?? {}) as Record<string, string>;
-  deps[depName] = 'workspace:*';
-  if (trailhead === 'cli') {
-    deps['commander'] = '^14.0.0';
-    pkg['bin'] = {
-      [(pkg['name'] as string | undefined) ?? basename(cwd)]: './src/cli.ts',
-    };
-  }
-  pkg['dependencies'] = Object.fromEntries(
-    Object.entries(deps).toSorted(([a], [b]) => a.localeCompare(b))
-  );
-  return depName;
-};
-
-/** Update package.json with trailhead dependency and CLI bin if needed. */
-const updatePkgJsonForTrailhead = async (
-  cwd: string,
-  trailhead: 'cli' | 'mcp'
-): Promise<string> => {
-  const pkgPath = join(cwd, 'package.json');
-  if (!existsSync(pkgPath)) {
-    return trailhead === 'cli' ? '@ontrails/cli' : '@ontrails/mcp';
-  }
-  const pkg = (await Bun.file(pkgPath).json()) as Record<string, unknown>;
-  const depName = patchPkgDeps(pkg, trailhead, cwd);
-  await Bun.write(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
-  return depName;
-};
-
-/** Create the entry file for a trailhead and return the relative path. */
-const writeTrailheadEntry = async (
-  cwd: string,
-  trailhead: 'cli' | 'mcp'
-): Promise<string> => {
-  const entryFile = getEntryFile(trailhead);
-  const fullEntryPath = join(cwd, entryFile);
-  const appImport = (await findTopoPath(cwd)) ?? './app.js';
-  const content =
-    trailhead === 'cli'
-      ? generateCliEntry(appImport)
-      : generateMcpEntry(appImport);
-
-  mkdirSync(dirname(fullEntryPath), { recursive: true });
-  await Bun.write(fullEntryPath, content);
-  return entryFile;
-};
-
-export const addTrailhead = trail('add.trailhead', {
-  blaze: async (input) => {
-    const cwd = resolve(input.dir ?? '.');
-    const { trailhead } = input;
-    const entryFile = getEntryFile(trailhead);
-
-    if (existsSync(join(cwd, entryFile))) {
-      return Result.err(
-        new Error(
-          `${trailhead.toUpperCase()} trailhead already exists. Nothing to do.`
-        )
-      );
-    }
-
-    return Result.ok({
-      created: await writeTrailheadEntry(cwd, trailhead),
-      dependency: await updatePkgJsonForTrailhead(cwd, trailhead),
-    });
-  },
-  description: 'Add a trailhead to an existing project',
-  input: z.object({
-    dir: z.string().optional().describe('Project directory'),
-    trailhead: z.enum(['cli', 'mcp']).describe('Trailhead to add'),
-  }),
-  output: z.object({
-    created: z.string(),
-    dependency: z.string(),
-  }),
-});

package/src/trails/topo-export.ts

@@ -1,39 +0,0 @@
-import { trail } from '@ontrails/core';
-import { z } from 'zod';
-
-import { loadApp } from './load-app.js';
-import { exportCurrentTopo } from './topo-store-support.js';
-import {
-  DEFAULT_APP_MODULE,
-  isolatedExampleInput,
-  topoSaveOutput,
-} from './topo-support.js';
-
-export const topoExportTrail = trail('topo.export', {
-  blaze: async (input, ctx) => {
-    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
-    const app = await loadApp(input.module, rootDir);
-    return exportCurrentTopo(app, { rootDir });
-  },
-  description: 'Export the current topo to .trails artifacts',
-  examples: [
-    {
-      input: isolatedExampleInput('topo-export'),
-      name: 'Write the current topo export',
-    },
-  ],
-  input: z.object({
-    module: z
-      .string()
-      .default(DEFAULT_APP_MODULE)
-      .describe('Path to the app module'),
-    rootDir: z.string().optional().describe('Workspace root directory'),
-  }),
-  intent: 'write',
-  output: z.object({
-    hash: z.string(),
-    lockPath: z.string(),
-    mapPath: z.string(),
-    save: topoSaveOutput,
-  }),
-});