@ontrails/trails 1.0.0-beta.3 → 1.0.0-beta.32

package/src/trails/guide.ts

@@ -4,11 +4,17 @@
  * 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 { withFreshOperatorApp } from './operator-context.js';
+import { trailDetailOutput } from './topo-output-schemas.js';
+import {
+  deriveCurrentGuideEntries,
+  deriveCurrentTopoDetail,
+  readSurfaceLayerNamesFromContext,
+} from './topo-read-support.js';
+import { createIsolatedExampleInput } from './topo-support.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -18,87 +24,83 @@ interface GuideEntry {
   readonly description: string;
   readonly exampleCount: number;
   readonly id: string;
-  readonly kind: string;
+  readonly kind: 'trail';
 }
 
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-const toGuideEntries = (app: Topo): GuideEntry[] => {
-  const entries: GuideEntry[] = [];
+type GuideTrailOutput =
+  | {
+      readonly entries: GuideEntry[];
+      readonly mode: 'list';
+    }
+  | {
+      readonly detail: z.output<typeof trailDetailOutput>;
+      readonly mode: 'detail';
+    };
 
-  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,
-    });
-  }
+const guideTrailInputSchema = 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'),
+});
 
-  return entries;
-};
+type GuideTrailInput = z.output<typeof guideTrailInputSchema>;
 
-const toGuideDetail = (item: Trail<unknown, unknown>): object => ({
-  description: item.description ?? null,
-  detours: item.detours ?? null,
-  examples: item.examples ?? [],
-  id: item.id,
-  kind: item.kind,
-});
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
 
 export const guideTrail = trail('guide', {
+  blaze: async (input: GuideTrailInput, ctx) =>
+    withFreshOperatorApp<GuideTrailOutput>(input, ctx, ({ lease, rootDir }) => {
+      if (input.trailId) {
+        const detail = deriveCurrentTopoDetail(lease.app, input.trailId, {
+          cliAliases: lease.cliAliases,
+          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({
+        entries: deriveCurrentGuideEntries(lease.app, {
+          rootDir,
+        }) as GuideEntry[],
+        mode: 'list' as const,
+      });
+    }),
   description: 'Runtime guidance for trails',
   examples: [
     {
       description: 'Lists all trails with descriptions and example counts',
-      input: {},
+      input: createIsolatedExampleInput('guide-list'),
       name: 'List trail guidance',
     },
   ],
-  implementation: 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));
-  },
-  input: z.object({
-    module: z
-      .string()
-      .default('./src/app.ts')
-      .describe('Path to the app module'),
-    trailId: z.string().optional().describe('Trail ID for detailed guidance'),
-  }),
-  output: z.union([
-    z.array(
-      z.object({
-        description: z.string(),
-        exampleCount: z.number(),
-        id: z.string(),
-        kind: z.string(),
-      })
-    ),
+  input: guideTrailInputSchema,
+  intent: 'read',
+  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'),
     }),
   ]),
-  readOnly: true,
 });