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

package/dist/lib/subsystem-model-store.d.ts

@@ -4,12 +4,12 @@
  *
  * Lets the CLI create/list models without Studio's HTTP bridge running.
  * Structural validation mirrors the Studio POST gate (construct / mechanism /
- * throughlines / detail provenance). File/symbol verification is Studio-only
+ * walkthroughs / detail provenance). File/symbol verification is Studio-only
  * for now and may be empty on CLI-created records until opened/updated there.
  */
 export declare const SUBSYSTEM_EDGE_MECHANISMS: readonly ["imports", "imports_from", "re_exports", "defines", "calls", "extends", "inherits", "implements", "mixes_in", "uses", "method", "references", "contains", "feeds", "produces", "writes", "reads", "watches", "registers-into"];
-export declare const SUBSYSTEM_COMPONENT_CONSTRUCTS: readonly ["class", "function", "method", "interface", "type_alias", "enum", "store", "external"];
-export declare const SUBSYSTEM_DETAIL_PROVENANCES: readonly ["verified", "authored"];
+export declare const SUBSYSTEM_COMPONENT_CONSTRUCTS: readonly ["class", "function", "method", "interface", "type_alias", "enum", "store", "external", "custom_entity"];
+export declare const SUBSYSTEM_DECLARATION_PROVENANCES: readonly ["verified", "authored"];
 export interface SubsystemModelIndexEntry {
     id: string;
     title: string;
@@ -25,14 +25,19 @@ export interface SubsystemModelIndexEntry {
         owner: string;
         name: string;
     };
+    /** Host-only gist link mirrored from the record. */
+    gist?: {
+        id: string;
+        fileName?: string;
+    };
 }
 export interface StoredSubsystemModel {
     id: string;
     title: string;
     description?: string;
     components: unknown[];
-    edges: unknown[];
-    throughlines?: unknown[];
+    relations: unknown[];
+    walkthroughs?: unknown[];
     createdAt: string;
     updatedAt: string;
     lastOpenedAt?: string;
@@ -43,14 +48,19 @@ export interface StoredSubsystemModel {
     };
     repoRoot?: string;
     repoRoots?: Record<string, string>;
+    /** Host-only GitHub gist link (not portable). */
+    gist?: {
+        id: string;
+        fileName?: string;
+    };
     verification?: unknown;
 }
 export interface CreateSubsystemModelInput {
     title: string;
     description?: string;
     components: unknown[];
-    edges: unknown[];
-    throughlines?: unknown[];
+    relations: unknown[];
+    walkthroughs?: unknown[];
     source?: string;
     repo?: {
         owner: string;
@@ -60,15 +70,17 @@ export interface CreateSubsystemModelInput {
     repoRoots?: Record<string, string>;
 }
 export declare function subsystemModelFilePath(id: string): string;
-export declare function findEdgeMechanismProblems(edges: unknown): string[];
-export declare function findThroughlineProblems(edges: unknown, throughlines: unknown): string[];
+export declare function findRelationTypeProblems(relations: unknown): string[];
+export declare function findWalkthroughProblems(walkthroughs: unknown): string[];
 export declare function findComponentConstructProblems(components: unknown): string[];
-export declare function findDetailProvenanceProblems(components: unknown): string[];
-export declare function normalizeDetailProvenance(components: unknown): void;
+export declare function findDeclarationProvenanceProblems(components: unknown): string[];
+export declare function normalizeDeclarationProvenance(components: unknown): void;
 export declare function isRepoRoots(value: unknown): value is Record<string, string>;
 /** Structural problems that would make Studio reject a POST (empty = valid). */
 export declare function findCreateProblems(body: Record<string, unknown>): string[];
 export declare function listSubsystemModels(): Promise<SubsystemModelIndexEntry[]>;
 export declare function getSubsystemModel(id: string): Promise<StoredSubsystemModel | null>;
 export declare function createSubsystemModel(doc: CreateSubsystemModelInput): Promise<StoredSubsystemModel>;
+/** Patch an existing record (e.g. stamp a host gist ref after share). */
+export declare function updateSubsystemModel(id: string, patch: Partial<Pick<StoredSubsystemModel, 'title' | 'description' | 'components' | 'relations' | 'walkthroughs' | 'source' | 'repo' | 'repoRoot' | 'repoRoots' | 'gist'>>): Promise<StoredSubsystemModel | null>;
 //# sourceMappingURL=subsystem-model-store.d.ts.map

package/dist/lib/subsystem-model-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subsystem-model-store.d.ts","sourceRoot":"","sources":["../../src/lib/subsystem-model-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"subsystem-model-store.d.ts","sourceRoot":"","sources":["../../src/lib/subsystem-model-store.ts"],"names":[],"mappings":"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"}

package/dist/lib/subsystem-model-store.js

@@ -4,12 +4,13 @@
  *
  * Lets the CLI create/list models without Studio's HTTP bridge running.
  * Structural validation mirrors the Studio POST gate (construct / mechanism /
- * throughlines / detail provenance). File/symbol verification is Studio-only
+ * walkthroughs / detail provenance). File/symbol verification is Studio-only
  * for now and may be empty on CLI-created records until opened/updated there.
  */
 import { promises as fs } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { deriveGraphEdges } from '@principal-ai/subsystems-core';
 const ROOT = join(homedir(), '.principal', 'subsystem-models');
 const INDEX_PATH = join(ROOT, '_index.json');
 export const SUBSYSTEM_EDGE_MECHANISMS = [
@@ -42,8 +43,9 @@ export const SUBSYSTEM_COMPONENT_CONSTRUCTS = [
     'enum',
     'store',
     'external',
+    'custom_entity',
 ];
-export const SUBSYSTEM_DETAIL_PROVENANCES = ['verified', 'authored'];
+export const SUBSYSTEM_DECLARATION_PROVENANCES = ['verified', 'authored'];
 function graphId() {
     const ts = Date.now();
     const rand = Math.random().toString(36).slice(2, 11);
@@ -58,53 +60,72 @@ export function subsystemModelFilePath(id) {
 async function ensureDir() {
     await fs.mkdir(ROOT, { recursive: true });
 }
-export function findEdgeMechanismProblems(edges) {
-    if (!Array.isArray(edges))
-        return [];
+const SUBSYSTEM_RELATION_TYPES = [
+    'imports', 'imports_from', 're_exports', 'defines', 'extends', 'inherits',
+    'implements', 'mixes_in', 'method', 'references', 'contains',
+];
+const SUBSYSTEM_WALKTHROUGH_MECHANISMS = [
+    'calls', 'uses', 'feeds', 'produces', 'writes', 'reads', 'watches', 'registers-into',
+];
+export 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)} — allowed: ${SUBSYSTEM_EDGE_MECHANISMS.join(', ')}`);
     }
     return problems;
 }
-export function findThroughlineProblems(edges, throughlines) {
-    if (throughlines === undefined)
+export function findWalkthroughProblems(walkthroughs) {
+    if (walkthroughs === undefined)
         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'));
+    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`);
             }
         });
     }
@@ -124,50 +145,55 @@ export function findComponentConstructProblems(components) {
     }
     return problems;
 }
-export function findDetailProvenanceProblems(components) {
+export 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'])
+        if (!c || typeof c !== 'object')
+            continue;
+        if (!c['declaration'])
             continue;
-        const p = c['detailProvenance'];
+        const p = c['declarationProvenance'];
         if (p === undefined)
             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)} — allowed: ${SUBSYSTEM_DETAIL_PROVENANCES.join(', ')}. Hand-authored details must be "authored"; "verified" is reserved for tool-extracted data.`);
+        problems.push(`component ${JSON.stringify(String(c['id'] ?? '<no id>'))}: invalid declarationProvenance ${JSON.stringify(p)} — allowed: ${SUBSYSTEM_DECLARATION_PROVENANCES.join(', ')}. Hand-authored declarations must be "authored"; "verified" is reserved for tool-extracted data.`);
     }
     return problems;
 }
-export function normalizeDetailProvenance(components) {
+export 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'];
+        const p = c['declarationProvenance'];
         if (p !== 'verified' && p !== 'authored')
-            c['detailProvenance'] = 'authored';
-        const kind = detail['kind'];
+            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'],
+            store: ['properties'],
         };
         for (const key of arrays[String(kind)] ?? []) {
-            if (!Array.isArray(detail[key]))
-                detail[key] = [];
+            if (!Array.isArray(declaration[key]))
+                declaration[key] = [];
         }
     }
 }
@@ -185,16 +211,16 @@ export 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) {
@@ -203,13 +229,17 @@ function indexEntryFor(record) {
         title: record.title,
         description: record.description,
         componentCount: record.components.length,
-        edgeCount: record.edges.length,
+        edgeCount: deriveGraphEdges({
+            relations: record.relations,
+            walkthroughs: record.walkthroughs,
+        }).length,
         createdAt: record.createdAt,
         updatedAt: record.updatedAt,
         lastOpenedAt: record.lastOpenedAt,
         fileName: `${record.id}.json`,
         source: record.source,
         repo: record.repo,
+        gist: record.gist,
     };
 }
 async function readIndex() {
@@ -278,7 +308,7 @@ export async function getSubsystemModel(id) {
 }
 export async function createSubsystemModel(doc) {
     await ensureDir();
-    normalizeDetailProvenance(doc.components);
+    normalizeDeclarationProvenance(doc.components);
     const now = new Date().toISOString();
     const record = {
         ...doc,
@@ -290,3 +320,19 @@ export async function createSubsystemModel(doc) {
     await upsertIndexEntry(indexEntryFor(record));
     return record;
 }
+/** Patch an existing record (e.g. stamp a host gist ref after share). */
+export async function updateSubsystemModel(id, patch) {
+    const existing = await getSubsystemModel(id);
+    if (!existing)
+        return null;
+    if (patch.components !== undefined)
+        normalizeDeclarationProvenance(patch.components);
+    const updated = {
+        ...existing,
+        ...patch,
+        updatedAt: new Date().toISOString(),
+    };
+    await fs.writeFile(graphPath(id), JSON.stringify(updated, null, 2), 'utf8');
+    await upsertIndexEntry(indexEntryFor(updated));
+    return updated;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principal-ai/principal-studio-cli",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Principal AI CLI — subsystem models, Subsystems Studio, trails, and agent sessions",
   "main": "dist/index.cjs",
   "types": "dist/index.d.ts",
@@ -35,8 +35,8 @@
     "@principal-ai/alexandria-core-library": "^0.4.0",
     "@principal-ai/codebase-composition": "^0.2.57",
     "@principal-ai/file-city-builder": "^0.5.0",
-    "@principal-ai/subsystems-core": "^0.30.0",
     "@principal-ai/repository-abstraction": "^0.5.7",
+    "@principal-ai/subsystems-core": "0.32.0",
     "better-sqlite3": "^13.0.0",
     "chalk": "5.6.2",
     "commander": "14.0.2",
@@ -45,7 +45,7 @@
     "js-yaml": "4.1.1"
   },
   "optionalDependencies": {
-    "@principal-ai/subsystems-studio": "^0.6.3"
+    "@principal-ai/subsystems-studio": "^0.6.9"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",