@voilabs/plugins 0.0.1-beta.0

package/dist/manager.js

@@ -0,0 +1,1006 @@
+import { Plugin } from "./plugin.js";
+import { injectHtml as injectHtmlString, renderInjectionHtml, renderPluginInjection, } from "./injection.js";
+export class PluginManagerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PluginManagerError";
+    }
+}
+export class PluginNotFoundError extends PluginManagerError {
+    constructor(pluginId) {
+        super(`Plugin "${pluginId}" was not found.`);
+        this.name = "PluginNotFoundError";
+    }
+}
+export class PluginNotInstalledError extends PluginManagerError {
+    constructor(pluginId) {
+        super(`Plugin "${pluginId}" is not installed.`);
+        this.name = "PluginNotInstalledError";
+    }
+}
+export class MemoryPluginDatabase {
+    records = new Map();
+    async list(scope = {}) {
+        return [...this.records.values()].filter((record) => (record.tenantId ?? "") === (scope.tenantId ?? ""));
+    }
+    async load(pluginId, scope = {}) {
+        return this.records.get(storageKey(pluginId, scope.tenantId)) ?? null;
+    }
+    async save(installation) {
+        this.records.set(storageKey(installation.pluginId, installation.tenantId), installation);
+        return installation;
+    }
+    async update(pluginId, patch, scope = {}) {
+        const current = await this.load(pluginId, scope);
+        if (!current) {
+            throw new PluginNotInstalledError(pluginId);
+        }
+        const updated = {
+            ...current,
+            ...patch,
+            pluginId,
+            tenantId: scope.tenantId,
+            updatedAt: new Date().toISOString(),
+        };
+        await this.save(updated);
+        return updated;
+    }
+    async delete(pluginId, scope = {}) {
+        this.records.delete(storageKey(pluginId, scope.tenantId));
+    }
+}
+export class PluginManager {
+    marketplaces;
+    redisUrl;
+    registry = new Map();
+    database;
+    encryption;
+    fetcher;
+    defaultTenantId;
+    marketplacesSynced = false;
+    marketplacesSyncedAt;
+    marketplaceSyncPromise;
+    autoSyncMarketplaces;
+    marketplaceRefreshIntervalMs;
+    github;
+    constructor(options = {}) {
+        this.marketplaces = options.marketplaces ?? [];
+        this.redisUrl = options.redisUrl;
+        this.database = options.database ?? new MemoryPluginDatabase();
+        this.encryption = options.encryption;
+        this.fetcher = options.fetcher ?? globalThis.fetch?.bind(globalThis);
+        this.defaultTenantId = options.defaultTenantId;
+        this.autoSyncMarketplaces =
+            options.autoSyncMarketplaces ?? this.marketplaces.length > 0;
+        this.marketplaceRefreshIntervalMs = options.marketplaceRefreshIntervalMs;
+        this.github = options.github ?? {};
+        if (options.plugins?.length) {
+            this.register(options.plugins);
+        }
+        if (options.syncOnInit) {
+            const initialSync = this.syncMarketplaces({ force: true });
+            initialSync.catch(() => undefined);
+        }
+    }
+    register(pluginOrPlugins) {
+        const plugins = Array.isArray(pluginOrPlugins)
+            ? pluginOrPlugins
+            : [pluginOrPlugins];
+        for (const pluginLike of plugins) {
+            const plugin = pluginLike instanceof Plugin ? pluginLike : new Plugin(pluginLike);
+            this.registry.set(plugin.id, plugin);
+        }
+        return this;
+    }
+    unregister(pluginId) {
+        return this.registry.delete(pluginId);
+    }
+    getById(pluginId) {
+        return this.registry.get(pluginId);
+    }
+    require(pluginId) {
+        const plugin = this.getById(pluginId);
+        if (!plugin) {
+            throw new PluginNotFoundError(pluginId);
+        }
+        return plugin;
+    }
+    async get(options = {}) {
+        await this.ready();
+        const page = Math.max(1, options.page ?? 1);
+        const limit = Math.max(1, Math.min(100, options.limit ?? 20));
+        const tenantId = this.resolveTenantId(options);
+        const query = options.query?.toLocaleLowerCase();
+        const tags = options.tags ?? [];
+        const installations = await this.listInstallations({ tenantId });
+        const installationByPluginId = new Map(installations.map((installation) => [installation.pluginId, installation]));
+        let items = [...this.registry.values()].map((plugin) => {
+            const installation = installationByPluginId.get(plugin.id);
+            return {
+                ...plugin.toManifest(),
+                installation: installation
+                    ? toInstallationSummary(installation)
+                    : undefined,
+            };
+        });
+        if (options.category) {
+            items = items.filter((item) => item.category === options.category);
+        }
+        if (options.provider) {
+            items = items.filter((item) => item.provider === options.provider);
+        }
+        if (query) {
+            items = items.filter((item) => [item.name, item.summary, item.description, item.provider, ...(item.tags ?? [])]
+                .filter(Boolean)
+                .some((value) => String(value).toLocaleLowerCase().includes(query)));
+        }
+        if (tags.length) {
+            items = items.filter((item) => tags.every((tag) => item.tags?.includes(tag)));
+        }
+        if (options.installed !== undefined) {
+            items = items.filter((item) => Boolean(item.installation?.installed) === options.installed);
+        }
+        if (options.enabled !== undefined) {
+            items = items.filter((item) => Boolean(item.installation?.enabled) === options.enabled);
+        }
+        const total = items.length;
+        const start = (page - 1) * limit;
+        const data = items.slice(start, start + limit);
+        return {
+            data,
+            page,
+            limit,
+            total,
+            hasNextPage: start + data.length < total,
+        };
+    }
+    async getPluginView(pluginId, scope = {}) {
+        await this.ready();
+        const tenantId = this.resolveTenantId(scope);
+        const plugin = this.require(pluginId);
+        const installation = await this.database.load(plugin.id, { tenantId });
+        return {
+            ...plugin.toManifest(),
+            installation: installation
+                ? toInstallationSummary(installation)
+                : undefined,
+        };
+    }
+    async install(pluginId, config, options = {}) {
+        await this.ready();
+        const tenantId = this.resolveTenantId(options);
+        const plugin = this.require(pluginId);
+        const normalizedConfig = plugin.applyDefaults(config);
+        await plugin.assertValidConfig(normalizedConfig);
+        const now = new Date().toISOString();
+        const existing = await this.database.load(plugin.id, { tenantId });
+        const installation = {
+            id: storageKey(plugin.id, tenantId),
+            pluginId: plugin.id,
+            tenantId,
+            enabled: options.enabled ?? existing?.enabled ?? true,
+            config: await this.sealConfig(plugin, normalizedConfig, { tenantId }),
+            version: plugin.version,
+            meta: options.meta ?? existing?.meta,
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now,
+        };
+        const saved = (await this.database.save(installation)) ?? installation;
+        await plugin.definition.lifecycle?.onInstall?.({
+            plugin,
+            manager: this,
+            installation: saved,
+            config: normalizedConfig,
+        });
+        return saved;
+    }
+    async updateConfig(pluginId, config, options = {}) {
+        await this.ready();
+        const tenantId = this.resolveTenantId(options);
+        const plugin = this.require(pluginId);
+        const current = await this.database.load(plugin.id, { tenantId });
+        if (!current) {
+            throw new PluginNotInstalledError(plugin.id);
+        }
+        const currentConfig = await this.revealConfig(plugin, current.config, {
+            tenantId,
+        });
+        const normalizedConfig = plugin.applyDefaults(options.merge === false
+            ? config
+            : {
+                ...currentConfig,
+                ...config,
+            });
+        await plugin.assertValidConfig(normalizedConfig);
+        const patch = {
+            config: await this.sealConfig(plugin, normalizedConfig, { tenantId }),
+            meta: options.meta ?? current.meta,
+            updatedAt: new Date().toISOString(),
+        };
+        const saved = await this.savePatch(plugin.id, patch, { tenantId });
+        await plugin.definition.lifecycle?.onUpdate?.({
+            plugin,
+            manager: this,
+            installation: saved,
+            config: normalizedConfig,
+        });
+        return saved;
+    }
+    async enable(pluginId, scope = {}) {
+        await this.ready();
+        const tenantId = this.resolveTenantId(scope);
+        const plugin = this.require(pluginId);
+        const installation = await this.savePatch(plugin.id, { enabled: true }, { tenantId });
+        await plugin.definition.lifecycle?.onEnable?.({
+            plugin,
+            manager: this,
+            installation,
+            config: await this.getInstallationConfig(plugin.id, { tenantId }),
+        });
+        return installation;
+    }
+    async disable(pluginId, scope = {}) {
+        await this.ready();
+        const tenantId = this.resolveTenantId(scope);
+        const plugin = this.require(pluginId);
+        const installation = await this.savePatch(plugin.id, { enabled: false }, { tenantId });
+        await plugin.definition.lifecycle?.onDisable?.({
+            plugin,
+            manager: this,
+            installation,
+            config: await this.getInstallationConfig(plugin.id, { tenantId }),
+        });
+        return installation;
+    }
+    async uninstall(pluginId, scope = {}) {
+        await this.ready();
+        const tenantId = this.resolveTenantId(scope);
+        const plugin = this.require(pluginId);
+        const installation = await this.database.load(plugin.id, { tenantId });
+        if (installation) {
+            await plugin.definition.lifecycle?.onUninstall?.({
+                plugin,
+                manager: this,
+                installation,
+                config: await this.revealConfig(plugin, installation.config, {
+                    tenantId,
+                }),
+            });
+        }
+        if (this.database.delete) {
+            await this.database.delete(plugin.id, { tenantId });
+            return;
+        }
+        await this.savePatch(plugin.id, { enabled: false }, { tenantId });
+    }
+    async getInstallation(pluginId, scope = {}) {
+        await this.ready();
+        return this.database.load(pluginId, {
+            tenantId: this.resolveTenantId(scope),
+        });
+    }
+    async getInstallationConfig(pluginId, scope = {}) {
+        await this.ready();
+        const tenantId = this.resolveTenantId(scope);
+        const plugin = this.require(pluginId);
+        const installation = await this.database.load(pluginId, { tenantId });
+        if (!installation) {
+            return {};
+        }
+        return this.revealConfig(plugin, installation.config, { tenantId });
+    }
+    getManifest(pluginId) {
+        return this.require(pluginId).toManifest();
+    }
+    getAdditionalMetaTags(pluginId) {
+        if (pluginId) {
+            return this.require(pluginId).definition.additionalMetaTags ?? [];
+        }
+        return [...this.registry.values()].flatMap((plugin) => plugin.definition.additionalMetaTags ?? []);
+    }
+    getFrontendComponents(slot) {
+        return [...this.registry.values()].flatMap((plugin) => {
+            const components = plugin.definition.frontend?.components ?? [];
+            return components
+                .filter((component) => !slot || component.slot === slot)
+                .map((component) => ({
+                ...component,
+                pluginId: plugin.id,
+            }));
+        });
+    }
+    async getInjections(options = {}) {
+        await this.ready();
+        const tenantId = this.resolveTenantId(options);
+        const scope = { tenantId };
+        const installedOnly = options.installedOnly ?? true;
+        const enabledOnly = options.enabledOnly ?? true;
+        const installations = await this.listInstallations(scope);
+        const installationByPluginId = new Map(installations.map((installation) => [installation.pluginId, installation]));
+        const url = resolveInjectionUrl(options);
+        const path = options.path ?? url?.pathname;
+        const resolved = [];
+        for (const plugin of this.registry.values()) {
+            const installation = installationByPluginId.get(plugin.id) ?? null;
+            if (installedOnly && !installation) {
+                continue;
+            }
+            if (enabledOnly && !installation?.enabled) {
+                continue;
+            }
+            const config = installation
+                ? await this.revealConfig(plugin, installation.config, scope)
+                : plugin.applyDefaults({});
+            for (const injection of plugin.definition.injections ?? []) {
+                if (!matchesInjectionQuery(injection, {
+                    ...options,
+                    path,
+                    area: options.area,
+                    placement: options.placement,
+                    installed: Boolean(installation),
+                    enabled: installation?.enabled ?? false,
+                    tenantId,
+                    config,
+                })) {
+                    continue;
+                }
+                const rendered = await renderPluginInjection(injection, {
+                    plugin,
+                    manager: this,
+                    installation,
+                    config,
+                    tenantId,
+                    request: options.request,
+                    url,
+                    path,
+                    area: options.area,
+                    placement: injection.placement,
+                    nonce: options.nonce,
+                    locals: options.locals ?? {},
+                });
+                if (!rendered?.html) {
+                    continue;
+                }
+                resolved.push({
+                    ...serializeInjection(injection),
+                    pluginId: plugin.id,
+                    pluginName: plugin.name,
+                    html: rendered.html,
+                });
+            }
+        }
+        return resolved.sort(sortResolvedInjections);
+    }
+    async renderInjections(options = {}) {
+        return renderInjectionHtml(await this.getInjections(options), options);
+    }
+    async injectHtml(html, options = {}) {
+        return injectHtmlString(html, await this.getInjections(options), options);
+    }
+    async ready() {
+        if (!this.shouldSyncMarketplaces()) {
+            return;
+        }
+        await this.syncMarketplaces({ force: this.isMarketplaceSyncStale() });
+    }
+    async syncMarketplaces(options = {}) {
+        if (!this.marketplaces.length) {
+            this.marketplacesSynced = true;
+            this.marketplacesSyncedAt = Date.now();
+            return { loaded: 0, marketplaces: 0 };
+        }
+        if (!options.force && this.marketplaceSyncPromise) {
+            return this.marketplaceSyncPromise;
+        }
+        if (!options.force && this.marketplacesSynced && !this.isMarketplaceSyncStale()) {
+            return {
+                loaded: 0,
+                marketplaces: this.marketplaces.length,
+            };
+        }
+        this.marketplaceSyncPromise = this.loadMarketplaces();
+        try {
+            return await this.marketplaceSyncPromise;
+        }
+        finally {
+            this.marketplaceSyncPromise = undefined;
+        }
+    }
+    async loadMarketplaces() {
+        let loaded = 0;
+        for (const marketplace of this.marketplaces) {
+            loaded += await this.loadMarketplace(marketplace);
+        }
+        this.marketplacesSynced = true;
+        this.marketplacesSyncedAt = Date.now();
+        return {
+            loaded,
+            marketplaces: this.marketplaces.length,
+        };
+    }
+    async loadMarketplace(marketplaceSource) {
+        if (!this.fetcher) {
+            throw new PluginManagerError("No fetch implementation is available.");
+        }
+        const candidates = marketplaceCandidates(marketplaceSource, this.github);
+        let lastError;
+        let successfulCandidates = 0;
+        const pluginsById = new Map();
+        for (const candidate of candidates) {
+            try {
+                const response = await this.fetcher(candidate.url, {
+                    headers: candidate.headers,
+                });
+                if (!response.ok) {
+                    lastError = new Error(`${response.status} ${response.statusText}`);
+                    continue;
+                }
+                successfulCandidates += 1;
+                if (candidate.parser === "github-tree") {
+                    const pluginFileCandidates = await readGitHubPluginFileCandidates(response, candidate);
+                    for (const pluginFileCandidate of pluginFileCandidates) {
+                        try {
+                            const pluginFileResponse = await this.fetcher(pluginFileCandidate.url, {
+                                headers: pluginFileCandidate.headers,
+                            });
+                            if (!pluginFileResponse.ok) {
+                                lastError = new Error(`${pluginFileResponse.status} ${pluginFileResponse.statusText}`);
+                                continue;
+                            }
+                            successfulCandidates += 1;
+                            const payload = await readMarketplacePayload(pluginFileResponse, pluginFileCandidate);
+                            for (const plugin of extractMarketplacePlugins(payload)) {
+                                const normalizedPlugin = applyMarketplaceDefaults(plugin, pluginFileCandidate);
+                                pluginsById.set(normalizedPlugin.id, normalizedPlugin);
+                            }
+                        }
+                        catch (error) {
+                            lastError = error;
+                        }
+                    }
+                    continue;
+                }
+                const payload = await readMarketplacePayload(response, candidate);
+                for (const plugin of extractMarketplacePlugins(payload)) {
+                    const normalizedPlugin = applyMarketplaceDefaults(plugin, candidate);
+                    pluginsById.set(normalizedPlugin.id, normalizedPlugin);
+                }
+            }
+            catch (error) {
+                lastError = error;
+            }
+        }
+        if (pluginsById.size) {
+            this.register([...pluginsById.values()]);
+            return pluginsById.size;
+        }
+        if (successfulCandidates > 0) {
+            return 0;
+        }
+        throw new PluginManagerError(`Marketplace "${marketplaceLabel(marketplaceSource)}" could not be loaded: ${String(lastError)}`);
+    }
+    shouldSyncMarketplaces() {
+        return Boolean(this.autoSyncMarketplaces &&
+            this.marketplaces.length &&
+            (!this.marketplacesSynced || this.isMarketplaceSyncStale()));
+    }
+    isMarketplaceSyncStale() {
+        if (!this.marketplaceRefreshIntervalMs || !this.marketplacesSyncedAt) {
+            return false;
+        }
+        return Date.now() - this.marketplacesSyncedAt >= this.marketplaceRefreshIntervalMs;
+    }
+    async listInstallations(scope) {
+        if (this.database.list) {
+            return this.database.list(scope);
+        }
+        const installations = await Promise.all([...this.registry.keys()].map((pluginId) => this.database.load(pluginId, scope)));
+        return installations.filter(Boolean);
+    }
+    async savePatch(pluginId, patch, scope) {
+        const current = await this.database.load(pluginId, scope);
+        if (!current) {
+            throw new PluginNotInstalledError(pluginId);
+        }
+        if (this.database.update) {
+            const updated = await this.database.update(pluginId, patch, scope);
+            if (updated) {
+                return updated;
+            }
+        }
+        const merged = {
+            ...current,
+            ...patch,
+            pluginId,
+            tenantId: scope.tenantId,
+            updatedAt: new Date().toISOString(),
+        };
+        await this.database.save(merged);
+        return merged;
+    }
+    resolveTenantId(scope = {}) {
+        return scope.tenantId ?? this.defaultTenantId;
+    }
+    async sealConfig(plugin, config, scope) {
+        const sealed = {};
+        for (const [key, value] of Object.entries(config)) {
+            const field = plugin.fields.find((candidate) => candidate.key === key);
+            if (field && shouldEncrypt(plugin, field) && this.encryption && value != null) {
+                sealed[key] = {
+                    __voilabsEncrypted: true,
+                    value: await this.encryption.encrypt(String(value), {
+                        pluginId: plugin.id,
+                        fieldKey: key,
+                        tenantId: scope.tenantId,
+                    }),
+                };
+                continue;
+            }
+            sealed[key] = value;
+        }
+        return sealed;
+    }
+    async revealConfig(plugin, config, scope) {
+        const revealed = {};
+        for (const [key, value] of Object.entries(config)) {
+            if (isEncryptedConfigValue(value) && this.encryption) {
+                revealed[key] = await this.encryption.decrypt(value.value, {
+                    pluginId: plugin.id,
+                    fieldKey: key,
+                    tenantId: scope.tenantId,
+                });
+                continue;
+            }
+            revealed[key] = value;
+        }
+        return revealed;
+    }
+}
+function storageKey(pluginId, tenantId) {
+    return `${tenantId ?? "default"}:${pluginId}`;
+}
+function toInstallationSummary(installation) {
+    return {
+        installed: true,
+        enabled: installation.enabled,
+        pluginId: installation.pluginId,
+        tenantId: installation.tenantId,
+        version: installation.version,
+        meta: installation.meta,
+        createdAt: installation.createdAt,
+        updatedAt: installation.updatedAt,
+    };
+}
+function shouldEncrypt(plugin, field) {
+    return Boolean(plugin.definition.needEncryption ||
+        field.encrypt ||
+        field.secret ||
+        field.type === "password" ||
+        field.type === "secret");
+}
+function isEncryptedConfigValue(value) {
+    return Boolean(value &&
+        typeof value === "object" &&
+        value.__voilabsEncrypted === true &&
+        typeof value.value === "string");
+}
+function matchesInjectionQuery(injection, context) {
+    if (injection.enabled === false) {
+        return false;
+    }
+    if (!placementMatches(injection.placement, context.placement)) {
+        return false;
+    }
+    if (!areaMatches(injection, context.area)) {
+        return false;
+    }
+    const condition = injection.condition;
+    if (!condition) {
+        return true;
+    }
+    if (condition.installedOnly && !context.installed) {
+        return false;
+    }
+    if (condition.enabledOnly && !context.enabled) {
+        return false;
+    }
+    if (condition.tenantIds?.length &&
+        (!context.tenantId || !condition.tenantIds.includes(context.tenantId))) {
+        return false;
+    }
+    if (condition.paths?.length && !matchesAnyPath(context.path, condition.paths)) {
+        return false;
+    }
+    if (condition.excludePaths?.length &&
+        matchesAnyPath(context.path, condition.excludePaths)) {
+        return false;
+    }
+    if (condition.config && !matchesConfig(context.config, condition.config)) {
+        return false;
+    }
+    return true;
+}
+function placementMatches(injectionPlacement, requested) {
+    if (!requested) {
+        return true;
+    }
+    if (injectionPlacement === requested) {
+        return true;
+    }
+    const aliases = {
+        head: ["head", "head:start", "head:end", "admin:head", "public:head"],
+        body: ["body", "body:start", "body:end", "admin:body", "public:body"],
+        footer: ["footer", "admin:footer", "public:footer"],
+    };
+    return aliases[requested]?.includes(injectionPlacement) ?? false;
+}
+function areaMatches(injection, area) {
+    const placementArea = injection.placement.includes(":")
+        ? injection.placement.split(":")[0]
+        : undefined;
+    const conditionArea = injection.condition?.area;
+    if (conditionArea) {
+        const allowedAreas = Array.isArray(conditionArea)
+            ? conditionArea
+            : [conditionArea];
+        if (!area || !allowedAreas.includes(area)) {
+            return false;
+        }
+    }
+    if (!placementArea || ["head", "body", "footer"].includes(placementArea)) {
+        return true;
+    }
+    return area === placementArea;
+}
+function matchesAnyPath(path, patterns) {
+    if (!path) {
+        return false;
+    }
+    return patterns.some((pattern) => matchPathPattern(path, pattern));
+}
+function matchPathPattern(path, pattern) {
+    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+    const normalizedPattern = pattern.startsWith("/") ? pattern : `/${pattern}`;
+    const regex = new RegExp(`^${normalizedPattern
+        .split("*")
+        .map(escapeRegex)
+        .join(".*")}$`);
+    return regex.test(normalizedPath);
+}
+function matchesConfig(config, expected) {
+    return Object.entries(expected).every(([key, value]) => config[key] === value);
+}
+function resolveInjectionUrl(options) {
+    if (options.url instanceof URL) {
+        return options.url;
+    }
+    if (typeof options.url === "string") {
+        return new URL(options.url, "http://voilabs.local");
+    }
+    if (options.request) {
+        return new URL(options.request.url);
+    }
+    return undefined;
+}
+function serializeInjection(injection) {
+    const { render: _render, ...serializable } = injection;
+    return serializable;
+}
+function sortResolvedInjections(left, right) {
+    return (left.order ?? 0) - (right.order ?? 0) || left.key.localeCompare(right.key);
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function marketplaceCandidates(input, defaults) {
+    if (typeof input === "string") {
+        const githubLocation = parseGitHubLocation(input);
+        if (githubLocation) {
+            return githubMarketplaceCandidates(githubLocation, defaults);
+        }
+        return [
+            {
+                url: input,
+                parser: "json",
+            },
+        ];
+    }
+    if ("url" in input) {
+        return [
+            {
+                url: input.url,
+                headers: mergeHeaders(defaults.headers, input.headers),
+                parser: "json",
+            },
+        ];
+    }
+    const repository = input.github ?? input.repository;
+    const parsed = repository ? parseGitHubLocation(repository) : null;
+    const owner = input.owner ?? parsed?.owner;
+    const repo = input.repo ?? parsed?.repo;
+    if (!owner || !repo) {
+        return [];
+    }
+    return githubMarketplaceCandidates({
+        owner,
+        repo,
+        branch: input.branch ?? parsed?.branch,
+        path: input.path ?? parsed?.path,
+        exactPath: parsed?.exactPath,
+    }, {
+        ...defaults,
+        ...input,
+    });
+}
+function githubMarketplaceCandidates(location, options) {
+    const rawBaseUrl = trimTrailingSlash(options.rawBaseUrl ?? "https://raw.githubusercontent.com");
+    const apiBaseUrl = trimTrailingSlash(options.apiBaseUrl ?? "https://api.github.com");
+    const defaultFiles = options.files ?? [
+        "marketplace.json",
+        "plugins.json",
+        "index.json",
+    ];
+    const pluginFileExtensions = normalizePluginFileExtensions(options.pluginFileExtensions);
+    const branchWasExplicit = Boolean(location.branch ?? options.branch);
+    const branches = branchWasExplicit
+        ? [location.branch ?? options.branch ?? "main"]
+        : ["main", "master"];
+    const paths = location.exactPath && location.path
+        ? [location.path]
+        : defaultFiles.map((file) => joinUrlPath(location.path, file));
+    const headers = mergeHeaders(options.headers, options.token
+        ? {
+            accept: "application/vnd.github+json",
+            authorization: `Bearer ${options.token}`,
+        }
+        : undefined);
+    const candidates = [];
+    for (const branch of branches) {
+        if (!location.exactPath && options.pluginFiles !== false) {
+            candidates.push({
+                url: `${apiBaseUrl}/repos/${location.owner}/${location.repo}/git/trees/${encodeURIComponent(branch)}?recursive=${options.recursivePluginFiles === false ? "0" : "1"}`,
+                headers,
+                parser: "github-tree",
+                github: {
+                    owner: location.owner,
+                    repo: location.repo,
+                    branch,
+                    pathPrefix: normalizePathPrefix(location.path),
+                    rawBaseUrl,
+                    apiBaseUrl,
+                    extensions: pluginFileExtensions,
+                    avatarSize: options.avatarSize ?? 128,
+                    headers,
+                },
+            });
+        }
+        for (const path of paths) {
+            const normalizedPath = path.replace(/^\/+/, "");
+            candidates.push({
+                url: `${rawBaseUrl}/${location.owner}/${location.repo}/${branch}/${normalizedPath}`,
+                headers,
+                parser: "json",
+                github: {
+                    owner: location.owner,
+                    repo: location.repo,
+                    branch,
+                    pathPrefix: normalizePathPrefix(location.path),
+                    rawBaseUrl,
+                    apiBaseUrl,
+                    extensions: pluginFileExtensions,
+                    avatarSize: options.avatarSize ?? 128,
+                    headers,
+                },
+            });
+            candidates.push({
+                url: `${apiBaseUrl}/repos/${location.owner}/${location.repo}/contents/${encodeUrlPath(normalizedPath)}?ref=${encodeURIComponent(branch)}`,
+                headers,
+                parser: "github-content",
+                github: {
+                    owner: location.owner,
+                    repo: location.repo,
+                    branch,
+                    pathPrefix: normalizePathPrefix(location.path),
+                    rawBaseUrl,
+                    apiBaseUrl,
+                    extensions: pluginFileExtensions,
+                    avatarSize: options.avatarSize ?? 128,
+                    headers,
+                },
+            });
+        }
+    }
+    return candidates;
+}
+function parseGitHubLocation(input) {
+    const normalized = input.replace(/^github:/, "").replace(/\.git$/, "");
+    try {
+        const url = new URL(normalized);
+        const hostname = url.hostname.toLocaleLowerCase();
+        if (hostname === "raw.githubusercontent.com") {
+            return null;
+        }
+        if (hostname !== "github.com" && hostname !== "www.github.com") {
+            return null;
+        }
+        const [owner, repo, marker, branch, ...rest] = url.pathname
+            .split("/")
+            .filter(Boolean);
+        if (!owner || !repo) {
+            return null;
+        }
+        if ((marker === "blob" || marker === "tree") && branch) {
+            return {
+                owner,
+                repo: repo.replace(/\.git$/, ""),
+                branch,
+                path: rest.join("/") || undefined,
+                exactPath: marker === "blob",
+            };
+        }
+        return {
+            owner,
+            repo: repo.replace(/\.git$/, ""),
+        };
+    }
+    catch {
+        const [owner, repo] = normalized.split("/").filter(Boolean);
+        if (!owner || !repo) {
+            return null;
+        }
+        return {
+            owner,
+            repo: repo.replace(/\.git$/, ""),
+        };
+    }
+}
+async function readMarketplacePayload(response, candidate) {
+    if (candidate.parser === "github-tree") {
+        throw new PluginManagerError(`GitHub tree response must be expanded before parsing ${candidate.url}.`);
+    }
+    if (candidate.parser === "json") {
+        return response.json();
+    }
+    const payload = (await response.json());
+    if (!payload.content || payload.encoding !== "base64") {
+        throw new PluginManagerError(`GitHub contents response did not include base64 JSON content from ${candidate.url}.`);
+    }
+    return JSON.parse(decodeBase64(payload.content));
+}
+function extractMarketplacePlugins(payload) {
+    if (Array.isArray(payload)) {
+        return payload;
+    }
+    if (isMarketplacePluginDefinition(payload)) {
+        return [payload];
+    }
+    return payload.plugin
+        ? [payload.plugin, ...(payload.plugins ?? payload.marketplace?.plugins ?? [])]
+        : payload.plugins ?? payload.marketplace?.plugins ?? [];
+}
+async function readGitHubPluginFileCandidates(response, candidate) {
+    if (!candidate.github) {
+        return [];
+    }
+    const discovery = candidate.github;
+    const payload = (await response.json());
+    return (payload.tree ?? [])
+        .filter((item) => Boolean(item.path && item.type === "blob"))
+        .filter((item) => isPluginFilePath(item.path, discovery))
+        .flatMap((item) => {
+        const encodedPath = encodeUrlPath(item.path);
+        return [
+            {
+                url: `${discovery.rawBaseUrl}/${discovery.owner}/${discovery.repo}/${discovery.branch}/${encodedPath}`,
+                headers: discovery.headers,
+                parser: "json",
+                github: discovery,
+            },
+            {
+                url: `${discovery.apiBaseUrl}/repos/${discovery.owner}/${discovery.repo}/contents/${encodedPath}?ref=${encodeURIComponent(discovery.branch)}`,
+                headers: discovery.headers,
+                parser: "github-content",
+                github: discovery,
+            },
+        ];
+    });
+}
+function isMarketplacePluginDefinition(value) {
+    return Boolean(value &&
+        typeof value === "object" &&
+        typeof value.id === "string" &&
+        typeof value.name === "string" &&
+        typeof value.summary === "string" &&
+        typeof value.category === "string");
+}
+function applyMarketplaceDefaults(plugin, candidate) {
+    const github = candidate.github;
+    if (!github) {
+        if (!plugin.provider) {
+            throw new PluginManagerError(`Marketplace plugin "${plugin.id}" must define provider when it is not loaded from GitHub.`);
+        }
+        return plugin;
+    }
+    return {
+        ...plugin,
+        provider: github.owner,
+        iconUrl: githubAvatarUrl(github.owner, github.avatarSize),
+        repositoryUrl: plugin.repositoryUrl ??
+            `https://github.com/${github.owner}/${github.repo}`,
+        meta: {
+            ...plugin.meta,
+            github: {
+                owner: github.owner,
+                repo: github.repo,
+                branch: github.branch,
+            },
+        },
+    };
+}
+function isPluginFilePath(path, discovery) {
+    const normalizedPath = path.replace(/^\/+/, "");
+    const prefix = discovery.pathPrefix;
+    if (prefix &&
+        normalizedPath !== prefix &&
+        !normalizedPath.startsWith(`${prefix}/`)) {
+        return false;
+    }
+    return discovery.extensions.some((extension) => normalizedPath.toLocaleLowerCase().endsWith(extension));
+}
+function marketplaceLabel(source) {
+    if (typeof source === "string") {
+        return source;
+    }
+    if ("url" in source) {
+        return source.url;
+    }
+    return source.github ?? source.repository ?? `${source.owner}/${source.repo}`;
+}
+function mergeHeaders(...headersList) {
+    const headers = new Headers();
+    for (const headersInit of headersList) {
+        if (!headersInit) {
+            continue;
+        }
+        new Headers(headersInit).forEach((value, key) => {
+            headers.set(key, value);
+        });
+    }
+    let hasHeaders = false;
+    headers.forEach(() => {
+        hasHeaders = true;
+    });
+    return hasHeaders ? headers : undefined;
+}
+function decodeBase64(value) {
+    const normalized = value.replace(/\s/g, "");
+    const buffer = globalThis.Buffer;
+    if (buffer) {
+        return buffer.from(normalized, "base64").toString("utf8");
+    }
+    const binary = atob(normalized);
+    const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+}
+function encodeUrlPath(path) {
+    return path.split("/").map(encodeURIComponent).join("/");
+}
+function joinUrlPath(base, path) {
+    return [base, path].filter(Boolean).join("/");
+}
+function normalizePathPrefix(path) {
+    const normalized = path?.replace(/^\/+|\/+$/g, "");
+    return normalized || undefined;
+}
+function normalizePluginFileExtensions(extensions) {
+    return (extensions?.length ? extensions : [".plugin"]).map((extension) => extension.startsWith(".")
+        ? extension.toLocaleLowerCase()
+        : `.${extension.toLocaleLowerCase()}`);
+}
+function githubAvatarUrl(owner, size) {
+    return `https://github.com/${owner}.png?size=${size}`;
+}
+function trimTrailingSlash(value) {
+    return value.replace(/\/+$/, "");
+}
+//# sourceMappingURL=manager.js.map