model-eol 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Sullivan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# model-eol
+
+![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)
+![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.1.
+
+![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.
+
+Ordinary software solved this layer: endoflife.date for EOL data, OSV for
+vulnerability feeds. This is the model version - a shared schema first, tooling
+second, so the existing trackers can converge instead of each scraping alone.
+
+## What's here
+
+- **`SPEC.md`** - the feed format (model-eol/0.1): id, aliases, announced, shutdown,
+  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
+  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.
+- **`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.
+
+## Try it
+
+Two commands, no install, no dependencies:
+
+```sh
+git clone https://github.com/thossullivan/model-eol && cd model-eol
+node check.mjs path/to/your/repo --days 90
+```
+
+That is the whole CI gate. (`npx model-eol` lands with the npm publish.)
+
+<details>
+<summary><b>Every command</b> - PR gate, distributor clocks, SBOM, badges, migration plans</summary>
+
+```sh
+# PR gate: flag only lines THIS change adds relative to the base ref
+node check.mjs check . --changed origin/main --days 90
+# the same repo judged by a distributor's clock instead of the publisher's
+node check.mjs path/to/your/repo --via aws-bedrock
+# inventory, and a CycloneDX 1.6 ML-BOM for your SBOM pipeline
+node check.mjs inventory path/to/your/repo
+node check.mjs inventory path/to/your/repo --format cyclonedx > model-bom.json
+# retirement schedule with the repo-level worst case
+node check.mjs schedule path/to/your/repo
+# GitHub Actions annotations, Markdown, or a shields.io badge
+node check.mjs alert path/to/your/repo --format github
+node check.mjs alert path/to/your/repo --format badge > model-eol-badge.json
+# migration plan (only high-confidence direct API refs are patchable) and safe apply
+node check.mjs plan path/to/your/repo --days 90 > plan.json
+node check.mjs apply --plan plan.json --dry-run
+```
+
+</details>
+
+Sample output against the test fixture (2026-08-01):
+
+```
+✗ app.py:2  o3-deep-research          RETIRED 2026-07-23 (9 days ago) -> gpt-5.6-sol
+! app.py:3  claude-opus-4-1-20250805  RETIRES 2026-08-05 (4 days) -> claude-opus-4-8
+· app.py:4  gpt-5.6-sol               no retirement scheduled
+earliest risk: 2026-07-23 (o3-deep-research-2025-06-26)
+```
+
+Exit 1 on findings at or past the threshold - wire it into CI as-is. The badge JSON
+plugs into the [shields endpoint](https://shields.io/endpoint) from any
+CI-accessible URL.
+
+**No API keys, no accounts.** Scanning is static analysis and the feeds are data
+files, so the checker, PR gate, schedule, SBOM export, and badge all run with zero
+credentials. The bot needs only a GitHub token (a fine-grained PAT if you want its
+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.
+
+## Same weights, different clocks
+
+The same model retires on different dates per channel, and a checker that ignores
+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.
+
+## Policy floors - a forward guarantee 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
+publishes no formal floor, so its feed makes no forward claim.
+
+## Direct-first inventory
+
+Direct API usage (OpenAI/Anthropic/Gemini/etc. SDK calls with real model IDs) is
+scanned and checked immediately. Cloud providers and gateways - Azure Foundry,
+Bedrock, Vertex, OpenRouter, LiteLLM, Portkey - often hide the model behind
+deployment names or routing aliases, so those references stay in inventory as
+resolver targets instead of pretending static code knows the deployed model:
+
+```
+? src/ai.ts:12  azure-ai-foundry  Azure Foundry/OpenAI deployment reference
+? src/ai.ts:30  openrouter        OpenRouter gateway reference
+```
+
+Use `--scope direct` to fail CI only on what static analysis can prove. Model-like
+strings absent from the feeds surface as non-failing **candidates**, so feed gaps
+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.
+
+## 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:
+
+```sh
+node bot/bot.mjs --dry-run --target-dir . --repo OWNER/REPO
+```
+
+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.
+
+## 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 scripts/feed-changelog.mjs                       # feeds' git history as an Atom feed
+```
+
+Parse failures fail loudly and never emit a guessed feed. This runs automatically:
+a weekly workflow (`.github/workflows/feed-refresh.yml`, Mondays 05:23 UTC) checks
+the live sources and opens a PR with the semantic diff - and an auto-updated
+README freshness line - when anything material changed. The first live runs earned
+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 actual ask
+
+The endgame is not "another checker"; it's the format. Providers already publish
+deprecation *pages* because customers asked. A `retirement_date` field in the models
+endpoint, or this feed at a well-known URL, turns every existing tracker into an
+ecosystem. endoflife.date now tracks Claude with nearly this field set - the
+convergence is already starting. If you maintain one of the community trackers:
+converging on a shared schema - this one or a better one - is the highest-leverage
+move any of us can make here.
+
+## Status / honesty
+
+- 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`.
+- 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
+  feeds. Deliberate: precision over discovery for a CI gate.
+- Fetchers: OpenAI, Anthropic, Google, aws-bedrock, and vertex-ai are live. Azure
+  clocks are carried where OpenAI's own page publishes them; a standalone Azure
+  lifecycle fetcher is not built yet.
+- Not yet: feed signing, gateway route resolvers, npm publish (prepped, pending).
+
+## Contributing
+
+The most valuable contribution is a feed correction with a source URL - and the
+one rule is that `feeds/*.json` are generated, never hand-edited. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for that workflow, the zero-dependency
+doctrine, and what a new publisher parser needs.

package/SPEC.md

@@ -0,0 +1,134 @@
+# model-eol - a machine-readable model deprecation feed (draft spec v0.1)
+
+> Status: sketch, 2026-07-25. The problem: model retirement dates live in HTML docs
+> and emails, so every deprecation checker is a scraper with a private registry
+> format. Ordinary software solved this layer - endoflife.date for EOL data, OSV for
+> vulnerability feeds. This is the model version: small enough that a provider could
+> ship it in an afternoon, useful enough that scrapers converge on it in the meantime.
+
+## The format
+
+A feed is a JSON document: metadata + a list of model entries.
+
+```json
+{
+  "spec": "model-eol/0.1",
+  "publisher": "openai",
+  "generated": "2026-07-25T00:00:00Z",
+  "source": "https://developers.openai.com/api/docs/deprecations",
+  "models": [
+    {
+      "id": "o3-deep-research-2025-06-26",
+      "aliases": ["o3-deep-research"],
+      "announced": "2026-04-22",
+      "shutdown": "2026-07-23",
+      "replacement": "gpt-5.6-sol",
+      "notes": "Deep-research post-trained agent; replacement is a general model + tools, not a structural successor.",
+      "distributions": [
+        { "via": "azure-ai-foundry", "shutdown": "2026-12-26",
+          "source": "https://learn.microsoft.com/en-us/azure/ai-foundry/openai/concepts/model-retirements" }
+      ]
+    },
+    {
+      "id": "gpt-5.6-sol"
+    }
+  ]
+}
+```
+
+### Fields
+
+| Field | Req | Meaning |
+|---|---|---|
+| `id` | yes | The exact model identifier as sent over the wire (dated snapshot preferred) |
+| `aliases` | no | Other strings that resolve to this model (undated aliases, marketing names) |
+| `announced` | no | Date the deprecation was announced (absent = not deprecated) |
+| `shutdown` | no | Date calls stop working on the publisher's own API (absent = none scheduled) |
+| `replacement` | no | A single exact model ID that resolves against an id or alias in this feed and is safe as a drop-in string substitution. This is the only field plan/apply may patch from |
+| `replacement_options` | no | An ordered array of exact model IDs for multiple or unresolved choices. These are issue-only and need not resolve in this feed |
+| `replacement_note` | no | Free-text guidance such as parameter requirements or provider platform alternatives |
+| `notes` | no | Human context: structural differences, migration gotchas |
+| `distributions` | no | Per-distributor lifecycles - the same weights on different clocks (Azure, Bedrock, Vertex). Each entry: `via`, optional `announced`/`shutdown`/`status`/`date_precision`, `source` |
+| `date_precision` | no | Qualifies `shutdown`: absent or `"exact"` means the stated day; `"earliest"` means the provider commits only that the event happens no sooner (Google's "earliest possible" dates). Consumers treat an earliest date as the scheduled date - it is the soonest legal death - and display it as a lower bound |
+
+Dates are ISO 8601, UTC. A model with no `announced` and no `shutdown` is an
+affirmative statement of "no retirement scheduled as of `generated`" - the absence
+is data, which is exactly what scraping HTML can never give you.
+
+`distributions[].status`, when present, is one of `active`, `legacy`,
+`extended-access`, or `retired`. `legacy` means no new consumers but existing
+usage works; `extended-access` means availability continues past the stated
+`shutdown` under a paid or opt-in program (Bedrock offers this for some models) -
+the `shutdown` date stays the base retirement, and the status flags that a
+negotiated tail exists.
+
+### Structured replacement contract
+
+`replacement` is a single exact model ID that resolves against an id or alias in
+the same feed and is safe as a drop-in string substitution. This is the ONLY
+field plan/apply may patch from. Otherwise absent.
+
+`replacement_options` is an optional array of exact model IDs. Each option must
+pass the identifier grammar, but feed resolution is NOT required since a target
+may not be carried yet. Options are ordered as the provider lists them.
+
+`replacement_note` is optional free-text guidance. It can carry parameter
+requirements such as `reasoning.mode: pro` or prose alternatives such as Google's
+platform pointers.
+
+Replacement options and notes are issue-only. The planner never auto-patches
+from options; it patches `replacement` exclusively.
+
+### Policy floors
+
+A feed MAY include a publisher's stated minimum deprecation notice period:
+
+```json
+"policy": {
+  "min_notice_days": 60,
+  "source": "https://platform.claude.com/docs/en/about-claude/model-deprecations"
+}
+```
+
+For an entry with neither `announced` nor `shutdown`, a policy floor means the
+entry cannot become unavailable before `generated` + `min_notice_days` days,
+provided the provider honors its stated policy. This is a stated policy, not a
+contract or a guarantee that the provider will remain available.
+
+The `policy` field is optional. Its absence means no forward claim can be made,
+intentionally. OpenAI publishes no formal notice floor, so the OpenAI feed carries
+no `policy` field.
+
+### Why `distributions` is in the core and not an extension
+
+The July 2026 evidence: OpenAI shut off `o3-deep-research` on July 23; Azure lists it
+retiring December 26. Anthropic retired Claude 3.7 Sonnet on February 19; Bedrock
+kept it to April 28. The same BOM entry has different sourcing terms per channel, and
+a checker that doesn't know that will tell an Azure shop their model is dead five
+months early - or tell an OpenAI-direct shop they're fine because Azure says so.
+
+## Serving it
+
+- **Providers** (the ask): serve the feed at `/.well-known/model-eol.json`, or add
+  `announced`/`shutdown`/`replacement` to the existing models endpoint. Either kills
+  the scraping industry overnight.
+- **Aggregators** (the interim): community datasets re-publish provider pages in this
+  format, with `source` on every entry so claims are auditable. Multiple feeds
+  compose - a checker loads provider feeds where they exist and community feeds where
+  they don't.
+- **Consumers**: anything that can read JSON - a CI step, a dashboard, a Dependabot
+  clone that opens migration PRs when `shutdown - today < threshold`.
+
+## Non-goals (v0.1)
+
+Pricing, capabilities, context windows (models.dev and friends already do this);
+behavior-change tracking (that's an eval suite's job, not a manifest's); signing and
+provenance (worth doing the moment anyone depends on this; premature today).
+
+## Prior art, gratefully
+
+endoflife.date (the shape of the solution), OSV (proof that a shared schema turns N
+scrapers into an ecosystem), CycloneDX ML-BOM / SPDX AI profile (where an `eol` field
+belongs once feeds exist), and the current scrapers - llm-model-deprecation,
+llmstatus.ai, llm-info, ai-model-watch-data, modelradar-data - which are the demand
+signal this spec is trying to give a common target.

package/action.yml

@@ -0,0 +1,71 @@
+name: 'model-eol check'
+description: 'Fail CI when a pinned AI model ID is retired or retiring within a threshold, using model-eol feeds.'
+branding:
+  icon: 'alert-triangle'
+  color: 'red'
+inputs:
+  command:
+    description: 'Command to run: check, inventory, or schedule'
+    required: false
+    default: 'check'
+  paths:
+    description: 'Paths to scan. Newline-separated paths are recommended for paths containing spaces; single-line whitespace-separated paths remain supported for legacy compatibility.'
+    required: false
+    default: '.'
+  days:
+    description: 'Fail when a model retires within this many days'
+    required: false
+    default: '90'
+  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'
+    required: false
+    default: 'all'
+  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'
+    required: false
+    default: 'github'
+  feeds:
+    description: 'Directory of model-eol feeds (defaults to the feeds bundled with the action)'
+    required: false
+    default: ''
+runs:
+  using: 'composite'
+  steps:
+    - name: model-eol check
+      shell: bash
+      env:
+        MODEL_EOL_COMMAND: ${{ inputs.command }}
+        MODEL_EOL_PATHS: ${{ inputs.paths }}
+        MODEL_EOL_DAYS: ${{ inputs.days }}
+        MODEL_EOL_VIA: ${{ inputs.via }}
+        MODEL_EOL_CHANGED: ${{ inputs.changed }}
+        MODEL_EOL_SCOPE: ${{ inputs.scope }}
+        MODEL_EOL_FORMAT: ${{ inputs.format }}
+        MODEL_EOL_FEEDS: ${{ inputs.feeds }}
+      run: |
+        split_model_eol_paths() {
+          PATH_ARGS=()
+          if [[ "$MODEL_EOL_PATHS" == *$'\n'* ]]; then
+            while IFS= read -r path || [[ -n "$path" ]]; do
+              if [[ -n "$path" ]]; then PATH_ARGS+=("$path"); fi
+            done <<< "$MODEL_EOL_PATHS"
+          else
+            read -r -a PATH_ARGS <<< "$MODEL_EOL_PATHS"
+          fi
+        }
+        split_model_eol_paths
+        ARGS=("$MODEL_EOL_COMMAND" "${PATH_ARGS[@]}" --days "$MODEL_EOL_DAYS")
+        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[@]}"