@adea-ai/plugins 1.0.0

package/dist/icons.js

@@ -0,0 +1,268 @@
+/**
+ * Compile-time icon resolution.
+ *
+ * Marketplaces do not declare an icon field, so a plugin's mark is a file in
+ * its own content (`assets/logo.svg`, `assets/icon-large.png`, ...). Resolving
+ * one at compile time removes a runtime guess from consumers, and mirroring the
+ * bytes at publish time removes the upstream fetch entirely.
+ */
+/** Icon file size ceiling; a brand mark is never a large asset. */
+export const MAX_ICON_BYTES = 1024 * 1024;
+const SUPPORTED_EXTENSIONS = ['svg', 'png', 'webp', 'jpg', 'jpeg', 'gif', 'ico'];
+/** Ranked basenames; earlier entries win. Variants sort by the rank of the stem. */
+const STEM_RANK = {
+    icon: 0,
+    appicon: 0,
+    'app-icon': 0,
+    avatar: 2,
+    logo: 3,
+    mark: 4,
+    brand: 4,
+};
+const EXTENSION_RANK = {
+    svg: 0,
+    png: 1,
+    webp: 2,
+    ico: 3,
+    jpg: 4,
+    jpeg: 5,
+    gif: 6,
+};
+/** Preferred containers, best first. Files outside these are considered last. */
+const DIRECTORY_RANK = {
+    assets: 0,
+    '.assets': 1,
+    img: 2,
+    images: 3,
+    media: 4,
+    static: 5,
+};
+/** Files that are documentation, screenshots or brand collateral, not marks. */
+const EXCLUDED = /(screenshot|screen-shot|preview|example|sample|demo|mockup|diagram|architecture|flowchart|flow-|banner|hero|cover|thumbnail|chart|graph|illustration|photo)/;
+/** Repository infrastructure: CI images and templates, never a product mark. */
+const EXCLUDED_DIRECTORIES = ['.github', '.gitlab'];
+const MARK_WORDS = new Set([
+    'icon',
+    'appicon',
+    'avatar',
+    'logo',
+    'mark',
+    'brand',
+    'logomark',
+    'wordmark',
+]);
+const VARIANT_WORDS = new Set([
+    'large',
+    'small',
+    'light',
+    'dark',
+    'mono',
+    'white',
+    'black',
+    'positive',
+    'negative',
+    'color',
+    'colour',
+    'primary',
+    'secondary',
+    'horizontal',
+    'vertical',
+    'square',
+    'flat',
+    'glyph',
+]);
+/**
+ * Splits a file name into mark tokens. Separators are normalised because
+ * vendors write marks as `logo.svg`, `atlan-logo.png`, `Dynatrace_Logo_color_positive.png`
+ * or `cs logo big.png` alike.
+ */
+function splitName(basename) {
+    const withoutExtension = basename.slice(0, basename.lastIndexOf('.'));
+    const words = withoutExtension
+        .split(/[\s._-]+/)
+        .filter(Boolean)
+        .map((word) => word.toLowerCase());
+    const size = words.some((word) => word === 'small') ? 1 : 0;
+    const marks = words.some((word) => MARK_WORDS.has(word));
+    const stems = words.filter((word) => !MARK_WORDS.has(word) && !VARIANT_WORDS.has(word));
+    return { stems, marks, size };
+}
+/**
+ * Chooses one icon file from a release's file index, deterministically.
+ *
+ * Preference: `assets/icon.svg` before `assets/icon.png` before `assets/logo.*`,
+ * an `icon`/`logo` stem before `avatar`/`mark`/`brand`, an `assets` directory
+ * before other asset directories, SVG before raster for the same stem, and a
+ * `-large` variant before `-small`. Anything that looks like documentation or a
+ * screenshot is never selected. Ties break on path so the result is stable.
+ */
+export function selectIconPath(fileIndex) {
+    let best = null;
+    for (const raw of fileIndex) {
+        const path = raw.replace(/^\.?\//, '');
+        if (path.includes('..'))
+            continue;
+        const segments = path.split('/');
+        const basename = segments.pop() ?? '';
+        const extension = basename.slice(basename.lastIndexOf('.') + 1).toLowerCase();
+        if (!SUPPORTED_EXTENSIONS.includes(extension))
+            continue;
+        if (EXCLUDED.test(basename))
+            continue;
+        const directories = segments.map((segment) => segment.toLowerCase());
+        if (directories.some((segment) => EXCLUDED.test(segment)))
+            continue;
+        if (directories.some((segment) => EXCLUDED_DIRECTORIES.includes(segment)))
+            continue;
+        const { stems, marks, size } = splitName(basename);
+        const single = stems.length === 1 ? stems[0] : undefined;
+        const stemRank = marks ? (single ? (STEM_RANK[single] ?? 0) : 0) : undefined;
+        const nested = directories.filter((segment) => DIRECTORY_RANK[segment] !== undefined);
+        // A mark named as one — `logo.svg`, `atlan-logo.png`, `cs_logo_large.png` —
+        // is accepted anywhere, including the plugin root. An unnamed image must sit
+        // in a known asset directory, because a bare `banner.png` at the root is as
+        // likely to be documentation as a brand mark.
+        const directoryRank = nested.length > 0
+            ? (DIRECTORY_RANK[nested[nested.length - 1]] ?? 0)
+            : stemRank === undefined
+                ? Number.POSITIVE_INFINITY
+                : 0;
+        if (!Number.isFinite(directoryRank))
+            continue;
+        const score = [stemRank ?? 5, directoryRank, size, EXTENSION_RANK[extension] ?? 9, path.length];
+        if (!best || compareScore(score, best.score) < 0)
+            best = { path, score };
+    }
+    return best ? best.path : null;
+}
+function compareScore(left, right) {
+    for (let index = 0; index < left.length; index += 1) {
+        const difference = (left[index] ?? 0) - (right[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+}
+const SVG_ACTIVE_CONTENT = /<\s*script|<\s*foreignObject|<\s*iframe|<\s*use[^>]+href\s*=\s*["']?\s*(?:https?:)?\/\/|javascript:|<!ENTITY|<!DOCTYPE[^>]+\[|on(?:load|error|click|mouseover|focus|begin)\s*=/i;
+const SVG_EXTERNAL_REFERENCE = /(?:href|xlink:href|src|data|poster)\s*=\s*["']?\s*(?:https?:)?\/\//i;
+/** Sniffs a supported image type from magic bytes; SVG is detected as text. */
+export function sniffContentType(bytes) {
+    const ascii = (offset, length) => String.fromCharCode(...bytes.subarray(offset, offset + length));
+    if (bytes.length >= 8 && ascii(0, 8) === '\x89PNG\r\n\x1a\n')
+        return 'image/png';
+    if (bytes.length >= 3 && ascii(0, 3) === '\xff\xd8\xff')
+        return 'image/jpeg';
+    if (bytes.length >= 6 && ascii(0, 4) === 'GIF8')
+        return 'image/gif';
+    if (bytes.length >= 12 && ascii(0, 4) === 'RIFF' && ascii(8, 4) === 'WEBP')
+        return 'image/webp';
+    // Icon container: reserved(2), type 1 (icon) or 2 (cursor), count >= 1.
+    if (bytes.length >= 6 &&
+        bytes[0] === 0 &&
+        bytes[1] === 0 &&
+        (bytes[2] === 1 || bytes[2] === 2) &&
+        bytes[3] === 0 &&
+        ((bytes[4] ?? 0) | ((bytes[5] ?? 0) << 8)) > 0)
+        return 'image/x-icon';
+    if (bytes.length > 0) {
+        // An XML prologue, a doctype and leading comments may all precede the root
+        // element: exporters such as Adobe Illustrator and Figma emit them. What
+        // matters is that the document's root element is `<svg>`, not `<html>`.
+        const head = new TextDecoder()
+            .decode(bytes.subarray(0, Math.min(bytes.length, 4096)))
+            .trimStart()
+            .replace(/^<\?xml[\s\S]*?\?>/i, '')
+            .replace(/^<!DOCTYPE[^>]*?(?:\[[\s\S]*?\])?>/i, '')
+            .replace(/^(?:\s*<!--[\s\S]*?-->)+/, '')
+            .trimStart();
+        if (/^<svg[\s>]/i.test(head))
+            return 'image/svg+xml';
+    }
+    return null;
+}
+/**
+ * Verifies icon bytes before they are published.
+ *
+ * SVG is text that a browser can execute when it is inlined, so active content
+ * and external references are rejected outright. Consumers must still render a
+ * mirrored SVG through an `<img>` element and never inline it into the DOM.
+ */
+export function inspectIconBytes(bytes) {
+    if (bytes.length === 0)
+        return { rejected: 'EMPTY_FILE' };
+    if (bytes.length > MAX_ICON_BYTES)
+        return { rejected: 'SIZE_LIMIT_EXCEEDED' };
+    const contentType = sniffContentType(bytes);
+    if (!contentType)
+        return { rejected: 'CONTENT_TYPE_UNSUPPORTED' };
+    if (contentType === 'image/svg+xml') {
+        const text = new TextDecoder().decode(bytes);
+        if (SVG_ACTIVE_CONTENT.test(text))
+            return { rejected: 'SVG_ACTIVE_CONTENT' };
+        if (SVG_EXTERNAL_REFERENCE.test(text))
+            return { rejected: 'SVG_EXTERNAL_REFERENCE' };
+    }
+    return { contentType };
+}
+const EXTENSION_BY_CONTENT_TYPE = {
+    'image/png': 'png',
+    'image/jpeg': 'jpg',
+    'image/gif': 'gif',
+    'image/webp': 'webp',
+    'image/svg+xml': 'svg',
+    'image/x-icon': 'ico',
+};
+/**
+ * Content-addressed asset name. Release assets cannot contain `/`, so the
+ * digest prefix and extension form one flat name that any release can host.
+ */
+export function iconAssetName(digest, contentType) {
+    const extension = EXTENSION_BY_CONTENT_TYPE[contentType];
+    if (!extension)
+        throw new Error(`ICON_CONTENT_TYPE_UNSUPPORTED: ${contentType}`);
+    const hex = digest.startsWith('sha256:') ? digest.slice('sha256:'.length) : digest;
+    return `icon-${hex.slice(0, 32)}.${extension}`;
+}
+export function parseProductIconOverrides(input) {
+    if (typeof input !== 'object' || input === null)
+        throw new Error('PRODUCT_ICONS_INVALID');
+    const raw = input;
+    if (raw.schemaVersion !== 1)
+        throw new Error('PRODUCT_ICONS_INVALID');
+    const overrides = raw.overrides;
+    if (typeof overrides !== 'object' || overrides === null)
+        throw new Error('PRODUCT_ICONS_INVALID');
+    for (const [productKey, value] of Object.entries(overrides)) {
+        if (!/^[a-z0-9][a-z0-9-]{1,127}$/.test(productKey))
+            throw new Error(`PRODUCT_ICONS_KEY_INVALID: ${productKey}`);
+        if (value === null)
+            continue;
+        if (typeof value !== 'string' || value.length === 0 || value.length > 1024)
+            throw new Error(`PRODUCT_ICONS_PATH_INVALID: ${productKey}`);
+        if (value.startsWith('https://')) {
+            // Only the shape is checked here; site-icons applies the full host policy
+            // when it resolves the mark, so a bad host simply yields no icon.
+            if (!/^https:\/\/[a-z0-9.-]+\.[a-z]{2,}/i.test(value))
+                throw new Error(`PRODUCT_ICONS_SITE_UNSUPPORTED: ${productKey}`);
+            continue;
+        }
+        if (value.startsWith('/') || value.includes('..'))
+            throw new Error(`PRODUCT_ICONS_PATH_INVALID: ${productKey}`);
+    }
+    return { schemaVersion: 1, overrides: { ...overrides } };
+}
+/**
+ * Reads the override for a product: `forced` names a content path or `null` to
+ * publish no mark, and `site` names a vendor site to take the mark from.
+ */
+export function iconOverrideFor(overrides, productKey) {
+    if (!overrides || !(productKey in overrides.overrides))
+        return undefined;
+    const value = overrides.overrides[productKey];
+    if (value === null)
+        return { forced: null };
+    if (typeof value !== 'string')
+        return undefined;
+    return value.startsWith('https://') ? { site: value } : { forced: value };
+}
+//# sourceMappingURL=icons.js.map

package/dist/icons.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"icons.js","sourceRoot":"","sources":["../src/icons.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,304 @@
+import { type Catalog, type Capability, type Harness, type HarnessCompatibility, type PluginRelease, type SourcesLock } from './schema.js';
+import { type ParsedMarketplace, type SourceConfig } from './sources.js';
+import { type ConsumerCategory, type ConsumerIndex, type ConsumerProduct, type LeadingDiagnostic, type ProductPreference } from './consumer-index.js';
+import { type ProductIconOverrides } from './icons.js';
+import { type SiteIconFetcher } from './site-icons.js';
+/**
+ * Marks the catalog format this compiler emits.
+ *
+ * Bumping or first introducing this value makes a synchronization replay its
+ * verified pins and rebuild, which is how a format change reaches the published
+ * catalog when no upstream source has moved. It is deliberately separate from
+ * the agent-package normalizer version, which describes package normalization
+ * and would misreport a change here.
+ */
+export declare const CATALOG_CONTRACT_VERSION = "adea-catalog/3";
+export interface CatalogPolicy {
+    readonly allowedRepositoryProtocols: readonly string[];
+    readonly allowedRepositoryHosts: readonly string[];
+    readonly maxFilesPerPlugin: number;
+    readonly maxBytesPerPlugin: number;
+    readonly maxFileBytes: number;
+    readonly maxMarketplacePlugins: number;
+    readonly denyExecutableLifecycleScripts: boolean;
+    readonly publishRequiresCompleteContent: boolean;
+    readonly sensitiveCapabilityTypes: readonly string[];
+}
+export interface CategoryMap {
+    readonly aliases: Readonly<Record<string, string>>;
+    readonly fallback: string;
+}
+export interface ProductAliases {
+    readonly aliases: Readonly<Record<string, string>>;
+}
+export interface Snapshot {
+    readonly files: ReadonlyMap<string, Uint8Array>;
+    readonly symlinks: readonly string[];
+}
+/** Trusted compiler extension; never loaded from upstream plugin content. */
+export type ReleaseTransform = (release: PluginRelease, snapshot: Snapshot, pluginName: string) => PluginRelease;
+export interface SnapshotLoader {
+    load(repositoryUrl: string, commitSha: string, pluginSubdirectory: string): Promise<Snapshot>;
+}
+export interface ResolvedSource {
+    readonly config: SourceConfig;
+    readonly commitSha: string;
+    readonly manifestText: string;
+    readonly parsed: ParsedMarketplace;
+    readonly pluginPins: readonly PluginSourcePin[];
+    readonly retrievedAt: string;
+    readonly manifestDigest: string;
+}
+export interface PluginSourcePin {
+    readonly pluginName: string;
+    readonly repositoryUrl: string;
+    readonly pluginSubdirectory: string;
+    readonly resolvedCommitSha: string;
+}
+export interface SyncInput extends ConsumerIndexOptions {
+    readonly sources: readonly SourceConfig[];
+    readonly categoryMap: CategoryMap;
+    readonly productAliases: ProductAliases;
+    readonly productCategories?: Record<string, string>;
+    readonly productIconOverrides?: ProductIconOverrides;
+    /** Where this catalog is published, so records carry absolute asset URLs. */
+    readonly publicationRepositoryUrl?: string;
+    /** Directory that receives mirrored brand marks as the catalog is built. */
+    readonly iconAssetsDirectory?: string;
+    readonly policy: CatalogPolicy;
+    readonly mode?: 'live' | 'offline';
+    readonly fixtureRoot?: string;
+    readonly sourceId?: string;
+    readonly metadataOnly?: boolean;
+    readonly dryRun?: boolean;
+    readonly existingLock?: SourcesLock;
+    readonly existingCatalog?: Catalog;
+    readonly fromLock?: SourcesLock;
+    readonly snapshotLoader?: SnapshotLoader;
+    readonly resolveExternalRefs?: boolean;
+    /** Rebuild even when source pins are unchanged (used for explicit format migrations). */
+    readonly forceRebuild?: boolean;
+    readonly transformRelease?: ReleaseTransform;
+}
+export interface SyncResult {
+    readonly changed: boolean;
+    readonly dryRun: boolean;
+    readonly sourceHeads: readonly {
+        sourceId: string;
+        commitSha: string;
+    }[];
+    readonly catalog?: Catalog;
+    readonly lock?: SourcesLock;
+    readonly artifacts?: GeneratedArtifacts;
+    readonly changeReport: ChangeReport;
+}
+export interface ChangeReport {
+    readonly schemaVersion: 1;
+    readonly changedSources: readonly string[];
+    readonly addedPlugins: readonly string[];
+    readonly removedPlugins: readonly string[];
+    readonly changedPlugins: readonly string[];
+    readonly permissionSensitiveChanges: readonly string[];
+    readonly skippedPlugins: readonly SkippedPlugin[];
+    readonly contentResolution: 'complete' | 'complete-with-skips' | 'metadata-only';
+}
+export type PluginSkipReasonCode = 'GIT_SUBMODULE_UNSUPPORTED' | 'PLUGIN_FILE_TOO_LARGE' | 'PLUGIN_FILE_UNAVAILABLE' | 'PLUGIN_MANIFEST_INVALID' | 'PLUGIN_PATH_NOT_FOUND' | 'PLUGIN_SCHEMA_INVALID' | 'PLUGIN_SIZE_POLICY' | 'PLUGIN_SOURCE_UNAVAILABLE' | 'PLUGIN_TOO_LARGE' | 'PLUGIN_TOO_MANY_FILES' | 'SNAPSHOT_PATH_INVALID' | 'SYMLINK_ESCAPE';
+export interface SkippedPlugin {
+    readonly sourceId: string;
+    readonly pluginId: string;
+    readonly pluginName: string;
+    readonly reasonCode: PluginSkipReasonCode;
+    readonly securityReason: string;
+    readonly incompleteContent: true;
+    readonly paths: readonly string[];
+}
+/**
+ * Published artifacts by file name. The core six are always present; the
+ * consumer shards (`catalog-index.v1.json`, `shelf-<category>.v1.json` and
+ * `category-<category>.v1.json`) follow the configured categories.
+ */
+export interface GeneratedArtifacts {
+    readonly [name: string]: string;
+    readonly 'catalog.v1.json': string;
+    readonly 'catalog-summary.v1.json': string;
+    readonly 'sources.lock.json': string;
+    readonly 'compatibility.v1.json': string;
+    readonly 'categories.v1.json': string;
+    readonly 'integrity.json': string;
+}
+/** Result of checking a published consumer index against its catalog. */
+export interface ConsumerIndexVerification {
+    readonly hasConsumerIndex: boolean;
+    readonly diagnostics: readonly LeadingDiagnostic[];
+    readonly counts?: ConsumerIndex['counts'];
+    readonly topCount?: number;
+    readonly products?: Readonly<Record<string, ConsumerProduct>>;
+    readonly categories?: readonly ConsumerCategory[];
+    /** Shards the published integrity file set must carry for this index. */
+    readonly shards: readonly ShardArtifact[];
+}
+/** One consumer shard artifact and what it must contain. */
+export interface ShardArtifact {
+    readonly name: string;
+    readonly kind: 'index' | 'shelf' | 'list';
+    readonly category?: string;
+}
+/** Consumer index inputs: curated shelves and canonical-variant placement. */
+export interface ConsumerIndexOptions {
+    readonly leading?: Readonly<Record<string, readonly string[]>>;
+    readonly topCount?: number;
+    readonly productPreference?: ProductPreference;
+    /**
+     * Where this catalog is published. When known, product records carry an
+     * absolute, immutable URL for their brand mark so no client composes one.
+     */
+    readonly publicationRepositoryUrl?: string;
+    /**
+     * Base URL of the committed asset directory that browsers fetch directly.
+     *
+     * GitHub release assets answer a cross-origin `fetch` with no CORS header and
+     * redirect through a URL that cannot be cached, so a browser neither reads the
+     * index nor reuses an icon. The same files served from the repository are
+     * CORS-enabled, direct and cacheable.
+     */
+    readonly publicationAssetsBaseUrl?: string;
+    /**
+     * Base URL of the content-addressed snapshot directory, one level below the
+     * asset branch. Catalog artifacts are addressed by catalog identity, so they
+     * live in `catalogs/<catalogId>/` while digest-addressed brand marks sit at
+     * the branch root.
+     */
+    readonly publicationCatalogsBaseUrl?: string;
+    /**
+     * Whether curated-name drift is published in the consumer index. An offline
+     * build replays fixtures rather than the upstream catalogs, so its curation
+     * findings are noise and are omitted by default.
+     */
+    readonly curationDiagnostics?: boolean;
+}
+export declare function canonicalJson(value: unknown): string;
+export declare function digest(value: unknown): string;
+export declare function bytesDigest(files: ReadonlyMap<string, Uint8Array>): string;
+export declare function stablePluginId(sourceId: string, upstreamName: string): string;
+export declare function stableReleaseId(repositoryUrl: string, subdirectory: string, commitSha: string, contentDigest: string): string;
+export declare function normalizeCategory(value: string, map: CategoryMap): string;
+export declare function productGroupingKey(name: string, aliases: ProductAliases): string;
+export declare function synchronize(input: SyncInput): Promise<SyncResult>;
+export declare function buildCatalog(input: {
+    readonly resolvedSources: readonly ResolvedSource[];
+    readonly categoryMap: CategoryMap;
+    readonly productAliases: ProductAliases;
+    readonly productCategories?: Record<string, string>;
+    readonly leading?: Record<string, readonly string[]>;
+    readonly productIconOverrides?: ProductIconOverrides;
+    readonly iconAssetsDirectory?: string;
+    readonly policy?: CatalogPolicy;
+    readonly metadataOnly?: boolean;
+    readonly snapshotLoader: SnapshotLoader;
+    readonly resolveExternalRefs?: boolean;
+    readonly transformRelease?: ReleaseTransform;
+}): Promise<Catalog>;
+/** SHA-256 of a single byte buffer, in the catalog's digest format. */
+export declare function byteDigest(bytes: Uint8Array): string;
+export declare function classifyCapabilities(files: ReadonlyMap<string, Uint8Array>, metadata?: Record<string, unknown>): Capability[];
+export declare function createCompatibility(dialect: MarketplaceDialectName, capabilities: readonly Capability[], policy?: CatalogPolicy): Record<Harness, HarnessCompatibility>;
+type MarketplaceDialectName = 'openai' | 'cursor' | 'claude';
+/**
+ * Orders plugins so each category's curated leading products come first, in
+ * the configured order. Consumers preview the head of each category, so this
+ * ordering decides what users see before expanding.
+ */
+export declare function orderLeadingPlugins<T extends {
+    readonly plugins: readonly {
+        categories: readonly string[];
+        upstreamPluginName: string;
+    }[];
+}>(catalog: T, leading?: Record<string, readonly string[]>): T;
+export declare function createArtifacts(catalog: Catalog, lock: SourcesLock, options?: ConsumerIndexOptions): GeneratedArtifacts;
+export interface PublishedAsset {
+    readonly name: string;
+    readonly digest: string;
+    readonly bytes: number;
+    readonly contentType: string;
+    /** `content` mirrors a plugin file; `favicon` mirrors the product site's icon. */
+    readonly kind: 'content' | 'favicon';
+    /** Upstream path or URL the bytes came from, for provenance. */
+    readonly origin: string;
+}
+/** Every mirrored icon in the catalog, deduplicated by asset name. */
+export declare function iconAssets(index: ConsumerIndex): readonly PublishedAsset[];
+export declare function writeArtifacts(generatedDirectory: string, artifacts: GeneratedArtifacts): Promise<void>;
+export declare function verifyArtifacts(artifacts: GeneratedArtifacts): void;
+/**
+ * Re-checks one consumer shard against the navigation index: a shelf carries
+ * exactly the curated products in order, and a category list carries exactly
+ * the category's products in order.
+ */
+export declare function verifyShardArtifact(shard: ShardArtifact, content: string | undefined, verification: ConsumerIndexVerification): void;
+/**
+ * Re-checks the published consumer index against the catalog it indexes. The
+ * index is what Adea renders directly, so a contradiction between the two
+ * artifacts must never reach a release. Snapshots published before the index
+ * existed carry membership only; those are still membership-checked and
+ * reported as `hasConsumerIndex: false`.
+ */
+export declare function verifyConsumerIndex(content: string, catalog: Pick<Catalog, 'plugins'>, indexContent?: string): ConsumerIndexVerification;
+export declare function verifyCatalogReferences(catalog: Catalog, policy?: CatalogPolicy): void;
+/** Raw content URL for one file at an immutable commit. */
+export declare function rawContentUrl(repositoryUrl: string, commitSha: string, path: string): string;
+/** Fetches bytes from an allow-listed upstream URL with the shared retry policy. */
+export declare function fetchUpstreamBytes(url: string, signal?: AbortSignal): Promise<Uint8Array>;
+/**
+ * Request headers for one upstream URL.
+ *
+ * The credential and GitHub's media type are attached only for GitHub hosts.
+ * Sending them elsewhere is not merely a needless disclosure: `appwrite.io`
+ * answers a page carrying an `Authorization` header with HTTP 500, and a CDN
+ * asked for an image with `accept: application/vnd.github+json` can answer with
+ * bytes that are not the mark. A build that did this dropped marks it had
+ * already curated, and the curation verifier — which used its own anonymous
+ * headers — could not see it.
+ */
+export declare function upstreamRequestHeaders(url: string): Record<string, string>;
+/**
+ * Fetches vendor-site documents exactly as a live build does.
+ *
+ * Shared with the curation verifier so both ask a vendor the same question: a
+ * verifier with its own headers reports sites healthy that the build then fails
+ * to resolve.
+ *
+ * `deadline` optionally bounds one product's whole resolution. The per-request
+ * ceiling is always created fresh inside each fetch, so a caller that passes a
+ * deadline — or shares one — can never hand later requests an already-expired
+ * signal.
+ */
+export declare function createSiteIconFetcher(deadline?: AbortSignal): SiteIconFetcher;
+/** Ceiling for a single product-site request during icon discovery. */
+export declare const SITE_FETCH_TIMEOUT_MS = 15000;
+/**
+ * Read one GitHub repository tarball into path -> bytes.
+ *
+ * GitHub wraps every entry in a single top-level `<repo>-<sha>/` directory,
+ * which is stripped so the keys match the tree API's repository-relative
+ * paths. Only regular files are taken: directories, symlinks, hardlinks and
+ * the `pax_global_header` record are skipped, so a link can never be
+ * materialized as content. Every remaining path goes through
+ * `safeRelativePath`, so an archive that tries to escape the repository is
+ * rejected rather than partially trusted.
+ */
+export declare function readArchiveFiles(archive: Uint8Array, policy: CatalogPolicy): Promise<Map<string, Uint8Array>>;
+export declare class NetworkSnapshotLoader implements SnapshotLoader {
+    #private;
+    constructor(policy: CatalogPolicy);
+    load(repositoryUrl: string, commitSha: string, pluginSubdirectory: string): Promise<Snapshot>;
+}
+export declare class FixtureSnapshotLoader implements SnapshotLoader {
+    #private;
+    constructor(root: string, sources: readonly SourceConfig[]);
+    load(repositoryUrl: string, _commitSha: string, pluginSubdirectory: string): Promise<Snapshot>;
+}
+export declare class DirectorySnapshotLoader implements SnapshotLoader {
+    load(_repositoryUrl: string, _commitSha: string, pluginSubdirectory: string): Promise<Snapshot>;
+}
+export declare function snapshotFromDirectory(root: string, pluginSubdirectory: string): Promise<Snapshot>;
+export {};