@guiho/mirror 3.0.0 → 3.1.0

package/library/adapters.js

@@ -1,16 +1,53 @@
 /**
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
-import { $ } from 'bun';
+import { execFile } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { MirrorError } from './errors';
-import { assertValidSemver, sortSemverDescending } from './version';
-import { resolveMirrorPath } from './config';
+import { readFile, writeFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+import { MirrorError } from './errors.js';
+import { assertValidSemver, sortSemverDescending } from './version.js';
+import { resolveMirrorPath } from './config.js';
+const execFileAsync = promisify(execFile);
+let gitChecked = false;
+let gitExists = false;
+const checkGitAvailable = async () => {
+    if (gitChecked)
+        return gitExists;
+    gitChecked = true;
+    try {
+        await execFileAsync('git', ['--version']);
+        gitExists = true;
+    }
+    catch {
+        gitExists = false;
+    }
+    return gitExists;
+};
+export const ensureGitAvailable = async () => {
+    if (!(await checkGitAvailable())) {
+        throw new MirrorError('Git executable not found. Git is required when using git as a source or output.');
+    }
+};
+const gitNotFoundMessage = 'Git executable not found. Git is required when using git as a source or output.';
+const runGit = async (cwd, args) => {
+    if (!(await checkGitAvailable())) {
+        throw new MirrorError(gitNotFoundMessage);
+    }
+    try {
+        const { stdout } = await execFileAsync('git', args, { cwd });
+        return stdout;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new MirrorError(`Git command failed: git ${args.join(' ')}\n${message}`);
+    }
+};
 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`);
+    await writeFile(path, `${JSON.stringify(object, null, 2)}\n`, 'utf8');
 };
 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');
@@ -43,8 +80,9 @@ export const readCurrentVersion = async (config, projectName) => {
     return readGitVersion(config, projectName);
 };
 export const readGitVersion = async (config, projectName) => {
+    await ensureGitAvailable();
     await ensureGitRepository(config.cwd);
-    const tagsOutput = await $ `git -C ${config.cwd} tag --list`.text();
+    const tagsOutput = await runGit(config.cwd, ['-C', config.cwd, 'tag', '--list']);
     const versions = tagsOutput
         .split(/\r?\n/)
         .map((line) => line.trim())
@@ -87,8 +125,10 @@ export const assertSupportedGitTagTemplate = (template) => {
     }
 };
 export const isGitRepository = async (cwd) => {
+    if (!(await checkGitAvailable()))
+        return false;
     try {
-        await $ `git -C ${cwd} rev-parse --is-inside-work-tree`.quiet();
+        await execFileAsync('git', ['-C', cwd, 'rev-parse', '--is-inside-work-tree']);
         return true;
     }
     catch {
@@ -96,26 +136,36 @@ export const isGitRepository = async (cwd) => {
     }
 };
 export const isGitDirty = async (cwd) => {
-    const output = await $ `git -C ${cwd} status --porcelain`.quiet().text();
+    const output = await runGit(cwd, ['-C', cwd, 'status', '--porcelain']);
     return output.trim().length > 0;
 };
 export const createGitCommit = async (cwd, paths, message) => {
+    await ensureGitAvailable();
     for (const path of paths)
-        await $ `git -C ${cwd} add ${path}`.quiet();
-    await $ `git -C ${cwd} commit -m ${message}`.quiet();
+        await runGit(cwd, ['-C', cwd, 'add', path]);
+    await runGit(cwd, ['-C', cwd, 'commit', '-m', message]);
 };
 export const createGitTag = async (cwd, tag) => {
-    await $ `git -C ${cwd} tag ${tag} -m ${`Release ${tag}`}`.quiet();
+    await ensureGitAvailable();
+    await runGit(cwd, ['-C', cwd, 'tag', tag, '-m', `Release ${tag}`]);
 };
 export const pushGitRefs = async (cwd, includeCommit, includeTags) => {
+    await ensureGitAvailable();
     if (includeCommit)
-        await $ `git -C ${cwd} push`.quiet();
+        await runGit(cwd, ['-C', cwd, 'push']);
     if (includeTags)
-        await $ `git -C ${cwd} push --tags`.quiet();
+        await runGit(cwd, ['-C', cwd, 'push', '--tags']);
 };
 const readJsonObject = async (path, label) => {
     ensureFile(path, label);
-    const json = await Bun.file(path).json();
+    const content = await readFile(path, 'utf8');
+    let json;
+    try {
+        json = JSON.parse(content);
+    }
+    catch {
+        throw new MirrorError(`${label} must contain valid JSON: ${path}`);
+    }
     if (typeof json !== 'object' || json === null || Array.isArray(json))
         throw new MirrorError(`${label} must contain a JSON object: ${path}`);
     return json;
@@ -145,6 +195,7 @@ const ensureFile = (path, label) => {
         throw new MirrorError(`${label} file not found: ${path}`);
 };
 const ensureGitRepository = async (cwd) => {
+    await ensureGitAvailable();
     if (!(await isGitRepository(cwd)))
         throw new MirrorError(`Not a Git repository: ${cwd}`);
 };

package/library/agents.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { MirrorAgentAutomationResult, MirrorAgentSettings, MirrorAgentsInstructionsResult, MirrorCliOptions, MirrorSkillInstallResult, MirrorSkillInstallScope } from './types.js';
+export declare const mirrorSkillName = "guiho-as-mirror";
+export declare const mirrorAgentsSectionHeading = "## Semantic Project Versioning -- GUIHO Mirror";
+export declare const defaultMirrorAgentSettings: MirrorAgentSettings;
+export declare const mirrorAgentsSection = "## Semantic Project Versioning -- GUIHO Mirror\n\nInvoke the guiho-as-mirror agent skill every time the user wants to bump, tag, release, plan, initialize, configure, or troubleshoot semantic project versioning with GUIHO Mirror.\n\nBefore editing release docs or changelogs, inspect mirror.config.toml. If [agents].write_changelog is false, skip changelog edits. If it is missing or true, changelog edits are allowed when the project has a changelog.\n\nUse [agents].changelog_path as the changelog file path. If it is missing, use CHANGELOG.md in the project root.\n";
+type MirrorSkillPathOptions = {
+    cwd?: string;
+    homeDirectory?: string;
+};
+type MirrorSkillInstallOptions = MirrorSkillPathOptions & {
+    overwrite?: boolean;
+};
+type MirrorAgentAutomationOptions = MirrorCliOptions & {
+    homeDirectory?: string;
+};
+export declare const resolveMirrorSkillPath: (scope: MirrorSkillInstallScope, options?: MirrorSkillPathOptions) => string;
+export declare const isMirrorSkillInstalled: (scope: MirrorSkillInstallScope, options?: MirrorSkillPathOptions) => boolean;
+export declare const installMirrorSkill: (scope: MirrorSkillInstallScope, options?: MirrorSkillInstallOptions) => Promise<MirrorSkillInstallResult>;
+export declare const ensureMirrorAgentsInstructions: (cwd: string, create?: boolean) => Promise<MirrorAgentsInstructionsResult>;
+export declare const findAgentsFile: (cwd: string) => string | undefined;
+export declare const resolveMirrorAgentSettings: (options?: MirrorCliOptions) => Promise<MirrorAgentSettings>;
+export declare const runMirrorAgentAutomation: (options?: MirrorAgentAutomationOptions, notify?: (message: string) => void) => Promise<MirrorAgentAutomationResult>;
+export {};
+//# sourceMappingURL=agents.d.ts.map

package/library/agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../source/agents.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EACV,2BAA2B,EAC3B,mBAAmB,EACnB,8BAA8B,EAC9B,gBAAgB,EAChB,wBAAwB,EACxB,uBAAuB,EACxB,MAAM,YAAY,CAAA;AAInB,eAAO,MAAM,eAAe,oBAAoB,CAAA;AAChD,eAAO,MAAM,0BAA0B,mDAAmD,CAAA;AAE1F,eAAO,MAAM,0BAA0B,EAAE,mBAKxC,CAAA;AAED,eAAO,MAAM,mBAAmB,6jBAO/B,CAAA;AAED,KAAK,sBAAsB,GAAG;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,KAAK,yBAAyB,GAAG,sBAAsB,GAAG;IACxD,SAAS,CAAC,EAAE,OAAO,CAAA;CACpB,CAAA;AAED,KAAK,4BAA4B,GAAG,gBAAgB,GAAG;IACrD,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,OAAO,uBAAuB,EAAE,UAAS,sBAA2B,WAI1G,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,OAAO,uBAAuB,EAAE,UAAS,sBAA2B,YACvD,CAAA;AAEpD,eAAO,MAAM,kBAAkB,GAC7B,OAAO,uBAAuB,EAC9B,UAAS,yBAA8B,KACtC,OAAO,CAAC,wBAAwB,CAelC,CAAA;AAED,eAAO,MAAM,8BAA8B,GAAU,KAAK,MAAM,EAAE,gBAAc,KAAG,OAAO,CAAC,8BAA8B,CAkBxH,CAAA;AAED,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAWrD,CAAA;AAED,eAAO,MAAM,0BAA0B,GAAU,UAAS,gBAAqB,KAAG,OAAO,CAAC,mBAAmB,CAa5G,CAAA;AAED,eAAO,MAAM,wBAAwB,GACnC,UAAS,4BAAiC,EAC1C,SAAQ,CAAC,OAAO,EAAE,MAAM,KAAK,IAAe,KAC3C,OAAO,CAAC,2BAA2B,CAoBrC,CAAA"}

package/library/agents.js

@@ -0,0 +1,205 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { MirrorError } from './errors.js';
+import { discoverMirrorConfig, resolveMirrorPath } from './config.js';
+export const mirrorSkillName = 'guiho-as-mirror';
+export const mirrorAgentsSectionHeading = '## Semantic Project Versioning -- GUIHO Mirror';
+export const defaultMirrorAgentSettings = {
+    writeChangelog: true,
+    changelogPath: 'CHANGELOG.md',
+    autoAgentsMd: true,
+    autoSkillInstall: true,
+};
+export const mirrorAgentsSection = `${mirrorAgentsSectionHeading}
+
+Invoke the guiho-as-mirror agent skill every time the user wants to bump, tag, release, plan, initialize, configure, or troubleshoot semantic project versioning with GUIHO Mirror.
+
+Before editing release docs or changelogs, inspect mirror.config.toml. If [agents].write_changelog is false, skip changelog edits. If it is missing or true, changelog edits are allowed when the project has a changelog.
+
+Use [agents].changelog_path as the changelog file path. If it is missing, use CHANGELOG.md in the project root.
+`;
+export const resolveMirrorSkillPath = (scope, options = {}) => {
+    if (scope === 'local')
+        return resolve(options.cwd ?? process.cwd(), '.opencode', 'skills', mirrorSkillName, 'SKILL.md');
+    return resolve(resolveMirrorAgentHome(options.homeDirectory), '.config', 'opencode', 'skills', mirrorSkillName, 'SKILL.md');
+};
+export const isMirrorSkillInstalled = (scope, options = {}) => existsSync(resolveMirrorSkillPath(scope, options));
+export const installMirrorSkill = async (scope, options = {}) => {
+    const path = resolveMirrorSkillPath(scope, options);
+    const exists = existsSync(path);
+    if (exists && options.overwrite === false)
+        return { scope, path, installed: false, updated: false };
+    const content = await readBundledMirrorSkill();
+    const current = exists ? await readFile(path, 'utf8') : undefined;
+    if (current === content)
+        return { scope, path, installed: false, updated: false };
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, 'utf8');
+    return { scope, path, installed: !exists, updated: exists };
+};
+export const ensureMirrorAgentsInstructions = async (cwd, create = false) => {
+    const path = findAgentsFile(cwd) ?? resolve(cwd, 'AGENTS.md');
+    const exists = existsSync(path);
+    if (!exists && !create)
+        return { path, exists: false, changed: false };
+    if (!exists) {
+        await writeFile(path, `# Project Agents\n\n${mirrorAgentsSection}\n`, 'utf8');
+        return { path, exists: true, changed: true };
+    }
+    const content = await readFile(path, 'utf8');
+    if (content.includes(mirrorAgentsSectionHeading))
+        return { path, exists: true, changed: false };
+    const nextContent = `${content.trimEnd()}\n\n${mirrorAgentsSection}\n`;
+    await writeFile(path, nextContent, 'utf8');
+    return { path, exists: true, changed: true };
+};
+export const findAgentsFile = (cwd) => {
+    let current = resolve(cwd);
+    while (true) {
+        const path = resolve(current, 'AGENTS.md');
+        if (existsSync(path))
+            return path;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+};
+export const resolveMirrorAgentSettings = async (options = {}) => {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const discovered = await discoverMirrorConfig(cwd, options.config);
+    if (!discovered.raw)
+        return { ...defaultMirrorAgentSettings };
+    if (discovered.raw.schema !== 1)
+        throw new MirrorError('Unsupported or missing configuration schema. Expected `schema = 1`.');
+    return {
+        writeChangelog: optionalBoolean(discovered.raw.agents?.write_changelog, 'agents.write_changelog') !== false,
+        changelogPath: optionalString(discovered.raw.agents?.changelog_path, 'agents.changelog_path') ?? 'CHANGELOG.md',
+        autoAgentsMd: optionalBoolean(discovered.raw.agents?.auto_agents_md, 'agents.auto_agents_md') !== false,
+        autoSkillInstall: optionalBoolean(discovered.raw.agents?.auto_skill_install, 'agents.auto_skill_install') !== false,
+    };
+};
+export const runMirrorAgentAutomation = async (options = {}, notify = () => { }) => {
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const settings = await resolveMirrorAgentSettings(options);
+    const result = { settings };
+    if (settings.autoAgentsMd)
+        result.agentsMd = await ensureMirrorAgentsInstructions(cwd, false);
+    if (settings.autoSkillInstall) {
+        for (const scope of ['local', 'global']) {
+            if (isMirrorSkillInstalled(scope, { cwd, homeDirectory: options.homeDirectory }))
+                continue;
+            const path = resolveMirrorSkillPath(scope, { cwd, homeDirectory: options.homeDirectory });
+            notify(`notice: ${mirrorSkillName} skill not found ${scope}; Mirror is installing it at ${path}`);
+            const installed = await installMirrorSkill(scope, { cwd, homeDirectory: options.homeDirectory, overwrite: false });
+            if (scope === 'local')
+                result.localSkill = installed;
+            if (scope === 'global')
+                result.globalSkill = installed;
+        }
+    }
+    return result;
+};
+const readBundledMirrorSkill = async () => {
+    try {
+        return await readFile(new URL('../skills/guiho-as-mirror/SKILL.md', import.meta.url), 'utf8');
+    }
+    catch {
+        return embeddedMirrorSkillContent;
+    }
+};
+const resolveMirrorAgentHome = (homeDirectory) => {
+    const value = homeDirectory ?? process.env['MIRROR_AGENT_HOME'] ?? homedir();
+    return resolveMirrorPath(process.cwd(), value);
+};
+const optionalBoolean = (value, key) => {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'boolean')
+        throw new MirrorError(`Invalid ${key}. Expected true or false.`);
+    return value;
+};
+const optionalString = (value, key) => {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new MirrorError(`Invalid ${key}. Expected a string.`);
+    return value;
+};
+const embeddedMirrorSkillContent = [
+    '---',
+    'name: guiho-as-mirror',
+    'description: Use this skill whenever the user asks to version, bump, release, tag, initialize, configure, or troubleshoot a project with GUIHO Mirror. This includes Bun, npm, JSR, package.json, jsr.json, Git tag, semantic versioning, changelog, release-plan, prerelease, and what version comes next workflows.',
+    '---',
+    '',
+    '# GUIHO Mirror',
+    '',
+    'GUIHO Mirror is a deterministic CLI and TypeScript library for semantic project versioning. Use it instead of ad hoc version edits, manual package-manager version commands, or manual release tags.',
+    '',
+    '## Command Selection',
+    '',
+    '1. Use `bun @guiho/mirror` when the package is installed locally and Bun is available.',
+    '2. Use `mirror` when a global binary is available.',
+    '3. Use `bunx @guiho/mirror` when running without installation.',
+    '',
+    'Run `mirror --help` or `mirror <command> --help` for command-specific details when needed.',
+    '',
+    '## Release Workflow',
+    '',
+    'When the user asks to bump, release, tag, or version a project, follow this sequence:',
+    '',
+    '1. Confirm the target and project root. Supported targets are `major`, `premajor`, `minor`, `preminor`, `patch`, `prepatch`, `prerelease`, or an exact semver like `2.0.0`.',
+    '2. Run `<mirror> config show` and read `[git].allow_dirty`, `[agents].write_changelog`, and `[agents].changelog_path`.',
+    '3. If `allow_dirty = false` or absent, check `git status --short` and stop if the worktree is dirty.',
+    '4. Run the project type checker, commonly `bun run typecheck`.',
+    '5. Run the project test suite, commonly `bun test`.',
+    '6. Run `<mirror> version plan <target>` and use the planned next version as the source of truth.',
+    '7. Update release documentation only when it is part of the project release process.',
+    '8. If `[agents].write_changelog = false`, skip changelog edits. Otherwise update `[agents].changelog_path`, defaulting to `CHANGELOG.md` in the project root, and summarize only real changes.',
+    '9. Commit release-preparation changes before applying the version bump.',
+    '10. Run `<mirror> version apply <target> --yes`. Include `--commit` when file outputs and Git tag output are combined unless config already enables commits or push.',
+    '',
+    '## Safety Rules',
+    '',
+    '- Never skip `version plan`.',
+    '- Never hand-edit `package.json` or `jsr.json` version fields as a Mirror substitute.',
+    '- Never create Git tags manually for a Mirror-managed release unless recovering intentionally.',
+    '- Do not apply a version bump after failed typecheck or tests.',
+    '- Do not push release refs unless explicitly requested or configured.',
+    '- When plan output is surprising, stop and explain the mismatch.',
+    '',
+    '## Initialization Workflow',
+    '',
+    'Use `mirror init package.json`, `mirror init jsr.json`, or `mirror init git`, then validate with `mirror config check`, inspect with `mirror config show`, and test with `mirror version current` plus `mirror version plan patch`.',
+    '',
+    '## Configuration Reference',
+    '',
+    'Mirror searches for configuration via `--config <path>`, `./mirror.config.toml`, or `./config/mirror.config.toml`.',
+    '',
+    'Common configuration keys: `[version].source`, `[version].output`, `[version].prerelease_id`, `[git].tag_template`, `[git].commit`, `[git].push`, `[git].allow_dirty`, `[agents].write_changelog`, `[agents].changelog_path`, `[agents].auto_agents_md`, and `[agents].auto_skill_install`.',
+    '',
+    'Agent automation options default to true. Set `write_changelog = false` to tell agents to skip changelog edits, `changelog_path = "docs/CHANGELOG.md"` to specify the changelog file, `auto_agents_md = false` to stop Mirror from inserting its AGENTS.md section, and `auto_skill_install = false` to stop Mirror from installing `guiho-as-mirror` when missing.',
+    '',
+    '## CLI Reference',
+    '',
+    '- `mirror config show`',
+    '- `mirror config check`',
+    '- `mirror config schema`',
+    '- `mirror agents install local`',
+    '- `mirror agents install global`',
+    '- `mirror agents instructions`',
+    '- `mirror version current`',
+    '- `mirror version next <target>`',
+    '- `mirror version plan <target>`',
+    '- `mirror version apply <target> --yes`',
+    '',
+    '## Response Style',
+    '',
+    'When reporting a Mirror release result, include the target, current version, planned next version, typecheck/test status, docs or changelog files changed, final apply command, and whether commits, tags, or pushes were created.',
+    '',
+].join('\n');

package/library/cli.d.ts.map

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

package/library/cli.js

@@ -4,14 +4,15 @@
 import { defineCommand, runMain } from 'citty';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { MirrorError } from './errors';
-import { readCurrentVersion, resolveProjectName } from './adapters';
-import { configPathForDisplay, discoverMirrorConfig, loadMirrorConfig, relativeFromCwd, writeInitConfig } from './config';
-import { executeVersionPlan } from './executor';
-import { parseMirrorCliOptions } from './flags';
-import { buildVersionPlan, validateMirrorConfig } from './plan';
-import { mirrorBanner, reportConfig, reportConfigSchema, reportExecution, reportExecutionSummary, reportPlan, reportValue } from './reporter';
-import { resolveNextVersion } from './version';
+import { ensureMirrorAgentsInstructions, installMirrorSkill, runMirrorAgentAutomation } from './agents.js';
+import { MirrorError } from './errors.js';
+import { readCurrentVersion, resolveProjectName } from './adapters.js';
+import { configPathForDisplay, discoverMirrorConfig, loadMirrorConfig, relativeFromCwd, writeInitConfig } from './config.js';
+import { executeVersionPlan } from './executor.js';
+import { parseMirrorCliOptions } from './flags.js';
+import { buildVersionPlan, validateMirrorConfig } from './plan.js';
+import { mirrorBanner, reportAgentsInstructions, reportConfig, reportConfigSchema, reportExecution, reportExecutionSummary, reportPlan, reportSkillInstall, reportValue, } from './reporter.js';
+import { resolveNextVersion } from './version.js';
 const mirrorVersion = readInstalledVersion();
 const globalArgs = {
     config: { type: 'string', description: 'Path to mirror.config.toml' },
@@ -49,6 +50,7 @@ export const createMirrorCommand = () => defineCommand({
     subCommands: {
         init: createInitCommand(),
         config: createConfigCommand(),
+        agents: createAgentsCommand(),
         version: createVersionCommand(),
     },
 });
@@ -75,19 +77,16 @@ export const runMirrorCli = async (rawArgs = process.argv.slice(2)) => {
                     '  mirror version plan patch              # Preview a patch release plan',
                     '  mirror version apply minor --commit    # Apply a minor release with commit',
                     '  mirror version plan patch --output=package.json,jsr.json,git  # Plan with package, jsr, and git',
+                    '  mirror agents install local            # Install guiho-as-mirror in this project',
+                    '  mirror agents instructions             # Insert Mirror guidance into AGENTS.md',
                     '  mirror config schema                   # Print the configuration file reference',
                     '',
                 ].join('\n') + '\n');
             });
         }
-        // Intercept console.error during runMain to suppress citty's default
-        // ugly error dump (it does console.error(error, "\n") for non-CLIErrors).
-        // We capture the error object and handle it ourselves below.
         let capturedError = undefined;
         const originalConsoleError = console.error;
         console.error = (...args) => {
-            // citty prints CLIError messages as strings — let those through
-            // citty prints non-CLIError errors as objects — capture those
             if (args.length > 0 && args[0] instanceof Error) {
                 capturedError = args[0];
                 return;
@@ -97,8 +96,6 @@ export const runMirrorCli = async (rawArgs = process.argv.slice(2)) => {
         const originalProcessExit = process.exit;
         let exitCode;
         process.exit = ((code) => {
-            // If runMain calls process.exit(1) after an error, intercept it
-            // so we can handle the error ourselves. Let exit(0) through (--help).
             if (code !== 0 && capturedError) {
                 exitCode = code;
                 return undefined;
@@ -170,6 +167,7 @@ const createConfigCommand = () => defineCommand({
             args: overrideArgs,
             async run(context) {
                 const options = cliOptions(context.rawArgs, context.args);
+                await prepareAgents(options);
                 const config = await loadMirrorConfig(options);
                 if (options.format !== 'json')
                     process.stdout.write(mirrorBanner(configPathForDisplay(config)));
@@ -181,6 +179,7 @@ const createConfigCommand = () => defineCommand({
             args: overrideArgs,
             async run(context) {
                 const options = cliOptions(context.rawArgs, context.args);
+                await prepareAgents(options);
                 await validateMirrorConfig(options);
                 process.stdout.write(reportValue('ok', options.format));
             },
@@ -197,6 +196,36 @@ const createConfigCommand = () => defineCommand({
         }),
     },
 });
+const createAgentsCommand = () => defineCommand({
+    meta: { name: 'agents', description: 'Install Mirror agent skills and AGENTS.md instructions.' },
+    subCommands: {
+        install: defineCommand({
+            meta: { name: 'install', description: 'Install the guiho-as-mirror agent skill.' },
+            subCommands: {
+                local: createInstallSkillCommand('local'),
+                global: createInstallSkillCommand('global'),
+            },
+        }),
+        instructions: defineCommand({
+            meta: { name: 'instructions', description: 'Insert GUIHO Mirror semantic versioning guidance into AGENTS.md.' },
+            args: globalArgs,
+            async run(context) {
+                const options = cliOptions(context.rawArgs, context.args);
+                const result = await ensureMirrorAgentsInstructions(resolve(options.cwd ?? process.cwd()), true);
+                process.stdout.write(reportAgentsInstructions(result, options.format));
+            },
+        }),
+    },
+});
+const createInstallSkillCommand = (scope) => defineCommand({
+    meta: { name: scope, description: `Install the guiho-as-mirror skill ${scope}.` },
+    args: globalArgs,
+    async run(context) {
+        const options = cliOptions(context.rawArgs, context.args);
+        const result = await installMirrorSkill(scope, { cwd: resolve(options.cwd ?? process.cwd()) });
+        process.stdout.write(reportSkillInstall(result, options.format));
+    },
+});
 const createVersionCommand = () => defineCommand({
     meta: { name: 'version', description: 'Read, plan, and apply version changes.' },
     subCommands: {
@@ -205,6 +234,7 @@ const createVersionCommand = () => defineCommand({
             args: overrideArgs,
             async run(context) {
                 const options = cliOptions(context.rawArgs, context.args);
+                await prepareAgents(options);
                 const config = await loadMirrorConfig(options);
                 const projectName = await resolveProjectName(config);
                 process.stdout.write(reportValue(await readCurrentVersion(config, projectName), options.format));
@@ -215,6 +245,7 @@ const createVersionCommand = () => defineCommand({
             args: { ...overrideArgs, ...targetArg },
             async run(context) {
                 const options = cliOptions(context.rawArgs, context.args);
+                await prepareAgents(options);
                 const config = await loadMirrorConfig(options);
                 const projectName = await resolveProjectName(config);
                 const currentVersion = await readCurrentVersion(config, projectName);
@@ -226,6 +257,7 @@ const createVersionCommand = () => defineCommand({
             args: { ...overrideArgs, ...targetArg },
             async run(context) {
                 const options = cliOptions(context.rawArgs, context.args);
+                await prepareAgents(options);
                 const plan = await buildVersionPlan(String(context.args['target']), options);
                 if (options.format !== 'json')
                     process.stdout.write(mirrorBanner(plan.configPath ? plan.configPath : ''));
@@ -237,6 +269,7 @@ const createVersionCommand = () => defineCommand({
             args: { ...applyArgs, ...targetArg },
             async run(context) {
                 const options = cliOptions(context.rawArgs, context.args);
+                await prepareAgents(options);
                 const plan = await buildVersionPlan(String(context.args['target']), options);
                 if (options.format !== 'json')
                     process.stdout.write(mirrorBanner(plan.configPath ? plan.configPath : ''));
@@ -287,6 +320,9 @@ const outputArg = (value) => {
         return adapter;
     });
 };
+const prepareAgents = async (options) => {
+    await runMirrorAgentAutomation(options, (message) => console.error(message));
+};
 function readInstalledVersion() {
     try {
         const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));

package/library/config.d.ts

@@ -1,7 +1,7 @@
 /**
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
-import type { MirrorAdapterName, MirrorCliOptions, MirrorConfig, MirrorConfigDiscovery, MirrorRawConfig } from './types';
+import type { MirrorAdapterName, MirrorCliOptions, MirrorConfig, MirrorConfigDiscovery, MirrorRawConfig } from './types.js';
 export declare const resolveMirrorPath: (cwd: string, path: string) => string;
 export declare const relativeFromCwd: (cwd: string, path: string) => string;
 export declare const discoverMirrorConfig: (cwd: string, explicitPath?: string) => Promise<MirrorConfigDiscovery>;

package/library/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../source/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,qBAAqB,EAErB,eAAe,EAChB,MAAM,SAAS,CAAA;AAMhB,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,EAAE,MAAM,MAAM,WAAmD,CAAA;AAE9G,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,EAAE,MAAM,MAAM,WAGxD,CAAA;AAED,eAAO,MAAM,oBAAoB,GAAU,KAAK,MAAM,EAAE,eAAe,MAAM,KAAG,OAAO,CAAC,qBAAqB,CAa5G,CAAA;AAED,eAAO,MAAM,cAAc,GAAU,MAAM,MAAM,KAAG,OAAO,CAAC,eAAe,CAQ1E,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAU,UAAS,gBAAqB,KAAG,OAAO,CAAC,YAAY,CAO3F,CAAA;AAED,eAAO,MAAM,qBAAqB,GAChC,KAAK,eAAe,EACpB,KAAK,MAAM,EACX,YAAY,MAAM,GAAG,SAAS,EAC9B,UAAS,gBAAqB,KAC7B,YA6CF,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,MAAM,iBAAiB,EAAE,KAAK,MAAM,WAqEpE,CAAA;AAED,eAAO,MAAM,eAAe,GAAU,MAAM,iBAAiB,EAAE,KAAK,MAAM,EAAE,mBAAiB,oBAO5F,CAAA;AAED,eAAO,MAAM,oBAAoB,GAAI,QAAQ,YAAY,WAAoF,CAAA"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../source/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,qBAAqB,EAErB,eAAe,EAChB,MAAM,YAAY,CAAA;AAMnB,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,EAAE,MAAM,MAAM,WAAmD,CAAA;AAE9G,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,EAAE,MAAM,MAAM,WAGxD,CAAA;AAED,eAAO,MAAM,oBAAoB,GAAU,KAAK,MAAM,EAAE,eAAe,MAAM,KAAG,OAAO,CAAC,qBAAqB,CAa5G,CAAA;AAED,eAAO,MAAM,cAAc,GAAU,MAAM,MAAM,KAAG,OAAO,CAAC,eAAe,CAe1E,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAU,UAAS,gBAAqB,KAAG,OAAO,CAAC,YAAY,CAO3F,CAAA;AAED,eAAO,MAAM,qBAAqB,GAChC,KAAK,eAAe,EACpB,KAAK,MAAM,EACX,YAAY,MAAM,GAAG,SAAS,EAC9B,UAAS,gBAAqB,KAC7B,YAuDF,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,MAAM,iBAAiB,EAAE,KAAK,MAAM,WAuFpE,CAAA;AAED,eAAO,MAAM,eAAe,GAAU,MAAM,iBAAiB,EAAE,KAAK,MAAM,EAAE,mBAAiB,oBAO5F,CAAA;AAED,eAAO,MAAM,oBAAoB,GAAI,QAAQ,YAAY,WAAoF,CAAA"}

package/library/config.js

@@ -2,8 +2,10 @@
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
 import { existsSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
 import { basename, isAbsolute, join, relative, resolve } from 'node:path';
-import { MirrorError } from './errors';
+import { parse as parseToml } from 'smol-toml';
+import { MirrorError } from './errors.js';
 const adapters = new Set(['package.json', 'jsr.json', 'git']);
 const projectNameSources = new Set(['package.json', 'jsr.json']);
 export const resolveMirrorPath = (cwd, path) => (isAbsolute(path) ? path : resolve(cwd, path));
@@ -27,7 +29,15 @@ export const discoverMirrorConfig = async (cwd, explicitPath) => {
 export const readConfigFile = async (path) => {
     if (!existsSync(path))
         throw new MirrorError(`Configuration file not found: ${path}`);
-    const parsed = Bun.TOML.parse(await Bun.file(path).text());
+    const content = await readFile(path, 'utf8');
+    let parsed;
+    try {
+        parsed = parseToml(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new MirrorError(`Invalid TOML in configuration file: ${path}\n${message}`);
+    }
     if (!isRecord(parsed))
         throw new MirrorError(`Configuration file must contain a TOML object: ${path}`);
     return parsed;
@@ -57,6 +67,10 @@ export const normalizeMirrorConfig = (raw, cwd, configPath, options = {}) => {
     const gitCommit = optionalBoolean(raw.git?.commit, 'git.commit') === true;
     const gitPush = optionalBoolean(raw.git?.push, 'git.push') === true;
     const gitAllowDirty = optionalBoolean(raw.git?.allow_dirty, 'git.allow_dirty') === true;
+    const writeChangelog = optionalBoolean(raw.agents?.write_changelog, 'agents.write_changelog') !== false;
+    const changelogPath = optionalString(raw.agents?.changelog_path, 'agents.changelog_path') ?? 'CHANGELOG.md';
+    const autoAgentsMd = optionalBoolean(raw.agents?.auto_agents_md, 'agents.auto_agents_md') !== false;
+    const autoSkillInstall = optionalBoolean(raw.agents?.auto_skill_install, 'agents.auto_skill_install') !== false;
     return {
         schema: 1,
         cwd,
@@ -83,6 +97,12 @@ export const normalizeMirrorConfig = (raw, cwd, configPath, options = {}) => {
             push: options.push === true || gitPush,
             allowDirty: options.allowDirty === true || gitAllowDirty,
         },
+        agents: {
+            writeChangelog,
+            changelogPath,
+            autoAgentsMd,
+            autoSkillInstall,
+        },
     };
 };
 export const createInitConfig = (kind, cwd) => {
@@ -110,6 +130,12 @@ tag_template = "{name}@{version}"
 commit = false
 push = false
 allow_dirty = false
+
+[agents]
+write_changelog = true
+changelog_path = "CHANGELOG.md"
+auto_agents_md = true
+auto_skill_install = true
 `;
     }
     if (kind === 'jsr.json') {
@@ -132,6 +158,12 @@ tag_template = "{name}@{version}"
 commit = false
 push = false
 allow_dirty = false
+
+[agents]
+write_changelog = true
+changelog_path = "CHANGELOG.md"
+auto_agents_md = true
+auto_skill_install = true
 `;
     }
     return `schema = 1
@@ -150,13 +182,19 @@ tag_template = "v{version}"
 commit = false
 push = false
 allow_dirty = false
+
+[agents]
+write_changelog = true
+changelog_path = "CHANGELOG.md"
+auto_agents_md = true
+auto_skill_install = true
 `;
 };
 export const writeInitConfig = async (kind, cwd, overwrite = false) => {
     const path = join(cwd, 'mirror.config.toml');
     if (existsSync(path) && !overwrite)
         throw new MirrorError(`Configuration already exists: ${path}`);
-    await Bun.write(path, createInitConfig(kind, cwd));
+    await writeFile(path, createInitConfig(kind, cwd), 'utf8');
     return path;
 };
 export const configPathForDisplay = (config) => (config.configPath ? relativeFromCwd(config.cwd, config.configPath) : '(none)');