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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/trails",
-  "version": "1.0.0-beta.13",
+  "version": "1.0.0-beta.15",
   "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.14",
+    "@ontrails/core": "^1.0.0-beta.14",
+    "@ontrails/logging": "^1.0.0-beta.14",
+    "@ontrails/schema": "^1.0.0-beta.14",
+    "@ontrails/tracing": "^1.0.0-beta.14",
+    "@ontrails/warden": "^1.0.0-beta.14",
     "commander": "^14.0.3",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@ontrails/testing": "^1.0.0-beta.12"
+    "@ontrails/testing": "^1.0.0-beta.14"
   }
 }

package/src/__tests__/add-trail.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, test } from 'bun:test';
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import type { Result } from '@ontrails/core';
+import { ValidationError, validateInput } from '@ontrails/core';
+
+import { addTrail } from '../trails/add-trail.js';
+
+const repoTempDir = (): string =>
+  join(
+    resolve(import.meta.dir, '../..'),
+    '.tmp-tests',
+    `add-trail-${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 expectValidationError = (
+  result: Result<unknown, Error>
+): ValidationError => {
+  if (result.isOk()) {
+    throw new Error('Expected validation error');
+  }
+  expect(result.error).toBeInstanceOf(ValidationError);
+  return result.error as ValidationError;
+};
+
+const readGeneratedFile = (dir: string, relativePath: string): string => {
+  const filePath = join(dir, relativePath);
+  expect(existsSync(filePath)).toBe(true);
+  return readFileSync(filePath, 'utf8');
+};
+
+const assertGeneratedScaffold = (dir: string): void => {
+  const trailSource = readGeneratedFile(dir, 'src/trails/entity-prepare.ts');
+  const testSource = readGeneratedFile(dir, '__tests__/entity-prepare.test.ts');
+
+  expect(trailSource).toContain('description: "Prepare an entity for export"');
+  expect(trailSource).toContain('name: "Prepare a draft entity"');
+  expect(trailSource).toContain(
+    'expected: { message: "entity.prepare completed" }'
+  );
+  expect(testSource).toContain('description: "Prepare a draft entity"');
+  expect(testSource).toContain(
+    'expectValue: { message: "entity.prepare completed" }'
+  );
+  expect(trailSource).not.toContain('TODO');
+  expect(testSource).not.toContain('TODO');
+};
+
+describe('add.trail', () => {
+  test('requires authored description and example metadata', () => {
+    const error = expectValidationError(
+      validateInput(addTrail.input, {
+        id: 'entity.prepare',
+        intent: 'write',
+      })
+    );
+
+    expect(error.message).toContain('description');
+    expect(error.message).toContain('exampleName');
+  });
+
+  test('writes starter files without TODO placeholders', async () => {
+    const dir = repoTempDir();
+
+    try {
+      mkdirSync(dir, { recursive: true });
+
+      const result = expectOk(
+        await addTrail.blaze(
+          {
+            description: 'Prepare an entity for export',
+            exampleName: 'Prepare a draft entity',
+            id: 'entity.prepare',
+            intent: 'write',
+          },
+          { cwd: dir } as never
+        )
+      );
+
+      expect(result.created).toEqual([
+        'src/trails/entity-prepare.ts',
+        '__tests__/entity-prepare.test.ts',
+      ]);
+      assertGeneratedScaffold(dir);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+});

package/src/__tests__/create.test.ts

@@ -11,14 +11,18 @@ import { basename, dirname, join } from 'node:path';
 
 import { Result } from '@ontrails/core';
 
-import { addTrailhead } from '../trails/add-trailhead.js';
+import { addSurface } from '../trails/add-surface.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';
+import {
+  ontrailsPackageRange,
+  scaffoldDependencyVersions,
+} from '../versions.js';
 
 type Starter = 'empty' | 'entity' | 'hello';
-type Trailhead = 'cli' | 'mcp';
+type Surface = 'cli' | 'http' | 'mcp';
 
 const makeTempProject = (): string =>
   join(
@@ -76,8 +80,8 @@ const runCross = async (
     case 'create.scaffold': {
       return await createScaffold.blaze(input as never, {} as never);
     }
-    case 'add.trailhead': {
-      return await addTrailhead.blaze(input as never, {} as never);
+    case 'add.surface': {
+      return await addSurface.blaze(input as never, {} as never);
     }
     case 'add.verify': {
       return await addVerify.blaze(input as never, {} as never);
@@ -92,7 +96,7 @@ const runCreate = (
   projectDir: string,
   overrides?: Partial<{
     starter: Starter;
-    trailheads: readonly Trailhead[];
+    surfaces: readonly Surface[];
     verify: boolean;
   }>
 ) =>
@@ -101,7 +105,7 @@ const runCreate = (
       dir: dirname(projectDir),
       name: basename(projectDir),
       starter: overrides?.starter ?? 'hello',
-      trailheads: [...(overrides?.trailheads ?? ['cli'])],
+      surfaces: [...(overrides?.surfaces ?? ['cli'])],
       verify: overrides?.verify ?? true,
     },
     { cross: runCross } as never
@@ -117,7 +121,10 @@ const setupMinimalProject = (dir: string): void => {
   writeFileSync(
     join(dir, 'package.json'),
     JSON.stringify(
-      { dependencies: { '@ontrails/core': 'workspace:*' }, name: 'test' },
+      {
+        dependencies: { '@ontrails/core': ontrailsPackageRange },
+        name: 'test',
+      },
       null,
       2
     )
@@ -149,13 +156,28 @@ const assertCliPackage = (dir: string): void => {
   expect(pkg['name']).toBe(basename(dir));
 
   const deps = pkg['dependencies'] as Record<string, string>;
-  expect(deps['@ontrails/core']).toBe('workspace:*');
-  expect(deps['@ontrails/cli']).toBe('workspace:*');
-  expect(deps['commander']).toBeDefined();
+  expect(deps['@ontrails/core']).toBe(ontrailsPackageRange);
+  expect(deps['@ontrails/cli']).toBe(ontrailsPackageRange);
+  expect(deps['commander']).toBe(scaffoldDependencyVersions.commander);
+};
+
+const assertVerifyPackage = (dir: string): void => {
+  const pkg = readJson(dir, 'package.json');
+  const devDeps = pkg['devDependencies'] as Record<string, string>;
+  expect(devDeps['@ontrails/testing']).toBe(ontrailsPackageRange);
+  expect(devDeps['@ontrails/warden']).toBe(ontrailsPackageRange);
+  expect(devDeps['lefthook']).toBe(scaffoldDependencyVersions.lefthook);
+  expect(readText(dir, 'lefthook.yml')).toContain('bunx trails warden');
+  expect(readText(dir, 'lefthook.yml')).not.toContain('--exit-code');
+};
 
+const assertGeneratedToolingDeps = (dir: string): void => {
+  const pkg = readJson(dir, 'package.json');
   const devDeps = pkg['devDependencies'] as Record<string, string>;
-  expect(devDeps['@ontrails/testing']).toBe('workspace:*');
-  expect(devDeps['@ontrails/warden']).toBe('workspace:*');
+  expect(devDeps['@types/bun']).toBe(scaffoldDependencyVersions.bunTypes);
+  expect(devDeps['oxlint']).toBe(scaffoldDependencyVersions.oxlint);
+  expect(devDeps['typescript']).toBe(scaffoldDependencyVersions.typescript);
+  expect(devDeps['ultracite']).toBe(scaffoldDependencyVersions.ultracite);
 };
 
 const assertHelloApp = (dir: string): void => {
@@ -204,25 +226,45 @@ const assertEntityStarter = (dir: string): void => {
   ]);
 };
 
-const assertMcpTrailhead = (dir: string): void => {
+const assertMcpSurface = (dir: string): void => {
   expectPaths(dir, ['src/mcp.ts'], true);
   expectPaths(dir, ['src/cli.ts'], false);
   expectContainsAll(readText(dir, 'src/mcp.ts'), [
-    "import { trailhead } from '@ontrails/mcp'",
-    'await trailhead(app)',
+    "import { surface } from '@ontrails/mcp'",
+    'await surface(app)',
   ]);
 
   const deps = readJson(dir, 'package.json')['dependencies'] as Record<
     string,
     string
   >;
-  expect(deps['@ontrails/mcp']).toBe('workspace:*');
+  expect(deps['@ontrails/mcp']).toBe(ontrailsPackageRange);
   expect(deps['@ontrails/cli']).toBeUndefined();
 };
 
+const assertHttpSurface = (dir: string): void => {
+  expectPaths(dir, ['src/http.ts'], true);
+  expectContainsAll(readText(dir, 'src/http.ts'), [
+    "import { surface } from '@ontrails/hono'",
+    'await surface(app, { port: 3000 })',
+  ]);
+
+  const deps = readJson(dir, 'package.json')['dependencies'] as Record<
+    string,
+    string
+  >;
+  expect(deps['@ontrails/hono']).toBe(ontrailsPackageRange);
+  expect(deps['@ontrails/http']).toBe(ontrailsPackageRange);
+};
+
 const assertVerifySkipped = (dir: string): void => {
   expectPaths(dir, ['__tests__/examples.test.ts', 'lefthook.yml'], false);
-  expect(readJson(dir, 'package.json')['devDependencies']).toBeUndefined();
+  const devDeps = readJson(dir, 'package.json')['devDependencies'] as Record<
+    string,
+    string
+  >;
+  expect(devDeps['@ontrails/testing']).toBeUndefined();
+  expect(devDeps['@ontrails/warden']).toBeUndefined();
 };
 
 const assertEmptyStarter = (dir: string): void => {
@@ -251,6 +293,8 @@ describe('trails create', () => {
         expectOk(await runCreate(dir));
         assertDefaultProjectFiles(dir);
         assertCliPackage(dir);
+        assertVerifyPackage(dir);
+        assertGeneratedToolingDeps(dir);
         assertHelloApp(dir);
       });
     });
@@ -262,10 +306,17 @@ describe('trails create', () => {
       });
     });
 
-    test('generates with MCP trailhead', async () => {
+    test('generates with MCP surface', async () => {
+      await withTempProject(async (dir) => {
+        expectOk(await runCreate(dir, { surfaces: ['mcp'] }));
+        assertMcpSurface(dir);
+      });
+    });
+
+    test('generates with HTTP surface', async () => {
       await withTempProject(async (dir) => {
-        expectOk(await runCreate(dir, { trailheads: ['mcp'] }));
-        assertMcpTrailhead(dir);
+        expectOk(await runCreate(dir, { surfaces: ['http'] }));
+        assertHttpSurface(dir);
       });
     });
 
@@ -284,39 +335,52 @@ describe('trails create', () => {
     });
   });
 
-  describe('add-trailhead mode', () => {
+  describe('add-surface mode', () => {
     test('adds MCP to existing project', async () => {
       await withTempProject(async (dir) => {
         setupMinimalProject(dir);
         const result = expectOk(
-          await addTrailhead.blaze({ dir, trailhead: 'mcp' }, {} as never)
+          await addSurface.blaze({ dir, surface: '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 { trailhead } from '@ontrails/mcp'",
+          "import { surface } from '@ontrails/mcp'",
         ]);
         const deps = readJson(dir, 'package.json')['dependencies'] as Record<
           string,
           string
         >;
-        expect(deps['@ontrails/mcp']).toBe('workspace:*');
+        expect(deps['@ontrails/mcp']).toBe(ontrailsPackageRange);
+      });
+    });
+
+    test('adds HTTP to existing project', async () => {
+      await withTempProject(async (dir) => {
+        setupMinimalProject(dir);
+        const result = expectOk(
+          await addSurface.blaze({ dir, surface: 'http' }, {} as never)
+        );
+
+        expect(result.created).toBe('src/http.ts');
+        expect(result.dependency).toBe('@ontrails/hono');
+        assertHttpSurface(dir);
       });
     });
 
-    test('detects existing trailhead entrypoint', async () => {
+    test('detects existing surface 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 addTrailhead.blaze({ dir, trailhead: 'mcp' }, {} as never)
+          await addSurface.blaze({ dir, surface: 'mcp' }, {} as never)
         );
         expect(error.message).toBe(
-          'MCP trailhead already exists. Nothing to do.'
+          'MCP surface already exists. 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

@@ -1,7 +1,7 @@
 import { describe, expect, test } from 'bun:test';
 
 import type { AnyTrail } from '@ontrails/core';
-import { trail, topo, Result } from '@ontrails/core';
+import { ConflictError, trail, topo, Result } from '@ontrails/core';
 import { z } from 'zod';
 
 // ---------------------------------------------------------------------------
@@ -14,9 +14,13 @@ const helloTrail = trail('hello', {
     return Result.ok({ message: `Hello, ${name}!` });
   },
   description: 'Say hello',
-  detours: {
-    NotFoundError: ['search'],
-  },
+  detours: [
+    {
+      on: ConflictError,
+      /* oxlint-disable-next-line require-await -- test stub */
+      recover: async () => Result.ok({ message: 'recovered' }),
+    },
+  ],
   examples: [
     {
       expected: { message: 'Hello, world!' },
@@ -86,6 +90,7 @@ describe('trails guide', () => {
   test('detours are accessible on trail', () => {
     const t = app.get('hello') as AnyTrail;
     expect(t).toBeDefined();
-    expect(t.detours?.['NotFoundError']).toEqual(['search']);
+    expect(t.detours).toHaveLength(1);
+    expect(t.detours[0]?.on).toBe(ConflictError);
   });
 });