@ontrails/trails 1.0.0-beta.14 → 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,60 +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()
-      .default('./src/app.ts')
-      .describe('Path to the app module'),
+    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'),
     }),
   ]),
 });