c8ctl-plugin-nano 1.25.1 → 1.26.1

package/README.md

@@ -106,6 +106,10 @@ c8ctl nano clean
 c8ctl nano set bin   ~/workspace/nanobpmn/server/target/release/nanobpm-gateway-rest-server
 c8ctl nano set model-dir ~/bpmn-workspace
 
+# Clear a custom setting (back to the managed/release binary, or default workspace)
+c8ctl nano unset bin
+c8ctl nano unset model-dir
+
 # Show current configuration and on-disk locations
 c8ctl nano config
 ```
@@ -575,17 +579,23 @@ c8ctl nano start --console off        # headless: no console router at all
   env var is honored when the flag is not passed. The plugin passes the choice
   through as `NANOBPMN_CONSOLE` on every node.
 
-## Configuration (`set` / `config`)
+## Configuration (`set` / `unset` / `config`)
 
 Persistent settings are stored in `<state home>/config.json`:
 
-| Setting             | Env mapping              | Set with                          |
-|---------------------|--------------------------|-----------------------------------|
-| Binary path         | (used to launch nodes)   | `c8ctl nano set bin <path>`       |
-| Workspace directory | `NANOBPMN_WORKSPACE_DIR` | `c8ctl nano set model-dir <path>` |
+| Setting             | Env mapping              | Set with                          | Clear with                    |
+|---------------------|--------------------------|-----------------------------------|-------------------------------|
+| Binary path         | (used to launch nodes)   | `c8ctl nano set bin <path>`       | `c8ctl nano unset bin`        |
+| Workspace directory | `NANOBPMN_WORKSPACE_DIR` | `c8ctl nano set model-dir <path>` | `c8ctl nano unset model-dir`  |
 
 Show the effective configuration and all on-disk locations with `c8ctl nano config`.
 
+`unset bin` clears a custom binary path so node launches fall back to the
+managed platform binary — i.e. back on the release train that `c8ctl nano
+update` tracks. (Note: a `NANOBPMN_BINARY` environment variable still overrides
+even after `unset`.) `unset model-dir` returns the workspace to its default
+(`<state home>/workspace`).
+
 ## Updating to a new release (`update`)
 
 The plugin and the bundled server binary (delivered via the matching platform

package/c8ctl-plugin.js

@@ -450,7 +450,7 @@ function launcherEnvMarkers(resolved) {
 // Argument parsing
 // ---------------------------------------------------------------------------
 
-const VALID_SUBCOMMANDS = ['start', 'stop', 'status', 'logs', 'log', 'restart', 'pause', 'resume', 'clean', 'set', 'config', 'update', 'hire', 'assign', 'work', 'supervisor'];
+const VALID_SUBCOMMANDS = ['start', 'stop', 'status', 'logs', 'log', 'restart', 'pause', 'resume', 'clean', 'set', 'unset', 'config', 'update', 'hire', 'assign', 'work', 'supervisor'];
 
 /**
  * Parse positional args + flags into a normalized request.
@@ -1387,7 +1387,7 @@ function setConfig(req) {
   const key = req.positional[0];
   const value = req.positional[1];
 
-  if (!key || !(key in SETTING_ALIASES)) {
+  if (!key || !Object.hasOwn(SETTING_ALIASES, key)) {
     logger.error('Usage: c8ctl nano set <bin|model-dir> <path>');
     logger.info('Settings:');
     logger.info('  bin <path>        Path to the nanobpmn server binary');
@@ -1423,12 +1423,69 @@ function setConfig(req) {
   }
 }
 
+/**
+ * Clear a configured setting so resolution falls back to the default. The
+ * headline use is `unset bin`: after `set bin <path>` pins a self-managed
+ * binary (source 'configured', which disables self-update), clearing it lets
+ * the plugin fall back to the managed npm platform package — i.e. back on the
+ * release train. `unset model-dir` returns the workspace to its default.
+ */
+function unsetConfig(req) {
+  const logger = getLogger();
+  const key = req.positional[0];
+
+  if (!key || !Object.hasOwn(SETTING_ALIASES, key)) {
+    logger.error('Usage: c8ctl nano unset <bin|model-dir>');
+    logger.info('Settings:');
+    logger.info('  bin        Clear the custom server binary (back to the managed/release binary)');
+    logger.info('  model-dir  Clear the custom workspace dir (back to the default)');
+    process.exit(1);
+  }
+
+  const field = SETTING_ALIASES[key];
+  const cfg = readConfig();
+  const prev = cfg[field];
+  const wasSet = prev !== undefined && prev !== null && prev !== '';
+  const label = field === 'binary' ? 'custom binary override' : 'custom workspace override';
+
+  if (!wasSet) {
+    logger.info(`No ${label} is configured — nothing to clear.`);
+  } else {
+    delete cfg[field];
+    writeConfig(cfg);
+    logger.info(`Cleared ${label} (was ${prev}).`);
+  }
+
+  if (field === 'binary') {
+    // Report what resolves now, so the operator can see they are back on the
+    // managed release train (or what still overrides it).
+    try {
+      const r = resolveBinary({});
+      logger.info(`Now using: ${r.path} (${r.from}).`);
+      if (r.source === 'managed-npm') {
+        logger.info('Back on the managed release train — "c8ctl nano update" now tracks the published release.');
+      } else if (r.source === 'configured') {
+        logger.warn('Still pinned by NANOBPMN_BINARY in your environment; unset that to use the managed binary.');
+      }
+    } catch (err) {
+      logger.warn(`No binary resolves now: ${err instanceof Error ? err.message : err}`);
+      logger.info('Reinstall the plugin to fetch the managed platform binary, or set one again with "c8ctl nano set bin <path>".');
+    }
+  } else if (field === 'workspaceDir') {
+    logger.info(`Workspace is now the default: ${getWorkspaceDir()}.`);
+    const running = readState();
+    if (running && liveNodeCount(running) > 0) {
+      logger.warn('A cluster is running — restart it for the new workspace to take effect.');
+    }
+  }
+}
+
 function showConfig() {
   const cfg = readConfig();
   console.log('Nano plugin configuration:');
   console.log('');
   console.log(`  state home   ${getStateHome()}`);
-  console.log(`  binary       ${cfg.binary || '(auto-detect: $NANOBPMN_BINARY or repo build)'}`);
+  console.log(`  binary       ${cfg.binary || '(auto-detect: $NANOBPMN_BINARY, managed platform package, or repo build)'}`);
   const bundled = readBundledBinaryInfo();
   if (bundled) {
     const at = bundled.commit && bundled.commit !== 'unknown' ? ` (${bundled.commit})` : '';
@@ -1441,6 +1498,7 @@ function showConfig() {
   console.log(`  config file  ${getConfigFile()}`);
   console.log('');
   console.log('  Change with: c8ctl nano set bin <path> | c8ctl nano set model-dir <path>');
+  console.log('  Clear with:  c8ctl nano unset bin | c8ctl nano unset model-dir');
 }
 
 // ---------------------------------------------------------------------------
@@ -2237,14 +2295,9 @@ function makeSecretResolver(kind) {
 // Resolve the names a job needs (setup.secretRefs, plus the repo/PR credential
 // when allowPr). Returns resolved values + a list of names that were missing so
 // the caller can fail the job with a clear provisioning error.
-function resolveJobSecrets(resolver, envelope) {
+function resolveJobSecrets(resolver, envelope, { ghAuthToken = ghAuthTokenFromCli } = {}) {
   const names = new Set();
   for (const n of envelope.setup?.secretRefs || []) if (n) names.add(n);
-  if (envelope.task?.allowPr) {
-    const provider = envelope.repository?.provider || 'github';
-    const authRef = envelope.repository?.authRef || (provider === 'github' ? 'GITHUB_TOKEN' : undefined);
-    if (authRef) names.add(authRef);
-  }
   const resolved = {};
   const missing = [];
   for (const name of names) {
@@ -2252,6 +2305,34 @@ function resolveJobSecrets(resolver, envelope) {
     if (v === undefined) missing.push(name);
     else resolved[name] = v;
   }
+  // The github clone/push credential is resolved with a gh-CLI fallback so a
+  // default GITHUB_TOKEN isn't reported "missing" merely because it isn't in the
+  // env when `gh auth login` provides it. A custom authRef stays strict.
+  if (envelope.task?.allowPr) {
+    const provider = envelope.repository?.provider || 'github';
+    const authRef = envelope.repository?.authRef;
+    const ref = normalizeAuthRef(authRef);
+    if (ref.kind === 'invalid') {
+      // A present-but-blank authRef is a misconfiguration: surface it as missing
+      // so provisioning sheds rather than silently borrowing the default/gh token.
+      if (!missing.includes('repository.authRef')) missing.push('repository.authRef');
+    } else {
+      const ghAuthRef = ref.kind === 'custom'
+        ? ref.name
+        : (provider === 'github' ? 'GITHUB_TOKEN' : undefined);
+      if (ghAuthRef) {
+        names.add(ghAuthRef);
+        const token = githubCloneToken({ provider, authRef, secretResolver: resolver, ghAuthToken });
+        const missingIdx = missing.indexOf(ghAuthRef);
+        if (token) {
+          resolved[ghAuthRef] = token;
+          if (missingIdx !== -1) missing.splice(missingIdx, 1);
+        } else if (missingIdx === -1) {
+          missing.push(ghAuthRef);
+        }
+      }
+    }
+  }
   return { resolved, missing, names: [...names] };
 }
 
@@ -2402,6 +2483,82 @@ function credArgs() {
   return ['-c', 'credential.helper='];
 }
 
+// Fall back to the `gh` CLI's stored credential when GITHUB_TOKEN is not exported
+// to the env. Most interactive setups authenticate with `gh auth login` (keychain)
+// rather than an env var, so an env-only secret resolver yields no token and a
+// private/internal clone fails with "could not read Username". Best effort: returns
+// a trimmed token, or null when gh is missing / not logged in. The token is fed to
+// git via GIT_ASKPASS only (never argv/URL/helper), preserving the ephemeral-token
+// guarantee.
+// Memoized for the process lifetime: this is a synchronous spawnSync (up to a
+// 10s timeout) that can be reached per job, and jobs may run concurrently
+// (maxParallelJobs > 1), so consult the CLI at most once per worker run rather
+// than blocking every handler. A sentinel distinguishes "not yet computed" from
+// a cached null (gh missing / not logged in).
+//
+// Memoization alone still lets the *first* job pay the synchronous spawn on the
+// event loop, stalling any sibling handlers (and lock-extension heartbeats) for
+// up to the timeout. So `nano work` primes this cache once at startup via
+// `primeGhAuthToken()` — before the poll loop — moving the one unavoidable
+// blocking spawn off the job-handling path entirely. Any later call is a warm
+// cache hit; the memoization here is the safety net for paths that never primed.
+const GH_AUTH_TOKEN_UNSET = Symbol('gh-auth-token-unset');
+let ghAuthTokenCache = GH_AUTH_TOKEN_UNSET;
+function ghAuthTokenFromCli() {
+  if (ghAuthTokenCache !== GH_AUTH_TOKEN_UNSET) return ghAuthTokenCache;
+  let token = null;
+  try {
+    const r = spawnSync('gh', ['auth', 'token'], { encoding: 'utf8', timeout: 10_000 });
+    const tok = r.status === 0 ? (r.stdout || '').trim() : '';
+    token = tok || null;
+  } catch {
+    token = null;
+  }
+  ghAuthTokenCache = token;
+  return token;
+}
+
+// Warm the gh-token cache once, off the job-handling path. Safe to call any
+// number of times: the first call performs the (possibly blocking) lookup, the
+// rest are cache hits. Returns true once the cache is populated.
+function primeGhAuthToken() {
+  ghAuthTokenFromCli();
+  return ghAuthTokenCache !== GH_AUTH_TOKEN_UNSET;
+}
+
+// Normalize a repository authRef into one of three intents. Trimming matters so
+// a present-but-blank authRef ('' or whitespace) is treated as a misconfiguration
+// rather than "absent": absence enables the default/gh fallback, but a blank
+// custom ref must NOT silently borrow the operator's gh login.
+//   { kind: 'default' }        no custom authRef configured (undefined/null)
+//   { kind: 'custom', name }   a non-empty custom authRef (strict)
+//   { kind: 'invalid' }        authRef present but blank (config error)
+function normalizeAuthRef(authRef) {
+  if (authRef === undefined || authRef === null) return { kind: 'default' };
+  const trimmed = String(authRef).trim();
+  if (trimmed === '') return { kind: 'invalid' };
+  return { kind: 'custom', name: trimmed };
+}
+
+// Resolve the github clone/push credential. The default credential (env
+// GITHUB_TOKEN) falls back to the gh CLI's stored token so `gh auth login`
+// setups work without exporting GITHUB_TOKEN. A custom `authRef` is honored
+// strictly (env/secret resolver only, no gh fallback) so a misconfigured named
+// secret surfaces as missing rather than silently borrowing the operator's gh
+// login. An authRef that is present but blank is a misconfiguration and yields no
+// token (never the gh fallback). `ghAuthToken` is injectable for testing.
+// Returns a token or null.
+function githubCloneToken({ provider, authRef, secretResolver, ghAuthToken = ghAuthTokenFromCli }) {
+  const prov = provider || 'github';
+  const ref = normalizeAuthRef(authRef);
+  if (ref.kind === 'invalid') return null;
+  const usesDefault = prov === 'github' && ref.kind === 'default';
+  const name = ref.kind === 'custom' ? ref.name : (prov === 'github' ? 'GITHUB_TOKEN' : null);
+  let token = name ? (secretResolver.resolve(name) || null) : null;
+  if (!token && usesDefault) token = ghAuthToken() || null;
+  return token;
+}
+
 // Clone repo into <runDir>/workspace and check out / create the working branch.
 // Returns { workspaceDir, gitEnv, startSha, workingBranch, remote }. Throws a
 // ProvisionError (token-redacted) on any git failure so the caller can shed.
@@ -3136,6 +3293,12 @@ async function workAgent(req, flags) {
   const extraNote = extraJobTypes.length > 0 ? ` (${extraJobTypes.length} via --job-type)` : '';
   logger.info(`  listening on ${jobTypes.length} job type(s)${extraNote}: ${jobTypes.join('  ')}`);
   logger.info(`  max parallel: ${maxParallelJobs}; recovery window: ${recoveryWindowMs}ms; idle timeout: ${idleTimeoutMs}ms; hard cap: ${hardCapMs > 0 ? `${hardCapMs}ms` : 'off'}; poll timeout: ${pollTimeoutMs}ms`);
+  // Warm the gh-token cache now, off the job-handling path: githubCloneToken()
+  // may consult `gh auth token` (a synchronous spawn, up to 10s) as its default
+  // credential fallback, and doing that inside a job handler would stall sibling
+  // handlers + lock heartbeats when maxParallelJobs > 1. Priming here pays that
+  // cost once at startup so every later lookup is a warm cache hit.
+  primeGhAuthToken();
   logger.info('Polling for work — press Ctrl-C to stop.');
 
   // When launched under the supervisor, report per-job activity — which job(s)
@@ -3237,8 +3400,8 @@ async function workAgent(req, flags) {
         let repoToken = null;
         if (hasRepo) {
           const provider = envelope.repository.provider || 'github';
-          const authRef = envelope.repository.authRef || (provider === 'github' ? 'GITHUB_TOKEN' : null);
-          if (authRef) repoToken = secretResolver.resolve(authRef) || null; // optional: absent → anonymous clone
+          const authRef = envelope.repository.authRef;
+          repoToken = githubCloneToken({ provider, authRef, secretResolver }); // absent → anonymous clone
           try {
             mkdirSync(agentRunsRoot(), { recursive: true });
             runDir = mkdtempSync(join(agentRunsRoot(), 'run-'));
@@ -6121,6 +6284,7 @@ function parseProcessosRequest(args, flags) {
 // Internal helpers exported for tests/tooling only. c8ctl consumes just
 // `metadata` and `commands`; these named exports are inert to it.
 export { resolveBinary, findBinary, launcherEnvMarkers };
+export { setConfig, unsetConfig, readConfig, writeConfig, getConfigFile, SETTING_ALIASES };
 export { buildNpmInvocation };
 export {
   webConsoleUrl,
@@ -6158,6 +6322,9 @@ export {
   reconcileAgentPr,
   reapAgentRunDirs,
   authUrl,
+  githubCloneToken,
+  ghAuthTokenFromCli,
+  primeGhAuthToken,
   redactToken,
   agentRunsRoot,
   ProvisionError,
@@ -6231,6 +6398,7 @@ export const metadata = {
         { command: 'c8ctl nano restart --purge', description: 'Restart the cluster from a clean slate (delete engine data)' },
         { command: 'c8ctl nano clean', description: 'Wipe journal/data + logs on disk (keeps models/workers)' },
         { command: 'c8ctl nano set bin <path>', description: 'Set the nanobpmn server binary path' },
+        { command: 'c8ctl nano unset bin', description: 'Clear a custom binary path and return to the managed/release binary' },
         { 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)' },
@@ -6360,6 +6528,9 @@ export const commands = {
           case 'set':
             setConfig(req);
             break;
+          case 'unset':
+            unsetConfig(req);
+            break;
           case 'config':
             showConfig();
             break;
@@ -6464,6 +6635,7 @@ function printUsage() {
   console.log('  c8ctl nano restart [<nodes>] [--purge] ...');
   console.log('  c8ctl nano clean [--workspace]');
   console.log('  c8ctl nano set <bin|model-dir> <path>');
+  console.log('  c8ctl nano unset <bin|model-dir>');
   console.log('  c8ctl nano config');
   console.log('  c8ctl nano update [--check]');
   console.log('  c8ctl nano hire [--name <n>] [--rank <r>] [--command <c>] [--arg <switch> ...] [--model <m>] [--capabilities <a,b>] [--sandbox none|docker|podman] [--image <ref>] [--env NAME=VALUE ...] [--list]');
@@ -6481,6 +6653,7 @@ function printUsage() {
   console.log('  restart  Stop then start');
   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('  unset    Clear a setting ("bin" or "model-dir") back to its default');
   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('  hire     Create a CLI agent worker profile (rank + capabilities → job-type matrix)');

package/package.json

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