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

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

@@ -0,0 +1,77 @@
+import { Result, ValidationError, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+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) => {
+    if (input.dryRun !== true && input.yes !== true) {
+      return Result.err(
+        new ValidationError(
+          'Refusing to clean local state without `--yes` or `--dry-run`.'
+        )
+      );
+    }
+
+    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    return Result.ok(
+      cleanDevState({
+        dryRun: input.dryRun,
+        maxAge: input.traceAgeMs,
+        maxRecords: input.traces,
+        rootDir,
+        snapshotRetention: input.snapshots,
+      })
+    );
+  },
+  description: 'Prune unpinned topo snapshots and old trace records',
+  examples: [
+    {
+      input: {
+        dryRun: true,
+        rootDir: createIsolatedExampleInput('dev-clean').rootDir,
+      },
+      name: 'Preview local cleanup',
+    },
+  ],
+  input: z.object({
+    dryRun: z
+      .boolean()
+      .default(true)
+      .describe('Preview cleanup without changing state'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+    snapshots: z
+      .number()
+      .default(DEFAULT_TOPO_SNAPSHOT_RETENTION)
+      .describe('Unpinned topo snapshots to retain'),
+    traceAgeMs: z
+      .number()
+      .default(7 * 24 * 60 * 60 * 1000)
+      .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({
+      pinnedCount: z.number(),
+      snapshotCount: z.number(),
+      traceCount: z.number(),
+    }),
+    removed: z.object({
+      topoSnapshots: z.number(),
+      traceRecords: z.number(),
+    }),
+    retention: z.object({
+      snapshots: z.number(),
+      traceAgeMs: z.number(),
+      traces: z.number(),
+    }),
+  }),
+  permit: { scopes: ['dev:clean'] },
+});

package/src/trails/dev-reset.ts

@@ -0,0 +1,45 @@
+import { Result, ValidationError, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { resetDevState } from './dev-support.js';
+import { createIsolatedExampleInput } from './topo-support.js';
+
+export const devResetTrail = trail('dev.reset', {
+  blaze: (input, ctx) => {
+    if (input.dryRun !== true && input.yes !== true) {
+      return Result.err(
+        new ValidationError(
+          'Refusing to reset local state without `--yes` or `--dry-run`.'
+        )
+      );
+    }
+
+    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    return Result.ok(resetDevState({ dryRun: input.dryRun, rootDir }));
+  },
+  description: 'Remove local Trails database artifacts',
+  examples: [
+    {
+      input: {
+        dryRun: true,
+        rootDir: createIsolatedExampleInput('dev-reset').rootDir,
+      },
+      name: 'Preview local reset',
+    },
+  ],
+  input: z.object({
+    dryRun: z
+      .boolean()
+      .default(true)
+      .describe('Preview reset without changing state'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+    yes: z.boolean().default(false).describe('Confirm destructive changes'),
+  }),
+  intent: 'destroy',
+  output: z.object({
+    dryRun: z.boolean(),
+    removedCount: z.number(),
+    removedFiles: z.array(z.string()),
+  }),
+  permit: { scopes: ['dev:reset'] },
+});

package/src/trails/dev-stats.ts

@@ -0,0 +1,67 @@
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import {
+  buildDevStats,
+  DEFAULT_TOPO_SNAPSHOT_RETENTION,
+} from './dev-support.js';
+import { createIsolatedExampleInput } from './topo-support.js';
+
+export const devStatsTrail = trail('dev.stats', {
+  blaze: (input, ctx) => {
+    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    return Result.ok(
+      buildDevStats({
+        maxAge: input.traceAgeMs,
+        maxRecords: input.traces,
+        rootDir,
+        snapshotRetention: input.snapshots,
+      })
+    );
+  },
+  description: 'Show local Trails workspace state and retention',
+  examples: [
+    {
+      input: { rootDir: createIsolatedExampleInput('dev-stats').rootDir },
+      name: 'Show local dev state',
+    },
+  ],
+  input: z.object({
+    rootDir: z.string().optional().describe('Workspace root directory'),
+    snapshots: z
+      .number()
+      .default(DEFAULT_TOPO_SNAPSHOT_RETENTION)
+      .describe('Unpinned topo snapshots to retain'),
+    traceAgeMs: z
+      .number()
+      .default(7 * 24 * 60 * 60 * 1000)
+      .describe('Maximum retained trace age in milliseconds'),
+    traces: z.number().default(10_000).describe('Maximum retained trace count'),
+  }),
+  intent: 'read',
+  output: z.object({
+    db: z.object({
+      exists: z.boolean(),
+      fileSizeBytes: z.number(),
+      path: z.string(),
+    }),
+    lock: z.object({
+      exists: z.boolean(),
+      fileSizeBytes: z.number(),
+      path: z.string(),
+    }),
+    retention: z.object({
+      snapshots: z.number(),
+      traceAgeMs: z.number(),
+      traces: z.number(),
+    }),
+    topo: z.object({
+      pinnedCount: z.number(),
+      prunableSnapshotCount: z.number(),
+      snapshotCount: z.number(),
+    }),
+    tracing: z.object({
+      recordCount: z.number(),
+    }),
+  }),
+});