model-eol 0.2.3 → 0.3.0

package/README.md

@@ -1,6 +1,7 @@
 # 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)
 ![spec](https://img.shields.io/badge/spec-model--eol%2F0.1-blue)
 ![deps](https://img.shields.io/badge/runtime%20deps-zero-brightgreen)
@@ -8,17 +9,18 @@
 ![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.2.
+tooling that turns it into a Dependabot for models.** v0.2.4.
 
 ![model-eol demo: retired models, distributor clocks, worst-case date](docs/img/demo.gif)
 
 ## The problem
 
-On July 23, 2026, OpenAI shut down 18 models on schedule. Teams that pinned dated
-snapshots - the provider's own recommended practice - got production 404s, because a
-model ID is the one dependency your toolchain can't see. When an npm package is
-deprecated, the warning prints at install, Dependabot opens the PR, the advisory
-fails CI. A model's retirement date lives in an HTML docs page and an email.
+On July 23, 2026, OpenAI shut down 15 model snapshots on schedule. One of my
+tuned research workflows returned a model-not-found error that morning even though
+the retirement had been documented for months. A model ID is the one dependency
+my toolchain could not see. When an npm package is deprecated, the warning prints
+at install, Dependabot opens the PR, and an advisory can fail CI. A model's
+retirement date usually lives in an HTML docs page and an email.
 
 Ordinary software solved this layer: endoflife.date for EOL data, OSV for
 vulnerability feeds. This is the model version - a shared schema first, tooling
@@ -30,14 +32,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 (64 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-03<!-- /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.
 
@@ -100,6 +103,65 @@ 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
+the `v0` line:
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0 # --changed needs history to diff against the base ref
+- uses: thossullivan/model-eol@v0
+  with:
+    command: check
+    changed: origin/${{ github.base_ref }}
+    days: 90
+    scope: direct
+```
+
+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
+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).
+
 ## Same weights, different clocks
 
 The same model retires on different dates per channel, and a checker that ignores
@@ -107,17 +169,17 @@ 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 forward guarantee from absence
+## Policy floors - a planning floor from absence
 
 A feed entry with no `announced` and no `shutdown` is an affirmative "nothing
 scheduled as of `generated`" - something scraping HTML can never say. Publishers
-with a stated minimum notice period (Anthropic commits to >=60 days) carry a
-`policy` floor, so the schedule can say `guaranteed until <date> per anthropic
-stated policy`. Stated policy, not a contract - the wording says so. OpenAI
+with a stated minimum notice period (Anthropic states >=60 days) carry a
+`policy` floor, so the schedule can calculate a no-earlier-than planning date
+from the feed refresh. Stated policy, not a contract. OpenAI
 publishes no formal floor, so its feed makes no forward claim.
 
 ## Direct-first inventory
@@ -148,25 +210,41 @@ directories stay excluded.
 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 runs `model-eol@0` from npm in both jobs; consumer repositories
+do not need to copy `check.mjs` or the `bot/` source directory. Dismissals are
+respected; a changed shutdown date reopens. Configure via `.model-eol.json`:
+thresholds, scope, ignores, and an optional plan-level eval hook that can inspect
+`MODEL_EOL_PLAN` before publication. 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. In the split workflow this command runs
+once in the unmodified, read-only checkout; it is a plan preflight, not a test of
+each patched migration branch.
+
+On its first actionable run, the bot creates the `model-eol` label. If repository
+policy prevents label creation or assignment, it warns and still publishes work;
+metadata in each PR or issue preserves idempotence. For HTTPS remotes—including
+private repositories—the bot passes `GITHUB_TOKEN` to its 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 plan/eval job,
+write tokens only in the publish 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
 ```
 
@@ -178,6 +256,14 @@ their keep: they caught the hand-compiled feeds drifting from Anthropic's
 recommendations within one week, and corrected a hand-compiled Bedrock date that
 was three months wrong.
 
+The refresh also travels in the other direction. On August 3, Google removed the
+previously listed October 16 earliest shutdown dates for the Gemini 2.5 Pro,
+Flash, and Flash-Lite GA models. The pipeline opened
+[a PR with the semantic retraction](https://github.com/thossullivan/model-eol/pull/60),
+and merging it published v0.2.3 so downstream checks stopped warning from dates
+Google no longer listed. A lifecycle tracker has to retract stale alarms as well
+as add new ones.
+
 ## The actual ask
 
 The endgame is not "another checker"; it's the format. Providers already publish
@@ -192,8 +278,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
@@ -203,7 +290,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"