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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
/**
* Where `npm install --global` actually writes its executables.
*
* The AI Providers page installs a CLI with a fixed `npm install --global` and
* then asks whether PortOS can run it. Those two questions have different
* answers on any host whose npm prefix is not the directory the platform's Node
* installer put on PATH: a machine-wide Windows prefix while PATH still carries
* the per-user `%APPDATA%\npm` default, an `NPM_CONFIG_PREFIX` an admin set, an
* nvm/Volta switch, a `prefix=` in a user or global npmrc. The install writes a
* perfectly good `codex.cmd` and nothing on PATH names the directory holding
* it — so the card reported "the installer finished, but PortOS still cannot
* run `codex`" and advised a restart, which cannot fix a directory the machine
* PATH has never contained.
*
* npm resolves its prefix through a config cascade (cli flags, `npm_config_*`
* env, project/user/global npmrc, and a builtin npmrc that itself interpolates
* env vars), so re-deriving it from `%APPDATA%`/`$HOME` guesses would just
* reproduce the same class of bug on the next host. The only correct answer is
* npm's own, hence one cached `npm prefix -g`.
*
* `adoptPathDirs` does the rest; see its docstring in `processEnv.js` for why
* extending `process.env.PATH` is what a bare-name node-pty launch needs.
*/
import { existsSync } from 'fs';
import { join } from 'path';
import { mkdtempSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { bufferedSpawn, prepareCliSpawn } from './bufferedSpawn.js';
import { adoptPathDirs, safeChildProcessEnv } from './processEnv.js';
const IS_WIN = process.platform === 'win32';
// `npm prefix -g` reads config files and can pay a cold Node start, so it gets
// more room than the 5s PATH probes — but it must never hang a status refresh.
const PREFIX_TIMEOUT_MS = 15_000;
// npm's answer, held as a promise so concurrent callers share one spawn: a host
// does not change its global prefix underneath a running server.
let binDirProbe = null;
/** One `npm prefix -g`, mapped to the platform's global bin directory. */
async function probeNpmGlobalBinDir(spawnImpl) {
// npm is itself a large Node CLI that writes its OWN module compile cache
// under `TMPDIR`/`node-compile-cache` on every invocation (same class of
// problem `commandExists.js`'s `probe()` isolates for `kilo`/`opencode` —
// see its docstring, #9039). A throwaway scratch dir scoped to THIS one
// spawn keeps that cache out of the caller's real `TMPDIR` (and, under
// PortOS's own run-scoped vitest temp root, out of the leak report).
const scratchDir = mkdtempSync(join(tmpdir(), 'portos-cli-probe-'));
const env = { ...safeChildProcessEnv(), TMPDIR: scratchDir, TMP: scratchDir, TEMP: scratchDir };
try {
// `shell: false` + `prepareCliSpawn`, not `bufferedSpawn`'s `needsShell('npm')`
// default: that default is `shell: true` with an args array, which node
// space-joins WITHOUT escaping (DEP0190). The argv here is fixed, but the
// warning would print at every boot in both processes.
const { command, args } = prepareCliSpawn('npm', ['prefix', '-g'], env);
const { stdout } = await spawnImpl(command, args, { env, shell: false, timeoutMs: PREFIX_TIMEOUT_MS });
const prefix = String(stdout || '').trim().split(/\r?\n/)[0]?.trim() || '';
// Windows drops binaries straight in the prefix; POSIX uses `<prefix>/bin`.
return prefix ? (IS_WIN ? prefix : join(prefix, 'bin')) : null;
} finally {
try {
rmSync(scratchDir, { recursive: true, force: true });
} catch {
// Best-effort — a lingering handle on a still-terminating npm must not
// throw out of a probe that already has its answer.
}
}
}
/**
* Put npm's global bin directory on this process's PATH, so a CLI installed
* there is both discoverable and launchable by bare name. Idempotent, and a
* no-op when npm cannot be asked or the directory is not there yet.
*
* The existence check is deliberately NOT cached with npm's answer: the prefix
* directory does not exist until the first global install, and making that
* install visible without a restart is the whole point.
*
* @param {{spawnImpl?: Function}} [deps]
* @returns {Promise<string|null>} the directory now on PATH, or `null`
*/
export async function adoptNpmGlobalBinDir({ spawnImpl = bufferedSpawn } = {}) {
// A probe that cannot answer resolves null rather than rejecting: an
// unreachable npm means "PortOS keeps the PATH it has", not a failed caller.
binDirProbe = binDirProbe || probeNpmGlobalBinDir(spawnImpl).catch(() => null);
const dir = await binDirProbe;
if (!dir || !existsSync(dir)) return null;
const [adopted] = adoptPathDirs([dir]);
if (adopted) console.log(`🔗 Adopted npm global bin directory onto PortOS's PATH: ${adopted}`);
return dir;
}
/** Test-only: forget npm's answer so the next read re-probes. */
export function __resetNpmGlobalBinCache() {
binDirProbe = null;
}