@1agh/maude 0.17.1 → 0.18.0

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);
@@ -366,6 +508,13 @@ function escapeReg(s) {
 }
 
 function defaultPayload({ projectName, dsName }) {
+  // `--no-discovery` mode emits a deliberately NEUTRAL skeleton:
+  // achromatic grayscale, system fonts only, equal spacing/radii steps,
+  // single accent set to neutral graphite. The intent is for the project
+  // to immediately overwrite these with discovery-driven values via
+  // `/design:setup-ds`. These are NOT a "recommended starter palette" —
+  // they're an explicit placeholder that should look unfinished, so the
+  // designer is nudged toward actual decisions (DDR-026, 2026-05-25).
   return {
     project_name: projectName,
     project_label: titleCase(projectName),
@@ -373,7 +522,7 @@ function defaultPayload({ projectName, dsName }) {
     ds_skill_name: `${dsName}-design`,
     ds_description: `Default design system for ${projectName}.`,
     root_class: 'app',
-    theme_default: 'dark',
+    theme_default: 'light',
     theme_extra: '',
     handoff_targets: '[]',
     active_families: JSON.stringify(['accent']),
@@ -386,38 +535,94 @@ function defaultPayload({ projectName, dsName }) {
     platform_hard_rules: '',
     content_tone: 'direct-terse',
     mood_references_block: '_(not specified — extend during the next /design:setup-ds run)_',
-    type_scale_summary: '8-step ladder, 12–36px.',
-    voice_tone_block: 'Direct, terse. Action verbs. No marketing puffery.',
-    voice_tone_summary: 'direct-terse',
-    iconography_summary: 'Lucide, 1.5px stroke.',
+    type_scale_summary: '8-step ladder, populated by discovery.',
+    type_scale_summary_compact: '8-step (modular ratio)',
+    voice_tone_block: 'Voice not declared yet — capture during /design:setup-ds.',
+    voice_tone_summary: 'not-declared',
+    iconography_summary: 'Icon family not declared yet — capture during /design:setup-ds.',
     hard_rules_from_system_readme: '_(see system/<ds>/README.md Hard rules section)_',
     hard_rules_block:
-      '- WCAG 2.1 AA contrast\n- No off-token colors / radii / spacings\n- Real product strings only — no placeholder copy',
+      '- WCAG 2.1 AA contrast\n- No off-token values in canvases\n- Real product strings only — no placeholder copy',
     iso_timestamp: new Date().toISOString(),
-    // Token defaults (dark theme, neutral indigo accent)
-    bg_0_oklch: 'oklch(16% 0.012 245)',
-    bg_1_oklch: 'oklch(20% 0.014 245)',
-    bg_2_oklch: 'oklch(24% 0.014 245)',
-    bg_3_oklch: 'oklch(28% 0.013 245)',
-    bg_4_oklch: 'oklch(33% 0.013 245)',
-    fg_0_oklch: 'oklch(96% 0.008 245)',
-    fg_1_oklch: 'oklch(78% 0.012 245)',
-    fg_2_oklch: 'oklch(60% 0.012 245)',
-    fg_3_oklch: 'oklch(42% 0.010 245)',
-    accent_oklch: 'oklch(64% 0.18 264)',
-    accent_fg_oklch: 'oklch(98% 0.008 264)',
-    radius_xs: '4px',
-    radius_sm: '6px',
-    radius_md: '8px',
-    radius_lg: '12px',
-    radius_xl: '16px',
-    font_display: '"Inter", system-ui, sans-serif',
-    font_body: '"Inter", system-ui, sans-serif',
-    font_mono: '"JetBrains Mono", ui-monospace, monospace',
-    dur_flip: '140ms',
-    dur_panel: '220ms',
-    dur_route: '260ms',
+    // ─── Neutral-skeleton tokens (light theme grayscale, no chroma) ───
+    bg_0: 'oklch(100% 0 0)',
+    bg_1: 'oklch(97% 0 0)',
+    bg_2: 'oklch(94% 0 0)',
+    bg_3: 'oklch(90% 0 0)',
+    bg_4: 'oklch(85% 0 0)',
+    border_subtle: 'oklch(92% 0 0)',
+    border_default: 'oklch(85% 0 0)',
+    border_strong: 'oklch(70% 0 0)',
+    border_strategy: 'fixed-token',
+    fg_0: 'oklch(15% 0 0)',
+    fg_1: 'oklch(35% 0 0)',
+    fg_2: 'oklch(55% 0 0)',
+    fg_3: 'oklch(75% 0 0)',
+    accent_strategy: 'single',
+    accent_strategy_summary: 'single accent — discovery has not been run',
+    accent_block:
+      '  --accent:        oklch(35% 0 0);\n  --accent-hover:  oklch(30% 0 0);\n  --accent-active: oklch(25% 0 0);\n  --accent-fg:     oklch(98% 0 0);',
+    accent_rules_block:
+      'Single accent family (`--accent`, `--accent-hover`, `--accent-active`, `--accent-fg`). Project has not run discovery yet — the accent is set to neutral graphite as a placeholder. Run `/design:setup-ds` to pick a real palette.',
+    accent_rules_summary: 'Single family until discovery runs.',
+    color_space: 'oklch',
+    color_space_summary: 'OKLCH (default)',
+    color_space_block:
+      '**Color space:** OKLCH (default). Override via `config.colorSpace` if your project requires HSL, hex, or LAB.',
+    status_success: 'oklch(55% 0 0)',
+    status_warn: 'oklch(55% 0 0)',
+    status_error: 'oklch(55% 0 0)',
+    status_info: 'oklch(55% 0 0)',
+    presence_online: 'var(--status-success)',
+    presence_away: 'var(--status-warn)',
+    presence_offline: 'var(--fg-3)',
+    shadow_sm: 'none',
+    shadow_md: 'none',
+    shadow_lg: 'none',
+    radius_xs: '0',
+    radius_sm: '0',
+    radius_md: '0',
+    radius_lg: '0',
+    radius_xl: '0',
+    radius_pill: '999px',
+    space_0: '0',
+    space_1: '4px',
+    space_2: '8px',
+    space_3: '12px',
+    space_4: '16px',
+    space_5: '24px',
+    space_6: '32px',
+    space_7: '48px',
+    space_8: '64px',
+    font_display: 'system-ui, sans-serif',
+    font_body: 'system-ui, sans-serif',
+    font_mono: 'ui-monospace, monospace',
+    type_xs: '12px',
+    lh_xs: '16px',
+    type_sm: '13px',
+    lh_sm: '18px',
+    type_base: '14px',
+    lh_base: '20px',
+    type_md: '16px',
+    lh_md: '22px',
+    type_lg: '18px',
+    lh_lg: '26px',
+    type_xl: '22px',
+    lh_xl: '30px',
+    type_2xl: '28px',
+    lh_2xl: '36px',
+    type_3xl: '36px',
+    lh_3xl: '44px',
+    dur_flip: '120ms',
+    dur_panel: '200ms',
+    dur_route: '240ms',
     dur_soft: '320ms',
+    ease_out_curve: 'ease-out',
+    ease_in_out_curve: 'ease-in-out',
+    layout_max_w: '1200px',
+    layout_gutter: 'var(--space-4)',
+    touch_target_rule:
+      '44×44 minimum on touch surfaces (iOS HIG); 48×48 if the primary platform is Android (Material). N/A on desktop-only systems.',
     // Empty-state template fields
     empty_subject: 'items',
     empty_supporting: "When you create your first one, it'll show up here.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1agh/maude",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "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.18.0",
+    "@1agh/maude-darwin-x64": "0.18.0",
+    "@1agh/maude-linux-arm64": "0.18.0",
+    "@1agh/maude-linux-arm64-musl": "0.18.0",
+    "@1agh/maude-linux-x64": "0.18.0",
+    "@1agh/maude-linux-x64-musl": "0.18.0",
+    "@1agh/maude-win32-x64": "0.18.0"
   },
   "files": [
     "cli",

package/plugins/design/dev-server/bin/screenshot.sh

@@ -64,6 +64,18 @@ else
   [ -z "$OUT" ]     && { echo "screenshot.sh: --out required for single-shot modes" >&2; exit 2; }
 fi
 
+# TSX specimens cannot be opened via file:// — the browser would see raw JSX.
+# They must go through the dev-server route (http://localhost:PORT/<rel>),
+# which transpiles via _canvas-shell.html?canvas=<rel>. Phase 19 / DDR-044.
+case "$URL" in
+  file://*.tsx)
+    echo "screenshot.sh: TSX specimens cannot be screenshot via file:// (the browser sees raw JSX)." >&2
+    echo "  Use --port instead — the dev-server compiles TSX through _canvas-shell.html?canvas=<rel>." >&2
+    echo "  Example: screenshot.sh --port 4399 --full --out shot.png  (set the active canvas in the browser first)" >&2
+    exit 2
+    ;;
+esac
+
 # ---------- url resolution ----------
 if [ -z "$URL" ]; then
   REPO="${ROOT:-${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}}"

package/plugins/design/dev-server/boot-self-heal.ts

@@ -0,0 +1,90 @@
+// Boot-time self-heal — covers the gap between marketplace-cache installs
+// (git clone, honors .gitignore, no `npm install`) and what server.ts needs
+// at runtime. Two artifacts can be missing on a fresh clone:
+//
+//   - dist/client.bundle.js     → 404 on /_client/*
+//   - node_modules/react        → 500 on /_canvas-runtime/*
+//
+// Per DDR-044 we commit the bundle + styles, so dist/ should be present.
+// For node_modules/ we self-heal: detect missing react, run `bun install
+// --production`. Opt out with MAUDE_NO_AUTOBUILD=1 for read-only-filesystem
+// deployments (e.g. immutable infra).
+//
+// Phase 19. DDR-044.
+
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export interface SelfHealOptions {
+  /** Plugin install directory (the dev-server root). Defaults to this file's dir. */
+  here?: string;
+  /** Defaults to process.env.MAUDE_NO_AUTOBUILD === '1'. */
+  optOut?: boolean;
+  /** Defaults to Bun.spawn; tests override. */
+  spawn?: (cmd: readonly string[], cwd: string) => Promise<{ code: number }>;
+  /** Defaults to console.error; tests override to capture. */
+  log?: (msg: string) => void;
+  /** Defaults to process.exit; tests override to assert. */
+  exit?: (code: number) => never;
+}
+
+export interface SelfHealResult {
+  ran: ('install' | 'build')[];
+  skipped: 'all-present' | null;
+}
+
+export async function bootSelfHeal(opts: SelfHealOptions = {}): Promise<SelfHealResult> {
+  const here = opts.here ?? dirname(fileURLToPath(import.meta.url));
+  const optOut = opts.optOut ?? process.env.MAUDE_NO_AUTOBUILD === '1';
+  const log = opts.log ?? ((m) => console.error(m));
+  const exit =
+    opts.exit ??
+    ((code: number) => {
+      process.exit(code);
+    });
+  const spawn = opts.spawn ?? defaultSpawn;
+
+  const distMissing = !existsSync(join(here, 'dist', 'client.bundle.js'));
+  const depsMissing = !existsSync(join(here, 'node_modules', 'react', 'package.json'));
+
+  if (!distMissing && !depsMissing) return { ran: [], skipped: 'all-present' };
+
+  if (optOut) {
+    const missing = [
+      distMissing ? 'dist/client.bundle.js (run `bun run build.ts`)' : null,
+      depsMissing ? 'node_modules/react (run `bun install --production`)' : null,
+    ]
+      .filter(Boolean)
+      .join('\n  - ');
+    log(`\n  ⚠ first-boot artifacts missing and MAUDE_NO_AUTOBUILD=1 is set:\n  - ${missing}\n`);
+    exit(1);
+  }
+
+  const ran: ('install' | 'build')[] = [];
+  if (depsMissing) {
+    log('  ⚠ first-boot: installing runtime deps (one-time, ~15s)…');
+    const { code } = await spawn(['bun', 'install', '--production'], here);
+    if (code !== 0) {
+      log(`  ⚠ \`bun install --production\` exited ${code}. Set MAUDE_NO_AUTOBUILD=1 and run manually.`);
+      exit(1);
+    }
+    ran.push('install');
+  }
+  if (distMissing) {
+    log('  ⚠ first-boot: building client assets (one-time, ~2s)…');
+    const { code } = await spawn(['bun', 'run', 'build.ts'], here);
+    if (code !== 0) {
+      log(`  ⚠ \`bun run build.ts\` exited ${code}. Set MAUDE_NO_AUTOBUILD=1 and run manually.`);
+      exit(1);
+    }
+    ran.push('build');
+  }
+  return { ran, skipped: null };
+}
+
+async function defaultSpawn(cmd: readonly string[], cwd: string): Promise<{ code: number }> {
+  const proc = Bun.spawn([...cmd], { cwd, stdout: 'inherit', stderr: 'inherit' });
+  const code = await proc.exited;
+  return { code };
+}