@lesliechan721/aw 0.1.0-beta.3

package/dist/src/utils/catalog-source-cache.d.ts

@@ -0,0 +1,61 @@
+import type { CatalogSourceId, CliVersion, SourceIdentity } from '../types.js';
+import { type CatalogSnapshotValidation } from './catalog-snapshot.js';
+export interface CatalogSourceCacheMetadata {
+    schemaVersion: 2;
+    entryKey: string;
+    sourceId: CatalogSourceId;
+    sourceIdentity: SourceIdentity;
+    requestedRef: string;
+    resolvedCommit: string;
+    manifestDigest: string;
+    snapshotDigest: string;
+    minAwVersion: CliVersion;
+    validatedAt: string;
+}
+export interface CatalogSourceCacheEntry {
+    entryDir: string;
+    snapshotRoot: string;
+    metadata: CatalogSourceCacheMetadata;
+    validation: CatalogSnapshotValidation;
+}
+export interface CatalogSourceCacheLocation {
+    awHomeDir: string;
+    cacheRootDir: string;
+    rootDir: string;
+    currentDir: string;
+    lastGoodDir: string;
+}
+declare function resolveCatalogSourceCacheLocation(options: {
+    sourceId: CatalogSourceId;
+    sourceIdentity: SourceIdentity;
+    env?: NodeJS.ProcessEnv;
+}): CatalogSourceCacheLocation;
+declare function ensureCatalogSourceCacheLocation(location: CatalogSourceCacheLocation): Promise<void>;
+declare function readCatalogSourceCache(options: {
+    location: CatalogSourceCacheLocation;
+    sourceId: CatalogSourceId;
+    sourceIdentity: SourceIdentity;
+    requestedRef: string;
+    cliVersion: CliVersion;
+    signal?: AbortSignal;
+}): Promise<CatalogSourceCacheEntry | null>;
+declare function publishCatalogSourceCacheEntry(options: {
+    location: CatalogSourceCacheLocation;
+    sourceId: CatalogSourceId;
+    sourceIdentity: SourceIdentity;
+    requestedRef: string;
+    cliVersion: CliVersion;
+    resolvedCommit: string;
+    snapshotRoot: string;
+    validation: CatalogSnapshotValidation;
+    signal?: AbortSignal;
+}): Promise<CatalogSourceCacheEntry>;
+export declare function cleanupLegacyCatalogSourceCache(env?: NodeJS.ProcessEnv): Promise<string[]>;
+/** @internal Minimal cache bridge for catalog providers and cache behavior tests. */
+export declare const catalogSourceCacheInternal: {
+    ensureCatalogSourceCacheLocation: typeof ensureCatalogSourceCacheLocation;
+    publishCatalogSourceCacheEntry: typeof publishCatalogSourceCacheEntry;
+    readCatalogSourceCache: typeof readCatalogSourceCache;
+    resolveCatalogSourceCacheLocation: typeof resolveCatalogSourceCacheLocation;
+};
+export {};

package/dist/src/utils/catalog-source-cache.js

@@ -0,0 +1,276 @@
+import crypto from 'node:crypto';
+import path from 'node:path';
+import fs from 'fs-extra';
+import { compareStrictSemVer } from './manifest.js';
+import { canonicalizePathThroughExistingAncestorSync, resolveAwHome } from './state-paths.js';
+import { validateCatalogSnapshot } from './catalog-snapshot.js';
+const SOURCE_ID_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
+const SOURCE_IDENTITY_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const COMMIT_IDENTITY_PATTERN = /^(?:[0-9a-f]{40}|[0-9a-f]{64}|path:sha256:[0-9a-f]{64})$/;
+function digestJson(value) {
+    return crypto.createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+function throwIfAborted(signal) {
+    signal?.throwIfAborted();
+}
+function assertCacheIdentity(sourceId, sourceIdentity) {
+    if (!SOURCE_ID_PATTERN.test(sourceId) || !SOURCE_IDENTITY_PATTERN.test(sourceIdentity)) {
+        throw new Error('Invalid catalog source cache identity.');
+    }
+}
+function isStrictObject(value, keys) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    return Object.keys(value).sort().join('\0') === [...keys].sort().join('\0');
+}
+function parseMetadata(value) {
+    if (!isStrictObject(value, [
+        'schemaVersion', 'entryKey', 'sourceId', 'sourceIdentity', 'requestedRef',
+        'resolvedCommit', 'manifestDigest', 'snapshotDigest', 'minAwVersion', 'validatedAt',
+    ]))
+        return null;
+    if (value.schemaVersion !== 2
+        || typeof value.entryKey !== 'string' || !/^[0-9a-f]{64}$/.test(value.entryKey)
+        || typeof value.sourceId !== 'string' || !SOURCE_ID_PATTERN.test(value.sourceId)
+        || typeof value.sourceIdentity !== 'string' || !SOURCE_IDENTITY_PATTERN.test(value.sourceIdentity)
+        || typeof value.requestedRef !== 'string' || value.requestedRef.length === 0
+        || typeof value.resolvedCommit !== 'string' || !COMMIT_IDENTITY_PATTERN.test(value.resolvedCommit)
+        || typeof value.manifestDigest !== 'string' || !SOURCE_IDENTITY_PATTERN.test(value.manifestDigest)
+        || typeof value.snapshotDigest !== 'string' || !SOURCE_IDENTITY_PATTERN.test(value.snapshotDigest)
+        || typeof value.minAwVersion !== 'string'
+        || typeof value.validatedAt !== 'string' || Number.isNaN(Date.parse(value.validatedAt)))
+        return null;
+    return value;
+}
+function resolveCatalogSourceCacheLocation(options) {
+    assertCacheIdentity(options.sourceId, options.sourceIdentity);
+    const awHomeDir = canonicalizePathThroughExistingAncestorSync(resolveAwHome(options.env ?? process.env));
+    const cacheRootDir = path.join(awHomeDir, 'catalog-cache');
+    const rootDir = path.join(cacheRootDir, 'sources', options.sourceId);
+    return {
+        awHomeDir,
+        cacheRootDir,
+        rootDir,
+        currentDir: path.join(rootDir, 'current'),
+        lastGoodDir: path.join(rootDir, 'last-good'),
+    };
+}
+async function ensureRegularDirectory(directory) {
+    const stat = await fs.lstat(directory).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (stat) {
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            throw new Error(`Catalog source cache path must be a regular directory: ${directory}`);
+        }
+        return;
+    }
+    await fs.mkdir(directory).catch(async (error) => {
+        if (error.code !== 'EEXIST')
+            throw error;
+        const concurrent = await fs.lstat(directory);
+        if (!concurrent.isDirectory() || concurrent.isSymbolicLink())
+            throw error;
+    });
+}
+async function ensureCatalogSourceCacheLocation(location) {
+    for (const directory of [
+        location.awHomeDir, location.cacheRootDir, path.join(location.cacheRootDir, 'sources'), location.rootDir,
+    ])
+        await ensureRegularDirectory(directory);
+}
+async function readSnapshotAt(options) {
+    try {
+        throwIfAborted(options.signal);
+        const entryStat = await fs.lstat(options.entryDir);
+        if (!entryStat.isDirectory() || entryStat.isSymbolicLink())
+            return null;
+        const metadataPath = path.join(options.entryDir, 'metadata.json');
+        const snapshotRoot = path.join(options.entryDir, 'snapshot');
+        const metadataStat = await fs.lstat(metadataPath);
+        if (!metadataStat.isFile() || metadataStat.isSymbolicLink())
+            return null;
+        const metadata = parseMetadata(await fs.readJson(metadataPath));
+        if (!metadata || metadata.sourceId !== options.sourceId
+            || metadata.sourceIdentity !== options.sourceIdentity
+            || metadata.requestedRef !== options.requestedRef
+            || compareStrictSemVer(options.cliVersion, metadata.minAwVersion) < 0)
+            return null;
+        const expectedKey = digestJson({
+            sourceId: metadata.sourceId,
+            sourceIdentity: metadata.sourceIdentity,
+            requestedRef: metadata.requestedRef,
+            resolvedCommit: metadata.resolvedCommit,
+            manifestDigest: metadata.manifestDigest,
+            snapshotDigest: metadata.snapshotDigest,
+            minAwVersion: metadata.minAwVersion,
+        });
+        if (metadata.entryKey !== expectedKey)
+            return null;
+        const validation = await validateCatalogSnapshot(snapshotRoot);
+        if (validation.manifestDigest !== metadata.manifestDigest
+            || validation.snapshotDigest !== metadata.snapshotDigest
+            || validation.manifest.compatibility.aw.minVersion !== metadata.minAwVersion)
+            return null;
+        throwIfAborted(options.signal);
+        return { entryDir: options.entryDir, snapshotRoot, metadata, validation };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        if (options.signal?.aborted)
+            throw error;
+        return null;
+    }
+}
+async function readCatalogSourceCache(options) {
+    assertCacheIdentity(options.sourceId, options.sourceIdentity);
+    const common = {
+        sourceId: options.sourceId, sourceIdentity: options.sourceIdentity,
+        requestedRef: options.requestedRef, cliVersion: options.cliVersion, signal: options.signal,
+    };
+    return await readSnapshotAt({ ...common, entryDir: options.location.currentDir })
+        ?? await readSnapshotAt({ ...common, entryDir: options.location.lastGoodDir });
+}
+async function publishCatalogSourceCacheEntry(options) {
+    assertCacheIdentity(options.sourceId, options.sourceIdentity);
+    if (options.requestedRef.length === 0 || !COMMIT_IDENTITY_PATTERN.test(options.resolvedCommit)) {
+        throw new Error('Invalid catalog source cache snapshot identity.');
+    }
+    await ensureCatalogSourceCacheLocation(options.location);
+    const candidateDir = path.join(options.location.rootDir, `.candidate-${crypto.randomUUID()}.tmp`);
+    const replacedLastGood = path.join(options.location.rootDir, `.last-good-${crypto.randomUUID()}.tmp`);
+    const replacedCurrent = path.join(options.location.rootDir, `.current-${crypto.randomUUID()}.tmp`);
+    const candidateSnapshotRoot = path.join(candidateDir, 'snapshot');
+    let currentMoved = false;
+    let oldLastGoodMoved = false;
+    let invalidCurrentMoved = false;
+    let candidateInstalled = false;
+    let committed = false;
+    try {
+        await fs.mkdir(candidateDir);
+        await fs.copy(options.snapshotRoot, candidateSnapshotRoot, { dereference: false, preserveTimestamps: true });
+        const validation = await validateCatalogSnapshot(candidateSnapshotRoot);
+        throwIfAborted(options.signal);
+        if (validation.manifestDigest !== options.validation.manifestDigest
+            || validation.snapshotDigest !== options.validation.snapshotDigest
+            || validation.manifest.compatibility.aw.minVersion !== options.validation.manifest.compatibility.aw.minVersion)
+            throw new Error('Catalog snapshot changed before cache publication.');
+        const identity = {
+            sourceId: options.sourceId, sourceIdentity: options.sourceIdentity,
+            requestedRef: options.requestedRef, resolvedCommit: options.resolvedCommit,
+            manifestDigest: validation.manifestDigest, snapshotDigest: validation.snapshotDigest,
+            minAwVersion: validation.manifest.compatibility.aw.minVersion,
+        };
+        const metadata = {
+            schemaVersion: 2, entryKey: digestJson(identity), ...identity, validatedAt: new Date().toISOString(),
+        };
+        await fs.writeJson(path.join(candidateDir, 'metadata.json'), metadata, { spaces: 2 });
+        throwIfAborted(options.signal);
+        const current = await readSnapshotAt({
+            entryDir: options.location.currentDir,
+            sourceId: options.sourceId,
+            sourceIdentity: options.sourceIdentity,
+            requestedRef: options.requestedRef,
+            cliVersion: options.cliVersion,
+            signal: options.signal,
+        });
+        if (current) {
+            if (await fs.pathExists(options.location.lastGoodDir)) {
+                await fs.rename(options.location.lastGoodDir, replacedLastGood);
+                oldLastGoodMoved = true;
+            }
+            await fs.rename(options.location.currentDir, options.location.lastGoodDir);
+            currentMoved = true;
+        }
+        else if (await fs.pathExists(options.location.currentDir)) {
+            await fs.rename(options.location.currentDir, replacedCurrent);
+            invalidCurrentMoved = true;
+        }
+        await fs.rename(candidateDir, options.location.currentDir);
+        candidateInstalled = true;
+        const published = await readSnapshotAt({
+            entryDir: options.location.currentDir,
+            sourceId: options.sourceId,
+            sourceIdentity: options.sourceIdentity,
+            requestedRef: options.requestedRef,
+            cliVersion: options.cliVersion,
+            signal: options.signal,
+        });
+        if (!published)
+            throw new Error('Published catalog source cache snapshot did not validate.');
+        committed = true;
+        return published;
+    }
+    catch (error) {
+        if (candidateInstalled) {
+            await fs.remove(options.location.currentDir).catch(() => undefined);
+        }
+        if (!await fs.pathExists(options.location.currentDir) && currentMoved) {
+            await fs.rename(options.location.lastGoodDir, options.location.currentDir).catch(() => undefined);
+        }
+        if (oldLastGoodMoved && !await fs.pathExists(options.location.lastGoodDir)) {
+            await fs.rename(replacedLastGood, options.location.lastGoodDir).catch(() => undefined);
+        }
+        if (!await fs.pathExists(options.location.currentDir) && invalidCurrentMoved) {
+            await fs.rename(replacedCurrent, options.location.currentDir).catch(() => undefined);
+        }
+        throw error;
+    }
+    finally {
+        await fs.remove(candidateDir).catch(() => undefined);
+        if (committed) {
+            await fs.remove(replacedLastGood).catch(() => undefined);
+            await fs.remove(replacedCurrent).catch(() => undefined);
+        }
+    }
+}
+export async function cleanupLegacyCatalogSourceCache(env = process.env) {
+    const cacheRoot = path.join(canonicalizePathThroughExistingAncestorSync(resolveAwHome(env)), 'catalog-cache');
+    const warnings = [];
+    const cacheRootStat = await fs.lstat(cacheRoot).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        warnings.push('旧 Catalog cache 根检查失败。');
+        return undefined;
+    });
+    if (cacheRootStat === undefined || cacheRootStat === null)
+        return warnings;
+    if (!cacheRootStat.isDirectory() || cacheRootStat.isSymbolicLink()) {
+        warnings.push('旧 Catalog cache 根不是普通目录，已跳过清理。');
+        return warnings;
+    }
+    for (const name of ['entries', 'selectors', 'observations', 'locks', 'quarantine', 'observation-order.json']) {
+        try {
+            await fs.remove(path.join(cacheRoot, name));
+        }
+        catch {
+            warnings.push(`旧 Catalog cache 布局清理失败：${name}`);
+        }
+    }
+    const entries = await fs.readdir(cacheRoot, { withFileTypes: true }).catch(() => {
+        warnings.push('旧 Catalog cache 根读取失败。');
+        return [];
+    });
+    for (const entry of entries) {
+        if (entry.name === 'sources' || !SOURCE_ID_PATTERN.test(entry.name))
+            continue;
+        try {
+            await fs.remove(path.join(cacheRoot, entry.name));
+        }
+        catch {
+            warnings.push(`旧 Catalog cache 来源布局清理失败：${entry.name}`);
+        }
+    }
+    return warnings;
+}
+/** @internal Minimal cache bridge for catalog providers and cache behavior tests. */
+export const catalogSourceCacheInternal = {
+    ensureCatalogSourceCacheLocation,
+    publishCatalogSourceCacheEntry,
+    readCatalogSourceCache,
+    resolveCatalogSourceCacheLocation,
+};
+//# sourceMappingURL=catalog-source-cache.js.map

package/dist/src/utils/catalog-source-cache.js.map

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

package/dist/src/utils/catalog-source-identity.d.ts

@@ -0,0 +1,4 @@
+import type { CatalogSource, SourceIdentity } from '../types.js';
+export declare function canonicalizeCatalogGitUrl(value: string): string;
+export declare function canonicalizeCatalogPath(value: string, cwd: string): Promise<string>;
+export declare function calculateCatalogSourceIdentity(source: CatalogSource): Promise<SourceIdentity>;

package/dist/src/utils/catalog-source-identity.js

@@ -0,0 +1,118 @@
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import fs from 'fs-extra';
+import { CATALOG_SOURCE_IDENTITY_VERSION } from '../constants.js';
+const SCP_GIT_URL_PATTERN = /^([^@/:\s]+)@([^/:\s]+):(.+)$/;
+const ALLOWED_GIT_URL_PROTOCOLS = new Set(['file:', 'https:', 'ssh:']);
+function normalizeGitPath(pathname) {
+    const normalized = pathname.replace(/\/+$/, '');
+    if (normalized === '' || normalized === '.') {
+        throw new Error('Invalid catalog Git URL: expected a repository path.');
+    }
+    return normalized;
+}
+export function canonicalizeCatalogGitUrl(value) {
+    if (typeof value !== 'string' || value.trim() === '' || value !== value.trim()) {
+        throw new Error('Invalid catalog Git URL: expected a non-empty canonical URL.');
+    }
+    const scpMatch = SCP_GIT_URL_PATTERN.exec(value);
+    if (scpMatch) {
+        const [, username, hostname, pathname] = scpMatch;
+        const hostUrl = new URL(`ssh://${hostname}/`);
+        const pathKind = pathname.startsWith('/') ? 'absolute' : 'relative';
+        return `scp-${pathKind}:${username}@${hostUrl.hostname.toLowerCase()}:${normalizeGitPath(pathname)}`;
+    }
+    if (path.isAbsolute(value)) {
+        const normalized = path.normalize(value).replace(/[\\/]+$/, '');
+        if (!normalized)
+            throw new Error('Invalid catalog Git path: expected a repository path.');
+        return normalized;
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error('Invalid catalog Git URL: expected an absolute URL.');
+    }
+    if (!ALLOWED_GIT_URL_PROTOCOLS.has(url.protocol)) {
+        throw new Error(`Invalid catalog Git URL protocol "${url.protocol}".`);
+    }
+    if ((url.protocol !== 'file:' && !url.hostname)
+        || (url.protocol === 'file:' && url.hostname !== '')
+        || url.password
+        || (url.username && url.protocol !== 'ssh:')) {
+        throw new Error('Invalid catalog Git URL: embedded credentials are not allowed.');
+    }
+    if (url.search || url.hash) {
+        throw new Error('Invalid catalog Git URL: query strings and fragments are not allowed.');
+    }
+    if (url.protocol === 'https:' && url.username) {
+        throw new Error('Invalid catalog Git URL: embedded credentials are not allowed.');
+    }
+    if (url.protocol === 'file:') {
+        const filePath = fileURLToPath(url);
+        if (!path.isAbsolute(filePath))
+            throw new Error('Invalid catalog Git file URL: expected an absolute path.');
+        return pathToFileURL(normalizeGitPath(filePath)).href;
+    }
+    const username = url.username ? `${url.username}@` : '';
+    const port = url.port ? `:${url.port}` : '';
+    return `${url.protocol}//${username}${url.hostname.toLowerCase()}${port}${normalizeGitPath(url.pathname)}`;
+}
+function normalizeIdentitySubdir(subdir) {
+    if (subdir === undefined)
+        return null;
+    if (typeof subdir !== 'string' || subdir.trim() === '' || subdir.includes('\\')) {
+        throw new Error('Invalid catalog source subdir: expected a relative POSIX path.');
+    }
+    const normalized = path.posix.normalize(subdir);
+    if (path.posix.isAbsolute(subdir)
+        || normalized === '.'
+        || normalized === '..'
+        || normalized.startsWith('../')) {
+        throw new Error('Invalid catalog source subdir: path must stay inside the source.');
+    }
+    return normalized.replace(/^\.\//, '').replace(/\/$/, '');
+}
+async function realpathCatalogDirectory(value) {
+    const location = await fs.realpath(value);
+    const stat = await fs.stat(location);
+    if (!stat.isDirectory()) {
+        throw new Error('Invalid catalog path source: expected a directory.');
+    }
+    return location;
+}
+export async function canonicalizeCatalogPath(value, cwd) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error('Invalid catalog path source: expected a non-empty path.');
+    }
+    if (typeof cwd !== 'string' || cwd.trim() === '' || !path.isAbsolute(cwd)) {
+        throw new Error('Invalid catalog path source cwd: expected an absolute path.');
+    }
+    return realpathCatalogDirectory(path.resolve(cwd, value));
+}
+export async function calculateCatalogSourceIdentity(source) {
+    let location;
+    if (source.type === 'git') {
+        location = canonicalizeCatalogGitUrl(source.url);
+    }
+    else if (source.type === 'path') {
+        if (!path.isAbsolute(source.path)) {
+            throw new Error('Invalid catalog path source: expected a canonical absolute path.');
+        }
+        location = path.normalize(source.path);
+    }
+    else {
+        throw new Error('Invalid catalog source type: expected "git" or "path".');
+    }
+    const input = JSON.stringify({
+        version: CATALOG_SOURCE_IDENTITY_VERSION,
+        type: source.type,
+        location,
+        subdir: normalizeIdentitySubdir(source.type === 'git' ? source.subdir : undefined),
+    });
+    return `sha256:${crypto.createHash('sha256').update(input).digest('hex')}`;
+}
+//# sourceMappingURL=catalog-source-identity.js.map

package/dist/src/utils/catalog-source-identity.js.map

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

package/dist/src/utils/catalog-source-presentation.d.ts

@@ -0,0 +1 @@
+export declare function projectCatalogSourceLocation(value: string): string;

package/dist/src/utils/catalog-source-presentation.js

@@ -0,0 +1,32 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const SCP_LOCATION = /^(?:[^@/\s]+@)?([^/:\s]+):(.+)$/u;
+function privateLocationLabel(value) {
+    const basename = path.basename(value.replace(/[\\/]+$/u, ''));
+    return basename && basename !== path.parse(value).root
+        ? `已选择本地位置（${basename}）`
+        : '已选择本地位置';
+}
+export function projectCatalogSourceLocation(value) {
+    if (path.isAbsolute(value))
+        return privateLocationLabel(value);
+    try {
+        const url = new URL(value);
+        if (url.protocol === 'file:')
+            return privateLocationLabel(fileURLToPath(url));
+        url.username = '';
+        url.password = '';
+        url.search = '';
+        url.hash = '';
+        return url.toString().replace(/\/$/u, '');
+    }
+    catch {
+        if (value.includes('://'))
+            return '已输入远程来源';
+        const scp = SCP_LOCATION.exec(value);
+        return scp
+            ? `ssh://${scp[1]}/${scp[2].split(/[?#]/u, 1)[0].replace(/^\/+|\/+$/gu, '')}`
+            : '已输入来源位置';
+    }
+}
+//# sourceMappingURL=catalog-source-presentation.js.map

package/dist/src/utils/catalog-source-presentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-source-presentation.js","sourceRoot":"","sources":["../../../src/utils/catalog-source-presentation.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,YAAY,GAAG,kCAAkC,CAAC;AAExD,SAAS,oBAAoB,CAAC,KAAa;IACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC;IAC9D,OAAO,QAAQ,IAAI,QAAQ,KAAK,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI;QACpD,CAAC,CAAC,WAAW,QAAQ,GAAG;QACxB,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,KAAa;IACxD,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;QAAE,OAAO,oBAAoB,CAAC,KAAK,CAAC,CAAC;IAC/D,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;QAC3B,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO;YAAE,OAAO,oBAAoB,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC;QAC9E,GAAG,CAAC,QAAQ,GAAG,EAAE,CAAC;QAClB,GAAG,CAAC,QAAQ,GAAG,EAAE,CAAC;QAClB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC;QAChB,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC;QACd,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAC5C,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrC,OAAO,GAAG;YACR,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,EAAE;YAC/E,CAAC,CAAC,SAAS,CAAC;IAChB,CAAC;AACH,CAAC"}

package/dist/src/utils/catalog-source-references.d.ts

@@ -0,0 +1,65 @@
+import type { PlatformName, Scope } from '../types.js';
+export type CatalogSourceReferenceKind = 'legacyOwner' | 'namespacedOwner' | 'legacyConfig' | 'namespacedConfig' | 'legacyLifecycle' | 'namespacedLifecycle' | 'legacyMarketplace' | 'namespacedMarketplace';
+export interface CatalogSourceReference {
+    kind: CatalogSourceReferenceKind;
+    location: string;
+    pluginName?: string;
+    sourceId?: string;
+    sourceIdentity?: string;
+    marketplaceName?: string;
+    platform?: string;
+    scope?: string;
+    projectKey?: string | null;
+}
+export declare function canonicalMarketplaceRegistrationNames(references: readonly CatalogSourceReference[], sourceId: string): string[];
+export interface CatalogSourceReferenceInventory {
+    inventorySchemaVersion: 1;
+    references: CatalogSourceReference[];
+    errors: CatalogSourceInventoryError[];
+}
+export interface CatalogSourceInventoryError {
+    code: 'stateInventoryFailed';
+    kind: string;
+    location: string;
+    message: string;
+    relevance: {
+        global: true;
+    } | {
+        global: false;
+        sourceId?: string;
+        pluginName?: string;
+        platform?: PlatformName;
+        scope?: Scope;
+        projectLocationKey?: string;
+    };
+}
+export declare function inventoryLegacyOwnerReferences(options: {
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<CatalogSourceReferenceInventory>;
+export declare function inventoryLegacyConfigReferences(options: {
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<CatalogSourceReferenceInventory>;
+export declare function inventoryCatalogSourceReferences(options: {
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+    includeHistoricalProjects?: boolean;
+}): Promise<CatalogSourceReferenceInventory>;
+export declare class LegacyCatalogStateUnsupportedError extends Error {
+    readonly code = "legacyStateUnsupported";
+    readonly inventory: CatalogSourceReferenceInventory;
+    constructor(inventory: CatalogSourceReferenceInventory);
+}
+export declare class CatalogSourceReferencedError extends Error {
+    readonly code = "catalogSourceInUse";
+    readonly inventory: CatalogSourceReferenceInventory;
+    constructor(inventory: CatalogSourceReferenceInventory);
+}
+export declare class CatalogSourceInventoryIncompleteError extends Error {
+    readonly code = "stateInventoryFailed";
+    readonly inventory: CatalogSourceReferenceInventory;
+    constructor(inventory: CatalogSourceReferenceInventory);
+}
+export declare function assertCatalogSourceInventoryComplete(inventory: CatalogSourceReferenceInventory): void;
+export declare function assertCatalogSourceReferencesSupported(inventory: CatalogSourceReferenceInventory): void;