@ontrails/trails 1.0.0-beta.15 → 1.0.0-beta.16

package/src/run-example.ts

@@ -0,0 +1,149 @@
+/**
+ * CLI-surface bridge for the `run.example` trail.
+ *
+ * `run.example` resolves the named example on the target trail, executes it
+ * through the full pipeline, and packages an actual-vs-expected comparison
+ * into a structured envelope on the trail's outer `Result.ok(...)`. This module
+ * owns the surface decision of how to render that envelope:
+ *
+ * - Text mode (default): a compact summary on match, an `input / expected /
+ *   actual / diff` block on mismatch.
+ * - JSON / JSONL: emits the full {@link RunExampleComparison} envelope so
+ *   downstream consumers can parse the comparison shape directly.
+ *
+ * Match/mismatch is a comparison outcome, not an execution error: the trail
+ * always returns `Result.ok(envelope)`. This helper maps mismatch onto a
+ * non-zero exit code by throwing a `ValidationError` (category `validation`,
+ * exit 1) so Commander's error path runs.
+ *
+ * Outer Err on the run trail (NotFound, Ambiguous, Validation) is unaffected
+ * by `run.example`: this helper defers to the default handler so existing
+ * exit-code mapping and recovery hooks stay intact.
+ */
+
+import type { ActionResultContext } from '@ontrails/cli';
+import { deriveOutputMode, output } from '@ontrails/cli';
+import { ValidationError } from '@ontrails/core';
+
+import { runExampleComparisonSchema } from './trails/run-example.js';
+import type { RunExampleComparison } from './trails/run-example.js';
+
+// ---------------------------------------------------------------------------
+// Detection
+// ---------------------------------------------------------------------------
+
+const isExampleRunCtx = (ctx: ActionResultContext): boolean =>
+  ctx.trail.id === 'run.example';
+
+// ---------------------------------------------------------------------------
+// Text formatting
+// ---------------------------------------------------------------------------
+
+const formatJson = (value: unknown): string => {
+  try {
+    const encoded = JSON.stringify(value, null, 2);
+    return encoded === undefined ? String(value) : encoded;
+  } catch {
+    return String(value);
+  }
+};
+
+const formatMatchText = (envelope: RunExampleComparison): string =>
+  [
+    `OK  ${envelope.trailId} :: ${envelope.exampleName}`,
+    `mode: ${envelope.mode}`,
+    'actual matches expected.',
+  ].join('\n');
+
+const formatMismatchText = (envelope: RunExampleComparison): string => {
+  const diffBlock =
+    envelope.diff !== undefined && envelope.diff.length > 0
+      ? envelope.diff.map((line) => `  - ${line}`).join('\n')
+      : '  - <no diff lines>';
+
+  return [
+    `MISMATCH  ${envelope.trailId} :: ${envelope.exampleName}`,
+    `mode: ${envelope.mode}`,
+    'input:',
+    formatJson(envelope.input),
+    'expected:',
+    formatJson(envelope.expected),
+    'actual:',
+    formatJson(envelope.actual),
+    'diff:',
+    diffBlock,
+  ].join('\n');
+};
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Return value:
+ * - `false` — `run.example` did not apply; caller should fall through to its
+ *   default handler.
+ * - `true` — `run.example` handled the result and wrote output. Caller should
+ *   not invoke the default handler.
+ *
+ * Throws a {@link ValidationError} on mismatch so Commander's error path runs
+ * and the run trail surface exits with the validation category exit code.
+ */
+export const tryExampleRunOutput = (ctx: ActionResultContext): boolean => {
+  if (!isExampleRunCtx(ctx)) {
+    return false;
+  }
+
+  // Outer Err on the run.example trail (NotFound, Ambiguous, Validation) is not
+  // in scope here: defer to the default handler so existing
+  // exit-code mapping and recovery hooks stay intact.
+  if (ctx.result.isErr()) {
+    return false;
+  }
+
+  const envelope = runExampleComparisonSchema.safeParse(ctx.result.value);
+  if (!envelope.success) {
+    // Defensive fallback: the trail owns the output schema, so this branch is
+    // unreachable in practice. Defer to the default handler if anything else
+    // slips through.
+    return false;
+  }
+  const comparison = envelope.data;
+
+  const { mode } = deriveOutputMode(ctx.flags, ctx.topoName);
+
+  if (mode === 'text') {
+    if (comparison.match) {
+      output(formatMatchText(comparison), mode);
+      return true;
+    }
+    process.stderr.write(`${formatMismatchText(comparison)}\n`);
+    throw new ValidationError(
+      `Example '${comparison.exampleName}' on trail '${comparison.trailId}' did not match expected outcome.`,
+      {
+        context: {
+          exampleName: comparison.exampleName,
+          mode: comparison.mode,
+          trailId: comparison.trailId,
+        },
+      }
+    );
+  }
+
+  // JSON / JSONL: emit the full envelope so downstream consumers can parse
+  // the comparison shape directly.
+  output(comparison, mode);
+  if (!comparison.match) {
+    throw new ValidationError(
+      `Example '${comparison.exampleName}' on trail '${comparison.trailId}' did not match expected outcome.`,
+      {
+        context: {
+          exampleName: comparison.exampleName,
+          mode: comparison.mode,
+          trailId: comparison.trailId,
+        },
+      }
+    );
+  }
+  return true;
+};

package/src/run-examples.ts

@@ -0,0 +1,148 @@
+/**
+ * CLI-surface bridge for the `run.examples` trail.
+ *
+ * `run.examples` is a pure metadata read: the trail returns a
+ * {@link RunExamplesListing} on its outer Ok value.
+ * This module owns the surface decision of how to render that listing:
+ *
+ * - Text mode (default): a table-like list with `name`, truncated `input`,
+ *   and outcome (`ok` / `error: <code>`). Empty listings print
+ *   `No examples defined`.
+ * - JSON / JSONL: the structured `examples` array is emitted directly via
+ *   the resolved output mode, so agents and downstream consumers can parse
+ *   the full structured shape (`name`, `input`, `expected`, `expectedMatch`,
+ *   `error`, `signals`, `kind`, `provenance`).
+ *
+ * Errors at the outer layer (NotFoundError, AmbiguousError, ValidationError)
+ * are unaffected by `run.examples`: we always defer to the supplied default
+ * handler so the existing exit-code mapping and recovery hooks stay intact.
+ */
+
+import type { ActionResultContext } from '@ontrails/cli';
+import { deriveOutputMode, output } from '@ontrails/cli';
+import type { StructuredTrailExample } from '@ontrails/core';
+
+import { runExamplesListingSchema } from './trails/run-examples.js';
+import type { RunExamplesListing } from './trails/run-examples.js';
+
+// ---------------------------------------------------------------------------
+// Detection
+// ---------------------------------------------------------------------------
+
+const isExamplesRunCtx = (ctx: ActionResultContext): boolean =>
+  ctx.trail.id === 'run.examples';
+
+// ---------------------------------------------------------------------------
+// Text formatting
+// ---------------------------------------------------------------------------
+
+const INPUT_PREVIEW_LIMIT = 60;
+
+const truncate = (value: string, limit: number): string =>
+  value.length <= limit ? value : `${value.slice(0, limit - 1)}…`;
+
+const formatInputPreview = (input: unknown): string => {
+  if (input === undefined) {
+    return '';
+  }
+  let encoded: string;
+  try {
+    encoded = JSON.stringify(input) ?? '';
+  } catch {
+    encoded = String(input);
+  }
+  return truncate(encoded, INPUT_PREVIEW_LIMIT);
+};
+
+const formatOutcome = (example: StructuredTrailExample): string => {
+  if (example.kind === 'error') {
+    const code = example.error;
+    return code === undefined || code.length === 0 ? 'error' : `error: ${code}`;
+  }
+  return 'ok';
+};
+
+interface ExampleRow {
+  readonly name: string;
+  readonly input: string;
+  readonly outcome: string;
+}
+
+const buildRows = (
+  examples: readonly StructuredTrailExample[]
+): readonly ExampleRow[] =>
+  examples.map((example) => ({
+    input: formatInputPreview(example.input),
+    name: example.name,
+    outcome: formatOutcome(example),
+  }));
+
+const padRight = (value: string, width: number): string =>
+  value.length >= width ? value : value + ' '.repeat(width - value.length);
+
+const formatTable = (rows: readonly ExampleRow[]): string => {
+  const headers = { input: 'INPUT', name: 'NAME', outcome: 'OUTCOME' };
+  const allRows: readonly ExampleRow[] = [headers, ...rows];
+
+  const widths = {
+    input: Math.max(...allRows.map((row) => row.input.length)),
+    name: Math.max(...allRows.map((row) => row.name.length)),
+    outcome: Math.max(...allRows.map((row) => row.outcome.length)),
+  };
+
+  const formatRow = (row: ExampleRow): string =>
+    `${padRight(row.name, widths.name)}  ${padRight(row.input, widths.input)}  ${row.outcome}`;
+
+  return allRows.map(formatRow).join('\n');
+};
+
+const formatTextListing = (listing: RunExamplesListing): string => {
+  if (listing.examples.length === 0) {
+    return 'No examples defined';
+  }
+  return formatTable(buildRows(listing.examples));
+};
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Return value:
+ * - `false` — `run.examples` did not apply; caller should fall through to its
+ *   default handler.
+ * - `true` — `run.examples` handled the result and wrote output. Caller should
+ *   not invoke the default handler.
+ */
+export const tryExamplesRunOutput = (ctx: ActionResultContext): boolean => {
+  if (!isExamplesRunCtx(ctx)) {
+    return false;
+  }
+
+  // Outer Err on `run.examples` (NotFound, Ambiguous, Validation) is not in
+  // scope for this renderer: defer to the default handler so existing
+  // exit-code mapping and recovery hooks stay intact.
+  if (ctx.result.isErr()) {
+    return false;
+  }
+
+  const listing = runExamplesListingSchema.safeParse(ctx.result.value);
+  if (!listing.success) {
+    // Defensive fallback: the trail owns the output schema, so this branch is
+    // unreachable in practice. Defer to the default handler if anything else
+    // slips through.
+    return false;
+  }
+
+  const { mode } = deriveOutputMode(ctx.flags, ctx.topoName);
+
+  if (mode === 'text') {
+    output(formatTextListing(listing.data), mode);
+    return true;
+  }
+
+  // JSON / JSONL: emit the structured examples array directly so downstream
+  // consumers can parse the full structured shape per example.
+  output(listing.data.examples, mode);
+  return true;
+};

package/src/run-quiet.ts

@@ -0,0 +1,75 @@
+/**
+ * CLI-surface bridge for the `run` trail's `--quiet` flag.
+ *
+ * The `run` trail returns an `inner-trail-result` envelope as the `value` of
+ * its own outer `Result.ok(...)`. The default CLI on-result handler unwraps
+ * once, leaving stdout as `{ "kind": "inner-trail-result", "trailId": "...",
+ * "value": ... }` — useful when a caller wants provenance, but noisy when the
+ * caller only wants the inner value to feed downstream pipes.
+ *
+ * `--quiet` strips that envelope:
+ *
+ * - Inner result envelope → write the inner value to stdout via the resolved
+ *   output mode.
+ *
+ * Errors at the outer layer (the run trail itself failing — `NotFoundError`,
+ * `AmbiguousError`, `ValidationError` from input) are unaffected by `--quiet`:
+ * we always defer to the supplied default handler so collision-recovery and
+ * the existing error surface stay intact.
+ */
+
+import type { ActionResultContext } from '@ontrails/cli';
+import { deriveOutputMode, output } from '@ontrails/cli';
+
+import { INNER_TRAIL_RESULT_KIND } from './trails/run.js';
+
+interface InnerTrailResultEnvelope {
+  readonly kind: typeof INNER_TRAIL_RESULT_KIND;
+  readonly trailId: string;
+  readonly value: unknown;
+}
+
+const isInnerTrailResultEnvelope = (
+  value: unknown
+): value is InnerTrailResultEnvelope =>
+  typeof value === 'object' &&
+  value !== null &&
+  (value as { readonly kind?: unknown }).kind === INNER_TRAIL_RESULT_KIND &&
+  typeof (value as { readonly trailId?: unknown }).trailId === 'string' &&
+  'value' in value;
+
+const isQuietRunCtx = (ctx: ActionResultContext): boolean =>
+  ctx.trail.id === 'run' && ctx.flags['quiet'] === true;
+
+/**
+ * Return value:
+ * - `false` — `--quiet` did not apply; caller should fall through to its
+ *   default handler.
+ * - `true` — `--quiet` handled the result and wrote output. Caller should not
+ *   invoke the default handler.
+ *
+ */
+export const tryQuietRunOutput = async (
+  ctx: ActionResultContext
+): Promise<boolean> => {
+  if (!isQuietRunCtx(ctx)) {
+    return false;
+  }
+
+  // Outer Err on the run trail (collision, not-found, validation) is not in
+  // scope for --quiet: defer to the default handler so existing exit-code
+  // mapping and recovery hooks stay intact.
+  if (ctx.result.isErr()) {
+    return false;
+  }
+
+  const inner: unknown = ctx.result.value;
+  if (!isInnerTrailResultEnvelope(inner)) {
+    return false;
+  }
+
+  const { mode } = deriveOutputMode(ctx.flags, ctx.topoName);
+  const value = inner.value === undefined ? null : inner.value;
+  output(value, mode);
+  return true;
+};

package/src/run-trace.ts

@@ -0,0 +1,273 @@
+/**
+ * CLI-surface bridge for the `--trace` flag.
+ *
+ * `--trace` installs a per-invocation in-memory {@link TraceSink} so the
+ * intrinsic tracing pipeline in `@ontrails/core` records every trail-,
+ * span-, signal-, and activation-level event during the invocation. After
+ * the trail completes (success or failure), the records are rendered as a
+ * tree to stderr via `renderTraceTree` from `@ontrails/observe`. Under
+ * `--json`, the structured `TraceRecord[]` is also emitted on stdout as
+ * the `tracing` field of a Result envelope.
+ *
+ * Design notes:
+ *
+ * - The sink is **per-invocation**, not module-global. Each call to
+ *   {@link installTraceSink} replaces the registry entry with a fresh
+ *   `MemoryTraceSink` and returns a handle whose {@link TraceSession.finalize}
+ *   restores the previous sink and returns the captured records.
+ * - Tracing output is split across streams: the tree always goes to stderr,
+ *   structured records only enter stdout when both `--trace` and `--json`
+ *   are set. Under `--quiet`, the inner trail value remains the only stdout
+ *   payload (no envelope) per ADR-0044's pipe-friendly contract.
+ * - `--trace` on `run.examples` is a metadata read; the run trail short-circuits
+ *   before any execution, so no trace tree is rendered.
+ */
+
+import { getTraceSink, registerTraceSink } from '@ontrails/core';
+import type { TraceRecord, TraceSink } from '@ontrails/core';
+import { createMemorySink, renderTraceTree } from '@ontrails/observe';
+import type { MemoryTraceSink } from '@ontrails/observe';
+
+// ---------------------------------------------------------------------------
+// Argv detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect whether `--trace` appears in argv.
+ *
+ * Pre-parsed argv detection lets the CLI install the sink before
+ * `surface()` parses argv. The flag is also wired through the build
+ * pipeline as a meta flag, so trail input is unaffected.
+ */
+export const argvHasTraceFlag = (argv: readonly string[]): boolean =>
+  argv.includes('--trace');
+
+// ---------------------------------------------------------------------------
+// Sink session
+// ---------------------------------------------------------------------------
+
+/** Handle returned by {@link installTraceSink}. */
+export interface TraceSession {
+  /** The fresh in-memory sink that received records during this invocation. */
+  readonly sink: MemoryTraceSink;
+  /**
+   * Restore the previous trace sink and return a stable snapshot of the
+   * records collected during this session. Safe to call once; subsequent
+   * calls return an empty array.
+   */
+  readonly finalize: () => readonly TraceRecord[];
+}
+
+const restoreSink = (previous: TraceSink): void => {
+  // `registerTraceSink(undefined)` collapses back to `NOOP_SINK`, which is
+  // what we want when the prior sink was the default no-op singleton. For
+  // any other prior sink (e.g. an OTel adapter wired by the host), restore
+  // it directly so we do not accidentally drop the host's configured sink.
+  registerTraceSink(previous);
+};
+
+/**
+ * Register a fresh {@link MemoryTraceSink} as the active trace sink and
+ * return a handle that can later restore the previous sink.
+ */
+export const installTraceSink = (): TraceSession => {
+  const previous = getTraceSink();
+  const sink = createMemorySink();
+  registerTraceSink(sink);
+
+  let finalized = false;
+  return {
+    finalize: () => {
+      if (finalized) {
+        return [];
+      }
+      finalized = true;
+      const records = sink.records();
+      restoreSink(previous);
+      return records;
+    },
+    sink,
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Stderr rendering
+// ---------------------------------------------------------------------------
+
+/**
+ * Render the captured records as a tree to stderr, followed by a newline.
+ *
+ * No-ops on an empty record list so that quiet trails (e.g. metadata reads
+ * that never invoke `executeTrail`) do not produce a stray blank line.
+ */
+export const writeTraceTreeToStderr = (
+  records: readonly TraceRecord[]
+): void => {
+  if (records.length === 0) {
+    return;
+  }
+  const tree = renderTraceTree(records);
+  if (tree.length === 0) {
+    return;
+  }
+  process.stderr.write(`${tree}\n`);
+};
+
+// ---------------------------------------------------------------------------
+// JSON envelope shaping
+// ---------------------------------------------------------------------------
+
+/**
+ * Result-style envelope emitted on stdout under `--trace --json`.
+ *
+ * Mirrors the shape of `Result<T, E>` but adds a `tracing` field so a
+ * downstream consumer can deserialize the run outcome and the structured
+ * trace from a single document.
+ */
+export type TraceJsonEnvelope =
+  | {
+      readonly ok: true;
+      readonly value: unknown;
+      readonly tracing: readonly TraceRecord[];
+    }
+  | {
+      readonly ok: false;
+      readonly error: { readonly message: string; readonly name: string };
+      readonly tracing: readonly TraceRecord[];
+    };
+
+/**
+ * Minimal Result-shape contract used by the JSON envelope builder.
+ *
+ * The `value` and `error` properties may be present at the same time on a
+ * Result instance (the discriminated union narrows by `isOk` / `isErr`),
+ * so this interface keeps both optional and lets the builder branch without
+ * asserting either side.
+ */
+interface ResultLike {
+  readonly isOk: () => boolean;
+  readonly isErr: () => boolean;
+  readonly value?: unknown;
+  readonly error?: unknown;
+}
+
+const errorFromUnknown = (
+  value: unknown
+): { readonly message: string; readonly name: string } => {
+  if (value instanceof Error) {
+    return { message: value.message, name: value.name };
+  }
+  return { message: String(value), name: 'Error' };
+};
+
+/**
+ * Build the stdout envelope for `--trace --json`.
+ *
+ * On success, the inner value is taken straight from the trail's
+ * `Result.ok(...)` payload. On failure the envelope captures the error's
+ * `name` and `message` -- both safe to serialize and consistent with how
+ * other Trails surfaces project errors.
+ */
+export const buildTraceJsonEnvelope = (
+  result: ResultLike,
+  records: readonly TraceRecord[]
+): TraceJsonEnvelope => {
+  if (result.isOk()) {
+    return {
+      ok: true,
+      tracing: records,
+      value: result.value,
+    };
+  }
+  return {
+    error: errorFromUnknown(result.error),
+    ok: false,
+    tracing: records,
+  };
+};
+
+/**
+ * Serialize a {@link TraceJsonEnvelope} as a single JSON document for stdout.
+ *
+ * Indented with two spaces to match the rest of the CLI's `--json`
+ * formatting (see `output()` in `@ontrails/cli`).
+ */
+export const formatTraceJsonEnvelope = (envelope: TraceJsonEnvelope): string =>
+  `${JSON.stringify(envelope, null, 2)}\n`;
+
+// ---------------------------------------------------------------------------
+// onResult bridge
+// ---------------------------------------------------------------------------
+
+interface TryTraceCtx {
+  readonly flags: Record<string, unknown>;
+  readonly result: ResultLike;
+  readonly trail?: { readonly id: string } | undefined;
+}
+
+const isJsonMode = (flags: Record<string, unknown>): boolean => {
+  if (flags['json'] === true) {
+    return true;
+  }
+  if (typeof flags['output'] === 'string' && flags['output'] === 'json') {
+    return true;
+  }
+  return false;
+};
+
+const shouldEmitTraceEnvelope = (flags: Record<string, unknown>): boolean => {
+  if (flags['trace'] !== true) {
+    return false;
+  }
+  if (flags['quiet'] === true) {
+    // `--quiet` is the explicit pipe-friendly mode. Adding the tracing
+    // envelope to stdout would defeat the contract -- defer to the
+    // existing quiet handler for stdout and only render the tree on
+    // stderr (handled outside this helper).
+    return false;
+  }
+  if (flags['jsonl'] === true) {
+    // `--jsonl` streams items per line; the structured envelope cannot be
+    // expressed without breaking the line-delimited contract.
+    return false;
+  }
+  return isJsonMode(flags);
+};
+
+const traceOutputIsOwnedByRunFamily = (ctx: TryTraceCtx): boolean => {
+  if (ctx.trail?.id === 'run.example') {
+    // `run.example` owns stdout via its comparison envelope. Still render the
+    // trace tree to stderr, but do not override the example helper output.
+    return false;
+  }
+  if (ctx.trail?.id === 'run.examples') {
+    // Pure metadata read; no execution to trace.
+    return false;
+  }
+  return true;
+};
+
+/**
+ * If the invocation requested both `--trace` and `--json`, serialize the
+ * trace envelope to stdout and return `true`. Otherwise return `false` so
+ * the caller falls through to the regular on-result chain.
+ *
+ * The stderr tree is **not** rendered here -- it is rendered uniformly
+ * for every `--trace` invocation in the CLI entry-point's `finally`
+ * block, even when this helper short-circuits.
+ */
+export const tryTraceJsonOutput = (
+  ctx: TryTraceCtx,
+  session: TraceSession
+): boolean => {
+  if (
+    !shouldEmitTraceEnvelope(ctx.flags) ||
+    !traceOutputIsOwnedByRunFamily(ctx)
+  ) {
+    return false;
+  }
+  const records = session.sink.records();
+  const envelope = buildTraceJsonEnvelope(ctx.result, records);
+  process.stdout.write(formatTraceJsonEnvelope(envelope));
+  return true;
+};

package/src/run-warden.ts

@@ -0,0 +1,39 @@
+import type { ActionResultContext } from '@ontrails/cli';
+
+interface WardenResultValue {
+  readonly formatted: string;
+  readonly passed?: boolean | undefined;
+}
+
+const isWardenResultValue = (value: unknown): value is WardenResultValue => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const candidate = value as Record<string, unknown>;
+  return (
+    typeof candidate['formatted'] === 'string' &&
+    (candidate['passed'] === undefined ||
+      typeof candidate['passed'] === 'boolean')
+  );
+};
+
+export const tryWardenOutput = (ctx: ActionResultContext): boolean => {
+  if (
+    (ctx.trail.id !== 'warden' && ctx.trail.id !== 'warden.guide') ||
+    ctx.result.isErr()
+  ) {
+    return false;
+  }
+  const { value } = ctx.result;
+  if (!isWardenResultValue(value)) {
+    return false;
+  }
+
+  if (value.formatted.length > 0) {
+    process.stdout.write(`${value.formatted}\n`);
+  }
+  if (typeof value.passed === 'boolean') {
+    process.exitCode = value.passed ? 0 : 1;
+  }
+  return true;
+};