B2C CLI

This is a monorepo project with the following packages:

• ./packages/b2c-cli - the command line interface built with oclif
• ./packages/b2c-tooling-sdk - the SDK/library for B2C Commerce operations; supports the CLI and can be used standalone
• ./packages/b2c-dx-mcp - Model Context Protocol server; also built with oclif
• ./packages/b2c-vs-extension - VS Code extension (not published to npm; packaged as VSIX and versioned via git tags)
• ./docs - documentation site (private @salesforce/b2c-dx-docs workspace package; not published to npm)

Common Commands

# Install dependencies
pnpm install

# Build all packages
pnpm run build

# Build specific package
pnpm --filter @salesforce/b2c-cli run build
pnpm --filter @salesforce/b2c-tooling-sdk run build

# Dev mode for CLI (uses source files directly)
pnpm --filter @salesforce/b2c-cli run dev
# or using convenience script
./cli

Commands for Coding Agents

These commands produce condensed output optimized for AI coding agents:

# Run tests (minimal output - only failures + summary)
pnpm run test:agent

# Run tests for specific package
pnpm --filter @salesforce/b2c-cli run test:agent
pnpm --filter @salesforce/b2c-tooling-sdk run test:agent

# Lint (errors only, no warnings); Be sure to run lint before committing or writing a changeset
pnpm run lint:agent

# Type-check (single-line errors, no color)
pnpm run typecheck:agent

# Format check (lists only files needing formatting)
pnpm run -r format:check

Verbose Commands (Debugging/CI)

Use these for detailed output during debugging or in CI pipelines:

# Run tests with full output and coverage
pnpm run test

# Run tests for specific package
pnpm --filter @salesforce/b2c-cli run test
pnpm --filter @salesforce/b2c-tooling-sdk run test

# Format code with prettier
pnpm run -r format

# Lint with full output
pnpm run -r lint

Copyright Header

All TypeScript source files must include this exact copyright header block:

/*
 * 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
 */

The header is enforced by eslint via eslint-plugin-header. The canonical definition is in eslint.config.mjs (root) as copyrightHeader.

Setup/Packaging

• use pnpm over npm for package management
• shared dependencies are managed via pnpm catalogs — versions are defined once in the catalog: section of pnpm-workspace.yaml and referenced as "catalog:" in each package.json. When adding or updating a dependency that is shared across packages, update the catalog entry rather than individual package.json files.
• the pnpm run test commands also run the linter after tests
• use pnpm run -r format (or individually in packages) to format code with prettier
• use exports field in package.json files to define public API surface for packages; use development field for nodejs --conditions for development ergonomics (packages/b2c-cli/bin/dev.js will use this condition)

Documentation

• Update docs in ./docs/ folder and relevant skills in ./skills/b2c-cli/skills/ when updating or adding CLI commands.
• When adding new SDK modules, update docs/typedoc.json entry points to include the new module's barrel file so API docs are generated.

See documentation skill for details on updating user guides, CLI reference, and API docs.

# Run docs dev server (from project root)
pnpm run docs:dev

# Build docs for production (stable mode — root base path)
pnpm run docs:build

# Build docs in dev mode (/dev/ base path)
IS_DEV_BUILD=true pnpm run docs:build

Docs workspace package

The ./docs directory is a private workspace package (@salesforce/b2c-dx-docs) with a dependency on @salesforce/b2c-tooling-sdk. This exists to support doc-only releases and changelog tracking via changesets, not for npm publishing. It has no build script — pnpm -r run build skips it.

Deployed URL structure: stable/released docs are served at the root URL, dev docs (from main) live at /dev/.

Doc-only releases: to release documentation changes without bumping CLI/SDK/MCP, create a changeset that targets only the docs package:

---
'@salesforce/b2c-dx-docs': patch
---

Improved authentication guide with step-by-step examples

This produces a docs@<version> tag and triggers a docs rebuild on merge of the version PR.

Automatic cascade: because the docs package depends on the SDK, when the SDK version is bumped by a changeset, updateInternalDependencies: "patch" auto-bumps the docs version too — triggering a docs rebuild (correct since API docs are generated from the SDK).

Logging

• when logging use the logger instance from @salesforce/b2c-tooling-sdk/logger package
• CLI commands have access to this logger via this.log method from oclif Command class
• CLI commands can write directly to stdout/stderr if their primary purpose is to output or stream data

MCP Development

For MCP tools, resources, and workflow skills, see the MCP development skill.

CLI Command Development

See CLI command development skill for patterns.

Claude Code Skills

User-facing skills (for CLI users): ./skills/b2c-cli/skills/ - update when modifying CLI commands.

Developer skills (for contributors): ./.claude/skills/ - covers:

• CLI command development - oclif commands, flags, table output
• SDK module development - modules, exports, barrel files
• API client development - OpenAPI clients, OAuth scopes, SCAPI patterns
• Testing - Mocha, Chai, MSW patterns
• Documentation - user guides, CLI reference, API docs

Pull Requests

GUS work-item prefixes in PR titles must include @, for example @W-24337127: Support OpenShell sandboxes.

Pre-Commit Checks

Before committing code, always run lint to catch formatting and style issues:

pnpm run lint:agent

This catches prettier formatting, import ordering, class member ordering (perfectionist/sort-classes), and other issues that will fail CI.

Tooling documentation index

When you add/remove/rename a CLI command or change the MRT docs (docs/cli/) or user-facing skills (skills/b2c-cli/), regenerate the checked-in tooling documentation index (packages/b2c-tooling-sdk/data/tooling/index.json) and commit the result:

# Regenerate the index (run after doc/command changes)
pnpm --filter @salesforce/b2c-tooling-sdk run generate:tooling-index

# Verify it is up to date (this is what CI runs)
pnpm --filter @salesforce/b2c-tooling-sdk run check:tooling-index

A stale index fails CI's "Verify tooling documentation index" step first, which then skips the "Build packages" step — surfacing as a cascade of unrelated import/no-unresolved errors across packages. If you see that pattern, regenerate the index rather than chasing the import errors.

Testing

See testing skill for patterns on writing tests with Mocha, Chai, and MSW.

Stdout in tests: Command tests must not leak output to the console. stubCommandConfigAndLogger() silences command.log, command.logToStderr, and ux.stdout automatically. For other cases, use runSilent() from test/helpers/test-setup.ts.

Changesets

This project uses Changesets for version management with independent per-package versioning. Each package versions independently based on its own changesets.

How it works:

• A changeset affecting only the SDK bumps only the SDK version
• Packages that depend on a bumped package get an automatic patch bump (via updateInternalDependencies: "patch") — e.g., if SDK bumps, CLI, MCP, and Docs all auto-get a patch bump
• Only packages with a newer version than what's on npm get published (docs package is private and uses git tags instead)
• A changeset targeting only @salesforce/b2c-dx-docs triggers a doc-only release — no npm packages are published, just a docs@<version> tag and docs rebuild

Changeset guidelines:

• Create a changeset for any user-facing changes (features, bug fixes); typically in new pull requests
• Use separate changesets for distinct user-facing features or fixes in a pull request. Describe the final change relative to the base branch, not the branch's implementation history; fold follow-up work on an unreleased feature into that feature's changeset.
• Only list directly-changed packages in changeset frontmatter — do not include dependent packages (they get auto-bumped)
• Select the appropriate semver bump: patch (bug fixes) or minor (new features)
• Use major for breaking changes that require consumers to update their code
• Good changesets explain:
  • WHAT the change is
  • WHY the change was made
  • HOW a consumer should update their code
• Good changesets are brief and user-focused (not contributor); they are generally 1 line or two; The content of the changeset is used in CHANGELOG and release notes. You do not need to list internal implementation details or all details of commands; just the high level summary for users.

Valid changeset packages: @salesforce/b2c-api-schemas, @salesforce/b2c-cli, @salesforce/b2c-tooling-sdk, @salesforce/b2c-dx-mcp, @salesforce/mrt-utilities, b2c-vs-extension, @salesforce/b2c-dx-docs, @salesforce/b2c-agent-plugins, @salesforce/b2c-tooling-sdk-python

Create a changeset file directly in .changeset/ with a unique filename (e.g., descriptive-change-name.md):

---
'@salesforce/b2c-cli': patch
'@salesforce/b2c-tooling-sdk': patch
---

Description of the change explaining WHAT, WHY, and HOW to update

• Include only the packages that were directly modified
• For doc-only changes, target @salesforce/b2c-dx-docs instead of the CLI/SDK/MCP packages
• For changes to the GitHub Actions (action.yml, actions/), target @salesforce/b2c-cli — Actions are released with each CLI publish at the same version
• For changes to agent skills/plugins in skills/ (adding or updating skill content, adding a new plugin), target @salesforce/b2c-agent-plugins
• For changes to the Python SDK port (python/b2c-tooling-sdk/), target @salesforce/b2c-tooling-sdk-python — this is a private, unpublished package.json used only so Changesets can version and changelog that package; the bumped version flows into pyproject.toml/version.py via scripts/sync-python-sdk-version.mjs, but the actual release (tagging, pushing) is a separate manual step (see python/b2c-tooling-sdk/RELEASE.md), not automated by this repo's CI