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

package/src/trails/create-scaffold.ts

@@ -4,12 +4,27 @@
  * Generates package.json, tsconfig, app.ts, starter trails, and .trails/ directory.
  */
 
-import { mkdirSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { resolve } from 'node:path';
 
-import { Result, trail } from '@ontrails/core';
+import { Result, trail, WORKSPACE_GITIGNORE_CONTENT } from '@ontrails/core';
 import { z } from 'zod';
 
+import {
+  applyProjectOperations,
+  planProjectOperations,
+  PROJECT_NAME_MESSAGE,
+  PROJECT_NAME_PATTERN,
+  resolveProjectDir,
+} from '../project-writes.js';
+import type {
+  PlannedProjectOperation,
+  ProjectWriteOperation,
+} from '../project-writes.js';
+import {
+  ontrailsPackageRange,
+  scaffoldDependencyVersions,
+} from '../versions.js';
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -19,7 +34,9 @@ type Starter = 'empty' | 'entity' | 'hello';
 interface ScaffoldResult {
   readonly created: string[];
   readonly dir: string;
+  readonly dryRun: boolean;
   readonly name: string;
+  readonly plannedOperations: PlannedProjectOperation[];
 }
 
 // ---------------------------------------------------------------------------
@@ -28,17 +45,28 @@ 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,
+        oxfmt: scaffoldDependencyVersions.oxfmt,
+        oxlint: scaffoldDependencyVersions.oxlint,
+        typescript: scaffoldDependencyVersions.typescript,
+        ultracite: scaffoldDependencyVersions.ultracite,
+      }).toSorted(([a], [b]) => a.localeCompare(b))
+    ),
     name,
     scripts: {
       build: 'tsc -b',
+      'format:check': 'bunx ultracite check .',
+      'format:fix': 'bunx ultracite fix .',
       lint: 'oxlint ./src',
       test: 'bun test',
       typecheck: 'tsc --noEmit',
@@ -73,16 +101,19 @@ const TSCONFIG_CONTENT = JSON.stringify(
 const GITIGNORE_CONTENT = `node_modules/
 dist/
 *.tsbuildinfo
-.trails/_trailhead.json
+.trails/cache/
+.trails/state/
+.trails/config.local.js
+.trails/config.local.ts
 `;
 
-const OXLINTRC_CONTENT = JSON.stringify(
-  {
-    extends: ['ultracite'],
-  },
-  null,
-  2
-);
+const OXLINT_CONFIG_CONTENT = `import { defineConfig } from 'oxlint';
+import ultracite from 'ultracite/oxlint/core';
+
+export default defineConfig({
+  extends: [ultracite],
+});
+`;
 
 const OXFMTRC_CONTENT = `{
   // ultracite defaults
@@ -260,8 +291,11 @@ const starterImports: Record<
 
 const generateAppTs = (name: string, starter: Starter): string => {
   const { imports, modules } = starterImports[starter];
+  const appNameLiteral = JSON.stringify(name);
   const topoArgs =
-    modules.length > 0 ? `'${name}', ${modules.join(', ')}` : `'${name}'`;
+    modules.length > 0
+      ? `${appNameLiteral}, ${modules.join(', ')}`
+      : appNameLiteral;
 
   return [
     "import { topo } from '@ontrails/core';",
@@ -296,25 +330,21 @@ const collectScaffoldFiles = (
     ['package.json', generatePackageJson(name)],
     ['tsconfig.json', TSCONFIG_CONTENT],
     ['.gitignore', GITIGNORE_CONTENT],
-    ['.oxlintrc.json', OXLINTRC_CONTENT],
+    ['oxlint.config.ts', OXLINT_CONFIG_CONTENT],
     ['.oxfmtrc.jsonc', OXFMTRC_CONTENT],
+    ['.trails/.gitignore', WORKSPACE_GITIGNORE_CONTENT],
     ['src/app.ts', generateAppTs(name, starter)],
     ...starterFileGenerators[starter](),
   ]);
 
-const writeScaffoldFiles = async (
-  projectDir: string,
+const collectScaffoldOperations = (
   fileMap: Map<string, string>
-): Promise<string[]> => {
-  const files: string[] = [];
-  for (const [relativePath, content] of fileMap) {
-    const fullPath = join(projectDir, relativePath);
-    mkdirSync(dirname(fullPath), { recursive: true });
-    await Bun.write(fullPath, content);
-    files.push(relativePath);
-  }
-  return files;
-};
+): ProjectWriteOperation[] =>
+  [...fileMap].map(([path, content]) => ({
+    content,
+    kind: 'write' as const,
+    path,
+  }));
 
 // ---------------------------------------------------------------------------
 // Trail definition
@@ -322,31 +352,67 @@ const writeScaffoldFiles = async (
 
 export const createScaffold = trail('create.scaffold', {
   blaze: async (input) => {
-    const projectDir = resolve(input.dir ?? '.', input.name);
+    const projectDirResult = resolveProjectDir(input.dir ?? '.', input.name);
+    if (projectDirResult.isErr()) {
+      return Result.err(projectDirResult.error);
+    }
+
+    const projectDir = projectDirResult.value;
     const starter = (input.starter ?? 'hello') as Starter;
+    const dryRun = input.dryRun === true;
     const fileMap = collectScaffoldFiles(input.name, starter);
-    const files = await writeScaffoldFiles(projectDir, fileMap);
-    mkdirSync(join(projectDir, '.trails'), { recursive: true });
+    const operations = collectScaffoldOperations(fileMap);
+    const plannedOperations = dryRun
+      ? planProjectOperations(projectDir, operations)
+      : await applyProjectOperations(projectDir, operations);
+    if (plannedOperations.isErr()) {
+      return Result.err(plannedOperations.error);
+    }
+
+    const created = dryRun ? [] : [...fileMap.keys()];
 
     return Result.ok({
-      created: files,
-      dir: projectDir,
+      created,
+      dir: resolve(projectDir),
+      dryRun,
       name: input.name,
+      plannedOperations: plannedOperations.value,
     } satisfies ScaffoldResult);
   },
   description: 'Scaffold a new Trails project',
   input: z.object({
     dir: z.string().optional().describe('Parent directory'),
-    name: z.string().describe('Project name'),
+    dryRun: z
+      .boolean()
+      .default(false)
+      .describe('Plan scaffold writes without touching the project directory'),
+    name: z
+      .string()
+      .regex(PROJECT_NAME_PATTERN, PROJECT_NAME_MESSAGE)
+      .describe('Project name'),
     starter: z
       .enum(['hello', 'entity', 'empty'])
       .default('hello')
       .describe('Starter trail'),
   }),
-  meta: { internal: true },
   output: z.object({
-    created: z.array(z.string()),
+    created: z
+      .array(z.string())
+      .describe('Project-relative paths of files written (empty in dry-run)'),
     dir: z.string(),
+    dryRun: z.boolean(),
     name: z.string(),
+    plannedOperations: z.array(
+      z.discriminatedUnion('kind', [
+        z.object({ kind: z.literal('mkdir'), path: z.string() }),
+        z.object({
+          from: z.string(),
+          kind: z.literal('rename'),
+          to: z.string(),
+        }),
+        z.object({ kind: z.literal('write'), path: z.string() }),
+      ])
+    ),
   }),
+  visibility: 'internal',
 });

package/src/trails/create.ts

@@ -1,26 +1,30 @@
 /**
  * `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 { InternalError, Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
+import {
+  PROJECT_NAME_MESSAGE,
+  PROJECT_NAME_PATTERN,
+} from '../project-writes.js';
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
 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 +46,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 +67,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 +85,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 +100,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
@@ -149,11 +111,54 @@ 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 Result.err(new InternalError('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 +176,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,20 +184,28 @@ export const createRoute = trail('create', {
           label: 'MCP',
           value: 'mcp',
         },
+        {
+          hint: 'Hono-powered HTTP endpoints',
+          label: 'HTTP',
+          value: 'http',
+        },
       ],
     },
   },
   input: z.object({
     dir: z.string().optional().describe('Parent directory'),
-    name: z.string().describe('Project name'),
+    name: z
+      .string()
+      .regex(PROJECT_NAME_PATTERN, PROJECT_NAME_MESSAGE)
+      .describe('Project name'),
     starter: z
       .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,12 @@
 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 { resolveTrailRootDir } from './root-dir.js';
+import { createIsolatedExampleInput } from './topo-support.js';
 
 export const devCleanTrail = trail('dev.clean', {
   blaze: (input, ctx) => {
@@ -14,23 +18,27 @@ export const devCleanTrail = trail('dev.clean', {
       );
     }
 
-    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return Result.err(rootDirResult.error);
+    }
+    const rootDir = rootDirResult.value;
     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 +49,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'] },
 });

package/src/trails/dev-reset.ts

@@ -2,7 +2,8 @@ import { Result, ValidationError, trail } from '@ontrails/core';
 import { z } from 'zod';
 
 import { resetDevState } from './dev-support.js';
-import { isolatedExampleInput } from './topo-support.js';
+import { resolveTrailRootDir } from './root-dir.js';
+import { createIsolatedExampleInput } from './topo-support.js';
 
 export const devResetTrail = trail('dev.reset', {
   blaze: (input, ctx) => {
@@ -14,7 +15,11 @@ export const devResetTrail = trail('dev.reset', {
       );
     }
 
-    const rootDir = input.rootDir ?? ctx.cwd ?? process.cwd();
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return Result.err(rootDirResult.error);
+    }
+    const rootDir = rootDirResult.value;
     return Result.ok(resetDevState({ dryRun: input.dryRun, rootDir }));
   },
   description: 'Remove local Trails database artifacts',
@@ -22,7 +27,7 @@ export const devResetTrail = trail('dev.reset', {
     {
       input: {
         dryRun: true,
-        rootDir: isolatedExampleInput('dev-reset').rootDir,
+        rootDir: createIsolatedExampleInput('dev-reset').rootDir,
       },
       name: 'Preview local reset',
     },
@@ -41,4 +46,5 @@ export const devResetTrail = trail('dev.reset', {
     removedCount: z.number(),
     removedFiles: z.array(z.string()),
   }),
+  permit: { scopes: ['dev:reset'] },
 });