create-byan-agent 2.29.2 → 2.35.0

package/install/templates/_byan/mcp/byan-mcp-server/lib/gdoc-content.js

@@ -0,0 +1,203 @@
+// gdoc-content -- PURE content -> Google Docs API request builders.
+//
+// No network, no googleapis, no I/O : this module turns a plain content object
+// into the deterministic arrays of Docs `batchUpdate` requests that gdoc-client
+// sends. Kept pure so the whole shaping logic is unit-tested without a service
+// account or a network (see test/gdoc-content.test.js).
+//
+// Two modes, mirroring gdoc-client's two paths :
+//   - TEMPLATE mode  : buildReplaceRequests() -> replaceAllText over a branded
+//     template Doc (logo + palette live IN the template ; we only fill text).
+//   - NO-TEMPLATE     : buildDocumentRequests() -> insert a structured text doc
+//     and colour the title + headings from the AcadeNice palette. A logo is
+//     inserted at the top when a PNG URL is provided (opts.logoPngUrl /
+//     GDOC_LOGO_PNG_URL) ; Docs accepts a raster URL (PNG/JPG/GIF), not SVG, so
+//     the URL must point at a PNG. Absent -> the doc is text branded by colour
+//     only (graceful, no image request).
+
+// AcadeNice palette (from the brand charter). Hex here ; converted to the Docs
+// API rgbColor (0..1 floats) by hexToRgbColor.
+const BRANDING = {
+  marine: '#0e2656',
+  teal: '#24947a',
+  turquoise: '#4cccb8',
+};
+
+/**
+ * hexToRgbColor('#0e2656') -> { red, green, blue } each in [0,1], the shape the
+ * Docs API expects under textStyle.foregroundColor.color.rgbColor. Accepts an
+ * optional leading '#' and 3- or 6-digit hex. Throws on malformed input (a bad
+ * palette constant is a programming error, surfaced loudly in tests).
+ * @param {string} hex
+ */
+function hexToRgbColor(hex) {
+  if (typeof hex !== 'string') throw new TypeError('hex must be a string');
+  let h = hex.trim().replace(/^#/, '');
+  if (h.length === 3) h = h.split('').map((c) => c + c).join('');
+  if (!/^[0-9a-fA-F]{6}$/.test(h)) throw new Error(`invalid hex colour: ${hex}`);
+  const n = parseInt(h, 16);
+  return {
+    red: ((n >> 16) & 255) / 255,
+    green: ((n >> 8) & 255) / 255,
+    blue: (n & 255) / 255,
+  };
+}
+
+/**
+ * Normalize + validate the content object. Returns { title, sections, resources,
+ * fields }. Throws a clear error when the minimum (a non-empty title) is missing
+ * -- the caller turns that into a tool error, never a crash.
+ * @param {object} content
+ */
+function normalizeContent(content) {
+  const c = content || {};
+  const title = typeof c.title === 'string' ? c.title.trim() : '';
+  if (!title) throw new Error('content.title is required (non-empty string)');
+  const sections = Array.isArray(c.sections)
+    ? c.sections
+        .map((s) => ({
+          heading: typeof s?.heading === 'string' ? s.heading.trim() : '',
+          body: typeof s?.body === 'string' ? s.body : '',
+        }))
+        .filter((s) => s.heading || s.body)
+    : [];
+  const resources = Array.isArray(c.resources)
+    ? c.resources
+        .map((r) => ({
+          label: typeof r?.label === 'string' ? r.label.trim() : '',
+          url: typeof r?.url === 'string' ? r.url.trim() : '',
+        }))
+        .filter((r) => r.label || r.url)
+    : [];
+  const fields = c.fields && typeof c.fields === 'object' ? c.fields : {};
+  return { title, sections, resources, fields };
+}
+
+/**
+ * TEMPLATE mode. Map the content onto {{PLACEHOLDER}} tokens and emit one
+ * replaceAllText request per token. The template Doc carries the branding ; we
+ * only substitute text. `fields` lets a caller fill arbitrary {{KEY}} tokens
+ * (e.g. {{CANDIDAT}}). Deterministic order (stable for tests).
+ * @param {object} content
+ */
+function buildReplaceRequests(content) {
+  const { title, sections, resources, fields } = normalizeContent(content);
+  const map = {
+    TITLE: title,
+    BLOCS: sections.map((s) => `${s.heading}\n${s.body}`.trim()).join('\n\n'),
+    RESSOURCES: resources.map((r) => (r.url ? `${r.label} : ${r.url}` : r.label)).join('\n'),
+  };
+  for (const [k, v] of Object.entries(fields)) {
+    if (v != null) map[String(k).toUpperCase()] = String(v);
+  }
+  return Object.entries(map).map(([key, value]) => ({
+    replaceAllText: {
+      containsText: { text: `{{${key}}}`, matchCase: true },
+      replaceText: value,
+    },
+  }));
+}
+
+/**
+ * Assemble the flat document text + the index ranges to colour, for NO-TEMPLATE
+ * mode. Docs is 1-indexed (index 1 = first insertable position), so every range
+ * is offset by +1 against the assembled string. Returns { text, titleRange,
+ * headingRanges } with ranges as { startIndex, endIndex } in Docs coordinates.
+ * @param {object} content
+ */
+function assembleDocument(content) {
+  const { title, sections, resources } = normalizeContent(content);
+  const headingRanges = [];
+  let text = '';
+  const DOC_START = 1; // Docs body first insertable index
+
+  const titleStart = DOC_START + text.length;
+  text += `${title}\n\n`;
+  const titleRange = { startIndex: titleStart, endIndex: titleStart + title.length };
+
+  for (const s of sections) {
+    if (s.heading) {
+      const hs = DOC_START + text.length;
+      text += `${s.heading}\n`;
+      headingRanges.push({ startIndex: hs, endIndex: hs + s.heading.length });
+    }
+    if (s.body) text += `${s.body}\n`;
+    text += '\n';
+  }
+
+  if (resources.length) {
+    const rh = 'Ressources';
+    const rhs = DOC_START + text.length;
+    text += `${rh}\n`;
+    headingRanges.push({ startIndex: rhs, endIndex: rhs + rh.length });
+    for (const r of resources) {
+      text += `${r.url ? `${r.label} : ${r.url}` : r.label}\n`;
+    }
+  }
+
+  return { text, titleRange, headingRanges };
+}
+
+/**
+ * NO-TEMPLATE mode. Insert the assembled text at index 1, then colour the title
+ * (marine, bold, larger) and each heading (teal, bold) from the palette. Indices
+ * are valid because the single insertText happens first and every style range is
+ * computed against that one block. Returns the batchUpdate requests array.
+ * @param {object} content
+ * @param {object} [opts]
+ * @param {object} [opts.branding=BRANDING]
+ * @param {string} [opts.logoPngUrl]  PNG URL inserted at the top ; absent -> skipped
+ */
+function buildDocumentRequests(content, opts = {}) {
+  const branding = opts.branding || BRANDING;
+  const { text, titleRange, headingRanges } = assembleDocument(content);
+
+  const requests = [{ insertText: { location: { index: 1 }, text } }];
+
+  requests.push({
+    updateTextStyle: {
+      range: titleRange,
+      textStyle: {
+        bold: true,
+        fontSize: { magnitude: 20, unit: 'PT' },
+        foregroundColor: { color: { rgbColor: hexToRgbColor(branding.marine) } },
+      },
+      fields: 'bold,fontSize,foregroundColor',
+    },
+  });
+
+  for (const range of headingRanges) {
+    requests.push({
+      updateTextStyle: {
+        range,
+        textStyle: {
+          bold: true,
+          fontSize: { magnitude: 14, unit: 'PT' },
+          foregroundColor: { color: { rgbColor: hexToRgbColor(branding.teal) } },
+        },
+        fields: 'bold,fontSize,foregroundColor',
+      },
+    });
+  }
+
+  // Logo last : inserted at index 1 AFTER text+styles, so it lands at the very
+  // top and the already-styled text simply shifts down (styles stay bound to the
+  // characters). Skipped when no PNG URL is configured (graceful). Docs needs a
+  // raster URL (PNG/JPG/GIF) -- a non-PNG/SVG URL is rejected by the API and
+  // surfaces as gdoc-client's api-error, not a crash here.
+  const logoPngUrl = typeof opts.logoPngUrl === 'string' ? opts.logoPngUrl.trim() : '';
+  if (logoPngUrl) {
+    requests.push({ insertInlineImage: { location: { index: 1 }, uri: logoPngUrl } });
+  }
+
+  return requests;
+}
+
+export {
+  BRANDING,
+  hexToRgbColor,
+  normalizeContent,
+  buildReplaceRequests,
+  assembleDocument,
+  buildDocumentRequests,
+};

package/install/templates/_byan/mcp/byan-mcp-server/lib/resolve-config.js

@@ -26,8 +26,18 @@ import nodePath from 'node:path';
 const DEFAULT_API_URL = 'http://localhost:3737';
 
 // Keys the resolver understands. BYAN_API_URL is the only one with a non-empty
-// default; tokens and the optional Leantime URL stay empty when unset.
-const KEYS = ['BYAN_API_URL', 'BYAN_API_TOKEN', 'LEANTIME_API_URL', 'LEANTIME_API_TOKEN'];
+// default; tokens, the optional Leantime URL, and the optional Google Docs
+// publish config (service-account key path, template id, logo URL) stay empty
+// when unset.
+const KEYS = [
+  'BYAN_API_URL',
+  'BYAN_API_TOKEN',
+  'LEANTIME_API_URL',
+  'LEANTIME_API_TOKEN',
+  'GOOGLE_APPLICATION_CREDENTIALS',
+  'GDOC_TEMPLATE_ID',
+  'GDOC_LOGO_PNG_URL',
+];
 
 /**
  * An unexpanded `${...}` placeholder is NOT a real value. It is what a launcher
@@ -98,6 +108,9 @@ function resolveConfig(opts = {}) {
   out.BYAN_API_TOKEN = out.BYAN_API_TOKEN || '';
   out.LEANTIME_API_URL = out.LEANTIME_API_URL || '';
   out.LEANTIME_API_TOKEN = out.LEANTIME_API_TOKEN || '';
+  out.GOOGLE_APPLICATION_CREDENTIALS = out.GOOGLE_APPLICATION_CREDENTIALS || '';
+  out.GDOC_TEMPLATE_ID = out.GDOC_TEMPLATE_ID || '';
+  out.GDOC_LOGO_PNG_URL = out.GDOC_LOGO_PNG_URL || '';
   return out;
 }
 

package/install/templates/_byan/mcp/byan-mcp-server/lib/sync-rules.js

@@ -271,7 +271,7 @@ both gates hold (>= 2 non-substitutable options diverging on >= 1 weighted
 criterion). Emit the marker verbatim before the table:
 \`<!-- BYAN-BENCH:done g1=<#options> g2=<#divergent-criteria> scope=<internal|external> conf=<assertive|lean> -->\`.
 A confirm, a destructive prompt, or an obvious default is not a fork — emit
-\`<!-- BYAN-BENCH:skip reason=.. -->\` instead. Full doctrine: see @.claude/rules/benchmark.md`;
+\`<!-- BYAN-BENCH:skip reason=.. -->\` instead. Full doctrine (loaded on demand): see .claude/rules/benchmark.md`;
 }
 
 // ---------------------------------------------------------------------------

package/install/templates/_byan/mcp/byan-mcp-server/package.json

@@ -14,6 +14,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "google-auth-library": "^9.15.1",
+    "googleapis": "^148.0.0",
     "js-yaml": "^4.1.1"
   },
   "engines": {

package/install/templates/_byan/mcp/byan-mcp-server/server.js

@@ -14,6 +14,7 @@ import { harvest as harvestInsights, renderDigest as renderInsightDigest } from
 import { appendOutcome } from './lib/outcome-buffer.js';
 import { validateForLog, eloOutcomeForStrictComplete } from './lib/advisory-autofeed.js';
 import { readSoul, appendSoulMemory } from './lib/soul.js';
+import { createPublisher as createGdocPublisher } from './lib/gdoc-client.js';
 import {
   start as fdStart,
   status as fdStatus,
@@ -1353,6 +1354,56 @@ const tools = [
       additionalProperties: false,
     },
   },
+
+  // ─── Google Docs publish (service account, headless) ──────────────────
+  // byan-owned, durable publishing : a service-account JWT (no OAuth, no 7-day
+  // expiry) creates a branded Google Doc and returns its URL. Branding via a
+  // template (GDOC_TEMPLATE_ID) or the AcadeNice palette programmatically.
+  {
+    name: 'byan_publish',
+    description:
+      'Publish a branded Google Doc from content via a byan-owned SERVICE ACCOUNT (headless, durable, no OAuth). Copies a branded template when GDOC_TEMPLATE_ID is set (logo+palette in the template), else builds a programmatic doc branded by the AcadeNice palette. Returns the Doc URL; optionally shares it. Needs GOOGLE_APPLICATION_CREDENTIALS (SA key path). Degrades gracefully (ok:false + reason) when unconfigured. NOT remote-safe (network+auth).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string', description: 'Document title (required).' },
+        sections: {
+          type: 'array',
+          description: 'Ordered sections of the document.',
+          items: {
+            type: 'object',
+            properties: {
+              heading: { type: 'string' },
+              body: { type: 'string' },
+            },
+            additionalProperties: false,
+          },
+        },
+        resources: {
+          type: 'array',
+          description: 'Resource links rendered at the end.',
+          items: {
+            type: 'object',
+            properties: { label: { type: 'string' }, url: { type: 'string' } },
+            additionalProperties: false,
+          },
+        },
+        fields: {
+          type: 'object',
+          description: 'Extra {{KEY}} placeholder values for template mode.',
+        },
+        templateId: { type: 'string', description: 'Override GDOC_TEMPLATE_ID for this call.' },
+        shareWith: { type: 'string', description: 'Email address to share the Doc with.' },
+        role: {
+          type: 'string',
+          enum: ['reader', 'commenter', 'writer'],
+          description: 'Share role (default reader).',
+        },
+      },
+      required: ['title'],
+      additionalProperties: false,
+    },
+  },
 ];
 
 // Remote-safe MVP allowlist: the ONLY tools exposed on the remote Org Connector
@@ -2092,6 +2143,25 @@ export function createByanServer({ token, remoteOnly = false } = {}) {
       return { content: [{ type: 'text', text: JSON.stringify(instructions, null, 2) }] };
     }
 
+    // ─── Google Docs publish (service account, headless) ──────────────
+    if (name === 'byan_publish') {
+      const publisher = createGdocPublisher();
+      const result = await publisher.publish(
+        {
+          title: args.title,
+          sections: args.sections,
+          resources: args.resources,
+          fields: args.fields,
+        },
+        {
+          templateId: args.templateId,
+          shareWith: args.shareWith,
+          role: args.role,
+        }
+      );
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }
+
     // ─── Leantime tools ───────────────────────────────────────────────
     if (name === 'byan_leantime_ping') {
       const status = {

package/install/templates/_byan/mcp/byan-mcp-server/skill-bundles-manifest.json

@@ -184,7 +184,7 @@
       "name": "byan-hermes-dispatch",
       "module": "core",
       "tier": "connector-bound",
-      "sourceHash": "62b9c959c77468c0e14e3dfd45039151d29b1bcdc18b04b4d0deac606052a976"
+      "sourceHash": "45003e8a525a792d1a5dbe34ecb8e1443061fa5036a81a38a841598ce5aaf5ff"
     },
     "byan-insight": {
       "name": "byan-insight",

package/install/templates/docs/google-docs-publish.md

@@ -0,0 +1,121 @@
+# byan_publish -- Google Docs brandés, headless (service account)
+
+Le tool MCP `byan_publish` crée un Google Doc brandé depuis un objet de contenu,
+via un **service account que tu fournis** (modèle open-source, voir plus bas) :
+auth JWT durable, sans navigateur, sans refresh token, sans expiration 7 jours.
+C'est le chemin headless (cron, batch, sans humain) -- distinct du connecteur
+OAuth `gdrive`/gw.
+
+## Modèle open-source : chacun fournit SA clé
+
+BYAN est open-source : **aucune clé ne ship** dans le paquet npm. Chaque
+utilisateur fournit SA propre clé service account, sur sa machine. La clé vit
+dans `~/.byan/google-sa.json` (hors dépôt, 0600) et son chemin est persisté dans
+`~/.byan/credentials.json` (`GOOGLE_APPLICATION_CREDENTIALS`) ; le MCP server la
+lit via resolve-config.
+
+## Le setup (à l'install ou à la demande)
+
+L'installeur byan **propose** ce setup (opt-in, défaut non) et il existe aussi en
+commande dédiée :
+
+```bash
+npm run setup-gdoc
+```
+
+Il te guide vers la console Google, importe le JSON téléchargé dans
+`~/.byan/google-sa.json` (0600), et persiste le chemin (+ `GDOC_TEMPLATE_ID` /
+`GDOC_LOGO_PNG_URL` optionnels). Tu peux aussi tout faire à la main (poser le
+fichier + éditer `~/.byan/credentials.json`).
+
+## La seule étape manuelle : créer la clé service account
+
+byan ne peut pas créer cette clé à ta place (Google Cloud IAM est hors de portée
+de ses outils). ~2 minutes, une fois :
+
+1. Projet Google Cloud (idéalement l'org acadenice.fr) :
+   `https://console.cloud.google.com/projectcreate`
+2. Activer les APIs **Google Docs** et **Google Drive** :
+   `https://console.cloud.google.com/apis/library`
+3. Créer un **service account** :
+   `https://console.cloud.google.com/iam-admin/serviceaccounts`
+4. Sur ce service account -> onglet **Keys** -> *Add key* -> *Create new key* ->
+   **JSON** -> télécharger le fichier.
+5. Déposer le JSON sur la machine et pointer `GOOGLE_APPLICATION_CREDENTIALS`
+   dessus, soit en variable d'environnement, soit dans `~/.byan/credentials.json` :
+
+   ```json
+   { "GOOGLE_APPLICATION_CREDENTIALS": "/home/<user>/.byan/google-sa.json" }
+   ```
+
+La clé reste hors du dépôt (env ou `~/.byan/`), donc pas commitée.
+
+## Utilisation
+
+```jsonc
+// byan_publish
+{
+  "title": "Bilan d'évaluation - Alice",
+  "sections": [
+    { "heading": "Bloc 1 - Analyse", "body": "Acquis. ..." },
+    { "heading": "Bloc 2 - Conception", "body": "En cours. ..." }
+  ],
+  "resources": [
+    { "label": "Référentiel", "url": "https://..." }
+  ],
+  "shareWith": "alice@example.org",   // optionnel
+  "role": "reader"                      // reader | commenter | writer
+}
+```
+
+Retour en cas de succès : `{ ok: true, documentId, url, mode, shared }`.
+En cas de souci, le tool dégrade en `{ ok: false, reason, message }` plutôt que
+de planter :
+
+| reason | sens |
+|--------|------|
+| `no-credentials` | `GOOGLE_APPLICATION_CREDENTIALS` non défini |
+| `bad-credentials` | fichier introuvable ou JSON invalide (client_email + private_key requis) |
+| `dep-missing` | `googleapis` non installé -> `npm install googleapis google-auth-library` |
+| `invalid-content` | `title` manquant |
+| `api-error` | erreur renvoyée par l'API Google (message en clair) |
+
+## Branding : programmatique (défaut) ou template
+
+- **Programmatique** (défaut, sans config) : doc construit depuis le code, titre
+  et en-têtes colorés avec la palette AcadéNice (marine `#0e2656`, teal `#24947a`,
+  turquoise `#4cccb8`). Logo optionnel via `GDOC_LOGO_PNG_URL` (ou `logoPngUrl` en
+  argument) : une URL **PNG** publique, insérée en haut du doc ; absente, le doc
+  est brandé par les couleurs seules (Google Docs n'accepte pas le SVG).
+- **Template** (`GDOC_TEMPLATE_ID` ou `templateId` en argument) : le doc est une
+  **copie** d'un Google Doc template brandé (logo + palette dans le template), puis
+  les `{{PLACEHOLDERS}}` sont remplis (`{{TITLE}}`, `{{BLOCS}}`, `{{RESSOURCES}}`,
+  plus tout `{{KEY}}` passé via `fields`). C'est le mode recommandé pour un logo :
+  Google Docs n'insère pas de SVG, donc le logo vit dans le template (image déjà
+  posée), pas réinséré à chaque publication.
+
+## Portée et limites (honnêtes)
+
+- Scopes : `documents` + `drive.file` (par-fichier, le plus étroit suffisant pour
+  créer + partager). Pas le scope large `drive`.
+- Propriété des fichiers, selon le type de projet GCP :
+  - **Projet standalone (hors Workspace)** : le service account possède les
+    fichiers qu'il crée, dans son propre Drive (quota ~15 Go, valeur rapportée
+    par la communauté) ; partage-les via `shareWith` ; supprimer le service
+    account supprime ses fichiers.
+  - **Projet rattaché à une org Workspace (le setup recommandé plus haut)** : un
+    service account ne peut pas posséder d'assets Drive de l'org (Google IAM,
+    `service-account-overview`). Dans ce cas, crée le doc dans un **Shared Drive**
+    possédé par l'org (cible un dossier parent), ou impersonne un utilisateur via
+    la délégation domaine. Increment suivant côté code : un `GDOC_PARENT_FOLDER_ID`
+    (Shared Drive) ; en attendant, le partage `shareWith` reste fonctionnel et le
+    doc vit dans le stockage du service account.
+- La délégation domaine n'est pas requise pour le mode standalone (le SA agit
+  pour lui-même). Elle ne sert qu'à faire posséder le fichier par un utilisateur.
+
+## Contenu RNCP (adaptateur)
+
+`byan_publish` est générique. Pour publier un retour d'évaluation RNCP, un
+adaptateur transforme l'objet eval (couverture par bloc + synthèse) en
+`{ title, sections, resources }` puis appelle `byan_publish`. Cet adaptateur
+vit là où la chaîne RNCP est définie -- hors de ce module générique.

package/node_modules/byan-platform-config/lib/credentials.js

@@ -18,7 +18,19 @@ const path = require('path');
 const fs = require('fs-extra');
 
 // Keys the credentials file understands. Any other key passed in is ignored.
-const KNOWN_KEYS = ['BYAN_API_URL', 'BYAN_API_TOKEN', 'LEANTIME_API_URL', 'LEANTIME_API_TOKEN'];
+// The Google Docs publish keys (byan_publish) live here too so a per-user
+// service-account setup persists alongside the byan_web / Leantime config; the
+// MCP server reads them via resolve-config. GOOGLE_APPLICATION_CREDENTIALS is a
+// PATH to the SA JSON (not the key itself) -- the key file stays separate, 0600.
+const KNOWN_KEYS = [
+  'BYAN_API_URL',
+  'BYAN_API_TOKEN',
+  'LEANTIME_API_URL',
+  'LEANTIME_API_TOKEN',
+  'GOOGLE_APPLICATION_CREDENTIALS',
+  'GDOC_TEMPLATE_ID',
+  'GDOC_LOGO_PNG_URL',
+];
 
 function credentialsDir(homedir = os.homedir()) {
   return path.join(homedir, '.byan');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.29.2",
+  "version": "2.35.0",
   "description": "BYAN v2.8 - Intelligent AI agent creator with ELO trust system + scientific fact-check + Hermes universal dispatcher + native Claude Code integration (hooks, skills, MCP server). Multi-platform (Claude Code, Codex). Merise Agile + TDD + 71 Mantras. ~54% LLM cost savings.",
   "main": "src/index.js",
   "bin": {
@@ -18,6 +18,7 @@
     "test:e2e": "jest install/__tests__/post-install.e2e.test.js",
     "setup-turbo-whisper": "node install/setup-turbo-whisper.js",
     "setup-rtk": "node install/setup-rtk.js",
+    "setup-gdoc": "node install/setup-gdoc.js",
     "byan": "echo \"BYAN agent installed. Open Claude Code (or Codex) in this project.\"",
     "version": "node scripts/sync-install-version.js && git add install/package.json",
     "app:dev": "npm --prefix app run dev",
@@ -63,6 +64,7 @@
     "install/setup-turbo-whisper.js",
     "install/setup-parakeet.js",
     "install/setup-rtk.js",
+    "install/setup-gdoc.js",
     "install/install.sh",
     "install/package.json",
     "update-byan-agent/bin/",