@neonexai/beebole-mcp 1.0.0

package/README.md

@@ -0,0 +1,157 @@
+# @neonexai/beebole-mcp
+
+MCP server que conecta **Claude** (Claude Code / Claude Desktop) con **Beebole**
+(control de horas) a través de su **API GraphQL nueva** — la de la app rediseñada
+**`app.beebole.com`**.
+
+- **Endpoint:** `POST https://app.beebole.com/graphql`
+- **Auth:** cabecera `apikey: <API_KEY>` (la key se obtiene en `app.beebole.com → Settings → API`).
+- **Verificado e2e** (2026-06-25) contra la API real: 18/18 checks de lectura y
+  escritura (crear proyecto/tarea, fichar horas, editar, borrar, limpiar).
+
+Dos transportes:
+
+- **Local (stdio)** — *recomendado (GDPR)*: corre en el PC del cliente; su API key
+  vive solo en su máquina y los datos no pasan por ningún servidor intermedio.
+- **Remoto (HTTP, VPS)** — centralizado; el token viaja por cabecera
+  `X-Beebole-Key` en cada petición y **no se almacena** (stateless multi-tenant).
+
+---
+
+## Arquitectura: híbrida (curadas + passthrough)
+
+La API GraphQL nueva es enorme y *fine-grained*: **87 queries + 745 mutations**
+(cada campo editable tiene su propia mutation). Exponer eso 1:1 saturaría a
+cualquier agente. Por eso el server combina dos capas:
+
+**A) ~24 tools curadas** para el flujo real de un estudio:
+
+| Área | Tools |
+|---|---|
+| Identidad | `beebole_whoami` |
+| Proyectos | `beebole_list_projects`, `beebole_get_project`, `beebole_add_project` |
+| Tareas | `beebole_list_tasks`, `beebole_get_task`, `beebole_add_task` |
+| Personas | `beebole_list_persons`, `beebole_get_person`, `beebole_add_person` |
+| Fichaje de horas | `beebole_list_time_records`, `beebole_count_time_records`, `beebole_add_time_record`, `beebole_edit_time_record`, `beebole_delete_time_records`, `beebole_clone_time_records` |
+| Timesheets | `beebole_submit_timesheet`, `beebole_approve_timesheet`, `beebole_reject_timesheet` |
+| Catálogos | `beebole_list_tags`, `beebole_list_absence_types` |
+| Informes | `beebole_list_reports`, `beebole_run_report`, `beebole_planned_vs_real` |
+
+**B) 3 tools genéricas** para cobertura del **100%** de la API (las ~800
+operaciones restantes de administración/configuración):
+
+- `beebole_search_schema` — descubre cualquier operación por palabra clave.
+- `beebole_describe_operation` — su firma completa (args + input objects + retorno).
+- `beebole_graphql` — ejecuta cualquier query/mutation cruda.
+
+Flujo para algo sin tool curada: **search → describe → graphql**.
+
+### Notas de dominio (del propio schema)
+
+- **Timestamps**: `BeeboleTimestamp` = Unix epoch en **milisegundos** (`> 1e10`).
+- **Duración** de un time record: entero en **minutos** (ej. `90` = 1 h 30 min).
+  Beebole lo interpreta según los *time settings* de la organización; confírmalo
+  visualmente la primera vez.
+- **Estados** (`status`): `d`=draft, `s`=submitted, `a`=approved, `r`=rejected.
+- **Color**: índice de paleta `0-71`. **Ausencias**: unidad `day` o `hour`.
+- `addProject` / `addTask` requieren **`categoryId` o `parentId`** (la API
+  rechaza con `NoCategoryOrParentProvided` si no se da ninguno).
+
+---
+
+## Instalación
+
+Requisitos: **Node ≥ 18** y una **API key de Beebole** (`app.beebole.com → Settings → API`).
+
+### A) Local en el PC del cliente (recomendado · stdio)
+
+Se ejecuta directamente desde GitHub con `npx`, sin clonar nada:
+
+```bash
+claude mcp add beebole \
+  --env BEEBOLE_API_KEY=TU_API_KEY \
+  -- npx -y github:NeoNexAI/beebole-mcp
+```
+
+- `-s user` (scope usuario) lo deja disponible en **todos los proyectos** de ese PC:
+  ```bash
+  claude mcp add beebole -s user --env BEEBOLE_API_KEY=TU_API_KEY -- npx -y github:NeoNexAI/beebole-mcp
+  ```
+- En **Claude Desktop**, añade el bloque equivalente en su `mcp.json`:
+  ```json
+  {
+    "mcpServers": {
+      "beebole": {
+        "command": "npx",
+        "args": ["-y", "github:NeoNexAI/beebole-mcp"],
+        "env": { "BEEBOLE_API_KEY": "TU_API_KEY" }
+      }
+    }
+  }
+  ```
+
+Verifica la key **antes** de añadirlo (debe responder con tu nombre):
+
+```bash
+curl -s -H "apikey: TU_API_KEY" -H "Content-Type: application/json" \
+  -X POST https://app.beebole.com/graphql \
+  -d '{"query":"{ currentPerson{ id name email } }"}'
+```
+
+### B) Despliegue para un equipo (plan Team)
+
+No hay un “instalar para toda la organización” de un click para un MCP propio: cada
+equipo lo corre **en local** (stdio) con la API key correspondiente. Para
+estandarizarlo en varios PCs:
+
+- **Misma cuenta Beebole de empresa** → repartid la **misma API key** (cada PC la
+  pone en su `BEEBOLE_API_KEY`; nunca en el repo).
+- **Cada persona con su propio usuario Beebole** → cada PC usa **su** API key (el
+  server actúa siempre como esa persona).
+- Para fijar la config en un repo compartido, commitea un `.mcp.json` (scope
+  *project*) **sin la key** y que cada entorno aporte `BEEBOLE_API_KEY` por
+  variable de entorno. La key es un secreto: **nunca** se commitea.
+
+> Alternativa centralizada: desplegar el modo **HTTP** en el VPS (un solo sitio) y
+> que cada cliente Claude apunte ahí enviando su token por `X-Beebole-Key`. Útil si
+> no quieres instalar Node en cada PC; menos recomendable para datos GDPR sensibles.
+
+---
+
+## Desarrollo
+
+```bash
+npm install
+npm run build          # tsc → dist/  (incluye schema.json para selección/búsqueda)
+npm run typecheck
+BEEBOLE_API_KEY=... npm run smoke           # 9 checks de lectura e2e
+BEEBOLE_API_KEY=... SMOKE_WRITE=1 npm run smoke   # + ciclo de escritura (SOLO cuenta de pruebas)
+```
+
+El `smoke` con `SMOKE_WRITE=1` crea entidades `ZZ_SMOKE_TEST_*`, ficha, edita y
+**borra todo** al terminar; úsalo solo en una cuenta de pruebas.
+
+### Modo HTTP (VPS)
+
+```bash
+MCP_TRANSPORT=http PORT=8087 node dist/index.js
+# POST /mcp con cabecera X-Beebole-Key: <token>   ·   GET /health
+```
+
+---
+
+## Estructura
+
+```
+src/
+  index.ts    — entry point (stdio | HTTP)
+  client.ts   — cliente GraphQL (auth apikey) + helpers de schema (selección/búsqueda/describe)
+  tools.ts    — registro de las 27 tools (factoría buildServer(apiKey))
+  smoke.ts    — test e2e contra la API real
+schema.json   — introspección de la API (bundleada; potencia selección + search/describe)
+```
+
+---
+
+*Beebole API GraphQL — auth y endpoint verificados empíricamente 2026-06-25. Las
+funciones de Beebole evolucionan; reverificar en `app.beebole.com` ante cambios.*

package/dist/client.js

@@ -0,0 +1,231 @@
+/**
+ * Cliente de la API GraphQL de Beebole (app nueva, app.beebole.com).
+ *
+ *   - Endpoint:  POST https://app.beebole.com/graphql
+ *   - Auth:      cabecera  apikey: <API_KEY>   (verificado empíricamente 2026-06-25;
+ *                la key se encuentra en app.beebole.com › Settings › API)
+ *   - Respuesta: { data, errors?, permissionsErrors? }
+ *
+ * La API GraphQL nueva es fine-grained (87 queries + 745 mutations). Este cliente
+ * expone:
+ *   1) `graphql()` — ejecutor crudo (lo usan las tools curadas y el passthrough).
+ *   2) Helpers de SCHEMA bundleado (schema.json en la raíz del paquete):
+ *        - `selection()`  genera selection-sets válidos sin hardcodear 267 tipos.
+ *        - `searchOps()`  descubre operaciones por palabra clave.
+ *        - `describeOp()` da la firma completa (args + input fields + retorno).
+ *
+ * Notas de dominio (de las descripciones del schema):
+ *   - BeeboleTimestamp = Unix epoch en MILISEGUNDOS (> 1e10).
+ *   - BeeboleApprovalStatus: d=draft, s=submitted, a=approved, r=rejected.
+ *   - BeeboleColor: índice de paleta 0-71.  BeeboleAbsenceUnit: day|hour.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+export const BEEBOLE_GRAPHQL_ENDPOINT = process.env.BEEBOLE_GRAPHQL_ENDPOINT?.trim() || 'https://app.beebole.com/graphql';
+export class BeeboleError extends Error {
+}
+const schemaPath = fileURLToPath(new URL('../schema.json', import.meta.url));
+const SCHEMA = JSON.parse(readFileSync(schemaPath, 'utf8')).data.__schema;
+const TYPES = new Map();
+for (const t of SCHEMA.types)
+    if (t.name)
+        TYPES.set(t.name, t);
+const QUERY_TYPE = TYPES.get(SCHEMA.queryType.name);
+const MUTATION_TYPE = SCHEMA.mutationType ? TYPES.get(SCHEMA.mutationType.name) ?? null : null;
+function unwrap(t) {
+    let cur = t ?? null;
+    while (cur && cur.ofType)
+        cur = cur.ofType;
+    return cur;
+}
+/** Render legible de un TypeRef: BeeboleId!, [BeeboleId], etc. */
+export function typeStr(t) {
+    if (!t)
+        return '?';
+    if (t.kind === 'NON_NULL')
+        return `${typeStr(t.ofType)}!`;
+    if (t.kind === 'LIST')
+        return `[${typeStr(t.ofType)}]`;
+    return t.name ?? '?';
+}
+function isLeaf(typeName) {
+    if (!typeName)
+        return true;
+    const t = TYPES.get(typeName);
+    return !t || t.kind === 'SCALAR' || t.kind === 'ENUM';
+}
+/** Campos "resumen" de un objeto para profundidad de corte (id/name/fecha…). */
+function shallow(typeName) {
+    if (!typeName)
+        return '';
+    const t = TYPES.get(typeName);
+    if (!t || !t.fields)
+        return '';
+    const want = new Set(['id', 'name', 'iso', 'ts', 'email', 'status', 'duration', 'color', 'archived']);
+    return t.fields
+        .filter((f) => !(f.args && f.args.length) && want.has(f.name) && isLeaf(unwrap(f.type)?.name))
+        .map((f) => f.name)
+        .join(' ');
+}
+/**
+ * Genera un selection-set GraphQL válido para un tipo OBJECT a partir del schema.
+ * `depth` = niveles de expansión COMPLETA; más allá, los objetos se resumen a
+ * {id name …}. depth=0 → escalares del tipo + objetos anidados resumidos
+ * (ideal para listados); depth=1 → además expande un nivel (ideal para "get").
+ * Salta campos que requieren argumentos (evita queries inválidas) y cicla-protege.
+ */
+export function selection(typeName, depth = 0, _seen = new Set()) {
+    const t = TYPES.get(typeName);
+    if (!t || !t.fields)
+        return '';
+    if (_seen.has(typeName))
+        return '';
+    const seen = new Set(_seen);
+    seen.add(typeName);
+    const parts = [];
+    for (const f of t.fields) {
+        if (f.args && f.args.length)
+            continue;
+        const baseName = unwrap(f.type)?.name;
+        if (isLeaf(baseName)) {
+            parts.push(f.name);
+            continue;
+        }
+        if (depth <= 0) {
+            const sh = shallow(baseName);
+            if (sh)
+                parts.push(`${f.name}{ ${sh} }`);
+            continue;
+        }
+        const sub = selection(baseName, depth - 1, seen);
+        if (sub)
+            parts.push(`${f.name}{ ${sub} }`);
+    }
+    return parts.join(' ');
+}
+function opSignature(f) {
+    const args = (f.args ?? []).map((a) => `${a.name}: ${typeStr(a.type)}`).join(', ');
+    return `${f.name}(${args}): ${typeStr(f.type)}`;
+}
+function allOps() {
+    const out = [];
+    for (const f of QUERY_TYPE.fields ?? [])
+        out.push({ kind: 'query', name: f.name, description: f.description ?? '', signature: opSignature(f) });
+    for (const f of MUTATION_TYPE?.fields ?? [])
+        out.push({ kind: 'mutation', name: f.name, description: f.description ?? '', signature: opSignature(f) });
+    return out;
+}
+/** Busca operaciones (query+mutation) cuyo nombre o descripción casan TODAS las palabras. */
+export function searchOps(keyword, limit = 40) {
+    const terms = keyword.toLowerCase().split(/\s+/).filter(Boolean);
+    const hits = allOps().filter((o) => {
+        const hay = `${o.name} ${o.description}`.toLowerCase();
+        return terms.every((t) => hay.includes(t));
+    });
+    // Prioriza match en nombre sobre match solo en descripción.
+    hits.sort((a, b) => {
+        const an = terms.every((t) => a.name.toLowerCase().includes(t)) ? 0 : 1;
+        const bn = terms.every((t) => b.name.toLowerCase().includes(t)) ? 0 : 1;
+        return an - bn || a.name.localeCompare(b.name);
+    });
+    return hits.slice(0, limit);
+}
+/** Firma completa de una operación, con expansión de los input objects (1 nivel). */
+export function describeOp(name) {
+    const f = (QUERY_TYPE.fields ?? []).find((x) => x.name === name) ??
+        (MUTATION_TYPE?.fields ?? []).find((x) => x.name === name);
+    if (!f)
+        return null;
+    const kind = (QUERY_TYPE.fields ?? []).some((x) => x.name === name) ? 'query' : 'mutation';
+    const lines = [`${kind} ${opSignature(f)}`];
+    if (f.description)
+        lines.push(`  // ${f.description}`);
+    for (const a of f.args ?? []) {
+        const baseName = unwrap(a.type)?.name;
+        const it = baseName ? TYPES.get(baseName) : null;
+        if (it && it.kind === 'INPUT_OBJECT' && it.inputFields?.length) {
+            lines.push(`  input ${baseName} {`);
+            for (const inf of it.inputFields)
+                lines.push(`    ${inf.name}: ${typeStr(inf.type)}`);
+            lines.push('  }');
+        }
+        if (it && it.kind === 'SCALAR' && it.description) {
+            lines.push(`  scalar ${baseName}: ${it.description}`);
+        }
+    }
+    const retName = unwrap(f.type)?.name;
+    if (retName && !isLeaf(retName))
+        lines.push(`  returns ${retName} { ${selection(retName, 0)} }`);
+    return lines.join('\n');
+}
+// ── Cliente HTTP ────────────────────────────────────────────────────────────
+export class BeeboleClient {
+    apiKey;
+    endpoint;
+    constructor(apiKey, endpoint = BEEBOLE_GRAPHQL_ENDPOINT) {
+        this.apiKey = apiKey;
+        if (!apiKey || !apiKey.trim())
+            throw new BeeboleError('Falta la API key de Beebole.');
+        this.endpoint = endpoint;
+    }
+    /** Ejecuta una operación GraphQL. Devuelve `data`; lanza BeeboleError accionable. */
+    async graphql(query, variables = {}) {
+        let res;
+        try {
+            res = await fetch(this.endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json',
+                    apikey: this.apiKey,
+                },
+                body: JSON.stringify({ query, variables }),
+                signal: AbortSignal.timeout(60_000),
+            });
+        }
+        catch (err) {
+            throw new BeeboleError(`No se pudo contactar con Beebole: ${err.message}`);
+        }
+        const text = await res.text();
+        if (res.status === 401 || res.status === 403) {
+            throw new BeeboleError('Beebole rechazó la API key (HTTP ' +
+                res.status +
+                '). Verifica la key y que el acceso API esté habilitado en app.beebole.com › Settings.');
+        }
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            throw new BeeboleError(`Respuesta no-JSON de Beebole (HTTP ${res.status}): ${text.slice(0, 200)}`);
+        }
+        if (body.errors?.length) {
+            throw new BeeboleError('Beebole GraphQL error: ' + body.errors.map((e) => e.message).join('; ').slice(0, 500));
+        }
+        const data = body.data;
+        const dataEmpty = !data ||
+            typeof data !== 'object' ||
+            Object.keys(data).length === 0 ||
+            Object.values(data).every((v) => v == null);
+        if (body.permissionsErrors?.length && dataEmpty) {
+            throw new BeeboleError('Beebole denegó permisos para: ' +
+                body.permissionsErrors.join(', ') +
+                '. La API key necesita un rol con acceso a esos datos.');
+        }
+        return (data ?? {});
+    }
+}
+/**
+ * Construye `(decls)` y `(args)` GraphQL solo con los argumentos definidos, más
+ * el objeto de variables. Evita "variable never used" declarando únicamente lo
+ * que se pasa. Cada spec: { name, type (GraphQL), value }.
+ */
+export function gqlArgs(spec) {
+    const used = spec.filter((s) => s.value !== undefined && s.value !== null);
+    const decls = used.map((s) => `$${s.name}: ${s.type}`).join(', ');
+    const args = used.map((s) => `${s.name}: $${s.name}`).join(', ');
+    const variables = {};
+    for (const s of used)
+        variables[s.name] = s.value;
+    return { decls: decls ? `(${decls})` : '', args: args ? `(${args})` : '', variables };
+}

package/dist/index.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * Entry point del MCP de Beebole. Dos modos:
+ *
+ *   1) STDIO (por defecto, recomendado / local en el PC del cliente):
+ *      el token vive en la variable de entorno BEEBOLE_API_KEY del propio PC.
+ *      Uso:  npx @neonexai/beebole-mcp     (con BEEBOLE_API_KEY exportada)
+ *
+ *   2) HTTP remoto (VPS, MCP_TRANSPORT=http): stateless, multi-tenant. El token
+ *      llega en la cabecera X-Beebole-Key en CADA petición y NO se almacena.
+ *      Uso:  MCP_TRANSPORT=http PORT=8087 node dist/index.js
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import express from 'express';
+import { buildServer } from './tools.js';
+async function runStdio() {
+    const token = process.env.BEEBOLE_API_KEY ?? '';
+    if (!token.trim()) {
+        process.stderr.write('[beebole-mcp] Falta BEEBOLE_API_KEY en el entorno.\n');
+        process.exit(1);
+    }
+    const server = buildServer(token);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write('[beebole-mcp] stdio listo.\n');
+}
+function runHttp() {
+    const port = Number(process.env.PORT ?? 8087);
+    const app = express();
+    app.use(express.json({ limit: '1mb' }));
+    // Health check (sin auth) para nginx/Coolify.
+    app.get('/health', (_req, res) => {
+        res.json({ ok: true, service: 'beebole-mcp' });
+    });
+    // MCP endpoint stateless: un server efímero por petición, ligado al token del header.
+    app.post('/mcp', async (req, res) => {
+        const token = (req.header('x-beebole-key') ?? '').trim();
+        if (!token) {
+            res.status(401).json({
+                jsonrpc: '2.0',
+                error: { code: -32001, message: 'Falta la cabecera X-Beebole-Key.' },
+                id: null,
+            });
+            return;
+        }
+        const server = buildServer(token);
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+        res.on('close', () => {
+            transport.close();
+            server.close();
+        });
+        try {
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (err) {
+            process.stderr.write(`[beebole-mcp] error HTTP: ${err.message}\n`);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: '2.0',
+                    error: { code: -32603, message: 'Error interno del servidor MCP.' },
+                    id: null,
+                });
+            }
+        }
+    });
+    app.listen(port, () => {
+        process.stderr.write(`[beebole-mcp] HTTP stateless escuchando en :${port} (POST /mcp)\n`);
+    });
+}
+if ((process.env.MCP_TRANSPORT ?? '').toLowerCase() === 'http') {
+    runHttp();
+}
+else {
+    runStdio().catch((err) => {
+        process.stderr.write(`[beebole-mcp] fallo al iniciar: ${err.message}\n`);
+        process.exit(1);
+    });
+}

package/dist/smoke.js

@@ -0,0 +1,138 @@
+/**
+ * Smoke test e2e contra la API GraphQL real de Beebole (app.beebole.com/graphql).
+ *
+ * Uso:
+ *   BEEBOLE_API_KEY=<key> npm run smoke
+ *   BEEBOLE_API_KEY=<key> SMOKE_WRITE=1 npm run smoke   ← incluye un ciclo de
+ *       escritura (crear proyecto → fichar → editar → borrar → archivar) que
+ *       SOLO debe usarse en una cuenta de PRUEBAS (deja todo limpio al terminar).
+ *
+ * Salida: lista de checks con OK/FALLO y un resumen. Código de salida ≠ 0 si algo
+ * falla, para poder usarlo en CI / como gate de "operativo-verificado".
+ */
+import { BeeboleClient } from './client.js';
+const key = (process.env.BEEBOLE_API_KEY ?? '').trim();
+if (!key) {
+    process.stderr.write('Falta BEEBOLE_API_KEY en el entorno.\n');
+    process.exit(2);
+}
+const beebole = new BeeboleClient(key);
+let ok = 0;
+let fail = 0;
+async function check(name, fn) {
+    try {
+        const detail = await fn();
+        ok++;
+        process.stdout.write(`  ✓ ${name}${detail ? ` — ${detail}` : ''}\n`);
+    }
+    catch (err) {
+        fail++;
+        process.stdout.write(`  ✗ ${name} — ${err.message}\n`);
+    }
+}
+const now = Date.now();
+const days30 = 30 * 24 * 60 * 60 * 1000;
+async function main() {
+    process.stdout.write('\n== Beebole GraphQL smoke (lectura) ==\n');
+    await check('currentPerson', async () => {
+        const d = await beebole.graphql('{ currentPerson{ id name email } }');
+        if (!d.currentPerson?.id)
+            throw new Error('sin currentPerson');
+        return `${d.currentPerson.name} <${d.currentPerson.email}>`;
+    });
+    await check('currentOrganisation', async () => {
+        const d = await beebole.graphql('{ currentOrganisation{ id name } }');
+        return d.currentOrganisation?.name ?? '(sin nombre)';
+    });
+    await check('getProjects', async () => {
+        const d = await beebole.graphql('{ getProjects{ id name } }');
+        return `${d.getProjects?.length ?? 0} proyectos`;
+    });
+    await check('getTasks', async () => {
+        const d = await beebole.graphql('{ getTasks{ id name } }');
+        return `${d.getTasks?.length ?? 0} tareas`;
+    });
+    await check('getPersons', async () => {
+        const d = await beebole.graphql('{ getPersons{ id name } }');
+        return `${d.getPersons?.length ?? 0} personas`;
+    });
+    await check('getTags', async () => {
+        const d = await beebole.graphql('{ getTags{ id name } }');
+        return `${d.getTags?.length ?? 0} tags`;
+    });
+    await check('getAbsenceTypes', async () => {
+        const d = await beebole.graphql('{ getAbsenceTypes{ id name unit } }');
+        return `${d.getAbsenceTypes?.length ?? 0} tipos`;
+    });
+    await check('getReports', async () => {
+        const d = await beebole.graphql('{ getReports{ id name } }');
+        return `${d.getReports?.length ?? 0} informes`;
+    });
+    await check('countTimeRecords (30d)', async () => {
+        const d = await beebole.graphql('query($s:BeeboleTimestamp,$e:BeeboleTimestamp){ countTimeRecords(startTime:$s,endTime:$e) }', { s: now - days30, e: now });
+        return `${d.countTimeRecords} registros`;
+    });
+    if (process.env.SMOKE_WRITE === '1') {
+        process.stdout.write('\n== Ciclo de ESCRITURA (cuenta de pruebas) ==\n');
+        let projectId = '';
+        let taskId = '';
+        let personId = '';
+        let projectCatId = '';
+        let taskCatId = '';
+        let trId = '';
+        const startOfDay = now - (now % 86_400_000); // medianoche UTC de hoy
+        await check('whoami → personId', async () => {
+            const d = await beebole.graphql('{ currentPerson{ id } }');
+            personId = d.currentPerson.id;
+            return personId;
+        });
+        await check('getProjectCategories + getTaskCategories', async () => {
+            const d = await beebole.graphql('{ getProjectCategories{ id name } getTaskCategories{ id name } }');
+            projectCatId = d.getProjectCategories?.[0]?.id ?? '';
+            taskCatId = d.getTaskCategories?.[0]?.id ?? '';
+            if (!projectCatId || !taskCatId)
+                throw new Error('faltan categorías por defecto');
+            return `projCat=${projectCatId} taskCat=${taskCatId}`;
+        });
+        await check('addProject (con categoría)', async () => {
+            const d = await beebole.graphql('mutation($n:BeeboleName!,$c:BeeboleId){ addProject(name:$n,categoryId:$c){ id name } }', { n: 'ZZ_SMOKE_TEST_PROJECT', c: projectCatId });
+            projectId = d.addProject.id;
+            return projectId;
+        });
+        await check('addTask (con categoría)', async () => {
+            const d = await beebole.graphql('mutation($n:BeeboleName!,$c:BeeboleId){ addTask(name:$n,categoryId:$c){ id name } }', { n: 'ZZ_SMOKE_TEST_TASK', c: taskCatId });
+            taskId = d.addTask.id;
+            return taskId;
+        });
+        await check('assignTaskToProject', async () => {
+            await beebole.graphql('mutation($t:BeeboleId!,$p:BeeboleId!){ assignTaskToProject(taskId:$t,projectId:$p){ id } }', { t: taskId, p: projectId });
+            return 'asignada';
+        });
+        await check('addTimeRecord (90 min)', async () => {
+            const d = await beebole.graphql('mutation($s:BeeboleTimestamp!,$dur:Int!,$p:BeeboleId!,$t:BeeboleId,$pr:[BeeboleId]){ addTimeRecord(startTime:$s,duration:$dur,personId:$p,taskId:$t,projectIds:$pr){ id duration } }', { s: startOfDay, dur: 90, p: personId, t: taskId, pr: projectId ? [projectId] : undefined });
+            trId = d.addTimeRecord.id;
+            return `id=${trId} duration=${d.addTimeRecord.duration}`;
+        });
+        await check('editTimeRecordComment', async () => {
+            const d = await beebole.graphql('mutation($id:BeeboleId!,$c:String!){ editTimeRecordComment(id:$id,comment:$c){ comment } }', { id: trId, c: 'smoke test' });
+            return `comment="${d.editTimeRecordComment.comment}"`;
+        });
+        await check('deleteTimeRecords', async () => {
+            await beebole.graphql('mutation($ids:[BeeboleId!]!){ deleteTimeRecords(ids:$ids){ id } }', { ids: [trId] });
+            return 'borrado';
+        });
+        await check('cleanup: deleteTask + deleteProject', async () => {
+            if (taskId)
+                await beebole.graphql('mutation($id:BeeboleId!){ deleteTask(id:$id){ id } }', { id: taskId });
+            if (projectId)
+                await beebole.graphql('mutation($id:BeeboleId!){ deleteProject(id:$id){ id } }', { id: projectId });
+            return 'borrados';
+        });
+    }
+    process.stdout.write(`\n== Resumen: OK=${ok}  FALLO=${fail} ==\n`);
+    process.exit(fail === 0 ? 0 : 1);
+}
+main().catch((err) => {
+    process.stderr.write(`Smoke abortado: ${err.message}\n`);
+    process.exit(1);
+});