@datasynx/agentic-ai-cartography

Datasynx Cartography

AI-powered Infrastructure Discovery & Agentic AI Cartography

A Model Context Protocol server that gives any AI agent read-only awareness of your complete system landscape — local services, databases, SaaS tools, installed apps and their dependencies — with progressive disclosure, recursive dependency traversal and semantic search. Discovery runs deterministically (no LLM required) or via an optional Claude-driven loop. Provider-agnostic: works with Claude, OpenAI, Ollama, or any MCP-compatible host.

📖 Documentation · 📦 npm · 💼 LinkedIn · 🐛 Issues

Contents

MCP-first quick start · Connect your client · Embed in your app · What it does · Cross-platform · Features · Platform & ecosystem · CLI commands · Architecture · Safety · Public API · Releasing · Star History

🤖 MCP-first — install once, every agent knows your landscape

v2.0 inverts the architecture: the package's primary interface is now a production Model Context Protocol (MCP) server. Any MCP host — Claude Code, Cursor, Cline, Windsurf, VS Code Copilot, the Vercel AI SDK, LangGraph — connects to it and gains read-only awareness of your complete system landscape. The bundled Claude-driven discovery loop is now one optional turnkey adapter; the server needs no LLM dependency of its own.

The topology is exposed with progressive disclosure so agents never blow their context window:

• Resources (read-only context): cartography://graph/summary (low-token index — read first), cartography://nodes/{id}, cartography://services, cartography://databases, cartography://dependencies/{id}.
• Tools (parameterized queries): query_infrastructure, search_topology (semantic), get_dependencies (recursive graph traversal), query_natural_language (plain-English topology questions, LLM-free), correlate_topology (collapse the same resource across clouds/on-prem), get_cost_summary, score_compliance, classify_drift, list_services, get_node, get_summary, run_discovery.
• Prompts: audit-attack-surface, map-service-dependencies, onboard-to-system.

Quick start

# 1. Discover your system (read-only, deterministic — no LLM required)
npx -p @datasynx/agentic-ai-cartography cartography-mcp --help
datasynx-cartography discover          # or the richer Claude-driven loop

# 2. Run the MCP server (stdio by default)
npx -p @datasynx/agentic-ai-cartography cartography-mcp

Auto-install into your client

Let the harness write the correct config for your host — it parses the existing file and merges in the server entry without clobbering your other servers:

datasynx-cartography list-clients                          # supported hosts
# claude-code · cursor · vscode · codex · windsurf · cline · roo
# zed · junie · gemini · goose · openhands · claude-desktop
datasynx-cartography install --client claude-code          # global/user config
datasynx-cartography install --client claude-code --project # project-local (.mcp.json)
datasynx-cartography install --client claude-code --dry-run # preview the merge diff

Flags: --global (default) / --project scope, --dry-run (no write), --name <server>, --http/--url <url> (register the HTTP endpoint), --db <path>, --session <id>, --deeplink (print a one-click Cursor/VS Code install link instead of writing).

datasynx-cartography install --client cursor --deeplink   # cursor://… one-click link
datasynx-cartography install --client vscode --deeplink   # vscode://… + `code --add-mcp`

Thirteen hosts are supported today (see list-clients). The server is also deployable on Smithery (TypeScript runtime, smithery.yaml) and published to the official MCP Registry (server.json).

Smithery scope: the hosted runtime needs no secrets (smithery.yaml declares env: {}) because it serves a read-only catalog from an in-memory or supplied SQLite database. The cloud scanners (scan_aws_resources, scan_gcp_resources, scan_azure_resources, scan_k8s_resources) require the respective CLI and its credentials on the host, so they are intended for local/self-hosted runs, not the managed Smithery instance.

Claude Desktop one-click — build the portable bundle and double-click it (Settings → Extensions → Install), or drag it onto the window:

npm run build:mcpb     # → dist/cartography.mcpb (validated against the mcpb v0.3 schema)

Connect your client (copy-paste)

Claude Code — install as a plugin from the Datasynx marketplace (recommended):

/plugin marketplace add datasynx/claude-plugins
/plugin install cartography@datasynx

This wires up the MCP server in one step (verify with /mcp) — the same flow as shadowing. The plugin lives in plugin/. Prefer to wire it by hand instead?

claude mcp add cartography -- npx -p @datasynx/agentic-ai-cartography cartography-mcp

Cursor / Windsurf / Cline — mcp.json (or ~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "cartography": {
      "command": "npx",
      "args": ["-p", "@datasynx/agentic-ai-cartography", "cartography-mcp"]
    }
  }
}

VS Code (Copilot) — .vscode/mcp.json (note: servers, not mcpServers):

{
  "servers": {
    "cartography": { "command": "npx", "args": ["-p", "@datasynx/agentic-ai-cartography", "cartography-mcp"] }
  }
}

Remote / team use — Streamable HTTP (localhost-bound, DNS-rebind protected):

cartography-mcp --http --port 3737      # → http://127.0.0.1:3737/mcp (loopback, no auth)

# Exposing beyond loopback requires BOTH an explicit Host allowlist (CVE-2025-66414)
# AND a bearer token — clients must send `Authorization: Bearer <token>`:
export CARTOGRAPHY_HTTP_TOKEN=$(openssl rand -hex 32)
cartography-mcp --http --host 0.0.0.0 --port 3737 \
  --allowed-hosts cartography.internal:3737 --token "$CARTOGRAPHY_HTTP_TOKEN"

Binding a non-loopback --host without --allowed-hosts (DNS-rebinding) or without --token (CARTOGRAPHY_HTTP_TOKEN) is refused on purpose — it would leave the scanning tools open to anyone who can reach the host. Put it behind TLS / a reverse proxy for real deployments. The same flags work on datasynx-cartography mcp and the Smithery deployment.

Vercel AI SDK (provider-agnostic):

import { experimental_createMCPClient } from 'ai';
const mcp = await experimental_createMCPClient({
  transport: { type: 'sse', url: 'http://127.0.0.1:3737/mcp' },
});
const tools = await mcp.tools(); // MCP tools → AI SDK tools, any model

Frameworks without a config file (CrewAI, AutoGen/MAF, LangGraph, Pydantic AI, OpenAI Agents SDK, Smolagents, Vercel AI SDK) load MCP tools via their own adapters — copy-paste snippets in docs/adapters.md.

Full documentation lives at datasynx.github.io/agentic-ai-cartography — quickstart, the client matrix, MCP tools and CLI reference. Drop AGENTS.md into a repo to give coding agents the standard config block.

Embed in your own app

import { createMcpServer, runStdio, createSemanticSearch, localDiscoveryFn, CartographyDB } from '@datasynx/agentic-ai-cartography';

const db = new CartographyDB('/path/to/cartography.db');
const server = createMcpServer({
  db,
  search: await createSemanticSearch(db),   // semantic (sqlite-vec) + lexical fallback
  discovery: localDiscoveryFn(),            // deterministic, LLM-free scanners
});
await runStdio(server);

What it does

$ datasynx-cartography discover

  CARTOGRAPHY  localhost
  ─────────────────────────────────────────────
  🔖  Browser bookmarks scanned…
  🖥  All installed apps scanned…
  +  Node  saas_tool:vscode           [saas_tool]   90%
  +  Node  saas_tool:cursor           [saas_tool]   90%
  +  Node  saas_tool:docker-desktop   [saas_tool]   90%
  +  Node  saas_tool:github.com       [saas_tool]   70%  🔖
  +  Node  web_service:localhost:5432 [database]    90%
  +  Node  web_service:localhost:6379 [cache]       90%
  ~  Edge  web_service:app → web_service:localhost:5432  uses
  ─────────────────────────────────────────────
  DONE  9 nodes, 3 edges  in 38.4s

  SEARCH MORE  — Refine discovery interactively
  → Search for (Enter = finish): hubspot windsurf
  ⟳  Searching for: hubspot windsurf
  +  Node  saas_tool:hubspot.com      [saas_tool]   70%  🔖
  +  Node  saas_tool:windsurf         [saas_tool]   90%

Cross-Platform Support

Cartography runs natively on Linux, macOS, and Windows — no WSL required on Windows.

Capability	Linux	macOS	Windows
Network scanning	ss -tlnp	lsof -iTCP -sTCP:LISTEN	Get-NetTCPConnection
Process listing	ps aux	ps aux	Get-Process
Installed apps	dpkg, rpm, snap, flatpak, .desktop	/Applications, Homebrew, Spotlight	Registry, winget, choco, scoop
Command lookup	which	which	Get-Command (PowerShell)
File search	find	find	Get-ChildItem -Recurse
Shell	/bin/sh	/bin/sh	PowerShell (pwsh / powershell.exe)
DB service detection	CLI probes (psql, mysql, etc.)	CLI probes	Get-Service + CLI probes
Browser bookmarks	~/.config/google-chrome + Snap/Flatpak	~/Library/Application Support/...	%LOCALAPPDATA%\Google\Chrome\User Data
Firefox profiles	~/.mozilla/firefox + Snap/Flatpak	~/Library/.../Firefox/Profiles	%APPDATA%\Mozilla\Firefox\Profiles
Safety policy	Read-only allowlist (POSIX parser)	Read-only allowlist (POSIX parser)	Read-only allowlist (PowerShell mutating-cmdlet denylist)

Features

Feature	Details
Installed App Scan	Linux: dpkg/snap/flatpak/rpm, macOS: /Applications + Homebrew + Spotlight, Windows: Registry + winget + choco + scoop. 70+ known tools checked via cross-platform command lookup
Browser Bookmarks	Chrome, Chromium, Firefox, Brave, Edge, Vivaldi, Opera — all platforms including Snap/Flatpak on Linux
Database Discovery	PostgreSQL, MySQL, MongoDB, Redis, SQLite file scan. Windows: Get-Service for DB engine detection
Cloud Scanning	AWS (EC2/RDS/EKS/S3), GCP (Compute/GKE/Cloud Run), Azure (AKS/WebApps), Kubernetes
Human-in-the-Loop	Chat with the agent mid-discovery: type "hubspot windsurf" to search for specific tools
Terraform Import	First-class terraform-state scanner — *.tfstate JSON → authoritative IaC nodes/edges, reconciled with observed reality (no terraform CLI, no extra credentials)
Multi-Cloud Correlation	Collapse the same logical resource discovered across AWS/GCP/Azure/on-prem into canonical entities + confidence-scored same_as links (correlate_topology, pure & deterministic)
Intelligence Layer	Cost attribution (FinOps rollups), compliance scoring (CIS/SOC2/ISO 27001 starters), anomaly detection (orphans / shadow IT), severity-classified drift
Export Formats	Mermaid topology, D3.js interactive graph, Backstage YAML, JSON
Safety First	Strict read-only allowlist (not a denylist): only known-safe commands run — shell-aware for POSIX and PowerShell, enforced at the command runner as defense-in-depth. 100% read-only

Platform & Ecosystem

Beyond the MCP server, Cartography ships a read-only platform for teams and an ecosystem of integrations. Everything below is opt-in, read-only by default, and never phones home — the same locked constraints as the core.

REST / GraphQL API + web dashboard (Phase 4)

cartography api (and the cartography-api binary) exposes the topology over a read-only HTTP API — REST under /v1/... with a published OpenAPI 3.1 document, and GraphQL at /graphql (SDL + introspection, no Mutation type). It reuses the MCP transport's constant-time bearer auth + DNS-rebinding hardening and the same tenant-scoped query layer — no new runtime dependency (Node's built-in http).

cartography api                         # loopback dev — REST + /graphql + dashboard, no token
curl -s http://127.0.0.1:3737/v1/summary | jq .totals
# Exposed: a non-loopback bind REQUIRES both --allowed-hosts and --token
cartography api --host 0.0.0.0 --allowed-hosts cartograph.internal:3737 --token "$TOKEN"
cartography api --no-graphql            # REST only
cartography api --no-dashboard          # disable the / and /app web UI

The same server hosts a self-contained web dashboard at / and /app — a live, interactive Canvas topology view with node drill-down (no CDN, no build step, zero new dependency). It fetches the live /v1/* API, so it inherits the API's auth + RBAC/tenant scoping for free. See docs/how-to/api-server.md and docs/how-to/web-dashboard.md.

Role-based access control (Phase 4)

cartography auth layers identity + roles over the HTTP surfaces. A bearer token resolves to a principal { subject, tenant, role }; the server returns 401 for an unknown token, 403 for an insufficient role, and pins every read to the principal's tenant — no cross-tenant read by spoofing a header. Roles are viewer ⊂ operator (adds run_discovery) ⊂ admin (adds credential admin). Fully backward-compatible: with no credentials configured, the server behaves exactly as before. Tokens are stored hashed (sha256), printed once on creation.

cartography auth add alice --role operator --tenant acme   # prints the bearer token ONCE
cartography auth list                                       # subjects/roles/tenants, never the token
cartography auth revoke alice
cartography api --auth-required                             # require auth even on loopback

See docs/how-to/rbac.md.

Central collector → production (Phase 4)

cartography mcp --server-mode runs the binary as a self-hostable central collector that pools every employee's consented discovery into one org-wide topology — consent-first, never phones home. It exposes an authenticated POST /ingest write route (the consent-gated push envelope, server-side anonymization re-validation via --anon-mode reject|strip, per-org rate limit → 429 + Retry-After) and an org-wide merged get_summary. Public GET /healthz (liveness) / GET /readyz (readiness) probes and a deploy/ Docker bundle make it orchestrator-ready.

export CARTOGRAPHY_CENTRAL_TOKEN=$(openssl rand -base64 32)
cartography mcp --server-mode --host 0.0.0.0 \
  --allowed-hosts cartograph.internal:3737 --org acme --anon-mode reject

For an org-wide store at 10K+ nodes, opt into a Neo4j/Memgraph graph-DB backend for the collector's merge + summary path (neo4j-driver is an optional dependency; if absent or unreachable it degrades to SQLite, never fails):

cartography mcp --server-mode --store-backend graph \
  --graph-url bolt://graph.internal:7687 --graph-user neo4j --graph-password "$NEO4J_PASSWORD"
# or via env: CARTOGRAPHY_GRAPH_URL / _USER / _PASSWORD (kept out of process listings)

See docs/how-to/self-host-collector.md.

Backstage live data source (Phase 4)

Cartography maps discovered infrastructure to Backstage catalog entities (Component/API/ Resource + dependsOn relations). Export a static catalog-info.yaml snapshot, or consume the live, tenant-scoped endpoint GET /v1/backstage/catalog on the API server (re-mapped on every request, RBAC-pinned). A reference CartographEntityProvider lives in examples/backstage-plugin/. See docs/how-to/backstage.md.

Drift alerting — Slack / PagerDuty / Jira (Phase 4)

cartography drift classifies topology drift into info/warning/critical and fans it out to the sinks configured under the drift block of cartography.config.json — stdout, slack, pagerduty, jira, or a generic webhook. With no config it prints one redacted JSON line and makes no outbound request. Every sink is hardened identically (https:-or-loopback only, bounded timeout, body always credential-redacted, only host:port logged, one failing sink never blocks the others). See docs/how-to/drift-and-ci.md.

Kubernetes operator (Phase 5)

cartography operator runs the deterministic, LLM-free discovery continuously inside a cluster and reports drift between reconcile cycles — a "continuous CMDB for Kubernetes". It's a thin reconcile loop (no CRD, no controller-runtime, no agent loop), read-only (kubectl get … via the allowlist only). The deploy/k8s/ manifests ship a read-only ServiceAccount + ClusterRole (get/list/watch only — no write verbs).

kubectl apply -f deploy/k8s/operator.yaml          # in-cluster, single-replica Deployment
cartography operator --once                         # local dev against your kube-context
cartography operator --interval 300                 # long-running reconcile loop

See docs/how-to/k8s-operator.md and docs/how-to/terraform-import.md.

Requirements

• Node.js >= 20 (Linux, macOS, or Windows) — that's it for the MCP server and the deterministic, read-only discovery. No LLM and no API key required.
• Optional — Claude CLI, only for the richer Claude-driven discovery loop (datasynx-cartography discover): npm install -g @anthropic-ai/claude-code && claude login.
• Optional — semantic search auto-upgrades when sqlite-vec and a local embedder (@huggingface/transformers) are present; otherwise it falls back to lexical search. These ship as optionalDependencies and are lazy-loaded, so installs that skip them pay no cost. On startup the server logs semantic search: ready when the upgrade is active, or names the missing dependency and that it is using lexical search when it isn't.

Install

npm install -g @datasynx/agentic-ai-cartography

Quick Start

# Check all requirements (platform-aware)
datasynx-cartography doctor

# Discover your full infrastructure (autonomous agent scan)
# → scans bookmarks, installed apps, local services, cloud, config files
# → then interactive follow-up: type tool names to search further
datasynx-cartography discover

# Seed infrastructure manually (JSON file or interactive)
datasynx-cartography seed --file infra.json
datasynx-cartography seed

# View all browser bookmarks
datasynx-cartography bookmarks

# Full feature reference (shows platform-specific commands)
datasynx-cartography docs

Commands

Cartography (Discovery)

datasynx-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>           LLM model            (default: claude-sonnet-4-5-...)
  --org <name>          Org name for Backstage YAML
  -o, --output <dir>    Output directory     (default: ./datasynx-output)
  -v, --verbose         Show agent reasoning

Discovery pipeline (automatic, in order):

• Browser bookmarks — every domain classified as saas_tool or web_service
• Installed apps — all IDEs, business tools, dev tools, browsers (platform-native detection)
• Local services — ss (Linux), lsof (macOS), Get-NetTCPConnection (Windows)
• Database discovery — PostgreSQL, MySQL, MongoDB, Redis, SQLite files
• Cloud & Kubernetes — AWS/GCP/Azure/k8s (skipped gracefully if not configured)
• Config files — .env, docker-compose.yml, etc.
• Human-in-the-loop — interactive follow-up after initial scan

Analysis & Export

datasynx-cartography export [session-id] [options]
  --format <fmt...>    mermaid, json, yaml, html, map  (default: all)
  -o, --output <dir>   Output directory
datasynx-cartography show [session-id]             Session details + node list
datasynx-cartography sessions                      List all sessions
datasynx-cartography diff [base] [current]         Topology drift between two sessions (default: two most recent)
datasynx-cartography drift [base] [current]        Severity-classified drift alert → sink (default: stdout)
  --min-severity <s>   info | warning | critical    (drop items below this)
  --webhook <url>      Outbound webhook sink (opt-in; token via CARTOGRAPHY_DRIFT_TOKEN)
datasynx-cartography bookmarks                     View all browser bookmarks
datasynx-cartography seed [--file <path>]          Manually add infrastructure nodes
datasynx-cartography cost --file <csv>             Enrich nodes with owner/cost (FinOps)
datasynx-cartography compliance [session] --ruleset <name>   Grade against baseline/cis/soc2/iso27001
datasynx-cartography consent <…>                   Per-employee sharing policy + anonymization
datasynx-cartography sync <status|review|push>     Opt-in central-DB outbound pipeline
datasynx-cartography schedule --config <file>      Recurring headless discovery + drift
datasynx-cartography prune [--older-than <days>]   Prune old sessions / compact the audit trail
datasynx-cartography doctor                        Check all requirements + cloud CLIs
datasynx-cartography docs                          Full feature reference

Platform & Ecosystem

datasynx-cartography mcp [--server-mode] [--http]  MCP server / central collector (Phase 4)
datasynx-cartography api [--no-graphql] [--no-dashboard]   REST + GraphQL + web dashboard (Phase 4)
  --host <h> --port <n> --token <secret> --allowed-hosts <list>   (non-loopback needs both)
  --tenant <id> / --org <id>                       Tenant whose topology to serve
datasynx-cartography auth add <subject> --role <viewer|operator|admin> --tenant <id>   RBAC (Phase 4)
datasynx-cartography auth list | revoke <subject>
datasynx-cartography operator [--once] [--interval <sec>]   Kubernetes operator (Phase 5)

The cartography-mcp and cartography-api binaries start the MCP server and the API server directly (used by server.json / containers via npx).

Output Files

datasynx-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)
└── discovery.html             Enterprise discovery frontend (Map + Topology)

Cost Estimate

Mode	Model	Interval	per Hour	per 8h Day
Discover	Sonnet	one-shot	$0.15–0.50	one-shot

Architecture

The MCP server is the headline interface — LLM-agnostic and the same SQLite graph underneath every entry point. Discovery (deterministic scanners or the optional Claude loop) writes the graph; any MCP host reads it. The Phase 4 platform adds read-only HTTP surfaces over that same graph — the REST/GraphQL API (cartography api), the web dashboard, RBAC (cartography auth), the self-hostable central collector (mcp --server-mode, with an optional Neo4j/Memgraph backend), and a live Backstage data source — all sharing the MCP transport's bearer auth + tenant scoping.

                         ┌──────────────────────────────────────────┐
   MCP hosts ───────────►│  MCP server (src/mcp) — primary interface │
   (Claude Code,         │    Resources · Tools · Prompts            │
    Cursor, Cline,       │    stdio + Streamable HTTP transports     │
    Windsurf, VS Code,   └───────────────────┬──────────────────────┘
    Vercel AI SDK, …)                        │
                                             ▼
                              CartographyDB (SQLite WAL, src/db)
                         recursive-CTE traversal · search · summary
                                             ▲
                ┌────────────────────────────┴────────────────────────────┐
                │                                                          │
   Deterministic discovery (src/discovery, src/scanners)     Optional Claude loop (src/agent)
     bookmarks · installed-apps · local ports · DBs            runDiscovery() — human-in-the-loop
     LLM-free, registry-driven                                 LLM + Bash + custom MCP tools
                │                                                          │
                └──────────────────────────┬───────────────────────────────┘
                                           ▼
                    Platform layer (src/platform) + read-only allowlist (src/allowlist)
                    Shell/commands resolved per-OS · every command vetted before it runs

Safety

v2.0 replaces the old "block bad commands" denylist with a strict read-only allowlist (src/allowlist.ts): a command runs only if it is explicitly known to be safe. The check is shell-aware and enforced in two places — the command runner itself (defense-in-depth) and the Claude loop's PreToolUse hook.

• POSIX: parses the command line, resolves sudo/env/command-runners and brace groups, and allows only read-only tools (ss, lsof, ps, which, find, DB probes, cloud describe/list/get, kubectl get/describe, …). Redirections, pipes to writers, and anything unrecognized are rejected.
• Windows/PowerShell: allows read-only cmdlets and rejects mutating ones (Remove-Item, Move-Item, Stop-Process, Stop-Service, Restart-Computer, Format-Volume, Out-File, Set-Content, …).

Cartography only reads — never writes, never deletes.

Extending: scanner plugins

Add new discovery sources with zero core changes via the Scanner SPI. An out-of-tree @datasynx/scanner-* package default-exports definePlugin({ name, register }) and is loaded opt-in (config.plugins, --plugins, or CARTOGRAPHY_PLUGINS) — a plugin that is not named is never loaded. The host validates, namespaces (plugin:<pkg>:<id>), and enforces each scanner's declared allowedCommands against the read-only allowlist; a broken plugin is logged and skipped, never aborting discovery. See the authoring guide in docs/plugins.md and the template in examples/scanner-template/.

Public API

import {
  CartographyDB,
  runDiscovery,
  exportAll,
  safetyHook,
  defaultConfig,
} from '@datasynx/agentic-ai-cartography';

// Run a discovery pass with optional user hint
await runDiscovery(config, db, sessionId, onEvent, onAskUser, 'hubspot windsurf');

Releasing

release.yml publishes to npm automatically on every push to main, in one of two modes — auto-selected by which secrets are present:

• RELEASE_TOKEN present → full semantic-release. Version, CHANGELOG.md, git tag v<version>, GitHub Release and the provenance-signed npm publish are all derived from Conventional Commits since the last tag (fix: → patch, feat: → minor, feat!:/BREAKING CHANGE: → major; docs/chore/refactor/test/ci → no release). No manual version bumps. PR titles are linted by pr-title.yml so the squash-merge commit stays analyzable.
• RELEASE_TOKEN absent → idempotent npm publish. The package.json version is published (provenance-signed) only when it isn't already on npm — so doc/refactor merges are no-ops. Bump the version + merge to release.

Why two modes: every commit here carries .github/workflows/ files, and the Actions GITHUB_TOKEN may not push a git ref that touches workflow files (it can't hold the workflow scope). semantic-release pushes a tag, so it needs a workflow-scoped RELEASE_TOKEN. Until one exists, the idempotent publish keeps releases flowing with only NPM_TOKEN; adding RELEASE_TOKEN later upgrades to the full flow with no other changes.

Quality is gated independently by ci.yml on every PR and push: lint/typecheck → test matrix (Node 20/22) + coverage → audit + license check → build & validate (publint, are-the-types-wrong, ESM/CJS consumer smoke tests).

Repository secrets (Settings → Secrets and variables → Actions):

Secret	Required	Purpose
NPM_TOKEN	yes	npm Automation/granular token with publish rights for the @datasynx scope. Provenance signing itself needs no secret (OIDC).
RELEASE_TOKEN	optional	PAT (classic: repo + workflow) or deploy key. Unlocks full semantic-release (auto-versioning, changelog, tags, GitHub Releases). Without it, the idempotent npm publish is used.
CODECOV_TOKEN	optional	Upload coverage to Codecov (non-blocking if absent).

Star History

Built by

License

MIT — © Datasynx AI

Related Projects

• agentic-ai-shadowing — AI-powered agent session shadowing & replay