mz-dev 0.1.0-beta.0 → 0.1.0-beta.14

package/README.md

@@ -1,45 +1,57 @@
 # mz-dev
 
-Network debugging proxy + dashboard for Flutter / mobile development.
+A local-first developer workbench that runs your coding agents the way you
+would. It sees your app's traffic and runtime, knows your tickets and designs,
+and works to your standards.
 
 ```bash
-# One-shot
-npx mz-dev start
+# One-shot (prereleases are published under the `beta` dist-tag)
+npx mz-dev@beta start
 
 # Persistent install
-npm install -g mz-dev
+npm install -g mz-dev@beta
 mz start
 ```
 
+Pin an exact version (`mz-dev@0.1.0-beta.N`) when reporting issues.
+
 ## 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.
+- A local HTTP(S) proxy and traffic inspector, with intercept rules and a
+  mock server.
+- A web dashboard at `http://localhost:8889` for traffic, the API client,
+  environments, credentials and Vault, attached Flutter apps and the Jira
+  workspace.
+- An MCP server (`mz mcp`, or `http://127.0.0.1:8892/mcp` while `mz start`
+  runs) so coding agents can use the same tools.
 
 ## Supported platforms
 
-`darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`, `windows-x64`.
+macOS on Apple silicon (`darwin-arm64`). Node.js 18 or newer runs the `mz`
+launcher.
+
+Other platforms aren't published yet; on them `mz` says so and exits.
+
+## How the install works
 
-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>`.
+`mz-dev` is a small launcher. The binary, the dashboard and the Dart packages
+for your apps (`mz_client`) come in a separate package for your platform,
+`mz-dev-darwin-arm64`, which npm installs automatically as an optional
+dependency. Nothing is downloaded when the package installs, and there are no
+install scripts.
 
-## First-launch warnings
+If you install with optional dependencies turned off (`--omit=optional`),
+`mz` tells you to reinstall without that flag.
 
-- **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.
+`mz update --check` tells you when a newer version is published on your
+channel (set `MZ_NO_UPDATE_CHECK=1` to turn update checks off).
 
-## Source
+## First launch on macOS
 
-<https://github.com/koiralapankaj7/mz_dev>
+Beta binaries are not yet signed by Apple. Files that npm installs are not
+quarantined, so macOS normally runs `mz` without asking. If it ever reports
+that `mz` "cannot be opened", clear the quarantine flag:
+
+```bash
+xattr -d com.apple.quarantine "$(npm root -g)/mz-dev-darwin-arm64/bin/mz"
+```

package/bin/mz.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 /**
- * Thin shim that execs the platform-specific `mz` binary the
- * `postinstall` step downloaded.
+ * Thin shim that execs the `mz` binary from the platform package npm
+ * installed alongside (`mz-dev-darwin-arm64`, …; see scripts/resolve.js).
  *
  * 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.
+ * assets in that package (`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.
@@ -27,8 +27,7 @@ try {
 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.`,
+      'Reinstall the package: npm install -g mz-dev',
   );
   process.exit(1);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mz-dev",
-  "version": "0.1.0-beta.0",
-  "description": "Network debugging proxy + dashboard for Flutter / mobile development",
+  "version": "0.1.0-beta.14",
+  "description": "Local-first developer workbench that runs your coding agents the way you would",
   "keywords": [
     "flutter",
     "network",
@@ -12,14 +12,6 @@
     "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": {
@@ -28,18 +20,14 @@
   },
   "files": [
     "bin",
-    "scripts",
+    "scripts/resolve.js",
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "postinstall": "node scripts/install.js",
-    "preuninstall": "node scripts/uninstall.js"
+  "optionalDependencies": {
+    "mz-dev-darwin-arm64": "0.1.0-beta.14"
   },
   "engines": {
     "node": ">=18"
-  },
-  "dependencies": {
-    "tar": "^7.5.22"
   }
 }

package/scripts/resolve.js

@@ -1,36 +1,39 @@
 /**
- * Maps the running process to a {platform, binary, archive} triple.
+ * Finds the platform package that carries the `mz` binary.
  *
- * 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.
+ * `mz-dev` itself is a small launcher. Each supported platform's binary,
+ * dashboard and companion packages ship as their own npm package
+ * (`mz-dev-darwin-arm64`, …) listed in `optionalDependencies`; npm installs
+ * only the one whose `os`/`cpu` match the machine. Nothing is downloaded at
+ * install time.
  */
 'use strict';
 
+const fs = require('fs');
 const path = require('path');
 
+// Platforms with a published package. Adding one: build it with
+// `release/manual-release.sh npm`, publish it, and list it here and in
+// package.json `optionalDependencies`.
 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];
+function platformDir(platform = process.platform, arch = process.arch) {
+  const dir = PLATFORM_MAP[`${platform}:${arch}`];
   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.`,
+      `mz-dev has no prebuilt binary for ${platform}-${arch} yet. ` +
+        `Available: ${Object.values(PLATFORM_MAP).join(', ')}.`,
     );
   }
   return dir;
 }
 
+function platformPackageName(platform = platformDir()) {
+  return `mz-dev-${platform}`;
+}
+
 function binaryName() {
   return process.platform === 'win32' ? 'mz.exe' : 'mz';
 }
@@ -39,8 +42,23 @@ function packageRoot() {
   return path.resolve(__dirname, '..');
 }
 
+/**
+ * The installed platform package's directory. Resolved from this package so
+ * it works for global installs, `npx` and local `node_modules` alike.
+ */
 function platformRoot(platform = platformDir()) {
-  return path.join(packageRoot(), 'platform', platform);
+  const name = platformPackageName(platform);
+  try {
+    return path.dirname(
+      require.resolve(`${name}/package.json`, { paths: [packageRoot()] }),
+    );
+  } catch (_) {
+    throw new Error(
+      `mz-dev: ${name} is not installed. npm skips it when optional ` +
+        'dependencies are disabled (--omit=optional, --no-optional). ' +
+        `Reinstall with them enabled: npm install -g mz-dev`,
+    );
+  }
 }
 
 function binaryPath(platform = platformDir()) {
@@ -48,12 +66,15 @@ function binaryPath(platform = platformDir()) {
 }
 
 function uiDir(platform = platformDir()) {
-  return path.join(platformRoot(platform), 'ui', 'web');
+  const root = platformRoot(platform);
+  const web = path.join(root, 'ui', 'web');
+  return fs.existsSync(web) ? web : path.join(root, 'ui');
 }
 
 module.exports = {
   PLATFORM_MAP,
   platformDir,
+  platformPackageName,
   binaryName,
   packageRoot,
   platformRoot,

package/scripts/download.js

@@ -1,73 +0,0 @@
-'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

@@ -1,34 +0,0 @@
-'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

@@ -1,101 +0,0 @@
-#!/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

@@ -1,125 +0,0 @@
-'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/smoke.js

@@ -1,26 +0,0 @@
-#!/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

@@ -1,17 +0,0 @@
-#!/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 */
-}