Skip to content

AGENTS.md

Latest commit

 

History

History
204 lines (142 loc) · 8.91 KB

AGENTS.md

File metadata and controls

204 lines (142 loc) · 8.91 KB

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

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:

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.

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
  • a pull request can have multiple changesets; separate files for separate changes
  • 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-cli, @salesforce/b2c-tooling-sdk, @salesforce/b2c-dx-mcp, @salesforce/mrt-utilities, b2c-vs-extension, @salesforce/b2c-dx-docs, @salesforce/b2c-agent-plugins

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 agent skills/plugins in skills/ (adding or updating skill content, adding a new plugin), target @salesforce/b2c-agent-plugins