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

package/src/trails/guide.ts

@@ -10,8 +10,8 @@ import { z } from 'zod';
 import { withFreshOperatorApp } from './operator-context.js';
 import { trailDetailOutput } from './topo-output-schemas.js';
 import {
-  buildCurrentGuideEntries,
-  buildCurrentTopoDetail,
+  deriveCurrentGuideEntries,
+  deriveCurrentTopoDetail,
   readSurfaceLayerNamesFromContext,
 } from './topo-read-support.js';
 import { createIsolatedExampleInput } from './topo-support.js';
@@ -53,8 +53,8 @@ export const guideTrail = trail('guide', {
   blaze: async (input: GuideTrailInput, ctx) =>
     withFreshOperatorApp<GuideTrailOutput>(input, ctx, ({ lease, rootDir }) => {
       if (input.trailId) {
-        const detail = buildCurrentTopoDetail(lease.app, input.trailId, {
-          cliAliases: lease.cliAliases,
+        const detail = deriveCurrentTopoDetail(lease.app, input.trailId, {
+          overlays: lease.overlays,
           rootDir,
           surfaceLayerNames: readSurfaceLayerNamesFromContext(ctx),
         });
@@ -70,7 +70,7 @@ export const guideTrail = trail('guide', {
       }
 
       return Result.ok({
-        entries: buildCurrentGuideEntries(lease.app, {
+        entries: deriveCurrentGuideEntries(lease.app, {
           rootDir,
         }) as GuideEntry[],
         mode: 'list' as const,

package/src/trails/load-app.ts

@@ -19,11 +19,14 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import {
   deriveSafePath,
   isTrailsError,
+  listWorkspacePackages,
   PermissionError,
   Result,
   ValidationError,
 } from '@ontrails/core';
-import type { CliCommandAliasInput, Topo } from '@ontrails/core';
+import type { Topo } from '@ontrails/core';
+import { resolveTrailsOverlays } from '@ontrails/adapter-kit';
+import type { TopoGraphOverlayRegistration } from '@ontrails/topographer';
 import { findAppModule } from '@ontrails/cli';
 
 import {
@@ -278,6 +281,8 @@ interface PackageJson {
   readonly workspaces?: unknown;
 }
 
+type NamedPackageJson = PackageJson & { readonly name: string };
+
 const readPackageJson = (packagePath: string): PackageJson | undefined => {
   try {
     return JSON.parse(readFileSync(packagePath, 'utf8')) as PackageJson;
@@ -327,20 +332,6 @@ const isPackageLocalImport = (
 const isScannableModule = (modulePath: string): boolean =>
   SCANNABLE_EXTENSIONS.has(extname(modulePath));
 
-const resolveImportedModulePath = (
-  importerPath: string,
-  importPath: string
-): string => {
-  const resolved = import.meta.resolve(
-    importPath,
-    pathToFileURL(importerPath).href
-  );
-  return resolveFilesystemModulePath(
-    fileURLToPath(resolved),
-    dirname(importerPath)
-  );
-};
-
 const readDirectoryEntries = (directoryPath: string): readonly string[] => {
   try {
     return readdirSync(directoryPath);
@@ -359,25 +350,41 @@ const safeStat = (
   }
 };
 
-const readWorkspacePatterns = (cwd: string): readonly string[] => {
-  const rootPackage = readPackageJson(join(cwd, 'package.json'));
-  const workspaces = rootPackage?.workspaces;
-  if (Array.isArray(workspaces)) {
-    return workspaces.filter(
-      (pattern): pattern is string => typeof pattern === 'string'
-    );
+const resolveImportedModulePath = (
+  importerPath: string,
+  importPath: string
+): string => {
+  const resolved = import.meta.resolve(
+    importPath,
+    pathToFileURL(importerPath).href
+  );
+  const literalPath = resolveFilesystemModulePath(
+    fileURLToPath(resolved),
+    dirname(importerPath)
+  );
+  if (safeStat(literalPath)?.isFile()) {
+    return literalPath;
   }
-  if (
-    typeof workspaces === 'object' &&
-    workspaces !== null &&
-    'packages' in workspaces &&
-    Array.isArray(workspaces.packages)
-  ) {
-    return workspaces.packages.filter(
-      (pattern): pattern is string => typeof pattern === 'string'
+
+  // `import.meta.resolve` joins relative specifiers without probing the
+  // filesystem, so extensionless imports point at paths that do not exist even
+  // though Bun resolves them at runtime. Fall back to the runtime resolver so
+  // runtime-valid apps stay fresh-loadable.
+  try {
+    return resolveFilesystemModulePath(
+      Bun.resolveSync(importPath, dirname(importerPath)),
+      dirname(importerPath)
+    );
+  } catch (error) {
+    const extensionlessHint =
+      extname(importPath) === ''
+        ? ' Extensionless relative imports must match a .ts/.tsx/.js module or a directory index.'
+        : '';
+    throw new ValidationError(
+      `Cannot resolve import "${importPath}" from "${importerPath}" while mirroring the app for fresh loading: "${literalPath}" does not exist and runtime resolution found no match. Fix the specifier or add the missing file.${extensionlessHint}`,
+      { cause: asError(error), context: { importPath, importerPath } }
     );
   }
-  return [];
 };
 
 interface WorkspacePackage {
@@ -386,45 +393,12 @@ interface WorkspacePackage {
   readonly packageRoot: string;
 }
 
-const listWorkspacePackageRoots = (cwd: string): readonly string[] => {
-  const roots: string[] = [];
-  for (const pattern of readWorkspacePatterns(cwd)) {
-    if (pattern.endsWith('/*')) {
-      const baseDir = resolve(cwd, pattern.slice(0, -2));
-      for (const entry of readDirectoryEntries(baseDir)) {
-        const entryPath = join(baseDir, entry);
-        if (safeStat(entryPath)?.isDirectory()) {
-          roots.push(entryPath);
-        }
-      }
-      continue;
-    }
-
-    if (!pattern.includes('*')) {
-      roots.push(resolve(cwd, pattern));
-    }
-  }
-  return roots;
-};
-
-const readWorkspacePackages = (cwd: string): readonly WorkspacePackage[] => {
-  const packages: WorkspacePackage[] = [];
-  for (const packageRoot of listWorkspacePackageRoots(cwd)) {
-    const packageJson = readPackageJson(join(packageRoot, 'package.json'));
-    if (
-      packageJson !== undefined &&
-      typeof packageJson.name === 'string' &&
-      packageJson.name.length > 0
-    ) {
-      packages.push({
-        name: packageJson.name,
-        packageJson,
-        packageRoot,
-      });
-    }
-  }
-  return packages;
-};
+const readWorkspacePackages = (cwd: string): readonly WorkspacePackage[] =>
+  listWorkspacePackages<NamedPackageJson>(cwd).map((workspacePackage) => ({
+    name: workspacePackage.manifest.name,
+    packageJson: workspacePackage.manifest,
+    packageRoot: workspacePackage.packageRoot,
+  }));
 
 const parsePackageSpecifier = (
   importPath: string
@@ -1054,54 +1028,11 @@ const resolveLoadedTopo = (
   return app;
 };
 
-type LoadedCliAliases = Readonly<
-  Record<string, readonly CliCommandAliasInput[]>
->;
-
-const isStringArray = (value: unknown): value is readonly string[] =>
-  Array.isArray(value) && value.every((item) => typeof item === 'string');
-
-const isCliAliasInput = (value: unknown): value is CliCommandAliasInput =>
-  typeof value === 'string' || isStringArray(value);
-
-const resolveLoadedCliAliases = (
-  effectivePath: string,
-  mod: Record<string, unknown>
-): LoadedCliAliases | undefined => {
-  const value = mod['trailsCliAliases'] ?? mod['cliAliases'];
-  if (value === undefined) {
-    return undefined;
-  }
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-    throw new ValidationError(
-      `CLI alias export in "${effectivePath}" must be a record from trail ID to alias list.`
-    );
-  }
-
-  const aliases = value as Record<string, unknown>;
-  for (const [trailId, trailAliases] of Object.entries(aliases)) {
-    if (!Array.isArray(trailAliases)) {
-      throw new ValidationError(
-        `CLI alias export for trail "${trailId}" in "${effectivePath}" must be an array.`
-      );
-    }
-    for (const alias of trailAliases) {
-      if (!isCliAliasInput(alias)) {
-        throw new ValidationError(
-          `CLI alias export for trail "${trailId}" in "${effectivePath}" must contain string aliases or string-array paths.`
-        );
-      }
-    }
-  }
-
-  return aliases as LoadedCliAliases;
-};
-
 export interface FreshAppLease {
   readonly app: Topo;
-  readonly cliAliases?: LoadedCliAliases | undefined;
   readonly mirrorRoot: string;
   readonly release: () => void;
+  readonly overlays?: readonly TopoGraphOverlayRegistration[] | undefined;
 }
 
 export type LoadAppLeaseOptions = LoadAppTrustOptions;
@@ -1122,8 +1053,8 @@ const createUrlSchemeLease = async (
   >;
   return {
     app: resolveLoadedTopo(effectivePath, mod),
-    cliAliases: resolveLoadedCliAliases(effectivePath, mod),
     mirrorRoot: absolutePath,
+    overlays: resolveTrailsOverlays(mod, effectivePath),
     release: noopRelease,
   };
 };
@@ -1144,8 +1075,8 @@ const createFilesystemLease = async (
 
     return {
       app: resolveLoadedTopo(effectivePath, mod),
-      cliAliases: resolveLoadedCliAliases(effectivePath, mod),
       mirrorRoot,
+      overlays: resolveTrailsOverlays(mod, effectivePath),
       release,
     };
   } catch (error) {