@sfship/plugin-ship 1.0.0-beta.2

package/lib/core/file.d.ts

@@ -0,0 +1,34 @@
+/** Returns true if the path exists on the filesystem. */
+export declare function fileExists(path: string): boolean;
+/** Creates a directory and any missing parents. No-ops if it already exists. */
+export declare function ensureDir(path: string): void;
+/** Lists all entries in a directory. */
+export declare function listDir(path: string, options?: {
+    recursive?: boolean;
+}): string[];
+/** Reads a file as a UTF-8 string. */
+export declare function readText(path: string): string;
+/** Reads and parses a JSON file. */
+export declare function readJson<T>(path: string): T;
+/** Writes a UTF-8 string to a file, appending a trailing newline if one is not already present. */
+export declare function writeText(path: string, content: string): void;
+/** Appends a UTF-8 string to a file, creating it if it does not exist. */
+export declare function appendText(path: string, content: string): void;
+/** Writes a value as pretty-printed JSON to a file. */
+export declare function writeJson(path: string, data: unknown): void;
+/** Writes binary data to a file. */
+export declare function writeBinary(path: string, data: Buffer): void;
+/** Removes a file. Throws if the file does not exist or cannot be removed. */
+export declare function removeFile(path: string): void;
+/** Canonicalizes a task or flow name into its registry key form: trimmed, lowercased, forward-slash separated, no leading slash. */
+export declare function normalizePath(name: string): string;
+/** Returns true if the path exists and matches the given kind (`any`, `file`, or `dir`). */
+export declare function pathExists(path: string, kind: 'any' | 'file' | 'dir'): boolean;
+/** Finds files in `dir` whose names (without extension) match a glob pattern. */
+export declare function findFiles(dir: string, options?: {
+    pattern?: string;
+    recursive?: boolean;
+    stripExtension?: boolean;
+}): Promise<string[]>;
+/** Recursively returns all file paths under `dir`. */
+export declare function walkFiles(dir: string): Promise<string[]>;

package/lib/core/file.js

@@ -0,0 +1,123 @@
+/*
+ * 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 { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, appendFileSync, } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { basename, extname, join } from 'node:path';
+/* c8 ignore start */
+/** Returns true if the path exists on the filesystem. */
+export function fileExists(path) {
+    return existsSync(path);
+}
+/** Creates a directory and any missing parents. No-ops if it already exists. */
+export function ensureDir(path) {
+    mkdirSync(path, { recursive: true });
+}
+/** Lists all entries in a directory. */
+export function listDir(path, options) {
+    return readdirSync(path, options);
+}
+/** Reads a file as a UTF-8 string. */
+export function readText(path) {
+    return readFileSync(path, 'utf8');
+}
+/** Reads and parses a JSON file. */
+export function readJson(path) {
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+/** Writes a UTF-8 string to a file, appending a trailing newline if one is not already present. */
+export function writeText(path, content) {
+    writeFileSync(path, content.endsWith('\n') ? content : `${content}\n`);
+}
+/** Appends a UTF-8 string to a file, creating it if it does not exist. */
+export function appendText(path, content) {
+    appendFileSync(path, content, 'utf8');
+}
+/** Writes a value as pretty-printed JSON to a file. */
+export function writeJson(path, data) {
+    writeText(path, JSON.stringify(data, null, 2));
+}
+/** Writes binary data to a file. */
+export function writeBinary(path, data) {
+    writeFileSync(path, data);
+}
+/** Removes a file. Throws if the file does not exist or cannot be removed. */
+export function removeFile(path) {
+    rmSync(path);
+}
+/** Canonicalizes a task or flow name into its registry key form: trimmed, lowercased, forward-slash separated, no leading slash. */
+export function normalizePath(name) {
+    return name.trim().toLowerCase().replaceAll('\\', '/').replace(/^\/+/, '');
+}
+/* c8 ignore stop */
+/** Returns true if the path exists and matches the given kind (`any`, `file`, or `dir`). */
+export function pathExists(path, kind) {
+    if (kind === 'any')
+        return existsSync(path);
+    try {
+        const stat = statSync(path);
+        return kind === 'file' ? stat.isFile() : stat.isDirectory();
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return false;
+        throw err;
+    }
+}
+function globToRegex(pattern) {
+    const escaped = pattern
+        .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        .replace(/\*/g, '.*')
+        .replace(/\?/g, '.');
+    return new RegExp(`^${escaped}$`, 'i');
+}
+async function collectFiles(dir, regex, recursive, stripExt) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (recursive) {
+                // eslint-disable-next-line no-await-in-loop
+                results.push(...(await collectFiles(join(dir, entry.name), regex, recursive, stripExt)));
+            }
+        }
+        else if (entry.isFile()) {
+            const nameNoExt = basename(entry.name, extname(entry.name));
+            if (regex.test(nameNoExt)) {
+                results.push(stripExt ? nameNoExt : entry.name);
+            }
+        }
+    }
+    return results;
+}
+/** Finds files in `dir` whose names (without extension) match a glob pattern. */
+export async function findFiles(dir, options = {}) {
+    const { pattern = '*', recursive = true, stripExtension = true } = options;
+    return collectFiles(dir, globToRegex(pattern), recursive, stripExtension);
+}
+/** Recursively returns all file paths under `dir`. */
+export async function walkFiles(dir) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const nested = await Promise.all(entries.map((entry) => {
+        const fullPath = join(dir, entry.name);
+        return entry.isDirectory() ? walkFiles(fullPath) : Promise.resolve([fullPath]);
+    }));
+    return nested.flat();
+}
+//# sourceMappingURL=file.js.map

package/lib/core/file.js.map

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

package/lib/core/flow.context.d.ts

@@ -0,0 +1,22 @@
+import { ShipConfig } from './config.ship.schema.js';
+import { Params } from './task.param.schema.js';
+import { OrgRegistry } from './org.registry.js';
+export type FlowContext = {
+    /** Absolute path to the directory containing `ship.yml` — the project root. */
+    projectDir: string;
+    /** Absolute path to the `.ship` directory for the current project. */
+    shipDir: string;
+    /** The loaded ship configuration for this project. */
+    config: ShipConfig;
+    /** Registry for accessing Salesforce orgs and their definitions. */
+    orgs: OrgRegistry;
+    /** Writes a log message to the flow's output. */
+    log: (message: string) => void;
+    /** The params the flow was invoked with. */
+    params: Params;
+    /** True if any step has failed with ignore-failure during this flow run. */
+    hasFailures: boolean;
+    /** Invokes an sf CLI command in-process via oclif's plugin system. */
+    runCommand: (id: string, argv: string[]) => Promise<unknown>;
+};
+export declare function createFlowContext(init: Omit<FlowContext, 'hasFailures'>): FlowContext;

package/lib/core/flow.context.js

@@ -0,0 +1,4 @@
+export function createFlowContext(init) {
+    return { hasFailures: false, ...init };
+}
+//# sourceMappingURL=flow.context.js.map

package/lib/core/flow.context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.context.js","sourceRoot":"","sources":["../../src/core/flow.context.ts"],"names":[],"mappings":"AAoCA,MAAM,UAAU,iBAAiB,CAAC,IAAsC;IACtE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,CAAC;AACzC,CAAC"}

package/lib/core/flow.definition.schema.d.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+/** A single step within a flow definition. */
+declare const FlowStepSchema: z.ZodObject<{
+    task: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodString>]>>>;
+    if: z.ZodOptional<z.ZodObject<{
+        value: z.ZodString;
+        equals: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    }, z.core.$strict>>;
+    'if-not': z.ZodOptional<z.ZodObject<{
+        value: z.ZodString;
+        equals: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    }, z.core.$strict>>;
+    'ignore-failure': z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** Defines a named flow: its accepted params and the ordered steps to execute. */
+export declare const FlowDefinitionSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    params: z.ZodOptional<z.ZodArray<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>>>;
+    steps: z.ZodRecord<z.ZodString, z.ZodObject<{
+        task: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodString>]>>>;
+        if: z.ZodOptional<z.ZodObject<{
+            value: z.ZodString;
+            equals: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+        }, z.core.$strict>>;
+        'if-not': z.ZodOptional<z.ZodObject<{
+            value: z.ZodString;
+            equals: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+        }, z.core.$strict>>;
+        'ignore-failure': z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    finally: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        task: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodString>]>>>;
+        if: z.ZodOptional<z.ZodObject<{
+            value: z.ZodString;
+            equals: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+        }, z.core.$strict>>;
+        'if-not': z.ZodOptional<z.ZodObject<{
+            value: z.ZodString;
+            equals: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+        }, z.core.$strict>>;
+        'ignore-failure': z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type FlowStep = z.infer<typeof FlowStepSchema>;
+export type FlowDefinition = z.infer<typeof FlowDefinitionSchema>;
+export {};

package/lib/core/flow.definition.schema.js

@@ -0,0 +1,56 @@
+/*
+ * 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 { ParamDefinitionSchema, ParamValueSchema } from './task.param.schema.js';
+/** A scalar value or null that a condition can compare against. */
+const FlowStepConditionValueSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+/** Condition used in `if` / `if-not` step fields. Resolves a `${{ }}` token and optionally compares it to a value. */
+const FlowStepConditionSchema = z
+    .object({ value: z.string(), equals: FlowStepConditionValueSchema.optional() })
+    .strict();
+/** A single step within a flow definition. */
+const FlowStepSchema = z
+    .object({
+    /** The task to execute, e.g. "util/log" or "org/create/scratch". */
+    task: z.string(),
+    /** Parameters passed to the task. */
+    params: z.record(z.string(), ParamValueSchema).optional(),
+    /** Run step if condition is truthy (or equals a value). */
+    if: FlowStepConditionSchema.optional(),
+    /** Run step if condition is falsy (or equals a value). */
+    'if-not': FlowStepConditionSchema.optional(),
+    /** Continue the flow if this step fails, storing failure state in step outputs. */
+    'ignore-failure': z.boolean().optional(),
+})
+    .refine((s) => !(s.if && s['if-not']), { message: 'A step cannot have both "if" and "if-not"' });
+/** Defines a named flow: its accepted params and the ordered steps to execute. */
+export const FlowDefinitionSchema = z
+    .object({
+    /** Human-readable description of what this flow does. */
+    description: z.string().optional(),
+    /** Params this flow accepts, passed as `--param key=value` CLI flags when invoking the flow. */
+    params: z.array(ParamDefinitionSchema).optional(),
+    /** Named steps to execute in definition order. The key is the step ID, used for output references. */
+    steps: z.record(z.string(), FlowStepSchema),
+    /** Steps that always run after `steps`, regardless of success or failure. */
+    finally: z.record(z.string(), FlowStepSchema).optional(),
+})
+    .superRefine((flow, ctx) => {
+    const dup = Object.keys(flow.finally ?? {}).find((k) => k in flow.steps);
+    if (dup) {
+        ctx.addIssue({ code: 'custom', message: `Step ID "${dup}" appears in both "steps" and "finally"` });
+    }
+});
+/* c8 ignore stop */
+//# sourceMappingURL=flow.definition.schema.js.map

package/lib/core/flow.definition.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.definition.schema.js","sourceRoot":"","sources":["../../src/core/flow.definition.schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAEjF,mEAAmE;AACnE,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AAE9F,sHAAsH;AACtH,MAAM,uBAAuB,GAAG,CAAC;KAC9B,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,4BAA4B,CAAC,QAAQ,EAAE,EAAE,CAAC;KAC9E,MAAM,EAAE,CAAC;AAEZ,8CAA8C;AAC9C,MAAM,cAAc,GAAG,CAAC;KACrB,MAAM,CAAC;IACN,oEAAoE;IACpE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,qCAAqC;IACrC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,gBAAgB,CAAC,CAAC,QAAQ,EAAE;IACzD,2DAA2D;IAC3D,EAAE,EAAE,uBAAuB,CAAC,QAAQ,EAAE;IACtC,0DAA0D;IAC1D,QAAQ,EAAE,uBAAuB,CAAC,QAAQ,EAAE;IAC5C,mFAAmF;IACnF,gBAAgB,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CACzC,CAAC;KACD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,2CAA2C,EAAE,CAAC,CAAC;AAEnG,kFAAkF;AAClF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC;KAClC,MAAM,CAAC;IACN,yDAAyD;IACzD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,gGAAgG;IAChG,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,qBAAqB,CAAC,CAAC,QAAQ,EAAE;IACjD,sGAAsG;IACtG,KAAK,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,cAAc,CAAC;IAC3C,6EAA6E;IAC7E,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,cAAc,CAAC,CAAC,QAAQ,EAAE;CACzD,CAAC;KACD,WAAW,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;IACzB,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC;IACzE,IAAI,GAAG,EAAE,CAAC;QACR,GAAG,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,GAAG,yCAAyC,EAAE,CAAC,CAAC;IACtG,CAAC;AACH,CAAC,CAAC,CAAC;AAIL,oBAAoB"}

package/lib/core/flow.interpolate.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Traverses a nested object by an array of keys.
+ * Returns `undefined` if any segment is missing or non-traversable.
+ */
+export declare function deepGet(root: unknown, keys: string[]): unknown;
+/**
+ * If `value` is exactly one `${{ path }}` token, resolves the path against
+ * `context` — yielding `null` when the path is absent so callers can tell
+ * "missing" apart from "empty". Returns `undefined` when `value` is not a single
+ * pure token, signalling the caller to treat it as a literal or interpolate
+ * embedded tokens itself.
+ */
+export declare function resolvePureToken(value: string, context: Record<string, unknown>): unknown;
+/**
+ * Interpolates `${{ some.path }}` tokens in a value by looking up paths in a
+ * unified context object. Non-string values are returned unchanged; plain
+ * objects are interpolated recursively. A pure token resolves to the looked-up
+ * value (or `null`); a token embedded in surrounding text is stringified, with
+ * misses replaced by an empty string.
+ */
+export declare function interpolate(value: unknown, context: Record<string, unknown>): unknown;

package/lib/core/flow.interpolate.js

@@ -0,0 +1,64 @@
+/*
+ * 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.
+ */
+const PURE_TOKEN = /^\$\{\{\s*([\w.-]+)\s*\}\}$/;
+/** Matches each `${{ path }}` token embedded within a larger string. */
+const EMBEDDED_TOKEN = /\$\{\{\s*([\w.-]+)\s*\}\}/g;
+/**
+ * Traverses a nested object by an array of keys.
+ * Returns `undefined` if any segment is missing or non-traversable.
+ */
+export function deepGet(root, keys) {
+    let val = root;
+    for (const key of keys) {
+        if (val == null || typeof val !== 'object')
+            return undefined;
+        val = val[key];
+    }
+    return val;
+}
+/**
+ * If `value` is exactly one `${{ path }}` token, resolves the path against
+ * `context` — yielding `null` when the path is absent so callers can tell
+ * "missing" apart from "empty". Returns `undefined` when `value` is not a single
+ * pure token, signalling the caller to treat it as a literal or interpolate
+ * embedded tokens itself.
+ */
+export function resolvePureToken(value, context) {
+    const match = value.match(PURE_TOKEN);
+    return match ? deepGet(context, match[1].split('.')) ?? null : undefined;
+}
+/**
+ * Interpolates `${{ some.path }}` tokens in a value by looking up paths in a
+ * unified context object. Non-string values are returned unchanged; plain
+ * objects are interpolated recursively. A pure token resolves to the looked-up
+ * value (or `null`); a token embedded in surrounding text is stringified, with
+ * misses replaced by an empty string.
+ */
+export function interpolate(value, context) {
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, interpolate(v, context)]));
+    }
+    if (typeof value !== 'string')
+        return value;
+    const resolved = resolvePureToken(value, context);
+    if (resolved !== undefined)
+        return resolved;
+    let result = value;
+    for (const [match, path] of value.matchAll(EMBEDDED_TOKEN)) {
+        const raw = deepGet(context, path.split('.'));
+        result = result.replace(match, raw != null ? String(raw) : '');
+    }
+    return result;
+}
+//# sourceMappingURL=flow.interpolate.js.map

package/lib/core/flow.interpolate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.interpolate.js","sourceRoot":"","sources":["../../src/core/flow.interpolate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,UAAU,GAAG,6BAA6B,CAAC;AACjD,wEAAwE;AACxE,MAAM,cAAc,GAAG,4BAA4B,CAAC;AAEpD;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,IAAa,EAAE,IAAc;IACnD,IAAI,GAAG,GAAY,IAAI,CAAC;IACxB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,GAAG,IAAI,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAC7D,GAAG,GAAI,GAA+B,CAAC,GAAG,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa,EAAE,OAAgC;IAC9E,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IACtC,OAAO,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,OAAgC;IAC1E,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzE,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAC/F,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAE5C,MAAM,QAAQ,GAAG,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAClD,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAE5C,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QAC3D,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QAC9C,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -0,0 +1,32 @@
+import { FlowDefinition } from './flow.definition.schema.js';
+export declare const builtinsDir: string;
+/**
+ * Resolves flow definitions by name.
+ *
+ * On construction, scans both the built-in and consumer flow directories and
+ * Later sources shadow earlier ones: built-ins → .ship/flows/.
+ */
+export declare class FlowRegistry {
+    private readonly shipDir;
+    private readonly flows;
+    /** Built-in flow name → absolute source path, for `flow eject`. */
+    private readonly builtinFiles;
+    /** @param shipDir - The ship directory for this project. Consumer flows are loaded from `<shipDir>/flows`. */
+    constructor(shipDir: string);
+    /** Lists all available flow names. */
+    list(): string[];
+    /**
+     * Returns the flow definition for the given name.
+     *
+     * @param flowName - The flow name, e.g. "ci" or "managed-package/release".
+     * @throws If the flow cannot be found in any source.
+     */
+    resolveFlow(flowName: string): FlowDefinition;
+    /**
+     * Absolute path to a built-in flow's source `.yml`, or null if `flowName`
+     * is not a built-in (unknown, or a project-only flow). Used by `flow eject`.
+     *
+     * @param flowName - The flow name, e.g. "ci" or "managed-package/release".
+     */
+    builtinSource(flowName: string): string | null;
+}

package/lib/core/flow.registry.js

@@ -0,0 +1,99 @@
+/*
+ * 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 { fileURLToPath } from 'node:url';
+import { parse } from 'yaml';
+import { listDir, normalizePath, readText } from './file.js';
+import { FlowDefinitionSchema } from './flow.definition.schema.js';
+import { ExpectedError, formatZodError } from './error.js';
+export const builtinsDir = resolve(fileURLToPath(import.meta.url), '..', 'flows');
+function scanDir(dir) {
+    try {
+        return listDir(dir, { recursive: true })
+            .filter((f) => f.endsWith('.yml'))
+            .map((f) => f.replaceAll('\\', '/'));
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+        return [];
+    }
+}
+function loadFromPath(flowPath) {
+    let raw;
+    try {
+        raw = readText(flowPath);
+    }
+    catch (err) {
+        throw new ExpectedError(`Failed to load flow at ${flowPath}: ${err.message}`);
+    }
+    const parsed = parse(raw);
+    const result = FlowDefinitionSchema.safeParse(parsed);
+    if (!result.success)
+        throw new ExpectedError(`Invalid flow definition at ${flowPath}:\n${formatZodError(result.error)}`);
+    return result.data;
+}
+/**
+ * Resolves flow definitions by name.
+ *
+ * On construction, scans both the built-in and consumer flow directories and
+ * Later sources shadow earlier ones: built-ins → .ship/flows/.
+ */
+export class FlowRegistry {
+    shipDir;
+    flows;
+    /** Built-in flow name → absolute source path, for `flow eject`. */
+    builtinFiles;
+    /** @param shipDir - The ship directory for this project. Consumer flows are loaded from `<shipDir>/flows`. */
+    constructor(shipDir) {
+        this.shipDir = shipDir;
+        this.flows = new Map();
+        this.builtinFiles = new Map();
+        for (const file of scanDir(builtinsDir)) {
+            const name = normalizePath(file.replace(/\.yml$/, ''));
+            const path = resolve(builtinsDir, file);
+            this.builtinFiles.set(name, path);
+            this.flows.set(name, loadFromPath(path));
+        }
+        for (const file of scanDir(resolve(shipDir, 'flows')))
+            this.flows.set(normalizePath(file.replace(/\.yml$/, '')), loadFromPath(resolve(shipDir, 'flows', file)));
+    }
+    /** Lists all available flow names. */
+    list() {
+        return [...this.flows.keys()].sort();
+    }
+    /**
+     * Returns the flow definition for the given name.
+     *
+     * @param flowName - The flow name, e.g. "ci" or "managed-package/release".
+     * @throws If the flow cannot be found in any source.
+     */
+    resolveFlow(flowName) {
+        const name = normalizePath(flowName);
+        const flow = this.flows.get(name);
+        if (!flow)
+            throw new ExpectedError(`Unknown flow "${flowName}". Looked in: ${resolve(this.shipDir, 'flows', name)}`);
+        return flow;
+    }
+    /**
+     * Absolute path to a built-in flow's source `.yml`, or null if `flowName`
+     * is not a built-in (unknown, or a project-only flow). Used by `flow eject`.
+     *
+     * @param flowName - The flow name, e.g. "ci" or "managed-package/release".
+     */
+    builtinSource(flowName) {
+        return this.builtinFiles.get(normalizePath(flowName)) ?? null;
+    }
+}
+//# sourceMappingURL=flow.registry.js.map

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

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

package/lib/core/flow.renderer.d.ts

@@ -0,0 +1,51 @@
+import { FlowStep } from './flow.definition.schema.js';
+import { FlowContext } from './flow.context.js';
+type OutputStream = {
+    isTTY?: boolean;
+    write(chunk: string): boolean;
+};
+type Steps = ReadonlyArray<readonly [string, FlowStep]>;
+/**
+ * Renders a flow run as plain sequential output: a plan banner up front, a
+ * heading before each step, the step's own (and any subcommand's) output
+ * flowing untouched, and a result summary at the end.
+ *
+ * All formatting lives in the `flow.view` module so a flow looks the same
+ * whether it runs here or is inspected via `ship flow info`.
+ */
+export declare class FlowRenderer {
+    private readonly flowName;
+    private readonly mainSteps;
+    private readonly finallySteps;
+    private readonly write;
+    private readonly stepsById;
+    private readonly order;
+    private readonly completed;
+    private readonly failed;
+    private readonly skipped;
+    private readonly ignored;
+    private currentStep;
+    constructor(flowName: string, mainSteps: Steps, finallySteps: Steps, ctx: FlowContext, out?: OutputStream);
+    /** The step currently executing, or null between steps. */
+    get activeStep(): string | null;
+    private get outcome();
+    private static timestamp;
+    /** Prints the plan banner at the start of the run. */
+    start(): void;
+    /** Prints the heading for a step that is about to run. */
+    stepStart(stepId: string): void;
+    stepComplete(stepId: string): void;
+    stepFailed(stepId: string): void;
+    stepSkipped(stepId: string): void;
+    stepIgnored(stepId: string, err: Error): void;
+    /** Reports a flow that could not start (e.g. invalid flow params). */
+    failedBeforeStart(err: Error): void;
+    /** Reports a hard failure: prints the summary, then the error (and stack for unexpected errors). */
+    flowFailed(stepId: string, err: Error): void;
+    /** Prints the summary and the success banner. */
+    success(): void;
+    /** Handles a user interrupt (Ctrl+C): marks the active step failed and reports it. */
+    interrupt(): void;
+    private logLine;
+}
+export {};