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

package/src/trails/survey.ts

@@ -1,22 +1,24 @@
 /**
  * `survey` trail -- Full topo introspection.
  *
- * Lists trails, shows detail for individual trails, generates trailhead maps,
+ * Lists trails, shows detail for individual trails, generates surface maps,
  * and diffs against previous versions.
  */
 
+import { join } from 'node:path';
+
 import type { Topo } from '@ontrails/core';
 import { NotFoundError, Result, trail } from '@ontrails/core';
 import type { DiffResult } from '@ontrails/schema';
 import {
-  diffTrailheadMaps,
-  generateOpenApiSpec,
-  generateTrailheadMap,
-  readTrailheadMap,
+  deriveSurfaceMapDiff,
+  deriveOpenApiSpec,
+  deriveSurfaceMap,
+  readSurfaceMap,
 } from '@ontrails/schema';
 import { z } from 'zod';
 
-import { loadApp } from './load-app.js';
+import { loadApp, loadFreshAppLease } from './load-app.js';
 import {
   buildCurrentTopoBrief,
   buildCurrentTopoDetail,
@@ -25,10 +27,10 @@ import {
 import { exportCurrentTopo } from './topo-store-support.js';
 
 export {
-  formatProvisionDetail,
-  generateBriefReport,
-  generateSurveyList,
-  generateTrailDetail,
+  deriveBriefReport,
+  deriveResourceDetail,
+  deriveSurveyList,
+  deriveTrailDetail,
 } from './topo-reports.js';
 export type {
   BriefReport,
@@ -49,19 +51,20 @@ const formatDiff = (diff: DiffResult): object => ({
 
 const buildSurveyDiff = async (
   app: Topo,
+  rootDir: string,
   breakingOnly: boolean
 ): Promise<Result<object, Error>> => {
-  const currentMap = generateTrailheadMap(app);
-  const previousMap = await readTrailheadMap();
+  const currentMap = deriveSurfaceMap(app);
+  const previousMap = await readSurfaceMap({ dir: join(rootDir, '.trails') });
   if (!previousMap) {
     return Result.err(
       new NotFoundError(
-        'No previous trailhead map found. Run `trails topo export` first.'
+        'No saved surface map found. Run `trails topo export` first.'
       )
     );
   }
 
-  const diff = diffTrailheadMaps(previousMap, currentMap);
+  const diff = deriveSurfaceMapDiff(previousMap, currentMap);
   return Result.ok(
     breakingOnly
       ? formatDiff({
@@ -84,7 +87,7 @@ const buildSurveyDetail = (
     return Result.ok(detail);
   }
   return Result.err(
-    new NotFoundError(`Trail or provision not found: ${trailId}`)
+    new NotFoundError(`Trail or resource not found: ${trailId}`)
   );
 };
 
@@ -106,7 +109,7 @@ const buildSurveyGenerate = async (
 interface SurveyInput {
   breakingOnly: boolean;
   brief: boolean;
-  diff?: string | undefined;
+  diffSaved: boolean;
   generate: boolean;
   openapi: boolean;
   trailId?: string | undefined;
@@ -117,14 +120,14 @@ type SurveyMode = 'brief' | 'detail' | 'diff' | 'generate' | 'list' | 'openapi';
 /** Ordered mode checks — first truthy predicate wins, otherwise 'list'. */
 const modeChecks: readonly [(input: SurveyInput) => boolean, SurveyMode][] = [
   [(i) => i.brief, 'brief'],
-  [(i) => Boolean(i.diff), 'diff'],
+  [(i) => i.diffSaved, 'diff'],
   [(i) => Boolean(i.trailId), 'detail'],
   [(i) => i.generate, 'generate'],
   [(i) => i.openapi, 'openapi'],
 ];
 
 /** Determine which survey mode was requested, falling back to 'list'. */
-const resolveSurveyMode = (input: SurveyInput): SurveyMode =>
+const deriveSurveyMode = (input: SurveyInput): SurveyMode =>
   modeChecks.find(([predicate]) => predicate(input))?.[1] ?? 'list';
 
 type SurveyHandler = (
@@ -139,11 +142,12 @@ const surveyHandlers: Record<SurveyMode, SurveyHandler> = {
     Result.ok(buildCurrentTopoBrief(app, { rootDir })),
   detail: (app, input, rootDir) =>
     buildSurveyDetail(app, input.trailId ?? '', rootDir),
-  diff: (app, input) => buildSurveyDiff(app, input.breakingOnly),
+  diff: (app, input, rootDir) =>
+    buildSurveyDiff(app, rootDir, input.breakingOnly),
   generate: (app, _input, rootDir) => buildSurveyGenerate(app, rootDir),
   list: (app, _input, rootDir) =>
     Result.ok(buildCurrentTopoList(app, { rootDir })),
-  openapi: (app) => Result.ok(generateOpenApiSpec(app)),
+  openapi: (app) => Result.ok(deriveOpenApiSpec(app)),
 };
 
 /** Dispatch to the appropriate survey sub-command based on input flags. */
@@ -152,7 +156,7 @@ const dispatchSurvey = (
   input: SurveyInput,
   rootDir: string
 ): Result<object, Error> | Promise<Result<object, Error>> => {
-  const mode = resolveSurveyMode(input);
+  const mode = deriveSurveyMode(input);
   const handler = surveyHandlers[mode];
   return handler(app, input, rootDir);
 };
@@ -164,13 +168,34 @@ const dispatchSurvey = (
 export const surveyTrail = trail('survey', {
   blaze: async (input, ctx) => {
     const rootDir = ctx.cwd ?? '.';
+    const mode = deriveSurveyMode(input);
+    // Fresh load only for diffSaved: comparing against a previously-saved
+    // surface map requires the current app's source state, not any cached
+    // module graph that a prior import may have frozen. Other modes read
+    // the in-memory topo and benefit from the standard import cache.
+    //
+    // For diff specifically, use a disposable lease rather than retained
+    // fresh mirrors — the returned diff result is serialisable data, not
+    // a Topo reference with deferred imports, so the mirror can be
+    // released the moment dispatchSurvey returns. That keeps MCP/dev
+    // sessions that poll diff repeatedly from growing .trails-tmp/
+    // without bound.
+    if (mode === 'diff') {
+      const lease = await loadFreshAppLease(input.module, rootDir);
+      try {
+        return await dispatchSurvey(lease.app, input, rootDir);
+      } finally {
+        lease.release();
+      }
+    }
+
     const app = await loadApp(input.module, rootDir);
     return dispatchSurvey(app, input, rootDir);
   },
   description: 'Full topo introspection',
   examples: [
     {
-      description: 'Lists all registered trails with safety and trailhead info',
+      description: 'Lists all registered trails with safety and surface info',
       input: { module: './src/app.ts' },
       name: 'List all trails',
     },
@@ -191,15 +216,15 @@ export const surveyTrail = trail('survey', {
       .default(false)
       .describe('Only show breaking changes'),
     brief: z.boolean().default(false).describe('Quick capability summary'),
-    diff: z.string().optional().describe('Diff against a git ref'),
+    diffSaved: z
+      .boolean()
+      .default(false)
+      .describe('Diff against the saved local surface map'),
     generate: z
       .boolean()
       .default(false)
-      .describe('Generate trailhead map and lock file'),
-    module: z
-      .string()
-      .default('./src/app.ts')
-      .describe('Path to the app module'),
+      .describe('Generate surface map and lock file'),
+    module: z.string().optional().describe('Path to the app module'),
     openapi: z.boolean().default(false).describe('Output OpenAPI 3.1 spec'),
     trailId: z.string().optional().describe('Trail ID for detail view'),
   }),
@@ -215,13 +240,13 @@ export const surveyTrail = trail('survey', {
           safety: z.string(),
         })
       ),
-      provisionCount: z.number(),
-      provisions: z.array(
+      resourceCount: z.number(),
+      resources: z.array(
         z.object({
           description: z.string().nullable(),
           health: z.enum(['available', 'none']),
           id: z.string(),
-          kind: z.literal('provision'),
+          kind: z.literal('resource'),
           lifetime: z.literal('singleton'),
           usedBy: z.array(z.string()),
         })
@@ -233,11 +258,11 @@ export const surveyTrail = trail('survey', {
         detours: z.boolean(),
         examples: z.boolean(),
         outputSchemas: z.boolean(),
-        provisions: z.boolean(),
+        resources: z.boolean(),
         signals: z.boolean(),
       }),
       name: z.string(),
-      provisions: z.number(),
+      resources: z.number(),
       signals: z.number(),
       trails: z.number(),
       version: z.string(),
@@ -256,14 +281,14 @@ export const surveyTrail = trail('survey', {
       id: z.string(),
       intent: z.enum(['read', 'write', 'destroy']),
       kind: z.string(),
-      provisions: z.array(z.string()),
+      resources: z.array(z.string()),
       safety: z.string(),
     }),
     z.object({
       description: z.string().nullable(),
       health: z.enum(['available', 'none']),
       id: z.string(),
-      kind: z.literal('provision'),
+      kind: z.literal('resource'),
       lifetime: z.literal('singleton'),
       usedBy: z.array(z.string()),
     }),

package/src/trails/topo-export.ts

@@ -4,9 +4,8 @@ import { z } from 'zod';
 import { loadApp } from './load-app.js';
 import { exportCurrentTopo } from './topo-store-support.js';
 import {
-  DEFAULT_APP_MODULE,
-  isolatedExampleInput,
-  topoSaveOutput,
+  createIsolatedExampleInput,
+  topoSnapshotOutput,
 } from './topo-support.js';
 
 export const topoExportTrail = trail('topo.export', {
@@ -18,15 +17,12 @@ export const topoExportTrail = trail('topo.export', {
   description: 'Export the current topo to .trails artifacts',
   examples: [
     {
-      input: isolatedExampleInput('topo-export'),
+      input: createIsolatedExampleInput('topo-export'),
       name: 'Write the current topo export',
     },
   ],
   input: z.object({
-    module: z
-      .string()
-      .default(DEFAULT_APP_MODULE)
-      .describe('Path to the app module'),
+    module: z.string().optional().describe('Path to the app module'),
     rootDir: z.string().optional().describe('Workspace root directory'),
   }),
   intent: 'write',
@@ -34,6 +30,6 @@ export const topoExportTrail = trail('topo.export', {
     hash: z.string(),
     lockPath: z.string(),
     mapPath: z.string(),
-    save: topoSaveOutput,
+    snapshot: topoSnapshotOutput,
   }),
 });

package/src/trails/topo-history.ts

@@ -3,10 +3,9 @@ import { z } from 'zod';
 
 import {
   DEFAULT_TOPO_HISTORY_LIMIT,
-  isolatedExampleInput,
+  createIsolatedExampleInput,
   listTopoHistory,
-  topoPinOutput,
-  topoSaveOutput,
+  topoSnapshotOutput,
 } from './topo-support.js';
 
 export const topoHistoryTrail = trail('topo.history', {
@@ -14,10 +13,10 @@ export const topoHistoryTrail = trail('topo.history', {
     const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
     return Result.ok(listTopoHistory({ limit: input.limit, rootDir }));
   },
-  description: 'List saved topo metadata, including pins and recent autosaves',
+  description: 'List saved topo snapshots, including pinned references',
   examples: [
     {
-      input: isolatedExampleInput('topo-history'),
+      input: createIsolatedExampleInput('topo-history'),
       name: 'Show topo history',
     },
   ],
@@ -25,16 +24,15 @@ export const topoHistoryTrail = trail('topo.history', {
     limit: z
       .number()
       .default(DEFAULT_TOPO_HISTORY_LIMIT)
-      .describe('Maximum number of autosaves to return'),
+      .describe('Maximum number of snapshots to return'),
     rootDir: z.string().optional().describe('Workspace root directory'),
   }),
   intent: 'read',
   output: z.object({
     dbPath: z.string(),
     limit: z.number(),
-    pinCount: z.number(),
-    pins: z.array(topoPinOutput),
-    saveCount: z.number(),
-    saves: z.array(topoSaveOutput),
+    pinnedCount: z.number(),
+    snapshotCount: z.number(),
+    snapshots: z.array(topoSnapshotOutput),
   }),
 });

package/src/trails/topo-pin.ts

@@ -3,40 +3,36 @@ import { z } from 'zod';
 
 import { loadApp } from './load-app.js';
 import {
-  DEFAULT_APP_MODULE,
-  isolatedExampleInput,
-  pinCurrentTopo,
-  topoPinOutput,
-  topoSaveOutput,
+  createIsolatedExampleInput,
+  pinCurrentTopoSnapshot,
+  topoSnapshotOutput,
 } from './topo-support.js';
 
 export const topoPinTrail = trail('topo.pin', {
   blaze: async (input, ctx) => {
     const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
     const app = await loadApp(input.module, rootDir);
-    return Result.ok(pinCurrentTopo(app, { name: input.name, rootDir }));
+    return Result.ok(
+      pinCurrentTopoSnapshot(app, { name: input.name, rootDir })
+    );
   },
   description: 'Pin the current topo under a durable name',
   examples: [
     {
       input: {
-        ...isolatedExampleInput('topo-pin'),
+        ...createIsolatedExampleInput('topo-pin'),
         name: 'before-auth-refactor',
       },
       name: 'Pin the current topo',
     },
   ],
   input: z.object({
-    module: z
-      .string()
-      .default(DEFAULT_APP_MODULE)
-      .describe('Path to the app module'),
+    module: z.string().optional().describe('Path to the app module'),
     name: z.string().describe('Pin name'),
     rootDir: z.string().optional().describe('Workspace root directory'),
   }),
   intent: 'write',
   output: z.object({
-    pin: topoPinOutput,
-    save: topoSaveOutput,
+    snapshot: topoSnapshotOutput,
   }),
 });