@principal-ai/subsystems-react 0.51.4 → 0.52.0

package/src/stories/Subsystem/C4Graph/C4Component.stories.tsx

@@ -0,0 +1,198 @@
+import React, { useMemo, useState } from 'react';
+import '@xyflow/react/dist/style.css';
+import type { Meta, StoryObj } from '@storybook/react';
+import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
+import { C4Graph } from '../../../subsystem/C4Graph';
+import type { C4Edge, C4Group, C4Model, C4Element, C4Component } from '../../../subsystem/c4';
+
+const meta = {
+  title: 'Subsystem/C4Graph/C4Component',
+  component: C4Graph,
+  parameters: { layout: 'fullscreen' },
+  tags: ['autodocs'],
+  decorators: [
+    (Story) => (
+      <ThemeProvider theme={defaultEditorTheme}>
+        <Story />
+      </ThemeProvider>
+    ),
+  ],
+} satisfies Meta<typeof C4Graph>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ---------------------------------------------------------------------------
+// A C4 *component* diagram, hand-built.
+//
+// No single subsystem model owns these groupings — each one is stitched from
+// constructs that recur across many models (e.g. `auditSubsystemModel` appears
+// in 8). That is exactly why a component is an authored grouping: the evidence
+// lives across models, and a principal agent proposes the union while a person
+// confirms it.
+//
+// Two containers are drawn as frames; their components sit inside.
+// ---------------------------------------------------------------------------
+
+const SYSTEM = { id: 'system:acme', label: 'Subsystem Modeling', repoKey: 'pkg:github/acme/subsystem-modeling' };
+const HOST = 'container:studio-host';
+const RENDERER = 'container:studio-renderer';
+
+/** A component at level 3, inside a container. */
+function component(
+  over: Partial<C4Component> & Pick<C4Component, 'id' | 'label' | 'container'>,
+): C4Element {
+  return {
+    kind: 'component',
+    members: [],
+    constructs: [],
+    state: 'accepted',
+    parentId: over.container,
+    technology: 'Bun + Electrobun',
+    ...over,
+  };
+}
+
+const NODES: C4Element[] = [
+  // --- inside the host ------------------------------------------------------
+  component({
+    id: 'component:audit-verification',
+    label: 'Audit & verification',
+    container: HOST,
+    technology: 'Bun',
+    description: 'Checks a subsystem model and reports what is wrong.',
+    // The recurring constructs, stitched across ~8 models. See the story notes.
+    members: [
+      'auditSubsystemModel', 'verifySubsystemComponent', 'verifyModelFiles',
+      'createRegularAuditScheduler', 'applySubsystemModelAuditFix',
+      'auditTopologyRelations', 'auditBoundaryFields',
+    ],
+  }),
+  component({
+    id: 'component:maintain-proposals',
+    label: 'Maintain & proposals',
+    container: HOST,
+    technology: 'Bun',
+    description: 'Runs a maintain agent and records the corrections it proposes.',
+    members: [
+      'maintainSubsystemModel', 'runMaintainAgent', 'buildMaintainBrief',
+      'createSubsystemModelProposal', 'acceptSubsystemModelProposal',
+      'autoAcceptProposalIfConfident',
+    ],
+  }),
+  component({
+    id: 'component:model-store',
+    label: 'Model store I/O',
+    container: HOST,
+    technology: 'Bun fs',
+    description: 'Reads and writes model JSON under ~/.principal.',
+    members: [
+      'getSubsystemModel', 'listSubsystemModels', 'updateSubsystemModel',
+      'createSubsystemModel', 'readFile', 'writeFile', 'touchSubsystemModelOpened',
+    ],
+  }),
+  component({
+    id: 'component:session-pipeline',
+    label: 'Session pipeline',
+    container: HOST,
+    technology: 'Bun',
+    description: 'Turns raw OpenCode session rows into universal events.',
+    members: ['processSessionEvents', 'opencodeRowsToUniversalEvents', 'buildSessionIndex'],
+  }),
+
+  // --- inside the renderer --------------------------------------------------
+  component({
+    id: 'component:graph-view',
+    label: 'Graph view',
+    container: RENDERER,
+    technology: 'React + ELK',
+    description: 'Renders the component graph and its layout.',
+  }),
+  component({
+    id: 'component:model-views',
+    label: 'Model views',
+    container: RENDERER,
+    technology: 'React',
+    description: 'Lists and opens stored subsystem models.',
+  }),
+  component({
+    id: 'component:agent-sessions',
+    label: 'Agent sessions view',
+    container: RENDERER,
+    technology: 'React',
+    description: 'Shows maintain-agent sessions and their timelines.',
+  }),
+  component({
+    id: 'component:rpc-bridge',
+    label: 'RPC bridge',
+    container: RENDERER,
+    technology: 'Electrobun RPC',
+    description: 'Talks to the host process over the Electrobun bridge.',
+  }),
+];
+
+/** The two containers at this level, drawn as frames. */
+const GROUPS: C4Group[] = [
+  { id: HOST, kind: 'container', label: 'Subsystem Studio — host', parentId: SYSTEM.id, memberIds: NODES.filter((n) => n.parentId === HOST).map((n) => n.id) },
+  { id: RENDERER, kind: 'container', label: 'Subsystem Studio — renderer', parentId: SYSTEM.id, memberIds: NODES.filter((n) => n.parentId === RENDERER).map((n) => n.id) },
+  { id: SYSTEM.id, kind: 'system', label: SYSTEM.label, memberIds: [HOST, RENDERER] },
+];
+
+/** A line between components — protocol-labelled, like the container view. */
+function edge(id: string, source: string, target: string, protocol: string): C4Edge {
+  return { id, source, target, label: protocol, protocol, mechanisms: [], count: 1 };
+}
+
+const EDGES: C4Edge[] = [
+  edge('e:views-store', 'component:model-views', 'component:model-store', 'RPC'),
+  edge('e:views-audit', 'component:model-views', 'component:audit-verification', 'RPC'),
+  edge('e:audit-store', 'component:audit-verification', 'component:model-store', 'fs · JSON'),
+  edge('e:proposals-store', 'component:maintain-proposals', 'component:model-store', 'fs · JSON'),
+  edge('e:proposals-sessions', 'component:maintain-proposals', 'component:session-pipeline', 'feeds'),
+  edge('e:sessions-agent', 'component:agent-sessions', 'component:session-pipeline', 'RPC'),
+  edge('e:renderer-host', 'component:rpc-bridge', 'component:model-store', 'RPC'),
+  edge('e:views-graph', 'component:model-views', 'component:graph-view', 'calls'),
+];
+
+const componentModel: C4Model = {
+  view: 'component',
+  system: SYSTEM,
+  nodes: NODES,
+  groups: GROUPS,
+  edges: EDGES,
+};
+
+function Demo() {
+  const [selected, setSelected] = useState<string | null>(null);
+  const model = useMemo(() => componentModel, []);
+  const components = model.nodes.filter((n) => n.kind === 'component').length;
+
+  return (
+    <div style={{ width: '100%', height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <div style={{ flex: 1, minHeight: 0, position: 'relative' }}>
+        <C4Graph model={model} title="Subsystem Modeling" onSelectNode={setSelected} />
+      </div>
+      <div
+        style={{
+          padding: '6px 12px',
+          display: 'flex',
+          alignItems: 'center',
+          gap: 18,
+          fontFamily: 'monospace',
+          fontSize: 12,
+          color: '#aaa',
+          borderTop: '1px solid #333',
+        }}
+      >
+        <span>{components} components in {model.groups.filter((g) => g.kind === 'container').length} containers</span>
+        <span>{model.edges.length} lines</span>
+        <span>selected: {selected ?? '(none)'}</span>
+        <span style={{ color: '#777' }}>each component is a grouping stitched across many models</span>
+      </div>
+    </div>
+  );
+}
+
+export const Components: Story = {
+  render: () => <Demo />,
+};

package/src/stories/Subsystem/C4Graph/C4Container.stories.tsx

@@ -3,7 +3,7 @@ import '@xyflow/react/dist/style.css';
 import type { Meta, StoryObj } from '@storybook/react';
 import { ThemeProvider, defaultEditorTheme } from '@principal-ade/industry-theme';
 import { C4Graph } from '../../../subsystem/C4Graph';
-import type { C4Edge, C4Model, C4Node } from '../../../subsystem/c4';
+import type { C4Edge, C4Model, C4Element, C4Container } from '../../../subsystem/c4';
 
 const meta = {
   title: 'Subsystem/C4Graph/C4Container',
@@ -25,7 +25,7 @@ type Story = StoryObj<typeof meta>;
 // ---------------------------------------------------------------------------
 // A C4 container diagram, hand-built.
 //
-// Nothing here is derived: the boxes are `C4Node`s an author wrote down, and
+// Nothing here is derived: the boxes are authored `C4Element`s, and
 // the lines are explicit `C4Edge`s — no trails, no rollup. This is the shape a
 // caller hands to `C4Graph` once a model has been authored.
 //
@@ -35,18 +35,19 @@ type Story = StoryObj<typeof meta>;
 
 const SYSTEM = { id: 'system:acme', label: 'Subsystem Modeling', repoKey: 'pkg:github/acme/subsystem-modeling' };
 
-function container(over: Partial<C4Node> & Pick<C4Node, 'id' | 'label'>): C4Node {
+function container(over: Partial<C4Container> & Pick<C4Container, 'id' | 'label'>): C4Element {
   return {
     kind: 'container',
     members: [],
     constructs: [],
     state: 'accepted',
     containerKind: 'application',
+    technology: '',
     ...over,
   };
 }
 
-const NODES: C4Node[] = [
+const NODES: C4Element[] = [
   container({
     id: 'container:studio-host',
     label: 'Subsystem Studio — host',
@@ -79,7 +80,7 @@ const NODES: C4Node[] = [
     description: 'Every stored model and the correction queue.',
     parentId: SYSTEM.id,
   }),
-  // An external system drawn inside the boundary — something we depend on.
+  // An external system: someone else's system, drawn OUTSIDE the boundary.
   {
     kind: 'external-system',
     id: 'external:opencode',
@@ -89,7 +90,6 @@ const NODES: C4Node[] = [
     state: 'accepted',
     members: [],
     constructs: [],
-    parentId: SYSTEM.id,
   },
   // A person sits outside every system boundary.
   {
@@ -101,6 +101,42 @@ const NODES: C4Node[] = [
     members: [],
     constructs: [],
   },
+  // Components that live inside the host. Not drawn in the container view
+  // (`groups` frames only the containers), but carried on the model so the
+  // side panel can list them when the host is clicked.
+  {
+    kind: 'component',
+    id: 'component:audit-verification',
+    label: 'Audit & verification',
+    container: 'container:studio-host',
+    parentId: 'container:studio-host',
+    technology: 'Bun',
+    description: 'Checks a subsystem model and reports what is wrong.',
+    state: 'accepted',
+    members: ['auditSubsystemModel', 'verifySubsystemComponent', 'verifyModelFiles'],
+  },
+  {
+    kind: 'component',
+    id: 'component:maintain-proposals',
+    label: 'Maintain & proposals',
+    container: 'container:studio-host',
+    parentId: 'container:studio-host',
+    technology: 'Bun',
+    description: 'Runs a maintain agent and records the corrections it proposes.',
+    state: 'accepted',
+    members: ['maintainSubsystemModel', 'runMaintainAgent', 'createSubsystemModelProposal'],
+  },
+  {
+    kind: 'component',
+    id: 'component:model-store',
+    label: 'Model store I/O',
+    container: 'container:studio-host',
+    parentId: 'container:studio-host',
+    technology: 'Bun fs',
+    description: 'Reads and writes model JSON under ~/.principal.',
+    state: 'accepted',
+    members: ['getSubsystemModel', 'updateSubsystemModel', 'readFile'],
+  },
 ];
 
 const EDGES: C4Edge[] = [

package/src/stories/Subsystem/C4Graph/C4NodeGallery.stories.tsx

@@ -12,7 +12,7 @@ import {
   nodeMissing,
   NODE_W,
 } from '../../../subsystem/C4NodeCard';
-import type { C4Node } from '../../../subsystem/c4';
+import type { C4Element } from '../../../subsystem/c4';
 
 // ---------------------------------------------------------------------------
 // A card gallery: every C4 box variant, outside the graph.
@@ -25,7 +25,7 @@ import type { C4Node } from '../../../subsystem/c4';
 // is a plain presentational component, so it can be reviewed and diffed
 // without a layout engine in the way.
 //
-// Every card here is a flattened `C4Node` — the one shape a C4 box draws with,
+// Every card here is an authored `C4Element` — the shape a C4 box draws with,
 // produces from an authored element, with the per-kind fields already resolved
 // to the one shape the card draws with.
 // ---------------------------------------------------------------------------
@@ -48,17 +48,19 @@ type Story = StoryObj<typeof meta>;
 
 // --- sample nodes ---------------------------------------------------------
 
-function node(over: Partial<C4Node> & { id: string; label: string }): C4Node {
+function node(over: Record<string, unknown> & { id: string; label: string }): C4Element {
   return {
     kind: 'container',
+    containerKind: 'application',
+    technology: '',
+    state: 'proposed',
     members: [],
     constructs: [],
-    state: 'proposed',
     ...over,
-  };
+  } as C4Element;
 }
 
-const VARIANTS: Array<{ group: string; note: string; node: C4Node }> = [
+const VARIANTS: Array<{ group: string; note: string; node: C4Element }> = [
   // `id` on each variant is its caption key, not a component field.
 
   // --- confirmation state: the axis that matters most --------------------
@@ -356,7 +358,7 @@ function Gallery() {
                     width: 28,
                     height: Math.round((28 * size.height) / size.width),
                     borderRadius: Math.min(s.radius, 9),
-                    border: `${weight} ${s.dash} ${color}`,
+                    border: `${weight} ${nodeStyle(node({ id: 'x', label: '', kind }), theme).dash} ${color}`,
                     display: 'inline-block',
                   }}
                 />