@ontrails/core 1.0.0-beta.0

package/src/topo.ts

@@ -0,0 +1,123 @@
+/**
+ * Application entry point — scans module exports to build a topology graph.
+ */
+
+import { ValidationError } from './errors.js';
+import type { AnyEvent } from './event.js';
+import type { AnyHike } from './hike.js';
+import type { AnyTrail } from './trail.js';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface Topo {
+  readonly name: string;
+  readonly trails: ReadonlyMap<string, AnyTrail>;
+  readonly hikes: ReadonlyMap<string, AnyHike>;
+  readonly events: ReadonlyMap<string, AnyEvent>;
+  get(id: string): AnyTrail | AnyHike | undefined;
+  has(id: string): boolean;
+  list(): (AnyTrail | AnyHike)[];
+  listEvents(): AnyEvent[];
+}
+
+// ---------------------------------------------------------------------------
+// Kind discriminant check
+// ---------------------------------------------------------------------------
+
+type Registrable = AnyTrail | AnyHike | AnyEvent;
+
+const isRegistrable = (value: unknown): value is Registrable => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const { kind } = value as Record<string, unknown>;
+  return kind === 'trail' || kind === 'hike' || kind === 'event';
+};
+
+// ---------------------------------------------------------------------------
+// Topo implementation
+// ---------------------------------------------------------------------------
+
+const createTopo = (
+  name: string,
+  trails: ReadonlyMap<string, AnyTrail>,
+  hikes: ReadonlyMap<string, AnyHike>,
+  events: ReadonlyMap<string, AnyEvent>
+): Topo => ({
+  events,
+  get(id: string): AnyTrail | AnyHike | undefined {
+    return trails.get(id) ?? hikes.get(id);
+  },
+  has(id: string): boolean {
+    return trails.has(id) || hikes.has(id);
+  },
+  hikes,
+
+  list(): (AnyTrail | AnyHike)[] {
+    return [...trails.values(), ...hikes.values()];
+  },
+
+  listEvents(): AnyEvent[] {
+    return [...events.values()];
+  },
+
+  name,
+
+  trails,
+});
+
+// ---------------------------------------------------------------------------
+// topo()
+// ---------------------------------------------------------------------------
+
+/** Register a single registrable value into the appropriate map. */
+const register = (
+  value: Registrable,
+  trails: Map<string, AnyTrail>,
+  hikes: Map<string, AnyHike>,
+  events: Map<string, AnyEvent>
+): void => {
+  const { id } = value as { id: string };
+  const registrars: Record<string, () => void> = {
+    event: () => {
+      if (events.has(id)) {
+        throw new ValidationError(`Duplicate event ID: "${id}"`);
+      }
+      events.set(id, value as AnyEvent);
+    },
+    hike: () => {
+      if (hikes.has(id)) {
+        throw new ValidationError(`Duplicate hike ID: "${id}"`);
+      }
+      hikes.set(id, value as AnyHike);
+    },
+    trail: () => {
+      if (trails.has(id)) {
+        throw new ValidationError(`Duplicate trail ID: "${id}"`);
+      }
+      trails.set(id, value as AnyTrail);
+    },
+  };
+  registrars[value.kind]?.();
+};
+
+export const topo = (
+  name: string,
+  ...modules: Record<string, unknown>[]
+): Topo => {
+  const trails = new Map<string, AnyTrail>();
+  const hikes = new Map<string, AnyHike>();
+  const events = new Map<string, AnyEvent>();
+
+  for (const mod of modules) {
+    for (const value of Object.values(mod)) {
+      if (isRegistrable(value)) {
+        register(value, trails, hikes, events);
+      }
+    }
+  }
+
+  return createTopo(name, trails, hikes, events);
+};

package/src/trail.ts

@@ -0,0 +1,130 @@
+import type { z } from 'zod';
+
+import type { FieldOverride } from './derive.js';
+import type { Result } from './result.js';
+import type { Implementation, TrailContext } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Trail example
+// ---------------------------------------------------------------------------
+
+/**
+ * A named example for documentation and testing.
+ *
+ * The `input` field accepts `Partial<I>` so that fields with schema defaults
+ * (e.g. `z.number().default(20)`) can be omitted from examples. The schema
+ * fills in defaults at validation time.
+ */
+export interface TrailExample<I, O> {
+  /** Human-readable name */
+  readonly name: string;
+  /** Optional description of what this example demonstrates */
+  readonly description?: string | undefined;
+  /** The input value — fields with schema defaults may be omitted */
+  readonly input: Partial<I>;
+  /** Expected output for success-path examples */
+  readonly expected?: O | undefined;
+  /** Error class name for error-path examples */
+  readonly error?: string | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Trail spec
+// ---------------------------------------------------------------------------
+
+/** Everything needed to define a trail (minus the id) */
+export interface TrailSpec<I, O> {
+  /** Zod schema for validating input */
+  readonly input: z.ZodType<I>;
+  /** Zod schema for validating output (optional — some trails are fire-and-forget) */
+  readonly output?: z.ZodType<O> | undefined;
+  /** The pure function that does the work (sync or async authoring) */
+  readonly implementation: Implementation<I, O>;
+  /** Human-readable description */
+  readonly description?: string | undefined;
+  /** Named examples for docs and testing */
+  readonly examples?: readonly TrailExample<I, O>[] | undefined;
+  /** Trail is read-only (no side effects) */
+  readonly readOnly?: boolean | undefined;
+  /** Trail is destructive (deletes or overwrites data) */
+  readonly destructive?: boolean | undefined;
+  /** Trail is idempotent (safe to retry) */
+  readonly idempotent?: boolean | undefined;
+  /** Arbitrary metadata for tooling and filtering */
+  readonly markers?: Readonly<Record<string, unknown>> | undefined;
+  /** Named sets of downstream trail IDs that may be invoked */
+  readonly detours?: Readonly<Record<string, readonly string[]>> | undefined;
+  /** Per-field overrides for deriveFields() (labels, hints, options) */
+  readonly fields?: Readonly<Record<string, FieldOverride>> | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Trail (the frozen runtime object)
+// ---------------------------------------------------------------------------
+
+/** A fully-defined trail — the unit of work in the Trails system */
+export interface Trail<I, O> extends Omit<TrailSpec<I, O>, 'implementation'> {
+  readonly kind: 'trail';
+  readonly id: string;
+  readonly implementation: Implementation<I, O>;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a trail definition.
+ *
+ * Returns a frozen object with `kind: "trail"` and all spec fields.
+ * The trail is inert until handed to a runner.
+ *
+ * @example
+ * ```typescript
+ * // ID as first argument (recommended for human authoring)
+ * const show = trail("entity.show", {
+ *   input: z.object({ name: z.string() }),
+ *   implementation: (input) => Result.ok(entity),
+ * });
+ *
+ * // Full spec object (for programmatic generation)
+ * const show = trail({
+ *   id: "entity.show",
+ *   input: z.object({ name: z.string() }),
+ *   implementation: (input) => Result.ok(entity),
+ * });
+ * ```
+ */
+export function trail<I, O>(id: string, spec: TrailSpec<I, O>): Trail<I, O>;
+export function trail<I, O>(
+  spec: TrailSpec<I, O> & { readonly id: string }
+): Trail<I, O>;
+export function trail<I, O>(
+  idOrSpec: string | (TrailSpec<I, O> & { readonly id: string }),
+  maybeSpec?: TrailSpec<I, O>
+): Trail<I, O> {
+  const resolved =
+    typeof idOrSpec === 'string'
+      ? { id: idOrSpec, spec: maybeSpec }
+      : { id: idOrSpec.id, spec: idOrSpec };
+
+  if (!resolved.spec) {
+    throw new TypeError('trail() requires a spec when an id is provided');
+  }
+
+  const { implementation, ...spec } = resolved.spec;
+
+  return Object.freeze({
+    ...spec,
+    id: resolved.id,
+    implementation: async (input: I, ctx: TrailContext) =>
+      await implementation(input, ctx),
+    kind: 'trail' as const,
+  });
+}
+
+// Re-export types that callers of trail() will need
+// oxlint-disable-next-line no-explicit-any -- existential type for heterogeneous collections; `any` is correct here because Implementation is contravariant in I
+export type AnyTrail = Trail<any, any>;
+
+export type { Implementation, TrailContext, Result };

package/src/types.ts

@@ -0,0 +1,58 @@
+import type { Result } from './result.js';
+
+/**
+ * Trail implementation — sync or async.
+ *
+ * Authors can return `Result` directly or wrap it in a `Promise`. The framework
+ * normalizes with `await` at every call site, so both forms work transparently.
+ */
+export type Implementation<I, O> = (
+  input: I,
+  ctx: TrailContext
+) => Result<O, Error> | Promise<Result<O, Error>>;
+
+/** Invoke another trail by id — used for trail composition */
+export type FollowFn = <O>(
+  id: string,
+  input: unknown
+) => Promise<Result<O, Error>>;
+
+/** Callback for reporting progress from long-running trails */
+export type ProgressCallback = (event: ProgressEvent) => void;
+
+/** Structured progress event emitted during trail execution */
+export interface ProgressEvent {
+  readonly type: 'start' | 'progress' | 'complete' | 'error';
+  readonly current?: number | undefined;
+  readonly total?: number | undefined;
+  readonly message?: string | undefined;
+  readonly ts: string;
+}
+
+/** Minimal logger interface — implementations can bridge to any logging library */
+export interface Logger {
+  readonly name?: string | undefined;
+  trace(message: string, data?: Record<string, unknown>): void;
+  debug(message: string, data?: Record<string, unknown>): void;
+  info(message: string, data?: Record<string, unknown>): void;
+  warn(message: string, data?: Record<string, unknown>): void;
+  error(message: string, data?: Record<string, unknown>): void;
+  fatal(message: string, data?: Record<string, unknown>): void;
+  child(context: Record<string, unknown>): Logger;
+}
+
+/** Runtime context threaded through every trail execution */
+export interface TrailContext {
+  readonly requestId: string;
+  readonly signal: AbortSignal;
+  readonly follow?: FollowFn | undefined;
+  readonly permit?: unknown | undefined;
+  readonly workspaceRoot?: string | undefined;
+  readonly logger?: Logger | undefined;
+  readonly progress?: ProgressCallback | undefined;
+  readonly cwd?: string | undefined;
+  readonly env?: Record<string, string | undefined> | undefined;
+  readonly [key: string]: unknown;
+}
+
+export type Surface = 'cli' | 'mcp' | 'http' | 'ws';

package/src/validate-topo.ts

@@ -0,0 +1,151 @@
+/**
+ * Structural validation for a Topo graph.
+ *
+ * Checks hike follows references, example input validity, event origin
+ * references, and output schema completeness. Returns a Result with all
+ * issues collected into a single ValidationError.
+ */
+
+import { ValidationError } from './errors.js';
+import type { AnyEvent } from './event.js';
+import type { AnyHike } from './hike.js';
+import { Result } from './result.js';
+import type { Topo } from './topo.js';
+import type { AnyTrail } from './trail.js';
+import { validateInput } from './validation.js';
+
+// ---------------------------------------------------------------------------
+// Issue shape
+// ---------------------------------------------------------------------------
+
+export interface TopoIssue {
+  readonly trailId: string;
+  readonly rule: string;
+  readonly message: string;
+}
+
+// ---------------------------------------------------------------------------
+// Validators
+// ---------------------------------------------------------------------------
+
+const checkFollows = (
+  hikes: ReadonlyMap<string, AnyHike>,
+  topo: Topo
+): TopoIssue[] => {
+  const issues: TopoIssue[] = [];
+  for (const [id, hike] of hikes) {
+    for (const followId of hike.follows) {
+      if (followId === id) {
+        issues.push({
+          message: `Hike follows itself`,
+          rule: 'no-self-follow',
+          trailId: id,
+        });
+      } else if (!topo.has(followId)) {
+        issues.push({
+          message: `Follows "${followId}" which is not in the topo`,
+          rule: 'follows-exist',
+          trailId: id,
+        });
+      }
+    }
+  }
+  return issues;
+};
+
+const checkOneExample = (
+  id: string,
+  example: {
+    name: string;
+    input: unknown;
+    expected?: unknown | undefined;
+    error?: string | undefined;
+  },
+  inputSchema: { safeParse: (data: unknown) => { success: boolean } },
+  hasOutput: boolean
+): TopoIssue[] => {
+  const issues: TopoIssue[] = [];
+  const result = validateInput(inputSchema as AnyTrail['input'], example.input);
+  if (result.isErr() && example.error === undefined) {
+    issues.push({
+      message: `Example "${example.name}" input does not parse against schema`,
+      rule: 'example-input-valid',
+      trailId: id,
+    });
+  }
+  if (example.expected !== undefined && !hasOutput) {
+    issues.push({
+      message: `Example "${example.name}" has expected output but trail has no output schema`,
+      rule: 'output-schema-present',
+      trailId: id,
+    });
+  }
+  return issues;
+};
+
+const checkExamples = (trails: ReadonlyMap<string, AnyTrail>): TopoIssue[] => {
+  const issues: TopoIssue[] = [];
+  for (const [id, trail] of trails) {
+    if (!trail.examples) {
+      continue;
+    }
+    for (const example of trail.examples) {
+      issues.push(...checkOneExample(id, example, trail.input, !!trail.output));
+    }
+  }
+  return issues;
+};
+
+const checkEventOrigins = (
+  events: ReadonlyMap<string, AnyEvent>,
+  topo: Topo
+): TopoIssue[] => {
+  const issues: TopoIssue[] = [];
+  for (const [id, evt] of events) {
+    if (!evt.from) {
+      continue;
+    }
+    for (const originId of evt.from) {
+      if (!topo.has(originId)) {
+        issues.push({
+          message: `Event origin "${originId}" is not in the topo`,
+          rule: 'event-origin-exists',
+          trailId: id,
+        });
+      }
+    }
+  }
+  return issues;
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate the structural integrity of a Topo graph.
+ *
+ * Checks follows references, example inputs, event origins, and output
+ * schema presence. Returns `Result.ok()` when no issues are found, or
+ * `Result.err(ValidationError)` with all issues in the error context.
+ */
+export const validateTopo = (topo: Topo): Result<void, ValidationError> => {
+  const issues = [
+    ...checkFollows(topo.hikes, topo),
+    ...checkExamples(topo.trails),
+    ...checkEventOrigins(topo.events, topo),
+  ];
+
+  if (issues.length === 0) {
+    return Result.ok();
+  }
+
+  return Result.err(
+    new ValidationError(
+      `Topo validation failed with ${issues.length} issue(s)`,
+      {
+        context: { issues },
+      }
+    )
+  );
+};

package/src/validation.ts

@@ -0,0 +1,182 @@
+/**
+ * Validation utilities for @ontrails/core
+ *
+ * Wraps Zod parsing into Result types and provides JSON Schema conversion
+ * for trail input schemas.
+ */
+
+import type { z } from 'zod';
+
+import { ValidationError } from './errors.js';
+import { Result } from './result.js';
+
+// ---------------------------------------------------------------------------
+// Zod → JSON Schema (Zod v4)
+// ---------------------------------------------------------------------------
+
+/** Internal accessor for Zod v4's internals. */
+interface ZodInternals {
+  readonly _zod: {
+    readonly def: Readonly<Record<string, unknown>>;
+    readonly traits: ReadonlySet<string>;
+  };
+  readonly description?: string;
+}
+
+type JsonSchema = Record<string, unknown>;
+type JsonSchemaConverter = (schema: z.ZodType) => JsonSchema;
+
+// ---------------------------------------------------------------------------
+// Internal helpers (defined before usage)
+// ---------------------------------------------------------------------------
+
+const isOptionalLike = (s: ZodInternals): boolean => {
+  const defType = s._zod.def['type'] as string;
+  return defType === 'optional' || defType === 'default';
+};
+
+// ---------------------------------------------------------------------------
+// Issue formatting
+// ---------------------------------------------------------------------------
+
+/** Format each ZodIssue as "path: message" (or just "message" for root). */
+export const formatZodIssues = (issues: z.ZodIssue[]): string[] =>
+  issues.map((issue) => {
+    const path = issue.path.join('.');
+    return path ? `${path}: ${issue.message}` : issue.message;
+  });
+
+// ---------------------------------------------------------------------------
+// Input validation
+// ---------------------------------------------------------------------------
+
+/** Parse unknown data against a Zod schema, returning a Result. */
+export const validateInput = <T>(
+  schema: z.ZodType<T>,
+  data: unknown
+): Result<T, ValidationError> => {
+  const parsed = schema.safeParse(data);
+  if (parsed.success) {
+    return Result.ok(parsed.data);
+  }
+  const messages = formatZodIssues(parsed.error.issues);
+  return Result.err(
+    new ValidationError(messages.join('; '), {
+      cause: parsed.error,
+      context: { issues: parsed.error.issues },
+    })
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Output validation
+// ---------------------------------------------------------------------------
+
+/** Parse unknown data against a Zod schema, returning a Result suitable for output validation. */
+export const validateOutput = <T>(
+  schema: z.ZodType<T>,
+  data: unknown
+): Result<T, ValidationError> => {
+  const parsed = schema.safeParse(data);
+  if (parsed.success) {
+    return Result.ok(parsed.data);
+  }
+  const messages = formatZodIssues(parsed.error.issues);
+  return Result.err(
+    new ValidationError(`Output validation failed: ${messages.join('; ')}`, {
+      cause: parsed.error,
+      context: { issues: parsed.error.issues },
+    })
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Zod → JSON Schema (public API)
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert common Zod types to a JSON Schema object.
+ *
+ * Uses Zod v4's `_zod.def` and `_zod.traits` for introspection.
+ * Covers: string, number, boolean, object, array, enum, optional,
+ * default, union, literal, nullable, and describe.
+ */
+export const zodToJsonSchema: JsonSchemaConverter = (
+  schema: z.ZodType
+): JsonSchema => {
+  const s = schema as unknown as ZodInternals;
+
+  const collectObjectFields = (shape: Record<string, ZodInternals>) => {
+    const properties: JsonSchema = {};
+    const required: string[] = [];
+    for (const [key, value] of Object.entries(shape)) {
+      properties[key] = zodToJsonSchema(value as unknown as z.ZodType);
+      if (!isOptionalLike(value)) {
+        required.push(key);
+      }
+    }
+    return { properties, required };
+  };
+
+  const convertObject = (value: ZodInternals): JsonSchema => {
+    const shape = value._zod.def['shape'] as
+      | Record<string, ZodInternals>
+      | undefined;
+    if (!shape) {
+      return { type: 'object' };
+    }
+    const { properties, required } = collectObjectFields(shape);
+    const result: JsonSchema = { properties, type: 'object' };
+    if (required.length > 0) {
+      result['required'] = required;
+    }
+    return result;
+  };
+
+  const zodConverters: Record<string, (value: ZodInternals) => JsonSchema> = {
+    array: (value) => {
+      const element = value._zod.def['element'] as unknown as z.ZodType;
+      return { items: zodToJsonSchema(element), type: 'array' };
+    },
+    boolean: () => ({ type: 'boolean' }),
+    default: (value) => {
+      const inner = value._zod.def['innerType'] as unknown as z.ZodType;
+      const innerSchema = zodToJsonSchema(inner);
+      const rawDefault = value._zod.def['defaultValue'];
+      innerSchema['default'] =
+        typeof rawDefault === 'function' ? rawDefault() : rawDefault;
+      return innerSchema;
+    },
+    enum: (value) => {
+      const entries = value._zod.def['entries'] as Record<string, string>;
+      return { enum: Object.values(entries), type: 'string' };
+    },
+    literal: (value) => {
+      const values = value._zod.def['values'] as unknown[];
+      return { const: values[0] };
+    },
+    nullable: (value) => {
+      const inner = value._zod.def['innerType'] as unknown as z.ZodType;
+      return { anyOf: [zodToJsonSchema(inner), { type: 'null' }] };
+    },
+    number: () => ({ type: 'number' }),
+    object: convertObject,
+    optional: (value) => {
+      const inner = value._zod.def['innerType'] as unknown as z.ZodType;
+      return zodToJsonSchema(inner);
+    },
+    string: () => ({ type: 'string' }),
+    union: (value) => {
+      const options = value._zod.def['options'] as unknown as z.ZodType[];
+      return { anyOf: options.map((option) => zodToJsonSchema(option)) };
+    },
+  };
+
+  const converter = zodConverters[s._zod.def['type'] as string];
+  const base = converter ? converter(s) : {};
+
+  if (s.description) {
+    base['description'] = s.description;
+  }
+  return base;
+};