@guiho/mirror 3.1.2 → 3.2.1

package/library/config.js

@@ -6,6 +6,8 @@ import { readFile, writeFile } from 'node:fs/promises';
 import { basename, isAbsolute, join, relative, resolve } from 'node:path';
 import { parse as parseToml } from 'smol-toml';
 import { MirrorError } from './errors.js';
+import { mirrorConfigSchemaReference } from './schema.js';
+import { normalizeHooksConfig } from './hooks.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));
@@ -62,6 +64,7 @@ export const normalizeMirrorConfig = (raw, cwd, configPath, options = {}) => {
     const projectName = optionalString(raw.project?.name, 'project.name');
     const prereleaseId = options.preid ?? optionalString(raw.version?.prerelease_id, 'version.prerelease_id') ?? '';
     const packagePath = options.packageFile ?? optionalString(raw.package?.path, 'package.path') ?? 'package.json';
+    const packageAuxiliaryPaths = assertStringArray(raw.package?.auxiliary_paths, 'package.auxiliary_paths');
     const jsrPath = options.jsrFile ?? optionalString(raw.jsr?.path, 'jsr.path') ?? 'jsr.json';
     const tagTemplate = optionalString(raw.git?.tag_template, 'git.tag_template') ?? 'v{version}';
     const gitCommit = optionalBoolean(raw.git?.commit, 'git.commit') === true;
@@ -71,6 +74,7 @@ export const normalizeMirrorConfig = (raw, cwd, configPath, options = {}) => {
     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;
+    const hooks = normalizeHooksConfig(raw.hooks);
     return {
         schema: 1,
         cwd,
@@ -87,6 +91,7 @@ export const normalizeMirrorConfig = (raw, cwd, configPath, options = {}) => {
         },
         package: {
             path: packagePath,
+            auxiliaryPaths: packageAuxiliaryPaths,
         },
         jsr: {
             path: jsrPath,
@@ -103,100 +108,93 @@ export const normalizeMirrorConfig = (raw, cwd, configPath, options = {}) => {
             autoAgentsMd,
             autoSkillInstall,
         },
+        hooks,
     };
 };
-export const createInitConfig = (kind, cwd) => {
-    const projectName = basename(cwd);
-    if (kind === 'package.json') {
-        return `schema = 1
-
-[project]
-name_source = "package.json"
-
-[version]
-scheme = "semver"
-source = "package.json"
-output = ["package.json"]
-prerelease_id = ""
-
-[package]
-path = "package.json"
-
-[jsr]
-path = "jsr.json"
-
-[git]
-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') {
-        return `schema = 1
-
-[project]
-name_source = "jsr.json"
-
-[version]
-scheme = "semver"
-source = "jsr.json"
-output = ["jsr.json"]
-prerelease_id = ""
-
-[jsr]
-path = "jsr.json"
-
-[git]
-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
-
-[project]
-name = "${projectName}"
-
-[version]
-scheme = "semver"
-source = "git"
-output = ["git"]
-prerelease_id = ""
-
-[git]
-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) => {
+export const defaultInitAnswersForSource = (kind, cwd) => ({
+    source: kind,
+    output: kind === 'git' ? ['git'] : [kind, 'git'],
+    packagePath: 'package.json',
+    auxiliaryPaths: [],
+    jsrPath: 'jsr.json',
+    name: kind === 'git' ? basename(cwd) : undefined,
+    prereleaseId: '',
+    tagTemplate: '{name}@{version}',
+    commit: kind !== 'git',
+    push: false,
+});
+export const generateInitConfig = (answers, cwd) => {
+    const lines = [];
+    lines.push(`#:schema ${mirrorConfigSchemaReference}`);
+    lines.push('');
+    lines.push('schema = 1');
+    lines.push('');
+    lines.push('[project]');
+    if (answers.source === 'package.json')
+        lines.push('name_source = "package.json"');
+    else if (answers.source === 'jsr.json')
+        lines.push('name_source = "jsr.json"');
+    else
+        lines.push(`name = "${answers.name ?? basename(cwd)}"`);
+    lines.push('');
+    lines.push('[version]');
+    lines.push('scheme = "semver"');
+    lines.push(`source = "${answers.source}"`);
+    lines.push(`output = [${answers.output.map((value) => `"${value}"`).join(', ')}]`);
+    lines.push(`prerelease_id = "${answers.prereleaseId}"`);
+    lines.push('');
+    lines.push('[package]');
+    lines.push(`path = "${answers.packagePath}"`);
+    lines.push(`auxiliary_paths = [${answers.auxiliaryPaths.map((value) => `"${value}"`).join(', ')}]`);
+    lines.push('');
+    lines.push('[jsr]');
+    lines.push(`path = "${answers.jsrPath}"`);
+    lines.push('');
+    lines.push('[git]');
+    lines.push(`tag_template = "${answers.tagTemplate}"`);
+    lines.push(`commit = ${String(answers.commit)}`);
+    lines.push(`push = ${String(answers.push)}`);
+    lines.push('allow_dirty = false');
+    lines.push('');
+    lines.push('[agents]');
+    lines.push('write_changelog = true');
+    lines.push('changelog_path = "CHANGELOG.md"');
+    lines.push('auto_agents_md = true');
+    lines.push('auto_skill_install = true');
+    return `${lines.join('\n')}\n`;
+};
+export const createInitConfig = (kind, cwd) => generateInitConfig(defaultInitAnswersForSource(kind, cwd), cwd);
+export const writeInitConfig = async (kind, cwd, overwrite = false) => writeInitConfigFromAnswers(defaultInitAnswersForSource(kind, cwd), cwd, overwrite);
+export const writeInitConfigFromAnswers = async (answers, cwd, overwrite = false) => {
     const path = join(cwd, 'mirror.config.toml');
-    if (existsSync(path) && !overwrite)
-        throw new MirrorError(`Configuration already exists: ${path}`);
-    await writeFile(path, createInitConfig(kind, cwd), 'utf8');
+    const generated = generateInitConfig(answers, cwd);
+    if (existsSync(path) && !overwrite) {
+        await writeFile(path, reconcileInitConfig(await readFile(path, 'utf8'), generated), 'utf8');
+        return path;
+    }
+    await writeFile(path, generated, 'utf8');
     return path;
 };
+export const reconcileInitConfig = (existingContent, defaultsContent) => {
+    const existingRaw = parseConfigContent(existingContent, 'existing configuration');
+    const defaultsRaw = parseConfigContent(defaultsContent, 'default configuration');
+    const additions = [];
+    for (const [sectionName, defaultSection] of Object.entries(defaultsRaw)) {
+        if (!isRecord(defaultSection))
+            continue;
+        const existingSection = existingRaw[sectionName];
+        if (!isRecord(existingSection)) {
+            additions.push(renderTomlSection(sectionName, defaultSection));
+            continue;
+        }
+        const missingValues = Object.fromEntries(Object.entries(defaultSection).filter(([key]) => existingSection[key] === undefined));
+        if (Object.keys(missingValues).length > 0)
+            existingContent = insertTomlValuesIntoSection(existingContent, sectionName, missingValues);
+    }
+    if (additions.length === 0)
+        return existingContent;
+    return `${existingContent.trimEnd()}\n\n${additions.join('\n\n')}\n`;
+};
 export const configPathForDisplay = (config) => (config.configPath ? relativeFromCwd(config.cwd, config.configPath) : '(none)');
 const assertAdapter = (value, key) => {
     if (typeof value !== 'string' || !adapters.has(value))
@@ -213,6 +211,17 @@ const assertOutput = (value) => {
         throw new MirrorError('Invalid or missing version.output. Expected at least one output adapter.');
     return value.map((item) => assertAdapter(item, 'version.output'));
 };
+const assertStringArray = (value, key) => {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new MirrorError(`Invalid ${key}. Expected an array of strings.`);
+    return value.map((item) => {
+        if (typeof item !== 'string' || item.length === 0)
+            throw new MirrorError(`Invalid ${key}. Expected an array of strings.`);
+        return item;
+    });
+};
 const dedupeAdapters = (value) => [...new Set(value)];
 const optionalString = (value, key) => {
     if (value === undefined)
@@ -229,3 +238,43 @@ const optionalBoolean = (value, key) => {
     return value;
 };
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const parseConfigContent = (content, label) => {
+    let parsed;
+    try {
+        parsed = parseToml(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new MirrorError(`Invalid TOML in ${label}:\n${message}`);
+    }
+    if (!isRecord(parsed))
+        throw new MirrorError(`Invalid ${label}. Expected a TOML object.`);
+    return parsed;
+};
+const renderTomlSection = (sectionName, values) => {
+    const lines = [`[${sectionName}]`];
+    for (const [key, value] of Object.entries(values)) {
+        lines.push(`${key} = ${renderTomlValue(value)}`);
+    }
+    return lines.join('\n');
+};
+const insertTomlValuesIntoSection = (content, sectionName, values) => {
+    const lines = content.split(/\r?\n/);
+    const sectionIndex = lines.findIndex((line) => line.trim() === `[${sectionName}]`);
+    if (sectionIndex === -1)
+        return `${content.trimEnd()}\n\n${renderTomlSection(sectionName, values)}\n`;
+    const nextSectionIndex = lines.findIndex((line, index) => index > sectionIndex && /^\[[^\]]+]\s*$/.test(line.trim()));
+    const insertIndex = nextSectionIndex === -1 ? lines.length : nextSectionIndex;
+    const renderedValues = Object.entries(values).map(([key, value]) => `${key} = ${renderTomlValue(value)}`);
+    lines.splice(insertIndex, 0, ...renderedValues);
+    return lines.join('\n');
+};
+const renderTomlValue = (value) => {
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (Array.isArray(value))
+        return `[${value.map(renderTomlValue).join(', ')}]`;
+    throw new MirrorError('Cannot render unsupported init configuration value.');
+};

package/library/executor.d.ts

@@ -1,7 +1,7 @@
 /**
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
-import type { MirrorCliOptions, MirrorExecutionResult } from './types.js';
+import type { MirrorCliOptions, MirrorExecutionResult, MirrorHooksConfig } from './types.js';
 export declare const applyVersionPlan: (target: string, options?: MirrorCliOptions) => Promise<MirrorExecutionResult>;
-export declare const executeVersionPlan: (plan: MirrorExecutionResult["plan"], options?: MirrorCliOptions) => Promise<MirrorExecutionResult>;
+export declare const executeVersionPlan: (plan: MirrorExecutionResult["plan"], options?: MirrorCliOptions, hooks?: MirrorHooksConfig, target?: string) => Promise<MirrorExecutionResult>;
 //# sourceMappingURL=executor.d.ts.map

package/library/executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../source/executor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAMzE,eAAO,MAAM,gBAAgB,GAAU,QAAQ,MAAM,EAAE,UAAS,gBAAqB,KAAG,OAAO,CAAC,qBAAqB,CAIpH,CAAA;AAED,eAAO,MAAM,kBAAkB,GAC7B,MAAM,qBAAqB,CAAC,MAAM,CAAC,EACnC,UAAS,gBAAqB,KAC7B,OAAO,CAAC,qBAAqB,CAmB/B,CAAA"}
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../source/executor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAM5F,eAAO,MAAM,gBAAgB,GAAU,QAAQ,MAAM,EAAE,UAAS,gBAAqB,KAAG,OAAO,CAAC,qBAAqB,CAIpH,CAAA;AAED,eAAO,MAAM,kBAAkB,GAC7B,MAAM,qBAAqB,CAAC,MAAM,CAAC,EACnC,UAAS,gBAAqB,EAC9B,QAAQ,iBAAiB,EACzB,eAAyB,KACxB,OAAO,CAAC,qBAAqB,CAoC/B,CAAA"}

package/library/executor.js

@@ -2,33 +2,47 @@
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
 import { MirrorError } from './errors.js';
-import { createGitCommit, createGitTag, isGitDirty, isGitRepository, pushGitRefs, writeJsrVersion, writePackageVersion } from './adapters.js';
-import { loadMirrorConfig } from './config.js';
+import { createGitCommit, createGitTag, isGitDirty, isGitRepository, pushGitRefs, writeJsrVersionFile, writePackageVersionFile } from './adapters.js';
 import { buildVersionPlan } from './plan.js';
+import { hookEnvForAction, runActionHooks } from './hooks.js';
 export const applyVersionPlan = async (target, options = {}) => {
     const plan = await buildVersionPlan(target, options);
     return executeVersionPlan(plan, options);
 };
-export const executeVersionPlan = async (plan, options = {}) => {
+export const executeVersionPlan = async (plan, options = {}, hooks, target = plan.nextVersion) => {
+    const hookResults = [];
     if (options.dryRun)
-        return { plan, applied: false, dryRun: true };
+        return { plan, applied: false, dryRun: true, hookResults };
     if (!plan.allowDirty && (await isGitRepository(plan.cwd)) && (await isGitDirty(plan.cwd))) {
         throw new MirrorError('Git worktree is dirty. Commit changes or pass --allow-dirty.');
     }
     if (!options.yes)
         throw new MirrorError('Refusing to apply without confirmation. Pass --yes to apply the plan.');
-    const config = await loadMirrorConfig(options);
-    if (config.version.output.includes('package.json'))
-        await writePackageVersion(config, plan.nextVersion);
-    if (config.version.output.includes('jsr.json'))
-        await writeJsrVersion(config, plan.nextVersion);
     for (const action of plan.actions) {
-        if (action.type === 'git-commit')
+        const actionEnv = hookEnvForAction(plan, target, action);
+        if (action.type === 'write-file') {
+            await runActionHooks('before:write', hooks?.['before:write'], actionEnv, plan.cwd, options);
+            if (action.adapter === 'package.json')
+                await writePackageVersionFile(action.path, plan.nextVersion);
+            if (action.adapter === 'jsr.json')
+                await writeJsrVersionFile(action.path, plan.nextVersion);
+            await runActionHooks('after:write', hooks?.['after:write'], actionEnv, plan.cwd, options);
+        }
+        if (action.type === 'git-commit') {
+            await runActionHooks('before:commit', hooks?.['before:commit'], actionEnv, plan.cwd, options);
             await createGitCommit(plan.cwd, action.paths, action.message);
-        if (action.type === 'git-tag')
+            await runActionHooks('after:commit', hooks?.['after:commit'], actionEnv, plan.cwd, options);
+        }
+        if (action.type === 'git-tag') {
+            await runActionHooks('before:tag', hooks?.['before:tag'], actionEnv, plan.cwd, options);
             await createGitTag(plan.cwd, action.tag);
-        if (action.type === 'git-push')
+            await runActionHooks('after:tag', hooks?.['after:tag'], actionEnv, plan.cwd, options);
+        }
+        if (action.type === 'git-push') {
+            await runActionHooks('before:push', hooks?.['before:push'], actionEnv, plan.cwd, options);
             await pushGitRefs(plan.cwd, action.includeCommit, action.includeTags);
+            await runActionHooks('after:push', hooks?.['after:push'], actionEnv, plan.cwd, options);
+        }
     }
-    return { plan, applied: true, dryRun: false };
+    return { plan, applied: true, dryRun: false, hookResults };
 };

package/library/flags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../source/flags.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAqB,gBAAgB,EAAgB,MAAM,YAAY,CAAA;AAenF,eAAO,MAAM,qBAAqB,GAAI,SAAS,MAAM,EAAE,KAAG,gBAuDzD,CAAA"}
+{"version":3,"file":"flags.d.ts","sourceRoot":"","sources":["../source/flags.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAqB,gBAAgB,EAAgB,MAAM,YAAY,CAAA;AAenF,eAAO,MAAM,qBAAqB,GAAI,SAAS,MAAM,EAAE,KAAG,gBAkEzD,CAAA"}

package/library/flags.js

@@ -2,7 +2,7 @@
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
 import { MirrorError } from './errors.js';
-const booleanFlags = new Set(['dry-run', 'commit', 'push', 'allow-dirty', 'yes', 'no-color', 'verbose', 'help', 'version']);
+const booleanFlags = new Set(['dry-run', 'commit', 'push', 'allow-dirty', 'non-interactive', 'yes', 'no-color', 'verbose', 'help', 'version']);
 const adapterNames = new Set(['package.json', 'jsr.json', 'git']);
 const shortFlagAliases = {
     '-dy': '--dry-run',
@@ -38,6 +38,12 @@ export const parseMirrorCliOptions = (rawArgs) => {
             parsed['output'] = [...(Array.isArray(current) ? current : current ? [String(current)] : []), ...nextValues];
             continue;
         }
+        if (key === 'auxiliary') {
+            const nextValues = value.split(',').map((item) => item.trim()).filter(Boolean);
+            const current = parsed['auxiliary'];
+            parsed['auxiliary'] = [...(Array.isArray(current) ? current : current ? [String(current)] : []), ...nextValues];
+            continue;
+        }
         parsed[key] = value;
     }
     return {
@@ -49,11 +55,15 @@ export const parseMirrorCliOptions = (rawArgs) => {
         output: Array.isArray(parsed['output']) ? parsed['output'].map((value) => assertAdapter(value, '--output')) : undefined,
         packageFile: typeof parsed['packageFile'] === 'string' ? parsed['packageFile'] : undefined,
         jsrFile: typeof parsed['jsrFile'] === 'string' ? parsed['jsrFile'] : undefined,
+        auxiliary: Array.isArray(parsed['auxiliary']) ? parsed['auxiliary'].map((value) => String(value)) : undefined,
+        tagTemplate: typeof parsed['tagTemplate'] === 'string' ? parsed['tagTemplate'] : undefined,
+        name: typeof parsed['name'] === 'string' ? parsed['name'] : undefined,
         preid: typeof parsed['preid'] === 'string' ? parsed['preid'] : undefined,
         dryRun: parsed['dryRun'] === true,
         commit: parsed['commit'] === true,
         push: parsed['push'] === true,
         allowDirty: parsed['allowDirty'] === true,
+        nonInteractive: parsed['nonInteractive'] === true,
         yes: parsed['yes'] === true,
         verbose: parsed['verbose'] === true,
     };

package/library/guiho-mirror.d.ts

@@ -1,15 +1,18 @@
 /**
  * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
  */
-export type { MirrorAdapterName, MirrorCliOptions, MirrorConfig, MirrorExecutionResult, MirrorFormat, MirrorAgentAutomationResult, MirrorAgentSettings, MirrorAgentsInstructionsResult, MirrorRawConfig, MirrorSkillInstallResult, MirrorSkillInstallScope, MirrorVersionPlan, MirrorVersionPlanAction, MirrorVersionTarget, } from './types.js';
+export type { MirrorAdapterName, MirrorCliOptions, MirrorConfig, MirrorExecutionResult, MirrorFormat, MirrorAgentAutomationResult, MirrorAgentSettings, MirrorAgentsInstructionsResult, MirrorHookCommand, MirrorHookName, MirrorHookResult, MirrorHooksConfig, MirrorInitAnswers, MirrorInitFlags, MirrorInitPrompter, MirrorRawConfig, MirrorSkillInstallResult, MirrorSkillInstallScope, MirrorVersionPlan, MirrorVersionPlanAction, MirrorVersionTarget, } from './types.js';
 export { MirrorError, invariant } from './errors.js';
 export { parseMirrorCliOptions } from './flags.js';
-export { defaultMirrorAgentSettings, ensureMirrorAgentsInstructions, findAgentsFile, installMirrorSkill, isMirrorSkillInstalled, mirrorAgentsSection, mirrorAgentsSectionHeading, mirrorSkillName, resolveMirrorAgentSettings, resolveMirrorSkillPath, runMirrorAgentAutomation, } from './agents.js';
-export { createInitConfig, discoverMirrorConfig, loadMirrorConfig, normalizeMirrorConfig, writeInitConfig } from './config.js';
+export { defaultMirrorAgentSettings, ensureMirrorAgentsInstructions, findAgentsFile, installMirrorSkill, isMirrorSkillInstalled, mirrorAgentsSection, mirrorAgentsSectionEndMarker, mirrorAgentsSectionHeading, mirrorAgentsSectionStartMarker, mirrorSkillName, resolveMirrorAgentSettings, resolveMirrorSkillPath, runMirrorAgentAutomation, } from './agents.js';
+export { createInitConfig, defaultInitAnswersForSource, discoverMirrorConfig, generateInitConfig, loadMirrorConfig, normalizeMirrorConfig, reconcileInitConfig, writeInitConfig, writeInitConfigFromAnswers, } from './config.js';
+export { createReadlineInitPrompter, isInteractiveInit, parseAdapterList, resolveInitAnswers } from './init.js';
+export { mirrorConfigJsonSchema, mirrorConfigSchemaReference, renderMirrorConfigJsonSchema } from './schema.js';
 export { assertValidSemver, isMirrorReleaseTarget, mirrorReleaseTargets, resolveNextVersion, sortSemverDescending } from './version.js';
-export { createGitCommit, createGitTag, ensureAdapterFiles, ensureGitAvailable, assertSupportedGitTagTemplate, isGitDirty, isGitRepository, readCurrentVersion, readGitVersion, readJsrName, readJsrVersion, readPackageName, readPackageVersion, renderGitTag, resolveProjectName, supportedGitTagTemplates, versionFromTag, writeJsrVersion, writePackageVersion, } from './adapters.js';
+export { createGitCommit, createGitTag, ensureAdapterFiles, ensureGitAvailable, assertSupportedGitTagTemplate, isGitDirty, isGitRepository, readCurrentVersion, readGitVersion, readJsrName, readJsrVersion, readJsrVersionFile, readPackageName, readPackageVersion, readPackageVersionFile, renderGitTag, resolveProjectName, supportedGitTagTemplates, versionFromTag, writeJsrVersion, writeJsrVersionFile, writePackageVersion, writePackageVersionFile, } from './adapters.js';
 export { buildVersionPlan, releaseLabel, resolveFileOutputPaths, validateMirrorConfig } from './plan.js';
 export { applyVersionPlan, executeVersionPlan } from './executor.js';
+export { hookEnvFromConfig, hookEnvForAction, hookEnvForPlan, hookEnvForResult, mirrorHookNames, normalizeHooksConfig, runHooks, runHooksQuiet, } from './hooks.js';
 export { mirrorBanner, reportAgentsInstructions, reportConfig, reportConfigSchema, reportExecution, reportExecutionSummary, reportPlan, reportSkillInstall, reportValue, } from './reporter.js';
 export { createMirrorCommand, runMirrorCli } from './cli.js';
 //# sourceMappingURL=guiho-mirror.d.ts.map

package/library/guiho-mirror.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guiho-mirror.d.ts","sourceRoot":"","sources":["../source/guiho-mirror.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,qBAAqB,EACrB,YAAY,EACZ,2BAA2B,EAC3B,mBAAmB,EACnB,8BAA8B,EAC9B,eAAe,EACf,wBAAwB,EACxB,uBAAuB,EACvB,iBAAiB,EACjB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAClD,OAAO,EACL,0BAA0B,EAC1B,8BAA8B,EAC9B,cAAc,EACd,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,0BAA0B,EAC1B,eAAe,EACf,0BAA0B,EAC1B,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC9H,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACvI,OAAO,EACL,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,6BAA6B,EAC7B,UAAU,EACV,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,EACd,eAAe,EACf,mBAAmB,GACpB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AACxG,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AACpE,OAAO,EACL,YAAY,EACZ,wBAAwB,EACxB,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,sBAAsB,EACtB,UAAU,EACV,kBAAkB,EAClB,WAAW,GACZ,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA"}
+{"version":3,"file":"guiho-mirror.d.ts","sourceRoot":"","sources":["../source/guiho-mirror.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,qBAAqB,EACrB,YAAY,EACZ,2BAA2B,EAC3B,mBAAmB,EACnB,8BAA8B,EAC9B,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,wBAAwB,EACxB,uBAAuB,EACvB,iBAAiB,EACjB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAClD,OAAO,EACL,0BAA0B,EAC1B,8BAA8B,EAC9B,cAAc,EACd,kBAAkB,EAClB,sBAAsB,EACtB,mBAAmB,EACnB,4BAA4B,EAC5B,0BAA0B,EAC1B,8BAA8B,EAC9B,eAAe,EACf,0BAA0B,EAC1B,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,0BAA0B,GAC3B,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,0BAA0B,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAC/G,OAAO,EAAE,sBAAsB,EAAE,2BAA2B,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAA;AAC/G,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACvI,OAAO,EACL,eAAe,EACf,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,6BAA6B,EAC7B,UAAU,EACV,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,kBAAkB,EAClB,sBAAsB,EACtB,YAAY,EACZ,kBAAkB,EAClB,wBAAwB,EACxB,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAA;AACxG,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AACpE,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,QAAQ,EACR,aAAa,GACd,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,YAAY,EACZ,wBAAwB,EACxB,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,sBAAsB,EACtB,UAAU,EACV,kBAAkB,EAClB,WAAW,GACZ,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA"}

package/library/guiho-mirror.js

@@ -3,11 +3,14 @@
  */
 export { MirrorError, invariant } from './errors.js';
 export { parseMirrorCliOptions } from './flags.js';
-export { defaultMirrorAgentSettings, ensureMirrorAgentsInstructions, findAgentsFile, installMirrorSkill, isMirrorSkillInstalled, mirrorAgentsSection, mirrorAgentsSectionHeading, mirrorSkillName, resolveMirrorAgentSettings, resolveMirrorSkillPath, runMirrorAgentAutomation, } from './agents.js';
-export { createInitConfig, discoverMirrorConfig, loadMirrorConfig, normalizeMirrorConfig, writeInitConfig } from './config.js';
+export { defaultMirrorAgentSettings, ensureMirrorAgentsInstructions, findAgentsFile, installMirrorSkill, isMirrorSkillInstalled, mirrorAgentsSection, mirrorAgentsSectionEndMarker, mirrorAgentsSectionHeading, mirrorAgentsSectionStartMarker, mirrorSkillName, resolveMirrorAgentSettings, resolveMirrorSkillPath, runMirrorAgentAutomation, } from './agents.js';
+export { createInitConfig, defaultInitAnswersForSource, discoverMirrorConfig, generateInitConfig, loadMirrorConfig, normalizeMirrorConfig, reconcileInitConfig, writeInitConfig, writeInitConfigFromAnswers, } from './config.js';
+export { createReadlineInitPrompter, isInteractiveInit, parseAdapterList, resolveInitAnswers } from './init.js';
+export { mirrorConfigJsonSchema, mirrorConfigSchemaReference, renderMirrorConfigJsonSchema } from './schema.js';
 export { assertValidSemver, isMirrorReleaseTarget, mirrorReleaseTargets, resolveNextVersion, sortSemverDescending } from './version.js';
-export { createGitCommit, createGitTag, ensureAdapterFiles, ensureGitAvailable, assertSupportedGitTagTemplate, isGitDirty, isGitRepository, readCurrentVersion, readGitVersion, readJsrName, readJsrVersion, readPackageName, readPackageVersion, renderGitTag, resolveProjectName, supportedGitTagTemplates, versionFromTag, writeJsrVersion, writePackageVersion, } from './adapters.js';
+export { createGitCommit, createGitTag, ensureAdapterFiles, ensureGitAvailable, assertSupportedGitTagTemplate, isGitDirty, isGitRepository, readCurrentVersion, readGitVersion, readJsrName, readJsrVersion, readJsrVersionFile, readPackageName, readPackageVersion, readPackageVersionFile, renderGitTag, resolveProjectName, supportedGitTagTemplates, versionFromTag, writeJsrVersion, writeJsrVersionFile, writePackageVersion, writePackageVersionFile, } from './adapters.js';
 export { buildVersionPlan, releaseLabel, resolveFileOutputPaths, validateMirrorConfig } from './plan.js';
 export { applyVersionPlan, executeVersionPlan } from './executor.js';
+export { hookEnvFromConfig, hookEnvForAction, hookEnvForPlan, hookEnvForResult, mirrorHookNames, normalizeHooksConfig, runHooks, runHooksQuiet, } from './hooks.js';
 export { mirrorBanner, reportAgentsInstructions, reportConfig, reportConfigSchema, reportExecution, reportExecutionSummary, reportPlan, reportSkillInstall, reportValue, } from './reporter.js';
 export { createMirrorCommand, runMirrorCli } from './cli.js';

package/library/hooks.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { MirrorCliOptions, MirrorConfig, MirrorHookCommand, MirrorHookName, MirrorHookResult, MirrorHooksConfig, MirrorVersionPlan, MirrorVersionPlanAction } from './types.js';
+export declare const mirrorHookNames: MirrorHookName[];
+export declare const normalizeHooksConfig: (raw: Record<string, MirrorHookCommand> | undefined) => MirrorHooksConfig;
+export declare const runHooks: (name: MirrorHookName, commands: string[] | undefined, env: Record<string, string>, cwd: string) => Promise<MirrorHookResult | undefined>;
+export declare const runHooksQuiet: (name: MirrorHookName, commands: string[] | undefined, env: Record<string, string>, cwd: string, results: MirrorHookResult[]) => Promise<void>;
+export declare const runActionHooks: (name: MirrorHookName, commands: string[] | undefined, env: Record<string, string>, cwd: string, options: MirrorCliOptions) => Promise<MirrorHookResult | undefined>;
+export declare const hookEnvFromConfig: (config: MirrorConfig, target: string) => Record<string, string>;
+export declare const hookEnvForPlan: (plan: MirrorVersionPlan, target: string) => Record<string, string>;
+export declare const hookEnvForAction: (plan: MirrorVersionPlan, target: string, action: MirrorVersionPlanAction) => Record<string, string>;
+export declare const hookEnvForResult: (plan: MirrorVersionPlan, target: string, applied: boolean, dryRun: boolean) => Record<string, string>;
+//# sourceMappingURL=hooks.d.ts.map

package/library/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../source/hooks.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA;AAUpL,eAAO,MAAM,eAAe,EAAE,cAAc,EAQ3C,CAAA;AAID,eAAO,MAAM,oBAAoB,GAAI,KAAK,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,SAAS,KAAG,iBAezF,CAAA;AAED,eAAO,MAAM,QAAQ,GACnB,MAAM,cAAc,EACpB,UAAU,MAAM,EAAE,GAAG,SAAS,EAC9B,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC3B,KAAK,MAAM,KACV,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAwBtC,CAAA;AAED,eAAO,MAAM,aAAa,GACxB,MAAM,cAAc,EACpB,UAAU,MAAM,EAAE,GAAG,SAAS,EAC9B,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC3B,KAAK,MAAM,EACX,SAAS,gBAAgB,EAAE,KAC1B,OAAO,CAAC,IAAI,CAUd,CAAA;AAED,eAAO,MAAM,cAAc,GACzB,MAAM,cAAc,EACpB,UAAU,MAAM,EAAE,GAAG,SAAS,EAC9B,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC3B,KAAK,MAAM,EACX,SAAS,gBAAgB,KACxB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAItC,CAAA;AAED,eAAO,MAAM,iBAAiB,GAAI,QAAQ,YAAY,EAAE,QAAQ,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAM5F,CAAA;AAEF,eAAO,MAAM,cAAc,GAAI,MAAM,iBAAiB,EAAE,QAAQ,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAa5F,CAAA;AAEF,eAAO,MAAM,gBAAgB,GAAI,MAAM,iBAAiB,EAAE,QAAQ,MAAM,EAAE,QAAQ,uBAAuB,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAwBhI,CAAA;AAED,eAAO,MAAM,gBAAgB,GAAI,MAAM,iBAAiB,EAAE,QAAQ,MAAM,EAAE,SAAS,OAAO,EAAE,QAAQ,OAAO,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAIjI,CAAA"}

package/library/hooks.js

@@ -0,0 +1,122 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import { MirrorError } from './errors.js';
+const execAsync = (command, options) => promisify(exec)(command, {
+    cwd: options.cwd,
+    env: { ...process.env, ...options.env },
+    maxBuffer: 10 * 1024 * 1024,
+});
+export const mirrorHookNames = [
+    'before:everything', 'after:everything',
+    'before:plan', 'after:plan',
+    'before:apply', 'after:apply',
+    'before:write', 'after:write',
+    'before:commit', 'after:commit',
+    'before:tag', 'after:tag',
+    'before:push', 'after:push',
+];
+const hookNameSet = new Set(mirrorHookNames);
+export const normalizeHooksConfig = (raw) => {
+    if (!raw || typeof raw !== 'object')
+        return {};
+    const config = {};
+    for (const [key, value] of Object.entries(raw)) {
+        const name = key.replaceAll('_', ':');
+        if (!hookNameSet.has(name))
+            continue;
+        const commands = typeof value === 'string' ? [value] : value;
+        config[name] = commands;
+    }
+    return config;
+};
+export const runHooks = async (name, commands, env, cwd) => {
+    if (!commands || commands.length === 0)
+        return undefined;
+    const start = Date.now();
+    for (let i = 0; i < commands.length; i++) {
+        const command = commands[i];
+        if (!command)
+            continue;
+        try {
+            await execAsync(command, { cwd, env });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const exitCode = typeof error['code'] === 'number' ? error['code'] : 1;
+            throw new MirrorError(`Hook '${name}' failed (exit code ${exitCode}): ${command}\n${message}`, Number(exitCode));
+        }
+    }
+    return {
+        name,
+        commands,
+        status: 'success',
+        durationMs: Date.now() - start,
+        exitCode: 0,
+    };
+};
+export const runHooksQuiet = async (name, commands, env, cwd, results) => {
+    if (!commands || commands.length === 0)
+        return;
+    try {
+        await runHooks(name, commands, env, cwd);
+        results.push({ name, commands, status: 'success', durationMs: 0, exitCode: 0 });
+    }
+    catch (error) {
+        const exitCode = error instanceof MirrorError ? error.exitCode ?? 1 : 1;
+        results.push({ name, commands, status: 'failure', durationMs: 0, exitCode, stderr: error instanceof Error ? error.message : String(error) });
+    }
+};
+export const runActionHooks = async (name, commands, env, cwd, options) => {
+    if (options.dryRun || !commands || commands.length === 0)
+        return undefined;
+    return runHooks(name, commands, env, cwd);
+};
+export const hookEnvFromConfig = (config, target) => ({
+    MIRROR_CWD: config.cwd,
+    MIRROR_CONFIG_PATH: config.configPath ?? '',
+    MIRROR_SOURCE: config.version.source,
+    MIRROR_OUTPUT: config.version.output.join(','),
+    MIRROR_TARGET: target,
+});
+export const hookEnvForPlan = (plan, target) => ({
+    MIRROR_CWD: plan.cwd,
+    MIRROR_CONFIG_PATH: plan.configPath ?? '',
+    MIRROR_SOURCE: plan.source,
+    MIRROR_OUTPUT: plan.output.join(','),
+    MIRROR_TARGET: target,
+    MIRROR_CURRENT: plan.currentVersion,
+    MIRROR_NEXT: plan.nextVersion,
+    MIRROR_PROJECT_NAME: plan.project.name ?? '',
+    MIRROR_GIT_TAG: plan.gitTag ?? '',
+    MIRROR_FILE_PATHS: plan.fileOutputPaths.join(','),
+    MIRROR_COMMIT_ENABLED: String(plan.commitEnabled),
+    MIRROR_PUSH_ENABLED: String(plan.pushEnabled),
+});
+export const hookEnvForAction = (plan, target, action) => {
+    const env = hookEnvForPlan(plan, target);
+    if (action.type === 'write-file') {
+        env['MIRROR_FILE_PATH'] = action.path;
+        env['MIRROR_FILE_CURRENT'] = action.currentVersion;
+        env['MIRROR_FILE_NEXT'] = action.nextVersion;
+    }
+    if (action.type === 'git-commit') {
+        env['MIRROR_COMMIT_MSG'] = action.message;
+        env['MIRROR_COMMIT_PATHS'] = action.paths.join(' ');
+    }
+    if (action.type === 'git-tag') {
+        env['MIRROR_TAG'] = action.tag;
+    }
+    if (action.type === 'git-push') {
+        env['MIRROR_INCLUDE_COMMIT'] = String(action.includeCommit);
+        env['MIRROR_INCLUDE_TAGS'] = String(action.includeTags);
+    }
+    return env;
+};
+export const hookEnvForResult = (plan, target, applied, dryRun) => ({
+    ...hookEnvForPlan(plan, target),
+    MIRROR_APPLIED: String(applied),
+    MIRROR_DRY_RUN: String(dryRun),
+});

package/library/init.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+import type { MirrorAdapterName, MirrorInitAnswers, MirrorInitFlags, MirrorInitPrompter } from './types.js';
+export declare const parseAdapterList: (value: string) => MirrorAdapterName[];
+export declare const resolveInitAnswers: (flags: MirrorInitFlags, cwd: string, prompter?: MirrorInitPrompter) => Promise<MirrorInitAnswers>;
+export declare const isInteractiveInit: (options: {
+    yes?: boolean;
+    nonInteractive?: boolean;
+}) => boolean;
+export declare const createReadlineInitPrompter: () => MirrorInitPrompter;
+//# sourceMappingURL=init.d.ts.map

package/library/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../source/init.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAI3G,eAAO,MAAM,gBAAgB,GAAI,OAAO,MAAM,KAAG,iBAAiB,EAQjE,CAAA;AAQD,eAAO,MAAM,kBAAkB,GAC7B,OAAO,eAAe,EACtB,KAAK,MAAM,EACX,WAAW,kBAAkB,KAC5B,OAAO,CAAC,iBAAiB,CAkD3B,CAAA;AAED,eAAO,MAAM,iBAAiB,GAAI,SAAS;IAAE,GAAG,CAAC,EAAE,OAAO,CAAC;IAAC,cAAc,CAAC,EAAE,OAAO,CAAA;CAAE,YACG,CAAA;AAEzF,eAAO,MAAM,0BAA0B,QAAO,kBAmB7C,CAAA"}