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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/trails",
-  "version": "1.0.0-beta.12",
+  "version": "1.0.0-beta.14",
   "bin": {
     "trails": "./bin/trails.ts"
   },
@@ -14,15 +14,16 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",
-    "@ontrails/cli": "^1.0.0-beta.12",
-    "@ontrails/core": "^1.0.0-beta.12",
-    "@ontrails/logging": "^1.0.0-beta.12",
-    "@ontrails/schema": "^1.0.0-beta.12",
-    "@ontrails/warden": "^1.0.0-beta.12",
+    "@ontrails/cli": "^1.0.0-beta.13",
+    "@ontrails/core": "^1.0.0-beta.13",
+    "@ontrails/logging": "^1.0.0-beta.13",
+    "@ontrails/schema": "^1.0.0-beta.13",
+    "@ontrails/tracker": "^1.0.0-beta.13",
+    "@ontrails/warden": "^1.0.0-beta.13",
     "commander": "^14.0.3",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@ontrails/testing": "^1.0.0-beta.12"
+    "@ontrails/testing": "^1.0.0-beta.13"
   }
 }

package/src/__tests__/create.test.ts

@@ -11,19 +11,19 @@ import { basename, dirname, join } from 'node:path';
 
 import { Result } from '@ontrails/core';
 
-import { addSurface } from '../trails/add-surface.js';
+import { addTrailhead } from '../trails/add-trailhead.js';
 import { addVerify } from '../trails/add-verify.js';
 import { createRoute } from '../trails/create.js';
 import { createScaffold } from '../trails/create-scaffold.js';
 import { isInsideProject } from '../trails/project.js';
 
 type Starter = 'empty' | 'entity' | 'hello';
-type Surface = 'cli' | 'mcp';
+type Trailhead = 'cli' | 'mcp';
 
 const makeTempProject = (): string =>
   join(
     tmpdir(),
-    `trails-blaze-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    `trails-create-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
   );
 
 const readJson = (dir: string, relativePath: string): Record<string, unknown> =>
@@ -68,43 +68,43 @@ const expectErr = <T>(result: Result<T, Error>): Error => {
   return result.error;
 };
 
-const runFollow = async (
+const runCross = async (
   id: string,
   input: unknown
 ): Promise<Result<unknown, Error>> => {
   switch (id) {
     case 'create.scaffold': {
-      return await createScaffold.run(input as never, {} as never);
+      return await createScaffold.blaze(input as never, {} as never);
     }
-    case 'add.surface': {
-      return await addSurface.run(input as never, {} as never);
+    case 'add.trailhead': {
+      return await addTrailhead.blaze(input as never, {} as never);
     }
     case 'add.verify': {
-      return await addVerify.run(input as never, {} as never);
+      return await addVerify.blaze(input as never, {} as never);
     }
     default: {
-      return Result.err(new Error(`Unknown follow target: ${id}`));
+      return Result.err(new Error(`Unknown cross target: ${id}`));
     }
   }
 };
 
-const runBlaze = (
+const runCreate = (
   projectDir: string,
   overrides?: Partial<{
     starter: Starter;
-    surfaces: readonly Surface[];
+    trailheads: readonly Trailhead[];
     verify: boolean;
   }>
 ) =>
-  createRoute.run(
+  createRoute.blaze(
     {
       dir: dirname(projectDir),
       name: basename(projectDir),
       starter: overrides?.starter ?? 'hello',
-      surfaces: [...(overrides?.surfaces ?? ['cli'])],
+      trailheads: [...(overrides?.trailheads ?? ['cli'])],
       verify: overrides?.verify ?? true,
     },
-    { follow: runFollow } as never
+    { cross: runCross } as never
   );
 
 const setupMinimalProject = (dir: string): void => {
@@ -177,7 +177,7 @@ const assertEntityStarter = (dir: string): void => {
       'src/trails/entity.ts',
       'src/trails/search.ts',
       'src/trails/onboard.ts',
-      'src/events/entity-events.ts',
+      'src/signals/entity-signals.ts',
       'src/store.ts',
     ],
     true
@@ -187,7 +187,7 @@ const assertEntityStarter = (dir: string): void => {
     "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'",
   ]);
   expectContainsAll(readText(dir, 'src/trails/entity.ts'), [
     "import { Result, trail } from '@ontrails/core'",
@@ -204,12 +204,12 @@ const assertEntityStarter = (dir: string): void => {
   ]);
 };
 
-const assertMcpSurface = (dir: string): void => {
+const assertMcpTrailhead = (dir: string): void => {
   expectPaths(dir, ['src/mcp.ts'], true);
   expectPaths(dir, ['src/cli.ts'], false);
   expectContainsAll(readText(dir, 'src/mcp.ts'), [
-    "import { blaze } from '@ontrails/mcp'",
-    'await blaze(app)',
+    "import { trailhead } from '@ontrails/mcp'",
+    'await trailhead(app)',
   ]);
 
   const deps = readJson(dir, 'package.json')['dependencies'] as Record<
@@ -244,11 +244,11 @@ const withTempProject = async (
   }
 };
 
-describe('trails blaze', () => {
+describe('trails create', () => {
   describe('create mode', () => {
     test('generates project structure with defaults', async () => {
       await withTempProject(async (dir) => {
-        expectOk(await runBlaze(dir));
+        expectOk(await runCreate(dir));
         assertDefaultProjectFiles(dir);
         assertCliPackage(dir);
         assertHelloApp(dir);
@@ -257,46 +257,46 @@ describe('trails blaze', () => {
 
     test('generates with entity starter', async () => {
       await withTempProject(async (dir) => {
-        expectOk(await runBlaze(dir, { starter: 'entity' }));
+        expectOk(await runCreate(dir, { starter: 'entity' }));
         assertEntityStarter(dir);
       });
     });
 
-    test('generates with MCP surface', async () => {
+    test('generates with MCP trailhead', async () => {
       await withTempProject(async (dir) => {
-        expectOk(await runBlaze(dir, { surfaces: ['mcp'] }));
-        assertMcpSurface(dir);
+        expectOk(await runCreate(dir, { trailheads: ['mcp'] }));
+        assertMcpTrailhead(dir);
       });
     });
 
     test('skips verification when verify is false', async () => {
       await withTempProject(async (dir) => {
-        expectOk(await runBlaze(dir, { verify: false }));
+        expectOk(await runCreate(dir, { verify: false }));
         assertVerifySkipped(dir);
       });
     });
 
     test('generates with empty starter', async () => {
       await withTempProject(async (dir) => {
-        expectOk(await runBlaze(dir, { starter: 'empty' }));
+        expectOk(await runCreate(dir, { starter: 'empty' }));
         assertEmptyStarter(dir);
       });
     });
   });
 
-  describe('add-surface mode', () => {
+  describe('add-trailhead mode', () => {
     test('adds MCP to existing project', async () => {
       await withTempProject(async (dir) => {
         setupMinimalProject(dir);
         const result = expectOk(
-          await addSurface.run({ dir, surface: 'mcp' }, {} as never)
+          await addTrailhead.blaze({ dir, trailhead: 'mcp' }, {} as never)
         );
 
         expect(result.created).toBe('src/mcp.ts');
         expect(result.dependency).toBe('@ontrails/mcp');
         expectPaths(dir, ['src/mcp.ts'], true);
         expectContainsAll(readText(dir, 'src/mcp.ts'), [
-          "import { blaze } from '@ontrails/mcp'",
+          "import { trailhead } from '@ontrails/mcp'",
         ]);
         const deps = readJson(dir, 'package.json')['dependencies'] as Record<
           string,
@@ -306,16 +306,18 @@ describe('trails blaze', () => {
       });
     });
 
-    test('detects already-blazed surface', async () => {
+    test('detects existing trailhead entrypoint', async () => {
       await withTempProject(async (dir) => {
         mkdirSync(join(dir, 'src'), { recursive: true });
         mkdirSync(join(dir, '.trails'), { recursive: true });
         writeFileSync(join(dir, 'src', 'mcp.ts'), 'existing content');
 
         const error = expectErr(
-          await addSurface.run({ dir, surface: 'mcp' }, {} as never)
+          await addTrailhead.blaze({ dir, trailhead: 'mcp' }, {} as never)
+        );
+        expect(error.message).toBe(
+          'MCP trailhead already exists. Nothing to do.'
         );
-        expect(error.message).toBe('MCP is already blazed. Nothing to do.');
       });
     });
   });

package/src/__tests__/draft-promote.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import type { Result } from '@ontrails/core';
+import { ValidationError } from '@ontrails/core';
+
+import { draftPromoteTrail } from '../trails/draft-promote.js';
+
+const repoTempDir = (): string =>
+  join(
+    resolve(import.meta.dir, '../..'),
+    '.tmp-tests',
+    `draft-promote-${Date.now()}-${Math.random().toString(36).slice(2)}`
+  );
+
+const expectOk = <T>(result: Result<T, Error>): T => {
+  if (result.isErr()) {
+    throw result.error;
+  }
+  return result.value;
+};
+
+const expectErr = <E extends Error>(result: Result<unknown, E>): E => {
+  if (result.isOk()) {
+    throw new Error('expected result to be an error');
+  }
+  return result.error;
+};
+
+const writeDraftPromoteFixture = (dir: string): void => {
+  mkdirSync(join(dir, 'src'), { recursive: true });
+
+  writeFileSync(
+    join(dir, 'src', 'app.ts'),
+    `import { topo } from '@ontrails/core';
+import { draftPrepare } from './_draft.prepare.js';
+import { exportTrail } from './export.js';
+
+export const app = topo('draft-test', { draftPrepare, exportTrail });
+`
+  );
+
+  writeFileSync(
+    join(dir, 'src', '_draft.prepare.ts'),
+    `import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+export const draftPrepare = trail('_draft.entity.prepare', {
+  blaze: async () => Result.ok({ ready: true }),
+  input: z.object({}),
+  output: z.object({ ready: z.boolean() }),
+});
+`
+  );
+
+  writeFileSync(
+    join(dir, 'src', 'export.ts'),
+    `import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+export const exportTrail = trail('entity.export', {
+  blaze: async () => Result.ok({ exported: true }),
+  crosses: ['_draft.entity.prepare'],
+  input: z.object({}),
+  output: z.object({ exported: z.boolean() }),
+});
+`
+  );
+};
+
+const expectDraftPromoteResults = (dir: string): void => {
+  expect(existsSync(join(dir, 'src', '_draft.prepare.ts'))).toBe(false);
+  expect(existsSync(join(dir, 'src', 'prepare.ts'))).toBe(true);
+  expect(readFileSync(join(dir, 'src', 'prepare.ts'), 'utf8')).toContain(
+    "trail('entity.prepare'"
+  );
+  expect(readFileSync(join(dir, 'src', 'export.ts'), 'utf8')).toContain(
+    "crosses: ['entity.prepare']"
+  );
+  expect(readFileSync(join(dir, 'src', 'app.ts'), 'utf8')).toContain(
+    "from './prepare.js'"
+  );
+};
+
+describe('draft.promote', () => {
+  test('promotes draft ids, renames files, and updates imports', async () => {
+    const dir = repoTempDir();
+
+    try {
+      writeDraftPromoteFixture(dir);
+
+      const result = expectOk(
+        await draftPromoteTrail.blaze(
+          {
+            fromId: '_draft.entity.prepare',
+            renameFiles: true,
+            rootDir: dir,
+            toId: 'entity.prepare',
+          },
+          { cwd: dir } as never
+        )
+      );
+
+      expect(result.promotedEstablished).toBe(true);
+      expect(result.remainingDraftIds).toEqual([]);
+      expect(result.updatedFiles).toEqual(
+        expect.arrayContaining(['src/app.ts', 'src/export.ts'])
+      );
+      expect(result.renamedFiles).toEqual([
+        {
+          from: 'src/_draft.prepare.ts',
+          to: 'src/prepare.ts',
+        },
+      ]);
+      expectDraftPromoteResults(dir);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('returns ValidationError when rootDir does not exist', async () => {
+    const error = expectErr(
+      await draftPromoteTrail.blaze(
+        {
+          fromId: '_draft.entity.prepare',
+          renameFiles: true,
+          rootDir: join(repoTempDir(), 'missing'),
+          toId: 'entity.prepare',
+        },
+        { cwd: process.cwd() } as never
+      )
+    );
+
+    expect(error).toBeInstanceOf(ValidationError);
+    expect(error.message).toContain('rootDir does not exist');
+  });
+});

package/src/__tests__/guide.test.ts

@@ -9,6 +9,10 @@ import { z } from 'zod';
 // ---------------------------------------------------------------------------
 
 const helloTrail = trail('hello', {
+  blaze: (input) => {
+    const name = input.name ?? 'world';
+    return Result.ok({ message: `Hello, ${name}!` });
+  },
   description: 'Say hello',
   detours: {
     NotFoundError: ['search'],
@@ -28,10 +32,6 @@ const helloTrail = trail('hello', {
   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}!` });
-  },
 });
 
 const app = topo('test-app', { hello: helloTrail });

package/src/__tests__/load-app.test.ts

@@ -1,8 +1,37 @@
 import { describe, expect, test } from 'bun:test';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { resolve } from 'node:path';
 
 import { loadApp } from '../trails/load-app.js';
 
+const writeLoadAppFixture = (cwd: string, name: string): void => {
+  writeFileSync(
+    resolve(cwd, 'src/app.ts'),
+    `export const app = {
+  name: '${name}',
+  trails: new Map(),
+  signals: new Map(),
+  provisions: new Map()
+};`
+  );
+};
+
+const assertLoadAppCaching = async (cwd: string): Promise<void> => {
+  writeLoadAppFixture(cwd, 'first');
+
+  const first = await loadApp('./src/app.ts', cwd);
+
+  writeLoadAppFixture(cwd, 'second');
+
+  const cached = await loadApp('./src/app.ts', cwd);
+  const fresh = await loadApp('./src/app.ts', cwd, { fresh: true });
+
+  expect(first.name).toBe('first');
+  expect(cached.name).toBe('first');
+  expect(fresh.name).toBe('second');
+};
+
 describe('loadApp', () => {
   test('resolves relative module paths from cwd', async () => {
     // import.meta.dir is src/__tests__/, go up two to get apps/trails/
@@ -12,4 +41,18 @@ describe('loadApp', () => {
     expect(app.name).toBe('trails');
     expect(app.get('survey')).toBeDefined();
   });
+
+  test('can bypass module caching with fresh loading', async () => {
+    const cwd = resolve(
+      tmpdir(),
+      `trails-load-app-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    );
+
+    try {
+      mkdirSync(resolve(cwd, 'src'), { recursive: true });
+      await assertLoadAppCaching(cwd);
+    } finally {
+      rmSync(cwd, { force: true, recursive: true });
+    }
+  });
 });