Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

12.4 KB
Raw Blame
/**
 * The SSE runner behind every harness lifecycle action — install, update,
 * remove.
 *
 * Extracted from `routes/providers.js`, which owned the install stream inline,
 * so the Harnesses page can drive update and remove through the SAME single
 * child, single-flight guard, and disconnect-cancels contract. Two copies of
 * that loop would mean two independent guards, and npm's global prefix plus the
 * vendor install scripts all write ONE bin directory — an update racing an
 * install there is exactly the corruption the guard exists to prevent.
 *
 * Installing, updating, or removing a global CLI mutates host state, so every
 * caller is a POST even though the response is SSE-encoded, and the browser
 * reads it with fetch rather than EventSource (which auto-reconnects and would
 * relaunch non-idempotent work on a dropped stream).
 *
 * The request names a runtime *id* and an *action*, both table lookups. The
 * command, package and URL come from `providerRuntimeInstaller.js`'s fixed
 * table, so no request input ever reaches a shell word.
 */

import { createLineReader } from '../lib/streamLines.js';
import { onClientDisconnect, openSseStream } from '../lib/sseDownload.js';
import { createInstallLogger } from '../lib/installLogger.js';
import { ServerError } from '../lib/errorHandler.js';
import {
  buildRuntimeActionCommand,
  describeRuntimeInstall,
  getProviderRuntime,
  getProviderRuntimeStatus,
  RUNTIME_ACTIONS,
  spawnRuntimeInstaller,
  stopRuntimeInstaller,
} from './providerRuntimeInstaller.js';

/**
 * One global CLI action at a time — npm's global prefix and the vendor install
 * scripts all write the same bin directory. A lightweight re-entrancy guard for
 * a double-click or a second browser tab, shared by every action so an update
 * cannot start while an install is mid-write. The child stays owned by the
 * request so a client disconnect can terminate it.
 */
let actionInFlight = null;

/** Test-only: clear a guard left set by an aborted run. */
export function __resetHarnessActionGuard() {
  actionInFlight = null;
}

/**
 * Per-action copy. `skipWhenInstalled` carries both the short-circuit message
 * AND, by its absence, the "this action needs the harness present" rule — the
 * two are the same fact stated once: an action that has nothing to do when the
 * CLI is there is exactly the one that has something to do when it isn't.
 *
 * Install is the only action with that short-circuit. Update deliberately has
 * none: "you are on the latest" is the vendor updater's answer to give, not
 * ours to guess from a registry read that may be stale or unavailable.
 *
 * Keyed by the same strings as `RUNTIME_ACTIONS`; `providerRuntimeInstaller.test.js`
 * pins the two together, because a fourth action would otherwise reach
 * `ACTION_COPY[action]` as `undefined` and crash mid-stream.
 */
export const HARNESS_ACTION_COPY = Object.freeze({
  install: { verb: 'Installing', noun: 'installer', skipWhenInstalled: 'Already installed — nothing to do.' },
  update: { verb: 'Updating', noun: 'updater', skipWhenInstalled: null },
  uninstall: { verb: 'Removing', noun: 'uninstaller', skipWhenInstalled: null },
});

/**
 * Run one harness action, streaming the child's output to the browser as SSE.
 *
 * Resolves once the stream has ended. Throws only BEFORE the headers are
 * flushed (unknown id, unsupported action) — after that point every failure is
 * reported as a terminal SSE frame, because the error middleware can no longer
 * send a JSON body to this response.
 *
 * @param {import('express').Request} req
 * @param {import('express').Response} res
 * @param {{runtime: unknown, action?: string}} params
 */
export async function streamHarnessAction(req, res, { runtime: runtimeId, action = 'install' }) {
  if (!RUNTIME_ACTIONS.includes(action)) {
    throw new ServerError('Unknown harness action', { status: 400, code: 'UNKNOWN_HARNESS_ACTION', context: { action: String(action || '') } });
  }
  // Table lookups only (no I/O), so a bad request is a plain 400 instead of a
  // stream that only says "no" once the modal is up. The real probe waits until
  // the disconnect handler is registered below.
  const row = getProviderRuntime(runtimeId);
  if (!row) {
    throw new ServerError('Unknown provider runtime', { status: 400, code: 'UNKNOWN_RUNTIME', context: { runtime: String(runtimeId || '') } });
  }
  if (!buildRuntimeActionCommand(row.id, action)) {
    throw new ServerError(
      `PortOS cannot ${action} ${row.label} — it was not installed from a package manager PortOS drives. Follow the vendor instructions instead.`,
      { status: 400, code: 'UNSUPPORTED_HARNESS_ACTION', context: { runtime: row.id, action } },
    );
  }

  const copy = HARNESS_ACTION_COPY[action];
  const { send, safeEnd } = openSseStream(res);
  // The ledger line names the ACTION, not just the harness — three lanes share
  // this logger, and a bare label would file every removal as an install.
  const installLog = createInstallLogger({
    installer: action === 'install' ? row.label : `${row.label} ${action}`,
    target: `${row.command} on PortOS's PATH`,
  });
  const emit = (event) => { installLog.onEvent(event); send(event); };
  let child = null;
  let finished = false;
  let clientGone = false;
  let reservation = null;

  // Register before the availability probe. If the modal closes while the probe
  // is resolving, do not start work nobody can observe.
  onClientDisconnect(req, res, () => {
    clientGone = true;
    installLog.cancel();
    if (finished) return;
    if (child) stopRuntimeInstaller(child);
    if (reservation && actionInFlight === reservation) actionInFlight = null;
    safeEnd();
  });

  // Un-cached: the user may have just installed (or removed) this CLI in a
  // terminal, and a stale answer would run redundant or impossible work.
  const status = await getProviderRuntimeStatus(row.id, { fresh: true });
  if (clientGone) return safeEnd();
  if (status.installed && copy.skipWhenInstalled) {
    send({ type: 'log', message: `${status.label} is already available to PortOS.` });
    send({ type: 'complete', message: copy.skipWhenInstalled });
    return safeEnd();
  }
  if (!status.installed && !copy.skipWhenInstalled) {
    send({ type: 'error', message: `${status.label} is not installed on this host, so there is nothing to ${action}.` });
    return safeEnd();
  }
  // `installable` gates the tool an install/uninstall shells THROUGH (npm,
  // curl). A vendor self-updater runs the harness's own binary, which the
  // installed check above already proved runnable.
  const needsHostTool = action !== 'update' || !row.selfUpdate;
  if (needsHostTool && !status.installable) {
    send({ type: 'error', message: status.blockedReason || `PortOS cannot ${action} ${status.label} on this host.` });
    return safeEnd();
  }
  if (actionInFlight) {
    send({ type: 'error', message: 'Another harness install is already running. Wait for it to finish or restart PortOS.' });
    return safeEnd();
  }

  // Reserve synchronously before spawning so two requests that finish their
  // status probe together cannot launch competing writes into the same bin
  // directory.
  reservation = {};
  actionInFlight = reservation;
  if (clientGone) {
    actionInFlight = null;
    return safeEnd();
  }

  send({ type: 'stage', stage: action, message: `${copy.verb} ${status.label}.` });
  emit({ type: 'log', message: `Running ${describeRuntimeInstall(row.id, action)}.` });
  installLog.start();
  // `spawn` can throw synchronously (a rejected argv shape, an OS-level spawn
  // refusal). Two things must happen here that letting it bubble would not do:
  // release the reservation — or every later action answers "another install is
  // already running" until PortOS restarts — and report the failure as a
  // terminal SSE frame, since the headers are already flushed and the error
  // middleware can no longer send JSON to this response.
  try {
    child = spawnRuntimeInstaller(row.id, { action });
  } catch (err) {
    finished = true;
    if (actionInFlight === reservation) actionInFlight = null;
    emit({ type: 'error', message: `${status.label} ${copy.noun} failed to start: ${err.message}` });
    return safeEnd();
  }
  actionInFlight = child;

  const onLine = (line) => {
    const text = line.trimEnd();
    if (text) emit({ type: 'log', message: text });
  };
  // npm runs with `--no-progress`, which suppresses its usual redraws. Keep the
  // default newline-only reader as a defensive second layer: a lifecycle child
  // (or a vendor script's own progress bar) that still writes bare carriage
  // returns cannot turn every redraw into a browser log frame and a full modal
  // re-render.
  const stdoutReader = createLineReader(onLine);
  const stderrReader = createLineReader(onLine);
  child.stdout.on('data', stdoutReader.push);
  child.stderr.on('data', stderrReader.push);
  child.on('error', (err) => {
    if (finished) return;
    finished = true;
    if (actionInFlight === child) actionInFlight = null;
    emit({ type: 'error', message: `${status.label} ${copy.noun} failed to start: ${err.message}` });
    safeEnd();
  });
  child.on('close', async (code) => {
    if (finished) return;
    try {
      stdoutReader.flush();
      stderrReader.flush();
      finished = true;
      if (actionInFlight === child) actionInFlight = null;
      // The post-action PATH check is deliberately stronger than the exit code.
      // A successful write whose bin directory is absent from PM2's PATH would
      // otherwise recreate the same opaque agent-start failure — and for a
      // removal, "npm said ok" is not the same as "PortOS can no longer run it".
      //
      // `fresh` is load-bearing: the pre-action probe cached this runtime's
      // availability seconds ago, and re-reading it would report the state the
      // action just changed.
      const after = await getProviderRuntimeStatus(row.id, { fresh: true });
      emit(terminalFrame({ action, code, status: after, copy, command: row.command, before: status.version }));
      safeEnd();
    } catch (err) {
      // Child-process completion runs outside Express's request lifecycle.
      console.error(`❌ ${status.label} ${action} completion check failed: ${err.message}`);
      emit({ type: 'error', message: `${status.label} ${action} completion check failed: ${err.message}` });
      safeEnd();
    }
  });
}

/**
 * The one terminal SSE frame an action ends on, decided from the exit code AND
 * the re-probed availability.
 */
function terminalFrame({ action, code, status, copy, command, before }) {
  if (code !== 0) {
    return { type: 'error', message: `${status.label} ${copy.noun} exited with code ${code}.` };
  }
  if (action === 'uninstall') {
    return status.installed
      ? { type: 'error', message: `The uninstall finished, but PortOS can still run \`${command}\`. Another copy is on this machine's PATH — one installed by Homebrew or a vendor script, which PortOS did not write and will not delete.` }
      : { type: 'complete', message: `${status.label} has been removed. Providers that used it will show as needing setup.` };
  }
  if (!status.installed) {
    return { type: 'error', message: `The ${copy.noun} finished, but PortOS still cannot run \`${command}\`. npm wrote it to a bin directory that is not on this machine's PATH — run \`npm prefix -g\` in a terminal, add that directory (plus \`/bin\` off Windows) to your PATH, then restart PortOS.` };
  }
  const version = status.version ? ` (${status.version})` : '';
  if (action !== 'update') {
    return { type: 'complete', message: `${status.label} is installed and available to PortOS${version}.` };
  }
  // Report what the version actually DID, never "up to date" from an exit code
  // alone. A vendor updater that exits 0 without touching the copy on PATH would
  // otherwise claim currency in the modal while the row behind it still shows
  // the Update-available badge against the published version — two contradictory
  // claims on one screen. A version we could not read on either side says so.
  if (!status.version || !before) {
    return { type: 'complete', message: `${status.label} updater finished. PortOS could not read a version to compare.` };
  }
  return status.version === before
    ? { type: 'complete', message: `${status.label} updater finished and left it on ${before} — that is the newest ${command} can reach itself. If a newer release exists, install it the way this copy was installed.` }
    : { type: 'complete', message: `${status.label} updated: ${before} → ${status.version}.` };
}