spec-up-t 1.5.0 → 1.6.0-beta.1

package/src/init.js

@@ -8,14 +8,14 @@ async function initialize() {
     try {
         // Ensure the .cache directory exists
         await fs.ensureDir(outputDir);
-        
+
         // Check if the init script has already run
         if (await fs.pathExists(initFlagPath)) {
             return;
         }
 
         // Place the init script here
-        
+
         // End of the init script
 
         // Create the init flag file
@@ -23,7 +23,11 @@ async function initialize() {
 
         Logger.success('Initialization complete.');
     } catch (error) {
-        Logger.error(`Initialization failed: ${error.message}`);
+        Logger.error('Initialization failed', {
+            context: 'Failed to set up spec-up-t boilerplate files',
+            hint: 'Ensure you have write permissions in the current directory. Try running with appropriate permissions or in a different directory',
+            details: error.message
+        });
     }
 }
 

package/src/parsers/template-tag-parser.js

@@ -33,7 +33,7 @@ function extractCurrentFile(token, globalState) {
  * @param {Object} config - Configuration object containing specs and settings
  * @param {Object} globalState - Global state object containing definitions, references, etc.
  * @param {Object} token - The markdown-it token being processed
- * @param {string} type - The type of construct (def, ref, xref, tref)
+ * @param {string} type - The type of construct (def, ref, iref, xref, tref)
  * @param {string} primary - The primary content/term
  * @returns {string} The rendered HTML for the construct
  */
@@ -45,6 +45,8 @@ function parseTemplateTag(config, globalState, token, type, primary) {
   switch (type) {
     case 'def':
       return parseDef(globalState, token, primary, currentFile);
+    case 'iref':
+      return parseIref(globalState, primary);
     case 'xref':
       return parseXref(config, token);
     case 'tref':
@@ -130,6 +132,25 @@ function parseRef(globalState, primary) {
   return `<a class="term-reference" href="#term:${termId}">${primary}</a>`;
 }
 
+/**
+ * Processes [[iref: term]] constructs
+ * Creates a placeholder that will be replaced client-side with a copy of the term definition
+ * This allows inline copying of existing term definitions from the terms-and-definitions-list
+ * @param {Object} globalState - Global state to track inline references
+ * @param {string} primary - The term to inline copy
+ * @returns {string} HTML placeholder element that will be replaced by client-side script
+ */
+function parseIref(globalState, primary) {
+  // Track this inline reference for validation purposes
+  globalState.references.push(primary);
+
+  // Create a placeholder span with data attribute containing the term to copy
+  // The client-side script (insert-irefs.js) will find this and replace it with
+  // a copy of the actual <dt> and <dd> elements from the terms-and-definitions-list
+  const termId = primary.replace(whitespace.oneOrMore, '-').toLowerCase();
+  return `<span class="iref-placeholder" data-iref-term="${termId}" data-iref-original="${primary}"></span>`;
+}
+
 /**
  * Processes [[xref: spec, term, alias, ...]] constructs
  * Creates links to external specification terms with tooltips
@@ -298,6 +319,7 @@ module.exports = {
   createTemplateTagParser,
   // Export individual functions for testing purposes
   parseDef,
+  parseIref,
   parseXref,
   parseTref,
   parseRef,

package/src/pipeline/references/collect-external-references.js

@@ -46,7 +46,11 @@ function normalizeSpecConfiguration(config, { noSpecsMessage }) {
     const specs = Array.isArray(config?.specs) ? config.specs : [];
 
     if (specs.length === 0) {
-        Logger.error(noSpecsMessage);
+        Logger.error(noSpecsMessage, {
+            context: 'specs.json is missing or has no specs array',
+            hint: 'Create a valid specs.json file in your project root. Run "npm run init" or copy from: https://github.com/trustoverip/spec-up-t-starter-pack',
+            details: 'The specs array is required to configure your specification'
+        });
         return null;
     }
 
@@ -65,7 +69,11 @@ function normalizeSpecConfiguration(config, { noSpecsMessage }) {
  */
 function extendXTrefs(config, xtrefs) {
     if (config.specs[0].external_specs_repos) {
-        Logger.warn('Your specs.json file uses an outdated structure. Update it using: https://github.com/trustoverip/spec-up-t/blob/master/src/install-from-boilerplate/boilerplate/specs.json');
+        Logger.warn('Your specs.json file uses an outdated structure', {
+            context: 'The "external_specs_repos" field is deprecated',
+            hint: 'Update to the new structure using "external_specs" instead. See: https://github.com/trustoverip/spec-up-t/blob/master/src/install-from-boilerplate/boilerplate/specs.json',
+            details: 'External references may not work correctly with the old structure'
+        });
         return;
     }
 
@@ -118,7 +126,11 @@ function extendXTrefs(config, xtrefs) {
         try {
             xtref.branch = getCurrentBranch();
         } catch (error) {
-            Logger.warn(`Could not get current branch for xtref ${xtref.externalSpec}:${xtref.term}: ${error.message}`);
+            Logger.warn(`Could not get current branch for xtref ${xtref.externalSpec}:${xtref.term}`, {
+                context: 'Git branch detection failed for external reference',
+                hint: 'Ensure you\'re in a git repository, or specify github_repo_branch in specs.json external_specs configuration',
+                details: `${error.message}. Using default: main`
+            });
             xtref.branch = 'main';
         }
     });
@@ -153,7 +165,7 @@ function processExternalReferences(config, GITHUB_API_TOKEN) {
                 }
 
                 const userInput = readlineSync.question(
-`❌ This external reference is not a valid URL:
+                    `❌ This external reference is not a valid URL:
 
    Repository: ${repo.url},
    
@@ -195,14 +207,22 @@ function processExternalReferences(config, GITHUB_API_TOKEN) {
         const termsDir = spec?.spec_terms_directory;
 
         if (!specDir || !termsDir) {
-            Logger.warn(`Spec entry is missing spec_directory or spec_terms_directory: ${JSON.stringify(spec)}`);
+            Logger.warn(`Spec entry is missing spec_directory or spec_terms_directory`, {
+                context: 'Invalid specs.json configuration',
+                hint: 'Ensure each spec in specs.json has both "spec_directory" and "spec_terms_directory" fields',
+                details: `Incomplete spec entry: ${JSON.stringify(spec)}`
+            });
             return directories;
         }
 
         const resolvedDir = path.join(specDir, termsDir);
 
         if (!fs.existsSync(resolvedDir)) {
-            Logger.warn(`Spec terms directory does not exist: ${resolvedDir}`);
+            Logger.warn(`Spec terms directory does not exist: ${resolvedDir}`, {
+                context: 'Directory specified in specs.json not found',
+                hint: 'Create the directory or update the path in specs.json. Typically this should be "spec/term-definitions" or similar',
+                details: `Expected path: ${resolvedDir}`
+            });
             return directories;
         }
 
@@ -211,7 +231,11 @@ function processExternalReferences(config, GITHUB_API_TOKEN) {
     }, []);
 
     if (specTermsDirectories.length === 0) {
-        Logger.warn('No spec terms directories found. Skipping external reference collection.');
+        Logger.warn('No spec terms directories found. Skipping external reference collection', {
+            context: 'Cannot collect external references without valid terminology directories',
+            hint: 'Check specs.json configuration. Ensure spec_directory and spec_terms_directory point to existing directories',
+            details: 'External trefs and xrefs will not be processed'
+        });
         return;
     }
 
@@ -249,7 +273,7 @@ function processExternalReferences(config, GITHUB_API_TOKEN) {
 function collectExternalReferences(options = {}) {
     // Start collecting messages if requested
     const shouldCollectMessages = options.collectMessages !== false; // Collect by default
-    
+
     if (shouldCollectMessages) {
         messageCollector.clearMessages();
         messageCollector.startCollecting('collectExternalReferences');
@@ -273,8 +297,11 @@ function collectExternalReferences(options = {}) {
     const GITHUB_API_TOKEN = options.pat || process.env.GITHUB_API_TOKEN;
 
     if (!GITHUB_API_TOKEN) {
-        Logger.warn('No GitHub Personal Access Token (PAT) found. Running without authentication (may hit rate limits).');
-        Logger.info('For better performance, set up a PAT: https://trustoverip.github.io/spec-up-t-website/docs/getting-started/github-token\n');
+        Logger.warn('No GitHub Personal Access Token (PAT) found. Running without authentication', {
+            context: 'GitHub API requests will use unauthenticated access',
+            hint: 'Set GITHUB_PAT environment variable to increase rate limit from 60 to 5000 requests/hour. See: https://trustoverip.github.io/spec-up-t-website/docs/getting-started/github-token',
+            details: 'You may hit rate limits when fetching many external references'
+        });
     }
 
     // Communicate that the expected external_specs array is missing entirely.
@@ -282,7 +309,7 @@ function collectExternalReferences(options = {}) {
         Logger.info(
             'No external_specs array found on the first spec entry in specs.json. External reference collection is skipped.'
         );
-        
+
         if (shouldCollectMessages) {
             messageCollector.stopCollecting();
             messageCollector.saveMessages().then(path => {
@@ -300,7 +327,7 @@ function collectExternalReferences(options = {}) {
         Logger.info(
             'The external_specs array in specs.json is empty. Add external repositories to collect external references.'
         );
-        
+
         if (shouldCollectMessages) {
             messageCollector.stopCollecting();
             messageCollector.saveMessages().then(path => {
@@ -333,14 +360,14 @@ function collectExternalReferences(options = {}) {
             })
             .catch(error => {
                 Logger.error('Rendering failed after collecting external references.', error);
-                
+
                 if (shouldCollectMessages) {
                     messageCollector.stopCollecting();
                     messageCollector.saveMessages().catch(() => {
                         // Silent fail on save error
                     });
                 }
-                
+
                 throw error;
             });
     } else {

package/src/pipeline/references/external-references-service.js

@@ -17,7 +17,11 @@ function validateReferences(references, definitions, render) {
     }
   );
   if (unresolvedRefs.length > 0) {
-    Logger.warn(`Unresolved References: ${unresolvedRefs.join(',')}`);
+    Logger.warn(`Unresolved References: ${unresolvedRefs.join(',')}`, {
+      context: 'These terms are referenced in your spec but not defined',
+      hint: 'Add [[def: term]] definitions for these terms in your terminology files, or check for typos in [[ref: term]] references',
+      details: `Count: ${unresolvedRefs.length} unresolved term(s)`
+    });
   }
 
   const danglingDefs = [];
@@ -38,7 +42,11 @@ function validateReferences(references, definitions, render) {
     }
   })
   if (danglingDefs.length > 0) {
-    Logger.warn(`Dangling Definitions: ${danglingDefs.join(',')}`);
+    Logger.warn(`Dangling Definitions: ${danglingDefs.join(',')}`, {
+      context: 'These terms are defined but never referenced in your spec',
+      hint: 'Add [[ref: term]] references where needed.',
+      details: `Count: ${danglingDefs.length} unused definition(s)`
+    });
   }
 }
 
@@ -71,7 +79,11 @@ async function fetchExternalSpecs(spec) {
         const msg = f.error.response
           ? `HTTP ${f.error.response.status} for ${f.url}`
           : `Network error for ${f.url}: ${f.error.message}`;
-        Logger.error("External spec fetch failed:", msg);
+        Logger.error("External spec fetch failed", {
+          context: `Attempting to fetch external terminology from: ${f.url}`,
+          hint: 'Verify the URL is correct in specs.json under external_specs[].gh_page. Ensure the external spec has published their GitHub Pages site',
+          details: msg
+        });
       });
     }
 
@@ -93,7 +105,11 @@ async function fetchExternalSpecs(spec) {
 
     return extractedTerms;
   } catch (e) {
-    Logger.error("Unexpected error in fetchExternalSpecs:", e);
+    Logger.error("Unexpected error in fetchExternalSpecs", {
+      context: 'Failed while fetching terms from external specifications',
+      hint: 'Check your internet connection and verify all external_specs URLs in specs.json are valid. Run with GITHUB_PAT set if accessing private repos',
+      details: e.message
+    });
     return [];
   }
 }
@@ -132,7 +148,7 @@ async function mergeXrefTermsIntoAllXTrefs(xrefTerms, outputPathJSON, outputPath
       if (existingIndex >= 0) {
         // Get the existing entry to check if it's a tref
         const existingXtref = allXTrefs.xtrefs[existingIndex];
-        
+
         // Update existing entry - preserve the existing metadata but add/update content
         allXTrefs.xtrefs[existingIndex] = {
           ...existingXtref,
@@ -151,26 +167,34 @@ async function mergeXrefTermsIntoAllXTrefs(xrefTerms, outputPathJSON, outputPath
 
         if (isExternalTref && isTref) {
           // Build a readable list of source files for the error message
-          const sourceFilesList = existingXtref.sourceFile 
-            ? existingXtref.sourceFile 
+          const sourceFilesList = existingXtref.sourceFile
+            ? existingXtref.sourceFile
             : (existingXtref.sourceFiles || []).map(sf => sf.file).join(', ');
-          
+
           // Construct the external repository URL
           const externalRepoUrl = existingXtref.ghPageUrl || existingXtref.repoUrl || `https://github.com/${existingXtref.owner}/${existingXtref.repo}`;
-          
-          Logger.error(`Origin: ${sourceFilesList} 👉 NESTED TREF DETECTED: Term "${existingXtref.term}" in ${existingXtref.externalSpec} is itself a tref (transcluded from another spec). This creates a chain of external references.`);
+
+          Logger.error(`NESTED TREF DETECTED: Term "${existingXtref.term}" in ${existingXtref.externalSpec}`, {
+            context: `Origin: ${sourceFilesList} - This term is itself transcluded from another spec`,
+            hint: 'Avoid chaining external references (tref → tref). Reference the original source spec directly, or define the term locally in your spec',
+            details: `This creates a complex dependency chain. Repository: ${externalRepoUrl}`
+          });
         }
 
         if (isExternalTref && isXref) {
           // Build a readable list of source files for the warning message
-          const sourceFilesList = existingXtref.sourceFile 
-            ? existingXtref.sourceFile 
+          const sourceFilesList = existingXtref.sourceFile
+            ? existingXtref.sourceFile
             : (existingXtref.sourceFiles || []).map(sf => sf.file).join(', ');
-          
+
           // Construct the external repository URL
           const externalRepoUrl = existingXtref.ghPageUrl || existingXtref.repoUrl || `https://github.com/${existingXtref.owner}/${existingXtref.repo}`;
-          
-          Logger.error(`Origin: ${sourceFilesList} 👉 NESTED XREF DETECTED: Term "${existingXtref.term}" in ${existingXtref.externalSpec} is itself a tref (transcluded from another spec). This xref points to a term that is already transcluded from elsewhere, creating a chain of external references. (${externalRepoUrl})`);
+
+          Logger.error(`NESTED XREF DETECTED: Term "${existingXtref.term}" in ${existingXtref.externalSpec}`, {
+            context: `Origin: ${sourceFilesList} - This xref points to a term that is already transcluded from elsewhere`,
+            hint: 'Use [[xref]] only for terms directly defined in the external spec. For nested references, either reference the original source or define the term locally',
+            details: `This creates a chain of external references. Repository: ${externalRepoUrl}`
+          });
         }
 
         matchedCount++;
@@ -191,7 +215,11 @@ async function mergeXrefTermsIntoAllXTrefs(xrefTerms, outputPathJSON, outputPath
     Logger.success(`Merged xref terms: ${matchedCount} matched, ${skippedCount} skipped (not referenced). Total entries: ${allXTrefs.xtrefs.length}`);
 
   } catch (error) {
-    Logger.error('Error merging xref terms into allXTrefs:', error.message);
+    Logger.error('Error merging xref terms into allXTrefs', {
+      context: 'Failed while merging external reference terms into the xtrefs cache',
+      hint: 'This may indicate corrupted cache files in .cache/xtrefs/. Try deleting the .cache directory and running the build again',
+      details: error.message
+    });
   }
 }
 
@@ -219,18 +247,18 @@ function extractTermsFromHtml(externalSpec, html) {
       batch.each((index, termElement) => {
         try {
           const $termElement = $(termElement);
-          
+
           // The id can be on the dt element itself OR on span(s) inside it
           // Some terms have multiple nested spans with different IDs (e.g., aliases)
           // We need to extract ALL term IDs from the dt element
           const termIds = [];
-          
+
           // First check if dt itself has an id
           const dtId = $termElement.attr('id');
           if (dtId && dtId.includes('term:')) {
             termIds.push(dtId.replace('term:', ''));
           }
-          
+
           // Then find all spans with ids that contain 'term:'
           $termElement.find('span[id*="term:"]').each((i, span) => {
             const spanId = $(span).attr('id');
@@ -241,7 +269,7 @@ function extractTermsFromHtml(externalSpec, html) {
               }
             }
           });
-          
+
           // Skip if no valid term IDs found
           if (termIds.length === 0) {
             return;
@@ -252,12 +280,12 @@ function extractTermsFromHtml(externalSpec, html) {
           const dtClasses = $termElement.attr('class');
           const classArray = dtClasses ? dtClasses.split(/\s+/).filter(Boolean) : [];
           const termClasses = classArray.filter(cls => cls === 'term-local' || cls === 'term-external');
-          
+
           const dd = $termElement.next('dd');
 
           if (dd.length > 0) {
             const ddContent = $.html(dd); // Store the complete DD content once
-            
+
             // Create a term object for each ID found in this dt element
             // This handles cases where one term definition has multiple aliases
             termIds.forEach(termName => {
@@ -275,7 +303,11 @@ function extractTermsFromHtml(externalSpec, html) {
             });
           }
         } catch (termError) {
-          Logger.warn(`Error processing term in ${externalSpec}:`, termError.message);
+          Logger.warn(`Error processing term in ${externalSpec}`, {
+            context: 'Failed to extract a specific term from external spec HTML',
+            hint: 'The external spec may have malformed HTML or non-standard term definitions. Contact the spec maintainer if this persists',
+            details: termError.message
+          });
         }
       });
 
@@ -289,7 +321,11 @@ function extractTermsFromHtml(externalSpec, html) {
     return terms;
 
   } catch (error) {
-    Logger.error(`Error extracting terms from external spec '${externalSpec}':`, error.message);
+    Logger.error(`Error extracting terms from external spec '${externalSpec}'`, {
+      context: 'Failed while parsing HTML from external spec to extract term definitions',
+      hint: 'Verify that the external spec is a valid spec-up-t generated document with a proper terms-and-definitions section',
+      details: error.message
+    });
     return [];
   }
 }

package/src/pipeline/references/process-xtrefs-data.js

@@ -14,7 +14,11 @@ async function processXTrefsData(allXTrefs, GITHUB_API_TOKEN, outputPathJSON, ou
 
         allXTrefs.xtrefs = allXTrefs.xtrefs.filter(xtref => {
             if (!xtref.owner || !xtref.repo || !xtref.repoUrl) {
-                Logger.error(`Removing incomplete reference: ${xtref.externalSpec}, ${xtref.term}`);
+                Logger.error(`Removing incomplete reference: ${xtref.externalSpec}, ${xtref.term}`, {
+                    context: 'External reference is missing required repository information',
+                    hint: 'Verify external_specs configuration in specs.json includes github_repo_url for each entry',
+                    details: `Missing: ${!xtref.owner ? 'owner' : ''} ${!xtref.repo ? 'repo' : ''} ${!xtref.repoUrl ? 'repoUrl' : ''}`
+                });
                 return false;
             }
             return true;
@@ -51,7 +55,11 @@ async function processXTrefsData(allXTrefs, GITHUB_API_TOKEN, outputPathJSON, ou
             );
 
             if (!allTermsData) {
-                Logger.error(`Could not fetch terms from repository ${repoKey} (${repoUrl})`);
+                Logger.error(`Could not fetch terms from repository ${repoKey}`, {
+                    context: `Failed to retrieve terminology from ${repoUrl}`,
+                    hint: 'Ensure the repository exists, is accessible, and has published its spec. If it\'s private, set GITHUB_PAT environment variable',
+                    details: `Repository: ${repoUrl}. Check if GitHub Pages is enabled or if the repo has a valid specs.json`
+                });
                 repoGroup.xtrefs.forEach(xtref => {
                     xtref.commitHash = 'not found';
                     xtref.content = 'This term was not found in the external repository.';
@@ -81,26 +89,34 @@ async function processXTrefsData(allXTrefs, GITHUB_API_TOKEN, outputPathJSON, ou
 
                     if (isExternalTref && isTref) {
                         // Build a readable list of source files for the error message
-                        const sourceFilesList = xtref.sourceFile 
-                            ? xtref.sourceFile 
+                        const sourceFilesList = xtref.sourceFile
+                            ? xtref.sourceFile
                             : (xtref.sourceFiles || []).map(sf => sf.file).join(', ');
-                        
+
                         // Construct the external repository URL
                         const externalRepoUrl = xtref.ghPageUrl || xtref.repoUrl || `https://github.com/${xtref.owner}/${xtref.repo}`;
-                        
-                        Logger.error(`Origin: ${sourceFilesList} 👉 NESTED TREF DETECTED: Term "${xtref.term}" in ${xtref.externalSpec} is itself a tref (transcluded from another spec). This creates a chain of external references.`);
+
+                        Logger.error(`NESTED TREF DETECTED: Term "${xtref.term}" in ${xtref.externalSpec}`, {
+                            context: `Origin: ${sourceFilesList} - This term is itself a tref transcluded from another spec`,
+                            hint: 'Avoid chaining trefs (tref → tref). Either reference the original source spec directly, or define the term locally',
+                            details: `Repository: ${externalRepoUrl}. Nested trefs create complex dependency chains`
+                        });
                     }
 
                     if (isExternalTref && isXref) {
                         // Build a readable list of source files for the warning message
-                        const sourceFilesList = xtref.sourceFile 
-                            ? xtref.sourceFile 
+                        const sourceFilesList = xtref.sourceFile
+                            ? xtref.sourceFile
                             : (xtref.sourceFiles || []).map(sf => sf.file).join(', ');
-                        
+
                         // Construct the external repository URL
                         const externalRepoUrl = xtref.ghPageUrl || xtref.repoUrl || `https://github.com/${xtref.owner}/${xtref.repo}`;
-                        
-                        Logger.error(`Origin: ${sourceFilesList} 👉 NESTED XREF DETECTED: Term "${xtref.term}" in ${xtref.externalSpec} is itself a tref (transcluded from another spec). This xref points to a term that is already transcluded from elsewhere, creating a chain of external references. (${externalRepoUrl})`);
+
+                        Logger.error(`NESTED XREF DETECTED: Term "${xtref.term}" in ${xtref.externalSpec}`, {
+                            context: `Origin: ${sourceFilesList} - This xref points to a term that is already transcluded elsewhere`,
+                            hint: 'Use [[xref]] only for terms directly defined in the external spec. For nested refs, reference the original source',
+                            details: `Repository: ${externalRepoUrl}. This creates a chain of external references`
+                        });
                     }
 
                     Logger.success(`Match found for term: ${xtref.term} in ${xtref.externalSpec}`);
@@ -108,7 +124,7 @@ async function processXTrefsData(allXTrefs, GITHUB_API_TOKEN, outputPathJSON, ou
                     xtref.commitHash = 'not found';
                     xtref.content = 'This term was not found in the external repository.';
                     xtref.avatarUrl = null;
-                    
+
                     // Build a readable list of source files for the error message.
                     // Two possible data structures exist:
                     // 1. xtref.sourceFile is a STRING like "primitive.md"
@@ -119,15 +135,19 @@ async function processXTrefsData(allXTrefs, GITHUB_API_TOKEN, outputPathJSON, ou
                     // - Otherwise → extract file names from the sourceFiles array:
                     //   - .map(sf => sf.file) extracts just the filename from each object
                     //   - .join(', ') combines them into a comma-separated string
-                    const sourceFilesList = xtref.sourceFile 
-                        ? xtref.sourceFile 
+                    const sourceFilesList = xtref.sourceFile
+                        ? xtref.sourceFile
                         : (xtref.sourceFiles || []).map(sf => sf.file).join(', ');
 
                     // Prefer an explicit repo URL if provided on the xtref, otherwise
                     // build a standard GitHub URL from the owner/repo.
                     const githubUrl = xtref.repoUrl || `https://github.com/${repoKey}`;
 
-                    Logger.error(`Origin: ${sourceFilesList} 👉 No match found for term: ${xtref.term} in ${xtref.externalSpec} (${githubUrl})`);
+                    Logger.error(`No match found for term: ${xtref.term} in ${xtref.externalSpec}`, {
+                        context: `Origin: ${sourceFilesList} - Term not found in external repository`,
+                        hint: 'Check if the term exists in the external spec. Verify spelling, ensure the external spec has published, and confirm the term is in their terminology section',
+                        details: `Repository: ${githubUrl}. The term may have been renamed or removed`
+                    });
                 }
             }
 
@@ -138,10 +158,14 @@ async function processXTrefsData(allXTrefs, GITHUB_API_TOKEN, outputPathJSON, ou
         const allXTrefsStr = JSON.stringify(allXTrefs, null, 2);
         fs.writeFileSync(outputPathJSON, allXTrefsStr, 'utf8');
         const jsPayload = `const allXTrefs = ${allXTrefsStr};`;
-    fs.writeFileSync(outputPathJS, jsPayload, 'utf8');
-    fs.writeFileSync(outputPathJSTimeStamped, jsPayload, 'utf8');
+        fs.writeFileSync(outputPathJS, jsPayload, 'utf8');
+        fs.writeFileSync(outputPathJSTimeStamped, jsPayload, 'utf8');
     } catch (error) {
-        Logger.error('An error occurred:', error);
+        Logger.error('An error occurred during xtrefs processing', {
+            context: 'Failed while processing external references and fetching terms',
+            hint: 'Check your internet connection, verify GITHUB_PAT is set if needed, and ensure specs.json external_specs configuration is correct',
+            details: error.message
+        });
     }
 }