@elmundi/ship-cli 0.14.1 → 0.15.3

package/lib/config/migrate.mjs

@@ -1,223 +0,0 @@
-/**
- * `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;
-}

package/lib/find-ship-root.mjs

@@ -1,75 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-
-const MARKER_DIRS = [
-  "artifacts/patterns",
-  "artifacts/tools",
-  "artifacts/collections",
-];
-
-function markersOk(dir) {
-  return MARKER_DIRS.every((rel) => {
-    const abs = path.join(dir, rel);
-    try {
-      return fs.statSync(abs).isDirectory();
-    } catch {
-      return false;
-    }
-  });
-}
-
-/**
- * Walk parents from cwd for a directory containing the v2 artifacts/ tree.
- * @returns {string | null}
- */
-export function tryFindShipRepoRootFromWalk() {
-  let dir = path.resolve(process.cwd());
-  for (;;) {
-    if (markersOk(dir)) return dir;
-    const parent = path.dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return null;
-}
-
-/**
- * Root of the Ship monorepo (artifacts/<plural>/<id>/ARTIFACT.md present).
- * Set `SHIP_REPO` to an absolute path when not running from inside the tree.
- */
-export function findShipRepoRoot() {
-  const env = process.env.SHIP_REPO?.trim();
-  if (env) {
-    const r = path.resolve(env);
-    if (!markersOk(r)) {
-      throw new Error(
-        `SHIP_REPO=${r} is not the Ship monorepo (expected artifacts/{patterns,tools,collections}/ at repo root).`,
-      );
-    }
-    return r;
-  }
-  const walked = tryFindShipRepoRootFromWalk();
-  if (walked) return walked;
-  throw new Error(
-    "Ship repo root not found: run from inside the ship clone, or set SHIP_REPO to the repository root.",
-  );
-}
-
-/**
- * When `SHIP_REPO` is unset, returns repo root only if cwd is inside the tree; otherwise `null` (use hosted catalog).
- * When `SHIP_REPO` is set, validates and returns that path or throws.
- * @returns {string | null}
- */
-export function resolveShipRepoRootForCatalog() {
-  const env = process.env.SHIP_REPO?.trim();
-  if (env) {
-    const r = path.resolve(env);
-    if (!markersOk(r)) {
-      throw new Error(
-        `SHIP_REPO=${r} is not the Ship monorepo (expected artifacts/{patterns,tools,collections}/ at repo root).`,
-      );
-    }
-    return r;
-  }
-  return tryFindShipRepoRootFromWalk();
-}

package/lib/process/specialist-prompt-contract.mjs

@@ -1,171 +0,0 @@
-export const SPECIALIST_PROMPT_GUARDRAILS = `# Ship specialist execution guardrails
-
-These rules apply to specialist prompts assembled from process configuration,
-ticket context, workspace policies, and knowledge buckets.
-
-## Knowledge First
-
-Before inventing a solution or procedure, search Ship knowledge for relevant
-recipes, patterns, policies, and technical context. Use repository-specific
-knowledge first when a repo is known, then workspace knowledge. If no relevant
-article is found, say that explicitly before proposing a new approach.
-
-Knowledge articles can also answer clarifying technical questions when the
-ticket lacks implementation detail.
-
-## Allowed Exits
-
-A specialist cycle may end only through a Ship-controlled outcome:
-
-- Ask for clarification: return a clarification intent for Ship to post as a
-  tracker comment and mirror into Inbox.
-- Handoff: request one of the transitions explicitly configured in the process
-  FSM. Ship validates the transition before any side effect.
-- Complete with result: produce the final result or PR reference for Ship to
-  record. Repository changes must be delivered through pull requests only.
-
-## Boundaries
-
-Do not perform direct ticket-system mutations. Do not execute transitions that
-are not declared in the process configuration. Do not push directly to protected
-branches or bypass review. All material actions must be represented in Ship
-audit data. Workspace policies are mandatory and override recipe guidance.`;
-
-export function renderSpecialistPromptGuardrails() {
-  return `${SPECIALIST_PROMPT_GUARDRAILS.trim()}\n`;
-}
-
-export function buildSpecialistPromptBundle({
-  process,
-  state,
-  allowedTransitions = [],
-  ticket = null,
-  policies = null,
-}) {
-  const specialist = normalizeSpecialist(state.specialist);
-  const agentProfile =
-    state.agent_profile || specialist.agent_profile || "auto";
-  return {
-    process: {
-      id: process.id,
-      name: process.name || process.id,
-      primary: process.primary === true,
-    },
-    state: {
-      id: state.id,
-      name: state.name || state.id,
-      instructions: typeof state.instructions === "string" ? state.instructions : "",
-      triggers: Array.isArray(state.triggers) ? state.triggers : [],
-      exit_conditions: Array.isArray(state.exit_conditions) ? state.exit_conditions : [],
-      block_conditions: Array.isArray(state.block_conditions) ? state.block_conditions : [],
-    },
-    specialist,
-    agent_profile: agentProfile,
-    ticket,
-    policies,
-    allowed_transitions: allowedTransitions.map((transition) => ({
-      from: transition.from,
-      to: transition.to,
-      condition: transition.condition || null,
-    })),
-    guardrails: renderSpecialistPromptGuardrails(),
-  };
-}
-
-export function renderSpecialistPromptBundleMarkdown(bundle) {
-  const lines = [
-    "# Ship Specialist Prompt Bundle",
-    "",
-    "## Process",
-    "",
-    `- Process: ${bundle.process.name} (\`${bundle.process.id}\`)`,
-    `- Primary: ${bundle.process.primary ? "yes" : "no"}`,
-    `- State: ${bundle.state.name} (\`${bundle.state.id}\`)`,
-    "",
-    "## Specialist",
-    "",
-    `- Specialist: ${bundle.specialist.name} (\`${bundle.specialist.id}\`)`,
-    `- Agent profile: \`${bundle.agent_profile}\``,
-    "",
-    bundle.specialist.role || "No specialist role description configured.",
-    "",
-  ];
-
-  if (bundle.state.instructions) {
-    lines.push("## State Instructions", "", bundle.state.instructions, "");
-  }
-
-  lines.push("## Ticket Context", "");
-  if (bundle.ticket) {
-    lines.push(...renderTicketLines(bundle.ticket), "");
-  } else {
-    lines.push("No ticket context was supplied. Use the Ship tracker picker before starting this specialist cycle.", "");
-  }
-
-  lines.push("## Workspace Policies", "");
-  if (bundle.policies && bundle.policies.trim()) {
-    lines.push(bundle.policies.trim(), "");
-  } else {
-    lines.push("Workspace policies were not supplied locally. In managed runs, Ship must inject enabled workspace policies before the agent starts.", "");
-  }
-
-  lines.push("## Allowed Transitions", "");
-  if (bundle.allowed_transitions.length) {
-    for (const transition of bundle.allowed_transitions) {
-      const condition = transition.condition ? ` when ${transition.condition}` : "";
-      lines.push(`- \`${transition.from}\` -> \`${transition.to}\`${condition}`);
-    }
-  } else {
-    lines.push("- No outgoing transitions are configured for this state. The agent may only ask for clarification or complete with a result.");
-  }
-
-  lines.push(
-    "",
-    "## Required Guardrails",
-    "",
-    bundle.guardrails.trim(),
-    "",
-  );
-  return `${lines.join("\n").trim()}\n`;
-}
-
-function normalizeSpecialist(value) {
-  if (typeof value === "string") {
-    return { id: value, name: value, role: "", agent_profile: null };
-  }
-  if (value && typeof value === "object" && !Array.isArray(value)) {
-    return {
-      id: String(value.id || value.name || "specialist"),
-      name: String(value.name || value.id || "Specialist"),
-      role: typeof value.role === "string" ? value.role : "",
-      agent_profile: typeof value.agent_profile === "string" ? value.agent_profile : null,
-    };
-  }
-  return { id: "specialist", name: "Specialist", role: "", agent_profile: null };
-}
-
-function renderTicketLines(ticket) {
-  const lines = [];
-  for (const key of ["id", "key", "title", "url", "status", "description"]) {
-    const value = ticket[key];
-    if (typeof value === "string" && value.trim()) {
-      lines.push(`- ${titleCase(key)}: ${value.trim()}`);
-    }
-  }
-  const extra = Object.entries(ticket).filter(
-    ([key, value]) =>
-      !["id", "key", "title", "url", "status", "description"].includes(key) &&
-      value != null &&
-      typeof value !== "object",
-  );
-  for (const [key, value] of extra) {
-    lines.push(`- ${titleCase(key)}: ${String(value)}`);
-  }
-  return lines.length ? lines : ["- Ticket context object was empty."];
-}
-
-function titleCase(value) {
-  return value
-    .replace(/[_-]+/g, " ")
-    .replace(/\b\w/g, (char) => char.toUpperCase());
-}

package/lib/state/lockfile.mjs

@@ -1,180 +0,0 @@
-/**
- * `shipctl.lock.json` — reproducible-build anchor for Ship lanes (RFC-0007
- * Phase 4). Records the exact `(kind, id, version, content_sha256)` of
- * every artifact a lane depends on, plus where that body is materialised on
- * disk. Without it, `shipctl run --offline` has no way to decide whether
- * a cached pattern is "the one the lane expects" — the lockfile gives a
- * positive, auditable answer.
- *
- * Only patterns are locked today (lanes only reference patterns via
- * `lane.pattern`). The schema is forward-compatible: tools and collections
- * can be added to the same `artifacts` map with no version bump.
- *
- * Concurrency: the writer does an atomic rename (write to `.tmp` in the
- * same directory, rename over the target). Readers always open a read-only
- * handle so a race doesn't yield a truncated parse.
- */
-
-import fs from "node:fs";
-import path from "node:path";
-
-import { artifactSha256 } from "../cache/store.mjs";
-
-const LOCKFILE_REL = path.join(".ship", "shipctl.lock.json");
-export const LOCKFILE_SCHEMA_VERSION = 1;
-
-export function lockfilePath(shipRoot) {
-  return path.join(shipRoot, LOCKFILE_REL);
-}
-
-/**
- * @typedef {Object} LockfileEntry
- * @property {string} version             Resolved version of the artifact.
- * @property {string} content_sha256      Hex digest (RFC-0005 normalisation).
- * @property {string} cached_path         Relative path inside the ship root.
- * @property {"http" | "monorepo" | "inline"} source
- * @property {boolean} pinned             Whether a config pin constrained this.
- * @property {string} [channel]           Manifest channel at time of lock.
- *
- * @typedef {Object} Lockfile
- * @property {1} version
- * @property {string} generated_at        ISO-8601 UTC.
- * @property {string} shipctl_version
- * @property {{ base_url: string, channel: string } | null} source
- * @property {Record<string, LockfileEntry>} artifacts  Key: "<kind>/<id>".
- * @property {string[]} [notes]           Free-form operator hints.
- */
-
-/**
- * @param {string} shipRoot
- * @returns {Lockfile | null}
- */
-export function readLockfile(shipRoot) {
-  const file = lockfilePath(shipRoot);
-  if (!fs.existsSync(file)) return null;
-  const raw = fs.readFileSync(file, "utf8");
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch (err) {
-    throw new Error(`shipctl.lock.json: invalid JSON (${err instanceof Error ? err.message : err})`);
-  }
-  if (!parsed || typeof parsed !== "object") {
-    throw new Error("shipctl.lock.json: root must be an object");
-  }
-  if (parsed.version !== LOCKFILE_SCHEMA_VERSION) {
-    throw new Error(
-      `shipctl.lock.json: unsupported version ${parsed.version} (shipctl supports v${LOCKFILE_SCHEMA_VERSION}).`,
-    );
-  }
-  if (!parsed.artifacts || typeof parsed.artifacts !== "object") {
-    throw new Error("shipctl.lock.json: missing `artifacts` map");
-  }
-  return parsed;
-}
-
-/**
- * @param {string} shipRoot
- * @param {Lockfile} data
- */
-export function writeLockfile(shipRoot, data) {
-  const file = lockfilePath(shipRoot);
-  fs.mkdirSync(path.dirname(file), { recursive: true });
-
-  /* Sort the artifacts map so diffs stay minimal between runs. We can't
-   * rely on JSON object key order, but `JSON.stringify` honours insertion
-   * order on v8, and every modern engine we care about follows suit. */
-  const sorted = {};
-  const keys = Object.keys(data.artifacts || {}).sort();
-  for (const k of keys) sorted[k] = data.artifacts[k];
-
-  const normalised = {
-    version: LOCKFILE_SCHEMA_VERSION,
-    generated_at: data.generated_at,
-    shipctl_version: data.shipctl_version,
-    source: data.source || null,
-    artifacts: sorted,
-    notes: Array.isArray(data.notes) ? [...data.notes] : [],
-  };
-
-  const tmp = `${file}.tmp`;
-  fs.writeFileSync(tmp, `${JSON.stringify(normalised, null, 2)}\n`, "utf8");
-  fs.renameSync(tmp, file);
-}
-
-/**
- * Build the lookup key the rest of shipctl uses.
- * @param {string} kind
- * @param {string} id
- */
-export function lockKey(kind, id) {
-  return `${kind}/${id}`;
-}
-
-/**
- * @param {Lockfile} lock
- * @param {string} kind
- * @param {string} id
- * @returns {LockfileEntry | null}
- */
-export function lookupLock(lock, kind, id) {
-  if (!lock) return null;
-  const key = lockKey(kind, id);
-  const entry = lock.artifacts?.[key];
-  return entry || null;
-}
-
-/**
- * Compute the lockfile entry for a freshly-materialised artifact body.
- * Keeping the signature narrow — just `body` and a bit of provenance —
- * means the caller can't accidentally smuggle transient fields into the
- * lock.
- *
- * @param {Object} params
- * @param {string} params.body           Artifact text (markdown + frontmatter).
- * @param {string} params.version        Resolved version string.
- * @param {string} params.cachedPath     Path relative to the ship root.
- * @param {"http" | "monorepo" | "inline"} params.source
- * @param {boolean} [params.pinned=false]
- * @param {string} [params.channel]
- * @returns {LockfileEntry}
- */
-export function entryFromBody({
-  body,
-  version,
-  cachedPath,
-  source,
-  pinned = false,
-  channel,
-}) {
-  return {
-    version,
-    content_sha256: artifactSha256(body),
-    cached_path: String(cachedPath).replace(/\\/g, "/"),
-    source,
-    pinned: Boolean(pinned),
-    ...(channel ? { channel: String(channel) } : {}),
-  };
-}
-
-/**
- * Decide whether a body matches a lockfile entry. Returns a structured
- * `{ ok, reason }` so callers can emit specific diagnostics.
- *
- * @param {LockfileEntry | null} entry
- * @param {string} body
- * @returns {{ ok: boolean, reason?: string, expected?: string, actual?: string }}
- */
-export function verifyBody(entry, body) {
-  if (!entry) return { ok: false, reason: "missing-entry" };
-  const actual = artifactSha256(body);
-  if (actual !== entry.content_sha256) {
-    return {
-      ok: false,
-      reason: "sha-mismatch",
-      expected: entry.content_sha256,
-      actual,
-    };
-  }
-  return { ok: true };
-}