@underpostnet/cyberia 3.3.0 → 3.3.73

package/src/runtime/wp/Wp.js

@@ -13,8 +13,8 @@
 
 import fs from 'fs-extra';
 import path from 'path';
-import { shellExec } from '../../server/process.js';
-import { loggerFactory } from '../../server/logger.js';
+import { shellExec } from '../../server/runtime/process.js';
+import { loggerFactory } from '../../server/ops/logger.js';
 import { Lampp } from '../lampp/Lampp.js';
 import Underpost from '../../index.js';
 
@@ -141,14 +141,7 @@ class WpService {
       ({ freshInstall } = WpService.provisionFresh({ host, siteRoot: wpDir, db, wp, subDir }));
     }
 
-    // Ensure git is initialized and linked to the backup repository.
-    // Mark the directory as safe before git operations — the site root is owned
-    // by daemon:daemon (Apache) and git 2.35+ refuses to run in directories owned
-    // by a different user unless explicitly declared safe.
-    if (repository) {
-      shellExec(`git config --global --add safe.directory "${wpDir}"`);
-      Underpost.repo.initLocalRepo({ path: wpDir, origin: repository });
-    }
+    if (repository) Underpost.repo.initLocalRepo({ path: wpDir, origin: repository });
 
     // Write a root .htaccess that rewrites / → /subDir/ when running in subdirectory mode
     if (subDir) {
@@ -187,9 +180,9 @@ class WpService {
   }
 
   /**
-   * Clone mode — clones `repository` into `siteRoot` if not present, then
-   * verifies `wp-config.php` exists.  If it is missing the site root is wiped
-   * and a fresh WordPress install is performed (requires `db` config).
+   * Clone mode — materializes `siteRoot` from `repository` via
+   * {@link UnderpostRepository.provisionSiteRoot}, then verifies `wp-config.php` exists.
+   * An unreachable remote or a checkout without `wp-config.php` falls back to a fresh install.
    * @param {object} opts
    * @param {string}      opts.host       - Virtual-host name (for logging).
    * @param {string}      opts.siteRoot   - Absolute path where the site should live.
@@ -197,37 +190,11 @@ class WpService {
    * @param {object|null} [opts.db]       - MariaDB config used as fallback for fresh install.
    */
   static provisionClone({ host, siteRoot, repository, db, wp, subDir = '' }) {
-    if (!process.env.GITHUB_TOKEN && repository && repository.startsWith('https://github.com/')) {
-      logger.warn(`${host}: GITHUB_TOKEN not set — git operations will fail for private repositories`);
-    }
-
-    // Step 0 — verify the remote repository is reachable; fall back to fresh install if not.
-    // repository.js isRemoteRepo handles token injection internally.
-    const repoAccessible = Underpost.repo.isRemoteRepo(repository);
-    logger.info(`${host}: remote accessible = ${repoAccessible} (${repository})`);
-    if (!repoAccessible) {
-      logger.warn(`${host}: remote repository not accessible (${repository}) — running fresh install`);
-      return WpService.provisionFresh({ host, siteRoot, db, wp, subDir });
-    }
+    const { accessible } = Underpost.repo.provisionSiteRoot({ host, siteRoot, repository });
+    if (!accessible) return WpService.provisionFresh({ host, siteRoot, db, wp, subDir });
 
-    // Step 1 — clone if the directory does not exist yet
-    if (!fs.existsSync(siteRoot)) {
-      logger.info(`${host}: cloning ${repository} → ${siteRoot}`);
-      const cloneUrl = Underpost.repo.resolveAuthUrl(repository);
-      const tmp = `${siteRoot}.tmp`;
-      if (fs.existsSync(tmp)) shellExec(`sudo rm -rf "${tmp}"`);
-      shellExec(`git clone "${cloneUrl}" "${tmp}"`);
-      shellExec(`sudo mv "${tmp}" "${siteRoot}"`);
-      shellExec(`sudo chmod -R 755 "${siteRoot}"`);
-      shellExec(`sudo chown -R daemon:daemon "${siteRoot}"`);
-    } else {
-      logger.info(`${host}: repo already present at ${siteRoot}`);
-    }
-
-    // Step 2 — verify wp-config.php; if missing, wipe and do a fresh install.
-    // initLocalRepo is NOT called here — createApp always calls it after provisionClone
-    // returns (whether clone or fallback path) so we avoid a double-init and ensure
-    // safe.directory is declared before git runs.
+    // A checkout without wp-config.php is not a WordPress site: discard it and install fresh.
+    // initLocalRepo is left to createApp so both provisioning paths converge on one call.
     if (!fs.existsSync(path.join(siteRoot, 'wp-config.php'))) {
       logger.warn(`${host}: wp-config.php not found — wiping site root and running fresh install`);
       shellExec(`sudo rm -rf "${siteRoot}"`);
@@ -515,10 +482,9 @@ Thumbs.db
     const repoName = repository.split('/').pop().split('.')[0];
 
     logger.info(`${host}: persisting site to repository`);
-    shellExec(
-      `cd "${siteRoot}" && git add -A && git commit -m "wp provision ${host} $(date -u +%Y-%m-%dT%H:%M:%SZ)"`,
-      { silentOnError: true },
-    );
+    shellExec(`cd "${siteRoot}" && git add -A && git commit -m "wp provision ${host} $(date -u +%Y-%m-%dT%H:%M:%SZ)"`, {
+      silentOnError: true,
+    });
     shellExec(`cd "${siteRoot}" && underpost push . ${githubOrg}/${repoName} -f`);
     logger.info(`${host}: initial commit pushed to ${githubOrg}/${repoName}`);
   }
@@ -630,7 +596,9 @@ if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROT
 
     // MariaDB export is handled by the shared db.js backup flow — no duplicate dump here.
     if (fs.existsSync(path.join(siteRoot, '.git'))) {
-      shellExec(`cd "${siteRoot}" && git add -A && git commit -m "wp backup $(date -u +%Y-%m-%dT%H:%M:%SZ)"`, { silentOnError: true });
+      shellExec(`cd "${siteRoot}" && git add -A && git commit -m "wp backup $(date -u +%Y-%m-%dT%H:%M:%SZ)"`, {
+        silentOnError: true,
+      });
       shellExec(`cd "${siteRoot}" && underpost push . ${githubOrg}/${repository.split('/').pop().split('.')[0]}`);
       logger.info(`backup: git push done for ${siteRoot}`);
     } else {

package/src/server/{catalog.js → build/catalog.js}

@@ -8,9 +8,9 @@
  * deploy id resolve to the empty catalog — nothing else breaks.
  *
  * Each product catalog default-exports the uniform shape documented in
- * {@link module:src/server/catalog-cyberia}.
+ * {@link module:src/projects/cyberia/catalog-cyberia.js}.
  *
- * @module src/server/catalog.js
+ * @module src/server/build/catalog.js
  * @namespace Catalog
  */
 
@@ -18,7 +18,13 @@ import fs from 'fs-extra';
 import { fileURLToPath } from 'node:url';
 import * as path from 'node:path';
 
-/** Empty product catalog returned for deploy ids without a dedicated module. */
+/**
+ * Empty product catalog returned for deploy ids without a dedicated module.
+ *
+ * The `package*` fields are the deploy's package manifest contract, read by
+ * {@link module:src/server/build/package.js}: a deploy id with no catalog gets the engine
+ * manifest under its own identity, and one with a catalog adds exactly what it declares here.
+ */
 const EMPTY_CATALOG = {
   sourceMoves: [],
   privateConfPaths: [],
@@ -28,6 +34,10 @@ const EMPTY_CATALOG = {
   copies: [],
   keywords: [],
   description: '',
+  packageName: '',
+  packageBin: {},
+  packageDependencies: {},
+  packageScripts: {},
 };
 
 /**
@@ -44,7 +54,7 @@ const loadDeployCatalog = async (deployId) => {
   const suffix = (deployId ?? '').split('dd-')[1];
   if (!suffix) return EMPTY_CATALOG;
   if (fs.existsSync(`./src/projects/${suffix}/catalog-${suffix}.js`)) {
-    const mod = await import(`../projects/${suffix}/catalog-${suffix}.js`);
+    const mod = await import(`../../projects/${suffix}/catalog-${suffix}.js`);
     return { ...EMPTY_CATALOG, ...(mod.default ?? {}) };
   }
   return EMPTY_CATALOG;
@@ -63,7 +73,7 @@ const loadProductCatalogs = async () => {
   const catalogs = [];
   for (const file of await fs.readdir('./src/projects')) {
     if (file === 'underpost') continue;
-    const mod = await import(`../projects/${file}/catalog-${file}.js`);
+    const mod = await import(`../../projects/${file}/catalog-${file}.js`);
     if (mod.default) catalogs.push({ ...EMPTY_CATALOG, ...mod.default });
   }
   return catalogs;

package/src/server/build/coverage.js

@@ -0,0 +1,117 @@
+/**
+ * The coverage HTML report as a build artifact: where a run leaves it, where an assembled
+ * deploy artifact carries it, and what is published when nothing was carried.
+ *
+ * The report is produced by the test stage (`npm run test:coverage`) and bundled into the
+ * deploy artifact at {@link COVERAGE_BUNDLE_DIRECTORY}. A workload container only ever
+ * copies it: running a test runner inside a pod costs minutes of the build phase, needs the
+ * dev dependency tree, and — because a suite's expected non-zero exits latch the runtime
+ * status contract — publishes a false `error` to the deployment monitor.
+ *
+ * @module src/server/build/coverage.js
+ * @namespace UnderpostCoverage
+ */
+
+import fs from 'fs-extra';
+import { UNDERPOST_TESTING } from './testing.js';
+
+/**
+ * @constant COVERAGE_BUNDLE_DIRECTORY
+ * @description Path, relative to a source tree root, where an assembled deploy artifact
+ * carries the report. Deliberately not under `coverage/`, which every engine `.gitignore`
+ * excludes, so the bundled artifact is publishable source rather than a local run's output.
+ * @memberof UnderpostCoverage
+ */
+const COVERAGE_BUNDLE_DIRECTORY = 'docs/coverage';
+
+const normalizeRoot = (root) => `${root ?? ''}`.replace(/\/+$/, '');
+
+/**
+ * @method coverageReportCandidates
+ * @description Every place a coverage HTML report can live in a source tree, most local
+ * first: the reporters a run writes, then the bundled artifact a deploy artifact carries.
+ * @param {string} root - Source tree root.
+ * @returns {string[]} Candidate report directories.
+ * @memberof UnderpostCoverage
+ */
+const coverageReportCandidates = (root) => {
+  const base = normalizeRoot(root);
+  if (!base) return [];
+  const coverage = `${base}/${UNDERPOST_TESTING.coverageDirectory}`;
+  return [`${coverage}/html`, `${coverage}/lcov-report`, coverage, `${base}/${COVERAGE_BUNDLE_DIRECTORY}`];
+};
+
+/**
+ * @method resolveCoverageReportPath
+ * @description First candidate that actually carries an HTML index. A directory holding
+ * only `lcov.info` is not a report and is not published.
+ * @param {string} root - Source tree root.
+ * @returns {string|undefined} Report directory, or undefined when none is available.
+ * @memberof UnderpostCoverage
+ */
+const resolveCoverageReportPath = (root) =>
+  coverageReportCandidates(root).find((candidate) => fs.existsSync(`${candidate}/index.html`));
+
+/**
+ * @method bundleCoverageReport
+ * @description Copies the report of `fromRoot` into `toRoot`'s bundle directory, so the
+ * assembled artifact carries it into every container started from that source.
+ * @param {string} fromRoot - Tree the report was generated in.
+ * @param {string} toRoot - Assembled artifact root.
+ * @returns {{bundled: boolean, from?: string, to: string}} What was bundled, and where.
+ * @memberof UnderpostCoverage
+ */
+const bundleCoverageReport = (fromRoot, toRoot) => {
+  const to = `${normalizeRoot(toRoot)}/${COVERAGE_BUNDLE_DIRECTORY}`;
+  const from = resolveCoverageReportPath(fromRoot);
+  if (!from) return { bundled: false, to };
+  fs.emptyDirSync(to);
+  fs.copySync(from, to);
+  return { bundled: true, from, to };
+};
+
+/**
+ * @method coverageUnavailablePage
+ * @description The page served where a report was expected but none was bundled. A static
+ * document, never an invitation to generate one at runtime.
+ * @param {object} [options]
+ * @param {string} [options.command] - Command that produces the report.
+ * @returns {string} HTML document.
+ * @memberof UnderpostCoverage
+ */
+const coverageUnavailablePage = ({ command = 'npm run test:coverage' } = {}) => `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="robots" content="noindex" />
+    <title>Coverage report unavailable</title>
+    <style>
+      :root { color-scheme: light dark; }
+      body { margin: 0; display: grid; place-items: center; min-height: 100vh;
+             font: 16px/1.6 system-ui, -apple-system, Segoe UI, Roboto, sans-serif; }
+      main { max-width: 34rem; padding: 2rem; }
+      h1 { font-size: 1.25rem; margin: 0 0 .75rem; }
+      p { margin: 0 0 .75rem; opacity: .8; }
+      code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .9em; }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>Coverage report unavailable</h1>
+      <p>This build carried no coverage report. The report is generated by the test stage and
+      bundled into the deploy artifact under <code>${COVERAGE_BUNDLE_DIRECTORY}</code>.</p>
+      <p>Run <code>${command}</code> in the build environment, then assemble and publish the
+      artifact again.</p>
+    </main>
+  </body>
+</html>
+`;
+
+export {
+  COVERAGE_BUNDLE_DIRECTORY,
+  bundleCoverageReport,
+  coverageReportCandidates,
+  coverageUnavailablePage,
+  resolveCoverageReportPath,
+};

package/src/server/build/execution.js

@@ -0,0 +1,402 @@
+/**
+ * This module is pure with respect to the environment: it classifies, resolves and
+ * decides, but never executes. Enforcement belongs to `src/server/runtime/process.js`,
+ * which owns the subprocess boundary.
+ *
+ * @module src/server/build/execution.js
+ * @namespace UnderpostExecution
+ */
+
+import { execFileSync } from 'node:child_process';
+import nodePath from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = nodePath.resolve(nodePath.dirname(fileURLToPath(import.meta.url)), '../../..');
+
+/**
+ * @constant EXECUTION_PROFILE_ENV_KEY
+ * @description Environment key the active profile rides on into child processes. Reading it
+ * back is what makes a nested `underpost` invocation stay inside its parent's profile.
+ * @memberof UnderpostExecution
+ */
+const EXECUTION_PROFILE_ENV_KEY = 'UNDERPOST_EXECUTION_PROFILE';
+
+/**
+ * @constant CAPABILITIES
+ * @description The side-effect classes a command can exercise, ordered least to most
+ * privileged. The order is load-bearing: a compound command takes the capability of its
+ * most privileged segment, so `kubectl create … | kubectl apply -f -` is a cluster write
+ * rather than a cluster read.
+ * @memberof UnderpostExecution
+ */
+const CAPABILITIES = ['fs', 'git', 'net', 'cluster:read', 'host:write', 'cluster:write'];
+
+const capabilityRank = (capability) => CAPABILITIES.indexOf(capability);
+
+/**
+ * @constant EXECUTION_PROFILES
+ * @description The profile table. `permits` is the closed set of capabilities a run may
+ * exercise; everything else is elided.
+ *
+ * `reads: 'neutral'` is what lets a denied read stay invisible to its caller: a blocked
+ * `cluster:read` returns the empty result that 200+ `silentOnError` call sites already
+ * treat as "not present", so no caller needs to learn a new failure mode.
+ * @memberof UnderpostExecution
+ */
+const EXECUTION_PROFILES = {
+  // Full access. The default, and the only profile that may mutate a cluster or a host.
+  LIVE_CLUSTER: {
+    name: 'LIVE_CLUSTER',
+    permits: [...CAPABILITIES],
+    reads: 'live',
+    description: 'Full access: cluster and host mutation permitted.',
+  },
+  // Manifest and artifact generation. Filesystem and git are build outputs, not
+  // environment mutation, so they stay permitted — a build that regenerates manifests
+  // and commits them is doing its job.
+  HERMETIC_BUILD: {
+    name: 'HERMETIC_BUILD',
+    permits: ['fs', 'git'],
+    reads: 'neutral',
+    description: 'Build outputs only: no cluster, host or network side effects.',
+  },
+  // Nothing executes. Every effect is reported as the intent it would have carried out.
+  OFFLINE_DRY_RUN: {
+    name: 'OFFLINE_DRY_RUN',
+    permits: [],
+    reads: 'neutral',
+    description: 'Nothing executes; every command is reported as intent.',
+  },
+};
+
+const DEFAULT_PROFILE = 'LIVE_CLUSTER';
+
+/**
+ * @constant PROFILE_ALIAS_FLAGS
+ * @description Legacy bypass flags mapped onto the profile that subsumes them, so an
+ * operator who already knows the old flag lands in the right profile without learning a
+ * new one. The flags stay on the CLI surface — they are published entrypoints.
+ *
+ * Each alias is guarded by `when`, because a bypass flag is only equivalent to a profile
+ * in the mode it was written for. `--disable-update-underpost-config` means "skip one
+ * projection step" during a live deploy, but means "this run cannot reach a cluster at
+ * all" during a manifest build; aliasing it unconditionally would silently turn a real
+ * deploy into a no-op. Flags that are step toggles in every mode are deliberately absent:
+ * they keep their own guards, which the profile gate sits underneath rather than replaces.
+ * @memberof UnderpostExecution
+ */
+const PROFILE_ALIAS_FLAGS = {
+  disableUpdateUnderpostConfig: {
+    profile: 'HERMETIC_BUILD',
+    when: (options) => options?.buildManifest === true,
+  },
+};
+
+// Verbs that only read cluster state. Everything else kubectl accepts is treated as a
+// write: an unrecognised verb must not be assumed harmless.
+const KUBECTL_READ_VERBS = new Set([
+  'get',
+  'describe',
+  'logs',
+  'top',
+  'explain',
+  'api-resources',
+  'api-versions',
+  'version',
+  'cluster-info',
+  'config',
+  'auth',
+  'diff',
+]);
+
+// kubectl flags that consume the token after them, which would otherwise be mistaken
+// for the verb (`kubectl -n default get pods`).
+const KUBECTL_VALUE_FLAGS = new Set(['-n', '--namespace', '--context', '--kubeconfig', '--server', '--user']);
+
+const HOST_WRITE_BINARIES = new Set([
+  'systemctl',
+  'journalctl',
+  'dnf',
+  'yum',
+  'apt',
+  'apt-get',
+  'rpm',
+  'firewall-cmd',
+  'setenforce',
+  'semanage',
+  'restorecon',
+  'chcon',
+  'mount',
+  'umount',
+  'mkfs',
+  'parted',
+  'lvcreate',
+  'modprobe',
+  'sysctl',
+  'useradd',
+  'groupadd',
+  'usermod',
+  'lxc',
+  'lxd',
+  'virsh',
+  'virt-install',
+  'docker',
+  'podman',
+  'crictl',
+  'kind',
+  'kubeadm',
+  'k3s',
+  'wg',
+  'wg-quick',
+  'ip',
+  'iptables',
+  'nft',
+  'haproxy',
+]);
+
+// `gh` reaches a remote service and writes to it (`gh secret set`, `gh release create`), so it
+// is a network effect rather than local filesystem work — an unclassified binary would default
+// to `fs` and run under HERMETIC_BUILD.
+const NET_BINARIES = new Set(['curl', 'wget', 'ssh', 'scp', 'sftp', 'rsync', 'nc', 'ping', 'dig', 'nslookup', 'gh']);
+
+const CLUSTER_BINARIES = new Set(['kubectl', 'helm']);
+
+// Binaries that re-enter the engine. They are classified as local process work because
+// the child resolves its own profile from the environment — gating them here would stop
+// a hermetic build from reaching the very stages it exists to run.
+const NESTED_CLI_BINARIES = new Set(['node', 'npm', 'npx', 'underpost']);
+
+const stripSudo = (tokens) => {
+  if (tokens[0] !== 'sudo') return { tokens, escalated: false };
+  let index = 1;
+  // `sudo -u dd -E cmd` — step over sudo's own flags and their values.
+  while (index < tokens.length && tokens[index].startsWith('-')) {
+    const consumesValue = tokens[index] === '-u' || tokens[index] === '--user' || tokens[index] === '-g';
+    index += consumesValue ? 2 : 1;
+  }
+  return { tokens: tokens.slice(index), escalated: true };
+};
+
+const kubectlVerb = (tokens) => {
+  for (let index = 1; index < tokens.length; index++) {
+    const token = tokens[index];
+    if (KUBECTL_VALUE_FLAGS.has(token)) {
+      index++;
+      continue;
+    }
+    if (token.startsWith('-')) continue;
+    return token;
+  }
+  return '';
+};
+
+const classifySegment = (segment) => {
+  const tokens = `${segment ?? ''}`.trim().split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) return 'fs';
+
+  const { tokens: bare, escalated } = stripSudo(tokens);
+  if (bare.length === 0) return escalated ? 'host:write' : 'fs';
+
+  // Leading `VAR=value` assignments are not the command.
+  let start = 0;
+  while (start < bare.length && /^[A-Z_][A-Z0-9_]*=/i.test(bare[start])) start++;
+  const binary = nodePath.basename(bare[start] ?? '');
+  const rest = bare.slice(start);
+
+  if (CLUSTER_BINARIES.has(binary)) {
+    if (binary === 'helm') {
+      const verb = rest[1] ?? '';
+      return verb === 'list' || verb === 'get' || verb === 'status' ? 'cluster:read' : 'cluster:write';
+    }
+    return KUBECTL_READ_VERBS.has(kubectlVerb(rest)) ? 'cluster:read' : 'cluster:write';
+  }
+  if (NESTED_CLI_BINARIES.has(binary)) return 'fs';
+  if (binary === 'git') return 'git';
+  if (HOST_WRITE_BINARIES.has(binary)) return 'host:write';
+  if (NET_BINARIES.has(binary)) return 'net';
+
+  // An escalated command we do not otherwise recognise is a host mutation by definition.
+  return escalated ? 'host:write' : 'fs';
+};
+
+/**
+ * Classifies the side effect a command exercises.
+ *
+ * Compound commands resolve to their most privileged segment, so a pipeline cannot
+ * launder a write through a read.
+ * @param {string} cmd - The command string.
+ * @returns {string} One of {@link CAPABILITIES}.
+ * @memberof UnderpostExecution
+ */
+const classifyCommand = (cmd = '') => {
+  const text = `${cmd ?? ''}`;
+  if (!text.trim()) return 'fs';
+  // Heredoc bodies are data, not commands: `kubectl apply -f - <<'EOF' … EOF` must be
+  // classified on its first line alone, or YAML content would be parsed as a pipeline.
+  const [head] = text.split(/<<-?\s*'?[A-Za-z_]+'?/);
+  const segments = `${head}`.split(/&&|\|\||[;|]/);
+  let capability = 'fs';
+  for (const segment of segments) {
+    const segmentCapability = classifySegment(segment);
+    if (capabilityRank(segmentCapability) > capabilityRank(capability)) capability = segmentCapability;
+  }
+  return capability;
+};
+
+/**
+ * Resolves a profile by name, falling back to the default rather than throwing on an
+ * unknown value — an unreadable environment variable must not brick every command.
+ * @param {string} [name] - Profile name.
+ * @returns {object} The profile record.
+ * @memberof UnderpostExecution
+ */
+const executionProfileFactory = (name = '') => {
+  const key = `${name ?? ''}`.trim().toUpperCase().replace(/-/g, '_');
+  return EXECUTION_PROFILES[key] ?? EXECUTION_PROFILES[DEFAULT_PROFILE];
+};
+
+/**
+ * Maps a CLI options object onto the profile it selects.
+ *
+ * An explicit `--profile` wins. Otherwise a legacy bypass flag selects the profile that
+ * subsumes it, but only in the mode where the two actually mean the same thing.
+ * @param {object} [options] - Commander options.
+ * @returns {string} Profile name.
+ * @memberof UnderpostExecution
+ */
+const profileFromOptionsFactory = (options = {}) => {
+  const explicit = `${options?.profile ?? ''}`.trim();
+  if (explicit) return executionProfileFactory(explicit).name;
+  for (const [flag, alias] of Object.entries(PROFILE_ALIAS_FLAGS))
+    if (options?.[flag] === true && alias.when(options)) return alias.profile;
+  return '';
+};
+
+/**
+ * The profile in effect for this process.
+ * @returns {object} The active profile record.
+ * @memberof UnderpostExecution
+ */
+const activeExecutionProfile = () => executionProfileFactory(process.env[EXECUTION_PROFILE_ENV_KEY]);
+
+/**
+ * Installs a profile as the process-wide default.
+ *
+ * Writing the environment variable is the propagation mechanism: children inherit the
+ * environment, so a nested `underpost` invocation resolves the same profile with no
+ * command-string threading.
+ * @param {string} name - Profile name.
+ * @returns {object} The profile now in effect.
+ * @memberof UnderpostExecution
+ */
+const setExecutionProfile = (name) => {
+  const profile = executionProfileFactory(name);
+  process.env[EXECUTION_PROFILE_ENV_KEY] = profile.name;
+  return profile;
+};
+
+/**
+ * Runs `fn` under `name`, restoring the previous profile afterwards.
+ *
+ * Restores through a `finally` and awaits a thenable result, so a throwing or async
+ * stage cannot leak a hermetic profile into the rest of the process.
+ * @param {string} name - Profile to run under.
+ * @param {Function} fn - Work to run.
+ * @returns {*} Whatever `fn` returns.
+ * @memberof UnderpostExecution
+ */
+const withExecutionProfile = (name, fn) => {
+  const previous = process.env[EXECUTION_PROFILE_ENV_KEY];
+  const restore = () => {
+    if (previous === undefined) delete process.env[EXECUTION_PROFILE_ENV_KEY];
+    else process.env[EXECUTION_PROFILE_ENV_KEY] = previous;
+  };
+  setExecutionProfile(name);
+  let result;
+  try {
+    result = fn();
+  } catch (error) {
+    restore();
+    throw error;
+  }
+  if (result && typeof result.then === 'function') return result.finally(restore);
+  restore();
+  return result;
+};
+
+/**
+ * Decides whether a command may run under the active profile.
+ *
+ * Returns a decision rather than acting on one; `shellExec` owns the consequence.
+ * @param {string} cmd - The command string.
+ * @param {object} [context] - Optional overrides.
+ * @param {string} [context.profile] - Profile name, defaulting to the active one.
+ * @returns {{permitted: boolean, capability: string, profile: string, neutral: boolean}} Decision.
+ * @memberof UnderpostExecution
+ */
+const executionDecisionFactory = (cmd, { profile } = {}) => {
+  const record = profile ? executionProfileFactory(profile) : activeExecutionProfile();
+  const capability = classifyCommand(cmd);
+  return {
+    permitted: record.permits.includes(capability),
+    capability,
+    profile: record.name,
+    neutral: record.reads === 'neutral',
+  };
+};
+
+const localUnderpostCli = `node ${packageRoot}/bin/index.js`;
+let underpostCliCache;
+
+/**
+ * Resolves how to invoke a CLI from a subprocess.
+ *
+ * Two different questions hide behind "run underpost", and conflating them runs the
+ * wrong codebase:
+ *
+ *   - `local: true` — re-enter the package this process is running from, resolved through
+ *     `import.meta.url`. From a checkout that is the checkout; from a global install it is
+ *     that same global install, so a deployed node is unaffected. Every multi-stage runner
+ *     wants this: a stage that re-enters `underpost` must run the code its parent runs, or
+ *     the two disagree about layout. A stale global install reading credential seeds from a
+ *     directory this version moved is what that skew looks like in practice.
+ *   - default — whichever CLI this machine is meant to use: the globally linked binary
+ *     when one exists, otherwise this checkout by absolute path, so a build box without a
+ *     global install still works and callers that `cd` elsewhere keep resolving the same
+ *     CLI.
+ *
+ * This replaces the `options.dev ? 'node bin' : 'underpost'` branch copied across 14 call
+ * sites, none of which agreed on what happened when neither resolved.
+ * @param {string} [name] - CLI to resolve.
+ * @param {object} [options] - Resolution options.
+ * @param {boolean} [options.local] - Re-enter this checkout instead of a global install.
+ * @returns {string} Command prefix to invoke it with.
+ * @memberof UnderpostExecution
+ */
+const cli = (name = 'underpost', { local = false } = {}) => {
+  if (name !== 'underpost') return name;
+  if (local) return localUnderpostCli;
+  if (underpostCliCache) return underpostCliCache;
+  try {
+    execFileSync('sh', ['-c', 'command -v underpost'], { stdio: 'ignore' });
+    underpostCliCache = 'underpost';
+  } catch {
+    underpostCliCache = localUnderpostCli;
+  }
+  return underpostCliCache;
+};
+
+export {
+  activeExecutionProfile,
+  CAPABILITIES,
+  classifyCommand,
+  cli,
+  EXECUTION_PROFILE_ENV_KEY,
+  EXECUTION_PROFILES,
+  executionDecisionFactory,
+  executionProfileFactory,
+  PROFILE_ALIAS_FLAGS,
+  profileFromOptionsFactory,
+  setExecutionProfile,
+  withExecutionProfile,
+};