create-byan-agent 2.9.10 → 2.11.1

package/node_modules/byan-platform-config/README.md

@@ -0,0 +1,107 @@
+# byan-platform-config
+
+Shared platform config primitives for BYAN. Single source of truth for
+`.mcp.json`, `.env`, `.claude/settings.local.json`, token prompting,
+byan_web reachability validation, and URL normalization.
+
+Consumed by both `create-byan-agent` (installer) and `update-byan-agent`
+(update CLI) so the two CLIs stay in sync.
+
+## Install
+
+```bash
+npm install byan-platform-config
+```
+
+## Public API
+
+```js
+const {
+  mcpConfig,
+  envConfig,
+  tokenPrompt,
+  validate,
+  urlUtils,
+} = require('byan-platform-config');
+```
+
+### mcpConfig — `.mcp.json` management
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `ensureMcpConfig` | `(projectRoot, { apiUrl, token }) → Promise<{ path }>` | READ-MERGE-WRITE. Strips `/api` suffix, preserves other mcpServers, preserves existing byan command/args. |
+| `readMcpConfig` | `(projectRoot) → Promise<object\|null>` | Returns parsed `.mcp.json` or `null` if missing/malformed. |
+| `mergeByanEntry` | `(existingConfig, { apiUrl, token }) → object` | Pure merge — no I/O. Returns a new config object. |
+
+```js
+await mcpConfig.ensureMcpConfig('/path/to/proj', {
+  apiUrl: 'http://localhost:3737',
+  token: 'byan_abc123',
+});
+```
+
+### envConfig — `.env` and `settings.local.json`
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `updateSettingsLocal` | `(projectRoot, envVars) → Promise<{ path }>` | Merges vars into `.claude/settings.local.json`, preserves unrelated keys. |
+| `updateDotenv` | `(projectRoot, envVars) → Promise<{ path }>` | Appends/updates `.env`, preserves comments and blank lines. |
+| `readEnvToken` | `(projectRoot) → Promise<string\|null>` | Reads `BYAN_API_TOKEN` with fallback chain : `.env` then `settings.local.json`. |
+
+```js
+await envConfig.updateDotenv('/path/to/proj', { BYAN_API_TOKEN: 'tok' });
+const tok = await envConfig.readEnvToken('/path/to/proj');
+```
+
+### tokenPrompt — interactive prompt
+
+| Symbol | Signature / Value | Description |
+|--------|-------------------|-------------|
+| `promptForToken` | `() → Promise<{ configured, apiUrl?, token? }>` | Inquirer prompt (confirm + URL + password). |
+| `ENV_KEYS` | `['BYAN_API_TOKEN', 'BYAN_API_URL']` | Canonical env var names. |
+
+```js
+const res = await tokenPrompt.promptForToken();
+if (res.configured) { /* use res.apiUrl, res.token */ }
+```
+
+### validate — reachability probe
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `validateByanWebReachability` | `({ apiUrl, token?, timeoutMs? }) → Promise<{ reachable, status?, latencyMs?, error? }>` | GET `/api/health`. Errors surface in the result object instead of throwing. Default timeout 5000 ms. |
+
+```js
+const r = await validate.validateByanWebReachability({
+  apiUrl: 'http://localhost:3737',
+  token: 'byan_abc',
+});
+// → { reachable: true, status: 200, latencyMs: 12 }
+```
+
+### urlUtils — URL normalization
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `stripApiSuffix` | `(url) → string` | Strips trailing `/api`, `/api/`, `/api/v1`, etc. |
+| `buildAuthHeader` | `(token) → { Authorization } \| {}` | `ApiKey` scheme for `byan_*` tokens, `Bearer` otherwise. |
+
+```js
+urlUtils.stripApiSuffix('http://x:1/api');  // → 'http://x:1'
+urlUtils.buildAuthHeader('byan_abc');       // → { Authorization: 'ApiKey byan_abc' }
+urlUtils.buildAuthHeader('eyJ...');         // → { Authorization: 'Bearer eyJ...' }
+```
+
+## Test
+
+```bash
+npm test
+```
+
+## Design invariants
+
+- READ-MERGE-WRITE on every file operation — unknown keys are preserved.
+- `ensureMcpConfig` keeps `mcpServers.byan.command` and `.args` if already set.
+- `validateByanWebReachability` resolves instead of rejecting — errors surface in the result object.
+- `stripApiSuffix` is idempotent and leaves URLs without a `/api` suffix untouched.
+- `buildAuthHeader` returns `{}` (not `{ Authorization: undefined }`) when token is missing.

package/node_modules/byan-platform-config/index.js

@@ -0,0 +1,16 @@
+/**
+ * byan-platform-config — shared platform config primitives.
+ *
+ * Single source of truth for .mcp.json management, .env/settings.local.json
+ * manipulation, token prompting, byan_web reachability validation, and URL
+ * normalization. Consumed by both install/ (create-byan-agent) and
+ * update-byan-agent/ so the two CLIs do not drift.
+ */
+
+module.exports = {
+  mcpConfig: require('./lib/mcp-config'),
+  envConfig: require('./lib/env-config'),
+  tokenPrompt: require('./lib/token-prompt'),
+  validate: require('./lib/validate'),
+  urlUtils: require('./lib/url-utils'),
+};

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

@@ -0,0 +1,128 @@
+/**
+ * .env and .claude/settings.local.json management.
+ *
+ * updateSettingsLocal : merge env vars into .claude/settings.local.json,
+ *                       preserving unrelated keys (permissions, hooks, etc.).
+ * updateDotenv        : append/update .env lines, preserving comments and
+ *                       blank lines, replacing (not duplicating) existing keys.
+ * readEnvToken        : fallback chain to read BYAN_API_TOKEN for migrations.
+ */
+
+const path = require('path');
+const fs = require('fs-extra');
+
+async function readJsonOrEmpty(filePath) {
+  if (await fs.pathExists(filePath)) {
+    try {
+      return await fs.readJson(filePath);
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {Record<string,string>} envVars
+ * @returns {Promise<{ path: string }>}
+ */
+async function updateSettingsLocal(projectRoot, envVars) {
+  const filePath = path.join(projectRoot, '.claude', 'settings.local.json');
+  const current = await readJsonOrEmpty(filePath);
+  current.env = { ...(current.env || {}), ...envVars };
+  await fs.ensureDir(path.dirname(filePath));
+  await fs.writeJson(filePath, current, { spaces: 2 });
+  return { path: filePath };
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {Record<string,string>} envVars
+ * @returns {Promise<{ path: string }>}
+ */
+async function updateDotenv(projectRoot, envVars) {
+  const filePath = path.join(projectRoot, '.env');
+  let content = '';
+  if (await fs.pathExists(filePath)) {
+    content = await fs.readFile(filePath, 'utf8');
+  }
+
+  const lines = content ? content.split(/\r?\n/) : [];
+  const keys = Object.keys(envVars);
+  const kept = lines.filter((line) => {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) return true;
+    const eq = trimmed.indexOf('=');
+    if (eq < 0) return true;
+    const key = trimmed.slice(0, eq).trim();
+    return !keys.includes(key);
+  });
+
+  while (kept.length && kept[kept.length - 1] === '') kept.pop();
+  for (const key of keys) {
+    const val = envVars[key] ?? '';
+    kept.push(`${key}=${val}`);
+  }
+  kept.push('');
+
+  await fs.writeFile(filePath, kept.join('\n'), 'utf8');
+  return { path: filePath };
+}
+
+/**
+ * Parses a single `KEY=value` line, respecting surrounding double quotes.
+ * Returns null for comment/empty/malformed lines.
+ */
+function parseDotenvLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith('#')) return null;
+  const eq = trimmed.indexOf('=');
+  if (eq < 0) return null;
+  const key = trimmed.slice(0, eq).trim();
+  let val = trimmed.slice(eq + 1).trim();
+  if (val.length >= 2 && val.startsWith('"') && val.endsWith('"')) {
+    val = val.slice(1, -1);
+  }
+  return { key, value: val };
+}
+
+/**
+ * Reads BYAN_API_TOKEN from .env first, falls back to
+ * .claude/settings.local.json env.BYAN_API_TOKEN. Returns null if neither
+ * contains a non-empty value.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<string|null>}
+ */
+async function readEnvToken(projectRoot) {
+  const dotenvPath = path.join(projectRoot, '.env');
+  if (await fs.pathExists(dotenvPath)) {
+    const content = await fs.readFile(dotenvPath, 'utf8');
+    for (const line of content.split(/\r?\n/)) {
+      const parsed = parseDotenvLine(line);
+      if (parsed && parsed.key === 'BYAN_API_TOKEN' && parsed.value) {
+        return parsed.value;
+      }
+    }
+  }
+
+  const settingsPath = path.join(projectRoot, '.claude', 'settings.local.json');
+  if (await fs.pathExists(settingsPath)) {
+    try {
+      const settings = await fs.readJson(settingsPath);
+      const tok = settings && settings.env && settings.env.BYAN_API_TOKEN;
+      if (typeof tok === 'string' && tok.length > 0) return tok;
+    } catch {
+      // ignore malformed json
+    }
+  }
+
+  return null;
+}
+
+module.exports = {
+  updateSettingsLocal,
+  updateDotenv,
+  readEnvToken,
+};

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

@@ -0,0 +1,95 @@
+/**
+ * .mcp.json management.
+ *
+ * READ-MERGE-WRITE semantics : preserves all existing mcpServers.* entries
+ * and, if byan entry already exists, preserves its command/args. Only the
+ * env.BYAN_API_URL and env.BYAN_API_TOKEN are authoritative from caller.
+ */
+
+const path = require('path');
+const fs = require('fs-extra');
+const { stripApiSuffix } = require('./url-utils');
+
+const MCP_SERVER_REL_PATH = '_byan/mcp/byan-mcp-server/server.js';
+
+async function readJsonOrEmpty(filePath) {
+  if (await fs.pathExists(filePath)) {
+    try {
+      return await fs.readJson(filePath);
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+
+/**
+ * Reads the project's .mcp.json.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<object|null>} parsed config or null if missing/malformed.
+ */
+async function readMcpConfig(projectRoot) {
+  const filePath = path.join(projectRoot, '.mcp.json');
+  if (!(await fs.pathExists(filePath))) return null;
+  try {
+    return await fs.readJson(filePath);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pure merge — no I/O. Returns a new config object with byan entry merged.
+ * Useful for migrations that inspect the diff before writing.
+ *
+ * @param {object} existingConfig — current parsed config (may be {} or {mcpServers:{...}})
+ * @param {{ apiUrl: string, token?: string }} opts
+ * @returns {object} new merged config
+ */
+function mergeByanEntry(existingConfig, { apiUrl, token } = {}) {
+  const cfg = existingConfig && typeof existingConfig === 'object' ? { ...existingConfig } : {};
+  cfg.mcpServers = { ...(cfg.mcpServers || {}) };
+
+  const existing = cfg.mcpServers.byan || {};
+  const cleanUrl = stripApiSuffix(apiUrl);
+
+  const env = { ...(existing.env || {}) };
+  env.BYAN_API_URL = cleanUrl;
+  if (token && typeof token === 'string' && token.length > 0) {
+    env.BYAN_API_TOKEN = token;
+  } else {
+    delete env.BYAN_API_TOKEN;
+  }
+
+  cfg.mcpServers.byan = {
+    command: 'node',
+    args: [MCP_SERVER_REL_PATH],
+    ...existing,
+    env,
+  };
+
+  return cfg;
+}
+
+/**
+ * Ensures .mcp.json exists with a valid byan entry. READ-MERGE-WRITE.
+ *
+ * @param {string} projectRoot
+ * @param {{ apiUrl: string, token?: string }} opts
+ * @returns {Promise<{ path: string }>}
+ */
+async function ensureMcpConfig(projectRoot, { apiUrl, token } = {}) {
+  const filePath = path.join(projectRoot, '.mcp.json');
+  const current = await readJsonOrEmpty(filePath);
+  const merged = mergeByanEntry(current, { apiUrl, token });
+  await fs.writeJson(filePath, merged, { spaces: 2 });
+  return { path: filePath };
+}
+
+module.exports = {
+  ensureMcpConfig,
+  readMcpConfig,
+  mergeByanEntry,
+  MCP_SERVER_REL_PATH,
+};

package/node_modules/byan-platform-config/lib/token-prompt.js

@@ -0,0 +1,61 @@
+/**
+ * Interactive prompt for byan_web API URL + JWT/ApiKey token.
+ *
+ * Extracted verbatim from install's byan-web-integration so the UX does
+ * not drift between create-byan-agent and update-byan-agent.
+ */
+
+const inquirer = require('inquirer');
+const chalk = require('chalk');
+
+const DEFAULT_API_URL = 'http://localhost:3737';
+const ENV_KEYS = ['BYAN_API_TOKEN', 'BYAN_API_URL'];
+
+/**
+ * @returns {Promise<{ configured: boolean, apiUrl?: string, token?: string }>}
+ */
+async function promptForToken() {
+  const { wantsToken } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'wantsToken',
+      message:
+        'Connect this project to your byan_web instance ? ' +
+        chalk.yellow('(service payant — requires a paid subscription to generate a token)'),
+      default: false,
+    },
+  ]);
+
+  if (!wantsToken) return { configured: false };
+
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'apiUrl',
+      message: 'byan_web API URL:',
+      default: DEFAULT_API_URL,
+      validate: (v) =>
+        /^https?:\/\//.test(v.trim()) || 'Must start with http:// or https://',
+    },
+    {
+      type: 'password',
+      name: 'token',
+      message: 'byan_web JWT token (from POST /api/auth/login):',
+      mask: '*',
+      validate: (v) =>
+        (typeof v === 'string' && v.trim().length > 0) || 'Token cannot be empty',
+    },
+  ]);
+
+  return {
+    configured: true,
+    apiUrl: answers.apiUrl.trim(),
+    token: answers.token.trim(),
+  };
+}
+
+module.exports = {
+  promptForToken,
+  ENV_KEYS,
+  DEFAULT_API_URL,
+};

package/node_modules/byan-platform-config/lib/url-utils.js

@@ -0,0 +1,27 @@
+/**
+ * URL utilities for BYAN platform config.
+ *
+ * stripApiSuffix : normalize apiUrl so the MCP server.js doesn't double the
+ *                  /api prefix (see install B5 bugfix).
+ * buildAuthHeader : ApiKey scheme for user-generated byan_ tokens,
+ *                   Bearer scheme for JWT tokens.
+ */
+
+function stripApiSuffix(url) {
+  if (typeof url !== 'string' || url.length === 0) return url;
+  // Strip trailing /api, /api/, /api/v1, /api/v1/ etc. — keep protocol/host intact.
+  return url.replace(/\/api(?:\/v\d+)?\/?$/, '');
+}
+
+function buildAuthHeader(token) {
+  if (!token || typeof token !== 'string' || token.length === 0) {
+    return {};
+  }
+  const scheme = token.startsWith('byan_') ? 'ApiKey' : 'Bearer';
+  return { Authorization: `${scheme} ${token}` };
+}
+
+module.exports = {
+  stripApiSuffix,
+  buildAuthHeader,
+};

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

@@ -0,0 +1,44 @@
+/**
+ * byan_web reachability probe.
+ *
+ * Never throws — always resolves with a plain result object. Uses
+ * AbortController to enforce a hard timeout (default 5s).
+ */
+
+const { stripApiSuffix, buildAuthHeader } = require('./url-utils');
+
+/**
+ * @param {{ apiUrl: string, token?: string, timeoutMs?: number }} opts
+ * @returns {Promise<{ reachable: boolean, status?: number, latencyMs?: number, error?: string }>}
+ */
+async function validateByanWebReachability({ apiUrl, token, timeoutMs = 5000 }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  const headers = buildAuthHeader(token);
+  const url = `${stripApiSuffix(apiUrl)}/api/health`;
+  const t0 = Date.now();
+
+  try {
+    const res = await fetch(url, { method: 'GET', headers, signal: controller.signal });
+    const latencyMs = Date.now() - t0;
+    clearTimeout(timer);
+
+    if (res.status >= 200 && res.status < 400) {
+      return { reachable: true, status: res.status, latencyMs };
+    }
+    return {
+      reachable: true,
+      status: res.status,
+      latencyMs,
+      error: `HTTP ${res.status}`,
+    };
+  } catch (err) {
+    clearTimeout(timer);
+    return { reachable: false, error: err.message || String(err) };
+  }
+}
+
+module.exports = {
+  validateByanWebReachability,
+};

package/node_modules/byan-platform-config/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "byan-platform-config",
+  "version": "1.0.0",
+  "description": "Shared platform config lib for BYAN install/update (.mcp.json, .env, token, validate, url)",
+  "main": "index.js",
+  "scripts": {
+    "test": "jest"
+  },
+  "keywords": [
+    "byan",
+    "platform-config",
+    "mcp",
+    "byan-web"
+  ],
+  "author": "Yan",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Yan-Acadenice/BYAN.git",
+    "directory": "install/packages/platform-config"
+  },
+  "homepage": "https://github.com/Yan-Acadenice/BYAN#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "fs-extra": "^11.2.0",
+    "inquirer": "^8.2.5"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "index.js",
+    "lib/",
+    "README.md"
+  ]
+}

package/node_modules/fs-extra/LICENSE

@@ -0,0 +1,15 @@
+(The MIT License)
+
+Copyright (c) 2011-2024 JP Richardson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files
+(the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify,
+ merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
+OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.