@mmmbuto/nexuscrew 0.7.7 → 0.8.0

package/lib/cli/doctor.js

@@ -0,0 +1,160 @@
+'use strict';
+// nexuscrew doctor: auto-diagnosi (design §3, §7). [A2]
+// Struttura ESTENSIBILE: una lista di check-fn, ognuna ritorna
+//   { name, ok, warn?, detail? }. B0 aggiungerà i check tunnel/ssh (permitlisten,
+//   OpenSSH ≥7.8 sul rendezvous) appendendo alla lista, senza toccare il resto.
+// Exit code: 0 se tutti ok (i warn non falliscono), 1 se almeno un check è FAIL.
+// Nessun segreto nell'output (mai il token, solo il path + i permessi).
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { detectPlatform, uid } = require('./platform.js');
+const { installPath } = require('./service.js');
+const { resolvePaths } = require('./url.js');
+const { commandExists } = require('./path.js');
+
+function nodeMajor() {
+  return parseInt(String(process.versions.node).split('.')[0], 10);
+}
+
+function checkNode() {
+  const maj = nodeMajor();
+  return { name: 'node >= 18', ok: maj >= 18, detail: `v${process.versions.node}` };
+}
+
+function checkTmux(existsImpl, tmuxBin) {
+  return existsImpl(tmuxBin || 'tmux')
+    ? { name: 'tmux presente', ok: true }
+    : { name: 'tmux presente', ok: false, detail: 'non trovato su PATH (installa tmux)' };
+}
+
+function checkPty(ptyLoad) {
+  try {
+    ptyLoad();
+    return { name: 'PTY prebuilt caricabile', ok: true };
+  } catch (e) {
+    return { name: 'PTY prebuilt caricabile', ok: false, detail: e && e.message ? e.message : 'load fallito' };
+  }
+}
+
+function checkService(platform, home, execImpl, uidVal, installPathOverride) {
+  const target = installPathOverride || installPath(platform, home);
+  const installed = fs.existsSync(target);
+  let active = false;
+  try {
+    if (platform === 'linux') {
+      const s = execImpl('systemctl', ['--user', 'is-active', 'nexuscrew'], { encoding: 'utf8' });
+      active = String(s).trim() === 'active';
+    } else if (platform === 'mac') {
+      execImpl('launchctl', ['print', `gui/${uidVal}/com.mmmbuto.nexuscrew`], { stdio: 'ignore' });
+      active = true;
+    } else if (platform === 'termux') {
+      const pidf = require('./pidfile.js');
+      const meta = pidf.readPidfile(pidf.defaultPidfilePath());
+      active = !!(meta && pidf.isAlive(meta));
+    }
+  } catch (_) { active = false; }
+  return {
+    name: 'service installato/attivo',
+    ok: installed,
+    warn: installed && !active, // installato ma non attivo = warning, non fail
+    detail: installed ? (active ? 'attivo' : 'installato ma non attivo') : `non installato (${target})`,
+  };
+}
+
+function checkBoot(platform, home, execImpl) {
+  if (platform === 'termux') {
+    const p = path.join(home, '.termux', 'boot', 'nexuscrew.sh');
+    const ok = fs.existsSync(p);
+    return { name: 'boot script', ok, warn: !ok, detail: ok ? p : 'nessun Termux:boot script' };
+  }
+  if (platform === 'linux') {
+    try {
+      const s = execImpl('systemctl', ['--user', 'is-enabled', 'nexuscrew'], { encoding: 'utf8' });
+      const enabled = String(s).trim() === 'enabled';
+      return { name: 'boot (systemd enabled)', ok: true, warn: !enabled, detail: enabled ? 'enabled' : 'non enabled (non parte al boot)' };
+    } catch (_) {
+      return { name: 'boot (systemd enabled)', ok: true, warn: true, detail: 'non enabled' };
+    }
+  }
+  // mac: RunAtLoad nel plist installato
+  const target = installPath('mac', home);
+  const ok = fs.existsSync(target);
+  return { name: 'boot (launchd RunAtLoad)', ok: true, warn: !ok, detail: ok ? 'plist installato' : 'plist non installato' };
+}
+
+// ssh client presente su PATH: prerequisito dei tunnel multi-node (design §4).
+function checkSshClient(existsImpl) {
+  return existsImpl('ssh')
+    ? { name: 'ssh client presente', ok: true }
+    : { name: 'ssh client presente', ok: false, detail: 'ssh non trovato su PATH (necessario per i tunnel multi-node)' };
+}
+
+// OpenSSH >=7.8 per permitlisten (vincola i -R lato rendezvous; design §7 (a)).
+// Determinabile e <7.8 -> FAIL (il ruolo node non e' abilitabile). Non
+// determinabile -> WARN (verifica manuale), non blocca la diagnosi generale.
+function checkSshPermitlisten(sshVersionImpl) {
+  const tun = require('../nodes/tunnel.js');
+  const v = tun.readSshVersion(sshVersionImpl);
+  const supp = tun.sshSupportsPermitlisten(v);
+  if (supp === null) {
+    return { name: 'OpenSSH permitlisten (>=7.8)', ok: true, warn: true, detail: 'versione ssh non determinabile — verifica prima di abilitare il ruolo node' };
+  }
+  if (supp) return { name: 'OpenSSH permitlisten (>=7.8)', ok: true, detail: v.raw };
+  return { name: 'OpenSSH permitlisten (>=7.8)', ok: false, detail: `OpenSSH ${v.major}.${v.minor} < 7.8 — permitlisten non supportato (ruolo node non abilitabile)` };
+}
+
+function checkTokenPerms(tokenPath) {
+  try {
+    const st = fs.lstatSync(tokenPath);
+    if (st.isSymbolicLink()) {
+      return { name: 'token file permessi', ok: false, detail: 'è un symlink (rifiutato)' };
+    }
+    const mode = st.mode & 0o777;
+    const ok = mode === 0o600;
+    return { name: 'token file permessi', ok, detail: `mode 0${mode.toString(8)}${ok ? '' : ' (atteso 0600)'}` };
+  } catch (e) {
+    if (e.code === 'ENOENT') {
+      return { name: 'token file permessi', ok: false, detail: 'token assente (esegui init)' };
+    }
+    return { name: 'token file permessi', ok: false, detail: e.message };
+  }
+}
+
+// Esegue tutti i check. Seam iniettabili per test (platform, home, execImpl, ptyLoad).
+function doctor(opts = {}) {
+  const platform = opts.platform || detectPlatform();
+  const home = opts.home || os.homedir();
+  const execImpl = opts.execImpl || execFileSync;
+  const uidVal = opts.uid || uid();
+  const log = opts.log || console.log;
+  const ptyLoad = opts.ptyLoad || (() => require('../pty/provider.js').loadPty());
+  const existsImpl = opts.commandExists || commandExists;
+  const { tokenPath } = resolvePaths(opts);
+
+  const checks = [
+    checkNode(),
+    checkTmux(existsImpl, opts.tmuxBin),
+    checkPty(ptyLoad),
+    checkService(platform, home, execImpl, uidVal, opts.installPath),
+    checkBoot(platform, home, execImpl),
+    checkTokenPerms(tokenPath),
+    checkSshClient(existsImpl),
+    checkSshPermitlisten(opts.sshVersion),
+  ];
+
+  for (const c of checks) {
+    const tag = c.ok ? (c.warn ? 'WARN' : 'OK  ') : 'FAIL';
+    log(`${tag}  ${c.name}${c.detail ? ' — ' + c.detail : ''}`);
+  }
+  const ok = checks.every((c) => c.ok); // i warn non fanno fallire
+  log(ok ? 'doctor: tutto ok' : 'doctor: problemi rilevati (vedi FAIL sopra)');
+  return { platform, checks, ok, code: ok ? 0 : 1 };
+}
+
+module.exports = {
+  doctor, nodeMajor,
+  checkNode, checkTmux, checkPty, checkService, checkBoot, checkTokenPerms,
+  checkSshClient, checkSshPermitlisten,
+};

package/lib/cli/fleet-service.js

@@ -74,6 +74,10 @@ function generateFleetMac(opts) {
   const entryXml = escapeXml(opts.entryPath);
   const repoXml = escapeXml(repoRoot);
   const homeXml = escapeXml(home);
+  const launchPath = [...new Set([
+    path.dirname(opts.nodeBin), '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin',
+  ])].join(':');
+  const launchPathXml = escapeXml(launchPath);
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -88,6 +92,11 @@ function generateFleetMac(opts) {
   </array>
   <key>WorkingDirectory</key>
   <string>${repoXml}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>${launchPathXml}</string>
+  </dict>
   <key>RunAtLoad</key>
   <true/>
   <key>StandardOutPath</key>
@@ -235,10 +244,11 @@ function fleetInstallCommands(platform, target, ctx) {
     ];
   }
   if (platform === 'mac') {
-    const label = `gui/${ctx.uid || uid()}/com.mmmbuto.nexuscrew-fleet`;
+    const domain = `gui/${ctx.uid || uid()}`;
+    const label = `${domain}/com.mmmbuto.nexuscrew-fleet`;
     return [
       ['launchctl', ['bootout', label]],      // idempotente: ignorato se non caricato
-      ['launchctl', ['bootstrap', label, target]],
+      ['launchctl', ['bootstrap', domain, target]],
     ];
   }
   if (platform === 'termux') {
@@ -285,7 +295,10 @@ function installFleetService(platform, content, ctx, { dryRun = false, execImpl
   const failures = [];
   for (const [bin, args] of cmds) {
     try { execImpl(bin, args, { stdio: 'ignore' }); }
-    catch (e) { failures.push({ cmd: `${bin} ${args.join(' ')}`, error: e.message }); }
+    catch (e) {
+      if (platform === 'mac' && bin === 'launchctl' && args[0] === 'bootout') continue;
+      failures.push({ cmd: `${bin} ${args.join(' ')}`, error: e.message });
+    }
   }
 
   return { target, mode, written: true, failures };

package/lib/cli/init.js

@@ -8,7 +8,6 @@
 const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
-const { execFileSync } = require('node:child_process');
 const { detectPlatform, nodeBin, repoRoot, uid } = require('./platform.js');
 const { loadOrCreateToken } = require('../auth/token.js');
 const { generateService, installService, fileMode, installPath: svcInstallPath } = require('./service.js');
@@ -17,10 +16,12 @@ const {
   generateFleetService, installFleetService, migrationGate,
   selectProviderModeSync, fleetFileMode,
 } = require('./fleet-service.js');
+const { atomicWrite: writeFleet } = require('../fleet/definitions.js');
+const { defaultDefinitions } = require('../fleet/managed.js');
+const { commandExists } = require('./path.js');
 
-function haveTmux(tmuxBin) {
-  try { execFileSync('command', ['-v', tmuxBin], { stdio: 'ignore', shell: true }); return true; }
-  catch (_) { return false; }
+function haveTmux(tmuxBin, env = process.env) {
+  return commandExists(tmuxBin, env);
 }
 
 function nodeMajor() {
@@ -87,6 +88,20 @@ function runInit(opts = {}) {
       actions.push(`preserved config ${configPath} (port ${port})`);
     }
   }
+
+  // Fleet app defaults: soltanto i due client nativi. Provider cloud/Z.AI sono
+  // disponibili nel catalogo managed ma vanno aggiunti esplicitamente.
+  const fleetDefsPath = opts.fleetDefsPath || path.join(configDir, 'fleet.json');
+  if (!dryRun && !fs.existsSync(fleetDefsPath)) {
+    try {
+      writeFleet(fleetDefsPath, defaultDefinitions());
+      actions.push(`created fleet defaults ${fleetDefsPath} (claude.native, codex-vl.native)`);
+    } catch (e) {
+      actions.push(`WARN: fleet defaults non creati: ${e.message}`);
+    }
+  } else if (!dryRun) {
+    actions.push(`preserved fleet definitions ${fleetDefsPath}`);
+  }
   if (!port) port = 41820;
 
   // token (preserva esistente) [M4]
@@ -104,6 +119,22 @@ function runInit(opts = {}) {
     actions.push(`files root ${filesRoot}`);
   }
 
+  // nodes.json (B0): nodeId STABILE per installazione (generato qui se manca) +
+  // migrazione esplicita guarded dei nodes legacy da config.json. READONLY/dry-run
+  // saltano; ogni errore -> WARN, MAI far fallire l'init.
+  if (!dryRun && process.env.NEXUSCREW_READONLY !== '1' && !opts.readonly) {
+    try {
+      const nstore = require('../nodes/store.js');
+      const nodesPath = opts.nodesPath || path.join(configDir, 'nodes.json');
+      const st = nstore.loadOrInitStore(nodesPath);
+      actions.push(`nodes.json ok (${nodesPath}, nodeId ${st.nodeId.slice(0, 8)}…)`);
+      const mig = nstore.migrateLegacyNodes(configPath, nodesPath);
+      if (mig.migrated) actions.push(`nodes: migrati ${mig.count} nodi legacy da config.json`);
+    } catch (e) {
+      actions.push(`WARN: nodes.json init/migrazione fallita: ${e.message} (init prosegue)`);
+    }
+  }
+
   // service generation
   const svcCtx = {
     repoRoot: repoRoot(),
@@ -153,7 +184,7 @@ function runInit(opts = {}) {
         fleetBin: opts.fleetBin || path.join(home, '.local', 'bin', 'fleet'),
         fleetProvider: opts.fleetProvider || process.env.NEXUSCREW_FLEET_PROVIDER,
         builtinEnabled: opts.builtinEnabled,
-        fleetDefsPath: opts.fleetDefsPath || path.join(configDir, 'fleet.json'),
+        fleetDefsPath,
       };
       const sel = selectProvider(fleetCfg) || {};
       if (sel.mode !== 'builtin') {
@@ -206,7 +237,9 @@ function runInit(opts = {}) {
   const url = `http://127.0.0.1:${port}/`;
   const urlWithToken = token ? `${url}#token=${token}` : url;
   actions.push(`platform: ${platform}`);
-  actions.push(`URL: ${urlWithToken}`);
+  // printUrl:false -> non stampare l'URL col token (usato da smart-up, che presenta
+  // URL base + QR da se': cosi' l'output di smart-up non contiene il token in chiaro).
+  if (opts.printUrl !== false) actions.push(`URL: ${urlWithToken}`);
 
   for (const a of actions) log(a);
 

package/lib/cli/path.js

@@ -0,0 +1,24 @@
+'use strict';
+// Risoluzione eseguibili senza shell: nessun `command -v`, nessuna espansione
+// o concatenazione di input. Supporta path assoluti/espliciti e scan di PATH.
+const fs = require('node:fs');
+const path = require('node:path');
+
+function executable(p) {
+  try {
+    const st = fs.statSync(p);
+    if (!st.isFile()) return false;
+    fs.accessSync(p, fs.constants.X_OK);
+    return true;
+  } catch (_) { return false; }
+}
+
+function commandExists(bin, env = process.env) {
+  if (typeof bin !== 'string' || !bin || bin.includes('\0')) return false;
+  if (path.isAbsolute(bin) || bin.includes('/') || bin.includes('\\')) return executable(bin);
+  return String((env && env.PATH) || '').split(path.delimiter)
+    .filter(Boolean)
+    .some((dir) => executable(path.join(dir, bin)));
+}
+
+module.exports = { commandExists };

package/lib/cli/service.js

@@ -87,6 +87,10 @@ function generateMac(ctx) {
   const repoXml = escapeXml(ctx.repoRoot);
   const homeXml = escapeXml(ctx.home);
   const port = ctx.port;
+  const launchPath = [...new Set([
+    path.dirname(ctx.nodeBin), '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin',
+  ])].join(':');
+  const launchPathXml = escapeXml(launchPath);
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -105,6 +109,8 @@ function generateMac(ctx) {
   <dict>
     <key>NEXUSCREW_PORT</key>
     <string>${port}</string>
+    <key>PATH</key>
+    <string>${launchPathXml}</string>
   </dict>
   <key>RunAtLoad</key>
   <true/>
@@ -193,7 +199,11 @@ function installService(platform, content, ctx, { dryRun = false, execImpl = exe
   const failures = [];
   for (const [bin, args] of cmds) {
     try { execImpl(bin, args, { stdio: 'ignore' }); }
-    catch (e) { failures.push({ cmd: `${bin} ${args.join(' ')}`, error: e.message }); }
+    catch (e) {
+      // bootout e' idempotente: un job non ancora caricato non e' un errore di installazione.
+      if (platform === 'mac' && bin === 'launchctl' && args[0] === 'bootout') continue;
+      failures.push({ cmd: `${bin} ${args.join(' ')}`, error: e.message });
+    }
   }
 
   return { target, mode, written: true, failures };
@@ -208,11 +218,12 @@ function installCommands(platform, target, ctx) {
     ];
   }
   if (platform === 'mac') {
-    const label = `gui/${ctx.uid || uid()}/com.mmmbuto.nexuscrew`;
+    const domain = `gui/${ctx.uid || uid()}`;
+    const label = `${domain}/com.mmmbuto.nexuscrew`;
     // bootout (ignore se non esiste) poi bootstrap
     return [
       ['launchctl', ['bootout', label]],
-      ['launchctl', ['bootstrap', label, target]],
+      ['launchctl', ['bootstrap', domain, target]],
     ];
   }
   if (platform === 'termux') {

package/lib/cli/url.js

@@ -0,0 +1,63 @@
+'use strict';
+// URL/token helpers per la CLI unificata (design §3). [A2]
+// - resolvePaths: config/token path home-aware (seam per test con HOME temporanea).
+// - readToken: legge il token esistente SENZA crearlo (no-follow symlink), null se assente.
+// - loadPort: porta corrente (opts > env > config.json > default 41820).
+// - buildUrl: URL loopback; withToken aggiunge #token=… (UNICO posto dove il token appare).
+// - renderQr: QR ASCII generato in locale (qrcode-terminal, MIT) — NIENTE fetch a runtime.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { readTokenSafe } = require('../auth/token.js');
+
+const DEFAULT_PORT = 41820;
+
+function resolvePaths(opts = {}) {
+  const home = opts.home || os.homedir();
+  const configDir = opts.configDir || path.join(home, '.nexuscrew');
+  return {
+    home,
+    configDir,
+    configPath: opts.configPath || path.join(configDir, 'config.json'),
+    tokenPath: opts.tokenPath || path.join(configDir, 'token'),
+  };
+}
+
+// Legge il token esistente (no create). Symlink -> throw (readTokenSafe); assente -> null.
+function readToken(tokenPath) {
+  try {
+    return readTokenSafe(tokenPath);
+  } catch (e) {
+    if (e.code === 'ENOENT') return null; // lstat su path inesistente
+    throw e; // symlink / permessi -> propaga
+  }
+}
+
+// Porta corrente: opts.port > env NEXUSCREW_PORT > config.json > default.
+function loadPort(opts = {}) {
+  if (opts.port) return Number(opts.port);
+  if (process.env.NEXUSCREW_PORT) return Number(process.env.NEXUSCREW_PORT);
+  const { configPath } = resolvePaths(opts);
+  try {
+    const c = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    if (c && c.port) return Number(c.port);
+  } catch (_) {}
+  return DEFAULT_PORT;
+}
+
+// URL loopback. withToken=true e token presente -> aggiunge #token=… (mai altrove).
+function buildUrl(port, token, { withToken = false } = {}) {
+  const base = `http://127.0.0.1:${port}/`;
+  return withToken && token ? `${base}#token=${token}` : base;
+}
+
+// QR ASCII del testo. Generazione locale (qrcode-terminal), callback sincrona.
+// small=true -> QR compatto (half-block chars) leggibile su terminale mobile/Termux.
+function renderQr(text, opts = {}) {
+  const qrcode = opts.qrcode || require('qrcode-terminal');
+  let out = '';
+  qrcode.generate(String(text), { small: opts.small !== false }, (s) => { out = s; });
+  return out;
+}
+
+module.exports = { resolvePaths, readToken, loadPort, buildUrl, renderQr, DEFAULT_PORT };

package/lib/config.js

@@ -20,6 +20,8 @@ function baseDefaults() {
     tokenPath: path.join(os.homedir(), '.nexuscrew', 'token'),
     tmuxBin: 'tmux',
     readonlyDefault: false,
+    // Etichetta neutra usata nel prefisso delle risposte ask incollate in TUI.
+    replyLabel: 'human',
     filesRoot: path.join(os.homedir(), 'NexusFiles'),
     maxUpload: 100 * 1024 * 1024,
     voiceUrl: null,
@@ -27,6 +29,7 @@ function baseDefaults() {
     voiceTokenFile: null,
     fleetEnabled: true,
     fleetBin: path.join(os.homedir(), '.local', 'bin', 'fleet'),
+    providerSecretsPath: path.join(os.homedir(), '.nexuscrew', 'providers.env'),
     sessionPresets: {},
   };
 }
@@ -51,6 +54,7 @@ function envOverrides() {
   if (process.env.NEXUSCREW_TOKEN_FILE) e.tokenPath = process.env.NEXUSCREW_TOKEN_FILE;
   if (process.env.NEXUSCREW_TMUX) e.tmuxBin = process.env.NEXUSCREW_TMUX;
   if (process.env.NEXUSCREW_READONLY) e.readonlyDefault = process.env.NEXUSCREW_READONLY === '1';
+  if (process.env.NEXUSCREW_REPLY_LABEL) e.replyLabel = process.env.NEXUSCREW_REPLY_LABEL;
   if (process.env.NEXUSCREW_FILES_ROOT) e.filesRoot = process.env.NEXUSCREW_FILES_ROOT;
   if (process.env.NEXUSCREW_MAX_UPLOAD_MB) e.maxUpload = Number(process.env.NEXUSCREW_MAX_UPLOAD_MB) * 1024 * 1024;
   if (process.env.NEXUSCREW_VOICE_URL) e.voiceUrl = process.env.NEXUSCREW_VOICE_URL;
@@ -58,6 +62,7 @@ function envOverrides() {
   if (process.env.NEXUSCREW_VOICE_TOKEN_FILE) e.voiceTokenFile = process.env.NEXUSCREW_VOICE_TOKEN_FILE;
   if (process.env.NEXUSCREW_FLEET) e.fleetEnabled = process.env.NEXUSCREW_FLEET !== '0';
   if (process.env.NEXUSCREW_FLEET_BIN) e.fleetBin = process.env.NEXUSCREW_FLEET_BIN;
+  if (process.env.NEXUSCREW_PROVIDER_SECRETS) e.providerSecretsPath = process.env.NEXUSCREW_PROVIDER_SECRETS;
   return e;
 }
 

package/lib/decks/routes.js

@@ -0,0 +1,81 @@
+'use strict';
+const express = require('express');
+const fs = require('node:fs');
+const store = require('./store.js');
+
+function httpError(status, message, extra) {
+  const e = new Error(message); e.status = status; e.extra = extra; return e;
+}
+
+function decksRoutes({ cfg = {}, decksPath }) {
+  const r = express.Router();
+  r.use(express.json({ limit: '64kb' }));
+  const readonly = () => cfg.readonlyDefault === true || process.env.NEXUSCREW_READONLY === '1';
+  const mutate = (fn) => (req, res) => {
+    if (readonly()) return res.status(403).json({ error: 'READONLY: mutazione deck bloccata' });
+    try { return fn(req, res); }
+    catch (e) { return res.status(e.status || 500).json({ error: String(e.message || e), ...(e.extra || {}) }); }
+  };
+  const read = () => {
+    const found = store.loadStore(decksPath);
+    if (found) return found;
+    if (readonly() && !fs.existsSync(decksPath)) return store.emptyStore();
+    return store.loadOrCreate(decksPath);
+  };
+  const expected = (body) => {
+    const n = body && body.expectedRevision;
+    if (!Number.isSafeInteger(n) || n < 0) throw httpError(400, 'expectedRevision non valida');
+    return n;
+  };
+  const find = (st, name) => st.decks.find((d) => d.name === name) || null;
+  const checkRevision = (deck, rev) => {
+    if (deck.revision !== rev) throw httpError(409, 'deck modificato da un’altra finestra', { current: deck });
+  };
+
+  r.get('/', (_req, res) => {
+    try { res.json(read()); } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+  });
+  r.post('/', mutate((req, res) => {
+    const name = String(req.body && req.body.name || '');
+    if (!store.NAME_RE.test(name)) throw httpError(400, 'nome deck non valido');
+    const st = read();
+    if (find(st, name)) throw httpError(409, `deck già esistente: ${name}`);
+    if (st.decks.length >= store.MAX_DECKS) throw httpError(400, 'limite deck raggiunto');
+    const deck = { name, revision: 0, layout: { columns: [] } };
+    st.decks.push(deck); store.atomicWrite(decksPath, st);
+    res.status(201).json(deck);
+  }));
+  r.put('/:name', mutate((req, res) => {
+    const st = read(); const deck = find(st, String(req.params.name || ''));
+    if (!deck) throw httpError(404, 'deck inesistente');
+    checkRevision(deck, expected(req.body));
+    const layout = store.parseLayout(req.body && req.body.layout);
+    if (!layout) throw httpError(400, 'layout deck non valido');
+    deck.layout = layout; deck.revision += 1;
+    store.atomicWrite(decksPath, st); res.json(deck);
+  }));
+  r.patch('/:name', mutate((req, res) => {
+    const oldName = String(req.params.name || '');
+    if (oldName === 'main') throw httpError(400, 'main non rinominabile');
+    const newName = String(req.body && req.body.name || '');
+    if (!store.NAME_RE.test(newName)) throw httpError(400, 'nome deck non valido');
+    const st = read(); const deck = find(st, oldName);
+    if (!deck) throw httpError(404, 'deck inesistente');
+    checkRevision(deck, expected(req.body));
+    if (find(st, newName)) throw httpError(409, `deck già esistente: ${newName}`);
+    deck.name = newName; deck.revision += 1;
+    store.atomicWrite(decksPath, st); res.json(deck);
+  }));
+  r.delete('/:name', mutate((req, res) => {
+    const name = String(req.params.name || '');
+    if (name === 'main') throw httpError(400, 'main non eliminabile');
+    const st = read(); const deck = find(st, name);
+    if (!deck) throw httpError(404, 'deck inesistente');
+    checkRevision(deck, expected(req.body));
+    st.decks = st.decks.filter((d) => d.name !== name);
+    store.atomicWrite(decksPath, st); res.json({ removed: true, name });
+  }));
+  return r;
+}
+
+module.exports = { decksRoutes };

package/lib/decks/store.js

@@ -0,0 +1,117 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+
+const SCHEMA_VERSION = 1;
+const MAX_DECKS = 24;
+const MAX_TILES = 9;
+const NAME_RE = /^[a-z0-9-]{1,32}$/;
+const NODE_RE = /^[a-z0-9-]{1,32}$/;
+
+function defaultDecksPath(home) {
+  return path.join(home || os.homedir(), '.nexuscrew', 'decks.json');
+}
+
+function emptyLayout() { return { columns: [] }; }
+function emptyStore() {
+  return { schemaVersion: SCHEMA_VERSION, decks: [{ name: 'main', revision: 0, layout: emptyLayout() }] };
+}
+
+function validText(s, max) {
+  if (typeof s !== 'string' || !s || s.length > max) return false;
+  for (let i = 0; i < s.length; i += 1) {
+    const c = s.charCodeAt(i);
+    if (c <= 0x1f || c === 0x7f) return false;
+  }
+  return true;
+}
+
+function parseLayout(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw) || !Array.isArray(raw.columns)) return null;
+  if (raw.columns.length > MAX_TILES) return null;
+  const seen = new Set();
+  const columns = [];
+  let count = 0;
+  for (const c of raw.columns) {
+    if (!c || typeof c !== 'object' || Array.isArray(c) || !Array.isArray(c.tiles) || !c.tiles.length) return null;
+    const width = Number(c.width);
+    if (!Number.isFinite(width) || width < 0.2 || width > 100) return null;
+    const tiles = [];
+    for (const t of c.tiles) {
+      if (!t || typeof t !== 'object' || Array.isArray(t) || !validText(t.session, 128)) return null;
+      if (t.node !== undefined && (typeof t.node !== 'string' || !NODE_RE.test(t.node))) return null;
+      const height = Number(t.height);
+      const fontSize = Number(t.fontSize);
+      if (!Number.isFinite(height) || height < 0.2 || height > 100) return null;
+      if (!Number.isFinite(fontSize) || fontSize < 9 || fontSize > 24) return null;
+      const key = t.node ? `${t.node}:${t.session}` : t.session;
+      if (seen.has(key) || ++count > MAX_TILES) return null;
+      seen.add(key);
+      const tile = { session: t.session, height, fontSize };
+      if (t.node) tile.node = t.node;
+      tiles.push(tile);
+    }
+    columns.push({ width, tiles });
+  }
+  return { columns };
+}
+
+function parseStore(raw) {
+  try {
+    const obj = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)
+      || obj.schemaVersion !== SCHEMA_VERSION || !Array.isArray(obj.decks)
+      || obj.decks.length < 1 || obj.decks.length > MAX_DECKS) return null;
+    const names = new Set();
+    const decks = [];
+    for (const d of obj.decks) {
+      if (!d || typeof d !== 'object' || !NAME_RE.test(d.name) || names.has(d.name)) return null;
+      if (!Number.isSafeInteger(d.revision) || d.revision < 0) return null;
+      const layout = parseLayout(d.layout);
+      if (!layout) return null;
+      names.add(d.name);
+      decks.push({ name: d.name, revision: d.revision, layout });
+    }
+    if (!names.has('main')) return null;
+    decks.sort((a, b) => (a.name === 'main' ? -1 : b.name === 'main' ? 1 : a.name.localeCompare(b.name)));
+    return { schemaVersion: SCHEMA_VERSION, decks };
+  } catch (_) { return null; }
+}
+
+function loadStore(p) {
+  try {
+    const st = fs.lstatSync(p);
+    if (!st.isFile() || st.isSymbolicLink()) return null;
+    return parseStore(fs.readFileSync(p, 'utf8'));
+  } catch (_) { return null; }
+}
+
+function atomicWrite(p, data) {
+  try {
+    if (fs.lstatSync(p).isSymbolicLink()) throw new Error('refuse symlink decks.json');
+  } catch (e) { if (e.code !== 'ENOENT') throw e; }
+  const parsed = parseStore(data);
+  if (!parsed) throw new Error('decks.json non valido');
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const tmp = path.join(path.dirname(p), `.${path.basename(p)}.${crypto.randomBytes(6).toString('hex')}.tmp`);
+  try {
+    fs.writeFileSync(tmp, `${JSON.stringify(parsed, null, 2)}\n`, { mode: 0o600 });
+    fs.chmodSync(tmp, 0o600);
+    fs.renameSync(tmp, p);
+  } catch (e) { try { fs.unlinkSync(tmp); } catch (_) {} throw e; }
+  return parsed;
+}
+
+function loadOrCreate(p) {
+  const found = loadStore(p);
+  if (found) return found;
+  try { if (fs.existsSync(p)) throw new Error('decks.json presente ma invalido'); } catch (e) { throw e; }
+  return atomicWrite(p, emptyStore());
+}
+
+module.exports = {
+  SCHEMA_VERSION, MAX_DECKS, MAX_TILES, NAME_RE,
+  defaultDecksPath, emptyStore, parseLayout, parseStore, loadStore, loadOrCreate, atomicWrite,
+};