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

package/src/trails/add-verify.ts

@@ -2,12 +2,18 @@
  * `add.verify` trail -- Add testing + warden setup to a project.
  */
 
-import { existsSync, mkdirSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { existsSync } from 'node:fs';
 
 import { Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
+import {
+  PROJECT_NAME_MESSAGE,
+  PROJECT_NAME_PATTERN,
+  resolveProjectDir,
+  resolveProjectPath,
+  writeProjectFile,
+} from '../project-writes.js';
 import {
   ontrailsPackageRange,
   scaffoldDependencyVersions,
@@ -45,14 +51,24 @@ const patchVerifyDeps = (pkg: Record<string, unknown>): void => {
 /** Update package.json in the target project with verify dependencies. */
 const updatePackageJsonForVerify = async (
   projectDir: string
-): Promise<void> => {
-  const pkgPath = join(projectDir, 'package.json');
+): Promise<Result<void, Error>> => {
+  const pkgPathResult = resolveProjectPath(projectDir, 'package.json');
+  if (pkgPathResult.isErr()) {
+    return Result.err(pkgPathResult.error);
+  }
+
+  const pkgPath = pkgPathResult.value;
   if (!existsSync(pkgPath)) {
-    return;
+    return Result.ok();
   }
   const pkg = (await Bun.file(pkgPath).json()) as Record<string, unknown>;
   patchVerifyDeps(pkg);
-  await Bun.write(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+  const written = await writeProjectFile(
+    projectDir,
+    'package.json',
+    `${JSON.stringify(pkg, null, 2)}\n`
+  );
+  return written.isErr() ? Result.err(written.error) : Result.ok();
 };
 
 // ---------------------------------------------------------------------------
@@ -61,32 +77,56 @@ const updatePackageJsonForVerify = async (
 
 export const addVerify = trail('add.verify', {
   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 files: string[] = [];
 
     const writeFile = async (
       relativePath: string,
       content: string
-    ): Promise<void> => {
-      const fullPath = join(projectDir, relativePath);
-      mkdirSync(dirname(fullPath), { recursive: true });
-      await Bun.write(fullPath, content);
-      files.push(relativePath);
+    ): Promise<Result<void, Error>> => {
+      const written = await writeProjectFile(projectDir, relativePath, content);
+      if (written.isErr()) {
+        return Result.err(written.error);
+      }
+      files.push(written.value);
+      return Result.ok();
     };
 
-    await writeFile('__tests__/examples.test.ts', generateTestFile());
-    await writeFile('lefthook.yml', generateLefthookYml());
-    await updatePackageJsonForVerify(projectDir);
+    const testFile = await writeFile(
+      '__tests__/examples.test.ts',
+      generateTestFile()
+    );
+    if (testFile.isErr()) {
+      return Result.err(testFile.error);
+    }
+
+    const lefthookFile = await writeFile('lefthook.yml', generateLefthookYml());
+    if (lefthookFile.isErr()) {
+      return Result.err(lefthookFile.error);
+    }
+
+    const packageResult = await updatePackageJsonForVerify(projectDir);
+    if (packageResult.isErr()) {
+      return Result.err(packageResult.error);
+    }
 
     return Result.ok({ created: files });
   },
   description: 'Add testing and warden verification',
   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'),
   }),
-  meta: { internal: true },
   output: z.object({
     created: z.array(z.string()),
   }),
+  visibility: 'internal',
 });

package/src/trails/completions-complete.ts

@@ -0,0 +1,165 @@
+/**
+ * `completions __complete` internal trail -- dynamic completion suggestions.
+ *
+ * The static shell scripts emitted by {@link completionsTrail} delegate to this
+ * trail at tab-press time. The trail receives the partial argv that the user
+ * has typed (after the binary name) and returns newline-delimited suggestions
+ * the shell should offer.
+ *
+ * Today the trail knows about two `run` positions:
+ *
+ *  - `trails run <prefix>` — return matching trail IDs.
+ *  - `trails run example <trail-id> <prefix>` — return matching example names
+ *    defined on the resolved trail.
+ *
+ * The `run example` branch loads the trail's owning app at tab-press time so the
+ * suggestions reflect the live trail definition. Unknown trails and no
+ * examples naturally collapse to an empty list; recoverable load failures are
+ * suppressed here because completion must never surface errors back to the
+ * shell mid-keystroke.
+ */
+
+import { Result, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import {
+  renderTrailExampleCompletions,
+  renderTrailIdCompletions,
+} from '../completions.js';
+import { resolveTrailRootDir } from './root-dir.js';
+
+const EMPTY_SUGGESTIONS = '';
+
+interface CompleteContext {
+  readonly args: readonly string[];
+  readonly rootDir: string;
+}
+
+type CompletionHandler = (ctx: CompleteContext) => Promise<readonly string[]>;
+
+/**
+ * Detect whether the user is completing the example-name positional on a
+ * `trails run example` invocation.
+ *
+ * The shell hands us the partial argv with the **last element** as the token
+ * being completed. We recognize the `run example <trail-id> <TAB>` shape when:
+ *
+ *  - the command family is `run example`, and
+ *  - a non-flag positional (the trail ID) sits at `args[2]`.
+ *
+ * Returns the trail ID + prefix to complete, or `null` if the cursor is not
+ * in an example-name value position.
+ */
+const detectExampleValueCompletion = (
+  args: readonly string[]
+): { readonly trailId: string; readonly prefix: string } | null => {
+  if (args.length < 4) {
+    return null;
+  }
+  const [, subcommand, trailId] = args;
+  if (subcommand !== 'example') {
+    return null;
+  }
+  if (trailId === undefined || trailId.startsWith('-')) {
+    return null;
+  }
+  const prefix = args[3] ?? '';
+  return { prefix, trailId };
+};
+
+/**
+ * Handler for the `trails run` subcommand.
+ *
+ * Two completion positions are recognized:
+ *
+ *  - `trails run example <trail-id> <prefix>` — return example names defined
+ *    on the resolved trail (matching `prefix`, sorted).
+ *  - `trails run <prefix>` — return matching trail IDs.
+ *
+ * Anything else (unknown flag context, a cursor beyond the trail ID, etc.)
+ * returns no suggestions so completed positional values are not suggested
+ * again.
+ */
+const completeRunPosition: CompletionHandler = async ({ args, rootDir }) => {
+  const exampleContext = detectExampleValueCompletion(args);
+  if (exampleContext !== null) {
+    const suggestionsResult = await renderTrailExampleCompletions(
+      rootDir,
+      exampleContext.trailId,
+      exampleContext.prefix
+    );
+    return suggestionsResult.unwrapOr([]);
+  }
+  if (args.length !== 2) {
+    return [];
+  }
+  const prefix = args[1] ?? '';
+  return await renderTrailIdCompletions(rootDir, prefix);
+};
+
+const renderSuggestions = (suggestions: readonly string[]): string =>
+  suggestions.join('\n');
+
+/**
+ * Subcommand → handler dispatch table.
+ *
+ * Keep this a pure lookup so adding a new completion target (`run example`,
+ * `--app`, etc.) is a new entry rather than a new branch.
+ *
+ * @remarks As more handlers grow per-token-shape logic (e.g. distinguishing
+ * `--app <TAB>` vs `<trail-id> <TAB>` for the same subcommand), expect this
+ * table to evolve into a sub-table of (token-pattern → completion-fn) per
+ * subcommand or a small parser yielding a discriminated `CompletionContext`
+ * union. Today the single `'run'` entry is small enough that explicit
+ * branching inside `completeRunPosition` is cleaner.
+ */
+const SUBCOMMAND_HANDLERS: Readonly<Record<string, CompletionHandler>> = {
+  run: completeRunPosition,
+};
+
+export const completionsCompleteTrail = trail('completions.__complete', {
+  blaze: async (input, ctx) => {
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return Result.err(rootDirResult.error);
+    }
+    const rootDir = rootDirResult.value;
+
+    const [subcommand] = input.args;
+    if (subcommand === undefined) {
+      return Result.ok(EMPTY_SUGGESTIONS);
+    }
+
+    const handler = SUBCOMMAND_HANDLERS[subcommand];
+    if (handler === undefined) {
+      return Result.ok(EMPTY_SUGGESTIONS);
+    }
+
+    const suggestions = await handler({ args: input.args, rootDir });
+    return Result.ok(renderSuggestions(suggestions));
+  },
+  description:
+    'Internal: emit dynamic completion suggestions for the current partial argv. Invoked by the static shell completion script at tab-press time.',
+  examples: [
+    {
+      description: 'Empty argv yields no suggestions',
+      input: { args: [] },
+      name: 'Empty args',
+    },
+  ],
+  input: z.object({
+    args: z
+      .array(z.string())
+      .readonly()
+      .describe(
+        'Partial argv after the binary name; the last element is the token being completed'
+      ),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+  }),
+  intent: 'read',
+  output: z
+    .string()
+    .describe(
+      'Newline-delimited suggestions the shell should offer for the current token'
+    ),
+});

package/src/trails/completions.ts

@@ -0,0 +1,47 @@
+/**
+ * `completions` trail -- Print a shell completion script for the `trails` CLI.
+ *
+ * The trail's responsibility is small: render a static shell script that, when
+ * sourced by the user's shell, registers a tab-completion handler that
+ * delegates to `trails completions __complete <args...>` for the live
+ * suggestions. See {@link renderCompletionScript} for the per-shell shape.
+ */
+
+import { trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { renderCompletionScript } from '../completions.js';
+
+const COMPLETIONS_BIN_NAME = 'trails';
+
+export const completionsTrail = trail('completions', {
+  args: ['shell'],
+  blaze: async (input) =>
+    renderCompletionScript(input.shell, COMPLETIONS_BIN_NAME),
+  description:
+    'Print a shell completion script for the trails CLI; pipe into your shell rc to register tab-completion',
+  examples: [
+    {
+      description: 'Render a bash completion script',
+      input: { shell: 'bash' },
+      name: 'Render bash completion',
+    },
+    {
+      description: 'Render a zsh completion script',
+      input: { shell: 'zsh' },
+      name: 'Render zsh completion',
+    },
+    {
+      description: 'Render a fish completion script',
+      input: { shell: 'fish' },
+      name: 'Render fish completion',
+    },
+  ],
+  input: z.object({
+    shell: z
+      .enum(['bash', 'zsh', 'fish'])
+      .describe('Target shell flavor for the completion script'),
+  }),
+  intent: 'read',
+  output: z.string(),
+});

package/src/trails/create-scaffold.ts

@@ -4,12 +4,22 @@
  * 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,
@@ -24,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[];
 }
 
 // ---------------------------------------------------------------------------
@@ -44,6 +56,7 @@ const generatePackageJson = (name: string): string => {
     devDependencies: Object.fromEntries(
       Object.entries({
         '@types/bun': scaffoldDependencyVersions.bunTypes,
+        oxfmt: scaffoldDependencyVersions.oxfmt,
         oxlint: scaffoldDependencyVersions.oxlint,
         typescript: scaffoldDependencyVersions.typescript,
         ultracite: scaffoldDependencyVersions.ultracite,
@@ -52,6 +65,8 @@ const generatePackageJson = (name: string): string => {
     name,
     scripts: {
       build: 'tsc -b',
+      'format:check': 'bunx ultracite check .',
+      'format:fix': 'bunx ultracite fix .',
       lint: 'oxlint ./src',
       test: 'bun test',
       typecheck: 'tsc --noEmit',
@@ -86,16 +101,19 @@ const TSCONFIG_CONTENT = JSON.stringify(
 const GITIGNORE_CONTENT = `node_modules/
 dist/
 *.tsbuildinfo
-.trails/_surface.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
@@ -273,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';",
@@ -309,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
@@ -335,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

@@ -5,9 +5,14 @@
  * via ctx.cross.
  */
 
-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
 // ---------------------------------------------------------------------------
@@ -106,7 +111,7 @@ const collectCreatedFiles = (
 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'));
     }
     const { cross } = ctx;
 
@@ -189,7 +194,10 @@ export const createRoute = trail('create', {
   },
   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')

package/src/trails/dev-clean.ts

@@ -5,6 +5,7 @@ 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', {
@@ -17,7 +18,11 @@ 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,

package/src/trails/dev-reset.ts

@@ -2,6 +2,7 @@ import { Result, ValidationError, trail } from '@ontrails/core';
 import { z } from 'zod';
 
 import { resetDevState } from './dev-support.js';
+import { resolveTrailRootDir } from './root-dir.js';
 import { createIsolatedExampleInput } from './topo-support.js';
 
 export const devResetTrail = trail('dev.reset', {
@@ -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',

package/src/trails/dev-stats.ts

@@ -5,11 +5,16 @@ import {
   buildDevStats,
   DEFAULT_TOPO_SNAPSHOT_RETENTION,
 } from './dev-support.js';
+import { resolveTrailRootDir } from './root-dir.js';
 import { createIsolatedExampleInput } from './topo-support.js';
 
 export const devStatsTrail = trail('dev.stats', {
   blaze: (input, ctx) => {
-    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(
       buildDevStats({
         maxAge: input.traceAgeMs,