create-byan-agent 2.11.3 → 2.12.1

package/_byan/mcp/byan-mcp-server/lib/kanban.js

@@ -0,0 +1,226 @@
+/**
+ * Kanban + stand-up registry for BYAN party-mode sessions.
+ *
+ * Kanban : _byan-output/party-mode-sessions/<session_id>/kanban.json
+ *   columns : todo | doing | blocked | review | done
+ *   cards   : { id, title, assignee, priority, created_at, moved_at,
+ *               column, blocker_reason? }
+ *
+ * Stand-up : _byan-output/party-mode-sessions/<session_id>/standup.jsonl
+ *   entries : { agent, timestamp, did, blockers, next }
+ *
+ * Hermes watches stand-ups : an agent with 2+ consecutive "blocked"
+ * reports in the stand-up stream is flagged and their card is moved to
+ * `blocked` column in the kanban.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const COLUMNS = ['todo', 'doing', 'blocked', 'review', 'done'];
+
+function resolveRoot(projectRoot) {
+  return projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function sessionDir(projectRoot, sessionId) {
+  return path.join(
+    resolveRoot(projectRoot),
+    '_byan-output',
+    'party-mode-sessions',
+    sanitize(sessionId)
+  );
+}
+
+function sanitize(id) {
+  return String(id || 'default').replace(/[^a-zA-Z0-9._-]/g, '-').slice(0, 80);
+}
+
+function kanbanPath(projectRoot, sessionId) {
+  return path.join(sessionDir(projectRoot, sessionId), 'kanban.json');
+}
+
+function standupPath(projectRoot, sessionId) {
+  return path.join(sessionDir(projectRoot, sessionId), 'standup.jsonl');
+}
+
+function readKanban(projectRoot, sessionId) {
+  const p = kanbanPath(projectRoot, sessionId);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeKanban(projectRoot, sessionId, board) {
+  const p = kanbanPath(projectRoot, sessionId);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(board, null, 2));
+}
+
+function emptyBoard(sessionId, now) {
+  return {
+    session_id: sessionId,
+    created_at: now.toISOString(),
+    updated_at: now.toISOString(),
+    columns: COLUMNS.slice(),
+    cards: {},
+  };
+}
+
+export function createBoard({ sessionId, projectRoot, now = new Date() } = {}) {
+  if (!sessionId) throw new Error('sessionId is required');
+  const existing = readKanban(projectRoot, sessionId);
+  if (existing) return existing;
+  const board = emptyBoard(sessionId, now);
+  writeKanban(projectRoot, sessionId, board);
+  return board;
+}
+
+export function addCard({
+  sessionId,
+  card,
+  projectRoot,
+  now = new Date(),
+} = {}) {
+  if (!sessionId) throw new Error('sessionId is required');
+  if (!card || !card.id || !card.title) throw new Error('card.id and card.title required');
+
+  const board = readKanban(projectRoot, sessionId) || emptyBoard(sessionId, now);
+  if (board.cards[card.id]) throw new Error(`card ${card.id} already exists`);
+
+  board.cards[card.id] = {
+    id: card.id,
+    title: card.title,
+    assignee: card.assignee || null,
+    priority: card.priority || 'P2',
+    column: card.column || 'todo',
+    created_at: now.toISOString(),
+    moved_at: now.toISOString(),
+    blocker_reason: null,
+  };
+  board.updated_at = now.toISOString();
+
+  writeKanban(projectRoot, sessionId, board);
+  return board.cards[card.id];
+}
+
+export function moveCard({
+  sessionId,
+  cardId,
+  toColumn,
+  blocker_reason,
+  projectRoot,
+  now = new Date(),
+} = {}) {
+  if (!COLUMNS.includes(toColumn)) {
+    throw new Error(`toColumn must be one of ${COLUMNS.join(', ')}, got ${toColumn}`);
+  }
+  const board = readKanban(projectRoot, sessionId);
+  if (!board) throw new Error(`no kanban for session ${sessionId}`);
+  if (!board.cards[cardId]) throw new Error(`card ${cardId} not found`);
+
+  const card = board.cards[cardId];
+  card.column = toColumn;
+  card.moved_at = now.toISOString();
+  card.blocker_reason = toColumn === 'blocked' ? blocker_reason || 'unspecified' : null;
+  board.updated_at = now.toISOString();
+
+  writeKanban(projectRoot, sessionId, board);
+  return card;
+}
+
+export function assignCard({
+  sessionId,
+  cardId,
+  assignee,
+  projectRoot,
+  now = new Date(),
+} = {}) {
+  if (!assignee) throw new Error('assignee is required');
+  const board = readKanban(projectRoot, sessionId);
+  if (!board || !board.cards[cardId]) throw new Error(`card ${cardId} not found`);
+  board.cards[cardId].assignee = assignee;
+  board.cards[cardId].moved_at = now.toISOString();
+  board.updated_at = now.toISOString();
+  writeKanban(projectRoot, sessionId, board);
+  return board.cards[cardId];
+}
+
+export function getBoard({ sessionId, projectRoot } = {}) {
+  if (!sessionId) throw new Error('sessionId is required');
+  return readKanban(projectRoot, sessionId);
+}
+
+export function postStandup({
+  sessionId,
+  agent,
+  did,
+  blockers = [],
+  next,
+  projectRoot,
+  now = new Date(),
+} = {}) {
+  if (!sessionId) throw new Error('sessionId is required');
+  if (!agent) throw new Error('agent is required');
+
+  const entry = {
+    agent,
+    timestamp: now.toISOString(),
+    did: did || '',
+    blockers: Array.isArray(blockers) ? blockers : [],
+    next: next || '',
+  };
+
+  const p = standupPath(projectRoot, sessionId);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.appendFileSync(p, JSON.stringify(entry) + '\n');
+  return entry;
+}
+
+export function readStandups({ sessionId, projectRoot, limit = 50 } = {}) {
+  const p = standupPath(projectRoot, sessionId);
+  if (!fs.existsSync(p)) return [];
+  const lines = fs.readFileSync(p, 'utf8').split('\n').filter(Boolean);
+  const out = [];
+  for (const line of lines) {
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+      // skip malformed
+    }
+  }
+  return out.slice(-limit);
+}
+
+/**
+ * Detect agents with >= minStreak consecutive blocked stand-ups.
+ * Returns array of { agent, streak, lastAt }.
+ */
+export function detectBlockedStreaks({ sessionId, minStreak = 2, projectRoot } = {}) {
+  const standups = readStandups({ sessionId, projectRoot, limit: 500 });
+  const streaks = {};
+  const agentLast = {};
+
+  for (const entry of standups) {
+    const isBlocked = Array.isArray(entry.blockers) && entry.blockers.length > 0;
+    if (isBlocked) {
+      streaks[entry.agent] = (streaks[entry.agent] || 0) + 1;
+    } else {
+      streaks[entry.agent] = 0;
+    }
+    agentLast[entry.agent] = entry.timestamp;
+  }
+
+  const flagged = [];
+  for (const [agent, n] of Object.entries(streaks)) {
+    if (n >= minStreak) {
+      flagged.push({ agent, streak: n, lastAt: agentLast[agent] });
+    }
+  }
+  return flagged;
+}
+
+export const KANBAN_COLUMNS = COLUMNS;

package/_byan/mcp/byan-mcp-server/lib/peer-review.js

@@ -0,0 +1,187 @@
+/**
+ * Peer review registry for BYAN agents working in party-mode.
+ *
+ * Contract :
+ *   - An agent producing an artefact (commit, file change, spec) opens a
+ *     review request via requestReview(). The request is persisted at
+ *     _byan-output/reviews/<task_id>.json.
+ *   - Another agent (must be ≠ author) issues a verdict via
+ *     recordVerdict() with { verdict: approve | changes | block, comments,
+ *     must_fix }.
+ *   - listPending() returns all unresolved requests. pickReviewer()
+ *     returns an alternative agent from the roster distinct from the
+ *     author.
+ *
+ * Enforces the "reviewer must differ from author" invariant inside
+ * recordVerdict() and throws if violated.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DEFAULT_ROSTER = [
+  'bmad-bmm-architect',
+  'bmad-bmm-dev',
+  'bmad-bmm-quinn',
+  'bmad-bmm-pm',
+  'bmad-bmm-sm',
+  'bmad-bmm-analyst',
+  'bmad-bmm-ux-designer',
+  'bmad-bmm-tech-writer',
+  'bmad-tea-tea',
+  'bmad-compliance',
+];
+
+function resolveRoot(projectRoot) {
+  return projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function reviewsDir(projectRoot) {
+  return path.join(resolveRoot(projectRoot), '_byan-output', 'reviews');
+}
+
+function reviewPath(projectRoot, taskId) {
+  return path.join(reviewsDir(projectRoot), `${sanitizeId(taskId)}.json`);
+}
+
+function sanitizeId(id) {
+  return String(id).replace(/[^a-zA-Z0-9._-]/g, '-').slice(0, 80);
+}
+
+function readReview(projectRoot, taskId) {
+  const p = reviewPath(projectRoot, taskId);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeReview(projectRoot, review) {
+  fs.mkdirSync(reviewsDir(projectRoot), { recursive: true });
+  fs.writeFileSync(reviewPath(projectRoot, review.task_id), JSON.stringify(review, null, 2));
+}
+
+export function requestReview({
+  task_id,
+  author,
+  artifact_paths = [],
+  description = '',
+  projectRoot,
+  now = new Date(),
+} = {}) {
+  if (!task_id) throw new Error('task_id is required');
+  if (!author) throw new Error('author (agent name) is required');
+
+  const existing = readReview(projectRoot, task_id);
+  if (existing && existing.status === 'pending') {
+    throw new Error(`review for task ${task_id} already pending (author ${existing.author})`);
+  }
+
+  const review = {
+    task_id,
+    author,
+    artifact_paths: Array.isArray(artifact_paths) ? artifact_paths : [],
+    description: String(description || ''),
+    status: 'pending',
+    verdicts: [],
+    created_at: now.toISOString(),
+    updated_at: now.toISOString(),
+  };
+
+  writeReview(projectRoot, review);
+  return review;
+}
+
+export function recordVerdict({
+  task_id,
+  reviewer,
+  verdict,
+  comments = [],
+  must_fix = [],
+  projectRoot,
+  now = new Date(),
+} = {}) {
+  if (!task_id) throw new Error('task_id is required');
+  if (!reviewer) throw new Error('reviewer (agent name) is required');
+  if (!['approve', 'changes', 'block'].includes(verdict)) {
+    throw new Error(`verdict must be approve | changes | block, got ${verdict}`);
+  }
+
+  const review = readReview(projectRoot, task_id);
+  if (!review) throw new Error(`no review found for task ${task_id} — call requestReview first`);
+
+  if (review.author === reviewer) {
+    throw new Error(
+      `reviewer (${reviewer}) cannot be the same as author (${review.author}). Pick a different agent.`
+    );
+  }
+
+  review.verdicts.push({
+    reviewer,
+    verdict,
+    comments: Array.isArray(comments) ? comments : [],
+    must_fix: Array.isArray(must_fix) ? must_fix : [],
+    at: now.toISOString(),
+  });
+
+  if (verdict === 'approve') review.status = 'approved';
+  else if (verdict === 'block') review.status = 'blocked';
+  else review.status = 'changes_requested';
+
+  review.updated_at = now.toISOString();
+  writeReview(projectRoot, review);
+  return review;
+}
+
+export function getReview({ task_id, projectRoot } = {}) {
+  if (!task_id) throw new Error('task_id is required');
+  return readReview(projectRoot, task_id);
+}
+
+export function listPending({ projectRoot } = {}) {
+  const dir = reviewsDir(projectRoot);
+  if (!fs.existsSync(dir)) return [];
+  const files = fs.readdirSync(dir).filter((f) => f.endsWith('.json'));
+  const out = [];
+  for (const f of files) {
+    try {
+      const r = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8'));
+      if (r.status === 'pending' || r.status === 'changes_requested') out.push(r);
+    } catch {
+      // skip malformed
+    }
+  }
+  out.sort((a, b) => (a.created_at > b.created_at ? -1 : 1));
+  return out;
+}
+
+export function pickReviewer({ author, preferredDomain, roster = DEFAULT_ROSTER } = {}) {
+  const domainPairs = {
+    dev: ['bmad-bmm-quinn', 'bmad-tea-tea'],
+    'bmm-dev': ['bmad-bmm-quinn', 'bmad-tea-tea'],
+    'bmad-bmm-dev': ['bmad-bmm-quinn', 'bmad-tea-tea'],
+    architect: ['bmad-tea-tea', 'bmad-bmm-quinn'],
+    'bmad-bmm-architect': ['bmad-tea-tea', 'bmad-bmm-quinn'],
+    pm: ['bmad-bmm-sm', 'bmad-bmm-analyst'],
+    'bmad-bmm-pm': ['bmad-bmm-sm', 'bmad-bmm-analyst'],
+    'ux-designer': ['bmad-bmm-pm', 'bmad-bmm-analyst'],
+    'bmad-bmm-ux-designer': ['bmad-bmm-pm', 'bmad-bmm-analyst'],
+  };
+
+  const keys = [preferredDomain, author].filter(Boolean);
+  for (const k of keys) {
+    const candidates = domainPairs[k] || [];
+    for (const c of candidates) {
+      if (c !== author) return c;
+    }
+  }
+
+  for (const r of roster) {
+    if (r !== author) return r;
+  }
+  return null;
+}
+
+export const DEFAULT_AGENT_ROSTER = DEFAULT_ROSTER;

package/_byan/mcp/byan-mcp-server/lib/soul.js

@@ -0,0 +1,64 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const DEFAULT_FILES = {
+  soul: '_byan/soul.md',
+  tao: '_byan/tao.md',
+  'soul-memory': '_byan/soul-memory.md',
+};
+
+export function resolveProjectRoot(envRoot) {
+  return envRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+export function readSoul({ which = 'all', projectRoot }) {
+  const root = resolveProjectRoot(projectRoot);
+  const targets =
+    which === 'all'
+      ? Object.keys(DEFAULT_FILES)
+      : [which].filter((k) => DEFAULT_FILES[k]);
+
+  if (targets.length === 0) {
+    throw new Error(
+      `Unknown soul target: "${which}". Valid: ${Object.keys(DEFAULT_FILES).join(', ')} or "all".`
+    );
+  }
+
+  const result = {};
+  for (const key of targets) {
+    const p = path.join(root, DEFAULT_FILES[key]);
+    if (fs.existsSync(p)) {
+      result[key] = {
+        path: DEFAULT_FILES[key],
+        content: fs.readFileSync(p, 'utf8'),
+      };
+    } else {
+      result[key] = { path: DEFAULT_FILES[key], content: null, missing: true };
+    }
+  }
+  return result;
+}
+
+export function appendSoulMemory({ entry, projectRoot, validated = false, now = new Date() }) {
+  if (!entry || typeof entry !== 'string' || entry.trim().length === 0) {
+    throw new Error('entry must be a non-empty string');
+  }
+  if (!validated) {
+    throw new Error(
+      'validated=true is required. Per BYAN rule, soul-memory entries must be confirmed by the user before append.'
+    );
+  }
+
+  const root = resolveProjectRoot(projectRoot);
+  const p = path.join(root, DEFAULT_FILES['soul-memory']);
+  const stamp = now.toISOString().slice(0, 10);
+  const block = `\n\n---\n\n## Entree ${stamp}\n\n${entry.trim()}\n`;
+
+  const dir = path.dirname(p);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const existing = fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : '# Soul-Memory — Journal vivant BYAN\n';
+  fs.writeFileSync(p, existing + block);
+
+  return { path: DEFAULT_FILES['soul-memory'], appended_chars: block.length };
+}

package/_byan/mcp/byan-mcp-server/lib/workflow-scripts.js

@@ -0,0 +1,156 @@
+/**
+ * Workflow node scripts — thin wrapper over byan_web REST endpoints.
+ *
+ * Wraps :
+ *   GET    /api/workflow-nodes/:nodeId/scripts
+ *   GET    /api/scripts/:id
+ *   POST   /api/workflow-nodes/:nodeId/scripts
+ *   PATCH  /api/scripts/:id
+ *   DELETE /api/scripts/:id
+ *   GET    /api/scripts/:id/history
+ *   POST   /api/scripts/:id/rollback
+ *   POST   /api/workflow-nodes/:nodeId/scripts/import
+ *   POST   /api/scripts/validate
+ *
+ * `apiRequest` is injected so tests can pass a mock without an HTTP round-trip.
+ */
+
+export const ALLOWED_LANGUAGES = ['bash', 'python', 'javascript', 'typescript'];
+export const ALLOWED_EXEC_MODES = ['context', 'local'];
+
+function encodeId(id) {
+  if (!id || typeof id !== 'string') throw new Error('id must be a non-empty string');
+  return encodeURIComponent(id);
+}
+
+function unwrap(body) {
+  if (body && typeof body === 'object' && 'data' in body) return body.data;
+  return body;
+}
+
+export async function listScripts({ apiRequest, nodeId }) {
+  if (!nodeId) throw new Error('nodeId is required');
+  const body = await apiRequest(`/api/workflow-nodes/${encodeId(nodeId)}/scripts`);
+  return { data: body.data || [], total: body.total ?? (body.data || []).length };
+}
+
+export async function getScript({ apiRequest, id }) {
+  const body = await apiRequest(`/api/scripts/${encodeId(id)}`);
+  return unwrap(body);
+}
+
+export async function createScript({
+  apiRequest,
+  nodeId,
+  name,
+  language,
+  content,
+  execution_mode,
+  order_idx,
+  bypassValidation,
+}) {
+  if (!nodeId) throw new Error('nodeId is required');
+  if (!name) throw new Error('name is required');
+  if (!ALLOWED_LANGUAGES.includes(language)) {
+    throw new Error(`language must be one of ${ALLOWED_LANGUAGES.join(', ')}, got ${language}`);
+  }
+  if (typeof content !== 'string') throw new Error('content (string) is required');
+
+  const payload = { name, language, content };
+  if (execution_mode !== undefined) payload.execution_mode = execution_mode;
+  if (order_idx !== undefined) payload.order_idx = order_idx;
+  if (bypassValidation === true) payload.bypassValidation = true;
+
+  const body = await apiRequest(`/api/workflow-nodes/${encodeId(nodeId)}/scripts`, {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  });
+  return unwrap(body);
+}
+
+export async function updateScript({
+  apiRequest,
+  id,
+  expected_version,
+  name,
+  language,
+  content,
+  execution_mode,
+  order_idx,
+  bypassValidation,
+}) {
+  const payload = {};
+  if (expected_version !== undefined) payload.expected_version = expected_version;
+  if (name !== undefined) payload.name = name;
+  if (language !== undefined) {
+    if (!ALLOWED_LANGUAGES.includes(language)) {
+      throw new Error(`language must be one of ${ALLOWED_LANGUAGES.join(', ')}, got ${language}`);
+    }
+    payload.language = language;
+  }
+  if (content !== undefined) payload.content = content;
+  if (execution_mode !== undefined) payload.execution_mode = execution_mode;
+  if (order_idx !== undefined) payload.order_idx = order_idx;
+  if (bypassValidation === true) payload.bypassValidation = true;
+
+  const body = await apiRequest(`/api/scripts/${encodeId(id)}`, {
+    method: 'PATCH',
+    body: JSON.stringify(payload),
+  });
+  return unwrap(body);
+}
+
+export async function deleteScript({ apiRequest, id }) {
+  const body = await apiRequest(`/api/scripts/${encodeId(id)}`, { method: 'DELETE' });
+  return unwrap(body);
+}
+
+export async function getScriptHistory({ apiRequest, id }) {
+  const body = await apiRequest(`/api/scripts/${encodeId(id)}/history`);
+  return { data: body.data || [], total: body.total ?? (body.data || []).length };
+}
+
+export async function rollbackScript({ apiRequest, id, version }) {
+  if (!Number.isInteger(version) || version < 1) {
+    throw new Error('version must be a positive integer');
+  }
+  const body = await apiRequest(`/api/scripts/${encodeId(id)}/rollback`, {
+    method: 'POST',
+    body: JSON.stringify({ version }),
+  });
+  return unwrap(body);
+}
+
+export async function importScript({
+  apiRequest,
+  nodeId,
+  url,
+  name,
+  language,
+  execution_mode,
+}) {
+  if (!nodeId) throw new Error('nodeId is required');
+  if (!url) throw new Error('url is required');
+  const payload = { url };
+  if (name !== undefined) payload.name = name;
+  if (language !== undefined) payload.language = language;
+  if (execution_mode !== undefined) payload.execution_mode = execution_mode;
+
+  const body = await apiRequest(`/api/workflow-nodes/${encodeId(nodeId)}/scripts/import`, {
+    method: 'POST',
+    body: JSON.stringify(payload),
+  });
+  return unwrap(body);
+}
+
+export async function validateScriptSyntax({ apiRequest, language, content }) {
+  if (!ALLOWED_LANGUAGES.includes(language)) {
+    throw new Error(`language must be one of ${ALLOWED_LANGUAGES.join(', ')}, got ${language}`);
+  }
+  if (typeof content !== 'string') throw new Error('content (string) is required');
+  const body = await apiRequest('/api/scripts/validate', {
+    method: 'POST',
+    body: JSON.stringify({ language, content }),
+  });
+  return unwrap(body);
+}

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

@@ -0,0 +1,43 @@
+{
+  "name": "byan-mcp-server",
+  "version": "0.2.0",
+  "description": "BYAN MCP server — exposes byan_web REST API (projects, FD lifecycle, kanban, ELO, fact-check, workflow-node-scripts, peer-review) as Claude Code tools.",
+  "main": "server.js",
+  "type": "module",
+  "bin": {
+    "byan-mcp": "./server.js"
+  },
+  "files": [
+    "server.js",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node server.js",
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mcp",
+    "byan",
+    "claude-code",
+    "workflow",
+    "fd-lifecycle",
+    "kanban",
+    "elo-trust",
+    "fact-check"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Les-fous-du-bus/byan_web.git",
+    "directory": "_byan/mcp/byan-mcp-server"
+  },
+  "author": "Yan Acadenice",
+  "license": "MIT"
+}