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

package/src/trails/survey.ts

@@ -1,255 +1,45 @@
 /**
  * `survey` trail -- Full topo introspection.
  *
- * Lists trails, shows detail for individual trails, generates surface maps,
+ * Lists trails, shows detail for individual trails, generates trailhead maps,
  * and diffs against previous versions.
  */
 
-import type { Topo, Trail } from '@ontrails/core';
-import { Result, trail } from '@ontrails/core';
+import type { Topo } from '@ontrails/core';
+import { NotFoundError, Result, trail } from '@ontrails/core';
 import type { DiffResult } from '@ontrails/schema';
 import {
-  diffSurfaceMaps,
+  diffTrailheadMaps,
   generateOpenApiSpec,
-  generateSurfaceMap,
-  hashSurfaceMap,
-  readSurfaceMap,
-  writeSurfaceLock,
-  writeSurfaceMap,
+  generateTrailheadMap,
+  readTrailheadMap,
 } from '@ontrails/schema';
 import { z } from 'zod';
 
 import { loadApp } from './load-app.js';
+import {
+  buildCurrentTopoBrief,
+  buildCurrentTopoDetail,
+  buildCurrentTopoList,
+} from './topo-read-support.js';
+import { exportCurrentTopo } from './topo-store-support.js';
+
+export {
+  formatProvisionDetail,
+  generateBriefReport,
+  generateSurveyList,
+  generateTrailDetail,
+} 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 services: boolean;
-    readonly outputSchemas: boolean;
-    readonly examples: boolean;
-    readonly detours: boolean;
-    readonly events: boolean;
-  };
-  readonly trails: number;
-  readonly events: number;
-  readonly services: number;
-}
-
-export interface SurveyListReport {
-  readonly count: number;
-  readonly entries: readonly {
-    readonly examples: number;
-    readonly id: string;
-    readonly kind: string;
-    readonly safety: string;
-  }[];
-  readonly serviceCount: number;
-  readonly services: readonly {
-    readonly description: string | null;
-    readonly health: 'available' | 'none';
-    readonly id: string;
-    readonly kind: 'service';
-    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 follow: readonly string[];
-  readonly id: string;
-  readonly intent: 'read' | 'write' | 'destroy';
-  readonly kind: string;
-  readonly safety: string;
-  readonly services: 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;
-  hasServices: 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')),
-    hasServices: trails.some(
-      (r) =>
-        Array.isArray(r['services']) && (r['services'] as unknown[]).length > 0
-    ),
-  };
-};
-
-/** Generate a compact capability report for the given topo. */
-export const generateBriefReport = (app: Topo): BriefReport => {
-  const { hasDetours, hasExamples, hasOutputSchemas, hasServices } =
-    detectFeatures(app);
-
-  return {
-    contractVersion: '2026-03',
-    events: app.events.size,
-    features: {
-      detours: hasDetours,
-      events: app.events.size > 0,
-      examples: hasExamples,
-      outputSchemas: hasOutputSchemas,
-      services: hasServices,
-    },
-    name: app.name,
-    services: app.services.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 buildServiceUsage = (
-  app: Topo
-): ReadonlyMap<string, readonly string[]> => {
-  const usage = new Map<string, string[]>();
-
-  for (const trailDef of app.list()) {
-    for (const declaredService of trailDef.services) {
-      const users = usage.get(declaredService.id) ?? [];
-      users.push(trailDef.id);
-      usage.set(declaredService.id, users);
-    }
-  }
-
-  return new Map(
-    [...usage.entries()].map(([id, users]) => [id, users.toSorted()] as const)
-  );
-};
-
-const serviceHealthStatus = (service: {
-  health?: unknown;
-}): 'available' | 'none' =>
-  service.health === undefined ? 'none' : 'available';
-
-const formatServiceList = (app: Topo): SurveyListReport['services'] => {
-  const usage = buildServiceUsage(app);
-  return app
-    .listServices()
-    .map((service) => ({
-      description: service.description ?? null,
-      health: serviceHealthStatus(service),
-      id: service.id,
-      kind: service.kind,
-      lifetime: 'singleton' as const,
-      usedBy: usage.get(service.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 services = formatServiceList(app);
-
-  return {
-    count: items.length,
-    entries,
-    serviceCount: services.length,
-    services,
-  };
-};
-
-/**
- * Build a human-readable detail view for a single trail.
- *
- * Overlaps with `trailToEntry` in `@ontrails/schema` which builds the
- * surface-map entry. The two serve different audiences (human display vs
- * machine-diffable surface 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 {
-    description: item.description ?? null,
-    detours: item.detours ?? null,
-    examples: item.examples ?? [],
-    follow: item.follow.toSorted(),
-    id: item.id,
-    intent: item.intent,
-    kind: item.kind,
-    safety,
-    services: item.services.map((service) => service.id).toSorted(),
-  };
-};
-
-const formatServiceDetail = (app: Topo, serviceId: string): object => {
-  const item = app.getService(serviceId);
-  const usedBy = buildServiceUsage(app).get(serviceId) ?? [];
-
-  return {
-    description: item?.description ?? null,
-    health: item ? serviceHealthStatus(item) : 'none',
-    id: serviceId,
-    kind: 'service',
-    lifetime: 'singleton',
-    usedBy,
-  };
-};
-
 const formatDiff = (diff: DiffResult): object => ({
   breaking: diff.breaking,
   hasBreaking: diff.hasBreaking,
@@ -261,17 +51,17 @@ const buildSurveyDiff = async (
   app: Topo,
   breakingOnly: boolean
 ): Promise<Result<object, Error>> => {
-  const currentMap = generateSurfaceMap(app);
-  const previousMap = await readSurfaceMap();
+  const currentMap = generateTrailheadMap(app);
+  const previousMap = await readTrailheadMap();
   if (!previousMap) {
     return Result.err(
-      new Error(
-        'No previous surface map found. Run `trails survey generate` first.'
+      new NotFoundError(
+        'No previous trailhead map found. Run `trails topo export` first.'
       )
     );
   }
 
-  const diff = diffSurfaceMaps(previousMap, currentMap);
+  const diff = diffTrailheadMaps(previousMap, currentMap);
   return Result.ok(
     breakingOnly
       ? formatDiff({
@@ -286,26 +76,31 @@ 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.getService(trailId)) {
-    return Result.ok(formatServiceDetail(app, trailId));
-  }
-  return Result.err(new Error(`Trail or service not found: ${trailId}`));
+  return Result.err(
+    new NotFoundError(`Trail or provision not found: ${trailId}`)
+  );
 };
 
 const buildSurveyGenerate = async (
-  app: Topo
+  app: Topo,
+  rootDir: string
 ): Promise<Result<object, Error>> => {
-  const surfaceMap = generateSurfaceMap(app);
-  const mapPath = await writeSurfaceMap(surfaceMap);
-  const hash = hashSurfaceMap(surfaceMap);
-  const lockPath = await writeSurfaceLock(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 {
@@ -334,27 +129,32 @@ const resolveSurveyMode = (input: SurveyInput): SurveyMode =>
 
 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 ?? ''),
+  brief: (app, _input, rootDir) =>
+    Result.ok(buildCurrentTopoBrief(app, { rootDir })),
+  detail: (app, input, rootDir) =>
+    buildSurveyDetail(app, input.trailId ?? '', rootDir),
   diff: (app, input) => buildSurveyDiff(app, input.breakingOnly),
-  generate: (app) => buildSurveyGenerate(app),
-  list: (app) => Result.ok(generateSurveyList(app)),
+  generate: (app, _input, rootDir) => buildSurveyGenerate(app, rootDir),
+  list: (app, _input, rootDir) =>
+    Result.ok(buildCurrentTopoList(app, { rootDir })),
   openapi: (app) => Result.ok(generateOpenApiSpec(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 handler = surveyHandlers[mode];
-  return handler(app, input);
+  return handler(app, input, rootDir);
 };
 
 // ---------------------------------------------------------------------------
@@ -362,21 +162,26 @@ const dispatchSurvey = (
 // ---------------------------------------------------------------------------
 
 export const surveyTrail = trail('survey', {
+  blaze: async (input, ctx) => {
+    const rootDir = ctx.cwd ?? '.';
+    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 surface info',
-      input: {},
+      description: 'Lists all registered trails with safety and trailhead info',
+      input: { module: './src/app.ts' },
       name: 'List all trails',
     },
     {
       description: 'Quick capability summary with counts and feature flags',
-      input: { brief: true },
+      input: { brief: true, module: './src/app.ts' },
       name: 'Brief capability report',
     },
     {
       description: 'Generate an OpenAPI 3.1 specification for the topo',
-      input: { openapi: true },
+      input: { module: './src/app.ts', openapi: true },
       name: 'OpenAPI spec',
     },
   ],
@@ -390,7 +195,7 @@ export const surveyTrail = trail('survey', {
     generate: z
       .boolean()
       .default(false)
-      .describe('Generate surface map and lock file'),
+      .describe('Generate trailhead map and lock file'),
     module: z
       .string()
       .default('./src/app.ts')
@@ -410,13 +215,13 @@ export const surveyTrail = trail('survey', {
           safety: z.string(),
         })
       ),
-      serviceCount: z.number(),
-      services: z.array(
+      provisionCount: z.number(),
+      provisions: z.array(
         z.object({
           description: z.string().nullable(),
           health: z.enum(['available', 'none']),
           id: z.string(),
-          kind: z.literal('service'),
+          kind: z.literal('provision'),
           lifetime: z.literal('singleton'),
           usedBy: z.array(z.string()),
         })
@@ -424,16 +229,16 @@ export const surveyTrail = trail('survey', {
     }),
     z.object({
       contractVersion: z.string(),
-      events: z.number(),
       features: z.object({
         detours: z.boolean(),
-        events: z.boolean(),
         examples: z.boolean(),
         outputSchemas: z.boolean(),
-        services: z.boolean(),
+        provisions: z.boolean(),
+        signals: z.boolean(),
       }),
       name: z.string(),
-      services: z.number(),
+      provisions: z.number(),
+      signals: z.number(),
       trails: z.number(),
       version: z.string(),
     }),
@@ -444,21 +249,21 @@ export const surveyTrail = trail('survey', {
       warnings: z.array(z.unknown()),
     }),
     z.object({
+      crosses: z.array(z.string()),
       description: z.unknown().nullable(),
       detours: z.unknown().nullable(),
       examples: z.array(z.unknown()),
-      follow: z.array(z.string()),
       id: z.string(),
       intent: z.enum(['read', 'write', 'destroy']),
       kind: z.string(),
+      provisions: z.array(z.string()),
       safety: z.string(),
-      services: z.array(z.string()),
     }),
     z.object({
       description: z.string().nullable(),
       health: z.enum(['available', 'none']),
       id: z.string(),
-      kind: z.literal('service'),
+      kind: z.literal('provision'),
       lifetime: z.literal('singleton'),
       usedBy: z.array(z.string()),
     }),
@@ -488,8 +293,4 @@ export const surveyTrail = trail('survey', {
         .optional(),
     }),
   ]),
-  run: async (input, ctx) => {
-    const app = await loadApp(input.module, ctx.cwd ?? '.');
-    return dispatchSurvey(app, input);
-  },
 });

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,39 @@
+import { trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { loadApp } from './load-app.js';
+import { exportCurrentTopo } from './topo-store-support.js';
+import {
+  DEFAULT_APP_MODULE,
+  isolatedExampleInput,
+  topoSaveOutput,
+} 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: isolatedExampleInput('topo-export'),
+      name: 'Write the current topo export',
+    },
+  ],
+  input: z.object({
+    module: z
+      .string()
+      .default(DEFAULT_APP_MODULE)
+      .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(),
+    save: topoSaveOutput,
+  }),
+});

package/src/trails/topo-history.ts

@@ -0,0 +1,40 @@
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import {
+  DEFAULT_TOPO_HISTORY_LIMIT,
+  isolatedExampleInput,
+  listTopoHistory,
+  topoPinOutput,
+  topoSaveOutput,
+} 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 metadata, including pins and recent autosaves',
+  examples: [
+    {
+      input: isolatedExampleInput('topo-history'),
+      name: 'Show topo history',
+    },
+  ],
+  input: z.object({
+    limit: z
+      .number()
+      .default(DEFAULT_TOPO_HISTORY_LIMIT)
+      .describe('Maximum number of autosaves 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),
+  }),
+});

package/src/trails/topo-pin.ts

@@ -0,0 +1,42 @@
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { loadApp } from './load-app.js';
+import {
+  DEFAULT_APP_MODULE,
+  isolatedExampleInput,
+  pinCurrentTopo,
+  topoPinOutput,
+  topoSaveOutput,
+} 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 }));
+  },
+  description: 'Pin the current topo under a durable name',
+  examples: [
+    {
+      input: {
+        ...isolatedExampleInput('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'),
+    name: z.string().describe('Pin name'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+  }),
+  intent: 'write',
+  output: z.object({
+    pin: topoPinOutput,
+    save: topoSaveOutput,
+  }),
+});