Development

How the package is built, tested and released. The repository's AGENTS.md holds the full rules; the maintainer's notes, decisions and plan are under ai-docs/.

Layout

• src/: TypeScript. retrieve-markdown.ts (the request, decoding and both call forms), query-string.ts (the query string exactly as 1.1.7 built it), errors.ts, index.ts, and cli.ts (the command, on node:util parseArgs).
• dist/: built by tsdown into index.mjs, index.cjs, their .d.mts and .d.cts declarations, and cli.mjs. The published package holds dist/ (without the CLI's source map), the CHANGELOG, README, LICENSE and package.json: 11 files, 86,183 bytes unpacked.
• test/: golden, unit, functional, CLI, package-shape, consumer and live suites. Tests import dist/, never src/, and run against both builds.
• test/golden/: capture-1.1.7.cjs, 1.1.7.json, codec.cjs and fixture-server.cjs. The recording was made from the published 1.1.7 and is never regenerated or edited.

Commands

npm ci
npm run build          # tsdown -> dist/
npm test               # build, then every suite against dist/ (local fixture server only)
npm run test:dist      # the same suites against the dist/ already built
npm run test:consumers # pack, install the tarball in a scratch project, run the ESM, CJS, type and bin fixtures
npm run test:live      # opt-in: two requests to the real API
npm run coverage       # c8 over the suites; fails under 95% lines or 90% branches
npm run lint           # xo
npm run typecheck      # tsc --noEmit
npm run check          # publint, attw, npm pack --dry-run (needs a build first)

Building needs Node 22.18 or later (tsdown); the built package and its tests run on Node 20 and later. On 2026-09-29, npm test in a clone on Node 24.18.0 on Windows 11 passed 371 of 371 tests in 4 suites.

Tests never touch the real API

Every suite points fetch at test/golden/fixture-server.cjs: test/helpers/api.js swaps globalThis.fetch for a wrapper that refuses any origin other than https://api.stackexchange.com and sends the path and query to the local server. The id picks the fixture's answer. 127968, 1, 2 and 1010 hold posts, and 9001 and up are odd responses (API errors, HTML, broken gzip, a server that never answers). Any other id is not found. Only npm run test:live and the weekly live.yml workflow (Mondays at 06:23 UTC) make real requests, two per run.

This wiki's examples were checked another way, against the published package: ai-docs/notes/2026-09-29-wiki-verify.mjs with 2026-09-29-host-fixture.mjs, which serve the API under its real host name through a proxy on 127.0.0.1. The note ai-docs/notes/2026-09-29-github-wiki.md says how to run it again.

CI

ci.yml runs on every push to master and every pull request:

Job	What it runs
lint and typecheck	npm run lint, npm run typecheck, npm audit signatures, npm audit --omit=dev (Node 24)
package shape and coverage	npm run check, npm run coverage (Node 24)
test	every suite against both builds and the consumer fixtures, on Node 20, 22, 24 and 26 on Linux, and Node 24 on Windows and macOS (built on Node 24 first)
bun, deno	the consumer fixtures under the latest Bun and Deno 2.x
ci	passes only when every job above passed; the ruleset on master requires it

Releases

Nothing is published from a developer's machine. A release updates CHANGELOG.md (the heading carries the date), runs the maintainer's preflight check, then npm version <version> and git push --follow-tags. The tag starts release.yml, which builds, tests and stages the publish through npm trusted publishing with provenance. The maintainer approves the staged version on npmjs.com with two-factor authentication, and a separate job creates the GitHub Release. verify-published.yml then checks the package from the registry. The trusted publisher names release.yml, so renaming that file breaks publishing.

Dependabot opens weekly pull requests for npm and GitHub Actions. .npmrc sets min-release-age=3, so an install resolves only versions at least three days old.