@elmundi/ship-cli 0.11.2 → 0.12.1

package/lib/config/schema.mjs

@@ -33,6 +33,22 @@ export const LANE_EVENT_TYPES = Object.freeze([
 export const LANE_IDEMPOTENCY_STORES = Object.freeze(["file", "backend"]);
 export const LANE_IDEMPOTENCY_RESET_ON = Object.freeze(["version-change", "manual"]);
 
+/* RFC-0008 C3.2 — fan-out strategy for multi-pattern lanes.
+ *
+ *   matrix      — GitHub Actions matrix: one runner per pattern, parallel.
+ *   sequential  — Single runner, `shipctl run` iterates patterns in order.
+ *   concurrent  — Single runner, `shipctl run` spawns subprocesses in parallel.
+ *
+ * Meaningful only when ``patterns.length > 1``; single-pattern lanes ignore
+ * it (the linter warns if it's set on a single-pattern lane). Default:
+ * ``matrix``. */
+export const LANE_FANOUT_MODES = Object.freeze([
+  "matrix",
+  "sequential",
+  "concurrent",
+]);
+export const LANE_FANOUT_DEFAULT = "matrix";
+
 /* Lane ids travel into file paths (`.ship/state/<key>.json`), workflow
  * file names (`.github/workflows/ship-<lane>.yml`), and env vars, so
  * restrict them conservatively: ASCII lowercase, digits, dash, underscore. */
@@ -156,6 +172,7 @@ export function DEFAULT_CONFIG_V2() {
       default: { provider: null },
       overrides: {},
     },
+    process: DEFAULT_PROCESS_CONFIG(),
     lanes: {},
     artifacts: v1.artifacts,
     cache: v1.cache,
@@ -163,6 +180,28 @@ export function DEFAULT_CONFIG_V2() {
   };
 }
 
+export function DEFAULT_PROCESS_CONFIG() {
+  return {
+    id: "development",
+    name: "Development Process",
+    primary: true,
+    states: [
+      { id: "task_intake", name: "Intake", specialist: { id: "intake", name: "Intake specialist" }, layout: { x: 72, y: 170 } },
+      { id: "ba_requirements", name: "Requirements", specialist: { id: "business_analyst", name: "Business analyst" }, layout: { x: 338, y: 170 } },
+      { id: "dev_implementation", name: "Implementation", specialist: { id: "developer", name: "Developer" }, layout: { x: 604, y: 170 } },
+      { id: "qa_manual", name: "Quality Review", specialist: { id: "qa_engineer", name: "QA engineer" }, layout: { x: 870, y: 170 } },
+      { id: "pr_review", name: "Final Review", specialist: { id: "review_owner", name: "Review owner" }, layout: { x: 1136, y: 170 } },
+    ],
+    transitions: [
+      { from: "task_intake", to: "ba_requirements" },
+      { from: "ba_requirements", to: "dev_implementation" },
+      { from: "dev_implementation", to: "qa_manual" },
+      { from: "qa_manual", to: "pr_review" },
+    ],
+    routines: [],
+  };
+}
+
 /**
  * Back-compat alias. Pre-existing callers expect DEFAULT_CONFIG() to
  * return the current schema's shape; default to v2 so new installs
@@ -190,6 +229,7 @@ const KNOWN_TOP_LEVEL_V2 = new Set([
   "api",
   "stack",
   "agent",
+  "process",
   "lanes",
   "artifacts",
   "cache",
@@ -269,6 +309,105 @@ function validateSharedSections(obj, errors, warnings) {
  * @param {string[]} errors
  * @param {string[]} warnings
  */
+function validateV2Process(obj, errors, warnings) {
+  const process = obj.process;
+  if (process === undefined) return;
+  if (!isPlainObject(process)) {
+    errors.push("process: must be an object");
+    return;
+  }
+  pushUnknownKeyWarnings(
+    process,
+    new Set(["id", "name", "primary", "states", "transitions", "routines"]),
+    "process",
+    warnings,
+  );
+  if (typeof process.id !== "string" || !process.id.trim()) {
+    errors.push("process.id: must be a non-empty string");
+  }
+  if (process.name !== undefined && (typeof process.name !== "string" || !process.name.trim())) {
+    errors.push("process.name: must be a non-empty string when set");
+  }
+  if (process.primary !== undefined && typeof process.primary !== "boolean") {
+    errors.push("process.primary: must be boolean when set");
+  }
+
+  if (!Array.isArray(process.states) || process.states.length < 1) {
+    errors.push("process.states: must contain at least one state");
+    return;
+  }
+  const stateIds = new Set();
+  for (let i = 0; i < process.states.length; i += 1) {
+    const state = process.states[i];
+    const prefix = `process.states[${i}]`;
+    if (!isPlainObject(state)) {
+      errors.push(`${prefix}: must be an object`);
+      continue;
+    }
+    pushUnknownKeyWarnings(
+      state,
+      new Set(["id", "name", "specialist", "layout", "instructions", "triggers", "exit_conditions", "block_conditions"]),
+      prefix,
+      warnings,
+    );
+    if (typeof state.id !== "string" || !state.id.trim()) {
+      errors.push(`${prefix}.id: must be a non-empty string`);
+    } else if (stateIds.has(state.id)) {
+      errors.push(`${prefix}.id: duplicate state id ${JSON.stringify(state.id)}`);
+    } else {
+      stateIds.add(state.id);
+    }
+    if (state.name !== undefined && (typeof state.name !== "string" || !state.name.trim())) {
+      errors.push(`${prefix}.name: must be a non-empty string when set`);
+    }
+    if (state.instructions !== undefined && typeof state.instructions !== "string") {
+      errors.push(`${prefix}.instructions: must be a string when set`);
+    }
+    if (state.specialist !== undefined && !isPlainObject(state.specialist) && typeof state.specialist !== "string") {
+      errors.push(`${prefix}.specialist: must be an object or string when set`);
+    }
+    if (state.layout !== undefined) {
+      if (!isPlainObject(state.layout)) {
+        errors.push(`${prefix}.layout: must be an object when set`);
+      } else {
+        pushUnknownKeyWarnings(state.layout, new Set(["x", "y"]), `${prefix}.layout`, warnings);
+        if (typeof state.layout.x !== "number" || !Number.isFinite(state.layout.x)) {
+          errors.push(`${prefix}.layout.x: must be a finite number`);
+        }
+        if (typeof state.layout.y !== "number" || !Number.isFinite(state.layout.y)) {
+          errors.push(`${prefix}.layout.y: must be a finite number`);
+        }
+      }
+    }
+  }
+
+  if (process.transitions !== undefined) {
+    if (!Array.isArray(process.transitions)) {
+      errors.push("process.transitions: must be a list when set");
+    } else {
+      for (let i = 0; i < process.transitions.length; i += 1) {
+        const transition = process.transitions[i];
+        const prefix = `process.transitions[${i}]`;
+        if (!isPlainObject(transition)) {
+          errors.push(`${prefix}: must be an object`);
+          continue;
+        }
+        pushUnknownKeyWarnings(transition, new Set(["from", "to", "condition"]), prefix, warnings);
+        if (!stateIds.has(transition.from)) {
+          errors.push(`${prefix}.from: must reference an existing state id`);
+        }
+        if (!stateIds.has(transition.to)) {
+          errors.push(`${prefix}.to: must reference an existing state id`);
+        }
+      }
+    }
+  }
+
+  if (process.routines !== undefined && !Array.isArray(process.routines)) {
+    errors.push("process.routines: must be a list when set");
+  }
+}
+
 function validateV2Lanes(obj, errors, warnings) {
   const agent = obj.agent;
   if (agent !== undefined) {
@@ -331,7 +470,9 @@ function validateV2Lanes(obj, errors, warnings) {
 const KNOWN_LANE_COMMON = new Set([
   "kind",
   "pattern",
+  "patterns",
   "pattern_version",
+  "fanout",
   "permissions",
   "runner",
   "timeout_minutes",
@@ -366,8 +507,36 @@ function validateLane(laneId, lane, errors, warnings) {
       `${prefix}.kind: must be one of ${LANE_KINDS.join("|")}; got ${JSON.stringify(lane.kind)}`,
     );
   }
-  if (typeof lane.pattern !== "string" || !lane.pattern.trim()) {
-    errors.push(`${prefix}.pattern: must be a non-empty pattern id`);
+  // ``patterns: [ids]`` is the canonical multi-pattern form (RFC-0008 C3);
+  // ``pattern: <id>`` is kept as the single-pattern alias so existing
+  // configs keep working. Exactly one of the two must be present.
+  const hasPatterns = Array.isArray(lane.patterns);
+  const hasPattern = typeof lane.pattern === "string";
+  if (hasPatterns && hasPattern) {
+    errors.push(
+      `${prefix}: use either 'pattern' (single) or 'patterns' (list), not both`,
+    );
+  } else if (hasPatterns) {
+    if (lane.patterns.length < 1) {
+      errors.push(`${prefix}.patterns: must contain at least one pattern id`);
+    } else {
+      for (let i = 0; i < lane.patterns.length; i += 1) {
+        const p = lane.patterns[i];
+        if (typeof p !== "string" || !p.trim()) {
+          errors.push(
+            `${prefix}.patterns[${i}]: must be a non-empty pattern id string`,
+          );
+        }
+      }
+    }
+  } else if (hasPattern) {
+    if (!lane.pattern.trim()) {
+      errors.push(`${prefix}.pattern: must be a non-empty pattern id`);
+    }
+  } else {
+    errors.push(
+      `${prefix}: must declare 'pattern' (single) or 'patterns' (list)`,
+    );
   }
   if (
     lane.pattern_version !== undefined &&
@@ -375,6 +544,21 @@ function validateLane(laneId, lane, errors, warnings) {
   ) {
     errors.push(`${prefix}.pattern_version: must be a non-empty semver string when set`);
   }
+  // RFC-0008 C3.2 — `fanout` picks how multi-pattern lanes execute.
+  // Single-pattern lanes ignore it (it's a no-op for them); we emit a
+  // warning rather than an error so schedule templates that set it
+  // blindly remain portable across single/multi-pattern use.
+  if (lane.fanout !== undefined) {
+    if (typeof lane.fanout !== "string" || !LANE_FANOUT_MODES.includes(lane.fanout)) {
+      errors.push(
+        `${prefix}.fanout: must be one of ${LANE_FANOUT_MODES.join("|")}; got ${JSON.stringify(lane.fanout)}`,
+      );
+    } else if (hasPattern || (hasPatterns && lane.patterns.length < 2)) {
+      warnings.push(
+        `${prefix}.fanout: ignored for single-pattern lanes (has no effect unless 'patterns' has ≥2 entries)`,
+      );
+    }
+  }
   if (lane.permissions !== undefined && !isPlainObject(lane.permissions)) {
     errors.push(`${prefix}.permissions: must be an object when set`);
   }
@@ -499,6 +683,7 @@ export function validateConfig(obj) {
 
   validateSharedSections(obj, errors, warnings);
   if (isV2) {
+    validateV2Process(obj, errors, warnings);
     validateV2Lanes(obj, errors, warnings);
   }
 
@@ -648,3 +833,69 @@ export function validateConfig(obj) {
   if (errors.length) return { ok: false, errors, warnings };
   return { ok: true, config: obj, warnings };
 }
+
+/**
+ * Return the canonical list of pattern ids for a lane.
+ *
+ * Accepts both the canonical ``patterns: [ids]`` (RFC-0008) and the
+ * legacy ``pattern: <id>`` single-string alias. Use this helper
+ * everywhere that reads ``lane.pattern`` / ``lane.patterns`` so the
+ * call-site never has to branch on the two shapes.
+ *
+ * For lanes that declared neither key (e.g. malformed config that
+ * slipped past validateConfig), returns an empty list rather than
+ * throwing — the caller already surfaced the validation error.
+ *
+ * @param {any} lane
+ * @returns {string[]}
+ */
+export function lanePatterns(lane) {
+  if (!lane || typeof lane !== "object") return [];
+  if (Array.isArray(lane.patterns)) {
+    return lane.patterns
+      .map((p) => (typeof p === "string" ? p.trim() : ""))
+      .filter(Boolean);
+  }
+  if (typeof lane.pattern === "string" && lane.pattern.trim()) {
+    return [lane.pattern.trim()];
+  }
+  return [];
+}
+
+/**
+ * The "primary" pattern id for a lane. Shorthand for ``lanePatterns(lane)[0]``
+ * with an explicit null for lanes that have no pattern.
+ *
+ * Intended for call-sites that currently only consume a single pattern
+ * (shipctl run, the renderer, the dashboard). They read this and will
+ * continue to work until multi-pattern execution lands (C3.2); until
+ * then, a lane with ``patterns.length > 1`` is rejected upstream by
+ * the executor with a clear error.
+ *
+ * @param {any} lane
+ * @returns {string | null}
+ */
+export function lanePrimaryPattern(lane) {
+  const list = lanePatterns(lane);
+  return list.length ? list[0] : null;
+}
+
+/**
+ * Resolve the effective fan-out mode for a lane.
+ *
+ * Returns ``LANE_FANOUT_DEFAULT`` (``matrix``) when the lane doesn't
+ * declare one or has at most one pattern (in which case the concept
+ * doesn't apply but we still want a deterministic value for downstream
+ * consumers). Unknown / invalid values fall back to the default; the
+ * validator already flags them as errors at config-load time.
+ *
+ * @param {any} lane
+ * @returns {"matrix" | "sequential" | "concurrent"}
+ */
+export function laneFanout(lane) {
+  if (!lane || typeof lane !== "object") return LANE_FANOUT_DEFAULT;
+  if (typeof lane.fanout === "string" && LANE_FANOUT_MODES.includes(lane.fanout)) {
+    return lane.fanout;
+  }
+  return LANE_FANOUT_DEFAULT;
+}

package/lib/config.mjs

@@ -8,6 +8,7 @@ export function extractGlobalArgv(argv) {
     baseUrl: (
       process.env.SHIP_API_BASE || "https://ship.elmundi.com/api/methodology"
     ).replace(/\/$/, ""),
+    baseUrlSource: process.env.SHIP_API_BASE ? "env" : "default",
     json: false,
     yes: false,
     force: false,
@@ -39,10 +40,12 @@ export function extractGlobalArgv(argv) {
     if (a === "--base-url" && copy[1]) {
       copy.shift();
       out.baseUrl = String(copy.shift()).replace(/\/$/, "");
+      out.baseUrlSource = "flag";
       continue;
     }
     if (a.startsWith("--base-url=")) {
       out.baseUrl = a.slice("--base-url=".length).replace(/\/$/, "");
+      out.baseUrlSource = "flag";
       copy.shift();
       continue;
     }

package/lib/state/idempotency.mjs

@@ -12,7 +12,7 @@
  *   {
  *     "version": 1,
  *     "lane": "seed_knowledge_starters",
- *     "pattern_id": "seed-knowledge-starters",
+ *     "pattern_id": "onboard-seed-knowledge",
  *     "pattern_sha256": "…",
  *     "pattern_version": "1.0.0",
  *     "completed_at": "2026-04-21T14:20:00Z",

package/lib/templates.mjs

@@ -30,8 +30,8 @@ Agent protocol (must follow before applying an artifact):
 
 \`\`\`bash
 shipctl pattern list
-shipctl pattern show cloud-developer              # resolves latest or pin
-shipctl pattern fetch cloud-developer --version 1.4.2
+shipctl pattern show role-developer              # resolves latest or pin
+shipctl pattern fetch role-developer --version 1.4.2
 shipctl search "release gates and qa split" --top-k 8
 shipctl docs fetch documentation/adoption/delivery-quality-and-release-process.md
 shipctl sync                                       # reconcile .ship/cache/
@@ -41,7 +41,7 @@ shipctl sync                                       # reconcile .ship/cache/
 
 \`\`\`bash
 curl -sS -X POST "${baseUrl}/fetch" -H "Content-Type: application/json" \\
-  -d '{"kind":"pattern","id":"cloud-developer"}'
+  -d '{"kind":"pattern","id":"role-developer"}'
 curl -sS "${baseUrl}/patterns"
 \`\`\`
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@elmundi/ship-cli",
-  "version": "0.11.2",
+  "version": "0.12.1",
   "type": "module",
-  "description": "Ship CLI — artifacts protocol (patterns/tools/workflows/collections), docs search/fetch/feedback, and agent init",
+  "description": "Ship CLI: bootstrap a repo, sync the Plays catalog, run Automations, report Runs.",
   "license": "Apache-2.0",
   "author": "Denys Kuzin",
   "repository": {