@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.
Files changed (56) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/DOCS.md +35 -74
  3. package/README.md +15 -41
  4. package/jsr.json +4 -2
  5. package/package.json +11 -20
  6. package/scripts/install-package.ts +70 -0
  7. package/scripts/mirror-bin.ts +20 -0
  8. package/skills/guiho-as-mirror/SKILL.md +2 -29
  9. package/library/adapters.d.ts +0 -32
  10. package/library/adapters.d.ts.map +0 -1
  11. package/library/adapters.js +0 -210
  12. package/library/agents.d.ts +0 -29
  13. package/library/agents.d.ts.map +0 -1
  14. package/library/agents.js +0 -212
  15. package/library/cli.d.ts +0 -29
  16. package/library/cli.d.ts.map +0 -1
  17. package/library/cli.js +0 -416
  18. package/library/config.d.ts +0 -18
  19. package/library/config.d.ts.map +0 -1
  20. package/library/config.js +0 -280
  21. package/library/errors.d.ts +0 -9
  22. package/library/errors.d.ts.map +0 -1
  23. package/library/errors.js +0 -15
  24. package/library/executor.d.ts +0 -7
  25. package/library/executor.d.ts.map +0 -1
  26. package/library/executor.js +0 -48
  27. package/library/flags.d.ts +0 -6
  28. package/library/flags.d.ts.map +0 -1
  29. package/library/flags.js +0 -80
  30. package/library/guiho-mirror-bin.d.ts +0 -6
  31. package/library/guiho-mirror-bin.d.ts.map +0 -1
  32. package/library/guiho-mirror-bin.js +0 -6
  33. package/library/guiho-mirror.d.ts +0 -18
  34. package/library/guiho-mirror.d.ts.map +0 -1
  35. package/library/guiho-mirror.js +0 -16
  36. package/library/hooks.d.ts +0 -14
  37. package/library/hooks.d.ts.map +0 -1
  38. package/library/hooks.js +0 -122
  39. package/library/init.d.ts +0 -12
  40. package/library/init.d.ts.map +0 -1
  41. package/library/init.js +0 -100
  42. package/library/plan.d.ts +0 -10
  43. package/library/plan.d.ts.map +0 -1
  44. package/library/plan.js +0 -85
  45. package/library/reporter.d.ts +0 -15
  46. package/library/reporter.d.ts.map +0 -1
  47. package/library/reporter.js +0 -182
  48. package/library/schema.d.ts +0 -164
  49. package/library/schema.d.ts.map +0 -1
  50. package/library/schema.js +0 -152
  51. package/library/types.d.ts +0 -205
  52. package/library/types.d.ts.map +0 -1
  53. package/library/types.js +0 -4
  54. package/library/version.d.ts +0 -10
  55. package/library/version.d.ts.map +0 -1
  56. 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 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.
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: Node >= 20
14
+ - Runtime target: native Bun-compiled CLI binary
15
15
  - Development runtime: Bun
16
- - Package type: ESM
17
- - Library entrypoint: `source/guiho-mirror.ts`
16
+ - Package type: CLI-only
18
17
  - CLI entrypoint: `source/guiho-mirror-bin.ts`
19
- - TypeScript build output: `library/`
20
- - Standalone binary output: `bin/mirror` or `bin/mirror.exe`
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` and a TypeScript API for loading configuration, building release plans, reading versions, and applying version changes.
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 Mirror as a development dependency:
84
+ Install the native binary directly on macOS or Linux:
84
85
 
85
86
  ```bash
86
- bun add -d @guiho/mirror
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
- Or with npm:
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
- Use the CLI through the package manager or through the installed `mirror` binary.
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, TypeScript APIs, release behavior, Git behavior, package contents, agent automation, tests that describe public behavior, and operational workflows.
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 library export surface.
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`: citty command tree, CLI argument mapping, and process-facing error handling.
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
- - `library/`: TypeScript build output used by `main` and `types`.
563
- - `bin/`: compiled standalone CLI binary output.
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
- Build the library:
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 build`.
623
- 7. Run `bun run binary` when the CLI binary is part of the release validation.
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 and TypeScript library 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.
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 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).
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 and Node >= 20. Run from the `mirror/` directory:
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.2.1",
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.2.1",
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": "./library/guiho-mirror-bin.js"
7
+ "mirror": "./scripts/mirror-bin.ts"
16
8
  },
17
9
  "files": [
18
10
  "README.md",
19
- "library/",
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": "rm -rf library && tsc -p tsconfig.build.json",
49
- "binary": "bun build source/guiho-mirror-bin.ts --compile --outfile bin/mirror",
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
- "citty": "^0.2.2",
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 and TypeScript library 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.
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 runs on Node >= 20 at runtime, Bun, and Deno. Bun is the recommended development tool for the Mirror project itself. Git is required only for Git-based workflows: `source = "git"`, `output = ["git"]`, commits, tags, or pushes.
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:
@@ -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"}