@kikedealba/recap 0.0.0-stage → 0.9.0

package/Resources/wrapup-prompt.md

@@ -0,0 +1,32 @@
+Vas a cerrar en bita el registro de una reunión ya transcrita y resumida. Con la minuta y la transcripción de abajo, decide cómo queda documentada.
+
+- Título actual del contador: «{{currentTitle}}»
+- Proyecto actual del contador: {{currentProject}}
+- Fecha: {{date}} · Duración: {{duration}} · Modo: {{mode}}
+- Proyectos que existen en bita (elige solo de esta lista, con el nombre exacto):
+{{projects}}
+{{existingPage}}
+
+Responde únicamente con un objeto JSON, sin texto antes ni después y sin bloque de código, con esta forma:
+
+{"title": "...", "project": "..." | null, "pageTitle": "...", "pageMarkdown": "...", "backlog": [{"kind": "pending" | "finding", "title": "...", "body": "..."}]}
+
+Reglas por campo:
+
+- **title**: el tema real de la reunión, corto (máximo 80 caracteres), reconocible en Jira. Por ejemplo, «Reunión presencial: iniciativa de recompra con cupón post-entrega». Sin fecha.
+- **project**: el nombre exacto de uno de los proyectos de la lista, solo si la conversación deja claro a cuál pertenece (se menciona el cliente, el producto o el sistema). Si hay duda, o si ninguno aplica, `null`. Nunca inventes un nombre.
+- **pageTitle**: el título de la página de documentación, el tema sin la palabra «reunión». Por ejemplo, «Iniciativa de recompra con cupón post-entrega».
+- **pageMarkdown**: el cuerpo de la página, en Markdown, sin título H1. Debe ser un documento técnico formal que explica **cómo es** lo que se trató, en presente:
+  - Secciones `##` por tema: contexto y objetivo, cómo funciona o cómo se propone, decisiones tomadas y, si aplica, arquitectura, datos, costos o plan de pruebas, con las cifras y nombres que se dijeron.
+  - Si hay un flujo o una arquitectura, puedes incluir un diagrama en un bloque `mermaid`. Solo con componentes que se mencionaron: si algo no se nombró, no lo supongas.
+  - **Prohibido**: secciones de «Pendientes», «Próximos pasos», «Hallazgos», «Preguntas abiertas» o «Lo que falta»; eso va en `backlog`. Tampoco «se acordó con el usuario», «según lo solicitado», «decidimos», «creo que», primera ni segunda persona, ni comentarios sobre la grabación o la transcripción.
+  - Entre 3 y 7 secciones. Nada que no esté en la minuta o en la transcripción.
+- **backlog**: un ítem por cada pendiente (`kind: "pending"`, redactado como acción que empieza con verbo; en `body` el responsable, la fecha y el contexto si se mencionaron) y por cada pregunta abierta o riesgo (`kind: "finding"`). Títulos de una línea, sin numeración. Lista vacía si no hay ninguno.
+
+<minuta>
+{{summary}}
+</minuta>
+
+<transcripcion>
+{{transcript}}
+</transcripcion>

package/commands/recap-ask.md

@@ -0,0 +1,28 @@
+---
+description: Responde la última pregunta de la reunión en curso con las páginas y repos del proyecto
+argument-hint: [pregunta, opcional]
+allowed-tools: Bash(recap ask:*)
+---
+
+Responde en vivo una pregunta de la reunión que se está grabando.
+
+- **Con `$ARGUMENTS`**, es la pregunta:
+
+  ```
+  recap ask --active --question "$ARGUMENTS" --json
+  ```
+
+- **Sin `$ARGUMENTS`**, recap toma la última pregunta de la transcripción en
+  vivo:
+
+  ```
+  recap ask --active --json
+  ```
+
+Muestra `data.answer` tal cual y, debajo, las fuentes de `data.sources` (su
+`label`). Si `data.found` es false, dilo en una línea: no está documentado.
+Si falla con `NOT_RECORDING`, no hay grabación activa; con `NO_QUESTION`, la
+transcripción en vivo todavía está vacía y hace falta escribir la pregunta.
+Puede haber otras respuestas en curso al mismo tiempo; no se estorban. Las
+respuestas que el live-worker encontró solo llevan `auto: true` en
+`live/answers.jsonl`.

package/commands/recap-list.md

@@ -0,0 +1,21 @@
+---
+description: Lista las reuniones grabadas, o muestra la minuta de una
+argument-hint: [id, parte del título o "last"]
+allowed-tools: Bash(recap list:*), Bash(recap show:*)
+---
+
+**Sin `$ARGUMENTS`**, lista las reuniones recientes:
+
+!`recap list`
+
+y muéstralas en una tabla corta (fecha, modo, estado, duración, título).
+
+**Con `$ARGUMENTS`**, muestra esa reunión:
+
+```
+recap show "$ARGUMENTS"
+```
+
+Si tiene minuta, muéstrala tal cual. Si no, di en qué estado está y si alguna
+etapa falló. Si el texto coincide con varias reuniones (`MEETING_AMBIGUOUS`),
+lista las candidatas y pregunta cuál.

package/commands/recap-proposals.md

@@ -0,0 +1,32 @@
+---
+description: Revisa los cambios a la documentación que propuso una reunión
+argument-hint: [id de la reunión o "last"]
+allowed-tools: Bash(recap proposals:*), Bash(recap show:*), Read, Write
+---
+
+Al cerrar una reunión ligada a bita, recap deja los cambios explícitos a
+páginas existentes como propuestas en la rama `proposal/meeting-<entrada>` de
+los docs. Nada llega a `main` sin aceptarse.
+
+1. La reunión es `$ARGUMENTS`, o `last` si viene vacío. Lista sus propuestas:
+
+   ```
+   recap proposals ls <reunión> --json
+   ```
+
+2. Por cada una en `pending` o `stale`, muestra el detalle con
+   `recap proposals show <reunión> <n> --json`: título, página y sección,
+   justificación, citas (con su minuto) y el diff.
+3. Pregunta qué hacer con cada una y aplícalo:
+
+   ```
+   recap proposals accept <reunión> <n> --json
+   recap proposals accept <reunión> <n> --md <archivo-editado> --json
+   recap proposals reject <reunión> <n> --json
+   ```
+
+   Para editar antes de aceptar, copia `proposal.file`, haz el cambio que pida
+   el usuario y pásalo con `--md`.
+
+Si `accept` deja la propuesta en `stale`, la página cambió desde la propuesta:
+muéstralo, y ofrece editarla sobre la versión actual y aceptarla con `--md`.

package/commands/recap-start.md

@@ -0,0 +1,47 @@
+---
+description: Empieza a grabar una reunión (remota o presencial)
+argument-hint: [remota|presencial] [título]
+allowed-tools: Bash(recap start:*), Bash(recap status:*), Bash(recap import:*), Bash(bita start:*)
+---
+
+Estado actual:
+
+!`recap status --json`
+
+Empieza a grabar una reunión con `$ARGUMENTS`.
+
+1. **Si arriba dice que ya se está grabando**, no arranques otra: dilo en una
+   línea y termina.
+2. **Modo.** Sácalo de `$ARGUMENTS` o del contexto de la conversación:
+   - remota: Meet, Zoom, Teams, llamada, videollamada, en línea.
+   - presencial: en sala, en oficina, en persona.
+
+   Si no se puede saber, pregunta solo "¿remota o presencial?" y espera.
+3. **Título.** Lo que quede de `$ARGUMENTS` sin la palabra del modo, literal. Si
+   no hay, uno corto sacado del contexto; si tampoco hay contexto, arranca sin
+   título.
+4. **Por dónde arrancar.** Si arriba `data.bitaLinked` es true, recap escucha
+   los eventos de bita: arranca por bita, para que el tiempo también quede
+   medido y la minuta llegue al documento de la entrada:
+
+   ```
+   bita start "<título>" --kind remote-meeting
+   bita start "<título>" --kind in-person-meeting
+   ```
+
+   Si `data.bitaLinked` es false, arranca recap directamente:
+
+   ```
+   recap start --remote "<título>"
+   recap start --in-person "<título>"
+   ```
+
+Si falla por permisos (`SCREEN_DENIED`, `MICROPHONE_DENIED`), di exactamente qué
+activar en Configuración > Privacidad y seguridad. Si es `RECORDER_TIMEOUT` o
+falta una dependencia, sugiere `recap setup`. Si es `CAPTURE_UNAVAILABLE`
+(Windows o Linux), explica que ahí no se graba: que grabe con otra app y la
+procese con `recap import <archivo>`. Si arrancaste por bita, confirma
+con `recap status` que la grabación empezó.
+
+Responde en una línea: modo, título, que ya está grabando y el id de bita si
+arrancó por ahí. Nada más.

package/commands/recap-status.md

@@ -0,0 +1,14 @@
+---
+description: Muestra si se está grabando y en qué va la última reunión
+allowed-tools: Bash(recap status:*)
+---
+
+!`recap status --json`
+
+Resume en una o dos líneas:
+
+- Si `data.recording` es true: modo, título y tiempo transcurrido.
+- Si no: que no se está grabando, y el estado de la última reunión
+  (`data.latest.status`). Si está en `processing`, di qué etapas ya están en
+  `done` dentro de `data.latest.stages`. Si alguna está en `failed`, muestra
+  su error.

package/commands/recap-stop.md

@@ -0,0 +1,69 @@
+---
+description: Termina la grabación y deja la reunión documentada
+argument-hint: [--no-wait para no esperar el resultado]
+allowed-tools: Bash(recap stop:*), Bash(recap status:*), Bash(recap wait:*), Bash(recap show:*), Bash(bita stop:*), Bash(bita ls:*), Bash(bita amend:*), Bash(bita docs page move:*), Bash(bita backlog edit:*), Bash(inkwell page move:*), Bash(inkwell backlog edit:*)
+---
+
+Detén la grabación activa y deja la reunión documentada.
+
+Grabación actual:
+
+!`recap status --json`
+
+Si no hay grabación activa (`NOT_RECORDING`), dilo en una línea y termina.
+
+## Si la grabación sigue a un contador de bita
+
+Cuando `data.active.bitaEntryId` trae un id, para **el contador**, no recap. Sin
+`--did` y sin escribir la página:
+
+```
+bita stop <id> --json
+recap wait --bita-entry <id> --json
+```
+
+El hook de bita detiene la grabación y recap hace lo demás:
+
+- transcribe y escribe la minuta;
+- le pone al contador un título real y, si no tenía, su proyecto;
+- crea o completa la página;
+- pasa los pendientes al backlog;
+- deja la minuta en la sección «Reunión» de la entrada.
+
+`recap wait` tarda de uno a cinco minutos en una reunión de una hora: córrelo con
+un timeout amplio (15 min). Si después de un minuto `recap status` sigue
+grabando, el evento no llegó: párala con `recap stop`.
+
+## Si es una grabación suelta
+
+```
+recap stop --json
+recap wait --json
+```
+
+## Qué responder
+
+Con el resultado de `recap wait` responde:
+
+- título y duración;
+- con bita: el proyecto, la página (`wrapup.pageId`) y cuántos pendientes y
+  hallazgos quedaron en el backlog;
+- sin bita: los **Acuerdos** y **Pendientes** de la minuta, tal cual.
+
+Si una etapa falló, muestra su error y sugiere `recap process <id>`: retoma
+desde la etapa que falló.
+
+**Si `wrapup.projectResolved` es false**, pregunta solo «¿De qué proyecto fue?»
+y, con la respuesta:
+
+```
+bita amend <entryId> --project <X>
+bita docs page move <pageId> --project <X>
+bita backlog edit <CLAVE> --project <X>      # una por cada valor de wrapup.backlogKeys
+```
+
+Si inkwell está instalado, usa `inkwell page move <pageId> --project <X>` e
+`inkwell backlog edit <CLAVE> --project <X>` en lugar de los dos últimos.
+
+Con `--no-wait` en `$ARGUMENTS`, solo para y responde en una línea que el
+procesamiento sigue en segundo plano.

package/commands/recap-summarize.md

@@ -0,0 +1,31 @@
+---
+description: Rehace la minuta de una reunión dentro de la sesión, con indicaciones
+argument-hint: [id o "last"] [indicaciones, p. ej. "enfócate en los riesgos"]
+allowed-tools: Bash(recap prompt:*), Bash(recap save-summary:*), Bash(recap show:*), Read, Write
+---
+
+Rehaz la minuta de una reunión aquí mismo, en lugar del `claude -p` sin
+supervisión del pipeline.
+
+1. El primer token de `$ARGUMENTS` es la reunión (id, parte del id o `last`);
+   si no parece un id, usa `last`. El resto son indicaciones del usuario.
+2. Obtén las instrucciones completas, con la transcripción y la lista de
+   capturas:
+
+   ```
+   recap prompt <reunión>
+   ```
+
+3. Síguelas al pie de la letra. Las rutas de las capturas son relativas al
+   directorio que aparece en la primera línea; ábrelas con Read cuando el tema
+   lo amerite. Aplica las indicaciones del usuario encima de esas
+   instrucciones, sin romper la estructura de secciones.
+4. Escribe la minuta, empezando por `## Resumen`, en un archivo del directorio
+   temporal de la sesión, y guárdala:
+
+   ```
+   recap save-summary <reunión> <archivo>
+   ```
+
+Responde con los **Acuerdos** y **Pendientes** de la nueva minuta y la ruta de
+`summary.md`.

package/dist/bin/recap.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../cli/router.js";
+const code = await main(process.argv.slice(2));
+process.exitCode = code;

package/dist/bita/client.js

@@ -0,0 +1,155 @@
+import path from 'node:path';
+import { findTool, invokeTool } from '@kikedealba/kit/registry';
+import { parseEnvelope } from '@kikedealba/kit/envelope';
+import { isRecord } from "../core/json.js";
+import { home } from "../core/paths.js";
+import { exec } from "../core/proc.js";
+import { suffix, trimmed } from "../core/text.js";
+import { locateTool, toolEnvironment } from "../core/tools.js";
+import { RecapError, errorMessage } from "../errors.js";
+export function parseResponse(stdout, stderr, status) {
+    const envelope = parseEnvelope(stdout);
+    const error = isRecord(envelope?.['error']) ? envelope['error'] : undefined;
+    const ok = status === 0 && envelope?.['ok'] === true;
+    return {
+        ok,
+        data: envelope?.['data'],
+        meta: isRecord(envelope?.['meta']) ? envelope['meta'] : undefined,
+        errorCode: typeof error?.['code'] === 'string' ? error['code'] : undefined,
+        errorMessage: typeof error?.['message'] === 'string' ? error['message'] : ok ? undefined : suffix(trimmed(stdout + stderr), 300),
+    };
+}
+export async function callBita(bita, args) {
+    const response = await bita.invoke(args);
+    if (!response.ok)
+        throw new RecapError('BITA_FAILED', `bita ${args.slice(0, 3).join(' ')} failed: ${response.errorMessage ?? 'no reason given'}`);
+    return response.data;
+}
+export const QUIET_ENV = { BITA_NO_HOOKS: '1', KIT_NO_EVENTS: '1' };
+export function neutralCwd() {
+    return path.parse(home()).root || '/';
+}
+export async function bitaCommand(config) {
+    const registered = await findTool('bita').catch(() => null);
+    if (registered)
+        return registered.bin;
+    const located = await locateTool('bita', config);
+    return located ? [located] : null;
+}
+export class BitaClient {
+    command;
+    config;
+    target;
+    constructor(command, config, target) {
+        this.command = command;
+        this.config = config;
+        this.target = target;
+    }
+    static async create(config, target) {
+        const command = await bitaCommand(config);
+        return command ? new BitaClient(command, config, target) : null;
+    }
+    targetArgs() {
+        const args = [];
+        if (this.target.databasePath)
+            args.push('--db-path', this.target.databasePath);
+        if (this.target.docsRoot)
+            args.push('--docs-dir', this.target.docsRoot);
+        return args;
+    }
+    async run(args) {
+        const [executable, ...prefix] = this.command;
+        if (!executable)
+            throw new RecapError('DEPENDENCY_MISSING', 'bita not found');
+        const env = { ...toolEnvironment(executable, this.config), ...QUIET_ENV };
+        return exec(executable, [...prefix, ...args], { env, cwd: neutralCwd() });
+    }
+    async invoke(args) {
+        const result = await this.run([...args, '--json', ...this.targetArgs()]);
+        return parseResponse(result.stdout, result.stderr, result.status);
+    }
+}
+export function inkwellArguments(args) {
+    if (args[0] === 'backlog')
+        return [...args];
+    if (args[0] !== 'docs')
+        return null;
+    if (args[1] === 'propose')
+        return ['git', 'propose', ...args.slice(2)];
+    return args.slice(1);
+}
+let inkwellCache = null;
+export function resetInkwellCache() {
+    inkwellCache = null;
+}
+async function discoverInkwell() {
+    if (process.env['RECAP_NO_INKWELL'] === '1')
+        return null;
+    const tool = await findTool('inkwell', { capability: 'docs.page.write' }).catch(() => null);
+    if (!tool)
+        return null;
+    try {
+        const { envelope } = await invokeTool(tool, ['migrate', 'status'], { env: { ...process.env, ...QUIET_ENV }, timeoutMs: 20_000 });
+        return envelope.ok && envelope.data?.migrated === true ? tool : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function findInkwell() {
+    inkwellCache ??= discoverInkwell();
+    return inkwellCache;
+}
+export class InkwellClient {
+    tool;
+    constructor(tool) {
+        this.tool = tool;
+    }
+    async invoke(args) {
+        try {
+            const { envelope } = await invokeTool(this.tool, args, { env: { ...process.env, ...QUIET_ENV }, cwd: neutralCwd(), timeoutMs: 300_000 });
+            return {
+                ok: envelope.ok,
+                data: envelope.data,
+                meta: envelope.meta,
+                errorCode: envelope.error?.code,
+                errorMessage: envelope.error?.message,
+            };
+        }
+        catch (error) {
+            return { ok: false, errorCode: 'INKWELL_FAILED', errorMessage: errorMessage(error) };
+        }
+    }
+}
+export class DocsRouter {
+    bita;
+    inkwell;
+    constructor(bita, inkwell) {
+        this.bita = bita;
+        this.inkwell = inkwell;
+    }
+    async invoke(args) {
+        const mapped = this.inkwell ? inkwellArguments(args) : null;
+        if (mapped && this.inkwell)
+            return this.inkwell.invoke(mapped);
+        if (this.bita)
+            return this.bita.invoke(args);
+        return { ok: false, errorCode: 'DEPENDENCY_MISSING', errorMessage: 'bita not found' };
+    }
+}
+export function meetingTarget(meeting) {
+    return { databasePath: meeting.bitaDatabasePath, docsRoot: meeting.bitaDocsRoot };
+}
+export async function docsClient(config, target) {
+    const bita = await BitaClient.create(config, target);
+    const inkwell = await findInkwell();
+    if (!bita && !inkwell)
+        return null;
+    return new DocsRouter(bita, inkwell ? new InkwellClient(inkwell) : null);
+}
+export async function requireBita(config, target) {
+    const client = await BitaClient.create(config, target);
+    if (!client)
+        throw new RecapError('DEPENDENCY_MISSING', 'bita not found. Install it with `npm install -g @kikedealba/bita`', { hint: 'npm install -g @kikedealba/bita' });
+    return client;
+}

package/dist/bita/hook.js

@@ -0,0 +1,81 @@
+import { isRecord } from "../core/json.js";
+export const MEETING_KINDS = {
+    'remote-meeting': 'remote',
+    'in-person-meeting': 'in-person',
+};
+export const HOOK_EVENTS = ['start', 'stop', 'cancel', 'amend'];
+function optionalString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+export function decodeHookEvent(text) {
+    const value = JSON.parse(text);
+    if (!isRecord(value) || typeof value['event'] !== 'string' || !isRecord(value['entry']))
+        throw new Error('the event has no event name or entry');
+    const entry = value['entry'];
+    if (typeof entry['id'] !== 'number' || !Number.isInteger(entry['id']) || typeof entry['description'] !== 'string')
+        throw new Error('the entry has no id or description');
+    const pageIds = Array.isArray(value['pageIds']) ? value['pageIds'].filter((id) => typeof id === 'number' && Number.isInteger(id)) : undefined;
+    return {
+        event: value['event'],
+        entry: {
+            id: entry['id'],
+            description: entry['description'],
+            kind: optionalString(entry['kind']),
+            running: typeof entry['running'] === 'boolean' ? entry['running'] : undefined,
+            projectName: optionalString(entry['projectName']),
+        },
+        previousKind: optionalString(value['previousKind']),
+        databasePath: optionalString(value['databasePath']),
+        docsRoot: optionalString(value['docsRoot']),
+        pageIds,
+    };
+}
+export function eventSnapshot(event) {
+    return { title: event.entry.description, projectName: event.entry.projectName, kind: event.entry.kind, pageIds: event.pageIds ?? [] };
+}
+export function eventMode(event) {
+    return event.entry.kind === undefined ? undefined : MEETING_KINDS[event.entry.kind];
+}
+export function previousMode(event) {
+    return event.previousKind === undefined ? undefined : MEETING_KINDS[event.previousKind];
+}
+export function eventTarget(event) {
+    return { databasePath: event.databasePath, docsRoot: event.docsRoot };
+}
+export function describeAction(action) {
+    switch (action.type) {
+        case 'start':
+            return `start(${action.mode})`;
+        case 'ignore':
+            return `ignore(${action.reason})`;
+        default:
+            return action.type;
+    }
+}
+export function planHook(event, activeEntryId) {
+    const isActive = activeEntryId === event.entry.id;
+    const mode = eventMode(event);
+    switch (event.event) {
+        case 'start':
+            if (!mode)
+                return { type: 'ignore', reason: `entry #${event.entry.id} is not a meeting` };
+            return activeEntryId === undefined ? { type: 'start', mode } : { type: 'ignore', reason: 'another meeting is already being recorded' };
+        case 'stop':
+            return isActive ? { type: 'stopAndProcess' } : { type: 'processIfRecorded' };
+        case 'cancel':
+            return { type: 'discard' };
+        case 'amend': {
+            const previous = previousMode(event);
+            if (mode && previous === undefined) {
+                if (event.entry.running === false)
+                    return { type: 'ignore', reason: `entry #${event.entry.id} already stopped` };
+                return activeEntryId === undefined ? { type: 'start', mode } : { type: 'ignore', reason: 'another meeting is already being recorded' };
+            }
+            if (mode === undefined && previous !== undefined && isActive)
+                return { type: 'stopWithoutProcessing' };
+            return { type: 'ignore', reason: 'kind change does not affect the recording' };
+        }
+        default:
+            return { type: 'ignore', reason: `unknown event ${event.event}` };
+    }
+}