shabti 2.4.0 → 2.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shabti",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "description": "Agent Memory OS — semantic memory for AI agents",
   "type": "module",
   "main": "native.cjs",

package/src/a2a/agentCard.js

@@ -0,0 +1,48 @@
+import { readFileSync } from "fs";
+
+const { version } = JSON.parse(
+  readFileSync(new URL("../../package.json", import.meta.url), "utf8"),
+);
+
+export function buildAgentCard(baseUrl) {
+  return {
+    protocolVersion: "0.3.0",
+    name: "Shabti Memory Engine",
+    description: "A2A-compatible memory agent providing storage, search, and status operations",
+    url: baseUrl,
+    version,
+    capabilities: {
+      streaming: false,
+      pushNotifications: false,
+      stateTransitionHistory: false,
+    },
+    defaultInputModes: ["text", "application/json"],
+    defaultOutputModes: ["application/json"],
+    skills: [
+      {
+        id: "memory_store",
+        name: "Store Memory",
+        description: "Persist a memory entry with content and optional metadata tags",
+        tags: ["memory", "store", "save", "remember"],
+        inputModes: ["text", "application/json"],
+        outputModes: ["application/json"],
+      },
+      {
+        id: "memory_search",
+        name: "Search Memories",
+        description: "Search stored memories using semantic similarity queries",
+        tags: ["memory", "search", "recall", "find", "query"],
+        inputModes: ["text", "application/json"],
+        outputModes: ["application/json"],
+      },
+      {
+        id: "memory_status",
+        name: "Memory Status",
+        description: "Get status information about the memory engine",
+        tags: ["memory", "status", "health", "stats"],
+        inputModes: ["text"],
+        outputModes: ["application/json"],
+      },
+    ],
+  };
+}

package/src/a2a/server.js

@@ -0,0 +1,390 @@
+import { createServer } from "http";
+import { randomUUID } from "crypto";
+import { buildAgentCard } from "./agentCard.js";
+import { createEngine } from "../core/engine.js";
+import { logger } from "../utils/logger.js";
+
+// ============================================================
+// Task Store (in-memory)
+// ============================================================
+
+export class TaskStore {
+  constructor() {
+    this.tasks = new Map();
+  }
+
+  create(contextId) {
+    const task = {
+      kind: "task",
+      id: randomUUID(),
+      contextId: contextId || randomUUID(),
+      status: { state: "submitted", timestamp: new Date().toISOString() },
+      artifacts: [],
+      history: [],
+    };
+    this.tasks.set(task.id, task);
+    return task;
+  }
+
+  get(id) {
+    return this.tasks.get(id) || null;
+  }
+
+  set(id, task) {
+    this.tasks.set(id, task);
+  }
+
+  clear() {
+    this.tasks.clear();
+  }
+}
+
+// ============================================================
+// Skill Handlers
+// ============================================================
+
+async function handleMemoryStore(engine, parts) {
+  let content = null;
+  let opts = {};
+
+  for (const part of parts) {
+    if (part.kind === "data" && part.data) {
+      content = part.data.content || content;
+      if (part.data.namespace) opts.namespace = part.data.namespace;
+      if (part.data.tags) opts.tags = part.data.tags;
+      if (part.data.ttl) opts.ttlSeconds = part.data.ttl;
+    } else if (part.kind === "text" && part.text) {
+      content = content || part.text;
+    }
+  }
+
+  if (!content) {
+    throw Object.assign(new Error("Missing content in message parts"), { code: -32602 });
+  }
+
+  const result = await engine.store(content, opts);
+  return {
+    artifactId: randomUUID(),
+    name: "store_result",
+    parts: [{ kind: "data", data: { status: result.status, id: result.id || result.existingId } }],
+  };
+}
+
+async function handleMemorySearch(engine, parts) {
+  let query = null;
+  let limit = 10;
+
+  for (const part of parts) {
+    if (part.kind === "data" && part.data) {
+      query = part.data.query || query;
+      if (part.data.limit) limit = part.data.limit;
+    } else if (part.kind === "text" && part.text) {
+      query = query || part.text;
+    }
+  }
+
+  if (!query) {
+    throw Object.assign(new Error("Missing query in message parts"), { code: -32602 });
+  }
+
+  const results = await engine.executeQuery({ text: query, limit });
+  const formatted = results.map((r) => ({
+    id: r.id,
+    content: r.content,
+    score: r.score,
+    namespace: r.namespace,
+  }));
+
+  return {
+    artifactId: randomUUID(),
+    name: "search_results",
+    parts: [{ kind: "data", data: { query, results: formatted, count: formatted.length } }],
+  };
+}
+
+function handleMemoryStatus(engine) {
+  const status = engine.status();
+  return {
+    artifactId: randomUUID(),
+    name: "status",
+    parts: [
+      {
+        kind: "data",
+        data: {
+          status: "ok",
+          entry_count: status.entryCount,
+          tier: status.tier,
+          model_id: status.modelId,
+        },
+      },
+    ],
+  };
+}
+
+// ============================================================
+// Skill Router
+// ============================================================
+
+export function resolveSkill(parts) {
+  // Check for explicit skill in data parts
+  for (const part of parts) {
+    if (part.kind === "data" && part.data?.skill) {
+      return part.data.skill;
+    }
+  }
+
+  // Text-based routing
+  for (const part of parts) {
+    if (part.kind === "text" && part.text) {
+      const lower = part.text.toLowerCase();
+      if (/\b(store|save|remember)\b/.test(lower)) return "memory_store";
+      if (/\b(search|find|recall|query)\b/.test(lower)) return "memory_search";
+      if (/\b(status|health|stats|info)\b/.test(lower)) return "memory_status";
+    }
+  }
+
+  // Check for structured data that implies a skill
+  for (const part of parts) {
+    if (part.kind === "data" && part.data) {
+      if (part.data.content) return "memory_store";
+      if (part.data.query) return "memory_search";
+    }
+  }
+
+  return null;
+}
+
+// ============================================================
+// JSON-RPC Dispatcher (testable without HTTP)
+// ============================================================
+
+export async function dispatchRpc(engine, taskStore, method, params) {
+  switch (method) {
+    case "message/send":
+      return handleMessageSend(engine, taskStore, params || {});
+    case "tasks/get":
+      return handleTasksGet(taskStore, params || {});
+    case "tasks/cancel":
+      return handleTasksCancel(taskStore, params || {});
+    default:
+      return { error: { code: -32601, message: `Method not found: ${method}` } };
+  }
+}
+
+async function handleMessageSend(engine, taskStore, params) {
+  const message = params?.message;
+  if (!message || !message.parts || message.parts.length === 0) {
+    return { error: { code: -32602, message: "Missing message or parts" } };
+  }
+
+  const skill = resolveSkill(message.parts);
+  if (!skill) {
+    return {
+      error: { code: -32005, message: "Could not determine which skill to invoke from message" },
+    };
+  }
+
+  const task = taskStore.create(message.contextId);
+
+  // Store the incoming message in history
+  task.history.push(message);
+
+  try {
+    task.status = { state: "working", timestamp: new Date().toISOString() };
+
+    let artifact;
+    switch (skill) {
+      case "memory_store":
+        artifact = await handleMemoryStore(engine, message.parts);
+        break;
+      case "memory_search":
+        artifact = await handleMemorySearch(engine, message.parts);
+        break;
+      case "memory_status":
+        artifact = handleMemoryStatus(engine);
+        break;
+      default:
+        task.status = { state: "failed", timestamp: new Date().toISOString() };
+        taskStore.set(task.id, task);
+        return { error: { code: -32004, message: `Unknown skill: ${skill}` } };
+    }
+
+    task.artifacts = [artifact];
+    task.status = { state: "completed", timestamp: new Date().toISOString() };
+  } catch (err) {
+    task.status = {
+      state: "failed",
+      timestamp: new Date().toISOString(),
+      message: {
+        kind: "message",
+        role: "agent",
+        messageId: randomUUID(),
+        parts: [{ kind: "text", text: err.message }],
+      },
+    };
+    taskStore.set(task.id, task);
+    if (err.code) return { error: { code: err.code, message: err.message } };
+    return { error: { code: -32603, message: err.message } };
+  }
+
+  taskStore.set(task.id, task);
+  return { result: task };
+}
+
+function handleTasksGet(taskStore, params) {
+  const id = params?.id;
+  if (!id) return { error: { code: -32602, message: "Missing task id" } };
+
+  const task = taskStore.get(id);
+  if (!task) return { error: { code: -32001, message: `Task not found: ${id}` } };
+
+  // Apply historyLength filter
+  if (params.historyLength !== undefined) {
+    const result = { ...task };
+    const n = params.historyLength;
+    result.history = n === 0 ? [] : task.history.slice(-n);
+    return { result };
+  }
+
+  return { result: task };
+}
+
+function handleTasksCancel(taskStore, params) {
+  const id = params?.id;
+  if (!id) return { error: { code: -32602, message: "Missing task id" } };
+
+  const task = taskStore.get(id);
+  if (!task) return { error: { code: -32001, message: `Task not found: ${id}` } };
+
+  const terminal = ["completed", "failed", "canceled", "rejected"];
+  if (terminal.includes(task.status.state)) {
+    return {
+      error: { code: -32002, message: `Task is already in terminal state: ${task.status.state}` },
+    };
+  }
+
+  task.status = { state: "canceled", timestamp: new Date().toISOString() };
+  taskStore.set(task.id, task);
+  return { result: task };
+}
+
+// ============================================================
+// HTTP Server
+// ============================================================
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (c) => chunks.push(c));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString()));
+    req.on("error", reject);
+  });
+}
+
+export function startA2AServer(port = 3000) {
+  let engine = null;
+  let engineError = null;
+
+  function getEngine() {
+    if (engine) return engine;
+    if (engineError) throw engineError;
+    try {
+      engine = createEngine();
+      logger.info("A2A engine initialized");
+    } catch (err) {
+      logger.error("A2A engine initialization failed", { error: err.message });
+      engineError = err;
+      throw err;
+    }
+    return engine;
+  }
+
+  const baseUrl = `http://localhost:${port}/`;
+  const agentCard = buildAgentCard(baseUrl);
+  const taskStore = new TaskStore();
+
+  const server = createServer(async (req, res) => {
+    // CORS headers
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      return res.end();
+    }
+
+    // Agent Card discovery
+    if (req.method === "GET" && req.url === "/.well-known/agent-card.json") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      return res.end(JSON.stringify(agentCard, null, 2));
+    }
+
+    // JSON-RPC endpoint
+    if (req.method === "POST" && (req.url === "/" || req.url === "")) {
+      let body;
+      try {
+        body = await readBody(req);
+      } catch {
+        res.writeHead(400);
+        return res.end();
+      }
+
+      let rpc;
+      try {
+        rpc = JSON.parse(body);
+      } catch {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        return res.end(
+          JSON.stringify({
+            jsonrpc: "2.0",
+            id: null,
+            error: { code: -32700, message: "Parse error" },
+          }),
+        );
+      }
+
+      const { id, method, params } = rpc;
+      let response;
+
+      try {
+        response = await dispatchRpc(getEngine(), taskStore, method, params);
+      } catch (err) {
+        response = { error: { code: -32603, message: `Engine error: ${err.message}` } };
+      }
+
+      res.writeHead(200, { "Content-Type": "application/json" });
+      if (response.error) {
+        return res.end(JSON.stringify({ jsonrpc: "2.0", id, error: response.error }));
+      }
+      return res.end(JSON.stringify({ jsonrpc: "2.0", id, result: response.result }));
+    }
+
+    res.writeHead(404);
+    res.end("Not Found");
+  });
+
+  server.listen(port, "127.0.0.1", () => {
+    console.log(`\n  Shabti A2A server listening on ${baseUrl}`);
+    console.log(`  Agent Card: ${baseUrl}.well-known/agent-card.json`);
+    console.log(`  Skills: ${agentCard.skills.map((s) => s.id).join(", ")}\n`);
+  });
+
+  async function shutdown() {
+    console.log("\n  Shutting down A2A server...");
+    server.close();
+    if (engine && engine.shutdown) {
+      try {
+        await engine.shutdown();
+      } catch {
+        // best-effort
+      }
+    }
+    process.exit(0);
+  }
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+
+  return server;
+}

package/src/a2a/standalone.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Standalone A2A server entry point.
+ * Used by tests and `shabti a2a` CLI command.
+ */
+import { startA2AServer } from "./server.js";
+
+const port = parseInt(process.env.SHABTI_A2A_PORT || "3000", 10);
+startA2AServer(port);

package/src/commands/a2a.js

@@ -0,0 +1,19 @@
+import { startA2AServer } from "../a2a/server.js";
+import { error } from "../utils/style.js";
+import { parsePort } from "../utils/validate.js";
+
+export function registerA2A(program) {
+  program
+    .command("a2a")
+    .description("Start the A2A (Agent-to-Agent) protocol server")
+    .option("-p, --port <port>", "Port to listen on", "3000")
+    .action((opts) => {
+      try {
+        const port = parsePort(opts.port, "--port");
+        startA2AServer(port);
+      } catch (err) {
+        error(err.message);
+        process.exitCode = 1;
+      }
+    });
+}

package/src/commands/export.js

@@ -1,6 +1,7 @@
 import { writeFileSync } from "fs";
 import { createEngine } from "../core/engine.js";
 import { success, error } from "../utils/style.js";
+import { parsePositiveInt } from "../utils/validate.js";
 
 export function registerExport(program) {
   program
@@ -15,7 +16,7 @@ export function registerExport(program) {
         const engine = createEngine();
         const listOpts = {};
         if (opts.namespace) listOpts.namespace = opts.namespace;
-        if (opts.limit) listOpts.limit = parseInt(opts.limit, 10);
+        if (opts.limit) listOpts.limit = parsePositiveInt(opts.limit, "--limit");
         listOpts.includeEmbeddings = opts.embeddings !== false ? false : false;
         // --no-embeddings sets opts.embeddings = false (commander negatable)
         // default: exclude embeddings for smaller output

package/src/commands/import.js

@@ -1,4 +1,4 @@
-import { readFileSync } from "fs";
+import { readFileSync, existsSync } from "fs";
 import { createEngine } from "../core/engine.js";
 import { success, error, info, warn } from "../utils/style.js";
 
@@ -11,6 +11,11 @@ export function registerImport(program) {
     .option("--dry-run", "Parse and validate without storing")
     .action(async (file, opts) => {
       try {
+        if (!existsSync(file)) {
+          error(`File not found: ${file}`);
+          process.exitCode = 1;
+          return;
+        }
         const raw = readFileSync(file, "utf8");
         const lines = raw
           .split("\n")

package/src/commands/search.js

@@ -2,6 +2,7 @@ import chalk from "chalk";
 import Table from "cli-table3";
 import { createEngine } from "../core/engine.js";
 import { error, heading } from "../utils/style.js";
+import { parsePositiveInt, parseScore } from "../utils/validate.js";
 
 export function registerSearch(program) {
   program
@@ -23,13 +24,13 @@ export function registerSearch(program) {
         const engine = createEngine();
 
         const query = { text: queryText };
-        query.limit = parseInt(opts.limit, 10);
+        query.limit = parsePositiveInt(opts.limit, "--limit");
         if (opts.namespace) query.namespace = opts.namespace;
-        if (opts.timeStart) query.timeStart = parseInt(opts.timeStart, 10);
-        if (opts.timeEnd) query.timeEnd = parseInt(opts.timeEnd, 10);
-        if (opts.cluster) query.clusterId = parseInt(opts.cluster, 10);
-        if (opts.followLinks) query.maxHops = parseInt(opts.followLinks, 10);
-        if (opts.minScore) query.minScore = parseFloat(opts.minScore);
+        if (opts.timeStart) query.timeStart = parsePositiveInt(opts.timeStart, "--time-start");
+        if (opts.timeEnd) query.timeEnd = parsePositiveInt(opts.timeEnd, "--time-end");
+        if (opts.cluster) query.clusterId = parsePositiveInt(opts.cluster, "--cluster");
+        if (opts.followLinks) query.maxHops = parsePositiveInt(opts.followLinks, "--follow-links");
+        if (opts.minScore) query.minScore = parseScore(opts.minScore, "--min-score");
         if (opts.explain) query.withExplanation = true;
         if (opts.excludeSuperseded) query.excludeSuperseded = true;
 

package/src/commands/store.js

@@ -1,5 +1,6 @@
 import { createEngine, loadConfig, saveConfig } from "../core/engine.js";
 import { success, error, info, warn } from "../utils/style.js";
+import { parsePositiveInt } from "../utils/validate.js";
 
 export function registerStore(program) {
   program
@@ -17,7 +18,7 @@ export function registerStore(program) {
         if (opts.namespace) options.namespace = opts.namespace;
         if (opts.session) options.sessionId = opts.session;
         if (opts.tags) options.tags = opts.tags.split(",").map((t) => t.trim());
-        if (opts.ttl) options.ttlSeconds = parseInt(opts.ttl, 10);
+        if (opts.ttl) options.ttlSeconds = parsePositiveInt(opts.ttl, "--ttl");
 
         // Model versioning check
         const currentModelId = engine.modelId();

package/src/core/retry.js

@@ -0,0 +1,49 @@
+import { logger } from "../utils/logger.js";
+
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_BACKOFF_MS = [500, 1000, 2000];
+
+/**
+ * Create an engine with retry and exponential backoff.
+ * Intended for long-running servers (MCP, A2A) — not for one-shot CLI commands.
+ *
+ * @param {Function} factory - Function that creates the engine (e.g., createEngine)
+ * @param {object} [options]
+ * @param {number} [options.maxRetries=3]
+ * @param {number[]} [options.backoffMs=[500,1000,2000]]
+ * @returns {Promise<object>} The created engine
+ */
+export async function createEngineWithRetry(factory, options = {}) {
+  const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const backoffs = options.backoffMs ?? DEFAULT_BACKOFF_MS;
+
+  let lastError;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const engine = factory();
+      if (attempt > 0) {
+        logger.info(`Engine connected after ${attempt + 1} attempts`);
+      }
+      return engine;
+    } catch (err) {
+      lastError = err;
+      if (attempt < maxRetries) {
+        const delay = backoffs[Math.min(attempt, backoffs.length - 1)];
+        logger.warn(
+          `Engine connection failed (attempt ${attempt + 1}/${maxRetries + 1}), retrying in ${delay}ms`,
+          {
+            error: err.message,
+          },
+        );
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+  }
+
+  logger.error(`Engine connection failed after ${maxRetries + 1} attempts`, {
+    error: lastError.message,
+    hint: "Is Qdrant running? Try: shabti config setup --check",
+  });
+  throw lastError;
+}

package/src/index.js

@@ -3,6 +3,7 @@
 import { readFileSync } from "fs";
 import chalk from "chalk";
 import { Command } from "commander";
+import { registerA2A } from "./commands/a2a.js";
 import { registerChat } from "./commands/chat.js";
 import { registerConfig } from "./commands/config.js";
 import { registerHello } from "./commands/hello.js";
@@ -71,6 +72,7 @@ function buildProgram() {
     .name("shabti")
     .description("Agent Memory OS — semantic memory for AI agents")
     .version(version);
+  registerA2A(program);
   registerChat(program);
   registerConfig(program);
   registerHello(program);

package/src/mcp/server.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import { createInterface } from "readline";
 import { createEngine, loadConfig } from "../core/engine.js";
+import { createEngineWithRetry } from "../core/retry.js";
+import { logger } from "../utils/logger.js";
 
 const SERVER_INFO = {
   name: "shabti-memory",
@@ -123,11 +125,22 @@ let engineInitAttempted = false;
 function initEngine() {
   if (engine) return engine;
   if (engineInitAttempted) return null;
+  // Synchronous fallback for initial attempt
   engineInitAttempted = true;
   try {
     engine = createEngine();
-  } catch {
-    // engine stays null — tools will return errors
+    logger.info("Engine initialized");
+  } catch (err) {
+    logger.warn("Engine not available, starting background retry", { error: err.message });
+    // Start async retry in background
+    createEngineWithRetry(createEngine)
+      .then((eng) => {
+        engine = eng;
+        logger.info("Engine connected via retry");
+      })
+      .catch(() => {
+        logger.error("Engine retry exhausted — tools will return errors");
+      });
   }
   return engine;
 }
@@ -445,4 +458,20 @@ rl.on("line", (line) => {
   const trimmed = line.trim();
   if (trimmed) handleRequest(trimmed);
 });
-rl.on("close", () => process.exit(0));
+
+async function shutdown() {
+  logger.info("MCP server shutting down");
+  rl.close();
+  if (engine && engine.shutdown) {
+    try {
+      await engine.shutdown();
+    } catch {
+      // best-effort
+    }
+  }
+  process.exit(0);
+}
+
+rl.on("close", shutdown);
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);

package/src/utils/logger.js

@@ -0,0 +1,40 @@
+const LEVELS = { debug: 0, info: 1, warn: 2, error: 3, silent: 4 };
+
+function getLevel() {
+  const name = (process.env.SHABTI_LOG_LEVEL || "info").toLowerCase();
+  return LEVELS[name] ?? LEVELS.info;
+}
+
+function isJsonMode() {
+  return process.env.SHABTI_LOG_JSON === "1";
+}
+
+function shouldLog(level) {
+  return LEVELS[level] >= getLevel();
+}
+
+function formatTimestamp() {
+  return new Date().toISOString();
+}
+
+function log(level, message, data) {
+  if (!shouldLog(level)) return;
+
+  if (isJsonMode()) {
+    const entry = { timestamp: formatTimestamp(), level, message };
+    if (data !== undefined) entry.data = data;
+    process.stderr.write(JSON.stringify(entry) + "\n");
+  } else {
+    const prefix = `[${formatTimestamp()}] [${level.toUpperCase()}]`;
+    const msg =
+      data !== undefined ? `${prefix} ${message} ${JSON.stringify(data)}` : `${prefix} ${message}`;
+    process.stderr.write(msg + "\n");
+  }
+}
+
+export const logger = {
+  debug: (message, data) => log("debug", message, data),
+  info: (message, data) => log("info", message, data),
+  warn: (message, data) => log("warn", message, data),
+  error: (message, data) => log("error", message, data),
+};

package/src/utils/validate.js

@@ -0,0 +1,54 @@
+/**
+ * Parse a string as a positive integer. Returns the number or throws.
+ */
+export function parsePositiveInt(value, name) {
+  const n = parseInt(value, 10);
+  if (isNaN(n) || n <= 0) {
+    throw new Error(`${name} must be a positive integer, got: ${value}`);
+  }
+  return n;
+}
+
+/**
+ * Parse a string as a non-negative integer (>= 0). Returns the number or throws.
+ */
+export function parseNonNegativeInt(value, name) {
+  const n = parseInt(value, 10);
+  if (isNaN(n) || n < 0) {
+    throw new Error(`${name} must be a non-negative integer, got: ${value}`);
+  }
+  return n;
+}
+
+/**
+ * Parse a string as a positive float. Returns the number or throws.
+ */
+export function parsePositiveFloat(value, name) {
+  const n = parseFloat(value);
+  if (isNaN(n) || n <= 0) {
+    throw new Error(`${name} must be a positive number, got: ${value}`);
+  }
+  return n;
+}
+
+/**
+ * Parse a string as a float in [0, 1]. Returns the number or throws.
+ */
+export function parseScore(value, name) {
+  const n = parseFloat(value);
+  if (isNaN(n) || n < 0 || n > 1) {
+    throw new Error(`${name} must be a number between 0 and 1, got: ${value}`);
+  }
+  return n;
+}
+
+/**
+ * Parse a string as a valid TCP port (1–65535). Returns the number or throws.
+ */
+export function parsePort(value, name) {
+  const n = parseInt(value, 10);
+  if (isNaN(n) || n < 1 || n > 65535) {
+    throw new Error(`${name} must be a port number (1–65535), got: ${value}`);
+  }
+  return n;
+}