@elmundi/ship-cli 0.12.1 → 0.14.0

package/bin/shipctl.mjs

@@ -140,13 +140,21 @@ 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);
     process.exit(0);
   }
 
-  if (cmd === "run") {
+  if (cmd === "run" || cmd === "agent-run") {
+    // ``agent-run`` is a back-compat alias for ``run`` — older trigger
+    // workflows still spell it that way until they re-seed.
     const { runCommand } = await import("../lib/commands/run.mjs");
     await runCommand(ctx, rest);
     process.exit(0);

package/lib/agents/cursor.mjs

@@ -0,0 +1,143 @@
+/**
+ * Cursor Cloud Agent runtime adapter.
+ *
+ * Wraps the public ``POST https://api.cursor.com/v0/agents`` API the
+ * ElMundi sibling repo uses (``tools/linear-agent/scripts/cloud-agent-launch.mjs``).
+ * The shape Ship needs:
+ *
+ *   1. Launch an agent against ``repo`` at ``ref`` with ``prompt``.
+ *   2. Poll until the agent's status is one of the terminal values
+ *      (``FINISHED`` / ``ERRORED`` / ``CANCELLED``).
+ *   3. Return the branch name + final status to ``shipctl run``. Side
+ *      effects (tracker writes / inbox rows) happen via the agent's
+ *      own ``POST /agent-runs/finish`` call from inside Cursor — the
+ *      CLI no longer reads a state file off the branch.
+ *
+ * Auth: ``CURSOR_API_KEY`` env var, sent as Basic ``<key>:`` per Cursor's
+ * docs.
+ */
+
+import { Buffer } from "node:buffer";
+
+const BASE = "https://api.cursor.com";
+const TERMINAL_STATUSES = new Set(["FINISHED", "ERRORED", "CANCELLED"]);
+
+
+function authHeader() {
+  const key = (process.env.CURSOR_API_KEY || "").trim();
+  if (!key) {
+    throw new Error("CURSOR_API_KEY is not set");
+  }
+  return "Basic " + Buffer.from(`${key}:`).toString("base64");
+}
+
+
+async function postJson(path, body) {
+  const res = await fetch(`${BASE}${path}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: authHeader(),
+    },
+    body: JSON.stringify(body),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Cursor API ${path} ${res.status}: ${text.slice(0, 500)}`);
+  }
+  return text ? JSON.parse(text) : {};
+}
+
+
+async function getJson(path) {
+  const res = await fetch(`${BASE}${path}`, {
+    headers: { Authorization: authHeader() },
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Cursor API ${path} ${res.status}: ${text.slice(0, 500)}`);
+  }
+  return text ? JSON.parse(text) : {};
+}
+
+
+/**
+ * Launch a single Cursor agent and poll until it terminates.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoUrl       e.g. ``https://github.com/owner/repo``
+ * @param {string} opts.ref           branch the agent checks out (default ``main``)
+ * @param {string} opts.branchName    branch the agent commits onto
+ * @param {string} opts.prompt        full prompt body
+ * @param {boolean} [opts.autoCreatePr] open a PR when done (default false)
+ * @param {number} [opts.pollIntervalMs]   poll cadence (default 15s)
+ * @param {number} [opts.timeoutMs]   total deadline (default 30 min)
+ * @param {(line: string) => void} [opts.onLog] streaming log hook
+ * @returns {Promise<{ agentId: string, branchName: string, status: string, raw: object }>}
+ */
+export async function runCursorAgent({
+  repoUrl,
+  ref = "main",
+  branchName,
+  prompt,
+  autoCreatePr = false,
+  pollIntervalMs = 15_000,
+  timeoutMs = 30 * 60 * 1000,
+  onLog = (l) => console.error(`[cursor] ${l}`),
+} = {}) {
+  if (!repoUrl) throw new Error("runCursorAgent: repoUrl required");
+  if (!branchName) throw new Error("runCursorAgent: branchName required");
+  if (!prompt || typeof prompt !== "string") {
+    throw new Error("runCursorAgent: prompt required");
+  }
+
+  const launch = await postJson("/v0/agents", {
+    prompt: { text: prompt },
+    source: { repository: repoUrl, ref },
+    target: {
+      branchName,
+      autoCreatePr,
+      openAsCursorGithubApp: false,
+    },
+  });
+  const agentId = launch.id || launch.agentId || launch.agent_id;
+  if (!agentId) {
+    throw new Error(`Cursor launch returned no agent id: ${JSON.stringify(launch).slice(0, 300)}`);
+  }
+  onLog(`launched agent=${agentId} branch=${branchName} ref=${ref}`);
+
+  const deadline = Date.now() + timeoutMs;
+  let lastStatus = launch.status || "CREATING";
+  while (Date.now() < deadline) {
+    if (TERMINAL_STATUSES.has(String(lastStatus).toUpperCase())) {
+      onLog(`agent terminal: status=${lastStatus}`);
+      return { agentId, branchName, status: lastStatus, raw: launch };
+    }
+    await sleep(pollIntervalMs);
+    let snapshot;
+    try {
+      snapshot = await getJson(`/v0/agents/${encodeURIComponent(agentId)}`);
+    } catch (err) {
+      onLog(`poll error (continuing): ${err.message}`);
+      continue;
+    }
+    const next = (snapshot.status || "").toString();
+    if (next && next !== lastStatus) {
+      onLog(`status: ${lastStatus} → ${next}`);
+      lastStatus = next;
+    }
+    if (TERMINAL_STATUSES.has(next.toUpperCase())) {
+      return { agentId, branchName, status: next, raw: snapshot };
+    }
+  }
+  throw new Error(
+    `Cursor agent ${agentId} did not reach a terminal state within ${Math.round(
+      timeoutMs / 1000,
+    )}s (last status: ${lastStatus})`,
+  );
+}
+
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}

package/lib/agents/index.mjs

@@ -0,0 +1,51 @@
+/**
+ * Agent runtime dispatcher.
+ *
+ * E14 picks the runtime per ``.ship/config.yml`` ``agent.default.provider``
+ * (and per-routine override under ``agent.overrides.<routine>``). Today
+ * Cursor Cloud is the only one wired in; ``claude`` / ``codex`` slots
+ * exist so adding them later is a single new file plus an entry in
+ * ``RUNTIMES`` here.
+ */
+
+import { runCursorAgent } from "./cursor.mjs";
+
+
+const RUNTIMES = {
+  cursor: runCursorAgent,
+  // claude: runClaudeCodeAgent,   // TODO when we add it
+  // codex:  runCodexAgent,        // TODO when we add it
+};
+
+const DEFAULT_PROVIDER = "cursor";
+
+
+export function resolveProvider(config, routineId) {
+  const override = config?.agent?.overrides?.[routineId]?.provider;
+  if (override) return String(override).toLowerCase();
+  const def = config?.agent?.default?.provider;
+  if (def) return String(def).toLowerCase();
+  return DEFAULT_PROVIDER;
+}
+
+
+/**
+ * Run the configured agent runtime.
+ *
+ * @param {string} provider — one of ``RUNTIMES``' keys.
+ * @param {object} opts — passed straight through to the runtime.
+ * @returns {Promise<{ agentId: string, branchName: string, status: string, raw: object }>}
+ */
+export async function runAgent(provider, opts) {
+  const fn = RUNTIMES[provider];
+  if (!fn) {
+    const known = Object.keys(RUNTIMES).join(", ") || "(none)";
+    throw new Error(
+      `agent runtime '${provider}' is not wired in this build. Known: ${known}`,
+    );
+  }
+  return fn(opts);
+}
+
+
+export const SUPPORTED_PROVIDERS = Object.freeze(Object.keys(RUNTIMES));

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,19 @@ 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]
-                [--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.
+                                       — compute due routines locally, then claim
+                                         the schedule window in Ship.
+    shipctl run --routine <id> [--dry-run] [--json] [--cwd <dir>]
+                                       — execute one routine end-to-end:
+                                         resolve pattern, fetch a ticket
+                                         (if FSM-staged), launch the agent
+                                         runtime, exit on terminal status.
+                                         'shipctl agent-run' is a back-compat
+                                         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 +96,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.
 
@@ -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,6 +177,13 @@ 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 || explicitGlobalBaseUrl(ctx));

package/lib/commands/lanes.mjs

@@ -1,14 +1,14 @@
 /**
  * `shipctl lanes` — generate and manage the thin GitHub Actions caller
- * workflows that delegate to the reusable `run-agent.yml` (RFC-0007 Phase 3).
+ * workflows that delegate to a **vendored** reusable `run-agent.yml` in the
+ * same repository (RFC-0007 Phase 3).
  *
  * Each lane in `.ship/config.yml` (v2) gets one file at
  *   .github/workflows/ship-<lane_id>.yml
- * whose body is nothing but the `on:` triggers (derived from the lane
- * kind) and a single `uses: ElMundiUA/ship/.github/workflows/run-agent.yml@<ref>`
- * call. Any customisation — flags, payload shape, callback URL wiring — is
- * centralised in the reusable workflow so upgrading customer fleets is a
- * single ref bump.
+ * whose body is the `on:` triggers (derived from the lane kind) and
+ *   `uses: ./.github/workflows/run-agent.yml`
+ * `shipctl lanes install` also writes `.github/workflows/run-agent.yml`
+ * from the template bundled inside `@elmundi/ship-cli`.
  *
  * Subcommands:
  *   install   — render wrappers for every declared lane (or just --only X).
@@ -21,6 +21,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import YAML from "yaml";
 
 import { findShipRoot, readConfig } from "../config/io.mjs";
@@ -28,7 +29,6 @@ import {
   validateConfig,
   CONFIG_SCHEMA_VERSION,
   lanePatterns,
-  lanePrimaryPattern,
   laneFanout,
 } from "../config/schema.mjs";
 
@@ -42,9 +42,16 @@ const BANNER_HEADER = `${BANNER_MARKER}
 # Regenerate via: shipctl lanes install
 # Hand edits OUTSIDE the \`ship-cli:\` markers will NOT be overwritten.`;
 
-const DEFAULT_REUSABLE_OWNER = "ElMundiUA";
-const DEFAULT_REUSABLE_REPO = "ship";
-const DEFAULT_REUSABLE_PATH = ".github/workflows/run-agent.yml";
+/** Same-repo reusable workflow path (GitHub Actions). */
+const LOCAL_REUSABLE_USES = "./.github/workflows/run-agent.yml";
+
+const RUN_AGENT_MARKER = "# ship-cli: run-agent v1";
+
+function readRunAgentTemplate() {
+  const dir = path.dirname(fileURLToPath(import.meta.url));
+  const vendor = path.join(dir, "..", "vendor", "run-agent.workflow.yml");
+  return fs.readFileSync(vendor, "utf8");
+}
 
 function printHelp() {
   console.log(`shipctl lanes — manage GitHub Actions caller workflows for the
@@ -62,11 +69,8 @@ USAGE
 
 FLAGS (install)
   --only <ids>           Comma-separated lane ids to render (default: all).
-  --ref <git-ref>        Git ref of ElMundiUA/ship to pin the reusable workflow
-                         to (default: the shipctl_min version from config.yml,
-                         prefixed with 'v' — e.g. v0.12.0).
-  --owner <gh-owner>     GitHub owner of the ship repo (default: ElMundiUA).
-  --repo <name>          GitHub repo name (default: ship).
+  --ref, --owner, --repo Ignored (legacy); reusable workflow is always
+                         ${LOCAL_REUSABLE_USES} in the caller repo.
   --shipctl-version <v>  Pin the @elmundi/ship-cli version the reusable
                          workflow installs on the runner (default: latest).
   --force                Overwrite wrappers that exist but were not generated
@@ -97,6 +101,45 @@ export async function lanesCommand(ctx, rest) {
 
 /* ─────────────────────────── install ─────────────────────────── */
 
+/**
+ * Copy vendored `run-agent.workflow.yml` into `.github/workflows/run-agent.yml`.
+ */
+function syncRunAgentTemplate({ runAgentFile, runAgentRel, dryRun, force, installed, skipped }) {
+  let template;
+  try {
+    template = readRunAgentTemplate();
+  } catch (err) {
+    throw new Error(
+      `cannot read bundled run-agent template: ${err instanceof Error ? err.message : err}`,
+    );
+  }
+  const existed = fs.existsSync(runAgentFile);
+  if (existed) {
+    const cur = fs.readFileSync(runAgentFile, "utf8");
+    if (!cur.includes(RUN_AGENT_MARKER) && !force) {
+      skipped.push({ path: runAgentRel, reason: "run-agent-exists-without-banner" });
+      return;
+    }
+    if (cur === template) {
+      skipped.push({ path: runAgentRel, reason: "run-agent-up-to-date" });
+      return;
+    }
+  }
+  if (dryRun) {
+    installed.push({
+      path: runAgentRel,
+      action: existed ? "would-update-run-agent" : "would-write-run-agent",
+    });
+    return;
+  }
+  fs.mkdirSync(path.dirname(runAgentFile), { recursive: true });
+  fs.writeFileSync(runAgentFile, template, "utf8");
+  installed.push({
+    path: runAgentRel,
+    action: existed ? "updated-run-agent" : "wrote-run-agent",
+  });
+}
+
 async function installCmd(ctx, rest) {
   const args = parseInstallArgs(rest);
   args.dryRun = args.dryRun || Boolean(ctx.dryRun);
@@ -112,20 +155,26 @@ async function installCmd(ctx, rest) {
     );
   }
 
-  const ref = args.ref || deriveDefaultRef(config);
-  const reusable = formatReusableRef({
-    owner: args.owner || DEFAULT_REUSABLE_OWNER,
-    repo: args.repo || DEFAULT_REUSABLE_REPO,
-    ref,
-  });
-
+  const reusable = LOCAL_REUSABLE_USES;
   const targetDir = path.join(shipRoot, WORKFLOW_DIR);
-  if (!args.dryRun) fs.mkdirSync(targetDir, { recursive: true });
+  const runAgentFile = path.join(targetDir, "run-agent.yml");
+  const runAgentRel = path.relative(shipRoot, runAgentFile) || runAgentFile;
 
   const installed = [];
   const skipped = [];
   const errors = [];
 
+  syncRunAgentTemplate({
+    runAgentFile,
+    runAgentRel,
+    dryRun: args.dryRun,
+    force: args.force,
+    installed,
+    skipped,
+  });
+
+  if (!args.dryRun) fs.mkdirSync(targetDir, { recursive: true });
+
   for (const [laneId, lane] of wanted) {
     const file = path.join(targetDir, `ship-${laneId}.yml`);
     const rel = path.relative(shipRoot, file) || file;
@@ -169,7 +218,7 @@ async function installCmd(ctx, rest) {
   };
 
   emitSummary(ctx, args, payload, () => {
-    console.log(`Ship lanes → ${reusable}`);
+    console.log(`Ship lanes → reusable ${reusable}`);
     for (const row of installed) console.log(`  ${row.action}: ${row.path}`);
     for (const row of skipped) console.log(`  skipped (${row.reason}): ${row.path}`);
     for (const row of errors) console.log(`  ERROR: ${row.lane}: ${row.error}`);
@@ -191,7 +240,7 @@ function listCmd(ctx, rest) {
       kind: lane.kind,
       // ``pattern`` keeps the single-string shape for humans/scripts
       // that eyeball the first pattern; ``patterns`` always lists all
-      // so multi-pattern lanes (RFC-0008 C3.1) surface correctly.
+      // so multi-pattern routines (RFC-0008 C3.1) surface correctly.
       pattern: pats[0] || null,
       patterns: pats,
       // ``fanout`` resolves to the runtime default (``matrix``) when
@@ -310,16 +359,6 @@ function selectLanes(config, onlyCsv) {
   return all.filter(([id]) => wanted.has(id));
 }
 
-function deriveDefaultRef(config) {
-  const min = config.shipctl_min;
-  if (typeof min === "string" && /^\d+\.\d+\.\d+/.test(min)) return `v${min}`;
-  return "main";
-}
-
-function formatReusableRef({ owner, repo, ref }) {
-  return `${owner}/${repo}/${DEFAULT_REUSABLE_PATH}@${ref}`;
-}
-
 /**
  * Render the caller workflow YAML. The body is structured first as a JS
  * object so the output is guaranteed to be syntactically valid; we then