scripts/model-guides.mjs

Functions

Imports

It imports no other module of this repo. No module of this repo imports it.

Source

1#!/usr/bin/env node
2// Fetches the Anthropic models overview and each model's prompting guide, stores
3// them under guides/, and reports which ones changed since the last fetch.
4//
5// No secrets. Every URL here is public documentation and the script sends no
6// credentials, so it runs the same from a laptop, from CI, or from a job.
7//
8// Fetches the .md variant of each docs page rather than the HTML. Measured
9// 2026-09-11: appending .md to a docs path returns text/markdown (the fable 5.1
10// guide is 54572 bytes as markdown against 740542 as HTML), and /index.md 404s.
11// Markdown is what we want to hash: it is the text without the page chrome that
12// changes on every site deploy.
13
14import { createHash } from 'node:crypto';
15import { mkdir, readFile, writeFile } from 'node:fs/promises';
16import { dirname, join } from 'node:path';
17import { fileURLToPath } from 'node:url';
18
19const HERE = dirname(fileURLToPath(import.meta.url));
20const REPO = join(HERE, '..');
21const GUIDES = join(REPO, 'guides');
22const STATE = join(GUIDES, '_state.json');
23
24const DOCS = 'https://platform.claude.com/docs/en';
25const OVERVIEW = `${DOCS}/about-claude/models/overview.md`;
26const GUIDE = (slug) => `${DOCS}/build-with-claude/prompt-engineering/prompting-claude-${slug}.md`;
27
28// A model id looks like claude-fable-5-1 or claude-haiku-4-5-20251001. The guide
29// slug is the id minus the claude- prefix and minus any dated suffix, because the
30// guides are named for the model line rather than for a snapshot.
31const MODEL_ID = /\bclaude-(fable|mythos|opus|sonnet|haiku)-\d[a-z0-9-]*/g;
32const DATED_SUFFIX = /-\d{8}$/;
33
34function slugFor(modelId) {
35  return modelId.replace(/^claude-/, '').replace(DATED_SUFFIX, '');
36}
37
38function sha256(text) {
39  return createHash('sha256').update(text, 'utf8').digest('hex');
40}
41
42async function fetchText(url) {
43  const res = await fetch(url, {
44    redirect: 'follow',
45    headers: { 'user-agent': 'claude-skills model-guides (+https://github.com/DrDustinEdwards/claude-skills)' },
46  });
47  if (res.status === 404) return { status: 404, text: null };
48  if (!res.ok) throw new Error(`${url} returned ${res.status}`);
49  return { status: res.status, text: await res.text() };
50}
51
52async function readState() {
53  try {
54    return JSON.parse(await readFile(STATE, 'utf8'));
55  } catch (err) {
56    if (err.code === 'ENOENT') return { models: {} };
57    throw err;
58  }
59}
60
61// Pulls the model ids out of the overview. Returns them deduped and sorted so a
62// reordering of the page is not mistaken for a change.
63export function discoverModels(overviewMarkdown) {
64  const ids = new Set();
65  for (const match of overviewMarkdown.matchAll(MODEL_ID)) ids.add(match[0]);
66  const slugs = new Set([...ids].map(slugFor));
67  return [...slugs].sort();
68}
69
70// Compares a fresh fetch against stored state. Pure, so the test can drive it
71// without a network.
72export function classify(slug, fetched, prior) {
73  if (fetched.status === 404) {
74    if (!prior) return { slug, state: 'none', changed: false };
75    if (prior.status === 404) return { slug, state: 'none', changed: false };
76    return { slug, state: 'withdrawn', changed: true };
77  }
78  const hash = sha256(fetched.text);
79  if (!prior) return { slug, state: 'new', changed: true, hash };
80  if (prior.status === 404) return { slug, state: 'new', changed: true, hash };
81  if (prior.sha256 !== hash) return { slug, state: 'changed', changed: true, hash, priorSha256: prior.sha256 };
82  return { slug, state: 'unchanged', changed: false, hash };
83}
84
85async function main() {
86  const json = process.argv.includes('--json');
87  const dryRun = process.argv.includes('--dry-run');
88
89  const overview = await fetchText(OVERVIEW);
90  if (overview.status === 404 || !overview.text) {
91    throw new Error(`models overview not found at ${OVERVIEW}`);
92  }
93
94  const slugs = discoverModels(overview.text);
95  // Fail closed. Zero models means the overview moved or its shape changed, and
96  // reporting "nothing changed" there would quietly stop every future refresh.
97  if (slugs.length === 0) {
98    throw new Error(`discovered 0 models in ${OVERVIEW}; the page shape changed`);
99  }
100
101  const prior = await readState();
102  const results = [];
103  const now = new Date().toISOString();
104
105  for (const slug of slugs) {
106    const fetched = await fetchText(GUIDE(slug));
107    const result = classify(slug, fetched, prior.models?.[slug]);
108    results.push(result);
109
110    if (dryRun) continue;
111    if (fetched.status === 404) continue;
112    await mkdir(GUIDES, { recursive: true });
113    // The guide file holds the fetched bytes and nothing else, so its hash is the
114    // hash of the document. fetched_at lives in _state.json: stamping it into the
115    // file would make every fetch look like a change.
116    await writeFile(join(GUIDES, `${slug}.md`), fetched.text, 'utf8');
117  }
118
119  const state = { fetched_at: now, overview_sha256: sha256(overview.text), models: {} };
120  for (const r of results) {
121    const p = prior.models?.[r.slug];
122    state.models[r.slug] = r.state === 'none' || r.state === 'withdrawn'
123      ? { status: 404, url: GUIDE(r.slug), fetched_at: now }
124      : {
125          status: 200,
126          url: GUIDE(r.slug),
127          sha256: r.hash,
128          fetched_at: r.changed ? now : (p?.fetched_at ?? now),
129          changed_at: r.changed ? now : (p?.changed_at ?? now),
130        };
131  }
132  if (!dryRun) await writeFile(STATE, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
133
134  const changed = results.filter((r) => r.changed);
135  if (json) {
136    console.log(JSON.stringify({ fetched_at: now, discovered: slugs, changed, results }, null, 2));
137  } else {
138    console.log(`discovered ${slugs.length} model(s): ${slugs.join(', ')}`);
139    for (const r of results) console.log(`  ${r.state.padEnd(10)} ${r.slug}`);
140    console.log(changed.length === 0 ? 'no guide changed' : `${changed.length} changed: ${changed.map((r) => r.slug).join(', ')}`);
141  }
142}
143
144// Only run when invoked directly, so the test can import the pure helpers.
145if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
146  main().catch((err) => {
147    console.error(`model-guides failed: ${err.message}`);
148    process.exit(1);
149  });
150}