localhostly 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Iuri Bertto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# localhostly
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Expose any local port on a public HTTPS URL — behind NAT, without opening ports.
+
+```sh
+npm i -g localhostly
+localhostly login <token>
+localhostly 3000
+# → https://brave-amber-otter.localhostly.iblabs.io  →  http://127.0.0.1:3000
+```
+
+Requires Node.js 24 or newer. Works on Linux, macOS and Windows.
+
+## Get a token
+
+Create a free account with your e-mail (no confirmation needed):
+
+```sh
+curl -X POST -d '{"email":"you@example.com"}' https://localhostly.iblabs.io/api/signup
+# {"token":"lh_..."}
+```
+
+Then save it on this computer (once):
+
+```sh
+localhostly login lh_...
+```
+
+The token is kept in `~/.localhostly/config.json`, readable only by you (`$LOCALHOSTLY_HOME` moves the folder).
+
+## Run
+
+```sh
+localhostly 3000                        # expose http://127.0.0.1:3000
+localhostly http 3000 --password        # visitors must type a password (a random one is shown)
+localhostly http 3000 --password s3cret # ...or your own
+localhostly http 8080 --host myapp.test # forward to another local address; the app receives it as Host
+```
+
+The terminal shows the public URL and every request live. HTTP, streaming responses and WebSockets all go through.
+Stop with Ctrl+C.
+
+The first time a browser opens your URL it sees a short warning page (it protects against phishing); API clients,
+webhooks and `curl` never see it, and a browser can skip it by sending the header `X-Localhostly-Skip-Warning`.
+
+## Keep it always on
+
+```sh
+localhostly service install 3000   # a system service: starts with the computer, reconnects, keeps the same name
+localhostly service status
+localhostly service uninstall
+```
+
+It uses systemd (user service) on Linux, launchd on macOS and a Windows service on Windows. Install the command
+with `npm i -g` first — a copy run by `npx` lives in a temporary folder.
+
+## Free plan limits
+
+2 tunnels at a time, 150 requests per minute and 25 GiB per month per account.
+
+## All options
+
+```sh
+localhostly --help
+localhostly --version
+```
+
+## Links
+
+- Website: https://localhostly.iblabs.io
+
+## License
+
+MIT

package/agente/cli.js

@@ -0,0 +1,349 @@
+// A linha de comando: `localhostly <porta>`, `localhostly http <porta>`, `localhostly login <token>` e
+// `localhostly service install|status|uninstall`.
+import { randomInt } from 'node:crypto';
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import * as servico from './servico/index.js';
+import { criarLog, criarTela } from './tela.js';
+import { SERVIDOR_PADRAO, Tunel } from './tunel.js';
+
+const VERSAO = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+const AJUDA = `localhostly ${VERSAO} — expose a local port on a public HTTPS URL
+
+Usage:
+  localhostly <port>                 expose http://127.0.0.1:<port>
+  localhostly http <port> [options]  the same, with options
+  localhostly login <token>          save your token on this computer
+
+  localhostly service install <port> [options]
+                                     keep the tunnel always on as a system service (systemd on Linux,
+                                     launchd on macOS, a Windows service): starts with the computer,
+                                     reconnects by itself and keeps the same name
+  localhostly service status         is the service running, and its URL
+  localhostly service uninstall      stop and remove the service
+
+Options:
+  --host <host[:port]>    local address to forward to; the app also receives it as Host
+  --server <url>          tunnel server (default ${SERVIDOR_PADRAO}, or $LOCALHOSTLY_SERVER)
+  --password [value]      ask visitors for a password (the browser shows a login box; any user name);
+                          without a value, a random one is created and shown here
+  --password-file <file>  the same, with the password read from a file
+  --service               service mode: one log line per event, no live table, never gives up
+  --home <dir>            where the token and the service state live (default ~/.localhostly,
+                          or $LOCALHOSTLY_HOME)
+  -h, --help              show this help
+  -v, --version           show the version
+`;
+
+export function pastaConfig(env = process.env) {
+  return env.LOCALHOSTLY_HOME || join(homedir(), '.localhostly');
+}
+
+const COMANDOS = ['http', 'login', 'service'];
+
+export function lerConfig(env = process.env) {
+  try {
+    return JSON.parse(readFileSync(join(pastaConfig(env), 'config.json'), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+export function gravarToken(token, env = process.env) {
+  const pasta = pastaConfig(env);
+  mkdirSync(pasta, { recursive: true, mode: 0o700 });
+  const arquivo = join(pasta, 'config.json');
+  const config = { ...lerConfig(env), token };
+  writeFileSync(arquivo, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(arquivo, 0o600);
+  return arquivo;
+}
+
+// Sem caracteres que se confundem (0/O, 1/l/I).
+const ALFABETO_SENHA = 'abcdefghijkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+
+export function gerarSenha(tamanho = 12) {
+  let senha = '';
+  for (let i = 0; i < tamanho; i++) senha += ALFABETO_SENHA[randomInt(ALFABETO_SENHA.length)];
+  return senha;
+}
+
+function erroDeUso(mensagem) {
+  const erro = new Error(mensagem);
+  erro.uso = true;
+  return erro;
+}
+
+function porta(texto) {
+  const n = Number(texto);
+  if (!/^\d+$/.test(String(texto)) || n < 1 || n > 65535) throw erroDeUso(`invalid port: ${texto}`);
+  return n;
+}
+
+// "--host 127.0.0.1:4777", "--host app.test", "--host [::1]:3000"
+export function lerAlvo(texto, portaPadrao) {
+  const m = /^\[([^\]]+)\](?::(\d+))?$/.exec(texto) ?? /^([^:]+)(?::(\d+))?$/.exec(texto);
+  if (!m) throw erroDeUso(`invalid --host: ${texto}`);
+  return { host: m[1], porta: m[2] ? porta(m[2]) : portaPadrao };
+}
+
+export function lerArgumentos(argv) {
+  const opcoes = {
+    comando: null,
+    posicionais: [],
+    host: null,
+    servidor: null,
+    senha: false,
+    arquivoSenha: null,
+    servico: false,
+    home: null,
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const [chave, embutido] = a.startsWith('--') && a.includes('=') ? [a.slice(0, a.indexOf('=')), a.slice(a.indexOf('=') + 1)] : [a, undefined];
+    const valorDe = () => {
+      if (embutido !== undefined) return embutido;
+      if (i + 1 >= argv.length) throw erroDeUso(`${chave} needs a value`);
+      return argv[++i];
+    };
+    // "--password" sozinho (true) ou com valor: "--password=x", ou "--password x" quando x não é opção
+    // nem a porta que ainda falta ("localhostly --password 4777" é a porta).
+    const valorDaSenha = () => {
+      if (embutido !== undefined) {
+        if (!embutido) throw erroDeUso('--password= needs a value');
+        return embutido;
+      }
+      const proximo = argv[i + 1];
+      if (proximo === undefined || proximo.startsWith('-')) return true;
+      const semPorta = !opcoes.posicionais.some((p) => /^\d+$/.test(p));
+      if (semPorta && /^\d+$/.test(proximo)) return true;
+      i++;
+      return proximo;
+    };
+    if (chave === '-h' || chave === '--help') opcoes.comando = 'ajuda';
+    else if (chave === '-v' || chave === '--version') opcoes.comando ??= 'versao';
+    else if (chave === '--host') opcoes.host = valorDe();
+    else if (chave === '--server') opcoes.servidor = valorDe();
+    else if (chave === '--password') opcoes.senha = valorDaSenha();
+    else if (chave === '--password-file') opcoes.arquivoSenha = valorDe();
+    else if (chave === '--service') opcoes.servico = true;
+    else if (chave === '--home') opcoes.home = valorDe();
+    else if (chave.startsWith('-')) throw erroDeUso(`unknown option: ${chave}`);
+    else opcoes.posicionais.push(a);
+  }
+  if (!opcoes.comando) {
+    const [primeiro] = opcoes.posicionais;
+    if (COMANDOS.includes(primeiro)) opcoes.comando = opcoes.posicionais.shift();
+    else if (primeiro === undefined) opcoes.comando = 'ajuda';
+    else opcoes.comando = 'http';
+  }
+  return opcoes;
+}
+
+function lerArquivoSenha(arquivo) {
+  let texto;
+  try {
+    texto = readFileSync(arquivo, 'utf8');
+  } catch (erro) {
+    throw erroDeUso(`cannot read --password-file ${arquivo}: ${erro.code ?? erro.message}`);
+  }
+  const senha = texto.replace(/\r?\n$/, '');
+  if (!senha) throw erroDeUso(`--password-file ${arquivo} is empty`);
+  return senha;
+}
+
+// A senha pedida: { senha (o texto ou null), gerada (só a tela mostra a gerada) }.
+function senhaDe(opcoes) {
+  if (opcoes.arquivoSenha && opcoes.senha) throw erroDeUso('use --password or --password-file, not both');
+  if (opcoes.arquivoSenha) return { senha: lerArquivoSenha(opcoes.arquivoSenha), gerada: false };
+  if (opcoes.senha === true) return { senha: gerarSenha(), gerada: true };
+  return { senha: opcoes.senha || null, gerada: false };
+}
+
+function alvoDe(opcoes, uso) {
+  if (opcoes.posicionais.length !== 1) throw erroDeUso(uso);
+  const p = porta(opcoes.posicionais[0]);
+  return { porta: p, alvo: opcoes.host ? lerAlvo(opcoes.host, p) : { host: '127.0.0.1', porta: p } };
+}
+
+const USO_SERVICO =
+  'usage: localhostly service install <port> [--host h[:p]] [--password [value]] [--server url]\n' +
+  '       localhostly service status\n' +
+  '       localhostly service uninstall';
+
+// `localhostly service ...`. rc: 0 ok (status: rodando), 1 falha (status: instalado e parado), 2 uso, 3 não instalado.
+export async function comandoServico(
+  opcoes,
+  { env = process.env, saida = process.stdout, erros = process.stderr, api = servico, plataforma = process.platform, esperarUrlMs = 15_000 } = {},
+) {
+  const [sub, ...resto] = opcoes.posicionais;
+  const home = resolve(pastaConfig(env));
+  const nome = api.nomeDoSistema(plataforma);
+  try {
+    if (sub === 'install') {
+      let porta;
+      let senha;
+      let gerada;
+      try {
+        ({ porta } = alvoDe({ ...opcoes, posicionais: resto }, USO_SERVICO));
+        if (opcoes.host) lerAlvo(opcoes.host, porta);
+        ({ senha, gerada } = senhaDe(opcoes));
+      } catch (erro) {
+        if (!erro.uso) throw erro;
+        erros.write(`${erro.message}\n`);
+        return 2;
+      }
+      const config = lerConfig(env);
+      if (!config.token) {
+        erros.write(
+          'no token saved: create an account at https://localhostly.iblabs.io and run `localhostly login <token>` first\n',
+        );
+        return 1;
+      }
+      const servidor = opcoes.servidor || env.LOCALHOSTLY_SERVER || config.server || null;
+      const antes = Date.now();
+      const r = api.instalar({ porta, host: opcoes.host, servidor, senha, home }, { plataforma, env });
+      saida.write(`Installed the localhostly ${nome}: ${r.arquivo}\n`);
+      saida.write('It starts with the computer, reconnects by itself and keeps the same name.\n');
+      if (gerada) saida.write(`Password: ${senha} (any user name)\n`);
+      else if (senha) saida.write('Password protected (any user name).\n');
+      const fim = Date.now() + esperarUrlMs;
+      let tunel = null;
+      while (Date.now() < fim) {
+        const e = api.lerEstado(home);
+        if (e?.url && Date.parse(e.em) >= antes - 1000) {
+          tunel = e;
+          break;
+        }
+        await new Promise((ok) => setTimeout(ok, 200));
+      }
+      saida.write(tunel ? `URL: ${tunel.url}\n` : 'Run `localhostly service status` in a moment to see the URL.\n');
+      saida.write(`Logs: ${r.log}\n`);
+      for (const aviso of r.avisos ?? []) saida.write(`\n${aviso}\n`);
+      return 0;
+    }
+    if (sub === 'status' && resto.length === 0) {
+      const r = api.status({ plataforma, env, home });
+      if (!r.instalado) {
+        saida.write('The localhostly service is not installed. Install it with `localhostly service install <port>`.\n');
+        return 3;
+      }
+      saida.write(`localhostly ${nome}: ${r.estado}${r.pid ? ` (pid ${r.pid})` : ''}\n`);
+      saida.write(`Starts with the computer: ${r.sobeSozinho ? 'yes' : 'no'}\n`);
+      if (r.tunel?.url) saida.write(`URL: ${r.tunel.url} (since ${r.tunel.em})\n`);
+      if (r.log) saida.write(`Logs: ${r.log}\n`);
+      return r.rodando ? 0 : 1;
+    }
+    if (sub === 'uninstall' && resto.length === 0) {
+      const r = api.remover({ plataforma, env, home });
+      saida.write(r.removido ? `Removed the localhostly ${nome}.\n` : 'The localhostly service was not installed.\n');
+      return 0;
+    }
+  } catch (erro) {
+    if (!(erro instanceof api.ErroServico)) throw erro;
+    erros.write(`${erro.message}\n`);
+    return 1;
+  }
+  erros.write(`${USO_SERVICO}\n`);
+  return 2;
+}
+
+export async function principal(argv = process.argv.slice(2), { env = process.env, saida = process.stdout } = {}) {
+  let opcoes;
+  try {
+    opcoes = lerArgumentos(argv);
+  } catch (erro) {
+    process.stderr.write(`${erro.message}\n\n${AJUDA}`);
+    return 2;
+  }
+  if (opcoes.home) env = { ...env, LOCALHOSTLY_HOME: resolve(opcoes.home) };
+  if (opcoes.comando === 'ajuda') {
+    saida.write(AJUDA);
+    return 0;
+  }
+  if (opcoes.comando === 'versao') {
+    saida.write(`${VERSAO}\n`);
+    return 0;
+  }
+  if (opcoes.comando === 'login') {
+    const [token] = opcoes.posicionais;
+    if (!token) {
+      process.stderr.write('usage: localhostly login <token>\n');
+      return 2;
+    }
+    const arquivo = gravarToken(token, env);
+    saida.write(`Token saved to ${arquivo}\n`);
+    return 0;
+  }
+  if (opcoes.comando === 'service') return comandoServico(opcoes, { env, saida });
+
+  let alvo;
+  let senha;
+  let gerada;
+  try {
+    ({ alvo } = alvoDe(opcoes, 'usage: localhostly [http] <port>'));
+    ({ senha, gerada } = senhaDe(opcoes));
+  } catch (erro) {
+    process.stderr.write(`${erro.message}\n\n${AJUDA}`);
+    return 2;
+  }
+
+  // O modo serviço: uma linha por evento, o último nome guardado e pedido de novo, e nunca desiste.
+  const modoServico = opcoes.servico;
+  const home = resolve(pastaConfig(env));
+  const config = lerConfig(env);
+  const servidor = opcoes.servidor || env.LOCALHOSTLY_SERVER || config.server || SERVIDOR_PADRAO;
+  const tela = modoServico ? criarLog(saida) : criarTela(saida);
+  if (!config.token) {
+    tela.aviso('no token saved: create an account at https://localhostly.iblabs.io and run `localhostly login <token>`');
+  }
+
+  const tunel = new Tunel({
+    servidor,
+    token: config.token ?? null,
+    alvo,
+    hostCabecalho: opcoes.host,
+    senha,
+    sessao: modoServico ? servico.lerEstado(home) : null,
+    insistir: modoServico,
+  });
+  if (modoServico) tela.conectando(servidor);
+  tunel.on('pronto', ({ nome, url, tokenSessao, retomado }) => {
+    if (modoServico && tokenSessao) {
+      try {
+        servico.gravarEstado(home, { nome, tokenSessao, url });
+      } catch (erro) {
+        tela.aviso(`could not save the tunnel state in ${home}: ${erro.code ?? erro.message}`);
+      }
+    }
+    tela.pronto({ url, alvo: tunel.enderecoLocal, senha: senha && (gerada ? senha : true), retomado });
+  });
+  tunel.on('nome_trocado', ({ de, para }) =>
+    tela.aviso(`name changed: ${de} -> ${para} (the old name was released while the tunnel was offline)`),
+  );
+  tunel.on('requisicao', (r) => tela.requisicao(r));
+  tunel.on('caiu', () => tela.aviso('connection to the server lost; the URL is offline'));
+  tunel.on('reconectando', ({ emMs }) => tela.aviso(`reconnecting in ${(emMs / 1000).toFixed(1)}s…`));
+  tunel.on('aviso', (erro) => tela.aviso(`server: ${erro.code ?? erro.message}`));
+
+  return await new Promise((resolver) => {
+    tunel.on('recusado', (erro) => {
+      if (modoServico) {
+        tela.erro(`server refused the tunnel: ${erro.message}; trying again`);
+        return;
+      }
+      tela.erro(`server refused the tunnel: ${erro.message}`);
+      tunel.fechar();
+      resolver(1);
+    });
+    const sair = () => {
+      tunel.fechar();
+      resolver(0);
+    };
+    process.once('SIGINT', sair);
+    process.once('SIGTERM', sair);
+    tunel.abrir();
+  });
+}

package/agente/servico/comum.js

@@ -0,0 +1,39 @@
+// O que os três sistemas dividem: o comando do agente em modo serviço e o executor dos comandos do sistema.
+import { spawnSync } from 'node:child_process';
+
+export const NOME = 'localhostly';
+
+// spawnSync sem lançar: { rc, saida, erro } (rc -1 quando o programa nem existe).
+export function executar(programa, args = [], opcoes = {}) {
+  const r = spawnSync(programa, args, { encoding: 'utf8', windowsHide: true, ...opcoes });
+  return {
+    rc: r.error ? -1 : r.status ?? -1,
+    saida: r.stdout ?? '',
+    erro: r.error ? r.error.message : r.stderr ?? '',
+  };
+}
+
+// O argv do agente que o serviço roda: [node, bin/localhostly.js, 'http', porta, '--service', ...]. A senha nunca vai
+// na linha de comando (o `ps` a mostraria a qualquer usuário): só o caminho do arquivo 0600 que a guarda.
+export function comandoDoAgente({ exe, porta, host = null, servidor = null, home, arquivoSenha = null }) {
+  if (!Array.isArray(exe) || exe.length === 0) throw new Error('exe: the agent command is missing');
+  if (!Number.isInteger(porta) || porta < 1 || porta > 65535) throw new Error(`invalid port: ${porta}`);
+  const args = [...exe, 'http', String(porta), '--service', '--home', home];
+  if (host) args.push('--host', host);
+  if (servidor) args.push('--server', servidor);
+  if (arquivoSenha) args.push('--password-file', arquivoSenha);
+  return args;
+}
+
+export class ErroServico extends Error {
+  constructor(mensagem, detalhe = '') {
+    super(detalhe ? `${mensagem}\n${detalhe.trim()}` : mensagem);
+  }
+}
+
+// Roda e lança com a saída do comando quando ele falha.
+export function exigir(exec, programa, args, mensagem) {
+  const r = exec(programa, args);
+  if (r.rc !== 0) throw new ErroServico(`${mensagem} (${[programa, ...args].join(' ')}: exit ${r.rc})`, r.erro || r.saida);
+  return r;
+}

package/agente/servico/index.js

@@ -0,0 +1,98 @@
+// `localhostly service install|status|uninstall`: escolhe o sistema por process.platform e prepara o que os três
+// dividem (o comando do agente, o arquivo da senha, o estado do último túnel).
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { comandoDoAgente, ErroServico, executar } from './comum.js';
+import * as launchd from './launchd.js';
+import * as systemd from './systemd.js';
+import * as windows from './windows.js';
+
+export { ErroServico };
+
+const SISTEMAS = { linux: systemd, darwin: launchd, win32: windows };
+const NOMES = { linux: 'systemd user service', darwin: 'launchd LaunchAgent', win32: 'Windows service' };
+
+export function sistema(plataforma = process.platform) {
+  const s = SISTEMAS[plataforma];
+  if (!s) throw new ErroServico(`localhostly service does not support ${plataforma} (Linux, macOS and Windows only)`);
+  return s;
+}
+
+export function nomeDoSistema(plataforma = process.platform) {
+  return NOMES[plataforma] ?? plataforma;
+}
+
+// O agente que o serviço roda: este node e este bin/localhostly.js, por caminho absoluto; no binário do download
+// (empacotado pelo pkg, scripts/binarios.sh) o próprio executável é o agente.
+export function exePadrao(empacotado = Boolean(process.pkg)) {
+  if (empacotado) return [process.execPath];
+  return [process.execPath, fileURLToPath(new URL('../../bin/localhostly.js', import.meta.url))];
+}
+
+export function arquivoSenha(home) {
+  return join(home, 'service-password');
+}
+
+export function arquivoEstado(home) {
+  return join(home, 'estado.json');
+}
+
+// O último túnel do serviço: { nome, tokenSessao, url, em }. A reconexão (e o serviço relançado) pede o mesmo nome.
+export function lerEstado(home) {
+  try {
+    const e = JSON.parse(readFileSync(arquivoEstado(home), 'utf8'));
+    return typeof e?.nome === 'string' && typeof e?.tokenSessao === 'string' ? e : null;
+  } catch {
+    return null;
+  }
+}
+
+export function gravarEstado(home, { nome, tokenSessao, url }, agora = new Date()) {
+  mkdirSync(home, { recursive: true, mode: 0o700 });
+  const arquivo = arquivoEstado(home);
+  const temp = `${arquivo}.${process.pid}.tmp`;
+  writeFileSync(temp, `${JSON.stringify({ nome, tokenSessao, url, em: agora.toISOString() }, null, 2)}\n`, { mode: 0o600 });
+  renameSync(temp, arquivo); // inteiro ou nada: o serviço morto no meio não deixa o estado pela metade
+  try {
+    chmodSync(arquivo, 0o600);
+  } catch {}
+  return arquivo;
+}
+
+// opcoes: { porta, host, servidor, senha (texto ou null), home, exe }
+export function instalar(opcoes, { plataforma = process.platform, casa = homedir(), env = process.env, exec = executar, uid } = {}) {
+  const s = sistema(plataforma);
+  const { porta, host = null, servidor = null, senha = null, home, exe = exePadrao() } = opcoes;
+  if (!Number.isInteger(porta)) throw new ErroServico('usage: localhostly service install <port> [--host h[:p]] [--password [value]]');
+  mkdirSync(home, { recursive: true, mode: 0o700 });
+  let arquivo = null;
+  if (senha) {
+    arquivo = arquivoSenha(home);
+    writeFileSync(arquivo, `${senha}\n`, { mode: 0o600 });
+    try {
+      chmodSync(arquivo, 0o600);
+    } catch {}
+  } else {
+    rmSync(arquivoSenha(home), { force: true });
+  }
+  const comando = comandoDoAgente({ exe, porta, host, servidor, home, arquivoSenha: arquivo });
+  const r = s.instalar({ comando, porta, home }, { casa, env, exec, home, ...(uid === undefined ? {} : { uid }) });
+  // o npx roda de uma pasta de cache que pode sumir: o serviço apontaria para um caminho morto
+  if (exe.some((parte) => /[\\/]_npx[\\/]/.test(parte))) {
+    r.avisos = [...(r.avisos ?? []), 'This localhostly runs from the npx cache, which can be cleaned: install it for good and run `service install` again.'];
+  }
+  return r;
+}
+
+export function remover({ plataforma = process.platform, casa = homedir(), env = process.env, exec = executar, uid, home } = {}) {
+  const r = sistema(plataforma).remover({ casa, env, exec, home, ...(uid === undefined ? {} : { uid }) });
+  if (home) rmSync(arquivoSenha(home), { force: true });
+  return r;
+}
+
+export function status({ plataforma = process.platform, casa = homedir(), env = process.env, exec = executar, uid, home } = {}) {
+  const r = sistema(plataforma).status({ casa, env, exec, home, ...(uid === undefined ? {} : { uid }) });
+  return { ...r, tunel: home ? lerEstado(home) : null };
+}

package/agente/servico/launchd.js

@@ -0,0 +1,100 @@
+// macOS: um LaunchAgent do usuário (~/Library/LaunchAgents/io.iblabs.localhostly.plist, `launchctl`), que sobe no
+// login (RunAtLoad) e é relançado pelo launchd quando cai (KeepAlive).
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ErroServico, executar } from './comum.js';
+
+export const ROTULO = 'io.iblabs.localhostly';
+
+export function arquivoDoPlist({ casa = homedir() } = {}) {
+  return join(casa, 'Library', 'LaunchAgents', `${ROTULO}.plist`);
+}
+
+export function arquivoDoLog({ casa = homedir() } = {}) {
+  return join(casa, 'Library', 'Logs', 'localhostly.log');
+}
+
+export function escaparXml(texto) {
+  return String(texto)
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+}
+
+export function gerarPlist(comando, { log }) {
+  const str = (v) => `<string>${escaparXml(v)}</string>`;
+  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">',
+    '<dict>',
+    '  <key>Label</key>',
+    `  ${str(ROTULO)}`,
+    '  <key>ProgramArguments</key>',
+    '  <array>',
+    ...comando.map((a) => `    ${str(a)}`),
+    '  </array>',
+    '  <key>EnvironmentVariables</key>',
+    '  <dict>',
+    '    <key>NO_COLOR</key>',
+    '    <string>1</string>',
+    '  </dict>',
+    '  <key>RunAtLoad</key>',
+    '  <true/>',
+    '  <key>KeepAlive</key>',
+    '  <true/>',
+    '  <key>ThrottleInterval</key>',
+    '  <integer>5</integer>',
+    '  <key>ProcessType</key>',
+    '  <string>Background</string>',
+    '  <key>StandardOutPath</key>',
+    `  ${str(log)}`,
+    '  <key>StandardErrorPath</key>',
+    `  ${str(log)}`,
+    '</dict>',
+    '</plist>',
+    '',
+  ].join('\n');
+}
+
+function dominio(uid) {
+  return `gui/${uid}`;
+}
+
+export function instalar({ comando }, { casa, uid = process.getuid?.(), exec = executar } = {}) {
+  const arquivo = arquivoDoPlist({ casa });
+  const log = arquivoDoLog({ casa });
+  mkdirSync(join(arquivo, '..'), { recursive: true });
+  mkdirSync(join(log, '..'), { recursive: true });
+  // reinstalar troca a configuração: o agente de antes sai do launchd antes do novo entrar
+  exec('launchctl', ['bootout', `${dominio(uid)}/${ROTULO}`]);
+  writeFileSync(arquivo, gerarPlist(comando, { log }));
+  exec('launchctl', ['enable', `${dominio(uid)}/${ROTULO}`]);
+  const r = exec('launchctl', ['bootstrap', dominio(uid), arquivo]);
+  if (r.rc !== 0) {
+    throw new ErroServico(`could not load the LaunchAgent (launchctl bootstrap ${dominio(uid)}: exit ${r.rc})`, r.erro || r.saida);
+  }
+  return { arquivo, log: `tail -f ${log}`, avisos: [] };
+}
+
+export function remover({ casa, uid = process.getuid?.(), exec = executar } = {}) {
+  const arquivo = arquivoDoPlist({ casa });
+  const existia = existsSync(arquivo);
+  exec('launchctl', ['bootout', `${dominio(uid)}/${ROTULO}`]);
+  rmSync(arquivo, { force: true });
+  return { removido: existia, arquivo };
+}
+
+export function status({ casa, uid = process.getuid?.(), exec = executar } = {}) {
+  const arquivo = arquivoDoPlist({ casa });
+  if (!existsSync(arquivo)) return { instalado: false, arquivo };
+  const r = exec('launchctl', ['print', `${dominio(uid)}/${ROTULO}`]);
+  const base = { instalado: true, arquivo, sobeSozinho: true, log: `tail -f ${arquivoDoLog({ casa })}` };
+  if (r.rc !== 0) return { ...base, rodando: false, estado: 'not loaded', pid: null, sobeSozinho: false };
+  const estado = /^\s*state = (.+)$/m.exec(r.saida)?.[1]?.trim() ?? 'unknown';
+  const pid = Number(/^\s*pid = (\d+)/m.exec(r.saida)?.[1]) || null;
+  return { ...base, rodando: estado === 'running', estado, pid };
+}