@elmundi/ship-cli 0.12.1 → 0.14.0

package/lib/commands/sync.mjs

@@ -51,7 +51,7 @@ FLAGS
                        version. Use when intentionally bumping a pin.
   --dry-run            Print the resolution plan; do not write or fetch.
   --lock               After sync, materialise every pattern referenced
-                       by the declared lanes and write
+                       by the declared routines and write
                        .ship/shipctl.lock.json (used by
                        'shipctl run --offline').
   --json               Emit a structured JSON summary on stdout.

package/lib/commands/trigger.mjs

@@ -1,43 +1,51 @@
 import { readConfig } from "../config/io.mjs";
+import { dueLanesFromRoutines, dueRoutines } from "../runtime/routines.mjs";
 
-const VERSION = "v1";
+const VERSION = "v2";
 
 export async function triggerCommand(ctx, rest) {
   const opts = parseArgs(rest);
-  const baseUrl = resolveBaseUrl(opts.baseUrl || explicitGlobalBaseUrl(ctx));
-  const token = requireToken();
-  let workspaceId = opts.workspace;
-  if (!workspaceId) workspaceId = await resolveSoleWorkspace(baseUrl, token);
-  const repoId = await resolveRepoId(baseUrl, token, workspaceId, opts.repo);
   const { config } = readConfig(opts.cwd || process.cwd());
+  const local = dueRoutines(config, { event: opts.event, now: opts.now ? new Date(opts.now) : new Date() });
+  let due = local.due;
 
-  const result = await apiPostJson(
-    baseUrl,
-    `/v1/workspaces/${encodeURIComponent(workspaceId)}/repos/${encodeURIComponent(repoId)}/trigger`,
-    {
-      event: opts.event,
-      config,
-      github: {
-        event_name: process.env.SHIP_EVENT_NAME || process.env.GITHUB_EVENT_NAME || "",
-        ref: process.env.SHIP_REF || process.env.GITHUB_REF || "",
-        sha: process.env.SHIP_SHA || process.env.GITHUB_SHA || "",
-        run_id: process.env.GITHUB_RUN_ID || "",
-      },
-    },
-    token,
-  );
+  const baseUrl = resolveBaseUrl(opts.baseUrl || explicitGlobalBaseUrl(ctx));
+  const token = process.env.SHIP_API_TOKEN || "";
+  let claimStatus = "skipped:no-token";
+  if (token && due.length > 0 && !opts.noClaim) {
+    let workspaceId = opts.workspace;
+    if (!workspaceId) workspaceId = await resolveSoleWorkspace(baseUrl, token);
+    const repoId = await resolveRepoId(baseUrl, token, workspaceId, opts.repo);
+    const claimed = [];
+    for (const routine of due) {
+      const claim = await claimRoutine(baseUrl, token, workspaceId, repoId, opts.event, routine);
+      if (claim.status === "claimed" || claim.status === "unavailable") {
+        claimed.push({ ...routine, claim_status: claim.status });
+      }
+    }
+    due = claimed;
+    claimStatus = "attempted";
+  }
+
+  const result = {
+    event: opts.event,
+    status: due.length ? "due" : "noop",
+    due_routines: due,
+    due_lanes: dueLanesFromRoutines(due),
+    skipped_routines: local.skipped,
+    claim_status: claimStatus,
+  };
 
   if (ctx.json || opts.json) {
     console.log(JSON.stringify(result, null, 2));
     return;
   }
-  const due = Array.isArray(result.due_lanes) ? result.due_lanes : [];
   if (!due.length) {
-    console.log(`Ship trigger ${opts.event}: no lanes due.`);
+    console.log(`Ship trigger ${opts.event}: no routines due.`);
     return;
   }
-  console.log(`Ship trigger ${opts.event}: ${due.length} lane(s) due`);
-  for (const lane of due) console.log(`  - ${lane.lane_id}`);
+  console.log(`Ship trigger ${opts.event}: ${due.length} routine(s) due`);
+  for (const routine of due) console.log(`  - ${routine.routine_id}`);
 }
 
 function explicitGlobalBaseUrl(ctx) {
@@ -45,13 +53,13 @@ function explicitGlobalBaseUrl(ctx) {
 }
 
 function printHelp() {
-  console.log(`shipctl trigger — ask Ship which lanes are due (${VERSION})
+  console.log(`shipctl trigger — compute which routines are due (${VERSION})
 
 USAGE
-  shipctl trigger --event schedule --repo <id|owner/name> [--workspace <id>] [--json]
+  shipctl trigger --event schedule [--repo <id|owner/name>] [--workspace <id>] [--json]
 
 ENV
-  SHIP_API_TOKEN             Required.
+  SHIP_API_TOKEN             Optional. When set, due routines are claimed in Ship.
   SHIP_WORKSPACE_API_BASE    Optional API base override.
   SHIP_API_BASE              Fallback API base override.
 `);
@@ -64,6 +72,8 @@ function parseArgs(args) {
     repo: null,
     baseUrl: null,
     cwd: null,
+    now: null,
+    noClaim: false,
     json: false,
   };
   const copy = [...args];
@@ -87,10 +97,16 @@ function parseArgs(args) {
       consume("--workspace", "workspace") ||
       consume("--repo", "repo") ||
       consume("--base-url", "baseUrl") ||
-      consume("--cwd", "cwd")
+      consume("--cwd", "cwd") ||
+      consume("--now", "now")
     ) {
       continue;
     }
+    if (copy[0] === "--no-claim") {
+      out.noClaim = true;
+      copy.shift();
+      continue;
+    }
     if (copy[0] === "--json") {
       out.json = true;
       copy.shift();
@@ -114,15 +130,6 @@ function parseArgs(args) {
   return out;
 }
 
-function requireToken() {
-  const token = process.env.SHIP_API_TOKEN || "";
-  if (!token) {
-    console.error("SHIP_API_TOKEN is required.");
-    process.exit(1);
-  }
-  return token;
-}
-
 function resolveBaseUrl(explicit) {
   if (explicit) return explicit.replace(/\/+$/, "");
   if (process.env.SHIP_WORKSPACE_API_BASE) return process.env.SHIP_WORKSPACE_API_BASE.replace(/\/+$/, "");
@@ -169,6 +176,33 @@ async function apiPostJson(baseUrl, path, body, token) {
   return apiRequest(baseUrl, path, "POST", token, body);
 }
 
+async function claimRoutine(baseUrl, token, workspaceId, repoId, event, routine) {
+  try {
+    return await apiPostJson(
+      baseUrl,
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/repos/${encodeURIComponent(repoId)}/routine-runs/claim`,
+      {
+        event,
+        routine_id: routine.routine_id,
+        window_key: routine.window_key,
+        scheduled_for: routine.scheduled_for,
+        window_start: routine.window_start,
+        window_end: routine.window_end,
+        github: {
+          event_name: process.env.SHIP_EVENT_NAME || process.env.GITHUB_EVENT_NAME || "",
+          ref: process.env.SHIP_REF || process.env.GITHUB_REF || "",
+          sha: process.env.SHIP_SHA || process.env.GITHUB_SHA || "",
+          run_id: process.env.GITHUB_RUN_ID || "",
+        },
+      },
+      token,
+    );
+  } catch (err) {
+    console.error(`warn: routine claim failed, running locally: ${err instanceof Error ? err.message : err}`);
+    return { status: "unavailable" };
+  }
+}
+
 async function apiRequest(baseUrl, path, method, token, body) {
   const url = `${baseUrl}${path}`;
   let res;
@@ -195,6 +229,5 @@ async function apiRequest(baseUrl, path, method, token, body) {
   }
   if (res.ok) return data;
   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);
+  throw new Error(`HTTP ${res.status} ${res.statusText} on ${method} ${url}\n${msg}`);
 }

package/lib/config/schema.mjs

@@ -33,7 +33,7 @@ export const LANE_EVENT_TYPES = Object.freeze([
 export const LANE_IDEMPOTENCY_STORES = Object.freeze(["file", "backend"]);
 export const LANE_IDEMPOTENCY_RESET_ON = Object.freeze(["version-change", "manual"]);
 
-/* RFC-0008 C3.2 — fan-out strategy for multi-pattern lanes.
+/* RFC-0008 C3.2 — fan-out strategy for multi-pattern routines.
  *
  *   matrix      — GitHub Actions matrix: one runner per pattern, parallel.
  *   sequential  — Single runner, `shipctl run` iterates patterns in order.
@@ -49,6 +49,18 @@ export const LANE_FANOUT_MODES = Object.freeze([
 ]);
 export const LANE_FANOUT_DEFAULT = "matrix";
 
+export const PROCESS_AGENT_PROFILES = Object.freeze([
+  "auto",
+  "main",
+  "cheaper",
+  "cursor_agent",
+  "codex_cli",
+  "ship_cloud_agent",
+  "local_cli",
+]);
+
+export const PROCESS_TRIGGER_TYPES = Object.freeze(["manual", "event", "schedule"]);
+
 /* Lane ids travel into file paths (`.ship/state/<key>.json`), workflow
  * file names (`.github/workflows/ship-<lane>.yml`), and env vars, so
  * restrict them conservatively: ASCII lowercase, digits, dash, underscore. */
@@ -198,14 +210,14 @@ export function DEFAULT_PROCESS_CONFIG() {
       { from: "dev_implementation", to: "qa_manual" },
       { from: "qa_manual", to: "pr_review" },
     ],
-    routines: [],
+    routines: {},
   };
 }
 
 /**
  * Back-compat alias. Pre-existing callers expect DEFAULT_CONFIG() to
  * return the current schema's shape; default to v2 so new installs
- * benefit from lanes.
+ * benefit from process routines.
  */
 export function DEFAULT_CONFIG() {
   return DEFAULT_CONFIG_V2();
@@ -346,7 +358,7 @@ function validateV2Process(obj, errors, warnings) {
     }
     pushUnknownKeyWarnings(
       state,
-      new Set(["id", "name", "specialist", "layout", "instructions", "triggers", "exit_conditions", "block_conditions"]),
+      new Set(["id", "name", "specialist", "agent_profile", "layout", "instructions", "triggers", "exit_conditions", "block_conditions"]),
       prefix,
       warnings,
     );
@@ -363,9 +375,33 @@ function validateV2Process(obj, errors, warnings) {
     if (state.instructions !== undefined && typeof state.instructions !== "string") {
       errors.push(`${prefix}.instructions: must be a string when set`);
     }
-    if (state.specialist !== undefined && !isPlainObject(state.specialist) && typeof state.specialist !== "string") {
-      errors.push(`${prefix}.specialist: must be an object or string when set`);
+    if (state.specialist !== undefined) {
+      if (typeof state.specialist === "string") {
+        if (!state.specialist.trim()) {
+          errors.push(`${prefix}.specialist: must be a non-empty string when set`);
+        }
+      } else if (!isPlainObject(state.specialist)) {
+        errors.push(`${prefix}.specialist: must be an object or string when set`);
+      } else {
+        pushUnknownKeyWarnings(
+          state.specialist,
+          new Set(["id", "name", "agent_profile"]),
+          `${prefix}.specialist`,
+          warnings,
+        );
+        requireOptionalString(state.specialist.id, `${prefix}.specialist.id`, errors, { required: false });
+        requireOptionalString(state.specialist.name, `${prefix}.specialist.name`, errors, { required: false });
+        validateProcessAgentProfile(
+          state.specialist.agent_profile,
+          `${prefix}.specialist.agent_profile`,
+          errors,
+        );
+      }
     }
+    validateProcessAgentProfile(state.agent_profile, `${prefix}.agent_profile`, errors);
+    validateProcessTriggers(state.triggers, `${prefix}.triggers`, errors);
+    validateProcessConditions(state.exit_conditions, `${prefix}.exit_conditions`, errors);
+    validateProcessConditions(state.block_conditions, `${prefix}.block_conditions`, errors);
     if (state.layout !== undefined) {
       if (!isPlainObject(state.layout)) {
         errors.push(`${prefix}.layout: must be an object when set`);
@@ -399,12 +435,162 @@ function validateV2Process(obj, errors, warnings) {
         if (!stateIds.has(transition.to)) {
           errors.push(`${prefix}.to: must reference an existing state id`);
         }
+        requireOptionalString(transition.condition, `${prefix}.condition`, errors, { required: false });
       }
     }
   }
 
-  if (process.routines !== undefined && !Array.isArray(process.routines)) {
-    errors.push("process.routines: must be a list when set");
+  validateProcessRoutines(process.routines, errors, warnings);
+}
+
+function validateProcessAgentProfile(value, prefix, errors) {
+  if (value === undefined || value === null) return;
+  if (typeof value !== "string" || !PROCESS_AGENT_PROFILES.includes(value)) {
+    errors.push(`${prefix}: must be one of ${PROCESS_AGENT_PROFILES.join("|")}`);
+  }
+}
+
+function validateProcessTriggers(value, prefix, errors) {
+  if (value === undefined) return;
+  if (!Array.isArray(value)) {
+    errors.push(`${prefix}: must be a list when set`);
+    return;
+  }
+  for (let i = 0; i < value.length; i += 1) {
+    const trigger = value[i];
+    const itemPrefix = `${prefix}[${i}]`;
+    if (!isPlainObject(trigger)) {
+      errors.push(`${itemPrefix}: must be an object`);
+      continue;
+    }
+    if (!PROCESS_TRIGGER_TYPES.includes(trigger.type)) {
+      errors.push(`${itemPrefix}.type: must be one of ${PROCESS_TRIGGER_TYPES.join("|")}`);
+    }
+    if (trigger.type === "schedule") {
+      requireOptionalString(trigger.interval, `${itemPrefix}.interval`, errors, { required: true });
+    } else if (trigger.type === "event") {
+      requireOptionalString(trigger.event, `${itemPrefix}.event`, errors, { required: true });
+    }
+  }
+}
+
+function validateProcessConditions(value, prefix, errors) {
+  if (value === undefined) return;
+  if (!Array.isArray(value)) {
+    errors.push(`${prefix}: must be a list when set`);
+    return;
+  }
+  for (let i = 0; i < value.length; i += 1) {
+    const condition = value[i];
+    const itemPrefix = `${prefix}[${i}]`;
+    if (!isPlainObject(condition)) {
+      errors.push(`${itemPrefix}: must be an object`);
+      continue;
+    }
+    requireOptionalString(condition.expression, `${itemPrefix}.expression`, errors, { required: true });
+  }
+}
+
+function validateProcessRoutines(value, errors, warnings) {
+  if (value === undefined) return;
+  const entries = Array.isArray(value)
+    ? value.map((routine, i) => [String(i), routine, `process.routines[${i}]`])
+    : isPlainObject(value)
+      ? Object.entries(value).map(([id, routine]) => [id, routine, `process.routines.${id}`])
+      : null;
+  if (!entries) {
+    errors.push("process.routines: must be a map or list when set");
+    return;
+  }
+  for (const [routineId, routine, prefix] of entries) {
+    if (!isPlainObject(routine)) {
+      errors.push(`${prefix}: must be an object`);
+      continue;
+    }
+    pushUnknownKeyWarnings(
+      routine,
+      new Set([
+        "id",
+        "name",
+        "cadence",
+        "enabled",
+        "trigger",
+        "description",
+        "prompt",
+        "instructions",
+        "pattern",
+        "patterns",
+        "pattern_version",
+        "fanout",
+        "idempotency",
+        "agent_profile",
+        "specialist_id",
+        "specialist_name",
+        "specialist",
+        "schedule",
+        "window",
+        "event",
+      ]),
+      prefix,
+      warnings,
+    );
+    if (Array.isArray(value)) {
+      requireOptionalString(routine.id, `${prefix}.id`, errors, { required: true });
+    } else if (!LANE_ID_REGEX.test(routineId)) {
+      errors.push(`${prefix}: invalid routine id`);
+    }
+    requireOptionalString(routine.name, `${prefix}.name`, errors, { required: true });
+    requireOptionalString(routine.cadence, `${prefix}.cadence`, errors, { required: false });
+    if (routine.enabled !== undefined && routine.enabled !== null && typeof routine.enabled !== "boolean") {
+      errors.push(`${prefix}.enabled: must be a boolean when set`);
+    }
+    requireOptionalString(routine.description, `${prefix}.description`, errors, { required: false });
+    requireOptionalString(routine.instructions, `${prefix}.instructions`, errors, { required: false });
+    requireOptionalString(routine.prompt, `${prefix}.prompt`, errors, { required: false });
+    requireOptionalString(routine.pattern, `${prefix}.pattern`, errors, { required: false });
+    if (routine.patterns !== undefined) {
+      if (!Array.isArray(routine.patterns) || routine.patterns.some((p) => typeof p !== "string" || !p.trim())) {
+        errors.push(`${prefix}.patterns: must be a list of non-empty strings`);
+      }
+    }
+    if (routine.fanout !== undefined && !LANE_FANOUT_MODES.includes(routine.fanout)) {
+      errors.push(`${prefix}.fanout: must be one of ${LANE_FANOUT_MODES.join("|")}`);
+    }
+    requireOptionalString(routine.specialist_id, `${prefix}.specialist_id`, errors, { required: false });
+    requireOptionalString(routine.specialist_name, `${prefix}.specialist_name`, errors, { required: false });
+    validateProcessAgentProfile(routine.agent_profile, `${prefix}.agent_profile`, errors);
+    validateRoutineTrigger(routine.trigger, `${prefix}.trigger`, errors);
+    if (routine.schedule !== undefined && routine.schedule !== null) {
+      if (typeof routine.schedule !== "string" && !isPlainObject(routine.schedule)) {
+        errors.push(`${prefix}.schedule: must be an object or cron string when set`);
+      }
+    }
+  }
+}
+
+function validateRoutineTrigger(value, prefix, errors) {
+  if (value === undefined || value === null) return;
+  if (!isPlainObject(value)) {
+    errors.push(`${prefix}: must be an object when set`);
+    return;
+  }
+  if (!PROCESS_TRIGGER_TYPES.includes(value.type)) {
+    errors.push(`${prefix}.type: must be one of ${PROCESS_TRIGGER_TYPES.join("|")}`);
+  }
+  if (value.type === "schedule") {
+    requireOptionalString(value.cron ?? value.interval, `${prefix}.cron`, errors, { required: true });
+  }
+  if (value.type === "event") {
+    requireOptionalString(value.event, `${prefix}.event`, errors, { required: true });
+  }
+}
+
+function requireOptionalString(value, prefix, errors, { required }) {
+  if ((value === undefined || value === null) && !required) return;
+  if (typeof value !== "string" || !value.trim()) {
+    errors.push(
+      `${prefix}: must be ${required ? "a non-empty string" : "null or a non-empty string"}`,
+    );
   }
 }
 
@@ -544,8 +730,8 @@ function validateLane(laneId, lane, errors, warnings) {
   ) {
     errors.push(`${prefix}.pattern_version: must be a non-empty semver string when set`);
   }
-  // RFC-0008 C3.2 — `fanout` picks how multi-pattern lanes execute.
-  // Single-pattern lanes ignore it (it's a no-op for them); we emit a
+  // RFC-0008 C3.2 — `fanout` picks how multi-pattern routines execute.
+  // Single-pattern routines ignore it (it's a no-op for them); we emit a
   // warning rather than an error so schedule templates that set it
   // blindly remain portable across single/multi-pattern use.
   if (lane.fanout !== undefined) {

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

@@ -0,0 +1,171 @@
+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());
+}