nowaikit 4.0.5 → 4.1.0

package/dist/utils/audit.js

@@ -0,0 +1,48 @@
+/**
+ * Append-only audit log for mutating operations.
+ *
+ * Writes one JSON object per line to NOWAIKIT_AUDIT_LOG (default
+ * ~/.config/nowaikit/audit.jsonl). Records who/what/when without storing full
+ * payloads — field VALUES are hashed, only field NAMES are kept in the clear —
+ * so the log is safe to retain for compliance/MSP use.
+ *
+ * Set NOWAIKIT_AUDIT_DISABLED=true to turn it off.
+ */
+import { appendFile, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { logger } from './logging.js';
+function auditPath() {
+    return process.env.NOWAIKIT_AUDIT_LOG || join(homedir(), '.config', 'nowaikit', 'audit.jsonl');
+}
+function hashPayload(fields) {
+    if (!fields)
+        return undefined;
+    try {
+        return createHash('sha256').update(JSON.stringify(fields)).digest('hex').slice(0, 16);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Append an audit entry. Best-effort — never throws into the caller. */
+export async function appendAudit(entry, fields) {
+    if (process.env.NOWAIKIT_AUDIT_DISABLED === 'true')
+        return;
+    const line = JSON.stringify({
+        ts: new Date().toISOString(),
+        ...entry,
+        field_names: entry.field_names ?? (fields ? Object.keys(fields) : undefined),
+        payload_hash: entry.payload_hash ?? hashPayload(fields),
+    }) + '\n';
+    try {
+        const path = auditPath();
+        await mkdir(dirname(path), { recursive: true });
+        await appendFile(path, line, 'utf8');
+    }
+    catch (err) {
+        logger.warn(`Audit log write failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+//# sourceMappingURL=audit.js.map

package/dist/utils/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/utils/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAetC,SAAS,SAAS;IAChB,OAAO,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC;AACjG,CAAC;AAED,SAAS,WAAW,CAAC,MAAgC;IACnD,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,IAAI,CAAC;QACH,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACxF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,yEAAyE;AACzE,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,KAAiB,EAAE,MAAgC;IACnF,IAAI,OAAO,CAAC,GAAG,CAAC,uBAAuB,KAAK,MAAM;QAAE,OAAO;IAC3D,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;QAC1B,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC5B,GAAG,KAAK;QACR,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC5E,YAAY,EAAE,KAAK,CAAC,YAAY,IAAI,WAAW,CAAC,MAAM,CAAC;KACxD,CAAC,GAAG,IAAI,CAAC;IACV,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,SAAS,EAAE,CAAC;QACzB,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,MAAM,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,IAAI,CAAC,2BAA2B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC7F,CAAC;AACH,CAAC"}

package/dist/utils/guardrails.d.ts

@@ -0,0 +1,5 @@
+/** Throw if writes to `table` (optionally touching `fields`) are blocked by guardrails. */
+export declare function assertWriteAllowed(table: string, fields?: Record<string, unknown>): void;
+/** Whether a table is on the delete denylist (delete is treated as a write to the table). */
+export declare function assertDeleteAllowed(table: string): void;
+//# sourceMappingURL=guardrails.d.ts.map

package/dist/utils/guardrails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrails.d.ts","sourceRoot":"","sources":["../../src/utils/guardrails.ts"],"names":[],"mappings":"AA2BA,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CA+BxF;AAED,6FAA6F;AAC7F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEvD"}

package/dist/utils/guardrails.js

@@ -0,0 +1,50 @@
+import { ServiceNowError } from './errors.js';
+/**
+ * Write guardrails — defense-in-depth beyond the binary WRITE_ENABLED flag.
+ *
+ * Config (all optional, comma-separated):
+ *   NOWAIKIT_TABLE_DENYLIST   — tables that may never be written (e.g. sys_user,sys_properties)
+ *   NOWAIKIT_FIELD_DENYLIST   — fields that may never be written; "table.field" or bare "field"
+ *   NOWAIKIT_WRITE_SCOPE_PREFIX — if set, only tables matching one of these prefixes may be written
+ *                                 (e.g. "x_" to confine agents to scoped-app tables)
+ *
+ * Built-in always-denied fields protect credentials/security regardless of config.
+ */
+const BUILTIN_FIELD_DENYLIST = new Set([
+    'sys_user.user_password',
+    'sys_user.password',
+    'user_password',
+    'password',
+]);
+function parseList(envVar) {
+    const raw = process.env[envVar];
+    if (!raw)
+        return [];
+    return raw.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean);
+}
+/** Throw if writes to `table` (optionally touching `fields`) are blocked by guardrails. */
+export function assertWriteAllowed(table, fields) {
+    const t = table.toLowerCase();
+    const tableDenylist = parseList('NOWAIKIT_TABLE_DENYLIST');
+    if (tableDenylist.includes(t)) {
+        throw new ServiceNowError(`Writes to "${table}" are blocked by NOWAIKIT_TABLE_DENYLIST.`, 'WRITE_GUARDRAIL');
+    }
+    const scopePrefixes = parseList('NOWAIKIT_WRITE_SCOPE_PREFIX');
+    if (scopePrefixes.length > 0 && !scopePrefixes.some((p) => t.startsWith(p))) {
+        throw new ServiceNowError(`Writes to "${table}" are blocked: not within an allowed scope prefix (${scopePrefixes.join(', ')}).`, 'WRITE_GUARDRAIL');
+    }
+    if (fields) {
+        const fieldDenylist = new Set([...BUILTIN_FIELD_DENYLIST, ...parseList('NOWAIKIT_FIELD_DENYLIST')]);
+        for (const field of Object.keys(fields)) {
+            const f = field.toLowerCase();
+            if (fieldDenylist.has(f) || fieldDenylist.has(`${t}.${f}`)) {
+                throw new ServiceNowError(`Writing field "${field}" on "${table}" is blocked by the field denylist.`, 'WRITE_GUARDRAIL');
+            }
+        }
+    }
+}
+/** Whether a table is on the delete denylist (delete is treated as a write to the table). */
+export function assertDeleteAllowed(table) {
+    assertWriteAllowed(table);
+}
+//# sourceMappingURL=guardrails.js.map

package/dist/utils/guardrails.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrails.js","sourceRoot":"","sources":["../../src/utils/guardrails.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;GAUG;AAEH,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAAS;IAC7C,wBAAwB;IACxB,mBAAmB;IACnB,eAAe;IACf,UAAU;CACX,CAAC,CAAC;AAEH,SAAS,SAAS,CAAC,MAAc;IAC/B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IACpB,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AAC3E,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,kBAAkB,CAAC,KAAa,EAAE,MAAgC;IAChF,MAAM,CAAC,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAE9B,MAAM,aAAa,GAAG,SAAS,CAAC,yBAAyB,CAAC,CAAC;IAC3D,IAAI,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,eAAe,CACvB,cAAc,KAAK,2CAA2C,EAC9D,iBAAiB,CAClB,CAAC;IACJ,CAAC;IAED,MAAM,aAAa,GAAG,SAAS,CAAC,6BAA6B,CAAC,CAAC;IAC/D,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,MAAM,IAAI,eAAe,CACvB,cAAc,KAAK,sDAAsD,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EACrG,iBAAiB,CAClB,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,sBAAsB,EAAE,GAAG,SAAS,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC;QACpG,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACxC,MAAM,CAAC,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;YAC9B,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;gBAC3D,MAAM,IAAI,eAAe,CACvB,kBAAkB,KAAK,SAAS,KAAK,qCAAqC,EAC1E,iBAAiB,CAClB,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,kBAAkB,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC"}

package/dist/utils/version.d.ts

@@ -0,0 +1,3 @@
+export declare const SERVER_NAME = "nowaikit";
+export declare const VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/utils/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/utils/version.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,WAAW,aAAa,CAAC;AAetC,eAAO,MAAM,OAAO,QAAgB,CAAC"}

package/dist/utils/version.js

@@ -0,0 +1,25 @@
+/**
+ * Single source of truth for the package version.
+ * Reads version from package.json at runtime so server.ts, transport,
+ * a2a agent card, and dashboard never drift from package.json again.
+ */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+export const SERVER_NAME = 'nowaikit';
+function readVersion() {
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        // dist/utils/version.js -> ../../package.json  (project root)
+        const pkgPath = resolve(here, '..', '..', 'package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        if (pkg.version)
+            return pkg.version;
+    }
+    catch {
+        // fall through to default
+    }
+    return '0.0.0';
+}
+export const VERSION = readVersion();
+//# sourceMappingURL=version.js.map

package/dist/utils/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/utils/version.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE7C,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC;AAEtC,SAAS,WAAW;IAClB,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QACrD,8DAA8D;QAC9D,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;QAC1D,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAyB,CAAC;QAC9E,IAAI,GAAG,CAAC,OAAO;YAAE,OAAO,GAAG,CAAC,OAAO,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,0BAA0B;IAC5B,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,MAAM,OAAO,GAAG,WAAW,EAAE,CAAC"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "nowaikit",
   "mcpName": "io.github.aartiq/nowaikit",
-  "version": "4.0.5",
-  "description": "The Most Comprehensive ServiceNow AI Toolkit — 400+ MCP tools + 26 AI capabilities (scan, review, build, ops, docs) + direct BYOK mode. Integrates with Claude, ChatGPT, Gemini, Cursor, GitHub Copilot and any LLM.",
+  "version": "4.1.0",
+  "description": "The Most Comprehensive ServiceNow AI Toolkit \u2014 400+ MCP tools + 26 AI capabilities (scan, review, build, ops, docs) + direct BYOK mode. Integrates with Claude, ChatGPT, Gemini, Cursor, GitHub Copilot and any LLM.",
   "main": "dist/server.js",
   "types": "dist/server.d.ts",
   "exports": {
@@ -31,6 +31,7 @@
     "dist/",
     "desktop/serve.cjs",
     "desktop/renderer/dist/",
+    "skills/",
     "instances.example.json",
     ".env.example"
   ],

package/skills/README.md

@@ -0,0 +1,21 @@
+# NowAIKit Agent Skills
+
+Cross-platform [Agent Skills](https://www.anthropic.com/news/skills) that orchestrate the NowAIKit MCP tools for common ServiceNow workflows. Each skill is a folder with a `SKILL.md` (YAML frontmatter `name` + `description` for progressive disclosure, then concise instructions).
+
+They work with any agent runtime that supports the Agent Skills format — **Claude Code, Cursor, OpenAI Codex, GitHub Copilot, Windsurf** — alongside the NowAIKit MCP server.
+
+## Skills
+
+| Skill | Use it when |
+|-------|-------------|
+| `servicenow-incident-triage` | Triage/investigate/prioritize an incident or a queue |
+| `servicenow-cmdb-health-audit` | Check CMDB health, data quality, CSDM conformance, or clean up CIs |
+| `servicenow-safe-deployment` | Build and promote artifacts across instances with update sets + ATF |
+
+## Install
+
+**Claude Code:** copy a skill folder into `~/.claude/skills/` (global) or `.claude/skills/` (project), or point your skills path at this directory.
+
+**Cursor / Codex / others:** add this folder to the agent's skills/rules path per that tool's docs.
+
+All three skills assume the NowAIKit MCP server is connected. They lean on the safety features built into NowAIKit: `dry_run` previews, the write audit log, and write guardrails. Skills never apply destructive changes without showing a dry-run diff first.

package/skills/servicenow-cmdb-health-audit/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: servicenow-cmdb-health-audit
+description: Audit ServiceNow CMDB health using NowAIKit MCP tools — find duplicate, orphaned, and stale CIs, score completeness, and propose remediation. Use when the user asks to check CMDB health, data quality, CSDM conformance, or clean up the CMDB.
+---
+
+# ServiceNow CMDB Health Audit
+
+Use the NowAIKit CMDB tools to assess and remediate. Discover exact tool names with `search_tools` (e.g. "cmdb health", "find duplicates").
+
+## Workflow
+
+1. **Snapshot.** Run `cmdb_health_dashboard` for the overall score and class breakdown.
+2. **Find issues in parallel:** `cmdb_find_duplicates`, `cmdb_find_orphans`, `cmdb_find_stale`, and `analyze_data_quality` / `check_table_completeness` for key classes (cmdb_ci_server, cmdb_ci_appl, business apps).
+3. **Assess impact** before any change with `cmdb_impact_analysis` on candidate CIs.
+4. **CSDM lens.** Check that Application Services, Business Applications, and Service Offerings exist and are related per CSDM 4.0; flag gaps.
+5. **Remediate safely.** For merges/retirements/updates, call write tools with **`dry_run: true` first**, present the diff, then apply. Prefer `cmdb_reconcile` for authoritative-source conflicts.
+6. **Report.** Counts by issue type, the health score delta you expect, and a prioritized remediation list (highest blast-radius first).
+
+## Rules
+- Never merge or retire a CI without showing impact analysis + dry-run diff.
+- CMDB writes require `WRITE_ENABLED=true` and `CMDB_WRITE_ENABLED=true`.
+- CI relationships must have both parent and child defined (CSDM).
+- All writes are captured in the NowAIKit audit log.

package/skills/servicenow-incident-triage/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: servicenow-incident-triage
+description: Triage a ServiceNow incident or a queue of incidents using NowAIKit MCP tools — gather context, find similar past incidents, suggest a resolution, set priority, and assign. Use when the user asks to triage, investigate, prioritize, or work an incident (by number or as a batch).
+---
+
+# ServiceNow Incident Triage
+
+Drive triage through the NowAIKit MCP tools. Discover tools with `search_tools` if a name is unknown.
+
+## Workflow
+
+1. **Scope.** If given an incident number, fetch it (`get_incident`). For a queue, `query_records` on `incident` with an encoded query (validate it first with `validate_query`), e.g. `active=true^assignment_group=<grp>^priority<=2`.
+2. **Context.** Pull the caller, CI, and recent activity. For grounding, use `generate_summary` and `ml_similar_incidents` (or `ai_search`) to find prior resolutions.
+3. **Classify.** Use `categorize_incident` / `ml_auto_categorize` to confirm category and `suggest_resolution` for a candidate fix.
+4. **Act safely.** Propose field changes (priority, assignment_group, work notes) and apply with `update_record`. **Always run with `dry_run: true` first** and show the before→after diff before applying for real. Add context with `add_work_note`.
+5. **Summarize.** Report what changed, the suggested resolution, and links to the similar incidents you used.
+
+## Rules
+- Never set priority/assignment without showing the dry-run diff first.
+- Requires `WRITE_ENABLED=true` for any update; if disabled, output the proposed changes instead of applying.
+- Encoded queries use `^` (AND) and `^OR` (OR), never SQL `AND`/`OR`. Validate with `validate_query`.
+- Writes are recorded in the NowAIKit audit log automatically.

package/skills/servicenow-safe-deployment/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: servicenow-safe-deployment
+description: Safely build and deploy ServiceNow artifacts (business rules, scripts, flows, catalog items) across instances using NowAIKit MCP tools, with update sets, dry-run previews, and ATF verification. Use when the user asks to deploy, promote, build, or move changes between dev/test/prod.
+---
+
+# ServiceNow Safe Deployment
+
+Orchestrate build → verify → promote through NowAIKit MCP tools. Use `search_tools` to find exact names (e.g. "update set", "run atf", "create business rule").
+
+## Workflow
+
+1. **Capture scope.** Ensure an active update set: `ensure_active_update_set` (or create one). Confirm the target instance with `get_current_instance` — never assume prod.
+2. **Build.** Create artifacts (`create_business_rule`, `create_script_include`, `create_flow`, `create_catalog_item`, …). For raw table writes, preview with `dry_run: true` and show the payload/diff before applying.
+3. **Verify.** Run ATF: `run_atf_suite` / `run_atf_test` and read results (`get_atf_suite_result`, `get_atf_failure_insight`). Do not promote on failures.
+4. **Review the set.** `preview_update_set` and list changes; check for collisions.
+5. **Promote.** Move to the next environment with `switch_instance`, then `commit_update_set` / deployment tools. **Confirm explicitly before any prod commit.**
+6. **Report.** Artifacts created, ATF pass/fail, update set name, and the promotion path taken.
+
+## Rules
+- Scripting writes require `WRITE_ENABLED=true` + `SCRIPTING_ENABLED=true`; ATF needs `ATF_ENABLED=true`.
+- Always dry-run writes and run ATF before promoting.
+- Treat any instance that is not an explicit dev/test as production — stop and confirm.
+- New development goes in scoped apps (`x_vendor_app`), never global.
+- All writes are captured in the NowAIKit audit log.