@mcp-com-ai/plugin-capability-graph 0.0.0-stage → 1.3.0

package/dist/visualization-flow-cards.d.ts

@@ -0,0 +1,26 @@
+import type { CapabilityGraphOperationNode, CapabilityGraphPlanningStepV1, CapabilityGraphV1 } from "@mcp-com-ai/core";
+import type { CapabilityGraphVisualizationFlowCardsV1, CapabilityGraphVisualizationFlowInputHintV1, CapabilityGraphVisualizationFlowInputV1, CapabilityGraphVisualizationPlanTraceInputV1 } from "./visualization-types";
+/**
+ * Project a generation-time plan trace into Flow Cards: one start card, one
+ * action card per planner step in planner order, and one outcome card.
+ *
+ * Cards are derived from the trace and graph only. Dependency levels and
+ * input hints are advisory presentation; they never reorder or alter the plan.
+ */
+export declare function projectFlowCards(graph: CapabilityGraphV1, input: CapabilityGraphVisualizationPlanTraceInputV1): CapabilityGraphVisualizationFlowCardsV1;
+/**
+ * Step *j* depends on an earlier step *i* when *i* is the latest earlier
+ * producer of a fact *j* requires, when *i* removes a fact *j* requires or
+ * produces, or when *j* removes a fact *i* requires or produces. A fact no earlier step
+ * produced came from the initial state and creates no dependency.
+ */
+export declare function stepDependencies(steps: readonly CapabilityGraphPlanningStepV1[]): number[][];
+export declare function dependencyLevels(dependencies: readonly number[][]): number[];
+/**
+ * Advisory required-input hint for an operation step. Inputs count as
+ * possibly linked when an earlier step's operation has a planning-eligible
+ * operation link to this operation; which parameters it maps is unknown.
+ */
+export declare function flowInputHint(graph: CapabilityGraphV1, steps: readonly CapabilityGraphPlanningStepV1[], step: CapabilityGraphPlanningStepV1, operations: ReadonlyMap<string, CapabilityGraphOperationNode>): CapabilityGraphVisualizationFlowInputHintV1 | undefined;
+/** Required parameters and required body property names; never credentials. */
+export declare function requiredInputs(operation: CapabilityGraphOperationNode): CapabilityGraphVisualizationFlowInputV1[];

package/dist/visualization-renderer.d.ts

@@ -0,0 +1,2 @@
+import { type CapabilityGraphVisualizationDocumentV1, type CapabilityGraphVisualizationRenderOptions } from "./visualization-types";
+export declare function renderCapabilityGraphVisualizationHtml(document: CapabilityGraphVisualizationDocumentV1, options?: CapabilityGraphVisualizationRenderOptions): Promise<string>;

package/dist/visualization-shared.d.ts

@@ -0,0 +1,7 @@
+import type { PlanningFactV1 } from "@mcp-com-ai/core";
+/** Helpers shared by the pure visualization projections. */
+export declare function isTechnicalFact(fact: PlanningFactV1): boolean;
+export declare function factKey(fact: PlanningFactV1): string;
+export declare function copyFact(fact: PlanningFactV1): PlanningFactV1;
+export declare function domId(identity: string): string;
+export declare function searchText(values: readonly unknown[]): string;

package/dist/visualization-types.d.ts

@@ -0,0 +1,343 @@
+import type { CapabilityGraphAuthorizationRequirement, CapabilityGraphBodyVariant, CapabilityGraphDiagnostic, CapabilityGraphEffects, CapabilityGraphInputDescriptor, CapabilityGraphOperationProvenance, CapabilityGraphOutputDescriptor, CapabilityGraphPlanningGateV1, CapabilityGraphPlanningOutcome, CapabilityGraphPlanningResultV1, CapabilityGraphPlanningStepV1, CapabilityGraphPlanningTransitionSourceV1, CapabilityGraphProvenance, CapabilityGraphSource, PlanningFactV1 } from "@mcp-com-ai/core";
+import type { CapabilityGraphFactClosureV1, CapabilityGraphFactFindingV1 } from "./fact-closure";
+type CapabilityGraphDiagnosticSeverity = CapabilityGraphDiagnostic["severity"];
+export declare const CAPABILITY_GRAPH_VISUALIZATION_LIMITS: Readonly<{
+    maxInputBytes: number;
+    maxNodes: 5000;
+    maxEdges: 20000;
+    maxPlanningTransitions: 10000;
+    maxPlanningFacts: 10000;
+    maxStateRelations: 50000;
+    maxPlanTraceSteps: 1000;
+    maxDiagnostics: 2000;
+    maxOutputBytes: number;
+}>;
+export type CapabilityGraphVisualizationLimitName = keyof typeof CAPABILITY_GRAPH_VISUALIZATION_LIMITS;
+export interface CapabilityGraphVisualizationLimitsV1 {
+    readonly maxInputBytes: number;
+    readonly maxNodes: number;
+    readonly maxEdges: number;
+    readonly maxPlanningTransitions: number;
+    readonly maxPlanningFacts: number;
+    readonly maxStateRelations: number;
+    readonly maxPlanTraceSteps: number;
+    readonly maxDiagnostics: number;
+    readonly maxOutputBytes: number;
+}
+export type CapabilityGraphVisualizationNodeKind = "capability" | "operation";
+export type CapabilityGraphVisualizationItemKind = CapabilityGraphVisualizationNodeKind | "edge" | "transition" | "fact" | "plan-state" | "flow-card" | "diagnostic";
+export interface CapabilityGraphVisualizationPointV1 {
+    readonly x: number;
+    readonly y: number;
+}
+export interface CapabilityGraphVisualizationNodeV1 {
+    readonly identity: string;
+    readonly graphId: string;
+    readonly domId: string;
+    readonly kind: CapabilityGraphVisualizationNodeKind;
+    readonly label: string;
+    readonly searchText: string;
+    readonly position: CapabilityGraphVisualizationPointV1;
+    readonly relatedIdentities: readonly string[];
+    readonly taxonomy: readonly string[];
+    readonly provenance: CapabilityGraphProvenance;
+    readonly description?: string;
+    readonly purpose?: string;
+    readonly method?: string;
+    readonly path?: string;
+    readonly useWhen?: readonly string[];
+    readonly avoidWhen?: readonly string[];
+    readonly inputs?: readonly CapabilityGraphInputDescriptor[];
+    readonly bodyVariants?: readonly CapabilityGraphBodyVariant[];
+    readonly outputs?: readonly CapabilityGraphOutputDescriptor[];
+    readonly effects?: CapabilityGraphEffects;
+    readonly authorization?: readonly CapabilityGraphAuthorizationRequirement[];
+    readonly prerequisites?: readonly string[];
+    readonly fieldProvenance?: CapabilityGraphOperationProvenance;
+}
+export interface CapabilityGraphVisualizationEdgeV1 {
+    readonly identity: string;
+    readonly graphId: string;
+    readonly domId: string;
+    readonly type: "capability-operation" | "operation-link";
+    readonly sourceIdentity: string;
+    readonly targetIdentity: string;
+    readonly path: string;
+    readonly label?: string;
+    readonly planningEligible: boolean;
+    readonly provenance: CapabilityGraphProvenance;
+}
+export interface CapabilityGraphVisualizationTransitionV1 {
+    readonly identity: string;
+    readonly graphId: string;
+    readonly domId: string;
+    readonly target: {
+        readonly kind: "operation" | "workflow";
+        readonly id: string;
+    };
+    readonly requires: readonly PlanningFactV1[];
+    readonly produces: readonly PlanningFactV1[];
+    readonly removes: readonly PlanningFactV1[];
+    readonly cost: number;
+    readonly gates: readonly CapabilityGraphPlanningGateV1[];
+    readonly sources: readonly CapabilityGraphPlanningTransitionSourceV1[];
+    readonly searchText: string;
+}
+export type CapabilityGraphVisualizationStateRelationKind = "requires" | "produces" | "removes";
+export interface CapabilityGraphVisualizationFactNodeV1 {
+    readonly identity: string;
+    readonly domId: string;
+    readonly fact: PlanningFactV1;
+    readonly label: string;
+    readonly technical: boolean;
+    readonly position: CapabilityGraphVisualizationPointV1;
+    readonly producerIdentities: readonly string[];
+    readonly consumerIdentities: readonly string[];
+    readonly removerIdentities: readonly string[];
+    readonly searchText: string;
+}
+export interface CapabilityGraphVisualizationStateTransitionNodeV1 {
+    readonly identity: string;
+    readonly domId: string;
+    readonly transitionIdentity: string;
+    readonly label: string;
+    readonly position: CapabilityGraphVisualizationPointV1;
+    readonly searchText: string;
+}
+export interface CapabilityGraphVisualizationStateRelationV1 {
+    readonly identity: string;
+    readonly domId: string;
+    readonly kind: CapabilityGraphVisualizationStateRelationKind;
+    readonly factIdentity: string;
+    readonly transitionIdentity: string;
+    readonly sourceIdentity: string;
+    readonly targetIdentity: string;
+    readonly path: string;
+    readonly sources: readonly CapabilityGraphPlanningTransitionSourceV1[];
+}
+export interface CapabilityGraphVisualizationBusinessStatesV1 {
+    readonly schemaVersion: "1";
+    readonly facts: readonly CapabilityGraphVisualizationFactNodeV1[];
+    readonly transitions: readonly CapabilityGraphVisualizationStateTransitionNodeV1[];
+    readonly relations: readonly CapabilityGraphVisualizationStateRelationV1[];
+    readonly layout: CapabilityGraphVisualizationLayoutV1;
+    readonly counts: {
+        readonly facts: number;
+        readonly businessFacts: number;
+        readonly technicalFacts: number;
+        readonly relations: number;
+    };
+}
+export interface CapabilityGraphVisualizationPlanStateV1 {
+    readonly identity: string;
+    readonly domId: string;
+    readonly index: number;
+    readonly label: string;
+    readonly facts: readonly PlanningFactV1[];
+    readonly added: readonly PlanningFactV1[];
+    readonly removed: readonly PlanningFactV1[];
+    readonly transitionId?: string;
+    readonly target?: CapabilityGraphPlanningStepV1["target"];
+}
+export interface CapabilityGraphVisualizationPlanTraceV1 {
+    readonly schemaVersion: "1";
+    readonly outcome: CapabilityGraphPlanningOutcome;
+    readonly graphFingerprint: string;
+    readonly initialFacts: readonly PlanningFactV1[];
+    readonly goalFacts: readonly PlanningFactV1[];
+    readonly totalCost: number;
+    readonly states: readonly CapabilityGraphVisualizationPlanStateV1[];
+    readonly unsatisfiedGates: readonly CapabilityGraphPlanningGateV1[];
+    readonly diagnostics: readonly CapabilityGraphDiagnostic[];
+}
+export interface CapabilityGraphVisualizationPlanTraceInputV1 {
+    readonly initialFacts: readonly PlanningFactV1[];
+    readonly goalFacts: readonly PlanningFactV1[];
+    readonly result: CapabilityGraphPlanningResultV1;
+    /**
+     * Gate codes supplied to the planner. When present with `principalSupplied`,
+     * Flow Cards attribute waits to exact steps; otherwise they fall back to
+     * matching the result's unsatisfied gates.
+     */
+    readonly satisfiedGates?: readonly string[];
+    readonly principalSupplied?: boolean;
+}
+export type CapabilityGraphVisualizationFlowCardKind = "start" | "action" | "outcome";
+export interface CapabilityGraphVisualizationFlowWaitV1 {
+    readonly kind: CapabilityGraphPlanningGateV1["kind"];
+    readonly code: string;
+    readonly detail?: string;
+}
+export interface CapabilityGraphVisualizationFlowOtherwiseV1 {
+    readonly status: string;
+    readonly produces: readonly PlanningFactV1[];
+    readonly removes: readonly PlanningFactV1[];
+}
+export interface CapabilityGraphVisualizationFlowInputV1 {
+    readonly name: string;
+    readonly location: string;
+}
+export interface CapabilityGraphVisualizationFlowLinkSourceV1 {
+    readonly edgeIdentity: string;
+    readonly fromStep: number;
+    readonly label?: string;
+}
+/**
+ * Advisory required-input hint. Never a planning gate and never a claim about
+ * which parameter a Link maps: V1 graphs do not retain Link mappings.
+ */
+export interface CapabilityGraphVisualizationFlowInputHintV1 {
+    readonly status: "needs-input" | "may-be-linked";
+    readonly inputs: readonly CapabilityGraphVisualizationFlowInputV1[];
+    readonly links: readonly CapabilityGraphVisualizationFlowLinkSourceV1[];
+}
+/** Allowlisted declared event; descriptive only. */
+export interface CapabilityGraphVisualizationTriggerV1 {
+    readonly id: string;
+    readonly kind: "webhook" | "callback";
+    readonly name: string;
+    readonly method: string;
+    readonly expression?: string;
+    readonly operationId?: string;
+    readonly purpose: string;
+    readonly produces: readonly PlanningFactV1[];
+}
+export interface CapabilityGraphVisualizationFlowCardV1 {
+    readonly identity: string;
+    readonly domId: string;
+    readonly kind: CapabilityGraphVisualizationFlowCardKind;
+    readonly label: string;
+    /** One-based planner step number for action cards. */
+    readonly step?: number;
+    /** Dependency level derived from declared facts; action cards only. */
+    readonly level?: number;
+    readonly dependsOn: readonly string[];
+    readonly transitionId?: string;
+    readonly target?: CapabilityGraphPlanningStepV1["target"];
+    readonly effectMode?: string;
+    readonly purpose?: string;
+    readonly requires: readonly PlanningFactV1[];
+    readonly produces: readonly PlanningFactV1[];
+    readonly removes: readonly PlanningFactV1[];
+    readonly waits: readonly CapabilityGraphVisualizationFlowWaitV1[];
+    /** Declared response outcomes shown as "Otherwise" branches; never planned. */
+    readonly otherwise?: readonly CapabilityGraphVisualizationFlowOtherwiseV1[];
+    readonly inputHint?: CapabilityGraphVisualizationFlowInputHintV1;
+    readonly initialFacts?: readonly PlanningFactV1[];
+    readonly goalFacts?: readonly PlanningFactV1[];
+    /** Start card only: declared triggers that signal an initial fact. */
+    readonly triggerIds?: readonly string[];
+    readonly outcome?: CapabilityGraphPlanningOutcome;
+    readonly diagnosticCodes?: readonly string[];
+    readonly searchText: string;
+}
+export interface CapabilityGraphVisualizationFlowCardsV1 {
+    readonly schemaVersion: "1";
+    readonly outcome: CapabilityGraphPlanningOutcome;
+    readonly levelCount: number;
+    readonly cards: readonly CapabilityGraphVisualizationFlowCardV1[];
+}
+export type CapabilityGraphVisualizationFactFindingV1 = CapabilityGraphFactFindingV1;
+/** Static fact-closure findings; no planner run is involved. */
+export type CapabilityGraphVisualizationFactAuditV1 = CapabilityGraphFactClosureV1;
+export declare const CAPABILITY_GRAPH_VISUALIZATION_VIEWS: readonly ["topology", "business-states", "planning", "plan-trace", "flow-cards"];
+export type CapabilityGraphVisualizationViewName = (typeof CAPABILITY_GRAPH_VISUALIZATION_VIEWS)[number];
+export interface CapabilityGraphVisualizationDiagnosticV1 {
+    readonly identity: string;
+    readonly domId: string;
+    readonly code: string;
+    readonly severity: CapabilityGraphDiagnosticSeverity;
+    readonly message: string;
+    readonly pointer?: string;
+    readonly operationIdentity?: string;
+}
+export interface CapabilityGraphVisualizationFilterValuesV1 {
+    readonly taxonomy: readonly string[];
+    readonly methods: readonly string[];
+    readonly effects: readonly string[];
+    readonly provenanceKinds: readonly string[];
+    readonly diagnosticSeverities: readonly CapabilityGraphDiagnosticSeverity[];
+    readonly edgeTypes: readonly string[];
+}
+export interface CapabilityGraphVisualizationLayoutV1 {
+    readonly width: number;
+    readonly height: number;
+    readonly nodeWidth: number;
+    readonly nodeHeight: number;
+}
+export interface CapabilityGraphVisualizationCountsV1 {
+    readonly capabilities: number;
+    readonly operations: number;
+    readonly edges: number;
+    readonly planningTransitions: number;
+    readonly planningFacts: number;
+    readonly businessFacts: number;
+    readonly technicalFacts: number;
+    readonly stateRelations: number;
+    readonly diagnostics: number;
+}
+export interface CapabilityGraphVisualizationDocumentV1 {
+    readonly schemaVersion: "1";
+    readonly graphSchemaVersion: "1";
+    readonly graphFingerprint: string;
+    readonly source: CapabilityGraphSource;
+    readonly counts: CapabilityGraphVisualizationCountsV1;
+    readonly layout: CapabilityGraphVisualizationLayoutV1;
+    readonly nodes: readonly CapabilityGraphVisualizationNodeV1[];
+    readonly edges: readonly CapabilityGraphVisualizationEdgeV1[];
+    readonly planning?: {
+        readonly schemaVersion: "1";
+        readonly transitions: readonly CapabilityGraphVisualizationTransitionV1[];
+    };
+    readonly businessStates?: CapabilityGraphVisualizationBusinessStatesV1;
+    readonly planTrace?: CapabilityGraphVisualizationPlanTraceV1;
+    readonly flowCards?: CapabilityGraphVisualizationFlowCardsV1;
+    readonly factAudit?: CapabilityGraphVisualizationFactAuditV1;
+    readonly triggers?: readonly CapabilityGraphVisualizationTriggerV1[];
+    /** Present only when explicitly requested; the viewer default is topology. */
+    readonly initialView?: CapabilityGraphVisualizationViewName;
+    readonly diagnostics: readonly CapabilityGraphVisualizationDiagnosticV1[];
+    readonly filters: CapabilityGraphVisualizationFilterValuesV1;
+}
+export interface CapabilityGraphVisualizationSelectionV1 {
+    readonly kind: CapabilityGraphVisualizationItemKind;
+    readonly identity: string;
+}
+export interface CapabilityGraphVisualizationFilterStateV1 {
+    readonly query?: string;
+    readonly nodeKind?: CapabilityGraphVisualizationNodeKind;
+    readonly taxonomy?: string;
+    readonly method?: string;
+    readonly effect?: string;
+    readonly authorization?: "required" | "none";
+    readonly provenance?: string;
+    readonly diagnosticSeverity?: CapabilityGraphDiagnosticSeverity;
+    readonly edgeType?: string;
+    readonly planningEligibility?: "eligible" | "descriptive";
+}
+export interface CapabilityGraphVisualizationRenderOptions {
+    /** Tests and embedders may lower, but never raise, compiled safety ceilings. */
+    readonly limits?: Partial<CapabilityGraphVisualizationLimitsV1>;
+    /** Optional deterministic planner result to project as an exact state trace. */
+    readonly planTrace?: CapabilityGraphVisualizationPlanTraceInputV1;
+    /** Facts established outside the API; excluded from orphan findings. */
+    readonly clientVerifiedFacts?: readonly PlanningFactV1[];
+    readonly initialView?: CapabilityGraphVisualizationViewName;
+}
+export declare class CapabilityGraphVisualizationError extends Error {
+    readonly code: string;
+    readonly details?: Readonly<{
+        limit?: CapabilityGraphVisualizationLimitName;
+        count?: number;
+        maximum?: number;
+        path?: string;
+    }> | undefined;
+    constructor(code: string, message: string, details?: Readonly<{
+        limit?: CapabilityGraphVisualizationLimitName;
+        count?: number;
+        maximum?: number;
+        path?: string;
+    }> | undefined);
+}
+export declare function visualizationFactText(fact: PlanningFactV1): string;
+export {};

package/dist/visualization.d.ts

@@ -0,0 +1,3 @@
+import { type CapabilityGraphVisualizationDocumentV1, type CapabilityGraphVisualizationLimitsV1, type CapabilityGraphVisualizationRenderOptions } from "./visualization-types";
+export declare function projectCapabilityGraphVisualization(value: unknown, options?: CapabilityGraphVisualizationRenderOptions): CapabilityGraphVisualizationDocumentV1;
+export declare function effectiveVisualizationLimits(requested?: Partial<CapabilityGraphVisualizationLimitsV1>): CapabilityGraphVisualizationLimitsV1;

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@mcp-com-ai/plugin-capability-graph",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.3.0",
+  "description": "Compile OpenAPI documents into deterministic HAPI capability graphs.",
+  "license": "LRL-CL",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mcp-com-ai/hapimcp"
+  },
+  "homepage": "https://hapi.mcp.com.ai",
+  "bugs": {
+    "url": "https://github.com/mcp-com-ai/hapimcp"
+  },
+  "sponsor": {
+    "url": "https://go.rebelion.la/sponsors"
+  },
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "hapi-build-source": "./src/index.ts",
+      "bun": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "hapi-build-source": "./src/runtime.ts",
+      "bun": "./dist/runtime.js",
+      "default": "./dist/runtime.js"
+    },
+    "./visualization": {
+      "types": "./dist/visualization-api.d.ts",
+      "hapi-build-source": "./src/visualization-api.ts",
+      "bun": "./dist/visualization-api.js",
+      "default": "./dist/visualization-api.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test",
+    "build": "bun ../../../scripts/build-package.ts ."
+  },
+  "dependencies": {
+    "@mcp-com-ai/core": "^1.1.0",
+    "@mcp-com-ai/plugin-sdk": "^1.1.0",
+    "yaml": "^2.8.2"
+  },
+  "keywords": [
+    "hapi",
+    "hapi-cli-plugin",
+    "openapi",
+    "capability-graph",
+    "mcp"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}