@principal-ai/principal-studio-cli 0.37.1 → 0.38.0

package/dist/commands/subsystem-model.js

@@ -152,8 +152,8 @@ async function createAction(options) {
             title: body['title'],
             description: typeof body['description'] === 'string' ? body['description'] : undefined,
             components: body['components'],
-            edges: body['edges'],
-            throughlines: Array.isArray(body['throughlines']) ? body['throughlines'] : undefined,
+            relations: body['relations'],
+            walkthroughs: Array.isArray(body['walkthroughs']) ? body['walkthroughs'] : undefined,
             source: typeof body['source'] === 'string' ? body['source'] : undefined,
             repo: body['repo'],
             repoRoot: typeof body['repoRoot'] === 'string' ? body['repoRoot'] : undefined,

package/dist/index.cjs

@@ -3457,29 +3457,63 @@ var require_subsystem_model = __commonJS({
   "node_modules/@principal-ai/subsystems-core/dist/types/subsystem-model.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    exports2.toPortableDocument = exports2.isSubsystemModelDocument = void 0;
+    exports2.deriveGraphEdges = exports2.derivedGraphEdgeId = exports2.toPortableDocument = exports2.isSubsystemModelDocument = void 0;
     function isSubsystemModelDocument(value) {
       if (!value || typeof value !== "object")
         return false;
       const v = value;
-      return typeof v.title === "string" && Array.isArray(v.components) && Array.isArray(v.edges);
+      return typeof v.title === "string" && Array.isArray(v.components) && Array.isArray(v.relations);
     }
     exports2.isSubsystemModelDocument = isSubsystemModelDocument;
     function toPortableDocument(doc) {
       const out = {
         title: doc.title,
         components: doc.components,
-        edges: doc.edges
+        relations: doc.relations
       };
       if (doc.$schema)
         out.$schema = doc.$schema;
       if (doc.description)
         out.description = doc.description;
-      if (doc.throughlines)
-        out.throughlines = doc.throughlines;
+      if (doc.walkthroughs)
+        out.walkthroughs = doc.walkthroughs;
       return out;
     }
     exports2.toPortableDocument = toPortableDocument;
+    function derivedGraphEdgeId(from, to, mechanism) {
+      return `${from}--${mechanism}-->${to}`;
+    }
+    exports2.derivedGraphEdgeId = derivedGraphEdgeId;
+    function deriveGraphEdges2(doc) {
+      const byId = /* @__PURE__ */ new Map();
+      for (const r of doc.relations ?? []) {
+        const id = r.id || derivedGraphEdgeId(r.from, r.to, r.relationType);
+        if (!byId.has(id)) {
+          byId.set(id, {
+            id,
+            from: r.from,
+            to: r.to,
+            mechanism: r.relationType,
+            refs: r.refs
+          });
+        }
+      }
+      for (const w of doc.walkthroughs ?? []) {
+        for (const step of w.steps) {
+          const id = derivedGraphEdgeId(step.from, step.to, step.mechanism);
+          if (!byId.has(id)) {
+            byId.set(id, {
+              id,
+              from: step.from,
+              to: step.to,
+              mechanism: step.mechanism
+            });
+          }
+        }
+      }
+      return [...byId.values()];
+    }
+    exports2.deriveGraphEdges = deriveGraphEdges2;
   }
 });
 
@@ -9790,6 +9824,31 @@ var require_node = __commonJS({
   }
 });
 
+// node_modules/@principal-ai/subsystems-core/dist/index.js
+var require_dist2 = __commonJS({
+  "node_modules/@principal-ai/subsystems-core/dist/index.js"(exports2) {
+    "use strict";
+    var __createBinding = exports2 && exports2.__createBinding || (Object.create ? function(o, m, k, k2) {
+      if (k2 === void 0) k2 = k;
+      var desc = Object.getOwnPropertyDescriptor(m, k);
+      if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+        desc = { enumerable: true, get: function() {
+          return m[k];
+        } };
+      }
+      Object.defineProperty(o, k2, desc);
+    } : function(o, m, k, k2) {
+      if (k2 === void 0) k2 = k;
+      o[k2] = m[k];
+    });
+    var __exportStar = exports2 && exports2.__exportStar || function(m, exports3) {
+      for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports3, p)) __createBinding(exports3, m, p);
+    };
+    Object.defineProperty(exports2, "__esModule", { value: true });
+    __exportStar(require_types(), exports2);
+  }
+});
+
 // node_modules/commander/esm.mjs
 var import_index = __toESM(require_commander(), 1);
 var {
@@ -15379,29 +15438,9 @@ var import_node_fs7 = require("node:fs");
 var import_node_fs6 = require("node:fs");
 var import_node_os6 = require("node:os");
 var import_node_path5 = require("node:path");
+var import_subsystems_core = __toESM(require_dist2(), 1);
 var ROOT3 = (0, import_node_path5.join)((0, import_node_os6.homedir)(), ".principal", "subsystem-models");
 var INDEX_PATH = (0, import_node_path5.join)(ROOT3, "_index.json");
-var SUBSYSTEM_EDGE_MECHANISMS = [
-  "imports",
-  "imports_from",
-  "re_exports",
-  "defines",
-  "calls",
-  "extends",
-  "inherits",
-  "implements",
-  "mixes_in",
-  "uses",
-  "method",
-  "references",
-  "contains",
-  "feeds",
-  "produces",
-  "writes",
-  "reads",
-  "watches",
-  "registers-into"
-];
 var SUBSYSTEM_COMPONENT_CONSTRUCTS = [
   "class",
   "function",
@@ -15413,7 +15452,7 @@ var SUBSYSTEM_COMPONENT_CONSTRUCTS = [
   "external",
   "custom_entity"
 ];
-var SUBSYSTEM_DETAIL_PROVENANCES = ["verified", "authored"];
+var SUBSYSTEM_DECLARATION_PROVENANCES = ["verified", "authored"];
 function graphId() {
   const ts = Date.now();
   const rand = Math.random().toString(36).slice(2, 11);
@@ -15428,56 +15467,84 @@ function subsystemModelFilePath(id) {
 async function ensureDir() {
   await import_node_fs6.promises.mkdir(ROOT3, { recursive: true });
 }
-function findEdgeMechanismProblems(edges) {
-  if (!Array.isArray(edges)) return [];
+var SUBSYSTEM_RELATION_TYPES = [
+  "imports",
+  "imports_from",
+  "re_exports",
+  "defines",
+  "extends",
+  "inherits",
+  "implements",
+  "mixes_in",
+  "method",
+  "references",
+  "contains"
+];
+var SUBSYSTEM_WALKTHROUGH_MECHANISMS = [
+  "calls",
+  "uses",
+  "feeds",
+  "produces",
+  "writes",
+  "reads",
+  "watches",
+  "registers-into"
+];
+function findRelationTypeProblems(relations) {
+  if (!Array.isArray(relations)) return ["relations must be an array"];
   const problems = [];
-  for (const edge of edges) {
-    const e = edge;
-    if (typeof e?.mechanism === "string" && SUBSYSTEM_EDGE_MECHANISMS.includes(e.mechanism)) {
-      continue;
+  for (const rel of relations) {
+    const r = rel;
+    if (typeof r?.id !== "string" || !r.id.trim()) {
+      problems.push(`relation ${JSON.stringify(r?.id ?? "<no id>")}: id is required`);
+    }
+    if (typeof r?.from !== "string" || !r.from.trim()) {
+      problems.push(`relation ${JSON.stringify(r?.id ?? "<no id>")}: from is required`);
+    }
+    if (typeof r?.to !== "string" || !r.to.trim()) {
+      problems.push(`relation ${JSON.stringify(r?.id ?? "<no id>")}: to is required`);
+    }
+    if (typeof r?.relationType !== "string" || !SUBSYSTEM_RELATION_TYPES.includes(r.relationType)) {
+      problems.push(
+        `relation ${JSON.stringify(r?.id ?? "<no id>")}: unknown relationType ${JSON.stringify(r?.relationType)}`
+      );
     }
-    problems.push(
-      `edge ${JSON.stringify(e?.id ?? "<no id>")}: unknown mechanism ${JSON.stringify(e?.mechanism)} \u2014 allowed: ${SUBSYSTEM_EDGE_MECHANISMS.join(", ")}`
-    );
   }
   return problems;
 }
-function findThroughlineProblems(edges, throughlines) {
-  if (throughlines === void 0) return [];
-  if (!Array.isArray(throughlines)) return ["throughlines must be an array"];
-  const edgeIds = new Set(
-    (Array.isArray(edges) ? edges : []).map((e) => e?.id).filter((id) => typeof id === "string")
-  );
+function findWalkthroughProblems(walkthroughs) {
+  if (walkthroughs === void 0) return [];
+  if (!Array.isArray(walkthroughs)) return ["walkthroughs must be an array"];
   const problems = [];
-  for (const tl of throughlines) {
-    const t = tl;
-    const label = JSON.stringify(t?.id ?? "<no id>");
-    if (typeof t?.id !== "string" || !t.id.trim()) {
-      problems.push(`throughline ${label}: id is required`);
+  for (const wt of walkthroughs) {
+    const w = wt;
+    const label = JSON.stringify(w?.id ?? "<no id>");
+    if (typeof w?.id !== "string" || !w.id.trim()) {
+      problems.push(`walkthrough ${label}: id is required`);
       continue;
     }
-    if (typeof t?.title !== "string" || !t.title.trim()) {
-      problems.push(`throughline ${label}: title is required`);
+    if (typeof w?.title !== "string" || !w.title.trim()) {
+      problems.push(`walkthrough ${label}: title is required`);
     }
-    if (!Array.isArray(t.steps)) {
-      problems.push(`throughline ${label}: steps array is required`);
+    if (!Array.isArray(w.steps)) {
+      problems.push(`walkthrough ${label}: steps array is required`);
       continue;
     }
-    t.steps.forEach((step, i) => {
+    w.steps.forEach((step, i) => {
       const s = step;
-      if (typeof s?.edgeId !== "string" || !edgeIds.has(s.edgeId)) {
-        problems.push(
-          `throughline ${label}: step ${i} edgeId ${JSON.stringify(s?.edgeId ?? "<missing>")} does not match any edge in the graph`
-        );
+      if (typeof s?.from !== "string" || !s.from.trim()) {
+        problems.push(`walkthrough ${label}: step ${i} from is required`);
+      }
+      if (typeof s?.to !== "string" || !s.to.trim()) {
+        problems.push(`walkthrough ${label}: step ${i} to is required`);
+      }
+      if (typeof s?.mechanism !== "string" || !SUBSYSTEM_WALKTHROUGH_MECHANISMS.includes(s.mechanism)) {
+        problems.push(`walkthrough ${label}: step ${i} unknown mechanism ${JSON.stringify(s?.mechanism)}`);
       }
       if (typeof s?.file !== "string" || !s.file.trim()) {
-        problems.push(
-          `throughline ${label}: step ${i} file is required (edgeId ${JSON.stringify(s?.edgeId ?? "<missing>")})`
-        );
+        problems.push(`walkthrough ${label}: step ${i} file is required`);
       } else if (typeof s?.line !== "number" || !Number.isInteger(s.line) || s.line < 1) {
-        problems.push(
-          `throughline ${label}: step ${i} line must be a positive 1-based integer (edgeId ${JSON.stringify(s?.edgeId ?? "<missing>")}, file ${JSON.stringify(s?.file)})`
-        );
+        problems.push(`walkthrough ${label}: step ${i} line must be a positive 1-based integer`);
       }
     });
   }
@@ -15497,46 +15564,48 @@ function findComponentConstructProblems(components) {
   }
   return problems;
 }
-function findDetailProvenanceProblems(components) {
+function findDeclarationProvenanceProblems(components) {
   if (!Array.isArray(components)) return [];
   const problems = [];
   for (const component of components) {
     const c = component;
-    if (!c || typeof c !== "object" || !c["detail"]) continue;
-    const p = c["detailProvenance"];
+    if (!c || typeof c !== "object") continue;
+    if (!c["declaration"]) continue;
+    const p = c["declarationProvenance"];
     if (p === void 0) continue;
-    if (typeof p === "string" && SUBSYSTEM_DETAIL_PROVENANCES.includes(p)) {
+    if (typeof p === "string" && SUBSYSTEM_DECLARATION_PROVENANCES.includes(p)) {
       continue;
     }
     problems.push(
-      `component ${JSON.stringify(String(c["id"] ?? "<no id>"))}: invalid detailProvenance ${JSON.stringify(p)} \u2014 allowed: ${SUBSYSTEM_DETAIL_PROVENANCES.join(", ")}. Hand-authored details must be "authored"; "verified" is reserved for tool-extracted data.`
+      `component ${JSON.stringify(String(c["id"] ?? "<no id>"))}: invalid declarationProvenance ${JSON.stringify(p)} \u2014 allowed: ${SUBSYSTEM_DECLARATION_PROVENANCES.join(", ")}. Hand-authored declarations must be "authored"; "verified" is reserved for tool-extracted data.`
     );
   }
   return problems;
 }
-function normalizeDetailProvenance(components) {
+function normalizeDeclarationProvenance(components) {
   if (!Array.isArray(components)) return;
   for (const component of components) {
     const c = component;
     if (!c || typeof c !== "object") continue;
-    const detail = c["detail"];
-    if (!detail || typeof detail !== "object") {
-      delete c["detailProvenance"];
+    const declaration = c["declaration"];
+    if (!declaration || typeof declaration !== "object") {
+      delete c["declarationProvenance"];
       continue;
     }
-    const p = c["detailProvenance"];
-    if (p !== "verified" && p !== "authored") c["detailProvenance"] = "authored";
-    const kind = detail["kind"];
+    const p = c["declarationProvenance"];
+    if (p !== "verified" && p !== "authored") c["declarationProvenance"] = "authored";
+    const kind = declaration["kind"];
     const arrays = {
       function: ["parameters", "callers", "callees"],
       method: ["parameters"],
       class: ["methods", "properties", "extends", "implements", "instantiations", "references"],
       type: ["properties", "usedBy", "implementors"],
       module: ["imports", "exports", "symbols"],
-      custom_entity: ["attributes"]
+      custom_entity: ["attributes"],
+      store: ["properties"]
     };
     for (const key of arrays[String(kind)] ?? []) {
-      if (!Array.isArray(detail[key])) detail[key] = [];
+      if (!Array.isArray(declaration[key])) declaration[key] = [];
     }
   }
 }
@@ -15552,15 +15621,15 @@ function findCreateProblems(body) {
   if (!Array.isArray(body["components"])) {
     problems.push("components array is required");
   }
-  if (!Array.isArray(body["edges"])) {
-    problems.push("edges array is required");
+  if (!Array.isArray(body["relations"])) {
+    problems.push("relations array is required");
   }
   if (problems.length > 0) return problems;
   return [
     ...findComponentConstructProblems(body["components"]),
-    ...findDetailProvenanceProblems(body["components"]),
-    ...findEdgeMechanismProblems(body["edges"]),
-    ...findThroughlineProblems(body["edges"], body["throughlines"])
+    ...findDeclarationProvenanceProblems(body["components"]),
+    ...findRelationTypeProblems(body["relations"]),
+    ...findWalkthroughProblems(body["walkthroughs"])
   ];
 }
 function indexEntryFor(record) {
@@ -15569,7 +15638,10 @@ function indexEntryFor(record) {
     title: record.title,
     description: record.description,
     componentCount: record.components.length,
-    edgeCount: record.edges.length,
+    edgeCount: (0, import_subsystems_core.deriveGraphEdges)({
+      relations: record.relations,
+      walkthroughs: record.walkthroughs
+    }).length,
     createdAt: record.createdAt,
     updatedAt: record.updatedAt,
     lastOpenedAt: record.lastOpenedAt,
@@ -15635,7 +15707,7 @@ async function getSubsystemModel(id) {
 }
 async function createSubsystemModel(doc) {
   await ensureDir();
-  normalizeDetailProvenance(doc.components);
+  normalizeDeclarationProvenance(doc.components);
   const now = (/* @__PURE__ */ new Date()).toISOString();
   const record = {
     ...doc,
@@ -15779,8 +15851,8 @@ async function createAction(options) {
       title: body["title"],
       description: typeof body["description"] === "string" ? body["description"] : void 0,
       components: body["components"],
-      edges: body["edges"],
-      throughlines: Array.isArray(body["throughlines"]) ? body["throughlines"] : void 0,
+      relations: body["relations"],
+      walkthroughs: Array.isArray(body["walkthroughs"]) ? body["walkthroughs"] : void 0,
       source: typeof body["source"] === "string" ? body["source"] : void 0,
       repo: body["repo"],
       repoRoot: typeof body["repoRoot"] === "string" ? body["repoRoot"] : void 0,
@@ -15986,7 +16058,7 @@ function createSubsystemModelCommand() {
 }
 
 // src/index.ts
-var VERSION = true ? "0.37.1" : "0.0.0-dev";
+var VERSION = true ? "0.38.0" : "0.0.0-dev";
 var program2 = new Command();
 program2.name("principal-ai").description(
   "Principal AI CLI \u2014 subsystem models, Subsystems Studio, trails, and agent sessions"