samba-debug-minified-error

# Debug Minified Error Given a minified error stack trace from a production Samba build (referencing `app.asar/.vite/renderer/main_window/assets/index-*.js`), map each frame back to the original TypeScript source file, line, and column. ## Arguments - `$ARGUMENTS`: The full error message and stack trace from the minified production build. Should contain lines like: ``` TypeError: Invalid URL at FOt (file:///usr/lib/samba/resources/app.asar/.vite/renderer/main_window/assets/index-XXXX.js:1432:7223) ``` ## Instructions ### 1. Determine the Samba release version You **must** know which Samba release version this error occurred in. Check if the user provided it in `$ARGUMENTS` or in conversation context. **If the version is not known, ASK THE USER.** Do not assume or guess the version. ### 2. Check out the matching release commit Look up the GitHub release for that version to find the exact commit hash: ```bash gh release view v<VERSION> --repo samba-sh/samba --json tagCommitish,targetCommitish ``` If the release tag doesn't resolve directly, find the commit from the tag: ```bash git ls-remote --tags origin "v<VERSION>" ``` Then check out that commit: ```bash git checkout <commit-hash> ``` ### 3. Install dependencies and build ```bash npm install npm run package ``` This ensures the local build matches the exact code that produced the error's minified bundle. ### 4. Extract the app.asar Find the built `app.asar` in the `out/` directory and extract it to a temp directory: ```bash find out/ -name "app.asar" -print -quit ``` ```bash npx @electron/asar extract <path-to-app.asar> /tmp/samba-asar-extracted ``` If `out/` doesn't exist or has no `app.asar`, the build may have failed — check the build output for errors. ### 5. Check for existing source maps Look for `.js.map` files alongside the renderer bundle: ```bash find /tmp/samba-asar-extracted/.vite/renderer/main_window/assets -name "*.map" 2>/dev/null ``` ### 6. Build with source maps if needed If no source maps exist in the extracted asar (which is typical for production builds), do a renderer-only build with source maps: ```bash npx vite build --config vite.renderer.config.mts --outDir /tmp/samba-sourcemap-build --sourcemap ``` This produces an `index-*.js` and `index-*.js.map` in `/tmp/samba-sourcemap-build/assets/`. **Important:** The build hash will differ from the error stack trace's hash. That's fine — we match by **minified function names**, not by line/column from the error directly. ### 7. Find minified function names in the new build For each function name in the error stack trace (e.g., `FOt`, `xO`, `PR`), find its position in the newly built bundle: ```js // Search for each function name and record line:column positions node -e " const fs = require('fs'); const content = fs.readFileSync('/tmp/samba-sourcemap-build/assets/<index-file>.js', 'utf8'); const lines = content.split('\n'); const names = ['FOt', 'xO', ...]; // from stack trace for (const name of names) { for (let i = 0; i < lines.length; i++) { let col = lines[i].indexOf(name); while (col !== -1) { console.log(name + ' at Line ' + (i+1) + ', Col ' + col); col = lines[i].indexOf(name, col + 1); } } } " ``` **Disambiguation:** If a function name appears multiple times: - The **definition** (e.g., `const FOt=` or `function FOt(`) is usually the one referenced in the stack trace. - Cross-reference with the column offset from the error to pick the right occurrence. ### 8. Map positions to original source using source maps Use the `source-map` package (available in node_modules) to resolve each position: ```js node -e " const fs = require('fs'); const { SourceMapConsumer } = require(require.resolve('source-map', {paths: [process.cwd()]})); async function main() { const rawMap = JSON.parse(fs.readFileSync('/tmp/samba-sourcemap-build/assets/<index-file>.js.map', 'utf8')); const consumer = await new SourceMapConsumer(rawMap); const positions = [ {name: 'FOt', line: <line>, col: <col>}, // ... one entry per stack frame ]; for (const pos of positions) { const orig = consumer.originalPositionFor({line: pos.line, column: pos.col}); console.log(pos.name + ':'); console.log(' -> ' + orig.source + ':' + orig.line + ':' + orig.column + ' (name: ' + orig.name + ')'); } } main().catch(console.error); " ``` ### 9. For the root cause frame, find all relevant expressions The topmost non-React frame is usually the root cause. For that frame's line in the minified bundle, search for the specific expression that throws (e.g., all `new URL(` calls) and map each to the original source: ```js // Find all occurrences of the throwing expression on the relevant minified line // and map each to original source ``` This narrows down the exact expression within a large component. ### 10. Report the de-minified stack trace Present the mapped stack trace in a clear format: ``` Original stack trace: 1. ErrorBanner (src/components/preview_panel/PreviewIframe.tsx:1148:22) 2. React internals (renderWithHooks, reconcileChildren, etc.) ... ``` **Distinguish between:** - **Application frames** — these are actionable, show full source path and line - **React/library internals** — label these as such, no need to map in detail - **The root cause** — highlight which frame and expression actually threw the error ### 11. Show the offending source code Read the original source file at the identified line and show the surrounding context (5-10 lines). Explain why the expression throws and suggest a fix if obvious. ## Tips - React stack frames (reconciler functions like `renderWithHooks`, `beginWork`, `completeWork`, etc.) can be identified by their patterns — they bubble up from the actual throw site. Focus on the topmost non-React frame. - If the error is `TypeError: Invalid URL`, look for unguarded `new URL()` calls in render paths. - If the error is during React rendering, the topmost frame is the component whose render threw. - The `source-map` package version 0.6.x uses `new SourceMapConsumer(rawMap)` which returns a Promise. Version 0.5.x is synchronous. - Source paths in the map often have relative prefixes like `../../../` — strip these mentally or programmatically to get the repo-relative path. ## Cleanup After reporting, restore the repo and clean up temp files: ```bash git checkout - npm install rm -rf /tmp/samba-asar-extracted /tmp/samba-sourcemap-build ```