@datasynx/agentic-ai-cartography 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Datasynx AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# @datasynx-ai/agentic-ai-cartography
+
+**AI-powered Infrastructure Cartography & SOP Generation**
+
+Cartography uses the **Claude Agent SDK** to automatically discover your infrastructure, map dependencies, and generate Standard Operating Procedures from observed workflows — all from your terminal.
+
+```
+$ cartography discover
+🔍 Scanning localhost...
+   ├── postgres:5432 (3 databases, 47 tables)
+   ├── redis:6379 (standalone, 12 keys)
+   ├── nginx:80 → upstream:3000 (express)
+   │   └── GET /api/users, POST /api/auth, ...
+   ├── rabbitmq:5672 (3 queues)
+   └── grafana:3000 → prometheus:9090
+✓ 8 nodes, 11 edges discovered
+✓ Exported: catalog.json, topology.mermaid, catalog-info.yaml
+
+$ cartography shadow start
+👁 Shadow daemon started (PID 48291)
+   Observing network + processes every 30s...
+
+$ cartography shadow stop
+✓ Shadow stopped. 142 events, 3 tasks, 2 workflows detected.
+✓ Generated: sops/deploy-check.md, sops/db-migration.md
+```
+
+Claude **is** the agent — it decides which read-only commands to run, analyses the output, and stores results via custom MCP tools into SQLite. No hand-written parsers, diff logic, or decision trees.
+
+---
+
+## Requirements
+
+- **Node.js ≥ 18**
+- **Claude CLI** (runtime dependency — the Agent SDK starts it as a child process)
+
+```bash
+npm install -g @anthropic-ai/claude-code
+claude login
+```
+
+---
+
+## Install
+
+```bash
+npm install -g @datasynx-ai/agentic-ai-cartography
+```
+
+---
+
+## Quick Start
+
+```bash
+# Discover your infrastructure (one-shot, Claude Sonnet)
+cartography discover
+
+# Start background observer (Claude Haiku, every 30s)
+cartography shadow start
+
+# Attach to see live events
+cartography shadow attach
+
+# After observing: generate SOPs from workflows
+cartography sops
+
+# Stop daemon
+cartography shadow stop
+
+# Full feature overview
+cartography docs
+```
+
+---
+
+## Commands
+
+### Discovery
+
+```
+cartography discover [options]
+
+  --entry <hosts...>    Start hosts          (default: localhost)
+  --depth <n>           Max crawl depth      (default: 8)
+  --max-turns <n>       Max agent turns      (default: 50)
+  --model <m>           Claude model         (default: claude-sonnet-4-5-...)
+  --org <name>          Org name for Backstage YAML
+  -o, --output <dir>    Output directory     (default: ./cartography-output)
+  -v, --verbose         Show agent reasoning
+```
+
+### Shadow Daemon
+
+```
+cartography shadow start [options]
+
+  --interval <ms>       Poll interval        (default: 30000, min: 15000)
+  --inactivity <ms>     Task boundary gap    (default: 300000)
+  --model <m>           Claude model         (default: claude-haiku-4-5-...)
+  --track-windows       Track window focus (requires xdotool)
+  --auto-save           Save nodes without prompting
+  --foreground          Run in foreground (no fork)
+
+cartography shadow stop
+cartography shadow status
+cartography shadow attach    # hotkeys: [T] new task  [S] status  [D] detach  [Q] stop
+```
+
+### Analysis & Export
+
+```
+cartography sops [session-id]              Generate SOPs from observed workflows
+cartography export [session-id] [options]  Export all formats
+  --format <fmt...>    mermaid, json, yaml, html, sops  (default: all)
+  -o, --output <dir>   Output directory
+cartography show [session-id]              Session details + node list
+cartography sessions                       List all sessions
+cartography docs                           Full feature reference
+```
+
+---
+
+## Output Files
+
+```
+cartography-output/
+├── catalog.json               Full machine-readable dump
+├── catalog-info.yaml          Backstage service catalog
+├── topology.mermaid           Infrastructure topology (graph TB)
+├── dependencies.mermaid       Service dependencies (graph LR)
+├── topology.html              Interactive D3.js force graph
+├── sops/
+│   ├── deploy-check.md
+│   └── db-migration.md
+└── workflows/
+    └── workflow-001.mermaid
+```
+
+---
+
+## Costs
+
+| Mode | Model | Interval | per Hour | per 8h Day |
+|------|-------|----------|----------|------------|
+| Discovery | Sonnet | one-shot | $0.15–0.50 | one-shot |
+| Shadow | Haiku | 30s | $0.12–0.36 | $0.96–2.88 |
+| Shadow | Haiku | 60s | $0.06–0.18 | $0.48–1.44 |
+| Shadow (quiet)* | Haiku | 30s | ~$0.02 | ~$0.16 |
+| SOP generation | Sonnet | one-shot | $0.01–0.03 | one-shot |
+
+\* *quiet = diff-check skips ~90% of cycles when the system is idle*
+
+---
+
+## Architecture
+
+```
+CLI (Commander)
+  └── Preflight: Claude CLI check + API key + interval validation
+      └── Agent Orchestrator
+          ├── runDiscovery()     Claude Sonnet + Bash + MCP Tools
+          ├── runShadowCycle()   Claude Haiku + MCP Tools only (no Bash!)
+          └── generateSOPs()     Anthropic Messages API (no agent loop)
+              └── Custom MCP Tools: save_node, save_edge, save_event,
+                                    get_catalog, manage_task, save_sop
+                  └── CartographyDB (SQLite WAL, ~/.cartography/cartography.db)
+
+Shadow Daemon
+  ├── takeSnapshot()  →  ss + ps  (no Claude!)
+  ├── Diff-check      →  only calls Claude when something changed
+  ├── IPC Server      →  Unix socket ~/.cartography/daemon.sock
+  └── Notifications   →  desktop alerts when no client attached
+```
+
+### Safety
+
+Every Bash call is guarded by a `PreToolUse` hook that blocks any destructive command:
+`rm`, `mv`, `dd`, `chmod`, `kill`, `docker rm/run/exec`, `kubectl delete/apply/exec`, redirects (`>`), and more.
+Claude only reads — never writes, never deletes.
+
+---
+
+## Public API
+
+```typescript
+import {
+  CartographyDB,
+  runDiscovery,
+  runShadowCycle,
+  generateSOPs,
+  exportAll,
+  safetyHook,
+  defaultConfig,
+} from '@datasynx-ai/agentic-ai-cartography';
+```
+
+---
+
+## License
+
+MIT — © Datasynx AI