@ontrails/trails 1.0.0-beta.1 → 1.0.0-beta.11

package/src/__tests__/create.test.ts

@@ -74,13 +74,13 @@ const runFollow = async (
 ): Promise<Result<unknown, Error>> => {
   switch (id) {
     case 'create.scaffold': {
-      return await createScaffold.implementation(input as never, {} as never);
+      return await createScaffold.run(input as never, {} as never);
     }
     case 'add.surface': {
-      return await addSurface.implementation(input as never, {} as never);
+      return await addSurface.run(input as never, {} as never);
     }
     case 'add.verify': {
-      return await addVerify.implementation(input as never, {} as never);
+      return await addVerify.run(input as never, {} as never);
     }
     default: {
       return Result.err(new Error(`Unknown follow target: ${id}`));
@@ -96,7 +96,7 @@ const runBlaze = (
     verify: boolean;
   }>
 ) =>
-  createRoute.implementation(
+  createRoute.run(
     {
       dir: dirname(projectDir),
       name: basename(projectDir),
@@ -199,7 +199,7 @@ const assertEntityStarter = (dir: string): void => {
     'return Result.ok({ results: [] })',
   ]);
   expectContainsAll(readText(dir, 'src/trails/onboard.ts'), [
-    "import { Result, hike } from '@ontrails/core'",
+    "import { Result, trail } from '@ontrails/core'",
     'return Result.ok({ onboarded: true })',
   ]);
 };
@@ -289,7 +289,7 @@ describe('trails blaze', () => {
       await withTempProject(async (dir) => {
         setupMinimalProject(dir);
         const result = expectOk(
-          await addSurface.implementation({ dir, surface: 'mcp' }, {} as never)
+          await addSurface.run({ dir, surface: 'mcp' }, {} as never)
         );
 
         expect(result.created).toBe('src/mcp.ts');
@@ -313,7 +313,7 @@ describe('trails blaze', () => {
         writeFileSync(join(dir, 'src', 'mcp.ts'), 'existing content');
 
         const error = expectErr(
-          await addSurface.implementation({ dir, surface: 'mcp' }, {} as never)
+          await addSurface.run({ dir, surface: 'mcp' }, {} as never)
         );
         expect(error.message).toBe('MCP is already blazed. Nothing to do.');
       });

package/src/__tests__/guide.test.ts

@@ -25,13 +25,13 @@ const helloTrail = trail('hello', {
       name: 'Named greeting',
     },
   ],
-  implementation: (input) => {
+  input: z.object({ name: z.string().optional() }),
+  intent: 'read',
+  output: z.object({ message: z.string() }),
+  run: (input) => {
     const name = input.name ?? 'world';
     return Result.ok({ message: `Hello, ${name}!` });
   },
-  input: z.object({ name: z.string().optional() }),
-  output: z.object({ message: z.string() }),
-  readOnly: true,
 });
 
 const app = topo('test-app', { hello: helloTrail });

package/src/__tests__/survey.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test';
 
-import { topo, trail, Result } from '@ontrails/core';
+import { Result, service, topo, trail } from '@ontrails/core';
 import {
   generateSurfaceMap,
   hashSurfaceMap,
@@ -9,8 +9,16 @@ import {
 import type { SurfaceMap } from '@ontrails/schema';
 import { z } from 'zod';
 
-import { generateBriefReport } from '../trails/survey.js';
-import type { BriefReport } from '../trails/survey.js';
+import {
+  generateBriefReport,
+  generateSurveyList,
+  generateTrailDetail,
+} from '../trails/survey.js';
+import type {
+  BriefReport,
+  SurveyListReport,
+  TrailDetailReport,
+} from '../trails/survey.js';
 
 // ---------------------------------------------------------------------------
 // Test fixtures
@@ -28,23 +36,37 @@ const helloTrail = trail('hello', {
       name: 'Default greeting',
     },
   ],
-  implementation: (input) => {
+  input: z.object({ name: z.string().optional() }),
+  intent: 'read',
+  output: z.object({ message: z.string() }),
+  run: (input) => {
     const name = input.name ?? 'world';
     return Result.ok({ message: `Hello, ${name}!` });
   },
-  input: z.object({ name: z.string().optional() }),
-  output: z.object({ message: z.string() }),
-  readOnly: true,
+  services: [
+    service('db.main', {
+      create: () => Result.ok({ source: 'factory' }),
+    }),
+  ],
 });
 
 const byeTrail = trail('bye', {
   description: 'Say goodbye',
-  implementation: (input) => Result.ok({ message: `Goodbye, ${input.name}!` }),
   input: z.object({ name: z.string() }),
   output: z.object({ message: z.string() }),
+  run: (input) => Result.ok({ message: `Goodbye, ${input.name}!` }),
 });
 
-const app = topo('test-app', { bye: byeTrail, hello: helloTrail });
+const [dbService] = helloTrail.services;
+if (!dbService) {
+  throw new Error('Expected helloTrail to declare db.main');
+}
+
+const app = topo('test-app', {
+  bye: byeTrail,
+  dbService,
+  hello: helloTrail,
+});
 
 // ---------------------------------------------------------------------------
 // Tests
@@ -53,10 +75,11 @@ const app = topo('test-app', { bye: byeTrail, hello: helloTrail });
 describe('trails survey', () => {
   test('generateSurfaceMap includes all trails', () => {
     const surfaceMap = generateSurfaceMap(app);
-    expect(surfaceMap.entries.length).toBe(2);
+    expect(surfaceMap.entries.length).toBe(3);
     const ids = surfaceMap.entries.map((e) => e.id);
     expect(ids).toContain('hello');
     expect(ids).toContain('bye');
+    expect(ids).toContain('db.main');
   });
 
   test('surface map entries have expected fields', () => {
@@ -64,8 +87,9 @@ describe('trails survey', () => {
     const hello = surfaceMap.entries.find((e) => e.id === 'hello');
     expect(hello).toBeDefined();
     expect(hello?.kind).toBe('trail');
-    expect(hello?.readOnly).toBe(true);
+    expect(hello?.intent).toBe('read');
     expect(hello?.exampleCount).toBe(1);
+    expect(hello?.services).toEqual(['db.main']);
   });
 
   test('JSON output is valid JSON', () => {
@@ -73,7 +97,7 @@ describe('trails survey', () => {
     const json = JSON.stringify(surfaceMap, null, 2);
     const parsed = JSON.parse(json) as SurfaceMap;
     expect(parsed.version).toBe('1.0');
-    expect(parsed.entries.length).toBe(2);
+    expect(parsed.entries.length).toBe(3);
   });
 
   test('hashSurfaceMap produces stable hash', () => {
@@ -129,8 +153,8 @@ describe('trails survey --brief', () => {
   test('report includes correct trail count', () => {
     const report = generateBriefReport(app);
     expect(report.trails).toBe(2);
-    expect(report.hikes).toBe(0);
     expect(report.events).toBe(0);
+    expect(report.services).toBe(1);
   });
 
   test('detects features in use', () => {
@@ -138,8 +162,8 @@ describe('trails survey --brief', () => {
     expect(report.features.outputSchemas).toBe(true);
     expect(report.features.examples).toBe(true);
     expect(report.features.detours).toBe(true);
-    expect(report.features.hikes).toBe(false);
     expect(report.features.events).toBe(false);
+    expect(report.features.services).toBe(true);
   });
 
   test('JSON output is valid', () => {
@@ -148,6 +172,7 @@ describe('trails survey --brief', () => {
     const parsed = JSON.parse(json) as BriefReport;
     expect(parsed.name).toBe('test-app');
     expect(parsed.trails).toBe(2);
+    expect(parsed.services).toBe(1);
   });
 
   test('empty app reports zero features', () => {
@@ -157,5 +182,35 @@ describe('trails survey --brief', () => {
     expect(report.features.outputSchemas).toBe(false);
     expect(report.features.examples).toBe(false);
     expect(report.features.detours).toBe(false);
+    expect(report.features.services).toBe(false);
+  });
+});
+
+describe('trails survey detail', () => {
+  test('trail detail includes declared services, follow, and intent', () => {
+    const detail = generateTrailDetail(helloTrail);
+    const parsed = structuredClone(detail) as TrailDetailReport;
+
+    expect(parsed.follow).toEqual([]);
+    expect(parsed.intent).toBe('read');
+    expect(parsed.services).toEqual(['db.main']);
+  });
+});
+
+describe('trails survey services section', () => {
+  test('list output includes service lifetime and health status', () => {
+    const report = generateSurveyList(app);
+    const parsed = structuredClone(report) as SurveyListReport;
+    const db = parsed.services.find((entry) => entry.id === 'db.main');
+
+    expect(parsed.serviceCount).toBe(1);
+    expect(db).toEqual({
+      description: null,
+      health: 'none',
+      id: 'db.main',
+      kind: 'service',
+      lifetime: 'singleton',
+      usedBy: ['hello'],
+    });
   });
 });

package/src/__tests__/warden.test.ts

@@ -21,7 +21,7 @@ describe('trails warden', () => {
       writeFileSync(
         join(dir, 'good.ts'),
         `trail("hello", {
-  implementation: async (input, ctx) => {
+  run: async (input, ctx) => {
     return Result.ok({ message: "hi" });
   }
 })`
@@ -54,7 +54,7 @@ describe('trails warden', () => {
       writeFileSync(
         join(dir, 'bad.ts'),
         `trail("x", {
-  implementation: async () => { throw new Error("boom"); }
+  run: async () => { throw new Error("boom"); }
 })`
       );
       const report = await runWarden({ driftOnly: true, rootDir: dir });

package/src/clack.ts

@@ -55,8 +55,30 @@ const fieldResolvers: Record<Field['type'], FieldResolver> = {
     const raw = await clack.text({ message: field.label });
     return clack.isCancel(raw) ? undefined : Number(raw);
   },
+  'number[]': async (field) => {
+    const raw = await clack.text({
+      message: `${field.label} (comma-separated numbers)`,
+    });
+    if (clack.isCancel(raw)) {
+      return;
+    }
+    return String(raw)
+      .split(',')
+      .map((s) => Number(s.trim()));
+  },
   string: async (field) =>
     cancelable(await clack.text({ message: field.label })),
+  'string[]': async (field) => {
+    const raw = await clack.text({
+      message: `${field.label} (comma-separated)`,
+    });
+    if (clack.isCancel(raw)) {
+      return;
+    }
+    return String(raw)
+      .split(',')
+      .map((s) => s.trim());
+  },
 };
 
 /** Resolve a single field value with Clack. */

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));
+  },
 });