@ontrails/core 1.0.0-beta.2 → 1.0.0-beta.21

package/src/version-resolution.ts

@@ -0,0 +1,308 @@
+import {
+  AmbiguousError,
+  TrailsError,
+  ValidationError,
+  VersionNotSupportedError,
+} from './errors.js';
+import { Result } from './result.js';
+import {
+  deriveSupportedTrailVersions,
+  getTrailVersionEntryKind,
+  isArchivedTrailVersionEntry,
+} from './trail.js';
+import type {
+  AnyTrail,
+  TrailVersionForkEntry,
+  TrailVersionRevisionEntry,
+} from './trail.js';
+import {
+  TRAIL_VERSION_MARKER_LENGTH,
+  TRAIL_VERSION_MARKER_MIN_PREFIX_LENGTH,
+  deriveTrailVersionMarkers,
+} from './version-marker.js';
+
+export type TrailVersionReference = number | string;
+
+export interface ParsedTrailVersionReference {
+  readonly id: string;
+  readonly version?: TrailVersionReference | undefined;
+}
+
+export type ResolvedTrailVersion =
+  | {
+      readonly current: true;
+      readonly kind: 'current';
+      readonly marker?: string | undefined;
+      readonly version?: number | undefined;
+    }
+  | {
+      readonly current: false;
+      readonly deprecated: boolean;
+      readonly entry: TrailVersionForkEntry;
+      readonly kind: 'fork';
+      readonly marker?: string | undefined;
+      readonly version: number;
+    }
+  | {
+      readonly current: false;
+      readonly deprecated: boolean;
+      readonly entry: TrailVersionRevisionEntry;
+      readonly kind: 'revision';
+      readonly marker?: string | undefined;
+      readonly version: number;
+    };
+
+interface ParsedVersionReference {
+  readonly display: number | string;
+  readonly markerPrefix?: string | undefined;
+  readonly number?: number | undefined;
+}
+
+type MarkerResolvableTrail = Pick<
+  AnyTrail,
+  | 'composes'
+  | 'detours'
+  | 'id'
+  | 'input'
+  | 'output'
+  | 'resources'
+  | 'version'
+  | 'versions'
+>;
+
+const versionRefPattern = /^(.+)@(.+)$/;
+const positiveIntegerPattern = /^[1-9]\d*$/;
+const markerPrefixPattern = /^[0-9a-fA-F]+$/;
+
+const parsePositiveInteger = (value: string): number | undefined => {
+  if (!positiveIntegerPattern.test(value)) {
+    return undefined;
+  }
+  const version = Number(value);
+  return Number.isSafeInteger(version) ? version : undefined;
+};
+
+const isInlineVersionReference = (value: string): boolean =>
+  parsePositiveInteger(value) !== undefined ||
+  (value.length >= TRAIL_VERSION_MARKER_MIN_PREFIX_LENGTH &&
+    value.length <= TRAIL_VERSION_MARKER_LENGTH &&
+    markerPrefixPattern.test(value));
+
+const unsupportedVersion = (
+  trail: Pick<AnyTrail, 'id' | 'version' | 'versions'>,
+  requested: number | string,
+  reason: string
+): VersionNotSupportedError => {
+  const supported = deriveSupportedTrailVersions(trail);
+  return new VersionNotSupportedError(trail.id, requested, supported, reason);
+};
+
+export const parseTrailIdVersionReference = (
+  id: string
+): Result<ParsedTrailVersionReference, ValidationError> => {
+  const match = versionRefPattern.exec(id);
+  if (match === null) {
+    return Result.ok({ id });
+  }
+
+  const [, baseId, rawVersion] = match;
+  if (baseId === undefined || rawVersion === undefined) {
+    return Result.err(
+      new ValidationError(
+        'Trail version reference must use trail.id@N or trail.id@<marker-prefix>'
+      )
+    );
+  }
+  if (!isInlineVersionReference(rawVersion)) {
+    return Result.ok({ id });
+  }
+
+  return Result.ok({ id: baseId, version: rawVersion });
+};
+
+const parseVersionReference = (
+  reference: TrailVersionReference
+): Result<ParsedVersionReference, Error> => {
+  if (typeof reference === 'number') {
+    return Number.isSafeInteger(reference) && reference > 0
+      ? Result.ok({ display: reference, number: reference })
+      : Result.err(
+          new ValidationError(
+            'Trail version reference must be a positive integer'
+          )
+        );
+  }
+
+  const markerRequested = reference.startsWith('@');
+  const raw = markerRequested ? reference.slice(1) : reference;
+  if (raw.length === 0) {
+    return Result.err(
+      new ValidationError('Trail version reference must not be empty')
+    );
+  }
+
+  const number = parsePositiveInteger(raw);
+  if (!markerRequested && number !== undefined) {
+    return Result.ok({
+      display: reference,
+      markerPrefix:
+        raw.length >= TRAIL_VERSION_MARKER_MIN_PREFIX_LENGTH &&
+        raw.length <= TRAIL_VERSION_MARKER_LENGTH &&
+        markerPrefixPattern.test(raw)
+          ? raw.toLowerCase()
+          : undefined,
+      number,
+    });
+  }
+
+  if (
+    raw.length >= TRAIL_VERSION_MARKER_MIN_PREFIX_LENGTH &&
+    raw.length <= TRAIL_VERSION_MARKER_LENGTH &&
+    markerPrefixPattern.test(raw)
+  ) {
+    return Result.ok({
+      display: reference,
+      markerPrefix: raw.toLowerCase(),
+    });
+  }
+
+  return Result.err(
+    new ValidationError(
+      'Trail version reference must be a positive integer or marker prefix'
+    )
+  );
+};
+
+const trailHasVersion = (
+  trail: Pick<AnyTrail, 'version' | 'versions'>,
+  version: number
+): boolean =>
+  trail.version === version || trail.versions?.[version] !== undefined;
+
+const resolveMarkerReference = (
+  trail: MarkerResolvableTrail,
+  requested: number | string,
+  prefix: string
+): Result<{ readonly marker: string; readonly version: number }, Error> => {
+  let records: ReturnType<typeof deriveTrailVersionMarkers>;
+  try {
+    records = deriveTrailVersionMarkers(trail);
+  } catch (error: unknown) {
+    return Result.err(
+      error instanceof TrailsError
+        ? error
+        : new ValidationError(
+            `Trail version marker derivation failed: ${String(error)}`
+          )
+    );
+  }
+  const matches = records.filter((record) => record.marker.startsWith(prefix));
+
+  if (matches.length === 0) {
+    return Result.err(unsupportedVersion(trail, requested, 'marker missing'));
+  }
+  if (matches.length > 1) {
+    return Result.err(
+      new AmbiguousError(
+        `Trail version marker prefix ${prefix} is ambiguous across versions ${matches.map((record) => record.version).join(', ')}`
+      )
+    );
+  }
+
+  const match = matches[0] as (typeof matches)[number];
+
+  return Result.ok({ marker: match.marker, version: match.version });
+};
+
+const resolveRequestedVersionNumber = (
+  trail: MarkerResolvableTrail,
+  reference: TrailVersionReference
+): Result<
+  { readonly marker?: string | undefined; readonly version: number },
+  Error
+> => {
+  const parsed = parseVersionReference(reference);
+  if (parsed.isErr()) {
+    return parsed;
+  }
+
+  const { display, markerPrefix, number } = parsed.value;
+  if (number !== undefined && trailHasVersion(trail, number)) {
+    return Result.ok({ version: number });
+  }
+
+  if (markerPrefix !== undefined) {
+    const marker = resolveMarkerReference(trail, display, markerPrefix);
+    if (marker.isOk()) {
+      return marker;
+    }
+    if (number === undefined) {
+      return marker;
+    }
+  }
+
+  return Result.err(unsupportedVersion(trail, display, 'missing'));
+};
+
+export const resolveTrailVersion = (
+  trail: MarkerResolvableTrail,
+  reference?: TrailVersionReference | undefined
+): Result<ResolvedTrailVersion, Error> => {
+  if (reference === undefined) {
+    return Result.ok({
+      current: true,
+      kind: 'current',
+      ...(trail.version === undefined ? {} : { version: trail.version }),
+    });
+  }
+
+  if (trail.version === undefined) {
+    return Result.err(unsupportedVersion(trail, reference, 'unversioned'));
+  }
+
+  const requested = resolveRequestedVersionNumber(trail, reference);
+  if (requested.isErr()) {
+    return requested;
+  }
+
+  if (requested.value.version === trail.version) {
+    return Result.ok({
+      current: true,
+      kind: 'current',
+      ...(requested.value.marker === undefined
+        ? {}
+        : { marker: requested.value.marker }),
+      version: trail.version,
+    });
+  }
+
+  const entry = trail.versions?.[requested.value.version];
+  if (entry === undefined) {
+    return Result.err(unsupportedVersion(trail, reference, 'missing'));
+  }
+  if (isArchivedTrailVersionEntry(entry)) {
+    return Result.err(unsupportedVersion(trail, reference, 'archived'));
+  }
+
+  const kind = getTrailVersionEntryKind(entry);
+  const base = {
+    current: false,
+    deprecated: entry.status?.state === 'deprecated',
+    ...(requested.value.marker === undefined
+      ? {}
+      : { marker: requested.value.marker }),
+    version: requested.value.version,
+  } as const;
+
+  return kind === 'fork'
+    ? Result.ok({
+        ...base,
+        entry: entry as TrailVersionForkEntry,
+        kind,
+      })
+    : Result.ok({
+        ...base,
+        entry: entry as TrailVersionRevisionEntry,
+        kind,
+      });
+};

package/src/version-runtime.ts

@@ -0,0 +1,120 @@
+import { InternalError, ValidationError } from './errors.js';
+import { Result } from './result.js';
+import type { ExecuteTrailOptions } from './execute.js';
+import { getTrailVersionEntryKind } from './trail.js';
+import type { AnyTrail, TrailVersionEntry } from './trail.js';
+import { validateInput, validateOutput } from './validation.js';
+
+export type TrailVersionCurrentExecutor<
+  Options extends ExecuteTrailOptions = ExecuteTrailOptions,
+> = (
+  trail: AnyTrail,
+  input: unknown,
+  options?: Options
+) => Promise<Result<unknown, Error>>;
+
+const normalizeTransposeError = (
+  trail: AnyTrail,
+  version: number,
+  phase: 'input' | 'output',
+  error: unknown
+): InternalError => {
+  const message = error instanceof Error ? error.message : String(error);
+  const options: { cause?: Error; context: Record<string, unknown> } = {
+    context: { phase, trailId: trail.id, version },
+  };
+  if (error instanceof Error) {
+    options.cause = error;
+  }
+  return new InternalError(
+    `Trail "${trail.id}" version ${version} transpose.${phase} failed: ${message}`,
+    options
+  );
+};
+
+const runTransposeInput = async (
+  trail: AnyTrail,
+  version: number,
+  entry: TrailVersionEntry,
+  input: unknown
+): Promise<Result<unknown, Error>> => {
+  if (entry.transpose === undefined) {
+    return Result.ok(input);
+  }
+
+  try {
+    return Result.ok(await entry.transpose.input({ input }));
+  } catch (error: unknown) {
+    return Result.err(normalizeTransposeError(trail, version, 'input', error));
+  }
+};
+
+const runTransposeOutput = async (
+  trail: AnyTrail,
+  version: number,
+  entry: TrailVersionEntry,
+  output: unknown
+): Promise<Result<unknown, Error>> => {
+  if (entry.transpose === undefined) {
+    return Result.ok(output);
+  }
+
+  try {
+    return Result.ok(await entry.transpose.output({ output }));
+  } catch (error: unknown) {
+    return Result.err(normalizeTransposeError(trail, version, 'output', error));
+  }
+};
+
+export const executeTrailRevision = async <
+  Options extends ExecuteTrailOptions = ExecuteTrailOptions,
+>(
+  trail: AnyTrail,
+  version: number,
+  entry: TrailVersionEntry,
+  rawInput: unknown,
+  options: Options | undefined,
+  executeCurrentTrail: TrailVersionCurrentExecutor<Options>
+): Promise<Result<unknown, Error>> => {
+  if (getTrailVersionEntryKind(entry) !== 'revision') {
+    return Result.err(
+      new ValidationError(
+        `Trail "${trail.id}" version ${version} is not a revision entry`
+      )
+    );
+  }
+
+  const historicalInput = validateInput(entry.input, rawInput);
+  if (historicalInput.isErr()) {
+    return historicalInput;
+  }
+
+  const currentInput = await runTransposeInput(
+    trail,
+    version,
+    entry,
+    historicalInput.value
+  );
+  if (currentInput.isErr()) {
+    return currentInput;
+  }
+
+  const currentOutput = await executeCurrentTrail(
+    trail,
+    currentInput.value,
+    options
+  );
+  if (currentOutput.isErr()) {
+    return currentOutput;
+  }
+
+  const historicalOutput = await runTransposeOutput(
+    trail,
+    version,
+    entry,
+    currentOutput.value
+  );
+  return historicalOutput.isErr()
+    ? historicalOutput
+    : validateOutput(entry.output, historicalOutput.value);
+};

package/src/webhook.ts

@@ -0,0 +1,278 @@
+import type {
+  ActivationSource,
+  ActivationSourceMeta,
+  ActivationSourceParse,
+} from './activation-source.js';
+import { InternalError, ValidationError } from './errors.js';
+import { Result } from './result.js';
+
+export const webhookMethods = Object.freeze([
+  'DELETE',
+  'GET',
+  'PATCH',
+  'POST',
+  'PUT',
+] as const);
+
+export type WebhookMethod = (typeof webhookMethods)[number];
+export type WebhookMethodInput = WebhookMethod | Lowercase<WebhookMethod>;
+
+export type WebhookVerifyHeaders = Readonly<
+  Record<string, readonly string[] | string | undefined>
+>;
+
+export interface WebhookVerifyRequest {
+  readonly body: ArrayBuffer | Uint8Array | string;
+  readonly headers: WebhookVerifyHeaders;
+  readonly method: string;
+  readonly path: string;
+}
+
+export type WebhookVerify = (
+  request: WebhookVerifyRequest
+) => Promise<Result<void, Error>> | Result<void, Error>;
+
+export interface WebhookSpec<TOutput = unknown> {
+  readonly meta?: ActivationSourceMeta | undefined;
+  readonly method?: WebhookMethodInput | undefined;
+  readonly parse: ActivationSourceParse<TOutput>;
+  readonly path: string;
+  readonly payload?: ActivationSource['payload'] | undefined;
+  readonly verify?: WebhookVerify | undefined;
+  /** Reserved for future webhook-specific design; trail versioning is trail-only. */
+  readonly version?: never;
+}
+
+export interface WebhookSource<TOutput = unknown> extends ActivationSource {
+  readonly kind: 'webhook';
+  readonly meta?: ActivationSourceMeta | undefined;
+  readonly method: WebhookMethod;
+  readonly parse: ActivationSourceParse<TOutput>;
+  readonly path: string;
+  readonly payload?: ActivationSource['payload'] | undefined;
+  readonly verify?: WebhookVerify | undefined;
+}
+
+export interface WebhookValidationIssue {
+  readonly field: 'method' | 'parse' | 'path' | 'verify';
+  readonly message: string;
+}
+
+const DEFAULT_WEBHOOK_METHOD = 'POST' as const;
+
+const normalizeMethod = (
+  method: WebhookMethodInput | string | undefined
+): string => (method ?? DEFAULT_WEBHOOK_METHOD).trim().toUpperCase();
+
+const normalizePath = (path: string): string => path.trim();
+
+const isWebhookMethod = (method: string): method is WebhookMethod =>
+  (webhookMethods as readonly string[]).includes(method);
+
+const isObjectRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const isZodSchema = (value: unknown): boolean =>
+  isObjectRecord(value) && typeof value['safeParse'] === 'function';
+
+const validateMethod = (
+  method: WebhookMethodInput | string | undefined
+): WebhookValidationIssue[] => {
+  const normalized = normalizeMethod(method);
+  return isWebhookMethod(normalized)
+    ? []
+    : [
+        {
+          field: 'method',
+          message: `Webhook method must be one of ${webhookMethods.join(', ')}`,
+        },
+      ];
+};
+
+const validatePath = (path: unknown): WebhookValidationIssue[] => {
+  if (typeof path !== 'string' || path.trim().length === 0) {
+    return [
+      {
+        field: 'path',
+        message: 'Webhook path must be a non-empty absolute path',
+      },
+    ];
+  }
+
+  const normalized = normalizePath(path);
+  return normalized.startsWith('/')
+    ? []
+    : [
+        {
+          field: 'path',
+          message: 'Webhook path must start with "/"',
+        },
+      ];
+};
+
+const validateRequiredParse = (parse: unknown): WebhookValidationIssue[] =>
+  parse === undefined
+    ? [
+        {
+          field: 'parse',
+          message: 'Webhook sources must define parse',
+        },
+      ]
+    : [];
+
+const validateParseShape = (parse: unknown): WebhookValidationIssue[] => {
+  if (parse === undefined || isZodSchema(parse)) {
+    return [];
+  }
+  if (isObjectRecord(parse) && isZodSchema(parse['output'])) {
+    return [];
+  }
+  return [
+    {
+      field: 'parse',
+      message: 'Webhook parse must be a Zod schema or define parse.output',
+    },
+  ];
+};
+
+const validateVerify = (verify: unknown): WebhookValidationIssue[] =>
+  verify === undefined || typeof verify === 'function'
+    ? []
+    : [
+        {
+          field: 'verify',
+          message: 'Webhook verify must be a function when provided',
+        },
+      ];
+
+const webhookIssuesMessage = (
+  id: string,
+  issues: readonly WebhookValidationIssue[]
+): string =>
+  `webhook("${id}") is invalid: ${issues.map((issue) => `${issue.field}: ${issue.message}`).join('; ')}`;
+
+const assertWebhookSpec = <TOutput>(
+  id: string,
+  spec: WebhookSpec<TOutput>
+): {
+  readonly method: WebhookMethod;
+  readonly path: string;
+} => {
+  const issues = [
+    ...validateMethod(spec.method),
+    ...validatePath(spec.path),
+    ...validateRequiredParse(spec.parse),
+    ...validateParseShape(spec.parse),
+    ...validateVerify(spec.verify),
+  ];
+
+  if (issues.length > 0) {
+    throw new ValidationError(webhookIssuesMessage(id, issues), {
+      context: { issues },
+    });
+  }
+
+  return {
+    method: normalizeMethod(spec.method) as WebhookMethod,
+    path: normalizePath(spec.path),
+  };
+};
+
+export const validateWebhookSource = (
+  source: ActivationSource
+): readonly WebhookValidationIssue[] => {
+  if (source.kind !== 'webhook') {
+    return [];
+  }
+
+  return [
+    ...validateMethod(source.method),
+    ...validatePath(source.path),
+    ...validateRequiredParse(source.parse),
+    ...validateParseShape(source.parse),
+    ...validateVerify(source.verify),
+  ];
+};
+
+const errorFromUnknown = (error: unknown): Error =>
+  error instanceof Error ? error : new Error(String(error));
+
+export const getWebhookHeaders = (
+  request: Pick<WebhookVerifyRequest, 'headers'>,
+  name: string
+): readonly string[] => {
+  const normalized = name.toLowerCase();
+  const matches: string[] = [];
+  for (const [headerName, value] of Object.entries(request.headers)) {
+    if (headerName.toLowerCase() !== normalized) {
+      continue;
+    }
+    if (value === undefined) {
+      continue;
+    }
+    if (typeof value === 'string') {
+      matches.push(value);
+    } else {
+      matches.push(...value);
+    }
+  }
+  return matches;
+};
+
+export const getWebhookHeader = (
+  request: Pick<WebhookVerifyRequest, 'headers'>,
+  name: string
+): string | undefined => {
+  const [first] = getWebhookHeaders(request, name);
+  return first;
+};
+
+export const verifyWebhookRequest = async (
+  source: Pick<WebhookSource, 'id' | 'verify'>,
+  request: WebhookVerifyRequest
+): Promise<Result<void, Error>> => {
+  if (source.verify === undefined) {
+    return Result.ok();
+  }
+
+  try {
+    return await source.verify(request);
+  } catch (error) {
+    const cause = errorFromUnknown(error);
+    return Result.err(
+      new InternalError(`Webhook source "${source.id}" verification threw`, {
+        cause,
+      })
+    );
+  }
+};
+
+export function webhook<TOutput>(
+  id: string,
+  spec: WebhookSpec<TOutput>
+): WebhookSource<TOutput>;
+export function webhook<TOutput>(
+  spec: WebhookSpec<TOutput> & { readonly id: string }
+): WebhookSource<TOutput>;
+export function webhook<TOutput>(
+  idOrSpec: string | (WebhookSpec<TOutput> & { readonly id: string }),
+  maybeSpec?: WebhookSpec<TOutput>
+): WebhookSource<TOutput> {
+  const id = typeof idOrSpec === 'string' ? idOrSpec : idOrSpec.id;
+  // oxlint-disable-next-line no-non-null-assertion -- overload guarantees maybeSpec when idOrSpec is string
+  const spec = typeof idOrSpec === 'string' ? maybeSpec! : idOrSpec;
+  const normalized = assertWebhookSpec(id, spec);
+
+  return Object.freeze({
+    id,
+    kind: 'webhook' as const,
+    method: normalized.method,
+    parse: spec.parse,
+    path: normalized.path,
+    ...(spec.meta === undefined
+      ? {}
+      : { meta: Object.freeze({ ...spec.meta }) }),
+    ...(spec.payload === undefined ? {} : { payload: spec.payload }),
+    ...(spec.verify === undefined ? {} : { verify: spec.verify }),
+  });
+}

package/src/workspace.ts

@@ -71,7 +71,7 @@ export const isInsideWorkspace = (
 /**
  * Returns the relative path from `workspaceRoot` to `filePath`.
  */
-export const getRelativePath = (
+export const deriveRelativePath = (
   filePath: string,
   workspaceRoot: string
 ): string => relative(resolve(workspaceRoot), resolve(filePath));