actor-debugger 0.1.1 → 0.1.2

package/README.md

@@ -54,6 +54,22 @@ in your sources (via source maps), step, inspect — no `devtools://` URL, no lo
 Prefer the raw channel? `npx wscat -c "wss://<run>.runs.apify.net/<uuid>"`, or point
 `Playwright/Puppeteer connectOverCDP` at that wss URL.
 
+## TypeScript sources (automatic)
+
+A remote DevTools frontend can never fetch `file://` URLs from the container, so external
+`.js.map` files — the standard `"sourceMap": true` tsc output — are unreachable to it, and
+DevTools would fall back to the generated JS ("Source map failed to load"). The debugger fixes
+this itself at startup: it scans the compiled output, reads each external `.map` from the
+container's disk, embeds the original TS text into it (`sourcesContent`, read from the `.ts`
+files in the image), and rewrites the reference into an inline `data:` URL. Any tsc setup that
+emits source maps at all (`sourceMap` or `inlineSourceMap`) therefore just works — no tsconfig
+changes needed.
+
+The one unrecoverable case is a build with no source maps: then the run log prints a hint to
+compile with `"sourceMap": true`. If the `.ts` files aren't in the image (a multi-stage build
+copying only `dist/`), mappings still inline but sources can't be shown — the log says so; `COPY`
+your `src/` into the final stage to fix it.
+
 ## Entrypoint detection order
 
 1. An explicit path argument, if given.

package/bin/cli.mjs

@@ -17,6 +17,7 @@ import { createRequire } from 'node:module';
 import path from 'node:path';
 
 import { startDebugServer } from '../lib/debug_server.mjs';
+import { inlineSourceMaps } from '../lib/inline_sourcemaps.mjs';
 
 const INSPECTOR_PORT = 9229;
 const TAG = '[actor-debugger]';
@@ -110,6 +111,19 @@ if (!entry) {
     process.exit(1);
 }
 
+// A remote DevTools frontend cannot fetch file:// URLs, so external .map files (and the .ts
+// sources they reference) are unreachable to it. Inline them into the compiled files up front.
+const mapRoot = path.resolve(path.dirname(entry)).startsWith(process.cwd()) ? process.cwd() : path.dirname(entry);
+const maps = inlineSourceMaps(mapRoot, (msg) => console.error(`${TAG} ${msg}`));
+if (maps.inlined > 0) {
+    console.error(`${TAG} inlined ${maps.inlined} source map(s) so DevTools can show original sources.`);
+    if (maps.missingSources > 0) {
+        console.error(`${TAG} ${maps.missingSources} original source file(s) not in the image - those stay JS-only. COPY your src/ into the image to fix.`);
+    }
+} else if (maps.alreadyInline === 0) {
+    console.error(`${TAG} no source maps found - TS Actors: compile with "sourceMap": true to debug original sources.`);
+}
+
 const inspectFlag = brk ? '--inspect-brk' : '--inspect';
 const nodeArgs = ['--enable-source-maps', `${inspectFlag}=127.0.0.1:${INSPECTOR_PORT}`];
 

package/lib/inline_sourcemaps.mjs

@@ -0,0 +1,128 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const SKIP_DIRS = new Set(['node_modules', '.git', '.actor', 'apify_storage', 'storage']);
+const JS_EXT = new Set(['.js', '.mjs', '.cjs']);
+const MAP_RE = /(\/\/[#@][ \t]*sourceMappingURL=)([^\s]+)/g;
+const MAX_FILES = 5000;
+
+function lastMapRef(source) {
+    let match = null;
+    for (const m of source.matchAll(MAP_RE)) match = m;
+    return match;
+}
+
+function decodeDataUrl(url) {
+    const m = /^data:application\/json[^,]*;base64,(.*)$/.exec(url);
+    if (!m) return null;
+    try {
+        return JSON.parse(Buffer.from(m[1], 'base64').toString('utf8'));
+    } catch {
+        return null;
+    }
+}
+
+/** Fill in map.sourcesContent from the .ts/.js sources on disk where missing. */
+function embedSources(map, mapDir) {
+    const sources = map.sources ?? [];
+    const content = map.sourcesContent ?? new Array(sources.length).fill(null);
+    let missing = 0;
+    for (let i = 0; i < sources.length; i++) {
+        if (content[i] != null) continue;
+        const src = sources[i];
+        if (!src || /^[a-z+]+:/i.test(src)) {
+            missing++;
+            continue;
+        }
+        const file = path.resolve(mapDir, map.sourceRoot ?? '', src);
+        try {
+            content[i] = fs.readFileSync(file, 'utf8');
+        } catch {
+            missing++;
+        }
+    }
+    map.sourcesContent = content;
+    return missing;
+}
+
+/**
+ * Make every compiled file's source map usable by a REMOTE DevTools frontend. The browser serving
+ * our DevTools UI can never fetch `file://` URLs from the container, so external `.map` files (and
+ * the original .ts sources they point at) are unreachable to it - only what is embedded in the
+ * script itself gets through the inspector. This walks `rootDir`, and for each .js/.mjs/.cjs file:
+ *  - resolves an external sourceMappingURL against the file, reading the .map from disk;
+ *  - embeds the original sources into the map (`sourcesContent`) from disk where missing;
+ *  - rewrites the sourceMappingURL comment to an inline base64 `data:` URL.
+ * Already-inline maps just get missing `sourcesContent` filled in. Files without a map reference
+ * are left untouched.
+ *
+ * @returns {{ inlined: number, alreadyInline: number, scanned: number, missingSources: number }}
+ */
+export function inlineSourceMaps(rootDir, log = () => {}) {
+    const stats = { inlined: 0, alreadyInline: 0, scanned: 0, missingSources: 0 };
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        } catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (stats.scanned >= MAX_FILES) return;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.')) walk(full);
+                continue;
+            }
+            if (!entry.isFile() || !JS_EXT.has(path.extname(entry.name))) continue;
+            stats.scanned++;
+            processFile(full, stats, log);
+        }
+    };
+    walk(rootDir);
+    return stats;
+}
+
+function processFile(file, stats, log) {
+    let source;
+    try {
+        source = fs.readFileSync(file, 'utf8');
+    } catch {
+        return;
+    }
+    const ref = lastMapRef(source);
+    if (!ref) return;
+    const url = ref[2];
+
+    let map;
+    let alreadyInline = false;
+    if (url.startsWith('data:')) {
+        map = decodeDataUrl(url);
+        alreadyInline = true;
+        // Inline map already carrying all sources - nothing for us to do.
+        if (map && (map.sourcesContent ?? []).length >= (map.sources ?? []).length
+            && (map.sourcesContent ?? []).every((c) => c != null)) {
+            stats.alreadyInline++;
+            return;
+        }
+    } else if (!/^[a-z+]+:/i.test(url)) {
+        try {
+            map = JSON.parse(fs.readFileSync(path.resolve(path.dirname(file), url), 'utf8'));
+        } catch {
+            log(`map file for ${file} not readable (${url}) - skipped`);
+            return;
+        }
+    }
+    if (!map) return;
+
+    stats.missingSources += embedSources(map, path.dirname(file));
+    const dataUrl = `data:application/json;base64,${Buffer.from(JSON.stringify(map)).toString('base64')}`;
+    const start = ref.index + ref[1].length;
+    const patched = source.slice(0, start) + dataUrl + source.slice(start + url.length);
+    try {
+        fs.writeFileSync(file, patched);
+        stats.inlined++;
+    } catch {
+        log(`could not rewrite ${file} - skipped${alreadyInline ? '' : ' (map stays external)'}`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "actor-debugger",
-    "version": "0.1.1",
+    "version": "0.1.2",
     "description": "Drop-in remote debugger for Apify Node/TS Actors: one Dockerfile CMD line launches your Actor under the Node inspector, reachable over the run's container URL. No local setup, no rebuild of your own code.",
     "type": "module",
     "bin": {