systemview-plugin 1.1.1 → 1.3.0

package/README.md

@@ -1,2 +1,98 @@
 # systemview-plugin
-SystemView is a documentation and testing suite for SystemLynx
+
+Connects a [SystemLynx](https://github.com/Odion100/SystemLynx) service to [SystemView](https://github.com/Odion100/systemview) — the documentation and testing suite for SystemLynx.
+
+---
+
+## Installation
+
+```bash
+npm install systemview-plugin
+```
+
+---
+
+## Setup
+
+```js
+const { App } = require("systemlynx");
+
+App.startService({ route, port })
+  .module("Users", Users)
+  .module("Orders", Orders);
+
+if (process.env.SYSTEMVIEW_HOST) {
+  const SystemViewPlugin = require("systemview-plugin")({
+    connection: process.env.SYSTEMVIEW_HOST,  // SystemView API URL
+    specs: "./specs",                          // local path for docs and test files
+    projectCode: "myProject",                 // groups services together in SystemView
+    serviceId: "MyService",                   // name for this service
+  });
+  App.use(SystemViewPlugin);
+}
+```
+
+Set `SYSTEMVIEW_HOST` to your SystemView instance, e.g.:
+
+```bash
+SYSTEMVIEW_HOST=http://localhost:3000/systemview/api node index.js
+```
+
+---
+
+## What it does on startup
+
+1. **Registers with SystemView** — sends connection data to the SystemView server so the service appears in the UI under `projectCode > serviceId`
+2. **Writes `systemview.manifest.json`** — saves connection data and spec file locations to the project root so the SystemView CLI can run tests without the SystemView server running
+
+If multiple services in the same project use the plugin, each one merges its own entry into the manifest rather than overwriting it.
+
+---
+
+## `systemview.manifest.json`
+
+Written automatically to the root of your service project on each startup:
+
+```json
+{
+  "projectCode": "myProject",
+  "services": [
+    {
+      "serviceId": "MyService",
+      "system": {
+        "connectionData": {
+          "serviceUrl": "http://localhost:4100/my/api",
+          "modules": [ ... ],
+          "routing": { ... }
+        }
+      },
+      "specList": {
+        "docs": ["Users.md"],
+        "tests": ["Users.signUp.json"]
+      }
+    }
+  ]
+}
+```
+
+Add it to `.gitignore` — it's a local artifact that regenerates on each startup.
+
+With the manifest in place, the CLI can run tests directly against your live service without needing the SystemView server:
+
+```bash
+systemview test myProject
+```
+
+---
+
+## Specs folder
+
+The plugin reads and writes documentation and test files from the `specs` path you configure:
+
+```
+specs/
+  docs/         # markdown files, one per method
+  tests/        # JSON test files, one per method
+```
+
+These files are committed to your repo. The SystemView UI saves to them via the plugin's `saveDoc` and `saveTest` methods.

package/SystemViewModule.js

@@ -1,4 +1,5 @@
 const fs = require("fs");
+const path = require("path");
 const {
   deleteFile,
   getFile,
@@ -81,5 +82,17 @@ module.exports = ({ App, specs, projectCode, serviceId, module = {} }) => {
       const specList = this.getSpecList();
       return { projectCode, serviceId, system, specList };
     };
+    this.getLog = ({ limit } = {}) => {
+      const logsFile = path.join(process.cwd(), "systemview.logs");
+      try {
+        const lines = fs.readFileSync(logsFile, "utf8")
+          .split("\n")
+          .filter(Boolean)
+          .map(JSON.parse);
+        return limit ? lines.slice(-limit) : lines;
+      } catch {
+        return [];
+      }
+    };
   };
 };

package/index.js

@@ -1,3 +1,5 @@
+const fs = require("fs");
+const path = require("path");
 const SystemViewModule = require("./SystemViewModule");
 const { getSpecList } = require("./utils");
 
@@ -8,7 +10,9 @@ module.exports = function ({
   serviceId,
   module,
 }) {
-  return function (App) {
+  const LOGS_FILE = path.join(process.cwd(), "systemview.logs");
+
+  function install(App) {
     App.loadService("SystemView", connection)
       .module(
         "Plugin",
@@ -24,15 +28,44 @@ module.exports = function ({
         "ready",
         async function connectSystemView({ connectionData, modules, routing, services }) {
           const system = { connectionData, modules, routing, services };
+          const specList = getSpecList(specs);
           try {
             const { SystemView } = this.useService("SystemView");
-            const specList = getSpecList(specs);
             await SystemView.connect({ system, projectCode, serviceId, specList });
             console.log(`[SystemView]: ${projectCode}.${serviceId} connected!\n`);
           } catch (error) {
             console.log(`[SystemView]: ${projectCode}.${serviceId} connection failed\n`);
           }
+          // Write manifest so CLI can run tests without the SystemView server
+          try {
+            const manifestPath = path.join(process.cwd(), "systemview.manifest.json");
+            let manifest = { projectCode, services: [] };
+            if (fs.existsSync(manifestPath)) {
+              try { manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8")); } catch {}
+              if (!manifest.services) manifest.services = [];
+            }
+            const entry = { serviceId, system, specList };
+            const idx = manifest.services.findIndex((s) => s.serviceId === serviceId);
+            if (idx > -1) manifest.services[idx] = entry;
+            else manifest.services.push(entry);
+            manifest.projectCode = projectCode;
+            fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+          } catch (err) {
+            console.log(`[SystemView]: failed to write manifest: ${err.message}\n`);
+          }
         }
       );
+  }
+
+  install.log = function (...args) {
+    console.log(...args);
+    const entry = JSON.stringify({
+      ts: new Date().toISOString(),
+      service: `${projectCode}.${serviceId}`,
+      message: args.length === 1 ? args[0] : args,
+    });
+    fs.appendFileSync(LOGS_FILE, entry + "\n");
   };
+
+  return install;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "systemview-plugin",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Connects your SystemLynx project to the SystemView UI",
   "main": "index.js",
   "scripts": {