@ontrails/trails 1.0.0-beta.2 → 1.0.0-beta.22

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 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',
+    stringifyScaffoldPackageJson(pkg)
+  );
+  return written.isErr() ? Result.err(written.error) : Result.ok();
 };
 
 // ---------------------------------------------------------------------------
@@ -55,33 +92,66 @@ const updatePackageJsonForVerify = async (
 // ---------------------------------------------------------------------------
 
 export const addVerify = trail('add.verify', {
-  description: 'Add testing and warden verification',
-  implementation: async (input) => {
-    const projectDir = resolve(input.dir ?? '.', input.name);
+  blaze: 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 Result.err(exists.error);
+      }
+      if (exists.value) {
+        return Result.ok();
+      }
+
+      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 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 });
   },
+  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'),
   }),
-  markers: { internal: true },
   output: z.object({
     created: z.array(z.string()),
   }),
+  permit: { scopes: ['project:write'] },
+  visibility: 'internal',
 });

package/src/trails/compile.ts

@@ -0,0 +1,67 @@
+import { trail } from '@ontrails/core';
+import type { Result, Topo } from '@ontrails/core';
+import { z } from 'zod';
+
+import { tryLoadFreshAppLease } from './load-app.js';
+import { resolveTrailRootDir } from './root-dir.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 }
+): 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', {
+  blaze: async (input: CompileTrailInput, ctx) => {
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return rootDirResult;
+    }
+    const rootDir = rootDirResult.value;
+    const leaseResult = await tryLoadFreshAppLease(input.module, rootDir);
+    if (leaseResult.isErr()) {
+      return leaseResult;
+    }
+    const lease = leaseResult.value;
+    try {
+      return await compileCurrentTopo(lease.app, {
+        force: input.force,
+        rootDir,
+      });
+    } finally {
+      lease.release();
+    }
+  },
+  description: 'Compile the current topo to .trails artifacts',
+  examples: [
+    {
+      input: createIsolatedExampleInput('compile'),
+      name: 'Compile the current topo artifacts',
+    },
+  ],
+  input: compileTrailInputSchema,
+  intent: 'write',
+  output: z.object({
+    hash: z.string(),
+    lockPath: z.string(),
+    snapshot: topoSnapshotOutput,
+    topoPath: z.string(),
+  }),
+  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', {
+  blaze: 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));
+  },
+  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(),
+});