@ontrails/trails 1.0.0-beta.23 → 1.0.0-beta.29

package/src/trails/guide.ts

@@ -7,7 +7,7 @@
 import { NotFoundError, Result, trail } from '@ontrails/core';
 import { z } from 'zod';
 
-import { tryLoadFreshAppLease } from './load-app.js';
+import { withFreshOperatorApp } from './operator-context.js';
 import { trailDetailOutput } from './topo-output-schemas.js';
 import {
   buildCurrentGuideEntries,
@@ -15,7 +15,6 @@ import {
   readSurfaceLayerNamesFromContext,
 } from './topo-read-support.js';
 import { createIsolatedExampleInput } from './topo-support.js';
-import { resolveTrailRootDir } from './root-dir.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -28,6 +27,16 @@ interface GuideEntry {
   readonly kind: 'trail';
 }
 
+type GuideTrailOutput =
+  | {
+      readonly entries: GuideEntry[];
+      readonly mode: 'list';
+    }
+  | {
+      readonly detail: z.output<typeof trailDetailOutput>;
+      readonly mode: 'detail';
+    };
+
 const guideTrailInputSchema = z.object({
   module: z.string().optional().describe('Path to the app module'),
   rootDir: z.string().optional().describe('Workspace root directory'),
@@ -41,21 +50,11 @@ type GuideTrailInput = z.output<typeof guideTrailInputSchema>;
 // ---------------------------------------------------------------------------
 
 export const guideTrail = trail('guide', {
-  blaze: async (input: GuideTrailInput, 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 {
+  blaze: async (input: GuideTrailInput, ctx) =>
+    withFreshOperatorApp<GuideTrailOutput>(input, ctx, ({ lease, rootDir }) => {
       if (input.trailId) {
         const detail = buildCurrentTopoDetail(lease.app, input.trailId, {
+          cliAliases: lease.cliAliases,
           rootDir,
           surfaceLayerNames: readSurfaceLayerNamesFromContext(ctx),
         });
@@ -76,10 +75,7 @@ export const guideTrail = trail('guide', {
         }) as GuideEntry[],
         mode: 'list' as const,
       });
-    } finally {
-      lease.release();
-    }
-  },
+    }),
   description: 'Runtime guidance for trails',
   examples: [
     {

package/src/trails/load-app.ts

@@ -23,7 +23,7 @@ import {
   Result,
   ValidationError,
 } from '@ontrails/core';
-import type { Topo } from '@ontrails/core';
+import type { CliCommandAliasInput, Topo } from '@ontrails/core';
 import { findAppModule } from '@ontrails/cli';
 
 import {
@@ -1054,8 +1054,52 @@ const resolveLoadedTopo = (
   return app;
 };
 
+type LoadedCliAliases = Readonly<
+  Record<string, readonly CliCommandAliasInput[]>
+>;
+
+const isStringArray = (value: unknown): value is readonly string[] =>
+  Array.isArray(value) && value.every((item) => typeof item === 'string');
+
+const isCliAliasInput = (value: unknown): value is CliCommandAliasInput =>
+  typeof value === 'string' || isStringArray(value);
+
+const resolveLoadedCliAliases = (
+  effectivePath: string,
+  mod: Record<string, unknown>
+): LoadedCliAliases | undefined => {
+  const value = mod['trailsCliAliases'] ?? mod['cliAliases'];
+  if (value === undefined) {
+    return undefined;
+  }
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new ValidationError(
+      `CLI alias export in "${effectivePath}" must be a record from trail ID to alias list.`
+    );
+  }
+
+  const aliases = value as Record<string, unknown>;
+  for (const [trailId, trailAliases] of Object.entries(aliases)) {
+    if (!Array.isArray(trailAliases)) {
+      throw new ValidationError(
+        `CLI alias export for trail "${trailId}" in "${effectivePath}" must be an array.`
+      );
+    }
+    for (const alias of trailAliases) {
+      if (!isCliAliasInput(alias)) {
+        throw new ValidationError(
+          `CLI alias export for trail "${trailId}" in "${effectivePath}" must contain string aliases or string-array paths.`
+        );
+      }
+    }
+  }
+
+  return aliases as LoadedCliAliases;
+};
+
 export interface FreshAppLease {
   readonly app: Topo;
+  readonly cliAliases?: LoadedCliAliases | undefined;
   readonly mirrorRoot: string;
   readonly release: () => void;
 }
@@ -1071,14 +1115,18 @@ const noopRelease = (): void => undefined;
 const createUrlSchemeLease = async (
   absolutePath: string,
   effectivePath: string
-): Promise<FreshAppLease> => ({
-  app: resolveLoadedTopo(
-    effectivePath,
-    await importWithCacheBust(absolutePath)
-  ),
-  mirrorRoot: absolutePath,
-  release: noopRelease,
-});
+): Promise<FreshAppLease> => {
+  const mod = (await importWithCacheBust(absolutePath)) as Record<
+    string,
+    unknown
+  >;
+  return {
+    app: resolveLoadedTopo(effectivePath, mod),
+    cliAliases: resolveLoadedCliAliases(effectivePath, mod),
+    mirrorRoot: absolutePath,
+    release: noopRelease,
+  };
+};
 
 const createFilesystemLease = async (
   absolutePath: string,
@@ -1096,6 +1144,7 @@ const createFilesystemLease = async (
 
     return {
       app: resolveLoadedTopo(effectivePath, mod),
+      cliAliases: resolveLoadedCliAliases(effectivePath, mod),
       mirrorRoot,
       release,
     };

package/src/trails/operator-context.ts

@@ -0,0 +1,66 @@
+import type { Result } from '@ontrails/core';
+
+import { tryLoadFreshAppLease } from './load-app.js';
+import type { FreshAppLease } from './load-app.js';
+import { resolveTrailRootDir } from './root-dir.js';
+
+interface RootDirInput {
+  readonly rootDir?: string | undefined;
+}
+
+interface FreshAppInput extends RootDirInput {
+  readonly module?: string | undefined;
+}
+
+interface RootDirContext {
+  readonly cwd?: string | undefined;
+}
+
+interface FreshAppContext {
+  readonly lease: FreshAppLease;
+  readonly rootDir: string;
+}
+
+export const withOperatorRootDir = async <T>(
+  input: RootDirInput,
+  ctx: RootDirContext,
+  consume: (rootDir: string) => Result<T, Error> | Promise<Result<T, Error>>
+): Promise<Result<T, Error>> => {
+  const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+  if (rootDirResult.isErr()) {
+    return rootDirResult;
+  }
+  return await consume(rootDirResult.value);
+};
+
+export const withFreshAppLease = async <T>(
+  modulePath: string | undefined,
+  rootDir: string,
+  consume: (
+    lease: FreshAppLease
+  ) => Result<T, Error> | Promise<Result<T, Error>>
+): Promise<Result<T, Error>> => {
+  const leaseResult = await tryLoadFreshAppLease(modulePath, rootDir);
+  if (leaseResult.isErr()) {
+    return leaseResult;
+  }
+  const lease = leaseResult.value;
+  try {
+    return await consume(lease);
+  } finally {
+    lease.release();
+  }
+};
+
+export const withFreshOperatorApp = async <T>(
+  input: FreshAppInput,
+  ctx: RootDirContext,
+  consume: (
+    context: FreshAppContext
+  ) => Result<T, Error> | Promise<Result<T, Error>>
+): Promise<Result<T, Error>> =>
+  withOperatorRootDir(input, ctx, (rootDir) =>
+    withFreshAppLease(input.module, rootDir, (lease) =>
+      consume({ lease, rootDir })
+    )
+  );

package/src/trails/regrade.ts

@@ -0,0 +1,72 @@
+/**
+ * `regrade` trail -- Run downstream migration checks and safe rewrites.
+ */
+
+import { NotFoundError, Result, trail, validateOutput } from '@ontrails/core';
+import type { Result as TrailsResult } from '@ontrails/core';
+import {
+  regradeReportOutput,
+  runRegrade,
+  wardenTermRewriteClasses,
+} from '@ontrails/regrade';
+import type { RegradeReport } from '@ontrails/regrade';
+import { z } from 'zod';
+
+import { resolveTrailRootDir } from './root-dir.js';
+
+const regradeInputSchema = z.object({
+  apply: z
+    .boolean()
+    .default(false)
+    .describe('Write safe rewrites to disk; dry-run report only by default'),
+  classIds: z
+    .array(z.string())
+    .optional()
+    .describe('Regrade class ids to run (defaults to all built-in classes)'),
+  rootDir: z.string().optional().describe('Workspace root directory'),
+});
+
+export const regradeTrail = trail('regrade', {
+  blaze: (input, ctx) => {
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return rootDirResult;
+    }
+
+    const reportResult: TrailsResult<RegradeReport | null, Error> = runRegrade({
+      apply: input.apply,
+      classes: wardenTermRewriteClasses,
+      root: rootDirResult.value,
+      ...(input.classIds === undefined
+        ? {}
+        : { selection: { classIds: input.classIds } }),
+    });
+    if (reportResult.isErr()) {
+      return reportResult;
+    }
+
+    const report = reportResult.value;
+    if (report === null) {
+      return Result.err(
+        new NotFoundError(
+          `Regrade root "${rootDirResult.value}" could not be read as a directory.`
+        )
+      );
+    }
+
+    const validated: TrailsResult<
+      z.output<typeof regradeReportOutput>,
+      Error
+    > = validateOutput(regradeReportOutput, report);
+    if (validated.isErr()) {
+      return validated;
+    }
+
+    return Result.ok(validated.value);
+  },
+  description: 'Run downstream migration checks and safe rewrites',
+  input: regradeInputSchema,
+  intent: 'write',
+  output: regradeReportOutput,
+  permit: 'public',
+});

package/src/trails/release-check.ts

@@ -45,6 +45,7 @@ const contractReleaseFactSchema = z.object({
 });
 
 const releaseCheckOutputSchema = z.object({
+  activePackageChangesetsWithoutReleaseFacts: z.array(z.string()).readonly(),
   affectedPackages: z.array(z.string()).readonly(),
   changedChangesets: z.array(z.string()).readonly(),
   configPath: z.string().optional(),

package/src/trails/run-example.ts

@@ -13,9 +13,8 @@ import {
 import type { BasePermit, StructuredTrailExample, Topo } from '@ontrails/core';
 import { z } from 'zod';
 
-import { tryLoadFreshAppLease } from './load-app.js';
+import { withFreshAppLease, withOperatorRootDir } from './operator-context.js';
 import { resolveRunModulePath } from './run.js';
-import { resolveTrailRootDir } from './root-dir.js';
 import { createIsolatedExampleInput } from './topo-support.js';
 
 export const RUN_EXAMPLE_COMPARISON_KIND = 'example-comparison' as const;
@@ -355,7 +354,7 @@ const buildComparisonEnvelope = async (
 ): Promise<Result<RunExampleComparison, Error>> => {
   const exampleResult = findExample(app, trailId, exampleName);
   if (exampleResult.isErr()) {
-    return Result.err(exampleResult.error);
+    return exampleResult;
   }
   const example = exampleResult.value;
   const mode = determineMode(example);
@@ -440,42 +439,27 @@ type RunExampleTrailInput = z.output<typeof runExampleTrailInputSchema>;
 
 export const runExampleTrail = trail('run.example', {
   args: ['id', 'exampleName'],
-  blaze: async (input: RunExampleTrailInput, ctx) => {
-    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
-    if (rootDirResult.isErr()) {
-      return rootDirResult;
-    }
-    const rootDir = rootDirResult.value;
-    const moduleResolution = await resolveRunModulePath(
-      rootDir,
-      input.module,
-      input.id,
-      input.app
-    );
-    if (moduleResolution.isErr()) {
-      return moduleResolution;
-    }
-
-    const leaseResult = await tryLoadFreshAppLease(
-      moduleResolution.value,
-      rootDir
-    );
-    if (leaseResult.isErr()) {
-      return leaseResult;
-    }
-    const lease = leaseResult.value;
-
-    try {
-      return await buildComparisonEnvelope(
-        lease.app,
+  blaze: async (input: RunExampleTrailInput, ctx) =>
+    withOperatorRootDir(input, ctx, async (rootDir) => {
+      const moduleResolution = await resolveRunModulePath(
+        rootDir,
+        input.module,
         input.id,
-        input.exampleName,
-        ctx.permit
+        input.app
       );
-    } finally {
-      lease.release();
-    }
-  },
+      if (moduleResolution.isErr()) {
+        return moduleResolution;
+      }
+
+      return withFreshAppLease(moduleResolution.value, rootDir, (lease) =>
+        buildComparisonEnvelope(
+          lease.app,
+          input.id,
+          input.exampleName,
+          ctx.permit
+        )
+      );
+    }),
   description: 'Run a named example on a trail and compare actual vs expected',
   examples: [
     {

package/src/trails/run-examples.ts

@@ -11,9 +11,8 @@ import {
 import type { StructuredTrailExample, Topo } from '@ontrails/core';
 import { z } from 'zod';
 
-import { tryLoadFreshAppLease } from './load-app.js';
+import { withFreshAppLease, withOperatorRootDir } from './operator-context.js';
 import { resolveRunModulePath } from './run.js';
-import { resolveTrailRootDir } from './root-dir.js';
 import { createIsolatedExampleInput } from './topo-support.js';
 
 export const RUN_EXAMPLES_LISTING_KIND = 'examples-listing' as const;
@@ -100,37 +99,22 @@ type RunExamplesTrailInput = z.output<typeof runExamplesTrailInputSchema>;
 
 export const runExamplesTrail = trail('run.examples', {
   args: ['id'],
-  blaze: async (input: RunExamplesTrailInput, ctx) => {
-    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
-    if (rootDirResult.isErr()) {
-      return rootDirResult;
-    }
-    const rootDir = rootDirResult.value;
-    const moduleResolution = await resolveRunModulePath(
-      rootDir,
-      input.module,
-      input.id,
-      input.app
-    );
-    if (moduleResolution.isErr()) {
-      return moduleResolution;
-    }
-
-    const leaseResult = await tryLoadFreshAppLease(
-      moduleResolution.value,
-      rootDir
-    );
-    if (leaseResult.isErr()) {
-      return leaseResult;
-    }
-    const lease = leaseResult.value;
+  blaze: async (input: RunExamplesTrailInput, ctx) =>
+    withOperatorRootDir(input, ctx, async (rootDir) => {
+      const moduleResolution = await resolveRunModulePath(
+        rootDir,
+        input.module,
+        input.id,
+        input.app
+      );
+      if (moduleResolution.isErr()) {
+        return moduleResolution;
+      }
 
-    try {
-      return buildExamplesListing(lease.app, input.id);
-    } finally {
-      lease.release();
-    }
-  },
+      return withFreshAppLease(moduleResolution.value, rootDir, (lease) =>
+        buildExamplesListing(lease.app, input.id)
+      );
+    }),
   description: "List a trail's examples without executing it",
   examples: [
     {

package/src/trails/run.ts

@@ -33,6 +33,7 @@ import {
   AmbiguousError,
   NotFoundError,
   Result,
+  ValidationError,
   run,
   trail,
 } from '@ontrails/core';
@@ -49,8 +50,7 @@ import {
   writeIsolatedExampleTextFile,
 } from '../local-state-io.js';
 
-import { tryLoadFreshAppLease } from './load-app.js';
-import { resolveTrailRootDir } from './root-dir.js';
+import { withFreshAppLease, withOperatorRootDir } from './operator-context.js';
 import { createIsolatedExampleInput } from './topo-support.js';
 
 export const INNER_TRAIL_RESULT_KIND = 'inner-trail-result' as const;
@@ -313,73 +313,97 @@ const buildAmbiguousExampleInput = (): {
   return { id: 'shared.id', rootDir: root };
 };
 
-const runTrailInputSchema = z.object({
-  app: z
-    .string()
-    .optional()
-    .describe(
-      'Workspace app to resolve the trail ID against; required when the ID is exposed by more than one app'
-    ),
-  id: z.string().describe('Trail ID to invoke'),
-  input: z
-    .unknown()
-    .optional()
-    .describe(
-      'Parsed input for the resolved trail; the CLI surface JSON.parses the inline argument before passing it through'
-    ),
-  module: z.string().optional().describe('Path to the app module'),
-  rootDir: z.string().optional().describe('Workspace root directory'),
-});
+const runTrailInputSchema = z
+  .object({
+    app: z
+      .string()
+      .optional()
+      .describe(
+        'Workspace app to resolve the trail ID against; required when the ID is exposed by more than one app'
+      ),
+    id: z.string().describe('Trail ID to invoke'),
+    input: z
+      .unknown()
+      .optional()
+      .describe(
+        'Parsed input for the resolved trail; the CLI surface JSON.parses the inline argument before passing it through'
+      ),
+    module: z.string().optional().describe('Path to the app module'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+  })
+  .catchall(z.unknown());
 
 type RunTrailInput = z.output<typeof runTrailInputSchema>;
 
+const RUN_TRAIL_CONTROL_KEYS = new Set([
+  'app',
+  'id',
+  'input',
+  'module',
+  'rootDir',
+]);
+
+const directInputEntries = (
+  input: RunTrailInput
+): readonly (readonly [string, unknown])[] =>
+  Object.entries(input).filter(([key]) => !RUN_TRAIL_CONTROL_KEYS.has(key));
+
+const resolveInnerTrailInput = (
+  input: RunTrailInput
+): Result<unknown, ValidationError> => {
+  const entries = directInputEntries(input);
+  if (entries.length === 0) {
+    return Result.ok(input.input);
+  }
+  if (Object.hasOwn(input, 'input')) {
+    return Result.err(
+      new ValidationError(
+        'trails run received both direct input fields and an explicit input wrapper. Use one shape: either {"name":"Alpha"} or {"input":{"name":"Alpha"}}.'
+      )
+    );
+  }
+  return Result.ok(Object.fromEntries(entries));
+};
+
 // ---------------------------------------------------------------------------
 // Trail definition
 // ---------------------------------------------------------------------------
 
 export const runTrail = trail('run', {
   args: ['id'],
-  blaze: async (input: RunTrailInput, ctx) => {
-    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
-    if (rootDirResult.isErr()) {
-      return rootDirResult;
-    }
-    const rootDir = rootDirResult.value;
-
-    // Single-app back-compat: if the caller provided `module`, trust it.
-    const moduleResolution = await resolveRunModulePath(
-      rootDir,
-      input.module,
-      input.id,
-      input.app
-    );
-    if (moduleResolution.isErr()) {
-      return moduleResolution;
-    }
-    const modulePath = moduleResolution.value;
-
-    const leaseResult = await tryLoadFreshAppLease(modulePath, rootDir);
-    if (leaseResult.isErr()) {
-      return leaseResult;
-    }
-    const lease = leaseResult.value;
+  blaze: async (input: RunTrailInput, ctx) =>
+    withOperatorRootDir(input, ctx, async (rootDir) => {
+      const innerInput = resolveInnerTrailInput(input);
+      if (innerInput.isErr()) {
+        return innerInput;
+      }
 
-    try {
-      const result = await run(lease.app, input.id, input.input, {
-        ctx: ctx.permit === undefined ? {} : { permit: ctx.permit },
-      });
-      if (result.isErr()) {
-        return Result.err(result.error);
+      // Single-app back-compat: if the caller provided `module`, trust it.
+      const moduleResolution = await resolveRunModulePath(
+        rootDir,
+        input.module,
+        input.id,
+        input.app
+      );
+      if (moduleResolution.isErr()) {
+        return moduleResolution;
       }
-      return Result.ok({
-        kind: INNER_TRAIL_RESULT_KIND,
-        trailId: input.id,
-        value: result.value,
+      const modulePath = moduleResolution.value;
+
+      return withFreshAppLease(modulePath, rootDir, async (lease) => {
+        const result = await run(lease.app, input.id, innerInput.value, {
+          ctx: ctx.permit === undefined ? {} : { permit: ctx.permit },
+        });
+        if (result.isErr()) {
+          return result;
+        }
+        return Result.ok({
+          kind: INNER_TRAIL_RESULT_KIND,
+          trailId: input.id,
+          value: result.value,
+        });
       });
-    } finally {
-      lease.release();
-    }
-  },
+    }),
   description:
     'Resolve a trail by ID in the current app and execute it through the shared pipeline',
   examples: [