@guiho/mirror 3.0.0-alpha.4

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 3.0.0-alpha.2 (2026-05-17)
+
+Initial open source release.
+
+### Features
+
+- TOML-based configuration with `mirror.config.toml`
+- Semantic versioning with `semver` support
+- Adapters for `package.json`, `jsr.json`, and Git tags
+- CLI with `mirror init`, `mirror config`, and `mirror version` commands
+- Dry-run mode, dirty worktree protection, and interactive confirmation
+- Text and JSON output formats
+- Git commit, tag, and push automation
+- Prerelease identifier support

package/LICENSE.md

@@ -0,0 +1,23 @@
+@guiho/mirror
+
+The MIT License (MIT)
+
+Copyright (c) 2026 Cristóvão GUIHO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# 🪞 GUIHO Mirror
+
+**Open source project versioning for Bun, npm, JSR, and Git.**
+
+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.
+
+```text
+source -> version engine -> plan -> outputs
+```
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+bun add -d @guiho/mirror
+```
+
+### Initializing
+
+Create a default configuration file for your project type:
+
+```bash
+mirror init package.json
+# or
+mirror init jsr.json
+# or
+mirror init git
+```
+
+### Typical Workflow
+
+```bash
+# See current version
+mirror version current
+
+# Preview a patch release
+mirror version plan patch
+
+# Apply a minor release and create a Git commit & tag
+mirror version apply minor --commit --yes
+```
+
+---
+
+## 📖 Documentation
+
+Mirror's architecture is based on a predictable read-plan-apply lifecycle, making it safe and easy to automate. It is designed to be easily consumed by humans and AI agents.
+
+### Project Model
+
+Mirror uses a strict release model:
+- **Project:** The package, repository, application, or directory being versioned.
+- **Source:** The single adapter Mirror reads the current version from.
+- **Output:** The adapters Mirror writes the next version to.
+- **Plan:** The read-only description of all intended changes before any mutation occurs.
+
+### Adapters
+
+Adapters connect Mirror to different versioning ecosystems:
+- `package.json`: Reads/writes the `version` field in a `package.json` file.
+- `jsr.json`: Reads/writes the `version` field in a `jsr.json` file.
+- `git`: Reads versions from Git tags and creates release tags/commits.
+
+### CLI Commands
+
+Mirror provides a concise CLI with three main command groups:
+
+#### `mirror init`
+Creates a `mirror.config.toml` file in the current directory.
+- `mirror init package.json`
+- `mirror init jsr.json`
+- `mirror init git`
+
+#### `mirror config`
+Validates and inspects configuration.
+- `mirror config show`: Prints the resolved configuration.
+- `mirror config check`: Validates configuration without output.
+- `mirror config schema`: Prints the comprehensive configuration reference.
+
+#### `mirror version`
+Manages the version lifecycle.
+- `mirror version current`: Prints the current project version.
+- `mirror version next <target>`: Prints the next version without side-effects.
+- `mirror version plan <target>`: Builds and prints the release plan.
+- `mirror version apply <target>`: Applies the release plan.
+
+*Targets supported:* `major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, `prerelease`, or an exact semantic version (e.g., `2.0.0`).
+
+### Configuration (`mirror.config.toml`)
+
+Mirror looks for configuration via the `--config <path>` flag, `./mirror.config.toml`, or `./config/mirror.config.toml`.
+
+```toml
+schema = 1
+
+[project]
+name = "my-project"                    # Optional. Explicit project name.
+name_source = "package.json"           # Optional. "package.json" or "jsr.json"
+
+[version]
+scheme = "semver"                      # Required. Only "semver" is supported.
+source = "package.json"                # Required. "package.json", "jsr.json", or "git"
+output = ["package.json", "git"]       # Required. Adapters to write to.
+prerelease_id = "alpha"                # Optional. e.g., creates 1.0.1-alpha.0
+
+[package]
+path = "package.json"                  # Optional. Override path to package.json
+
+[jsr]
+path = "jsr.json"                      # Optional. Override path to jsr.json
+
+[git]
+tag_template = "{name}@{version}"      # Optional. Supported: "v{version}", "{name}@{version}", "{name}/v{version}"
+commit = false                         # Optional. Create release commits. Default: false.
+push = false                           # Optional. Push release refs. Default: false.
+allow_dirty = false                    # Optional. Allow dirty Git worktree. Default: false.
+```
+
+### Safety & Git Automation
+
+By default, `mirror version apply` prevents accidental mutations:
+- Fails on a dirty Git worktree (unless `--allow-dirty` is used).
+- Requires `--yes` to skip interactive confirmation (non-interactive environments).
+- Never pushes release refs automatically unless configured or `--push` is passed.
+
+When combining file outputs (`package.json`, `jsr.json`) with Git tag output, Mirror requires either `--commit` or `--push` so that the tag attaches to the release commit containing the updated files. For Git-only outputs, `--commit` will not create an empty commit; it simply tags `HEAD`.
+
+---
+
+## 💻 API Reference
+
+Mirror exposes a fully-typed TypeScript API for custom automation scripts.
+
+### Core Lifecycle Methods
+
+```ts
+import { buildVersionPlan, applyVersionPlan, executeVersionPlan } from '@guiho/mirror'
+
+// 1. Build a read-only plan for a patch release
+const plan = await buildVersionPlan('patch', { cwd: process.cwd() })
+
+// 2. Inspect the plan
+console.log(plan.currentVersion) // "1.0.0"
+console.log(plan.nextVersion)    // "1.0.1"
+console.log(plan.actions)        // Array of actions (write-file, git-commit, etc.)
+
+// 3. Execute the plan manually
+const result = await executeVersionPlan(plan, { dryRun: false, yes: true })
+
+// OR: Build and apply in one step
+await applyVersionPlan('minor', { cwd: process.cwd(), yes: true })
+```
+
+### Reading State
+
+```ts
+import { loadMirrorConfig, readCurrentVersion } from '@guiho/mirror'
+
+// Load resolved configuration
+const config = await loadMirrorConfig({ cwd: process.cwd() })
+
+// Read the current version using the configured source
+const version = await readCurrentVersion(config)
+```
+
+---
+
+## 🛠️ Development
+
+Development tasks require Bun and run from the `mirror/` directory:
+
+```bash
+cd mirror
+bun install
+bun run typecheck
+bun test
+bun run build
+bun run binary
+```
+
+---
+
+## 🎵 The Origin of the Name
+
+The name **Mirror** was inspired by the music track ["MIRROR" by SleepyThePrince & DJ Dadda](https://www.youtube.com/watch?v=vi0didVAqjU), featured on the album *"Blackout"*.
+
+In a deeper sense, the name also fits the purpose of the library perfectly: just as looking in a mirror reflects an exact snapshot of who we are, this library reflects the exact state and version of whatever you are building.

package/jsr.json

@@ -0,0 +1,12 @@
+{
+  "name": "@guiho/mirror",
+  "version": "3.0.0-alpha.4",
+  "exports": "./source/guiho-mirror.ts",
+  "publish": {
+    "include": [
+      "source/**/*.ts",
+      "README.md",
+      "LICENSE.md"
+    ]
+  }
+}

package/library/adapters.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { MirrorConfig, MirrorJsonObject } from './types';
+export declare const supportedGitTagTemplates: readonly ["v{version}", "{name}@{version}", "{name}/v{version}"];
+export declare const readPackageJson: (path: string) => Promise<MirrorJsonObject>;
+export declare const readJsrJson: (path: string) => Promise<MirrorJsonObject>;
+export declare const writeJsonObject: (path: string, object: MirrorJsonObject) => Promise<void>;
+export declare const readPackageVersion: (config: MirrorConfig) => Promise<string>;
+export declare const readJsrVersion: (config: MirrorConfig) => Promise<string>;
+export declare const readPackageName: (config: MirrorConfig) => Promise<string>;
+export declare const readJsrName: (config: MirrorConfig) => Promise<string>;
+export declare const writePackageVersion: (config: MirrorConfig, nextVersion: string) => Promise<void>;
+export declare const writeJsrVersion: (config: MirrorConfig, nextVersion: string) => Promise<void>;
+export declare const ensureAdapterFiles: (config: MirrorConfig) => Promise<void>;
+export declare const resolveProjectName: (config: MirrorConfig) => Promise<string | undefined>;
+export declare const readCurrentVersion: (config: MirrorConfig, projectName?: string) => Promise<string>;
+export declare const readGitVersion: (config: MirrorConfig, projectName?: string) => Promise<string>;
+export declare const renderGitTag: (template: string, version: string, projectName?: string) => string;
+export declare const versionFromTag: (template: string, tag: string, projectName?: string) => string | undefined;
+export declare const assertSupportedGitTagTemplate: (template: string) => void;
+export declare const isGitRepository: (cwd: string) => Promise<boolean>;
+export declare const isGitDirty: (cwd: string) => Promise<boolean>;
+export declare const createGitCommit: (cwd: string, paths: string[], message: string) => Promise<void>;
+export declare const createGitTag: (cwd: string, tag: string) => Promise<void>;
+export declare const pushGitRefs: (cwd: string, includeCommit: boolean, includeTags: boolean) => Promise<void>;
+//# sourceMappingURL=adapters.d.ts.map

package/library/adapters.d.ts.map

@@ -0,0 +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"}

package/library/adapters.js

@@ -0,0 +1,152 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { $ } from 'bun';
+import { existsSync } from 'node:fs';
+import { MirrorError } from './errors';
+import { assertValidSemver, sortSemverDescending } from './version';
+import { resolveMirrorPath } from './config';
+export const supportedGitTagTemplates = ['v{version}', '{name}@{version}', '{name}/v{version}'];
+export const readPackageJson = async (path) => readJsonObject(path, 'package.json');
+export const readJsrJson = async (path) => readJsonObject(path, 'jsr.json');
+export const writeJsonObject = async (path, object) => {
+    await Bun.write(path, `${JSON.stringify(object, null, 2)}\n`);
+};
+export const readPackageVersion = async (config) => readVersionField(resolveMirrorPath(config.cwd, config.package.path), 'package.json');
+export const readJsrVersion = async (config) => readVersionField(resolveMirrorPath(config.cwd, config.jsr.path), 'jsr.json');
+export const readPackageName = async (config) => readNameField(resolveMirrorPath(config.cwd, config.package.path), 'package.json');
+export const readJsrName = async (config) => readNameField(resolveMirrorPath(config.cwd, config.jsr.path), 'jsr.json');
+export const writePackageVersion = async (config, nextVersion) => writeVersionField(resolveMirrorPath(config.cwd, config.package.path), 'package.json', nextVersion);
+export const writeJsrVersion = async (config, nextVersion) => writeVersionField(resolveMirrorPath(config.cwd, config.jsr.path), 'jsr.json', nextVersion);
+export const ensureAdapterFiles = async (config) => {
+    if (usesAdapter(config, 'package.json'))
+        ensureFile(resolveMirrorPath(config.cwd, config.package.path), 'package.json');
+    if (usesAdapter(config, 'jsr.json'))
+        ensureFile(resolveMirrorPath(config.cwd, config.jsr.path), 'jsr.json');
+    if (usesAdapter(config, 'git'))
+        await ensureGitRepository(config.cwd);
+};
+export const resolveProjectName = async (config) => {
+    if (config.project.name)
+        return config.project.name;
+    if (config.project.nameSource === 'package.json')
+        return readPackageName(config);
+    if (config.project.nameSource === 'jsr.json')
+        return readJsrName(config);
+    return undefined;
+};
+export const readCurrentVersion = async (config, projectName) => {
+    if (config.version.source === 'package.json')
+        return readPackageVersion(config);
+    if (config.version.source === 'jsr.json')
+        return readJsrVersion(config);
+    return readGitVersion(config, projectName);
+};
+export const readGitVersion = async (config, projectName) => {
+    await ensureGitRepository(config.cwd);
+    const tagsOutput = await $ `git -C ${config.cwd} tag --list`.text();
+    const versions = tagsOutput
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((tag) => versionFromTag(config.git.tagTemplate, tag, projectName))
+        .filter((version) => Boolean(version));
+    if (versions.length === 0)
+        throw new MirrorError(`No Git tags match template: ${config.git.tagTemplate}`);
+    return sortSemverDescending(versions)[0] ?? '';
+};
+export const renderGitTag = (template, version, projectName) => {
+    assertSupportedGitTagTemplate(template);
+    assertValidSemver(version, 'Git tag version');
+    if (template.includes('{name}') && !projectName)
+        throw new MirrorError(`Tag template requires a project name: ${template}`);
+    return template.replaceAll('{version}', version).replaceAll('{name}', projectName ?? '');
+};
+export const versionFromTag = (template, tag, projectName) => {
+    assertSupportedGitTagTemplate(template);
+    if (template.includes('{name}') && !projectName)
+        throw new MirrorError(`Tag template requires a project name: ${template}`);
+    const escapedTemplate = escapeRegex(template)
+        .replaceAll('\\{version\\}', '(?<version>.+)')
+        .replaceAll('\\{name\\}', escapeRegex(projectName ?? ''));
+    const match = new RegExp(`^${escapedTemplate}$`).exec(tag);
+    const version = match?.groups?.['version'];
+    if (!version)
+        return undefined;
+    try {
+        assertValidSemver(version, 'Git tag version');
+        return version;
+    }
+    catch {
+        return undefined;
+    }
+};
+export const assertSupportedGitTagTemplate = (template) => {
+    if (!supportedGitTagTemplates.includes(template)) {
+        throw new MirrorError(`Unsupported Git tag template: ${template}. Expected v{version}, {name}@{version}, or {name}/v{version}.`);
+    }
+};
+export const isGitRepository = async (cwd) => {
+    try {
+        await $ `git -C ${cwd} rev-parse --is-inside-work-tree`.quiet();
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export const isGitDirty = async (cwd) => {
+    const output = await $ `git -C ${cwd} status --porcelain`.quiet().text();
+    return output.trim().length > 0;
+};
+export const createGitCommit = async (cwd, paths, message) => {
+    for (const path of paths)
+        await $ `git -C ${cwd} add ${path}`.quiet();
+    await $ `git -C ${cwd} commit -m ${message}`.quiet();
+};
+export const createGitTag = async (cwd, tag) => {
+    await $ `git -C ${cwd} tag ${tag} -m ${`Release ${tag}`}`.quiet();
+};
+export const pushGitRefs = async (cwd, includeCommit, includeTags) => {
+    if (includeCommit)
+        await $ `git -C ${cwd} push`.quiet();
+    if (includeTags)
+        await $ `git -C ${cwd} push --tags`.quiet();
+};
+const readJsonObject = async (path, label) => {
+    ensureFile(path, label);
+    const json = await Bun.file(path).json();
+    if (typeof json !== 'object' || json === null || Array.isArray(json))
+        throw new MirrorError(`${label} must contain a JSON object: ${path}`);
+    return json;
+};
+const readVersionField = async (path, label) => {
+    const json = await readJsonObject(path, label);
+    const version = json['version'];
+    if (typeof version !== 'string')
+        throw new MirrorError(`${label} must contain a string version field: ${path}`);
+    assertValidSemver(version, `${label} version`);
+    return version;
+};
+const readNameField = async (path, label) => {
+    const json = await readJsonObject(path, label);
+    const name = json['name'];
+    if (typeof name !== 'string' || name.length === 0)
+        throw new MirrorError(`${label} must contain a string name field: ${path}`);
+    return name;
+};
+const writeVersionField = async (path, label, nextVersion) => {
+    const json = await readJsonObject(path, label);
+    json['version'] = nextVersion;
+    await writeJsonObject(path, json);
+};
+const ensureFile = (path, label) => {
+    if (!existsSync(path))
+        throw new MirrorError(`${label} file not found: ${path}`);
+};
+const ensureGitRepository = async (cwd) => {
+    if (!(await isGitRepository(cwd)))
+        throw new MirrorError(`Not a Git repository: ${cwd}`);
+};
+const usesAdapter = (config, adapter) => config.version.source === adapter || config.version.output.includes(adapter);
+const escapeRegex = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');

package/library/cli.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+export declare const createMirrorCommand: () => import("citty").CommandDef<{
+    config: {
+        type: "string";
+        description: string;
+    };
+    cwd: {
+        type: "string";
+        description: string;
+    };
+    format: {
+        type: "enum";
+        options: string[];
+        default: string;
+        description: string;
+    };
+    'no-color': {
+        type: "boolean";
+        description: string;
+    };
+}>;
+export declare const runMirrorCli: (rawArgs?: string[]) => Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/library/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../source/cli.ts"],"names":[],"mappings":"AAAA;;GAEG;AA+CH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;EAa5B,CAAA;AAEJ,eAAO,MAAM,YAAY,GAAU,kBAA+B,kBAyCjE,CAAA"}