@elmundi/ship-cli 0.12.1 → 0.14.0

package/lib/runtime/routines.mjs

@@ -0,0 +1,264 @@
+import { laneFanout, lanePatterns, LANE_FANOUT_DEFAULT } from "../config/schema.mjs";
+
+const DEFAULT_SCHEDULE_WINDOW_MINUTES = 30;
+
+export function routineEntries(config) {
+  const process = config?.process;
+  const raw = process && typeof process === "object" ? process.routines : null;
+  const out = [];
+  if (Array.isArray(raw)) {
+    for (const item of raw) {
+      if (!item || typeof item !== "object") continue;
+      const id = typeof item.id === "string" ? item.id.trim() : "";
+      if (!id) continue;
+      out.push([id, item]);
+    }
+  } else if (raw && typeof raw === "object") {
+    for (const [id, item] of Object.entries(raw)) {
+      if (!item || typeof item !== "object") continue;
+      out.push([id, { id, ...item }]);
+    }
+  }
+  return out;
+}
+
+export function routineMap(config) {
+  return Object.fromEntries(routineEntries(config));
+}
+
+export function resolveExecutable(config, id) {
+  const routines = routineMap(config);
+  if (routines[id]) {
+    return { kind: "routine", id, source: routines[id], executable: routineToExecutable(id, routines[id]) };
+  }
+  const lane = config?.lanes?.[id];
+  if (lane) {
+    return { kind: "lane", id, source: lane, executable: laneToExecutable(id, lane) };
+  }
+  return null;
+}
+
+export function executableIds(config) {
+  return {
+    routines: Object.keys(routineMap(config)).sort(),
+    lanes: Object.keys(config?.lanes || {}).sort(),
+  };
+}
+
+export function routineToExecutable(id, routine) {
+  const trigger = normalizeRoutineTrigger(routine);
+  return {
+    id,
+    type: "routine",
+    kind: trigger.kind,
+    trigger,
+    pattern: stringOrNull(routine.pattern),
+    patterns: Array.isArray(routine.patterns) ? routine.patterns : undefined,
+    pattern_version: stringOrNull(routine.pattern_version),
+    fanout: routine.fanout || LANE_FANOUT_DEFAULT,
+    idempotency: routine.idempotency || null,
+    prompt: stringOrNull(routine.prompt) || stringOrNull(routine.instructions),
+    agent_profile: stringOrNull(routine.agent_profile) || stringOrNull(routine.specialist?.agent_profile),
+  };
+}
+
+export function laneToExecutable(id, lane) {
+  return {
+    id,
+    type: "lane",
+    kind: lane.kind,
+    trigger: laneTrigger(lane),
+    pattern: lane.pattern,
+    patterns: lane.patterns,
+    pattern_version: lane.pattern_version,
+    fanout: laneFanout(lane),
+    idempotency: lane.idempotency || null,
+    prompt: null,
+    agent_profile: null,
+  };
+}
+
+export function executablePatterns(executable) {
+  return lanePatterns(executable);
+}
+
+export function executableFanout(executable) {
+  return executable?.fanout || LANE_FANOUT_DEFAULT;
+}
+
+export function dueRoutines(config, { event, now = new Date() }) {
+  const due = [];
+  const skipped = [];
+  for (const [routineId, routine] of routineEntries(config)) {
+    if (routine.enabled === false) {
+      skipped.push({ routine_id: routineId, reason: "disabled" });
+      continue;
+    }
+    const executable = routineToExecutable(routineId, routine);
+    if (!routineAcceptsEvent(executable, event)) {
+      skipped.push({ routine_id: routineId, reason: "trigger_mismatch", trigger: executable.kind });
+      continue;
+    }
+    if (event === "schedule") {
+      const slot = latestCronMatch(executable.trigger.cron, {
+        now,
+        windowMinutes: executable.trigger.window_minutes,
+      });
+      if (!slot) {
+        skipped.push({ routine_id: routineId, reason: "not_due", trigger: "schedule" });
+        continue;
+      }
+      const windowEnd = new Date(slot.getTime() + executable.trigger.window_minutes * 60_000);
+      due.push({
+        routine_id: routineId,
+        trigger: "schedule",
+        cron: executable.trigger.cron,
+        scheduled_for: slot.toISOString(),
+        window_start: slot.toISOString(),
+        window_end: windowEnd.toISOString(),
+        window_key: `schedule:${routineId}:${formatWindowKey(slot)}`,
+      });
+      continue;
+    }
+    const started = new Date(now);
+    due.push({
+      routine_id: routineId,
+      trigger: event,
+      scheduled_for: started.toISOString(),
+      window_start: started.toISOString(),
+      window_end: started.toISOString(),
+      window_key: `${event}:${routineId}:${formatWindowKey(started)}`,
+    });
+  }
+  return { due, skipped };
+}
+
+export function dueLanesFromRoutines(due) {
+  return due.map((routine) => ({
+    lane_id: routine.routine_id,
+    routine_id: routine.routine_id,
+    kind: routine.trigger,
+    reason: "due",
+    window_key: routine.window_key,
+    scheduled_for: routine.scheduled_for,
+  }));
+}
+
+function normalizeRoutineTrigger(routine) {
+  const trigger = routine.trigger && typeof routine.trigger === "object" ? routine.trigger : {};
+  if (routine.schedule || trigger.type === "schedule") {
+    const schedule = routine.schedule && typeof routine.schedule === "object" ? routine.schedule : {};
+    const cron =
+      stringOrNull(trigger.cron) ||
+      stringOrNull(trigger.interval) ||
+      stringOrNull(schedule.cron) ||
+      stringOrNull(schedule.interval) ||
+      (typeof routine.schedule === "string" ? routine.schedule : null);
+    return {
+      kind: "schedule",
+      cron,
+      window_minutes: parseWindowMinutes(trigger.window || schedule.window || routine.window),
+      catchup: stringOrNull(trigger.catchup) || stringOrNull(schedule.catchup) || "latest",
+    };
+  }
+  if (trigger.type === "event" || routine.event) {
+    return {
+      kind: "event",
+      event: stringOrNull(trigger.event) || stringOrNull(routine.event),
+    };
+  }
+  return { kind: "once" };
+}
+
+function laneTrigger(lane) {
+  if (lane.kind === "schedule") {
+    return {
+      kind: "schedule",
+      cron: stringOrNull(lane.cron),
+      window_minutes: DEFAULT_SCHEDULE_WINDOW_MINUTES,
+      catchup: "latest",
+    };
+  }
+  if (lane.kind === "event") return { kind: "event", event: stringOrNull(lane.on) };
+  return { kind: lane.kind || "once" };
+}
+
+function routineAcceptsEvent(executable, event) {
+  if (event === "schedule") return executable.kind === "schedule";
+  if (event === "manual") return ["schedule", "event", "once"].includes(executable.kind);
+  if (executable.kind !== "event") return false;
+  const configured = executable.trigger.event || "";
+  return configured.split(",").map((part) => part.trim()).filter(Boolean).includes(event);
+}
+
+function latestCronMatch(cron, { now, windowMinutes }) {
+  if (typeof cron !== "string" || !cron.trim()) return null;
+  const fields = cron.trim().split(/\s+/);
+  if (fields.length !== 5) return null;
+  const [minute, hour, dom, month, dow] = fields;
+  const cursor = new Date(now);
+  cursor.setUTCSeconds(0, 0);
+  for (let offset = 0; offset <= windowMinutes; offset += 1) {
+    const candidate = new Date(cursor.getTime() - offset * 60_000);
+    if (
+      cronFieldMatches(minute, candidate.getUTCMinutes(), 0, 59) &&
+      cronFieldMatches(hour, candidate.getUTCHours(), 0, 23) &&
+      cronFieldMatches(dom, candidate.getUTCDate(), 1, 31) &&
+      cronFieldMatches(month, candidate.getUTCMonth() + 1, 1, 12) &&
+      cronFieldMatches(dow, candidate.getUTCDay(), 0, 6)
+    ) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+function cronFieldMatches(expr, value, min, max) {
+  for (const rawPart of String(expr).split(",")) {
+    const part = rawPart.trim();
+    if (!part) continue;
+    let step = 1;
+    let base = part;
+    if (part.includes("/")) {
+      const pieces = part.split("/");
+      base = pieces[0];
+      step = Number.parseInt(pieces[1], 10);
+      if (!Number.isInteger(step) || step <= 0) continue;
+    }
+    let start;
+    let end;
+    if (base === "*") {
+      start = min;
+      end = max;
+    } else if (base.includes("-")) {
+      const [a, b] = base.split("-");
+      start = Number.parseInt(a, 10);
+      end = Number.parseInt(b, 10);
+    } else {
+      start = Number.parseInt(base, 10);
+      end = start;
+    }
+    if (!Number.isInteger(start) || !Number.isInteger(end)) continue;
+    if (start <= value && value <= end && (value - start) % step === 0) return true;
+  }
+  return false;
+}
+
+function parseWindowMinutes(value) {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) return Math.floor(value);
+  if (typeof value !== "string" || !value.trim()) return DEFAULT_SCHEDULE_WINDOW_MINUTES;
+  const raw = value.trim();
+  const match = raw.match(/^(\d+)\s*(m|min|minute|minutes)?$/i);
+  if (match) return Math.max(1, Number.parseInt(match[1], 10));
+  const hours = raw.match(/^(\d+)\s*(h|hr|hour|hours)$/i);
+  if (hours) return Math.max(1, Number.parseInt(hours[1], 10) * 60);
+  return DEFAULT_SCHEDULE_WINDOW_MINUTES;
+}
+
+function formatWindowKey(date) {
+  return date.toISOString().slice(0, 16).replace(/[-:]/g, "").replace("T", "T");
+}
+
+function stringOrNull(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}

package/lib/vendor/run-agent.workflow.yml

@@ -0,0 +1,254 @@
+# ship-cli: run-agent v1 — generated by `shipctl lanes install`.
+# Regenerate via: shipctl lanes install
+# Template ships with @elmundi/ship-cli; hand edits outside this banner may be overwritten.
+name: Ship · run-agent (reusable)
+# RFC-0007 Phase 3 + RFC-0008 C3.2 — reusable workflow for lane wrappers.
+# Caller repos use: uses: ./.github/workflows/run-agent.yml (same repository).
+
+on:
+  workflow_call:
+    inputs:
+      lane:
+        description: "Lane id as declared in .ship/config.yml"
+        type: string
+        required: true
+      trigger:
+        description: "Override trigger (once|event|schedule|manual). Defaults to github.event_name."
+        type: string
+        required: false
+        default: ""
+      shipctl_version:
+        description: "npm dist-tag or semver for @elmundi/ship-cli. Default: latest."
+        type: string
+        required: false
+        default: "latest"
+      node_version:
+        description: "Node.js major version for the runner"
+        type: string
+        required: false
+        default: "20"
+      dry_run:
+        description: "Resolve the lane but neither call the callback nor write the idempotency marker."
+        type: boolean
+        required: false
+        default: false
+      offline:
+        description: "Do not talk to the methodology API; read patterns from the local .ship/cache."
+        type: boolean
+        required: false
+        default: false
+      ship_run_id:
+        description: "Pipeline-run id the callback should report against (set by Ship dispatch)."
+        type: string
+        required: false
+        default: ""
+      ship_callback_url:
+        description: "Ship callback URL (set by Ship dispatch)."
+        type: string
+        required: false
+        default: ""
+      upload_prompt:
+        description: "Upload the rendered prompt as a workflow artifact named `ship-prompt`."
+        type: boolean
+        required: false
+        default: true
+    secrets:
+      SHIP_API_TOKEN:
+        description: "Methodology API token (optional; required for private patterns / callbacks)."
+        required: false
+      SHIP_API_BASE:
+        description: "Ship API origin for shipctl (e.g. https://api.example.com). Wizard seeds this from SHIP_PUBLIC_URL."
+        required: false
+      SHIP_RUN_TOKEN:
+        description: "Short-lived bearer token Ship issued when dispatching this run."
+        required: false
+
+permissions:
+  contents: read
+
+jobs:
+  plan:
+    name: "ship plan --lane ${{ inputs.lane }}"
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      matrix: ${{ steps.plan.outputs.matrix }}
+      patterns: ${{ steps.plan.outputs.patterns }}
+      fanout: ${{ steps.plan.outputs.fanout }}
+    steps:
+      - name: Checkout caller repo
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ inputs.node_version }}
+
+      - name: Install shipctl
+        run: npm install -g @elmundi/ship-cli@${{ inputs.shipctl_version }}
+
+      - name: Resolve patterns + fanout
+        id: plan
+        env:
+          LANE: ${{ inputs.lane }}
+        run: |
+          set -euo pipefail
+          JSON=$(shipctl lanes list --json)
+          ROW=$(echo "$JSON" | jq -c --arg lane "$LANE" '.lanes[] | select(.lane == $lane)')
+          if [ -z "$ROW" ] || [ "$ROW" = "null" ]; then
+            echo "::error::lane '$LANE' not declared in .ship/config.yml"
+            exit 1
+          fi
+          PATTERNS=$(echo "$ROW" | jq -c '.patterns // []')
+          FANOUT=$(echo "$ROW" | jq -r '.fanout // "matrix"')
+          N=$(echo "$PATTERNS" | jq 'length')
+          if [ "$N" -lt 1 ]; then
+            echo "::error::lane '$LANE' declares no patterns"
+            exit 1
+          fi
+
+          if [ "$FANOUT" = "matrix" ] && [ "$N" -gt 1 ]; then
+            MATRIX=$(echo "$PATTERNS" | jq -c '[.[] | {pattern: ., fanout: "matrix"}]')
+          elif [ "$N" -gt 1 ]; then
+            MATRIX=$(jq -cn --arg fanout "$FANOUT" '[{pattern: "", fanout: $fanout}]')
+          else
+            MATRIX='[{"pattern": "", "fanout": "matrix"}]'
+          fi
+
+          echo "patterns=$PATTERNS" >> "$GITHUB_OUTPUT"
+          echo "fanout=$FANOUT"     >> "$GITHUB_OUTPUT"
+          echo "matrix=$MATRIX"     >> "$GITHUB_OUTPUT"
+          {
+            echo "### Plan"
+            echo "- lane: \`$LANE\`"
+            echo "- patterns: $(echo "$PATTERNS" | jq -r '. | join(", ")')"
+            echo "- fanout: $FANOUT"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+  run:
+    name: "ship run --lane ${{ inputs.lane }} (pattern=${{ matrix.entry.pattern }} fanout=${{ matrix.entry.fanout }})"
+    needs: plan
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        entry: ${{ fromJSON(needs.plan.outputs.matrix) }}
+    steps:
+      - name: Checkout caller repo
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ inputs.node_version }}
+
+      - name: Install shipctl
+        run: npm install -g @elmundi/ship-cli@${{ inputs.shipctl_version }}
+
+      - name: Resolve trigger
+        id: trigger
+        env:
+          OVERRIDE: ${{ inputs.trigger }}
+          EVENT: ${{ github.event_name }}
+        run: |
+          set -euo pipefail
+          if [ -n "${OVERRIDE:-}" ]; then
+            echo "value=$OVERRIDE" >> "$GITHUB_OUTPUT"
+          else
+            case "$EVENT" in
+              workflow_dispatch) echo "value=manual" >> "$GITHUB_OUTPUT" ;;
+              schedule)          echo "value=schedule" >> "$GITHUB_OUTPUT" ;;
+              *)                 echo "value=event" >> "$GITHUB_OUTPUT" ;;
+            esac
+          fi
+
+      - name: shipctl run
+        id: run
+        env:
+          SHIP_API_TOKEN: ${{ secrets.SHIP_API_TOKEN }}
+          SHIP_API_BASE: ${{ secrets.SHIP_API_BASE }}
+          SHIP_RUN_TOKEN: ${{ secrets.SHIP_RUN_TOKEN }}
+          SHIP_RUN_ID: ${{ inputs.ship_run_id }}
+          MATRIX_PATTERN: ${{ matrix.entry.pattern }}
+          MATRIX_FANOUT:  ${{ matrix.entry.fanout }}
+        run: |
+          set -euo pipefail
+          mkdir -p .ship/run-output
+          ARGS=(run --lane "${{ inputs.lane }}" --trigger "${{ steps.trigger.outputs.value }}")
+          [ "${{ inputs.dry_run }}" = "true" ] && ARGS+=(--dry-run)
+          [ "${{ inputs.offline }}" = "true" ] && ARGS+=(--offline)
+          [ -n "${MATRIX_PATTERN:-}" ] && ARGS+=(--pattern "$MATRIX_PATTERN")
+          [ -n "${MATRIX_FANOUT:-}"  ] && ARGS+=(--fanout  "$MATRIX_FANOUT")
+          [ -n "${SHIP_RUN_ID:-}"    ] && ARGS+=(--ship-run-id "$SHIP_RUN_ID")
+
+          set +e
+          shipctl "${ARGS[@]}" \
+            1> .ship/run-output/prompt.md \
+            2> .ship/run-output/shipctl.log
+          STATUS=$?
+          set -e
+
+          cat .ship/run-output/shipctl.log >&2 || true
+          echo "status=$STATUS" >> "$GITHUB_OUTPUT"
+          if [ "$STATUS" -ne 0 ]; then
+            echo "::error::shipctl run exited with $STATUS"
+            exit "$STATUS"
+          fi
+
+      - name: Upload prompt artifact
+        if: ${{ inputs.upload_prompt && (success() || failure()) }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: ship-prompt-${{ inputs.lane }}${{ matrix.entry.pattern != '' && format('-{0}', matrix.entry.pattern) || '' }}
+          path: .ship/run-output/
+          if-no-files-found: warn
+          retention-days: 14
+
+  aggregate:
+    name: "ship aggregate --lane ${{ inputs.lane }}"
+    if: ${{ always() && inputs.ship_callback_url != '' }}
+    needs: [plan, run]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout caller repo
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ inputs.node_version }}
+
+      - name: Install shipctl
+        run: npm install -g @elmundi/ship-cli@${{ inputs.shipctl_version }}
+
+      - name: Report rollup to Ship
+        env:
+          SHIP_RUN_ID: ${{ inputs.ship_run_id }}
+          SHIP_CALLBACK_URL: ${{ inputs.ship_callback_url }}
+          SHIP_RUN_TOKEN: ${{ secrets.SHIP_RUN_TOKEN }}
+          GH_RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          RUN_RESULT: ${{ needs.run.result }}
+          PLAN_PATTERNS: ${{ needs.plan.outputs.patterns }}
+          PLAN_FANOUT: ${{ needs.plan.outputs.fanout }}
+        run: |
+          set -euo pipefail
+          case "$RUN_RESULT" in
+            success)
+              CB=ok
+              SUMMARY="Ship lane ${{ inputs.lane }} completed ($PLAN_FANOUT over $PLAN_PATTERNS)."
+              ;;
+            failure|cancelled|skipped|*)
+              CB=fail
+              SUMMARY="Ship lane ${{ inputs.lane }} $RUN_RESULT ($PLAN_FANOUT over $PLAN_PATTERNS)."
+              ;;
+          esac
+          shipctl callback --status "$CB" \
+            --summary "$SUMMARY" \
+            --metric "lane_id=${{ inputs.lane }}" \
+            --metric "fanout=$PLAN_FANOUT" \
+            --metric "patterns=$(echo "$PLAN_PATTERNS" | jq -r '. | join(",")')" \
+            --metric "gh_workflow_run_id=${{ github.run_id }}" \
+            --metric "gh_html_url=$GH_RUN_URL" \
+            --metric "gh_event=${{ github.event_name }}" || true

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@elmundi/ship-cli",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "type": "module",
-  "description": "Ship CLI: bootstrap a repo, sync the Plays catalog, run Automations, report Runs.",
+  "description": "Ship CLI: bootstrap a repo, sync the catalog, run process routines, report outcomes.",
   "license": "Apache-2.0",
   "author": "Denys Kuzin",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ElMundiUA/ship.git",
+    "url": "git+https://github.com/ElMundiUA/ship.git",
     "directory": "cli"
   },
   "bugs": {
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "bin": {
-    "shipctl": "./bin/shipctl.mjs"
+    "shipctl": "bin/shipctl.mjs"
   },
   "scripts": {
     "test": "node --test tests/*.test.mjs"