@ontrails/core 1.0.0-beta.0

package/src/adapters.ts

@@ -0,0 +1,68 @@
+import type { Result } from './result.js';
+
+// ---------------------------------------------------------------------------
+// Shared option types
+// ---------------------------------------------------------------------------
+
+/** Options for search queries */
+export interface SearchOptions {
+  readonly limit?: number | undefined;
+  readonly offset?: number | undefined;
+  readonly filters?: Readonly<Record<string, unknown>> | undefined;
+}
+
+/** A single search hit */
+export interface SearchResult {
+  readonly id: string;
+  readonly score: number;
+  readonly document: Readonly<Record<string, unknown>>;
+}
+
+/** Options for storage writes */
+export interface StorageOptions {
+  /** Time-to-live in milliseconds */
+  readonly ttl?: number | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Adapter port interfaces
+// ---------------------------------------------------------------------------
+
+/** Full-text / vector index adapter */
+export interface IndexAdapter {
+  index(
+    id: string,
+    document: Readonly<Record<string, unknown>>
+  ): Promise<Result<void, Error>>;
+
+  search(
+    query: string,
+    options?: SearchOptions
+  ): Promise<Result<readonly SearchResult[], Error>>;
+
+  remove(id: string): Promise<Result<void, Error>>;
+}
+
+/** Key-value storage adapter */
+export interface StorageAdapter {
+  get(key: string): Promise<Result<unknown, Error>>;
+  set(
+    key: string,
+    value: unknown,
+    options?: StorageOptions
+  ): Promise<Result<void, Error>>;
+  delete(key: string): Promise<Result<void, Error>>;
+  has(key: string): Promise<Result<boolean, Error>>;
+}
+
+/** Cache adapter with typed get/set and bulk clear */
+export interface CacheAdapter {
+  get<T>(key: string): Promise<Result<T | undefined, Error>>;
+  set<T>(
+    key: string,
+    value: T,
+    options?: StorageOptions
+  ): Promise<Result<void, Error>>;
+  delete(key: string): Promise<Result<void, Error>>;
+  clear(): Promise<Result<void, Error>>;
+}

package/src/blob-ref.ts

@@ -0,0 +1,39 @@
+/**
+ * BlobRef — a frozen reference to binary data for @ontrails/core.
+ */
+
+/** Immutable reference to a blob of binary data. */
+export interface BlobRef {
+  readonly name: string;
+  readonly mimeType: string;
+  readonly size: number;
+  readonly data: Uint8Array | ReadableStream<Uint8Array>;
+}
+
+/** Creates a frozen BlobRef. */
+export const createBlobRef = (options: {
+  name: string;
+  mimeType: string;
+  size: number;
+  data: Uint8Array | ReadableStream<Uint8Array>;
+}): BlobRef =>
+  Object.freeze({
+    data: options.data,
+    mimeType: options.mimeType,
+    name: options.name,
+    size: options.size,
+  });
+
+/** Type guard for BlobRef-shaped values. */
+export const isBlobRef = (value: unknown): value is BlobRef => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const obj = value as Record<string, unknown>;
+  return (
+    typeof obj['name'] === 'string' &&
+    typeof obj['mimeType'] === 'string' &&
+    typeof obj['size'] === 'number' &&
+    (obj['data'] instanceof Uint8Array || obj['data'] instanceof ReadableStream)
+  );
+};

package/src/branded.ts

@@ -0,0 +1,135 @@
+/**
+ * Branded types and validated constructors for @ontrails/core.
+ *
+ * Branded types enforce domain constraints at the type level while remaining
+ * plain primitives at runtime. Factory functions return Result so callers
+ * handle validation failures explicitly.
+ */
+
+import { ValidationError } from './errors.js';
+import type { Result } from './result.js';
+import { Result as R } from './result.js';
+
+// ---------------------------------------------------------------------------
+// Branding primitive
+// ---------------------------------------------------------------------------
+
+/** Attach a phantom tag to a base type. */
+export type Branded<T, Tag extends string> = T & { readonly __brand: Tag };
+
+/** Brand a value. No validation — use factory functions for safe construction. */
+export const brand = <T, Tag extends string>(
+  _tag: Tag,
+  value: T
+): Branded<T, Tag> => value as Branded<T, Tag>;
+
+/** Strip the brand and recover the underlying value. */
+export const unbrand = <T>(value: Branded<T, string>): T => value as T;
+
+// ---------------------------------------------------------------------------
+// Built-in branded types
+// ---------------------------------------------------------------------------
+
+export type UUID = Branded<string, 'UUID'>;
+export type Email = Branded<string, 'Email'>;
+export type NonEmptyString = Branded<string, 'NonEmptyString'>;
+export type PositiveInt = Branded<number, 'PositiveInt'>;
+
+// ---------------------------------------------------------------------------
+// Validation patterns
+// ---------------------------------------------------------------------------
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-7][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+// ---------------------------------------------------------------------------
+// Factory functions — each returns Result<BrandedType, ValidationError>
+// ---------------------------------------------------------------------------
+
+export const uuid = (value: string): Result<UUID, ValidationError> => {
+  if (!UUID_RE.test(value)) {
+    return R.err(
+      new ValidationError(`Invalid UUID: "${value}"`, {
+        context: { value },
+      })
+    );
+  }
+  return R.ok(value as UUID);
+};
+
+export const email = (value: string): Result<Email, ValidationError> => {
+  if (!EMAIL_RE.test(value)) {
+    return R.err(
+      new ValidationError(`Invalid email: "${value}"`, {
+        context: { value },
+      })
+    );
+  }
+  return R.ok(value as Email);
+};
+
+export const nonEmptyString = (
+  value: string
+): Result<NonEmptyString, ValidationError> => {
+  if (value.length === 0) {
+    return R.err(new ValidationError('String must not be empty'));
+  }
+  return R.ok(value as NonEmptyString);
+};
+
+export const positiveInt = (
+  value: number
+): Result<PositiveInt, ValidationError> => {
+  if (!Number.isInteger(value) || value <= 0) {
+    return R.err(
+      new ValidationError(`Expected positive integer, got ${value}`, {
+        context: { value },
+      })
+    );
+  }
+  return R.ok(value as PositiveInt);
+};
+
+// ---------------------------------------------------------------------------
+// ID utilities
+// ---------------------------------------------------------------------------
+
+const ALPHANUMERIC =
+  'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+
+/**
+ * Generate a random alphanumeric ID.
+ * Runtime-agnostic: uses `crypto.getRandomValues`.
+ */
+export const shortId = (length = 8): string => {
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  let id = '';
+  for (let i = 0; i < length; i += 1) {
+    const byte = bytes[i];
+    if (byte !== undefined) {
+      id += ALPHANUMERIC[byte % ALPHANUMERIC.length];
+    }
+  }
+  return id;
+};
+
+/**
+ * Produce a deterministic hex hash from an input string.
+ * Uses a simple FNV-1a 32-bit hash — good enough for non-cryptographic IDs.
+ */
+export const hashId = (input: string): string => {
+  // FNV offset basis
+  let hash = 2_166_136_261;
+  for (let i = 0; i < input.length; i += 1) {
+    // oxlint-disable-next-line no-bitwise -- FNV-1a hash requires XOR
+    hash ^= input.codePointAt(i) ?? 0;
+    // FNV prime
+    hash = Math.imul(hash, 0x01_00_01_93);
+  }
+  // Convert to unsigned 32-bit then hex
+  // oxlint-disable-next-line no-bitwise, prefer-math-trunc -- unsigned right shift needed for u32 conversion (Math.trunc differs semantically)
+  return (hash >>> 0).toString(16).padStart(8, '0');
+};

package/src/collections.ts

@@ -0,0 +1,99 @@
+/**
+ * Collection utilities and type helpers for @ontrails/core.
+ */
+
+// ---------------------------------------------------------------------------
+// Type utilities
+// ---------------------------------------------------------------------------
+
+/** Recursively make every property optional. */
+export type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+/** Flatten an intersection into a single object type for better IDE display. */
+// oxlint-disable-next-line ban-types -- `& {}` is a standard TypeScript idiom to force type expansion in IDE tooltips
+export type Prettify<T> = { [K in keyof T]: T[K] } & {};
+
+/** Require at least one property from T. */
+export type AtLeastOne<T> = {
+  [K in keyof T]-?: Pick<T, K> & Partial<Omit<T, K>>;
+}[keyof T];
+
+/** A tuple with at least one element. */
+export type NonEmptyArray<T> = [T, ...T[]];
+
+// ---------------------------------------------------------------------------
+// Guards
+// ---------------------------------------------------------------------------
+
+/** Narrows a readonly array to a NonEmptyArray. */
+export const isNonEmptyArray = <T>(
+  array: readonly T[]
+): array is NonEmptyArray<T> => array.length > 0;
+
+// ---------------------------------------------------------------------------
+// Collection functions
+// ---------------------------------------------------------------------------
+
+/** Split an array into chunks of at most `size` elements. */
+export const chunk = <T>(array: readonly T[], size: number): T[][] => {
+  if (size < 1) {
+    throw new RangeError('chunk size must be >= 1');
+  }
+  const result: T[][] = [];
+  for (let i = 0; i < array.length; i += size) {
+    result.push(array.slice(i, i + size));
+  }
+  return result;
+};
+
+/**
+ * Remove duplicate items. When `key` is provided, uniqueness is determined
+ * by the return value of the key function; otherwise strict equality is used.
+ */
+export const dedupe = <T>(
+  array: readonly T[],
+  key?: (item: T) => unknown
+): T[] => {
+  if (!key) {
+    return [...new Set(array)];
+  }
+  const seen = new Set<unknown>();
+  const result: T[] = [];
+  for (const item of array) {
+    const k = key(item);
+    if (!seen.has(k)) {
+      seen.add(k);
+      result.push(item);
+    }
+  }
+  return result;
+};
+
+/** Group items by a string key. */
+export const groupBy = <T>(
+  array: readonly T[],
+  key: (item: T) => string
+): Record<string, T[]> => {
+  const groups: Record<string, T[]> = {};
+  for (const item of array) {
+    const k = key(item);
+    (groups[k] ??= []).push(item);
+  }
+  return groups;
+};
+
+/** Return a new sorted array based on a key function (ascending). */
+export const sortBy = <T>(
+  array: readonly T[],
+  key: (item: T) => string | number
+): T[] =>
+  [...array].toSorted((a, b) => {
+    const ka = key(a);
+    const kb = key(b);
+    if (typeof ka === 'number' && typeof kb === 'number') {
+      return ka - kb;
+    }
+    return String(ka).localeCompare(String(kb));
+  });

package/src/context.ts

@@ -0,0 +1,18 @@
+import type { TrailContext } from './types.js';
+
+/**
+ * Create a TrailContext with sensible defaults.
+ *
+ * - `requestId` defaults to `Bun.randomUUIDv7()` (sortable v7 UUID)
+ * - `signal` defaults to a fresh, non-aborted `AbortSignal`
+ * - All other fields come from `overrides`
+ */
+export const createTrailContext = (
+  overrides?: Partial<TrailContext>
+): TrailContext => ({
+  cwd: process.cwd(),
+  env: process.env as Record<string, string | undefined>,
+  requestId: Bun.randomUUIDv7(),
+  signal: new AbortController().signal,
+  ...overrides,
+});

package/src/derive.ts

@@ -0,0 +1,223 @@
+/**
+ * Schema-driven field derivation for @ontrails/core
+ *
+ * Introspects Zod v4 schemas to produce a surface-agnostic Field[] descriptor
+ * that UI layers (CLI prompts, web forms, etc.) can consume.
+ */
+
+import type { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/** A surface-agnostic field descriptor derived from a Zod schema. */
+export interface Field {
+  readonly name: string;
+  readonly type: 'string' | 'number' | 'boolean' | 'enum' | 'multiselect';
+  readonly label: string;
+  readonly required: boolean;
+  readonly default?: unknown | undefined;
+  readonly options?:
+    | readonly {
+        value: string;
+        label?: string | undefined;
+        hint?: string | undefined;
+      }[]
+    | undefined;
+}
+
+/** Per-field overrides supplied by trail authors. */
+export interface FieldOverride {
+  readonly label?: string | undefined;
+  readonly message?: string | undefined;
+  readonly hint?: string | undefined;
+  readonly options?:
+    | readonly {
+        value: string;
+        label: string;
+        hint?: string | undefined;
+      }[]
+    | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Zod v4 internals accessor
+// ---------------------------------------------------------------------------
+
+interface ZodInternals {
+  readonly _zod: {
+    readonly def: Readonly<Record<string, unknown>>;
+    readonly traits: ReadonlySet<string>;
+  };
+  readonly description?: string | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Convert camelCase / PascalCase to "Title Case" label. */
+const humanize = (str: string): string =>
+  str
+    .replaceAll(/([a-z])([A-Z])/g, '$1 $2')
+    .replaceAll(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .replace(/^./, (ch) => ch.toUpperCase());
+
+interface UnwrapResult {
+  defaultValue: unknown;
+  description: string | undefined;
+  inner: ZodInternals;
+  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 inner to state if present. */
+const propagateDescription = (
+  inner: ZodInternals,
+  state: { description: string | undefined }
+): void => {
+  if (inner.description) {
+    state.description = inner.description;
+  }
+};
+
+/** Step one level of optional/default unwrapping. Returns null if not a wrapper type. */
+const unwrapStep = (
+  current: ZodInternals,
+  state: {
+    defaultValue: unknown;
+    description: string | undefined;
+    required: boolean;
+  }
+): 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 = (s: ZodInternals): UnwrapResult => {
+  const state = {
+    defaultValue: undefined as unknown,
+    description: s.description,
+    required: true,
+  };
+  let current = s;
+
+  // 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 DerivedFieldType {
+  options: string[] | undefined;
+  type: Field['type'];
+}
+
+const fieldTypeByDef: Record<string, (s: ZodInternals) => DerivedFieldType> = {
+  array: (s) => {
+    const element = s._zod.def['element'] as unknown as ZodInternals;
+    const elementType = element._zod.def['type'] as string;
+    if (elementType === 'enum') {
+      const entries = element._zod.def['entries'] as Record<string, string>;
+      return { options: Object.values(entries), type: 'multiselect' };
+    }
+    return { options: undefined, type: 'string' };
+  },
+  boolean: () => ({ options: undefined, type: 'boolean' }),
+  enum: (s) => {
+    const entries = s._zod.def['entries'] as Record<string, string>;
+    return { options: Object.values(entries), type: 'enum' };
+  },
+  number: () => ({ options: undefined, type: 'number' }),
+  string: () => ({ options: undefined, type: 'string' }),
+};
+
+/** Derive field type and raw options from the unwrapped Zod def. */
+const deriveFieldType = (s: ZodInternals): DerivedFieldType => {
+  const defType = s._zod.def['type'] as string;
+  const derive = fieldTypeByDef[defType];
+  return derive ? derive(s) : { options: undefined, type: 'string' };
+};
+
+/** Build options array, merging with overrides when present. */
+const buildOptions = (
+  rawOptions: string[] | undefined,
+  overrideOptions: FieldOverride['options'] | undefined
+): Field['options'] | undefined => {
+  if (!rawOptions) {
+    return undefined;
+  }
+
+  if (!overrideOptions) {
+    return rawOptions.map((v) => ({ value: v }));
+  }
+
+  const overrideMap = new Map(overrideOptions.map((o) => [o.value, o]));
+  return rawOptions.map((v) => {
+    const ov = overrideMap.get(v);
+    return ov ? { hint: ov.hint, label: ov.label, value: v } : { value: v };
+  });
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive a surface-agnostic Field[] from a Zod object schema.
+ *
+ * Uses Zod v4's `_zod.def` for introspection. Returns fields sorted by name.
+ */
+/** Derive a single field from a shape entry. */
+const deriveField = (
+  key: string,
+  value: ZodInternals,
+  overrides?: Record<string, FieldOverride>
+): Field => {
+  const { inner, required, defaultValue, description } = unwrap(value);
+  const { type, options: rawOptions } = deriveFieldType(inner);
+  const override = overrides?.[key];
+  const label = override?.label ?? description ?? humanize(key);
+  const options = buildOptions(rawOptions, override?.options);
+  return { default: defaultValue, label, name: key, options, required, type };
+};
+
+export const deriveFields = (
+  schema: z.ZodType,
+  overrides?: Record<string, FieldOverride>
+): Field[] => {
+  const s = schema as unknown as ZodInternals;
+  if ((s._zod.def['type'] as string) !== 'object') {
+    return [];
+  }
+
+  const shape = s._zod.def['shape'] as Record<string, ZodInternals> | undefined;
+  if (!shape) {
+    return [];
+  }
+
+  const fields = Object.entries(shape).map(([key, value]) =>
+    deriveField(key, value, overrides)
+  );
+  return fields.toSorted((a, b) => a.name.localeCompare(b.name));
+};