@ontrails/cli 1.0.0-beta.0 → 1.0.0-beta.1

package/.turbo/turbo-lint.log

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

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @ontrails/cli
 
+## 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
+
 ## 1.0.0-beta.0
 
 ### Minor Changes

package/README.md

@@ -1,18 +1,8 @@
 # @ontrails/cli
 
-CLI surface adapter for Trails. Framework-agnostic command model, automatic flag derivation from Zod schemas, output formatting, and a Commander adapter with a one-line `blaze()` entry point.
+CLI surface adapter. One `blaze()` call turns a topo into a full CLI with flags, subcommands, help text, and error-mapped exit codes -- all derived from the trail contracts.
 
-## Installation
-
-```bash
-bun add @ontrails/cli
-# If using the /commander subpath:
-bun add commander
-```
-
-`commander` is an optional peer dependency -- only required if you use the `/commander` subpath. The main `@ontrails/cli` export is framework-agnostic.
-
-## Quick Start
+## Usage
 
 ```typescript
 import { trail, topo, Result } from '@ontrails/core';
@@ -28,8 +18,6 @@ const app = topo('myapp', { greet });
 blaze(app);
 ```
 
-Pure trails can return `Result` directly. The CLI surface still runs the normalized awaitable implementation shape at execution time.
-
 ```bash
 $ myapp greet --name World
 Hello, World!
@@ -42,125 +30,59 @@ Options:
   -h, --help      display help for command
 ```
 
-## API Overview
-
-### `blaze(app, options?)` -- Commander Adapter
-
-The one-liner. Builds commands from the topo, adapts to Commander, parses `process.argv`.
-
-```typescript
-import { blaze } from '@ontrails/cli/commander';
-
-blaze(app, {
-  name: 'myapp',
-  version: '1.0.0',
-  onResult: async (ctx) => {
-    /* custom result handling */
-  },
-  layers: [myAuthLayer],
-});
-```
-
-### `buildCliCommands(app, options?)`
-
-Framework-agnostic command builder. Produces `CliCommand[]` that any CLI framework can consume.
+For more control, build the commands yourself:
 
 ```typescript
 import { buildCliCommands } from '@ontrails/cli';
+import { toCommander } from '@ontrails/cli/commander';
 
 const commands = buildCliCommands(app);
-// Each command: name, flags, args, group, trail ref, execute()
+const program = toCommander(commands, { name: 'myapp' });
+program.parse();
 ```
 
-### Flag Derivation
-
-Flags are derived automatically from the trail's Zod input schema:
-
-| Zod type              | CLI flag            | Notes                         |
-| --------------------- | ------------------- | ----------------------------- |
-| `z.string()`          | `--name <value>`    | Required string               |
-| `z.number()`          | `--count <value>`   | Required number               |
-| `z.boolean()`         | `--verbose`         | Boolean switch                |
-| `z.enum(["a", "b"])`  | `--format <value>`  | With choices                  |
-| `z.array(z.string())` | `--tag <values...>` | Repeatable: `--tag a --tag b` |
-| `z.optional(...)`     | `--name [value]`    | Optional                      |
-| `z.default(...)`      | `--name [value]`    | With default value            |
+`buildCliCommands` returns a framework-agnostic `CliCommand[]`. Use `toCommander` for Commander, or write your own adapter.
 
-Name conversion: `camelCase` field names become `--kebab-case` flags. `.describe()` on Zod fields becomes help text.
+## API
 
-### Trail ID to Command Mapping
-
-Dotted trail IDs create subcommand groups:
-
-| Trail ID      | CLI command         |
-| ------------- | ------------------- |
-| `greet`       | `myapp greet`       |
-| `entity.show` | `myapp entity show` |
-| `math.add`    | `myapp math add`    |
-
-### Output Formatting
+| Export | What it does |
+| --- | --- |
+| `blaze(app, options?)` | One-liner: build commands, wire Commander, parse argv |
+| `buildCliCommands(app)` | Framework-agnostic command builder, returns `CliCommand[]` |
+| `toCommander(commands, options?)` | Adapt `CliCommand[]` to a Commander program |
+| `deriveFlags(schema)` | Extract CLI flags from a Zod schema |
+| `output(data, mode)` | Format output as JSON, JSONL, or text |
+| `resolveOutputMode(options)` | Resolve output mode from flags and env vars |
 
-```typescript
-import { output, resolveOutputMode } from '@ontrails/cli';
+See the [API Reference](../../docs/api-reference.md) for the full list.
 
-await output({ name: 'Alpha' }, 'json'); // Pretty JSON
-await output(items, 'jsonl'); // One JSON line per item
-await output('Hello', 'text'); // Plain text
-```
+## Flag derivation
 
-Output mode resolution priority: `--json` > `--jsonl` > `--output <mode>` > `TRAILS_JSON=1` > `TRAILS_JSONL=1` > `"text"`.
+Flags come from the Zod schema automatically. No manual flag definitions.
 
-### Flag Presets
+| Zod type | CLI flag | Notes |
+| --- | --- | --- |
+| `z.string()` | `--name <value>` | Required |
+| `z.boolean()` | `--verbose` | Switch |
+| `z.enum(["a","b"])` | `--format <value>` | With choices |
+| `z.array(z.string())` | `--tag <values...>` | Repeatable |
+| `z.optional(...)` | `--name [value]` | Optional |
 
-- **`outputModePreset()`** -- `--output <mode>`, `--json`, `--jsonl`
-- **`cwdPreset()`** -- `--cwd <path>`
-- **`dryRunPreset()`** -- `--dry-run` (auto-added for destructive trails)
+`camelCase` fields become `--kebab-case` flags. `.describe()` becomes help text.
 
-### Built-in Layers
+## Subcommands
 
-- **`autoIterateLayer`** -- Adds `--all` flag for paginated trails; collects all pages.
-- **`dateShortcutsLayer`** -- Expands `"today"`, `"7d"`, `"30d"`, `"this-week"`, `"this-month"` into ISO date ranges.
+Dotted trail IDs create subcommand groups: `entity.show` becomes `myapp entity show`.
 
-### Commander Adapter (Advanced)
+## Layers
 
-Build the Commander program manually for full control:
+- **`autoIterateLayer`** -- adds `--all` for paginated trails, collects all pages
+- **`dateShortcutsLayer`** -- expands `"today"`, `"7d"`, `"30d"` into ISO date ranges
 
-```typescript
-import { buildCliCommands } from '@ontrails/cli';
-import { toCommander } from '@ontrails/cli/commander';
+## Installation
 
-const commands = buildCliCommands(app);
-const program = toCommander(commands, { name: 'myapp' });
-program.parse();
+```bash
+bun add @ontrails/cli commander
 ```
 
-To use a different CLI framework, consume `CliCommand[]` and write your own adapter.
-
-### Error Handling
-
-Trail error categories map to exit codes automatically:
-
-| Category     | Exit code |
-| ------------ | --------- |
-| `validation` | 1         |
-| `not_found`  | 2         |
-| `conflict`   | 3         |
-| `permission` | 4         |
-| `timeout`    | 5         |
-| `rate_limit` | 6         |
-| `network`    | 7         |
-| `internal`   | 8         |
-| `auth`       | 9         |
-| `cancelled`  | 130       |
-
-## Subpath Exports
-
-| Export | Contents |
-| --- | --- |
-| `@ontrails/cli` | `buildCliCommands`, `deriveFlags`, `output`, `resolveOutputMode`, flag presets, layers, `CliCommand` types |
-| `@ontrails/cli/commander` | `toCommander`, `blaze` (requires `commander` peer) |
-
-## Further Reading
-
-- [CLI Surface Guide](../../docs/surfaces/cli.md)
-- [Getting Started](../../docs/getting-started.md)
+`commander` is a peer dependency, required only for the `/commander` subpath.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/cli",
-  "version": "1.0.0-beta.0",
+  "version": "1.0.0-beta.1",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
@@ -15,7 +15,7 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "workspace:*"
+    "@ontrails/core": "workspace:^"
   },
   "peerDependencies": {
     "commander": "^14.0.3",