@dboio/cli 0.6.8 → 0.6.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dboio/cli",
-  "version": "0.6.8",
+  "version": "0.6.9",
   "description": "CLI for the DBO.io framework",
   "type": "module",
   "bin": {

package/src/commands/add.js

@@ -8,6 +8,7 @@ import { log } from '../lib/logger.js';
 import { shouldSkipColumn } from '../lib/columns.js';
 import { loadAppConfig } from '../lib/config.js';
 import { checkStoredTicket, clearGlobalTicket } from '../lib/ticketing.js';
+import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
 
 // Directories and patterns to skip when scanning with `dbo add .`
 const IGNORE_DIRS = new Set(['.dbo', '.git', 'node_modules', '.svn', '.hg']);
@@ -17,6 +18,7 @@ export const addCommand = new Command('add')
   .argument('<path>', 'File or "." to scan current directory')
   .option('-C, --confirm <value>', 'Commit: true (default) or false', 'true')
   .option('--ticket <id>', 'Override ticket ID')
+  .option('--modifyKey <key>', 'Provide ModifyKey directly (skips interactive prompt)')
   .option('-y, --yes', 'Auto-accept all prompts')
   .option('--json', 'Output raw JSON')
   .option('--jq <expr>', 'Filter JSON response')
@@ -26,6 +28,14 @@ export const addCommand = new Command('add')
     try {
       const client = new DboClient({ domain: options.domain, verbose: options.verbose });
 
+      // ModifyKey guard
+      const modifyKeyResult = await checkModifyKey(options);
+      if (modifyKeyResult.cancel) {
+        log.info('Submission cancelled');
+        return;
+      }
+      if (modifyKeyResult.modifyKey) options._resolvedModifyKey = modifyKeyResult.modifyKey;
+
       if (targetPath === '.') {
         await addDirectory(process.cwd(), client, options);
       } else {
@@ -242,10 +252,21 @@ async function submitAdd(meta, metaPath, filePath, client, options) {
 
   const extraParams = { '_confirm': options.confirm };
   if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
+  if (options._resolvedModifyKey) extraParams['_modify_key'] = options._resolvedModifyKey;
 
   let body = await buildInputBody(dataExprs, extraParams);
   let result = await client.postUrlEncoded('/api/input/submit', body);
 
+  // Reactive ModifyKey retry
+  if (!result.successful && result.messages?.some(m => isModifyKeyError(m))) {
+    const retryMK = await handleModifyKeyError();
+    if (retryMK.cancel) { log.info('Submission cancelled'); return null; }
+    extraParams['_modify_key'] = retryMK.modifyKey;
+    options._resolvedModifyKey = retryMK.modifyKey;
+    body = await buildInputBody(dataExprs, extraParams);
+    result = await client.postUrlEncoded('/api/input/submit', body);
+  }
+
   // Retry with prompted params if needed (ticket, user, repo mismatch)
   const retryResult = await checkSubmitErrors(result);
   if (retryResult) {

package/src/commands/clone.js

@@ -2,7 +2,7 @@ import { Command } from 'commander';
 import { readFile, writeFile, mkdir, access } from 'fs/promises';
 import { join, basename, extname } from 'path';
 import { DboClient } from '../lib/client.js';
-import { loadConfig, updateConfigWithApp, loadClonePlacement, saveClonePlacement, ensureGitignore, saveEntityDirPreference, loadEntityDirPreference, saveEntityContentExtractions, loadEntityContentExtractions, saveAppJsonBaseline, addDeleteEntry, loadCollisionResolutions, saveCollisionResolutions, loadSynchronize } from '../lib/config.js';
+import { loadConfig, updateConfigWithApp, loadClonePlacement, saveClonePlacement, ensureGitignore, saveEntityDirPreference, loadEntityDirPreference, saveEntityContentExtractions, loadEntityContentExtractions, saveAppJsonBaseline, addDeleteEntry, loadCollisionResolutions, saveCollisionResolutions, loadSynchronize, saveAppModifyKey } from '../lib/config.js';
 import { buildBinHierarchy, resolveBinPath, createDirectories, saveStructureFile, getBinName, findBinByPath, BINS_DIR, DEFAULT_PROJECT_DIRS, ENTITY_DIR_MAP } from '../lib/structure.js';
 import { log } from '../lib/logger.js';
 import { setFileTimestamps } from '../lib/timestamps.js';
@@ -501,6 +501,16 @@ export async function performClone(source, options = {}) {
   });
   log.dim('  Updated .dbo/config.json with app metadata');
 
+  // Detect and store ModifyKey for locked/production apps
+  const modifyKey = appJson.ModifyKey || null;
+  await saveAppModifyKey(modifyKey);
+  if (modifyKey) {
+    log.warn('');
+    log.warn('  ⚠  This app has a ModifyKey set (production/locked mode).');
+    log.warn('     You will be prompted to enter the ModifyKey before any push, input, add, content deploy, or deploy command.');
+    log.warn('');
+  }
+
   // Step 3: Update package.json
   await updatePackageJson(appJson, config);
 

package/src/commands/content.js

@@ -5,6 +5,7 @@ import { DboClient } from '../lib/client.js';
 import { buildInputBody } from '../lib/input-parser.js';
 import { formatResponse, formatError } from '../lib/formatter.js';
 import { saveToDisk } from '../lib/save-to-disk.js';
+import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
 import { log } from '../lib/logger.js';
 
 function collect(value, previous) {
@@ -28,16 +29,38 @@ const deployCmd = new Command('deploy')
   .argument('<filepath>', 'Local file path')
   .option('-C, --confirm <value>', 'Commit: true (default) or false', 'true')
   .option('--ticket <id>', 'Override ticket ID')
+  .option('--modifyKey <key>', 'Provide ModifyKey directly (skips interactive prompt)')
   .option('--json', 'Output raw JSON')
   .option('-v, --verbose', 'Show HTTP request details')
   .option('--domain <host>', 'Override domain')
   .action(async (uid, filepath, options) => {
     try {
       const client = new DboClient({ domain: options.domain, verbose: options.verbose });
+
+      // ModifyKey guard
+      const modifyKeyResult = await checkModifyKey(options);
+      if (modifyKeyResult.cancel) {
+        log.info('Submission cancelled');
+        return;
+      }
+
       const extraParams = { '_confirm': options.confirm };
       if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
-      const body = await buildInputBody([`RowUID:${uid};column:content.Content@${filepath}`], extraParams);
-      const result = await client.postUrlEncoded('/api/input/submit', body);
+      if (modifyKeyResult.modifyKey) extraParams['_modify_key'] = modifyKeyResult.modifyKey;
+
+      const dataExprs = [`RowUID:${uid};column:content.Content@${filepath}`];
+      let body = await buildInputBody(dataExprs, extraParams);
+      let result = await client.postUrlEncoded('/api/input/submit', body);
+
+      // Reactive ModifyKey retry
+      if (!result.successful && result.messages?.some(m => isModifyKeyError(m))) {
+        const retryMK = await handleModifyKeyError();
+        if (retryMK.cancel) { log.info('Submission cancelled'); return; }
+        extraParams['_modify_key'] = retryMK.modifyKey;
+        body = await buildInputBody(dataExprs, extraParams);
+        result = await client.postUrlEncoded('/api/input/submit', body);
+      }
+
       formatResponse(result, { json: options.json });
       if (!result.successful) process.exit(1);
     } catch (err) {

package/src/commands/deploy.js

@@ -3,6 +3,7 @@ import { readFile } from 'fs/promises';
 import { DboClient } from '../lib/client.js';
 import { buildInputBody } from '../lib/input-parser.js';
 import { formatResponse, formatError } from '../lib/formatter.js';
+import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
 import { log } from '../lib/logger.js';
 
 const MANIFEST_FILE = 'dbo.deploy.json';
@@ -13,6 +14,7 @@ export const deployCommand = new Command('deploy')
   .option('--all', 'Deploy all entries in the manifest')
   .option('-C, --confirm <value>', 'Commit: true (default) or false', 'true')
   .option('--ticket <id>', 'Override ticket ID')
+  .option('--modifyKey <key>', 'Provide ModifyKey directly (skips interactive prompt)')
   .option('--json', 'Output raw JSON')
   .option('-v, --verbose', 'Show HTTP request details')
   .option('--domain <host>', 'Override domain')
@@ -51,6 +53,14 @@ export const deployCommand = new Command('deploy')
         process.exit(1);
       }
 
+      // ModifyKey guard — check once before any submissions
+      const modifyKeyResult = await checkModifyKey(options);
+      if (modifyKeyResult.cancel) {
+        log.info('Submission cancelled');
+        return;
+      }
+      let activeModifyKey = modifyKeyResult.modifyKey;
+
       for (const [entryName, entry] of entries) {
         if (!entry) {
           log.warn(`Skipping unknown deployment: ${entryName}`);
@@ -71,8 +81,21 @@ export const deployCommand = new Command('deploy')
 
         const extraParams = { '_confirm': options.confirm };
         if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
-        const body = await buildInputBody([`RowUID:${uid};column:${entity}.${column}@${file}`], extraParams);
-        const result = await client.postUrlEncoded('/api/input/submit', body);
+        if (activeModifyKey) extraParams['_modify_key'] = activeModifyKey;
+
+        const dataExprs = [`RowUID:${uid};column:${entity}.${column}@${file}`];
+        let body = await buildInputBody(dataExprs, extraParams);
+        let result = await client.postUrlEncoded('/api/input/submit', body);
+
+        // Reactive ModifyKey retry
+        if (!result.successful && result.messages?.some(m => isModifyKeyError(m))) {
+          const retryMK = await handleModifyKeyError();
+          if (retryMK.cancel) { log.info('Submission cancelled'); break; }
+          activeModifyKey = retryMK.modifyKey;
+          extraParams['_modify_key'] = activeModifyKey;
+          body = await buildInputBody(dataExprs, extraParams);
+          result = await client.postUrlEncoded('/api/input/submit', body);
+        }
 
         if (result.successful) {
           log.success(`${entryName} deployed`);

package/src/commands/input.js

@@ -4,6 +4,7 @@ import { buildInputBody, parseFileArg, checkSubmitErrors } from '../lib/input-pa
 import { formatResponse, formatError } from '../lib/formatter.js';
 import { loadAppConfig } from '../lib/config.js';
 import { checkStoredTicket, clearGlobalTicket } from '../lib/ticketing.js';
+import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
 import { log } from '../lib/logger.js';
 
 function collect(value, previous) {
@@ -16,6 +17,7 @@ export const inputCommand = new Command('input')
   .option('-f, --file <field=@path>', 'File attachment for multipart upload (repeatable)', collect, [])
   .option('-C, --confirm <value>', 'Commit changes: true (default) or false for validation only', 'true')
   .option('--ticket <id>', 'Override ticket ID (_OverrideTicketID)')
+  .option('--modifyKey <key>', 'Provide ModifyKey directly (skips interactive prompt)')
   .option('--login', 'Auto-login user created by this submission')
   .option('--transactional', 'Use transactional processing')
   .option('--json', 'Output raw JSON response')
@@ -45,6 +47,14 @@ export const inputCommand = new Command('input')
         }
       }
 
+      // ModifyKey guard
+      const modifyKeyResult = await checkModifyKey(options);
+      if (modifyKeyResult.cancel) {
+        log.info('Submission cancelled');
+        return;
+      }
+      if (modifyKeyResult.modifyKey) extraParams['_modify_key'] = modifyKeyResult.modifyKey;
+
       // Check if data expressions include AppID; if not and config has one, prompt
       const allDataText = options.data.join(' ');
       const hasAppId = /\.AppID[=@]/.test(allDataText) || /AppID=/.test(allDataText);
@@ -93,6 +103,14 @@ export const inputCommand = new Command('input')
         const files = options.file.map(parseFileArg);
         let result = await client.postMultipart('/api/input/submit', fields, files);
 
+        // Reactive ModifyKey retry
+        if (!result.successful && result.messages?.some(m => isModifyKeyError(m))) {
+          const retryMK = await handleModifyKeyError();
+          if (retryMK.cancel) { log.info('Submission cancelled'); return; }
+          fields['_modify_key'] = retryMK.modifyKey;
+          result = await client.postMultipart('/api/input/submit', fields, files);
+        }
+
         // Retry with prompted params if needed (ticket, user, repo mismatch)
         const retryResult = await checkSubmitErrors(result);
         if (retryResult) {
@@ -112,6 +130,15 @@ export const inputCommand = new Command('input')
         let body = await buildInputBody(options.data, extraParams);
         let result = await client.postUrlEncoded('/api/input/submit', body);
 
+        // Reactive ModifyKey retry
+        if (!result.successful && result.messages?.some(m => isModifyKeyError(m))) {
+          const retryMK = await handleModifyKeyError();
+          if (retryMK.cancel) { log.info('Submission cancelled'); return; }
+          extraParams['_modify_key'] = retryMK.modifyKey;
+          body = await buildInputBody(options.data, extraParams);
+          result = await client.postUrlEncoded('/api/input/submit', body);
+        }
+
         // Retry with prompted params if needed (ticket, user, repo mismatch)
         const retryResult = await checkSubmitErrors(result);
         if (retryResult) {

package/src/commands/push.js

@@ -8,6 +8,7 @@ import { log } from '../lib/logger.js';
 import { shouldSkipColumn } from '../lib/columns.js';
 import { loadConfig, loadSynchronize, saveSynchronize, loadAppJsonBaseline, saveAppJsonBaseline, hasBaseline } from '../lib/config.js';
 import { checkStoredTicket, applyStoredTicketToSubmission, clearRecordTicket, clearGlobalTicket } from '../lib/ticketing.js';
+import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
 import { setFileTimestamps } from '../lib/timestamps.js';
 import { findMetadataFiles } from '../lib/diff.js';
 import { detectChangedColumns, findBaselineEntry } from '../lib/delta.js';
@@ -18,6 +19,7 @@ export const pushCommand = new Command('push')
   .argument('<path>', 'File or directory to push')
   .option('-C, --confirm <value>', 'Commit: true (default) or false', 'true')
   .option('--ticket <id>', 'Override ticket ID')
+  .option('--modifyKey <key>', 'Provide ModifyKey directly (skips interactive prompt)')
   .option('--meta-only', 'Only push metadata changes, skip file content')
   .option('--content-only', 'Only push file content, skip metadata columns')
   .option('-y, --yes', 'Auto-accept all prompts (path refactoring, etc.)')
@@ -29,15 +31,23 @@ export const pushCommand = new Command('push')
     try {
       const client = new DboClient({ domain: options.domain, verbose: options.verbose });
 
+      // ModifyKey guard — check once before any submissions
+      const modifyKeyResult = await checkModifyKey(options);
+      if (modifyKeyResult.cancel) {
+        log.info('Submission cancelled');
+        return;
+      }
+      const modifyKey = modifyKeyResult.modifyKey;
+
       // Process pending deletions from synchronize.json
-      await processPendingDeletes(client, options);
+      await processPendingDeletes(client, options, modifyKey);
 
       const pathStat = await stat(targetPath);
 
       if (pathStat.isDirectory()) {
-        await pushDirectory(targetPath, client, options);
+        await pushDirectory(targetPath, client, options, modifyKey);
       } else {
-        await pushSingleFile(targetPath, client, options);
+        await pushSingleFile(targetPath, client, options, modifyKey);
       }
     } catch (err) {
       formatError(err);
@@ -48,7 +58,7 @@ export const pushCommand = new Command('push')
 /**
  * Process pending delete entries from .dbo/synchronize.json
  */
-async function processPendingDeletes(client, options) {
+async function processPendingDeletes(client, options, modifyKey = null) {
   const sync = await loadSynchronize();
   if (!sync.delete || sync.delete.length === 0) return;
 
@@ -62,6 +72,7 @@ async function processPendingDeletes(client, options) {
 
     const extraParams = { '_confirm': options.confirm || 'true' };
     if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
+    if (modifyKey) extraParams['_modify_key'] = modifyKey;
 
     const body = await buildInputBody([entry.expression], extraParams);
 
@@ -69,23 +80,33 @@ async function processPendingDeletes(client, options) {
       const result = await client.postUrlEncoded('/api/input/submit', body);
 
       // Retry with prompted params if needed
-      const retryResult = await checkSubmitErrors(result);
-      if (retryResult) {
-        if (retryResult.skipRecord || retryResult.skipAll) {
+      const errorResult = await checkSubmitErrors(result);
+      if (errorResult) {
+        if (errorResult.skipRecord) {
           log.warn(`  Skipping deletion of "${entry.name}"`);
           remaining.push(entry);
           continue;
         }
-        const params = retryResult.retryParams || retryResult;
+        if (errorResult.skipAll) {
+          log.warn(`  Skipping deletion of "${entry.name}" and all remaining`);
+          remaining.push(entry);
+          // Push all remaining entries too
+          const currentIdx = sync.delete.indexOf(entry);
+          for (let i = currentIdx + 1; i < sync.delete.length; i++) {
+            remaining.push(sync.delete[i]);
+          }
+          break;
+        }
+        const params = errorResult.retryParams || errorResult;
         Object.assign(extraParams, params);
         const retryBody = await buildInputBody([entry.expression], extraParams);
-        const retryResult = await client.postUrlEncoded('/api/input/submit', retryBody);
-        if (retryResult.successful) {
+        const retryResponse = await client.postUrlEncoded('/api/input/submit', retryBody);
+        if (retryResponse.successful) {
           log.success(`  Deleted "${entry.name}" from server`);
           deletedUids.push(entry.UID);
         } else {
           log.error(`  Failed to delete "${entry.name}"`);
-          formatResponse(retryResult, { json: options.json, jq: options.jq });
+          formatResponse(retryResponse, { json: options.json, jq: options.jq });
           remaining.push(entry);
         }
       } else if (result.successful) {
@@ -119,7 +140,7 @@ async function processPendingDeletes(client, options) {
 /**
  * Push a single file using its companion .metadata.json
  */
-async function pushSingleFile(filePath, client, options) {
+async function pushSingleFile(filePath, client, options, modifyKey = null) {
   // Find the metadata file
   const dir = dirname(filePath);
   const base = basename(filePath, extname(filePath));
@@ -133,13 +154,13 @@ async function pushSingleFile(filePath, client, options) {
     process.exit(1);
   }
 
-  await pushFromMetadata(meta, metaPath, client, options);
+  await pushFromMetadata(meta, metaPath, client, options, null, modifyKey);
 }
 
 /**
  * Push all records found in a directory (recursive)
  */
-async function pushDirectory(dirPath, client, options) {
+async function pushDirectory(dirPath, client, options, modifyKey = null) {
   const metaFiles = await findMetadataFiles(dirPath);
 
   if (metaFiles.length === 0) {
@@ -251,7 +272,7 @@ async function pushDirectory(dirPath, client, options) {
 
   for (const item of toPush) {
     try {
-      const success = await pushFromMetadata(item.meta, item.metaPath, client, options, item.changedColumns);
+      const success = await pushFromMetadata(item.meta, item.metaPath, client, options, item.changedColumns, modifyKey);
       if (success) {
         succeeded++;
         successfulPushes.push(item);
@@ -285,7 +306,7 @@ async function pushDirectory(dirPath, client, options) {
  * @param {string[]|null} changedColumns - Optional array of changed column names (for delta sync)
  * @returns {Promise<boolean>} - True if push succeeded
  */
-async function pushFromMetadata(meta, metaPath, client, options, changedColumns = null) {
+async function pushFromMetadata(meta, metaPath, client, options, changedColumns = null, modifyKey = null) {
   const uid = meta.UID || meta._id;
   const entity = meta._entity;
   const contentCols = new Set(meta._contentColumns || []);
@@ -349,10 +370,20 @@ async function pushFromMetadata(meta, metaPath, client, options, changedColumns
 
   const extraParams = { '_confirm': options.confirm };
   if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
+  if (modifyKey) extraParams['_modify_key'] = modifyKey;
 
   let body = await buildInputBody(dataExprs, extraParams);
   let result = await client.postUrlEncoded('/api/input/submit', body);
 
+  // Reactive ModifyKey retry — server rejected because key wasn't set locally
+  if (!result.successful && result.messages?.some(m => isModifyKeyError(m))) {
+    const retryMK = await handleModifyKeyError();
+    if (retryMK.cancel) { log.info('Submission cancelled'); return false; }
+    extraParams['_modify_key'] = retryMK.modifyKey;
+    body = await buildInputBody(dataExprs, extraParams);
+    result = await client.postUrlEncoded('/api/input/submit', body);
+  }
+
   // Retry with prompted params if needed (ticket, user, repo mismatch)
   const retryResult = await checkSubmitErrors(result);
   if (retryResult) {

package/src/lib/config.js

@@ -181,9 +181,10 @@ export async function loadAppConfig() {
       AppUID: config.AppUID || null,
       AppName: config.AppName || null,
       AppShortName: config.AppShortName || null,
+      AppModifyKey: config.AppModifyKey || null,
     };
   } catch {
-    return { AppID: null, AppUID: null, AppName: null, AppShortName: null };
+    return { AppID: null, AppUID: null, AppName: null, AppShortName: null, AppModifyKey: null };
   }
 }
 
@@ -528,6 +529,32 @@ export async function getAllPluginScopes() {
   return result;
 }
 
+// ─── AppModifyKey ─────────────────────────────────────────────────────────
+
+/**
+ * Save AppModifyKey to .dbo/config.json.
+ * Pass null to remove the key (e.g. when server no longer has one).
+ */
+export async function saveAppModifyKey(modifyKey) {
+  await mkdir(dboDir(), { recursive: true });
+  let existing = {};
+  try { existing = JSON.parse(await readFile(configPath(), 'utf8')); } catch {}
+  if (modifyKey != null) existing.AppModifyKey = modifyKey;
+  else delete existing.AppModifyKey;
+  await writeFile(configPath(), JSON.stringify(existing, null, 2) + '\n');
+}
+
+/**
+ * Load AppModifyKey from .dbo/config.json.
+ * Returns the key string or null if not set.
+ */
+export async function loadAppModifyKey() {
+  try {
+    const raw = await readFile(configPath(), 'utf8');
+    return JSON.parse(raw).AppModifyKey || null;
+  } catch { return null; }
+}
+
 // ─── Gitignore ────────────────────────────────────────────────────────────
 
 /**

package/src/lib/input-parser.js

@@ -116,7 +116,8 @@ export async function checkSubmitErrors(result) {
   const allText = messages.filter(m => typeof m === 'string').join(' ');
 
   // --- Ticket error detection (new interactive handling) ---
-  const hasTicketError = allText.includes('ticket_error');
+  // Match ticket_error, ticket_lookup_error, and similar variants
+  const hasTicketError = allText.includes('ticket_error') || allText.includes('ticket_lookup_error');
   const hasRepoMismatch = allText.includes('repo_mismatch');
 
   if (hasTicketError) {

package/src/lib/modify-key.js

@@ -0,0 +1,96 @@
+import { loadAppModifyKey, saveAppModifyKey } from './config.js';
+import { log } from './logger.js';
+
+/**
+ * Pre-submission ModifyKey guard.
+ * - If options.modifyKey flag is set, it takes precedence — no prompt, no config check.
+ * - Returns { modifyKey: null } if no key is set in config (no-op).
+ * - Prompts user to type the key; returns { modifyKey: string } on match.
+ * - Returns { modifyKey: null, cancel: true } on mismatch or cancel.
+ */
+export async function checkModifyKey(options = {}) {
+  // --modifyKey flag takes precedence (mirrors --ticket / --confirm behavior)
+  if (options.modifyKey) return { modifyKey: options.modifyKey, cancel: false };
+
+  const storedKey = await loadAppModifyKey();
+  if (!storedKey) return { modifyKey: null, cancel: false };
+
+  log.warn('');
+  log.warn('  ⚠  This app is locked (production mode). A ModifyKey is required to submit changes.');
+  log.warn('');
+
+  const inquirer = (await import('inquirer')).default;
+  const { action } = await inquirer.prompt([{
+    type: 'list',
+    name: 'action',
+    message: 'This app has a ModifyKey set. How would you like to proceed?',
+    choices: [
+      { name: 'Enter the ModifyKey to proceed', value: 'enter' },
+      { name: 'Cancel submission', value: 'cancel' },
+    ],
+  }]);
+
+  if (action === 'cancel') return { modifyKey: null, cancel: true };
+
+  const { enteredKey } = await inquirer.prompt([{
+    type: 'input',
+    name: 'enteredKey',
+    message: 'ModifyKey:',
+  }]);
+
+  const key = enteredKey.trim();
+  if (!key) {
+    log.error('  No ModifyKey entered. Submission cancelled.');
+    return { modifyKey: null, cancel: true };
+  }
+
+  return { modifyKey: key, cancel: false };
+}
+
+/**
+ * Detects whether a server response error message requires a ModifyKey.
+ * Server error format: "Error:The '<app>' app (UID=...) has a ModifyKey – ..."
+ */
+export function isModifyKeyError(responseMessage) {
+  return typeof responseMessage === 'string' && responseMessage.includes('has a ModifyKey');
+}
+
+/**
+ * Reactive ModifyKey handler — called after a submission fails with a ModifyKey error.
+ * Prompts the user to enter the key, saves it to config, and returns it for retry.
+ * Returns { modifyKey: string } on success or { modifyKey: null, cancel: true } on cancel.
+ */
+export async function handleModifyKeyError() {
+  log.warn('');
+  log.warn('  ⚠  This app requires a ModifyKey. The key has not been set locally (try re-running `dbo clone`).');
+  log.warn('');
+
+  const inquirer = (await import('inquirer')).default;
+  const { action } = await inquirer.prompt([{
+    type: 'list',
+    name: 'action',
+    message: 'A ModifyKey is required. How would you like to proceed?',
+    choices: [
+      { name: 'Enter the ModifyKey to retry', value: 'enter' },
+      { name: 'Cancel submission', value: 'cancel' },
+    ],
+  }]);
+
+  if (action === 'cancel') return { modifyKey: null, cancel: true };
+
+  const { enteredKey } = await inquirer.prompt([{
+    type: 'input',
+    name: 'enteredKey',
+    message: 'ModifyKey:',
+  }]);
+
+  const key = enteredKey.trim();
+  if (!key) {
+    log.error('  No ModifyKey entered. Submission cancelled.');
+    return { modifyKey: null, cancel: true };
+  }
+
+  await saveAppModifyKey(key);
+  log.info('  ModifyKey saved to .dbo/config.json for future use.');
+  return { modifyKey: key, cancel: false };
+}