@simplysf/simply-package 2.9.0 → 2.10.1

package/README.md

@@ -23,6 +23,7 @@ This package is part of the [`@simplysf/simply`](https://github.com/SimplySF/sim
 - [`sf simply package dependencies install`](#sf-simply-package-dependencies-install)
 - [`sf simply package dependencies manage`](#sf-simply-package-dependencies-manage)
 - [`sf simply package version cleanup`](#sf-simply-package-version-cleanup)
+- [`sf simply package version get`](#sf-simply-package-version-get)
 
 ## `sf simply package dependencies install`
 
@@ -156,7 +157,7 @@ FLAG DESCRIPTIONS
     Packages not listed here use --retry-attempts.
 ```
 
-_See code: [lib/commands/simply/package/dependencies/install.js](https://github.com/SimplySF/simply-node/blob/@simplysf/simply-package@2.8.14/packages/simply-package/lib/commands/simply/package/dependencies/install.js)_
+_See code: [lib/commands/simply/package/dependencies/install.js](https://github.com/SimplySF/simply-node/blob/@simplysf/simply-package@2.9.0/packages/simply-package/lib/commands/simply/package/dependencies/install.js)_
 
 ## `sf simply package dependencies manage`
 
@@ -215,7 +216,7 @@ FLAG DESCRIPTIONS
     version without interactive prompts. Mutually exclusive with --update-to-latest.
 ```
 
-_See code: [lib/commands/simply/package/dependencies/manage.js](https://github.com/SimplySF/simply-node/blob/@simplysf/simply-package@2.8.14/packages/simply-package/lib/commands/simply/package/dependencies/manage.js)_
+_See code: [lib/commands/simply/package/dependencies/manage.js](https://github.com/SimplySF/simply-node/blob/@simplysf/simply-package@2.9.0/packages/simply-package/lib/commands/simply/package/dependencies/manage.js)_
 
 ## `sf simply package version cleanup`
 
@@ -269,234 +270,67 @@ FLAG DESCRIPTIONS
     does not match this matcher is deleted. Mutually exclusive with --matcher.
 ```
 
-_See code: [lib/commands/simply/package/version/cleanup.js](https://github.com/SimplySF/simply-node/blob/@simplysf/simply-package@2.8.14/packages/simply-package/lib/commands/simply/package/version/cleanup.js)_
-<!-- commandsstop -->
+_See code: [lib/commands/simply/package/version/cleanup.js](https://github.com/SimplySF/simply-node/blob/@simplysf/simply-package@2.9.0/packages/simply-package/lib/commands/simply/package/version/cleanup.js)_
 
-- [`sf simply package dependencies install`](#sf-simply-package-dependencies-install)
-- [`sf simply package dependencies manage`](#sf-simply-package-dependencies-manage)
-- [`sf simply package version cleanup`](#sf-simply-package-version-cleanup)
+## `sf simply package version get`
 
-## `sf simply package dependencies install`
-
-Install package dependencies for a Salesforce project.
+Get a package version from sfdx-project.json.
 
 ```
 USAGE
-  $ sf simply package dependencies install -o <value> [--json] [--flags-dir <value>] [-a all|package] [--api-version <value>] [-z
-    <value>] [-i All|Delta|Upgrade] [-k <value>...] [-r] [--output-file <value>] [-b <value>] [-s AllUsers|AdminsOnly]
-    [-v <value>] [-t DeprecateOnly|Mixed|Delete] [-w <value>]
+  $ sf simply package version get -p <value> [--json] [--flags-dir <value>] [-d <value>]
 
 FLAGS
-  -a, --apex-compile=<option>        Compile all Apex in the org and package, or only Apex in the package; unlocked
-                                     packages only.
-                                     <options: all|package>
-  -b, --publish-wait=<value>         Maximum number of minutes to wait for the Subscriber Package Version ID to become
-                                     available in the target org before canceling the install request.
-  -i, --install-type=<option>        [default: Upgrade] Install all packages, only deltas, or only newer versions.
-                                     <options: All|Delta|Upgrade>
-  -k, --installation-key=<value>...  Installation key for key-protected packages
-  -o, --target-org=<value>           (required) Username or alias of the target org. Not required if the `target-org`
-                                     configuration variable is already set.
-  -r, --no-prompt                    Don't prompt for confirmation.
-  -s, --security-type=<option>       [default: AdminsOnly] Security access type for the installed package. (deprecation
-                                     notice: The default --security-type value will change from AllUsers to AdminsOnly
-                                     in v47.0 or later.)
-                                     <options: AllUsers|AdminsOnly>
-  -t, --upgrade-type=<option>        [default: Mixed] Upgrade type for the package installation; available only for
-                                     unlocked packages.
-                                     <options: DeprecateOnly|Mixed|Delete>
-  -v, --target-dev-hub=<value>       Username or alias of the Dev Hub org.
-  -w, --wait=<value>                 Number of minutes to wait for installation status.
-  -z, --branch=<value>               Package branch to consider when specifiying a Package/VersionNumber combination
-      --api-version=<value>          Override the api version used for api requests made by this command
-      --output-file=<value>          Path to write a JSON install report to.
+  -d, --directory=<value>  Package directory to search.
+  -p, --package=<value>    (required) Package name or alias to look up.
 
 GLOBAL FLAGS
   --flags-dir=<value>  Import flag values from a directory.
   --json               Format output as json.
 
 DESCRIPTION
-  Install package dependencies for a Salesforce project.
-
-  Installs all specified package dependencies in a Salesforce DX project using the sfdx-project.json definition.
+  Get a package version from sfdx-project.json.
 
-EXAMPLES
-  $ sf simply package dependencies install --target-org myTargetOrg --target-dev-hub myTargetDevHub
+  Reads the version a package is declared at in your project's sfdx-project.json and prints it, so a script doesn't have
+  to parse the project file itself.
 
-  $ sf simply package dependencies install --target-org myTargetOrg --target-dev-hub myTargetDevHub --installation-key "MyPackage1Alias:MyPackage1Key"
+  Both dependencies and the project's own package are searched. A dependency declared as an alias (test-package@0.1.0+2)
+  resolves to the version portion of the alias; a dependency declared as a package name plus a versionNumber resolves to
+  that versionNumber; a dependency declared as a raw ID resolves through packageAliases. A package directory that builds
+  the package resolves to that directory's versionNumber.
 
-  $ sf simply package dependencies install --target-org myTargetOrg --target-dev-hub myTargetDevHub --installation-key "MyPackage1Alias:MyPackage1Key" --installation-key "MyPackage2Alias:MyPackage2Key"
+  The version is returned exactly as it appears in the project file — no normalizing between the 0.1.0+2, 57.0.0-3, and
+  1.2.3.LATEST forms, since each means something to the tool that consumes it.
 
-  $ sf simply package dependencies install --target-org myTargetOrg --target-dev-hub myTargetDevHub --output-file install-report.json
-
-FLAG DESCRIPTIONS
-  -a, --apex-compile=all|package
-
-    Compile all Apex in the org and package, or only Apex in the package; unlocked packages only.
-
-    Applies to unlocked packages only. Specifies whether to compile all Apex in the org and package, or only the Apex in
-    the package.
-
-    For package installs into production orgs, or any org that has Apex Compile on Deploy enabled, the platform compiles
-    all Apex in the org after the package install or upgrade operation completes.
-
-    This approach assures that package installs and upgrades don’t impact the performance of an org, and is done even if
-    --apex-compile package is specified.
-
-  -i, --install-type=All|Delta|Upgrade  Install all packages, only deltas, or only newer versions.
-
-    If 'All' is specified, then all packages specified in package dependencies are installed, regardless of if the
-    version already is installed in the org. If 'Delta' is specified, then only packages that differ from what is
-    installed in the org will be installed. If 'Upgrade' is specified, then a package is installed only if it isn't
-    already installed, or if its semantic version (major.minor.patch.build) is newer than the version currently
-    installed in the org; packages with an installed version that is the same as or newer than the target version are
-    skipped.
-
-  -k, --installation-key=<value>...  Installation key for key-protected packages
-
-    Installation key for key-protected packages in the key:value format of SubscriberPackageVersionId:Key
-
-  -r, --no-prompt  Don't prompt for confirmation.
-
-    Allows the following without an explicit confirmation response: 1) Remote Site Settings and Content Security Policy
-    websites to send or receive data, and 2) --upgrade-type Delete to proceed.
-
-  -t, --upgrade-type=DeprecateOnly|Mixed|Delete
-
-    Upgrade type for the package installation; available only for unlocked packages.
-
-    For package upgrades, specifies whether to mark all removed components as deprecated (DeprecateOnly), to delete
-    removed components that can be safely deleted and deprecate the others (Mixed), or to delete all removed components,
-    except for custom objects and custom fields, that don't have dependencies (Delete). The default is Mixed. Can
-    specify DeprecateOnly or Delete only for unlocked package upgrades.
-
-  -z, --branch=<value>  Package branch to consider when specifiying a Package/VersionNumber combination
-
-    For dependencies specified by Package/VersionNumber combination, you can specify the branch group of builds to work
-    from by entering the branch build name. If not specified, the builds from NULL branch will be considered.
-
-  --output-file=<value>  Path to write a JSON install report to.
-
-    When specified, a JSON report of the install outcome for every resolved dependency is written to this path, in
-    addition to the normal terminal output you can continue to monitor as the command runs. Each entry includes the
-    package name, the SubscriberPackageVersionId already installed in the org (if any), the SubscriberPackageVersionId
-    that was attempted, and the decision made (Skipped, Installed, Installing, or Failed).
-```
-
-_See code: [lib/commands/simply/package/dependencies/install.js](https://github.com/SimplySF/simply-node/blob/@simplysf/simply-package@2.8.1/packages/simply-package/lib/commands/simply/package/dependencies/install.js)_
-
-## `sf simply package dependencies manage`
-
-Manage package dependency versions for a Salesforce project.
-
-```
-USAGE
-  $ sf simply package dependencies manage -v <value> [--json] [--flags-dir <value>] [-b <value>] [--update-to-released |
-    --update-to-latest] [--api-version <value>]
-
-FLAGS
-  -b, --branch=<value>          Package branch to consider when evaluating version options.
-  -v, --target-dev-hub=<value>  (required) Username or alias of the Dev Hub org. Not required if the `target-dev-hub`
-                                configuration variable is already set.
-      --api-version=<value>     Override the api version used for api requests made by this command
-      --update-to-latest        Automatically set all dependencies to the latest non-pinned build.
-      --update-to-released      Automatically update all dependencies to the latest released version.
-
-GLOBAL FLAGS
-  --flags-dir=<value>  Import flag values from a directory.
-  --json               Format output as json.
-
-DESCRIPTION
-  Manage package dependency versions for a Salesforce project.
-
-  Interactively updates package dependency versions in sfdx-project.json by querying the Dev Hub for available versions.
-  Supports interactive selection or automatic update to the latest released or latest build version.
-
-  Project-level configuration (in sfdx-project.json) is read from the following keys:
-
-  - plugins.simply.dependencies.ignore — array of Package2Ids or aliases to leave unchanged
-  - plugins.simply.package.brancheswithreleasedversions — array of branch names that contain released versions
+  This command reads the project file only. It never contacts an org or a Dev Hub, so it can run in a pipeline before
+  any authentication step.
 
 EXAMPLES
-  $ sf simply package dependencies manage --target-dev-hub myDevHub
-
-  $ sf simply package dependencies manage --target-dev-hub myDevHub --branch my-feature-branch
-
-  $ sf simply package dependencies manage --target-dev-hub myDevHub --update-to-released
-
-  $ sf simply package dependencies manage --target-dev-hub myDevHub --update-to-latest
-
-FLAG DESCRIPTIONS
-  -b, --branch=<value>  Package branch to consider when evaluating version options.
-
-    When specified, the command will include the latest build on this branch as a selectable option for each dependency.
-
-  --update-to-latest  Automatically set all dependencies to the latest non-pinned build.
-
-    When specified, all dependencies managed by the Dev Hub are automatically set to a non-pinned X.Y.Z.LATEST version
-    number without interactive prompts. Mutually exclusive with --update-to-released.
-
-  --update-to-released  Automatically update all dependencies to the latest released version.
-
-    When specified, all dependencies managed by the Dev Hub are automatically updated to the latest released package
-    version without interactive prompts. Mutually exclusive with --update-to-latest.
-```
+  Get the version of a dependency:
 
-_See code: [lib/commands/simply/package/dependencies/manage.js](https://github.com/SimplySF/simply-node/blob/@simplysf/simply-package@2.8.1/packages/simply-package/lib/commands/simply/package/dependencies/manage.js)_
+    $ sf simply package version get --package test-package
 
-## `sf simply package version cleanup`
-
-Cleanup package versions.
-
-```
-USAGE
-  $ sf simply package version cleanup -p <value> -v <value> [--json] [--flags-dir <value>] [--api-version <value>] [-s <value> | -x
-    <value>]
-
-FLAGS
-  -p, --package=<value>          (required) Package Id
-  -s, --matcher=<value>          MAJOR.MINOR.PATCH to select on
-  -v, --target-dev-hub=<value>   (required) Username or alias of the Dev Hub org. Not required if the `target-dev-hub`
-                                 configuration variable is already set.
-  -x, --exclude-matcher=<value>  MAJOR.MINOR.PATCH to exclude on
-      --api-version=<value>      Override the api version used for api requests made by this command
-
-GLOBAL FLAGS
-  --flags-dir=<value>  Import flag values from a directory.
-  --json               Format output as json.
-
-DESCRIPTION
-  Cleanup package versions.
+  Get the version of the package the project itself builds:
 
-  Delete package versions for a given package provided a MAJOR.MINOR.PATCH matcher, either to select on or to exclude
-  on. Does not delete released package versions.
+    $ sf simply package version get --package my-package
 
-  If --matcher is provided, only the unreleased versions matching MAJOR.MINOR.PATCH are deleted. If --exclude-matcher is
-  provided instead, every unreleased version that does _not_ match MAJOR.MINOR.PATCH is deleted. Exactly one of
-  --matcher or --exclude-matcher must be specified.
+  Get a dependency's version from one package directory:
 
-EXAMPLES
-  $ sf simply package version cleanup --package 0Hoxx00000000CqCAI --matcher 2.10.0 --target-dev-hub myDevHub
-
-  $ sf simply package version cleanup --package 0Hoxx00000000CqCAI --exclude-matcher 2.10.0 --target-dev-hub myDevHub
+    $ sf simply package version get --package test-package --directory force-app
 
 FLAG DESCRIPTIONS
-  -p, --package=<value>  Package Id
-
-    The 0Ht Package Id that you wish to cleanup versions for.
-
-  -s, --matcher=<value>  MAJOR.MINOR.PATCH to select on
+  -d, --directory=<value>  Package directory to search.
 
-    The MAJOR.MINOR.PATCH matcher that should be used to find package versions to delete. Only versions matching this
-    matcher are deleted. Mutually exclusive with --exclude-matcher.
+    The path of a single package directory to search, matching a "path" value in packageDirectories. Use this when the
+    same package is declared at different versions in more than one package directory.
 
-  -x, --exclude-matcher=<value>  MAJOR.MINOR.PATCH to exclude on
+  -p, --package=<value>  Package name or alias to look up.
 
-    The MAJOR.MINOR.PATCH matcher that should be used to find package versions to keep. Every unreleased version that
-    does not match this matcher is deleted. Mutually exclusive with --matcher.
+    The package name as it appears in sfdx-project.json, without a version suffix. For a dependency declared as
+    "test-package@0.1.0+2", pass "test-package".
 ```
 
-_See code: [lib/commands/simply/package/version/cleanup.js](https://github.com/SimplySF/simply-node/blob/@simplysf/simply-package@2.8.1/packages/simply-package/lib/commands/simply/package/version/cleanup.js)_
+_See code: [lib/commands/simply/package/version/get.js](https://github.com/SimplySF/simply-node/blob/@simplysf/simply-package@2.9.0/packages/simply-package/lib/commands/simply/package/version/get.js)_
 <!-- commandsstop -->
 
 ## Configuration Files

package/lib/commands/simply/package/version/get.d.ts

@@ -0,0 +1,31 @@
+import { SfCommand } from '@salesforce/sf-plugins-core';
+import { PackageVersionSource } from '../../../../common/packageVersionLookup.js';
+/** The version a package is declared at in `sfdx-project.json`, and where that declaration lives. */
+export type PackageVersionGetResult = {
+    package: string;
+    version: string;
+    source: PackageVersionSource;
+    packageDirectory: string;
+    subscriberPackageVersionId?: string;
+};
+/**
+ * Reads a package's version out of `sfdx-project.json` — either a dependency's version or the
+ * version the project's own package is at. Local only: no org, Dev Hub, or auth involved.
+ */
+export default class PackageVersionGet extends SfCommand<PackageVersionGetResult> {
+    static readonly summary: string;
+    static readonly description: string;
+    static readonly examples: string[];
+    static readonly requiresProject = true;
+    static readonly flags: {
+        package: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        directory: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'flags-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    /**
+     * @returns The declared version of `--package`, and where in the project file it was declared.
+     * @throws {SfError} If the package isn't declared, is declared without a resolvable version, or
+     * is declared at conflicting versions in more than one package directory.
+     */
+    run(): Promise<PackageVersionGetResult>;
+}

package/lib/commands/simply/package/version/get.js

@@ -0,0 +1,100 @@
+/*
+ * Copyright (c) 2026, Clay Chipps.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Messages } from '@salesforce/core';
+import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
+import { findPackageVersions, } from '../../../../common/packageVersionLookup.js';
+Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+const messages = Messages.loadMessages('@simplysf/simply-package', 'simply.package.version.get');
+/**
+ * Reads a package's version out of `sfdx-project.json` — either a dependency's version or the
+ * version the project's own package is at. Local only: no org, Dev Hub, or auth involved.
+ */
+export default class PackageVersionGet extends SfCommand {
+    static summary = messages.getMessage('summary');
+    static description = messages.getMessage('description');
+    static examples = messages.getMessages('examples');
+    static requiresProject = true;
+    static flags = {
+        ...SfCommand.baseFlags,
+        package: Flags.string({
+            summary: messages.getMessage('flags.package.summary'),
+            description: messages.getMessage('flags.package.description'),
+            char: 'p',
+            required: true,
+        }),
+        directory: Flags.string({
+            summary: messages.getMessage('flags.directory.summary'),
+            description: messages.getMessage('flags.directory.description'),
+            char: 'd',
+        }),
+    };
+    /**
+     * @returns The declared version of `--package`, and where in the project file it was declared.
+     * @throws {SfError} If the package isn't declared, is declared without a resolvable version, or
+     * is declared at conflicting versions in more than one package directory.
+     */
+    async run() {
+        const { flags } = await this.parse(PackageVersionGet);
+        const projectJson = await this.project.retrieveSfProjectJson();
+        const project = projectJson.getContents();
+        const matches = findPackageVersions(project, flags.package, { directory: flags.directory });
+        if (matches.length === 0) {
+            throw messages.createError('errors.packageNotFound', [flags.package, describeSearchScope(project, flags)]);
+        }
+        const versionedMatches = matches.filter((match) => match.version);
+        if (versionedMatches.length === 0) {
+            throw messages.createError('errors.noVersionFound', [flags.package, matches[0].packageDirectory]);
+        }
+        const distinctVersions = new Set(versionedMatches.map((match) => match.version));
+        if (distinctVersions.size > 1) {
+            throw messages.createError('errors.ambiguousMatch', [flags.package, describeMatches(versionedMatches)]);
+        }
+        const match = versionedMatches[0];
+        const result = {
+            package: match.package,
+            version: match.version,
+            source: match.source,
+            packageDirectory: match.packageDirectory,
+            ...(match.subscriberPackageVersionId
+                ? { subscriberPackageVersionId: match.subscriberPackageVersionId }
+                : undefined),
+        };
+        // Nothing but the version, so `$(sf simply package version get -p foo)` is directly usable.
+        // SfCommand.log is a no-op under --json, so this doesn't disturb the JSON output.
+        this.log(result.version);
+        return result;
+    }
+}
+/**
+ * @param project - The parsed `sfdx-project.json` contents.
+ * @param flags - The command's parsed flags.
+ * @returns A description of which package directories were searched, for the not-found error.
+ */
+function describeSearchScope(project, flags) {
+    if (flags.directory) {
+        return `package directory '${flags.directory}'`;
+    }
+    const paths = project.packageDirectories.map((directory) => directory.path ?? '<unnamed>');
+    return `package directories: ${paths.join(', ')}`;
+}
+/**
+ * @param matches - The conflicting matches.
+ * @returns A `version (directory)` list, for the ambiguity error.
+ */
+function describeMatches(matches) {
+    return matches.map((match) => `${match.version} (${match.packageDirectory})`).join(', ');
+}
+//# sourceMappingURL=get.js.map

package/lib/commands/simply/package/version/get.js.map

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

package/lib/common/packageVersionLookup.d.ts

@@ -0,0 +1,56 @@
+import { SfdxProject } from '@simplysf/simply-core';
+/** Where in `sfdx-project.json` a version was declared. */
+export type PackageVersionSource = 'dependency' | 'packageDirectory';
+/** One place a package name is declared in `sfdx-project.json`, and the version found there. */
+export type PackageVersionMatch = {
+    /** The name matched on, as written in the project file. */
+    package: string;
+    /** The declared version, or `undefined` if the declaration carries no resolvable version. */
+    version?: string;
+    source: PackageVersionSource;
+    /** The `path` of the package directory the declaration was found in. */
+    packageDirectory: string;
+    /** The `04t` the declaration resolves to, when one is knowable from `packageAliases`. */
+    subscriberPackageVersionId?: string;
+};
+/** Narrows which package directories {@link findPackageVersions} looks at. */
+export type FindPackageVersionsOptions = {
+    /** Only search the package directory with this `path`. */
+    directory?: string;
+};
+/**
+ * Split a package reference into its name and version parts.
+ *
+ * Splits on the *last* `@`, matching how `sfdx-project.json` aliases are written and how
+ * `simply-cicd`'s dependabot updater already parses them, so a name that itself contains an `@`
+ * (a scoped-style `@ns/pkg`) keeps its name intact.
+ *
+ * @param value - A package reference, e.g. `test-package@0.1.0+2`, `test-package`, or an ID.
+ * @returns The name, plus the version if the reference carried one.
+ */
+export declare function splitPackageAlias(value: string): {
+    name: string;
+    version?: string;
+};
+/**
+ * Find every place `packageName` is declared in a project, and the version declared with it.
+ *
+ * A package can be declared four ways, all of which are searched:
+ * 1. A dependency whose `package` is a versioned alias — `test-package@0.1.0+2`.
+ * 2. A dependency whose `package` is a bare name plus a sibling `versionNumber`.
+ * 3. A dependency whose `package` is a raw ID, where `packageAliases` maps a versioned alias for
+ * `packageName` onto that same ID.
+ * 4. A package directory that *builds* `packageName`, i.e. the project's own package version.
+ *
+ * Matches are returned rather than resolved to a single answer because "the same package declared
+ * at two different versions in two directories" is a real project state, and only the caller knows
+ * whether that's an error or a list to display.
+ *
+ * @param project - The parsed `sfdx-project.json` contents.
+ * @param packageName - The package name or alias to look up.
+ * @param options - Narrows which package directories are searched.
+ * @returns Every match, in package-directory order, dependencies before the directory's own
+ * package. A match with no `version` means the package is declared but its version isn't
+ * knowable from the project file alone.
+ */
+export declare function findPackageVersions(project: SfdxProject, packageName: string, options?: FindPackageVersionsOptions): PackageVersionMatch[];

package/lib/common/packageVersionLookup.js

@@ -0,0 +1,141 @@
+/*
+ * Copyright (c) 2026, Clay Chipps.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { isSubscriberPackageVersionId } from './packageUtils.js';
+/**
+ * Split a package reference into its name and version parts.
+ *
+ * Splits on the *last* `@`, matching how `sfdx-project.json` aliases are written and how
+ * `simply-cicd`'s dependabot updater already parses them, so a name that itself contains an `@`
+ * (a scoped-style `@ns/pkg`) keeps its name intact.
+ *
+ * @param value - A package reference, e.g. `test-package@0.1.0+2`, `test-package`, or an ID.
+ * @returns The name, plus the version if the reference carried one.
+ */
+export function splitPackageAlias(value) {
+    const lastAtIndex = value.lastIndexOf('@');
+    // An `@` at index 0 is part of the name (`@ns/pkg`), not a version separator.
+    if (lastAtIndex <= 0) {
+        return { name: value };
+    }
+    return { name: value.slice(0, lastAtIndex), version: value.slice(lastAtIndex + 1) || undefined };
+}
+/**
+ * Find every place `packageName` is declared in a project, and the version declared with it.
+ *
+ * A package can be declared four ways, all of which are searched:
+ * 1. A dependency whose `package` is a versioned alias — `test-package@0.1.0+2`.
+ * 2. A dependency whose `package` is a bare name plus a sibling `versionNumber`.
+ * 3. A dependency whose `package` is a raw ID, where `packageAliases` maps a versioned alias for
+ * `packageName` onto that same ID.
+ * 4. A package directory that *builds* `packageName`, i.e. the project's own package version.
+ *
+ * Matches are returned rather than resolved to a single answer because "the same package declared
+ * at two different versions in two directories" is a real project state, and only the caller knows
+ * whether that's an error or a list to display.
+ *
+ * @param project - The parsed `sfdx-project.json` contents.
+ * @param packageName - The package name or alias to look up.
+ * @param options - Narrows which package directories are searched.
+ * @returns Every match, in package-directory order, dependencies before the directory's own
+ * package. A match with no `version` means the package is declared but its version isn't
+ * knowable from the project file alone.
+ */
+export function findPackageVersions(project, packageName, options = {}) {
+    const aliases = project.packageAliases ?? {};
+    const directories = options.directory
+        ? project.packageDirectories.filter((directory) => directory.path === options.directory)
+        : project.packageDirectories;
+    return directories.flatMap((directory) => [
+        ...findDependencyMatches(directory, packageName, aliases),
+        ...findOwnPackageMatch(directory, packageName),
+    ]);
+}
+/**
+ * @param directory - The package directory to search.
+ * @param packageName - The package name or alias to look up.
+ * @param aliases - The project's `packageAliases` map.
+ * @returns Matches among `directory`'s declared dependencies.
+ */
+function findDependencyMatches(directory, packageName, aliases) {
+    const packageDirectory = directory.path ?? '';
+    return (directory.dependencies ?? []).flatMap((dependency) => {
+        if (!dependency.package) {
+            return [];
+        }
+        const { name, version } = splitPackageAlias(dependency.package);
+        if (name === packageName) {
+            return [
+                {
+                    package: dependency.package,
+                    version: version ?? dependency.versionNumber,
+                    source: 'dependency',
+                    packageDirectory,
+                    subscriberPackageVersionId: subscriberVersionIdFor(dependency.package, aliases),
+                },
+            ];
+        }
+        // The dependency is written as a raw ID: recover the version from whichever versioned alias
+        // for this package points at that same ID.
+        const aliasForId = Object.keys(aliases).find((alias) => aliases[alias] === dependency.package && splitPackageAlias(alias).name === packageName);
+        if (!aliasForId) {
+            return [];
+        }
+        return [
+            {
+                package: aliasForId,
+                version: splitPackageAlias(aliasForId).version ?? dependency.versionNumber,
+                source: 'dependency',
+                packageDirectory,
+                subscriberPackageVersionId: isSubscriberPackageVersionId(dependency.package) ? dependency.package : undefined,
+            },
+        ];
+    });
+}
+/**
+ * @param directory - The package directory to search.
+ * @param packageName - The package name or alias to look up.
+ * @returns A single match if this directory builds `packageName`, otherwise nothing.
+ */
+function findOwnPackageMatch(directory, packageName) {
+    if (!directory.package) {
+        return [];
+    }
+    const { name, version } = splitPackageAlias(directory.package);
+    if (name !== packageName) {
+        return [];
+    }
+    return [
+        {
+            package: directory.package,
+            version: directory.versionNumber ?? version,
+            source: 'packageDirectory',
+            packageDirectory: directory.path ?? '',
+        },
+    ];
+}
+/**
+ * @param reference - A dependency's `package` value.
+ * @param aliases - The project's `packageAliases` map.
+ * @returns The `04t` `reference` denotes, either directly or through an alias, if any.
+ */
+function subscriberVersionIdFor(reference, aliases) {
+    if (isSubscriberPackageVersionId(reference)) {
+        return reference;
+    }
+    const resolved = aliases[reference];
+    return resolved && isSubscriberPackageVersionId(resolved) ? resolved : undefined;
+}
+//# sourceMappingURL=packageVersionLookup.js.map

package/lib/common/packageVersionLookup.js.map

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

package/messages/simply.package.version.get.md

@@ -0,0 +1,55 @@
+# summary
+
+Get a package version from sfdx-project.json.
+
+# description
+
+Reads the version a package is declared at in your project's sfdx-project.json and prints it, so a script doesn't have to parse the project file itself.
+
+Both dependencies and the project's own package are searched. A dependency declared as an alias (test-package@0.1.0+2) resolves to the version portion of the alias; a dependency declared as a package name plus a versionNumber resolves to that versionNumber; a dependency declared as a raw ID resolves through packageAliases. A package directory that builds the package resolves to that directory's versionNumber.
+
+The version is returned exactly as it appears in the project file — no normalizing between the 0.1.0+2, 57.0.0-3, and 1.2.3.LATEST forms, since each means something to the tool that consumes it.
+
+This command reads the project file only. It never contacts an org or a Dev Hub, so it can run in a pipeline before any authentication step.
+
+# flags.package.summary
+
+Package name or alias to look up.
+
+# flags.package.description
+
+The package name as it appears in sfdx-project.json, without a version suffix. For a dependency declared as "test-package@0.1.0+2", pass "test-package".
+
+# flags.directory.summary
+
+Package directory to search.
+
+# flags.directory.description
+
+The path of a single package directory to search, matching a "path" value in packageDirectories. Use this when the same package is declared at different versions in more than one package directory.
+
+# examples
+
+- Get the version of a dependency:
+
+  <%= config.bin %> <%= command.id %> --package test-package
+
+- Get the version of the package the project itself builds:
+
+  <%= config.bin %> <%= command.id %> --package my-package
+
+- Get a dependency's version from one package directory:
+
+  <%= config.bin %> <%= command.id %> --package test-package --directory force-app
+
+# errors.packageNotFound
+
+No package named '%s' is declared in %s.
+
+# errors.noVersionFound
+
+The package '%s' is declared in '%s', but without a version. Add a version to its alias (name@version) or a versionNumber to the dependency.
+
+# errors.ambiguousMatch
+
+The package '%s' is declared at more than one version: %s. Use --directory to choose one package directory.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@simplysf/simply-package",
   "description": "Utilities for working with packages",
-  "version": "2.9.0",
+  "version": "2.10.1",
   "author": "@ClayChipps",
   "homepage": "https://github.com/SimplySF/simply-node",
   "bugs": "https://github.com/SimplySF/simply-node/issues",
@@ -77,7 +77,7 @@
     "@salesforce/packaging": "^4.22.16",
     "@salesforce/sf-plugins-core": "^12.2.16",
     "@salesforce/ts-types": "^2.0.12",
-    "@simplysf/simply-core": "^1.3.0",
+    "@simplysf/simply-core": "^1.4.0",
     "@simplysf/simply-plugin-kit": "^1.0.4",
     "zod": "^4.1.12"
   },
@@ -225,5 +225,5 @@
       "output": []
     }
   },
-  "gitHead": "c3eece6a9447aa996f4515f53a6697e78e318b31"
+  "gitHead": "714cbc02c9cac7b8eb745a5be607e281af238751"
 }