amalgm 0.1.41 → 0.1.44

package/README.md

@@ -22,7 +22,19 @@ amalgm login --setup-code ABCD-EFGH-JKLM-NPQR
 
 `amalgm doctor` checks the installed runtime, login record, service supervisor, required local ports, daemon state, and whether an HMAC proxy token is available.
 
-`amalgm start` installs/starts the best available service supervisor for the machine, then the supervisor runs `amalgm run` and keeps the local essentials alive:
+`amalgm run` is the foreground runtime supervisor. It reads the declared service manifest, starts each local service, health-checks them, and restarts unhealthy children with backoff. In a container you control, make this the container command/entrypoint, ideally behind a tiny init such as Docker `--init`, `tini`, or the provider's init wrapper:
+
+```sh
+amalgm run
+```
+
+`amalgm start` is the host attachment helper. It installs/starts the best available launcher for the machine, then that launcher runs `amalgm run`:
+
+- macOS host: LaunchAgent
+- Linux host with real user systemd: systemd user service
+- random/container shell where no service manager is available: portable best-effort watchdog
+
+The runtime supervisor keeps the declared local essentials alive:
 
 - port monitor on `8081`
 - filesystem/auth watcher on `8082`
@@ -31,7 +43,7 @@ amalgm login --setup-code ABCD-EFGH-JKLM-NPQR
 - events/previews/artifact tunnel to `wire.events.amalgm.ai`
 - chat tunnel to `amalgm-chat-gateway`
 
-The npm supervisor binds local services to `127.0.0.1` by default and connects them outward through the registered Amalgm tunnels. For development without cloud registration, use `amalgm start --local-only`. For direct foreground debugging, use `amalgm start --foreground`.
+The npm supervisor binds local services to `127.0.0.1` by default and connects them outward through the registered Amalgm tunnels. For development without cloud registration, use `amalgm start --local-only`. For direct foreground debugging, use `amalgm run` or `amalgm start --foreground`.
 
 Useful commands:
 

package/lib/cli.js

@@ -28,6 +28,17 @@ const {
   stopService,
   uninstallService,
 } = require('./service');
+const {
+  cleanupStaleRuntimeProcesses,
+  runtimeServiceProcesses,
+  supervisorProcesses,
+} = require('./process-cleanup');
+const {
+  runtimePortsForStatus,
+  runtimeServiceNames,
+  runtimeServiceScripts,
+  runtimeServices,
+} = require('./runtime-manifest');
 const {
   deleteComputerAuth,
   loadComputerRecord,
@@ -84,6 +95,7 @@ function usage() {
     'Usage:',
     '  amalgm login [--app-url https://amalgm.ai] [--name "My Mac"] [--setup-code ABCD-EFGH-JKLM-NPQR] [--no-open] [--no-poll]',
     '  amalgm start [--foreground] [--local-only]',
+    '  amalgm run [--local-only]',
     '  amalgm stop',
     '  amalgm status',
     '  amalgm doctor',
@@ -139,36 +151,13 @@ function runtimeEntry(relativePath) {
 }
 
 function runtimeMissingFiles() {
-  const required = [
-    runtimeEntry('scripts/amalgm-mcp/index.js'),
-    runtimeEntry('scripts/chat-server.js'),
-    runtimeEntry('scripts/fs-watcher.js'),
-    runtimeEntry('scripts/local-gateway.js'),
-    runtimeEntry('scripts/port-monitor.js'),
-  ];
+  const required = runtimeServiceScripts().map((script) => runtimeEntry(script));
   return required.filter((file) => !fs.existsSync(file));
 }
 
 function servicePorts() {
   const state = readJson(RUNTIME_STATE_FILE, null);
-  const statePorts = state?.ports || {};
-  if (Number.isInteger(state?.gateway_port)) {
-    return [
-      ['local-gateway', Number(state.gateway_port)],
-      ['port-monitor', Number(statePorts.port_monitor || 0)],
-      ['fs-watcher', Number(statePorts.fs_watcher || 0)],
-      ['amalgm-mcp', Number(statePorts.amalgm_mcp || 0)],
-      ['chat-server', Number(statePorts.chat_server || 0)],
-    ].filter(([, port]) => Number.isInteger(port) && port > 0);
-  }
-
-  return [
-    ['local-gateway', Number(process.env.AMALGM_GATEWAY_PORT || 28781)],
-    ['port-monitor', Number(process.env.PORT_MONITOR_PORT || 8081)],
-    ['fs-watcher', Number(process.env.FS_WATCHER_PORT || 8082)],
-    ['amalgm-mcp', Number(process.env.AMALGM_MCP_PORT || 8083)],
-    ['chat-server', Number(process.env.CHAT_SERVER_PORT || 8084)],
-  ];
+  return runtimePortsForStatus(state, process.env);
 }
 
 function hasRequiredComputerFields(record) {
@@ -352,13 +341,7 @@ function isPortFree(port, host = '127.0.0.1') {
 
 async function unavailableServicePorts() {
   const results = [];
-  const explicitEnvByService = new Map([
-    ['local-gateway', 'AMALGM_GATEWAY_PORT'],
-    ['port-monitor', 'PORT_MONITOR_PORT'],
-    ['fs-watcher', 'FS_WATCHER_PORT'],
-    ['amalgm-mcp', 'AMALGM_MCP_PORT'],
-    ['chat-server', 'CHAT_SERVER_PORT'],
-  ]);
+  const explicitEnvByService = new Map(runtimeServices().map((service) => [service.name, service.envName]));
   for (const [name, port] of servicePorts()) {
     const envName = explicitEnvByService.get(name);
     if (!envName || !process.env[envName]) continue;
@@ -846,6 +829,8 @@ async function start(options) {
     await stop();
   }
 
+  cleanupStaleRuntimeProcesses({ includeSupervisors: true });
+
   const blockedPorts = await unavailableServicePorts();
   if (blockedPorts.length > 0) {
     const detail = blockedPorts.map(([name, port]) => `${name} (${port})`).join(', ');
@@ -928,6 +913,7 @@ async function stop() {
     } catch {
       // noop
     }
+    cleanupStaleRuntimeProcesses({ includeSupervisors: true });
     console.log('Amalgm is not running.');
     return;
   }
@@ -951,10 +937,11 @@ async function stop() {
   } catch {
     // noop
   }
+  cleanupStaleRuntimeProcesses({ includeSupervisors: true });
   console.log('Amalgm stopped.');
 }
 
-async function checkHttp(port, pathName = '/healthz') {
+async function checkHttpOnce(port, pathName = '/healthz', timeoutMs = 1500) {
   return new Promise((resolve) => {
     const req = http.request(
       {
@@ -962,7 +949,7 @@ async function checkHttp(port, pathName = '/healthz') {
         port,
         path: pathName,
         method: 'GET',
-        timeout: 1000,
+        timeout: timeoutMs,
       },
       (res) => {
         res.resume();
@@ -978,6 +965,16 @@ async function checkHttp(port, pathName = '/healthz') {
   });
 }
 
+async function checkHttp(port, pathName = '/healthz', options = {}) {
+  const attempts = Math.max(1, Number(options.attempts || 3));
+  const timeoutMs = Math.max(500, Number(options.timeoutMs || 1500));
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    if (await checkHttpOnce(port, pathName, timeoutMs)) return true;
+    if (attempt < attempts - 1) await sleep(150);
+  }
+  return false;
+}
+
 async function waitForServices(timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   let latest = [];
@@ -1028,9 +1025,26 @@ async function status() {
   }
   console.log(`HMAC proxy: ${proxyTokenFromRecord(record) ? 'configured' : 'not configured'}`);
 
+  const runtimeChildren = runtimeServiceProcesses();
+  const runtimeSupervisors = supervisorProcesses();
+  const expectedServiceCount = runtimeServiceNames().length;
+  if (runtimeChildren.length > expectedServiceCount || runtimeSupervisors.length > 1) {
+    console.log(
+      `Warning: multiple Amalgm runtime processes detected (${runtimeSupervisors.length} supervisor, ${runtimeChildren.length} services). Run \`amalgm stop && amalgm start\`.`,
+    );
+  }
+
+  const serviceStateByName = new Map(
+    (Array.isArray(runtimeState?.services) ? runtimeState.services : [])
+      .map((service) => [service.name, service]),
+  );
   for (const [name, port] of servicePorts()) {
     const ok = await checkHttp(port);
-    console.log(`${name.padEnd(13)} ${ok ? 'up' : 'down'}  http://127.0.0.1:${port}`);
+    const serviceState = serviceStateByName.get(name);
+    const detail = serviceState?.status && serviceState.status !== 'running'
+      ? ` (${serviceState.status}${serviceState.reason ? `: ${serviceState.reason}` : ''})`
+      : '';
+    console.log(`${name.padEnd(13)} ${ok ? 'up' : 'down'}  http://127.0.0.1:${port}${detail}`);
   }
 }
 
@@ -1101,6 +1115,16 @@ async function doctor() {
     );
   }
   add('daemon', daemonRunning, daemonRunning ? `pid ${pid}` : 'stopped', daemonRunning ? 'ok' : 'warn');
+  const runtimeChildren = runtimeServiceProcesses();
+  const runtimeSupervisors = supervisorProcesses();
+  const expectedServices = daemonRunning ? runtimeServiceNames().length : 0;
+  const cleanProcessShape = runtimeSupervisors.length <= 1 && runtimeChildren.length <= expectedServices;
+  add(
+    'runtime processes',
+    cleanProcessShape,
+    `${runtimeSupervisors.length} supervisor, ${runtimeChildren.length} services`,
+    cleanProcessShape ? 'ok' : 'warn',
+  );
   if (lastShutdown?.signal || lastShutdown?.reason) {
     add(
       'last shutdown',
@@ -1109,15 +1133,25 @@ async function doctor() {
       'warn',
     );
   }
+  const runtimeServiceState = Array.isArray(readJson(RUNTIME_STATE_FILE, null)?.services)
+    ? readJson(RUNTIME_STATE_FILE, null).services
+    : [];
+  const unhealthyState = runtimeServiceState.filter((service) => (
+    service.status && !['running', 'starting'].includes(service.status)
+  ));
+  if (runtimeServiceState.length > 0) {
+    add(
+      'service states',
+      unhealthyState.length === 0,
+      unhealthyState.length === 0
+        ? `${runtimeServiceState.length} declared service(s) running/starting`
+        : unhealthyState.map((service) => `${service.name}:${service.status}`).join(', '),
+      unhealthyState.length === 0 ? 'ok' : 'warn',
+    );
+  }
 
   for (const [name, port] of servicePorts()) {
-    const envName = {
-      'local-gateway': 'AMALGM_GATEWAY_PORT',
-      'port-monitor': 'PORT_MONITOR_PORT',
-      'fs-watcher': 'FS_WATCHER_PORT',
-      'amalgm-mcp': 'AMALGM_MCP_PORT',
-      'chat-server': 'CHAT_SERVER_PORT',
-    }[name];
+    const envName = runtimeServices().find((service) => service.name === name)?.envName;
     const ok = daemonRunning ? await checkHttp(port) : (!process.env[envName] || await isPortFree(port));
     add(
       `${name} port`,

package/lib/process-cleanup.js

@@ -0,0 +1,239 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const {
+  AMALGM_DIR,
+  PACKAGE_ROOT,
+  RUNTIME_DIR,
+} = require('./paths');
+const {
+  runtimeServiceScripts,
+} = require('./runtime-manifest');
+
+const RUNTIME_SERVICE_MARKERS = runtimeServiceScripts()
+  .map((script) => path.join(RUNTIME_DIR, script).replace(/\\/g, '/'));
+const RUNTIME_SERVICE_SUFFIXES = runtimeServiceScripts()
+  .map((script) => `runtime/${script}`.replace(/\\/g, '/'));
+
+const SUPERVISOR_MARKER = path.join(PACKAGE_ROOT, 'bin', 'amalgm.js').replace(/\\/g, '/');
+const SUPERVISOR_SUFFIX = '/bin/amalgm.js';
+
+function isPidRunning(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function waitForExit(pid, timeoutMs = 5000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline && isPidRunning(pid)) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+  }
+  return !isPidRunning(pid);
+}
+
+function readProcString(file) {
+  try {
+    return fs.readFileSync(file).toString('utf8');
+  } catch {
+    return '';
+  }
+}
+
+function readProcCommand(pid) {
+  const cmdline = readProcString(`/proc/${pid}/cmdline`).replace(/\0/g, ' ').trim();
+  if (cmdline) return cmdline;
+  try {
+    const result = spawnSync('ps', ['-p', String(pid), '-o', 'command='], {
+      encoding: 'utf8',
+      timeout: 1000,
+    });
+    return String(result.stdout || '').trim();
+  } catch {
+    return '';
+  }
+}
+
+function readProcPpid(pid) {
+  try {
+    const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf8');
+    const lastParen = stat.lastIndexOf(')');
+    if (lastParen === -1) return null;
+    const parts = stat.slice(lastParen + 2).trim().split(/\s+/);
+    const ppid = Number(parts[1]);
+    return Number.isInteger(ppid) ? ppid : null;
+  } catch {
+    return null;
+  }
+}
+
+function readProcEnv(pid) {
+  const raw = readProcString(`/proc/${pid}/environ`);
+  if (!raw) return null;
+  const env = {};
+  for (const entry of raw.split('\0')) {
+    if (!entry) continue;
+    const index = entry.indexOf('=');
+    if (index <= 0) continue;
+    env[entry.slice(0, index)] = entry.slice(index + 1);
+  }
+  return env;
+}
+
+function listProcProcesses() {
+  try {
+    return fs.readdirSync('/proc')
+      .filter((entry) => /^\d+$/.test(entry))
+      .map((entry) => Number(entry))
+      .filter((pid) => Number.isInteger(pid) && pid > 0)
+      .map((pid) => ({
+        pid,
+        ppid: readProcPpid(pid),
+        command: readProcCommand(pid),
+        env: readProcEnv(pid),
+      }))
+      .filter((item) => item.command);
+  } catch {
+    return null;
+  }
+}
+
+function listPsProcesses() {
+  try {
+    const result = spawnSync('ps', ['-eo', 'pid=,ppid=,command='], {
+      encoding: 'utf8',
+      timeout: 2000,
+    });
+    if (result.status !== 0) return [];
+    return String(result.stdout || '')
+      .split('\n')
+      .map((line) => {
+        const match = line.trim().match(/^(\d+)\s+(\d+)\s+(.+)$/);
+        if (!match) return null;
+        return {
+          pid: Number(match[1]),
+          ppid: Number(match[2]),
+          command: match[3],
+          env: null,
+        };
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function listProcesses() {
+  const processes = listProcProcesses() || listPsProcesses();
+  const commandByPid = new Map(processes.map((item) => [item.pid, item.command]));
+  return processes.map((item) => ({
+    ...item,
+    parentCommand: commandByPid.get(item.ppid) || readProcCommand(item.ppid),
+  }));
+}
+
+function normalizedCommand(command) {
+  return String(command || '').replace(/\\/g, '/');
+}
+
+function envMatchesAmalgmDir(env) {
+  if (!env || !env.AMALGM_DIR) return true;
+  return path.resolve(env.AMALGM_DIR) === path.resolve(AMALGM_DIR);
+}
+
+function commandLooksLikeRuntimeService(command, item = null, options = {}) {
+  const normalized = normalizedCommand(command);
+  if (RUNTIME_SERVICE_MARKERS.some((marker) => normalized.includes(marker))) return true;
+  if (!RUNTIME_SERVICE_SUFFIXES.some((marker) => normalized.includes(marker))) return false;
+  if (item?.env && envMatchesAmalgmDir(item.env)) return true;
+  if (!options.includeOrphanedForeign) return false;
+  const parent = normalizedCommand(item?.parentCommand || '');
+  return !commandLooksLikeAnySupervisor(parent);
+}
+
+function commandLooksLikeSupervisor(command) {
+  const normalized = normalizedCommand(command);
+  return normalized.includes(SUPERVISOR_MARKER) && /\brun\b/.test(normalized);
+}
+
+function commandLooksLikeAnySupervisor(command) {
+  const normalized = normalizedCommand(command);
+  return normalized.includes(SUPERVISOR_SUFFIX) && /\brun\b/.test(normalized);
+}
+
+function runtimeServiceProcesses(options = {}) {
+  const exclude = new Set([process.pid, ...(options.excludePids || [])].filter(Number.isInteger));
+  return listProcesses()
+    .filter((item) => !exclude.has(item.pid))
+    .filter((item) => commandLooksLikeRuntimeService(item.command, item, options))
+    .filter((item) => envMatchesAmalgmDir(item.env));
+}
+
+function supervisorProcesses(options = {}) {
+  const exclude = new Set([process.pid, ...(options.excludePids || [])].filter(Number.isInteger));
+  return listProcesses()
+    .filter((item) => !exclude.has(item.pid))
+    .filter((item) => commandLooksLikeSupervisor(item.command))
+    .filter((item) => envMatchesAmalgmDir(item.env));
+}
+
+function terminateProcesses(processes, options = {}) {
+  const logger = options.logger || null;
+  const unique = [...new Map(processes.map((item) => [item.pid, item])).values()]
+    .filter((item) => isPidRunning(item.pid));
+  if (unique.length === 0) return [];
+
+  for (const item of unique) {
+    try {
+      process.kill(item.pid, 'SIGTERM');
+    } catch {
+      // It may have exited between discovery and shutdown.
+    }
+  }
+
+  const survivors = [];
+  for (const item of unique) {
+    if (!waitForExit(item.pid, options.termTimeoutMs || 3000)) survivors.push(item);
+  }
+
+  for (const item of survivors) {
+    try {
+      process.kill(item.pid, 'SIGKILL');
+    } catch {
+      // noop
+    }
+  }
+  for (const item of survivors) waitForExit(item.pid, options.killTimeoutMs || 1500);
+
+  const stopped = unique.filter((item) => !isPidRunning(item.pid));
+  if (stopped.length > 0 && logger?.log) {
+    logger.log(`cleaned stale Amalgm runtime process(es): ${stopped.map((item) => item.pid).join(', ')}`);
+  }
+  return stopped;
+}
+
+function cleanupStaleRuntimeProcesses(options = {}) {
+  const stale = runtimeServiceProcesses({
+    includeOrphanedForeign: true,
+    ...options,
+  });
+  const supervisors = options.includeSupervisors ? supervisorProcesses(options) : [];
+  return terminateProcesses([...stale, ...supervisors], options);
+}
+
+module.exports = {
+  cleanupStaleRuntimeProcesses,
+  commandLooksLikeRuntimeService,
+  commandLooksLikeSupervisor,
+  isPidRunning,
+  runtimeServiceProcesses,
+  supervisorProcesses,
+  terminateProcesses,
+};

package/lib/runtime-manifest.js

@@ -0,0 +1,131 @@
+'use strict';
+
+const RUNTIME_SERVICES = [
+  {
+    name: 'local-gateway',
+    script: 'scripts/local-gateway.js',
+    portKey: 'gateway',
+    envName: 'AMALGM_GATEWAY_PORT',
+    stateKey: 'gateway',
+    defaultPort: 28781,
+    launchOrder: 50,
+  },
+  {
+    name: 'port-monitor',
+    script: 'scripts/port-monitor.js',
+    portKey: 'portMonitor',
+    envName: 'PORT_MONITOR_PORT',
+    stateKey: 'port_monitor',
+    defaultPort: 8081,
+    launchOrder: 10,
+  },
+  {
+    name: 'fs-watcher',
+    script: 'scripts/fs-watcher.js',
+    portKey: 'fsWatcher',
+    envName: 'FS_WATCHER_PORT',
+    stateKey: 'fs_watcher',
+    defaultPort: 8082,
+    launchOrder: 20,
+  },
+  {
+    name: 'amalgm-mcp',
+    script: 'scripts/amalgm-mcp/index.js',
+    portKey: 'amalgmMcp',
+    envName: 'AMALGM_MCP_PORT',
+    stateKey: 'amalgm_mcp',
+    defaultPort: 8083,
+    launchOrder: 40,
+  },
+  {
+    name: 'chat-server',
+    script: 'scripts/chat-server.js',
+    portKey: 'chatServer',
+    envName: 'CHAT_SERVER_PORT',
+    stateKey: 'chat_server',
+    defaultPort: 8084,
+    launchOrder: 30,
+  },
+];
+
+function runtimeServices() {
+  return RUNTIME_SERVICES.map((service) => ({ ...service }));
+}
+
+function runtimeLaunchServices() {
+  return runtimeServices().sort((left, right) => left.launchOrder - right.launchOrder);
+}
+
+function runtimeServiceNames() {
+  return RUNTIME_SERVICES.map((service) => service.name);
+}
+
+function runtimeServiceScripts() {
+  return RUNTIME_SERVICES.map((service) => service.script);
+}
+
+function runtimeServiceByName(name) {
+  return RUNTIME_SERVICES.find((service) => service.name === name) || null;
+}
+
+function runtimePortsFromState(state) {
+  const statePorts = state?.ports || {};
+  const values = {};
+  for (const service of RUNTIME_SERVICES) {
+    if (service.stateKey === 'gateway' && Number.isInteger(state?.gateway_port)) {
+      values[service.name] = Number(state.gateway_port);
+      continue;
+    }
+    const port = Number(statePorts[service.stateKey] || 0);
+    if (Number.isInteger(port) && port > 0) values[service.name] = port;
+  }
+  return values;
+}
+
+function runtimePortsFromEnv(env = process.env) {
+  const values = {};
+  for (const service of RUNTIME_SERVICES) {
+    const port = Number(env[service.envName] || service.defaultPort);
+    if (Number.isInteger(port) && port > 0) values[service.name] = port;
+  }
+  return values;
+}
+
+function runtimePortsForStatus(state, env = process.env) {
+  const fromState = runtimePortsFromState(state);
+  const fromEnv = runtimePortsFromEnv(env);
+  return RUNTIME_SERVICES
+    .map((service) => [service.name, fromState[service.name] || fromEnv[service.name]])
+    .filter(([, port]) => Number.isInteger(port) && port > 0);
+}
+
+function runtimePortsState(ports) {
+  const statePorts = {};
+  for (const service of RUNTIME_SERVICES) {
+    const port = Number(ports?.[service.portKey] || 0);
+    if (!Number.isInteger(port) || port <= 0) continue;
+    if (service.stateKey !== 'gateway') statePorts[service.stateKey] = port;
+  }
+  return {
+    gateway_port: Number(ports?.gateway || 0) || undefined,
+    gateway_url: ports?.gateway ? `http://127.0.0.1:${ports.gateway}` : undefined,
+    ports: statePorts,
+    services: RUNTIME_SERVICES.map((service) => ({
+      name: service.name,
+      port: Number(ports?.[service.portKey] || 0) || null,
+      health_path: '/healthz',
+    })),
+  };
+}
+
+module.exports = {
+  runtimeLaunchServices,
+  runtimePortsForStatus,
+  runtimePortsFromEnv,
+  runtimePortsFromState,
+  runtimePortsState,
+  runtimeServiceByName,
+  runtimeServiceNames,
+  runtimeServiceScripts,
+  runtimeServices,
+};