@underpostnet/cyberia 3.3.0 → 3.3.76

package/src/cli/deploy.js

@@ -5,13 +5,9 @@
  */
 
 import {
-  buildKindPorts,
-  buildPortProxyRouter,
-  buildProxyRouter,
   clusterTypeFactory,
   Config,
   deployHostsFactory,
-  deployRangePortFactory,
   gatewayApiEnabledFactory,
   getDataDeploy,
   instanceStatusPageEntriesFactory,
@@ -19,16 +15,22 @@ import {
   loadConfServerJson,
   loadReplicas,
   nextTrafficFactory,
-  pathPortAssignmentFactory,
   schedulableNodeFactory,
   trafficFromRoutingInfoFactory,
-} from '../server/conf.js';
-import { cronDeployIdResolve } from '../server/cron.js';
-import { loggerFactory } from '../server/logger.js';
-import { HOST_VOLUME_ROOT } from '../server/environment.js';
-import { shellExec } from '../server/process.js';
-import { runSELinuxCommands, selinuxRestoreconCommandFactory } from '../server/selinux.js';
-import { INTERNAL_READY_PATH, INTERNAL_HEALTH_PATH } from '../server/runtime-status.js';
+} from '../server/runtime/conf.js';
+import {
+  buildKindPorts,
+  buildPortProxyRouter,
+  buildProxyRouter,
+  deployRangePortFactory,
+  pathPortAssignmentFactory,
+  readDeployRoutes,
+} from '../server/network/router.js';
+import { loggerFactory } from '../server/ops/logger.js';
+import { HOST_VOLUME_ROOT } from '../server/runtime/environment.js';
+import { shellExec } from '../server/runtime/process.js';
+import { ensureContainerStorage, ensureContainerStorageSubtree } from '../server/security/container-storage.js';
+import { INTERNAL_READY_PATH, INTERNAL_HEALTH_PATH } from '../server/runtime/runtime-status.js';
 import { staticContextRoutesFactory, statusPageRoutesFactory } from '../client-builder/client-build.js';
 import {
   UNDERPOST_GATEWAY,
@@ -41,13 +43,15 @@ import {
   syncStaticAssetFromPod,
   writeHostServerConf,
   writeStaticAsset,
-} from '../server/underpost-gateway.js';
+} from '../server/network/underpost-gateway.js';
 import { getCapVariableName } from '../client/components/core/CommonJs.js';
 import fs from 'fs-extra';
 import nodePath from 'node:path';
 import dotenv from 'dotenv';
 import os from 'node:os';
 import crypto from 'node:crypto';
+import { appSecretName } from './app.js';
+import { domainContextFactory } from './domains.js';
 import Underpost from '../index.js';
 
 /**
@@ -79,7 +83,7 @@ const GATEWAY_CONTROLLER_NAME = `${GATEWAY_EXTENSION_GROUP}/gatewayclass-control
 // Gateway references: one name, resolved through gatewayApiConfigFactory, so an
 // override reaches the installer and the manifests together.
 const GATEWAY_CLASS_DEFAULT = 'eg';
-// Where `bin client <deployId> <env>` writes each host's bundle, including the
+// Where `bin client <deployId> --env <env>` writes each host's bundle, including the
 // SSR status views declared in conf.ssr.json (`<host><path>/<status>/index.html`).
 // Engine root inside the workload container; the built PWA artifacts live under
 // its `public/` tree, which is where the static edge documents are sourced from.
@@ -89,6 +93,17 @@ const UPSTREAM_FAILURE_STATUSES = [502, 503, 504];
 
 const CONTAINER_ENGINE_ROOT = '/home/dd/engine';
 
+// The manifest set `deploy --build-manifest` produces for one environment.
+const DEFAULT_MANIFEST_FILES = [
+  'deployment.yaml',
+  'proxy.yaml',
+  'gateway.yaml',
+  'httproute.yaml',
+  'pv-pvc.yaml',
+  'traffic-service.yaml',
+  'grpc-service.yaml',
+];
+
 /**
  * Maps a host/path's edge-served views onto the statuses the gateway intercepts
  * for it, and the context directory each status is answered from.
@@ -132,10 +147,10 @@ const GATEWAY_DURATION_UNITS = [
 ];
 
 /**
- * Converts an HTTPProxy duration (`300000ms`, `10s`, `infinity`) into a Gateway
+ * Converts an HTTPProxy duration (`10000ms`, `10s`, `infinity`) into a Gateway
  * API Duration. The Gateway API grammar allows at most 5 digits per component,
  * so a value that overflows in one unit is re-expressed in a coarser one
- * (`300000ms` → `5m`); `infinity` maps to `0s`, which disables the timeout.
+ * (`10000ms` → `5m`); `infinity` maps to `0s`, which disables the timeout.
  * @param {string|number} value - Source duration.
  * @returns {string|null} Gateway API Duration, or null when unset/unparsable.
  */
@@ -154,12 +169,12 @@ const gatewayDurationFactory = (value) => {
 
 const logger = loggerFactory(import.meta);
 
-// hostPath volume trees are written under the operator's home directory, which
-// carries a label no unprivileged container can read. Cluster bring-up registers
-// the persistent mapping for HOST_VOLUME_ROOT; this applies it to what a deploy
-// just wrote. A no-op where SELinux or its userspace is absent.
-const restoreContainerContext = (path) =>
-  runSELinuxCommands([selinuxRestoreconCommandFactory(path)], { execute: shellExec });
+// hostPath volume trees are written under the operator's home directory, which carries a label no
+// unprivileged container can read. This registers the persistent mapping and restores the tree,
+// rather than only restoring it: a deploy must not depend on cluster bring-up having run on this
+// host, and a plain `restorecon` against an unmapped path re-applies the very default that makes
+// the volume unreadable. A no-op where SELinux or its userspace is absent.
+const prepareContainerStorage = (path) => ensureContainerStorageSubtree(path, { execute: shellExec });
 
 /**
  * @class UnderpostDeploy
@@ -449,20 +464,15 @@ EOF
     }) {
       if (!readinessProbe) throw new Error(`Refusing to build ${deployId}-${env}-${suffix} without a readiness probe`);
       if (!cmd)
-        cmd =
-          pullBundle || skipFullBuild
-            ? [
-                // When pullBundle (or skipFullBuild) is set the container pulls the pre-built client
-                // bundle from Cloudinary (push-bundle must have been run on the dev machine beforehand).
-                `underpost secret underpost --create-from-env`,
-                `underpost start --build --run --pull-bundle --skip-full-build ${deployId} ${env}`,
-              ]
-            : [
-                // `npm install -g npm@11.2.0`,
-                // `npm install -g underpost`,
-                `underpost secret underpost --create-from-env`,
-                `underpost start --build --run ${deployId} ${env}`,
-              ];
+        // One command, and deliberately only `start`. This string is executed by whatever
+        // underpost the image happens to ship, which is as new as the last npm publish and no
+        // newer — so it may name only CLI surface that has always existed. Everything the
+        // deployment needs beyond that, host configuration included, is done inside the start
+        // lifecycle, where the code is the freshly pulled source rather than the image snapshot.
+        // `--pull-bundle` fetches the pre-built client bundle instead of building it in-pod.
+        cmd = [
+          `underpost start --build --run${pullBundle || skipFullBuild ? ' --pull-bundle --skip-full-build' : ''} ${deployId} ${env}`,
+        ];
       const packageJson = JSON.parse(fs.readFileSync('./package.json', 'utf8'));
       if (!volumes) volumes = [];
       const confVolume = fs.existsSync(`./engine-private/conf/${deployId}/conf.volume.json`)
@@ -503,6 +513,12 @@ ${
           envFrom:
             - secretRef:
                 name: underpost-config
+            # The deployment's own environment, with its .env.<env>.oci overlay already
+            # applied by 'app apply'. Optional so a deployment predating that Secret still
+            # starts; the in-pod 'app load' resolves the same overlay as a second path.
+            - secretRef:
+                name: ${appSecretName(deployId, env)}
+                optional: true
 ${
   internalStatusPort
     ? `          env:
@@ -601,7 +617,7 @@ spec:
      * @param {string} options.namespace - Kubernetes namespace for the deployment (defaults to "default").
      * @param {string} [options.versions] - Comma-separated list of versions to deploy.
      * @param {string} [options.cmd] - Custom initialization command for deploymentYamlPartsFactory (comma-separated commands).
-     * @param {string} [options.timeoutResponse] - HTTPProxy per-route response timeout (e.g. "300000ms", "infinity").
+     * @param {string} [options.timeoutResponse] - HTTPProxy per-route response timeout (e.g. "10000ms", "infinity").
      * @param {string} [options.timeoutIdle] - HTTPProxy per-route idle timeout (e.g. "10s", "infinity").
      * @param {string} [options.retryCount] - HTTPProxy per-route retry count (e.g. 3).
      * @param {string} [options.retryPerTryTimeout] - HTTPProxy per-route per-try timeout (e.g. "150ms").
@@ -1096,6 +1112,41 @@ spec:
     kind: ClusterIssuer
   secretName: ${host}`;
     },
+    /**
+     * Mirrors each deploy's built development manifests into the project tree, and refreshes the
+     * public default configuration they belong to.
+     *
+     * The project repository carries the development manifests of every routed deploy; the
+     * private build directory is where they are produced. A manifest the build stopped producing
+     * is removed here rather than left behind, so the two cannot disagree about what a deploy
+     * ships.
+     * @param {string[]} [deployIds] - Deploy ids to mirror; the route table plus `dd-cron` otherwise.
+     * @returns {Array<{deployId: string, copied: string[], removed: string[]}>} What was mirrored.
+     * @memberof UnderpostDeploy
+     */
+    mirrorDefaultManifests(deployIds = readDeployRoutes().concat(['dd-cron'])) {
+      const mirrored = [];
+      for (const deployId of deployIds) {
+        const copied = [];
+        const removed = [];
+        for (const file of DEFAULT_MANIFEST_FILES) {
+          const source = `./engine-private/conf/${deployId}/build/development/${file}`;
+          const target = `./manifests/deployment/${deployId}-development/${file}`;
+          if (fs.existsSync(source)) {
+            fs.copySync(source, target);
+            copied.push(file);
+          } else if (fs.existsSync(target)) {
+            fs.removeSync(target);
+            removed.push(file);
+          }
+        }
+        shellExec(`node bin new --dev --default-conf --deploy-id ${deployId}`);
+        mirrored.push({ deployId, copied, removed });
+      }
+      logger.info('Default deployment manifests mirrored', { deployIds: mirrored.map(({ deployId }) => deployId) });
+      return mirrored;
+    },
+
     /**
      * Retrieves the current traffic status for a deployment.
      * @param {string} deployId - Deployment ID for which the traffic status is being retrieved.
@@ -1735,6 +1786,45 @@ ${rules}`;
       return `${ready}`.includes('true');
     },
 
+    /**
+     * Reports whether a Deployment object exists at all.
+     *
+     * The inactive colour of a blue/green pair is routinely absent, so callers
+     * that act on it must distinguish "not deployed yet" from a failed lookup.
+     * @param {string} deployment - Deployment name.
+     * @param {string} [namespace] - Kubernetes namespace.
+     * @returns {boolean} True when the object is present.
+     */
+    deploymentExists({ deployment, namespace = 'default' }) {
+      return !!`${
+        shellExec(`kubectl get deployment ${deployment} -n ${namespace} --ignore-not-found -o name`, {
+          stdout: true,
+          silent: true,
+          silentOnError: true,
+        }) || ''
+      }`.trim();
+    },
+
+    /**
+     * Node a live Deployment is pinned to, read from its `nodeSelector`.
+     *
+     * A colour created next to a live one must inherit that placement: its
+     * hostPath volumes exist on that node only.
+     * @param {string} deployment - Deployment name.
+     * @param {string} [namespace] - Kubernetes namespace.
+     * @returns {string} Node hostname, or empty when the workload is unpinned or absent.
+     */
+    deploymentNode({ deployment, namespace = 'default' }) {
+      if (!deployment) return '';
+      return `${
+        shellExec(
+          `kubectl get deployment ${deployment} -n ${namespace} ` +
+            `-o jsonpath='{.spec.template.spec.nodeSelector.kubernetes\.io/hostname}'`,
+          { stdout: true, silent: true, silentOnError: true },
+        ) || ''
+      }`.trim();
+    },
+
     /**
      * Reports whether the Deployment controller has observed the current
      * generation and every desired replica is updated, Ready, and Available.
@@ -1890,12 +1980,11 @@ ${rules}`;
               ? 'project'
               : null,
           });
-      // The documents were just written under the operator's home tree, whose
-      // policy label (user_home_t) the unprivileged gateway container cannot
-      // read — it would answer 403 for every one of them. The persistent
-      // mapping is registered at cluster bring-up; restore it here so files
-      // this pass created carry it too.
-      restoreContainerContext(hostRoot);
+      // The documents were just written under the operator's home tree, whose policy label
+      // (user_home_t) the unprivileged gateway container cannot read — it would answer 403 for
+      // every one of them. Register the mapping for the volume root and restore this subtree, so
+      // the files this pass created carry the shared container label.
+      prepareContainerStorage(hostRoot);
       logger.info('Static edge documents placed', {
         deployId,
         podName: podName || '(no running workload; placed from this checkout)',
@@ -2096,7 +2185,7 @@ ${rules}`;
      * @param {boolean} options.disableUpdateVolume - Whether to disable volume updates.
      * @param {boolean} options.disableUpdateUnderpostConfig - Whether to disable Underpost config updates.
      * @param {string} [options.namespace] - Kubernetes namespace for the deployment (defaults to "default").
-     * @param {string} [options.timeoutResponse] - HTTPProxy per-route response timeout (e.g. "300000ms", "infinity").
+     * @param {string} [options.timeoutResponse] - HTTPProxy per-route response timeout (e.g. "10000ms", "infinity").
      * @param {string} [options.timeoutIdle] - HTTPProxy per-route idle timeout (e.g. "10s", "infinity").
      * @param {string} [options.retryCount] - HTTPProxy per-route retry count (e.g. 3).
      * @param {string} [options.retryPerTryTimeout] - HTTPProxy per-route per-try timeout (e.g. "150ms").
@@ -2157,8 +2246,7 @@ ${Underpost.deploy.buildCertManagerCertificate({ host, namespace })}
 EOF`);
         }
         return;
-      } else if (!deployList || deployList === 'dd')
-        deployList = fs.readFileSync(`./engine-private/deploy/dd.router`, 'utf8');
+      } else if (!deployList || deployList === 'dd') deployList = readDeployRoutes().join(',');
       const deployIds = deployList
         .split(',')
         .map((id) => id.trim())
@@ -2202,11 +2290,19 @@ EOF`);
           Underpost.deploy.syncStaticAssets(deployId, env, options);
         return;
       }
+      // Before the `--build-manifest` return: a manifest build is when the Secrets it mounts
+      // must exist, and `run sync` reaches this command with `--build-manifest --info-router`.
+      if (!options.disableUpdateUnderpostConfig) {
+        Underpost.host.apply(domainContextFactory({ env, namespace }));
+        // Each deployment's own env, OCI overlay applied. Without it the overlay reaches a pod
+        // only through in-pod `app load`, so a stale image keeps the base file's 127.0.0.1.
+        for (const _deployId of deployIds)
+          Underpost.app.apply(domainContextFactory({ env, namespace, args: { 'deploy-id': _deployId } }));
+      }
       if (options.infoRouter === true || options.buildManifest === true) {
         logger.info('router', await Underpost.deploy.routerFactory(deployList, env));
         return;
       }
-      if (!options.disableUpdateUnderpostConfig) Underpost.deploy.configMap(env);
 
       for (const _deployId of deployList.split(',')) {
         const deployId = _deployId.trim();
@@ -2392,27 +2488,6 @@ EOF`);
         }
       }
     },
-    /**
-     * Creates a Kubernetes Secret for a deployment (replaces configMap for secret data).
-     * Secrets are mounted as tmpfs (never written to node disk) and support RBAC restrictions.
-     * @param {string} env - Environment for which the secret is being created.
-     * @param {string} [namespace='default'] - Kubernetes namespace for the secret.
-     * @memberof UnderpostDeploy
-     */
-    configMap(env, namespace = 'default') {
-      const cronDeployId = cronDeployIdResolve() || 'dd-cron';
-      const envFilePath = `/home/dd/engine/engine-private/conf/${cronDeployId}/.env.${env}`;
-      // `--from-env-file` turns every KEY=VALUE into a secret key that the Deployment injects via
-      // `envFrom`. Strip shell/runtime-critical keys (notably PATH) first — an injected PATH
-      // overrides the image's own and breaks coreutils/sudo resolution inside the pod.
-      const sanitizedEnvPath = `${envFilePath}.secret`;
-      fs.writeFileSync(sanitizedEnvPath, Underpost.secret.sanitizeSecretEnvFile(fs.readFileSync(envFilePath, 'utf8')));
-      shellExec(`kubectl delete secret underpost-config -n ${namespace} --ignore-not-found`);
-      shellExec(
-        `kubectl create secret generic underpost-config --from-env-file=${sanitizedEnvPath} --dry-run=client -o yaml | kubectl apply -f - -n ${namespace}`,
-      );
-      fs.removeSync(sanitizedEnvPath);
-    },
     /**
      * Switches the traffic for a deployment.
      *
@@ -2552,7 +2627,7 @@ EOF`);
       const grpcServicePath = `./engine-private/conf/${deployId}/build/${env}/grpc-service.yaml`;
       if (fs.existsSync(grpcServicePath)) shellExec(`kubectl apply -f ${grpcServicePath} -n ${namespace}`);
 
-      Underpost.env.set(`${deployId}-${env}-traffic`, targetTraffic);
+      Underpost.host.store.set(`${deployId}-${env}-traffic`, targetTraffic);
     },
 
     /**
@@ -2562,9 +2637,8 @@ EOF`);
      * behaves identically everywhere:
      *
      *   1. **Explicit node** — `node` (the resolved `--node` value). Upstream
-     *      runners derive it from the comma-path field or `--node-name`
-     *      (`run sync`: `path.split(',')[4]` > `--node-name` > default) and from
-     *      `--node-name` directly (`run instance`).
+     *      runners derive it from `--node-name` (`run sync`: `--node-name` >
+     *      cluster-type default; `run instance`: `--node-name` directly).
      *   2. **`UNDERPOST_DEPLOY_NODE` env** — for kubeadm / k3s, the configured
      *      target node name. This makes hostPath PV `nodeAffinity` deterministic
      *      regardless of where the manifest is *built*: building inside a
@@ -2668,10 +2742,15 @@ EOF`);
         const localHost = os.hostname();
         dataNode = options.nodeName || localHost;
         if (dataNode === localHost) {
-          // Target node is the control plane / current host: write directly.
-          if (!fs.existsSync(rootVolumeHostPath)) fs.mkdirSync(rootVolumeHostPath, { recursive: true });
+          // Target node is the control plane / current host: write directly. The directory is
+          // created owned by the invoking user — the root above it may be root-owned, and the copy
+          // that follows is unprivileged — and labeled before as well as after the copy, so the
+          // files land already carrying the shared container label instead of inheriting the
+          // operator home tree's.
+          const { uid, gid } = os.userInfo();
+          ensureContainerStorage(rootVolumeHostPath, { execute: shellExec, owner: `${uid}:${gid}` });
           fs.copySync(volume.volumeMountPath, rootVolumeHostPath);
-          restoreContainerContext(rootVolumeHostPath);
+          prepareContainerStorage(rootVolumeHostPath);
         } else {
           // Target node is remote: fs.copySync would only write the control-plane
           // filesystem, leaving the real node's hostPath empty. Ship the folder to
@@ -2691,6 +2770,9 @@ EOF`);
             host: nodeHost,
             localDir: volume.volumeMountPath,
             remoteDir: rootVolumeHostPath,
+            // The volume is mounted on that node, so the label has to exist there. Labeling the
+            // control plane's copy of the path would leave the pod reading an unlabeled tree.
+            containerStorage: true,
             ...(options.sshKeyPath ? { keyPath: options.sshKeyPath } : {}),
           });
         }

package/src/cli/docker-compose.js

@@ -10,8 +10,8 @@
 
 import fs from 'fs-extra';
 import nodePath from 'path';
-import { getRootDirectory, shellExec } from '../server/process.js';
-import { loggerFactory } from '../server/logger.js';
+import { getRootDirectory, shellExec } from '../server/runtime/process.js';
+import { loggerFactory } from '../server/ops/logger.js';
 import Nginx from '../runtime/nginx/Nginx.js';
 
 const logger = loggerFactory(import.meta);
@@ -143,7 +143,7 @@ class UnderpostDockerCompose {
         // Point the template .env.example at the Docker service-discovery hosts
         // before `new engine` copies it. The generated dd-engine/.env.development
         // is seeded from this file and is applied over the process env by
-        // loadConf (src/server/conf.js), so without this the engine would fall
+        // loadConf (src/server/runtime/conf.js), so without this the engine would fall
         // back to the .env.example localhost defaults for DB_HOST/VALKEY_HOST.
         'sed -i "s#^DB_HOST=.*#DB_HOST=$${DB_HOST}#" .env.example',
         'sed -i "s#^VALKEY_HOST=.*#VALKEY_HOST=$${VALKEY_HOST}#" .env.example',
@@ -151,7 +151,7 @@ class UnderpostDockerCompose {
         'cd /home/dd',
         'underpost new engine',
       ];
-    return ['underpost secret underpost --create-from-env', `underpost start --build --run ${deployId} ${env}`];
+    return [`underpost start --build --run ${deployId} ${env}`];
   }
 
   /**
@@ -192,7 +192,7 @@ services:
 MONGO_IMAGE=mongo:latest
 VALKEY_IMAGE=valkey/valkey:latest
 APP_IMAGE=underpost/underpost-engine
-APP_TAG=v3.3.0
+APP_TAG=v3.3.76
 PROXY_IMAGE=nginx:stable-alpine
 PROMETHEUS_IMAGE=prom/prometheus:latest
 GRAFANA_IMAGE=grafana/grafana:latest

package/src/cli/domains.js

@@ -0,0 +1,184 @@
+/**
+ * Shared command surface for the four domains.
+ *
+ * `secret`, `host`, `app` and `state` are registered from one factory, so the action list and the
+ * option list exist exactly once. Symmetry is not a convention the four commands agree to follow
+ * — it is structural: a verb or a flag added here appears on all four, and one that is not here
+ * cannot appear on any of them.
+ *
+ * The three configuration domains carry a durable source; `state` is the runtime monitoring /
+ * telemetry layer and carries none, so its actions read and export a live observation instead.
+ * The verbs are the same either way — see {@link UnderpostState} for what each means there.
+ * @module src/cli/domains.js
+ * @namespace UnderpostDomains
+ */
+
+/**
+ * The canonical action set. Every domain implements all of these with the same meaning:
+ *
+ * | action  | direction                         |
+ * |---------|-----------------------------------|
+ * | setup   | onboard the domain, idempotently  |
+ * | load    | durable store  -> local runtime   |
+ * | publish | local runtime  -> durable store   |
+ * | apply   | durable store  -> live cluster    |
+ * | status  | read-only report                  |
+ * | rotate  | replace the current projection    |
+ * | clean   | withdraw local traces             |
+ * @constant {Array<{name: string, summary: string}>}
+ * @memberof UnderpostDomains
+ */
+const DOMAIN_ACTIONS = [
+  { name: 'setup', summary: 'Onboards the domain: provisions whatever it needs, then converges it. Idempotent.' },
+  { name: 'load', summary: 'Loads the durable source into the local runtime environment.' },
+  { name: 'publish', summary: 'Writes the local runtime environment into the durable source.' },
+  { name: 'apply', summary: 'Projects the durable source into the live cluster.' },
+  { name: 'status', summary: 'Read-only report of the domain: sources, keys, and drift from the cluster.' },
+  { name: 'rotate', summary: 'Replaces the current projection or encryption identity.' },
+  { name: 'clean', summary: 'Withdraws the domain traces from the local filesystem.' },
+];
+
+/**
+ * The canonical option set, identical on every action of every domain.
+ *
+ * Deliberately five. Everything a single domain used to carry its own flag for — an Age
+ * recipient, a secret name list, a sub-configuration — passes through `--args` instead, so the
+ * visible surface does not grow when one domain gains a parameter.
+ * @constant {Array<{flags: string, description: string}>}
+ * @memberof UnderpostDomains
+ */
+const DOMAIN_OPTIONS = [
+  { flags: '--env <env>', description: 'Target environment: development | production | test (default: production).' },
+  { flags: '--namespace <namespace>', description: 'Kubernetes namespace to act on (default: default).' },
+  {
+    flags: '--args <key=value-list>',
+    description:
+      'Comma-separated domain parameters, e.g. `names=postgres-secret`, `recipient=age1...`, `sub-conf=nexodev`.',
+  },
+  { flags: '--dry-run', description: 'Reports what the action would change without changing anything.' },
+  { flags: '--force', description: 'Confirms the irreversible variant of the action.' },
+];
+
+/**
+ * Key-level operators a domain may register alongside the canonical seven.
+ *
+ * They are not part of {@link DOMAIN_ACTIONS} on purpose: the canonical set is a bulk-lifecycle
+ * verb set, symmetric across every domain, with no place for per-key reads and writes. A domain
+ * that owns a key-value store opts into these instead of getting a command of its own — the host
+ * configuration store is the host domain's, so `underpost host get KEY` is where it is read.
+ * @constant {Array<string>}
+ * @memberof UnderpostDomains
+ */
+const DOMAIN_STORE_OPERATORS = ['get', 'set', 'delete', 'list'];
+
+const DOMAIN_STORE_OPTIONS = [
+  { flags: '--plain', description: 'Prints the value in plain text (get).' },
+  { flags: '--filter <keyword>', description: 'Filters by matching key or value (list).' },
+  { flags: '--copy', description: 'Copies the value to the clipboard (get).' },
+];
+
+/**
+ * Parses `--args key=value,key=value` into an object.
+ *
+ * Values may contain `=` (an Age recipient does not, a password can), so only the first
+ * separator splits. A bare `key` is the boolean shorthand for `key=true`.
+ * @param {string} [value] - Raw `--args` string.
+ * @returns {Object<string, string|boolean>} Parsed parameters.
+ * @memberof UnderpostDomains
+ */
+const parseDomainArgs = (value) => {
+  // Idempotent: an already-parsed object passes through, so normalizing a context twice — once
+  // at the CLI boundary, once inside the action a programmatic caller invoked directly — is safe.
+  if (value && typeof value === 'object') return { ...value };
+  return Object.fromEntries(
+    `${value ?? ''}`
+      .split(',')
+      .map((entry) => entry.trim())
+      .filter(Boolean)
+      .map((entry) => {
+        const index = entry.indexOf('=');
+        return index === -1 ? [entry, true] : [entry.slice(0, index).trim(), entry.slice(index + 1)];
+      }),
+  );
+};
+
+/**
+ * Normalizes the parsed options handed to a domain action, so every domain receives the same
+ * shape and none of them re-derives a default of its own.
+ * @param {object} [options] - Commander options for the invocation.
+ * @returns {{env: string, namespace: string, args: object, dryRun: boolean, force: boolean}} Normalized context.
+ * @memberof UnderpostDomains
+ */
+const domainContextFactory = (options = {}) => ({
+  env: `${options.env ?? ''}`.trim() || 'production',
+  namespace: `${options.namespace ?? ''}`.trim() || 'default',
+  args: parseDomainArgs(options.args),
+  dryRun: options.dryRun === true,
+  force: options.force === true,
+});
+
+/**
+ * Registers one domain as a top-level command carrying the full canonical surface.
+ *
+ * The action is a required argument rather than a flag so the three commands read as
+ * `underpost <domain> <action>`, and an unknown action fails against the shared list instead of
+ * silently doing nothing.
+ * @param {object} program - The commander program.
+ * @param {object} domain - Domain registration.
+ * @param {string} domain.name - Command name (`secret`, `host`, `app`, `state`).
+ * @param {boolean} [domain.store] - Whether this domain owns a key-value store, and so carries
+ *   the key-level operators alongside the canonical actions.
+ * @param {string} domain.description - One-line command description.
+ * @param {Function} domain.api - Returns the domain API implementing every canonical action.
+ * @returns {object} The registered commander command.
+ * @memberof UnderpostDomains
+ */
+const registerDomainCommand = (program, { name, description, api, store = false }) => {
+  const actions = DOMAIN_ACTIONS.map((action) => action.name);
+  const operators = store ? DOMAIN_STORE_OPERATORS : [];
+  const command = program
+    .command(name)
+    .argument(
+      '<action>',
+      `Action to run. One of: ${[...actions, ...operators].join(', ')}.\n` +
+        DOMAIN_ACTIONS.map((action) => `  ${action.name.padEnd(8)} ${action.summary}`).join('\n') +
+        (store ? `\n  ${'get|set|delete|list'.padEnd(8)} Key-level access to the store this domain owns.` : ''),
+    )
+    .description(description);
+  // Only a store-owning domain takes a key and a value; the others keep the bare action surface.
+  if (store) {
+    command.argument('[key]', 'Key to act on, for the key-level operators.');
+    command.argument('[value]', 'Value to write, for the `set` operator.');
+  }
+  // Commander hands the action `(...arguments, options, command)`, so the options object is
+  // second from the end no matter how many positionals this domain declared.
+  command.action((...received) => {
+    const options = received[received.length - 2];
+    const [action, key, value] = received;
+    if (operators.includes(action)) {
+      if (action !== 'list' && !key) throw new Error(`${name} ${action} requires a key`);
+      if (action === 'set' && value === undefined) throw new Error(`${name} set requires a value`);
+      return api()[action](key, value, options);
+    }
+    if (!actions.includes(action))
+      throw new Error(`Unknown ${name} action: ${action} (expected ${[...actions, ...operators].join(', ')})`);
+    const implementation = api()[action];
+    // Guards the contract at the boundary: a domain that has not implemented the full
+    // canonical set fails here by name, rather than as `undefined is not a function`.
+    if (typeof implementation !== 'function')
+      throw new Error(`Domain '${name}' does not implement the '${action}' action`);
+    return implementation(domainContextFactory(options));
+  });
+  for (const option of DOMAIN_OPTIONS) command.option(option.flags, option.description);
+  if (store) for (const option of DOMAIN_STORE_OPTIONS) command.option(option.flags, option.description);
+  return command;
+};
+
+export {
+  DOMAIN_ACTIONS,
+  DOMAIN_OPTIONS,
+  DOMAIN_STORE_OPERATORS,
+  domainContextFactory,
+  parseDomainArgs,
+  registerDomainCommand,
+};