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

package/src/trails/{add-surface.ts → add-trailhead.ts}

@@ -1,5 +1,5 @@
 /**
- * `add.surface` trail -- Add a surface to an existing project.
+ * `add.trailhead` trail -- Add a trailhead to an existing project.
  *
  * Generates the CLI or MCP entry point and updates package.json dependencies.
  */
@@ -13,24 +13,24 @@ import { z } from 'zod';
 import { findTopoPath } from './project.js';
 
 const generateCliEntry = (appImportPath: string): string =>
-  `import { blaze } from '@ontrails/cli/commander';
+  `import { trailhead } from '@ontrails/cli/commander';
 
 import { app } from '${appImportPath}';
 
-blaze(app);
+trailhead(app);
 `;
 
 const generateMcpEntry = (appImportPath: string): string =>
-  `import { blaze } from '@ontrails/mcp';
+  `import { trailhead } from '@ontrails/mcp';
 
 import { app } from '${appImportPath}';
 
-await blaze(app);
+await trailhead(app);
 `;
 
-/** Resolve the entry file for a surface. */
-const getEntryFile = (surface: 'cli' | 'mcp'): string =>
-  surface === 'cli' ? 'src/cli.ts' : 'src/mcp.ts';
+/** Resolve the entry file for a trailhead. */
+const getEntryFile = (trailhead: 'cli' | 'mcp'): string =>
+  trailhead === 'cli' ? 'src/cli.ts' : 'src/mcp.ts';
 
 // ---------------------------------------------------------------------------
 // Trail definition
@@ -39,13 +39,13 @@ const getEntryFile = (surface: 'cli' | 'mcp'): string =>
 /** Patch deps and optionally bin in a parsed package.json. */
 const patchPkgDeps = (
   pkg: Record<string, unknown>,
-  surface: 'cli' | 'mcp',
+  trailhead: 'cli' | 'mcp',
   cwd: string
 ): string => {
-  const depName = surface === 'cli' ? '@ontrails/cli' : '@ontrails/mcp';
+  const depName = trailhead === 'cli' ? '@ontrails/cli' : '@ontrails/mcp';
   const deps = (pkg['dependencies'] ?? {}) as Record<string, string>;
   deps[depName] = 'workspace:*';
-  if (surface === 'cli') {
+  if (trailhead === 'cli') {
     deps['commander'] = '^14.0.0';
     pkg['bin'] = {
       [(pkg['name'] as string | undefined) ?? basename(cwd)]: './src/cli.ts',
@@ -57,31 +57,31 @@ const patchPkgDeps = (
   return depName;
 };
 
-/** Update package.json with surface dependency and CLI bin if needed. */
-const updatePkgJsonForSurface = async (
+/** Update package.json with trailhead dependency and CLI bin if needed. */
+const updatePkgJsonForTrailhead = async (
   cwd: string,
-  surface: 'cli' | 'mcp'
+  trailhead: 'cli' | 'mcp'
 ): Promise<string> => {
   const pkgPath = join(cwd, 'package.json');
   if (!existsSync(pkgPath)) {
-    return surface === 'cli' ? '@ontrails/cli' : '@ontrails/mcp';
+    return trailhead === 'cli' ? '@ontrails/cli' : '@ontrails/mcp';
   }
   const pkg = (await Bun.file(pkgPath).json()) as Record<string, unknown>;
-  const depName = patchPkgDeps(pkg, surface, cwd);
+  const depName = patchPkgDeps(pkg, trailhead, cwd);
   await Bun.write(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
   return depName;
 };
 
-/** Create the entry file for a surface and return the relative path. */
-const writeSurfaceEntry = async (
+/** Create the entry file for a trailhead and return the relative path. */
+const writeTrailheadEntry = async (
   cwd: string,
-  surface: 'cli' | 'mcp'
+  trailhead: 'cli' | 'mcp'
 ): Promise<string> => {
-  const entryFile = getEntryFile(surface);
+  const entryFile = getEntryFile(trailhead);
   const fullEntryPath = join(cwd, entryFile);
   const appImport = (await findTopoPath(cwd)) ?? './app.js';
   const content =
-    surface === 'cli'
+    trailhead === 'cli'
       ? generateCliEntry(appImport)
       : generateMcpEntry(appImport);
 
@@ -90,30 +90,32 @@ const writeSurfaceEntry = async (
   return entryFile;
 };
 
-export const addSurface = trail('add.surface', {
-  description: 'Add a surface to an existing project',
-  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) => {
+export const addTrailhead = trail('add.trailhead', {
+  blaze: async (input) => {
     const cwd = resolve(input.dir ?? '.');
-    const { surface } = input;
-    const entryFile = getEntryFile(surface);
+    const { trailhead } = input;
+    const entryFile = getEntryFile(trailhead);
 
     if (existsSync(join(cwd, entryFile))) {
       return Result.err(
-        new Error(`${surface.toUpperCase()} is already blazed. Nothing to do.`)
+        new Error(
+          `${trailhead.toUpperCase()} trailhead already exists. Nothing to do.`
+        )
       );
     }
 
     return Result.ok({
-      created: await writeSurfaceEntry(cwd, surface),
-      dependency: await updatePkgJsonForSurface(cwd, surface),
+      created: await writeTrailheadEntry(cwd, trailhead),
+      dependency: await updatePkgJsonForTrailhead(cwd, trailhead),
     });
   },
+  description: 'Add a trailhead to an existing project',
+  input: z.object({
+    dir: z.string().optional().describe('Project directory'),
+    trailhead: z.enum(['cli', 'mcp']).describe('Trailhead to add'),
+  }),
+  output: z.object({
+    created: z.string(),
+    dependency: z.string(),
+  }),
 });

package/src/trails/add-verify.ts

@@ -55,16 +55,7 @@ const updatePackageJsonForVerify = async (
 // ---------------------------------------------------------------------------
 
 export const addVerify = trail('add.verify', {
-  description: 'Add testing and warden verification',
-  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) => {
+  blaze: async (input) => {
     const projectDir = resolve(input.dir ?? '.', input.name);
     const files: string[] = [];
 
@@ -84,4 +75,13 @@ export const addVerify = trail('add.verify', {
 
     return Result.ok({ created: files });
   },
+  description: 'Add testing and warden verification',
+  input: z.object({
+    dir: z.string().optional().describe('Parent directory'),
+    name: z.string().describe('Project name'),
+  }),
+  meta: { internal: true },
+  output: z.object({
+    created: z.array(z.string()),
+  }),
 });

package/src/trails/create-scaffold.ts

@@ -73,7 +73,7 @@ const TSCONFIG_CONTENT = JSON.stringify(
 const GITIGNORE_CONTENT = `node_modules/
 dist/
 *.tsbuildinfo
-.trails/_surface.json
+.trails/_trailhead.json
 `;
 
 const OXLINTRC_CONTENT = JSON.stringify(
@@ -107,7 +107,7 @@ export const hello = trail('hello', {
       name: 'Named greeting',
     },
   ],
-  run: (input) => {
+  blaze: (input) => {
     const name = input.name ?? 'world';
     return Result.ok({ message: \`Hello, \${name}!\` });
   },
@@ -139,7 +139,7 @@ export const show = trail('entity.show', {
       name: 'Show entity',
     },
   ],
-  run: (input) => {
+  blaze: (input) => {
     return Result.ok({ id: input.id, name: 'Example' });
   },
   input: z.object({ id: z.string() }),
@@ -156,7 +156,7 @@ export const add = trail('entity.add', {
       name: 'Add entity',
     },
   ],
-  run: (input) => {
+  blaze: (input) => {
     return Result.ok({ id: '1', name: input.name });
   },
   input: z.object({ name: z.string() }),
@@ -177,7 +177,7 @@ export const search = trail('search', {
       name: 'Search entities',
     },
   ],
-  run: () => {
+  blaze: () => {
     return Result.ok({ results: [] });
   },
   input: z.object({ query: z.string() }),
@@ -194,9 +194,9 @@ import { z } from 'zod';
 
 export const onboard = trail('entity.onboard', {
   description: 'Onboard a new entity end-to-end',
-  follow: ['entity.add'],
-  run: async (input, ctx) => {
-    const result = await ctx.follow('entity.add', { name: input.name });
+  crosses: ['entity.add'],
+  blaze: async (input, ctx) => {
+    const result = await ctx.cross('entity.add', { name: input.name });
     if (result.isErr()) {
       return result;
     }
@@ -207,11 +207,11 @@ export const onboard = trail('entity.onboard', {
 });
 `;
 
-const generateEntityEvents = (): string =>
-  `import { event } from '@ontrails/core';
+const generateEntitySignals = (): string =>
+  `import { signal } from '@ontrails/core';
 import { z } from 'zod';
 
-export const entityUpdated = event('entity.updated', {
+export const entityUpdated = signal('entity.updated', {
   description: 'Fired when an entity is updated',
   payload: z.object({
     entityId: z.string(),
@@ -248,9 +248,9 @@ const starterImports: Record<
       "import * as entity from './trails/entity.js';",
       "import * as search from './trails/search.js';",
       "import * as onboard from './trails/onboard.js';",
-      "import * as entityEvents from './events/entity-events.js';",
+      "import * as entitySignals from './signals/entity-signals.js';",
     ],
-    modules: ['entity', 'search', 'onboard', 'entityEvents'],
+    modules: ['entity', 'search', 'onboard', 'entitySignals'],
   },
   hello: {
     imports: ["import * as hello from './trails/hello.js';"],
@@ -282,7 +282,7 @@ const starterFileGenerators: Record<Starter, () => [string, string][]> = {
     ['src/trails/entity.ts', generateEntityTrails()],
     ['src/trails/search.ts', generateSearchTrail()],
     ['src/trails/onboard.ts', generateOnboardTrail()],
-    ['src/events/entity-events.ts', generateEntityEvents()],
+    ['src/signals/entity-signals.ts', generateEntitySignals()],
     ['src/store.ts', generateStore()],
   ],
   hello: () => [['src/trails/hello.ts', generateHelloTrail()]],
@@ -321,6 +321,19 @@ const writeScaffoldFiles = async (
 // ---------------------------------------------------------------------------
 
 export const createScaffold = trail('create.scaffold', {
+  blaze: 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);
+  },
   description: 'Scaffold a new Trails project',
   input: z.object({
     dir: z.string().optional().describe('Parent directory'),
@@ -330,23 +343,10 @@ export const createScaffold = trail('create.scaffold', {
       .default('hello')
       .describe('Starter trail'),
   }),
-  metadata: { internal: true },
+  meta: { 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

@@ -1,11 +1,11 @@
 /**
  * `create` route -- Create a new Trails project.
  *
- * Composes create.scaffold, add.surface, and add.verify sub-trails
- * via ctx.follow().
+ * Composes create.scaffold, add.trailhead, and add.verify sub-trails
+ * via ctx.cross().
  */
 
-import type { FollowFn } from '@ontrails/core';
+import type { CrossFn } from '@ontrails/core';
 import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
@@ -14,13 +14,13 @@ import { z } from 'zod';
 // ---------------------------------------------------------------------------
 
 type Starter = 'empty' | 'entity' | 'hello';
-type Surface = 'cli' | 'mcp';
+type Trailhead = 'cli' | 'mcp';
 
-interface BlazeInput {
+interface CreateInput {
   readonly dir?: string | undefined;
   readonly name: string;
   readonly starter: Starter;
-  readonly surfaces: readonly Surface[];
+  readonly trailheads: readonly Trailhead[];
   readonly verify: boolean;
 }
 
@@ -48,9 +48,9 @@ const buildScaffoldInput = (input: ScaffoldRequest) => ({
   starter: input.starter,
 });
 
-const buildSurfaceInput = (dir: string, surface: string) => ({
+const buildTrailheadInput = (dir: string, trailhead: string) => ({
   dir,
-  surface,
+  trailhead,
 });
 
 const buildVerifyInput = (input: VerifyRequest) => ({
@@ -59,22 +59,22 @@ const buildVerifyInput = (input: VerifyRequest) => ({
 });
 
 const scaffoldProject = (
-  follow: FollowFn,
+  cross: CrossFn,
   input: ScaffoldRequest
 ): Promise<Result<ScaffoldedProject, Error>> =>
-  follow('create.scaffold', buildScaffoldInput(input));
+  cross('create.scaffold', buildScaffoldInput(input));
 
-const addSurfaceFiles = async (
-  follow: FollowFn,
+const addTrailheadFiles = async (
+  cross: CrossFn,
   dir: string,
-  surfaces: readonly string[]
+  trailheads: readonly string[]
 ): Promise<Result<string[], Error>> => {
   const created: string[] = [];
 
-  for (const surface of surfaces) {
-    const result = await follow<{ created: string; dependency: string }>(
-      'add.surface',
-      buildSurfaceInput(dir, surface)
+  for (const trailhead of trailheads) {
+    const result = await cross<{ created: string; dependency: string }>(
+      'add.trailhead',
+      buildTrailheadInput(dir, trailhead)
     );
     if (result.isErr()) {
       return Result.err(result.error);
@@ -86,14 +86,14 @@ const addSurfaceFiles = async (
 };
 
 const collectVerifyFiles = async (
-  follow: FollowFn,
+  cross: CrossFn,
   input: VerifyRequest
 ): Promise<Result<string[], Error>> => {
   if (!input.verify) {
     return Result.ok([]);
   }
 
-  const result = await follow<{ created: string[] }>(
+  const result = await cross<{ created: string[] }>(
     'add.verify',
     buildVerifyInput(input)
   );
@@ -104,29 +104,29 @@ const collectVerifyFiles = async (
 
 const collectCreatedFiles = (
   scaffolded: readonly string[],
-  surfaces: readonly string[],
+  trailheads: readonly string[],
   verify: readonly string[]
-): string[] => [...scaffolded, ...surfaces, ...verify];
+): string[] => [...scaffolded, ...trailheads, ...verify];
 
 const runCreate = async (
-  follow: FollowFn,
-  input: BlazeInput
+  cross: CrossFn,
+  input: CreateInput
 ): Promise<Result<{ created: string[]; dir: string; name: string }, Error>> => {
-  const scaffolded = await scaffoldProject(follow, input);
+  const scaffolded = await scaffoldProject(cross, input);
   if (scaffolded.isErr()) {
     return Result.err(scaffolded.error);
   }
 
-  const surfaceResults = await addSurfaceFiles(
-    follow,
+  const trailheadResults = await addTrailheadFiles(
+    cross,
     scaffolded.value.dir,
-    input.surfaces
+    input.trailheads
   );
-  if (surfaceResults.isErr()) {
-    return Result.err(surfaceResults.error);
+  if (trailheadResults.isErr()) {
+    return Result.err(trailheadResults.error);
   }
 
-  const verifyFiles = await collectVerifyFiles(follow, input);
+  const verifyFiles = await collectVerifyFiles(cross, input);
   if (verifyFiles.isErr()) {
     return Result.err(verifyFiles.error);
   }
@@ -134,7 +134,7 @@ const runCreate = async (
   return Result.ok({
     created: collectCreatedFiles(
       scaffolded.value.created,
-      surfaceResults.value,
+      trailheadResults.value,
       verifyFiles.value
     ),
     dir: scaffolded.value.dir,
@@ -147,6 +147,13 @@ const runCreate = async (
 // ---------------------------------------------------------------------------
 
 export const createRoute = trail('create', {
+  blaze: async (input: CreateInput, ctx) => {
+    if (!ctx.cross) {
+      return Result.err(new Error('create route requires ctx.cross'));
+    }
+    return await runCreate(ctx.cross, input);
+  },
+  crosses: ['create.scaffold', 'add.trailhead', 'add.verify'],
   description: 'Create a new Trails project',
   fields: {
     starter: {
@@ -157,14 +164,14 @@ export const createRoute = trail('create', {
           value: 'hello',
         },
         {
-          hint: '4 trails, event, store',
+          hint: '4 trails, signal, store',
           label: 'Entity CRUD',
           value: 'entity',
         },
         { hint: 'Just the structure', label: 'Empty', value: 'empty' },
       ],
     },
-    surfaces: {
+    trailheads: {
       options: [
         { hint: 'Commander-based command line', label: 'CLI', value: 'cli' },
         {
@@ -175,7 +182,6 @@ export const createRoute = trail('create', {
       ],
     },
   },
-  follow: ['create.scaffold', 'add.surface', 'add.verify'],
   input: z.object({
     dir: z.string().optional().describe('Parent directory'),
     name: z.string().describe('Project name'),
@@ -183,10 +189,10 @@ export const createRoute = trail('create', {
       .enum(['hello', 'entity', 'empty'])
       .default('hello')
       .describe('Starter trail'),
-    surfaces: z
+    trailheads: z
       .array(z.enum(['cli', 'mcp']))
       .default(['cli'])
-      .describe('Surfaces'),
+      .describe('Trailheads'),
     verify: z.boolean().default(true).describe('Include testing + warden'),
   }),
   output: z.object({
@@ -194,10 +200,4 @@ export const createRoute = trail('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

@@ -55,11 +55,24 @@ const toGuideDetail = (item: Trail<unknown, unknown>): object => ({
 });
 
 export const guideTrail = trail('guide', {
+  blaze: 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));
+  },
   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 +101,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));
-  },
 });