@ontrails/trails 0.2.0

package/README.md

@@ -0,0 +1,48 @@
+# Trails CLI
+
+Command-line tools for working with Trails projects.
+
+Use the canonical [Homebrew installation guide](../../docs/getting-started.md#installation) for installation, updates, and removal. Stable `0.2.0` installation requires the release assets and tap update; that handoff is pending. The formula requires Bun at runtime.
+
+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.
+
+These commands target stable `0.2.0`. Run them after that version is published to npm.
+
+```bash
+bunx @ontrails/trails@0.2.0 create my-app --permit '{"id":"local-dev","scopes":["project:write"]}'
+bunx @ontrails/trails@0.2.0 create my-app --workspace --permit '{"id":"local-dev","scopes":["project:write"]}'
+```
+
+Common workflows:
+
+- `trails create` starts a standalone app by default; `--workspace` creates a configured workspace with that app under `apps/<name>`. Generated surfaces live under `bin/`, app source stays side-effect-free, and `--dry-run` returns the complete write plan without touching disk. Workspace creation rejects targets nested beneath an existing configured workspace while allowing a child workspace beneath an ancestor standalone Config. On a rerun, a preserved app entry also rejects when its runtime-selected topo ID can be statically proven to conflict with `workspace.apps`; dynamic, indirect, and post-construction mutation forms remain preserved and are validated by runtime commands such as `trails compile`.
+- `trails add surface` adds another surface entrypoint to an existing project.
+- `trails topo` inspects topo state and manages pins/history.
+- `trails compile` writes the selected app's `trails.lock`. At a configured workspace root, pass `--app <id>`; compile never fans out or writes an aggregate root lock.
+- `trails validate` checks the selected app, or validates every configured app when run at a workspace root without `--app`.
+- `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. Pass `--app <id>` for one configured app. A workspace-root saved read returns a labeled app-partitioned view and may be partial; workspace diff requires complete views on both roots. `trails wayfind file <file> --outline` remains the operator-owned explicit-source exception and does not accept app selection.
+- `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. Configured workspaces derive topo targets from `workspace.apps`; `--app <id>` narrows topo-aware checks while preserving project-wide source facts. 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. The minimal `from`/`to` seed is the primary workflow: planning deterministically derives morphology proposals, source-observed naming and public-identifier review candidates, review-only filename moves with reference-closure evidence, a namespace census, and current live-topo API preserves into the artifact's `derivation` section. Each derived item records provenance; uncertain forms and file moves remain review inventory until explicitly authored into the plan. A malformed or incompatible `trails.lock` fails planning instead of silently dropping live-API preserves. Use `plan --expand --dry-run` to inspect additional observed 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. Human CLI runs stream concise phase progress to stderr; `--json` and `--jsonl` keep that channel quiet while returning phase names and timings in the structured result. MCP returns the same lifecycle facts from `trails_plan_regrade`, `trails_check_regrade`, `trails_preview_regrade`, `trails_apply_regrade`, and `trails_adjust_regrade` and forwards progress notifications when the caller supplies a progress token. Lifecycle timings describe the command invocation and are never persisted into plans or history receipts. Apply reuses its command-local preflight evaluation only when exact source bytes plus plan, policy, scope, lock, and tool identities still match. Any stale or unreadable fact fails closed; no prepared handle is written to disk or required for receipt regeneration, and the post-apply completion scan still runs independently.
+- `trails guide` remains available for compatibility; prefer `trails wayfind --source live --module <app-module>` or saved-artifact Wayfinder reads for agent navigation.
+
+For configured workspaces, migrate package-manager discovery, root aggregate-lock assumptions, and persistent `warden.apps` lists to static `workspace.apps`. `--root-dir` fixes the project boundary, `--app` selects one stable configured ID, and `--module` only refines that app's live entry. Run and completion ownership are derived live from those configured apps; a root aggregate `trails.lock` is neither created nor consulted as workspace identity.
+
+Use `trails config explain --json` to inspect that source-static identity without loading app modules or consulting locks. From a workspace root it reports the configured app catalog; `--app <id>` or an app-root CWD narrows the same Config-authored identity and records how the selection was made.
+
+Scaffolding never writes `trails.lock` itself. Install dependencies, then use the normal compile path with the narrow `topo:write` permit:
+
+```bash
+# From a standalone app
+trails compile --permit '{"id":"local-dev","scopes":["topo:write"]}'
+
+# From a configured workspace root
+trails compile --app my-app --permit '{"id":"local-dev","scopes":["topo:write"]}'
+```
+
+The selected app receives a validated lock with its deterministic `scaffold` overlay. The generated README teaches the same standalone or workspace flow.
+
+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/bin/trails.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+/* oxlint-disable eslint-plugin-jest/require-hook -- CLI bin entrypoints execute at module scope */
+import '../src/cli.js';

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@ontrails/trails",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/outfitter-dev/trails.git",
+    "directory": "apps/trails"
+  },
+  "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",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "@manypkg/get-packages": "1.1.3",
+    "@ontrails/adapter-kit": "^0.2.0",
+    "@ontrails/cli": "^0.2.0",
+    "@ontrails/commander": "^0.2.0",
+    "@ontrails/config": "^0.2.0",
+    "@ontrails/core": "^0.2.0",
+    "@ontrails/http": "^0.2.0",
+    "@ontrails/mcp": "^0.2.0",
+    "@ontrails/observability": "^0.2.0",
+    "@ontrails/permits": "^0.2.0",
+    "@ontrails/regrade": "^0.2.0",
+    "@ontrails/source": "^0.2.0",
+    "@ontrails/topography": "^0.2.0",
+    "@ontrails/warden": "^0.2.0",
+    "commander": "^14.0.3",
+    "typescript": "5.9.3",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@ontrails/cloudflare": "^0.2.0",
+    "@ontrails/testing": "^0.2.0"
+  }
+}

package/src/app.ts

@@ -0,0 +1,167 @@
+import { surfaceOverlay, topo } from '@ontrails/core';
+import {
+  wayfindAdaptersTrail,
+  wayfindEntitiesTrail,
+  wayfindContractTrail,
+  wayfindDescribeTrail,
+  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 configExplain from './trails/config-explain.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 operatorApp = topo(
+  'trails',
+  run,
+  runExamples,
+  runExample,
+  survey,
+  topoCommand,
+  compile,
+  configExplain,
+  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,
+  completions,
+  completionsComplete
+);
+
+const operatorTrails = Object.fromEntries(
+  operatorApp.list().map((trailItem) => [trailItem.id, trailItem])
+);
+
+const cliWayfinderCommandTrails = {
+  wayfindDiffTrail: wayfind.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/clack.ts

@@ -0,0 +1,111 @@
+/**
+ * Clack-backed input resolver for the Trails CLI.
+ *
+ * This stays at the app layer so @ontrails/cli remains prompt-library agnostic.
+ */
+
+import type { Field, InputResolver, ResolveInputOptions } from '@ontrails/cli';
+import { isInteractive } from '@ontrails/cli';
+import * as clack from '@clack/prompts';
+
+/** Check whether a field still needs input. */
+const needsInput = (field: Field, current: Record<string, unknown>): boolean =>
+  current[field.name] === undefined &&
+  field.required &&
+  field.default === undefined;
+
+/** Build Clack options from field options. */
+const toClackOptions = (field: Field) =>
+  field.options?.map((option) => ({
+    ...(option.hint === undefined ? {} : { hint: option.hint }),
+    label: option.label ?? option.value,
+    value: option.value,
+  })) ?? [];
+
+/** Normalize cancelled prompts to `undefined`. */
+const cancelable = async <T>(value: T | symbol): Promise<T | undefined> =>
+  await (clack.isCancel(value) ? undefined : value);
+
+type FieldResolver = (field: Field) => Promise<unknown>;
+
+const fieldResolvers: Record<Field['type'], FieldResolver> = {
+  boolean: async (field) =>
+    cancelable(
+      await clack.confirm({
+        initialValue: (field.default as boolean | undefined) ?? false,
+        message: field.label,
+      })
+    ),
+  enum: async (field) =>
+    cancelable(
+      await clack.select({
+        message: field.label,
+        options: toClackOptions(field),
+      })
+    ),
+  multiselect: async (field) =>
+    cancelable(
+      await clack.multiselect({
+        initialValues: (field.default as string[] | undefined) ?? [],
+        message: field.label,
+        options: toClackOptions(field),
+      })
+    ),
+  number: async (field) => {
+    const raw = await clack.text({ message: field.label });
+    return clack.isCancel(raw) ? undefined : Number(raw);
+  },
+  'number[]': async (field) => {
+    const raw = await clack.text({
+      message: `${field.label} (comma-separated numbers)`,
+    });
+    if (clack.isCancel(raw)) {
+      return;
+    }
+    return String(raw)
+      .split(',')
+      .map((s) => Number(s.trim()));
+  },
+  string: async (field) =>
+    cancelable(await clack.text({ message: field.label })),
+  'string[]': async (field) => {
+    const raw = await clack.text({
+      message: `${field.label} (comma-separated)`,
+    });
+    if (clack.isCancel(raw)) {
+      return;
+    }
+    return String(raw)
+      .split(',')
+      .map((s) => s.trim());
+  },
+};
+
+/** Resolve a single field value with Clack. */
+const resolveField = (field: Field): Promise<unknown> => {
+  const resolver = fieldResolvers[field.type];
+  return resolver(field);
+};
+
+/** Fill missing input by prompting with Clack when interactive. */
+export const resolveInputWithClack: InputResolver = async (
+  fields,
+  provided,
+  options?: ResolveInputOptions
+) => {
+  if (!isInteractive(options)) {
+    return provided;
+  }
+
+  const resolved: Record<string, unknown> = { ...provided };
+  for (const field of fields) {
+    if (!needsInput(field, resolved)) {
+      continue;
+    }
+    const value = await resolveField(field);
+    if (value !== undefined) {
+      resolved[field.name] = value;
+    }
+  }
+  return resolved;
+};