From b9ddbd41661238a707fba14397aebba3955bc54a Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Fri, 12 Jun 2026 00:45:43 +0200 Subject: [PATCH 1/4] docs: add agent-generic SKILLS.md Add a SKILLS.md guide for using the heylogs CLI (check, rule tuning via --rule and heylogs.properties, all built-in rules, other commands) plus how to run it via gg.cmd/JBang. Link to it from AGENTS.md and README.md so agents and users can discover it. Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 2 + README.md | 2 + SKILLS.md | 286 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 290 insertions(+) create mode 100644 SKILLS.md diff --git a/AGENTS.md b/AGENTS.md index beac702a..b8621e9d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,6 +4,8 @@ Heylogs is a Java 8+ multi-module Maven project for validating and releasing changelogs in [Keep a Changelog](https://keepachangelog.com) format. It parses Markdown into an AST (via [flexmark-java](https://github.com/vsch/flexmark-java)) and operates on the tree. +> **This file** covers building and contributing to Heylogs itself. To *use* Heylogs (run `check`, tune rules, configure `heylogs.properties`) on a changelog, see [`SKILLS.md`](SKILLS.md). + ## Architecture **Core module** (`heylogs-api`): Contains the facade class (`Heylogs`), domain model, and SPI interfaces in the `spi` subpackage. Internal implementation lives under `internal.*` packages — never reference these types from public API. diff --git a/README.md b/README.md index b8aa2f52..b4313572 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,8 @@ Heylogs is available in multiple formats to fit your workflow: - **[Maven Enforcer rules](docs/usage-enforcer-rules.md)** - Enforce changelog quality in builds - **[CI/CD pipelines](docs/usage-pipelines.md)** - Integrate into CI/CD environments +> Using an AI coding assistant? [`SKILLS.md`](SKILLS.md) is an agent-generic guide to running `check`, tuning rules, and configuring `heylogs.properties`. + ## Features Heylogs provides several **commands** to interact with changelog files: diff --git a/SKILLS.md b/SKILLS.md new file mode 100644 index 00000000..3e8d1d71 --- /dev/null +++ b/SKILLS.md @@ -0,0 +1,286 @@ +# SKILLS.md — Working with Heylogs changelogs + +This file is an agent-generic guide (works with any coding assistant) for using +the [Heylogs](https://github.com/nbbrd/heylogs) CLI to validate and maintain +[Keep a Changelog](https://keepachangelog.com)–formatted `CHANGELOG.md` files. + +For project architecture and contribution conventions, see [`AGENTS.md`](AGENTS.md). +Full feature docs live under [`docs/`](docs/). + +## What Heylogs does + +Heylogs parses a Markdown changelog into an AST and validates/transforms it. +It is available as a CLI, a Maven plugin, Maven Enforcer rules, and a Java +library. This guide focuses on the **CLI**. + +```bash +heylogs [] +``` + +## Running the CLI + +Examples below write `heylogs …` for brevity. If you don't have a native binary +on `PATH` (e.g. via Homebrew/Scoop), run the same commands through one of the +options below — substitute the whole invocation for `heylogs`. + +### With gg.cmd (recommended — no prerequisites) + +[`gg.cmd`](https://github.com/eirikb/gg/) bootstraps both a JDK and JBang on +demand, so contributors and CI need **nothing** pre-installed. Download it once +into the repo: + +```bash +curl -L ggcmd.io > gg.cmd && chmod +x gg.cmd +``` + +Then run heylogs via JBang through it: + +```bash +./gg.cmd jbang com.github.nbbrd.heylogs:heylogs-cli:0.18.1:bin check CHANGELOG.md +``` + +### With JBang directly + +If JBang is already available: + +```bash +jbang com.github.nbbrd.heylogs:heylogs-cli:0.18.1:bin check CHANGELOG.md +``` + +Install JBang with the universal (all-platforms) installer if needed: + +```bash +# Linux / macOS / Windows (bash) +curl -Ls https://sh.jbang.dev | bash -s - app setup +# Windows PowerShell +iex "& { $(iwr -useb https://ps.jbang.dev) } app setup" +``` + +JBang can also resolve the latest release from the project's catalog +(`heylogs@nbbrd`, requires `trust: https://github.com/nbbrd/jbang-catalog`). +Replace `0.18.1` with the version you want; see +[releases](https://github.com/nbbrd/heylogs/releases/latest). Other install +methods (Homebrew, Scoop, plain jar) are in [`docs/usage-cli.md`](docs/usage-cli.md). + +Global options available on every command: + +| Option | Purpose | +|------------------------|-------------------------------------------------------------------| +| `--debug` | Print the full stack trace on error. | +| `--batch` | Suppress progress feedback on stderr and disable ANSI colors (CI).| +| `-D=` | Set a Java system property (repeatable). | + +Most commands default to `CHANGELOG.md` and accept a positional file argument +(use `-` for stdin). File-modifying commands print a one-line status to +**stderr** (`+` modified, `!` needs attention, `~` dry-run, `=` no-op) and most +support `--dry-run`. + +## Primary task: `check` + +Validate a changelog against the rule set: + +```bash +heylogs check # checks CHANGELOG.md +heylogs check path/to/CHANGELOG.md +heylogs check --recursive # find changelogs recursively +heylogs check --format json --output result.json +``` + +Output formats: `stylish` (default), `json`, `github-actions`, … (run +`heylogs list` to see what's installed). + +### Adjusting which rules run and their severity + +Each rule has a severity: `ERROR`, `WARN`, `INFO`, or `OFF` (disabled). Override +per invocation with repeated `--rule :` options: + +```bash +# Enable dot-space-link-style (off by default) as a warning, and disable no-empty-group +heylogs check --rule dot-space-link-style:WARN --rule no-empty-group:OFF +``` + +This is the canonical way to tune rules ad hoc. For persistent configuration, +use `heylogs.properties` (below). + +### Other `check` configuration options + +| Option | Purpose | +|---------------------------|--------------------------------------------------------| +| `--rule ` | Override a rule's severity (repeatable). | +| `--versioning ` | Versioning scheme: `semver`, `calver:YYYY.MM.DD`, `regex:…`. | +| `--tagging ` | Tag naming, e.g. `prefix:v` (for `v1.0.0`). | +| `--forge ` | `github`, `gitlab`, or `forgejo` (link validation). | +| `--domain ` | Map a custom domain to a forge (repeatable), e.g. `git.corp.com:gitlab`. | +| `--no-config` | Ignore all `heylogs.properties` files. | + +## Configuration via `heylogs.properties` + +Settings can be made persistent (and shared across CLI, Maven plugin, and +Enforcer) in a `heylogs.properties` file. Files are discovered by walking **up** +the directory tree from the changelog's directory; parent files load first and +**child values override parents** (Lombok-style). For list properties (`rules`, +`domains`) the child list **replaces** the parent list entirely. + +```properties +# heylogs.properties — project root +versioning=semver +tagging=prefix:v +forge=github + +# Rule severity overrides (comma-separated). Same id:severity grammar as --rule. +rules=dot-space-link-style:WARN,no-empty-group:OFF + +# Map custom domains to forges (comma-separated) +domains=git.company.com:gitlab,code.internal.org:github + +# Stop walking up to parent directories (e.g. monorepo module boundary) +config.stopBubbling=true +``` + +| Property | Description | Example | +|--------------|------------------------------|----------------------------------------------| +| `versioning` | Version validation scheme | `semver`, `calver:YYYY.MM.DD`, `regex:^\d+$` | +| `tagging` | Tag naming strategy | `prefix:v` | +| `forge` | Hosting platform | `github`, `gitlab`, `forgejo` | +| `rules` | Rule severity overrides | `no-empty-group:WARN,https:OFF` | +| `domains` | Custom forge domains | `git.company.com:gitlab` | + +Precedence note: `--rule` on the command line and the `rules` list in +`heylogs.properties` both express the same `id:severity` overrides. Use +`--no-config` to bypass the file hierarchy entirely and rely only on CLI flags +(useful in CI for explicit, reproducible config). + +A template `heylogs.properties` ships at the root of this repository. + +### Pattern: get a repo (or several) to "0 problems" without editing the changelog + +Because the file is **auto-discovered** and `rules=name:SEVERITY` accepts `OFF`, +rule-tuning can live entirely in configuration — no `CHANGELOG.md` edits needed. +This keeps a changelog a verbatim port of its upstream source while still passing +`heylogs check`. + +1. Run `heylogs check` and note every rule id that fires. +2. Put one `heylogs.properties` at the root, listing those rules at the severity + you want (`OFF` to silence, `WARN` to downgrade from `ERROR`): + + ```properties + # Uniform config: silence/downgrade the rules that fire, edit no changelogs + versioning=semver + forge=github + rules=dot-space-link-style:OFF,no-empty-group:OFF,release-date:WARN + ``` + +3. Re-run `heylogs check` until it reports 0. + +For several repositories, drop the **same** `heylogs.properties` in each (or place +one in a shared parent directory and let hierarchical discovery apply it to all, +unless `config.stopBubbling=true` blocks it). One uniform config can bring every +repo to 0 while the workflow and changelog contents stay identical to upstream. + +## Available rules + +Rules fall into three kinds: **format** (structure/formatting), **content** +(required sections, links, uniqueness), and **versioning** (version numbers and +tag refs). The table below lists every built-in rule and its **default** +severity. The reference description for each is in +[`docs/feature-rules.md`](docs/feature-rules.md). + +| ID | Default | What it enforces | +|----------------------------|---------|----------------------------------------------------------------------------------| +| `all-h2-contain-a-version` | ERROR | Every `##` heading parses as `[ref] - YYYY-MM-DD` or `[Unreleased]`. | +| `date-displayed` | ERROR | Every released version heading has a `YYYY-MM-DD` date (Unreleased exempt). | +| `for-humans` | ERROR | Exactly one `# Changelog` heading. | +| `latest-version-first` | ERROR | Released versions in reverse-chronological order; Unreleased on top. | +| `linkable` | ERROR | Every version heading is linkable (inline or reference-style with a definition). | +| `type-of-changes-grouped` | ERROR | Every `###` heading is one of Added/Changed/Deprecated/Removed/Fixed/Security. | +| `column-width` | OFF | Bullet lines ≤ 80 chars. Enable for a hard line-length policy. | +| `consistent-separator` | ERROR | One ref↔date separator style per file (`-`, `–`, or `—`). | +| `dot-space-link-style` | OFF | Trailing forge links preceded by `. ` (e.g. `Fix typo. [#42](…)`). | +| `duplicate-items` | ERROR | No two identical bullet items within the same group. | +| `forge-ref` | ERROR | Forge links use the canonical URL format for the detected forge. | +| `https` | ERROR | `http://` links must be `https://`. | +| `imbalanced-braces` | ERROR | No unmatched `{`/`}` in bullet text (outside code spans). | +| `no-empty-group` | ERROR | A `###` group must have at least one bullet item. | +| `no-empty-release` | ERROR | A released version must contain at least one item. | +| `no-link-brackets` | ERROR | Forge reference links not wrapped in `()` or `[]`. | +| `no-orphan-ref` | ERROR | Every reference-link definition is used at least once. | +| `no-version-regression` | ERROR | Version numbers don't decrease top-to-bottom (when a scheme is active). | +| `release-date` | WARN | Release dates are not in the future. | +| `tag-versioning` | ERROR | Version refs match the configured tag scheme (e.g. `v1.0.0`). | +| `unique-headings` | ERROR | No two version headings have identical text. | +| `unique-release` | ERROR | No two versions share the same `ref`. | +| `unknown-link-type` | WARN | Forge-matching reference defs whose link type can't be recognised. | +| `versioning-format` | ERROR | Version refs conform to the active scheme (SemVer/CalVer/custom). | + +Discover the rules installed in your environment (including extensions) with: + +```bash +heylogs list # human-readable; also lists formats, forges, schemes +heylogs list --format json +``` + +## Other commands + +All commands default to `CHANGELOG.md`, accept a positional file (or `-` for +stdin), and most support `--dry-run`. + +### Authoring / editing + +| Command | Purpose | Example | +|-----------|---------------------------------------------------------------------|---------------------------------------------------------------| +| `init` | Create a new changelog from a template (fails if it exists). | `heylogs init --project-url https://github.com/nbbrd/heylogs` | +| `push` | Add an entry to the Unreleased section (creates the group as needed).| `heylogs push -y added -m "Add custom themes"` | +| `fetch` | Add an entry from a forge issue/PR (full URL or short `#ref`). | `heylogs fetch -y fixed -i "#42"` | +| `note` | Set/replace the summary text after the Unreleased header. | `heylogs note -m "Performance improvements."` | +| `format` | Normalize ordering & markers (idempotent). `--check` for CI gate. | `heylogs format` · `heylogs format --check` | + +`push`/`fetch` change types (`-y`): `added`, `changed`, `deprecated`, +`removed`, `fixed`, `security`. + +### Releasing + +| Command | Purpose | Example | +|-----------|------------------------------------------------------|----------------------------------| +| `release` | Convert Unreleased changes into a new version entry. | `heylogs release --ref 1.0.0` | +| `yank` | Append `[YANKED]` to a release heading. | `heylogs yank -r 1.0.0` | + +### Inspecting / converting + +| Command | Purpose | Example | +|-----------|------------------------------------------------------------------|--------------------------------------------------| +| `scan` | Summarize content (release count, date range, forge, …). | `heylogs scan --format json` | +| `extract` | Filter/extract specific versions (e.g. latest only). | `heylogs extract --limit 1 --output latest.md` | +| `export` | Serialize the changelog to structured data (e.g. JSON). | `heylogs export --format json` | +| `import` | Rebuild a Markdown changelog from structured data (export's inverse). | `heylogs import changelog.json` | +| `list` | List installed resources: rules, formats, forges, schemes. | `heylogs list --format json` | + +Commands are composable (Unix-style) — `extract` and `export` read from stdin: + +```bash +heylogs extract --limit 1 | heylogs export - --format json +``` + +## Typical agent workflow + +```bash +# 1. Validate; tune rules for this project +heylogs check --rule dot-space-link-style:WARN --rule no-empty-group:OFF + +# 2. Normalize structure before committing +heylogs format + +# 3. Add changes as you work +heylogs push -y fixed -m "Fix parser memory leak" + +# 4. Gate in CI (no colors/feedback, fail on formatting drift) +heylogs --batch format --check +heylogs --batch check +``` + +In CI, prefer `--batch` (clean output, no ANSI) and consider `--no-config` for +fully explicit, reproducible configuration. + +--- + +See [`docs/`](docs/) for per-feature documentation and +[`docs/feature-matrix.md`](docs/feature-matrix.md) for support by usage mode. From 26bf1cb248d6aee8b7d90683f3ac106ae260fcd5 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Tue, 23 Jun 2026 01:51:00 +0200 Subject: [PATCH 2/4] docs: restructure SKILLS.md into Agent Skills convention Move the root SKILLS.md into skills/heylogs/ following the Agent Skills convention (the layout distributed by skills.sh / `npx skills`): - skills/heylogs/SKILL.md: YAML frontmatter (name + trigger-phrase description) plus a concise guide. Body stays agent-generic; only the frontmatter is spec-shaped. - skills/heylogs/references/: rule table, heylogs.properties semantics, CLI runners, and per-command tables split out for progressive loading. - skills/heylogs/README.md: install guide (`npx skills add nbbrd/heylogs --skill heylogs`). Single cohesive `heylogs` skill (not per-command). No skills-lock.json (that is a consumer lockfile, not needed to publish a skill). Repoint the AGENTS.md and README.md links to the skill. Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 2 +- README.md | 2 +- SKILLS.md | 286 ----------------------- skills/heylogs/README.md | 58 +++++ skills/heylogs/SKILL.md | 169 ++++++++++++++ skills/heylogs/references/commands.md | 54 +++++ skills/heylogs/references/config-file.md | 63 +++++ skills/heylogs/references/rules.md | 45 ++++ skills/heylogs/references/running-cli.md | 61 +++++ 9 files changed, 452 insertions(+), 288 deletions(-) delete mode 100644 SKILLS.md create mode 100644 skills/heylogs/README.md create mode 100644 skills/heylogs/SKILL.md create mode 100644 skills/heylogs/references/commands.md create mode 100644 skills/heylogs/references/config-file.md create mode 100644 skills/heylogs/references/rules.md create mode 100644 skills/heylogs/references/running-cli.md diff --git a/AGENTS.md b/AGENTS.md index b8621e9d..49440543 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ Heylogs is a Java 8+ multi-module Maven project for validating and releasing changelogs in [Keep a Changelog](https://keepachangelog.com) format. It parses Markdown into an AST (via [flexmark-java](https://github.com/vsch/flexmark-java)) and operates on the tree. -> **This file** covers building and contributing to Heylogs itself. To *use* Heylogs (run `check`, tune rules, configure `heylogs.properties`) on a changelog, see [`SKILLS.md`](SKILLS.md). +> **This file** covers building and contributing to Heylogs itself. To *use* Heylogs (run `check`, tune rules, configure `heylogs.properties`) on a changelog, see the [`heylogs` skill](skills/heylogs/SKILL.md). ## Architecture diff --git a/README.md b/README.md index b4313572..7b658b04 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ Heylogs is available in multiple formats to fit your workflow: - **[Maven Enforcer rules](docs/usage-enforcer-rules.md)** - Enforce changelog quality in builds - **[CI/CD pipelines](docs/usage-pipelines.md)** - Integrate into CI/CD environments -> Using an AI coding assistant? [`SKILLS.md`](SKILLS.md) is an agent-generic guide to running `check`, tuning rules, and configuring `heylogs.properties`. +> Using an AI coding assistant? The [`heylogs` skill](skills/heylogs/SKILL.md) is an agent-generic guide to running `check`, tuning rules, and configuring `heylogs.properties`. Install it with `npx skills add nbbrd/heylogs --skill heylogs` ([details](skills/heylogs/README.md)). ## Features diff --git a/SKILLS.md b/SKILLS.md deleted file mode 100644 index 3e8d1d71..00000000 --- a/SKILLS.md +++ /dev/null @@ -1,286 +0,0 @@ -# SKILLS.md — Working with Heylogs changelogs - -This file is an agent-generic guide (works with any coding assistant) for using -the [Heylogs](https://github.com/nbbrd/heylogs) CLI to validate and maintain -[Keep a Changelog](https://keepachangelog.com)–formatted `CHANGELOG.md` files. - -For project architecture and contribution conventions, see [`AGENTS.md`](AGENTS.md). -Full feature docs live under [`docs/`](docs/). - -## What Heylogs does - -Heylogs parses a Markdown changelog into an AST and validates/transforms it. -It is available as a CLI, a Maven plugin, Maven Enforcer rules, and a Java -library. This guide focuses on the **CLI**. - -```bash -heylogs [] -``` - -## Running the CLI - -Examples below write `heylogs …` for brevity. If you don't have a native binary -on `PATH` (e.g. via Homebrew/Scoop), run the same commands through one of the -options below — substitute the whole invocation for `heylogs`. - -### With gg.cmd (recommended — no prerequisites) - -[`gg.cmd`](https://github.com/eirikb/gg/) bootstraps both a JDK and JBang on -demand, so contributors and CI need **nothing** pre-installed. Download it once -into the repo: - -```bash -curl -L ggcmd.io > gg.cmd && chmod +x gg.cmd -``` - -Then run heylogs via JBang through it: - -```bash -./gg.cmd jbang com.github.nbbrd.heylogs:heylogs-cli:0.18.1:bin check CHANGELOG.md -``` - -### With JBang directly - -If JBang is already available: - -```bash -jbang com.github.nbbrd.heylogs:heylogs-cli:0.18.1:bin check CHANGELOG.md -``` - -Install JBang with the universal (all-platforms) installer if needed: - -```bash -# Linux / macOS / Windows (bash) -curl -Ls https://sh.jbang.dev | bash -s - app setup -# Windows PowerShell -iex "& { $(iwr -useb https://ps.jbang.dev) } app setup" -``` - -JBang can also resolve the latest release from the project's catalog -(`heylogs@nbbrd`, requires `trust: https://github.com/nbbrd/jbang-catalog`). -Replace `0.18.1` with the version you want; see -[releases](https://github.com/nbbrd/heylogs/releases/latest). Other install -methods (Homebrew, Scoop, plain jar) are in [`docs/usage-cli.md`](docs/usage-cli.md). - -Global options available on every command: - -| Option | Purpose | -|------------------------|-------------------------------------------------------------------| -| `--debug` | Print the full stack trace on error. | -| `--batch` | Suppress progress feedback on stderr and disable ANSI colors (CI).| -| `-D=` | Set a Java system property (repeatable). | - -Most commands default to `CHANGELOG.md` and accept a positional file argument -(use `-` for stdin). File-modifying commands print a one-line status to -**stderr** (`+` modified, `!` needs attention, `~` dry-run, `=` no-op) and most -support `--dry-run`. - -## Primary task: `check` - -Validate a changelog against the rule set: - -```bash -heylogs check # checks CHANGELOG.md -heylogs check path/to/CHANGELOG.md -heylogs check --recursive # find changelogs recursively -heylogs check --format json --output result.json -``` - -Output formats: `stylish` (default), `json`, `github-actions`, … (run -`heylogs list` to see what's installed). - -### Adjusting which rules run and their severity - -Each rule has a severity: `ERROR`, `WARN`, `INFO`, or `OFF` (disabled). Override -per invocation with repeated `--rule :` options: - -```bash -# Enable dot-space-link-style (off by default) as a warning, and disable no-empty-group -heylogs check --rule dot-space-link-style:WARN --rule no-empty-group:OFF -``` - -This is the canonical way to tune rules ad hoc. For persistent configuration, -use `heylogs.properties` (below). - -### Other `check` configuration options - -| Option | Purpose | -|---------------------------|--------------------------------------------------------| -| `--rule ` | Override a rule's severity (repeatable). | -| `--versioning ` | Versioning scheme: `semver`, `calver:YYYY.MM.DD`, `regex:…`. | -| `--tagging ` | Tag naming, e.g. `prefix:v` (for `v1.0.0`). | -| `--forge ` | `github`, `gitlab`, or `forgejo` (link validation). | -| `--domain ` | Map a custom domain to a forge (repeatable), e.g. `git.corp.com:gitlab`. | -| `--no-config` | Ignore all `heylogs.properties` files. | - -## Configuration via `heylogs.properties` - -Settings can be made persistent (and shared across CLI, Maven plugin, and -Enforcer) in a `heylogs.properties` file. Files are discovered by walking **up** -the directory tree from the changelog's directory; parent files load first and -**child values override parents** (Lombok-style). For list properties (`rules`, -`domains`) the child list **replaces** the parent list entirely. - -```properties -# heylogs.properties — project root -versioning=semver -tagging=prefix:v -forge=github - -# Rule severity overrides (comma-separated). Same id:severity grammar as --rule. -rules=dot-space-link-style:WARN,no-empty-group:OFF - -# Map custom domains to forges (comma-separated) -domains=git.company.com:gitlab,code.internal.org:github - -# Stop walking up to parent directories (e.g. monorepo module boundary) -config.stopBubbling=true -``` - -| Property | Description | Example | -|--------------|------------------------------|----------------------------------------------| -| `versioning` | Version validation scheme | `semver`, `calver:YYYY.MM.DD`, `regex:^\d+$` | -| `tagging` | Tag naming strategy | `prefix:v` | -| `forge` | Hosting platform | `github`, `gitlab`, `forgejo` | -| `rules` | Rule severity overrides | `no-empty-group:WARN,https:OFF` | -| `domains` | Custom forge domains | `git.company.com:gitlab` | - -Precedence note: `--rule` on the command line and the `rules` list in -`heylogs.properties` both express the same `id:severity` overrides. Use -`--no-config` to bypass the file hierarchy entirely and rely only on CLI flags -(useful in CI for explicit, reproducible config). - -A template `heylogs.properties` ships at the root of this repository. - -### Pattern: get a repo (or several) to "0 problems" without editing the changelog - -Because the file is **auto-discovered** and `rules=name:SEVERITY` accepts `OFF`, -rule-tuning can live entirely in configuration — no `CHANGELOG.md` edits needed. -This keeps a changelog a verbatim port of its upstream source while still passing -`heylogs check`. - -1. Run `heylogs check` and note every rule id that fires. -2. Put one `heylogs.properties` at the root, listing those rules at the severity - you want (`OFF` to silence, `WARN` to downgrade from `ERROR`): - - ```properties - # Uniform config: silence/downgrade the rules that fire, edit no changelogs - versioning=semver - forge=github - rules=dot-space-link-style:OFF,no-empty-group:OFF,release-date:WARN - ``` - -3. Re-run `heylogs check` until it reports 0. - -For several repositories, drop the **same** `heylogs.properties` in each (or place -one in a shared parent directory and let hierarchical discovery apply it to all, -unless `config.stopBubbling=true` blocks it). One uniform config can bring every -repo to 0 while the workflow and changelog contents stay identical to upstream. - -## Available rules - -Rules fall into three kinds: **format** (structure/formatting), **content** -(required sections, links, uniqueness), and **versioning** (version numbers and -tag refs). The table below lists every built-in rule and its **default** -severity. The reference description for each is in -[`docs/feature-rules.md`](docs/feature-rules.md). - -| ID | Default | What it enforces | -|----------------------------|---------|----------------------------------------------------------------------------------| -| `all-h2-contain-a-version` | ERROR | Every `##` heading parses as `[ref] - YYYY-MM-DD` or `[Unreleased]`. | -| `date-displayed` | ERROR | Every released version heading has a `YYYY-MM-DD` date (Unreleased exempt). | -| `for-humans` | ERROR | Exactly one `# Changelog` heading. | -| `latest-version-first` | ERROR | Released versions in reverse-chronological order; Unreleased on top. | -| `linkable` | ERROR | Every version heading is linkable (inline or reference-style with a definition). | -| `type-of-changes-grouped` | ERROR | Every `###` heading is one of Added/Changed/Deprecated/Removed/Fixed/Security. | -| `column-width` | OFF | Bullet lines ≤ 80 chars. Enable for a hard line-length policy. | -| `consistent-separator` | ERROR | One ref↔date separator style per file (`-`, `–`, or `—`). | -| `dot-space-link-style` | OFF | Trailing forge links preceded by `. ` (e.g. `Fix typo. [#42](…)`). | -| `duplicate-items` | ERROR | No two identical bullet items within the same group. | -| `forge-ref` | ERROR | Forge links use the canonical URL format for the detected forge. | -| `https` | ERROR | `http://` links must be `https://`. | -| `imbalanced-braces` | ERROR | No unmatched `{`/`}` in bullet text (outside code spans). | -| `no-empty-group` | ERROR | A `###` group must have at least one bullet item. | -| `no-empty-release` | ERROR | A released version must contain at least one item. | -| `no-link-brackets` | ERROR | Forge reference links not wrapped in `()` or `[]`. | -| `no-orphan-ref` | ERROR | Every reference-link definition is used at least once. | -| `no-version-regression` | ERROR | Version numbers don't decrease top-to-bottom (when a scheme is active). | -| `release-date` | WARN | Release dates are not in the future. | -| `tag-versioning` | ERROR | Version refs match the configured tag scheme (e.g. `v1.0.0`). | -| `unique-headings` | ERROR | No two version headings have identical text. | -| `unique-release` | ERROR | No two versions share the same `ref`. | -| `unknown-link-type` | WARN | Forge-matching reference defs whose link type can't be recognised. | -| `versioning-format` | ERROR | Version refs conform to the active scheme (SemVer/CalVer/custom). | - -Discover the rules installed in your environment (including extensions) with: - -```bash -heylogs list # human-readable; also lists formats, forges, schemes -heylogs list --format json -``` - -## Other commands - -All commands default to `CHANGELOG.md`, accept a positional file (or `-` for -stdin), and most support `--dry-run`. - -### Authoring / editing - -| Command | Purpose | Example | -|-----------|---------------------------------------------------------------------|---------------------------------------------------------------| -| `init` | Create a new changelog from a template (fails if it exists). | `heylogs init --project-url https://github.com/nbbrd/heylogs` | -| `push` | Add an entry to the Unreleased section (creates the group as needed).| `heylogs push -y added -m "Add custom themes"` | -| `fetch` | Add an entry from a forge issue/PR (full URL or short `#ref`). | `heylogs fetch -y fixed -i "#42"` | -| `note` | Set/replace the summary text after the Unreleased header. | `heylogs note -m "Performance improvements."` | -| `format` | Normalize ordering & markers (idempotent). `--check` for CI gate. | `heylogs format` · `heylogs format --check` | - -`push`/`fetch` change types (`-y`): `added`, `changed`, `deprecated`, -`removed`, `fixed`, `security`. - -### Releasing - -| Command | Purpose | Example | -|-----------|------------------------------------------------------|----------------------------------| -| `release` | Convert Unreleased changes into a new version entry. | `heylogs release --ref 1.0.0` | -| `yank` | Append `[YANKED]` to a release heading. | `heylogs yank -r 1.0.0` | - -### Inspecting / converting - -| Command | Purpose | Example | -|-----------|------------------------------------------------------------------|--------------------------------------------------| -| `scan` | Summarize content (release count, date range, forge, …). | `heylogs scan --format json` | -| `extract` | Filter/extract specific versions (e.g. latest only). | `heylogs extract --limit 1 --output latest.md` | -| `export` | Serialize the changelog to structured data (e.g. JSON). | `heylogs export --format json` | -| `import` | Rebuild a Markdown changelog from structured data (export's inverse). | `heylogs import changelog.json` | -| `list` | List installed resources: rules, formats, forges, schemes. | `heylogs list --format json` | - -Commands are composable (Unix-style) — `extract` and `export` read from stdin: - -```bash -heylogs extract --limit 1 | heylogs export - --format json -``` - -## Typical agent workflow - -```bash -# 1. Validate; tune rules for this project -heylogs check --rule dot-space-link-style:WARN --rule no-empty-group:OFF - -# 2. Normalize structure before committing -heylogs format - -# 3. Add changes as you work -heylogs push -y fixed -m "Fix parser memory leak" - -# 4. Gate in CI (no colors/feedback, fail on formatting drift) -heylogs --batch format --check -heylogs --batch check -``` - -In CI, prefer `--batch` (clean output, no ANSI) and consider `--no-config` for -fully explicit, reproducible configuration. - ---- - -See [`docs/`](docs/) for per-feature documentation and -[`docs/feature-matrix.md`](docs/feature-matrix.md) for support by usage mode. diff --git a/skills/heylogs/README.md b/skills/heylogs/README.md new file mode 100644 index 00000000..186263a0 --- /dev/null +++ b/skills/heylogs/README.md @@ -0,0 +1,58 @@ +# Install the `heylogs` skill + +The `heylogs` skill teaches an AI coding agent how to validate and maintain +[Keep a Changelog](https://keepachangelog.com)–formatted `CHANGELOG.md` files +with the **[Heylogs](https://github.com/nbbrd/heylogs)** CLI — running `check`, +tuning rules, and configuring `heylogs.properties`. The skill definition is in +[`SKILL.md`](SKILL.md), with details under [`references/`](references/). + +Skills can be installed in many ways — refer to your agent's documentation for +the available options. Below we use [skills](https://github.com/vercel-labs/skills) +(`npx skills`, see [skills.sh](https://skills.sh)), which installs a skill in a +single step across multiple agents (Claude Code, OpenCode, GitHub Copilot, +Codex, and more) in a unified way. + +## Prerequisites + +Node.js (v18+) is required only for the `npx skills` method. Install it via your +system's package manager or from [nodejs.org](https://nodejs.org). + +The skill drives the Heylogs CLI; if it isn't on your `PATH`, the skill itself +explains how to run it with no prerequisites via `gg.cmd` or JBang (see +[`references/running-cli.md`](references/running-cli.md)). + +## Installation + +```bash +npx skills add nbbrd/heylogs --skill heylogs +``` + +The installer fetches the skill from the repository, asks which agents to install +it for (several universal agents incl. Claude Code are enabled by default), then +the scope (project vs **Global** — recommended so it's available in every +project) and method (**Symlink** recommended — updates reflect immediately). +Confirm to finish. + +Non-interactive (CI-friendly) install for Claude Code, global: + +```bash +npx skills add nbbrd/heylogs --skill heylogs -g -a claude-code -y +``` + +## Alternative: manual installation + +If you prefer not to use `npx skills`, download the skill folder +[`skills/heylogs/`](.) and register it as a local skill folder per your agent's +documentation (no Node.js required). + +## Update + +```bash +npx skills update heylogs +``` + +## Usage + +Once installed, invoke `/heylogs` in the selected agent, or just ask it to check, +fix, or release a changelog — the skill's `description` triggers it automatically. +See the [skill definition](SKILL.md) for full capabilities. diff --git a/skills/heylogs/SKILL.md b/skills/heylogs/SKILL.md new file mode 100644 index 00000000..5a4bee04 --- /dev/null +++ b/skills/heylogs/SKILL.md @@ -0,0 +1,169 @@ +--- +name: heylogs +description: > + Validate and maintain Keep a Changelog–formatted CHANGELOG.md files with the + Heylogs CLI. Use this skill whenever the user asks to check, lint, validate, + fix, format, or release a changelog, sees Heylogs rule violations (e.g. + no-empty-group, latest-version-first, forge-ref), wants to get a repo to + "0 problems" via heylogs.properties without editing the changelog, or needs to + add/extract/export changelog entries. Covers the `check` command and rule + configuration (primary task), persistent `heylogs.properties` config, every + built-in rule, the authoring/releasing/inspecting commands, and how to run the + CLI with no prerequisites via gg.cmd or JBang. +metadata: + source: https://github.com/nbbrd/heylogs + agent-generic: "true" +--- + +# Working with Heylogs changelogs + +Agent-generic guide (works with any coding assistant) for using the +[Heylogs](https://github.com/nbbrd/heylogs) CLI to validate and maintain +[Keep a Changelog](https://keepachangelog.com)–formatted `CHANGELOG.md` files. + +For project architecture and contribution conventions, see [`AGENTS.md`](../../AGENTS.md). +Full feature docs live under [`docs/`](../../docs/). + +## What Heylogs does + +Heylogs parses a Markdown changelog into an AST and validates/transforms it. +It is available as a CLI, a Maven plugin, Maven Enforcer rules, and a Java +library. This skill focuses on the **CLI**. + +```bash +heylogs [] +``` + +Examples below write `heylogs …` for brevity. If you don't have a native binary +on `PATH`, run the same command through `gg.cmd` (no prerequisites) or JBang — +see [`references/running-cli.md`](references/running-cli.md). Quickest one-liner: + +```bash +./gg.cmd jbang com.github.nbbrd.heylogs:heylogs-cli:0.18.1:bin check CHANGELOG.md +``` + +Most commands default to `CHANGELOG.md` and accept a positional file argument +(use `-` for stdin). File-modifying commands print a one-line status to +**stderr** (`+` modified, `!` needs attention, `~` dry-run, `=` no-op) and most +support `--dry-run`. Global options (`--debug`, `--batch`, `-D=`) are +documented in [`references/running-cli.md`](references/running-cli.md). + +## Primary task: `check` + +Validate a changelog against the rule set: + +```bash +heylogs check # checks CHANGELOG.md +heylogs check path/to/CHANGELOG.md +heylogs check --recursive # find changelogs recursively +heylogs check --format json --output result.json +``` + +Output formats: `stylish` (default), `json`, `github-actions`, … (run +`heylogs list` to see what's installed). + +### Adjusting which rules run and their severity + +Each rule has a severity: `ERROR`, `WARN`, `INFO`, or `OFF` (disabled). Override +per invocation with repeated `--rule :` options: + +```bash +# Enable dot-space-link-style (off by default) as a warning, and disable no-empty-group +heylogs check --rule dot-space-link-style:WARN --rule no-empty-group:OFF +``` + +This is the canonical way to tune rules ad hoc. For persistent configuration, +use `heylogs.properties` (below). Other `check` options — `--versioning`, +`--tagging`, `--forge`, `--domain`, `--no-config` — are listed in +[`references/commands.md`](references/commands.md#check-options). + +## Configuration via `heylogs.properties` + +Settings can be made persistent (and shared across CLI, Maven plugin, and +Enforcer) in a `heylogs.properties` file. Files are discovered by walking **up** +the directory tree from the changelog's directory; parent files load first and +**child values override parents**. A template ships at the root of the Heylogs +repository. Full discovery/override/`stopBubbling` semantics and the property +table are in [`references/config-file.md`](references/config-file.md). + +```properties +# heylogs.properties — project root +versioning=semver +tagging=prefix:v +forge=github +rules=dot-space-link-style:WARN,no-empty-group:OFF +``` + +### Pattern: get a repo (or several) to "0 problems" without editing the changelog + +Because the file is **auto-discovered** and `rules=name:SEVERITY` accepts `OFF`, +rule-tuning can live entirely in configuration — no `CHANGELOG.md` edits needed. +This keeps a changelog a verbatim port of its upstream source while still passing +`heylogs check`. + +1. Run `heylogs check` and note every rule id that fires. +2. Put one `heylogs.properties` at the root, listing those rules at the severity + you want (`OFF` to silence, `WARN` to downgrade from `ERROR`): + + ```properties + # Uniform config: silence/downgrade the rules that fire, edit no changelogs + versioning=semver + forge=github + rules=dot-space-link-style:OFF,no-empty-group:OFF,release-date:WARN + ``` + +3. Re-run `heylogs check` until it reports 0. + +For several repositories, drop the **same** `heylogs.properties` in each (or place +one in a shared parent directory and let hierarchical discovery apply it to all, +unless `config.stopBubbling=true` blocks it). + +## Available rules + +Rules fall into three kinds: **format** (structure/formatting), **content** +(required sections, links, uniqueness), and **versioning** (version numbers and +tag refs). The full table of every built-in rule with its default severity is in +[`references/rules.md`](references/rules.md). Discover the rules installed in +your environment (including extensions) with: + +```bash +heylogs list # human-readable; also lists formats, forges, schemes +heylogs list --format json +``` + +## Other commands + +All commands default to `CHANGELOG.md`, accept a positional file (or `-` for +stdin), and most support `--dry-run`: + +- **Authoring/editing:** `init`, `push`, `fetch`, `note`, `format` +- **Releasing:** `release`, `yank` +- **Inspecting/converting:** `scan`, `extract`, `export`, `import`, `list` + +Full purpose + examples for each, plus composability notes, are in +[`references/commands.md`](references/commands.md). + +## Typical agent workflow + +```bash +# 1. Validate; tune rules for this project +heylogs check --rule dot-space-link-style:WARN --rule no-empty-group:OFF + +# 2. Normalize structure before committing +heylogs format + +# 3. Add changes as you work +heylogs push -y fixed -m "Fix parser memory leak" + +# 4. Gate in CI (no colors/feedback, fail on formatting drift) +heylogs --batch format --check +heylogs --batch check +``` + +In CI, prefer `--batch` (clean output, no ANSI) and consider `--no-config` for +fully explicit, reproducible configuration. + +--- + +See [`docs/`](../../docs/) for per-feature documentation and +[`docs/feature-matrix.md`](../../docs/feature-matrix.md) for support by usage mode. diff --git a/skills/heylogs/references/commands.md b/skills/heylogs/references/commands.md new file mode 100644 index 00000000..6814062f --- /dev/null +++ b/skills/heylogs/references/commands.md @@ -0,0 +1,54 @@ +# Heylogs commands reference + +All commands default to `CHANGELOG.md`, accept a positional file (or `-` for +stdin), and most support `--dry-run`. + +## `check` options + +`check` is the primary task (see [`../SKILL.md`](../SKILL.md)). Beyond +`--rule :`: + +| Option | Purpose | +|---------------------------|--------------------------------------------------------| +| `--rule ` | Override a rule's severity (repeatable). | +| `--versioning ` | Versioning scheme: `semver`, `calver:YYYY.MM.DD`, `regex:…`. | +| `--tagging ` | Tag naming, e.g. `prefix:v` (for `v1.0.0`). | +| `--forge ` | `github`, `gitlab`, or `forgejo` (link validation). | +| `--domain ` | Map a custom domain to a forge (repeatable), e.g. `git.corp.com:gitlab`. | +| `--no-config` | Ignore all `heylogs.properties` files. | + +## Authoring / editing + +| Command | Purpose | Example | +|-----------|---------------------------------------------------------------------|---------------------------------------------------------------| +| `init` | Create a new changelog from a template (fails if it exists). | `heylogs init --project-url https://github.com/nbbrd/heylogs` | +| `push` | Add an entry to the Unreleased section (creates the group as needed).| `heylogs push -y added -m "Add custom themes"` | +| `fetch` | Add an entry from a forge issue/PR (full URL or short `#ref`). | `heylogs fetch -y fixed -i "#42"` | +| `note` | Set/replace the summary text after the Unreleased header. | `heylogs note -m "Performance improvements."` | +| `format` | Normalize ordering & markers (idempotent). `--check` for CI gate. | `heylogs format` · `heylogs format --check` | + +`push`/`fetch` change types (`-y`): `added`, `changed`, `deprecated`, +`removed`, `fixed`, `security`. + +## Releasing + +| Command | Purpose | Example | +|-----------|------------------------------------------------------|----------------------------------| +| `release` | Convert Unreleased changes into a new version entry. | `heylogs release --ref 1.0.0` | +| `yank` | Append `[YANKED]` to a release heading. | `heylogs yank -r 1.0.0` | + +## Inspecting / converting + +| Command | Purpose | Example | +|-----------|------------------------------------------------------------------|--------------------------------------------------| +| `scan` | Summarize content (release count, date range, forge, …). | `heylogs scan --format json` | +| `extract` | Filter/extract specific versions (e.g. latest only). | `heylogs extract --limit 1 --output latest.md` | +| `export` | Serialize the changelog to structured data (e.g. JSON). | `heylogs export --format json` | +| `import` | Rebuild a Markdown changelog from structured data (export's inverse). | `heylogs import changelog.json` | +| `list` | List installed resources: rules, formats, forges, schemes. | `heylogs list --format json` | + +Commands are composable (Unix-style) — `extract` and `export` read from stdin: + +```bash +heylogs extract --limit 1 | heylogs export - --format json +``` diff --git a/skills/heylogs/references/config-file.md b/skills/heylogs/references/config-file.md new file mode 100644 index 00000000..201b4316 --- /dev/null +++ b/skills/heylogs/references/config-file.md @@ -0,0 +1,63 @@ +# Configuration via `heylogs.properties` + +Settings can be made persistent (and shared across CLI, Maven plugin, and +Enforcer) in a `heylogs.properties` file. Files are discovered by walking **up** +the directory tree from the changelog's directory; parent files load first and +**child values override parents** (Lombok-style). For list properties (`rules`, +`domains`) the child list **replaces** the parent list entirely. + +```properties +# heylogs.properties — project root +versioning=semver +tagging=prefix:v +forge=github + +# Rule severity overrides (comma-separated). Same id:severity grammar as --rule. +rules=dot-space-link-style:WARN,no-empty-group:OFF + +# Map custom domains to forges (comma-separated) +domains=git.company.com:gitlab,code.internal.org:github + +# Stop walking up to parent directories (e.g. monorepo module boundary) +config.stopBubbling=true +``` + +| Property | Description | Example | +|--------------|------------------------------|----------------------------------------------| +| `versioning` | Version validation scheme | `semver`, `calver:YYYY.MM.DD`, `regex:^\d+$` | +| `tagging` | Tag naming strategy | `prefix:v` | +| `forge` | Hosting platform | `github`, `gitlab`, `forgejo` | +| `rules` | Rule severity overrides | `no-empty-group:WARN,https:OFF` | +| `domains` | Custom forge domains | `git.company.com:gitlab` | + +Precedence note: `--rule` on the command line and the `rules` list in +`heylogs.properties` both express the same `id:severity` overrides. Use +`--no-config` to bypass the file hierarchy entirely and rely only on CLI flags +(useful in CI for explicit, reproducible config). + +A template `heylogs.properties` ships at the root of the Heylogs repository. + +## Pattern: get a repo (or several) to "0 problems" without editing the changelog + +Because the file is **auto-discovered** and `rules=name:SEVERITY` accepts `OFF`, +rule-tuning can live entirely in configuration — no `CHANGELOG.md` edits needed. +This keeps a changelog a verbatim port of its upstream source while still passing +`heylogs check`. + +1. Run `heylogs check` and note every rule id that fires. +2. Put one `heylogs.properties` at the root, listing those rules at the severity + you want (`OFF` to silence, `WARN` to downgrade from `ERROR`): + + ```properties + # Uniform config: silence/downgrade the rules that fire, edit no changelogs + versioning=semver + forge=github + rules=dot-space-link-style:OFF,no-empty-group:OFF,release-date:WARN + ``` + +3. Re-run `heylogs check` until it reports 0. + +For several repositories, drop the **same** `heylogs.properties` in each (or place +one in a shared parent directory and let hierarchical discovery apply it to all, +unless `config.stopBubbling=true` blocks it). One uniform config can bring every +repo to 0 while the workflow and changelog contents stay identical to upstream. diff --git a/skills/heylogs/references/rules.md b/skills/heylogs/references/rules.md new file mode 100644 index 00000000..c67d7868 --- /dev/null +++ b/skills/heylogs/references/rules.md @@ -0,0 +1,45 @@ +# Heylogs built-in rules + +Rules fall into three kinds: **format** (structure/formatting), **content** +(required sections, links, uniqueness), and **versioning** (version numbers and +tag refs). The table below lists every built-in rule and its **default** +severity. The reference description for each is in +[`docs/feature-rules.md`](../../../docs/feature-rules.md). + +| ID | Default | What it enforces | +|----------------------------|---------|----------------------------------------------------------------------------------| +| `all-h2-contain-a-version` | ERROR | Every `##` heading parses as `[ref] - YYYY-MM-DD` or `[Unreleased]`. | +| `date-displayed` | ERROR | Every released version heading has a `YYYY-MM-DD` date (Unreleased exempt). | +| `for-humans` | ERROR | Exactly one `# Changelog` heading. | +| `latest-version-first` | ERROR | Released versions in reverse-chronological order; Unreleased on top. | +| `linkable` | ERROR | Every version heading is linkable (inline or reference-style with a definition). | +| `type-of-changes-grouped` | ERROR | Every `###` heading is one of Added/Changed/Deprecated/Removed/Fixed/Security. | +| `column-width` | OFF | Bullet lines ≤ 80 chars. Enable for a hard line-length policy. | +| `consistent-separator` | ERROR | One ref↔date separator style per file (`-`, `–`, or `—`). | +| `dot-space-link-style` | OFF | Trailing forge links preceded by `. ` (e.g. `Fix typo. [#42](…)`). | +| `duplicate-items` | ERROR | No two identical bullet items within the same group. | +| `forge-ref` | ERROR | Forge links use the canonical URL format for the detected forge. | +| `https` | ERROR | `http://` links must be `https://`. | +| `imbalanced-braces` | ERROR | No unmatched `{`/`}` in bullet text (outside code spans). | +| `no-empty-group` | ERROR | A `###` group must have at least one bullet item. | +| `no-empty-release` | ERROR | A released version must contain at least one item. | +| `no-link-brackets` | ERROR | Forge reference links not wrapped in `()` or `[]`. | +| `no-orphan-ref` | ERROR | Every reference-link definition is used at least once. | +| `no-version-regression` | ERROR | Version numbers don't decrease top-to-bottom (when a scheme is active). | +| `release-date` | WARN | Release dates are not in the future. | +| `tag-versioning` | ERROR | Version refs match the configured tag scheme (e.g. `v1.0.0`). | +| `unique-headings` | ERROR | No two version headings have identical text. | +| `unique-release` | ERROR | No two versions share the same `ref`. | +| `unknown-link-type` | WARN | Forge-matching reference defs whose link type can't be recognised. | +| `versioning-format` | ERROR | Version refs conform to the active scheme (SemVer/CalVer/custom). | + +Discover the rules installed in your environment (including extensions) with: + +```bash +heylogs list # human-readable; also lists formats, forges, schemes +heylogs list --format json +``` + +Override any rule's severity ad hoc with `--rule :` (`ERROR`, +`WARN`, `INFO`, `OFF`), or persistently via the `rules` list in +`heylogs.properties` — see [`config-file.md`](config-file.md). diff --git a/skills/heylogs/references/running-cli.md b/skills/heylogs/references/running-cli.md new file mode 100644 index 00000000..6fec8507 --- /dev/null +++ b/skills/heylogs/references/running-cli.md @@ -0,0 +1,61 @@ +# Running the Heylogs CLI + +Examples in [`../SKILL.md`](../SKILL.md) write `heylogs …` for brevity. If you +don't have a native binary on `PATH` (e.g. via Homebrew/Scoop), run the same +commands through one of the options below — substitute the whole invocation for +`heylogs`. + +## With gg.cmd (recommended — no prerequisites) + +[`gg.cmd`](https://github.com/eirikb/gg/) bootstraps both a JDK and JBang on +demand, so contributors and CI need **nothing** pre-installed. Download it once +into the repo: + +```bash +curl -L ggcmd.io > gg.cmd && chmod +x gg.cmd +``` + +Then run heylogs via JBang through it: + +```bash +./gg.cmd jbang com.github.nbbrd.heylogs:heylogs-cli:0.18.1:bin check CHANGELOG.md +``` + +## With JBang directly + +If JBang is already available: + +```bash +jbang com.github.nbbrd.heylogs:heylogs-cli:0.18.1:bin check CHANGELOG.md +``` + +Install JBang with the universal (all-platforms) installer if needed: + +```bash +# Linux / macOS / Windows (bash) +curl -Ls https://sh.jbang.dev | bash -s - app setup +# Windows PowerShell +iex "& { $(iwr -useb https://ps.jbang.dev) } app setup" +``` + +JBang can also resolve the latest release from the project's catalog +(`heylogs@nbbrd`, requires `trust: https://github.com/nbbrd/jbang-catalog`). +Replace `0.18.1` with the version you want; see +[releases](https://github.com/nbbrd/heylogs/releases/latest). Other install +methods (Homebrew, Scoop, plain jar) are in +[`docs/usage-cli.md`](../../../docs/usage-cli.md). + +## Global options + +Available on every command: + +| Option | Purpose | +|------------------------|-------------------------------------------------------------------| +| `--debug` | Print the full stack trace on error. | +| `--batch` | Suppress progress feedback on stderr and disable ANSI colors (CI).| +| `-D=` | Set a Java system property (repeatable). | + +Most commands default to `CHANGELOG.md` and accept a positional file argument +(use `-` for stdin). File-modifying commands print a one-line status to +**stderr** (`+` modified, `!` needs attention, `~` dry-run, `=` no-op) and most +support `--dry-run`. From 3e24d0e8ea08d8c35a6c4d090da80e62fe0a0ba7 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Tue, 23 Jun 2026 02:29:58 +0200 Subject: [PATCH 3/4] docs: run CLI via JBang zero-install one-liner instead of gg.cmd Replace gg.cmd bootstrapping with JBang's install-script pipe (curl -Ls https://sh.jbang.dev | bash -s - ...) and document JBANG_USE_NATIVE=true for near-instant startup via JBang's native binary. Co-Authored-By: Claude Opus 4.8 --- skills/heylogs/README.md | 2 +- skills/heylogs/SKILL.md | 9 ++++---- skills/heylogs/references/running-cli.md | 27 +++++++++++++----------- 3 files changed, 21 insertions(+), 17 deletions(-) diff --git a/skills/heylogs/README.md b/skills/heylogs/README.md index 186263a0..584f2b4b 100644 --- a/skills/heylogs/README.md +++ b/skills/heylogs/README.md @@ -18,7 +18,7 @@ Node.js (v18+) is required only for the `npx skills` method. Install it via your system's package manager or from [nodejs.org](https://nodejs.org). The skill drives the Heylogs CLI; if it isn't on your `PATH`, the skill itself -explains how to run it with no prerequisites via `gg.cmd` or JBang (see +explains how to run it with no prerequisites via JBang (see [`references/running-cli.md`](references/running-cli.md)). ## Installation diff --git a/skills/heylogs/SKILL.md b/skills/heylogs/SKILL.md index 5a4bee04..965ecd02 100644 --- a/skills/heylogs/SKILL.md +++ b/skills/heylogs/SKILL.md @@ -9,7 +9,7 @@ description: > add/extract/export changelog entries. Covers the `check` command and rule configuration (primary task), persistent `heylogs.properties` config, every built-in rule, the authoring/releasing/inspecting commands, and how to run the - CLI with no prerequisites via gg.cmd or JBang. + CLI with no prerequisites via JBang. metadata: source: https://github.com/nbbrd/heylogs agent-generic: "true" @@ -35,11 +35,12 @@ heylogs [] ``` Examples below write `heylogs …` for brevity. If you don't have a native binary -on `PATH`, run the same command through `gg.cmd` (no prerequisites) or JBang — -see [`references/running-cli.md`](references/running-cli.md). Quickest one-liner: +on `PATH`, run the same command through JBang (no prerequisites) — see +[`references/running-cli.md`](references/running-cli.md). Quickest one-liner: ```bash -./gg.cmd jbang com.github.nbbrd.heylogs:heylogs-cli:0.18.1:bin check CHANGELOG.md +export JBANG_USE_NATIVE=true +curl -Ls https://sh.jbang.dev | bash -s - com.github.nbbrd.heylogs:heylogs-cli:0.18.1:bin check CHANGELOG.md ``` Most commands default to `CHANGELOG.md` and accept a positional file argument diff --git a/skills/heylogs/references/running-cli.md b/skills/heylogs/references/running-cli.md index 6fec8507..6ddacd99 100644 --- a/skills/heylogs/references/running-cli.md +++ b/skills/heylogs/references/running-cli.md @@ -5,31 +5,34 @@ don't have a native binary on `PATH` (e.g. via Homebrew/Scoop), run the same commands through one of the options below — substitute the whole invocation for `heylogs`. -## With gg.cmd (recommended — no prerequisites) +## Zero-install one-liner (recommended — no prerequisites) -[`gg.cmd`](https://github.com/eirikb/gg/) bootstraps both a JDK and JBang on -demand, so contributors and CI need **nothing** pre-installed. Download it once -into the repo: +JBang's install script bootstraps JBang (and a JDK) on demand and runs the CLI in +a single command — nothing pre-installed. Set `JBANG_USE_NATIVE=true` to launch +JBang's own native binary for near-instant startup (no JVM needed to start JBang +itself): ```bash -curl -L ggcmd.io > gg.cmd && chmod +x gg.cmd +# Linux / macOS / Windows (bash) +export JBANG_USE_NATIVE=true +curl -Ls https://sh.jbang.dev | bash -s - com.github.nbbrd.heylogs:heylogs-cli:0.18.1:bin check CHANGELOG.md ``` -Then run heylogs via JBang through it: - -```bash -./gg.cmd jbang com.github.nbbrd.heylogs:heylogs-cli:0.18.1:bin check CHANGELOG.md +```powershell +# Windows PowerShell +$env:JBANG_USE_NATIVE = "true" +iex "& { $(iwr -useb https://ps.jbang.dev) } com.github.nbbrd.heylogs:heylogs-cli:0.18.1:bin check CHANGELOG.md" ``` -## With JBang directly +## With JBang installed -If JBang is already available: +If JBang is already on `PATH`: ```bash jbang com.github.nbbrd.heylogs:heylogs-cli:0.18.1:bin check CHANGELOG.md ``` -Install JBang with the universal (all-platforms) installer if needed: +Install JBang persistently with the universal (all-platforms) installer if needed: ```bash # Linux / macOS / Windows (bash) From b291896b0f681b84930c27fdf525b541d1cf0b2c Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Tue, 23 Jun 2026 02:35:46 +0200 Subject: [PATCH 4/4] docs: bump heylogs CLI example version to 0.19.1 Co-Authored-By: Claude Opus 4.8 --- skills/heylogs/SKILL.md | 2 +- skills/heylogs/references/running-cli.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/skills/heylogs/SKILL.md b/skills/heylogs/SKILL.md index 965ecd02..1501797a 100644 --- a/skills/heylogs/SKILL.md +++ b/skills/heylogs/SKILL.md @@ -40,7 +40,7 @@ on `PATH`, run the same command through JBang (no prerequisites) — see ```bash export JBANG_USE_NATIVE=true -curl -Ls https://sh.jbang.dev | bash -s - com.github.nbbrd.heylogs:heylogs-cli:0.18.1:bin check CHANGELOG.md +curl -Ls https://sh.jbang.dev | bash -s - com.github.nbbrd.heylogs:heylogs-cli:0.19.1:bin check CHANGELOG.md ``` Most commands default to `CHANGELOG.md` and accept a positional file argument diff --git a/skills/heylogs/references/running-cli.md b/skills/heylogs/references/running-cli.md index 6ddacd99..e91d1460 100644 --- a/skills/heylogs/references/running-cli.md +++ b/skills/heylogs/references/running-cli.md @@ -15,13 +15,13 @@ itself): ```bash # Linux / macOS / Windows (bash) export JBANG_USE_NATIVE=true -curl -Ls https://sh.jbang.dev | bash -s - com.github.nbbrd.heylogs:heylogs-cli:0.18.1:bin check CHANGELOG.md +curl -Ls https://sh.jbang.dev | bash -s - com.github.nbbrd.heylogs:heylogs-cli:0.19.1:bin check CHANGELOG.md ``` ```powershell # Windows PowerShell $env:JBANG_USE_NATIVE = "true" -iex "& { $(iwr -useb https://ps.jbang.dev) } com.github.nbbrd.heylogs:heylogs-cli:0.18.1:bin check CHANGELOG.md" +iex "& { $(iwr -useb https://ps.jbang.dev) } com.github.nbbrd.heylogs:heylogs-cli:0.19.1:bin check CHANGELOG.md" ``` ## With JBang installed @@ -29,7 +29,7 @@ iex "& { $(iwr -useb https://ps.jbang.dev) } com.github.nbbrd.heylogs:heylogs-cl If JBang is already on `PATH`: ```bash -jbang com.github.nbbrd.heylogs:heylogs-cli:0.18.1:bin check CHANGELOG.md +jbang com.github.nbbrd.heylogs:heylogs-cli:0.19.1:bin check CHANGELOG.md ``` Install JBang persistently with the universal (all-platforms) installer if needed: @@ -43,7 +43,7 @@ iex "& { $(iwr -useb https://ps.jbang.dev) } app setup" JBang can also resolve the latest release from the project's catalog (`heylogs@nbbrd`, requires `trust: https://github.com/nbbrd/jbang-catalog`). -Replace `0.18.1` with the version you want; see +Replace `0.19.1` with the version you want; see [releases](https://github.com/nbbrd/heylogs/releases/latest). Other install methods (Homebrew, Scoop, plain jar) are in [`docs/usage-cli.md`](../../../docs/usage-cli.md).