create-byan-agent 2.11.0 → 2.11.2

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

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import fsSync from 'node:fs';
+import fsPromises from 'node:fs/promises';
+import nodePath from 'node:path';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import {
@@ -94,6 +97,81 @@ async function apiRequest(path, options = {}) {
   return body;
 }
 
+// Default filters — skip common build/vcs artifacts that pollute payload.
+const DEFAULT_SKIP_DIRS = new Set([
+  '.git', 'node_modules', 'dist', 'build', '.next', 'coverage',
+  '__pycache__', '.venv', 'venv', '.pytest_cache', '.mypy_cache',
+  'target', 'out', '.turbo', '.cache', '.DS_Store',
+]);
+const DEFAULT_SKIP_FILE_PATTERNS = [
+  /\.log$/i, /\.sqlite$/i, /\.sqlite-journal$/i, /\.sqlite-wal$/i,
+  /\.lock$/i, /\.pid$/i,
+];
+// Heuristic: treat as binary if content has NUL byte in first 8KB.
+function looksBinary(buf) {
+  const sample = buf.subarray(0, Math.min(buf.length, 8192));
+  for (const b of sample) if (b === 0) return true;
+  return false;
+}
+
+// Hard limits — match W1's API guards so we fail fast client-side.
+const MAX_FILES = 10000;
+const MAX_TOTAL_BYTES = 100 * 1024 * 1024; // 100 MB
+
+async function buildFilesPayload(absRoot, opts = {}) {
+  const skipDirs = opts.skipDirs || DEFAULT_SKIP_DIRS;
+  const skipPatterns = opts.skipPatterns || DEFAULT_SKIP_FILE_PATTERNS;
+  const maxFiles = opts.maxFiles || MAX_FILES;
+  const maxBytes = opts.maxBytes || MAX_TOTAL_BYTES;
+
+  const stat = await fsPromises.stat(absRoot);
+  if (!stat.isDirectory()) {
+    throw new Error(`Path is not a directory: ${absRoot}`);
+  }
+
+  const files = [];
+  let totalBytes = 0;
+
+  async function walk(dir) {
+    const entries = await fsPromises.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = nodePath.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (skipDirs.has(entry.name)) continue;
+        await walk(full);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (skipPatterns.some((re) => re.test(entry.name))) continue;
+
+      const rel = nodePath.relative(absRoot, full).split(nodePath.sep).join('/');
+      const buf = await fsPromises.readFile(full);
+
+      totalBytes += buf.length;
+      if (files.length + 1 > maxFiles) {
+        throw new Error(
+          `Too many files (>${maxFiles}). Add to skipDirs or increase maxFiles.`
+        );
+      }
+      if (totalBytes > maxBytes) {
+        throw new Error(
+          `Total size exceeds ${(maxBytes / 1024 / 1024).toFixed(0)}MB. ` +
+          `Prune node_modules/dist/build dirs or increase maxBytes.`
+        );
+      }
+
+      if (looksBinary(buf)) {
+        files.push({ path: rel, content: buf.toString('base64'), encoding: 'base64' });
+      } else {
+        files.push({ path: rel, content: buf.toString('utf8'), encoding: 'utf8' });
+      }
+    }
+  }
+
+  await walk(absRoot);
+  return { files, count: files.length, totalBytes };
+}
+
 const tools = [
   {
     name: 'byan_ping',
@@ -124,13 +202,13 @@ const tools = [
   {
     name: 'byan_import_project',
     description:
-      'Import a local project directory into byan_web. Scans BMAD artifacts (_bmad-output/, docs/, _bmad/_memory/). Requires auth.',
+      'Import a local project directory into byan_web. Reads files from the local filesystem (client-side) and uploads them as a payload; works whether byan_web is local or remote. Skips .git, node_modules, dist, build, coverage, *.log, *.sqlite. Limits: 10000 files, 100MB total. Requires auth.',
     inputSchema: {
       type: 'object',
       properties: {
         path: {
           type: 'string',
-          description: 'Absolute path to the project directory to import.',
+          description: 'Absolute path to the project directory on THIS machine (the MCP client). The API does not need filesystem access to this path.',
         },
         name: { type: 'string', description: 'Optional project name override.' },
         type: {
@@ -138,6 +216,14 @@ const tools = [
           enum: ['dev', 'training'],
           description: 'Project type. Default: dev.',
         },
+        maxFiles: {
+          type: 'number',
+          description: 'Override max file count (default 10000).',
+        },
+        maxBytes: {
+          type: 'number',
+          description: 'Override max total bytes (default 104857600 = 100MB).',
+        },
       },
       required: ['path'],
       additionalProperties: false,
@@ -820,10 +906,14 @@ const tools = [
   {
     name: 'byan_api_import_scan',
     description:
-      'Scan a local directory and report what would be imported. POST /api/import/scan. Requires BYAN_API_TOKEN.',
+      'Scan a local directory and report what would be imported into byan_web. Reads files from the local filesystem (client-side) and uploads them as a payload; works whether byan_web is local or remote. Skips .git, node_modules, dist, build, coverage, *.log, *.sqlite. Limits: 10000 files, 100MB total. Requires auth.',
     inputSchema: {
       type: 'object',
-      properties: { path: { type: 'string', description: 'Absolute path to scan.' } },
+      properties: {
+        path: { type: 'string', description: 'Absolute path to the directory on THIS machine (the MCP client). The API does not need filesystem access to this path.' },
+        maxFiles: { type: 'number', description: 'Override max file count (default 10000).' },
+        maxBytes: { type: 'number', description: 'Override max total bytes (default 104857600 = 100MB).' },
+      },
       required: ['path'],
       additionalProperties: false,
     },
@@ -831,10 +921,14 @@ const tools = [
   {
     name: 'byan_api_import_dry_run',
     description:
-      'Dry-run an import from a local directory (no writes). POST /api/import/dry-run. Requires BYAN_API_TOKEN.',
+      'Dry-run an import from a local directory into byan_web (no writes). Reads files from the local filesystem (client-side) and uploads them as a payload; works whether byan_web is local or remote. Skips .git, node_modules, dist, build, coverage, *.log, *.sqlite. Limits: 10000 files, 100MB total. Requires auth.',
     inputSchema: {
       type: 'object',
-      properties: { path: { type: 'string', description: 'Absolute path to dry-run.' } },
+      properties: {
+        path: { type: 'string', description: 'Absolute path to the directory on THIS machine (the MCP client). The API does not need filesystem access to this path.' },
+        maxFiles: { type: 'number', description: 'Override max file count (default 10000).' },
+        maxBytes: { type: 'number', description: 'Override max total bytes (default 104857600 = 100MB).' },
+      },
       required: ['path'],
       additionalProperties: false,
     },
@@ -899,10 +993,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       if (!BYAN_API_TOKEN) {
         throw new Error('BYAN_API_TOKEN env var is required for this tool.');
       }
+      // Always upload files payload — works for both localhost and remote API.
+      // The API still accepts { path } for backward compat if caller insists,
+      // but the MCP client has no reason to use it (we can always read locally).
+      const { files } = await buildFilesPayload(args.path, {
+        ...(args.maxFiles ? { maxFiles: args.maxFiles } : {}),
+        ...(args.maxBytes ? { maxBytes: args.maxBytes } : {}),
+      });
       const body = await apiRequest('/api/import/project', {
         method: 'POST',
         body: JSON.stringify({
-          path: args.path,
+          files,
           ...(args.name ? { name: args.name } : {}),
           ...(args.type ? { type: args.type } : {}),
         }),
@@ -1298,18 +1399,28 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
     if (name === 'byan_api_import_scan') {
       requireToken();
+      // Build files payload from client filesystem — works for remote byan_web.
+      const { files } = await buildFilesPayload(args.path, {
+        ...(args.maxFiles ? { maxFiles: args.maxFiles } : {}),
+        ...(args.maxBytes ? { maxBytes: args.maxBytes } : {}),
+      });
       const body = await apiRequest('/api/import/scan', {
         method: 'POST',
-        body: JSON.stringify({ path: args.path }),
+        body: JSON.stringify({ files }),
       });
       return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
     }
 
     if (name === 'byan_api_import_dry_run') {
       requireToken();
+      // Build files payload from client filesystem — works for remote byan_web.
+      const { files } = await buildFilesPayload(args.path, {
+        ...(args.maxFiles ? { maxFiles: args.maxFiles } : {}),
+        ...(args.maxBytes ? { maxBytes: args.maxBytes } : {}),
+      });
       const body = await apiRequest('/api/import/dry-run', {
         method: 'POST',
-        body: JSON.stringify({ path: args.path }),
+        body: JSON.stringify({ files }),
       });
       return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }] };
     }
@@ -1325,3 +1436,5 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 
 const transport = new StdioServerTransport();
 await server.connect(transport);
+
+export { buildFilesPayload };

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,
+};