@elmundi/ship-cli 0.8.1 → 0.12.0

package/lib/commands/lanes.mjs

@@ -0,0 +1,527 @@
+/**
+ * `shipctl lanes` — generate and manage the thin GitHub Actions caller
+ * workflows that delegate to the reusable `run-agent.yml` (RFC-0007 Phase 3).
+ *
+ * Each lane in `.ship/config.yml` (v2) gets one file at
+ *   .github/workflows/ship-<lane_id>.yml
+ * whose body is nothing but the `on:` triggers (derived from the lane
+ * kind) and a single `uses: ElMundiUA/ship/.github/workflows/run-agent.yml@<ref>`
+ * call. Any customisation — flags, payload shape, callback URL wiring — is
+ * centralised in the reusable workflow so upgrading customer fleets is a
+ * single ref bump.
+ *
+ * Subcommands:
+ *   install   — render wrappers for every declared lane (or just --only X).
+ *   list      — print the lane map with the trigger each wrapper would emit.
+ *   remove    — delete previously-generated ship-*.yml wrappers.
+ *
+ * Everything is idempotent and marker-guarded; hand-edits outside the
+ * `<!-- ship-cli: lanes v1 -->` banner survive re-runs.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+
+import { findShipRoot, readConfig } from "../config/io.mjs";
+import {
+  validateConfig,
+  CONFIG_SCHEMA_VERSION,
+  lanePatterns,
+  lanePrimaryPattern,
+  laneFanout,
+} from "../config/schema.mjs";
+
+const EXIT_OK = 0;
+const EXIT_USAGE = 2;
+const EXIT_CONFIG = 10;
+
+const WORKFLOW_DIR = path.join(".github", "workflows");
+const BANNER_MARKER = "# ship-cli: lanes v1 — generated by `shipctl lanes install`.";
+const BANNER_HEADER = `${BANNER_MARKER}
+# Regenerate via: shipctl lanes install
+# Hand edits OUTSIDE the \`ship-cli:\` markers will NOT be overwritten.`;
+
+const DEFAULT_REUSABLE_OWNER = "ElMundiUA";
+const DEFAULT_REUSABLE_REPO = "ship";
+const DEFAULT_REUSABLE_PATH = ".github/workflows/run-agent.yml";
+
+function printHelp() {
+  console.log(`shipctl lanes — manage GitHub Actions caller workflows for the
+lanes declared in .ship/config.yml (each lane shows up as an
+Automation in the operator console; one Run is recorded per dispatch).
+
+Aliases: shipctl automations <subcmd>  (operator-friendly name; both work)
+
+USAGE
+  shipctl lanes install [--only <id,id>] [--ref <git-ref>] [--owner <gh-owner>]
+                        [--repo <repo>] [--shipctl-version <npm-tag>] [--dry-run]
+                        [--force] [--json] [--cwd <dir>]
+  shipctl lanes list [--json] [--cwd <dir>]
+  shipctl lanes remove [--only <id,id>] [--dry-run] [--json] [--cwd <dir>]
+
+FLAGS (install)
+  --only <ids>           Comma-separated lane ids to render (default: all).
+  --ref <git-ref>        Git ref of ElMundiUA/ship to pin the reusable workflow
+                         to (default: the shipctl_min version from config.yml,
+                         prefixed with 'v' — e.g. v0.12.0).
+  --owner <gh-owner>     GitHub owner of the ship repo (default: ElMundiUA).
+  --repo <name>          GitHub repo name (default: ship).
+  --shipctl-version <v>  Pin the @elmundi/ship-cli version the reusable
+                         workflow installs on the runner (default: latest).
+  --force                Overwrite wrappers that exist but were not generated
+                         by this tool (default: refuse and warn).
+  --dry-run              Show which files would be written without writing.
+  --json                 Emit a structured summary.
+
+EXIT
+  0    success (including --dry-run)
+  2    argument / IO / config-missing
+  10   .ship/config.yml failed validation
+`);
+}
+
+export async function lanesCommand(ctx, rest) {
+  const copy = [...rest];
+  const sub = copy.shift();
+  if (!sub || sub === "--help" || sub === "-h" || sub === "help") {
+    printHelp();
+    process.exit(EXIT_OK);
+  }
+  if (sub === "install") return installCmd(ctx, copy);
+  if (sub === "list") return listCmd(ctx, copy);
+  if (sub === "remove" || sub === "rm") return removeCmd(ctx, copy);
+  console.error(`unknown lanes subcommand: ${sub}\nRun: shipctl lanes --help`);
+  process.exit(EXIT_USAGE);
+}
+
+/* ─────────────────────────── install ─────────────────────────── */
+
+async function installCmd(ctx, rest) {
+  const args = parseInstallArgs(rest);
+  args.dryRun = args.dryRun || Boolean(ctx.dryRun);
+  args.force = args.force || Boolean(ctx.force);
+  args.json = args.json || Boolean(ctx.json);
+  const { cwd, config, shipRoot } = loadConfig(args.cwd);
+
+  const wanted = selectLanes(config, args.only);
+  if (wanted.length === 0) {
+    const payload = { ok: true, installed: [], skipped: [], errors: [] };
+    return emitSummary(ctx, args, payload, () =>
+      console.log("No lanes declared in .ship/config.yml — nothing to install."),
+    );
+  }
+
+  const ref = args.ref || deriveDefaultRef(config);
+  const reusable = formatReusableRef({
+    owner: args.owner || DEFAULT_REUSABLE_OWNER,
+    repo: args.repo || DEFAULT_REUSABLE_REPO,
+    ref,
+  });
+
+  const targetDir = path.join(shipRoot, WORKFLOW_DIR);
+  if (!args.dryRun) fs.mkdirSync(targetDir, { recursive: true });
+
+  const installed = [];
+  const skipped = [];
+  const errors = [];
+
+  for (const [laneId, lane] of wanted) {
+    const file = path.join(targetDir, `ship-${laneId}.yml`);
+    const rel = path.relative(shipRoot, file) || file;
+    const render = renderWrapper({
+      laneId,
+      lane,
+      reusable,
+      shipctlVersion: args.shipctlVersion || "latest",
+    });
+    if (render.error) {
+      errors.push({ lane: laneId, error: render.error });
+      continue;
+    }
+    const existed = fs.existsSync(file);
+    if (existed) {
+      const cur = fs.readFileSync(file, "utf8");
+      if (!cur.includes(BANNER_MARKER) && !args.force) {
+        skipped.push({ lane: laneId, path: rel, reason: "exists-without-banner" });
+        continue;
+      }
+      if (cur === render.content) {
+        skipped.push({ lane: laneId, path: rel, reason: "up-to-date" });
+        continue;
+      }
+    }
+    if (args.dryRun) {
+      installed.push({ lane: laneId, path: rel, action: existed ? "would-update" : "would-write" });
+      continue;
+    }
+    fs.writeFileSync(file, render.content, "utf8");
+    installed.push({ lane: laneId, path: rel, action: existed ? "updated" : "wrote" });
+  }
+
+  const payload = {
+    ok: errors.length === 0,
+    reusable,
+    dry_run: Boolean(args.dryRun),
+    installed,
+    skipped,
+    errors,
+  };
+
+  emitSummary(ctx, args, payload, () => {
+    console.log(`Ship lanes → ${reusable}`);
+    for (const row of installed) console.log(`  ${row.action}: ${row.path}`);
+    for (const row of skipped) console.log(`  skipped (${row.reason}): ${row.path}`);
+    for (const row of errors) console.log(`  ERROR: ${row.lane}: ${row.error}`);
+    if (args.dryRun) console.log("(--dry-run: no files written)");
+  });
+
+  if (errors.length) process.exit(EXIT_CONFIG);
+}
+
+/* ───────────────────────────── list ──────────────────────────── */
+
+function listCmd(ctx, rest) {
+  const args = parseListArgs(rest);
+  const { config } = loadConfig(args.cwd);
+  const rows = Object.entries(config.lanes || {}).map(([id, lane]) => {
+    const pats = lanePatterns(lane);
+    return {
+      lane: id,
+      kind: lane.kind,
+      // ``pattern`` keeps the single-string shape for humans/scripts
+      // that eyeball the first pattern; ``patterns`` always lists all
+      // so multi-pattern lanes (RFC-0008 C3.1) surface correctly.
+      pattern: pats[0] || null,
+      patterns: pats,
+      // ``fanout`` resolves to the runtime default (``matrix``) when
+      // the lane doesn't declare one, so the workflow plan step
+      // doesn't have to branch on "is this key missing?" (RFC-0008 C3.2).
+      fanout: laneFanout(lane),
+      on: lane.kind === "event" ? lane.on || null : null,
+      cron: lane.kind === "schedule" ? lane.cron || null : null,
+      idempotency_key: lane.kind === "once" ? lane.idempotency?.key || null : null,
+    };
+  });
+  if (ctx.json || args.json) {
+    console.log(JSON.stringify({ ok: true, lanes: rows }, null, 2));
+    return;
+  }
+  if (!rows.length) {
+    console.log("No lanes declared.");
+    return;
+  }
+  for (const row of rows) {
+    const trigger =
+      row.kind === "event"
+        ? `on ${row.on}`
+        : row.kind === "schedule"
+          ? `cron ${JSON.stringify(row.cron)}`
+          : `once ${row.idempotency_key || ""}`;
+    const patternLabel =
+      row.patterns.length > 1
+        ? `patterns=[${row.patterns.join(", ")}]`
+        : `pattern=${row.pattern || "-"}`;
+    console.log(
+      `  ${row.lane.padEnd(28)} kind=${row.kind.padEnd(9)} ${trigger}  (${patternLabel})`,
+    );
+  }
+}
+
+/* ──────────────────────────── remove ─────────────────────────── */
+
+function removeCmd(ctx, rest) {
+  const args = parseRemoveArgs(rest);
+  args.dryRun = args.dryRun || Boolean(ctx.dryRun);
+  args.json = args.json || Boolean(ctx.json);
+  const { shipRoot } = loadConfig(args.cwd, { requireValid: false });
+  const targetDir = path.join(shipRoot, WORKFLOW_DIR);
+  if (!fs.existsSync(targetDir)) {
+    emitSummary(ctx, args, { ok: true, removed: [], skipped: [] }, () =>
+      console.log("No .github/workflows directory; nothing to remove."),
+    );
+    return;
+  }
+  const wanted = args.only ? new Set(args.only) : null;
+  const removed = [];
+  const skipped = [];
+  for (const entry of fs.readdirSync(targetDir)) {
+    const m = /^ship-(.+)\.ya?ml$/.exec(entry);
+    if (!m) continue;
+    const laneId = m[1];
+    if (wanted && !wanted.has(laneId)) continue;
+    const file = path.join(targetDir, entry);
+    const rel = path.relative(shipRoot, file) || file;
+    const content = fs.readFileSync(file, "utf8");
+    if (!content.includes(BANNER_MARKER)) {
+      skipped.push({ lane: laneId, path: rel, reason: "not-generated-by-shipctl" });
+      continue;
+    }
+    if (args.dryRun) {
+      removed.push({ lane: laneId, path: rel, action: "would-remove" });
+      continue;
+    }
+    fs.unlinkSync(file);
+    removed.push({ lane: laneId, path: rel, action: "removed" });
+  }
+  emitSummary(ctx, args, { ok: true, dry_run: Boolean(args.dryRun), removed, skipped }, () => {
+    for (const row of removed) console.log(`  ${row.action}: ${row.path}`);
+    for (const row of skipped) console.log(`  skipped (${row.reason}): ${row.path}`);
+    if (args.dryRun) console.log("(--dry-run: no files removed)");
+  });
+}
+
+/* ─────────────────────────── helpers ─────────────────────────── */
+
+function loadConfig(cwdOverride, { requireValid = true } = {}) {
+  const cwd = cwdOverride || process.cwd();
+  const shipRoot = findShipRoot(cwd);
+  if (!shipRoot) {
+    console.error(`No .ship/config.yml found upward from ${cwd}.`);
+    process.exit(EXIT_USAGE);
+  }
+  let read;
+  try {
+    read = readConfig(cwd);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(EXIT_USAGE);
+  }
+  if (requireValid) {
+    const v = validateConfig(read.config);
+    if (!v.ok) {
+      for (const e of v.errors) console.error(e);
+      process.exit(EXIT_CONFIG);
+    }
+    for (const w of v.warnings) console.error(`warn: ${w}`);
+    if (Number(read.config.version) !== CONFIG_SCHEMA_VERSION) {
+      console.error(
+        `warn: .ship/config.yml is v${read.config.version}; run 'shipctl migrate' to use lanes.`,
+      );
+    }
+  }
+  return { cwd, shipRoot, config: read.config };
+}
+
+function selectLanes(config, onlyCsv) {
+  const all = Object.entries(config.lanes || {});
+  if (!onlyCsv || onlyCsv.length === 0) return all;
+  const wanted = new Set(onlyCsv);
+  return all.filter(([id]) => wanted.has(id));
+}
+
+function deriveDefaultRef(config) {
+  const min = config.shipctl_min;
+  if (typeof min === "string" && /^\d+\.\d+\.\d+/.test(min)) return `v${min}`;
+  return "main";
+}
+
+function formatReusableRef({ owner, repo, ref }) {
+  return `${owner}/${repo}/${DEFAULT_REUSABLE_PATH}@${ref}`;
+}
+
+/**
+ * Render the caller workflow YAML. The body is structured first as a JS
+ * object so the output is guaranteed to be syntactically valid; we then
+ * prepend the banner comment block.
+ *
+ * @returns {{content?: string, error?: string}}
+ */
+export function renderWrapper({ laneId, lane, reusable, shipctlVersion }) {
+  const kind = lane && lane.kind;
+  const on = onBlockForLane(lane);
+  if (on.error) return { error: on.error };
+
+  const permissions = lane.permissions && Object.keys(lane.permissions).length
+    ? { ...lane.permissions }
+    : { contents: "read" };
+
+  const doc = {
+    name: `Ship · ${laneId}`,
+    on: on.value,
+    permissions,
+    jobs: {
+      run: {
+        uses: reusable,
+        with: {
+          lane: laneId,
+          shipctl_version: shipctlVersion,
+        },
+        secrets: "inherit",
+      },
+    },
+  };
+
+  // For kind=once lanes we expose the run_id / callback_url / etc so the
+  // Ship dashboard can dispatch against the wrapper. We only attach these
+  // under workflow_dispatch so cron/event triggers don't pay the cost.
+  if (kind === "once" || (on.value && on.value.workflow_dispatch)) {
+    doc.on = ensureDispatchInputs(on.value);
+    doc.jobs.run.with.ship_run_id = "${{ inputs.ship_run_id }}";
+    doc.jobs.run.with.ship_callback_url = "${{ inputs.ship_callback_url }}";
+  }
+
+  let body;
+  try {
+    body = YAML.stringify(doc, {
+      lineWidth: 0,
+      defaultStringType: "PLAIN",
+      defaultKeyType: "PLAIN",
+    });
+  } catch (err) {
+    return { error: `yaml render failed: ${err instanceof Error ? err.message : err}` };
+  }
+
+  const content = `${BANNER_HEADER}\n# lane: ${laneId}   kind: ${kind}\n${body}`;
+  return { content };
+}
+
+function onBlockForLane(lane) {
+  const kind = lane && lane.kind;
+  const dispatch = {
+    workflow_dispatch: {
+      inputs: {
+        ship_run_id: { description: "Ship pipeline_run id", required: false, type: "string" },
+        ship_callback_url: {
+          description: "Ship callback URL",
+          required: false,
+          type: "string",
+        },
+      },
+    },
+  };
+  if (kind === "once") return { value: dispatch };
+  if (kind === "schedule") {
+    if (!lane.cron) return { error: "schedule lane missing `cron`" };
+    return { value: { ...dispatch, schedule: [{ cron: String(lane.cron) }] } };
+  }
+  if (kind === "event") {
+    if (!lane.on) return { error: "event lane missing `on`" };
+    const eventBlock = lane.when && Object.keys(lane.when).length
+      ? { types: Array.isArray(lane.when.types) ? lane.when.types : undefined }
+      : {};
+    // We don't try to fully translate `when.conclusion` etc — those are
+    // runtime checks in the reusable workflow; the caller just needs to
+    // fire on the event.
+    const event = {};
+    event[String(lane.on)] = Object.keys(eventBlock).length ? eventBlock : null;
+    return { value: { ...dispatch, ...event } };
+  }
+  return { error: `unknown lane kind: ${kind}` };
+}
+
+function ensureDispatchInputs(onValue) {
+  if (!onValue || typeof onValue !== "object") return onValue;
+  if (!onValue.workflow_dispatch) {
+    onValue.workflow_dispatch = {
+      inputs: {
+        ship_run_id: { description: "Ship pipeline_run id", required: false, type: "string" },
+        ship_callback_url: {
+          description: "Ship callback URL",
+          required: false,
+          type: "string",
+        },
+      },
+    };
+  }
+  return onValue;
+}
+
+/* ─────────────────────────── arg parsing ─────────────────────────── */
+
+function parseInstallArgs(rest) {
+  const out = {
+    cwd: null,
+    only: null,
+    ref: null,
+    owner: null,
+    repo: null,
+    shipctlVersion: null,
+    dryRun: false,
+    force: false,
+    json: false,
+  };
+  const copy = [...rest];
+  while (copy.length) {
+    const a = copy.shift();
+    if (a === "--help" || a === "-h") {
+      printHelp();
+      process.exit(EXIT_OK);
+    } else if (a === "--dry-run") out.dryRun = true;
+    else if (a === "--force") out.force = true;
+    else if (a === "--json") out.json = true;
+    else if (a === "--only" && copy[0] !== undefined) out.only = csv(copy.shift());
+    else if (a && a.startsWith("--only=")) out.only = csv(a.slice("--only=".length));
+    else if (a === "--ref" && copy[0] !== undefined) out.ref = String(copy.shift());
+    else if (a && a.startsWith("--ref=")) out.ref = a.slice("--ref=".length);
+    else if (a === "--owner" && copy[0] !== undefined) out.owner = String(copy.shift());
+    else if (a && a.startsWith("--owner=")) out.owner = a.slice("--owner=".length);
+    else if (a === "--repo" && copy[0] !== undefined) out.repo = String(copy.shift());
+    else if (a && a.startsWith("--repo=")) out.repo = a.slice("--repo=".length);
+    else if (a === "--shipctl-version" && copy[0] !== undefined) out.shipctlVersion = String(copy.shift());
+    else if (a && a.startsWith("--shipctl-version=")) out.shipctlVersion = a.slice("--shipctl-version=".length);
+    else if (a === "--cwd" && copy[0] !== undefined) out.cwd = path.resolve(String(copy.shift()));
+    else if (a && a.startsWith("--cwd=")) out.cwd = path.resolve(a.slice("--cwd=".length));
+    else {
+      console.error(`unknown argument: ${a}\nRun: shipctl lanes install --help`);
+      process.exit(EXIT_USAGE);
+    }
+  }
+  return out;
+}
+
+function parseListArgs(rest) {
+  const out = { cwd: null, json: false };
+  const copy = [...rest];
+  while (copy.length) {
+    const a = copy.shift();
+    if (a === "--json") out.json = true;
+    else if (a === "--cwd" && copy[0] !== undefined) out.cwd = path.resolve(String(copy.shift()));
+    else if (a && a.startsWith("--cwd=")) out.cwd = path.resolve(a.slice("--cwd=".length));
+    else if (a === "--help" || a === "-h") {
+      printHelp();
+      process.exit(EXIT_OK);
+    } else {
+      console.error(`unknown argument: ${a}`);
+      process.exit(EXIT_USAGE);
+    }
+  }
+  return out;
+}
+
+function parseRemoveArgs(rest) {
+  const out = { cwd: null, only: null, dryRun: false, json: false };
+  const copy = [...rest];
+  while (copy.length) {
+    const a = copy.shift();
+    if (a === "--dry-run") out.dryRun = true;
+    else if (a === "--json") out.json = true;
+    else if (a === "--only" && copy[0] !== undefined) out.only = csv(copy.shift());
+    else if (a && a.startsWith("--only=")) out.only = csv(a.slice("--only=".length));
+    else if (a === "--cwd" && copy[0] !== undefined) out.cwd = path.resolve(String(copy.shift()));
+    else if (a && a.startsWith("--cwd=")) out.cwd = path.resolve(a.slice("--cwd=".length));
+    else if (a === "--help" || a === "-h") {
+      printHelp();
+      process.exit(EXIT_OK);
+    } else {
+      console.error(`unknown argument: ${a}`);
+      process.exit(EXIT_USAGE);
+    }
+  }
+  return out;
+}
+
+function csv(value) {
+  return String(value || "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function emitSummary(ctx, args, payload, humanFn) {
+  if (ctx.json || args.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    humanFn();
+  }
+}