c8ctl-plugin-nano 1.0.0 → 1.1.0

package/README.md

@@ -124,6 +124,27 @@ Persistent settings are stored in `<state home>/config.json`:
 
 Show the effective configuration and all on-disk locations with `c8ctl nano config`.
 
+## Updating to a new release (`update`)
+
+The plugin and the bundled server binary (delivered via the matching platform
+package) ship together on npm as `c8ctl-plugin-nano`. To pull a new nanobpmn
+release onto a machine that already has nano installed:
+
+```bash
+c8ctl nano update          # check npm for a newer release and install it
+c8ctl nano update --check  # only report whether an update is available
+```
+
+`update` compares the installed plugin version against the latest published on
+npm. When a newer release exists it reinstalls the package globally
+(`npm install -g c8ctl-plugin-nano@latest`), which brings the new server binary
+with it. It only ever drives npm — it never touches the private upstream source —
+so it works for any npm-installed user. After updating, restart any running
+cluster (`c8ctl nano restart`) so it picks up the new binary.
+
+If the plugin is running from a local checkout rather than a global npm install,
+`update` prints the manual command instead of reinstalling in place.
+
 ## Checking status
 
 `c8ctl nano status` queries each node's always-on `GET /v2/topology`, which is the
@@ -261,8 +282,9 @@ The plugin needs a built `nanobpmn` server binary. Resolution order:
 1. `--binary <path>`
 2. configured path (`c8ctl nano set bin <path>`)
 3. `NANOBPMN_BINARY=<path>`
-4. the matching **platform package** (`c8ctl-plugin-nano-<os>-<arch>`), installed
-   automatically as an `optionalDependency` when you install the plugin from npm
+4. the matching **platform package** (`@nanobpm/c8ctl-plugin-nano-<os>-<arch>`),
+   installed automatically as an `optionalDependency` when you install the plugin
+   from npm
 5. `release` build under the nanobpmn repo
 6. `debug` build under the nanobpmn repo
 
@@ -426,15 +448,16 @@ publishes to npm, and creates a GitHub Release.
 ### Platform packages
 
 The server binary is shipped as a set of platform-specific npm packages, one per
-target, gated by npm's `os`/`cpu` fields:
+target, gated by npm's `os`/`cpu` fields. They are **scoped under `@nanobpm`** (a
+scope we own) so the names can never be squatted or npm-security-held:
 
-| package                          | os     | cpu   |
-|----------------------------------|--------|-------|
-| `c8ctl-plugin-nano-darwin-arm64` | darwin | arm64 |
-| `c8ctl-plugin-nano-darwin-x64`   | darwin | x64   |
-| `c8ctl-plugin-nano-linux-x64`    | linux  | x64   |
-| `c8ctl-plugin-nano-linux-arm64`  | linux  | arm64 |
-| `c8ctl-plugin-nano-win32-x64`    | win32  | x64   |
+| package                                    | os     | cpu   |
+|--------------------------------------------|--------|-------|
+| `@nanobpm/c8ctl-plugin-nano-darwin-arm64`  | darwin | arm64 |
+| `@nanobpm/c8ctl-plugin-nano-darwin-x64`    | darwin | x64   |
+| `@nanobpm/c8ctl-plugin-nano-linux-x64`     | linux  | x64   |
+| `@nanobpm/c8ctl-plugin-nano-linux-arm64`   | linux  | arm64 |
+| `@nanobpm/c8ctl-plugin-nano-win32-x64`     | win32  | x64   |
 
 The root `c8ctl-plugin-nano` lists all five as `optionalDependencies` (pinned to
 the exact release version, injected into the published tarball at release time).
@@ -487,7 +510,14 @@ with provenance (`NPM_CONFIG_PROVENANCE: true`, requires this repo to be public)
 Trusted Publishing is per-package and requires the package to already exist, so:
 
 1. **Bootstrap** the first release with a granular-automation `NPM_TOKEN` secret —
-   it is used automatically and creates all six packages.
+   it is used automatically and creates all six packages. The token must have
+   **publish rights to the `@nanobpm` scope** (the platform packages are scoped).
 2. On npmjs.com, add a **Trusted Publisher** (this repo + `release.yml`) for the
-   root package and each of the five platform packages.
+   root package and each of the five `@nanobpm/c8ctl-plugin-nano-*` platform
+   packages.
 3. Remove the `NPM_TOKEN` secret; subsequent releases authenticate via OIDC.
+
+> Note: because the platform packages are **scoped** (`@nanobpm/…`), they sidestep
+> the unscoped-name squatting/`0.0.1-security` hold that previously blocked
+> `c8ctl-plugin-nano-win32-x64`. If you ever add a new platform, its scoped name is
+> yours to publish immediately.

package/c8ctl-plugin.js

@@ -25,7 +25,7 @@
  *   c8ctl nano restart [<nodes>] ...
  */
 
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import {
   existsSync,
   mkdirSync,
@@ -63,8 +63,9 @@ function readBundledBinaryInfo() {
 
 /**
  * Locate the nanobpmn binary shipped by the matching platform package
- * (an optionalDependency such as c8ctl-plugin-nano-darwin-arm64). Returns the
- * absolute path, or undefined if the package isn't installed for this host.
+ * (an optionalDependency such as @nanobpm/c8ctl-plugin-nano-darwin-arm64).
+ * Returns the absolute path, or undefined if the package isn't installed for
+ * this host.
  */
 function findPlatformPackageBinary() {
   const p = platformForHost();
@@ -257,7 +258,7 @@ function findBinary(flags) {
 // Argument parsing
 // ---------------------------------------------------------------------------
 
-const VALID_SUBCOMMANDS = ['start', 'stop', 'status', 'logs', 'log', 'restart', 'pause', 'resume', 'clean', 'set', 'config'];
+const VALID_SUBCOMMANDS = ['start', 'stop', 'status', 'logs', 'log', 'restart', 'pause', 'resume', 'clean', 'set', 'config', 'update'];
 
 /**
  * Parse positional args + flags into a normalized request.
@@ -288,6 +289,7 @@ function parseRequest(args, flags) {
     force: Boolean(flags?.force),
     capture: Boolean(flags?.capture),
     workspace: Boolean(flags?.workspace),
+    check: Boolean(flags?.check),
     binary: flags?.binary,
   };
 }
@@ -1106,6 +1108,119 @@ function showConfig() {
   console.log('  Change with: c8ctl nano set bin <path> | c8ctl nano set model-dir <path>');
 }
 
+// ---------------------------------------------------------------------------
+// update — pull a new nanobpmn release onto a machine with an existing install.
+// The plugin (and the bundled server binary, shipped via the matching platform
+// package) is distributed on npm as c8ctl-plugin-nano, so a release is pulled by
+// reinstalling the package globally. We only ever drive npm here — never touch
+// the private upstream source — so this works for any npm-installed user.
+// ---------------------------------------------------------------------------
+
+/** This plugin package's identity, read from its own package.json. */
+function pluginPackage() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(pluginDir, 'package.json'), 'utf8'));
+    return { name: pkg.name || 'c8ctl-plugin-nano', version: pkg.version || null };
+  } catch {
+    return { name: 'c8ctl-plugin-nano', version: null };
+  }
+}
+
+/**
+ * Numeric semver comparison (major.minor.patch), ignoring any pre-release/build
+ * suffix. Returns -1 if a<b, 0 if equal, 1 if a>b.
+ */
+function compareSemver(a, b) {
+  const norm = (v) =>
+    String(v)
+      .replace(/^v/, '')
+      .split(/[-+]/)[0]
+      .split('.')
+      .map((n) => Number.parseInt(n, 10) || 0);
+  const av = norm(a);
+  const bv = norm(b);
+  for (let i = 0; i < 3; i++) {
+    const x = av[i] || 0;
+    const y = bv[i] || 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return 0;
+}
+
+/** Latest published version of `name` per the npm registry (throws on failure). */
+function npmLatestVersion(name) {
+  const res = spawnSync('npm', ['view', name, 'version'], { encoding: 'utf8' });
+  if (res.error) throw new Error(res.error.message);
+  if (res.status !== 0) {
+    throw new Error((res.stderr || '').trim() || `npm view exited ${res.status}`);
+  }
+  return res.stdout.trim();
+}
+
+/** True when this plugin lives under npm's global node_modules (so `-g` updates it). */
+function isGlobalInstall() {
+  const res = spawnSync('npm', ['root', '-g'], { encoding: 'utf8' });
+  if (res.status !== 0) return false;
+  const root = res.stdout.trim();
+  return Boolean(root) && pluginDir.startsWith(root);
+}
+
+function updatePlugin(req) {
+  const { name, version: current } = pluginPackage();
+  const bundled = readBundledBinaryInfo();
+  const nanoNote = bundled ? `  (bundled nano ${bundled.version})` : '';
+  const manual = `  npm install -g ${name}@latest`;
+
+  console.log(`Installed: ${name} v${current ?? '?'}${nanoNote}`);
+
+  let latest;
+  try {
+    latest = npmLatestVersion(name);
+  } catch (err) {
+    console.log(`Could not check npm for updates: ${err.message}`);
+    console.log('Pull the latest release manually with:');
+    console.log(manual);
+    return;
+  }
+  console.log(`Latest:    ${name} v${latest}  (npm)`);
+  console.log('');
+
+  if (current && compareSemver(current, latest) >= 0) {
+    console.log('Already on the latest release — nothing to do.');
+    return;
+  }
+
+  console.log(`Update available: v${current ?? '?'} -> v${latest}`);
+
+  if (req.check) {
+    console.log('Run `c8ctl nano update` to pull it (or manually):');
+    console.log(manual);
+    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:');
+    console.log(manual);
+    console.log('(or, for a local checkout, `git pull` then reload the plugin).');
+    return;
+  }
+
+  console.log(`Pulling ${name}@${latest} via npm...`);
+  console.log('');
+  const res = spawnSync('npm', ['install', '-g', `${name}@${latest}`], { stdio: 'inherit' });
+  if (res.error) throw new Error(res.error.message);
+  if (res.status !== 0) {
+    throw new Error(
+      `npm install -g ${name}@${latest} failed (exit ${res.status}). ` +
+        `You may need elevated permissions: sudo ${manual.trim()}`,
+    );
+  }
+  console.log('');
+  console.log(`Updated to v${latest}. Restart any running cluster to use the new binary:`);
+  console.log('  c8ctl nano restart');
+}
+
 // ---------------------------------------------------------------------------
 // processos — manage a single local ProcessOS instance (the optimization-plane
 // server that analyses a running Nano BPM engine). Unlike nano, the ProcessOS
@@ -1662,6 +1777,8 @@ export const metadata = {
         { command: 'c8ctl nano set bin <path>', description: 'Set the nanobpmn server binary path' },
         { command: 'c8ctl nano set model-dir <path>', description: 'Set the workspace dir (models + workers)' },
         { command: 'c8ctl nano config', description: 'Show current plugin configuration and paths' },
+        { command: 'c8ctl nano update', description: 'Pull the latest published nano release (re-installs via npm)' },
+        { command: 'c8ctl nano update --check', description: 'Check whether a newer nano release is available' },
       ],
     },
     processos: {
@@ -1695,6 +1812,7 @@ export const commands = {
       purge: { type: 'boolean', description: 'stop: also delete per-node engine data' },
       force: { type: 'boolean', description: 'start: stop any existing cluster first' },
       workspace: { type: 'boolean', description: 'clean: also delete the workspace (models + workers)' },
+      check: { type: 'boolean', description: 'update: only report whether a new release is available; do not install' },
       binary: { type: 'string', description: 'Path to the nanobpmn server binary' },
     },
     handler: async (args, flags) => {
@@ -1740,6 +1858,9 @@ export const commands = {
           case 'config':
             showConfig();
             break;
+          case 'update':
+            updatePlugin(req);
+            break;
         }
       } catch (error) {
         logger.error(`nano ${req.subcommand} failed: ${error instanceof Error ? error.message : error}`);
@@ -1812,6 +1933,7 @@ function printUsage() {
   console.log('  c8ctl nano clean [--workspace]');
   console.log('  c8ctl nano set <bin|model-dir> <path>');
   console.log('  c8ctl nano config');
+  console.log('  c8ctl nano update [--check]');
   console.log('');
   console.log('Subcommands:');
   console.log('  start    Spawn an N-node local cluster wired to talk to each other on localhost');
@@ -1824,6 +1946,7 @@ function printUsage() {
   console.log('  clean    Wipe journal/data + logs on disk (keeps models/workers)');
   console.log('  set      Persist a setting: "bin <path>" or "model-dir <path>"');
   console.log('  config   Show current configuration and on-disk locations');
+  console.log('  update   Pull the latest published nano release (--check to only report)');
   console.log('');
   console.log('Options:');
   console.log('  <nodes>              Number of nodes to start (default 1)');

package/nanobpmn-binary.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.1",
-  "commit": "ed49485",
-  "updated": "2026-06-28T06:34:54Z"
-}
+  "version": "0.0.2",
+  "commit": "44ad803",
+  "updated": "2026-06-30T06:04:34Z"
+}

package/package.json

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

package/platforms.mjs

@@ -2,7 +2,9 @@
  * Single source of truth for the platform-specific binary packages.
  *
  * Each entry maps a Node platform/arch pair to:
- *   - pkg:   the npm package name that carries the binary for that platform
+ *   - pkg:   the npm package name that carries the binary for that platform.
+ *            Scoped under @nanobpm (a scope we own) so the names can never be
+ *            squatted or npm-security-held the way an unscoped name can.
  *   - os:    the npm "os" field value (process.platform)
  *   - cpu:   the npm "cpu" field value (process.arch)
  *   - triple: the Rust target triple (informational; used by the Nano BPM CI)
@@ -19,7 +21,7 @@ export const BIN_BASENAME = 'nanobpm-gateway-rest-server';
 
 export const PLATFORMS = [
   {
-    pkg: 'c8ctl-plugin-nano-darwin-arm64',
+    pkg: '@nanobpm/c8ctl-plugin-nano-darwin-arm64',
     os: 'darwin',
     cpu: 'arm64',
     triple: 'aarch64-apple-darwin',
@@ -27,7 +29,7 @@ export const PLATFORMS = [
     bin: BIN_BASENAME,
   },
   {
-    pkg: 'c8ctl-plugin-nano-darwin-x64',
+    pkg: '@nanobpm/c8ctl-plugin-nano-darwin-x64',
     os: 'darwin',
     cpu: 'x64',
     triple: 'x86_64-apple-darwin',
@@ -35,7 +37,7 @@ export const PLATFORMS = [
     bin: BIN_BASENAME,
   },
   {
-    pkg: 'c8ctl-plugin-nano-linux-x64',
+    pkg: '@nanobpm/c8ctl-plugin-nano-linux-x64',
     os: 'linux',
     cpu: 'x64',
     triple: 'x86_64-unknown-linux-gnu',
@@ -43,7 +45,7 @@ export const PLATFORMS = [
     bin: BIN_BASENAME,
   },
   {
-    pkg: 'c8ctl-plugin-nano-linux-arm64',
+    pkg: '@nanobpm/c8ctl-plugin-nano-linux-arm64',
     os: 'linux',
     cpu: 'arm64',
     triple: 'aarch64-unknown-linux-gnu',
@@ -51,7 +53,7 @@ export const PLATFORMS = [
     bin: BIN_BASENAME,
   },
   {
-    pkg: 'c8ctl-plugin-nano-win32-x64',
+    pkg: '@nanobpm/c8ctl-plugin-nano-win32-x64',
     os: 'win32',
     cpu: 'x64',
     triple: 'x86_64-pc-windows-msvc',