@adea-ai/plugins 1.0.0

package/dist/index.js

@@ -0,0 +1,1877 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { Readable } from 'node:stream';
+import { createGunzip } from 'node:zlib';
+import { extract } from 'tar-stream';
+import { CatalogSchema, HarnessSchema, SourcesLockSchema, PluginSchema, } from './schema.js';
+import { canonicalRepositoryUrl, parseJsonDocument, parseMarketplaceManifest, safeRelativePath, } from './sources.js';
+import { buildConsumerIndex, CATALOG_INDEX_ARTIFACT, iconCoverage, } from './consumer-index.js';
+import { iconAssetName, iconOverrideFor, inspectIconBytes, selectIconPath, } from './icons.js';
+import { stageIconBytes } from './icon-mirror.js';
+import { isVendorHomepage, resolveSiteIcon, } from './site-icons.js';
+import { normalizeDisplayName } from './display-name.js';
+import { immutableAssetUrl } from './publication.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 const CATALOG_CONTRACT_VERSION = 'adea-catalog/3';
+const DEFAULT_POLICY = {
+    allowedRepositoryProtocols: ['https:'],
+    allowedRepositoryHosts: ['github.com', 'www.github.com'],
+    maxFilesPerPlugin: 4096,
+    maxBytesPerPlugin: 50 * 1024 * 1024,
+    maxFileBytes: 5 * 1024 * 1024,
+    maxMarketplacePlugins: 4096,
+    denyExecutableLifecycleScripts: true,
+    publishRequiresCompleteContent: false,
+    sensitiveCapabilityTypes: [
+        'mcp-server',
+        'connector',
+        'hook',
+        'browser',
+        'scheduled-task',
+        'executable',
+    ],
+};
+export function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    const object = value;
+    return `{${Object.keys(object)
+        .toSorted()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key])}`)
+        .join(',')}}`;
+}
+export function digest(value) {
+    return `sha256:${createHash('sha256').update(canonicalJson(value)).digest('hex')}`;
+}
+export function bytesDigest(files) {
+    const hash = createHash('sha256');
+    for (const [path, bytes] of [...files.entries()].toSorted(([left], [right]) => left.localeCompare(right))) {
+        hash.update(`${path.length}:${path}:${bytes.byteLength}:`);
+        hash.update(bytes);
+    }
+    return `sha256:${hash.digest('hex')}`;
+}
+export function stablePluginId(sourceId, upstreamName) {
+    return `plugin:${slug(sourceId)}:${slug(upstreamName)}`;
+}
+export function stableReleaseId(repositoryUrl, subdirectory, commitSha, contentDigest) {
+    return `release:${digest({ repositoryUrl, subdirectory, commitSha, contentDigest }).slice('sha256:'.length)}`;
+}
+export function normalizeCategory(value, map) {
+    const key = value.trim().toLocaleLowerCase();
+    return map.aliases[key] ?? (slug(key) || map.fallback);
+}
+export function productGroupingKey(name, aliases) {
+    const key = name.trim().toLocaleLowerCase();
+    return aliases.aliases[key] ?? slug(key);
+}
+export async function synchronize(input) {
+    const mode = input.mode ?? 'live';
+    const configs = input.sources.filter((source) => !input.sourceId || source.sourceId === input.sourceId);
+    if (configs.length === 0)
+        throw new Error(`SOURCE_NOT_FOUND: ${input.sourceId ?? 'none'}`);
+    const lockToUse = input.fromLock ?? input.existingLock;
+    const resolved = await mapWithConcurrency(configs, 4, (config) => resolveSource(config, mode, input.fixtureRoot, lockToUse, input.fromLock !== undefined));
+    const sourceHeads = resolved.map(({ config, commitSha }) => ({
+        sourceId: config.sourceId,
+        commitSha,
+    }));
+    const unchanged = input.fromLock === undefined &&
+        input.forceRebuild !== true &&
+        input.existingLock !== undefined &&
+        resolved.length === input.existingLock.sources.length &&
+        resolved.every((source) => {
+            const previous = input.existingLock?.sources.find((entry) => entry.sourceId === source.config.sourceId);
+            if (!previous)
+                return false;
+            return (previous.resolvedCommitSha === source.commitSha &&
+                previous.sourceManifestDigest === source.manifestDigest &&
+                digest(previous.pluginPins) === digest(source.pluginPins));
+        });
+    if (unchanged) {
+        return {
+            changed: false,
+            dryRun: input.dryRun ?? false,
+            sourceHeads,
+            changeReport: {
+                schemaVersion: 1,
+                changedSources: [],
+                addedPlugins: [],
+                removedPlugins: [],
+                changedPlugins: [],
+                permissionSensitiveChanges: [],
+                skippedPlugins: [],
+                contentResolution: input.metadataOnly ? 'metadata-only' : 'complete',
+            },
+        };
+    }
+    const buildResult = await buildCatalogInternal({
+        resolvedSources: resolved,
+        categoryMap: input.categoryMap,
+        ...(input.productCategories ? { productCategories: input.productCategories } : {}),
+        ...(input.leading ? { leading: input.leading } : {}),
+        ...(input.productIconOverrides ? { productIconOverrides: input.productIconOverrides } : {}),
+        ...(input.iconAssetsDirectory ? { iconAssetsDirectory: input.iconAssetsDirectory } : {}),
+        productAliases: input.productAliases,
+        policy: input.policy,
+        metadataOnly: input.metadataOnly ?? false,
+        snapshotLoader: input.snapshotLoader ??
+            (mode === 'offline'
+                ? new FixtureSnapshotLoader(input.fixtureRoot ?? 'fixtures', configs)
+                : new NetworkSnapshotLoader(input.policy)),
+        resolveExternalRefs: mode === 'live',
+        ...(input.transformRelease ? { transformRelease: input.transformRelease } : {}),
+    });
+    const catalog = buildResult.catalog;
+    const lock = createSourcesLock(resolved);
+    const artifacts = createArtifacts(orderLeadingPlugins(catalog, input.leading), lock, {
+        ...(input.leading ? { leading: input.leading } : {}),
+        ...(input.topCount !== undefined ? { topCount: input.topCount } : {}),
+        ...(input.productPreference ? { productPreference: input.productPreference } : {}),
+        ...(input.publicationRepositoryUrl
+            ? { publicationRepositoryUrl: input.publicationRepositoryUrl }
+            : {}),
+        ...(input.publicationAssetsBaseUrl
+            ? { publicationAssetsBaseUrl: input.publicationAssetsBaseUrl }
+            : {}),
+        ...(input.publicationCatalogsBaseUrl
+            ? { publicationCatalogsBaseUrl: input.publicationCatalogsBaseUrl }
+            : {}),
+        curationDiagnostics: (input.mode ?? 'live') !== 'offline',
+    });
+    verifyArtifacts(artifacts);
+    const report = createChangeReport(catalog, lock, input.existingLock, input.existingCatalog, buildResult.skippedPlugins);
+    if (input.policy.publishRequiresCompleteContent && input.metadataOnly) {
+        throw new Error('CATALOG_CONTENT_INCOMPLETE: publication requires complete content');
+    }
+    return {
+        changed: true,
+        dryRun: input.dryRun ?? false,
+        sourceHeads,
+        catalog,
+        lock,
+        artifacts,
+        changeReport: report,
+    };
+}
+export async function buildCatalog(input) {
+    return (await buildCatalogInternal({
+        resolvedSources: input.resolvedSources,
+        categoryMap: input.categoryMap,
+        productAliases: input.productAliases,
+        policy: input.policy ?? DEFAULT_POLICY,
+        metadataOnly: input.metadataOnly ?? false,
+        snapshotLoader: input.snapshotLoader,
+        resolveExternalRefs: input.resolveExternalRefs ?? false,
+        ...(input.transformRelease ? { transformRelease: input.transformRelease } : {}),
+        ...(input.productCategories ? { productCategories: input.productCategories } : {}),
+        ...(input.leading ? { leading: input.leading } : {}),
+        ...(input.productIconOverrides ? { productIconOverrides: input.productIconOverrides } : {}),
+    })).catalog;
+}
+async function buildCatalogInternal(input) {
+    const policy = input.policy ?? DEFAULT_POLICY;
+    for (const source of input.resolvedSources) {
+        assertRepositoryAllowed(source.config.repositoryUrl, policy);
+        for (const entry of source.parsed.entries) {
+            if (entry.source.kind === 'git')
+                assertRepositoryAllowed(entry.source.repositoryUrl, policy);
+        }
+    }
+    const sourceRecords = input.resolvedSources
+        .map(({ config, commitSha, retrievedAt, manifestDigest }) => ({
+        sourceId: config.sourceId,
+        displayName: config.displayName,
+        repositoryUrl: canonicalRepositoryUrl(config.repositoryUrl),
+        marketplaceDialect: config.marketplaceDialect,
+        manifestPath: config.manifestPath,
+        defaultBranch: config.defaultBranch,
+        resolvedCommitSha: commitSha,
+        retrievalTimestamp: retrievedAt,
+        trustClassification: config.trustClassification,
+        sourceManifestDigest: manifestDigest,
+        synchronizationStatus: 'synchronized',
+    }))
+        .toSorted((left, right) => left.sourceId.localeCompare(right.sourceId));
+    let plugins = [];
+    let skippedPlugins = [];
+    for (const source of input.resolvedSources) {
+        if (source.parsed.entries.length > policy.maxMarketplacePlugins)
+            throw new Error('MARKETPLACE_TOO_MANY_PLUGINS');
+        const normalized = await mapWithConcurrency(source.parsed.entries, 8, async (entry) => {
+            try {
+                const plugin = await normalizePlugin({
+                    source,
+                    entry,
+                    categoryMap: input.categoryMap,
+                    ...(input.productCategories ? { productCategories: input.productCategories } : {}),
+                    productAliases: input.productAliases,
+                    ...(input.productIconOverrides
+                        ? { productIconOverrides: input.productIconOverrides }
+                        : {}),
+                    ...(input.iconAssetsDirectory ? { iconAssetsDirectory: input.iconAssetsDirectory } : {}),
+                    policy,
+                    metadataOnly: input.metadataOnly ?? false,
+                    snapshotLoader: input.snapshotLoader,
+                    resolveExternalRefs: input.resolveExternalRefs ?? true,
+                    ...(input.transformRelease ? { transformRelease: input.transformRelease } : {}),
+                });
+                try {
+                    return { plugin: PluginSchema.parse(plugin) };
+                }
+                catch {
+                    throw new PluginSafetyError('PLUGIN_SCHEMA_INVALID', []);
+                }
+            }
+            catch (error) {
+                const skipped = createSkippedPlugin(source, entry, error);
+                if (!skipped)
+                    throw error;
+                return { skipped };
+            }
+        });
+        const sourcePlugins = [];
+        const sourceSkipped = [];
+        for (const result of normalized) {
+            if (result.plugin)
+                sourcePlugins.push(result.plugin);
+            if (result.skipped)
+                sourceSkipped.push(result.skipped);
+        }
+        const weatherSkips = sourceSkipped.filter((skipped) => UPSTREAM_WEATHER_SKIP_CODES.has(skipped.reasonCode));
+        if (source.parsed.entries.length > 0 && weatherSkips.length === source.parsed.entries.length)
+            throw new PluginSafetyError('PLUGIN_SOURCE_UNAVAILABLE', [
+                canonicalRepositoryUrl(source.config.repositoryUrl),
+            ]);
+        for (const plugin of sourcePlugins)
+            plugins.push(plugin);
+        for (const skipped of sourceSkipped)
+            skippedPlugins.push(skipped);
+    }
+    plugins = plugins.toSorted((left, right) => left.pluginId.localeCompare(right.pluginId));
+    skippedPlugins = skippedPlugins.toSorted((left, right) => left.pluginId.localeCompare(right.pluginId) ||
+        left.reasonCode.localeCompare(right.reasonCode) ||
+        left.paths.join('\0').localeCompare(right.paths.join('\0')));
+    const body = {
+        schemaVersion: 1,
+        generatedAt: sourceRecords
+            .map((s) => s.retrievalTimestamp)
+            .toSorted()
+            .at(-1) ?? new Date(0).toISOString(),
+        sources: sourceRecords,
+        plugins,
+    };
+    return {
+        catalog: CatalogSchema.parse({
+            ...body,
+            catalogId: `catalog:${digest(body).slice('sha256:'.length)}`,
+        }),
+        skippedPlugins,
+    };
+}
+class PluginSafetyError extends Error {
+    reasonCode;
+    paths;
+    constructor(reasonCode, paths) {
+        super(`${reasonCode}${paths.length > 0 ? `: ${paths.join(',')}` : ''}`);
+        this.reasonCode = reasonCode;
+        this.paths = paths;
+        this.name = 'PluginSafetyError';
+    }
+}
+const pluginSkipReasons = {
+    GIT_SUBMODULE_UNSUPPORTED: 'The plugin contains a Git submodule, so the catalog excludes it rather than traversing an unpinned repository boundary.',
+    PLUGIN_FILE_TOO_LARGE: 'The plugin contains a file over the configured size limit, so the catalog excludes the plugin before publication.',
+    PLUGIN_FILE_UNAVAILABLE: 'A plugin file could not be fetched from upstream after retries, so the catalog excludes the plugin rather than publishing partial content.',
+    PLUGIN_MANIFEST_INVALID: 'The plugin manifest is malformed, so the catalog excludes the plugin before consuming its metadata.',
+    PLUGIN_PATH_NOT_FOUND: 'The declared plugin path does not exist at the pinned commit, so the catalog excludes the plugin.',
+    PLUGIN_SCHEMA_INVALID: 'The normalized plugin record exceeds the published catalog schema, so the catalog excludes it before publication.',
+    PLUGIN_SIZE_POLICY: 'The plugin exceeds the configured size policy, so the catalog excludes it before publication.',
+    PLUGIN_SOURCE_UNAVAILABLE: 'The plugin repository tree could not be fetched from upstream after retries, so the catalog excludes the plugin rather than publishing partial content.',
+    PLUGIN_TOO_LARGE: 'The plugin exceeds the configured aggregate size limit, so the catalog excludes it before publication.',
+    PLUGIN_TOO_MANY_FILES: 'The plugin exceeds the configured file-count limit, so the catalog excludes it before publication.',
+    SNAPSHOT_PATH_INVALID: 'The plugin snapshot contains an unsafe path, so the catalog excludes it rather than allowing repository escape.',
+    SYMLINK_ESCAPE: 'The plugin snapshot contains symlinks; symlinks are never followed, so the catalog excludes the plugin.',
+};
+function createSkippedPlugin(source, entry, error) {
+    const parsed = error instanceof PluginSafetyError
+        ? { reasonCode: error.reasonCode, paths: error.paths }
+        : parsePluginSafetyError(error);
+    if (!parsed)
+        return undefined;
+    return {
+        sourceId: source.config.sourceId,
+        pluginId: stablePluginId(source.config.sourceId, entry.name),
+        pluginName: entry.name,
+        reasonCode: parsed.reasonCode,
+        securityReason: pluginSkipReasons[parsed.reasonCode],
+        incompleteContent: true,
+        paths: [...new Set(parsed.paths)].toSorted(),
+    };
+}
+function parsePluginSafetyError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const match = /^([A-Z_]+)(?::\s?(.*))?$/.exec(message);
+    if (!match)
+        return undefined;
+    const reasonCode = match[1];
+    if (!(reasonCode in pluginSkipReasons))
+        return undefined;
+    return {
+        reasonCode,
+        paths: match[2]
+            ? match[2]
+                .split(',')
+                .map((path) => path.trim())
+                .filter(Boolean)
+            : [],
+    };
+}
+async function normalizePlugin(input) {
+    const { source, entry, policy } = input;
+    const resolved = await resolvePluginSource(entry.name, entry.source, source, input.resolveExternalRefs);
+    const snapshot = input.metadataOnly
+        ? { files: new Map(), symlinks: [] }
+        : await input.snapshotLoader.load(resolved.repositoryUrl, resolved.commitSha, resolved.subdirectory);
+    if (snapshot.symlinks.length > 0)
+        throw new PluginSafetyError('SYMLINK_ESCAPE', [...snapshot.symlinks].toSorted());
+    validateSnapshot(snapshot, policy, entry.name);
+    const contentDigest = input.metadataOnly
+        ? digest({
+            repositoryUrl: resolved.repositoryUrl,
+            subdirectory: resolved.subdirectory,
+            commitSha: resolved.commitSha,
+            entryDigest: entry.entryDigest,
+        })
+        : bytesDigest(snapshot.files);
+    const pluginManifest = findPluginManifest(snapshot, input.transformRelease !== undefined);
+    const manifestDigest = pluginManifest ? digest(pluginManifest.metadata) : entry.entryDigest;
+    const capabilities = classifyCapabilities(snapshot.files, pluginManifest?.metadata);
+    const iconOverride = iconOverrideFor(input.productIconOverrides, productGroupingKey(entry.name, input.productAliases));
+    const contentIcon = resolveContentIcon(snapshot, iconOverride, input.metadataOnly ?? false);
+    const favicon = contentIcon === undefined
+        ? await resolveFavicon({
+            entry,
+            iconOverride,
+            metadataOnly: input.metadataOnly ?? false,
+            live: input.resolveExternalRefs === true,
+        })
+        : undefined;
+    // Stage the mark while its bytes are in hand. Publication then needs no
+    // re-fetch, and a site icon cannot drift between resolution and release.
+    if (input.iconAssetsDirectory) {
+        const staged = contentIcon
+            ? snapshot.files.get(contentIcon.kind === 'content' ? contentIcon.path : '')
+            : favicon?.bytes;
+        if (staged)
+            await stageIconBytes(input.iconAssetsDirectory, iconAssetName(contentIcon ? contentIcon.digest : favicon.digest, contentIcon ? contentIcon.contentType : favicon.contentType), staged);
+    }
+    const releaseId = stableReleaseId(resolved.repositoryUrl, resolved.subdirectory, resolved.commitSha, contentDigest);
+    const originalRelease = createRelease({
+        source,
+        entry,
+        resolved,
+        contentDigest,
+        manifestDigest,
+        capabilities,
+        snapshot,
+        ...(pluginManifest ? { pluginManifest } : {}),
+        releaseId,
+        ...(contentIcon ? { contentIcon } : {}),
+        ...(favicon ? { favicon } : {}),
+        metadataOnly: input.metadataOnly,
+    });
+    const release = input.transformRelease && !input.metadataOnly
+        ? input.transformRelease(originalRelease, snapshot, entry.name)
+        : originalRelease;
+    const compatibility = createCompatibility(source.config.marketplaceDialect, capabilities, policy);
+    const security = createSecurity(capabilities, policy, input.metadataOnly);
+    const normalizedCategories = entry.categories.map((category) => normalizeCategory(category, input.categoryMap));
+    const productCategory = input.productCategories?.[entry.name];
+    const categories = [
+        ...new Set((productCategory
+            ? [productCategory, ...normalizedCategories.filter((category) => category !== 'other')]
+            : normalizedCategories.length > 0
+                ? normalizedCategories
+                : [input.categoryMap.fallback]).filter(Boolean)),
+    ].toSorted();
+    // The name a list renders: marketplace manifests are inconsistent (`Gmail`
+    // beside `zapier` beside `aws-agents-for-devsecops`), so the catalog
+    // publishes the written form once and every consumer shows the same thing.
+    const displayName = normalizeDisplayName(entry.displayName ?? pluginManifest?.displayName ?? entry.name);
+    const authors = entry.authors.length > 0
+        ? [...entry.authors]
+        : source.parsed.owner.length > 0
+            ? [...source.parsed.owner]
+            : ['Unknown'];
+    const keywords = [...new Set([...entry.keywords, ...entry.name.split(/[-_\s]+/g), ...categories])]
+        .filter(Boolean)
+        .toSorted();
+    const provenance = {
+        sourceId: source.config.sourceId,
+        repositoryUrl: canonicalRepositoryUrl(source.config.repositoryUrl),
+        manifestPath: source.config.manifestPath,
+        pluginSubdirectory: resolved.subdirectory || '.',
+        resolvedCommitSha: resolved.commitSha,
+        sourceManifestDigest: source.manifestDigest,
+        upstreamEntryDigest: entry.entryDigest,
+    };
+    return {
+        pluginId: stablePluginId(source.config.sourceId, entry.name),
+        displayName,
+        description: entry.description || pluginManifest?.description || '',
+        productGroupingKey: productGroupingKey(entry.name, input.productAliases),
+        categories,
+        keywords,
+        authors,
+        ...(entry.homepage ? { homepage: entry.homepage } : {}),
+        icons: entry.icons.length > 0 ? [...entry.icons].toSorted() : (pluginManifest?.icons ?? []),
+        sourceId: source.config.sourceId,
+        upstreamPluginName: entry.name,
+        currentReleaseId: releaseId,
+        availableReleases: [release],
+        capabilitySummary: capabilitySummary(capabilities),
+        harnessCompatibility: compatibility,
+        license: findLicense(entry, pluginManifest?.metadata),
+        provenance,
+        securityClassification: security,
+    };
+}
+function createRelease(input) {
+    const requiredCredentials = new Set();
+    const auth = input.entry.policy.authentication;
+    if (typeof auth === 'string' && auth !== 'NONE' && auth !== 'DISABLED')
+        requiredCredentials.add('authentication');
+    for (const value of arrayValue(input.entry.raw.requiredCredentials))
+        if (typeof value === 'string')
+            requiredCredentials.add(value);
+    const requiredConnectors = [
+        ...new Set(arrayValue(input.entry.raw.connectors).filter(isString)),
+    ].toSorted();
+    const permissionSensitiveChanges = input.capabilities
+        .filter((capability) => capability.securityImpact === 'sensitive')
+        .map((capability) => capability.type)
+        .toSorted();
+    const metadata = {
+        catalogContract: CATALOG_CONTRACT_VERSION,
+        marketplaceEntry: input.entry.raw,
+        ...(input.pluginManifest ? { pluginManifest: input.pluginManifest.metadata } : {}),
+        sourceDialect: input.source.config.marketplaceDialect,
+    };
+    const version = input.pluginManifest?.version ?? stringValue(input.entry.raw.version);
+    return {
+        releaseId: input.releaseId,
+        ...(version ? { upstreamVersion: version } : {}),
+        resolvedRepositoryUrl: input.resolved.repositoryUrl,
+        resolvedCommitSha: input.resolved.commitSha,
+        pluginSubdirectory: input.resolved.subdirectory || '.',
+        canonicalContentDigest: input.contentDigest,
+        manifestDigest: input.manifestDigest,
+        contentResolution: input.metadataOnly ? 'metadata-only' : 'complete',
+        releaseMetadata: metadata,
+        capabilities: [...input.capabilities].toSorted((left, right) => left.type.localeCompare(right.type) || left.name.localeCompare(right.name)),
+        requiredConnectors,
+        requiredCredentials: [...requiredCredentials].toSorted(),
+        permissionSensitiveChanges: [...new Set(permissionSensitiveChanges)],
+        fileIndex: [...input.snapshot.files.keys()].toSorted(),
+        publicationTimestamp: input.source.retrievedAt,
+        ...assembleIcon(input),
+    };
+}
+/**
+ * Resolves the product site's icon, for a plugin whose content ships no mark.
+ *
+ * Only a live build with complete content attempts this: a metadata-only or
+ * offline run must not reach out to vendor sites, and neither may a product the
+ * curator has already decided about.
+ */
+async function resolveFavicon(input) {
+    if (!input.live || input.metadataOnly)
+        return undefined;
+    if (input.iconOverride?.forced === null || input.iconOverride?.forced)
+        return undefined;
+    const homepage = input.iconOverride?.site ?? input.entry.homepage;
+    if (!isVendorHomepage(homepage))
+        return undefined;
+    // Bound both fetches: a vendor site that never answers must not stall a
+    // catalogue build. A timeout simply leaves the product on its monogram.
+    const signal = AbortSignal.timeout(SITE_FETCH_TIMEOUT_MS);
+    const resolved = await resolveSiteIcon(homepage, createSiteIconFetcher(signal));
+    return 'contentType' in resolved ? resolved : undefined;
+}
+/**
+ * Picks and vets the brand mark for a release.
+ *
+ * A file in the plugin's own content is preferred, because it is the mark the
+ * vendor ships with the plugin. When the content has none, a live build falls
+ * back to the declared homepage's site icon: many plugins are a thin wrapper
+ * over a vendor API and point at the vendor's site rather than shipping a logo.
+ * Whatever the source, an icon that fails inspection is absent rather than
+ * advertised: the catalog never publishes content it would refuse to mirror.
+ */
+function resolveContentIcon(snapshot, iconOverride, metadataOnly) {
+    if (metadataOnly || snapshot.files.size === 0)
+        return undefined;
+    // A curator override wins over every rule, including "publish no icon".
+    if (iconOverride?.forced === null)
+        return undefined;
+    const files = [...snapshot.files.keys()].toSorted();
+    const forced = iconOverride?.forced;
+    if (forced && !files.includes(forced))
+        return undefined;
+    const path = forced ?? selectIconPath(files);
+    if (!path)
+        return undefined;
+    const bytes = snapshot.files.get(path);
+    if (!bytes)
+        return undefined;
+    const inspected = inspectIconBytes(bytes);
+    if (!('contentType' in inspected))
+        return undefined;
+    return {
+        kind: 'content',
+        path,
+        contentType: inspected.contentType,
+        digest: byteDigest(bytes),
+        bytes: bytes.byteLength,
+    };
+}
+/** Assembles the release icon from whichever source produced one. */
+function assembleIcon(input) {
+    if (input.contentIcon)
+        return { icon: input.contentIcon };
+    if (input.favicon)
+        return {
+            icon: {
+                kind: 'favicon',
+                url: input.favicon.url,
+                homepage: input.favicon.homepage,
+                contentType: input.favicon.contentType,
+                digest: input.favicon.digest,
+                bytes: input.favicon.bytes.byteLength,
+            },
+        };
+    return {};
+}
+/** SHA-256 of a single byte buffer, in the catalog's digest format. */
+export function byteDigest(bytes) {
+    return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+async function resolvePluginSource(pluginName, spec, source, resolveExternalRefs) {
+    if (spec.kind === 'local')
+        return {
+            repositoryUrl: canonicalRepositoryUrl(source.config.repositoryUrl),
+            subdirectory: spec.path,
+            commitSha: source.commitSha,
+        };
+    const canonicalUrl = canonicalRepositoryUrl(spec.repositoryUrl);
+    const pin = source.pluginPins.find((candidate) => candidate.pluginName === pluginName &&
+        candidate.repositoryUrl === canonicalUrl &&
+        candidate.pluginSubdirectory === spec.subdirectory);
+    const commitSha = pin?.resolvedCommitSha ??
+        spec.sha ??
+        (resolveExternalRefs
+            ? await resolveGitRef(spec.repositoryUrl, spec.ref?.startsWith('refs/') ? spec.ref : `refs/heads/${spec.ref ?? 'main'}`)
+            : source.commitSha);
+    return {
+        repositoryUrl: canonicalUrl,
+        subdirectory: pin?.pluginSubdirectory ?? spec.subdirectory,
+        commitSha,
+    };
+}
+function validateSnapshot(snapshot, policy, pluginName) {
+    if (snapshot.files.size > policy.maxFilesPerPlugin)
+        throw new PluginSafetyError('PLUGIN_TOO_MANY_FILES', [pluginName]);
+    let total = 0;
+    for (const [path, bytes] of snapshot.files) {
+        try {
+            safeRelativePath(path, 'SNAPSHOT_PATH_INVALID');
+        }
+        catch {
+            throw new PluginSafetyError('SNAPSHOT_PATH_INVALID', [path]);
+        }
+        if (bytes.byteLength > policy.maxFileBytes)
+            throw new PluginSafetyError('PLUGIN_FILE_TOO_LARGE', [path]);
+        total += bytes.byteLength;
+    }
+    if (total > policy.maxBytesPerPlugin)
+        throw new PluginSafetyError('PLUGIN_TOO_LARGE', [pluginName]);
+}
+function assertRepositoryAllowed(repositoryUrl, policy) {
+    const parsed = new URL(canonicalRepositoryUrl(repositoryUrl));
+    if (!policy.allowedRepositoryProtocols.includes(parsed.protocol))
+        throw new Error(`GIT_PROTOCOL_POLICY: ${parsed.protocol}`);
+    if (!policy.allowedRepositoryHosts.includes(parsed.hostname.toLowerCase()))
+        throw new Error(`GIT_HOST_POLICY: ${parsed.hostname}`);
+}
+function findPluginManifest(snapshot, preferRoot = false) {
+    const candidates = [...snapshot.files.keys()]
+        .filter((path) => {
+        const lower = path.toLocaleLowerCase();
+        return lower === 'plugin.json' || lower.endsWith('/plugin.json') || lower === 'package.json';
+    })
+        .toSorted((left, right) => manifestRank(left) - manifestRank(right) || left.localeCompare(right));
+    const path = preferRoot && snapshot.files.has('plugin.json') ? 'plugin.json' : candidates[0];
+    if (!path)
+        return undefined;
+    try {
+        const bytes = snapshot.files.get(path);
+        if (!bytes)
+            return undefined;
+        const metadata = parseJsonDocument(new TextDecoder().decode(bytes));
+        return {
+            metadata,
+            ...((stringValue(metadata.displayName) ?? stringValue(metadata.name))
+                ? { displayName: stringValue(metadata.displayName) ?? stringValue(metadata.name) }
+                : {}),
+            ...(stringValue(metadata.description)
+                ? { description: stringValue(metadata.description) }
+                : {}),
+            ...(stringValue(metadata.version) ? { version: stringValue(metadata.version) } : {}),
+            icons: [metadata.icon, ...(Array.isArray(metadata.icons) ? metadata.icons : [])]
+                .filter(isString)
+                .toSorted(),
+        };
+    }
+    catch {
+        throw new PluginSafetyError('PLUGIN_MANIFEST_INVALID', [path]);
+    }
+}
+function manifestRank(path) {
+    const lower = path.toLocaleLowerCase();
+    if (lower.endsWith('/.claude-plugin/plugin.json'))
+        return 0;
+    if (lower.endsWith('/.cursor-plugin/plugin.json'))
+        return 1;
+    if (lower.endsWith('/.agents/plugin.json'))
+        return 2;
+    return lower === 'plugin.json' ? 3 : 4;
+}
+export function classifyCapabilities(files, metadata) {
+    const groups = new Map();
+    const add = (type, path) => groups.set(type, [...(groups.get(type) ?? []), path]);
+    for (const path of files.keys()) {
+        const lower = path.toLocaleLowerCase();
+        const file = basename(lower);
+        if (file === 'skill.md' || lower.includes('/skills/'))
+            add('skill', path);
+        if (file === '.mcp.json' || file === 'mcp.json' || lower.includes('/mcp-servers/'))
+            add('mcp-server', path);
+        if (lower.includes('/commands/') || lower.startsWith('commands/'))
+            add('command', path);
+        if (lower.includes('/agents/') || lower.startsWith('agents/') || lower.includes('/subagents/'))
+            add('agent', path);
+        if (lower.includes('/hooks/') || lower.startsWith('hooks/') || file === 'hooks.json')
+            add('hook', path);
+        if (lower.includes('/rules/') ||
+            lower.startsWith('rules/') ||
+            file === 'agents.md' ||
+            file === 'claude.md' ||
+            lower.includes('.cursor/rules/'))
+            add('rule', path);
+        if (lower.includes('browser') || lower.includes('playwright') || lower.includes('chrome'))
+            add('browser', path);
+        if (lower.includes('/schedule') || lower.includes('/cron') || file.includes('schedule'))
+            add('scheduled-task', path);
+        if (lower.includes('/ui/') || lower.startsWith('ui/') || lower.includes('/components/'))
+            add('ui-component', path);
+        if (lower.startsWith('bin/') ||
+            lower.startsWith('scripts/') ||
+            /\.(sh|bash|py|exe|bin)$/.test(file))
+            add('executable', path);
+    }
+    if (metadata && (metadata.mcpServers !== undefined || metadata.mcp !== undefined))
+        add('mcp-server', 'plugin-manifest');
+    if (metadata && (metadata.hooks !== undefined || metadata.hook !== undefined))
+        add('hook', 'plugin-manifest');
+    if (groups.size === 0)
+        groups.set('unknown', ['plugin-root']);
+    return [...groups.entries()].map(([type, paths]) => ({
+        type: type,
+        name: type,
+        paths: [...new Set(paths)].toSorted(),
+        metadata: {},
+        securityImpact: [
+            'mcp-server',
+            'connector',
+            'hook',
+            'browser',
+            'scheduled-task',
+            'executable',
+        ].includes(type)
+            ? 'sensitive'
+            : 'none',
+    }));
+}
+function capabilitySummary(capabilities) {
+    const summary = {};
+    for (const capability of capabilities)
+        summary[capability.type] = capability.paths.length;
+    return summary;
+}
+export function createCompatibility(dialect, capabilities, policy = DEFAULT_POLICY) {
+    const types = [...new Set(capabilities.map((capability) => capability.type))].toSorted();
+    const sensitive = types.filter((type) => policy.sensitiveCapabilityTypes.includes(type));
+    const make = (status, reasons) => ({
+        status,
+        reasons: [...new Set(reasons)].toSorted(),
+        responsibleCapabilities: types,
+    });
+    const result = {};
+    for (const harness of HarnessSchema.options) {
+        const native = (harness === 'claude-code' && dialect === 'claude') ||
+            (harness === 'cursor' && dialect === 'cursor') ||
+            (harness === 'codex' && dialect === 'openai');
+        if (types.includes('executable'))
+            result[harness] = make('unsupported', [
+                'Executable components require harness-specific execution authority.',
+            ]);
+        else if (types.includes('unknown'))
+            result[harness] = make('unknown', [
+                'The plugin content was not classified into a supported component type.',
+            ]);
+        else if (native && sensitive.length === 0)
+            result[harness] = make('native', [
+                `The ${dialect} marketplace dialect matches the ${harness} harness.`,
+            ]);
+        else if (sensitive.length > 0 && ['pi', 'hermes', 'opencode'].includes(harness))
+            result[harness] = make('partially-supported', [
+                `Sensitive capabilities require ${harness} policy and runtime review.`,
+                ...sensitive.map((type) => `Capability ${type} is not granted by this catalog.`),
+            ]);
+        else if (types.every((type) => ['skill', 'rule', 'mcp-server', 'command', 'agent'].includes(type)))
+            result[harness] = make(native ? 'native' : 'portable', native
+                ? [`The ${dialect} marketplace dialect matches the ${harness} harness.`]
+                : ['Files can be copied or translated into the harness layout.']);
+        else
+            result[harness] = make('requires-translation', [
+                'One or more capabilities need a harness-specific projection.',
+            ]);
+    }
+    return result;
+}
+function createSecurity(capabilities, policy, metadataOnly) {
+    const sensitive = [
+        ...new Set(capabilities
+            .filter((capability) => policy.sensitiveCapabilityTypes.includes(capability.type))
+            .map((capability) => capability.type)),
+    ].toSorted();
+    const reasons = sensitive.length > 0
+        ? sensitive.map((type) => `Contains ${type} capability metadata.`)
+        : metadataOnly
+            ? ['Content was not fetched in metadata-only mode.']
+            : ['No permission-sensitive executable capability was detected.'];
+    return {
+        level: sensitive.length > 0 ? 'sensitive' : metadataOnly ? 'review' : 'low',
+        reasons,
+        permissionSensitiveChanges: sensitive,
+        contentResolution: metadataOnly ? 'metadata-only' : 'complete',
+    };
+}
+function findLicense(entry, metadata) {
+    const candidate = stringValue(metadata?.license) ?? stringValue(entry.raw.license);
+    if (!candidate)
+        return { name: 'Unknown', source: 'unknown' };
+    return {
+        name: candidate,
+        ...(candidate.startsWith('http') ? { url: candidate } : {}),
+        source: metadata?.license !== undefined ? 'plugin-manifest' : 'marketplace-entry',
+    };
+}
+function createSourcesLock(sources) {
+    const entries = sources
+        .map((source) => ({
+        sourceId: source.config.sourceId,
+        repositoryUrl: canonicalRepositoryUrl(source.config.repositoryUrl),
+        defaultBranch: source.config.defaultBranch,
+        resolvedCommitSha: source.commitSha,
+        manifestPath: source.config.manifestPath,
+        marketplaceDialect: source.config.marketplaceDialect,
+        sourceManifestDigest: source.manifestDigest,
+        retrievedAt: source.retrievedAt,
+        synchronizationStatus: 'synchronized',
+        pluginPins: source.pluginPins.map((pin) => ({ ...pin })),
+    }))
+        .toSorted((left, right) => left.sourceId.localeCompare(right.sourceId));
+    const body = { schemaVersion: 1, sources: entries };
+    return SourcesLockSchema.parse({
+        ...body,
+        lockId: `lock:${digest(body).slice('sha256:'.length)}`,
+    });
+}
+/**
+ * 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 function orderLeadingPlugins(catalog, leading) {
+    if (!leading)
+        return catalog;
+    const leadRank = new Map();
+    for (const [category, names] of Object.entries(leading)) {
+        names.forEach((name, index) => {
+            const key = `${category}::${name}`;
+            if (!leadRank.has(key))
+                leadRank.set(key, index);
+        });
+    }
+    const rank = (plugin) => {
+        let best = Number.POSITIVE_INFINITY;
+        for (const category of plugin.categories) {
+            const value = leadRank.get(`${category}::${plugin.upstreamPluginName}`);
+            if (value !== undefined && value < best)
+                best = value;
+        }
+        return best;
+    };
+    return {
+        ...catalog,
+        plugins: catalog.plugins.toSorted((left, right) => rank(left) - rank(right)),
+    };
+}
+export function createArtifacts(catalog, lock, options = {}) {
+    const index = buildConsumerIndex({
+        catalog,
+        ...(options.leading ? { leading: options.leading } : {}),
+        ...(options.topCount !== undefined ? { topCount: options.topCount } : {}),
+        ...(options.productPreference ? { preference: options.productPreference } : {}),
+        ...(options.publicationRepositoryUrl
+            ? { publicationRepositoryUrl: options.publicationRepositoryUrl }
+            : {}),
+        ...(options.publicationAssetsBaseUrl
+            ? { publicationAssetsBaseUrl: options.publicationAssetsBaseUrl }
+            : {}),
+        ...(options.publicationCatalogsBaseUrl
+            ? { publicationCatalogsBaseUrl: options.publicationCatalogsBaseUrl }
+            : {}),
+    });
+    const summary = {
+        schemaVersion: 1,
+        catalogId: catalog.catalogId,
+        generatedAt: catalog.generatedAt,
+        sourceCount: catalog.sources.length,
+        pluginCount: catalog.plugins.length,
+        categories: [...new Set(catalog.plugins.flatMap((plugin) => plugin.categories))].toSorted(),
+        productGroups: [
+            ...new Set(catalog.plugins.map((plugin) => plugin.productGroupingKey)),
+        ].toSorted(),
+        search: catalog.plugins
+            .map((plugin) => ({
+            pluginId: plugin.pluginId,
+            text: `${plugin.displayName} ${plugin.description} ${plugin.keywords.join(' ')}`.trim(),
+        }))
+            .toSorted((left, right) => left.pluginId.localeCompare(right.pluginId)),
+    };
+    const compatibility = {
+        schemaVersion: 1,
+        catalogId: catalog.catalogId,
+        plugins: catalog.plugins.map((plugin) => ({
+            pluginId: plugin.pluginId,
+            harnessCompatibility: plugin.harnessCompatibility,
+        })),
+    };
+    // Navigation stays small and points at the shards a client then fetches:
+    // `shelf-*` for a default view, `category-*` for "view more", and
+    // `catalog-index.v1.json` for the complete product list.
+    const navigation = {
+        schemaVersion: 1,
+        catalogId: catalog.catalogId,
+        generatedAt: catalog.generatedAt,
+        topCount: index.topCount,
+        sourcePreference: index.sourcePreference,
+        counts: index.counts,
+        catalogIndexArtifact: CATALOG_INDEX_ARTIFACT,
+        iconCoverage: iconCoverage(index),
+        // The index URL rides in the navigation artifact so a client can fetch the
+        // browsing index from the publication it was told about, verify it against
+        // the digest in integrity.json, and never compose a URL or need this
+        // service to proxy it. Absent for an unpublished build.
+        ...(options.publicationCatalogsBaseUrl
+            ? {
+                catalogIndexUrl: `${options.publicationCatalogsBaseUrl}/${catalog.catalogId.slice('catalog:'.length)}/${CATALOG_INDEX_ARTIFACT}`,
+            }
+            : options.publicationAssetsBaseUrl
+                ? { catalogIndexUrl: `${options.publicationAssetsBaseUrl}/${CATALOG_INDEX_ARTIFACT}` }
+                : options.publicationRepositoryUrl
+                    ? {
+                        catalogIndexUrl: immutableAssetUrl(options.publicationRepositoryUrl, catalog.catalogId, CATALOG_INDEX_ARTIFACT),
+                    }
+                    : {}),
+        // Marks ride in the navigation artifact so a client that already receives it
+        // renders compiled brand marks without fetching the browsing index. Keys are
+        // sorted for a stable artifact.
+        brandMarks: Object.fromEntries(Object.keys(index.products)
+            .toSorted()
+            .flatMap((productKey) => {
+            const assetUrl = index.products[productKey]?.icon?.assetUrl;
+            return assetUrl ? [[productKey, assetUrl]] : [];
+        })),
+        categories: index.categories,
+        diagnostics: options.curationDiagnostics === false ? [] : index.diagnostics,
+    };
+    const shards = {
+        [CATALOG_INDEX_ARTIFACT]: json({
+            schemaVersion: 1,
+            catalogId: catalog.catalogId,
+            generatedAt: catalog.generatedAt,
+            topCount: index.topCount,
+            sourcePreference: index.sourcePreference,
+            counts: index.counts,
+            products: index.products,
+            categories: index.categories.map((category) => ({
+                category: category.category,
+                productCount: category.productCount,
+                productKeys: category.productKeys,
+            })),
+        }),
+    };
+    for (const category of index.categories) {
+        shards[category.shelfArtifact] = json({
+            schemaVersion: 1,
+            catalogId: catalog.catalogId,
+            category: category.category,
+            topCount: index.topCount,
+            products: category.topProductKeys.map((productKey) => index.products[productKey]),
+        });
+        shards[category.listArtifact] = json({
+            schemaVersion: 1,
+            catalogId: catalog.catalogId,
+            category: category.category,
+            productCount: category.productCount,
+            pluginCount: category.pluginCount,
+            products: category.productKeys.map((productKey) => index.products[productKey]),
+        });
+    }
+    const files = {
+        'catalog.v1.json': json(catalog),
+        'catalog-summary.v1.json': json(summary),
+        'sources.lock.json': json(lock),
+        'compatibility.v1.json': json(compatibility),
+        'categories.v1.json': json(navigation),
+        ...shards,
+    };
+    const integrityBody = {
+        schemaVersion: 1,
+        catalogId: catalog.catalogId,
+        // An artifact's digest is the canonical digest of its text, not a hash of
+        // the file bytes: consumers read the artifact as a string and compare it
+        // with `canonicalDigest`, so a checker hashing the raw bytes will disagree
+        // with every published release. Mirrored marks below are the byte case,
+        // because a client stores those bytes.
+        files: Object.fromEntries(Object.entries(files)
+            .toSorted()
+            .map(([name, content]) => [name, digest(content)])),
+        // Mirrored brand marks are published next to the artifacts, never inside
+        // them: the digest and size let a consumer or the release check verify the
+        // bytes it fetched without trusting the release listing.
+        assets: iconAssets(index),
+    };
+    return { ...files, 'integrity.json': json(integrityBody) };
+}
+/** Every mirrored icon in the catalog, deduplicated by asset name. */
+export function iconAssets(index) {
+    const assets = new Map();
+    for (const product of Object.values(index.products)) {
+        if (!product.icon)
+            continue;
+        assets.set(product.icon.asset, {
+            name: product.icon.asset,
+            digest: product.icon.digest,
+            bytes: product.icon.bytes,
+            contentType: product.icon.contentType,
+            kind: product.icon.kind,
+            origin: product.icon.kind === 'content' ? (product.icon.path ?? '') : (product.icon.url ?? ''),
+        });
+    }
+    return [...assets.values()].toSorted((left, right) => left.name.localeCompare(right.name));
+}
+export async function writeArtifacts(generatedDirectory, artifacts) {
+    const parent = dirname(generatedDirectory);
+    await fs.mkdir(parent, { recursive: true });
+    const temporary = await fs.mkdtemp(join(parent, '.catalog-'));
+    try {
+        for (const [name, content] of Object.entries(artifacts))
+            await fs.writeFile(join(temporary, name), content, 'utf8');
+        const backup = `${generatedDirectory}.previous`;
+        await fs.rm(backup, { recursive: true, force: true });
+        let movedExisting = false;
+        try {
+            await fs.rename(generatedDirectory, backup);
+            movedExisting = true;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        try {
+            await fs.rename(temporary, generatedDirectory);
+        }
+        catch (error) {
+            if (movedExisting)
+                await fs.rename(backup, generatedDirectory);
+            throw error;
+        }
+        if (movedExisting)
+            await fs.rm(backup, { recursive: true, force: true });
+    }
+    finally {
+        await fs.rm(temporary, { recursive: true, force: true });
+    }
+}
+export function verifyArtifacts(artifacts) {
+    const parsedCatalog = CatalogSchema.parse(JSON.parse(artifacts['catalog.v1.json']));
+    verifyCatalogReferences(parsedCatalog);
+    const lock = SourcesLockSchema.parse(JSON.parse(artifacts['sources.lock.json']));
+    const summary = JSON.parse(artifacts['catalog-summary.v1.json']);
+    const compatibility = JSON.parse(artifacts['compatibility.v1.json']);
+    const categories = JSON.parse(artifacts['categories.v1.json']);
+    const integrity = JSON.parse(artifacts['integrity.json']);
+    if (parsedCatalog.sources.length !== lock.sources.length)
+        throw new Error('INTEGRITY_SOURCE_COUNT_MISMATCH');
+    if (summary.schemaVersion !== 1 ||
+        summary.catalogId !== parsedCatalog.catalogId ||
+        summary.sourceCount !== parsedCatalog.sources.length ||
+        summary.pluginCount !== parsedCatalog.plugins.length ||
+        !Array.isArray(summary.search) ||
+        compatibility.schemaVersion !== 1 ||
+        compatibility.catalogId !== parsedCatalog.catalogId ||
+        !Array.isArray(compatibility.plugins) ||
+        compatibility.plugins.length !== parsedCatalog.plugins.length ||
+        categories.schemaVersion !== 1 ||
+        categories.catalogId !== parsedCatalog.catalogId ||
+        !Array.isArray(categories.categories) ||
+        (categories.products !== undefined &&
+            (typeof categories.products !== 'object' || categories.products === null)) ||
+        (categories.diagnostics !== undefined && !Array.isArray(categories.diagnostics)) ||
+        integrity.schemaVersion !== 1 ||
+        integrity.catalogId !== parsedCatalog.catalogId ||
+        !integrity.files ||
+        (integrity.assets !== undefined && !Array.isArray(integrity.assets))) {
+        throw new Error('INTEGRITY_ARTIFACT_METADATA_MISMATCH');
+    }
+    // The published file set is exactly what integrity.json enumerates, so the
+    // shards can grow with the category configuration without a fixed list here.
+    for (const name of Object.keys(artifacts))
+        if (name !== 'integrity.json' && integrity.files?.[name] === undefined)
+            throw new Error(`INTEGRITY_FILE_SET_MISMATCH: ${name}`);
+    for (const [name, expected] of Object.entries(integrity.files ?? {})) {
+        const content = artifacts[name];
+        if (content === undefined)
+            throw new Error(`INTEGRITY_FILE_SET_MISMATCH: ${name}`);
+        if (digest(content) !== expected)
+            throw new Error(`INTEGRITY_DIGEST_MISMATCH: ${name}`);
+    }
+    const indexArtifact = artifacts[CATALOG_INDEX_ARTIFACT];
+    const verification = verifyConsumerIndex(artifacts['categories.v1.json'], parsedCatalog, indexArtifact);
+    if (verification.hasConsumerIndex && indexArtifact === undefined)
+        throw new Error(`SHARD_MISSING: ${CATALOG_INDEX_ARTIFACT}`);
+    for (const shard of verification.shards)
+        verifyShardArtifact(shard, artifacts[shard.name], verification);
+    verifyIconAssets(integrity.assets, verification);
+}
+/**
+ * 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 function verifyShardArtifact(shard, content, verification) {
+    if (content === undefined)
+        throw new Error(`SHARD_MISSING: ${shard.name}`);
+    const parsed = JSON.parse(content);
+    // The index shard carries products keyed by productKey; the shelf and list
+    // shards carry them as ordered arrays.
+    const products = shard.kind === 'index'
+        ? Object.values((parsed.products ?? {}))
+        : parsed.products;
+    if (!Array.isArray(products))
+        throw new Error(`SHARD_PRODUCTS_INVALID: ${shard.name}`);
+    const keys = products.map((product) => product.productKey);
+    if (new Set(keys).size !== keys.length)
+        throw new Error(`SHARD_DUPLICATE_PRODUCT: ${shard.name}`);
+    if (shard.kind === 'index') {
+        const expected = Object.keys(verification.products ?? {}).toSorted();
+        if (keys.toSorted().join('\n') !== expected.join('\n'))
+            throw new Error('SHARD_INDEX_MEMBERSHIP_MISMATCH');
+        return;
+    }
+    const category = verification.categories?.find((item) => item.category === shard.category);
+    if (!category)
+        throw new Error(`SHARD_CATEGORY_UNKNOWN: ${shard.name}`);
+    const expected = shard.kind === 'shelf' ? category.topProductKeys : category.productKeys;
+    if (keys.join('\n') !== expected.join('\n'))
+        throw new Error(`SHARD_ORDER_MISMATCH: ${shard.name}`);
+    for (const product of products) {
+        const index = verification.products?.[product.productKey];
+        if (!index || digest(index) !== digest(product))
+            throw new Error(`SHARD_PRODUCT_MISMATCH: ${shard.name}: ${product.productKey}`);
+    }
+}
+/** Every mirrored icon is declared once, with the digest the index advertises. */
+function verifyIconAssets(assets, verification) {
+    const declared = (assets ?? []);
+    if (!Array.isArray(declared))
+        throw new Error('INTEGRITY_ASSETS_INVALID');
+    const referenced = new Map();
+    for (const product of Object.values(verification.products ?? {})) {
+        if (!product.icon)
+            continue;
+        const existing = referenced.get(product.icon.asset);
+        if (existing && existing.digest !== product.icon.digest)
+            throw new Error(`ICON_ASSET_DIGEST_CONFLICT: ${product.icon.asset}`);
+        referenced.set(product.icon.asset, {
+            name: product.icon.asset,
+            digest: product.icon.digest,
+            bytes: product.icon.bytes,
+            contentType: product.icon.contentType,
+            kind: product.icon.kind,
+            origin: product.icon.kind === 'content' ? (product.icon.path ?? '') : (product.icon.url ?? ''),
+        });
+    }
+    if (declared.length !== referenced.size)
+        throw new Error('INTEGRITY_ASSET_SET_MISMATCH');
+    for (const asset of declared) {
+        const expected = referenced.get(asset.name);
+        if (!expected)
+            throw new Error(`INTEGRITY_ASSET_UNDECLARED: ${asset.name}`);
+        if (expected.digest !== asset.digest ||
+            expected.bytes !== asset.bytes ||
+            expected.contentType !== asset.contentType ||
+            expected.kind !== asset.kind ||
+            expected.origin !== asset.origin)
+            throw new Error(`INTEGRITY_ASSET_MISMATCH: ${asset.name}`);
+    }
+}
+/**
+ * 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 function verifyConsumerIndex(content, catalog, indexContent) {
+    const index = JSON.parse(content);
+    const knownPlugins = new Map(catalog.plugins.map((plugin) => [plugin.pluginId, plugin]));
+    // Products live in the index shard; the navigation artifact only points at it.
+    const shard = indexContent ? JSON.parse(indexContent) : undefined;
+    const products = shard && typeof shard.products === 'object' && shard.products !== null
+        ? shard.products
+        : typeof index.products === 'object' && index.products !== null
+            ? index.products
+            : undefined;
+    const diagnostics = Array.isArray(index.diagnostics) ? index.diagnostics : [];
+    for (const category of index.categories ?? []) {
+        const members = catalog.plugins.filter((plugin) => plugin.categories.includes(category.category));
+        if (category.pluginCount !== undefined && category.pluginCount !== members.length)
+            throw new Error(`CONSUMER_INDEX_PLUGIN_COUNT_MISMATCH: ${category.category}`);
+        if (category.pluginIds.length !== members.length)
+            throw new Error(`CONSUMER_INDEX_PLUGIN_LIST_MISMATCH: ${category.category}`);
+        if (new Set(category.pluginIds).size !== category.pluginIds.length)
+            throw new Error(`CONSUMER_INDEX_DUPLICATE_PLUGIN: ${category.category}`);
+        for (const pluginId of category.pluginIds) {
+            const plugin = knownPlugins.get(pluginId);
+            if (!plugin || !plugin.categories.includes(category.category))
+                throw new Error(`CONSUMER_INDEX_FOREIGN_PLUGIN: ${category.category}: ${pluginId}`);
+        }
+        if (!products)
+            continue;
+        if (category.productKeys === undefined || category.topProductKeys === undefined)
+            throw new Error(`CONSUMER_INDEX_PRODUCTS_INCOMPLETE: ${category.category}`);
+        if (new Set(category.productKeys).size !== category.productKeys.length)
+            throw new Error(`CONSUMER_INDEX_DUPLICATE_PRODUCT: ${category.category}`);
+        for (const productKey of category.productKeys) {
+            const product = products[productKey];
+            if (!product)
+                throw new Error(`CONSUMER_INDEX_UNKNOWN_PRODUCT: ${productKey}`);
+            if (!product.categories.includes(category.category))
+                throw new Error(`CONSUMER_INDEX_PRODUCT_CATEGORY_MISMATCH: ${productKey}`);
+        }
+        if (category.productCount !== category.productKeys.length)
+            throw new Error(`CONSUMER_INDEX_PRODUCT_COUNT_MISMATCH: ${category.category}`);
+        const topCount = index.topCount;
+        if (topCount === undefined || !Number.isInteger(topCount) || topCount < 0)
+            throw new Error('CONSUMER_INDEX_TOP_COUNT_INVALID');
+        if (category.topProductKeys.length > topCount)
+            throw new Error(`CONSUMER_INDEX_TOP_OVERFLOW: ${category.category}`);
+        const shelved = new Set();
+        for (const product of Object.values(products)) {
+            // Indexes published before the install facts existed carry no `release`,
+            // and are still valid; a record that does carry one must agree with the
+            // catalog it claims to describe.
+            if (product.release) {
+                const plugin = knownPlugins.get(product.pluginId);
+                const release = plugin?.availableReleases.find((candidate) => candidate.releaseId === plugin.currentReleaseId);
+                if (!plugin ||
+                    !release ||
+                    product.release.releaseId !== release.releaseId ||
+                    product.release.canonicalContentDigest !== release.canonicalContentDigest ||
+                    product.release.sourceRevision !== release.resolvedCommitSha ||
+                    product.provenance?.resolvedCommitSha !== release.resolvedCommitSha)
+                    throw new Error(`CONSUMER_INDEX_RELEASE_MISMATCH: ${product.productKey}`);
+            }
+            const icon = product.icon;
+            if (!icon?.assetUrl)
+                continue;
+            if (!icon.assetUrl.startsWith('https://') || !icon.assetUrl.endsWith(`/${icon.asset}`))
+                throw new Error(`CONSUMER_INDEX_ASSET_URL_INVALID: ${icon.asset}`);
+        }
+        for (const productKey of category.topProductKeys) {
+            if (!category.productKeys.includes(productKey))
+                throw new Error(`CONSUMER_INDEX_TOP_NOT_MEMBER: ${category.category}: ${productKey}`);
+            if (shelved.has(productKey))
+                throw new Error(`CONSUMER_INDEX_TOP_REPEATED: ${productKey}`);
+            shelved.add(productKey);
+        }
+    }
+    if (products) {
+        // A product headlines one category only, so no product is shelved twice.
+        const claimed = new Set();
+        for (const category of index.categories ?? [])
+            for (const productKey of category.topProductKeys ?? []) {
+                if (claimed.has(productKey))
+                    throw new Error(`CONSUMER_INDEX_TOP_CROSS_CATEGORY: ${productKey}`);
+                claimed.add(productKey);
+            }
+        for (const [productKey, product] of Object.entries(products)) {
+            if (productKey !== product.productKey)
+                throw new Error('CONSUMER_INDEX_PRODUCT_KEY_MISMATCH');
+            if (product.variantPluginIds[0] !== product.pluginId)
+                throw new Error(`CONSUMER_INDEX_CANONICAL_NOT_FIRST: ${productKey}`);
+            const variants = new Set(product.variantPluginIds.map((pluginId) => {
+                const plugin = knownPlugins.get(pluginId);
+                if (!plugin)
+                    throw new Error(`CONSUMER_INDEX_UNKNOWN_PLUGIN: ${pluginId}`);
+                if (plugin.productGroupingKey !== productKey)
+                    throw new Error(`CONSUMER_INDEX_VARIANT_PRODUCT_MISMATCH: ${pluginId}`);
+                return pluginId;
+            }));
+            if (variants.size !== product.variantPluginIds.length)
+                throw new Error(`CONSUMER_INDEX_DUPLICATE_VARIANT: ${productKey}`);
+        }
+        const counts = shard?.counts ?? index.counts;
+        if (counts?.plugins !== catalog.plugins.length)
+            throw new Error('CONSUMER_INDEX_TOTAL_MISMATCH');
+        if (counts?.products !== Object.keys(products).length)
+            throw new Error('CONSUMER_INDEX_PRODUCT_TOTAL_MISMATCH');
+        if (counts?.redundantPlugins !== catalog.plugins.length - counts.products)
+            throw new Error('CONSUMER_INDEX_REDUNDANCY_MISMATCH');
+        if (index.counts && shard?.counts && digest(index.counts) !== digest(shard.counts))
+            throw new Error('CONSUMER_INDEX_COUNTS_MISMATCH');
+        if (shard?.topCount !== undefined && index.topCount !== shard.topCount)
+            throw new Error('CONSUMER_INDEX_TOP_COUNT_MISMATCH');
+    }
+    if (products && index.iconCoverage) {
+        const expected = iconCoverage({ products });
+        if (index.iconCoverage.total !== expected.total ||
+            index.iconCoverage.content !== expected.content ||
+            index.iconCoverage.favicon !== expected.favicon ||
+            index.iconCoverage.monogramOnly !== expected.monogramOnly ||
+            index.iconCoverage.monogramProductKeys.join('\n') !== expected.monogramProductKeys.join('\n'))
+            throw new Error('CONSUMER_INDEX_ICON_COVERAGE_MISMATCH');
+    }
+    const shards = [
+        ...(products ? [{ name: CATALOG_INDEX_ARTIFACT, kind: 'index' }] : []),
+        ...(index.categories ?? []).flatMap((category) => products && category.shelfArtifact && category.listArtifact
+            ? [
+                { name: category.shelfArtifact, kind: 'shelf', category: category.category },
+                { name: category.listArtifact, kind: 'list', category: category.category },
+            ]
+            : []),
+    ];
+    return {
+        hasConsumerIndex: products !== undefined,
+        diagnostics,
+        ...(products ? { counts: index.counts } : {}),
+        ...(products && index.topCount !== undefined ? { topCount: index.topCount } : {}),
+        ...(products ? { products, categories: index.categories ?? [] } : {}),
+        shards: products ? shards : [],
+    };
+}
+export function verifyCatalogReferences(catalog, policy = DEFAULT_POLICY) {
+    for (const source of catalog.sources) {
+        assertRepositoryAllowed(source.repositoryUrl, policy);
+        validateCatalogPath(source.manifestPath, 'SOURCE_MANIFEST_PATH_INVALID');
+    }
+    for (const plugin of catalog.plugins) {
+        assertRepositoryAllowed(plugin.provenance.repositoryUrl, policy);
+        validateCatalogPath(plugin.provenance.pluginSubdirectory, 'PROVENANCE_PATH_INVALID');
+        for (const release of plugin.availableReleases) {
+            assertRepositoryAllowed(release.resolvedRepositoryUrl, policy);
+            validateCatalogPath(release.pluginSubdirectory, 'RELEASE_PATH_INVALID');
+            for (const path of release.fileIndex)
+                validateCatalogPath(path, 'RELEASE_FILE_PATH_INVALID');
+        }
+    }
+}
+function validateCatalogPath(path, code) {
+    if (path !== '.')
+        safeRelativePath(path, code);
+}
+function createChangeReport(catalog, lock, existingLock, existingCatalog, skippedPlugins = []) {
+    const changedSources = existingLock
+        ? lock.sources
+            .filter((source) => (() => {
+            const previous = existingLock.sources.find((candidate) => candidate.sourceId === source.sourceId);
+            return (!previous ||
+                previous?.resolvedCommitSha !== source.resolvedCommitSha ||
+                previous.sourceManifestDigest !== source.sourceManifestDigest ||
+                digest(previous.pluginPins) !== digest(source.pluginPins));
+        })())
+            .map((source) => source.sourceId)
+        : lock.sources.map((source) => source.sourceId);
+    const previousPlugins = new Map(existingCatalog?.plugins.map((plugin) => [plugin.pluginId, plugin]) ?? []);
+    const currentPlugins = new Map(catalog.plugins.map((plugin) => [plugin.pluginId, plugin]));
+    const addedPlugins = catalog.plugins
+        .filter((plugin) => !previousPlugins.has(plugin.pluginId))
+        .map((plugin) => plugin.pluginId);
+    const removedPlugins = [...previousPlugins.keys()].filter((pluginId) => !currentPlugins.has(pluginId));
+    const changedPlugins = catalog.plugins
+        .filter((plugin) => previousPlugins.get(plugin.pluginId)?.currentReleaseId !== plugin.currentReleaseId &&
+        previousPlugins.has(plugin.pluginId))
+        .map((plugin) => plugin.pluginId);
+    return {
+        schemaVersion: 1,
+        changedSources: changedSources.toSorted(),
+        addedPlugins: addedPlugins.toSorted(),
+        removedPlugins: removedPlugins.toSorted(),
+        changedPlugins: changedPlugins.toSorted(),
+        skippedPlugins,
+        permissionSensitiveChanges: catalog.plugins
+            .flatMap((plugin) => plugin.securityClassification.permissionSensitiveChanges.map((type) => `${plugin.pluginId}:${type}`))
+            .toSorted(),
+        contentResolution: skippedPlugins.length > 0
+            ? 'complete-with-skips'
+            : catalog.plugins.some((plugin) => plugin.securityClassification.contentResolution === 'metadata-only')
+                ? 'metadata-only'
+                : 'complete',
+    };
+}
+async function resolveSource(config, mode, fixtureRoot, lock, fromLock) {
+    const manifestPath = safeRelativePath(config.manifestPath, 'SOURCE_MANIFEST_PATH_INVALID');
+    const locked = lock?.sources.find((entry) => entry.sourceId === config.sourceId);
+    if (fromLock && !locked)
+        throw new Error(`SOURCE_LOCK_ENTRY_MISSING: ${config.sourceId}`);
+    const commitSha = fromLock && locked
+        ? locked.resolvedCommitSha
+        : mode === 'offline'
+            ? (config.fixtureCommitSha ?? locked?.resolvedCommitSha)
+            : await resolveGitRef(config.repositoryUrl, `refs/heads/${config.defaultBranch}`);
+    if (!commitSha || !/^[a-f0-9]{40}$/.test(commitSha))
+        throw new Error(`SOURCE_COMMIT_UNRESOLVED: ${config.sourceId}`);
+    const manifestText = mode === 'offline'
+        ? await readFixtureManifest({ ...config, manifestPath }, fixtureRoot)
+        : await fetchText(rawUrl(config.repositoryUrl, commitSha, manifestPath));
+    const parsed = parseMarketplaceManifest(parseJsonDocument(manifestText), config);
+    if (fromLock && locked && digest(manifestText) !== locked.sourceManifestDigest)
+        throw new Error(`SOURCE_LOCK_MANIFEST_MISMATCH: ${config.sourceId}`);
+    const pluginPins = await resolvePluginPins({
+        config,
+        parsed,
+        sourceCommitSha: commitSha,
+        lockedPins: locked?.pluginPins,
+        fromLock,
+        resolveExternalRefs: mode === 'live',
+    });
+    return {
+        config,
+        commitSha,
+        manifestText,
+        parsed,
+        pluginPins,
+        retrievedAt: fromLock && locked
+            ? locked.retrievedAt
+            : mode === 'offline'
+                ? '2026-01-01T00:00:00.000Z'
+                : new Date().toISOString(),
+        manifestDigest: digest(manifestText),
+    };
+}
+async function resolvePluginPins(input) {
+    const pins = await mapWithConcurrency(input.parsed.entries, 8, async (entry) => {
+        if (entry.source.kind === 'local') {
+            return {
+                pluginName: entry.name,
+                repositoryUrl: canonicalRepositoryUrl(input.config.repositoryUrl),
+                pluginSubdirectory: entry.source.path,
+                resolvedCommitSha: input.sourceCommitSha,
+            };
+        }
+        const repositoryUrl = canonicalRepositoryUrl(entry.source.repositoryUrl);
+        const pluginSubdirectory = entry.source.subdirectory;
+        const locked = input.lockedPins?.find((pin) => pin.pluginName === entry.name);
+        if (input.fromLock && !locked)
+            throw new Error(`SOURCE_LOCK_PLUGIN_PIN_MISSING: ${input.config.sourceId}:${entry.name}`);
+        if (locked) {
+            if (locked.repositoryUrl !== repositoryUrl ||
+                locked.pluginSubdirectory !== pluginSubdirectory) {
+                throw new Error(`SOURCE_LOCK_PLUGIN_PIN_MISMATCH: ${input.config.sourceId}:${entry.name}`);
+            }
+            return locked;
+        }
+        const resolvedCommitSha = entry.source.sha ??
+            (input.resolveExternalRefs
+                ? await resolveGitRef(repositoryUrl, entry.source.ref?.startsWith('refs/')
+                    ? entry.source.ref
+                    : `refs/heads/${entry.source.ref ?? 'main'}`)
+                : input.sourceCommitSha);
+        return { pluginName: entry.name, repositoryUrl, pluginSubdirectory, resolvedCommitSha };
+    });
+    return pins.toSorted((left, right) => left.pluginName.localeCompare(right.pluginName));
+}
+async function mapWithConcurrency(values, concurrency, mapper) {
+    const results = Array.from({ length: values.length });
+    let nextIndex = 0;
+    const worker = async () => {
+        while (true) {
+            const index = nextIndex++;
+            if (index >= values.length)
+                return;
+            results[index] = await mapper(values[index], index);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(Math.max(concurrency, 1), values.length) }, () => worker()));
+    return results;
+}
+async function readFixtureManifest(config, fixtureRoot) {
+    if (!fixtureRoot || !config.fixturePath)
+        throw new Error(`FIXTURE_ROOT_REQUIRED: ${config.sourceId}`);
+    return fs.readFile(join(resolve(fixtureRoot), config.fixturePath, config.manifestPath), 'utf8');
+}
+async function resolveGitRef(repositoryUrl, ref) {
+    const result = spawn('git', ['ls-remote', canonicalRepositoryUrl(repositoryUrl), ref], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([
+        new Promise((resolveOutput, reject) => {
+            const chunks = [];
+            result.stdout?.on('data', (chunk) => chunks.push(chunk));
+            result.stdout?.on('error', reject);
+            result.stdout?.on('end', () => resolveOutput(Buffer.concat(chunks).toString('utf8')));
+        }),
+        new Promise((resolveError) => {
+            const chunks = [];
+            result.stderr?.on('data', (chunk) => chunks.push(chunk));
+            result.stderr?.on('error', () => resolveError(''));
+            result.stderr?.on('end', () => resolveError(Buffer.concat(chunks).toString('utf8')));
+        }),
+        new Promise((resolveExit, reject) => {
+            result.on('error', reject);
+            result.on('close', (code) => resolveExit(code ?? 1));
+        }),
+    ]);
+    if (exitCode !== 0)
+        throw new Error(`GIT_REF_LOOKUP_FAILED: ${repositoryUrl}:${ref}:${stderr.trim()}`);
+    const sha = stdout.trim().split(/\s+/)[0];
+    if (!sha || !/^[a-f0-9]{40}$/.test(sha))
+        throw new Error(`GIT_REF_NOT_FOUND: ${repositoryUrl}:${ref}`);
+    return sha;
+}
+/** Raw content URL for one file at an immutable commit. */
+export function rawContentUrl(repositoryUrl, commitSha, path) {
+    return rawUrl(repositoryUrl, commitSha, path);
+}
+/** Fetches bytes from an allow-listed upstream URL with the shared retry policy. */
+export async function fetchUpstreamBytes(url, signal) {
+    const response = await fetchUpstream(url, {
+        headers: upstreamRequestHeaders(url),
+        ...(signal ? { signal } : {}),
+    });
+    if (!response.ok)
+        throw new Error(`HTTP_FETCH_FAILED: ${response.status}: ${url}`);
+    return new Uint8Array(await response.arrayBuffer());
+}
+function rawUrl(repositoryUrl, commitSha, path) {
+    const parsed = new URL(canonicalRepositoryUrl(repositoryUrl));
+    return `https://raw.githubusercontent.com${parsed.pathname}/${commitSha}/${path.split('/').map(encodeURIComponent).join('/')}`;
+}
+async function fetchText(url) {
+    const response = await fetch(url, { headers: upstreamRequestHeaders(url) });
+    if (!response.ok)
+        throw new Error(`HTTP_FETCH_FAILED: ${response.status}:${url}`);
+    return response.text();
+}
+const UPSTREAM_USER_AGENT = 'agent-hq-plugin-marketplace';
+/**
+ * Hosts that may receive the repository credential.
+ *
+ * Everything else is fetched anonymously. The token this build runs with
+ * authorises repository writes for the duration of the job, so a vendor
+ * homepage, its icon CDN or any other third party must never be handed it.
+ */
+const GITHUB_CREDENTIAL_HOSTS = /(^|\.)(github\.com|githubusercontent\.com)$/;
+/**
+ * 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 function upstreamRequestHeaders(url) {
+    const anonymous = { 'user-agent': UPSTREAM_USER_AGENT };
+    let host;
+    try {
+        host = new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return anonymous;
+    }
+    const token = process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN;
+    if (!token || !GITHUB_CREDENTIAL_HOSTS.test(host))
+        return anonymous;
+    return {
+        accept: 'application/vnd.github+json',
+        authorization: `Bearer ${token}`,
+        'user-agent': UPSTREAM_USER_AGENT,
+    };
+}
+/**
+ * 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 function createSiteIconFetcher(deadline) {
+    const bounded = () => {
+        const ceiling = AbortSignal.timeout(SITE_FETCH_TIMEOUT_MS);
+        return deadline ? AbortSignal.any([deadline, ceiling]) : ceiling;
+    };
+    return {
+        fetchText: async (url) => new TextDecoder().decode(await fetchUpstreamBytes(url, bounded())),
+        fetchBytes: (url) => fetchUpstreamBytes(url, bounded()),
+        digest: byteDigest,
+    };
+}
+/** Ceiling for a single product-site request during icon discovery. */
+export const SITE_FETCH_TIMEOUT_MS = 15_000;
+const UPSTREAM_FETCH_MAX_ATTEMPTS = 3;
+const UPSTREAM_FETCH_BASE_DELAY_MS = 1000;
+const UPSTREAM_FETCH_MAX_DELAY_MS = 30000;
+const UPSTREAM_WEATHER_SKIP_CODES = new Set([
+    'PLUGIN_SOURCE_UNAVAILABLE',
+    'PLUGIN_FILE_UNAVAILABLE',
+    'PLUGIN_PATH_NOT_FOUND',
+]);
+function sleep(ms) {
+    return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+}
+function upstreamRetryDelayMs(attempt, response) {
+    const retryAfter = response?.headers.get('retry-after');
+    if (retryAfter !== null && retryAfter !== undefined) {
+        const seconds = Number(retryAfter);
+        if (Number.isFinite(seconds) && seconds >= 0)
+            return Math.min(seconds * 1000, UPSTREAM_FETCH_MAX_DELAY_MS);
+        const date = Date.parse(retryAfter);
+        if (!Number.isNaN(date))
+            return Math.min(Math.max(date - Date.now(), 0), UPSTREAM_FETCH_MAX_DELAY_MS);
+    }
+    return Math.min(UPSTREAM_FETCH_BASE_DELAY_MS * 2 ** attempt, UPSTREAM_FETCH_MAX_DELAY_MS);
+}
+function isRateLimitedUpstream(response) {
+    return (response.headers.get('x-ratelimit-remaining') === '0' ||
+        response.headers.get('retry-after') !== null);
+}
+function isRetryableUpstreamStatus(status, response) {
+    if (status === 429)
+        return true;
+    if (status >= 500)
+        return true;
+    if (status === 403 && response !== undefined && isRateLimitedUpstream(response))
+        return true;
+    return false;
+}
+async function fetchUpstream(url, init) {
+    let attempt = 0;
+    for (;;) {
+        let response;
+        try {
+            response = await fetch(url, init);
+        }
+        catch (error) {
+            if (attempt >= UPSTREAM_FETCH_MAX_ATTEMPTS - 1)
+                throw error;
+            await sleep(upstreamRetryDelayMs(attempt));
+            attempt += 1;
+            continue;
+        }
+        if (response.ok ||
+            !isRetryableUpstreamStatus(response.status, response) ||
+            attempt >= UPSTREAM_FETCH_MAX_ATTEMPTS - 1)
+            return response;
+        await sleep(upstreamRetryDelayMs(attempt, response));
+        attempt += 1;
+    }
+}
+/**
+ * Ceiling on bytes read out of one repository archive.
+ *
+ * The per-plugin policy still bounds what any single plugin may contain; this
+ * only stops a decompression bomb from exhausting the build host, and it is
+ * enforced while the stream is read rather than after it is buffered.
+ */
+const MAX_ARCHIVE_BYTES = 512 * 1024 * 1024;
+function concatChunks(chunks, length) {
+    const out = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+/**
+ * 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 async function readArchiveFiles(archive, policy) {
+    const files = new Map();
+    let totalBytes = 0;
+    const parser = extract();
+    const gunzip = createGunzip();
+    const settled = new Promise((resolveDone, rejectDone) => {
+        const fail = (error) => {
+            gunzip.destroy();
+            parser.destroy();
+            rejectDone(error);
+        };
+        parser.on('entry', (header, stream, next) => {
+            const skip = () => {
+                stream.on('end', next);
+                stream.resume();
+            };
+            if (header.type !== 'file')
+                return skip();
+            const segments = header.name.split('/');
+            if (segments.length < 2)
+                return skip();
+            let path;
+            try {
+                path = safeRelativePath(segments.slice(1).join('/'), 'TREE_PATH_INVALID');
+            }
+            catch (error) {
+                return fail(error);
+            }
+            const chunks = [];
+            let length = 0;
+            stream.on('data', (chunk) => {
+                const bytes = chunk;
+                length += bytes.byteLength;
+                chunks.push(bytes);
+            });
+            stream.on('error', fail);
+            stream.on('end', () => {
+                try {
+                    const bytes = concatChunks(chunks, length);
+                    if (bytes.byteLength > policy.maxFileBytes)
+                        throw new Error(`PLUGIN_FILE_TOO_LARGE: ${path}`);
+                    totalBytes += bytes.byteLength;
+                    if (totalBytes > MAX_ARCHIVE_BYTES)
+                        throw new Error('PLUGIN_SIZE_POLICY: archive');
+                    files.set(path, bytes);
+                    next();
+                }
+                catch (error) {
+                    fail(error);
+                }
+            });
+            stream.resume();
+        });
+        parser.on('error', fail);
+        gunzip.on('error', fail);
+        parser.on('finish', () => resolveDone());
+    });
+    Readable.from([archive]).pipe(gunzip).pipe(parser);
+    await settled;
+    return files;
+}
+export class NetworkSnapshotLoader {
+    #policy;
+    #trees = new Map();
+    #archives = new Map();
+    constructor(policy) {
+        this.#policy = policy;
+    }
+    async load(repositoryUrl, commitSha, pluginSubdirectory) {
+        const parsed = new URL(canonicalRepositoryUrl(repositoryUrl));
+        if (!['github.com', 'www.github.com'].includes(parsed.hostname))
+            throw new Error(`GIT_HOST_UNSUPPORTED: ${parsed.hostname}`);
+        const [owner, repo] = parsed.pathname.split('/').filter(Boolean);
+        if (!owner || !repo)
+            throw new Error('GIT_REPOSITORY_INVALID');
+        const key = `${owner}/${repo}@${commitSha}`;
+        let tree = this.#trees.get(key);
+        if (!tree) {
+            const treeUrl = `https://api.github.com/repos/${owner}/${repo}/git/trees/${commitSha}?recursive=1`;
+            const response = await fetchUpstream(treeUrl, {
+                headers: upstreamRequestHeaders(treeUrl),
+            });
+            if (!response.ok)
+                throw new PluginSafetyError('PLUGIN_SOURCE_UNAVAILABLE', [`${owner}/${repo}`]);
+            const payload = (await response.json());
+            if (payload.truncated)
+                throw new Error(`GIT_TREE_TRUNCATED: ${owner}/${repo}@${commitSha}`);
+            tree = (payload.tree ?? []).map((entry) => ({
+                ...entry,
+                path: safeRelativePath(entry.path, 'TREE_PATH_INVALID'),
+            }));
+            this.#trees.set(key, tree);
+        }
+        const prefix = pluginSubdirectory ? `${safeRelativePath(pluginSubdirectory)}/` : '';
+        const submodules = tree.filter((entry) => entry.path.startsWith(prefix) && (entry.type === 'commit' || entry.mode === '160000'));
+        if (submodules.length > 0)
+            throw new Error(`GIT_SUBMODULE_UNSUPPORTED: ${repositoryUrl}:${pluginSubdirectory}`);
+        const selected = tree.filter((entry) => entry.type === 'blob' && entry.path.startsWith(prefix));
+        if (selected.length === 0)
+            throw new Error(`PLUGIN_PATH_NOT_FOUND: ${repositoryUrl}:${pluginSubdirectory}`);
+        const files = new Map();
+        const symlinks = tree
+            .filter((entry) => entry.mode === '120000' && entry.path.startsWith(prefix))
+            .map((entry) => entry.path);
+        if (selected.length > this.#policy.maxFilesPerPlugin)
+            throw new Error('PLUGIN_TOO_MANY_FILES');
+        let totalSize = 0;
+        for (const entry of selected) {
+            const size = entry.size ?? 0;
+            if (size > this.#policy.maxFileBytes || totalSize + size > this.#policy.maxBytesPerPlugin)
+                throw new Error(`PLUGIN_SIZE_POLICY: ${entry.path}`);
+            totalSize += size;
+        }
+        // The tree above already bounded this plugin before a byte was pulled, so
+        // the archive is the only unbounded read left and it is capped while it
+        // streams. One archive per repository replaces one request per file.
+        const archive = await this.#archiveFiles(key, owner, repo, commitSha);
+        for (const entry of selected) {
+            const bytes = archive.get(entry.path);
+            if (!bytes)
+                throw new PluginSafetyError('PLUGIN_FILE_UNAVAILABLE', [entry.path]);
+            if (bytes.byteLength > this.#policy.maxFileBytes)
+                throw new Error(`PLUGIN_FILE_TOO_LARGE: ${entry.path}`);
+            files.set(prefix ? relative(prefix.slice(0, -1), entry.path).replaceAll('\\', '/') : entry.path, bytes);
+        }
+        return { files, symlinks };
+    }
+    /**
+     * One repository archive per (repository, commit), shared by every plugin
+     * that repository hosts.
+     */
+    async #archiveFiles(key, owner, repo, commitSha) {
+        const cached = this.#archives.get(key);
+        if (cached)
+            return cached;
+        const url = `https://api.github.com/repos/${owner}/${repo}/tarball/${commitSha}`;
+        const response = await fetchUpstream(url, { headers: upstreamRequestHeaders(url) });
+        if (!response.ok)
+            throw new PluginSafetyError('PLUGIN_SOURCE_UNAVAILABLE', [`${owner}/${repo}`]);
+        const files = await readArchiveFiles(new Uint8Array(await response.arrayBuffer()), this.#policy);
+        this.#archives.set(key, files);
+        return files;
+    }
+}
+export class FixtureSnapshotLoader {
+    #root;
+    #sources;
+    constructor(root, sources) {
+        this.#root = resolve(root);
+        this.#sources = new Map(sources.map((source) => [canonicalRepositoryUrl(source.repositoryUrl), source]));
+    }
+    async load(repositoryUrl, _commitSha, pluginSubdirectory) {
+        const source = this.#sources.get(canonicalRepositoryUrl(repositoryUrl));
+        if (!source?.fixturePath)
+            throw new Error(`FIXTURE_REPOSITORY_NOT_FOUND: ${repositoryUrl}`);
+        return snapshotFromDirectory(join(this.#root, source.fixturePath), pluginSubdirectory);
+    }
+}
+export class DirectorySnapshotLoader {
+    async load(_repositoryUrl, _commitSha, pluginSubdirectory) {
+        throw new Error(`DIRECTORY_LOADER_REQUIRES_ROOT: ${pluginSubdirectory}`);
+    }
+}
+export async function snapshotFromDirectory(root, pluginSubdirectory) {
+    const directory = resolve(root, pluginSubdirectory);
+    const files = new Map();
+    const symlinks = [];
+    const rootStat = await fs.lstat(directory);
+    if (rootStat.isSymbolicLink())
+        return { files, symlinks: [pluginSubdirectory || '.'] };
+    await walk(directory, directory, files, symlinks);
+    return { files, symlinks };
+}
+async function walk(root, current, files, symlinks) {
+    for (const entry of await fs.readdir(current, { withFileTypes: true })) {
+        const absolute = join(current, entry.name);
+        const relativePath = safeRelativePath(relative(root, absolute), 'DIRECTORY_PATH_INVALID');
+        if (entry.isSymbolicLink()) {
+            symlinks.push(relativePath);
+            continue;
+        }
+        if (entry.isDirectory())
+            await walk(root, absolute, files, symlinks);
+        else if (entry.isFile())
+            files.set(relativePath, await fs.readFile(absolute));
+    }
+}
+function sortArtifactKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortArtifactKeys);
+    if (value !== null && typeof value === 'object')
+        return Object.fromEntries(Object.keys(value)
+            .toSorted()
+            .map((key) => [key, sortArtifactKeys(value[key])]));
+    return value;
+}
+function json(value) {
+    return `${JSON.stringify(sortArtifactKeys(value), null, 2)}\n`;
+}
+function trimSlugEdges(value) {
+    let start = 0;
+    let end = value.length;
+    while (start < end && value[start] === '-')
+        start += 1;
+    while (end > start && value[end - 1] === '-')
+        end -= 1;
+    return value.slice(start, end);
+}
+function slug(value) {
+    const result = trimSlugEdges(value
+        .trim()
+        .toLocaleLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')).slice(0, 128) || 'unknown';
+    return result.length < 2 ? `${result}-plugin` : result;
+}
+function stringValue(input) {
+    return typeof input === 'string' && input.trim() ? input.trim() : undefined;
+}
+function isString(input) {
+    return typeof input === 'string' && input.trim().length > 0;
+}
+function arrayValue(input) {
+    return Array.isArray(input) ? input : [];
+}
+//# sourceMappingURL=index.js.map