@lesliechan721/aw 0.1.0-beta.4 → 0.1.0-beta.6

package/dist/src/commands/catalog-publish.js

@@ -1,108 +1,36 @@
 import crypto from 'node:crypto';
-import { execFile } from 'node:child_process';
-import os from 'node:os';
 import path from 'node:path';
-import { promisify } from 'node:util';
 import fs from 'fs-extra';
-import { assertStrictSemVer, preparePublishedWorkspaceCatalog, readPluginWorkspace, validatePublishedCatalogSnapshot, } from '@lesliechan721/aw-plugin-core';
-import { bundleLocalPlugin, createCatalogRuntimeImportResolver } from '../../scripts/plugin-staging.js';
-import { CLI_RESERVED_IMPORTS } from '../utils/manifest.js';
-import { resolveCliPackageRoot } from '../utils/paths.js';
-const execFileAsync = promisify(execFile);
-const LEGACY_ATTEMPTED_MARKER = path.join('.aw', 'publish', 'attempted.json');
-const INHERITED_GIT_AUTH_ENV = new Set([
-    'GIT_ASKPASS',
-    'GIT_HTTP_USER_AGENT',
-    'GIT_SSH',
-    'GIT_SSH_COMMAND',
-    'GIT_SSH_VARIANT',
-    'GIT_SSL_CAINFO',
-    'GIT_SSL_NO_VERIFY',
-    'GIT_TERMINAL_PROMPT',
-]);
+import { validatePublishedCatalogSnapshot } from '@lesliechan721/aw-plugin-core';
+import { disposeCatalogPublicationInspection, parseRemoteRefs, prepareCatalogPublicationInspection, publicationGit, publicationGitExit, } from './catalog-publication-inspection.js';
+export { safeRemoteIdentity, sanitizedGitEnvironment } from './catalog-publication-inspection.js';
 function digest(value) {
     return `sha256:${crypto.createHash('sha256').update(value).digest('hex')}`;
 }
-export function sanitizedGitEnvironment(source) {
-    return Object.fromEntries(Object.entries(source).filter(([key]) => !key.startsWith('GIT_') || INHERITED_GIT_AUTH_ENV.has(key)));
-}
-export function safeRemoteIdentity(value) {
-    if (/^[a-z][a-z\d+.-]*:\/\//iu.test(value)) {
-        try {
-            const url = new URL(value);
-            url.username = '';
-            url.password = '';
-            url.search = '';
-            url.hash = '';
-            return url.toString();
-        }
-        catch {
-            // Fall through to conservative display sanitization for malformed URLs.
-        }
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(',')}]`;
+    if (value !== null && typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(',')}}`;
     }
-    const withoutQuery = value.split(/[?#]/u, 1)[0];
-    return withoutQuery
-        .replace(/^([^/@\s:]+):([^/@\s]+)@/u, '')
-        .replace(/^[^@\s]+@(?=[^:/\s]+[/:])/u, '');
+    return JSON.stringify(value);
 }
-function attemptPath(workspaceRoot, catalogVersion) {
-    return path.join(workspaceRoot, '.aw', 'publish', 'attempts', `${catalogVersion}.json`);
-}
-async function migrateLegacyAttempt(workspaceRoot, catalogVersion) {
-    const legacyPath = path.join(workspaceRoot, LEGACY_ATTEMPTED_MARKER);
-    if (!(await fs.pathExists(legacyPath)))
-        return;
-    let recordedVersion = catalogVersion;
-    try {
-        const legacy = await fs.readJson(legacyPath);
-        if (legacy.schemaVersion === 1 && typeof legacy.catalogVersion === 'string') {
-            recordedVersion = assertStrictSemVer(legacy.catalogVersion, 'legacy attempted Catalog version');
-        }
-    }
-    catch {
-        // Bind an unreadable legacy marker to the current version. A later version uses a new file.
-    }
-    const destination = attemptPath(workspaceRoot, recordedVersion);
-    await fs.ensureDir(path.dirname(destination));
-    if (await fs.pathExists(destination))
-        return;
-    await fs.rename(legacyPath, destination);
+export function catalogPublicationDescriptorDigest(descriptor) {
+    return digest(canonicalJson(descriptor));
 }
-async function git(cwd, args, env, label) {
-    try {
-        const result = await execFileAsync('git', [...args], {
-            cwd,
-            env,
-            encoding: 'utf8',
-            maxBuffer: 16 * 1024 * 1024,
-        });
-        return result.stdout.trim();
-    }
-    catch (error) {
-        throw new Error(label, { cause: error });
-    }
-}
-async function gitExit(cwd, args, env) {
-    try {
-        await execFileAsync('git', [...args], { cwd, env, encoding: 'utf8' });
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function parseRemoteRefs(output) {
-    return new Map(output.split('\n').filter(Boolean).map((line) => {
-        const [objectId, ref] = line.split(/\s+/u);
-        return [ref, objectId];
-    }));
-}
-async function writeJsonAtomic(filePath, value) {
+async function writeJsonAtomic(filePath, value, exclusive) {
     await fs.ensureDir(path.dirname(filePath));
     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', mode: 0o600 });
     try {
-        await fs.rename(temporary, filePath);
+        if (exclusive) {
+            await fs.link(temporary, filePath);
+            await fs.remove(temporary);
+        }
+        else {
+            await fs.rename(temporary, filePath);
+        }
     }
     catch (error) {
         await fs.remove(temporary);
@@ -115,164 +43,255 @@ async function clearWorktree(repositoryRoot) {
             await fs.remove(path.join(repositoryRoot, name));
     }
 }
-async function materializeSourceHead(options) {
-    const archivePath = path.join(options.temporaryRoot, 'source-head.tar');
-    await fs.ensureDir(options.outputRoot);
-    await git(options.repoRoot, [
-        'archive', '--format=tar', `--output=${archivePath}`, options.sourceHead,
-    ], options.env, 'Could not archive the committed source HEAD.');
-    const tarEnv = { ...options.env };
-    delete tarEnv.TAR_OPTIONS;
-    try {
-        await execFileAsync('tar', ['-xf', archivePath, '-C', options.outputRoot], {
-            env: tarEnv,
-            encoding: 'utf8',
-            maxBuffer: 16 * 1024 * 1024,
-        });
+async function assertNoGitAttributes(root, relative = '') {
+    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.name === '.gitattributes') {
+            throw new Error(`Catalog publication snapshot must not contain .gitattributes (${child}).`);
+        }
+        if (entry.isDirectory())
+            await assertNoGitAttributes(root, child);
     }
-    catch (error) {
-        throw new Error('Could not materialize the committed source HEAD.', { cause: error });
+}
+async function assertSnapshotBinding(snapshotRoot, descriptor) {
+    const [stats, validation, ledgerBytes] = await Promise.all([
+        fs.lstat(snapshotRoot),
+        validatePublishedCatalogSnapshot(snapshotRoot),
+        fs.readFile(path.join(snapshotRoot, 'plugin-release-ledger.json')),
+    ]);
+    if (!stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new Error('Prepared Catalog snapshot must be a regular local directory.');
     }
-    finally {
-        await fs.remove(archivePath);
+    const release = validation.manifest.release;
+    if (validation.manifest.catalogVersion !== descriptor.catalogVersion
+        || validation.manifest.channel !== descriptor.channel
+        || validation.snapshotDigest !== descriptor.snapshotDigest
+        || release.state !== 'published'
+        || release.sourceHead !== descriptor.sourceHead
+        || release.contentDigest !== descriptor.contentDigest
+        || release.planId !== descriptor.planId
+        || digest(ledgerBytes) !== descriptor.ledgerDigest) {
+        throw new Error('Prepared Catalog descriptor, snapshot, ledger, or plan identity changed.');
     }
+    await assertNoGitAttributes(snapshotRoot);
 }
-async function validatePublishedSourceWorkspace(workspace, env) {
-    const validator = path.join(resolveCliPackageRoot(), 'dist', 'authoring', 'scripts', 'validate-plugin.mjs');
-    for (const plugin of workspace.plugins) {
-        try {
-            await execFileAsync(process.execPath, [
-                validator,
-                plugin.rootDir,
-                '--workspace-root', workspace.workspaceRoot,
-                '--json',
-            ], {
-                cwd: workspace.workspaceRoot,
-                env,
-                encoding: 'utf8',
-                maxBuffer: 16 * 1024 * 1024,
-            });
-        }
-        catch (error) {
-            let details = '';
-            if (typeof error === 'object' && error !== null && 'stdout' in error && typeof error.stdout === 'string') {
-                try {
-                    const result = JSON.parse(error.stdout);
-                    details = (result.errors ?? [])
-                        .map((entry) => typeof entry.message === 'string' ? entry.message : '')
-                        .filter(Boolean)
-                        .join('; ');
-                }
-                catch {
-                    // Keep the public validator failure bounded to its plugin identity.
-                }
-            }
-            throw new Error(`Plugin ${plugin.manifest.name} failed public source validation before Catalog publication${details ? `: ${details}` : '.'}`);
+async function publishCatalogPublicationPreparation(options) {
+    const { preparation: inspection, descriptor, snapshotRoot } = options;
+    const { temporaryRoot, repositoryRoot, repoRoot, sourceHead, remote, branch, branchRef, tag, tagRef, fetchUrl, pushUrl, safeFetchUrl, safePushUrl, remoteIdentityDigest, parent, attemptPath, env, } = inspection;
+    if (catalogPublicationDescriptorDigest(inspection.descriptor)
+        !== catalogPublicationDescriptorDigest(descriptor)) {
+        throw new Error('Catalog publication descriptor changed after preparation.');
+    }
+    if (!inspection.tagAvailable) {
+        throw new Error(`Remote Catalog tag ${tag} already exists. Increase the Catalog version.`);
+    }
+    if (!inspection.attemptAvailable || await fs.pathExists(attemptPath)) {
+        throw new Error(`Catalog ${descriptor.catalogVersion} already has an attempted publication record. `
+            + 'Run aw catalog version <higher> before publishing again.');
+    }
+    if (!(await publicationGitExit(repoRoot, ['check-ignore', '-q', attemptPath], env))) {
+        throw new Error('Catalog publish state under .aw/publish must be ignored by Git. Add .aw/ to .gitignore.');
+    }
+    await assertSnapshotBinding(snapshotRoot, descriptor);
+    if (parent) {
+        await publicationGit(repositoryRoot, [
+            'checkout', '--quiet', '--detach', 'refs/aw/catalog-parent',
+        ], env, 'publicationCommitFailed', 'Could not select the publication parent.');
+    }
+    else {
+        await publicationGit(repositoryRoot, [
+            'checkout', '--quiet', '--orphan', 'catalog-publication',
+        ], env, 'publicationCommitFailed', 'Could not create the initial Catalog publication.');
+    }
+    await clearWorktree(repositoryRoot);
+    await fs.copy(snapshotRoot, repositoryRoot, { dereference: false });
+    await publicationGit(repositoryRoot, ['add', '--force', '--all'], env, 'publicationCommitFailed', 'Could not stage the Catalog publication tree.');
+    await publicationGit(repositoryRoot, [
+        '-c', 'user.name=AW Catalog Publisher',
+        '-c', 'user.email=catalog-publisher@agent-workflows.invalid',
+        'commit', '--quiet', '-m', `Catalog ${descriptor.catalogVersion}`,
+    ], env, 'publicationCommitFailed', 'Could not create the Catalog publication commit.');
+    const commit = await publicationGit(repositoryRoot, [
+        'rev-parse', 'HEAD',
+    ], env, 'publicationCommitFailed', 'Could not resolve the Catalog publication commit.');
+    const parents = (await publicationGit(repositoryRoot, [
+        'show', '-s', '--format=%P', commit,
+    ], env, 'publicationCommitFailed', 'Could not verify the Catalog publication parent.'))
+        .split(/\s+/u)
+        .filter(Boolean);
+    if ((parent && (parents.length !== 1 || parents[0] !== parent)) || (!parent && parents.length !== 0)) {
+        throw new Error('Catalog publication commit has an invalid parent.');
+    }
+    const verificationRoot = path.join(temporaryRoot, 'verification');
+    await fs.ensureDir(verificationRoot);
+    await publicationGit(repositoryRoot, [
+        '--work-tree', verificationRoot, 'checkout', '--quiet', commit, '--', '.',
+    ], env, 'publicationCommitFailed', 'Could not verify the Catalog publication commit tree.');
+    await assertSnapshotBinding(verificationRoot, descriptor);
+    await publicationGit(repositoryRoot, [
+        '-c', 'user.name=AW Catalog Publisher',
+        '-c', 'user.email=catalog-publisher@agent-workflows.invalid',
+        'tag', '--annotate', tag, '--message', `Catalog ${descriptor.catalogVersion}`,
+    ], env, 'publicationCommitFailed', 'Could not create the annotated Catalog tag.');
+    const liveHead = await publicationGit(repoRoot, [
+        'rev-parse', '--verify', 'HEAD',
+    ], env, 'sourceDrift', 'Could not recheck the source Git HEAD.');
+    const liveStatus = await publicationGit(repoRoot, [
+        'status', '--porcelain=v1', '--untracked-files=all', '--ignore-submodules=none',
+    ], env, 'sourceDrift', 'Could not recheck the source worktree.');
+    if (liveHead !== sourceHead || liveStatus !== '') {
+        throw new Error('Source HEAD or worktree changed before Catalog publication.');
+    }
+    let liveFetchUrl;
+    let livePushUrl;
+    if (descriptor.remote.name === null) {
+        liveFetchUrl = fetchUrl;
+        livePushUrl = pushUrl;
+    }
+    else {
+        [liveFetchUrl, livePushUrl] = await Promise.all([
+            publicationGit(repoRoot, ['remote', 'get-url', descriptor.remote.name], env, 'remoteDrift', 'Could not recheck the Catalog publication remote configuration.'),
+            publicationGit(repoRoot, ['remote', 'get-url', '--push', descriptor.remote.name], env, 'remoteDrift', 'Could not recheck the Catalog publication remote configuration.'),
+        ]);
+    }
+    if (digest(JSON.stringify({ fetchUrl: liveFetchUrl, pushUrl: livePushUrl })) !== remoteIdentityDigest) {
+        throw new Error('Catalog remote configuration changed during preparation.');
+    }
+    const liveRefs = parseRemoteRefs(await publicationGit(repositoryRoot, [
+        'ls-remote', 'publish', branchRef, tagRef, `${tagRef}^{}`,
+    ], env, 'remoteDrift', 'Could not recheck the Catalog publication remote.'));
+    if ((liveRefs.get(branchRef) ?? null) !== parent || liveRefs.has(tagRef) || liveRefs.has(`${tagRef}^{}`)) {
+        throw new Error('Catalog remote changed during preparation. Increase the Catalog version before publishing again.');
+    }
+    if (await fs.pathExists(attemptPath)) {
+        throw new Error(`Catalog ${descriptor.catalogVersion} already has an attempted publication record. `
+            + 'Run aw catalog version <higher> before publishing again.');
+    }
+    await options.beforeRemoteWrite?.();
+    const attempted = {
+        schemaVersion: 1,
+        state: 'attempted',
+        workspaceIdentity: descriptor.workspaceIdentity,
+        catalogVersion: descriptor.catalogVersion,
+        sourceHead,
+        remote: { name: descriptor.remote.name, identityDigest: remoteIdentityDigest },
+        branch,
+        parent,
+        tag,
+        snapshotDigest: descriptor.snapshotDigest,
+        contentDigest: descriptor.contentDigest,
+        planId: descriptor.planId,
+        descriptorDigest: catalogPublicationDescriptorDigest(descriptor),
+        attemptedAt: new Date().toISOString(),
+    };
+    try {
+        await writeJsonAtomic(attemptPath, attempted, true);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            throw new Error(`Catalog ${descriptor.catalogVersion} already has an attempted publication record. `
+                + 'Run aw catalog version <higher> before publishing again.');
         }
+        throw error;
+    }
+    try {
+        await publicationGit(repositoryRoot, [
+            'push', '--atomic', `--force-with-lease=${branchRef}:${parent ?? ''}`,
+            'publish', `${commit}:${branchRef}`, `${tagRef}:${tagRef}`,
+        ], env, 'publicationUncertain', `Catalog atomic push failed or its result is uncertain. Do not retry ${descriptor.catalogVersion}; increase the Catalog version.`);
     }
+    catch {
+        throw new Error(`Catalog atomic push failed or its result is uncertain. Do not retry ${descriptor.catalogVersion}; run aw catalog version <higher>.`);
+    }
+    const publishedRefs = parseRemoteRefs(await publicationGit(repositoryRoot, [
+        'ls-remote', 'publish', branchRef, tagRef, `${tagRef}^{}`,
+    ], env, 'publicationUncertain', `Catalog publication result is uncertain. Do not retry ${descriptor.catalogVersion}; increase the Catalog version.`));
+    if (publishedRefs.get(branchRef) !== commit || publishedRefs.get(`${tagRef}^{}`) !== commit) {
+        throw new Error(`Catalog publication result is uncertain. Do not retry ${descriptor.catalogVersion}; run aw catalog version <higher>.`);
+    }
+    await writeJsonAtomic(attemptPath, {
+        ...attempted,
+        state: 'published',
+        commit,
+        publishedAt: new Date().toISOString(),
+    }, false);
+    return {
+        command: 'catalog:publish',
+        ok: true,
+        workspaceIdentity: descriptor.workspaceIdentity,
+        catalogVersion: descriptor.catalogVersion,
+        channel: descriptor.channel,
+        remote,
+        remoteUrl: safeFetchUrl,
+        fetchUrl: safeFetchUrl,
+        pushUrl: safePushUrl,
+        branch,
+        parent,
+        tag,
+        commit,
+        sourceHead,
+        pluginCount: descriptor.pluginNames.length,
+        snapshotDigest: descriptor.snapshotDigest,
+        planId: descriptor.planId,
+        descriptorDigest: catalogPublicationDescriptorDigest(descriptor),
+    };
 }
-const publishBuildAdapter = {
-    async build(options) {
-        await bundleLocalPlugin(options.plugin, options.outputRoot, {
-            buildMode: 'staging',
-            runtimeResolver: createCatalogRuntimeImportResolver(options.plugins),
+export async function publishPreparedCatalogPublication(options) {
+    const inspection = await prepareCatalogPublicationInspection({
+        workspaceRoot: options.workspaceRoot,
+        remote: options.remote,
+        remoteUrl: options.remoteUrl,
+        branch: options.branch,
+        env: options.env,
+        failOnUnavailable: true,
+    });
+    try {
+        return await publishCatalogPublicationPreparation({
+            preparation: inspection,
+            descriptor: options.descriptor,
+            snapshotRoot: options.snapshotRoot,
+            beforeRemoteWrite: options.beforeRemoteWrite,
         });
-    },
-};
+    }
+    finally {
+        await disposeCatalogPublicationInspection(inspection);
+    }
+}
 export async function runCatalogPublishCommand(options) {
     if (options.json && !options.yes)
         throw new Error('Catalog publish with --json requires --yes.');
     if (!options.interactive && !options.yes)
         throw new Error('Non-interactive Catalog publish requires --yes.');
-    const remote = options.remote ?? 'origin';
-    const branch = options.branch ?? 'catalog';
-    const env = sanitizedGitEnvironment(options.env);
-    const workspaceRoot = await fs.realpath(path.resolve(options.workspaceRoot));
-    const repoRoot = await git(workspaceRoot, ['rev-parse', '--show-toplevel'], env, 'Workspace must be inside a real Git worktree.');
-    const sourceHead = await git(repoRoot, ['rev-parse', '--verify', 'HEAD'], env, 'Workspace Git HEAD must be committed and not unborn.');
-    const status = await git(repoRoot, [
-        'status', '--porcelain=v1', '--untracked-files=all', '--ignore-submodules=none',
-    ], env, 'Could not inspect the source worktree.');
-    if (status !== '')
-        throw new Error('Catalog publish requires the complete source Git worktree to be clean.');
-    const temporaryRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'aw-public-catalog-'));
-    let fetchUrl = '';
-    let pushUrl = '';
-    let safeFetchUrl = '';
-    let safePushUrl = '';
+    if (!/^sha256:[0-9a-f]{64}$/u.test(options.expectedDescriptorDigest ?? '')) {
+        throw new Error('Catalog publish requires --expected-descriptor-digest from a successful publication preflight.');
+    }
+    const inspection = await prepareCatalogPublicationInspection({
+        ...options,
+        failOnUnavailable: true,
+    });
     try {
-        const sourceRoot = path.join(temporaryRoot, 'source');
-        await materializeSourceHead({ repoRoot, sourceHead, outputRoot: sourceRoot, temporaryRoot, env });
-        const workspaceRelative = path.relative(repoRoot, workspaceRoot);
-        if (workspaceRelative === '..' || workspaceRelative.startsWith(`..${path.sep}`) || path.isAbsolute(workspaceRelative)) {
-            throw new Error('Catalog workspace must stay inside its Git worktree root.');
+        const preparedDescriptorDigest = catalogPublicationDescriptorDigest(inspection.descriptor);
+        if (options.expectedDescriptorDigest !== preparedDescriptorDigest) {
+            throw new Error('Catalog publication descriptor does not match the authorized preflight. Run preflight and authorize the current exact identity.');
         }
-        const sourceWorkspaceRoot = path.join(sourceRoot, workspaceRelative);
-        await git(repoRoot, ['check-ref-format', '--branch', branch], env, 'Invalid Catalog publication branch name.');
-        const workspace = await readPluginWorkspace(sourceWorkspaceRoot, { reservedImports: CLI_RESERVED_IMPORTS });
-        await validatePublishedSourceWorkspace(workspace, env);
-        const catalogVersion = workspace.metadata.catalog.version;
-        const tag = `catalog-v${catalogVersion}`;
-        await git(repoRoot, ['check-ref-format', `refs/tags/${tag}`], env, 'Invalid Catalog publication tag.');
-        const markerPath = attemptPath(workspaceRoot, catalogVersion);
-        if (!(await gitExit(repoRoot, ['check-ignore', '-q', markerPath], env))) {
+        if (!(await publicationGitExit(inspection.repoRoot, ['check-ignore', '-q', inspection.attemptPath], inspection.env))) {
             throw new Error('Catalog publish state under .aw/publish must be ignored by Git. Add .aw/ to .gitignore.');
         }
-        await migrateLegacyAttempt(workspaceRoot, catalogVersion);
-        if (await fs.pathExists(markerPath)) {
-            throw new Error(`Catalog ${catalogVersion} already has an attempted publication record. `
-                + 'Run aw catalog version <higher> before publishing again.');
-        }
-        fetchUrl = await git(repoRoot, ['remote', 'get-url', remote], env, `Git remote ${JSON.stringify(remote)} is not configured.`);
-        pushUrl = await git(repoRoot, ['remote', 'get-url', '--push', remote], env, `Git remote ${JSON.stringify(remote)} has no push URL.`);
-        safeFetchUrl = safeRemoteIdentity(fetchUrl);
-        safePushUrl = safeRemoteIdentity(pushUrl);
-        const remoteIdentityDigest = digest(JSON.stringify({ fetchUrl, pushUrl }));
-        const branchRef = `refs/heads/${branch}`;
-        const tagRef = `refs/tags/${tag}`;
-        const repositoryRoot = path.join(temporaryRoot, 'repository');
-        await fs.ensureDir(repositoryRoot);
-        await git(repositoryRoot, ['init', '--quiet'], env, 'Could not create the isolated publication repository.');
-        await git(repositoryRoot, ['config', 'core.hooksPath', path.join(temporaryRoot, 'disabled-hooks')], env, 'Could not disable publication hooks.');
-        await git(repositoryRoot, ['config', 'core.symlinks', 'true'], env, 'Could not configure the isolated publication repository.');
-        await git(repositoryRoot, ['remote', 'add', 'publish', pushUrl], env, 'Could not configure the publication remote.');
-        const initialRefs = parseRemoteRefs(await git(repositoryRoot, [
-            'ls-remote', 'publish', branchRef, tagRef, `${tagRef}^{}`,
-        ], env, 'Could not inspect the Catalog publication remote.'));
-        if (initialRefs.has(tagRef) || initialRefs.has(`${tagRef}^{}`)) {
-            throw new Error(`Remote Catalog tag ${tag} already exists. Increase the Catalog version.`);
-        }
-        const parent = initialRefs.get(branchRef) ?? null;
-        let previousSnapshotRoot;
-        if (parent) {
-            await git(repositoryRoot, ['fetch', '--quiet', '--no-tags', 'publish', `${branchRef}:refs/remotes/publish/catalog`], env, 'Could not fetch the published Catalog branch.');
-            previousSnapshotRoot = path.join(temporaryRoot, 'previous');
-            await fs.ensureDir(previousSnapshotRoot);
-            await git(repositoryRoot, ['--work-tree', previousSnapshotRoot, 'checkout', '--quiet', 'refs/remotes/publish/catalog', '--', '.'], env, 'Could not read the published Catalog snapshot.');
-            await validatePublishedCatalogSnapshot(previousSnapshotRoot);
-        }
-        const prepared = await preparePublishedWorkspaceCatalog({
-            workspaceRoot: sourceWorkspaceRoot,
-            sourceHead,
-            previousSnapshotRoot,
-            adapter: publishBuildAdapter,
-            reservedImports: CLI_RESERVED_IMPORTS,
-        });
-        const preparedHead = await git(repoRoot, ['rev-parse', '--verify', 'HEAD'], env, 'Could not recheck the source Git HEAD.');
-        const preparedStatus = await git(repoRoot, [
-            'status', '--porcelain=v1', '--untracked-files=all', '--ignore-submodules=none',
-        ], env, 'Could not recheck the source worktree.');
-        if (preparedHead !== sourceHead || preparedStatus !== '') {
-            throw new Error('Source HEAD or worktree changed during Catalog preparation. Commit or clean it before publishing.');
-        }
         if (!options.yes) {
             options.io.stderr([
-                `Source HEAD: ${sourceHead}`,
-                `Catalog: ${prepared.catalogVersion} (${prepared.channel})`,
-                `Push remote: ${remote} (${safePushUrl})`,
-                `Branch: ${branchRef}`,
-                `Tag: ${tagRef}`,
-                `Plugins: ${prepared.pluginNames.length}`,
+                `Workspace identity: ${inspection.descriptor.workspaceIdentity}`,
+                `Source HEAD: ${inspection.sourceHead}`,
+                `Catalog: ${inspection.descriptor.catalogVersion} (${inspection.descriptor.channel})`,
+                `Remote: ${inspection.remote}`,
+                `Fetch URL: ${inspection.safeFetchUrl}`,
+                `Push URL: ${inspection.safePushUrl}`,
+                `Branch: ${inspection.branchRef}`,
+                `Parent: ${inspection.parent ?? '<root>'}`,
+                `Tag: ${inspection.tagRef}`,
+                `Snapshot digest: ${inspection.descriptor.snapshotDigest}`,
+                `Plan ID: ${inspection.descriptor.planId}`,
+                `Descriptor digest: ${preparedDescriptorDigest}`,
+                `Plugins: ${inspection.descriptor.pluginNames.length}`,
                 'One atomic push will publish the branch and annotated tag.',
             ].join('\n') + '\n');
             if (!options.confirm || !(await options.confirm('Publish this Catalog snapshot?'))) {
@@ -280,95 +299,21 @@ export async function runCatalogPublishCommand(options) {
                 return null;
             }
         }
-        if (parent)
-            await git(repositoryRoot, ['checkout', '--quiet', '--detach', 'refs/remotes/publish/catalog'], env, 'Could not select the publication parent.');
-        else
-            await git(repositoryRoot, ['checkout', '--quiet', '--orphan', 'catalog-publication'], env, 'Could not create the initial Catalog publication.');
-        await clearWorktree(repositoryRoot);
-        await fs.copy(prepared.outputRoot, repositoryRoot, { dereference: false });
-        await git(repositoryRoot, ['add', '--force', '--all'], env, 'Could not stage the Catalog publication tree.');
-        await git(repositoryRoot, [
-            '-c', 'user.name=AW Catalog Publisher',
-            '-c', 'user.email=catalog-publisher@agent-workflows.invalid',
-            'commit', '--quiet', '-m', `Catalog ${catalogVersion}`,
-        ], env, 'Could not create the Catalog publication commit.');
-        const commit = await git(repositoryRoot, ['rev-parse', 'HEAD'], env, 'Could not resolve the Catalog publication commit.');
-        const parents = (await git(repositoryRoot, ['show', '-s', '--format=%P', commit], env, 'Could not verify the Catalog publication parent.')).split(/\s+/u).filter(Boolean);
-        if ((parent && (parents.length !== 1 || parents[0] !== parent)) || (!parent && parents.length !== 0)) {
-            throw new Error('Catalog publication commit has an invalid parent.');
-        }
-        const verificationRoot = path.join(temporaryRoot, 'verification');
-        await fs.ensureDir(verificationRoot);
-        await git(repositoryRoot, ['--work-tree', verificationRoot, 'checkout', '--quiet', commit, '--', '.'], env, 'Could not verify the Catalog publication commit tree.');
-        const committed = await validatePublishedCatalogSnapshot(verificationRoot);
-        if (committed.snapshotDigest !== prepared.snapshotDigest)
-            throw new Error('Catalog publication commit tree differs from the prepared snapshot.');
-        await git(repositoryRoot, [
-            '-c', 'user.name=AW Catalog Publisher',
-            '-c', 'user.email=catalog-publisher@agent-workflows.invalid',
-            'tag', '--annotate', tag, '--message', `Catalog ${catalogVersion}`,
-        ], env, 'Could not create the annotated Catalog tag.');
-        const attemptedAt = new Date().toISOString();
-        const attempted = {
-            schemaVersion: 1,
-            state: 'attempted',
-            workspaceIdentity: digest(JSON.stringify({ repoRoot, workspaceRelative: path.relative(repoRoot, workspaceRoot) })),
-            catalogVersion,
-            sourceHead,
-            remote: { name: remote, identityDigest: remoteIdentityDigest },
-            branch,
-            tag,
-            preparedSnapshotDigest: prepared.snapshotDigest,
-            attemptedAt,
-        };
-        await writeJsonAtomic(markerPath, attempted);
-        const liveRefs = parseRemoteRefs(await git(repositoryRoot, [
-            'ls-remote', 'publish', branchRef, tagRef, `${tagRef}^{}`,
-        ], env, 'Could not recheck the Catalog publication remote.'));
-        if ((liveRefs.get(branchRef) ?? null) !== parent || liveRefs.has(tagRef) || liveRefs.has(`${tagRef}^{}`)) {
-            throw new Error('Catalog remote changed during preparation. Increase the Catalog version before publishing again.');
-        }
-        try {
-            await git(repositoryRoot, [
-                'push', '--atomic', 'publish', `${commit}:${branchRef}`, `${tagRef}:${tagRef}`,
-            ], env, `Catalog atomic push failed or its result is uncertain. Do not retry ${catalogVersion}; increase the Catalog version.`);
-        }
-        catch {
-            throw new Error(`Catalog atomic push failed or its result is uncertain. Do not retry ${catalogVersion}; run aw catalog version <higher>.`);
-        }
-        const publishedRefs = parseRemoteRefs(await git(repositoryRoot, [
-            'ls-remote', 'publish', branchRef, tagRef, `${tagRef}^{}`,
-        ], env, `Catalog publication result is uncertain. Do not retry ${catalogVersion}; increase the Catalog version.`));
-        if (publishedRefs.get(branchRef) !== commit || publishedRefs.get(`${tagRef}^{}`) !== commit) {
-            throw new Error(`Catalog publication result is uncertain. Do not retry ${catalogVersion}; run aw catalog version <higher>.`);
-        }
-        await writeJsonAtomic(markerPath, { ...attempted, state: 'published', commit, publishedAt: new Date().toISOString() });
-        return {
-            command: 'catalog:publish',
-            ok: true,
-            catalogVersion,
-            channel: prepared.channel,
-            remote,
-            remoteUrl: safeFetchUrl,
-            fetchUrl: safeFetchUrl,
-            pushUrl: safePushUrl,
-            branch,
-            tag,
-            commit,
-            sourceHead,
-            pluginCount: prepared.pluginNames.length,
-            snapshotDigest: prepared.snapshotDigest,
-        };
+        return await publishCatalogPublicationPreparation({
+            preparation: inspection,
+            descriptor: inspection.descriptor,
+            snapshotRoot: inspection.prepared.outputRoot,
+        });
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(message
-            .replaceAll(temporaryRoot, '<temporary Catalog state>')
-            .replaceAll(fetchUrl, safeFetchUrl)
-            .replaceAll(pushUrl, safePushUrl));
+        const message = (error instanceof Error ? error.message : String(error))
+            .replaceAll(inspection.temporaryRoot, '<temporary Catalog state>')
+            .replaceAll(inspection.fetchUrl, inspection.safeFetchUrl)
+            .replaceAll(inspection.pushUrl, inspection.safePushUrl);
+        throw new Error(message);
     }
     finally {
-        await fs.remove(temporaryRoot);
+        await disposeCatalogPublicationInspection(inspection);
     }
 }
 //# sourceMappingURL=catalog-publish.js.map