@ontrails/trails 1.0.0-beta.3 → 1.0.0-beta.30

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/project.ts

@@ -5,10 +5,24 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 
+import { isDraftMarkedFile } from '@ontrails/warden';
+
 /** Return all TypeScript entries in a project's src directory. */
-const scanSourceEntries = (srcDir: string): string[] => [
-  ...new Bun.Glob('*.ts').scanSync({ cwd: srcDir }),
-];
+const sourceEntryPriority = (entry: string): number => {
+  if (entry === 'app.ts') {
+    return 0;
+  }
+  return isDraftMarkedFile(entry) ? 2 : 1;
+};
+
+const scanSourceEntries = (srcDir: string): string[] =>
+  [...new Bun.Glob('*.ts').scanSync({ cwd: srcDir })].toSorted((a, b) => {
+    const priority = sourceEntryPriority(a) - sourceEntryPriority(b);
+    if (priority === 0) {
+      return a.localeCompare(b);
+    }
+    return priority;
+  });
 
 /** Resolve an entry to an app import if it contains topo(). */
 const toTopoImport = async (

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

@@ -0,0 +1,105 @@
+/**
+ * `release.check` trail -- Branch-local release rule evaluation.
+ */
+
+import { Result, trail, ValidationError } from '@ontrails/core';
+import { z } from 'zod';
+
+import { runReleaseCheck } from '../release/check.js';
+import { resolveTrailRootDir } from './root-dir.js';
+
+const releaseCheckInputSchema = z.object({
+  baseRef: z
+    .string()
+    .optional()
+    .describe('Base git ref for changed-file and contract fact comparison'),
+  changedFiles: z
+    .string()
+    .optional()
+    .describe('Path to a newline-delimited changed-file list'),
+  configPath: z.string().optional().describe('Path to trails.config.ts'),
+  releaseNone: z
+    .boolean()
+    .default(false)
+    .describe('Compatibility no-release override'),
+  rootDir: z.string().optional().describe('Workspace root directory'),
+});
+
+const contractReleaseFactAspectSchema = z.enum([
+  'input',
+  'output',
+  'surfaces',
+  'trail',
+  'visibility',
+]);
+
+const contractReleaseFactSchema = z.object({
+  aspect: contractReleaseFactAspectSchema,
+  baseHash: z.string().nullable(),
+  changedFiles: z.array(z.string()).readonly(),
+  currentHash: z.string().nullable(),
+  packageName: z.string().optional(),
+  path: z.string(),
+  trailId: z.string(),
+  workspacePath: z.string().optional(),
+});
+
+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(),
+  contractFacts: z.array(contractReleaseFactSchema).readonly(),
+  coveredPackages: z.array(z.string()).readonly(),
+  errors: z.array(z.string()).readonly(),
+  formatted: z.string(),
+  matchedRuleIds: z.array(z.string()).readonly(),
+  noReleaseOverride: z.boolean(),
+  passed: z.boolean(),
+  releaseNone: z.boolean(),
+  uncoveredContractFacts: z.array(contractReleaseFactSchema).readonly(),
+  versionRelease: z.boolean(),
+});
+
+export const releaseCheckTrail = trail('release.check', {
+  blaze: async (input, ctx) => {
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return rootDirResult;
+    }
+
+    try {
+      return Result.ok(
+        await runReleaseCheck({
+          ...(input.baseRef === undefined ? {} : { baseRef: input.baseRef }),
+          ...(input.changedFiles === undefined
+            ? {}
+            : { changedFilesPath: input.changedFiles }),
+          ...(input.configPath === undefined
+            ? {}
+            : { configPath: input.configPath }),
+          env: ctx.env ?? {},
+          releaseNone: input.releaseNone,
+          repoRoot: rootDirResult.value,
+        })
+      );
+    } catch (error) {
+      return Result.err(
+        new ValidationError(
+          error instanceof Error ? error.message : String(error)
+        )
+      );
+    }
+  },
+  description: 'Check branch-local release rules',
+  examples: [
+    {
+      input: { baseRef: 'HEAD' },
+      name: 'Check release rules from the current HEAD',
+    },
+  ],
+  input: releaseCheckInputSchema,
+  intent: 'read',
+  output: releaseCheckOutputSchema,
+  permit: 'public',
+});

package/src/trails/release-smoke.ts

@@ -0,0 +1,48 @@
+/**
+ * `release.smoke` trail -- Local release confidence checks.
+ */
+
+import { Result, trail, ValidationError } from '@ontrails/core';
+import { z } from 'zod';
+
+import { releaseSmokeCheckValues, runReleaseSmoke } from '../release/smoke.js';
+
+const releaseSmokeCheckSchema = z.enum(releaseSmokeCheckValues);
+
+const releaseSmokeInputSchema = z.object({
+  check: z.string().default('all').describe('Release smoke check to run'),
+});
+
+const releaseSmokeCheckResultSchema = z.object({
+  check: z.enum(['packed-artifacts', 'wayfinder-dogfood']),
+  message: z.string(),
+  packageCount: z.number().optional(),
+  passed: z.literal(true),
+  trailCount: z.number().optional(),
+});
+
+const releaseSmokeOutputSchema = z.object({
+  checks: z.array(releaseSmokeCheckResultSchema).readonly(),
+  message: z.string(),
+  passed: z.literal(true),
+});
+
+export const releaseSmokeTrail = trail('release.smoke', {
+  blaze: async (input) => {
+    try {
+      const check = releaseSmokeCheckSchema.parse(input.check);
+      return Result.ok(await runReleaseSmoke(check));
+    } catch (error) {
+      return Result.err(
+        new ValidationError(
+          error instanceof Error ? error.message : String(error)
+        )
+      );
+    }
+  },
+  description: 'Run local release confidence smoke checks',
+  input: releaseSmokeInputSchema,
+  intent: 'read',
+  output: releaseSmokeOutputSchema,
+  permit: 'public',
+});

package/src/trails/revise.ts

@@ -0,0 +1,53 @@
+import { Result, ValidationError, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import {
+  findLifecycleTrail,
+  forkVersionEntrySource,
+  parseLifecycleTarget,
+  reviseTrailSource,
+  withLifecycleApp,
+} from './version-lifecycle-support.js';
+
+export const reviseTrail = trail('revise', {
+  args: ['target'],
+  blaze: async (input, ctx) =>
+    withLifecycleApp(input, ctx.cwd, async (app, rootDir) => {
+      const target = parseLifecycleTarget(input.target);
+      if (target.isErr()) {
+        return target;
+      }
+      if (target.value.version !== undefined) {
+        return input.as === 'fork'
+          ? forkVersionEntrySource(rootDir, target.value)
+          : Result.err(
+              new ValidationError(
+                'Revising a specific historical entry requires --as fork'
+              )
+            );
+      }
+      const found = findLifecycleTrail(app, target.value.trailId);
+      if (found.isErr()) {
+        return found;
+      }
+      return reviseTrailSource(rootDir, found.value, input.as);
+    }),
+  description: 'Scaffold the next trail version entry',
+  input: z.object({
+    as: z
+      .enum(['revision', 'fork'])
+      .default('revision')
+      .describe('Version entry shape to scaffold'),
+    module: z.string().optional().describe('Path to the app module'),
+    rootDir: z.string().optional().describe('Workspace root directory'),
+    target: z.string().min(1).describe('Trail target, optionally trail.id@N'),
+  }),
+  intent: 'write',
+  output: z.object({
+    file: z.string(),
+    trailId: z.string(),
+    updated: z.boolean(),
+    warnings: z.array(z.string()).optional(),
+  }),
+  permit: { scopes: ['version:write'] },
+});

package/src/trails/root-dir.ts

@@ -0,0 +1,21 @@
+import { Result, ValidationError } from '@ontrails/core';
+
+const ROOT_DIR_MESSAGE =
+  'Trail execution requires rootDir input or ctx.cwd from the runtime context.';
+
+export const resolveTrailRootDir = (
+  rootDir: string | undefined,
+  cwd: string | undefined
+): Result<string, ValidationError> => {
+  const resolved = rootDir ?? cwd;
+  return resolved === undefined
+    ? Result.err(new ValidationError(ROOT_DIR_MESSAGE))
+    : Result.ok(resolved);
+};
+
+export const requireTrailRootDir = (rootDir: string | undefined): string => {
+  if (rootDir === undefined) {
+    throw new ValidationError(ROOT_DIR_MESSAGE);
+  }
+  return rootDir;
+};