@unified-product-graph/cloud-server 0.8.5 → 0.8.7

package/CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to `@unified-product-graph/cloud-server` are documented in t
 
 This package co-versions with `@unified-product-graph/core` and `@unified-product-graph/mcp-server`. One version line covers the spec and both reference implementations.
 
+## 0.8.7 · 2026-06-03 · Consolidation + QA train
+
+Co-version with the `@unified-product-graph/*` 0.8.7 release train (framework-surface consolidation + `scoring_lens`, CLI hardening, cross-surface QA, led by `core`/`cli`/`mcp-server`; folds the 0.8.6 train). No cloud-server surface change; co-versioned for a clean install matrix.
+
 ## 0.8.5 · 2026-06-02 · Field-report fast-follow
 
 Co-version with the `@unified-product-graph/*` 0.8.5 fast-follow (skill_audit source resolution + CLI/docs consistency + npx-cache fix, led by `cli`/`mcp-server`). No cloud-server surface change; co-versioned for a clean install matrix.

package/dist/index.js

@@ -386,14 +386,14 @@ var UPGPgStore = class _UPGPgStore {
   // ── Edges ──────────────────────────────────────────────────────────────────
   async getAllEdges(productId) {
     const { rows } = await this.pool.query(
-      `SELECT id, source, target, type FROM upg.edges WHERE product_id = $1`,
+      `SELECT id, source, target, type, properties FROM upg.edges WHERE product_id = $1`,
       [productId]
     );
     return rows.map(rowToEdge);
   }
   async getEdgesForNode(nodeId2) {
     const { rows } = await this.pool.query(
-      `SELECT id, source, target, type FROM upg.edges
+      `SELECT id, source, target, type, properties FROM upg.edges
        WHERE source = $1 OR target = $1`,
       [nodeId2]
     );
@@ -405,9 +405,16 @@ var UPGPgStore = class _UPGPgStore {
     try {
       await client.query("BEGIN");
       await client.query(
-        `INSERT INTO upg.edges (id, product_id, source, target, type)
-         VALUES ($1, $2, $3, $4, $5)`,
-        [id, productId, edge.source, edge.target, edge.type]
+        `INSERT INTO upg.edges (id, product_id, source, target, type, properties)
+         VALUES ($1, $2, $3, $4, $5, $6)`,
+        [
+          id,
+          productId,
+          edge.source,
+          edge.target,
+          edge.type,
+          edge.properties ? JSON.stringify(edge.properties) : null
+        ]
       );
       await appendAudit(client, {
         productId,
@@ -431,7 +438,7 @@ var UPGPgStore = class _UPGPgStore {
       await client.query("BEGIN");
       const { rows } = await client.query(
         `DELETE FROM upg.edges WHERE id = $1
-         RETURNING id, product_id, source, target, type`,
+         RETURNING id, product_id, source, target, type, properties`,
         [id]
       );
       if (rows.length === 0) {
@@ -455,6 +462,46 @@ var UPGPgStore = class _UPGPgStore {
       client.release();
     }
   }
+  /**
+   * Set (or merge) the gated `properties` payload on a single edge (0.8.6
+   * framework-exercise parity). Merge is the default: the supplied keys are
+   * deep-merged at the top level via JSONB `||`; pass `{ merge: false }` to
+   * replace the payload wholesale. Mirrors the local SDK's `setEdgeProperties`.
+   */
+  async setEdgeProperties(id, values, opts = {}) {
+    const merge = opts.merge !== false;
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      const sql = merge ? `UPDATE upg.edges
+             SET properties = COALESCE(properties, '{}'::jsonb) || $1::jsonb
+           WHERE id = $2
+           RETURNING id, product_id, source, target, type, properties` : `UPDATE upg.edges
+             SET properties = $1::jsonb
+           WHERE id = $2
+           RETURNING id, product_id, source, target, type, properties`;
+      const { rows } = await client.query(sql, [JSON.stringify(values), id]);
+      if (rows.length === 0) {
+        await client.query("ROLLBACK");
+        throw new Error(`Edge not found: ${id}`);
+      }
+      await appendAudit(client, {
+        productId: rows[0].product_id,
+        action: "update",
+        entityType: "edge",
+        entityId: id,
+        changes: values
+      });
+      await client.query("COMMIT");
+      this.emit(rows[0].product_id, "edge.updated", { id, properties: values });
+      return rowToEdge(rows[0]);
+    } catch (err) {
+      await client.query("ROLLBACK");
+      throw err;
+    } finally {
+      client.release();
+    }
+  }
   // ── Edge utilities ─────────────────────────────────────
   /**
    * Flat enumeration of all edges for a product, optionally filtered by type.
@@ -861,7 +908,9 @@ function rowToNode(row) {
   return node;
 }
 function rowToEdge(row) {
-  return { id: row.id, source: row.source, target: row.target, type: row.type };
+  const edge = { id: row.id, source: row.source, target: row.target, type: row.type };
+  if (row.properties != null) edge.properties = row.properties;
+  return edge;
 }
 
 // src/lib/webhook-dispatcher.ts
@@ -1740,6 +1789,120 @@ var renameEdgeType = async (args, { store }) => {
   }
 };
 
+// src/tools/frameworks.ts
+import { UPG_FRAMEWORKS_BY_ID } from "@unified-product-graph/core";
+import {
+  frameworkInputKeys,
+  FRAMEWORK_EXERCISE_INCLUDES_EDGE
+} from "@unified-product-graph/sdk";
+var applyFramework = async (args, { store }) => {
+  if (!args.product_id) return textError("Missing required parameter: product_id");
+  const frameworkId = args.framework_id;
+  if (!frameworkId) {
+    return textError('Missing required parameter: framework_id (e.g. "moscow", "rice-scoring")');
+  }
+  const framework = UPG_FRAMEWORKS_BY_ID[frameworkId];
+  if (!framework) {
+    return textError(
+      `Unknown framework: "${frameworkId}". Pass a framework id from the catalog (e.g. 'moscow', 'rice-scoring', 'kano-model').`
+    );
+  }
+  const productId = args.product_id;
+  const warnings = [];
+  try {
+    const exercise = await store.addNode(productId, {
+      id: nodeId(),
+      type: "framework_exercise",
+      title: args.title ?? `${framework.name} exercise`,
+      status: args.status ?? "draft",
+      properties: { framework_id: frameworkId }
+    });
+    const included = [];
+    for (const entityId of args.entity_ids ?? []) {
+      const target = await store.getNode(entityId);
+      if (!target) {
+        warnings.push(`Could not include ${entityId}: target not found`);
+        continue;
+      }
+      const edge = {
+        id: edgeId(),
+        source: exercise.id,
+        target: entityId,
+        type: FRAMEWORK_EXERCISE_INCLUDES_EDGE
+      };
+      try {
+        await store.addEdge(productId, edge);
+        included.push({ edge_id: edge.id, entity_id: entityId });
+      } catch (err) {
+        warnings.push(`Could not include ${entityId}: ${err.message}`);
+      }
+    }
+    return text(
+      JSON.stringify(
+        { exercise_id: exercise.id, exercise, included, warnings },
+        null,
+        2
+      )
+    );
+  } catch (err) {
+    return textError(err.message);
+  }
+};
+var scoreEntity = async (args, { store }) => {
+  const exerciseId = args.exercise_id;
+  const entityId = args.entity_id;
+  const values = args.values;
+  if (!exerciseId) return textError("Missing required parameter: exercise_id");
+  if (!entityId) return textError("Missing required parameter: entity_id");
+  if (!values || typeof values !== "object" || Array.isArray(values)) {
+    return textError(
+      'Missing required parameter: values (object of input \u2192 value, e.g. { "moscow": "must" })'
+    );
+  }
+  const exercise = await store.getNode(exerciseId);
+  if (!exercise) return textError(`Exercise not found: ${exerciseId}`);
+  if (exercise.type !== "framework_exercise") {
+    return textError(`Node ${exerciseId} is a ${exercise.type}, not a framework_exercise.`);
+  }
+  const warnings = [];
+  const frameworkId = exercise.properties?.framework_id;
+  const framework = frameworkId ? UPG_FRAMEWORKS_BY_ID[frameworkId] : void 0;
+  if (framework) {
+    const known = new Set(frameworkInputKeys(framework));
+    if (known.size > 0) {
+      const unknown = Object.keys(values).filter((k) => !known.has(k));
+      if (unknown.length > 0) {
+        warnings.push(
+          `Value key(s) not declared by ${frameworkId}: ${unknown.join(", ")}. Stored anyway (permissive).`
+        );
+      }
+    }
+  }
+  try {
+    const edges = await store.getEdgesForNode(exerciseId);
+    const existing = edges.find(
+      (e) => e.type === FRAMEWORK_EXERCISE_INCLUDES_EDGE && e.source === exerciseId && e.target === entityId
+    );
+    if (existing) {
+      const edge2 = await store.setEdgeProperties(existing.id, values, { merge: !args.replace });
+      return text(JSON.stringify({ edge: edge2, warnings }, null, 2));
+    }
+    const target = await store.getNode(entityId);
+    if (!target) return textError(`Entity not found: ${entityId}`);
+    const edge = {
+      id: edgeId(),
+      source: exerciseId,
+      target: entityId,
+      type: FRAMEWORK_EXERCISE_INCLUDES_EDGE,
+      properties: values
+    };
+    await store.addEdge(exercise.product_id, edge);
+    return text(JSON.stringify({ edge, warnings }, null, 2));
+  } catch (err) {
+    return textError(err.message);
+  }
+};
+
 // src/tools/areas.ts
 var listProductAreas = async (args, { store }) => {
   if (!args.product_id) return textError(`Missing required parameter: product_id`);
@@ -1916,7 +2079,7 @@ import {
   UPG_DOMAIN_GUIDES,
   UPG_DOMAINS,
   UPG_FRAMEWORKS,
-  UPG_FRAMEWORKS_BY_ID,
+  UPG_FRAMEWORKS_BY_ID as UPG_FRAMEWORKS_BY_ID2,
   UPG_EDGE_CATALOG as UPG_EDGE_CATALOG2,
   UPG_REGIONS,
   UPG_REGION_MAP,
@@ -2061,7 +2224,7 @@ var prioritise = (args) => {
       'Missing required parameter: framework_id (e.g. "rice-scoring", "ice-scoring", "kano-model")'
     );
   }
-  const framework = UPG_FRAMEWORKS_BY_ID[frameworkId];
+  const framework = UPG_FRAMEWORKS_BY_ID2[frameworkId];
   return approachEnvelope("prioritise", candidates, {
     params: { candidates, framework_id: frameworkId },
     framework_resolved: framework ? { id: framework.id, name: framework.name, category: framework.category } : null,
@@ -2158,7 +2321,7 @@ var listFrameworks = (args) => {
 var getFramework = (args) => {
   const id = args.id;
   if (!id) return textError("Missing required parameter: id");
-  const framework = UPG_FRAMEWORKS_BY_ID[id];
+  const framework = UPG_FRAMEWORKS_BY_ID2[id];
   if (!framework) return textError(`Unknown framework id: ${id}`);
   return text(JSON.stringify(framework, null, 2));
 };
@@ -4940,6 +5103,42 @@ var TOOL_DEFINITIONS = [
         "product_id"
       ]
     }
+  },
+  {
+    "name": "apply_framework",
+    "description": "Apply a framework (MoSCoW, RICE, Kano, ...) to a set of entities in a product: creates a framework_exercise node and an `includes` edge to each entity. The per-entity result is recorded on the edge via score_entity, never on the entity node, so the same entity can sit in many exercises and any entity type can be scored. Returns { exercise_id, exercise, included, warnings }.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "product_id": { "type": "string", "description": "Required. Product the exercise belongs to." },
+        "framework_id": { "type": "string", "description": 'Required. UPGFramework.id (e.g. "moscow", "rice-scoring").' },
+        "title": { "type": "string", "description": 'Human label for the exercise (default "<Framework> exercise").' },
+        "entity_ids": { "type": "array", "items": { "type": "string" }, "description": "Entities to pull into the exercise (any type)." },
+        "status": { "type": "string", "description": "Lifecycle phase: draft | active | archived (default draft)." }
+      },
+      "required": [
+        "product_id",
+        "framework_id"
+      ]
+    }
+  },
+  {
+    "name": "score_entity",
+    "description": "Record a framework's result for one entity on the exercise's includes edge (a MoSCoW bucket, a RICE score, a canvas slot). Auto-includes the entity if not already in scope. Merges into existing edge properties unless replace is set. The product is resolved from the exercise node. Returns { edge, warnings }.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "exercise_id": { "type": "string", "description": "Required. The framework_exercise id." },
+        "entity_id": { "type": "string", "description": "Required. The entity being scored." },
+        "values": { "type": "object", "description": 'Required. The result as { input: value }, e.g. { "moscow": "must" } or { "reach": 800, "impact": 3 }.' },
+        "replace": { "type": "boolean", "description": "Replace the edge properties instead of merging (default false)." }
+      },
+      "required": [
+        "exercise_id",
+        "entity_id",
+        "values"
+      ]
+    }
   }
 ];
 var HANDLERS = {
@@ -4963,6 +5162,9 @@ var HANDLERS = {
   delete_edge: deleteEdge,
   export_edges: exportEdges,
   rename_edge_type: renameEdgeType,
+  // ── Framework exercises (0.8.6 cloud parity) ────────────────────
+  apply_framework: applyFramework,
+  score_entity: scoreEntity,
   list_product_areas: listProductAreas,
   get_area_graph: getAreaGraph,
   create_area: createArea,