create-byan-agent 2.7.6 → 2.7.7

package/install/src/observability/metrics/metrics-collector.js

@@ -0,0 +1,325 @@
+/**
+ * Metrics Collector for BYAN v2.0
+ * Collects and manages system metrics (counters, gauges, timings)
+ * 
+ * @module observability/metrics/metrics-collector
+ * @version 2.0.0-HYPER-MVP
+ */
+
+/**
+ * Metrics Collector - Records and tracks system metrics
+ * 
+ * @class MetricsCollector
+ * @example
+ * const metrics = new MetricsCollector();
+ * metrics.increment('api.calls', { endpoint: '/chat' });
+ * metrics.recordDuration('request.duration', 150);
+ */
+class MetricsCollector {
+  constructor() {
+    this.metrics = new Map();
+  }
+
+  /**
+   * Record a metric with a specific value
+   * 
+   * @param {string} name - Metric name
+   * @param {number} value - Metric value
+   * @param {Object} [tags={}] - Optional tags for filtering
+   * @returns {void}
+   * 
+   * @example
+   * metrics.recordMetric('memory.usage', 1024, { unit: 'MB', service: 'api' });
+   */
+  recordMetric(name, value, tags = {}) {
+    if (!name || typeof name !== 'string') {
+      throw new Error('Metric name must be a non-empty string');
+    }
+
+    if (typeof value !== 'number') {
+      throw new Error('Metric value must be a number');
+    }
+
+    if (isNaN(value)) {
+      throw new Error('Metric value cannot be NaN');
+    }
+
+    const key = this._generateKey(name, tags);
+    
+    this.metrics.set(key, {
+      name,
+      value,
+      tags: { ...tags },
+      timestamp: new Date().toISOString(),
+      type: 'gauge',
+    });
+  }
+
+  /**
+   * Increment a counter metric
+   * 
+   * @param {string} name - Metric name
+   * @param {Object} [tags={}] - Optional tags
+   * @param {number} [delta=1] - Increment amount
+   * @returns {void}
+   * 
+   * @example
+   * metrics.increment('api.calls', { endpoint: '/chat' });
+   * metrics.increment('cache.hits', {}, 5); // Increment by 5
+   */
+  increment(name, tags = {}, delta = 1) {
+    if (!name || typeof name !== 'string') {
+      throw new Error('Metric name must be a non-empty string');
+    }
+
+    if (typeof delta !== 'number') {
+      throw new Error('Delta must be a number');
+    }
+
+    const key = this._generateKey(name, tags);
+    const existing = this.metrics.get(key);
+
+    if (existing) {
+      this.metrics.set(key, {
+        ...existing,
+        value: existing.value + delta,
+        timestamp: new Date().toISOString(),
+      });
+    } else {
+      this.metrics.set(key, {
+        name,
+        value: delta,
+        tags: { ...tags },
+        timestamp: new Date().toISOString(),
+        type: 'counter',
+      });
+    }
+  }
+
+  /**
+   * Decrement a counter metric
+   * 
+   * @param {string} name - Metric name
+   * @param {Object} [tags={}] - Optional tags
+   * @param {number} [delta=1] - Decrement amount
+   * @returns {void}
+   * 
+   * @example
+   * metrics.decrement('active.connections', { server: 'main' });
+   */
+  decrement(name, tags = {}, delta = 1) {
+    this.increment(name, tags, -delta);
+  }
+
+  /**
+   * Record a duration/timing metric
+   * 
+   * @param {string} name - Metric name
+   * @param {number} durationMs - Duration in milliseconds
+   * @param {Object} [tags={}] - Optional tags
+   * @returns {void}
+   * 
+   * @example
+   * metrics.recordDuration('request.duration', 150, { status: '200' });
+   */
+  recordDuration(name, durationMs, tags = {}) {
+    if (!name || typeof name !== 'string') {
+      throw new Error('Metric name must be a non-empty string');
+    }
+
+    if (typeof durationMs !== 'number') {
+      throw new Error('Duration must be a number');
+    }
+
+    if (durationMs < 0) {
+      throw new Error('Duration cannot be negative');
+    }
+
+    const key = this._generateKey(name, tags);
+    
+    this.metrics.set(key, {
+      name,
+      value: durationMs,
+      tags: { ...tags },
+      timestamp: new Date().toISOString(),
+      type: 'timing',
+    });
+  }
+
+  /**
+   * Generate unique key for metric with tags
+   * 
+   * @private
+   * @param {string} name - Metric name
+   * @param {Object} tags - Tags
+   * @returns {string} Unique key
+   */
+  _generateKey(name, tags) {
+    if (Object.keys(tags).length === 0) {
+      return name;
+    }
+
+    const sortedTags = Object.keys(tags)
+      .sort()
+      .map((key) => `${key}:${tags[key]}`)
+      .join(',');
+
+    return `${name}[${sortedTags}]`;
+  }
+
+  /**
+   * Get all metrics
+   * 
+   * @returns {Object} All metrics as key-value pairs
+   * 
+   * @example
+   * const allMetrics = metrics.getMetrics();
+   * Object.entries(allMetrics).forEach(([key, metric]) => {
+   *   console.log(`${key}: ${metric.value}`);
+   * });
+   */
+  getMetrics() {
+    const result = {};
+    
+    for (const [key, value] of this.metrics.entries()) {
+      result[key] = { ...value };
+    }
+
+    return result;
+  }
+
+  /**
+   * Get a specific metric
+   * 
+   * @param {string} name - Metric name
+   * @param {Object} [tags={}] - Optional tags
+   * @returns {Object|null} Metric or null if not found
+   * 
+   * @example
+   * const apiCalls = metrics.getMetric('api.calls', { endpoint: '/chat' });
+   * console.log(`API calls: ${apiCalls.value}`);
+   */
+  getMetric(name, tags = {}) {
+    const key = this._generateKey(name, tags);
+    const metric = this.metrics.get(key);
+    
+    return metric ? { ...metric } : null;
+  }
+
+  /**
+   * Get metrics filtered by name prefix
+   * 
+   * @param {string} prefix - Name prefix
+   * @returns {Object} Filtered metrics
+   * 
+   * @example
+   * const apiMetrics = metrics.getMetricsByPrefix('api.');
+   * // Returns all metrics starting with 'api.'
+   */
+  getMetricsByPrefix(prefix) {
+    const result = {};
+
+    for (const [key, value] of this.metrics.entries()) {
+      if (value.name.startsWith(prefix)) {
+        result[key] = { ...value };
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Get metrics filtered by type
+   * 
+   * @param {string} type - Metric type (gauge, counter, timing)
+   * @returns {Object} Filtered metrics
+   * 
+   * @example
+   * const counters = metrics.getMetricsByType('counter');
+   */
+  getMetricsByType(type) {
+    const result = {};
+
+    for (const [key, value] of this.metrics.entries()) {
+      if (value.type === type) {
+        result[key] = { ...value };
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Clear all metrics
+   * 
+   * @returns {void}
+   * 
+   * @example
+   * metrics.clear(); // Remove all metrics
+   */
+  clear() {
+    this.metrics.clear();
+  }
+
+  /**
+   * Get metrics count
+   * 
+   * @returns {number} Number of metrics
+   */
+  count() {
+    return this.metrics.size;
+  }
+
+  /**
+   * Reset a specific metric to zero
+   * 
+   * @param {string} name - Metric name
+   * @param {Object} [tags={}] - Optional tags
+   * @returns {boolean} True if metric was reset, false if not found
+   * 
+   * @example
+   * metrics.resetMetric('api.calls', { endpoint: '/chat' });
+   */
+  resetMetric(name, tags = {}) {
+    const key = this._generateKey(name, tags);
+    const existing = this.metrics.get(key);
+
+    if (existing) {
+      this.metrics.set(key, {
+        ...existing,
+        value: 0,
+        timestamp: new Date().toISOString(),
+      });
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Get summary statistics
+   * 
+   * @returns {Object} Summary stats
+   * 
+   * @example
+   * const stats = metrics.getStats();
+   * // { total: 10, byType: { counter: 5, gauge: 3, timing: 2 } }
+   */
+  getStats() {
+    const byType = {};
+    
+    for (const metric of this.metrics.values()) {
+      if (!byType[metric.type]) {
+        byType[metric.type] = 0;
+      }
+      byType[metric.type]++;
+    }
+
+    return {
+      total: this.metrics.size,
+      byType,
+    };
+  }
+}
+
+module.exports = { MetricsCollector };

package/install/switch-to-v2.sh

@@ -0,0 +1,126 @@
+#!/bin/bash
+# Switch BYAN Installer to v2.0
+# This script updates package.json to use the new v2.0 installer
+
+set -e
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo -e "${BLUE}╔════════════════════════════════════════════════════════════╗${NC}"
+echo -e "${BLUE}║  Switch to BYAN v2.0 Installer                            ║${NC}"
+echo -e "${BLUE}╚════════════════════════════════════════════════════════════╝${NC}"
+echo ""
+
+cd "${SCRIPT_DIR}"
+
+# Check if package.json exists
+if [ ! -f "package.json" ]; then
+    echo -e "${RED}✗ package.json not found in ${SCRIPT_DIR}${NC}"
+    exit 1
+fi
+
+# Backup original
+echo -e "${YELLOW}[1/4] Creating backup...${NC}"
+cp package.json package.json.backup
+echo -e "${GREEN}✓ Backup created: package.json.backup${NC}"
+
+# Show current version
+echo ""
+echo -e "${YELLOW}[2/4] Current configuration:${NC}"
+CURRENT_VERSION=$(grep '"version"' package.json | head -1 | cut -d'"' -f4)
+CURRENT_BIN=$(grep '"create-byan-agent"' package.json | head -1 | cut -d'"' -f4)
+echo "  Version: ${CURRENT_VERSION}"
+echo "  Binary:  ${CURRENT_BIN}"
+
+# Update package.json
+echo ""
+echo -e "${YELLOW}[3/4] Updating to v2.0...${NC}"
+
+# Use Node.js to safely update JSON
+node -e "
+const fs = require('fs');
+const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+
+// Update version
+pkg.version = '2.0.0-alpha.1';
+
+// Update description
+pkg.description = 'NPX installer for BYAN v2.0 - Agent creators with v2.0 runtime support';
+
+// Update bin
+pkg.bin['create-byan-agent'] = 'bin/create-byan-agent-v2.js';
+
+// Write back
+fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+console.log('✓ package.json updated');
+"
+
+if [ $? -eq 0 ]; then
+    echo -e "${GREEN}✓ package.json updated successfully${NC}"
+else
+    echo -e "${RED}✗ Failed to update package.json${NC}"
+    echo -e "${YELLOW}Restoring backup...${NC}"
+    mv package.json.backup package.json
+    exit 1
+fi
+
+# Verify changes
+echo ""
+echo -e "${YELLOW}[4/4] Verifying changes...${NC}"
+NEW_VERSION=$(grep '"version"' package.json | head -1 | cut -d'"' -f4)
+NEW_BIN=$(grep '"create-byan-agent"' package.json | head -1 | cut -d'"' -f4)
+echo "  New Version: ${NEW_VERSION}"
+echo "  New Binary:  ${NEW_BIN}"
+
+# Check if v2 installer exists
+if [ -f "bin/create-byan-agent-v2.js" ]; then
+    echo -e "${GREEN}✓ v2.0 installer found${NC}"
+else
+    echo -e "${RED}✗ v2.0 installer not found: bin/create-byan-agent-v2.js${NC}"
+    exit 1
+fi
+
+# Set executable permissions
+chmod +x bin/create-byan-agent-v2.js
+echo -e "${GREEN}✓ Executable permissions set${NC}"
+
+# Summary
+echo ""
+echo -e "${GREEN}╔════════════════════════════════════════════════════════════╗${NC}"
+echo -e "${GREEN}║  ✅ Successfully switched to v2.0 installer                 ║${NC}"
+echo -e "${GREEN}╚════════════════════════════════════════════════════════════╝${NC}"
+echo ""
+
+echo -e "${BLUE}Changes made:${NC}"
+echo "  • Version: ${CURRENT_VERSION} → ${NEW_VERSION}"
+echo "  • Binary:  ${CURRENT_BIN} → ${NEW_BIN}"
+echo "  • Backup:  package.json.backup (preserved)"
+echo ""
+
+echo -e "${YELLOW}Next steps:${NC}"
+echo "  1. Test the installer locally:"
+echo "     ${BLUE}cd /tmp && mkdir test-project && cd test-project && git init${NC}"
+echo "     ${BLUE}node ${SCRIPT_DIR}/bin/create-byan-agent-v2.js${NC}"
+echo ""
+echo "  2. Commit the changes:"
+echo "     ${BLUE}git add package.json${NC}"
+echo "     ${BLUE}git commit -m 'feat: upgrade to BYAN v2.0 installer'${NC}"
+echo ""
+echo "  3. Publish to npm (alpha):"
+echo "     ${BLUE}npm publish --tag alpha${NC}"
+echo ""
+echo "  4. Test installation:"
+echo "     ${BLUE}npx create-byan-agent@alpha${NC}"
+echo ""
+
+echo -e "${YELLOW}To rollback:${NC}"
+echo "  ${BLUE}cp package.json.backup package.json${NC}"
+echo ""
+
+echo -e "${GREEN}Ready to deploy! 🚀${NC}"

package/install/templates/_byan/workflows/byan/forge-persona-workflow.md

@@ -0,0 +1,115 @@
+---
+name: forge-persona-workflow
+description: "Interview court pour forger un persona reutilisable — archetype, blocages, style d'apprentissage"
+version: "1.0.0"
+module: byan
+phases: 3
+output: "_byan/personas/{persona_name}.md"
+template: "_byan/templates/persona.md"
+---
+
+# FORGE-PERSONA — Persona Forging Workflow
+
+## Objectif
+
+Conduire une interview courte et structuree pour creer un persona
+reutilisable dans `_byan/personas/{persona_name}.md`.
+
+Un persona n'est PAS un agent. C'est un profil cognitif que BYAN peut incarner
+pour tester sa pedagogie, valider un agent, ou comprendre un point de vue different.
+
+---
+
+## Persona du Forgeron (mode persona)
+
+Pendant ce workflow, BYAN adopte une voix adaptee :
+- Curieuse, pas clinique — on construit un humain fictif, pas un formulaire
+- Questions concretes — "donne-moi un exemple" plutot que "decris le concept"
+- Ecoute les non-dits — ce que l'utilisateur ne dit pas sur le persona revele souvent le plus important
+- Si l'utilisateur repond de maniere generique → challenge : "ca, c'est du generique. Qui est CETTE personne ?"
+
+---
+
+## Phase 1 — Archetype et contexte
+
+**Questions :**
+
+1. "C'est qui cette personne ? Donne-moi le portrait en 2-3 phrases — pas un CV, une impression."
+2. "Quel est son niveau ? Debutant qui decouvre, intermediaire qui consolide, avance qui approfondit, expert qui change de domaine ?"
+3. "Dans quel domaine elle evolue ? Et surtout — pourquoi elle est la, devant toi/BYAN ?"
+
+**Forgeron ecoute :**
+- L'archetype naturel qui emerge (pas celui declare)
+- Le contexte emotionnel — pourquoi cette personne a besoin d'aide
+- Les mots choisis par l'utilisateur — ils revelent l'empathie ou la distance
+
+**Gate :** portrait recu et reformule → continuer
+
+---
+
+## Phase 2 — Blocages et style
+
+**Questions :**
+
+4. "Qu'est-ce qui la bloque ? Pas le sujet — la peur, la croyance, la cicatrice. Qu'est-ce qui l'empeche d'avancer meme quand le contenu est bon ?"
+5. "Comment elle apprend le mieux ? Elle a besoin de voir pour comprendre ? De faire pour retenir ? De lire d'abord pour se rassurer ?"
+6. "Quand elle dit 'j'ai compris' — comment tu sais si c'est vrai ou faux ? C'est quoi son tell ?"
+
+**Forgeron ecoute :**
+- Les blocages emotionnels (pas techniques) — la peur de paraitre con, l'imposteur, le perfectionnisme paralysant
+- Le style d'apprentissage reel (pas ideal)
+- Les signaux de pseudo-comprehension — c'est la qu'on detecte si la pedagogie marche
+
+**Gate :** blocages et style mappes → continuer
+
+---
+
+## Phase 3 — Voix et validation
+
+**Questions :**
+
+7. "Si cette personne te parlait, c'est quoi sa phrase typique ? Le truc qu'elle dirait naturellement."
+8. "Quand ca va bien — elle reagit comment ? Quand ca bloque — elle fait quoi ?"
+
+**Forgeron synthetise :**
+
+```
+PERSONA : {nom}
+ARCHETYPE : {archetype}
+NIVEAU : {niveau}
+DOMAINE : {domaine}
+BLOCAGES : {liste courte}
+STYLE : {style d'apprentissage}
+TELL : {signal de pseudo-comprehension}
+PHRASES : {2-3 phrases typiques}
+```
+
+**Demander :** "Est-ce que tu reconnais cette personne ?"
+
+Si non → "Qu'est-ce qui sonne faux ?" → ajuster
+Si oui → generer le fichier
+
+---
+
+## Generation
+
+1. Lire le template : `{project-root}/_byan/templates/persona.md`
+2. Remplir avec les donnees de l'interview
+3. Ecrire dans : `{project-root}/_byan/personas/{persona_name}.md`
+   - Le nom du fichier est derive du nom du persona (kebab-case, sans accents)
+4. Confirmer : "Persona {nom} forge et stocke dans `_byan/personas/{persona_name}.md`. Pret a etre joue avec [PP]."
+
+---
+
+## Regles
+
+- **Interview court** — 8 questions max. Pas d'interview fleuve.
+- **Concret avant abstrait** — exemples et phrases avant definitions
+- **Le persona n'est pas l'utilisateur** — c'est un profil fictif inspire du reel
+- **Pas de persona parfait** — les blocages et les tells sont obligatoires. Un persona sans faille est inutile.
+- **Regle de nommage** — le nom du fichier est en kebab-case, sans accents, sans espaces
+- **Un persona = un fichier** — pas de fichier multi-personas
+
+---
+
+*Workflow cree par BYAN — Feature Development Sprint A*