@sfship/plugin-ship 1.0.0-beta.2

package/lib/core/task.output.js

@@ -0,0 +1,39 @@
+/**
+ * Task-facing output API. Passed into `TaskContext` so tasks can read and write
+ * step outputs without holding a reference to the full `Store`.
+ *
+ * - `get(key)` — reads this step's own output.
+ * - `get(stepId, key)` — reads another step's output by its ID.
+ * - `set(key, value)` — writes a named output value under this step's namespace.
+ */
+export class TaskOutput {
+    stepId;
+    store;
+    constructor(stepId, store) {
+        this.stepId = stepId;
+        this.store = store;
+    }
+    /**
+     * Writes a named output value under this step's namespace,
+     * making it available to subsequent steps via `${{ steps.<id>.<key> }}`.
+     *
+     * @param key - The output key.
+     * @param value - The value to store.
+     */
+    set(key, value) {
+        this.store.set(this.stepId, key, value);
+    }
+    /**
+     * Reads an output value.
+     *
+     * @param keyOrStepId - The output key (own step) or step ID (other step).
+     * @param key - The output key when reading from another step.
+     */
+    get(keyOrStepId, key) {
+        if (key === undefined) {
+            return this.store.get(this.stepId, keyOrStepId);
+        }
+        return this.store.get(keyOrStepId, key);
+    }
+}
+//# sourceMappingURL=task.output.js.map

package/lib/core/task.output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.output.js","sourceRoot":"","sources":["../../src/core/task.output.ts"],"names":[],"mappings":"AAeA;;;;;;;GAOG;AACH,MAAM,OAAO,UAAU;IACe;IAAiC;IAArE,YAAoC,MAAc,EAAmB,KAAY;QAA7C,WAAM,GAAN,MAAM,CAAQ;QAAmB,UAAK,GAAL,KAAK,CAAO;IAAG,CAAC;IAErF;;;;;;OAMG;IACI,GAAG,CAAC,GAAW,EAAE,KAAc;QACpC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED;;;;;OAKG;IACI,GAAG,CAAC,WAAmB,EAAE,GAAY;QAC1C,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACtB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QAClD,CAAC;QACD,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;IAC1C,CAAC;CACF"}

package/lib/core/task.param.d.ts

@@ -0,0 +1,30 @@
+import type { ParamValue, ParamDefinition, Params } from './task.param.schema.js';
+export type { ParamValue, ParamDefinition, Params };
+/**
+ * Validates and coerces raw key/value input against a param schema.
+ * Applies defaults, checks for missing required params, and coerces types —
+ * so string values from CLI flags are automatically parsed into the declared type.
+ *
+ * @param rawParams - Unvalidated input, typically from user CLI flags or flow config.
+ * @param paramDefinitions - The schema to validate against.
+ * @returns A fully resolved `Params` object containing only declared params.
+ * @throws If a required param is missing or a value cannot be coerced to the declared type.
+ */
+export declare function validateParams(rawParams: Record<string, unknown>, paramDefinitions: ParamDefinition[]): Params;
+/**
+ * Parses an array of "key=value" CLI flag strings into a params object.
+ * Supports dotted notation for record params: "tokens.FOO=bar" becomes { tokens: { FOO: "bar" } }.
+ */
+export declare function parseCliParams(flags: string[]): Record<string, string | Record<string, string>>;
+/**
+ * Builds an argv array for a passthrough sf CLI command from a resolved params object.
+ *
+ * Each param becomes `--key value` (string/number) or `--key` (boolean true).
+ * Keys present in `overrides` are skipped from the params scan and replaced with
+ * the provided value instead — pass `null` to omit a key entirely.
+ *
+ * @param params - The resolved params from the task context.
+ * @param overrides - Per-key replacements or nulls to skip.
+ * @returns A flat argv array ready to pass to `runCommand`.
+ */
+export declare function resolvePassthroughArgs(params: Params, overrides?: Record<string, string | null>): string[];

package/lib/core/task.param.js

@@ -0,0 +1,141 @@
+/*
+ * 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 { ExpectedError } from './error.js';
+/**
+ * Validates and coerces raw key/value input against a param schema.
+ * Applies defaults, checks for missing required params, and coerces types —
+ * so string values from CLI flags are automatically parsed into the declared type.
+ *
+ * @param rawParams - Unvalidated input, typically from user CLI flags or flow config.
+ * @param paramDefinitions - The schema to validate against.
+ * @returns A fully resolved `Params` object containing only declared params.
+ * @throws If a required param is missing or a value cannot be coerced to the declared type.
+ */
+export function validateParams(rawParams, paramDefinitions) {
+    const resolved = {};
+    const missing = paramDefinitions.filter((d) => d.required && (rawParams[d.name] ?? d.default) === undefined);
+    if (missing.length) {
+        const list = missing.map((p) => `  ${p.name}`).join('\n');
+        throw new ExpectedError(`Missing required params:\n${list}`);
+    }
+    for (const definition of paramDefinitions) {
+        const val = rawParams[definition.name] ?? definition.default;
+        if (val !== undefined) {
+            if (!isParamValue(val)) {
+                throw new ExpectedError(`Param "${definition.name}" must be a string, number, boolean, or record`);
+            }
+            resolved[definition.name] = coerce(val, definition);
+        }
+    }
+    return resolved;
+}
+/**
+ * Parses an array of "key=value" CLI flag strings into a params object.
+ * Supports dotted notation for record params: "tokens.FOO=bar" becomes { tokens: { FOO: "bar" } }.
+ */
+export function parseCliParams(flags) {
+    const result = {};
+    for (const flag of flags) {
+        const i = flag.indexOf('=');
+        const key = i === -1 ? flag : flag.slice(0, i);
+        const value = i === -1 ? 'true' : flag.slice(i + 1);
+        const dot = key.indexOf('.');
+        if (dot !== -1) {
+            const parent = key.slice(0, dot);
+            const child = key.slice(dot + 1);
+            const existing = result[parent];
+            const record = typeof existing === 'object' ? existing : {};
+            record[child] = value;
+            result[parent] = record;
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Builds an argv array for a passthrough sf CLI command from a resolved params object.
+ *
+ * Each param becomes `--key value` (string/number) or `--key` (boolean true).
+ * Keys present in `overrides` are skipped from the params scan and replaced with
+ * the provided value instead — pass `null` to omit a key entirely.
+ *
+ * @param params - The resolved params from the task context.
+ * @param overrides - Per-key replacements or nulls to skip.
+ * @returns A flat argv array ready to pass to `runCommand`.
+ */
+export function resolvePassthroughArgs(params, overrides = {}) {
+    const merged = {};
+    for (const [key, value] of Object.entries(params)) {
+        if (typeof value !== 'object')
+            merged[key] = value;
+    }
+    for (const [flag, value] of Object.entries(overrides)) {
+        const key = flag.startsWith('--') ? flag.slice(2) : flag;
+        merged[key] = value;
+    }
+    const argv = [];
+    for (const [key, value] of Object.entries(merged)) {
+        if (value === null)
+            continue;
+        if (typeof value === 'boolean') {
+            if (value)
+                argv.push(`--${key}`);
+        }
+        else {
+            argv.push(`--${key}`, String(value));
+        }
+    }
+    return argv;
+}
+function isParamValue(val) {
+    if (typeof val === 'string' || typeof val === 'number' || typeof val === 'boolean')
+        return true;
+    if (val !== null && typeof val === 'object' && !Array.isArray(val))
+        return Object.values(val).every((v) => typeof v === 'string');
+    return false;
+}
+/**
+ * Coerces a value to the type declared in the param definition.
+ * If the value is already the correct type it is returned as-is.
+ * String values are parsed when the definition expects a number or boolean.
+ *
+ * @throws If the string cannot be meaningfully parsed into the expected type.
+ */
+function coerce(val, definition) {
+    if (definition.type === 'record') {
+        if (typeof val !== 'object')
+            throw new ExpectedError(`Param "${definition.name}" expected a record (use dotted notation: ${definition.name}.KEY=value), got "${String(val)}"`);
+        return val;
+    }
+    if (typeof val === definition.type)
+        return val;
+    if (definition.type === 'number') {
+        const n = Number(val);
+        if (isNaN(n))
+            throw new ExpectedError(`Param "${definition.name}" expected a number, got "${String(val)}"`);
+        return n;
+    }
+    if (definition.type === 'boolean') {
+        if (val === 'true')
+            return true;
+        if (val === 'false')
+            return false;
+        throw new ExpectedError(`Param "${definition.name}" expected a boolean ("true" or "false"), got "${String(val)}"`);
+    }
+    // definition.type === 'string', val is number or boolean
+    return String(val);
+}
+//# sourceMappingURL=task.param.js.map

package/lib/core/task.param.js.map

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

package/lib/core/task.param.schema.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+/** Zod schema for a value that can be passed as a task or flow param. */
+export declare const ParamValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodString>]>;
+/** A scalar value that can be passed as a task or flow param. */
+export type ParamValue = z.infer<typeof ParamValueSchema>;
+/** A resolved, validated set of params, keyed by param name. */
+export type Params = Record<string, ParamValue>;
+/** Zod schema for a single param declaration, shared between task and flow definitions. */
+export declare const ParamDefinitionSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodDefault<z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        record: "record";
+    }>>;
+    required: z.ZodOptional<z.ZodBoolean>;
+    default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** A single param declaration. */
+export type ParamDefinition = z.infer<typeof ParamDefinitionSchema>;

package/lib/core/task.param.schema.js

@@ -0,0 +1,26 @@
+/*
+ * 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';
+/** Zod schema for a value that can be passed as a task or flow param. */
+export const ParamValueSchema = z.union([z.string(), z.number(), z.boolean(), z.record(z.string(), z.string())]);
+/** Zod schema for a single param declaration, shared between task and flow definitions. */
+export const ParamDefinitionSchema = z.object({
+    name: z.string(),
+    type: z.enum(['string', 'number', 'boolean', 'record']).default('string'),
+    required: z.boolean().optional(),
+    default: z.union([z.string(), z.number(), z.boolean()]).optional(),
+    description: z.string().optional(),
+});
+/* c8 ignore stop */
+//# sourceMappingURL=task.param.schema.js.map

package/lib/core/task.param.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.param.schema.js","sourceRoot":"","sources":["../../src/core/task.param.schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,yEAAyE;AACzE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;AAQjH,2FAA2F;AAC3F,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC;IACzE,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAChC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE;IAClE,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACnC,CAAC,CAAC;AAIH,oBAAoB"}

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

@@ -0,0 +1,22 @@
+import { Task } from './task.definition.schema.js';
+/**
+ * Resolves and loads tasks by name.
+ *
+ * On construction, scans both the built-in and consumer task directories and
+ * builds a name → path map. Consumer tasks shadow built-ins of the same name.
+ */
+export declare class TaskRegistry {
+    private readonly shipDir;
+    private readonly tasks;
+    /** @param shipDir - The ship directory for this project. Consumer tasks are loaded from `<shipDir>/tasks`. */
+    constructor(shipDir: string);
+    /** Lists all available task names. */
+    list(): string[];
+    /**
+     * Resolves a task by name.
+     *
+     * @param taskName - The task name from the flow step, e.g. "org/create/scratch".
+     * @throws If the task cannot be found in either location.
+     */
+    resolveTask(taskName: string): Promise<Task>;
+}

package/lib/core/task.registry.js

@@ -0,0 +1,85 @@
+/*
+ * 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 { pathToFileURL, fileURLToPath } from 'node:url';
+import { listDir } from './file.js';
+import { TaskSchema } from './task.definition.schema.js';
+import { asError, ExpectedError, formatZodError } from './error.js';
+import { normalizePath } from './file.js';
+const builtinsDir = resolve(fileURLToPath(import.meta.url), '..', 'tasks');
+async function loadFromPath(taskPath, name) {
+    let mod;
+    try {
+        mod = (await import(pathToFileURL(taskPath).href));
+    }
+    catch (err) {
+        throw new ExpectedError(`Failed to load task at ${taskPath}: ${asError(err).message}`);
+    }
+    const result = TaskSchema.safeParse(mod.default);
+    if (!result.success)
+        throw new ExpectedError(`Invalid task at ${taskPath}: ${formatZodError(result.error)}`);
+    return { ...result.data, name };
+}
+function scanDir(dir) {
+    const names = new Set();
+    try {
+        for (const file of listDir(dir, { recursive: true })) {
+            if (/\.(mjs|js|ts)$/.test(file) && !file.endsWith('.d.ts')) {
+                names.add(file.replaceAll('\\', '/'));
+            }
+        }
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+    }
+    return names;
+}
+/**
+ * Resolves and loads tasks by name.
+ *
+ * On construction, scans both the built-in and consumer task directories and
+ * builds a name → path map. Consumer tasks shadow built-ins of the same name.
+ */
+export class TaskRegistry {
+    shipDir;
+    tasks;
+    /** @param shipDir - The ship directory for this project. Consumer tasks are loaded from `<shipDir>/tasks`. */
+    constructor(shipDir) {
+        this.shipDir = shipDir;
+        this.tasks = new Map();
+        for (const file of scanDir(builtinsDir))
+            this.tasks.set(normalizePath(file.replace(/(?:\/index)?\.(mjs|js|ts)$/, '')), resolve(builtinsDir, file));
+        for (const file of scanDir(resolve(shipDir, 'tasks')))
+            this.tasks.set(normalizePath(file.replace(/(?:\/index)?\.(mjs|js|ts)$/, '')), resolve(shipDir, 'tasks', file));
+    }
+    /** Lists all available task names. */
+    list() {
+        return [...this.tasks.keys()].sort();
+    }
+    /**
+     * Resolves a task by name.
+     *
+     * @param taskName - The task name from the flow step, e.g. "org/create/scratch".
+     * @throws If the task cannot be found in either location.
+     */
+    async resolveTask(taskName) {
+        const name = normalizePath(taskName);
+        const taskPath = this.tasks.get(name);
+        if (!taskPath)
+            throw new ExpectedError(`Unknown task "${taskName}". Looked in: ${resolve(this.shipDir, 'tasks', name)}`);
+        return loadFromPath(taskPath, name);
+    }
+}
+//# sourceMappingURL=task.registry.js.map

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

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

package/lib/core/task.view.d.ts

@@ -0,0 +1,10 @@
+import { Task } from './task.definition.schema.js';
+/**
+ * Returns a UX-formatted string with the task name and, if present, its description.
+ *
+ * @param task - Object containing the task `name` and optional `description`.
+ * @returns Formatted string with colorized label and value pairs.
+ */
+export declare function formatTaskPreview(task: Pick<Task, 'name'> & {
+    description?: string;
+}): string;

package/lib/core/task.view.js

@@ -0,0 +1,25 @@
+/*
+ * 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 { StandardColors } from '@salesforce/sf-plugins-core';
+/**
+ * Returns a UX-formatted string with the task name and, if present, its description.
+ *
+ * @param task - Object containing the task `name` and optional `description`.
+ * @returns Formatted string with colorized label and value pairs.
+ */
+export function formatTaskPreview(task) {
+    const header = `${StandardColors.info('Task:')} ${StandardColors.success(task.name)}`;
+    return task.description ? `${header}\n${StandardColors.info('Description:')} ${task.description}` : header;
+}
+//# sourceMappingURL=task.view.js.map

package/lib/core/task.view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.view.js","sourceRoot":"","sources":["../../src/core/task.view.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAG7D;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAmD;IACnF,MAAM,MAAM,GAAG,GAAG,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;IACtF,OAAO,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,MAAM,KAAK,cAAc,CAAC,IAAI,CAAC,cAAc,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;AAC7G,CAAC"}

package/lib/core/tasks/apex/run/test.d.ts

@@ -0,0 +1,25 @@
+import type { TaskContext } from '../../../task.definition.schema.js';
+declare const _default: {
+    description: string;
+    params: ({
+        name: string;
+        type: "string";
+        required: false;
+        description: string;
+        default?: undefined;
+    } | {
+        name: string;
+        type: "number";
+        required: false;
+        default: number;
+        description: string;
+    } | {
+        name: string;
+        type: "number";
+        required: false;
+        description: string;
+        default?: undefined;
+    })[];
+    run({ flow, params }: TaskContext): Promise<void>;
+};
+export default _default;

package/lib/core/tasks/apex/run/test.js

@@ -0,0 +1,85 @@
+import { resolvePassthroughArgs } from '../../../task.param.js';
+import { ExpectedError } from '../../../error.js';
+// Default --wait value in minutes
+const DEFAULT_WAIT_TIME = 15;
+export default {
+    description: 'Runs Apex tests against the target org. Passthrough for `sf apex run test`.',
+    params: [
+        {
+            name: 'target-org',
+            type: 'string',
+            required: false,
+            description: 'Org alias or username to run tests against. Defaults to the SF CLI default target-org.',
+        },
+        {
+            name: 'test-level',
+            type: 'string',
+            required: false,
+            description: 'Apex test level. Defaults to "RunSpecifiedTests" when class-names is set, otherwise "RunLocalTests".',
+        },
+        {
+            name: 'class-names',
+            type: 'string',
+            required: false,
+            description: 'Comma-separated test class names. Required when test-level is "RunSpecifiedTests".',
+        },
+        {
+            name: 'namespace',
+            type: 'string',
+            required: false,
+            description: 'Namespace prefix to prepend to each class name. Defaults to project.package.namespace from ship.yml.',
+        },
+        {
+            name: 'wait',
+            type: 'number',
+            required: false,
+            default: DEFAULT_WAIT_TIME,
+            description: `Minutes to wait for the test run to complete. Defaults to ${DEFAULT_WAIT_TIME}`,
+        },
+        {
+            name: 'min-coverage',
+            type: 'number',
+            required: false,
+            description: 'Minimum org-wide coverage percentage (0–100). Fails the step if not met.',
+        },
+    ],
+    async run({ flow, params }) {
+        const alias = flow.orgs.resolveAlias(params['target-org']);
+        const rawClassNames = params['class-names'];
+        const namespace = params['namespace'];
+        const classNames = rawClassNames && namespace
+            ? rawClassNames
+                .split(',')
+                .map((c) => (c.includes('.') ? c.trim() : `${namespace}.${c.trim()}`))
+                .join(',')
+            : rawClassNames;
+        const effectiveTestLevel = params['test-level'] ?? (classNames ? 'RunSpecifiedTests' : 'RunLocalTests');
+        const wait = params['wait'] ?? DEFAULT_WAIT_TIME;
+        const argv = resolvePassthroughArgs(params, {
+            '--target-org': alias ?? null,
+            '--tests': classNames ?? null,
+            '--class-names': null,
+            '--namespace': null,
+            '--test-level': effectiveTestLevel ?? null,
+            '--wait': String(wait),
+            '--min-coverage': null,
+            '--code-coverage': params['min-coverage'] !== undefined ? 'true' : null,
+        });
+        flow.log('Running Apex tests...');
+        const result = (await flow.runCommand('apex:run:test', argv));
+        const { summary } = result;
+        if (!summary) {
+            throw new ExpectedError('Test run did not complete within the wait period. Increase the `wait` param or retrieve results manually with `sf apex get test`.');
+        }
+        flow.log(`Tests run: ${summary.testsRan} | Passed: ${summary.passing} | Failed: ${summary.failing}`);
+        const minCoverage = params['min-coverage'];
+        if (minCoverage !== undefined && summary.orgWideCoverage !== undefined) {
+            const pct = parseInt(summary.orgWideCoverage, 10);
+            if (pct < minCoverage) {
+                throw new ExpectedError(`Coverage ${pct}% is below the required minimum of ${minCoverage}%.`);
+            }
+            flow.log(`Org-wide coverage: ${summary.orgWideCoverage}`);
+        }
+    },
+};
+//# sourceMappingURL=test.js.map

package/lib/core/tasks/apex/run/test.js.map

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

package/lib/core/tasks/data/import/tree.d.ts

@@ -0,0 +1,12 @@
+import type { TaskContext } from '../../../task.definition.schema.js';
+declare const _default: {
+    description: string;
+    params: {
+        name: string;
+        type: "string";
+        required: false;
+        description: string;
+    }[];
+    run({ flow, params }: TaskContext): Promise<void>;
+};
+export default _default;

package/lib/core/tasks/data/import/tree.js

@@ -0,0 +1,61 @@
+/*
+ * 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 { resolvePassthroughArgs } from '../../../task.param.js';
+import { pathExists } from '../../../file.js';
+/** Conventional plan file imported when neither `plan` nor `files` is given. */
+const DEFAULT_PLAN = 'data/plan.json';
+export default {
+    description: 'Imports records into an org from tree/plan files. Passthrough for `sf data import tree`.',
+    params: [
+        {
+            name: 'target-org',
+            type: 'string',
+            required: false,
+            description: 'Org alias or username to import records into. Defaults to the SF CLI default target-org.',
+        },
+        {
+            name: 'plan',
+            type: 'string',
+            required: false,
+            description: 'Path to a plan file describing the ordered tree of records to import. Defaults to `.ship/data/plan.json` if present; otherwise the import is skipped.',
+        },
+        {
+            name: 'files',
+            type: 'string',
+            required: false,
+            description: 'Comma-separated tree JSON files to import. Alternative to `plan`.',
+        },
+    ],
+    async run({ flow, params }) {
+        const overrides = {};
+        // Explicit plan/files win. Otherwise fall back to the conventional
+        // `.ship/data/plan.json`; if a project hasn't created one, there's nothing
+        // to import, so skip rather than fail.
+        if (!params['plan'] && !params['files']) {
+            const defaultPlan = resolve(flow.shipDir, DEFAULT_PLAN);
+            if (!pathExists(defaultPlan, 'file')) {
+                flow.log(`No plan or files configured and no ${DEFAULT_PLAN} found — skipping data import.`);
+                return;
+            }
+            overrides['--plan'] = defaultPlan;
+            flow.log(`Importing records from ${defaultPlan}.`);
+        }
+        overrides['--target-org'] = flow.orgs.resolveAlias(params['target-org']) ?? null;
+        const argv = resolvePassthroughArgs(params, overrides);
+        await flow.runCommand('data:import:tree', argv);
+        flow.log('Imported records.');
+    },
+};
+//# sourceMappingURL=tree.js.map

package/lib/core/tasks/data/import/tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../../../../src/core/tasks/data/import/tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,gFAAgF;AAChF,MAAM,YAAY,GAAG,gBAAgB,CAAC;AAEtC,eAAe;IACb,WAAW,EAAE,0FAA0F;IACvG,MAAM,EAAE;QACN;YACE,IAAI,EAAE,YAAY;YAClB,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,KAAK;YACf,WAAW,EAAE,0FAA0F;SACxG;QACD;YACE,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,KAAK;YACf,WAAW,EACT,uJAAuJ;SAC1J;QACD;YACE,IAAI,EAAE,OAAO;YACb,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,KAAK;YACf,WAAW,EAAE,mEAAmE;SACjF;KACF;IACD,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,EAAe;QACrC,MAAM,SAAS,GAAkC,EAAE,CAAC;QAEpD,mEAAmE;QACnE,2EAA2E;QAC3E,uCAAuC;QACvC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YACxC,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;YACxD,IAAI,CAAC,UAAU,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,CAAC;gBACrC,IAAI,CAAC,GAAG,CAAC,sCAAsC,YAAY,gCAAgC,CAAC,CAAC;gBAC7F,OAAO;YACT,CAAC;YACD,SAAS,CAAC,QAAQ,CAAC,GAAG,WAAW,CAAC;YAClC,IAAI,CAAC,GAAG,CAAC,0BAA0B,WAAW,GAAG,CAAC,CAAC;QACrD,CAAC;QAED,SAAS,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,YAAY,CAAuB,CAAC,IAAI,IAAI,CAAC;QACvG,MAAM,IAAI,GAAG,sBAAsB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QACvD,MAAM,IAAI,CAAC,UAAU,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;QAChD,IAAI,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAChC,CAAC;CACuB,CAAC"}