@ontrails/core 1.0.0-beta.4 → 1.0.0-beta.41

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 projected 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

@@ -4,6 +4,24 @@
 
 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;
 

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];
+};