runtime:process

Host process information: environment, arguments, working directory, platform, signals, and exit. Aligned in spirit with the WinterTC CLI-API proposal.

Import

import { env, args, platform, arch, cwd, exit, unmask } from "runtime:process";

// Or the default aggregate:
import process from "runtime:process";

Exports

env — reading and writing

import { env } from "runtime:process";

console.log(env.HOME);      // read
env.FEATURE_FLAG = "on";    // write (in-process only)
delete env.SECRET;          // delete (in-process only)

args — program arguments

// esrun app.js build --watch
import { args } from "runtime:process";

console.log(args); // ["build", "--watch"]

signals — graceful shutdown

Watching a signal suppresses its default action, which is what lets a SIGTERM drain instead of kill.

import { onSignal, offSignal } from "runtime:process";

const shutdown = async (signal) => {
  offSignal(signal, shutdown);   // a second ^C should kill, not queue
  await server.stop();
};
onSignal("SIGINT", shutdown);
onSignal("SIGTERM", shutdown);

exit — stopping the run

import { exit } from "runtime:process";

if (failed) exit(1); // records the code and halts immediately
exit();              // defaults to 0

stdout — drawing on a terminal

console.log formats a value, appends a newline, and goes wherever the host pointed it. That is right for a log line and wrong for a display: a spinner is a carriage return and no newline, and a progress bar rewrites the line it is already on.

import { stdout } from "runtime:process";

if (stdout.isTTY) {
  stdout.write(`\r${bar(done / total, stdout.columns ?? 60)}`);
} else {
  console.log(`${done}/${total}`);
}

Ask isTTY before you draw. A spinner redrawn with \r into a log file is a file of spinner frames, and colour escapes in a pipe are noise in somebody's grep.

The size comes from the terminal, not from $COLUMNS — a shell exports that to itself rather than to a child, and it is stale the moment the window is dragged. Where the host cannot answer it says so rather than reporting a plausible 80.

Neither needs a capability, for the reason console.log does not: writing to the stream this program was started with reaches nothing it was not already handed, so --deny-all still leaves a program able to say what it is doing.

permissions — what this run may reach

Fixed at launch by esrun's permission flags, so has() is a synchronous boolean: there is nothing to request and no prompt to await.

import { permissions } from "runtime:process";

permissions.denied; // ["read", "write"] — [] when nothing is denied
permissions.has("net"); // true

if (permissions.has("write")) await fs.write("cache.json", data);

PermissionName is "read", "write", "imports", "net", "listen", "env", "run", "signals" — the same words the --deny-<name> flags use. Needs no capability, so it answers with everything denied too.

A scoped grant reports true: --allow-env=PORT grants the env capability and narrows what it yields, so has("env") means "you may read an environment variable", not "you may read this one". The same holds for --allow-net=<hosts> and the rest.

There is no per-value form — has("read", "/etc/passwd") throws. Which paths and hosts are allowed is set by the deployment, not asked about by the application, and the exact answer for one value is to make the call and catch ERR_PERMISSION_DENIED. A path is judged after the runtime resolves it, so an answer given in advance could be stale by the time the call happens.

Secrets — masked by default

Secret-bearing keys are exposed as a Secret that renders as [redacted] in console, strings, and JSON. A key qualifies if it ends in _KEY, _TOKEN, _SECRET, _PASS(WORD), or contains CREDENTIAL/AUTH.

import { env, unmask } from "runtime:process";

// Keys ending in *_SECRET(S) / *_PASSWORD(S) are masked by default.
console.log(env.DB_PASSWORD);        // [redacted]
console.log(`${env.DB_PASSWORD}`);   // [redacted]
JSON.stringify(env);                 // ..."DB_PASSWORD":"[redacted]"...

const pw = unmask(env.DB_PASSWORD);  // real value, explicit
unmask(env.DB_HOST);                 // plain strings pass through

Load values from a file with esrun --env-file=.env (no auto-discovery; the OS environment wins unless --env-override is passed).

Reporting on yourself

import { cpuTime, memoryUsage, uptime } from "runtime:process";

const { heapUsed, heapLimit } = memoryUsage();
if (heapLimit - heapUsed < 32 * 1024 * 1024) shedLoad();

heapLimit - heapUsed is real headroom: exceed it and the heap guard ends this agent. Per isolate, so a worker answers for itself:

// in a worker started with { memory: 64 }
memoryUsage().heapLimit;   // 67108864, not the parent's
cpuTime();                 // CPU burned by *this worker's* thread
uptime();                  // ms since *this worker* started

uptime() is not performance.now(). A worker is handed its parent's clock, so performance.now() counts from when the process's runtime was built and reads the same in every agent.

Utilisation is two reads and a division:

const [cpu0, t0] = [cpuTime(), uptime()];
await work();
const busy = (cpuTime() - cpu0) / (uptime() - t0);

cpuTime() is total CPU, not a user/system split. The split needs Mach on macOS, where a wrong struct layout is a memory-safety bug rather than a wrong number, so it is reported nowhere rather than on two platforms out of three.

Errors