@underpostnet/cyberia 3.3.73 → 3.3.76

package/src/api/object-layer/object-layer.service.js

@@ -15,13 +15,18 @@ import { loggerFactory } from '../../server/ops/logger.js';
 import { ObjectLayerRenderFramesDto } from '../object-layer-render-frames/object-layer-render-frames.model.js';
 import { FileFactory } from '../file/file.service.js';
 import fs from 'fs-extra';
+import os from 'node:os';
+import path from 'node:path';
+import sharp from 'sharp';
+import { validateStats } from '../../client/components/cyberia/SharedDefaultsCyberia.js';
 import { ObjectLayerDto } from './object-layer.model.js';
 import { ObjectLayerEngine } from '../../projects/cyberia/object-layer.js';
 import { shellExec } from '../../server/runtime/process.js';
 import { DataQuery } from '../../server/storage/data-query.js';
 import { AtlasSpriteSheetService } from '../atlas-sprite-sheet/atlas-sprite-sheet.service.js';
+import { AtlasSpriteSheetStore } from '../../projects/cyberia/atlas-sprite-sheet-store.js';
 import { IpfsClient } from '../../projects/cyberia/ipfs-client.js';
-import { createPinRecord, removePinRecordsAndUnpin } from '../ipfs/ipfs.service.js';
+import { removePinRecordsAndUnpin } from '../ipfs/ipfs.service.js';
 
 /**
  * Logger instance for this module.
@@ -45,8 +50,8 @@ class ObjectLayerService {
    * - `/metadata/:itemType/:itemId` — Create an object layer from uploaded frames and metadata.
    * - Default — Create an object layer directly from the request body.
    *
-   * The `/metadata` and default routes delegate to {@link ObjectLayerEngine.createObjectLayerDocuments}
-   * for document creation, atlas generation, SHA-256 computation, and IPFS pinning.
+   * The `/metadata` and default routes delegate to {@link ObjectLayerEngine.persistObjectLayerDocuments}
+   * for the document write, atlas generation, SHA-256 computation, and IPFS pinning.
    *
    * @async
    * @function post
@@ -160,22 +165,12 @@ class ObjectLayerService {
           metadataOverride: req.body,
         });
 
-      const { objectLayer } = await ObjectLayerEngine.createObjectLayerDocuments({
+      const { objectLayer } = await ObjectLayerEngine.persistObjectLayerDocuments({
         ObjectLayer,
         ObjectLayerRenderFrames,
         objectLayerRenderFramesData,
         objectLayerData,
-        createOptions: {
-          generateAtlas: true,
-          atlasServiceContext: {
-            req,
-            res,
-            options,
-            AtlasSpriteSheetService,
-            IpfsClient,
-            createPinRecord,
-          },
-        },
+        persistOptions: { options },
       });
 
       return objectLayer;
@@ -191,44 +186,32 @@ class ObjectLayerService {
     bodyData.data.render.cid = '';
     bodyData.data.render.metadataCid = '';
 
-    // If has render frames, generate atlas + CIDs BEFORE creating the ObjectLayer
+    // Stage the atlas CIDs before the write, so the document is never stored without them.
     if (bodyData.objectLayerRenderFramesId) {
       const renderFramesDoc = await ObjectLayerRenderFrames.findById(bodyData.objectLayerRenderFramesId);
       if (renderFramesDoc) {
         try {
-          const stagingOL = {
-            data: bodyData.data,
-            objectLayerRenderFramesId: renderFramesDoc,
-          };
-          const result = await AtlasSpriteSheetService.generate(
-            { objectLayer: stagingOL, auth: req.auth },
-            res,
+          const { atlasDoc, atlasCid, atlasMetadataCid } = await AtlasSpriteSheetStore.persist({
+            itemKey: bodyData.data.item.id,
+            objectLayerRenderFrames: renderFramesDoc,
             options,
-            { skipObjectLayerSave: true },
-          );
-          bodyData.data.render.cid = result.atlasCid;
-          bodyData.data.render.metadataCid = result.atlasMetadataCid;
-          bodyData.atlasSpriteSheetId = result.atlasDoc._id;
+          });
+          bodyData.data.render.cid = atlasCid;
+          bodyData.data.render.metadataCid = atlasMetadataCid;
+          bodyData.atlasSpriteSheetId = atlasDoc._id;
         } catch (atlasError) {
           logger.error('Failed to auto-generate atlas for new ObjectLayer:', atlasError);
         }
       }
     }
 
-    // Pin data JSON to IPFS
-    try {
-      const itemId = bodyData.data.item.id;
-      const mfsPath = `/object-layer/${itemId}/${itemId}_data.json`;
-      const ipfsResult = await IpfsClient.addJsonToIpfs(bodyData.data, `${itemId}_data.json`, mfsPath);
-      if (ipfsResult) {
-        bodyData.cid = ipfsResult.cid;
-        await createPinRecord({ cid: ipfsResult.cid, resourceType: 'object-layer-data', mfsPath, options });
-      }
-    } catch (ipfsError) {
-      logger.warn('Failed to pin data JSON to IPFS:', ipfsError.message);
-    }
+    const dataCid = await ObjectLayerEngine.pinObjectLayerData({
+      data: bodyData.data,
+      itemId: bodyData.data.item.id,
+      options,
+    });
+    if (dataCid) bodyData.cid = dataCid;
 
-    // Atomic create/replace – ObjectLayer is fully populated with all CIDs
     return await (await ObjectLayer.upsertByItemId(bodyData)).populate('objectLayerRenderFramesId');
   };
 
@@ -257,25 +240,33 @@ class ObjectLayerService {
     /** @type {import('./object-layer.model.js').ObjectLayerModel} */
     const ObjectLayer = DataBaseProviderService.getModel('ObjectLayer', options);
 
-    // GET /search-item-ids?q=<partial> - Fast partial match search on data.item.id
+    // Object layers are addressed by item id, the key the editor navigates by.
+    const keyFilter = (key) => DataQuery.naturalKeyFilter('data.item.id', key);
+
+    // GET /search-item-ids - item identity, by prefix (`q`, for type-ahead) or by exact ids
+    // (`ids`, comma separated). Carries the item's type because that is what addresses its
+    // sprite directory; an id alone cannot be previewed.
     if (req.path.startsWith('/search-item-ids')) {
       const q = (req.query.q || '').trim();
-      if (!q) return { itemIds: [] };
-      // Escape regex special characters for safe partial matching
-      const escaped = q.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-      const results = await ObjectLayer.find(
-        { 'data.item.id': { $regex: escaped, $options: 'i' } },
-        { 'data.item.id': 1, _id: 0 },
-      )
-        .limit(20)
+      const ids = String(req.query.ids || '')
+        .split(',')
+        .map((id) => id.trim())
+        .filter(Boolean);
+      if (!q && ids.length === 0) return { items: [] };
+      const query = ids.length
+        ? { 'data.item.id': { $in: ids } }
+        : // Escape regex special characters for safe partial matching
+          { 'data.item.id': { $regex: q.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), $options: 'i' } };
+      const results = await ObjectLayer.find(query, { 'data.item.id': 1, 'data.item.type': 1, _id: 0 })
+        .limit(ids.length ? ids.length : 20)
         .lean();
-      const itemIds = [...new Set(results.map((r) => r.data.item.id))];
-      return { itemIds };
+      const byId = new Map(results.map((r) => [r.data.item.id, r.data.item.type || '']));
+      return { items: [...byId].map(([id, type]) => ({ id, type })) };
     }
 
     // GET /frame-counts/:id - Get frame counts for each direction using numeric codes
     if (req.path.startsWith('/frame-counts/')) {
-      const objectLayer = await ObjectLayer.findById(req.params.id)
+      const objectLayer = await ObjectLayer.findOne(keyFilter(req.params.id))
         .select(ObjectLayerDto.select.getMetadata())
         .populate('objectLayerRenderFramesId');
       if (!objectLayer) {
@@ -318,7 +309,7 @@ class ObjectLayerService {
 
     // GET /render/:id - Get only render data for specific object layer
     if (req.path.startsWith('/render/')) {
-      const objectLayer = await ObjectLayer.findById(req.params.id)
+      const objectLayer = await ObjectLayer.findOne(keyFilter(req.params.id))
         .select(ObjectLayerDto.select.getRender())
         .populate('objectLayerRenderFramesId');
       if (!objectLayer) {
@@ -333,7 +324,7 @@ class ObjectLayerService {
 
     // GET /metadata/:id - Get only metadata (no render frames/colors) for specific object layer
     if (req.path.startsWith('/metadata/')) {
-      const objectLayer = await ObjectLayer.findById(req.params.id)
+      const objectLayer = await ObjectLayer.findOne(keyFilter(req.params.id))
         .select(ObjectLayerDto.select.getMetadata())
         .populate('objectLayerRenderFramesId', ObjectLayerRenderFramesDto.select.get());
       if (!objectLayer) {
@@ -385,22 +376,14 @@ class ObjectLayerService {
     }
 
     // GET / - Get paginated list of object layers
-    const id = req.params.id || req.query.id;
-    logger.info(`ObjectLayerService.get - filtering check - id: ${id}`);
-    if (id && id !== 'undefined' && !['render', 'metadata', 'frame-counts'].includes(id)) {
-      try {
-        const objectLayer = await ObjectLayer.findById(id)
-          .select(ObjectLayerDto.select.get())
-          .populate('atlasSpriteSheetId', 'cid')
-          .populate('objectLayerRenderFramesId', ObjectLayerRenderFramesDto.select.get());
-        if (objectLayer) {
-          logger.info(`ObjectLayerService.get - found record by id: ${id}`);
-          return { data: [objectLayer], total: 1, page: 1, totalPages: 1 };
-        }
-        logger.warn(`ObjectLayerService.get - record NOT found for id: ${id}`);
-      } catch (e) {
-        logger.warn(`Invalid ID format or not found: ${id}`);
-      }
+    const key = req.params.id || req.query.id;
+    if (key && key !== 'undefined' && !['render', 'metadata', 'frame-counts'].includes(key)) {
+      const objectLayer = await ObjectLayer.findOne(keyFilter(key))
+        .select(ObjectLayerDto.select.get())
+        .populate('atlasSpriteSheetId', 'cid')
+        .populate('objectLayerRenderFramesId', ObjectLayerRenderFramesDto.select.get());
+      if (objectLayer) return { data: [objectLayer], total: 1, page: 1, totalPages: 1 };
+      logger.warn(`ObjectLayerService.get - no object layer for key: ${key}`);
     }
 
     const { query, sort, skip, limit, page } = DataQuery.parse(req.query);
@@ -493,9 +476,14 @@ class ObjectLayerService {
     // Create temporary output file path
     const tempOutputPath = `${framesFolder}/${tmpOutputFileName}`;
 
+    // img2webp takes one frame size, and frames of one direction may differ: the game
+    // stretches each to the entity's cell box, so the preview stretches them to the
+    // largest one — nearest-neighbour, since a scaled frame is still pixel art.
+    const stagedFolder = await ObjectLayerService.stageUniformFrames(framesFolder, pngFiles);
+
     try {
       // Change to the frames directory and execute img2webp command
-      const cmd = `cd "${framesFolder}" && img2webp -d ${frameDuration} -loop 0 *.png -o ${tmpOutputFileName}`;
+      const cmd = `cd "${stagedFolder ?? framesFolder}" && img2webp -d ${frameDuration} -loop 0 *.png -o "${path.resolve(tempOutputPath)}"`;
 
       logger.info(`Executing command: ${cmd}`);
 
@@ -546,9 +534,41 @@ class ObjectLayerService {
       }
 
       throw error;
+    } finally {
+      if (stagedFolder) await fs.remove(stagedFolder);
     }
   };
 
+  /**
+   * Stages copies of the frames resized to one common size when they differ, or returns null
+   * when they already share one and can be encoded in place.
+   * @function stageUniformFrames
+   * @memberof ObjectLayerService
+   * @param {string} framesFolder - Directory holding the direction's PNG frames.
+   * @param {string[]} pngFiles - Frame file names, in animation order.
+   * @returns {Promise<string|null>} Temporary directory with the resized frames, or null.
+   */
+  static stageUniformFrames = async (framesFolder, pngFiles) => {
+    const sizes = await Promise.all(
+      pngFiles.map(async (file) => {
+        const { width, height } = await sharp(`${framesFolder}/${file}`).metadata();
+        return { file, width, height };
+      }),
+    );
+    const width = Math.max(...sizes.map((size) => size.width));
+    const height = Math.max(...sizes.map((size) => size.height));
+    if (sizes.every((size) => size.width === width && size.height === height)) return null;
+
+    const stagedFolder = await fs.mkdtemp(path.join(os.tmpdir(), 'ol-webp-'));
+    for (const { file } of sizes) {
+      await sharp(`${framesFolder}/${file}`)
+        .resize(width, height, { fit: 'fill', kernel: 'nearest' })
+        .toFile(`${stagedFolder}/${file}`);
+    }
+    logger.info(`Staged ${pngFiles.length} frame(s) at ${width}x${height} for webp encoding`);
+    return stagedFolder;
+  };
+
   /**
    * PUT handler for updating object layers, their frame images, and metadata.
    *
@@ -557,8 +577,8 @@ class ObjectLayerService {
    * - `/:id/metadata/:itemType/:itemId` — Update metadata and reprocess all frames.
    * - `/:id` — Standard update from request body.
    *
-   * The `/metadata` route delegates to {@link ObjectLayerEngine.updateObjectLayerDocuments}
-   * for document update, atlas regeneration, SHA-256 computation, and IPFS pinning.
+   * The `/metadata` route delegates to {@link ObjectLayerEngine.persistObjectLayerDocuments}
+   * for the document write, atlas regeneration, SHA-256 computation, and IPFS pinning.
    *
    * @async
    * @function put
@@ -652,7 +672,6 @@ class ObjectLayerService {
 
     // PUT /:id/metadata/:itemType/:itemId - Update object layer metadata and reprocess all frames
     if (req.path.includes('/metadata/')) {
-      const objectLayerId = req.params.id;
       const itemType = req.params.itemType;
       const itemId = req.params.itemId;
 
@@ -683,24 +702,12 @@ class ObjectLayerService {
           metadataOverride: req.body,
         });
 
-      // Update documents using engine method (with atlas generation)
-      const { objectLayer } = await ObjectLayerEngine.updateObjectLayerDocuments({
-        objectLayerId,
+      const { objectLayer } = await ObjectLayerEngine.persistObjectLayerDocuments({
         ObjectLayer,
         ObjectLayerRenderFrames,
         objectLayerRenderFramesData,
         objectLayerData,
-        updateOptions: {
-          generateAtlas: true,
-          atlasServiceContext: {
-            req,
-            res,
-            options,
-            AtlasSpriteSheetService,
-            IpfsClient,
-            createPinRecord,
-          },
-        },
+        persistOptions: { options },
       });
 
       return objectLayer;
@@ -715,25 +722,19 @@ class ObjectLayerService {
     // Apply body updates to staging data in memory
     const updateData = { ...req.body };
     const stagingData = updateData.data || existingOL.data.toObject();
+    stagingData.stats = validateStats(stagingData.stats);
     if (!stagingData.render) stagingData.render = {};
 
-    // Use existing render frames if available
-    const renderFramesData = existingOL.objectLayerRenderFramesId;
-    if (renderFramesData) {
+    if (existingOL.objectLayerRenderFramesId) {
       try {
-        const stagingOL = {
-          data: stagingData,
-          objectLayerRenderFramesId: renderFramesData,
-        };
-        const result = await AtlasSpriteSheetService.generate(
-          { objectLayer: stagingOL, auth: req.auth },
-          res,
+        const { atlasDoc, atlasCid, atlasMetadataCid } = await AtlasSpriteSheetStore.persist({
+          itemKey: stagingData.item.id,
+          objectLayerRenderFrames: existingOL.objectLayerRenderFramesId,
           options,
-          { skipObjectLayerSave: true },
-        );
-        stagingData.render.cid = result.atlasCid;
-        stagingData.render.metadataCid = result.atlasMetadataCid;
-        updateData.atlasSpriteSheetId = result.atlasDoc._id;
+        });
+        stagingData.render.cid = atlasCid;
+        stagingData.render.metadataCid = atlasMetadataCid;
+        updateData.atlasSpriteSheetId = atlasDoc._id;
       } catch (atlasError) {
         logger.error('Failed to auto-update atlas for ObjectLayer:', atlasError);
       }
@@ -742,25 +743,17 @@ class ObjectLayerService {
     updateData.data = stagingData;
     updateData.sha256 = ObjectLayerEngine.computeSha256(stagingData);
 
-    // Pin data JSON to IPFS
-    try {
-      const itemId = stagingData.item.id;
-      const mfsPath = `/object-layer/${itemId}/${itemId}_data.json`;
-      const ipfsResult = await IpfsClient.addJsonToIpfs(stagingData, `${itemId}_data.json`, mfsPath);
-      if (ipfsResult) {
-        updateData.cid = ipfsResult.cid;
-        await createPinRecord({ cid: ipfsResult.cid, resourceType: 'object-layer-data', mfsPath, options });
-      }
-    } catch (ipfsError) {
-      logger.warn('Failed to pin data JSON to IPFS:', ipfsError.message);
-    }
+    const dataCid = await ObjectLayerEngine.pinObjectLayerData({
+      data: stagingData,
+      itemId: stagingData.item.id,
+      options,
+    });
+    if (dataCid) updateData.cid = dataCid;
 
-    // Atomic update with all CIDs populated
-    let updatedObjectLayer = await ObjectLayer.findByIdAndUpdate(req.params.id, updateData, {
+    return await ObjectLayer.findByIdAndUpdate(req.params.id, updateData, {
       returnDocument: 'after',
+      runValidators: true,
     }).populate('objectLayerRenderFramesId');
-
-    return updatedObjectLayer;
   };
 
   /**

package/src/cli/app.js

@@ -205,14 +205,25 @@ class UnderpostApp {
       // The resolution loadConf performed, not `ociEnv()`, which forces the overlay on: a
       // skipped overlay and an applied one were indistinguishable in the pod log.
       const resolved = deployEnvContentFactory(deployId, context.env, `${context.args?.['sub-conf'] ?? ''}`.trim());
+      const inContainer = Underpost.state.isInsideContainer();
       logger.info('Deployment environment loaded', {
         deployId,
         instanceId: instanceId || null,
         source: envPath,
-        inContainer: Underpost.state.isInsideContainer(),
+        inContainer,
         ociOverlay: resolved.overlay,
         keys: Object.keys(values).length,
       });
+      // A container that resolves no overlay runs on the host-scoped endpoints of the base file —
+      // a loopback database, a local cache — and fails minutes later at the first connection,
+      // pointing at the endpoint rather than at the conf checkout that is missing the overlay.
+      // Named rather than thrown: a deployment is allowed to have no overlay for an environment.
+      if (inContainer && !instanceId && !resolved.overlay)
+        logger.warn('No OCI env overlay resolved; container is running on host-scoped values', {
+          deployId,
+          env: context.env,
+          expected: deployOciEnvFilePath(deployId, context.env),
+        });
       return { source: envPath, keys: Object.keys(values).length };
     },
 

package/src/cli/client.js

@@ -83,7 +83,7 @@ class UnderpostClient {
           const env = deployEnvFactory(options, process.env.NODE_ENV || 'development');
           process.env.NODE_ENV = env;
           if (options.mergeZip) {
-            mergeClientBuildZip({
+            await mergeClientBuildZip({
               buildPrefix: options.mergeZip,
               logger,
             });
@@ -91,7 +91,7 @@ class UnderpostClient {
           }
 
           if (options.unzip) {
-            unzipClientBuild({
+            await unzipClientBuild({
               buildPrefix: options.unzip,
               logger,
             });

package/src/cli/cluster.js

@@ -31,6 +31,7 @@ import {
 } from '../server/network/underpost-ingress.js';
 import { MONGODB_DEFAULT_REPLICA_COUNT } from '../db/mongo/MongooseDB.js';
 import { MongoBootstrap } from '../db/mongo/MongoBootstrap.js';
+import { MongoExpress } from '../db/mongo/MongoExpress.js';
 import os from 'os';
 import fs from 'fs-extra';
 import Underpost from '../index.js';
@@ -82,6 +83,7 @@ class UnderpostCluster {
      * @param {object} [options] - Configuration options for cluster initialization.
      * @param {boolean} [options.mongodb=false] - Deploy MongoDB.
      * @param {boolean} [options.mongodb4=false] - Deploy MongoDB 4.4.
+     * @param {boolean} [options.mongoExpress=false] - Deploy the mongo-express web client for inspecting the MongoDB StatefulSet collections.
      * @param {string} [options.serviceHost=''] - Set a custom host/IP for exposed MongoDB and Valkey clients.
      * @param {boolean} [options.mariadb=false] - Deploy MariaDB.
      * @param {boolean} [options.mysql=false] - Deploy MySQL.
@@ -129,6 +131,7 @@ class UnderpostCluster {
       options = {
         mongodb: false,
         mongodb4: false,
+        mongoExpress: false,
         serviceHost: '',
         mariadb: false,
         mysql: false,
@@ -509,6 +512,10 @@ class UnderpostCluster {
           });
       }
 
+      // After both StatefulSet branches, so one invocation can bring up MongoDB and its inspector
+      // and the client reads the auth mode from the set this run just applied.
+      if (options.mongoExpress) await MongoExpress.deploy({ namespace: options.namespace, underpostRoot, options });
+
       // Installing one stack must never break the other. Whichever is already
       // present decides whether this install takes the node's 80/443 for itself
       // or joins the underpost ingress, so it is read before anything is applied.

package/src/cli/deploy.js

@@ -147,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.
  */
@@ -617,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").
@@ -2185,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").

package/src/cli/docker-compose.js

@@ -192,7 +192,7 @@ services:
 MONGO_IMAGE=mongo:latest
 VALKEY_IMAGE=valkey/valkey:latest
 APP_IMAGE=underpost/underpost-engine
-APP_TAG=v3.3.73
+APP_TAG=v3.3.76
 PROXY_IMAGE=nginx:stable-alpine
 PROMETHEUS_IMAGE=prom/prometheus:latest
 GRAFANA_IMAGE=grafana/grafana:latest

package/src/cli/fs-selection.js

@@ -0,0 +1,115 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import UnderpostRepository from './repository.js';
+
+const manifestFilterNames = ['key', 'fromKey', 'toKey', 'keyRegex'];
+
+const normalizeStoragePath = (value) => {
+  if (value === undefined || value === '') return '';
+  const absolute = path.resolve(value);
+  const relative = path.relative(process.cwd(), absolute);
+  return (
+    path.isAbsolute(value) && (relative === '..' || relative.startsWith(`..${path.sep}`)) ? absolute : relative || '.'
+  )
+    .split(path.sep)
+    .join('/');
+};
+
+const isWithinScope = (key, scope) => {
+  if (scope === undefined || scope === '') return true;
+  const relative = path.relative(path.resolve(scope), path.resolve(key));
+  return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+};
+
+const validateSelectionOptions = (scope, options) => {
+  if (options.git && options.tracked) throw new Error('Use either --git or --tracked.');
+  if (!options.tracked && !scope) throw new Error('Provide a filesystem path, or use --tracked.');
+  if (options.rm && options.pull) throw new Error('Use either --rm or --pull.');
+  if (options.omitUnzip && !options.pull) throw new Error('--omit-unzip requires --pull.');
+};
+
+const filterManifestEntries = (entries, options = {}, scope) => {
+  const keys = entries.map(([key]) => key);
+  const keyIndex = (name) => {
+    const index = keys.indexOf(options[name]);
+    if (index < 0) throw new Error(`Manifest key not found for ${name}: ${options[name]}`);
+    return index;
+  };
+  const start = options.fromKey === undefined ? 0 : keyIndex('fromKey');
+  const end = options.toKey === undefined ? keys.length - 1 : keyIndex('toKey');
+  if (start > end && (options.fromKey !== undefined || options.toKey !== undefined))
+    throw new Error('--from-key must precede or equal --to-key.');
+
+  let regex;
+  if (options.keyRegex !== undefined) {
+    try {
+      regex = new RegExp(options.keyRegex);
+    } catch {
+      throw new Error(`Invalid --key-regex: ${options.keyRegex}`);
+    }
+  }
+  const matches = (key) => isWithinScope(key, scope) && (!regex || regex.test(key));
+  if (options.key !== undefined) {
+    const index = keyIndex('key');
+    if (index < start || index > end || !matches(options.key))
+      throw new Error('--key conflicts with the manifest range, path scope, or regex.');
+  }
+  return entries
+    .slice(start, end + 1)
+    .filter(([key]) => matches(key) && (options.key === undefined || key === options.key));
+};
+
+const resolveFilesystemSelection = (scope) => {
+  const files = [];
+  const visit = (target) => {
+    const stats = fs.statSync(target);
+    if (stats.isFile()) files.push(normalizeStoragePath(target));
+    else if (stats.isDirectory()) {
+      for (const entry of fs
+        .readdirSync(target, { withFileTypes: true })
+        .sort((a, b) => a.name.localeCompare(b.name))) {
+        const child = path.join(target, entry.name);
+        // Do not follow directory links during traversal.
+        if (entry.isSymbolicLink()) {
+          if (fs.statSync(child, { throwIfNoEntry: false })?.isFile()) files.push(normalizeStoragePath(child));
+        } else visit(child);
+      }
+    } else throw new Error(`Storage requires a regular file or directory: ${target}`);
+  };
+  visit(scope);
+  return files;
+};
+
+const resolveGitSelection = (files, scope) => {
+  const context = fs.statSync(scope).isDirectory() ? scope : path.dirname(scope);
+  const tracked = new Set(UnderpostRepository.API.getTrackedFiles(context));
+  return files.filter((file) => tracked.has(path.resolve(file)));
+};
+
+const resolveTrackedSelection = (entries) => entries.map(([key]) => key);
+
+const resolveSelection = (scope, manifest, options = {}) => {
+  validateSelectionOptions(scope, options);
+  const entries = Object.entries(manifest);
+  const filtered = filterManifestEntries(entries, options, scope);
+  if (options.tracked) return resolveTrackedSelection(filtered);
+
+  let files = resolveFilesystemSelection(scope);
+  if (options.git) files = resolveGitSelection(files, scope);
+  const manifestKeys = new Map(entries.map(([key]) => [normalizeStoragePath(key), key]));
+  files = files.map((file) => manifestKeys.get(file) ?? file);
+  if (manifestFilterNames.some((name) => options[name] !== undefined)) {
+    const selected = new Set(resolveTrackedSelection(filtered));
+    files = files.filter((file) => selected.has(file));
+  }
+  return files;
+};
+
+export {
+  normalizeStoragePath,
+  filterManifestEntries,
+  resolveFilesystemSelection,
+  resolveGitSelection,
+  resolveTrackedSelection,
+  resolveSelection,
+};