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

package/src/trails/topo-store-support.ts

@@ -1,52 +1,60 @@
 /**
  * Stored-export pipeline for topo persistence.
  *
- * Extracted from topo-support.ts so this branch (trl-131) owns its own file,
- * keeping absorb routing clean across the stack.
+ * Extracted from topo-support.ts to isolate store persistence concerns,
+ * keeping module boundaries clean.
  */
 
-import type { Topo } from '@ontrails/core';
+import type { Topo, TopoSnapshot } from '@ontrails/core';
 import { InternalError, Result } from '@ontrails/core';
-import type { TopoSaveRecord } from '@ontrails/core/internal/topo-saves';
 import type { StoredTopoExport } from '@ontrails/core/internal/topo-store';
 import {
+  createTopoSnapshot,
   getStoredTopoExport,
-  persistEstablishedTopoSave,
 } from '@ontrails/core/internal/topo-store';
 import {
   openWriteTrailsDb,
-  resolveTrailsDir,
+  deriveTrailsDir,
 } from '@ontrails/core/internal/trails-db';
-import type { TrailheadLock, TrailheadMap } from '@ontrails/schema';
-import { writeTrailheadLock, writeTrailheadMap } from '@ontrails/schema';
+import type { SurfaceLock, SurfaceMap } from '@ontrails/schema';
+import { writeSurfaceLock, writeSurfaceMap } from '@ontrails/schema';
 
 import type { TopoExportReport } from './topo-support.js';
-import { currentGitState, resolveRootDir, topoCounts } from './topo-support.js';
+import {
+  deriveRootDir,
+  deriveTopoCounts,
+  readGitState,
+} from './topo-support.js';
 
 const persistAndReadStoredExport = (
   app: Topo,
   db: ReturnType<typeof openWriteTrailsDb>,
   rootDir: string
-): Result<{ save: TopoSaveRecord; storedExport: StoredTopoExport }, Error> => {
-  const saveResult = persistEstablishedTopoSave(db, app, {
-    ...currentGitState(rootDir),
-    ...topoCounts(app),
+): Result<
+  { snapshot: TopoSnapshot; storedExport: StoredTopoExport },
+  Error
+> => {
+  const snapshotResult = createTopoSnapshot(db, app, {
+    ...readGitState(rootDir),
+    ...deriveTopoCounts(app),
   });
-  if (saveResult.isErr()) {
-    return saveResult;
+  if (snapshotResult.isErr()) {
+    return snapshotResult;
   }
 
-  const save = saveResult.value;
-  const storedExport = getStoredTopoExport(db, save.id);
+  const snapshot = snapshotResult.value;
+  const storedExport = getStoredTopoExport(db, snapshot.id);
 
   if (storedExport === undefined) {
     return Result.err(
-      new InternalError(`Missing stored topo export for save "${save.id}"`)
+      new InternalError(
+        `Missing stored topo export for snapshot "${snapshot.id}"`
+      )
     );
   }
 
   return Result.ok({
-    save,
+    snapshot,
     storedExport,
   });
 };
@@ -55,17 +63,17 @@ const writeStoredExportArtifacts = async (
   storedExport: StoredTopoExport,
   trailsDir: string
 ): Promise<Pick<TopoExportReport, 'hash' | 'lockPath' | 'mapPath'>> => {
-  const mapPath = await writeTrailheadMap(
-    JSON.parse(storedExport.trailheadMapJson) as TrailheadMap,
+  const mapPath = await writeSurfaceMap(
+    JSON.parse(storedExport.surfaceMapJson) as SurfaceMap,
     { dir: trailsDir }
   );
-  const lockPath = await writeTrailheadLock(
-    JSON.parse(storedExport.lockContent) as TrailheadLock,
+  const lockPath = await writeSurfaceLock(
+    JSON.parse(storedExport.lockContent) as SurfaceLock,
     { dir: trailsDir }
   );
 
   return {
-    hash: storedExport.trailheadHash,
+    hash: storedExport.surfaceHash,
     lockPath,
     mapPath,
   };
@@ -75,7 +83,7 @@ export const exportCurrentTopo = async (
   app: Topo,
   options?: { readonly rootDir?: string }
 ): Promise<Result<TopoExportReport, Error>> => {
-  const rootDir = resolveRootDir(options?.rootDir);
+  const rootDir = deriveRootDir(options?.rootDir);
   const db = openWriteTrailsDb({ rootDir });
 
   try {
@@ -84,12 +92,12 @@ export const exportCurrentTopo = async (
       return persisted;
     }
 
-    const { save, storedExport } = persisted.value;
+    const { snapshot, storedExport } = persisted.value;
     const artifacts = await writeStoredExportArtifacts(
       storedExport,
-      resolveTrailsDir({ rootDir })
+      deriveTrailsDir({ rootDir })
     );
-    return Result.ok({ ...artifacts, save });
+    return Result.ok({ ...artifacts, snapshot });
   } finally {
     db.close();
   }

package/src/trails/topo-support.ts

@@ -3,60 +3,33 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import type { Topo } from '@ontrails/core';
-import type {
-  TopoPinRecord,
-  TopoSaveRecord,
-} from '@ontrails/core/internal/topo-saves';
 import {
-  getTopoPin,
-  listTopoPins,
-  listTopoSaves,
-  pinTopoSave,
-  unpinTopoSave,
-} from '@ontrails/core/internal/topo-saves';
-import { persistEstablishedTopoSave } from '@ontrails/core/internal/topo-store';
-import {
-  openReadTrailsDb,
-  openWriteTrailsDb,
-  resolveTrailsDbPath,
-} from '@ontrails/core/internal/trails-db';
+  createTopoSnapshot as persistTopoSnapshot,
+  listTopoSnapshots as readTopoSnapshots,
+  pinTopoSnapshot,
+  unpinTopoSnapshot,
+} from '@ontrails/core';
+import type { Topo, TopoSnapshot } from '@ontrails/core';
+import { deriveTrailsDbPath } from '@ontrails/core/internal/trails-db';
 import { z } from 'zod';
 
 import type { BriefReport, SurveyListReport } from './topo-reports.js';
 
-/** Output schema for a topo save record. Shared across topo trails. */
-export const topoSaveOutput = z.object({
+/** Output schema for a topo snapshot record. Shared across topo trails. */
+export const topoSnapshotOutput = z.object({
   createdAt: z.string(),
   gitDirty: z.boolean(),
   gitSha: z.string().optional(),
   id: z.string(),
-  provisionCount: z.number(),
+  pinnedAs: z.string().optional(),
+  resourceCount: z.number(),
   signalCount: z.number(),
   trailCount: z.number(),
 });
 
-/** Output schema for a topo pin record. Shared across topo trails. */
-export const topoPinOutput = z.object({
-  createdAt: z.string(),
-  name: z.string(),
-  saveId: z.string(),
-});
-
 export const DEFAULT_APP_MODULE = './src/app.ts';
 export const DEFAULT_TOPO_HISTORY_LIMIT = 10;
 export const LOCK_PATH = '.trails/trails.lock';
-export const LEGACY_LOCK_PATH = '.trails/trailhead.lock';
-
-/** Resolve the lockfile path, preferring the current name with legacy fallback. */
-export const resolveLockPath = (trailsDir: string): string => {
-  const primary = join(trailsDir, 'trails.lock');
-  if (existsSync(primary)) {
-    return primary;
-  }
-  const legacy = join(trailsDir, 'trailhead.lock');
-  return existsSync(legacy) ? legacy : primary;
-};
 const EXAMPLE_APP_MODULE = fileURLToPath(new URL('../app.ts', import.meta.url));
 
 export interface TopoSummaryReport {
@@ -70,17 +43,16 @@ export interface TopoSummaryReport {
 export interface TopoHistoryReport {
   readonly dbPath: string;
   readonly limit: number;
-  readonly pinCount: number;
-  readonly pins: TopoPinRecord[];
-  readonly saveCount: number;
-  readonly saves: TopoSaveRecord[];
+  readonly pinnedCount: number;
+  readonly snapshotCount: number;
+  readonly snapshots: TopoSnapshot[];
 }
 
 export interface TopoExportReport {
   readonly hash: string;
   readonly lockPath: string;
   readonly mapPath: string;
-  readonly save: TopoSaveRecord;
+  readonly snapshot: TopoSnapshot;
 }
 
 export interface TopoVerifyReport {
@@ -90,7 +62,7 @@ export interface TopoVerifyReport {
   readonly stale: false;
 }
 
-export const resolveRootDir = (cwd?: string): string => cwd ?? process.cwd();
+export const deriveRootDir = (cwd?: string): string => cwd ?? process.cwd();
 
 const safeGit = (cwd: string, args: readonly string[]): string | undefined => {
   const proc = Bun.spawnSync({
@@ -105,7 +77,7 @@ const safeGit = (cwd: string, args: readonly string[]): string | undefined => {
   return text.length === 0 ? undefined : text;
 };
 
-export const currentGitState = (
+export const readGitState = (
   rootDir: string
 ): { readonly gitDirty: boolean; readonly gitSha?: string } => {
   const gitSha = safeGit(rootDir, ['rev-parse', 'HEAD']);
@@ -116,10 +88,10 @@ export const currentGitState = (
   };
 };
 
-export const topoCounts = (
+export const deriveTopoCounts = (
   app: Topo
-): Pick<TopoSaveRecord, 'provisionCount' | 'signalCount' | 'trailCount'> => ({
-  provisionCount: app.provisions.size,
+): Pick<TopoSnapshot, 'resourceCount' | 'signalCount' | 'trailCount'> => ({
+  resourceCount: app.resources.size,
   signalCount: app.signals.size,
   trailCount: app.trails.size,
 });
@@ -130,40 +102,39 @@ const emptyTopoHistory = (
 ): TopoHistoryReport => ({
   dbPath,
   limit,
-  pinCount: 0,
-  pins: [],
-  saveCount: 0,
-  saves: [],
+  pinnedCount: 0,
+  snapshotCount: 0,
+  snapshots: [],
 });
 
-const collectedTopoHistory = (
+const collectTopoHistory = (
   dbPath: string,
   limit: number,
-  pins: readonly TopoPinRecord[],
-  allSaves: readonly TopoSaveRecord[]
+  snapshots: readonly TopoSnapshot[]
 ): TopoHistoryReport => ({
   dbPath,
   limit,
-  pinCount: pins.length,
-  pins: [...pins],
-  saveCount: allSaves.length,
-  saves: allSaves.slice(0, limit),
+  pinnedCount: snapshots.filter((snapshot) => snapshot.pinnedAs !== undefined)
+    .length,
+  snapshotCount: snapshots.length,
+  snapshots: snapshots.slice(0, limit),
 });
 
-const removeTopoPinWithDb = (
-  input: { readonly dryRun: boolean; readonly name: string },
-  pin: TopoPinRecord,
-  db: Parameters<typeof unpinTopoSave>[0]
+const buildSnapshotInput = (
+  app: Topo,
+  rootDir: string
 ): {
-  readonly dryRun: boolean;
-  readonly pin?: TopoPinRecord;
-  readonly removed: boolean;
-} =>
-  input.dryRun
-    ? { dryRun: true, pin, removed: false }
-    : { dryRun: false, pin, removed: unpinTopoSave(db, input.name) };
+  readonly gitDirty: boolean;
+  readonly gitSha?: string;
+  readonly resourceCount: number;
+  readonly signalCount: number;
+  readonly trailCount: number;
+} => ({
+  ...readGitState(rootDir),
+  ...deriveTopoCounts(app),
+});
 
-export const isolatedExampleInput = (
+export const createIsolatedExampleInput = (
   name: string
 ): { readonly module: string; readonly rootDir: string } => {
   const rootDir = join(tmpdir(), 'ontrails-trails-examples', name);
@@ -175,100 +146,85 @@ export const isolatedExampleInput = (
   };
 };
 
-export const createCurrentTopoSave = (
+export const createCurrentTopoSnapshot = (
   app: Topo,
   options?: { readonly rootDir?: string }
-): TopoSaveRecord => {
-  const rootDir = resolveRootDir(options?.rootDir);
-  const db = openWriteTrailsDb({ rootDir });
-
-  try {
-    const result = persistEstablishedTopoSave(db, app, {
-      ...currentGitState(rootDir),
-      ...topoCounts(app),
-    });
-    if (result.isErr()) {
-      throw result.error;
-    }
-    return result.value;
-  } finally {
-    db.close();
+): TopoSnapshot => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  const result = persistTopoSnapshot(app, {
+    rootDir,
+    ...buildSnapshotInput(app, rootDir),
+  });
+  if (result.isErr()) {
+    throw result.error;
   }
+  return result.value;
 };
 
 export const listTopoHistory = (options?: {
   readonly limit?: number;
   readonly rootDir?: string;
 }): TopoHistoryReport => {
-  const rootDir = resolveRootDir(options?.rootDir);
+  const rootDir = deriveRootDir(options?.rootDir);
   const limit = options?.limit ?? DEFAULT_TOPO_HISTORY_LIMIT;
-  const dbPath = resolveTrailsDbPath({ rootDir });
+  const dbPath = deriveTrailsDbPath({ rootDir });
   if (!existsSync(dbPath)) {
     return emptyTopoHistory(dbPath, limit);
   }
-  const db = openReadTrailsDb({ rootDir });
 
-  try {
-    return collectedTopoHistory(
-      dbPath,
-      limit,
-      listTopoPins(db),
-      listTopoSaves(db)
-    );
-  } finally {
-    db.close();
-  }
+  return collectTopoHistory(dbPath, limit, readTopoSnapshots({ rootDir }));
 };
 
-export const pinCurrentTopo = (
+export const pinCurrentTopoSnapshot = (
   app: Topo,
   input: { readonly name: string; readonly rootDir?: string }
-): { readonly pin: TopoPinRecord; readonly save: TopoSaveRecord } => {
-  const rootDir = resolveRootDir(input.rootDir);
-  const db = openWriteTrailsDb({ rootDir });
+): { readonly snapshot: TopoSnapshot } => {
+  const rootDir = deriveRootDir(input.rootDir);
+  const created = persistTopoSnapshot(app, {
+    rootDir,
+    ...buildSnapshotInput(app, rootDir),
+  });
+  if (created.isErr()) {
+    throw created.error;
+  }
 
-  try {
-    const result = persistEstablishedTopoSave(db, app, {
-      ...currentGitState(rootDir),
-      ...topoCounts(app),
-    });
-    if (result.isErr()) {
-      throw result.error;
-    }
-    const pin = pinTopoSave(db, {
-      name: input.name,
-      saveId: result.value.id,
-    });
-    return { pin, save: result.value };
-  } finally {
-    db.close();
+  const snapshot = pinTopoSnapshot(created.value.id, input.name, {
+    rootDir,
+  });
+  if (snapshot === undefined) {
+    throw new Error(`Missing topo snapshot "${created.value.id}" to pin`);
   }
+
+  return { snapshot };
 };
 
-export const removeTopoPin = (input: {
+export const removePinnedTopoSnapshot = (input: {
   readonly dryRun: boolean;
   readonly name: string;
   readonly rootDir?: string;
 }): {
   readonly dryRun: boolean;
-  readonly pin?: TopoPinRecord;
   readonly removed: boolean;
+  readonly snapshot?: TopoSnapshot;
 } => {
-  const rootDir = resolveRootDir(input.rootDir);
-  if (!existsSync(resolveTrailsDbPath({ rootDir }))) {
+  const rootDir = deriveRootDir(input.rootDir);
+  if (!existsSync(deriveTrailsDbPath({ rootDir }))) {
     return { dryRun: input.dryRun, removed: false };
   }
-  const db = input.dryRun
-    ? openReadTrailsDb({ rootDir })
-    : openWriteTrailsDb({ rootDir });
 
-  try {
-    const pin = getTopoPin(db, input.name);
-    if (pin === undefined) {
-      return { dryRun: input.dryRun, removed: false };
-    }
-    return removeTopoPinWithDb(input, pin, db);
-  } finally {
-    db.close();
+  if (input.dryRun) {
+    const snapshot = readTopoSnapshots({ pinned: true, rootDir }).find(
+      (candidate) => candidate.pinnedAs === input.name
+    );
+    return snapshot === undefined
+      ? { dryRun: true, removed: false }
+      : { dryRun: true, removed: false, snapshot };
   }
+
+  const snapshot = unpinTopoSnapshot(input.name, { rootDir });
+  return {
+    dryRun: false,
+    removed: snapshot !== undefined,
+    ...(snapshot === undefined ? {} : { snapshot }),
+  };
 };

package/src/trails/topo-unpin.ts

@@ -2,9 +2,9 @@ import { Result, ValidationError, trail } from '@ontrails/core';
 import { z } from 'zod';
 
 import {
-  isolatedExampleInput,
-  removeTopoPin,
-  topoPinOutput,
+  createIsolatedExampleInput,
+  removePinnedTopoSnapshot,
+  topoSnapshotOutput,
 } from './topo-support.js';
 
 export const topoUnpinTrail = trail('topo.unpin', {
@@ -19,14 +19,18 @@ export const topoUnpinTrail = trail('topo.unpin', {
 
     const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
     return Result.ok(
-      removeTopoPin({ dryRun: input.dryRun, name: input.name, rootDir })
+      removePinnedTopoSnapshot({
+        dryRun: input.dryRun,
+        name: input.name,
+        rootDir,
+      })
     );
   },
   description: 'Remove a named topo pin',
   examples: [
     {
       input: {
-        ...isolatedExampleInput('topo-unpin'),
+        ...createIsolatedExampleInput('topo-unpin'),
         dryRun: true,
         name: 'before-auth-refactor',
       },
@@ -45,7 +49,8 @@ export const topoUnpinTrail = trail('topo.unpin', {
   intent: 'destroy',
   output: z.object({
     dryRun: z.boolean(),
-    pin: topoPinOutput.optional(),
     removed: z.boolean(),
+    snapshot: topoSnapshotOutput.optional(),
   }),
+  permit: { scopes: ['topo:delete'] },
 });

package/src/trails/topo-verify.ts

@@ -3,7 +3,6 @@ import { z } from 'zod';
 
 import { loadApp } from './load-app.js';
 import { verifyCurrentTopo } from './topo-read-support.js';
-import { DEFAULT_APP_MODULE } from './topo-support.js';
 
 export const topoVerifyTrail = trail('topo.verify', {
   blaze: async (input, ctx) => {
@@ -13,10 +12,7 @@ export const topoVerifyTrail = trail('topo.verify', {
   },
   description: 'Verify that the committed lockfile matches 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'),
     rootDir: z.string().optional().describe('Workspace root directory'),
   }),
   intent: 'read',

package/src/trails/topo.ts

@@ -3,7 +3,6 @@ import { z } from 'zod';
 
 import { loadApp } from './load-app.js';
 import { buildTopoSummary } from './topo-read-support.js';
-import { DEFAULT_APP_MODULE } from './topo-support.js';
 
 const summaryOutput = z.object({
   app: z.object({
@@ -12,11 +11,11 @@ const summaryOutput = z.object({
       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(),
@@ -32,13 +31,13 @@ const summaryOutput = z.object({
         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()),
       })
@@ -62,10 +61,7 @@ export const topoTrail = trail('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'),
     rootDir: z.string().optional().describe('Workspace root directory'),
   }),
   intent: 'read',

package/src/trails/warden.ts

@@ -23,9 +23,14 @@ import { loadApp } from './load-app.js';
 export const wardenTrail = trail('warden', {
   blaze: async (input, ctx) => {
     const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
-    // oxlint-disable-next-line prefer-await-to-then -- catch converts rejection to undefined cleanly
-    const topo = await loadApp('./src/app.ts', rootDir).catch(
-      (): undefined => undefined
+    // oxlint-disable-next-line prefer-await-to-then -- catch preserves graceful degradation
+    const topo = await loadApp(input.module, rootDir).catch(
+      (error: unknown): undefined => {
+        ctx.logger?.warn('Could not load app for topo-aware governance', {
+          error: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+      }
     );
 
     const report = await runWarden({
@@ -76,6 +81,10 @@ export const wardenTrail = trail('warden', {
       .default('text')
       .describe('Output format: text, json, github, or summary'),
     lintOnly: z.boolean().default(false).describe('Only run lint rules'),
+    module: z
+      .string()
+      .optional()
+      .describe('App module path (auto-discovered if omitted)'),
     rootDir: z.string().optional().describe('Root directory to scan'),
   }),
   intent: 'read',

package/src/versions.ts

@@ -0,0 +1,43 @@
+interface PackageJson {
+  readonly catalog?: Record<string, string>;
+  readonly dependencies?: Record<string, string>;
+  readonly devDependencies?: Record<string, string>;
+  readonly version?: string;
+}
+
+const readPackageJson = async (url: URL): Promise<PackageJson> =>
+  (await Bun.file(url).json()) as PackageJson;
+
+const appPackageJson = await readPackageJson(
+  new URL('../package.json', import.meta.url)
+);
+const rootPackageJson = await readPackageJson(
+  new URL('../../../package.json', import.meta.url)
+);
+
+const requireVersion = (value: string | undefined, label: string): string => {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`Missing version for ${label}`);
+  }
+  return value;
+};
+
+const rootCatalog = rootPackageJson.catalog ?? {};
+const rootDevDependencies = rootPackageJson.devDependencies ?? {};
+
+export const trailsPackageVersion = requireVersion(
+  appPackageJson.version,
+  '@ontrails/trails'
+);
+
+export const ontrailsPackageRange = `^${trailsPackageVersion}`;
+
+export const scaffoldDependencyVersions = {
+  bunTypes: requireVersion(rootDevDependencies['@types/bun'], '@types/bun'),
+  commander: requireVersion(rootCatalog['commander'], 'commander'),
+  lefthook: requireVersion(rootDevDependencies['lefthook'], 'lefthook'),
+  oxlint: requireVersion(rootDevDependencies['oxlint'], 'oxlint'),
+  typescript: requireVersion(rootDevDependencies['typescript'], 'typescript'),
+  ultracite: requireVersion(rootDevDependencies['ultracite'], 'ultracite'),
+  zod: requireVersion(rootCatalog['zod'], 'zod'),
+} as const;

package/tsconfig.tests.json

@@ -0,0 +1,10 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": ".",
+    "types": ["bun"]
+  },
+  "include": ["src/**/*.test.ts", "src/__tests__/**/*.ts", "__tests__/**/*.ts"],
+  "exclude": []
+}