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

package/src/trails/project.ts

@@ -5,10 +5,24 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
+import { isDraftMarkedFile } from '@ontrails/warden';
+
 /** Return all TypeScript entries in a project's src directory. */
-const scanSourceEntries = (srcDir: string): string[] => [
-  ...new Bun.Glob('*.ts').scanSync({ cwd: srcDir }),
-];
+const sourceEntryPriority = (entry: string): number => {
+  if (entry === 'app.ts') {
+    return 0;
+  }
+  return isDraftMarkedFile(entry) ? 2 : 1;
+};
+
+const scanSourceEntries = (srcDir: string): string[] =>
+  [...new Bun.Glob('*.ts').scanSync({ cwd: srcDir })].toSorted((a, b) => {
+    const priority = sourceEntryPriority(a) - sourceEntryPriority(b);
+    if (priority === 0) {
+      return a.localeCompare(b);
+    }
+    return priority;
+  });
 
 /** Resolve an entry to an app import if it contains topo(). */
 const toTopoImport = async (

package/src/trails/survey.ts

@@ -1,256 +1,47 @@
 /**
  * `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 type { Topo, Trail } from '@ontrails/core';
-import { Result, trail } from '@ontrails/core';
+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,
-  hashTrailheadMap,
-  readTrailheadMap,
-  writeTrailheadLock,
-  writeTrailheadMap,
+  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,
+  buildCurrentTopoList,
+} from './topo-read-support.js';
+import { exportCurrentTopo } from './topo-store-support.js';
+
+export {
+  deriveBriefReport,
+  deriveResourceDetail,
+  deriveSurveyList,
+  deriveTrailDetail,
+} from './topo-reports.js';
+export type {
+  BriefReport,
+  SurveyListReport,
+  TrailDetailReport,
+} from './topo-reports.js';
 
 // ---------------------------------------------------------------------------
 // Brief report (formerly scout)
 // ---------------------------------------------------------------------------
 
-export interface BriefReport {
-  readonly name: string;
-  readonly version: string;
-  readonly contractVersion: string;
-  readonly features: {
-    readonly provisions: boolean;
-    readonly outputSchemas: boolean;
-    readonly examples: boolean;
-    readonly detours: boolean;
-    readonly signals: boolean;
-  };
-  readonly trails: number;
-  readonly signals: number;
-  readonly provisions: number;
-}
-
-export interface SurveyListReport {
-  readonly count: number;
-  readonly entries: readonly {
-    readonly examples: number;
-    readonly id: string;
-    readonly kind: string;
-    readonly safety: string;
-  }[];
-  readonly provisionCount: number;
-  readonly provisions: readonly {
-    readonly description: string | null;
-    readonly health: 'available' | 'none';
-    readonly id: string;
-    readonly kind: 'provision';
-    readonly lifetime: 'singleton';
-    readonly usedBy: readonly string[];
-  }[];
-}
-
-export interface TrailDetailReport {
-  readonly description: string | null;
-  readonly detours: Trail<unknown, unknown>['detours'] | null;
-  readonly examples: readonly unknown[];
-  readonly crosses: readonly string[];
-  readonly id: string;
-  readonly intent: 'read' | 'write' | 'destroy';
-  readonly kind: string;
-  readonly safety: string;
-  readonly provisions: readonly string[];
-}
-
-/** Check if a trail has a specific feature. */
-const trailHas = (raw: Record<string, unknown>, key: string): boolean => {
-  if (key === 'examples') {
-    return Array.isArray(raw[key]) && (raw[key] as unknown[]).length > 0;
-  }
-  return Boolean(raw[key]);
-};
-
-/** Detect which features are used across trails. */
-const detectFeatures = (
-  app: Topo
-): {
-  hasDetours: boolean;
-  hasExamples: boolean;
-  hasOutputSchemas: boolean;
-  hasProvisions: boolean;
-} => {
-  const trails = [...app.trails.values()].map(
-    (item) => item as unknown as Record<string, unknown>
-  );
-  return {
-    hasDetours: trails.some((r) => trailHas(r, 'detours')),
-    hasExamples: trails.some((r) => trailHas(r, 'examples')),
-    hasOutputSchemas: trails.some((r) => trailHas(r, 'output')),
-    hasProvisions: trails.some(
-      (r) =>
-        Array.isArray(r['provisions']) &&
-        (r['provisions'] as unknown[]).length > 0
-    ),
-  };
-};
-
-/** Generate a compact capability report for the given topo. */
-export const generateBriefReport = (app: Topo): BriefReport => {
-  const { hasDetours, hasExamples, hasOutputSchemas, hasProvisions } =
-    detectFeatures(app);
-
-  return {
-    contractVersion: '2026-03',
-    features: {
-      detours: hasDetours,
-      examples: hasExamples,
-      outputSchemas: hasOutputSchemas,
-      provisions: hasProvisions,
-      signals: app.signals.size > 0,
-    },
-    name: app.name,
-    provisions: app.provisions.size,
-    signals: app.signals.size,
-    trails: app.trails.size,
-    version: '0.1.0',
-  };
-};
-
-// ---------------------------------------------------------------------------
-// Formatting helpers
-// ---------------------------------------------------------------------------
-
-const safetyLabel = (entry: {
-  intent?: 'read' | 'write' | 'destroy';
-}): string => {
-  if (entry.intent === 'destroy') {
-    return 'destroy';
-  }
-  if (entry.intent === 'read') {
-    return 'read';
-  }
-  return '-';
-};
-
-const buildProvisionUsage = (
-  app: Topo
-): ReadonlyMap<string, readonly string[]> => {
-  const usage = new Map<string, string[]>();
-
-  for (const trailDef of app.list()) {
-    for (const declaredProvision of trailDef.provisions) {
-      const users = usage.get(declaredProvision.id) ?? [];
-      users.push(trailDef.id);
-      usage.set(declaredProvision.id, users);
-    }
-  }
-
-  return new Map(
-    [...usage.entries()].map(([id, users]) => [id, users.toSorted()] as const)
-  );
-};
-
-const provisionHealthStatus = (provision: {
-  health?: unknown;
-}): 'available' | 'none' =>
-  provision.health === undefined ? 'none' : 'available';
-
-const formatProvisionList = (app: Topo): SurveyListReport['provisions'] => {
-  const usage = buildProvisionUsage(app);
-  return app
-    .listProvisions()
-    .map((provision) => ({
-      description: provision.description ?? null,
-      health: provisionHealthStatus(provision),
-      id: provision.id,
-      kind: provision.kind,
-      lifetime: 'singleton' as const,
-      usedBy: usage.get(provision.id) ?? [],
-    }))
-    .toSorted((a, b) => a.id.localeCompare(b.id));
-};
-
-export const generateSurveyList = (app: Topo): SurveyListReport => {
-  const items = app.list();
-  const entries = items.map((item) => {
-    const safety = safetyLabel(
-      item as unknown as { intent?: 'read' | 'write' | 'destroy' }
-    );
-    const examples = Array.isArray(
-      (item as unknown as { examples?: unknown[] }).examples
-    )
-      ? (item as unknown as { examples: unknown[] }).examples.length
-      : 0;
-
-    return {
-      examples,
-      id: item.id,
-      kind: item.kind,
-      safety,
-    };
-  });
-
-  const provisions = formatProvisionList(app);
-
-  return {
-    count: items.length,
-    entries,
-    provisionCount: provisions.length,
-    provisions,
-  };
-};
-
-/**
- * Build a human-readable detail view for a single trail.
- *
- * Overlaps with `trailToEntry` in `@ontrails/schema` which builds the
- * trailhead-map entry. The two serve different audiences (human display vs
- * machine-diffable trailhead map) so they are kept separate.
- */
-export const generateTrailDetail = (
-  item: Trail<unknown, unknown>
-): TrailDetailReport => {
-  const safety = safetyLabel(
-    item as unknown as { intent?: 'read' | 'write' | 'destroy' }
-  );
-
-  return {
-    crosses: item.crosses.toSorted(),
-    description: item.description ?? null,
-    detours: item.detours ?? null,
-    examples: item.examples ?? [],
-    id: item.id,
-    intent: item.intent,
-    kind: item.kind,
-    provisions: item.provisions.map((provision) => provision.id).toSorted(),
-    safety,
-  };
-};
-
-const formatProvisionDetail = (app: Topo, provisionId: string): object => {
-  const item = app.getProvision(provisionId);
-  const usedBy = buildProvisionUsage(app).get(provisionId) ?? [];
-
-  return {
-    description: item?.description ?? null,
-    health: item ? provisionHealthStatus(item) : 'none',
-    id: provisionId,
-    kind: 'provision',
-    lifetime: 'singleton',
-    usedBy,
-  };
-};
-
 const formatDiff = (diff: DiffResult): object => ({
   breaking: diff.breaking,
   hasBreaking: diff.hasBreaking,
@@ -260,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 Error(
-        'No previous trailhead map found. Run `trails survey generate` first.'
+      new NotFoundError(
+        '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({
@@ -287,32 +79,37 @@ const buildSurveyDiff = async (
 
 const buildSurveyDetail = (
   app: Topo,
-  trailId: string
+  trailId: string,
+  rootDir: string
 ): Result<object, Error> => {
-  const item = app.get(trailId);
-  if (item) {
-    return Result.ok(generateTrailDetail(item as Trail<unknown, unknown>));
+  const detail = buildCurrentTopoDetail(app, trailId, { rootDir });
+  if (detail !== undefined) {
+    return Result.ok(detail);
   }
-  if (app.getProvision(trailId)) {
-    return Result.ok(formatProvisionDetail(app, trailId));
-  }
-  return Result.err(new Error(`Trail or provision not found: ${trailId}`));
+  return Result.err(
+    new NotFoundError(`Trail or resource not found: ${trailId}`)
+  );
 };
 
 const buildSurveyGenerate = async (
-  app: Topo
+  app: Topo,
+  rootDir: string
 ): Promise<Result<object, Error>> => {
-  const trailheadMap = generateTrailheadMap(app);
-  const mapPath = await writeTrailheadMap(trailheadMap);
-  const hash = hashTrailheadMap(trailheadMap);
-  const lockPath = await writeTrailheadLock(hash);
-  return Result.ok({ hash, lockPath, mapPath });
+  const exported = await exportCurrentTopo(app, { rootDir });
+  if (exported.isErr()) {
+    return exported;
+  }
+  return Result.ok({
+    hash: exported.value.hash,
+    lockPath: exported.value.lockPath,
+    mapPath: exported.value.mapPath,
+  });
 };
 
 interface SurveyInput {
   breakingOnly: boolean;
   brief: boolean;
-  diff?: string | undefined;
+  diffSaved: boolean;
   generate: boolean;
   openapi: boolean;
   trailId?: string | undefined;
@@ -323,39 +120,45 @@ 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 = (
   app: Topo,
-  input: SurveyInput
+  input: SurveyInput,
+  rootDir: string
 ) => Result<object, Error> | Promise<Result<object, Error>>;
 
 /** Handlers keyed by survey mode. */
 const surveyHandlers: Record<SurveyMode, SurveyHandler> = {
-  brief: (app) => Result.ok(generateBriefReport(app)),
-  detail: (app, input) => buildSurveyDetail(app, input.trailId ?? ''),
-  diff: (app, input) => buildSurveyDiff(app, input.breakingOnly),
-  generate: (app) => buildSurveyGenerate(app),
-  list: (app) => Result.ok(generateSurveyList(app)),
-  openapi: (app) => Result.ok(generateOpenApiSpec(app)),
+  brief: (app, _input, rootDir) =>
+    Result.ok(buildCurrentTopoBrief(app, { rootDir })),
+  detail: (app, input, rootDir) =>
+    buildSurveyDetail(app, input.trailId ?? '', rootDir),
+  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(deriveOpenApiSpec(app)),
 };
 
 /** Dispatch to the appropriate survey sub-command based on input flags. */
 const dispatchSurvey = (
   app: Topo,
-  input: SurveyInput
+  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);
+  return handler(app, input, rootDir);
 };
 
 // ---------------------------------------------------------------------------
@@ -364,13 +167,35 @@ const dispatchSurvey = (
 
 export const surveyTrail = trail('survey', {
   blaze: async (input, ctx) => {
-    const app = await loadApp(input.module, ctx.cwd ?? '.');
-    return dispatchSurvey(app, input);
+    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',
     },
@@ -391,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'),
   }),
@@ -415,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()),
         })
@@ -433,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(),
@@ -456,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-constants.ts

@@ -0,0 +1,2 @@
+export const REPORT_CONTRACT_VERSION = '2026-03';
+export const REPORT_VERSION = '0.1.0';

package/src/trails/topo-export.ts

@@ -0,0 +1,35 @@
+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-history.ts

@@ -0,0 +1,38 @@
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import {
+  DEFAULT_TOPO_HISTORY_LIMIT,
+  createIsolatedExampleInput,
+  listTopoHistory,
+  topoSnapshotOutput,
+} from './topo-support.js';
+
+export const topoHistoryTrail = trail('topo.history', {
+  blaze: (input, ctx) => {
+    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    return Result.ok(listTopoHistory({ limit: input.limit, rootDir }));
+  },
+  description: 'List saved topo snapshots, including pinned references',
+  examples: [
+    {
+      input: createIsolatedExampleInput('topo-history'),
+      name: 'Show topo history',
+    },
+  ],
+  input: z.object({
+    limit: z
+      .number()
+      .default(DEFAULT_TOPO_HISTORY_LIMIT)
+      .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(),
+    pinnedCount: z.number(),
+    snapshotCount: z.number(),
+    snapshots: z.array(topoSnapshotOutput),
+  }),
+});

package/src/trails/topo-pin.ts

@@ -0,0 +1,38 @@
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { loadApp } from './load-app.js';
+import {
+  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(
+      pinCurrentTopoSnapshot(app, { name: input.name, rootDir })
+    );
+  },
+  description: 'Pin the current topo under a durable name',
+  examples: [
+    {
+      input: {
+        ...createIsolatedExampleInput('topo-pin'),
+        name: 'before-auth-refactor',
+      },
+      name: 'Pin the current topo',
+    },
+  ],
+  input: z.object({
+    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({
+    snapshot: topoSnapshotOutput,
+  }),
+});