@underpostnet/cyberia 3.3.0 → 3.3.73

package/src/server/runtime/config-scope.js

@@ -0,0 +1,215 @@
+/**
+ * Ownership of configuration keys, and the projections that carry a value out of its owner.
+ *
+ * The platform's domains are `app`, `host`, `secret` and `state`; this module does not add a
+ * fifth. What it adds is the missing half of the host domain's model: its durable source is one
+ * env file, but the values in it answer to different concerns with different consumers and very
+ * different blast radii. Provisioning credentials, registry credentials and the cron jobs' own
+ * connection settings were reaching every workload that read that file, because "the host
+ * environment" was the only granularity the system had.
+ *
+ * Ownership and visibility are separate questions, and only ownership is answered by pattern.
+ *
+ * {@link CONFIG_OWNERSHIP} says where a key lives. A family pattern is right for that: a new
+ * `MAAS_` key is a provisioning key wherever it came from.
+ *
+ * {@link SCOPE_ENTITLEMENTS} says what a workload may read, and is an exact key list. A pattern
+ * there would mean the next credential added to a family silently inherits that family's audience
+ * — `GITHUB_NEW_SENSITIVE_TOKEN` becoming cron-visible because `GITHUB_` once was. So the policy
+ * is readable from the table alone: what cron can see is what the table names, and nothing a
+ * naming convention implies.
+ *
+ * Classification is closed at both ends: {@link classifyConfigKeys} reports anything it cannot
+ * place instead of defaulting it into a scope, and an entitlement the table does not name is
+ * refused. An unknown key is a design question, not a value to guess at.
+ *
+ * @module src/server/runtime/config-scope.js
+ * @namespace ConfigScope
+ */
+
+/**
+ * @constant CONFIG_SCOPES
+ * @description The scopes a configuration key can belong to, and what consumes each.
+ * @memberof ConfigScope
+ */
+const CONFIG_SCOPES = Object.freeze({
+  runtime: 'Process settings a manifest states about a workload; never carried by a projection.',
+  host: 'Node-level operation: the edge, the observability stack, cluster mail and deployment targets.',
+  cron: 'The scheduled jobs: their APIs, their DNS providers and the connection they reach the fleet on.',
+  baremetal: 'Machine provisioning: MAAS, its database, and the network a commissioned node boots on.',
+  publishing: 'Release identities: the registries and package indexes a publish authenticates to.',
+  app: "A deployment's own runtime: its database, its sessions, its integrations.",
+});
+
+/**
+ * @constant CONFIG_OWNERSHIP
+ * @description Key patterns in resolution order, each naming its owner and the scopes it is
+ * projected into. First match wins, so a specific rule is placed above the family it narrows.
+ * @memberof ConfigScope
+ */
+const CONFIG_OWNERSHIP = Object.freeze([
+  { match: /^(NODE_ENV|NODE_OPTIONS|DOTENV_CONFIG_QUIET|ENABLE_FILE_LOGS|TIME_ZONE)$/, owner: 'runtime' },
+
+  { match: /^(VULTR_|DDNS_|HTTP_PLAIN_IP_URL$)/, owner: 'cron' },
+
+  { match: /^(MAAS_|DB_PG_MAAS_)/, owner: 'baremetal' },
+  { match: /^(TFTP_ROOT|NETMASK|NFS_EXPORT_PATH)$/, owner: 'baremetal' },
+
+  { match: /^(NPM_|DOCKER_HUB_|POSTMAN_)/, owner: 'publishing' },
+
+  { match: /^(GITHUB_|DEFAULT_SSH_|FORWARD_PROXY_|DEFAULT_DEPLOY_)/, owner: 'host' },
+  { match: /^(GF_SECURITY_|CLUSTER_MAILER_)/, owner: 'host' },
+  { match: /^UNDERPOST_EVENT_TOKEN$/, owner: 'host' },
+
+  { match: /^(DB_|MARIADB_|VALKEY_)/, owner: 'app' },
+  { match: /^(JWT_SECRET|ACCESS_EXPIRE_MINUTES|REFRESH_EXPIRE_MINUTES|PORT|DEPLOY_ID)$/, owner: 'app' },
+  { match: /^(DEFAULT_ADMIN_|CLOUDINARY_|WP_)/, owner: 'app' },
+  { match: /^(GEMINI_API_KEY|NVIDIA_API_KEY)$/, owner: 'app' },
+]);
+
+/**
+ * @constant SCOPE_ENTITLEMENTS
+ * @description Exactly what each workload scope may read, by key name.
+ *
+ * Every entry is a key some code in this repository reads. A value the workload does not consume
+ * is not listed, because projecting one is not merely waste: `*_SSH_KEY_PATH` named a path that
+ * only exists on a host, and handing it to a pod made the resolver prefer it over the Secret
+ * mount holding the actual key.
+ * @memberof ConfigScope
+ */
+const SCOPE_ENTITLEMENTS = Object.freeze({
+  cron: Object.freeze([
+    // vultr: the API it meters against, and the edge it toggles egress on.
+    'VULTR_API_KEY',
+    'VULTR_INSTANCE_ID',
+    'VULTR_BANDWIDTH_THRESHOLD',
+    'VULTR_VPS_IP',
+    'VULTR_SSH_USER',
+    'VULTR_SSH_PORT',
+    'FORWARD_PROXY_API_KEY',
+    'FORWARD_PROXY_HOST',
+    'FORWARD_PROXY_PORT',
+    // backup and vultr: the connection out of the pod. The key itself is a Secret volume.
+    'DEFAULT_SSH_USER',
+    'DEFAULT_SSH_HOST',
+    'DEFAULT_SSH_PORT',
+    // backup: the identity its git operations authenticate as.
+    'GITHUB_TOKEN',
+    'GITHUB_USERNAME',
+    // dns: the provider it updates and the host it probes.
+    'DDNS_HOST',
+    'DDNS_PROVIDER',
+    'DDNS_API_KEY',
+    'DDNS_USER',
+    'HTTP_PLAIN_IP_URL',
+    'DEFAULT_DEPLOY_HOST',
+  ]),
+});
+
+/**
+ * The owning scope of a key, and the scopes it reaches.
+ * @param {string} key - Environment variable name.
+ * @returns {{owner: string, projectedTo: string[]}|null} Ownership, or null when unclassified.
+ * @memberof ConfigScope
+ */
+const configOwnershipFactory = (key) => {
+  const name = `${key || ''}`;
+  const rule = CONFIG_OWNERSHIP.find((entry) => entry.match.test(name));
+  if (!rule) return null;
+  const projectedTo = Object.entries(SCOPE_ENTITLEMENTS)
+    .filter(([scope, keys]) => scope !== rule.owner && keys.includes(name))
+    .map(([scope]) => scope);
+  return { owner: rule.owner, projectedTo };
+};
+
+/**
+ * Whether a scope receives a key.
+ *
+ * A scope with an entitlement list reads that list and nothing else — owning a key is not by
+ * itself permission to ship it to a workload, which is what keeps a new member of an owned family
+ * from arriving in a pod unreviewed. Scopes without a list are host-side and read what they own.
+ *
+ * `runtime` is never a pass-through: process settings are what a manifest states about the
+ * workload it defines, not credentials a projection carries.
+ * @param {string} key - Environment variable name.
+ * @param {string} scope - Scope name.
+ * @returns {boolean} True when the scope may see the key.
+ * @memberof ConfigScope
+ */
+const scopeReceivesKey = (key, scope) => {
+  const ownership = configOwnershipFactory(key);
+  if (!ownership) return false;
+  const entitlement = SCOPE_ENTITLEMENTS[scope];
+  if (entitlement) return entitlement.includes(`${key || ''}`);
+  return ownership.owner === scope;
+};
+
+/**
+ * Splits an environment into the scopes that receive each key.
+ *
+ * `unclassified` is the fail-closed half: a key no rule places is reported rather than dropped
+ * into a default scope, because the two wrong answers — hiding it from a consumer that needs it,
+ * or handing a credential to a workload that does not — are both silent.
+ * @param {Object<string, string>} values - Parsed environment.
+ * @returns {{scopes: Object<string, string[]>, unclassified: string[]}} Key names per scope.
+ * @memberof ConfigScope
+ */
+const classifyConfigKeys = (values = {}) => {
+  const scopes = Object.fromEntries(Object.keys(CONFIG_SCOPES).map((scope) => [scope, []]));
+  const unclassified = [];
+
+  for (const key of Object.keys(values)) {
+    const ownership = configOwnershipFactory(key);
+    if (!ownership) {
+      unclassified.push(key);
+      continue;
+    }
+    scopes[ownership.owner].push(key);
+  }
+
+  return { scopes, unclassified };
+};
+
+/**
+ * The subset of an environment a scope is entitled to.
+ * @param {Object<string, string>} values - Parsed environment.
+ * @param {string} scope - Scope name.
+ * @returns {Object<string, string>} Entitled key/value pairs.
+ * @memberof ConfigScope
+ */
+const scopeValuesFactory = (values = {}, scope = '') =>
+  Object.fromEntries(Object.entries(values).filter(([key]) => scopeReceivesKey(key, scope)));
+
+/**
+ * Renders a scope rejection without disclosing the value that caused it.
+ * @param {object} params - Rejection context.
+ * @param {string} params.domain - Domain reporting the rejection.
+ * @param {string} [params.deployId] - Deploy the source belongs to.
+ * @param {string} [params.env] - Environment selector.
+ * @param {string} params.key - Key that was rejected.
+ * @param {string} params.reason - Why it was rejected.
+ * @returns {string} Diagnostic line, values omitted by construction.
+ * @memberof ConfigScope
+ */
+const configRejectionFactory = ({ domain, deployId = '', env = '', key, reason }) =>
+  [
+    'configuration source rejected:',
+    `domain=${domain}`,
+    deployId ? `deploy=${deployId}` : '',
+    env ? `env=${env}` : '',
+    `key=${key}`,
+    `reason=${reason}`,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+export {
+  CONFIG_OWNERSHIP,
+  CONFIG_SCOPES,
+  SCOPE_ENTITLEMENTS,
+  classifyConfigKeys,
+  configOwnershipFactory,
+  configRejectionFactory,
+  scopeReceivesKey,
+  scopeValuesFactory,
+};

package/src/server/runtime/environment.js

@@ -0,0 +1,149 @@
+/**
+ * Environment and global installation path resolution.
+ * @module src/server/runtime/environment.js
+ * @namespace ServerEnvironment
+ */
+'use strict';
+
+import dotenv from 'dotenv';
+import fs from 'fs-extra';
+import { execFileSync } from 'node:child_process';
+import nodePath from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loggerFactory } from '../ops/logger.js';
+
+const logger = loggerFactory(import.meta);
+
+/**
+ * Node directory backing every hostPath PersistentVolume the deploy flow
+ * materializes (`<root>/<pv id>`), including the shared gateway's static tree.
+ * Cluster bring-up gives it the shared container label, because the pods that
+ * read these documents are unprivileged.
+ * @constant {string}
+ * @memberof ServerEnvironment
+ */
+const HOST_VOLUME_ROOT = '/home/dd/engine/volume';
+const packageRoot = nodePath.resolve(nodePath.dirname(fileURLToPath(import.meta.url)), '../../..');
+const envFileCache = new Map();
+let rootEnvPath;
+
+/**
+ * Resolves the global npm module directory.
+ * @returns {string}
+ * @memberof ServerEnvironment
+ */
+const getNpmRootPath = () => {
+  try {
+    return execFileSync('npm', ['root', '-g'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return '';
+  }
+};
+
+/**
+ * Resolves the global Underpost installation directory.
+ * @returns {string}
+ * @memberof ServerEnvironment
+ */
+const getUnderpostRootPath = () => {
+  const npmRoot = getNpmRootPath();
+  return npmRoot ? `${npmRoot}/underpost` : `${packageRoot}/.underpost`;
+};
+
+const readEnvFile = (path) => {
+  if (envFileCache.has(path)) return envFileCache.get(path);
+  let values = {};
+  try {
+    if (path && fs.existsSync(path)) values = dotenv.parse(fs.readFileSync(path, 'utf8'));
+  } catch (error) {
+    logger.warn('Ignoring unreadable env file', { target: path, message: error.message });
+  }
+  envFileCache.set(path, values);
+  return values;
+};
+
+const environmentValueFactory = (key) => {
+  const processValue = `${process.env[key] ?? ''}`.trim();
+  if (processValue) return processValue;
+
+  if (rootEnvPath === undefined) {
+    const underpostRoot = getUnderpostRootPath();
+    rootEnvPath = underpostRoot ? `${underpostRoot}/.env` : '';
+  }
+
+  for (const path of ['./.env', rootEnvPath]) {
+    const value = `${readEnvFile(path)[key] ?? ''}`.trim();
+    if (value) return value;
+  }
+  return '';
+};
+
+/**
+ * Single source of truth for resolving a deployment environment name from CLI options.
+ * Explicit `--env` always wins; `--dev` is the development shorthand; otherwise the
+ * caller's `fallback` decides. Deliberately does not read `process.env.NODE_ENV`, so a
+ * developer shell that exports it cannot silently retarget a deploy — callers whose
+ * contract is ambient (the client build) pass it in as `fallback` themselves.
+ * @method deployEnvFactory
+ * @param {object} [options] - CLI options carrying the environment selection.
+ * @param {string} [options.env] - Explicit environment name.
+ * @param {boolean} [options.dev] - Development context shorthand.
+ * @param {string} [fallback='production'] - Value when no option selects an environment.
+ * @returns {string} `development` | `production` | `test` | custom env name.
+ * @memberof ServerEnvironment
+ */
+const deployEnvFactory = (options = {}, fallback = 'production') => {
+  const explicit = `${options?.env ?? ''}`.trim();
+  if (explicit) return explicit;
+  if (options?.dev === true) return 'development';
+  return fallback;
+};
+
+/**
+ * Renders environment values as dotenv file contents.
+ * @method renderEnv
+ * @param {Object<string, *>} envObj - Environment values keyed by variable name.
+ * @returns {string} Dotenv text, one `KEY=value` per line.
+ * @memberof ServerEnvironment
+ */
+const renderEnv = (envObj) =>
+  Object.keys(envObj)
+    .map((key) => `${key}=${envObj[key]}`)
+    .join('\n');
+
+/**
+ * Writes environment values as a dotenv file.
+ * @method writeEnv
+ * @param {string} envPath - Destination file path.
+ * @param {Object<string, *>} envObj - Environment values keyed by variable name.
+ * @returns {void}
+ * @memberof ServerEnvironment
+ */
+const writeEnv = (envPath, envObj) => fs.writeFileSync(envPath, renderEnv(envObj), 'utf8');
+
+/**
+ * Whether this process runs inside an OCI container image, by Kubernetes service injection or
+ * Docker's marker file.
+ *
+ * Lives in this module because it is an environment fact two unrelated concerns read: the
+ * container runtime state store ({@link UnderpostState.isInsideContainer}, which re-exports it)
+ * and the OCI env overlay {@link ServerConfBuilder.deployEnvContentFactory} resolves.
+ * @method isOciRuntime
+ * @returns {boolean} True when running inside a container.
+ * @memberof ServerEnvironment
+ */
+const isOciRuntime = () => !!process.env.KUBERNETES_SERVICE_HOST || fs.existsSync('/.dockerenv');
+
+export {
+  deployEnvFactory,
+  environmentValueFactory,
+  getNpmRootPath,
+  getUnderpostRootPath,
+  HOST_VOLUME_ROOT,
+  isOciRuntime,
+  renderEnv,
+  writeEnv,
+};

package/src/server/{process.js → runtime/process.js}

@@ -17,14 +17,18 @@
  *     `ProcessController.children` so SIGINT/SIGTERM forwarding can reach
  *     them before the parent exits.
  *
- * @module src/server/process.js
+ * @module src/server/runtime/process.js
  * @namespace Process
  */
 // https://nodejs.org/api/process
 import shell from 'shelljs';
-import { loggerFactory } from './logger.js';
+import fs from 'fs-extra';
+import nodePath from 'node:path';
+import { loggerFactory, redactSensitiveText } from '../ops/logger.js';
 import clipboard from 'clipboardy';
-import Underpost from '../index.js';
+import Underpost from '../../index.js';
+import { latchRuntimeError } from './runtime-status.js';
+import { executionDecisionFactory } from '../build/execution.js';
 const logger = loggerFactory(import.meta);
 /**
  * Gets the current working directory, replacing backslashes with forward slashes for consistency.
@@ -140,16 +144,26 @@ class ProcessController {
   }
 }
 /**
- * `ShellExecError` — thrown by `shellExec` when the underlying command
- * exits with a non-zero code (the default fail-fast behaviour). Carries
- * the exit code, stdout, and stderr for inspection by callers / CI
- * pipelines that need structured failure data.
+ * Quotes one value as a single shell argument.
+ *
+ * Single source of that quoting: a composed command reaches `sh -c`, so any
+ * value carrying spaces, commas or quotes has to survive one more parse than
+ * the caller wrote it for. Single quotes are literal in POSIX shells, and an
+ * embedded single quote is closed, escaped and reopened.
+ * @memberof Process
+ * @param {*} value - Value to pass as one argument.
+ * @returns {string} The value, quoted.
+ */
+const shellArgumentFactory = (value) => `'${`${value ?? ''}`.replaceAll("'", `'\\''`)}'`;
+
+/**
+ * Error thrown by `shellExec` on a non-zero exit, with structured process output.
  */
 class ShellExecError extends Error {
   constructor(cmd, code, stdout, stderr) {
-    super(`shellExec failed (exit=${code}): ${cmd}`);
+    super(`shellExec failed (exit=${code}): ${redactSensitiveText(cmd)}`);
     this.name = 'ShellExecError';
-    this.cmd = cmd;
+    this.cmd = redactSensitiveText(cmd);
     this.code = code;
     this.stdout = stdout;
     this.stderr = stderr;
@@ -180,8 +194,46 @@ class ShellExecError extends Error {
  * @returns {string|shelljs.ShellString} `ShellString` by default; the stdout string when `stdout: true`.
  * @throws {ShellExecError} On non-zero exit when `silentOnError` is not set.
  */
+/**
+ * The result a denied read hands back.
+ *
+ * Shaped as a `ShellString` so an elided command is indistinguishable from one that ran
+ * and found nothing — which is the answer the `silentOnError` call sites already handle.
+ * @returns {shelljs.ShellString} Empty successful result.
+ * @memberof Process
+ */
+const neutralShellResult = () => {
+  const result = shell.ShellString('');
+  result.code = 0;
+  result.stdout = '';
+  result.stderr = '';
+  return result;
+};
+
+/**
+ * Applies the active execution profile to one command.
+ *
+ * This is the single gate the profile system rests on: because every external
+ * invocation reaches it, an offline stage needs no per-call-site opt-out.
+ * @param {string} cmd - The command about to run.
+ * @param {Object} options - The `shellExec` options.
+ * @returns {null|{elided: true, result: *}} `null` when the command may run.
+ * @memberof Process
+ */
+const executionGate = (cmd, options) => {
+  const decision = executionDecisionFactory(cmd);
+  if (decision.permitted) return null;
+  logger.info(`[${decision.profile}] elided ${decision.capability}`, redactSensitiveText(cmd));
+  return { elided: true, result: options.stdout ? '' : neutralShellResult() };
+};
+
 const shellExec = (cmd, options = {}) => {
-  if (!options.disableLog) logger.info(`cmd`, cmd);
+  const gated = executionGate(cmd, options);
+  if (gated) {
+    if (options.callback) return options.callback(0, '', '');
+    return gated.result;
+  }
+  if (!options.disableLog) logger.info(`cmd`, redactSensitiveText(cmd));
 
   // Whitelist exactly the keys `shelljs.exec` understands. Passing our own
   // bookkeeping keys through (or a literal `cwd: undefined`) makes shelljs
@@ -189,6 +241,7 @@ const shellExec = (cmd, options = {}) => {
   const shellOpts = {};
   if (options.silent !== undefined) shellOpts.silent = options.silent;
   if (options.async !== undefined) shellOpts.async = options.async;
+  if (options.env !== undefined) shellOpts.env = options.env;
 
   // Hermetic cwd. shelljs.cd mutates a process-wide global; instead we
   // snapshot the current cwd here, switch for the duration of this call,
@@ -200,7 +253,7 @@ const shellExec = (cmd, options = {}) => {
     try {
       process.chdir(options.cwd);
     } catch (err) {
-      if (Underpost.env.isInsideContainer()) Underpost.env.set('container-status', 'error')
+      latchRuntimeError();
       throw new ShellExecError(cmd, -1, '', `chdir(${options.cwd}) failed: ${err.message}`);
     }
   }
@@ -214,7 +267,7 @@ const shellExec = (cmd, options = {}) => {
     const result = shell.exec(cmd, shellOpts);
 
     if (!options.silentOnError && result && typeof result.code === 'number' && result.code !== 0) {
-      if (Underpost.env.isInsideContainer()) Underpost.env.set('container-status', 'error')
+      latchRuntimeError();
       throw new ShellExecError(cmd, result.code, result.stdout || '', result.stderr || '');
     }
 
@@ -229,6 +282,58 @@ const shellExec = (cmd, options = {}) => {
     }
   }
 };
+/**
+ * Runs a command as a child process and resolves when it exits, without blocking the event loop.
+ *
+ * Same contract as {@link shellExec}: a non-zero exit throws {@link ShellExecError} unless
+ * `silentOnError`, and `stdout` returns the captured output. The difference is that timers and
+ * sockets keep running while the child does — which is what lets the in-pod status endpoint
+ * answer during a build instead of going silent for its whole duration.
+ *
+ * @memberof Process
+ * @param {string} cmd - The command to run.
+ * @param {Object} [options] - Options.
+ * @param {boolean} [options.silent] - Suppress child output on the parent stdio.
+ * @param {boolean} [options.silentOnError] - Resolve instead of throwing on a non-zero exit.
+ * @param {boolean} [options.stdout] - Resolve with the captured stdout rather than the result.
+ * @param {boolean} [options.disableLog] - Suppress the command log line.
+ * @param {string} [options.cwd] - Directory to run in.
+ * @param {NodeJS.ProcessEnv} [options.env] - Environment passed only to the child process.
+ * @returns {Promise<*>} Resolves with the result, or the stdout when `stdout` is set.
+ */
+const shellExecAsync = (cmd, options = {}) =>
+  new Promise((resolve, reject) => {
+    const gated = executionGate(cmd, options);
+    if (gated) return resolve(options.stdout ? '' : { code: 0, stdout: '', stderr: '' });
+    if (!options.disableLog) logger.info(`cmd`, redactSensitiveText(cmd));
+    const shellOpts = { async: true };
+    if (options.silent !== undefined) shellOpts.silent = options.silent;
+    if (options.cwd) shellOpts.cwd = options.cwd;
+    if (options.env !== undefined) shellOpts.env = options.env;
+    shell.exec(cmd, shellOpts, (code, stdout, stderr) => {
+      if (code !== 0 && !options.silentOnError) {
+        latchRuntimeError();
+        return reject(new ShellExecError(cmd, code, stdout || '', stderr || ''));
+      }
+      resolve(options.stdout ? stdout : { code, stdout, stderr });
+    });
+  });
+
+/**
+ * Blocks the calling thread for `ms` milliseconds.
+ *
+ * Retry backoff around the synchronous `shellExec` chains (kubectl exec, pod
+ * readiness polling) has no async boundary to await on, so the wait has to
+ * block. `Atomics.wait` keeps the CPU idle instead of spinning.
+ *
+ * @memberof Process
+ * @param {number} ms - Milliseconds to block for. Non-positive values are a no-op.
+ * @returns {void}
+ */
+const sleepSync = (ms) => {
+  if (!(typeof ms === 'number') || !(ms > 0)) return;
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+};
 /**
  * Changes the current working directory using shelljs.
  *
@@ -258,6 +363,38 @@ const shellCd = (cd, options = { disableLog: false }) => {
  * @returns {string} The shell command string for the daemon process.
  */
 const daemonProcess = (cmd) => `exec bash -c '${cmd}; exec tail -f /dev/null'`;
+
+/**
+ * Installs a root-owned host file at an explicit mode, reporting whether it changed.
+ *
+ * Staged then installed rather than written in place: the caller may run
+ * unprivileged while the destination is root-owned, and `install -m` sets the
+ * mode as it copies, so a 0600 file is never briefly readable at the default
+ * umask. Returning the changed flag is what lets callers restart a service only
+ * when its unit actually differs.
+ *
+ * @param {object} params
+ * @param {string} params.target - Destination path.
+ * @param {string} params.content - File contents.
+ * @param {string} [params.mode] - Octal mode.
+ * @param {boolean} [params.dryRun] - Report the destination instead of writing.
+ * @returns {boolean} True when the file changed.
+ * @memberof ProcessService
+ */
+const installRootFile = ({ target, content, mode = '0644', dryRun = false }) => {
+  const current = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : null;
+  if (current === content) return false;
+  if (dryRun) {
+    logger.info(`[dry-run] write ${target} (mode ${mode})`, { bytes: content.length });
+    return true;
+  }
+  const staged = nodePath.join('/tmp', `underpost-root-file-${nodePath.basename(target)}-${process.pid}`);
+  fs.writeFileSync(staged, content, { mode: 0o600 });
+  shellExec(`sudo mkdir -p ${nodePath.dirname(target)}`, { silent: true });
+  shellExec(`sudo install -m ${mode} -o root -g root ${staged} ${target}`, { silent: true });
+  fs.removeSync(staged);
+  return true;
+};
 /**
  * Retrieves the process ID (PID) of the most recently created gnome-terminal instance.
  * Note: This function is environment-specific (GNOME/Linux) and uses `pgrep -n`.
@@ -287,11 +424,15 @@ function pbcopy(data) {
   logger.info(`copied to clipboard`, clipboard.readSync());
 }
 export {
+  installRootFile,
   ProcessController,
   ShellExecError,
   getRootDirectory,
+  shellArgumentFactory,
   shellExec,
+  shellExecAsync,
   shellCd,
+  sleepSync,
   pbcopy,
   getTerminalPid,
   daemonProcess,