@ingeniomaps/cauce 0.1.0 → 0.3.0

package/engine/agents/catalog.js

@@ -0,0 +1,67 @@
+'use strict'
+
+// Resolución única del catálogo de cargos. La usan el ciclo de aprendizaje, la validación de
+// equipos y la instalación en runners: tres lugares que antes resolvían por su cuenta.
+//
+// Cada tipo separa lo del toolkit de lo del proyecto igual que el resto de las colecciones:
+//
+//   agents/<tipo>/system/<slug>/SKILL.md   viene con Cauce y se reemplaza al actualizar
+//   agents/<tipo>/<slug>/SKILL.md          es del proyecto y manda sobre el anterior
+//
+// Un slug repetido entre tipos distintos sigue siendo ambiguo: ahí no hay ninguna regla que
+// diga cuál gana, y elegir en silencio sería peor que fallar.
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+function directories(dir) {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+  } catch { return [] }
+}
+
+function types(root) {
+  return directories(path.join(root, 'agents'))
+}
+
+// Todos los cargos visibles: los del proyecto ocultan a los del sistema con el mismo slug.
+function list(root) {
+  const catalog = path.join(root, 'agents')
+  const found = new Map()
+  for (const type of types(root)) {
+    const base = path.join(catalog, type)
+    // El sistema primero para que el proyecto lo sobrescriba al pasar por encima.
+    for (const [source, system] of [[path.join(base, 'system'), true], [base, false]]) {
+      for (const slug of directories(source)) {
+        if (slug === 'system' || !SLUG.test(slug)) continue
+        const dir = path.join(source, slug)
+        if (!fs.existsSync(path.join(dir, 'SKILL.md'))) continue
+        found.set(slug, { slug, type, dir, system })
+      }
+    }
+  }
+  return [...found.values()].sort((left, right) => left.slug.localeCompare(right.slug))
+}
+
+function resolve(root, slug) {
+  if (!SLUG.test(slug || '')) throw new Error(`agente inválido: ${slug || '(vacío)'}`)
+  const matches = []
+  for (const type of types(root)) {
+    const own = path.join(root, 'agents', type, slug)
+    const system = path.join(root, 'agents', type, 'system', slug)
+    // Dentro de un tipo la precedencia está definida; entre tipos no, y por eso se acumulan.
+    if (fs.existsSync(path.join(own, 'SKILL.md'))) matches.push(own)
+    else if (fs.existsSync(path.join(system, 'SKILL.md'))) matches.push(system)
+  }
+  if (!matches.length) throw new Error(`no existe agents/<tipo>/${slug}/SKILL.md`)
+  if (matches.length > 1) {
+    throw new Error(`agente ambiguo ${slug}: ${matches.map((dir) => path.relative(root, dir)).join(', ')}`)
+  }
+  return matches[0]
+}
+
+module.exports = { list, resolve, types }

package/engine/agents/learning.js

@@ -4,6 +4,7 @@
 
 const fs = require('fs')
 const path = require('path')
+const catalog = require('./catalog')
 
 const REQUIRED_SECTIONS = [
   'Hallazgos',
@@ -15,22 +16,7 @@ const REQUIRED_SECTIONS = [
 ]
 
 function agentRoot(root, agent) {
-  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(agent || '')) throw new Error(`agente inválido: ${agent || '(vacío)'}`)
-  const catalog = path.join(root, 'agents')
-  let types = []
-  try {
-    types = fs.readdirSync(catalog, { withFileTypes: true })
-      .filter((entry) => entry.isDirectory())
-      .map((entry) => entry.name)
-  } catch { /* catálogo ausente */ }
-  const matches = types
-    .map((type) => path.join(catalog, type, agent))
-    .filter((target) => fs.existsSync(path.join(target, 'SKILL.md')))
-  if (!matches.length) throw new Error(`no existe agents/<tipo>/${agent}/SKILL.md`)
-  if (matches.length > 1) {
-    throw new Error(`agente ambiguo ${agent}: ${matches.map((target) => path.relative(root, target)).join(', ')}`)
-  }
-  return matches[0]
+  return catalog.resolve(root, agent)
 }
 
 function isoDate(now = new Date()) { return now.toISOString().slice(0, 10) }

package/engine/automation/index.js

@@ -5,6 +5,9 @@ const path = require('node:path')
 const { spawnSync } = require('node:child_process')
 const F = require('../core/files')
 const H = require('../hooks/run')
+const P = require('../planning/parser')
+const catalog = require('../agents/catalog')
+const O = require('../core/ownership')
 
 const RUNNER_NAMES = ['claude', 'codex', 'gemini', 'antigravity']
 
@@ -81,6 +84,48 @@ function resolveItem(paths, root, name, item) {
   }
 }
 
+// Cargos del catálogo, con el frontmatter que el runner indexa para elegir a quién invocar.
+function roleCatalog(root) {
+  return catalog.list(root)
+    .map((role) => {
+      const field = P.frontmatter(fs.readFileSync(path.join(role.dir, 'SKILL.md'), 'utf8'))
+      return { ...role, reference: path.relative(root, role.dir), description: field('description') }
+    })
+    .filter((role) => role.description)
+}
+
+// Puntero fino: conserva nombre y descripción —lo único que el runner lee hasta invocar— y remite
+// al contrato completo. Evita duplicar el catálogo entero dentro de la configuración del runner.
+function roleSkill(role) {
+  return `---
+name: ${role.slug}
+description: ${role.description}
+---
+
+# ${role.slug}
+
+Leé \`${role.reference}/SKILL.md\` para el contrato completo del cargo: cuándo actuar,
+qué decide, qué no le corresponde y cuál es su entrega mínima. Sus métodos y formatos de salida están
+en \`${role.reference}/references/\`.
+
+Respetá los límites de ese contrato y las reglas de \`AGENTS.md\`. Generado por
+\`cauce automation install\`: no lo edites acá.
+`
+}
+
+function installRoleSkills(root, runner, output) {
+  if (!runner.capabilities.nativeSkills || !runner.roleSkills) return 0
+  const base = F.assertWithin(root, path.resolve(root, runner.roleSkills), `${runner.name}: roleSkills`)
+  const roles = roleCatalog(root)
+  for (const role of roles) {
+    const file = path.join(base, role.slug, 'SKILL.md')
+    F.assertNoSymlinkPath(root, file)
+    F.atomicWrite(file, roleSkill(role))
+  }
+  if (roles.length) output.log(`✓ ${runner.name}: ${roles.length} cargo(s) disponibles en ${runner.roleSkills}`)
+  return roles.length
+}
+
 function hasHooks(config) {
   if (config.hooks && Object.keys(config.hooks).length) return true
   const events = [
@@ -125,12 +170,11 @@ function check(root) {
       errors.push(`automatization/hooks/${name} no es ejecutable`)
     }
   }
-  const installedRuntime = path.join(root, '.ops', 'engine', 'hooks', 'run.js')
-  const sourceRuntime = path.join(root, 'engine', 'hooks', 'run.js')
-  if (!fs.existsSync(installedRuntime) && !fs.existsSync(sourceRuntime)) {
-    errors.push('falta engine/hooks/run.js')
+  // El motor puede venir de la dependencia npm, de la copia local o del propio repositorio.
+  if (!O.engineAt(root, path.join('hooks', 'run.js'))) {
+    errors.push('falta engine/hooks/run.js: instalá la dependencia o restaurá .ops/engine')
   }
-  const workflows = ['autobuild.js', path.join('integrations', 'sync.js')]
+  const workflows = ['autobuild.js', 'team.js', path.join('integrations', 'sync.js')]
   workflows.push(path.join('integrations', 'promote.js'))
   for (const name of workflows) {
     if (!fs.existsSync(path.join(root, 'automatization', 'workflows', name))) {
@@ -256,6 +300,23 @@ function doctor(root, name, output = console) {
       errors.push(`${item.target}: difiere de la fuente canónica`)
     }
   }
+  // Un cargo que quedó fuera, o cuya descripción cambió en el catálogo, deja al runner eligiendo
+  // con información vieja. Se reinstala, no se repara a mano.
+  if (runner.capabilities.nativeSkills && runner.roleSkills) {
+    const missing = []
+    const stale = []
+    for (const role of roleCatalog(root)) {
+      const file = path.join(root, runner.roleSkills, role.slug, 'SKILL.md')
+      if (!fs.existsSync(file)) missing.push(role.slug)
+      else if (fs.readFileSync(file, 'utf8') !== roleSkill(role)) stale.push(role.slug)
+    }
+    if (missing.length) {
+      warnings.push(`${missing.length} cargo(s) sin instalar en ${runner.roleSkills}: reinstalá el adaptador`)
+    }
+    if (stale.length) {
+      warnings.push(`${stale.length} cargo(s) desactualizados en ${runner.roleSkills}: reinstalá el adaptador`)
+    }
+  }
   const executable = spawnSync(
     'sh',
     ['-c', 'command -v "$1" >/dev/null 2>&1', 'runner-doctor', runner.command],
@@ -304,6 +365,7 @@ function install(root, name, output = console) {
       output.log(`✓ ${name}: instalado ${resolved.item.target}`)
     }
   }
+  installRoleSkills(root, runner, output)
   return runner
 }
 
@@ -323,6 +385,8 @@ module.exports = {
   install,
   legacyGuardWiring,
   pruneSupersededHooks,
+  roleCatalog,
+  roleSkill,
   listHooks,
   mergeConfig,
   runnerManifest,

package/engine/cli/ops.js

@@ -10,8 +10,11 @@ const I = require('../integrations/registry')
 const L = require('../agents/learning')
 const A = require('../automation')
 const F = require('../core/files')
+const O = require('../core/ownership')
+const CL = require('../core/changelog')
 const C = require('../config/validate')
 const T = require('../teams/registry')
+const AG = require('../agents/catalog')
 
 const PROJECT_ROOT = path.resolve(__dirname, '..', '..')
 
@@ -22,10 +25,11 @@ function fail(message, code = 1) {
 
 function usage() {
   console.log(`Uso:
-  ops init <destino> [--name <nombre>] [--mode embedded|sidecar] [--force]
+  ops init <destino> [--name <nombre>] [--mode embedded|sidecar] [--engine copy|dependency] [--force]
   ops check <planning-dir> [--json]
   ops tree <planning-dir> [--no-color] [--json]
   ops context <planning-dir> [--json]
+  ops upgrade <ops-root> [--check] [--force]
   ops archive <planning-dir> <NNN>
   ops integration list <ops-root>
   ops integration check <ops-root> [provider]
@@ -42,6 +46,7 @@ function usage() {
   ops automation install <ops-root> claude|codex|gemini|antigravity
   ops learn <agent> [--proposal]
   ops evaluate <agent>
+  ops agents list [ops-root] [--json]
   ops team list
   ops team check <team>
   ops team show <team>`)
@@ -75,13 +80,14 @@ function copyTemplate(source, target, replacements, force, skip = []) {
   }
 }
 
-function copyRuntime(source, target, preserve = false, boundary = target) {
+function copyRuntime(source, target, preserve = false, boundary = target, skip = []) {
   F.assertNoSymlinkPath(boundary, target)
   fs.mkdirSync(target, { recursive: true })
   for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    if (skip.includes(entry.name)) continue
     const from = path.join(source, entry.name)
     const to = path.join(target, entry.name)
-    if (entry.isDirectory()) copyRuntime(from, to, preserve, boundary)
+    if (entry.isDirectory()) copyRuntime(from, to, preserve, boundary, skip)
     else if (preserve && fs.existsSync(to)) console.log(`= conservado ${to}`)
     else {
       F.assertNoSymlinkPath(boundary, to)
@@ -90,6 +96,19 @@ function copyRuntime(source, target, preserve = false, boundary = target) {
   }
 }
 
+// Declara el motor como dependencia exacta: el lockfile decide qué versión corre, no una copia.
+// Conserva el manifiesto existente porque el repo anfitrión puede tener el suyo.
+function declareEngine(manifest, version) {
+  let pkg = { name: path.basename(path.dirname(manifest)), private: true, version: '0.0.0' }
+  if (fs.existsSync(manifest)) {
+    try { pkg = JSON.parse(fs.readFileSync(manifest, 'utf8')) } catch (error) {
+      fail(`package.json inválido en ${manifest}: ${error.message}`)
+    }
+  }
+  pkg.devDependencies = { ...pkg.devDependencies, '@ingeniomaps/cauce': version }
+  F.atomicWriteJson(manifest, pkg)
+}
+
 function init(target) {
   if (!target) fail('Falta <destino>.', 2)
   const mode = option('--mode', 'embedded')
@@ -137,6 +156,8 @@ function init(target) {
     path.join(root, 'automatization', 'runners'),
     preserve,
     root,
+    // El README de runners lo provee el template: le habla al proyecto, no a quien desarrolla Cauce.
+    O.TEMPLATE_OWNED.filter((owned) => owned.startsWith('automatization/runners/')).map((owned) => path.basename(owned)),
   )
   copyRuntime(
     path.join(PROJECT_ROOT, 'automatization', 'workflows'),
@@ -144,10 +165,25 @@ function init(target) {
     preserve,
     root,
   )
-  const engine = path.join(root, '.ops', 'engine')
-  copyRuntime(path.join(PROJECT_ROOT, 'engine'), engine, preserve, root)
-  fs.chmodSync(path.join(engine, 'cli', 'ops.js'), 0o755)
+  const version = require(path.join(PROJECT_ROOT, 'package.json')).version
+  // Un repo con npm recibe el motor como dependencia versionada; uno de Go, Python o Rust recibe
+  // la copia, porque exigirle un package.json para correr su planning sería imponerle un stack.
+  const manifest = path.join(root, 'package.json')
+  const engineMode = option('--engine', fs.existsSync(manifest) ? 'dependency' : 'copy')
+  if (!['copy', 'dependency'].includes(engineMode)) fail('--engine debe ser copy o dependency.', 2)
+  if (engineMode === 'dependency') declareEngine(manifest, version)
+  else {
+    const engine = path.join(root, '.ops', 'engine')
+    copyRuntime(path.join(PROJECT_ROOT, 'engine'), engine, preserve, root)
+    fs.chmodSync(path.join(engine, 'cli', 'ops.js'), 0o755)
+  }
+  // La instancia recuerda de qué versión salió: sin esto no hay actualización posible.
+  const configFile = path.join(root, 'ops.config.json')
+  const config = JSON.parse(fs.readFileSync(configFile, 'utf8'))
+  config.cauceVersion = version
+  F.atomicWriteJson(configFile, config)
   console.log(`\n✓ ${name}: sistema ops creado en ${root}`)
+  if (engineMode === 'dependency') console.log('  siguiente: npm install (el motor viene de la dependencia)')
   console.log(`  siguiente: node ${path.join(root, 'tools', 'ops.js')} check ${path.join(root, 'planning')}`)
 }
 
@@ -254,6 +290,12 @@ function check(dir) {
   errors.push(...integration.errors)
   warnings.push(...integration.warnings)
 
+  // Sobrescribir una entrada de system/ es legítimo y esperado; lo que no puede pasar es que
+  // ocurra en silencio, porque esa entrada deja de recibir las mejoras del toolkit.
+  for (const override of O.overrides(path.resolve(root, '..'))) {
+    warnings.push(`${override.collection}/${override.project} sobrescribe ${override.system} (override explícito)`)
+  }
+
   if (process.argv.includes('--json')) {
     console.log(JSON.stringify({
       ok: !errors.length,
@@ -414,6 +456,112 @@ function context(dir) {
   for (const action of report.humanActions) console.log(`HUMAN  ${action.task}: ${action.action}`)
 }
 
+// Qué trae la versión nueva, leído del paquete: sin esto el reemplazo de system/ es a ciegas.
+function printChangelog(from, to) {
+  const notes = CL.between(CL.read(PROJECT_ROOT), from, to)
+  if (!notes.length) return
+  for (const note of notes) {
+    console.log(`\n  ── ${note.version} ──`)
+    for (const line of note.body.split('\n')) if (line.trim()) console.log(`  ${line}`)
+  }
+  console.log('')
+}
+
+function instanceVersion(root) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, 'ops.config.json'), 'utf8')).cauceVersion || ''
+  } catch { return '' }
+}
+
+// Sobrescribe lo que trae el paquete y deja intacto lo demás: un guard propio de la empresa,
+// o un adaptador de runner que el toolkit no conoce, sobreviven a la actualización.
+function overlayTree(from, to, root, skip = []) {
+  F.assertNoSymlinkPath(root, to)
+  copyRuntime(from, to, false, root, skip)
+}
+
+// Actualiza sólo lo que el toolkit declara suyo. Todo lo demás —planning, organization, reglas
+// propias, agentes editados— queda intacto por construcción, no por comparación.
+function upgrade(dir) {
+  const root = path.resolve(dir || '.')
+  if (!fs.existsSync(path.join(root, 'ops.config.json'))) {
+    fail(`${root} no es una instancia de Cauce: falta ops.config.json.`, 2)
+  }
+  const dry = process.argv.includes('--check')
+  const force = process.argv.includes('--force')
+  const from = instanceVersion(root)
+  const to = require(path.join(PROJECT_ROOT, 'package.json')).version
+  const system = O.systemPaths(root)
+  const changed = O.localChanges(root, PROJECT_ROOT)
+  const overrides = O.overrides(root)
+
+  if (dry) {
+    if (from === to) return console.log(`= ${to}: la instancia está al día`)
+    console.log(`⚠ hay una versión más nueva: ${to} (la instancia tiene ${from || 'una previa'})`)
+    printChangelog(from, to)
+    for (const file of changed) console.log(`  editado localmente: ${file}`)
+    process.exit(1)
+  }
+
+  if (changed.length && !force) {
+    for (const file of changed) console.error(`✗ ${file}`)
+    fail(
+      `\n${changed.length} archivo(s) del runtime fueron editados y se perderían.\n\n` +
+      'El runtime es del toolkit: en vez de editarlo, agregá lo tuyo al lado con otro nombre —un\n' +
+      'guard propio sobrevive a cada actualización— y registralo en la configuración de tu runner,\n' +
+      'que sí es del proyecto. Para desactivar un guard alcanza con quitarlo de esa configuración.\n' +
+      'Si el cambio ya no te sirve, repetí con --force para descartarlo.',
+    )
+  }
+
+  for (const relative of [...system, ...O.RUNTIME_PATHS]) {
+    const origin = path.join(PROJECT_ROOT, O.sourceOf(relative))
+    if (!fs.existsSync(origin)) continue
+    const target = path.join(root, relative)
+    // Una instancia que toma el motor de npm no debe recuperar la copia: la actualiza el lockfile.
+    if (relative === '.ops/engine' && !fs.existsSync(target)) continue
+    const skip = O.TEMPLATE_OWNED
+      .filter((owned) => owned.startsWith(`${relative}/`))
+      .map((owned) => path.basename(owned))
+    if (fs.statSync(origin).isDirectory()) overlayTree(origin, target, root, skip)
+    else {
+      F.assertNoSymlinkPath(root, target)
+      F.atomicWrite(target, fs.readFileSync(origin, 'utf8'))
+    }
+  }
+
+  const config = JSON.parse(fs.readFileSync(path.join(root, 'ops.config.json'), 'utf8'))
+  config.cauceVersion = to
+  F.atomicWriteJson(path.join(root, 'ops.config.json'), config)
+
+  console.log(`✓ Cauce ${from || '(previa)'} → ${to}`)
+  // Descartar con --force es legítimo; hacerlo sin dejar rastro no. Queda en la salida del comando,
+  // que es la evidencia que el protocolo pide para cualquier cambio.
+  for (const file of changed) console.log(`− descartado tu cambio en ${file}`)
+  printChangelog(from, to)
+  console.log(`  ${system.length} ruta(s) del sistema y ${O.RUNTIME_PATHS.length} del runtime actualizadas`)
+  for (const override of overrides) {
+    console.log(`= conservado ${override.collection}/${override.project}: sobrescribe ${override.system}`)
+  }
+  console.log('  planning, organization y todo lo propio quedaron intactos')
+}
+
+// Lista los cargos visibles resolviendo la precedencia; evita que cada consumidor —CI incluido—
+// reimplemente el recorrido del catálogo.
+function agents(action, dir) {
+  if (action !== 'list') fail(`Acción de agents desconocida: ${action || '(vacía)'}`, 2)
+  const root = path.resolve(dir || '.')
+  const roles = AG.list(root)
+  if (process.argv.includes('--json')) {
+    // `path` viene resuelto: quien consuma esto no debería reconstruir dónde ganó la precedencia.
+    return console.log(JSON.stringify(roles.map((role) => ({
+      slug: role.slug, type: role.type, system: role.system,
+      path: path.relative(root, role.dir).split(path.sep).join('/'),
+    }))))
+  }
+  for (const role of roles) console.log(`${role.slug}${role.system ? '' : '  (propio)'}`)
+}
+
 function archive(dir, rawNum) {
   const root = path.resolve(dir || '.')
   const num = String(rawNum || '').padStart(3, '0')
@@ -570,6 +718,8 @@ function team(action, slug) {
     for (const error of result.errors) console.error(`✗ ${error}`)
     if (result.errors.length) fail(`${slug}: ${result.errors.length} error(es)`, 1)
     if (action === 'show') {
+      // El manifiesto entero, para que un workflow ejecute las etapas sin que un modelo lo parsee.
+      if (process.argv.includes('--json')) return console.log(JSON.stringify(result.manifest))
       console.log(`${result.manifest.name} (${slug})`)
       console.log(result.manifest.purpose)
       for (const stage of result.manifest.stages) {
@@ -588,6 +738,8 @@ async function main() {
   else if (command === 'check') check(process.argv[3])
   else if (command === 'tree') tree(process.argv[3])
   else if (command === 'context') context(process.argv[3])
+  else if (command === 'upgrade') upgrade(process.argv[3])
+  else if (command === 'agents') agents(process.argv[3], process.argv[4])
   else if (command === 'archive') archive(process.argv[3], process.argv[4])
   else if (command === 'integration') {
     await integration(process.argv[3], process.argv[4], process.argv[5], process.argv[6])

package/engine/config/validate.js

@@ -7,7 +7,10 @@ function validateOpsConfig(config) {
   if (!config || typeof config !== 'object' || Array.isArray(config)) {
     return ['ops.config.json: debe ser un objeto']
   }
-  const allowed = new Set(['$schema', 'project', 'mode', 'planningDir', 'workspaceRoots', 'runner'])
+  // `cauceVersion` la escribe el toolkit, no la persona: registra de qué versión salió la instancia.
+  const allowed = new Set([
+    '$schema', 'cauceVersion', 'project', 'mode', 'planningDir', 'workspaceRoots', 'runner',
+  ])
   for (const key of Object.keys(config)) {
     if (!allowed.has(key)) errors.push(`ops.config.json: propiedad desconocida ${key}`)
   }

package/engine/core/changelog.js

@@ -0,0 +1,50 @@
+'use strict'
+
+// `upgrade` reemplaza `system/` sin pedir confirmación. Mostrar qué cambió entre la versión
+// instalada y la nueva es lo que separa "actualizarse rápido" de "actualizarse a ciegas".
+
+const fs = require('node:fs')
+const path = require('node:path')
+
+const HEADING = /^##\s*\[([^\]]+)\]/
+
+// Compara versiones semver sin dependencias. Lo no numérico ordena antes que la release.
+function compare(left, right) {
+  const parse = (value) => String(value).split('-')[0].split('.').map((part) => Number(part) || 0)
+  const [a, b] = [parse(left), parse(right)]
+  for (let index = 0; index < 3; index++) {
+    if ((a[index] || 0) !== (b[index] || 0)) return (a[index] || 0) - (b[index] || 0)
+  }
+  return 0
+}
+
+function entries(text) {
+  const found = []
+  let current = null
+  for (const line of text.split('\n')) {
+    const heading = line.match(HEADING)
+    if (heading) {
+      current = { version: heading[1], lines: [] }
+      found.push(current)
+      continue
+    }
+    if (current) current.lines.push(line)
+  }
+  return found.map((entry) => ({ version: entry.version, body: entry.lines.join('\n').trim() }))
+}
+
+// Entradas estrictamente posteriores a `from` y hasta `to`. Una versión no publicada se incluye
+// siempre: es justamente la que el usuario está por recibir desde el paquete.
+function between(text, from, to) {
+  return entries(text).filter((entry) => {
+    if (!/^\d/.test(entry.version)) return true
+    if (from && compare(entry.version, from) <= 0) return false
+    return !to || compare(entry.version, to) <= 0
+  })
+}
+
+function read(packageRoot) {
+  try { return fs.readFileSync(path.join(packageRoot, 'CHANGELOG.md'), 'utf8') } catch { return '' }
+}
+
+module.exports = { between, compare, entries, read }