@ontrails/trails 1.0.0-beta.15 → 1.0.0-beta.17

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

@@ -1,426 +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/tracing';
-
-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, resource, 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() }),
-  resources: [
-    resource('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.resources;
-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.resourceCount).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.resources).toEqual(['db.main']);
-
-      const exportResult = expectOk(
-        await topoExportTrail.blaze(moduleInput, { cwd: dir } as never)
-      );
-      expect(exportResult.hash).toHaveLength(64);
-      expect(existsSync(join(dir, '.trails', '_surface.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,
-      });
-
-      const summaryAfterExport = expectOk(
-        await topoTrail.blaze(moduleInput, { cwd: dir } as never)
-      );
-      expect(summaryAfterExport.lockExists).toBe(true);
-
-      const verifyResult = expectOk(
-        await topoVerifyTrail.blaze(moduleInput, { cwd: dir } as never)
-      );
-      expect(verifyResult.stale).toBe(false);
-
-      writeFileSync(join(dir, '.trails', 'trails.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,
-        resourceCount: 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,
-          resources: 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',
-        resources: ['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.snapshot.pinnedAs).toBe('before-auth');
-
-      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 snapshot_id = ?'
-          )
-          .get(firstPin.snapshot.id);
-        const exportedRows = projectionDb
-          .query<{ count: number }, [string]>(
-            'SELECT COUNT(*) as count FROM topo_trails WHERE snapshot_id = ?'
-          )
-          .get(firstExport.snapshot.id);
-        const projectedSaves = projectionDb
-          .query<{ count: number }, []>(
-            'SELECT COUNT(DISTINCT snapshot_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.pinnedCount).toBe(1);
-      expect(history.snapshotCount).toBeGreaterThanOrEqual(3);
-      expect(
-        history.snapshots.some(
-          (snapshot) => snapshot.id === firstPin.snapshot.id
-        )
-      ).toBe(true);
-      expect(
-        history.snapshots.some(
-          (snapshot) => snapshot.id === secondExport.snapshot.id
-        )
-      ).toBe(true);
-
-      const stats = expectOk(
-        await devStatsTrail.blaze({}, { cwd: dir } as never)
-      );
-      expect(stats.topo.pinnedCount).toBe(1);
-      expect(stats.tracing.recordCount).toBe(2);
-
-      const cleanPreview = expectOk(
-        await devCleanTrail.blaze(
-          { dryRun: true, snapshots: 0, traceAgeMs: 0 },
-          {
-            cwd: dir,
-          } as never
-        )
-      );
-      expect(cleanPreview.dryRun).toBe(true);
-      expect(cleanPreview.removed.topoSnapshots).toBeGreaterThanOrEqual(2);
-      expect(cleanPreview.removed.traceRecords).toBe(2);
-
-      const cleanResult = expectOk(
-        await devCleanTrail.blaze(
-          { dryRun: false, snapshots: 0, traceAgeMs: 0, yes: true },
-          { cwd: dir } as never
-        )
-      );
-      expect(cleanResult.removed.traceRecords).toBe(2);
-      expect(cleanResult.remaining.pinnedCount).toBe(1);
-
-      const unpinPreview = expectOk(
-        await topoUnpinTrail.blaze({ dryRun: true, name: 'before-auth' }, {
-          cwd: dir,
-        } as never)
-      );
-      expect(unpinPreview.dryRun).toBe(true);
-      expect(unpinPreview.snapshot?.pinnedAs).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.topoSnapshots).toBe(0);
-      expect(preview.removed.traceRecords).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.topoSnapshots).toBe(0);
-      expect(applied.removed.traceRecords).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/topo-export.ts

@@ -1,35 +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 {
-  createIsolatedExampleInput,
-  topoSnapshotOutput,
-} 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: createIsolatedExampleInput('topo-export'),
-      name: 'Write the current topo export',
-    },
-  ],
-  input: z.object({
-    module: z.string().optional().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(),
-    snapshot: topoSnapshotOutput,
-  }),
-});

package/src/trails/topo-show.ts

@@ -1,54 +0,0 @@
-import { NotFoundError, Result, trail } from '@ontrails/core';
-import { z } from 'zod';
-
-import { loadApp } from './load-app.js';
-import { buildCurrentTopoDetail } from './topo-read-support.js';
-
-const trailDetailOutput = z.object({
-  crosses: z.array(z.string()),
-  description: z.unknown().nullable(),
-  detours: z.unknown().nullable(),
-  examples: z.array(z.unknown()),
-  id: z.string(),
-  intent: z.enum(['read', 'write', 'destroy']),
-  kind: z.string(),
-  resources: z.array(z.string()),
-  safety: z.string(),
-});
-
-const resourceDetailOutput = z.object({
-  description: z.string().nullable(),
-  health: z.enum(['available', 'none']),
-  id: z.string(),
-  kind: z.literal('resource'),
-  lifetime: z.literal('singleton'),
-  usedBy: z.array(z.string()),
-});
-
-export const topoShowTrail = trail('topo.show', {
-  blaze: async (input, ctx) => {
-    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
-    const app = await loadApp(input.module, rootDir);
-    const detail = buildCurrentTopoDetail(app, input.id, { rootDir });
-    if (detail !== undefined) {
-      return Result.ok(detail);
-    }
-    return Result.err(
-      new NotFoundError(`Trail or resource not found: ${input.id}`)
-    );
-  },
-  description: 'Show detail for a current trail or resource',
-  examples: [
-    {
-      input: { id: 'topo' },
-      name: 'Show current trail detail',
-    },
-  ],
-  input: z.object({
-    id: z.string().describe('Trail or resource ID to inspect'),
-    module: z.string().optional().describe('Path to the app module'),
-    rootDir: z.string().optional().describe('Workspace root directory'),
-  }),
-  intent: 'read',
-  output: z.union([trailDetailOutput, resourceDetailOutput]),
-});

package/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "dist",
-    "rootDir": "."
-  },
-  "include": ["src", "bin"],
-  "exclude": ["**/__tests__/**", "**/*.test.ts", "dist"]
-}

package/tsconfig.tests.json

@@ -1,10 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "noEmit": true,
-    "rootDir": ".",
-    "types": ["bun"]
-  },
-  "include": ["src/**/*.test.ts", "src/__tests__/**/*.ts", "__tests__/**/*.ts"],
-  "exclude": []
-}