underpost 3.2.28 → 3.2.70

package/src/cli/deploy.js

@@ -383,6 +383,10 @@ spec:
      * @param {string} [options.imagePullPolicy] - Container imagePullPolicy override (`Always`, `IfNotPresent`, `Never`); forwarded to deploymentYamlPartsFactory. Defaults to `Never` for `localhost/` images and `IfNotPresent` otherwise.
      * @param {boolean} [options.disableRuntimeProbes] - Omit internal-status HTTP probes from generated manifests. When true no readiness/liveness/startup probes are emitted.
      * @param {boolean} [options.tcpProbes] - Emit legacy TCP socket probes instead of HTTP internal-status probes (migration path).
+     * @param {string} [options.node] - Explicit target node for hostPath PV nodeAffinity pinning; resolved through {@link UnderpostDeploy.resolveDeployNode} together with the cluster flags.
+     * @param {boolean} [options.kind] - Kind cluster context; affects the cluster-type node default when no explicit node is set.
+     * @param {boolean} [options.kubeadm] - Kubeadm cluster context; affects the cluster-type node default when no explicit node is set.
+     * @param {boolean} [options.k3s] - K3s cluster context; affects the cluster-type node default when no explicit node is set.
      * @returns {Promise<void>} - Promise that resolves when the manifest is built.
      * @memberof UnderpostDeploy
      */
@@ -455,6 +459,15 @@ ${Underpost.deploy
           ? JSON.parse(fs.readFileSync(`./engine-private/conf/${deployId}/conf.volume.json`, 'utf8'))
           : [];
         if (confVolume.length > 0) {
+          // Mirror deployVolume's data-node resolution so the generated manifest
+          // pins the PV to the same node that physically receives the volume data.
+          const pvDataNode = Underpost.deploy.resolveDeployNode({
+            node: options.node,
+            kind: options.kind,
+            kubeadm: options.kubeadm,
+            k3s: options.k3s,
+            env,
+          });
           let volumeYaml = '';
           for (const deploymentVersion of deploymentVersions) {
             for (const volume of confVolume) {
@@ -466,6 +479,7 @@ ${Underpost.deploy
                 pvcId,
                 namespace: options.namespace,
                 hostPath,
+                nodeName: pvDataNode,
               })}\n`;
             }
           }
@@ -548,7 +562,7 @@ ${Underpost.deploy
           const yamlPath = `./engine-private/conf/${deployId}/build/${env}/secret.yaml`;
           fs.writeFileSync(yamlPath, secretYaml, 'utf8');
         } else {
-          const deploymentsFiles = ['Dockerfile', 'proxy.yaml', 'deployment.yaml', 'pv-pvc.yaml'];
+          const deploymentsFiles = ['Dockerfile', 'proxy.yaml', 'deployment.yaml', 'pv-pvc.yaml', 'grpc-service.yaml'];
           for (const file of deploymentsFiles) {
             if (fs.existsSync(`./engine-private/conf/${deployId}/build/${env}/${file}`)) {
               fs.copyFileSync(
@@ -720,7 +734,8 @@ spec:
      * @param {string} options.image - Docker image for the deployment.
      * @param {string} options.traffic - Traffic status for the deployment.
      * @param {string} options.replicas - Number of replicas for the deployment.
-     * @param {string} options.node - Node name for resource allocation.
+     * @param {string} options.node - Explicit target node (highest precedence in the node chain). When empty, {@link UnderpostDeploy.resolveDeployNode} falls back to the cluster-type default (`kind-worker` for kind, host for kubeadm/k3s). Used for both volume placement and hostPath PV nodeAffinity.
+     * @param {string} [options.sshKeyPath] - Private key path for node SSH operations, forwarded to deployVolume when shipping a hostPath volume to a remote target node over SSH. Defaults to engine-private/deploy/id_rsa.
      * @param {boolean} options.disableUpdateDeployment - Whether to disable deployment updates.
      * @param {boolean} options.disableUpdateProxy - Whether to disable proxy updates.
      * @param {boolean} options.disableDeploymentProxy - Whether to disable deployment proxy.
@@ -938,9 +953,16 @@ EOF`);
                   env,
                   version,
                   namespace,
-                  nodeName: options.node ? options.node : env === 'development' ? 'kind-worker' : os.hostname(),
+                  nodeName: Underpost.deploy.resolveDeployNode({
+                    node: options.node,
+                    kind: options.kind,
+                    kubeadm: options.kubeadm,
+                    k3s: options.k3s,
+                    env,
+                  }),
                   clusterContext: options.k3s ? 'k3s' : options.kubeadm ? 'kubeadm' : 'kind',
                   gitClean: options.gitClean || false,
+                  sshKeyPath: options.sshKeyPath || '',
                 });
           }
 
@@ -987,10 +1009,17 @@ EOF`);
      */
     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=/home/dd/engine/engine-private/conf/${cronDeployId}/.env.${env} --dry-run=client -o yaml | kubectl apply -f - -n ${namespace}`,
+        `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.
@@ -1036,6 +1065,37 @@ EOF`);
       Underpost.env.set(`${deployId}-${env}-traffic`, targetTraffic);
     },
 
+    /**
+     * Resolves the effective target node for a deployment, applying a single
+     * precedence chain shared by every deploy workflow — the default `deploy`
+     * callback, `run sync`, and custom `run instance` — so node customization
+     * 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`).
+     *   2. **Cluster-type default** — when no explicit node is given: `kind-worker`
+     *      for a kind cluster (the node that hosts kind hostPath volumes),
+     *      otherwise the control-plane / current host (`os.hostname()`) for
+     *      kubeadm / k3s. With no explicit cluster flag, `development` is treated
+     *      as kind and `production` as the host, preserving legacy behaviour.
+     *
+     * @param {object} params
+     * @param {string} [params.node=''] - Explicit node (`--node`); highest precedence.
+     * @param {boolean} [params.kind=false] - Kind cluster context.
+     * @param {boolean} [params.kubeadm=false] - Kubeadm cluster context.
+     * @param {boolean} [params.k3s=false] - K3s cluster context.
+     * @param {string} [params.env=''] - Deployment environment; tie-breaker when no cluster flag is set.
+     * @returns {string} The effective node name.
+     * @memberof UnderpostDeploy
+     */
+    resolveDeployNode({ node = '', kind = false, kubeadm = false, k3s = false, env = '' } = {}) {
+      if (node) return node;
+      const isKind = kind || (!kubeadm && !k3s && env !== 'production');
+      return isKind ? 'kind-worker' : os.hostname();
+    },
+
     /**
      * Deploys a volume for a deployment.
      * @param {object} volume - Volume configuration.
@@ -1047,9 +1107,10 @@ EOF`);
      * @param {string} options.env - Environment for the deployment.
      * @param {string} options.version - Version of the deployment.
      * @param {string} options.namespace - Kubernetes namespace for the deployment.
-     * @param {string} options.nodeName - Node name for the deployment.
+     * @param {string} options.nodeName - Effective target node (already resolved via {@link UnderpostDeploy.resolveDeployNode}). The volume data is written/shipped here and the PV is pinned to it; an empty value falls back to the cluster-type default inside this method.
      * @param {string} [options.clusterContext='kind'] - Cluster context type ('kind', 'kubeadm', or 'k3s').
      * @param {boolean} [options.gitClean=false] - Whether to run git clean on volumeMountPath before copying.
+     * @param {string} [options.sshKeyPath=''] - Private key path used when the target node is remote and the volume is shipped over SSH. Empty falls back to copyDirToNode's default (engine-private/deploy/id_rsa).
      * @memberof UnderpostDeploy
      */
     deployVolume(
@@ -1062,6 +1123,7 @@ EOF`);
         nodeName: '',
         clusterContext: 'kind',
         gitClean: false,
+        sshKeyPath: '',
       },
     ) {
       if (!volume.claimName) {
@@ -1076,16 +1138,48 @@ EOF`);
       if (options.gitClean && volume.volumeMountPath) {
         Underpost.repo.clean({ paths: [volume.volumeMountPath] });
       }
+      // The node that physically receives the volume data. hostPath volumes are
+      // node-local, so the data must land on the node where the pod will run, and
+      // the PV is pinned there (nodeAffinity) so the scheduler co-locates the pod
+      // with its volume — never mounting an empty DirectoryOrCreate on another node.
+      let dataNode;
       if (clusterContext === 'kind') {
         const kindNode = options.nodeName || 'kind-worker';
+        dataNode = kindNode;
         shellExec(`docker exec -i ${kindNode} bash -c "mkdir -p ${rootVolumeHostPath}"`);
         shellExec(`tar -C ${volume.volumeMountPath} -c . | docker cp - ${kindNode}:${rootVolumeHostPath}`);
         shellExec(
           `docker exec -i ${kindNode} bash -c "chown -R 1000:1000 ${rootVolumeHostPath}; chmod -R 755 ${rootVolumeHostPath}"`,
         );
       } else {
-        if (!fs.existsSync(rootVolumeHostPath)) fs.mkdirSync(rootVolumeHostPath, { recursive: true });
-        fs.copySync(volume.volumeMountPath, rootVolumeHostPath);
+        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 });
+          fs.copySync(volume.volumeMountPath, 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
+          // the node over SSH so the data exists where the pod is pinned.
+          const nodeHost =
+            shellExec(
+              `kubectl get node ${dataNode} -o jsonpath='{.status.addresses[?(@.type=="InternalIP")].address}'`,
+              { stdout: true, silent: true, silentOnError: true },
+            ).trim() || dataNode;
+          logger.info('Shipping volume to remote node over SSH', {
+            node: dataNode,
+            host: nodeHost,
+            src: volume.volumeMountPath,
+            dest: rootVolumeHostPath,
+          });
+          Underpost.ssh.copyDirToNode({
+            host: nodeHost,
+            localDir: volume.volumeMountPath,
+            remoteDir: rootVolumeHostPath,
+            ...(options.sshKeyPath ? { keyPath: options.sshKeyPath } : {}),
+          });
+        }
       }
       shellExec(`kubectl delete pvc ${pvcId} -n ${namespace} --ignore-not-found`);
       shellExec(`kubectl delete pv ${pvId} --ignore-not-found`);
@@ -1094,6 +1188,7 @@ ${Underpost.deploy.persistentVolumeFactory({
   hostPath: rootVolumeHostPath,
   pvcId,
   namespace,
+  nodeName: dataNode,
 })}
 EOF
 `);
@@ -1182,11 +1277,28 @@ ${secret ? `          readOnly: true\n` : ''}`;
      * @param {string} options.hostPath - Host path for the persistent volume.
      * @param {string} options.pvcId - Persistent volume claim ID.
      * @param {string} [options.namespace='default'] - Kubernetes namespace for the PVC claimRef.
+     * @param {string} [options.nodeName=''] - Node name to which the persistent volume is pinned (optional).
      * @returns {string} - YAML configuration for the persistent volume and claim.
      * @memberof UnderpostDeploy
      */
-    persistentVolumeFactory({ hostPath, pvcId, namespace = 'default' }) {
+    persistentVolumeFactory({ hostPath, pvcId, namespace = 'default', nodeName = '' }) {
       const pvId = pvcId.replace(/^pvc-/, 'pv-');
+      // hostPath volumes are node-local: deployVolume writes the content to the
+      // filesystem of a single node. Without nodeAffinity the scheduler can place
+      // the pod on a different node and mount an empty DirectoryOrCreate hostPath
+      // (missing the materialized assets). Pin the PV to the node that holds the
+      // data so the pod is always co-located with its volume.
+      const nodeAffinity = nodeName
+        ? `
+  nodeAffinity:
+    required:
+      nodeSelectorTerms:
+        - matchExpressions:
+            - key: kubernetes.io/hostname
+              operator: In
+              values:
+                - ${nodeName}`
+        : '';
       return `apiVersion: v1
 kind: PersistentVolume
 metadata:
@@ -1197,7 +1309,7 @@ spec:
   accessModes:
     - ReadWriteOnce
   persistentVolumeReclaimPolicy: Retain
-  storageClassName: manual
+  storageClassName: manual${nodeAffinity}
   claimRef:
     apiVersion: v1
     kind: PersistentVolumeClaim

package/src/cli/docker-compose.js

@@ -77,14 +77,42 @@ class UnderpostDockerCompose {
     return nodePath.isAbsolute(relPath) ? relPath : nodePath.join(getRootDirectory(), relPath);
   }
 
+  /**
+   * Resolves the canonical directory for a custom docker-compose workflow,
+   * keyed by `--deploy-id` + `--docker-compose-id`:
+   * `engine-private/conf/<deploy-id>/docker-compose/<docker-compose-id>`.
+   * This directory ships its own `docker-compose.yml`, `compose.env`, and
+   * `nginx.conf` (used as-is, never generated). Returns null when
+   * `--docker-compose-id` is not set (the default, self-generating workflow).
+   * @param {object} options - CLI options.
+   * @returns {string|null} Repo-root-relative canonical dir, or null.
+   * @memberof UnderpostDockerCompose
+   */
+  static composeIdBase(options = {}) {
+    if (!options.dockerComposeId) return null;
+    const deployId = options.deployId || DEFAULT_DEPLOY_ID;
+    return `engine-private/conf/${deployId}/docker-compose/${options.dockerComposeId}`;
+  }
+
   /**
    * Builds the base `docker compose` invocation with explicit file and env-file,
    * so behavior is independent of the caller's working directory.
+   *
+   * Custom workflow (`--docker-compose-id`): the compose file, env-file, and
+   * bind-mounted config (nginx.conf, mongodb/) all live in the canonical dir, so
+   * compose runs with `--project-directory` pinned there and no app-override.
    * @param {object} options - CLI options.
    * @returns {string} The base command string (without a subcommand).
    * @memberof UnderpostDockerCompose
    */
   static baseCmd(options = {}) {
+    const base = UnderpostDockerCompose.composeIdBase(options);
+    if (base) {
+      const projectDir = UnderpostDockerCompose.resolve(base);
+      const composeFile = UnderpostDockerCompose.resolve(options.composeFile || `${base}/docker-compose.yml`);
+      const envFile = UnderpostDockerCompose.resolve(options.envFile || `${base}/compose.env`);
+      return `docker compose --project-directory ${projectDir} --env-file ${envFile} -f ${composeFile}`;
+    }
     const composeFile = UnderpostDockerCompose.resolve(options.composeFile || 'docker-compose.yml');
     const envFile = UnderpostDockerCompose.resolve(options.envFile || 'docker/compose.env');
     const overrideFile = UnderpostDockerCompose.resolve(options.appOverride || 'docker/compose.app.yml');
@@ -163,7 +191,7 @@ services:
 MONGO_IMAGE=mongo:latest
 VALKEY_IMAGE=valkey/valkey:latest
 APP_IMAGE=underpost/underpost-engine
-APP_TAG=v3.2.22
+APP_TAG=v3.2.70
 PROXY_IMAGE=nginx:stable-alpine
 PROMETHEUS_IMAGE=prom/prometheus:latest
 GRAFANA_IMAGE=grafana/grafana:latest
@@ -343,6 +371,20 @@ datasources:
    * @memberof UnderpostDockerCompose
    */
   static generate(options = {}) {
+    // Custom workflow: docker-compose.yml, compose.env, and nginx.conf are
+    // pre-authored in the canonical dir and used as-is — do NOT generate them.
+    // Only (re)write the required MongoDB entrypoint (replica-set bootstrap),
+    // the single generated infra artifact, into <canonical>/mongodb so the
+    // stack stays self-contained under `--project-directory`.
+    const composeIdBase = UnderpostDockerCompose.composeIdBase(options);
+    if (composeIdBase) {
+      const mongoEntrypointPath = UnderpostDockerCompose.resolve(`${composeIdBase}/mongodb/entrypoint.sh`);
+      fs.mkdirpSync(nodePath.dirname(mongoEntrypointPath));
+      fs.writeFileSync(mongoEntrypointPath, UnderpostDockerCompose.mongoEntrypointContent(), { mode: 0o755 });
+      logger.info('mongodb entrypoint written (custom workflow)', { path: mongoEntrypointPath });
+      return;
+    }
+
     Nginx.removeRouter();
     for (const { host, routes } of PROXY_HOSTS) Nginx.createApp({ host, routes });
     Nginx.createDefaultServer(DEFAULT_UPSTREAM);
@@ -449,6 +491,20 @@ datasources:
       silentOnError: true,
     });
 
+    // Custom workflow: the compose file, compose.env, and nginx.conf are
+    // hand-authored source — never prune them. Only drop the one generated
+    // artifact (the mongo entrypoint), regenerated on the next --up/--generate.
+    const composeIdBase = UnderpostDockerCompose.composeIdBase(options);
+    if (composeIdBase) {
+      const mongoEntrypointPath = UnderpostDockerCompose.resolve(`${composeIdBase}/mongodb/entrypoint.sh`);
+      if (fs.existsSync(mongoEntrypointPath)) {
+        fs.removeSync(mongoEntrypointPath);
+        logger.info('removed generated artifact', { path: mongoEntrypointPath });
+      }
+      logger.info('Docker Compose reset complete. Run `--up` to recreate the stack.');
+      return;
+    }
+
     // Phase 2: prune generated artifacts (regenerated on the next --generate/--up).
     const artifacts = options.force
       ? [...GENERATED_ARTIFACTS, options.envFile || 'docker/compose.env']
@@ -489,6 +545,7 @@ datasources:
      * @param {boolean} [options.shell] - Open an interactive shell in `target` (default: app).
      * @param {string} [options.exec] - General-purpose passthrough docker compose subcommand.
      * @param {string} [options.deployId] - Deployment to run as the app (default: dd-default). `dd-default` self-bootstraps a fresh engine; any other id runs the standard `underpost start` command.
+     * @param {string} [options.dockerComposeId] - Custom-workflow selector. When set, use the canonical stack at `engine-private/conf/<deploy-id>/docker-compose/<docker-compose-id>/` (docker-compose.yml + compose.env + nginx.conf, used as-is), skipping nginx/env/app-override generation. Used by the Cyberia MMO ecosystem (`--deploy-id dd-cyberia --docker-compose-id cyberia`).
      * @param {string} [options.env] - Deployment environment for non-default deploy ids (default: development).
      * @param {string} [options.composeFile] - Override compose file path.
      * @param {string} [options.envFile] - Override env-file path.

package/src/cli/env.js

@@ -143,12 +143,21 @@ class UnderpostRootEnv {
     /**
      * @method clean
      * @description Cleans the underpost root environment by removing the environment file.
+     * @param {object} options - Options for cleaning the environment.
+     * @param {Array<string>} [options.keepKeys=[]] - List of keys to keep in the environment file. If provided, only these keys will be retained.
      * @memberof UnderpostEnv
      */
-    clean() {
+    clean(options = { keepKeys: [] }) {
+      const { keepKeys } = options;
       const exeRootPath = `${getNpmRootPath()}/underpost`;
       const envPath = `${exeRootPath}/.env`;
-      fs.removeSync(envPath);
+      if (keepKeys && keepKeys.length > 0 && fs.existsSync(envPath)) {
+        const env = dotenv.parse(fs.readFileSync(envPath, 'utf8'));
+        const filteredEnv = Object.fromEntries(Object.entries(env).filter(([key]) => keepKeys.includes(key)));
+        writeEnv(envPath, filteredEnv);
+      } else {
+        fs.removeSync(envPath);
+      }
     },
     /**
      * @method isInsideContainer

package/src/cli/fs.js

@@ -64,6 +64,31 @@ class UnderpostFileStorage {
     writeStorageConf(storage, storageConf) {
       if (storage) fs.writeFileSync(storageConf, JSON.stringify(storage, null, 4), 'utf8');
     },
+    /**
+     * @method gitTrack
+     * @description Optional, non-fatal Git tracking layer. Any Git error is logged and swallowed
+     * so it can never interrupt or roll back the canonical `storage.*.json` workflow.
+     * @param {string} gitPath - The working directory to stage/commit.
+     * @param {object} [options] - Tracking options.
+     * @param {boolean} [options.init=false] - If true, initialize a local repo before staging.
+     * @param {string} [options.message=''] - Explicit commit message; when omitted, `underpost cmt` is used.
+     * @memberof UnderpostFileStorage
+     */
+    gitTrack(gitPath, options = { init: false, message: '' }) {
+      try {
+        if (options.init === true) Underpost.repo.initLocalRepo({ path: gitPath });
+        shellExec(`cd ${gitPath} && git add .`, { silentOnError: true, silent: true, disableLog: true });
+        if (options.message)
+          shellExec(`cd ${gitPath} && git commit -m "${options.message}"`, {
+            silentOnError: true,
+            silent: true,
+            disableLog: true,
+          });
+        else shellExec(`underpost cmt ${gitPath} feat`, { silentOnError: true, silent: true, disableLog: true });
+      } catch (error) {
+        logger.warn('git tracking skipped (non-fatal)', { gitPath, error: error?.message });
+      }
+    },
     /**
      * @method recursiveCallback
      * @description Recursively processes files and directories based on the provided options.
@@ -125,6 +150,7 @@ class UnderpostFileStorage {
 
         if (hasPathFilter && options.force === true && fs.existsSync(basePath)) fs.removeSync(basePath);
 
+        // Storage is canonical: persist the removal before any (optional) git tracking runs.
         Underpost.fs.writeStorageConf(storage, storageConf);
 
         if (associatedPaths.length === 0)
@@ -136,13 +162,8 @@ class UnderpostFileStorage {
           });
 
         if (options.git === true) {
-          const gitPath = hasPathFilter ? basePath : '.';
-          shellExec(`cd ${gitPath} && git add .`);
-          shellExec(`underpost cmt ${gitPath} feat`, {
-            silentOnError: true,
-            silent: true,
-            disableLog: true,
-          });
+          const gitPath = !hasPathFilter ? '.' : isSingleFile ? parentDir : basePath;
+          Underpost.fs.gitTrack(gitPath);
         }
 
         return;
@@ -151,7 +172,16 @@ class UnderpostFileStorage {
       // For single files, run getDeleteFiles against the parent directory to avoid
       // trying to `cd` into a file.
       const gitContextPath = isSingleFile ? parentDir : path;
-      const deleteFiles = options.pull === true ? [] : Underpost.repo.getDeleteFiles(gitContextPath);
+      // Detecting locally-deleted files is a best-effort enhancement backed by git; if the path is
+      // not a repo (or git is unavailable) it must not block the canonical storage workflow.
+      let deleteFiles = [];
+      if (options.pull !== true) {
+        try {
+          deleteFiles = Underpost.repo.getDeleteFiles(gitContextPath);
+        } catch (error) {
+          logger.warn('delete detection skipped (git unavailable)', { path: gitContextPath, error: error?.message });
+        }
+      }
 
       // When processing a single file, only consider it for deletion
       for (const relativePath of deleteFiles) {
@@ -172,12 +202,7 @@ class UnderpostFileStorage {
         if (pullSkipCount > 0) logger.warn(`Pull skipped ${pullSkipCount} files that already exist`);
         // Only run git init/commit when the caller explicitly requests git tracking (--git flag).
         // For bundle pulls into ./build the git step is unwanted and would error on a non-repo path.
-        if (options.git === true) {
-          Underpost.repo.initLocalRepo({ path: gitContextPath });
-          shellExec(`cd ${gitContextPath} && git add . && git commit -m "Base pull state"`, {
-            silentOnError: true,
-          });
-        }
+        if (options.git === true) Underpost.fs.gitTrack(gitContextPath, { init: true, message: 'Base pull state' });
       } else {
         let files;
         if (isSingleFile) {
@@ -200,15 +225,9 @@ class UnderpostFileStorage {
           } else logger.warn('File already exists', _path);
         }
       }
+      // Storage is canonical and always persisted; git is an optional layer on top.
       Underpost.fs.writeStorageConf(storage, storageConf);
-      if (options.git === true) {
-        shellExec(`cd ${gitContextPath} && git add .`);
-        shellExec(`underpost cmt ${gitContextPath} feat`, {
-          silentOnError: true,
-          silent: true,
-          disableLog: true,
-        });
-      }
+      if (options.git === true) Underpost.fs.gitTrack(gitContextPath);
     },
     /**
      * @method callback
@@ -230,10 +249,12 @@ class UnderpostFileStorage {
       path,
       options = { rm: false, recursive: false, deployId: '', force: false, pull: false, git: false, omitUnzip: false },
     ) {
-      if (options.recursive === true || options.git === true)
+      // rm always routes through recursiveCallback so storage.*.json is updated regardless of
+      // --recursive/--git. The bare `delete` primitive only removes the remote asset and would
+      // otherwise leave the tracked storage key orphaned.
+      if (options.recursive === true || options.git === true || options.rm === true)
         return await Underpost.fs.recursiveCallback(path, options);
       if (options.pull === true) return await Underpost.fs.pull(path, options);
-      if (options.rm === true) return await Underpost.fs.delete(path, options);
       return await Underpost.fs.upload(path, options);
     },
     /**