@ontrails/core 1.0.0-beta.30 → 1.0.0-beta.39

package/src/webhook.ts

@@ -4,7 +4,9 @@ import type {
   ActivationSourceParse,
 } from './activation-source.js';
 import { InternalError, ValidationError } from './errors.js';
+import type { AnyResource } from './resource.js';
 import { Result } from './result.js';
+import type { TrailContext } from './types.js';
 
 export const webhookMethods = Object.freeze([
   'DELETE',
@@ -28,16 +30,46 @@ export interface WebhookVerifyRequest {
   readonly path: string;
 }
 
+/**
+ * Verification callback for inbound webhook requests.
+ *
+ * When the source declares `resources`, surfaces call `verify` with a
+ * resource-capable context so signature checks can reach declared
+ * resources (e.g. a store holding per-endpoint secrets). Verifiers that
+ * only need the request may ignore the second parameter.
+ */
 export type WebhookVerify = (
-  request: WebhookVerifyRequest
+  request: WebhookVerifyRequest,
+  ctx?: TrailContext
 ) => Promise<Result<void, Error>> | Result<void, Error>;
 
 export interface WebhookSpec<TOutput = unknown> {
+  /**
+   * Allowlist of header names delivered to the consumer trail. When set,
+   * the webhook envelope includes a `headers` map with the matching
+   * headers, lowercased. Headers outside the allowlist never reach the
+   * trail boundary.
+   */
+  readonly headers?: readonly string[] | undefined;
   readonly meta?: ActivationSourceMeta | undefined;
   readonly method?: WebhookMethodInput | undefined;
   readonly parse: ActivationSourceParse<TOutput>;
+  /**
+   * Absolute path, optionally with dynamic segments (`/hooks/:endpoint`).
+   * Segment values are delivered as fields of the webhook envelope under
+   * their segment names.
+   */
   readonly path: string;
   readonly payload?: ActivationSource['payload'] | undefined;
+  /**
+   * Deliver the raw request body text to the consumer trail as a
+   * `rawBody` envelope field. With `rawBody`, a non-JSON body no longer
+   * fails at the surface — the trail owns payload interpretation (e.g.
+   * HMAC verification over exact bytes).
+   */
+  readonly rawBody?: boolean | undefined;
+  /** Resources the `verify` callback may access through its context. */
+  readonly resources?: readonly AnyResource[] | undefined;
   readonly verify?: WebhookVerify | undefined;
   /** Reserved for future webhook-specific design; trail versioning is trail-only. */
   readonly version?: never;
@@ -45,11 +77,16 @@ export interface WebhookSpec<TOutput = unknown> {
 
 export interface WebhookSource<TOutput = unknown> extends ActivationSource {
   readonly kind: 'webhook';
+  readonly headers?: readonly string[] | undefined;
   readonly meta?: ActivationSourceMeta | undefined;
   readonly method: WebhookMethod;
   readonly parse: ActivationSourceParse<TOutput>;
   readonly path: string;
+  /** Dynamic segment names parsed from `path`, in order. Empty for static paths. */
+  readonly pathParams: readonly string[];
   readonly payload?: ActivationSource['payload'] | undefined;
+  readonly rawBody?: boolean | undefined;
+  readonly resources?: readonly AnyResource[] | undefined;
   readonly verify?: WebhookVerify | undefined;
 }
 
@@ -66,6 +103,111 @@ const normalizeMethod = (
 
 const normalizePath = (path: string): string => path.trim();
 
+const WEBHOOK_PATH_PARAM_PATTERN = /^:[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** Envelope field names a path segment must not shadow. */
+const RESERVED_ENVELOPE_FIELDS = new Set(['body', 'headers', 'rawBody']);
+
+const pathSegments = (path: string): readonly string[] =>
+  normalizePath(path).split('/').slice(1);
+
+const isParamSegment = (segment: string): boolean => segment.startsWith(':');
+
+/** Decode a path segment, keeping the raw text when the encoding is malformed. */
+const decodeSegment = (segment: string): string => {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+};
+
+/**
+ * Parse the dynamic segment names out of a webhook path pattern.
+ *
+ * @example
+ * ```ts
+ * parseWebhookPathParams('/hooks/:endpoint'); // ['endpoint']
+ * parseWebhookPathParams('/webhooks/payment'); // []
+ * ```
+ */
+export const parseWebhookPathParams = (path: string): readonly string[] =>
+  pathSegments(path)
+    .filter((segment) => isParamSegment(segment))
+    .map((segment) => segment.slice(1));
+
+/**
+ * Match a concrete request path against a webhook path pattern.
+ *
+ * Returns the captured segment values keyed by segment name, or
+ * `undefined` when the path does not match. Static patterns match only
+ * themselves and capture nothing.
+ *
+ * @example
+ * ```ts
+ * matchWebhookPath('/hooks/:endpoint', '/hooks/github');
+ * // { endpoint: 'github' }
+ * ```
+ */
+export const matchWebhookPath = (
+  pattern: string,
+  path: string
+): Readonly<Record<string, string>> | undefined => {
+  const patternSegments = pathSegments(pattern);
+  const actualSegments = path.split('/').slice(1);
+  if (patternSegments.length !== actualSegments.length) {
+    return undefined;
+  }
+
+  const params: Record<string, string> = {};
+  for (const [index, patternSegment] of patternSegments.entries()) {
+    const actual = actualSegments[index] ?? '';
+    if (isParamSegment(patternSegment)) {
+      if (actual.length === 0) {
+        return undefined;
+      }
+      params[patternSegment.slice(1)] = decodeSegment(actual);
+      continue;
+    }
+    if (patternSegment !== actual) {
+      return undefined;
+    }
+  }
+  return params;
+};
+
+/**
+ * True when two webhook path patterns can both match one concrete path.
+ *
+ * Segment-wise: two literals overlap only when equal; a dynamic segment
+ * overlaps anything. Used by governance to extend route-collision
+ * detection past exact-path equality.
+ *
+ * @example
+ * ```ts
+ * webhookPathPatternsOverlap('/hooks/:a', '/hooks/github'); // true
+ * webhookPathPatternsOverlap('/hooks/:a', '/api/:b'); // false
+ * ```
+ */
+export const webhookPathPatternsOverlap = (
+  left: string,
+  right: string
+): boolean => {
+  const leftSegments = pathSegments(left);
+  const rightSegments = pathSegments(right);
+  if (leftSegments.length !== rightSegments.length) {
+    return false;
+  }
+  return leftSegments.every((leftSegment, index) => {
+    const rightSegment = rightSegments[index] ?? '';
+    return (
+      isParamSegment(leftSegment) ||
+      isParamSegment(rightSegment) ||
+      leftSegment === rightSegment
+    );
+  });
+};
+
 const isWebhookMethod = (method: string): method is WebhookMethod =>
   (webhookMethods as readonly string[]).includes(method);
 
@@ -100,14 +242,42 @@ const validatePath = (path: unknown): WebhookValidationIssue[] => {
   }
 
   const normalized = normalizePath(path);
-  return normalized.startsWith('/')
-    ? []
-    : [
-        {
-          field: 'path',
-          message: 'Webhook path must start with "/"',
-        },
-      ];
+  if (!normalized.startsWith('/')) {
+    return [
+      {
+        field: 'path',
+        message: 'Webhook path must start with "/"',
+      },
+    ];
+  }
+
+  const issues: WebhookValidationIssue[] = [];
+  for (const segment of pathSegments(normalized)) {
+    if (isParamSegment(segment) && !WEBHOOK_PATH_PARAM_PATTERN.test(segment)) {
+      issues.push({
+        field: 'path',
+        message: `Webhook path segment "${segment}" must match :name with a letter or underscore first`,
+      });
+    }
+  }
+
+  const params = parseWebhookPathParams(normalized);
+  if (new Set(params).size !== params.length) {
+    issues.push({
+      field: 'path',
+      message: 'Webhook path segments must use unique names',
+    });
+  }
+  for (const param of params) {
+    if (RESERVED_ENVELOPE_FIELDS.has(param)) {
+      issues.push({
+        field: 'path',
+        message: `Webhook path segment ":${param}" collides with the reserved envelope field "${param}"`,
+      });
+    }
+  }
+
+  return issues;
 };
 
 const validateRequiredParse = (parse: unknown): WebhookValidationIssue[] =>
@@ -229,14 +399,15 @@ export const getWebhookHeader = (
 
 export const verifyWebhookRequest = async (
   source: Pick<WebhookSource, 'id' | 'verify'>,
-  request: WebhookVerifyRequest
+  request: WebhookVerifyRequest,
+  ctx?: TrailContext
 ): Promise<Result<void, Error>> => {
   if (source.verify === undefined) {
     return Result.ok();
   }
 
   try {
-    return await source.verify(request);
+    return await source.verify(request, ctx);
   } catch (error) {
     const cause = errorFromUnknown(error);
     return Result.err(
@@ -269,10 +440,22 @@ export function webhook<TOutput>(
     method: normalized.method,
     parse: spec.parse,
     path: normalized.path,
+    pathParams: Object.freeze([...parseWebhookPathParams(normalized.path)]),
+    ...(spec.headers === undefined
+      ? {}
+      : {
+          headers: Object.freeze(
+            spec.headers.map((name) => name.toLowerCase())
+          ),
+        }),
     ...(spec.meta === undefined
       ? {}
       : { meta: Object.freeze({ ...spec.meta }) }),
     ...(spec.payload === undefined ? {} : { payload: spec.payload }),
+    ...(spec.rawBody === undefined ? {} : { rawBody: spec.rawBody }),
+    ...(spec.resources === undefined
+      ? {}
+      : { resources: Object.freeze([...spec.resources]) }),
     ...(spec.verify === undefined ? {} : { verify: spec.verify }),
   });
 }

package/src/workspace.ts

@@ -5,26 +5,189 @@
  * helpers for working with paths relative to a workspace.
  */
 
-import { resolve, relative, dirname, join, isAbsolute } from 'node:path';
-
 import { NotFoundError } from './errors.js';
 import { Result } from './result.js';
+// Workspace discovery is a tooling path: the node builtins load lazily at
+// first use so the core barrel's module graph stays execution-portable on
+// runtimes without node: builtins (TRL-1198).
+import { loadRuntimeBuiltin } from './runtime-builtins.js';
 
-/** Check if a directory has a package.json with a `workspaces` field. */
-const hasWorkspacesField = async (dir: string): Promise<boolean> => {
-  const pkgPath = join(dir, 'package.json');
-  const file = Bun.file(pkgPath);
-  if (!(await file.exists())) {
-    return false;
+const fs = () => loadRuntimeBuiltin('node:fs');
+const nodePath = () => loadRuntimeBuiltin('node:path');
+
+export interface WorkspaceRootManifest {
+  readonly workspaces?: unknown;
+}
+
+export interface WorkspacePackage<
+  Manifest extends object = Record<string, unknown>,
+> {
+  readonly manifest: Manifest;
+  readonly packageJsonPath: string;
+  readonly packageRoot: string;
+  readonly workspacePath: string;
+}
+
+const isRecord = (value: unknown): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const normalizePath = (path: string): string => path.replaceAll('\\', '/');
+
+const normalizeRealPath = (path: string): string => {
+  try {
+    return normalizePath(fs().realpathSync(path));
+  } catch {
+    return normalizePath(nodePath().resolve(path));
   }
+};
+
+const readJsonSync = <T>(path: string): T | undefined => {
   try {
-    const pkg: unknown = await file.json();
-    return typeof pkg === 'object' && pkg !== null && 'workspaces' in pkg;
+    return JSON.parse(fs().readFileSync(path, 'utf8')) as T;
   } catch {
-    return false;
+    return undefined;
+  }
+};
+
+/** Check if a directory has a package.json with a `workspaces` field. */
+const hasWorkspacesField = (dir: string): boolean => {
+  const pkg = readJsonSync<unknown>(nodePath().join(dir, 'package.json'));
+  return typeof pkg === 'object' && pkg !== null && 'workspaces' in pkg;
+};
+
+/**
+ * List workspace patterns from a root package manifest.
+ *
+ * Supports npm/Bun's array form and Yarn-style `{ packages: [] }` form.
+ *
+ * @example
+ * ```ts
+ * listWorkspacePatterns({ workspaces: ['packages/*'] });
+ * ```
+ */
+export const listWorkspacePatterns = (
+  manifest: WorkspaceRootManifest | undefined
+): readonly string[] => {
+  const { workspaces } = manifest ?? {};
+  if (Array.isArray(workspaces)) {
+    return workspaces.filter(
+      (pattern): pattern is string => typeof pattern === 'string'
+    );
+  }
+
+  const packages = isRecord(workspaces) ? workspaces['packages'] : undefined;
+  return Array.isArray(packages)
+    ? packages.filter(
+        (pattern): pattern is string => typeof pattern === 'string'
+      )
+    : [];
+};
+
+const workspaceDirsForPattern = (
+  rootDir: string,
+  pattern: string
+): readonly string[] => {
+  if (!pattern.endsWith('/*')) {
+    const workspaceDir = nodePath().join(rootDir, pattern);
+    return fs().existsSync(nodePath().join(workspaceDir, 'package.json'))
+      ? [workspaceDir]
+      : [];
+  }
+
+  const groupDir = nodePath().join(rootDir, pattern.slice(0, -2));
+  if (!fs().existsSync(groupDir)) {
+    return [];
+  }
+
+  return fs()
+    .readdirSync(groupDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => nodePath().join(groupDir, entry.name))
+    .filter((workspaceDir) =>
+      fs().existsSync(nodePath().join(workspaceDir, 'package.json'))
+    )
+    .toSorted();
+};
+
+/**
+ * List package directories matched by workspace patterns.
+ *
+ * Only directories containing `package.json` are returned.
+ *
+ * @example
+ * ```ts
+ * listWorkspacePackageDirs('/repo', ['packages/*']);
+ * ```
+ */
+export const listWorkspacePackageDirs = (
+  rootDir: string,
+  patterns: readonly string[]
+): readonly string[] =>
+  patterns.flatMap((pattern) => workspaceDirsForPattern(rootDir, pattern));
+
+/**
+ * List workspace package manifests from a workspace root.
+ *
+ * @example
+ * ```ts
+ * const packages = listWorkspacePackages('/repo');
+ * ```
+ */
+export const listWorkspacePackages = <
+  Manifest extends { readonly name?: unknown } = { readonly name?: unknown },
+>(
+  rootDir: string
+): readonly WorkspacePackage<Manifest>[] => {
+  const normalizedRoot = normalizeRealPath(rootDir);
+  const rootManifest = readJsonSync<WorkspaceRootManifest>(
+    nodePath().join(normalizedRoot, 'package.json')
+  );
+  const packages: WorkspacePackage<Manifest>[] = [];
+
+  for (const workspaceDir of listWorkspacePackageDirs(
+    normalizedRoot,
+    listWorkspacePatterns(rootManifest)
+  )) {
+    const packageJsonPath = nodePath().join(workspaceDir, 'package.json');
+    const manifest = readJsonSync<Manifest>(packageJsonPath);
+    if (!manifest || typeof manifest.name !== 'string') {
+      continue;
+    }
+
+    const packageRoot = normalizeRealPath(nodePath().dirname(packageJsonPath));
+    packages.push({
+      manifest,
+      packageJsonPath: normalizeRealPath(packageJsonPath),
+      packageRoot,
+      workspacePath: normalizePath(
+        nodePath().relative(normalizedRoot, packageRoot)
+      ),
+    });
   }
+
+  return packages.toSorted((left, right) =>
+    left.workspacePath.localeCompare(right.workspacePath)
+  );
 };
 
+/**
+ * Find a workspace package by its package name.
+ *
+ * @example
+ * ```ts
+ * const workspace = findWorkspacePackage('/repo', '@ontrails/core');
+ * ```
+ */
+export const findWorkspacePackage = <
+  Manifest extends { readonly name?: unknown } = { readonly name?: unknown },
+>(
+  rootDir: string,
+  packageName: string
+): WorkspacePackage<Manifest> | undefined =>
+  listWorkspacePackages<Manifest>(rootDir).find(
+    (workspacePackage) => workspacePackage.manifest.name === packageName
+  );
+
 /**
  * Walks up from `startDir` (defaults to `process.cwd()`) looking for a
  * `package.json` that contains a `"workspaces"` field.
@@ -35,15 +198,15 @@ const hasWorkspacesField = async (dir: string): Promise<boolean> => {
 export const findWorkspaceRoot = async (
   startDir?: string
 ): Promise<Result<string, NotFoundError>> => {
-  let current = resolve(startDir ?? process.cwd());
+  let current = nodePath().resolve(startDir ?? process.cwd());
 
   // eslint-disable-next-line no-constant-condition
   while (true) {
-    if (await hasWorkspacesField(current)) {
+    if (hasWorkspacesField(current)) {
       return Result.ok(current);
     }
 
-    const parent = dirname(current);
+    const parent = nodePath().dirname(current);
 
     if (parent === current) {
       return Result.err(
@@ -64,6 +227,7 @@ export const isInsideWorkspace = (
   filePath: string,
   workspaceRoot: string
 ): boolean => {
+  const { isAbsolute, relative, resolve } = nodePath();
   const rel = relative(resolve(workspaceRoot), resolve(filePath));
   return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
 };
@@ -74,4 +238,7 @@ export const isInsideWorkspace = (
 export const deriveRelativePath = (
   filePath: string,
   workspaceRoot: string
-): string => relative(resolve(workspaceRoot), resolve(filePath));
+): string => {
+  const { relative, resolve } = nodePath();
+  return relative(resolve(workspaceRoot), resolve(filePath));
+};