feat: run CLI commands in a browser

.gitignore

@@ -6,3 +6,4 @@ coverage/
 .DS_Store
 
 .release/
+dist-browser/

eslint.config.js

@@ -8,6 +8,7 @@ export default tseslint.config(
       '.release/**',
       'coverage/**',
       'dist/**',
+      'dist-browser/**',
       'node_modules/**',
     ],
   },

package.json

@@ -20,6 +20,7 @@
   "scripts": {
     "audit:prod": "npm audit --omit=dev",
     "build": "npm run clean && tsc -p tsconfig.build.json",
+    "build:browser": "node scripts/gen-browser-registry.mjs && node scripts/build-browser.mjs",
     "clean": "node scripts/clean-dist.js",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
@@ -35,12 +36,13 @@
     "@oclif/core": "^4.13.5",
     "@polymorfa/sdk": "0.1.0-dev.20261004024706",
     "jq-wasm": "3.0.0-jq-1.8.2",
-    "zod": "4.2.0"
+    "zod": "4.6.7"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.5",
     "@oclif/test": "^4.1.22",
     "@types/node": "^24.0.0",
+    "esbuild": "^0.28.2",
     "eslint": "^9.39.5",
     "prettier": "^3.9.6",
     "tsx": "^4.20.6",

scripts/build-browser.mjs

@@ -0,0 +1,105 @@
+// Builds dist-browser/: the CLI's commands as a browser module (src/browser/index.ts).
+// Node built-ins and local-only packages resolve to src/browser/stubs; each command loads on demand.
+import console from 'node:console'
+import process from 'node:process'
+import {URL} from 'node:url'
+import {execFileSync} from 'node:child_process'
+import {readFileSync, writeFileSync, rmSync} from 'node:fs'
+import {builtinModules} from 'node:module'
+import {build} from 'esbuild'
+
+const pkg = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+)
+const stub = (name) =>
+  new URL(`../src/browser/stubs/${name}.ts`, import.meta.url).pathname
+const NODE = {
+  fs: stub('fs'),
+  'fs/promises': stub('fs-promises'),
+  path: stub('path'),
+  'path/posix': stub('path'),
+  os: stub('os'),
+  crypto: stub('crypto'),
+  events: stub('events'),
+  buffer: stub('buffer'),
+  child_process: stub('unavailable'),
+  net: stub('unavailable'),
+  dns: stub('unavailable'),
+  'dns/promises': stub('unavailable'),
+  http: stub('unavailable'),
+  https: stub('unavailable'),
+  readline: stub('unavailable'),
+  'readline/promises': stub('unavailable'),
+}
+const PACKAGES = new Set([
+  '@napi-rs/keyring',
+  '@modelcontextprotocol/server',
+  '@modelcontextprotocol/server/stdio',
+  'jq-wasm',
+  '@polymorfa/sdk/node',
+])
+const escape = (value) => value.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')
+const builtins = new RegExp(`^(${builtinModules.map(escape).join('|')})$`)
+
+const stubs = {
+  name: 'browser-stubs',
+  setup(builder) {
+    builder.onResolve({filter: /^node:/}, (args) => ({
+      path: NODE[args.path.slice(5)] ?? stub('misc'),
+    }))
+    builder.onResolve({filter: builtins}, (args) => ({
+      path: NODE[args.path] ?? stub('misc'),
+    }))
+    builder.onResolve(
+      {
+        filter:
+          /^(@napi-rs\/keyring|@modelcontextprotocol\/server(\/stdio)?|jq-wasm|@polymorfa\/sdk\/node)$/,
+      },
+      (args) =>
+        PACKAGES.has(args.path) ? {path: stub('packages')} : undefined,
+    )
+  },
+}
+
+const commit = execFileSync('git', ['rev-parse', 'HEAD'], {
+  encoding: 'utf8',
+}).trim()
+rmSync(new URL('../dist-browser', import.meta.url), {
+  recursive: true,
+  force: true,
+})
+const result = await build({
+  entryPoints: ['src/browser/index.ts'],
+  bundle: true,
+  splitting: true,
+  format: 'esm',
+  platform: 'browser',
+  target: 'es2022',
+  outdir: 'dist-browser',
+  entryNames: 'polymorfa-cli',
+  chunkNames: 'chunks/[name]-[hash]',
+  inject: [stub('process'), stub('buffer-global')],
+  define: {
+    __CLI_VERSION__: JSON.stringify(pkg.version),
+    __CLI_COMMIT__: JSON.stringify(commit),
+    global: 'globalThis',
+  },
+  plugins: [stubs],
+  mainFields: ['browser', 'module', 'main'],
+  conditions: ['browser', 'import', 'default'],
+  minify: process.env.BROWSER_MINIFY !== '0',
+  legalComments: 'linked',
+  metafile: true,
+  logLevel: 'warning',
+})
+const bytes = Object.values(result.metafile.outputs).reduce(
+  (sum, output) => sum + output.bytes,
+  0,
+)
+writeFileSync(
+  new URL('../dist-browser/manifest.json', import.meta.url),
+  `${JSON.stringify({package: pkg.name, version: pkg.version, commit, entry: 'polymorfa-cli.js', files: Object.keys(result.metafile.outputs).length, bytes}, null, 2)}\n`,
+)
+console.log(
+  `dist-browser: ${Object.keys(result.metafile.outputs).length} files, ${(bytes / 1024 / 1024).toFixed(2)} MiB, commit ${commit.slice(0, 10)}`,
+)

scripts/gen-browser-registry.mjs

@@ -0,0 +1,41 @@
+// Writes src/browser/registry.gen.ts: every command id mapped to a lazy import of its module.
+// A command's id is its path under src/commands, with directories joined by spaces.
+import console from 'node:console'
+import {URL} from 'node:url'
+import {readdirSync, statSync, writeFileSync} from 'node:fs'
+import {join, relative} from 'node:path'
+import {format, resolveConfig} from 'prettier'
+
+const root = new URL('../src/commands/', import.meta.url).pathname
+const files = []
+const walk = (dir) => {
+  for (const name of readdirSync(dir).sort()) {
+    const path = join(dir, name)
+    if (statSync(path).isDirectory()) walk(path)
+    else if (
+      name.endsWith('.ts') &&
+      !name.endsWith('.test.ts') &&
+      !name.endsWith('.d.ts')
+    )
+      files.push(path)
+  }
+}
+walk(root)
+const entries = files.map((file) => {
+  const rel = relative(root, file).replace(/\.ts$/, '')
+  const id = rel.split('/').join(' ')
+  return `  ${JSON.stringify(id)}: () => import('../commands/${rel}.js'),`
+})
+const out = `// Generated by scripts/gen-browser-registry.mjs. Do not edit.
+export const COMMAND_LOADERS: Readonly<Record<string, () => Promise<{default: unknown}>>> = {
+${entries.join('\n')}
+}
+`
+const target = new URL('../src/browser/registry.gen.ts', import.meta.url)
+// Formatted like the rest of the source, so the format check passes.
+const options = (await resolveConfig(target.pathname)) ?? {}
+writeFileSync(
+  target,
+  await format(out, {...options, filepath: target.pathname}),
+)
+console.log(`registry: ${files.length} commands`)