@elmundi/ship-cli 0.15.3 → 0.16.0

package/bin/shipctl.mjs

@@ -81,6 +81,18 @@ try {
     process.exit(0);
   }
 
+  if (cmd === "inbox") {
+    const { inboxCommand } = await import("../lib/commands/inbox.mjs");
+    await inboxCommand(ctx, rest);
+    process.exit(0);
+  }
+
+  if (cmd === "project") {
+    const { projectCommand } = await import("../lib/commands/project.mjs");
+    await projectCommand(ctx, rest);
+    process.exit(0);
+  }
+
   if (cmd === "run") {
     const { runCommand } = await import("../lib/commands/run.mjs");
     await runCommand(ctx, rest);

package/lib/agent_api.mjs

@@ -0,0 +1,192 @@
+/**
+ * Shared client helpers for ``shipctl`` commands that hit the
+ * agent-runs API (inbox / project / etc).
+ *
+ * Reuses the same auth model the existing ``shipctl knowledge`` flow
+ * established: bearer ``SHIP_API_TOKEN`` PAT, base URL resolved via
+ * the same precedence chain (flag → ``SHIP_WORKSPACE_API_BASE`` →
+ * ``SHIP_API_BASE`` → prod default), workspace id resolved via flag /
+ * ``SHIP_WORKSPACE_ID`` / sole-workspace lookup.
+ *
+ * Exit codes are uniform across commands so wrapper scripts can
+ * branch on them: 0 ok, 1 arg/config error, 2 auth error (401),
+ * 3 network/5xx.
+ */
+
+const PROD_BASE = "https://api.ship.elmundi.com";
+
+
+/**
+ * @param {string|null|undefined} explicit
+ * @returns {string}
+ */
+export function resolveBaseUrl(explicit) {
+  if (explicit) return explicit.replace(/\/+$/, "");
+  const envWorkspace = process.env.SHIP_WORKSPACE_API_BASE;
+  if (envWorkspace) return envWorkspace.replace(/\/+$/, "");
+  const envGeneric = process.env.SHIP_API_BASE;
+  if (envGeneric) return envGeneric.replace(/\/+$/, "");
+  return PROD_BASE;
+}
+
+
+export function requireToken() {
+  const token = process.env.SHIP_API_TOKEN || "";
+  if (!token) {
+    console.error(
+      "SHIP_API_TOKEN is required. Mint one at /settings in the Ship console.",
+    );
+    process.exit(1);
+  }
+  return token;
+}
+
+
+/**
+ * @param {string} baseUrl
+ * @param {string} token
+ * @returns {Promise<string>}
+ */
+export async function resolveSoleWorkspace(baseUrl, token) {
+  const rows = await apiRequest(baseUrl, "/v1/workspaces", "GET", token, null);
+  if (!Array.isArray(rows) || rows.length === 0) {
+    console.error("No workspaces visible to this token.");
+    process.exit(1);
+  }
+  if (rows.length > 1) {
+    const ids = rows.map((r) => `${r.id} (${r.name ?? "?"})`).join("\n  ");
+    console.error(
+      `Token has access to more than one workspace; pass --workspace <id>.\n  ${ids}`,
+    );
+    process.exit(1);
+  }
+  return String(rows[0].id);
+}
+
+
+/**
+ * @param {{ workspace?: string|null, baseUrl?: string|null }} opts
+ * @param {{ baseUrl?: string|null, baseUrlSource?: string|null }} ctx
+ */
+export async function resolveContext(opts, ctx) {
+  const baseUrl = resolveBaseUrl(
+    opts.baseUrl || (ctx?.baseUrlSource === "flag" ? ctx?.baseUrl : null),
+  );
+  const token = requireToken();
+  let workspaceId =
+    opts.workspace || (process.env.SHIP_WORKSPACE_ID || "").trim() || "";
+  if (!workspaceId) {
+    workspaceId = await resolveSoleWorkspace(baseUrl, token);
+  }
+  return { baseUrl, token, workspaceId };
+}
+
+
+/**
+ * @param {string} baseUrl
+ * @param {string} path
+ * @param {"GET"|"POST"|"DELETE"} method
+ * @param {string} token
+ * @param {Record<string, unknown>|null} body
+ */
+export async function apiRequest(baseUrl, path, method, token, body) {
+  const url = `${baseUrl}${path}`;
+  let res;
+  try {
+    res = await fetch(url, {
+      method,
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        Authorization: `Bearer ${token}`,
+      },
+      body: body === null ? undefined : JSON.stringify(body),
+    });
+  } catch (err) {
+    console.error(
+      `Network error calling ${url}: ${err instanceof Error ? err.message : err}`,
+    );
+    process.exit(3);
+  }
+  const text = await res.text();
+  let data = null;
+  try {
+    data = text ? JSON.parse(text) : null;
+  } catch {
+    data = text;
+  }
+  if (res.ok) return data;
+  if (res.status === 401) {
+    console.error(
+      `HTTP 401 on ${method} ${url} — SHIP_API_TOKEN is missing, expired, or lacks workspace access.`,
+    );
+    process.exit(2);
+  }
+  const msg = typeof data === "string" ? data : JSON.stringify(data);
+  console.error(`HTTP ${res.status} ${res.statusText} on ${method} ${url}\n${msg}`);
+  process.exit(res.status >= 500 ? 3 : 1);
+}
+
+
+/**
+ * Read a value from a flag (`--name`/`--name=value`). Returns true if
+ * consumed; mutates ``copy`` in place.
+ *
+ * @param {string[]} copy
+ * @param {string} flag
+ * @param {Record<string, string|null>} out
+ * @param {string} key
+ */
+export function consumeStringFlag(copy, flag, out, key) {
+  if (copy[0] === flag && copy[1] !== undefined) {
+    copy.shift();
+    out[key] = String(copy.shift());
+    return true;
+  }
+  const p = `${flag}=`;
+  if (copy[0] && copy[0].startsWith(p)) {
+    out[key] = copy[0].slice(p.length);
+    copy.shift();
+    return true;
+  }
+  return false;
+}
+
+
+/**
+ * Read a body / file argument. ``--body <inline>`` takes the next arg
+ * as the literal body; ``--body-file <path>`` reads the file content.
+ * Mutually exclusive — the second wins if both are given but we warn.
+ *
+ * @param {string[]} copy
+ * @param {Record<string, string|null>} out
+ */
+export function consumeBodyFlags(copy, out) {
+  if (consumeStringFlag(copy, "--body", out, "body")) return true;
+  if (consumeStringFlag(copy, "--body-file", out, "bodyFile")) return true;
+  return false;
+}
+
+
+/**
+ * Resolve ``--body`` vs ``--body-file`` into a single string. Reads
+ * stdin when ``--body-file=-`` so callers can pipe markdown.
+ *
+ * @param {{ body?: string|null, bodyFile?: string|null }} out
+ */
+export async function readBodyFromOpts(out) {
+  if (out.body && out.bodyFile) {
+    console.error("Pass --body OR --body-file, not both.");
+    process.exit(1);
+  }
+  if (out.bodyFile) {
+    const fs = await import("node:fs/promises");
+    if (out.bodyFile === "-") {
+      const chunks = [];
+      for await (const chunk of process.stdin) chunks.push(chunk);
+      return Buffer.concat(chunks).toString("utf8");
+    }
+    return await fs.readFile(out.bodyFile, "utf8");
+  }
+  return out.body || "";
+}

package/lib/commands/inbox.mjs

@@ -0,0 +1,171 @@
+/**
+ * `shipctl inbox` — write into the operator's mailbox from a routine.
+ *
+ * Routines like daily-retro / learning-capture / process-reviewer file
+ * a single ``type=report`` letter per run; the operator opens it in the
+ * mailbox preview and hits Acknowledge. SDLC pipelines occasionally
+ * file ``approval`` / ``improvement`` items.
+ *
+ * Usage:
+ *
+ *   shipctl inbox create
+ *     --type <report|improvement|approval|exception>
+ *     --title "Daily retro 2026-05-07"
+ *     --body  "<markdown>" | --body-file path/to/digest.md | --body-file -
+ *     [--summary "<short list-row blurb>"]
+ *     [--workspace <id>]
+ *     [--ticket-ref <id>]
+ *     [--json]
+ *
+ * Auth: bearer ``SHIP_API_TOKEN`` (mint at /settings).
+ *
+ * Exit codes:
+ *   0  inbox item created
+ *   1  arg / config / 4xx error
+ *   2  auth error (401)
+ *   3  network / 5xx error
+ */
+
+import {
+  apiRequest,
+  consumeBodyFlags,
+  consumeStringFlag,
+  readBodyFromOpts,
+  resolveContext,
+} from "../agent_api.mjs";
+
+
+const VALID_TYPES = new Set([
+  "report",
+  "improvement",
+  "approval",
+  "exception",
+]);
+
+
+export async function inboxCommand(ctx, rest) {
+  const [sub, ...args] = rest;
+  if (!sub || sub === "help" || sub === "-h" || sub === "--help") {
+    printInboxHelp();
+    return;
+  }
+  if (sub === "create") {
+    await inboxCreateCommand(ctx, args);
+    return;
+  }
+  console.error(
+    `Unknown 'shipctl inbox' subcommand: ${sub}\nRun: shipctl inbox --help`,
+  );
+  process.exit(1);
+}
+
+
+function printInboxHelp() {
+  console.log(`shipctl inbox — file letters in the operator's mailbox
+
+SUBCOMMANDS
+  shipctl inbox create --type <kind> --title <s> --body <md>
+                       [--summary <s>] [--ticket-ref <id>]
+                       [--body-file <path|->] [--workspace <id>] [--json]
+
+TYPES
+  report        Read-only digest (daily retro, learning capture,
+                process review). Operator hits Acknowledge.
+  improvement   Actionable suggestion. Operator accepts / dismisses.
+  approval      Gated decision. Operator approves / rejects / dismisses.
+  exception     Policy edge case. Operator acknowledges / dismisses.
+
+ENV
+  SHIP_API_TOKEN             Required. Bearer PAT minted at /settings.
+  SHIP_WORKSPACE_ID          Optional. Skips the /v1/workspaces lookup.
+  SHIP_WORKSPACE_API_BASE    Optional override for the control plane.
+
+EXIT
+  0  letter filed
+  1  arg / config / 4xx
+  2  auth (401)
+  3  network / 5xx
+`);
+}
+
+
+async function inboxCreateCommand(ctx, args) {
+  const opts = parseCreateArgs(args);
+  const body = (await readBodyFromOpts(opts)).trim();
+  if (!body) {
+    console.error("Pass --body <markdown> or --body-file <path|->");
+    process.exit(1);
+  }
+  const { baseUrl, token, workspaceId } = await resolveContext(opts, ctx);
+
+  const result = await apiRequest(
+    baseUrl,
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/inbox/items`,
+    "POST",
+    token,
+    {
+      type: opts.type,
+      title: opts.title,
+      body,
+      summary: opts.summary || null,
+      ticket_ref: opts.ticketRef || null,
+    },
+  );
+
+  if (ctx?.json || opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`Letter filed (${opts.type}): ${opts.title}`);
+}
+
+
+function parseCreateArgs(args) {
+  const out = {
+    type: null,
+    title: null,
+    body: null,
+    bodyFile: null,
+    summary: null,
+    ticketRef: null,
+    workspace: null,
+    baseUrl: null,
+    json: false,
+  };
+  const copy = [...args];
+  while (copy.length) {
+    if (
+      consumeStringFlag(copy, "--type", out, "type") ||
+      consumeStringFlag(copy, "--title", out, "title") ||
+      consumeStringFlag(copy, "--summary", out, "summary") ||
+      consumeStringFlag(copy, "--ticket-ref", out, "ticketRef") ||
+      consumeStringFlag(copy, "--workspace", out, "workspace") ||
+      consumeStringFlag(copy, "--base-url", out, "baseUrl") ||
+      consumeBodyFlags(copy, out)
+    ) {
+      continue;
+    }
+    if (copy[0] === "--json") {
+      out.json = true;
+      copy.shift();
+      continue;
+    }
+    if (copy[0] === "--help" || copy[0] === "-h") {
+      printInboxHelp();
+      process.exit(0);
+    }
+    console.error(`Unknown flag: ${copy[0]}`);
+    process.exit(1);
+  }
+  if (!out.type || !VALID_TYPES.has(out.type)) {
+    console.error(
+      `--type must be one of ${[...VALID_TYPES].join(" | ")}`,
+    );
+    process.exit(1);
+  }
+  if (!out.title || !out.title.trim()) {
+    console.error("--title is required");
+    process.exit(1);
+  }
+  return out;
+}

package/lib/commands/project.mjs

@@ -0,0 +1,152 @@
+/**
+ * `shipctl project` — manage tracker projects from a routine.
+ *
+ * Today the only subcommand is ``find-or-create``: the reviewer
+ * routines (tech-reviewer, qa-reviewer, security-officer) call this
+ * once per run to resolve their dedicated holding-pen project ("Tech
+ * Debt", "QA Debt", "Security") on the workspace's bound tracker.
+ * First run creates; every subsequent run short-circuits on the
+ * case-insensitive name match — no list-then-create race.
+ *
+ * Usage:
+ *
+ *   shipctl project find-or-create
+ *     --name "Tech Debt"
+ *     --body "<markdown body for the new project — only used on create>"
+ *     [--description "<one-liner; ≤240 chars; only used on create>"]
+ *     [--workspace <id>]
+ *     [--json]
+ *
+ * Output (default): ``project_id\tname\tcreated`` on a single line so
+ * shell scripts can parse it. ``--json`` returns the full server
+ * response.
+ *
+ * Auth: bearer ``SHIP_API_TOKEN``.
+ *
+ * Exit codes:
+ *   0  project resolved (found or created)
+ *   1  arg / config / 4xx error
+ *   2  auth error (401)
+ *   3  network / 5xx error
+ */
+
+import {
+  apiRequest,
+  consumeBodyFlags,
+  consumeStringFlag,
+  readBodyFromOpts,
+  resolveContext,
+} from "../agent_api.mjs";
+
+
+export async function projectCommand(ctx, rest) {
+  const [sub, ...args] = rest;
+  if (!sub || sub === "help" || sub === "-h" || sub === "--help") {
+    printProjectHelp();
+    return;
+  }
+  if (sub === "find-or-create") {
+    await projectFindOrCreateCommand(ctx, args);
+    return;
+  }
+  console.error(
+    `Unknown 'shipctl project' subcommand: ${sub}\nRun: shipctl project --help`,
+  );
+  process.exit(1);
+}
+
+
+function printProjectHelp() {
+  console.log(`shipctl project — manage tracker projects
+
+SUBCOMMANDS
+  shipctl project find-or-create --name <s> --body <md>
+                                 [--description <s>] [--body-file <path|->]
+                                 [--workspace <id>] [--json]
+
+ENV
+  SHIP_API_TOKEN             Required. Bearer PAT minted at /settings.
+  SHIP_WORKSPACE_ID          Optional. Skips the /v1/workspaces lookup.
+  SHIP_WORKSPACE_API_BASE    Optional override for the control plane.
+
+EXIT
+  0  project resolved
+  1  arg / config / 4xx
+  2  auth (401)
+  3  network / 5xx
+`);
+}
+
+
+async function projectFindOrCreateCommand(ctx, args) {
+  const opts = parseFindOrCreateArgs(args);
+  const body = (await readBodyFromOpts(opts)).trim();
+  if (!body) {
+    console.error("Pass --body <markdown> or --body-file <path|->");
+    process.exit(1);
+  }
+  const { baseUrl, token, workspaceId } = await resolveContext(opts, ctx);
+
+  const result = await apiRequest(
+    baseUrl,
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/projects/find-or-create`,
+    "POST",
+    token,
+    {
+      name: opts.name,
+      body,
+      description: opts.description || null,
+    },
+  );
+
+  if (ctx?.json || opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  const project = result?.project ?? {};
+  const created = result?.created ? "created" : "existing";
+  console.log(
+    `${project.id ?? ""}\t${project.name ?? opts.name}\t${created}`,
+  );
+}
+
+
+function parseFindOrCreateArgs(args) {
+  const out = {
+    name: null,
+    body: null,
+    bodyFile: null,
+    description: null,
+    workspace: null,
+    baseUrl: null,
+    json: false,
+  };
+  const copy = [...args];
+  while (copy.length) {
+    if (
+      consumeStringFlag(copy, "--name", out, "name") ||
+      consumeStringFlag(copy, "--description", out, "description") ||
+      consumeStringFlag(copy, "--workspace", out, "workspace") ||
+      consumeStringFlag(copy, "--base-url", out, "baseUrl") ||
+      consumeBodyFlags(copy, out)
+    ) {
+      continue;
+    }
+    if (copy[0] === "--json") {
+      out.json = true;
+      copy.shift();
+      continue;
+    }
+    if (copy[0] === "--help" || copy[0] === "-h") {
+      printProjectHelp();
+      process.exit(0);
+    }
+    console.error(`Unknown flag: ${copy[0]}`);
+    process.exit(1);
+  }
+  if (!out.name || !out.name.trim()) {
+    console.error("--name is required");
+    process.exit(1);
+  }
+  return out;
+}

package/lib/commands/run.mjs

@@ -158,7 +158,10 @@ export async function runCommand(ctx, rest) {
   if (!roleResolved) {
     die(EXIT_USAGE, `unknown agent role '${specialistSlug}' for this workspace`);
   }
-  const fsmStage = roleResolved.fsm_stage || null;
+  // Per-routine FSM stage override takes precedence over the role's
+  // default. Lets one role (``ba``) drive both ``ba_requirements`` for
+  // SDLC and ``wbs`` for decomposition without per-process role clones.
+  const fsmStage = resolved.executable?.fsm_stage || roleResolved.fsm_stage || null;
   const roleBody = roleResolved.prompt || "";
   const systemBody = systemResolved?.prompt || "";
 
@@ -484,6 +487,24 @@ function renderPrompt({ patternBody, baseBody, role, routineSpec, task, fsmStage
   out.push("");
   out.push(renderLifecycleHooks());
   if (task) {
+    // ELS-86: parent project context (Brief / WBS / Architecture /
+    // Test architecture / Tasks). The server lifts and caps it; we
+    // render it BEFORE the per-ticket block so the agent sees the
+    // surrounding plan first, then narrows to its own scope. Only
+    // present when the ticket is part of a decomposed project — the
+    // server returns ``project_context: null`` otherwise and we
+    // skip the block silently.
+    if (typeof task.project_context === "string" && task.project_context.trim()) {
+      out.push("");
+      out.push("## Project context");
+      out.push("");
+      out.push(
+        "_Excerpt of the parent project body. Read for surrounding plan;",
+        "your scope is the per-task block below, not the whole project._",
+      );
+      out.push("");
+      out.push(task.project_context.trim());
+    }
     out.push("");
     out.push("## Task");
     out.push(`- **Ticket:** \`${task.ticket_ref}\` (${task.kind})`);
@@ -637,11 +658,19 @@ as a one-shot credential for this run.
 
 function makeBranchName(routine, ticketRef) {
   const stamp = Date.now().toString(36);
+  // Sanitize ``routine`` too — for pipeline-pick runs ``runHandle`` is
+  // ``pipeline:<specialist>`` and the bare ``:`` is in git's reserved
+  // character set, which Cursor's ``/v0/agents`` validator rejects
+  // with HTTP 400 ("Invalid branch name. Branch names cannot start
+  // with '-', contain invalid characters (spaces, ~, ^, :, ?, *, [,
+  // ], \\, .., @{, //), end with '/', '.lock', or '.', or be named
+  // 'HEAD'."). Same regex as the ticketRef path.
+  const safeRoutine = String(routine).replace(/[^a-zA-Z0-9_-]/g, "-");
   if (ticketRef) {
     const safe = String(ticketRef).replace(/[^a-zA-Z0-9_-]/g, "-");
-    return `cursor/ship-${routine}-${safe}-${stamp}`;
+    return `cursor/ship-${safeRoutine}-${safe}-${stamp}`;
   }
-  return `cursor/ship-${routine}-${stamp}`;
+  return `cursor/ship-${safeRoutine}-${stamp}`;
 }
 
 

package/lib/config/schema.mjs

@@ -558,6 +558,10 @@ function validateProcessRoutines(value, errors, warnings) {
         "schedule",
         "window",
         "event",
+        // ``fsm_stage`` overrides the role's default stage so one role
+        // can drive multiple processes (BA serves both
+        // ``ba_requirements`` for SDLC and ``wbs`` for decomposition).
+        "fsm_stage",
       ]),
       prefix,
       warnings,
@@ -616,6 +620,7 @@ function validateProcessRoutines(value, errors, warnings) {
       );
     }
     validateProcessAgentProfile(routine.agent_profile, `${prefix}.agent_profile`, errors);
+    requireOptionalString(routine.fsm_stage, `${prefix}.fsm_stage`, errors, { required: false });
     validateRoutineTrigger(routine.trigger, `${prefix}.trigger`, errors);
     if (routine.schedule !== undefined && routine.schedule !== null) {
       if (typeof routine.schedule !== "string" && !isPlainObject(routine.schedule)) {

package/lib/runtime/routines.mjs

@@ -64,6 +64,11 @@ export function routineToExecutable(id, routine) {
     idempotency: routine.idempotency || null,
     prompt: stringOrNull(routine.prompt) || stringOrNull(routine.instructions),
     agent_profile: stringOrNull(routine.agent_profile) || stringOrNull(routine.specialist?.agent_profile),
+    // Per-routine FSM stage override. When set, ``shipctl run`` uses
+    // it instead of the role's default ``fsm_stage`` — that's how a
+    // single role (e.g. ``ba``) serves both SDLC (``ba_requirements``)
+    // and decomposition (``wbs``) without per-process role clones.
+    fsm_stage: stringOrNull(routine.fsm_stage),
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elmundi/ship-cli",
-  "version": "0.15.3",
+  "version": "0.16.0",
   "type": "module",
   "description": "Ship CLI: bootstrap a repo, sync the catalog, run process routines, report outcomes.",
   "license": "Apache-2.0",