create-byan-agent 2.29.2 → 2.38.0

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/install/templates/docs/leantime-integration.md

@@ -13,7 +13,7 @@ events:
 | FD phase / event | Effect on the board |
 |------------------|---------------------|
 | DISCOVERY (project confirmed) | create-or-fetch the Leantime project |
-| DISPATCH (per backlog feature) | one task per feature |
+| DISPATCH (per backlog feature) | one task per feature, with effort (storypoints), priority and a description |
 | BUILD (feature starts) | task -> column `doing` |
 | REVIEW needs-rework / VALIDATE KO | task -> column `blocked` |
 | VALIDATE OK | task -> column `review` |
@@ -23,6 +23,16 @@ The FD lifecycle columns (`todo|doing|blocked|review|done`) are resolved to the
 project's configured Leantime status ids at call time (statuses are per-project
 ints), with a conservative fallback when the labels cannot be read.
 
+Each created task also carries the BYAN signal, not just a bare title:
+
+- **effort** -- `storypoints` from the feature's complexity: a finite `complexity`
+  (0-100) bucketed on the Fibonacci scale (`<=15->2`, `16-39->5`, `40-69->8`,
+  `>=70->13`), else derived from priority (`P1->8`, `P2->5`, `P3->3`, default 3).
+- **priority** -- `P1`/`P2`/`P3` mapped to Leantime `3`/`2`/`1` (omitted when unknown).
+- **description** -- `BYAN FD <id> -- <headline>`, plus `[complexity:N]` when known.
+  It also carries the complexity if the Leantime effort field name differs from
+  the presumed `storypoints` (a `[UNVERIFIED]` wire detail, see Troubleshooting).
+
 ## Automatic sync (the leantime-fd-sync hook)
 
 You do not call the `byan_leantime_*` tools by hand. A Claude Code `PostToolUse`

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/node_modules/byan-platform-config/lib/mcp-config.js

@@ -27,6 +27,13 @@ const path = require('path');
 const fs = require('fs-extra');
 
 const MCP_SERVER_REL_PATH = '_byan/mcp/byan-mcp-server/server.js';
+// Channel entrypoint: a SEPARATE MCP server (research preview) spawned by Claude
+// Code via --dangerously-load-development-channels. Same relative-path discipline
+// as the main server (relative to projectRoot, never absolute) so the entry is
+// portable across machines/OSes and stays valid when the repo is moved or shipped
+// via npm. The entry is INERT by default: registering it in .mcp.json does NOT
+// enable the channel (that needs the explicit --dangerously-load flag at launch).
+const MCP_CHANNEL_REL_PATH = '_byan/mcp/byan-mcp-server/channel-entry.js';
 const TOKEN_PLACEHOLDER = '${BYAN_API_TOKEN}';
 const LEANTIME_URL_PLACEHOLDER = '${LEANTIME_API_URL}';
 const LEANTIME_TOKEN_PLACEHOLDER = '${LEANTIME_API_TOKEN}';
@@ -87,15 +94,66 @@ function mergeByanEntry(existingConfig, { apiUrl, token } = {}) {
   delete env.BYAN_API_URL;
   delete env.BYAN_API_TOKEN;
 
+  // The canonical RELATIVE path is forced on `args` AFTER ...existing so it always
+  // wins -- this REPAIRS a stale entry that carried an absolute path (a pre-2.37.x
+  // install): relative survives a moved / npm-shipped repo, absolute does not, and
+  // Claude Code spawns the server with cwd=projectRoot so the relative path resolves
+  // identically. `command` is only F1-orthogonal (the interpreter, not a path), so a
+  // user-chosen command is preserved; we default to 'node' only when absent. Other
+  // pre-existing keys are still preserved.
   const entry = {
-    command: 'node',
-    args: [MCP_SERVER_REL_PATH],
     ...existing,
+    command: existing.command || 'node',
+    args: [MCP_SERVER_REL_PATH],
   };
   if (Object.keys(env).length > 0) entry.env = env;
   else delete entry.env;
 
   cfg.mcpServers.byan = entry;
+
+  // The channel entry is written alongside byan from the SAME merge so there is
+  // a single source of truth for the byan MCP registration. It is inert.
+  return mergeChannelEntry(cfg);
+}
+
+/**
+ * Pure merge — no I/O. Adds the `byan-channel` MCP server entry alongside byan.
+ *
+ * This entry is a Claude Code research-preview channel (CC v2.1.80+). It is
+ * INERT by default: present in .mcp.json but only loaded when the user launches
+ * with `claude --dangerously-load-development-channels server:byan-channel`.
+ * Registering it does NOT auto-activate anything — this function writes NO
+ * channelsEnabled / allowedChannelPlugins / --dangerously-load flag.
+ *
+ * Same portability discipline as the byan entry: a RELATIVE path (never
+ * absolute), no secret in env (the channel resolves its own config at boot via
+ * resolve-config.js: env -> ~/.byan/credentials.json -> defaults). An existing
+ * byan-channel entry is preserved (command/args/env) so the merge is idempotent.
+ *
+ * @param {object} existingConfig — current parsed config
+ * @returns {object} new merged config
+ */
+function mergeChannelEntry(existingConfig) {
+  const cfg = existingConfig && typeof existingConfig === 'object' ? { ...existingConfig } : {};
+  cfg.mcpServers = { ...(cfg.mcpServers || {}) };
+
+  const existing = cfg.mcpServers['byan-channel'] || {};
+
+  // The canonical RELATIVE path + the empty (secret-free) env are forced AFTER
+  // ...existing so they always win, normalizing a stale entry (absolute path, or
+  // a stray env) while preserving any other pre-existing key. env stays empty: the
+  // channel resolves BYAN_API_URL/TOKEN itself via resolve-config.js -- writing a
+  // secret here would land it in tracked git, and the channel has no legitimate
+  // env contract of its own (Leantime refs live on the byan entry). `command` is
+  // F1-orthogonal so a user-chosen interpreter is preserved, 'node' only as the
+  // default. Idempotent: re-running yields the same entry.
+  cfg.mcpServers['byan-channel'] = {
+    ...existing,
+    command: existing.command || 'node',
+    args: [MCP_CHANNEL_REL_PATH],
+    env: {},
+  };
+
   return cfg;
 }
 
@@ -141,14 +199,20 @@ function mergeLeantimeRefs(existingConfig) {
   env.LEANTIME_API_URL = LEANTIME_URL_PLACEHOLDER;
   env.LEANTIME_API_TOKEN = LEANTIME_TOKEN_PLACEHOLDER;
 
+  // Same discipline as mergeByanEntry: args forced to the canonical RELATIVE path
+  // (normalizes a stale absolute one), command preserved (F1-orthogonal), env
+  // carries the merged Leantime refs.
   cfg.mcpServers.byan = {
-    command: 'node',
-    args: [MCP_SERVER_REL_PATH],
     ...existing,
+    command: existing.command || 'node',
+    args: [MCP_SERVER_REL_PATH],
     env,
   };
 
-  return cfg;
+  // Keep the channel entry coherent with the byan entry: ensureLeantimeRefs runs
+  // after ensureMcpConfig in the installer, but routing through mergeChannelEntry
+  // here makes the byan-channel registration robust to call order (idempotent).
+  return mergeChannelEntry(cfg);
 }
 
 /**
@@ -252,12 +316,14 @@ module.exports = {
   ensureMcpConfig,
   readMcpConfig,
   mergeByanEntry,
+  mergeChannelEntry,
   mergeLeantimeRefs,
   ensureLeantimeRefs,
   addMcpEntry,
   removeMcpEntry,
   looksLikeSecret,
   MCP_SERVER_REL_PATH,
+  MCP_CHANNEL_REL_PATH,
   TOKEN_PLACEHOLDER,
   LEANTIME_URL_PLACEHOLDER,
   LEANTIME_TOKEN_PLACEHOLDER,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.29.2",
+  "version": "2.38.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/",

package/install/templates/.mcp.json.tmpl

@@ -1,8 +0,0 @@
-{
-  "mcpServers": {
-    "byan": {
-      "command": "node",
-      "args": ["{{PROJECT_ROOT}}/_byan/mcp/byan-mcp-server/server.js"]
-    }
-  }
-}