@salesforce/b2c-cli 1.19.1 → 1.20.1

package/dist/commands/preferences/site/update.d.ts

@@ -0,0 +1,19 @@
+import { PreferencesCommand } from '../../../utils/preferences.js';
+import { type SitePreferences } from '@salesforce/b2c-tooling-sdk';
+export default class PreferencesSiteUpdate extends PreferencesCommand<typeof PreferencesSiteUpdate> {
+    static args: {
+        'group-id': import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static description: string;
+    static enableJsonFlag: boolean;
+    static examples: string[];
+    static flags: {
+        'instance-type': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'site-id': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        file: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        body: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'mask-passwords': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static strict: boolean;
+    run(): Promise<SitePreferences>;
+}

package/dist/commands/preferences/site/update.js

@@ -0,0 +1,103 @@
+/*
+ * 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
+ */
+import fs from 'node:fs';
+import { Args, Flags, ux } from '@oclif/core';
+import { PreferencesCommand, buildAssignmentMap, instanceTypeFlag, maskPasswordsFlag, } from '../../../utils/preferences.js';
+import { getApiErrorMessage } from '@salesforce/b2c-tooling-sdk';
+import { t, withDocs } from '../../../i18n/index.js';
+export default class PreferencesSiteUpdate extends PreferencesCommand {
+    static args = {
+        'group-id': Args.string({
+            description: 'Preference group ID',
+            required: true,
+        }),
+    };
+    static description = withDocs(t('commands.preferences.site.update.description', 'Update custom preferences in a site preference group. Pass attribute assignments (KEY=value, KEY:=json, KEY=@file, KEY:=@file, KEY=) or use --file/--body for bulk edits.'), '/cli/preferences.html#update-site');
+    static enableJsonFlag = true;
+    static examples = [
+        '<%= config.bin %> <%= command.id %> CustomGroupId --site-id RefArch c_name=hello c_count:=5 --tenant-id zzxy_prd',
+        '<%= config.bin %> <%= command.id %> CustomGroupId --site-id RefArch c_banner=@banner.html --tenant-id zzxy_prd',
+        '<%= config.bin %> <%= command.id %> CustomGroupId -I staging --site-id RefArch --file prefs.json --tenant-id zzxy_prd',
+    ];
+    static flags = {
+        'instance-type': instanceTypeFlag,
+        'site-id': Flags.string({
+            char: 's',
+            description: 'Site ID',
+            required: true,
+        }),
+        file: Flags.string({
+            char: 'f',
+            description: 'JSON file with preferences body. Custom attributes use the "c_" prefix.',
+            exclusive: ['body'],
+        }),
+        body: Flags.string({
+            description: 'Inline JSON body with preferences. Custom attributes use the "c_" prefix.',
+            exclusive: ['file'],
+        }),
+        'mask-passwords': maskPasswordsFlag,
+    };
+    // Allow variadic KEY=value / KEY:=json assignments after <group-id>.
+    static strict = false;
+    async run() {
+        this.requireOAuthCredentials();
+        const { 'group-id': groupId } = this.args;
+        const { 'instance-type': instanceType, 'site-id': siteId, file, body, 'mask-passwords': maskPasswords } = this.flags;
+        const organizationId = this.getOrganizationId();
+        const { argv } = await this.parse(PreferencesSiteUpdate);
+        const assignments = argv.slice(1);
+        const haveAssignments = assignments.length > 0;
+        if (haveAssignments && (file || body)) {
+            this.error(t('commands.preferences.assignmentsAndBodyExclusive', 'Provide either KEY=value assignments or --file/--body, not both.'));
+        }
+        if (!haveAssignments && !file && !body) {
+            this.error(t('commands.preferences.bodyRequired', 'Provide KEY=value assignments or --file/--body with the preferences to update.'));
+        }
+        let requestBody;
+        if (haveAssignments) {
+            try {
+                requestBody = buildAssignmentMap(assignments);
+            }
+            catch (error) {
+                this.error(error.message);
+            }
+        }
+        else {
+            let raw;
+            if (file) {
+                if (!fs.existsSync(file)) {
+                    this.error(t('commands.preferences.fileNotFound', 'File not found: {{file}}', { file }));
+                }
+                raw = fs.readFileSync(file, 'utf8');
+            }
+            else {
+                raw = body;
+            }
+            try {
+                requestBody = JSON.parse(raw);
+            }
+            catch {
+                this.error(t('commands.preferences.parseError', 'Failed to parse JSON body'));
+            }
+        }
+        const result = await this.preferencesRwClient.PATCH('/organizations/{organizationId}/site-preference-groups/{groupId}/{instanceType}', {
+            params: {
+                path: { organizationId, groupId, instanceType: instanceType },
+                query: { siteId, maskPasswords },
+            },
+            body: requestBody,
+        });
+        if (!result.data) {
+            const message = getApiErrorMessage(result.error, result.response);
+            this.error(t('commands.preferences.site.update.error', 'Failed to update site preference group: {{message}}', { message }));
+        }
+        if (this.jsonEnabled())
+            return result.data;
+        ux.stdout(JSON.stringify(result.data, null, 2) + '\n');
+        return result.data;
+    }
+}
+//# sourceMappingURL=update.js.map

package/dist/commands/preferences/site/update.js.map

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

package/dist/commands/setup/ide/index.js

@@ -10,7 +10,7 @@ import { withDocs } from '../../../i18n/index.js';
  */
 export default class SetupIdeIndex extends BaseCommand {
     static description = withDocs('Set up IDE integrations that consume B2C CLI configuration', '/cli/setup.html#b2c-setup-ide');
-    static examples = ['<%= config.bin %> setup ide prophet'];
+    static examples = ['<%= config.bin %> setup ide tsserver-plugin'];
     async run() {
         await this.config.runCommand('help', ['setup', 'ide']);
     }

package/dist/commands/setup/ide/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/commands/setup/ide/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAC,WAAW,EAAC,MAAM,iCAAiC,CAAC;AAC5D,OAAO,EAAC,QAAQ,EAAC,MAAM,wBAAwB,CAAC;AAEhD;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,aAAc,SAAQ,WAAiC;IAC1E,MAAM,CAAC,WAAW,GAAG,QAAQ,CAC3B,4DAA4D,EAC5D,+BAA+B,CAChC,CAAC;IAEF,MAAM,CAAC,QAAQ,GAAG,CAAC,qCAAqC,CAAC,CAAC;IAE1D,KAAK,CAAC,GAAG;QACP,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;IACzD,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/commands/setup/ide/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAC,WAAW,EAAC,MAAM,iCAAiC,CAAC;AAC5D,OAAO,EAAC,QAAQ,EAAC,MAAM,wBAAwB,CAAC;AAEhD;;GAEG;AACH,MAAM,CAAC,OAAO,OAAO,aAAc,SAAQ,WAAiC;IAC1E,MAAM,CAAC,WAAW,GAAG,QAAQ,CAC3B,4DAA4D,EAC5D,+BAA+B,CAChC,CAAC;IAEF,MAAM,CAAC,QAAQ,GAAG,CAAC,6CAA6C,CAAC,CAAC;IAElE,KAAK,CAAC,GAAG;QACP,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;IACzD,CAAC"}

package/dist/commands/setup/index.js

@@ -17,7 +17,7 @@ export default class SetupIndex extends BaseCommand {
     static examples = [
         '<%= config.bin %> setup --help',
         '<%= config.bin %> setup instance create',
-        '<%= config.bin %> setup ide prophet',
+        '<%= config.bin %> setup ide tsserver-plugin',
     ];
     async run() {
         const hasInstance = this.resolvedConfig.hasB2CInstanceConfig();

package/dist/commands/setup/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/setup/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAC,OAAO,EAAC,MAAM,gCAAgC,CAAC;AACvD,OAAO,EAAC,WAAW,EAAC,MAAM,iCAAiC,CAAC;AAC5D,OAAO,EAAC,QAAQ,EAAC,MAAM,qBAAqB,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,CAAC,OAAO,OAAO,UAAW,SAAQ,WAA8B;IACpE,MAAM,CAAC,WAAW,GAAG,QAAQ,CAC3B,yFAAyF,EACzF,iBAAiB,CAClB,CAAC;IAEF,MAAM,CAAC,QAAQ,GAAG;QAChB,gCAAgC;QAChC,yCAAyC;QACzC,qCAAqC;KACtC,CAAC;IAEF,KAAK,CAAC,GAAG;QACP,MAAM,WAAW,GAAG,IAAI,CAAC,cAAc,CAAC,oBAAoB,EAAE,CAAC;QAC/D,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAEnE,IAAI,CAAC,WAAW,IAAI,KAAK,EAAE,CAAC;YAC1B,MAAM,YAAY,GAAG,MAAM,OAAO,CAAC,uDAAuD,EAAE,EAAC,UAAU,EAAE,IAAI,EAAC,CAAC,CAAC;YAEhH,IAAI,YAAY,EAAE,CAAC;gBACjB,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,uBAAuB,CAAC,CAAC;gBACtD,OAAO;YACT,CAAC;QACH,CAAC;QAED,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAClD,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/commands/setup/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAC,OAAO,EAAC,MAAM,gCAAgC,CAAC;AACvD,OAAO,EAAC,WAAW,EAAC,MAAM,iCAAiC,CAAC;AAC5D,OAAO,EAAC,QAAQ,EAAC,MAAM,qBAAqB,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,CAAC,OAAO,OAAO,UAAW,SAAQ,WAA8B;IACpE,MAAM,CAAC,WAAW,GAAG,QAAQ,CAC3B,yFAAyF,EACzF,iBAAiB,CAClB,CAAC;IAEF,MAAM,CAAC,QAAQ,GAAG;QAChB,gCAAgC;QAChC,yCAAyC;QACzC,6CAA6C;KAC9C,CAAC;IAEF,KAAK,CAAC,GAAG;QACP,MAAM,WAAW,GAAG,IAAI,CAAC,cAAc,CAAC,oBAAoB,EAAE,CAAC;QAC/D,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAEnE,IAAI,CAAC,WAAW,IAAI,KAAK,EAAE,CAAC;YAC1B,MAAM,YAAY,GAAG,MAAM,OAAO,CAAC,uDAAuD,EAAE,EAAC,UAAU,EAAE,IAAI,EAAC,CAAC,CAAC;YAEhH,IAAI,YAAY,EAAE,CAAC;gBACjB,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,uBAAuB,CAAC,CAAC;gBACtD,OAAO;YACT,CAAC;QACH,CAAC;QAED,MAAM,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IAClD,CAAC"}

package/dist/utils/docs/workspace.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared `--workspace` resolution for the `docs search` and `docs read` commands
+ * so both apply the same workspace-aware ranking (parity: a fuzzy `docs read`
+ * should resolve the same top hit that `docs search` ranks first).
+ */
+import { type DetectionResult, type ProjectType } from '@salesforce/b2c-tooling-sdk/discovery';
+/** Minimal logger surface used by {@link resolveDocsWorkspace}. */
+interface WorkspaceLogger {
+    debug(objOrMsg: unknown, msg?: string): void;
+}
+/** Detector signature — matches the SDK's `detectWorkspaceType`; injected so commands can stub it in tests. */
+type DetectWorkspaceType = (cwd: string) => Promise<DetectionResult>;
+/**
+ * Resolves the `--workspace` flag value to concrete project type(s).
+ *
+ * Workspace awareness is ON by default (matching the MCP docs tools): when the
+ * flag is unset — or explicitly `auto` — workspace detection runs and its result
+ * favors the detected workspace's docs. `all` opts out (no preference); an
+ * explicit type (or comma-separated list) is used verbatim without detection.
+ *
+ * Kept dependency-injected (detector/logger/warn) rather than a base-class method
+ * so both docs commands share one implementation and can stub detection in tests.
+ *
+ * @param value - The raw `--workspace` flag value (may be undefined)
+ * @param detect - Workspace detector (the command's stubbable `detectWorkspaceType`)
+ * @param logger - Command logger for debug tracing
+ * @param warn - Callback for surfacing unknown workspace types to the user
+ * @returns Concrete project types to favor, or `undefined` for no preference
+ */
+export declare function resolveDocsWorkspace(value: string | undefined, detect: DetectWorkspaceType, logger: WorkspaceLogger, warn: (message: string) => void): Promise<ProjectType[] | undefined>;
+export {};

package/dist/utils/docs/workspace.js

@@ -0,0 +1,68 @@
+/*
+ * 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
+ */
+/**
+ * Shared `--workspace` resolution for the `docs search` and `docs read` commands
+ * so both apply the same workspace-aware ranking (parity: a fuzzy `docs read`
+ * should resolve the same top hit that `docs search` ranks first).
+ */
+import { PROJECT_TYPES } from '@salesforce/b2c-tooling-sdk/discovery';
+/**
+ * Resolves the `--workspace` flag value to concrete project type(s).
+ *
+ * Workspace awareness is ON by default (matching the MCP docs tools): when the
+ * flag is unset — or explicitly `auto` — workspace detection runs and its result
+ * favors the detected workspace's docs. `all` opts out (no preference); an
+ * explicit type (or comma-separated list) is used verbatim without detection.
+ *
+ * Kept dependency-injected (detector/logger/warn) rather than a base-class method
+ * so both docs commands share one implementation and can stub detection in tests.
+ *
+ * @param value - The raw `--workspace` flag value (may be undefined)
+ * @param detect - Workspace detector (the command's stubbable `detectWorkspaceType`)
+ * @param logger - Command logger for debug tracing
+ * @param warn - Callback for surfacing unknown workspace types to the user
+ * @returns Concrete project types to favor, or `undefined` for no preference
+ */
+export async function resolveDocsWorkspace(value, detect, logger, warn) {
+    if (value === 'all') {
+        logger.debug('Workspace preference disabled (--workspace all); no detection run');
+        return undefined;
+    }
+    if (!value || value === 'auto') {
+        const cwd = process.cwd();
+        const detection = await detect(cwd);
+        const resolved = detection.projectTypes.length > 0 ? detection.projectTypes : undefined;
+        logger.debug({
+            cwd,
+            workspaceFlag: value ?? '(unset, defaults to auto)',
+            matchedPatterns: detection.matchedPatterns,
+            projectTypes: detection.projectTypes,
+            resolved: resolved ?? null,
+        }, resolved
+            ? `Auto-detected workspace: ${resolved.join(', ')}`
+            : 'No workspace detected; using no workspace preference');
+        return resolved;
+    }
+    // Handle one or more comma-separated explicit types. Validate against the
+    // canonical PROJECT_TYPES; warn on (and drop) anything unrecognized.
+    const known = new Set(PROJECT_TYPES);
+    const requested = value
+        .split(',')
+        .map((s) => s.trim().toLowerCase())
+        .filter((s) => s.length > 0);
+    const valid = requested.filter((s) => known.has(s));
+    const invalid = requested.filter((s) => !known.has(s));
+    if (invalid.length > 0) {
+        warn(`Ignoring unknown workspace type(s): ${invalid.join(', ')}`);
+    }
+    if (valid.length === 0) {
+        logger.debug({ requested }, 'No valid workspace types specified; using no workspace preference');
+        return undefined;
+    }
+    logger.debug({ workspace: valid }, 'Using explicitly specified workspace type(s)');
+    return [...new Set(valid)];
+}
+//# sourceMappingURL=workspace.js.map

package/dist/utils/docs/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../../src/utils/docs/workspace.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;;;;GAIG;AACH,OAAO,EAAC,aAAa,EAAyC,MAAM,uCAAuC,CAAC;AAU5G;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,KAAyB,EACzB,MAA2B,EAC3B,MAAuB,EACvB,IAA+B;IAE/B,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;QACpB,MAAM,CAAC,KAAK,CAAC,mEAAmE,CAAC,CAAC;QAClF,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,KAAK,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;QAC1B,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,CAAC;QACpC,MAAM,QAAQ,GAAG,SAAS,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC;QACxF,MAAM,CAAC,KAAK,CACV;YACE,GAAG;YACH,aAAa,EAAE,KAAK,IAAI,2BAA2B;YACnD,eAAe,EAAE,SAAS,CAAC,eAAe;YAC1C,YAAY,EAAE,SAAS,CAAC,YAAY;YACpC,QAAQ,EAAE,QAAQ,IAAI,IAAI;SAC3B,EACD,QAAQ;YACN,CAAC,CAAC,4BAA4B,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;YACnD,CAAC,CAAC,sDAAsD,CAC3D,CAAC;QACF,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,0EAA0E;IAC1E,qEAAqE;IACrE,MAAM,KAAK,GAAG,IAAI,GAAG,CAAS,aAAa,CAAC,CAAC;IAC7C,MAAM,SAAS,GAAG,KAAK;SACpB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;SAClC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAkB,CAAC;IACrE,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACvD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,IAAI,CAAC,uCAAuC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACpE,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,MAAM,CAAC,KAAK,CAAC,EAAC,SAAS,EAAC,EAAE,mEAAmE,CAAC,CAAC;QAC/F,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,CAAC,KAAK,CAAC,EAAC,SAAS,EAAE,KAAK,EAAC,EAAE,8CAA8C,CAAC,CAAC;IACjF,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AAC7B,CAAC"}

package/dist/utils/preferences.d.ts

@@ -0,0 +1,48 @@
+import { Command } from '@oclif/core';
+import { OAuthCommand } from '@salesforce/b2c-tooling-sdk/cli';
+import { type PreferencesClient } from '@salesforce/b2c-tooling-sdk';
+/**
+ * Flag for selecting the SCAPI Preferences instance type.
+ *
+ * Defaults to `development` — a real tier valid for both reads and writes.
+ * `current` is accepted (handy for reads) but the SCAPI Preferences API
+ * rejects it on writes, so it is never the default.
+ */
+export declare const instanceTypeFlag: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+/** Shared `--mask-passwords` (plural) flag used by all instance-scoped preferences commands. */
+export declare const maskPasswordsFlag: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+export type PreferenceAssignmentValue = boolean | null | number | Record<string, unknown> | string | unknown[];
+/**
+ * Parse a single assignment expression for the preferences write commands.
+ *
+ * Operators:
+ *  - `key=value`   string value
+ *  - `key:=json`   raw JSON (number, bool, array, object)
+ *  - `key=@file`   file contents as a string value
+ *  - `key:=@file`  file contents parsed as JSON
+ *  - `key=`        null (clears/unsets the attribute)
+ *
+ * The Preferences API does not coerce types, so callers must use `:=` to send
+ * non-string JSON types.
+ */
+export declare function parsePreferenceAssignment(expr: string): {
+    key: string;
+    value: PreferenceAssignmentValue;
+};
+/** Build a flat `{ [key]: value }` object from assignment expressions. */
+export declare function buildAssignmentMap(exprs: string[]): Record<string, PreferenceAssignmentValue>;
+/**
+ * Base command class for SCAPI Configuration Preferences API commands.
+ *
+ * Provides lazy-initialized read-only and read-write clients with proper
+ * OAuth strategy and configuration.
+ */
+export declare abstract class PreferencesCommand<T extends typeof Command> extends OAuthCommand<T> {
+    private _preferencesClient?;
+    private _preferencesRwClient?;
+    /** Returns a read-only Preferences API client. */
+    protected get preferencesClient(): PreferencesClient;
+    /** Returns a read-write Preferences API client. */
+    protected get preferencesRwClient(): PreferencesClient;
+    private preferencesClientConfig;
+}

package/dist/utils/preferences.js

@@ -0,0 +1,125 @@
+/*
+ * 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
+ */
+import fs from 'node:fs';
+import { Command, Flags } from '@oclif/core';
+import { OAuthCommand } from '@salesforce/b2c-tooling-sdk/cli';
+import { createPreferencesClient, } from '@salesforce/b2c-tooling-sdk';
+import { t } from '../i18n/index.js';
+const INSTANCE_TYPES = ['staging', 'development', 'sandbox', 'production'];
+/**
+ * Flag for selecting the SCAPI Preferences instance type.
+ *
+ * Defaults to `development` — a real tier valid for both reads and writes.
+ * `current` is accepted (handy for reads) but the SCAPI Preferences API
+ * rejects it on writes, so it is never the default.
+ */
+export const instanceTypeFlag = Flags.string({
+    char: 'I',
+    description: 'Instance type. Use "current" (reads only) to target the instance handling the request.',
+    options: [...INSTANCE_TYPES, 'current'],
+    default: 'development',
+});
+/** Shared `--mask-passwords` (plural) flag used by all instance-scoped preferences commands. */
+export const maskPasswordsFlag = Flags.boolean({
+    description: 'Mask values of type password',
+    default: false,
+    allowNo: true,
+});
+/**
+ * Parse a single assignment expression for the preferences write commands.
+ *
+ * Operators:
+ *  - `key=value`   string value
+ *  - `key:=json`   raw JSON (number, bool, array, object)
+ *  - `key=@file`   file contents as a string value
+ *  - `key:=@file`  file contents parsed as JSON
+ *  - `key=`        null (clears/unsets the attribute)
+ *
+ * The Preferences API does not coerce types, so callers must use `:=` to send
+ * non-string JSON types.
+ */
+export function parsePreferenceAssignment(expr) {
+    const jsonIdx = expr.indexOf(':=');
+    const eqIdx = expr.indexOf('=');
+    // ":=" wins only if it appears before the first "="
+    if (jsonIdx !== -1 && (eqIdx === -1 || jsonIdx < eqIdx)) {
+        const key = expr.slice(0, jsonIdx);
+        const rest = expr.slice(jsonIdx + 2);
+        if (!key) {
+            throw new Error(t('commands.preferences.assignment.emptyKey', 'Empty key in assignment: {{expr}}', { expr }));
+        }
+        const raw = rest.startsWith('@') ? readPreferenceFile(rest.slice(1)) : rest;
+        try {
+            return { key, value: JSON.parse(raw) };
+        }
+        catch {
+            throw new Error(t('commands.preferences.assignment.invalidJson', 'Invalid JSON for {{key}} (use := for raw JSON)', { key }));
+        }
+    }
+    if (eqIdx === -1) {
+        throw new Error(t('commands.preferences.assignment.invalidFormat', 'Invalid assignment: {{expr}}. Use KEY=value, KEY:=json, KEY=@file, or KEY:=@file.', { expr }));
+    }
+    const key = expr.slice(0, eqIdx);
+    const rest = expr.slice(eqIdx + 1);
+    if (!key) {
+        throw new Error(t('commands.preferences.assignment.emptyKey', 'Empty key in assignment: {{expr}}', { expr }));
+    }
+    if (rest === '')
+        return { key, value: null };
+    if (rest.startsWith('@'))
+        return { key, value: readPreferenceFile(rest.slice(1)) };
+    return { key, value: rest };
+}
+/** Build a flat `{ [key]: value }` object from assignment expressions. */
+export function buildAssignmentMap(exprs) {
+    const map = {};
+    for (const expr of exprs) {
+        const { key, value } = parsePreferenceAssignment(expr);
+        map[key] = value;
+    }
+    return map;
+}
+function readPreferenceFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+        throw new Error(t('commands.preferences.fileNotFound', 'File not found: {{file}}', { file: filePath }));
+    }
+    return fs.readFileSync(filePath, 'utf8');
+}
+/**
+ * Base command class for SCAPI Configuration Preferences API commands.
+ *
+ * Provides lazy-initialized read-only and read-write clients with proper
+ * OAuth strategy and configuration.
+ */
+export class PreferencesCommand extends OAuthCommand {
+    _preferencesClient;
+    _preferencesRwClient;
+    /** Returns a read-only Preferences API client. */
+    get preferencesClient() {
+        if (!this._preferencesClient) {
+            this._preferencesClient = createPreferencesClient(this.preferencesClientConfig(), this.getOAuthStrategy());
+        }
+        return this._preferencesClient;
+    }
+    /** Returns a read-write Preferences API client. */
+    get preferencesRwClient() {
+        if (!this._preferencesRwClient) {
+            this._preferencesRwClient = createPreferencesClient(this.preferencesClientConfig(), this.getOAuthStrategy(), {
+                readWrite: true,
+            });
+        }
+        return this._preferencesRwClient;
+    }
+    preferencesClientConfig() {
+        const shortCode = this.resolvedConfig.values.shortCode;
+        const tenantId = this.requireTenantId();
+        if (!shortCode) {
+            this.error(t('error.shortCodeRequired', 'SCAPI short code required. Provide --short-code, set SFCC_SHORTCODE, or configure short-code in dw.json.'));
+        }
+        return { shortCode, tenantId };
+    }
+}
+//# sourceMappingURL=preferences.js.map

package/dist/utils/preferences.js.map

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