cisco-axl 2.0.0 → 2.1.2

package/cli/commands/doctor.js

@@ -0,0 +1,134 @@
+"use strict";
+
+const { loadConfig, getConfigPath, getConfigDir } = require("../utils/config.js");
+const { resolveConfig } = require("../utils/connection.js");
+
+module.exports = function (program) {
+  program.command("doctor")
+    .description("Check AXL connectivity and configuration health")
+    .action(async (opts, command) => {
+      const globalOpts = command.optsWithGlobals();
+      let passed = 0;
+      let warned = 0;
+      let failed = 0;
+
+      const ok = (msg) => { console.log(`  ✓ ${msg}`); passed++; };
+      const warn = (msg) => { console.log(`  ⚠ ${msg}`); warned++; };
+      const fail = (msg) => { console.log(`  ✗ ${msg}`); failed++; };
+
+      console.log("\n  cisco-axl doctor");
+      console.log("  " + "─".repeat(50));
+
+      // 1. Configuration
+      console.log("\n  Configuration");
+      let conn;
+      try {
+        const data = loadConfig();
+        if (!data.activeCluster) {
+          fail("No active cluster configured");
+          console.log("    Run: cisco-axl config add <name> --host <host> --username <user> --password <pass> --cucm-version <ver>");
+          printSummary(passed, warned, failed);
+          return;
+        }
+        ok(`Active cluster: ${data.activeCluster}`);
+        const cluster = data.clusters[data.activeCluster];
+        ok(`Host: ${cluster.host}`);
+        ok(`Username: ${cluster.username}`);
+        ok(`CUCM version: ${cluster.version}`);
+
+        if (cluster.insecure) warn("TLS verification: disabled (--insecure)");
+        else ok("TLS verification: enabled");
+
+        conn = await resolveConfig(globalOpts);
+      } catch (err) {
+        fail(`Config error: ${err.message}`);
+        printSummary(passed, warned, failed);
+        return;
+      }
+
+      // 2. AXL API connectivity
+      console.log("\n  AXL API");
+      try {
+        if (conn.insecure) { process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0"; }
+        const axlService = require("../../dist/index.js");
+        const service = new axlService(conn.host, conn.username, conn.password, conn.version);
+
+        await service.testAuthentication();
+        ok(`AXL API: connected`);
+
+        // Try a simple SQL query to verify read access
+        try {
+          const sqlResult = await service.executeSqlQuery("SELECT COUNT(*) AS cnt FROM device");
+          const rows = Array.isArray(sqlResult) ? sqlResult : sqlResult?.row || [];
+          const count = rows[0]?.cnt || "?";
+          ok(`SQL query: ${count} device(s) in database`);
+        } catch {
+          warn("SQL query: could not query device table — may lack permissions");
+        }
+
+        // Check operation count
+        try {
+          const ops = await service.returnOperations();
+          const count = Array.isArray(ops) ? ops.length : 0;
+          ok(`AXL operations: ${count} available`);
+        } catch {
+          warn("Could not list AXL operations");
+        }
+      } catch (err) {
+        const msg = err.message || String(err);
+        if (msg.includes("401") || msg.includes("Authentication") || msg.includes("Unauthorized")) {
+          fail("AXL API: authentication failed — check username/password");
+        } else if (msg.includes("ECONNREFUSED")) {
+          fail("AXL API: connection refused — check host and port");
+        } else if (msg.includes("ENOTFOUND")) {
+          fail("AXL API: hostname not found — check host");
+        } else if (msg.includes("certificate")) {
+          fail("AXL API: TLS certificate error — try adding --insecure to the cluster config");
+        } else {
+          fail(`AXL API: ${msg}`);
+        }
+      }
+
+      // 3. Security
+      console.log("\n  Security");
+      try {
+        const fs = require("node:fs");
+        const configPath = getConfigPath();
+        const stats = fs.statSync(configPath);
+        const mode = (stats.mode & 0o777).toString(8);
+        if (mode === "600") ok(`Config file permissions: ${mode} (secure)`);
+        else warn(`Config file permissions: ${mode} — should be 600. Run: chmod 600 ${configPath}`);
+      } catch { /* config file may not exist yet */ }
+
+      // 4. Audit trail
+      try {
+        const fs = require("node:fs");
+        const path = require("node:path");
+        const auditPath = path.join(getConfigDir(), "audit.jsonl");
+        if (fs.existsSync(auditPath)) {
+          const stats = fs.statSync(auditPath);
+          const sizeMB = (stats.size / 1024 / 1024).toFixed(1);
+          ok(`Audit trail: ${sizeMB}MB`);
+          if (stats.size > 8 * 1024 * 1024) warn("Audit trail approaching 10MB rotation limit");
+        } else {
+          ok("Audit trail: empty (no operations logged yet)");
+        }
+      } catch { /* ignore */ }
+
+      printSummary(passed, warned, failed);
+    });
+
+  function printSummary(passed, warned, failed) {
+    console.log("\n  " + "─".repeat(50));
+    console.log(`  Results: ${passed} passed, ${warned} warning${warned !== 1 ? "s" : ""}, ${failed} failed`);
+    if (failed > 0) {
+      process.exitCode = 1;
+      console.log("  Status:  issues found — review failures above");
+    } else if (warned > 0) {
+      console.log("  Status:  healthy with warnings");
+    } else {
+      console.log("  Status:  all systems healthy");
+    }
+    console.log("");
+  }
+};

package/cli/commands/execute.js

@@ -10,6 +10,7 @@
 const { createService } = require("../utils/connection.js");
 const { printResult, printError } = require("../utils/output.js");
 const { enforceReadOnly } = require("../utils/readonly.js");
+const { readStdin } = require("../utils/stdin.js");
 
 /**
  * Registers the execute command on the given Commander program.
@@ -20,6 +21,7 @@ module.exports = function registerExecuteCommand(program) {
     .command("execute <operation>")
     .description("Execute a raw AXL operation with JSON tags")
     .option("--tags <json>", "JSON object of operation tags")
+    .option("--stdin", "read JSON tags from stdin (for piping)")
     .option("--template <file>", "JSON template file with %%var%% placeholders")
     .option("--vars <json>", "variables to resolve in template (JSON)")
     .option("--csv <file>", "CSV file for bulk operations (use with --template)")
@@ -32,14 +34,22 @@ module.exports = function registerExecuteCommand(program) {
       let errorMsg;
 
       try {
-        enforceReadOnly(globalOpts, "execute");
+        await enforceReadOnly(globalOpts, "execute");
+
+        // Read from stdin if --stdin flag is set
+        if (cmdOpts.stdin) {
+          const stdinData = await readStdin();
+          if (!stdinData) throw new Error("--stdin specified but no data piped. Pipe JSON via: echo '{...}' | cisco-axl execute <op> --stdin");
+          cmdOpts.tags = stdinData.trim();
+        }
 
         // Validate mutual exclusivity
-        if (cmdOpts.tags && cmdOpts.template) {
-          throw new Error("--tags and --template are mutually exclusive");
+        const inputCount = [cmdOpts.tags, cmdOpts.template].filter(Boolean).length;
+        if (inputCount > 1) {
+          throw new Error("--tags, --stdin, and --template are mutually exclusive");
         }
-        if (!cmdOpts.tags && !cmdOpts.template) {
-          throw new Error("Either --tags or --template must be provided");
+        if (inputCount === 0) {
+          throw new Error("Provide input via --tags, --stdin, or --template");
         }
 
         const opts = {

package/cli/commands/remove.js

@@ -24,7 +24,7 @@ module.exports = function registerRemoveCommand(program) {
       let errorMsg;
 
       try {
-        enforceReadOnly(globalOpts, "remove");
+        await enforceReadOnly(globalOpts, "remove");
 
         const service = await createService(globalOpts);
         const opts = {

package/cli/commands/sql.js

@@ -75,7 +75,7 @@ module.exports = function registerSqlCommand(program) {
       let errorMsg;
 
       try {
-        enforceReadOnly(globalOpts, "sql update");
+        await enforceReadOnly(globalOpts, "sql update");
 
         const service = await createService(globalOpts);
         const opts = {

package/cli/commands/update.js

@@ -10,6 +10,7 @@
 const { createService } = require("../utils/connection.js");
 const { printResult, printError } = require("../utils/output.js");
 const { enforceReadOnly } = require("../utils/readonly.js");
+const { readStdin } = require("../utils/stdin.js");
 
 /**
  * Registers the update command on the given Commander program.
@@ -20,6 +21,7 @@ module.exports = function registerUpdateCommand(program) {
     .command("update <type> [identifier]")
     .description("Update an existing AXL item by type and name or UUID")
     .option("--data <json>", "JSON object of fields to update")
+    .option("--stdin", "read JSON data from stdin (for piping)")
     .option("--template <file>", "JSON template file with %%var%% placeholders")
     .option("--vars <json>", "variables to resolve in template (JSON)")
     .option("--csv <file>", "CSV file for bulk operations (use with --template)")
@@ -32,14 +34,22 @@ module.exports = function registerUpdateCommand(program) {
       let errorMsg;
 
       try {
-        enforceReadOnly(globalOpts, "update");
+        await enforceReadOnly(globalOpts, "update");
+
+        // Read from stdin if --stdin flag is set
+        if (cmdOpts.stdin) {
+          const stdinData = await readStdin();
+          if (!stdinData) throw new Error("--stdin specified but no data piped. Pipe JSON via: echo '{...}' | cisco-axl update <type> <id> --stdin");
+          cmdOpts.data = stdinData.trim();
+        }
 
         // Validate mutual exclusivity
-        if (cmdOpts.data && cmdOpts.template) {
-          throw new Error("--data and --template are mutually exclusive");
+        const inputCount = [cmdOpts.data, cmdOpts.template].filter(Boolean).length;
+        if (inputCount > 1) {
+          throw new Error("--data, --stdin, and --template are mutually exclusive");
         }
-        if (!cmdOpts.data && !cmdOpts.template) {
-          throw new Error("Either --data or --template must be provided");
+        if (inputCount === 0) {
+          throw new Error("Provide input via --data, --stdin, or --template");
         }
 
         const opts = {

package/cli/index.js

@@ -1,14 +1,26 @@
 "use strict";
 
 const { Command } = require("commander");
-const { version } = require("../package.json");
+const pkg = require("../package.json");
+
+// Suppress Node.js TLS warning when --insecure is used
+const originalEmitWarning = process.emitWarning;
+process.emitWarning = (warning, ...args) => {
+  if (typeof warning === "string" && warning.includes("NODE_TLS_REJECT_UNAUTHORIZED")) return;
+  originalEmitWarning.call(process, warning, ...args);
+};
+
+try {
+  const updateNotifier = require("update-notifier").default || require("update-notifier");
+  updateNotifier({ pkg }).notify();
+} catch {};
 
 const program = new Command();
 
 program
   .name("cisco-axl")
   .description("CLI for Cisco CUCM AXL operations")
-  .version(version)
+  .version(pkg.version)
   .option("--format <type>", "output format: table, json, toon, csv", "table")
   .option("--host <host>", "CUCM hostname (overrides config/env)")
   .option("--username <user>", "CUCM username (overrides config/env)")
@@ -33,6 +45,7 @@ require("./commands/sql.js")(program);
 require("./commands/execute.js")(program);
 require("./commands/operations.js")(program);
 require("./commands/describe.js")(program);
+require("./commands/doctor.js")(program);
 // require("./commands/phone.js")(program);
 // require("./commands/line.js")(program);
 // require("./commands/user.js")(program);

package/cli/utils/config.js

@@ -263,15 +263,30 @@ function resolveSsValue(id, field) {
 
       try {
         const data = JSON.parse(stdout);
-        // ss-cli returns an object; find the field case-insensitively
         const fieldLower = field.toLowerCase();
+
+        // First: check top-level keys (simple key-value secrets)
         const foundKey = Object.keys(data).find(
           (k) => k.toLowerCase() === fieldLower
         );
-        if (foundKey === undefined) {
-          return reject(new Error(`Field "${field}" not found in ss-cli response for secret ${id}`));
+        if (foundKey !== undefined) {
+          return resolve(data[foundKey]);
         }
-        resolve(data[foundKey]);
+
+        // Second: check items array (Secret Server template secrets)
+        // Items have fieldName, slug, and itemValue properties
+        if (Array.isArray(data.items)) {
+          const item = data.items.find(
+            (i) =>
+              (i.slug && i.slug.toLowerCase() === fieldLower) ||
+              (i.fieldName && i.fieldName.toLowerCase() === fieldLower)
+          );
+          if (item) {
+            return resolve(item.itemValue);
+          }
+        }
+
+        return reject(new Error(`Field "${field}" not found in secret ${id}`));
       } catch (parseErr) {
         reject(new Error(`Failed to parse ss-cli output for secret ${id}: ${parseErr.message}`));
       }

package/cli/utils/confirm.js

@@ -0,0 +1,34 @@
+const readline = require("readline");
+const { getRandomWord } = require("./wordlist.js");
+
+function checkWriteAllowed(clusterConfig, globalOpts = {}) {
+  const readOnly = clusterConfig?.readOnly || globalOpts.readOnly;
+  if (!readOnly) return Promise.resolve(true);
+
+  if (!process.stdin.isTTY) {
+    throw new Error(
+      "This cluster is configured as read-only. " +
+      "Interactive TTY required for write confirmation. " +
+      "Change config with: cisco-axl config update <name> --no-read-only"
+    );
+  }
+
+  const word = getRandomWord();
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+
+  return new Promise((resolve, reject) => {
+    rl.question(
+      `\n⚠ This cluster is configured as read-only.\nTo proceed, type "${word}" to confirm: `,
+      (answer) => {
+        rl.close();
+        if (answer.trim().toLowerCase() === word.toLowerCase()) {
+          resolve({ confirmed: true, word });
+        } else {
+          reject(new Error("Confirmation failed. Write operation cancelled."));
+        }
+      }
+    );
+  });
+}
+
+module.exports = { checkWriteAllowed };

package/cli/utils/connection.js

@@ -119,9 +119,13 @@ async function resolveConfig(flags = {}) {
 async function createService(flags = {}) {
   const config = await resolveConfig(flags);
 
-  // Handle --insecure flag
+  // Handle --insecure flag — suppress Node's TLS warning since user opted in
   if (config.insecure || flags.insecure) {
     process.env.NODE_TLS_REJECT_UNAUTHORIZED = "0";
+    process.emitWarning = ((orig) => function (warning, ...args) {
+      if (typeof warning === "string" && warning.includes("NODE_TLS_REJECT_UNAUTHORIZED")) return;
+      return orig.call(process, warning, ...args);
+    })(process.emitWarning);
   }
 
   // Build axlService options

package/cli/utils/readonly.js

@@ -1,31 +1,26 @@
 "use strict";
 
+const { checkWriteAllowed } = require("./confirm.js");
+
 /**
  * Check if read-only mode is active (via --read-only flag or cluster config).
- * Throws an error if a write operation is attempted in read-only mode.
+ * If read-only, requires interactive TTY confirmation with a random word.
+ * Non-interactive sessions (AI agents without TTY) fail automatically.
  *
  * @param {object} globalOpts - Commander global options
  * @param {string} operation - The operation being attempted (for error message)
  */
-function enforceReadOnly(globalOpts, operation) {
-  if (globalOpts.readOnly) {
-    throw new Error(
-      `Operation "${operation}" blocked — read-only mode is active.\n` +
-      "Read-only mode only allows: get, list, describe, operations, sql query.\n" +
-      "Remove --read-only flag to perform write operations."
-    );
-  }
-
-  // Also check cluster config for readOnly setting
+async function enforceReadOnly(globalOpts, operation) {
   const { getActiveCluster } = require("./config.js");
   const cluster = getActiveCluster(globalOpts.cluster);
-  if (cluster && cluster.readOnly) {
-    throw new Error(
-      `Operation "${operation}" blocked — cluster "${cluster.name}" is configured as read-only.\n` +
-      "Update the cluster config to allow write operations:\n" +
-      `  cisco-axl config add ${cluster.name} ... (without read-only)`
-    );
-  }
+  const clusterConfig = cluster || {};
+
+  // Build a combined config for checkWriteAllowed
+  const config = {
+    readOnly: globalOpts.readOnly || clusterConfig.readOnly || false,
+  };
+
+  await checkWriteAllowed(config, globalOpts);
 }
 
 module.exports = { enforceReadOnly };

package/cli/utils/stdin.js

@@ -0,0 +1,20 @@
+"use strict";
+
+/**
+ * Read all data from stdin as a string.
+ * Returns null if stdin is a TTY (no piped input).
+ */
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    if (process.stdin.isTTY) {
+      return resolve(null);
+    }
+    const chunks = [];
+    process.stdin.setEncoding("utf-8");
+    process.stdin.on("data", (chunk) => chunks.push(chunk));
+    process.stdin.on("end", () => resolve(chunks.join("")));
+    process.stdin.on("error", reject);
+  });
+}
+
+module.exports = { readStdin };

package/cli/utils/wordlist.js

@@ -0,0 +1,9 @@
+const crypto = require("crypto");
+
+function getRandomWord() {
+  // Generate a random 8-char string that doesn't exist in the codebase
+  // Not guessable, not brute-forceable from a known word list
+  return crypto.randomBytes(4).toString("hex");
+}
+
+module.exports = { getRandomWord };

package/docs/api.md

@@ -0,0 +1,191 @@
+# Library API Reference
+
+## Setup
+
+```javascript
+const axlService = require("cisco-axl");
+
+let service = new axlService("10.10.20.1", "administrator", "ciscopsdt", "14.0");
+
+// With options
+let service = new axlService("10.10.20.1", "administrator", "ciscopsdt", "14.0", {
+  logging: { level: "info" },
+  retry: { retries: 3, retryDelay: 1000 }
+});
+```
+
+## ESM / TypeScript
+
+```javascript
+// CommonJS
+const axlService = require("cisco-axl");
+
+// ESM
+import axlService from "cisco-axl";
+import { AXLAuthError, AXLOperationError } from "cisco-axl";
+```
+
+```typescript
+import axlService from 'cisco-axl';
+
+const service = new axlService("10.10.20.1", "administrator", "ciscopsdt", "14.0");
+
+const tags = await service.getOperationTags("listRoutePartition");
+tags.searchCriteria.name = "%%";
+const result = await service.executeOperation("listRoutePartition", tags);
+```
+
+See the `examples/typescript` directory for more examples.
+
+## Logging
+
+```javascript
+// Via environment variable
+// DEBUG=true
+
+// Via constructor
+let service = new axlService("10.10.20.1", "administrator", "ciscopsdt", "14.0", {
+  logging: {
+    level: "info",  // "error" | "warn" | "info" | "debug"
+    handler: (level, message, data) => {
+      myLogger[level](message, data);
+    }
+  }
+});
+
+// Change at runtime
+service.setLogLevel("debug");
+```
+
+## Convenience Methods
+
+```javascript
+// Get a single item by name or UUID
+await service.getItem("Phone", "SEP001122334455");
+await service.getItem("Phone", { uuid: "abc-123" });
+
+// List items with search criteria and returned tags
+await service.listItems("RoutePartition");  // all partitions
+await service.listItems("Phone", { name: "SEP%" }, { name: "", model: "" });
+
+// Add, update, remove
+await service.addItem("RoutePartition", { name: "NEW-PT", description: "New" });
+await service.updateItem("Phone", "SEP001122334455", { description: "Updated" });
+await service.removeItem("RoutePartition", "NEW-PT");
+
+// SQL
+const rows = await service.executeSqlQuery("SELECT name FROM routepartition");
+await service.executeSqlUpdate("UPDATE routepartition SET description='test' WHERE name='NEW-PT'");
+```
+
+## Operation Discovery
+
+```javascript
+// List all operations
+const ops = await service.returnOperations();
+const phoneOps = await service.returnOperations("phone");
+
+// Get tag schema
+const tags = await service.getOperationTags("addRoutePartition");
+
+// Get detailed metadata (required, nillable, type)
+const detailed = await service.getOperationTagsDetailed("addRoutePartition");
+console.log(detailed.routePartition.required);  // true
+console.log(detailed.routePartition.children.name.type);  // "string"
+```
+
+## Execute Any Operation
+
+```javascript
+const tags = await service.getOperationTags("addRoutePartition");
+tags.routePartition.name = "INTERNAL-PT";
+tags.routePartition.description = "Internal directory numbers";
+
+const result = await service.executeOperation("addRoutePartition", tags);
+console.log("UUID:", result);
+```
+
+## Batch Operations
+
+```javascript
+const results = await service.executeBatch([
+  { operation: "getPhone", tags: { name: "SEP001122334455" } },
+  { operation: "getPhone", tags: { name: "SEP556677889900" } },
+], 5); // concurrency limit
+
+results.forEach((r) => {
+  console.log(r.success ? `${r.operation}: OK` : `${r.operation}: ${r.error.message}`);
+});
+```
+
+## Error Handling
+
+```javascript
+const { AXLAuthError, AXLNotFoundError, AXLOperationError, AXLValidationError } = require("cisco-axl");
+
+try {
+  await service.executeOperation("getPhone", { name: "INVALID" });
+} catch (error) {
+  if (error instanceof AXLAuthError) console.log("Bad credentials");
+  else if (error instanceof AXLNotFoundError) console.log("Operation not found:", error.operation);
+  else if (error instanceof AXLOperationError) console.log("SOAP fault:", error.message);
+  else if (error instanceof AXLValidationError) console.log("Invalid input:", error.message);
+}
+```
+
+## Retry Configuration
+
+```javascript
+let service = new axlService("10.10.20.1", "admin", "pass", "14.0", {
+  retry: {
+    retries: 3,
+    retryDelay: 1000,
+    retryOn: (error) => error.message.includes("ECONNRESET")
+  }
+});
+```
+
+## json-variables Support
+
+```javascript
+var lineTemplate = {
+  pattern: "%%_extension_%%",
+  alertingName: "%%_firstName_%% %%_lastName_%%",
+  description: "%%_firstName_%% %%_lastName_%%",
+  _data: {
+    extension: "1001",
+    firstName: "Tom",
+    lastName: "Smith",
+  },
+};
+
+const lineTags = jVar(lineTemplate);
+await service.executeOperation("updateLine", lineTags);
+```
+
+## Methods Reference
+
+### Core
+
+| Method | Description |
+|--------|-------------|
+| `new axlService(host, user, pass, version, opts?)` | Constructor |
+| `testAuthentication()` | Test credentials against AXL endpoint |
+| `returnOperations(filter?)` | List available operations |
+| `getOperationTags(operation)` | Get tag schema for an operation |
+| `getOperationTagsDetailed(operation)` | Get detailed tag metadata (required/nillable/type) |
+| `executeOperation(operation, tags, opts?)` | Execute any AXL operation |
+| `executeBatch(operations[], concurrency?)` | Parallel batch execution |
+| `setLogLevel(level)` | Change log level at runtime |
+
+### Convenience
+
+| Method | Description |
+|--------|-------------|
+| `getItem(type, identifier, opts?)` | Get single item by name or UUID |
+| `listItems(type, search?, returnedTags?, opts?)` | List items with filtering |
+| `addItem(type, data, opts?)` | Add a new item |
+| `updateItem(type, identifier, updates, opts?)` | Update an existing item |
+| `removeItem(type, identifier, opts?)` | Remove an item |
+| `executeSqlQuery(sql)` | Run a SQL SELECT query |
+| `executeSqlUpdate(sql)` | Run a SQL INSERT/UPDATE/DELETE |