@sfship/plugin-ship 1.0.0-beta.2

package/lib/core/flows/deploy/qa.yml

@@ -0,0 +1,51 @@
+description: Set up a QA environment using the latest beta managed package.
+steps:
+  create-org:
+    task: org/create/scratch
+    params:
+      scratch-def: qa
+      duration: 7
+      no-namespace: true
+  package-data:
+    task: git/release/fetch
+    params:
+      prerelease: true
+  update-dependencies:
+    task: package/install/dependencies
+    params:
+      target-org: ${{ steps.create-org.target-org }}
+  check-pre:
+    task: util/file/exists
+    params:
+      path: unpackaged/pre
+  deploy-pre:
+    if:
+      value: ${{ steps.check-pre.exists }}
+    task: project/deploy/start
+    params:
+      target-org: ${{ steps.create-org.target-org }}
+      source-dir: unpackaged/pre
+  install:
+    task: package/install
+    params:
+      target-org: ${{ steps.create-org.target-org }}
+      version-id: ${{ steps.package-data.version-id }}
+  check-post:
+    task: util/file/exists
+    params:
+      path: unpackaged/post
+  deploy-post:
+    if:
+      value: ${{ steps.check-post.exists }}
+    task: project/deploy/start
+    params:
+      target-org: ${{ steps.create-org.target-org }}
+      source-dir: unpackaged/post
+  assign-permsets:
+    task: org/assign/permsets
+    params:
+      target-org: ${{ steps.create-org.target-org }}
+  load-data:
+    task: data/import/tree
+    params:
+      target-org: ${{ steps.create-org.target-org }}

package/lib/core/flows/deploy/regression.yml

@@ -0,0 +1,60 @@
+description: Simulate an upgrade from the latest production release to the latest beta, with full dependency and unpackaged metadata setup.
+steps:
+  create-org:
+    task: org/create/scratch
+    params:
+      scratch-def: regression
+      duration: 1
+      no-namespace: true
+  find-release:
+    task: git/release/fetch
+    params:
+      prerelease: false
+  find-beta:
+    task: git/release/fetch
+    params:
+      prerelease: true
+  update-dependencies:
+    task: package/install/dependencies
+    params:
+      target-org: ${{ steps.create-org.target-org }}
+  check-pre:
+    task: util/file/exists
+    params:
+      path: unpackaged/pre
+  deploy-pre:
+    if:
+      value: ${{ steps.check-pre.exists }}
+    task: project/deploy/start
+    params:
+      target-org: ${{ steps.create-org.target-org }}
+      source-dir: unpackaged/pre
+  install-release:
+    task: package/install
+    params:
+      target-org: ${{ steps.create-org.target-org }}
+      version-id: ${{ steps.find-release.version-id }}
+  install-beta:
+    task: package/install
+    params:
+      target-org: ${{ steps.create-org.target-org }}
+      version-id: ${{ steps.find-beta.version-id }}
+  assign-permsets:
+    task: org/assign/permsets
+    params:
+      target-org: ${{ steps.create-org.target-org }}
+  check-post:
+    task: util/file/exists
+    params:
+      path: unpackaged/post
+  deploy-post:
+    if:
+      value: ${{ steps.check-post.exists }}
+    task: project/deploy/start
+    params:
+      target-org: ${{ steps.create-org.target-org }}
+      source-dir: unpackaged/post
+  load-data:
+    task: data/import/tree
+    params:
+      target-org: ${{ steps.create-org.target-org }}

package/lib/core/flows/deploy/release.yml

@@ -0,0 +1,38 @@
+description: Install the latest production release into a fresh scratch org and run Apex tests.
+steps:
+  create-org:
+    task: org/create/scratch
+    params:
+      scratch-def: release
+      duration: 1
+      no-namespace: true
+  find-release:
+    task: git/release/fetch
+    params:
+      prerelease: false
+  update-dependencies:
+    task: package/install/dependencies
+    params:
+      target-org: ${{ steps.create-org.target-org }}
+  install:
+    task: package/install
+    params:
+      target-org: ${{ steps.create-org.target-org }}
+      version-id: ${{ steps.find-release.version-id }}
+  assign-permsets:
+    task: org/assign/permsets
+    params:
+      target-org: ${{ steps.create-org.target-org }}
+  find-test-classes:
+    task: util/file/find
+    params:
+      path: force-app/main/default/classes
+      pattern: ${{ config.project.package.testPattern }}
+  run-tests:
+    if:
+      value: ${{ steps.find-test-classes.count }}
+    task: apex/run/test
+    params:
+      target-org: ${{ steps.create-org.target-org }}
+      class-names: ${{ steps.find-test-classes.files }}
+      namespace: ${{ config.project.package.namespace }}

package/lib/core/flows/release/beta.yml

@@ -0,0 +1,25 @@
+description: Build a beta managed package version and release it on GitHub.
+params:
+  - name: version-type
+    type: string
+    required: false
+    default: minor
+    description: Which part of the version to bump relative to the latest released version. One of build, patch, minor, major.
+steps:
+  verify-dependencies:
+    task: package/dependencies/verify
+  resolve-next:
+    task: package/version/resolve-next
+    params:
+      version-type: ${{ params.version-type }}
+  create-version:
+    task: package/version/create
+    params:
+      code-coverage: true
+      version-number: ${{ steps.resolve-next.version-number }}
+  github-release:
+    task: git/release/create
+    params:
+      tag: v${{ steps.create-version.version-number }}
+      version-id: ${{ steps.create-version.version-id }}
+      prerelease: true

package/lib/core/flows/release/production.yml

@@ -0,0 +1,16 @@
+description: Promote the latest beta to released and create a production GitHub release.
+steps:
+  find-beta:
+    task: git/release/fetch
+    params:
+      prerelease: true
+  promote:
+    task: package/version/promote
+    params:
+      version-id: ${{ steps.find-beta.version-id }}
+  github-release:
+    task: git/release/create
+    params:
+      tag: v${{ steps.find-beta.version-base }}
+      version-id: ${{ steps.promote.version-id }}
+      prerelease: false

package/lib/core/org.registry.d.ts

@@ -0,0 +1,45 @@
+import { Org } from '@salesforce/core';
+import { ScratchOrgDef } from './org.scratch.schema.js';
+/**
+ * Manages lazy-loaded Salesforce `Org` instances and scratch org definitions
+ * for a flow run. Caches both to avoid redundant filesystem reads and
+ * `Org.create()` calls across tasks.
+ */
+export declare class OrgRegistry {
+    private readonly orgsDir;
+    private readonly projectName?;
+    private orgs;
+    private defs;
+    /**
+     * @param orgsDir - Path to the directory containing scratch org definition JSON files.
+     * @param projectName - Optional project name used to qualify org aliases (e.g. `"myproject:dev"`).
+     */
+    constructor(orgsDir: string, projectName?: string | undefined);
+    /**
+     * Resolves an org identifier to a qualified alias or username for use with `Org.create()`.
+     *
+     * Resolution order:
+     * 1. If a def file exists in the orgs directory, qualifies as `<projectName>:<alias>`.
+     * 2. If the input contains `@`, treats it as a Salesforce username and returns as-is.
+     * 3. Otherwise assumes it is an SF CLI alias and returns as-is.
+     *
+     * @param alias - A project alias, Salesforce username, or SF CLI alias.
+     */
+    resolveAlias(alias: string): string;
+    resolveAlias(alias: string | undefined): string | undefined;
+    /**
+     * Returns an Org instance for the given alias,
+     * creating and caching it if it hasn't been instantiated yet.
+     * Automatically qualifies the alias using the project naming convention.
+     *
+     * @param alias - The raw org alias, e.g. "dev".
+     */
+    getOrg(alias: string): Promise<Org>;
+    /**
+     * Returns the scratch org definition for the given alias,
+     * reading and caching the JSON file if it hasn't been loaded yet.
+     *
+     * @param alias - The scratch org alias, e.g. "dev".
+     */
+    getDef(alias: string): ScratchOrgDef;
+}

package/lib/core/org.registry.js

@@ -0,0 +1,76 @@
+/*
+ * 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 { resolve } from 'node:path';
+import { Org } from '@salesforce/core';
+import { ScratchOrgDefSchema } from './org.scratch.schema.js';
+import { fileExists, readText } from './file.js';
+import { ExpectedError } from './error.js';
+/**
+ * Manages lazy-loaded Salesforce `Org` instances and scratch org definitions
+ * for a flow run. Caches both to avoid redundant filesystem reads and
+ * `Org.create()` calls across tasks.
+ */
+export class OrgRegistry {
+    orgsDir;
+    projectName;
+    orgs = new Map();
+    defs = new Map();
+    /**
+     * @param orgsDir - Path to the directory containing scratch org definition JSON files.
+     * @param projectName - Optional project name used to qualify org aliases (e.g. `"myproject:dev"`).
+     */
+    constructor(orgsDir, projectName) {
+        this.orgsDir = orgsDir;
+        this.projectName = projectName;
+    }
+    resolveAlias(alias) {
+        if (alias === undefined)
+            return undefined;
+        const defPath = resolve(this.orgsDir, `${alias}.json`);
+        if (fileExists(defPath))
+            return this.projectName ? `${this.projectName}:${alias}` : alias;
+        return alias;
+    }
+    /**
+     * Returns an Org instance for the given alias,
+     * creating and caching it if it hasn't been instantiated yet.
+     * Automatically qualifies the alias using the project naming convention.
+     *
+     * @param alias - The raw org alias, e.g. "dev".
+     */
+    async getOrg(alias) {
+        const qualified = this.resolveAlias(alias);
+        if (!this.orgs.has(qualified)) {
+            this.orgs.set(qualified, await Org.create({ aliasOrUsername: qualified }));
+        }
+        return this.orgs.get(qualified);
+    }
+    /**
+     * Returns the scratch org definition for the given alias,
+     * reading and caching the JSON file if it hasn't been loaded yet.
+     *
+     * @param alias - The scratch org alias, e.g. "dev".
+     */
+    getDef(alias) {
+        if (!this.defs.has(alias)) {
+            const defPath = resolve(this.orgsDir, `${alias}.json`);
+            if (!fileExists(defPath)) {
+                throw new ExpectedError(`No scratch org definition found for alias "${alias}" at ${defPath}`);
+            }
+            this.defs.set(alias, ScratchOrgDefSchema.parse(JSON.parse(readText(defPath))));
+        }
+        return this.defs.get(alias);
+    }
+}
+//# sourceMappingURL=org.registry.js.map

package/lib/core/org.registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"org.registry.js","sourceRoot":"","sources":["../../src/core/org.registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,EAAiB,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;GAIG;AACH,MAAM,OAAO,WAAW;IAQc;IAAkC;IAP9D,IAAI,GAAG,IAAI,GAAG,EAAe,CAAC;IAC9B,IAAI,GAAG,IAAI,GAAG,EAAyB,CAAC;IAEhD;;;OAGG;IACH,YAAoC,OAAe,EAAmB,WAAoB;QAAtD,YAAO,GAAP,OAAO,CAAQ;QAAmB,gBAAW,GAAX,WAAW,CAAS;IAAG,CAAC;IAcvF,YAAY,CAAC,KAAyB;QAC3C,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC1C,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC;QACvD,IAAI,UAAU,CAAC,OAAO,CAAC;YAAE,OAAO,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,WAAW,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;QAC1F,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,MAAM,CAAC,KAAa;QAC/B,MAAM,SAAS,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAC3C,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,CAAC,MAAM,CAAC,EAAE,eAAe,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;QAC7E,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAE,CAAC;IACnC,CAAC;IAED;;;;;OAKG;IACI,MAAM,CAAC,KAAa;QACzB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC,CAAC;YACvD,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;gBACzB,MAAM,IAAI,aAAa,CAAC,8CAA8C,KAAK,QAAQ,OAAO,EAAE,CAAC,CAAC;YAChG,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,mBAAmB,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QACjF,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC;IAC/B,CAAC;CACF"}

package/lib/core/org.scratch.schema.d.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+/**
+ * Zod schema for a Salesforce scratch org definition file.
+ * Mirrors the shape of a `project-scratch-def.json`, with strict validation
+ * on known fields and `catchall` to allow unknown Salesforce-specific extensions.
+ */
+export declare const ScratchOrgDefSchema: z.ZodObject<{
+    edition: z.ZodEnum<{
+        Developer: "Developer";
+        Enterprise: "Enterprise";
+        Group: "Group";
+        Professional: "Professional";
+    }>;
+    orgName: z.ZodOptional<z.ZodString>;
+    country: z.ZodOptional<z.ZodString>;
+    username: z.ZodOptional<z.ZodString>;
+    adminEmail: z.ZodOptional<z.ZodEmail>;
+    description: z.ZodOptional<z.ZodString>;
+    hasSampleData: z.ZodOptional<z.ZodBoolean>;
+    language: z.ZodOptional<z.ZodString>;
+    features: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    release: z.ZodOptional<z.ZodEnum<{
+        preview: "preview";
+        previous: "previous";
+    }>>;
+    settings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    objectSettings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        sharingModel: z.ZodOptional<z.ZodEnum<{
+            private: "private";
+            read: "read";
+            readWrite: "readWrite";
+            readWriteTransfer: "readWriteTransfer";
+            fullAccess: "fullAccess";
+            controlledByParent: "controlledByParent";
+            controlledByCampaign: "controlledByCampaign";
+            controlledByLeadOrContent: "controlledByLeadOrContent";
+        }>>;
+        defaultRecordType: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    snapshot: z.ZodOptional<z.ZodString>;
+    sourceOrg: z.ZodOptional<z.ZodString>;
+}, z.core.$catchall<z.ZodUnknown>>;
+/** A validated scratch org definition, inferred from {@link ScratchOrgDefSchema}. */
+export type ScratchOrgDef = z.infer<typeof ScratchOrgDefSchema>;

package/lib/core/org.scratch.schema.js

@@ -0,0 +1,62 @@
+/*
+ * 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 { z } from 'zod';
+/** Valid sharing models for a Salesforce scratch org object. */
+const ScratchOrgSharingModelSchema = z.enum([
+    'private',
+    'read',
+    'readWrite',
+    'readWriteTransfer',
+    'fullAccess',
+    'controlledByParent',
+    'controlledByCampaign',
+    'controlledByLeadOrContent',
+]);
+/** Per-object settings that can be applied to a scratch org definition. */
+const ScratchOrgObjectSettingSchema = z.object({
+    sharingModel: ScratchOrgSharingModelSchema.optional(),
+    defaultRecordType: z.string().optional(),
+});
+/**
+ * Zod schema for a Salesforce scratch org definition file.
+ * Mirrors the shape of a `project-scratch-def.json`, with strict validation
+ * on known fields and `catchall` to allow unknown Salesforce-specific extensions.
+ */
+export const ScratchOrgDefSchema = z
+    .object({
+    /** The Salesforce edition for the scratch org. */
+    edition: z.enum(['Developer', 'Enterprise', 'Group', 'Professional']),
+    orgName: z.string().optional(),
+    country: z.string().optional(),
+    username: z.string().optional(),
+    adminEmail: z.email().optional(),
+    /** Max 2000 characters. */
+    description: z.string().max(2000).optional(),
+    hasSampleData: z.boolean().optional(),
+    language: z.string().optional(),
+    /** List of Salesforce features to enable (e.g. `'Communities'`, `'LightningSalesConsole'`). */
+    features: z.array(z.string()).optional(),
+    release: z.enum(['preview', 'previous']).optional(),
+    /** Org-wide settings, keyed by settings API name. */
+    settings: z.record(z.string(), z.unknown()).optional(),
+    /** Per-object sharing and record type settings. */
+    objectSettings: z.record(z.string(), ScratchOrgObjectSettingSchema).optional(),
+    /** Name of an org snapshot to create the scratch org from. */
+    snapshot: z.string().optional(),
+    /** 15-character org ID of a source org to copy settings from. */
+    sourceOrg: z.string().length(15).optional(),
+})
+    .catchall(z.unknown());
+/* c8 ignore stop */
+//# sourceMappingURL=org.scratch.schema.js.map

package/lib/core/org.scratch.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"org.scratch.schema.js","sourceRoot":"","sources":["../../src/core/org.scratch.schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,gEAAgE;AAChE,MAAM,4BAA4B,GAAG,CAAC,CAAC,IAAI,CAAC;IAC1C,SAAS;IACT,MAAM;IACN,WAAW;IACX,mBAAmB;IACnB,YAAY;IACZ,oBAAoB;IACpB,sBAAsB;IACtB,2BAA2B;CAC5B,CAAC,CAAC;AAEH,2EAA2E;AAC3E,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,YAAY,EAAE,4BAA4B,CAAC,QAAQ,EAAE;IACrD,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACzC,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC;KACjC,MAAM,CAAC;IACN,kDAAkD;IAClD,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,YAAY,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC;IACrE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,UAAU,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE;IAChC,2BAA2B;IAC3B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;IAC5C,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACrC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,+FAA+F;IAC/F,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACxC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC,QAAQ,EAAE;IACnD,qDAAqD;IACrD,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE;IACtD,mDAAmD;IACnD,cAAc,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,6BAA6B,CAAC,CAAC,QAAQ,EAAE;IAC9E,8DAA8D;IAC9D,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC/B,iEAAiE;IACjE,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;CAC5C,CAAC;KACD,QAAQ,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;AAIzB,oBAAoB"}

package/lib/core/package.dependencies.d.ts

@@ -0,0 +1,45 @@
+import type { ShipDependency } from './config.dependency.schema.js';
+import { type SfdxProject } from './sfdx-project.js';
+/** Install a specific package version by its 04t ID. */
+export type PackageIdStep = {
+    kind: 'package-id';
+    versionId: string;
+    name?: string;
+};
+/** Deploy a subdirectory from a GitHub repository as metadata, with namespace tokens injected. */
+export type MetadataStep = {
+    kind: 'metadata';
+    repoUrl: string;
+    subfolder: string;
+    namespace: string;
+    tag: string;
+    /** 04t package version ID of the release this bundle ships with — lets the installer skip it when already present. */
+    versionId: string;
+};
+/** A single resolved install or deploy step produced by the dependency resolver. */
+export type DependencyStep = PackageIdStep | MetadataStep;
+/**
+ * Resolves a `ship.yml` dependency list into a flat, ordered list of install and deploy steps.
+ *
+ * GitHub dependencies are resolved by reading the annotated tag message on the repo's latest
+ * (or pinned) release. The tag carries the package's own version_id and a pre-flattened
+ * transitive dependency list, so no recursive remote config fetching is needed. The format
+ * is inherited from CumulusCI so ship- and CCI-released packages resolve uniformly.
+ *
+ * Duplicate packages are deduplicated — the first occurrence wins. Circular GitHub repository
+ * references throw.
+ *
+ * @param deps - The top-level dependency list from `ship.yml`.
+ * @returns Ordered list of {@link DependencyStep} ready for execution.
+ */
+export declare function resolveDependencies(deps: ShipDependency[]): Promise<DependencyStep[]>;
+export type DriftResult = {
+    /** Version IDs present in ship.yml but missing from sfdx-project.json. */
+    missing: string[];
+    /** Version IDs present in sfdx-project.json but no longer in ship.yml. */
+    stale: string[];
+    /** versionId → human-readable name, gathered from both sides for use in error output. */
+    names: Map<string, string>;
+};
+/** Compares resolved ship.yml package-id steps against the dependencies committed in sfdx-project.json. */
+export declare function computeDrift(steps: PackageIdStep[], project: SfdxProject): DriftResult;

package/lib/core/package.dependencies.js

@@ -0,0 +1,158 @@
+import { ExpectedError } from './error.js';
+import { normalizeRepo, fetchRelease, fetchGitTag, fetchCciNamespace, fetchSubdirs } from './service.github.js';
+import { defaultPackageDirectory } from './sfdx-project.js';
+/**
+ * Parses a release's annotated tag message into its version ID and dependency list.
+ * Returns `null` if the message does not contain the expected structured block.
+ *
+ * The format originated with CumulusCI and is inherited unchanged so ship- and
+ * CCI-released packages resolve through the same path:
+ * ```
+ * version_id: 04tXXX
+ * package_type: 2GP
+ * dependencies: [{"version_id": "04tYYY", "package_name": "..."}]
+ * ```
+ */
+function parseTagMessage(message) {
+    const versionIdMatch = message.match(/^version_id:\s*(04t[A-Za-z0-9]{12,15})/m);
+    if (!versionIdMatch)
+        return null;
+    let dependencies = [];
+    const depsPrefixIndex = message.indexOf('dependencies:');
+    if (depsPrefixIndex !== -1) {
+        const afterDeps = message.slice(depsPrefixIndex + 'dependencies:'.length).trim();
+        if (afterDeps.startsWith('[')) {
+            try {
+                dependencies = JSON.parse(afterDeps);
+            }
+            catch {
+                // leave as empty array
+            }
+        }
+    }
+    return { versionId: versionIdMatch[1], dependencies };
+}
+/**
+ * Resolves a GitHub repository dependency into an ordered list of steps.
+ *
+ * Reads the annotated tag message on the latest (or pinned) release for the package
+ * version ID and its pre-flattened transitive dependency list, and discovers any
+ * `unpackaged/pre` / `unpackaged/post` subdirectories to deploy before and after the
+ * package install.
+ */
+async function resolveGitHubRepo(dep, visited) {
+    const { github, tag, name } = dep;
+    const repo = normalizeRepo(github);
+    // Circular dependency detection — added synchronously before the first await
+    // so it is safe to call from Promise.all.
+    if (visited.has(repo))
+        throw new ExpectedError(`Circular dependency detected: ${repo}`);
+    visited.add(repo);
+    const release = await fetchRelease(repo, tag);
+    if (!release)
+        throw new ExpectedError(`No GitHub release found for ${repo}${tag ? `@${tag}` : ''}`);
+    const [gitTag, namespace, preSubdirs, postSubdirs] = await Promise.all([
+        fetchGitTag(repo, release.tagName),
+        fetchCciNamespace(repo, release.tagName),
+        fetchSubdirs(repo, release.tagName, 'unpackaged/pre'),
+        fetchSubdirs(repo, release.tagName, 'unpackaged/post'),
+    ]);
+    const metadata = gitTag ? parseTagMessage(gitTag.message) : null;
+    if (!metadata)
+        throw new ExpectedError(`No release metadata found in tag ${release.tagName} for ${repo}`);
+    const steps = [];
+    const repoUrl = `https://github.com/${repo}`;
+    for (const subfolder of preSubdirs) {
+        const key = `${repo}:${subfolder}`;
+        if (!visited.has(key)) {
+            visited.add(key);
+            steps.push({
+                kind: 'metadata',
+                repoUrl,
+                subfolder,
+                namespace,
+                tag: release.tagName,
+                versionId: metadata.versionId,
+            });
+        }
+    }
+    for (const transitive of metadata.dependencies) {
+        if (!visited.has(transitive.version_id)) {
+            visited.add(transitive.version_id);
+            steps.push({ kind: 'package-id', versionId: transitive.version_id, name: transitive.package_name });
+        }
+    }
+    if (!visited.has(metadata.versionId)) {
+        visited.add(metadata.versionId);
+        steps.push({ kind: 'package-id', versionId: metadata.versionId, name });
+    }
+    for (const subfolder of postSubdirs) {
+        const key = `${repo}:${subfolder}`;
+        if (!visited.has(key)) {
+            visited.add(key);
+            steps.push({
+                kind: 'metadata',
+                repoUrl,
+                subfolder,
+                namespace,
+                tag: release.tagName,
+                versionId: metadata.versionId,
+            });
+        }
+    }
+    return steps;
+}
+/** Resolves a list of plugin-ship dependencies into an ordered list of steps. */
+async function resolveShipDeps(deps, visited) {
+    return (await Promise.all(deps.map((dep) => {
+        // Resolve GitHub dependency
+        if ('github' in dep) {
+            return resolveGitHubRepo(dep, visited);
+        }
+        // Resolve 04t dependency
+        if (visited.has(dep.versionId))
+            return [];
+        visited.add(dep.versionId);
+        return [{ kind: 'package-id', versionId: dep.versionId, name: dep.name }];
+    }))).flat();
+}
+/**
+ * Resolves a `ship.yml` dependency list into a flat, ordered list of install and deploy steps.
+ *
+ * GitHub dependencies are resolved by reading the annotated tag message on the repo's latest
+ * (or pinned) release. The tag carries the package's own version_id and a pre-flattened
+ * transitive dependency list, so no recursive remote config fetching is needed. The format
+ * is inherited from CumulusCI so ship- and CCI-released packages resolve uniformly.
+ *
+ * Duplicate packages are deduplicated — the first occurrence wins. Circular GitHub repository
+ * references throw.
+ *
+ * @param deps - The top-level dependency list from `ship.yml`.
+ * @returns Ordered list of {@link DependencyStep} ready for execution.
+ */
+export async function resolveDependencies(deps) {
+    return resolveShipDeps(deps, new Set());
+}
+/** Compares resolved ship.yml package-id steps against the dependencies committed in sfdx-project.json. */
+export function computeDrift(steps, project) {
+    const expected = new Set(steps.map((s) => s.versionId));
+    const names = new Map();
+    for (const step of steps) {
+        if (step.name)
+            names.set(step.versionId, step.name);
+    }
+    const aliases = project.packageAliases ?? {};
+    const committed = new Set();
+    for (const dep of defaultPackageDirectory(project)?.dependencies ?? []) {
+        const versionId = aliases[dep.package] ?? dep.package;
+        committed.add(versionId);
+        if (dep.package !== versionId && !names.has(versionId))
+            names.set(versionId, dep.package);
+    }
+    return {
+        missing: [...expected].filter((id) => !committed.has(id)),
+        stale: [...committed].filter((id) => !expected.has(id)),
+        names,
+    };
+}
+//# sourceMappingURL=package.dependencies.js.map

package/lib/core/package.dependencies.js.map

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

package/lib/core/package.installer.d.ts

@@ -0,0 +1,13 @@
+import type { ShipDependency } from './config.dependency.schema.js';
+import { type DependencyStep } from './package.dependencies.js';
+export declare function describeStep(step: DependencyStep): string;
+export type InstallDependenciesOptions = {
+    alias: string | undefined;
+    wait: number;
+    dryRun: boolean;
+    force: boolean;
+    shipDir: string;
+    log: (msg: string) => void;
+    runCommand: (id: string, argv: string[]) => Promise<unknown>;
+};
+export declare function installDependencies(deps: ShipDependency[], options: InstallDependenciesOptions): Promise<void>;