@ontrails/trails 1.0.0-beta.24 → 1.0.0-beta.29

package/src/trails/survey.ts

@@ -7,7 +7,7 @@
 
 import { basename, extname, join } from 'node:path';
 
-import type { Topo } from '@ontrails/core';
+import type { CliCommandAliasInput, Topo } from '@ontrails/core';
 import {
   deriveSafePath,
   NotFoundError,
@@ -28,8 +28,7 @@ import { z } from 'zod';
 
 import { writeIsolatedExampleJsonFile } from '../local-state-io.js';
 
-import { tryLoadFreshAppLease } from './load-app.js';
-import { resolveTrailRootDir } from './root-dir.js';
+import { withFreshAppLease, withOperatorRootDir } from './operator-context.js';
 import {
   buildCurrentTopoBrief,
   buildCurrentTopoList,
@@ -435,7 +434,7 @@ const readPathTopoGraph = async (
 const describeAgainstPathTarget = (against: string): string =>
   basename(against) === 'topo.lock' || extname(against) === '.json'
     ? 'workspace-relative TopoGraph file'
-    : 'workspace-relative directory containing topo.lock';
+    : 'workspace-relative directory containing trails.lock or topo.lock';
 
 const topoGraphNotFound = (against: string): NotFoundError =>
   new NotFoundError(
@@ -449,7 +448,9 @@ const readAgainstTopoGraph = async (
   against?: string | undefined
 ): Promise<Result<{ against: string; map: TopoGraph }, Error>> => {
   if (against === undefined || against === 'saved') {
-    const map = await readTopoGraph({ dir: join(rootDir, '.trails') });
+    const map =
+      (await readTopoGraph({ dir: rootDir })) ??
+      (await readTopoGraph({ dir: join(rootDir, '.trails') }));
     return map === null
       ? Result.err(
           new NotFoundError(
@@ -505,9 +506,13 @@ const buildSurveyLookup = (
   app: Topo,
   entityId: string,
   rootDir: string,
+  cliAliases:
+    | Readonly<Record<string, readonly CliCommandAliasInput[]>>
+    | undefined,
   surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined
 ): Result<object, Error> => {
   const matches = buildCurrentTopoMatches(app, entityId, {
+    cliAliases,
     rootDir,
     surfaceLayerNames,
   });
@@ -518,9 +523,13 @@ const buildSurveyTrailDetail = (
   app: Topo,
   id: string,
   rootDir: string,
+  cliAliases:
+    | Readonly<Record<string, readonly CliCommandAliasInput[]>>
+    | undefined,
   surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined
 ): Result<object, Error> => {
   const detail = buildCurrentTrailDetail(app, id, {
+    cliAliases,
     rootDir,
     surfaceLayerNames,
   });
@@ -572,15 +581,24 @@ type SurveyHandler = (
   app: Topo,
   input: SurveyInput,
   rootDir: string,
+  cliAliases:
+    | Readonly<Record<string, readonly CliCommandAliasInput[]>>
+    | undefined,
   surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined
 ) => Result<object, Error> | Promise<Result<object, Error>>;
 
 /** Handlers keyed by survey mode. */
 const surveyHandlers: Record<SurveyMode, SurveyHandler> = {
-  lookup: (app, input, rootDir, surfaceLayerNames) =>
+  lookup: (app, input, rootDir, cliAliases, surfaceLayerNames) =>
     input.id === undefined || input.id === ''
       ? Result.err(new ValidationError('Survey lookup requires an id'))
-      : buildSurveyLookup(app, input.id, rootDir, surfaceLayerNames),
+      : buildSurveyLookup(
+          app,
+          input.id,
+          rootDir,
+          cliAliases,
+          surfaceLayerNames
+        ),
   overview: (app, _input, rootDir) =>
     Result.ok(buildCurrentTopoList(app, { rootDir })),
 };
@@ -595,11 +613,20 @@ const dispatchSurvey = async (
   app: Topo,
   input: SurveyInput,
   rootDir: string,
+  cliAliases:
+    | Readonly<Record<string, readonly CliCommandAliasInput[]>>
+    | undefined,
   surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined
 ): Promise<Result<SurveyEnvelope, Error>> => {
   const mode = deriveSurveyMode(input);
   const handler = surveyHandlers[mode];
-  const result = await handler(app, input, rootDir, surfaceLayerNames);
+  const result = await handler(
+    app,
+    input,
+    rootDir,
+    cliAliases,
+    surfaceLayerNames
+  );
   if (result.isErr()) {
     return result;
   }
@@ -615,19 +642,16 @@ const detailInputSchema = z.object({
 const withFreshSurveyApp = async <T>(
   input: { readonly module?: string | undefined },
   rootDir: string,
-  consume: (app: Topo) => Promise<Result<T, Error>> | Result<T, Error>
-): Promise<Result<T, Error>> => {
-  const leaseResult = await tryLoadFreshAppLease(input.module, rootDir);
-  if (leaseResult.isErr()) {
-    return Result.err(leaseResult.error);
-  }
-  const lease = leaseResult.value;
-  try {
-    return await consume(lease.app);
-  } finally {
-    lease.release();
-  }
-};
+  consume: (
+    app: Topo,
+    cliAliases:
+      | Readonly<Record<string, readonly CliCommandAliasInput[]>>
+      | undefined
+  ) => Promise<Result<T, Error>> | Result<T, Error>
+): Promise<Result<T, Error>> =>
+  withFreshAppLease(input.module, rootDir, (lease) =>
+    consume(lease.app, lease.cliAliases)
+  );
 
 const withResolvedSurveyApp = async <T>(
   input: {
@@ -637,16 +661,17 @@ const withResolvedSurveyApp = async <T>(
   cwd: string | undefined,
   consume: (
     app: Topo,
-    rootDir: string
+    rootDir: string,
+    cliAliases:
+      | Readonly<Record<string, readonly CliCommandAliasInput[]>>
+      | undefined
   ) => Promise<Result<T, Error>> | Result<T, Error>
-): Promise<Result<T, Error>> => {
-  const rootDirResult = resolveTrailRootDir(input.rootDir, cwd);
-  if (rootDirResult.isErr()) {
-    return Result.err(rootDirResult.error);
-  }
-  const rootDir = rootDirResult.value;
-  return withFreshSurveyApp(input, rootDir, (app) => consume(app, rootDir));
-};
+): Promise<Result<T, Error>> =>
+  withOperatorRootDir(input, { cwd }, (rootDir) =>
+    withFreshSurveyApp(input, rootDir, (app, cliAliases) =>
+      consume(app, rootDir, cliAliases)
+    )
+  );
 
 const moduleInputSchema = z.object({
   module: z.string().optional().describe('Path to the app module'),
@@ -718,8 +743,14 @@ const surveyMatchOutput = z.discriminatedUnion('kind', [
 export const surveyTrail = trail('survey', {
   args: ['id'],
   blaze: async (input, ctx) =>
-    withResolvedSurveyApp(input, ctx.cwd, (app, rootDir) =>
-      dispatchSurvey(app, input, rootDir, readSurfaceLayerNamesFromContext(ctx))
+    withResolvedSurveyApp(input, ctx.cwd, (app, rootDir, cliAliases) =>
+      dispatchSurvey(
+        app,
+        input,
+        rootDir,
+        cliAliases,
+        readSurfaceLayerNamesFromContext(ctx)
+      )
     ),
   description: 'Full topo introspection',
   examples: [
@@ -827,6 +858,7 @@ export const surveySurfacesTrail = trail('survey.surfaces', {
 });
 
 export const surveyDiffTrail = trail('survey.diff', {
+  args: ['target'],
   blaze: async (input, ctx) =>
     withResolvedSurveyApp(input, ctx.cwd, (app, rootDir) =>
       buildSurveyDiff(app, rootDir, input)
@@ -838,6 +870,16 @@ export const surveyDiffTrail = trail('survey.diff', {
       input: createDiffExampleInput(),
       name: 'Diff against baseline',
     },
+    {
+      description: 'Show only breaking contract drift',
+      input: { ...createDiffExampleInput(), breaks: true },
+      name: 'Breaking changes',
+    },
+    {
+      description: 'Show graph-only force audit events',
+      input: { ...createDiffExampleInput(), forces: true },
+      name: 'Force audit events',
+    },
     {
       description: 'Reject an empty saved map target',
       error: 'ValidationError',
@@ -859,43 +901,15 @@ export const surveyDiffTrail = trail('survey.diff', {
   output: diffOutput,
 });
 
-export const diffTrail = trail('diff', {
-  args: ['target'],
-  blaze: async (input, ctx) =>
-    withResolvedSurveyApp(input, ctx.cwd, (app, rootDir) =>
-      buildSurveyDiff(app, rootDir, input)
-    ),
-  description: 'Diff the current topo against a saved TopoGraph',
-  examples: [
-    {
-      description: 'Compare current topo to a saved TopoGraph directory',
-      input: createDiffExampleInput(),
-      name: 'Diff against baseline',
-    },
-    {
-      description: 'Show only breaking contract drift',
-      input: { ...createDiffExampleInput(), breaks: true },
-      name: 'Breaking changes',
-    },
-    {
-      description: 'Show graph-only force audit events',
-      input: { ...createDiffExampleInput(), forces: true },
-      name: 'Force audit events',
-    },
-  ],
-  input: diffInputSchema,
-  intent: 'read',
-  output: diffOutput,
-});
-
 export const surveyTrailDetailTrail = trail('survey.trail', {
   args: ['id'],
   blaze: async (input, ctx) =>
-    withResolvedSurveyApp(input, ctx.cwd, (app, rootDir) =>
+    withResolvedSurveyApp(input, ctx.cwd, (app, rootDir, cliAliases) =>
       buildSurveyTrailDetail(
         app,
         input.id,
         rootDir,
+        cliAliases,
         readSurfaceLayerNamesFromContext(ctx)
       )
     ),

package/src/trails/topo-output-schemas.ts

@@ -178,6 +178,17 @@ export const trailDetailOutput = z.object({
   cli: z
     .object({
       path: z.array(z.string()).readonly(),
+      routes: z
+        .array(
+          z.object({
+            kind: z.enum(['alias', 'canonical']),
+            path: z.array(z.string()).readonly(),
+            source: z.enum(['derived', 'surface', 'trail']),
+            target: z.string(),
+          })
+        )
+        .readonly()
+        .optional(),
     })
     .nullable(),
   composedLayers: z.object({

package/src/trails/topo-pin.ts

@@ -1,8 +1,7 @@
 import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
-import { tryLoadFreshAppLease } from './load-app.js';
-import { resolveTrailRootDir } from './root-dir.js';
+import { withFreshOperatorApp } from './operator-context.js';
 import {
   createIsolatedExampleInput,
   pinCurrentTopoSnapshot,
@@ -10,25 +9,12 @@ import {
 } from './topo-support.js';
 
 export const topoPinTrail = trail('topo.pin', {
-  blaze: async (input, ctx) => {
-    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
-    if (rootDirResult.isErr()) {
-      return rootDirResult;
-    }
-    const rootDir = rootDirResult.value;
-    const leaseResult = await tryLoadFreshAppLease(input.module, rootDir);
-    if (leaseResult.isErr()) {
-      return leaseResult;
-    }
-    const lease = leaseResult.value;
-    try {
-      return Result.ok(
+  blaze: async (input, ctx) =>
+    withFreshOperatorApp(input, ctx, ({ lease, rootDir }) =>
+      Result.ok(
         pinCurrentTopoSnapshot(lease.app, { name: input.name, rootDir })
-      );
-    } finally {
-      lease.release();
-    }
-  },
+      )
+    ),
   description: 'Pin the current topo under a durable name',
   examples: [
     {

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

@@ -8,7 +8,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
-import type { Topo, TrailContext } from '@ontrails/core';
+import type { CliCommandAliasInput, Topo, TrailContext } from '@ontrails/core';
 import {
   ConflictError,
   deriveTrailsDbPath,
@@ -24,9 +24,10 @@ import {
   deriveTopoGraphHash,
   readLockManifest,
   readTopoGraph,
+  readTrailsLock,
   stripTopoGraphForces,
 } from '@ontrails/topographer';
-import type { TopoGraph } from '@ontrails/topographer';
+import type { LockManifest, TopoGraph } from '@ontrails/topographer';
 
 import type {
   BriefReport,
@@ -71,6 +72,9 @@ export interface CurrentTopoMatch {
 }
 
 export interface CurrentTopoReadOptions {
+  readonly cliAliases?:
+    | Readonly<Record<string, readonly CliCommandAliasInput[]>>
+    | undefined;
   readonly rootDir?: string | undefined;
   readonly surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined;
 }
@@ -96,6 +100,46 @@ export const readSurfaceLayerNamesFromContext = (
 const hasCommittedLock = (trailsDir: string): boolean =>
   existsSync(join(trailsDir, 'trails.lock'));
 
+const readCommittedLock = async (
+  rootDir: string
+): Promise<{
+  readonly lockManifest: LockManifest;
+  readonly topoGraph: TopoGraph;
+} | null> => {
+  const trailsLock = await readTrailsLock({ dir: rootDir });
+  if (trailsLock !== null) {
+    return {
+      lockManifest: {
+        artifacts: [
+          {
+            path: 'topo.lock',
+            role: 'topo',
+            sha256: trailsLock.topoGraphHash,
+          },
+        ],
+        scope: trailsLock.scope,
+        summary: trailsLock.summary,
+        version: 3,
+      },
+      topoGraph: trailsLock.topoGraph as TopoGraph,
+    };
+  }
+
+  const legacyDir = deriveTrailsDir({ rootDir });
+  const legacyManifest = await readLockManifest({ dir: legacyDir });
+  if (legacyManifest === null) {
+    return null;
+  }
+  const legacyTopoGraph = await readTopoGraph({ dir: legacyDir });
+  if (legacyTopoGraph === null) {
+    return null;
+  }
+  return {
+    lockManifest: legacyManifest,
+    topoGraph: legacyTopoGraph,
+  };
+};
+
 // ---------------------------------------------------------------------------
 // Public read-only consumers
 // ---------------------------------------------------------------------------
@@ -105,12 +149,13 @@ export const buildTopoSummary = (
   options?: { readonly rootDir?: string }
 ): TopoSummaryReport => {
   const rootDir = deriveRootDir(options?.rootDir);
-  const trailsDir = deriveTrailsDir({ rootDir });
   return {
     app: deriveBriefReport(app),
     dbPath: deriveTrailsDbPath({ rootDir }),
     list: deriveSurveyList(app),
-    lockExists: hasCommittedLock(trailsDir),
+    lockExists:
+      hasCommittedLock(rootDir) ||
+      hasCommittedLock(deriveTrailsDir({ rootDir })),
     lockPath: LOCK_PATH,
   };
 };
@@ -154,6 +199,7 @@ export const buildCurrentTrailDetail = (
     ? undefined
     : deriveTrailDetail(trail, app, undefined, {
         surfaceLayerNames: options?.surfaceLayerNames,
+        topoGraph: deriveTopoGraph(app, { cliAliases: options?.cliAliases }),
       });
 };
 
@@ -192,7 +238,7 @@ export const buildCurrentTopoMatches = (
     (activationGraph ??= deriveActivationGraph(app));
   let topoGraph: ReturnType<typeof deriveTopoGraph> | undefined;
   const getTopoGraph = (): ReturnType<typeof deriveTopoGraph> =>
-    (topoGraph ??= deriveTopoGraph(app));
+    (topoGraph ??= deriveTopoGraph(app, { cliAliases: options?.cliAliases }));
 
   const trail = app.get(id);
   if (trail !== undefined) {
@@ -220,14 +266,17 @@ export const buildCurrentTopoMatches = (
 
 export const validateCurrentTopo = async (
   app: Topo,
-  options?: { readonly rootDir?: string }
+  options?: {
+    readonly cliAliases?:
+      | Readonly<Record<string, readonly CliCommandAliasInput[]>>
+      | undefined;
+    readonly rootDir?: string;
+  }
 ): Promise<Result<TopoValidateReport, Error>> => {
   const rootDir = deriveRootDir(options?.rootDir);
-  let lockManifest: Awaited<ReturnType<typeof readLockManifest>>;
+  let committedLock: Awaited<ReturnType<typeof readCommittedLock>>;
   try {
-    lockManifest = await readLockManifest({
-      dir: deriveTrailsDir({ rootDir }),
-    });
+    committedLock = await readCommittedLock(rootDir);
   } catch (error) {
     const message =
       error instanceof Error
@@ -240,7 +289,7 @@ export const validateCurrentTopo = async (
     );
   }
 
-  if (lockManifest === null) {
+  if (committedLock === null) {
     return Result.err(
       new NotFoundError(
         'No committed trails.lock found. Run `trails compile` first.'
@@ -248,7 +297,10 @@ export const validateCurrentTopo = async (
     );
   }
 
-  const currentExport = deriveCurrentTopoExport(app, { rootDir });
+  const currentExport = deriveCurrentTopoExport(app, {
+    cliAliases: options?.cliAliases,
+    rootDir,
+  });
   if (currentExport.isErr()) {
     return currentExport;
   }
@@ -256,7 +308,7 @@ export const validateCurrentTopo = async (
     currentExport.value.topoGraphJson
   ) as TopoGraph;
   const currentHash = currentExport.value.topoGraphHash;
-  const topoArtifact = lockManifest.artifacts.find(
+  const topoArtifact = committedLock.lockManifest.artifacts.find(
     (artifact) => artifact.role === 'topo' && artifact.path === 'topo.lock'
   );
   if (topoArtifact === undefined) {
@@ -267,36 +319,34 @@ export const validateCurrentTopo = async (
     );
   }
 
+  const committedTopo = committedLock.topoGraph;
+  const committedHash = deriveTopoGraphHash(committedTopo);
+  if (committedHash !== topoArtifact.sha256) {
+    return Result.err(
+      new ValidationError(
+        'trails.lock graph hash does not match its embedded TopoGraph. Run `trails compile` to refresh it.'
+      )
+    );
+  }
+
   if (topoArtifact.sha256 !== currentHash) {
-    const committedTopo = await readTopoGraph({
-      dir: deriveTrailsDir({ rootDir }),
-    });
-    if (committedTopo !== null) {
-      const committedHash = deriveTopoGraphHash(committedTopo);
-      const forceStrippedHash = deriveTopoGraphHash(
-        stripTopoGraphForces(committedTopo)
-      );
-      if (
-        committedHash === topoArtifact.sha256 &&
-        forceStrippedHash === currentHash
-      ) {
-        return Result.ok({
-          committedHash: topoArtifact.sha256,
-          currentHash,
-          lockPath: LOCK_PATH,
-          stale: false,
-        });
-      }
+    const forceStrippedHash = deriveTopoGraphHash(
+      stripTopoGraphForces(committedTopo)
+    );
+    if (forceStrippedHash === currentHash) {
+      return Result.ok({
+        committedHash: topoArtifact.sha256,
+        currentHash,
+        lockPath: LOCK_PATH,
+        stale: false,
+      });
     }
-    const breakingSummary =
-      committedTopo === null
-        ? ''
-        : (() => {
-            const diff = deriveTopoGraphDiff(committedTopo, currentTopo);
-            return diff.breaking.length > 0
-              ? ` Breaking changes detected: ${diff.breaking.length}.`
-              : '';
-          })();
+    const breakingSummary = (() => {
+      const diff = deriveTopoGraphDiff(committedTopo, currentTopo);
+      return diff.breaking.length > 0
+        ? ` Breaking changes detected: ${diff.breaking.length}.`
+        : '';
+    })();
     return Result.err(
       new ConflictError(
         `trails.lock is stale. Run \`trails compile\` to refresh it.${breakingSummary}`

package/src/trails/topo-reports.ts

@@ -1,6 +1,6 @@
 import {
   DETOUR_MAX_ATTEMPTS_CAP,
-  deriveCliPath,
+  deriveTrailCliCommandProjection,
   filterSurfaceTrails,
   isArchivedTrailVersionEntry,
   zodToJsonSchema,
@@ -176,6 +176,7 @@ export interface TrailDetailReport {
   readonly activationSources: readonly ActivationSourceReport[];
   readonly cli: {
     readonly path: readonly string[];
+    readonly routes?: NonNullable<TopoGraphEntry['cli']>['routes'];
   } | null;
   /**
    * Composed layer names visible at the survey boundary.
@@ -560,7 +561,8 @@ export const deriveShippedSurfaceProjectionsForTrail = (
     trail.id,
     'trail'
   );
-  const commandPath = deriveCliPath(trail.id);
+  const commandPath =
+    entry?.cli?.path ?? deriveTrailCliCommandProjection(trail).path;
   const httpMethod = deriveHttpMethod(trail.intent);
   const httpPath = deriveHttpPath(trail.id);
   const mcpToolName = deriveToolName(app.name, trail.id);