@sfship/plugin-ship 1.0.0-beta.2

package/lib/commands/ship/task/list.js

@@ -0,0 +1,45 @@
+/*
+ * 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 { SfCommand, Flags, StandardColors } from '@salesforce/sf-plugins-core';
+import { Messages } from '@salesforce/core';
+import { loadConfig, resolveProjectPaths } from '../../../core/config.loader.js';
+import { TaskRegistry } from '../../../core/task.registry.js';
+import { renderTree } from '../../../core/tree.js';
+Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+const messages = Messages.loadMessages('@sfship/plugin-ship', 'ship.task.list');
+/** Lists all available tasks. */
+export default class TaskList extends SfCommand {
+    static summary = messages.getMessage('summary');
+    static description = messages.getMessage('description');
+    static examples = messages.getMessages('examples');
+    static flags = {
+        config: Flags.file({ default: 'ship.yml', summary: messages.getMessage('flags.config.summary') }),
+    };
+    static enableJsonFlag = false;
+    async run() {
+        const { flags } = await this.parse(TaskList);
+        const config = loadConfig(flags.config);
+        const { shipDir } = resolveProjectPaths(flags.config, config);
+        const tasks = new TaskRegistry(shipDir).list();
+        this.log('');
+        this.styledHeader('Task List');
+        this.log(renderTree(tasks));
+        this.log(StandardColors.info('Tip:') +
+            ' Run ' +
+            StandardColors.success('sf ship task info <path>') +
+            ' to see full details for a task.');
+        this.log('');
+    }
+}
+//# sourceMappingURL=list.js.map

package/lib/commands/ship/task/list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../../../src/commands/ship/task/list.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC/E,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAEnD,QAAQ,CAAC,kCAAkC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC7D,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,qBAAqB,EAAE,gBAAgB,CAAC,CAAC;AAEhF,iCAAiC;AACjC,MAAM,CAAC,OAAO,OAAO,QAAS,SAAQ,SAAe;IAC5C,MAAM,CAAU,OAAO,GAAG,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IACzD,MAAM,CAAU,WAAW,GAAG,QAAQ,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IACjE,MAAM,CAAU,QAAQ,GAAG,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;IAE5D,MAAM,CAAU,KAAK,GAAG;QAC7B,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,sBAAsB,CAAC,EAAE,CAAC;KAClG,CAAC;IAEK,MAAM,CAAU,cAAc,GAAG,KAAK,CAAC;IAEvC,KAAK,CAAC,GAAG;QACd,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC7C,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,EAAE,OAAO,EAAE,GAAG,mBAAmB,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAE9D,MAAM,KAAK,GAAG,IAAI,YAAY,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;QAE/C,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACb,IAAI,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;QAC/B,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;QAC5B,IAAI,CAAC,GAAG,CACN,cAAc,CAAC,IAAI,CAAC,MAAM,CAAC;YACzB,OAAO;YACP,cAAc,CAAC,OAAO,CAAC,0BAA0B,CAAC;YAClD,kCAAkC,CACrC,CAAC;QACF,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACf,CAAC"}

package/lib/commands/ship/task/run.d.ts

@@ -0,0 +1,16 @@
+import { SfCommand } from '@salesforce/sf-plugins-core';
+/** Runs a single task directly, outside of a flow. */
+export default class TaskRun extends SfCommand<void> {
+    static readonly summary: string;
+    static readonly description: string;
+    static readonly examples: string[];
+    static readonly args: {
+        taskName: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static readonly flags: {
+        config: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        param: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static readonly enableJsonFlag = false;
+    run(): Promise<void>;
+}

package/lib/commands/ship/task/run.js

@@ -0,0 +1,72 @@
+/*
+ * 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 { Args } from '@oclif/core';
+import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
+import { Messages } from '@salesforce/core';
+import { loadConfig, resolveProjectPaths } from '../../../core/config.loader.js';
+import { formatTaskPreview } from '../../../core/task.view.js';
+import { createFlowContext } from '../../../core/flow.context.js';
+import { parseCliParams, validateParams } from '../../../core/task.param.js';
+import { OrgRegistry } from '../../../core/org.registry.js';
+import { TaskRegistry } from '../../../core/task.registry.js';
+import { Store } from '../../../core/flow.store.js';
+import { handleError } from '../../../core/error.js';
+Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+const messages = Messages.loadMessages('@sfship/plugin-ship', 'ship.task.run');
+/** Runs a single task directly, outside of a flow. */
+export default class TaskRun extends SfCommand {
+    static summary = messages.getMessage('summary');
+    static description = messages.getMessage('description');
+    static examples = messages.getMessages('examples');
+    static args = {
+        taskName: Args.string({ description: messages.getMessage('args.taskName.summary'), required: true }),
+    };
+    static flags = {
+        config: Flags.file({ default: 'ship.yml', summary: messages.getMessage('flags.config.summary') }),
+        param: Flags.string({ summary: messages.getMessage('flags.param.summary'), multiple: true }),
+    };
+    static enableJsonFlag = false;
+    async run() {
+        const { args, flags } = await this.parse(TaskRun);
+        const params = parseCliParams(flags.param ?? []);
+        const config = loadConfig(flags.config);
+        const { projectDir, shipDir } = resolveProjectPaths(flags.config, config);
+        const context = createFlowContext({
+            projectDir,
+            shipDir,
+            config,
+            orgs: new OrgRegistry(resolve(shipDir, 'orgs'), config.project.slug),
+            log: (message) => this.log(message),
+            params,
+            runCommand: (id, argv) => this.config.runCommand(id, argv),
+        });
+        const runner = new TaskRegistry(shipDir);
+        const task = await runner.resolveTask(args.taskName);
+        this.log('');
+        this.log(formatTaskPreview(task));
+        const validatedParams = validateParams(params, task.params);
+        const store = new Store();
+        const output = store.getTaskOutput(args.taskName);
+        const taskContext = { flow: context, params: validatedParams, output };
+        try {
+            await task.run(taskContext);
+        }
+        catch (err) {
+            handleError(err, (msg) => this.log(msg));
+        }
+        this.log('');
+    }
+}
+//# sourceMappingURL=run.js.map

package/lib/commands/ship/task/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../../../src/commands/ship/task/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AACjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAE9D,OAAO,EAAE,KAAK,EAAE,MAAM,6BAA6B,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAErD,QAAQ,CAAC,kCAAkC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC7D,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,qBAAqB,EAAE,eAAe,CAAC,CAAC;AAE/E,sDAAsD;AACtD,MAAM,CAAC,OAAO,OAAO,OAAQ,SAAQ,SAAe;IAC3C,MAAM,CAAU,OAAO,GAAG,QAAQ,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IACzD,MAAM,CAAU,WAAW,GAAG,QAAQ,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IACjE,MAAM,CAAU,QAAQ,GAAG,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;IAE5D,MAAM,CAAU,IAAI,GAAG;QAC5B,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,QAAQ,CAAC,UAAU,CAAC,uBAAuB,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;KACrG,CAAC;IAEK,MAAM,CAAU,KAAK,GAAG;QAC7B,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,sBAAsB,CAAC,EAAE,CAAC;QACjG,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,UAAU,CAAC,qBAAqB,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;KAC7F,CAAC;IAEK,MAAM,CAAU,cAAc,GAAG,KAAK,CAAC;IAEvC,KAAK,CAAC,GAAG;QACd,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAElD,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;QACjD,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACxC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,mBAAmB,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAE1E,MAAM,OAAO,GAAG,iBAAiB,CAAC;YAChC,UAAU;YACV,OAAO;YACP,MAAM;YACN,IAAI,EAAE,IAAI,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;YACpE,GAAG,EAAE,CAAC,OAAe,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC;YAC3C,MAAM;YACN,UAAU,EAAE,CAAC,EAAU,EAAE,IAAc,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,EAAE,IAAI,CAAC;SAC7E,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,OAAO,CAAC,CAAC;QACzC,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAErD,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACb,IAAI,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC;QAClC,MAAM,eAAe,GAAG,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAE5D,MAAM,KAAK,GAAG,IAAI,KAAK,EAAE,CAAC;QAC1B,MAAM,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAClD,MAAM,WAAW,GAAgB,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,CAAC;QAEpF,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAC9B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,WAAW,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;QAC3C,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACf,CAAC"}

package/lib/core/config.dependency.schema.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+/** A plugin-ship GitHub repository dependency. Resolves via the annotated tag message on the latest (or pinned) release. */
+export declare const ShipGitHubDependencySchema: z.ZodObject<{
+    github: z.ZodString;
+    tag: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** A plugin-ship package dependency identified by package version ID. */
+export declare const ShipPackageIdDependencySchema: z.ZodObject<{
+    versionId: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** A single entry in a `ship.yml` dependency list. */
+export declare const ShipDependencySchema: z.ZodUnion<readonly [z.ZodObject<{
+    github: z.ZodString;
+    tag: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    versionId: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>]>;
+export type ShipGitHubDependency = z.infer<typeof ShipGitHubDependencySchema>;
+export type ShipPackageIdDependency = z.infer<typeof ShipPackageIdDependencySchema>;
+export type ShipDependency = z.infer<typeof ShipDependencySchema>;

package/lib/core/config.dependency.schema.js

@@ -0,0 +1,34 @@
+/*
+ * 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';
+/** A plugin-ship GitHub repository dependency. Resolves via the annotated tag message on the latest (or pinned) release. */
+export const ShipGitHubDependencySchema = z.object({
+    /** GitHub repository as a full URL or `owner/repo` slug. */
+    github: z.string(),
+    /** Pin to a specific release tag instead of resolving to latest. */
+    tag: z.string().optional(),
+    /** Human-readable label for this dependency, used to name the repo's own package step in log output. */
+    name: z.string().optional(),
+});
+/** A plugin-ship package dependency identified by package version ID. */
+export const ShipPackageIdDependencySchema = z.object({
+    /** The 04t package version ID. */
+    versionId: z.string(),
+    /** Human-readable label used in log output. */
+    name: z.string().optional(),
+});
+/** A single entry in a `ship.yml` dependency list. */
+export const ShipDependencySchema = z.union([ShipGitHubDependencySchema, ShipPackageIdDependencySchema]);
+/* c8 ignore stop */
+//# sourceMappingURL=config.dependency.schema.js.map

package/lib/core/config.dependency.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.dependency.schema.js","sourceRoot":"","sources":["../../src/core/config.dependency.schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,4HAA4H;AAC5H,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,4DAA4D;IAC5D,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,oEAAoE;IACpE,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC1B,wGAAwG;IACxG,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC5B,CAAC,CAAC;AAEH,yEAAyE;AACzE,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC;IACpD,kCAAkC;IAClC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,+CAA+C;IAC/C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC5B,CAAC,CAAC;AAEH,sDAAsD;AACtD,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,0BAA0B,EAAE,6BAA6B,CAAC,CAAC,CAAC;AAKzG,oBAAoB"}

package/lib/core/config.loader.d.ts

@@ -0,0 +1,23 @@
+import { ShipConfig } from './config.ship.schema.js';
+/**
+ * Reads and parses a `ship.yml` config file, validating it against {@link ShipConfigSchema}.
+ *
+ * @param configPath - Path to the config file. Defaults to `'ship.yml'` in the current directory.
+ * @returns The validated {@link ShipConfig}.
+ * @throws If the file cannot be read or fails schema validation.
+ */
+export declare function loadConfig(configPath?: string): ShipConfig;
+/**
+ * Resolves a project's directory layout from the path to its `ship.yml`.
+ *
+ * `projectDir` is the directory containing the config file; `shipDir` is
+ * `config.dir` resolved relative to it. Every command goes through this so
+ * `.ship` is located the same way regardless of the process's working directory.
+ *
+ * @param configPath - The `--config` path to the `ship.yml` file.
+ * @param config - The loaded config, for its `dir` setting.
+ */
+export declare function resolveProjectPaths(configPath: string, config: ShipConfig): {
+    projectDir: string;
+    shipDir: string;
+};

package/lib/core/config.loader.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 { dirname, join, resolve } from 'node:path';
+import { parse } from 'yaml';
+import { ShipConfigSchema } from './config.ship.schema.js';
+import { readText } from './file.js';
+import { ExpectedError, formatZodError } from './error.js';
+/**
+ * Reads and parses a `ship.yml` config file, validating it against {@link ShipConfigSchema}.
+ *
+ * @param configPath - Path to the config file. Defaults to `'ship.yml'` in the current directory.
+ * @returns The validated {@link ShipConfig}.
+ * @throws If the file cannot be read or fails schema validation.
+ */
+export function loadConfig(configPath = 'ship.yml') {
+    let raw;
+    try {
+        raw = readText(configPath);
+    }
+    catch {
+        throw new ExpectedError(`No ship.yml found at ${configPath}`);
+    }
+    let parsed;
+    try {
+        parsed = parse(raw);
+    }
+    catch (err) {
+        throw new ExpectedError(`Could not parse ship.yml: ${err.message}`);
+    }
+    try {
+        return ShipConfigSchema.parse(parsed);
+    }
+    catch (err) {
+        throw new ExpectedError(`Invalid ship.yml:\n${formatZodError(err)}`);
+    }
+}
+/**
+ * Resolves a project's directory layout from the path to its `ship.yml`.
+ *
+ * `projectDir` is the directory containing the config file; `shipDir` is
+ * `config.dir` resolved relative to it. Every command goes through this so
+ * `.ship` is located the same way regardless of the process's working directory.
+ *
+ * @param configPath - The `--config` path to the `ship.yml` file.
+ * @param config - The loaded config, for its `dir` setting.
+ */
+export function resolveProjectPaths(configPath, config) {
+    const projectDir = resolve(dirname(configPath));
+    return { projectDir, shipDir: join(projectDir, config.dir) };
+}
+//# sourceMappingURL=config.loader.js.map

package/lib/core/config.loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.loader.js","sourceRoot":"","sources":["../../src/core/config.loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAc,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,aAAqB,UAAU;IACxD,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,aAAa,CAAC,wBAAwB,UAAU,EAAE,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;IACtB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,aAAa,CAAC,6BAA8B,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IACjF,CAAC;IAED,IAAI,CAAC;QACH,OAAO,gBAAgB,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,aAAa,CAAC,sBAAsB,cAAc,CAAC,GAAe,CAAC,EAAE,CAAC,CAAC;IACnF,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAAkB,EAAE,MAAkB;IACxE,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;IAChD,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;AAC/D,CAAC"}

package/lib/core/config.ship.schema.d.ts

@@ -0,0 +1,174 @@
+import { z } from 'zod';
+import { ShipDependency } from './config.dependency.schema.js';
+/** Salesforce packaging metadata for the project. */
+declare const ProjectPackageConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    namespace: z.ZodOptional<z.ZodString>;
+    type: z.ZodEnum<{
+        Managed: "Managed";
+        Unlocked: "Unlocked";
+    }>;
+    permsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    testPattern: z.ZodDefault<z.ZodString>;
+    dependencies: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        github: z.ZodString;
+        tag: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        versionId: z.ZodString;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>>;
+}, z.core.$strict>;
+/** Git/GitHub configuration for the project. */
+declare const ProjectGitConfigSchema: z.ZodObject<{
+    defaultBranch: z.ZodOptional<z.ZodString>;
+    repoUrl: z.ZodOptional<z.ZodURL>;
+}, z.core.$strip>;
+/** Top-level project metadata within a ship config. */
+declare const ProjectConfigSchema: z.ZodPipe<z.ZodObject<{
+    slug: z.ZodOptional<z.ZodString>;
+    package: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        namespace: z.ZodOptional<z.ZodString>;
+        type: z.ZodEnum<{
+            Managed: "Managed";
+            Unlocked: "Unlocked";
+        }>;
+        permsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        testPattern: z.ZodDefault<z.ZodString>;
+        dependencies: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+            github: z.ZodString;
+            tag: z.ZodOptional<z.ZodString>;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            versionId: z.ZodString;
+            name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>]>>>;
+    }, z.core.$strict>>;
+    git: z.ZodOptional<z.ZodObject<{
+        defaultBranch: z.ZodOptional<z.ZodString>;
+        repoUrl: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strip>>;
+}, z.core.$strict>, z.ZodTransform<{
+    slug: string;
+    package?: {
+        name: string;
+        type: "Managed" | "Unlocked";
+        testPattern: string;
+        namespace?: string | undefined;
+        permsets?: string[] | undefined;
+        dependencies?: ({
+            github: string;
+            tag?: string | undefined;
+            name?: string | undefined;
+        } | {
+            versionId: string;
+            name?: string | undefined;
+        })[] | undefined;
+    } | undefined;
+    git?: {
+        defaultBranch?: string | undefined;
+        repoUrl?: string | undefined;
+    } | undefined;
+}, {
+    slug?: string | undefined;
+    package?: {
+        name: string;
+        type: "Managed" | "Unlocked";
+        testPattern: string;
+        namespace?: string | undefined;
+        permsets?: string[] | undefined;
+        dependencies?: ({
+            github: string;
+            tag?: string | undefined;
+            name?: string | undefined;
+        } | {
+            versionId: string;
+            name?: string | undefined;
+        })[] | undefined;
+    } | undefined;
+    git?: {
+        defaultBranch?: string | undefined;
+        repoUrl?: string | undefined;
+    } | undefined;
+}>>;
+/**
+ * Zod schema for the top-level `ship.yml`.
+ * Defines the project and optional ship directory override.
+ */
+export declare const ShipConfigSchema: z.ZodObject<{
+    project: z.ZodPipe<z.ZodObject<{
+        slug: z.ZodOptional<z.ZodString>;
+        package: z.ZodOptional<z.ZodObject<{
+            name: z.ZodString;
+            namespace: z.ZodOptional<z.ZodString>;
+            type: z.ZodEnum<{
+                Managed: "Managed";
+                Unlocked: "Unlocked";
+            }>;
+            permsets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            testPattern: z.ZodDefault<z.ZodString>;
+            dependencies: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                github: z.ZodString;
+                tag: z.ZodOptional<z.ZodString>;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>, z.ZodObject<{
+                versionId: z.ZodString;
+                name: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>]>>>;
+        }, z.core.$strict>>;
+        git: z.ZodOptional<z.ZodObject<{
+            defaultBranch: z.ZodOptional<z.ZodString>;
+            repoUrl: z.ZodOptional<z.ZodURL>;
+        }, z.core.$strip>>;
+    }, z.core.$strict>, z.ZodTransform<{
+        slug: string;
+        package?: {
+            name: string;
+            type: "Managed" | "Unlocked";
+            testPattern: string;
+            namespace?: string | undefined;
+            permsets?: string[] | undefined;
+            dependencies?: ({
+                github: string;
+                tag?: string | undefined;
+                name?: string | undefined;
+            } | {
+                versionId: string;
+                name?: string | undefined;
+            })[] | undefined;
+        } | undefined;
+        git?: {
+            defaultBranch?: string | undefined;
+            repoUrl?: string | undefined;
+        } | undefined;
+    }, {
+        slug?: string | undefined;
+        package?: {
+            name: string;
+            type: "Managed" | "Unlocked";
+            testPattern: string;
+            namespace?: string | undefined;
+            permsets?: string[] | undefined;
+            dependencies?: ({
+                github: string;
+                tag?: string | undefined;
+                name?: string | undefined;
+            } | {
+                versionId: string;
+                name?: string | undefined;
+            })[] | undefined;
+        } | undefined;
+        git?: {
+            defaultBranch?: string | undefined;
+            repoUrl?: string | undefined;
+        } | undefined;
+    }>>;
+    dir: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>;
+export type { ShipDependency };
+export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
+export type ProjectPackageConfig = z.infer<typeof ProjectPackageConfigSchema>;
+export type ProjectGitConfig = z.infer<typeof ProjectGitConfigSchema>;
+/** The validated top-level ship configuration, inferred from {@link ShipConfigSchema}. */
+export type ShipConfig = z.infer<typeof ShipConfigSchema>;

package/lib/core/config.ship.schema.js

@@ -0,0 +1,67 @@
+/*
+ * 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';
+import { ShipDependencySchema } from './config.dependency.schema.js';
+/** Salesforce packaging metadata for the project. */
+const ProjectPackageConfigSchema = z
+    .object({
+    /** The package name as it appears in the Salesforce packaging UI. */
+    name: z.string(),
+    /** The package namespace. */
+    namespace: z.string().optional(),
+    type: z.enum(['Managed', 'Unlocked']),
+    /** Permission sets (and/or permission set groups) to assign to the running user after package install in flow contexts. */
+    permsets: z.array(z.string()).optional(),
+    /** Glob pattern used to discover Apex test classes. Defaults to "*_Test". */
+    testPattern: z.string().default('*_Test'),
+    /** Packages to install before deploying or packaging. */
+    dependencies: z.array(ShipDependencySchema).optional(),
+})
+    .strict();
+/** Git/GitHub configuration for the project. */
+const ProjectGitConfigSchema = z.object({
+    /** The main branch name. Defaults to `main`. */
+    defaultBranch: z.string().optional(),
+    /** The GitHub repository URL. */
+    repoUrl: z.url().optional(),
+});
+/** Top-level project metadata within a ship config. */
+const ProjectConfigSchema = z
+    .object({
+    /** URL/alias-safe slug used as a prefix for generated org aliases. Defaults to package.name lowercased with spaces replaced by hyphens. */
+    slug: z.string().optional(),
+    /** Optional Salesforce package metadata. */
+    package: ProjectPackageConfigSchema.optional(),
+    /** Optional Git repository configuration. */
+    git: ProjectGitConfigSchema.optional(),
+})
+    .strict()
+    .transform((data) => ({
+    ...data,
+    slug: data.slug ?? data.package?.name?.toLowerCase().replace(/\s+/g, '-') ?? 'project',
+}));
+/**
+ * Zod schema for the top-level `ship.yml`.
+ * Defines the project and optional ship directory override.
+ */
+export const ShipConfigSchema = z
+    .object({
+    /** Project metadata. */
+    project: ProjectConfigSchema,
+    /** Directory used to resolve custom tasks, scratch-org defs, and other ship assets. Defaults to `.ship`. */
+    dir: z.string().default('.ship'),
+})
+    .strict();
+/* c8 ignore stop */
+//# sourceMappingURL=config.ship.schema.js.map

package/lib/core/config.ship.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.ship.schema.js","sourceRoot":"","sources":["../../src/core/config.ship.schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAkB,MAAM,+BAA+B,CAAC;AAErF,qDAAqD;AACrD,MAAM,0BAA0B,GAAG,CAAC;KACjC,MAAM,CAAC;IACN,qEAAqE;IACrE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,6BAA6B;IAC7B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACrC,2HAA2H;IAC3H,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACxC,6EAA6E;IAC7E,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC;IACzC,yDAAyD;IACzD,YAAY,EAAE,CAAC,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,QAAQ,EAAE;CACvD,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,gDAAgD;AAChD,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,gDAAgD;IAChD,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACpC,iCAAiC;IACjC,OAAO,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CAC5B,CAAC,CAAC;AAEH,uDAAuD;AACvD,MAAM,mBAAmB,GAAG,CAAC;KAC1B,MAAM,CAAC;IACN,2IAA2I;IAC3I,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC3B,4CAA4C;IAC5C,OAAO,EAAE,0BAA0B,CAAC,QAAQ,EAAE;IAC9C,6CAA6C;IAC7C,GAAG,EAAE,sBAAsB,CAAC,QAAQ,EAAE;CACvC,CAAC;KACD,MAAM,EAAE;KACR,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACpB,GAAG,IAAI;IACP,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,IAAI,SAAS;CACvF,CAAC,CAAC,CAAC;AAEN;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC;KAC9B,MAAM,CAAC;IACN,wBAAwB;IACxB,OAAO,EAAE,mBAAmB;IAC5B,4GAA4G;IAC5G,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC;CACjC,CAAC;KACD,MAAM,EAAE,CAAC;AAQZ,oBAAoB"}

package/lib/core/error.d.ts

@@ -0,0 +1,29 @@
+import { ZodError } from 'zod';
+/**
+ * Coerces an unknown caught value into an `Error`.
+ * Returns the original instance if it is already an `Error`; otherwise wraps it with `String()`.
+ *
+ * @param err - The value caught in a `catch` block.
+ */
+export declare function asError(err: unknown): Error;
+/**
+ * Formats a ZodError into a human-readable string for display in CLI output.
+ *
+ * @param err - The ZodError to format.
+ */
+export declare function formatZodError(err: ZodError): string;
+/**
+ * An error thrown when a known, user-facing failure occurs — invalid input,
+ * missing config, etc. The flow renderer suppresses the stack trace for these
+ * since they indicate a user mistake rather than an unexpected bug.
+ */
+export declare class ExpectedError extends Error {
+}
+/**
+ * Handles a caught error uniformly.
+ * - `ExpectedError`: prints the message and exits with code 1 (no stack trace).
+ * - Anything else: rethrows so the caller sees a full stack trace.
+ *
+ * @param err - The value caught in a `catch` block.
+ */
+export declare function handleError(err: unknown, log: (message: string) => void): never;

package/lib/core/error.js

@@ -0,0 +1,59 @@
+/**
+ * Coerces an unknown caught value into an `Error`.
+ * Returns the original instance if it is already an `Error`; otherwise wraps it with `String()`.
+ *
+ * @param err - The value caught in a `catch` block.
+ */
+export function asError(err) {
+    return err instanceof Error ? err : new Error(String(err));
+}
+function formatIssue(issue, pathPrefix = []) {
+    const fullPath = [...pathPrefix, ...issue.path].join('.');
+    const label = fullPath || '(root)';
+    if (issue.code === 'invalid_union' && issue.errors?.length) {
+        const variants = issue.errors
+            .map((variantIssues) => {
+            const first = variantIssues[0];
+            // c8 ignore next — Zod always provides at least one issue per union variant
+            if (!first)
+                return null;
+            const variantPath = [...pathPrefix, ...issue.path, ...first.path].join('.');
+            return `      ${variantPath || '(root)'}: ${first.message}`;
+        })
+            .filter(Boolean)
+            .join('\n');
+        return `  - ${label}: Invalid input — expected one of:\n${variants}`;
+    }
+    return `  - ${label}: ${issue.message}`;
+}
+/**
+ * Formats a ZodError into a human-readable string for display in CLI output.
+ *
+ * @param err - The ZodError to format.
+ */
+export function formatZodError(err) {
+    return err.issues.map((i) => formatIssue(i)).join('\n');
+}
+/**
+ * An error thrown when a known, user-facing failure occurs — invalid input,
+ * missing config, etc. The flow renderer suppresses the stack trace for these
+ * since they indicate a user mistake rather than an unexpected bug.
+ */
+export class ExpectedError extends Error {
+}
+/**
+ * Handles a caught error uniformly.
+ * - `ExpectedError`: prints the message and exits with code 1 (no stack trace).
+ * - Anything else: rethrows so the caller sees a full stack trace.
+ *
+ * @param err - The value caught in a `catch` block.
+ */
+export function handleError(err, log) {
+    const error = asError(err);
+    if (error instanceof ExpectedError) {
+        log(error.message);
+        process.exit(1);
+    }
+    throw error;
+}
+//# sourceMappingURL=error.js.map

package/lib/core/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../../src/core/error.ts"],"names":[],"mappings":"AAeA;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,GAAY;IAClC,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;AAC7D,CAAC;AAID,SAAS,WAAW,CAAC,KAAe,EAAE,aAAqC,EAAE;IAC3E,MAAM,QAAQ,GAAG,CAAC,GAAG,UAAU,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1D,MAAM,KAAK,GAAG,QAAQ,IAAI,QAAQ,CAAC;IAEnC,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,IAAI,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAC3D,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM;aAC1B,GAAG,CAAC,CAAC,aAAa,EAAE,EAAE;YACrB,MAAM,KAAK,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC;YAC/B,4EAA4E;YAC5E,IAAI,CAAC,KAAK;gBAAE,OAAO,IAAI,CAAC;YACxB,MAAM,WAAW,GAAG,CAAC,GAAG,UAAU,EAAE,GAAG,KAAK,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC5E,OAAO,SAAS,WAAW,IAAI,QAAQ,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;QAC9D,CAAC,CAAC;aACD,MAAM,CAAC,OAAO,CAAC;aACf,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,OAAO,OAAO,KAAK,uCAAuC,QAAQ,EAAE,CAAC;IACvE,CAAC;IAED,OAAO,OAAO,KAAK,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;AAC1C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,GAAa;IAC1C,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAa,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACtE,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,aAAc,SAAQ,KAAK;CAAG;AAE3C;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,GAAY,EAAE,GAA8B;IACtE,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC3B,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;QACnC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,MAAM,KAAK,CAAC;AACd,CAAC"}