feat: accept 15-char package version IDs in bundle definition file

sf-haulakh · claude · sf-haulakh · commit 06ee1370b606 · 2026-04-22T12:25:42.000+05:30
This change enables the sf package bundle version create command to
accept both 15-character and 18-character Salesforce package version
IDs (04t IDs) in the bundle definition file.

Previously, only 18-character IDs were supported, and providing a
15-character ID would result in an error: "No package version found
with alias: 04t5f000000WM9y"

Changes:
- Added convertTo18CharId() function to convert 15-char IDs to 18-char
  using the standard Salesforce ID checksum algorithm
- Added normalizePackageVersionIds() function to recursively search
  and normalize all packageVersion fields in the definition JSON
- Modified the run() method to read, normalize, and create a temporary
  definition file when 15-char IDs are detected
- Proper cleanup of temporary files in finally block
- Added comprehensive unit tests for ID normalization scenarios

Also added CLAUDE.md with codebase documentation for future AI instances.

Fixes: W-21383062

Co-Authored-By: Claude Sonnet 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,161 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is `@salesforce/plugin-packaging`, a Salesforce CLI plugin that provides commands for the Salesforce Packaging Platform. It supports both second-generation managed packages (2GP) and first-generation packages (1GP), as well as unlocked packages and package bundles.
+
+The plugin is built using:
+- **oclif** - CLI framework
+- **TypeScript** with strict ESM configuration
+- **@salesforce/packaging** library (v4.22.8) - Core packaging functionality
+- **@salesforce/sf-plugins-core** - Salesforce CLI plugin utilities
+
+## Architecture
+
+### Command Structure
+
+Commands follow the oclif pattern and are organized by topic:
+- `src/commands/package/` - Second-generation package commands
+- `src/commands/package/version/` - Package version management
+- `src/commands/package/bundle/` - Package bundle commands
+- `src/commands/package1/` - First-generation package commands
+
+Each command extends `SfCommand<T>` from `@salesforce/sf-plugins-core` and:
+- Defines flags using the `Flags` utility (with deprecation support for aliases)
+- Uses the `@salesforce/packaging` library for business logic
+- Loads messages from `.md` files in the `messages/` directory
+- Returns strongly-typed results
+
+### Key Patterns
+
+1. **Hub Flag Pattern**: Most commands require a Dev Hub connection using `requiredHubFlag` from `src/utils/hubFlag.ts`
+
+2. **Message Loading**: Commands load internationalized messages using:
+   ```typescript
+   Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+   const messages = Messages.loadMessages('@salesforce/plugin-packaging', 'message_file_name');
+   ```
+
+3. **Packaging Library Integration**: Business logic delegates to the `@salesforce/packaging` library:
+   ```typescript
+   const result = await Package.create(
+     flags['target-dev-hub'].getConnection(flags['api-version']),
+     this.project!,
+     options
+   );
+   ```
+
+4. **JSON Schemas**: Each command has a corresponding JSON schema in `schemas/` for output validation
+
+## Development Commands
+
+### Setup
+```bash
+yarn install              # Install dependencies
+yarn build               # Compile TypeScript and run linting
+yarn clean-all           # Clean everything including node_modules
+```
+
+### Building
+```bash
+yarn compile             # Compile TypeScript only
+yarn lint               # Run ESLint
+yarn build              # Compile + lint
+```
+
+### Testing
+```bash
+yarn test               # Run unit tests (mocha)
+yarn test:nuts          # Run NUTs (non-unit tests) - requires Dev Hub
+yarn test:nuts:package  # Run package-specific NUTs
+yarn test:nuts:package1 # Run 1GP package NUTs
+```
+
+**Important**: For 1GP NUTs, set `ONEGP_TESTKIT_AUTH_URL` environment variable for target org authentication.
+
+### Running Commands Locally
+```bash
+# Direct execution (must compile first)
+./bin/run.js package:create --help
+
+# Link to sf CLI
+sf plugins:link .
+sf package create --help
+```
+
+### Formatting
+```bash
+yarn format             # Format code with prettier
+```
+
+## Testing Strategy
+
+### Unit Tests
+- Located in `test/commands/` mirroring `src/commands/` structure
+- Named with `.test.ts` suffix
+- Run with mocha using ts-node
+- Use stubs/mocks for external dependencies
+- Aim for 95%+ code coverage
+
+### NUTs (Non-Unit Tests)
+- Named with `.nut.ts` suffix
+- Use `@salesforce/cli-plugins-testkit` framework
+- Run against real Salesforce orgs (require authenticated Dev Hub)
+- Test end-to-end command functionality
+- Run in parallel with `--jobs 20` flag
+
+## Linking the Packaging Library
+
+When developing against a local version of `@salesforce/packaging`:
+
+1. In the packaging library: `yarn link`
+2. In this plugin: `yarn link "@salesforce/packaging"`
+3. Make changes in packaging library and rebuild
+4. Test in this plugin
+
+See [packaging library docs](https://github.com/forcedotcom/packaging/blob/main/DEVELOPING.md#linking-to-the-packaging-plugin) for details.
+
+## Commit and Release Process
+
+### Commit Messages
+Follow [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/):
+- `fix:` - Patch version bump
+- `feat:` - Minor version bump  
+- Breaking changes require coordination with CLI team for major version bump
+
+Commit messages are enforced via commitlint and husky pre-commit hooks.
+
+### Release Process
+- PRs merged to `main` automatically publish to npmjs
+- Version bump is determined by commit message prefixes
+- README is auto-updated via `yarn version` script (runs `oclif readme`)
+
+## Key Configuration Files
+
+- `package.json` - Dependencies, scripts, oclif configuration
+- `tsconfig.json` - Extends `@salesforce/dev-config/tsconfig-strict-esm`
+- `.mocharc.json` - Mocha test configuration
+- `.nycrc` - Code coverage configuration
+- `wireit` config in `package.json` - Build orchestration and caching
+
+## Command Development Checklist
+
+When adding a new command:
+
+1. Create command file in appropriate `src/commands/` subdirectory
+2. Create message file in `messages/` (name matches command path with underscores)
+3. Add JSON schema in `schemas/` for output validation
+4. Write unit tests in `test/commands/` mirroring source structure
+5. Write NUTs if command interacts with Salesforce APIs
+6. Update command snapshot: `./bin/dev.js snapshot:compare`
+7. Regenerate README: `yarn version`
+
+## Important Notes
+
+- All package commands require a Dev Hub org (`--target-dev-hub` or `target-dev-hub` config)
+- Package version creation is async - commands return a request ID to poll for status
+- Installation keys can be required or bypassed (never both)
+- Second-generation packages require project context (`requiresProject: true`)
+- ESM modules are used throughout (`"type": "module"` in package.json)
diff --git a/src/commands/package/bundle/version/create.ts b/src/commands/package/bundle/version/create.ts
@@ -24,12 +24,78 @@ import {
 import { Messages, Lifecycle } from '@salesforce/core';
 import { camelCaseToTitleCase, Duration } from '@salesforce/kit';
 import { requiredHubFlag } from '../../../../utils/hubFlag.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
 
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 // TODO: Update messages
 const messages = Messages.loadMessages('@salesforce/plugin-packaging', 'bundle_version_create');
 export type BundleVersionCreate = BundleSObjects.PackageBundleVersionCreateRequestResult;
 
+/**
+ * Converts a 15-character Salesforce ID to its 18-character equivalent.
+ * If the ID is already 18 characters or not a valid Salesforce ID format, returns it unchanged.
+ *
+ * @param id - The Salesforce ID to convert
+ * @returns The 18-character Salesforce ID
+ */
+function convertTo18CharId(id: string): string {
+  // If already 18 chars or not 15 chars, return as-is
+  if (!id || id.length !== 15) {
+    return id;
+  }
+
+  // Salesforce ID conversion algorithm
+  // For each chunk of 5 characters, calculate a checksum character
+  const suffix: string[] = [];
+
+  for (let i = 0; i < 3; i++) {
+    let flags = 0;
+    for (let j = 0; j < 5; j++) {
+      const char = id.charAt(i * 5 + j);
+      // Check if character is uppercase (A-Z have higher ASCII values than lowercase)
+      if (char >= 'A' && char <= 'Z') {
+        flags += 1 << j;
+      }
+    }
+    // Convert flags to a base-32 character
+    suffix.push('ABCDEFGHIJKLMNOPQRSTUVWXYZ012345'.charAt(flags));
+  }
+
+  return id + suffix.join('');
+}
+
+/**
+ * Normalizes package version IDs in a bundle definition object.
+ * Converts any 15-character package version IDs to 18-character format.
+ *
+ * @param obj - The object to normalize (can be nested)
+ * @returns The normalized object
+ */
+function normalizePackageVersionIds(obj: unknown): unknown {
+  if (typeof obj !== 'object' || obj === null) {
+    return obj;
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => normalizePackageVersionIds(item));
+  }
+
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (key === 'packageVersion' && typeof value === 'string' && value.startsWith('04t')) {
+      // Normalize package version IDs (04t prefix)
+      result[key] = convertTo18CharId(value);
+    } else if (typeof value === 'object') {
+      result[key] = normalizePackageVersionIds(value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
 export class PackageBundlesCreate extends SfCommand<BundleSObjects.PackageBundleVersionCreateRequestResult> {
   public static readonly hidden = true;
   public static state = 'beta';
@@ -81,11 +147,38 @@ export class PackageBundlesCreate extends SfCommand<BundleSObjects.PackageBundle
       minorVersion = versionParts[1] || '';
     }
 
+    // Read and normalize the definition file to handle 15-char package version IDs
+    let definitionFilePath = flags['definition-file'];
+    let tempFilePath: string | undefined;
+
+    try {
+      // Read the definition file
+      const definitionContent = await fs.promises.readFile(definitionFilePath, 'utf8');
+      const definitionJson = JSON.parse(definitionContent) as unknown;
+
+      // Normalize any 15-character package version IDs to 18-character format
+      const normalizedJson = normalizePackageVersionIds(definitionJson);
+
+      // Check if any normalization occurred by comparing stringified versions
+      if (JSON.stringify(definitionJson) !== JSON.stringify(normalizedJson)) {
+        // Create a temporary file with normalized content
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'sf-bundle-'));
+        tempFilePath = path.join(tempDir, 'normalized-definition.json');
+        await fs.promises.writeFile(tempFilePath, JSON.stringify(normalizedJson, null, 2), 'utf8');
+        definitionFilePath = tempFilePath;
+        this.debug(`Normalized package version IDs in definition file. Using temporary file: ${tempFilePath}`);
+      }
+    } catch (error) {
+      // If reading/parsing fails, let the packaging library handle the error
+      // This preserves the original error messages for invalid JSON, missing files, etc.
+      this.debug(`Could not normalize definition file: ${error instanceof Error ? error.message : String(error)}`);
+    }
+
     const options: BundleVersionCreateOptions = {
       connection: flags['target-dev-hub'].getConnection(flags['api-version']),
       project: this.project!,
       PackageBundle: flags.bundle,
-      BundleVersionComponentsPath: flags['definition-file'],
+      BundleVersionComponentsPath: definitionFilePath,
       Description: flags.description,
       MajorVersion: majorVersion,
       MinorVersion: minorVersion,
@@ -134,6 +227,20 @@ export class PackageBundlesCreate extends SfCommand<BundleSObjects.PackageBundle
         this.spinner.stop();
       }
       throw error;
+    } finally {
+      // Clean up temporary file if it was created
+      if (tempFilePath) {
+        try {
+          const tempDir = path.dirname(tempFilePath);
+          await fs.promises.rm(tempDir, { recursive: true, force: true });
+          this.debug(`Cleaned up temporary definition file: ${tempFilePath}`);
+        } catch (cleanupError) {
+          // Log but don't fail if cleanup fails
+          this.debug(
+            `Failed to clean up temporary file: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`
+          );
+        }
+      }
     }
 
     // Stop spinner only if it was started - stop it cleanly without a message
diff --git a/test/commands/bundle/packageBundleVersionCreate.test.ts b/test/commands/bundle/packageBundleVersionCreate.test.ts
