@elmundi/ship-cli 0.12.0 → 0.12.2

package/README.md

@@ -445,8 +445,8 @@ shipctl lanes install --yes
 shipctl lanes install --only pr-self-review,release-cut
 
 # wire to a specific shipctl version pin
-shipctl lanes install --shipctl-version 0.12.0 \
-  --owner elmundi --repo ship --ref v0.12.0
+shipctl lanes install --shipctl-version 0.12.1 \
+  --owner elmundi --repo ship --ref v0.12.1
 
 # inspect what's on disk vs config.yml
 shipctl lanes list --json

package/bin/shipctl.mjs

@@ -24,6 +24,7 @@ if (raw[0] === "--version" || raw[0] === "-v" || raw[0] === "version") {
 const { _, ...g } = extractGlobalArgv(raw);
 const ctx = {
   baseUrl: g.baseUrl,
+  baseUrlSource: g.baseUrlSource,
   json: g.json,
   yes: g.yes,
   force: g.force,
@@ -139,6 +140,12 @@ try {
     process.exit(0);
   }
 
+  if (cmd === "process") {
+    const { processCommand } = await import("../lib/commands/process.mjs");
+    await processCommand(ctx, rest);
+    process.exit(0);
+  }
+
   if (cmd === "migrate") {
     const { migrateCommand } = await import("../lib/commands/migrate.mjs");
     await migrateCommand(ctx, rest);

package/lib/commands/help.mjs

@@ -1,20 +1,20 @@
 export function printHelp() {
-  console.log(`shipctl — adopt Ship in a repo, sync the catalog, run lanes, report Runs.
+  console.log(`shipctl — adopt Ship in a repo, sync the catalog, run routines, report outcomes.
 
 Bootstrap a new or existing repo (init / new / doctor), pull the
-methodology catalog into .ship/cache (sync), execute one-shot lanes or
-emit prompts for the workspace runner (run / lanes / kickoff /
+methodology catalog into .ship/cache (sync), execute one-shot routines or
+emit prompts for the workspace runner (trigger / run / kickoff /
 callback). Talks to the methodology + orchestration APIs over HTTPS.
 
 VOCABULARY
-  lanes:   (.ship/config.yml)  → operator console: Automations
-  pattern: (artifact kind)     → operator console: Plays
-  pipeline_runs (DB / API)     → operator console: Runs
-  attention surface            → operator console: Inbox
+  process.routines: (.ship/config.yml) → repo-local scheduled/manual work
+  pattern:          (artifact kind)    → cached role/playbook prompt body
+  routine claim:    (Ship API)         → idempotent schedule-window claim
+  attention surface                    → operator console: Inbox
 
-The protocol-stable terms (lanes:, pattern:, pipeline_runs) stay
-literal in YAML, CLI flags, and HTTP. Operator-facing prose uses the
-console nouns.
+Legacy 'lanes:' configs and '--lane' flags are still accepted as aliases
+so already-seeded repositories keep working while new repos use
+'process.routines'.
 
 GLOBAL FLAGS
   --base-url URL   Methodology API (default: SHIP_API_BASE or
@@ -66,22 +66,18 @@ COMMANDS
                  [--force-unpin] [--dry-run] [--lock] [--json] [--cwd <dir>]
                                        — fetch artifacts into .ship/cache. With --lock,
                                          also writes .ship/shipctl.lock.json covering
-                                         every pattern the declared lanes depend on.
+                                        every pattern the declared routines depend on.
 
   Run
     shipctl trigger --event schedule --repo <id|owner/name> [--workspace <id>] [--json]
-                                       — ask Ship which configured lanes are
-                                         due for the current GitHub trigger.
-    shipctl run --lane <id> [--pattern <id>] [--fanout matrix|sequential|concurrent]
+                                       — compute due routines locally, then claim
+                                         the schedule window in Ship.
+    shipctl run --routine <id> [--pattern <id>] [--fanout matrix|sequential|concurrent]
                 [--trigger event|schedule|manual|once]
                 [--dry-run] [--offline] [--json] [--cwd <dir>]
                 [--ship-run-id <uuid>] [--ship-callback-url <url>] [--ship-run-token <jwt>]
-                                       — one-shot dispatch entry point. 'kind: once'
-                                         lanes execute fully here; 'kind: lane / event /
-                                         schedule' lanes are queued for the workspace
-                                         runner via .github/workflows/run-agent.yml.
-                                         Reports its terminal status via the callback URL
-                                         Ship injected into the workflow.
+                                       — one-shot routine dispatch entry point.
+                                         Use --lane as a legacy alias.
     shipctl lanes install [--only <csv>] [--ref <git-ref>] [--owner <gh>] [--repo <name>]
                           [--shipctl-version <v>] [--dry-run] [--force] [--json] [--cwd <dir>]
     shipctl lanes list   [--json] [--cwd <dir>]
@@ -99,6 +95,17 @@ COMMANDS
                                          RunSummary outcome) back to Ship so it can
                                          render the outcome row and route any
                                          escalations into the Inbox.
+    shipctl process prompt --state <id> [--ticket-json <json>] [--policies-file <path>]
+                           [--cwd <dir>] [--json]
+                                      — assemble a Process/FSM specialist prompt
+                                        bundle with ticket context, allowed
+                                        transitions, policies, and mandatory
+                                        knowledge-first guardrails.
+    shipctl process tickets --workspace <id> [--query <text>] [--tracker <kind>] [--json]
+                                      — read-only tracker picker for selecting
+                                        ticket context before building a process
+                                        prompt. Does not create, comment, or
+                                        transition tickets.
 
   Knowledge
     shipctl knowledge init [--workspace <id>] [--repo <id|owner/name>] [--only <csv>] [--json]

package/lib/commands/knowledge.mjs

@@ -44,10 +44,12 @@
 
 const VERSION = "v1";
 
-/** Ship ships two starter buckets today — keep in lockstep with
- * ``backend.app.services.catalog.KNOWLEDGE_STARTERS`` and
- * ``console/src/lib/api/client.ts#KNOWLEDGE_STARTERS``. */
-const KNOWN_SLUGS = ["code-style", "ui-runbook"];
+/** Static starters with source markdown under ``artifacts/knowledge-starters``.
+ * Procedural catalog recipes are exposed by the backend under the
+ * ``ship-recipes/<pattern-id>`` prefix because that list is generated from
+ * on-disk pattern artifacts at runtime. */
+export const STATIC_KNOWLEDGE_SLUGS = ["code-style", "ui-runbook"];
+export const RECIPE_KNOWLEDGE_PREFIX = "ship-recipes/";
 
 /**
  * @param {{baseUrl?: string, json?: boolean}} ctx
@@ -100,7 +102,9 @@ INIT FLAGS
                      Defaults to the most-recently activated repo in
                      the resolved workspace.
   --only <csv>       Comma-separated starter slugs. Defaults to the
-                     full catalog (${KNOWN_SLUGS.join(", ")}).
+                     full backend catalog, including static starters
+                     (${STATIC_KNOWLEDGE_SLUGS.join(", ")}) and generated
+                     recipe starters under ${RECIPE_KNOWLEDGE_PREFIX}<pattern-id>.
   --base-url URL     Workspace control-plane API. See env fallbacks.
   --json             Emit a machine-readable JSON summary.
 
@@ -123,7 +127,7 @@ EXIT
  */
 async function knowledgeInitCommand(ctx, args) {
   const opts = parseInitArgs(args);
-  const baseUrl = resolveBaseUrl(opts.baseUrl || ctx.baseUrl);
+  const baseUrl = resolveBaseUrl(opts.baseUrl || explicitGlobalBaseUrl(ctx));
   const token = process.env.SHIP_API_TOKEN || "";
   if (!token) {
     console.error(
@@ -134,10 +138,10 @@ async function knowledgeInitCommand(ctx, args) {
 
   const selection = opts.only;
   if (selection !== null) {
-    const unknown = selection.filter((s) => !KNOWN_SLUGS.includes(s));
+    const unknown = selection.filter((s) => !isKnownKnowledgeStarterSlug(s));
     if (unknown.length) {
       console.error(
-        `Unknown knowledge slug(s): ${unknown.join(", ")}\nKnown: ${KNOWN_SLUGS.join(", ")}`,
+        `Unknown knowledge slug(s): ${unknown.join(", ")}\nKnown static slugs: ${STATIC_KNOWLEDGE_SLUGS.join(", ")}; recipe slugs must start with ${RECIPE_KNOWLEDGE_PREFIX}`,
       );
       process.exit(1);
     }
@@ -173,9 +177,16 @@ async function knowledgeInitCommand(ctx, args) {
   );
 }
 
+export function isKnownKnowledgeStarterSlug(slug) {
+  return (
+    STATIC_KNOWLEDGE_SLUGS.includes(slug) ||
+    slug.startsWith(RECIPE_KNOWLEDGE_PREFIX)
+  );
+}
+
 async function knowledgeFetchCommand(ctx, args) {
   const opts = parseFetchArgs(args);
-  const baseUrl = resolveBaseUrl(opts.baseUrl || ctx.baseUrl);
+  const baseUrl = resolveBaseUrl(opts.baseUrl || explicitGlobalBaseUrl(ctx));
   const token = requireToken();
   let workspaceId = opts.workspace;
   if (!workspaceId) {
@@ -218,7 +229,7 @@ async function knowledgeFetchCommand(ctx, args) {
 
 async function knowledgeRefreshIntelCommand(ctx, args) {
   const opts = parseRefreshArgs(args);
-  const baseUrl = resolveBaseUrl(opts.baseUrl || ctx.baseUrl);
+  const baseUrl = resolveBaseUrl(opts.baseUrl || explicitGlobalBaseUrl(ctx));
   const token = requireToken();
   let workspaceId = opts.workspace;
   if (!workspaceId) {
@@ -246,7 +257,7 @@ async function knowledgeRefreshIntelCommand(ctx, args) {
 
 async function knowledgeBootstrapCommand(ctx, args) {
   const opts = parseBootstrapArgs(args);
-  const baseUrl = resolveBaseUrl(opts.baseUrl || ctx.baseUrl);
+  const baseUrl = resolveBaseUrl(opts.baseUrl || explicitGlobalBaseUrl(ctx));
   const token = requireToken();
   let workspaceId = opts.workspace;
   if (!workspaceId) {
@@ -278,6 +289,10 @@ async function knowledgeBootstrapCommand(ctx, args) {
   );
 }
 
+function explicitGlobalBaseUrl(ctx) {
+  return ctx?.baseUrlSource === "flag" ? ctx.baseUrl : null;
+}
+
 /**
  * @param {string[]} args
  * @returns {{

package/lib/commands/process.mjs

@@ -0,0 +1,388 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { readConfig } from "../config/io.mjs";
+import { CONFIG_SCHEMA_VERSION, validateConfig } from "../config/schema.mjs";
+import { apiGet } from "../http.mjs";
+import {
+  buildSpecialistPromptBundle,
+  renderSpecialistPromptBundleMarkdown,
+} from "../process/specialist-prompt-contract.mjs";
+
+export async function processCommand(ctx, rest) {
+  const [sub, ...args] = rest;
+  if (!sub || sub === "help" || sub === "-h" || sub === "--help") {
+    printProcessHelp();
+    return;
+  }
+  if (sub === "prompt" || sub === "bundle") {
+    await processPromptCommand(ctx, args);
+    return;
+  }
+  if (sub === "tickets") {
+    await processTicketsCommand(ctx, args);
+    return;
+  }
+  console.error(
+    `Unknown 'shipctl process' subcommand: ${sub}\nRun: shipctl process --help`,
+  );
+  process.exit(1);
+}
+
+function printProcessHelp() {
+  console.log(`shipctl process — assemble Process/FSM specialist context
+
+USAGE
+  shipctl process prompt --state <state-id> [--ticket-json <json>] [--ticket-file <path>]
+                         [--ticket-id <id>] [--ticket-title <title>] [--ticket-url <url>]
+                         [--ticket-description <text>] [--policies-file <path>]
+                         [--cwd <dir>] [--json]
+  shipctl process prompt --specialist <specialist-id> [...]
+  shipctl process tickets --workspace <id> [--process <id>] [--tracker <kind>]
+                          [--query <text>] [--state open|closed|all] [--limit <n>]
+                          [--project-hint <hint>] [--assignee-me] [--assignee <user>]
+                          [--json]
+
+WHAT IT EMITS
+  A specialist prompt bundle assembled from .ship/config.yml:
+    - process and state identity
+    - specialist template fields from the selected state
+    - ticket context supplied by the caller / tracker picker
+    - allowed outgoing FSM transitions from process.transitions
+    - workspace policies supplied by --policies-file
+    - mandatory knowledge-first and Ship-boundary guardrails
+
+The command does not mutate tracker tickets, execute transitions, or write to
+the repository. It prepares context for an agent runtime; Ship remains
+responsible for side effects, FSM validation, audit logging, and PR-only writes.`);
+}
+
+async function processTicketsCommand(ctx, args) {
+  const opts = parseTicketsArgs(args);
+  const baseUrl = resolveWorkspaceBaseUrl(opts.baseUrl || ctx.baseUrl);
+  const token = process.env.SHIP_API_TOKEN || "";
+  if (!token) {
+    console.error("SHIP_API_TOKEN is required for shipctl process tickets.");
+    process.exit(1);
+  }
+  const processId = opts.processId || "development";
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries({
+    tracker: opts.tracker,
+    project_hint: opts.projectHint,
+    state: opts.state,
+    query: opts.query,
+    assignee: opts.assignee,
+    limit: opts.limit,
+  })) {
+    if (value !== null && value !== undefined && value !== "") {
+      params.set(key, String(value));
+    }
+  }
+  if (opts.assigneeMe) params.set("assignee_me", "true");
+  const suffix = params.toString() ? `?${params}` : "";
+  const data = await apiGet(
+    baseUrl,
+    `/v1/workspaces/${encodeURIComponent(opts.workspace)}/processes/${encodeURIComponent(processId)}/tickets${suffix}`,
+  );
+  if (ctx.json || opts.json) {
+    console.log(JSON.stringify(data, null, 2));
+    return;
+  }
+  const tickets = Array.isArray(data?.tickets) ? data.tickets : [];
+  console.log(`Tracker: ${data?.tracker || opts.tracker || "(auto)"}`);
+  if (!tickets.length) {
+    console.log("No tickets matched.");
+    return;
+  }
+  for (const ticket of tickets) {
+    const id = ticket.key || ticket.display_id || ticket.id || "(no id)";
+    const title = ticket.title || "(untitled)";
+    const status = ticket.status ? ` [${ticket.status}]` : "";
+    const url = ticket.url ? `\n  ${ticket.url}` : "";
+    console.log(`- ${id}${status}: ${title}${url}`);
+  }
+}
+
+async function processPromptCommand(ctx, args) {
+  const opts = parsePromptArgs(args);
+  const cwd = opts.cwd || process.cwd();
+  let config;
+  try {
+    config = readConfig(cwd).config;
+  } catch (err) {
+    die(err instanceof Error ? err.message : String(err));
+  }
+  if (config.version !== CONFIG_SCHEMA_VERSION) {
+    die(
+      `.ship/config.yml is at v${config.version}; shipctl process prompt requires v${CONFIG_SCHEMA_VERSION}.\nRun 'shipctl migrate' to upgrade.`,
+    );
+  }
+  const validation = validateConfig(config);
+  if (!validation.ok) {
+    die(["config is invalid:", ...validation.errors.map((e) => `  - ${e}`)].join("\n"));
+  }
+  const processConfig = config.process;
+  if (!processConfig || typeof processConfig !== "object") {
+    die("process: missing from .ship/config.yml");
+  }
+
+  const state = selectState(processConfig, opts);
+  const allowedTransitions = Array.isArray(processConfig.transitions)
+    ? processConfig.transitions.filter((transition) => transition.from === state.id)
+    : [];
+  const bundle = buildSpecialistPromptBundle({
+    process: processConfig,
+    state,
+    allowedTransitions,
+    ticket: resolveTicket(opts),
+    policies: readOptionalFile(opts.policiesFile, "policies"),
+  });
+
+  if (ctx.json || opts.json) {
+    console.log(JSON.stringify(bundle, null, 2));
+    return;
+  }
+  process.stdout.write(renderSpecialistPromptBundleMarkdown(bundle));
+}
+
+function parsePromptArgs(args) {
+  const out = {
+    state: null,
+    specialist: null,
+    cwd: null,
+    json: false,
+    ticketJson: null,
+    ticketFile: null,
+    ticket: {},
+    policiesFile: null,
+  };
+  const copy = [...args];
+  const readValue = (flag) => {
+    const current = copy.shift();
+    if (current === flag) {
+      if (copy.length === 0) die(`${flag} requires a value`);
+      return String(copy.shift());
+    }
+    const prefix = `${flag}=`;
+    if (current && current.startsWith(prefix)) {
+      return current.slice(prefix.length);
+    }
+    copy.unshift(current);
+    return null;
+  };
+
+  while (copy.length) {
+    const arg = copy[0];
+    if (arg === "--help" || arg === "-h") {
+      printProcessHelp();
+      process.exit(0);
+    }
+    if (arg === "--json") {
+      copy.shift();
+      out.json = true;
+      continue;
+    }
+    const state = readValue("--state");
+    if (state !== null) {
+      out.state = state;
+      continue;
+    }
+    const specialist = readValue("--specialist");
+    if (specialist !== null) {
+      out.specialist = specialist;
+      continue;
+    }
+    const cwd = readValue("--cwd");
+    if (cwd !== null) {
+      out.cwd = path.resolve(cwd);
+      continue;
+    }
+    const ticketJson = readValue("--ticket-json");
+    if (ticketJson !== null) {
+      out.ticketJson = ticketJson;
+      continue;
+    }
+    const ticketFile = readValue("--ticket-file");
+    if (ticketFile !== null) {
+      out.ticketFile = path.resolve(ticketFile);
+      continue;
+    }
+    const policiesFile = readValue("--policies-file");
+    if (policiesFile !== null) {
+      out.policiesFile = path.resolve(policiesFile);
+      continue;
+    }
+    for (const [flag, key] of [
+      ["--ticket-id", "id"],
+      ["--ticket-key", "key"],
+      ["--ticket-title", "title"],
+      ["--ticket-url", "url"],
+      ["--ticket-status", "status"],
+      ["--ticket-description", "description"],
+    ]) {
+      const value = readValue(flag);
+      if (value !== null) {
+        out.ticket[key] = value;
+        break;
+      }
+    }
+    if (copy[0] === arg) {
+      die(`unknown argument: ${arg}\nRun: shipctl process prompt --help`);
+    }
+  }
+  if (!out.state && !out.specialist) {
+    die("either --state <state-id> or --specialist <specialist-id> is required");
+  }
+  if (out.state && out.specialist) {
+    die("use either --state or --specialist, not both");
+  }
+  return out;
+}
+
+function parseTicketsArgs(args) {
+  const out = {
+    workspace: null,
+    processId: "development",
+    tracker: null,
+    projectHint: null,
+    query: null,
+    state: "open",
+    limit: 10,
+    assigneeMe: false,
+    assignee: null,
+    baseUrl: null,
+    json: false,
+  };
+  const copy = [...args];
+  const readValue = (flag) => {
+    const current = copy.shift();
+    if (current === flag) {
+      if (copy.length === 0) die(`${flag} requires a value`);
+      return String(copy.shift());
+    }
+    const prefix = `${flag}=`;
+    if (current && current.startsWith(prefix)) {
+      return current.slice(prefix.length);
+    }
+    copy.unshift(current);
+    return null;
+  };
+  while (copy.length) {
+    const arg = copy[0];
+    if (arg === "--help" || arg === "-h") {
+      printProcessHelp();
+      process.exit(0);
+    }
+    if (arg === "--json") {
+      copy.shift();
+      out.json = true;
+      continue;
+    }
+    if (arg === "--assignee-me") {
+      copy.shift();
+      out.assigneeMe = true;
+      continue;
+    }
+    for (const [flag, key] of [
+      ["--workspace", "workspace"],
+      ["--process", "processId"],
+      ["--tracker", "tracker"],
+      ["--project-hint", "projectHint"],
+      ["--query", "query"],
+      ["--state", "state"],
+      ["--limit", "limit"],
+      ["--assignee", "assignee"],
+      ["--base-url", "baseUrl"],
+    ]) {
+      const value = readValue(flag);
+      if (value !== null) {
+        out[key] = key === "limit" ? Number(value) : value;
+        break;
+      }
+    }
+    if (copy[0] === arg) {
+      die(`unknown argument: ${arg}\nRun: shipctl process tickets --help`);
+    }
+  }
+  if (!out.workspace) die("--workspace <id> is required");
+  if (!["open", "closed", "all"].includes(out.state)) {
+    die("--state must be one of open|closed|all");
+  }
+  if (!Number.isInteger(out.limit) || out.limit < 1 || out.limit > 25) {
+    die("--limit must be an integer between 1 and 25");
+  }
+  return out;
+}
+
+function selectState(processConfig, opts) {
+  const states = Array.isArray(processConfig.states) ? processConfig.states : [];
+  if (opts.state) {
+    const state = states.find((item) => item.id === opts.state);
+    if (!state) die(`unknown process state ${JSON.stringify(opts.state)}`);
+    return state;
+  }
+  const state = states.find((item) => {
+    const specialist = item.specialist;
+    if (typeof specialist === "string") return specialist === opts.specialist;
+    if (specialist && typeof specialist === "object") {
+      return specialist.id === opts.specialist || specialist.name === opts.specialist;
+    }
+    return false;
+  });
+  if (!state) die(`unknown process specialist ${JSON.stringify(opts.specialist)}`);
+  return state;
+}
+
+function resolveTicket(opts) {
+  const parts = [];
+  if (opts.ticketFile) {
+    const body = readOptionalFile(opts.ticketFile, "ticket");
+    if (body) {
+      parts.push(parseTicketJson(body, `ticket file ${opts.ticketFile}`));
+    }
+  }
+  if (opts.ticketJson) {
+    parts.push(parseTicketJson(opts.ticketJson, "--ticket-json"));
+  }
+  if (Object.keys(opts.ticket).length) {
+    parts.push(opts.ticket);
+  }
+  if (!parts.length) return null;
+  return Object.assign({}, ...parts);
+}
+
+function parseTicketJson(value, label) {
+  try {
+    const parsed = JSON.parse(value);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      die(`${label}: must be a JSON object`);
+    }
+    return parsed;
+  } catch (err) {
+    die(`${label}: failed to parse JSON (${err instanceof Error ? err.message : err})`);
+  }
+}
+
+function readOptionalFile(filePath, label) {
+  if (!filePath) return null;
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch (err) {
+    die(`failed to read ${label} file ${filePath}: ${err instanceof Error ? err.message : err}`);
+  }
+}
+
+function resolveWorkspaceBaseUrl(explicit) {
+  return (
+    explicit ||
+    process.env.SHIP_WORKSPACE_API_BASE ||
+    process.env.SHIP_API_BASE ||
+    "https://api.ship.elmundi.com"
+  );
+}
+
+function die(message) {
+  console.error(message);
+  process.exit(1);
+}