@ontrails/trails 1.0.0-beta.0 → 1.0.0-beta.10

package/src/trails/add-surface.ts

@@ -92,7 +92,15 @@ const writeSurfaceEntry = async (
 
 export const addSurface = trail('add.surface', {
   description: 'Add a surface to an existing project',
-  implementation: async (input) => {
+  input: z.object({
+    dir: z.string().optional().describe('Project directory'),
+    surface: z.enum(['cli', 'mcp']).describe('Surface to add'),
+  }),
+  output: z.object({
+    created: z.string(),
+    dependency: z.string(),
+  }),
+  run: async (input) => {
     const cwd = resolve(input.dir ?? '.');
     const { surface } = input;
     const entryFile = getEntryFile(surface);
@@ -108,12 +116,4 @@ export const addSurface = trail('add.surface', {
       dependency: await updatePkgJsonForSurface(cwd, surface),
     });
   },
-  input: z.object({
-    dir: z.string().optional().describe('Project directory'),
-    surface: z.enum(['cli', 'mcp']).describe('Surface to add'),
-  }),
-  output: z.object({
-    created: z.string(),
-    dependency: z.string(),
-  }),
 });

package/src/trails/add-trail.ts

@@ -14,17 +14,9 @@ import { z } from 'zod';
 
 const generateTrailFile = (
   id: string,
-  readOnly: boolean,
-  destructive: boolean
+  intent: 'read' | 'write' | 'destroy'
 ): string => {
-  const markers: string[] = [];
-  if (readOnly) {
-    markers.push('  readOnly: true,');
-  }
-  if (destructive) {
-    markers.push('  destructive: true,');
-  }
-  const markerBlock = markers.length > 0 ? `\n${markers.join('\n')}` : '';
+  const intentLine = intent === 'write' ? '' : `\n  intent: '${intent}',`;
 
   return `import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
@@ -37,10 +29,10 @@ export const ${id.replaceAll('.', '_')} = trail('${id}', {
       name: 'TODO: add example',
     },
   ],
-  implementation: async (input) => {
+  run: async (input) => {
     return Result.ok({ message: 'TODO' });
   },
-  input: z.object({}),${markerBlock}
+  input: z.object({}),${intentLine}
   output: z.object({ message: z.string() }),
 });
 `;
@@ -73,16 +65,23 @@ const writeWithDirs = async (
 
 export const addTrail = trail('add.trail', {
   description: 'Scaffold a new trail with tests and examples',
-  implementation: async (input, ctx) => {
+  input: z.object({
+    id: z.string().describe('Trail ID (e.g., entity.update)'),
+    intent: z
+      .enum(['read', 'write', 'destroy'])
+      .default('write')
+      .describe('Trail intent'),
+  }),
+  output: z.object({
+    created: z.array(z.string()),
+  }),
+  run: async (input, ctx) => {
     const { id } = input;
     const moduleName = id.replaceAll('.', '-');
     const cwd = resolve(ctx.cwd ?? '.');
 
     const files = new Map<string, string>([
-      [
-        `src/trails/${moduleName}.ts`,
-        generateTrailFile(id, input.readOnly, input.destructive),
-      ],
+      [`src/trails/${moduleName}.ts`, generateTrailFile(id, input.intent)],
       [`__tests__/${moduleName}.test.ts`, generateTestFile(id)],
     ]);
 
@@ -92,12 +91,4 @@ export const addTrail = trail('add.trail', {
 
     return Result.ok({ created: [...files.keys()] });
   },
-  input: z.object({
-    destructive: z.boolean().default(false).describe('Destructive trail'),
-    id: z.string().describe('Trail ID (e.g., entity.update)'),
-    readOnly: z.boolean().default(false).describe('Read-only trail'),
-  }),
-  output: z.object({
-    created: z.array(z.string()),
-  }),
 });

package/src/trails/add-verify.ts

@@ -56,7 +56,15 @@ const updatePackageJsonForVerify = async (
 
 export const addVerify = trail('add.verify', {
   description: 'Add testing and warden verification',
-  implementation: async (input) => {
+  input: z.object({
+    dir: z.string().optional().describe('Parent directory'),
+    name: z.string().describe('Project name'),
+  }),
+  metadata: { internal: true },
+  output: z.object({
+    created: z.array(z.string()),
+  }),
+  run: async (input) => {
     const projectDir = resolve(input.dir ?? '.', input.name);
     const files: string[] = [];
 
@@ -76,12 +84,4 @@ export const addVerify = trail('add.verify', {
 
     return Result.ok({ created: files });
   },
-  input: z.object({
-    dir: z.string().optional().describe('Parent directory'),
-    name: z.string().describe('Project name'),
-  }),
-  markers: { internal: true },
-  output: z.object({
-    created: z.array(z.string()),
-  }),
 });

package/src/trails/create-scaffold.ts

@@ -107,7 +107,7 @@ export const hello = trail('hello', {
       name: 'Named greeting',
     },
   ],
-  implementation: (input) => {
+  run: (input) => {
     const name = input.name ?? 'world';
     return Result.ok({ message: \`Hello, \${name}!\` });
   },
@@ -117,7 +117,7 @@ export const hello = trail('hello', {
   output: z.object({
     message: z.string(),
   }),
-  readOnly: true,
+  intent: 'read',
 });
 `;
 
@@ -139,12 +139,12 @@ export const show = trail('entity.show', {
       name: 'Show entity',
     },
   ],
-  implementation: (input) => {
+  run: (input) => {
     return Result.ok({ id: input.id, name: 'Example' });
   },
   input: z.object({ id: z.string() }),
   output: entitySchema,
-  readOnly: true,
+  intent: 'read',
 });
 
 export const add = trail('entity.add', {
@@ -156,7 +156,7 @@ export const add = trail('entity.add', {
       name: 'Add entity',
     },
   ],
-  implementation: (input) => {
+  run: (input) => {
     return Result.ok({ id: '1', name: input.name });
   },
   input: z.object({ name: z.string() }),
@@ -177,25 +177,25 @@ export const search = trail('search', {
       name: 'Search entities',
     },
   ],
-  implementation: () => {
+  run: () => {
     return Result.ok({ results: [] });
   },
   input: z.object({ query: z.string() }),
   output: z.object({
     results: z.array(z.object({ id: z.string(), name: z.string() })),
   }),
-  readOnly: true,
+  intent: 'read',
 });
 `;
 
-const generateOnboardHike = (): string =>
-  `import { Result, hike } from '@ontrails/core';
+const generateOnboardTrail = (): string =>
+  `import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
-export const onboard = hike('entity.onboard', {
+export const onboard = trail('entity.onboard', {
   description: 'Onboard a new entity end-to-end',
-  follows: ['entity.add'],
-  implementation: async (input, ctx) => {
+  follow: ['entity.add'],
+  run: async (input, ctx) => {
     const result = await ctx.follow('entity.add', { name: input.name });
     if (result.isErr()) {
       return result;
@@ -281,7 +281,7 @@ const starterFileGenerators: Record<Starter, () => [string, string][]> = {
   entity: () => [
     ['src/trails/entity.ts', generateEntityTrails()],
     ['src/trails/search.ts', generateSearchTrail()],
-    ['src/trails/onboard.ts', generateOnboardHike()],
+    ['src/trails/onboard.ts', generateOnboardTrail()],
     ['src/events/entity-events.ts', generateEntityEvents()],
     ['src/store.ts', generateStore()],
   ],
@@ -322,19 +322,6 @@ const writeScaffoldFiles = async (
 
 export const createScaffold = trail('create.scaffold', {
   description: 'Scaffold a new Trails project',
-  implementation: async (input) => {
-    const projectDir = resolve(input.dir ?? '.', input.name);
-    const starter = (input.starter ?? 'hello') as Starter;
-    const fileMap = collectScaffoldFiles(input.name, starter);
-    const files = await writeScaffoldFiles(projectDir, fileMap);
-    mkdirSync(join(projectDir, '.trails'), { recursive: true });
-
-    return Result.ok({
-      created: files,
-      dir: projectDir,
-      name: input.name,
-    } satisfies ScaffoldResult);
-  },
   input: z.object({
     dir: z.string().optional().describe('Parent directory'),
     name: z.string().describe('Project name'),
@@ -343,10 +330,23 @@ export const createScaffold = trail('create.scaffold', {
       .default('hello')
       .describe('Starter trail'),
   }),
-  markers: { internal: true },
+  metadata: { internal: true },
   output: z.object({
     created: z.array(z.string()),
     dir: z.string(),
     name: z.string(),
   }),
+  run: async (input) => {
+    const projectDir = resolve(input.dir ?? '.', input.name);
+    const starter = (input.starter ?? 'hello') as Starter;
+    const fileMap = collectScaffoldFiles(input.name, starter);
+    const files = await writeScaffoldFiles(projectDir, fileMap);
+    mkdirSync(join(projectDir, '.trails'), { recursive: true });
+
+    return Result.ok({
+      created: files,
+      dir: projectDir,
+      name: input.name,
+    } satisfies ScaffoldResult);
+  },
 });

package/src/trails/create.ts

@@ -6,7 +6,7 @@
  */
 
 import type { FollowFn } from '@ontrails/core';
-import { Result, hike } from '@ontrails/core';
+import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
 // ---------------------------------------------------------------------------
@@ -146,7 +146,7 @@ const runCreate = async (
 // Route definition
 // ---------------------------------------------------------------------------
 
-export const createRoute = hike('create', {
+export const createRoute = trail('create', {
   description: 'Create a new Trails project',
   fields: {
     starter: {
@@ -157,7 +157,7 @@ export const createRoute = hike('create', {
           value: 'hello',
         },
         {
-          hint: '4 trails, hike, event, store',
+          hint: '4 trails, event, store',
           label: 'Entity CRUD',
           value: 'entity',
         },
@@ -175,13 +175,7 @@ export const createRoute = hike('create', {
       ],
     },
   },
-  follows: ['create.scaffold', 'add.surface', 'add.verify'],
-  implementation: async (input: BlazeInput, ctx) => {
-    if (!ctx.follow) {
-      return Result.err(new Error('create route requires ctx.follow'));
-    }
-    return await runCreate(ctx.follow, input);
-  },
+  follow: ['create.scaffold', 'add.surface', 'add.verify'],
   input: z.object({
     dir: z.string().optional().describe('Parent directory'),
     name: z.string().describe('Project name'),
@@ -200,4 +194,10 @@ export const createRoute = hike('create', {
     dir: z.string(),
     name: z.string(),
   }),
+  run: async (input: BlazeInput, ctx) => {
+    if (!ctx.follow) {
+      return Result.err(new Error('create route requires ctx.follow'));
+    }
+    return await runCreate(ctx.follow, input);
+  },
 });

package/src/trails/guide.ts

@@ -63,19 +63,6 @@ export const guideTrail = trail('guide', {
       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()
@@ -83,6 +70,7 @@ export const guideTrail = trail('guide', {
       .describe('Path to the app module'),
     trailId: z.string().optional().describe('Trail ID for detailed guidance'),
   }),
+  intent: 'read',
   output: z.union([
     z.array(
       z.object({
@@ -100,5 +88,17 @@ export const guideTrail = trail('guide', {
       kind: z.string(),
     }),
   ]),
-  readOnly: true,
+  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/survey.ts

@@ -10,6 +10,7 @@ import { Result, trail } from '@ontrails/core';
 import type { DiffResult } from '@ontrails/schema';
 import {
   diffSurfaceMaps,
+  generateOpenApiSpec,
   generateSurfaceMap,
   hashSurfaceMap,
   readSurfaceMap,
@@ -32,11 +33,9 @@ export interface BriefReport {
     readonly outputSchemas: boolean;
     readonly examples: boolean;
     readonly detours: boolean;
-    readonly hikes: boolean;
     readonly events: boolean;
   };
   readonly trails: number;
-  readonly hikes: number;
   readonly events: number;
 }
 
@@ -73,10 +72,8 @@ export const generateBriefReport = (app: Topo): BriefReport => {
       detours: hasDetours,
       events: app.events.size > 0,
       examples: hasExamples,
-      hikes: app.hikes.size > 0,
       outputSchemas: hasOutputSchemas,
     },
-    hikes: app.hikes.size,
     name: app.name,
     trails: app.trails.size,
     version: '0.1.0',
@@ -88,14 +85,13 @@ export const generateBriefReport = (app: Topo): BriefReport => {
 // ---------------------------------------------------------------------------
 
 const safetyLabel = (entry: {
-  readOnly?: boolean;
-  destructive?: boolean;
+  intent?: 'read' | 'write' | 'destroy';
 }): string => {
-  if (entry.destructive) {
-    return 'destructive';
+  if (entry.intent === 'destroy') {
+    return 'destroy';
   }
-  if (entry.readOnly) {
-    return 'readOnly';
+  if (entry.intent === 'read') {
+    return 'read';
   }
   return '-';
 };
@@ -104,7 +100,7 @@ const formatTrailList = (app: Topo): object => {
   const items = app.list();
   const entries = items.map((item) => {
     const safety = safetyLabel(
-      item as unknown as { readOnly?: boolean; destructive?: boolean }
+      item as unknown as { intent?: 'read' | 'write' | 'destroy' }
     );
     const examples = Array.isArray(
       (item as unknown as { examples?: unknown[] }).examples
@@ -132,7 +128,7 @@ const formatTrailList = (app: Topo): object => {
  */
 const formatTrailDetail = (item: Trail<unknown, unknown>): object => {
   const safety = safetyLabel(
-    item as unknown as { readOnly?: boolean; destructive?: boolean }
+    item as unknown as { intent?: 'read' | 'write' | 'destroy' }
   );
 
   return {
@@ -200,6 +196,55 @@ const buildSurveyGenerate = async (
   return Result.ok({ hash, lockPath, mapPath });
 };
 
+interface SurveyInput {
+  breakingOnly: boolean;
+  brief: boolean;
+  diff?: string | undefined;
+  generate: boolean;
+  openapi: boolean;
+  trailId?: string | undefined;
+}
+
+type SurveyMode = 'brief' | 'detail' | 'diff' | 'generate' | 'list' | 'openapi';
+
+/** Ordered mode checks — first truthy predicate wins, otherwise 'list'. */
+const modeChecks: readonly [(input: SurveyInput) => boolean, SurveyMode][] = [
+  [(i) => i.brief, 'brief'],
+  [(i) => Boolean(i.diff), 'diff'],
+  [(i) => Boolean(i.trailId), 'detail'],
+  [(i) => i.generate, 'generate'],
+  [(i) => i.openapi, 'openapi'],
+];
+
+/** Determine which survey mode was requested, falling back to 'list'. */
+const resolveSurveyMode = (input: SurveyInput): SurveyMode =>
+  modeChecks.find(([predicate]) => predicate(input))?.[1] ?? 'list';
+
+type SurveyHandler = (
+  app: Topo,
+  input: SurveyInput
+) => Result<object, Error> | Promise<Result<object, Error>>;
+
+/** Handlers keyed by survey mode. */
+const surveyHandlers: Record<SurveyMode, SurveyHandler> = {
+  brief: (app) => Result.ok(generateBriefReport(app)),
+  detail: (app, input) => buildSurveyDetail(app, input.trailId ?? ''),
+  diff: (app, input) => buildSurveyDiff(app, input.breakingOnly),
+  generate: (app) => buildSurveyGenerate(app),
+  list: (app) => Result.ok(formatTrailList(app)),
+  openapi: (app) => Result.ok(generateOpenApiSpec(app)),
+};
+
+/** Dispatch to the appropriate survey sub-command based on input flags. */
+const dispatchSurvey = (
+  app: Topo,
+  input: SurveyInput
+): Result<object, Error> | Promise<Result<object, Error>> => {
+  const mode = resolveSurveyMode(input);
+  const handler = surveyHandlers[mode];
+  return handler(app, input);
+};
+
 // ---------------------------------------------------------------------------
 // Trail definition
 // ---------------------------------------------------------------------------
@@ -217,28 +262,12 @@ export const surveyTrail = trail('survey', {
       input: { brief: true },
       name: 'Brief capability report',
     },
+    {
+      description: 'Generate an OpenAPI 3.1 specification for the topo',
+      input: { openapi: true },
+      name: 'OpenAPI spec',
+    },
   ],
-  implementation: async (input, ctx) => {
-    const app = await loadApp(input.module, ctx.cwd ?? '.');
-
-    if (input.brief) {
-      return Result.ok(generateBriefReport(app));
-    }
-
-    if (input.diff) {
-      return await buildSurveyDiff(app, input.breakingOnly);
-    }
-
-    if (input.trailId) {
-      return buildSurveyDetail(app, input.trailId);
-    }
-
-    if (input.generate) {
-      return await buildSurveyGenerate(app);
-    }
-
-    return Result.ok(formatTrailList(app));
-  },
   input: z.object({
     breakingOnly: z
       .boolean()
@@ -254,8 +283,10 @@ export const surveyTrail = trail('survey', {
       .string()
       .default('./src/app.ts')
       .describe('Path to the app module'),
+    openapi: z.boolean().default(false).describe('Output OpenAPI 3.1 spec'),
     trailId: z.string().optional().describe('Trail ID for detail view'),
   }),
+  intent: 'read',
   output: z.union([
     z.object({
       count: z.number(),
@@ -275,10 +306,8 @@ export const surveyTrail = trail('survey', {
         detours: z.boolean(),
         events: z.boolean(),
         examples: z.boolean(),
-        hikes: z.boolean(),
         outputSchemas: z.boolean(),
       }),
-      hikes: z.number(),
       name: z.string(),
       trails: z.number(),
       version: z.string(),
@@ -302,6 +331,29 @@ export const surveyTrail = trail('survey', {
       lockPath: z.string(),
       mapPath: z.string(),
     }),
+    z.object({
+      components: z.object({
+        schemas: z.record(z.string(), z.unknown()),
+      }),
+      info: z.object({
+        description: z.string().optional(),
+        title: z.string(),
+        version: z.string(),
+      }),
+      openapi: z.literal('3.1.0'),
+      paths: z.record(z.string(), z.record(z.string(), z.unknown())),
+      servers: z
+        .array(
+          z.object({
+            description: z.string().optional(),
+            url: z.string(),
+          })
+        )
+        .optional(),
+    }),
   ]),
-  readOnly: true,
+  run: async (input, ctx) => {
+    const app = await loadApp(input.module, ctx.cwd ?? '.');
+    return dispatchSurvey(app, input);
+  },
 });

package/src/trails/warden.ts

@@ -37,38 +37,6 @@ export const wardenTrail = trail('warden', {
       name: 'GitHub Actions annotations',
     },
   ],
-  implementation: async (input, ctx) => {
-    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
-    // oxlint-disable-next-line prefer-await-to-then -- catch converts rejection to undefined cleanly
-    const topo = await loadApp('./src/app.ts', rootDir).catch(
-      (): undefined => undefined
-    );
-
-    const report = await runWarden({
-      driftOnly: input.driftOnly,
-      lintOnly: input.lintOnly,
-      rootDir,
-      topo,
-    });
-
-    const formatters: Record<string, (r: typeof report) => string> = {
-      github: formatGitHubAnnotations,
-      json: formatJson,
-      summary: formatSummary,
-      text: formatWardenReport,
-    };
-    const formatter = formatters[input.format] ?? formatWardenReport;
-    const formatted = formatter(report);
-
-    return Result.ok({
-      diagnostics: report.diagnostics,
-      drift: report.drift,
-      errorCount: report.errorCount,
-      formatted,
-      passed: report.passed,
-      warnCount: report.warnCount,
-    });
-  },
   input: z.object({
     driftOnly: z.boolean().default(false).describe('Only run drift detection'),
     format: z
@@ -78,6 +46,7 @@ export const wardenTrail = trail('warden', {
     lintOnly: z.boolean().default(false).describe('Only run lint rules'),
     rootDir: z.string().optional().describe('Root directory to scan'),
   }),
+  intent: 'read',
   output: z.object({
     diagnostics: z.array(
       z.object({
@@ -100,5 +69,36 @@ export const wardenTrail = trail('warden', {
     passed: z.boolean(),
     warnCount: z.number(),
   }),
-  readOnly: true,
+  run: async (input, ctx) => {
+    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    // oxlint-disable-next-line prefer-await-to-then -- catch converts rejection to undefined cleanly
+    const topo = await loadApp('./src/app.ts', rootDir).catch(
+      (): undefined => undefined
+    );
+
+    const report = await runWarden({
+      driftOnly: input.driftOnly,
+      lintOnly: input.lintOnly,
+      rootDir,
+      topo,
+    });
+
+    const formatters: Record<string, (r: typeof report) => string> = {
+      github: formatGitHubAnnotations,
+      json: formatJson,
+      summary: formatSummary,
+      text: formatWardenReport,
+    };
+    const formatter = formatters[input.format] ?? formatWardenReport;
+    const formatted = formatter(report);
+
+    return Result.ok({
+      diagnostics: report.diagnostics,
+      drift: report.drift,
+      errorCount: report.errorCount,
+      formatted,
+      passed: report.passed,
+      warnCount: report.warnCount,
+    });
+  },
 });