@1agh/maude 0.17.1 → 0.17.2

package/cli/commands/design.mjs

@@ -1,6 +1,7 @@
-import { spawn } from 'node:child_process';
+import { execSync, spawn } from 'node:child_process';
 import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
-import { basename, join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { basename, dirname, join, resolve } from 'node:path';
 import { parseArgs } from '../lib/argv.mjs';
 
 const SUBCOMMANDS = new Set(['serve', 'init', 'export', 'help']);
@@ -60,23 +61,42 @@ function usage() {
 
 async function runServe({ args, pkgRoot }) {
   const forwarded = args.slice(args.indexOf('serve') + 1);
+  const fs = await import('node:fs');
 
   // Resolution order:
-  //   1. Side-channel from postinstall (cli/.platform-binary-path) — direct
-  //      native exec, zero Node startup tax. DDR-015.
-  //   2. Bun + server.ts (local dev or postinstall-skipped install).
-  //   3. Legacy server.mjs on Node — last-resort fallback for boxes without
-  //      bun. Should only fire mid-migration; removed in v1.0.
+  //   1. Side-channel cache from postinstall (cli/.platform-binary-path).
+  //   2. Lazy resolve of @1agh/maude-<slug>/maude (postinstall was skipped
+  //      — Bun global, --ignore-scripts, Docker layer without scripts, etc.).
+  //   3. (only in local dev tree) Bun + server.ts from source.
+  //   4. Hard-fail with actionable hint.
+  // Maintainers hacking on the dev-server source can force #3 with
+  // MAUDE_FORCE_SOURCE=1.
+  const forceSource = process.env.MAUDE_FORCE_SOURCE === '1';
   const sideChannel = resolve(pkgRoot, 'cli', '.platform-binary-path');
   let binPath = null;
-  try {
-    const { readFileSync, existsSync } = await import('node:fs');
-    if (existsSync(sideChannel)) {
-      const candidate = readFileSync(sideChannel, 'utf8').trim();
-      if (candidate && existsSync(candidate)) binPath = candidate;
+
+  if (!forceSource) {
+    try {
+      if (fs.existsSync(sideChannel)) {
+        const candidate = fs.readFileSync(sideChannel, 'utf8').trim();
+        if (candidate && fs.existsSync(candidate)) binPath = candidate;
+      }
+    } catch {
+      /* fall through to lazy resolve */
+    }
+
+    if (!binPath) {
+      const resolved = lazyResolveBinary({ pkgRoot, fs });
+      if (resolved.binPath) {
+        binPath = resolved.binPath;
+        // Cache for next invocation (best-effort — read-only fs is fine).
+        try {
+          fs.writeFileSync(sideChannel, binPath, 'utf8');
+        } catch {
+          /* read-only fs / no permission — non-fatal */
+        }
+      }
     }
-  } catch {
-    /* fall through */
   }
 
   if (binPath) {
@@ -89,6 +109,30 @@ async function runServe({ args, pkgRoot }) {
     return;
   }
 
+  // No binary found. Two possibilities:
+  //   - Production install missing platform package — hard-fail with guidance.
+  //   - Local dev tree (claude-design checkout) — fall through to source.
+  const inDevTree = isLocalDevTree(pkgRoot, fs);
+
+  if (!inDevTree && !forceSource) {
+    const slug = detectPlatformSlug();
+    const siblingHint = slug ? resolve(pkgRoot, '..', `maude-${slug}`) : '(unknown platform)';
+    process.stderr.write(
+      `maude design serve: platform binary not found.\n\n  Expected:  @1agh/maude-${slug || '<platform>'}/maude\n  Looked in: ${siblingHint}\n\nLikely causes:\n  • Installer skipped postinstall (Bun global, npm --ignore-scripts,\n    pnpm strict-scripts, Docker layer rebuilds).\n  • Optional dependency for your platform did not install.\n  • Global 'maude' is a leftover 'npm link' to a source checkout.\n\nFix (clean reinstall):\n  cd ~                          # NOT inside a maude source repo\n  npm uninstall -g @1agh/maude  # remove any stale link\n  npm i -g @1agh/maude          # real tarball install + postinstall\n\nOr re-run postinstall on the existing install:\n  npm rebuild -g @1agh/maude\n\nPlatform: ${process.platform}-${process.arch}\n`
+    );
+    process.exit(1);
+  }
+
+  // Local dev tree (or forced source). Verify deps before invoking source —
+  // catches the npm/pnpm/oxc-parser native-binding bug (npm#4828) up front.
+  const missing = checkDevDeps({ pkgRoot });
+  if (missing.length) {
+    process.stderr.write(
+      `maude design serve: missing dev-server dependencies in local checkout.\n\n  Missing: ${missing.join(', ')}\n  Repo:    ${pkgRoot}\n\nThis repo uses pnpm (see packageManager in package.json). Install deps:\n  cd ${pkgRoot} && pnpm install\n\nIf you already ran 'npm install' here, the npm optional-deps bug\n(npm#4828) may have left native bindings broken. Reset first:\n  rm -rf node_modules package-lock.json && pnpm install\n`
+    );
+    process.exit(1);
+  }
+
   const tsEntry = resolve(pkgRoot, 'plugins', 'design', 'dev-server', 'server.ts');
   const mjsEntry = resolve(pkgRoot, 'plugins', 'design', 'dev-server', 'server.mjs');
 
@@ -108,6 +152,104 @@ async function runServe({ args, pkgRoot }) {
   });
 }
 
+// Mirrors cli/install.cjs:detectSlug — kept in sync intentionally. Both forms
+// run during the lifecycle of a single install (postinstall + first serve).
+function detectPlatformSlug() {
+  const p = process.platform;
+  const a = process.arch;
+  if (p === 'darwin') {
+    if (a === 'arm64') return 'darwin-arm64';
+    try {
+      const t = execSync('sysctl -n sysctl.proc_translated', {
+        stdio: ['ignore', 'pipe', 'ignore'],
+      })
+        .toString()
+        .trim();
+      if (t === '1') return 'darwin-arm64';
+    } catch {
+      /* not under Rosetta */
+    }
+    return 'darwin-x64';
+  }
+  if (p === 'linux') {
+    let isMusl = false;
+    try {
+      const report = process.report?.getReport?.();
+      isMusl = !report?.header?.glibcVersionRuntime;
+    } catch {
+      /* default to glibc */
+    }
+    if (a === 'arm64') return isMusl ? 'linux-arm64-musl' : 'linux-arm64';
+    return isMusl ? 'linux-x64-musl' : 'linux-x64';
+  }
+  if (p === 'win32') return 'win32-x64';
+  return null;
+}
+
+function lazyResolveBinary({ pkgRoot, fs }) {
+  const slug = detectPlatformSlug();
+  if (!slug) return { binPath: null, slug: null };
+  const filename = process.platform === 'win32' ? 'maude.exe' : 'maude';
+
+  // Flat layout — production npm/bun global install. pkgRoot is
+  // <node_modules>/@1agh/maude, sibling is <node_modules>/@1agh/maude-<slug>.
+  const sibling = resolve(pkgRoot, '..', `maude-${slug}`, filename);
+  if (fs.existsSync(sibling)) {
+    try {
+      fs.chmodSync(sibling, 0o755);
+    } catch {
+      /* read-only — ignore */
+    }
+    return { binPath: sibling, slug };
+  }
+
+  // Nested layout — pnpm with isolation, or dev tree's own node_modules.
+  try {
+    const require = createRequire(import.meta.url);
+    const manifest = require.resolve(`@1agh/maude-${slug}/package.json`, {
+      paths: [pkgRoot, resolve(pkgRoot, 'cli')],
+    });
+    const fromManifest = resolve(dirname(manifest), filename);
+    if (fs.existsSync(fromManifest)) {
+      try {
+        fs.chmodSync(fromManifest, 0o755);
+      } catch {
+        /* ignore */
+      }
+      return { binPath: fromManifest, slug };
+    }
+  } catch {
+    /* platform package not installed */
+  }
+
+  return { binPath: null, slug };
+}
+
+// Mirrors cli/install.cjs:isLocalDev — the `packages/` directory is only present
+// in the source checkout, never in a published npm tarball (excluded from
+// package.json:files).
+function isLocalDevTree(pkgRoot, fs) {
+  return fs.existsSync(resolve(pkgRoot, 'packages', 'maude-darwin-arm64', 'package.json'));
+}
+
+function checkDevDeps({ pkgRoot }) {
+  const require = createRequire(import.meta.url);
+  // The dev-server source path imports these as bare specifiers. If they
+  // resolve, bun/node will load them; if they don't, the spawn will fail
+  // with a less actionable error.
+  const required = ['magic-string', 'oxc-parser'];
+  const missing = [];
+  const paths = [resolve(pkgRoot, 'plugins', 'design', 'dev-server'), resolve(pkgRoot)];
+  for (const dep of required) {
+    try {
+      require.resolve(dep, { paths });
+    } catch {
+      missing.push(dep);
+    }
+  }
+  return missing;
+}
+
 async function runExport({ args }) {
   // `maude design export <format> [--scope ...] [--port N] [--out <path>] [--option key=value]`
   const subArgs = args.slice(args.indexOf('export') + 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1agh/maude",
-  "version": "0.17.1",
+  "version": "0.17.2",
   "description": "Marketplace of Claude Code plugins by Michal Dovrtěl: `design` (canvas-first design iteration) + `flow` (generic agentic workflow loop with .ai second brain). Ships the `maude` CLI (with `mdcc` legacy alias) to scaffold workspace, run the design dev server, and manage configs.",
   "type": "module",
   "engines": {
@@ -41,13 +41,13 @@
     "prepublishOnly": "bash scripts/check-version-parity.sh"
   },
   "optionalDependencies": {
-    "@1agh/maude-darwin-arm64": "0.17.1",
-    "@1agh/maude-darwin-x64": "0.17.1",
-    "@1agh/maude-linux-arm64": "0.17.1",
-    "@1agh/maude-linux-arm64-musl": "0.17.1",
-    "@1agh/maude-linux-x64": "0.17.1",
-    "@1agh/maude-linux-x64-musl": "0.17.1",
-    "@1agh/maude-win32-x64": "0.17.1"
+    "@1agh/maude-darwin-arm64": "0.17.2",
+    "@1agh/maude-darwin-x64": "0.17.2",
+    "@1agh/maude-linux-arm64": "0.17.2",
+    "@1agh/maude-linux-arm64-musl": "0.17.2",
+    "@1agh/maude-linux-x64": "0.17.2",
+    "@1agh/maude-linux-x64-musl": "0.17.2",
+    "@1agh/maude-win32-x64": "0.17.2"
   },
   "files": [
     "cli",

package/plugins/design/dev-server/build.ts

@@ -15,8 +15,8 @@
 //
 // Per DDR-009 (Bun runtime authoritative) + DDR-012 (React 19 unified) + DDR-014 (Lightning CSS).
 
-import { existsSync, mkdirSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { browserslistToTargets, bundle as lcssBundle } from 'lightningcss';
@@ -122,14 +122,117 @@ async function buildCss(): Promise<{ outBytes: number; outPath: string }> {
 
 // ---------- (c) Server binary (bun build --compile, per-platform) ----------
 
+// Per-target oxc-parser binding embed. Bun 1.3.4+ regressed `--compile` NAPI
+// native-binding embedding (see DDR-042-oxc-parser-bun-compile-workaround.md).
+// `with { type: 'file' }` requires a literal string path, so we generate one
+// thin entry file per --target whose only purpose is to (1) embed the matching
+// platform binding as an asset, (2) set NAPI_RS_NATIVE_LIBRARY_PATH from the
+// runtime virtual path, then (3) hand off to the real server.ts. ESM
+// evaluation order guarantees the env var is set before any downstream module
+// touches oxc-parser.
+
+// oxc-parser's NAPI-RS binding packages use a richer slug than our build
+// target slug — Linux needs the libc kind suffix, Windows needs the toolchain
+// suffix. Mirrored from oxc-parser/src-js/bindings.js loader cases.
+function oxcBindingSlug(slug: string): string {
+  if (slug === 'linux-x64') return 'linux-x64-gnu';
+  if (slug === 'linux-arm64') return 'linux-arm64-gnu';
+  if (slug === 'win32-x64') return 'win32-x64-msvc';
+  // darwin-arm64 / darwin-x64 / linux-x64-musl / linux-arm64-musl already match.
+  return slug;
+}
+
+// npm/bun's installer respects each package's `os`/`cpu` fields and skips
+// platform sub-packages whose filter doesn't match the host (the bindings
+// declare e.g. `"cpu": ["x64"]`). For cross-compile targets — most notably
+// darwin-x64 built on a darwin-arm64 CI runner — this means the matching
+// `@oxc-parser/binding-<oxcSlug>` is NOT in node_modules even though it's
+// listed as a direct devDependency. Fetch + extract the tarball manually so
+// `with { type: 'file' }` resolution succeeds during `bun build --compile`.
+async function ensureBindingForTarget(oxcSlug: string): Promise<void> {
+  const bindingDir = join(ROOT, 'node_modules', '@oxc-parser', `binding-${oxcSlug}`);
+  const bindingFile = join(bindingDir, `parser.${oxcSlug}.node`);
+  if (existsSync(bindingFile)) return; // host install already placed it
+
+  // Read the installed oxc-parser version so the tarball URL stays in sync.
+  // Walk up from build.ts to find the workspace-visible oxc-parser package.json
+  // (pnpm hoists it under node_modules/.pnpm, then symlinks at workspace level).
+  let oxcVersion = '0.131.0';
+  const candidates = [
+    join(ROOT, 'node_modules', 'oxc-parser', 'package.json'),
+    join(ROOT, '..', '..', '..', 'node_modules', 'oxc-parser', 'package.json'),
+  ];
+  for (const c of candidates) {
+    if (existsSync(c)) {
+      oxcVersion = JSON.parse(readFileSync(c, 'utf8')).version;
+      break;
+    }
+  }
+
+  console.log(`[build] cross-compile: fetching @oxc-parser/binding-${oxcSlug}@${oxcVersion}`);
+  const tarballUrl = `https://registry.npmjs.org/@oxc-parser/binding-${oxcSlug}/-/binding-${oxcSlug}-${oxcVersion}.tgz`;
+  const response = await fetch(tarballUrl);
+  if (!response.ok) {
+    throw new Error(`failed to fetch ${tarballUrl}: HTTP ${response.status}`);
+  }
+  const tmpTgz = join(ROOT, `.binding-${oxcSlug}.tgz`);
+  await Bun.write(tmpTgz, await response.arrayBuffer());
+  mkdirSync(bindingDir, { recursive: true });
+  // npm pack output: `package/parser.<oxcSlug>.node` + `package/package.json`.
+  // --strip-components=1 drops the leading `package/` so files land in bindingDir.
+  const tarProc = Bun.spawn(['tar', 'xf', tmpTgz, '-C', bindingDir, '--strip-components=1'], {
+    stdout: 'inherit',
+    stderr: 'inherit',
+  });
+  const tarCode = await tarProc.exited;
+  if (tarCode !== 0)
+    throw new Error(`tar extraction failed for binding-${oxcSlug} (exit ${tarCode})`);
+  unlinkSync(tmpTgz);
+}
+
+export function writeCompileEntry(target: PlatformTarget): string {
+  const slug = platformSlug(target);
+  const oxcSlug = oxcBindingSlug(slug);
+  const entryDir = join(DIST, '.compile-entries');
+  mkdirSync(entryDir, { recursive: true });
+
+  // ESM hoists `import` statements above top-level code, so the env-var
+  // assignment MUST live in a separate leaf module that's imported BEFORE
+  // server.ts — otherwise server.ts (and transitively oxc-parser) evaluates
+  // first and reads NAPI_RS_NATIVE_LIBRARY_PATH before we set it.
+  const initPath = join(entryDir, `init-oxc-${slug}.ts`);
+  const entryPath = join(entryDir, `server-${slug}.ts`);
+  const bindingSpec = `@oxc-parser/binding-${oxcSlug}/parser.${oxcSlug}.node`;
+  const initContent = `// AUTO-GENERATED by build.ts — do not edit by hand.
+// Per-target oxc-parser binding embed (Bun 1.3.4+ --compile NAPI regression
+// workaround — see .ai/decisions/DDR-042-oxc-parser-bun-compile-workaround.md).
+// Side-effect module: must be imported BEFORE any oxc-parser usage.
+import bindingPath from ${JSON.stringify(bindingSpec)} with { type: 'file' };
+process.env.NAPI_RS_NATIVE_LIBRARY_PATH = bindingPath;
+`;
+  writeFileSync(initPath, initContent);
+
+  // Forward slashes for the import specifier even on Windows hosts — ESM uses
+  // POSIX-style paths, not the host's filesystem separator.
+  const realServerRel = relative(entryDir, join(ROOT, 'server.ts')).split('\\').join('/');
+  const entryContent = `// AUTO-GENERATED by build.ts — do not edit by hand.
+// Per-target compile entry — see DDR-042-oxc-parser-bun-compile-workaround.md.
+import './init-oxc-${slug}.ts';
+import ${JSON.stringify(realServerRel)};
+`;
+  writeFileSync(entryPath, entryContent);
+  return entryPath;
+}
+
 async function buildServerBinary(target: PlatformTarget): Promise<{ outPath: string }> {
   ensureDist();
   const slug = platformSlug(target);
   const ext = slug.startsWith('win32') ? '.exe' : '';
   const outPath = join(DIST, `maude-${slug}${ext}`);
-  const entry = join(ROOT, 'server.ts');
-  if (!existsSync(entry)) {
-    // T7 not landed yet — fall back to the .mjs entry so this script remains runnable mid-migration.
+  const realEntry = join(ROOT, 'server.ts');
+  if (!existsSync(realEntry)) {
+    // Legacy fallback — pre-DDR-009 .mjs path. Doesn't use oxc-parser, so the
+    // 1.3.4+ regression doesn't apply; entry stub generator is skipped.
     const legacy = join(ROOT, 'server.mjs');
     if (!existsSync(legacy)) throw new Error(`Neither server.ts nor server.mjs exists in ${ROOT}`);
     const proc = Bun.spawn(
@@ -150,6 +253,10 @@ async function buildServerBinary(target: PlatformTarget): Promise<{ outPath: str
       throw new Error(`bun build --compile (legacy) failed for ${target} (exit ${code})`);
     return { outPath };
   }
+  // Make sure the target's NAPI binding is on disk even if bun/npm's os/cpu
+  // filter skipped it (cross-compile case — see ensureBindingForTarget docs).
+  await ensureBindingForTarget(oxcBindingSlug(slug));
+  const entry = writeCompileEntry(target);
   const proc = Bun.spawn(
     [
       'bun',
@@ -262,6 +369,11 @@ async function main() {
   }
 }
 
-await main();
+// Only run the build when invoked directly — importers (e.g. the test suite,
+// which calls `writeCompileEntry` from build.ts) should not trigger a dev
+// build as a side effect.
+if (import.meta.main) {
+  await main();
+}
 
 export { buildClient, buildCss, buildServerBinary, PLATFORM_MATRIX, type PlatformTarget };

package/plugins/design/dev-server/canvas-pipeline.ts

@@ -16,6 +16,11 @@
 // Toolchain matches scripts/migrate-canvases.ts (codemod) and canvas-edit.ts
 // (AST-aware /design:edit element edits) — same oxc-parser + magic-string pair
 // in three call sites, one mental model.
+//
+// `bun build --compile` requires a per-target entry stub that sets
+// NAPI_RS_NATIVE_LIBRARY_PATH before this file's transitive imports load
+// oxc-parser. The pipeline itself is unaware of the workaround — it's a
+// build-layer concern. See DDR-042-oxc-parser-bun-compile-workaround.md.
 
 import MagicString from 'magic-string';
 import { parseSync } from 'oxc-parser';