@sleetdrop/dsh-plugin-topology 0.1.0

package/lib/typert.js

@@ -0,0 +1,142 @@
+/**
+ * Host-face Typert manifest.
+ *
+ * The 0.1.1-rc.2 typert-loader resolves each loader entry's `exports["./typert"]`
+ * and registers its TYPERT manifest into `ctx.typert`; packages without the
+ * export are skipped silently, which leaves their `@Remote` methods
+ * undiscoverable. This module mirrors the artifact the
+ * `@deepseek-ai/dsh-typert-generator` would emit for this package, so the host
+ * gateway can dispatch `pluginTopology/analyze` and `pluginTopology/render`.
+ * @module @sleetdrop/dsh-plugin-topology/typert
+ */
+import { z } from 'zod';
+const pluginStateSchema = z.union([
+    z.literal('PENDING'), z.literal('LOADING'), z.literal('ACTIVE'),
+    z.literal('FAILED'), z.literal('DISPOSED'), z.literal('UNLOADING'),
+]);
+const pluginNodeSchema = z.object({
+    'id': z.string().readonly(),
+    'kind': z.literal('plugin').readonly(),
+    'label': z.string().readonly(),
+    'state': pluginStateSchema.readonly(),
+    'parent': z.union([z.literal(null), z.string()]).readonly(),
+    'inject': z.array(z.string()).readonly(),
+    'source': z.string().readonly().optional(),
+});
+const serviceNodeSchema = z.object({
+    'id': z.string().readonly(),
+    'kind': z.literal('service').readonly(),
+    'label': z.string().readonly(),
+    'scope': z.string().readonly(),
+});
+const topologyGraphSchema = z.object({
+    'kind': z.literal('bipartite').readonly(),
+    'generatedAt': z.string().readonly(),
+    'nodes': z.array(z.union([pluginNodeSchema, serviceNodeSchema])).readonly(),
+    'edges': z.array(z.object({
+        'source': z.string().readonly(),
+        'target': z.string().readonly(),
+        'kind': z.union([z.literal('provides'), z.literal('injects')]).readonly(),
+        'service': z.string().readonly(),
+    })).readonly(),
+    'unresolved': z.array(z.object({
+        'plugin': z.string().readonly(),
+        'service': z.string().readonly(),
+        'state': pluginStateSchema.readonly(),
+    })).readonly(),
+});
+const collapsedGraphSchema = z.object({
+    'kind': z.literal('collapsed').readonly(),
+    'generatedAt': z.string().readonly(),
+    'nodes': z.array(pluginNodeSchema).readonly(),
+    'edges': z.array(z.object({
+        'source': z.string().readonly(),
+        'target': z.string().readonly(),
+        'service': z.string().readonly(),
+    })).readonly(),
+});
+const topologyAnalysisSchema = z.object({
+    'graph': topologyGraphSchema.readonly(),
+    'collapsed': collapsedGraphSchema.readonly(),
+    'nodeMetrics': z.record(z.string(), z.object({
+        'inDegree': z.number().readonly(),
+        'outDegree': z.number().readonly(),
+        'degreeCentrality': z.number().readonly(),
+        'betweennessCentrality': z.number().readonly(),
+        'eigenvectorCentrality': z.number().readonly(),
+        'pagerank': z.number().readonly(),
+    })).readonly(),
+    'graphMetrics': z.object({
+        'nodeCount': z.number().readonly(),
+        'edgeCount': z.number().readonly(),
+        'density': z.number().readonly(),
+        'stronglyConnectedComponents': z.number().readonly(),
+        'largestSccSize': z.number().readonly(),
+        'isDag': z.boolean().readonly(),
+        'weaklyConnectedComponents': z.number().readonly(),
+        'diameter': z.number().readonly(),
+        'averagePathLength': z.number().readonly(),
+        'sourceCount': z.number().readonly(),
+        'sinkCount': z.number().readonly(),
+    }).readonly(),
+});
+export const TYPERT = {
+    package: '@sleetdrop/dsh-plugin-topology',
+    face: 'host',
+    schemas: [],
+    invocations: [
+        {
+            id: '@sleetdrop/dsh-plugin-topology#pluginTopology/analyze',
+            service: 'pluginTopology',
+            namespace: 'pluginTopology',
+            method: 'analyze',
+            invocation: { kind: 'direct' },
+            parameters: [],
+            result: {
+                mode: 'strict',
+                typeSymbol: '@sleetdrop/dsh-plugin-topology/types#TopologyAnalysis',
+                schema: topologyAnalysisSchema,
+            },
+        },
+        {
+            id: '@sleetdrop/dsh-plugin-topology#pluginTopology/render',
+            service: 'pluginTopology',
+            namespace: 'pluginTopology',
+            method: 'render',
+            invocation: { kind: 'direct' },
+            parameters: [
+                {
+                    name: 'format',
+                    wire: 'format',
+                    source: 'json',
+                    codec: {
+                        mode: 'strict',
+                        typeSymbol: '@sleetdrop/dsh-plugin-topology/types#RenderFormat',
+                        schema: z.union([z.literal('json'), z.literal('dot'), z.literal('svg')]),
+                    },
+                },
+                {
+                    name: 'rankdir',
+                    wire: 'rankdir',
+                    source: 'json',
+                    codec: {
+                        mode: 'strict',
+                        typeSymbol: '@sleetdrop/dsh-plugin-topology/types#Rankdir',
+                        schema: z.union([z.literal('TB'), z.literal('LR')]),
+                    },
+                },
+            ],
+            result: {
+                mode: 'strict',
+                typeSymbol: '@sleetdrop/dsh-plugin-topology#pluginTopology/render:result',
+                schema: z.string(),
+            },
+        },
+    ],
+    model: {
+        services: [],
+        events: [],
+        objects: [],
+    },
+};
+export default TYPERT;

package/lib/types.d.ts

@@ -0,0 +1,126 @@
+/**
+ * JSON-safe types for the plugin topology snapshot.
+ * @module @sleetdrop/dsh-plugin-topology
+ */
+/** Plugin fiber lifecycle states, in Cordis {@link FiberState} declaration order. */
+export type PluginState = 'PENDING' | 'LOADING' | 'ACTIVE' | 'FAILED' | 'DISPOSED' | 'UNLOADING';
+/** Export format selectors for the topology renderer. */
+export type RenderFormat = 'json' | 'dot' | 'svg';
+/** Graphviz layout direction for SVG/DOT rendering. */
+export type Rankdir = 'TB' | 'LR';
+/** Node kinds in the service dependency graph. */
+export type TopologyNodeKind = 'plugin' | 'service';
+/** Edge kinds in the service dependency graph. */
+export type TopologyEdgeKind = 'provides' | 'injects';
+/** One plugin fiber (or the synthetic root) in the dependency graph. */
+export interface PluginNode {
+    /** Stable node id `p:<uid>`; the synthetic root is `p:0`. */
+    readonly id: string;
+    readonly kind: 'plugin';
+    /** Fiber display name; the synthetic root is `root`. */
+    readonly label: string;
+    /** Lifecycle state at snapshot time. */
+    readonly state: PluginState;
+    /** Node id of the fiber that mounted this one; `null` for the root. */
+    readonly parent: string | null;
+    /** Service names this fiber declares it injects. */
+    readonly inject: string[];
+    /** Module specifier the loader imported this plugin from; absent for programmatic mounts. */
+    readonly source?: string;
+}
+/** One provided service in the dependency graph. */
+export interface ServiceNode {
+    /** Stable node id `s:<scope>:<name>`. */
+    readonly id: string;
+    readonly kind: 'service';
+    /** Service name. */
+    readonly label: string;
+    /** Isolation scope discriminator: `root` or `isolate-<n>`. */
+    readonly scope: string;
+}
+export type TopologyNode = PluginNode | ServiceNode;
+/** A directed edge in the service dependency graph. */
+export interface TopologyEdge {
+    readonly source: string;
+    readonly target: string;
+    readonly kind: TopologyEdgeKind;
+    /** Service name the edge crosses. */
+    readonly service: string;
+}
+/** A declared inject with no resolvable provider at snapshot time. */
+export interface UnresolvedDependency {
+    /** Plugin node id that declared the dependency. */
+    readonly plugin: string;
+    /** Service name that had no active provider. */
+    readonly service: string;
+    /** Plugin lifecycle state at snapshot time. */
+    readonly state: PluginState;
+}
+/** A point-in-time snapshot of the runtime plugin topology. */
+export interface TopologyGraph {
+    /** Fixed discriminator; the snapshot is always the bipartite service graph. */
+    readonly kind: 'bipartite';
+    /** ISO timestamp of the capture. */
+    readonly generatedAt: string;
+    readonly nodes: TopologyNode[];
+    readonly edges: TopologyEdge[];
+    readonly unresolved: UnresolvedDependency[];
+}
+/** One plugin-to-plugin dependency edge in the collapsed projection. */
+export interface DependencyEdge {
+    /** Consumer plugin id; it depends on `target`. */
+    readonly source: string;
+    /** Provider plugin id; it is depended on by `source`. */
+    readonly target: string;
+    /** Service name that mediates the dependency. */
+    readonly service: string;
+}
+/** Plugin-only projection of the dependency graph. */
+export interface CollapsedGraph {
+    readonly kind: 'collapsed';
+    readonly generatedAt: string;
+    readonly nodes: PluginNode[];
+    readonly edges: DependencyEdge[];
+}
+/** Graph-theory metrics for one plugin node in the collapsed graph. */
+export interface NodeMetrics {
+    /** Number of plugins that depend on this one. */
+    readonly inDegree: number;
+    /** Number of plugins this one depends on. */
+    readonly outDegree: number;
+    /** `(inDegree + outDegree)` normalized by `2 * (n - 1)`. */
+    readonly degreeCentrality: number;
+    /** Unweighted directed betweenness centrality. */
+    readonly betweennessCentrality: number;
+    /** Eigenvector centrality from in-neighbors; 0 on an acyclic graph. */
+    readonly eigenvectorCentrality: number;
+    /** PageRank from in-neighbors with damping 0.85. */
+    readonly pagerank: number;
+}
+/** Aggregate metrics over the collapsed plugin graph. */
+export interface GraphMetrics {
+    readonly nodeCount: number;
+    /** Unique plugin dependency pairs, deduplicating service-mediated repeats. */
+    readonly edgeCount: number;
+    readonly density: number;
+    readonly stronglyConnectedComponents: number;
+    readonly largestSccSize: number;
+    /** True when every node is its own strongly connected component. */
+    readonly isDag: boolean;
+    readonly weaklyConnectedComponents: number;
+    /** Largest finite shortest-path length; unreachable pairs are excluded. */
+    readonly diameter: number;
+    /** Mean finite shortest-path length over reachable pairs. */
+    readonly averagePathLength: number;
+    /** Nodes that depend on nothing. */
+    readonly sourceCount: number;
+    /** Nodes nothing depends on. */
+    readonly sinkCount: number;
+}
+/** Snapshot plus its graph-theory analysis. */
+export interface TopologyAnalysis {
+    readonly graph: TopologyGraph;
+    readonly collapsed: CollapsedGraph;
+    readonly nodeMetrics: Record<string, NodeMetrics>;
+    readonly graphMetrics: GraphMetrics;
+}

package/lib/types.js

@@ -0,0 +1,5 @@
+/**
+ * JSON-safe types for the plugin topology snapshot.
+ * @module @sleetdrop/dsh-plugin-topology
+ */
+export {};

package/overlay.example.yml

@@ -0,0 +1,19 @@
+# Node-half only overlay for `dsh --profile <name> --patch <this file>`.
+# Use this to test the `graph.render` tool and the host dependency service
+# WITHOUT installing the bundle into a profile (the browser panel needs the
+# web profile; see README "Local development").
+#
+# Copy this to overlay.yml and replace the path with the absolute path to this
+# checkout's built node entry. Build first:
+#
+#   pnpm install && pnpm build
+#   cp overlay.example.yml overlay.yml   # then edit the name below
+#   dsh --profile headless --patch ./overlay.yml "render the plugin topology as json"
+#
+- insert:
+    - id: plugin-topology
+      name: /absolute/path/to/dsh-plugin-topology/lib/index.js
+
+- insert:
+    - id: tool-plugin-topology
+      name: /absolute/path/to/dsh-plugin-topology/lib/tool.js

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "@sleetdrop/dsh-plugin-topology",
+  "version": "0.1.0",
+  "description": "Plugin dependency graph inspector for DeepSeek Harness: a host service that snapshots the live Cordis plugin fiber tree, a graph.render tool for the model, and a browser panel that renders the plugin/service topology as a zoomable graph with metrics, legend, and unresolved-dependency table.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sleetdrop/dsh-plugin-topology.git"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh-plugin",
+    "plugin-topology",
+    "cordis",
+    "graphviz"
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./types": {
+      "types": "./lib/types.d.ts",
+      "default": "./lib/types.js"
+    },
+    "./package.json": "./package.json",
+    "./tool": {
+      "types": "./lib/tool.d.ts",
+      "default": "./lib/tool.js"
+    },
+    "./remote": {
+      "types": "./lib/client/remote-client.d.ts",
+      "default": "./lib/client/remote-client.js"
+    },
+    "./typert": {
+      "types": "./lib/typert.d.ts",
+      "default": "./lib/typert.js"
+    }
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "overlay.example.yml",
+    "NEXT-STEPS.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-api-remotes",
+        "@deepseek-ai/dsh-client-ui-sidebar"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-api-remotes": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-sidebar": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-api-remotes": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-locale": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-runtime": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-sidebar": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "0.1.1-rc.2",
+    "@types/node": "^24.0.0",
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "tsdown": "^0.15.0",
+    "typescript": "^5.8.0",
+    "lightningcss": "1.32.0",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.1-rc.2"
+  },
+  "dependencies": {
+    "@hpcc-js/wasm-graphviz": "^1.28.0",
+    "zod": "^4.4.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "scripts": {
+    "build": "tsc && tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsc -p tsconfig.test.json && node --test 'lib-test/test/*.test.js'"
+  }
+}