@guiho/mirror 3.2.0 → 3.3.0-alpha.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 +27 -0
- package/DOCS.md +142 -76
- package/README.md +15 -41
- package/jsr.json +4 -2
- package/package.json +11 -20
- package/schema/mirror.config.schema.json +231 -0
- package/scripts/install-package.ts +70 -0
- package/scripts/mirror-bin.ts +20 -0
- package/skills/guiho-as-mirror/SKILL.md +2 -29
- package/library/adapters.d.ts +0 -32
- package/library/adapters.d.ts.map +0 -1
- package/library/adapters.js +0 -210
- package/library/agents.d.ts +0 -27
- package/library/agents.d.ts.map +0 -1
- package/library/agents.js +0 -200
- package/library/cli.d.ts +0 -29
- package/library/cli.d.ts.map +0 -1
- package/library/cli.js +0 -387
- package/library/config.d.ts +0 -18
- package/library/config.d.ts.map +0 -1
- package/library/config.js +0 -277
- package/library/errors.d.ts +0 -9
- package/library/errors.d.ts.map +0 -1
- package/library/errors.js +0 -15
- package/library/executor.d.ts +0 -7
- package/library/executor.d.ts.map +0 -1
- package/library/executor.js +0 -32
- package/library/flags.d.ts +0 -6
- package/library/flags.d.ts.map +0 -1
- package/library/flags.js +0 -80
- package/library/guiho-mirror-bin.d.ts +0 -6
- package/library/guiho-mirror-bin.d.ts.map +0 -1
- package/library/guiho-mirror-bin.js +0 -6
- package/library/guiho-mirror.d.ts +0 -17
- package/library/guiho-mirror.d.ts.map +0 -1
- package/library/guiho-mirror.js +0 -15
- package/library/init.d.ts +0 -12
- package/library/init.d.ts.map +0 -1
- package/library/init.js +0 -100
- package/library/plan.d.ts +0 -10
- package/library/plan.d.ts.map +0 -1
- package/library/plan.js +0 -85
- package/library/reporter.d.ts +0 -14
- package/library/reporter.d.ts.map +0 -1
- package/library/reporter.js +0 -156
- package/library/schema.d.ts +0 -133
- package/library/schema.d.ts.map +0 -1
- package/library/schema.js +0 -128
- package/library/types.d.ts +0 -190
- package/library/types.d.ts.map +0 -1
- package/library/types.js +0 -4
- package/library/version.d.ts +0 -10
- package/library/version.d.ts.map +0 -1
- package/library/version.js +0 -31
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,33 @@ 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
|
+
## Unreleased
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- Added Bun-native multi-target binary compilation for Linux, macOS, and Windows release assets.
|
|
13
|
+
- Added direct native binary installers for POSIX shells and PowerShell.
|
|
14
|
+
- Added package-manager install helper that places the matching native binary at `bin/mirror`.
|
|
15
|
+
|
|
16
|
+
### Changed
|
|
17
|
+
|
|
18
|
+
- Converted Mirror to a CLI-only package and removed the public TypeScript API contract from package metadata and documentation.
|
|
19
|
+
- Replaced Node.js runtime imports with Bun-native file, TOML, process, shell, and binary build APIs.
|
|
20
|
+
- Replaced `citty` with Mirror's internal CLI router and replaced `smol-toml` with Bun's native `Bun.TOML` parser, while keeping `semver` for semantic version calculations.
|
|
21
|
+
- Changed npm packaging to ship a small Bun launcher and postinstall downloader instead of bundling every platform binary into the package tarball.
|
|
22
|
+
|
|
23
|
+
## [3.2.1] - 2026-06-09
|
|
24
|
+
|
|
25
|
+
### Added
|
|
26
|
+
|
|
27
|
+
- Added lifecycle hooks with before/after hook points around planning, applying, writing, committing, tagging, pushing, and the full execution flow.
|
|
28
|
+
|
|
29
|
+
### Changed
|
|
30
|
+
|
|
31
|
+
- Wrapped the generated Mirror `AGENTS.md` guidance in `BEGIN/END GUIHO MIRROR` markers that tell agents not to edit the Mirror-managed block.
|
|
32
|
+
- Made Mirror AGENTS guidance detection whitespace-insensitive so markdown formatting that only adds or removes blank lines does not duplicate the section.
|
|
33
|
+
- Updated hook tests to use the active Bun runtime instead of requiring a separate `node` binary on `PATH`.
|
|
34
|
+
|
|
8
35
|
## [3.2.0] - 2026-06-07
|
|
9
36
|
|
|
10
37
|
### Added
|
package/DOCS.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# GUIHO Mirror Documentation
|
|
2
2
|
|
|
3
|
-
GUIHO Mirror is a deterministic CLI
|
|
3
|
+
GUIHO Mirror is a deterministic CLI 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
4
|
|
|
5
5
|
```text
|
|
6
6
|
source -> version engine -> plan -> outputs
|
|
@@ -11,15 +11,16 @@ Mirror is designed for human operators, CI jobs, and AI coding agents that need
|
|
|
11
11
|
## Package Overview
|
|
12
12
|
|
|
13
13
|
- Package name: `@guiho/mirror`
|
|
14
|
-
- Runtime target:
|
|
14
|
+
- Runtime target: native Bun-compiled CLI binary
|
|
15
15
|
- Development runtime: Bun
|
|
16
|
-
- Package type:
|
|
17
|
-
- Library entrypoint: `source/guiho-mirror.ts`
|
|
16
|
+
- Package type: CLI-only
|
|
18
17
|
- CLI entrypoint: `source/guiho-mirror-bin.ts`
|
|
19
|
-
-
|
|
20
|
-
- Standalone
|
|
18
|
+
- Package-manager launcher path: `scripts/mirror-bin.ts`
|
|
19
|
+
- Standalone release assets: `bin/guiho-mirror-<os>-<arch>` or `bin/guiho-mirror-<os>-<arch>.exe`
|
|
21
20
|
|
|
22
|
-
The public package exposes a CLI named `mirror
|
|
21
|
+
The public package exposes a CLI named `mirror`. It does not maintain a public TypeScript API contract.
|
|
22
|
+
|
|
23
|
+
Mirror's implementation is Bun-native where Bun provides the runtime primitive. Runtime code uses Bun APIs for file IO, TOML parsing, shell/process execution, and binary compilation. Mirror uses an internal CLI router and keeps `semver` for semantic version calculations; do not add Node.js runtime imports or parser dependencies when Bun provides the capability.
|
|
23
24
|
|
|
24
25
|
## Core Model
|
|
25
26
|
|
|
@@ -80,19 +81,28 @@ Prerelease identifiers come from `[version].prerelease_id` or the `--preid` CLI
|
|
|
80
81
|
|
|
81
82
|
## Installation
|
|
82
83
|
|
|
83
|
-
Install
|
|
84
|
+
Install the native binary directly on macOS or Linux:
|
|
84
85
|
|
|
85
86
|
```bash
|
|
86
|
-
|
|
87
|
+
curl -fsSL https://raw.githubusercontent.com/CGuiho/mirror/main/mirror/install.sh | sh
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
Install the native binary directly on Windows:
|
|
91
|
+
|
|
92
|
+
```powershell
|
|
93
|
+
irm https://raw.githubusercontent.com/CGuiho/mirror/main/mirror/install.ps1 | iex
|
|
87
94
|
```
|
|
88
95
|
|
|
89
|
-
|
|
96
|
+
Package-manager installs are also supported:
|
|
90
97
|
|
|
91
98
|
```bash
|
|
99
|
+
bun add -d @guiho/mirror
|
|
92
100
|
npm install -D @guiho/mirror
|
|
101
|
+
pnpm add -D @guiho/mirror
|
|
102
|
+
yarn add -D @guiho/mirror
|
|
93
103
|
```
|
|
94
104
|
|
|
95
|
-
|
|
105
|
+
Package-manager installs use a small Bun launcher plus install-time tooling that downloads the matching native binary into `vendor/mirror`. Direct installers are the no-runtime path; package-manager installs require Bun for the launcher and postinstall helper.
|
|
96
106
|
|
|
97
107
|
## Quick Start
|
|
98
108
|
|
|
@@ -204,7 +214,7 @@ mirror agents instructions
|
|
|
204
214
|
|
|
205
215
|
- `install local`: Writes `.agents/skills/guiho-as-mirror/SKILL.md` in the project.
|
|
206
216
|
- `install global`: Writes `~/.agents/skills/guiho-as-mirror/SKILL.md`.
|
|
207
|
-
- `instructions`: Creates or updates `AGENTS.md` with the GUIHO Mirror semantic versioning section.
|
|
217
|
+
- `instructions`: Creates or updates `AGENTS.md` with the protected GUIHO Mirror semantic versioning section.
|
|
208
218
|
|
|
209
219
|
Global skill installation uses the user home directory. Tests and automation can override that home root with `MIRROR_AGENT_HOME`.
|
|
210
220
|
|
|
@@ -340,7 +350,7 @@ Automation is controlled by `[agents]`.
|
|
|
340
350
|
- Disable changelog edits by agents with `write_changelog = false`.
|
|
341
351
|
- Direct agents to the correct changelog with `changelog_path = "path/to/CHANGELOG.md"`.
|
|
342
352
|
|
|
343
|
-
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.
|
|
353
|
+
The generated AGENTS section is wrapped in `<!-- BEGIN GUIHO MIRROR - DO NOT EDIT THIS SECTION -->` and `<!-- END GUIHO MIRROR -->` markers so agents know the block is Mirror-managed. It instructs agents to invoke `guiho-as-mirror` for versioning work, inspect `mirror.config.toml`, respect `write_changelog`, and use `changelog_path` for changelog edits. Mirror detects the existing block with whitespace-insensitive matching so markdown formatting that only adds or removes blank lines does not duplicate the section. Use `mirror agents install local` only when a project-local skill copy is desired explicitly.
|
|
344
354
|
|
|
345
355
|
## Release Safety Rules
|
|
346
356
|
|
|
@@ -355,85 +365,148 @@ Mirror intentionally separates planning from mutation.
|
|
|
355
365
|
|
|
356
366
|
`mirror version apply` refuses to mutate unless `--yes` is passed, unless `--dry-run` is used.
|
|
357
367
|
|
|
358
|
-
##
|
|
368
|
+
## Lifecycle Hooks
|
|
359
369
|
|
|
360
|
-
|
|
370
|
+
Mirror supports lifecycle hooks that run shell commands at defined points during `mirror version apply`. Hooks are configured in the `[hooks]` section of `mirror.config.toml`.
|
|
361
371
|
|
|
362
|
-
|
|
363
|
-
2. Run `mirror config show` and inspect `allow_dirty`, `write_changelog`, and `changelog_path`.
|
|
364
|
-
3. Check `git status --short` when dirty worktrees are not allowed.
|
|
365
|
-
4. Run the project typechecker.
|
|
366
|
-
5. Run the project test suite.
|
|
367
|
-
6. Run `mirror version plan <target>`.
|
|
368
|
-
7. Update release documentation when needed.
|
|
369
|
-
8. Update `[agents].changelog_path` only when `write_changelog` is not false and the file exists or is part of the release process.
|
|
370
|
-
9. Commit release-preparation documentation before applying the version bump.
|
|
371
|
-
10. Run `mirror version apply <target> --yes`, adding `--commit` when file outputs and Git tag output are combined.
|
|
372
|
+
### Lifecycle Tree
|
|
372
373
|
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
374
|
+
```
|
|
375
|
+
before:everything # Runs once, before anything else
|
|
376
|
+
│
|
|
377
|
+
├─ before:plan # Runs before buildVersionPlan()
|
|
378
|
+
│ buildVersionPlan() # Plan construction (read-only)
|
|
379
|
+
│ after:plan # Runs after plan is built
|
|
380
|
+
│
|
|
381
|
+
├─ before:apply # Runs before executeVersionPlan()
|
|
382
|
+
│ │
|
|
383
|
+
│ ├─ before:write # Runs before each file-write batch
|
|
384
|
+
│ │ write-file(s) # Mutate package.json / jsr.json
|
|
385
|
+
│ │ after:write # Runs after all file writes
|
|
386
|
+
│ │
|
|
387
|
+
│ ├─ before:commit # Runs before git commit
|
|
388
|
+
│ │ git-commit # git add + git commit
|
|
389
|
+
│ │ after:commit # Runs after git commit
|
|
390
|
+
│ │
|
|
391
|
+
│ ├─ before:tag # Runs before git tag
|
|
392
|
+
│ │ git-tag # git tag -m "..."
|
|
393
|
+
│ │ after:tag # Runs after git tag
|
|
394
|
+
│ │
|
|
395
|
+
│ ├─ before:push # Runs before git push
|
|
396
|
+
│ │ git-push # git push + git push --tags
|
|
397
|
+
│ │ after:push # Runs after git push
|
|
398
|
+
│ │
|
|
399
|
+
│ after:apply # Runs after executeVersionPlan() completes (always runs)
|
|
400
|
+
│
|
|
401
|
+
after:everything # Runs once, after everything else (always runs)
|
|
402
|
+
```
|
|
378
403
|
|
|
379
|
-
|
|
404
|
+
### Hook Configuration
|
|
380
405
|
|
|
381
|
-
|
|
406
|
+
```toml
|
|
407
|
+
[hooks]
|
|
408
|
+
before_everything = "npm run typecheck"
|
|
409
|
+
after_everything = "echo 'Release complete!'"
|
|
382
410
|
|
|
383
|
-
|
|
411
|
+
before_plan = ["npm run lint", "npm run typecheck"]
|
|
412
|
+
after_plan = "echo 'Plan is ready'"
|
|
384
413
|
|
|
385
|
-
|
|
386
|
-
|
|
414
|
+
before_apply = "npm run build"
|
|
415
|
+
after_apply = "node scripts/notify-release.js"
|
|
387
416
|
|
|
388
|
-
|
|
417
|
+
before_write = "echo 'Writing version files...'"
|
|
418
|
+
after_write = "echo 'Files written'"
|
|
389
419
|
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
console.log(plan.actions)
|
|
420
|
+
before_commit = ["npm run format", "echo 'Committing...'"]
|
|
421
|
+
after_commit = "echo 'Committed'"
|
|
393
422
|
|
|
394
|
-
|
|
423
|
+
before_tag = "echo 'Tagging release...'"
|
|
424
|
+
after_tag = "echo 'Tagged'"
|
|
395
425
|
|
|
396
|
-
|
|
426
|
+
before_push = "echo 'Pushing...'"
|
|
427
|
+
after_push = "echo 'Pushed'"
|
|
397
428
|
```
|
|
398
429
|
|
|
399
|
-
|
|
430
|
+
- Each hook key maps to a string (single command) or array of strings (multiple commands run sequentially).
|
|
431
|
+
- Hook names use underscores (`before_everything`) in TOML, which normalizes to colon form (`before:everything`) internally.
|
|
432
|
+
- Hook commands run in the project root directory through the default platform shell.
|
|
433
|
+
- Action-level hooks (`before:write`, `before:commit`, `before:tag`, `before:push` and their `after:` variants) fire only when the corresponding action is part of the plan.
|
|
434
|
+
- Hooks are skipped during `--dry-run`.
|
|
435
|
+
|
|
436
|
+
### Hook Error Handling
|
|
437
|
+
|
|
438
|
+
- When a hook exits with a non-zero code, Mirror stops the pipeline and reports the failure.
|
|
439
|
+
- `after:apply` and `after:everything` always run, even when a prior hook or action failed. This ensures cleanup and notification hooks fire reliably.
|
|
440
|
+
|
|
441
|
+
### Hook Environment Variables
|
|
442
|
+
|
|
443
|
+
Every hook receives `MIRROR_*` environment variables with release context:
|
|
444
|
+
|
|
445
|
+
| Variable | Scope | Description |
|
|
446
|
+
|------------------------|--------------|-------------------------------------------------------|
|
|
447
|
+
| `MIRROR_CWD` | Always | Project root directory |
|
|
448
|
+
| `MIRROR_CONFIG_PATH` | Always | Path to resolved `mirror.config.toml` |
|
|
449
|
+
| `MIRROR_SOURCE` | Always | Version source adapter |
|
|
450
|
+
| `MIRROR_OUTPUT` | Always | Comma-separated output adapters |
|
|
451
|
+
| `MIRROR_TARGET` | Always | The release target argument |
|
|
452
|
+
| `MIRROR_CURRENT` | Plan+ | Current version string |
|
|
453
|
+
| `MIRROR_NEXT` | Plan+ | Next version string |
|
|
454
|
+
| `MIRROR_PROJECT_NAME` | Plan+ | Resolved project name |
|
|
455
|
+
| `MIRROR_GIT_TAG` | Plan+ | Rendered git tag (if git output) |
|
|
456
|
+
| `MIRROR_FILE_PATHS` | Plan+ | Comma-separated file output paths |
|
|
457
|
+
| `MIRROR_COMMIT_ENABLED`| Plan+ | `true`/`false` |
|
|
458
|
+
| `MIRROR_PUSH_ENABLED` | Plan+ | `true`/`false` |
|
|
459
|
+
| `MIRROR_FILE_PATH` | Write | Path being written to |
|
|
460
|
+
| `MIRROR_FILE_CURRENT` | Write | Current version in the file |
|
|
461
|
+
| `MIRROR_FILE_NEXT` | Write | Next version being written |
|
|
462
|
+
| `MIRROR_COMMIT_MSG` | Commit | Commit message |
|
|
463
|
+
| `MIRROR_COMMIT_PATHS` | Commit | Space-separated paths being committed |
|
|
464
|
+
| `MIRROR_TAG` | Tag | Git tag being created |
|
|
465
|
+
| `MIRROR_INCLUDE_COMMIT`| Push | `true`/`false` |
|
|
466
|
+
| `MIRROR_INCLUDE_TAGS` | Push | `true`/`false` |
|
|
467
|
+
| `MIRROR_APPLIED` | Results | `true`/`false` (whether execution actually applied) |
|
|
468
|
+
| `MIRROR_DRY_RUN` | Results | `true`/`false` |
|
|
469
|
+
|
|
470
|
+
"Plan+" means the variable is available starting from `before:plan` and all later hooks. "Write", "Commit", "Tag", and "Push" mean the variable is available at the corresponding action-level hooks. "Results" means `after:apply` and `after:everything`.
|
|
400
471
|
|
|
401
|
-
|
|
402
|
-
import { loadMirrorConfig, readCurrentVersion } from '@guiho/mirror'
|
|
472
|
+
## Recommended Agent Release Workflow
|
|
403
473
|
|
|
404
|
-
|
|
405
|
-
const version = await readCurrentVersion(config)
|
|
406
|
-
```
|
|
474
|
+
When an AI coding agent prepares a Mirror-managed release, it should follow this sequence.
|
|
407
475
|
|
|
408
|
-
|
|
476
|
+
1. Confirm the target and project root.
|
|
477
|
+
2. Run `mirror config show` and inspect `allow_dirty`, `write_changelog`, and `changelog_path`.
|
|
478
|
+
3. Check `git status --short` when dirty worktrees are not allowed.
|
|
479
|
+
4. Run the project typechecker.
|
|
480
|
+
5. Run the project test suite.
|
|
481
|
+
6. Run `mirror version plan <target>`.
|
|
482
|
+
7. Update release documentation when needed.
|
|
483
|
+
8. Update `[agents].changelog_path` only when `write_changelog` is not false and the file exists or is part of the release process.
|
|
484
|
+
9. Commit release-preparation documentation before applying the version bump.
|
|
485
|
+
10. Run `mirror version apply <target> --yes`, adding `--commit` when file outputs and Git tag output are combined.
|
|
409
486
|
|
|
410
|
-
|
|
411
|
-
import {
|
|
412
|
-
ensureMirrorAgentsInstructions,
|
|
413
|
-
installMirrorSkill,
|
|
414
|
-
runMirrorAgentAutomation,
|
|
415
|
-
} from '@guiho/mirror'
|
|
487
|
+
## Documentation Requirement Before Publishing
|
|
416
488
|
|
|
417
|
-
|
|
418
|
-
await installMirrorSkill('local', { cwd: process.cwd() })
|
|
419
|
-
await runMirrorAgentAutomation({ cwd: process.cwd() })
|
|
420
|
-
```
|
|
489
|
+
Every behavior change must be documented before publishing a new version. This includes changes to CLI commands, configuration fields, release behavior, Git behavior, package contents, agent automation, tests that describe public behavior, and operational workflows.
|
|
421
490
|
|
|
422
|
-
|
|
491
|
+
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.
|
|
423
492
|
|
|
424
493
|
## Internal Source Map
|
|
425
494
|
|
|
426
|
-
- `source/guiho-mirror.ts`: public
|
|
495
|
+
- `source/guiho-mirror.ts`: internal source aggregation for tests and CLI internals, not a public API contract.
|
|
427
496
|
- `source/guiho-mirror-bin.ts`: CLI binary entrypoint.
|
|
428
|
-
- `source/cli.ts`:
|
|
429
|
-
- `source/config.ts`: TOML discovery, schema validation, defaulting, init config generation, init reconciliation, and override merge.
|
|
497
|
+
- `source/cli.ts`: internal command router, CLI argument mapping, and process-facing error handling.
|
|
498
|
+
- `source/config.ts`: Bun TOML discovery, schema validation, defaulting, init config generation, init reconciliation, and override merge.
|
|
430
499
|
- `source/init.ts`: init answer resolution, interactive prompts (TTY-only), and defaults.
|
|
431
500
|
- `source/schema.ts`: JSON Schema for `mirror.config.toml` and the `#:schema` reference.
|
|
432
501
|
- `source/types.ts`: public and internal TypeScript types.
|
|
433
|
-
- `source/version.ts`: semver target validation and next-version resolution.
|
|
502
|
+
- `source/version.ts`: `semver` target validation and next-version resolution.
|
|
434
503
|
- `source/adapters.ts`: package, JSR, and Git read/write primitives.
|
|
435
504
|
- `source/plan.ts`: validation and read-only release plan construction.
|
|
436
505
|
- `source/executor.ts`: mutation layer for file writes, Git commits, tags, and pushes.
|
|
506
|
+
- `source/hooks.ts`: lifecycle hook configuration, execution, and environment variable construction.
|
|
507
|
+
- `source/path.ts`: small path helpers used instead of Node.js `path` imports.
|
|
508
|
+
- `source/runtime.ts`: Bun-native file, process, and shell helpers.
|
|
509
|
+
- `source/build-binaries.ts`: multi-target Bun binary compilation script.
|
|
437
510
|
- `source/reporter.ts`: text and JSON report formatting.
|
|
438
511
|
- `source/agents.ts`: agent skill installation and AGENTS.md guidance automation.
|
|
439
512
|
- `source/errors.ts`: user-facing errors with stable exit codes.
|
|
@@ -454,9 +527,8 @@ bun run binary
|
|
|
454
527
|
|
|
455
528
|
Generated outputs are ignored and should not be hand-edited.
|
|
456
529
|
|
|
457
|
-
- `
|
|
458
|
-
- `
|
|
459
|
-
- `bundle/`: optional bundled output.
|
|
530
|
+
- `bin/`: ignored local compiled binary output and release asset staging.
|
|
531
|
+
- `vendor/`: package-manager postinstall destination for the selected native binary.
|
|
460
532
|
|
|
461
533
|
There is no lint or formatter config. Existing source style is strict TypeScript, ESM imports, single quotes, and no semicolons.
|
|
462
534
|
|
|
@@ -491,19 +563,13 @@ bun test source/guiho-mirror.spec.ts
|
|
|
491
563
|
|
|
492
564
|
## Build and Binary
|
|
493
565
|
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
```bash
|
|
497
|
-
bun run build
|
|
498
|
-
```
|
|
499
|
-
|
|
500
|
-
Compile the standalone binary:
|
|
566
|
+
Compile native binaries:
|
|
501
567
|
|
|
502
568
|
```bash
|
|
503
569
|
bun run binary
|
|
504
570
|
```
|
|
505
571
|
|
|
506
|
-
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.
|
|
572
|
+
The binary build writes `bin/mirror` for local validation and platform release assets for Linux, macOS, and Windows x64/arm64 targets where Bun compilation supports the target. Do not publish the full `bin/` matrix inside the npm package; upload those files as GitHub release assets and let installers download the matching one. 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.
|
|
507
573
|
|
|
508
574
|
## Publishing Checklist
|
|
509
575
|
|
|
@@ -514,8 +580,8 @@ Before publishing a new version:
|
|
|
514
580
|
3. Confirm other relevant docs are updated, including `README.md`, `AGENTS.md`, and the configured changelog path when applicable.
|
|
515
581
|
4. Run `bun run typecheck`.
|
|
516
582
|
5. Run `bun test`.
|
|
517
|
-
6. Run `bun run
|
|
518
|
-
7.
|
|
583
|
+
6. Run `bun run binary`.
|
|
584
|
+
7. Upload the generated platform binaries as release assets when publishing a binary release.
|
|
519
585
|
8. Run `mirror version plan <target>`.
|
|
520
586
|
9. Commit release documentation updates before applying the version bump.
|
|
521
587
|
10. Run `mirror version apply <target> --yes` with the required commit or push flags.
|
package/README.md
CHANGED
|
@@ -2,13 +2,13 @@
|
|
|
2
2
|
|
|
3
3
|
**Open source project versioning for Bun, npm, JSR, and Git.**
|
|
4
4
|
|
|
5
|
-
Mirror is a powerful, deterministic CLI
|
|
5
|
+
Mirror is a powerful, deterministic CLI for semantic project versioning. It reads a single version source, calculates the next semantic version, builds a transparent release plan, and safely applies it to configured outputs like `package.json`, `jsr.json`, and Git tags.
|
|
6
6
|
|
|
7
7
|
```text
|
|
8
8
|
source -> version engine -> plan -> outputs
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
Mirror
|
|
11
|
+
Mirror ships as a **native Bun-compiled CLI binary**. Direct installers run the native binary without requiring Node.js or Bun at runtime. Package-manager installs use a small Bun launcher and postinstall helper. Git is required **only** for Git-based workflows (`source: "git"`, `output: ["git"]`, or commit/tag/push operations).
|
|
12
12
|
|
|
13
13
|
---
|
|
14
14
|
|
|
@@ -22,6 +22,18 @@ npm install -D @guiho/mirror
|
|
|
22
22
|
bun add -d @guiho/mirror
|
|
23
23
|
```
|
|
24
24
|
|
|
25
|
+
Direct native binary install on macOS/Linux:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
curl -fsSL https://raw.githubusercontent.com/CGuiho/mirror/main/mirror/install.sh | sh
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Direct native binary install on Windows:
|
|
32
|
+
|
|
33
|
+
```powershell
|
|
34
|
+
irm https://raw.githubusercontent.com/CGuiho/mirror/main/mirror/install.ps1 | iex
|
|
35
|
+
```
|
|
36
|
+
|
|
25
37
|
### Initializing
|
|
26
38
|
|
|
27
39
|
Create a default configuration file for your project type:
|
|
@@ -155,47 +167,9 @@ When combining file outputs (`package.json`, `jsr.json`) with Git tag output, Mi
|
|
|
155
167
|
|
|
156
168
|
---
|
|
157
169
|
|
|
158
|
-
## 💻 API Reference
|
|
159
|
-
|
|
160
|
-
Mirror exposes a fully-typed TypeScript API for custom automation scripts.
|
|
161
|
-
|
|
162
|
-
### Core Lifecycle Methods
|
|
163
|
-
|
|
164
|
-
```ts
|
|
165
|
-
import { buildVersionPlan, applyVersionPlan, executeVersionPlan } from '@guiho/mirror'
|
|
166
|
-
|
|
167
|
-
// 1. Build a read-only plan for a patch release
|
|
168
|
-
const plan = await buildVersionPlan('patch', { cwd: process.cwd() })
|
|
169
|
-
|
|
170
|
-
// 2. Inspect the plan
|
|
171
|
-
console.log(plan.currentVersion) // "1.0.0"
|
|
172
|
-
console.log(plan.nextVersion) // "1.0.1"
|
|
173
|
-
console.log(plan.actions) // Array of actions (write-file, git-commit, etc.)
|
|
174
|
-
|
|
175
|
-
// 3. Execute the plan manually
|
|
176
|
-
const result = await executeVersionPlan(plan, { dryRun: false, yes: true })
|
|
177
|
-
|
|
178
|
-
// OR: Build and apply in one step
|
|
179
|
-
await applyVersionPlan('minor', { cwd: process.cwd(), yes: true })
|
|
180
|
-
```
|
|
181
|
-
|
|
182
|
-
### Reading State
|
|
183
|
-
|
|
184
|
-
```ts
|
|
185
|
-
import { loadMirrorConfig, readCurrentVersion } from '@guiho/mirror'
|
|
186
|
-
|
|
187
|
-
// Load resolved configuration
|
|
188
|
-
const config = await loadMirrorConfig({ cwd: process.cwd() })
|
|
189
|
-
|
|
190
|
-
// Read the current version using the configured source
|
|
191
|
-
const version = await readCurrentVersion(config)
|
|
192
|
-
```
|
|
193
|
-
|
|
194
|
-
---
|
|
195
|
-
|
|
196
170
|
## 🛠️ Development
|
|
197
171
|
|
|
198
|
-
Development tasks require Bun
|
|
172
|
+
Development tasks require Bun. Run from the `mirror/` directory:
|
|
199
173
|
|
|
200
174
|
```bash
|
|
201
175
|
cd mirror
|
package/jsr.json
CHANGED
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@guiho/mirror",
|
|
3
|
-
"version": "3.
|
|
4
|
-
"exports": "./source/guiho-mirror.ts",
|
|
3
|
+
"version": "3.3.0-alpha.1",
|
|
4
|
+
"exports": "./source/guiho-mirror-bin.ts",
|
|
5
5
|
"publish": {
|
|
6
6
|
"include": [
|
|
7
7
|
"source/**/*.ts",
|
|
8
|
+
"install.sh",
|
|
9
|
+
"install.ps1",
|
|
8
10
|
"README.md",
|
|
9
11
|
"LICENSE.md"
|
|
10
12
|
]
|
package/package.json
CHANGED
|
@@ -1,29 +1,22 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@guiho/mirror",
|
|
3
3
|
"description": "Open source project versioning for Bun, npm, JSR, and Git.",
|
|
4
|
-
"version": "3.
|
|
4
|
+
"version": "3.3.0-alpha.1",
|
|
5
5
|
"type": "module",
|
|
6
|
-
"main": "./library/guiho-mirror.js",
|
|
7
|
-
"types": "./library/guiho-mirror.d.ts",
|
|
8
|
-
"exports": {
|
|
9
|
-
".": {
|
|
10
|
-
"types": "./library/guiho-mirror.d.ts",
|
|
11
|
-
"import": "./library/guiho-mirror.js"
|
|
12
|
-
}
|
|
13
|
-
},
|
|
14
6
|
"bin": {
|
|
15
|
-
"mirror": "./
|
|
7
|
+
"mirror": "./scripts/mirror-bin.ts"
|
|
16
8
|
},
|
|
17
9
|
"files": [
|
|
18
10
|
"README.md",
|
|
19
|
-
"
|
|
11
|
+
"scripts/",
|
|
20
12
|
"skills/",
|
|
21
13
|
"schema/",
|
|
22
|
-
"docs/",
|
|
23
14
|
"jsr.json",
|
|
24
15
|
"CHANGELOG.md",
|
|
25
16
|
"LICENSE.md",
|
|
26
|
-
"DOCS.md"
|
|
17
|
+
"DOCS.md",
|
|
18
|
+
"install.sh",
|
|
19
|
+
"install.ps1"
|
|
27
20
|
],
|
|
28
21
|
"keywords": [
|
|
29
22
|
"bun",
|
|
@@ -44,10 +37,11 @@
|
|
|
44
37
|
"access": "public"
|
|
45
38
|
},
|
|
46
39
|
"scripts": {
|
|
40
|
+
"postinstall": "bun run scripts/install-package.ts",
|
|
41
|
+
"prepack": "bun run binary",
|
|
47
42
|
"dev": "bun run --watch source/guiho-mirror-bin.ts",
|
|
48
|
-
"build": "
|
|
49
|
-
"binary": "bun
|
|
50
|
-
"bundle": "rm -rf bundle && bun build source/guiho-mirror-bin.ts --outdir bundle --target node --sourcemap=linked",
|
|
43
|
+
"build": "bun run binary",
|
|
44
|
+
"binary": "bun run source/build-binaries.ts",
|
|
51
45
|
"typecheck": "tsc -p . --noEmit",
|
|
52
46
|
"clean": "rm -rf .temp",
|
|
53
47
|
"clean-build": "rm -rf build library bundle bin",
|
|
@@ -69,12 +63,9 @@
|
|
|
69
63
|
"url": "https://github.com/CGuiho/mirror/issues"
|
|
70
64
|
},
|
|
71
65
|
"dependencies": {
|
|
72
|
-
"
|
|
73
|
-
"semver": "^7.8.1",
|
|
74
|
-
"smol-toml": "^1.6.1"
|
|
66
|
+
"semver": "^7.8.1"
|
|
75
67
|
},
|
|
76
68
|
"devDependencies": {
|
|
77
|
-
"@guiho/mirror": "^3.0.0",
|
|
78
69
|
"@types/bun": "1.3.14",
|
|
79
70
|
"@types/semver": "^7.7.1",
|
|
80
71
|
"typescript": "5.8.2"
|