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

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

@@ -0,0 +1,426 @@
+/* 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/app.ts

@@ -1,22 +1,44 @@
 import { topo } from '@ontrails/core';
 
-import * as addTrailhead from './trails/add-trailhead.js';
+import * as addSurface from './trails/add-surface.js';
 import * as addTrail from './trails/add-trail.js';
 import * as addVerify from './trails/add-verify.js';
 import * as create from './trails/create.js';
 import * as createScaffold from './trails/create-scaffold.js';
+import * as devClean from './trails/dev-clean.js';
+import * as devReset from './trails/dev-reset.js';
+import * as devStats from './trails/dev-stats.js';
+import * as draftPromote from './trails/draft-promote.js';
 import * as guide from './trails/guide.js';
 import * as survey from './trails/survey.js';
+import * as topoExport from './trails/topo-export.js';
+import * as topoHistory from './trails/topo-history.js';
+import * as topoPin from './trails/topo-pin.js';
+import * as topoShow from './trails/topo-show.js';
+import * as topoCommand from './trails/topo.js';
+import * as topoUnpin from './trails/topo-unpin.js';
+import * as topoVerify from './trails/topo-verify.js';
 import * as warden from './trails/warden.js';
 
 export const app = topo(
   'trails',
   survey,
+  topoCommand,
+  topoShow,
+  topoHistory,
+  topoPin,
+  topoUnpin,
+  topoExport,
+  topoVerify,
+  devStats,
+  devClean,
+  devReset,
   guide,
+  draftPromote,
   warden,
   create,
   createScaffold,
-  addTrailhead,
+  addSurface,
   addVerify,
   addTrail
 );

package/src/clack.ts

@@ -1,7 +1,7 @@
 /**
  * Clack-backed input resolver for the Trails CLI.
  *
- * This stays at the app gate so @ontrails/cli remains prompt-library agnostic.
+ * This stays at the app layer so @ontrails/cli remains prompt-library agnostic.
  */
 
 import type { Field, InputResolver, ResolveInputOptions } from '@ontrails/cli';

package/src/cli.ts

@@ -1,14 +1,15 @@
 import { outputModePreset } from '@ontrails/cli';
-import { trailhead } from '@ontrails/cli/commander';
+import { surface } from '@ontrails/cli/commander';
 
 import { app } from './app.js';
 import { resolveInputWithClack } from './clack.js';
+import { trailsPackageVersion } from './versions.js';
 
 // oxlint-disable-next-line require-hook -- CLI entry point
-trailhead(app, {
+await surface(app, {
   description: 'Agent-native, contract-first TypeScript framework',
   name: 'trails',
   presets: [outputModePreset()],
   resolveInput: resolveInputWithClack,
-  version: '0.1.0',
+  version: trailsPackageVersion,
 });

package/src/trails/add-surface.ts

@@ -0,0 +1,150 @@
+/**
+ * `add.surface` trail -- Add a surface to an existing project.
+ *
+ * Generates surface entry points 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 {
+  ontrailsPackageRange,
+  scaffoldDependencyVersions,
+} from '../versions.js';
+import { findTopoPath } from './project.js';
+
+type Surface = 'cli' | 'http' | 'mcp';
+
+const generateCliEntry = (appImportPath: string): string =>
+  `import { surface } from '@ontrails/cli/commander';
+
+import { app } from '${appImportPath}';
+
+await surface(app);
+`;
+
+const generateMcpEntry = (appImportPath: string): string =>
+  `import { surface } from '@ontrails/mcp';
+
+import { app } from '${appImportPath}';
+
+await surface(app);
+`;
+
+const generateHttpEntry = (appImportPath: string): string =>
+  `import { surface } from '@ontrails/hono';
+
+import { app } from '${appImportPath}';
+
+await surface(app, { port: 3000 });
+`;
+
+const surfaceEntryFiles = {
+  cli: 'src/cli.ts',
+  http: 'src/http.ts',
+  mcp: 'src/mcp.ts',
+} satisfies Record<Surface, string>;
+
+const surfaceDependencies = {
+  cli: ['@ontrails/cli'],
+  http: ['@ontrails/hono', '@ontrails/http'],
+  mcp: ['@ontrails/mcp'],
+} satisfies Record<Surface, readonly string[]>;
+
+/** Resolve the entry file for a surface. */
+const getEntryFile = (surface: Surface): string => surfaceEntryFiles[surface];
+
+// ---------------------------------------------------------------------------
+// Trail definition
+// ---------------------------------------------------------------------------
+
+/** Patch deps and optionally bin in a parsed package.json. */
+const patchPkgDeps = (
+  pkg: Record<string, unknown>,
+  surface: Surface,
+  cwd: string
+): string => {
+  const [depName = ''] = surfaceDependencies[surface];
+  const deps = (pkg['dependencies'] ?? {}) as Record<string, string>;
+  for (const dependency of surfaceDependencies[surface]) {
+    deps[dependency] = ontrailsPackageRange;
+  }
+  if (surface === 'cli') {
+    deps['commander'] = scaffoldDependencyVersions.commander;
+    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 surface dependency and CLI bin if needed. */
+const updatePkgJsonForSurface = async (
+  cwd: string,
+  surface: Surface
+): Promise<string> => {
+  const pkgPath = join(cwd, 'package.json');
+  if (!existsSync(pkgPath)) {
+    return surfaceDependencies[surface][0] ?? '';
+  }
+  const pkg = (await Bun.file(pkgPath).json()) as Record<string, unknown>;
+  const depName = patchPkgDeps(pkg, surface, cwd);
+  await Bun.write(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+  return depName;
+};
+
+/** Create the entry file for a surface and return the relative path. */
+const writeSurfaceEntry = async (
+  cwd: string,
+  surface: Surface
+): Promise<string> => {
+  const entryFile = getEntryFile(surface);
+  const fullEntryPath = join(cwd, entryFile);
+  const appImport = (await findTopoPath(cwd)) ?? './app.js';
+  const generators = {
+    cli: generateCliEntry,
+    http: generateHttpEntry,
+    mcp: generateMcpEntry,
+  } satisfies Record<Surface, (appImportPath: string) => string>;
+  const content = generators[surface](appImport);
+
+  mkdirSync(dirname(fullEntryPath), { recursive: true });
+  await Bun.write(fullEntryPath, content);
+  return entryFile;
+};
+
+export const addSurface = trail('add.surface', {
+  blaze: async (input) => {
+    const cwd = resolve(input.dir ?? '.');
+    const { surface } = input;
+    const entryFile = getEntryFile(surface);
+
+    if (existsSync(join(cwd, entryFile))) {
+      return Result.err(
+        new Error(
+          `${surface.toUpperCase()} surface already exists. Nothing to do.`
+        )
+      );
+    }
+
+    return Result.ok({
+      created: await writeSurfaceEntry(cwd, surface),
+      dependency: await updatePkgJsonForSurface(cwd, surface),
+    });
+  },
+  description: 'Add a surface to an existing project',
+  input: z.object({
+    dir: z.string().optional().describe('Project directory'),
+    surface: z.enum(['cli', 'http', 'mcp']).describe('Surface to add'),
+  }),
+  output: z.object({
+    created: z.string(),
+    dependency: z.string(),
+  }),
+});