@ontrails/trails 1.0.0-beta.19 → 1.0.0-beta.21

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # trails
 
+## 1.0.0-beta.21
+
+### Minor Changes
+
+- bb5a219: Add the public `create.versions` trail (`trails create versions`). Scaffold dependency version derivation graduates from `scripts/sync-scaffold-versions.ts` into the `create` surface: check mode verifies `apps/trails/src/scaffold-versions.generated.ts` is current, write mode regenerates it, and the root script remains as a thin compatibility wrapper.
+
+### Patch Changes
+
+- 4c0041c: Expose `wayfind.errors` and `wayfind.adapters` as read-only direct tools on the Trails operator MCP surface.
+- 4cca012: Add the `wayfind.errors` graph-read trail and expose it through the Trails CLI for local error-fact inspection.
+- 708b861: Expose `wayfind.adapters` over adapter-kit fact reports and add it to the Trails operator CLI Wayfinder surface.
+- b6579b8: Expose selected Wayfinder graph-read queries through the local `trails wayfind` CLI command group for dogfooding saved topo artifacts.
+- 52e15bc: Repair fresh app loading so mirrored workspace modules can resolve first-party workspace packages and their installed package dependencies from the mirror.
+- d4ec336: Add a repo-level Wayfinder dogfood smoke command that exercises the local
+  Trails CLI against exported operator topo artifacts.
+- 0d1472a: Expose release rules config helpers from `@ontrails/trails/release` so
+  projects can compose release policy into `trails.config.ts`.
+- 8f681ae: Move release rule evaluation into the Trails app package and export the
+  release check and public trail contract fact helpers from
+  `@ontrails/trails/release`.
+- 9e77ae1: Expose release rule evaluation through the `trails release check` command and
+  the Trails MCP operator surface, with JSON output available through the shared
+  CLI output mode.
+- fd676c4: Expose the native Bun release binding from `@ontrails/trails/release` and keep publish and registry scripts as compatibility wrappers.
+- 0ccb3e5: Add `release.smoke` as the public Trails release confidence surface for packed artifact and Wayfinder dogfood checks.
+- Updated dependencies [99523f2]
+- Updated dependencies [5e301d2]
+- Updated dependencies [4cca012]
+- Updated dependencies [3caa263]
+- Updated dependencies [708b861]
+- Updated dependencies [5be032c]
+  - @ontrails/core@1.0.0-beta.21
+  - @ontrails/permits@1.0.0-beta.21
+  - @ontrails/topographer@1.0.0-beta.21
+  - @ontrails/wayfinder@1.0.0-beta.21
+  - @ontrails/adapter-kit@1.0.0-beta.21
+  - @ontrails/warden@1.0.0-beta.21
+  - @ontrails/commander@1.0.0-beta.21
+  - @ontrails/cli@1.0.0-beta.21
+  - @ontrails/http@1.0.0-beta.21
+  - @ontrails/mcp@1.0.0-beta.21
+  - @ontrails/observe@1.0.0-beta.21
+  - @ontrails/tracing@1.0.0-beta.21
+
+## 1.0.0-beta.20
+
+### Minor Changes
+
+- 396136a: Add the Trails operator MCP entrypoint with deferred surface facets and cold-context resources.
+
+### Patch Changes
+
+- 851a2a3: Derive trail caller and blaze input types from the authored input schema while keeping one public input contract.
+- d89a889: Project selected Wayfinder graph-read trails into the Trails operator MCP surface alongside clearer first-class operator tools.
+- f67cd2a: Document Wayfinder as a real graph-read query catalog instead of a shell-only
+  package, including MCP exposure guidance, agent skill guidance, and release
+  notes for the v0 catalog and its deferred non-goals.
+- Updated dependencies [851a2a3]
+- Updated dependencies [eee1307]
+- Updated dependencies [9bec01c]
+- Updated dependencies [accb9ec]
+- Updated dependencies [8bc0708]
+- Updated dependencies [6901776]
+- Updated dependencies [f67cd2a]
+- Updated dependencies [c65c465]
+- Updated dependencies [38f62f8]
+- Updated dependencies [b248d4a]
+- Updated dependencies [5364df1]
+- Updated dependencies [2067441]
+- Updated dependencies [6c3296c]
+  - @ontrails/core@1.0.0-beta.20
+  - @ontrails/warden@1.0.0-beta.20
+  - @ontrails/topographer@1.0.0-beta.20
+  - @ontrails/adapter-kit@1.0.0-beta.20
+  - @ontrails/mcp@1.0.0-beta.20
+  - @ontrails/wayfinder@1.0.0-beta.20
+  - @ontrails/commander@1.0.0-beta.20
+  - @ontrails/cli@1.0.0-beta.20
+  - @ontrails/http@1.0.0-beta.20
+  - @ontrails/observe@1.0.0-beta.20
+  - @ontrails/permits@1.0.0-beta.20
+  - @ontrails/tracing@1.0.0-beta.20
+
 ## 1.0.0-beta.19
 
 ### Major Changes

package/README.md

@@ -15,6 +15,8 @@ Common workflows:
 - `trails topo` inspects topo state and manages pins/history.
 - `trails compile` writes committed topo artifacts.
 - `trails validate` checks committed topo artifacts for drift.
+- `trails wayfind overview` and adjacent `trails wayfind ...` commands read
+  saved topo artifacts through Wayfinder for local graph navigation.
 - `trails warden` runs Trails governance checks for contract and architecture drift.
 - `trails guide` shows available trails and examples from a project.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/trails",
-  "version": "1.0.0-beta.19",
+  "version": "1.0.0-beta.21",
   "bin": {
     "trails": "./bin/trails.ts"
   },
@@ -14,6 +14,10 @@
     "CHANGELOG.md"
   ],
   "type": "module",
+  "exports": {
+    "./release": "./src/release/index.ts",
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "build": "tsc -b",
     "test": "bun test",
@@ -23,21 +27,23 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",
-    "@ontrails/adapter-kit": "^1.0.0-beta.19",
-    "@ontrails/cli": "^1.0.0-beta.19",
-    "@ontrails/commander": "^1.0.0-beta.19",
-    "@ontrails/core": "^1.0.0-beta.19",
-    "@ontrails/http": "^1.0.0-beta.19",
-    "@ontrails/mcp": "^1.0.0-beta.19",
-    "@ontrails/observe": "^1.0.0-beta.19",
-    "@ontrails/permits": "^1.0.0-beta.19",
-    "@ontrails/topographer": "^1.0.0-beta.19",
-    "@ontrails/tracing": "^1.0.0-beta.19",
-    "@ontrails/warden": "^1.0.0-beta.19",
+    "@ontrails/adapter-kit": "^1.0.0-beta.21",
+    "@ontrails/cli": "^1.0.0-beta.21",
+    "@ontrails/commander": "^1.0.0-beta.21",
+    "@ontrails/core": "^1.0.0-beta.21",
+    "@ontrails/http": "^1.0.0-beta.21",
+    "@ontrails/mcp": "^1.0.0-beta.21",
+    "@ontrails/observe": "^1.0.0-beta.21",
+    "@ontrails/permits": "^1.0.0-beta.21",
+    "@ontrails/topographer": "^1.0.0-beta.21",
+    "@ontrails/tracing": "^1.0.0-beta.21",
+    "@ontrails/warden": "^1.0.0-beta.21",
+    "@ontrails/wayfinder": "^1.0.0-beta.21",
     "commander": "^14.0.3",
+    "typescript": "^5.9.3",
     "zod": "^4.3.5"
   },
   "devDependencies": {
-    "@ontrails/testing": "^1.0.0-beta.19"
+    "@ontrails/testing": "^1.0.0-beta.21"
   }
 }

package/src/app.ts

@@ -1,4 +1,16 @@
 import { topo } from '@ontrails/core';
+import {
+  wayfindAdaptersTrail,
+  wayfindContractTrail,
+  wayfindDescribeTrail,
+  wayfindErrorsTrail,
+  wayfindExamplesTrail,
+  wayfindImpactTrail,
+  wayfindNearbyTrail,
+  wayfindOverviewTrail,
+  wayfindSearchTrail,
+  wayfindTrailsTrail,
+} from '@ontrails/wayfinder';
 
 import * as addSurface from './trails/add-surface.js';
 import * as addTrail from './trails/add-trail.js';
@@ -10,6 +22,7 @@ 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';
@@ -17,6 +30,8 @@ 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 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';
@@ -30,7 +45,7 @@ import * as validate from './trails/validate.js';
 import * as warden from './trails/warden.js';
 import * as wardenGuide from './trails/warden-guide.js';
 
-export const app = topo(
+export const operatorApp = topo(
   'trails',
   run,
   runExamples,
@@ -49,6 +64,8 @@ export const app = topo(
   devClean,
   devReset,
   guide,
+  releaseCheck,
+  releaseSmoke,
   draftPromote,
   adapterCheck,
   warden,
@@ -56,9 +73,34 @@ export const app = topo(
   create,
   createAdapter,
   createScaffold,
+  createVersions,
   addSurface,
   addVerify,
   addTrail,
   completions,
   completionsComplete
 );
+
+const operatorTrails = Object.fromEntries(
+  operatorApp.list().map((trailItem) => [trailItem.id, trailItem])
+);
+
+const cliWayfinderTrails = {
+  wayfindAdaptersTrail,
+  wayfindContractTrail,
+  wayfindDescribeTrail,
+  wayfindErrorsTrail,
+  wayfindExamplesTrail,
+  wayfindImpactTrail,
+  wayfindNearbyTrail,
+  wayfindOverviewTrail,
+  wayfindSearchTrail,
+  wayfindTrailsTrail,
+};
+
+export const trailsCliIncludedTrails = [
+  ...operatorApp.list().map((trailItem) => trailItem.id),
+  ...Object.values(cliWayfinderTrails).map((trailItem) => trailItem.id),
+];
+
+export const app = topo('trails', operatorTrails, cliWayfinderTrails);

package/src/cli.ts

@@ -19,7 +19,7 @@ import { createProgram } from '@ontrails/commander';
 import { resolvePermitFromBearerToken } from '@ontrails/permits';
 import { deriveTopoGraph } from '@ontrails/topographer';
 
-import { app } from './app.js';
+import { app, trailsCliIncludedTrails } from './app.js';
 import { resolveInputWithClack } from './clack.js';
 import { getRetiredTopoCommandDiagnostic } from './retired-topo-command.js';
 import { attachCompletionsInstallCommand } from './run-completions-install.js';
@@ -27,6 +27,10 @@ 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';
@@ -70,6 +74,7 @@ const buildOnResult =
     // `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;
     }
@@ -89,6 +94,9 @@ const buildOnResult =
     if (tryAdapterCheckOutput(resolvedCtx)) {
       return;
     }
+    if (tryReleaseCheckOutput(resolvedCtx)) {
+      return;
+    }
     await defaultOnResult(resolvedCtx);
   };
 
@@ -287,6 +295,7 @@ const runSurfaceOnce = async (): Promise<void> => {
   try {
     const program = createProgram(app, {
       description: 'Agent-native, contract-first TypeScript framework',
+      include: trailsCliIncludedTrails,
       name: 'trails',
       onResult: buildOnResult(session),
       presets: [

package/src/load-app-mirror.ts

@@ -44,6 +44,13 @@ const validateMirrorRoot = (
       );
 };
 
+const isPathInside = (root: string, target: string): boolean => {
+  const candidate = relative(root, target);
+  return (
+    candidate === '' || (!candidate.startsWith('..') && !isAbsolute(candidate))
+  );
+};
+
 const resolveAbsoluteSourcePath = (
   sourcePath: string
 ): TrailsResult<string, ValidationError> =>
@@ -56,6 +63,41 @@ const resolveAbsoluteSourcePath = (
         )
       );
 
+export const ensureLoadAppMirrorDirectory = (
+  directoryPath: string,
+  mirrorRoot: string
+): TrailsResult<void, Error> => {
+  const root = validateMirrorRoot(mirrorRoot);
+  if (root.isErr()) {
+    return root;
+  }
+
+  const target = resolve(directoryPath);
+  if (!isPathInside(root.value, target)) {
+    return Result.err(
+      new PermissionError(
+        `Refusing to create load-app mirror directory outside "${root.value}"`,
+        { context: { directoryPath: target, mirrorRoot: root.value } }
+      )
+    );
+  }
+
+  try {
+    mkdirSync(target, { recursive: true });
+    return Result.ok();
+  } catch (error) {
+    return Result.err(
+      new InternalError(
+        `Failed to create load-app mirror directory "${target}"`,
+        {
+          cause: asError(error),
+          context: { directoryPath: target, mirrorRoot: root.value },
+        }
+      )
+    );
+  }
+};
+
 /**
  * Convert an absolute source path to the deterministic location inside a
  * load-app fresh mirror.

package/src/mcp-app.ts

@@ -0,0 +1,30 @@
+import { topo } from '@ontrails/core';
+import {
+  wayfindAdaptersTrail,
+  wayfindContractTrail,
+  wayfindErrorsTrail,
+  wayfindExamplesTrail,
+  wayfindImpactTrail,
+  wayfindNearbyTrail,
+  wayfindOverviewTrail,
+  wayfindSearchTrail,
+  wayfindTrailsTrail,
+} from '@ontrails/wayfinder';
+
+import { operatorApp } from './app.js';
+
+const operatorTrails = Object.fromEntries(
+  operatorApp.list().map((trailItem) => [trailItem.id, trailItem])
+);
+
+export const trailsMcpApp = topo('trails', operatorTrails, {
+  wayfindAdaptersTrail,
+  wayfindContractTrail,
+  wayfindErrorsTrail,
+  wayfindExamplesTrail,
+  wayfindImpactTrail,
+  wayfindNearbyTrail,
+  wayfindOverviewTrail,
+  wayfindSearchTrail,
+  wayfindTrailsTrail,
+});

package/src/mcp-options.ts

@@ -0,0 +1,77 @@
+import type { CreateServerOptions, McpSurfaceFacetMap } from '@ontrails/mcp';
+
+export const trailsMcpIncludedTrails = [
+  'adapter.check',
+  'add.surface',
+  'add.trail',
+  'compile',
+  'create',
+  'create.adapter',
+  'deprecate',
+  'dev.clean',
+  'dev.reset',
+  'dev.stats',
+  'diff',
+  'doctor',
+  'draft.promote',
+  'guide',
+  'release.check',
+  'release.smoke',
+  'revise',
+  'run',
+  'run.example',
+  'run.examples',
+  'survey',
+  'survey.brief',
+  'survey.diff',
+  'survey.resource',
+  'survey.signal',
+  'survey.surfaces',
+  'survey.trail',
+  'topo',
+  'topo.history',
+  'topo.pin',
+  'topo.unpin',
+  'validate',
+  'warden',
+  'warden.guide',
+  'wayfind.adapters',
+  'wayfind.contract',
+  'wayfind.errors',
+  'wayfind.examples',
+  'wayfind.impact',
+  'wayfind.nearby',
+  'wayfind.overview',
+  'wayfind.search',
+  'wayfind.trails',
+] as const;
+
+export const trailsMcpFacets = {
+  inspect: {
+    description:
+      'Inspect saved topo structure, resources, signals, surfaces, and diffs.',
+    mcp: { loading: 'deferred' },
+    trails: [
+      'survey',
+      'diff',
+      'topo',
+      'guide',
+      'survey.brief',
+      'survey.diff',
+      'survey.resource',
+      'survey.signal',
+      'survey.surfaces',
+      'survey.trail',
+      'topo.history',
+    ],
+  },
+} satisfies McpSurfaceFacetMap;
+
+export const trailsMcpSurfaceOptions = {
+  description:
+    'Trails framework operator surface. Use MCP resources for cold context, direct tools for high-signal work, and the inspect facet for saved topo reads.',
+  facets: trailsMcpFacets,
+  include: trailsMcpIncludedTrails,
+  mcpResources: { examples: true, surfaceMap: true },
+  name: 'trails',
+} satisfies CreateServerOptions;

package/src/mcp.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env bun
+/* oxlint-disable eslint-plugin-jest/require-hook -- MCP stdio entrypoints execute at module scope */
+import { surface } from '@ontrails/mcp';
+
+import { trailsMcpApp } from './mcp-app.js';
+import { trailsMcpSurfaceOptions } from './mcp-options.js';
+
+await surface(trailsMcpApp, trailsMcpSurfaceOptions);

package/src/release/bindings.ts

@@ -0,0 +1,39 @@
+export const releaseBindingKindValues = ['native', 'adapter'] as const;
+export type ReleaseBindingKind = (typeof releaseBindingKindValues)[number];
+
+export const releaseBindingPlacementValues = [
+  'same-package',
+  'subpath',
+  'extracted',
+] as const;
+export type ReleaseBindingPlacement =
+  (typeof releaseBindingPlacementValues)[number];
+
+export const releaseBindingCapabilityValues = [
+  'pack-check',
+  'publish',
+  'registry-preflight',
+] as const;
+export type ReleaseBindingCapability =
+  (typeof releaseBindingCapabilityValues)[number];
+
+export interface ReleaseBindingDescriptor {
+  readonly boundary: 'foreign' | 'trails-owned';
+  readonly capabilities: readonly ReleaseBindingCapability[];
+  readonly description: string;
+  readonly id: string;
+  readonly kind: ReleaseBindingKind;
+  readonly placement: ReleaseBindingPlacement;
+  readonly runtime: string;
+}
+
+export const nativeBunReleaseBinding = {
+  boundary: 'trails-owned',
+  capabilities: ['pack-check', 'publish', 'registry-preflight'],
+  description:
+    'Built-in Bun release binding for Trails-owned package pack checks, npm registry preflight, and lockstep package publication.',
+  id: 'release.binding.native-bun',
+  kind: 'native',
+  placement: 'same-package',
+  runtime: 'bun',
+} satisfies ReleaseBindingDescriptor;