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

package/src/trails/guide.ts

@@ -4,11 +4,14 @@
  * Lists trails with descriptions and examples. Detailed guidance is planned for post-v1.
  */
 
-import type { Topo, Trail } from '@ontrails/core';
-import { Result, trail } from '@ontrails/core';
+import { NotFoundError, Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
 import { loadApp } from './load-app.js';
+import {
+  buildCurrentGuideEntries,
+  buildCurrentTopoDetail,
+} from './topo-read-support.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -25,48 +28,30 @@ interface GuideEntry {
 // Helpers
 // ---------------------------------------------------------------------------
 
-const toGuideEntries = (app: Topo): GuideEntry[] => {
-  const entries: GuideEntry[] = [];
-
-  for (const item of app.list()) {
-    const raw = item as unknown as Record<string, unknown>;
-    entries.push({
-      description:
-        typeof raw['description'] === 'string'
-          ? raw['description']
-          : '(no description)',
-      exampleCount: Array.isArray(raw['examples'])
-        ? (raw['examples'] as unknown[]).length
-        : 0,
-      id: item.id,
-      kind: item.kind,
-    });
-  }
-
-  return entries;
-};
-
-const toGuideDetail = (item: Trail<unknown, unknown>): object => ({
-  description: item.description ?? null,
-  detours: item.detours ?? null,
-  examples: item.examples ?? [],
-  id: item.id,
-  kind: item.kind,
-});
-
 export const guideTrail = trail('guide', {
   blaze: async (input, ctx) => {
-    const app = await loadApp(input.module, ctx.cwd ?? '.');
+    const rootDir = ctx.cwd ?? '.';
+    const app = await loadApp(input.module, rootDir);
 
     if (input.trailId) {
-      const item = app.get(input.trailId);
-      if (!item) {
-        return Result.err(new Error(`Trail not found: ${input.trailId}`));
+      const detail = buildCurrentTopoDetail(app, input.trailId, { rootDir });
+      if (detail === undefined || detail.kind !== 'trail') {
+        return Result.err(
+          new NotFoundError(`Trail not found: ${input.trailId}`)
+        );
       }
-      return Result.ok(toGuideDetail(item as Trail<unknown, unknown>));
+      return Result.ok({
+        description: detail.description,
+        detours: detail.detours,
+        examples: detail.examples,
+        id: detail.id,
+        kind: detail.kind,
+      });
     }
 
-    return Result.ok(toGuideEntries(app));
+    return Result.ok(
+      buildCurrentGuideEntries(app, { rootDir }) as GuideEntry[]
+    );
   },
   description: 'Runtime guidance for trails',
   examples: [

package/src/trails/load-app.ts

@@ -1,31 +1,94 @@
-import { isAbsolute, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { existsSync, rmSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import type { Topo } from '@ontrails/core';
 
 const URL_SCHEME = /^[a-zA-Z][a-zA-Z\d+.-]*:/;
 
-/** Resolve a module path from cwd so CLI defaults behave like shell paths. */
-const resolveModuleSpecifier = (modulePath: string, cwd: string): string => {
-  if (URL_SCHEME.test(modulePath)) {
-    return modulePath;
-  }
+const resolveUrlModulePath = (modulePath: string): string => {
+  const url = new URL(modulePath);
+  return url.protocol === 'file:' ? fileURLToPath(url) : modulePath;
+};
 
+const resolveFilesystemModulePath = (
+  modulePath: string,
+  cwd: string
+): string => {
   const absolutePath = isAbsolute(modulePath)
     ? modulePath
     : resolve(cwd, modulePath);
-  return pathToFileURL(absolutePath).href;
+  if (!absolutePath.endsWith('.js') || existsSync(absolutePath)) {
+    return absolutePath;
+  }
+
+  const tsPath = absolutePath.replace(/\.js$/, '.ts');
+  return existsSync(tsPath) ? tsPath : absolutePath;
+};
+
+/** Resolve a module path from cwd so CLI defaults behave like shell paths. */
+const resolveAbsoluteModulePath = (modulePath: string, cwd: string): string =>
+  URL_SCHEME.test(modulePath)
+    ? resolveUrlModulePath(modulePath)
+    : resolveFilesystemModulePath(modulePath, cwd);
+
+const freshModuleCopyPath = (absolutePath: string): string =>
+  join(
+    dirname(absolutePath),
+    `.__fresh-${Date.now()}-${Math.random().toString(36).slice(2)}-${basename(absolutePath)}`
+  );
+
+/**
+ * Import a module bypassing the ESM cache for the entry file.
+ *
+ * @remarks
+ * Cache-busting applies to the entry module only. Transitive imports resolved
+ * by the entry file are still served from Bun's module cache. This is
+ * acceptable for the draft promotion workflow (the only caller) because
+ * promotion changes which modules the entry file imports, not the modules
+ * themselves. If a deeper cache-bust is needed in the future, consider
+ * Bun's `Loader.registry` or a full process restart.
+ */
+const importFreshModule = async (
+  modulePath: string,
+  cwd: string
+): Promise<Record<string, unknown>> => {
+  const absolutePath = resolveAbsoluteModulePath(modulePath, cwd);
+  if (URL_SCHEME.test(absolutePath) && !absolutePath.startsWith('/')) {
+    const url = new URL(absolutePath);
+    url.searchParams.set('t', Date.now().toString());
+    return (await import(url.href)) as Record<string, unknown>;
+  }
+
+  const freshPath = freshModuleCopyPath(absolutePath);
+  await Bun.write(freshPath, await Bun.file(absolutePath).text());
+
+  try {
+    return (await import(pathToFileURL(freshPath).href)) as Record<
+      string,
+      unknown
+    >;
+  } finally {
+    rmSync(freshPath, { force: true });
+  }
 };
 
 /** Load a Topo export from a module path relative to cwd. */
 export const loadApp = async (
   modulePath: string,
-  cwd: string
+  cwd: string,
+  options: { fresh?: boolean | undefined } = {}
 ): Promise<Topo> => {
-  const mod = (await import(resolveModuleSpecifier(modulePath, cwd))) as Record<
-    string,
-    unknown
-  >;
+  const resolvedModulePath = resolveAbsoluteModulePath(modulePath, cwd);
+  const mod =
+    options.fresh === true
+      ? await importFreshModule(modulePath, cwd)
+      : ((await import(
+          URL_SCHEME.test(resolvedModulePath) &&
+            !resolvedModulePath.startsWith('/')
+            ? new URL(resolvedModulePath).href
+            : pathToFileURL(resolvedModulePath).href
+        )) as Record<string, unknown>);
   const app = (mod['default'] ?? mod['app']) as Topo | undefined;
   if (!app?.trails) {
     throw new Error(

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

@@ -5,252 +5,41 @@
  * 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 {
   diffTrailheadMaps,
   generateOpenApiSpec,
   generateTrailheadMap,
-  hashTrailheadMap,
   readTrailheadMap,
-  writeTrailheadLock,
-  writeTrailheadMap,
 } 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 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,
@@ -266,8 +55,8 @@ const buildSurveyDiff = async (
   const previousMap = await readTrailheadMap();
   if (!previousMap) {
     return Result.err(
-      new Error(
-        'No previous trailhead map found. Run `trails survey generate` first.'
+      new NotFoundError(
+        'No previous trailhead map found. Run `trails topo export` first.'
       )
     );
   }
@@ -287,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>));
-  }
-  if (app.getProvision(trailId)) {
-    return Result.ok(formatProvisionDetail(app, trailId));
+  const detail = buildCurrentTopoDetail(app, trailId, { rootDir });
+  if (detail !== undefined) {
+    return Result.ok(detail);
   }
-  return Result.err(new Error(`Trail or provision 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 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 {
@@ -335,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);
 };
 
 // ---------------------------------------------------------------------------
@@ -364,8 +163,9 @@ 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 app = await loadApp(input.module, rootDir);
+    return dispatchSurvey(app, input, rootDir);
   },
   description: 'Full topo introspection',
   examples: [

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),
+  }),
+});