@sr-labs/devkit 0.0.0-stage → 0.1.0

package/.gitlab-ci.yml

@@ -0,0 +1,24 @@
+image: node:24
+
+stages: [test, publish]
+
+default:
+  before_script:
+    - corepack enable
+    - pnpm install --frozen-lockfile
+
+test:
+  stage: test
+  script:
+    - pnpm test
+
+# Publishes every workspace package to npmjs.org when a vX.Y.Z tag is pushed.
+# pnpm rewrites `workspace:^` dependency ranges to the released version.
+publish:
+  stage: publish
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+  script:
+    - pnpm run build
+    - echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc
+    - pnpm -r publish --no-git-checks

package/.nvmrc

@@ -0,0 +1 @@
+v24.12.0

package/AGENTS.md

@@ -0,0 +1,15 @@
+# AGENTS.md
+
+## Agent skills
+
+### Issue tracker
+
+Issues are tracked in GitLab Issues (`gitlab.com/sr-labs/devkit`) via the `glab` CLI; external merge requests are not a triage surface. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+Default vocabulary: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+Single-context: one `CONTEXT.md` + `docs/adr/` at the repo root. See `docs/agents/domain.md`.

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## v0.1.0 - 2026-10-19
+
+### Features
+
+- rename to devkit, extract core and add umbrella devkit CLI
+
+## v0.0.3 - 2026-10-15
+
+### Fixes
+
+- restore root workspace package.json
+
+## v0.0.2 - 2026-10-15
+
+## v0.0.1 - 2026-10-15

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sr-labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# devkit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A series of tools that help set up the development environment of projects, published as public npm packages under [`@sr-labs`](https://www.npmjs.com/org/sr-labs).
+
+> This project was renamed from `dev-tools`; the old GitLab path `sr-labs/dev-tools` now redirects to `sr-labs/devkit`.
+
+| Package                                        | Bin           | What it does                                                                                            |
+| ---------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------- |
+| [`@sr-labs/devkit`](packages/devkit)           | `devkit`      | Umbrella: one `devkit` command with subcommands (`devkit release`, `devkit changelog`).                 |
+| [`@sr-labs/release-tag`](packages/release-tag) | `release-tag` | Next `vX.Y.Z` from Conventional Commits; bumps package files, updates `CHANGELOG.md`, commits and tags. |
+| [`@sr-labs/changelog`](packages/changelog)     | `changelog`   | Regenerates `CHANGELOG.md` from every `vX.Y.Z` tag.                                                     |
+| [`@sr-labs/core`](packages/core)               | -             | Shared git helpers; library only.                                                                       |
+
+Install `@sr-labs/devkit` to get every tool with one dependency. Install `@sr-labs/release-tag` or
+`@sr-labs/changelog` alone when you need a single tool; their bins and flags are the same as the `devkit` subcommands.
+
+## Using the packages in a repository
+
+```sh
+pnpm add -D @sr-labs/devkit   # or npm i -D; or just @sr-labs/release-tag / @sr-labs/changelog
+```
+
+```json
+"scripts": {
+  "release:tag": "devkit release",
+  "changelog": "devkit changelog"
+}
+```
+
+```sh
+pnpm release:tag                     # dry run: prints next version and notes
+pnpm release:tag --apply             # bump, CHANGELOG.md, commit, annotated tag
+pnpm release:tag --push              # ...and push the tag
+pnpm changelog                       # rewrite CHANGELOG.md from all tags
+pnpm changelog --unreleased --stdout
+```
+
+## Rules
+
+- Tags are `vX.Y.Z`. `feat` bumps minor, `fix`/`perf` bump patch, `!` or a `BREAKING CHANGE:` footer bumps
+  major (minor before 1.0). Other types never trigger a release.
+- `--apply` rewrites `package.json`, `package-lock.json` (if present) and, for workspaces
+  (`pnpm-workspace.yaml`, else `package.json` `workspaces`; `dir/*` or literal paths), every workspace
+  `package.json` plus sibling dependency ranges, so a monorepo releases in lockstep. `workspace:` ranges are
+  left for pnpm to rewrite at publish.
+- An existing `CHANGELOG.md` gets the new section inserted above the newest `## ` heading, so hand edits
+  survive. Without one, the full history is generated. `--no-changelog` skips it.
+
+## Developing
+
+Uses pnpm (version pinned in `packageManager`; `corepack enable` picks it up).
+
+```sh
+pnpm install
+pnpm test           # builds (tsc -b) then runs vitest, including an end-to-end run in a temp git repo
+pnpm run check      # typecheck sources and tests
+```
+
+Packages ship compiled JS in `dist/` because Node does not strip TypeScript types inside `node_modules`.
+
+## Releasing
+
+This repo releases itself with its own tool. All packages share one version.
+
+```sh
+pnpm release:tag --push
+```
+
+The tag push runs the `publish` job in `.gitlab-ci.yml`, which publishes every workspace package to npmjs.org
+using the `NPM_TOKEN` GitLab CI/CD variable (an npm automation/granular access token with publish access to
+`@sr-labs`). Note `--push` pushes only the tag; push `main` too.

package/docs/agents/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`** — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

package/docs/agents/issue-tracker.md

@@ -0,0 +1,46 @@
+# Issue tracker: GitLab
+
+Issues and PRDs for this repo live as GitLab issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `glab issue create --title "..." --description "..."`. Use a heredoc for multi-line descriptions. Pass `--description -` to open an editor.
+- **Read an issue**: `glab issue view <number> --comments`. Use `-F json` for machine-readable output.
+- **List issues**: `glab issue list -F json` with appropriate `--label` filters.
+- **Comment on an issue**: `glab issue note <number> --message "..."`. GitLab calls comments "notes".
+- **Apply / remove labels**: `glab issue update <number> --label "..."` / `--unlabel "..."`. Multiple labels can be comma-separated or by repeating the flag.
+- **Close**: `glab issue close <number>`. `glab issue close` does not accept a closing comment, so post the explanation first with `glab issue note <number> --message "..."`, then close.
+- **Merge requests**: GitLab calls PRs "merge requests". Use `glab mr create`, `glab mr view`, `glab mr note`, etc. — the same shape as `gh pr ...` with `mr` in place of `pr` and `note`/`--message` in place of `comment`/`--body`.
+
+Infer the repo from `git remote -v` — `glab` does this automatically when run inside a clone.
+
+## Merge requests as a triage surface
+
+**MRs as a request surface: no.** _(Set to `yes` if this repo treats external merge requests as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, MRs run through the same labels and states as issues, using the `glab mr` equivalents:
+
+- **Read an MR**: `glab mr view <number> --comments` and `glab mr diff <number>` for the diff.
+- **List external MRs for triage**: `glab mr list -F json`, then keep only MRs whose author is not a project member/owner (a contributor's MR, not a maintainer's in-flight work).
+- **Comment / label / close**: `glab mr note`, `glab mr update --label`/`--unlabel`, `glab mr close`.
+
+Unlike GitHub, GitLab numbers issues and MRs separately, so `#42` is unambiguous once you know which surface the maintainer means.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitLab issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `glab issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `glab issue create --label wayfinder:map`. (On GitLab tiers with native epics, an epic may hold the map instead; a labelled issue works everywhere.)
+- **Child ticket**: an issue carrying `Part of #<map>` at the top of its description and labels `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitLab's **native blocking link** — the canonical, UI-visible representation. Add it with the `/blocked_by #<n>` quick action, posted as a note (`glab issue note <child> --message "/blocked_by #<blocker>"`). Native blocking links are a Premium/Ultimate feature; on the free tier (or where unavailable) fall back to a `Blocked by: #<n>, #<n>` line at the top of the description. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: `glab issue list -F json` scoped to the map's children, drop any with an open blocker — a native `blocked_by` link to an open issue (`glab api projects/:id/issues/:iid/links`), or an open issue in the `Blocked by` line — or an assignee; first in map order wins.
+- **Claim**: `glab issue update <n> --assignee @me` — the session's first write.
+- **Resolve**: `glab issue note <n> --message "<answer>"`, then `glab issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

package/docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.

package/docs/specs/devkit-rename-and-layout.md

@@ -0,0 +1,71 @@
+# Spec: rename to devkit and restructure into core + umbrella CLI
+
+Status: ready-for-agent
+
+## Problem Statement
+
+The repo is called `dev-tools`, a name that is already taken on npm as an unscoped package, is too generic to find, and does not say what the project is for. The intended purpose is a series of tools that help set up the development environment of projects. Today the repo only holds two release tools (`changelog`, `release-tag`), has no single entry point, and shares code between them by one package importing from the other (git helpers live inside `changelog`). Adding more tools would make this worse.
+
+## Solution
+
+Rename the project to **devkit** (repo and docs), keep the `@sr-labs` npm scope, and add an umbrella package `@sr-labs/devkit` that exposes one `devkit` command with subcommands (`devkit release`, `devkit changelog`). Extract the shared helpers into `@sr-labs/core` so every tool depends on it rather than on a sibling tool. `@sr-labs/changelog` and `@sr-labs/release-tag` stay published and usable on their own with unchanged bins and flags.
+
+## User Stories
+
+1. As a maintainer, I want the project named devkit, so that its name describes a toolkit for development environments.
+2. As a maintainer, I want all packages under the `@sr-labs` scope, so that publishing never clashes with unscoped npm names.
+3. As a user, I want to install one package `@sr-labs/devkit`, so that I get every tool with a single dependency.
+4. As a user, I want a `devkit` bin with subcommands, so that I have one discoverable entry point.
+5. As a user, I want `devkit release` to behave exactly like `release-tag`, so that I can switch without relearning flags.
+6. As a user, I want `devkit changelog` to behave exactly like `changelog`, so that I can switch without relearning flags.
+7. As a user, I want `devkit --help` to list available subcommands, so that I can discover tools.
+8. As a user, I want `devkit --version` to print the umbrella version, so that I can report what I run.
+9. As a user, I want an unknown subcommand to print an error and the help text and exit non-zero, so that typos are obvious in scripts.
+10. As an existing user of `@sr-labs/release-tag`, I want its bin and flags unchanged, so that my scripts keep working.
+11. As an existing user of `@sr-labs/changelog`, I want its bin and flags unchanged, so that my scripts keep working.
+12. As a library consumer, I want `@sr-labs/changelog` to keep exporting its commit parsing and notes API, so that my imports keep working.
+13. As a tool author, I want shared git and exec helpers in `@sr-labs/core`, so that new tools do not copy code or import a sibling tool.
+14. As a tool author, I want a new tool to be one new package plus one subcommand registration, so that extending devkit is cheap.
+15. As a maintainer, I want all packages to share one version and release in lockstep, so that the existing release flow still works.
+16. As a maintainer, I want `pnpm release:tag` in this repo to keep releasing every package, including the new ones, so that I dogfood the tools.
+17. As a maintainer, I want repository URLs, READMEs and CI to use the devkit name, so that no stale references remain.
+18. As a maintainer, I want the old `dev-tools` GitLab path to be documented as moved, so that existing clones and links are understood.
+19. As a contributor, I want `pnpm test` to build and test every package, so that one command verifies the monorepo.
+20. As a contributor, I want the README to explain the package layout and which package to install, so that I pick the right one.
+21. As a user on Node 20+, I want every package to keep `engines.node >=20`, so that support is unchanged.
+22. As a user, I want compiled JS in `dist/` for every package, so that installs work inside `node_modules`.
+
+## Implementation Decisions
+
+- **Naming**: project name `devkit`. npm packages: `@sr-labs/devkit` (umbrella, bin `devkit`), `@sr-labs/core` (shared helpers, library only), `@sr-labs/changelog` and `@sr-labs/release-tag` (unchanged names and bins). The root workspace package is renamed to `devkit` and stays private.
+- **core**: receives the git/exec helpers currently inside the changelog package (the `git` runner, version-tag listing, commit-range reading). No behavior change; pure move. Public API is exported from the package index. Add `core` only with what is actually shared today; no speculative utilities.
+- **changelog**: depends on `@sr-labs/core` for git helpers. Keeps exporting commit parsing and release-notes APIs so release-tag's existing import keeps working. Re-exporting git helpers from changelog is not required.
+- **release-tag**: depends on `core` for git helpers and on `changelog` for commit parsing and notes, as today.
+- **devkit umbrella**: depends on `changelog` and `release-tag`. Its bin dispatches the first argument to a subcommand registry (`release`, `changelog`) and forwards remaining argv, stdio and exit code unchanged. The registry is a plain data table so adding a tool is one entry. Subcommand implementations are imported as modules from the tool packages (each tool exposes its CLI entry as a callable function in addition to its bin), not spawned as child processes.
+- **Tool CLI entry points**: each of `changelog` and `release-tag` splits its bin into a thin executable wrapper plus an exported `main(argv)` that returns an exit code, so the umbrella can call it. Bin names and flags do not change.
+- **Versioning**: all packages stay in lockstep; the new packages start at the current shared version. `workspace:^` ranges between packages as today. The release tool's workspace discovery already covers `packages/*`.
+- **Repo rename**: update repository URLs in all `package.json` files, README, CI config and changelog links from `sr-labs/dev-tools` to the new `devkit` path. The actual GitLab project rename is a manual step by the owner (GitLab redirects the old path); the spec only covers in-repo references. Git history and existing tags are untouched, including old changelog entries.
+- **Docs**: root README describes devkit's purpose (environment setup tooling), the package table with the new packages, and the install recommendation (`@sr-labs/devkit` for everything, individual packages for a single tool). Each new package gets a short README.
+- **Build**: new packages get tsconfigs extending the base and are added to project references; `tsc -b` stays the build.
+
+## Testing Decisions
+
+- A good test exercises external behavior only: run the built CLI, assert on stdout, exit code and resulting repo state. No assertions on internal module structure.
+- **One new seam**: the built `devkit` bin, run end-to-end in a throwaway git repo. Cover: `devkit release` dry run and `--apply` match what `release-tag` does; `devkit changelog` regenerates the same output as `changelog`; unknown subcommand exits non-zero with help; `--help` lists subcommands.
+- Existing seams stay: unit tests for notes, version and package-files, and the release-tag end-to-end test. They must keep passing unchanged except for import path updates where code moved to `core`.
+- Tests that cover moved git helpers move with them into `core`; no new core-level seam is added.
+- Prior art: the temp-repo, built-CLI pattern in the release-tag CLI test (`execFileSync` against `dist/cli.js` with fixed git author env).
+
+## Out of Scope
+
+- Any new environment-setup tool (hooks, lint/editor config, CI templates). Those come later as their own packages and specs.
+- Renaming the GitLab project itself, or changing remotes on contributors' machines.
+- Changing release rules, changelog format or any flag of the existing tools.
+- Deprecating or republishing old versions of existing packages.
+- A plugin system for third-party subcommands.
+
+## Further Notes
+
+- npm availability checked 2026-10-19: unscoped `dev-tools`, `devkit`, `devenv`, `devsetup` are taken; `@sr-labs/devkit` and `@sr-labs/setup` returned 404 (free). Re-check `@sr-labs/core` before first publish.
+- First publish of the two new packages needs `publishConfig.access: public` like the existing ones.
+- Order suggestion: extract `core`, then add `main(argv)` exports, then umbrella, then rename references and docs, so each step keeps `pnpm test` green.

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "@sr-labs/devkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/sr-labs/devkit.git"
+  },
+  "type": "module",
+  "packageManager": "pnpm@12.8.1",
+  "scripts": {
+    "build": "tsc -b",
+    "check": "tsc -b && tsc -p tsconfig.test.json",
+    "test": "tsc -b && vitest run",
+    "release:tag": "tsc -b && node packages/release-tag/dist/cli.js"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.3",
+    "typescript": "~6.0.2",
+    "vitest": "^5.0.4"
+  }
+}

package/packages/changelog/README.md

@@ -0,0 +1,7 @@
+# @sr-labs/changelog
+
+`changelog [--stdout] [--unreleased] [--file CHANGELOG.md]` regenerates a changelog from Conventional Commits
+between `vX.Y.Z` tags, grouped into Breaking Changes, Features, Fixes and Performance.
+
+Also exports the building blocks (`parseCommit`, `readCommits`, `listVersionTags`, `formatSection`,
+`prependSection`, ...) used by `@sr-labs/release-tag`. See the [devkit README](../../README.md).

package/packages/changelog/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@sr-labs/changelog",
+  "version": "0.1.0",
+  "description": "Generate CHANGELOG.md from Conventional Commits between vX.Y.Z tags.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/sr-labs/devkit.git",
+    "directory": "packages/changelog"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "changelog": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@sr-labs/core": "workspace:^"
+  }
+}

package/packages/changelog/src/cli.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from './main.ts';
+
+process.exitCode = main(process.argv.slice(2));

package/packages/changelog/src/commits.ts

@@ -0,0 +1,29 @@
+import type { Commit } from '@sr-labs/core';
+
+export type { Commit };
+
+export interface ParsedCommit {
+  type: string;
+  scope?: string;
+  description: string;
+  breaking: boolean;
+  /** First line of a `BREAKING CHANGE:` footer, when present. */
+  breakingNote?: string;
+}
+
+const HEADER = /^(\w+)(?:\(([^)]*)\))?(!)?:\s*(.+)$/;
+const BREAKING_FOOTER = /^BREAKING[ -]CHANGE:\s*(.*)$/m;
+
+/** Parses a Conventional Commits header and breaking footer. Null for non-conventional subjects (e.g. merges). */
+export function parseCommit(c: Commit): ParsedCommit | null {
+  const m = HEADER.exec(c.subject);
+  if (!m) return null;
+  const note = BREAKING_FOOTER.exec(c.body)?.[1].trim();
+  return {
+    type: m[1],
+    scope: m[2] || undefined,
+    description: m[4],
+    breaking: m[3] === '!' || note !== undefined,
+    breakingNote: note || undefined
+  };
+}

package/packages/changelog/src/git.ts

@@ -0,0 +1,11 @@
+import { listVersionTags, readCommits, type Tag } from '@sr-labs/core';
+import type { Release } from './notes.ts';
+
+/** Every tagged release with its commits since the previous tag, newest first. */
+export function readReleases(tags: Tag[] = listVersionTags()): Release[] {
+  return tags.map((t, i) => ({
+    tag: t.name,
+    date: t.date,
+    commits: readCommits(tags[i + 1] ? `${tags[i + 1].name}..${t.name}` : t.name)
+  }));
+}

package/packages/changelog/src/index.ts

@@ -0,0 +1,4 @@
+export * from './commits.ts';
+export * from './git.ts';
+export { main } from './main.ts';
+export * from './notes.ts';

package/packages/changelog/src/main.ts

@@ -0,0 +1,33 @@
+// Usage: changelog [--stdout] [--unreleased] [--file CHANGELOG.md]
+// Regenerates the changelog from every vX.Y.Z tag. --unreleased adds commits since the latest tag.
+import { writeFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { listVersionTags, readCommits } from '@sr-labs/core';
+import { readReleases } from './git.ts';
+import { formatChangelog, type Release } from './notes.ts';
+
+/** Runs the changelog CLI with args (without node/script) and returns the exit code. */
+export function main(argv: string[]): number {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      stdout: { type: 'boolean', default: false },
+      unreleased: { type: 'boolean', default: false },
+      file: { type: 'string', default: 'CHANGELOG.md' }
+    }
+  });
+
+  const tags = listVersionTags();
+  const releases: Release[] = readReleases(tags);
+  if (values.unreleased) {
+    releases.unshift({ tag: 'Unreleased', date: '', commits: readCommits(tags[0] ? `${tags[0].name}..HEAD` : 'HEAD') });
+  }
+
+  const text = formatChangelog(releases);
+  if (values.stdout) process.stdout.write(text);
+  else {
+    writeFileSync(values.file, text);
+    console.log(`Wrote ${values.file} (${tags.length} releases)`);
+  }
+  return 0;
+}

package/packages/changelog/src/notes.ts

@@ -0,0 +1,60 @@
+import { parseCommit, type Commit, type ParsedCommit } from './commits.ts';
+
+export interface Section {
+  title: string;
+  items: string[];
+}
+
+export interface Release {
+  tag: string;
+  /** YYYY-MM-DD; empty for an unreleased section. */
+  date: string;
+  commits: Commit[];
+}
+
+const SECTIONS: Array<[string, string]> = [
+  ['feat', 'Features'],
+  ['fix', 'Fixes'],
+  ['perf', 'Performance']
+];
+
+const item = (p: ParsedCommit, text = p.description) => `${p.scope ? `${p.scope}: ` : ''}${text}`;
+
+/** Release-worthy commits grouped by section; breaking changes first and also listed under their type. */
+export function groupCommits(commits: Commit[]): Section[] {
+  const parsed = commits.map(parseCommit).filter((p): p is ParsedCommit => p !== null);
+  const sections: Section[] = [];
+  const breaking = parsed.filter((p) => p.breaking).map((p) => item(p, p.breakingNote));
+  if (breaking.length) sections.push({ title: 'Breaking Changes', items: breaking });
+  for (const [type, title] of SECTIONS) {
+    const items = parsed.filter((p) => p.type === type).map((p) => item(p));
+    if (items.length) sections.push({ title, items });
+  }
+  return sections;
+}
+
+/** Annotated-tag message: title line plus a grouped plain-text changelog. */
+export function formatTagNotes(tag: string, commits: Commit[]): string {
+  const lines = [tag, ''];
+  for (const s of groupCommits(commits)) lines.push(`${s.title}:`, ...s.items.map((i) => `- ${i}`), '');
+  return lines.join('\n').trimEnd() + '\n';
+}
+
+/** One `## vX.Y.Z - date` Markdown section. */
+export function formatSection(r: Release): string {
+  const lines = [`## ${r.date ? `${r.tag} - ${r.date}` : r.tag}`, ''];
+  for (const s of groupCommits(r.commits)) lines.push(`### ${s.title}`, '', ...s.items.map((i) => `- ${i}`), '');
+  return lines.join('\n').trimEnd() + '\n';
+}
+
+/** Whole CHANGELOG.md; releases newest first. */
+export function formatChangelog(releases: Release[]): string {
+  return ['# Changelog\n', ...releases.map(formatSection)].join('\n');
+}
+
+/** Inserts a section above the newest existing `## ` heading, keeping any hand-written preamble and edits. */
+export function prependSection(changelog: string, section: string): string {
+  const i = changelog.search(/^## /m);
+  if (i === -1) return (changelog.trim() ? changelog.trimEnd() + '\n\n' : '# Changelog\n\n') + section;
+  return changelog.slice(0, i) + section + '\n' + changelog.slice(i);
+}

package/packages/changelog/test/notes.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest';
+import { parseCommit } from '../src/commits.ts';
+import { formatChangelog, formatSection, formatTagNotes, prependSection } from '../src/notes.ts';
+
+const c = (subject: string, body = '') => ({ subject, body });
+
+describe('parseCommit', () => {
+  it('parses type, scope and breaking markers', () => {
+    expect(parseCommit(c('feat(ui)!: x'))).toEqual({
+      type: 'feat',
+      scope: 'ui',
+      description: 'x',
+      breaking: true,
+      breakingNote: undefined
+    });
+    expect(parseCommit(c('fix: y', 'details\n\nBREAKING CHANGE: drops z\nmore'))?.breakingNote).toBe('drops z');
+    expect(parseCommit(c('Merge ticket 04: reverb'))).toBeNull();
+  });
+});
+
+describe('notes', () => {
+  it('groups tag notes', () => {
+    const n = formatTagNotes('v0.3.0', [c('feat(engine): x'), c('fix: y'), c('docs: z')]);
+    expect(n).toBe('v0.3.0\n\nFeatures:\n- engine: x\n\nFixes:\n- y\n');
+  });
+
+  it('lists breaking changes first, using the footer text when present', () => {
+    const n = formatTagNotes('v1.0.0', [c('feat(api)!: new x'), c('fix: y', 'BREAKING CHANGE: y renamed')]);
+    expect(n).toBe('v1.0.0\n\nBreaking Changes:\n- api: new x\n- y renamed\n\nFeatures:\n- api: new x\n\nFixes:\n- y\n');
+  });
+
+  it('formats markdown sections and a whole changelog', () => {
+    const r = { tag: 'v0.2.0', date: '2026-10-01', commits: [c('perf: faster'), c('chore: tidy')] };
+    expect(formatSection(r)).toBe('## v0.2.0 - 2026-10-01\n\n### Performance\n\n- faster\n');
+    expect(formatSection({ tag: 'Unreleased', date: '', commits: [] })).toBe('## Unreleased\n');
+    expect(formatChangelog([r])).toBe('# Changelog\n\n## v0.2.0 - 2026-10-01\n\n### Performance\n\n- faster\n');
+  });
+
+  it('prepends above the newest release, keeping the preamble', () => {
+    const existing = '# Changelog\n\nHand-written intro.\n\n## v0.1.0 - 2026-01-01\n\n- old\n';
+    expect(prependSection(existing, '## v0.2.0 - 2026-02-01\n')).toBe(
+      '# Changelog\n\nHand-written intro.\n\n## v0.2.0 - 2026-02-01\n\n## v0.1.0 - 2026-01-01\n\n- old\n'
+    );
+    expect(prependSection('', '## v0.1.0\n')).toBe('# Changelog\n\n## v0.1.0\n');
+    expect(prependSection('# Changelog\n', '## v0.1.0\n')).toBe('# Changelog\n\n## v0.1.0\n');
+  });
+});

package/packages/changelog/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "rootDir": "src", "outDir": "dist" },
+  "include": ["src"],
+  "references": [{ "path": "../core" }]
+}

package/packages/core/README.md

@@ -0,0 +1,3 @@
+# @sr-labs/core
+
+Shared git helpers (`git`, `listVersionTags`, `readCommits`) used by the [devkit](../../README.md) tools. Library only, no bin.