@salesforce/b2c-tooling-sdk 2.3.0 → 2.5.0

package/dist/esm/config/config-write.js

@@ -0,0 +1,296 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * Read and write individual configuration fields at the source that supplies them.
+ *
+ * Writes go to the highest-priority source currently supplying a field, so the
+ * new value always takes effect. A field no source supplies goes to the entry
+ * that selected the instance (for example the active dw.json config). Sources
+ * that don't implement {@link ConfigSource.updateConfig} (shell environment,
+ * ~/.mobify, package.json) are never written; credential stores are written
+ * through {@link ConfigSource.storeCredential} for their declared fields.
+ *
+ * @module config/config-write
+ */
+import { getConfigOrigins } from './config-origins.js';
+import { DW_JSON_FIELDS } from './dw-json-schema.js';
+import { CONFIG_KEY_ALIASES, kebabToCamelCase } from './mapping.js';
+import { CREDENTIAL_GROUPS } from './resolver.js';
+/** dw.json keys whose normalized field has a different name. */
+const FIELD_RENAMES = { oauthScopes: 'scopes' };
+/** dw.json keys managed by other commands (`setup instance ...`) or shorthands of another key. */
+const UNSETTABLE_KEYS = new Set(['name', 'active', 'user-auth']);
+/** Error raised when a configuration field can't be read or written safely. */
+export class ConfigWriteError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ConfigWriteError';
+    }
+}
+function camelToKebabCase(value) {
+    return value.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`);
+}
+/** All keys `setup set` accepts, in dw.json order. */
+export function listConfigKeys() {
+    return Object.entries(DW_JSON_FIELDS)
+        .filter(([key]) => !UNSETTABLE_KEYS.has(key))
+        .map(([key, schema]) => {
+        const dwKey = kebabToCamelCase(key);
+        return { key, field: (FIELD_RENAMES[dwKey] ?? dwKey), schema };
+    });
+}
+/**
+ * Resolve a user-supplied key (dw.json kebab-case, camelCase, a legacy alias,
+ * or the normalized field name) to a settable configuration key.
+ *
+ * @throws ConfigWriteError for unknown or unsettable keys
+ */
+export function resolveConfigKey(input) {
+    const trimmed = input.trim();
+    const canonical = CONFIG_KEY_ALIASES[trimmed] ?? kebabToCamelCase(trimmed);
+    const key = camelToKebabCase(canonical);
+    if (UNSETTABLE_KEYS.has(key)) {
+        throw new ConfigWriteError('CONFIG_KEY_UNKNOWN', key === 'user-auth'
+            ? '`user-auth` is shorthand for `auth-methods`; set `auth-methods` instead.'
+            : `\`${key}\` is managed by \`b2c setup instance\` commands.`);
+    }
+    const found = listConfigKeys().find((entry) => entry.key === key || entry.field === canonical);
+    if (!found) {
+        throw new ConfigWriteError('CONFIG_KEY_UNKNOWN', `Unknown configuration key "${input}". Keys use dw.json names, for example: ${listConfigKeys()
+            .slice(0, 6)
+            .map((entry) => entry.key)
+            .join(', ')}.`);
+    }
+    return found;
+}
+function describeSchema(schema) {
+    if (Array.isArray(schema.oneOf))
+        return schema.oneOf.map(describeSchema).join(' or ');
+    if (Array.isArray(schema.enum))
+        return `one of ${schema.enum.join(', ')}`;
+    if (schema.type === 'array' && schema.items)
+        return `array of ${describeSchema(schema.items)}`;
+    return String(schema.type ?? 'value');
+}
+/** Validate a value against the JSON Schema subset used by the dw.json schema. */
+function validate(schema, value, path) {
+    if (Array.isArray(schema.oneOf)) {
+        const options = schema.oneOf;
+        return options.some((option) => validate(option, value, path) === undefined)
+            ? undefined
+            : `${path} must be ${describeSchema(schema)}`;
+    }
+    switch (schema.type) {
+        case 'array': {
+            if (!Array.isArray(value))
+                return `${path} must be an array`;
+            for (const [index, item] of value.entries()) {
+                const error = schema.items ? validate(schema.items, item, `${path}[${index}]`) : undefined;
+                if (error)
+                    return error;
+            }
+            break;
+        }
+        case 'boolean': {
+            if (typeof value !== 'boolean')
+                return `${path} must be true or false`;
+            break;
+        }
+        case 'object': {
+            if (!value || typeof value !== 'object' || Array.isArray(value))
+                return `${path} must be a JSON object`;
+            const record = value;
+            const properties = (schema.properties ?? {});
+            for (const required of schema.required ?? []) {
+                if (record[required] === undefined)
+                    return `${path}.${required} is required`;
+            }
+            for (const [name, item] of Object.entries(record)) {
+                if (!properties[name]) {
+                    if (schema.additionalProperties === false)
+                        return `${path}.${name} is not a known property`;
+                    continue;
+                }
+                const error = validate(properties[name], item, `${path}.${name}`);
+                if (error)
+                    return error;
+            }
+            break;
+        }
+        case 'string': {
+            if (typeof value !== 'string')
+                return `${path} must be a string`;
+            break;
+        }
+    }
+    if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+        return `${path} must be ${describeSchema(schema)}`;
+    }
+    return undefined;
+}
+function acceptsStringList(schema) {
+    if (Array.isArray(schema.oneOf))
+        return schema.oneOf.some(acceptsStringList);
+    return schema.type === 'array' && schema.items?.type === 'string';
+}
+/**
+ * Coerce a command-line value to the key's type.
+ *
+ * String keys keep the text as given. Other keys accept JSON (`true`,
+ * `["a","b"]`, `{"level":"NO_DELETE"}`); string-list keys also accept a
+ * plain or comma-separated value (`./schemas` becomes `["./schemas"]`).
+ *
+ * @throws ConfigWriteError when the value doesn't match the key's schema
+ */
+export function parseConfigValue(key, raw) {
+    const candidates = [];
+    if (key.schema.type === 'string') {
+        candidates.push(raw);
+    }
+    else {
+        try {
+            candidates.push(JSON.parse(raw));
+        }
+        catch {
+            // Not JSON; fall through to the plain-text forms below.
+        }
+        if (acceptsStringList(key.schema)) {
+            candidates.push(raw
+                .split(',')
+                .map((item) => item.trim())
+                .filter(Boolean));
+        }
+    }
+    let error;
+    for (const candidate of candidates) {
+        error = validate(key.schema, candidate, key.key);
+        if (!error)
+            return candidate;
+    }
+    throw new ConfigWriteError('CONFIG_VALUE_INVALID', `Invalid value for ${key.key}: ${error ?? `expected ${describeSchema(key.schema)}`}.`);
+}
+function describeSource(info) {
+    return info.location ? `${info.name} (${info.location})` : info.name;
+}
+/**
+ * Whether a source can persist `field`: through {@link ConfigSource.updateConfig},
+ * or for a credential store, {@link ConfigSource.storeCredential} for a declared
+ * credential field.
+ */
+function canWrite(origin, field) {
+    const { source } = origin;
+    return Boolean(source.updateConfig || (source.storeCredential && source.credentialFields?.includes(field)));
+}
+/**
+ * Locate a field in a resolved configuration: which source supplies it and
+ * which source a write should update.
+ *
+ * The target is, in order: the source supplying the field; the source
+ * supplying the other half of its credential pair; or, for a field nothing
+ * sets, the source that supplied the instance itself (its `instanceName`, else
+ * its `hostname`). A derived value (a sandbox hostname worked out from its
+ * tenant ID) counts as supplied by the source of the field it came from. Every
+ * rule uses only {@link ConfigSourceInfo} and the optional write methods, so
+ * plugin sources take part the same way dw.json does.
+ */
+export function locateConfigField(config, field) {
+    const origins = getConfigOrigins(config) ?? [];
+    const supplies = (info, name) => info.fields.includes(name) && !info.fieldsIgnored?.includes(name);
+    /** The origin supplying `name`, following a derived value back to the origin of its base field. */
+    const originOf = (name) => {
+        const direct = origins.find((origin) => supplies(origin.info, name));
+        if (direct)
+            return direct;
+        const base = config.sources.find((info) => info.derivedFrom && supplies(info, name))?.derivedFrom?.field;
+        return base ? origins.find((origin) => supplies(origin.info, base)) : undefined;
+    };
+    const supplier = config.sources.find((info) => supplies(info, field));
+    // A credential pair (client ID + secret) must come from one source, so the
+    // other half of a supplied pair decides where this field goes.
+    const partners = CREDENTIAL_GROUPS.find((group) => group.includes(field)) ?? [field];
+    const own = originOf(field);
+    const supplying = own ?? partners.map(originOf).find(Boolean);
+    if (supplying) {
+        if (!canWrite(supplying, field)) {
+            return {
+                supplier: own?.info,
+                error: new ConfigWriteError('CONFIG_SOURCE_READ_ONLY', own
+                    ? `${field} comes from ${describeSource(supplying.info)}, which can't be written. Change or remove it there.`
+                    : `${field} pairs with ${partners.filter((partner) => partner !== field).join(', ')} from ${describeSource(supplying.info)}, which can't be written. Set both there.`),
+            };
+        }
+        return { supplier, target: supplying };
+    }
+    if (supplier || config.values[field] !== undefined) {
+        const base = supplier?.derivedFrom;
+        return {
+            supplier,
+            error: new ConfigWriteError('CONFIG_SOURCE_READ_ONLY', base
+                ? `${field} is derived from ${base.field}${base.source ? '' : ' given as a flag'}, so it can't be written here.`
+                : `${field} comes from ${supplier ? describeSource(supplier) : 'a command-line flag'}, which can't be written.`),
+        };
+    }
+    // Nothing supplies the field: write it where the instance itself is defined.
+    const instanceOrigin = originOf('instanceName') ?? originOf('hostname');
+    if (instanceOrigin && canWrite(instanceOrigin, field))
+        return { target: instanceOrigin };
+    return {
+        error: new ConfigWriteError('CONFIG_NO_WRITE_TARGET', instanceOrigin
+            ? `${field} isn't set, and ${describeSource(instanceOrigin.info)} can't store it.`
+            : `${field} isn't set and no instance is selected to write it to. Select one with --instance, mark one active with \`b2c setup instance set-active\`, or create one with \`b2c setup instance create\`.`),
+    };
+}
+/** Persist one field through whichever write method the target source implements. */
+async function persist(config, { source, info, options }, field, value) {
+    if (source.updateConfig)
+        return source.updateConfig({ [field]: value }, options);
+    const instance = config.values.instanceName ?? options.instance;
+    if (!instance) {
+        throw new ConfigWriteError('CONFIG_NO_WRITE_TARGET', `${source.name} stores credentials per instance, and no instance name is selected. Use --instance.`);
+    }
+    if (value === undefined) {
+        if (!source.removeCredential) {
+            throw new ConfigWriteError('CONFIG_SOURCE_READ_ONLY', `${source.name} can't remove ${field}.`);
+        }
+        await source.removeCredential(instance, field, options);
+    }
+    else {
+        if (typeof value !== 'string')
+            throw new ConfigWriteError('CONFIG_VALUE_INVALID', `${field} must be a string.`);
+        await source.storeCredential(instance, field, value, options);
+    }
+    return { location: info.location ?? source.name, instance };
+}
+/**
+ * Set or remove (`value === undefined`) a field at the source that supplies it.
+ *
+ * @throws ConfigWriteError when the field has no writable target
+ */
+export async function writeConfigField(config, field, value) {
+    const location = locateConfigField(config, field);
+    if (value === undefined && !location.supplier) {
+        throw new ConfigWriteError('CONFIG_NOT_SET', `${field} isn't set.`);
+    }
+    const base = value === undefined ? location.supplier?.derivedFrom : undefined;
+    if (base) {
+        throw new ConfigWriteError('CONFIG_NOT_SET', `${field} isn't set; it's derived from ${base.field}${base.source ? ` in ${base.source}` : ''}. Unset ${base.field} instead.`);
+    }
+    if (!location.target)
+        throw location.error;
+    const result = await persist(config, location.target, field, value);
+    return { ...result, source: location.target.source.name };
+}
+/**
+ * Remove a field from the source that supplies it.
+ *
+ * @throws ConfigWriteError when the field isn't set or its source can't be written
+ */
+export async function removeConfigField(config, field) {
+    return writeConfigField(config, field, undefined);
+}
+//# sourceMappingURL=config-write.js.map

package/dist/esm/config/config-write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-write.js","sourceRoot":"","sources":["../../../src/config/config-write.ts"],"names":[],"mappings":"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"}

package/dist/esm/config/dw-json-schema.d.ts

@@ -0,0 +1,14 @@
+/** A JSON Schema fragment (draft-07 subset). */
+export type JsonSchema = Record<string, unknown>;
+/** Public URL of the published schema (usable as `"$schema"` in dw.json). */
+export declare const DW_JSON_SCHEMA_URL = "https://salesforcecommercecloud.github.io/b2c-developer-tooling/schemas/dw.schema.json";
+/**
+ * Canonical instance-level fields keyed by kebab-case name (the on-disk spelling).
+ * Descriptions mirror the Settings Reference in the configuration guide.
+ */
+export declare const DW_JSON_FIELDS: Record<string, JsonSchema>;
+/**
+ * Builds the `dw.json` JSON Schema from {@link DW_JSON_FIELDS}, adding the
+ * camelCase spelling and legacy aliases for every field.
+ */
+export declare function buildDwJsonSchema(): JsonSchema;

package/dist/esm/config/dw-json-schema.js

@@ -0,0 +1,269 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * JSON Schema for `dw.json` configuration files.
+ *
+ * This module is the single source of truth for the published schema at
+ * `data/schemas/dw.schema.json` (regenerate with `pnpm run generate:dw-json-schema`).
+ * Editors use it for validation, completion, and hover docs; the VS Code
+ * extension registers it for every `dw.json`.
+ *
+ * `dw.json` accepts both kebab-case (canonical) and camelCase spellings, plus a
+ * few legacy aliases (see {@link CONFIG_KEY_ALIASES}). The schema lists every
+ * accepted spelling so editors do not flag valid files. Unknown keys are allowed
+ * because other tools share `dw.json`.
+ *
+ * @module config/dw-json-schema
+ */
+import { CLIENT_AUTH_METHODS } from '../auth/client-credentials.js';
+import { CONFIG_KEY_ALIASES, kebabToCamelCase } from './mapping.js';
+/** Public URL of the published schema (usable as `"$schema"` in dw.json). */
+export const DW_JSON_SCHEMA_URL = 'https://salesforcecommercecloud.github.io/b2c-developer-tooling/schemas/dw.schema.json';
+const DOCS_URL = 'https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/configuration.html';
+const stringArray = { type: 'array', items: { type: 'string' } };
+const AUTH_METHODS = ['client-credentials', 'jwt', 'user', 'implicit', 'basic', 'api-key'];
+/**
+ * Canonical instance-level fields keyed by kebab-case name (the on-disk spelling).
+ * Descriptions mirror the Settings Reference in the configuration guide.
+ */
+export const DW_JSON_FIELDS = {
+    // Instance and site
+    name: { type: 'string', description: 'Connection name for instance selection (`--instance` / `SFCC_INSTANCE`).' },
+    active: { type: 'boolean', description: 'Use this entry as the default instance.' },
+    hostname: {
+        type: 'string',
+        description: 'Instance hostname, without a URL path (e.g. `abcd-001.dx.commercecloud.salesforce.com`). Env: `SFCC_SERVER`.',
+    },
+    'webdav-hostname': { type: 'string', description: 'Separate WebDAV hostname. Env: `SFCC_WEBDAV_SERVER`.' },
+    'code-version': {
+        type: 'string',
+        description: 'Default code version for operations that accept one. Env: `SFCC_CODE_VERSION`.',
+    },
+    'short-code': { type: 'string', description: 'SCAPI short code. Env: `SFCC_SHORTCODE`.' },
+    'tenant-id': {
+        type: 'string',
+        description: 'Tenant or organization ID, such as `abcd_001` or `f_ecom_abcd_001`. Env: `SFCC_TENANT_ID`.',
+    },
+    'site-id': {
+        type: 'string',
+        description: 'Default site/channel ID for supported site and shopper operations. Env: `SFCC_SITE_ID`.',
+    },
+    'api-backend': {
+        type: 'string',
+        enum: ['auto', 'scapi', 'ocapi'],
+        description: 'API backend for operations supporting both SCAPI and OCAPI. `auto` (default) prefers SCAPI with OCAPI fallback. Env: `SFCC_API_BACKEND`.',
+    },
+    // Administrative authentication
+    'client-id': { type: 'string', description: 'Account Manager API client ID. Env: `SFCC_CLIENT_ID`.' },
+    'client-secret': { type: 'string', description: 'Account Manager client secret. Env: `SFCC_CLIENT_SECRET`.' },
+    'oauth-scopes': {
+        ...stringArray,
+        description: 'Requested OAuth scopes. Scope grants must be configured on the API client. Env: `SFCC_OAUTH_SCOPES` (comma-separated).',
+    },
+    'jwt-cert-path': {
+        type: 'string',
+        description: 'PEM certificate path for JWT authentication. Env: `SFCC_JWT_CERT`; flag: `--jwt-cert`.',
+    },
+    'jwt-key-path': { type: 'string', description: 'PEM private key path for JWT authentication. Env: `SFCC_JWT_KEY`.' },
+    'jwt-passphrase': {
+        type: 'string',
+        description: 'Passphrase for an encrypted JWT private key. Env: `SFCC_JWT_PASSPHRASE`.',
+    },
+    'auth-methods': {
+        type: 'array',
+        items: { type: 'string', enum: AUTH_METHODS },
+        uniqueItems: true,
+        description: 'Ordered list of allowed authentication methods. Do not combine with `user-auth`. Env: `SFCC_AUTH_METHODS` (comma-separated).',
+    },
+    'user-auth': {
+        type: 'boolean',
+        description: 'Shorthand for `"auth-methods": ["user"]` (browser login). Do not combine with `auth-methods`.',
+    },
+    'account-manager-host': {
+        type: 'string',
+        description: 'Account Manager hostname override. Env: `SFCC_ACCOUNT_MANAGER_HOST`.',
+    },
+    'client-auth-method': {
+        type: 'string',
+        enum: [...CLIENT_AUTH_METHODS],
+        description: 'How client credentials are sent to Account Manager (default `basic`). Env: `SFCC_CLIENT_AUTH_METHOD`; flag: `--client-auth-method`.',
+    },
+    // Shopper authentication
+    'slas-client-id': {
+        type: 'string',
+        description: 'Shopper Login and API Access Service (SLAS) client ID. Env: `SFCC_SLAS_CLIENT_ID`.',
+    },
+    'slas-client-secret': {
+        type: 'string',
+        description: 'Secret for a private SLAS client; omit for public clients. Env: `SFCC_SLAS_CLIENT_SECRET`.',
+    },
+    // WebDAV and certificates
+    username: {
+        type: 'string',
+        description: 'Business Manager username (typically an email address) for WebDAV. Env: `SFCC_USERNAME`.',
+    },
+    password: { type: 'string', description: 'WebDAV access key for `username`. Env: `SFCC_PASSWORD`.' },
+    certificate: {
+        type: 'string',
+        description: 'Path to a PKCS12 (`.p12` / `.pfx`) client certificate for mTLS. Env: `SFCC_CERTIFICATE`.',
+    },
+    'certificate-passphrase': {
+        type: 'string',
+        description: 'Client certificate passphrase. Env: `SFCC_CERTIFICATE_PASSPHRASE`.',
+    },
+    'self-signed': {
+        type: 'boolean',
+        description: 'Disable server certificate verification (default `false`). Not required just because you use mTLS. Env: `SFCC_SELFSIGNED`.',
+    },
+    // Code, content, and documentation
+    cartridges: {
+        oneOf: [stringArray, { type: 'string' }],
+        description: 'Cartridge names for deploy/watch filtering and IDE discovery. Array, or a colon/comma-separated string. Env: `SFCC_CARTRIDGES`.',
+    },
+    'auto-upload': { type: 'boolean', description: 'Automatically upload code changes from the VS Code extension.' },
+    'content-library': { type: 'string', description: 'Default library for content list/export.' },
+    catalogs: { ...stringArray, description: 'Catalog IDs for WebDAV browsing. Env: `SFCC_CATALOGS`.' },
+    libraries: {
+        type: 'array',
+        items: {
+            oneOf: [
+                { type: 'string' },
+                {
+                    type: 'object',
+                    required: ['id'],
+                    properties: {
+                        id: { type: 'string', description: 'Library ID.' },
+                        siteLibrary: { type: 'boolean', description: 'Whether this is a site-private library.' },
+                    },
+                },
+            ],
+        },
+        description: 'Content library IDs, as strings or `{"id": "RefArch", "siteLibrary": true}` entries. Env: `SFCC_LIBRARIES`.',
+    },
+    'asset-query': {
+        ...stringArray,
+        description: 'JSON dot-paths for finding static asset URLs in content (default `["image.path"]`). Env: `SFCC_ASSET_QUERY`.',
+    },
+    'import-set-exclude': {
+        ...stringArray,
+        description: 'Project-relative directories to exclude recursively from import-set discovery. Env: `SFCC_IMPORT_SET_EXCLUDE`.',
+    },
+    'docs-categories': {
+        ...stringArray,
+        description: 'Documentation category allowlist for supported searches. Env: `SFCC_DOCS_CATEGORIES`.',
+    },
+    'scapi-schemas': {
+        ...stringArray,
+        description: 'Local SCAPI OpenAPI JSON files or directories (relative to the project directory), or http(s) URLs, for MCP code mode. Env: `SFCC_SCAPI_SCHEMAS`.',
+    },
+    // Sandboxes and analytics
+    realm: { type: 'string', description: 'Default realm for sandbox operations.' },
+    'sandbox-api-host': {
+        type: 'string',
+        description: 'On-Demand Sandbox API hostname override. Env: `SFCC_SANDBOX_API_HOST`.',
+    },
+    'cip-host': { type: 'string', description: 'CIP analytics host override. Env: `SFCC_CIP_HOST`.' },
+    safety: {
+        type: 'object',
+        description: 'Per-instance safety restrictions and confirmation rules. See the Safety Mode guide.',
+        additionalProperties: false,
+        properties: {
+            level: {
+                type: 'string',
+                enum: ['NONE', 'NO_DELETE', 'NO_UPDATE', 'READ_ONLY'],
+                description: 'Baseline restriction level. Env: `SFCC_SAFETY_LEVEL`.',
+            },
+            confirm: {
+                type: 'boolean',
+                description: 'Require interactive confirmation for blocked operations instead of refusing them.',
+            },
+            rules: {
+                type: 'array',
+                description: 'Ordered rules; the first match wins.',
+                items: {
+                    type: 'object',
+                    required: ['action'],
+                    additionalProperties: false,
+                    properties: {
+                        method: { type: 'string', description: 'HTTP method pattern (e.g. `POST`, `DELETE`).' },
+                        path: { type: 'string', description: 'URL path glob (e.g. `/jobs/*/executions`).' },
+                        job: { type: 'string', description: 'Job ID glob.' },
+                        command: { type: 'string', description: 'CLI command ID glob (e.g. `sandbox:*`, `ecdn:cache:purge`).' },
+                        action: { type: 'string', enum: ['allow', 'block', 'confirm'], description: 'Action when the rule matches.' },
+                    },
+                },
+            },
+        },
+    },
+    // Managed Runtime
+    'mrt-api-key': { type: 'string', description: 'Managed Runtime API key. Env: `MRT_API_KEY`.' },
+    'mrt-project': {
+        type: 'string',
+        description: 'Managed Runtime project slug (storefront ID for SCAPI MRT operations). Env: `MRT_PROJECT`.',
+    },
+    'mrt-environment': { type: 'string', description: 'Managed Runtime target environment. Env: `MRT_ENVIRONMENT`.' },
+    'mrt-origin': { type: 'string', description: 'Managed Runtime API origin override. Env: `MRT_CLOUD_ORIGIN`.' },
+    'mrt-backend': {
+        type: 'string',
+        enum: ['auto', 'legacy', 'scapi'],
+        description: 'Managed Runtime backend for supported operations (default `auto`). Env: `MRT_BACKEND`.',
+    },
+};
+/** Legacy and alternate spellings, excluding simple camelCase forms. */
+function aliasesFor(camelKey) {
+    return Object.entries(CONFIG_KEY_ALIASES)
+        .filter(([, canonical]) => canonical === camelKey)
+        .map(([alias]) => alias);
+}
+/**
+ * Builds the `dw.json` JSON Schema from {@link DW_JSON_FIELDS}, adding the
+ * camelCase spelling and legacy aliases for every field.
+ */
+export function buildDwJsonSchema() {
+    const instanceProperties = {};
+    for (const [kebab, schema] of Object.entries(DW_JSON_FIELDS)) {
+        instanceProperties[kebab] = schema;
+        const camel = kebabToCamelCase(kebab);
+        const alternates = [camel, ...aliasesFor(camel)].filter((k) => k !== kebab);
+        for (const alternate of alternates) {
+            instanceProperties[alternate] ??= {
+                ...schema,
+                description: `Alternate spelling of \`${kebab}\`. ${String(schema.description ?? '')}`.trim(),
+            };
+        }
+    }
+    const instanceSchema = {
+        type: 'object',
+        properties: instanceProperties,
+        additionalProperties: true,
+        not: {
+            anyOf: [
+                { required: ['user-auth', 'auth-methods'] },
+                { required: ['userAuth', 'authMethods'] },
+                { required: ['user-auth', 'authMethods'] },
+                { required: ['userAuth', 'auth-methods'] },
+            ],
+        },
+    };
+    return {
+        $schema: 'http://json-schema.org/draft-07/schema#',
+        $id: DW_JSON_SCHEMA_URL,
+        title: 'B2C Commerce dw.json',
+        description: `Connection and project configuration for B2C Commerce tooling. See ${DOCS_URL}`,
+        definitions: { instance: instanceSchema },
+        allOf: [{ $ref: '#/definitions/instance' }],
+        type: 'object',
+        properties: {
+            $schema: { type: 'string', description: 'JSON Schema reference for editor support.' },
+            configs: {
+                type: 'array',
+                description: 'Named instance entries. Select one with `--instance` / `SFCC_INSTANCE`, or mark one `active`.',
+                items: { $ref: '#/definitions/instance' },
+            },
+        },
+    };
+}
+//# sourceMappingURL=dw-json-schema.js.map

package/dist/esm/config/dw-json-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dw-json-schema.js","sourceRoot":"","sources":["../../../src/config/dw-json-schema.ts"],"names":[],"mappings":"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"}

package/dist/esm/config/dw-json.d.ts

@@ -93,6 +93,8 @@ export interface DwJsonConfig {
     cipHost?: string;
     /** Documentation categories to expose (allowlist); dw.json key `docs-categories` */
     docsCategories?: string[];
+    /** Local SCAPI OpenAPI contracts (files, directories or http(s) URLs) for MCP code mode; dw.json key `scapi-schemas` */
+    scapiSchemas?: string[];
     /** Path to PKCS12 certificate file for mTLS (two-factor auth) */
     certificate?: string;
     /** Passphrase for the certificate */

package/dist/esm/config/dw-json.js

@@ -297,16 +297,20 @@ export async function updateInstanceConfig(patch, options = {}) {
     if (!target) {
         throw new Error(`Instance "${options.instance}" not found`);
     }
+    // Rebuild the entry so a replaced key keeps its position in the file.
+    const entries = Object.entries(target);
     for (const [field, value] of Object.entries(patch)) {
-        for (const key of Object.keys(target)) {
-            if ((CONFIG_KEY_ALIASES[key] ?? kebabToCamelCase(key)) === field) {
-                delete target[key];
-            }
-        }
+        const matches = (key) => (CONFIG_KEY_ALIASES[key] ?? kebabToCamelCase(key)) === field;
+        const position = entries.findIndex(([key]) => matches(key));
+        const remaining = entries.filter(([key]) => !matches(key));
         if (value !== undefined) {
-            target[camelToKebabCase(field)] = value;
+            remaining.splice(position === -1 ? remaining.length : position, 0, [camelToKebabCase(field), value]);
         }
+        entries.splice(0, entries.length, ...remaining);
     }
+    for (const key of Object.keys(target))
+        delete target[key];
+    Object.assign(target, Object.fromEntries(entries));
     await saveDwJson(existing, dwJsonPath);
     return { name: target.name, path: dwJsonPath };
 }