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

package/README.md

@@ -0,0 +1,27 @@
+# Trails CLI
+
+Command-line tools for working with Trails projects.
+
+Use the CLI to scaffold a Trails app, add surfaces, inspect the current topo, run warden checks, manage draft state, and keep local Trails project state tidy.
+
+```bash
+bunx @ontrails/trails create
+```
+
+Common workflows:
+
+- `trails create` starts a new Trails project with generated trail, topo, surface, and verification files.
+- `trails add surface` adds another surface entrypoint to an existing project.
+- `trails topo` inspects topo state and manages pins/history.
+- `trails compile` writes root `trails.lock`.
+- `trails validate` checks root `trails.lock` for drift.
+- `trails wayfind`, `trails wayfind --trails --intent read`, `trails wayfind <id> --contract`, `trails wayfind <id> --deps`, `trails wayfind <id> --impact`, `trails wayfind pattern "wayfind.*"`, `trails wayfind query "release drift"`, and `trails wayfind diff ...` read graph artifacts through Wayfinder. `trails wayfind file <file> --outline` is the operator-owned live-source exception, assembled with `@ontrails/source` and enriched with saved graph context when available.
+- `trails schema <command...>` shows accepted CLI routes, aliases, flags, and schemas for an operator command or command namespace.
+- `trails warden` runs Trails governance checks for contract and architecture drift. Use `--scope-exclude <glob>` or project `warden.scope.exclude` config when local notes, scratch space, or generated state should not be governed by Warden.
+- `trails regrade plan <from> <to> --root-dir <path> --json` writes an active Regrade plan, `trails regrade plan --expand` stages wide-net review candidates in that plan, `trails regrade preview` reruns it without writing, and `trails regrade apply` consumes the plan and writes history. Use `plan --expand --dry-run` to inspect staged candidates without writing the active plan, and add `--dry-run` to `apply` to prove the apply path without mutating source. Use `trails regrade plans` and `trails regrade check` when a workspace has active plans that need inspection before apply. MCP exposes the same lifecycle as `trails_plan_regrade`, `trails_list_regrades`, `trails_check_regrade`, `trails_preview_regrade`, and `trails_apply_regrade`.
+- `trails guide` remains available for compatibility; prefer `trails wayfind --source live --module <app-module>` or saved-artifact Wayfinder reads for agent navigation.
+
+Trails is contract-first: define trails once with typed input, Result output, examples, and meta; the framework derives CLI, MCP, HTTP, and future surfaces from the same contracts.
+
+See the main Trails documentation for the full framework guide:
+<https://github.com/outfitter-dev/trails>

package/package.json

@@ -1,10 +1,23 @@
 {
   "name": "@ontrails/trails",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.42",
   "bin": {
     "trails": "./bin/trails.ts"
   },
+  "files": [
+    "bin/**/*.ts",
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "type": "module",
+  "exports": {
+    "./release": "./src/release/index.ts",
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "build": "tsc -b",
     "test": "bun test",
@@ -14,15 +27,26 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",
-    "@ontrails/cli": "^1.0.0-beta.0",
-    "@ontrails/core": "^1.0.0-beta.0",
-    "@ontrails/logging": "^1.0.0-beta.0",
-    "@ontrails/schema": "^1.0.0-beta.0",
-    "@ontrails/warden": "^1.0.0-beta.0",
+    "@ontrails/adapter-kit": "^1.0.0-beta.42",
+    "@ontrails/cli": "^1.0.0-beta.42",
+    "@ontrails/commander": "^1.0.0-beta.42",
+    "@ontrails/config": "^1.0.0-beta.42",
+    "@ontrails/core": "^1.0.0-beta.42",
+    "@ontrails/http": "^1.0.0-beta.42",
+    "@ontrails/mcp": "^1.0.0-beta.42",
+    "@ontrails/observe": "^1.0.0-beta.42",
+    "@ontrails/permits": "^1.0.0-beta.42",
+    "@ontrails/regrade": "^1.0.0-beta.42",
+    "@ontrails/source": "^1.0.0-beta.42",
+    "@ontrails/topography": "^1.0.0-beta.42",
+    "@ontrails/tracing": "^1.0.0-beta.42",
+    "@ontrails/warden": "^1.0.0-beta.42",
     "commander": "^14.0.3",
+    "typescript": "^5.9.3",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@ontrails/testing": "^1.0.0-beta.0"
+    "@ontrails/cloudflare": "^1.0.0-beta.42",
+    "@ontrails/testing": "^1.0.0-beta.42"
   }
 }

package/src/app.ts

@@ -1,22 +1,166 @@
-import { topo } from '@ontrails/core';
+import { surfaceOverlay, topo } from '@ontrails/core';
+import {
+  wayfindAdaptersTrail,
+  wayfindEntitiesTrail,
+  wayfindContractTrail,
+  wayfindDescribeTrail,
+  wayfindDiffTrail,
+  wayfindErrorsTrail,
+  wayfindExamplesTrail,
+  wayfindOverlayTrail,
+  wayfindTrailheadsTrail,
+  wayfindImpactTrail,
+  wayfindNearbyTrail,
+  wayfindOverviewTrail,
+  wayfindResourcesTrail,
+  wayfindSearchTrail,
+  wayfindSignalsTrail,
+  wayfindSurfacesTrail,
+  wayfindTrailsTrail,
+  wayfindVersionsTrail,
+} from '@ontrails/topography';
 
 import * as addSurface from './trails/add-surface.js';
 import * as addTrail from './trails/add-trail.js';
 import * as addVerify from './trails/add-verify.js';
+import * as adapterCheck from './trails/adapter-check.js';
+import * as compile from './trails/compile.js';
+import * as completions from './trails/completions.js';
+import * as completionsComplete from './trails/completions-complete.js';
 import * as create from './trails/create.js';
+import * as createAdapter from './trails/create-adapter.js';
 import * as createScaffold from './trails/create-scaffold.js';
+import * as createVersions from './trails/create-versions.js';
+import * as deprecate from './trails/deprecate.js';
+import * as devClean from './trails/dev-clean.js';
+import * as devReset from './trails/dev-reset.js';
+import * as devStats from './trails/dev-stats.js';
+import * as doctor from './trails/doctor.js';
+import * as draftPromote from './trails/draft-promote.js';
 import * as guide from './trails/guide.js';
+import * as regrade from './trails/regrade.js';
+import * as releaseCheck from './trails/release-check.js';
+import * as releaseSmoke from './trails/release-smoke.js';
+import * as revise from './trails/revise.js';
+import * as run from './trails/run.js';
+import * as runExample from './trails/run-example.js';
+import * as runExamples from './trails/run-examples.js';
 import * as survey from './trails/survey.js';
+import * as topoHistory from './trails/topo-history.js';
+import * as topoPin from './trails/topo-pin.js';
+import * as topoCommand from './trails/topo.js';
+import * as topoUnpin from './trails/topo-unpin.js';
+import * as validate from './trails/validate.js';
 import * as warden from './trails/warden.js';
+import * as wardenGuide from './trails/warden-guide.js';
+import * as wayfind from './trails/wayfind.js';
+import { wayfindOutlineTrail } from './trails/wayfind-outline.js';
 
-export const app = topo(
+export const operatorApp = topo(
   'trails',
+  run,
+  runExamples,
+  runExample,
   survey,
+  topoCommand,
+  compile,
+  topoHistory,
+  topoPin,
+  topoUnpin,
+  validate,
+  revise,
+  deprecate,
+  doctor,
+  devStats,
+  devClean,
+  devReset,
   guide,
+  regrade,
+  releaseCheck,
+  releaseSmoke,
+  draftPromote,
+  adapterCheck,
   warden,
+  wardenGuide,
   create,
+  createAdapter,
   createScaffold,
+  createVersions,
   addSurface,
   addVerify,
-  addTrail
+  addTrail,
+  completions,
+  completionsComplete
 );
+
+const operatorTrails = Object.fromEntries(
+  operatorApp.list().map((trailItem) => [trailItem.id, trailItem])
+);
+
+const cliWayfinderCommandTrails = {
+  wayfindDiffTrail,
+  wayfindFileTrail: wayfind.wayfindFileTrail,
+  wayfindPatternTrail: wayfind.wayfindPatternTrail,
+  wayfindQueryTrail: wayfind.wayfindQueryTrail,
+  wayfindTrail: wayfind.wayfindTrail,
+};
+
+const cliWayfinderSupportTrails = {
+  wayfindAdaptersTrail,
+  wayfindContractTrail,
+  wayfindDescribeTrail,
+  wayfindEntitiesTrail,
+  wayfindErrorsTrail,
+  wayfindExamplesTrail,
+  wayfindImpactTrail,
+  wayfindNearbyTrail,
+  wayfindOutlineTrail,
+  wayfindOverlayTrail,
+  wayfindOverviewTrail,
+  wayfindResourcesTrail,
+  wayfindSearchTrail,
+  wayfindSignalsTrail,
+  wayfindSurfacesTrail,
+  wayfindTrailheadsTrail,
+  wayfindTrailsTrail,
+  wayfindVersionsTrail,
+};
+
+const cliWayfinderTrails = {
+  ...cliWayfinderCommandTrails,
+  ...cliWayfinderSupportTrails,
+};
+
+export const trailsCliIncludedTrails = [
+  ...new Set([
+    ...operatorApp.list().map((trailItem) => trailItem.id),
+    ...Object.values(cliWayfinderCommandTrails).map(
+      (trailItem) => trailItem.id
+    ),
+  ]),
+];
+
+export const trailsOverlays = [
+  surfaceOverlay({
+    cli: { diff: 'survey.diff' },
+    // Authored, lockable default for the operator MCP `inspect` trailhead.
+    // The call-site map in `mcp-options.ts` overrides it at runtime with
+    // richer metadata (description, deferred loading) over the same members.
+    mcp: {
+      inspect: [
+        'survey',
+        'topo',
+        'guide',
+        'survey.brief',
+        'survey.diff',
+        'survey.resource',
+        'survey.signal',
+        'survey.surfaces',
+        'survey.trail',
+        'topo.history',
+      ],
+    },
+  }),
+];
+
+export const app = topo('trails', operatorTrails, cliWayfinderTrails);

package/src/cli.ts

@@ -1,14 +1,348 @@
-import { outputModePreset } from '@ontrails/cli';
-import { blaze } from '@ontrails/cli/commander';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { isAbsolute, join, resolve } from 'node:path';
 
-import { app } from './app.js';
+import {
+  defaultOnResult,
+  devPermitPreset,
+  deriveCliCommands,
+  outputModePreset,
+  permitPreset,
+  tokenPreset,
+  tracePreset,
+  watchPreset,
+} from '@ontrails/cli';
+import type {
+  ActionResultContext,
+  ResolveCliPermitFromToken,
+} from '@ontrails/cli';
+import { createProgram } from '@ontrails/commander';
+import type { CreateProgramOptions } from '@ontrails/commander';
+import { resolvePermitFromBearerToken } from '@ontrails/permits';
+import { deriveTopoGraph } from '@ontrails/topography';
+
+import { app, trailsCliIncludedTrails, trailsOverlays } from './app.js';
 import { resolveInputWithClack } from './clack.js';
+import { getRetiredTopoCommandDiagnostic } from './retired-topo-command.js';
+import { attachCompletionsInstallCommand } from './run-completions-install.js';
+import { attachSchemaCommand } from './run-schema.js';
+import {
+  applyAdapterCheckExitCode,
+  tryAdapterCheckOutput,
+} from './run-adapter-check.js';
+import {
+  applyReleaseCheckExitCode,
+  tryReleaseCheckOutput,
+} from './run-release-check.js';
+import { tryRecoverFromRunCollision } from './run-collision.js';
+import { tryExampleRunOutput } from './run-example.js';
+import { tryExamplesRunOutput } from './run-examples.js';
+import { tryQuietRunOutput } from './run-quiet.js';
+import {
+  argvHasTraceFlag,
+  installTraceSink,
+  tryTraceJsonOutput,
+  writeTraceTreeToStderr,
+} from './run-trace.js';
+import type { TraceSession } from './run-trace.js';
+import {
+  argvHasWatchFlag,
+  hashTopoGraphEntry,
+  readRunTrailId,
+  runWatchLoop,
+} from './run-watch.js';
+import { tryWardenOutput } from './run-warden.js';
+import { tryWayfindOutlineOutput } from './run-wayfind-outline.js';
+import { tryLoadFreshAppLease } from './trails/load-app.js';
+import { resolveRunModulePath } from './trails/run.js';
+import { resolveTrailRootDir } from './trails/root-dir.js';
+import { trailsPackageVersion } from './versions.js';
+
+const buildOnResult =
+  (session: TraceSession | undefined) =>
+  async (ctx: ActionResultContext): Promise<void> => {
+    const recovered = await tryRecoverFromRunCollision(ctx, { graph: app });
+    const resolvedCtx: ActionResultContext =
+      recovered === undefined
+        ? ctx
+        : {
+            ...ctx,
+            input: recovered.isOk()
+              ? (ctx.trail.input.safeParse(ctx.input).data ?? ctx.input)
+              : ctx.input,
+            result: recovered,
+          };
+
+    // `--trace --json` (without `--quiet`) emits a single Result-shaped
+    // envelope on stdout that includes the captured records under
+    // `tracing`. Hand that case off before the regular chain so the
+    // existing handlers do not also write to stdout.
+    applyAdapterCheckExitCode(resolvedCtx);
+    applyReleaseCheckExitCode(resolvedCtx);
+    if (session !== undefined && tryTraceJsonOutput(resolvedCtx, session)) {
+      return;
+    }
+
+    if (tryExampleRunOutput(resolvedCtx)) {
+      return;
+    }
+    if (tryExamplesRunOutput(resolvedCtx)) {
+      return;
+    }
+    if (await tryQuietRunOutput(resolvedCtx)) {
+      return;
+    }
+    if (tryWardenOutput(resolvedCtx)) {
+      return;
+    }
+    if (tryAdapterCheckOutput(resolvedCtx)) {
+      return;
+    }
+    if (tryReleaseCheckOutput(resolvedCtx)) {
+      return;
+    }
+    if (tryWayfindOutlineOutput(resolvedCtx)) {
+      return;
+    }
+    await defaultOnResult(resolvedCtx);
+  };
+
+const traceEnabled = argvHasTraceFlag(process.argv);
+const maybeInstallTraceSession = (): TraceSession | undefined =>
+  traceEnabled ? installTraceSink() : undefined;
+
+const resolveCliPermitFromToken: ResolveCliPermitFromToken = (input) =>
+  resolvePermitFromBearerToken({
+    bearerToken: input.token,
+    configValues: input.configValues,
+    env: process.env as Record<string, string | undefined>,
+    graph: input.graph,
+    missingAuthResourceMessage:
+      '--token requires an auth adapter. Register authResource from @ontrails/permits in your topo.',
+    nullPermitMessage: 'Auth adapter did not produce a permit for --token',
+    requestId: input.requestId,
+    resources: input.resources,
+    surface: 'cli',
+  });
+
+interface WatchRunTarget {
+  readonly app?: string | undefined;
+  readonly id: string;
+  readonly module?: string | undefined;
+  readonly rootDir?: string | undefined;
+}
+
+const readFlagValue = (
+  args: readonly string[],
+  flagName: string
+): string | undefined => {
+  const longFlag = `--${flagName}`;
+  const prefixedFlag = `${longFlag}=`;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === longFlag) {
+      return args[i + 1];
+    }
+    if (arg?.startsWith(prefixedFlag)) {
+      return arg.slice(prefixedFlag.length);
+    }
+  }
+  return undefined;
+};
+
+const resolveWatchRunTarget = (
+  argv: readonly string[]
+): WatchRunTarget | null => {
+  const args = argv.slice(2);
+  const id = readRunTrailId(args);
+  if (id === undefined) {
+    return null;
+  }
+  return {
+    app: readFlagValue(args, 'app'),
+    id,
+    module: readFlagValue(args, 'module'),
+    rootDir: readFlagValue(args, 'root-dir'),
+  };
+};
+
+/**
+ * Resolve the directory whose source-file events wake the `--watch` loop.
+ * Reruns still depend on the resolved TopoGraph entry hash; this path is
+ * only the cheap filesystem event source.
+ */
+const toWatchSourcePath = (rootDir: string, modulePath: string): string => {
+  if (modulePath.startsWith('file:')) {
+    return fileURLToPath(modulePath);
+  }
+  return isAbsolute(modulePath) ? modulePath : resolve(rootDir, modulePath);
+};
+
+const resolveWatchDirectorySourcePath = async (
+  target: WatchRunTarget | null
+): Promise<string> => {
+  if (target !== null) {
+    const rootDirResult = resolveTrailRootDir(target.rootDir, process.cwd());
+    if (rootDirResult.isErr()) {
+      throw rootDirResult.error;
+    }
+    const moduleResult = await resolveRunModulePath(
+      rootDirResult.value,
+      target.module,
+      target.id,
+      target.app
+    );
+    if (moduleResult.isOk()) {
+      return toWatchSourcePath(rootDirResult.value, moduleResult.value);
+    }
+  }
+  const cwd = process.cwd();
+  const srcDir = join(cwd, 'src');
+  if (existsSync(srcDir)) {
+    return join(srcDir, 'app.ts');
+  }
+  return join(cwd, 'app.ts');
+};
+
+const readWatchTopoGraphEntryHash = async (
+  target: WatchRunTarget | null
+): Promise<string | null> => {
+  if (target === null) {
+    return null;
+  }
+  const rootDirResult = resolveTrailRootDir(target.rootDir, process.cwd());
+  if (rootDirResult.isErr()) {
+    throw rootDirResult.error;
+  }
+  const rootDir = rootDirResult.value;
+  const moduleResult = await resolveRunModulePath(
+    rootDir,
+    target.module,
+    target.id,
+    target.app
+  );
+  if (moduleResult.isErr()) {
+    throw moduleResult.error;
+  }
+  const leaseResult = await tryLoadFreshAppLease(moduleResult.value, rootDir);
+  if (leaseResult.isErr()) {
+    throw leaseResult.error;
+  }
+  const lease = leaseResult.value;
+  try {
+    const topoGraph = deriveTopoGraph(lease.app);
+    const entry = topoGraph.entries.find(
+      (candidate) => candidate.kind === 'trail' && candidate.id === target.id
+    );
+    return entry === undefined ? null : hashTopoGraphEntry(entry);
+  } finally {
+    lease.release();
+  }
+};
+
+const wardenValueFlags = new Set([
+  '--apps',
+  '--config-path',
+  '--depth',
+  '--drafts',
+  '--fail-on',
+  '--format',
+  '--scope-exclude',
+  '--lock',
+  '--root-dir',
+]);
+
+const normalizeWardenArgv = (argv: readonly string[]): string[] => {
+  if (argv[2] !== 'warden') {
+    return [...argv];
+  }
+
+  const normalized = [...argv];
+  let previousFlagConsumesValue = false;
+  for (let index = 3; index < normalized.length; index += 1) {
+    const arg = normalized[index];
+    if (arg === undefined) {
+      continue;
+    }
+
+    if (previousFlagConsumesValue) {
+      previousFlagConsumesValue = false;
+      continue;
+    }
+
+    if (arg === '-a') {
+      normalized[index] = '--apps';
+      previousFlagConsumesValue = true;
+      continue;
+    }
+
+    previousFlagConsumesValue = wardenValueFlags.has(arg);
+  }
+
+  return normalized;
+};
+
+/**
+ * Invoke `surface()` once with an optional fresh trace session.
+ *
+ * When `--trace` is set, a fresh {@link TraceSession} is installed for the
+ * duration of the call and finalized in the `finally` block. Under
+ * `--watch`, this produces a fresh sink (and a fresh stderr tree) per
+ * rerun rather than letting records accumulate in a single
+ * process-lifetime sink.
+ */
+const runSurfaceOnce = async (): Promise<void> => {
+  const retiredTopoCommand = getRetiredTopoCommandDiagnostic(process.argv);
+  if (retiredTopoCommand !== null) {
+    process.stderr.write(`${retiredTopoCommand.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const session = maybeInstallTraceSession();
+  try {
+    const surfaceOptions = {
+      description: 'Agent-native, contract-first TypeScript framework',
+      include: trailsCliIncludedTrails,
+      name: 'trails',
+      onResult: buildOnResult(session),
+      overlays: trailsOverlays,
+      presets: [
+        outputModePreset(),
+        tracePreset(),
+        permitPreset(),
+        tokenPreset(),
+        devPermitPreset(),
+        watchPreset(),
+      ],
+      resolveInput: resolveInputWithClack,
+      resolvePermitFromToken: resolveCliPermitFromToken,
+      version: trailsPackageVersion,
+    } satisfies CreateProgramOptions;
+    const program = createProgram(app, surfaceOptions);
+    const schemaCommands = deriveCliCommands(app, surfaceOptions);
+    if (schemaCommands.isErr()) {
+      throw schemaCommands.error;
+    }
+    attachSchemaCommand(program, schemaCommands.value);
+    attachCompletionsInstallCommand(program);
+    await program.parseAsync(normalizeWardenArgv(process.argv));
+  } finally {
+    if (session !== undefined) {
+      const records = session.finalize();
+      writeTraceTreeToStderr(records);
+    }
+  }
+};
+
+const watchTarget = argvHasWatchFlag(process.argv)
+  ? resolveWatchRunTarget(process.argv)
+  : null;
 
-// oxlint-disable-next-line require-hook -- CLI entry point
-blaze(app, {
-  description: 'Agent-native, contract-first TypeScript framework',
-  name: 'trails',
-  presets: [outputModePreset()],
-  resolveInput: resolveInputWithClack,
-  version: '0.1.0',
-});
+await (argvHasWatchFlag(process.argv)
+  ? runWatchLoop({
+      readTopoGraphEntryHash: () => readWatchTopoGraphEntryHash(watchTarget),
+      run: runSurfaceOnce,
+      sourcePath: await resolveWatchDirectorySourcePath(watchTarget),
+    })
+  : runSurfaceOnce());