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

package/dist/src/utils/plugin-config.js

@@ -6,6 +6,7 @@ import { canonicalizePluginConfigValues, formatPluginConfigIssue, matchPluginCon
 import { assertTestReadablePath, assertTestWritablePath, } from './test-path-fence.js';
 import { canonicalizePathThroughExistingAncestor, resolveAwHome, resolveRepoRootSync, } from './paths.js';
 import { assertRealFileParentWithinRoot, assertSafeFileMutationPath, atomicReplaceSafeFile, } from './safe-fs.js';
+import { assertProjectSharedConfigPathVisible, PROJECT_CONFIG_SHAREABILITY_UNVERIFIED_WARNING, } from './project-boundary.js';
 export function codexNativeRefreshKeys(manifest) {
     return new Set((manifest.artifacts?.targets ?? []).flatMap((target) => target.platform === 'codex'
         && target.target === 'codex.skill'
@@ -13,6 +14,51 @@ export function codexNativeRefreshKeys(manifest) {
         ? target.refreshKeys
         : []));
 }
+function readPluginConfigBinding(value, scope) {
+    if (!isRecord(value))
+        return null;
+    if (scope === 'user') {
+        return value.kind === 'source'
+            && typeof value.sourceIdentity === 'string'
+            && /^sha256:[0-9a-f]{64}$/u.test(value.sourceIdentity)
+            && Object.keys(value).every((key) => ['kind', 'sourceIdentity'].includes(key))
+            ? { kind: 'source', sourceIdentity: value.sourceIdentity }
+            : null;
+    }
+    return value.kind === 'catalog'
+        && typeof value.logicalIdentity === 'string'
+        && value.logicalIdentity.trim().length > 0
+        && Object.keys(value).every((key) => ['kind', 'logicalIdentity'].includes(key))
+        ? { kind: 'catalog', logicalIdentity: value.logicalIdentity }
+        : null;
+}
+const PLUGIN_CONFIG_ENVELOPE_V4_KEYS = new Set([
+    'schemaVersion',
+    'sourceId',
+    'pluginName',
+    'binding',
+    'values',
+]);
+function readPluginConfigEnvelopeV4(value, scope) {
+    if (!isRecord(value)
+        || value.schemaVersion !== 4
+        || typeof value.sourceId !== 'string'
+        || typeof value.pluginName !== 'string'
+        || !isRecord(value.values)
+        || Object.keys(value).some((key) => !PLUGIN_CONFIG_ENVELOPE_V4_KEYS.has(key))) {
+        return null;
+    }
+    const binding = readPluginConfigBinding(value.binding, scope);
+    if (!binding)
+        return null;
+    return {
+        schemaVersion: 4,
+        sourceId: value.sourceId,
+        pluginName: value.pluginName,
+        binding,
+        values: value.values,
+    };
+}
 export class PluginConfigResetError extends Error {
     code;
     osCode;
@@ -356,17 +402,33 @@ async function readNamespacedStoreFile(options) {
     if (parsed.state === 'invalidJson')
         return parsed.store;
     const raw = parsed.value;
-    if (!isRecord(raw) || raw.schemaVersion !== 3) {
-        return invalidStore(options.filePath, 'schemaVersionUnsupported', 'Only plugin config store schemaVersion 3 is supported.', parsed.rawDigest);
+    if (!isRecord(raw) || raw.schemaVersion !== 4) {
+        return invalidStore(options.filePath, 'schemaVersionUnsupported', 'Only plugin config store schemaVersion 4 is supported.', parsed.rawDigest);
+    }
+    const envelope = readPluginConfigEnvelopeV4(raw, options.scope);
+    if (!envelope) {
+        return invalidStore(options.filePath, 'schemaVersionUnsupported', 'The plugin config store schemaVersion 4 envelope is invalid.', parsed.rawDigest);
     }
-    if (raw.sourceId !== options.sourceId
-        || raw.pluginName !== options.pluginName
-        || raw.sourceIdentity !== options.sourceIdentity) {
+    if (envelope.sourceId !== options.sourceId
+        || envelope.pluginName !== options.pluginName) {
         return invalidStore(options.filePath, 'identityMismatch', 'The store identity does not match its source and namespaced path.', parsed.rawDigest);
     }
+    const binding = envelope.binding;
+    const matchesBinding = options.scope === 'user'
+        ? binding?.kind === 'source'
+            && typeof options.sourceIdentity === 'string'
+            && binding.sourceIdentity === options.sourceIdentity
+        : binding?.kind === 'catalog'
+            && typeof options.logicalIdentity === 'string'
+            && binding.logicalIdentity === options.logicalIdentity;
+    if (!matchesBinding) {
+        return invalidStore(options.filePath, 'identityMismatch', options.scope === 'user'
+            ? 'The user store is not bound to the requested source identity.'
+            : 'The project store is not bound to the requested Catalog logical identity.', parsed.rawDigest);
+    }
     return validateStoreValues({
         filePath: options.filePath,
-        values: raw.values,
+        values: envelope.values,
         rawDigest: parsed.rawDigest,
     });
 }
@@ -374,14 +436,18 @@ function namespacedConfigContent(options) {
     const values = canonicalizePluginConfigValues(options.values);
     if (!options.sourceId)
         return `${JSON.stringify(values, null, 2)}\n`;
-    if (!options.sourceIdentity) {
-        throw new Error('sourceChanged: namespaced plugin config requires a source identity.');
-    }
+    const binding = options.scope === 'user'
+        ? options.sourceIdentity
+            ? { kind: 'source', sourceIdentity: options.sourceIdentity }
+            : (() => { throw new Error('sourceChanged: user plugin config requires a source identity.'); })()
+        : options.logicalIdentity
+            ? { kind: 'catalog', logicalIdentity: options.logicalIdentity }
+            : (() => { throw new Error('catalogUnavailable: project plugin config requires verified Catalog logical identity evidence.'); })();
     const envelope = {
-        schemaVersion: 3,
+        schemaVersion: 4,
         sourceId: options.sourceId,
-        sourceIdentity: options.sourceIdentity,
         pluginName: options.pluginName,
+        binding,
         values,
     };
     return `${JSON.stringify(envelope, null, 2)}\n`;
@@ -431,7 +497,9 @@ export async function readPluginConfigStore(options) {
         ? readNamespacedStoreFile({
             filePath,
             sourceId: options.sourceId,
+            scope: options.scope,
             sourceIdentity: options.sourceIdentity,
+            logicalIdentity: options.logicalIdentity,
             pluginName: options.pluginName,
         })
         : readStoreFile(filePath);
@@ -447,16 +515,16 @@ export async function readNamespacedPluginConfigStoreIdentity(options) {
     if (parsed.state === 'invalidJson') {
         throw new Error(`${parsed.store.invalidCode}: invalid namespaced plugin config store.`);
     }
-    const raw = parsed.value;
-    if (!isRecord(raw) || raw.schemaVersion !== 3 || !isRecord(raw.values)
-        || raw.sourceId !== options.sourceId || raw.pluginName !== options.pluginName
-        || typeof raw.sourceIdentity !== 'string') {
+    const envelope = readPluginConfigEnvelopeV4(parsed.value, options.scope);
+    if (!envelope
+        || envelope.sourceId !== options.sourceId
+        || envelope.pluginName !== options.pluginName) {
         throw new Error('schemaVersionUnsupported: invalid namespaced plugin config store.');
     }
-    const store = validateStoreValues({ filePath, values: raw.values });
+    const store = validateStoreValues({ filePath, values: envelope.values });
     assertReadyPluginConfigStore(store);
     return {
-        sourceIdentity: raw.sourceIdentity,
+        binding: envelope.binding,
         store,
     };
 }
@@ -496,6 +564,64 @@ export async function listPluginConfigStorePluginNames(options) {
     const pluginNames = (await Promise.all(storeRoots.map((storeRoot) => listConfigStoreDirectoryPluginNames(storeRoot)))).flat();
     return [...new Set(pluginNames)].sort((left, right) => left.localeCompare(right));
 }
+export async function listNamespacedPluginConfigStoreIdentities(options) {
+    const boundaryRoot = options.scope === 'user'
+        ? resolveAwHome(options.env)
+        : resolveAwProjectRoot(options.cwd);
+    if (options.scope === 'user') {
+        await canonicalizePathThroughExistingAncestor(boundaryRoot);
+    }
+    else {
+        await fs.realpath(boundaryRoot);
+    }
+    const storeRoot = path.join(boundaryRoot, ...(options.scope === 'project' ? ['.agent-workflows'] : []), CONFIG_DIR);
+    if (!await inspectConfigInventoryStoreRoot(boundaryRoot, storeRoot))
+        return [];
+    const output = [];
+    for (const sourceEntry of await fs.readdir(storeRoot, { withFileTypes: true })) {
+        if (!sourceEntry.isDirectory() || sourceEntry.isSymbolicLink())
+            continue;
+        let sourceId;
+        try {
+            sourceId = assertSafePluginConfigSegment(sourceEntry.name);
+        }
+        catch {
+            continue;
+        }
+        const sourceRoot = path.join(storeRoot, sourceId);
+        let pluginEntries;
+        try {
+            await assertNoConfigSymlink(boundaryRoot, sourceRoot);
+            pluginEntries = await fs.readdir(sourceRoot, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const pluginEntry of pluginEntries) {
+            if (!pluginEntry.isDirectory() || pluginEntry.isSymbolicLink())
+                continue;
+            let pluginName;
+            try {
+                pluginName = assertSafePluginConfigSegment(pluginEntry.name);
+                await assertNoConfigSymlink(boundaryRoot, path.join(sourceRoot, pluginName));
+            }
+            catch {
+                continue;
+            }
+            let target;
+            try {
+                target = await lstatIfExists(path.join(sourceRoot, pluginName, CONFIG_FILE));
+            }
+            catch {
+                continue;
+            }
+            if (!target)
+                continue;
+            output.push({ sourceId, pluginName, pluginId: `${sourceId}/${pluginName}` });
+        }
+    }
+    return output.sort((left, right) => left.pluginId.localeCompare(right.pluginId));
+}
 export async function listNamespacedPluginConfigStores(options) {
     const boundaryRoot = options.scope === 'user'
         ? resolveAwHome(options.env)
@@ -532,17 +658,17 @@ export async function listNamespacedPluginConfigStores(options) {
             if (parsed.state === 'invalidJson') {
                 throw new Error(`${parsed.store.invalidCode}: invalid namespaced plugin config store "${filePath}".`);
             }
-            const raw = parsed.value;
-            if (!isRecord(raw) || raw.schemaVersion !== 3 || !isRecord(raw.values)
-                || raw.sourceId !== sourceId || raw.pluginName !== pluginName
-                || typeof raw.sourceIdentity !== 'string') {
+            const envelope = readPluginConfigEnvelopeV4(parsed.value, options.scope);
+            if (!envelope
+                || envelope.sourceId !== sourceId
+                || envelope.pluginName !== pluginName) {
                 throw new Error(`schemaVersionUnsupported: invalid namespaced plugin config store "${filePath}".`);
             }
-            const store = validateStoreValues({ filePath, values: raw.values });
+            const store = validateStoreValues({ filePath, values: envelope.values });
             assertReadyPluginConfigStore(store);
             output.push({
                 sourceId,
-                sourceIdentity: raw.sourceIdentity,
+                binding: envelope.binding,
                 pluginName,
                 pluginId: `${sourceId}/${pluginName}`,
                 values: store.values,
@@ -560,22 +686,37 @@ export async function writePluginConfigStore(options) {
     const allowedRoot = resolvePluginConfigAllowedRoot(options);
     const validated = validateStoreValues({ filePath, values: options.values });
     assertReadyPluginConfigStore(validated);
+    const warnings = [];
     await withConfigFileMutation({
         filePath,
         allowedRoot,
-        action: async () => Object.keys(validated.values).length === 0
-            ? atomicRemoveConfigFile({ filePath, allowedRoot })
-            : atomicReplaceConfigFile({
+        action: async () => {
+            if (Object.keys(validated.values).length === 0) {
+                return atomicRemoveConfigFile({ filePath, allowedRoot });
+            }
+            if (options.scope === 'project') {
+                const visibility = await assertProjectSharedConfigPathVisible({
+                    cwd: options.cwd,
+                    targetPath: filePath,
+                    env: options.env,
+                });
+                if (visibility?.state === 'unverified') {
+                    warnings.push(PROJECT_CONFIG_SHAREABILITY_UNVERIFIED_WARNING);
+                }
+            }
+            return atomicReplaceConfigFile({
                 filePath,
                 allowedRoot,
                 content: namespacedConfigContent({ ...options, values: validated.values }),
                 mode: 0o600,
-            }),
+            });
+        },
     });
     return {
         pluginName: options.pluginName,
         scope: options.scope,
         path: filePath,
+        warnings,
     };
 }
 export async function patchPluginConfigStore(options) {
@@ -586,6 +727,7 @@ export async function patchPluginConfigStore(options) {
     });
     const allowedRoot = resolvePluginConfigAllowedRoot(options);
     const removedKeys = options.removeKeys ?? [];
+    const warnings = [];
     await withConfigFileMutation({
         filePath,
         allowedRoot,
@@ -596,7 +738,9 @@ export async function patchPluginConfigStore(options) {
                     ? await readNamespacedStoreFile({
                         filePath,
                         sourceId: options.sourceId,
+                        scope: options.scope,
                         sourceIdentity: options.sourceIdentity,
+                        logicalIdentity: options.logicalIdentity,
                         pluginName: options.pluginName,
                     })
                     : await readStoreFile(filePath)
@@ -618,6 +762,16 @@ export async function patchPluginConfigStore(options) {
                 await atomicRemoveConfigFile({ filePath, allowedRoot });
             }
             else {
+                if (options.scope === 'project') {
+                    const visibility = await assertProjectSharedConfigPathVisible({
+                        cwd: options.cwd,
+                        targetPath: filePath,
+                        env: options.env,
+                    });
+                    if (visibility?.state === 'unverified') {
+                        warnings.push(PROJECT_CONFIG_SHAREABILITY_UNVERIFIED_WARNING);
+                    }
+                }
                 await atomicReplaceConfigFile({
                     filePath,
                     allowedRoot,
@@ -631,6 +785,7 @@ export async function patchPluginConfigStore(options) {
         pluginName: options.pluginName,
         scope: options.scope,
         path: filePath,
+        warnings,
         updatedKeys: Object.keys(options.updates),
         removedKeys,
     };
@@ -897,6 +1052,7 @@ export async function resolveEffectivePluginConfig(options) {
     const userStore = await readPluginConfigStore({
         sourceId: options.sourceId,
         sourceIdentity: options.sourceIdentity,
+        logicalIdentity: options.logicalIdentity,
         pluginName,
         scope: 'user',
         cwd: options.cwd,
@@ -907,6 +1063,7 @@ export async function resolveEffectivePluginConfig(options) {
         : await readPluginConfigStore({
             sourceId: options.sourceId,
             sourceIdentity: options.sourceIdentity,
+            logicalIdentity: options.logicalIdentity,
             pluginName,
             scope: 'project',
             cwd: options.cwd,
@@ -920,8 +1077,10 @@ export async function resolveEffectivePluginConfig(options) {
     const sources = {};
     const fieldStates = {};
     const ignoredUnknownKeys = [];
+    const unsupportedLayerOverrides = [];
     const dangerousKeyIssues = [];
     const schemaKeys = new Set(Object.keys(schema));
+    const userOnlyKeys = codexNativeRefreshKeys(options.manifest);
     for (const key of schemaKeys) {
         sources[key] = 'missing';
     }
@@ -967,13 +1126,26 @@ export async function resolveEffectivePluginConfig(options) {
                 }
             }
         }
+        const supportedEntries = scope === 'project'
+            ? Object.fromEntries(Object.entries(plainEntries).filter(([key]) => {
+                if (!schemaKeys.has(key) || !userOnlyKeys.has(key))
+                    return true;
+                unsupportedLayerOverrides.push({
+                    type: 'configLayerUnsupported',
+                    key,
+                    scope: 'project',
+                    source: 'project',
+                });
+                return false;
+            }))
+            : plainEntries;
         await applyConfigLayer({
             values,
             redactedValues,
             sources,
             fieldStates,
             schema,
-            entries: plainEntries,
+            entries: supportedEntries,
             source,
         });
     }
@@ -999,6 +1171,7 @@ export async function resolveEffectivePluginConfig(options) {
         sources,
         fieldStates,
         issues,
+        unsupportedLayerOverrides,
         ignoredUnknownKeys,
         schema,
         stores: {
@@ -1030,6 +1203,7 @@ export async function resolveProjectArtifactRenderConfig(options) {
             readPluginConfigStore({
                 sourceId: options.sourceId,
                 sourceIdentity: options.sourceIdentity,
+                logicalIdentity: options.logicalIdentity,
                 pluginName,
                 scope: 'user',
                 cwd: options.cwd,
@@ -1038,6 +1212,7 @@ export async function resolveProjectArtifactRenderConfig(options) {
             readPluginConfigStore({
                 sourceId: options.sourceId,
                 sourceIdentity: options.sourceIdentity,
+                logicalIdentity: options.logicalIdentity,
                 pluginName,
                 scope: 'project',
                 cwd: options.cwd,
@@ -1052,6 +1227,7 @@ export async function resolveProjectArtifactRenderConfig(options) {
             values: {},
             sources: {},
             issues: [],
+            unsupportedLayerOverrides: [],
             ignoredUnknownKeys: [],
             schema: {},
             stores: { user: userStore, project: projectStore },
@@ -1067,6 +1243,7 @@ export async function resolveProjectArtifactRenderConfig(options) {
         values: effective.values,
         sources: effective.sources,
         issues: effective.issues,
+        unsupportedLayerOverrides: effective.unsupportedLayerOverrides,
         ignoredUnknownKeys: effective.ignoredUnknownKeys,
         schema: effective.schema,
         stores: {
@@ -1155,6 +1332,7 @@ export async function resolveProjectScopedPluginConfigView(options) {
         sources: effective.sources,
         entries,
         issues: effective.issues,
+        unsupportedLayerOverrides: effective.unsupportedLayerOverrides,
         ignoredUnknownKeys: effective.ignoredUnknownKeys,
     };
 }
@@ -1196,6 +1374,7 @@ async function buildManifestFieldEntries(options) {
     const userStore = await readPluginConfigStore({
         sourceId: options.plugin.sourceId,
         sourceIdentity: options.plugin.sourceIdentity,
+        logicalIdentity: options.plugin.catalogLogicalIdentity,
         pluginName: options.plugin.manifest.name,
         scope: 'user',
         cwd: options.cwd,
@@ -1207,6 +1386,7 @@ async function buildManifestFieldEntries(options) {
         : await readPluginConfigStore({
             sourceId: options.plugin.sourceId,
             sourceIdentity: options.plugin.sourceIdentity,
+            logicalIdentity: options.plugin.catalogLogicalIdentity,
             pluginName: options.plugin.manifest.name,
             scope: 'project',
             cwd: options.cwd,
@@ -1221,6 +1401,7 @@ async function buildManifestFieldEntries(options) {
     const effective = await resolveEffectivePluginConfig({
         sourceId: options.plugin.sourceId,
         sourceIdentity: options.plugin.sourceIdentity,
+        logicalIdentity: options.plugin.catalogLogicalIdentity,
         pluginName: options.plugin.manifest.name,
         manifest: options.plugin.manifest,
         targetScope: options.scope === 'user' ? 'user' : 'project',
@@ -1228,12 +1409,65 @@ async function buildManifestFieldEntries(options) {
         env: options.env,
     });
     const userOnlyKeys = codexNativeRefreshKeys(options.plugin.manifest);
+    const projectRemovalFallback = (key) => {
+        const field = schema[key];
+        if (Object.hasOwn(userPlainEntries, key)) {
+            const value = userPlainEntries[key];
+            const validationIssues = validateCorePluginConfigValue(field, value, key);
+            if (validationIssues.length > 0) {
+                return {
+                    state: 'invalid',
+                    sourceLayer: 'user',
+                    issues: validationIssues.map((issue) => ({
+                        type: 'invalid-config',
+                        key,
+                        source: 'user',
+                        message: formatPluginConfigIssue(issue),
+                    })),
+                };
+            }
+            return {
+                state: 'valid',
+                effectiveValue: redactValue(field, value),
+                sourceLayer: 'user',
+            };
+        }
+        if (field.default === undefined)
+            return { state: 'missing' };
+        const validationIssues = validateCorePluginConfigValue(field, field.default, key);
+        if (validationIssues.length > 0) {
+            return {
+                state: 'invalid',
+                sourceLayer: 'default',
+                issues: validationIssues.map((issue) => ({
+                    type: 'invalid-config',
+                    key,
+                    source: 'default',
+                    message: formatPluginConfigIssue(issue),
+                })),
+            };
+        }
+        return {
+            state: 'valid',
+            effectiveValue: redactValue(field, field.default),
+            sourceLayer: 'default',
+        };
+    };
     const effectiveFieldState = (key) => {
         const source = effective.sources[key];
         const sourceLayer = toConfigSourceLayer(source);
         const field = schema[key];
         const fieldIssues = effective.issues.filter((entry) => entry.key === key);
         const fieldState = effective.fieldStates[key];
+        const fallback = options.scope === 'project'
+            ? projectRemovalFallback(key)
+            : fieldState?.fallback
+                ? {
+                    state: 'valid',
+                    effectiveValue: fieldState.fallback.redactedValue,
+                    sourceLayer: fieldState.fallback.source,
+                }
+                : undefined;
         if (source === undefined || source === 'missing') {
             return {
                 valueState: fieldIssues.length > 0 ? 'invalid' : 'default',
@@ -1253,12 +1487,7 @@ async function buildManifestFieldEntries(options) {
                     issues: fieldState.invalidOverride.issues,
                 },
             } : {}),
-            ...(fieldState?.fallback ? {
-                fallback: {
-                    effectiveValue: fieldState.fallback.redactedValue,
-                    sourceLayer: fieldState.fallback.source,
-                },
-            } : {}),
+            ...(fallback ? { fallback } : {}),
             ...configFieldProjection({
                 field,
                 value: issue ? undefined : effective.values[key],
@@ -1269,12 +1498,18 @@ async function buildManifestFieldEntries(options) {
     };
     const fields = [];
     for (const [key, field] of Object.entries(schema)) {
+        const canSet = options.scope !== 'project'
+            || (!userOnlyKeys.has(key) && field.sensitive !== true);
         const base = {
             key,
             title: field.title ?? key,
             kind: 'manifest',
             reserved: false,
-            writable: options.scope !== 'project' || !userOnlyKeys.has(key),
+            writable: canSet,
+            canSet,
+            canUnset: options.scope === 'user'
+                ? Object.hasOwn(userPlainEntries, key)
+                : options.scope === 'project' && Object.hasOwn(projectPlainEntries, key),
             valueState: 'default',
             effectiveValue: null,
             sourceLayer: null,
@@ -1375,6 +1610,7 @@ async function buildLegacyStoreFieldEntries(options) {
         const store = await readPluginConfigStore({
             sourceId: options.sourceId,
             sourceIdentity: options.sourceIdentity,
+            logicalIdentity: options.logicalIdentity,
             pluginName: options.pluginName,
             scope: location.scope,
             cwd: options.cwd,
@@ -1387,6 +1623,8 @@ async function buildLegacyStoreFieldEntries(options) {
                 kind: 'manifest',
                 reserved: false,
                 writable: false,
+                canSet: false,
+                canUnset: false,
                 valueState: 'configured',
                 effectiveValue: '[redacted]',
                 sourceLayer: location.sourceLayer,
@@ -1437,6 +1675,7 @@ export async function resolveConfigRead(options) {
         : await buildLegacyStoreFieldEntries({
             sourceId: options.sourceId,
             sourceIdentity: options.sourceIdentity,
+            logicalIdentity: options.logicalIdentity,
             pluginName,
             scope: options.scope,
             cwd: options.cwd,
@@ -1446,6 +1685,9 @@ export async function resolveConfigRead(options) {
         pluginName,
         scope: options.scope,
         ...(schemaAccess.schema ? { schema: schemaAccess.schema } : {}),
+        ...(schemaAccess.plugin?.manifest.config?.fields
+            ? { fieldDefinitions: schemaAccess.plugin.manifest.config.fields }
+            : {}),
         fields: manifestFields,
     };
 }
@@ -1588,13 +1830,21 @@ export function toCliConfigPromptOptions(model) {
         requiredKeys: [...model.requiredKeys],
     };
 }
-function formatRequiredConfigSetCommands(pluginName, issues, defaultScope) {
+export function formatPluginConfigSetRecoveryCommand(pluginName, key, field, scope) {
+    return field.sensitive === true
+        ? `aw config set ${pluginName} ${key} --scope user --value-stdin`
+        : `aw config set ${pluginName} ${key} --scope ${scope} --value-json '<json>'`;
+}
+function formatRequiredConfigSetCommands(pluginName, issues, defaultScope, schema) {
     const commands = new Set();
     for (const issue of issues) {
         const scope = issue.source === 'user' || issue.source === 'project'
             ? issue.source
             : defaultScope;
-        commands.add(`aw config set ${pluginName} ${issue.key} --scope ${scope} --value-json '<json>'`);
+        const field = schema[issue.key];
+        if (!field)
+            continue;
+        commands.add(formatPluginConfigSetRecoveryCommand(pluginName, issue.key, field, scope));
     }
     return [...commands].map((command) => `\`${command}\``).join(' 或 ');
 }
@@ -1620,6 +1870,7 @@ export async function preflightRequiredPluginConfigs(options) {
         let effective = await resolveEffectivePluginConfig({
             sourceId: target.sourceId,
             sourceIdentity: target.sourceIdentity,
+            logicalIdentity: target.logicalIdentity,
             pluginName,
             manifest: target.manifest,
             cwd: options.cwd,
@@ -1630,7 +1881,7 @@ export async function preflightRequiredPluginConfigs(options) {
             continue;
         }
         const details = blockingIssues.map((issue) => issue.key).join(', ');
-        const setCommands = formatRequiredConfigSetCommands(pluginName, blockingIssues, options.defaultScope);
+        const setCommands = formatRequiredConfigSetCommands(pluginName, blockingIssues, options.defaultScope, target.manifest.config.fields);
         throw new Error(`${pluginName} requires valid AW config before install/upgrade: ${details}. ` +
             `Run ${setCommands}, or open \`aw\` to complete setup.`);
     }