@guiho/mirror 3.0.0-alpha.4

package/source/adapters.ts

@@ -0,0 +1,176 @@
+/**
+ * @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 type { MirrorConfig, MirrorJsonObject } from './types'
+import { MirrorError } from './errors'
+import { assertValidSemver, sortSemverDescending } from './version'
+import { resolveMirrorPath } from './config'
+
+export const supportedGitTagTemplates = ['v{version}', '{name}@{version}', '{name}/v{version}'] as const
+
+export const readPackageJson = async (path: string): Promise<MirrorJsonObject> => readJsonObject(path, 'package.json')
+export const readJsrJson = async (path: string): Promise<MirrorJsonObject> => readJsonObject(path, 'jsr.json')
+
+export const writeJsonObject = async (path: string, object: MirrorJsonObject) => {
+  await Bun.write(path, `${JSON.stringify(object, null, 2)}\n`)
+}
+
+export const readPackageVersion = async (config: MirrorConfig) => readVersionField(resolveMirrorPath(config.cwd, config.package.path), 'package.json')
+export const readJsrVersion = async (config: MirrorConfig) => readVersionField(resolveMirrorPath(config.cwd, config.jsr.path), 'jsr.json')
+export const readPackageName = async (config: MirrorConfig) => readNameField(resolveMirrorPath(config.cwd, config.package.path), 'package.json')
+export const readJsrName = async (config: MirrorConfig) => readNameField(resolveMirrorPath(config.cwd, config.jsr.path), 'jsr.json')
+
+export const writePackageVersion = async (config: MirrorConfig, nextVersion: string) =>
+  writeVersionField(resolveMirrorPath(config.cwd, config.package.path), 'package.json', nextVersion)
+
+export const writeJsrVersion = async (config: MirrorConfig, nextVersion: string) =>
+  writeVersionField(resolveMirrorPath(config.cwd, config.jsr.path), 'jsr.json', nextVersion)
+
+export const ensureAdapterFiles = async (config: MirrorConfig) => {
+  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: MirrorConfig) => {
+  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: MirrorConfig, projectName?: string) => {
+  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: MirrorConfig, projectName?: string) => {
+  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): version is string => 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: string, version: string, projectName?: string) => {
+  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: string, tag: string, projectName?: string) => {
+  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: string) => {
+  if (!(supportedGitTagTemplates as readonly string[]).includes(template)) {
+    throw new MirrorError(`Unsupported Git tag template: ${template}. Expected v{version}, {name}@{version}, or {name}/v{version}.`)
+  }
+}
+
+export const isGitRepository = async (cwd: string) => {
+  try {
+    await $`git -C ${cwd} rev-parse --is-inside-work-tree`.quiet()
+    return true
+  } catch {
+    return false
+  }
+}
+
+export const isGitDirty = async (cwd: string) => {
+  const output = await $`git -C ${cwd} status --porcelain`.quiet().text()
+  return output.trim().length > 0
+}
+
+export const createGitCommit = async (cwd: string, paths: string[], message: string) => {
+  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: string, tag: string) => {
+  await $`git -C ${cwd} tag ${tag} -m ${`Release ${tag}`}`.quiet()
+}
+
+export const pushGitRefs = async (cwd: string, includeCommit: boolean, includeTags: boolean) => {
+  if (includeCommit) await $`git -C ${cwd} push`.quiet()
+  if (includeTags) await $`git -C ${cwd} push --tags`.quiet()
+}
+
+const readJsonObject = async (path: string, label: string): Promise<MirrorJsonObject> => {
+  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 as MirrorJsonObject
+}
+
+const readVersionField = async (path: string, label: string): Promise<string> => {
+  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: string, label: string): Promise<string> => {
+  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: string, label: string, nextVersion: string) => {
+  const json = await readJsonObject(path, label)
+  json['version'] = nextVersion
+  await writeJsonObject(path, json)
+}
+
+const ensureFile = (path: string, label: string) => {
+  if (!existsSync(path)) throw new MirrorError(`${label} file not found: ${path}`)
+}
+
+const ensureGitRepository = async (cwd: string) => {
+  if (!(await isGitRepository(cwd))) throw new MirrorError(`Not a Git repository: ${cwd}`)
+}
+
+const usesAdapter = (config: MirrorConfig, adapter: 'package.json' | 'jsr.json' | 'git') =>
+  config.version.source === adapter || config.version.output.includes(adapter)
+
+const escapeRegex = (value: string) => value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')

package/source/cli.ts

@@ -0,0 +1,285 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+
+import { defineCommand, runMain } from 'citty'
+import type { ArgsDef } 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 type { MirrorAdapterName, MirrorCliOptions } from './types'
+import { resolveNextVersion } from './version'
+
+const mirrorVersion = readInstalledVersion()
+
+const globalArgs = {
+  config: { type: 'string', description: 'Path to mirror.config.toml' },
+  cwd: { type: 'string', description: 'Run as if Mirror started in this directory' },
+  format: { type: 'enum', options: ['text', 'json'], default: 'text', description: 'Output format' },
+  'no-color': { type: 'boolean', description: 'Disable color output' },
+} satisfies ArgsDef
+
+const overrideArgs = {
+  ...globalArgs,
+  source: { type: 'enum', options: ['package.json', 'jsr.json', 'git'], description: 'Override version source' },
+  output: { type: 'string', description: 'Override version output. Repeat or comma-separate values.' },
+  'package-file': { type: 'string', description: 'Override package.json path' },
+  'jsr-file': { type: 'string', description: 'Override jsr.json path' },
+  preid: { type: 'string', description: 'Override prerelease identifier' },
+} satisfies ArgsDef
+
+const applyArgs = {
+  ...overrideArgs,
+  'dry-run': { type: 'boolean', alias: 'dy', description: 'Build and print the plan without applying it' },
+  commit: { type: 'boolean', description: 'Create a release commit when file outputs changed' },
+  push: { type: 'boolean', description: 'Create the release commit when needed, then push release refs' },
+  'allow-dirty': { type: 'boolean', description: 'Allow release in a dirty Git worktree' },
+  yes: { type: 'boolean', alias: 'y', description: 'Apply without interactive confirmation' },
+} satisfies ArgsDef
+
+const targetArg = {
+  target: { type: 'positional', description: 'Release target or exact semantic version', required: true },
+} satisfies ArgsDef
+
+export const createMirrorCommand = () =>
+  defineCommand({
+    meta: {
+      name: 'mirror',
+      version: mirrorVersion,
+      description: 'Open source project versioning for Bun, npm, JSR, and Git.',
+    },
+    args: globalArgs,
+    subCommands: {
+      init: createInitCommand(),
+      config: createConfigCommand(),
+      version: createVersionCommand(),
+    },
+  })
+
+export const runMirrorCli = async (rawArgs = process.argv.slice(2)) => {
+  const effectiveArgs = rawArgs.length === 0 ? ['--help'] : rawArgs
+  const restoreColorOutput = effectiveArgs.includes('--no-color') ? stripColorFromProcessOutput() : () => {}
+
+  try {
+    if (effectiveArgs.includes('--no-color')) process.env['NO_COLOR'] = '1'
+
+    if (effectiveArgs.includes('--help')) {
+      const parsed = parseMirrorCliOptions(effectiveArgs)
+      const cwd = resolve(parsed.cwd ?? process.cwd())
+      const discovery = await discoverMirrorConfig(cwd, parsed.config)
+      const configDisplay = discovery.path ? relativeFromCwd(cwd, discovery.path) : ''
+      process.stdout.write(mirrorBanner(configDisplay))
+    }
+
+    if (rawArgs.length === 0) {
+      process.on('exit', () => {
+        process.stdout.write([
+          'EXAMPLES',
+          '',
+          '  mirror version current                 # Print the current version',
+          '  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 config schema                   # Print the configuration file reference',
+          '',
+        ].join('\n') + '\n')
+      })
+    }
+
+    await runMain(createMirrorCommand(), { rawArgs: effectiveArgs })
+  } catch (error) {
+    if (error instanceof MirrorError) {
+      console.error(error.message)
+      process.exit(error.exitCode)
+    }
+
+    throw error
+  } finally {
+    restoreColorOutput()
+  }
+}
+
+const createInitCommand = () =>
+  defineCommand({
+    meta: { name: 'init', description: 'Create a Mirror configuration file.' },
+    subCommands: {
+      'package.json': createInitKindCommand('package.json'),
+      'jsr.json': createInitKindCommand('jsr.json'),
+      git: createInitKindCommand('git'),
+    },
+  })
+
+const createInitKindCommand = (kind: MirrorAdapterName) =>
+  defineCommand({
+    meta: { name: kind, description: `Create ${kind} project configuration.` },
+    args: {
+      ...globalArgs,
+      yes: { type: 'boolean', description: 'Overwrite existing mirror.config.toml' },
+    },
+    async run(context) {
+      const options = cliOptions(context.rawArgs, context.args)
+      const path = await writeInitConfig(kind, options.cwd ?? process.cwd(), Boolean(options.yes))
+      process.stdout.write(reportValue(`created ${path}`, options.format))
+    },
+  })
+
+const createConfigCommand = () =>
+  defineCommand({
+    meta: { name: 'config', description: 'Inspect and validate Mirror configuration.' },
+    subCommands: {
+      show: defineCommand({
+        meta: { name: 'show', description: 'Print the resolved configuration.' },
+        args: overrideArgs,
+        async run(context) {
+          const options = cliOptions(context.rawArgs, context.args)
+          const config = await loadMirrorConfig(options)
+          if (options.format !== 'json') process.stdout.write(mirrorBanner(configPathForDisplay(config)))
+          process.stdout.write(reportConfig(config, options.format))
+        },
+      }),
+      check: defineCommand({
+        meta: { name: 'check', description: 'Validate the resolved configuration.' },
+        args: overrideArgs,
+        async run(context) {
+          const options = cliOptions(context.rawArgs, context.args)
+          await validateMirrorConfig(options)
+          process.stdout.write(reportValue('ok', options.format))
+        },
+      }),
+      schema: defineCommand({
+        meta: { name: 'schema', description: 'Print the configuration file reference.' },
+        args: globalArgs,
+        run(context) {
+          const options = cliOptions(context.rawArgs, context.args)
+          if (options.format !== 'json') process.stdout.write(mirrorBanner())
+          process.stdout.write(reportConfigSchema(options.format))
+        },
+      }),
+    },
+  })
+
+const createVersionCommand = () =>
+  defineCommand({
+    meta: { name: 'version', description: 'Read, plan, and apply version changes.' },
+    subCommands: {
+      current: defineCommand({
+        meta: { name: 'current', description: 'Print the current project version.' },
+        args: overrideArgs,
+        async run(context) {
+          const options = cliOptions(context.rawArgs, context.args)
+          const config = await loadMirrorConfig(options)
+          const projectName = await resolveProjectName(config)
+          process.stdout.write(reportValue(await readCurrentVersion(config, projectName), options.format))
+        },
+      }),
+      next: defineCommand({
+        meta: { name: 'next', description: 'Print the next version without checking outputs.' },
+        args: { ...overrideArgs, ...targetArg },
+        async run(context) {
+          const options = cliOptions(context.rawArgs, context.args)
+          const config = await loadMirrorConfig(options)
+          const projectName = await resolveProjectName(config)
+          const currentVersion = await readCurrentVersion(config, projectName)
+          process.stdout.write(reportValue(resolveNextVersion(currentVersion, String(context.args['target']), config.version.prereleaseId), options.format))
+        },
+      }),
+      plan: defineCommand({
+        meta: { name: 'plan', description: 'Print the release plan without writing anything.' },
+        args: { ...overrideArgs, ...targetArg },
+        async run(context) {
+          const options = cliOptions(context.rawArgs, context.args)
+          const plan = await buildVersionPlan(String(context.args['target']), options)
+          if (options.format !== 'json') process.stdout.write(mirrorBanner(plan.configPath ? plan.configPath : ''))
+          process.stdout.write(reportPlan(plan, options.format))
+        },
+      }),
+      apply: defineCommand({
+        meta: { name: 'apply', description: 'Apply the release plan.' },
+        args: { ...applyArgs, ...targetArg },
+        async run(context) {
+          const options = cliOptions(context.rawArgs, context.args)
+          const plan = await buildVersionPlan(String(context.args['target']), options)
+
+          if (options.format !== 'json') process.stdout.write(mirrorBanner(plan.configPath ? plan.configPath : ''))
+          if (options.format !== 'json') process.stdout.write(reportPlan(plan, options.format))
+
+          const result = await executeVersionPlan(plan, options)
+          process.stdout.write(options.format === 'json' ? reportExecution(result, options.format) : reportExecutionSummary(result, options.format))
+        },
+      }),
+    },
+  })
+
+const cliOptions = (rawArgs: string[], args: Record<string, unknown>): MirrorCliOptions => {
+  const parsed = parseMirrorCliOptions(rawArgs)
+
+  return {
+    ...parsed,
+    config: parsed.config ?? stringArg(args['config']),
+    cwd: parsed.cwd ?? stringArg(args['cwd']),
+    format: parsed.format ?? (args['format'] === 'json' ? 'json' : 'text'),
+    source: parsed.source ?? adapterArg(args['source']),
+    output: parsed.output ?? outputArg(args['output']),
+    packageFile: parsed.packageFile ?? stringArg(args['packageFile']),
+    jsrFile: parsed.jsrFile ?? stringArg(args['jsrFile']),
+    preid: parsed.preid ?? stringArg(args['preid']),
+    dryRun: parsed.dryRun || args['dryRun'] === true,
+    commit: parsed.commit || args['commit'] === true,
+    push: parsed.push || args['push'] === true,
+    allowDirty: parsed.allowDirty || args['allowDirty'] === true,
+    yes: parsed.yes || args['yes'] === true,
+  }
+}
+
+const stringArg = (value: unknown) => (typeof value === 'string' ? value : undefined)
+
+const adapterArg = (value: unknown) => {
+  if (value === 'package.json' || value === 'jsr.json' || value === 'git') return value
+  return undefined
+}
+
+const outputArg = (value: unknown): MirrorCliOptions['output'] => {
+  if (typeof value !== 'string') return undefined
+
+  const values = value.split(',').map((item) => item.trim()).filter(Boolean)
+
+  if (values.length === 0) return undefined
+
+  return values.map((item) => {
+    const adapter = adapterArg(item)
+    if (!adapter) throw new MirrorError(`Invalid --output value: ${item}`)
+    return adapter
+  })
+}
+
+function readInstalledVersion() {
+  try {
+    const packageJson = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as Record<string, unknown>
+    return typeof packageJson['version'] === 'string' ? packageJson['version'] : '0.0.0'
+  } catch {
+    return '0.0.0'
+  }
+}
+
+const stripAnsi = (value: string) => value.replace(/\u001B\[[0-?]*[ -/]*[@-~]/g, '')
+
+const stripColorFromProcessOutput = () => {
+  const originalLog = console.log
+  const originalError = console.error
+
+  console.log = (...values: unknown[]) => originalLog(...values.map(stripAnsiValue))
+  console.error = (...values: unknown[]) => originalError(...values.map(stripAnsiValue))
+
+  return () => {
+    console.log = originalLog
+    console.error = originalError
+  }
+}
+
+const stripAnsiValue = (value: unknown) => (typeof value === 'string' ? stripAnsi(value) : value)

package/source/config.ts

@@ -0,0 +1,224 @@
+/**
+ * @copyright Copyright (c) 2026 GUIHO Technologies as represented by Cristóvão GUIHO. All Rights Reserved.
+ */
+
+import { existsSync } from 'node:fs'
+import { basename, isAbsolute, join, relative, resolve } from 'node:path'
+import type {
+  MirrorAdapterName,
+  MirrorCliOptions,
+  MirrorConfig,
+  MirrorConfigDiscovery,
+  MirrorProjectNameSource,
+  MirrorRawConfig,
+} from './types'
+import { MirrorError } from './errors'
+
+const adapters = new Set(['package.json', 'jsr.json', 'git'])
+const projectNameSources = new Set(['package.json', 'jsr.json'])
+
+export const resolveMirrorPath = (cwd: string, path: string) => (isAbsolute(path) ? path : resolve(cwd, path))
+
+export const relativeFromCwd = (cwd: string, path: string) => {
+  const relativePath = relative(cwd, resolveMirrorPath(cwd, path))
+  return relativePath || '.'
+}
+
+export const discoverMirrorConfig = async (cwd: string, explicitPath?: string): Promise<MirrorConfigDiscovery> => {
+  if (explicitPath) {
+    const configPath = resolveMirrorPath(cwd, explicitPath)
+    return { path: configPath, raw: await readConfigFile(configPath) }
+  }
+
+  const rootConfigPath = resolve(cwd, 'mirror.config.toml')
+  if (existsSync(rootConfigPath)) return { path: rootConfigPath, raw: await readConfigFile(rootConfigPath) }
+
+  const nestedConfigPath = resolve(cwd, 'config', 'mirror.config.toml')
+  if (existsSync(nestedConfigPath)) return { path: nestedConfigPath, raw: await readConfigFile(nestedConfigPath) }
+
+  return {}
+}
+
+export const readConfigFile = async (path: string): Promise<MirrorRawConfig> => {
+  if (!existsSync(path)) throw new MirrorError(`Configuration file not found: ${path}`)
+
+  const parsed = Bun.TOML.parse(await Bun.file(path).text())
+
+  if (!isRecord(parsed)) throw new MirrorError(`Configuration file must contain a TOML object: ${path}`)
+
+  return parsed as MirrorRawConfig
+}
+
+export const loadMirrorConfig = async (options: MirrorCliOptions = {}): Promise<MirrorConfig> => {
+  const cwd = resolve(options.cwd ?? process.cwd())
+  const discovered = await discoverMirrorConfig(cwd, options.config)
+
+  if (!discovered.raw) throw new MirrorError('Mirror configuration not found. Run `mirror init package`, `mirror init jsr`, or `mirror init git`.')
+
+  return normalizeMirrorConfig(discovered.raw, cwd, discovered.path, options)
+}
+
+export const normalizeMirrorConfig = (
+  raw: MirrorRawConfig,
+  cwd: string,
+  configPath: string | undefined,
+  options: MirrorCliOptions = {},
+): MirrorConfig => {
+  if (raw.schema !== 1) throw new MirrorError('Unsupported or missing configuration schema. Expected `schema = 1`.')
+  if (raw.version?.scheme !== undefined && raw.version.scheme !== 'semver') throw new MirrorError('Only `version.scheme = "semver"` is supported.')
+
+  const source = options.source ?? assertAdapter(raw.version?.source, 'version.source')
+  const output = dedupeAdapters(options.output ?? assertOutput(raw.version?.output))
+  const nameSource: MirrorProjectNameSource | undefined = raw.project?.name_source
+    ? assertProjectNameSource(raw.project.name_source, 'project.name_source')
+    : undefined
+  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 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
+  const gitPush = optionalBoolean(raw.git?.push, 'git.push') === true
+  const gitAllowDirty = optionalBoolean(raw.git?.allow_dirty, 'git.allow_dirty') === true
+
+  return {
+    schema: 1,
+    cwd,
+    configPath,
+    project: {
+      name: projectName,
+      nameSource,
+    },
+    version: {
+      scheme: 'semver',
+      source,
+      output,
+      prereleaseId,
+    },
+    package: {
+      path: packagePath,
+    },
+    jsr: {
+      path: jsrPath,
+    },
+    git: {
+      tagTemplate,
+      commit: options.commit === true || options.push === true || gitCommit || gitPush,
+      push: options.push === true || gitPush,
+      allowDirty: options.allowDirty === true || gitAllowDirty,
+    },
+  }
+}
+
+export const createInitConfig = (kind: MirrorAdapterName, cwd: string) => {
+  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
+`
+  }
+
+  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
+`
+  }
+
+  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
+`
+}
+
+export const writeInitConfig = async (kind: MirrorAdapterName, cwd: string, 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))
+  return path
+}
+
+export const configPathForDisplay = (config: MirrorConfig) => (config.configPath ? relativeFromCwd(config.cwd, config.configPath) : '(none)')
+
+const assertAdapter = (value: unknown, key: string): MirrorAdapterName => {
+  if (typeof value !== 'string' || !adapters.has(value)) throw new MirrorError(`Invalid or missing ${key}. Expected package.json, jsr.json, or git.`)
+  return value as MirrorAdapterName
+}
+
+const assertProjectNameSource = (value: unknown, key: string): MirrorProjectNameSource => {
+  if (typeof value !== 'string' || !projectNameSources.has(value)) throw new MirrorError(`Invalid ${key}. Expected package.json or jsr.json.`)
+  return value as MirrorProjectNameSource
+}
+
+const assertOutput = (value: unknown): MirrorAdapterName[] => {
+  if (!Array.isArray(value) || value.length === 0) throw new MirrorError('Invalid or missing version.output. Expected at least one output adapter.')
+  return value.map((item) => assertAdapter(item, 'version.output'))
+}
+
+const dedupeAdapters = (value: MirrorAdapterName[]) => [...new Set(value)]
+
+const optionalString = (value: unknown, key: string) => {
+  if (value === undefined) return undefined
+  if (typeof value !== 'string') throw new MirrorError(`Invalid ${key}. Expected a string.`)
+  return value
+}
+
+const optionalBoolean = (value: unknown, key: string) => {
+  if (value === undefined) return undefined
+  if (typeof value !== 'boolean') throw new MirrorError(`Invalid ${key}. Expected true or false.`)
+  return value
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === 'object' && value !== null && !Array.isArray(value)