@ontrails/cli 1.0.0-beta.0

package/src/build.ts

@@ -0,0 +1,267 @@
+/**
+ * Build framework-agnostic CliCommand[] from an App's topology.
+ */
+
+import type { Field, Layer, Topo, TrailContext } from '@ontrails/core';
+import {
+  Result,
+  composeLayers,
+  createTrailContext,
+  deriveFields,
+  validateInput,
+} from '@ontrails/core';
+
+import type { AnyTrail, CliCommand, CliFlag } from './command.js';
+import { dryRunPreset, toFlags } from './flags.js';
+import type { InputResolver } from './prompt.js';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** 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;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Convert kebab-case flag name back to camelCase for input merging. */
+const toCamel = (str: string): string =>
+  str.replaceAll(/-([a-z])/g, (_, ch: string) => ch.toUpperCase());
+
+/**
+ * Parse a trail ID into group + command name.
+ * "entity.show" -> { group: "entity", name: "show" }
+ * "search" -> { group: undefined, name: "search" }
+ */
+const parseTrailId = (
+  id: string
+): { group: string | undefined; name: string } => {
+  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: CliFlag[], derived: CliFlag[]): CliFlag[] => {
+  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: Record<string, unknown>,
+  parsedFlags: Record<string, unknown>
+): Record<string, unknown> => {
+  const mergedInput: Record<string, unknown> = { ...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: readonly Field[],
+  mergedInput: Record<string, unknown>,
+  options?: BuildCliCommandsOptions
+): Promise<void> => {
+  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: Partial<TrailContext> | undefined,
+  options?: BuildCliCommandsOptions
+): Promise<TrailContext> => {
+  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: BuildCliCommandsOptions | undefined,
+  ctx: ActionResultContext
+): Promise<void> => {
+  if (options?.onResult) {
+    await options.onResult(ctx);
+  }
+};
+
+/** Execute a trail with validated input. */
+const executeTrail = async (
+  t: AnyTrail,
+  validatedInput: unknown,
+  ctxOverrides: Partial<TrailContext> | undefined,
+  options?: BuildCliCommandsOptions
+): Promise<Result<unknown, Error>> => {
+  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: AnyTrail,
+    fields: readonly Field[],
+    _flags: CliFlag[],
+    options?: BuildCliCommandsOptions
+  ) =>
+  async (
+    parsedArgs: Record<string, unknown>,
+    parsedFlags: Record<string, unknown>,
+    ctxOverrides?: Partial<TrailContext>
+  ): Promise<Result<unknown, Error>> => {
+    const mergedInput = mergeArgsAndFlags(parsedArgs, parsedFlags);
+    await applyPrompting(fields, mergedInput, options);
+
+    const validated = validateInput(t.input, mergedInput);
+    if (validated.isErr()) {
+      const errorResult: Result<unknown, Error> = 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: readonly Field[],
+  destructive: boolean | undefined,
+  options?: BuildCliCommandsOptions
+): CliFlag[] => {
+  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: AnyTrail,
+  options?: BuildCliCommandsOptions
+): CliCommand => {
+  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: Topo,
+  options?: BuildCliCommandsOptions
+): CliCommand[] => {
+  const commands: CliCommand[] = [];
+
+  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 as AnyTrail;
+    if (t.markers?.['internal'] === true) {
+      continue;
+    }
+    commands.push(toCliCommand(t, options));
+  }
+
+  return commands;
+};

package/src/command.ts

@@ -0,0 +1,73 @@
+/**
+ * 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';
+
+// ---------------------------------------------------------------------------
+// AnyTrail -- type-erased trail for the CLI boundary
+// ---------------------------------------------------------------------------
+
+/**
+ * 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.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyTrail = Trail<any, any>;
+
+// ---------------------------------------------------------------------------
+// CliFlag
+// ---------------------------------------------------------------------------
+
+/** 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;
+}
+
+// ---------------------------------------------------------------------------
+// CliArg
+// ---------------------------------------------------------------------------
+
+/** A positional CLI argument. */
+export interface CliArg {
+  readonly name: string;
+  readonly description?: string | undefined;
+  readonly required: boolean;
+  readonly variadic: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// CliCommand
+// ---------------------------------------------------------------------------
+
+/** 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>>;
+}

package/src/commander/blaze.ts

@@ -0,0 +1,67 @@
+/**
+ * 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 { buildCliCommands } from '../build.js';
+import type { CliFlag } from '../command.js';
+import { defaultOnResult } from '../on-result.js';
+import type { InputResolver } from '../prompt.js';
+import type { ToCommanderOptions } from './to-commander.js';
+import { toCommander } from './to-commander.js';
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+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;
+}
+
+// ---------------------------------------------------------------------------
+// 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: Topo, options: BlazeCliOptions = {}): void => {
+  const commands = buildCliCommands(app, {
+    createContext: options.createContext,
+    layers: options.layers,
+    onResult: options.onResult ?? defaultOnResult,
+    presets: options.presets,
+    resolveInput: options.resolveInput,
+  });
+
+  const commanderOpts: ToCommanderOptions = {
+    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();
+};

package/src/commander/index.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';

package/src/commander/to-commander.ts

@@ -0,0 +1,186 @@
+/**
+ * Adapt framework-agnostic CliCommand[] to a Commander program.
+ */
+
+import { exitCodeMap, isTrailsError } from '@ontrails/core';
+import { Command, Option } from 'commander';
+
+import type { CliCommand, CliFlag } from '../command.js';
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+export interface ToCommanderOptions {
+  description?: string | undefined;
+  name?: string | undefined;
+  version?: string | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Build the flag string portion of a Commander Option. */
+const buildFlagArgument = (flag: CliFlag): string => {
+  if (flag.variadic) {
+    return flag.required ? '<values...>' : '[values...]';
+  }
+  return flag.required ? '<value>' : '[value]';
+};
+
+const buildFlagString = (flag: CliFlag): string => {
+  const long = `--${flag.name}`;
+  const short = flag.short ? `-${flag.short}` : undefined;
+
+  if (flag.type === 'boolean') {
+    return short ? `${short}, ${long}` : long;
+  }
+
+  const argPart = buildFlagArgument(flag);
+  return short ? `${short}, ${long} ${argPart}` : `${long} ${argPart}`;
+};
+
+/** Build a Commander Option from a CliFlag. */
+const buildOption = (flag: CliFlag): Option => {
+  const opt = new Option(buildFlagString(flag), flag.description);
+  if (flag.choices) {
+    opt.choices(flag.choices);
+  }
+  if (flag.default !== undefined) {
+    opt.default(flag.default);
+  }
+  if (flag.type === 'number' || flag.type === 'number[]') {
+    opt.argParser(parseFloat);
+  }
+  return opt;
+};
+
+/** Add positional args to a Commander subcommand. */
+const buildArgTemplate = (arg: CliCommand['args'][number]): string => {
+  if (arg.variadic) {
+    return arg.required ? `<${arg.name}...>` : `[${arg.name}...]`;
+  }
+  return arg.required ? `<${arg.name}>` : `[${arg.name}]`;
+};
+
+const addArgs = (sub: Command, cmd: CliCommand): void => {
+  for (const arg of cmd.args) {
+    const template = buildArgTemplate(arg);
+    sub.argument(template, arg.description);
+  }
+};
+
+/** Collect positional args from Commander's action callback into a record. */
+const collectPositionalArgs = (
+  cmd: CliCommand,
+  actionArgs: unknown[]
+): Record<string, unknown> => {
+  const parsedArgs: Record<string, unknown> = {};
+  for (let i = 0; i < cmd.args.length; i += 1) {
+    const argDef = cmd.args[i];
+    if (argDef) {
+      parsedArgs[argDef.name] = actionArgs[i];
+    }
+  }
+  return parsedArgs;
+};
+
+/** Handle execution errors with appropriate exit codes. */
+const handleError = (error: unknown): void => {
+  if (error instanceof Error) {
+    process.stderr.write(`Error: ${error.message}\n`);
+    if (isTrailsError(error)) {
+      process.exit(exitCodeMap[error.category]);
+    }
+  } else {
+    process.stderr.write(`Error: ${String(error)}\n`);
+  }
+  process.exit(8);
+};
+
+/** Wire a CliCommand's action to a Commander subcommand. */
+const wireAction = (sub: Command, cmd: CliCommand): void => {
+  sub.action(async (...actionArgs: unknown[]) => {
+    const opts = sub.opts() as Record<string, unknown>;
+    const parsedArgs = collectPositionalArgs(cmd, actionArgs);
+    try {
+      await cmd.execute(parsedArgs, opts);
+    } catch (error: unknown) {
+      handleError(error);
+    }
+  });
+};
+
+/** Attach a subcommand to its group or to the top-level program. */
+const attachToGroup = (
+  sub: Command,
+  cmd: CliCommand,
+  program: Command,
+  groups: Map<string, Command>
+): void => {
+  if (cmd.group) {
+    let groupCmd = groups.get(cmd.group);
+    if (!groupCmd) {
+      groupCmd = new Command(cmd.group);
+      groups.set(cmd.group, groupCmd);
+      program.addCommand(groupCmd);
+    }
+    groupCmd.addCommand(sub);
+  } else {
+    program.addCommand(sub);
+  }
+};
+
+/** Apply options to a Commander program. */
+const applyOptions = (program: Command, options?: ToCommanderOptions): void => {
+  if (options?.name) {
+    program.name(options.name);
+  }
+  if (options?.version) {
+    program.version(options.version);
+  }
+  if (options?.description) {
+    program.description(options.description);
+  }
+};
+
+// ---------------------------------------------------------------------------
+// toCommander
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert CliCommand[] into a configured Commander program.
+ *
+ * Groups commands by their `group` field into parent/subcommand structure.
+ * Wires each command's `.action()` to call `execute()` and handle errors.
+ */
+/** Build a Commander subcommand from a CliCommand. */
+const buildSubcommand = (cmd: CliCommand): Command => {
+  const sub = new Command(cmd.name);
+  if (cmd.description) {
+    sub.description(cmd.description);
+  }
+  for (const flag of cmd.flags) {
+    sub.addOption(buildOption(flag));
+  }
+  addArgs(sub, cmd);
+  wireAction(sub, cmd);
+  return sub;
+};
+
+export const toCommander = (
+  commands: CliCommand[],
+  options?: ToCommanderOptions
+): Command => {
+  const program = new Command();
+  applyOptions(program, options);
+  const groups = new Map<string, Command>();
+
+  for (const cmd of commands) {
+    const sub = buildSubcommand(cmd);
+    attachToGroup(sub, cmd, program, groups);
+  }
+
+  return program;
+};