c8ctl-plugin-nano 1.2.0 → 1.3.1

package/README.md

@@ -376,9 +376,23 @@ start/stop/status/logs lifecycle as `nano`.
 > setting the download URL you were given by the Nano BPM team, or by pointing
 > the plugin at a binary you already have.
 
+### Quick install (closed-alpha invitees)
+
+If you were given a ProcessOS download URL, this one-liner installs the Camunda 8
+CLI (`@camunda8/cli`) and this plugin, then configures the download URL:
+
+```bash
+curl -fsSL https://gist.githubusercontent.com/jwulf/9015a7c660b274c568d80e85c3914161/raw/install-processos.sh \
+  | bash -s -- "<the download URL you were given>"
+```
+
+(Requires Node.js 18+. The canonical script lives at
+[`install-processos.sh`](./install-processos.sh).) Then run `c8ctl processos start`.
+
+
 ```bash
-# Closed-alpha channel: the plugin downloads + caches the matching binary
-export PROCESSOS_DOWNLOAD_URL=<url you were given>
+# Closed-alpha channel: persist the download URL, then start
+c8ctl processos set 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
@@ -386,8 +400,10 @@ 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
+The download URL is the prefix the release binaries live under (e.g. the
+`…/processos/latest/` bucket URL). Persist it with `c8ctl processos set
+download-url <url>`, or set `PROCESSOS_DOWNLOAD_URL` in your environment (the env
+var wins when both are present). 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.
@@ -407,7 +423,7 @@ c8ctl processos stop
 
 ### Automatic update notice
 
-When you're on the closed-alpha channel (`PROCESSOS_DOWNLOAD_URL` set), the
+When you're on the closed-alpha channel (download URL configured), 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
@@ -457,6 +473,7 @@ Settings persist under a `processos` key in the same `config.json` as `nano`.
 
 ```bash
 c8ctl processos set bin <path>          # path to the downloaded ProcessOS binary
+c8ctl processos set download-url <url>  # closed-alpha binary download URL (enables ProcessOS)
 c8ctl processos set port <n>            # listen port (default 8090)
 c8ctl processos set nano-url <url>      # target Nano BPM engine (default http://localhost:8080)
 c8ctl processos set data-dir <path>     # PROCESSOS_DATA_DIR (default <stateHome>/processos-data)
@@ -467,8 +484,9 @@ c8ctl processos config                  # show current settings and on-disk path
 
 The binary is resolved in this order: `--binary` flag → `set bin` →
 `$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
+`processos/target/{release,debug}/processos` build → a fresh download from the
+configured download URL (`set download-url` / `$PROCESSOS_DOWNLOAD_URL`). Typed
+settings (`port`, `nano-url`, `data-dir`) always
 win over generic `env` passthrough values when launching.
 
 ## Installing

package/c8ctl-plugin.js

@@ -1400,6 +1400,18 @@ function getProcessosNanoUrl() {
   return cfg.nanoUrl || process.env.NANO_BASE_URL || DEFAULT_NANO_URL;
 }
 
+/**
+ * The closed-alpha download URL: env var (PROCESSOS_DOWNLOAD_URL) wins, then the
+ * persisted `processos set download-url` config value. Null when neither is set.
+ */
+function getProcessosDownloadUrl() {
+  const fromEnv = process.env.PROCESSOS_DOWNLOAD_URL;
+  if (fromEnv && String(fromEnv).trim()) return String(fromEnv).trim();
+  const cfg = readProcessosConfig();
+  if (cfg.downloadUrl && String(cfg.downloadUrl).trim()) return String(cfg.downloadUrl).trim();
+  return null;
+}
+
 /** The listen port (flag overrides configured value, which overrides default). */
 function getProcessosPort(req) {
   const cfg = readProcessosConfig();
@@ -1589,7 +1601,7 @@ 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;
+  const dlUrl = getProcessosDownloadUrl();
   if (dlUrl) {
     const dest = getProcessosCachedBinaryPath();
     const meta = await fetchProcessosVersionMeta(dlUrl);
@@ -1628,7 +1640,7 @@ async function resolveProcessosBinary(req) {
  * given a PROCESSOS_DOWNLOAD_URL to fetch it from.
  */
 function processosEnabled(req) {
-  if (process.env.PROCESSOS_DOWNLOAD_URL) return true;
+  if (getProcessosDownloadUrl()) return true;
   try {
     if (findConfiguredProcessosBinary(req)) return true;
   } catch {
@@ -1645,8 +1657,10 @@ function printProcessosClosedAlpha() {
     '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' +
+      '  c8ctl processos set download-url <url>   # persists it for this machine\n' +
+      '  c8ctl processos start                    # downloads + runs the matching binary\n' +
+      '\n' +
+      '(or set PROCESSOS_DOWNLOAD_URL in your environment for the same effect)\n' +
       '\n' +
       'or, if you already have the binary, point the plugin at it:\n' +
       '  c8ctl processos set bin <path>',
@@ -1751,7 +1765,7 @@ function printProcessosUpdateNotice(current, latest) {
 function maybeNotifyProcessosUpdate(req) {
   try {
     if (updateNotifierDisabled()) return;
-    const dlUrl = process.env.PROCESSOS_DOWNLOAD_URL;
+    const dlUrl = getProcessosDownloadUrl();
     if (!dlUrl) return; // no published channel to compare against
     const current = getInstalledProcessosVersion(req);
     if (!current) return;
@@ -2030,6 +2044,8 @@ const PROCESSOS_SET_FIELDS = {
   port: 'port',
   'nano-url': 'nanoUrl',
   nanourl: 'nanoUrl',
+  'download-url': 'downloadUrl',
+  downloadurl: 'downloadUrl',
   'data-dir': 'dataDir',
   datadir: 'dataDir',
   env: 'env',
@@ -2039,6 +2055,7 @@ function printProcessosSetUsage() {
   const logger = getLogger();
   logger.info('Usage: c8ctl processos set <field> <value>');
   logger.info('  bin <path>          Path to the downloaded ProcessOS binary');
+  logger.info('  download-url <url>  Closed-alpha binary download URL (enables ProcessOS)');
   logger.info('  port <n>            Listen port (default 8090)');
   logger.info('  nano-url <url>      Target Nano BPM engine URL (default http://localhost:8080)');
   logger.info('  data-dir <path>     ProcessOS data directory');
@@ -2111,6 +2128,16 @@ function setProcessosConfig(req) {
     }
     cfg.nanoUrl = val;
     logger.info(`Set nano-url = ${val}`);
+  } else if (field === 'downloadUrl') {
+    const val = req.positional[1];
+    if (val === undefined || val === '') {
+      // Allow clearing with an empty value: c8ctl processos set download-url ""
+      delete cfg.downloadUrl;
+      logger.info('Cleared download-url');
+    } else {
+      cfg.downloadUrl = String(val).trim();
+      logger.info(`Set download-url = ${cfg.downloadUrl}`);
+    }
   } else if (field === 'dataDir') {
     const val = req.positional[1];
     if (!val) {
@@ -2144,7 +2171,13 @@ 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 dlUrl = getProcessosDownloadUrl();
+  const dlSource = process.env.PROCESSOS_DOWNLOAD_URL && String(process.env.PROCESSOS_DOWNLOAD_URL).trim()
+    ? '  (from $PROCESSOS_DOWNLOAD_URL)'
+    : cfg.downloadUrl
+      ? '  (from "processos set download-url")'
+      : '';
+  console.log(`    download url   ${dlUrl ? dlUrl + dlSource : '(not set — ProcessOS is a closed alpha; "c8ctl processos set download-url <url>" to enable)'}`);
   const cached = getProcessosCachedBinaryPath();
   const meta = readProcessosBinaryMeta();
   console.log(`    cached binary  ${existsSync(cached) ? cached : '(none — downloaded on first "processos start")'}`);
@@ -2155,7 +2188,7 @@ function showProcessosConfig() {
   console.log(`  state file ${getProcessosStateFile()}`);
   console.log(`  log file   ${getProcessosLogFile()}`);
   console.log('');
-  console.log('  Change with: c8ctl processos set bin <path> | set port <n> | set nano-url <url> | set data-dir <path> | set env KEY=VALUE');
+  console.log('  Change with: c8ctl processos set bin <path> | set download-url <url> | set port <n> | set nano-url <url> | set data-dir <path> | set env KEY=VALUE');
 }
 
 function printProcessosUsage() {
@@ -2167,11 +2200,11 @@ function printProcessosUsage() {
   console.log('  c8ctl processos stop');
   console.log('  c8ctl processos restart [...]');
   console.log('  c8ctl processos logs [--follow]');
-  console.log('  c8ctl processos set bin <path> | port <n> | nano-url <url> | data-dir <path> | env KEY=VALUE');
+  console.log('  c8ctl processos set bin <path> | download-url <url> | port <n> | nano-url <url> | data-dir <path> | env KEY=VALUE');
   console.log('  c8ctl processos config');
   console.log('');
   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('  c8ctl processos set 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');
@@ -2236,7 +2269,7 @@ export const metadata = {
     processos: {
       description: 'Manage a local ProcessOS instance — start, status, stop, logs, config',
       examples: [
-        { command: 'export PROCESSOS_DOWNLOAD_URL=<url>', description: 'Enable the closed alpha + auto-download the matching binary' },
+        { command: 'c8ctl processos set 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' },

package/nanobpmn-binary.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.2",
-  "commit": "44ad803",
-  "updated": "2026-06-30T06:04:34Z"
+  "version": "0.0.3",
+  "commit": "a3511a2",
+  "updated": "2026-06-30T20:29:46Z"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "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": {
-    "@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"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.3.1",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.3.1",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.3.1",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.3.1",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.3.1"
   }
 }