@kitschpatrol/chagent 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bin/cli.js +184 -0
- package/dist/lib/bumpp.d.ts +14 -0
- package/dist/lib/bumpp.js +72 -0
- package/dist/lib/index.d.ts +31 -0
- package/dist/lib/index.js +4 -0
- package/dist/lib-CXMRRbJf.js +175 -0
- package/dist/progress-DQtRnH1N.js +74 -0
- package/dist/review-LYSADnul.js +2310 -0
- package/dist/types-Cms1Tu5k.d.ts +162 -0
- package/license.txt +21 -0
- package/package.json +93 -3
- package/readme.md +313 -0
- package/README.md +0 -3
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
declare const configSchema: z.ZodObject<{
|
|
3
|
+
agent: z.ZodOptional<z.ZodEnum<{
|
|
4
|
+
codex: "codex";
|
|
5
|
+
claude: "claude";
|
|
6
|
+
}>>;
|
|
7
|
+
cache: z.ZodOptional<z.ZodBoolean>;
|
|
8
|
+
effort: z.ZodOptional<z.ZodEnum<{
|
|
9
|
+
low: "low";
|
|
10
|
+
medium: "medium";
|
|
11
|
+
high: "high";
|
|
12
|
+
xhigh: "xhigh";
|
|
13
|
+
max: "max";
|
|
14
|
+
}>>;
|
|
15
|
+
exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
16
|
+
github: z.ZodOptional<z.ZodBoolean>;
|
|
17
|
+
maxInputChars: z.ZodOptional<z.ZodNumber>;
|
|
18
|
+
model: z.ZodOptional<z.ZodString>;
|
|
19
|
+
packages: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
20
|
+
tagPatterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
21
|
+
timeoutMs: z.ZodOptional<z.ZodNumber>;
|
|
22
|
+
}, z.core.$strict>;
|
|
23
|
+
type Config = z.infer<typeof configSchema>;
|
|
24
|
+
/** Define optional repository configuration with TypeScript completion. */
|
|
25
|
+
declare function defineConfig(config: Config): Config;
|
|
26
|
+
/** Load configuration from the repository root or an explicitly selected file. */
|
|
27
|
+
declare function loadConfig(root: string, file?: string): Promise<Config>;
|
|
28
|
+
declare const categories: readonly ["Added", "Changed", "Deprecated", "Removed", "Fixed", "Security", "Documentation", "Maintenance"];
|
|
29
|
+
type Category = (typeof categories)[number];
|
|
30
|
+
declare const agentNames: readonly ["codex", "claude"];
|
|
31
|
+
declare const efforts: readonly ["low", "medium", "high", "xhigh", "max"];
|
|
32
|
+
type AgentName = (typeof agentNames)[number];
|
|
33
|
+
type Effort = (typeof efforts)[number];
|
|
34
|
+
type Change = {
|
|
35
|
+
breaking: boolean;
|
|
36
|
+
category: Category;
|
|
37
|
+
description: string;
|
|
38
|
+
sources: string[];
|
|
39
|
+
};
|
|
40
|
+
type Evidence = {
|
|
41
|
+
/** Git commits associated with pull-request evidence. */
|
|
42
|
+
commits?: string[];
|
|
43
|
+
id: string;
|
|
44
|
+
kind: 'commit' | 'manifest' | 'pull-request' | 'range';
|
|
45
|
+
text: string;
|
|
46
|
+
};
|
|
47
|
+
/**
|
|
48
|
+
* One release to describe. This is plain data, so it serves as both prompt
|
|
49
|
+
* input and cache identity.
|
|
50
|
+
*/
|
|
51
|
+
type ReleaseRequest = {
|
|
52
|
+
evidence: Evidence[];
|
|
53
|
+
existingEntries: string;
|
|
54
|
+
/** Unique and stable across runs; each change set echoes it. */
|
|
55
|
+
id: string;
|
|
56
|
+
initialRelease: boolean;
|
|
57
|
+
mode: 'initialize' | 'update';
|
|
58
|
+
packageName: string;
|
|
59
|
+
/**
|
|
60
|
+
* Read-only research context in the local checkout; Git snapshots, not the
|
|
61
|
+
* working tree, define the release.
|
|
62
|
+
*/
|
|
63
|
+
repository: {
|
|
64
|
+
directory: string;
|
|
65
|
+
excludeDirectories: string[];
|
|
66
|
+
from?: string;
|
|
67
|
+
to: string;
|
|
68
|
+
};
|
|
69
|
+
scope: 'package' | 'repository';
|
|
70
|
+
version: string;
|
|
71
|
+
};
|
|
72
|
+
/** How to run a session, as opposed to what it should describe. */
|
|
73
|
+
type RunSettings = {
|
|
74
|
+
effort: Effort;
|
|
75
|
+
model?: string;
|
|
76
|
+
signal?: AbortSignal;
|
|
77
|
+
timeoutMs: number;
|
|
78
|
+
};
|
|
79
|
+
/** One or more releases to research together in a single session. */
|
|
80
|
+
type GenerationRequest = {
|
|
81
|
+
releases: ReleaseRequest[];
|
|
82
|
+
/**
|
|
83
|
+
* A previous response that failed validation, to correct rather than research
|
|
84
|
+
* again.
|
|
85
|
+
*/
|
|
86
|
+
repair?: {
|
|
87
|
+
error: string;
|
|
88
|
+
response: unknown;
|
|
89
|
+
};
|
|
90
|
+
repositoryRoot: string;
|
|
91
|
+
settings: RunSettings;
|
|
92
|
+
};
|
|
93
|
+
type ChangeSet = {
|
|
94
|
+
changes: Change[];
|
|
95
|
+
id: string;
|
|
96
|
+
};
|
|
97
|
+
type GenerationResponse = {
|
|
98
|
+
releases: ChangeSet[];
|
|
99
|
+
};
|
|
100
|
+
type AgentAdapter = {
|
|
101
|
+
/** Change this identifier when the adapter's generation behavior changes. */
|
|
102
|
+
cacheKey?: string;
|
|
103
|
+
/**
|
|
104
|
+
* Describe every requested release, returning exactly one change set per
|
|
105
|
+
* release ID.
|
|
106
|
+
*/
|
|
107
|
+
generate: (request: GenerationRequest) => Promise<GenerationResponse>;
|
|
108
|
+
name: string;
|
|
109
|
+
};
|
|
110
|
+
type ReleaseContext = {
|
|
111
|
+
date?: string;
|
|
112
|
+
tag?: string;
|
|
113
|
+
version: string;
|
|
114
|
+
};
|
|
115
|
+
type GenerateOptions = Omit<Config, 'agent'> & {
|
|
116
|
+
agent?: AgentAdapter | AgentName;
|
|
117
|
+
configFile?: string;
|
|
118
|
+
cwd?: string;
|
|
119
|
+
/** Receives a short status message as generation moves between agent sessions. */
|
|
120
|
+
onProgress?: (message: string) => void;
|
|
121
|
+
/**
|
|
122
|
+
* Explicitly reconstruct all history instead of preserving existing release
|
|
123
|
+
* sections.
|
|
124
|
+
*/
|
|
125
|
+
rebuild?: boolean;
|
|
126
|
+
release?: ReleaseContext;
|
|
127
|
+
signal?: AbortSignal;
|
|
128
|
+
};
|
|
129
|
+
type FileEdit = {
|
|
130
|
+
after: string;
|
|
131
|
+
before?: string;
|
|
132
|
+
path: string;
|
|
133
|
+
};
|
|
134
|
+
type Checkpoint = {
|
|
135
|
+
baseRef: string;
|
|
136
|
+
contentHash: string;
|
|
137
|
+
head: string;
|
|
138
|
+
instructionVersion: string;
|
|
139
|
+
path: string;
|
|
140
|
+
};
|
|
141
|
+
type ReleaseSummary = {
|
|
142
|
+
/** Anchor of the actual package heading, including preserved historical dates. */
|
|
143
|
+
anchor?: string;
|
|
144
|
+
changelogPath: string;
|
|
145
|
+
changes: Change[];
|
|
146
|
+
date?: string;
|
|
147
|
+
packageDirectory: string;
|
|
148
|
+
packageName: string;
|
|
149
|
+
ref: string;
|
|
150
|
+
tag?: string;
|
|
151
|
+
version: string;
|
|
152
|
+
};
|
|
153
|
+
type ChangelogPlan = {
|
|
154
|
+
/** Internal, disposable incremental-generation metadata. */
|
|
155
|
+
checkpoints: Checkpoint[];
|
|
156
|
+
diagnostics: string[];
|
|
157
|
+
files: FileEdit[];
|
|
158
|
+
head: string;
|
|
159
|
+
releases: ReleaseSummary[];
|
|
160
|
+
root: string;
|
|
161
|
+
};
|
|
162
|
+
export { Config as _, ChangeSet as a, Evidence as c, GenerationRequest as d, GenerationResponse as f, RunSettings as g, ReleaseSummary as h, Change as i, FileEdit as l, ReleaseRequest as m, AgentName as n, ChangelogPlan as o, ReleaseContext as p, Category as r, Effort as s, AgentAdapter as t, GenerateOptions as u, defineConfig as v, loadConfig as y };
|
package/license.txt
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Eric Mika
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/package.json
CHANGED
|
@@ -1,6 +1,96 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kitschpatrol/chagent",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Changelog agent. CLI tool and TypeScript library to generate and update changelogs with a little help from your LLMs.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"changelog",
|
|
7
|
+
"cli",
|
|
8
|
+
"codex",
|
|
9
|
+
"claude",
|
|
10
|
+
"agent",
|
|
11
|
+
"release-notes",
|
|
12
|
+
"typescript"
|
|
13
|
+
],
|
|
14
|
+
"homepage": "https://github.com/kitschpatrol/chagent",
|
|
15
|
+
"bugs": "https://github.com/kitschpatrol/chagent/issues",
|
|
16
|
+
"repository": {
|
|
17
|
+
"type": "git",
|
|
18
|
+
"url": "git+https://github.com/kitschpatrol/chagent.git"
|
|
19
|
+
},
|
|
20
|
+
"license": "MIT",
|
|
21
|
+
"author": {
|
|
22
|
+
"name": "Eric Mika",
|
|
23
|
+
"email": "eric@ericmika.com",
|
|
24
|
+
"url": "https://ericmika.com"
|
|
25
|
+
},
|
|
26
|
+
"sideEffects": false,
|
|
27
|
+
"type": "module",
|
|
28
|
+
"exports": {
|
|
29
|
+
".": {
|
|
30
|
+
"types": "./dist/lib/index.d.ts",
|
|
31
|
+
"import": "./dist/lib/index.js"
|
|
32
|
+
},
|
|
33
|
+
"./bumpp": {
|
|
34
|
+
"types": "./dist/lib/bumpp.d.ts",
|
|
35
|
+
"import": "./dist/lib/bumpp.js"
|
|
36
|
+
}
|
|
37
|
+
},
|
|
38
|
+
"main": "./dist/lib/index.js",
|
|
39
|
+
"module": "./dist/lib/index.js",
|
|
40
|
+
"types": "./dist/lib/index.d.ts",
|
|
41
|
+
"bin": {
|
|
42
|
+
"chagent": "dist/bin/cli.js"
|
|
43
|
+
},
|
|
44
|
+
"files": [
|
|
45
|
+
"dist"
|
|
46
|
+
],
|
|
47
|
+
"dependencies": {
|
|
48
|
+
"@clack/prompts": "^1.8.1",
|
|
49
|
+
"@types/node": "~24.13.6",
|
|
50
|
+
"cosmiconfig": "^10.0.1",
|
|
51
|
+
"cross-spawn": "^7.0.6",
|
|
52
|
+
"lognow": "^0.8.8",
|
|
53
|
+
"semver": "^7.8.6",
|
|
54
|
+
"yaml": "^2.9.1",
|
|
55
|
+
"yargs": "^18.2.0",
|
|
56
|
+
"zod": "^4.6.7"
|
|
57
|
+
},
|
|
58
|
+
"devDependencies": {
|
|
59
|
+
"@arethetypeswrong/core": "^0.18.5",
|
|
60
|
+
"@kitschpatrol/shared-config": "^8.14.1",
|
|
61
|
+
"@types/cross-spawn": "^6.0.6",
|
|
62
|
+
"@types/semver": "^7.8.0",
|
|
63
|
+
"@types/yargs": "^17.0.35",
|
|
64
|
+
"brewpub": "^0.5.1",
|
|
65
|
+
"bumpp": "^12.3.0",
|
|
66
|
+
"fast-check": "^4.10.2",
|
|
67
|
+
"mdat-plugin-cli-help": "^3.4.2",
|
|
68
|
+
"publint": "^0.3.25",
|
|
69
|
+
"shx": "^0.4.0",
|
|
70
|
+
"tsdown": "^0.23.5",
|
|
71
|
+
"typescript": "~6.0.3",
|
|
72
|
+
"vitest": "^5.1.0"
|
|
73
|
+
},
|
|
74
|
+
"peerDependencies": {
|
|
75
|
+
"bumpp": ">=12.3.0"
|
|
76
|
+
},
|
|
77
|
+
"peerDependenciesMeta": {
|
|
78
|
+
"bumpp": {
|
|
79
|
+
"optional": true
|
|
80
|
+
}
|
|
81
|
+
},
|
|
82
|
+
"engines": {
|
|
83
|
+
"node": "^24.16.0 || >=26.3.0"
|
|
84
|
+
},
|
|
85
|
+
"publishConfig": {
|
|
86
|
+
"access": "public"
|
|
87
|
+
},
|
|
88
|
+
"scripts": {
|
|
89
|
+
"build": "tsdown",
|
|
90
|
+
"clean-deep": "shx rm -f pnpm-lock.yaml && git clean -fdX",
|
|
91
|
+
"fix": "pnpm build && ksc fix",
|
|
92
|
+
"lint": "pnpm build && ksc lint",
|
|
93
|
+
"release": "bumpp --all --commit 'Release: %s' --execute 'node dist/bin/cli.js' && pnpm build && pnpm publish --otp $(op item get npm --otp) && brewpub --tap kitschpatrol/tap --description 'Generate and update changelogs from Git history with Codex or Claude'",
|
|
94
|
+
"test": "pnpm build && vitest run"
|
|
95
|
+
}
|
|
6
96
|
}
|
package/readme.md
ADDED
|
@@ -0,0 +1,313 @@
|
|
|
1
|
+
# chagent
|
|
2
|
+
|
|
3
|
+
<!-- badges -->
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@kitschpatrol/chagent)
|
|
6
|
+
[](https://opensource.org/license/mit)
|
|
7
|
+
[](https://github.com/kitschpatrol/chagent/actions/workflows/ci.yml)
|
|
8
|
+
[](https://github.com/kitschpatrol/homebrew-tap/blob/HEAD/Formula/chagent.rb)
|
|
9
|
+
|
|
10
|
+
<!-- /badges -->
|
|
11
|
+
|
|
12
|
+
<!-- short-description -->
|
|
13
|
+
|
|
14
|
+
**Changelog agent. CLI tool and TypeScript library to generate and update changelogs with a little help from your LLMs.**
|
|
15
|
+
|
|
16
|
+
<!-- /short-description -->
|
|
17
|
+
|
|
18
|
+
## Overview
|
|
19
|
+
|
|
20
|
+
Run `chagent` in a Git repository to either create a changelog where none previously existed, or update an existing changelog to capture recent changes.
|
|
21
|
+
|
|
22
|
+
Projects can use any language or build system. Version tags supply release boundaries; `package.json` is optional. Codex or Claude inspects historical commits and files directly to decide what belongs in each release.
|
|
23
|
+
|
|
24
|
+
Between releases, it will add changes under the `Unreleased` heading. Historical release sections retain their original Markdown.
|
|
25
|
+
|
|
26
|
+
Initialization reconstructs the complete reachable release history, including the initial release's capabilities and meaningful documentation, dependency, compatibility, build, test, and CI changes. Releases containing only maintenance still receive useful descriptions.
|
|
27
|
+
|
|
28
|
+
Codex and Claude research missing releases together in one session, sharing their understanding of the project across versions and packages. Very large histories split into additional sessions only when their release context exceeds the input budget. Ordinary single-release updates use one request.
|
|
29
|
+
|
|
30
|
+
The CLI and TypeScript library use your installed, authenticated Codex or Claude Code CLI. Codex defaults to `gpt-6.1-sol`; Claude defaults to [Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/overview) (`claude-opus-5-5`). Both use `xhigh` reasoning effort by default. No separate API key or installed agent skill is required.
|
|
31
|
+
|
|
32
|
+
Output uses the canonical [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) header and extends its six standard categories with `Documentation` and `Maintenance`. The standard headings describe user-facing concerns, including public APIs and runtime compatibility; the extensions also capture documentation and internal development work.
|
|
33
|
+
|
|
34
|
+
| Heading | Covers |
|
|
35
|
+
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
36
|
+
| `Added` | New user-facing features and public APIs. |
|
|
37
|
+
| `Changed` | Changes to existing user-facing functionality, public APIs, or runtime support. |
|
|
38
|
+
| `Deprecated` | Features and public APIs scheduled for removal. |
|
|
39
|
+
| `Removed` | Removed features and public APIs. |
|
|
40
|
+
| `Fixed` | Bugs affecting users or library consumers. |
|
|
41
|
+
| `Security` | Vulnerability fixes affecting users or library consumers. |
|
|
42
|
+
| `Documentation` | All documentation changes, including guides, examples, API documentation, and help text. |
|
|
43
|
+
| `Maintenance` | Other changes without a user-facing feature change, bug fix, vulnerability fix, or documentation change, including routine dependency updates, internal refactoring, builds, tests, CI, and release tooling. |
|
|
44
|
+
|
|
45
|
+
Categories follow the impact of a change. A dependency update that fixes a user-facing bug belongs under `Fixed`, while a routine dependency refresh or a fix to development tooling belongs under `Maintenance`. Documentation-only corrections belong under `Documentation`.
|
|
46
|
+
|
|
47
|
+
You can invoke it directly, or easily integrate it with a [bumpp](https://github.com/antfu-collective/bumpp)-powered release workflow.
|
|
48
|
+
|
|
49
|
+
Future versions might offer more in the way of CI integration.
|
|
50
|
+
|
|
51
|
+
## Getting started
|
|
52
|
+
|
|
53
|
+
<!-- dependencies -->
|
|
54
|
+
|
|
55
|
+
### Dependencies
|
|
56
|
+
|
|
57
|
+
- [Node.js](https://nodejs.org/) 24.16.0 or newer (specifically `^24.16.0 || >=26.3.0`)
|
|
58
|
+
|
|
59
|
+
<!-- /dependencies -->
|
|
60
|
+
|
|
61
|
+
You also need Git and one supported agent CLI on your path. Log in to that CLI before running chagent. Optional GitHub enrichment uses an authenticated `gh` installation and falls back to local Git when unavailable.
|
|
62
|
+
|
|
63
|
+
The adapters were exercised with Codex CLI 0.166.0 and Claude Code 2.1.311. Older versions must support the structured-output and isolation flags used by the adapters.
|
|
64
|
+
|
|
65
|
+
<!-- install -->
|
|
66
|
+
|
|
67
|
+
### Installation
|
|
68
|
+
|
|
69
|
+
There are several ways to install @kitschpatrol/chagent depending on how you're planning to use it:
|
|
70
|
+
|
|
71
|
+
#### CLI
|
|
72
|
+
|
|
73
|
+
Run it once without installing:
|
|
74
|
+
|
|
75
|
+
```sh
|
|
76
|
+
npx @kitschpatrol/chagent
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Or install it globally with Homebrew:
|
|
80
|
+
|
|
81
|
+
```sh
|
|
82
|
+
brew install kitschpatrol/tap/chagent
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Or install it globally with npm:
|
|
86
|
+
|
|
87
|
+
```sh
|
|
88
|
+
npm install --global @kitschpatrol/chagent
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
#### Library
|
|
92
|
+
|
|
93
|
+
Add it to your project to import the TypeScript API. This also puts the `chagent` CLI on your project's path:
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
npm install @kitschpatrol/chagent
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
<!-- /install -->
|
|
100
|
+
|
|
101
|
+
## Usage
|
|
102
|
+
|
|
103
|
+
### CLI usage
|
|
104
|
+
|
|
105
|
+
Use `--model` and `--effort` to override the selected agent's defaults.
|
|
106
|
+
|
|
107
|
+
Explicit CLI flags override repository configuration, which overrides built-in defaults. The defaults shown in `--help` apply when no repository override is configured; the model default depends on the selected agent.
|
|
108
|
+
|
|
109
|
+
Interactive review edits temporary candidate files. After the editor exits, the updated diff is displayed. Accepting writes exactly the saved content. Cancelling leaves repository files unchanged. Editor selection follows `git var GIT_EDITOR`, or `--editor`; GUI editor commands must wait, for example `code --wait`.
|
|
110
|
+
|
|
111
|
+
The default command writes changelog files without staging or committing them.
|
|
112
|
+
|
|
113
|
+
Add `--verbose` to log resolved options, Git and agent commands, cache decisions, and session timing to stderr. On a terminal, it replaces the progress timer with plain lines.
|
|
114
|
+
|
|
115
|
+
Use `chagent --rebuild --interactive` to reconstruct an existing changelog from history and review the replacement. This explicitly replaces historical prose, including manual edits; ordinary runs preserve it. Use `--rebuild --dry-run` to preview the reconstruction without writing files. In a monorepo, rebuilding covers both package changelogs and the root summary.
|
|
116
|
+
|
|
117
|
+
<!-- cli-help -->
|
|
118
|
+
|
|
119
|
+
#### Commands
|
|
120
|
+
|
|
121
|
+
##### Command: `chagent`
|
|
122
|
+
|
|
123
|
+
Initialize or update changelogs from repository history.
|
|
124
|
+
|
|
125
|
+
Usage:
|
|
126
|
+
|
|
127
|
+
```txt
|
|
128
|
+
chagent
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
| Option | Description | Type | Default |
|
|
132
|
+
| ----------------------- | --------------------------------------------------------------------- | --------------------------------------------- | --------------------------------------------- |
|
|
133
|
+
| `--cwd` | Repository directory | `string` | current directory |
|
|
134
|
+
| `--agent` | Installed agent CLI | `"codex"` `"claude"` | `codex` |
|
|
135
|
+
| `--model` | Agent model | `string` | gpt-6.1-sol (Codex); claude-opus-5-5 (Claude) |
|
|
136
|
+
| `--effort` | Reasoning effort | `"low"` `"medium"` `"high"` `"xhigh"` `"max"` | `xhigh` |
|
|
137
|
+
| `--interactive`<br>`-i` | Review a diff and optionally edit before writing | `boolean` | `false` |
|
|
138
|
+
| `--editor` | Editor command for interactive review; configure GUI editors to wait | `string` | git var GIT_EDITOR |
|
|
139
|
+
| `--dry-run` | Print a diff without applying changes | `boolean` | `false` |
|
|
140
|
+
| `--rebuild` | Reconstruct all history, replacing existing release text | `boolean` | `false` |
|
|
141
|
+
| `--amend` | Amend a verified unpublished release commit and matching local tags | `boolean` | `false` |
|
|
142
|
+
| `--github` | Enrich Git evidence using gh when available; disable with --no-github | `boolean` | `true` |
|
|
143
|
+
| `--cache` | Cache drafts and incremental state; disable with --no-cache | `boolean` | `true` |
|
|
144
|
+
| `--config` | Configuration file path | `string` | auto-detected from repository root |
|
|
145
|
+
| `--timeout` | Agent timeout in seconds | `number` | `1200` |
|
|
146
|
+
| `--verbose` | Log commands, cache decisions, and session details to stderr | `boolean` | `false` |
|
|
147
|
+
| `--help`<br>`-h` | Show help | `boolean` | |
|
|
148
|
+
| `--version`<br>`-v` | Show version number | `boolean` | |
|
|
149
|
+
|
|
150
|
+
<!-- /cli-help -->
|
|
151
|
+
|
|
152
|
+
#### CLI Examples
|
|
153
|
+
|
|
154
|
+
```sh
|
|
155
|
+
# Automatically initialize or update the current repository.
|
|
156
|
+
chagent
|
|
157
|
+
|
|
158
|
+
# Review the diff, optionally edit, then accept or cancel.
|
|
159
|
+
chagent --interactive
|
|
160
|
+
|
|
161
|
+
# Reconstruct an existing changelog and review its replacement.
|
|
162
|
+
chagent --rebuild --interactive
|
|
163
|
+
|
|
164
|
+
# Select Claude Opus 5.5 with xhigh effort.
|
|
165
|
+
chagent --agent claude
|
|
166
|
+
|
|
167
|
+
# Preview changes without applying them.
|
|
168
|
+
chagent --dry-run --no-github
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### Library
|
|
172
|
+
|
|
173
|
+
#### API
|
|
174
|
+
|
|
175
|
+
`generateChangelog` returns proposed edits, release summaries, diagnostics, and incremental checkpoints. `writeChangelog` verifies the original file contents and Git HEAD before applying edits. It rejects symlink destinations, rolls back a failed series of writes, and leaves the index unchanged.
|
|
176
|
+
|
|
177
|
+
`previewChangelog(plan)` returns a unified diff. `reviewChangelog(plan, { editor })` provides terminal review and returns an edited plan, or `undefined` when cancelled. `amendRelease(plan)` is the explicit post-bump release integration described below. `setLogger(logger)` enables library logging; library calls are silent by default. Pass `onProgress` to `generateChangelog` to receive short status messages between agent sessions.
|
|
178
|
+
|
|
179
|
+
Custom providers implement the exported `AgentAdapter` type and can be passed as `agent`. Their `generate(request)` method receives a `GenerationRequest` with one or more `releases` to research together, the local `repositoryRoot`, and run `settings`. Each release identifies its package, scope, mode, Git refs, and a bounded starting context, including a range citation for findings from direct research of the local Git checkout. The method resolves to `{ releases: [{ id, changes }] }`, with every requested release ID exactly once, one of the eight supported categories, and citations from that release's own `evidence`. Give an adapter a stable `cacheKey` to enable reusable draft caching, and change that key when its behavior changes. All adapter results receive the same output validation.
|
|
180
|
+
|
|
181
|
+
#### API Examples
|
|
182
|
+
|
|
183
|
+
```ts
|
|
184
|
+
import { generateChangelog, writeChangelog } from '@kitschpatrol/chagent'
|
|
185
|
+
|
|
186
|
+
const plan = await generateChangelog({ cwd: '/path/to/repository' })
|
|
187
|
+
|
|
188
|
+
// Inspect plan.files or edit their `after` contents before applying them.
|
|
189
|
+
await writeChangelog(plan)
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### Bumpp integration
|
|
193
|
+
|
|
194
|
+
Chagent works nicely with the [bumpp](https://github.com/antfu-collective/bumpp) versioning and release tool.
|
|
195
|
+
|
|
196
|
+
#### Bumpp CLI approach
|
|
197
|
+
|
|
198
|
+
Execute chagent as part of the bump process:
|
|
199
|
+
|
|
200
|
+
```sh
|
|
201
|
+
bumpp --all --execute "chagent -i"
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
This runs the following sequence:
|
|
205
|
+
|
|
206
|
+
1. Bumpp updates the package version.
|
|
207
|
+
2. Chagent moves all existing `Unreleased` notes into the new release section, preserves their text, and adds missing changes. Older release sections remain unchanged.
|
|
208
|
+
3. The `-i` flag displays the diff and lets you edit, accept, or cancel. Saved edits are included when you accept.
|
|
209
|
+
4. Bumpp commits the version and changelog changes together, tags the release, and pushes.
|
|
210
|
+
|
|
211
|
+
Remove `-i` to skip review. Add `--no-push` if you want to push separately.
|
|
212
|
+
|
|
213
|
+
`--all` is needed for this command because bumpp otherwise commits only its version-update files. It includes every pending change, including unrelated and untracked files, so start from a clean working tree. It controls which files are committed, not which files bumpp updates versions in.
|
|
214
|
+
|
|
215
|
+
#### Bumpp configuration file approach
|
|
216
|
+
|
|
217
|
+
Alternatively, use the library callback in `bump.config.ts` to include only the generated changelogs alongside the version-update files, without `--all`:
|
|
218
|
+
|
|
219
|
+
```ts
|
|
220
|
+
import { createBumppHook } from '@kitschpatrol/chagent/bumpp'
|
|
221
|
+
import { defineConfig } from 'bumpp'
|
|
222
|
+
|
|
223
|
+
export default defineConfig({
|
|
224
|
+
commit: 'Release {version}.',
|
|
225
|
+
execute: createBumppHook(),
|
|
226
|
+
})
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
For review during releases, use `createBumppHook({ interactive: true })`. Other options include `agent`, `model`, `effort`, `github`, `cache`, and `editor`.
|
|
230
|
+
|
|
231
|
+
The callback shows progress and diagnostics on stderr. Pass `onProgress` to handle status messages yourself.
|
|
232
|
+
|
|
233
|
+
Bumpp updates versions before invoking the callback. The callback generates and reviews changelogs, stages only those files, and adds them to bumpp's explicit commit file list. Bumpp then commits and tags the complete release. Its existing push and publishing settings remain under your control.
|
|
234
|
+
|
|
235
|
+
Avoid putting changelogs in bumpp's version-replacement `files` option: it can replace version references in historical entries.
|
|
236
|
+
|
|
237
|
+
With either approach, a generation error or cancelled review stops bumpp before its commit and tag. Bumpp's already updated version files remain available for correction or retry. The callback requires bumpp 12.3.0 or newer. It works with recursive releases, and with independently versioned packages released from their own directories.
|
|
238
|
+
|
|
239
|
+
For an existing post-bump workflow, `chagent --amend` explicitly amends an unpublished version-only release commit and updates matching local tags. It checks current remote refs, preserves unrelated staged work and tag annotations, and refuses published releases, ambiguous commits, detached HEAD, and signed tags. Signed tags need manual re-signing; the pre-commit callback avoids that problem. Chagent itself never pushes or publishes.
|
|
240
|
+
|
|
241
|
+
### Monorepos
|
|
242
|
+
|
|
243
|
+
Workspace declarations in `pnpm-workspace.yaml` or `package.json` determine the packages to process. Each current workspace package gets its own changelog. The root contains repository highlights and links to package releases.
|
|
244
|
+
|
|
245
|
+
For other monorepo layouts, configure `packages` directory globs. These directories do not need npm manifests; their Git tags identify releases, using the directory basename as the package name.
|
|
246
|
+
|
|
247
|
+
Shared-version repositories use repository versions at the root. Independently versioned repositories use package-qualified headings such as `@example/package@1.2.0`. Repository infrastructure changes appear in the root's `Unreleased` section. Explicit workspace dependencies contribute relevant source context to dependent packages. Dependency and tooling maintenance belongs under `Maintenance`. `build`, `coverage`, and `dist` directories at the top of a package count as generated output and are excluded, so a package named `packages/build` is still treated as source.
|
|
248
|
+
|
|
249
|
+
GitHub links to package changelogs on the default branch remain usable when a root entry is extracted for GitHub release notes.
|
|
250
|
+
|
|
251
|
+
### Configuration
|
|
252
|
+
|
|
253
|
+
Configuration is optional. A `chagent.config.ts` file can override defaults:
|
|
254
|
+
|
|
255
|
+
```ts
|
|
256
|
+
import { defineConfig } from '@kitschpatrol/chagent'
|
|
257
|
+
|
|
258
|
+
export default defineConfig({
|
|
259
|
+
agent: 'codex',
|
|
260
|
+
cache: true,
|
|
261
|
+
effort: 'xhigh',
|
|
262
|
+
github: true,
|
|
263
|
+
maxInputChars: 80_000,
|
|
264
|
+
model: 'gpt-6.1-sol',
|
|
265
|
+
timeoutMs: 1_200_000,
|
|
266
|
+
})
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
Importing `defineConfig` requires chagent in the repository's own dependencies. With `npx`, Homebrew, or a global installation, export a plain object instead.
|
|
270
|
+
|
|
271
|
+
Also supported: `chagent.config.mjs`, `chagent.config.js`, `chagent.config.json`, or a `chagent` key in `package.json`. CLI flags override configured values. `--config` selects a specific file.
|
|
272
|
+
|
|
273
|
+
Use `packages` and `exclude` directory globs to customize workspace discovery. Use `tagPatterns` to select unusual release tag conventions. Templates support `{name}` and `{version}`; defaults recognize `v1.2.3`, `1.2.3`, `@scope/package@1.2.3`, and `@scope/package/v1.2.3`.
|
|
274
|
+
|
|
275
|
+
## Background
|
|
276
|
+
|
|
277
|
+
### Implementation notes
|
|
278
|
+
|
|
279
|
+
Chagent reads reachable version tags and commit history regardless of the project's language. Optional npm metadata supplies workspace discovery, local version-bump detection before tagging, and the conditional Node.js compatibility note. Repository tags remain authoritative even when a root `package.json` has an unrelated tooling version. Other projects use tagged releases, or an explicit `release` context through the library API. Without reliable released-version boundaries, new changes belong to `Unreleased`; version numbers are not invented. An existing release heading with no matching Git boundary requires its tags or a corrected tag pattern. Release headings can be level one or two, with optional links, dates, and a `v` prefix, including the Conventional Changelog format. Level three headings count as releases when they name a version, as standard-version writes patch releases. Chagent stops rather than risk duplicating history when a level one or two heading names a version in another form, or when an unclosed code fence would hide later headings. Broken `package.json` files in history are tolerated. Shallow clones must be completed before generation.
|
|
280
|
+
|
|
281
|
+
GitHub enrichment uses release dates and commit-associated PR information. PR lookups batch unique commits across all requested releases and packages; each release receives only its associated PRs. **GitHub release-note bodies are never generation inputs.** Changelog files and generated build output are excluded from source evidence. Existing changelog prose is supplied only to preserve edits and avoid duplicate entries.
|
|
282
|
+
|
|
283
|
+
The agent chooses which historical source files, public interfaces, documentation, and build configuration to inspect. It reads Git snapshots at the supplied release refs instead of treating current or uncommitted files as historical evidence. `maxInputChars` bounds the starting context supplied to agents; it does not restrict which repository files they can investigate. Requests prioritize release boundaries and existing human entries, then fit optional starting evidence into the remaining budget. An individual release's existing entries are never truncated. `timeoutMs` applies to each agent session. Lockfile maintenance retains its commit intent, while pure npm version-bump bookkeeping is excluded.
|
|
284
|
+
|
|
285
|
+
Agents return structured changes with evidence references. Stray whitespace and list markers in descriptions are normalized. A response that still fails validation gets one correction request; a second failure stops the run before anything is written or cached. Application code owns the header, release boundaries, Markdown insertion, and Git writes. Agents run in the repository: Codex uses a read-only sandbox with approval requests disabled; Claude exposes read/search and Bash tools in [`dontAsk` mode](https://code.claude.com/docs/en/permissions), which allows read-only commands and denies actions requiring permission. Customizations are disabled for these invocations. Only chagent writes the reviewed changelog. Repository content is sent to the selected agent service using your existing account.
|
|
286
|
+
|
|
287
|
+
After writing, chagent passes each changed changelog to `fixFile` from the repository's own `@kitschpatrol/shared-config`, or from `@kitschpatrol/prettier-config` when that is all that imports. This formats the whole changelog, including older release sections, and no other files. `--dry-run` and `--interactive` diffs show the text before formatting. A formatting failure leaves the changelog as written and reports a diagnostic. Repositories without either package keep the changelog as written.
|
|
288
|
+
|
|
289
|
+
Drafts and checkpoints are stored under the checkout's Git directory in `chagent/`. They are disposable and are not committed. Shared session results are validated together and cached separately for each release. Completed sessions can be reused after interruptions; an interrupted session must run again. `--no-cache` disables reuse and persistence. Dry runs can populate the draft cache but do not apply changelog edits.
|
|
290
|
+
|
|
291
|
+
## Maintainers
|
|
292
|
+
|
|
293
|
+
[kitschpatrol](https://github.com/kitschpatrol)
|
|
294
|
+
|
|
295
|
+
<!-- contributing -->
|
|
296
|
+
|
|
297
|
+
## Contributing
|
|
298
|
+
|
|
299
|
+
[Issues](https://github.com/kitschpatrol/chagent/issues) are welcome and appreciated.
|
|
300
|
+
|
|
301
|
+
Please open an issue to discuss changes before submitting a pull request. Unsolicited PRs (especially AI-generated ones) are unlikely to be merged.
|
|
302
|
+
|
|
303
|
+
This repository uses [@kitschpatrol/shared-config](https://github.com/kitschpatrol/shared-config) (via its `ksc` CLI) for linting and formatting, plus [MDAT](https://github.com/kitschpatrol/mdat) for readme placeholder expansion.
|
|
304
|
+
|
|
305
|
+
<!-- /contributing -->
|
|
306
|
+
|
|
307
|
+
<!-- license -->
|
|
308
|
+
|
|
309
|
+
## License
|
|
310
|
+
|
|
311
|
+
[MIT](license.txt) © [Eric Mika](https://ericmika.com)
|
|
312
|
+
|
|
313
|
+
<!-- /license -->
|
package/README.md
DELETED