@savvy-web/changesets

Custom changelog formatter and markdown processing pipeline for the Silk Suite. Replaces the default @changesets/cli/changelog formatter with a three-layer architecture that validates changeset files, formats structured changelog entries, and post-processes the generated CHANGELOG.md.

Features

• Section-aware changesets -- Categorize changes with h2 headings (Features, Bug Fixes, Breaking Changes, etc.)
• Three-layer pipeline -- Pre-validation (remark-lint), changelog formatting (Changesets API), and post-processing (remark-transform)
• CLI tooling -- savvy-changesets binary with init, lint, check, validate-file, transform, and version subcommands
• GitHub integration -- Automatic PR links, commit references, and contributor attribution
• Version file syncing -- Bump version fields in additional JSON files using glob patterns and JSONPath expressions
• Editor support -- markdownlint rules for real-time validation in VS Code and CI
• Dependency table format -- Structured GFM tables for tracking dependency changes with automatic collapse, sort, and aggregation
• AI-agent-friendly errors -- All lint and validation errors include inline fix instructions and documentation links, so AI agents can resolve issues without examining source code

Installation

npm install @savvy-web/changesets -D

Quick Start

Bootstrap your repository:

savvy-changesets init

This creates .changeset/config.json with auto-detected GitHub repo settings and configures markdownlint rules. Or configure manually:

{
  "changelog": [
    "@savvy-web/changesets/changelog",
    { "repo": "owner/repo" }
  ]
}

Write section-aware changeset files using ## Section headings to categorize changes:

---
"@my/package": minor
---

## Features

### OAuth2 Authentication

Added a new authentication system with OAuth2 support for third-party providers.

### CLI `login` Command

New interactive login command that opens the browser for OAuth2 consent:

```bash
my-package login --provider github
```

Returns a session token that can be passed to subsequent commands:

```typescript
import { createSession } from "@my/package";

const session = await createSession({ provider: "github" });
```

## Bug Fixes

* Fixed token refresh race condition during concurrent requests
* Corrected redirect URI validation for localhost callbacks

Claude Code Plugin

A companion Claude Code plugin is available that helps AI agents write well-structured changeset files. Install it at the project scope alongside the @savvy-web/changesets package:

# Add the Savvy Web plugin marketplace (one-time setup)
/plugin marketplace add savvy-web/systems

# Install the changesets plugin for this project
/plugin install changesets@savvy-web-systems --scope project

This adds the plugin to your .claude/settings.json:

{
  "enabledPlugins": {
    "changesets@savvy-web-systems": true
  }
}

The plugin provides:

• /changesets:create -- reconcile changesets with the branch's diff: discover existing entries, classify the diff, apply exclusion rules, and decide whether to create / update / delete
• /changesets:squash -- consolidate per-package changesets with identical bump mappings
• /changesets:check -- validate changeset files against CSH001-CSH005 structural rules
• /changesets:list -- summarize pending changesets (packages, bump types, content previews)
• /changesets:preview -- render the combined CHANGELOG output the current set would produce
• /changesets:style -- full style and format specification (also auto-loads on .changeset/*.md reads)
• changeset-manager agent -- autonomous subagent that runs the create/squash flows on demand

Automated hooks run transparently in the background:

| Hook | Trigger | Action | | ---- | ------- | ------ | | SessionStart | Session begins | Injects changeset format rules and tool pointers into the agent context; persists CHANGESETS_* env vars for sibling hooks | | PreToolUse (Bash) | Agent runs git push from a feature branch | Denies the push when the diff against origin/main (or origin/master) contains no added or modified .changeset/*.md. Override with CHANGESETS_SKIP_PUSH_CHECK=1 git push ... (inline or via env(1)), or by exporting it before launching Claude Code | | PostToolUse (Write|Edit) | Agent writes/edits a .changeset/*.md file | Runs savvy-changesets validate-file on the changed file; feeds errors back for immediate correction |

The push guard fails open for non-feature branches (main, master, release/*, changeset-release/*, dependabot/*, renovate/*, renovate-*), ambiguous git state (detached HEAD, missing origin/main/origin/master), and when the merge-base diff already contains a changeset -- so it catches the common "forgot to write a changeset" mistake without becoming a gate.

To have Claude automatically manage changesets as part of a multi-step workflow, include it in your prompt:

Implement the feature described in issue #42. When you're done, create a changeset documenting the user-facing changes for the GitHub release.

The agent will use the changeset-manager subagent to analyze the diff, detect affected packages, choose the appropriate content depth, and write a properly structured changeset file. The hooks ensure every changeset is validated as it is written, and the push guard catches branches that try to ship without a changeset.

Documentation

• Configuration -- Options, version files, markdownlint integration, CI scripts
• Section-Aware Pipeline -- End-to-end walkthrough of how section-aware changesets flow through the pipeline
• Markdownlint Rule Docs -- Per-rule documentation with examples, fix instructions, and rationale
• CLI Reference -- All commands and options
• API Reference -- Classes, types, Effect services, remark plugins
• Architecture -- Three-layer pipeline design and export map

License

MIT