@guiho/mirror 3.2.1 → 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 +15 -0
- package/DOCS.md +35 -74
- package/README.md +15 -41
- package/jsr.json +4 -2
- package/package.json +11 -20
- 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 -29
- package/library/agents.d.ts.map +0 -1
- package/library/agents.js +0 -212
- package/library/cli.d.ts +0 -29
- package/library/cli.d.ts.map +0 -1
- package/library/cli.js +0 -416
- package/library/config.d.ts +0 -18
- package/library/config.d.ts.map +0 -1
- package/library/config.js +0 -280
- 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 -48
- 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 -18
- package/library/guiho-mirror.d.ts.map +0 -1
- package/library/guiho-mirror.js +0 -16
- package/library/hooks.d.ts +0 -14
- package/library/hooks.d.ts.map +0 -1
- package/library/hooks.js +0 -122
- 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 -15
- package/library/reporter.d.ts.map +0 -1
- package/library/reporter.js +0 -182
- package/library/schema.d.ts +0 -164
- package/library/schema.d.ts.map +0 -1
- package/library/schema.js +0 -152
- package/library/types.d.ts +0 -205
- 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,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
|
+
## 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
|
+
|
|
8
23
|
## [3.2.1] - 2026-06-09
|
|
9
24
|
|
|
10
25
|
### 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
|
|
|
@@ -476,69 +486,27 @@ When an AI coding agent prepares a Mirror-managed release, it should follow this
|
|
|
476
486
|
|
|
477
487
|
## Documentation Requirement Before Publishing
|
|
478
488
|
|
|
479
|
-
Every behavior change must be documented before publishing a new version. This includes changes to CLI commands, configuration fields,
|
|
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.
|
|
480
490
|
|
|
481
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.
|
|
482
492
|
|
|
483
|
-
## TypeScript API
|
|
484
|
-
|
|
485
|
-
Mirror exports types and functions from `source/guiho-mirror.ts`.
|
|
486
|
-
|
|
487
|
-
Common release-plan API:
|
|
488
|
-
|
|
489
|
-
```ts
|
|
490
|
-
import { applyVersionPlan, buildVersionPlan, executeVersionPlan } from '@guiho/mirror'
|
|
491
|
-
|
|
492
|
-
const plan = await buildVersionPlan('patch', { cwd: process.cwd() })
|
|
493
|
-
|
|
494
|
-
console.log(plan.currentVersion)
|
|
495
|
-
console.log(plan.nextVersion)
|
|
496
|
-
console.log(plan.actions)
|
|
497
|
-
|
|
498
|
-
await executeVersionPlan(plan, { yes: true })
|
|
499
|
-
|
|
500
|
-
await applyVersionPlan('minor', { cwd: process.cwd(), yes: true })
|
|
501
|
-
```
|
|
502
|
-
|
|
503
|
-
Configuration and read API:
|
|
504
|
-
|
|
505
|
-
```ts
|
|
506
|
-
import { loadMirrorConfig, readCurrentVersion } from '@guiho/mirror'
|
|
507
|
-
|
|
508
|
-
const config = await loadMirrorConfig({ cwd: process.cwd() })
|
|
509
|
-
const version = await readCurrentVersion(config)
|
|
510
|
-
```
|
|
511
|
-
|
|
512
|
-
Agent automation API:
|
|
513
|
-
|
|
514
|
-
```ts
|
|
515
|
-
import {
|
|
516
|
-
ensureMirrorAgentsInstructions,
|
|
517
|
-
installMirrorSkill,
|
|
518
|
-
runMirrorAgentAutomation,
|
|
519
|
-
} from '@guiho/mirror'
|
|
520
|
-
|
|
521
|
-
await ensureMirrorAgentsInstructions(process.cwd(), true)
|
|
522
|
-
await installMirrorSkill('local', { cwd: process.cwd() })
|
|
523
|
-
await runMirrorAgentAutomation({ cwd: process.cwd() })
|
|
524
|
-
```
|
|
525
|
-
|
|
526
|
-
The API uses the same configuration discovery and safety rules as the CLI.
|
|
527
|
-
|
|
528
493
|
## Internal Source Map
|
|
529
494
|
|
|
530
|
-
- `source/guiho-mirror.ts`: public
|
|
495
|
+
- `source/guiho-mirror.ts`: internal source aggregation for tests and CLI internals, not a public API contract.
|
|
531
496
|
- `source/guiho-mirror-bin.ts`: CLI binary entrypoint.
|
|
532
|
-
- `source/cli.ts`:
|
|
533
|
-
- `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.
|
|
534
499
|
- `source/init.ts`: init answer resolution, interactive prompts (TTY-only), and defaults.
|
|
535
500
|
- `source/schema.ts`: JSON Schema for `mirror.config.toml` and the `#:schema` reference.
|
|
536
501
|
- `source/types.ts`: public and internal TypeScript types.
|
|
537
|
-
- `source/version.ts`: semver target validation and next-version resolution.
|
|
502
|
+
- `source/version.ts`: `semver` target validation and next-version resolution.
|
|
538
503
|
- `source/adapters.ts`: package, JSR, and Git read/write primitives.
|
|
539
504
|
- `source/plan.ts`: validation and read-only release plan construction.
|
|
540
505
|
- `source/executor.ts`: mutation layer for file writes, Git commits, tags, and pushes.
|
|
541
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.
|
|
542
510
|
- `source/reporter.ts`: text and JSON report formatting.
|
|
543
511
|
- `source/agents.ts`: agent skill installation and AGENTS.md guidance automation.
|
|
544
512
|
- `source/errors.ts`: user-facing errors with stable exit codes.
|
|
@@ -559,9 +527,8 @@ bun run binary
|
|
|
559
527
|
|
|
560
528
|
Generated outputs are ignored and should not be hand-edited.
|
|
561
529
|
|
|
562
|
-
- `
|
|
563
|
-
- `
|
|
564
|
-
- `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.
|
|
565
532
|
|
|
566
533
|
There is no lint or formatter config. Existing source style is strict TypeScript, ESM imports, single quotes, and no semicolons.
|
|
567
534
|
|
|
@@ -596,19 +563,13 @@ bun test source/guiho-mirror.spec.ts
|
|
|
596
563
|
|
|
597
564
|
## Build and Binary
|
|
598
565
|
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
```bash
|
|
602
|
-
bun run build
|
|
603
|
-
```
|
|
604
|
-
|
|
605
|
-
Compile the standalone binary:
|
|
566
|
+
Compile native binaries:
|
|
606
567
|
|
|
607
568
|
```bash
|
|
608
569
|
bun run binary
|
|
609
570
|
```
|
|
610
571
|
|
|
611
|
-
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.
|
|
612
573
|
|
|
613
574
|
## Publishing Checklist
|
|
614
575
|
|
|
@@ -619,8 +580,8 @@ Before publishing a new version:
|
|
|
619
580
|
3. Confirm other relevant docs are updated, including `README.md`, `AGENTS.md`, and the configured changelog path when applicable.
|
|
620
581
|
4. Run `bun run typecheck`.
|
|
621
582
|
5. Run `bun test`.
|
|
622
|
-
6. Run `bun run
|
|
623
|
-
7.
|
|
583
|
+
6. Run `bun run binary`.
|
|
584
|
+
7. Upload the generated platform binaries as release assets when publishing a binary release.
|
|
624
585
|
8. Run `mirror version plan <target>`.
|
|
625
586
|
9. Commit release documentation updates before applying the version bump.
|
|
626
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"
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
#!/usr/bin/env bun
|
|
2
|
+
/**
|
|
3
|
+
* Package-manager install helper for GUIHO Mirror.
|
|
4
|
+
*
|
|
5
|
+
* This script uses Bun APIs only. It downloads the platform-native Mirror binary
|
|
6
|
+
* into `vendor/mirror`. Package-manager installs use the small Bun launcher in
|
|
7
|
+
* `scripts/mirror-bin.ts`; direct installers remain the no-Bun runtime path.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
type PackageJson = {
|
|
11
|
+
version?: string
|
|
12
|
+
repository?: string | { url?: string }
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
const packageJson = await Bun.file(new URL('../package.json', import.meta.url)).json() as PackageJson
|
|
16
|
+
const sourceEntrypoint = Bun.file(new URL('../source/guiho-mirror-bin.ts', import.meta.url))
|
|
17
|
+
|
|
18
|
+
if (await sourceEntrypoint.exists()) {
|
|
19
|
+
console.log('source checkout detected; skipping native binary download')
|
|
20
|
+
process.exit(0)
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
const version = process.env['MIRROR_VERSION'] ?? packageJson.version ?? 'latest'
|
|
24
|
+
const repo = process.env['MIRROR_REPO'] ?? 'CGuiho/mirror'
|
|
25
|
+
const asset = detectAsset()
|
|
26
|
+
const bundledAsset = Bun.file(new URL(`../bin/${asset}`, import.meta.url))
|
|
27
|
+
const destination = new URL('../vendor/mirror', import.meta.url)
|
|
28
|
+
|
|
29
|
+
if (await bundledAsset.exists()) {
|
|
30
|
+
await Bun.write(destination, bundledAsset)
|
|
31
|
+
console.log(`installed bundled GUIHO Mirror native binary: ${asset}`)
|
|
32
|
+
process.exit(0)
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
const tag = version === 'latest' ? 'latest' : `@guiho/mirror@${version}`
|
|
36
|
+
const url = tag === 'latest'
|
|
37
|
+
? `https://github.com/${repo}/releases/latest/download/${asset}`
|
|
38
|
+
: `https://github.com/${repo}/releases/download/${encodeURIComponent(tag)}/${asset}`
|
|
39
|
+
|
|
40
|
+
const response = await fetch(url)
|
|
41
|
+
|
|
42
|
+
if (!response.ok) {
|
|
43
|
+
console.error(`error: failed to download ${url}`)
|
|
44
|
+
console.error(`status: ${response.status} ${response.statusText}`)
|
|
45
|
+
process.exit(1)
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
await Bun.write(destination, response)
|
|
49
|
+
console.log(`installed GUIHO Mirror native binary: ${asset}`)
|
|
50
|
+
|
|
51
|
+
function detectAsset() {
|
|
52
|
+
const os = detectOs()
|
|
53
|
+
const arch = detectArch()
|
|
54
|
+
return `guiho-mirror-${os}-${arch}${os === 'windows' ? '.exe' : ''}`
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
function detectOs() {
|
|
58
|
+
if (process.platform === 'linux') return 'linux'
|
|
59
|
+
if (process.platform === 'darwin') return 'macos'
|
|
60
|
+
if (process.platform === 'win32') return 'windows'
|
|
61
|
+
console.error(`error: unsupported OS: ${process.platform}`)
|
|
62
|
+
process.exit(1)
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
function detectArch() {
|
|
66
|
+
if (process.arch === 'x64') return 'x64'
|
|
67
|
+
if (process.arch === 'arm64') return 'arm64'
|
|
68
|
+
console.error(`error: unsupported architecture: ${process.arch}`)
|
|
69
|
+
process.exit(1)
|
|
70
|
+
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
#!/usr/bin/env bun
|
|
2
|
+
/**
|
|
3
|
+
* Small package-manager launcher for the downloaded native Mirror binary.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
const binaryPath = new URL('../vendor/mirror', import.meta.url)
|
|
7
|
+
const binary = Bun.file(binaryPath)
|
|
8
|
+
|
|
9
|
+
if (!(await binary.exists())) {
|
|
10
|
+
console.error('error: GUIHO Mirror native binary is missing. Reinstall @guiho/mirror or run `bun run scripts/install-package.ts`.')
|
|
11
|
+
process.exit(1)
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
const proc = Bun.spawn([binaryPath.pathname, ...process.argv.slice(2)], {
|
|
15
|
+
stdin: 'inherit',
|
|
16
|
+
stdout: 'inherit',
|
|
17
|
+
stderr: 'inherit',
|
|
18
|
+
})
|
|
19
|
+
|
|
20
|
+
process.exit(await proc.exited)
|
|
@@ -5,7 +5,7 @@ description: Use this skill whenever the user asks to version, bump, release, ta
|
|
|
5
5
|
|
|
6
6
|
# GUIHO Mirror
|
|
7
7
|
|
|
8
|
-
GUIHO Mirror is a deterministic CLI
|
|
8
|
+
GUIHO Mirror is a deterministic CLI for semantic project versioning. It reads one version source, calculates the next semantic version, builds a transparent read-only plan, and applies the plan to configured outputs such as `package.json`, `jsr.json`, and Git tags.
|
|
9
9
|
|
|
10
10
|
```text
|
|
11
11
|
source -> version engine -> plan -> outputs
|
|
@@ -23,7 +23,7 @@ Choose the Mirror command in this order:
|
|
|
23
23
|
|
|
24
24
|
When unsure, run a cheap availability check (`bun @guiho/mirror --help`, `mirror --help`, or `bunx @guiho/mirror --help`) and then reuse the working command consistently. Run `mirror --help` or `mirror <command> --help` for command-specific details when needed.
|
|
25
25
|
|
|
26
|
-
Mirror
|
|
26
|
+
Mirror ships as a Bun-compiled native CLI binary. The installed `mirror` command should not require Node.js or Bun at runtime. Bun is required for Mirror project development and binary compilation. Git is required only for Git-based workflows: `source = "git"`, `output = ["git"]`, commits, tags, or pushes.
|
|
27
27
|
|
|
28
28
|
## Release Workflow
|
|
29
29
|
|
|
@@ -177,33 +177,6 @@ mirror version apply <target> --yes
|
|
|
177
177
|
|
|
178
178
|
Supported targets are `major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, `prerelease`, or an exact semantic version such as `2.0.0`.
|
|
179
179
|
|
|
180
|
-
## TypeScript API
|
|
181
|
-
|
|
182
|
-
When the user wants automation code rather than CLI usage, use the typed API:
|
|
183
|
-
|
|
184
|
-
```ts
|
|
185
|
-
import { applyVersionPlan, buildVersionPlan, executeVersionPlan } from '@guiho/mirror';
|
|
186
|
-
|
|
187
|
-
const plan = await buildVersionPlan('patch', { cwd: process.cwd() });
|
|
188
|
-
|
|
189
|
-
console.log(plan.currentVersion);
|
|
190
|
-
console.log(plan.nextVersion);
|
|
191
|
-
console.log(plan.actions);
|
|
192
|
-
|
|
193
|
-
await executeVersionPlan(plan, { dryRun: false, yes: true });
|
|
194
|
-
|
|
195
|
-
await applyVersionPlan('minor', { cwd: process.cwd(), yes: true });
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
For reading state:
|
|
199
|
-
|
|
200
|
-
```ts
|
|
201
|
-
import { loadMirrorConfig, readCurrentVersion } from '@guiho/mirror';
|
|
202
|
-
|
|
203
|
-
const config = await loadMirrorConfig({ cwd: process.cwd() });
|
|
204
|
-
const version = await readCurrentVersion(config);
|
|
205
|
-
```
|
|
206
|
-
|
|
207
180
|
## Mirror Project Development
|
|
208
181
|
|
|
209
182
|
When working inside the Mirror project repository itself, run development commands from the `mirror/` directory:
|
package/library/adapters.d.ts
DELETED
|
@@ -1,32 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
|
|
3
|
-
*/
|
|
4
|
-
import type { MirrorConfig, MirrorJsonObject } from './types.js';
|
|
5
|
-
export declare const ensureGitAvailable: () => Promise<void>;
|
|
6
|
-
export declare const supportedGitTagTemplates: readonly ["v{version}", "{name}@{version}", "{name}/v{version}"];
|
|
7
|
-
export declare const readPackageJson: (path: string) => Promise<MirrorJsonObject>;
|
|
8
|
-
export declare const readJsrJson: (path: string) => Promise<MirrorJsonObject>;
|
|
9
|
-
export declare const writeJsonObject: (path: string, object: MirrorJsonObject) => Promise<void>;
|
|
10
|
-
export declare const readPackageVersion: (config: MirrorConfig) => Promise<string>;
|
|
11
|
-
export declare const readJsrVersion: (config: MirrorConfig) => Promise<string>;
|
|
12
|
-
export declare const readPackageVersionFile: (path: string) => Promise<string>;
|
|
13
|
-
export declare const readJsrVersionFile: (path: string) => Promise<string>;
|
|
14
|
-
export declare const readPackageName: (config: MirrorConfig) => Promise<string>;
|
|
15
|
-
export declare const readJsrName: (config: MirrorConfig) => Promise<string>;
|
|
16
|
-
export declare const writePackageVersion: (config: MirrorConfig, nextVersion: string) => Promise<void>;
|
|
17
|
-
export declare const writeJsrVersion: (config: MirrorConfig, nextVersion: string) => Promise<void>;
|
|
18
|
-
export declare const writePackageVersionFile: (path: string, nextVersion: string) => Promise<void>;
|
|
19
|
-
export declare const writeJsrVersionFile: (path: string, nextVersion: string) => Promise<void>;
|
|
20
|
-
export declare const ensureAdapterFiles: (config: MirrorConfig) => Promise<void>;
|
|
21
|
-
export declare const resolveProjectName: (config: MirrorConfig) => Promise<string | undefined>;
|
|
22
|
-
export declare const readCurrentVersion: (config: MirrorConfig, projectName?: string) => Promise<string>;
|
|
23
|
-
export declare const readGitVersion: (config: MirrorConfig, projectName?: string) => Promise<string>;
|
|
24
|
-
export declare const renderGitTag: (template: string, version: string, projectName?: string) => string;
|
|
25
|
-
export declare const versionFromTag: (template: string, tag: string, projectName?: string) => string | undefined;
|
|
26
|
-
export declare const assertSupportedGitTagTemplate: (template: string) => void;
|
|
27
|
-
export declare const isGitRepository: (cwd: string) => Promise<boolean>;
|
|
28
|
-
export declare const isGitDirty: (cwd: string) => Promise<boolean>;
|
|
29
|
-
export declare const createGitCommit: (cwd: string, paths: string[], message: string) => Promise<void>;
|
|
30
|
-
export declare const createGitTag: (cwd: string, tag: string) => Promise<void>;
|
|
31
|
-
export declare const pushGitRefs: (cwd: string, includeCommit: boolean, includeTags: boolean) => Promise<void>;
|
|
32
|
-
//# sourceMappingURL=adapters.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
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,sBAAsB,GAAU,MAAM,MAAM,oBAA2C,CAAA;AACpG,eAAO,MAAM,kBAAkB,GAAU,MAAM,MAAM,oBAAuC,CAAA;AAC5F,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,uBAAuB,GAAU,MAAM,MAAM,EAAE,aAAa,MAAM,kBAAyD,CAAA;AACxI,eAAO,MAAM,mBAAmB,GAAU,MAAM,MAAM,EAAE,aAAa,MAAM,kBAAqD,CAAA;AAEhI,eAAO,MAAM,kBAAkB,GAAU,QAAQ,YAAY,kBAO5D,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"}
|