cyberia 3.2.12 → 3.2.22

package/src/cli/run.js

@@ -15,6 +15,7 @@ import {
   getNpmRootPath,
   isDeployRunnerContext,
   loadConfServerJson,
+  loadReplicas,
   writeEnv,
 } from '../server/conf.js';
 import { actionInitLog, loggerFactory } from '../server/logger.js';
@@ -119,6 +120,7 @@ const logger = loggerFactory(import.meta);
  * @property {boolean} skipFullBuild - Whether to skip the full client bundle build during deployment (supported by: sync, template-deploy).
  * @property {boolean} pullBundle - Whether to pull the bundle before running. Use together with --skip-full-build to skip the local build entirely (supported by: sync, template-deploy).
  * @property {boolean} remove - Whether to remove/teardown resources instead of creating them (e.g. delete-expose for k3s proxy devices in dev-cluster).
+ * @property {boolean} test - Whether to enable test/generic-purpose mode (e.g. use self-signed TLS instead of cert-manager).
  * @memberof UnderpostRun
  */
 const DEFAULT_OPTION = {
@@ -187,6 +189,7 @@ const DEFAULT_OPTION = {
   skipFullBuild: false,
   pullBundle: false,
   remove: false,
+  test: false,
 };
 
 /**
@@ -222,7 +225,7 @@ class UnderpostRun {
         shellExec(`${baseCommand} cluster${options.dev ? ' --dev' : ''}`);
 
         shellExec(
-          `${baseCommand} cluster${options.dev ? ' --dev' : ''} --mongodb4 --service-host ${mongoHosts.join(
+          `${baseCommand} cluster${options.dev ? ' --dev' : ''} --mongodb --service-host ${mongoHosts.join(
             ',',
           )} --pull-image`,
         );
@@ -264,6 +267,16 @@ class UnderpostRun {
       logger.info(hostListenResult.renderHosts);
     },
 
+    /**
+     * @method etc-hosts
+     * @description Modifies the `/etc/hosts` file to add entries for local access to services,
+     * based on the provided path input.
+     * @param {string} path - The input value, identifier, or path for the operation (used to specify the entries to add to /etc/hosts).
+     */
+    'etc-hosts': (path = '', options = DEFAULT_OPTION) => {
+      etcHostFactory(path.split(','));
+    },
+
     /**
      * @method ipfs-expose
      * @description Exposes IPFS Cluster services on specified ports for local access.
@@ -422,6 +435,7 @@ class UnderpostRun {
         return;
       }
       shellExec(`${baseCommand} run pull`);
+      shellExec(`${baseCommand} run shared-dir`);
 
       // Capture last N commit messages for propagation.
       // When --from-n-commit is not set, auto-detect unpushed commit count (same as --unpush flag).
@@ -502,6 +516,7 @@ class UnderpostRun {
         return;
       }
       shellExec(`${baseCommand} run pull`);
+      shellExec(`${baseCommand} run shared-dir`);
 
       // Capture last N commit messages from the engine repo.
       // When --from-n-commit is not set, auto-detect unpushed commit count (same as --unpush flag).
@@ -713,6 +728,11 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
       let targetTraffic = currentTraffic ? (currentTraffic === 'blue' ? 'green' : 'blue') : 'green';
       if (targetTraffic) versions = versions ? versions : targetTraffic;
 
+      const ignorePods =
+        isDeployRunnerContext(path, options) && targetTraffic
+          ? Underpost.kubectl.get(`${deployId}-${env}-${targetTraffic}`, 'pods', options.namespace).map((p) => p.NAME)
+          : [];
+
       const timeoutFlags = Underpost.deploy.timeoutFlagsFactory(options);
       const cmdString = options.cmd
         ? ' --cmd ' + (options.cmd.find((c) => c.match('"')) ? '"' + options.cmd + '"' : "'" + options.cmd + "'")
@@ -743,7 +763,7 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
         );
         if (!targetTraffic)
           targetTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace });
-        await Underpost.deploy.monitorReadyRunner(deployId, env, targetTraffic, [], options.namespace, 'underpost');
+        await Underpost.monitor.monitorReadyRunner(deployId, env, targetTraffic, ignorePods, options.namespace);
         Underpost.deploy.switchTraffic(deployId, env, targetTraffic, replicas, options.namespace, options);
       } else
         logger.info('current traffic', Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace }));
@@ -989,8 +1009,19 @@ echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com
             // pathRewritePolicy,
           });
         if (options.tls) {
-          shellExec(`sudo kubectl delete Certificate ${_host} -n ${options.namespace} --ignore-not-found`);
-          proxyYaml += Underpost.deploy.buildCertManagerCertificate({ ...options, host: _host });
+          if (options.test) {
+            const sslDir = `./engine-private/ssl/${_host}`;
+            const nameSafe = _host.replace(/[^a-zA-Z0-9_.-]/g, '_');
+            fs.mkdirpSync(sslDir);
+            shellExec(`bash ./scripts/ssl.sh "${sslDir}" "${_host}"`);
+            shellExec(`kubectl delete secret ${_host} -n ${options.namespace} --ignore-not-found`);
+            shellExec(
+              `kubectl create secret tls ${_host} --cert="${sslDir}/${nameSafe}.pem" --key="${sslDir}/${nameSafe}-key.pem" -n ${options.namespace}`,
+            );
+          } else {
+            shellExec(`sudo kubectl delete Certificate ${_host} -n ${options.namespace} --ignore-not-found`);
+            proxyYaml += Underpost.deploy.buildCertManagerCertificate({ ...options, host: _host });
+          }
         }
         // console.log(proxyYaml);
         shellExec(`kubectl delete HTTPProxy ${_host} --namespace ${options.namespace} --ignore-not-found`);
@@ -1059,6 +1090,7 @@ EOF
         // Examples images:
         // `underpost/underpost-engine:${Underpost.version}`
         // `localhost/rockylinux9-underpost:${Underpost.version}`
+        if (options.imageName) _image = options.imageName;
         if (!_image) _image = `underpost/underpost-engine:${Underpost.version}`;
 
         if (_image && !_image.startsWith('localhost'))
@@ -1154,12 +1186,16 @@ EOF
 `,
           { disableLog: true },
         );
-        const { ready, readyPods } = await Underpost.deploy.monitorReadyRunner(
+        // Custom instances run a bare binary (no `underpost start` / internal
+        // HTTP endpoint): Kubernetes readiness is the running signal and
+        // container-status is read via exec. See `Deploy custom instance to K8S.md`.
+        const { ready, readyPods } = await Underpost.monitor.monitorReadyRunner(
           _deployId,
           env,
           targetTraffic,
           ignorePods,
           options.namespace,
+          { readyGate: 'kubernetes', statusTransport: 'exec' },
         );
 
         if (!ready) {
@@ -1169,7 +1205,7 @@ EOF
         shellExec(
           `${baseCommand} run${baseClusterCommand} --namespace ${options.namespace}` +
             `${options.nodeName ? ` --node-name ${options.nodeName}` : ''}` +
-            `${options.tls ? ` --tls` : ''}` +
+            `${options.tls ? ` --tls ${options.test ? '--test' : ''}` : ''}` +
             ` instance-promote '${path}'`,
         );
       }
@@ -1436,8 +1472,8 @@ EOF`);
       const baseClusterCommand = options.dev ? ' --dev' : '';
       const currentImage = options.imageName
         ? options.imageName
-        : Underpost.deploy
-            .getCurrentLoadedImages(options.nodeName ? options.nodeName : 'kind-worker', false)
+        : Underpost.image
+            .getCurrentLoaded(options.nodeName ? options.nodeName : 'kind-worker', false)
             .find((o) => o.IMAGE.match('underpost'));
       const podName = options.podName || `underpost-dev-container`;
       const volumeHostPath = options.claimName || '/home/dd';
@@ -1714,20 +1750,13 @@ EOF`);
       const currentTraffic = Underpost.deploy.getCurrentTraffic(deployId, { namespace: options.namespace });
       const targetTraffic = currentTraffic === 'blue' ? 'green' : 'blue';
       const env = options.dev ? 'development' : 'production';
-      const ignorePods = Underpost.deploy
+      const ignorePods = Underpost.kubectl
         .get(`${deployId}-${env}-${targetTraffic}`, 'pods', options.namespace)
         .map((p) => p.NAME);
 
       shellExec(`sudo kubectl rollout restart deployment/${deployId}-${env}-${targetTraffic} -n ${options.namespace}`);
 
-      await Underpost.deploy.monitorReadyRunner(
-        deployId,
-        env,
-        targetTraffic,
-        ignorePods,
-        options.namespace,
-        'underpost',
-      );
+      await Underpost.monitor.monitorReadyRunner(deployId, env, targetTraffic, ignorePods, options.namespace);
 
       Underpost.deploy.switchTraffic(deployId, env, targetTraffic, options.replicas, options.namespace, options);
     },
@@ -1819,7 +1848,7 @@ EOF`);
         }`;
         shellExec(cmd, { async: true });
       }
-      await awaitDeployMonitor();
+      if ((await awaitDeployMonitor()) !== true) return;
       {
         const cmd = `npm run dev:client ${deployId} ${subConf} ${host} ${_path} proxy${options.tls ? ' tls' : ''}`;
 
@@ -1827,7 +1856,7 @@ EOF`);
           async: true,
         });
       }
-      await awaitDeployMonitor();
+      if ((await awaitDeployMonitor()) !== true) return;
       shellExec(
         `NODE_ENV=development node src/proxy proxy ${deployId} ${subConf} ${host} ${_path}${options.tls ? ' tls' : ''}`,
       );
@@ -2504,7 +2533,8 @@ EOF`;
     /**
      * @method push-bundle
      * @description Builds the client zip for the specified deployment, splits it into parts, and uploads to file storage.
-     *   Steps: set env, build+split zip, switch to cron env, upload parts to storage.
+     *   Steps: set env, build+split zip, upload only the zip parts belonging to the deploy-id's hosts (from conf.server.json).
+     *   Only files matching `<host>-<route>.zip.part*` or `<host>-<route>.zip` for each non-skipped route are uploaded.
      * @param {string} path - Optional `fsPath.splitOption` string.
      *   Examples: `build` (default split 8), `build.16` (split 16 MB), `build.none-split` (no split flag).
      * @param {Object} options - The default underpost runner options for customizing workflow.
@@ -2513,7 +2543,7 @@ EOF`;
      * @memberof UnderpostRun
      */
     'push-bundle': (path = '', options = DEFAULT_OPTION) => {
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const baseCommand = 'node bin'; // options.dev ? 'node bin' : 'underpost';
       const env = options.dev ? 'development' : 'production';
       const deployId = options.deployId || 'dd-default';
       const pathParts = (path || '').split('.');
@@ -2537,11 +2567,54 @@ EOF`;
         }
       }
 
+      const confServerPath = `./engine-private/conf/${deployId}/conf.server.json`;
+      const confServer = fs.existsSync(confServerPath)
+        ? loadReplicas(deployId, loadConfServerJson(confServerPath))
+        : {};
+      const storageFilePath = `engine-private/conf/${deployId}/storage.bundle.json`;
+
       shellExec(`${baseCommand} env ${deployId} ${env}`);
       shellExec(`${baseCommand} client ${deployId} --build-zip${splitFlag ? ` ${splitFlag}` : ''}`);
-      shellExec(
-        `${baseCommand} fs ${fsPath} --recursive --deploy-id ${deployId} --storage-file-path engine-private/conf/${deployId}/storage.bundle.json --force`,
-      );
+
+      const pushBundleFiles = (host, routePath) => {
+        const buildId = `${host}-${routePath.replaceAll('/', '')}`;
+        const buildDir = `./${fsPath}`;
+        if (!fs.existsSync(buildDir)) return;
+        const partFiles = fs
+          .readdirSync(buildDir)
+          .filter(
+            (name) =>
+              name.startsWith(`${buildId}.zip.part`) ||
+              name.startsWith(`${buildId}.zip-part`) ||
+              name === `${buildId}.zip`,
+          )
+          .map((name) => `${fsPath}/${name}`);
+        if (partFiles.length === 0) {
+          logger.warn(`push-bundle: no bundle files found for '${host}${routePath}'`, { buildId });
+          return;
+        }
+        for (const partFile of partFiles) {
+          shellExec(
+            `${baseCommand} fs ${partFile} --deploy-id ${deployId} --storage-file-path ${storageFilePath} --force`,
+          );
+        }
+      };
+
+      for (const host of Object.keys(confServer)) {
+        for (const routePath of Object.keys(confServer[host])) {
+          const routeConf = confServer[host][routePath] || {};
+          if (routeConf.redirect || routeConf.disabledRebuild) continue;
+          if (routeConf.singleReplica) {
+            if (routeConf.replicas) {
+              for (const replica of routeConf.replicas) {
+                pushBundleFiles(host, replica);
+              }
+            }
+            continue;
+          }
+          pushBundleFiles(host, routePath);
+        }
+      }
     },
 
     /**
@@ -2558,11 +2631,13 @@ EOF`;
      * @memberof UnderpostRun
      */
     'pull-bundle': (path = '', options = DEFAULT_OPTION) => {
-      const baseCommand = options.dev ? 'node bin' : 'underpost';
+      const baseCommand = 'node bin'; // options.dev ? 'node bin' : 'underpost';
       const env = options.dev ? 'development' : 'production';
       const deployId = options.deployId || 'dd-default';
       const confServerPath = `./engine-private/conf/${deployId}/conf.server.json`;
-      const confServer = fs.existsSync(confServerPath) ? loadConfServerJson(confServerPath) : {};
+      const confServer = fs.existsSync(confServerPath)
+        ? loadReplicas(deployId, loadConfServerJson(confServerPath))
+        : {};
       const hostsArg = path
         ? path
             .split(',')
@@ -2581,64 +2656,75 @@ EOF`;
         `${baseCommand} fs build --recursive --deploy-id ${deployId} --storage-file-path engine-private/conf/${deployId}/storage.bundle.json --pull --omit-unzip`,
       );
 
+      const pullBundleRoute = (host, routePath) => {
+        const buildId = `${host}-${routePath.replaceAll('/', '')}`;
+        const zipPath = `build/${buildId}.zip`;
+        const buildDir = './build';
+        const hasZip = fs.existsSync(zipPath);
+        const hasParts =
+          fs.existsSync(buildDir) &&
+          fs
+            .readdirSync(buildDir)
+            .some((name) => name.startsWith(`${buildId}.zip.part`) || name.startsWith(`${buildId}.zip-part`));
+
+        if (!hasZip && !hasParts) {
+          logger.warn(`Bundle not found for '${host}${routePath}'. Skipping.`, { zipPath, deployId });
+          return;
+        }
+
+        if (hasParts) shellExec(`${baseCommand} client --merge-zip ${zipPath}`);
+        shellExec(`${baseCommand} client --unzip ${zipPath}`);
+        shellExec(`sudo rm -rf ${zipPath}`);
+
+        if (fs.existsSync(buildDir)) {
+          fs.readdirSync(buildDir)
+            .filter((name) => name.startsWith(`${buildId}.zip.part`) || name.startsWith(`${buildId}.zip-part`))
+            .forEach((partFile) => shellExec(`sudo rm -rf ${buildDir}/${partFile}`));
+        }
+
+        const extractedDir = `build/${buildId.replace(/-$/, '')}`;
+        if (!fs.existsSync(extractedDir)) {
+          logger.warn(`Extracted build dir not found: ${extractedDir}. Skipping move for '${host}${routePath}'.`);
+          return;
+        }
+
+        const publicDestPath = routePath === '/' ? `public/${host}` : `public/${host}${routePath}`;
+        if (fs.existsSync(publicDestPath)) shellExec(`sudo rm -rf ${publicDestPath}`);
+        if (routePath !== '/') shellExec(`sudo mkdir -p public/${host}`);
+        fs.copySync(`${extractedDir}`, `${publicDestPath}`);
+      };
+
       for (const host of hostsArg) {
-        // Gather all routes for this host; fall back to root '/' when host is not in confServer
-        // (e.g. when hosts were provided explicitly via the path argument).
         const routePaths = confServer[host] ? Object.keys(confServer[host]) : ['/'];
 
         for (const routePath of routePaths) {
           const routeConf = confServer[host] ? confServer[host][routePath] || {} : {};
-          // Skip routes that are not built by buildClient (mirrors buildClient skip conditions)
-          if (routeConf.singleReplica || routeConf.redirect || routeConf.disabledRebuild) continue;
-
-          // buildClient names the zip as "<host>-<path-no-slashes>.zip"
-          // e.g. host="underpost.net", path="/" → buildId="underpost.net-", zip="build/underpost.net-.zip"
-          // e.g. host="app.net", path="/admin" → buildId="app.net-admin", zip="build/app.net-admin.zip"
-          const buildId = `${host}-${routePath.replaceAll('/', '')}`;
-          const zipPath = `build/${buildId}.zip`;
-          const buildDir = './build';
-          const hasZip = fs.existsSync(zipPath);
-          const hasParts =
-            fs.existsSync(buildDir) &&
-            fs
-              .readdirSync(buildDir)
-              .some((name) => name.startsWith(`${buildId}.zip.part`) || name.startsWith(`${buildId}.zip-part`));
-
-          if (!hasZip && !hasParts) {
-            logger.warn(`Bundle not found for '${host}${routePath}'. Skipping.`, { zipPath, deployId });
-            continue;
-          }
-
-          if (hasParts) shellExec(`${baseCommand} client --merge-zip ${zipPath}`);
-          shellExec(`${baseCommand} client --unzip ${zipPath}`);
-          shellExec(`sudo rm -rf ${zipPath}`);
-
-          // Clean up downloaded part wrapper zips left by --omit-unzip pull
-          if (fs.existsSync(buildDir)) {
-            fs.readdirSync(buildDir)
-              .filter((name) => name.startsWith(`${buildId}.zip.part`) || name.startsWith(`${buildId}.zip-part`))
-              .forEach((partFile) => shellExec(`sudo rm -rf ${buildDir}/${partFile}`));
-          }
-
-          // unzipClientBuild extracts to buildId with trailing '-' stripped
-          // e.g. "build/underpost.net-" → "build/underpost.net"
-          // e.g. "build/app.net-admin" → "build/app.net-admin" (no trailing dash, no change)
-          const extractedDir = `build/${buildId.replace(/-$/, '')}`;
-          if (!fs.existsSync(extractedDir)) {
-            logger.warn(`Extracted build dir not found: ${extractedDir}. Skipping move for '${host}${routePath}'.`);
+          if (routeConf.redirect || routeConf.disabledRebuild) continue;
+          if (routeConf.singleReplica) {
+            if (routeConf.replicas) {
+              for (const replica of routeConf.replicas) {
+                pullBundleRoute(host, replica);
+              }
+            }
             continue;
           }
-
-          // Destination mirrors the public directory layout used by the server
-          const publicDestPath = routePath === '/' ? `public/${host}` : `public/${host}${routePath}`;
-          if (fs.existsSync(publicDestPath)) shellExec(`sudo rm -rf ${publicDestPath}`);
-          // Ensure parent directory exists for sub-paths
-          if (routePath !== '/') shellExec(`sudo mkdir -p public/${host}`);
-          shellExec(`sudo mv ${extractedDir} ${publicDestPath}`);
+          pullBundleRoute(host, routePath);
         }
       }
     },
 
+    /**
+     * @method build-cluster-deployment-manifests
+     * @description Builds deployment manifests for both production and development environments using `node bin deploy --build-manifest`, syncing them, and setting replicas to 1 for the `dd` deployment.
+     * @param {string} path - Unused.
+     * @param {Object} options - The default underpost runner options for customizing workflow.
+     * @memberof UnderpostRun
+     */
+    'build-cluster-deployment-manifests': (path = '', options = DEFAULT_OPTION) => {
+      shellExec(`node bin deploy --build-manifest --sync --info-router --replicas 1 dd development`);
+      shellExec(`node bin deploy --build-manifest --sync --info-router --replicas 1 dd production --cert`);
+    },
+
     /**
      * @method monitor-ui
      * @description Installs and enables the Cockpit KVM Dashboard (cockpit, cockpit-machines, libvirt)

package/src/client/components/core/PanelForm.js

@@ -73,7 +73,7 @@ class PanelForm {
       parentIdModal: undefined,
       route: 'home',
       htmlFormHeader: async () => '',
-      firsUpdateEvent: async () => { },
+      firsUpdateEvent: async () => {},
       share: {
         copyLink: false,
         copySourceMd: false,
@@ -196,12 +196,12 @@ class PanelForm {
               <img
                 class="abs center"
                 style="${renderCssAttr({
-              style: {
-                width: '100px',
-                height: '100px',
-                opacity: 0.2,
-              },
-            })}"
+                  style: {
+                    width: '100px',
+                    height: '100px',
+                    opacity: 0.2,
+                  },
+                })}"
                 src="${defaultUrlImage}"
               />
             `,
@@ -382,15 +382,15 @@ class PanelForm {
             // It will be filtered from the tags array to keep visibility control separate from content tags
             const tags = data.tags
               ? uniqueArray(
-                data.tags
-                  .replaceAll('/', ',')
-                  .replaceAll('-', ',')
-                  .replaceAll(' ', ',')
-                  .split(',')
-                  .map((t) => t.trim())
-                  .filter((t) => t)
-                  .concat(prefixTags),
-              )
+                  data.tags
+                    .replaceAll('/', ',')
+                    .replaceAll('-', ',')
+                    .replaceAll(' ', ',')
+                    .split(',')
+                    .map((t) => t.trim())
+                    .filter((t) => t)
+                    .concat(prefixTags),
+                )
               : prefixTags;
             let originObj, originFileObj, indexOriginObj;
             if (editId) {
@@ -432,8 +432,8 @@ class PanelForm {
               // In edit mode, null means user cleared the file - we need to tell server to remove it
               const isFileCleared = data.fileId === null && editId;
               await (async () => {
-                // When file is null and not the first iteration or not in edit mode, skip upload
-                if (!file && !isFileCleared) return;
+                // When file is null, no markdown content, and not clearing a file, skip upload
+                if (!file && !isFileCleared && !hasMdContent) return;
                 // When user cleared file in edit mode, set fileId=null so server removes the reference
                 if (isFileCleared) {
                   fileId = null;
@@ -489,8 +489,8 @@ class PanelForm {
                 message: documentMessage,
                 data: documentData,
               } = originObj && indexFormDoc === 0
-                  ? await DocumentService.put({ id: originObj._id, body })
-                  : await DocumentService.post({
+                ? await DocumentService.put({ id: originObj._id, body })
+                : await DocumentService.post({
                     body,
                   });
               const newDoc = {
@@ -518,12 +518,12 @@ class PanelForm {
                 fileId: {
                   fileBlob: file
                     ? {
-                      data: {
-                        data: await getDataFromInputFile(file),
-                      },
-                      mimetype: file.type,
-                      name: file.name,
-                    }
+                        data: {
+                          data: await getDataFromInputFile(file),
+                        },
+                        mimetype: file.type,
+                        name: file.name,
+                      }
                     : undefined,
                   filePlain: undefined,
                 },
@@ -742,36 +742,36 @@ class PanelForm {
             <div
               class="in fll ssr-shimmer-search-box"
               style="${renderCssAttr({
-            style: {
-              width: '80%',
-              height: '30px',
-              top: '-13px',
-              left: '10px',
-            },
-          })}"
+                style: {
+                  width: '80%',
+                  height: '30px',
+                  top: '-13px',
+                  left: '10px',
+                },
+              })}"
             ></div>
           </div>`,
           createdAt: html`<div class="fl">
             <div
               class="in fll ssr-shimmer-search-box"
               style="${renderCssAttr({
-            style: {
-              width: '50%',
-              height: '30px',
-              left: '-5px',
-            },
-          })}"
+                style: {
+                  width: '50%',
+                  height: '30px',
+                  left: '-5px',
+                },
+              })}"
             ></div>
           </div>`,
           mdFileId: html`<div class="fl section-mp">
             <div
               class="in fll ssr-shimmer-search-box"
               style="${renderCssAttr({
-            style: {
-              width: '80%',
-              height: '30px',
-            },
-          })}"
+                style: {
+                  width: '80%',
+                  height: '30px',
+                },
+              })}"
             ></div>
           </div>`.repeat(random(2, 4)),
           ssr: true,

package/src/client/components/cyberia/SharedDefaultsCyberia.js

@@ -109,7 +109,7 @@ export const ENTITY_TYPE_TO_ITEM_TYPES = Object.freeze({
 export const QUEST_STEPS_TYPES = Object.freeze(['collect', 'talk', 'kill']);
 
 /** Action categories accepted by the cyberia-action engine. */
-export const CYBERIA_ACTION_TYPES = Object.freeze(['craft', 'shop', 'storage', 'quest-talk']);
+export const CYBERIA_ACTION_TYPES = Object.freeze(['craft', 'shop', 'storage', 'talk', 'quest-talk']);
 
 /**
  * Canonical (itemId → itemType) registry shipped with the engine. Used

package/src/client/public/cyberia-docs/ACTION-SYSTEM.md

@@ -8,7 +8,7 @@
 
 The Action System defines how NPC entities interact with players. An **Action** is a spatial, typed payload attached to a map entity that the player activates by tapping the NPC. Actions drive dialogue, shops, crafting, storage, and quest grant events.
 
-> **Implementation status — Pre-alpha:** The CyberiaAction and CyberiaDialogue MongoDB schemas and Engine REST API (`src/api/cyberia-action`, `src/api/cyberia-dialogue`) are defined. Go server integration (NPC tap routing to action handlers, shop/craft transaction processing, quest grant on dialogue completion) is planned for the **Alpha milestone**. The `freeze_start`/`freeze_end` WS messages for modal protection are implemented in the Go server today.
+> **Implementation status — Alpha (talk / quest-talk):** The CyberiaAction and CyberiaDialogue MongoDB schemas and Engine REST API (`src/api/cyberia-action`, `src/api/cyberia-dialogue`) are defined. The `talk` and `quest-talk` paths are wired end-to-end: the Go server binds actions to entities at instance init, validates dialogue completion, grants quests, and advances `talk` objectives (see **Dialogue Interaction Protocol** below). Shop / craft / storage transaction processing remains planned for a later Alpha increment. The `freeze_start`/`freeze_end` WS messages for modal protection are implemented; dialogue freeze now rides on the `dlg_*` frames.
 
 ---
 
@@ -154,6 +154,60 @@ sequenceDiagram
 
 ---
 
+## Dialogue Interaction Protocol (talk / quest-talk)
+
+Tapping an interaction bubble opens the Raylib-native **`modal_interact`** modal
+first — the general-purpose entry point. Its `[Talk]` tab (shown only when the
+entity has dialogue) opens `modal_dialogue`; its `[Chat / Profile]` tab opens the
+JS overlay with no freeze.
+
+The client is identical for `talk` and `quest-talk`; the **server** branches after
+`dlg_complete`. The client never declares the action type, quest code, or quest
+dialogue codes — the server resolves the bound action from its own
+`entityId → CyberiaAction` cache (bound at instance init).
+
+### Wire messages
+
+| Direction | Message        | When                                  | Payload                              |
+| --------- | -------------- | ------------------------------------- | ------------------------------------ |
+| C → S     | `dlg_start`    | `modal_dialogue` opens                | `{ entityId, itemId }`               |
+| C → S     | `dlg_complete` | player reads all lines, closes        | `{ entityId, itemId, dialogCode }`   |
+| C → S     | `dlg_cancel`   | player dismisses early (✕ / outside)  | `{ entityId, itemId }`               |
+| S → C     | `dlg_ack`      | after `dlg_complete` is processed     | `{ questGranted, objectivesDone, quests[] }` |
+
+Binary uplink opcodes: `dlg_start` `0x17`, `dlg_complete` `0x18`, `dlg_cancel`
+`0x19` (JSON aliases of the same names are also accepted).
+
+`dlg_ack` is notify-only — it carries the affected quest snapshot entries the
+client upserts into its local `quest_store` (Quest Journal); it never gates
+simulation state.
+
+### Server `dlg_complete` handling
+
+1. Validate `player.activeDialogueEntityID == msg.entityId`; drop otherwise.
+2. Clear the dialogue context and thaw the player (modal protection off).
+3. Resolve the action from `actionCache[entityId]`. `talk` → ack only.
+4. `quest-talk`: on first contact grant `grantQuestCode`; then for every active
+   quest whose **current step** has a `{ type: 'talk', itemId == provideItemId }`
+   objective, increment it — **only** when `msg.dialogCode` is in the action's
+   `questDialogueCodes`. On quest completion, deliver rewards (FCT) and unlock
+   successors.
+
+> **Dialogue-code contract.** The C client fetches dialogue groups at
+> `/api/cyberia-dialogue/code/default-<itemId>`, so the code it reports on
+> `dlg_complete` is `default-<provideItemId>`. For a `quest-talk` objective to
+> advance, the action's `questDialogueCodes` must contain that code.
+
+### Freeze semantics
+
+| Event                              | Player state              |
+| ---------------------------------- | ------------------------- |
+| `modal_interact` open              | Active (no freeze)        |
+| `dlg_start` sent                   | Frozen — immune to damage |
+| `dlg_complete` / `dlg_cancel` sent | Unfrozen                  |
+
+---
+
 ## Spatial Binding and Instance Init
 
 `sourceMapCode + sourceCellX + sourceCellY` links an Action to a specific entity cell in a specific map. During instance initialization: