@sfship/plugin-ship 1.0.0-beta.2

package/lib/core/tasks/util/file/exists.d.ts

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

package/lib/core/tasks/util/file/exists.js

@@ -0,0 +1,53 @@
+/*
+ * 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 { pathExists } from '../../../file.js';
+import { ExpectedError } from '../../../error.js';
+export default {
+    description: 'Checks whether a file or directory exists. Mirrors `test -e` / `-f` / `-d`. Outputs `exists` for use in step `if` gates.',
+    params: [
+        {
+            name: 'path',
+            type: 'string',
+            required: true,
+            description: 'Path to check. Relative paths resolve against the project directory.',
+        },
+        {
+            name: 'kind',
+            type: 'string',
+            required: false,
+            default: 'any',
+            description: 'What to check for: `any` (mirrors `test -e`, default), `file` (`-f`), or `dir` (`-d`).',
+        },
+    ],
+    outputs: [
+        {
+            name: 'exists',
+            type: 'boolean',
+            description: 'True if the path exists and matches `kind`; otherwise false.',
+        },
+    ],
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async run({ flow, params, output }) {
+        const target = resolve(flow.projectDir, params['path']);
+        const kind = params['kind'];
+        if (!['any', 'file', 'dir'].includes(kind)) {
+            throw new ExpectedError(`Invalid kind "${kind}". Use one of: any, file, dir.`);
+        }
+        const exists = pathExists(target, kind);
+        flow.log(`${target} ${exists ? 'exists' : 'does not exist'} (kind: ${kind})`);
+        output.set('exists', exists);
+    },
+};
+//# sourceMappingURL=exists.js.map

package/lib/core/tasks/util/file/exists.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exists.js","sourceRoot":"","sources":["../../../../../src/core/tasks/util/file/exists.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,eAAe;IACb,WAAW,EACT,0HAA0H;IAC5H,MAAM,EAAE;QACN;YACE,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,IAAI;YACd,WAAW,EAAE,sEAAsE;SACpF;QACD;YACE,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,KAAK;YACd,WAAW,EAAE,wFAAwF;SACtG;KACF;IACD,OAAO,EAAE;QACP;YACE,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,SAAS;YACf,WAAW,EAAE,8DAA8D;SAC5E;KACF;IACD,4DAA4D;IAC5D,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAe;QAC7C,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAW,CAAC,CAAC;QAClE,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAW,CAAC;QACtC,IAAI,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,aAAa,CAAC,iBAAiB,IAAI,gCAAgC,CAAC,CAAC;QACjF,CAAC;QAED,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,IAA8B,CAAC,CAAC;QAClE,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,IAAI,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,gBAAgB,WAAW,IAAI,GAAG,CAAC,CAAC;QAC9E,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC/B,CAAC;CACuB,CAAC"}

package/lib/core/tasks/util/file/find.d.ts

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

package/lib/core/tasks/util/file/find.js

@@ -0,0 +1,70 @@
+/*
+ * 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 { findFiles } from '../../../file.js';
+export default {
+    description: 'Finds files in a directory whose names match a glob pattern.',
+    params: [
+        {
+            name: 'path',
+            type: 'string',
+            required: true,
+            description: 'Directory to search, relative to the project root.',
+        },
+        {
+            name: 'pattern',
+            type: 'string',
+            required: false,
+            default: '*',
+            description: 'Glob pattern matched against the filename without extension. Case-insensitive. Defaults to "*".',
+        },
+        {
+            name: 'recursive',
+            type: 'boolean',
+            required: false,
+            default: true,
+            description: 'Recurse into subdirectories. Defaults to true.',
+        },
+        {
+            name: 'strip-extension',
+            type: 'boolean',
+            required: false,
+            default: true,
+            description: 'Strip file extensions from results. Defaults to true.',
+        },
+    ],
+    outputs: [
+        {
+            name: 'files',
+            type: 'string',
+            description: 'Comma-separated list of matching file names.',
+        },
+        {
+            name: 'count',
+            type: 'string',
+            description: 'Number of matching files found.',
+        },
+    ],
+    async run({ flow, params, output }) {
+        const dir = resolve(flow.projectDir, params['path']);
+        const pattern = params['pattern'] ?? '*';
+        const recursive = params['recursive'] !== false;
+        const stripExtension = params['strip-extension'] !== false;
+        const files = await findFiles(dir, { pattern, recursive, stripExtension });
+        flow.log(`Found ${files.length} file(s) matching "${pattern}" in ${params['path']}.`);
+        output.set('files', files.join(','));
+        output.set('count', String(files.length));
+    },
+};
+//# sourceMappingURL=find.js.map

package/lib/core/tasks/util/file/find.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find.js","sourceRoot":"","sources":["../../../../../src/core/tasks/util/file/find.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAG7C,eAAe;IACb,WAAW,EAAE,8DAA8D;IAC3E,MAAM,EAAE;QACN;YACE,IAAI,EAAE,MAAM;YACZ,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,IAAI;YACd,WAAW,EAAE,oDAAoD;SAClE;QACD;YACE,IAAI,EAAE,SAAS;YACf,IAAI,EAAE,QAAQ;YACd,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,GAAG;YACZ,WAAW,EAAE,iGAAiG;SAC/G;QACD;YACE,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,SAAS;YACf,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,IAAI;YACb,WAAW,EAAE,gDAAgD;SAC9D;QACD;YACE,IAAI,EAAE,iBAAiB;YACvB,IAAI,EAAE,SAAS;YACf,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,IAAI;YACb,WAAW,EAAE,uDAAuD;SACrE;KACF;IACD,OAAO,EAAE;QACP;YACE,IAAI,EAAE,OAAO;YACb,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,8CAA8C;SAC5D;QACD;YACE,IAAI,EAAE,OAAO;YACb,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,iCAAiC;SAC/C;KACF;IACD,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAe;QAC7C,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,CAAW,CAAC,CAAC;QAC/D,MAAM,OAAO,GAAI,MAAM,CAAC,SAAS,CAAwB,IAAI,GAAG,CAAC;QACjE,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,KAAK,KAAK,CAAC;QAChD,MAAM,cAAc,GAAG,MAAM,CAAC,iBAAiB,CAAC,KAAK,KAAK,CAAC;QAE3D,MAAM,KAAK,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,CAAC,CAAC;QAE3E,IAAI,CAAC,GAAG,CAAC,SAAS,KAAK,CAAC,MAAM,sBAAsB,OAAO,QAAQ,MAAM,CAAC,MAAM,CAAW,GAAG,CAAC,CAAC;QAChG,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QACrC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAC5C,CAAC;CACuB,CAAC"}

package/lib/core/tasks/util/log.d.ts

@@ -0,0 +1,13 @@
+import type { TaskContext } from '../../task.definition.schema.js';
+/** Logs a message to the flow output. Useful for progress indicators and debug output in flows. */
+declare const _default: {
+    description: string;
+    params: {
+        name: string;
+        type: "string";
+        required: true;
+        description: string;
+    }[];
+    run({ flow, params }: TaskContext): Promise<void>;
+};
+export default _default;

package/lib/core/tasks/util/log.js

@@ -0,0 +1,10 @@
+/** Logs a message to the flow output. Useful for progress indicators and debug output in flows. */
+export default {
+    description: 'Logs a message to the flow output.',
+    params: [{ name: 'message', type: 'string', required: true, description: 'The message to log.' }],
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async run({ flow, params }) {
+        flow.log(params['message']);
+    },
+};
+//# sourceMappingURL=log.js.map

package/lib/core/tasks/util/log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.js","sourceRoot":"","sources":["../../../../src/core/tasks/util/log.ts"],"names":[],"mappings":"AAeA,mGAAmG;AACnG,eAAe;IACb,WAAW,EAAE,oCAAoC;IACjD,MAAM,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,qBAAqB,EAAE,CAAC;IACjG,4DAA4D;IAC5D,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,EAAe;QACrC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAW,CAAC,CAAC;IACxC,CAAC;CACuB,CAAC"}

package/lib/core/templates/README.md

@@ -0,0 +1,35 @@
+# SF Ship Documentation
+
+## Create a Dev Org
+
+Spin up a personal scratch org with your source deployed and dependencies installed:
+
+```
+sf ship flow run deploy/dev
+```
+
+## Retrieve Metadata
+
+After making changes in the org, pull them back locally:
+
+```
+sf project retrieve start
+```
+
+## Create a Release
+
+Build and promote a new package version through environments:
+
+```
+sf ship flow run release/beta
+```
+
+## Promote a Package Version
+
+```
+sf ship flow run release/production
+```
+
+## Documentation
+
+TODO

package/lib/core/tree.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Renders a list of slash-separated paths as an ASCII tree.
+ *
+ * @param names - Sorted list of slash-separated path names.
+ * @returns The tree as a single string ready to print.
+ */
+export declare function renderTree(names: string[]): string;

package/lib/core/tree.js

@@ -0,0 +1,42 @@
+function insert(tree, parts) {
+    const [head, ...rest] = parts;
+    if (rest.length === 0) {
+        if (!tree.has(head))
+            tree.set(head, null);
+    }
+    else {
+        if (!tree.has(head) || tree.get(head) === null)
+            tree.set(head, new Map());
+        insert(tree.get(head), rest);
+    }
+}
+function renderLines(tree, prefix = '') {
+    const lines = [];
+    const entries = [...tree.entries()];
+    for (const [i, [key, children]] of entries.entries()) {
+        const isLast = i === entries.length - 1;
+        const connector = isLast ? '└── ' : '├── ';
+        const childPrefix = prefix + (isLast ? '    ' : '│   ');
+        if (children === null) {
+            lines.push(`${prefix}${connector}${key}`);
+        }
+        else {
+            lines.push(`${prefix}${connector}${key}/`);
+            lines.push(...renderLines(children, childPrefix));
+        }
+    }
+    return lines;
+}
+/**
+ * Renders a list of slash-separated paths as an ASCII tree.
+ *
+ * @param names - Sorted list of slash-separated path names.
+ * @returns The tree as a single string ready to print.
+ */
+export function renderTree(names) {
+    const tree = new Map();
+    for (const name of names)
+        insert(tree, name.split('/'));
+    return renderLines(tree).join('\n');
+}
+//# sourceMappingURL=tree.js.map

package/lib/core/tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../src/core/tree.ts"],"names":[],"mappings":"AAeA,SAAS,MAAM,CAAC,IAAU,EAAE,KAAe;IACzC,MAAM,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC;IAC9B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC5C,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;QAC1E,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAS,EAAE,IAAI,CAAC,CAAC;IACvC,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,IAAU,EAAE,MAAM,GAAG,EAAE;IAC1C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IACpC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;QACrD,MAAM,MAAM,GAAG,CAAC,KAAK,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;QACxC,MAAM,SAAS,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;QAC3C,MAAM,WAAW,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;QACxD,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACtB,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,GAAG,SAAS,GAAG,GAAG,EAAE,CAAC,CAAC;QAC5C,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,GAAG,SAAS,GAAG,GAAG,GAAG,CAAC,CAAC;YAC3C,KAAK,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC,CAAC;QACpD,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,KAAe;IACxC,MAAM,IAAI,GAAS,IAAI,GAAG,EAAE,CAAC;IAC7B,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;IACxD,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACtC,CAAC"}

package/messages/service.connect.github.md

@@ -0,0 +1,16 @@
+# summary
+
+Connect a GitHub account to plugin-ship via OAuth.
+
+# description
+
+Opens a browser-based OAuth flow to authenticate with GitHub. Once connected, plugin-ship can interact with your repositories on your behalf.
+
+# flags.alias.summary
+
+Alias for this GitHub account. Defaults to "default".
+
+# examples
+
+- <%= config.bin %> <%= command.id %>
+- <%= config.bin %> <%= command.id %> --alias work

package/messages/ship.flow.eject.md

@@ -0,0 +1,21 @@
+# summary
+
+Copy a standard flow into your project for customization.
+
+# description
+
+Copies a built-in flow definition into your project's .ship/flows/ directory so you can modify it. Fails if the flow is not a built-in, or if the destination file already exists.
+
+# args.flowName.summary
+
+The name of the built-in flow to eject.
+
+# flags.config.summary
+
+Path to the ship.yml config file.
+
+# examples
+
+- Eject the ci flow into your project:
+
+  <%= config.bin %> <%= command.id %> ci

package/messages/ship.flow.info.md

@@ -0,0 +1,21 @@
+# summary
+
+Show details for a flow.
+
+# description
+
+Displays the description, accepted params, and step-by-step breakdown for a named flow.
+
+# args.flowName.summary
+
+The name of the flow to inspect.
+
+# flags.config.summary
+
+Path to the ship.yml config file.
+
+# examples
+
+- Show details for a flow:
+
+  <%= config.bin %> <%= command.id %> ci

package/messages/ship.flow.list.md

@@ -0,0 +1,15 @@
+# summary
+
+List all flows defined in ship.yml.
+
+# description
+
+Reads ship.yml and prints the names of all defined flows.
+
+# flags.config.summary
+
+Path to the ship.yml config file.
+
+# examples
+
+- <%= config.bin %> <%= command.id %>

package/messages/ship.flow.run.md

@@ -0,0 +1,23 @@
+# summary
+
+Run a flow defined in ship.yml.
+
+# description
+
+Reads ship.yml from the current directory, finds the named flow, and executes its tasks in sequence.
+
+# flags.name.summary
+
+Kebab-cased name of the flow to run, found in `ship.yml` such as `deploy-dev-org`.
+
+# flags.config.summary
+
+Path to the ship.yml config file.
+
+# flags.param.summary
+
+Flow parameter in key=value format.
+
+# examples
+
+- <%= config.bin %> <%= command.id %> my_flow

package/messages/ship.project.init.md

@@ -0,0 +1,23 @@
+# summary
+
+Initialize a new plugin-ship project in the current directory.
+
+# description
+
+Runs sf project generate to scaffold a standard Salesforce project, then patches sfdx-project.json with 2GP settings and writes ship.yml and .ship/orgs scratch org definitions. Existing files are left untouched.
+
+# flags.template.summary
+
+Template to use for project generation.
+
+# flags.api-version.summary
+
+Override the API version used for API requests made by this command.
+
+# flags.lwc-language.summary
+
+Default language to use for LWC components (javascript or typescript).
+
+# examples
+
+- <%= config.bin %> <%= command.id %>

package/messages/ship.service.delete.md

@@ -0,0 +1,19 @@
+# summary
+
+Remove a stored service credential.
+
+# description
+
+Deletes the credential from the OS keychain and removes the associated metadata file.
+
+# args.service.summary
+
+The service name (e.g. github.com).
+
+# args.alias.summary
+
+The account alias (e.g. default).
+
+# examples
+
+- <%= config.bin %> <%= command.id %> github.com default

package/messages/ship.service.info.md

@@ -0,0 +1,19 @@
+# summary
+
+Show details for a stored service credential.
+
+# description
+
+Prints the metadata for a stored service credential identified by service name and alias.
+
+# args.service.summary
+
+The service name (e.g. github).
+
+# args.alias.summary
+
+The account alias (e.g. default).
+
+# examples
+
+- <%= config.bin %> <%= command.id %> github.com default

package/messages/ship.service.list.md

@@ -0,0 +1,11 @@
+# summary
+
+List all connected services.
+
+# description
+
+Shows all stored service credentials managed by plugin-ship.
+
+# examples
+
+- <%= config.bin %> <%= command.id %>

package/messages/ship.task.info.md

@@ -0,0 +1,25 @@
+# summary
+
+Show details for a task.
+
+# description
+
+Displays the description, accepted params, and store outputs for a built-in or custom task.
+
+# args.taskName.summary
+
+The name of the task to inspect.
+
+# flags.config.summary
+
+Path to the ship.yml config file.
+
+# examples
+
+- Show details for a built-in task:
+
+  <%= config.bin %> <%= command.id %> org/create/scratch
+
+- Show details for a custom task:
+
+  <%= config.bin %> <%= command.id %> my-custom-task

package/messages/ship.task.list.md

@@ -0,0 +1,15 @@
+# summary
+
+List all available tasks.
+
+# description
+
+Prints built-in tasks and any custom tasks found in the `.ship/tasks/` directory.
+
+# flags.config.summary
+
+Path to the ship.yml config file.
+
+# examples
+
+- <%= config.bin %> <%= command.id %>

package/messages/ship.task.run.md

@@ -0,0 +1,29 @@
+# summary
+
+Run a single ship task.
+
+# description
+
+Runs a built-in or custom task directly, outside of a flow. Useful for testing and one-off operations.
+
+# args.taskName.summary
+
+The name of the task to run.
+
+# flags.config.summary
+
+Path to the ship.yml config file.
+
+# flags.param.summary
+
+Task parameter in key=value format.
+
+# examples
+
+- Run the log task:
+
+  <%= config.bin %> <%= command.id %> log --param message=hello
+
+- Run a custom task:
+
+  <%= config.bin %> <%= command.id %> create-scratch-org --param scratch-def=dev