@elmundi/ship-cli 0.8.1 → 0.12.0

package/lib/commands/verify.mjs

@@ -0,0 +1,187 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readConfig, findShipRoot } from "../config/io.mjs";
+import { allChecks, runChecks, summarize } from "../verify/registry.mjs";
+
+const SEVERITY_ORDER = { info: 0, warn: 1, error: 2 };
+
+function parseArgs(argv) {
+  const out = {
+    cwd: null,
+    check: /** @type {string[]} */ ([]),
+    json: false,
+    noNetwork: false,
+    severity: "info",
+    help: false,
+  };
+  const copy = [...argv];
+  while (copy.length) {
+    const a = copy.shift();
+    if (a === "--help" || a === "-h") { out.help = true; continue; }
+    if (a === "--json") { out.json = true; continue; }
+    if (a === "--no-network") { out.noNetwork = true; continue; }
+    if (a === "--cwd" && copy.length) { out.cwd = copy.shift(); continue; }
+    if (a && a.startsWith("--cwd=")) { out.cwd = a.slice("--cwd=".length); continue; }
+    if (a === "--check" && copy.length) {
+      for (const s of String(copy.shift()).split(",")) {
+        const id = s.trim();
+        if (id) out.check.push(id);
+      }
+      continue;
+    }
+    if (a && a.startsWith("--check=")) {
+      for (const s of a.slice("--check=".length).split(",")) {
+        const id = s.trim();
+        if (id) out.check.push(id);
+      }
+      continue;
+    }
+    if (a === "--severity" && copy.length) { out.severity = copy.shift(); continue; }
+    if (a && a.startsWith("--severity=")) { out.severity = a.slice("--severity=".length); continue; }
+    // Silently ignore unknown flags so globals (--base-url, --json) don't blow up.
+  }
+  if (!["info", "warn", "error"].includes(out.severity)) {
+    throw new Error(`verify: unknown --severity '${out.severity}'. Expected: info|warn|error`);
+  }
+  return out;
+}
+
+function printHelp() {
+  console.log(`shipctl verify — post-adoption liveness check for a Ship repo.
+
+USAGE
+  shipctl verify [--cwd DIR] [--check <id,...>] [--no-network]
+                 [--severity info|warn|error] [--json]
+
+OPTIONS
+  --cwd DIR            Target repo root (defaults to cwd / nearest .ship/).
+  --check <id,...>     Run only the listed check ids (csv or repeated).
+  --no-network         Skip checks in the 'network' category.
+  --severity <level>   Filter displayed rows:
+                         info  (default)  — show all checks (pass/warn/fail/skip)
+                         warn             — show warn + fail only
+                         error            — show fail only
+  --json               Machine-readable output: {checks:[...], summary:{...}}.
+
+EXIT CODE
+  0 when no checks returned 'fail' (warnings do not fail).
+  1 when at least one check failed.
+
+AVAILABLE CHECKS
+${allChecks().map((c) => `  ${c.id.padEnd(22)} ${c.description}`).join("\n")}
+`);
+}
+
+function loadConfig(cwd) {
+  try {
+    const { config } = readConfig(cwd);
+    return config;
+  } catch {
+    return null;
+  }
+}
+
+function loadInventory(cwd) {
+  const root = findShipRoot(cwd) || cwd;
+  const invPath = path.join(root, ".ship", "inventory.json");
+  if (!fs.existsSync(invPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(invPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function pickByStatus(rows, severity) {
+  if (severity === "info") return rows;
+  if (severity === "warn") return rows.filter((r) => r.status === "warn" || r.status === "fail");
+  return rows.filter((r) => r.status === "fail");
+}
+
+function badge(status) {
+  return `[${status}]`;
+}
+
+function pad(s, n) {
+  s = String(s);
+  if (s.length >= n) return s;
+  return s + " ".repeat(n - s.length);
+}
+
+/**
+ * @param {{json:boolean, yes:boolean, force:boolean, dryRun:boolean, baseUrl?:string}} ctx
+ * @param {string[]} args
+ */
+export async function verifyCommand(ctx, args) {
+  let parsed;
+  try {
+    parsed = parseArgs(args);
+  } catch (e) {
+    console.error(e.message);
+    process.exit(2);
+    return;
+  }
+  if (parsed.help) { printHelp(); return; }
+  if (ctx && ctx.json) parsed.json = true;
+
+  const rawCwd = parsed.cwd || process.cwd();
+  const resolvedRoot = findShipRoot(rawCwd) || path.resolve(rawCwd);
+
+  const config = loadConfig(resolvedRoot);
+  const inventory = loadInventory(resolvedRoot);
+  const baseUrl = (ctx && ctx.baseUrl)
+    || (config && config.api && config.api.base_url)
+    || process.env.SHIP_API_BASE
+    || "https://ship.elmundi.com";
+
+  const checkCtx = {
+    cwd: resolvedRoot,
+    config,
+    inventory,
+    baseUrl,
+    logger: (msg) => { if (!parsed.json) process.stderr.write(`${msg}\n`); },
+  };
+
+  const rows = await runChecks(checkCtx, {
+    filter: parsed.check.length ? parsed.check : null,
+    noNetwork: parsed.noNetwork,
+  });
+  const summary = summarize(rows);
+  const exitCode = summary.fail > 0 ? 1 : 0;
+
+  if (parsed.json) {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          cwd: resolvedRoot,
+          checks: rows,
+          summary,
+          exit_code: exitCode,
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    process.exit(exitCode);
+    return;
+  }
+
+  const header = [`Ship verify — ${resolvedRoot}`, ""];
+  const visible = pickByStatus(rows, parsed.severity);
+  const idWidth = Math.max(
+    14,
+    ...visible.map((r) => r.id.length),
+  );
+
+  const body = visible.map((r) => `${badge(r.status)} ${pad(r.id, idWidth)}  ${r.detail}`);
+  const footer = [
+    "",
+    `${summary.total} check${summary.total === 1 ? "" : "s"} total: ${summary.pass} pass, ${summary.warn} warn, ${summary.fail} fail, ${summary.skip} skip`,
+    `Exit code: ${exitCode}${summary.fail ? " (any fail)" : ""}`,
+  ];
+  if (!visible.length) {
+    body.push(`(no checks match --severity ${parsed.severity})`);
+  }
+  process.stdout.write(`${header.concat(body, footer).join("\n")}\n`);
+  process.exit(exitCode);
+}

package/lib/config/io.mjs

@@ -0,0 +1,232 @@
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import YAML from "yaml";
+import { DEFAULT_CONFIG } from "./schema.mjs";
+
+export const SHIP_DIR = ".ship";
+export const CONFIG_REL = path.join(SHIP_DIR, "config.yml");
+export const STATE_REL = path.join(SHIP_DIR, "state.json");
+
+/**
+ * Walk upward from startCwd looking for `.ship/config.yml`.
+ * Returns the directory containing `.ship/` or null.
+ * @param {string} startCwd
+ * @returns {string | null}
+ */
+export function findShipRoot(startCwd) {
+  let dir = path.resolve(startCwd || process.cwd());
+  for (;;) {
+    if (fs.existsSync(path.join(dir, CONFIG_REL))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Stable top-level and nested key order. Unknown keys are appended alphabetically.
+ *
+ * v2 introduces `agent` and `lanes` at the top level, plus nested keys
+ * under each lane. We keep them in their "natural reading order" so a
+ * human diffing two configs doesn't see a churn just because `shipctl
+ * config set` rewrote the file.
+ */
+const KEY_ORDER = {
+  __root: [
+    "version",
+    "shipctl_min",
+    "api",
+    "stack",
+    "agent",
+    "lanes",
+    "artifacts",
+    "cache",
+    "telemetry",
+  ],
+  api: ["base_url", "channel", "ttl_hours", "offline_ok"],
+  stack: ["tracker", "ci", "agents", "agent", "language", "preset"],
+  "stack.agent": ["provider"],
+  agent: ["default", "overrides"],
+  "agent.default": ["provider"],
+  /* lanes.* is handled by LANE_KEY_ORDER below — each lane follows the
+   * same ordering regardless of its id. */
+  artifacts: ["pins", "auto_update"],
+  cache: ["vcs_tracked"],
+  telemetry: ["share", "anonymous_id", "scope"],
+  "telemetry.scope": ["artifact_usage", "improvement_drafts", "errors"],
+};
+
+const LANE_KEY_ORDER = [
+  "kind",
+  "pattern",
+  "pattern_version",
+  "on",
+  "when",
+  "cron",
+  "cron_tz",
+  "idempotency",
+  "permissions",
+  "runner",
+  "timeout_minutes",
+  "concurrency",
+];
+
+const LANE_IDEMPOTENCY_KEY_ORDER = ["key", "store", "reset_on"];
+
+function orderForPath(pathKey) {
+  /* lanes.<anything> — single lane entry, always share the same order */
+  if (/^lanes\.[^.]+$/.test(pathKey)) return LANE_KEY_ORDER;
+  if (/^lanes\.[^.]+\.idempotency$/.test(pathKey)) return LANE_IDEMPOTENCY_KEY_ORDER;
+  return KEY_ORDER[pathKey] || [];
+}
+
+const USER_KEYED_LEAF_MAPS = new Set(["artifacts.pins", "agent.overrides"]);
+const USER_KEYED_STRUCT_MAPS = new Set(["lanes"]);
+
+function orderedCopy(obj, pathKey) {
+  if (!obj || typeof obj !== "object" || Array.isArray(obj)) return obj;
+
+  /* User-keyed leaf map: keep author's key order, don't recurse (values
+   * are simple scalars like a semver string). */
+  if (USER_KEYED_LEAF_MAPS.has(pathKey)) {
+    const out = {};
+    for (const k of Object.keys(obj)) out[k] = obj[k];
+    return out;
+  }
+
+  /* User-keyed struct map: keep author's key order, but recurse into
+   * each entry so its internal fields get normalised. */
+  if (USER_KEYED_STRUCT_MAPS.has(pathKey)) {
+    const out = {};
+    for (const k of Object.keys(obj)) {
+      out[k] = orderedCopy(obj[k], `${pathKey}.${k}`);
+    }
+    return out;
+  }
+
+  const order = orderForPath(pathKey);
+  const remaining = new Set(Object.keys(obj));
+  const out = {};
+  for (const k of order) {
+    if (remaining.has(k)) {
+      out[k] = obj[k];
+      remaining.delete(k);
+    }
+  }
+  for (const k of [...remaining].sort()) out[k] = obj[k];
+
+  for (const [k, v] of Object.entries(out)) {
+    const childKey = pathKey === "__root" ? k : pathKey ? `${pathKey}.${k}` : k;
+    out[k] = orderedCopy(v, childKey);
+  }
+  return out;
+}
+
+/**
+ * @param {string} cwd
+ * @returns {{config:object, filePath:string}}
+ */
+export function readConfig(cwd) {
+  const root = findShipRoot(cwd);
+  if (!root) {
+    throw new Error(
+      `.ship/config.yml not found (searched from ${path.resolve(cwd || process.cwd())} upward). Run 'shipctl config init' first.`,
+    );
+  }
+  const filePath = path.join(root, CONFIG_REL);
+  let text;
+  try {
+    text = fs.readFileSync(filePath, "utf8");
+  } catch (e) {
+    throw new Error(`Failed to read ${filePath}: ${e.message}`);
+  }
+  let parsed;
+  try {
+    parsed = YAML.parse(text);
+  } catch (e) {
+    throw new Error(`Failed to parse ${filePath}: ${e.message}`);
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error(`${filePath}: top-level must be a YAML mapping`);
+  }
+  return { config: parsed, filePath };
+}
+
+/**
+ * @param {string} filePath
+ * @param {object} config
+ */
+export function writeConfig(filePath, config) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const ordered = orderedCopy(JSON.parse(JSON.stringify(config)), "__root");
+  const body = YAML.stringify(ordered, {
+    lineWidth: 0,
+    indent: 2,
+    defaultStringType: "PLAIN",
+  });
+  const tmp = `${filePath}.tmp`;
+  fs.writeFileSync(tmp, body, "utf8");
+  fs.renameSync(tmp, filePath);
+}
+
+/**
+ * Generate a fresh UUID v4 into config.telemetry.anonymous_id if missing/invalid.
+ * Mutates the config in place.
+ * @param {object} config
+ * @returns {string} the resulting anonymous_id
+ */
+export function ensureAnonymousId(config) {
+  if (!config.telemetry || typeof config.telemetry !== "object") config.telemetry = {};
+  const cur = config.telemetry.anonymous_id;
+  const valid =
+    typeof cur === "string" &&
+    /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(cur);
+  if (!valid) config.telemetry.anonymous_id = randomUUID();
+  return config.telemetry.anonymous_id;
+}
+
+/**
+ * Default empty state for .ship/state.json.
+ */
+export function defaultState() {
+  return {
+    last_sync_at: null,
+    last_manifest_hash: null,
+    outbox_pending_count: 0,
+  };
+}
+
+/**
+ * @param {string} cwd
+ * @returns {{state:object, filePath:string}}
+ */
+export function readState(cwd) {
+  const root = findShipRoot(cwd);
+  if (!root) throw new Error(".ship/ not found; run 'shipctl config init' first.");
+  const filePath = path.join(root, STATE_REL);
+  if (!fs.existsSync(filePath)) return { state: defaultState(), filePath };
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    return { state: { ...defaultState(), ...(parsed || {}) }, filePath };
+  } catch (e) {
+    throw new Error(`Failed to parse ${filePath}: ${e.message}`);
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @param {object} state
+ */
+export function writeState(cwd, state) {
+  const root = findShipRoot(cwd);
+  if (!root) throw new Error(".ship/ not found; run 'shipctl config init' first.");
+  const filePath = path.join(root, STATE_REL);
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+  fs.renameSync(tmp, filePath);
+  return filePath;
+}
+
+export { DEFAULT_CONFIG };

package/lib/config/migrate.mjs

@@ -0,0 +1,223 @@
+/**
+ * `shipctl migrate` — convert `.ship/config.yml` from v1 to v2.
+ *
+ * v2 introduces the `lanes` map, `agent.default/overrides`, and deprecates
+ * the `workflow` artifact kind. The migration is deliberately conservative:
+ *
+ *   - Every v1 field we still recognise is copied verbatim, not rewritten.
+ *   - `stack.agent.provider` is lifted into `agent.default.provider`; we
+ *     leave `stack.agent` intact so rolling back to an old shipctl still
+ *     finds the field where v1 expected it.
+ *   - The legacy `lanes:` list-of-strings (a shape customers wrote by
+ *     hand between 0.9.x and 0.11.x — not a formal v1 field but widely
+ *     present on disk) is translated into the v2 `lanes:` map using the
+ *     preset defaults table below.
+ *   - Unknown keys survive at the top level; v2 validation emits a
+ *     warning but does not drop them.
+ *
+ * The migration is idempotent: running it against a v2 config returns
+ * the input untouched.
+ */
+
+import {
+  CONFIG_SCHEMA_VERSION,
+  DEFAULT_PROCESS_CONFIG,
+  LEGACY_CONFIG_SCHEMA_VERSION,
+} from "./schema.mjs";
+
+/**
+ * Default lane translations for the well-known v1 `lanes:` list entries.
+ * Each entry maps the v1 string id to a v2 lane body. These were the
+ * four lane ids the `monorepo`, `web-app`, and `api-backend` presets
+ * bundled; anything outside this table is left for the caller to fill
+ * in manually (the migrator warns and adds a stub).
+ *
+ * Keep these aligned with `artifacts/collections/preset-*` and with
+ * RFC-0007 §"Lane-id reservations".
+ */
+const V1_LANE_DEFAULTS = Object.freeze({
+  pr_review: {
+    kind: "event",
+    pattern: "flow-pr-self-review",
+    on: "pull_request",
+    permissions: { contents: "read", "pull-requests": "write" },
+  },
+  daily_standup: {
+    kind: "schedule",
+    pattern: "flow-daily-retro",
+    cron: "0 9 * * 1-5",
+  },
+  tech_debt: {
+    kind: "schedule",
+    pattern: "flow-learning-capture",
+    cron: "0 10 * * 1",
+  },
+  self_heal: {
+    kind: "event",
+    pattern: "op-workflow-self-heal",
+    on: "workflow_run",
+    when: { conclusion: "failure" },
+    permissions: { contents: "read", actions: "read", "pull-requests": "write" },
+  },
+});
+
+/**
+ * @typedef {{
+ *   migrated: boolean,
+ *   config: object,
+ *   warnings: string[],
+ *   stub_lanes: string[],
+ * }} MigrationResult
+ */
+
+/**
+ * Migrate a parsed config object from v1 to v2. Returns a fresh config
+ * object (input is not mutated) plus any non-fatal warnings.
+ *
+ * @param {object} input
+ * @returns {MigrationResult}
+ */
+export function migrateV1ToV2(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("migrate: config must be a mapping");
+  }
+
+  if (input.version === CONFIG_SCHEMA_VERSION) {
+    return {
+      migrated: false,
+      config: input,
+      warnings: ["config already at v2; nothing to do"],
+      stub_lanes: [],
+    };
+  }
+  if (input.version !== LEGACY_CONFIG_SCHEMA_VERSION) {
+    throw new Error(
+      `migrate: unsupported source version ${JSON.stringify(input.version)}; only v${LEGACY_CONFIG_SCHEMA_VERSION} is supported`,
+    );
+  }
+
+  /* Deep-clone first — never touch the caller's object. YAML parse
+   * output is pure JSON so JSON round-trip is safe. */
+  const src = JSON.parse(JSON.stringify(input));
+  const warnings = [];
+  const stubLanes = [];
+
+  const out = {
+    version: CONFIG_SCHEMA_VERSION,
+    /* Bump the hard floor to the release that introduces v2. Anyone
+     * stuck on <0.12 will fail loudly on read instead of silently
+     * pretending v2 is v1. */
+    shipctl_min: bumpFloor(src.shipctl_min, "0.12.0"),
+  };
+
+  /* api / stack / cache / telemetry / artifacts survive verbatim — v2
+   * only added new top-level siblings. Preserve unknown keys too so a
+   * future field added by a newer shipctl on the same config doesn't
+   * get eaten by an older migrator. */
+  for (const k of Object.keys(src)) {
+    if (k === "version" || k === "shipctl_min") continue;
+    if (k === "lanes") continue; /* handled below */
+    out[k] = src[k];
+  }
+
+  /* agent.default / agent.overrides */
+  out.agent = out.agent && typeof out.agent === "object" ? out.agent : {};
+  if (!out.agent.default || typeof out.agent.default !== "object") {
+    out.agent.default = { provider: null };
+  }
+  if (!out.agent.overrides || typeof out.agent.overrides !== "object") {
+    out.agent.overrides = {};
+  }
+  /* Lift stack.agent.provider into agent.default.provider if unset.
+   * We intentionally leave the original value in place so v1 readers
+   * keep working; v2 readers prefer agent.default.provider anyway. */
+  const liftedProvider = src.stack?.agent?.provider ?? null;
+  if (liftedProvider && !out.agent.default.provider) {
+    out.agent.default.provider = liftedProvider;
+  }
+
+  if (!out.process || typeof out.process !== "object" || Array.isArray(out.process)) {
+    out.process = cloneDefault(DEFAULT_PROCESS_CONFIG());
+  }
+
+  /* lanes: translate from the legacy list-of-strings shape. */
+  out.lanes = {};
+  const srcLanes = src.lanes;
+  if (Array.isArray(srcLanes)) {
+    for (const laneId of srcLanes) {
+      if (typeof laneId !== "string") {
+        warnings.push(`lanes: skipped non-string entry ${JSON.stringify(laneId)}`);
+        continue;
+      }
+      const normalised = laneId.trim();
+      if (!normalised) continue;
+      const def = V1_LANE_DEFAULTS[normalised];
+      if (def) {
+        out.lanes[normalised] = cloneDefault(def);
+      } else {
+        /* Unknown v1 lane — emit a stub so the customer sees exactly
+         * which fields need attention on the next `shipctl doctor`. */
+        out.lanes[normalised] = {
+          kind: "schedule",
+          pattern: `TODO-pattern-for-${normalised}`,
+          cron: "TODO",
+        };
+        stubLanes.push(normalised);
+        warnings.push(
+          `lanes.${normalised}: no preset mapping; wrote a stub (fill in kind/pattern/cron before shipping)`,
+        );
+      }
+    }
+  } else if (srcLanes && typeof srcLanes === "object") {
+    /* Already a map (e.g. someone hand-edited partway). Copy as-is;
+     * the v2 validator will flag any malformed lanes on the next
+     * `shipctl doctor` or write. */
+    out.lanes = JSON.parse(JSON.stringify(srcLanes));
+  } else if (srcLanes !== undefined) {
+    warnings.push(
+      `lanes: unexpected v1 shape ${typeof srcLanes}; dropped. Add lanes manually or rerun 'shipctl init'.`,
+    );
+  }
+
+  return {
+    migrated: true,
+    config: out,
+    warnings,
+    stub_lanes: stubLanes,
+  };
+}
+
+function cloneDefault(laneBody) {
+  return JSON.parse(JSON.stringify(laneBody));
+}
+
+/**
+ * Parse a semver-ish "X.Y.Z" and return the higher of the current floor
+ * and the minimum the caller wants. If `current` is not a string or
+ * doesn't parse, we fall back to the minimum unconditionally — an
+ * unreadable floor is no floor.
+ *
+ * @param {unknown} current
+ * @param {string} minimum
+ * @returns {string}
+ */
+function bumpFloor(current, minimum) {
+  if (typeof current !== "string") return minimum;
+  const cur = parseSemver(current);
+  const min = parseSemver(minimum);
+  if (!cur || !min) return minimum;
+  return compareSemver(cur, min) >= 0 ? current : minimum;
+}
+
+function parseSemver(s) {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(String(s).trim());
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+function compareSemver(a, b) {
+  for (let i = 0; i < 3; i += 1) {
+    if (a[i] !== b[i]) return a[i] - b[i];
+  }
+  return 0;
+}