@datasynx/agentic-ai-cartography 2.5.0 → 2.7.0

package/dist/index.js

@@ -2562,6 +2562,7 @@ function newAnomalies(base, current) {
 
 // src/db.ts
 var DEFAULT_TENANT = "local";
+var SCHEMA_VERSION = 15;
 function normalizeTenant(raw) {
   if (raw == null) return DEFAULT_TENANT;
   const cleaned = sanitizeUntrusted(String(raw)).trim().slice(0, 128);
@@ -3966,6 +3967,14 @@ var CartographyDB = class {
     }
     return rows.length;
   }
+  /**
+   * Retention/compaction (4.7): delete audit events older than `olderThan` (ISO 8601).
+   * The audit trail grows unbounded on a busy collector; this bounds it without touching
+   * sessions/nodes/edges. Returns the number of events removed.
+   */
+  pruneEventsOlderThan(olderThan) {
+    return this.db.prepare("DELETE FROM activity_events WHERE timestamp < ?").run(olderThan).changes;
+  }
   // ── Graph queries (read-only context layer) ─────────────────────────────────
   /** Fetch a single node by id within a session. */
   getNode(sessionId, nodeId) {
@@ -4404,6 +4413,9 @@ var SqliteQueryBackend = class {
   node(ctx, id, sessionId) {
     return this.db.getNode(this.resolveSession(ctx, sessionId), id);
   }
+  edges(ctx, sessionId) {
+    return this.db.getEdges(this.resolveSession(ctx, sessionId));
+  }
   dependencies(ctx, id, q, sessionId) {
     const sid = this.resolveSession(ctx, sessionId);
     return this.db.getDependencies(sid, id, {
@@ -4654,7 +4666,7 @@ var ContributorSchema = z5.object({
 });
 var IngestEnvelopeSchema = z5.object({
   schemaVersion: z5.literal(INGEST_SCHEMA_VERSION),
-  org: z5.string().min(1).optional(),
+  org: z5.string().min(1).max(128).optional(),
   items: z5.array(z5.object({
     contentHash: z5.string(),
     kind: z5.enum(["node", "edge"]),
@@ -4742,6 +4754,7 @@ function ingestEnvelope(store, envelope, opts = {}) {
 
 // src/central/server.ts
 function createIngestHandler(store, opts = {}) {
+  const quota = opts.quota;
   return (body) => {
     const parsed = IngestEnvelopeSchema.safeParse(body);
     if (!parsed.success) {
@@ -4749,6 +4762,14 @@ function createIngestHandler(store, opts = {}) {
       logWarn("ingest: rejected invalid envelope", { issues });
       return { status: 400, body: { error: "invalid envelope", issues } };
     }
+    if (quota) {
+      const org = normalizeTenant(parsed.data.org ?? opts.defaultOrg);
+      const decision = quota.take(org);
+      if (!decision.allowed) {
+        logWarn("ingest: rate limited", { org, retryAfterSec: decision.retryAfterSec });
+        return { status: 429, body: { error: "too many requests" }, headers: { "retry-after": String(decision.retryAfterSec) } };
+      }
+    }
     try {
       const result = ingestEnvelope(store, parsed.data, opts);
       return { status: 200, body: result };
@@ -4759,6 +4780,39 @@ function createIngestHandler(store, opts = {}) {
   };
 }
 
+// src/central/quota.ts
+var DEFAULT_INGEST_QUOTA = { capacity: 120, refillMs: 6e4 };
+var MAX_KEYS = 1e4;
+var RateLimiter = class {
+  constructor(cfg = DEFAULT_INGEST_QUOTA, now = () => Date.now()) {
+    this.cfg = cfg;
+    this.now = now;
+  }
+  buckets = /* @__PURE__ */ new Map();
+  /** Consume one token for `key`. Returns whether the request is allowed (+ Retry-After when not). */
+  take(key) {
+    const t = this.now();
+    const ratePerMs = this.cfg.capacity / this.cfg.refillMs;
+    let b = this.buckets.get(key);
+    if (!b) {
+      if (this.buckets.size >= MAX_KEYS) {
+        const oldest = this.buckets.keys().next().value;
+        if (oldest !== void 0) this.buckets.delete(oldest);
+      }
+      b = { tokens: this.cfg.capacity, last: t };
+      this.buckets.set(key, b);
+    }
+    b.tokens = Math.min(this.cfg.capacity, b.tokens + Math.max(0, t - b.last) * ratePerMs);
+    b.last = t;
+    if (b.tokens >= 1) {
+      b.tokens -= 1;
+      return { allowed: true, retryAfterSec: 0 };
+    }
+    const waitMs = (1 - b.tokens) / ratePerMs;
+    return { allowed: false, retryAfterSec: Math.max(1, Math.ceil(waitMs / 1e3)) };
+  }
+};
+
 // src/scanners/bookmarks.ts
 var PERSONAL = [
   "facebook.",
@@ -5646,7 +5700,7 @@ async function resolveNlQuery(db, sessionId, search, raw, opts) {
 
 // src/mcp/server.ts
 var SERVER_NAME = "cartography";
-var SERVER_VERSION = "2.5.0";
+var SERVER_VERSION = "2.7.0";
 var SERVICE_TYPES = NODE_TYPE_GROUPS.web;
 var DATA_TYPES = NODE_TYPE_GROUPS.data;
 var lexicalSearch = async (db, sessionId, query, opts) => db.searchNodes(sessionId, query, { types: opts.types, limit: opts.limit }).map((node) => ({ node }));
@@ -6289,6 +6343,16 @@ async function runHttp(factory, opts = {}) {
   const httpServer = http.createServer(async (req, res) => {
     try {
       const url = req.url ?? "";
+      const probePath = new URL(url || "/", "http://probe").pathname;
+      if (probePath === "/healthz") {
+        res.writeHead(200, { "content-type": "application/json" }).end('{"status":"ok"}');
+        return;
+      }
+      if (probePath === "/readyz") {
+        const r = opts.readiness ? opts.readiness() : { ready: true };
+        res.writeHead(r.ready ? 200 : 503, { "content-type": "application/json" }).end(JSON.stringify({ status: r.ready ? "ready" : "unready" }));
+        return;
+      }
       const isIngest = url.startsWith("/ingest") && opts.onIngest !== void 0;
       if (!url.startsWith("/mcp") && !isIngest) {
         res.writeHead(404, { "content-type": "application/json" }).end('{"error":"not found"}');
@@ -6316,7 +6380,7 @@ async function runHttp(factory, opts = {}) {
           return;
         }
         const out = onIngest(value);
-        res.writeHead(out.status, { "content-type": "application/json" }).end(JSON.stringify(out.body));
+        res.writeHead(out.status, { "content-type": "application/json", ...out.headers ?? {} }).end(JSON.stringify(out.body));
         return;
       }
       const sessionId = req.headers["mcp-session-id"];
@@ -7179,6 +7243,54 @@ function headerValue(req, name) {
   return v;
 }
 
+// src/backstage.ts
+var COMPONENT_TYPES = ["web_service", "container", "pod"];
+function sanitize(id) {
+  return id.replace(/[^a-zA-Z0-9_]/g, "_");
+}
+function toBackstageEntities(nodes, edges, opts = {}) {
+  const owner = opts.org ?? "unknown";
+  return nodes.map((node) => {
+    const kind = COMPONENT_TYPES.includes(node.type) ? "Component" : node.type === "api_endpoint" ? "API" : "Resource";
+    const dependsOn = edges.filter((e) => e.sourceId === node.id).map((e) => `resource:default/${sanitize(e.targetId)}`);
+    return {
+      apiVersion: "backstage.io/v1alpha1",
+      kind,
+      metadata: {
+        name: sanitize(node.id),
+        annotations: {
+          "cartography/discovered-at": node.discoveredAt,
+          "cartography/confidence": String(node.confidence)
+        }
+      },
+      spec: {
+        type: node.type,
+        lifecycle: "production",
+        owner: node.owner ?? owner,
+        ...dependsOn.length > 0 ? { dependsOn } : {}
+      }
+    };
+  });
+}
+function entitiesToYaml(entities) {
+  return entities.map((e) => {
+    const lines = [
+      `apiVersion: ${e.apiVersion}`,
+      `kind: ${e.kind}`,
+      `metadata:`,
+      `  name: ${e.metadata.name}`,
+      `  annotations:`,
+      ...Object.entries(e.metadata.annotations).map(([k, v]) => `    ${k}: "${v}"`),
+      `spec:`,
+      `  type: ${e.spec.type}`,
+      `  lifecycle: ${e.spec.lifecycle}`,
+      `  owner: ${e.spec.owner}`,
+      ...e.spec.dependsOn && e.spec.dependsOn.length > 0 ? ["  dependsOn:", ...e.spec.dependsOn.map((d) => `    - ${d}`)] : []
+    ];
+    return lines.join("\n");
+  }).join("\n---\n");
+}
+
 // src/api/schemas.ts
 import { z as z8 } from "zod";
 var DIRECTIONS = ["downstream", "upstream", "both"];
@@ -7314,6 +7426,21 @@ var ErrorResponse = z8.object({
   error: z8.string(),
   code: z8.string().optional()
 });
+var BackstageEntitySchema = z8.object({
+  apiVersion: z8.literal("backstage.io/v1alpha1"),
+  kind: z8.enum(["Component", "API", "Resource"]),
+  metadata: z8.object({
+    name: z8.string(),
+    annotations: z8.record(z8.string(), z8.string())
+  }),
+  spec: z8.object({
+    type: z8.string(),
+    lifecycle: z8.string(),
+    owner: z8.string(),
+    dependsOn: z8.array(z8.string()).optional()
+  })
+});
+var BackstageCatalogResponse = z8.object({ entities: z8.array(BackstageEntitySchema) });
 var API_SCHEMAS = {
   Node: NodeSchema2,
   Edge: EdgeSchema2,
@@ -7325,10 +7452,13 @@ var API_SCHEMAS = {
   Session: SessionSchema,
   Sessions: SessionsResponse,
   Health: HealthResponse,
-  Error: ErrorResponse
+  Error: ErrorResponse,
+  BackstageEntity: BackstageEntitySchema,
+  BackstageCatalog: BackstageCatalogResponse
 };
 
 // src/api/rest.ts
+var BACKSTAGE_NODE_CAP = 1e3;
 function toApiNode(n) {
   const out = { id: n.id, type: n.type, name: n.name, confidence: n.confidence, tags: n.tags };
   if (n.domain !== void 0) out["domain"] = n.domain;
@@ -7463,6 +7593,14 @@ function handleHealth(ctx, d) {
   const h = d.backend.health(ctx);
   return ok(validateOut(HealthResponse, { status: "ok", version: d.version, store: h.store, sessions: h.sessions }));
 }
+function handleBackstageCatalog(ctx, d) {
+  return guard(() => {
+    const page = d.backend.nodes(ctx, { limit: BACKSTAGE_NODE_CAP });
+    const edges = d.backend.edges(ctx);
+    const entities = toBackstageEntities(page.nodes, edges, { org: ctx.tenant });
+    return ok(validateOut(BackstageCatalogResponse, { entities }));
+  });
+}
 
 // src/api/openapi.ts
 function defOf(schema) {
@@ -7619,6 +7757,13 @@ function buildOpenApiDocument(opts) {
           parameters: [TENANT_PARAM],
           responses: { "200": ok2("Sessions", "Sessions"), ...errorResponses() }
         }
+      },
+      "/v1/backstage/catalog": {
+        get: {
+          summary: "The tenant topology as Backstage catalog entities (live data source, 4.6)",
+          parameters: [SESSION_PARAM, TENANT_PARAM],
+          responses: { "200": ok2("BackstageCatalog", "Backstage catalog entities"), ...errorResponses() }
+        }
       }
     }
   };
@@ -8133,6 +8278,8 @@ function dispatchRest(ctx, path, url, deps) {
       return handleDiff(ctx, url, deps);
     case "/v1/sessions":
       return handleSessions(ctx, deps);
+    case "/v1/backstage/catalog":
+      return handleBackstageCatalog(ctx, deps);
     default: {
       const m = DEPENDENCIES_RE.exec(path);
       if (m) return handleDependencies(ctx, decodeURIComponent(m[1]), url, deps);
@@ -9638,7 +9785,7 @@ var MERMAID_CLASSES = {
   saas_tool: "fill:#2a1a2a,stroke:#9a3a9a,color:#daf",
   unknown: "fill:#2a2a2a,stroke:#5a5a5a,color:#aaa"
 };
-function sanitize(id) {
+function sanitize2(id) {
   return id.replace(/[^a-zA-Z0-9_]/g, "_");
 }
 function nodeLabel(node) {
@@ -9680,14 +9827,14 @@ function generateTopologyMermaid(nodes, edges) {
     const label = LAYER_LABELS[layerKey] ?? layerKey;
     lines.push(`    subgraph ${layerKey}["${label}"]`);
     for (const node of layerNodes) {
-      lines.push(`      ${sanitize(node.id)}${nodeLabel(node)}:::${node.type.replace(/_/g, "")}`);
+      lines.push(`      ${sanitize2(node.id)}${nodeLabel(node)}:::${node.type.replace(/_/g, "")}`);
     }
     lines.push("    end");
     lines.push("");
   }
   for (const edge of edges) {
-    const src = sanitize(edge.sourceId);
-    const tgt = sanitize(edge.targetId);
+    const src = sanitize2(edge.sourceId);
+    const tgt = sanitize2(edge.targetId);
     const label = EDGE_LABELS[edge.relationship] ?? edge.relationship;
     const arrow = edge.confidence < 0.6 ? `-. "${label}" .->` : `-->|"${label}"|`;
     lines.push(`    ${src} ${arrow} ${tgt}`);
@@ -9713,12 +9860,12 @@ function generateDependencyMermaid(nodes, edges) {
   }
   lines.push("");
   for (const node of usedNodes) {
-    lines.push(`    ${sanitize(node.id)}${nodeLabel(node)}:::${node.type.replace(/_/g, "")}`);
+    lines.push(`    ${sanitize2(node.id)}${nodeLabel(node)}:::${node.type.replace(/_/g, "")}`);
   }
   lines.push("");
   for (const edge of depEdges) {
     const label = EDGE_LABELS[edge.relationship] ?? edge.relationship;
-    lines.push(`    ${sanitize(edge.sourceId)} -->|"${label}"| ${sanitize(edge.targetId)}`);
+    lines.push(`    ${sanitize2(edge.sourceId)} -->|"${label}"| ${sanitize2(edge.targetId)}`);
   }
   return lines.join("\n");
 }
@@ -9769,44 +9916,21 @@ function generateDiffMermaid(diff) {
     ensureEndpoint(e.targetId);
   }
   for (const { node, cls, suffix } of entries.values()) {
-    lines.push(`    ${sanitize(node.id)}${diffNodeLabel(node, suffix)}:::${cls}`);
+    lines.push(`    ${sanitize2(node.id)}${diffNodeLabel(node, suffix)}:::${cls}`);
   }
   lines.push("");
   for (const e of diff.edges.added) {
     const label = EDGE_LABELS[e.relationship] ?? e.relationship;
-    lines.push(`    ${sanitize(e.sourceId)} ==>|"+ ${label}"| ${sanitize(e.targetId)}`);
+    lines.push(`    ${sanitize2(e.sourceId)} ==>|"+ ${label}"| ${sanitize2(e.targetId)}`);
   }
   for (const e of diff.edges.removed) {
     const label = EDGE_LABELS[e.relationship] ?? e.relationship;
-    lines.push(`    ${sanitize(e.sourceId)} -.->|"- ${label}"| ${sanitize(e.targetId)}`);
+    lines.push(`    ${sanitize2(e.sourceId)} -.->|"- ${label}"| ${sanitize2(e.targetId)}`);
   }
   return lines.join("\n");
 }
 function exportBackstageYAML(nodes, edges, org) {
-  const owner = org ?? "unknown";
-  const docs = [];
-  for (const node of nodes) {
-    const isComponent = ["web_service", "container", "pod"].includes(node.type);
-    const isAPI = node.type === "api_endpoint";
-    const kind = isComponent ? "Component" : isAPI ? "API" : "Resource";
-    const deps = edges.filter((e) => e.sourceId === node.id).map((e) => `    - resource:default/${sanitize(e.targetId)}`);
-    const doc = [
-      `apiVersion: backstage.io/v1alpha1`,
-      `kind: ${kind}`,
-      `metadata:`,
-      `  name: ${sanitize(node.id)}`,
-      `  annotations:`,
-      `    cartography/discovered-at: "${node.discoveredAt}"`,
-      `    cartography/confidence: "${node.confidence}"`,
-      `spec:`,
-      `  type: ${node.type}`,
-      `  lifecycle: production`,
-      `  owner: ${node.owner ?? owner}`,
-      ...deps.length > 0 ? ["  dependsOn:", ...deps] : []
-    ].join("\n");
-    docs.push(doc);
-  }
-  return docs.join("\n---\n");
+  return entitiesToYaml(toBackstageEntities(nodes, edges, org !== void 0 ? { org } : {}));
 }
 function exportJSON(db, sessionId) {
   const nodes = db.getNodes(sessionId);
@@ -11506,6 +11630,7 @@ export {
   CredentialConfigSchema,
   CsvCostSource,
   DEFAULT_ANOMALY_THRESHOLDS,
+  DEFAULT_INGEST_QUOTA,
   DEFAULT_SERVER_NAME,
   DEFAULT_TENANT,
   DriftConfigSchema,
@@ -11527,10 +11652,12 @@ export {
   ProviderRegistry,
   RELATION_TO_DIRECTION,
   ROLES,
+  RateLimiter,
   RoleSchema,
   RuleCheckSchema,
   RulesetSchema,
   SCAN_ARG_PATTERNS,
+  SCHEMA_VERSION,
   SDL,
   SEVERITY_WEIGHT,
   SHARING_LEVELS,
@@ -11610,6 +11737,7 @@ export {
   diffTopology,
   edgesToConnections,
   enrichCosts,
+  entitiesToYaml,
   evaluateCheck,
   evaluateRule,
   evidenceLine,
@@ -11739,6 +11867,7 @@ export {
   startApi,
   stripSensitive,
   timingSafeEqual,
+  toBackstageEntities,
   validateScanner,
   vscodeDeeplink,
   zodToJsonSchema