@lesliechan721/aw 0.1.0-beta.8 → 0.1.0-beta.9

package/dist/src/index.js

@@ -4,15 +4,17 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { Command, CommanderError, Option } from 'commander';
-import { resolveCatalogWorkspaceRoot } from '@lesliechan721/aw-plugin-core';
+import { doctorEvalProviders } from '@lesliechan721/agent-skill-eval';
 import { initCommand } from './commands/init.js';
+import { resolveCatalogWorkspaceRoot } from './commands/catalog-workspace-resolution.js';
 import { addCatalogSourceCommand, explicitRefPolicy, listCatalogSources, removeCatalogSourceCommand, setPrimaryCatalogSourceCommand, updateCatalogSourceCommand, } from './commands/catalog-source.js';
-import { activateCatalogSourceCandidateCommand, catalogGenerationStatusCommand, refreshCatalogSourceGenerationCommand, setCatalogSourceRefreshPolicyCommand, } from './commands/catalog-generation.js';
+import { catalogSourceStatusCommand, syncCatalogSourceCommand, } from './commands/catalog-generation.js';
 import { cleanupWriteCommand as cleanupCommand, installWriteCommand as installCommand, reinstallWriteCommand as reinstallCommand, uninstallWriteCommand as uninstallCommand, upgradeWriteCommand as upgradeCommand, } from './commands/write-commands.js';
+import { syncCommand } from './commands/sync-command.js';
 import { formatInteractiveConsoleUnavailableMessage, runConsoleController, } from './commands/console.js';
 import { runCommandWizard, toWizardCandidates, WizardExecutionError, } from './commands/wizard.js';
 import { createCliExecutionContext, emitCommandEvent, } from './commands/runtime.js';
-import { loadConsoleItemsResult, statusCommandV5 } from './commands/status-v5.js';
+import { loadConsoleItemsResult, statusCommandV6 } from './commands/status-v6.js';
 import { normalizeUninstallCommandOptions, normalizeCleanupCommandOptions, resolveConfigReadResolution, resolveConfigProjectLayer, resolveConfigWriteScope, normalizeInstallCommandOptions, normalizeReinstallCommandOptions, normalizeUpgradeCommandOptions, } from './commands/options.js';
 import { isCommandWarningError, } from './types.js';
 import { formatWarnings } from './output/reporter.js';
@@ -28,7 +30,7 @@ import { assertCatalogSourceReferencesSupported, inventoryLegacyConfigReferences
 import { parsePluginId, withResolvedCatalogPlugin, withResolvedMultiSourceCatalog, } from './utils/multi-source-catalog.js';
 import { sanitizeCatalogSourceError } from './utils/catalog-public-error.js';
 import { catalogGenerationErrorCode } from './utils/catalog-generation-error.js';
-import { bootstrapCatalogOperationSources, resolveCatalogOperationContext, } from './utils/catalog-operation-context.js';
+import { resolveCatalogOperationContext, } from './utils/catalog-operation-context.js';
 import { formatConfigCommandValue, parseConfigValue, } from './utils/config-value.js';
 import { withAwHomeMutationLock, } from './utils/aw-home-mutation-lock.js';
 import { installPortableSkills, materializePortableSkillsToDirectory, PortableCommandError, renderPortableReview, } from './portable/commands.js';
@@ -36,12 +38,12 @@ import { SkillsCliError } from './portable/skills-cli.js';
 import { computeReviewComponentDigest, listReviewRecords, parseReviewAttachment, publishReviewRecord, showReviewRecord, verifyReviewRecord, } from './commands/review-publication.js';
 import { resolveRepoRoot } from './utils/state-paths.js';
 import { runCatalogBuildCommand, runCatalogInitCommand, runCatalogValidateCommand, runCatalogVersionCommand, runPluginBuildCommand, runPluginTestCommand, } from './authoring/workspace-commands.js';
-import { runCatalogPublishCommand } from './commands/catalog-publish.js';
+import { runCatalogPublishApplyCommand, runCatalogPublishPlanCommand, } from './commands/catalog-publish.js';
 import { getCatalogStatus, renderCatalogStatus } from './commands/catalog-status.js';
-import { getCatalogContext } from './commands/catalog-context.js';
 import { activateCatalogDevSource, catalogDevSourceError, createCatalogDevFailureReceipt, deactivateCatalogDevSource, getCatalogDevSourceStatus, } from './commands/catalog-dev-source.js';
 import { getPluginCapabilitiesResult, parsePluginCapabilitySurface, renderPluginCapabilities, } from './commands/plugin-capabilities.js';
-import { AwCapabilityUnsupportedError, checkCurrentAw, describeCurrentAw, inspectPluginRequirements, IMPLEMENTED_AW_CAPABILITIES, } from './commands/aw-capabilities.js';
+import { AwCapabilityUnsupportedError, checkCurrentAw, describeCurrentAw, inspectPluginRequirements, } from './commands/aw-capabilities.js';
+import { prepareSkillEval } from './commands/skill-eval.js';
 function createDefaultIo() {
     return {
         stdout: (text) => process.stdout.write(text),
@@ -67,6 +69,148 @@ function resolveCommandReceiptExitCode(result) {
     }
     return 0;
 }
+class WriteCommandRequestError extends Error {
+    code = 'invalidArguments';
+}
+function normalizeWriteRequest(normalize) {
+    try {
+        return normalize();
+    }
+    catch (error) {
+        throw new WriteCommandRequestError(error instanceof Error ? error.message : String(error));
+    }
+}
+function writeCommandFailure(error) {
+    const message = redactString(error instanceof Error ? error.message : String(error));
+    if (error instanceof CommanderError || error instanceof WriteCommandRequestError) {
+        return { code: 'invalidArguments', message };
+    }
+    const explicitCode = error?.code;
+    if (typeof explicitCode === 'string' && /^[A-Za-z][A-Za-z0-9]*$/u.test(explicitCode)) {
+        return { code: explicitCode, message };
+    }
+    const separator = message.indexOf(':');
+    const prefix = separator > 0 ? message.slice(0, separator) : '';
+    return {
+        code: /^[A-Za-z][A-Za-z0-9]*$/u.test(prefix) ? prefix : 'writeCommandFailed',
+        message,
+    };
+}
+function preparseWriteReceiptRequest(argv) {
+    const request = { json: false, plugins: [] };
+    let positionalOnly = false;
+    for (let index = 1; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (positionalOnly) {
+            request.plugins.push(token);
+            continue;
+        }
+        if (token === '--') {
+            positionalOnly = true;
+            continue;
+        }
+        if (token === '--json') {
+            request.json = true;
+            continue;
+        }
+        if (token === '--platform' || token === '--scope') {
+            const value = argv[index + 1];
+            if (token === '--platform')
+                request.platform = value;
+            else
+                request.scope = value;
+            index += 1;
+            continue;
+        }
+        if (token.startsWith('--platform=')) {
+            request.platform = token.slice('--platform='.length);
+            continue;
+        }
+        if (token.startsWith('--scope=')) {
+            request.scope = token.slice('--scope='.length);
+            continue;
+        }
+        if (token === '--dependency-scope' || token === '--script-timeout' || token === '--log-file') {
+            index += 1;
+            continue;
+        }
+        if (token.startsWith('--'))
+            continue;
+        if (token.startsWith('-') && token !== '-') {
+            const shortOptions = token.slice(1);
+            for (let offset = 0; offset < shortOptions.length; offset += 1) {
+                const option = shortOptions[offset];
+                if (option === 'j') {
+                    request.json = true;
+                    continue;
+                }
+                if (option === 'p' || option === 's') {
+                    const value = shortOptions.slice(offset + 1) || argv[index + 1];
+                    if (option === 'p')
+                        request.platform = value;
+                    else
+                        request.scope = value;
+                    if (shortOptions.length === offset + 1)
+                        index += 1;
+                    break;
+                }
+            }
+            continue;
+        }
+        request.plugins.push(token);
+    }
+    return request;
+}
+function jsonWriteCommandRequest(argv) {
+    const command = argv[0];
+    if (!['install', 'upgrade', 'reinstall', 'uninstall', 'cleanup', 'sync'].includes(command ?? '')) {
+        return null;
+    }
+    const request = preparseWriteReceiptRequest(argv);
+    if (!request.json)
+        return null;
+    const rawPlatform = request.platform;
+    const platform = rawPlatform === 'codex' || rawPlatform === 'claude' || rawPlatform === 'both'
+        ? rawPlatform
+        : 'codex';
+    return {
+        command: command,
+        plugins: request.plugins,
+        platform,
+        scope: request.scope === 'project' ? 'project' : 'user',
+    };
+}
+function writeCommandFailureReceipt(write, request, error) {
+    const platforms = request.platform === 'both'
+        ? ['codex', 'claude']
+        : [request.platform];
+    writeJsonReceipt(write, buildRebuildReceiptJson(request.command, {
+        platforms,
+        plugins: request.plugins,
+        warnings: [],
+        overallState: 'failed',
+        errors: [writeCommandFailure(error)],
+        receiptTargets: request.plugins.flatMap((selector) => platforms.map((platform) => {
+            let pluginName = selector;
+            let sourceId;
+            try {
+                const parsed = parsePluginId(selector);
+                pluginName = parsed.pluginName;
+                sourceId = parsed.sourceId;
+            }
+            catch {
+                // Keep the raw selector in the failed receipt.
+            }
+            return {
+                pluginName,
+                pluginId: selector,
+                ...(sourceId ? { sourceId } : {}),
+                platform,
+                scope: request.scope,
+            };
+        })),
+    }));
+}
 async function runAuthoringScript(options) {
     const scriptPath = path.join(resolveCliPackageRoot(), 'dist', 'authoring', 'scripts', options.scriptName);
     return new Promise((resolve, reject) => {
@@ -150,6 +294,9 @@ export function buildEquivalentWriteCommandTokens(command, selection, rawOptions
         ...(rawOptions.allowManagedCodexInstall === true
             ? ['--allow-managed-codex-install']
             : []),
+        ...(command === 'install'
+            ? (rawOptions.dependencyScope ?? []).flatMap((value) => ['--dependency-scope', value])
+            : []),
         ...(command === 'cleanup' ? [] : optionTokens('--script-timeout', rawOptions.scriptTimeout)),
         ...(!all && selection.plugins.length > 0 ? ['--', ...selection.plugins] : []),
     ];
@@ -309,7 +456,6 @@ async function resolveStoredOnlyConfigIdentity(options) {
     const sourceIdentity = [...identities][0];
     await withResolvedMultiSourceCatalog({
         cliVersion: resolveCliVersion(),
-        freshnessPolicy: 'cacheFirst',
         sourceIds: [parsed.sourceId],
         env: options.context.env,
         consume: async (catalog) => {
@@ -338,7 +484,6 @@ async function resolveMultiSourceConfigRead(options) {
     return withResolvedCatalogPlugin({
         selector: options.selector,
         cliVersion: resolveCliVersion(),
-        freshnessPolicy: 'cacheFirst',
         env: options.context.env,
         consume: async ({ pluginId, source, plugin }) => {
             const result = await resolveConfigRead({
@@ -411,9 +556,9 @@ export function createManagedCodexAuthorizer(rawOptions, context) {
         return !response.cancelled && response.value === true;
     };
 }
-async function executeWriteCommand(command, pluginNames, rawOptions, context) {
+async function executeWriteCommand(command, pluginNames, rawOptions, context, directCli = false) {
     const raw = { cwd: context.cwd, ...rawOptions };
-    const commandOptions = command === 'install'
+    const commandOptions = normalizeWriteRequest(() => command === 'install'
         ? normalizeInstallCommandOptions(raw)
         : command === 'upgrade'
             ? normalizeUpgradeCommandOptions(raw)
@@ -421,7 +566,7 @@ async function executeWriteCommand(command, pluginNames, rawOptions, context) {
                 ? normalizeUninstallCommandOptions(raw)
                 : command === 'cleanup'
                     ? normalizeCleanupCommandOptions(raw)
-                    : normalizeReinstallCommandOptions(raw);
+                    : normalizeReinstallCommandOptions(raw));
     await emitCommandEvent(context, {
         type: 'options:normalized',
         data: { plugins: pluginNames, options: commandOptions },
@@ -429,6 +574,7 @@ async function executeWriteCommand(command, pluginNames, rawOptions, context) {
     const managedCodexAuthorizer = createManagedCodexAuthorizer(rawOptions, context);
     const runtime = {
         ...context,
+        directCli,
         ...(managedCodexAuthorizer ? { managedCodexAuthorizer } : {}),
     };
     switch (command) {
@@ -441,10 +587,11 @@ async function executeWriteCommand(command, pluginNames, rawOptions, context) {
 }
 async function runWriteCommandAction(command, pluginNames, rawOptions, context) {
     if ((command === 'cleanup' || command === 'reinstall') && pluginNames.length > 1) {
-        throw new Error(`${command} 命令当前只支持单个插件目标。`);
+        throw new WriteCommandRequestError(`${command} 命令当前只支持单个插件目标。`);
+    }
+    if (command === 'upgrade') {
+        normalizeWriteRequest(() => assertUpgradeAllConflict(pluginNames, rawOptions.all === true));
     }
-    if (command === 'upgrade')
-        assertUpgradeAllConflict(pluginNames, rawOptions.all === true);
     const missingPlugin = pluginNames.length === 0 && !(command === 'upgrade' && rawOptions.all === true);
     const missingPlatform = rawOptions.platform === undefined;
     const missingScope = command === 'cleanup' && rawOptions.scope === undefined;
@@ -460,11 +607,11 @@ async function runWriteCommandAction(command, pluginNames, rawOptions, context)
     if (!missing) {
         return {
             cancelled: false,
-            result: await executeWriteCommand(command, pluginNames, rawOptions, context),
+            result: await executeWriteCommand(command, pluginNames, rawOptions, context, true),
         };
     }
     if (!isWizardAvailable(context, rawOptions)) {
-        throw new Error(writeCommandUsage(command));
+        throw new WriteCommandRequestError(writeCommandUsage(command));
     }
     const loaded = await loadConsoleItemsResult({
         cwd: context.cwd,
@@ -785,6 +932,93 @@ export function buildProgram(options = {}) {
     const skill = program
         .command('skill')
         .description('Install, materialize, or validate Agent Skills');
+    const skillEval = skill
+        .command('eval')
+        .description('Prepare or diagnose deterministic Agent Skill Eval inputs');
+    skillEval
+        .command('doctor')
+        .description('Inspect Agent Skill Eval provider readiness without model execution')
+        .requiredOption('--json', 'emit one provider doctor JSON object')
+        .action(async () => {
+        try {
+            writeJsonReceipt(io.stdout, await doctorEvalProviders({ sourceEnv: env }));
+        }
+        catch (error) {
+            writeJsonReceipt(io.stdout, {
+                ok: false,
+                error: redactString(error instanceof Error ? error.message : String(error)),
+            });
+            commandExitState.exitCode = 1;
+        }
+    });
+    skillEval
+        .command('prepare')
+        .description('Prepare one complete Agent Skill Eval input directory')
+        .argument('<plugin>', 'canonical Workspace plugin name')
+        .argument('<skill>', 'owner Skill name')
+        .option('--suite <suite>', 'Eval suite ID')
+        .option('--profile <profile>', 'Eval profile ID')
+        .option('--workspace-root <root>', 'Catalog Workspace root')
+        .option('--split <split>', 'case split filter')
+        .option('--case <id>', 'case ID filter')
+        .option('--runs <count>', 'runs per selected case')
+        .option('--timeout-ms <milliseconds>', 'timeout for each provider attempt')
+        .option('--baseline <mode>', 'append without-skill comparison')
+        .option('--previous-version <runtime-skill-root>', 'append a previous-version comparison')
+        .option('--keep-workspace', 'retain the preparation materialization workspace', false)
+        .requiredOption('--output <spec-directory>', 'new EvalSpec directory')
+        .requiredOption('--json', 'emit one preparation receipt JSON object')
+        .action(async (pluginName, skillName, rawOptions) => {
+        try {
+            const workspace = await resolveCatalogWorkspaceRoot({
+                cwd,
+                ...(rawOptions.workspaceRoot === undefined ? {} : { explicitRoot: rawOptions.workspaceRoot }),
+                mode: 'existing',
+                env,
+            });
+            const runs = rawOptions.runs === undefined
+                ? undefined
+                : (/^[1-9][0-9]*$/u.test(rawOptions.runs) ? Number(rawOptions.runs) : Number.NaN);
+            const timeoutMs = rawOptions.timeoutMs === undefined
+                ? undefined
+                : (/^[1-9][0-9]*$/u.test(rawOptions.timeoutMs) ? Number(rawOptions.timeoutMs) : Number.NaN);
+            const receipt = await prepareSkillEval({
+                workspaceRoot: workspace.workspaceRoot,
+                workspaceRootResolvedFrom: workspace.workspaceRootResolvedFrom,
+                pluginName,
+                skillName,
+                ...(rawOptions.suite === undefined ? {} : { suiteId: rawOptions.suite }),
+                ...(rawOptions.profile === undefined ? {} : { profileId: rawOptions.profile }),
+                output: rawOptions.output,
+                cwd,
+                env,
+                ...(rawOptions.split === undefined ? {} : { split: rawOptions.split }),
+                ...(rawOptions.case === undefined ? {} : { caseId: rawOptions.case }),
+                ...(runs === undefined ? {} : { runs }),
+                ...(timeoutMs === undefined ? {} : { timeoutMs }),
+                ...(rawOptions.baseline === undefined ? {} : {
+                    baseline: rawOptions.baseline,
+                }),
+                ...(rawOptions.previousVersion === undefined ? {} : {
+                    previousVersion: rawOptions.previousVersion,
+                }),
+                ...(rawOptions.keepWorkspace === true ? { keepWorkspace: true } : {}),
+            });
+            writeJsonReceipt(io.stdout, receipt);
+        }
+        catch (error) {
+            writeJsonReceipt(io.stdout, {
+                schemaVersion: 1,
+                command: 'skill:eval:prepare',
+                ok: false,
+                errors: [{
+                        code: 'evalPreparationFailed',
+                        message: redactString(error instanceof Error ? error.message : String(error)),
+                    }],
+            });
+            commandExitState.exitCode = 1;
+        }
+    });
     const review = program
         .command('review')
         .description('Publish and inspect immutable review records');
@@ -945,7 +1179,7 @@ export function buildProgram(options = {}) {
         .option('--skill <name...>', 'install only selected Skill names')
         .option('--agent <id...>', 'install to explicit Agent IDs')
         .option('-y, --yes', 'confirm the reviewed install', false)
-        .option('-j, --json', 'emit one receipt v4 JSON object', false)
+        .option('-j, --json', 'emit one receipt v5 JSON object', false)
         .action(async (selector, rawOptions) => {
         const context = createActionContext('skill:install', {});
         const writeFailure = (error) => {
@@ -955,7 +1189,7 @@ export function buildProgram(options = {}) {
                     ? error.code
                     : 'portableInstallFailed');
             writeJsonReceipt(io.stdout, {
-                receiptSchemaVersion: 4,
+                receiptSchemaVersion: 5,
                 command: 'skill:install',
                 ok: false,
                 status: 'failed',
@@ -1049,7 +1283,7 @@ export function buildProgram(options = {}) {
         .requiredOption('-s, --scope <scope>', 'project or user')
         .requiredOption('--out <dir>', 'output directory')
         .option('--skill <name...>', 'write only selected Skill names')
-        .option('-j, --json', 'emit one receipt v4 JSON object', false)
+        .option('-j, --json', 'emit one receipt v5 JSON object', false)
         .action(async (selector, rawOptions) => {
         const context = createActionContext('skill:materialize', {});
         try {
@@ -1076,7 +1310,7 @@ export function buildProgram(options = {}) {
                     ? error.code
                     : 'portableMaterializeFailed');
             writeJsonReceipt(io.stdout, {
-                receiptSchemaVersion: 4,
+                receiptSchemaVersion: 5,
                 command: 'skill:materialize',
                 ok: false,
                 plugin: { id: selector },
@@ -1108,7 +1342,7 @@ export function buildProgram(options = {}) {
         '',
         'During development, keep the current stable target when production content changes.',
         'Next, run `aw plugin validate`, `aw plugin test`, `aw plugin build`, and `aw catalog build`.',
-        'Publish only as an explicit later step; inspect `aw catalog publish --help` first.',
+        'Publish only as an explicit later step; inspect `aw catalog publish plan --help` first.',
         '',
     ].join('\n'))
         .argument('<plugin-name>', 'lowercase hyphen-case plugin name')
@@ -1133,7 +1367,7 @@ export function buildProgram(options = {}) {
         '',
         'During development, keep the current stable target when production content changes.',
         'Next, run `aw plugin validate`, `aw plugin test`, `aw plugin build`, and `aw catalog build`.',
-        'Publish only as an explicit later step; inspect `aw catalog publish --help` first.',
+        'Publish only as an explicit later step; inspect `aw catalog publish plan --help` first.',
         '',
     ].join('\n'))
         .argument('<plugin-name>', 'existing lowercase hyphen-case plugin name')
@@ -1252,6 +1486,7 @@ export function buildProgram(options = {}) {
                 cwd,
                 ...(rawOptions.workspaceRoot === undefined ? {} : { explicitRoot: rawOptions.workspaceRoot }),
                 mode: 'initialize',
+                env,
             });
             await runCatalogInitCommand({
                 ...rawOptions,
@@ -1267,27 +1502,6 @@ export function buildProgram(options = {}) {
             commandExitState.exitCode = 1;
         }
     });
-    catalog
-        .command('context')
-        .description('Inspect resolved Catalog Workspace and publication context without network access')
-        .option('--workspace-root <path>', 'explicit Catalog Workspace root')
-        .option('--remote <name>', 'Git remote (default: origin, otherwise sole remote; explicit if ambiguous)')
-        .option('--branch <name>', 'explicit Catalog publication branch')
-        .requiredOption('--json', 'emit one schema 1 JSON object')
-        .action(async (rawOptions) => {
-        const receipt = await getCatalogContext({
-            cwd,
-            workspaceRoot: rawOptions.workspaceRoot,
-            remote: rawOptions.remote,
-            branch: rawOptions.branch,
-            env,
-            awVersion: resolveCliVersion(),
-            capabilities: IMPLEMENTED_AW_CAPABILITIES,
-        });
-        writeJsonReceipt(io.stdout, receipt);
-        if (receipt.issues.some((issue) => issue.blocking))
-            commandExitState.exitCode = 1;
-    });
     catalog
         .command('version')
         .description('Read or set the Catalog version')
@@ -1350,7 +1564,7 @@ export function buildProgram(options = {}) {
     });
     catalog
         .command('validate')
-        .description('Validate a schema 5 Catalog snapshot')
+        .description('Validate a schema 6 Catalog snapshot')
         .argument('<snapshot-directory>', 'Catalog snapshot directory')
         .option('--json', 'emit one machine-readable JSON result', false)
         .action(async (snapshotDirectory, rawOptions) => {
@@ -1371,19 +1585,13 @@ export function buildProgram(options = {}) {
     });
     catalog
         .command('status')
-        .description('Inspect a Catalog Workspace; --preflight executes plugin validation and build code')
+        .description('Inspect static Catalog Workspace, snapshot, and Git facts')
         .option('--workspace-root <path>', 'Catalog Workspace root (default: nearest ancestor from current directory)')
-        .option('--remote <name>', 'Git remote for preflight (default: origin, otherwise sole remote; explicit if ambiguous)')
-        .option('--branch <name>', 'dedicated Catalog branch for preflight (default: catalog)')
-        .option('--preflight', 'run publication validation and temporary plugin builds (executes plugin code)', false)
         .option('--json', 'emit one machine-readable JSON status object', false)
         .action(async (rawOptions) => {
         const receipt = await getCatalogStatus({
             cwd,
             workspaceRoot: rawOptions.workspaceRoot,
-            remote: rawOptions.remote,
-            branch: rawOptions.branch,
-            preflight: rawOptions.preflight,
             env,
         });
         if (rawOptions.json)
@@ -1392,24 +1600,70 @@ export function buildProgram(options = {}) {
             io.stdout(renderCatalogStatus(receipt));
         commandExitState.exitCode = receipt.ok ? 0 : 1;
     });
-    catalog
+    const catalogPublish = catalog
         .command('publish')
-        .description('Publish a versioned Catalog snapshot to a configured Git remote')
+        .description('Plan or apply a versioned Catalog publication');
+    catalogPublish
+        .command('plan')
+        .description('Prepare and inspect the exact Catalog publication plan')
+        .option('--workspace-root <path>', 'Catalog Workspace root (default: nearest ancestor from current directory)')
+        .option('--remote <name>', 'Git remote (default: origin, otherwise sole remote; explicit if ambiguous)')
+        .option('--branch <name>', 'dedicated Catalog branch (default: catalog)')
+        .option('--json', 'emit one machine-readable JSON result', false)
+        .action(async (rawOptions) => {
+        try {
+            const result = await runCatalogPublishPlanCommand({
+                cwd,
+                workspaceRoot: rawOptions.workspaceRoot,
+                remote: rawOptions.remote,
+                branch: rawOptions.branch,
+                env,
+                io,
+            });
+            if (rawOptions.json)
+                writeJsonReceipt(io.stdout, result);
+            else {
+                writeLine(io.stdout, `Workspace identity: ${result.workspaceIdentity}`);
+                writeLine(io.stdout, `Source HEAD: ${result.sourceHead}`);
+                writeLine(io.stdout, `Remote identity: ${result.descriptor.remote.identityDigest}`);
+                writeLine(io.stdout, `Remote: ${result.remote} (${result.remoteUrl})`);
+                writeLine(io.stdout, `Branch: refs/heads/${result.branch}`);
+                writeLine(io.stdout, `Parent: ${result.parent ?? '<root>'}`);
+                writeLine(io.stdout, `Tag: refs/tags/${result.tag}`);
+                writeLine(io.stdout, `Snapshot digest: ${result.snapshotDigest}`);
+                writeLine(io.stdout, `Plan digest: ${result.planDigest}`);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (rawOptions.json)
+                writeJsonReceipt(io.stdout, {
+                    command: 'catalog:publish:plan',
+                    ok: false,
+                    errors: [{ message }],
+                });
+            writeLine(io.stderr, message);
+            commandExitState.exitCode = 1;
+        }
+    });
+    catalogPublish
+        .command('apply')
+        .description('Apply an authorized Catalog publication plan')
         .option('--workspace-root <path>', 'Catalog Workspace root (default: nearest ancestor from current directory)')
         .option('--remote <name>', 'Git remote (default: origin, otherwise sole remote; explicit if ambiguous)')
         .option('--branch <name>', 'dedicated Catalog branch (default: catalog)')
-        .option('--expected-descriptor-digest <digest>', 'required exact descriptor returned by publication preflight')
+        .requiredOption('--expected-plan-digest <sha256>', 'exact plan digest returned by catalog publish plan')
         .option('-y, --yes', 'confirm publication without a prompt', false)
         .option('--json', 'emit one machine-readable JSON result', false)
         .action(async (rawOptions) => {
         try {
-            const context = createActionContext('catalog:publish', {});
-            const result = await runCatalogPublishCommand({
+            const context = createActionContext('catalog:publish:apply', {});
+            const result = await runCatalogPublishApplyCommand({
                 cwd,
                 workspaceRoot: rawOptions.workspaceRoot,
                 remote: rawOptions.remote,
                 branch: rawOptions.branch,
-                expectedDescriptorDigest: rawOptions.expectedDescriptorDigest,
+                expectedPlanDigest: rawOptions.expectedPlanDigest,
                 yes: rawOptions.yes,
                 json: rawOptions.json,
                 env,
@@ -1438,7 +1692,7 @@ export function buildProgram(options = {}) {
             const message = error instanceof Error ? error.message : String(error);
             if (rawOptions.json)
                 writeJsonReceipt(io.stdout, {
-                    command: 'catalog:publish',
+                    command: 'catalog:publish:apply',
                     ok: false,
                     errors: [{ message }],
                 });
@@ -1455,7 +1709,7 @@ export function buildProgram(options = {}) {
         .option('--source-id <id>', 'explicit managed source ID')
         .option('--primary', 'make the development source primary', false)
         .option('--force-build', 'rebuild a current snapshot', false)
-        .requiredOption('--json', 'emit one schema 1 JSON receipt')
+        .requiredOption('--json', 'emit one schema 2 JSON receipt')
         .action(async (rawOptions) => {
         try {
             const receipt = await activateCatalogDevSource({
@@ -1482,7 +1736,7 @@ export function buildProgram(options = {}) {
     catalogDev
         .command('status')
         .option('--workspace-root <path>', 'explicit Catalog Workspace root')
-        .requiredOption('--json', 'emit one schema 1 JSON receipt')
+        .requiredOption('--json', 'emit one schema 3 JSON receipt')
         .action(async (rawOptions) => {
         const receipt = await getCatalogDevSourceStatus({
             cwd,
@@ -1496,12 +1750,18 @@ export function buildProgram(options = {}) {
     catalogDev
         .command('deactivate')
         .option('--workspace-root <path>', 'explicit Catalog Workspace root')
-        .requiredOption('--json', 'emit one schema 1 JSON receipt')
+        .option('--source-id <id>', 'recover one managed source by exact ID')
+        .option('--replacement-primary <id>', 'replacement when the target source is primary')
+        .option('-y, --yes', 'confirm recovery by source ID', false)
+        .requiredOption('--json', 'emit one schema 2 JSON receipt')
         .action(async (rawOptions) => {
         try {
             const receipt = await deactivateCatalogDevSource({
                 cwd,
                 workspaceRoot: rawOptions.workspaceRoot,
+                sourceId: rawOptions.sourceId,
+                replacementPrimary: rawOptions.replacementPrimary,
+                yes: rawOptions.yes,
                 env,
             });
             writeJsonReceipt(io.stdout, receipt);
@@ -1510,7 +1770,8 @@ export function buildProgram(options = {}) {
         catch (error) {
             const failure = catalogDevSourceError(error);
             writeJsonReceipt(io.stdout, createCatalogDevFailureReceipt({
-                command: 'deactivate', cwd, workspaceRoot: rawOptions.workspaceRoot, ...failure,
+                command: 'deactivate', cwd, workspaceRoot: rawOptions.workspaceRoot,
+                sourceId: rawOptions.sourceId, ...failure,
             }));
             commandExitState.exitCode = 1;
         }
@@ -1523,7 +1784,7 @@ export function buildProgram(options = {}) {
         const message = failure instanceof Error ? failure.message : String(error);
         if (json) {
             writeJsonReceipt(io.stdout, {
-                receiptSchemaVersion: 4,
+                receiptSchemaVersion: 5,
                 command,
                 ok: false,
                 changed: false,
@@ -1540,7 +1801,9 @@ export function buildProgram(options = {}) {
         const message = redactString(failure.message);
         if (json) {
             writeJsonReceipt(io.stdout, {
-                catalogGenerationSchemaVersion: 1,
+                ...(command === 'catalog:source:sync'
+                    ? { catalogGenerationSchemaVersion: 1 }
+                    : { catalogGenerationStatusSchemaVersion: 1 }),
                 command,
                 ok: false,
                 ...(sourceId ? { sourceId } : {}),
@@ -1569,7 +1832,7 @@ export function buildProgram(options = {}) {
                                 : message.split(':', 1)[0] || 'configMutationFailed';
         if (json && !message.includes('Usage:')) {
             writeJsonReceipt(io.stdout, {
-                receiptSchemaVersion: 4,
+                receiptSchemaVersion: 5,
                 command,
                 ok: false,
                 overallState: 'failed',
@@ -1582,24 +1845,16 @@ export function buildProgram(options = {}) {
     };
     const withResolvedConfigMutationPlugin = (context, selector, consume) => (async () => {
         const parsed = parsePluginId(selector);
-        await bootstrapCatalogOperationSources({
-            cliVersion: resolveCliVersion(),
-            ...(parsed.sourceId ? { sourceIds: [parsed.sourceId] } : {}),
-            env: context.env,
-        });
         return withAwHomeMutationLock({
             env: context.env,
             action: async (awHomeMutationToken) => {
                 const catalogOperationContext = await resolveCatalogOperationContext({
-                    cliVersion: resolveCliVersion(),
                     ...(parsed.sourceId ? { sourceIds: [parsed.sourceId] } : {}),
                     env: context.env,
-                    bootstrapMissingActive: false,
                 });
                 return withResolvedCatalogPlugin({
                     selector,
                     cliVersion: resolveCliVersion(),
-                    freshnessPolicy: 'cacheFirst',
                     operationContext: catalogOperationContext,
                     env: context.env,
                     consume: (resolution) => consume(resolution, awHomeMutationToken, catalogOperationContext),
@@ -1622,106 +1877,57 @@ export function buildProgram(options = {}) {
         }
     });
     catalogSource
-        .command('refresh')
+        .command('sync')
         .argument('<id>')
-        .option('-j, --json', 'print the generation refresh result as JSON', false)
+        .option('--check', 'fetch and validate without changing the Catalog store or Active state', false)
+        .option('-j, --json', 'print the source sync result as JSON', false)
         .action(async (id, rawOptions) => {
         try {
-            const result = await refreshCatalogSourceGenerationCommand({
+            const result = await syncCatalogSourceCommand({
                 sourceId: id,
                 cliVersion: resolveCliVersion(),
+                check: rawOptions.check === true,
                 env,
             });
             if (rawOptions.json) {
                 writeJsonReceipt(io.stdout, {
                     ...result,
-                    command: 'catalog:source:refresh',
-                    ok: true,
-                });
-            }
-            else {
-                writeLine(io.stdout, `Catalog source ${id}: ${result.outcome}.`);
-            }
-        }
-        catch (error) {
-            writeCatalogGenerationFailure('catalog:source:refresh', id, rawOptions.json === true, error);
-        }
-    });
-    catalogSource
-        .command('activate-candidate')
-        .argument('<id>')
-        .option('-j, --json', 'print the generation activation result as JSON', false)
-        .action(async (id, rawOptions) => {
-        try {
-            const result = await activateCatalogSourceCandidateCommand({ sourceId: id, env });
-            if (rawOptions.json) {
-                writeJsonReceipt(io.stdout, {
-                    ...result,
-                    command: 'catalog:source:activate-candidate',
+                    command: 'catalog:source:sync',
                     ok: true,
                 });
             }
             else {
-                writeLine(io.stdout, `Catalog source ${id} Candidate activated.`);
+                writeLine(io.stdout, rawOptions.check
+                    ? `Catalog source ${id} is valid.`
+                    : `Catalog source ${id}: ${result.outcome}.`);
             }
         }
         catch (error) {
-            writeCatalogGenerationFailure('catalog:source:activate-candidate', id, rawOptions.json === true, error);
+            writeCatalogGenerationFailure('catalog:source:sync', id, rawOptions.json === true, error);
         }
     });
     catalogSource
-        .command('generation-status')
+        .command('status')
         .argument('[id]')
-        .option('-j, --json', 'print Catalog generation status as JSON', false)
+        .option('-j, --json', 'print offline Catalog source status as JSON', false)
         .action(async (id, rawOptions) => {
         try {
-            const result = await catalogGenerationStatusCommand({ sourceId: id, env });
+            const result = await catalogSourceStatusCommand({ sourceId: id, env });
             if (rawOptions.json) {
                 writeJsonReceipt(io.stdout, result);
             }
             else {
                 for (const source of result.sources) {
-                    const active = source.active ? `Active ${source.active.catalogVersion}` : 'no Active';
-                    const candidate = source.candidate
-                        ? `, Candidate ${source.candidate.catalogVersion}`
-                        : '';
-                    writeLine(io.stdout, `${source.sourceId}: ${active}${candidate} (${source.refreshPolicy})`);
+                    const active = source.active
+                        ? `Active ${source.active.snapshotDigest}`
+                        : 'no Active';
+                    const readiness = source.activeReady ? 'ready' : 'not ready';
+                    writeLine(io.stdout, `${source.sourceId}: ${active}, ${readiness}`);
                 }
             }
         }
         catch (error) {
-            writeCatalogGenerationFailure('catalog:source:generation-status', id, rawOptions.json === true, error);
-        }
-    });
-    catalogSource
-        .command('refresh-policy')
-        .argument('<id>')
-        .argument('<policy>', 'startup or manual')
-        .option('-j, --json', 'print Catalog refresh policy result as JSON', false)
-        .action(async (id, policy, rawOptions) => {
-        try {
-            if (policy !== 'startup' && policy !== 'manual') {
-                throw new Error('Catalog refresh policy must be startup or manual.');
-            }
-            const result = await setCatalogSourceRefreshPolicyCommand({
-                sourceId: id,
-                refreshPolicy: policy,
-                env,
-            });
-            if (rawOptions.json) {
-                writeJsonReceipt(io.stdout, {
-                    catalogGenerationSchemaVersion: 1,
-                    command: 'catalog:source:refresh-policy',
-                    ok: true,
-                    ...result,
-                });
-            }
-            else {
-                writeLine(io.stdout, `Catalog source ${id} refresh policy: ${result.refreshPolicy}.`);
-            }
-        }
-        catch (error) {
-            writeCatalogGenerationFailure('catalog:source:refresh-policy', id, rawOptions.json === true, error);
+            writeCatalogGenerationFailure('catalog:source:status', id, rawOptions.json === true, error);
         }
     });
     catalogSource
@@ -1868,7 +2074,6 @@ export function buildProgram(options = {}) {
     });
     program
         .command('init')
-        .option('-f, --force', 're-fetch and rebuild the current catalog cache entry', false)
         .option('-j, --json', 'print receipt as JSON', false)
         .option('-v, --verbose', 'show command diagnostics', false)
         .option('-D, --debug', 'write debug diagnostics to a log file', false)
@@ -1876,8 +2081,6 @@ export function buildProgram(options = {}) {
         .action(async (rawOptions) => {
         const context = createActionContext('init', rawOptions);
         const result = await runActionWithContext(context, () => initCommand({
-            force: rawOptions.force,
-            cliVersion: resolveCliVersion(),
             env: context.env,
         }));
         if (rawOptions.json) {
@@ -1888,20 +2091,68 @@ export function buildProgram(options = {}) {
                 writeLine(io.stdout, line);
             }
         }
-        writeWarnings(io.stderr, result.warnings, { actionableOnly: true });
         for (const source of result.sources) {
             if (!source.ok && source.error)
                 writeLine(io.stderr, `${source.id}: ${source.error}`);
         }
         commandExitState.exitCode = result.ok ? 0 : 1;
     });
+    program
+        .command('sync')
+        .description('Reconcile Codex actual state from existing desired intent')
+        .argument('[plugins...]')
+        .requiredOption('-s, --scope <scope>', 'project or user')
+        .requiredOption('-p, --platform <platform>', 'codex')
+        .option('-a, --all', 'reconcile every desired plugin in the selected scope', false)
+        .option('-y, --yes', 'authorize shared native replacement or forced repair', false)
+        .option('--allow-managed-codex-install', 'allow this command to acquire or rebuild the pinned AW-managed Codex runtime', false)
+        .option('-j, --json', 'print sync receipt as JSON', false)
+        .option('-v, --verbose', 'show command diagnostics', false)
+        .option('-D, --debug', 'write debug diagnostics to a log file', false)
+        .option('--log-file <path>', 'write debug diagnostics to the specified file')
+        .action(async (plugins, rawOptions) => {
+        const context = createActionContext('sync', rawOptions);
+        const normalized = normalizeWriteRequest(() => normalizeInstallCommandOptions({
+            cwd: context.cwd,
+            scope: rawOptions.scope,
+            platform: rawOptions.platform,
+            allowManagedCodexInstall: rawOptions.allowManagedCodexInstall,
+        }));
+        if (normalized.platform !== 'codex') {
+            throw new Error('syncPlatformUnsupported: sync requires --platform codex.');
+        }
+        const syncPlatform = normalized.platform;
+        const result = await runActionWithContext(context, () => syncCommand(plugins ?? [], {
+            cwd: context.cwd,
+            env: context.env,
+            platform: syncPlatform,
+            scope: normalized.scope,
+            all: rawOptions.all,
+            yes: rawOptions.yes,
+            json: rawOptions.json,
+            interactive: context.interactive && context.isTty && !context.isCi,
+            prompt: context.prompt,
+            allowManagedCodexInstall: rawOptions.allowManagedCodexInstall,
+        }, context));
+        if (rawOptions.json) {
+            writeJsonReceipt(io.stdout, buildRebuildReceiptJson('sync', result));
+        }
+        else {
+            for (const line of renderRebuildReceipt('sync', result))
+                writeLine(io.stdout, line);
+        }
+        writeWarnings(io.stderr, result.warnings, { actionableOnly: true });
+        commandExitState.exitCode = resolveCommandReceiptExitCode(result);
+    });
     program
         .command('install')
         .argument('[plugins...]')
         .option('-s, --scope <scope>', 'project or user')
         .option('-p, --platform <platform>', 'codex | claude | both')
+        .option('--dependency-scope <pluginId[#platform]=scope>', 'place one dependency at project or user scope; repeat for more dependencies', (value, previous) => [...previous, value], [])
         .option('--script-timeout <ms>', 'override plugin lifecycle script timeout in milliseconds')
         .option('--allow-managed-codex-install', 'allow this command to acquire or rebuild the pinned AW-managed Codex runtime', false)
+        .option('-y, --yes', 'authorize shared Codex native replacement', false)
         .option('-j, --json', 'print receipt as JSON', false)
         .option('-v, --verbose', 'show command diagnostics', false)
         .option('-D, --debug', 'write debug diagnostics to a log file', false)
@@ -1959,6 +2210,7 @@ export function buildProgram(options = {}) {
         .option('-p, --platform <platform>', 'codex | claude | both')
         .option('--script-timeout <ms>', 'override plugin lifecycle script timeout in milliseconds')
         .option('--allow-managed-codex-install', 'allow this command to acquire or rebuild the pinned AW-managed Codex runtime', false)
+        .option('-y, --yes', 'authorize shared Codex native replacement', false)
         .option('-j, --json', 'print receipt as JSON', false)
         .option('-v, --verbose', 'show command diagnostics', false)
         .option('-D, --debug', 'write debug diagnostics to a log file', false)
@@ -2015,6 +2267,7 @@ export function buildProgram(options = {}) {
         .option('-p, --platform <platform>', 'codex | claude | both')
         .option('--script-timeout <ms>', 'override plugin lifecycle script timeout in milliseconds')
         .option('--allow-managed-codex-install', 'allow this command to acquire or rebuild the pinned AW-managed Codex runtime', false)
+        .option('-y, --yes', 'authorize shared Codex native replacement or forced reinstall', false)
         .option('-j, --json', 'print receipt as JSON', false)
         .option('-v, --verbose', 'show command diagnostics', false)
         .option('-D, --debug', 'write debug diagnostics to a log file', false)
@@ -2233,7 +2486,7 @@ export function buildProgram(options = {}) {
                     });
                     return {
                         ok: writeReceipt.overallState === 'succeeded',
-                        receiptSchemaVersion: 4,
+                        receiptSchemaVersion: 5,
                         command: 'config:set',
                         ...writeReceipt,
                         plugin: plugin.manifest.name,
@@ -2388,7 +2641,7 @@ export function buildProgram(options = {}) {
                     });
                     return {
                         ok: writeReceipt.overallState === 'succeeded',
-                        receiptSchemaVersion: 4,
+                        receiptSchemaVersion: 5,
                         command: 'config:unset',
                         ...writeReceipt,
                         plugin: plugin.manifest.name,
@@ -2512,7 +2765,7 @@ export function buildProgram(options = {}) {
                         });
                         return {
                             ok: resetReceipt.overallState === 'succeeded',
-                            receiptSchemaVersion: 4,
+                            receiptSchemaVersion: 5,
                             command: 'config:reset',
                             ...resetReceipt,
                             plugin: plugin.manifest.name,
@@ -2620,7 +2873,7 @@ export function buildProgram(options = {}) {
         .option('-j, --json', 'print status as JSON', false)
         .action(async (plugins, rawOptions) => {
         const context = createActionContext('status', rawOptions);
-        const result = await runActionWithContext(context, () => statusCommandV5({
+        const result = await runActionWithContext(context, () => statusCommandV6({
             plugins: plugins ?? [],
             cwd,
             env: context.env,
@@ -2673,6 +2926,7 @@ export async function runCli(argv, options = {}) {
         && ['activate', 'status', 'deactivate'].includes(argv[2] ?? '')
         ? argv[2]
         : null;
+    const jsonWriteRequest = jsonWriteCommandRequest(argv);
     try {
         const authoringScriptByCommand = {
             init: 'init-plugin.mjs',
@@ -2742,7 +2996,7 @@ export async function runCli(argv, options = {}) {
             const message = 'option --subdir cannot be used with option --no-subdir';
             if (argv.includes('--json') && argv[0] === 'catalog' && argv[1] === 'source' && argv[2] === 'update') {
                 writeJsonReceipt(io.stdout, {
-                    receiptSchemaVersion: 4,
+                    receiptSchemaVersion: 5,
                     command: 'catalog:source:update',
                     ok: false,
                     changed: false,
@@ -2776,7 +3030,9 @@ export async function runCli(argv, options = {}) {
         }
         const program = buildProgram({
             ...options,
-            io: jsonCatalogDevCommand ? { ...io, stderr: () => undefined } : io,
+            io: jsonCatalogDevCommand || jsonWriteRequest
+                ? { ...io, stderr: () => undefined }
+                : io,
             diagnostics: {
                 ...options.diagnostics,
                 metadata: {
@@ -2810,6 +3066,10 @@ export async function runCli(argv, options = {}) {
             }));
             return 1;
         }
+        if (jsonWriteRequest) {
+            writeCommandFailureReceipt(io.stdout, jsonWriteRequest, error);
+            return 1;
+        }
         if (jsonAuthoringCommand && !(error instanceof CommanderError)) {
             const message = error instanceof Error ? error.message : String(error);
             if (jsonAuthoringCommand === 'plugin:validate') {