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

package/src/trails/add-surface.ts

@@ -0,0 +1,150 @@
+/**
+ * `add.surface` trail -- Add a surface to an existing project.
+ *
+ * Generates surface entry points and updates package.json dependencies.
+ */
+
+import { existsSync, mkdirSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import {
+  ontrailsPackageRange,
+  scaffoldDependencyVersions,
+} from '../versions.js';
+import { findTopoPath } from './project.js';
+
+type Surface = 'cli' | 'http' | 'mcp';
+
+const generateCliEntry = (appImportPath: string): string =>
+  `import { surface } from '@ontrails/cli/commander';
+
+import { app } from '${appImportPath}';
+
+await surface(app);
+`;
+
+const generateMcpEntry = (appImportPath: string): string =>
+  `import { surface } from '@ontrails/mcp';
+
+import { app } from '${appImportPath}';
+
+await surface(app);
+`;
+
+const generateHttpEntry = (appImportPath: string): string =>
+  `import { surface } from '@ontrails/hono';
+
+import { app } from '${appImportPath}';
+
+await surface(app, { port: 3000 });
+`;
+
+const surfaceEntryFiles = {
+  cli: 'src/cli.ts',
+  http: 'src/http.ts',
+  mcp: 'src/mcp.ts',
+} satisfies Record<Surface, string>;
+
+const surfaceDependencies = {
+  cli: ['@ontrails/cli'],
+  http: ['@ontrails/hono', '@ontrails/http'],
+  mcp: ['@ontrails/mcp'],
+} satisfies Record<Surface, readonly string[]>;
+
+/** Resolve the entry file for a surface. */
+const getEntryFile = (surface: Surface): string => surfaceEntryFiles[surface];
+
+// ---------------------------------------------------------------------------
+// Trail definition
+// ---------------------------------------------------------------------------
+
+/** Patch deps and optionally bin in a parsed package.json. */
+const patchPkgDeps = (
+  pkg: Record<string, unknown>,
+  surface: Surface,
+  cwd: string
+): string => {
+  const [depName = ''] = surfaceDependencies[surface];
+  const deps = (pkg['dependencies'] ?? {}) as Record<string, string>;
+  for (const dependency of surfaceDependencies[surface]) {
+    deps[dependency] = ontrailsPackageRange;
+  }
+  if (surface === 'cli') {
+    deps['commander'] = scaffoldDependencyVersions.commander;
+    pkg['bin'] = {
+      [(pkg['name'] as string | undefined) ?? basename(cwd)]: './src/cli.ts',
+    };
+  }
+  pkg['dependencies'] = Object.fromEntries(
+    Object.entries(deps).toSorted(([a], [b]) => a.localeCompare(b))
+  );
+  return depName;
+};
+
+/** Update package.json with surface dependency and CLI bin if needed. */
+const updatePkgJsonForSurface = async (
+  cwd: string,
+  surface: Surface
+): Promise<string> => {
+  const pkgPath = join(cwd, 'package.json');
+  if (!existsSync(pkgPath)) {
+    return surfaceDependencies[surface][0] ?? '';
+  }
+  const pkg = (await Bun.file(pkgPath).json()) as Record<string, unknown>;
+  const depName = patchPkgDeps(pkg, surface, 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 (
+  cwd: string,
+  surface: Surface
+): Promise<string> => {
+  const entryFile = getEntryFile(surface);
+  const fullEntryPath = join(cwd, entryFile);
+  const appImport = (await findTopoPath(cwd)) ?? './app.js';
+  const generators = {
+    cli: generateCliEntry,
+    http: generateHttpEntry,
+    mcp: generateMcpEntry,
+  } satisfies Record<Surface, (appImportPath: string) => string>;
+  const content = generators[surface](appImport);
+
+  mkdirSync(dirname(fullEntryPath), { recursive: true });
+  await Bun.write(fullEntryPath, content);
+  return entryFile;
+};
+
+export const addSurface = trail('add.surface', {
+  blaze: async (input) => {
+    const cwd = resolve(input.dir ?? '.');
+    const { surface } = input;
+    const entryFile = getEntryFile(surface);
+
+    if (existsSync(join(cwd, entryFile))) {
+      return Result.err(
+        new Error(
+          `${surface.toUpperCase()} surface already exists. Nothing to do.`
+        )
+      );
+    }
+
+    return Result.ok({
+      created: await writeSurfaceEntry(cwd, surface),
+      dependency: await updatePkgJsonForSurface(cwd, surface),
+    });
+  },
+  description: 'Add a surface to an existing project',
+  input: z.object({
+    dir: z.string().optional().describe('Project directory'),
+    surface: z.enum(['cli', 'http', 'mcp']).describe('Surface to add'),
+  }),
+  output: z.object({
+    created: z.string(),
+    dependency: z.string(),
+  }),
+});

package/src/trails/add-trail.ts

@@ -12,40 +12,53 @@ import { z } from 'zod';
 // Helpers
 // ---------------------------------------------------------------------------
 
+const literal = (value: string): string => JSON.stringify(value);
+
+const deriveExampleMessage = (id: string): string => `${id} completed`;
+
 const generateTrailFile = (
   id: string,
+  description: string,
+  exampleName: string,
   intent: 'read' | 'write' | 'destroy'
 ): string => {
   const intentLine = intent === 'write' ? '' : `\n  intent: '${intent}',`;
+  const exampleMessage = deriveExampleMessage(id);
 
   return `import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
 export const ${id.replaceAll('.', '_')} = trail('${id}', {
-  description: 'TODO: describe this trail',
+  blaze: async () => {
+    return Result.ok({ message: ${literal(exampleMessage)} });
+  },
+  description: ${literal(description)},
   examples: [
     {
+      expected: { message: ${literal(exampleMessage)} },
       input: {},
-      name: 'TODO: add example',
+      name: ${literal(exampleName)},
     },
   ],
-  blaze: async (input) => {
-    return Result.ok({ message: 'TODO' });
-  },
   input: z.object({}),${intentLine}
   output: z.object({ message: z.string() }),
 });
 `;
 };
 
-const generateTestFile = (id: string): string => {
+const generateTestFile = (id: string, exampleName: string): string => {
   const moduleName = id.replaceAll('.', '-');
   const trailName = id.replaceAll('.', '_');
+  const exampleMessage = deriveExampleMessage(id);
   return `import { testTrail } from '@ontrails/testing';
 import { ${trailName} } from '../src/trails/${moduleName}.js';
 
 testTrail(${trailName}, [
-  { description: 'basic test', input: {}, expectOk: true },
+  {
+    description: ${literal(exampleName)},
+    expectValue: { message: ${literal(exampleMessage)} },
+    input: {},
+  },
 ]);
 `;
 };
@@ -64,14 +77,26 @@ const writeWithDirs = async (
 };
 
 export const addTrail = trail('add.trail', {
+  args: ['id'],
   blaze: 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.intent)],
-      [`__tests__/${moduleName}.test.ts`, generateTestFile(id)],
+      [
+        `src/trails/${moduleName}.ts`,
+        generateTrailFile(
+          id,
+          input.description,
+          input.exampleName,
+          input.intent
+        ),
+      ],
+      [
+        `__tests__/${moduleName}.test.ts`,
+        generateTestFile(id, input.exampleName),
+      ],
     ]);
 
     for (const [relativePath, content] of files) {
@@ -82,7 +107,18 @@ export const addTrail = trail('add.trail', {
   },
   description: 'Scaffold a new trail with tests and examples',
   input: z.object({
-    id: z.string().describe('Trail ID (e.g., entity.update)'),
+    description: z
+      .string()
+      .min(1, 'Trail description is required')
+      .describe('Trail description'),
+    exampleName: z
+      .string()
+      .min(1, 'Starter example name is required')
+      .describe('Starter example name'),
+    id: z
+      .string()
+      .min(1, 'Trail ID is required')
+      .describe('Trail ID (e.g., entity.update)'),
     intent: z
       .enum(['read', 'write', 'destroy'])
       .default('write')

package/src/trails/add-verify.ts

@@ -8,30 +8,35 @@ import { dirname, join, resolve } from 'node:path';
 import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
+import {
+  ontrailsPackageRange,
+  scaffoldDependencyVersions,
+} from '../versions.js';
+
 // ---------------------------------------------------------------------------
 // Content generators
 // ---------------------------------------------------------------------------
 
 const generateTestFile = (): string =>
-  `import { testAll } from '@ontrails/testing';
+  `import { testAllEstablished } from '@ontrails/testing';
 import { app } from '../src/app.js';
 
-testAll(app);
+testAllEstablished(app);
 `;
 
 const generateLefthookYml = (): string =>
   `pre-push:
   commands:
     warden:
-      run: bunx trails warden --exit-code
+      run: bunx trails warden
 `;
 
 /** Add testing and warden devDependencies to package.json when present. */
 const patchVerifyDeps = (pkg: Record<string, unknown>): void => {
   const devDeps = (pkg['devDependencies'] ?? {}) as Record<string, string>;
-  devDeps['@ontrails/testing'] = 'workspace:*';
-  devDeps['@ontrails/warden'] = 'workspace:*';
-  devDeps['lefthook'] = '^2.1.1';
+  devDeps['@ontrails/testing'] = ontrailsPackageRange;
+  devDeps['@ontrails/warden'] = ontrailsPackageRange;
+  devDeps['lefthook'] = scaffoldDependencyVersions.lefthook;
   pkg['devDependencies'] = Object.fromEntries(
     Object.entries(devDeps).toSorted(([a], [b]) => a.localeCompare(b))
   );

package/src/trails/create-scaffold.ts

@@ -10,6 +10,11 @@ import { dirname, join, resolve } from 'node:path';
 import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
+import {
+  ontrailsPackageRange,
+  scaffoldDependencyVersions,
+} from '../versions.js';
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -28,14 +33,22 @@ interface ScaffoldResult {
 
 const generatePackageJson = (name: string): string => {
   const deps: Record<string, string> = {
-    '@ontrails/core': 'workspace:*',
-    zod: '^4.0.0',
+    '@ontrails/core': ontrailsPackageRange,
+    zod: scaffoldDependencyVersions.zod,
   };
 
   const pkg: Record<string, unknown> = {
     dependencies: Object.fromEntries(
       Object.entries(deps).toSorted(([a], [b]) => a.localeCompare(b))
     ),
+    devDependencies: Object.fromEntries(
+      Object.entries({
+        '@types/bun': scaffoldDependencyVersions.bunTypes,
+        oxlint: scaffoldDependencyVersions.oxlint,
+        typescript: scaffoldDependencyVersions.typescript,
+        ultracite: scaffoldDependencyVersions.ultracite,
+      }).toSorted(([a], [b]) => a.localeCompare(b))
+    ),
     name,
     scripts: {
       build: 'tsc -b',
@@ -73,7 +86,7 @@ const TSCONFIG_CONTENT = JSON.stringify(
 const GITIGNORE_CONTENT = `node_modules/
 dist/
 *.tsbuildinfo
-.trails/_trailhead.json
+.trails/_surface.json
 `;
 
 const OXLINTRC_CONTENT = JSON.stringify(

package/src/trails/create.ts

@@ -1,11 +1,10 @@
 /**
  * `create` route -- Create a new Trails project.
  *
- * Composes create.scaffold, add.trailhead, and add.verify sub-trails
- * via ctx.cross().
+ * Composes create.scaffold, add.surface, and add.verify sub-trails
+ * via ctx.cross.
  */
 
-import type { CrossFn } from '@ontrails/core';
 import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
@@ -14,13 +13,13 @@ import { z } from 'zod';
 // ---------------------------------------------------------------------------
 
 type Starter = 'empty' | 'entity' | 'hello';
-type Trailhead = 'cli' | 'mcp';
+type Surface = 'cli' | 'http' | 'mcp';
 
 interface CreateInput {
   readonly dir?: string | undefined;
   readonly name: string;
   readonly starter: Starter;
-  readonly trailheads: readonly Trailhead[];
+  readonly surfaces: readonly Surface[];
   readonly verify: boolean;
 }
 
@@ -42,15 +41,20 @@ interface ScaffoldedProject {
   readonly name: string;
 }
 
+interface SurfaceResult {
+  readonly created: string;
+  readonly dependency: string;
+}
+
 const buildScaffoldInput = (input: ScaffoldRequest) => ({
   ...(input.dir === undefined ? {} : { dir: input.dir }),
   name: input.name,
   starter: input.starter,
 });
 
-const buildTrailheadInput = (dir: string, trailhead: string) => ({
+const buildSurfaceInput = (dir: string, surface: string) => ({
   dir,
-  trailhead,
+  surface,
 });
 
 const buildVerifyInput = (input: VerifyRequest) => ({
@@ -58,24 +62,14 @@ const buildVerifyInput = (input: VerifyRequest) => ({
   name: input.name,
 });
 
-const scaffoldProject = (
-  cross: CrossFn,
-  input: ScaffoldRequest
-): Promise<Result<ScaffoldedProject, Error>> =>
-  cross('create.scaffold', buildScaffoldInput(input));
-
-const addTrailheadFiles = async (
-  cross: CrossFn,
-  dir: string,
-  trailheads: readonly string[]
+const collectSurfaceFiles = async (
+  surfaces: readonly string[],
+  addSurface: (surface: string) => Promise<Result<SurfaceResult, Error>>
 ): Promise<Result<string[], Error>> => {
   const created: string[] = [];
 
-  for (const trailhead of trailheads) {
-    const result = await cross<{ created: string; dependency: string }>(
-      'add.trailhead',
-      buildTrailheadInput(dir, trailhead)
-    );
+  for (const surface of surfaces) {
+    const result = await addSurface(surface);
     if (result.isErr()) {
       return Result.err(result.error);
     }
@@ -86,17 +80,14 @@ const addTrailheadFiles = async (
 };
 
 const collectVerifyFiles = async (
-  cross: CrossFn,
-  input: VerifyRequest
+  shouldVerify: boolean,
+  addVerify: () => Promise<Result<{ created: string[] }, Error>>
 ): Promise<Result<string[], Error>> => {
-  if (!input.verify) {
+  if (!shouldVerify) {
     return Result.ok([]);
   }
 
-  const result = await cross<{ created: string[] }>(
-    'add.verify',
-    buildVerifyInput(input)
-  );
+  const result = await addVerify();
   return result.isErr()
     ? Result.err(result.error)
     : Result.ok(result.value.created);
@@ -104,43 +95,9 @@ const collectVerifyFiles = async (
 
 const collectCreatedFiles = (
   scaffolded: readonly string[],
-  trailheads: readonly string[],
+  surfaces: readonly string[],
   verify: readonly string[]
-): string[] => [...scaffolded, ...trailheads, ...verify];
-
-const runCreate = async (
-  cross: CrossFn,
-  input: CreateInput
-): Promise<Result<{ created: string[]; dir: string; name: string }, Error>> => {
-  const scaffolded = await scaffoldProject(cross, input);
-  if (scaffolded.isErr()) {
-    return Result.err(scaffolded.error);
-  }
-
-  const trailheadResults = await addTrailheadFiles(
-    cross,
-    scaffolded.value.dir,
-    input.trailheads
-  );
-  if (trailheadResults.isErr()) {
-    return Result.err(trailheadResults.error);
-  }
-
-  const verifyFiles = await collectVerifyFiles(cross, input);
-  if (verifyFiles.isErr()) {
-    return Result.err(verifyFiles.error);
-  }
-
-  return Result.ok({
-    created: collectCreatedFiles(
-      scaffolded.value.created,
-      trailheadResults.value,
-      verifyFiles.value
-    ),
-    dir: scaffolded.value.dir,
-    name: input.name,
-  });
-};
+): string[] => [...scaffolded, ...surfaces, ...verify];
 
 // ---------------------------------------------------------------------------
 // Route definition
@@ -151,9 +108,52 @@ export const createRoute = trail('create', {
     if (!ctx.cross) {
       return Result.err(new Error('create route requires ctx.cross'));
     }
-    return await runCreate(ctx.cross, input);
+    const { cross } = ctx;
+
+    const scaffolded = await cross<ScaffoldedProject>(
+      'create.scaffold',
+      buildScaffoldInput(input)
+    );
+    if (scaffolded.isErr()) {
+      return Result.err(scaffolded.error);
+    }
+
+    const finishCreate = async (): Promise<
+      Result<{ created: string[]; dir: string; name: string }, Error>
+    > => {
+      const surfaceFiles = await collectSurfaceFiles(
+        input.surfaces,
+        (surface) =>
+          cross<SurfaceResult>(
+            'add.surface',
+            buildSurfaceInput(scaffolded.value.dir, surface)
+          )
+      );
+      if (surfaceFiles.isErr()) {
+        return Result.err(surfaceFiles.error);
+      }
+
+      const verifyFiles = await collectVerifyFiles(input.verify, () =>
+        cross<{ created: string[] }>('add.verify', buildVerifyInput(input))
+      );
+      if (verifyFiles.isErr()) {
+        return Result.err(verifyFiles.error);
+      }
+
+      return Result.ok({
+        created: collectCreatedFiles(
+          scaffolded.value.created,
+          surfaceFiles.value,
+          verifyFiles.value
+        ),
+        dir: scaffolded.value.dir,
+        name: input.name,
+      });
+    };
+
+    return finishCreate();
   },
-  crosses: ['create.scaffold', 'add.trailhead', 'add.verify'],
+  crosses: ['create.scaffold', 'add.surface', 'add.verify'],
   description: 'Create a new Trails project',
   fields: {
     starter: {
@@ -171,7 +171,7 @@ export const createRoute = trail('create', {
         { hint: 'Just the structure', label: 'Empty', value: 'empty' },
       ],
     },
-    trailheads: {
+    surfaces: {
       options: [
         { hint: 'Commander-based command line', label: 'CLI', value: 'cli' },
         {
@@ -179,6 +179,11 @@ export const createRoute = trail('create', {
           label: 'MCP',
           value: 'mcp',
         },
+        {
+          hint: 'Hono-powered HTTP endpoints',
+          label: 'HTTP',
+          value: 'http',
+        },
       ],
     },
   },
@@ -189,10 +194,10 @@ export const createRoute = trail('create', {
       .enum(['hello', 'entity', 'empty'])
       .default('hello')
       .describe('Starter trail'),
-    trailheads: z
-      .array(z.enum(['cli', 'mcp']))
+    surfaces: z
+      .array(z.enum(['cli', 'http', 'mcp']))
       .default(['cli'])
-      .describe('Trailheads'),
+      .describe('Surfaces'),
     verify: z.boolean().default(true).describe('Include testing + warden'),
   }),
   output: z.object({

package/src/trails/dev-clean.ts

@@ -1,8 +1,11 @@
 import { Result, ValidationError, trail } from '@ontrails/core';
 import { z } from 'zod';
 
-import { cleanDevState, DEFAULT_TOPO_SAVE_RETENTION } from './dev-support.js';
-import { isolatedExampleInput } from './topo-support.js';
+import {
+  cleanDevState,
+  DEFAULT_TOPO_SNAPSHOT_RETENTION,
+} from './dev-support.js';
+import { createIsolatedExampleInput } from './topo-support.js';
 
 export const devCleanTrail = trail('dev.clean', {
   blaze: (input, ctx) => {
@@ -18,19 +21,19 @@ export const devCleanTrail = trail('dev.clean', {
     return Result.ok(
       cleanDevState({
         dryRun: input.dryRun,
-        maxAge: input.trackAgeMs,
-        maxRecords: input.tracks,
+        maxAge: input.traceAgeMs,
+        maxRecords: input.traces,
         rootDir,
-        saveRetention: input.saves,
+        snapshotRetention: input.snapshots,
       })
     );
   },
-  description: 'Prune unpinned topo saves and old track records',
+  description: 'Prune unpinned topo snapshots and old trace records',
   examples: [
     {
       input: {
         dryRun: true,
-        rootDir: isolatedExampleInput('dev-clean').rootDir,
+        rootDir: createIsolatedExampleInput('dev-clean').rootDir,
       },
       name: 'Preview local cleanup',
     },
@@ -41,33 +44,34 @@ export const devCleanTrail = trail('dev.clean', {
       .default(true)
       .describe('Preview cleanup without changing state'),
     rootDir: z.string().optional().describe('Workspace root directory'),
-    saves: z
+    snapshots: z
       .number()
-      .default(DEFAULT_TOPO_SAVE_RETENTION)
-      .describe('Unpinned topo saves to retain'),
-    trackAgeMs: z
+      .default(DEFAULT_TOPO_SNAPSHOT_RETENTION)
+      .describe('Unpinned topo snapshots to retain'),
+    traceAgeMs: z
       .number()
       .default(7 * 24 * 60 * 60 * 1000)
-      .describe('Maximum retained track age in milliseconds'),
-    tracks: z.number().default(10_000).describe('Maximum retained track count'),
+      .describe('Maximum retained trace age in milliseconds'),
+    traces: z.number().default(10_000).describe('Maximum retained trace count'),
     yes: z.boolean().default(false).describe('Confirm destructive changes'),
   }),
   intent: 'destroy',
   output: z.object({
     dryRun: z.boolean(),
     remaining: z.object({
-      pinCount: z.number(),
-      saveCount: z.number(),
-      trackCount: z.number(),
+      pinnedCount: z.number(),
+      snapshotCount: z.number(),
+      traceCount: z.number(),
     }),
     removed: z.object({
-      topoSaves: z.number(),
-      trackRecords: z.number(),
+      topoSnapshots: z.number(),
+      traceRecords: z.number(),
     }),
     retention: z.object({
-      saves: z.number(),
-      trackAgeMs: z.number(),
-      tracks: z.number(),
+      snapshots: z.number(),
+      traceAgeMs: z.number(),
+      traces: z.number(),
     }),
   }),
+  permit: { scopes: ['dev:clean'] },
 });