@dboio/cli 0.19.7 → 0.20.3

package/src/lib/filenames.js

@@ -1,7 +1,7 @@
 /**
- * Filename convention helpers for the metadata~uid convention.
- * Metadata files: name.metadata~uid.json
- * Companion files: natural names, no UID embedded.
+ * Filename convention helpers for the metadata convention.
+ * Metadata files: name.metadata.json  (UID is stored inside the JSON, not in the filename)
+ * Companion files: natural names.
  */
 
 import { rename, unlink, writeFile, readFile, readdir } from 'fs/promises';
@@ -15,6 +15,8 @@ import { join, dirname, basename, extname } from 'path';
  * @param {string} uid   - Server-assigned UID
  * @param {string} [ext] - File extension WITHOUT leading dot (e.g. 'css', 'png', '')
  * @returns {string}     - e.g. "colors~abc123.css" or "abc123.css" or "colors~abc123"
+ * @deprecated Use buildMetaFilename() for metadata files. This function is retained
+ *             only for legacy detection/migration code.
  */
 export function buildUidFilename(name, uid, ext = '') {
   const base = (name === uid) ? uid : `${name}~${uid}`;
@@ -100,6 +102,7 @@ export function stripUidFromFilename(localName, uid) {
 
 /**
  * Check whether a filename already contains ~<uid>.
+ * @deprecated Only used by legacy migration code.
  */
 export function hasUidInFilename(filename, uid) {
   return typeof filename === 'string' && typeof uid === 'string'
@@ -114,25 +117,28 @@ export function hasUidInFilename(filename, uid) {
  * Returns { name, uid } or null.
  */
 export function detectLegacyDotUid(filename) {
-  const match = filename.match(/^(.+)\.([a-z0-9]{10,})\.metadata\.json$/);
+  const match = filename.match(/^(.+)\.([a-z0-9_]{10,})\.metadata\.json$/);
   return match ? { name: match[1], uid: match[2] } : null;
 }
 
 /**
- * Build the new-convention metadata filename.
- * Format: <naturalBase>.metadata~<uid>.json
+ * Build a metadata filename for a record.
+ * Format: <naturalBase>.metadata.json
+ * The UID is stored inside the JSON, not in the filename.
  *
- * For content records: naturalBase = "colors" → "colors.metadata~abc123.json"
- * For media records:   naturalBase = "logo.png" → "logo.png.metadata~abc123.json"
- * For output records:  naturalBase = "Sales" → "Sales.metadata~abc123.json"
+ * For content records:  naturalBase = "colors"    → "colors.metadata.json"
+ * For media records:    naturalBase = "logo.png"  → "logo.png.metadata.json"
+ * For output records:   naturalBase = "Sales"     → "Sales.metadata.json"
+ *
+ * Collision avoidance (when two records share a name) is handled by the caller
+ * via numbered suffixes: "colors-1.metadata.json", "colors-2.metadata.json", etc.
  *
  * @param {string} naturalBase - Name without any ~uid (may include media extension)
- * @param {string} uid         - Server-assigned UID
  * @returns {string}
  */
-export function buildMetaFilename(naturalBase, uid) {
+export function buildMetaFilename(naturalBase) {
   // Guard: strip any trailing .metadata suffix(es) and ~uid fragments from naturalBase
-  // to prevent double-metadata filenames (e.g., "app.metadata.metadata~app.json")
+  // to prevent double-metadata filenames (e.g., "app.metadata.metadata.json")
   let base = naturalBase;
   const metaParsed = parseMetaFilename(base + '.json');
   if (metaParsed) {
@@ -142,34 +148,43 @@ export function buildMetaFilename(naturalBase, uid) {
   while (base.endsWith('.metadata')) {
     base = base.substring(0, base.length - 9);
   }
-  return `${base}.metadata~${uid}.json`;
+  return `${base}.metadata.json`;
 }
 
 /**
  * Test whether a filename is a metadata file (new or legacy format).
  *
- * New format:    name.metadata~uid.json
- * Legacy format: name~uid.metadata.json  (also accepted during migration)
+ * New format:    name.metadata.json  (UID in JSON content, not filename)
+ * Legacy format: name.metadata~uid.json  (also accepted during migration)
  *
  * @param {string} filename
  * @returns {boolean}
  */
 export function isMetadataFile(filename) {
-  return /\.metadata~[a-z0-9]+\.json$/i.test(filename)   // new: name.metadata~uid.json
-    || filename.endsWith('.metadata.json')                 // legacy + pre-UID temp files
-    || /\.[a-z0-9]{10,}\.metadata\.json$/i.test(filename); // legacy dot-separated: name.uid.metadata.json
+  return filename.endsWith('.metadata.json')                 // new format + legacy pre-UID temp files
+    || /\.metadata~[a-z0-9_]+\.json$/i.test(filename)       // legacy tilde-uid suffix format
+    || /\.[a-z0-9]{10,}\.metadata\.json$/i.test(filename);  // legacy dot-separated: name.uid.metadata.json
 }
 
 /**
- * Parse a new-format metadata filename into its components.
- * Returns null for legacy-format filenames (use detectLegacyTildeMetadata for those).
+ * Parse a metadata filename into its components.
+ *
+ * New format:    name.metadata.json      → { naturalBase: "name" }
+ * Legacy format: name.metadata~uid.json  → { naturalBase: "name", uid: "uid" }
  *
- * @param {string} filename - e.g. "colors.metadata~abc123.json"
- * @returns {{ naturalBase: string, uid: string } | null}
+ * Returns null for non-metadata filenames.
+ *
+ * @param {string} filename
+ * @returns {{ naturalBase: string, uid?: string } | null}
  */
 export function parseMetaFilename(filename) {
-  const m = filename.match(/^(.+)\.metadata~([a-z0-9]+)\.json$/i);
-  return m ? { naturalBase: m[1], uid: m[2] } : null;
+  // Legacy format with uid in suffix (migration target for 008, source for 013)
+  const legacy = filename.match(/^(.+)\.metadata~([a-z0-9_]+)\.json$/i);
+  if (legacy) return { naturalBase: legacy[1], uid: legacy[2] };
+
+  // New format: name.metadata.json
+  const m = filename.match(/^(.+)\.metadata\.json$/i);
+  return m ? { naturalBase: m[1] } : null;
 }
 
 /**
@@ -181,11 +196,11 @@ export function parseMetaFilename(filename) {
  */
 export function detectLegacyTildeMetadata(filename) {
   // Case 1: name~uid.metadata.json (content/entity metadata)
-  const m1 = filename.match(/^(.+)~([a-z0-9]{10,})\.metadata\.json$/);
+  const m1 = filename.match(/^(.+)~([a-z0-9_]{10,})\.metadata\.json$/);
   if (m1) return { naturalBase: m1[1], uid: m1[2] };
 
   // Case 2: name~uid.ext.metadata.json (media metadata)
-  const m2 = filename.match(/^(.+)~([a-z0-9]{10,})\.([a-z0-9]+)\.metadata\.json$/);
+  const m2 = filename.match(/^(.+)~([a-z0-9_]{10,})\.([a-z0-9]+)\.metadata\.json$/);
   if (m2) return { naturalBase: `${m2[1]}.${m2[3]}`, uid: m2[2] };
 
   return null;
@@ -210,7 +225,7 @@ export async function findMetadataForCompanion(companionPath) {
   let entries;
   try { entries = await readdir(dir); } catch { return null; }
 
-  // 1. Fast path: match naturalBase of new-format metadata files
+  // 1. Fast path: match naturalBase of metadata files
   for (const entry of entries) {
     const parsed = parseMetaFilename(entry);
     if (parsed && (parsed.naturalBase === base || parsed.naturalBase === companionName)) {
@@ -218,7 +233,7 @@ export async function findMetadataForCompanion(companionPath) {
     }
   }
 
-  // 2. Scan all metadata files (new + legacy) for @reference match
+  // 2. Scan all metadata files for @reference match
   for (const entry of entries) {
     if (!isMetadataFile(entry)) continue;
     const metaPath = join(dir, entry);
@@ -241,8 +256,10 @@ export async function findMetadataForCompanion(companionPath) {
 }
 
 /**
- * Rename a file pair (content + metadata) to the ~uid convention after server assigns a UID.
- * Updates @reference values inside the metadata file.
+ * Update the UID field in a metadata file in-place.
+ * Previously renamed the file to include ~uid in the name; now the UID lives
+ * only inside the JSON content, so no rename is needed.
+ *
  * Restores file timestamps from _LastUpdated.
  *
  * @param {Object} meta        - Current metadata object
@@ -250,57 +267,28 @@ export async function findMetadataForCompanion(companionPath) {
  * @param {string} uid         - Newly assigned UID from server
  * @param {string} lastUpdated - Server _LastUpdated value
  * @param {string} serverTz    - Timezone for timestamp conversion
- * @returns {Promise<{ newMetaPath: string, newFilePath: string|null }>}
+ * @returns {Promise<{ newMetaPath: string, newFilePath: null, updatedMeta: Object }>}
  */
 export async function renameToUidConvention(meta, metaPath, uid, lastUpdated, serverTz) {
-  const metaDir = dirname(metaPath);
-  const metaFilename = basename(metaPath);
-
-  // Already in new format — nothing to do
-  if (parseMetaFilename(metaFilename)?.uid === uid) {
-    return { newMetaPath: metaPath, newFilePath: null, updatedMeta: meta };
-  }
-
-  // Determine naturalBase from the temp/old metadata filename
-  // Temp format from adopt.js: "colors.metadata.json" → naturalBase = "colors"
-  // Old tilde format: "colors~uid.metadata.json" → naturalBase = "colors"
-  let naturalBase;
-  const legacyParsed = detectLegacyTildeMetadata(metaFilename);
-  if (legacyParsed) {
-    naturalBase = legacyParsed.naturalBase;
-  } else if (metaFilename.endsWith('.metadata.json')) {
-    naturalBase = metaFilename.slice(0, -'.metadata.json'.length);
-  } else {
-    naturalBase = basename(metaFilename, '.json');
-  }
-
-  const newMetaPath = join(metaDir, buildMetaFilename(naturalBase, uid));
-
-  // Update only the UID field; @reference values are UNCHANGED (companions keep natural names)
   const updatedMeta = { ...meta, UID: uid };
 
-  // Write updated metadata to new path
-  await writeFile(newMetaPath, JSON.stringify(updatedMeta, null, 2) + '\n');
-
-  // Remove old metadata file (new content already written to newMetaPath above)
-  if (metaPath !== newMetaPath) {
-    try { await unlink(metaPath); } catch { /* old file already gone */ }
-  }
+  // Write updated metadata to same path (no rename — UID is in the JSON, not the filename)
+  await writeFile(metaPath, JSON.stringify(updatedMeta, null, 2) + '\n');
 
-  // Restore timestamps for metadata file and companions (companions are not renamed)
+  // Restore timestamps for metadata file and companions
   if (serverTz && lastUpdated) {
     const { setFileTimestamps } = await import('./timestamps.js');
-    try { await setFileTimestamps(newMetaPath, lastUpdated, lastUpdated, serverTz); } catch {}
+    try { await setFileTimestamps(metaPath, lastUpdated, lastUpdated, serverTz); } catch {}
     const contentCols = [...(meta._companionReferenceColumns || meta._contentColumns || [])];
     if (meta._mediaFile) contentCols.push('_mediaFile');
     for (const col of contentCols) {
       const ref = updatedMeta[col];
       if (ref && String(ref).startsWith('@')) {
-        const fp = join(metaDir, String(ref).substring(1));
+        const fp = join(dirname(metaPath), String(ref).substring(1));
         try { await setFileTimestamps(fp, lastUpdated, lastUpdated, serverTz); } catch {}
       }
     }
   }
 
-  return { newMetaPath, newFilePath: null, updatedMeta };
+  return { newMetaPath: metaPath, newFilePath: null, updatedMeta };
 }

package/src/lib/ignore.js

@@ -11,6 +11,9 @@ const DBOIGNORE_FILE = '.dboignore';
 const DEFAULT_FILE_CONTENT = `# DBO CLI ignore patterns
 # (gitignore-style syntax — works like .gitignore)
 
+# Build artifacts
+*.map
+
 # DBO internal
 .app/
 .dboignore

package/src/lib/input-parser.js

@@ -37,12 +37,8 @@ export async function buildInputBody(dataExpressions, extraParams = {}) {
   }
 
   for (const expr of dataExpressions) {
-    // Split by & to handle multiple ops in one -d string
-    const ops = expr.split('&');
-    for (const op of ops) {
-      const encoded = await encodeInputExpression(op.trim());
-      parts.push(encoded);
-    }
+    const encoded = await encodeInputExpression(expr.trim());
+    parts.push(encoded);
   }
 
   return parts.join('&');

package/src/lib/insert.js

@@ -1,4 +1,4 @@
-import { readFile, readdir, writeFile, mkdir, unlink } from 'fs/promises';
+import { readFile, readdir, writeFile, mkdir } from 'fs/promises';
 import { join, dirname, basename, extname, relative } from 'path';
 import { DboClient } from './client.js';
 import { buildInputBody, checkSubmitErrors } from './input-parser.js';
@@ -7,7 +7,7 @@ import { log } from './logger.js';
 import { shouldSkipColumn } from './columns.js';
 import { loadAppConfig, loadAppJsonBaseline, saveAppJsonBaseline, loadExtensionDocumentationMDPlacement, loadDescriptorFilenamePreference, loadConfig } from './config.js';
 import { loadMetadataSchema, saveMetadataSchema } from './metadata-schema.js';
-import { hasUidInFilename, buildMetaFilename, isMetadataFile } from './filenames.js';
+import { isMetadataFile } from './filenames.js';
 import { setFileTimestamps } from './timestamps.js';
 import { checkStoredTicket, clearGlobalTicket } from './ticketing.js';
 import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from './modify-key.js';
@@ -283,7 +283,8 @@ export async function submitAdd(meta, metaPath, filePath, client, options) {
 
   for (const [key, value] of Object.entries(meta)) {
     if (shouldSkipColumn(key)) continue;
-    if (key === 'UID') continue; // Never submit UID on add — server assigns it
+    // UID is included only if the developer manually placed it in the metadata file.
+    // The CLI never auto-generates UIDs — the server assigns them on insert.
     if (value === null || value === undefined) continue;
 
     const strValue = String(value);
@@ -366,51 +367,35 @@ export async function submitAdd(meta, metaPath, filePath, client, options) {
     }
 
     if (returnedUID) {
-      // Check if UID is already embedded in the filename (idempotency guard)
-      const currentMetaBase = basename(metaPath);
-      if (hasUidInFilename(currentMetaBase, returnedUID)) {
-        meta.UID = returnedUID;
-        await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
-        log.success(`UID already in filename: ${returnedUID}`);
-      } else {
-        // Companion file NOT renamed — only update UID in metadata and rename metadata file
-        const metaDir = dirname(metaPath);
-        const metaBase = basename(metaPath, '.metadata.json');
-        const newMetaPath = join(metaDir, buildMetaFilename(metaBase, returnedUID));
-
-        meta.UID = returnedUID;
-
-        await writeFile(newMetaPath, JSON.stringify(meta, null, 2) + '\n');
-        if (metaPath !== newMetaPath) {
-          try { await unlink(metaPath); } catch { /* old file already gone */ }
-        }
-        log.dim(`  Renamed metadata: ${basename(metaPath)} → ${basename(newMetaPath)}`);
-        log.success(`UID assigned: ${returnedUID}`);
-
-        // Restore timestamps for metadata and companion files
-        const config = await loadConfig();
-        const serverTz = config.ServerTimezone;
-        if (serverTz && returnedLastUpdated) {
-          try {
-            await setFileTimestamps(newMetaPath, returnedLastUpdated, returnedLastUpdated, serverTz);
-            for (const col of (meta._companionReferenceColumns || meta._contentColumns || [])) {
-              const ref = meta[col];
-              if (ref && String(ref).startsWith('@')) {
-                const fp = join(metaDir, String(ref).substring(1));
-                await upsertDeployEntry(fp, returnedUID, entity, col);
-                try { await setFileTimestamps(fp, returnedLastUpdated, returnedLastUpdated, serverTz); } catch {}
-              }
-            }
-            if (meta._mediaFile && String(meta._mediaFile).startsWith('@')) {
-              const mediaFp = join(metaDir, String(meta._mediaFile).substring(1));
-              await upsertDeployEntry(mediaFp, returnedUID, entity, 'File');
+      // UID lives in the JSON content — write it in-place, no filename rename needed
+      const metaDir = dirname(metaPath);
+      meta.UID = returnedUID;
+      await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
+      log.success(`UID assigned: ${returnedUID}`);
+
+      // Restore timestamps for metadata and companion files
+      const config = await loadConfig();
+      const serverTz = config.ServerTimezone;
+      if (serverTz && returnedLastUpdated) {
+        try {
+          await setFileTimestamps(metaPath, returnedLastUpdated, returnedLastUpdated, serverTz);
+          for (const col of (meta._companionReferenceColumns || meta._contentColumns || [])) {
+            const ref = meta[col];
+            if (ref && String(ref).startsWith('@')) {
+              const fp = join(metaDir, String(ref).substring(1));
+              await upsertDeployEntry(fp, returnedUID, entity, col);
+              try { await setFileTimestamps(fp, returnedLastUpdated, returnedLastUpdated, serverTz); } catch {}
             }
-          } catch { /* non-critical */ }
-        }
-
-        // Update .app_baseline.json so subsequent pull/diff recognize this record
-        await updateBaselineWithNewRecord(meta, returnedUID, returnedLastUpdated);
+          }
+          if (meta._mediaFile && String(meta._mediaFile).startsWith('@')) {
+            const mediaFp = join(metaDir, String(meta._mediaFile).substring(1));
+            await upsertDeployEntry(mediaFp, returnedUID, entity, 'File');
+          }
+        } catch { /* non-critical */ }
       }
+
+      // Update .app_baseline.json so subsequent pull/diff recognize this record
+      await updateBaselineWithNewRecord(meta, returnedUID, returnedLastUpdated);
       log.dim(`  Run "dbo pull -e ${entity} ${returnedUID}" to populate all columns`);
     }
   }
@@ -497,8 +482,8 @@ export async function findUnaddedFiles(dir, ig, referencedFiles) {
       const raw = await readFile(join(dir, entry.name), 'utf8');
       if (!raw.trim()) continue;
       const meta = JSON.parse(raw);
-      // Only count records that are on the server (have UID or _CreatedOn)
-      if (!meta.UID && !meta._CreatedOn) continue;
+      // Only count records that are on the server (have _CreatedOn or _LastUpdated)
+      if (!meta._CreatedOn && !meta._LastUpdated) continue;
       collectCompanionRefs(meta, localRefs);
     } catch { /* skip unreadable */ }
   }
@@ -566,7 +551,7 @@ async function _scanMetadataRefs(dir, referenced) {
       const raw = await readFile(fullPath, 'utf8');
       if (!raw.trim()) continue;
       const meta = JSON.parse(raw);
-      if (!meta._CreatedOn && !meta.UID) continue; // only count server-confirmed records
+      if (!meta._CreatedOn && !meta._LastUpdated) continue; // only count server-confirmed records
 
       // Collect all @ references (including from inline output children)
       const allRefs = new Set();

package/src/lib/structure.js

@@ -16,7 +16,7 @@ export const BINS_DIR = 'lib/bins';
 export const SCAFFOLD_DIRS = [
   'lib/bins',
   'lib/app_version',
-  'lib/entity',
+  'lib/data_source',
   'lib/extension',
   'lib/security',
   'src',
@@ -32,7 +32,6 @@ export const SCAFFOLD_DIRS = [
  */
 export const ON_DEMAND_ENTITY_DIRS = new Set([
   'automation',
-  'data_source',
   'entity_column',
   'entity_column_value',
   'group',
@@ -48,7 +47,6 @@ export const ON_DEMAND_ENTITY_DIRS = new Set([
  */
 export const DEFAULT_PROJECT_DIRS = [
   ...SCAFFOLD_DIRS,
-  'lib/data_source',
   'lib/group',
   'lib/redirect',
   'lib/site',
@@ -87,16 +85,26 @@ export const ENTITY_DIR_NAMES = new Set([
   'site',
 ]);
 
+/**
+ * Entity types that are co-located in another entity's directory.
+ * Maps entity name → directory name (both live under lib/<dirName>/).
+ */
+const ENTITY_DIR_REMAP = {
+  entity: 'data_source',
+};
+
 /**
  * Resolve the local directory path for an entity-dir type.
- * Always returns "lib/<entityName>" (e.g. "lib/extension", "lib/site").
+ * Most entities map to "lib/<entityName>"; remapped entities (e.g. "entity"
+ * → "lib/data_source") are defined in ENTITY_DIR_REMAP.
  * Use this instead of bare entity name concatenation everywhere.
  *
  * @param {string} entityName - Entity key from ENTITY_DIR_NAMES (e.g. "extension")
  * @returns {string} - Path relative to project root (e.g. "lib/extension")
  */
 export function resolveEntityDirPath(entityName) {
-  return `${LIB_DIR}/${entityName}`;
+  const dirName = ENTITY_DIR_REMAP[entityName] ?? entityName;
+  return `${LIB_DIR}/${dirName}`;
 }
 
 // ─── Core Asset Entity Classification ─────────────────────────────────────
@@ -421,7 +429,9 @@ export async function loadDescriptorMapping() {
 
 /**
  * Resolve the sub-directory path for a single extension record.
- * Returns "extension/<MappedName>" or "extension/_unsupported".
+ * Returns "lib/extension/<MappedName>" for mapped descriptors,
+ * "lib/extension/<descriptor>" for unmapped descriptors with a value,
+ * or "lib/extension" for records with no descriptor.
  *
  * @param {Object} record   - Extension record with a .Descriptor field
  * @param {Object} mapping  - descriptor key → dir name (from buildDescriptorMapping)
@@ -429,8 +439,13 @@ export async function loadDescriptorMapping() {
  */
 export function resolveExtensionSubDir(record, mapping) {
   const descriptor = record.Descriptor;
-  if (!descriptor || !mapping[descriptor]) {
+  if (!descriptor) {
     return EXTENSION_DESCRIPTORS_DIR;
   }
-  return `${EXTENSION_DESCRIPTORS_DIR}/${mapping[descriptor]}`;
+  if (mapping[descriptor]) {
+    return `${EXTENSION_DESCRIPTORS_DIR}/${mapping[descriptor]}`;
+  }
+  // Unmapped descriptor (no descriptor_definition record): use the raw descriptor
+  // value as the directory name — matches the directory created by buildDescriptorPrePass.
+  return `${EXTENSION_DESCRIPTORS_DIR}/${descriptor}`;
 }

package/src/lib/ticketing.js

@@ -1,7 +1,7 @@
 import { readFile, writeFile, mkdir } from 'fs/promises';
 import { join } from 'path';
 import { log } from './logger.js';
-import { projectDir } from './config.js';
+import { projectDir, saveRepositoryIntegrationID, loadRepositoryIntegrationID } from './config.js';
 
 const TICKETING_FILE = 'ticketing.local.json';
 
@@ -283,13 +283,14 @@ export async function checkStoredTicket(options, context = '') {
 }
 
 /**
- * Apply a stored ticket to submission data expressions if no --ticket flag is set.
- * Checks per-record ticket first, then global ticket.
+ * Look up and return the active stored ticket for a submission, if no --ticket flag is set.
+ * Checks per-record ticket first, then global ticket. Callers pass the returned value
+ * to _OverrideTicketID in extraParams.
  *
- * @param {string[]} dataExprs - The data expressions array (mutated in place)
- * @param {string} entity - Entity name
- * @param {string|number} rowId - Row ID or UID used in the submission
- * @param {string} uid - Record UID for per-record lookup
+ * @param {string[]} dataExprs - Unused; kept for backwards compatibility
+ * @param {string} entity - Unused; kept for backwards compatibility
+ * @param {string|number} rowId - Unused; kept for backwards compatibility
+ * @param {string} uid - Record UID for per-record ticket lookup
  * @param {Object} options - Command options
  * @param {string|null} [sessionOverride] - One-time ticket override from pre-flight prompt
  */
@@ -301,10 +302,66 @@ export async function applyStoredTicketToSubmission(dataExprs, entity, rowId, ui
   const ticketToUse = sessionOverride || recordTicket || globalTicket;
 
   if (ticketToUse) {
-    const ticketExpr = buildTicketExpression(entity, rowId, ticketToUse);
-    dataExprs.push(ticketExpr);
+    // Don't add _LastUpdatedTicketID to dataExprs — callers set _OverrideTicketID in extraParams,
+    // which is sufficient and avoids server-side RowUID lookup failures on some entities (e.g. extension).
     log.dim(`  Applying ticket: ${ticketToUse}`);
     return ticketToUse;
   }
   return null;
 }
+
+/**
+ * Fetch the app object from the server and cache RepositoryIntegrationID in .app/config.json.
+ *
+ * Uses UpdatedAfter=<today> to keep the response small — children records are filtered
+ * but the top-level app record (including RepositoryIntegrationID) is always returned.
+ *
+ * @param {DboClient} client
+ * @param {string} appShortName
+ * @returns {Promise<{ id: string|null, fetched: boolean }>}
+ *   id: the RepositoryIntegrationID value (or null if not set)
+ *   fetched: true if the server responded successfully, false on network/parse failure
+ */
+export async function fetchAndCacheRepositoryIntegration(client, appShortName) {
+  if (!appShortName) return { id: null, fetched: false };
+
+  try {
+    const today = new Date().toISOString().substring(0, 10); // YYYY-MM-DD
+    const result = await client.get(
+      `/api/app/object/${encodeURIComponent(appShortName)}`,
+      { UpdatedAfter: today }
+    );
+
+    if (!result.ok && !result.successful) return { id: null, fetched: false };
+
+    const data = result.payload || result.data;
+    if (!data) return { id: null, fetched: false };
+
+    // Normalize response shape (array, Rows wrapper, or direct object)
+    let appRecord;
+    if (Array.isArray(data)) {
+      appRecord = data.length > 0 ? data[0] : null;
+    } else if (data?.Rows?.length > 0) {
+      appRecord = data.Rows[0];
+    } else if (data?.rows?.length > 0) {
+      appRecord = data.rows[0];
+    } else if (data && typeof data === 'object' && (data.UID || data.ShortName)) {
+      appRecord = data;
+    } else {
+      return { id: null, fetched: false };
+    }
+
+    if (!appRecord) return { id: null, fetched: false };
+
+    const id = (appRecord.RepositoryIntegrationID != null && appRecord.RepositoryIntegrationID !== '')
+      ? appRecord.RepositoryIntegrationID
+      : null;
+
+    // Persist so push can fall back to this if the next fetch fails
+    await saveRepositoryIntegrationID(id);
+
+    return { id, fetched: true };
+  } catch {
+    return { id: null, fetched: false };
+  }
+}