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

package/src/run-watch.ts

@@ -0,0 +1,432 @@
+/**
+ * CLI-surface bridge for the `--watch` flag (`trails run --watch`).
+ *
+ * `--watch` is a local-development ergonomics affordance for `trails run`.
+ * After the first invocation completes, the CLI installs a filesystem
+ * watcher as a cheap event source. On each debounced event, the watcher
+ * re-derives the watched trail's resolved-contract hash from its TopoGraph
+ * entry and invokes the supplied `onRerun` callback only when that hash
+ * changes. The loop runs until the user sends `SIGINT`.
+ *
+ * Design notes:
+ *
+ * - **Scope.** Watching is intentionally narrow. Filesystem events only wake
+ *   the loop; the rerun decision is the watched trail's TopoGraph entry.
+ *   Comments, whitespace, and unrelated sibling trail changes wake the loop
+ *   but do not rerun unless the resolved contract changes.
+ * - **Debounce.** Editor saves often produce multiple `fs.watch` events
+ *   per logical change (write tmp, rename, touch mtime). The debounce
+ *   coalesces these into a single rerun and dampens AFS / iCloud sync
+ *   bursts.
+ * - **No external deps.** Uses `node:fs.watch` (re-exported by Bun) so
+ *   we avoid pulling in `chokidar` or similar.
+ */
+
+import { once } from 'node:events';
+import { watch as nodeWatch } from 'node:fs';
+import type { FSWatcher } from 'node:fs';
+import { dirname, extname } from 'node:path';
+
+import type { TopoGraphEntry } from '@ontrails/topographer';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Debounce window (ms) for coalescing rapid filesystem events into a single
+ * rerun. Sized small enough to feel instantaneous but large enough to
+ * absorb editor save bursts and sync-driven duplicate notifications.
+ */
+export const WATCH_DEBOUNCE_MS = 100;
+
+/**
+ * Warmup window (ms) after the watcher is created during which incoming
+ * events are ignored.
+ *
+ * On macOS, `fs.watch` (FSEvents) routinely emits a phantom `rename`
+ * event for files that already existed in the watched directory shortly
+ * after the watcher is installed. Ignoring events within this short
+ * warmup prevents a spurious rerun on the first invocation without
+ * meaningfully delaying real edits.
+ *
+ * Applied uniformly across platforms — the cost is negligible (no human
+ * saves within ~150ms of starting `trails run --watch`), and a
+ * platform-specific branch isn't worth the complexity.
+ */
+export const WATCH_WARMUP_MS = 150;
+
+/** Extensions considered relevant to a trail rerun. */
+const WATCHED_EXTENSIONS: ReadonlySet<string> = new Set([
+  '.ts',
+  '.tsx',
+  '.js',
+  '.mjs',
+  '.cjs',
+]);
+
+const ANSI_CLEAR_SCREEN = '\u001B[2J\u001B[H';
+
+const WATCH_SCHEMA_INVALID_MESSAGE =
+  '[watch] schema invalid; skipping rerun until valid\n';
+const WATCH_TRAIL_REMOVED_MESSAGE = '[watch] trail removed; awaiting return\n';
+
+// ---------------------------------------------------------------------------
+// Argv detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect whether `--watch` appears in argv.
+ *
+ * Pre-parsed argv detection lets the CLI install the watcher loop before
+ * `surface()` parses argv. The flag is also wired through the build
+ * pipeline as a meta flag, so trail input is unaffected.
+ */
+export const argvHasWatchFlag = (argv: readonly string[]): boolean =>
+  argv.includes('--watch');
+
+const RUN_FLAGS_WITH_VALUES: ReadonlySet<string> = new Set([
+  '--app',
+  '--input',
+  '--input-json',
+  '--module',
+  '--output',
+  '--root-dir',
+  '--token',
+  '--permit',
+]);
+
+const RUN_SHORT_FLAGS_WITH_VALUES: ReadonlySet<string> = new Set(['-o']);
+
+/**
+ * Read the target trail id from a `trails run ...` argv slice.
+ *
+ * Accepts args after the binary name (for example
+ * `['run', '-o', 'json', 'trail.id', '--watch']`). The parser is intentionally
+ * small and conservative: it skips known CLI meta flags and their values so the
+ * watch loop resolves the same trail the run command will execute.
+ */
+export const readRunTrailId = (args: readonly string[]): string | undefined => {
+  const runIndex = args.indexOf('run');
+  if (runIndex === -1) {
+    return undefined;
+  }
+  const positionals: string[] = [];
+  for (let i = runIndex + 1; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === undefined) {
+      continue;
+    }
+    if (arg.startsWith('--')) {
+      if (!arg.includes('=') && RUN_FLAGS_WITH_VALUES.has(arg)) {
+        i += 1;
+      }
+      continue;
+    }
+    if (arg.startsWith('-')) {
+      if (RUN_SHORT_FLAGS_WITH_VALUES.has(arg)) {
+        i += 1;
+      }
+      continue;
+    }
+    positionals.push(arg);
+  }
+  const [first, second] = positionals;
+  if (first === 'examples' || first === 'example') {
+    return second;
+  }
+  return first;
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const formatError = (error: unknown): string => {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+};
+
+const isRelevantFilename = (filename: string | null): boolean => {
+  if (filename === null || filename.length === 0) {
+    return false;
+  }
+  return WATCHED_EXTENSIONS.has(extname(filename));
+};
+
+const canonicalize = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value !== null && typeof value === 'object') {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(value).toSorted()) {
+      sorted[key] = canonicalize((value as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+  return value;
+};
+
+export const hashTopoGraphEntry = (entry: TopoGraphEntry): string => {
+  const hasher = new Bun.CryptoHasher('sha256');
+  hasher.update(JSON.stringify(canonicalize(entry)));
+  return hasher.digest('hex');
+};
+
+export type ReadTopoGraphEntryHash = () =>
+  | Promise<string | null>
+  | string
+  | null;
+
+// ---------------------------------------------------------------------------
+// Watcher
+// ---------------------------------------------------------------------------
+
+/** Options for {@link createTrailWatcher}. */
+export interface CreateTrailWatcherOptions {
+  /**
+   * Absolute path to the resolved trail's source file. The watcher targets
+   * the directory containing this file (non-recursive) and filters events
+   * to relevant extensions only.
+   */
+  readonly sourcePath: string;
+  /**
+   * Invoked once per debounced change burst. Errors thrown by the callback
+   * are caught and reported to stderr so a misbehaving handler does not
+   * tear down the watcher loop.
+   */
+  readonly onRerun: () => void | Promise<void>;
+  /**
+   * Derive the watched trail's current resolved-contract hash. Return `null`
+   * when the watched trail is temporarily absent. Throw when the current
+   * source state cannot produce a valid TopoGraph.
+   */
+  readonly readTopoGraphEntryHash: ReadTopoGraphEntryHash;
+  /**
+   * Last known good resolved-contract hash captured after the initial run.
+   * When omitted, the next valid changed hash becomes the first rerun signal.
+   */
+  readonly initialTopoGraphEntryHash?: string | null | undefined;
+  /**
+   * Override for the debounce window. Primarily a test seam; production
+   * callers should rely on {@link WATCH_DEBOUNCE_MS}.
+   */
+  readonly debounceMs?: number | undefined;
+  /**
+   * Override for the warmup window. Primarily a test seam; production
+   * callers should rely on {@link WATCH_WARMUP_MS}.
+   */
+  readonly warmupMs?: number | undefined;
+}
+
+/** Handle returned by {@link createTrailWatcher}. */
+export interface TrailWatcher {
+  /**
+   * Stop the watcher and clear any pending debounce timer. Idempotent —
+   * subsequent calls are no-ops.
+   */
+  readonly close: () => void;
+}
+
+/**
+ * Create a filesystem watcher that triggers `onRerun` whenever a relevant
+ * filesystem event changes the watched trail's resolved contract.
+ *
+ * The watcher targets the directory of `sourcePath` (non-recursive). Events
+ * are filtered to TypeScript/JavaScript file extensions and coalesced through
+ * a short debounce window. Each debounced event re-reads the watched trail's
+ * TopoGraph entry hash; only a hash change reruns the trail.
+ *
+ * @remarks Reruns are not serialized. If a save lands while a previous
+ * rerun is still awaiting `onRerun`, the new debounce window can fire
+ * concurrently. In practice the {@link WATCH_DEBOUNCE_MS} window plus
+ * realistic save cadences make this uncommon, and each `surface()` call
+ * from the loop is independent. Callers that share mutable surface
+ * state (e.g. a global trace sink) must scope it per invocation —
+ * `runSurfaceOnce` in `apps/trails/src/cli.ts` does this for `--trace`.
+ */
+export const createTrailWatcher = (
+  options: CreateTrailWatcherOptions
+): TrailWatcher => {
+  const debounceMs = options.debounceMs ?? WATCH_DEBOUNCE_MS;
+  const warmupMs = options.warmupMs ?? WATCH_WARMUP_MS;
+  const watchDir = dirname(options.sourcePath);
+  const startedAt = Date.now();
+
+  let closed = false;
+  let currentTopoGraphEntryHash = options.initialTopoGraphEntryHash ?? null;
+  let invalidTopoGraphWarned = false;
+  let trailRemovedWarned = false;
+  let pending: ReturnType<typeof setTimeout> | undefined;
+  let watcher: FSWatcher | undefined;
+
+  const readNextTopoGraphEntryHash = async (): Promise<
+    string | null | undefined
+  > => {
+    try {
+      const nextHash = await options.readTopoGraphEntryHash();
+      invalidTopoGraphWarned = false;
+      if (nextHash !== null) {
+        trailRemovedWarned = false;
+      } else if (!trailRemovedWarned) {
+        process.stderr.write(WATCH_TRAIL_REMOVED_MESSAGE);
+        trailRemovedWarned = true;
+      }
+      return nextHash;
+    } catch {
+      if (!invalidTopoGraphWarned) {
+        process.stderr.write(WATCH_SCHEMA_INVALID_MESSAGE);
+        invalidTopoGraphWarned = true;
+      }
+      return undefined;
+    }
+  };
+
+  const fireRerun = async (): Promise<void> => {
+    pending = undefined;
+    if (closed) {
+      return;
+    }
+    const nextHash = await readNextTopoGraphEntryHash();
+    if (closed) {
+      return;
+    }
+    if (nextHash === undefined || nextHash === null) {
+      return;
+    }
+    if (nextHash === currentTopoGraphEntryHash) {
+      return;
+    }
+    currentTopoGraphEntryHash = nextHash;
+    try {
+      await options.onRerun();
+    } catch (error: unknown) {
+      process.stderr.write(`watch: rerun failed: ${formatError(error)}\n`);
+    }
+  };
+
+  const scheduleRerun = (): void => {
+    if (closed) {
+      return;
+    }
+    if (pending !== undefined) {
+      clearTimeout(pending);
+    }
+    pending = setTimeout(() => {
+      void fireRerun();
+    }, debounceMs);
+  };
+
+  watcher = nodeWatch(
+    watchDir,
+    { persistent: true, recursive: false },
+    (_event, filename) => {
+      if (Date.now() - startedAt < warmupMs) {
+        // Suppress FSEvents replay of pre-existing files on macOS.
+        return;
+      }
+      if (!isRelevantFilename(filename)) {
+        return;
+      }
+      scheduleRerun();
+    }
+  );
+
+  watcher.on('error', (error: Error) => {
+    process.stderr.write(`watch: watcher error: ${error.message}\n`);
+  });
+
+  return {
+    close: () => {
+      if (closed) {
+        return;
+      }
+      closed = true;
+      if (pending !== undefined) {
+        clearTimeout(pending);
+        pending = undefined;
+      }
+      if (watcher !== undefined) {
+        watcher.close();
+        watcher = undefined;
+      }
+    },
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Watch loop
+// ---------------------------------------------------------------------------
+
+/** Options for {@link runWatchLoop}. */
+export interface RunWatchLoopOptions {
+  /** Absolute path to the resolved trail's source file. */
+  readonly sourcePath: string;
+  /** Invoked once per debounced change burst (and once initially). */
+  readonly run: () => Promise<void>;
+  /** Derive the watched trail's current resolved-contract hash. */
+  readonly readTopoGraphEntryHash: ReadTopoGraphEntryHash;
+  /**
+   * Override for the debounce window. Primarily a test seam.
+   */
+  readonly debounceMs?: number | undefined;
+  /**
+   * Whether to clear the terminal between reruns. Defaults to `true` for
+   * the standard interactive experience; tests pass `false` to keep
+   * captured output legible.
+   */
+  readonly clearScreen?: boolean | undefined;
+}
+
+/**
+ * Run the trail once, then install a watcher and re-run on changes until
+ * `SIGINT` is received. Returns the exit code (always `0` on a clean
+ * SIGINT shutdown).
+ *
+ * @remarks This is the high-level entry point used by the CLI binary.
+ * Tests should target {@link createTrailWatcher} directly rather than
+ * spawning a subprocess to drive this loop.
+ */
+export const runWatchLoop = async (
+  options: RunWatchLoopOptions
+): Promise<number> => {
+  const clearScreen = options.clearScreen ?? true;
+
+  const performRun = async (): Promise<void> => {
+    if (clearScreen) {
+      process.stdout.write(ANSI_CLEAR_SCREEN);
+    }
+    try {
+      await options.run();
+    } catch (error: unknown) {
+      process.stderr.write(`watch: run failed: ${formatError(error)}\n`);
+    }
+  };
+
+  await performRun();
+
+  let initialTopoGraphEntryHash: string | null = null;
+  try {
+    initialTopoGraphEntryHash = await options.readTopoGraphEntryHash();
+  } catch {
+    process.stderr.write(WATCH_SCHEMA_INVALID_MESSAGE);
+  }
+
+  const watcher = createTrailWatcher({
+    debounceMs: options.debounceMs,
+    initialTopoGraphEntryHash,
+    onRerun: performRun,
+    readTopoGraphEntryHash: options.readTopoGraphEntryHash,
+    sourcePath: options.sourcePath,
+  });
+
+  // `once(emitter, 'event')` returns a Promise that resolves when the
+  // event fires. Cleaner than `new Promise(resolve => emitter.on(...))`
+  // and aligns with `eslint-plugin-promise/avoid-new`.
+  await once(process, 'SIGINT');
+  watcher.close();
+  return 0;
+};

package/src/scaffold-versions.generated.ts

@@ -0,0 +1,12 @@
+// GENERATED FILE — do not edit by hand. Run `bun scripts/sync-scaffold-versions.ts` to regenerate.
+
+export const scaffoldDependencyVersions = {
+  bunTypes: '^1.3.11',
+  commander: '^14.0.3',
+  lefthook: '^2.1.1',
+  oxfmt: '0.47.0',
+  oxlint: '1.62.0',
+  typescript: '^5.9.3',
+  ultracite: '7.6.2',
+  zod: '^4.3.5',
+} as const;

package/src/trails/add-surface.ts

@@ -4,22 +4,24 @@
  * Generates surface entry points and updates package.json dependencies.
  */
 
-import { existsSync, mkdirSync } from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
 
-import { Result, trail } from '@ontrails/core';
+import { AlreadyExistsError, Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
 import {
-  ontrailsPackageRange,
-  scaffoldDependencyVersions,
-} from '../versions.js';
+  projectPathExists,
+  resolveProjectPath,
+  writeProjectFile,
+} from '../project-writes.js';
+import { ontrailsPackageRange } 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 { surface } from '@ontrails/commander';
 
 import { app } from '${appImportPath}';
 
@@ -49,7 +51,7 @@ const surfaceEntryFiles = {
 } satisfies Record<Surface, string>;
 
 const surfaceDependencies = {
-  cli: ['@ontrails/cli'],
+  cli: ['@ontrails/cli', '@ontrails/commander'],
   http: ['@ontrails/hono', '@ontrails/http'],
   mcp: ['@ontrails/mcp'],
 } satisfies Record<Surface, readonly string[]>;
@@ -73,7 +75,6 @@ const patchPkgDeps = (
     deps[dependency] = ontrailsPackageRange;
   }
   if (surface === 'cli') {
-    deps['commander'] = scaffoldDependencyVersions.commander;
     pkg['bin'] = {
       [(pkg['name'] as string | undefined) ?? basename(cwd)]: './src/cli.ts',
     };
@@ -88,24 +89,32 @@ const patchPkgDeps = (
 const updatePkgJsonForSurface = async (
   cwd: string,
   surface: Surface
-): Promise<string> => {
-  const pkgPath = join(cwd, 'package.json');
+): Promise<Result<string, Error>> => {
+  const pkgPathResult = resolveProjectPath(cwd, 'package.json');
+  if (pkgPathResult.isErr()) {
+    return Result.err(pkgPathResult.error);
+  }
+
+  const pkgPath = pkgPathResult.value;
   if (!existsSync(pkgPath)) {
-    return surfaceDependencies[surface][0] ?? '';
+    return Result.ok(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;
+  const written = await writeProjectFile(
+    cwd,
+    'package.json',
+    `${JSON.stringify(pkg, null, 2)}\n`
+  );
+  return written.isErr() ? Result.err(written.error) : Result.ok(depName);
 };
 
 /** Create the entry file for a surface and return the relative path. */
 const writeSurfaceEntry = async (
   cwd: string,
   surface: Surface
-): Promise<string> => {
+): Promise<Result<string, Error>> => {
   const entryFile = getEntryFile(surface);
-  const fullEntryPath = join(cwd, entryFile);
   const appImport = (await findTopoPath(cwd)) ?? './app.js';
   const generators = {
     cli: generateCliEntry,
@@ -114,9 +123,8 @@ const writeSurfaceEntry = async (
   } satisfies Record<Surface, (appImportPath: string) => string>;
   const content = generators[surface](appImport);
 
-  mkdirSync(dirname(fullEntryPath), { recursive: true });
-  await Bun.write(fullEntryPath, content);
-  return entryFile;
+  const written = await writeProjectFile(cwd, entryFile, content);
+  return written.isErr() ? Result.err(written.error) : Result.ok(entryFile);
 };
 
 export const addSurface = trail('add.surface', {
@@ -124,18 +132,32 @@ export const addSurface = trail('add.surface', {
     const cwd = resolve(input.dir ?? '.');
     const { surface } = input;
     const entryFile = getEntryFile(surface);
+    const entryExists = projectPathExists(cwd, entryFile);
+    if (entryExists.isErr()) {
+      return Result.err(entryExists.error);
+    }
 
-    if (existsSync(join(cwd, entryFile))) {
+    if (entryExists.value) {
       return Result.err(
-        new Error(
+        new AlreadyExistsError(
           `${surface.toUpperCase()} surface already exists. Nothing to do.`
         )
       );
     }
 
+    const created = await writeSurfaceEntry(cwd, surface);
+    if (created.isErr()) {
+      return Result.err(created.error);
+    }
+
+    const dependency = await updatePkgJsonForSurface(cwd, surface);
+    if (dependency.isErr()) {
+      return Result.err(dependency.error);
+    }
+
     return Result.ok({
-      created: await writeSurfaceEntry(cwd, surface),
-      dependency: await updatePkgJsonForSurface(cwd, surface),
+      created: created.value,
+      dependency: dependency.value,
     });
   },
   description: 'Add a surface to an existing project',

package/src/trails/add-trail.ts

@@ -2,12 +2,20 @@
  * `add.trail` trail -- Scaffold a new trail file with tests.
  */
 
-import { mkdirSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { resolve } from 'node:path';
 
 import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
+import {
+  trailIdToExportName,
+  trailIdToModuleName,
+  TRAIL_ID_MESSAGE,
+  TRAIL_ID_PATTERN,
+  validateTrailId,
+  writeProjectFile,
+} from '../project-writes.js';
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -22,13 +30,15 @@ const generateTrailFile = (
   exampleName: string,
   intent: 'read' | 'write' | 'destroy'
 ): string => {
-  const intentLine = intent === 'write' ? '' : `\n  intent: '${intent}',`;
+  const intentLine =
+    intent === 'write' ? '' : `\n  intent: ${literal(intent)},`;
   const exampleMessage = deriveExampleMessage(id);
+  const trailName = trailIdToExportName(id);
 
   return `import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
-export const ${id.replaceAll('.', '_')} = trail('${id}', {
+export const ${trailName} = trail(${literal(id)}, {
   blaze: async () => {
     return Result.ok({ message: ${literal(exampleMessage)} });
   },
@@ -47,8 +57,8 @@ export const ${id.replaceAll('.', '_')} = trail('${id}', {
 };
 
 const generateTestFile = (id: string, exampleName: string): string => {
-  const moduleName = id.replaceAll('.', '-');
-  const trailName = id.replaceAll('.', '_');
+  const moduleName = trailIdToModuleName(id);
+  const trailName = trailIdToExportName(id);
   const exampleMessage = deriveExampleMessage(id);
   return `import { testTrail } from '@ontrails/testing';
 import { ${trailName} } from '../src/trails/${moduleName}.js';
@@ -67,20 +77,16 @@ testTrail(${trailName}, [
 // Trail definition
 // ---------------------------------------------------------------------------
 
-/** Write a file, creating parent directories as needed. */
-const writeWithDirs = async (
-  filePath: string,
-  content: string
-): Promise<void> => {
-  mkdirSync(dirname(filePath), { recursive: true });
-  await Bun.write(filePath, content);
-};
-
 export const addTrail = trail('add.trail', {
   args: ['id'],
   blaze: async (input, ctx) => {
     const { id } = input;
-    const moduleName = id.replaceAll('.', '-');
+    const validated = validateTrailId(id);
+    if (validated.isErr()) {
+      return Result.err(validated.error);
+    }
+
+    const moduleName = trailIdToModuleName(validated.value);
     const cwd = resolve(ctx.cwd ?? '.');
 
     const files = new Map<string, string>([
@@ -100,7 +106,10 @@ export const addTrail = trail('add.trail', {
     ]);
 
     for (const [relativePath, content] of files) {
-      await writeWithDirs(join(cwd, relativePath), content);
+      const written = await writeProjectFile(cwd, relativePath, content);
+      if (written.isErr()) {
+        return Result.err(written.error);
+      }
     }
 
     return Result.ok({ created: [...files.keys()] });
@@ -118,6 +127,7 @@ export const addTrail = trail('add.trail', {
     id: z
       .string()
       .min(1, 'Trail ID is required')
+      .regex(TRAIL_ID_PATTERN, TRAIL_ID_MESSAGE)
       .describe('Trail ID (e.g., entity.update)'),
     intent: z
       .enum(['read', 'write', 'destroy'])