@guiho/mirror 3.0.0 → 3.1.1

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 CHANGED
@@ -5,6 +5,29 @@ 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.1] - 2026-06-07
9
+
10
+ ### Changed
11
+
12
+ - Changed Mirror skill installation paths to the standard `.agents/skills` and `~/.agents/skills` directories.
13
+ - Changed automatic skill installation to global-only by default while keeping explicit local installation available through `mirror agents install local`.
14
+ - Updated documentation, schema text, and tests to describe the standard agent skill directories.
15
+
16
+ ## [3.1.0] - 2026-06-07
17
+
18
+ ### Added
19
+
20
+ - Added Mirror agent automation commands for installing the bundled `guiho-as-mirror` skill locally or globally.
21
+ - Added `mirror agents instructions` to create or update `AGENTS.md` with Mirror semantic versioning guidance.
22
+ - Added `[agents]` configuration for changelog behavior, changelog path selection, AGENTS.md insertion, and automatic skill installation.
23
+ - Added the bundled `guiho-as-mirror` skill to the published package.
24
+ - Added full package documentation in `mirror/DOCS.md` and repository guidance requiring documentation updates before publishing new versions.
25
+
26
+ ### Changed
27
+
28
+ - Mirror project commands now auto-check Mirror agent guidance and install missing `guiho-as-mirror` skills when enabled.
29
+ - Configuration reports and schemas now include resolved agent automation settings.
30
+
8
31
  ## [3.0.0] - 2026-05-17
9
32
 
10
33
  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,543 @@
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 `.agents/skills/guiho-as-mirror/SKILL.md` in the project.
198
+ - `install global`: Writes `~/.agents/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
+ Automatic skill installation is global-only by default. Use `mirror agents install local` when a project-local `.agents/skills/guiho-as-mirror/SKILL.md` copy is intentionally needed.
204
+
205
+ ### `mirror version`
206
+
207
+ Reads, plans, and applies version changes.
208
+
209
+ ```bash
210
+ mirror version current
211
+ mirror version next <target>
212
+ mirror version plan <target>
213
+ mirror version apply <target> --yes
214
+ ```
215
+
216
+ - `current`: Prints the current version from the configured source.
217
+ - `next`: Prints the next version without checking outputs.
218
+ - `plan`: Builds and prints the read-only release plan.
219
+ - `apply`: Applies the release plan.
220
+
221
+ ## Configuration Reference
222
+
223
+ Mirror discovers configuration in this order:
224
+
225
+ 1. Explicit `--config <path>`
226
+ 2. `mirror.config.toml` in the effective current working directory
227
+ 3. `config/mirror.config.toml` in the effective current working directory
228
+
229
+ Root configuration takes precedence over nested `config/mirror.config.toml`.
230
+
231
+ Full configuration example:
232
+
233
+ ```toml
234
+ schema = 1
235
+
236
+ [project]
237
+ name = "my-project"
238
+ name_source = "package.json"
239
+
240
+ [version]
241
+ scheme = "semver"
242
+ source = "package.json"
243
+ output = ["package.json", "git"]
244
+ prerelease_id = "alpha"
245
+
246
+ [package]
247
+ path = "package.json"
248
+
249
+ [jsr]
250
+ path = "jsr.json"
251
+
252
+ [git]
253
+ tag_template = "{name}@{version}"
254
+ commit = false
255
+ push = false
256
+ allow_dirty = false
257
+
258
+ [agents]
259
+ write_changelog = true
260
+ changelog_path = "CHANGELOG.md"
261
+ auto_agents_md = true
262
+ auto_skill_install = true
263
+ ```
264
+
265
+ ### `schema`
266
+
267
+ Required. Must be `1`.
268
+
269
+ ### `[project]`
270
+
271
+ - `name`: Optional explicit project name.
272
+ - `name_source`: Optional adapter used to read the project name. Supported values are `package.json` and `jsr.json`.
273
+
274
+ Use `name` for Git-only projects or when the package metadata name should not be used in tags.
275
+
276
+ ### `[version]`
277
+
278
+ - `scheme`: Required when present. Only `semver` is supported.
279
+ - `source`: Required. Supported values are `package.json`, `jsr.json`, and `git`.
280
+ - `output`: Required non-empty array. Supported values are `package.json`, `jsr.json`, and `git`.
281
+ - `prerelease_id`: Optional prerelease identifier, for example `alpha` or `beta`.
282
+
283
+ Exactly one source is used. Multiple outputs are allowed.
284
+
285
+ ### `[package]`
286
+
287
+ - `path`: Optional path to `package.json`. Default: `package.json`.
288
+
289
+ ### `[jsr]`
290
+
291
+ - `path`: Optional path to `jsr.json`. Default: `jsr.json`.
292
+
293
+ ### `[git]`
294
+
295
+ - `tag_template`: Optional tag format. Default: `v{version}`.
296
+ - `commit`: Optional release commit default. Default: `false`.
297
+ - `push`: Optional release push default. Default: `false`.
298
+ - `allow_dirty`: Optional dirty worktree behavior. Default: `false`.
299
+
300
+ 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.
301
+
302
+ ### `[agents]`
303
+
304
+ Agent settings tell AI coding agents how to prepare release documentation and whether Mirror should install helper guidance automatically.
305
+
306
+ - `write_changelog`: Optional. Tell agents whether changelog edits are allowed. Default: `true`.
307
+ - `changelog_path`: Optional. Changelog file path for agents. Default: `CHANGELOG.md`.
308
+ - `auto_agents_md`: Optional. Insert Mirror guidance into `AGENTS.md` when present. Default: `true`.
309
+ - `auto_skill_install`: Optional. Install `guiho-as-mirror` globally when missing. Default: `true`.
310
+
311
+ 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.
312
+
313
+ Mirror uses standard agent skill directories:
314
+
315
+ - Local: `.agents/skills/<skill-name>/SKILL.md`
316
+ - Global: `~/.agents/skills/<skill-name>/SKILL.md`
317
+
318
+ ## Agent Automation
319
+
320
+ Mirror can self-provision AI-agent instructions for projects that use standard agent skill directories.
321
+
322
+ When automation is enabled, project commands check for `AGENTS.md` and for global `guiho-as-mirror` skill installation. If guidance is missing, Mirror notifies the user and writes the missing global skill or AGENTS section. Mirror does not automatically write a local skill file; local installation is explicit.
323
+
324
+ Automation is controlled by `[agents]`.
325
+
326
+ - Disable AGENTS.md insertion with `auto_agents_md = false`.
327
+ - Disable automatic global skill installation with `auto_skill_install = false`.
328
+ - Disable changelog edits by agents with `write_changelog = false`.
329
+ - Direct agents to the correct changelog with `changelog_path = "path/to/CHANGELOG.md"`.
330
+
331
+ 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. Use `mirror agents install local` only when a project-local skill copy is desired explicitly.
332
+
333
+ ## Release Safety Rules
334
+
335
+ Mirror intentionally separates planning from mutation.
336
+
337
+ - Always run `mirror version plan <target>` before applying a release.
338
+ - Do not hand-edit configured version fields as a substitute for Mirror.
339
+ - Do not create release tags manually for Mirror-managed releases unless recovering intentionally.
340
+ - Do not apply after failed typecheck or tests.
341
+ - Do not push release refs unless requested or configured.
342
+ - Do not continue on a dirty Git worktree unless `allow_dirty = true` or `--allow-dirty` was provided intentionally.
343
+
344
+ `mirror version apply` refuses to mutate unless `--yes` is passed, unless `--dry-run` is used.
345
+
346
+ ## Recommended Agent Release Workflow
347
+
348
+ When an AI coding agent prepares a Mirror-managed release, it should follow this sequence.
349
+
350
+ 1. Confirm the target and project root.
351
+ 2. Run `mirror config show` and inspect `allow_dirty`, `write_changelog`, and `changelog_path`.
352
+ 3. Check `git status --short` when dirty worktrees are not allowed.
353
+ 4. Run the project typechecker.
354
+ 5. Run the project test suite.
355
+ 6. Run `mirror version plan <target>`.
356
+ 7. Update release documentation when needed.
357
+ 8. Update `[agents].changelog_path` only when `write_changelog` is not false and the file exists or is part of the release process.
358
+ 9. Commit release-preparation documentation before applying the version bump.
359
+ 10. Run `mirror version apply <target> --yes`, adding `--commit` when file outputs and Git tag output are combined.
360
+
361
+ ## Documentation Requirement Before Publishing
362
+
363
+ 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.
364
+
365
+ 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.
366
+
367
+ ## TypeScript API
368
+
369
+ Mirror exports types and functions from `source/guiho-mirror.ts`.
370
+
371
+ Common release-plan API:
372
+
373
+ ```ts
374
+ import { applyVersionPlan, buildVersionPlan, executeVersionPlan } from '@guiho/mirror'
375
+
376
+ const plan = await buildVersionPlan('patch', { cwd: process.cwd() })
377
+
378
+ console.log(plan.currentVersion)
379
+ console.log(plan.nextVersion)
380
+ console.log(plan.actions)
381
+
382
+ await executeVersionPlan(plan, { yes: true })
383
+
384
+ await applyVersionPlan('minor', { cwd: process.cwd(), yes: true })
385
+ ```
386
+
387
+ Configuration and read API:
388
+
389
+ ```ts
390
+ import { loadMirrorConfig, readCurrentVersion } from '@guiho/mirror'
391
+
392
+ const config = await loadMirrorConfig({ cwd: process.cwd() })
393
+ const version = await readCurrentVersion(config)
394
+ ```
395
+
396
+ Agent automation API:
397
+
398
+ ```ts
399
+ import {
400
+ ensureMirrorAgentsInstructions,
401
+ installMirrorSkill,
402
+ runMirrorAgentAutomation,
403
+ } from '@guiho/mirror'
404
+
405
+ await ensureMirrorAgentsInstructions(process.cwd(), true)
406
+ await installMirrorSkill('local', { cwd: process.cwd() })
407
+ await runMirrorAgentAutomation({ cwd: process.cwd() })
408
+ ```
409
+
410
+ The API uses the same configuration discovery and safety rules as the CLI.
411
+
412
+ ## Internal Source Map
413
+
414
+ - `source/guiho-mirror.ts`: public library export surface.
415
+ - `source/guiho-mirror-bin.ts`: CLI binary entrypoint.
416
+ - `source/cli.ts`: citty command tree, CLI argument mapping, and process-facing error handling.
417
+ - `source/config.ts`: TOML discovery, schema validation, defaulting, init config generation, and override merge.
418
+ - `source/types.ts`: public and internal TypeScript types.
419
+ - `source/version.ts`: semver target validation and next-version resolution.
420
+ - `source/adapters.ts`: package, JSR, and Git read/write primitives.
421
+ - `source/plan.ts`: validation and read-only release plan construction.
422
+ - `source/executor.ts`: mutation layer for file writes, Git commits, tags, and pushes.
423
+ - `source/reporter.ts`: text and JSON report formatting.
424
+ - `source/agents.ts`: agent skill installation and AGENTS.md guidance automation.
425
+ - `source/errors.ts`: user-facing errors with stable exit codes.
426
+ - `source/guiho-mirror.spec.ts`: Bun test coverage for configuration, adapters, planning, execution, CLI behavior, Git behavior, and agent automation.
427
+ - `skills/guiho-as-mirror/SKILL.md`: bundled AI-agent skill installed by `mirror agents` commands.
428
+
429
+ ## Development Workflow
430
+
431
+ Run package commands from `mirror/`.
432
+
433
+ ```bash
434
+ bun install
435
+ bun run typecheck
436
+ bun test
437
+ bun run build
438
+ bun run binary
439
+ ```
440
+
441
+ Generated outputs are ignored and should not be hand-edited.
442
+
443
+ - `library/`: TypeScript build output used by `main` and `types`.
444
+ - `bin/`: compiled standalone CLI binary output.
445
+ - `bundle/`: optional bundled output.
446
+
447
+ There is no lint or formatter config. Existing source style is strict TypeScript, ESM imports, single quotes, and no semicolons.
448
+
449
+ ## Testing
450
+
451
+ The test suite uses `bun test` and `bun:test`.
452
+
453
+ Current tests cover:
454
+
455
+ - CLI flag parsing and short aliases.
456
+ - Config discovery and validation.
457
+ - CLI overrides over config values.
458
+ - Package and JSR version reads/writes.
459
+ - Semver target resolution.
460
+ - Git tag parsing and rendering.
461
+ - Release plan construction.
462
+ - Apply behavior, dry-run behavior, commits, tags, pushes, and dirty worktree checks.
463
+ - Git unavailable behavior.
464
+ - Agent automation settings, AGENTS.md insertion, skill installation, and changelog path guidance.
465
+
466
+ Run all tests:
467
+
468
+ ```bash
469
+ bun test
470
+ ```
471
+
472
+ Run one file:
473
+
474
+ ```bash
475
+ bun test source/guiho-mirror.spec.ts
476
+ ```
477
+
478
+ ## Build and Binary
479
+
480
+ Build the library:
481
+
482
+ ```bash
483
+ bun run build
484
+ ```
485
+
486
+ Compile the standalone binary:
487
+
488
+ ```bash
489
+ bun run binary
490
+ ```
491
+
492
+ 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.
493
+
494
+ ## Publishing Checklist
495
+
496
+ Before publishing a new version:
497
+
498
+ 1. Confirm intended changes are committed.
499
+ 2. Confirm `DOCS.md` reflects all changed behavior.
500
+ 3. Confirm other relevant docs are updated, including `README.md`, `AGENTS.md`, and the configured changelog path when applicable.
501
+ 4. Run `bun run typecheck`.
502
+ 5. Run `bun test`.
503
+ 6. Run `bun run build`.
504
+ 7. Run `bun run binary` when the CLI binary is part of the release validation.
505
+ 8. Run `mirror version plan <target>`.
506
+ 9. Commit release documentation updates before applying the version bump.
507
+ 10. Run `mirror version apply <target> --yes` with the required commit or push flags.
508
+
509
+ Do not publish a new version when documentation is stale relative to the code being released.
510
+
511
+ ## Troubleshooting
512
+
513
+ ### Configuration not found
514
+
515
+ Run `mirror init package.json`, `mirror init jsr.json`, or `mirror init git` from the project root, or pass `--config <path>`.
516
+
517
+ ### Adapter file not found
518
+
519
+ Check `[package].path` or `[jsr].path`, or pass `--package-file` or `--jsr-file`.
520
+
521
+ ### Unsupported Git tag template
522
+
523
+ Use one of the supported templates: `v{version}`, `{name}@{version}`, or `{name}/v{version}`.
524
+
525
+ ### Git executable not found
526
+
527
+ Install Git or remove Git from the configured source/output. Git is required only for Git-based workflows.
528
+
529
+ ### Dirty Git worktree
530
+
531
+ Commit or stash changes before applying a release, or intentionally enable `allow_dirty = true` or pass `--allow-dirty`.
532
+
533
+ ### File outputs with Git tag output require commit or push
534
+
535
+ Use `--commit`, `--push`, `[git].commit = true`, or `[git].push = true` so the release tag points at the commit containing updated version files.
536
+
537
+ ### Changelog should not be edited
538
+
539
+ Set `[agents].write_changelog = false` in `mirror.config.toml`.
540
+
541
+ ### Changelog is not at project root
542
+
543
+ 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 `.agents/skills/guiho-as-mirror/SKILL.md`.
90
+ - `mirror agents install global`: Installs the bundled `guiho-as-mirror` skill at `~/.agents/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 globally 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` to opt out of automatic guidance insertion, or `auto_skill_install = false` to opt out of automatic global 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 run from the `mirror/` directory:
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@guiho/mirror",
3
- "version": "3.0.0",
3
+ "version": "3.1.1",
4
4
  "exports": "./source/guiho-mirror.ts",
5
5
  "publish": {
6
6
  "include": [
@@ -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;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAK7D,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,oBAc9E,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,qBAOhD,CAAA;AAED,eAAO,MAAM,UAAU,GAAU,KAAK,MAAM,qBAG3C,CAAA;AAED,eAAO,MAAM,eAAe,GAAU,KAAK,MAAM,EAAE,OAAO,MAAM,EAAE,EAAE,SAAS,MAAM,kBAGlF,CAAA;AAED,eAAO,MAAM,YAAY,GAAU,KAAK,MAAM,EAAE,KAAK,MAAM,kBAE1D,CAAA;AAED,eAAO,MAAM,WAAW,GAAU,KAAK,MAAM,EAAE,eAAe,OAAO,EAAE,aAAa,OAAO,kBAG1F,CAAA"}
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"}