@ontrails/warden 1.0.0-beta.0 → 1.0.0-beta.2

package/.turbo/turbo-lint.log

@@ -1,3 +1,3 @@
 $ oxlint ./src
 Found 0 warnings and 0 errors.
-Finished in 105ms on 30 files with 93 rules using 24 threads.
+Finished in 24ms on 30 files with 93 rules using 24 threads.

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @ontrails/warden
 
+## 1.0.0-beta.2
+
+### Patch Changes
+
+- Fix workspace dependency resolution in published packages. Now using bun publish
+  which correctly replaces workspace:^ with actual version numbers.
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.2
+  - @ontrails/schema@1.0.0-beta.2
+
+## 1.0.0-beta.1
+
+### Patch Changes
+
+- Fix two blocking bugs from real-world migration:
+  - Published packages now resolve correctly (workspace:^ instead of workspace:\*)
+  - Error forwarding works across different success types (Err no longer carries phantom T)
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.1
+  - @ontrails/schema@1.0.0-beta.1
+
 ## 1.0.0-beta.0
 
 ### Minor Changes

package/README.md

@@ -1,16 +1,10 @@
 # @ontrails/warden
 
-Governance and contract enforcement for Trails. Lint rules that keep agents (and humans) on trails, surface lock drift detection, and a CLI runner for CI gating.
+AST-based code convention rules for Trails. 10 lint rules that catch contract violations at development time, plus surface lock drift detection and CI formatters.
 
-## Installation
+Structural checks (follows existence, recursive follows, example schema validation) live in `validateTopo()` from `@ontrails/core`. Warden handles the code-level rules that need AST analysis.
 
-```bash
-bun add -d @ontrails/warden
-```
-
-Peer dependencies: `@ontrails/core`, `@ontrails/schema`.
-
-## Quick Start
+## Usage
 
 From the Trails CLI:
 
@@ -30,62 +24,22 @@ const report = await runWarden(app, { exitCode: true });
 console.log(formatWardenReport(report));
 ```
 
-## Lint Rules
-
-10 built-in rules under the `trails/` namespace:
+## Rules
 
 | Rule | Severity | What it catches |
 | --- | --- | --- |
-| `no-throw-in-implementation` | error | `throw` statements inside `implementation` bodies |
-| `context-no-surface-types` | error | Surface-specific type imports in trail files |
-| `prefer-schema-inference` | warn | `fields` overrides that only repeat schema-derived labels or enum options |
-| `valid-describe-refs` | warn | `@see` references inside `.describe()` strings that do not resolve |
+| `no-throw-in-implementation` | error | `throw` inside implementation bodies |
+| `implementation-returns-result` | error | Implementations returning raw values instead of `Result` |
+| `context-no-surface-types` | error | Surface type imports (`Request`, `McpSession`) in trail files |
+| `no-sync-result-assumption` | error | Missing `await` on implementation results |
 | `valid-detour-refs` | error | Detour targets that do not exist in the topo |
-| `no-direct-implementation-call` | warn | Direct `.implementation()` calls in application code |
-| `no-sync-result-assumption` | error | Missing `await` on `.implementation()` results |
-| `implementation-returns-result` | error | Implementations that return raw values instead of `Result` |
-| `no-throw-in-detour-target` | error | `throw` inside trails that serve as detour targets |
+| `no-throw-in-detour-target` | error | `throw` inside detour target trails |
+| `no-direct-implementation-call` | warn | Direct `.implementation()` calls bypassing `ctx.follow()` |
 | `no-direct-impl-in-route` | warn | Direct `.implementation()` calls inside hike bodies |
+| `prefer-schema-inference` | warn | Redundant field overrides already derivable from the schema |
+| `valid-describe-refs` | warn | `@see` refs in `.describe()` that do not resolve |
 
-Several structural checks (follows existence, recursive follows, event origins, example schema validation, output schema presence) are handled by `validateTopo()` in `@ontrails/core`. Follows coverage (matching `follows` declarations to actual `ctx.follow()` calls) is verified by `testExamples()` in `@ontrails/testing`.
-
-### Configuration
-
-Add to `.oxlintrc.json`:
-
-```json
-{
-  "plugins": ["trails"],
-  "rules": {
-    "trails/no-throw-in-implementation": "error",
-    "trails/context-no-surface-types": "error",
-    "trails/valid-describe-refs": "warn",
-    "trails/valid-detour-refs": "error",
-    "trails/no-sync-result-assumption": "error",
-    "trails/implementation-returns-result": "error",
-    "trails/no-throw-in-detour-target": "error",
-    "trails/no-direct-implementation-call": "warn",
-    "trails/no-direct-impl-in-route": "warn",
-    "trails/prefer-schema-inference": "warn"
-  }
-}
-```
-
-### Key Rules
-
-**`no-throw-in-implementation`** -- Implementations return `Result.err()`, never `throw`. Flags `ThrowStatement` nodes inside `implementation` function bodies.
-
-**`context-no-surface-types`** -- Implementations are pure functions. Importing `Request`, `Response`, `McpSession`, or other surface types couples domain logic to a transport.
-
-**`prefer-schema-inference`** -- `fields` is for enrichment, not repetition. If a label or enum options are already derivable from the Zod schema, remove the redundant override and let `derive()` supply it.
-
-**`no-direct-implementation-call`** -- Direct `.implementation()` calls bypass validation, tracing, and layers. Application code should use `ctx.follow()` instead.
-
-**`no-sync-result-assumption`** -- Trail implementations normalize to `Promise<Result>`, even when the author wrote a sync body. Callers must `await` before using `.isOk()`, `.value`, or other `Result` APIs.
-
-**`valid-describe-refs`** -- `@see` tags inside schema `.describe()` strings are part of the contract surface. Warden warns when those references drift away from the actual topo.
-
-## Drift Detection
+## Drift detection
 
 Warden integrates with `@ontrails/schema` to detect when the topo has changed without updating `surface.lock`:
 
@@ -94,20 +48,15 @@ import { checkDrift } from '@ontrails/warden';
 
 const drift = await checkDrift(app);
 if (drift.stale) {
-  console.log(
-    'surface.lock is stale -- regenerate with `trails survey generate`'
-  );
+  console.log('surface.lock is stale -- regenerate with `trails survey generate`');
 }
 ```
 
-The check regenerates the surface map, hashes it, and compares against the committed `surface.lock`.
-
-## CI Integration
+## CI integration
 
 Add to lefthook for pre-push enforcement:
 
 ```yaml
-# lefthook.yml
 pre-push:
   commands:
     warden:
@@ -115,18 +64,28 @@ pre-push:
       tags: governance
 ```
 
-## API
+CI formatters for structured output:
 
 ```typescript
-import {
-  runWarden,
-  formatWardenReport,
-  checkDrift,
-  wardenRules,
-} from '@ontrails/warden';
+import { formatGitHubAnnotations, formatJson, formatSummary } from '@ontrails/warden';
 ```
 
-## Further Reading
+## API
+
+| Export | What it does |
+| --- | --- |
+| `runWarden(app, options?)` | Run all rules and drift checks, return a report |
+| `formatWardenReport(report)` | Human-readable report |
+| `checkDrift(app)` | Check if `surface.lock` matches the current topo |
+| `wardenRules` | Registry of all built-in rules |
+| `formatGitHubAnnotations(report)` | GitHub Actions annotation format |
+| `formatJson(report)` | Machine-readable JSON |
+| `formatSummary(report)` | Compact summary line |
 
-- [Architecture](../../docs/architecture.md)
-- [Testing Guide](../../docs/testing.md)
+See the [API Reference](../../docs/api-reference.md) for the full list.
+
+## Installation
+
+```bash
+bun add -d @ontrails/warden
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/warden",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.2",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -16,10 +16,10 @@
   "devDependencies": {
     "@oxc-project/types": "^0.122.0",
     "oxc-parser": "^0.121.0",
-    "zod": "catalog:"
+    "zod": "^4.3.5"
   },
   "peerDependencies": {
-    "@ontrails/core": "workspace:*",
-    "@ontrails/schema": "workspace:*"
+    "@ontrails/core": "^1.0.0-beta.0",
+    "@ontrails/schema": "^1.0.0-beta.0"
   }
 }