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

permissions — what this run may reach

Fixed at launch by esrun's denial 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 under --deny-all 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).

Errors