@open-agent-toolkit/cli 0.2.65 → 0.2.67

package/dist/commands/config/index.js

@@ -11,9 +11,11 @@ import { normalizeDispatchMatrix, validateDispatchRouteTarget, walkDispatchMatri
 import { formatDispatchNotices, terminalReviewerNoticesForMatrix, } from '../../config/dispatch-notices.js';
 import { dispatchPolicyModeDescription, dispatchPolicyPolicyDescription, managedDispatchPolicyValueList, } from '../../config/dispatch-policy-options.js';
 import { parseJsonConfig } from '../../config/json.js';
-import { VALID_DISPATCH_POLICY_MODES, VALID_MANAGED_DISPATCH_POLICIES, MAX_GATE_TIMEOUT_MS, MIN_GATE_TIMEOUT_MS, isValidGateTimeoutMs, normalizeWorkflowPostImplementSequence, readOatConfig, readOatConfigForDefaultScopeRepair, readOatConfigForDocumentationExcludesRepair, readOatConfigForInstructionPointerExcludesRepair, readOatLocalConfig, readUserConfig, writeOatConfig, writeOatLocalConfig, writeUserConfig, } from '../../config/oat-config.js';
-import { resolveEffectiveConfig, } from '../../config/resolve.js';
+import { VALID_DISPATCH_POLICY_MODES, VALID_MANAGED_DISPATCH_POLICIES, MAX_GATE_TIMEOUT_MS, MIN_GATE_TIMEOUT_MS, isValidGateTimeoutMs, normalizeWorkflowPostImplementSequence, readOatConfig, readOatConfigForDefaultScopeRepair, readOatConfigForDocumentationExcludesRepair, readOatConfigForInstructionPointerExcludesRepair, readOatConfigWithWarnings, readOatLocalConfig, readUserConfig, writeOatConfig, writeOatLocalConfig, writeUserConfig, } from '../../config/oat-config.js';
+import { getOwnKey, setOwnKey } from '../../config/own-keys.js';
+import { resolveEffectiveConfig, resolveEnvOverride, } from '../../config/resolve.js';
 import { resolveAssetsRoot } from '../../fs/assets.js';
+import { atomicWriteJson } from '../../fs/io.js';
 import { resolveProjectRoot } from '../../fs/paths.js';
 import { normalizeMatrixCellAvailability, validateMatrixCell, } from '../../providers/identity/availability.js';
 import { createDispatchValidationPassContext, validateDispatchMatrixRefs, } from '../../providers/identity/dispatch-validation.js';
@@ -28,6 +30,31 @@ const DISPATCH_MATRIX_TIERS = [
     'high',
     'frontier',
 ];
+const PJM_REMOTE_PROVIDERS = ['github', 'linear', 'jira'];
+const PJM_REMOTE_OPERATIONS = [
+    'create',
+    'update-fields',
+    'transition',
+    'annotate',
+    'delete',
+    'relink',
+    'detach',
+    'recreate',
+];
+const PJM_REMOTE_CONFIG_KEYS = [
+    'pjm.remote',
+    'pjm.remote.schemaVersion',
+    'pjm.remote.storage.state',
+    'pjm.remote.policy',
+    'pjm.remote.policy.description',
+    'pjm.remote.policy.authority.default',
+    ...PJM_REMOTE_OPERATIONS.map((operation) => `pjm.remote.policy.authority.operations.${operation}`),
+    ...PJM_REMOTE_PROVIDERS.flatMap((provider) => [
+        `pjm.remote.policy.providers.${provider}.description`,
+        `pjm.remote.policy.providers.${provider}.authority.default`,
+        ...PJM_REMOTE_OPERATIONS.map((operation) => `pjm.remote.policy.providers.${provider}.authority.operations.${operation}`),
+    ]),
+];
 const KEY_ORDER = [
     'activeIdea',
     'activeProject',
@@ -58,6 +85,7 @@ const KEY_ORDER = [
     'git.defaultBranch',
     'projects.root',
     'projects.defaultScope',
+    ...PJM_REMOTE_CONFIG_KEYS,
     'tools.brainstorm',
     'tools.core',
     'tools.docs',
@@ -94,7 +122,45 @@ const KEY_ORDER = [
     'workflow.gateTimeouts.artifact',
     'worktrees.root',
 ];
+const PJM_REMOTE_CONFIG_CATALOG = PJM_REMOTE_CONFIG_KEYS.map((key) => {
+    const aggregate = key === 'pjm.remote' || key === 'pjm.remote.policy';
+    const schemaVersion = key === 'pjm.remote.schemaVersion';
+    const storage = key === 'pjm.remote.storage.state';
+    const authority = key.includes('.authority.');
+    const description = key.endsWith('.description');
+    const type = schemaVersion
+        ? 'literal 1'
+        : storage
+            ? 'local | shared'
+            : authority
+                ? 'read-only | user-approved | user-authorized | autonomous'
+                : description
+                    ? 'none | managed-section | replace'
+                    : 'object';
+    return {
+        key,
+        group: 'PJM Remote Shared Policy',
+        file: '.oat/config.json',
+        scope: 'shared repo',
+        type,
+        defaultValue: schemaVersion
+            ? '1'
+            : storage
+                ? 'local'
+                : authority
+                    ? 'read-only'
+                    : description
+                        ? 'none'
+                        : 'unset',
+        mutability: aggregate || schemaVersion ? 'read-only' : 'read/write',
+        owningCommand: aggregate || schemaVersion
+            ? 'individual child keys'
+            : `oat config set ${key} <value> --shared`,
+        description: 'Repository-owned remote storage or mutation policy; host execution is discovered live and cannot broaden it.',
+    };
+});
 const CONFIG_CATALOG = [
+    ...PJM_REMOTE_CONFIG_CATALOG,
     {
         key: 'projects.root',
         group: 'Shared Repo (.oat/config.json)',
@@ -884,6 +950,7 @@ const DEFAULT_DEPENDENCIES = {
     readOatConfigForDefaultScopeRepair,
     readOatConfigForDocumentationExcludesRepair,
     readOatConfigForInstructionPointerExcludesRepair,
+    readOatConfigWithWarnings,
     writeOatConfig,
     readOatLocalConfig,
     writeOatLocalConfig,
@@ -893,6 +960,7 @@ const DEFAULT_DEPENDENCIES = {
     resolveEffectiveConfig,
     resolveAssetsRoot,
     readFile: (path) => readFileDefault(path, 'utf8'),
+    atomicWriteJson,
     confirmAction,
     validateMatrixCell,
     createDispatchValidationPassContext,
@@ -905,6 +973,9 @@ function isConfigKey(value) {
         value === 'workflow.dispatchCeiling.providers' ||
         isDispatchCeilingProviderKey(value));
 }
+function isPjmRemoteConfigKey(key) {
+    return key.startsWith('pjm.remote');
+}
 function isDispatchCeilingProviderKey(value) {
     return (value.startsWith(DISPATCH_CEILING_PROVIDER_KEY_PREFIX) &&
         value.slice(DISPATCH_CEILING_PROVIDER_KEY_PREFIX.length).trim().length > 0);
@@ -1119,6 +1190,12 @@ function validateSurfaceForKey(key, surface) {
         }
         return;
     }
+    if (isPjmRemoteConfigKey(key)) {
+        if (surface !== 'shared') {
+            throw new Error(`Cannot set '${key}' at '${surface}' scope. PJM remote policy and storage can only be set at shared scope.`);
+        }
+        return;
+    }
     if (key.startsWith('explainers.')) {
         const allowed = key === 'explainers.defaults.style' ||
             key === 'explainers.defaults.palette' ||
@@ -1183,9 +1260,16 @@ function defaultSurfaceForKey(key) {
 /**
  * Resolve the `--shared` / `--local` / `--user` trio to a single surface.
  *
- * Lifted verbatim out of the `set` action so `unset` enforces the same
- * mutual-exclusion rule through the same code path. The thrown message is
- * byte-identical to the one `set` raised inline, because tests pin it.
+ * `set`, `unset`, and `adopt` all resolve the trio here -- this is the only
+ * copy of the mutual-exclusion rule and of its message. It was lifted verbatim
+ * out of the `set` action so `unset` could share it, and `adopt` was folded on
+ * afterwards.
+ *
+ * The message is pinned in two ways, so changing it means moving all three
+ * commands together: the per-command cases assert it individually, and the
+ * three-command parity case in `index.test.ts` ('set, unset, and adopt reject
+ * the same conflicting surface flags with one message') compares the three
+ * commands' output to each other as well as to the literal.
  */
 function resolveSurfaceFlags(options) {
     const flagsPresent = [options.shared, options.local, options.user].filter(Boolean).length;
@@ -1435,7 +1519,10 @@ function applyWorkflowValue(workflow, key, value) {
         const { provider, tier } = parseDispatchCeilingProviderConfigKey(key);
         const providers = workflow.dispatchCeiling?.providers ?? {};
         if (tier) {
-            const existingProviderValue = providers[provider];
+            // `provider` is a user-supplied config-key segment, so the lookup is
+            // own-key guarded. The computed-key writes below use object-literal
+            // define semantics and are already safe.
+            const existingProviderValue = getOwnKey(providers, provider);
             const existingTierMap = existingProviderValue &&
                 typeof existingProviderValue === 'object' &&
                 !Array.isArray(existingProviderValue)
@@ -1532,6 +1619,98 @@ function formatResolvedValue(value) {
     }
     return String(value);
 }
+function defaultPjmRemoteSharedConfig() {
+    return {
+        schemaVersion: 1,
+        storage: { state: 'local' },
+        policy: {
+            description: 'none',
+            authority: { default: 'read-only', operations: {} },
+            providers: {},
+        },
+    };
+}
+function applyPjmRemoteSharedValue(current, key, rawValue) {
+    if (key === 'pjm.remote' ||
+        key === 'pjm.remote.policy' ||
+        key === 'pjm.remote.schemaVersion') {
+        throw new Error(`Config key '${key}' is read-only; set one of its documented child keys.`);
+    }
+    const remote = structuredClone(current ?? defaultPjmRemoteSharedConfig());
+    if (key === 'pjm.remote.storage.state') {
+        const state = rawValue.trim();
+        if (state !== 'local' && state !== 'shared') {
+            throw new Error(`Invalid value for ${key}: expected one of local | shared, got '${rawValue}'.`);
+        }
+        if (state === 'shared') {
+            throw new Error("Shared operational storage requires 'oat pjm remote storage shared' preview and approval; direct config set is blocked.");
+        }
+        remote.storage = { state };
+        return remote;
+    }
+    const descriptions = [
+        'none',
+        'managed-section',
+        'replace',
+    ];
+    const authorities = [
+        'read-only',
+        'user-approved',
+        'user-authorized',
+        'autonomous',
+    ];
+    const value = rawValue.trim();
+    if (key === 'pjm.remote.policy.description') {
+        if (!descriptions.includes(value)) {
+            throw new Error(`Invalid value for ${key}: expected one of ${descriptions.join(' | ')}, got '${rawValue}'.`);
+        }
+        remote.policy.description = value;
+        return remote;
+    }
+    if (!authorities.includes(value)) {
+        if (key.endsWith('.description')) {
+            if (!descriptions.includes(value)) {
+                throw new Error(`Invalid value for ${key}: expected one of ${descriptions.join(' | ')}, got '${rawValue}'.`);
+            }
+        }
+        else {
+            throw new Error(`Invalid value for ${key}: expected one of ${authorities.join(' | ')}, got '${rawValue}'.`);
+        }
+    }
+    if (key === 'pjm.remote.policy.authority.default') {
+        remote.policy.authority.default = value;
+        return remote;
+    }
+    const repositoryOperationPrefix = 'pjm.remote.policy.authority.operations.';
+    if (key.startsWith(repositoryOperationPrefix)) {
+        const operation = key.slice(repositoryOperationPrefix.length);
+        remote.policy.authority.operations ??= {};
+        remote.policy.authority.operations[operation] =
+            value;
+        return remote;
+    }
+    const parts = key.split('.');
+    const provider = parts[4];
+    remote.policy.providers ??= {};
+    const providerPolicy = structuredClone(remote.policy.providers[provider] ?? {});
+    if (parts[5] === 'description') {
+        providerPolicy.description = value;
+    }
+    else {
+        providerPolicy.authority ??= {};
+        if (parts[6] === 'default') {
+            providerPolicy.authority.default = value;
+        }
+        else {
+            providerPolicy.authority.operations ??= {};
+            const operation = parts[7];
+            providerPolicy.authority.operations[operation] =
+                value;
+        }
+    }
+    remote.policy.providers[provider] = providerPolicy;
+    return remote;
+}
 async function getConfigValue(repoRoot, userConfigDir, key, dependencies, preserveRawObject = false) {
     const resolved = await dependencies.resolveEffectiveConfig(repoRoot, userConfigDir, dependencies.processEnv);
     const entry = resolved.resolved[key];
@@ -1569,20 +1748,24 @@ function buildResolvedConfigAggregate(resolved, key) {
         if (sourceRank[entry.source] > sourceRank[source]) {
             source = entry.source;
         }
+        // Key segments come from resolved config keys, so a provider literally
+        // named `__proto__` reaches this walk. A bare `cursor[part]` descends into
+        // `Object.prototype` and the leaf write then lands on the global
+        // prototype, polluting every object in the process -- not just this map.
         const parts = entryKey.slice(prefix.length).split('.');
         let cursor = value;
         for (const [index, part] of parts.entries()) {
             if (index === parts.length - 1) {
-                cursor[part] = entry.value;
+                setOwnKey(cursor, part, entry.value);
             }
             else {
-                const nested = cursor[part];
+                const nested = getOwnKey(cursor, part);
                 if (typeof nested !== 'object' ||
                     nested === null ||
                     Array.isArray(nested)) {
-                    cursor[part] = {};
+                    setOwnKey(cursor, part, {});
                 }
-                cursor = cursor[part];
+                cursor = getOwnKey(cursor, part);
             }
         }
     }
@@ -1600,6 +1783,19 @@ async function listConfigKeys(repoRoot, userConfigDir, dependencies) {
 async function setConfigValue(repoRoot, userConfigDir, key, rawValue, surface, dependencies, warn) {
     validateSurfaceForKey(key, surface);
     const effectiveSurface = surface === 'auto' ? defaultSurfaceForKey(key) : surface;
+    if (isPjmRemoteConfigKey(key)) {
+        const config = await dependencies.readOatConfig(repoRoot);
+        const remote = applyPjmRemoteSharedValue(config.pjm?.remote, key, rawValue);
+        await dependencies.writeOatConfig(repoRoot, {
+            ...config,
+            pjm: { ...config.pjm, remote },
+        });
+        return {
+            key,
+            value: rawValue.trim(),
+            source: 'shared',
+        };
+    }
     if (isWorkflowKey(key)) {
         const parsedValue = parseWorkflowValue(key, rawValue);
         const displayValue = formatResolvedValue(parsedValue);
@@ -1990,7 +2186,8 @@ function configPathForKey(key) {
     }
     if (key.startsWith('explainers.') ||
         key.startsWith('documentation.') ||
-        key.startsWith('archive.')) {
+        key.startsWith('archive.') ||
+        isPjmRemoteConfigKey(key)) {
         return key.split('.');
     }
     if (key === 'git.defaultBranch' ||
@@ -2024,8 +2221,25 @@ function configPathForKey(key) {
  */
 async function unsetConfigValue(repoRoot, userConfigDir, key, surface, dependencies, warn) {
     validateSurfaceForKey(key, surface);
-    const resolved = await dependencies.resolveEffectiveConfig(repoRoot, userConfigDir, dependencies.processEnv);
-    const envShadowed = resolved.resolved[key]?.source === 'env';
+    // These are structural views (and, for schemaVersion, the discriminator
+    // that makes the remote policy readable), just as they are for `set`.
+    // Refuse them before resolving config so an unset attempt can never be
+    // mistaken for permission to remove the whole policy boundary.
+    if (key === 'pjm.remote' ||
+        key === 'pjm.remote.policy' ||
+        key === 'pjm.remote.schemaVersion') {
+        throw new Error(`Config key '${key}' is read-only; unset one of its documented child keys.`);
+    }
+    // Deliberately not `resolveEffectiveConfig`: its result was used for this one
+    // boolean, and its strict normalization throws on exactly the malformed
+    // stored value `unset` exists to remove. `ENV_OVERRIDE_MAP` covers three
+    // keys, all of which are in `DEFAULT_SHARED_CONFIG` and therefore always
+    // present in the resolved view, and the env branch is checked first there --
+    // so this probe answers identically for every config key. The whole-config
+    // read this replaces was also a validation barrier; that role is reinstated
+    // separately by the targeted barrier below, which reads every surface except
+    // the targeted one (the targeted one is re-normalized on write instead).
+    const envShadowed = resolveEnvOverride(key, dependencies.processEnv) !== undefined;
     if (key === 'activeProject' || key === 'lastPausedProject') {
         throw new Error(`Cannot unset state key '${key}'. Lifecycle state is cleared with: oat config set ${key} ''`);
     }
@@ -2046,6 +2260,44 @@ async function unsetConfigValue(repoRoot, userConfigDir, key, surface, dependenc
         ? defaultSurfaceForKey(key)
         : surface;
     const path = configPathForKey(key);
+    // Targeted strict barrier.
+    //
+    // `resolveEffectiveConfig` used to run at the top of this function, and as a
+    // side effect of resolving it strictly read all three surfaces. That read --
+    // not its return value -- is what made a malformed value anywhere abort
+    // `unset` before it wrote anything. The `envShadowed` probe above no longer
+    // performs it, so the barrier is reinstated here explicitly and narrowly:
+    // every surface OTHER than the targeted one is read strictly, through the
+    // same injected readers `resolveEffectiveConfig` composes, so a malformed
+    // value on an untargeted surface still aborts with the identical
+    // `Invalid <key>` message it produced before.
+    //
+    // The targeted surface is deliberately excluded, and that exclusion is the
+    // whole point of the change: `removeFromSurface` reads it through the
+    // key-specific repair reader -- lenient only for the key being removed -- and
+    // writes it back through `writeOatConfig` / `writeOatLocalConfig` /
+    // `writeUserConfig`, every one of which re-normalizes. A malformed value on
+    // the targeted surface that is NOT the key being removed is therefore still
+    // refused, on the rewrite rather than on a pre-read.
+    if (effectiveSurface !== 'shared') {
+        await dependencies.readOatConfig(repoRoot);
+    }
+    if (effectiveSurface !== 'local') {
+        await dependencies.readOatLocalConfig(repoRoot);
+    }
+    if (effectiveSurface !== 'user') {
+        await dependencies.readUserConfig(userConfigDir);
+    }
+    // The one branch that gets no re-normalization on the way out: the
+    // `pjm.remote` raw-write path in `removeFromSurface` persists through
+    // `atomicWriteJson`, bypassing `writeOatConfig`. So the targeted shared
+    // surface must be read strictly here too. `pjm.remote` children are not among
+    // the malformed-value repair keys this change targets, which is why adding
+    // this read keeps that branch's acceptance set byte-identical to its previous
+    // one rather than narrowing it.
+    if (isPjmRemoteConfigKey(key)) {
+        await dependencies.readOatConfig(repoRoot);
+    }
     const removed = await removeFromSurface(repoRoot, userConfigDir, key, effectiveSurface, path, dependencies);
     // The env guard is scoped to the targeted surface, not to the effective
     // value, so that `unset` mirrors `set`: `set` happily rewrites a stored value
@@ -2107,6 +2359,25 @@ async function removeFromSurface(repoRoot, userConfigDir, key, effectiveSurface,
         return false;
     }
     const configPath = join(repoRoot, '.oat', 'config.json');
+    if (isPjmRemoteConfigKey(key)) {
+        // PJM remote normalization materializes fail-closed defaults such as
+        // policy.description=none and authority.default=read-only. Removing a
+        // leaf from that normalized object and sending it through writeOatConfig
+        // would therefore write the leaf straight back while reporting success.
+        // The strict shared read happens in `unsetConfigValue`'s targeted barrier
+        // immediately before this call -- this branch depends on it, because
+        // `atomicWriteJson` below bypasses `writeOatConfig`'s normalization, so
+        // nothing downstream would catch a malformed document. Given that read,
+        // perform this removal against the validated raw document and atomically
+        // persist only the requested structural change.
+        const repaired = await removeConfigPathOnDisk(configPath, path);
+        if (!repaired) {
+            return false;
+        }
+        preservePjmRemotePolicyBoundary(repaired, path);
+        await dependencies.atomicWriteJson(configPath, repaired);
+        return true;
+    }
     const sharedConfig = key === 'documentation.excludes'
         ? await dependencies.readOatConfigForDocumentationExcludesRepair(repoRoot)
         : key === 'documentation.instructionPointerExcludes'
@@ -2126,6 +2397,31 @@ async function removeFromSurface(repoRoot, userConfigDir, key, effectiveSurface,
     }
     return false;
 }
+/**
+ * Keep the required PJM remote policy object when unsetting its final leaf.
+ *
+ * The recursive remover normally prunes empty parents. For this one schema,
+ * however, `policy` is the structural boundary that keeps sibling remote state
+ * (notably `storage.state=shared`) readable. An empty policy is valid and
+ * normalizes to the fail-closed defaults; an absent policy makes the complete
+ * remote object unreadable.
+ */
+function preservePjmRemotePolicyBoundary(config, path) {
+    if (path[0] !== 'pjm' || path[1] !== 'remote' || path[2] !== 'policy') {
+        return;
+    }
+    const pjm = config.pjm;
+    if (!isRecord(pjm)) {
+        return;
+    }
+    const remote = pjm.remote;
+    if (!isRecord(remote)) {
+        return;
+    }
+    if (!Object.prototype.hasOwnProperty.call(remote, 'policy')) {
+        remote.policy = {};
+    }
+}
 /**
  * Remove `path` from the raw JSON on disk, ignoring normalization.
  *
@@ -2193,15 +2489,22 @@ function applyDispatchMatrixRecommendation(workflow, recommendation) {
     const providers = {
         ...recommendation.providers,
     };
+    // `existingProviders` is a `normalizeDispatchMatrix` product, which now
+    // keeps a provider literally named `__proto__` as an own key, so
+    // `Object.entries` yields it here and every access is own-key guarded. The
+    // `{ ...recommendation.providers }` spread above is already safe.
     for (const [provider, existingValue] of Object.entries(existingProviders)) {
-        const recommendedValue = recommendation.providers[provider];
+        const recommendedValue = getOwnKey(recommendation.providers, provider);
         if (recommendedValue &&
             typeof recommendedValue !== 'string' &&
             typeof existingValue !== 'string') {
-            providers[provider] = { ...recommendedValue, ...existingValue };
+            setOwnKey(providers, provider, {
+                ...recommendedValue,
+                ...existingValue,
+            });
         }
         else {
-            providers[provider] = existingValue;
+            setOwnKey(providers, provider, existingValue);
         }
     }
     return {
@@ -2218,11 +2521,10 @@ async function effectiveTerminalReviewerNotices(repoRoot, userConfigDir, depende
     const effectiveProviders = {};
     for (const config of [resolved.user, resolved.shared, resolved.local]) {
         for (const [provider, value] of Object.entries(config.workflow?.dispatchCeiling?.providers ?? {})) {
-            const existing = effectiveProviders[provider];
-            effectiveProviders[provider] =
-                isRecord(existing) && isRecord(value)
-                    ? { ...existing, ...value }
-                    : value;
+            const existing = getOwnKey(effectiveProviders, provider);
+            setOwnKey(effectiveProviders, provider, isRecord(existing) && isRecord(value)
+                ? { ...existing, ...value }
+                : value);
         }
     }
     return terminalReviewerNoticesForMatrix(effectiveProviders);
@@ -2329,6 +2631,32 @@ function formatCatalogDetails(entries) {
     ].join('\n'))
         .join('\n\n');
 }
+/**
+ * The `warnings` field for a JSON document, omitted when there is nothing to
+ * say.
+ *
+ * An always-present `warnings: []` would be new noise on the common path and
+ * would break every existing exact-match assertion on these documents, so the
+ * key appears only when it carries something -- the same shape
+ * `exclusionWarnings` uses in `commands/instructions/sync/sync.ts`.
+ */
+function jsonWarnings(warnings) {
+    return warnings.length > 0 ? { warnings } : {};
+}
+/**
+ * Emit shared-config read warnings on the human channel.
+ *
+ * `logger.warn` is a no-op under `--json` (`ui/logger.ts`), so the JSON
+ * document carries the same strings in its own `warnings` field instead. Each
+ * caller picks exactly one channel, which is why this is only ever reached from
+ * the non-JSON branch: routing both ways would print nothing extra today but
+ * would double-print the moment the logger learned to emit under `--json`.
+ */
+function emitConfigReadWarnings(context, warnings) {
+    for (const warning of warnings) {
+        context.logger.warn(warning);
+    }
+}
 async function runGet(keyArg, context, dependencies) {
     try {
         if (!isConfigKey(keyArg)) {
@@ -2336,14 +2664,21 @@ async function runGet(keyArg, context, dependencies) {
         }
         const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
         const userConfigDir = join(context.home, '.oat');
+        // One read per invocation, not one per resolved layer, so a wrong-typed
+        // key is reported once. A fail-closed key throws here exactly as it would
+        // have thrown inside `resolveEffectiveConfig` below -- same normalizer,
+        // same message -- so error precedence is unchanged.
+        const { warnings } = await dependencies.readOatConfigWithWarnings(repoRoot);
         const value = await getConfigValue(repoRoot, userConfigDir, keyArg, dependencies, context.json);
         if (context.json) {
             context.logger.json({
                 status: 'ok',
                 ...value,
+                ...jsonWarnings(warnings),
             });
         }
         else {
+            emitConfigReadWarnings(context, warnings);
             context.logger.info(formatResolvedValue(value.value) ?? '');
         }
         process.exitCode = 0;
@@ -2463,6 +2798,9 @@ async function runList(context, dependencies) {
     try {
         const repoRoot = await dependencies.resolveProjectRoot(context.cwd);
         const userConfigDir = join(context.home, '.oat');
+        // `list` resolves every key and each resolution re-reads the shared file,
+        // so the warning has to come from this one read rather than from the loop.
+        const { warnings } = await dependencies.readOatConfigWithWarnings(repoRoot);
         const values = [];
         for (const key of await listConfigKeys(repoRoot, userConfigDir, dependencies)) {
             values.push(await getConfigValue(repoRoot, userConfigDir, key, dependencies));
@@ -2471,9 +2809,11 @@ async function runList(context, dependencies) {
             context.logger.json({
                 status: 'ok',
                 values,
+                ...jsonWarnings(warnings),
             });
         }
         else {
+            emitConfigReadWarnings(context, warnings);
             context.logger.info(formatList(values));
         }
         process.exitCode = 0;
@@ -2594,21 +2934,7 @@ export function createConfigCommand(overrides = {}) {
         .action(async (template, options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));
         try {
-            const flagsPresent = [
-                options.shared,
-                options.local,
-                options.user,
-            ].filter(Boolean).length;
-            if (flagsPresent > 1) {
-                throw new Error('--shared, --local, and --user flags are mutually exclusive; pass at most one.');
-            }
-            let surface = 'auto';
-            if (options.shared)
-                surface = 'shared';
-            else if (options.local)
-                surface = 'local';
-            else if (options.user)
-                surface = 'user';
+            const surface = resolveSurfaceFlags(options);
             await runAdopt(template, { surface }, context, dependencies);
         }
         catch (error) {

package/dist/commands/docs/index-generate/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAI5C,eAAO,MAAM,uBAAuB,iIAC4F,CAAC;AAuBjI,UAAU,6BAA6B;IACrC,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,aAAa,EAAE,oBAAoB,KAChD,OAAO,CAAC,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,KAAK,MAAM,CAAC;IACrE,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5D,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC7D;AAED,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAggBD,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAgCT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAI5C,eAAO,MAAM,uBAAuB,iIAC4F,CAAC;AAuBjI,UAAU,6BAA6B;IACrC,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,aAAa,EAAE,oBAAoB,KAChD,OAAO,CAAC,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,KAAK,MAAM,CAAC;IACrE,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5D,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC7D;AAED,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAomBD,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAgCT"}