synfull 0.1.0 → 0.1.2

package/README.md

@@ -4,7 +4,7 @@ Synfull is a local-first host monitoring dashboard for Windows and Linux, provid
 
 ## Install from npm
 
-Requirements: Node.js 18+, Python 3.10+, and npm. The CLI creates its own Python virtual environment and installs the backend dependencies when needed. Linux requires Python build prerequisites when a dependency has no wheel for the host platform.
+Requirements: Node.js 18+, Python 3.10+, and npm. The CLI creates its own Python virtual environment and installs the backend dependencies when needed. On Ubuntu/Debian, install `python3-venv` (or the matching `python3.X-venv` package) if venv creation reports that pip is missing. Linux may also require build prerequisites when a dependency has no wheel for the host platform.
 
 ```sh
 npm install -g synfull
@@ -13,11 +13,11 @@ synfull start
 synfull open
 ```
 
-The dashboard listens on **127.0.0.1:8000** only. The initial local login is username `admin`, password `admin`; Synfull will require you to set a new password of at least 12 characters before accessing the application. Do not expose the service publicly or through an untrusted proxy. npm installation alone does not register a background service or change system startup.
+During interactive `synfull setup`, you can choose whether to bind to `0.0.0.0` for access from other devices on your LAN; localhost-only (`127.0.0.1`) remains the default, and non-interactive setup stays local-only. LAN binding exposes the login page and server to every reachable network interface: use a trusted LAN, configure the host firewall to allow only the devices/subnet you intend, change the initial `admin` / `admin` password locally before signing in remotely, and do not expose Synfull directly to the public internet. npm installation alone does not register a background service or change system startup.
 
 ### Commands
 
-- `synfull setup` prepares the isolated Python runtime and dependencies.
+- `synfull setup` asks whether to allow LAN access, then prepares the isolated Python runtime and dependencies. The choice is saved in the CLI config and used by later starts and service registration.
 - `synfull start` runs in the background; `synfull run` keeps the server in the foreground.
 - `synfull status`, `synfull stop`, and `synfull open` manage a manually started instance.
 - `synfull install-service` explicitly enables automatic start and restart. On Windows this registers a per-user logon scheduled task. On Linux it creates and enables a system-wide systemd service and therefore requires `sudo`; the service runs as your invoking user, not root.
@@ -29,7 +29,7 @@ Configuration:
 
 - `SYNFULL_HOME` selects the CLI runtime/application directory.
 - `SYNFULL_STATE_DIR` selects persistent database and app state.
-- `SYNFULL_BIND_PORT` changes the localhost port (default `8000`). The listener is deliberately fixed to `127.0.0.1` in npm mode.
+- `SYNFULL_BIND_PORT` changes the port (default `8000`). The bind host is selected during interactive setup and defaults to `127.0.0.1`; `SYNFULL_BIND_HOST=127.0.0.1` or `SYNFULL_BIND_HOST=0.0.0.0` can override it for a single run/service install.
 
 ## Development from source
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synfull",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Local-first cross-platform host monitoring dashboard",
   "license": "MIT",
   "type": "commonjs",

package/scripts/synfull.cjs

@@ -5,6 +5,7 @@ const crypto = require('node:crypto')
 const fs = require('node:fs')
 const os = require('node:os')
 const path = require('node:path')
+const readline = require('node:readline/promises')
 const { spawn, spawnSync } = require('node:child_process')
 const ROOT = path.resolve(__dirname, '..')
 const VERSION = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version
@@ -29,6 +30,7 @@ const STATE_DIR = process.env.SYNFULL_STATE_DIR || (WINDOWS
 const RUNTIME = path.join(APP_DIR, '.venv', WINDOWS ? 'Scripts' : 'bin', WINDOWS ? 'python.exe' : 'python')
 const PID_FILE = path.join(HOME, 'synfull.pid')
 const LOG_FILE = path.join(HOME, 'synfull.log')
+const CLI_CONFIG = path.join(HOME, 'config.json')
 const CLI = path.resolve(__filename)
 
 function run(command, args, options = {}) {
@@ -47,6 +49,37 @@ function pythonCommand() {
   }
   throw new Error('Python 3.10+ was not found. Install Python and ensure it is on PATH, then run `synfull setup`.')
 }
+function configuredBindHost() {
+  try {
+    const config = JSON.parse(fs.readFileSync(CLI_CONFIG, 'utf8'))
+    if (config.bindHost === '0.0.0.0') return '0.0.0.0'
+  } catch {}
+  return '127.0.0.1'
+}
+function selectedBindHost() {
+  const host = process.env.SYNFULL_BIND_HOST || configuredBindHost()
+  if (!['127.0.0.1', '0.0.0.0'].includes(host)) throw new Error('SYNFULL_BIND_HOST must be 127.0.0.1 or 0.0.0.0.')
+  return host
+}
+function saveBindHost(host) {
+  if (!['127.0.0.1', '0.0.0.0'].includes(host)) throw new Error('Bind host must be 127.0.0.1 or 0.0.0.0.')
+  fs.mkdirSync(HOME, { recursive: true })
+  fs.writeFileSync(CLI_CONFIG, `${JSON.stringify({ bindHost: host }, null, 2)}\n`, { mode: 0o600 })
+}
+async function configureBindHost() {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  try {
+    const answer = await rl.question('Allow other devices on your LAN to access Synfull by binding to 0.0.0.0? (y/N): ')
+    const host = /^y(es)?$/i.test(answer.trim()) ? '0.0.0.0' : '127.0.0.1'
+    saveBindHost(host)
+    console.log(host === '0.0.0.0'
+      ? 'LAN access enabled. Change the initial admin password from this machine before signing in from another device; use a trusted LAN and configure your firewall.'
+      : 'Synfull will only accept connections from this machine.')
+  } finally {
+    rl.close()
+  }
+}
 function ensureRuntime() {
   if (!fs.existsSync(path.join(ROOT, 'backend', 'app')) || !fs.existsSync(path.join(ROOT, 'frontend', 'dist', 'index.html'))) {
     throw new Error('This npm package is missing its backend or built dashboard assets.')
@@ -61,6 +94,21 @@ function ensureRuntime() {
     const python = pythonCommand()
     run(python.command, [...python.prefix, '-m', 'venv', path.join(APP_DIR, '.venv')])
   }
+  const pipAvailable = spawnSync(RUNTIME, ['-m', 'pip', '--version'], { stdio: 'ignore', windowsHide: true }).status === 0
+  if (!pipAvailable) {
+    const python = pythonCommand()
+    const repair = spawnSync(python.command, [...python.prefix, '-m', 'venv', '--upgrade-deps', '--upgrade', path.join(APP_DIR, '.venv')], { encoding: 'utf8', windowsHide: true })
+    if (repair.status !== 0) {
+      const detail = (repair.stderr || repair.stdout || '').trim()
+      if (detail) console.error(detail)
+      const platformFix = WINDOWS
+        ? 'Repair or reinstall Python with its pip/venv components, then rerun `synfull setup`.'
+        : 'On Ubuntu/Debian install venv support (`sudo apt install python3-venv`, or the matching `python3.X-venv` package), remove the incomplete venv at ~/.local/share/synfull/app/.venv, then rerun `synfull setup`.'
+      throw new Error(`The Python virtual environment is missing pip. ${platformFix}`)
+    }
+  }
+  const pipReady = spawnSync(RUNTIME, ['-m', 'pip', '--version'], { stdio: 'ignore', windowsHide: true }).status === 0
+  if (!pipReady) throw new Error('The Python virtual environment still has no pip. Install the Python venv support package and recreate the runtime, then rerun `synfull setup`.')
   const requirementsPath = path.join(APP_DIR, 'backend', 'requirements-runtime.txt')
   const requirementsHash = crypto.createHash('sha256').update(fs.readFileSync(requirementsPath)).digest('hex')
   const installedHashPath = path.join(APP_DIR, '.runtime-requirements-hash')
@@ -78,7 +126,7 @@ function ensureRuntime() {
 function serverEnvironment() {
   return {
     ...process.env,
-    SYNFULL_BIND_HOST: '127.0.0.1',
+    SYNFULL_BIND_HOST: selectedBindHost(),
     SYNFULL_BIND_PORT: process.env.SYNFULL_BIND_PORT || '8000',
     SYNFULL_STATE_DIR: STATE_DIR,
     SYNFULL_BOOTSTRAP_DEFAULT_ADMIN: '1',
@@ -87,9 +135,12 @@ function serverEnvironment() {
 }
 function startServer(foreground) {
   ensureRuntime()
-  const args = ['-m', 'uvicorn', 'app.main:app', '--app-dir', path.join(APP_DIR, 'backend'), '--host', '127.0.0.1', '--port', process.env.SYNFULL_BIND_PORT || '8000']
+  const env = serverEnvironment()
+  const bindHost = env.SYNFULL_BIND_HOST
+  const port = process.env.SYNFULL_BIND_PORT || '8000'
+  const args = ['-m', 'uvicorn', 'app.main:app', '--app-dir', path.join(APP_DIR, 'backend'), '--host', bindHost, '--port', port]
   if (foreground) {
-    const child = spawn(RUNTIME, args, { cwd: APP_DIR, env: serverEnvironment(), stdio: 'inherit', windowsHide: true })
+    const child = spawn(RUNTIME, args, { cwd: APP_DIR, env, stdio: 'inherit', windowsHide: true })
     child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)))
     for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => child.kill(signal))
     return
@@ -99,8 +150,7 @@ function startServer(foreground) {
     try { process.kill(pid, 0); console.log(`Synfull is already running (PID ${pid}).`); return } catch { fs.rmSync(PID_FILE, { force: true }) }
   }
   const output = fs.openSync(LOG_FILE, 'a')
-  const detached = !WINDOWS
-  const child = spawn(RUNTIME, args, { cwd: APP_DIR, env: serverEnvironment(), detached, stdio: ['ignore', output, output], windowsHide: true })
+  const child = spawn(RUNTIME, args, { cwd: APP_DIR, env, detached: !WINDOWS, stdio: ['ignore', output, output], windowsHide: true })
   fs.closeSync(output)
   child.once('error', error => {
     fs.rmSync(PID_FILE, { force: true })
@@ -109,7 +159,8 @@ function startServer(foreground) {
   })
   child.once('spawn', () => {
     fs.writeFileSync(PID_FILE, String(child.pid))
-    console.log(`Synfull started at http://127.0.0.1:${process.env.SYNFULL_BIND_PORT || '8000'} (PID ${child.pid}).`)
+    console.log(`Synfull started on ${bindHost}:${port} (PID ${child.pid}).`)
+    if (bindHost === '0.0.0.0') console.log(`LAN clients can use http://<server-lan-ip>:${port}; change the initial admin password locally first.`)
   })
   child.unref()
   console.log(`Logs: ${LOG_FILE}`)
@@ -134,43 +185,44 @@ function status() {
     pid = fs.readFileSync(PID_FILE, 'utf8').trim()
     try { process.kill(Number(pid), 0); running = true } catch { fs.rmSync(PID_FILE, { force: true }) }
   }
+  const bindHost = selectedBindHost()
   console.log(`Synfull ${VERSION}: ${running ? `running (PID ${pid})` : 'stopped'}`)
-  console.log(`Dashboard: http://127.0.0.1:${process.env.SYNFULL_BIND_PORT || '8000'}`)
+  console.log(`Dashboard: http://${bindHost === '0.0.0.0' ? '<server-lan-ip>' : '127.0.0.1'}:${process.env.SYNFULL_BIND_PORT || '8000'}`)
   console.log(`Data: ${STATE_DIR}`)
 }
 function windowsTaskXml() {
-  const sid = spawnSync('whoami.exe', ['/user', '/fo', 'csv', '/nh'], { encoding: 'utf8', windowsHide: true }).stdout.match(/S-1-[0-9-]+/)
+  const identity = spawnSync('whoami.exe', ['/user', '/fo', 'csv', '/nh'], { encoding: 'utf8', windowsHide: true })
+  const sid = (identity.stdout || '').match(/S-1-[0-9-]+/)
   if (!sid) throw new Error('Could not determine the current Windows account SID.')
   const exe = process.execPath.replace(/&/g, '&amp;').replace(/</g, '&lt;')
   const cli = CLI.replace(/&/g, '&amp;').replace(/</g, '&lt;')
   return `<?xml version="1.0" encoding="UTF-16"?>\n<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task"><Triggers><LogonTrigger><Enabled>true</Enabled><UserId>${sid[0]}</UserId></LogonTrigger></Triggers><Principals><Principal id="Author"><UserId>${sid[0]}</UserId><LogonType>InteractiveToken</LogonType><RunLevel>LeastPrivilege</RunLevel></Principal></Principals><Settings><MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy><DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries><StopIfGoingOnBatteries>false</StopIfGoingOnBatteries><RestartOnFailure><Interval>PT1M</Interval><Count>999</Count></RestartOnFailure><ExecutionTimeLimit>PT0S</ExecutionTimeLimit><Enabled>true</Enabled></Settings><Actions Context="Author"><Exec><Command>${exe}</Command><Arguments>"${cli}" run</Arguments><WorkingDirectory>${APP_DIR.replace(/&/g, '&amp;').replace(/</g, '&lt;')}</WorkingDirectory></Exec></Actions></Task>`
 }
 function installStartup() {
-  if (!WINDOWS && process.getuid && process.getuid() !== 0) {
-    throw new Error('Installing the system-wide boot service requires administrator permission. Re-run with sudo; the service will still run as your original user.')
-  }
-  if (!WINDOWS) {
-    const serviceUser = process.env.SUDO_USER || os.userInfo().username
-    if (serviceUser === 'root') throw new Error('Do not install Synfull as root. Re-run `sudo synfull install-service` from your normal account.')
-  }
+  if (!WINDOWS && process.getuid && process.getuid() !== 0) throw new Error('Installing the system-wide boot service requires administrator permission. Re-run with sudo; the service will still run as your original user.')
+  if (!WINDOWS && (process.env.SUDO_USER || os.userInfo().username) === 'root') throw new Error('Do not install Synfull as root. Re-run `sudo synfull install-service` from your normal account.')
+  saveBindHost(selectedBindHost())
   ensureRuntime()
+  const bindHost = selectedBindHost()
+  const port = process.env.SYNFULL_BIND_PORT || '8000'
   if (WINDOWS) {
     const xmlPath = path.join(os.tmpdir(), `synfull-task-${process.pid}.xml`)
     fs.writeFileSync(xmlPath, `\ufeff${windowsTaskXml()}`, 'utf16le')
     try { run('schtasks.exe', ['/Create', '/TN', 'Synfull', '/XML', xmlPath, '/F']) } finally { fs.rmSync(xmlPath, { force: true }) }
-    console.log('Synfull will start at sign-in and restart after failures. It runs only on 127.0.0.1.')
+    console.log(`Synfull will start at sign-in and restart after failures. Bind address: ${bindHost}.`)
   } else {
     const serviceUser = process.env.SUDO_USER || os.userInfo().username
     fs.mkdirSync(STATE_DIR, { recursive: true })
     run('chown', ['-R', serviceUser, HOME, STATE_DIR])
     const escaped = value => value.replace(/\\/g, '\\\\').replace(/ /g, '\\x20').replace(/%/g, '%%')
-    const unit = `[Unit]\nDescription=Synfull local host monitoring\nAfter=network.target\n\n[Service]\nType=simple\nUser=${serviceUser}\nWorkingDirectory=${escaped(APP_DIR)}\nEnvironment=SYNFULL_BIND_HOST=127.0.0.1\nEnvironment=SYNFULL_BIND_PORT=${process.env.SYNFULL_BIND_PORT || '8000'}\nEnvironment=SYNFULL_STATE_DIR=${escaped(STATE_DIR)}\nEnvironment=SYNFULL_BOOTSTRAP_DEFAULT_ADMIN=1\nEnvironment=PYTHONPATH=${escaped(path.join(APP_DIR, 'backend'))}\nExecStart=${escaped(RUNTIME)} -m uvicorn app.main:app --app-dir ${escaped(path.join(APP_DIR, 'backend'))} --host 127.0.0.1 --port ${process.env.SYNFULL_BIND_PORT || '8000'}\nRestart=always\nRestartSec=3\n\n[Install]\nWantedBy=multi-user.target\n`
+    const unit = `[Unit]\nDescription=Synfull host monitoring\nAfter=network.target\n\n[Service]\nType=simple\nUser=${serviceUser}\nWorkingDirectory=${escaped(APP_DIR)}\nEnvironment=SYNFULL_BIND_HOST=${bindHost}\nEnvironment=SYNFULL_BIND_PORT=${port}\nEnvironment=SYNFULL_STATE_DIR=${escaped(STATE_DIR)}\nEnvironment=SYNFULL_BOOTSTRAP_DEFAULT_ADMIN=1\nEnvironment=PYTHONPATH=${escaped(path.join(APP_DIR, 'backend'))}\nExecStart=${escaped(RUNTIME)} -m uvicorn app.main:app --app-dir ${escaped(path.join(APP_DIR, 'backend'))} --host ${bindHost} --port ${port}\nRestart=always\nRestartSec=3\n\n[Install]\nWantedBy=multi-user.target\n`
     const unitPath = '/etc/systemd/system/synfull-npm.service'
     fs.writeFileSync(unitPath, unit, { mode: 0o644 })
     try { run('systemctl', ['daemon-reload']); run('systemctl', ['enable', '--now', 'synfull-npm.service']) }
     catch (error) { fs.rmSync(unitPath, { force: true }); throw error }
-    console.log('Synfull is installed as a systemd service and starts at boot. It listens only on 127.0.0.1.')
+    console.log(`Synfull is installed as a systemd service and starts at boot. Bind address: ${bindHost}.`)
   }
+  if (bindHost === '0.0.0.0') console.log('Allow access only from trusted LAN devices, configure your firewall, and change the initial admin password locally before remote sign-in.')
 }
 function uninstallStartup() {
   if (WINDOWS) run('schtasks.exe', ['/Delete', '/TN', 'Synfull', '/F'])
@@ -178,29 +230,27 @@ function uninstallStartup() {
   console.log('Synfull startup registration removed; application data was retained.')
 }
 function help() {
-  console.log(`Synfull ${VERSION}\n\nUsage: synfull <command>\n\nCommands:\n  setup             Prepare local runtime and install Python dependencies\n  start             Start Synfull in the background\n  run               Run Synfull in the foreground (for service managers)\n  stop              Stop a background Synfull process\n  status            Show status and local URLs\n  open              Open the local dashboard\n  install-service   Register start-at-login (Windows) or start-at-boot (Linux)\n  uninstall-service Remove startup registration without deleting data\n\nSynfull binds to localhost only by default. Override data/port with SYNFULL_STATE_DIR, SYNFULL_HOME, and SYNFULL_BIND_PORT.`)
+  console.log(`Synfull ${VERSION}\n\nUsage: synfull <command>\n\nCommands:\n  setup             Prepare local runtime and install Python dependencies\n  start             Start Synfull in the background\n  run               Run Synfull in the foreground (for service managers)\n  stop              Stop a background Synfull process\n  status            Show status and local URLs\n  open              Open the local dashboard\n  install-service   Register start-at-login (Windows) or start-at-boot (Linux)\n  uninstall-service Remove startup registration without deleting data\n\nSetup asks whether to allow LAN connections; localhost-only is the default. Use a trusted LAN, open the port in your firewall only as needed, and change the initial admin password locally before remote sign-in.`)
 }
-function main() {
+async function main() {
   const command = process.argv[2]
   if (command === '--version' || command === '-v') { console.log(VERSION); return }
   if (command === '--help' || command === '-h') { help(); return }
   if (!['win32', 'linux'].includes(process.platform)) throw new Error('Synfull npm CLI currently supports Windows and Linux.')
-  if (command === 'setup') { ensureRuntime(); console.log(`Runtime ready. Data directory: ${STATE_DIR}`) }
+  if (command === 'setup') { await configureBindHost(); ensureRuntime(); console.log(`Runtime ready. Data directory: ${STATE_DIR}`) }
   else if (command === 'start') startServer(false)
   else if (command === 'run') startServer(true)
   else if (command === 'stop') stopServer()
   else if (command === 'status') status()
   else if (command === 'open') {
-    const url = `http://127.0.0.1:${process.env.SYNFULL_BIND_PORT || '8000'}`
+    const host = selectedBindHost()
+    const url = `http://${host === '0.0.0.0' ? '127.0.0.1' : host}:${process.env.SYNFULL_BIND_PORT || '8000'}`
     if (WINDOWS) spawn('cmd.exe', ['/c', 'start', '', url], { detached: true, stdio: 'ignore', windowsHide: true }).unref()
-    else spawn(process.platform === 'linux' ? 'xdg-open' : 'open', [url], { detached: true, stdio: 'ignore' }).unref()
+    else spawn('xdg-open', [url], { detached: true, stdio: 'ignore' }).unref()
   }
   else if (command === 'install-service') installStartup()
   else if (command === 'uninstall-service') uninstallStartup()
   else help()
 }
-
-if (require.main === module) {
-  try { main() } catch (error) { console.error(`Synfull: ${error.message}`); process.exitCode = 1 }
-}
-module.exports = { ensureRuntime, serverEnvironment, APP_DIR, STATE_DIR, ROOT }
+if (require.main === module) main().catch(error => { console.error(`Synfull: ${error.message}`); process.exitCode = 1 })
+module.exports = { ensureRuntime, serverEnvironment, configuredBindHost, selectedBindHost, saveBindHost, APP_DIR, STATE_DIR, ROOT }