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

package/src/trails/guide.ts

@@ -7,11 +7,15 @@
 import { NotFoundError, Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
-import { loadApp } from './load-app.js';
+import { tryLoadFreshAppLease } from './load-app.js';
+import { trailDetailOutput } from './topo-output-schemas.js';
 import {
   buildCurrentGuideEntries,
   buildCurrentTopoDetail,
+  readSurfaceLayerNamesFromContext,
 } from './topo-read-support.js';
+import { createIsolatedExampleInput } from './topo-support.js';
+import { resolveTrailRootDir } from './root-dir.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -21,7 +25,7 @@ interface GuideEntry {
   readonly description: string;
   readonly exampleCount: number;
   readonly id: string;
-  readonly kind: string;
+  readonly kind: 'trail';
 }
 
 // ---------------------------------------------------------------------------
@@ -30,57 +34,73 @@ interface GuideEntry {
 
 export const guideTrail = trail('guide', {
   blaze: async (input, ctx) => {
-    const rootDir = ctx.cwd ?? '.';
-    const app = await loadApp(input.module, rootDir);
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return Result.err(rootDirResult.error);
+    }
+    const rootDir = rootDirResult.value;
+    const leaseResult = await tryLoadFreshAppLease(input.module, rootDir);
+    if (leaseResult.isErr()) {
+      return Result.err(leaseResult.error);
+    }
+    const lease = leaseResult.value;
 
-    if (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}`)
-        );
+    try {
+      if (input.trailId) {
+        const detail = buildCurrentTopoDetail(lease.app, input.trailId, {
+          rootDir,
+          surfaceLayerNames: readSurfaceLayerNamesFromContext(ctx),
+        });
+        if (detail === undefined || detail.kind !== 'trail') {
+          return Result.err(
+            new NotFoundError(`Trail not found: ${input.trailId}`)
+          );
+        }
+        return Result.ok({
+          detail,
+          mode: 'detail' as const,
+        });
       }
+
       return Result.ok({
-        description: detail.description,
-        detours: detail.detours,
-        examples: detail.examples,
-        id: detail.id,
-        kind: detail.kind,
+        entries: buildCurrentGuideEntries(lease.app, {
+          rootDir,
+        }) as GuideEntry[],
+        mode: 'list' as const,
       });
+    } finally {
+      lease.release();
     }
-
-    return Result.ok(
-      buildCurrentGuideEntries(app, { rootDir }) as GuideEntry[]
-    );
   },
   description: 'Runtime guidance for trails',
   examples: [
     {
       description: 'Lists all trails with descriptions and example counts',
-      input: { module: './src/app.ts' },
+      input: createIsolatedExampleInput('guide-list'),
       name: 'List trail guidance',
     },
   ],
   input: z.object({
     module: z.string().optional().describe('Path to the app module'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
     trailId: z.string().optional().describe('Trail ID for detailed guidance'),
   }),
   intent: 'read',
-  output: z.union([
-    z.array(
-      z.object({
-        description: z.string(),
-        exampleCount: z.number(),
-        id: z.string(),
-        kind: z.string(),
-      })
-    ),
+  output: z.discriminatedUnion('mode', [
+    z.object({
+      entries: z.array(
+        z.object({
+          description: z.string(),
+          exampleCount: z.number(),
+          id: z.string(),
+          kind: z.literal('trail'),
+        })
+      ),
+      mode: z.literal('list'),
+    }),
     z.object({
-      description: z.string().nullable(),
-      detours: z.unknown().nullable(),
-      examples: z.array(z.unknown()),
-      id: z.string(),
-      kind: z.string(),
+      detail: trailDetailOutput,
+      mode: z.literal('detail'),
     }),
   ]),
 });

package/src/trails/load-app.ts

@@ -1,18 +1,40 @@
-import { existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+} from 'node:fs';
 import {
   dirname,
   extname,
   isAbsolute,
   join,
-  parse as parsePath,
   relative,
   resolve,
 } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import {
+  deriveSafePath,
+  InternalError,
+  isTrailsError,
+  PermissionError,
+  Result,
+  ValidationError,
+} from '@ontrails/core';
 import type { Topo } from '@ontrails/core';
 import { findAppModule } from '@ontrails/cli';
 
+import {
+  createLoadAppMirrorRootPath,
+  LOAD_APP_MIRROR_ENTRY_PREFIX,
+  LOAD_APP_MIRROR_PARENT_DIRNAME,
+  removeLoadAppMirrorRootQuietly,
+  resolveLoadAppMirrorFilePath,
+  writeLoadAppMirrorFile,
+} from '../load-app-mirror.js';
+
 const URL_SCHEME = /^[a-zA-Z][a-zA-Z\d+.-]*:/;
 
 type TranspilerLoader = 'ts' | 'tsx' | 'js' | 'jsx';
@@ -58,7 +80,7 @@ const RETAINED_MIRROR_ROOTS = new Set<string>();
 
 const cleanupAllMirrorRoots = (): void => {
   for (const root of [...ACTIVE_MIRROR_ROOTS, ...RETAINED_MIRROR_ROOTS]) {
-    rmSync(root, { force: true, recursive: true });
+    removeLoadAppMirrorRootQuietly(root);
   }
   ACTIVE_MIRROR_ROOTS.clear();
   RETAINED_MIRROR_ROOTS.clear();
@@ -110,7 +132,7 @@ const acquireMirrorLease = (mirrorRoot: string): (() => void) => {
 
     released = true;
     ACTIVE_MIRROR_ROOTS.delete(mirrorRoot);
-    rmSync(mirrorRoot, { force: true, recursive: true });
+    removeLoadAppMirrorRootQuietly(mirrorRoot);
   };
 };
 
@@ -134,30 +156,161 @@ const resolveFilesystemModulePath = (
   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 =>
+const trustBoundaryError = (reason: string): PermissionError =>
+  new PermissionError(
+    `Refusing to load an app module outside the workspace trust boundary (${reason}). Use a workspace-relative module path, or pass trustedModulePath: true from trusted code.`
+  );
+
+const toLoadAppError = (error: unknown): Error =>
+  isTrailsError(error)
+    ? error
+    : new InternalError('Failed to load app module', {
+        cause: error instanceof Error ? error : new Error(String(error)),
+      });
+
+const isPathInside = (root: string, target: string): boolean => {
+  const candidate = relative(root, target);
+  return (
+    candidate === '' || (!candidate.startsWith('..') && !isAbsolute(candidate))
+  );
+};
+
+const realpathIfPresent = (path: string): string | undefined => {
+  try {
+    return realpathSync(path);
+  } catch {
+    return undefined;
+  }
+};
+
+const ensureRealPathInsideCwd = (
+  resolvedModulePath: string,
+  cwd: string
+): string => {
+  const realRoot = realpathIfPresent(cwd);
+  const realModule = realpathIfPresent(resolvedModulePath);
+  if (
+    realRoot !== undefined &&
+    realModule !== undefined &&
+    !isPathInside(realRoot, realModule)
+  ) {
+    throw trustBoundaryError('symlink_escape');
+  }
+
+  return resolvedModulePath;
+};
+
+/** Resolve a caller-trusted module path using the legacy escape hatch policy. */
+const resolveTrustedModulePath = (modulePath: string, cwd: string): string =>
   URL_SCHEME.test(modulePath)
     ? resolveUrlModulePath(modulePath)
     : resolveFilesystemModulePath(modulePath, cwd);
 
-const MIRROR_PARENT_DIRNAME = '.trails-tmp';
-
-const MIRROR_ENTRY_PREFIX = 'load-app-fresh-';
-
 /**
- * Convert an absolute path to a drive-safe relative form before appending it
- * to the mirror root. `path.parse(...).root` returns `'/'` on POSIX and
- * `'C:\\'` (or similar) on Windows, so `relative` strips the platform root
- * in both cases.
+ * Resolve the default app module path inside cwd.
+ *
+ * @remarks
+ * CLI and trail callers accept user-supplied module specifiers, so the default
+ * policy is deliberately narrower than `import()` itself: no URL schemes, no
+ * absolute paths, and no parent traversal. Internal callers that intentionally
+ * load a path outside cwd must opt into `trustedModulePath`.
  */
-const freshMirrorPath = (absolutePath: string, mirrorRoot: string): string =>
-  join(mirrorRoot, relative(parsePath(absolutePath).root, absolutePath));
+const resolveContainedModulePath = (
+  modulePath: string,
+  cwd: string
+): string => {
+  if (URL_SCHEME.test(modulePath)) {
+    throw trustBoundaryError('url_scheme');
+  }
+  if (isAbsolute(modulePath)) {
+    throw trustBoundaryError('absolute_path');
+  }
+
+  const safePath = deriveSafePath(cwd, modulePath);
+  if (safePath.isErr()) {
+    throw trustBoundaryError('parent_escape');
+  }
+
+  return ensureRealPathInsideCwd(
+    resolveFilesystemModulePath(safePath.value, cwd),
+    cwd
+  );
+};
+
+interface LoadAppTrustOptions {
+  readonly trustedModulePath?: boolean | undefined;
+}
+
+const resolveLoadAppModulePath = (
+  modulePath: string,
+  cwd: string,
+  options: LoadAppTrustOptions = {}
+): string =>
+  options.trustedModulePath === true
+    ? resolveTrustedModulePath(modulePath, cwd)
+    : resolveContainedModulePath(modulePath, cwd);
+
+const findWorkspaceRelativeAppModule = (cwd: string): string => {
+  const discovered = findAppModule(cwd);
+  return isAbsolute(discovered) ? relative(cwd, discovered) : discovered;
+};
 
 const isLocalFilesystemImport = (importPath: string): boolean =>
   importPath.startsWith('.') ||
   importPath.startsWith('/') ||
   importPath.startsWith('file:');
 
+const readPackageName = (packagePath: string): string | undefined => {
+  try {
+    const parsed = JSON.parse(readFileSync(packagePath, 'utf8')) as
+      | { readonly name?: unknown }
+      | undefined;
+    return typeof parsed?.name === 'string' && parsed.name.length > 0
+      ? parsed.name
+      : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+const findNearestPackageName = (directoryPath: string): string | undefined => {
+  let current = directoryPath;
+  while (true) {
+    const name = readPackageName(join(current, 'package.json'));
+    if (name !== undefined) {
+      return name;
+    }
+
+    const parent = dirname(current);
+    if (parent === current) {
+      return undefined;
+    }
+    current = parent;
+  }
+};
+
+const isPackageLocalImport = (
+  importerPath: string,
+  importPath: string
+): boolean => {
+  if (importPath.startsWith('#')) {
+    return true;
+  }
+
+  const packageName = findNearestPackageName(dirname(importerPath));
+  return (
+    packageName !== undefined &&
+    (importPath === packageName || importPath.startsWith(`${packageName}/`))
+  );
+};
+
+const shouldMirrorImportSpecifier = (
+  importerPath: string,
+  importPath: string
+): boolean =>
+  isLocalFilesystemImport(importPath) ||
+  isPackageLocalImport(importerPath, importPath);
+
 const isScannableModule = (modulePath: string): boolean =>
   SCANNABLE_EXTENSIONS.has(extname(modulePath));
 
@@ -188,19 +341,10 @@ const collectImportedModulePaths = (
   return getImportScanner(loader)
     .scanImports(source)
     .map((entry) => entry.path)
-    .filter(isLocalFilesystemImport)
+    .filter((importPath) => shouldMirrorImportSpecifier(modulePath, importPath))
     .map((importPath) => resolveImportedModulePath(modulePath, importPath));
 };
 
-/**
- * Copy a single file into the mirror by raw bytes.
- *
- * @remarks
- * Reading via `.bytes()` rather than `.text()` preserves binary payloads
- * (`.wasm`, `.node`, compiled assets) that may sit alongside source files in
- * the app's graph. Text decoding would corrupt them on the way through the
- * mirror.
- */
 const copyFileToMirror = async (
   sourcePath: string,
   mirrorRoot: string,
@@ -211,10 +355,10 @@ const copyFileToMirror = async (
   }
   copied.add(sourcePath);
 
-  const mirrorPath = freshMirrorPath(sourcePath, mirrorRoot);
-  mkdirSync(dirname(mirrorPath), { recursive: true });
-  const bytes = await Bun.file(sourcePath).bytes();
-  await Bun.write(mirrorPath, bytes);
+  const written = await writeLoadAppMirrorFile(sourcePath, mirrorRoot);
+  if (written.isErr()) {
+    throw written.error;
+  }
 };
 
 /**
@@ -301,14 +445,11 @@ const isStaleMirrorEntry = (entryPath: string, now: number): boolean => {
 };
 
 const removeStaleMirrorEntry = (entryPath: string): void => {
-  try {
-    rmSync(entryPath, { force: true, recursive: true });
-  } catch {
-    /*
-     * Another concurrent load may own it. Safe to ignore — the next sweep
-     * will retry.
-     */
-  }
+  /*
+   * Another concurrent load may own it. Safe to ignore — the next sweep
+   * will retry.
+   */
+  removeLoadAppMirrorRootQuietly(entryPath);
 };
 
 /**
@@ -322,7 +463,7 @@ const cleanupStaleMirrorRoots = (mirrorParent: string): void => {
   }
   const now = Date.now();
   for (const entry of entries) {
-    if (!entry.startsWith(MIRROR_ENTRY_PREFIX)) {
+    if (!entry.startsWith(LOAD_APP_MIRROR_ENTRY_PREFIX)) {
       continue;
     }
     const entryPath = join(mirrorParent, entry);
@@ -333,12 +474,9 @@ const cleanupStaleMirrorRoots = (mirrorParent: string): void => {
 };
 
 const freshMirrorRootPath = (cwd: string): string => {
-  const mirrorParent = join(cwd, MIRROR_PARENT_DIRNAME);
+  const mirrorParent = join(cwd, LOAD_APP_MIRROR_PARENT_DIRNAME);
   cleanupStaleMirrorRoots(mirrorParent);
-  return join(
-    mirrorParent,
-    `${MIRROR_ENTRY_PREFIX}${Date.now()}-${Math.random().toString(36).slice(2)}`
-  );
+  return createLoadAppMirrorRootPath(cwd);
 };
 
 interface MirrorWalkContext {
@@ -383,11 +521,33 @@ const copyDirectoryTreeToMirror = async (
   }
 };
 
+const copyNearestPackageJsonToMirror = async (
+  directoryPath: string,
+  context: MirrorWalkContext
+): Promise<void> => {
+  let current = directoryPath;
+  while (true) {
+    const packagePath = join(current, 'package.json');
+    const packageStat = safeStat(packagePath);
+    if (packageStat?.isFile()) {
+      await copyFileToMirror(packagePath, context.mirrorRoot, context.copied);
+      return;
+    }
+
+    const parent = dirname(current);
+    if (parent === current) {
+      return;
+    }
+    current = parent;
+  }
+};
+
 const mirrorImportedModule = async (
   modulePath: string,
   context: MirrorWalkContext
 ): Promise<void> => {
   const moduleDirectory = dirname(modulePath);
+  await copyNearestPackageJsonToMirror(moduleDirectory, context);
   if (context.visitedDirectories.has(moduleDirectory)) {
     await copyFileToMirror(modulePath, context.mirrorRoot, context.copied);
     return;
@@ -429,7 +589,11 @@ const mirrorFreshImportGraph = async (
   };
 
   await visit(entryPath);
-  return freshMirrorPath(entryPath, mirrorRoot);
+  const freshPath = resolveLoadAppMirrorFilePath(entryPath, mirrorRoot);
+  if (freshPath.isErr()) {
+    throw freshPath.error;
+  }
+  return freshPath.value;
 };
 
 /**
@@ -461,16 +625,16 @@ const prepareMirror = async (
     const freshPath = await mirrorFreshImportGraph(absolutePath, mirrorRoot);
     return { freshPath, mirrorRoot };
   } catch (error) {
-    rmSync(mirrorRoot, { force: true, recursive: true });
+    removeLoadAppMirrorRootQuietly(mirrorRoot);
     throw error;
   }
 };
 
 const importFreshModule = async (
-  modulePath: string,
+  resolvedModulePath: string,
   cwd: string
 ): Promise<Record<string, unknown>> => {
-  const absolutePath = resolveAbsoluteModulePath(modulePath, cwd);
+  const absolutePath = resolvedModulePath;
   if (URL_SCHEME.test(absolutePath) && !absolutePath.startsWith('/')) {
     return await importWithCacheBust(absolutePath);
   }
@@ -491,7 +655,7 @@ const resolveLoadedTopo = (
     | Topo
     | undefined;
   if (!app?.trails) {
-    throw new Error(
+    throw new ValidationError(
       `Could not find a Topo export in "${effectivePath}". ` +
         "Expected a default, 'graph', or 'app' named export created with topo()."
     );
@@ -505,6 +669,12 @@ export interface FreshAppLease {
   readonly release: () => void;
 }
 
+export type LoadAppLeaseOptions = LoadAppTrustOptions;
+
+export interface LoadAppOptions extends LoadAppTrustOptions {
+  readonly fresh?: boolean | undefined;
+}
+
 const noopRelease = (): void => undefined;
 
 const createUrlSchemeLease = async (
@@ -546,26 +716,51 @@ const createFilesystemLease = async (
 
 export const loadFreshAppLease = async (
   modulePath: string | undefined,
-  cwd: string
+  cwd: string,
+  options: LoadAppLeaseOptions = {}
 ): Promise<FreshAppLease> => {
   const effectivePath =
-    modulePath === undefined ? findAppModule(cwd) : modulePath;
-  const absolutePath = resolveAbsoluteModulePath(effectivePath, cwd);
+    modulePath === undefined ? findWorkspaceRelativeAppModule(cwd) : modulePath;
+  const absolutePath = resolveLoadAppModulePath(effectivePath, cwd, options);
 
   return URL_SCHEME.test(absolutePath) && !absolutePath.startsWith('/')
     ? await createUrlSchemeLease(absolutePath, effectivePath)
     : await createFilesystemLease(absolutePath, cwd, effectivePath);
 };
 
-/** Load a Topo export from a module path relative to cwd. */
+export const tryLoadFreshAppLease = async (
+  modulePath: string | undefined,
+  cwd: string,
+  options: LoadAppLeaseOptions = {}
+): Promise<Result<FreshAppLease, Error>> => {
+  try {
+    return Result.ok(await loadFreshAppLease(modulePath, cwd, options));
+  } catch (error) {
+    return Result.err(toLoadAppError(error));
+  }
+};
+
+/**
+ * Load a Topo export from a module path relative to cwd.
+ *
+ * @remarks
+ * By default, `modulePath` must be workspace-relative and stay under `cwd`.
+ * URL-shaped, absolute, and parent-escape paths are rejected. Trusted internal
+ * callers can pass `trustedModulePath: true` to deliberately use the broader
+ * dynamic-import escape hatch.
+ */
 export const loadApp = async (
   modulePath: string | undefined,
   cwd: string,
-  options: { fresh?: boolean | undefined } = {}
+  options: LoadAppOptions = {}
 ): Promise<Topo> => {
   const effectivePath =
-    modulePath === undefined ? findAppModule(cwd) : modulePath;
-  const resolvedModulePath = resolveAbsoluteModulePath(effectivePath, cwd);
+    modulePath === undefined ? findWorkspaceRelativeAppModule(cwd) : modulePath;
+  const resolvedModulePath = resolveLoadAppModulePath(
+    effectivePath,
+    cwd,
+    options
+  );
   const mod =
     options.fresh === true
       ? await importFreshModule(resolvedModulePath, cwd)

package/src/trails/root-dir.ts

@@ -0,0 +1,21 @@
+import { Result, ValidationError } from '@ontrails/core';
+
+const ROOT_DIR_MESSAGE =
+  'Trail execution requires rootDir input or ctx.cwd from the runtime context.';
+
+export const resolveTrailRootDir = (
+  rootDir: string | undefined,
+  cwd: string | undefined
+): Result<string, ValidationError> => {
+  const resolved = rootDir ?? cwd;
+  return resolved === undefined
+    ? Result.err(new ValidationError(ROOT_DIR_MESSAGE))
+    : Result.ok(resolved);
+};
+
+export const requireTrailRootDir = (rootDir: string | undefined): string => {
+  if (rootDir === undefined) {
+    throw new ValidationError(ROOT_DIR_MESSAGE);
+  }
+  return rootDir;
+};