mz-dev 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Pankaj Koirala
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# mz-dev
+
+Network debugging proxy + dashboard for Flutter / mobile development.
+
+```bash
+# One-shot
+npx mz-dev start
+
+# Persistent install
+npm install -g mz-dev
+mz start
+```
+
+## What you get
+
+- A local HTTP/HTTPS proxy that captures every request your app
+  makes.
+- A web dashboard at `http://localhost:8889` to inspect, replay,
+  mock, intercept, and AI-analyse traffic.
+- An MCP server so AI tools can drive the same workflows.
+
+## Supported platforms
+
+`darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `windows-x64`.
+
+The package itself is platform-agnostic. The `postinstall` step
+downloads the matching prebuilt binary + Flutter web bundle from
+the GitHub Release tagged `v<this package version>`.
+
+## First-launch warnings
+
+- **macOS**: The binary is unsigned (we don't yet pay for an Apple
+  Developer account). On first run macOS Gatekeeper will refuse to
+  open it. Workaround:
+  ```bash
+  xattr -d com.apple.quarantine "$(npm root -g)/mz-dev/platform/$(node -p "process.platform + '-' + process.arch")/bin/mz"
+  ```
+  Or right-click the binary in Finder → Open.
+- **Windows**: SmartScreen will prompt "Windows protected your PC"
+  on first launch. Click *More info* → *Run anyway*.
+- **Linux**: nothing to do.
+
+## Source
+
+<https://github.com/koiralapankaj7/mz_dev>

package/bin/mz.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * Thin shim that execs the platform-specific `mz` binary the
+ * `postinstall` step downloaded.
+ *
+ * Sets `MZ_DEV_UI_DIR` so the binary finds the bundled Flutter web
+ * assets next to itself (`<package>/platform/<arch>/ui/web/`)
+ * regardless of the user's current working directory.
+ *
+ * Forwards stdio + signals so the binary feels native: Ctrl+C, pipes,
+ * exit codes all behave as if the user invoked the binary directly.
+ */
+'use strict';
+
+const fs = require('fs');
+const { spawn } = require('child_process');
+const { binaryPath, uiDir, platformDir } = require('../scripts/resolve');
+
+let resolvedBinary;
+try {
+  resolvedBinary = binaryPath();
+} catch (e) {
+  console.error(e.message);
+  process.exit(1);
+}
+
+if (!fs.existsSync(resolvedBinary)) {
+  console.error(
+    `mz-dev: binary missing at ${resolvedBinary}. ` +
+      `The postinstall step may have failed — try ` +
+      `\`npm rebuild mz-dev\` or reinstall the package.`,
+  );
+  process.exit(1);
+}
+
+const env = { ...process.env };
+const ui = uiDir();
+if (fs.existsSync(ui)) {
+  env.MZ_DEV_UI_DIR = ui;
+}
+
+const child = spawn(resolvedBinary, process.argv.slice(2), {
+  stdio: 'inherit',
+  env,
+  windowsHide: false,
+});
+
+// Forward common termination signals so a Ctrl+C in the user's
+// terminal stops the underlying binary (otherwise it hangs as
+// an orphan).
+const SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT'];
+const signalHandlers = new Map();
+for (const sig of SIGNALS) {
+  const handler = () => {
+    if (!child.killed) child.kill(sig);
+  };
+  signalHandlers.set(sig, handler);
+  process.on(sig, handler);
+}
+
+function removeSignalHandlers() {
+  for (const [signal, handler] of signalHandlers) {
+    process.removeListener(signal, handler);
+  }
+}
+
+child.on('error', (err) => {
+  removeSignalHandlers();
+  console.error(`mz-dev (${platformDir()}): failed to launch binary: ${err.message}`);
+  process.exit(1);
+});
+
+child.on('exit', (code, signal) => {
+  // Restore default signal handling before re-raising; otherwise our own
+  // forwarding listener consumes the signal and may incorrectly exit with 0.
+  removeSignalHandlers();
+  if (signal) {
+    // Re-raise the signal in our own process so callers (shells,
+    // CI runners) see the same exit reason as the child.
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code ?? 0);
+  }
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "mz-dev",
+  "version": "0.1.0-beta.0",
+  "description": "Network debugging proxy + dashboard for Flutter / mobile development",
+  "keywords": [
+    "flutter",
+    "network",
+    "proxy",
+    "debugging",
+    "devtools",
+    "mock-server",
+    "intercept",
+    "cli"
+  ],
+  "homepage": "https://github.com/koiralapankaj7/mz_dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/koiralapankaj7/mz_dev.git"
+  },
+  "bugs": {
+    "url": "https://github.com/koiralapankaj7/mz_dev/issues"
+  },
+  "license": "MIT",
+  "author": "Pankaj Koirala",
+  "bin": {
+    "mz": "bin/mz.js",
+    "mz-dev": "bin/mz.js"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/install.js",
+    "preuninstall": "node scripts/uninstall.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "tar": "^7.5.22"
+  }
+}

package/scripts/download.js

@@ -0,0 +1,73 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { Readable, Transform } = require('node:stream');
+const { pipeline } = require('node:stream/promises');
+
+function expectedChecksum(manifest, archive) {
+  const matches = [];
+  for (const line of manifest.split('\n')) {
+    const match = /^([a-fA-F0-9]{64}) [ *](.+)$/.exec(line.replace(/\r$/, ''));
+    if (match && match[2].split('/').pop() === archive) matches.push(match[1].toLowerCase());
+  }
+  if (matches.length !== 1) throw new Error('Expected exactly one archive checksum in SHA256SUMS.txt');
+  return matches[0];
+}
+
+async function downloadFile(url, destination, {
+  maxBytes = 512 * 1024 * 1024, timeoutMs = 120000, fetchImpl = fetch,
+} = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let response;
+  try {
+    for (let redirects = 0; ; redirects++) {
+      const parsed = new URL(url);
+      if (parsed.protocol !== 'https:' || parsed.username || parsed.password) {
+        throw new Error('Installer downloads require HTTPS without URL credentials');
+      }
+      response = await fetchImpl(parsed.href, {
+        redirect: 'manual', signal: controller.signal,
+        headers: { 'User-Agent': 'mz-dev-installer' },
+      });
+      if (![301, 302, 303, 307, 308].includes(response.status)) break;
+      await response.body?.cancel();
+      const location = response.headers.get('location');
+      if (!location || redirects >= 5) throw new Error('Invalid or excessive download redirects');
+      url = new URL(location, parsed).href;
+    }
+    if (response.status !== 200 || !response.body) throw new Error(`Download HTTP ${response.status}`);
+    const hash = crypto.createHash('sha256');
+    let bytes = 0;
+    const meter = new Transform({
+      transform(chunk, encoding, callback) {
+        bytes += chunk.length;
+        if (bytes > maxBytes) return callback(new Error('Download exceeds size limit'));
+        hash.update(chunk);
+        callback(null, chunk);
+      },
+    });
+    await pipeline(Readable.fromWeb(response.body), meter,
+      fs.createWriteStream(destination, { flags: 'wx', mode: 0o600 }),
+      { signal: controller.signal });
+    return hash.digest('hex');
+  } finally {
+    controller.abort();
+    clearTimeout(timer);
+  }
+}
+
+async function verifiedArchive(baseUrl, archive, directory, options = {}) {
+  if (!/^mz-dev-[a-z0-9-]+\.tar\.gz$/.test(archive)) throw new Error('Invalid archive name');
+  const manifestPath = path.join(directory, 'SHA256SUMS.txt');
+  await downloadFile(`${baseUrl}/SHA256SUMS.txt`, manifestPath,
+    { ...options, maxBytes: 1024 * 1024 });
+  const expected = expectedChecksum(await fs.promises.readFile(manifestPath, 'utf8'), archive);
+  const archivePath = path.join(directory, archive);
+  const actual = await downloadFile(`${baseUrl}/${archive}`, archivePath, options);
+  if (actual !== expected) throw new Error('Archive SHA-256 checksum mismatch');
+  return archivePath;
+}
+
+module.exports = { expectedChecksum, downloadFile, verifiedArchive };

package/scripts/extract.js

@@ -0,0 +1,34 @@
+'use strict';
+const tar = require('tar');
+
+function entryFilter(root, { maxEntries = 20000, maxBytes = 1024 * 1024 * 1024 } = {}) {
+  let count = 0;
+  let bytes = 0;
+  const seen = new Set();
+  return function (name, entry) {
+    const clean = name.replace(/\/$/, '');
+    const parts = clean.split('/');
+    const key = clean.toLowerCase();
+    count++;
+    bytes += entry.size;
+    if (parts[0] !== root || parts.some(part => !part || part === '.' || part === '..') ||
+        /[\\:\x00-\x1f]/.test(name) || !['File', 'Directory'].includes(entry.type) ||
+        seen.has(key) || !Number.isSafeInteger(entry.size) || entry.size < 0 ||
+        count > maxEntries || bytes > maxBytes) {
+      this.abort(new Error('Unsafe or oversized release archive entry'));
+      return false;
+    }
+    seen.add(key);
+    return true;
+  };
+}
+
+async function extractArchive(file, directory, root, limits = {}) {
+  // Preflight the complete archive before creating any extracted files.
+  await tar.t({ file, strict: true, maxDecompressionRatio: 1000,
+    filter: entryFilter(root, limits) });
+  await tar.x({ file, cwd: directory, strip: 1, strict: true,
+    preserveOwner: false, maxDecompressionRatio: 1000,
+    filter: entryFilter(root, limits) });
+}
+module.exports = { extractArchive };

package/scripts/install.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * Postinstall: downloads the platform-specific mz_dev binary +
+ * Flutter UI bundle from the matching GitHub Release and unpacks it
+ * into `<package>/platform/<arch>/`.
+ *
+ * Why a downloader instead of bundling every platform's binary in
+ * the npm package: keeps the published tarball tiny (~5 KB instead
+ * of ~80 MB) and avoids tagging the npm registry with binaries it
+ * shouldn't be hosting.
+ *
+ * Re-running install skips download only for a marked, complete bundle.
+ *
+ * Failure is non-fatal: we print a clear "download manually from X"
+ * pointer and exit 0 so `npm install` itself doesn't break for
+ * users who'll fetch the binary another way (offline, corporate
+ * proxy, etc.).
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { verifiedArchive } = require('./download');
+const { isCompleteInstall, installBundle } = require('./installation');
+
+const { extractArchive } = require('./extract');
+
+const {
+  binaryPath,
+  binaryName,
+  platformDir,
+  platformRoot,
+} = require('./resolve');
+const pkg = require('../package.json');
+
+const REPO = 'koiralapankaj7/mz_dev';
+
+function logFailure(reason, downloadUrl) {
+  console.error(`\nmz-dev: postinstall failed — ${reason}`);
+  if (downloadUrl) {
+    console.error(
+      `mz-dev: you can fetch the binary manually:\n  ${downloadUrl}\n` +
+        `        and unpack it under:\n  ${platformRoot()}\n`,
+    );
+  }
+  // Keep `npm install` green; the shim prints a friendlier error
+  // when the user actually tries to run `mz`.
+  process.exitCode = 0;
+}
+
+let platform;
+try {
+  platform = platformDir();
+} catch (e) {
+  // Unsupported platform → nothing to install. Exit 0 so installing
+  // mz-dev as a transitive dep on an exotic CI doesn't blow up.
+  console.warn(`mz-dev: ${e.message}`);
+  process.exit(0);
+}
+
+const archive = `mz-dev-${platform}.tar.gz`;
+const url = `https://github.com/${REPO}/releases/download/v${pkg.version}/${archive}`;
+const targetDir = platformRoot(platform);
+const finalBinary = binaryPath(platform);
+
+if (isCompleteInstall(targetDir, binaryName(), pkg.version)) {
+  // Already provisioned (npm cache hit, manual download, etc.).
+  // Make sure the perm bit is right just in case.
+  if (process.platform !== 'win32') fs.chmodSync(finalBinary, 0o755);
+  process.exit(0);
+}
+
+(async () => {
+  console.log(`mz-dev: downloading ${archive} (v${pkg.version})`);
+  let temporary;
+  try {
+    temporary = fs.mkdtempSync(path.join(os.tmpdir(), 'mz-download-'));
+    const verified = await verifiedArchive(url.slice(0, url.lastIndexOf('/')), archive, temporary);
+    const backup = await installBundle({
+      target: targetDir, binary: binaryName(), version: pkg.version,
+      extract: directory => extractArchive(verified, directory, `mz-dev-${platform}`),
+    });
+    if (backup) console.log(`mz-dev: previous installation retained at ${backup}`);
+  } catch (err) {
+    logFailure(`download/verification/extraction failed (${err.message})`, url);
+    return;
+  } finally {
+    if (temporary) fs.rmSync(temporary, { recursive: true, force: true });
+  }
+
+  if (!fs.existsSync(finalBinary)) {
+    logFailure(
+      `archive did not contain bin/${binaryName()} for ${platform}`,
+      url,
+    );
+    return;
+  }
+  if (process.platform !== 'win32') fs.chmodSync(finalBinary, 0o755);
+  console.log(`mz-dev: installed ${platform} binary`);
+})();

package/scripts/installation.js

@@ -0,0 +1,125 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+
+function digestFile(filename) {
+  const descriptor = fs.openSync(filename, 'r');
+  try {
+    const hash = createHash('sha256');
+    const buffer = Buffer.allocUnsafe(64 * 1024);
+    let length;
+    while ((length = fs.readSync(descriptor, buffer, 0, buffer.length, null)) > 0) {
+      hash.update(buffer.subarray(0, length));
+    }
+    return hash.digest('hex');
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+
+function requiredAssets(binary) {
+  return [`bin/${binary}`, ...(process.platform === 'win32' ? [] : ['bin/mz-check-supervisor']),
+    'ui/web/index.html', 'ui/web/main.dart.js',
+    'packages/mz_client/pubspec.yaml', 'packages/mz_client/lib/mz_client.dart',
+    'packages/mz_protocol/pubspec.yaml', 'packages/mz_protocol/lib/mz_protocol.dart'];
+}
+
+function requiredInventory(directory, binary) {
+  return requiredAssets(binary).map(relative => [relative,
+    digestFile(path.join(directory, relative))]);
+}
+
+// Inventory is derived from regular files, never paths supplied by the marker.
+// This detects accidental damage; it does not authenticate against a local
+// attacker who can rewrite both the libraries and installation marker.
+function nativeInventory(directory) {
+  const root = path.join(directory, 'lib');
+  if (!fs.existsSync(root)) return [];
+  const result = [];
+  function visit(relative) {
+    const absolute = path.join(root, relative);
+    const stat = fs.lstatSync(absolute);
+    if (stat.isDirectory()) {
+      for (const name of fs.readdirSync(absolute).sort()) {
+        visit(relative ? `${relative}/${name}` : name);
+      }
+    } else if (stat.isFile() && stat.size > 0) {
+      result.push([relative, digestFile(absolute)]);
+    } else throw new Error('Invalid native library asset');
+  }
+  visit('');
+  return result;
+}
+
+function validateBundle(directory, binary) {
+  function inspect(entry) {
+    const stat = fs.lstatSync(entry);
+    if (stat.isDirectory()) {
+      for (const child of fs.readdirSync(entry)) inspect(path.join(entry, child));
+    } else if (!stat.isFile()) throw new Error('Bundle contains a non-regular entry');
+  }
+  inspect(directory);
+  for (const relative of requiredAssets(binary)) {
+    const stat = fs.lstatSync(path.join(directory, relative));
+    if (!stat.isFile() || stat.size === 0) throw new Error(`Missing bundle asset: ${relative}`);
+  }
+  if (process.platform !== 'win32') {
+    fs.accessSync(path.join(directory, 'bin/mz-check-supervisor'), fs.constants.X_OK);
+  }
+}
+
+function isCompleteInstall(directory, binary, version) {
+  try {
+    const marker = JSON.parse(fs.readFileSync(path.join(directory, '.mz-install.json'), 'utf8'));
+    if (marker.version !== version || marker.format !== 2) return false;
+    validateBundle(directory, binary);
+    if (process.platform !== 'win32') {
+      fs.accessSync(path.join(directory, 'bin', binary), fs.constants.X_OK);
+    }
+    return JSON.stringify(marker.nativeAssets) === JSON.stringify(nativeInventory(directory)) &&
+      JSON.stringify(marker.requiredAssets) === JSON.stringify(requiredInventory(directory, binary));
+  } catch (_) { return false; }
+}
+
+async function installBundle({ target, binary, version, extract, rename = fs.renameSync }) {
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const lock = `${target}.install-lock`;
+  fs.mkdirSync(lock); // Refuse a concurrent or interrupted installation.
+  let transaction;
+  try {
+    if (fs.existsSync(target) && !fs.lstatSync(target).isDirectory()) {
+      throw new Error('Installation target must be a regular directory');
+    }
+    transaction = fs.mkdtempSync(path.join(path.dirname(target), '.mz-install-'));
+    const staged = path.join(transaction, 'new');
+    const previous = path.join(transaction, 'previous');
+    fs.mkdirSync(staged);
+    await extract(staged);
+    validateBundle(staged, binary);
+    if (process.platform !== 'win32') fs.chmodSync(path.join(staged, 'bin', binary), 0o755);
+    fs.writeFileSync(path.join(staged, '.mz-install.json'), JSON.stringify({
+      format: 2, version, nativeAssets: nativeInventory(staged),
+      requiredAssets: requiredInventory(staged, binary),
+    }));
+    const hadPrevious = fs.existsSync(target);
+    if (hadPrevious) rename(target, previous);
+    try {
+      rename(staged, target);
+    } catch (error) {
+      if (hadPrevious) {
+        try { rename(previous, target); }
+        catch (_) { throw new Error(`Installation failed; previous files retained at ${previous}`); }
+      }
+      throw error;
+    }
+    // Retain previous files rather than destroying a manual install or recovery data.
+    return hadPrevious ? previous : null;
+  } finally {
+    if (transaction && !fs.existsSync(path.join(transaction, 'previous'))) {
+      fs.rmSync(transaction, { recursive: true, force: true });
+    }
+    fs.rmdirSync(lock);
+  }
+}
+module.exports = { validateBundle, isCompleteInstall, installBundle };

package/scripts/resolve.js

@@ -0,0 +1,62 @@
+/**
+ * Maps the running process to a {platform, binary, archive} triple.
+ *
+ * Single source of truth for "which binary do we run / download".
+ * Used by both `bin/mz.js` (to exec) and `scripts/install.js` (to
+ * download). Keeping the map here means adding a new platform is a
+ * one-line edit.
+ */
+'use strict';
+
+const path = require('path');
+
+const PLATFORM_MAP = {
+  'darwin:arm64': 'darwin-arm64',
+  'darwin:x64': 'darwin-x64',
+  'linux:x64': 'linux-x64',
+  'linux:arm64': 'linux-arm64',
+  'win32:x64': 'windows-x64',
+};
+
+function platformDir() {
+  const key = `${process.platform}:${process.arch}`;
+  const dir = PLATFORM_MAP[key];
+  if (!dir) {
+    throw new Error(
+      `mz-dev does not have a prebuilt binary for ${key}. ` +
+        `Supported: ${Object.keys(PLATFORM_MAP).join(', ')}. ` +
+        `File an issue at https://github.com/koiralapankaj7/mz_dev/issues.`,
+    );
+  }
+  return dir;
+}
+
+function binaryName() {
+  return process.platform === 'win32' ? 'mz.exe' : 'mz';
+}
+
+function packageRoot() {
+  return path.resolve(__dirname, '..');
+}
+
+function platformRoot(platform = platformDir()) {
+  return path.join(packageRoot(), 'platform', platform);
+}
+
+function binaryPath(platform = platformDir()) {
+  return path.join(platformRoot(platform), 'bin', binaryName());
+}
+
+function uiDir(platform = platformDir()) {
+  return path.join(platformRoot(platform), 'ui', 'web');
+}
+
+module.exports = {
+  PLATFORM_MAP,
+  platformDir,
+  binaryName,
+  packageRoot,
+  platformRoot,
+  binaryPath,
+  uiDir,
+};

package/scripts/smoke.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * Sanity-check the resolver without invoking the binary.
+ *
+ *   node release/npm/scripts/smoke.js
+ *
+ * Prints the platform/binary/UI paths the shim would use on this
+ * machine. Useful when adding a new platform to verify the
+ * `PLATFORM_MAP` entry resolves correctly before tagging a
+ * release.
+ */
+'use strict';
+
+const {
+  platformDir,
+  binaryName,
+  binaryPath,
+  uiDir,
+} = require('./resolve');
+
+console.log(JSON.stringify({
+  platform: platformDir(),
+  binaryName: binaryName(),
+  binaryPath: binaryPath(),
+  uiDir: uiDir(),
+}, null, 2));

package/scripts/uninstall.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * Best-effort cleanup of the downloaded `platform/` tree on
+ * `npm uninstall`. Quiet — failure here is harmless because the
+ * whole package directory is about to be removed anyway.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const platformRoot = path.join(__dirname, '..', 'platform');
+try {
+  fs.rmSync(platformRoot, { recursive: true, force: true });
+} catch (_) {
+  /* ignore */
+}