@lesliechan721/aw-plugin-core 0.1.0-beta.1

package/dist/workspace.js

@@ -0,0 +1,963 @@
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import fs from 'fs-extra';
+import { assertCatalogVersion, assertStrictSemVer, compareStrictSemVer, MARKETPLACE_SOURCE_PATH, SOURCE_MANIFEST_PATH, createMarketplaceManifest, createMarketplaceManifestEntry, normalizeCatalogManifestBase, normalizeCatalogMarketplaceIdentity, normalizeCatalogManifestEntries, normalizeManifestDigestInput, readMarketplaceSourceMeta, readPluginManifest, validatePlatformManifestProjection, } from './manifest-contract.js';
+import { resolveSupportedPlatforms } from './platform-support.js';
+import { appendCatalogToPluginReleaseLedger, assertStablePluginVersion, PLUGIN_RELEASE_LEDGER_FILENAME, PLUGIN_RELEASE_LEDGER_SCHEMA_VERSION, resolveBetaPluginVersionOverrides, validatePluginReleaseLedgerAgainstManifest, } from './plugin-release.js';
+export const DEFAULT_WORKSPACE_CATALOG_VERSION = '0.1.0';
+export const DEFAULT_CATALOG_OUTPUT_PATH = path.join('.aw', 'catalog');
+export const DEFAULT_PUBLISHED_CATALOG_OUTPUT_PATH = path.join('.aw', 'publish', 'catalog');
+export const DEFAULT_PLUGIN_OUTPUT_PATH = path.join('.aw', 'plugins');
+export const CATALOG_MANIFEST_FILENAME = 'catalog-manifest.json';
+export const GENERATED_OUTPUT_MARKER_FILENAME = '.aw-generated.json';
+export const WORKSPACE_MARKER_FILENAME = '.aw-workspace.json';
+function isInside(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (relative !== '..'
+        && !relative.startsWith(`..${path.sep}`)
+        && !path.isAbsolute(relative));
+}
+async function assertDirectoryWithoutSymlinks(directory, label) {
+    const requested = path.resolve(directory);
+    const stat = await fs.lstat(requested).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (!stat?.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error(`${label} must be a regular non-symbolic-link directory: ${requested}`);
+    }
+    return fs.realpath(requested);
+}
+async function assertNoSymlinkPath(root, target) {
+    const relative = path.relative(root, target);
+    let current = root;
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        const stat = await fs.lstat(current).catch((error) => {
+            if (error.code === 'ENOENT')
+                return null;
+            throw error;
+        });
+        if (!stat)
+            return;
+        if (stat.isSymbolicLink()) {
+            throw new Error(`Output path must not contain symbolic links: ${current}`);
+        }
+    }
+}
+export async function resolveWorkspaceOutputPath(options) {
+    const workspaceRoot = await assertDirectoryWithoutSymlinks(options.workspaceRoot, 'Workspace root');
+    const outputRoot = path.resolve(workspaceRoot, options.outputPath);
+    if (!isInside(workspaceRoot, outputRoot) || outputRoot === workspaceRoot) {
+        throw new Error(`Output must be inside the workspace: ${outputRoot}`);
+    }
+    await assertNoSymlinkPath(workspaceRoot, outputRoot);
+    const protectedRoots = [
+        path.join(workspaceRoot, '.aw'),
+        path.join(workspaceRoot, '.git'),
+        path.join(workspaceRoot, 'plugins'),
+    ];
+    for (const protectedRoot of protectedRoots) {
+        if (protectedRoot.endsWith(`${path.sep}.aw`) && outputRoot !== protectedRoot)
+            continue;
+        if (isInside(protectedRoot, outputRoot) || isInside(outputRoot, protectedRoot)) {
+            throw new Error(`Output overlaps a protected workspace path: ${outputRoot}`);
+        }
+    }
+    const otherGeneratedRoot = path.join(workspaceRoot, options.kind === 'catalog' ? DEFAULT_PLUGIN_OUTPUT_PATH : DEFAULT_CATALOG_OUTPUT_PATH);
+    if (options.kind && (isInside(otherGeneratedRoot, outputRoot) || isInside(outputRoot, otherGeneratedRoot))) {
+        throw new Error(`Output overlaps a different generated output kind: ${outputRoot}`);
+    }
+    return { workspaceRoot, outputRoot };
+}
+function safeWorkspaceName(workspaceRoot) {
+    const normalized = path.basename(workspaceRoot).toLowerCase()
+        .replace(/[^a-z0-9]+/gu, '-')
+        .replace(/^-+|-+$/gu, '');
+    return normalized || 'aw-workspace';
+}
+function workspaceMetadata(options, workspaceRoot) {
+    const workspaceName = safeWorkspaceName(workspaceRoot);
+    return {
+        owner: {
+            name: options.ownerName?.trim() || workspaceName,
+            url: options.ownerUrl?.trim() || `https://example.invalid/aw-workspaces/${workspaceName}`,
+        },
+        interface: {
+            displayName: options.displayName?.trim() || workspaceName,
+        },
+        catalog: {
+            version: assertCatalogVersion(options.catalogVersion ?? DEFAULT_WORKSPACE_CATALOG_VERSION, 'catalog version'),
+        },
+    };
+}
+async function writeJsonAtomic(filePath, value) {
+    const temporary = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${crypto.randomUUID()}.tmp`);
+    await fs.writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { flag: 'wx' });
+    try {
+        await fs.rename(temporary, filePath);
+    }
+    catch (error) {
+        await fs.remove(temporary);
+        throw error;
+    }
+}
+async function writeTextAtomic(filePath, value) {
+    const temporary = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${crypto.randomUUID()}.tmp`);
+    await fs.writeFile(temporary, value, { flag: 'wx' });
+    try {
+        await fs.rename(temporary, filePath);
+    }
+    catch (error) {
+        await fs.remove(temporary);
+        throw error;
+    }
+}
+function workspaceIdentity(workspaceRoot) {
+    return sha256(`aw-plugin-workspace-v1\0${path.resolve(workspaceRoot)}`);
+}
+function workspaceScaffoldMarker(metadata) {
+    return {
+        schemaVersion: 1,
+        kind: 'aw-plugin-workspace',
+        workspaceIdentity: sha256(crypto.randomUUID()),
+        sourceIdentity: sha256(stableStringify(metadata)),
+    };
+}
+function validateWorkspaceScaffoldMarker(value) {
+    const marker = value;
+    const digestPattern = /^sha256:[0-9a-f]{64}$/u;
+    if (!marker
+        || typeof marker !== 'object'
+        || Array.isArray(marker)
+        || !isDeepStrictEqual(Object.keys(marker).sort(), [
+            'kind', 'schemaVersion', 'sourceIdentity', 'workspaceIdentity',
+        ])
+        || marker.schemaVersion !== 1
+        || marker.kind !== 'aw-plugin-workspace'
+        || typeof marker.workspaceIdentity !== 'string'
+        || !digestPattern.test(marker.workspaceIdentity)
+        || typeof marker.sourceIdentity !== 'string'
+        || !digestPattern.test(marker.sourceIdentity)) {
+        throw new Error('Invalid workspace scaffold marker.');
+    }
+    return { workspaceIdentity: marker.workspaceIdentity };
+}
+async function readWorkspaceOwnershipIdentity(workspaceRoot) {
+    const markerPath = path.join(workspaceRoot, WORKSPACE_MARKER_FILENAME);
+    if (!await fs.pathExists(markerPath))
+        return workspaceIdentity(workspaceRoot);
+    return validateWorkspaceScaffoldMarker(await readRegularJson(markerPath, 'Workspace marker')).workspaceIdentity;
+}
+async function readRegularJson(filePath, label) {
+    const stat = await fs.lstat(filePath).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (!stat?.isFile() || stat.isSymbolicLink()) {
+        throw new Error(`${label} must be a regular non-symbolic-link file: ${filePath}`);
+    }
+    return fs.readJson(filePath);
+}
+export async function initializePluginWorkspace(options) {
+    const workspaceRoot = await assertDirectoryWithoutSymlinks(options.workspaceRoot, 'Workspace root');
+    const pluginsRoot = path.join(workspaceRoot, 'plugins');
+    const metadataPath = path.join(workspaceRoot, MARKETPLACE_SOURCE_PATH);
+    const markerPath = path.join(workspaceRoot, WORKSPACE_MARKER_FILENAME);
+    const metadata = workspaceMetadata(options, workspaceRoot);
+    const existingMetadata = await fs.pathExists(metadataPath);
+    const existingMarker = await fs.pathExists(markerPath);
+    if ((existingMetadata || existingMarker) && !options.force) {
+        throw new Error(`Workspace catalog scaffold already exists: ${workspaceRoot}`);
+    }
+    if (await fs.pathExists(pluginsRoot)) {
+        const stat = await fs.lstat(pluginsRoot);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            throw new Error(`Workspace plugins path must be a regular directory: ${pluginsRoot}`);
+        }
+        const entries = (await fs.readdir(pluginsRoot)).filter((entry) => entry !== path.basename(metadataPath));
+        if (entries.length > 0 && !existingMarker) {
+            throw new Error(`Refusing to initialize over a non-managed plugins directory: ${pluginsRoot}`);
+        }
+    }
+    if (existingMetadata) {
+        const current = await readMarketplaceSourceMeta(workspaceRoot);
+        if (!isDeepStrictEqual(current, metadata)) {
+            throw new Error(`Refusing to replace different workspace catalog metadata: ${metadataPath}`);
+        }
+    }
+    const expectedMarker = workspaceScaffoldMarker(metadata);
+    if (existingMarker) {
+        const currentMarker = await readRegularJson(markerPath, 'Workspace marker');
+        try {
+            validateWorkspaceScaffoldMarker(currentMarker);
+        }
+        catch {
+            throw new Error(`Refusing to replace a workspace scaffold with a different identity: ${workspaceRoot}`);
+        }
+    }
+    const gitignorePath = path.join(workspaceRoot, '.gitignore');
+    const gitignoreExists = await fs.pathExists(gitignorePath);
+    let previousGitignore = null;
+    if (gitignoreExists) {
+        const stat = await fs.lstat(gitignorePath);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new Error(`Workspace .gitignore must be a regular file: ${gitignorePath}`);
+        }
+        previousGitignore = await fs.readFile(gitignorePath, 'utf8');
+    }
+    await fs.ensureDir(pluginsRoot);
+    try {
+        if (previousGitignore === null) {
+            await fs.writeFile(gitignorePath, '.aw/\n', { flag: 'wx' });
+        }
+        else if (!previousGitignore.split(/\r?\n/u).includes('.aw/')) {
+            const separator = previousGitignore.length === 0 || previousGitignore.endsWith('\n') ? '' : '\n';
+            await writeTextAtomic(gitignorePath, `${previousGitignore}${separator}.aw/\n`);
+        }
+        if (!existingMetadata)
+            await writeJsonAtomic(metadataPath, metadata);
+        if (!existingMarker)
+            await writeJsonAtomic(markerPath, expectedMarker);
+    }
+    catch (error) {
+        if (!existingMetadata)
+            await fs.remove(metadataPath);
+        if (!existingMarker)
+            await fs.remove(markerPath);
+        if (previousGitignore === null)
+            await fs.remove(gitignorePath);
+        else
+            await writeTextAtomic(gitignorePath, previousGitignore);
+        if ((await fs.readdir(pluginsRoot)).length === 0)
+            await fs.remove(pluginsRoot);
+        throw error;
+    }
+    return { workspaceRoot, metadataPath, metadata };
+}
+export async function readPluginWorkspace(workspaceRoot, options = {}) {
+    const root = await assertDirectoryWithoutSymlinks(workspaceRoot, 'Workspace root');
+    const metadataPath = path.join(root, MARKETPLACE_SOURCE_PATH);
+    await readRegularJson(metadataPath, 'Workspace catalog metadata');
+    if (!isInside(root, await fs.realpath(metadataPath)))
+        throw new Error('Workspace catalog metadata resolves outside the workspace.');
+    const metadata = await readMarketplaceSourceMeta(root);
+    const pluginsRoot = await assertDirectoryWithoutSymlinks(path.join(root, 'plugins'), 'Workspace plugins directory');
+    if (!isInside(root, pluginsRoot))
+        throw new Error('Workspace plugins directory resolves outside the workspace.');
+    const plugins = [];
+    for (const entry of (await fs.readdir(pluginsRoot, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name))) {
+        if (entry.name === path.basename(metadataPath) || !entry.isDirectory()) {
+            if (entry.isSymbolicLink())
+                throw new Error(`Workspace plugin source must not be a symbolic link: ${entry.name}`);
+            continue;
+        }
+        const pluginRoot = path.join(pluginsRoot, entry.name);
+        const pluginStat = await fs.lstat(pluginRoot);
+        if (!pluginStat.isDirectory() || pluginStat.isSymbolicLink() || !isInside(root, await fs.realpath(pluginRoot))) {
+            throw new Error(`Workspace plugin source must be a regular in-workspace directory: ${pluginRoot}`);
+        }
+        const manifestDir = path.join(pluginRoot, path.dirname(SOURCE_MANIFEST_PATH));
+        const manifestPath = path.join(pluginRoot, SOURCE_MANIFEST_PATH);
+        await assertDirectoryWithoutSymlinks(manifestDir, 'Plugin manifest directory');
+        await readRegularJson(manifestPath, 'Plugin manifest');
+        if (!isInside(root, await fs.realpath(manifestPath)))
+            throw new Error(`Plugin manifest resolves outside the workspace: ${manifestPath}`);
+        const plugin = await readPluginManifest(pluginRoot, { mode: 'source', reservedImports: options.reservedImports });
+        if (plugin.manifest.name !== entry.name) {
+            throw new Error(`Plugin directory name ${JSON.stringify(entry.name)} must match manifest name ${JSON.stringify(plugin.manifest.name)}.`);
+        }
+        plugins.push(plugin);
+    }
+    return { workspaceRoot: root, metadataPath, metadata, plugins };
+}
+export async function setWorkspaceCatalogVersion(workspaceRoot, version, options = {}) {
+    const current = await readPluginWorkspace(workspaceRoot, options);
+    const metadata = {
+        ...current.metadata,
+        catalog: { version: assertCatalogVersion(version, 'catalog version') },
+    };
+    await writeJsonAtomic(current.metadataPath, metadata);
+    return metadata;
+}
+export function deriveCatalogChannel(version) {
+    const parsed = assertCatalogVersion(version, 'catalog version');
+    return parsed.includes('-') ? 'beta' : 'latest';
+}
+async function replaceGeneratedOutput(options) {
+    const parent = path.dirname(options.outputRoot);
+    await fs.ensureDir(parent);
+    const stagingRoot = path.join(parent, `.${path.basename(options.outputRoot)}.aw-staging-${crypto.randomUUID()}`);
+    const backupRoot = path.join(parent, `.${path.basename(options.outputRoot)}.aw-backup-${crypto.randomUUID()}`);
+    const exists = await fs.pathExists(options.outputRoot);
+    if (exists && !options.force)
+        throw new Error(`Output already exists: ${options.outputRoot}`);
+    if (exists && options.assertReplaceable)
+        await options.assertReplaceable(options.outputRoot);
+    await fs.ensureDir(stagingRoot);
+    try {
+        await options.build(stagingRoot);
+        await options.validate(stagingRoot);
+        if (exists)
+            await fs.rename(options.outputRoot, backupRoot);
+        try {
+            await fs.rename(stagingRoot, options.outputRoot);
+        }
+        catch (error) {
+            if (exists)
+                await fs.rename(backupRoot, options.outputRoot);
+            throw error;
+        }
+        if (exists)
+            await fs.remove(backupRoot);
+    }
+    catch (error) {
+        await fs.remove(stagingRoot);
+        throw error;
+    }
+}
+function assertDependencyGraph(plugins) {
+    const byName = new Map(plugins.map((plugin) => [plugin.manifest.name, plugin]));
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (name) => {
+        if (visiting.has(name))
+            throw new Error(`Plugin dependency cycle includes ${JSON.stringify(name)}.`);
+        if (visited.has(name))
+            return;
+        const plugin = byName.get(name);
+        if (!plugin)
+            throw new Error(`Missing same-source plugin dependency ${JSON.stringify(name)}.`);
+        visiting.add(name);
+        for (const dependency of plugin.manifest.dependencies ?? [])
+            visit(dependency);
+        visiting.delete(name);
+        visited.add(name);
+    };
+    for (const plugin of plugins)
+        visit(plugin.manifest.name);
+}
+function orderPlugins(plugins) {
+    assertDependencyGraph(plugins);
+    const result = [];
+    const seen = new Set();
+    const byName = new Map(plugins.map((plugin) => [plugin.manifest.name, plugin]));
+    const visit = (plugin) => {
+        if (seen.has(plugin.manifest.name))
+            return;
+        for (const name of [...(plugin.manifest.dependencies ?? [])].sort())
+            visit(byName.get(name));
+        seen.add(plugin.manifest.name);
+        result.push(plugin);
+    };
+    for (const plugin of [...plugins].sort((left, right) => left.manifest.name.localeCompare(right.manifest.name)))
+        visit(plugin);
+    return result;
+}
+function stableStringify(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function sha256(value) {
+    return `sha256:${crypto.createHash('sha256').update(value).digest('hex')}`;
+}
+function publishedContentDigest(manifest) {
+    return sha256(stableStringify({
+        schemaIdentity: { schemaVersion: manifest.schemaVersion },
+        marketplaceMetadata: {
+            name: 'aw',
+            owner: manifest.marketplace.owner,
+            interface: manifest.marketplace.interface,
+        },
+        compatibility: manifest.compatibility,
+        plugins: manifest.entries.map((entry) => ({
+            name: entry.name,
+            targetVersion: entry.version.replace(/-beta\.[1-9]\d*$/u, ''),
+            contentDigest: entry.contentDigest,
+        })).sort((left, right) => left.name.localeCompare(right.name)),
+    }));
+}
+function sourceIdentity(metadata, plugins) {
+    return sha256(stableStringify({
+        metadata,
+        plugins: [...plugins]
+            .sort((left, right) => left.manifest.name.localeCompare(right.manifest.name))
+            .map((plugin) => plugin.manifest),
+    }));
+}
+function generatedOutputMarker(options) {
+    return {
+        schemaVersion: 1,
+        kind: options.kind,
+        workspaceIdentity: options.workspaceIdentity,
+        sourceIdentity: options.sourceIdentity,
+        ...(options.sourceName ? { sourceName: options.sourceName } : {}),
+    };
+}
+async function listBundleFiles(root, relative = '') {
+    const result = [];
+    for (const entry of await fs.readdir(path.join(root, relative), { withFileTypes: true })) {
+        const child = relative ? path.posix.join(relative, entry.name) : entry.name;
+        if (entry.isDirectory())
+            result.push(...await listBundleFiles(root, child));
+        else
+            result.push(child);
+    }
+    return result.sort();
+}
+async function catalogPathRecord(root, relative, versionNeutral) {
+    const filePath = path.join(root, ...relative.split('/'));
+    const stat = await fs.lstat(filePath);
+    if (stat.isSymbolicLink()) {
+        return { path: relative, kind: 'symlink', mode: '120000', digest: sha256(await fs.readlink(filePath)) };
+    }
+    if (!stat.isFile())
+        throw new Error(`Catalog digest path must be a regular file or symlink: ${filePath}.`);
+    const manifests = new Set(['.agents-plugin/plugin.json', '.claude-plugin/plugin.json', '.codex-plugin/plugin.json']);
+    const digest = versionNeutral && manifests.has(relative)
+        ? sha256(stableStringify({ ...await fs.readJson(filePath), version: '<plugin-version>' }))
+        : sha256(await fs.readFile(filePath));
+    return { path: relative, kind: 'file', mode: (stat.mode & 0o100) === 0 ? '100644' : '100755', digest };
+}
+async function calculateEntryDigest(root, versionNeutral) {
+    const files = await listBundleFiles(root);
+    return sha256(stableStringify(await Promise.all(files.map((file) => catalogPathRecord(root, file, versionNeutral)))));
+}
+async function expectedCatalogEntry(plugin, pluginRoot) {
+    return {
+        ...createMarketplaceManifestEntry(plugin),
+        version: plugin.manifest.version,
+        compatibility: plugin.manifest.compatibility,
+        artifactDigest: await calculateEntryDigest(pluginRoot, false),
+        manifestDigest: sha256(normalizeManifestDigestInput(plugin.manifest)),
+        contentDigest: await calculateEntryDigest(pluginRoot, true),
+    };
+}
+function normalizeCatalogRelease(raw, catalogVersion) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error('Invalid catalog manifest release: expected an object.');
+    }
+    const release = raw;
+    if (release.state === 'development') {
+        if (Object.keys(release).join('\0') !== 'state') {
+            throw new Error('Invalid development catalog release: unknown field.');
+        }
+        return { state: 'development' };
+    }
+    const allowed = new Set(['state', 'targetVersion', 'planId', 'sourceHead', 'contentDigest']);
+    if (release.state !== 'published' || Object.keys(release).some((key) => !allowed.has(key))) {
+        throw new Error('Invalid published catalog release.');
+    }
+    const targetVersion = assertStrictSemVer(release.targetVersion, 'catalog release targetVersion');
+    if (targetVersion.includes('-') || targetVersion.includes('+')) {
+        throw new Error('Invalid catalog release targetVersion: expected a stable version.');
+    }
+    if (targetVersion !== catalogVersion.replace(/-beta\.[1-9]\d*$/u, '')) {
+        throw new Error('Invalid catalog release targetVersion: must match catalogVersion.');
+    }
+    const digestPattern = /^sha256:[0-9a-f]{64}$/u;
+    if (typeof release.planId !== 'string' || !digestPattern.test(release.planId)) {
+        throw new Error('Invalid catalog release planId.');
+    }
+    if (typeof release.contentDigest !== 'string' || !digestPattern.test(release.contentDigest)) {
+        throw new Error('Invalid catalog release contentDigest.');
+    }
+    if (typeof release.sourceHead !== 'string' || !/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u.test(release.sourceHead)) {
+        throw new Error('Invalid catalog release sourceHead.');
+    }
+    return {
+        state: 'published',
+        targetVersion,
+        planId: release.planId,
+        sourceHead: release.sourceHead,
+        contentDigest: release.contentDigest,
+    };
+}
+export async function buildWorkspaceCatalog(options) {
+    const workspace = await readPluginWorkspace(options.workspaceRoot, { reservedImports: options.reservedImports });
+    const plugins = orderPlugins(workspace.plugins);
+    const resolved = await resolveWorkspaceOutputPath({
+        workspaceRoot: workspace.workspaceRoot,
+        outputPath: options.outputPath ?? DEFAULT_CATALOG_OUTPUT_PATH,
+        kind: 'catalog',
+    });
+    const catalogVersion = workspace.metadata.catalog.version;
+    const channel = deriveCatalogChannel(catalogVersion);
+    const pluginNames = plugins.map((plugin) => plugin.manifest.name).sort();
+    const identity = sourceIdentity(workspace.metadata, plugins);
+    const marker = generatedOutputMarker({
+        kind: 'catalog',
+        workspaceIdentity: await readWorkspaceOwnershipIdentity(workspace.workspaceRoot),
+        sourceIdentity: identity,
+    });
+    await replaceGeneratedOutput({
+        outputRoot: resolved.outputRoot,
+        force: options.force === true,
+        build: async (stagingRoot) => {
+            const bundledPlugins = [];
+            for (const plugin of plugins) {
+                const closure = dependencyClosure(plugin, plugins);
+                const outputRoot = path.join(stagingRoot, 'plugins', plugin.manifest.name);
+                await fs.ensureDir(outputRoot);
+                await options.adapter.build({
+                    workspaceRoot: workspace.workspaceRoot,
+                    plugin,
+                    plugins,
+                    dependencies: closure.slice(0, -1),
+                    outputRoot,
+                });
+                bundledPlugins.push(await readPluginManifest(outputRoot, { mode: 'bundle' }));
+            }
+            const byPlatform = (platform) => bundledPlugins
+                .filter((plugin) => resolveSupportedPlatforms(plugin.manifest).has(platform))
+                .sort((left, right) => left.manifest.name.localeCompare(right.manifest.name));
+            await fs.outputJson(path.join(stagingRoot, '.agents', 'plugins', 'marketplace.json'), createMarketplaceManifest(workspace.metadata, byPlatform('codex')), { spaces: 2 });
+            await fs.outputJson(path.join(stagingRoot, '.claude-plugin', 'marketplace.json'), createMarketplaceManifest(workspace.metadata, byPlatform('claude')), { spaces: 2 });
+            let minVersion = '0.0.0';
+            for (const plugin of bundledPlugins) {
+                const candidate = plugin.manifest.compatibility.aw.minVersion;
+                if (compareStrictSemVer(candidate, minVersion) > 0)
+                    minVersion = candidate;
+            }
+            const entries = await Promise.all([...bundledPlugins]
+                .sort((left, right) => left.manifest.name.localeCompare(right.manifest.name))
+                .map((plugin) => expectedCatalogEntry(plugin, plugin.rootDir)));
+            const manifest = {
+                schemaVersion: 4,
+                catalogVersion,
+                channel,
+                compatibility: { aw: { minVersion } },
+                marketplace: {
+                    owner: workspace.metadata.owner,
+                    interface: workspace.metadata.interface,
+                },
+                release: { state: 'development' },
+                entries,
+            };
+            await fs.writeJson(path.join(stagingRoot, CATALOG_MANIFEST_FILENAME), manifest, { spaces: 2 });
+            await fs.writeJson(path.join(stagingRoot, GENERATED_OUTPUT_MARKER_FILENAME), marker, { spaces: 2 });
+        },
+        validate: async (stagingRoot) => { await validateCatalogSnapshot(stagingRoot); },
+        assertReplaceable: async (existingRoot) => {
+            await validateCatalogSnapshot(existingRoot);
+            await assertGeneratedOutput(existingRoot, marker);
+        },
+    });
+    return { outputRoot: resolved.outputRoot, catalogVersion, channel, pluginNames };
+}
+async function rewritePublishedPluginVersions(snapshotRoot, overrides) {
+    for (const [pluginName, version] of Object.entries(overrides)) {
+        assertStrictSemVer(version, `${pluginName} published version`);
+        for (const relative of [
+            '.agents-plugin/plugin.json',
+            '.claude-plugin/plugin.json',
+            '.codex-plugin/plugin.json',
+        ]) {
+            const manifestPath = path.join(snapshotRoot, 'plugins', pluginName, relative);
+            if (!(await fs.pathExists(manifestPath)))
+                continue;
+            const manifest = await fs.readJson(manifestPath);
+            await fs.writeFile(manifestPath, `${JSON.stringify({ ...manifest, version }, null, 2)}\n`);
+        }
+    }
+}
+export async function validatePublishedCatalogSnapshot(snapshotDirectory) {
+    const validation = await validateCatalogSnapshot(snapshotDirectory);
+    if (validation.manifest.release.state !== 'published') {
+        throw new Error('Published Catalog snapshot must have release.state published.');
+    }
+    if (!validation.ledger)
+        throw new Error('Published Catalog snapshot must include a plugin release ledger.');
+    return { ...validation, ledger: validation.ledger };
+}
+export async function preparePublishedWorkspaceCatalog(options) {
+    if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u.test(options.sourceHead)) {
+        throw new Error('Published Catalog sourceHead must be a committed Git object ID.');
+    }
+    const workspace = await readPluginWorkspace(options.workspaceRoot, { reservedImports: options.reservedImports });
+    for (const plugin of workspace.plugins) {
+        assertStablePluginVersion(plugin.manifest.version, `${plugin.manifest.name} source version`);
+    }
+    const catalogVersion = workspace.metadata.catalog.version;
+    const channel = deriveCatalogChannel(catalogVersion);
+    const previous = options.previousSnapshotRoot
+        ? await validatePublishedCatalogSnapshot(options.previousSnapshotRoot)
+        : null;
+    if (previous && compareStrictSemVer(catalogVersion, previous.manifest.catalogVersion) <= 0) {
+        throw new Error(`Catalog version ${catalogVersion} must be higher than published ${previous.manifest.catalogVersion}.`);
+    }
+    const previousLedger = previous?.ledger ?? {
+        schemaVersion: PLUGIN_RELEASE_LEDGER_SCHEMA_VERSION,
+        records: [],
+    };
+    const temporaryRelative = path.join('.aw', 'publish', `.catalog-preparation-${crypto.randomUUID()}`);
+    const finalRelative = options.outputPath
+        ?? `${DEFAULT_PUBLISHED_CATALOG_OUTPUT_PATH}-v${catalogVersion}`;
+    let temporaryRoot = path.resolve(workspace.workspaceRoot, temporaryRelative);
+    try {
+        const built = await buildWorkspaceCatalog({
+            workspaceRoot: workspace.workspaceRoot,
+            outputPath: temporaryRelative,
+            adapter: options.adapter,
+            reservedImports: options.reservedImports,
+        });
+        temporaryRoot = built.outputRoot;
+        const development = await validateCatalogSnapshot(temporaryRoot);
+        const contentDigests = new Map(development.manifest.entries.map((entry) => [entry.name, entry.contentDigest]));
+        const overrides = channel === 'beta'
+            ? resolveBetaPluginVersionOverrides({
+                plugins: workspace.plugins,
+                contentDigests,
+                ledger: previousLedger,
+            })
+            : Object.fromEntries(workspace.plugins.map((plugin) => [plugin.manifest.name, plugin.manifest.version]));
+        await rewritePublishedPluginVersions(temporaryRoot, overrides);
+        const bundledPlugins = await Promise.all(workspace.plugins.map((plugin) => readPluginManifest(path.join(temporaryRoot, 'plugins', plugin.manifest.name), { mode: 'bundle' })));
+        const entries = await Promise.all(bundledPlugins.sort((left, right) => left.manifest.name.localeCompare(right.manifest.name))
+            .map((plugin) => expectedCatalogEntry(plugin, plugin.rootDir)));
+        const manifestWithoutRelease = {
+            ...development.manifest,
+            entries,
+        };
+        const contentDigest = publishedContentDigest(manifestWithoutRelease);
+        const manifest = {
+            ...manifestWithoutRelease,
+            release: {
+                state: 'published',
+                targetVersion: catalogVersion.replace(/-beta\.[1-9]\d*$/u, ''),
+                planId: contentDigest,
+                sourceHead: options.sourceHead,
+                contentDigest,
+            },
+        };
+        const ledger = appendCatalogToPluginReleaseLedger({
+            previous: previousLedger,
+            manifest,
+            contentDigests,
+        });
+        await Promise.all([
+            fs.writeFile(path.join(temporaryRoot, CATALOG_MANIFEST_FILENAME), `${JSON.stringify(manifest, null, 2)}\n`),
+            fs.writeFile(path.join(temporaryRoot, PLUGIN_RELEASE_LEDGER_FILENAME), `${JSON.stringify(ledger, null, 2)}\n`),
+        ]);
+        const prepared = await validatePublishedCatalogSnapshot(temporaryRoot);
+        const resolved = await resolveWorkspaceOutputPath({
+            workspaceRoot: workspace.workspaceRoot,
+            outputPath: finalRelative,
+            kind: 'catalog',
+        });
+        const marker = await fs.readJson(path.join(temporaryRoot, GENERATED_OUTPUT_MARKER_FILENAME));
+        await replaceGeneratedOutput({
+            outputRoot: resolved.outputRoot,
+            force: true,
+            build: (stagingRoot) => fs.copy(temporaryRoot, stagingRoot, { dereference: false }),
+            validate: async (stagingRoot) => { await validatePublishedCatalogSnapshot(stagingRoot); },
+            assertReplaceable: async (existingRoot) => {
+                await validatePublishedCatalogSnapshot(existingRoot);
+                await assertGeneratedOutput(existingRoot, marker);
+            },
+        });
+        return {
+            outputRoot: resolved.outputRoot,
+            catalogVersion,
+            channel,
+            pluginNames: built.pluginNames,
+            snapshotDigest: prepared.snapshotDigest,
+            contentDigest,
+            planId: contentDigest,
+        };
+    }
+    finally {
+        await fs.remove(temporaryRoot);
+    }
+}
+function dependencyClosure(plugin, all) {
+    const byName = new Map(all.map((entry) => [entry.manifest.name, entry]));
+    const result = [];
+    const visited = new Set();
+    const visit = (entry) => {
+        if (visited.has(entry.manifest.name))
+            return;
+        for (const name of [...(entry.manifest.dependencies ?? [])].sort()) {
+            const dependency = byName.get(name);
+            if (!dependency)
+                throw new Error(`Missing same-source plugin dependency ${JSON.stringify(name)}.`);
+            visit(dependency);
+        }
+        visited.add(entry.manifest.name);
+        result.push(entry);
+    };
+    visit(plugin);
+    return result;
+}
+export async function buildWorkspacePlugin(options) {
+    const workspace = await readPluginWorkspace(options.workspaceRoot, { reservedImports: options.reservedImports });
+    assertDependencyGraph(workspace.plugins);
+    const requestedPluginRoot = path.resolve(workspace.workspaceRoot, options.pluginDirectory);
+    const pluginRoot = await fs.realpath(requestedPluginRoot);
+    if (!isInside(workspace.workspaceRoot, pluginRoot))
+        throw new Error('Plugin directory must stay inside the workspace.');
+    const plugin = workspace.plugins.find((entry) => entry.rootDir === pluginRoot);
+    if (!plugin) {
+        throw new Error(`Plugin directory is not part of this workspace source: ${pluginRoot}`);
+    }
+    const closure = dependencyClosure(plugin, workspace.plugins);
+    const identity = sha256(normalizeManifestDigestInput(plugin.manifest));
+    const marker = generatedOutputMarker({
+        kind: 'plugin',
+        workspaceIdentity: await readWorkspaceOwnershipIdentity(workspace.workspaceRoot),
+        sourceIdentity: identity,
+        sourceName: plugin.manifest.name,
+    });
+    const resolved = await resolveWorkspaceOutputPath({
+        workspaceRoot: workspace.workspaceRoot,
+        outputPath: options.outputPath ?? path.join(DEFAULT_PLUGIN_OUTPUT_PATH, plugin.manifest.name),
+        kind: 'plugin',
+    });
+    await replaceGeneratedOutput({
+        outputRoot: resolved.outputRoot,
+        force: options.force === true,
+        build: (stagingRoot) => options.adapter.build({
+            workspaceRoot: workspace.workspaceRoot,
+            plugin,
+            plugins: workspace.plugins,
+            dependencies: closure.slice(0, -1),
+            outputRoot: stagingRoot,
+        }).then(() => fs.writeJson(path.join(stagingRoot, GENERATED_OUTPUT_MARKER_FILENAME), marker, { spaces: 2 })),
+        validate: async (stagingRoot) => {
+            await readPluginManifest(stagingRoot, { mode: 'bundle' });
+            await assertGeneratedOutput(stagingRoot, marker);
+        },
+        assertReplaceable: async (existingRoot) => {
+            await assertGeneratedOutput(existingRoot, marker);
+        },
+    });
+    const digest = await digestDirectory(resolved.outputRoot);
+    return {
+        outputRoot: resolved.outputRoot,
+        pluginName: plugin.manifest.name,
+        dependencies: closure.slice(0, -1).map((entry) => entry.manifest.name),
+        digest,
+    };
+}
+async function assertGeneratedOutput(root, expected) {
+    const markerPath = path.join(root, GENERATED_OUTPUT_MARKER_FILENAME);
+    const stat = await fs.lstat(markerPath).catch((error) => {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    });
+    if (!stat?.isFile() || stat.isSymbolicLink()) {
+        throw new Error(`Refusing to replace foreign plugin output: ${root}`);
+    }
+    const marker = await fs.readJson(markerPath);
+    const expectedKeys = expected.sourceName === undefined
+        ? ['kind', 'schemaVersion', 'sourceIdentity', 'workspaceIdentity']
+        : ['kind', 'schemaVersion', 'sourceIdentity', 'sourceName', 'workspaceIdentity'];
+    const digestPattern = /^sha256:[0-9a-f]{64}$/u;
+    if (!isDeepStrictEqual(Object.keys(marker).sort(), expectedKeys)
+        || marker.schemaVersion !== 1
+        || typeof marker.workspaceIdentity !== 'string'
+        || !digestPattern.test(marker.workspaceIdentity)
+        || typeof marker.sourceIdentity !== 'string'
+        || !digestPattern.test(marker.sourceIdentity)) {
+        throw new Error(`Refusing to replace foreign plugin output: ${root}`);
+    }
+    const ownershipFields = ['schemaVersion', 'kind', 'workspaceIdentity', 'sourceName'];
+    if (ownershipFields.some((field) => marker[field] !== expected[field])) {
+        throw new Error(`Refusing to replace plugin output with a different identity: ${root}`);
+    }
+}
+async function digestDirectory(root) {
+    const entries = [];
+    const walk = async (directory) => {
+        for (const name of (await fs.readdir(directory)).sort()) {
+            const filePath = path.join(directory, name);
+            const relative = path.relative(root, filePath).split(path.sep).join('/');
+            if (relative === GENERATED_OUTPUT_MARKER_FILENAME)
+                continue;
+            const stat = await fs.lstat(filePath);
+            if (stat.isSymbolicLink())
+                throw new Error(`Generated output contains a symbolic link: ${relative}`);
+            if (stat.isDirectory())
+                await walk(filePath);
+            else if (stat.isFile())
+                entries.push(`${relative}\0${crypto.createHash('sha256').update(await fs.readFile(filePath)).digest('hex')}`);
+            else
+                throw new Error(`Generated output contains an unsupported entry: ${relative}`);
+        }
+    };
+    await walk(root);
+    return `sha256:${crypto.createHash('sha256').update(entries.join('\n')).digest('hex')}`;
+}
+export async function validateCatalogSnapshot(snapshotDirectory) {
+    const rootDir = await assertDirectoryWithoutSymlinks(snapshotDirectory, 'Catalog snapshot');
+    const allowed = new Set([
+        CATALOG_MANIFEST_FILENAME,
+        GENERATED_OUTPUT_MARKER_FILENAME,
+        '.agents',
+        '.claude-plugin',
+        'plugins',
+        'plugin-release-ledger.json',
+    ]);
+    const entries = await fs.readdir(rootDir);
+    const unexpected = entries.filter((entry) => !allowed.has(entry));
+    const required = [CATALOG_MANIFEST_FILENAME, '.agents', '.claude-plugin', 'plugins'];
+    const missing = required.filter((entry) => !entries.includes(entry));
+    if (unexpected.length > 0 || missing.length > 0) {
+        throw new Error(`Invalid catalog snapshot root layout: missing [${missing.join(', ')}], unexpected [${unexpected.join(', ')}].`);
+    }
+    if (entries.includes(GENERATED_OUTPUT_MARKER_FILENAME)) {
+        const marker = await readRegularJson(path.join(rootDir, GENERATED_OUTPUT_MARKER_FILENAME), 'Catalog generated output marker');
+        const digestPattern = /^sha256:[0-9a-f]{64}$/u;
+        if (!isDeepStrictEqual(Object.keys(marker).sort(), [
+            'kind', 'schemaVersion', 'sourceIdentity', 'workspaceIdentity',
+        ])
+            || marker.schemaVersion !== 1
+            || marker.kind !== 'catalog'
+            || typeof marker.workspaceIdentity !== 'string'
+            || !digestPattern.test(marker.workspaceIdentity)
+            || typeof marker.sourceIdentity !== 'string'
+            || !digestPattern.test(marker.sourceIdentity)) {
+            throw new Error('Invalid catalog generated output marker.');
+        }
+    }
+    const assertLayout = async (directory, expected) => {
+        const real = await assertDirectoryWithoutSymlinks(directory, 'Catalog snapshot directory');
+        if (!isInside(rootDir, real))
+            throw new Error(`Catalog snapshot directory resolves outside the snapshot: ${directory}`);
+        const actual = (await fs.readdir(directory)).sort();
+        const wanted = [...expected].sort();
+        if (!isDeepStrictEqual(actual, wanted)) {
+            throw new Error(`Invalid catalog snapshot directory layout at ${directory}.`);
+        }
+    };
+    await assertLayout(path.join(rootDir, '.agents'), ['plugins']);
+    await assertLayout(path.join(rootDir, '.agents', 'plugins'), ['marketplace.json']);
+    await assertLayout(path.join(rootDir, '.claude-plugin'), ['marketplace.json']);
+    await readRegularJson(path.join(rootDir, '.agents', 'plugins', 'marketplace.json'), 'Codex marketplace');
+    await readRegularJson(path.join(rootDir, '.claude-plugin', 'marketplace.json'), 'Claude marketplace');
+    const snapshotDigest = await digestDirectory(rootDir);
+    const raw = await fs.readJson(path.join(rootDir, CATALOG_MANIFEST_FILENAME));
+    const allowedManifestKeys = new Set([
+        'schemaVersion', 'catalogVersion', 'channel', 'compatibility', 'marketplace', 'release', 'entries',
+    ]);
+    for (const key of Object.keys(raw))
+        if (!allowedManifestKeys.has(key))
+            throw new Error(`Invalid catalog manifest: unknown field ${JSON.stringify(key)}.`);
+    if (raw.schemaVersion !== 4)
+        throw new Error('Invalid catalog manifest schemaVersion: expected 4.');
+    const base = normalizeCatalogManifestBase(raw, 'catalog manifest v4');
+    const marketplaceIdentity = normalizeCatalogMarketplaceIdentity(raw.marketplace);
+    if (!Array.isArray(raw.entries))
+        throw new Error('Invalid catalog manifest entries: expected an array.');
+    const rawEntries = raw.entries;
+    const contentDigests = rawEntries.map((entry, index) => {
+        if (typeof entry.contentDigest !== 'string' || !/^sha256:[0-9a-f]{64}$/u.test(entry.contentDigest)) {
+            throw new Error(`Invalid catalog manifest entries[${index}].contentDigest.`);
+        }
+        return entry.contentDigest;
+    });
+    const entriesWithoutContentDigest = rawEntries.map((entry) => {
+        const copy = { ...entry };
+        delete copy.contentDigest;
+        return copy;
+    });
+    const normalizedEntries = normalizeCatalogManifestEntries(entriesWithoutContentDigest, base, 'catalog manifest v4')
+        .map((entry, index) => ({ ...entry, contentDigest: contentDigests[index] }));
+    const pluginNames = normalizedEntries.map((entry, index) => {
+        if (typeof entry.name !== 'string')
+            throw new Error(`Invalid catalog manifest entries[${index}].name.`);
+        return entry.name;
+    });
+    if (new Set(pluginNames).size !== pluginNames.length)
+        throw new Error('Invalid catalog manifest entries: duplicate plugin name.');
+    if (pluginNames.join('\0') !== [...pluginNames].sort().join('\0'))
+        throw new Error('Invalid catalog manifest entries: expected stable name order.');
+    const diskNames = (await fs.readdir(path.join(rootDir, 'plugins'))).sort();
+    if (diskNames.join('\0') !== [...pluginNames].sort().join('\0'))
+        throw new Error('Invalid catalog snapshot plugin inventory.');
+    const plugins = [];
+    for (const [index, name] of pluginNames.entries()) {
+        const pluginRoot = path.join(rootDir, 'plugins', name);
+        const plugin = await readPluginManifest(pluginRoot, { mode: 'bundle' });
+        for (const platform of ['claude', 'codex']) {
+            const platformManifest = path.join(pluginRoot, `.${platform}-plugin`, 'plugin.json');
+            const exists = await fs.pathExists(platformManifest);
+            if (exists !== resolveSupportedPlatforms(plugin.manifest).has(platform)) {
+                throw new Error(`Catalog plugin ${JSON.stringify(name)} has an inconsistent ${platform} bundle projection.`);
+            }
+            if (exists) {
+                const rawPlatformManifest = await readRegularJson(platformManifest, `${platform} plugin manifest`);
+                await validatePlatformManifestProjection(plugin, platform, rawPlatformManifest);
+            }
+        }
+        const expected = await expectedCatalogEntry(plugin, pluginRoot);
+        for (const field of Object.keys(expected)) {
+            if (!isDeepStrictEqual(normalizedEntries[index][field], expected[field])) {
+                throw new Error(`Catalog entry ${field} for ${JSON.stringify(name)} does not match its plugin bundle.`);
+            }
+        }
+        plugins.push(plugin);
+    }
+    assertDependencyGraph(plugins);
+    const agentsMarketplace = await fs.readJson(path.join(rootDir, '.agents', 'plugins', 'marketplace.json'));
+    const claudeMarketplace = await fs.readJson(path.join(rootDir, '.claude-plugin', 'marketplace.json'));
+    const marketplaceMetadata = {
+        owner: marketplaceIdentity.owner,
+        interface: marketplaceIdentity.interface,
+        catalog: { version: base.catalogVersion },
+    };
+    const expectedAgents = createMarketplaceManifest(marketplaceMetadata, plugins.filter((plugin) => resolveSupportedPlatforms(plugin.manifest).has('codex')));
+    const expectedClaude = createMarketplaceManifest(marketplaceMetadata, plugins.filter((plugin) => resolveSupportedPlatforms(plugin.manifest).has('claude')));
+    const normalizeMarketplaceOrder = (marketplace) => {
+        const canonical = JSON.parse(JSON.stringify(marketplace));
+        return {
+            ...canonical,
+            plugins: Array.isArray(canonical.plugins)
+                ? [...canonical.plugins].sort((left, right) => String(left?.name).localeCompare(String(right?.name)))
+                : canonical.plugins,
+        };
+    };
+    if (!isDeepStrictEqual(normalizeMarketplaceOrder(agentsMarketplace), normalizeMarketplaceOrder(expectedAgents))) {
+        throw new Error('Codex marketplace metadata or plugin inventory does not match the snapshot bundles.');
+    }
+    if (!isDeepStrictEqual(normalizeMarketplaceOrder(claudeMarketplace), normalizeMarketplaceOrder(expectedClaude))) {
+        throw new Error('Claude marketplace metadata or plugin inventory does not match the snapshot bundles.');
+    }
+    const release = normalizeCatalogRelease(raw.release, base.catalogVersion);
+    const manifest = {
+        schemaVersion: 4,
+        catalogVersion: base.catalogVersion,
+        channel: base.channel,
+        compatibility: base.compatibility,
+        marketplace: marketplaceIdentity,
+        release,
+        entries: normalizedEntries,
+    };
+    if (release.state === 'published') {
+        const contentDigest = publishedContentDigest(manifest);
+        if (release.contentDigest !== contentDigest) {
+            throw new Error('Published catalog release contentDigest does not match the snapshot.');
+        }
+    }
+    const hasLedger = entries.includes(PLUGIN_RELEASE_LEDGER_FILENAME);
+    if (release.state === 'published' && !hasLedger) {
+        throw new Error('Published Catalog snapshot must include plugin-release-ledger.json.');
+    }
+    if (release.state === 'development' && hasLedger) {
+        throw new Error('Development Catalog snapshot must not include plugin-release-ledger.json.');
+    }
+    const ledger = hasLedger
+        ? validatePluginReleaseLedgerAgainstManifest(await readRegularJson(path.join(rootDir, PLUGIN_RELEASE_LEDGER_FILENAME), 'Plugin release ledger'), manifest)
+        : undefined;
+    return { rootDir, manifest, ...(ledger ? { ledger } : {}), snapshotDigest };
+}
+//# sourceMappingURL=workspace.js.map