model-eol 0.4.1 → 0.5.0

package/bot/lib/git.mjs

@@ -105,6 +105,55 @@ export const verifyBotBranch = (cwd, branch, expectedHead, auth = null) => {
   }
 }
 
+export const verifyRemoteBranchHead = (cwd, branch, expectedHead, auth = null) => {
+  try {
+    run(cwd, ['fetch', 'origin', '--prune'], false, auth)
+  } catch (error) {
+    return { head: null, safe: false, error: error.message }
+  }
+  const head = run(cwd, ['rev-parse', '--verify', `refs/remotes/origin/${branch}`], true)
+  return {
+    head,
+    safe: head === expectedHead,
+    error: null,
+  }
+}
+
+const exactObjectId = value => typeof value === 'string' && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i.test(value)
+
+const requireExactObjectId = (value, name) => {
+  if (!exactObjectId(value)) throw new Error(`refusing remote branch mutation without an exact ${name} commit`)
+}
+
+export const isCommitAvailable = (cwd, head) => exactObjectId(head)
+  && run(cwd, ['cat-file', '-e', `${head}^{commit}`], true) !== null
+
+export const deleteRemoteBranch = (cwd, branch, expectedHead, auth = null) => {
+  requireExactObjectId(expectedHead, 'expected')
+  const ref = `refs/heads/${branch}`
+  run(cwd, [
+    'push',
+    `--force-with-lease=${ref}:${expectedHead}`,
+    'origin',
+    `:${ref}`,
+  ], false, auth)
+}
+
+export const restoreRemoteBranch = (cwd, branch, expectedCurrentHead, restoreHead, auth = null) => {
+  requireExactObjectId(expectedCurrentHead, 'current')
+  requireExactObjectId(restoreHead, 'restore')
+  if (!isCommitAvailable(cwd, restoreHead)) {
+    throw new Error(`refusing remote branch rollback because restore commit ${restoreHead} is unavailable`)
+  }
+  const ref = `refs/heads/${branch}`
+  run(cwd, [
+    'push',
+    `--force-with-lease=${ref}:${expectedCurrentHead}`,
+    'origin',
+    `${restoreHead}:${ref}`,
+  ], false, auth)
+}
+
 export const pushBranch = (cwd, branch, expectedHead = null, auth = null, { allowMissing = false } = {}) => {
   const destination = `HEAD:refs/heads/${branch}`
   if (expectedHead !== null) {

package/bot/lib/github.mjs

@@ -149,6 +149,10 @@ export class GitHubClient {
     return data
   }
 
+  async getPull(number) {
+    return (await this.request('GET', `/repos/${this.repo}/pulls/${number}`)).data
+  }
+
   async listIssues() {
     const issues = await this.listAll(`/repos/${this.repo}/issues`)
     return issues.filter(issue => !issue.pull_request)

package/bot.yml.example

@@ -36,9 +36,12 @@ jobs:
             exit 1
           fi
           printf '%s\n' "$MODEL_EOL_VERSION" > "$RUNNER_TEMP/model-eol-plan/model-eol-version"
-          PLAN_ARGS=(plan .)
-          if [ ! -f .model-eol.json ]; then PLAN_ARGS+=(--days 90 --scope direct); fi
-          npx --yes --package="model-eol@$MODEL_EOL_VERSION" model-eol "${PLAN_ARGS[@]}" > "$RUNNER_TEMP/model-eol-plan/model-eol-plan.json"
+          # Resolve npx outside the consumer checkout so a repository whose own
+          # package is named model-eol cannot shadow the requested published bin.
+          cd "$RUNNER_TEMP/model-eol-plan"
+          npx --yes --package="model-eol@$MODEL_EOL_VERSION" \
+            -c 'cd "$GITHUB_WORKSPACE" && if [ -f .model-eol.json ]; then model-eol plan .; else model-eol plan . --days 90 --scope direct; fi' \
+            > "$RUNNER_TEMP/model-eol-plan/model-eol-plan.json"
       - name: Upload plan
         uses: actions/upload-artifact@v7
         with:
@@ -55,8 +58,9 @@ jobs:
     permissions:
       contents: read
     steps:
-      # Provider credentials exist only in this read-only job. The evaluator
-      # forwards only names explicitly allowed by eval.pass_env.
+      # Add only the provider secrets required by trusted default-branch eval
+      # code, and list the same names in eval.pass_env. Environment filtering is
+      # not an OS sandbox; this job's hard boundary is that it has no write token.
       - uses: actions/checkout@v7
         with:
           persist-credentials: false
@@ -71,10 +75,8 @@ jobs:
           path: ${{ runner.temp }}/model-eol-plan
       - name: Apply and evaluate each migration independently
         env:
-          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
-          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-          GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
-          GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
+          # Example (opt in only when needed by eval.pass_env):
+          # OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
           # A non-empty repository variable overrides eval.command. Otherwise
           # the strictly validated command in .model-eol.json is used.
           MODEL_EOL_EVAL_COMMAND: ${{ vars.MODEL_EOL_EVAL_COMMAND }}
@@ -85,8 +87,9 @@ jobs:
             echo "refusing invalid resolved model-eol version: $MODEL_EOL_VERSION" >&2
             exit 1
           fi
+          cd "$RUNNER_TEMP/model-eol-eval"
           npx --yes --package="model-eol@$MODEL_EOL_VERSION" model-eol-bot evaluate \
-            --target-dir . \
+            --target-dir "$GITHUB_WORKSPACE" \
             --plan-file "$RUNNER_TEMP/model-eol-plan/model-eol-plan.json" \
             --output-file "$RUNNER_TEMP/model-eol-eval/model-eol-eval-results.json"
       - name: Upload bounded eval results
@@ -134,15 +137,21 @@ jobs:
           MODEL_EOL_EVAL_COMMAND: ${{ vars.MODEL_EOL_EVAL_COMMAND }}
           MODEL_EOL_TOKEN_KIND: ${{ secrets.MODEL_EOL_BOT_TOKEN && 'external-token' || 'github-token' }}
         run: |
+          mkdir -p "$RUNNER_TEMP/model-eol-publish"
           MODEL_EOL_VERSION="$(cat "$RUNNER_TEMP/model-eol-plan/model-eol-version")"
           if [[ ! "$MODEL_EOL_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
             echo "refusing invalid resolved model-eol version: $MODEL_EOL_VERSION" >&2
             exit 1
           fi
-          npx --yes --package="model-eol@$MODEL_EOL_VERSION" model-eol-bot --repo "${{ github.repository }}" --target-dir .
+          cd "$RUNNER_TEMP/model-eol-publish"
+          npx --yes --package="model-eol@$MODEL_EOL_VERSION" model-eol-bot \
+            --repo "${{ github.repository }}" \
+            --target-dir "$GITHUB_WORKSPACE"
 
 # A PR made with GITHUB_TOKEN does not trigger pull_request workflows. For
 # required checks, store a narrowly scoped fine-grained PAT or GitHub App token
 # as MODEL_EOL_BOT_TOKEN. Keep provider keys out of the publish job.
+# For migration evidence, copy examples/model-eol-eval.mjs into the consumer,
+# customize its dedicated eval command, and set eval.command in .model-eol.json.
 # Set feeds.allow_vendored_fallback: true only for degraded report-only runs.
 # Independent concurrent invocations need external mutual exclusion.

package/check.mjs

@@ -10,9 +10,11 @@
 //   node check.mjs alert [paths...] [--format github|markdown|badge] [--json]
 //   node check.mjs plan [paths...] [--days N] [--scope all|direct] [--via DISTRIBUTOR] [--feeds DIR]
 //   node check.mjs apply --plan plan.json [--dry-run]
+//   node check.mjs validate document.json [...] [--type feed|config|check|inventory|schedule|alert|plan]
 //
 // exit codes: check/alert 0 = clear, 1 = finding, 2 = usage error;
-// apply 0 = all items applied, 1 = item refused, 2 = usage or plan error.
+// apply 0 = all items applied, 1 = item refused, 2 = usage or plan error;
+// validate 0 = every document valid, 2 = usage, parse, schema, or semantic error.
 
 import fs from 'node:fs'
 import path from 'node:path'
@@ -45,6 +47,7 @@ import {
   formatSchedule,
 } from './lib/reports.mjs'
 import { addedLinesForTargets, filterFindingsToChanged, gitRootFor, incompleteScanNotes, scanTargets } from './lib/scanner.mjs'
+import { DOCUMENT_TYPES, formatDocumentErrors, validateDocumentFile } from './lib/validate-document.mjs'
 
 const rootForTarget = target => {
   const absolute = path.resolve(target)
@@ -93,7 +96,7 @@ const repoPathForFile = (file, roots) => {
 }
 
 const main = () => {
-const COMMANDS = new Set(['check', 'inventory', 'schedule', 'alert', 'plan', 'apply', 'help'])
+const COMMANDS = new Set(['check', 'inventory', 'schedule', 'alert', 'plan', 'apply', 'validate', 'help'])
 const args = process.argv.slice(2)
 
 if (args[0] === '--help' || args[0] === '-h') args[0] = 'help'
@@ -115,6 +118,7 @@ try {
       'allow-incomplete': { type: 'boolean' },
       'dry-run': { type: 'boolean' },
       changed: { type: 'string' },
+      type: { type: 'string' },
       help: { type: 'boolean', short: 'h' },
     },
     allowPositionals: true,
@@ -148,6 +152,7 @@ Usage:
   node check.mjs alert [paths...] [--config FILE] [--days N] [--scope all|direct] [--format github|markdown|badge] [--json]
   node check.mjs plan [paths...] [--config FILE] [--days N] [--scope all|direct] [--via DISTRIBUTOR] [--feeds DIR] [--allow-incomplete]
   node check.mjs apply --plan plan.json [--dry-run]
+  node check.mjs validate document.json [...] [--type feed|config|check|inventory|schedule|alert|plan]
 
 Commands:
   check       Fail when tracked model IDs are retired or retiring within --days.
@@ -159,6 +164,8 @@ Commands:
   alert       Emit GitHub Actions annotations, Markdown, or a Shields badge JSON and fail on errors.
   plan        Emit a JSON migration plan with only safely patchable direct API references.
   apply       Apply a plan with line-hash and occurrence checks; use --dry-run to preview.
+  validate    Validate a feed, config, check, inventory, schedule, alert, or plan document.
+              The type is inferred from its discriminator or .model-eol.json filename unless --type is set.
 
 Scopes:
   all        Check every tracked model ID found. This preserves the original behavior.
@@ -171,12 +178,21 @@ Configuration:
 Exit codes:
   0  Clean, or report generated successfully.
   1  Findings, alert errors, or refused apply items.
-  2  Usage, feed, scan, or plan errors.
+  2  Usage, feed, scan, plan, or validation errors.
   3  Output stream failure other than EPIPE.
 `)
   return 0
 }
 
+if (positionals.some(value => value.length === 0)) {
+  console.error('positional paths must be non-empty')
+  return 2
+}
+if (values.via === '') {
+  console.error('--via must be a non-empty lifecycle channel')
+  return 2
+}
+
 if (command === 'apply') {
   if (!PLAN_FILE || positionals.length) {
     console.error('apply requires --plan plan.json and accepts no target paths')
@@ -191,6 +207,41 @@ if (command === 'apply') {
   }
 }
 
+if (command === 'validate') {
+  const allowedOptions = new Set(['type'])
+  const unsupported = Object.keys(values).find(option => !allowedOptions.has(option))
+  if (positionals.length === 0 || unsupported) {
+    const detail = unsupported ? `; --${unsupported} is not supported by validate` : ''
+    console.error(`validate requires one or more JSON documents${detail}`)
+    return 2
+  }
+  if (values.type !== undefined && !DOCUMENT_TYPES.includes(values.type) && values.type !== 'bot-config' && values.type !== 'model-eol-config') {
+    console.error(`unknown document type ${JSON.stringify(values.type)}; expected ${DOCUMENT_TYPES.join(', ')}`)
+    return 2
+  }
+  let failed = false
+  for (const file of positionals) {
+    try {
+      const result = validateDocumentFile(file, { type: values.type ?? null })
+      if (result.errors.length) {
+        for (const error of formatDocumentErrors(result.errors)) console.error(`${file}: ${error}`)
+        failed = true
+        continue
+      }
+      console.log(`${file}: valid ${result.type} document`)
+    } catch (error) {
+      console.error(`${file}: validation failed: ${error.message}`)
+      failed = true
+    }
+  }
+  return failed ? 2 : 0
+}
+
+if (values.type !== undefined) {
+  console.error('--type is only supported by the validate command')
+  return 2
+}
+
 let configLocation
 let repositoryConfig
 try {
@@ -355,7 +406,7 @@ if (command === 'plan') {
 
 if (command === 'check') {
   if (AS_JSON) {
-    console.log(JSON.stringify({ threshold_days: DAYS, distributor: VIA, scope: SCOPE, scan_notes: scan.notes, findings: changedFindings }, null, 2))
+    console.log(JSON.stringify({ schema: 'model-eol/check@0.1', threshold_days: DAYS, distributor: VIA, scope: SCOPE, scan_notes: scan.notes, findings: changedFindings }, null, 2))
   } else {
     console.log(formatCheck({ findings: changedFindings, bad, scannedFiles: scan.files.length, days: DAYS, scope: SCOPE }))
   }

package/examples/model-eol-eval.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+// Copy this file into the consuming repository and replace VERIFY with the
+// smallest command that proves the model-dependent behavior you rely on.
+// model-eol runs it from an isolated checkout after applying one migration.
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+
+const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+const VERIFY = Object.freeze({ command: npm, args: ['run', 'eval:model-eol'] })
+
+const required = name => {
+  const value = process.env[name]
+  if (!value) throw new Error(`${name} is required`)
+  return value
+}
+
+const singleLine = value => String(value).replace(/[\r\n]+/g, ' ').trim()
+
+let reportPath = process.env.MODEL_EOL_REPORT || null
+let exitCode = 1
+const report = ['## Repository migration eval', '']
+
+try {
+  const oldId = required('MODEL_EOL_OLD_ID')
+  const newId = required('MODEL_EOL_NEW_ID')
+  const planPath = required('MODEL_EOL_PLAN')
+  reportPath = required('MODEL_EOL_REPORT')
+  const plan = JSON.parse(fs.readFileSync(planPath, 'utf8'))
+  if (plan.plan_schema !== 'model-eol.plan/0.1' || !Array.isArray(plan.items) || plan.items.length === 0) {
+    throw new Error('MODEL_EOL_PLAN is not a non-empty model-eol plan')
+  }
+  if (plan.items.some(item => item.id !== oldId || item.replacement !== newId)) {
+    throw new Error('MODEL_EOL_PLAN contains a migration outside MODEL_EOL_OLD_ID/MODEL_EOL_NEW_ID')
+  }
+
+  const files = [...new Set(plan.items.map(item => item.file))].sort()
+  report.push(
+    `- Migration: \`${singleLine(oldId)}\` to \`${singleLine(newId)}\``,
+    `- Planned references: ${plan.items.length} across ${files.length} file(s)`,
+    `- Verification: \`${VERIFY.command} ${VERIFY.args.join(' ')}\``,
+  )
+
+  const started = Date.now()
+  const result = spawnSync(VERIFY.command, VERIFY.args, {
+    cwd: process.cwd(),
+    env: process.env,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    maxBuffer: 8 * 1024 * 1024,
+  })
+  const elapsedMs = Date.now() - started
+  const passed = !result.error && result.status === 0
+  report.push(
+    `- Result: ${passed ? 'pass' : 'fail'}`,
+    `- Exit code: ${Number.isInteger(result.status) ? result.status : 'unavailable'}`,
+    `- Duration: ${elapsedMs} ms`,
+  )
+  if (result.signal) report.push(`- Signal: ${singleLine(result.signal)}`)
+  if (result.error) report.push(`- Runner error: ${singleLine(result.error.message)}`)
+  report.push('', passed
+    ? 'The repository verification command passed in the isolated patched checkout.'
+    : 'The repository verification command failed. Reproduce it locally for full logs; command output is intentionally not copied into the publishable report.')
+  exitCode = passed ? 0 : 1
+} catch (error) {
+  report.push(`- Result: fail`, '', `Harness error: ${singleLine(error.message)}`)
+  exitCode = 1
+} finally {
+  if (reportPath) {
+    try {
+      fs.mkdirSync(path.dirname(path.resolve(reportPath)), { recursive: true })
+      fs.writeFileSync(reportPath, `${report.join('\n')}\n`, { encoding: 'utf8', mode: 0o600 })
+    } catch (error) {
+      console.error(`could not write MODEL_EOL_REPORT: ${error.message}`)
+      exitCode = 1
+    }
+  } else {
+    console.error('MODEL_EOL_REPORT is required')
+  }
+}
+
+process.exitCode = exitCode

package/examples/workflows/model-eol.yml

@@ -0,0 +1,52 @@
+# model-eol - copy this file to .github/workflows/model-eol.yml in YOUR repo.
+#
+# Two gates:
+#   - every PR: fail only if THIS change adds a model that is retired or
+#     retiring within the threshold (existing references stay out of the way)
+#   - weekly: full-repository check, so legacy references surface on a schedule
+#     instead of in an outage
+#
+# Judged by a distributor's clock instead? Add `via: aws-bedrock` (or
+# azure-ai-foundry) to the step's `with:` block.
+
+name: model-eol
+
+on:
+  pull_request:
+  schedule:
+    - cron: '17 6 * * 1' # weekly, Monday 06:17 UTC
+
+jobs:
+  pr-gate:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # --changed needs history to diff against the base ref
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          package-manager-cache: false
+      - uses: thossullivan/model-eol@v0
+        with:
+          command: check
+          changed: origin/${{ github.base_ref }}
+          days: 90
+          scope: direct
+
+  weekly-full-check:
+    if: github.event_name == 'schedule'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          package-manager-cache: false
+      - uses: thossullivan/model-eol@v0
+        with:
+          command: alert
+          days: 90
+          scope: direct
+          format: github

package/feeds/amazon.json

@@ -1,7 +1,7 @@
 {
   "spec": "model-eol/0.1",
   "publisher": "amazon",
-  "generated": "2026-08-18T00:47:44.931Z",
+  "generated": "2026-08-18T12:06:03.442Z",
   "source": "https://docs.aws.amazon.com/bedrock/latest/userguide/model-lifecycle.html",
   "models": [
     {
@@ -14,6 +14,7 @@
           "via": "aws-bedrock",
           "announced": "2026-03-30",
           "shutdown": "2026-09-30",
+          "status": "legacy",
           "source": "https://docs.aws.amazon.com/bedrock/latest/userguide/model-lifecycle.html"
         }
       ]
@@ -28,6 +29,7 @@
           "via": "aws-bedrock",
           "announced": "2026-03-30",
           "shutdown": "2026-09-30",
+          "status": "legacy",
           "source": "https://docs.aws.amazon.com/bedrock/latest/userguide/model-lifecycle.html"
         }
       ]
@@ -42,6 +44,7 @@
           "via": "aws-bedrock",
           "announced": "2026-03-13",
           "shutdown": "2026-09-14",
+          "status": "legacy",
           "source": "https://docs.aws.amazon.com/bedrock/latest/userguide/model-lifecycle.html"
         }
       ]
@@ -56,6 +59,7 @@
           "via": "aws-bedrock",
           "announced": "2026-03-13",
           "shutdown": "2026-09-14",
+          "status": "legacy",
           "source": "https://docs.aws.amazon.com/bedrock/latest/userguide/model-lifecycle.html"
         }
       ]

package/feeds/anthropic.json

@@ -1,7 +1,7 @@
 {
   "spec": "model-eol/0.1",
   "publisher": "anthropic",
-  "generated": "2026-08-18T00:47:44.931Z",
+  "generated": "2026-08-18T12:06:03.442Z",
   "source": "https://platform.claude.com/docs/en/about-claude/model-deprecations",
   "policy": {
     "min_notice_days": 60,
@@ -45,6 +45,7 @@
           "via": "aws-bedrock",
           "announced": "2026-03-10",
           "shutdown": "2026-09-10",
+          "status": "extended-access",
           "source": "https://docs.aws.amazon.com/bedrock/latest/userguide/model-lifecycle.html"
         }
       ],
@@ -74,6 +75,7 @@
           "via": "aws-bedrock",
           "announced": "2026-04-14",
           "shutdown": "2026-10-14",
+          "status": "extended-access",
           "source": "https://docs.aws.amazon.com/bedrock/latest/userguide/model-lifecycle.html"
         }
       ],
@@ -103,6 +105,7 @@
           "via": "aws-bedrock",
           "announced": "2026-07-08",
           "shutdown": "2027-01-08",
+          "status": "extended-access",
           "source": "https://docs.aws.amazon.com/bedrock/latest/userguide/model-lifecycle.html"
         }
       ],