@agilno-tech/rivet 0.1.0-alpha.0

package/src/adapters/factory.js

@@ -0,0 +1,122 @@
+import { createAdapter, captureRecord } from './contract.js';
+import { createJiraAdapter } from './jira.js';
+import { createLinearAdapter } from './linear.js';
+import { providerCredentialStatus } from '../config/load.js';
+
+const TRACKERS = new Set(['jira', 'linear']);
+const ENV_NAME = /^[A-Z][A-Z0-9_]{1,127}$/;
+
+export class TrackerProviderFactoryError extends Error {
+  constructor() {
+    super('Tracker provider configuration is missing, ambiguous, or invalid.');
+    this.name = 'TrackerProviderFactoryError';
+    this.code = 'ERR_TRACKER_PROVIDER_CONFIGURATION';
+    this.safeMessage = this.message;
+  }
+}
+
+function fail() { throw new TrackerProviderFactoryError(); }
+
+function snapshotInput(input) {
+  try {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) fail();
+    const allowed = new Set(['config', 'environment', 'transport', 'clock']);
+    const keys = Reflect.ownKeys(input);
+    if (keys.some(key => typeof key !== 'string' || !allowed.has(key))
+      || !['config', 'environment', 'transport'].every(key => keys.includes(key))) fail();
+    const output = {};
+    for (const key of keys) {
+      const descriptor = Object.getOwnPropertyDescriptor(input, key);
+      if (!descriptor?.enumerable || !Object.hasOwn(descriptor, 'value')) fail();
+      output[key] = descriptor.value;
+    }
+    return output;
+  } catch (error) {
+    if (error instanceof TrackerProviderFactoryError) throw error;
+    fail();
+  }
+}
+
+function envValue(environment, reference) {
+  if (typeof reference !== 'string' || !ENV_NAME.test(reference)) fail();
+  let value;
+  try { value = environment[reference]; } catch { fail(); }
+  if (typeof value !== 'string' || value.length < 1 || value.length > 8192 || /[\u0000\r\n]/.test(value)) fail();
+  return value;
+}
+
+function selectProvider(providers, tracker, projectId) {
+  if (tracker !== undefined && !TRACKERS.has(tracker)) fail();
+  const candidates = providers.filter(provider => provider && typeof provider === 'object' && !Array.isArray(provider)
+    && (!provider.projectIds?.length || provider.projectIds.includes(projectId))
+    && (provider.transport === undefined || provider.transport === 'direct-api')
+    && TRACKERS.has(provider.kind) && provider.mode !== 'disabled'
+    && Array.isArray(provider.capabilities) && provider.capabilities.includes('issues-read')
+    && (tracker === undefined || provider.kind === tracker));
+  if (candidates.length !== 1) fail();
+  return candidates[0];
+}
+
+function credentialsFor(provider, environment) {
+  const credentials = provider.credentials;
+  if (!credentials || typeof credentials !== 'object' || Array.isArray(credentials)) fail();
+  if (provider.kind === 'jira') {
+    const username = envValue(environment, credentials.usernameEnv);
+    const token = envValue(environment, credentials.apiTokenEnv);
+    return Object.freeze({ authorization: `Basic ${Buffer.from(`${username}:${token}`, 'utf8').toString('base64')}`, accept: 'application/json' });
+  }
+  return Object.freeze({ authorization: envValue(environment, credentials.apiTokenEnv), accept: 'application/json' });
+}
+
+export function createTrackerProviderFactory(input) {
+  const captured = snapshotInput(input);
+  const providers = captured.config?.providers?.providers;
+  if (!Array.isArray(providers) || providers.length < 1 || providers.length > 64
+    || !captured.environment || typeof captured.environment !== 'object' || Array.isArray(captured.environment)
+    || !captured.transport || typeof captured.transport !== 'object'
+    || (captured.clock !== undefined && typeof captured.clock !== 'function')) fail();
+
+  const credentialStatus = () => {
+    try {
+      return providerCredentialStatus(captured.config, captured.environment)
+        .filter(item => providers.some(provider => provider.id === item.provider && TRACKERS.has(provider.kind)));
+    } catch { fail(); }
+  };
+
+  return Object.freeze({
+    credentialStatus,
+    create(options = {}) {
+      try {
+        if (!options || typeof options !== 'object' || Array.isArray(options)) fail();
+        const keys = Reflect.ownKeys(options);
+        if (keys.some(key => key !== 'tracker')) fail();
+        if (keys.includes('tracker')) {
+          const descriptor = Object.getOwnPropertyDescriptor(options, 'tracker');
+          if (!descriptor?.enumerable || !Object.hasOwn(descriptor, 'value')) fail();
+        }
+        const selected = selectProvider(providers, options.tracker, captured.config.project?.id);
+        if (typeof selected.endpoint !== 'string') fail();
+        const common = {
+          transport: captured.transport,
+          baseUrl: selected.endpoint,
+          headers: credentialsFor(selected, captured.environment),
+          ...(captured.clock === undefined ? {} : { clock: captured.clock }),
+        };
+        const adapter = selected.kind === 'jira' ? createJiraAdapter(common) : createLinearAdapter(common);
+        const scope = selected.resourceIds === undefined ? [] : [...selected.resourceIds];
+        if (!Array.isArray(selected.resourceIds ?? []) || scope.some(id => typeof id !== 'string' || !id || id.length > 200)) fail();
+        if (!scope.length) return adapter;
+        return createAdapter({ provider: adapter.provider, fixtureSource: adapter.fixtureSource, capabilities: adapter.capabilities, write: adapter.write,
+          async read(input) {
+            const request = captureRecord(input, new Set(['kind', 'id', 'signal']), ['kind', 'id']);
+            if (!scope.includes(request.id)) fail();
+            return adapter.read(request);
+          },
+        });
+      } catch (error) {
+        if (error instanceof TrackerProviderFactoryError) throw error;
+        fail();
+      }
+    },
+  });
+}

package/src/adapters/figma.js

@@ -0,0 +1,178 @@
+import {
+  boundedArray,
+  boundedString,
+  captureRecord,
+  createAdapter,
+  createSourceEnvelope,
+  failProvider,
+  immutableRedactedJson,
+  providerTimestamp,
+  readOnlyWrite,
+  sanitizeReferenceUrl,
+  snapshotProviderJson,
+} from './contract.js';
+import { createProviderHttpClient } from './http.js';
+
+const READ = Object.freeze(['file', 'nodes']);
+const WRITE = Object.freeze([]);
+
+function remoteFailure() { failProvider('remote', { provider: 'figma', retryClassification: 'permanent' }); }
+
+function validateNamedMap(value, kind) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) remoteFailure();
+  for (const entry of Object.values(value)) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry) || typeof entry.name !== 'string') remoteFailure();
+    if ((kind === 'component' || kind === 'style') && typeof entry.key !== 'string') remoteFailure();
+    if (kind === 'variable' && (!entry.valuesByMode || typeof entry.valuesByMode !== 'object' || Array.isArray(entry.valuesByMode))) remoteFailure();
+  }
+  return value;
+}
+
+function validateDocument(root) {
+  const pending = [root];
+  let count = 0;
+  while (pending.length > 0) {
+    const node = pending.pop();
+    count += 1;
+    if (count > 10_000 || !node || typeof node !== 'object' || Array.isArray(node)
+      || typeof node.id !== 'string' || typeof node.name !== 'string' || typeof node.type !== 'string'
+      || (node.children !== undefined && !Array.isArray(node.children))) remoteFailure();
+    if (node.children) pending.push(...node.children);
+  }
+}
+
+function validateFile(value) {
+  try {
+    if (!value || typeof value !== 'object' || Array.isArray(value) || typeof value.name !== 'string'
+      || typeof value.version !== 'string' || !value.document || typeof value.document !== 'object'
+      || Array.isArray(value.document)) throw new Error();
+    validateDocument(value.document);
+    validateNamedMap(value.components === undefined ? {} : value.components, 'component');
+    validateNamedMap(value.styles === undefined ? {} : value.styles, 'style');
+    if (value.variables !== undefined) validateNamedMap(value.variables, 'variable');
+    return value;
+  } catch { remoteFailure(); }
+}
+
+function validateNodes(value, requestedIds) {
+  try {
+    if (!value || typeof value !== 'object' || Array.isArray(value)
+      || !value.nodes || typeof value.nodes !== 'object' || Array.isArray(value.nodes)) throw new Error();
+    const returned = Object.keys(value.nodes).sort();
+    const requested = [...requestedIds].sort();
+    if (returned.length !== requested.length || returned.some((id, index) => id !== requested[index])) throw new Error();
+    for (const id of returned) {
+      const item = value.nodes[id];
+      if (!item || typeof item !== 'object' || Array.isArray(item)
+        || !item.document || typeof item.document !== 'object' || Array.isArray(item.document)
+        || item.document.id !== id || typeof item.document.name !== 'string' || typeof item.document.type !== 'string') throw new Error();
+      validateDocument(item.document);
+    }
+    return value;
+  } catch { remoteFailure(); }
+}
+
+function flattenNodes(root) {
+  const output = [];
+  const pending = [root];
+  let visited = 0;
+  while (pending.length > 0) {
+    const node = pending.pop();
+    if (!node || typeof node !== 'object') continue;
+    visited += 1;
+    if (visited > 10_000) failProvider('invalid-request', { provider: 'figma' });
+    if (typeof node.id === 'string' && node.type !== 'DOCUMENT') {
+      output.push({ id: node.id, name: String(node.name ?? ''), type: String(node.type ?? '') });
+    }
+    if (Array.isArray(node.children)) for (let index = node.children.length - 1; index >= 0; index -= 1) pending.push(node.children[index]);
+  }
+  return output;
+}
+
+export function normalizeFigma(file, rendered = {}, variables) {
+  const source = snapshotProviderJson(file);
+  const renderedSource = snapshotProviderJson(rendered);
+  const variableSource = variables === undefined ? (source?.variables ?? {}) : snapshotProviderJson(variables);
+  return immutableRedactedJson({
+    metadata: {
+      name: String(source?.name ?? ''), version: String(source?.version ?? ''),
+      lastModified: String(source?.lastModified ?? ''),
+    },
+    nodes: flattenNodes(source?.document), components: source?.components ?? {}, styles: source?.styles ?? {},
+    variables: variableSource,
+    renderedReferences: Object.entries(renderedSource).map(([nodeId, url]) => ({
+      nodeId, url: sanitizeReferenceUrl(url),
+    })),
+  });
+}
+
+export function createFigmaAdapter(input) {
+  const config = captureRecord(input, new Set([
+    'transport', 'baseUrl', 'headers', 'timeoutMs', 'maxResponseBytes', 'maxPages', 'clock',
+  ]), ['transport', 'baseUrl'], 'invalid-config');
+  const now = config.clock ?? (() => new Date().toISOString());
+  if (typeof now !== 'function') failProvider('invalid-config', { provider: 'figma' });
+  const http = createProviderHttpClient({
+    provider: 'figma', baseUrl: config.baseUrl, transport: config.transport,
+    ...(config.headers === undefined ? {} : { headers: config.headers }),
+    ...(config.timeoutMs === undefined ? {} : { timeoutMs: config.timeoutMs }),
+    ...(config.maxResponseBytes === undefined ? {} : { maxResponseBytes: config.maxResponseBytes }),
+    ...(config.maxPages === undefined ? {} : { maxPages: config.maxPages }),
+  });
+
+  async function read(inputRead) {
+    const request = captureRecord(inputRead, new Set(['kind', 'id', 'nodeIds', 'render', 'includeVariables', 'signal']), ['kind', 'id']);
+    const kind = boundedString(request.kind, 16, /^(?:file|nodes)$/);
+    const id = boundedString(request.id, 128, /^[A-Za-z0-9_-]+$/);
+    const nodeIds = request.nodeIds === undefined ? Object.freeze([]) : boundedArray(
+      request.nodeIds, 100, child => boundedString(child, 128, /^[A-Za-z0-9:;._-]+$/),
+    );
+    if (new Set(nodeIds).size !== nodeIds.length || (kind === 'nodes' && nodeIds.length === 0)) failProvider('invalid-request', { provider: 'figma' });
+    if (request.render !== undefined && typeof request.render !== 'boolean') failProvider('invalid-request', { provider: 'figma' });
+    if (request.includeVariables !== undefined && typeof request.includeVariables !== 'boolean') failProvider('invalid-request', { provider: 'figma' });
+    const signal = request.signal === undefined ? {} : { signal: request.signal };
+    const path = kind === 'nodes'
+      ? `/v1/files/${encodeURIComponent(id)}/nodes?ids=${encodeURIComponent(nodeIds.join(','))}`
+      : `/v1/files/${encodeURIComponent(id)}`;
+    const fileResponse = await http.request({ method: 'GET', path, ...signal });
+    if (kind === 'file') validateFile(fileResponse.data);
+    else validateNodes(fileResponse.data, nodeIds);
+    const file = kind === 'nodes'
+      ? { ...fileResponse.data, document: { id: 'selected', name: 'Selected nodes', type: 'DOCUMENT', children: Object.values(fileResponse.data?.nodes ?? {}).map(item => item?.document).filter(Boolean) } }
+      : fileResponse.data;
+    let rendered = {};
+    if (request.render === true && nodeIds.length > 0) {
+      const imageResponse = await http.request({
+        method: 'GET', path: `/v1/images/${encodeURIComponent(id)}?ids=${encodeURIComponent(nodeIds.join(','))}`, ...signal,
+      });
+      rendered = imageResponse.data?.images;
+      if (!rendered || typeof rendered !== 'object' || Array.isArray(rendered)
+        || Object.values(rendered).some(value => typeof value !== 'string')) failProvider('remote', { provider: 'figma' });
+      try { for (const value of Object.values(rendered)) sanitizeReferenceUrl(value); }
+      catch { failProvider('remote', { provider: 'figma', retryClassification: 'permanent' }); }
+      const imageIds = Object.keys(rendered).sort();
+      const requestedImageIds = [...nodeIds].sort();
+      if (imageIds.length !== requestedImageIds.length
+        || imageIds.some((nodeId, index) => nodeId !== requestedImageIds[index])) remoteFailure();
+    }
+    let variables = file?.variables ?? {};
+    if (request.includeVariables === true) {
+      const variableResponse = await http.request({
+        method: 'GET', path: `/v1/files/${encodeURIComponent(id)}/variables/local`, ...signal,
+      });
+      variables = variableResponse.data?.meta?.variables;
+      if (!variables || typeof variables !== 'object' || Array.isArray(variables)) failProvider('remote', { provider: 'figma' });
+      validateNamedMap(variables, 'variable');
+    }
+    return createSourceEnvelope({
+      provider: 'figma', sourceId: id, sourceUrl: `https://www.figma.com/file/${encodeURIComponent(id)}`,
+      fetchedAt: providerTimestamp(now, 'figma'), fixtureSource: false, raw: { file, rendered, variables }, normalized: normalizeFigma(file, rendered, variables),
+      retryClassification: 'none', capabilities: { read: READ, write: WRITE },
+    });
+  }
+
+  return createAdapter({
+    provider: 'figma', fixtureSource: false, capabilities: { read: READ, write: WRITE },
+    read, write: readOnlyWrite('figma'),
+  });
+}

package/src/adapters/fixtures.js

@@ -0,0 +1,183 @@
+import { constants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import { isAbsolute, join, resolve } from 'node:path';
+
+import {
+  boundedString,
+  captureRecord,
+  createAdapter,
+  createSourceEnvelope,
+  failProvider,
+  readOnlyWrite,
+} from './contract.js';
+import { normalizeConfluence } from './confluence.js';
+import { normalizeFigma } from './figma.js';
+import { normalizeJira } from './jira.js';
+
+const DEFINITIONS = Object.freeze({
+  jira: Object.freeze({ file: 'jira.json', read: Object.freeze(['epic', 'issue']), normalize: normalizeJira }),
+  confluence: Object.freeze({ file: 'confluence.json', read: Object.freeze(['page']), normalize: normalizeConfluence }),
+  figma: Object.freeze({ file: 'figma.json', read: Object.freeze(['file', 'nodes']), normalize: raw => normalizeFigma(raw, Object.fromEntries(
+    (raw?.renderedReferences ?? []).map(item => [item.nodeId, item.url]),
+  )) }),
+  github: Object.freeze({
+    file: 'github.json', read: Object.freeze(['repo', 'branch', 'pull', 'checks', 'reviews', 'artifacts', 'delivery']),
+    normalize: raw => raw,
+  }),
+});
+const trustedPacketSources = new WeakMap();
+
+function descriptorRoot(handle) {
+  if (process.platform !== 'linux') failProvider('invalid-config');
+  return `/proc/self/fd/${handle.fd}`;
+}
+
+function sameIdentity(left, right) {
+  return left.dev === right.dev && left.ino === right.ino && left.size === right.size
+    && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+
+function trustedHandle(value, provider) {
+  let stat;
+  let read;
+  try { ({ stat, read } = value); } catch { failProvider('invalid-config', { provider }); }
+  if (typeof stat !== 'function' || typeof read !== 'function') failProvider('invalid-config', { provider });
+  return Object.freeze({
+    stat: options => Reflect.apply(stat, value, [options]),
+    read: (...args) => Reflect.apply(read, value, args),
+  });
+}
+
+export function createTrustedFixturePacketSource(input) {
+  const value = captureRecord(input, new Set(['packets']), ['packets'], 'invalid-config');
+  const providers = Object.keys(DEFINITIONS);
+  const packets = captureRecord(value.packets, new Set(providers), providers, 'invalid-config');
+  const handles = {};
+  for (const provider of providers) handles[provider] = trustedHandle(packets[provider], provider);
+  const source = Object.freeze({ kind: 'trusted-preopened-provider-fixtures' });
+  trustedPacketSources.set(source, Object.freeze(handles));
+  return source;
+}
+
+async function readPacket(handle, provider, validateAnchor = async () => {}) {
+  let text;
+  let identity;
+  try {
+    const before = await handle.stat({ bigint: true });
+    if (!before.isFile() || before.nlink !== 1n || before.size < 2n || before.size > BigInt(2 * 1024 * 1024)) failProvider('invalid-config', { provider });
+    const size = Number(before.size);
+    const bytes = Buffer.alloc(size + 1);
+    let offset = 0;
+    while (offset < bytes.length) {
+      const result = await handle.read(bytes, offset, bytes.length - offset, offset);
+      if (result.bytesRead === 0) break;
+      offset += result.bytesRead;
+    }
+    const after = await handle.stat({ bigint: true });
+    await validateAnchor();
+    if (offset !== size || !sameIdentity(before, after)) {
+      failProvider('invalid-config', { provider });
+    }
+    identity = `${before.dev}:${before.ino}`;
+    try { text = new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, size)); }
+    catch { failProvider('invalid-config', { provider }); }
+  } catch { failProvider('invalid-config', { provider }); }
+  let packet;
+  try { packet = JSON.parse(text); } catch { failProvider('invalid-config', { provider }); }
+  const value = captureRecord(packet, new Set(['sourceId', 'sourceUrl', 'fetchedAt', 'raw']), ['sourceId', 'sourceUrl', 'fetchedAt', 'raw'], 'invalid-config');
+  return Object.freeze({ identity, packet: Object.freeze({
+    sourceId: boundedString(value.sourceId, 256), sourceUrl: boundedString(value.sourceUrl, 2048),
+    fetchedAt: boundedString(value.fetchedAt, 32), raw: value.raw,
+  }) });
+}
+
+async function loadPacket(rootHandle, rootIdentity, root, definition, provider) {
+  const path = join(descriptorRoot(rootHandle), definition.file);
+  const noFollow = constants.O_NOFOLLOW;
+  if (!Number.isInteger(noFollow)) failProvider('invalid-config', { provider });
+  let fileHandle;
+  try { fileHandle = await open(path, constants.O_RDONLY | noFollow); }
+  catch { failProvider('invalid-config', { provider }); }
+  try {
+    return await readPacket(trustedHandle(fileHandle, provider), provider, async () => {
+      const rootAfter = await rootHandle.stat({ bigint: true });
+      const rootPathAfter = await lstat(root, { bigint: true }).catch(() => null);
+      if (rootAfter.dev !== rootIdentity.dev || rootAfter.ino !== rootIdentity.ino
+        || !rootPathAfter || rootPathAfter.dev !== rootIdentity.dev || rootPathAfter.ino !== rootIdentity.ino) {
+        failProvider('invalid-config', { provider });
+      }
+    });
+  } finally {
+    await fileHandle.close().catch(() => {});
+  }
+}
+
+async function loadPreopenedPackets(source) {
+  const handles = trustedPacketSources.get(source);
+  if (!handles) failProvider('invalid-config');
+  const packets = {};
+  const identities = new Set();
+  for (const [provider, definition] of Object.entries(DEFINITIONS)) {
+    const result = await readPacket(handles[provider], provider);
+    if (identities.has(result.identity)) failProvider('invalid-config', { provider });
+    identities.add(result.identity);
+    packets[provider] = result.packet;
+  }
+  return packets;
+}
+
+async function loadRootPackets(rootInput) {
+  if (process.platform !== 'linux') failProvider('invalid-config');
+  const root = await realpath(rootInput).catch(() => null);
+  if (!root || root !== rootInput) failProvider('invalid-config');
+  const pathIdentity = await lstat(root, { bigint: true }).catch(() => null);
+  if (!pathIdentity?.isDirectory() || pathIdentity.isSymbolicLink()) failProvider('invalid-config');
+  const directoryFlags = constants.O_RDONLY | (constants.O_DIRECTORY ?? 0) | (constants.O_NOFOLLOW ?? 0);
+  let rootHandle;
+  try { rootHandle = await open(root, directoryFlags); } catch { failProvider('invalid-config'); }
+  const packets = {};
+  const identities = new Set();
+  try {
+    const identity = await rootHandle.stat({ bigint: true });
+    if (!identity.isDirectory() || identity.dev !== pathIdentity.dev || identity.ino !== pathIdentity.ino) failProvider('invalid-config');
+    for (const [provider, definition] of Object.entries(DEFINITIONS)) {
+      const result = await loadPacket(rootHandle, identity, root, definition, provider);
+      if (identities.has(result.identity)) failProvider('invalid-config', { provider });
+      identities.add(result.identity);
+      packets[provider] = result.packet;
+    }
+  } finally { await rootHandle.close().catch(() => {}); }
+  return packets;
+}
+
+export async function createFixtureAdapters(input) {
+  const config = captureRecord(input, new Set(['root', 'source']), [], 'invalid-config');
+  if ((config.root === undefined) === (config.source === undefined)) failProvider('invalid-config');
+  let packets;
+  if (config.source !== undefined) packets = await loadPreopenedPackets(config.source);
+  else {
+    const rootInput = boundedString(config.root, 2048, undefined, 'invalid-config');
+    if (!isAbsolute(rootInput) || resolve(rootInput) !== rootInput) failProvider('invalid-config');
+    packets = await loadRootPackets(rootInput);
+  }
+  const output = {};
+  for (const [provider, definition] of Object.entries(DEFINITIONS)) {
+    const packet = packets[provider];
+    const read = async inputRead => {
+      const request = captureRecord(inputRead, new Set(['kind']), ['kind']);
+      const kind = boundedString(request.kind, 32, /^[a-z][a-z0-9-]*$/);
+      if (!definition.read.includes(kind)) failProvider('invalid-request', { provider });
+      return createSourceEnvelope({
+        provider, sourceId: packet.sourceId, sourceUrl: packet.sourceUrl, fetchedAt: packet.fetchedAt,
+        fixtureSource: true, raw: packet.raw,
+        normalized: { ...definition.normalize(packet.raw), fixture: Object.freeze({ sourced: true, packet: definition.file }) },
+        retryClassification: 'none', capabilities: { read: definition.read, write: [] },
+      });
+    };
+    output[provider] = createAdapter({
+      provider, fixtureSource: true, capabilities: { read: definition.read, write: [] }, read,
+      write: readOnlyWrite(provider),
+    });
+  }
+  return Object.freeze(output);
+}