@ontrails/trails 1.0.0-beta.30 → 1.0.0-beta.39

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

@@ -8,7 +8,7 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
-import type { CliCommandAliasInput, Topo, TrailContext } from '@ontrails/core';
+import type { Topo, TrailContext } from '@ontrails/core';
 import {
   ConflictError,
   deriveTrailsDbPath,
@@ -27,7 +27,11 @@ import {
   readTrailsLock,
   stripTopoGraphForces,
 } from '@ontrails/topographer';
-import type { LockManifest, TopoGraph } from '@ontrails/topographer';
+import type {
+  LockManifest,
+  TopoGraph,
+  TopoGraphOverlayRegistration,
+} from '@ontrails/topographer';
 
 import type {
   BriefReport,
@@ -72,10 +76,8 @@ export interface CurrentTopoMatch {
 }
 
 export interface CurrentTopoReadOptions {
-  readonly cliAliases?:
-    | Readonly<Record<string, readonly CliCommandAliasInput[]>>
-    | undefined;
   readonly rootDir?: string | undefined;
+  readonly overlays?: readonly TopoGraphOverlayRegistration[] | undefined;
   readonly surfaceLayerNames?: Partial<SurfaceLayerNames> | undefined;
 }
 
@@ -144,7 +146,7 @@ const readCommittedLock = async (
 // Public read-only consumers
 // ---------------------------------------------------------------------------
 
-export const buildTopoSummary = (
+export const deriveTopoSummary = (
   app: Topo,
   options?: { readonly rootDir?: string }
 ): TopoSummaryReport => {
@@ -160,17 +162,17 @@ export const buildTopoSummary = (
   };
 };
 
-export const buildCurrentTopoBrief = (
+export const deriveCurrentTopoBrief = (
   app: Topo,
   _options?: { readonly rootDir?: string }
 ): BriefReport => deriveBriefReport(app);
 
-export const buildCurrentTopoList = (
+export const deriveCurrentTopoList = (
   app: Topo,
   _options?: { readonly rootDir?: string }
 ): SurveyListReport => deriveSurveyList(app);
 
-export const buildCurrentGuideEntries = (
+export const deriveCurrentGuideEntries = (
   app: Topo,
   _options?: { readonly rootDir?: string }
 ): readonly {
@@ -189,7 +191,7 @@ export const buildCurrentGuideEntries = (
     }))
     .toSorted((a, b) => a.id.localeCompare(b.id));
 
-export const buildCurrentTrailDetail = (
+export const deriveCurrentTrailDetail = (
   app: Topo,
   id: string,
   options?: CurrentTopoReadOptions
@@ -199,11 +201,13 @@ export const buildCurrentTrailDetail = (
     ? undefined
     : deriveTrailDetail(trail, app, undefined, {
         surfaceLayerNames: options?.surfaceLayerNames,
-        topoGraph: deriveTopoGraph(app, { cliAliases: options?.cliAliases }),
+        topoGraph: deriveTopoGraph(app, {
+          overlays: options?.overlays,
+        }),
       });
 };
 
-export const buildCurrentResourceDetail = (
+export const deriveCurrentResourceDetail = (
   app: Topo,
   id: string,
   _options?: { readonly rootDir?: string }
@@ -212,22 +216,22 @@ export const buildCurrentResourceDetail = (
     ? undefined
     : (deriveResourceDetail(app, id) as CurrentResourceDetail);
 
-export const buildCurrentSignalDetail = (
+export const deriveCurrentSignalDetail = (
   app: Topo,
   id: string,
   _options?: { readonly rootDir?: string }
 ): SignalDetailReport | undefined => deriveSignalDetail(app, id);
 
-export const buildCurrentTopoDetail = (
+export const deriveCurrentTopoDetail = (
   app: Topo,
   id: string,
   options?: CurrentTopoReadOptions
 ): CurrentTopoDetail | undefined =>
-  buildCurrentTrailDetail(app, id, options) ??
-  buildCurrentResourceDetail(app, id) ??
-  buildCurrentSignalDetail(app, id);
+  deriveCurrentTrailDetail(app, id, options) ??
+  deriveCurrentResourceDetail(app, id) ??
+  deriveCurrentSignalDetail(app, id);
 
-export const buildCurrentTopoMatches = (
+export const deriveCurrentTopoMatches = (
   app: Topo,
   id: string,
   options?: CurrentTopoReadOptions
@@ -238,7 +242,9 @@ export const buildCurrentTopoMatches = (
     (activationGraph ??= deriveActivationGraph(app));
   let topoGraph: ReturnType<typeof deriveTopoGraph> | undefined;
   const getTopoGraph = (): ReturnType<typeof deriveTopoGraph> =>
-    (topoGraph ??= deriveTopoGraph(app, { cliAliases: options?.cliAliases }));
+    (topoGraph ??= deriveTopoGraph(app, {
+      overlays: options?.overlays,
+    }));
 
   const trail = app.get(id);
   if (trail !== undefined) {
@@ -251,7 +257,7 @@ export const buildCurrentTopoMatches = (
     });
   }
 
-  const resource = buildCurrentResourceDetail(app, id);
+  const resource = deriveCurrentResourceDetail(app, id);
   if (resource !== undefined) {
     matches.push({ detail: resource, kind: 'resource' });
   }
@@ -267,10 +273,8 @@ export const buildCurrentTopoMatches = (
 export const validateCurrentTopo = async (
   app: Topo,
   options?: {
-    readonly cliAliases?:
-      | Readonly<Record<string, readonly CliCommandAliasInput[]>>
-      | undefined;
     readonly rootDir?: string;
+    readonly overlays?: readonly TopoGraphOverlayRegistration[] | undefined;
   }
 ): Promise<Result<TopoValidateReport, Error>> => {
   const rootDir = deriveRootDir(options?.rootDir);
@@ -298,7 +302,7 @@ export const validateCurrentTopo = async (
   }
 
   const currentExport = deriveCurrentTopoExport(app, {
-    cliAliases: options?.cliAliases,
+    overlays: options?.overlays,
     rootDir,
   });
   if (currentExport.isErr()) {

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

@@ -7,7 +7,7 @@
 
 import { Database } from 'bun:sqlite';
 
-import type { CliCommandAliasInput, Topo } from '@ontrails/core';
+import type { Topo } from '@ontrails/core';
 import {
   ConflictError,
   deriveTrailsDir,
@@ -19,6 +19,7 @@ import {
 import type {
   LockManifest,
   TopoGraph,
+  TopoGraphOverlayRegistration,
   TopoSnapshot,
   TrailsLock,
 } from '@ontrails/topographer';
@@ -26,6 +27,7 @@ import type { StoredTopoExport } from '@ontrails/topographer/backend-support';
 import {
   annotateTopoGraphForces,
   carryForwardTopoGraphForces,
+  deriveSourceFingerprint,
   deriveTopoGraphDiff,
   deriveTopoGraphHash,
   readTopoGraph,
@@ -45,21 +47,24 @@ import {
   readGitState,
 } from './topo-support.js';
 
-type CliAliasesOption = Readonly<
-  Record<string, readonly CliCommandAliasInput[]>
->;
+type OverlaysOption = readonly TopoGraphOverlayRegistration[];
 
 const persistAndReadStoredExport = (
   app: Topo,
   db: ReturnType<typeof openWriteTrailsDb>,
   rootDir: string,
-  options?: { readonly cliAliases?: CliAliasesOption | undefined } | undefined
+  options?:
+    | {
+        readonly overlays?: OverlaysOption | undefined;
+      }
+    | undefined
 ): Result<
   { snapshot: TopoSnapshot; storedExport: StoredTopoExport },
   Error
 > => {
   const snapshotResult = createStoredTopoSnapshot(db, app, {
-    cliAliases: options?.cliAliases,
+    overlays: options?.overlays,
+    sourceFingerprint: deriveSourceFingerprint(rootDir),
     ...readGitState(rootDir),
     ...deriveTopoCounts(app),
   });
@@ -125,8 +130,8 @@ export const mapTopoExportError = (error: unknown): Error => {
 export const deriveCurrentTopoExport = (
   app: Topo,
   options?: {
-    readonly cliAliases?: CliAliasesOption | undefined;
     readonly rootDir?: string;
+    readonly overlays?: OverlaysOption | undefined;
   }
 ): Result<StoredTopoExport, Error> => {
   const rootDir = deriveRootDir(options?.rootDir);
@@ -134,7 +139,7 @@ export const deriveCurrentTopoExport = (
 
   try {
     const projected = persistAndReadStoredExport(app, db, rootDir, {
-      cliAliases: options?.cliAliases,
+      overlays: options?.overlays,
     });
     return projected.isErr()
       ? projected
@@ -219,6 +224,10 @@ const writeStoredExportArtifacts = async (
   const lockManifest = JSON.parse(
     storedExport.lockManifestJson
   ) as LockManifest;
+  // Omit wallclock provenance from the committed artifact so recompiling the
+  // same sources yields byte-identical lock files; the hash never covered it.
+  const { generatedAt: _generatedAt, ...committedTopoGraph } =
+    prepared.topoGraph;
   const lockPath = await writeTrailsLock(
     {
       scope: lockManifest.scope,
@@ -236,7 +245,7 @@ const writeStoredExportArtifacts = async (
           (entry) => entry.kind === 'trail'
         ).length,
       },
-      topoGraph: prepared.topoGraph,
+      topoGraph: committedTopoGraph,
       topoGraphHash: prepared.hash,
       version: 4,
     } as TrailsLock,
@@ -256,9 +265,9 @@ const writeStoredExportArtifacts = async (
 export const exportCurrentTopo = async (
   app: Topo,
   options?: {
-    readonly cliAliases?: CliAliasesOption | undefined;
     readonly force?: boolean | undefined;
     readonly rootDir?: string;
+    readonly overlays?: OverlaysOption | undefined;
   }
 ): Promise<Result<TopoExportReport, Error>> => {
   const rootDir = deriveRootDir(options?.rootDir);
@@ -266,7 +275,7 @@ export const exportCurrentTopo = async (
 
   try {
     const candidate = deriveCurrentTopoExport(app, {
-      cliAliases: options?.cliAliases,
+      overlays: options?.overlays,
       rootDir,
     });
     if (candidate.isErr()) {
@@ -283,7 +292,7 @@ export const exportCurrentTopo = async (
 
     db = openWriteTrailsDb({ rootDir });
     const persisted = persistAndReadStoredExport(app, db, rootDir, {
-      cliAliases: options?.cliAliases,
+      overlays: options?.overlays,
     });
     if (persisted.isErr()) {
       return persisted;

package/src/trails/topo-support.ts

@@ -29,6 +29,7 @@ export const topoSnapshotOutput = z.object({
   pinnedAs: z.string().optional(),
   resourceCount: z.number(),
   signalCount: z.number(),
+  sourceFingerprint: z.string().optional(),
   trailCount: z.number(),
 });
 

package/src/trails/topo.ts

@@ -3,7 +3,7 @@ import { z } from 'zod';
 
 import { withFreshOperatorApp } from './operator-context.js';
 import { activationOverviewOutput } from './topo-output-schemas.js';
-import { buildTopoSummary } from './topo-read-support.js';
+import { deriveTopoSummary } from './topo-read-support.js';
 import { createIsolatedExampleInput } from './topo-support.js';
 
 const summaryOutput = z.object({
@@ -74,7 +74,7 @@ const summaryOutput = z.object({
 export const topoTrail = trail('topo', {
   blaze: async (input, ctx) =>
     withFreshOperatorApp(input, ctx, ({ lease, rootDir }) =>
-      Result.ok(buildTopoSummary(lease.app, { rootDir }))
+      Result.ok(deriveTopoSummary(lease.app, { rootDir }))
     ),
   description: 'Show the current topo summary and entry list',
   examples: [

package/src/trails/validate.ts

@@ -8,7 +8,7 @@ export const validateTrail = trail('validate', {
   blaze: async (input, ctx) =>
     withFreshOperatorApp(input, ctx, ({ lease, rootDir }) =>
       validateCurrentTopo(lease.app, {
-        cliAliases: lease.cliAliases,
+        overlays: lease.overlays,
         rootDir,
       })
     ),

package/src/trails/version-lifecycle-support.ts

@@ -23,7 +23,7 @@ export interface LifecycleCommandInput {
 }
 
 export interface LifecycleWriteResult {
-  readonly file: string;
+  readonly filePath: string;
   readonly trailId: string;
   readonly updated: boolean;
   readonly warnings?: readonly string[] | undefined;
@@ -32,8 +32,8 @@ export interface LifecycleWriteResult {
 interface TrailSourceMatch {
   readonly configEnd: number;
   readonly configStart: number;
-  readonly filePath: string;
   readonly source: string;
+  readonly sourcePath: string;
 }
 
 interface PropertyMatch {
@@ -108,8 +108,8 @@ const findTrailSource = (
       return Result.ok({
         configEnd: match.config.end,
         configStart: match.config.start,
-        filePath,
         source: source.value,
+        sourcePath: filePath,
       });
     }
   }
@@ -566,13 +566,13 @@ export const reviseTrailSource = (
       blaze?.value
     )
   );
-  const written = writeLifecycleSourceFile(match.value.filePath, nextSource);
+  const written = writeLifecycleSourceFile(match.value.sourcePath, nextSource);
   if (written.isErr()) {
     return written;
   }
 
   return Result.ok({
-    file: match.value.filePath,
+    filePath: match.value.sourcePath,
     trailId: trail.id,
     updated: true,
     ...(usesForkPlaceholder
@@ -724,18 +724,18 @@ export const setVersionStatusSource = (
         );
   if (nextSource === match.value.source) {
     return Result.ok({
-      file: match.value.filePath,
+      filePath: match.value.sourcePath,
       trailId: target.trailId,
       updated: false,
     });
   }
-  const written = writeLifecycleSourceFile(match.value.filePath, nextSource);
+  const written = writeLifecycleSourceFile(match.value.sourcePath, nextSource);
   if (written.isErr()) {
     return written;
   }
 
   return Result.ok({
-    file: match.value.filePath,
+    filePath: match.value.sourcePath,
     trailId: target.trailId,
     updated: true,
   });
@@ -768,18 +768,18 @@ export const forkVersionEntrySource = (
   const nextSource = rewrite.source;
   if (nextSource === match.value.source) {
     return Result.ok({
-      file: match.value.filePath,
+      filePath: match.value.sourcePath,
       trailId: target.trailId,
       updated: false,
     });
   }
-  const written = writeLifecycleSourceFile(match.value.filePath, nextSource);
+  const written = writeLifecycleSourceFile(match.value.sourcePath, nextSource);
   if (written.isErr()) {
     return written;
   }
 
   return Result.ok({
-    file: match.value.filePath,
+    filePath: match.value.sourcePath,
     trailId: target.trailId,
     updated: true,
     ...(rewrite.usedPlaceholder

package/src/trails/warden-guide.ts

@@ -37,6 +37,12 @@ const wardenRuleGuideEntrySchema = z.object({
     .object({
       class: z.enum(wardenFixClasses),
       safety: z.enum(wardenFixSafeties),
+      scanTargets: z
+        .object({
+          exclude: z.array(z.string()).readonly().optional(),
+          extensions: z.array(z.string()).readonly().optional(),
+        })
+        .optional(),
     })
     .optional(),
   guidance: wardenGuidanceSchema.optional(),
@@ -54,10 +60,9 @@ const wardenRuleGuideEntrySchema = z.object({
 const wardenGuideManifestSchema = z.object({
   generatedFrom: z.object({
     package: z.literal('@ontrails/warden'),
-    registries: z.tuple([
-      z.literal('wardenRules'),
-      z.literal('wardenTopoRules'),
-    ]),
+    registries: z
+      .tuple([z.literal('wardenRules'), z.literal('wardenTopoRules')])
+      .readonly(),
     source: z.literal('builtin-rule-metadata'),
   }),
   kind: z.literal('trails-warden-guide-manifest'),

package/src/trails/warden.ts

@@ -66,6 +66,10 @@ const wardenInputSchema = z.object({
   prePush: z.boolean().default(false).describe('Use the pre-push preset'),
   refresh: z.boolean().default(false).describe('Alias for --lock refresh'),
   rootDir: z.string().optional().describe('Root directory to scan'),
+  scopeExclude: z
+    .array(z.string())
+    .optional()
+    .describe('Root-relative path globs that Warden should not govern'),
   skipLock: z.boolean().default(false).describe('Alias for --lock skip'),
   strict: z.boolean().default(false).describe('Alias for --fail-on warning'),
   summary: z.boolean().default(false).describe('Alias for --format summary'),
@@ -106,6 +110,16 @@ const pushApps = (
   }
 };
 
+const pushRepeatedValues = (
+  args: string[],
+  flag: string,
+  values: readonly string[] | undefined
+): void => {
+  for (const value of values ?? []) {
+    args.push(flag, value);
+  }
+};
+
 export const buildWardenCommandArgs = (
   input: WardenTrailInput
 ): readonly string[] => {
@@ -150,6 +164,7 @@ export const buildWardenCommandArgs = (
   pushFlag(args, input.fix, '--fix');
   pushFlag(args, input.adapterCheck, '--adapter-check');
   pushValue(args, '--config-path', input.configPath);
+  pushRepeatedValues(args, '--scope-exclude', input.scopeExclude);
   pushApps(args, input.apps);
 
   return args;

package/src/trails/wayfind.ts

@@ -40,7 +40,6 @@ const wayfindInputSchema = z
       .default(false)
       .describe('Render the describe view for the selected target'),
     errors: z.boolean().default(false).describe('Resolve trail error facts'),
-    facets: z.boolean().default(false).describe('Resolve surface facet facts'),
     impact: z
       .boolean()
       .default(false)
@@ -66,6 +65,12 @@ const wayfindInputSchema = z
       .boolean()
       .default(false)
       .describe('Render the outline view for a source file target'),
+    overlay: z
+      .string()
+      .optional()
+      .describe(
+        'Read a namespaced fact overlay from the saved graph (e.g. --overlay cloudflare)'
+      ),
     overview: z
       .boolean()
       .default(false)
@@ -81,6 +86,10 @@ const wayfindInputSchema = z
       .string()
       .optional()
       .describe('Graph entity ID or source file path to inspect'),
+    trailheads: z
+      .boolean()
+      .default(false)
+      .describe('Resolve surface trailhead facts'),
     trails: z.boolean().default(false).describe('Resolve trail facts'),
     view: wayfinderViewSchema
       .default('list')
@@ -134,7 +143,7 @@ const wayfindInputSchema = z
       (input.adapter === undefined &&
         !input.contours &&
         !input.errors &&
-        !input.facets &&
+        !input.trailheads &&
         input.intent === undefined &&
         !input.resources &&
         !input.signals &&
@@ -155,7 +164,34 @@ const wayfindInputSchema = z
         '--include attaches facts to a target or filtered population from locked artifacts; impact/deps and live-source includes are not supported yet.',
       path: ['include'],
     }
-  );
+  )
+  .refine(
+    (input) =>
+      input.overlay === undefined ||
+      (input.target === undefined &&
+        !input.deps &&
+        !input.impact &&
+        input.include.length === 0 &&
+        input.adapter === undefined &&
+        !input.contours &&
+        !input.errors &&
+        !input.trailheads &&
+        input.intent === undefined &&
+        !input.resources &&
+        !input.signals &&
+        !input.surfaces &&
+        !input.trails),
+    {
+      message:
+        'The --overlay flag reads one lock overlay and cannot be combined with targets, population selectors, or includes.',
+      path: ['overlay'],
+    }
+  )
+  .refine((input) => input.overlay === undefined || input.source !== 'live', {
+    message:
+      '--overlay reads namespaced overlays from locked artifacts; live source does not carry lock overlays.',
+    path: ['overlay'],
+  });
 
 const wayfindComposeInputSchema = z
   .object({
@@ -200,7 +236,7 @@ const hasLiveTypedFilter = (input: WayfindInput): boolean =>
   input.adapter !== undefined ||
   input.contours ||
   input.errors ||
-  input.facets ||
+  input.trailheads ||
   input.intent !== undefined ||
   input.resources ||
   input.signals ||
@@ -214,14 +250,14 @@ const populationFilters = (
   readonly kind?:
     | readonly (
         | 'contour'
-        | 'facet'
+        | 'trailhead'
         | 'resource'
         | 'signal'
         | 'surface'
         | 'trail'
       )[]
     | 'contour'
-    | 'facet'
+    | 'trailhead'
     | 'resource'
     | 'signal'
     | 'surface'
@@ -232,7 +268,7 @@ const populationFilters = (
 } => {
   const kinds = [
     ...(input.contours ? ['contour' as const] : []),
-    ...(input.facets ? ['facet' as const] : []),
+    ...(input.trailheads ? ['trailhead' as const] : []),
     ...(input.resources ? ['resource' as const] : []),
     ...(input.signals ? ['signal' as const] : []),
     ...(input.surfaces ? ['surface' as const] : []),
@@ -713,9 +749,9 @@ const viewPopulation = async (
       view: 'list' as const,
     };
   }
-  if (input.facets) {
+  if (input.trailheads) {
     return {
-      result: ctx.compose('wayfind.facets', {
+      result: ctx.compose('wayfind.trailheads', {
         filters,
         limit: input.limit,
         ...sourceInput(input),
@@ -767,6 +803,17 @@ export const wayfindTrail = trail('wayfind.navigate', {
         );
       }
     }
+    if (input.overlay !== undefined) {
+      return envelopeFor(
+        await ctx.compose('wayfind.overlay', {
+          namespace: input.overlay,
+          ...sourceInput(input),
+        }),
+        input,
+        ctx,
+        'list'
+      );
+    }
     const dispatched =
       (await viewRelation(input, ctx)) ??
       (await (input.target === undefined
@@ -791,7 +838,8 @@ export const wayfindTrail = trail('wayfind.navigate', {
     'wayfind.describe',
     'wayfind.errors',
     'wayfind.examples',
-    'wayfind.facets',
+    'wayfind.overlay',
+    'wayfind.trailheads',
     'wayfind.impact',
     'wayfind.nearby',
     'wayfind.outline',
@@ -842,13 +890,17 @@ export const wayfindTrail = trail('wayfind.navigate', {
       name: 'List surface facts',
     },
     {
-      input: { facets: true },
-      name: 'List facet facts',
+      input: { trailheads: true },
+      name: 'List trailhead facts',
     },
     {
       input: { overview: true },
       name: 'Show graph overview',
     },
+    {
+      input: { overlay: 'cloudflare' },
+      name: 'Read a namespaced lock overlay',
+    },
     {
       input: { include: ['examples'], target: 'wayfind.search' },
       name: 'Attach examples for a target',