@guiho/mirror 3.0.0 → 3.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/CHANGELOG.md +15 -0
- package/DOCS.md +536 -0
- package/README.md +24 -2
- package/jsr.json +1 -1
- package/library/adapters.d.ts +2 -1
- package/library/adapters.d.ts.map +1 -1
- package/library/adapters.js +65 -14
- package/library/agents.d.ts +27 -0
- package/library/agents.d.ts.map +1 -0
- package/library/agents.js +205 -0
- package/library/cli.d.ts.map +1 -1
- package/library/cli.js +51 -15
- package/library/config.d.ts +1 -1
- package/library/config.d.ts.map +1 -1
- package/library/config.js +41 -3
- package/library/executor.d.ts +1 -1
- package/library/executor.d.ts.map +1 -1
- package/library/executor.js +4 -4
- package/library/flags.d.ts +1 -1
- package/library/flags.d.ts.map +1 -1
- package/library/flags.js +1 -1
- package/library/guiho-mirror-bin.d.ts +1 -1
- package/library/guiho-mirror-bin.js +2 -2
- package/library/guiho-mirror.d.ts +11 -10
- package/library/guiho-mirror.d.ts.map +1 -1
- package/library/guiho-mirror.js +10 -9
- package/library/plan.d.ts +1 -1
- package/library/plan.d.ts.map +1 -1
- package/library/plan.js +4 -4
- package/library/reporter.d.ts +3 -1
- package/library/reporter.d.ts.map +1 -1
- package/library/reporter.js +33 -1
- package/library/types.d.ts +31 -0
- package/library/types.d.ts.map +1 -1
- package/library/version.js +1 -1
- package/package.json +8 -7
- package/skills/guiho-as-mirror/SKILL.md +227 -0
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [3.1.0] - 2026-06-07
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- Added Mirror agent automation commands for installing the bundled `guiho-as-mirror` skill locally or globally.
|
|
13
|
+
- Added `mirror agents instructions` to create or update `AGENTS.md` with Mirror semantic versioning guidance.
|
|
14
|
+
- Added `[agents]` configuration for changelog behavior, changelog path selection, AGENTS.md insertion, and automatic skill installation.
|
|
15
|
+
- Added the bundled `guiho-as-mirror` skill to the published package.
|
|
16
|
+
- Added full package documentation in `mirror/DOCS.md` and repository guidance requiring documentation updates before publishing new versions.
|
|
17
|
+
|
|
18
|
+
### Changed
|
|
19
|
+
|
|
20
|
+
- Mirror project commands now auto-check Mirror agent guidance and install missing `guiho-as-mirror` skills when enabled.
|
|
21
|
+
- Configuration reports and schemas now include resolved agent automation settings.
|
|
22
|
+
|
|
8
23
|
## [3.0.0] - 2026-05-17
|
|
9
24
|
|
|
10
25
|
This release marks a major milestone as we prepare for the **initial open-source release** of GUIHO Mirror. We have completely overhauled the error handling experience, modernized the CI/CD publishing pipeline, and hardened the CLI commands for public usage.
|
package/DOCS.md
ADDED
|
@@ -0,0 +1,536 @@
|
|
|
1
|
+
# GUIHO Mirror Documentation
|
|
2
|
+
|
|
3
|
+
GUIHO Mirror is a deterministic CLI and TypeScript library for semantic project versioning. It reads one source of truth, calculates the next semantic version, builds a transparent release plan, and applies that plan to configured outputs such as `package.json`, `jsr.json`, and Git tags.
|
|
4
|
+
|
|
5
|
+
```text
|
|
6
|
+
source -> version engine -> plan -> outputs
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
Mirror is designed for human operators, CI jobs, and AI coding agents that need predictable release behavior instead of ad hoc version edits.
|
|
10
|
+
|
|
11
|
+
## Package Overview
|
|
12
|
+
|
|
13
|
+
- Package name: `@guiho/mirror`
|
|
14
|
+
- Runtime target: Node >= 20
|
|
15
|
+
- Development runtime: Bun
|
|
16
|
+
- Package type: ESM
|
|
17
|
+
- Library entrypoint: `source/guiho-mirror.ts`
|
|
18
|
+
- CLI entrypoint: `source/guiho-mirror-bin.ts`
|
|
19
|
+
- TypeScript build output: `library/`
|
|
20
|
+
- Standalone binary output: `bin/mirror` or `bin/mirror.exe`
|
|
21
|
+
|
|
22
|
+
The public package exposes a CLI named `mirror` and a TypeScript API for loading configuration, building release plans, reading versions, and applying version changes.
|
|
23
|
+
|
|
24
|
+
## Core Model
|
|
25
|
+
|
|
26
|
+
Mirror uses a strict read-plan-apply lifecycle.
|
|
27
|
+
|
|
28
|
+
- Project: the package, repository, application, or directory being versioned.
|
|
29
|
+
- Source: the single adapter Mirror reads the current version from.
|
|
30
|
+
- Output: one or more adapters Mirror writes the next version to.
|
|
31
|
+
- Target: a release type or exact semantic version requested by the operator.
|
|
32
|
+
- Plan: the read-only description of all intended changes before mutation.
|
|
33
|
+
- Execution: the application of a previously built plan.
|
|
34
|
+
|
|
35
|
+
Planning is the main safety boundary. Operators and agents should inspect `mirror version plan <target>` before running `mirror version apply <target>`.
|
|
36
|
+
|
|
37
|
+
## Supported Version Adapters
|
|
38
|
+
|
|
39
|
+
### `package.json`
|
|
40
|
+
|
|
41
|
+
Reads and writes the `version` field in a configured `package.json` file. It can also read the package name when `project.name_source = "package.json"`.
|
|
42
|
+
|
|
43
|
+
Default path: `package.json`
|
|
44
|
+
|
|
45
|
+
### `jsr.json`
|
|
46
|
+
|
|
47
|
+
Reads and writes the `version` field in a configured `jsr.json` file. It can also read the package name when `project.name_source = "jsr.json"`.
|
|
48
|
+
|
|
49
|
+
Default path: `jsr.json`
|
|
50
|
+
|
|
51
|
+
### `git`
|
|
52
|
+
|
|
53
|
+
Reads versions from Git tags and writes release tags. Git is required only when `git` is used as the version source, as an output, or when release commits or pushes are enabled.
|
|
54
|
+
|
|
55
|
+
Supported tag templates:
|
|
56
|
+
|
|
57
|
+
- `v{version}`
|
|
58
|
+
- `{name}@{version}`
|
|
59
|
+
- `{name}/v{version}`
|
|
60
|
+
|
|
61
|
+
Templates that include `{name}` require a project name from `project.name`, `project.name_source = "package.json"`, or `project.name_source = "jsr.json"`.
|
|
62
|
+
|
|
63
|
+
## Release Targets
|
|
64
|
+
|
|
65
|
+
Mirror accepts semver release types and exact semantic versions.
|
|
66
|
+
|
|
67
|
+
Supported release types:
|
|
68
|
+
|
|
69
|
+
- `major`
|
|
70
|
+
- `premajor`
|
|
71
|
+
- `minor`
|
|
72
|
+
- `preminor`
|
|
73
|
+
- `patch`
|
|
74
|
+
- `prepatch`
|
|
75
|
+
- `prerelease`
|
|
76
|
+
|
|
77
|
+
Exact versions are also valid, for example `2.0.0` or `2.0.0-alpha.1`.
|
|
78
|
+
|
|
79
|
+
Prerelease identifiers come from `[version].prerelease_id` or the `--preid` CLI override. If no identifier is configured, semver prerelease targets use the default semver numeric prerelease format.
|
|
80
|
+
|
|
81
|
+
## Installation
|
|
82
|
+
|
|
83
|
+
Install Mirror as a development dependency:
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
bun add -d @guiho/mirror
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
Or with npm:
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
npm install -D @guiho/mirror
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Use the CLI through the package manager or through the installed `mirror` binary.
|
|
96
|
+
|
|
97
|
+
## Quick Start
|
|
98
|
+
|
|
99
|
+
Create a configuration file:
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
mirror init package.json
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Inspect the current version:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
mirror version current
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Preview a patch release:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
mirror version plan patch
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Apply the release plan:
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
mirror version apply patch --yes
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
When combining file outputs with Git tag output, enable release commits so tags point at the commit containing the updated version files:
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
mirror version apply patch --commit --yes
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## CLI Reference
|
|
130
|
+
|
|
131
|
+
### Global Flags
|
|
132
|
+
|
|
133
|
+
Global flags are available on commands that load configuration.
|
|
134
|
+
|
|
135
|
+
- `--config <path>`: Use an explicit `mirror.config.toml` path.
|
|
136
|
+
- `--cwd <path>`: Run as if Mirror started in this directory.
|
|
137
|
+
- `--format text|json`: Choose text output or JSON output.
|
|
138
|
+
- `--no-color`: Disable ANSI color output.
|
|
139
|
+
- `--verbose`: Print full error details and stack traces.
|
|
140
|
+
|
|
141
|
+
### Override Flags
|
|
142
|
+
|
|
143
|
+
Version and config commands accept runtime overrides.
|
|
144
|
+
|
|
145
|
+
- `--source package.json|jsr.json|git`: Override the configured version source.
|
|
146
|
+
- `--output <adapter>`: Override outputs. Repeat the flag or comma-separate values.
|
|
147
|
+
- `--package-file <path>`: Override `[package].path`.
|
|
148
|
+
- `--jsr-file <path>`: Override `[jsr].path`.
|
|
149
|
+
- `--preid <identifier>`: Override `[version].prerelease_id`.
|
|
150
|
+
|
|
151
|
+
### Apply Flags
|
|
152
|
+
|
|
153
|
+
`mirror version apply` accepts additional flags.
|
|
154
|
+
|
|
155
|
+
- `--dry-run` or `-dy`: Build and print the plan without applying it.
|
|
156
|
+
- `--commit`: Create a release commit when file outputs changed.
|
|
157
|
+
- `--push`: Create the release commit when needed, then push release refs.
|
|
158
|
+
- `--allow-dirty`: Allow release in a dirty Git worktree.
|
|
159
|
+
- `--yes` or `-y`: Apply without interactive confirmation.
|
|
160
|
+
|
|
161
|
+
### `mirror init`
|
|
162
|
+
|
|
163
|
+
Creates `mirror.config.toml` in the current working directory.
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
mirror init package.json
|
|
167
|
+
mirror init jsr.json
|
|
168
|
+
mirror init git
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Use `--yes` to overwrite an existing configuration file.
|
|
172
|
+
|
|
173
|
+
### `mirror config`
|
|
174
|
+
|
|
175
|
+
Validates and inspects configuration.
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
mirror config show
|
|
179
|
+
mirror config check
|
|
180
|
+
mirror config schema
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
- `show`: Prints the resolved configuration after defaults and CLI overrides.
|
|
184
|
+
- `check`: Validates configuration, adapter files, Git availability, and supported Git tag templates.
|
|
185
|
+
- `schema`: Prints the configuration reference.
|
|
186
|
+
|
|
187
|
+
### `mirror agents`
|
|
188
|
+
|
|
189
|
+
Installs Mirror-aware AI-agent guidance.
|
|
190
|
+
|
|
191
|
+
```bash
|
|
192
|
+
mirror agents install local
|
|
193
|
+
mirror agents install global
|
|
194
|
+
mirror agents instructions
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
- `install local`: Writes `.opencode/skills/guiho-as-mirror/SKILL.md` in the project.
|
|
198
|
+
- `install global`: Writes `~/.config/opencode/skills/guiho-as-mirror/SKILL.md`.
|
|
199
|
+
- `instructions`: Creates or updates `AGENTS.md` with the GUIHO Mirror semantic versioning section.
|
|
200
|
+
|
|
201
|
+
Global skill installation uses the user home directory. Tests and automation can override that home root with `MIRROR_AGENT_HOME`.
|
|
202
|
+
|
|
203
|
+
### `mirror version`
|
|
204
|
+
|
|
205
|
+
Reads, plans, and applies version changes.
|
|
206
|
+
|
|
207
|
+
```bash
|
|
208
|
+
mirror version current
|
|
209
|
+
mirror version next <target>
|
|
210
|
+
mirror version plan <target>
|
|
211
|
+
mirror version apply <target> --yes
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
- `current`: Prints the current version from the configured source.
|
|
215
|
+
- `next`: Prints the next version without checking outputs.
|
|
216
|
+
- `plan`: Builds and prints the read-only release plan.
|
|
217
|
+
- `apply`: Applies the release plan.
|
|
218
|
+
|
|
219
|
+
## Configuration Reference
|
|
220
|
+
|
|
221
|
+
Mirror discovers configuration in this order:
|
|
222
|
+
|
|
223
|
+
1. Explicit `--config <path>`
|
|
224
|
+
2. `mirror.config.toml` in the effective current working directory
|
|
225
|
+
3. `config/mirror.config.toml` in the effective current working directory
|
|
226
|
+
|
|
227
|
+
Root configuration takes precedence over nested `config/mirror.config.toml`.
|
|
228
|
+
|
|
229
|
+
Full configuration example:
|
|
230
|
+
|
|
231
|
+
```toml
|
|
232
|
+
schema = 1
|
|
233
|
+
|
|
234
|
+
[project]
|
|
235
|
+
name = "my-project"
|
|
236
|
+
name_source = "package.json"
|
|
237
|
+
|
|
238
|
+
[version]
|
|
239
|
+
scheme = "semver"
|
|
240
|
+
source = "package.json"
|
|
241
|
+
output = ["package.json", "git"]
|
|
242
|
+
prerelease_id = "alpha"
|
|
243
|
+
|
|
244
|
+
[package]
|
|
245
|
+
path = "package.json"
|
|
246
|
+
|
|
247
|
+
[jsr]
|
|
248
|
+
path = "jsr.json"
|
|
249
|
+
|
|
250
|
+
[git]
|
|
251
|
+
tag_template = "{name}@{version}"
|
|
252
|
+
commit = false
|
|
253
|
+
push = false
|
|
254
|
+
allow_dirty = false
|
|
255
|
+
|
|
256
|
+
[agents]
|
|
257
|
+
write_changelog = true
|
|
258
|
+
changelog_path = "CHANGELOG.md"
|
|
259
|
+
auto_agents_md = true
|
|
260
|
+
auto_skill_install = true
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
### `schema`
|
|
264
|
+
|
|
265
|
+
Required. Must be `1`.
|
|
266
|
+
|
|
267
|
+
### `[project]`
|
|
268
|
+
|
|
269
|
+
- `name`: Optional explicit project name.
|
|
270
|
+
- `name_source`: Optional adapter used to read the project name. Supported values are `package.json` and `jsr.json`.
|
|
271
|
+
|
|
272
|
+
Use `name` for Git-only projects or when the package metadata name should not be used in tags.
|
|
273
|
+
|
|
274
|
+
### `[version]`
|
|
275
|
+
|
|
276
|
+
- `scheme`: Required when present. Only `semver` is supported.
|
|
277
|
+
- `source`: Required. Supported values are `package.json`, `jsr.json`, and `git`.
|
|
278
|
+
- `output`: Required non-empty array. Supported values are `package.json`, `jsr.json`, and `git`.
|
|
279
|
+
- `prerelease_id`: Optional prerelease identifier, for example `alpha` or `beta`.
|
|
280
|
+
|
|
281
|
+
Exactly one source is used. Multiple outputs are allowed.
|
|
282
|
+
|
|
283
|
+
### `[package]`
|
|
284
|
+
|
|
285
|
+
- `path`: Optional path to `package.json`. Default: `package.json`.
|
|
286
|
+
|
|
287
|
+
### `[jsr]`
|
|
288
|
+
|
|
289
|
+
- `path`: Optional path to `jsr.json`. Default: `jsr.json`.
|
|
290
|
+
|
|
291
|
+
### `[git]`
|
|
292
|
+
|
|
293
|
+
- `tag_template`: Optional tag format. Default: `v{version}`.
|
|
294
|
+
- `commit`: Optional release commit default. Default: `false`.
|
|
295
|
+
- `push`: Optional release push default. Default: `false`.
|
|
296
|
+
- `allow_dirty`: Optional dirty worktree behavior. Default: `false`.
|
|
297
|
+
|
|
298
|
+
If `push = true`, commit behavior is implied when file outputs are present. If file outputs and Git tag output are combined, Mirror requires commit or push behavior so the tag points at the version commit.
|
|
299
|
+
|
|
300
|
+
### `[agents]`
|
|
301
|
+
|
|
302
|
+
Agent settings tell AI coding agents how to prepare release documentation and whether Mirror should install helper guidance automatically.
|
|
303
|
+
|
|
304
|
+
- `write_changelog`: Optional. Tell agents whether changelog edits are allowed. Default: `true`.
|
|
305
|
+
- `changelog_path`: Optional. Changelog file path for agents. Default: `CHANGELOG.md`.
|
|
306
|
+
- `auto_agents_md`: Optional. Insert Mirror guidance into `AGENTS.md` when present. Default: `true`.
|
|
307
|
+
- `auto_skill_install`: Optional. Install `guiho-as-mirror` when missing. Default: `true`.
|
|
308
|
+
|
|
309
|
+
Set `write_changelog = false` when agents must skip changelog edits, even if a changelog exists. Set `changelog_path` when the changelog is not at the project root or when a package inside a monorepo writes release notes elsewhere.
|
|
310
|
+
|
|
311
|
+
## Agent Automation
|
|
312
|
+
|
|
313
|
+
Mirror can self-provision AI-agent instructions for projects that use opencode-compatible skills.
|
|
314
|
+
|
|
315
|
+
When automation is enabled, project commands check for `AGENTS.md` and for local/global `guiho-as-mirror` skill installation. If guidance is missing, Mirror notifies the user and writes the missing skill or AGENTS section.
|
|
316
|
+
|
|
317
|
+
Automation is controlled by `[agents]`.
|
|
318
|
+
|
|
319
|
+
- Disable AGENTS.md insertion with `auto_agents_md = false`.
|
|
320
|
+
- Disable local/global skill installation with `auto_skill_install = false`.
|
|
321
|
+
- Disable changelog edits by agents with `write_changelog = false`.
|
|
322
|
+
- Direct agents to the correct changelog with `changelog_path = "path/to/CHANGELOG.md"`.
|
|
323
|
+
|
|
324
|
+
The generated AGENTS section instructs agents to invoke `guiho-as-mirror` for versioning work, inspect `mirror.config.toml`, respect `write_changelog`, and use `changelog_path` for changelog edits.
|
|
325
|
+
|
|
326
|
+
## Release Safety Rules
|
|
327
|
+
|
|
328
|
+
Mirror intentionally separates planning from mutation.
|
|
329
|
+
|
|
330
|
+
- Always run `mirror version plan <target>` before applying a release.
|
|
331
|
+
- Do not hand-edit configured version fields as a substitute for Mirror.
|
|
332
|
+
- Do not create release tags manually for Mirror-managed releases unless recovering intentionally.
|
|
333
|
+
- Do not apply after failed typecheck or tests.
|
|
334
|
+
- Do not push release refs unless requested or configured.
|
|
335
|
+
- Do not continue on a dirty Git worktree unless `allow_dirty = true` or `--allow-dirty` was provided intentionally.
|
|
336
|
+
|
|
337
|
+
`mirror version apply` refuses to mutate unless `--yes` is passed, unless `--dry-run` is used.
|
|
338
|
+
|
|
339
|
+
## Recommended Agent Release Workflow
|
|
340
|
+
|
|
341
|
+
When an AI coding agent prepares a Mirror-managed release, it should follow this sequence.
|
|
342
|
+
|
|
343
|
+
1. Confirm the target and project root.
|
|
344
|
+
2. Run `mirror config show` and inspect `allow_dirty`, `write_changelog`, and `changelog_path`.
|
|
345
|
+
3. Check `git status --short` when dirty worktrees are not allowed.
|
|
346
|
+
4. Run the project typechecker.
|
|
347
|
+
5. Run the project test suite.
|
|
348
|
+
6. Run `mirror version plan <target>`.
|
|
349
|
+
7. Update release documentation when needed.
|
|
350
|
+
8. Update `[agents].changelog_path` only when `write_changelog` is not false and the file exists or is part of the release process.
|
|
351
|
+
9. Commit release-preparation documentation before applying the version bump.
|
|
352
|
+
10. Run `mirror version apply <target> --yes`, adding `--commit` when file outputs and Git tag output are combined.
|
|
353
|
+
|
|
354
|
+
## Documentation Requirement Before Publishing
|
|
355
|
+
|
|
356
|
+
Every behavior change must be documented before publishing a new version. This includes changes to CLI commands, configuration fields, TypeScript APIs, release behavior, Git behavior, package contents, agent automation, tests that describe public behavior, and operational workflows.
|
|
357
|
+
|
|
358
|
+
Before a version is published, update this file and any other relevant user-facing documentation so the published package describes the behavior that is actually shipping. If a code change does not require documentation, the release preparation should still state why no documentation update was needed.
|
|
359
|
+
|
|
360
|
+
## TypeScript API
|
|
361
|
+
|
|
362
|
+
Mirror exports types and functions from `source/guiho-mirror.ts`.
|
|
363
|
+
|
|
364
|
+
Common release-plan API:
|
|
365
|
+
|
|
366
|
+
```ts
|
|
367
|
+
import { applyVersionPlan, buildVersionPlan, executeVersionPlan } from '@guiho/mirror'
|
|
368
|
+
|
|
369
|
+
const plan = await buildVersionPlan('patch', { cwd: process.cwd() })
|
|
370
|
+
|
|
371
|
+
console.log(plan.currentVersion)
|
|
372
|
+
console.log(plan.nextVersion)
|
|
373
|
+
console.log(plan.actions)
|
|
374
|
+
|
|
375
|
+
await executeVersionPlan(plan, { yes: true })
|
|
376
|
+
|
|
377
|
+
await applyVersionPlan('minor', { cwd: process.cwd(), yes: true })
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
Configuration and read API:
|
|
381
|
+
|
|
382
|
+
```ts
|
|
383
|
+
import { loadMirrorConfig, readCurrentVersion } from '@guiho/mirror'
|
|
384
|
+
|
|
385
|
+
const config = await loadMirrorConfig({ cwd: process.cwd() })
|
|
386
|
+
const version = await readCurrentVersion(config)
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
Agent automation API:
|
|
390
|
+
|
|
391
|
+
```ts
|
|
392
|
+
import {
|
|
393
|
+
ensureMirrorAgentsInstructions,
|
|
394
|
+
installMirrorSkill,
|
|
395
|
+
runMirrorAgentAutomation,
|
|
396
|
+
} from '@guiho/mirror'
|
|
397
|
+
|
|
398
|
+
await ensureMirrorAgentsInstructions(process.cwd(), true)
|
|
399
|
+
await installMirrorSkill('local', { cwd: process.cwd() })
|
|
400
|
+
await runMirrorAgentAutomation({ cwd: process.cwd() })
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
The API uses the same configuration discovery and safety rules as the CLI.
|
|
404
|
+
|
|
405
|
+
## Internal Source Map
|
|
406
|
+
|
|
407
|
+
- `source/guiho-mirror.ts`: public library export surface.
|
|
408
|
+
- `source/guiho-mirror-bin.ts`: CLI binary entrypoint.
|
|
409
|
+
- `source/cli.ts`: citty command tree, CLI argument mapping, and process-facing error handling.
|
|
410
|
+
- `source/config.ts`: TOML discovery, schema validation, defaulting, init config generation, and override merge.
|
|
411
|
+
- `source/types.ts`: public and internal TypeScript types.
|
|
412
|
+
- `source/version.ts`: semver target validation and next-version resolution.
|
|
413
|
+
- `source/adapters.ts`: package, JSR, and Git read/write primitives.
|
|
414
|
+
- `source/plan.ts`: validation and read-only release plan construction.
|
|
415
|
+
- `source/executor.ts`: mutation layer for file writes, Git commits, tags, and pushes.
|
|
416
|
+
- `source/reporter.ts`: text and JSON report formatting.
|
|
417
|
+
- `source/agents.ts`: agent skill installation and AGENTS.md guidance automation.
|
|
418
|
+
- `source/errors.ts`: user-facing errors with stable exit codes.
|
|
419
|
+
- `source/guiho-mirror.spec.ts`: Bun test coverage for configuration, adapters, planning, execution, CLI behavior, Git behavior, and agent automation.
|
|
420
|
+
- `skills/guiho-as-mirror/SKILL.md`: bundled AI-agent skill installed by `mirror agents` commands.
|
|
421
|
+
|
|
422
|
+
## Development Workflow
|
|
423
|
+
|
|
424
|
+
Run package commands from `mirror/`.
|
|
425
|
+
|
|
426
|
+
```bash
|
|
427
|
+
bun install
|
|
428
|
+
bun run typecheck
|
|
429
|
+
bun test
|
|
430
|
+
bun run build
|
|
431
|
+
bun run binary
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
Generated outputs are ignored and should not be hand-edited.
|
|
435
|
+
|
|
436
|
+
- `library/`: TypeScript build output used by `main` and `types`.
|
|
437
|
+
- `bin/`: compiled standalone CLI binary output.
|
|
438
|
+
- `bundle/`: optional bundled output.
|
|
439
|
+
|
|
440
|
+
There is no lint or formatter config. Existing source style is strict TypeScript, ESM imports, single quotes, and no semicolons.
|
|
441
|
+
|
|
442
|
+
## Testing
|
|
443
|
+
|
|
444
|
+
The test suite uses `bun test` and `bun:test`.
|
|
445
|
+
|
|
446
|
+
Current tests cover:
|
|
447
|
+
|
|
448
|
+
- CLI flag parsing and short aliases.
|
|
449
|
+
- Config discovery and validation.
|
|
450
|
+
- CLI overrides over config values.
|
|
451
|
+
- Package and JSR version reads/writes.
|
|
452
|
+
- Semver target resolution.
|
|
453
|
+
- Git tag parsing and rendering.
|
|
454
|
+
- Release plan construction.
|
|
455
|
+
- Apply behavior, dry-run behavior, commits, tags, pushes, and dirty worktree checks.
|
|
456
|
+
- Git unavailable behavior.
|
|
457
|
+
- Agent automation settings, AGENTS.md insertion, skill installation, and changelog path guidance.
|
|
458
|
+
|
|
459
|
+
Run all tests:
|
|
460
|
+
|
|
461
|
+
```bash
|
|
462
|
+
bun test
|
|
463
|
+
```
|
|
464
|
+
|
|
465
|
+
Run one file:
|
|
466
|
+
|
|
467
|
+
```bash
|
|
468
|
+
bun test source/guiho-mirror.spec.ts
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
## Build and Binary
|
|
472
|
+
|
|
473
|
+
Build the library:
|
|
474
|
+
|
|
475
|
+
```bash
|
|
476
|
+
bun run build
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
Compile the standalone binary:
|
|
480
|
+
|
|
481
|
+
```bash
|
|
482
|
+
bun run binary
|
|
483
|
+
```
|
|
484
|
+
|
|
485
|
+
The compiled binary embeds fallback `guiho-as-mirror` skill content so `mirror agents install local` and `mirror agents install global` still work when adjacent package files are not available.
|
|
486
|
+
|
|
487
|
+
## Publishing Checklist
|
|
488
|
+
|
|
489
|
+
Before publishing a new version:
|
|
490
|
+
|
|
491
|
+
1. Confirm intended changes are committed.
|
|
492
|
+
2. Confirm `DOCS.md` reflects all changed behavior.
|
|
493
|
+
3. Confirm other relevant docs are updated, including `README.md`, `AGENTS.md`, and the configured changelog path when applicable.
|
|
494
|
+
4. Run `bun run typecheck`.
|
|
495
|
+
5. Run `bun test`.
|
|
496
|
+
6. Run `bun run build`.
|
|
497
|
+
7. Run `bun run binary` when the CLI binary is part of the release validation.
|
|
498
|
+
8. Run `mirror version plan <target>`.
|
|
499
|
+
9. Commit release documentation updates before applying the version bump.
|
|
500
|
+
10. Run `mirror version apply <target> --yes` with the required commit or push flags.
|
|
501
|
+
|
|
502
|
+
Do not publish a new version when documentation is stale relative to the code being released.
|
|
503
|
+
|
|
504
|
+
## Troubleshooting
|
|
505
|
+
|
|
506
|
+
### Configuration not found
|
|
507
|
+
|
|
508
|
+
Run `mirror init package.json`, `mirror init jsr.json`, or `mirror init git` from the project root, or pass `--config <path>`.
|
|
509
|
+
|
|
510
|
+
### Adapter file not found
|
|
511
|
+
|
|
512
|
+
Check `[package].path` or `[jsr].path`, or pass `--package-file` or `--jsr-file`.
|
|
513
|
+
|
|
514
|
+
### Unsupported Git tag template
|
|
515
|
+
|
|
516
|
+
Use one of the supported templates: `v{version}`, `{name}@{version}`, or `{name}/v{version}`.
|
|
517
|
+
|
|
518
|
+
### Git executable not found
|
|
519
|
+
|
|
520
|
+
Install Git or remove Git from the configured source/output. Git is required only for Git-based workflows.
|
|
521
|
+
|
|
522
|
+
### Dirty Git worktree
|
|
523
|
+
|
|
524
|
+
Commit or stash changes before applying a release, or intentionally enable `allow_dirty = true` or pass `--allow-dirty`.
|
|
525
|
+
|
|
526
|
+
### File outputs with Git tag output require commit or push
|
|
527
|
+
|
|
528
|
+
Use `--commit`, `--push`, `[git].commit = true`, or `[git].push = true` so the release tag points at the commit containing updated version files.
|
|
529
|
+
|
|
530
|
+
### Changelog should not be edited
|
|
531
|
+
|
|
532
|
+
Set `[agents].write_changelog = false` in `mirror.config.toml`.
|
|
533
|
+
|
|
534
|
+
### Changelog is not at project root
|
|
535
|
+
|
|
536
|
+
Set `[agents].changelog_path` to the correct path, for example `changelog_path = "../CHANGELOG.md"` in a package subdirectory.
|
package/README.md
CHANGED
|
@@ -8,6 +8,8 @@ Mirror is a powerful, deterministic CLI and TypeScript library for semantic proj
|
|
|
8
8
|
source -> version engine -> plan -> outputs
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
+
Mirror runs on **Node >= 20** at runtime. Bun is the recommended development tool (build, test, typecheck). Git is required **only** for Git-based workflows (`source: "git"`, `output: ["git"]`, or commit/tag/push operations).
|
|
12
|
+
|
|
11
13
|
---
|
|
12
14
|
|
|
13
15
|
## 🚀 Quick Start
|
|
@@ -15,6 +17,8 @@ source -> version engine -> plan -> outputs
|
|
|
15
17
|
### Installation
|
|
16
18
|
|
|
17
19
|
```bash
|
|
20
|
+
npm install -D @guiho/mirror
|
|
21
|
+
# or
|
|
18
22
|
bun add -d @guiho/mirror
|
|
19
23
|
```
|
|
20
24
|
|
|
@@ -62,7 +66,7 @@ Mirror uses a strict release model:
|
|
|
62
66
|
Adapters connect Mirror to different versioning ecosystems:
|
|
63
67
|
- `package.json`: Reads/writes the `version` field in a `package.json` file.
|
|
64
68
|
- `jsr.json`: Reads/writes the `version` field in a `jsr.json` file.
|
|
65
|
-
- `git`: Reads versions from Git tags and creates release tags/commits.
|
|
69
|
+
- `git`: Reads versions from Git tags and creates release tags/commits. Requires Git to be installed and accessible in `PATH`.
|
|
66
70
|
|
|
67
71
|
### CLI Commands
|
|
68
72
|
|
|
@@ -80,6 +84,12 @@ Validates and inspects configuration.
|
|
|
80
84
|
- `mirror config check`: Validates configuration without output.
|
|
81
85
|
- `mirror config schema`: Prints the comprehensive configuration reference.
|
|
82
86
|
|
|
87
|
+
#### `mirror agents`
|
|
88
|
+
Installs Mirror-aware agent guidance for projects that use AI coding agents.
|
|
89
|
+
- `mirror agents install local`: Installs the bundled `guiho-as-mirror` skill at `.opencode/skills/guiho-as-mirror/SKILL.md`.
|
|
90
|
+
- `mirror agents install global`: Installs the bundled `guiho-as-mirror` skill at `~/.config/opencode/skills/guiho-as-mirror/SKILL.md`.
|
|
91
|
+
- `mirror agents instructions`: Creates or updates `AGENTS.md` with the GUIHO Mirror semantic versioning section.
|
|
92
|
+
|
|
83
93
|
#### `mirror version`
|
|
84
94
|
Manages the version lifecycle.
|
|
85
95
|
- `mirror version current`: Prints the current project version.
|
|
@@ -117,8 +127,20 @@ tag_template = "{name}@{version}" # Optional. Supported: "v{version}", "{na
|
|
|
117
127
|
commit = false # Optional. Create release commits. Default: false.
|
|
118
128
|
push = false # Optional. Push release refs. Default: false.
|
|
119
129
|
allow_dirty = false # Optional. Allow dirty Git worktree. Default: false.
|
|
130
|
+
|
|
131
|
+
[agents]
|
|
132
|
+
write_changelog = true # Optional. Tell agents changelog edits are allowed. Default: true.
|
|
133
|
+
changelog_path = "CHANGELOG.md" # Optional. Changelog file path for agents. Default: "CHANGELOG.md".
|
|
134
|
+
auto_agents_md = true # Optional. Insert Mirror guidance into AGENTS.md when present. Default: true.
|
|
135
|
+
auto_skill_install = true # Optional. Install guiho-as-mirror when missing. Default: true.
|
|
120
136
|
```
|
|
121
137
|
|
|
138
|
+
### Agent Automation
|
|
139
|
+
|
|
140
|
+
Mirror is designed to be safely used by AI agents. Project commands automatically check for `AGENTS.md` and the `guiho-as-mirror` skill, then add the Mirror guidance or install the missing skill when automation is enabled.
|
|
141
|
+
|
|
142
|
+
Set `write_changelog = false` when agents should skip changelog edits during release preparation. Set `changelog_path = "docs/CHANGELOG.md"` when the changelog is not at the project root. Set `auto_agents_md = false` or `auto_skill_install = false` to opt out of automatic guidance insertion or skill installation.
|
|
143
|
+
|
|
122
144
|
### Safety & Git Automation
|
|
123
145
|
|
|
124
146
|
By default, `mirror version apply` prevents accidental mutations:
|
|
@@ -170,7 +192,7 @@ const version = await readCurrentVersion(config)
|
|
|
170
192
|
|
|
171
193
|
## 🛠️ Development
|
|
172
194
|
|
|
173
|
-
Development tasks require Bun and
|
|
195
|
+
Development tasks require Bun and Node >= 20. Run from the `mirror/` directory:
|
|
174
196
|
|
|
175
197
|
```bash
|
|
176
198
|
cd mirror
|
package/jsr.json
CHANGED
package/library/adapters.d.ts
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
|
|
3
3
|
*/
|
|
4
|
-
import type { MirrorConfig, MirrorJsonObject } from './types';
|
|
4
|
+
import type { MirrorConfig, MirrorJsonObject } from './types.js';
|
|
5
|
+
export declare const ensureGitAvailable: () => Promise<void>;
|
|
5
6
|
export declare const supportedGitTagTemplates: readonly ["v{version}", "{name}@{version}", "{name}/v{version}"];
|
|
6
7
|
export declare const readPackageJson: (path: string) => Promise<MirrorJsonObject>;
|
|
7
8
|
export declare const readJsrJson: (path: string) => Promise<MirrorJsonObject>;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../source/adapters.ts"],"names":[],"mappings":"AAAA;;GAEG;
|
|
1
|
+
{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../source/adapters.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAsBhE,eAAO,MAAM,kBAAkB,qBAI9B,CAAA;AAiBD,eAAO,MAAM,wBAAwB,kEAAmE,CAAA;AAExG,eAAO,MAAM,eAAe,GAAU,MAAM,MAAM,KAAG,OAAO,CAAC,gBAAgB,CAAyC,CAAA;AACtH,eAAO,MAAM,WAAW,GAAU,MAAM,MAAM,KAAG,OAAO,CAAC,gBAAgB,CAAqC,CAAA;AAE9G,eAAO,MAAM,eAAe,GAAU,MAAM,MAAM,EAAE,QAAQ,gBAAgB,kBAE3E,CAAA;AAED,eAAO,MAAM,kBAAkB,GAAU,QAAQ,YAAY,oBAAyF,CAAA;AACtJ,eAAO,MAAM,cAAc,GAAU,QAAQ,YAAY,oBAAiF,CAAA;AAC1I,eAAO,MAAM,eAAe,GAAU,QAAQ,YAAY,oBAAsF,CAAA;AAChJ,eAAO,MAAM,WAAW,GAAU,QAAQ,YAAY,oBAA8E,CAAA;AAEpI,eAAO,MAAM,mBAAmB,GAAU,QAAQ,YAAY,EAAE,aAAa,MAAM,kBACiB,CAAA;AAEpG,eAAO,MAAM,eAAe,GAAU,QAAQ,YAAY,EAAE,aAAa,MAAM,kBACa,CAAA;AAE5F,eAAO,MAAM,kBAAkB,GAAU,QAAQ,YAAY,kBAI5D,CAAA;AAED,eAAO,MAAM,kBAAkB,GAAU,QAAQ,YAAY,gCAK5D,CAAA;AAED,eAAO,MAAM,kBAAkB,GAAU,QAAQ,YAAY,EAAE,cAAc,MAAM,oBAIlF,CAAA;AAED,eAAO,MAAM,cAAc,GAAU,QAAQ,YAAY,EAAE,cAAc,MAAM,oBAe9E,CAAA;AAED,eAAO,MAAM,YAAY,GAAI,UAAU,MAAM,EAAE,SAAS,MAAM,EAAE,cAAc,MAAM,WAOnF,CAAA;AAED,eAAO,MAAM,cAAc,GAAI,UAAU,MAAM,EAAE,KAAK,MAAM,EAAE,cAAc,MAAM,uBAmBjF,CAAA;AAED,eAAO,MAAM,6BAA6B,GAAI,UAAU,MAAM,SAI7D,CAAA;AAED,eAAO,MAAM,eAAe,GAAU,KAAK,MAAM,qBAQhD,CAAA;AAED,eAAO,MAAM,UAAU,GAAU,KAAK,MAAM,qBAG3C,CAAA;AAED,eAAO,MAAM,eAAe,GAAU,KAAK,MAAM,EAAE,OAAO,MAAM,EAAE,EAAE,SAAS,MAAM,kBAIlF,CAAA;AAED,eAAO,MAAM,YAAY,GAAU,KAAK,MAAM,EAAE,KAAK,MAAM,kBAG1D,CAAA;AAED,eAAO,MAAM,WAAW,GAAU,KAAK,MAAM,EAAE,eAAe,OAAO,EAAE,aAAa,OAAO,kBAI1F,CAAA"}
|