@lesliechan721/aw 0.1.0-beta.10 → 0.1.0-beta.12

package/dist/src/index.js

@@ -7,24 +7,24 @@ import { Command, CommanderError, Option } from 'commander';
 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 { addCatalogSourceCommand, preflightCatalogSourceMutation, explicitRefPolicy, listCatalogSources, removeCatalogSourceCommand, setPrimaryCatalogSourceCommand, updateCatalogSourceCommand, } from './commands/catalog-source.js';
 import { catalogSourceStatusCommand, syncCatalogSourceCommand, } from './commands/catalog-generation.js';
-import { catalogStorePrune, catalogStoreStatus } from './commands/catalog-store.js';
+import { catalogStoreErrorCode, catalogStorePrune, catalogStoreStatus, } from './commands/catalog-store.js';
 import { cleanupWriteCommand as cleanupCommand, installWriteCommand as installCommand, reinstallWriteCommand as reinstallCommand, uninstallWriteCommand as uninstallCommand, } 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, statusCommandV7 } from './commands/status-v6.js';
-import { normalizeUninstallCommandOptions, normalizeCleanupCommandOptions, resolveConfigReadResolution, resolveConfigWriteScope, normalizeInstallCommandOptions, normalizeReinstallCommandOptions, } from './commands/options.js';
+import { normalizeUninstallCommandOptions, normalizeCleanupCommandOptions, resolveConfigReadResolution, resolveConfigWriteScope, normalizeInstallCommandOptions, normalizeReinstallCommandOptions, resolveScriptTimeoutMs, } from './commands/options.js';
 import { isCommandWarningError, } from './types.js';
 import { formatWarnings } from './output/reporter.js';
 import { redactString, redactValue } from './output/redact.js';
 import { renderShellCommand, } from './output/equivalent-command.js';
 import { buildRebuildReceiptJson, buildInitReceiptJson, renderRebuildReceipt, renderInitReceipt, } from './output/command-receipt.js';
 import { resolveCliPackageRoot } from './utils/paths.js';
-import { findConfigFieldEntry, listNamespacedPluginConfigStores, listPluginConfigStorePluginNames, readPluginConfigStore, renderPluginConfigValueForDisplay, resolveConfigRead, } from './utils/plugin-config.js';
-import { applyPluginConfigWrite, buildConfigMutationReceipt, describeResetAffectedFields, resetPluginConfigWithHelper, } from './utils/plugin-config-write.js';
+import { findConfigFieldEntry, formatPluginConfigSetRecoveryCommand, listNamespacedPluginConfigStores, listPluginConfigStorePluginNames, readPluginConfigStore, renderPluginConfigValueForDisplay, resolveConfigRead, } from './utils/plugin-config.js';
+import { applyPluginConfigWrite, buildConfigMutationReceipt, configWriteStateForError, describeResetAffectedFields, resetPluginConfigWithHelper, } from './utils/plugin-config-write.js';
 import { assertStrictSemVer } from './utils/manifest.js';
 import { writeCandidateEligibility } from './utils/target-eligibility.js';
 import { assertCatalogSourceReferencesSupported, inventoryLegacyConfigReferences, } from './utils/catalog-source-references.js';
@@ -269,10 +269,12 @@ function jsonConfigMutationRequest(argv) {
     };
 }
 function configMutationFailure(error, env, cwd) {
+    const configWrite = configWriteStateForError(error);
     if (error instanceof CommanderError) {
         return {
             code: 'invalidArguments',
             message: 'error: invalid config mutation arguments',
+            configWrite,
         };
     }
     const message = catalogPublicationFailure({
@@ -281,29 +283,29 @@ function configMutationFailure(error, env, cwd) {
         sensitiveRoots: [cwd],
     }).message;
     if (message.includes('Usage:'))
-        return { code: 'invalidArguments', message };
+        return { code: 'invalidArguments', message, configWrite };
     const generationCode = catalogGenerationErrorCode(error);
     if (generationCode === 'catalogGenerationUnavailable'
         || generationCode === 'catalogGenerationSourceMissing') {
-        return { code: 'catalogSourceUnavailable', message };
+        return { code: 'catalogSourceUnavailable', message, configWrite };
     }
     if (generationCode !== 'catalogGenerationFailed')
-        return { code: generationCode, message };
+        return { code: generationCode, message, configWrite };
     const explicitCode = error?.code;
     if (typeof explicitCode === 'string' && /^[A-Za-z][A-Za-z0-9]*$/u.test(explicitCode)) {
-        return { code: explicitCode, message };
+        return { code: explicitCode, message, configWrite };
     }
     if (message.includes('legacyStateUnsupported'))
-        return { code: 'legacyStateUnsupported', message };
+        return { code: 'legacyStateUnsupported', message, configWrite };
     if (message.includes('sourceChanged'))
-        return { code: 'sourceChanged', message };
+        return { code: 'sourceChanged', message, configWrite };
     if (message.includes('sourceMissing'))
-        return { code: 'sourceMissing', message };
+        return { code: 'sourceMissing', message, configWrite };
     if (message.startsWith('Cannot resolve required catalog sources:')) {
-        return { code: 'catalogSourceUnavailable', message };
+        return { code: 'catalogSourceUnavailable', message, configWrite };
     }
     const prefix = message.match(/^([A-Za-z][A-Za-z0-9]*):/u)?.[1];
-    return { code: prefix ?? 'configMutationFailed', message };
+    return { code: prefix ?? 'configMutationFailed', message, configWrite };
 }
 function writeConfigMutationFailureReceipt(write, request, failure) {
     let plugin;
@@ -319,6 +321,7 @@ function writeConfigMutationFailureReceipt(write, request, failure) {
     writeJsonReceipt(write, buildConfigMutationReceipt(request.command, {
         ok: false,
         overallState: 'failed',
+        configWrite: failure.configWrite,
         ...(plugin ? { plugin } : {}),
         errors: [failure],
     }));
@@ -374,7 +377,7 @@ function configCommandUsage(command) {
     const argumentsByCommand = {
         list: '<plugin>',
         get: '<plugin> [key]',
-        set: '<plugin> <field> --scope <project|user> (--value-json <json> | --preset <id>)',
+        set: '<plugin> <field> --scope <project|user> (--value-json <json> | --value-stdin | --preset <id>)',
         unset: '<plugin> <key>',
         reset: '<plugin> --scope <project|user> --yes',
     };
@@ -384,6 +387,13 @@ function configCommandUsage(command) {
         `Example: aw config ${command} example-plugin${command === 'set' ? ' mode --scope user --value-json \'"safe"\'' : command === 'unset' ? ' key' : command === 'reset' ? ' --scope user --yes' : ''}`,
     ].join('\n');
 }
+async function readUtf8Stdin(stdin) {
+    const chunks = [];
+    for await (const chunk of stdin) {
+        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
 function equivalentWriteCommand(command, selection, rawOptions) {
     return shellCommand(buildEquivalentWriteCommandTokens(command, selection, rawOptions));
 }
@@ -401,7 +411,9 @@ export function buildEquivalentWriteCommandTokens(command, selection, rawOptions
         ...(command === 'install'
             ? (rawOptions.dependencyScope ?? []).flatMap((value) => ['--dependency-scope', value])
             : []),
-        ...(command === 'cleanup' ? [] : optionTokens('--script-timeout', rawOptions.scriptTimeout)),
+        ...((command === 'install' || command === 'reinstall')
+            ? optionTokens('--script-timeout', rawOptions.scriptTimeout)
+            : []),
         ...(selection.plugins.length > 0 ? ['--', ...selection.plugins] : []),
     ];
 }
@@ -478,12 +490,11 @@ async function loadStoredConfigWizardCandidates(context, locations, options = {}
                 continue;
             const existing = storesByPlugin.get(store.pluginId) ?? {
                 sourceId: store.sourceId,
-                sourceIdentity: store.sourceIdentity,
+                ...(store.binding.kind === 'source'
+                    ? { sourceIdentity: store.binding.sourceIdentity }
+                    : {}),
                 keys: new Set(),
             };
-            if (existing.sourceIdentity !== store.sourceIdentity) {
-                throw new Error(`sourceChanged: ${store.pluginId} config stores have different source identities.`);
-            }
             for (const key of keys)
                 existing.keys.add(key);
             storesByPlugin.set(store.pluginId, existing);
@@ -495,7 +506,7 @@ async function loadStoredConfigWizardCandidates(context, locations, options = {}
         pluginName: pluginId,
         pluginId,
         sourceId: store.sourceId,
-        sourceIdentity: store.sourceIdentity,
+        ...(store.sourceIdentity ? { sourceIdentity: store.sourceIdentity } : {}),
         targets: [],
         configKeys: [...store.keys].sort((left, right) => left.localeCompare(right)),
     }));
@@ -538,7 +549,9 @@ async function resolveStoredConfigResetIdentity(options) {
         pluginName: match.pluginName,
         pluginId: match.pluginId,
         sourceId: match.sourceId,
-        sourceIdentity: match.sourceIdentity,
+        ...(match.binding.kind === 'source'
+            ? { sourceIdentity: match.binding.sourceIdentity }
+            : { logicalIdentity: match.binding.logicalIdentity }),
     };
 }
 async function resolveStoredOnlyConfigIdentity(options) {
@@ -552,12 +565,14 @@ async function resolveStoredOnlyConfigIdentity(options) {
     })))).flat().filter((store) => store.pluginId === options.selector);
     if (stores.length === 0)
         throw new Error(`Plugin "${options.selector}" does not have a namespaced config store.`);
-    const identities = new Set(stores.map((store) => store.sourceIdentity));
-    if (identities.size !== 1) {
-        throw new Error(`sourceChanged: ${options.selector} config stores have different source identities.`);
+    const sourceBindings = stores.flatMap((store) => store.binding.kind === 'source'
+        ? [store.binding.sourceIdentity] : []);
+    const catalogBindings = stores.flatMap((store) => store.binding.kind === 'catalog'
+        ? [store.binding.logicalIdentity] : []);
+    if (new Set(sourceBindings).size > 1 || new Set(catalogBindings).size > 1) {
+        throw new Error(`identityMismatch: ${options.selector} config stores have different bindings.`);
     }
-    const sourceIdentity = [...identities][0];
-    await withResolvedMultiSourceCatalog({
+    const currentSource = await withResolvedMultiSourceCatalog({
         cliVersion: resolveCliVersion(),
         sourceIds: [parsed.sourceId],
         env: options.context.env,
@@ -566,16 +581,24 @@ async function resolveStoredOnlyConfigIdentity(options) {
             if (!source?.resolution) {
                 throw source?.error ?? new Error(`Catalog source "${parsed.sourceId}" is unavailable.`);
             }
-            if (source.resolution.sourceIdentity !== sourceIdentity) {
-                throw new Error(`sourceChanged: ${options.selector} config source identity does not match the current source.`);
-            }
+            return {
+                sourceIdentity: source.resolution.sourceIdentity,
+                logicalIdentity: source.resolution.logicalIdentity,
+            };
         },
     });
+    if (sourceBindings[0] && sourceBindings[0] !== currentSource.sourceIdentity) {
+        throw new Error(`identityMismatch: ${options.selector} user config does not match the current source identity.`);
+    }
+    if (catalogBindings[0] && catalogBindings[0] !== currentSource.logicalIdentity) {
+        throw new Error(`identityMismatch: ${options.selector} project config does not match the current Catalog logical identity.`);
+    }
     return {
         pluginName: parsed.pluginName,
         pluginId: options.selector,
         sourceId: parsed.sourceId,
-        sourceIdentity,
+        sourceIdentity: currentSource.sourceIdentity,
+        logicalIdentity: currentSource.logicalIdentity,
     };
 }
 async function resolveMultiSourceConfigRead(options) {
@@ -624,6 +647,7 @@ async function resolveMultiSourceConfigRead(options) {
         const result = await resolveConfigRead({
             sourceId: stored.sourceId,
             sourceIdentity: stored.sourceIdentity,
+            logicalIdentity: stored.logicalIdentity,
             pluginName: stored.pluginName,
             plugin: null,
             scope: resolveConfigReadResolution(options.rawOptions.scope),
@@ -670,6 +694,7 @@ async function executeWriteCommand(command, pluginNames, rawOptions, context, di
     const runtime = {
         ...context,
         directCli,
+        preApplyConfirmed: rawOptions.yes === true,
         ...(managedCodexAuthorizer ? { managedCodexAuthorizer } : {}),
     };
     switch (command) {
@@ -860,26 +885,70 @@ function configLayerLabel(scope) {
     return '当前项目';
 }
 function writeConfigApplyNotice(write, receipt) {
-    if (receipt.targetResults.length === 0) {
-        const message = receipt.applySkippedReason === 'noConfigChange'
+    const sanitizeMessage = (message) => redactString(message)
+        .replace(/https?:\/\/\S+/giu, '[REDACTED URL]')
+        .replace(/(?:file:\/\/)?(?:\/[\w.@+-]+){2,}/gu, '[REDACTED PATH]')
+        .replace(/[A-Za-z]:\\(?:[^\s\\]+\\)+[^\s\\]*/gu, '[REDACTED PATH]');
+    const writeTargetFailures = () => {
+        for (const entry of receipt.apply.targetResults.filter((target) => target.state === 'failed' || target.state === 'skipped')) {
+            const reason = entry.message
+                ? `${entry.errorCode ? `[${entry.errorCode}] ` : ''}${sanitizeMessage(entry.message)}`
+                : entry.errorCode
+                    ? `失败原因：${entry.errorCode}。`
+                    : '未提供安全失败原因。';
+            const command = `aw reinstall ${receipt.plugin} -p ${entry.target.platform} -s ${entry.target.scope}`;
+            const recovery = entry.errorCode === 'invalidConfig'
+                ? ' 请修复无效配置后运行 aw sync。'
+                : entry.errorCode === 'preApplyAuthorizationRequired'
+                    || entry.errorCode === 'sharedNativeConfigApplyConfirmationRequired'
+                    || entry.errorCode === 'sharedNativeImpactAuthorizationRequired'
+                    ? ` 请运行 ${command} --yes 重试。`
+                    : entry.state === 'failed'
+                        ? ` 请在解决失败原因后运行 ${command}。`
+                        : '';
+            writeLine(write, `${entry.target.platform}/${entry.target.scope}：${reason}${recovery}`);
+        }
+    };
+    const targetResults = receipt.apply.targetResults;
+    if (receipt.apply.state === 'skipped') {
+        const message = receipt.apply.reason === 'noConfigChange'
             ? '配置内容没有变化，因此没有运行 reinstall。'
-            : receipt.applySkippedReason === 'invalidConfig'
-                ? '配置已保存，但当前配置无效，因此没有运行 reinstall。请先修复无效字段。'
-                : '配置已保存。当前没有可见的 AW 安装目标，因此没有应用配置。';
+            : receipt.apply.reason === 'noEffectiveConfigChange'
+                ? '配置存储已更新，但有效配置没有变化，因此没有运行 reinstall。'
+                : receipt.apply.reason === 'notRequested'
+                    ? '配置已保存，但未请求应用配置。'
+                    : '配置已保存。当前没有可见的 AW 安装目标，因此没有应用配置。';
         writeLine(write, message);
     }
-    else {
-        const completed = receipt.targetResults.filter((entry) => entry.state === 'completed').length;
-        const failed = receipt.targetResults.filter((entry) => entry.state === 'failed');
-        writeLine(write, `配置已保存。已重装 ${completed} 个当前可见目标；失败 ${failed.length} 个。`);
-        for (const entry of failed) {
-            writeLine(write, `${entry.target.platform}/${entry.target.scope}：${entry.message ?? 'reinstall 失败。'} `
-                + `请重试 aw reinstall ${receipt.plugin} -p ${entry.target.platform} -s ${entry.target.scope}。`);
-        }
+    else if (receipt.apply.state === 'unavailable') {
+        const fallbackMessages = {
+            invalidConfig: '可见目标的有效配置无效。',
+            schemaUnavailable: '配置 schema 不可用。',
+            sourceUnavailable: '插件来源不可用。',
+            effectiveConfigUnavailable: '无法读取有效配置。',
+            targetDiscoveryFailed: '无法发现可应用配置的目标。',
+        };
+        const detail = receipt.apply.error
+            ? `${receipt.apply.error.code}：${sanitizeMessage(receipt.apply.error.message)}`
+            : `${receipt.apply.reason}：${fallbackMessages[receipt.apply.reason]}`;
+        const recovery = receipt.apply.reason === 'invalidConfig'
+            ? '请修复无效配置后运行 aw sync。'
+            : receipt.apply.reason === 'effectiveConfigUnavailable'
+                ? '请修复配置后运行 aw sync。'
+                : receipt.apply.reason === 'schemaUnavailable' || receipt.apply.reason === 'sourceUnavailable'
+                    ? '请修复插件来源或配置后运行 aw sync。'
+                    : '请修复来源或配置后运行 aw sync。';
+        writeLine(write, `配置已保存，但当前无法应用配置。${detail} ${recovery}`);
+        writeTargetFailures();
     }
-    if (receipt.otherProjectsRequireReinstall) {
-        writeLine(write, '其它项目没有被扫描。请进入每个项目目录并运行对应的 aw reinstall 命令。');
+    else {
+        const completed = targetResults.filter((entry) => entry.state === 'completed').length;
+        const failed = targetResults.filter((entry) => entry.state === 'failed').length;
+        const skipped = targetResults.filter((entry) => entry.state === 'skipped').length;
+        writeLine(write, `配置已保存。已重装 ${completed} 个当前可见目标；失败 ${failed} 个；跳过 ${skipped} 个。`);
+        writeTargetFailures();
     }
+    writeWarnings(write, receipt.warnings);
 }
 function renderConfigFieldState(field) {
     if (field.valueState === 'invalid') {
@@ -899,11 +968,15 @@ function writeConfigReadHuman(write, resolved, pluginName) {
         }
         if (field.kind === 'manifest' && field.valueState === 'invalid') {
             const sourceScope = field.sourceLayer === 'project'
-                ? ' -s project'
-                : ' -s user';
-            writeLine(write, `  aw config set ${pluginName} ${field.key}${sourceScope} --value-json '<json>'`);
-            writeLine(write, `  aw config unset ${pluginName} ${field.key}${sourceScope}`);
-            writeLine(write, `  aw config reset ${pluginName}${sourceScope}`);
+                ? 'project'
+                : 'user';
+            const definition = resolved.fieldDefinitions?.[field.key];
+            if (definition) {
+                writeLine(write, `  ${formatPluginConfigSetRecoveryCommand(pluginName, field.key, definition, sourceScope)}`);
+            }
+            const scopeOption = ` -s ${sourceScope}`;
+            writeLine(write, `  aw config unset ${pluginName} ${field.key}${scopeOption}`);
+            writeLine(write, `  aw config reset ${pluginName}${scopeOption}`);
         }
     }
 }
@@ -963,7 +1036,7 @@ export function buildProgram(options = {}) {
     plugin
         .command('capabilities')
         .description('Show the current plugin manifest authoring surface')
-        .option('--surface <surface>', 'manifest | build-config | extensions | slash-commands | mcp-apps | config | post-apply | artifacts')
+        .option('--surface <surface>', 'manifest | build-config | extensions | slash-commands | mcp-apps | config | pre-apply | artifacts')
         .option('--json', 'emit one machine-readable JSON object', false)
         .action((rawOptions) => {
         try {
@@ -1447,7 +1520,7 @@ export function buildProgram(options = {}) {
         .option('--with-mcp', 'add a minimal .mcp.json', false)
         .option('--with-apps', 'add a minimal .app.json', false)
         .option('--with-config-api', 'add AW config schema and helper', false)
-        .option('--with-post-apply', 'add a Node postApply script sample', false);
+        .option('--with-pre-apply', 'add an idempotent Node preApply environment check', false);
     plugin
         .command('add-skill')
         .description('Add one static Skill scaffold to an existing plugin')
@@ -1833,7 +1906,7 @@ export function buildProgram(options = {}) {
     catalogDev
         .command('status')
         .option('--workspace-root <path>', 'explicit Catalog Workspace root')
-        .requiredOption('--json', 'emit one schema 3 JSON receipt')
+        .requiredOption('--json', 'emit one schema 4 JSON receipt')
         .action(async (rawOptions) => {
         const receipt = await getCatalogDevSourceStatus({
             cwd,
@@ -1849,8 +1922,8 @@ export function buildProgram(options = {}) {
         .option('--workspace-root <path>', 'explicit Catalog Workspace root')
         .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')
+        .option('-y, --yes', 'confirm source impact or recovery by source ID', false)
+        .requiredOption('--json', 'emit one schema 4 JSON receipt')
         .action(async (rawOptions) => {
         try {
             const receipt = await deactivateCatalogDevSource({
@@ -1881,11 +1954,12 @@ export function buildProgram(options = {}) {
         const message = failure instanceof Error ? failure.message : String(error);
         if (json) {
             writeJsonReceipt(io.stdout, {
-                receiptSchemaVersion: 5,
+                receiptSchemaVersion: 6,
                 command,
                 ok: false,
                 changed: false,
                 sourceId,
+                primaryChange: failure.impact?.primaryChange ?? null,
                 references: failure.impact?.references ?? failure.inventory?.references ?? [],
                 errors: [{ code: failure.code ?? failure.name ?? 'catalogSourceMutationFailed', message }],
             });
@@ -1900,7 +1974,7 @@ export function buildProgram(options = {}) {
             writeJsonReceipt(io.stdout, {
                 ...(command === 'catalog:source:sync'
                     ? { catalogGenerationSchemaVersion: 1 }
-                    : { catalogGenerationStatusSchemaVersion: 1 }),
+                    : { catalogGenerationStatusSchemaVersion: 2 }),
                 command,
                 ok: false,
                 ...(sourceId ? { sourceId } : {}),
@@ -1999,7 +2073,7 @@ export function buildProgram(options = {}) {
     catalogSource
         .command('status')
         .argument('[id]')
-        .option('-j, --json', 'print offline Catalog source status as JSON', false)
+        .option('-j, --json', 'print offline Catalog source status schema 2 as JSON', false)
         .action(async (id, rawOptions) => {
         try {
             const result = await catalogSourceStatusCommand({ sourceId: id, env });
@@ -2011,7 +2085,9 @@ export function buildProgram(options = {}) {
                     const active = source.active
                         ? `Active ${source.active.snapshotDigest}`
                         : 'no Active';
-                    const readiness = source.activeReady ? 'ready' : 'not ready';
+                    const readiness = source.compatibility?.state === 'unsupported'
+                        ? `incompatible (required: ${source.compatibility.requiredCapabilities.join(', ')}; missing: ${source.compatibility.missingCapabilities.join(', ')})`
+                        : source.activeReady ? 'ready' : 'not ready';
                     writeLine(io.stdout, `${source.sourceId}: ${active}, ${readiness}`);
                 }
             }
@@ -2030,6 +2106,7 @@ export function buildProgram(options = {}) {
         .option('--subdir <path>', 'use a catalog snapshot below the Git repository root')
         .option('--no-auto-check', 'disable automatic update checks for this source')
         .option('--primary', 'make this source primary', false)
+        .option('-y, --yes', 'confirm affected or unknown primary source references', false)
         .option('-j, --json', 'print mutation receipt as JSON', false)
         .action(async (id, rawOptions) => {
         try {
@@ -2040,7 +2117,7 @@ export function buildProgram(options = {}) {
                 throw new Error('Git catalog source add requires exactly one of `--ref` or `--default-ref`.');
             }
             if (rawOptions.path !== undefined && (rawOptions.ref !== undefined || rawOptions.defaultRef === true || rawOptions.subdir !== undefined)) {
-                throw new Error('Path catalog source add only accepts `--path`, `--primary`, and `--no-auto-check`.');
+                throw new Error('Path catalog source add only accepts `--path`, `--primary`, `--no-auto-check`, and `--yes`.');
             }
             const source = rawOptions.git !== undefined
                 ? {
@@ -2059,11 +2136,23 @@ export function buildProgram(options = {}) {
                     path: rawOptions.path,
                     ...(rawOptions.autoCheck === false ? { autoCheck: false } : {}),
                 };
+            const preview = source.primary
+                ? await preflightCatalogSourceMutation({
+                    request: { action: 'add', source }, cwd, env,
+                })
+                : undefined;
             const receipt = await addCatalogSourceCommand({
                 source,
                 cliVersion: resolveCliVersion(),
                 cwd,
                 env,
+                ...(preview ? {
+                    expectedConfigDigest: preview.configDigest,
+                    expectedProposedConfigDigest: preview.proposedConfigDigest,
+                    expectedImpactDigest: preview.impactDigest,
+                } : {}),
+                requireImpactConfirmation: true,
+                confirmImpact: rawOptions.yes === true,
             });
             if (rawOptions.json)
                 writeJsonReceipt(io.stdout, receipt);
@@ -2129,12 +2218,18 @@ export function buildProgram(options = {}) {
                         : {}),
                 }
                     : { autoCheck: rawOptions.autoCheck };
+            const preview = await preflightCatalogSourceMutation({
+                request: { action: 'update', sourceId: id, update }, cwd, env,
+            });
             const receipt = await updateCatalogSourceCommand({
                 sourceId: id,
                 update,
                 cliVersion: resolveCliVersion(),
                 cwd,
                 env,
+                expectedConfigDigest: preview.configDigest,
+                expectedProposedConfigDigest: preview.proposedConfigDigest,
+                expectedImpactDigest: preview.impactDigest,
                 requireIdentityChangeConfirmation: true,
                 confirmIdentityChange: rawOptions.yes === true,
             });
@@ -2152,10 +2247,17 @@ export function buildProgram(options = {}) {
     catalogSource
         .command('set-primary')
         .argument('<id>')
+        .option('-y, --yes', 'confirm affected or unknown primary source references', false)
         .option('-j, --json', 'print mutation receipt as JSON', false)
         .action(async (id, rawOptions) => {
         try {
-            const receipt = await setPrimaryCatalogSourceCommand({ sourceId: id, cwd, env });
+            const receipt = await setPrimaryCatalogSourceCommand({
+                sourceId: id,
+                cwd,
+                env,
+                requireImpactConfirmation: true,
+                confirmImpact: rawOptions.yes === true,
+            });
             if (rawOptions.json)
                 writeJsonReceipt(io.stdout, receipt);
             else
@@ -2209,18 +2311,22 @@ export function buildProgram(options = {}) {
                     writeLine(io.stdout, `${entry.storeKey}: ${entry.category}, ${entry.status}, ${entry.reason}, ${bytes}`);
                 }
                 writeLine(io.stdout, `Reclaimable: ${result.totals.reclaimableEntries} item(s).`);
+                if (result.errors.length > 0) {
+                    writeLine(io.stderr, `${result.errors.length} item(s) could not be fully inspected and were retained.`);
+                }
             }
+            commandExitState.exitCode = result.ok ? 0 : 1;
         }
         catch (error) {
             const failure = sanitizeCatalogSourceError(error, env);
             const message = redactString(failure.message);
             if (rawOptions.json)
                 writeJsonReceipt(io.stdout, {
-                    catalogStoreSchemaVersion: 1,
+                    catalogStoreSchemaVersion: 2,
                     command: 'catalog:store:status',
                     ok: false,
                     entries: [],
-                    errors: [{ code: catalogGenerationErrorCode(error), message }],
+                    errors: [{ code: catalogStoreErrorCode(error), message }],
                 });
             writeLine(io.stderr, message);
             commandExitState.exitCode = 1;
@@ -2246,24 +2352,23 @@ export function buildProgram(options = {}) {
             else if (dryRun) {
                 writeLine(io.stdout, `Dry run: ${result.entries.filter((entry) => entry.status === 'reclaimable').length} item(s) are reclaimable.`);
                 writeLine(io.stdout, 'Run `aw catalog store prune --yes` to delete them.');
+                if (result.errors.length > 0)
+                    writeLine(io.stderr, `${result.errors.length} item(s) could not be fully inspected and were retained.`);
             }
             else {
                 writeLine(io.stdout, `Deleted ${result.deleted.length} Catalog store item(s) (${result.deletedBytes} bytes).`);
                 if (result.errors.length > 0)
-                    writeLine(io.stderr, `${result.errors.length} item(s) could not be deleted and were retained.`);
+                    writeLine(io.stderr, `${result.errors.length} item(s) could not be fully inspected or deleted and were retained.`);
             }
             commandExitState.exitCode = result.ok ? 0 : 1;
         }
         catch (error) {
             const failure = sanitizeCatalogSourceError(error, env);
             const message = redactString(failure.message);
-            const explicitCode = error.code;
-            const code = typeof explicitCode === 'string'
-                ? explicitCode
-                : catalogGenerationErrorCode(error);
+            const code = catalogStoreErrorCode(error);
             if (rawOptions.json)
                 writeJsonReceipt(io.stdout, {
-                    catalogStoreSchemaVersion: 1,
+                    catalogStoreSchemaVersion: 2,
                     command: 'catalog:store:prune',
                     ok: false,
                     overallState: 'failed',
@@ -2312,7 +2417,8 @@ export function buildProgram(options = {}) {
         .requiredOption('-p, --platform <platform>', 'codex, claude, or both')
         .option('-a, --all', 'reconcile every desired plugin in the selected scope', false)
         .option('--refresh', 'refresh only Catalog sources required by selected intent roots', false)
-        .option('-y, --yes', 'authorize shared native replacement or forced repair', false)
+        .option('--script-timeout <ms>', 'override plugin preApply script timeout in milliseconds')
+        .option('-y, --yes', 'authorize preApply and 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)
@@ -2324,6 +2430,7 @@ export function buildProgram(options = {}) {
             cwd: context.cwd,
             scope: rawOptions.scope,
             platform: rawOptions.platform,
+            scriptTimeout: rawOptions.scriptTimeout,
             allowManagedCodexInstall: rawOptions.allowManagedCodexInstall,
         }));
         const syncPlatform = normalized.platform;
@@ -2340,6 +2447,7 @@ export function buildProgram(options = {}) {
             interactive: context.interactive && context.isTty && !context.isCi,
             prompt: context.prompt,
             allowManagedCodexInstall: rawOptions.allowManagedCodexInstall,
+            scriptTimeoutMs: normalized.scriptTimeoutMs,
         }, context));
         if (rawOptions.json) {
             writeJsonReceipt(io.stdout, buildRebuildReceiptJson('sync', result));
@@ -2357,9 +2465,9 @@ export function buildProgram(options = {}) {
         .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 postApply script timeout in milliseconds')
+        .option('--script-timeout <ms>', 'override plugin preApply 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('-y, --yes', 'authorize preApply and 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)
@@ -2386,7 +2494,6 @@ export function buildProgram(options = {}) {
         .argument('[plugins...]')
         .option('-s, --scope <scope>', 'project or user')
         .option('-p, --platform <platform>', 'codex | claude | both')
-        .option('--script-timeout <ms>', 'override plugin postApply script timeout in milliseconds')
         .option('--allow-managed-codex-install', 'allow this command to acquire or rebuild the pinned AW-managed Codex runtime', false)
         .option('-j, --json', 'print receipt as JSON', false)
         .option('-v, --verbose', 'show command diagnostics', false)
@@ -2442,9 +2549,9 @@ export function buildProgram(options = {}) {
         .argument('[plugins...]')
         .option('-s, --scope <scope>', 'project or user')
         .option('-p, --platform <platform>', 'codex | claude | both')
-        .option('--script-timeout <ms>', 'override plugin postApply script timeout in milliseconds')
+        .option('--script-timeout <ms>', 'override plugin preApply 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('-y, --yes', 'authorize preApply and 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)
@@ -2612,9 +2719,11 @@ export function buildProgram(options = {}) {
         .argument('[field]')
         .option('-s, --scope <scope>', 'project or user')
         .option('--value-json <json>', 'set the field to an exact JSON value')
+        .option('--value-stdin', 'read the exact string value from stdin until EOF', false)
         .option('--preset <id>', 'set the field to the current manifest preset value')
         .option('--apply', 'apply the saved config to visible desired placements', false)
-        .option('-y, --yes', 'confirm shared Codex native config apply', false)
+        .option('--script-timeout <ms>', 'override plugin preApply script timeout in milliseconds')
+        .option('-y, --yes', 'confirm preApply and shared Codex native config apply', 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)
@@ -2627,8 +2736,16 @@ export function buildProgram(options = {}) {
         try {
             outcome = await runActionWithContext(context, async () => {
                 const scope = resolveConfigWriteScope(rawOptions.scope);
-                if ((rawOptions.valueJson === undefined) === (rawOptions.preset === undefined)) {
-                    throw new Error('Use exactly one of --value-json <json> or --preset <id>.');
+                const scriptTimeoutMs = resolveScriptTimeoutMs(rawOptions);
+                const explicitValueCount = [
+                    rawOptions.valueJson !== undefined,
+                    rawOptions.valueStdin === true,
+                    rawOptions.preset !== undefined,
+                ].filter(Boolean).length;
+                if (explicitValueCount > 1
+                    || (explicitValueCount === 0
+                        && !(context.interactive && context.isTty && !context.isCi && rawOptions.json !== true))) {
+                    throw new Error('Use exactly one of --value-json <json>, --value-stdin, or --preset <id>.');
                 }
                 return withResolvedConfigMutationPlugin(context, pluginName, async ({ pluginId, source, plugin }, awHomeMutationToken, catalogOperationContext) => {
                     if (!plugin.manifest.config?.fields) {
@@ -2638,8 +2755,43 @@ export function buildProgram(options = {}) {
                     if (!field) {
                         throw new Error(`Unknown config key "${key}".`);
                     }
+                    const sensitive = field.sensitive === true;
+                    if (sensitive && scope !== 'user') {
+                        const error = new Error('sensitiveProjectConfigUnsupported: Sensitive config can only be set in user scope.');
+                        error.code = 'sensitiveProjectConfigUnsupported';
+                        throw error;
+                    }
+                    if (sensitive && (rawOptions.valueJson !== undefined || rawOptions.preset !== undefined)) {
+                        const error = new Error('sensitiveConfigInputUnsupported: Sensitive config cannot use --value-json or --preset.');
+                        error.code = 'sensitiveConfigInputUnsupported';
+                        throw error;
+                    }
+                    if (!sensitive && explicitValueCount !== 1) {
+                        throw new Error('Use exactly one of --value-json <json>, --value-stdin, or --preset <id>.');
+                    }
                     let inputValue;
-                    if (rawOptions.valueJson !== undefined) {
+                    if (rawOptions.valueStdin === true) {
+                        inputValue = await readUtf8Stdin(context.stdin);
+                    }
+                    else if (sensitive) {
+                        if (!(context.interactive && context.isTty && !context.isCi && rawOptions.json !== true)
+                            || !context.prompt.password) {
+                            const error = new Error('sensitiveConfigStdinRequired: Use --value-stdin for sensitive config outside an interactive terminal.');
+                            error.code = 'sensitiveConfigStdinRequired';
+                            throw error;
+                        }
+                        const response = await context.prompt.password({
+                            message: `输入 ${field.title ?? key}`,
+                            mask: true,
+                        });
+                        if (response.cancelled || response.action !== 'select' || response.value === undefined) {
+                            const error = new Error('sensitiveConfigInputCancelled: Sensitive config input was cancelled.');
+                            error.code = 'sensitiveConfigInputCancelled';
+                            throw error;
+                        }
+                        inputValue = response.value;
+                    }
+                    else if (rawOptions.valueJson !== undefined) {
                         try {
                             inputValue = JSON.parse(rawOptions.valueJson);
                         }
@@ -2665,6 +2817,7 @@ export function buildProgram(options = {}) {
                             awHomeMutationToken,
                             catalogOperationContext,
                             expectedGenerationSetDigest: catalogOperationContext.generationSetDigest,
+                            ...(scriptTimeoutMs === undefined ? {} : { scriptTimeoutMs }),
                         },
                         awHomeMutationToken,
                         request: {
@@ -2672,6 +2825,7 @@ export function buildProgram(options = {}) {
                         },
                         apply: rawOptions.apply === true,
                         sharedNativeApplyConfirmed: rawOptions.yes === true,
+                        preApplyConfirmed: rawOptions.yes === true,
                     });
                     return buildConfigMutationReceipt('config:set', {
                         ok: writeReceipt.overallState === 'succeeded',
@@ -2713,7 +2867,8 @@ export function buildProgram(options = {}) {
         .argument('[key]')
         .option('-s, --scope <scope>', 'project or user')
         .option('--apply', 'apply the saved config to visible desired placements', false)
-        .option('-y, --yes', 'confirm shared Codex native config apply', false)
+        .option('--script-timeout <ms>', 'override plugin preApply script timeout in milliseconds')
+        .option('-y, --yes', 'confirm preApply and shared Codex native config apply', 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)
@@ -2724,13 +2879,12 @@ export function buildProgram(options = {}) {
         try {
             outcome = await runActionWithContext(context, async () => {
                 const scope = resolveConfigWriteScope(rawOptions.scope);
-                const execute = async (selectedPlugin, selectedKey) => withResolvedConfigMutationPlugin(context, selectedPlugin, async ({ pluginId, source, plugin }, awHomeMutationToken, catalogOperationContext) => {
-                    if (plugin.manifest.config?.fields && !plugin.manifest.config.fields[selectedKey]) {
-                        throw new Error(`Unknown config key "${selectedKey}".`);
-                    }
+                const scriptTimeoutMs = resolveScriptTimeoutMs(rawOptions);
+                const execute = async (selectedPlugin, selectedKey, confirmed) => withResolvedConfigMutationPlugin(context, selectedPlugin, async ({ pluginId, source, plugin }, awHomeMutationToken, catalogOperationContext) => {
                     const store = await readPluginConfigStore({
                         sourceId: source.sourceId,
                         sourceIdentity: source.sourceIdentity,
+                        logicalIdentity: source.logicalIdentity,
                         pluginName: plugin.manifest.name,
                         scope,
                         cwd: context.cwd,
@@ -2752,13 +2906,15 @@ export function buildProgram(options = {}) {
                             awHomeMutationToken,
                             catalogOperationContext,
                             expectedGenerationSetDigest: catalogOperationContext.generationSetDigest,
+                            ...(scriptTimeoutMs === undefined ? {} : { scriptTimeoutMs }),
                         },
                         awHomeMutationToken,
                         request: {
                             removeKeys: [selectedKey],
                         },
                         apply: rawOptions.apply === true,
-                        sharedNativeApplyConfirmed: rawOptions.yes === true,
+                        sharedNativeApplyConfirmed: confirmed,
+                        preApplyConfirmed: rawOptions.yes === true,
                     });
                     return buildConfigMutationReceipt('config:unset', {
                         ok: writeReceipt.overallState === 'succeeded',
@@ -2777,11 +2933,15 @@ export function buildProgram(options = {}) {
                                 reserved: false,
                                 action: 'unset',
                                 scope,
+                                ...(!plugin.manifest.config?.fields?.[selectedKey] ? { stale: true } : {}),
                             }],
                     });
                 });
                 if (pluginName && key) {
-                    return { cancelled: false, value: await execute(pluginName, key) };
+                    return {
+                        cancelled: false,
+                        value: await execute(pluginName, key, rawOptions.yes === true),
+                    };
                 }
                 if (!isWizardAvailable(context, rawOptions))
                     throw new Error(configCommandUsage('unset'));
@@ -2808,7 +2968,7 @@ export function buildProgram(options = {}) {
                         scope: selection.scope ?? 'user',
                     })),
                     resultState: overallResultState,
-                    execute: (selection) => execute(selection.plugins[0], selection.key),
+                    execute: (selection) => execute(selection.plugins[0], selection.key, true),
                 });
                 return result.cancelled
                     ? { cancelled: true }
@@ -2838,7 +2998,8 @@ export function buildProgram(options = {}) {
         .argument('[plugin]')
         .option('-s, --scope <scope>', 'project or user')
         .option('--apply', 'apply the saved config to visible desired placements', false)
-        .option('-y, --yes', 'confirm destructive reset', false)
+        .option('--script-timeout <ms>', 'override plugin preApply script timeout in milliseconds')
+        .option('-y, --yes', 'confirm destructive reset and preApply/shared Codex native config apply', 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)
@@ -2849,6 +3010,7 @@ export function buildProgram(options = {}) {
         try {
             outcome = await runActionWithContext(context, async () => {
                 const execute = async (selectedPlugin, selectedScope, confirmed) => {
+                    const scriptTimeoutMs = resolveScriptTimeoutMs(rawOptions);
                     if (!confirmed) {
                         throw new Error(`Reset requires confirmation. Re-run \`aw config reset ${selectedPlugin} -s ${selectedScope} --yes\` to delete this store.`);
                     }
@@ -2861,6 +3023,7 @@ export function buildProgram(options = {}) {
                         const affectedFields = await describeResetAffectedFields({
                             sourceId: located.sourceId,
                             sourceIdentity: located.sourceIdentity,
+                            logicalIdentity: located.logicalIdentity,
                             pluginName: located.pluginName,
                             plugin,
                             pluginError,
@@ -2871,6 +3034,7 @@ export function buildProgram(options = {}) {
                         const resetReceipt = await resetPluginConfigWithHelper({
                             sourceId: located.sourceId,
                             sourceIdentity: located.sourceIdentity,
+                            logicalIdentity: located.logicalIdentity,
                             pluginName: located.pluginName,
                             scope: selectedScope,
                             cwd: context.cwd,
@@ -2879,6 +3043,9 @@ export function buildProgram(options = {}) {
                             plugin,
                             pluginError,
                             apply: rawOptions.apply === true,
+                            rebuildRuntime: scriptTimeoutMs === undefined ? undefined : { scriptTimeoutMs },
+                            sharedNativeApplyConfirmed: confirmed,
+                            preApplyConfirmed: rawOptions.yes === true,
                         });
                         return buildConfigMutationReceipt('config:reset', {
                             ok: resetReceipt.overallState === 'succeeded',
@@ -3115,11 +3282,12 @@ 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: 5,
+                    receiptSchemaVersion: 6,
                     command: 'catalog:source:update',
                     ok: false,
                     changed: false,
                     sourceId: argv[3] ?? '',
+                    primaryChange: null,
                     references: [],
                     errors: [{ code: 'catalogSourceOptionConflict', message }],
                 });
@@ -3132,11 +3300,12 @@ export async function runCli(argv, options = {}) {
             const message = 'option --auto-check cannot be used with option --no-auto-check';
             if (argv.includes('--json') || argv.includes('-j')) {
                 writeJsonReceipt(io.stdout, {
-                    receiptSchemaVersion: 5,
+                    receiptSchemaVersion: 6,
                     command: 'catalog:source:update',
                     ok: false,
                     changed: false,
                     sourceId: argv[3] ?? '',
+                    primaryChange: null,
                     references: [],
                     errors: [{ code: 'catalogSourceOptionConflict', message }],
                 });