@ontrails/cli 1.0.0-beta.0

package/.turbo/turbo-build.log

@@ -0,0 +1 @@
+$ tsc -b

package/.turbo/turbo-lint.log

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

package/.turbo/turbo-typecheck.log

@@ -0,0 +1 @@
+$ tsc --noEmit

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @ontrails/cli
+
+## 1.0.0-beta.0
+
+### Minor Changes
+
+- Initial v1 beta release of the Trails framework.
+
+  - **@ontrails/core** — Result type, error taxonomy, trail/hike/event/topo, validateTopo, validateInput/Output, deriveFields, patterns, redaction, branded types, resilience
+  - **@ontrails/cli** — CLI surface adapter, Commander integration, flag derivation, layers
+  - **@ontrails/mcp** — MCP surface adapter, tool generation, annotations, progress bridge
+  - **@ontrails/logging** — Structured logging, sinks, formatters, LogTape adapter
+  - **@ontrails/testing** — testAll, testExamples, testTrail, testHike, testContracts, testDetours, surface harnesses
+  - **@ontrails/warden** — AST-based code convention rules via oxc-parser, drift detection, CI formatters
+  - **@ontrails/schema** — Surface map generation, hashing, semantic diffing
+
+### Patch Changes
+
+- Updated dependencies
+  - @ontrails/core@1.0.0-beta.0

package/README.md

@@ -0,0 +1,166 @@
+# @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.
+
+## 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
+
+```typescript
+import { trail, topo, Result } from '@ontrails/core';
+import { blaze } from '@ontrails/cli/commander';
+import { z } from 'zod';
+
+const greet = trail('greet', {
+  input: z.object({ name: z.string().describe('Who to greet') }),
+  implementation: (input) => Result.ok(`Hello, ${input.name}!`),
+});
+
+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!
+
+$ myapp greet --help
+Usage: myapp greet [options]
+
+Options:
+  --name <value>  Who to greet
+  -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.
+
+```typescript
+import { buildCliCommands } from '@ontrails/cli';
+
+const commands = buildCliCommands(app);
+// Each command: name, flags, args, group, trail ref, execute()
+```
+
+### 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            |
+
+Name conversion: `camelCase` field names become `--kebab-case` flags. `.describe()` on Zod fields becomes help text.
+
+### 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
+
+```typescript
+import { output, resolveOutputMode } from '@ontrails/cli';
+
+await output({ name: 'Alpha' }, 'json'); // Pretty JSON
+await output(items, 'jsonl'); // One JSON line per item
+await output('Hello', 'text'); // Plain text
+```
+
+Output mode resolution priority: `--json` > `--jsonl` > `--output <mode>` > `TRAILS_JSON=1` > `TRAILS_JSONL=1` > `"text"`.
+
+### Flag Presets
+
+- **`outputModePreset()`** -- `--output <mode>`, `--json`, `--jsonl`
+- **`cwdPreset()`** -- `--cwd <path>`
+- **`dryRunPreset()`** -- `--dry-run` (auto-added for destructive trails)
+
+### Built-in Layers
+
+- **`autoIterateLayer`** -- Adds `--all` flag for paginated trails; collects all pages.
+- **`dateShortcutsLayer`** -- Expands `"today"`, `"7d"`, `"30d"`, `"this-week"`, `"this-month"` into ISO date ranges.
+
+### Commander Adapter (Advanced)
+
+Build the Commander program manually for full control:
+
+```typescript
+import { buildCliCommands } from '@ontrails/cli';
+import { toCommander } from '@ontrails/cli/commander';
+
+const commands = buildCliCommands(app);
+const program = toCommander(commands, { name: 'myapp' });
+program.parse();
+```
+
+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)

package/dist/build.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Build framework-agnostic CliCommand[] from an App's topology.
+ */
+import type { Layer, Topo, TrailContext } from '@ontrails/core';
+import { Result } from '@ontrails/core';
+import type { AnyTrail, CliCommand, CliFlag } from './command.js';
+import type { InputResolver } from './prompt.js';
+/** Context passed to the onResult callback. */
+export interface ActionResultContext {
+    readonly args: Record<string, unknown>;
+    readonly flags: Record<string, unknown>;
+    readonly input: unknown;
+    readonly result: Result<unknown, Error>;
+    readonly trail: AnyTrail;
+}
+/** Options for buildCliCommands. */
+export interface BuildCliCommandsOptions {
+    createContext?: (() => TrailContext | Promise<TrailContext>) | undefined;
+    layers?: Layer[] | undefined;
+    onResult?: ((ctx: ActionResultContext) => Promise<void>) | undefined;
+    presets?: CliFlag[][] | undefined;
+    resolveInput?: InputResolver | undefined;
+}
+export declare const buildCliCommands: (app: Topo, options?: BuildCliCommandsOptions) => CliCommand[];
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAS,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,EACL,MAAM,EAKP,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAElE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAMjD,+CAA+C;AAC/C,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;CAC1B;AAED,oCAAoC;AACpC,MAAM,WAAW,uBAAuB;IACtC,aAAa,CAAC,EAAE,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,GAAG,SAAS,CAAC;IACzE,MAAM,CAAC,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC;IAC7B,QAAQ,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC;IACrE,OAAO,CAAC,EAAE,OAAO,EAAE,EAAE,GAAG,SAAS,CAAC;IAClC,YAAY,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAC1C;AAiND,eAAO,MAAM,gBAAgB,GAC3B,KAAK,IAAI,EACT,UAAU,uBAAuB,KAChC,UAAU,EAiBZ,CAAC"}

package/dist/build.js

@@ -0,0 +1,167 @@
+/**
+ * Build framework-agnostic CliCommand[] from an App's topology.
+ */
+import { Result, composeLayers, createTrailContext, deriveFields, validateInput, } from '@ontrails/core';
+import { dryRunPreset, toFlags } from './flags.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Convert kebab-case flag name back to camelCase for input merging. */
+const toCamel = (str) => str.replaceAll(/-([a-z])/g, (_, ch) => ch.toUpperCase());
+/**
+ * Parse a trail ID into group + command name.
+ * "entity.show" -> { group: "entity", name: "show" }
+ * "search" -> { group: undefined, name: "search" }
+ */
+const parseTrailId = (id) => {
+    const dotIndex = id.indexOf('.');
+    if (dotIndex === -1) {
+        return { group: undefined, name: id };
+    }
+    return {
+        group: id.slice(0, dotIndex),
+        name: id.slice(dotIndex + 1),
+    };
+};
+/**
+ * Merge preset flags with schema-derived flags.
+ * Schema-derived flags take precedence on name collision.
+ */
+const mergeFlags = (presets, derived) => {
+    const derivedNames = new Set(derived.map((f) => f.name));
+    const merged = [...derived];
+    for (const preset of presets) {
+        if (!derivedNames.has(preset.name)) {
+            merged.push(preset);
+        }
+    }
+    return merged;
+};
+// ---------------------------------------------------------------------------
+// buildCliCommands
+// ---------------------------------------------------------------------------
+/**
+ * Build an array of framework-agnostic CLI commands from an App.
+ *
+ * Iterates the topo, derives flags from input schemas, groups by
+ * dot-notation, and wires up the execute function with validation,
+ * layer composition, and onResult handling.
+ */
+const META_FLAGS = new Set(['json', 'jsonl', 'output']);
+/** Merge parsed args and flags into a camelCase input record. */
+const mergeArgsAndFlags = (parsedArgs, parsedFlags) => {
+    const mergedInput = { ...parsedArgs };
+    for (const [key, value] of Object.entries(parsedFlags)) {
+        if (!META_FLAGS.has(key)) {
+            mergedInput[toCamel(key)] = value;
+        }
+    }
+    return mergedInput;
+};
+/** Apply interactive prompting and merge results. */
+const applyPrompting = async (fields, mergedInput, options) => {
+    if (!options?.resolveInput) {
+        return;
+    }
+    const resolved = await options.resolveInput(fields, mergedInput);
+    for (const [key, value] of Object.entries(resolved)) {
+        if (value !== undefined) {
+            mergedInput[key] = value;
+        }
+    }
+};
+/** Resolve a TrailContext from overrides, factory, or default. */
+const resolveContext = (ctxOverrides, options) => {
+    if (ctxOverrides) {
+        return Promise.resolve(createTrailContext(ctxOverrides));
+    }
+    if (options?.createContext) {
+        return Promise.resolve(options.createContext());
+    }
+    return Promise.resolve(createTrailContext());
+};
+/** Report a result via onResult callback if provided. */
+const reportResult = async (options, ctx) => {
+    if (options?.onResult) {
+        await options.onResult(ctx);
+    }
+};
+/** Execute a trail with validated input. */
+const executeTrail = async (t, validatedInput, ctxOverrides, options) => {
+    const ctx = await resolveContext(ctxOverrides, options);
+    const layers = options?.layers ?? [];
+    const impl = composeLayers(layers, t, t.implementation);
+    return impl(validatedInput, ctx);
+};
+/** Create the execute function for a CLI command. */
+const createExecute = (t, fields, _flags, options) => async (parsedArgs, parsedFlags, ctxOverrides) => {
+    const mergedInput = mergeArgsAndFlags(parsedArgs, parsedFlags);
+    await applyPrompting(fields, mergedInput, options);
+    const validated = validateInput(t.input, mergedInput);
+    if (validated.isErr()) {
+        const errorResult = Result.err(validated.error);
+        await reportResult(options, {
+            args: parsedArgs,
+            flags: parsedFlags,
+            input: mergedInput,
+            result: errorResult,
+            trail: t,
+        });
+        return errorResult;
+    }
+    const result = await executeTrail(t, validated.value, ctxOverrides, options);
+    await reportResult(options, {
+        args: parsedArgs,
+        flags: parsedFlags,
+        input: validated.value,
+        result,
+        trail: t,
+    });
+    return result;
+};
+/** Derive and merge flags for a trail. */
+const buildFlags = (fields, destructive, options) => {
+    let flags = toFlags(fields);
+    if (options?.presets) {
+        flags = mergeFlags(options.presets.flat(), flags);
+    }
+    if (destructive) {
+        flags = mergeFlags(dryRunPreset(), flags);
+    }
+    return flags;
+};
+/** Convert a trail or route into a CLI command when it is publicly exposed. */
+const toCliCommand = (t, options) => {
+    const { group, name } = parseTrailId(t.id);
+    const fields = deriveFields(t.input, t.fields);
+    const flags = buildFlags(fields, t.destructive, options);
+    return {
+        args: [],
+        description: t.description,
+        destructive: t.destructive,
+        execute: createExecute(t, fields, flags, options),
+        flags,
+        group,
+        idempotent: t.idempotent,
+        layers: options?.layers,
+        name,
+        readOnly: t.readOnly,
+        trail: t,
+    };
+};
+export const buildCliCommands = (app, options) => {
+    const commands = [];
+    for (const item of app.list()) {
+        if (item.kind !== 'trail' && item.kind !== 'hike') {
+            continue;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const t = item;
+        if (t.markers?.['internal'] === true) {
+            continue;
+        }
+        commands.push(toCliCommand(t, options));
+    }
+    return commands;
+};
+//# sourceMappingURL=build.js.map

package/dist/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"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"}

package/dist/command.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Framework-agnostic CLI command model.
+ *
+ * These interfaces are the intermediate representation that
+ * `buildCliCommands()` produces and framework adapters consume.
+ * No Commander (or any other framework) imports here.
+ */
+import type { Layer, Result, Trail, TrailContext } from '@ontrails/core';
+/**
+ * Type-erased trail reference. At the CLI adapter boundary we lose
+ * generic type information since flags/args are parsed as strings.
+ * Using `any` here is intentional -- the Zod schema validates at runtime.
+ */
+export type AnyTrail = Trail<any, any>;
+/** A single CLI flag derived from a Zod schema field or preset. */
+export interface CliFlag {
+    readonly name: string;
+    readonly short?: string | undefined;
+    readonly description?: string | undefined;
+    readonly type: 'string' | 'number' | 'boolean' | 'string[]' | 'number[]';
+    readonly required: boolean;
+    readonly default?: unknown | undefined;
+    readonly choices?: string[] | undefined;
+    readonly variadic: boolean;
+}
+/** A positional CLI argument. */
+export interface CliArg {
+    readonly name: string;
+    readonly description?: string | undefined;
+    readonly required: boolean;
+    readonly variadic: boolean;
+}
+/** A framework-agnostic representation of a CLI command. */
+export interface CliCommand {
+    readonly name: string;
+    readonly description?: string | undefined;
+    readonly group?: string | undefined;
+    readonly flags: CliFlag[];
+    readonly args: CliArg[];
+    readonly trail: AnyTrail;
+    readonly layers?: Layer[] | undefined;
+    readonly readOnly?: boolean | undefined;
+    readonly destructive?: boolean | undefined;
+    readonly idempotent?: boolean | undefined;
+    execute(parsedArgs: Record<string, unknown>, parsedFlags: Record<string, unknown>, ctx?: Partial<TrailContext>): Promise<Result<unknown, Error>>;
+}
+//# sourceMappingURL=command.d.ts.map

package/dist/command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAMzE;;;;GAIG;AAEH,MAAM,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AAMvC,mEAAmE;AACnE,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;IACzE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAMD,iCAAiC;AACjC,MAAM,WAAW,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAMD,4DAA4D;AAC5D,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAE1C,OAAO,CACL,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,GAAG,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC1B,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;CACpC"}

package/dist/command.js

@@ -0,0 +1,9 @@
+/**
+ * Framework-agnostic CLI command model.
+ *
+ * These interfaces are the intermediate representation that
+ * `buildCliCommands()` produces and framework adapters consume.
+ * No Commander (or any other framework) imports here.
+ */
+export {};
+//# sourceMappingURL=command.js.map

package/dist/command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command.js","sourceRoot":"","sources":["../src/command.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/commander/blaze.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The one-liner convenience for wiring an App to Commander.
+ */
+import type { Layer, Topo, TrailContext } from '@ontrails/core';
+import type { ActionResultContext } from '../build.js';
+import type { CliFlag } from '../command.js';
+import type { InputResolver } from '../prompt.js';
+export interface BlazeCliOptions {
+    createContext?: (() => TrailContext | Promise<TrailContext>) | undefined;
+    description?: string | undefined;
+    layers?: Layer[] | undefined;
+    name?: string | undefined;
+    onResult?: ((ctx: ActionResultContext) => Promise<void>) | undefined;
+    presets?: CliFlag[][] | undefined;
+    resolveInput?: InputResolver | undefined;
+    version?: string | undefined;
+}
+/**
+ * Wire an App to Commander and parse argv in one call.
+ *
+ * ```ts
+ * import { topo } from "@ontrails/core";
+ * import { blaze } from "@ontrails/cli/commander";
+ * import * as entity from "./trails/entity.ts";
+ *
+ * const app = topo("myapp", entity);
+ * blaze(app);
+ * ```
+ */
+export declare const blaze: (app: Topo, options?: BlazeCliOptions) => void;
+//# sourceMappingURL=blaze.d.ts.map

package/dist/commander/blaze.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blaze.d.ts","sourceRoot":"","sources":["../../src/commander/blaze.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEhE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAQlD,MAAM,WAAW,eAAe;IAC9B,aAAa,CAAC,EAAE,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,GAAG,SAAS,CAAC;IACzE,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,MAAM,CAAC,EAAE,KAAK,EAAE,GAAG,SAAS,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,QAAQ,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,mBAAmB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC;IACrE,OAAO,CAAC,EAAE,OAAO,EAAE,EAAE,GAAG,SAAS,CAAC;IAClC,YAAY,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACzC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AAMD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,IAAI,EAAE,UAAS,eAAoB,KAAG,IAqBhE,CAAC"}

package/dist/commander/blaze.js

@@ -0,0 +1,42 @@
+/**
+ * The one-liner convenience for wiring an App to Commander.
+ */
+import { buildCliCommands } from '../build.js';
+import { defaultOnResult } from '../on-result.js';
+import { toCommander } from './to-commander.js';
+// ---------------------------------------------------------------------------
+// blaze
+// ---------------------------------------------------------------------------
+/**
+ * Wire an App to Commander and parse argv in one call.
+ *
+ * ```ts
+ * import { topo } from "@ontrails/core";
+ * import { blaze } from "@ontrails/cli/commander";
+ * import * as entity from "./trails/entity.ts";
+ *
+ * const app = topo("myapp", entity);
+ * blaze(app);
+ * ```
+ */
+export const blaze = (app, options = {}) => {
+    const commands = buildCliCommands(app, {
+        createContext: options.createContext,
+        layers: options.layers,
+        onResult: options.onResult ?? defaultOnResult,
+        presets: options.presets,
+        resolveInput: options.resolveInput,
+    });
+    const commanderOpts = {
+        name: options.name ?? app.name,
+    };
+    if (options.version !== undefined) {
+        commanderOpts.version = options.version;
+    }
+    if (options.description !== undefined) {
+        commanderOpts.description = options.description;
+    }
+    const program = toCommander(commands, commanderOpts);
+    program.parse();
+};
+//# sourceMappingURL=blaze.js.map

package/dist/commander/blaze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blaze.js","sourceRoot":"","sources":["../../src/commander/blaze.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGlD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAiBhD,8EAA8E;AAC9E,QAAQ;AACR,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,GAAS,EAAE,UAA2B,EAAE,EAAQ,EAAE;IACtE,MAAM,QAAQ,GAAG,gBAAgB,CAAC,GAAG,EAAE;QACrC,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,eAAe;QAC7C,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,YAAY,EAAE,OAAO,CAAC,YAAY;KACnC,CAAC,CAAC;IAEH,MAAM,aAAa,GAAuB;QACxC,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI;KAC/B,CAAC;IACF,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAClC,aAAa,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAC1C,CAAC;IACD,IAAI,OAAO,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACtC,aAAa,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAClD,CAAC;IAED,MAAM,OAAO,GAAG,WAAW,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IACrD,OAAO,CAAC,KAAK,EAAE,CAAC;AAClB,CAAC,CAAC"}

package/dist/commander/index.d.ts

@@ -0,0 +1,5 @@
+export { toCommander } from './to-commander.js';
+export type { ToCommanderOptions } from './to-commander.js';
+export { blaze } from './blaze.js';
+export type { BlazeCliOptions } from './blaze.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/commander/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commander/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/dist/commander/index.js

@@ -0,0 +1,3 @@
+export { toCommander } from './to-commander.js';
+export { blaze } from './blaze.js';
+//# sourceMappingURL=index.js.map

package/dist/commander/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/commander/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/commander/to-commander.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Adapt framework-agnostic CliCommand[] to a Commander program.
+ */
+import { Command } from 'commander';
+import type { CliCommand } from '../command.js';
+export interface ToCommanderOptions {
+    description?: string | undefined;
+    name?: string | undefined;
+    version?: string | undefined;
+}
+export declare const toCommander: (commands: CliCommand[], options?: ToCommanderOptions) => Command;
+//# sourceMappingURL=to-commander.d.ts.map

package/dist/commander/to-commander.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-commander.d.ts","sourceRoot":"","sources":["../../src/commander/to-commander.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAE5C,OAAO,KAAK,EAAE,UAAU,EAAW,MAAM,eAAe,CAAC;AAMzD,MAAM,WAAW,kBAAkB;IACjC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AA0JD,eAAO,MAAM,WAAW,GACtB,UAAU,UAAU,EAAE,EACtB,UAAU,kBAAkB,KAC3B,OAWF,CAAC"}