Both P1s from Miguel's review on #2976.
**The weekly changelog command has a fourth output, and it is public.**
`changelog-process.mdx` listed three internal drafts. `outputWeeklyDraft` also
calls `prependDocsUpdate` on `--write` (`scripts/changelog-weekly.ts:236`),
which writes straight into `docs/weekly-updates.mdx`. A contributor following
the page would review three files and push a fourth unread. Now called out as a
warning, with the re-run behaviour, since that is what makes editing the entry
afterwards safe.
The same paragraph also said Weekly updates is "unlisted in the sidebar". That
was true when written and I made it false myself, putting the page back under
Explore in #2978 after Rames found it orphaned. Corrected rather than reverted —
the page belongs in the sidebar.
**Bare `hyperframes lint` cannot validate a registry item.** Both
`contributing.mdx` and `contributing/catalog.mdx` told contributors to run it.
The CLI resolves a project by looking for `index.html`
(`packages/cli/src/utils/project.ts`), and registry items ship as `<name>.html`
or `demo.html`, so it fails with "No composition found". This is not
theoretical: `scripts/lint-registry-items.mjs` exists precisely for this shape
and its header records two `gsap_non_transform_motion` errors that reached main
unlinted because of it.
Both pages now document `bun run lint:registry-items`, and the Catalog page
shows the install-into-a-scratch-project route for the full `check` gate rather
than claiming a bare `check` covers a registry item.
Verified by running the documented command, not just by reading the script.
Three things the quality layer asserted but the pages did not support.
changelog-process said "do not recreate docs/weekly-updates.mdx; that empty
public page was retired" while the page exists with a real curated feed. It
describes the page as it is: unlisted, reachable by URL and RSS, with versioned
notes still in the Changelog.
The Related-topics rule read as universal, but three different endings are in
use and each is right for its shape — Related topics on task pages, a single
Next line through the Prompt Guide's numbered sequence, and nothing on
reference and concept pages. The rule now says that, and every section matches
it; color-grading gained the Next line it was missing and no longer points at a
page this stack retired.
The vocabulary previews were 18 DocsVideo players in three unlabelled grids, so
a reader saw several near-identical clips with no way to tell smooth from
snappy. They are now native muted loops with visible captions, which is what
AGENTS.md asks for small preview loops in the first place.
## What
- Add `bun run release:prepare <version>` as the maintainer-facing stable release entrypoint.
- Make the first run draft missing changelog artifacts and intentionally exit before tagging; rerunning after manual review delegates to `set-version`.
- Tighten the direct `set-version` guard so stable releases also fail when generated TODO changelog copy is still present.
- Update maintainer docs to recommend `release:prepare` while keeping `changelog:draft` as the lower-level regeneration tool.
## Why
Stable releases should be hard to run without reviewed GitHub release notes and Mintlify changelog copy. This keeps the existing manual rewrite step, but makes the expected path one command that engineers can rerun after review.
## How
- Added `scripts/release-prepare.ts` with parsing, draft/review/set-version action selection, and command forwarding.
- Added focused script tests for parser behavior, action selection, command forwarding, and TODO detection.
- Extracted shared script CLI parsing helpers so `changelog:draft` and `release:prepare` use the same option handling.
- Adjusted `changelog:draft --write` so an existing release file is left unchanged unless `--force` is passed, while still allowing a missing docs entry to be added.
## Test plan
- [x] Unit tests added/updated: `bun run test:scripts`
- [x] Format check: `bun run format:check`
- [x] Lint: `bun run lint`
- [x] Typecheck: `bun run --filter '*' typecheck`
- [x] Fallow audit: `bunx fallow audit --base origin/main --fail-on-issues`
- [x] Manual CLI checks: `bun run release:prepare --help`; `bun run set-version 9.9.9` fails before mutation when changelog artifacts are missing
- [x] Documentation updated
* feat(docs): add changelog release workflow
* fix(scripts): resolve CodeQL findings in release scripts
- draft-changelog.ts: replace existsSync+writeFileSync check-then-act with
an atomic exclusive-write flag (flag: wx) to fix the js/file-system-race
TOCTOU finding; overwrite only under --force (flag: w).
- set-version.ts: switch execSync shell-string git calls to execFileSync with
argument arrays so the interpolated version/paths can never be interpreted
by a shell, resolving the js/indirect-command-line-injection findings.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(scripts): lower writeReleaseNotes complexity below CRAP threshold
The exclusive-write fix pushed writeReleaseNotes to cyclomatic 5 / CRAP 30.0
(fallow/high-crap-score, threshold 30.0). The '!force' guard in the catch is
redundant — EEXIST is only reachable under the 'wx' flag (force=false), since
'w' overwrites without throwing. Dropping it returns the function to cyclomatic
4 / CRAP 20 with identical behavior.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(docs): address changelog review feedback
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
ukimsanov