c8ctl-plugin-nano 1.7.1 → 1.8.0

package/README.md

@@ -169,6 +169,21 @@ and the history cap.
 > ⚠️ With `--in-memory`, restart recovers nothing, and Raft/replicated logs are
 > not persisted. Use it for stress/throughput testing, not durability testing.
 
+## Console profile (`--console` / `--profile`)
+
+The server ships a browser console. Pick how much of it is exposed at runtime:
+
+```bash
+c8ctl nano start                      # studio (default): full IDE + authoring API
+c8ctl nano start --console observe    # observability views only; authoring refused (403)
+c8ctl nano start --console off        # headless: no console router at all
+```
+
+- Values: `studio` (default), `observe`, `off`. `--profile` is an alias for
+  `--console`, and an inherited `NANOBPMN_CONSOLE` env var is honored when neither
+  flag is passed. The plugin passes the choice through as `NANOBPMN_CONSOLE` on
+  every node.
+
 ## Configuration (`set` / `config`)
 
 Persistent settings are stored in `<state home>/config.json`:

package/c8ctl-plugin.js

@@ -13,13 +13,15 @@
  *   NANOBPMN_RF        replication factor (1 = single-homed, no Raft)
  *   NANOBPMN_RAFT      set when RF > 1 to enable per-partition Raft
  *   NANOBPMN_DATA_DIR  this node's engine data directory
+ *   NANOBPMN_CONSOLE   runtime console profile (off | observe | studio)
+ *   NANOBPMN_NODE_BIN  Node path for the server's worker fallback runtime
  *
  * This plugin spawns N detached node processes wired to talk to each other on
  * localhost, tracks them in a state file, and stops them on request.
  *
  * Usage:
  *   c8ctl nano start [<nodes>] [--port <basePort>] [--partitions <n>] [--rf <n>]
- *                    [--in-memory] [--history-max <n>]
+ *                    [--in-memory] [--history-max <n>] [--console <profile>]
  *   c8ctl nano status
  *   c8ctl nano stop [--purge]
  *   c8ctl nano logs [<nodeId>] [--follow]
@@ -37,9 +39,10 @@ import {
   readdirSync,
   chmodSync,
   renameSync,
+  realpathSync,
 } from 'node:fs';
 import { homedir, platform as osPlatform } from 'node:os';
-import { join, isAbsolute, resolve as resolvePath, dirname } from 'node:path';
+import { join, isAbsolute, resolve as resolvePath, dirname, sep } from 'node:path';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { platformForHost } from './platforms.mjs';
@@ -333,6 +336,18 @@ function findBinary(flags) {
  */
 function launcherEnvMarkers(resolved) {
   const markers = { NANOBPMN_LAUNCHER: 'c8ctl-plugin-nano' };
+
+  // This launcher IS a Node runtime, so hand the server a known-good Node path
+  // for its worker fallback (Deno-preferred, Node >= 22.6). Avoid pinning an
+  // older Node runtime (the plugin supports Node >=18) so the server can still
+  // fall back to a newer Node on PATH when available.
+  const [nodeMajor, nodeMinor, nodePatch] = process.versions.node
+    .split('.')
+    .map((n) => Number.parseInt(n, 10));
+  const nodeOk =
+    nodeMajor > 22 ||
+    (nodeMajor === 22 && (nodeMinor > 6 || (nodeMinor === 6 && nodePatch >= 0)));
+  if (nodeOk) markers.NANOBPMN_NODE_BIN = process.execPath;
   const { version } = pluginPackage();
   // The plugin version is the update unit's "current" in the npm channel's
   // version space (same space as `npm view <plugin> version` -> latest), so the
@@ -380,6 +395,7 @@ function parseRequest(args, flags) {
     capture: Boolean(flags?.capture),
     inMemory: Boolean(flags?.['in-memory'] || flags?.['no-journal']),
     historyMax: intFlag('history-max'),
+    console: flags?.console ?? flags?.profile,
     workspace: Boolean(flags?.workspace),
     check: Boolean(flags?.check),
     binary: flags?.binary,
@@ -528,6 +544,26 @@ async function waitForHealthy(url, timeoutMs = READINESS_TIMEOUT_MS) {  const st
 // start
 // ---------------------------------------------------------------------------
 
+/** Runtime console profiles the server understands (nano-bpm ADR 0035 §C). */
+const CONSOLE_PROFILES = ['off', 'observe', 'studio'];
+
+/**
+ * Resolves the runtime console profile to pass through as NANOBPMN_CONSOLE.
+ * Precedence: --console/--profile flag > inherited NANOBPMN_CONSOLE env >
+ * 'studio' (the full IDE, our default). Unknown values are rejected so a typo
+ * fails fast here rather than silently degrading the console in the server.
+ */
+function resolveConsoleProfile(reqConsole) {
+  const raw = reqConsole ?? process.env.NANOBPMN_CONSOLE ?? 'studio';
+  const profile = String(raw).trim().toLowerCase();
+  if (!CONSOLE_PROFILES.includes(profile)) {
+    throw new Error(
+      `invalid console profile "${raw}" (use one of: ${CONSOLE_PROFILES.join(', ')})`,
+    );
+  }
+  return profile;
+}
+
 async function startCluster(req) {
   const logger = getLogger();
 
@@ -556,6 +592,7 @@ async function startCluster(req) {
   const capture = Boolean(req.capture);
   const inMemory = Boolean(req.inMemory);
   const historyMax = req.historyMax;
+  const consoleProfile = resolveConsoleProfile(req.console);
 
   if (partitions < nodeCount) {
     logger.warn(
@@ -629,7 +666,8 @@ async function startCluster(req) {
     `Starting Nano BPM cluster: ${nodeCount} node(s), ${partitions} partition(s), ` +
       `RF=${rf}${raft ? ', Raft on' : ''}${capture ? ', trace capture on' : ''}` +
       `${inMemory ? ', in-memory (no disk)' : ''}` +
-      `${historyMax !== undefined ? `, history-max=${historyMax}` : ''}`,
+      `${historyMax !== undefined ? `, history-max=${historyMax}` : ''}` +
+      `${consoleProfile !== 'studio' ? `, console=${consoleProfile}` : ''}`,
   );
   logger.info(`Binary:    ${binary}`);
   logger.info(`Workspace: ${workspaceDir} (models/, workers/)`);
@@ -666,6 +704,10 @@ async function startCluster(req) {
       // Shared, persistent authoring workspace (models + workers). Lives
       // outside the per-node data dir so "nano clean" never wipes it.
       NANOBPMN_WORKSPACE_DIR: workspaceDir,
+      // Runtime console profile (off | observe | studio). Default studio (full
+      // IDE); pass-through so --console/--profile or an inherited NANOBPMN_CONSOLE
+      // picks the observability-only or headless surface. See nano-bpm ADR 0035 §C.
+      NANOBPMN_CONSOLE: consoleProfile,
     };
     // Storage axis: an on-disk journal + read-model under the per-node data dir
     // (default), or a fully in-memory engine (in-memory journal + :memory: read
@@ -1308,6 +1350,51 @@ function isGlobalInstall() {
   return Boolean(root) && pluginDir.startsWith(root);
 }
 
+/**
+ * How this plugin is installed, which decides how `nano update` self-updates:
+ *   - 'managed': under c8ctl's own plugin store (…/c8ctl/plugins/node_modules),
+ *       where `c8ctl load plugin` installed it. Self-update in place by
+ *       reinstalling into that same npm --prefix. This is the norm for the
+ *       integrated c8ctl plugin architecture, so it takes precedence over a
+ *       coincidental global install of the same name.
+ *   - 'global': under `npm root -g` (a plain `npm install -g`).
+ *   - 'local':  a checkout / `npm link` — self-update isn't safe; tell the user.
+ */
+function pluginInstallInfo() {
+  const rt = globalThis.c8ctl;
+  if (rt && typeof rt.getUserDataDir === 'function') {
+    try {
+      // Node resolves symlinks when computing this module's path, so realpath
+      // both sides before comparing (e.g. macOS /var → /private/var, or a
+      // C8CTL_DATA_DIR that isn't canonicalized) to avoid a false 'local'.
+      const real = (p) => {
+        try {
+          return realpathSync(p);
+        } catch {
+          return p;
+        }
+      };
+      const pluginsDir = join(rt.getUserDataDir(), 'plugins');
+      const nm = real(join(pluginsDir, 'node_modules'));
+      const self = real(pluginDir);
+      if (self === nm || self.startsWith(nm + sep)) {
+        return { mode: 'managed', prefix: real(pluginsDir) };
+      }
+    } catch {
+      /* fall through to the global/local probes */
+    }
+  }
+  if (isGlobalInstall()) return { mode: 'global' };
+  return { mode: 'local' };
+}
+
+/** The copy-pasteable command that matches how this plugin is installed. */
+function manualUpdateCommand(name, info) {
+  if (info.mode === 'managed') return `  c8ctl load plugin ${name}@latest`;
+  if (info.mode === 'local') return '  git pull   # in your checkout, then reload the plugin';
+  return `  npm install -g ${name}@latest`;
+}
+
 function updatePlugin(req) {
   const { name, version: current } = pluginPackage();
 
@@ -1326,7 +1413,8 @@ function updatePlugin(req) {
   const nanoNote = nanoBin
     ? `  (nano server ${nanoVer ?? bundled?.version ?? 'present'})`
     : '  (nano server: not installed for this platform)';
-  const manual = `  npm install -g ${name}@latest`;
+  const info = pluginInstallInfo();
+  const manual = manualUpdateCommand(name, info);
 
   console.log(`Installed: ${name} v${current ?? '?'}${nanoNote}`);
 
@@ -1362,26 +1450,42 @@ function updatePlugin(req) {
     return;
   }
 
-  if (!isGlobalInstall()) {
-    console.log('This plugin is not a global npm install, so it cannot self-update in place.');
-    console.log('Pull the latest release with:');
+  if (info.mode === 'local') {
+    console.log('This plugin runs from a local checkout, so it cannot self-update in place.');
+    console.log('Update it with:');
     console.log(manual);
-    console.log('(or, for a local checkout, `git pull` then reload the plugin).');
     return;
   }
 
-  console.log(`Pulling ${name}@${latest} via npm...`);
+  const installArgs =
+    info.mode === 'managed'
+      ? ['install', `${name}@${latest}`, '--prefix', info.prefix]
+      : ['install', '-g', `${name}@${latest}`];
+  const where = info.mode === 'managed' ? 'the c8ctl plugin store' : "npm's global prefix";
+  console.log(`Pulling ${name}@${latest} into ${where}...`);
   console.log('');
-  const res = spawnSync('npm', ['install', '-g', `${name}@${latest}`], { stdio: 'inherit' });
+  const res = spawnSync('npm', installArgs, { stdio: 'inherit' });
   if (res.error) throw new Error(res.error.message);
   if (res.status !== 0) {
+    let hint;
+    if (info.mode === 'managed') {
+      hint = `You can also run:\n${manual}`;
+    } else if (osPlatform() === 'win32') {
+      hint = `You may need to run this command in an elevated terminal (Administrator): ${manual.trim()}`;
+    } else {
+      hint = `You may need elevated permissions: sudo ${manual.trim()}`;
+    }
     throw new Error(
-      `npm install -g ${name}@${latest} failed (exit ${res.status}). ` +
-        `You may need elevated permissions: sudo ${manual.trim()}`,
+      `npm ${installArgs.join(' ')} failed (exit ${res.status}). ${hint}`,
     );
   }
   console.log('');
-  console.log(`Updated to v${latest}. Restart any running cluster to use the new binary:`);
+  if (info.mode === 'managed') {
+    console.log(`Updated to v${latest}. The new plugin and bundled nano server load on your next c8ctl command.`);
+  } else {
+    console.log(`Updated to v${latest}.`);
+  }
+  console.log('Restart any running cluster to use the new server binary:');
   console.log('  c8ctl nano restart');
 }
 
@@ -1449,12 +1553,13 @@ function spawnUpdateRefresh(name, cacheFile) {
 }
 
 function printUpdateNotice(name, current, latest) {
+  const manual = manualUpdateCommand(name, pluginInstallInfo()).trim();
   const lines = [
     '',
     `╭─ Update available: ${name} v${current} → v${latest}`,
     '│  A newer nano release (plugin + bundled server) is published on npm.',
     '│  Install it:  c8ctl nano update',
-    `│  Or manually: npm install -g ${name}@latest`,
+    `│  Or manually: ${manual}`,
     '╰─ Then restart any running cluster: c8ctl nano restart',
     '',
   ];
@@ -2476,6 +2581,8 @@ export const commands = {
       'in-memory': { type: 'boolean', description: 'start: run with NO on-disk journal/read-model (in-memory engine; state lost on restart). Alias: --no-journal' },
       'no-journal': { type: 'boolean', description: 'start: alias for --in-memory' },
       'history-max': { type: 'string', description: 'start: cap retained terminal instances in the read model (NANOBPMN_HISTORY_MAX_INSTANCES; 0/unset = unbounded)' },
+      console: { type: 'string', description: 'start: runtime console profile off|observe|studio (NANOBPMN_CONSOLE; default studio). Alias: --profile' },
+      profile: { type: 'string', description: 'start: alias for --console (off|observe|studio; default studio)' },
       follow: { type: 'boolean', description: 'logs: stream output (tail -F)', short: 'f' },
       purge: { type: 'boolean', description: 'stop/restart: also delete per-node engine data' },
       force: { type: 'boolean', description: 'start: stop any existing cluster first' },
@@ -2607,7 +2714,7 @@ export const commands = {
 
 function printUsage() {
   console.log('Usage:');
-  console.log('  c8ctl nano start [<nodes>] [--port <basePort>] [--partitions <n>] [--rf <n>] [--raft] [--capture] [--in-memory] [--history-max <n>] [--binary <path>]');
+  console.log('  c8ctl nano start [<nodes>] [--port <basePort>] [--partitions <n>] [--rf <n>] [--raft] [--capture] [--in-memory] [--history-max <n>] [--console <profile>] [--binary <path>]');
   console.log('  c8ctl nano status [--port <port>]');
   console.log('  c8ctl nano stop [--purge]');
   console.log('  c8ctl nano logs [<nodeId>] [--follow]');
@@ -2641,6 +2748,7 @@ function printUsage() {
   console.log('  --capture            start: enable trace capture (recorded-input replay) on every node');
   console.log('  --in-memory          start: run with NO on-disk journal/read-model (alias --no-journal; state lost on restart)');
   console.log('  --history-max <n>    start: cap retained terminal instances in the read model (0/unset = unbounded)');
+  console.log('  --console <profile>  start: runtime console profile off|observe|studio (alias --profile; default studio)');
   console.log('  --binary <path>      Path to the nanobpmn server binary (overrides "set bin")');
   console.log('  --purge              stop: also delete per-node engine data');
   console.log('  --force              start: stop any existing cluster first');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "type": "module",
   "description": "c8ctl plugin to start, inspect, and stop a local Nano BPM (nanobpmn) cluster",
   "main": "c8ctl-plugin.js",
@@ -49,12 +49,12 @@
     "semantic-release": "^25.0.3"
   },
   "optionalDependencies": {
-    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.7.1",
-    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.7.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.7.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.7.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.7.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.7.1",
-    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.7.1"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.8.0",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.8.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.8.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.8.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.8.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.8.0",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.8.0"
   }
 }