@mmmbuto/nexuscrew 0.7.6 → 0.8.0

package/lib/fleet/managed.js

@@ -0,0 +1,211 @@
+'use strict';
+// Profili engine gestiti da NexusCrew. La configurazione descrive client e
+// provider; command/argv/env effettivi vengono composti qui, senza shell e senza
+// salvare segreti in fleet.json. I profili custom v1 restano supportati.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const OLLAMA_CLOUD_MODELS = Object.freeze([
+  'glm-5.2', 'kimi-k2.7-code', 'deepseek-v4-pro', 'minimax-m3',
+  'qwen3.5:397b', 'deepseek-v4-flash', 'mistral-large-3:675b', 'gemma4:31b',
+]);
+const OLLAMA_CONTEXT = Object.freeze({
+  'glm-5.2': 1000000,
+  'kimi-k2.7-code': 262144,
+  'deepseek-v4-pro': 524288,
+  'minimax-m3': 524288,
+  'qwen3.5:397b': 262144,
+  'deepseek-v4-flash': 1048576,
+  'mistral-large-3:675b': 262144,
+  'gemma4:31b': 262144,
+});
+
+const CATALOG = Object.freeze([
+  { id: 'claude.native', client: 'claude', provider: 'native', label: 'Claude · Native', auth: 'login', endpoint: 'Anthropic account', rc: true, default: true },
+  { id: 'codex-vl.native', client: 'codex-vl', provider: 'native', label: 'Codex-VL · Native', auth: 'login', endpoint: 'OpenAI account', rc: false, default: true },
+  { id: 'claude.ollama-cloud', client: 'claude', provider: 'ollama-cloud', label: 'Claude · Ollama Cloud Direct', auth: 'OLLAMA_API_KEY', endpoint: 'https://ollama.com', model: 'glm-5.2', models: OLLAMA_CLOUD_MODELS, rc: false, default: false },
+  { id: 'codex-vl.ollama-cloud', client: 'codex-vl', provider: 'ollama-cloud', label: 'Codex-VL · Ollama Cloud Direct', auth: 'OLLAMA_API_KEY', endpoint: 'https://ollama.com/v1', model: 'glm-5.2', models: OLLAMA_CLOUD_MODELS, rc: false, default: false },
+  { id: 'claude.zai-a', client: 'claude', provider: 'zai-a', label: 'Claude · Z.AI A', auth: 'ZAI_API_KEY_A', endpoint: 'https://api.z.ai/api/anthropic', model: 'glm-5.2[1m]', models: ['glm-5.2[1m]'], rc: false, default: false },
+  { id: 'claude.zai-p', client: 'claude', provider: 'zai-p', label: 'Claude · Z.AI P', auth: 'ZAI_API_KEY_P', endpoint: 'https://api.z.ai/api/anthropic', model: 'glm-5.2[1m]', models: ['glm-5.2[1m]'], rc: false, default: false },
+]);
+
+const byPair = (client, provider) => CATALOG.find((p) => p.client === client && p.provider === provider) || null;
+
+function normalizeManagedSpec(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const keys = Object.keys(value);
+  if (keys.some((k) => !['client', 'provider', 'model'].includes(k))) return null;
+  const profile = byPair(value.client, value.provider);
+  if (!profile) return null;
+  const model = value.model === undefined ? (profile.model || '') : value.model;
+  if (typeof model !== 'string' || model.length > 128) return null;
+  return { client: profile.client, provider: profile.provider, model };
+}
+
+function defaultDefinitions() {
+  return {
+    schemaVersion: 1,
+    engines: CATALOG.filter((p) => p.default).map((p) => ({
+      id: p.id, label: p.label, rc: p.rc,
+      managed: { client: p.client, provider: p.provider, model: p.model || '' },
+    })),
+    cells: [],
+  };
+}
+
+function parseEnvFile(file) {
+  const out = {};
+  let raw;
+  try {
+    const st = fs.lstatSync(file);
+    if (!st.isFile() || st.isSymbolicLink() || (st.mode & 0o077)) return out;
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (_) { return out; }
+  for (const line of raw.split(/\r?\n/)) {
+    const m = line.match(/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
+    if (!m) continue;
+    let value = m[2];
+    if ((value.startsWith("'") && value.endsWith("'")) || (value.startsWith('"') && value.endsWith('"'))) value = value.slice(1, -1);
+    out[m[1]] = value;
+  }
+  return out;
+}
+
+function binaryCandidates(client, home) {
+  const prefix = process.env.PREFIX || '';
+  if (client === 'claude') return [path.join(home, '.local', 'bin', 'claude'), '/usr/local/bin/claude', '/opt/homebrew/bin/claude', prefix && path.join(prefix, 'bin', 'claude')].filter(Boolean);
+  return [path.join(home, '.local', 'bin', 'codex-vl'), '/usr/local/bin/codex-vl', '/opt/homebrew/bin/codex-vl', prefix && path.join(prefix, 'bin', 'codex-vl')].filter(Boolean);
+}
+
+function findBinary(client, home) {
+  for (const candidate of binaryCandidates(client, home)) {
+    try {
+      const real = fs.realpathSync(candidate);
+      const st = fs.lstatSync(real);
+      if (!st.isFile() || !(st.mode & 0o100) || (st.mode & 0o002)) continue;
+      if (typeof process.getuid === 'function' && st.uid !== process.getuid() && st.uid !== 0) continue;
+      return real;
+    } catch (_) { /* next */ }
+  }
+  return null;
+}
+
+function secretsPath(cfg, home) {
+  return cfg.providerSecretsPath || process.env.NEXUSCREW_PROVIDER_SECRETS
+    || path.join(home, '.nexuscrew', 'providers.env');
+}
+
+let ollamaCache = { at: 0, models: [] };
+async function discoverOllamaModels(opts = {}) {
+  const now = Date.now();
+  const ttl = opts.ttlMs === undefined ? 30000 : opts.ttlMs;
+  if (!opts.noCache && ollamaCache.models.length && now - ollamaCache.at < ttl) return [...ollamaCache.models];
+  const fetchImpl = opts.fetchImpl || globalThis.fetch;
+  if (typeof fetchImpl !== 'function') return [...OLLAMA_CLOUD_MODELS];
+  try {
+    const home = opts.home || require('node:os').homedir();
+    const apiKey = opts.apiKey || parseEnvFile(secretsPath(opts, home)).OLLAMA_API_KEY;
+    if (!apiKey) throw new Error('OLLAMA_API_KEY mancante');
+    const response = await fetchImpl('https://ollama.com/api/tags', {
+      headers: { authorization: `Bearer ${apiKey}` },
+      signal: typeof AbortSignal !== 'undefined' && AbortSignal.timeout ? AbortSignal.timeout(2500) : undefined,
+    });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    const body = await response.json();
+    const available = new Set();
+    for (const item of Array.isArray(body.models) ? body.models : []) {
+      const name = typeof item?.name === 'string' ? item.name : '';
+      if (!/^[A-Za-z0-9._-]+(?::[A-Za-z0-9._-]+)?$/.test(name) || name.length > 128) continue;
+      available.add(name);
+    }
+    // La API diretta espone molti modelli, inclusi modelli in deprecazione. La UI
+    // mantiene la shortlist TOP curata, ma solo se ancora realmente disponibile.
+    const models = OLLAMA_CLOUD_MODELS.filter((name) => available.has(name));
+    if (!models.length) throw new Error('nessun modello cloud');
+    ollamaCache = { at: now, models };
+    return [...models];
+  } catch (_) {
+    ollamaCache = { at: now, models: [...OLLAMA_CLOUD_MODELS] };
+    return [...OLLAMA_CLOUD_MODELS];
+  }
+}
+
+function describeManaged(spec, cfg = {}) {
+  const normalized = normalizeManagedSpec(spec);
+  if (!normalized) return { configured: false, reason: 'profilo managed non valido' };
+  const home = cfg.home || require('node:os').homedir();
+  const profile = byPair(normalized.client, normalized.provider);
+  const binary = findBinary(normalized.client, home);
+  const secretFile = secretsPath(cfg, home);
+  const secrets = profile.auth === 'login' || profile.auth === 'none' ? {} : parseEnvFile(secretFile);
+  const authConfigured = profile.auth === 'login' || profile.auth === 'none' || !!secrets[profile.auth];
+  const configured = !!binary && authConfigured;
+  return {
+    client: profile.client, provider: profile.provider, model: normalized.model,
+    endpoint: profile.endpoint, auth: profile.auth, authConfigured, configured,
+    models: [...(profile.models || [])], defaultModel: profile.model || '',
+    binary: binary || '',
+    reason: !binary ? `client ${profile.client} non trovato` : (!authConfigured ? `credenziale ${profile.auth} mancante` : 'ready'),
+  };
+}
+
+function resolveManagedEngine(engine, cell, cfg = {}) {
+  const info = describeManaged(engine.managed, cfg);
+  if (!info.configured) return { ok: false, reason: info.reason, info };
+  const home = cfg.home || require('node:os').homedir();
+  const env = {};
+  const args = [];
+  const model = (cell && cell.model) || info.model;
+  if (info.client === 'claude') {
+    args.push('--dangerously-skip-permissions');
+    if (info.provider === 'native') {
+      if (engine.rc !== false) args.push('--remote-control', `Cloud_${cell.id}`);
+    } else if (info.provider === 'ollama-cloud') {
+      const secrets = parseEnvFile(secretsPath(cfg, home));
+      Object.assign(env, {
+        ANTHROPIC_BASE_URL: 'https://ollama.com', ANTHROPIC_AUTH_TOKEN: secrets.OLLAMA_API_KEY,
+        ANTHROPIC_API_KEY: '',
+        ANTHROPIC_MODEL: model, ANTHROPIC_SMALL_FAST_MODEL: model, API_TIMEOUT_MS: '3000000',
+        CLAUDE_CODE_AUTO_COMPACT_WINDOW: String(OLLAMA_CONTEXT[model] || 200000),
+      });
+    } else {
+      const profile = byPair(info.client, info.provider);
+      const secrets = parseEnvFile(secretsPath(cfg, home));
+      Object.assign(env, {
+        ANTHROPIC_BASE_URL: profile.endpoint, ANTHROPIC_AUTH_TOKEN: secrets[profile.auth],
+        ANTHROPIC_MODEL: model, ANTHROPIC_SMALL_FAST_MODEL: model,
+        API_TIMEOUT_MS: '3000000', CLAUDE_CODE_AUTO_COMPACT_WINDOW: '1000000',
+      });
+    }
+    if (model) args.push('--model', model);
+  } else {
+    args.push('--dangerously-bypass-approvals-and-sandbox');
+    if (info.provider === 'ollama-cloud') {
+      const secrets = parseEnvFile(secretsPath(cfg, home));
+      env.OPENAI_API_KEY = secrets.OLLAMA_API_KEY;
+      if (model) args.push('-m', model);
+      const localCatalog = path.join(home, '.codex', 'ollama_cloud_model_catalog.json');
+      args.push(
+        '-c', 'model_provider="ollama_cloud"',
+        '-c', 'model_providers.ollama_cloud.name="Ollama Cloud"',
+        '-c', 'model_providers.ollama_cloud.base_url="https://ollama.com/v1"',
+        '-c', 'model_providers.ollama_cloud.wire_api="responses"',
+        '-c', 'model_providers.ollama_cloud.stream_idle_timeout_ms=600000',
+        '-c', `model_context_window=${OLLAMA_CONTEXT[model] || 200000}`,
+      );
+      // Codex carica il catalogo solo all'avvio. Il file e' locale e opzionale:
+      // sui device che non lo hanno resta valido il fallback context-window sopra.
+      if (fs.existsSync(localCatalog)) args.push('-c', `model_catalog_json="${localCatalog}"`);
+    }
+  }
+  // Entrambi i client accettano il bootstrap come argomento posizionale. Questo
+  // evita di digitare nella TUI prima che sia pronta; argv e' diretto, mai shell.
+  if (cell && cell.prompt) args.push(cell.prompt);
+  return { ok: true, info, engine: { ...engine, command: info.binary, args, env, promptMode: 'managed-argv' } };
+}
+
+module.exports = {
+  CATALOG, OLLAMA_CLOUD_MODELS, OLLAMA_CONTEXT, normalizeManagedSpec, defaultDefinitions, describeManaged,
+  discoverOllamaModels,
+  resolveManagedEngine, parseEnvFile, findBinary,
+};

package/lib/fleet/provider.js

@@ -0,0 +1,102 @@
+'use strict';
+// B4.2 — Provider selection. Sceglie UNA volta, a startup, quale fleet governa il
+// runtime (design §4b/§9b/§9g). Ritorna { mode, reason, fleet }.
+//
+//   mode ∈ 'external' | 'builtin' | 'disabled'
+//
+// Regole (design §9g):
+//  - forced (cfg.fleetProvider | NEXUSCREW_FLEET_PROVIDER): onorato e FAIL-CLOSED
+//    se indisponibile. NIENTE auto-fallback silenzioso al built-in.
+//  - auto: 'external' vince solo se fidato (binTrusted, riusato da index.js) E
+//    risponde al contratto (createFleet → available). Altrimenti 'builtin' se
+//    abilitato e fleet.json valido. Altrimenti 'disabled'.
+//
+// Il drift a runtime NON si risolve qui: e' una scelta one-shot. Se l'external
+// diventa invalido DOPO lo startup, lo status risultante sara' degraded/unavailable
+// (mai fall-through silenzioso al built-in) — gestito dal layer di status.
+const { createFleet, binTrusted } = require('./index.js');
+const { createBuiltinFleet } = require('./builtin.js');
+
+const DISABLED_FLEET = Object.freeze({
+  available: false, provider: 'disabled', isCellSession: () => false, capabilities: () => [],
+});
+
+function failClosed(mode) {
+  return {
+    mode: 'disabled',
+    reason: `fail-closed: provider forzato "${mode}" non disponibile (nessun auto-fallback, §9g)`,
+    fleet: DISABLED_FLEET,
+  };
+}
+
+// Costruisce (una volta) i candidati e ne valuta la disponibilita'.
+async function selectProvider(cfg = {}) {
+  if (cfg.fleetEnabled === false) {
+    return { mode: 'disabled', reason: 'fleet disabilitato (fleetEnabled=false)', fleet: DISABLED_FLEET };
+  }
+
+  const forced = (cfg.fleetProvider || process.env.NEXUSCREW_FLEET_PROVIDER || '').toLowerCase() || null;
+
+  // External: fidato (regular file, exec, no symlink, no world-writable) E contratto ok.
+  let extFleet = null;
+  let extReason = null;
+  if (cfg.fleetBin) {
+    if (binTrusted(cfg.fleetBin)) {
+      const f = await createFleet(cfg);          // fa status --json al boot
+      if (f.available) { extFleet = f; extReason = 'fidato + risponde al contratto'; }
+      else extReason = 'binario fidato ma non risponde al contratto (status invalido)';
+    } else {
+      extReason = 'binario non fidato (symlink/world-writable/non exec)';
+    }
+  } else {
+    extReason = 'nessun fleetBin esterno configurato';
+  }
+
+  // Builtin: abilitato + fleet.json valido.
+  let biFleet = null;
+  let biReason = null;
+  if (cfg.builtinEnabled !== false) {
+    const f = await createBuiltinFleet({ ...cfg, fleetProviderReason: 'fleet.json definitions' });
+    if (f.available) { biFleet = f; biReason = 'fleet.json valido'; }
+    else biReason = 'fleet.json mancante o invalido (fail-closed)';
+  } else {
+    biReason = 'builtin disabilitato (builtinEnabled=false)';
+  }
+
+  // --- Mode FORZATO: fail-closed se il richiesto non e' disponibile ---
+  if (forced === 'external') {
+    return extFleet
+      ? { mode: 'external', reason: `forced external (${extReason})`, fleet: extFleet }
+      : failClosed('external');
+  }
+  if (forced === 'builtin') {
+    return biFleet
+      ? { mode: 'builtin', reason: `forced builtin (${biReason})`, fleet: biFleet }
+      : failClosed('builtin');
+  }
+  if (forced === 'disabled') {
+    return { mode: 'disabled', reason: 'forced disabled', fleet: DISABLED_FLEET };
+  }
+  if (forced) {
+    return failClosed(forced); // valore forzato non riconosciuto
+  }
+
+  // --- AUTO: external fidato+contratto vince, poi builtin, poi disabled ---
+  if (extFleet) {
+    return { mode: 'external', reason: `auto: external ${extReason}`, fleet: extFleet };
+  }
+  if (biFleet) {
+    return {
+      mode: 'builtin',
+      reason: `auto: external scartato (${extReason}) → builtin (${biReason})`,
+      fleet: biFleet,
+    };
+  }
+  return {
+    mode: 'disabled',
+    reason: `auto: nessun provider disponibile — external: ${extReason}; builtin: ${biReason}`,
+    fleet: DISABLED_FLEET,
+  };
+}
+
+module.exports = { selectProvider, DISABLED_FLEET };

package/lib/fleet/routes.js

@@ -1,14 +1,39 @@
 'use strict';
 const express = require('express');
 
+// Capability minime del contratto storico per i fleet external/legacy che NON
+// dichiarano capabilities() (design §9c): status/up/down/engine/boot.
+// Il built-in B4 aggiunge define/edit/remove/schema.
+const DEFAULT_CAPS = ['status', 'up', 'down', 'engine', 'boot'];
+
+function capList(fleet) {
+  return typeof fleet.capabilities === 'function' ? fleet.capabilities() : DEFAULT_CAPS;
+}
+
+// Design §9c: una route per un metodo non supportato dal provider ritorna 501
+// (mai 404/502 ambigui). Gli errori nativi del builtin (400/403/409) passano
+// invece nel guard con il loro status.
+function requireCap(fleet, cap) {
+  if (!capList(fleet).includes(cap)) {
+    const e = new Error('not supported by this fleet provider');
+    e.status = 501;
+    throw e;
+  }
+}
+
 // Router /api/fleet — fleetP è una Promise<Fleet> (createServer non diventa
 // async): ogni handler attende la resolve; unavailable → 404 sui comandi.
-function fleetRoutes(fleetP) {
+function fleetRoutes(fleetP, cfg = {}) {
   const r = express.Router();
   r.use(express.json({ limit: '4kb' }));
 
-  const guard = (fn) => async (req, res) => {
+  const readonly = () => (cfg.readonlyDefault === true || process.env.NEXUSCREW_READONLY === '1');
+
+  const guard = (fn, opts = {}) => async (req, res) => {
     try {
+      // READONLY e' un gate di prodotto, non solo del provider built-in: deve
+      // bloccare anche il fleet esterno legacy prima che tocchi systemd/tmux reali.
+      if (opts.mutate && readonly()) return res.status(403).json({ error: 'READONLY: mutazione fleet bloccata' });
       const fleet = await fleetP;
       if (!fleet.available) return res.status(404).json({ error: 'fleet non disponibile' });
       res.json(await fn(fleet, req.body || {}));
@@ -17,17 +42,62 @@ function fleetRoutes(fleetP) {
     }
   };
 
+  // /status espone anche `provider` e `capabilities` (design §9b/§9c), oltre ai
+  // campi storici (available/cells/engines). Provider senza capabilities()
+  // (external legacy) → DEFAULT_CAPS; external senza campo provider → 'external'.
   r.get('/status', async (_req, res) => {
     try {
       const fleet = await fleetP;
-      if (!fleet.available) return res.json({ available: false });
-      res.json(await fleet.status());
+      if (!fleet.available) {
+        return res.json({
+          available: false,
+          provider: fleet.provider || 'disabled',
+          bootOwner: 'none', // §9b: provider non disponibile -> nessun boot owner
+          capabilities: capList(fleet),
+        });
+      }
+      const st = await fleet.status();
+      const provider = st.provider || fleet.provider || 'external';
+      // bootOwner (§9b): preferisce quello dichiarato dal provider (st.bootOwner);
+      // altrimenti deriva dal mode: builtin -> 'builtin', disabled -> 'none',
+      // external -> 'external'. Contratto valori: 'builtin' | 'external' | 'none'.
+      const bootOwner = st.bootOwner || (provider === 'builtin' ? 'builtin' : provider === 'disabled' ? 'none' : 'external');
+      res.json({
+        ...st,
+        provider,
+        bootOwner,
+        capabilities: capList(fleet),
+      });
     } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
   });
-  r.post('/up', guard((f, b) => f.up(String(b.cell || ''), { engine: b.engine, boot: !!b.boot })));
-  r.post('/down', guard((f, b) => f.down(String(b.cell || ''), { boot: !!b.boot })));
-  r.post('/engine', guard((f, b) => f.engine(String(b.cell || ''), String(b.engine || ''))));
-  r.post('/boot', guard((f, b) => f.boot(String(b.cell || ''), b.enabled === true)));
+
+  // /up: il built-in (capability 'edit') è definitions-driven — se il body porta
+  // un engine lo persiste sulla cella (f.engine) PRIMA di up, perché l'engine
+  // dichiarato vince sull'override runtime (ignored dal builtin.up).
+  // External legacy: passthrough up(cell,{engine,boot}) invariato.
+  r.post('/up', guard((f, b) => {
+    const cell = String(b.cell || '');
+    if (b.engine && capList(f).includes('edit')) {
+      return f.engine(cell, String(b.engine), { model: typeof b.model === 'string' ? b.model : '' }).then(() => f.up(cell));
+    }
+    return f.up(cell, { engine: b.engine, boot: !!b.boot });
+  }, { mutate: true }));
+  r.post('/down', guard((f, b) => f.down(String(b.cell || ''), { boot: !!b.boot }), { mutate: true }));
+  r.post('/restart', guard((f, b) => { requireCap(f, 'restart'); return f.restart(String(b.cell || '')); }, { mutate: true }));
+  r.post('/engine', guard((f, b) => f.engine(String(b.cell || ''), String(b.engine || ''), { model: typeof b.model === 'string' ? b.model : '' }), { mutate: true }));
+  r.post('/boot', guard((f, b) => f.boot(String(b.cell || ''), b.enabled === true), { mutate: true }));
+
+  // --- Estensione B4.2: schema + define/edit/remove (engine e cell) ---
+  // Ogni route negozia la capability del provider: mancante → 501 (§9c).
+  r.get('/schema', guard((f) => { requireCap(f, 'schema'); return f.schema(); }));
+  r.get('/definitions', guard((f) => { requireCap(f, 'definitions'); return f.definitions(); }));
+  r.post('/define-engine', guard((f, b) => { requireCap(f, 'define'); return f.defineEngine(b.def); }, { mutate: true }));
+  r.post('/edit-engine', guard((f, b) => { requireCap(f, 'edit'); return f.editEngine(b.id, b.patch, b.envChanges); }, { mutate: true }));
+  r.post('/remove-engine', guard((f, b) => { requireCap(f, 'remove'); return f.removeEngine(b.id); }, { mutate: true }));
+  r.post('/define-cell', guard((f, b) => { requireCap(f, 'define'); return f.defineCell(b.def); }, { mutate: true }));
+  r.post('/edit-cell', guard((f, b) => { requireCap(f, 'edit'); return f.editCell(b.id, b.patch); }, { mutate: true }));
+  r.post('/remove-cell', guard((f, b) => { requireCap(f, 'remove'); return f.removeCell(b.id, { stop: b.stop === true }); }, { mutate: true }));
+
   return r;
 }
 

package/lib/fs/routes.js

@@ -0,0 +1,56 @@
+'use strict';
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const express = require('express');
+
+const MAX_ENTRIES = 500;
+
+// Router /api/fs — sfoglia SOLO directory, confinato alla home (o root passata).
+// Serve al folder-picker del dialog "new session": il browser non può sfogliare
+// il filesystem del server, quindi lo fa il server, dietro lo stesso Bearer di
+// tutte le /api. Policy symlink: realpath; se la risoluzione esce dalla root
+// (symlink verso fuori) → 403. Niente file, niente contenuti: solo nomi di dir.
+function fsRoutes({ home }) {
+  const r = express.Router();
+
+  r.get('/dirs', async (req, res) => {
+    try {
+      const root = await fsp.realpath(home);
+      const q = typeof req.query.path === 'string' && req.query.path ? req.query.path : root;
+      if (q.includes('\0')) return res.status(400).json({ error: 'path non valido' });
+      let real;
+      try { real = await fsp.realpath(path.resolve(root, q)); } catch (_) {
+        return res.status(404).json({ error: 'directory inesistente' });
+      }
+      if (real !== root && !real.startsWith(root + path.sep)) {
+        return res.status(403).json({ error: 'fuori dalla home' });
+      }
+      let entries;
+      try { entries = await fsp.readdir(real, { withFileTypes: true }); } catch (e) {
+        if (e.code === 'ENOTDIR') return res.status(404).json({ error: 'non è una directory' });
+        if (e.code === 'EACCES') return res.status(403).json({ error: 'permesso negato' });
+        throw e;
+      }
+      const showHidden = req.query.hidden === '1';
+      const names = [];
+      for (const d of entries) {
+        if (!showHidden && d.name.startsWith('.')) continue;
+        if (d.isDirectory()) { names.push(d.name); continue; }
+        if (d.isSymbolicLink()) {                    // symlink: solo se risolve a una dir
+          try { if ((await fsp.stat(path.join(real, d.name))).isDirectory()) names.push(d.name); } catch (_) { /* rotto: skip */ }
+        }
+      }
+      const dirs = names.sort((a, b) => a.localeCompare(b)).slice(0, MAX_ENTRIES);
+      res.json({
+        path: real,
+        parent: real === root ? null : path.dirname(real),
+        home: root,
+        dirs,
+      });
+    } catch (e) { res.status(500).json({ error: String(e.message || e) }); }
+  });
+
+  return r;
+}
+
+module.exports = { fsRoutes };