@elmundi/ship-cli 0.12.2 → 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/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.
@@ -730,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/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,6 +1,6 @@
 {
   "name": "@elmundi/ship-cli",
-  "version": "0.12.2",
+  "version": "0.14.0",
   "type": "module",
   "description": "Ship CLI: bootstrap a repo, sync the catalog, run process routines, report outcomes.",
   "license": "Apache-2.0",