model-eol 0.2.4 → 0.4.0

package/README.md

@@ -1,14 +1,16 @@
 # model-eol
 
 ![npm](https://img.shields.io/npm/v/model-eol)
+[![marketplace](https://img.shields.io/badge/marketplace-model--eol%20check-blue?logo=github)](https://github.com/marketplace/actions/model-eol-check)
 ![CI](https://github.com/thossullivan/model-eol/actions/workflows/ci.yml/badge.svg)
+[![feed refresh](https://github.com/thossullivan/model-eol/actions/workflows/feed-refresh.yml/badge.svg)](https://github.com/thossullivan/model-eol/actions/workflows/feed-refresh.yml)
 ![spec](https://img.shields.io/badge/spec-model--eol%2F0.1-blue)
 ![deps](https://img.shields.io/badge/runtime%20deps-zero-brightgreen)
 ![node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)
 ![license](https://img.shields.io/badge/license-MIT-blue)
 
 **A machine-readable deprecation feed format for AI models, plus the reference
-tooling that turns it into a Dependabot for models.** v0.2.3.
+tooling that turns it into a Dependabot for models.**
 
 ![model-eol demo: retired models, distributor clocks, worst-case date](docs/img/demo.gif)
 
@@ -31,14 +33,15 @@ second, so the existing trackers can converge instead of each scraping alone.
   replacement, `distributions` for per-channel lifecycles, and publisher `policy`
   floors. Small enough that a provider could serve it at
   `/.well-known/model-eol.json` in an afternoon.
-- **`feeds/`** - <!-- feeds-status -->Amazon (4 entries), Anthropic (29 entries), Google (64 entries) and OpenAI (194 entries), generated from the providers' live deprecation pages plus the AWS Bedrock lifecycle page, last verified 2026-08-03<!-- /feeds-status -->. Every
+- **`feeds/`** - <!-- feeds-status -->Amazon (4 entries), Anthropic (29 entries), Google (86 entries) and OpenAI (194 entries), generated from the providers' live deprecation pages plus the AWS Bedrock and Google Vertex AI lifecycle pages, feed data generated 2026-08-18<!-- /feeds-status -->. Every
   dated entry carries a source URL.
 - **`check.mjs`** - zero-dependency CLI: CI gate, PR diff gate, inventory, CycloneDX
   ML-BOM export, retirement schedule, alerts and badges, migration plan/apply.
 - **`refresh/`** - regenerates the feeds from provider pages, models endpoints, and
   distributor lifecycle pages, with a semantic diff for human review.
 - **`bot/`** - the Dependabot part: a cron GitHub workflow that maintains one
-  migration PR or issue per retiring model.
+  migration PR or issue per retiring model, published as the `model-eol-bot`
+  binary in the same npm package.
 - **`scripts/feed-changelog.mjs`** - the feeds' git history as Atom/markdown, so
   "model retirements as they are announced" is a feed you can subscribe to.
 
@@ -101,6 +104,11 @@ PRs to trigger checks), and provider API keys enter the picture in exactly two
 optional places: your own eval hook command, and the feed-refresh models-endpoint
 coverage.
 
+Both command-line binaries ship in one zero-dependency npm artifact. The test
+suite packs that artifact, installs it into an empty consumer directory with the
+network disabled, and runs both bins; it also fails if runtime, development,
+peer, or optional npm dependencies are introduced.
+
 ## Use it as a GitHub Action
 
 The same gate as a composite action - no npm install, feeds bundled, pinned to
@@ -122,9 +130,69 @@ That is the PR gate: fail only when *this* change adds a model that is retired
 or retiring within the threshold. Add `via: aws-bedrock` (or `azure-ai-foundry`)
 to judge by a distributor's clock. The copy-paste version with both gates - PR
 diff plus a weekly full-repository check - is
-[`examples/workflows/model-eol.yml`](examples/workflows/model-eol.yml); the
-same inputs drive `inventory` and `schedule` if CI should export an ML-BOM or a
-retirement calendar instead.
+[`examples/workflows/model-eol.yml`](examples/workflows/model-eol.yml). The
+Action also exposes `inventory`, `schedule`, `alert`, and `plan`. Use
+`format: cyclonedx` for an ML-BOM, or `output-file` to retain any report as a
+workflow artifact while keeping the same output in the job log.
+
+## One repository policy
+
+The CLI, Action, and bot all discover a strict `.model-eol.json` at the target
+Git repository root. CLI flags or Action inputs override configured values, and
+`--config FILE` selects an explicit policy when auto-discovery is ambiguous:
+
+```json
+{
+  "days": 90,
+  "scope": "direct",
+  "via": null,
+  "ignore": {
+    "models": ["o3-deep-research"],
+    "paths": ["test/fixtures/**", "vendor"]
+  },
+  "issues": { "enabled": true },
+  "eval": { "command": "npm test" }
+}
+```
+
+Unknown keys and invalid values fail closed. A canonical model ID or any alias
+in `ignore.models` suppresses the whole alias family; `ignore.paths` uses
+repo-relative `*`, `**`, and `?` globs and excludes matching files before scan
+coverage limits are counted. With no config the CLI keeps its historical
+`scope: all`; once a config exists, omitted values use the shared bot defaults
+(`days: 90`, `scope: direct`, and the publisher clock). The complete contract is
+[`schema/model-eol.bot-config.schema.json`](schema/model-eol.bot-config.schema.json).
+
+Mixed-provider monorepos can keep those top-level values as repository defaults,
+then apply path policies and a lifecycle channel per reference:
+
+```json
+{
+  "days": 90,
+  "scope": "direct",
+  "overrides": [
+    { "paths": ["services/**"], "scope": "all" },
+    { "paths": ["services/bedrock/**"], "days": 180, "via": "aws-bedrock" }
+  ],
+  "routes": [
+    { "paths": ["services/vertex/**"], "via": "vertex-ai" },
+    {
+      "paths": ["services/bedrock/**"],
+      "match": "chat-prod",
+      "model": "claude-3-7-sonnet-20250219",
+      "via": "aws-bedrock"
+    }
+  ]
+}
+```
+
+Matching overrides apply in order: later scalar values win and ignore lists are
+additive. The last matching route wins. Exact `match`/`model` pairs resolve a
+repository deployment alias without making cloud or gateway references patchable.
+Explicit CLI flags and Action inputs still take precedence. JSON inventory and
+plan output records each reference's effective threshold, scope, requested
+channel, and matching rule indexes, so a Bedrock service and a direct publisher
+call in the same repository do not silently share one global clock.
 
 ## Same weights, different clocks
 
@@ -133,9 +201,9 @@ this is wrong in both directions: o3-deep-research died at OpenAI on July 23 but
 lives on Azure AI Foundry until December 26; claude-opus-4-1 retires at Anthropic on
 August 5 but lives on Amazon Bedrock until January 8, 2027. `distributions` in the
 spec carries these per-channel clocks, `--via <distributor>` judges your repo by the
-channel you actually call, and the bedrock distributor fetcher keeps the clocks
-current from AWS's own lifecycle page. Treat a distributor's later date as runway
-for the same migration, not as a destination.
+channel you actually call, and the distributor refresh keeps Bedrock and Vertex
+clocks current from their lifecycle pages. Treat a distributor's later date as
+runway for the same migration, not as a destination.
 
 ## Policy floors - a planning floor from absence
 
@@ -166,33 +234,58 @@ stay visible without generating false alarms.
 The scanner covers code and configuration files with [`CODE_EXT`](lib/scanner.mjs)
 as the source of truth - Python, TypeScript/JavaScript, JSON/YAML/TOML, shell,
 Ruby, Go, Java, C#, Rust, C/C++, PHP, Swift, Kotlin, Terraform, SQL, Scala, and
-Objective-C. Terraform files (`.tf`, `.tfvars`) are scanned while `.terraform`
-directories stay excluded.
+Objective-C, including `.baml` sources. Publisher-compatible BAML provider/model
+pairs are eligible plan targets; generated BAML clients and conservative
+`DO NOT EDIT`/`@generated` sources are skipped. Model-eol's own JSON reports are
+also skipped on reruns, while third-party CycloneDX files remain scannable unless
+they carry explicit model-eol generator provenance. Terraform files (`.tf`,
+`.tfvars`) are scanned while `.terraform` directories stay excluded.
 
 ## The bot
 
 Copy `bot.yml.example` to `.github/workflows/model-eol-bot.yml` for a weekly run
 that maintains exactly one labelled migration PR per retiring model (full feed
 context in the body, never auto-merged) and one issue per finding that needs a
-human. Dismissals are respected; a changed shutdown date reopens. Configure via
-`.model-eol.json`: thresholds, scope, ignores, and an optional eval hook that runs
-your own regression command against the replacement before the PR opens. Preview
-everything with no GitHub calls:
+human. The workflow resolves `model-eol@0` from npm once and reuses that exact
+version across its plan, read-only evaluation, and write-token publication jobs;
+consumer repositories do not copy `check.mjs` or the `bot/` source directory.
+Dismissals are respected, reintroduced retired models create fresh work, and
+bot-owned PRs/issues close when their finding disappears. Preview everything with
+no GitHub calls and without adding a project dependency:
 
 ```sh
-node bot/bot.mjs --dry-run --target-dir . --repo OWNER/REPO
+npx --yes --package=model-eol@0 model-eol-bot --dry-run --target-dir . --repo OWNER/REPO
 ```
 
+The workflow honors configured `days`, `scope`, and `via` values; without a config
+it uses the bot defaults of 90 days and direct references. `eval.command` also
+comes from the config unless the `MODEL_EOL_EVAL_COMMAND` repository variable is
+set as an explicit workflow override. Each patchable model is applied in an
+isolated checkout and evaluated independently with its own old/new IDs, timeout,
+bounded report, and explicitly allowed environment. The content-bound result
+manifest is also pinned to the evaluated Git commit, letting passing migrations
+proceed while a failing peer remains blocked without publishing against a newer,
+unevaluated default branch.
+
+On its first actionable run, the bot creates the `model-eol` label. If repository
+policy prevents label creation or assignment, it fails closed rather than publish
+work whose ownership cannot be authenticated. Existing work is trusted only when
+the label, metadata, deterministic branch, repository, base, and Git lease agree.
+For HTTPS remotes—including private repositories—the bot passes `GITHUB_TOKEN` to
+temporary Git processes as a host-scoped authorization header and never places it
+in a remote URL.
+
 Two operational notes the hard way teaches: PRs created with `GITHUB_TOKEN` do not
 trigger `pull_request` workflows (use a fine-grained PAT or GitHub App token when
-checks must run), and the workflow splits privileges - provider keys live only in
-the read-only plan/eval job, write tokens only in the publish job.
+checks must run, stored as the optional `MODEL_EOL_BOT_TOKEN` secret), and the
+workflow splits privileges—provider keys live only in the read-only evaluation
+job, while write tokens live only in the reconciliation job.
 
 ## Keeping the feeds honest
 
 ```sh
 node refresh/refresh.mjs --check                      # semantic diff vs live pages; exit 3 = PR-worthy
-node refresh/refresh.mjs --distributor aws-bedrock    # distributor clocks from AWS's lifecycle page
+node refresh/refresh.mjs --distributor aws-bedrock,vertex-ai # distributor lifecycle clocks
 node scripts/feed-changelog.mjs                       # feeds' git history as an Atom feed
 ```
 
@@ -226,8 +319,9 @@ move any of us can make here.
 
 - Feeds refresh automatically: the weekly feed-refresh workflow is live in this
   repo (parse failures fail the run; material changes become a reviewed PR), and
-  CI runs the full suite on every push and PR. The bot workflow still ships as
-  `bot.yml.example`.
+  CI runs the full suite on every push and PR. The copy-ready bot workflow ships
+  as `bot.yml.example` and consumes the published package rather than local copies
+  of the tooling.
 - Current-model entries (and therefore policy-floor horizons) populate only when
   refresh runs with provider API keys for the models endpoints.
 - The checker matches known IDs only - it will not discover models absent from the
@@ -237,7 +331,8 @@ move any of us can make here.
   lifecycle fetcher is not built yet.
 - On npm as [`model-eol`](https://www.npmjs.com/package/model-eol). Material feed
   changes republish automatically as patch versions (trusted publishing with
-  provenance), so `npx model-eol` always checks against current dates.
+  provenance), while manual code releases require an explicit stable version, so
+  `npx model-eol` always checks against current dates.
 - Not yet: feed signing, gateway route resolvers.
 
 ## Contributing

package/action.yml

@@ -5,7 +5,7 @@ branding:
   color: 'red'
 inputs:
   command:
-    description: 'Command to run: check, inventory, or schedule'
+    description: 'Command to run: check, inventory, schedule, alert, or plan'
     required: false
     default: 'check'
   paths:
@@ -13,35 +13,56 @@ inputs:
     required: false
     default: '.'
   days:
-    description: 'Fail when a model retires within this many days'
+    description: 'Fail when a model retires within this many days (defaults to CLI or repository config)'
     required: false
-    default: '90'
+    default: ''
   via:
     description: 'Judge lifecycles by a distributor clock (e.g. azure-ai-foundry, aws-bedrock) instead of the publisher''s'
     required: false
     default: ''
   scope:
-    description: 'Check scope: all tracked model IDs, or direct to leave cloud/gateway refs as inventory hints'
+    description: 'Check scope: all tracked model IDs, or direct to leave cloud/gateway refs as inventory hints (defaults to CLI or repository config)'
     required: false
-    default: 'all'
+    default: ''
   changed:
     description: 'Base ref for the PR gate: check only lines added relative to this ref (requires fetch-depth: 0)'
     required: false
     default: ''
   format:
-    description: 'Alert output format when command is alert: github, markdown, or badge'
+    description: 'Output format: json, cyclonedx, or text for inventory; github, markdown, badge, or json for alert. Defaults to json for inventory and github for alert.'
     required: false
-    default: 'github'
+    default: ''
   feeds:
     description: 'Directory of model-eol feeds (defaults to the feeds bundled with the action)'
     required: false
     default: ''
+  config:
+    description: 'Path to a model-eol JSON config (defaults to repository config discovery)'
+    required: false
+    default: ''
+  include-docs:
+    description: 'Scan documentation files in addition to the default source and config files'
+    required: false
+    default: 'false'
+  allow-incomplete:
+    description: 'Allow check and plan to continue when scan coverage is incomplete'
+    required: false
+    default: 'false'
+  json:
+    description: 'Emit JSON for check, inventory, schedule, or alert'
+    required: false
+    default: 'false'
+  output-file:
+    description: 'Optional path that receives an exact copy of stdout while stdout remains visible in the Actions log'
+    required: false
+    default: ''
 runs:
   using: 'composite'
   steps:
     - name: model-eol check
       shell: bash
       env:
+        MODEL_EOL_ACTION_PATH: ${{ github.action_path }}
         MODEL_EOL_COMMAND: ${{ inputs.command }}
         MODEL_EOL_PATHS: ${{ inputs.paths }}
         MODEL_EOL_DAYS: ${{ inputs.days }}
@@ -50,7 +71,14 @@ runs:
         MODEL_EOL_SCOPE: ${{ inputs.scope }}
         MODEL_EOL_FORMAT: ${{ inputs.format }}
         MODEL_EOL_FEEDS: ${{ inputs.feeds }}
+        MODEL_EOL_CONFIG: ${{ inputs.config }}
+        MODEL_EOL_INCLUDE_DOCS: ${{ inputs['include-docs'] }}
+        MODEL_EOL_ALLOW_INCOMPLETE: ${{ inputs['allow-incomplete'] }}
+        MODEL_EOL_JSON: ${{ inputs.json }}
+        MODEL_EOL_OUTPUT_FILE: ${{ inputs['output-file'] }}
       run: |
+        set -euo pipefail
+
         split_model_eol_paths() {
           PATH_ARGS=()
           if [[ "$MODEL_EOL_PATHS" == *$'\n'* ]]; then
@@ -62,10 +90,97 @@ runs:
           fi
         }
         split_model_eol_paths
-        ARGS=("$MODEL_EOL_COMMAND" "${PATH_ARGS[@]}" --days "$MODEL_EOL_DAYS")
+
+        case "$MODEL_EOL_COMMAND" in
+          check|inventory|schedule|alert|plan) ;;
+          *)
+            echo "model-eol action: command must be check, inventory, schedule, alert, or plan" >&2
+            exit 2
+            ;;
+        esac
+        if [ -n "$MODEL_EOL_CHANGED" ] && [ "$MODEL_EOL_COMMAND" != 'check' ]; then
+          echo "model-eol action: changed is only supported by the check command" >&2
+          exit 2
+        fi
+        if [ -n "$MODEL_EOL_FORMAT" ] && [ "$MODEL_EOL_COMMAND" != 'inventory' ] && [ "$MODEL_EOL_COMMAND" != 'alert' ]; then
+          echo "model-eol action: format is only supported by the inventory and alert commands" >&2
+          exit 2
+        fi
+
+        ARGS=("$MODEL_EOL_COMMAND" "${PATH_ARGS[@]}")
+        if [ -n "$MODEL_EOL_DAYS" ]; then ARGS+=(--days "$MODEL_EOL_DAYS"); fi
         if [ -n "$MODEL_EOL_VIA" ]; then ARGS+=(--via "$MODEL_EOL_VIA"); fi
         if [ -n "$MODEL_EOL_CHANGED" ]; then ARGS+=(--changed "$MODEL_EOL_CHANGED"); fi
         if [ -n "$MODEL_EOL_SCOPE" ]; then ARGS+=(--scope "$MODEL_EOL_SCOPE"); fi
         if [ -n "$MODEL_EOL_FORMAT" ]; then ARGS+=(--format "$MODEL_EOL_FORMAT"); fi
         if [ -n "$MODEL_EOL_FEEDS" ]; then ARGS+=(--feeds "$MODEL_EOL_FEEDS"); fi
-        node "${{ github.action_path }}/check.mjs" "${ARGS[@]}"
+        if [ -n "$MODEL_EOL_CONFIG" ]; then ARGS+=(--config "$MODEL_EOL_CONFIG"); fi
+
+        append_boolean_flag() {
+          local value="$1"
+          local flag="$2"
+          local input_name="$3"
+          case "$value" in
+            true) ARGS+=("$flag") ;;
+            false|'') ;;
+            *)
+              echo "model-eol action: $input_name must be true or false" >&2
+              exit 2
+              ;;
+          esac
+        }
+        append_boolean_flag "$MODEL_EOL_INCLUDE_DOCS" --include-docs include-docs
+        case "$MODEL_EOL_ALLOW_INCOMPLETE" in
+          true)
+            if [ "$MODEL_EOL_COMMAND" != 'check' ] && [ "$MODEL_EOL_COMMAND" != 'plan' ]; then
+              echo "model-eol action: allow-incomplete is only supported by the check and plan commands" >&2
+              exit 2
+            fi
+            ARGS+=(--allow-incomplete)
+            ;;
+          false|'') ;;
+          *)
+            echo "model-eol action: allow-incomplete must be true or false" >&2
+            exit 2
+            ;;
+        esac
+        case "$MODEL_EOL_JSON" in
+          true)
+            if [ "$MODEL_EOL_COMMAND" = 'plan' ]; then
+              echo "model-eol action: json is only supported by the check, inventory, schedule, and alert commands" >&2
+              exit 2
+            fi
+            ARGS+=(--json)
+            ;;
+          false|'') ;;
+          *)
+            echo "model-eol action: json must be true or false" >&2
+            exit 2
+            ;;
+        esac
+
+        if [ -z "$MODEL_EOL_OUTPUT_FILE" ]; then
+          exec node "$MODEL_EOL_ACTION_PATH/check.mjs" "${ARGS[@]}"
+        fi
+        if [ -d "$MODEL_EOL_OUTPUT_FILE" ]; then
+          echo "model-eol action: output-file must name a file, not a directory" >&2
+          exit 2
+        fi
+
+        OUTPUT_TEMP="$(mktemp "${RUNNER_TEMP:-${TMPDIR:-/tmp}}/model-eol-output.XXXXXX")"
+        trap 'rm -f "$OUTPUT_TEMP"' EXIT
+        set +e
+        node "$MODEL_EOL_ACTION_PATH/check.mjs" "${ARGS[@]}" | tee "$OUTPUT_TEMP"
+        PIPE_STATUSES=("${PIPESTATUS[@]}")
+        CLI_STATUS="${PIPE_STATUSES[0]}"
+        TEE_STATUS="${PIPE_STATUSES[1]}"
+        COPY_STATUS=0
+        if [ "$TEE_STATUS" -eq 0 ]; then
+          cp -- "$OUTPUT_TEMP" "$MODEL_EOL_OUTPUT_FILE"
+          COPY_STATUS=$?
+        fi
+
+        FINAL_STATUS="$CLI_STATUS"
+        if [ "$FINAL_STATUS" -eq 0 ] && [ "$TEE_STATUS" -ne 0 ]; then FINAL_STATUS="$TEE_STATUS"; fi
+        if [ "$FINAL_STATUS" -eq 0 ] && [ "$COPY_STATUS" -ne 0 ]; then FINAL_STATUS="$COPY_STATUS"; fi
+        exit "$FINAL_STATUS"