c8ctl-plugin-nano 1.0.0 → 1.2.0

package/README.md

@@ -124,6 +124,43 @@ 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.
+
+### Automatic "update available" notice
+
+You don't have to remember to run `update --check`: any `nano` or `processos`
+command also surfaces a one-line notice when a newer release is published. It is
+deliberately unobtrusive:
+
+- The registry lookup runs in a **detached background process**, so a command is
+  never slowed down — the fresh result is used on the next invocation.
+- npm is queried at most **once per day**, and the notice is shown at most **once
+  per day** (state is cached under the plugin's state home in `update-check.json`).
+- The notice prints to **stderr**, so it never corrupts machine-readable stdout,
+  and is suppressed when stdout is not a TTY (piped/scripted) or when `CI` is set.
+
+To turn it off entirely, set `NANO_NO_UPDATE_NOTIFIER=1` (or the conventional
+`NO_UPDATE_NOTIFIER=1`). The explicit `c8ctl nano update` command is unaffected.
+
 ## Checking status
 
 `c8ctl nano status` queries each node's always-on `GET /v2/topology`, which is the
@@ -261,8 +298,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
 
@@ -332,14 +370,29 @@ ProcessOS is the optimization-plane server that analyses a running Nano BPM
 engine. The plugin can manage a single local ProcessOS instance with the same
 start/stop/status/logs lifecycle as `nano`.
 
-Unlike the Nano BPM server binary (which is distributed via npm — see below),
-**the ProcessOS binary is downloaded manually**: grab the build for your
-platform, then point the plugin at it.
+> **ProcessOS is a closed alpha.** The operational commands (`start`, `stop`,
+> `status`, `logs`, `restart`) stay locked with a *"not available yet"* notice
+> until you opt in. Only `set` and `config` work before then. Opt in either by
+> setting the download URL you were given by the Nano BPM team, or by pointing
+> the plugin at a binary you already have.
 
 ```bash
-# One-time: tell the plugin where the binary is
+# Closed-alpha channel: the plugin downloads + caches the matching binary
+export PROCESSOS_DOWNLOAD_URL=<url you were given>
+c8ctl processos start            # fetches processos-<os>-<arch> on first run
+
+# …or point the plugin at a binary you already have
 c8ctl processos set bin ~/Downloads/processos
+c8ctl processos start
+```
+
+`PROCESSOS_DOWNLOAD_URL` is the prefix the release binaries live under (e.g. the
+`…/processos/latest/` bucket URL). The plugin appends the per-platform asset name
+(`processos-darwin-arm64`, `processos-linux-x64`, `processos-win32-x64.exe`, …),
+downloads it to `<stateHome>/bin/`, marks it executable, and runs it. The cached
+download is reused on subsequent starts.
 
+```bash
 # Start ProcessOS against the local Nano BPM engine (http://localhost:8080)
 c8ctl processos start
 
@@ -352,6 +405,18 @@ c8ctl processos logs --follow
 c8ctl processos stop
 ```
 
+### Automatic update notice
+
+When you're on the closed-alpha channel (`PROCESSOS_DOWNLOAD_URL` set), the
+plugin checks for newer ProcessOS builds in the background and prints a short
+one-line notice (at most **once per day**) when the published version is newer
+than the one you're running. It compares your installed binary's version against
+the `version.json` the release pipeline publishes next to the binaries, never
+blocks the command (the check runs detached), and is suppressed on
+non-interactive shells, in CI, and when `NO_UPDATE_NOTIFIER` /
+`NANO_NO_UPDATE_NOTIFIER` is set. To update, stop and start ProcessOS again — a
+downloaded binary re-fetches the latest build; a `set bin` binary updates itself.
+
 On a successful `start` the summary leads with the landing page:
 
 ```
@@ -401,9 +466,10 @@ c8ctl processos config                  # show current settings and on-disk path
 ```
 
 The binary is resolved in this order: `--binary` flag → `set bin` →
-`$PROCESSOS_BINARY` → a local `processos/target/{release,debug}/processos` build.
-Typed settings (`port`, `nano-url`, `data-dir`) always win over generic `env`
-passthrough values when launching.
+`$PROCESSOS_BINARY` → a cached download under `<stateHome>/bin/` → a local
+`processos/target/{release,debug}/processos` build → a fresh download from
+`PROCESSOS_DOWNLOAD_URL`. Typed settings (`port`, `nano-url`, `data-dir`) always
+win over generic `env` passthrough values when launching.
 
 ## Installing
 
@@ -426,15 +492,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 +554,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,
@@ -34,6 +34,8 @@ import {
   writeFileSync,
   rmSync,
   readdirSync,
+  chmodSync,
+  renameSync,
 } from 'node:fs';
 import { homedir, platform as osPlatform } from 'node:os';
 import { join, isAbsolute, resolve as resolvePath, dirname } from 'node:path';
@@ -63,8 +65,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();
@@ -93,6 +96,23 @@ const PROCESSOS_STATE_FILE = 'processos.json';
 const PROCESSOS_DEFAULT_PORT = 8090;
 const DEFAULT_NANO_URL = 'http://localhost:8080';
 
+// Passive update notifier (npm-style): refresh the latest published version
+// from the registry in a detached background process at most once per day, and
+// surface a one-line "update available" notice at most once per day. Never
+// blocks a command and never fails one.
+const UPDATE_CACHE_FILE = 'update-check.json';
+const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+const UPDATE_NOTIFY_TTL_MS = 24 * 60 * 60 * 1000;
+
+// ProcessOS is a closed alpha distributed out-of-band: the binary lives in an
+// S3 bucket whose base URL is handed to enabled users via PROCESSOS_DOWNLOAD_URL.
+// `<base>/processos-<os>-<arch>[.exe]` is the per-platform binary and
+// `<base>/version.json` is the {version,commit,updated} metadata the CI writes
+// next to it (the analogue of npm's latest-version lookup for the nano plugin).
+const PROCESSOS_VERSION_META = 'version.json';
+const PROCESSOS_BINARY_META_FILE = 'processos-binary.json';
+const PROCESSOS_UPDATE_CACHE_FILE = 'processos-update-check.json';
+
 function getLogger() {
   if (globalThis.c8ctl) {
     return globalThis.c8ctl.getLogger();
@@ -257,7 +277,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 +308,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 +1127,232 @@ 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');
+}
+
+// ---------------------------------------------------------------------------
+// Passive "update available" notice. Modelled on npm's update-notifier: the
+// actual registry lookup runs in a detached background process (so a command is
+// never slowed), and we only print a notice — at most once per day — from a
+// cached result. The explicit `c8ctl nano update[ --check]` path is unchanged.
+// ---------------------------------------------------------------------------
+
+function getUpdateCacheFile() {
+  return join(getStateHome(), UPDATE_CACHE_FILE);
+}
+
+function readUpdateCache() {
+  try {
+    return JSON.parse(readFileSync(getUpdateCacheFile(), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeUpdateCache(obj) {
+  try {
+    mkdirSync(getStateHome(), { recursive: true });
+    writeFileSync(getUpdateCacheFile(), JSON.stringify(obj));
+  } catch {
+    /* a best-effort cache; ignore write failures */
+  }
+}
+
+/**
+ * True when the notifier should stay silent: an explicit opt-out, CI, or a
+ * non-interactive stdout (piped/scripted), so we never pollute machine-read
+ * output or nag in automation.
+ */
+function updateNotifierDisabled() {
+  if (process.env.NANO_NO_UPDATE_NOTIFIER || process.env.NO_UPDATE_NOTIFIER) return true;
+  if (process.env.CI) return true;
+  if (!process.stdout.isTTY) return true;
+  return false;
+}
+
+/**
+ * Refresh the cached latest version in the background. Spawns a detached Node
+ * process that runs `npm view <name> version` and writes the result to the
+ * cache file, then exits — the current command does not wait on it, so the
+ * fresh result is used on the *next* invocation.
+ */
+function spawnUpdateRefresh(name, cacheFile) {
+  const script =
+    'const{spawnSync}=require("child_process");' +
+    'const{readFileSync,writeFileSync}=require("fs");' +
+    `let prev={};try{prev=JSON.parse(readFileSync(${JSON.stringify(cacheFile)},"utf8"))}catch{}` +
+    'const out=Object.assign({},prev,{lastCheck:Date.now()});' +
+    `const r=spawnSync("npm",["view",${JSON.stringify(name)},"version"],{encoding:"utf8"});` +
+    'if(r.status===0){out.latest=String(r.stdout||"").trim()}' +
+    `try{writeFileSync(${JSON.stringify(cacheFile)},JSON.stringify(out))}catch{}`;
+  try {
+    const child = spawn(process.execPath, ['-e', script], { detached: true, stdio: 'ignore' });
+    child.unref();
+  } catch {
+    /* if we can't spawn, just skip this cycle */
+  }
+}
+
+function printUpdateNotice(name, current, latest) {
+  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`,
+    '╰─ Then restart any running cluster: c8ctl nano restart',
+    '',
+  ];
+  // stderr so it never corrupts parseable stdout.
+  for (const l of lines) console.error(l);
+}
+
+/**
+ * Best-effort, non-blocking update check run at the end of a command. Triggers
+ * a background registry refresh when the cache is stale, and prints a notice
+ * (at most once per day) when the cached latest version is newer than installed.
+ */
+function maybeNotifyUpdate(subcommand) {
+  try {
+    if (updateNotifierDisabled()) return;
+    if (subcommand === 'update') return; // the explicit command reports its own state
+    const { name, version: current } = pluginPackage();
+    if (!current || current === '0.0.0-dev') return;
+
+    const cacheFile = getUpdateCacheFile();
+    const cache = readUpdateCache();
+    const now = Date.now();
+
+    if (!cache.lastCheck || now - cache.lastCheck > UPDATE_CHECK_TTL_MS) {
+      try {
+        mkdirSync(getStateHome(), { recursive: true });
+      } catch {
+        /* ignore */
+      }
+      spawnUpdateRefresh(name, cacheFile);
+    }
+
+    const latest = cache.latest;
+    if (!latest || compareSemver(current, latest) >= 0) return;
+    if (cache.lastNotified && now - cache.lastNotified <= UPDATE_NOTIFY_TTL_MS) return;
+
+    printUpdateNotice(name, current, latest);
+    writeUpdateCache({ ...cache, lastNotified: now });
+  } catch {
+    /* the notifier must never break a command */
+  }
+}
+
 // ---------------------------------------------------------------------------
 // processos — manage a single local ProcessOS instance (the optimization-plane
 // server that analyses a running Nano BPM engine). Unlike nano, the ProcessOS
@@ -1182,15 +1429,17 @@ function clearProcessosState() {
 }
 
 /**
- * Locate the ProcessOS binary. Resolution order:
+ * Locate a ProcessOS binary the user already has, WITHOUT downloading. Order:
  *   1. --binary flag
  *   2. configured path ("processos set bin <path>")
  *   3. PROCESSOS_BINARY env var
- *   4. release build under the nanobpmn repo
- *   5. debug build under the nanobpmn repo
- * The binary is not shipped via npm — it is downloaded manually.
+ *   4. a previously auto-downloaded binary cached under the state home
+ *   5. release / debug build under the nanobpmn repo (local dev)
+ * Returns an absolute path, or null when nothing is configured/present. Throws
+ * only when an *explicitly* configured source points at a missing file (so the
+ * user gets an actionable error rather than a silent fallthrough).
  */
-function findProcessosBinary(req) {
+function findConfiguredProcessosBinary(req) {
   const cfg = readProcessosConfig();
   const sources = [
     { val: req?.binary && String(req.binary), from: '--binary' },
@@ -1206,24 +1455,331 @@ function findProcessosBinary(req) {
     return abs;
   }
 
-  const repo = getRepoRoot();
-  const name = 'processos';
-  const candidates = [
-    join(repo, 'processos', 'target', 'release', name),
-    join(repo, 'processos', 'target', 'debug', name),
-  ];
-  for (const c of candidates) {
-    if (existsSync(c)) return c;
+  const cached = getProcessosCachedBinaryPath();
+  if (existsSync(cached)) return cached;
+
+  let repo = null;
+  try {
+    repo = getRepoRoot();
+  } catch {
+    repo = null;
+  }
+  if (repo) {
+    const candidates = [
+      join(repo, 'processos', 'target', 'release', 'processos'),
+      join(repo, 'processos', 'target', 'debug', 'processos'),
+    ];
+    for (const c of candidates) {
+      if (existsSync(c)) return c;
+    }
+  }
+  return null;
+}
+
+/** The state-home directory that holds an auto-downloaded ProcessOS binary. */
+function getProcessosBinDir() {
+  return join(getStateHome(), 'bin');
+}
+
+function getProcessosCachedBinaryPath() {
+  const name = process.platform === 'win32' ? 'processos.exe' : 'processos';
+  return join(getProcessosBinDir(), name);
+}
+
+/** Sidecar recording the version of the auto-downloaded binary (for update checks). */
+function getProcessosBinaryMetaPath() {
+  return join(getProcessosBinDir(), PROCESSOS_BINARY_META_FILE);
+}
+
+function readProcessosBinaryMeta() {
+  try {
+    return JSON.parse(readFileSync(getProcessosBinaryMetaPath(), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The S3 asset name for the host platform, matching the names the nanobpmn CI
+ * uploads (`processos-<os>-<arch>`, `.exe` on Windows). Null on an unsupported
+ * platform.
+ */
+function processosAssetName(platform = process.platform, arch = process.arch) {
+  const map = {
+    'darwin:arm64': 'processos-darwin-arm64',
+    'darwin:x64': 'processos-darwin-x64',
+    'linux:x64': 'processos-linux-x64',
+    'linux:arm64': 'processos-linux-arm64',
+    'win32:x64': 'processos-win32-x64.exe',
+  };
+  return map[`${platform}:${arch}`] || null;
+}
+
+/**
+ * Join a PROCESSOS_DOWNLOAD_URL base with a leaf (`processos-<arch>` or
+ * `version.json`). The base is normally a directory/prefix (e.g. the S3
+ * `.../processos/latest/` URL); if it already points straight at a binary
+ * asset, we treat its parent directory as the base so siblings resolve too.
+ */
+function processosDownloadBase(rawUrl) {
+  const t = String(rawUrl || '').trim();
+  if (!t) return '';
+  if (t.endsWith('/')) return t.slice(0, -1);
+  const lastSeg = t.split('/').pop();
+  // A direct link to a binary asset -> use its parent as the base.
+  if (lastSeg.startsWith('processos-') || lastSeg === 'processos' || lastSeg.endsWith('.exe')) {
+    return t.slice(0, t.length - lastSeg.length - 1);
+  }
+  return t;
+}
+
+function processosBinaryUrl(rawUrl) {
+  const asset = processosAssetName();
+  if (!asset) {
+    throw new Error(
+      `No prebuilt ProcessOS binary is published for this platform (${process.platform}/${process.arch}).`,
+    );
+  }
+  return `${processosDownloadBase(rawUrl)}/${asset}`;
+}
+
+function processosVersionMetaUrl(rawUrl) {
+  return `${processosDownloadBase(rawUrl)}/${PROCESSOS_VERSION_META}`;
+}
+
+/** Fetch and parse the remote version.json (best-effort; null on any failure). */
+async function fetchProcessosVersionMeta(rawUrl, timeoutMs = 4000) {
+  try {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), timeoutMs);
+    const res = await fetch(processosVersionMetaUrl(rawUrl), { redirect: 'follow', signal: ctrl.signal });
+    clearTimeout(t);
+    if (!res.ok) return null;
+    const j = await res.json();
+    return j && typeof j === 'object' ? j : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Download a binary to `dest` (atomic via temp + rename; +x on unix). */
+async function downloadProcessosBinary(url, dest) {
+  const logger = getLogger();
+  logger.info(`Downloading ProcessOS for ${process.platform}/${process.arch} from ${url} ...`);
+  const res = await fetch(url, { redirect: 'follow' });
+  if (!res.ok) {
+    throw new Error(`ProcessOS download failed: HTTP ${res.status} ${res.statusText} for ${url}`);
+  }
+  const buf = Buffer.from(await res.arrayBuffer());
+  mkdirSync(getProcessosBinDir(), { recursive: true });
+  const tmp = `${dest}.download`;
+  writeFileSync(tmp, buf);
+  if (process.platform !== 'win32') chmodSync(tmp, 0o755);
+  renameSync(tmp, dest);
+  logger.info(`Saved ProcessOS to ${dest} (${(buf.length / 1_000_000).toFixed(1)} MB).`);
+  return dest;
+}
+
+/**
+ * Resolve the ProcessOS binary to run, downloading it on demand when the user
+ * has a PROCESSOS_DOWNLOAD_URL but no local copy yet. Resolution:
+ *   configured/local binary -> cached download -> fresh download -> error.
+ */
+async function resolveProcessosBinary(req) {
+  const configured = findConfiguredProcessosBinary(req); // may throw on a missing configured path
+  if (configured) return configured;
+
+  const dlUrl = process.env.PROCESSOS_DOWNLOAD_URL;
+  if (dlUrl) {
+    const dest = getProcessosCachedBinaryPath();
+    const meta = await fetchProcessosVersionMeta(dlUrl);
+    await downloadProcessosBinary(processosBinaryUrl(dlUrl), dest);
+    // Record what we fetched so the update notifier can compare later.
+    try {
+      mkdirSync(getProcessosBinDir(), { recursive: true });
+      writeFileSync(
+        getProcessosBinaryMetaPath(),
+        JSON.stringify({
+          version: meta?.version ?? null,
+          commit: meta?.commit ?? null,
+          updated: meta?.updated ?? null,
+          source: processosDownloadBase(dlUrl),
+          downloaded: new Date().toISOString(),
+        }),
+      );
+    } catch {
+      /* sidecar is best-effort */
+    }
+    return dest;
   }
+
   throw new Error(
-    `Could not find the ProcessOS binary.\n` +
-      `ProcessOS is not distributed via npm — download the binary for your platform, then point the plugin at it:\n` +
-      `  c8ctl processos set bin <path>   (or --binary <path>, or export PROCESSOS_BINARY)\n` +
-      `Alternatively build from source: (cd ${repo} && make processos-build-release)\n` +
-      `Looked for a local build in:\n  ${candidates.join('\n  ')}`,
+    `Could not find or download the ProcessOS binary.\n` +
+      `Set the download URL you were given (PROCESSOS_DOWNLOAD_URL), point the plugin at a\n` +
+      `local binary ("c8ctl processos set bin <path>" / --binary / PROCESSOS_BINARY), or build\n` +
+      `from source under the nanobpmn repo.`,
   );
 }
 
+/**
+ * Whether ProcessOS is enabled for this user. It is a closed alpha, so the
+ * operational commands stay locked until the user either has the binary on
+ * their system (configured path / cached download / local build) or has been
+ * given a PROCESSOS_DOWNLOAD_URL to fetch it from.
+ */
+function processosEnabled(req) {
+  if (process.env.PROCESSOS_DOWNLOAD_URL) return true;
+  try {
+    if (findConfiguredProcessosBinary(req)) return true;
+  } catch {
+    // A configured-but-missing path still means the user opted in; let the real
+    // not-found error surface from the command rather than the closed-alpha gate.
+    return true;
+  }
+  return false;
+}
+
+function printProcessosClosedAlpha() {
+  const logger = getLogger();
+  logger.error(
+    'ProcessOS is in closed alpha and is not available yet.\n' +
+      '\n' +
+      'To enable it, set the download URL you were given by the Nano BPM team:\n' +
+      '  export PROCESSOS_DOWNLOAD_URL=<url>\n' +
+      '  c8ctl processos start            # downloads + runs the matching binary\n' +
+      '\n' +
+      'or, if you already have the binary, point the plugin at it:\n' +
+      '  c8ctl processos set bin <path>',
+  );
+}
+
+// --- ProcessOS update notifier ---------------------------------------------
+// Mirrors the nano plugin notifier, but the "latest version" comes from the
+// version.json the nanobpmn CI publishes next to the S3 binaries rather than
+// from npm. Throttled to one background fetch + one notice per day.
+
+function getProcessosUpdateCacheFile() {
+  return join(getStateHome(), PROCESSOS_UPDATE_CACHE_FILE);
+}
+
+function readProcessosUpdateCache() {
+  try {
+    return JSON.parse(readFileSync(getProcessosUpdateCacheFile(), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeProcessosUpdateCache(obj) {
+  try {
+    mkdirSync(getStateHome(), { recursive: true });
+    writeFileSync(getProcessosUpdateCacheFile(), JSON.stringify(obj));
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * The installed ProcessOS version: the recorded version of an auto-downloaded
+ * binary, else `processos --version` against the resolved binary. Null when no
+ * binary is present or it can't report a version.
+ */
+function getInstalledProcessosVersion(req) {
+  const meta = readProcessosBinaryMeta();
+  if (meta.version) return String(meta.version);
+  let binary = null;
+  try {
+    binary = findConfiguredProcessosBinary(req);
+  } catch {
+    binary = null;
+  }
+  if (!binary) return null;
+  try {
+    const res = spawnSync(binary, ['--version'], { encoding: 'utf8', timeout: 3000 });
+    if (res.status === 0) {
+      const m = String(res.stdout || '').match(/(\d+\.\d+\.\d+[^\s]*)/);
+      if (m) return m[1];
+    }
+  } catch {
+    /* ignore */
+  }
+  return null;
+}
+
+/**
+ * Refresh the cached latest ProcessOS version in a detached background process
+ * (fetches version.json), so the current command never waits on the network.
+ */
+function spawnProcessosVersionRefresh(metaUrl, cacheFile) {
+  const script =
+    'const{readFileSync,writeFileSync}=require("fs");' +
+    `let prev={};try{prev=JSON.parse(readFileSync(${JSON.stringify(cacheFile)},"utf8"))}catch{}` +
+    'const out=Object.assign({},prev,{lastCheck:Date.now()});' +
+    'const ac=new AbortController();const t=setTimeout(()=>ac.abort(),5000);' +
+    `fetch(${JSON.stringify(metaUrl)},{redirect:"follow",signal:ac.signal})` +
+    '.then(r=>r.ok?r.json():null).then(j=>{clearTimeout(t);' +
+    'if(j&&j.version){out.latest=String(j.version);out.commit=j.commit||null}' +
+    `try{writeFileSync(${JSON.stringify(cacheFile)},JSON.stringify(out))}catch{}})` +
+    `.catch(()=>{try{writeFileSync(${JSON.stringify(cacheFile)},JSON.stringify(out))}catch{}});`;
+  try {
+    const child = spawn(process.execPath, ['-e', script], { detached: true, stdio: 'ignore' });
+    child.unref();
+  } catch {
+    /* skip this cycle */
+  }
+}
+
+function printProcessosUpdateNotice(current, latest) {
+  const lines = [
+    '',
+    `╭─ ProcessOS update available: v${current ?? '?'} → v${latest}`,
+    '│  A newer ProcessOS build is published.',
+    '│  Get it:  c8ctl processos stop && c8ctl processos start',
+    '│           (a configured binary updates itself; a downloaded one re-fetches)',
+    '╰─ Pin a specific build instead with: c8ctl processos set bin <path>',
+    '',
+  ];
+  for (const l of lines) console.error(l);
+}
+
+/**
+ * Best-effort, non-blocking ProcessOS update check. Triggers a background
+ * version.json fetch when the cache is stale and prints a notice (at most once
+ * per day) when the published version is newer than the installed one. Only
+ * meaningful when a download URL is configured (the closed-alpha channel).
+ */
+function maybeNotifyProcessosUpdate(req) {
+  try {
+    if (updateNotifierDisabled()) return;
+    const dlUrl = process.env.PROCESSOS_DOWNLOAD_URL;
+    if (!dlUrl) return; // no published channel to compare against
+    const current = getInstalledProcessosVersion(req);
+    if (!current) return;
+
+    const cacheFile = getProcessosUpdateCacheFile();
+    const cache = readProcessosUpdateCache();
+    const now = Date.now();
+
+    if (!cache.lastCheck || now - cache.lastCheck > UPDATE_CHECK_TTL_MS) {
+      try {
+        mkdirSync(getStateHome(), { recursive: true });
+      } catch {
+        /* ignore */
+      }
+      spawnProcessosVersionRefresh(processosVersionMetaUrl(dlUrl), cacheFile);
+    }
+
+    const latest = cache.latest;
+    if (!latest || compareSemver(current, latest) >= 0) return;
+    if (cache.lastNotified && now - cache.lastNotified <= UPDATE_NOTIFY_TTL_MS) return;
+
+    printProcessosUpdateNotice(current, latest);
+    writeProcessosUpdateCache({ ...cache, lastNotified: now });
+  } catch {
+    /* never break a command over the notifier */
+  }
+}
+
 /** Probe ProcessOS's GET /health endpoint for reachability. */
 async function probeProcessosHealthy(url) {
   return probePath(url, '/health');
@@ -1253,7 +1809,7 @@ async function startProcessos(req) {
     await stopProcessos({});
   }
 
-  const binary = findProcessosBinary(req);
+  const binary = await resolveProcessosBinary(req);
   const port = getProcessosPort(req);
   const url = `http://127.0.0.1:${port}`;
   const nanoUrl = req.nanoUrl || getProcessosNanoUrl();
@@ -1587,6 +2143,15 @@ function showProcessosConfig() {
     }
   }
   console.log('');
+  console.log('  closed-alpha channel:');
+  console.log(`    download url   ${process.env.PROCESSOS_DOWNLOAD_URL || '(not set — ProcessOS is a closed alpha; set PROCESSOS_DOWNLOAD_URL to enable)'}`);
+  const cached = getProcessosCachedBinaryPath();
+  const meta = readProcessosBinaryMeta();
+  console.log(`    cached binary  ${existsSync(cached) ? cached : '(none — downloaded on first "processos start")'}`);
+  if (meta.version || meta.commit) {
+    console.log(`    version        ${meta.version || '?'}${meta.commit ? ` (${String(meta.commit).slice(0, 8)})` : ''}${meta.downloaded ? `  downloaded ${meta.downloaded}` : ''}`);
+  }
+  console.log('');
   console.log(`  state file ${getProcessosStateFile()}`);
   console.log(`  log file   ${getProcessosLogFile()}`);
   console.log('');
@@ -1605,7 +2170,9 @@ function printProcessosUsage() {
   console.log('  c8ctl processos set bin <path> | port <n> | nano-url <url> | data-dir <path> | env KEY=VALUE');
   console.log('  c8ctl processos config');
   console.log('');
-  console.log('ProcessOS is downloaded manually; point the plugin at it with "c8ctl processos set bin <path>".');
+  console.log('ProcessOS is a closed alpha. Enable it with the download URL you were given:');
+  console.log('  export PROCESSOS_DOWNLOAD_URL=<url>   # plugin downloads + runs the matching binary');
+  console.log('or point the plugin at a binary you already have: "c8ctl processos set bin <path>".');
   console.log('By default ProcessOS spawns its own internal pilot Nano engine (the plugin auto-wires the nano');
   console.log('binary into PROCESSOS_NANO_BIN). Use --no-spawn-nano to instead use the --nano-url engine for');
   console.log('the pilot too. If no nano binary is available, it falls back to --no-spawn-nano automatically.');
@@ -1662,12 +2229,15 @@ 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: {
       description: 'Manage a local ProcessOS instance — start, status, stop, logs, config',
       examples: [
-        { command: 'c8ctl processos set bin <path>', description: 'Point the plugin at the downloaded ProcessOS binary' },
+        { command: 'export PROCESSOS_DOWNLOAD_URL=<url>', description: 'Enable the closed alpha + auto-download the matching binary' },
+        { command: 'c8ctl processos set bin <path>', description: 'Point the plugin at a ProcessOS binary you already have' },
         { command: 'c8ctl processos start', description: 'Start ProcessOS against the local Nano BPM engine' },
         { command: 'c8ctl processos start --nano-url http://localhost:8080', description: 'Start against a specific engine' },
         { command: 'c8ctl processos status', description: 'Show ProcessOS status and health' },
@@ -1695,6 +2265,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) => {
@@ -1706,6 +2277,7 @@ export const commands = {
         return;
       }
 
+      let failed = false;
       try {
         switch (req.subcommand) {
           case 'start':
@@ -1740,11 +2312,16 @@ 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}`);
-        process.exit(1);
+        failed = true;
       }
+      maybeNotifyUpdate(req.subcommand);
+      if (failed) process.exit(1);
     },
   },
   processos: {
@@ -1766,6 +2343,16 @@ export const commands = {
         return;
       }
 
+      // ProcessOS is a closed alpha: gate the operational commands until the
+      // user has opted in (download URL set or a binary on their system).
+      // `set`/`config` stay open so users can configure/inspect at any time.
+      const ungated = req.subcommand === 'set' || req.subcommand === 'config';
+      if (!ungated && !processosEnabled(req)) {
+        printProcessosClosedAlpha();
+        process.exit(1);
+      }
+
+      let failed = false;
       try {
         switch (req.subcommand) {
           case 'start':
@@ -1794,8 +2381,11 @@ export const commands = {
         }
       } catch (error) {
         logger.error(`processos ${req.subcommand} failed: ${error instanceof Error ? error.message : error}`);
-        process.exit(1);
+        failed = true;
       }
+      maybeNotifyUpdate(req.subcommand);
+      maybeNotifyProcessosUpdate(req);
+      if (failed) process.exit(1);
     },
   },
 };
@@ -1812,6 +2402,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 +2415,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.2.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.2.0",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.2.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.2.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.2.0",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.2.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',