@bobfrankston/importgen 0.1.10

package/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run build:*)",
+      "Bash(npmglobalize)"
+    ]
+  }
+}

package/.hintrc

@@ -0,0 +1,10 @@
+{
+  "extends": [
+    "development"
+  ],
+  "browserslist": [
+    "defaults",
+    "not ie 11",
+    "not ios_saf <= 15.8"
+  ]
+}

package/README.md

@@ -0,0 +1,91 @@
+# @bobfrankston/importgen
+
+Generate ES Module import maps from package.json dependencies for native browser module loading.
+
+## Installation
+
+```bash
+npm install -g @bobfrankston/importgen
+```
+
+## Usage
+
+In a directory with `package.json` and `index.html`:
+
+```bash
+# Generate once
+importgen
+
+# Watch for package.json changes
+importgen -w
+```
+
+## Automatic Generation with VS Code Tasks
+
+Add to `.vscode/tasks.json`:
+
+```json
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "importgen: watch",
+      "type": "shell",
+      "command": "importgen",
+      "args": ["-w"],
+      "runOptions": {
+        "runOn": "folderOpen"
+      },
+      "isBackground": true
+    }
+  ]
+}
+```
+
+## How It Works
+
+1. Reads `package.json` dependencies
+2. **Recursively resolves** all transitive dependencies
+3. Handles `file:` protocol dependencies and npm packages
+4. Detects and avoids circular dependencies
+5. Resolves correct entry points using `exports`, `module`, or `main` fields
+6. Generates import map with relative paths from HTML location
+7. Injects or updates `<script type="importmap">` in `index.html`
+8. In watch mode, regenerates when `package.json` changes
+
+### Circular Dependency Protection
+
+The tool tracks visited packages to prevent infinite loops when packages have circular dependencies (A → B → A). Each package is processed only once.
+
+## PWA Compatible
+
+Generated import maps are static and can be cached by service workers, making this ideal for Progressive Web Apps.
+
+## Example
+
+**package.json:**
+```json
+{
+  "dependencies": {
+    "@bobfrankston/lxlan": "^0.1.0",
+    "@bobfrankston/colorlib": "file:../colorlib"
+  }
+}
+```
+
+If `lxlan` depends on `lxlan-browser`, and `lxlan-browser` depends on `colorlib`, **all three packages** will be included in the generated import map:
+
+**Generated in index.html:**
+```html
+<script type="importmap">
+    {
+        "imports": {
+            "@bobfrankston/lxlan": "./node_modules/@bobfrankston/lxlan/index.js",
+            "@bobfrankston/lxlan-browser": "./node_modules/@bobfrankston/lxlan-browser/index.js",
+            "@bobfrankston/colorlib": "../colorlib/index.js"
+        }
+    }
+</script>
+```
+
+Note: The tool automatically resolves transitive dependencies and handles both npm packages and `file:` protocol dependencies.

package/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Generate ES Module import map from package.json dependencies
+ * Injects into HTML files for native browser module loading
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+/**
+ * Generate ES Module import map from package.json dependencies
+ * Injects into HTML files for native browser module loading
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import chokidar from 'chokidar';
+// Get version from package.json
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageJson = JSON.parse(fs.readFileSync(path.join(__dirname, 'package.json'), 'utf-8'));
+const VERSION = packageJson.version;
+/**
+ * Resolve dependency path based on version specifier
+ */
+function resolveDependencyPath(packageDir, depName, depVersion) {
+    if (depVersion.startsWith('file:')) {
+        // Handle file: protocol - resolve relative to package directory
+        const relativePath = depVersion.slice(5); // Remove 'file:' prefix
+        return path.resolve(packageDir, relativePath);
+    }
+    else if (depVersion.startsWith('workspace:')) {
+        // Workspace dependencies - look in node_modules
+        const nodeModulesPath = path.join(packageDir, 'node_modules', depName);
+        if (fs.existsSync(nodeModulesPath)) {
+            return nodeModulesPath;
+        }
+        return null;
+    }
+    else {
+        // npm version - look in node_modules
+        const nodeModulesPath = path.join(packageDir, 'node_modules', depName);
+        if (fs.existsSync(nodeModulesPath)) {
+            return nodeModulesPath;
+        }
+        return null;
+    }
+}
+/**
+ * Resolve entry point from package.json
+ */
+function resolveEntryPoint(pkg, packageDir) {
+    // 1. Check exports field (modern)
+    if (pkg.exports) {
+        if (typeof pkg.exports === 'string') {
+            return pkg.exports;
+        }
+        else if (pkg.exports['.']) {
+            const dotExport = pkg.exports['.'];
+            if (typeof dotExport === 'string') {
+                return dotExport;
+            }
+            else if (dotExport.import) {
+                return dotExport.import;
+            }
+            else if (dotExport.default) {
+                return dotExport.default;
+            }
+        }
+    }
+    // 2. Check module field (ESM)
+    if (pkg.module) {
+        return pkg.module;
+    }
+    // 3. Fall back to main field
+    if (pkg.main) {
+        return pkg.main;
+    }
+    // 4. Default to index.js
+    return './index.js';
+}
+/**
+ * Recursively collect all dependencies, avoiding circular references
+ */
+function collectDependencies(packageJsonPath, visited, dependencies, htmlDir, currentPath = '') {
+    try {
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+        const packageDir = path.dirname(packageJsonPath);
+        const deps = packageJson.dependencies || {};
+        for (const [depName, depVersion] of Object.entries(deps)) {
+            // Skip if already processed (circular dependency protection)
+            if (visited.has(depName)) {
+                continue;
+            }
+            visited.add(depName);
+            // Resolve dependency path
+            const depPath = resolveDependencyPath(packageDir, depName, depVersion);
+            if (!depPath) {
+                console.warn(`[generate-importmap] Warning: Could not resolve ${depName}`);
+                continue;
+            }
+            const depPackageJsonPath = path.join(depPath, 'package.json');
+            if (!fs.existsSync(depPackageJsonPath)) {
+                console.warn(`[generate-importmap] Warning: No package.json found for ${depName} at ${depPath}`);
+                continue;
+            }
+            // Read dependency's package.json
+            const depPackageJson = JSON.parse(fs.readFileSync(depPackageJsonPath, 'utf-8'));
+            // Resolve entry point
+            const entryPoint = resolveEntryPoint(depPackageJson, depPath);
+            const cleanEntryPoint = entryPoint.startsWith('./') ? entryPoint.slice(2) : entryPoint;
+            // Build path relative to node_modules
+            let relativePath;
+            if (currentPath === '') {
+                // Top-level dependency - directly in node_modules
+                relativePath = `./node_modules/${depName}/${cleanEntryPoint}`;
+            }
+            else {
+                // Nested dependency - under parent's node_modules
+                relativePath = `./node_modules/${currentPath}/node_modules/${depName}/${cleanEntryPoint}`;
+            }
+            dependencies.set(depName, relativePath);
+            // Recursively process this dependency's dependencies
+            const nestedPath = currentPath === '' ? depName : `${currentPath}/node_modules/${depName}`;
+            collectDependencies(depPackageJsonPath, visited, dependencies, htmlDir, nestedPath);
+        }
+    }
+    catch (e) {
+        console.error(`[generate-importmap] Error processing ${packageJsonPath}:`, e.message);
+    }
+}
+function generateImportMap(packageJsonPath, htmlFilePath) {
+    try {
+        const htmlDir = path.dirname(htmlFilePath);
+        const visited = new Set();
+        const dependencies = new Map();
+        // Recursively collect all dependencies
+        collectDependencies(packageJsonPath, visited, dependencies, htmlDir);
+        // Convert Map to plain object for JSON
+        const imports = {};
+        for (const [name, importPath] of dependencies) {
+            imports[name] = importPath;
+        }
+        const now = new Date();
+        const timestamp = now.toLocaleString('en-US', {
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+            hour12: false
+        }).replace(',', '');
+        const importMapScript = `<!-- ⚠️⚠️⚠️ WARNING: DO NOT MANUALLY EDIT THE IMPORT MAP BELOW ⚠️⚠️⚠️ -->
+    <!-- This import map is AUTO-GENERATED by 'importgen' from package.json dependencies -->
+    <!-- To update: modify package.json dependencies, then run: npm run importmap -->
+    <!-- NEVER manually edit the import map entries - they will be overwritten -->
+    <!-- @ts-expect-error: importmap not supported in older browsers -->
+    <!-- Generated by @bobfrankston/importgen v${VERSION} on ${timestamp} -->
+    <script type="importmap">
+    ${JSON.stringify({ imports }, null, 12)}
+    </script>`;
+        // Read HTML file
+        let html = fs.readFileSync(htmlFilePath, 'utf-8');
+        // Replace import map section (including any preceding comments about importgen/warning)
+        const importMapRegex = /(?:<!--[^>]*?-->\s*)*<script type="importmap">[\s\S]*?<\/script>/;
+        if (importMapRegex.test(html)) {
+            html = html.replace(importMapRegex, importMapScript);
+        }
+        else {
+            // Auto-init: insert before </head> if no import map found
+            console.log(`[generate-importmap] Initializing import map in ${path.basename(htmlFilePath)}`);
+            html = html.replace('</head>', `    ${importMapScript}\n</head>`);
+        }
+        // Write back to HTML file
+        fs.writeFileSync(htmlFilePath, html, 'utf-8');
+        console.log(`[generate-importmap v${VERSION}] Updated ${path.basename(htmlFilePath)}`);
+        console.log(`  Scanned ${visited.size} dependencies, generated ${dependencies.size} entries`);
+        if (dependencies.size > 0) {
+            console.log('  Packages:', Array.from(dependencies.keys()).join(', '));
+        }
+    }
+    catch (e) {
+        console.error('[generate-importmap] Error:', e.message);
+        process.exit(1);
+    }
+}
+/**
+ * Find HTML file - checks for parameter, then searches for common defaults
+ */
+function findHtmlFile(specifiedFile) {
+    if (specifiedFile) {
+        const fullPath = path.isAbsolute(specifiedFile)
+            ? specifiedFile
+            : path.join(process.cwd(), specifiedFile);
+        if (fs.existsSync(fullPath)) {
+            return fullPath;
+        }
+        return null;
+    }
+    // Search for common HTML file names
+    const candidates = ['index.html', 'default.html', 'default.htm'];
+    for (const candidate of candidates) {
+        const candidatePath = path.join(process.cwd(), candidate);
+        if (fs.existsSync(candidatePath)) {
+            return candidatePath;
+        }
+    }
+    return null;
+}
+// Parse CLI arguments
+const args = process.argv.slice(2);
+const watchMode = args.includes('-w') || args.includes('--watch');
+// Find HTML file argument (non-flag argument that ends with .html or .htm)
+const htmlArg = args.find(arg => !arg.startsWith('-') && /\.html?$/i.test(arg));
+const packageJsonPath = path.join(process.cwd(), 'package.json');
+const htmlFilePath = findHtmlFile(htmlArg);
+// Check if files exist
+if (!fs.existsSync(packageJsonPath)) {
+    console.error('[generate-importmap] Error: package.json not found in current directory');
+    process.exit(1);
+}
+if (!htmlFilePath) {
+    const searchedFiles = htmlArg ? htmlArg : 'index.html, default.html, default.htm';
+    console.error(`[generate-importmap] Error: HTML file not found (searched: ${searchedFiles})`);
+    process.exit(1);
+}
+if (watchMode) {
+    generateImportMap(packageJsonPath, htmlFilePath);
+    console.log('[generate-importmap] Watching for changes...');
+    const watcher = chokidar.watch([packageJsonPath], {
+        persistent: true,
+        ignoreInitial: true
+    });
+    watcher.on('change', () => generateImportMap(packageJsonPath, htmlFilePath));
+    watcher.on('ready', () => {
+        console.log('[generate-importmap] Watcher is ready and running.');
+    });
+    watcher.on('error', (error) => {
+        console.error('[generate-importmap] Watcher error:', error.message);
+    });
+}
+else {
+    generateImportMap(packageJsonPath, htmlFilePath);
+}
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@bobfrankston/importgen",
+  "version": "0.1.10",
+  "description": "Generate ES Module import maps from package.json dependencies for native browser module loading",
+  "main": "index.js",
+  "bin": {
+    "importgen": "index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc -w",
+    "preversion": "npm run build",
+    "postversion": "echo Version updated to $(node -p \"require('./package.json').version\")",
+    "release": "git add -A && git diff-index --quiet HEAD || git commit -m 'Build for release' && npm version patch",
+    "installer": "npm run release && npm install -g ."
+  },
+  "keywords": [
+    "import-map",
+    "esm",
+    "browser",
+    "modules",
+    "dependencies"
+  ],
+  "author": "Bob Frankston",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BobFrankston/importgen.git"
+  },
+  "dependencies": {
+    "chokidar": "^4.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.9"
+  }
+}

package/tasks-prototype.json

@@ -0,0 +1,24 @@
+        {
+            "label": "importgen: watch",
+            "type": "shell",
+            "command": "importgen",
+            "args": ["--watch"],
+            "runOptions": {
+                "runOn": "folderOpen"
+            },
+            "isBackground": true,
+            "problemMatcher": {
+                "pattern": {
+                    "regexp": "^$",
+                    "file": 1,
+                    "location": 2,
+                    "message": 3
+                },
+                "background": {
+                    "activeOnStart": true,
+                    "beginsPattern": "^\\[generate-importmap\\].*watching.*$",
+                    "endsPattern": "^\\[generate-importmap\\].*Updated.*$"
+                }
+            }
+   
+     }