@ontrails/cli 1.0.0-beta.0

package/src/flags.ts

@@ -0,0 +1,250 @@
+/**
+ * Flag derivation from surface-agnostic fields and reusable flag presets.
+ */
+
+import type { Field } from '@ontrails/core';
+import type { z } from 'zod';
+
+import type { CliFlag } from './command.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Convert camelCase to kebab-case. */
+const toKebab = (str: string): string =>
+  str.replaceAll(/[A-Z]/g, (ch) => `-${ch.toLowerCase()}`);
+
+interface ZodInternals {
+  readonly _zod: {
+    readonly def: Readonly<Record<string, unknown>>;
+  };
+  readonly description?: string;
+}
+
+interface CliFlagShape {
+  readonly choices?: string[] | undefined;
+  readonly type: CliFlag['type'];
+  readonly variadic: boolean;
+}
+
+const fieldTypeToCliFlag: Record<Field['type'], CliFlagShape> = {
+  boolean: { type: 'boolean', variadic: false },
+  enum: { type: 'string', variadic: false },
+  multiselect: { type: 'string[]', variadic: true },
+  number: { type: 'number', variadic: false },
+  string: { type: 'string', variadic: false },
+};
+
+/** Convert a derived field into a CLI flag descriptor. */
+const toCliFlag = (field: Field): CliFlag => {
+  const shape = fieldTypeToCliFlag[field.type];
+  return {
+    choices: field.options?.map((option) => option.value),
+    default: field.default,
+    description: field.label,
+    name: toKebab(field.name),
+    required: field.required,
+    type: shape.type,
+    variadic: shape.variadic,
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/** Convert derived fields to CLI flags. */
+export const toFlags = (fields: readonly Field[]): CliFlag[] =>
+  fields.map(toCliFlag);
+
+interface UnwrapState {
+  defaultValue: unknown;
+  description: string | undefined;
+  required: boolean;
+}
+
+/** Get the inner type from an optional or default wrapper. */
+const getInnerType = (current: ZodInternals): ZodInternals =>
+  current._zod.def['innerType'] as ZodInternals;
+
+/** Propagate description from an inner type. */
+const propagateDescription = (
+  inner: ZodInternals,
+  state: UnwrapState
+): void => {
+  if (inner.description) {
+    state.description = inner.description;
+  }
+};
+
+/** Step one unwrap level for optional/default fields. */
+const unwrapStep = (
+  current: ZodInternals,
+  state: UnwrapState
+): ZodInternals | null => {
+  const defType = current._zod.def['type'] as string;
+  if (defType !== 'optional' && defType !== 'default') {
+    return null;
+  }
+  state.required = false;
+  if (defType === 'default') {
+    state.defaultValue = current._zod.def['defaultValue'];
+  }
+  const inner = getInnerType(current);
+  propagateDescription(inner, state);
+  return inner;
+};
+
+/** Unwrap optional/default wrappers, collecting metadata. */
+const unwrap = (
+  schema: ZodInternals
+): {
+  defaultValue: unknown;
+  description: string | undefined;
+  inner: ZodInternals;
+  required: boolean;
+} => {
+  const state: UnwrapState = {
+    defaultValue: undefined,
+    description: schema.description,
+    required: true,
+  };
+  let current = schema;
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const next = unwrapStep(current, state);
+    if (next === null) {
+      break;
+    }
+    current = next;
+  }
+
+  return { ...state, inner: current };
+};
+
+interface DerivedFlagShape {
+  readonly choices?: string[] | undefined;
+  readonly type: CliFlag['type'];
+  readonly variadic: boolean;
+}
+
+const flagShapeByDef: Record<
+  string,
+  (schema: ZodInternals) => DerivedFlagShape
+> = {
+  array: (schema) => {
+    const element = schema._zod.def['element'] as ZodInternals;
+    const elementType = element._zod.def['type'] as string;
+    if (elementType === 'number') {
+      return { type: 'number[]', variadic: true };
+    }
+    return { type: 'string[]', variadic: true };
+  },
+  boolean: () => ({ type: 'boolean', variadic: false }),
+  enum: (schema) => {
+    const entries = schema._zod.def['entries'] as Record<string, string>;
+    return {
+      choices: Object.values(entries),
+      type: 'string',
+      variadic: false,
+    };
+  },
+  number: () => ({ type: 'number', variadic: false }),
+  string: () => ({ type: 'string', variadic: false }),
+};
+
+/** Derive the CLI flag shape for an unwrapped Zod field. */
+const deriveFlagShape = (schema: ZodInternals): DerivedFlagShape => {
+  const defType = schema._zod.def['type'] as string;
+  const deriveShape = flagShapeByDef[defType];
+  return deriveShape
+    ? deriveShape(schema)
+    : { type: 'string', variadic: false };
+};
+
+/** Derive a single CLI flag from an object shape entry. */
+const deriveFlag = (key: string, value: ZodInternals): CliFlag => {
+  const { inner, required, defaultValue, description } = unwrap(value);
+  const { choices, type, variadic } = deriveFlagShape(inner);
+  return {
+    choices,
+    default: defaultValue,
+    description: description ?? inner.description,
+    name: toKebab(key),
+    required,
+    type,
+    variadic,
+  };
+};
+
+/** Derive CLI flags from a Zod input schema. */
+export const deriveFlags = (schema: z.ZodType): CliFlag[] => {
+  const zod = schema as unknown as ZodInternals;
+  if ((zod._zod.def['type'] as string) !== 'object') {
+    return [];
+  }
+  const shape = zod._zod.def['shape'] as
+    | Record<string, ZodInternals>
+    | undefined;
+  if (!shape) {
+    return [];
+  }
+  return Object.entries(shape).map(([key, value]) => deriveFlag(key, value));
+};
+
+// ---------------------------------------------------------------------------
+// Presets
+// ---------------------------------------------------------------------------
+
+/** Flags for output mode selection: --output, --json, --jsonl */
+export const outputModePreset = (): CliFlag[] => [
+  {
+    choices: ['text', 'json', 'jsonl'],
+    default: 'text',
+    description: 'Output format',
+    name: 'output',
+    required: false,
+    short: 'o',
+    type: 'string',
+    variadic: false,
+  },
+  {
+    description: 'Shorthand for --output json',
+    name: 'json',
+    required: false,
+    type: 'boolean',
+    variadic: false,
+  },
+  {
+    description: 'Shorthand for --output jsonl',
+    name: 'jsonl',
+    required: false,
+    type: 'boolean',
+    variadic: false,
+  },
+];
+
+/** Flag for working directory override: --cwd */
+export const cwdPreset = (): CliFlag[] => [
+  {
+    description: 'Working directory override',
+    name: 'cwd',
+    required: false,
+    type: 'string',
+    variadic: false,
+  },
+];
+
+/** Flag for dry-run mode: --dry-run */
+export const dryRunPreset = (): CliFlag[] => [
+  {
+    default: false,
+    description: 'Execute without side effects',
+    name: 'dry-run',
+    required: false,
+    type: 'boolean',
+    variadic: false,
+  },
+];

package/src/index.ts

@@ -0,0 +1,28 @@
+// Command model
+export type { AnyTrail, CliCommand, CliFlag, CliArg } from './command.js';
+
+// Build
+export { buildCliCommands } from './build.js';
+export type { BuildCliCommandsOptions, ActionResultContext } from './build.js';
+
+// Flags
+export {
+  deriveFlags,
+  outputModePreset,
+  cwdPreset,
+  dryRunPreset,
+} from './flags.js';
+
+// Output
+export { output, resolveOutputMode } from './output.js';
+export type { OutputMode } from './output.js';
+
+// onResult
+export { defaultOnResult } from './on-result.js';
+
+// Prompt
+export { passthroughResolver, isInteractive } from './prompt.js';
+export type { Field, InputResolver, ResolveInputOptions } from './prompt.js';
+
+// Layers
+export { autoIterateLayer, dateShortcutsLayer } from './layers.js';

package/src/layers.ts

@@ -0,0 +1,231 @@
+/**
+ * CLI-specific layers shipped with @ontrails/cli.
+ */
+
+import type { Implementation, Layer, Trail } from '@ontrails/core';
+import { Result } from '@ontrails/core';
+
+// ---------------------------------------------------------------------------
+// Pagination output shape detection
+// ---------------------------------------------------------------------------
+
+interface ZodInternals {
+  readonly _zod: {
+    readonly def: Readonly<Record<string, unknown>>;
+  };
+}
+
+/** Check if a trail's output schema looks like a paginated response. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const isPaginatedOutput = (trail: Trail<any, any>): boolean => {
+  if (!trail.output) {
+    return false;
+  }
+  const s = trail.output as unknown as ZodInternals;
+  const defType = s._zod.def['type'] as string;
+  if (defType !== 'object') {
+    return false;
+  }
+
+  const shape = s._zod.def['shape'] as Record<string, ZodInternals> | undefined;
+  if (!shape) {
+    return false;
+  }
+
+  return 'items' in shape && 'hasMore' in shape && 'nextCursor' in shape;
+};
+
+/** Check if a trail's input schema has since/until fields. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const hasDateRangeFields = (trail: Trail<any, any>): boolean => {
+  const s = trail.input as unknown as ZodInternals;
+  const defType = s._zod.def['type'] as string;
+  if (defType !== 'object') {
+    return false;
+  }
+
+  const shape = s._zod.def['shape'] as Record<string, ZodInternals> | undefined;
+  if (!shape) {
+    return false;
+  }
+
+  return 'since' in shape || 'until' in shape;
+};
+
+// ---------------------------------------------------------------------------
+// autoIterateLayer
+// ---------------------------------------------------------------------------
+
+interface PaginatedInput {
+  cursor?: string;
+  all?: boolean;
+  [key: string]: unknown;
+}
+
+interface PaginatedOutput {
+  items: unknown[];
+  hasMore: boolean;
+  nextCursor?: string;
+}
+
+/** Fetch one page and extract items. Returns error result or page data. */
+const fetchPage = async <I, O>(
+  inp: PaginatedInput,
+  cursor: string | undefined,
+  implementation: Implementation<I, O>,
+  ctx: Parameters<Implementation<I, O>>[1]
+): Promise<Result<PaginatedOutput, Error>> => {
+  const pageInput = { ...inp, cursor } as I;
+  const result = await implementation(pageInput, ctx);
+  if (result.isErr()) {
+    return result as Result<PaginatedOutput, Error>;
+  }
+  return Result.ok(result.value as PaginatedOutput);
+};
+
+/** Accumulate items from a page and return the next cursor if there are more. */
+const accumulatePage = (
+  page: PaginatedOutput,
+  allItems: unknown[]
+): string | undefined => {
+  allItems.push(...page.items);
+  return page.hasMore && page.nextCursor ? page.nextCursor : undefined;
+};
+
+/** Collect all pages into a single result. */
+const collectAllPages = async <I, O>(
+  inp: PaginatedInput,
+  implementation: Implementation<I, O>,
+  ctx: Parameters<Implementation<I, O>>[1]
+): Promise<Result<unknown, Error>> => {
+  const allItems: unknown[] = [];
+  let cursor: string | undefined;
+
+  for (;;) {
+    const pageResult = await fetchPage(inp, cursor, implementation, ctx);
+    if (pageResult.isErr()) {
+      return pageResult;
+    }
+    cursor = accumulatePage(pageResult.value as PaginatedOutput, allItems);
+    if (cursor === undefined) {
+      break;
+    }
+  }
+
+  return Result.ok({ hasMore: false, items: allItems });
+};
+
+/**
+ * Automatically iterates paginated results when --all flag is present.
+ *
+ * When a trail's output matches the pagination pattern (items, hasMore,
+ * nextCursor) and the input contains `all: true`, this layer repeatedly
+ * calls the implementation with incrementing cursors and collects all items.
+ */
+export const autoIterateLayer: Layer = {
+  description: 'Auto-paginate results when --all flag is set',
+  name: 'autoIterate',
+
+  wrap<I, O>(
+    trail: Trail<I, O>,
+    implementation: Implementation<I, O>
+  ): Implementation<I, O> {
+    if (!isPaginatedOutput(trail)) {
+      return implementation;
+    }
+
+    return (input, ctx) => {
+      const inp = input as PaginatedInput;
+      if (!inp.all) {
+        return implementation(input, ctx);
+      }
+      return collectAllPages(inp, implementation, ctx) as Promise<
+        Result<O, Error>
+      >;
+    };
+  },
+};
+
+// ---------------------------------------------------------------------------
+// dateShortcutsLayer
+// ---------------------------------------------------------------------------
+
+/** Build a date relative to today with a day offset. */
+const daysAgo = (days: number): string => {
+  const now = new Date();
+  return new Date(
+    now.getFullYear(),
+    now.getMonth(),
+    now.getDate() - days
+  ).toISOString();
+};
+
+const dateShortcuts: Record<string, () => string> = {
+  'this-month': () => {
+    const now = new Date();
+    return new Date(now.getFullYear(), now.getMonth(), 1).toISOString();
+  },
+  'this-week': () => {
+    const now = new Date();
+    const dayOfWeek = now.getDay();
+    const diff = dayOfWeek === 0 ? 6 : dayOfWeek - 1;
+    return daysAgo(diff);
+  },
+  today: () => daysAgo(0),
+  yesterday: () => daysAgo(1),
+};
+
+/** Expand a date shortcut to an ISO date string. */
+const expandDateShortcut = (shortcut: string): string | undefined => {
+  const handler = dateShortcuts[shortcut];
+  if (handler) {
+    return handler();
+  }
+  const match = /^(\d+)d$/.exec(shortcut);
+  if (match?.[1]) {
+    return daysAgo(Number(match[1]));
+  }
+  return undefined;
+};
+
+/** Expand since/until shortcuts in an input record. */
+const expandDateFields = (
+  inp: Record<string, unknown>
+): Record<string, unknown> => {
+  const modified = { ...inp };
+  for (const field of ['since', 'until'] as const) {
+    if (typeof inp[field] === 'string') {
+      const expanded = expandDateShortcut(inp[field]);
+      if (expanded) {
+        modified[field] = expanded;
+      }
+    }
+  }
+  return modified;
+};
+
+/**
+ * Expands date shortcut strings into ISO date ranges.
+ *
+ * When a trail's input has `since` or `until` fields, this layer
+ * checks for shortcuts like "today", "yesterday", "7d", "30d",
+ * "this-week", "this-month" and expands them to ISO 8601 dates.
+ */
+export const dateShortcutsLayer: Layer = {
+  description: 'Expand date shortcuts (today, 7d, etc.) to ISO dates',
+  name: 'dateShortcuts',
+
+  wrap<I, O>(
+    trail: Trail<I, O>,
+    implementation: Implementation<I, O>
+  ): Implementation<I, O> {
+    if (!hasDateRangeFields(trail)) {
+      return implementation;
+    }
+
+    return (input, ctx) => {
+      const modified = expandDateFields(input as Record<string, unknown>);
+      return implementation(modified as I, ctx);
+    };
+  },
+};

package/src/on-result.ts

@@ -0,0 +1,27 @@
+/**
+ * Default result handler for CLI commands.
+ */
+
+import type { ActionResultContext } from './build.js';
+import { output, resolveOutputMode } from './output.js';
+
+// ---------------------------------------------------------------------------
+// defaultOnResult
+// ---------------------------------------------------------------------------
+
+/**
+ * The batteries-included result handler.
+ *
+ * - On error: throws the error (lets the program's error handler produce exit code)
+ * - On success: resolves output mode from flags, pipes value through `output()`
+ */
+export const defaultOnResult = async (
+  ctx: ActionResultContext
+): Promise<void> => {
+  if (ctx.result.isErr()) {
+    throw ctx.result.error;
+  }
+
+  const { mode } = resolveOutputMode(ctx.flags);
+  await output(ctx.result.value, mode);
+};

package/src/output.ts

@@ -0,0 +1,101 @@
+/**
+ * Output formatting and mode resolution for CLI output.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type OutputMode = 'text' | 'json' | 'jsonl';
+
+// ---------------------------------------------------------------------------
+// output()
+// ---------------------------------------------------------------------------
+
+/**
+ * Write a value to stdout in the specified format.
+ *
+ * - **text**: strings written directly; objects JSON-stringified with 2-space indent
+ * - **json**: always JSON.stringify with 2-space indent
+ * - **jsonl**: arrays emit one JSON line per element; scalars emit one line
+ */
+const outputWriters: Record<OutputMode, (value: unknown) => void> = {
+  json: (value) => process.stdout.write(`${JSON.stringify(value, null, 2)}\n`),
+  jsonl: (value) => {
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        process.stdout.write(`${JSON.stringify(item)}\n`);
+      }
+    } else {
+      process.stdout.write(`${JSON.stringify(value)}\n`);
+    }
+  },
+  text: (value) => {
+    if (typeof value === 'string') {
+      process.stdout.write(`${value}\n`);
+    } else {
+      process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+    }
+  },
+};
+
+export const output = (value: unknown, mode: OutputMode): void => {
+  const writer = outputWriters[mode];
+  writer(value);
+};
+
+// ---------------------------------------------------------------------------
+// resolveOutputMode()
+// ---------------------------------------------------------------------------
+
+const VALID_MODES = new Set<OutputMode>(['text', 'json', 'jsonl']);
+
+/** Resolve mode from flags alone (--json, --jsonl, --output). */
+const resolveFlagMode = (
+  flags: Record<string, unknown>
+): OutputMode | undefined => {
+  if (flags['json'] === true) {
+    return 'json';
+  }
+  if (flags['jsonl'] === true) {
+    return 'jsonl';
+  }
+  if (
+    typeof flags['output'] === 'string' &&
+    VALID_MODES.has(flags['output'] as OutputMode)
+  ) {
+    return flags['output'] as OutputMode;
+  }
+  return undefined;
+};
+
+/** Resolve mode from environment variables. */
+const resolveEnvMode = (): OutputMode | undefined => {
+  if (process.env['TRAILS_JSON'] === '1') {
+    return 'json';
+  }
+  if (process.env['TRAILS_JSONL'] === '1') {
+    return 'jsonl';
+  }
+  return undefined;
+};
+
+/**
+ * Determine the output mode from parsed CLI flags and environment.
+ *
+ * Resolution order (highest priority wins):
+ * 1. `flags.json === true` -> "json"
+ * 2. `flags.jsonl === true` -> "jsonl"
+ * 3. `flags.output` as string -> validate against OutputMode
+ * 4. `TRAILS_JSON=1` env var -> "json"
+ * 5. `TRAILS_JSONL=1` env var -> "jsonl"
+ * 6. Default: "text"
+ */
+export const resolveOutputMode = (
+  flags: Record<string, unknown>
+): {
+  mode: OutputMode;
+} => {
+  const mode = resolveFlagMode(flags) ?? resolveEnvMode() ?? 'text';
+  return { mode };
+};

package/src/prompt.ts

@@ -0,0 +1,40 @@
+/**
+ * Surface-agnostic input resolution contracts for CLI commands.
+ *
+ * The core CLI package does not depend on any concrete prompt library.
+ * Callers can provide a resolver that gathers missing input however they want
+ * (Clack, forms, conversational UI, or no prompting at all).
+ */
+
+import type { Field } from '@ontrails/core';
+
+/**
+ * Options passed to an input resolver.
+ *
+ * `isTTY` is provided so callers can override interactivity in tests.
+ */
+export interface ResolveInputOptions {
+  readonly isTTY?: boolean | undefined;
+}
+
+/**
+ * A resolver that fills in missing values for derived schema fields.
+ *
+ * The resolver receives the current input as field-name keyed values and
+ * returns a merged record with any newly gathered answers.
+ */
+export type InputResolver = (
+  fields: readonly Field[],
+  provided: Record<string, unknown>,
+  options?: ResolveInputOptions
+) => Promise<Record<string, unknown>>;
+
+/** Default passthrough resolver for non-interactive execution. */
+export const passthroughResolver: InputResolver = async (_fields, provided) =>
+  await provided;
+
+/** Shared TTY check for resolver implementations. */
+export const isInteractive = (options?: ResolveInputOptions): boolean =>
+  options?.isTTY ?? process.stdin.isTTY ?? false;
+
+export type { Field };

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["**/__tests__/**", "**/*.test.ts", "dist"]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/build.ts","./src/command.ts","./src/flags.ts","./src/index.ts","./src/layers.ts","./src/on-result.ts","./src/output.ts","./src/prompt.ts","./src/commander/blaze.ts","./src/commander/index.ts","./src/commander/to-commander.ts"],"version":"5.9.3"}