@guiho/mirror 3.0.0-alpha.4

package/source/guiho-mirror.ts

@@ -0,0 +1,44 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+
+export type {
+  MirrorAdapterName,
+  MirrorCliOptions,
+  MirrorConfig,
+  MirrorExecutionResult,
+  MirrorFormat,
+  MirrorRawConfig,
+  MirrorVersionPlan,
+  MirrorVersionPlanAction,
+  MirrorVersionTarget,
+} from './types'
+
+export { MirrorError, invariant } from './errors'
+export { parseMirrorCliOptions } from './flags'
+export { createInitConfig, discoverMirrorConfig, loadMirrorConfig, normalizeMirrorConfig, writeInitConfig } from './config'
+export { assertValidSemver, isMirrorReleaseTarget, mirrorReleaseTargets, resolveNextVersion, sortSemverDescending } from './version'
+export {
+  createGitCommit,
+  createGitTag,
+  ensureAdapterFiles,
+  assertSupportedGitTagTemplate,
+  isGitDirty,
+  isGitRepository,
+  readCurrentVersion,
+  readGitVersion,
+  readJsrName,
+  readJsrVersion,
+  readPackageName,
+  readPackageVersion,
+  renderGitTag,
+  resolveProjectName,
+  supportedGitTagTemplates,
+  versionFromTag,
+  writeJsrVersion,
+  writePackageVersion,
+} from './adapters'
+export { buildVersionPlan, releaseLabel, resolveFileOutputPaths, validateMirrorConfig } from './plan'
+export { applyVersionPlan, executeVersionPlan } from './executor'
+export { mirrorBanner, reportConfig, reportConfigSchema, reportExecution, reportExecutionSummary, reportPlan, reportValue } from './reporter'
+export { createMirrorCommand, runMirrorCli } from './cli'

package/source/plan.ts

@@ -0,0 +1,98 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+
+import { relative } from 'node:path'
+import type { MirrorCliOptions, MirrorConfig, MirrorVersionPlan, MirrorVersionPlanAction } from './types'
+import { MirrorError } from './errors'
+import { loadMirrorConfig, relativeFromCwd, resolveMirrorPath } from './config'
+import { ensureAdapterFiles, readCurrentVersion, renderGitTag, resolveProjectName } from './adapters'
+import { resolveNextVersion } from './version'
+
+export const validateMirrorConfig = async (options: MirrorCliOptions = {}): Promise<MirrorConfig> => {
+  const config = await loadMirrorConfig(options)
+  await ensureAdapterFiles(config)
+
+  const projectName = await resolveProjectName(config)
+
+  if (config.version.source === 'git' || config.version.output.includes('git')) {
+    renderGitTag(config.git.tagTemplate, '0.0.0', projectName)
+  }
+
+  return config
+}
+
+export const buildVersionPlan = async (target: string, options: MirrorCliOptions = {}): Promise<MirrorVersionPlan> => {
+  const config = await validateMirrorConfig(options)
+
+  const projectName = await resolveProjectName(config)
+  const currentVersion = await readCurrentVersion(config, projectName)
+  const nextVersion = resolveNextVersion(currentVersion, target, config.version.prereleaseId)
+  const fileOutputPaths = resolveFileOutputPaths(config)
+  const commitEnabled = config.git.commit
+  const pushEnabled = config.git.push
+  const actions: MirrorVersionPlanAction[] = []
+
+  for (const path of fileOutputPaths) {
+    actions.push({
+      type: 'write-file',
+      adapter: path.endsWith(config.package.path) ? 'package.json' : 'jsr.json',
+      path,
+      currentVersion,
+      nextVersion,
+    })
+  }
+
+  const gitTag = config.version.output.includes('git') ? renderGitTag(config.git.tagTemplate, nextVersion, projectName) : undefined
+
+  if (fileOutputPaths.length > 0 && gitTag && !commitEnabled && !pushEnabled) {
+    throw new MirrorError('Git tag output with file outputs requires --commit or --push so the tag points at the version commit.')
+  }
+
+  if (commitEnabled && fileOutputPaths.length > 0) {
+    actions.push({
+      type: 'git-commit',
+      message: releaseLabel(nextVersion, projectName),
+      paths: fileOutputPaths.map((path) => relative(config.cwd, path)),
+    })
+  }
+
+  if (gitTag) actions.push({ type: 'git-tag', tag: gitTag })
+
+  if (pushEnabled) {
+    actions.push({
+      type: 'git-push',
+      includeCommit: fileOutputPaths.length > 0,
+      includeTags: Boolean(gitTag),
+    })
+  }
+
+  return {
+    cwd: config.cwd,
+    configPath: config.configPath,
+    source: config.version.source,
+    output: config.version.output,
+    currentVersion,
+    nextVersion,
+    project: { name: projectName },
+    commitEnabled,
+    pushEnabled,
+    allowDirty: config.git.allowDirty,
+    fileOutputPaths,
+    gitTag,
+    actions,
+  }
+}
+
+export const resolveFileOutputPaths = (config: MirrorConfig) => {
+  const paths: string[] = []
+
+  if (config.version.output.includes('package.json')) paths.push(resolveMirrorPath(config.cwd, config.package.path))
+  if (config.version.output.includes('jsr.json')) paths.push(resolveMirrorPath(config.cwd, config.jsr.path))
+
+  return paths
+}
+
+export const releaseLabel = (version: string, projectName?: string) => (projectName ? `${projectName}@${version}` : `v${version}`)
+
+export const planPathForDisplay = (plan: MirrorVersionPlan, path: string) => relativeFromCwd(plan.cwd, path)

package/source/reporter.ts

@@ -0,0 +1,127 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+
+import type { MirrorConfig, MirrorExecutionResult, MirrorFormat, MirrorVersionPlan } from './types'
+import { configPathForDisplay, relativeFromCwd } from './config'
+
+export const mirrorBanner = (configPath?: string) => {
+  const noColor = process.env['NO_COLOR'] === '1'
+  const title = noColor ? '🪞  GUIHO Mirror' : '\x1b[1;36m🪞  GUIHO Mirror\x1b[0m'
+
+  if (configPath === undefined) return `\n${title}\n\n`
+
+  const dim = noColor ? '' : '\x1b[2m'
+  const reset = noColor ? '' : '\x1b[0m'
+  const status = configPath ? configPath : '(none)'
+
+  return `\n${title}\n\n${dim}config: ${status}${reset}\n\n`
+}
+
+export const reportValue = (value: unknown, format: MirrorFormat = 'text') => {
+  if (format === 'json') return `${JSON.stringify(value, null, 2)}\n`
+  return `${String(value)}\n`
+}
+
+export const reportConfig = (config: MirrorConfig, format: MirrorFormat = 'text') => {
+  if (format === 'json') return `${JSON.stringify(config, null, 2)}\n`
+
+  return [
+    `config: ${configPathForDisplay(config)}`,
+    `source: ${config.version.source}`,
+    `output: ${config.version.output.join(', ')}`,
+    `package: ${config.package.path}`,
+    `jsr: ${config.jsr.path}`,
+    `tag_template: ${config.git.tagTemplate}`,
+    `commit: ${String(config.git.commit)}`,
+    `push: ${String(config.git.push)}`,
+    `allow_dirty: ${String(config.git.allowDirty)}`,
+    '',
+  ].join('\n')
+}
+
+export const reportConfigSchema = (format: MirrorFormat = 'text') => {
+  if (format === 'json') {
+    return `${JSON.stringify({ schema: 'See text output for full reference.' }, null, 2)}\n`
+  }
+
+  return [
+    'MIRROR CONFIGURATION SCHEMA (mirror.config.toml)',
+    '',
+    '  schema = 1                                Required. Schema version. Must be 1.',
+    '',
+    '  [project]',
+    '  name = "<string>"                         Optional. Explicit project name.',
+    '  name_source = "package.json" | "jsr.json" Optional. Read project name from this adapter.',
+    '',
+    '  [version]',
+    '  scheme = "semver"                         Required. Only "semver" is supported.',
+    '  source = "package.json" | "jsr.json" | "git"  Required. Adapter to read the current version from.',
+    '  output = ["package.json", "jsr.json", "git"]  Required. Adapters to write the next version to.',
+    '  prerelease_id = "<string>"                Optional. Default prerelease identifier (e.g. "alpha").',
+    '',
+    '  [package]',
+    '  path = "<path>"                           Optional. Path to package.json. Default: "package.json".',
+    '',
+    '  [jsr]',
+    '  path = "<path>"                           Optional. Path to jsr.json. Default: "jsr.json".',
+    '',
+    '  [git]',
+    '  tag_template = "<template>"               Optional. Git tag format. Default: "v{version}".',
+    '                                            Supported: "v{version}", "{name}@{version}", "{name}/v{version}".',
+    '  commit = true | false                     Optional. Create release commits. Default: false.',
+    '  push = true | false                       Optional. Push release refs. Default: false.',
+    '  allow_dirty = true | false                Optional. Allow dirty Git worktree. Default: false.',
+    '',
+  ].join('\n')
+}
+
+export const reportPlan = (plan: MirrorVersionPlan, format: MirrorFormat = 'text') => {
+  if (format === 'json') return `${JSON.stringify(plan, null, 2)}\n`
+
+  const lines = [
+    `current: ${plan.currentVersion}`,
+    `next: ${plan.nextVersion}`,
+    `source: ${plan.source}`,
+    `output: ${plan.output.join(', ')}`,
+  ]
+
+  if (plan.project.name) lines.push(`project: ${plan.project.name}`)
+  if (plan.configPath) lines.push(`config: ${relativeFromCwd(plan.cwd, plan.configPath)}`)
+  if (plan.fileOutputPaths.length > 0) lines.push(`files: ${plan.fileOutputPaths.map((path) => relativeFromCwd(plan.cwd, path)).join(', ')}`)
+  if (plan.gitTag) lines.push(`tag: ${plan.gitTag}`)
+
+  lines.push('actions:')
+
+  for (const action of plan.actions) {
+    if (action.type === 'write-file') lines.push(`- write ${relativeFromCwd(plan.cwd, action.path)}: ${action.currentVersion} -> ${action.nextVersion}`)
+    if (action.type === 'git-commit') lines.push(`- commit ${action.message}`)
+    if (action.type === 'git-tag') lines.push(`- tag ${action.tag}`)
+    if (action.type === 'git-push') lines.push(`- push commit=${String(action.includeCommit)} tags=${String(action.includeTags)}`)
+  }
+
+  return `${lines.join('\n')}\n`
+}
+
+export const reportExecution = (result: MirrorExecutionResult, format: MirrorFormat = 'text') => {
+  if (format === 'json') return `${JSON.stringify(result, null, 2)}\n`
+  return `${reportPlan(result.plan, 'text')}applied: ${String(result.applied)}\ndry_run: ${String(result.dryRun)}\n`
+}
+
+export const reportExecutionSummary = (result: MirrorExecutionResult, format: MirrorFormat = 'text') => {
+  if (format === 'json') return `${JSON.stringify(result, null, 2)}\n`
+
+  const outputs = result.plan.output.join(', ')
+  const files = result.plan.fileOutputPaths.map((path) => relativeFromCwd(result.plan.cwd, path)).join(', ')
+  const lines = [
+    `applied: ${String(result.applied)}`,
+    `dry_run: ${String(result.dryRun)}`,
+    `version: ${result.plan.nextVersion}`,
+    `outputs: ${outputs}`,
+  ]
+
+  if (files) lines.push(`files: ${files}`)
+  if (result.plan.gitTag) lines.push(`tag: ${result.plan.gitTag}`)
+
+  return `${lines.join('\n')}\n`
+}

package/source/types.ts

@@ -0,0 +1,128 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+
+import type { ReleaseType } from 'semver'
+
+export type MirrorAdapterName = 'package.json' | 'jsr.json' | 'git'
+export type MirrorProjectNameSource = 'package.json' | 'jsr.json'
+export type MirrorFormat = 'text' | 'json'
+export type MirrorVersionTarget = ReleaseType | string
+export type MirrorJsonObject = Record<string, unknown>
+
+export type MirrorRawConfig = Partial<{
+  schema: number
+  project: Partial<{
+    name: string
+    name_source: MirrorProjectNameSource
+  }>
+  version: Partial<{
+    scheme: 'semver'
+    source: MirrorAdapterName
+    output: MirrorAdapterName[]
+    prerelease_id: string
+  }>
+  package: Partial<{ path: string }>
+  jsr: Partial<{ path: string }>
+  git: Partial<{
+    tag_template: string
+    commit: boolean
+    push: boolean
+    allow_dirty: boolean
+  }>
+}>
+
+export type MirrorConfig = {
+  schema: 1
+  cwd: string
+  configPath?: string
+  project: {
+    name?: string
+    nameSource?: MirrorProjectNameSource
+  }
+  version: {
+    scheme: 'semver'
+    source: MirrorAdapterName
+    output: MirrorAdapterName[]
+    prereleaseId: string
+  }
+  package: { path: string }
+  jsr: { path: string }
+  git: {
+    tagTemplate: string
+    commit: boolean
+    push: boolean
+    allowDirty: boolean
+  }
+}
+
+export type MirrorCliOptions = {
+  cwd?: string
+  config?: string
+  format?: MirrorFormat
+  noColor?: boolean
+  source?: MirrorAdapterName
+  output?: MirrorAdapterName[]
+  packageFile?: string
+  jsrFile?: string
+  preid?: string
+  dryRun?: boolean
+  commit?: boolean
+  push?: boolean
+  allowDirty?: boolean
+  yes?: boolean
+}
+
+export type MirrorConfigDiscovery = {
+  path?: string
+  raw?: MirrorRawConfig
+}
+
+export type MirrorProject = {
+  name?: string
+}
+
+export type MirrorVersionPlanAction =
+  | {
+      type: 'write-file'
+      adapter: 'package.json' | 'jsr.json'
+      path: string
+      currentVersion: string
+      nextVersion: string
+    }
+  | {
+      type: 'git-commit'
+      message: string
+      paths: string[]
+    }
+  | {
+      type: 'git-tag'
+      tag: string
+    }
+  | {
+      type: 'git-push'
+      includeCommit: boolean
+      includeTags: boolean
+    }
+
+export type MirrorVersionPlan = {
+  cwd: string
+  configPath?: string
+  source: MirrorAdapterName
+  output: MirrorAdapterName[]
+  currentVersion: string
+  nextVersion: string
+  project: MirrorProject
+  commitEnabled: boolean
+  pushEnabled: boolean
+  allowDirty: boolean
+  fileOutputPaths: string[]
+  gitTag?: string
+  actions: MirrorVersionPlanAction[]
+}
+
+export type MirrorExecutionResult = {
+  plan: MirrorVersionPlan
+  applied: boolean
+  dryRun: boolean
+}

package/source/version.ts

@@ -0,0 +1,39 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+
+import { inc, rcompare, valid as validSemver } from 'semver'
+import type { ReleaseType } from 'semver'
+import { MirrorError } from './errors'
+
+export const mirrorReleaseTargets = [
+  'major',
+  'premajor',
+  'minor',
+  'preminor',
+  'patch',
+  'prepatch',
+  'prerelease',
+] as const satisfies readonly ReleaseType[]
+
+export const isMirrorReleaseTarget = (target: string): target is ReleaseType =>
+  (mirrorReleaseTargets as readonly string[]).includes(target)
+
+export const assertValidSemver = (version: string, label: string) => {
+  if (!validSemver(version)) throw new MirrorError(`${label} is not a valid semantic version: ${version}`)
+}
+
+export const resolveNextVersion = (currentVersion: string, target: string, prereleaseId = '') => {
+  assertValidSemver(currentVersion, 'Current version')
+
+  if (validSemver(target)) return target
+  if (!isMirrorReleaseTarget(target)) throw new MirrorError(`Invalid version target: ${target}`)
+
+  const nextVersion = prereleaseId ? inc(currentVersion, target, prereleaseId) : inc(currentVersion, target)
+
+  if (!nextVersion) throw new MirrorError(`Failed to resolve next version from ${currentVersion} using ${target}`)
+
+  return nextVersion
+}
+
+export const sortSemverDescending = (versions: string[]) => [...versions].sort(rcompare)