create-byan-agent 2.13.1 → 2.14.1

package/install/bin/create-byan-agent-v2.js

@@ -16,9 +16,83 @@ const { generateProjectAgentsDoc } = require('../lib/project-agents-generator');
 const { launchPhase2Chat, generateDefaultConfig } = require('../lib/phase2-chat');
 const { setupByanWebIntegration, validateByanWebReachability } = require('../lib/byan-web-integration');
 const { setupClaudeNative } = require('../lib/claude-native-setup');
+const { setupCodexNative } = require('../lib/codex-native-setup');
 const { setupStagingConsent } = require('../lib/staging-consent');
+const { getLatestVersion, compareVersions } = require('../lib/utils/version-compare');
 
-const BYAN_VERSION = require('../package.json').version;
+// Version source-of-truth is the root package.json (the one npm publishes).
+// install/package.json used to be read here, but it carries an unrelated
+// internal version that drifted (2.11.0 while the npm package shipped 2.14.0)
+// and silently mis-flagged users as obsolete. Resolve via path so it works
+// both in the published tarball and in the dev repo.
+const BYAN_VERSION = require(path.resolve(__dirname, '..', '..', 'package.json')).version;
+
+// Versions strictly below this floor have known install bugs (e.g. v2.9.8 ships
+// the broken node_modules filter that copies an empty MCP server dir). They
+// are blocked outright. Above the floor, an outdated version becomes a soft
+// prompt — the user can choose to continue or upgrade.
+const KNOWN_BAD_VERSION_FLOOR = '2.13.1';
+
+async function assertVersionFresh({ skip = false, timeoutMs = 5000 } = {}) {
+  if (skip || process.env.BYAN_SKIP_VERSION_CHECK === '1') return;
+  let latest;
+  try {
+    latest = await Promise.race([
+      getLatestVersion('create-byan-agent'),
+      new Promise((_, rej) => setTimeout(() => rej(new Error('npm-timeout')), timeoutMs)),
+    ]);
+  } catch (err) {
+    console.log(chalk.gray(`  (version check skipped: ${err.message})`));
+    return;
+  }
+  if (compareVersions(BYAN_VERSION, latest) >= 0) return;
+
+  // Hard block when below the known-bad floor — these versions corrupt installs.
+  if (compareVersions(BYAN_VERSION, KNOWN_BAD_VERSION_FLOOR) < 0) {
+    console.error('');
+    console.error(chalk.red.bold('  BYAN installer is obsolete (known install bugs)'));
+    console.error('');
+    console.error(chalk.yellow(`    Installed: ${BYAN_VERSION}`));
+    console.error(chalk.yellow(`    Latest:    ${latest}`));
+    console.error(chalk.yellow(`    Floor:     ${KNOWN_BAD_VERSION_FLOOR} (older versions silently produce empty MCP servers)`));
+    console.error('');
+    console.error(chalk.cyan('  Upgrade required:'));
+    console.error(chalk.bold('    npm i -g create-byan-agent@latest'));
+    console.error('');
+    console.error(chalk.gray('  Bypass (not recommended):  --skip-version-check  or  BYAN_SKIP_VERSION_CHECK=1'));
+    console.error('');
+    process.exit(1);
+  }
+
+  // Soft prompt above the floor — propose upgrade interactively.
+  console.log('');
+  console.log(chalk.yellow.bold(`  BYAN ${BYAN_VERSION} -> ${latest} available on npm`));
+  console.log(chalk.gray('  Newer release published. Continue with current, or abort to upgrade?'));
+  if (!process.stdin.isTTY) {
+    console.log(chalk.gray('  (non-TTY context — continuing without prompt)'));
+    return;
+  }
+  const { proceed } = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'proceed',
+      message: 'How do you want to proceed ?',
+      choices: [
+        { name: `Continue with v${BYAN_VERSION}`, value: 'continue' },
+        { name: `Abort and upgrade (npm i -g create-byan-agent@latest)`, value: 'abort' },
+      ],
+      default: 'continue',
+    },
+  ]);
+  if (proceed === 'abort') {
+    console.log('');
+    console.log(chalk.cyan('  Run:'));
+    console.log(chalk.bold('    npm i -g create-byan-agent@latest'));
+    console.log(chalk.gray('  Then re-run `npx create-byan-agent`.'));
+    console.log('');
+    process.exit(0);
+  }
+}
 
 // ASCII Art Banner
 const banner = `
@@ -256,10 +330,12 @@ async function mergePackageJson(templateDir, projectRoot, spinner) {
 }
 
 // Main installer
-async function install() {
+async function install(options = {}) {
   console.clear();
   console.log(banner);
-  
+
+  await assertVersionFresh({ skip: options.skipVersionCheck });
+
   const projectRoot = process.cwd();
   
   // Step 1: Detect project type
@@ -1358,6 +1434,21 @@ async function install() {
     }
   }
 
+  if (needsCodex) {
+    console.log();
+    console.log(chalk.cyan('Codex CLI MCP setup (~/.codex/config.toml)'));
+    try {
+      await setupCodexNative(projectRoot);
+    } catch (error) {
+      console.log(chalk.red(`  ✘ Codex MCP setup failed: ${error.message}`));
+      console.log(
+        chalk.yellow(
+          `    → Edit ~/.codex/config.toml manually to add the byan MCP entry.`
+        )
+      );
+    }
+  }
+
   if (needsClaude || needsCopilot) {
     console.log();
     console.log(chalk.cyan('byan_web integration (optional — service payant)'));
@@ -1753,6 +1844,7 @@ program
   .name('create-byan-agent')
   .description('Install BYAN v2.2.0 - Builder of YAN with Model Selector and multi-platform support')
   .version(BYAN_VERSION)
+  .option('--skip-version-check', 'Bypass the npm freshness guard (not recommended)')
   .action(install);
 
 // Update Command (Yanstaller v3)

package/install/lib/codex-native-setup.js

@@ -0,0 +1,156 @@
+/**
+ * Codex CLI native setup — wires the BYAN MCP server into ~/.codex/config.toml
+ * during `npx create-byan-agent`.
+ *
+ * Mirrors claude-native-setup.js but targets Codex CLI's user-level TOML config.
+ * Per Codex docs (developers.openai.com/codex/mcp), MCP entries support:
+ *   command, args, env, env_vars, cwd, startup_timeout_sec, tool_timeout_sec,
+ *   enabled, required, enabled_tools, disabled_tools, supports_parallel_tool_calls.
+ *
+ * Idempotent: strips any existing [mcp_servers.byan*] sections before writing
+ * the fresh block. Other servers in config.toml are preserved untouched.
+ *
+ * Never persists a token: BYAN_API_TOKEN is left blank if not supplied via env
+ * or interactive prompt; the user gets a clear edit instruction.
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const os = require('os');
+const chalk = require('chalk');
+
+const SERVER_NAME = 'byan';
+
+function getCodexConfigPath() {
+  return path.join(os.homedir(), '.codex', 'config.toml');
+}
+
+async function detectCodex() {
+  return fs.pathExists(path.join(os.homedir(), '.codex'));
+}
+
+// TOML literal-string escape: single quotes don't interpret backslashes,
+// so paths and tokens land verbatim. We just refuse values containing "'".
+function tomlLiteral(value) {
+  const s = String(value);
+  if (s.includes("'")) {
+    throw new Error(`Cannot encode value with single quote in TOML literal: ${s}`);
+  }
+  return `'${s}'`;
+}
+
+// Removes every section whose header matches [mcp_servers.<name>] or
+// [mcp_servers.<name>.<sub>]. Lines belonging to such a section are dropped
+// until another header (any header) is encountered.
+function stripServerSections(content, name) {
+  const ours = new RegExp(
+    `^\\[mcp_servers\\.${name}(?:\\..+)?\\]\\s*$`
+  );
+  const anyHeader = /^\[.+\]\s*$/;
+  const out = [];
+  let inOur = false;
+  for (const raw of content.split('\n')) {
+    const line = raw;
+    if (ours.test(line)) {
+      inOur = true;
+      continue;
+    }
+    if (anyHeader.test(line)) {
+      inOur = false;
+      out.push(line);
+      continue;
+    }
+    if (!inOur) out.push(line);
+  }
+  // Trim trailing blank lines that may pile up after stripping
+  return out.join('\n').replace(/\n{3,}$/g, '\n\n').replace(/\s+$/, '\n');
+}
+
+function buildByanBlock({ serverPath, apiUrl, apiToken, startupTimeoutSec = 15 }) {
+  const lines = [
+    '',
+    '[mcp_servers.byan]',
+    `command = ${tomlLiteral('node')}`,
+    `args = [${tomlLiteral(serverPath)}]`,
+    `startup_timeout_sec = ${Number.isFinite(startupTimeoutSec) ? startupTimeoutSec : 15}`,
+    '',
+    '[mcp_servers.byan.env]',
+    `BYAN_API_URL = ${tomlLiteral(apiUrl)}`,
+    `BYAN_API_TOKEN = ${tomlLiteral(apiToken)}`,
+    '',
+  ];
+  return lines.join('\n');
+}
+
+async function patchCodexConfig(projectRoot, options = {}) {
+  const configPath = getCodexConfigPath();
+  const serverPath = path.join(
+    projectRoot,
+    '_byan',
+    'mcp',
+    'byan-mcp-server',
+    'server.js'
+  );
+
+  await fs.ensureDir(path.dirname(configPath));
+
+  let existing = '';
+  if (await fs.pathExists(configPath)) {
+    existing = await fs.readFile(configPath, 'utf8');
+  }
+
+  const apiUrl =
+    options.apiUrl ||
+    process.env.BYAN_API_URL ||
+    'http://localhost:3737';
+  const apiToken =
+    options.apiToken !== undefined
+      ? options.apiToken
+      : (process.env.BYAN_API_TOKEN || '');
+
+  const stripped = stripServerSections(existing, SERVER_NAME);
+  const block = buildByanBlock({
+    serverPath,
+    apiUrl,
+    apiToken,
+    startupTimeoutSec: options.startupTimeoutSec,
+  });
+
+  const merged =
+    (stripped.trimEnd().length > 0 ? stripped.trimEnd() + '\n' : '') + block;
+
+  await fs.writeFile(configPath, merged, 'utf8');
+  return { path: configPath, hadExisting: existing.length > 0, tokenSet: apiToken.length > 0 };
+}
+
+async function setupCodexNative(projectRoot, options = {}) {
+  const log = options.quiet ? () => {} : (...a) => console.log(...a);
+
+  const present = await detectCodex();
+  if (!present && !options.force) {
+    log(chalk.gray('  · Codex CLI not detected (~/.codex absent), skipping'));
+    return { skipped: true, reason: 'codex-not-detected' };
+  }
+
+  const result = await patchCodexConfig(projectRoot, options);
+  log(chalk.green(`  ✓ Codex MCP entry written to ${result.path}`));
+  if (!result.tokenSet) {
+    log(
+      chalk.yellow(
+        `    ⚠ BYAN_API_TOKEN left empty. Edit ${result.path} and set BYAN_API_TOKEN`
+      )
+    );
+    log(chalk.gray('      (or rerun with BYAN_API_TOKEN=byan_xxx in the env)'));
+  }
+  log(chalk.gray('    Restart Codex CLI for the new MCP server to load'));
+  return result;
+}
+
+module.exports = {
+  setupCodexNative,
+  patchCodexConfig,
+  stripServerSections,
+  buildByanBlock,
+  getCodexConfigPath,
+  detectCodex,
+};

package/install/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.11.0",
+  "version": "2.14.1",
   "description": "BYAN v2.2.2 - Intelligent AI agent installer with multi-platform native support (GitHub Copilot CLI, Claude Code, Codex/OpenCode)",
   "bin": {
     "create-byan-agent": "bin/create-byan-agent-v2.js"

package/install/templates/.claude/skills/byan-byan/SKILL.md

@@ -18,6 +18,18 @@ Invoke this protocol when the user :
 
 If the user request is a simple question or chat, stay out of FD — respond normally.
 
+## 1.5. Freshness check (silent, once per session)
+
+Before responding to the user's first activation message in a session, call the MCP tool `byan_update_check` once. It is read-only and cheap (single npm registry lookup, 5s timeout, no side effects).
+
+Behavior depending on the JSON returned :
+
+- `updateAvailable === true` : surface a one-line notice to the user, e.g. *"BYAN {installed} is behind {latest} on npm. Run `byan_update_apply` for the upgrade command, or skip and continue."* — then proceed normally with the user's request. Do not block.
+- `updateAvailable === false` and `note` is set (e.g. manifest missing, network error) : stay silent — do not nag.
+- `isCurrent === true` : stay silent.
+
+Never call `byan_update_apply` without explicit user consent. That tool returns a shell command — the user must run it themselves outside this conversation. Update is destructive (file overwrites with backup) and stays a deliberate user action.
+
 ## 2. Five-phase protocol
 
 ### Phase 1 — BRAINSTORM

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

@@ -0,0 +1,127 @@
+/**
+ * BYAN update lifecycle helper for the MCP server.
+ *
+ * Read-only check: compares the installed BYAN version (from
+ * <projectRoot>/_byan/.manifest.json, falling back to package.json) against
+ * the latest published version on the npm registry.
+ *
+ * Apply path: returns *instructions* (a shell command) rather than executing
+ * anything itself. Update is destructive (overwrites files) and must remain
+ * an explicit user action, gated through the regular yanstaller pipeline
+ * (`npx create-byan-agent update`).
+ */
+
+import fsPromises from 'node:fs/promises';
+import nodePath from 'node:path';
+import https from 'node:https';
+
+export async function checkForUpdate(projectRoot) {
+  const installed = await getInstalledVersion(projectRoot);
+  let latest;
+  let networkError;
+  try {
+    latest = await getLatestVersion('create-byan-agent');
+  } catch (err) {
+    networkError = err.message || String(err);
+  }
+  if (!latest) {
+    return {
+      installed,
+      latest: null,
+      updateAvailable: false,
+      networkError,
+      note: 'Latest version unknown — npm registry unreachable. Skipped silently.',
+    };
+  }
+  if (installed === 'unknown') {
+    return {
+      installed,
+      latest,
+      updateAvailable: false,
+      note: '_byan/.manifest.json missing — installed version cannot be determined. The project may be a fresh manual setup; consider running `npx create-byan-agent` to write the manifest.',
+    };
+  }
+  const cmp = compareVersions(installed, latest);
+  return {
+    installed,
+    latest,
+    updateAvailable: cmp < 0,
+    isCurrent: cmp >= 0,
+    delta: cmp < 0 ? 'behind' : cmp > 0 ? 'ahead' : 'same',
+  };
+}
+
+export function formatApplyInstructions({ preview = false, force = false } = {}) {
+  const args = ['update'];
+  if (preview) args.push('--preview');
+  if (force) args.push('--force');
+  return {
+    command: `npx create-byan-agent ${args.join(' ')}`,
+    rationale: preview
+      ? 'Preview mode — no files are written. Inspects diff against the latest npm template.'
+      : 'Apply update via the yanstaller pipeline. yanstaller backs up the project, diffs vs latest npm template, and merges only non-user-modified files unless --force is set.',
+    safety: [
+      'Backup is automatic before any write.',
+      'User-modified files are preserved (unless --force).',
+      'A rollback command (`npx create-byan-agent rollback`) is available afterwards.',
+    ],
+    next: 'Ask the user to run the command above. Do not execute it from inside this tool.',
+  };
+}
+
+async function getInstalledVersion(projectRoot) {
+  // _byan/.manifest.json is the canonical source — written by yanstaller after
+  // every install/update. byan-mcp-server/package.json carries an unrelated
+  // local version and would lie if used as fallback, so we don't fall back at
+  // all: return 'unknown' and let callers surface that honestly.
+  const manifestPath = nodePath.join(projectRoot, '_byan', '.manifest.json');
+  try {
+    const raw = await fsPromises.readFile(manifestPath, 'utf8');
+    const manifest = JSON.parse(raw);
+    if (manifest && manifest.version) return manifest.version;
+  } catch {}
+  return 'unknown';
+}
+
+function getLatestVersion(packageName, { timeoutMs = 5000 } = {}) {
+  const url = `https://registry.npmjs.org/${packageName}/latest`;
+  return new Promise((resolve, reject) => {
+    const req = https.get(
+      url,
+      { headers: { Accept: 'application/json' } },
+      (res) => {
+        if (res.statusCode !== 200) {
+          reject(new Error(`npm registry returned ${res.statusCode} for ${packageName}`));
+          res.resume();
+          return;
+        }
+        let data = '';
+        res.on('data', (chunk) => { data += chunk; });
+        res.on('end', () => {
+          try {
+            resolve(JSON.parse(data).version);
+          } catch (err) {
+            reject(new Error(`Failed to parse npm registry response: ${err.message}`));
+          }
+        });
+      }
+    );
+    req.on('error', (err) => reject(new Error(`Failed to reach npm registry: ${err.message}`)));
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error(`npm registry request timed out after ${timeoutMs}ms`));
+    });
+  });
+}
+
+function compareVersions(a, b) {
+  const pa = String(a).replace(/^v/, '').split('.').map((n) => Number(n) || 0);
+  const pb = String(b).replace(/^v/, '').split('.').map((n) => Number(n) || 0);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const na = pa[i] || 0;
+    const nb = pb[i] || 0;
+    if (na < nb) return -1;
+    if (na > nb) return 1;
+  }
+  return 0;
+}

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

@@ -45,6 +45,14 @@ import {
   fcCheck,
   fcParse,
 } from './lib/cli.js';
+import { checkForUpdate, formatApplyInstructions } from './lib/update.js';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = nodePath.dirname(__filename);
+// Resolve the host project root: server.js lives at
+// {projectRoot}/_byan/mcp/byan-mcp-server/server.js, so go up three levels.
+const PROJECT_ROOT = nodePath.resolve(__dirname, '..', '..', '..');
 
 const BYAN_API_URL = process.env.BYAN_API_URL || 'http://localhost:3737';
 const BYAN_API_TOKEN = process.env.BYAN_API_TOKEN || '';
@@ -956,6 +964,35 @@ const tools = [
       additionalProperties: false,
     },
   },
+  {
+    name: 'byan_update_check',
+    description:
+      'Check whether the BYAN platform installed in this project is up to date. Read-only. Reads the installed version from _byan/.manifest.json (fallback: package.json), fetches the latest published version from the npm registry (registry.npmjs.org/create-byan-agent), compares them, and returns { installed, latest, updateAvailable, delta }. Network failures are reported (networkError) and treated as "do not block". Use at agent activation to surface updates without nagging.',
+    inputSchema: {
+      type: 'object',
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: 'byan_update_apply',
+    description:
+      'Returns the exact shell command the user must run to apply a BYAN update via the yanstaller pipeline (backup, diff vs latest npm template, merge non-user-modified files). Does NOT execute anything itself — update is destructive and must remain an explicit user action. Use after byan_update_check reports updateAvailable=true and the user has consented.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        preview: {
+          type: 'boolean',
+          description: 'If true, returns the --preview command (shows the diff without writing). Default: false.',
+        },
+        force: {
+          type: 'boolean',
+          description: 'If true, returns the --force command (overrides user-modified files). Default: false. Use with caution.',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
 ];
 
 const server = new Server(
@@ -1457,6 +1494,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
     }
 
+    if (name === 'byan_update_check') {
+      const status = await checkForUpdate(PROJECT_ROOT);
+      return { content: [{ type: 'text', text: JSON.stringify(status, null, 2) }] };
+    }
+
+    if (name === 'byan_update_apply') {
+      const instructions = formatApplyInstructions({
+        preview: args.preview === true,
+        force: args.force === true,
+      });
+      return { content: [{ type: 'text', text: JSON.stringify(instructions, null, 2) }] };
+    }
+
     throw new Error(`Unknown tool: ${name}`);
   } catch (err) {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.13.1",
+  "version": "2.14.1",
   "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 (Copilot CLI, Claude Code, Codex). Merise Agile + TDD + 64 Mantras. ~54% LLM cost savings.",
   "main": "src/index.js",
   "bin": {
@@ -17,7 +17,8 @@
     "test:watch": "jest --watch",
     "test:e2e": "jest __tests__/e2e-install-update.test.js",
     "setup-turbo-whisper": "node install/setup-turbo-whisper.js",
-    "byan": "echo \"BYAN agent installed. Use: copilot and type /agent\""
+    "byan": "echo \"BYAN agent installed. Use: copilot and type /agent\"",
+    "version": "node scripts/sync-install-version.js && git add install/package.json"
   },
   "keywords": [
     "byan",