systemview 1.21.0 → 1.22.0

package/cli/index.js

@@ -16,7 +16,7 @@ const connectService = require("./connectService");
 const manifestCommands = require("./manifest");
 const probe = require("./probe");
 const logsCommand = require("./logs");
-const { HttpClient, createClient } = require("systemlynx");
+const { createClient } = require("systemlynx");
 const { createCookieHttpClient } = require("./cookieClient");
 const cookieHttpClient = createCookieHttpClient();
 const Client = createClient(cookieHttpClient);
@@ -45,7 +45,7 @@ function loadManifest() {
 async function startApp() {
   const port = isNaN(input[1]) ? DEFAULT_PORT : Number(input[1]);
   try {
-    await launchApp(port, { interactive: true, connectedUrls });
+    await launchApp(port, { interactive: true, connectedUrls, client: Client });
   } catch (error) {
     log.error("Launch failed: " + error.message);
   }
@@ -83,6 +83,7 @@ async function list() {
   await listTests(UI_URL, project_code, namespace, {
     connectedUrls,
     verbose: flags.verbose,
+    json: flags.json,
   });
   process.exit(0);
 }
@@ -113,24 +114,20 @@ async function quitApp() {
 
   if (await appIsRunning(api)) {
     log.info("Attempting remote shutdown...");
-    const url = `${api}/SystemView/shutdown`;
     try {
-      await HttpClient.request({ url, method: "put" });
+      const { SystemView } = await Client.loadService(api);
+      await SystemView.shutdown();
+    } catch {}
+    if (!(await appIsRunning(api))) {
       log.success("SystemView shutdown successful!");
-      process.exit(0);
-    } catch (error) {
-      if (!(await appIsRunning(api))) {
-        log.success("SystemView shutdown successful!");
-        process.exit(0);
-      } else {
-        log.error("Remote shutdown failed!");
-        process.exit(1);
-      }
+    } else {
+      log.error("Remote shutdown failed!");
+      process.exit(1);
     }
   } else {
     log.warn(`No SystemView instance found @ ${api}`);
-    process.exit(0);
   }
+  process.exit(0);
 }
 
 (async () => {
@@ -188,7 +185,7 @@ async function quitApp() {
       uiUrl: UI_URL,
     });
     process.exit(exitCode || 0);
-  } else if (command === "logs") {
+  } else if (command === "logs" || command === "log") {
     await launchApp(DEFAULT_PORT);
     await logsCommand(input[1], input[2], {
       uiUrl: UI_URL,
@@ -197,12 +194,16 @@ async function quitApp() {
       clear: flags.clear,
       json: flags.json,
       current: flags.current,
+      follow: flags.follow,
       verbose: flags.verbose,
       filter: flags.filter,
       or: flags.or,
       include: flags.include,
+      save: flags.save,
+      saved: flags.saved,
+      saveLimit: flags.saveLimit,
     });
-    process.exit(0);
+    if (!flags.follow) process.exit(0);
   } else {
     await startApp();
   }

package/cli/launchApp.js

@@ -2,6 +2,7 @@ const log = require("./logger");
 const appIsRunning = require("./appIsRunning");
 const launchSystemView = require("../api");
 const startLineReader = require("./startLineReader");
+const listTests = require("./listTests");
 
 module.exports = async function launchApp(port, { interactive = false, connectedUrls = new Set() } = {}) {
   const ui = `http://localhost:${port}`;
@@ -15,8 +16,9 @@ module.exports = async function launchApp(port, { interactive = false, connected
 
   if (await appIsRunning(api)) {
     if (interactive) {
-      log.info(`SystemView already running on port ${port} — attaching.`);
+      log.warn(`SystemView already running on port ${port} — attaching.`);
       logConnection();
+      await listTests(ui, null, null, { connectedUrls });
       return startLineReader(ui, { connectedUrls });
     }
     return;
@@ -27,6 +29,7 @@ module.exports = async function launchApp(port, { interactive = false, connected
   logConnection();
 
   if (interactive) {
+    await listTests(ui, null, null, { connectedUrls });
     return startLineReader(ui, { connectedUrls });
   }
 };

package/cli/listTests.js

@@ -6,11 +6,11 @@ const chalk = require("chalk");
 const cookieHttpClient = createCookieHttpClient();
 const Client = createClient(cookieHttpClient);
 
-module.exports = async function listTests(url, project_code, namespace, { connectedUrls = new Set(), verbose = false } = {}) {
+module.exports = async function listTests(url, project_code, namespace, { connectedUrls = new Set(), verbose = false, json = false } = {}) {
   const api = `${url}/systemview/api`;
 
   if (!project_code) {
-    await listAllProjects(api, Client, verbose, connectedUrls);
+    await listAllProjects(api, Client, verbose, connectedUrls, json);
     return;
   }
 
@@ -20,6 +20,25 @@ module.exports = async function listTests(url, project_code, namespace, { connec
     return;
   }
 
+  if (json) {
+    const output = [];
+    for (const { serviceId, system } of connectedServices) {
+      let testList = [];
+      try {
+        const svc = Client.createService(system.connectionData);
+        testList = await svc.Plugin.getTests();
+      } catch { continue; }
+      const filtered = namespace
+        ? testList.filter(({ namespace: n }) =>
+            `${n.serviceId}.${n.moduleName}.${n.methodName}`.includes(namespace)
+          )
+        : testList;
+      output.push({ serviceId, tests: filtered });
+    }
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+
   console.log("");
   console.log(`  ${chalk.bold(project_code)}`);
 
@@ -94,7 +113,7 @@ module.exports = async function listTests(url, project_code, namespace, { connec
   console.log("");
 };
 
-async function listAllProjects(api, Client, verbose = false, connectedUrls = new Set()) {
+async function listAllProjects(api, Client, verbose = false, connectedUrls = new Set(), json = false) {
   let projects;
   try {
     const { SystemView } = await Client.loadService(api);
@@ -106,10 +125,13 @@ async function listAllProjects(api, Client, verbose = false, connectedUrls = new
 
   const codes = Object.keys(projects);
   if (!codes.length) {
+    if (json) { console.log(JSON.stringify({})); return; }
     log.warn("No connected projects found.");
     return;
   }
 
+  if (json) { console.log(JSON.stringify(projects, null, 2)); return; }
+
   const total = codes.reduce((n, c) => n + projects[c].length, 0);
   console.log("");
   console.log(chalk.dim(`  ${codes.length} ${codes.length === 1 ? "project" : "projects"}, ${total} ${total === 1 ? "service" : "services"}`));

package/cli/logs.js

@@ -1,3 +1,5 @@
+const fs = require("fs");
+const path = require("path");
 const chalk = require("chalk");
 const log = require("./logger");
 const { createClient } = require("systemlynx");
@@ -5,9 +7,11 @@ const { createCookieHttpClient } = require("./cookieClient");
 const cookieHttpClient = createCookieHttpClient();
 const Client = createClient(cookieHttpClient);
 
+const DEFAULT_SNAPSHOT = "systemview-snapshot.ndjson";
+
 const LEVEL_COLOR = {
   trace: (s) => chalk.dim(s),
-  info: (s) => chalk.white(s),
+  log: (s) => chalk.white(s),
   warn: (s) => chalk.yellow(s),
   error: (s) => chalk.red(s),
   debug: (s) => chalk.blue(s),
@@ -15,13 +19,15 @@ const LEVEL_COLOR = {
 
 function colorLevel(level) {
   const fn = LEVEL_COLOR[level] || ((s) => s);
-  return fn((level || "info").padEnd(5));
+  return fn((level || "log").padEnd(5));
 }
 
 const SKIP_KEYS = new Set([
   "timestamp",
   "projectCode",
   "serviceId",
+  "module",
+  "method",
   "moduleMethod",
   "traceId",
   "level",
@@ -44,7 +50,9 @@ function formatRow(entry, verbose, extraFields) {
   const traceId = chalk.dim(entry.traceId || "—");
   let row = `  ${chalk.dim(time)}  ${chalk.cyan(project)} › ${chalk.cyan(service)}   ${method.padEnd(15)}  ${level}  ${traceId}  ${msg}${dur}`;
   if (extraFields && extraFields.length) {
-    const parts = extraFields.map((p) => `${chalk.dim(p + ":")} ${cellStr(getAtPath(entry, p))}`);
+    const parts = extraFields.map(
+      (p) => `${chalk.dim(p + ":")} ${cellStr(getAtPath(entry, p))}`,
+    );
     row += "  " + parts.join("  ");
   }
   if (verbose) {
@@ -99,17 +107,55 @@ function matchesFilters(entry, andFilters, orFilters) {
   return andPass && orPass;
 }
 
-const DISPLAY_SKIP = new Set(["timestamp", "projectCode", "serviceId", "moduleMethod", "traceId", "level", "message", "duration"]);
+const DISPLAY_SKIP = new Set([
+  "timestamp",
+  "projectCode",
+  "serviceId",
+  "module",
+  "method",
+  "moduleMethod",
+  "traceId",
+  "level",
+  "message",
+  "duration",
+]);
 
 function filterDisplayField(f) {
   if (f.field === "has" || f.field === "missing") return f.value;
   return f.field;
 }
 
+function appendSnapshot(filePath, entry, saveLimit) {
+  try {
+    let lines = [];
+    if (fs.existsSync(filePath)) {
+      lines = fs.readFileSync(filePath, "utf8").split("\n").filter(Boolean);
+    }
+    lines.push(JSON.stringify(entry));
+    if (lines.length > saveLimit) lines = lines.slice(lines.length - saveLimit);
+    fs.writeFileSync(filePath, lines.join("\n") + "\n");
+  } catch {}
+}
+
 module.exports = async function logsCommand(
   projectCode,
   namespace,
-  { uiUrl, level, limit = 50, clear, current, verbose, filter, or: orFilters, include },
+  {
+    uiUrl,
+    level,
+    limit = 300,
+    clear,
+    current,
+    follow,
+    verbose,
+    filter,
+    or: orFilters,
+    include,
+    json,
+    save,
+    saved,
+    saveLimit = 500,
+  },
 ) {
   const andFilters = parseFilters(filter);
   const orFiltersParsed = parseFilters(orFilters);
@@ -119,6 +165,51 @@ module.exports = async function logsCommand(
     ...(include || []),
   ].filter((f, i, arr) => !DISPLAY_SKIP.has(f) && arr.indexOf(f) === i);
 
+  const savePath =
+    save && typeof save === "string"
+      ? path.resolve(process.cwd(), save)
+      : path.resolve(process.cwd(), DEFAULT_SNAPSHOT);
+
+  const printEntry = (entry) => {
+    if (json) {
+      console.log(JSON.stringify(entry));
+      return;
+    }
+    console.log(formatRow(entry, verbose, extraFields));
+  };
+
+  // --saved: read local snapshot, no live streaming
+  if (saved) {
+    if (!fs.existsSync(savePath)) {
+      log.warn(`No snapshot found at: ${savePath}`);
+      return;
+    }
+    let entries = [];
+    try {
+      entries = fs
+        .readFileSync(savePath, "utf8")
+        .split("\n")
+        .filter(Boolean)
+        .map((l) => JSON.parse(l));
+    } catch (err) {
+      log.error("Failed to read snapshot: " + err.message);
+      return;
+    }
+    if (namespace)
+      entries = entries.filter(
+        (e) => e.moduleMethod && e.moduleMethod.includes(namespace),
+      );
+    if (andFilters.length || orFiltersParsed.length)
+      entries = entries.filter((e) => matchesFilters(e, andFilters, orFiltersParsed));
+    if (level) entries = entries.filter((e) => e.level === level);
+    entries = entries.slice(-limit);
+    console.log("");
+    console.log(chalk.bold(`  Snapshot: ${savePath}  (${entries.length} entries)`));
+    console.log("");
+    entries.forEach(printEntry);
+    return;
+  }
+
   let services = [];
   let effectiveNamespace = namespace;
 
@@ -137,10 +228,13 @@ module.exports = async function logsCommand(
         const projects = await SystemView.getProjects();
         const all = Object.values(projects).flat();
         const isNamespace = all.some(({ system }) =>
-          (system.connectionData.modules || []).some(({ name, methods }) =>
-            name.toLowerCase().includes(projectCode.toLowerCase()) ||
-            (methods || []).some(({ fn }) => fn.toLowerCase().includes(projectCode.toLowerCase()))
-          )
+          (system.connectionData.modules || []).some(
+            ({ name, methods }) =>
+              name.toLowerCase().includes(projectCode.toLowerCase()) ||
+              (methods || []).some(({ fn }) =>
+                fn.toLowerCase().includes(projectCode.toLowerCase()),
+              ),
+          ),
         );
         if (isNamespace) {
           services = all;
@@ -163,7 +257,10 @@ module.exports = async function logsCommand(
 
   if (clear) {
     const confirmed = await promptConfirm("Clear all logs? (y/N) ");
-    if (!confirmed) { log.warn("Aborted."); return; }
+    if (!confirmed) {
+      log.warn("Aborted.");
+      return;
+    }
     for (const { system } of services) {
       try {
         const svc = await Client.loadService(system.connectionData.serviceUrl);
@@ -185,32 +282,64 @@ module.exports = async function logsCommand(
     try {
       const svc = await Client.loadService(serviceUrl);
       const unsub = svc.SystemView.on("log", (entry) => {
-        if (effectiveNamespace && !(entry.moduleMethod && entry.moduleMethod.includes(effectiveNamespace))) return;
+        if (
+          effectiveNamespace &&
+          !(entry.moduleMethod && entry.moduleMethod.includes(effectiveNamespace))
+        )
+          return;
         if (andFilters.length || orFiltersParsed.length) {
           if (!matchesFilters(entry, andFilters, orFiltersParsed)) return;
         }
         if (level && entry.level !== level) return;
-        console.log(formatRow(entry, verbose, extraFields));
+        if (save) appendSnapshot(savePath, entry, saveLimit);
+        printEntry(entry);
+        if (queryUrl && !json && entry.traceId) {
+          const sep = queryUrl.includes("?") ? "&" : "?";
+          console.log(`      ${chalk.dim(queryUrl + sep + "traceId=" + encodeURIComponent(entry.traceId))}`);
+        }
+        console.log("");
       });
-      console.log(`    ${chalk.green("✓")} ${chalk.cyan(serviceId).padEnd(20)} ${chalk.dim(serviceUrl)}`);
+      console.log(
+        `    ${chalk.green("✓")} ${chalk.cyan(serviceId).padEnd(20)} ${chalk.dim(serviceUrl)}`,
+      );
       connected.push({ serviceId, svc, unsub });
     } catch {
-      console.log(`    ${chalk.red("✗")} ${chalk.cyan(serviceId).padEnd(20)} ${chalk.dim(serviceUrl)} ${chalk.red("(failed to connect)")}`);
+      console.log(
+        `    ${chalk.red("✗")} ${chalk.cyan(serviceId).padEnd(20)} ${chalk.dim(serviceUrl)} ${chalk.red("(failed to connect)")}`,
+      );
     }
   }
 
+  if (save) {
+    console.log(chalk.dim(`  Snapshot: ${savePath}  (limit ${saveLimit})`));
+  }
+
   const activeFilters = [];
-  if (effectiveNamespace) activeFilters.push(`namespace: ${chalk.white(effectiveNamespace)}`);
+  if (effectiveNamespace)
+    activeFilters.push(`namespace: ${chalk.white(effectiveNamespace)}`);
   if (level) activeFilters.push(`level: ${chalk.white(level)}`);
-  if (andFilters.length) activeFilters.push(`filter: ${chalk.white(andFilters.map((f) => `${f.field}=${f.value}`).join(", "))}`);
-  if (orFiltersParsed.length) activeFilters.push(`or: ${chalk.white(orFiltersParsed.map((f) => `${f.field}=${f.value}`).join(", "))}`);
-  if (extraFields.length) activeFilters.push(`include: ${chalk.white(extraFields.join(", "))}`);
+  if (andFilters.length)
+    activeFilters.push(
+      `filter: ${chalk.white(andFilters.map((f) => `${f.field}=${f.value}`).join(", "))}`,
+    );
+  if (orFiltersParsed.length)
+    activeFilters.push(
+      `or: ${chalk.white(orFiltersParsed.map((f) => `${f.field}=${f.value}`).join(", "))}`,
+    );
+  if (extraFields.length)
+    activeFilters.push(`include: ${chalk.white(extraFields.join(", "))}`);
   if (verbose) activeFilters.push(`verbose: ${chalk.white("on")}`);
+  const queryUrl = uiUrl ? buildLogsUrl(uiUrl, { projectCode, effectiveNamespace, level, andFilters, orFilters }) : null;
+
   if (activeFilters.length) {
     console.log("");
     console.log(chalk.dim(`  Filters:`));
     activeFilters.forEach((f) => console.log(`    ${chalk.dim(f)}`));
   }
+  if (queryUrl && !json) {
+    console.log("");
+    console.log(`  ${chalk.dim("UI:")} ${chalk.cyan(queryUrl)}`);
+  }
   console.log("");
 
   if (!connected.length) {
@@ -224,22 +353,54 @@ module.exports = async function logsCommand(
       try {
         let entries = await svc.SystemView.getLog({ limit });
         entries = entries || [];
-        if (effectiveNamespace) entries = entries.filter((e) => e.moduleMethod && e.moduleMethod.includes(effectiveNamespace));
-        if (andFilters.length || orFiltersParsed.length) entries = entries.filter((e) => matchesFilters(e, andFilters, orFiltersParsed));
+        if (effectiveNamespace)
+          entries = entries.filter(
+            (e) => e.moduleMethod && e.moduleMethod.includes(effectiveNamespace),
+          );
+        if (andFilters.length || orFiltersParsed.length)
+          entries = entries.filter((e) => matchesFilters(e, andFilters, orFiltersParsed));
         if (level) entries = entries.filter((e) => e.level === level);
         allEntries.push(...entries);
       } catch {}
     }
     if (allEntries.length) {
       console.log(chalk.dim(`  ── current (${allEntries.length}) ──`));
-      allEntries.forEach((e) => console.log(formatRow(e, verbose, extraFields)));
-      console.log(chalk.dim(`  ── streaming ──`));
+      allEntries.forEach((entry) => {
+        printEntry(entry);
+        if (queryUrl && !json && entry.traceId) {
+          const sep = queryUrl.includes("?") ? "&" : "?";
+          console.log(`      ${chalk.dim(queryUrl + sep + "traceId=" + encodeURIComponent(entry.traceId))}`);
+        }
+        console.log("");
+      });
     }
+
+    if (!follow) {
+      connected.forEach(({ unsub }) => unsub());
+      return () => {};
+    }
+    console.log(chalk.dim(`  ── streaming ──`));
   }
 
-  return () => { connected.forEach(({ unsub }) => unsub()); };
+  return () => {
+    connected.forEach(({ unsub }) => unsub());
+  };
 };
 
+function buildLogsUrl(uiUrl, { projectCode, effectiveNamespace, level, andFilters, orFilters }) {
+  const params = new URLSearchParams();
+  if (projectCode && effectiveNamespace !== projectCode) params.set("project", projectCode);
+  if (effectiveNamespace) params.set("method", effectiveNamespace);
+  if (level) params.set("level", level);
+  for (const f of andFilters || []) {
+    if (f.field === "has") params.append("has", f.value);
+    else if (f.field === "missing") params.append("missing", f.value);
+    else params.set(f.field, f.value);
+  }
+  const q = params.toString();
+  return `${uiUrl}/logs${q ? "?" + q : ""}`;
+}
+
 function promptConfirm(question) {
   return new Promise((resolve) => {
     process.stdout.write(question);

package/cli/openBrowser.js

@@ -8,7 +8,7 @@ module.exports = function openBrowser(url, project_code, namespace, connectedSer
   }
 
   const browserCommand = process.platform === "win32" ? "start" : "open";
-  const code = project_code ? "/" + project_code : "";
+  const code = project_code ? "/specs/" + project_code : "/specs";
 
   if (namespace && connectedServices && connectedServices.length) {
     const matches = resolveNamespace(namespace, connectedServices);

package/cli/startLineReader.js

@@ -8,13 +8,23 @@ const logsCommand = require("./logs");
 const log = require("./logger");
 const cli = require("./utils/cli");
 const readline = require("readline");
+const { createClient } = require("systemlynx");
+const { createCookieHttpClient } = require("./cookieClient");
+const Client = createClient(createCookieHttpClient());
 
-module.exports = function startLineReader(url, { connectedUrls = new Set() } = {}) {
+module.exports = async function startLineReader(url, { connectedUrls = new Set() } = {}) {
   const lineReader = readline.createInterface({
     input: process.stdin,
     output: process.stdout,
   });
 
+  let CLI = null;
+  try {
+    ({ CLI } = await Client.loadService(`${url}/systemview/api`));
+    const history = await CLI.getHistory();
+    lineReader.history = [...history].reverse();
+  } catch {}
+
   let stopLogs = null;
 
   const parseArgs = (args) => {
@@ -36,12 +46,18 @@ module.exports = function startLineReader(url, { connectedUrls = new Set() } = {
       }
       else if (args[i] === "--verbose") { flags.verbose = true; }
       else if (args[i] === "--current") { flags.current = true; }
+      else if (args[i] === "--follow" || args[i] === "-f") { flags.follow = true; }
+      else if (args[i] === "--clear") { flags.clear = true; }
       else if (args[i] === "--json") { flags.json = true; }
       else if (args[i] === "--bail") { flags.bail = true; }
       else if (args[i] === "--dry-run") { flags.dryRun = true; }
       else if (args[i] === "--force") { flags.force = true; }
       else if (args[i] === "--manifest") { flags.useManifest = true; }
-      else if (!args[i].startsWith("--")) { positional.push(args[i]); }
+      else if (args[i] === "--saved") { flags.saved = true; }
+      else if (args[i] === "--save" && args[i + 1] && !args[i + 1].startsWith("-")) { flags.save = args[++i]; }
+      else if (args[i] === "--save") { flags.save = true; }
+      else if (args[i] === "--save-limit" && args[i + 1]) { flags.saveLimit = parseInt(args[++i], 10); }
+      else if (!args[i].startsWith("-")) { positional.push(args[i]); }
     }
     return { flags, positional };
   };
@@ -52,8 +68,22 @@ module.exports = function startLineReader(url, { connectedUrls = new Set() } = {
     if (!command) { lineReader.prompt(); return; }
     const { flags, positional } = parseArgs(parts.slice(1));
 
-    if (["exit", "q", "shutdown", "stop"].includes(command)) {
+    if (["exit", "q"].includes(command)) {
       process.exit(0);
+    } else if (["stop", "shutdown"].includes(command)) {
+      const api = `${url}/systemview/api`;
+      try {
+        const { SystemView } = await Client.loadService(api);
+        await SystemView.shutdown();
+      } catch {}
+      const appIsRunning = require("./appIsRunning");
+      if (!(await appIsRunning(api))) {
+        log.success("SystemView stopped.");
+        process.exit(0);
+      } else {
+        log.error("Shutdown failed.");
+        lineReader.prompt();
+      }
     } else if (command === "test") {
       try {
         await runTests(url, positional[0], positional[1], {
@@ -137,7 +167,13 @@ module.exports = function startLineReader(url, { connectedUrls = new Set() } = {
   };
 
   lineReader.prompt();
-  lineReader.on("line", handleInput);
+  lineReader.on("line", async (input) => {
+    const trimmed = input.trim();
+    if (trimmed && CLI) {
+      try { await CLI.saveHistory(trimmed); } catch {}
+    }
+    handleInput(trimmed);
+  });
   lineReader.on("close", () => process.exit(0));
   return lineReader;
 };

package/cli/utils/cli.js

@@ -9,18 +9,19 @@ const HELP_TEXT = `
     test <projectCode> [namespace]         Run saved tests for a project
     list [projectCode] [namespace]         List projects, services, or tests
     logs [projectCode] [namespace]         Stream log entries from connected services
-    stoplogs                               Stop streaming logs (keeps log file)
-    clearlogs                              Wipe the log file and stop streaming
+    unsubscribe                            Stop streaming logs (keeps log file)  [alias: stoplogs]
+    flush                                  Wipe the log file and stop streaming  [alias: clearlogs]
     connect [url|projectCode]             Connect a service URL, reconnect a stored project, or connect all
     connect <url> --manifest              Connect via plugin manifest — registers under real projectCode
     disconnect [projectCode] [serviceId]  Remove a project or service from the UI store
     manifest clean                        Re-probe manifest entries, remove stale ones
     probe <ServiceId.Module.method> [args] Call a service method ad-hoc
     open [projectCode] [namespace]         Open the browser UI
-    shutdown [port]                        Stop a running SystemView instance
+    shutdown [port]                        Stop a running SystemView instance  [aliases: exit, stop, q]
 
   Flags:
     --version                              Print version and exit
+    -d, --debug                            Verbose debug output
     --json                                 Output results as JSON (for agents/CI)
     --verbose                              test: full results and args for all phases; list: expand hierarchy
     --manifest                             connect: use plugin manifest to get real projectCode
@@ -31,12 +32,19 @@ const HELP_TEXT = `
     --dry-run                              Print which tests would run without executing
     --phase <before|main|events|after>     Run only specified phase(s), comma-separated
     --index <n>                            Run only action at index n within each phase (0-based)
-    --level <trace|info|warn|error|debug>  logs: filter by level
+    --level <trace|log|warn|error|debug>   logs: filter by level
     --limit <n>                            logs: max entries to show with --current (default 50)
-    --current                              logs: show existing entries before streaming
-    --filter <field=value>                 logs: AND filter on a field (repeatable)
+    --current                              logs: show existing entries (use --follow to also stream)
+    -f, --follow                           logs: keep streaming after --current
+    --clear                                logs: wipe log store then stream
+    --filter <field=value>                 logs: AND filter on a field (repeatable); field can be a dot path
+    --filter has=<field>                     → only entries where field is present
+    --filter missing=<field>                 → only entries where field is absent
     --or <field=value>                     logs: OR filter on a field (repeatable)
-    --include <field>                      logs: include extra field in output (repeatable)
+    --include <field>                      logs: include extra field as a column (repeatable)
+    --save [path]                          logs: append streamed entries to a local snapshot file
+    --saved                                logs: read from local snapshot instead of live service
+    --save-limit <n>                       logs: max entries to keep in snapshot (default 500)
     --force                                connect: re-probe even if already connected
 
   Examples:
@@ -50,7 +58,12 @@ const HELP_TEXT = `
     systemview list buAPI --verbose
     systemview logs buAPI
     systemview logs buAPI --current --limit 20
+    systemview logs buAPI --current --follow
     systemview logs buAPI --filter level=error
+    systemview logs buAPI --filter has=log.userId
+    systemview logs buAPI --filter missing=error --include log
+    systemview logs buAPI --save
+    systemview logs buAPI --saved
     systemview connect http://localhost:4100/bu/api/profiles
     systemview connect http://localhost:4100/bu/api/profiles --manifest
     systemview connect buAPI
@@ -63,7 +76,7 @@ const HELP_TEXT = `
 
 const rawArgs = process.argv.slice(2);
 
-const flagValueArgs = ["--manifest", "--header", "--skip", "--phase", "--index", "--level", "--limit", "--follow", "--filter", "--or", "--include"];
+const flagValueArgs = ["--manifest", "--header", "--skip", "--phase", "--index", "--level", "--limit", "--follow", "--filter", "--or", "--include", "--save", "--save-limit"];
 
 const flags = {
   json: rawArgs.includes("--json"),
@@ -121,6 +134,19 @@ const flags = {
   })(),
   clear: rawArgs.includes("--clear"),
   force: rawArgs.includes("--force"),
+  save: (() => {
+    const i = rawArgs.indexOf("--save");
+    if (i === -1) return false;
+    const next = rawArgs[i + 1];
+    return (next && !next.startsWith("-")) ? next : true;
+  })(),
+  saved: rawArgs.includes("--saved"),
+  saveLimit: (() => {
+    const i = rawArgs.indexOf("--save-limit");
+    if (i === -1) return 500;
+    const val = parseInt(rawArgs[i + 1], 10);
+    return isNaN(val) ? 500 : val;
+  })(),
   headers: (() => {
     const result = {};
     rawArgs.forEach((a, i) => {