@floless/app 0.5.1

package/launch.mjs

@@ -0,0 +1,543 @@
+// floless.app launcher — open / stop / restart the local server with one click.
+// Dependency-free (Node built-ins only), Windows-first (the project is Windows).
+//
+//   node launch.mjs open      (default)  start-if-needed, then open the browser
+//   node launch.mjs stop                 kill whatever is serving the port
+//   node launch.mjs restart              stop, then open
+//
+// Health is checked on 127.0.0.1 (Node's resolver doesn't do the browser's
+// *.localhost trick); the BROWSER is pointed at the branded host, which Chrome/
+// Edge/Firefox resolve to 127.0.0.1 with no hosts-file edit.
+import { spawn, execSync, execFileSync } from 'node:child_process';
+import { dirname, join, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { existsSync } from 'node:fs';
+import http from 'node:http';
+import { createInterface } from 'node:readline';
+import { rotateLog, openLogFd } from './log.mjs';
+import { supervisorPidsToKill, teardownDecision, awareIsPresent, RUN_KEY, RUN_VALUE, PROTOCOL_KEY } from './teardown.mjs';
+import { resolveRealInstallExe } from './install-path.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PORT = Number(process.env.PORT ?? 4317);
+const HEALTH_URL = `http://127.0.0.1:${PORT}/api/health`;
+const BROWSER_URL = `http://floless.localhost:${PORT}`;
+const isWin = process.platform === 'win32';
+
+// Write a line, tolerating a dead stdout. The packaged exe is GUI-subsystem (the
+// build flips CUI→GUI so no console window appears at logon — see build/make-sea.mjs);
+// a GUI-subsystem process launched with no redirected stdout has an invalid fd 1, and
+// a raw write there can throw EBADF/EPIPE. The long-lived processes route stdio to the
+// logfile, but the first Scheduled-Task launch does not — so never let a log() write
+// crash the supervisor. (Defensive; matches the "never fail silently, never crash on
+// logging" intent.)
+const log = (m) => { try { process.stdout.write(`floless: ${m}\n`); } catch { /* dead stdout (GUI subsystem, no console) */ } };
+
+// One health probe → resolves true iff the server answers 200 quickly.
+function ping() {
+  return new Promise((resolve) => {
+    const req = http.get(HEALTH_URL, { timeout: 1500 }, (res) => {
+      res.resume();
+      resolve(res.statusCode === 200);
+    });
+    req.on('error', () => resolve(false));
+    req.on('timeout', () => { req.destroy(); resolve(false); });
+  });
+}
+
+// Probe the running server's build version via /api/health (it returns appVersion — the
+// installed build, "so it's scriptable"). Returns null when unreachable, non-JSON, or not
+// a floless server — in which case we never touch it.
+function probeVersion() {
+  return new Promise((resolve) => {
+    const req = http.get(HEALTH_URL, { timeout: 1500 }, (res) => {
+      let body = '';
+      res.on('data', (c) => { body += c; });
+      res.on('end', () => { try { resolve(JSON.parse(body).appVersion || null); } catch { resolve(null); } });
+    });
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+  });
+}
+
+// Compare dotted numeric versions: 1 if a>b, -1 if a<b, 0 if equal.
+export function cmpVersion(a, b) {
+  const pa = String(a ?? '').split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b ?? '').split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+// "Newest wins": take over the port ONLY when a known-older floless.app build is serving it
+// AND we know our own version — never kill an unknown/non-floless server, never downgrade.
+export function shouldTakeOver(runningVersion, selfVersion) {
+  if (!runningVersion || !selfVersion) return false;
+  return cmpVersion(selfVersion, runningVersion) > 0;
+}
+
+// This launcher's own build version (set by runAction from the dispatcher), so cmdOpen can
+// compare against whatever is already serving the port.
+let _selfVersion = null;
+
+async function waitHealthy(timeoutMs = 30000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await ping()) return true;
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  return false;
+}
+
+// Resolve how to start the server from wherever this launcher is installed:
+//   1. Packaged SEA exe  → spawn SELF with --serve (the main.ts dispatcher serves).
+//   2. npm install       → run the prebuilt bundle (dist/floless-server.cjs --serve).
+//   3. Repo dev only     → `npm run start` (= tsx index.ts); npm needs shell:true on
+//      Windows (Node 20+ CVE-2024-27980 hardening). Never used by an install/exe.
+// In every case the server is a detached daemon that outlives this launcher.
+function resolveServerStart() {
+  const packaged = /flolessapp\.exe$/i.test(process.execPath); // SEA exe → process.execPath is FlolessApp.exe
+  if (packaged) return { cmd: process.execPath, args: ['--serve'], shell: false };
+  const bundle = join(__dirname, 'dist', 'floless-server.cjs');
+  if (existsSync(bundle)) return { cmd: process.execPath, args: [bundle, '--serve'], shell: false };
+  return { cmd: 'npm', args: ['run', 'start'], shell: isWin }; // repo dev fallback
+}
+
+function startServerDetached() {
+  const { cmd, args, shell } = resolveServerStart();
+  // Route the detached daemon's stdout+stderr to the rotating logfile (not 'ignore')
+  // so a silent death leaves a trace; the server also appends crash stacks there. If
+  // the log can't be opened, fall back to 'ignore' rather than failing the launch.
+  rotateLog();
+  const fd = openLogFd();
+  const child = spawn(cmd, args, {
+    cwd: __dirname,
+    detached: true,
+    stdio: fd == null ? 'ignore' : ['ignore', fd, fd],
+    windowsHide: true,
+    shell,
+  });
+  child.unref();
+}
+
+function openBrowser(url) {
+  if (isWin) spawn('cmd', ['/c', 'start', '', url], { windowsHide: true, detached: true }).unref();
+  else spawn(process.platform === 'darwin' ? 'open' : 'xdg-open', [url], { detached: true }).unref();
+}
+
+// Kill whatever is LISTENING on PORT (robust: works no matter how the server was
+// started — launcher, `npm run dev`, or a bare `tsx`). Returns true if it killed.
+function stopServer() {
+  if (!isWin) {
+    try { execSync(`bash -lc "fuser -k ${PORT}/tcp"`, { stdio: 'ignore' }); return true; } catch { return false; }
+  }
+  try {
+    const ps =
+      `$p = Get-NetTCPConnection -LocalPort ${PORT} -State Listen -ErrorAction SilentlyContinue ` +
+      `| Select-Object -Expand OwningProcess -Unique; ` +
+      `if ($p) { $p | ForEach-Object { taskkill /PID $_ /T /F } } else { exit 9 }`;
+    execSync(`powershell -NoProfile -Command "${ps}"`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false; // exit 9 → nothing was listening
+  }
+}
+
+// Start the detached server if it isn't already listening; block until healthy.
+// Shared by `open` (which then opens the browser) and `start` (which does not).
+async function ensureServerUp() {
+  if (await ping()) return;
+  log('starting server…');
+  startServerDetached();
+  if (!(await waitHealthy())) {
+    log(`server did not become healthy on ${HEALTH_URL} within 30s — check for errors with "npm run dev"`);
+    process.exit(1);
+  }
+  log('server up');
+}
+
+export async function cmdOpen() {
+  if (await ping()) {
+    // Something is already serving the port. If it's a DIFFERENT, OLDER floless.app build than
+    // this one, take it over ("newest wins") so the version the user just launched is the one
+    // they get — instead of silently opening the stale instance (e.g. a leftover dev server).
+    const running = await probeVersion();
+    if (shouldTakeOver(running, _selfVersion)) {
+      log(`floless.app v${running} is already running on ${PORT}; this build is v${_selfVersion} — taking over`);
+      stopServer();
+      await new Promise((r) => setTimeout(r, 500)); // let the OS release the port
+      await ensureServerUp();
+    } else {
+      log(`already running${running ? ` (v${running})` : ''} — opening browser`);
+    }
+  } else {
+    await ensureServerUp();
+  }
+  log(`opening ${BROWSER_URL}`);
+  openBrowser(BROWSER_URL);
+}
+
+// `start` (the in-tab recovery trigger, fired as floless://start from a tab whose
+// server died): start-if-needed but NEVER open a browser — the tab that fired this
+// is already open and heals itself via its 5s health poll. This is the headless
+// counterpart to `open`, and the action autostart-on-login uses too.
+export async function cmdStart() {
+  if (await ping()) { log('already running'); return; }
+  await ensureServerUp();
+}
+
+// `supervise` — the login-autostart entry: KEEP the local server alive. Starts it if
+// down, then polls every few seconds and respawns it within ~5s whenever it dies.
+// This is the ROBUST recovery path: pure local process management — no browser, no
+// floless:// protocol, no admin. (The in-tab Restart button depends on the browser
+// honoring the floless:// handler, which locked-down / corporate-managed browsers can
+// silently refuse; the supervisor does not depend on the browser at all.) An open tab
+// heals its own UI via the 5s health poll once the server is back. Never returns —
+// this process lives for the whole login session.
+const SUPERVISE_POLL_MS = 3000;
+// Env-flag self-respawn sentinel. The packaged exe is GUI-subsystem (build/make-sea.mjs
+// flips CUI→GUI), so no console window ever appears — but we still re-spawn the
+// watchdog DETACHED, then exit: that lets the launching process (the logon Scheduled
+// Task) COMPLETE immediately (task returns to "Ready" instead of showing "Running" for
+// the whole session) while the detached child (FLOLESS_SUPERVISE_RESPAWNED=1) carries
+// the actual watchdog loop, decoupled from the task's lifetime. Set internally; do NOT
+// set it from outside (a user-set value would short-circuit the detach step).
+const SUPERVISE_RESPAWN_ENV = 'FLOLESS_SUPERVISE_RESPAWNED';
+
+export async function cmdSupervise() {
+  // Only the packaged SEA exe (autostart-wired by the Velopack hook) takes the
+  // detached-respawn path — its argv is `<exe> --supervise`, which the dispatcher in
+  // main.ts handles. The npm channel has process.execPath = node.exe and respawning
+  // `node --supervise` would fail with `bad option: --supervise`; autostart is also
+  // never wired in that channel, so a foreground loop with visible logs is the right
+  // dev behavior. Detect the SEA channel by the exe basename (`FlolessApp.exe`).
+  const isSeaChannel = /flolessapp\.exe$/i.test(process.execPath);
+  if (isSeaChannel && !process.env[SUPERVISE_RESPAWN_ENV]) {
+    // First entry on the packaged SEA: re-spawn ourselves detached, then exit, so the
+    // logon Scheduled Task that launched us COMPLETES immediately (returns to "Ready")
+    // while the detached child carries the watchdog loop for the session. The exe is
+    // GUI-subsystem (no console window at all — build/make-sea.mjs), so this is purely
+    // about decoupling from the task's lifetime, not console-hiding. Stdout/stderr
+    // route to the rotating logfile so a supervisor crash leaves a trail — `stdio:
+    // 'ignore'` would silently swallow every log() line + any uncaught crash (dual-
+    // review finding #1, 2026-05-30). If the logfile can't be opened we fall back to
+    // 'ignore' rather than failing the respawn.
+    rotateLog();
+    const fd = openLogFd();
+    const child = spawn(process.execPath, ['--supervise'], {
+      detached: true,
+      stdio: fd == null ? 'ignore' : ['ignore', fd, fd],
+      windowsHide: true,
+      env: { ...process.env, [SUPERVISE_RESPAWN_ENV]: '1' },
+    });
+    child.unref();
+    log('supervisor re-spawned detached');
+    return;
+  }
+  log('supervisor up — keeping the server alive');
+  for (;;) {
+    if (!(await ping())) {
+      log('server not responding — (re)starting');
+      // Spawn + BLOCK on waitHealthy (≤30s) before the next iteration: this serializes
+      // the loop so one outage = one spawn (no self-race), and a persistently-failing
+      // server retries on a ~33s cadence rather than churning. We deliberately do NOT
+      // route through ensureServerUp() — it process.exit(1)s on failure, which would
+      // kill the supervisor itself. If a spawn ever races another launcher (e.g. a
+      // manual floless://start), the loser's app.listen() throws EADDRINUSE and that
+      // process exits cleanly — never two live servers.
+      startServerDetached();
+      log((await waitHealthy()) ? 'server up' : 'server not healthy yet — will retry');
+    }
+    await new Promise((r) => setTimeout(r, SUPERVISE_POLL_MS));
+  }
+}
+
+export async function cmdStop() {
+  // Decide "is it running?" from the port itself (Get-NetTCPConnection / fuser),
+  // NOT an HTTP ping: a transient 1.5s health-timeout used to make stop a no-op
+  // while the server was up. stopServer() is idempotent and returns false only
+  // when nothing was actually listening (Windows exit 9 / fuser no-match).
+  if (!stopServer()) { log('not running — nothing to stop'); return; }
+  log(`stopping server on port ${PORT}…`);
+  // Confirm the port is freed (taskkill /T /F is synchronous; give the OS a moment).
+  for (let i = 0; i < 10; i++) {
+    if (!(await ping())) { log('stopped'); return; }
+    await new Promise((r) => setTimeout(r, 300));
+  }
+  log('warning: a process may still be holding the port');
+}
+
+// --- teardown (the engine behind `uninstall`) --------------------------------------
+//
+// Parse the uninstall flag tail (argv.slice(3)) into the two booleans teardownDecision
+// understands. Pure + exported so the CLI shim and main.ts share one parser and it can
+// be unit-tested without side effects. Unknown tokens are ignored (lenient).
+export function parseTeardownFlags(argv = []) {
+  return {
+    purge: argv.includes('--purge'),
+    keepAware: argv.includes('--keep-aware'),
+  };
+}
+
+// Parse `Get-CimInstance Win32_Process` JSON (ProcessId + CommandLine) into the
+// {pid, cmd} shape supervisorPidsToKill expects. Pure + exported for unit tests.
+// PowerShell emits a single object (not an array) when exactly one process matches,
+// and CommandLine can be null for processes we can't read — both are tolerated.
+export function parseProcessList(json) {
+  let parsed;
+  try { parsed = JSON.parse(json || '[]'); } catch { return []; }
+  const arr = Array.isArray(parsed) ? parsed : [parsed];
+  return arr
+    .filter((p) => p && p.ProcessId != null)
+    .map((p) => ({ pid: Number(p.ProcessId), cmd: String(p.CommandLine ?? '') }));
+}
+
+// Enumerate running processes as [{pid, cmd}]. Win32-only (uses Win32_Process);
+// returns [] elsewhere or on any failure (best-effort — teardown must never throw).
+function enumerateProcesses() {
+  if (!isWin) return [];
+  try {
+    const ps =
+      'Get-CimInstance Win32_Process | Select-Object ProcessId,CommandLine | ConvertTo-Json -Compress';
+    const out = execSync(`powershell -NoProfile -Command "${ps}"`, {
+      encoding: 'utf8',
+      windowsHide: true,
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    return parseProcessList(out);
+  } catch {
+    return [];
+  }
+}
+
+// Kill the --supervise watchdog FIRST (Codex B1) so it can't respawn the server in
+// the gap before stopServer(). Matches THIS app's exe + the supervise action, never
+// process.pid (self-kill guard lives in supervisorPidsToKill). Idempotent; win32-only.
+//
+// SAFETY (review #1): in the npm channel process.execPath is the GENERIC node.exe, so
+// matching on it alone could kill ANY `node … supervise` process (e.g. a third-party
+// watchdog). When we detect that channel, also require the launcher script (this
+// launch.mjs) in the command line — our supervisor runs `node … launch.mjs supervise`.
+// The packaged exe (unique FlolessApp.exe) passes no scriptMatch — its match is exact.
+function killSupervisor() {
+  if (!isWin) return;
+  const isNpmChannel = /^node(\.exe)?$/i.test(basename(process.execPath));
+  const scriptMatch = isNpmChannel ? basename(fileURLToPath(import.meta.url)) : undefined; // 'launch.mjs'
+  // MSIX-container case: the uninstaller running INSIDE the container sees its own
+  // process.execPath as the bind-link VIRTUAL path, but a supervisor we launched at
+  // logon (via a Run key registered with the un-virtualized REAL path) shows the
+  // REAL path in its command line. supervisorPidsToKill accepts an array of needles
+  // and matches if cmd contains ANY of them — pass both so the kill works whether
+  // the supervisor was launched at the virtual or real path. (For non-container
+  // installs the two paths are identical → unchanged behavior.)
+  const realExe = resolveRealInstallExe(process.execPath);
+  const exeMatch = realExe === process.execPath ? process.execPath : [process.execPath, realExe];
+  const pids = supervisorPidsToKill(enumerateProcesses(), process.pid, exeMatch, scriptMatch);
+  for (const pid of pids) {
+    log(`stopping supervisor (pid ${pid})…`);
+    // execFileSync (no shell) with an argv array — pid is already Number()-coerced in
+    // parseProcessList, and avoiding the shell rules out any injection entirely.
+    try { execFileSync('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true }); } catch { /* already gone */ }
+  }
+}
+
+// cmdTeardown — stop floless.app's live footprint in the ONLY safe order (Codex B1/B2/S2):
+//   1. kill the --supervise watchdog (else it respawns the server mid-teardown),
+//   2. stop the server on the port,
+//   3. a bounded (~3s) re-check over the FULL window: a slow-binding respawn or a
+//      freshly-spawned supervisor can appear at any tick within the supervisor's ~5s
+//      respawn cadence. So we poll the WHOLE window (never break early on a single
+//      miss — review B1/#2): on any tick the port answers, re-kill the supervisor
+//      (it may be the one that just respawned the server) THEN stop the server again.
+// Each step is idempotent + best-effort; cmdStop() is left untouched (the update flow
+// at main.ts depends on its port-only behavior).
+export async function cmdTeardown() {
+  killSupervisor();
+  stopServer();
+  // Bounded respawn-catch: poll the port for the full ~3s window. Do NOT break on a
+  // miss — a respawn may bind a few hundred ms after a transient gap, and a fresh
+  // supervisor may re-appear; only the deadline ends the loop.
+  const deadline = Date.now() + 3000;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 300));
+    if (await ping()) {
+      log('server respawned after kill — re-killing supervisor and stopping again');
+      killSupervisor(); // re-kill: a freshly-spawned watchdog is what brought it back
+      stopServer();
+    }
+  }
+  // After the window, if the port is STILL answering something is holding it (a
+  // respawn we couldn't outrun) — surface it instead of an unconditional success
+  // line (review #3). Otherwise report the clean stop.
+  if (await ping()) log('warning: a process may still be holding the port');
+  else log('server and supervisor stopped');
+}
+
+export async function cmdRestart() {
+  await cmdStop();
+  await new Promise((r) => setTimeout(r, 500));
+  await cmdOpen();
+}
+
+// Read a JSON API endpoint on the local server.
+function apiJson(path, method = 'GET') {
+  return new Promise((resolve, reject) => {
+    const req = http.request(`http://127.0.0.1:${PORT}${path}`, { method, timeout: 5000 }, (res) => {
+      let body = '';
+      res.on('data', (c) => (body += c));
+      res.on('end', () => { try { resolve(JSON.parse(body || '{}')); } catch { resolve({}); } });
+    });
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(); reject(new Error('timeout')); });
+    req.end();
+  });
+}
+
+// `floless login` — sign in to floless.io so the subscription gate opens. The
+// server owns the licensing (licensing.ts); the launcher just starts it if needed,
+// triggers the browser handoff, and polls the gate state until it goes valid.
+export async function cmdLogin() {
+  if (!(await ping())) {
+    log('starting server…');
+    startServerDetached();
+    if (!(await waitHealthy())) { log('server did not start — try "npm run dev" to see errors'); process.exit(1); }
+  }
+  const started = await apiJson('/api/license/start', 'POST').catch(() => ({}));
+  log(`opening sign-in in your browser${started.signInUrl ? `: ${started.signInUrl}` : ''}`);
+  log('waiting for sign-in to complete…');
+  const deadline = Date.now() + 185000;
+  while (Date.now() < deadline) {
+    const s = await apiJson('/api/license/status').catch(() => ({}));
+    if (s.state === 'valid' || s.state === 'offline-grace') { log('signed in — subscription active'); return; }
+    if (s.state === 'expired') { log(`signed in, but the subscription is expired — subscribe at ${s.signInUrl ?? 'floless.io'}`); return; }
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+  log('sign-in timed out — run "floless login" again to retry');
+}
+
+// Map a bare action ("open"/"stop"/"restart") OR a floless:// URI (how the Windows
+// protocol handler invokes us, e.g. floless://open) to an action name. For a URI
+// the action is the host part: floless://restart → "restart"; floless:// → open.
+export function parseAction(arg) {
+  let cmd = (arg || 'open').toLowerCase();
+  if (cmd.startsWith('floless:')) {
+    try { cmd = (new URL(arg).hostname || 'open').toLowerCase(); } catch { cmd = 'open'; }
+  }
+  return cmd;
+}
+
+// `floless update` via the npm bin lands here (bin/floless.mjs → launch.mjs).
+// The npm install has no Velopack package to self-update — npm owns versions — so
+// this is a deliberate no-op with the right instruction. The packaged exe never
+// reaches this: main.ts handles `update` before delegating to runAction.
+async function cmdUpdate() {
+  log('this is the npm build — update it with "npm i -g @floless/app"');
+  log('(the installer build self-updates via "floless-app update")');
+}
+
+// Remove the autostart Run value + the floless:// scheme key. Idempotent + win32-only
+// (reg.exe). Uses the SAME key strings autostart.ts/protocol.ts add (via teardown.mjs)
+// so install and uninstall can't drift. Each delete is best-effort: an absent key is
+// the success case (nothing to remove), so a non-zero exit is swallowed.
+function removeRegistryFootprint() {
+  if (!isWin) return;
+  try { execFileSync('reg', ['delete', RUN_KEY, '/v', RUN_VALUE, '/f'], { stdio: 'ignore', windowsHide: true }); } catch { /* value absent */ }
+  try { execFileSync('reg', ['delete', PROTOCOL_KEY, '/f'], { stdio: 'ignore', windowsHide: true }); } catch { /* key absent */ }
+}
+
+// Ask a yes/no question on the TTY; default NO on empty input (the [y/N] convention).
+// Only the caller's `decision.prompt` (which is already TTY-gated) reaches this.
+function promptYesNo(question) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(`${question} `, (answer) => {
+      rl.close();
+      resolve(/^y(es)?$/i.test((answer ?? '').trim()));
+    });
+  });
+}
+
+// `floless-app uninstall [--purge|--keep-aware]` — the npm channel. Tears down
+// floless.app's own footprint (server + supervisor + autostart key + floless://),
+// then per the decision removes the auto-installed AWARE runtime, and finally prints
+// the one command that removes the app package itself (a running process can't npm
+// rm -g itself cleanly mid-run). main.ts handles the exe channel + Velopack hook.
+export async function cmdUninstall(flags = {}) {
+  // teardownDecision throws on conflicting --purge + --keep-aware — let it surface as
+  // a clean error (the CLI shim's catch logs it and exits 1) rather than guessing.
+  const decision = teardownDecision({ ...flags, isTTY: process.stdin.isTTY });
+
+  log('stopping the server and supervisor…');
+  await cmdTeardown();
+
+  log('removing the autostart entry and floless:// scheme…');
+  removeRegistryFootprint();
+
+  let removeAware = decision.removeAware;
+  if (decision.prompt) {
+    removeAware = await promptYesNo('Also remove the AWARE runtime (@aware-aeco/cli)? [y/N]');
+  }
+
+  if (removeAware) {
+    log('removing the AWARE runtime — this will affect ANY other tool that uses @aware-aeco/cli.');
+    try {
+      execSync('npm uninstall -g @aware-aeco/cli', { stdio: 'inherit', shell: isWin });
+    } catch {
+      log('warning: "npm uninstall -g @aware-aeco/cli" failed — see the output above.');
+    }
+    // S4: a clean uninstall exit does NOT prove removal — verify by parsing
+    // `npm ls … --json`'s `dependencies` key (awareIsPresent), matching the
+    // exe channel's path in main.ts:removeAwarePerDecision (single source: both
+    // channels share the same JSON-verify, never diverge on exit-code semantics
+    // that vary across npm versions for a missing global). npm ls exits non-zero
+    // when the package is absent, so capture stdout from BOTH the success path
+    // and the thrown error; an unreadable result is treated as removed (defensive).
+    let lsJson = '';
+    try {
+      lsJson = execSync('npm ls -g @aware-aeco/cli --depth=0 --json', {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        shell: isWin,
+      });
+    } catch (err) {
+      lsJson = String(err?.stdout ?? '');
+    }
+    const stillPresent = awareIsPresent(lsJson);
+    if (stillPresent) {
+      log('AWARE may still be installed — remove it manually with: npm uninstall -g @aware-aeco/cli');
+      log('(if that fails with a permission error, retry in an elevated shell).');
+    } else {
+      log('AWARE runtime removed.');
+    }
+  } else {
+    log('keeping the AWARE runtime (@aware-aeco/cli). Remove it later with: npm uninstall -g @aware-aeco/cli');
+  }
+
+  log('done. Finally, remove floless.app itself with: npm uninstall -g @floless/app');
+}
+
+const ACTIONS = { open: cmdOpen, start: cmdStart, supervise: cmdSupervise, stop: cmdStop, restart: cmdRestart, login: cmdLogin, update: cmdUpdate, uninstall: cmdUninstall };
+
+// Run one launcher action by name/URI. Shared by the npm bin (CLI shim below) and
+// the packaged exe dispatcher (main.ts), so both surfaces behave identically. The
+// flag tail (argv.slice(3)) is parsed once here and passed to the action; every
+// existing action takes no params and simply ignores it (only `uninstall` reads it).
+export async function runAction(arg, flagArgv = [], selfVersion = null) {
+  _selfVersion = selfVersion;
+  const cmd = parseAction(arg);
+  const action = ACTIONS[cmd];
+  if (!action) { log(`unknown command "${cmd}" — use: open | start | supervise | stop | restart | login | update | uninstall`); process.exit(2); }
+  await action(parseTeardownFlags(flagArgv));
+}
+
+// CLI shim: run only when this file is the actual entry (`node launch.mjs <arg>`),
+// NOT when bundled into / imported by the dispatcher (main.ts). We key off the
+// entry's basename rather than import.meta.url: esbuild collapses every module's
+// import.meta.url to the bundle file, so a URL compare would wrongly fire inside
+// the bundle. The bundle/exe entry is never named "launch.mjs".
+const entry = basename(process.argv[1] ?? '').toLowerCase();
+if (entry === 'launch.mjs') {
+  runAction(process.argv[2], process.argv.slice(3)).catch((e) => { log(`error: ${e?.message ?? e}`); process.exit(1); });
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@floless/app",
+  "version": "0.5.1",
+  "type": "module",
+  "description": "Thin localhost host for floless.app — serves web/ and shells the aware CLI. No engine, no LLM.",
+  "bin": {
+    "floless-app": "bin/floless.mjs"
+  },
+  "files": [
+    "bin/",
+    "launch.mjs",
+    "teardown.mjs",
+    "dist/",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "dev": "tsx watch main.ts --serve",
+    "start": "tsx main.ts --serve",
+    "app": "node launch.mjs open",
+    "app:stop": "node launch.mjs stop",
+    "app:restart": "node launch.mjs restart",
+    "build": "node build/bundle.mjs",
+    "build:exe": "node build/bundle.mjs && node build/make-sea.mjs",
+    "typecheck": "tsc --noEmit",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@fastify/static": "^8.0.0",
+    "@types/node": "^22.0.0",
+    "chokidar": "^4.0.0",
+    "esbuild": "^0.28.0",
+    "fastify": "^5.0.0",
+    "pino-pretty": "^13.0.0",
+    "postject": "^1.0.0-alpha.6",
+    "rcedit": "^5.0.2",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "yaml": "^2.9.0"
+  }
+}