@ingeniomaps/cauce 0.69.0 → 0.71.0

package/engine/cli/worktree.js

@@ -0,0 +1,89 @@
+'use strict'
+
+// Dónde trabaja un agente. Prepara un árbol de trabajo por tarea con `git worktree`, que es git de base:
+// no hace falta instalar nada, y sobre todo **no clona el repositorio**. Un worktree comparte el mismo
+// `.git`, el mismo historial y los mismos objetos; lo único que materializa es un segundo directorio de
+// archivos, fijado a su rama.
+//
+// Esa es la propiedad que importa con varios agentes: cada uno queda en su rama y **nadie hace checkout
+// nunca**, que es lo que pisaría el trabajo del otro dentro de un único directorio compartido.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { spawnSync } = require('node:child_process')
+const ST = require('../planning/state')
+const CL = require('../planning/claims')
+const R = require('../core/repos')
+const O = require('../core/ownership')
+const { fail } = require('./io')
+
+const git = (cwd, ...args) => spawnSync('git', args, { cwd, encoding: 'utf8' })
+
+// El árbol que ya existe para esa rama, si existe. `--porcelain` lista bloques de `worktree <ruta>` y
+// `branch refs/heads/<nombre>`, y se lee así para no depender del formato humano, que cambia.
+function existing(repo, branch) {
+  const listed = git(repo, 'worktree', 'list', '--porcelain')
+  if (listed.status !== 0) return ''
+  let current = ''
+  for (const line of listed.stdout.split('\n')) {
+    if (line.startsWith('worktree ')) current = line.slice(9).trim()
+    if (line.trim() === `branch refs/heads/${branch}`) return current
+  }
+  return ''
+}
+
+function worktree(dir, slug, cli) {
+  const root = path.resolve(dir || '.')
+  if (!slug) return fail('Falta el slug. `ops worktree <planning-dir> <tarea>`', 2)
+  const state = ST.snapshot(root)
+  const task = state.milestones.flatMap((milestone) => milestone.tasks).find((one) => one.slug === slug)
+  if (!task) return fail(`${slug} no está en BACKLOG: sólo se prepara trabajo ya promovido.`, 2)
+
+  // No reserva —eso es `claim`— pero se niega a montar sobre lo de otro: preparar un árbol para una
+  // tarea ajena es trabajo que se va a tirar, y el aviso cuesta menos que descubrirlo después.
+  const taken = state.claims.find((one) => one.slug === slug)
+  if (taken && taken.runner !== CL.runner()) {
+    return fail(`${slug} la tomó ${taken.owner}; preparar un árbol para su tarea no ayuda a nadie.`)
+  }
+
+  const candidatos = R.reposFor(path.join(root, '..'), task.service)
+  if (candidatos.length > 1) {
+    return fail(`${task.service || '.'} existe en más de un repositorio (${candidatos.join(', ')}), así que `
+      + 'no puedo saber cuál. Escribí un `service:` que sólo exista en uno.', 2)
+  }
+  const repo = candidatos[0]
+  if (!repo) {
+    return fail(`no encontré el repositorio de ${task.service || '(sin service)'}: revisá workspaceRoots `
+      + 'en ops.config.json y que la ruta del servicio exista.', 2)
+  }
+
+  const branch = CL.branchOf(slug)
+  const already = existing(repo, branch)
+  const target = already || path.join(path.dirname(repo), `${path.basename(repo)}-${slug}`)
+  if (!already) {
+    if (fs.existsSync(target)) return fail(`${target} ya existe y no es un árbol de esta rama.`)
+    const hasBranch = git(repo, 'rev-parse', '--verify', '--quiet', `refs/heads/${branch}`).status === 0
+    const args = hasBranch ? ['worktree', 'add', target, branch] : ['worktree', 'add', '-b', branch, target]
+    const added = git(repo, ...args)
+    if (added.status !== 0) return fail(`git worktree add falló: ${(added.stderr || '').trim()}`)
+  }
+
+  if (cli.has('--json')) {
+    return console.log(JSON.stringify({ path: target, branch, repo, runner: target, reused: Boolean(already) }))
+  }
+  console.log(`${already ? '=' : '✓'} ${target}  (${branch})`)
+  // En `embedded` la instancia vive dentro del repo, así que cada árbol se lleva su propia copia de
+  // `planning/` — o ninguna, si todavía no se commiteó—. Para un agente solo eso funciona; para varios
+  // deja de haber coordinación, porque los reclamos de uno no los ve el otro hasta mergear. Se avisa y no
+  // se frena: usar un árbol por rama sin equipo es legítimo.
+  if (O.mode(path.join(root, '..')) === 'embedded') {
+    console.log('  ⚠ la instancia vive dentro del repo, así que este árbol lleva su propia copia de '
+      + 'planning/: los reclamos no se ven entre árboles hasta mergear. Para varios agentes, mode: sidecar.')
+  }
+  // El id del runner y la ruta son la misma cosa a propósito: el árbol es lo que distingue a un agente
+  // de otro en una máquina, así que darlo hecho evita el modo de fallo que deja a los dos con el mismo.
+  console.log(`  export CAUCE_RUNNER=${target}`)
+  console.log(`  node tools/ops.js claim ${path.relative(process.cwd(), root) || '.'} ${slug}`)
+}
+
+module.exports = { worktree }

package/engine/core/ownership.js

@@ -20,6 +20,9 @@ const SYSTEM_FILES = [
   'planning/business-rules/000-template.md',
   'planning/business-rules/README.md',
   'planning/rules/README.md',
+  'planning/claims/README.md',
+  'planning/done/README.md',
+  'planning/wip/README.md',
   'planning/roadmap/README.md',
   'planning/roadmap/epic-000-template.md',
   // La guía de entrega no tiene una línea de la empresa: describe el camino que Cauce recomienda, y lo
@@ -32,6 +35,7 @@ const SYSTEM_FILES = [
   'planning/delivery/environments.md',
   'planning/delivery/flags.md',
   'planning/delivery/multi-repo.md',
+  'planning/delivery/teamwork.md',
   'organization/roles/README.md',
   'flows/000-template.md',
   'flows/README.md',
@@ -75,9 +79,12 @@ const TEMPLATE_PREFIXES = [
   'tools/',
 ]
 
-// Archivos que la instancia recibe en su raíz y que el paquete tiene por duplicado: el propio del
-// toolkit y el de la plantilla. Gana el de la plantilla, que es el que le habla a la instancia.
-const TEMPLATE_FILES = new Set(['AGENTS.md', 'Makefile'])
+// Archivos que la instancia recibe en su raíz y cuyo original vive en `template/`. Dos de ellos el
+// paquete los tiene por duplicado —el propio del toolkit y el de la plantilla— y gana el de la
+// plantilla, que es el que le habla a la instancia; `.gitattributes` existe sólo del lado del molde y
+// entra por la misma puerta, porque sin esto `sourceOf` lo busca en la raíz del paquete y `upgrade` lo
+// saltea en silencio.
+const TEMPLATE_FILES = new Set(['AGENTS.md', 'Makefile', '.gitattributes'])
 
 function sourceOf(relative) {
   if (TEMPLATE_FILES.has(relative)) return path.join('template', relative)
@@ -186,6 +193,9 @@ function overrides(root) {
 // decidir acá. Una entrada pasa de `upgrade` a `init` cuando ninguna versión soportada puede no
 // tenerlo; que se quede de más no rompe nada, porque el archivo ya está y se conserva.
 const TEMPLATE_OWN = {
+  // 0.70.0. Le dice a git que los dos archivos que sólo crecen se concatenan en vez de
+  // conflictuar, así que hace falta en la instancia que ya existe y no sólo en la nueva.
+  '.gitattributes': 'upgrade',
   'README.md': 'init',
   'gitignore': 'init',
   'integrations/config.json': 'init',
@@ -202,13 +212,11 @@ const TEMPLATE_OWN = {
   // una instancia que actualiza queda leyendo una instrucción que apunta a un archivo que no tiene.
   'organization/workspace.md': 'upgrade',
   'planning/BACKLOG.md': 'init',
-  'planning/DONE.md': 'init',
   'planning/HUMAN_ACTIONS.md': 'init',
   'planning/INBOX.md': 'init',
   // 0.69.0. El contrato nace con esta versión, así que ninguna instancia anterior lo tiene: por `init`
   // no llegaría nunca a la que ya existe, que es justo la que iba a usarlo.
   'planning/RECURRING.md': 'upgrade',
-  'planning/WIP.md': 'init',
   'planning/delivery/project.md': 'init',
   'planning/done/.gitkeep': 'init',
   'planning/reports/README.md': 'init',

package/engine/core/repos.js

@@ -0,0 +1,67 @@
+'use strict'
+
+// En qué repositorio vive un servicio, y cuándo se movió por última vez una rama. Vive acá porque lo
+// preguntan dos cosas que no se conocen entre sí —preparar un árbol de trabajo y juzgar si un reclamo
+// sigue vivo— y la resolución tiene que ser la misma en las dos: escrita dos veces, una copia envejece
+// y las dos respuestas dejan de coincidir sin que nada falle.
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { spawnSync } = require('node:child_process')
+
+const git = (cwd, ...args) => spawnSync('git', args, { cwd, encoding: 'utf8' })
+
+// Los repositorios cuyo árbol contiene el servicio, resuelto como lo resuelve `check` para juzgar si
+// existe. Devuelve la raíz git de cada uno, que no siempre es la raíz declarada: `workspaceRoots` puede
+// apuntar a un subdirectorio.
+//
+// Devuelve una lista y no el primero porque con varias raíces la respuesta puede ser ambigua: un
+// `service: .` existe en todas, y un `src` puede existir en dos. Elegir el primero da una respuesta
+// plausible y equivocada —un árbol de trabajo en el repositorio que no era— sin que nada lo diga.
+function reposFor(opsRoot, service) {
+  let config = {}
+  try {
+    config = JSON.parse(fs.readFileSync(path.join(opsRoot, 'ops.config.json'), 'utf8'))
+  } catch { return [] }
+  return (Array.isArray(config.workspaceRoots) ? config.workspaceRoots : [])
+    .filter((one) => one && one.path)
+    .map((one) => path.resolve(opsRoot, one.path))
+    .filter((root) => fs.existsSync(path.join(root, service || '.')))
+    .map((root) => {
+      const top = git(root, 'rev-parse', '--show-toplevel')
+      return top.status === 0 ? top.stdout.trim() : ''
+    })
+    .filter(Boolean)
+    // Dos raíces del mismo repositorio son un solo repositorio: lo ambiguo es a cuál pertenece el
+    // servicio, no cuántas rutas lo contienen.
+    .filter((repo, index, todos) => todos.indexOf(repo) === index)
+}
+
+// El repositorio del servicio cuando no hay duda. Sin ninguno o con varios devuelve vacío, y quien
+// pregunta decide qué decir: para `check` es la degradación ya declarada —mirar sólo la fecha—, y para
+// `worktree` es un error que tiene que nombrar los candidatos.
+function repoOf(opsRoot, service) {
+  const repos = reposFor(opsRoot, service)
+  return repos.length === 1 ? repos[0] : ''
+}
+
+// La fecha del último commit **propio** de una rama, en AAAA-MM-DD, o vacío si no tiene ninguno. Vacío no
+// es un error: una tarea recién tomada todavía no tiene rama, la rama recién creada no tiene commits, y
+// un proyecto puede nombrar sus ramas de otra forma. Quien pregunta decide qué hacer con la ausencia.
+//
+// Lo que hay que excluir es el tronco. Una rama nueva hereda su historia entera, así que preguntar por su
+// último commit a secas devuelve el del tronco y **toda rama parece haber avanzado el día que se creó** —
+// que es justo lo contrario de lo que esta función existe para medir. El tronco es la rama en la que está
+// el árbol principal: los worktrees se crean desde ahí y ahí se queda.
+function lastCommit(repo, branch) {
+  if (!repo) return ''
+  const actual = git(repo, 'rev-parse', '--abbrev-ref', 'HEAD')
+  const tronco = actual.status === 0 ? actual.stdout.trim() : ''
+  const args = tronco && tronco !== branch
+    ? ['log', '-1', '--format=%cs', branch, '--not', tronco, '--']
+    : ['log', '-1', '--format=%cs', branch, '--']
+  const shown = git(repo, ...args)
+  return shown.status === 0 ? shown.stdout.trim() : ''
+}
+
+module.exports = { reposFor, repoOf, lastCommit }

package/engine/hooks/files.js

@@ -12,6 +12,7 @@ const {
 } = require('./input')
 const AP = require('./approval')
 const { readWip } = require('../planning/parser')
+const { runner } = require('../planning/claims')
 const { hasTasks } = require('../planning/state')
 const { TEMPLATE_PREFIXES } = require('../core/ownership')
 
@@ -138,7 +139,7 @@ function planFirst(input) {
   const root = opsRoot(input)
   if (!root) return
   const planning = path.join(root, 'planning')
-  const wip = readWip(planning)
+  const wip = readWip(planning, runner())
   if (wip && wip.complete + wip.pending > 0) return
   // Una instancia recién creada no tiene de dónde sacar una tarea: `onboard` deja el roadmap vacío y
   // dice que alguien lo llene. Exigir el plan ahí es un candado delante de la puerta, y la salida que
@@ -149,7 +150,7 @@ function planFirst(input) {
   if (!hasTasks(planning)) return
   const estado = wip ? `WIP tiene la tarea ${wip.task} y ningún paso` : 'WIP está en IDLE'
   const why = `${estado}, así que el plan todavía no está escrito.\n`
-    + 'Escribí en planning/WIP.md la tarea y su plan aprobado —pasos numerados, cada uno con un estado '
+    + 'Escribí en tu planning/wip/<runner>.md la tarea y su plan aprobado —pasos numerados, cada uno con un estado '
     + 'verificable— y volvé al cambio. Si esto no es trabajo de una tarea, aprobá la ruta.\n'
     + AP.HOW('OPS_PLAN_FIRST_OVERRIDE')
   for (const raw of filesOf(input)) {

package/engine/planning/adoption.js

@@ -96,7 +96,7 @@ function report({ done, epics = [], adopted = [] }) {
   for (const slug of slugs) {
     const entry = done.entries.find((candidate) => candidate.slug === slug)
     if (!entry) {
-      warnings.push(`${BASELINE}: ${slug} no está en DONE.md; sacalo de la lista`)
+      warnings.push(`${BASELINE}: ${slug} no está en done/; sacalo de la lista`)
     } else if (!PC.doneEntryErrors(entry, epics).length) {
       warnings.push(`${BASELINE}: ${slug} ya cumple el contrato; retiralo poniéndole \`#~\` delante`)
     }

package/engine/planning/claims.js

@@ -0,0 +1,153 @@
+'use strict'
+
+// Quién tomó qué. Un archivo por tarea reclamada: crearlo es reclamar, borrarlo es soltar.
+//
+// El nombre del archivo es el slug de la tarea, y de ahí sale la única propiedad que importa: dos
+// personas en tareas distintas no tocan el mismo archivo nunca, y dos que reclaman la misma chocan en
+// git — que es exactamente donde el choque significa algo y donde conviene verlo.
+//
+// El plan de la ejecución no vive acá. Eso es `wip/<runner>.md`, que es local y cambia en cada paso; acá va lo
+// poco que el resto del equipo necesita saber, que cambia dos veces por tarea. Son dos responsabilidades
+// distintas y por eso son dos archivos: el reclamo evita que dos runners tomen la misma tarea, y el WIP
+// evita que un runner lleve dos.
+
+const fs = require('node:fs')
+const { spawnSync } = require('node:child_process')
+const path = require('node:path')
+const P = require('./parser')
+
+const DIR = 'claims'
+const DATE = /^\d{4}-\d{2}-\d{2}$/
+
+// Tres días **sin ninguna señal de avance**, que no es lo mismo que tres días desde que se tomó. El
+// tiempo transcurrido solo no distingue una tarea larga de una abandonada, y equivocarse en esa
+// distinción es caro en los dos sentidos: apurar a alguien que está trabajando, o dejar bloqueada para
+// siempre la tarea de quien se fue.
+//
+// Lo que sí distingue es si la rama de la tarea se movió. Con esa señal, tres días sin un solo commit no
+// es una tarea larga: es una que se detuvo, y el aviso manda a mirar y no a soltar.
+const STALE_DAYS = 3
+
+// Quién soy. Sale de la identidad de git porque ya está configurada, es por máquina y es la que va a
+// terminar en el commit igual: pedir una segunda identidad sólo para esto sería un dato más que puede
+// quedar desincronizado. `CAUCE_OWNER` la pisa donde no la haya —un contenedor de CI, por ejemplo—.
+//
+// Sin identidad no se puede reclamar, y eso es correcto: un reclamo anónimo no le dice a nadie a quién
+// preguntarle.
+function owner(root) {
+  if (process.env.CAUCE_OWNER) return process.env.CAUCE_OWNER.trim()
+  const result = spawnSync('git', ['config', 'user.email'], { cwd: root, encoding: 'utf8' })
+  return result.status === 0 ? (result.stdout || '').trim() : ''
+}
+
+// Qué runner soy, que no es lo mismo que quién soy. En una máquina con varios agentes la identidad de
+// git es la misma para todos —`git config user.email` no distingue una sesión de otra—, así que si lo
+// que decide «esto es mío» fuera el owner, el segundo agente tomaría por propia la tarea del primero y
+// los dos construirían lo mismo. La unidad es el árbol de trabajo: uno por agente.
+//
+// `CAUCE_RUNNER` es la vía explícita y la que deja `ops worktree`. Sin ella se deduce del árbol donde
+// corre el proceso, que acierta cuando el agente invoca desde el suyo y falla —devolviendo el mismo id
+// para todos— cuando invoca desde una instancia sidecar compartida. Esa falla no queda en silencio:
+// `claim` se niega a darle una segunda tarea a un runner que ya tiene una, y ese es el mensaje que
+// manda a poner la variable.
+function runner() {
+  if (process.env.CAUCE_RUNNER) return process.env.CAUCE_RUNNER.trim()
+  const result = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' })
+  return result.status === 0 ? (result.stdout || '').trim() : process.cwd()
+}
+
+// La rama donde vive el trabajo de una tarea. La escriben `worktree` al crearla y `check` al buscar si
+// se movió, y son la misma o el segundo mira una rama que nadie usa.
+const branchOf = (slug) => `task/${slug}`
+
+function file(root, slug) {
+  return path.join(root, DIR, `${slug}.md`)
+}
+
+function read(root) {
+  let names = []
+  try { names = fs.readdirSync(path.join(root, DIR)) } catch { return [] }
+  return names.filter((name) => name.endsWith('.md') && name !== 'README.md').sort()
+    .map((name) => {
+      const field = P.frontmatter(P.read(path.join(root, DIR, name)))
+      return {
+        slug: name.replace(/\.md$/, ''),
+        task: field('task'),
+        owner: field('owner'),
+        runner: field('runner'),
+        started: field('started'),
+        service: field('service'),
+        at: `${DIR}/${name}`,
+      }
+    })
+}
+
+// El cuerpo de un reclamo. Es corto a propósito: todo lo que crezca acá vuelve a viajar por git en cada
+// cambio, que es de lo que este archivo vino a separarse.
+function content({ task, owner, runner: from, started, service }) {
+  return `---\ntask: ${task}\nowner: ${owner}\nrunner: ${from}\nstarted: ${started}\n`
+    + `service: ${service || ''}\n---\n\nTomada. El plan vive en el \`wip/\` de quien la tomó.\n`
+}
+
+function validate({ claims, milestones, done }) {
+  const errors = []
+  const queued = new Set(milestones.flatMap((milestone) => milestone.tasks).map((task) => task.slug))
+  for (const claim of claims) {
+    const at = `${claim.at}`
+    // El nombre del archivo es lo que hace única la reserva, así que un frontmatter que dice otra cosa
+    // reclama una tarea y bloquea otra. Es la única forma en que este contrato puede mentir.
+    if (claim.task !== claim.slug) {
+      errors.push(`${at}: declara task "${claim.task}" y el archivo reserva ${claim.slug}`)
+    }
+    if (!claim.owner) errors.push(`${at}: falta owner`)
+    if (!claim.runner) errors.push(`${at}: falta runner`)
+    if (!DATE.test(claim.started)) errors.push(`${at}: started debe ser AAAA-MM-DD`)
+    if (!queued.has(claim.slug) && !done.set.has(claim.slug)) {
+      errors.push(`${at}: ${claim.slug} no existe en BACKLOG ni DONE`)
+    }
+  }
+  return errors
+}
+
+const days = (from, to) => Math.round((Date.parse(`${to}T00:00:00Z`) - Date.parse(`${from}T00:00:00Z`))
+  / 86400000)
+
+// `activity` mapea el slug de una tarea a la fecha del último commit de su rama. Llega de afuera porque
+// resolverlo exige git y la configuración del proyecto, y este módulo se prueba sin ninguna de las dos.
+// Vacío es un estado legítimo —una tarea recién tomada no tiene rama— y entonces la única señal que
+// queda es cuándo se tomó.
+function warnings({ claims, done, today, activity = new Map() }) {
+  const lines = []
+  for (const claim of claims) {
+    if (done.set.has(claim.slug)) {
+      lines.push(`${claim.at}: ${claim.slug} ya está en DONE; soltala con \`ops release\``)
+      continue
+    }
+    if (!DATE.test(claim.started)) continue
+    const commit = activity.get(claim.slug) || ''
+    const ultima = commit && commit > claim.started ? commit : claim.started
+    const quieta = days(ultima, today)
+    if (quieta > STALE_DAYS) {
+      const senal = commit
+        ? `último commit hace ${days(commit, today)} días`
+        : 'la rama de la tarea no tiene commits'
+      lines.push(`${claim.at}: ${claim.slug} sin avanzar hace ${quieta} días `
+        + `(${claim.owner}, tomada hace ${days(claim.started, today)}; ${senal}); mirá si sigue viva`)
+    }
+  }
+  // Dos tareas del mismo servicio pueden tocar los mismos archivos, y eso no se puede saber antes de
+  // hacerlas. Lo único que se puede es decirlo a tiempo de que hablen, así que avisa y nunca frena:
+  // frenar serializaría a un equipo entero sobre un servicio, que es peor que la colisión que evita.
+  const byService = new Map()
+  for (const claim of claims.filter((one) => one.service && !done.set.has(one.slug))) {
+    byService.set(claim.service, [...(byService.get(claim.service) || []), claim])
+  }
+  for (const [service, group] of byService) {
+    if (group.length < 2) continue
+    lines.push(`${group.length} tareas tomadas sobre ${service} `
+      + `(${group.map((one) => `${one.slug} · ${one.owner}`).join('; ')}); pueden tocar los mismos archivos`)
+  }
+  return lines
+}
+
+module.exports = { DIR, STALE_DAYS, owner, runner, branchOf, file, read, content, validate, warnings }