@elmundi/ship-cli 0.11.2 → 0.12.0

package/lib/commands/callback.mjs

@@ -25,8 +25,35 @@
  * (which defaults to the public methodology host); run callbacks hit the
  * orchestration API (`api.ship.elmundi.com`), a different origin, so we
  * take the URL directly from the run context Ship injected.
+ *
+ * RFC-0010 Phase 3 (P3-03) extended this command to emit the new
+ * `RunSummary` contract on top of the existing `status`/`summary`/
+ * `metrics` body. Two equivalent code paths feed the same outcome:
+ *
+ *   - Per-field flags: `--outcome-text`, `--severity SEV=N`,
+ *     `--artifact TYPE:TITLE[:REF]`, `--requires-approval`,
+ *     `--approval-payload @file.json`, `--escalation TYPE:REASON`,
+ *     `--findings-count N`. Composes well with bash heredoc / per-step
+ *     authoring inside a workflow.
+ *   - Bulk env input: `SHIP_RUN_OUTCOME` (inline JSON object) or
+ *     `SHIP_RUN_OUTCOME_FILE` (path to JSON file). Suits agents that
+ *     emit a full RunSummary blob on stdout.
+ *
+ * If both env and flags are present we MERGE — flags win on collision
+ * (per-field shallow override at the top, per-key inside
+ * `findings_by_severity`). Backwards compat is guaranteed: when none of
+ * the new inputs are present, the request body is byte-identical to the
+ * pre-P3 contract (no `outcome` key emitted).
+ *
+ * Outcome shape validation (severity vocabulary, escalation type enum
+ * beyond what we accept on the CLI surface, etc.) is the BACKEND's job
+ * (see RFC-0010 §RunSummary + the P3-01 Pydantic model). `shipctl` only
+ * enforces well-formedness at the wire boundary: object-not-array,
+ * field types, file readability, JSON parseability.
  */
 
+import { readFileSync } from "node:fs";
+
 /** @typedef {"succeeded"|"failed"|"cancelled"} TerminalStatus */
 
 const STATUS_ALIASES = {
@@ -44,6 +71,22 @@ const STATUS_ALIASES = {
   cancel: "cancelled",
 };
 
+/* RFC-0010 §RunSummary — the five inbox/escalation types Ship knows
+ * how to route. We reject anything else at the CLI boundary so the
+ * misspelled `--escalation aproval:...` fails fast with a usage hint
+ * instead of being silently dropped by the backend's enum validator. */
+const VALID_ESCALATION_TYPES = new Set([
+  "clarification",
+  "improvement",
+  "failure",
+  "approval",
+  "exception",
+]);
+
+const VALID_SEVERITIES = new Set(["low", "medium", "high", "critical"]);
+
+const OUTCOME_TEXT_MAX = 500;
+
 const EXIT_USAGE = 2;
 const EXIT_AUTH = 10;
 const EXIT_CONFIG = 11;
@@ -55,36 +98,81 @@ function die(code, msg) {
 }
 
 function printCallbackHelp() {
-  console.log(`shipctl callback — report a pipeline run's terminal status to Ship.
+  console.log(`shipctl callback — what a Play's pattern calls when its work is done so Ship can render an outcome-first row in the Run list and route any escalations into the Inbox.
 
 USAGE
   shipctl callback --status <ok|fail|cancelled> [--summary "..."] [--metric k=v]...
+                   [--outcome-text "..."] [--severity SEV=N]... [--artifact TYPE:TITLE[:REF]]...
+                   [--requires-approval] [--approval-payload <@file|JSON>]
+                   [--escalation TYPE:REASON]... [--findings-count N]
 
-FLAGS
+Identity
+  --run-id       Pipeline run UUID (usually set by SHIP_RUN_ID env).
+  --callback-url Full callback URL (usually set by SHIP_CALLBACK_URL env).
+  --base-url     Orchestration API base (default: SHIP_API_BASE env). Combined
+                 with --run-id to construct the URL when --callback-url absent.
+  Env:
+    SHIP_RUN_TOKEN     (required) Short-lived bearer Ship issued for this run.
+    SHIP_CALLBACK_URL  (preferred) Full URL of the result endpoint.
+    SHIP_RUN_ID        Fallback input for --run-id.
+    SHIP_API_BASE      Fallback input for --base-url.
+
+Status & summary
   --status       Terminal status. Aliases: ok|success|succeeded, fail|failed,
                  cancelled|canceled. Required.
   --summary      One-line human summary (≤1024 chars). Optional.
   --metric k=v   Structured metric to attach. Repeatable. Values coerced:
                  numbers, booleans (true|false), JSON (prefix { or [), else string.
                  Example: --metric tickets_processed=3 --metric dry_run=true
-  --run-id       Pipeline run UUID (usually set by SHIP_RUN_ID env).
-  --callback-url Full callback URL (usually set by SHIP_CALLBACK_URL env).
-  --base-url     Orchestration API base (default: SHIP_API_BASE env). Combined
-                 with --run-id to construct the URL when --callback-url absent.
   --json         Print the Ship response JSON on success.
-  --help         Show this help.
+  --help, -h     Show this help.
 
-ENV
-  SHIP_RUN_TOKEN     (required) Short-lived bearer Ship issued for this run.
-  SHIP_CALLBACK_URL  (preferred) Full URL of the result endpoint.
-  SHIP_RUN_ID        Fallback input for --run-id.
-  SHIP_API_BASE      Fallback input for --base-url.
+RunSummary outcome (RFC-0010 §RunSummary — emitted as the request body's "outcome" object)
+  --outcome-text "..."     Pattern-authored single-line UI sentence (≤${OUTCOME_TEXT_MAX} chars,
+                           leading/trailing whitespace trimmed). This is what operators
+                           see in /runs — keep it concrete, no "completed successfully"
+                           filler. Example:
+                             "3 issues found · 1 PR opened"
+  --findings-count N       Non-negative integer total. If omitted but --severity
+                           flags are present, derived from their sum.
+  --severity SEV=N         Aggregated into outcome.findings_by_severity. SEV is one of
+                           low|medium|high|critical. N is non-negative int. Repeatable;
+                           order doesn't matter; last write wins per severity.
+  --artifact TYPE:TITLE[:REF]
+                           Repeatable. Parsed to {type, title, ref?}. Use \\: to embed
+                           a literal colon inside TITLE. REF (URL or external id) is
+                           optional. Example:
+                             --artifact pr:"Fix null check":https://github.com/o/r/pull/42
+  --requires-approval      Flag (no value). Sets outcome.requires_approval=true.
+  --approval-payload PAYLOAD
+                           JSON object to attach as outcome.approval_payload. Either
+                           inline JSON or "@path/to/file.json" to load from disk.
+                           Must parse to an object (not array/scalar).
+  --escalation TYPE:REASON Repeatable. Aggregated into outcome.escalations[]. Each
+                           escalation lands in the Inbox with that type. TYPE must
+                           be one of:
+                             clarification | improvement | failure | approval | exception
+  Env (alternative to per-field flags):
+    SHIP_RUN_OUTCOME       Inline JSON object — used as the base outcome (CLI flags
+                           merge on top, flag values win on per-field collision).
+    SHIP_RUN_OUTCOME_FILE  Path to a JSON file with the same semantics. Useful when
+                           an agent emits a full RunSummary blob to stdout.
 
-EXAMPLE (inside a workflow.yml ‹if: always()› step)
+EXAMPLES
+  # Terminal status only (legacy contract):
+  shipctl callback --status ok --summary "3 PRs scanned"
+
+  # Canonical pattern-authored outcome (mirrors flow-pr-self-review's "## Reporting"):
   shipctl callback --status ok \\
-    --summary "Intake processed TICKET-42" \\
-    --metric tickets_processed=1 \\
-    --metric ticket_ids=LIN-42
+    --outcome-text "Reviewed PR · 3 suggestions · 1 fix applied" \\
+    --findings-count 3 \\
+    --severity high=1 --severity medium=2 \\
+    --artifact comment:"PR self-review summary":"https://github.com/o/r/pull/42#issuecomment-1" \\
+    --artifact pr:"Auto-fix: null guard":"https://github.com/o/r/pull/42/commits/abc" \\
+    --escalation clarification:"Need owner sign-off on test rewrite"
+
+  # Bulk input from agent stdout:
+  SHIP_RUN_OUTCOME_FILE=./summary.json shipctl callback --status ok
 `);
 }
 
@@ -127,6 +215,190 @@ function parseMetricArg(tok) {
   return { key, value: coerceMetricValue(value) };
 }
 
+/* --severity SEV=N. Mirrors --metric's k=v shape but with a fixed
+ * vocabulary and integer values. We validate at the CLI surface so the
+ * `--severity hi=1` typo dies before we waste an HTTP round-trip. */
+export function parseSeverityArg(tok) {
+  const eq = tok.indexOf("=");
+  if (eq <= 0) {
+    die(EXIT_USAGE, `--severity expects SEV=N; got: ${tok}`);
+  }
+  const key = tok.slice(0, eq).trim().toLowerCase();
+  const raw = tok.slice(eq + 1).trim();
+  if (!VALID_SEVERITIES.has(key)) {
+    die(
+      EXIT_USAGE,
+      `--severity SEV must be one of low|medium|high|critical; got: ${key}`,
+    );
+  }
+  if (!/^\d+$/.test(raw)) {
+    die(
+      EXIT_USAGE,
+      `--severity ${key}=N expects a non-negative integer; got: ${raw}`,
+    );
+  }
+  const n = Number(raw);
+  if (!Number.isSafeInteger(n) || n < 0) {
+    die(
+      EXIT_USAGE,
+      `--severity ${key}=N expects a non-negative integer; got: ${raw}`,
+    );
+  }
+  return { key, value: n };
+}
+
+/* --artifact TYPE:TITLE[:REF]. The annoying parser-y bit: TITLE may
+ * embed colons via `\:`, REF is taken verbatim after the second
+ * unescaped colon (so URLs like https://… survive the round-trip
+ * without further escaping — only the post-TYPE post-TITLE colons
+ * matter as separators). */
+export function parseArtifactArg(tok) {
+  const findUnescapedColon = (s, start = 0) => {
+    for (let i = start; i < s.length; i++) {
+      if (s[i] === ":" && s[i - 1] !== "\\") return i;
+    }
+    return -1;
+  };
+  const firstColon = findUnescapedColon(tok);
+  if (firstColon <= 0) {
+    die(EXIT_USAGE, `--artifact expects TYPE:TITLE[:REF]; got: ${tok}`);
+  }
+  const type = tok.slice(0, firstColon).trim();
+  const rest = tok.slice(firstColon + 1);
+  const secondColon = findUnescapedColon(rest);
+  let titleRaw;
+  let ref = null;
+  if (secondColon < 0) {
+    titleRaw = rest;
+  } else {
+    titleRaw = rest.slice(0, secondColon);
+    ref = rest.slice(secondColon + 1);
+  }
+  /* Resolve the only escape we recognise. Other backslash sequences
+   * pass through untouched — kept deliberately narrow so we don't grow
+   * a DSL. */
+  const title = titleRaw.replace(/\\:/g, ":").trim();
+  if (!type) die(EXIT_USAGE, `--artifact TYPE cannot be empty: ${tok}`);
+  if (!title) die(EXIT_USAGE, `--artifact TITLE cannot be empty: ${tok}`);
+  /** @type {{type: string, title: string, ref?: string}} */
+  const out = { type, title };
+  if (ref !== null && ref !== "") out.ref = ref;
+  return out;
+}
+
+/* --escalation TYPE:REASON. REASON is everything after the first
+ * colon (so it can contain colons / URLs / punctuation freely). */
+export function parseEscalationArg(tok) {
+  const firstColon = tok.indexOf(":");
+  if (firstColon <= 0) {
+    die(EXIT_USAGE, `--escalation expects TYPE:REASON; got: ${tok}`);
+  }
+  const type = tok.slice(0, firstColon).trim().toLowerCase();
+  const reason = tok.slice(firstColon + 1).trim();
+  if (!VALID_ESCALATION_TYPES.has(type)) {
+    die(
+      EXIT_USAGE,
+      `--escalation TYPE must be one of ${[...VALID_ESCALATION_TYPES].join("|")}; got: ${type}`,
+    );
+  }
+  if (!reason) die(EXIT_USAGE, `--escalation REASON cannot be empty: ${tok}`);
+  return { type, reason };
+}
+
+/* --approval-payload @path | inline JSON. Distinguishes by the leading
+ * `@` because that's what bash/curl users already expect for
+ * load-from-file semantics. We always require an object (not a top-level
+ * array or scalar) so the backend's `Record<string, unknown>` slot lands
+ * something usable. */
+export function parseApprovalPayload(raw) {
+  let source = raw;
+  let origin = "inline JSON";
+  if (typeof raw === "string" && raw.startsWith("@")) {
+    const path = raw.slice(1);
+    if (!path) die(EXIT_USAGE, "--approval-payload @ requires a file path");
+    try {
+      source = readFileSync(path, "utf8");
+    } catch (err) {
+      die(
+        EXIT_CONFIG,
+        `--approval-payload could not read ${path}: ${err instanceof Error ? err.message : err}`,
+      );
+    }
+    origin = `file ${path}`;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(source);
+  } catch (err) {
+    die(
+      EXIT_CONFIG,
+      `--approval-payload (${origin}) is not valid JSON: ${err instanceof Error ? err.message : err}`,
+    );
+    return null;
+  }
+  if (
+    parsed === null ||
+    typeof parsed !== "object" ||
+    Array.isArray(parsed)
+  ) {
+    die(
+      EXIT_CONFIG,
+      `--approval-payload must be a JSON object (got ${Array.isArray(parsed) ? "array" : typeof parsed}).`,
+    );
+  }
+  return parsed;
+}
+
+/* SHIP_RUN_OUTCOME / SHIP_RUN_OUTCOME_FILE → object. Returns null when
+ * neither env is set. We do *not* validate the inner shape (severities,
+ * escalation types, etc.) here — that's the backend's responsibility
+ * per RFC-0010. We only enforce well-formedness so a typo in JSON
+ * surfaces as an EXIT_CONFIG with a useful message rather than a 422
+ * round-trip with the bearer already burned. */
+export function loadEnvOutcome(env = process.env) {
+  const inline = env.SHIP_RUN_OUTCOME;
+  const file = env.SHIP_RUN_OUTCOME_FILE;
+  if (!inline && !file) return null;
+  let source;
+  let origin;
+  if (file) {
+    try {
+      source = readFileSync(file, "utf8");
+    } catch (err) {
+      die(
+        EXIT_CONFIG,
+        `SHIP_RUN_OUTCOME_FILE could not read ${file}: ${err instanceof Error ? err.message : err}`,
+      );
+      return null;
+    }
+    origin = `SHIP_RUN_OUTCOME_FILE=${file}`;
+  } else {
+    source = inline;
+    origin = "SHIP_RUN_OUTCOME";
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(source);
+  } catch (err) {
+    die(
+      EXIT_CONFIG,
+      `${origin} is not valid JSON: ${err instanceof Error ? err.message : err}`,
+    );
+    return null;
+  }
+  if (
+    parsed === null ||
+    typeof parsed !== "object" ||
+    Array.isArray(parsed)
+  ) {
+    die(
+      EXIT_CONFIG,
+      `${origin} must be a JSON object (got ${Array.isArray(parsed) ? "array" : typeof parsed}).`,
+    );
+  }
+  return parsed;
+}
+
 export function parseCallbackArgs(rest) {
   const out = {
     status: null,
@@ -137,8 +409,25 @@ export function parseCallbackArgs(rest) {
     baseUrl: null,
     json: false,
     help: false,
+    /* Outcome accumulator. We track presence of *any* outcome flag with
+     * `outcomeFlagsSeen` so backwards-compat (no outcome key) is a
+     * deterministic check rather than a "did everything end up empty"
+     * heuristic. */
+    outcome: {
+      outcome_text: null,
+      findings_count: null,
+      findings_by_severity: {},
+      artifacts: [],
+      requires_approval: false,
+      approval_payload: null,
+      escalations: [],
+    },
+    outcomeFlagsSeen: false,
   };
   const copy = [...rest];
+  const markOutcome = () => {
+    out.outcomeFlagsSeen = true;
+  };
   /* Tiny arg-munger kept inline rather than pulling a dependency —
    * matches the style of feedback.mjs / patterns.mjs and keeps this CLI
    * zero-prod-deps apart from `yaml`. */
@@ -156,6 +445,24 @@ export function parseCallbackArgs(rest) {
     }
     return false;
   };
+  /* Same as strFlag but routes the captured value into a callback so
+   * we can validate / mutate (outcome flags don't live as plain keys
+   * on `out`). */
+  const handleArgFlag = (name, take) => {
+    if (copy[0] === name && copy[1] !== undefined) {
+      copy.shift();
+      take(String(copy.shift()));
+      return true;
+    }
+    const p = `${name}=`;
+    if (copy[0] && copy[0].startsWith(p)) {
+      const raw = copy[0].slice(p.length);
+      copy.shift();
+      take(raw);
+      return true;
+    }
+    return false;
+  };
   while (copy.length) {
     const a = copy[0];
     if (a === "--help" || a === "-h") {
@@ -186,6 +493,69 @@ export function parseCallbackArgs(rest) {
       out.metrics[key] = value;
       continue;
     }
+    if (
+      handleArgFlag("--outcome-text", (raw) => {
+        markOutcome();
+        const trimmed = String(raw).trim();
+        if (trimmed.length > OUTCOME_TEXT_MAX) {
+          die(
+            EXIT_USAGE,
+            `--outcome-text exceeds ${OUTCOME_TEXT_MAX} chars (got ${trimmed.length}).`,
+          );
+        }
+        out.outcome.outcome_text = trimmed;
+      })
+    )
+      continue;
+    if (
+      handleArgFlag("--findings-count", (raw) => {
+        markOutcome();
+        const r = String(raw).trim();
+        if (!/^\d+$/.test(r)) {
+          die(
+            EXIT_USAGE,
+            `--findings-count expects a non-negative integer; got: ${r}`,
+          );
+        }
+        out.outcome.findings_count = Number(r);
+      })
+    )
+      continue;
+    if (
+      handleArgFlag("--severity", (raw) => {
+        markOutcome();
+        const { key, value } = parseSeverityArg(String(raw));
+        out.outcome.findings_by_severity[key] = value;
+      })
+    )
+      continue;
+    if (
+      handleArgFlag("--artifact", (raw) => {
+        markOutcome();
+        out.outcome.artifacts.push(parseArtifactArg(String(raw)));
+      })
+    )
+      continue;
+    if (a === "--requires-approval") {
+      markOutcome();
+      out.outcome.requires_approval = true;
+      copy.shift();
+      continue;
+    }
+    if (
+      handleArgFlag("--approval-payload", (raw) => {
+        markOutcome();
+        out.outcome.approval_payload = parseApprovalPayload(String(raw));
+      })
+    )
+      continue;
+    if (
+      handleArgFlag("--escalation", (raw) => {
+        markOutcome();
+        out.outcome.escalations.push(parseEscalationArg(String(raw)));
+      })
+    )
+      continue;
     die(EXIT_USAGE, `unknown argument: ${a}\nRun: shipctl callback --help`);
   }
   return out;
@@ -208,11 +578,81 @@ export function resolveCallbackUrl(args, env = process.env) {
   return null;
 }
 
-export function buildCallbackBody(args) {
+/* Compose the final outcome from env (base) + CLI flags (overlay).
+ *
+ * Merge semantics — codified here so the test names stay terse and the
+ * spec deviation (if any) is grep-able:
+ *
+ *   - Top-level keys: shallow override (CLI wins on collision).
+ *   - `findings_by_severity`: per-key merge (env's `low: 1` survives a
+ *     CLI `--severity high=2`; CLI overrides env when severities collide).
+ *   - Arrays (`artifacts`, `escalations`): if CLI contributed any,
+ *     CLI replaces env. Otherwise env's array passes through. We
+ *     intentionally do NOT concat — appending env+CLI would be too
+ *     surprising for an agent that emits a complete blob and then a
+ *     human refines a single field via flag.
+ *   - `findings_count`: when neither env nor flag provides one but
+ *     `findings_by_severity` is present, we derive a sum so the
+ *     pattern doesn't need to compute it by hand.
+ */
+export function buildOutcome(args, env = process.env) {
+  const envOutcome = loadEnvOutcome(env);
+  if (!envOutcome && !args.outcomeFlagsSeen) return null;
+
+  /** @type {Record<string, unknown>} */
+  const merged = envOutcome ? { ...envOutcome } : {};
+
+  const cli = args.outcome;
+
+  if (cli.outcome_text !== null) merged.outcome_text = cli.outcome_text;
+  if (cli.findings_count !== null) merged.findings_count = cli.findings_count;
+
+  const cliSeverities = cli.findings_by_severity;
+  if (Object.keys(cliSeverities).length > 0) {
+    const baseSev =
+      merged.findings_by_severity &&
+      typeof merged.findings_by_severity === "object" &&
+      !Array.isArray(merged.findings_by_severity)
+        ? { ...merged.findings_by_severity }
+        : {};
+    merged.findings_by_severity = { ...baseSev, ...cliSeverities };
+  }
+
+  if (cli.artifacts.length > 0) merged.artifacts = cli.artifacts;
+  if (cli.requires_approval) merged.requires_approval = true;
+  if (cli.approval_payload !== null)
+    merged.approval_payload = cli.approval_payload;
+  if (cli.escalations.length > 0) merged.escalations = cli.escalations;
+
+  /* Derive `findings_count` from severity totals when neither side
+   * specified one explicitly. Catches the common case where the
+   * pattern emits per-severity counts and forgets the rollup. */
+  if (
+    merged.findings_count === undefined &&
+    merged.findings_by_severity &&
+    typeof merged.findings_by_severity === "object"
+  ) {
+    let sum = 0;
+    let any = false;
+    for (const v of Object.values(merged.findings_by_severity)) {
+      if (typeof v === "number" && Number.isFinite(v)) {
+        sum += v;
+        any = true;
+      }
+    }
+    if (any) merged.findings_count = sum;
+  }
+
+  return merged;
+}
+
+export function buildCallbackBody(args, env = process.env) {
   /** @type {Record<string, unknown>} */
   const body = { status: args.status };
   if (args.summary) body.summary = String(args.summary).slice(0, 1024);
   if (Object.keys(args.metrics).length > 0) body.metrics = args.metrics;
+  const outcome = buildOutcome(args, env);
+  if (outcome !== null) body.outcome = outcome;
   return body;
 }
 

package/lib/commands/config.mjs

@@ -100,7 +100,7 @@ function getAtPath(obj, dottedKey) {
 
 /**
  * Split a dotted key, preserving `<kind>/<id>` segments under artifacts.pins.
- * Example: artifacts.pins.pattern/cloud-developer → ["artifacts","pins","pattern/cloud-developer"]
+ * Example: artifacts.pins.pattern/role-developer → ["artifacts","pins","pattern/role-developer"]
  */
 function parsePath(dottedKey) {
   const raw = dottedKey.split(".");

package/lib/commands/docs.mjs

@@ -9,11 +9,11 @@ export async function docsCommand(ctx, args) {
   const [sub, ...rest] = args;
   if (!sub || sub === "help") {
     console.log(`Usage:
-  ship docs fetch <repo-relative-path>
-  ship docs feedback --title "..." --summary "..." [--recommendation "line"]... [--source-context "..."]
+  shipctl docs fetch <repo-relative-path>
+  shipctl docs feedback --title "..." --summary "..." [--recommendation "line"]... [--source-context "..."]
 
-Vector search:  ship search <query>
-Catalog bodies:  ship pattern|tool|collection fetch <id>
+Vector search:  shipctl search <query>
+Catalog bodies: shipctl pattern|tool|collection fetch <id>
 
 Global flags: --base-url URL  --json`);
     return;