feat: rename --working-directory to --project-directory (#199)

clavery · web-flow · commit eb3f5d053923 · 2026-02-24T11:57:04.000-05:00
* feat: rename --working-directory to --project-directory

Rename the global --working-directory flag to --project-directory (-d) to
better describe its purpose. The old flag name is kept as a deprecated
alias for backwards compatibility. Primary env var is now
SFCC_PROJECT_DIRECTORY; SFCC_WORKING_DIRECTORY continues to work as a
fallback.

Clear -d shorthand conflicts: job export --data-units uses -u, and
--description/-d removed from am clients create/update and ecdn zones
create.

* chore: downgrade changeset to patch for all packages

* revert: remove markdown-only changes from MCP package
diff --git a/.changeset/rename-working-directory-to-project-directory.md b/.changeset/rename-working-directory-to-project-directory.md
@@ -0,0 +1,7 @@
+---
+'@salesforce/b2c-cli': patch
+'@salesforce/b2c-tooling-sdk': patch
+'@salesforce/b2c-dx-mcp': patch
+---
+
+Rename `--working-directory` flag to `--project-directory` (`-d`). The old flag name `--working-directory` is still accepted as an alias. Primary env var is now `SFCC_PROJECT_DIRECTORY`; `SFCC_WORKING_DIRECTORY` continues to work as a deprecated fallback.
diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md
@@ -57,7 +57,7 @@ You can configure the CLI using environment variables:
 
 | Variable                      | Description                                                    |
 | ----------------------------- | -------------------------------------------------------------- |
-| `SFCC_WORKING_DIRECTORY`      | Project working directory                                      |
+| `SFCC_PROJECT_DIRECTORY`      | Project directory                                              |
 | `SFCC_CONFIG`                 | Path to config file (dw.json format)                           |
 | `SFCC_INSTANCE`               | Instance name from config file                                 |
 | `SFCC_SERVER`                 | The B2C instance hostname                                      |
diff --git a/docs/guide/ide-integration.md b/docs/guide/ide-integration.md
@@ -60,10 +60,10 @@ function toProphetConfig(config) {
 
 function loadDwConfig() {
   try {
-    var workingDirectory = process.env.SFCC_WORKING_DIRECTORY || __dirname || process.cwd();
+    var workingDirectory = process.env.SFCC_PROJECT_DIRECTORY || process.env.SFCC_WORKING_DIRECTORY || __dirname || process.cwd();
     var stdout = childProcess.execFileSync(
       'b2c',
-      ['setup', 'inspect', '--json', '--unmask', '--working-directory', workingDirectory],
+      ['setup', 'inspect', '--json', '--unmask', '--project-directory', workingDirectory],
       {
         encoding: 'utf8',
         stdio: ['ignore', 'pipe', 'pipe'],
diff --git a/packages/b2c-cli/src/commands/am/clients/create.ts b/packages/b2c-cli/src/commands/am/clients/create.ts
@@ -36,7 +36,6 @@ export default class ClientCreate extends AmCommand<typeof ClientCreate> {
       required: true,
     }),
     description: Flags.string({
-      char: 'd',
       description: 'Description of the API client',
     }),
     orgs: Flags.string({
diff --git a/packages/b2c-cli/src/commands/am/clients/update.ts b/packages/b2c-cli/src/commands/am/clients/update.ts
@@ -42,7 +42,6 @@ export default class ClientUpdate extends AmCommand<typeof ClientUpdate> {
       description: 'API client name',
     }),
     description: Flags.string({
-      char: 'd',
       description: 'Description of the API client',
     }),
     organizations: Flags.string({
diff --git a/packages/b2c-cli/src/commands/ecdn/zones/create.ts b/packages/b2c-cli/src/commands/ecdn/zones/create.ts
@@ -36,7 +36,6 @@ export default class EcdnZonesCreate extends EcdnCommand<typeof EcdnZonesCreate>
   static flags = {
     ...EcdnCommand.baseFlags,
     'domain-name': Flags.string({
-      char: 'd',
       description: t('flags.domainName.description', 'Domain name for the storefront zone'),
       required: true,
     }),
diff --git a/packages/b2c-cli/src/commands/job/export.ts b/packages/b2c-cli/src/commands/job/export.ts
@@ -75,7 +75,7 @@ export default class JobExport extends JobCommand<typeof JobExport> {
       description: 'Global data units to export (comma-separated: meta_data,custom_types,etc.)',
     }),
     'data-units': Flags.string({
-      char: 'd',
+      char: 'u',
       description: 'Full data units configuration as JSON string',
     }),
     'keep-archive': Flags.boolean({
diff --git a/packages/b2c-cli/src/commands/scaffold/generate.ts b/packages/b2c-cli/src/commands/scaffold/generate.ts
@@ -62,7 +62,7 @@ export default class ScaffoldGenerate extends BaseCommand<typeof ScaffoldGenerat
   };
 
   async run(): Promise<GenerateResponse | void> {
-    const projectRoot = this.flags['working-directory'] || process.cwd();
+    const projectRoot = this.flags['project-directory'] || process.cwd();
     const response = await executeScaffoldGenerate(
       {
         scaffoldId: this.args.scaffoldId,
diff --git a/packages/b2c-cli/src/commands/scaffold/info.ts b/packages/b2c-cli/src/commands/scaffold/info.ts
@@ -45,7 +45,7 @@ export default class ScaffoldInfo extends BaseCommand<typeof ScaffoldInfo> {
   async run(): Promise<ScaffoldInfoResponse> {
     const {scaffoldId} = this.args;
     const registry = createScaffoldRegistry();
-    const projectRoot = this.flags['working-directory'] || process.cwd();
+    const projectRoot = this.flags['project-directory'] || process.cwd();
 
     const scaffold = await registry.getScaffold(scaffoldId, {
       projectRoot,
diff --git a/packages/b2c-cli/src/commands/scaffold/list.ts b/packages/b2c-cli/src/commands/scaffold/list.ts
@@ -106,7 +106,7 @@ export default class ScaffoldList extends BaseCommand<typeof ScaffoldList> {
     const registry = createScaffoldRegistry();
     const category = this.flags.category as ScaffoldCategory | undefined;
     const source = this.flags.source as ScaffoldSource | undefined;
-    const projectRoot = this.flags['working-directory'] || process.cwd();
+    const projectRoot = this.flags['project-directory'] || process.cwd();
 
     const scaffolds = await registry.getScaffolds({
       category,
diff --git a/packages/b2c-cli/src/commands/scaffold/search.ts b/packages/b2c-cli/src/commands/scaffold/search.ts
@@ -87,7 +87,7 @@ export default class ScaffoldSearch extends BaseCommand<typeof ScaffoldSearch> {
     const {query} = this.args;
     const registry = createScaffoldRegistry();
     const category = this.flags.category as ScaffoldCategory | undefined;
-    const projectRoot = this.flags['working-directory'] || process.cwd();
+    const projectRoot = this.flags['project-directory'] || process.cwd();
 
     const scaffolds = await registry.searchScaffolds(query, {
       category,
diff --git a/packages/b2c-cli/src/commands/setup/ide/prophet.ts b/packages/b2c-cli/src/commands/setup/ide/prophet.ts
@@ -57,6 +57,10 @@ function loadDotEnv() {
 }
 
 function getWorkspaceRoot() {
+  if (process.env.SFCC_PROJECT_DIRECTORY && process.env.SFCC_PROJECT_DIRECTORY.trim()) {
+    return process.env.SFCC_PROJECT_DIRECTORY.trim();
+  }
+
   if (process.env.SFCC_WORKING_DIRECTORY && process.env.SFCC_WORKING_DIRECTORY.trim()) {
     return process.env.SFCC_WORKING_DIRECTORY.trim();
   }
@@ -86,11 +90,11 @@ function getWorkspaceRoot() {
 }
 
 function withWorkingDirectory(args, workingDirectory) {
-  if (!workingDirectory || args.indexOf('--working-directory') !== -1) {
+  if (!workingDirectory || args.indexOf('--project-directory') !== -1 || args.indexOf('--working-directory') !== -1) {
     return args.slice();
   }
 
-  return args.concat(['--working-directory', workingDirectory]);
+  return args.concat(['--project-directory', workingDirectory]);
 }
 
 function pickInspectConfig(parsed) {
@@ -332,8 +336,8 @@ export default class SetupIdeProphet extends BaseCommand<typeof SetupIdeProphet>
     if (this.flags.config) {
       args.push('--config', this.flags.config);
     }
-    if (this.flags['working-directory']) {
-      args.push('--working-directory', this.flags['working-directory']);
+    if (this.flags['project-directory']) {
+      args.push('--project-directory', this.flags['project-directory']);
     }
 
     return args;
diff --git a/packages/b2c-cli/test/commands/setup/ide/prophet.test.ts b/packages/b2c-cli/test/commands/setup/ide/prophet.test.ts
@@ -39,7 +39,7 @@ describe('setup ide prophet', () => {
       force: false,
       instance: undefined,
       config: undefined,
-      'working-directory': undefined,
+      'project-directory': undefined,
       ...flags,
     };
 
@@ -89,6 +89,7 @@ describe('setup ide prophet', () => {
       expect(content).to.include('support dwJson multi-config in prophet');
       expect(content).to.include("typeof workspace !== 'undefined'");
       expect(content).to.include("if (typeof __dirname === 'string' && __dirname)");
+      expect(content).to.include('process.env.SFCC_PROJECT_DIRECTORY');
       expect(content).to.include('process.env.SFCC_WORKING_DIRECTORY');
       expect(content).to.include('try {');
       expect(content).to.include('return {};');
@@ -137,7 +138,7 @@ describe('setup ide prophet', () => {
         output: outputPath,
         instance: 'staging',
         config: '/tmp/config/dw.json',
-        'working-directory': '/tmp/workspace',
+        'project-directory': '/tmp/workspace',
       });
 
       await runSilent(() => command.run());
@@ -147,7 +148,7 @@ describe('setup ide prophet', () => {
       expect(content).to.include('staging');
       expect(content).to.include('--config');
       expect(content).to.include('/tmp/config/dw.json');
-      expect(content).to.include('--working-directory');
+      expect(content).to.include('--project-directory');
       expect(content).to.include('/tmp/workspace');
     });
   });
diff --git a/packages/b2c-dx-mcp/src/commands/mcp.ts b/packages/b2c-dx-mcp/src/commands/mcp.ts
@@ -48,21 +48,21 @@
  * ### Global Flags (inherited from BaseCommand)
  * | Flag | Env Variable | Description |
  * |------|--------------|-------------|
- * | `--working-directory` | `SFCC_WORKING_DIRECTORY` | Project working directory (see note below) |
+ * | `--project-directory` | `SFCC_PROJECT_DIRECTORY` | Project directory (see note below) |
  * | `--config` | `SFCC_CONFIG` | Path to dw.json config file (auto-discovered if not provided) |
  * | `--instance` | `SFCC_INSTANCE` | Instance name from configuration file |
  * | `--log-level` | `SFCC_LOG_LEVEL` | Set logging verbosity (trace, debug, info, warn, error, silent) |
  * | `--debug` | `SFCC_DEBUG` | Enable debug logging |
  * | `--json` | - | Output logs as JSON lines |
  * | `--lang` | - | Language for messages |
  *
- * **Note on `--working-directory`**: Many MCP clients (Cursor, Claude Desktop) spawn servers from the
+ * **Note on `--project-directory`**: Many MCP clients (Cursor, Claude Desktop) spawn servers from the
  * user's home directory (`~`) rather than the project directory. This flag is used for:
  * - Auto-discovery (detecting project type when no `--toolsets` or `--tools` are provided)
  * - Scaffolding tools (creating files in the correct project location)
  * - Any tool that needs to operate on the project directory
  *
- * Use `--working-directory` or `SFCC_WORKING_DIRECTORY` env var to specify the actual project path.
+ * Use `--project-directory` or `SFCC_PROJECT_DIRECTORY` env var to specify the actual project path.
  *
  * ## Configuration
  *
@@ -258,7 +258,7 @@ export default class McpServerCommand extends BaseCommand<typeof McpServerComman
    * Priority (highest to lowest):
    * 1. CLI flags (--server, --username, --api-key, etc.)
    * 2. Environment variables (SFCC_SERVER, SFCC_USERNAME, SFCC_MRT_API_KEY, etc.)
-   * 3. dw.json file (via --config flag or auto-discovered from --working-directory)
+   * 3. dw.json file (via --config flag or auto-discovered from --project-directory)
    * 4. ~/.mobify file (for MRT API key)
    */
   protected override loadConfiguration(): ResolvedB2CConfig {
@@ -327,7 +327,7 @@ export default class McpServerCommand extends BaseCommand<typeof McpServerComman
       allowNonGaTools: this.flags['allow-non-ga-tools'],
       configPath: this.flags.config,
       // Working directory for auto-discovery. oclif handles flag with env fallback.
-      workingDirectory: this.flags['working-directory'],
+      workingDirectory: this.flags['project-directory'],
     };
 
     // Add toolsets to telemetry attributes
diff --git a/packages/b2c-dx-mcp/src/registry.ts b/packages/b2c-dx-mcp/src/registry.ts
@@ -118,16 +118,16 @@ export function createToolRegistry(loadServices: () => Services): ToolRegistry {
 async function performAutoDiscovery(flags: StartupFlags, reason: string): Promise<Toolset[]> {
   const logger = getLogger();
 
-  // Working directory from --working-directory flag or SFCC_WORKING_DIRECTORY env var
+  // Working directory from --project-directory flag or SFCC_PROJECT_DIRECTORY env var
   const workingDirectory = flags.workingDirectory ?? process.cwd();
 
   // Warn if working directory wasn't explicitly configured
   if (!flags.workingDirectory) {
     logger.warn(
       {cwd: workingDirectory},
-      'No --working-directory flag or SFCC_WORKING_DIRECTORY env var provided. ' +
+      'No --project-directory flag or SFCC_PROJECT_DIRECTORY env var provided. ' +
         'MCP clients like Cursor and Claude Desktop often spawn servers from ~ instead of the project directory. ' +
-        'Set --working-directory or SFCC_WORKING_DIRECTORY for reliable auto-discovery.',
+        'Set --project-directory or SFCC_PROJECT_DIRECTORY for reliable auto-discovery.',
     );
   }
 
diff --git a/packages/b2c-dx-mcp/src/tools/page-designer-decorator/analyzer.ts b/packages/b2c-dx-mcp/src/tools/page-designer-decorator/analyzer.ts
@@ -603,7 +603,7 @@ export function resolveComponent(input: string, workspaceRoot: string, searchPat
         `Full path checked: ${fullPath}\n\n` +
         `Tips:\n` +
         `  1. Use component name instead (e.g., "ProductCard") for automatic discovery\n` +
-        `  2. If components are in a different repo, set --working-directory flag or SFCC_WORKING_DIRECTORY env var`,
+        `  2. If components are in a different repo, set --project-directory flag or SFCC_PROJECT_DIRECTORY env var`,
     );
   }
 
@@ -630,7 +630,7 @@ export function resolveComponent(input: string, workspaceRoot: string, searchPat
         `  1. Provide full path: component: "src/components/ProductCard.tsx"\n` +
         `  2. Add custom search: searchPaths: ["packages/retail/src"]\n` +
         `  3. Check component name spelling and casing\n` +
-        `  4. If components are in a different repo, set --working-directory flag or SFCC_WORKING_DIRECTORY env var`,
+        `  4. If components are in a different repo, set --project-directory flag or SFCC_PROJECT_DIRECTORY env var`,
     );
   }
 
diff --git a/packages/b2c-dx-mcp/test/commands/mcp.test.ts b/packages/b2c-dx-mcp/test/commands/mcp.test.ts
@@ -77,10 +77,10 @@ describe('McpServerCommand', () => {
       expect(flag.env).to.equal('SFCC_MRT_API_KEY');
     });
 
-    it('should define working-directory flag with env var support', () => {
-      const flag = McpServerCommand.flags['working-directory'];
+    it('should define project-directory flag with env var support', () => {
+      const flag = McpServerCommand.flags['project-directory'];
       expect(flag).to.not.be.undefined;
-      expect(flag.env).to.equal('SFCC_WORKING_DIRECTORY');
+      expect(flag.env).to.equal('SFCC_PROJECT_DIRECTORY');
     });
   });
 
diff --git a/packages/b2c-tooling-sdk/src/cli/base-command.ts b/packages/b2c-tooling-sdk/src/cli/base-command.ts
@@ -95,9 +95,12 @@ export abstract class BaseCommand<T extends typeof Command> extends Command {
       env: 'SFCC_INSTANCE',
       helpGroup: 'GLOBAL',
     }),
-    'working-directory': Flags.string({
-      description: 'Project working directory',
-      env: 'SFCC_WORKING_DIRECTORY',
+    'project-directory': Flags.string({
+      char: 'd',
+      aliases: ['working-directory'],
+      description: 'Project directory',
+      env: 'SFCC_PROJECT_DIRECTORY',
+      default: async () => process.env.SFCC_WORKING_DIRECTORY || undefined,
       helpGroup: 'GLOBAL',
     }),
     'extra-query': Flags.string({
@@ -318,7 +321,7 @@ export abstract class BaseCommand<T extends typeof Command> extends Command {
     return {
       instance: this.flags.instance,
       configPath: this.flags.config,
-      workingDirectory: this.flags['working-directory'],
+      workingDirectory: this.flags['project-directory'],
     };
   }
 

Original file line number	Diff line number	Diff line change
`@@ -62,7 +62,7 @@ export default class ScaffoldGenerate extends BaseCommand<typeof ScaffoldGenerat`
`62`	`62`	`};`
`63`	`63`
`64`	`64`	`async run(): Promise<GenerateResponse \| void> {`
`65`		`- const projectRoot = this.flags['working-directory'] \|\| process.cwd();`
	`65`	`+ const projectRoot = this.flags['project-directory'] \|\| process.cwd();`
`66`	`66`	`const response = await executeScaffoldGenerate(`
`67`	`67`	`{`
`68`	`68`	`scaffoldId: this.args.scaffoldId,`