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

package/src/__tests__/survey.test.ts

@@ -8,21 +8,23 @@ import {
 } from 'node:fs';
 import { join, resolve } from 'node:path';
 
-import { Result, provision, topo, trail } from '@ontrails/core';
+import { ConflictError, Result, resource, topo, trail } from '@ontrails/core';
 import {
-  generateTrailheadMap,
-  hashTrailheadMap,
-  diffTrailheadMaps,
+  deriveSurfaceMap,
+  deriveSurfaceMapHash,
+  deriveSurfaceMapDiff,
+  writeSurfaceMap,
 } from '@ontrails/schema';
-import type { TrailheadMap } from '@ontrails/schema';
+import type { SurfaceMap } from '@ontrails/schema';
 import { z } from 'zod';
 
 import {
-  generateBriefReport,
-  generateSurveyList,
-  generateTrailDetail,
+  deriveBriefReport,
+  deriveSurveyList,
+  deriveTrailDetail,
   surveyTrail,
 } from '../trails/survey.js';
+import { loadApp } from '../trails/load-app.js';
 import type {
   BriefReport,
   SurveyListReport,
@@ -39,9 +41,13 @@ const helloTrail = trail('hello', {
     return Result.ok({ message: `Hello, ${name}!` });
   },
   description: 'Say hello',
-  detours: {
-    NotFoundError: ['search'],
-  },
+  detours: [
+    {
+      on: ConflictError,
+      /* oxlint-disable-next-line require-await -- test stub */
+      recover: async () => Result.ok({ message: 'recovered' }),
+    },
+  ],
   examples: [
     {
       expected: { message: 'Hello, world!' },
@@ -52,8 +58,8 @@ const helloTrail = trail('hello', {
   input: z.object({ name: z.string().optional() }),
   intent: 'read',
   output: z.object({ message: z.string() }),
-  provisions: [
-    provision('db.main', {
+  resources: [
+    resource('db.main', {
       create: () => Result.ok({ source: 'factory' }),
     }),
   ],
@@ -66,14 +72,14 @@ const byeTrail = trail('bye', {
   output: z.object({ message: z.string() }),
 });
 
-const [dbProvision] = helloTrail.provisions;
-if (!dbProvision) {
+const [dbResource] = helloTrail.resources;
+if (!dbResource) {
   throw new Error('Expected helloTrail to declare db.main');
 }
 
 const app = topo('test-app', {
   bye: byeTrail,
-  dbProvision,
+  dbResource,
   hello: helloTrail,
 });
 
@@ -84,11 +90,27 @@ const expectOk = <T>(result: Result<T, Error>): T => {
   return result.value;
 };
 
-const writeSurveyAppFixture = (dir: string): void => {
+const writeSurveyAppFixture = (
+  dir: string,
+  options?: { withBye?: boolean }
+) => {
   mkdirSync(join(dir, 'src'), { recursive: true });
+  const byeSource = options?.withBye
+    ? `
+const bye = trail('bye', {
+  blaze: async (input) => Result.ok({ message: \`Bye, \${input.name ?? 'world'}!\` }),
+  input: z.object({ name: z.string().optional() }),
+  intent: 'read',
+  output: z.object({ message: z.string() }),
+});
+`
+    : '';
+  const topoMembers = options?.withBye
+    ? '{ bye, dbMain, hello }'
+    : '{ dbMain, hello }';
   writeFileSync(
     join(dir, 'src', 'app.ts'),
-    `import { Result, provision, topo, trail } from '@ontrails/core';
+    `import { Result, resource, topo, trail } from '@ontrails/core';
 import { z } from 'zod';
 
 const hello = trail('hello', {
@@ -96,19 +118,21 @@ const hello = trail('hello', {
   input: z.object({ name: z.string().optional() }),
   intent: 'read',
   output: z.object({ message: z.string() }),
-  provisions: [
-    provision('db.main', {
+  resources: [
+    resource('db.main', {
       create: () => Result.ok({ source: 'factory' }),
     }),
   ],
 });
 
-const [dbMain] = hello.provisions;
+const [dbMain] = hello.resources;
 if (!dbMain) {
   throw new Error('expected hello to declare db.main');
 }
 
-export const app = topo('survey-fixture', { dbMain, hello });
+${byeSource}
+
+export const app = topo('survey-fixture', ${topoMembers});
 `
   );
 };
@@ -125,47 +149,47 @@ const repoTempDir = (): string =>
 // ---------------------------------------------------------------------------
 
 describe('trails survey', () => {
-  test('generateTrailheadMap includes all trails', () => {
-    const trailheadMap = generateTrailheadMap(app);
-    expect(trailheadMap.entries.length).toBe(3);
-    const ids = trailheadMap.entries.map((e) => e.id);
+  test('deriveSurfaceMap includes all trails', () => {
+    const surfaceMap = deriveSurfaceMap(app);
+    expect(surfaceMap.entries.length).toBe(3);
+    const ids = surfaceMap.entries.map((e) => e.id);
     expect(ids).toContain('hello');
     expect(ids).toContain('bye');
     expect(ids).toContain('db.main');
   });
 
-  test('trailhead map entries have expected fields', () => {
-    const trailheadMap = generateTrailheadMap(app);
-    const hello = trailheadMap.entries.find((e) => e.id === 'hello');
+  test('surface map entries have expected fields', () => {
+    const surfaceMap = deriveSurfaceMap(app);
+    const hello = surfaceMap.entries.find((e) => e.id === 'hello');
     expect(hello).toBeDefined();
     expect(hello?.cli?.path).toEqual(['hello']);
     expect(hello?.kind).toBe('trail');
     expect(hello?.intent).toBe('read');
     expect(hello?.exampleCount).toBe(1);
-    expect(hello?.provisions).toEqual(['db.main']);
+    expect(hello?.resources).toEqual(['db.main']);
   });
 
   test('JSON output is valid JSON', () => {
-    const trailheadMap = generateTrailheadMap(app);
-    const json = JSON.stringify(trailheadMap, null, 2);
-    const parsed = JSON.parse(json) as TrailheadMap;
+    const surfaceMap = deriveSurfaceMap(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(3);
   });
 
-  test('hashTrailheadMap produces stable hash', () => {
-    const trailheadMap = generateTrailheadMap(app);
-    const hash1 = hashTrailheadMap(trailheadMap);
-    const hash2 = hashTrailheadMap(trailheadMap);
+  test('deriveSurfaceMapHash produces stable hash', () => {
+    const surfaceMap = deriveSurfaceMap(app);
+    const hash1 = deriveSurfaceMapHash(surfaceMap);
+    const hash2 = deriveSurfaceMapHash(surfaceMap);
     expect(hash1).toBe(hash2);
     // SHA-256 hex
     expect(hash1.length).toBe(64);
   });
 
-  test('diffTrailheadMaps detects added trails', () => {
-    const prev = generateTrailheadMap(topo('test', { hello: helloTrail }));
-    const curr = generateTrailheadMap(app);
-    const diff = diffTrailheadMaps(prev, curr);
+  test('deriveSurfaceMapDiff detects added trails', () => {
+    const prev = deriveSurfaceMap(topo('test', { hello: helloTrail }));
+    const curr = deriveSurfaceMap(app);
+    const diff = deriveSurfaceMapDiff(prev, curr);
 
     expect(diff.info.length).toBeGreaterThan(0);
     const addedBye = diff.info.find((e) => e.id === 'bye');
@@ -173,10 +197,10 @@ describe('trails survey', () => {
     expect(addedBye?.change).toBe('added');
   });
 
-  test('diffTrailheadMaps detects removed trails', () => {
-    const prev = generateTrailheadMap(app);
-    const curr = generateTrailheadMap(topo('test', { hello: helloTrail }));
-    const diff = diffTrailheadMaps(prev, curr);
+  test('deriveSurfaceMapDiff detects removed trails', () => {
+    const prev = deriveSurfaceMap(app);
+    const curr = deriveSurfaceMap(topo('test', { hello: helloTrail }));
+    const diff = deriveSurfaceMapDiff(prev, curr);
 
     expect(diff.hasBreaking).toBe(true);
     const removedBye = diff.breaking.find((e) => e.id === 'bye');
@@ -184,9 +208,9 @@ describe('trails survey', () => {
     expect(removedBye?.change).toBe('removed');
   });
 
-  test('diffTrailheadMaps returns empty for identical maps', () => {
-    const trailheadMap = generateTrailheadMap(app);
-    const diff = diffTrailheadMaps(trailheadMap, trailheadMap);
+  test('deriveSurfaceMapDiff returns empty for identical maps', () => {
+    const surfaceMap = deriveSurfaceMap(app);
+    const diff = deriveSurfaceMapDiff(surfaceMap, surfaceMap);
     expect(diff.entries.length).toBe(0);
     expect(diff.hasBreaking).toBe(false);
   });
@@ -198,70 +222,70 @@ describe('trails survey', () => {
 
 describe('trails survey --brief', () => {
   test('produces a valid capability report', () => {
-    const report = generateBriefReport(app);
+    const report = deriveBriefReport(app);
     expect(report.name).toBe('test-app');
     expect(report.contractVersion).toBe('2026-03');
   });
 
   test('report includes correct trail count', () => {
-    const report = generateBriefReport(app);
+    const report = deriveBriefReport(app);
     expect(report.trails).toBe(2);
     expect(report.signals).toBe(0);
-    expect(report.provisions).toBe(1);
+    expect(report.resources).toBe(1);
   });
 
   test('detects features in use', () => {
-    const report = generateBriefReport(app);
+    const report = deriveBriefReport(app);
     expect(report.features.outputSchemas).toBe(true);
     expect(report.features.examples).toBe(true);
     expect(report.features.detours).toBe(true);
     expect(report.features.signals).toBe(false);
-    expect(report.features.provisions).toBe(true);
+    expect(report.features.resources).toBe(true);
   });
 
   test('JSON output is valid', () => {
-    const report = generateBriefReport(app);
+    const report = deriveBriefReport(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);
-    expect(parsed.provisions).toBe(1);
+    expect(parsed.resources).toBe(1);
   });
 
   test('empty app reports zero features', () => {
     const emptyApp = topo('empty', {});
-    const report = generateBriefReport(emptyApp);
+    const report = deriveBriefReport(emptyApp);
     expect(report.trails).toBe(0);
     expect(report.features.outputSchemas).toBe(false);
     expect(report.features.examples).toBe(false);
     expect(report.features.detours).toBe(false);
-    expect(report.features.provisions).toBe(false);
+    expect(report.features.resources).toBe(false);
   });
 });
 
 describe('trails survey detail', () => {
-  test('trail detail includes declared provisions, crossings, and intent', () => {
-    const detail = generateTrailDetail(helloTrail);
+  test('trail detail includes declared resources, crossings, and intent', () => {
+    const detail = deriveTrailDetail(helloTrail);
     const parsed = structuredClone(detail) as TrailDetailReport;
 
     expect(parsed.crosses).toEqual([]);
     expect(parsed.intent).toBe('read');
-    expect(parsed.provisions).toEqual(['db.main']);
+    expect(parsed.resources).toEqual(['db.main']);
   });
 });
 
-describe('trails survey provisions section', () => {
-  test('list output includes provision lifetime and health status', () => {
-    const report = generateSurveyList(app);
+describe('trails survey resources section', () => {
+  test('list output includes resource lifetime and health status', () => {
+    const report = deriveSurveyList(app);
     const parsed = structuredClone(report) as SurveyListReport;
-    const db = parsed.provisions.find((entry) => entry.id === 'db.main');
+    const db = parsed.resources.find((entry) => entry.id === 'db.main');
 
-    expect(parsed.provisionCount).toBe(1);
+    expect(parsed.resourceCount).toBe(1);
     expect(db).toEqual({
       description: null,
       health: 'none',
       id: 'db.main',
-      kind: 'provision',
+      kind: 'resource',
       lifetime: 'singleton',
       usedBy: ['hello'],
     });
@@ -286,7 +310,7 @@ describe('trails survey generate', () => {
       };
 
       expect(generated.hash).toHaveLength(64);
-      expect(existsSync(join(dir, '.trails', '_trailhead.json'))).toBe(true);
+      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'))
@@ -299,3 +323,55 @@ describe('trails survey generate', () => {
     }
   });
 });
+
+describe('trails survey diffSaved', () => {
+  test('returns an error when no saved surface map exists yet', async () => {
+    const dir = repoTempDir();
+
+    try {
+      writeSurveyAppFixture(dir);
+
+      const result = await surveyTrail.blaze(
+        { diffSaved: true, module: './src/app.ts' },
+        { cwd: dir } as never
+      );
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error.message).toContain('Run `trails topo export` first');
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('diffs against the saved local surface map', async () => {
+    const dir = repoTempDir();
+
+    try {
+      writeSurveyAppFixture(dir);
+      const baselineApp = await loadApp('./src/app.ts', dir);
+      await writeSurfaceMap(deriveSurfaceMap(baselineApp), {
+        dir: join(dir, '.trails'),
+      });
+
+      writeSurveyAppFixture(dir, { withBye: true });
+
+      const result = await surveyTrail.blaze(
+        { diffSaved: true, module: './src/app.ts' },
+        { cwd: dir } as never
+      );
+
+      expect(result.isOk()).toBe(true);
+      expect(result.value).toMatchObject({
+        hasBreaking: false,
+        info: [
+          expect.objectContaining({
+            change: 'added',
+            id: 'bye',
+          }),
+        ],
+      });
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+});

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

@@ -12,7 +12,7 @@ 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 { createDevStore } from '@ontrails/tracing';
 
 import { devCleanTrail } from '../trails/dev-clean.js';
 import { devResetTrail } from '../trails/dev-reset.js';
@@ -54,7 +54,7 @@ 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 { Result, resource, topo, trail } from '@ontrails/core';
 import { z } from 'zod';
 
 const hello = trail('hello', {
@@ -64,8 +64,8 @@ const hello = trail('hello', {
   input: z.object({ name: z.string().optional() }),
   intent: 'read',
   output: z.object({ message: z.string() }),
-  provisions: [
-    provision('db.main', {
+  resources: [
+    resource('db.main', {
       create: () => Result.ok({ source: 'factory' }),
     }),
   ],
@@ -78,7 +78,7 @@ const goodbye = trail('goodbye', {
   output: z.object({ ok: z.boolean() }),
 });
 
-const [dbMain] = hello.provisions;
+const [dbMain] = hello.resources;
 if (!dbMain) {
   throw new Error('expected hello to declare db.main');
 }
@@ -100,7 +100,7 @@ describe('topo and dev trails', () => {
       );
       expect(summary.app.name).toBe('fixture-app');
       expect(summary.list.count).toBe(2);
-      expect(summary.list.provisionCount).toBe(1);
+      expect(summary.list.resourceCount).toBe(1);
       expect(summary.lockExists).toBe(false);
 
       const detail = expectOk(
@@ -109,13 +109,13 @@ describe('topo and dev trails', () => {
         } as never)
       );
       expect(detail.id).toBe('hello');
-      expect(detail.provisions).toEqual(['db.main']);
+      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', '_trailhead.json'))).toBe(true);
+      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'))
@@ -124,23 +124,17 @@ describe('topo and dev trails', () => {
         version: 1,
       });
 
-      writeFileSync(
-        join(dir, '.trails', 'trailhead.lock'),
-        readFileSync(join(dir, '.trails', 'trails.lock'), 'utf8')
-      );
-      rmSync(join(dir, '.trails', 'trails.lock'));
-
-      const legacySummary = expectOk(
+      const summaryAfterExport = expectOk(
         await topoTrail.blaze(moduleInput, { cwd: dir } as never)
       );
-      expect(legacySummary.lockExists).toBe(true);
+      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', 'trailhead.lock'), 'stale\n');
+      writeFileSync(join(dir, '.trails', 'trails.lock'), 'stale\n');
       const verifyError = expectErr(
         await topoVerifyTrail.blaze(moduleInput, { cwd: dir } as never)
       );
@@ -163,7 +157,7 @@ describe('topo and dev trails', () => {
       );
       expect(surveyList).toMatchObject({
         count: 2,
-        provisionCount: 1,
+        resourceCount: 1,
       });
 
       const surveyBrief = expectOk(
@@ -175,7 +169,7 @@ describe('topo and dev trails', () => {
         features: {
           examples: true,
           outputSchemas: true,
-          provisions: true,
+          resources: true,
         },
         name: 'fixture-app',
         trails: 2,
@@ -188,7 +182,7 @@ describe('topo and dev trails', () => {
       );
       expect(surveyDetail).toMatchObject({
         id: 'hello',
-        provisions: ['db.main'],
+        resources: ['db.main'],
       });
 
       const guideList = expectOk(
@@ -243,8 +237,7 @@ describe('topo and dev trails', () => {
           cwd: dir,
         } as never)
       );
-      expect(firstPin.pin.name).toBe('before-auth');
-      expect(firstPin.pin.saveId).toBe(firstPin.save.id);
+      expect(firstPin.snapshot.pinnedAs).toBe('before-auth');
 
       const firstExport = expectOk(
         await topoExportTrail.blaze(moduleInput, { cwd: dir } as never)
@@ -264,17 +257,17 @@ describe('topo and dev trails', () => {
       try {
         const pinnedRows = projectionDb
           .query<{ count: number }, [string]>(
-            'SELECT COUNT(*) as count FROM topo_trails WHERE save_id = ?'
+            'SELECT COUNT(*) as count FROM topo_trails WHERE snapshot_id = ?'
           )
-          .get(firstPin.save.id);
+          .get(firstPin.snapshot.id);
         const exportedRows = projectionDb
           .query<{ count: number }, [string]>(
-            'SELECT COUNT(*) as count FROM topo_trails WHERE save_id = ?'
+            'SELECT COUNT(*) as count FROM topo_trails WHERE snapshot_id = ?'
           )
-          .get(firstExport.save.id);
+          .get(firstExport.snapshot.id);
         const projectedSaves = projectionDb
           .query<{ count: number }, []>(
-            'SELECT COUNT(DISTINCT save_id) as count FROM topo_trails'
+            'SELECT COUNT(DISTINCT snapshot_id) as count FROM topo_trails'
           )
           .get();
         const cachedSchemas = projectionDb
@@ -326,36 +319,45 @@ describe('topo and dev trails', () => {
       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.pinnedCount).toBe(1);
+      expect(history.snapshotCount).toBeGreaterThanOrEqual(3);
+      expect(
+        history.snapshots.some(
+          (snapshot) => snapshot.id === firstPin.snapshot.id
+        )
+      ).toBe(true);
       expect(
-        history.saves.some((save) => save.id === secondExport.save.id)
+        history.snapshots.some(
+          (snapshot) => snapshot.id === secondExport.snapshot.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);
+      expect(stats.topo.pinnedCount).toBe(1);
+      expect(stats.tracing.recordCount).toBe(2);
 
       const cleanPreview = expectOk(
-        await devCleanTrail.blaze({ dryRun: true, saves: 0, trackAgeMs: 0 }, {
-          cwd: dir,
-        } as never)
+        await devCleanTrail.blaze(
+          { dryRun: true, snapshots: 0, traceAgeMs: 0 },
+          {
+            cwd: dir,
+          } as never
+        )
       );
       expect(cleanPreview.dryRun).toBe(true);
-      expect(cleanPreview.removed.topoSaves).toBeGreaterThanOrEqual(2);
-      expect(cleanPreview.removed.trackRecords).toBe(2);
+      expect(cleanPreview.removed.topoSnapshots).toBeGreaterThanOrEqual(2);
+      expect(cleanPreview.removed.traceRecords).toBe(2);
 
       const cleanResult = expectOk(
         await devCleanTrail.blaze(
-          { dryRun: false, saves: 0, trackAgeMs: 0, yes: true },
+          { dryRun: false, snapshots: 0, traceAgeMs: 0, yes: true },
           { cwd: dir } as never
         )
       );
-      expect(cleanResult.removed.trackRecords).toBe(2);
-      expect(cleanResult.remaining.pinCount).toBe(1);
+      expect(cleanResult.removed.traceRecords).toBe(2);
+      expect(cleanResult.remaining.pinnedCount).toBe(1);
 
       const unpinPreview = expectOk(
         await topoUnpinTrail.blaze({ dryRun: true, name: 'before-auth' }, {
@@ -363,7 +365,7 @@ describe('topo and dev trails', () => {
         } as never)
       );
       expect(unpinPreview.dryRun).toBe(true);
-      expect(unpinPreview.pin?.name).toBe('before-auth');
+      expect(unpinPreview.snapshot?.pinnedAs).toBe('before-auth');
 
       const unpinResult = expectOk(
         await topoUnpinTrail.blaze(
@@ -404,8 +406,8 @@ describe('topo and dev trails', () => {
         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(preview.removed.topoSnapshots).toBe(0);
+      expect(preview.removed.traceRecords).toBe(0);
       expect(existsSync(join(dir, '.trails', 'trails.db'))).toBe(false);
 
       const applied = expectOk(
@@ -414,8 +416,8 @@ describe('topo and dev trails', () => {
         } as never)
       );
       expect(applied.dryRun).toBe(false);
-      expect(applied.removed.topoSaves).toBe(0);
-      expect(applied.removed.trackRecords).toBe(0);
+      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,6 +1,6 @@
 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';
@@ -38,7 +38,7 @@ export const app = topo(
   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,
 });