@elmundi/ship-cli 0.14.2 → 0.15.4

package/lib/commands/lanes.mjs

@@ -1,566 +0,0 @@
-/**
- * `shipctl lanes` — generate and manage the thin GitHub Actions caller
- * workflows that delegate to a **vendored** reusable `run-agent.yml` in the
- * same repository (RFC-0007 Phase 3).
- *
- * Each lane in `.ship/config.yml` (v2) gets one file at
- *   .github/workflows/ship-<lane_id>.yml
- * whose body is the `on:` triggers (derived from the lane kind) and
- *   `uses: ./.github/workflows/run-agent.yml`
- * `shipctl lanes install` also writes `.github/workflows/run-agent.yml`
- * from the template bundled inside `@elmundi/ship-cli`.
- *
- * 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 { fileURLToPath } from "node:url";
-import YAML from "yaml";
-
-import { findShipRoot, readConfig } from "../config/io.mjs";
-import {
-  validateConfig,
-  CONFIG_SCHEMA_VERSION,
-  lanePatterns,
-  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.`;
-
-/** Same-repo reusable workflow path (GitHub Actions). */
-const LOCAL_REUSABLE_USES = "./.github/workflows/run-agent.yml";
-
-const RUN_AGENT_MARKER = "# ship-cli: run-agent v1";
-
-function readRunAgentTemplate() {
-  const dir = path.dirname(fileURLToPath(import.meta.url));
-  const vendor = path.join(dir, "..", "vendor", "run-agent.workflow.yml");
-  return fs.readFileSync(vendor, "utf8");
-}
-
-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, --owner, --repo Ignored (legacy); reusable workflow is always
-                         ${LOCAL_REUSABLE_USES} in the caller repo.
-  --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 ─────────────────────────── */
-
-/**
- * Copy vendored `run-agent.workflow.yml` into `.github/workflows/run-agent.yml`.
- */
-function syncRunAgentTemplate({ runAgentFile, runAgentRel, dryRun, force, installed, skipped }) {
-  let template;
-  try {
-    template = readRunAgentTemplate();
-  } catch (err) {
-    throw new Error(
-      `cannot read bundled run-agent template: ${err instanceof Error ? err.message : err}`,
-    );
-  }
-  const existed = fs.existsSync(runAgentFile);
-  if (existed) {
-    const cur = fs.readFileSync(runAgentFile, "utf8");
-    if (!cur.includes(RUN_AGENT_MARKER) && !force) {
-      skipped.push({ path: runAgentRel, reason: "run-agent-exists-without-banner" });
-      return;
-    }
-    if (cur === template) {
-      skipped.push({ path: runAgentRel, reason: "run-agent-up-to-date" });
-      return;
-    }
-  }
-  if (dryRun) {
-    installed.push({
-      path: runAgentRel,
-      action: existed ? "would-update-run-agent" : "would-write-run-agent",
-    });
-    return;
-  }
-  fs.mkdirSync(path.dirname(runAgentFile), { recursive: true });
-  fs.writeFileSync(runAgentFile, template, "utf8");
-  installed.push({
-    path: runAgentRel,
-    action: existed ? "updated-run-agent" : "wrote-run-agent",
-  });
-}
-
-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 reusable = LOCAL_REUSABLE_USES;
-  const targetDir = path.join(shipRoot, WORKFLOW_DIR);
-  const runAgentFile = path.join(targetDir, "run-agent.yml");
-  const runAgentRel = path.relative(shipRoot, runAgentFile) || runAgentFile;
-
-  const installed = [];
-  const skipped = [];
-  const errors = [];
-
-  syncRunAgentTemplate({
-    runAgentFile,
-    runAgentRel,
-    dryRun: args.dryRun,
-    force: args.force,
-    installed,
-    skipped,
-  });
-
-  if (!args.dryRun) fs.mkdirSync(targetDir, { recursive: true });
-
-  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 ${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 routines (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));
-}
-
-/**
- * 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();
-  }
-}