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

package/src/trails/guide.ts

@@ -4,11 +4,14 @@
  * Lists trails with descriptions and examples. Detailed guidance is planned for post-v1.
  */
 
-import type { Topo, Trail } from '@ontrails/core';
-import { Result, trail } from '@ontrails/core';
+import { NotFoundError, Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
 import { loadApp } from './load-app.js';
+import {
+  buildCurrentGuideEntries,
+  buildCurrentTopoDetail,
+} from './topo-read-support.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -25,41 +28,36 @@ interface GuideEntry {
 // Helpers
 // ---------------------------------------------------------------------------
 
-const toGuideEntries = (app: Topo): GuideEntry[] => {
-  const entries: GuideEntry[] = [];
-
-  for (const item of app.list()) {
-    const raw = item as unknown as Record<string, unknown>;
-    entries.push({
-      description:
-        typeof raw['description'] === 'string'
-          ? raw['description']
-          : '(no description)',
-      exampleCount: Array.isArray(raw['examples'])
-        ? (raw['examples'] as unknown[]).length
-        : 0,
-      id: item.id,
-      kind: item.kind,
-    });
-  }
-
-  return entries;
-};
+export const guideTrail = trail('guide', {
+  blaze: async (input, ctx) => {
+    const rootDir = ctx.cwd ?? '.';
+    const app = await loadApp(input.module, rootDir);
 
-const toGuideDetail = (item: Trail<unknown, unknown>): object => ({
-  description: item.description ?? null,
-  detours: item.detours ?? null,
-  examples: item.examples ?? [],
-  id: item.id,
-  kind: item.kind,
-});
+    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}`)
+        );
+      }
+      return Result.ok({
+        description: detail.description,
+        detours: detail.detours,
+        examples: detail.examples,
+        id: detail.id,
+        kind: detail.kind,
+      });
+    }
 
-export const guideTrail = trail('guide', {
+    return Result.ok(
+      buildCurrentGuideEntries(app, { rootDir }) as GuideEntry[]
+    );
+  },
   description: 'Runtime guidance for trails',
   examples: [
     {
       description: 'Lists all trails with descriptions and example counts',
-      input: {},
+      input: { module: './src/app.ts' },
       name: 'List trail guidance',
     },
   ],
@@ -88,17 +86,4 @@ export const guideTrail = trail('guide', {
       kind: z.string(),
     }),
   ]),
-  run: async (input, ctx) => {
-    const app = await loadApp(input.module, ctx.cwd ?? '.');
-
-    if (input.trailId) {
-      const item = app.get(input.trailId);
-      if (!item) {
-        return Result.err(new Error(`Trail not found: ${input.trailId}`));
-      }
-      return Result.ok(toGuideDetail(item as Trail<unknown, unknown>));
-    }
-
-    return Result.ok(toGuideEntries(app));
-  },
 });

package/src/trails/load-app.ts

@@ -1,31 +1,94 @@
-import { isAbsolute, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { existsSync, rmSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import type { Topo } from '@ontrails/core';
 
 const URL_SCHEME = /^[a-zA-Z][a-zA-Z\d+.-]*:/;
 
-/** Resolve a module path from cwd so CLI defaults behave like shell paths. */
-const resolveModuleSpecifier = (modulePath: string, cwd: string): string => {
-  if (URL_SCHEME.test(modulePath)) {
-    return modulePath;
-  }
+const resolveUrlModulePath = (modulePath: string): string => {
+  const url = new URL(modulePath);
+  return url.protocol === 'file:' ? fileURLToPath(url) : modulePath;
+};
 
+const resolveFilesystemModulePath = (
+  modulePath: string,
+  cwd: string
+): string => {
   const absolutePath = isAbsolute(modulePath)
     ? modulePath
     : resolve(cwd, modulePath);
-  return pathToFileURL(absolutePath).href;
+  if (!absolutePath.endsWith('.js') || existsSync(absolutePath)) {
+    return absolutePath;
+  }
+
+  const tsPath = absolutePath.replace(/\.js$/, '.ts');
+  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 =>
+  URL_SCHEME.test(modulePath)
+    ? resolveUrlModulePath(modulePath)
+    : resolveFilesystemModulePath(modulePath, cwd);
+
+const freshModuleCopyPath = (absolutePath: string): string =>
+  join(
+    dirname(absolutePath),
+    `.__fresh-${Date.now()}-${Math.random().toString(36).slice(2)}-${basename(absolutePath)}`
+  );
+
+/**
+ * Import a module bypassing the ESM cache for the entry file.
+ *
+ * @remarks
+ * Cache-busting applies to the entry module only. Transitive imports resolved
+ * by the entry file are still served from Bun's module cache. This is
+ * acceptable for the draft promotion workflow (the only caller) because
+ * promotion changes which modules the entry file imports, not the modules
+ * themselves. If a deeper cache-bust is needed in the future, consider
+ * Bun's `Loader.registry` or a full process restart.
+ */
+const importFreshModule = async (
+  modulePath: string,
+  cwd: string
+): Promise<Record<string, unknown>> => {
+  const absolutePath = resolveAbsoluteModulePath(modulePath, cwd);
+  if (URL_SCHEME.test(absolutePath) && !absolutePath.startsWith('/')) {
+    const url = new URL(absolutePath);
+    url.searchParams.set('t', Date.now().toString());
+    return (await import(url.href)) as Record<string, unknown>;
+  }
+
+  const freshPath = freshModuleCopyPath(absolutePath);
+  await Bun.write(freshPath, await Bun.file(absolutePath).text());
+
+  try {
+    return (await import(pathToFileURL(freshPath).href)) as Record<
+      string,
+      unknown
+    >;
+  } finally {
+    rmSync(freshPath, { force: true });
+  }
 };
 
 /** Load a Topo export from a module path relative to cwd. */
 export const loadApp = async (
   modulePath: string,
-  cwd: string
+  cwd: string,
+  options: { fresh?: boolean | undefined } = {}
 ): Promise<Topo> => {
-  const mod = (await import(resolveModuleSpecifier(modulePath, cwd))) as Record<
-    string,
-    unknown
-  >;
+  const resolvedModulePath = resolveAbsoluteModulePath(modulePath, cwd);
+  const mod =
+    options.fresh === true
+      ? await importFreshModule(modulePath, cwd)
+      : ((await import(
+          URL_SCHEME.test(resolvedModulePath) &&
+            !resolvedModulePath.startsWith('/')
+            ? new URL(resolvedModulePath).href
+            : pathToFileURL(resolvedModulePath).href
+        )) as Record<string, unknown>);
   const app = (mod['default'] ?? mod['app']) as Topo | undefined;
   if (!app?.trails) {
     throw new Error(

package/src/trails/project.ts

@@ -5,10 +5,24 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
+import { isDraftMarkedFile } from '@ontrails/warden';
+
 /** Return all TypeScript entries in a project's src directory. */
-const scanSourceEntries = (srcDir: string): string[] => [
-  ...new Bun.Glob('*.ts').scanSync({ cwd: srcDir }),
-];
+const sourceEntryPriority = (entry: string): number => {
+  if (entry === 'app.ts') {
+    return 0;
+  }
+  return isDraftMarkedFile(entry) ? 2 : 1;
+};
+
+const scanSourceEntries = (srcDir: string): string[] =>
+  [...new Bun.Glob('*.ts').scanSync({ cwd: srcDir })].toSorted((a, b) => {
+    const priority = sourceEntryPriority(a) - sourceEntryPriority(b);
+    if (priority === 0) {
+      return a.localeCompare(b);
+    }
+    return priority;
+  });
 
 /** Resolve an entry to an app import if it contains topo(). */
 const toTopoImport = async (