cisco-perfmon 1.6.0 → 2.0.0

package/cli/utils/config.js

@@ -0,0 +1,112 @@
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+const { execSync } = require("node:child_process");
+
+const SS_PLACEHOLDER_RE = /<ss:(\d+):(\w+)>/g;
+
+function getConfigDir() {
+  return process.env.CISCO_PERFMON_CONFIG_DIR || path.join(os.homedir(), ".cisco-perfmon");
+}
+
+function getConfigPath() {
+  return path.join(getConfigDir(), "config.json");
+}
+
+function loadConfig() {
+  const configPath = getConfigPath();
+  if (!fs.existsSync(configPath)) return { activeCluster: null, clusters: {} };
+  return JSON.parse(fs.readFileSync(configPath, "utf-8"));
+}
+
+function saveConfig(config) {
+  const dir = getConfigDir();
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  fs.writeFileSync(getConfigPath(), JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+
+function addCluster(name, opts) {
+  const config = loadConfig();
+  config.clusters[name] = { host: opts.host, username: opts.username, password: opts.password };
+  if (opts.insecure) config.clusters[name].insecure = true;
+  if (!config.activeCluster) config.activeCluster = name;
+  saveConfig(config);
+}
+
+function useCluster(name) {
+  const config = loadConfig();
+  if (!config.clusters[name]) throw new Error(`Cluster "${name}" not found. Run "cisco-perfmon config list" to see available clusters.`);
+  config.activeCluster = name;
+  saveConfig(config);
+}
+
+function removeCluster(name) {
+  const config = loadConfig();
+  if (!config.clusters[name]) throw new Error(`Cluster "${name}" not found.`);
+  delete config.clusters[name];
+  if (config.activeCluster === name) {
+    const remaining = Object.keys(config.clusters);
+    config.activeCluster = remaining.length > 0 ? remaining[0] : null;
+  }
+  saveConfig(config);
+}
+
+function getActiveCluster(clusterName) {
+  const config = loadConfig();
+  const name = clusterName || config.activeCluster;
+  if (!name || !config.clusters[name]) return null;
+  return { name, ...config.clusters[name] };
+}
+
+function listClusters() {
+  const config = loadConfig();
+  return { activeCluster: config.activeCluster, clusters: config.clusters };
+}
+
+function maskPassword(password) {
+  if (!password) return "";
+  SS_PLACEHOLDER_RE.lastIndex = 0;
+  if (SS_PLACEHOLDER_RE.test(password)) { SS_PLACEHOLDER_RE.lastIndex = 0; return password; }
+  return "*".repeat(password.length);
+}
+
+function hasSsPlaceholders(obj) {
+  for (const value of Object.values(obj)) {
+    if (typeof value === "string") {
+      SS_PLACEHOLDER_RE.lastIndex = 0;
+      if (SS_PLACEHOLDER_RE.test(value)) { SS_PLACEHOLDER_RE.lastIndex = 0; return true; }
+    }
+  }
+  return false;
+}
+
+function resolveSsPlaceholders(obj) {
+  const resolved = { ...obj };
+  for (const [key, value] of Object.entries(resolved)) {
+    if (typeof value !== "string") continue;
+    SS_PLACEHOLDER_RE.lastIndex = 0;
+    resolved[key] = value.replace(SS_PLACEHOLDER_RE, (match, id, field) => {
+      try {
+        const output = execSync(`ss-cli get ${id} --format json`, { encoding: "utf-8", timeout: 10000 });
+        const secret = JSON.parse(output);
+        if (secret[field] !== undefined) return secret[field];
+        if (Array.isArray(secret.items)) {
+          const item = secret.items.find((i) => i.fieldName === field || i.slug === field);
+          if (item) return item.itemValue;
+        }
+        throw new Error(`Field "${field}" not found in secret ${id}`);
+      } catch (err) {
+        if (err.message.includes("ENOENT") || err.message.includes("not found")) {
+          throw new Error(`Config contains Secret Server references (<ss:...>) but ss-cli is not available. Install with: npm install -g @sieteunoseis/ss-cli`);
+        }
+        throw err;
+      }
+    });
+  }
+  return resolved;
+}
+
+module.exports = {
+  getConfigDir, getConfigPath, loadConfig, saveConfig, addCluster, useCluster, removeCluster,
+  getActiveCluster, listClusters, maskPassword, hasSsPlaceholders, resolveSsPlaceholders,
+};

package/cli/utils/connection.js

@@ -0,0 +1,36 @@
+const configUtil = require("./config.js");
+
+function resolveConfig(flags) {
+  const env = {
+    host: process.env.CUCM_HOST || process.env.CUCM_HOSTNAME || undefined,
+    username: process.env.CUCM_USERNAME || undefined,
+    password: process.env.CUCM_PASSWORD || undefined,
+  };
+
+  let fileConfig = {};
+  const cluster = configUtil.getActiveCluster(flags.cluster || undefined);
+  if (cluster) fileConfig = cluster;
+
+  const resolved = {
+    host: flags.host || env.host || fileConfig.host,
+    username: flags.username || env.username || fileConfig.username,
+    password: flags.password || env.password || fileConfig.password,
+    insecure: flags.insecure || fileConfig.insecure || false,
+  };
+
+  if (!resolved.host || !resolved.username || !resolved.password) {
+    throw new Error(
+      "No cluster configured. Set one up with:\n" +
+      "  cisco-perfmon config add <name> --host <h> --username <u> --password <p>\n" +
+      "  Or set environment variables: CUCM_HOST, CUCM_USERNAME, CUCM_PASSWORD"
+    );
+  }
+
+  if (configUtil.hasSsPlaceholders(resolved)) {
+    Object.assign(resolved, configUtil.resolveSsPlaceholders(resolved));
+  }
+
+  return resolved;
+}
+
+module.exports = { resolveConfig };

package/cli/utils/output.js

@@ -0,0 +1,28 @@
+const formatTable = require("../formatters/table.js");
+const formatJson = require("../formatters/json.js");
+const formatToon = require("../formatters/toon.js");
+const formatCsv = require("../formatters/csv.js");
+
+const formatters = { table: formatTable, json: formatJson, toon: formatToon, csv: formatCsv };
+
+async function printResult(data, format) {
+  const formatter = formatters[format || "table"];
+  if (!formatter) throw new Error(`Unknown format "${format}". Valid: table, json, toon, csv`);
+  const output = await Promise.resolve(formatter(data));
+  console.log(output);
+}
+
+function printError(err) {
+  const message = err.message || String(err);
+  process.stderr.write(`Error: ${message}\n`);
+  if (message.includes("Authentication failed") || (err.status === 401)) {
+    process.stderr.write('Hint: Run "cisco-perfmon config test" to verify your credentials.\n');
+  } else if (message.includes("Rate limit") || message.includes("Exceeded allowed rate") || err.status === 429) {
+    process.stderr.write("Hint: Wait 30 seconds and try again, or reduce polling frequency with --interval.\n");
+  } else if (message.includes("certificate") || message.includes("CERT")) {
+    process.stderr.write("Hint: Use --insecure for self-signed certificates.\n");
+  }
+  process.exitCode = 1;
+}
+
+module.exports = { printResult, printError };

package/main.js

@@ -112,19 +112,21 @@ const XML_REMOVE_COUNTER_ENVELOPE = (sessionHandle, counters) => `<soapenv:Envel
  * @param {string} host - The host to collect data from. This is usually the IP address/FQDN of the CUCM publisher.
  * @param {string} username - The username to authenticate with. This is usually an AXL user. Can leave this blank if using JESSIONSSO cookie.
  * @param {string} password - The password to authenticate with. This is usually an AXL user. Can leave this blank if using JESSIONSSO cookie.
- * @param {object} options - Additional headers to add to the request. Useful for adding cookies for SSO sessions.
+ * @param {object} options - Options object. Supports `retries` (default 3), `retryDelay` ms (default 5000), and any additional headers (e.g. cookies for SSO).
  * @returns {object} returns constructor object.
  */
 class perfMonService {
   constructor(host, username, password, options = {}, retry = true) {
     const RATE_LIMIT_DELAYS = [30000, 60000, 120000]; // 30s, 60s, 120s exponential backoff
+    const maxRetries = options.retries ?? (process.env.PM_RETRY ? parseInt(process.env.PM_RETRY) : 3);
+    const retryDelay = options.retryDelay ?? (process.env.PM_RETRY_DELAY ? parseInt(process.env.PM_RETRY_DELAY) : 5000);
 
     this._OPTIONS = {
       retryOn: async function (attempt, error, response) {
         if (!retry) {
           return false;
         }
-        if (attempt > (process.env.PM_RETRY ? parseInt(process.env.PM_RETRY) : 3)) {
+        if (attempt > maxRetries) {
           return false;
         }
 
@@ -147,7 +149,7 @@ class perfMonService {
         // retry on any network error, or 4xx or 5xx status codes
         if (error !== null || response.status >= 400) {
           const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-          await delay(process.env.PM_RETRY_DELAY ? parseInt(process.env.PM_RETRY_DELAY) : 5000);
+          await delay(retryDelay);
           return true;
         }
       },
@@ -204,7 +206,7 @@ class perfMonService {
    */
   async collectCounterData(host, object) {
     try {
-      let options = this._OPTIONS;
+      let options = { ...this._OPTIONS, headers: { ...this._OPTIONS.headers } };
       let server = this._HOST;
       let XML = XML_COLLECT_COUNTER_ENVELOPE(escapeXml(host), escapeXml(object));
       let soapBody = Buffer.from(XML);
@@ -220,9 +222,6 @@ class perfMonService {
       };
 
       promiseResults.cookie = response.headers.get("set-cookie") ? response.headers.get("set-cookie") : "";
-    if (promiseResults.cookie) {
-      this.setCookie(promiseResults.cookie);
-    }
       if (promiseResults.cookie) {
         this.setCookie(promiseResults.cookie);
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cisco-perfmon",
-  "version": "1.6.0",
+  "version": "2.0.0",
   "description": "A library to pull Perfmon data from Cisco VOS applications via SOAP",
   "main": "main.js",
   "module": "main.mjs",
@@ -12,8 +12,14 @@
       "types": "./types/index.d.ts"
     }
   },
+  "bin": {
+    "cisco-perfmon": "./bin/cisco-perfmon.js"
+  },
+  "funding": "https://buymeacoffee.com/automatebldrs",
   "scripts": {
-    "test": "NODE_OPTIONS=--experimental-vm-modules NODE_NO_WARNINGS=1 NODE_TLS_REJECT_UNAUTHORIZED=0 NODE_ENV=test node ./test/tests.js",
+    "test": "node ./test/unit.js",
+    "test:unit": "node ./test/unit.js",
+    "test:integration": "NODE_OPTIONS=--experimental-vm-modules NODE_NO_WARNINGS=1 NODE_TLS_REJECT_UNAUTHORIZED=0 NODE_ENV=test node ./test/tests.js",
     "development": "NODE_OPTIONS=--experimental-vm-modules NODE_NO_WARNINGS=1 NODE_TLS_REJECT_UNAUTHORIZED=0 NODE_ENV=development node ./test/tests.js",
     "generate-config": "NODE_OPTIONS=--experimental-vm-modules NODE_NO_WARNINGS=1 NODE_TLS_REJECT_UNAUTHORIZED=0 NODE_ENV=test node ./test/generateConfig.js",
     "rate-limit-test": "NODE_OPTIONS=--experimental-vm-modules NODE_NO_WARNINGS=1 NODE_TLS_REJECT_UNAUTHORIZED=0 NODE_ENV=test node ./test/rateLimitTest.js"
@@ -36,7 +42,12 @@
   },
   "homepage": "https://github.com/sieteunoseis/cisco-perfmon#readme",
   "dependencies": {
+    "@toon-format/toon": "^2.1.0",
+    "cli-table3": "^0.6.5",
+    "commander": "^12.1.0",
+    "csv-stringify": "^6.5.2",
     "fetch-retry": "^6.0.0",
+    "update-notifier": "^7.3.1",
     "xml2js": "^0.6.0"
   },
   "devDependencies": {

package/skills/cisco-perfmon-cli/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: cisco-perfmon-cli
+description: Use when collecting Cisco CUCM real-time performance counters via the cisco-perfmon CLI — CPU, memory, call statistics, device counts, and continuous monitoring with sparkline visualization.
+license: MIT
+metadata:
+  author: sieteunoseis
+  version: "1.0.0"
+---
+
+# cisco-perfmon CLI
+
+CLI for collecting Cisco CUCM real-time performance counters via the PerfMon SOAP API. Supports one-shot collection, session-based polling, continuous monitoring with live sparkline visualization, and multiple output formats.
+
+## Setup
+
+Configure a cluster (one-time):
+
+```bash
+cisco-perfmon config add <name> --host <host> --username <user> --password <pass> --insecure
+cisco-perfmon config test
+```
+
+For Secret Server integration:
+
+```bash
+cisco-perfmon config add <name> --host '<ss:ID:host>' --username '<ss:ID:username>' --password '<ss:ID:password>' --insecure
+```
+
+Or use environment variables:
+
+```bash
+export CUCM_HOST=<host>
+export CUCM_USERNAME=<user>
+export CUCM_PASSWORD=<pass>
+```
+
+## Commands
+
+### config -- Manage cluster configurations
+
+```bash
+cisco-perfmon config add <name> --host <host> --username <user> --password <pass>
+cisco-perfmon config use <name>
+cisco-perfmon config list
+cisco-perfmon config show
+cisco-perfmon config remove <name>
+cisco-perfmon config test
+```
+
+### list-objects -- List available perfmon counter objects
+
+```bash
+cisco-perfmon list-objects                          # all objects
+cisco-perfmon list-objects --search "CallManager"   # filter by keyword
+cisco-perfmon list-objects --format json             # JSON output
+```
+
+### list-instances -- List instances of a perfmon object
+
+```bash
+cisco-perfmon list-instances "Cisco CallManager"
+cisco-perfmon list-instances "Process" --format json
+```
+
+### describe -- Get counter descriptions
+
+```bash
+cisco-perfmon describe "Cisco CallManager"
+cisco-perfmon describe "Cisco CallManager" --counter CallsActive
+cisco-perfmon describe "Cisco CallManager" --counter CallsActive --instance ""
+```
+
+### collect -- One-shot counter data collection
+
+```bash
+cisco-perfmon collect "Cisco CallManager"                                       # all counters
+cisco-perfmon collect "Cisco CallManager" --counter CallsActive,CallsInProgress # specific counters
+cisco-perfmon collect "Cisco CallManager" --instance ""                          # filter by instance
+cisco-perfmon collect "Processor" --format json                                  # JSON output
+cisco-perfmon collect "Memory" --format csv > memory.csv                         # export to CSV
+```
+
+### session -- Manage perfmon polling sessions
+
+```bash
+cisco-perfmon session open                          # get a session handle
+cisco-perfmon session add <handle> --counters '[{"host":"cucm","object":"Cisco CallManager","counter":"CallsActive"}]'
+cisco-perfmon session collect <handle>              # collect session data
+cisco-perfmon session remove <handle> --counters '[...]'
+cisco-perfmon session close <handle>
+```
+
+### watch -- Continuous monitoring with live sparklines
+
+The watch command polls counters at a configurable interval and displays a live-updating table with sparkline visualizations showing value trends over the last 12 samples.
+
+```bash
+cisco-perfmon watch "Cisco CallManager"                                         # watch all counters
+cisco-perfmon watch "Cisco CallManager" --counter CallsActive --interval 5      # specific counter, 5s interval
+cisco-perfmon watch "Processor" --counter "% CPU Time" --instance "_Total"      # CPU monitoring
+cisco-perfmon watch "Memory" --interval 30 --duration 300                       # 5-minute memory check
+cisco-perfmon watch "Cisco CallManager" --format json --interval 10             # JSON output for piping
+```
+
+The table view shows: counter name, instance, current value, sparkline trend, min, max, and average. Press Ctrl+C to stop.
+
+### doctor -- Configuration and connectivity health check
+
+```bash
+cisco-perfmon doctor                                # run all checks
+cisco-perfmon doctor --insecure                     # with TLS skip
+```
+
+Checks: active cluster config, PerfMon API connectivity, counter object availability, config file permissions, audit trail size.
+
+## Common Workflows
+
+### Check system health
+
+```bash
+cisco-perfmon doctor
+cisco-perfmon collect "Cisco CallManager" --format json
+```
+
+### Monitor calls during testing
+
+```bash
+cisco-perfmon watch "Cisco CallManager" --counter CallsActive,CallsInProgress,CallsAttempted --interval 5
+```
+
+### CPU investigation
+
+```bash
+cisco-perfmon watch "Processor" --counter "% CPU Time" --instance "_Total" --interval 10
+cisco-perfmon collect "Processor" --format json
+```
+
+### List what counters are available
+
+```bash
+cisco-perfmon list-objects --search "Cisco"
+cisco-perfmon list-instances "Cisco CallManager"
+cisco-perfmon describe "Cisco CallManager" --counter CallsActive
+```
+
+### Export counter data to CSV
+
+```bash
+cisco-perfmon collect "Cisco CallManager" --format csv > callmanager.csv
+```
+
+### Session-based polling for selective counters
+
+```bash
+HANDLE=$(cisco-perfmon session open --format json | jq -r '.sessionHandle')
+cisco-perfmon session add "$HANDLE" --counters '[{"host":"cucm-pub","object":"Cisco CallManager","counter":"CallsActive"}]'
+cisco-perfmon session collect "$HANDLE"
+cisco-perfmon session close "$HANDLE"
+```
+
+## Output Formats
+
+- `--format table` (default) -- human-readable table
+- `--format json` -- for scripting/parsing
+- `--format toon` -- token-efficient for AI agents (recommended)
+- `--format csv` -- for spreadsheets
+
+## Global Flags
+
+- `--host <host>` -- override CUCM hostname
+- `--username <user>` -- override CUCM username
+- `--password <pass>` -- override CUCM password
+- `--cluster <name>` -- use a specific named cluster
+- `--insecure` -- skip TLS certificate verification (required for self-signed certs)
+- `--no-audit` -- disable audit logging for this command
+- `--debug` -- enable debug logging

package/test/cli/config.test.js

@@ -0,0 +1,196 @@
+const assert = require("assert");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+let passed = 0, failed = 0, total = 0;
+function describe(name, fn) { console.log(`  ${name}`); fn(); }
+function it(name, fn) {
+  total++;
+  try { fn(); console.log(`    \u2713 ${name}`); passed++; }
+  catch (e) { console.log(`    \u2717 ${name}: ${e.message}`); failed++; }
+}
+
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "cisco-perfmon-test-config-"));
+process.env.CISCO_PERFMON_CONFIG_DIR = tmpDir;
+
+const {
+  loadConfig, saveConfig, addCluster, useCluster, removeCluster,
+  getActiveCluster, listClusters, maskPassword, hasSsPlaceholders,
+  getConfigDir, getConfigPath,
+} = require("../../cli/utils/config.js");
+
+describe("getConfigDir", () => {
+  it("returns the CISCO_PERFMON_CONFIG_DIR env value", () => {
+    assert.strictEqual(getConfigDir(), tmpDir);
+  });
+
+  it("returns path under home when env is unset", () => {
+    const saved = process.env.CISCO_PERFMON_CONFIG_DIR;
+    delete process.env.CISCO_PERFMON_CONFIG_DIR;
+    const dir = getConfigDir();
+    assert.strictEqual(dir, path.join(os.homedir(), ".cisco-perfmon"));
+    process.env.CISCO_PERFMON_CONFIG_DIR = saved;
+  });
+});
+
+describe("getConfigPath", () => {
+  it("returns config.json inside config dir", () => {
+    assert.ok(getConfigPath().endsWith("config.json"));
+  });
+});
+
+describe("loadConfig", () => {
+  it("returns defaults when no config file exists", () => {
+    const config = loadConfig();
+    assert.strictEqual(config.activeCluster, null);
+    assert.deepStrictEqual(config.clusters, {});
+  });
+});
+
+describe("saveConfig / loadConfig round-trip", () => {
+  it("writes and reads back the same data", () => {
+    const data = { activeCluster: "lab", clusters: { lab: { host: "10.0.0.1", username: "admin", password: "pass" } } };
+    saveConfig(data);
+    const loaded = loadConfig();
+    assert.strictEqual(loaded.activeCluster, "lab");
+    assert.strictEqual(loaded.clusters.lab.host, "10.0.0.1");
+  });
+
+  it("config file exists on disk after save", () => {
+    const configPath = path.join(tmpDir, "config.json");
+    assert.ok(fs.existsSync(configPath), "config.json should exist");
+  });
+
+  it("config file has restricted permissions (600)", () => {
+    const configPath = path.join(tmpDir, "config.json");
+    const stats = fs.statSync(configPath);
+    const mode = (stats.mode & 0o777).toString(8);
+    assert.strictEqual(mode, "600");
+  });
+});
+
+describe("addCluster", () => {
+  it("adds a cluster and sets it active if none active", () => {
+    saveConfig({ activeCluster: null, clusters: {} });
+    addCluster("prod", { host: "cucm.example.com", username: "admin", password: "secret" });
+    const config = loadConfig();
+    assert.strictEqual(config.activeCluster, "prod");
+    assert.strictEqual(config.clusters.prod.host, "cucm.example.com");
+  });
+
+  it("adds insecure flag when specified", () => {
+    addCluster("lab2", { host: "lab.local", username: "u", password: "p", insecure: true });
+    const config = loadConfig();
+    assert.strictEqual(config.clusters.lab2.insecure, true);
+  });
+
+  it("does not overwrite activeCluster if one already set", () => {
+    const config = loadConfig();
+    assert.strictEqual(config.activeCluster, "prod");
+  });
+});
+
+describe("useCluster", () => {
+  it("switches the active cluster", () => {
+    useCluster("lab2");
+    const config = loadConfig();
+    assert.strictEqual(config.activeCluster, "lab2");
+  });
+
+  it("throws for unknown cluster", () => {
+    assert.throws(() => useCluster("nonexistent"), /not found/);
+  });
+});
+
+describe("removeCluster", () => {
+  it("removes a cluster", () => {
+    removeCluster("lab2");
+    const config = loadConfig();
+    assert.strictEqual(config.clusters.lab2, undefined);
+  });
+
+  it("reassigns activeCluster when removing the active one", () => {
+    saveConfig({ activeCluster: "a", clusters: { a: { host: "h", username: "u", password: "p" }, b: { host: "h2", username: "u2", password: "p2" } } });
+    removeCluster("a");
+    const config = loadConfig();
+    assert.strictEqual(config.activeCluster, "b");
+  });
+
+  it("sets activeCluster to null when removing last cluster", () => {
+    removeCluster("b");
+    const config = loadConfig();
+    assert.strictEqual(config.activeCluster, null);
+  });
+
+  it("throws for unknown cluster", () => {
+    assert.throws(() => removeCluster("nonexistent"), /not found/);
+  });
+});
+
+describe("getActiveCluster", () => {
+  it("returns null when no clusters configured", () => {
+    saveConfig({ activeCluster: null, clusters: {} });
+    assert.strictEqual(getActiveCluster(), null);
+  });
+
+  it("returns the active cluster with name merged in", () => {
+    saveConfig({ activeCluster: "prod", clusters: { prod: { host: "h", username: "u", password: "p" } } });
+    const cluster = getActiveCluster();
+    assert.strictEqual(cluster.name, "prod");
+    assert.strictEqual(cluster.host, "h");
+  });
+
+  it("returns a specific cluster when name is provided", () => {
+    saveConfig({ activeCluster: "prod", clusters: { prod: { host: "h1", username: "u", password: "p" }, lab: { host: "h2", username: "u", password: "p" } } });
+    const cluster = getActiveCluster("lab");
+    assert.strictEqual(cluster.name, "lab");
+    assert.strictEqual(cluster.host, "h2");
+  });
+});
+
+describe("listClusters", () => {
+  it("returns activeCluster and clusters map", () => {
+    const result = listClusters();
+    assert.ok("activeCluster" in result);
+    assert.ok("clusters" in result);
+    assert.strictEqual(typeof result.clusters, "object");
+  });
+});
+
+describe("maskPassword", () => {
+  it("masks a plain password with asterisks", () => {
+    assert.strictEqual(maskPassword("secret"), "******");
+  });
+
+  it("returns empty string for falsy input", () => {
+    assert.strictEqual(maskPassword(""), "");
+    assert.strictEqual(maskPassword(null), "");
+    assert.strictEqual(maskPassword(undefined), "");
+  });
+
+  it("preserves ss-cli placeholders unmasked", () => {
+    const placeholder = "<ss:123:password>";
+    assert.strictEqual(maskPassword(placeholder), placeholder);
+  });
+});
+
+describe("hasSsPlaceholders", () => {
+  it("detects <ss:ID:field> patterns", () => {
+    assert.strictEqual(hasSsPlaceholders({ password: "<ss:123:password>" }), true);
+  });
+
+  it("returns false for plain strings", () => {
+    assert.strictEqual(hasSsPlaceholders({ password: "plaintext" }), false);
+  });
+
+  it("returns false for empty object", () => {
+    assert.strictEqual(hasSsPlaceholders({}), false);
+  });
+});
+
+// Cleanup
+fs.rmSync(tmpDir, { recursive: true, force: true });
+
+console.log(`\n  config.test.js: ${total} tests, ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);