@ontrails/trails 1.0.0-beta.4 → 1.0.0-beta.42

package/src/trails/add-trail.ts

@@ -2,50 +2,73 @@
  * `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
 // ---------------------------------------------------------------------------
 
+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 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}', {
-  description: 'TODO: describe this trail',
+export const ${trailName} = trail(${literal(id)}, {
+  implementation: async () => {
+    return Result.ok({ message: ${literal(exampleMessage)} });
+  },
+  description: ${literal(description)},
   examples: [
     {
+      expected: { message: ${literal(exampleMessage)} },
       input: {},
-      name: 'TODO: add example',
+      name: ${literal(exampleName)},
     },
   ],
-  run: async (input) => {
-    return Result.ok({ message: 'TODO' });
-  },
   input: z.object({}),${intentLine}
   output: z.object({ message: z.string() }),
 });
 `;
 };
 
-const generateTestFile = (id: string): string => {
-  const moduleName = id.replaceAll('.', '-');
-  const trailName = id.replaceAll('.', '_');
+const generateTestFile = (id: string, exampleName: string): string => {
+  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';
 
 testTrail(${trailName}, [
-  { description: 'basic test', input: {}, expectOk: true },
+  {
+    description: ${literal(exampleName)},
+    expectValue: { message: ${literal(exampleMessage)} },
+    input: {},
+  },
 ]);
 `;
 };
@@ -54,41 +77,65 @@ 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'],
   description: 'Scaffold a new trail with tests and examples',
-  input: z.object({
-    id: z.string().describe('Trail ID (e.g., entity.update)'),
-    intent: z
-      .enum(['read', 'write', 'destroy'])
-      .default('write')
-      .describe('Trail intent'),
-  }),
-  output: z.object({
-    created: z.array(z.string()),
-  }),
-  run: async (input, ctx) => {
+  implementation: async (input, ctx) => {
     const { id } = input;
-    const moduleName = id.replaceAll('.', '-');
+    const validated = validateTrailId(id);
+    if (validated.isErr()) {
+      return validated;
+    }
+
+    const moduleName = trailIdToModuleName(validated.value);
     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) {
-      await writeWithDirs(join(cwd, relativePath), content);
+      const written = await writeProjectFile(cwd, relativePath, content);
+      if (written.isErr()) {
+        return written;
+      }
     }
 
     return Result.ok({ created: [...files.keys()] });
   },
+  input: z.object({
+    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')
+      .regex(TRAIL_ID_PATTERN, TRAIL_ID_MESSAGE)
+      .describe('Trail ID (e.g., entity.update)'),
+    intent: z
+      .enum(['read', 'write', 'destroy'])
+      .default('write')
+      .describe('Trail intent'),
+  }),
+  output: z.object({
+    created: z.array(z.string()),
+  }),
+  permit: { scopes: ['project:write'] },
 });

package/src/trails/add-verify.ts

@@ -2,36 +2,63 @@
  * `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,
+  projectPathExists,
+  resolveProjectDir,
+  resolveProjectPath,
+  writeProjectFile,
+} from '../project-writes.js';
+import {
+  ontrailsPackageRange,
+  scaffoldDependencyVersions,
+} from '../versions.js';
+import { stringifyScaffoldPackageJson } from './scaffold-json.js';
+
 // ---------------------------------------------------------------------------
 // Content generators
 // ---------------------------------------------------------------------------
 
 const generateTestFile = (): string =>
-  `import { testAll } from '@ontrails/testing';
+  `import { testAllEstablished } from '@ontrails/testing/established';
 import { app } from '../src/app.js';
 
-testAll(app);
+const permitScopes = [
+  ...new Set(
+    app
+      .list()
+      .flatMap((trail) =>
+        trail.permit && trail.permit !== 'public' ? trail.permit.scopes : []
+      )
+  ),
+];
+
+testAllEstablished(app, {
+  ctx: {
+    permit: { id: 'test-permit', scopes: permitScopes },
+  },
+});
 `;
 
 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))
   );
@@ -40,14 +67,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 pkgPathResult;
+  }
+
+  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',
+    stringifyScaffoldPackageJson(pkg)
+  );
+  return written.isErr() ? Result.err(written.error) : Result.ok();
 };
 
 // ---------------------------------------------------------------------------
@@ -56,32 +93,65 @@ const updatePackageJsonForVerify = async (
 
 export const addVerify = trail('add.verify', {
   description: 'Add testing and warden verification',
-  input: z.object({
-    dir: z.string().optional().describe('Parent directory'),
-    name: z.string().describe('Project name'),
-  }),
-  metadata: { internal: true },
-  output: z.object({
-    created: z.array(z.string()),
-  }),
-  run: async (input) => {
-    const projectDir = resolve(input.dir ?? '.', input.name);
+  implementation: async (input) => {
+    const projectDirResult = resolveProjectDir(input.dir ?? '.', input.name);
+    if (projectDirResult.isErr()) {
+      return projectDirResult;
+    }
+
+    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 exists = projectPathExists(projectDir, relativePath);
+      if (exists.isErr()) {
+        return exists;
+      }
+      if (exists.value) {
+        return Result.ok();
+      }
+
+      const written = await writeProjectFile(projectDir, relativePath, content);
+      if (written.isErr()) {
+        return written;
+      }
+      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 testFile;
+    }
+
+    const lefthookFile = await writeFile('lefthook.yml', generateLefthookYml());
+    if (lefthookFile.isErr()) {
+      return lefthookFile;
+    }
+
+    const packageResult = await updatePackageJsonForVerify(projectDir);
+    if (packageResult.isErr()) {
+      return packageResult;
+    }
 
     return Result.ok({ created: files });
   },
+  input: z.object({
+    dir: z.string().optional().describe('Parent directory'),
+    name: z
+      .string()
+      .regex(PROJECT_NAME_PATTERN, PROJECT_NAME_MESSAGE)
+      .describe('Project name'),
+  }),
+  output: z.object({
+    created: z.array(z.string()),
+  }),
+  permit: { scopes: ['project:write'] },
+  visibility: 'internal',
 });

package/src/trails/compile.ts

@@ -0,0 +1,58 @@
+import { trail } from '@ontrails/core';
+import type { Result, Topo } from '@ontrails/core';
+import type { TopoGraphOverlayRegistration } from '@ontrails/topography';
+import { z } from 'zod';
+
+import { withFreshOperatorApp } from './operator-context.js';
+import { exportCurrentTopo } from './topo-store-support.js';
+import type { TopoExportReport } from './topo-support.js';
+import {
+  createIsolatedExampleInput,
+  topoSnapshotOutput,
+} from './topo-support.js';
+
+export const compileCurrentTopo = async (
+  app: Topo,
+  options?: {
+    readonly force?: boolean | undefined;
+    readonly rootDir?: string;
+    readonly overlays?: readonly TopoGraphOverlayRegistration[] | undefined;
+  }
+): Promise<Result<TopoExportReport, Error>> => exportCurrentTopo(app, options);
+
+const compileTrailInputSchema = z.object({
+  force: z
+    .boolean()
+    .optional()
+    .describe('Record graph-only force events for breaking changes'),
+  module: z.string().optional().describe('Path to the app module'),
+  rootDir: z.string().optional().describe('Workspace root directory'),
+});
+
+type CompileTrailInput = z.output<typeof compileTrailInputSchema>;
+
+export const compileTrail = trail('compile', {
+  description: 'Compile the current topo to trails.lock',
+  examples: [
+    {
+      input: createIsolatedExampleInput('compile'),
+      name: 'Compile the current topo to trails.lock',
+    },
+  ],
+  implementation: async (input: CompileTrailInput, ctx) =>
+    withFreshOperatorApp(input, ctx, ({ lease, rootDir }) =>
+      compileCurrentTopo(lease.app, {
+        force: input.force,
+        overlays: lease.overlays,
+        rootDir,
+      })
+    ),
+  input: compileTrailInputSchema,
+  intent: 'write',
+  output: z.object({
+    hash: z.string(),
+    lockPath: z.string(),
+    snapshot: topoSnapshotOutput,
+  }),
+  permit: { scopes: ['topo:write'] },
+});

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', {
+  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',
+    },
+  ],
+  implementation: async (input, ctx) => {
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return rootDirResult;
+    }
+    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));
+  },
+  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'],
+  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',
+    },
+  ],
+  implementation: async (input) =>
+    renderCompletionScript(input.shell, COMPLETIONS_BIN_NAME),
+  input: z.object({
+    shell: z
+      .enum(['bash', 'zsh', 'fish'])
+      .describe('Target shell flavor for the completion script'),
+  }),
+  intent: 'read',
+  output: z.string(),
+});