@ontrails/core 0.2.0

package/src/resource.ts

@@ -0,0 +1,194 @@
+import { InternalError } from './errors.js';
+import type { Result } from './result.js';
+import type { AnySignal } from './signal.js';
+import type { ResourceLookup, TrailContext } from './types.js';
+import type { z } from 'zod';
+
+/**
+ * Stable process-scoped fields available when constructing a resource.
+ *
+ * Resources are app-level singletons, so they intentionally do not receive
+ * the full per-request TrailContext. When a resource declares a `config` schema,
+ * the validated config is passed as `resourceCtx.config`.
+ */
+export type ResourceContext<C = unknown> = Pick<
+  TrailContext,
+  'cwd' | 'env' | 'workspaceRoot'
+> & {
+  readonly config: C;
+};
+
+/** Explicit marker for resources that intentionally cannot provide a mock. */
+export interface ResourceUnmockable {
+  readonly reason: string;
+}
+
+/**
+ * Everything needed to describe a resource before a factory is introduced.
+ *
+ * When `config` is a Zod schema, the `create` callback receives
+ * `ResourceContext<C>` with the validated config value.
+ */
+export interface ResourceSpec<T, C = unknown> {
+  /** Create the resource instance from stable process-scoped context. */
+  readonly create: (
+    resourceCtx: ResourceContext<C>
+  ) => Result<T, Error> | Promise<Result<T, Error>>;
+  /** Config schema — when present, config is validated and passed to `create`. */
+  readonly config?: z.ZodType<C> | undefined;
+  /** Optional cleanup performed when the host application shuts down. */
+  readonly dispose?: ((resource: T) => void | Promise<void>) | undefined;
+  /** Optional operational readiness probe for introspection tooling. */
+  readonly health?:
+    | ((
+        resource: T
+      ) => Result<unknown, Error> | Promise<Result<unknown, Error>>)
+    | undefined;
+  /** Optional test factory used by higher-level helpers. */
+  readonly mock?: (() => T | Promise<T>) | undefined;
+  /** Document why this resource intentionally cannot provide a test mock. */
+  readonly unmockable?: ResourceUnmockable | undefined;
+  /** Human-readable description. */
+  readonly description?: string | undefined;
+  /** Arbitrary meta for tooling and filtering. */
+  readonly meta?: Readonly<Record<string, unknown>> | undefined;
+  /** Signals derived or owned by this resource. */
+  readonly signals?: readonly AnySignal[] | undefined;
+  /** Reserved for future resource-specific design; trail versioning is trail-only. */
+  readonly version?: never;
+}
+
+type ResourceSpecWithConfig<T, S extends z.ZodTypeAny> = Omit<
+  ResourceSpec<T, z.infer<S>>,
+  'config'
+> & {
+  readonly config: S;
+};
+
+/** A typed resource definition. */
+export interface Resource<T, C = unknown> extends ResourceSpec<T, C> {
+  readonly kind: 'resource';
+  readonly id: string;
+  /** Read the resolved resource instance from a trail context. */
+  from(ctx: TrailContext): T;
+}
+
+/**
+ * Existential type for heterogeneous resource collections.
+ *
+ * `Resource<T>` includes function parameters in `dispose`/`health`, so
+ * `unknown` is too narrow for mixed resource arrays. `any` is the correct
+ * existential here.
+ */
+// oxlint-disable-next-line no-explicit-any -- existential type for heterogeneous resource collections
+export type AnyResource = Resource<any, any>;
+
+/** Explicit runtime overrides keyed by resource ID. */
+export type ResourceOverrideMap = Readonly<Record<string, unknown>>;
+
+const getResourceId = <T>(
+  resourceOrId: string | Pick<Resource<T>, 'id'>
+): string =>
+  typeof resourceOrId === 'string' ? resourceOrId : resourceOrId.id;
+
+const getResourceInstance = <T>(
+  ctx: Pick<TrailContext, 'extensions'>,
+  resourceOrId: string | Pick<Resource<T>, 'id'>
+): T => {
+  const id = getResourceId(resourceOrId);
+  return ctx.extensions?.[id] as T;
+};
+
+const hasResourceInstance = (
+  ctx: Pick<TrailContext, 'extensions'>,
+  resourceOrId: string | Pick<AnyResource, 'id'>
+): boolean => Object.hasOwn(ctx.extensions ?? {}, getResourceId(resourceOrId));
+
+/** Create a `ctx.resource(...)` accessor bound to a concrete context snapshot. */
+export const createResourceLookup = (
+  getContext: () => Pick<TrailContext, 'extensions'>
+): ResourceLookup =>
+  ((resourceOrId: string | Pick<AnyResource, 'id'>) => {
+    const id = getResourceId(resourceOrId);
+    const ctx = getContext();
+    if (!hasResourceInstance(ctx, id)) {
+      throw new InternalError(`Resource "${id}" not provisioned in context`);
+    }
+    return getResourceInstance(ctx, id);
+  }) as ResourceLookup;
+
+/**
+ * Create a typed resource definition.
+ *
+ * The resource object is inert until a later execution branch resolves concrete
+ * instances into TrailContext extensions.
+ */
+export function resource<T, S extends z.ZodTypeAny>(
+  id: string,
+  spec: ResourceSpecWithConfig<T, S>
+): Resource<T, z.infer<S>>;
+export function resource<T, C = unknown>(
+  id: string,
+  spec: ResourceSpec<T, C>
+): Resource<T, C>;
+export function resource<T, C = unknown>(
+  id: string,
+  spec: ResourceSpec<T, C>
+): Resource<T, C> {
+  if (id.includes(':')) {
+    throw new InternalError(
+      `Resource "${id}" is invalid because resource ids may not contain ":"`
+    );
+  }
+  if (spec.mock !== undefined && spec.unmockable !== undefined) {
+    throw new InternalError(
+      `Resource "${id}" cannot define both mock and unmockable`
+    );
+  }
+  if (
+    spec.unmockable !== undefined &&
+    spec.unmockable.reason.trim().length === 0
+  ) {
+    throw new InternalError(
+      `Resource "${id}" is invalid because unmockable.reason must not be empty`
+    );
+  }
+
+  return Object.freeze({
+    ...spec,
+    from(ctx: TrailContext): T {
+      const lookup = ctx.resource ?? createResourceLookup(() => ctx);
+      return lookup(this);
+    },
+    id,
+    kind: 'resource' as const,
+  });
+}
+
+/** Narrow unknown values to resource definitions during topo discovery. */
+export const isResource = (value: unknown): value is AnyResource => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const v = value as { kind?: unknown; id?: unknown };
+  return v.kind === 'resource' && typeof v.id === 'string';
+};
+
+/**
+ * Return the first duplicate resource ID in a collection, if any.
+ *
+ * This supports later topo registration without each caller duplicating the
+ * same scan logic.
+ */
+export const findDuplicateResourceId = (
+  resources: readonly Pick<AnyResource, 'id'>[]
+): string | undefined => {
+  const seen = new Set<string>();
+  for (const candidate of resources) {
+    if (seen.has(candidate.id)) {
+      return candidate.id;
+    }
+    seen.add(candidate.id);
+  }
+  return undefined;
+};

package/src/result.ts

@@ -0,0 +1,212 @@
+/**
+ * A type-safe Result monad for representing success/failure without exceptions.
+ */
+
+import { InternalError, ValidationError } from './errors.js';
+
+export const resultAccessorNames = [
+  'error',
+  'flatMap',
+  'isErr',
+  'isOk',
+  'map',
+  'mapErr',
+  'match',
+  'unwrap',
+  'unwrapOr',
+  'value',
+] as const satisfies readonly (
+  | keyof Ok<unknown, unknown>
+  | keyof Err<unknown>
+)[];
+
+export type ResultAccessorName = (typeof resultAccessorNames)[number];
+
+class Ok<T, E> {
+  readonly value: T;
+
+  constructor(value: T) {
+    this.value = value;
+  }
+
+  // oxlint-disable-next-line class-methods-use-this -- type guard for Result discriminated union
+  isOk(): this is Ok<T, E> {
+    return true;
+  }
+
+  // oxlint-disable-next-line class-methods-use-this -- type guard for Result discriminated union
+  isErr(): this is Err<E> {
+    return false;
+  }
+
+  map<U>(fn: (value: T) => U): Result<U, E> {
+    return new Ok(fn(this.value));
+  }
+
+  flatMap<U, F = E>(fn: (value: T) => Result<U, F>): Result<U, E | F> {
+    return fn(this.value);
+  }
+
+  mapErr<F>(_fn: (error: E) => F): Result<T, F> {
+    return new Ok(this.value);
+  }
+
+  match<U>(handlers: { ok: (value: T) => U; err: (error: E) => U }): U {
+    return handlers.ok(this.value);
+  }
+
+  unwrap(): T {
+    return this.value;
+  }
+
+  unwrapOr(_fallback: T): T {
+    return this.value;
+  }
+}
+
+// oxlint-disable-next-line max-classes-per-file -- Result monad requires paired Ok/Err classes
+class Err<E> {
+  readonly error: E;
+
+  constructor(error: E) {
+    this.error = error;
+  }
+
+  // oxlint-disable-next-line class-methods-use-this -- type guard for Result discriminated union
+  isOk(): this is Ok<never, E> {
+    return false;
+  }
+
+  // oxlint-disable-next-line class-methods-use-this -- type guard for Result discriminated union
+  isErr(): this is Err<E> {
+    return true;
+  }
+
+  map<U>(_fn: (value: never) => U): Result<U, E> {
+    return new Err(this.error);
+  }
+
+  flatMap<U, F = E>(_fn: (value: never) => Result<U, F>): Result<U, E | F> {
+    return new Err(this.error);
+  }
+
+  mapErr<F>(fn: (error: E) => F): Result<never, F> {
+    return new Err(fn(this.error));
+  }
+
+  match<U>(handlers: { ok: (value: never) => U; err: (error: E) => U }): U {
+    return handlers.err(this.error);
+  }
+
+  unwrap(): never {
+    throw this.error instanceof Error
+      ? this.error
+      : new Error(String(this.error));
+  }
+
+  // oxlint-disable-next-line class-methods-use-this -- symmetric API with Ok.unwrapOr
+  unwrapOr<T>(fallback: T): T {
+    return fallback;
+  }
+}
+
+export type Result<T, E = Error> = Ok<T, E> | Err<E>;
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export const Result = {
+  combine<T, E>(results: readonly Result<T, E>[]): Result<T[], E> {
+    const values: T[] = [];
+    for (const result of results) {
+      if (result.isErr()) {
+        return new Err(result.error);
+      }
+      values.push(result.value);
+    }
+    return new Ok(values);
+  },
+
+  err<E>(error: E): Err<E> {
+    return new Err(error);
+  },
+
+  /**
+   * Wrap a fetch call in a Result, mapping failures to TrailsError subclasses.
+   *
+   * Network errors become NetworkError. Abort signals become CancelledError.
+   * HTTP error status codes map to the appropriate error category.
+   */
+  async fromFetch(
+    input: string | URL | Request,
+    init?: RequestInit
+  ): Promise<Result<Response, Error>> {
+    // Lazy import avoids a circular dependency (fetch.ts imports Result)
+    const { fromFetch: fetchImpl } = await import('./fetch.js');
+    return fetchImpl(input, init);
+  },
+
+  /**
+   * Parse a JSON string, returning a Result instead of throwing.
+   */
+  fromJson(json: string): Result<unknown, ValidationError> {
+    try {
+      return new Ok(JSON.parse(json) as unknown);
+    } catch (error) {
+      return new Err(
+        new ValidationError('Invalid JSON', {
+          cause: error instanceof Error ? error : new Error(String(error)),
+          context: { input: json.slice(0, 200) },
+        })
+      );
+    }
+  },
+
+  ok<T = void>(value?: T): Result<T, never> {
+    return new Ok(value as T);
+  },
+
+  /**
+   * Stringify a value to JSON, returning a Result. Handles circular references.
+   */
+  toJson(value: unknown): Result<string, InternalError> {
+    try {
+      // Track the current ancestor chain, not every object ever visited.
+      // This allows shared references in a DAG while still detecting cycles.
+      const stack: unknown[] = [];
+      const keys: string[] = [];
+
+      const json = JSON.stringify(value, function json(key, val: unknown) {
+        if (stack.length > 0) {
+          // `this` is the object that contains `key`. Trim the stack back
+          // to `this` so we only track the current ancestor path.
+          const thisIndex = stack.lastIndexOf(this as unknown);
+          stack.splice(thisIndex + 1);
+          keys.splice(thisIndex);
+        }
+
+        if (typeof val === 'object' && val !== null) {
+          if (stack.includes(val)) {
+            return '[Circular]';
+          }
+          stack.push(val);
+          keys.push(key);
+        }
+        return val;
+      });
+
+      if (json === undefined) {
+        return new Err(
+          new InternalError('Value is not JSON-serializable', {
+            context: { type: typeof value },
+          })
+        );
+      }
+      return new Ok(json);
+    } catch (error) {
+      return new Err(
+        new InternalError('Failed to stringify value', {
+          cause: error instanceof Error ? error : new Error(String(error)),
+        })
+      );
+    }
+  },
+} as const;

package/src/run.ts

@@ -0,0 +1,76 @@
+/**
+ * Headless trail execution without surface registration.
+ *
+ * Looks up a trail by ID in a topo, then delegates to `executeTrail`.
+ * Returns a `Result` and never throws.
+ */
+
+import type { Topo } from './topo.js';
+import { executeTrail } from './execute.js';
+import type { ExecuteTrailOptions } from './execute.js';
+import { parseTrailIdVersionReference } from './version-resolution.js';
+import { NotFoundError, ValidationError } from './errors.js';
+import { Result } from './result.js';
+
+// ---------------------------------------------------------------------------
+// Options
+// ---------------------------------------------------------------------------
+
+/** Options forwarded to `executeTrail` from `run`. */
+export type RunOptions = ExecuteTrailOptions;
+
+// ---------------------------------------------------------------------------
+// run()
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a trail by ID from a topo without registering it on a surface.
+ *
+ * Resolves the trail from the topo, then runs it through the standard
+ * `executeTrail` pipeline with `topo` threaded so `ctx.fire()` is bound
+ * to the producer's context inside `executeTrail`. Returns
+ * `Result.err(NotFoundError)` if the trail ID is not registered. Never
+ * throws — unexpected exceptions are returned as `Result.err(InternalError)`.
+ *
+ * @example
+ * ```typescript
+ * const result = await run(myTopo, 'greet', { name: 'Alice' });
+ * if (result.isOk()) console.log(result.value);
+ * ```
+ */
+export const run = (
+  topo: Topo,
+  id: string,
+  input: unknown,
+  options?: RunOptions
+): Promise<Result<unknown, Error>> => {
+  const parsed = parseTrailIdVersionReference(id);
+  if (parsed.isErr()) {
+    return Promise.resolve(Result.err(parsed.error));
+  }
+  if (parsed.value.version !== undefined && options?.version !== undefined) {
+    return Promise.resolve(
+      Result.err(
+        new ValidationError(
+          `Trail "${parsed.value.id}" cannot combine an @version suffix with options.version`
+        )
+      )
+    );
+  }
+
+  const trail = topo.get(parsed.value.id);
+  if (trail === undefined) {
+    return Promise.resolve(
+      Result.err(
+        new NotFoundError(`Trail "${id}" not found in topo "${topo.name}"`)
+      )
+    );
+  }
+  return executeTrail(trail, input, {
+    ...options,
+    ...(parsed.value.version === undefined
+      ? {}
+      : { version: parsed.value.version }),
+    topo,
+  });
+};

package/src/runtime-builtins.ts

@@ -0,0 +1,69 @@
+/**
+ * Lazy runtime-builtin loading for the execution-portable core barrel.
+ *
+ * Core tooling modules that need Bun or Node capabilities (`bun:sqlite`,
+ * `node:fs`, `node:os`, `node:path`) must not import them eagerly: the
+ * core barrel sits on the execution path of every surface, and edge
+ * runtimes such as workerd refuse module graphs that import `bun:`
+ * builtins and gate `node:` builtins behind compatibility flags
+ * (TRL-1198). Loading through `process.getBuiltinModule` keeps the
+ * specifier out of bundler module graphs entirely and defers the
+ * capability requirement to first use, so runtimes that never call a
+ * tooling helper never pay for it.
+ */
+
+import type * as BunSqlite from 'bun:sqlite';
+import type * as NodeFs from 'node:fs';
+import type * as NodeOs from 'node:os';
+import type * as NodePath from 'node:path';
+
+import { InternalError } from './errors.js';
+
+interface BuiltinModules {
+  readonly 'bun:sqlite': typeof BunSqlite;
+  readonly 'node:fs': typeof NodeFs;
+  readonly 'node:os': typeof NodeOs;
+  readonly 'node:path': typeof NodePath;
+}
+
+const loadedBuiltins = new Map<keyof BuiltinModules, unknown>();
+
+/**
+ * Load a Bun/Node builtin module at first use.
+ *
+ * @throws {InternalError} When the runtime does not expose the builtin
+ * (for example workerd without `nodejs_compat`). Trail execution never
+ * reaches this loader; only tooling helpers (trails-db, workspace
+ * discovery) do.
+ */
+export const loadRuntimeBuiltin = <TName extends keyof BuiltinModules>(
+  name: TName
+): BuiltinModules[TName] => {
+  const cached = loadedBuiltins.get(name);
+  if (cached !== undefined) {
+    return cached as BuiltinModules[TName];
+  }
+
+  const proc = (
+    globalThis as {
+      readonly process?: {
+        readonly getBuiltinModule?: (id: string) => unknown;
+      };
+    }
+  ).process;
+  if (typeof proc?.getBuiltinModule !== 'function') {
+    throw new InternalError(
+      `Runtime builtin "${name}" is unavailable: this runtime does not expose process.getBuiltinModule. Trails tooling helpers need a Bun or Node runtime; the trail execution path never loads them.`
+    );
+  }
+
+  const loaded = proc.getBuiltinModule(name);
+  if (loaded === undefined || loaded === null) {
+    throw new InternalError(
+      `Runtime builtin "${name}" is unavailable on this runtime.`
+    );
+  }
+
+  loadedBuiltins.set(name, loaded);
+  return loaded as BuiltinModules[TName];
+};