@1agh/maude 0.19.1 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1agh/maude",
-  "version": "0.19.1",
+  "version": "0.21.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": {
@@ -18,7 +18,7 @@
   },
   "scripts": {
     "start": "bun run plugins/design/dev-server/server.ts",
-    "dev": "bun run plugins/design/dev-server/server.ts --port 4399",
+    "dev": "bun run plugins/design/dev-server/server.ts --port 4555",
     "dev:site": "pnpm --filter @maude/site dev --port 4398",
     "build": "pnpm -r --if-present run build",
     "build:binary": "bun run plugins/design/dev-server/build.ts --release",
@@ -41,18 +41,22 @@
     "prepublishOnly": "bash scripts/check-version-parity.sh"
   },
   "optionalDependencies": {
-    "@1agh/maude-darwin-arm64": "0.19.1",
-    "@1agh/maude-darwin-x64": "0.19.1",
-    "@1agh/maude-linux-arm64": "0.19.1",
-    "@1agh/maude-linux-arm64-musl": "0.19.1",
-    "@1agh/maude-linux-x64": "0.19.1",
-    "@1agh/maude-linux-x64-musl": "0.19.1",
-    "@1agh/maude-win32-x64": "0.19.1"
+    "@1agh/maude-darwin-arm64": "0.21.0",
+    "@1agh/maude-darwin-x64": "0.21.0",
+    "@1agh/maude-linux-arm64": "0.21.0",
+    "@1agh/maude-linux-arm64-musl": "0.21.0",
+    "@1agh/maude-linux-x64": "0.21.0",
+    "@1agh/maude-linux-x64-musl": "0.21.0",
+    "@1agh/maude-win32-x64": "0.21.0"
   },
   "files": [
     "cli",
     "plugins/design/dev-server",
+    "plugins/design/dependencies.json",
+    "plugins/design/dependencies.schema.json",
     "plugins/design/templates",
+    "plugins/flow/dependencies.json",
+    "plugins/flow/dependencies.schema.json",
     "plugins/flow/templates",
     "plugins/flow/.claude-plugin/config.schema.json",
     "LICENSE",
@@ -84,5 +88,9 @@
     "@biomejs/biome": "^1.9.4",
     "@changesets/cli": "^2.27.10",
     "@playwright/test": "^1.60.0"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1"
   }
 }

package/plugins/design/dependencies.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "./dependencies.schema.json",
+  "version": "1",
+  "plugin": "design",
+  "dependencies": [
+    {
+      "id": "node",
+      "type": "cli",
+      "hardness": "hard",
+      "check": {
+        "command": "node --version",
+        "expectExit": 0,
+        "minVersion": "20.0.0"
+      },
+      "install": {
+        "preferred": "https://nodejs.org/en/download",
+        "darwin": "brew install node@22",
+        "linux": "https://nodejs.org/en/download/package-manager"
+      },
+      "autoInstall": false,
+      "usedBy": ["commands/init.md", "commands/browse.md", "dev-server/server.ts"],
+      "docsUrl": "https://nodejs.org"
+    },
+    {
+      "id": "git",
+      "type": "cli",
+      "hardness": "hard",
+      "check": {
+        "command": "git --version",
+        "expectExit": 0
+      },
+      "install": {
+        "darwin": "brew install git",
+        "linux": "apt-get install -y git || dnf install -y git"
+      },
+      "autoInstall": false,
+      "usedBy": ["commands/init.md", "dev-server/collab/git-lifecycle.ts"],
+      "docsUrl": "https://git-scm.com"
+    },
+    {
+      "id": "bun",
+      "type": "cli",
+      "hardness": "hard",
+      "check": {
+        "command": "bun --version",
+        "expectExit": 0,
+        "minVersion": "1.3.0"
+      },
+      "install": {
+        "preferred": "curl -fsSL https://bun.sh/install | bash",
+        "darwin": "brew install oven-sh/bun/bun",
+        "win32": "powershell -c \"irm bun.sh/install.ps1 | iex\""
+      },
+      "autoInstall": false,
+      "fallbackBehavior": "dev-server is migrating to Bun authoritatively (DDR-009). Some build steps (bun run build.ts, bun test) require Bun and have no Node fallback.",
+      "usedBy": ["dev-server/package.json", "dev-server/build.ts", "dev-server/bin/smoke.sh"],
+      "docsUrl": "https://bun.com"
+    },
+    {
+      "id": "agent-browser",
+      "type": "cli",
+      "hardness": "soft",
+      "check": {
+        "command": "agent-browser --version",
+        "expectExit": 0
+      },
+      "install": {
+        "preferred": "npm i -g @anthropic-ai/agent-browser"
+      },
+      "autoInstall": true,
+      "fallbackBehavior": "Screenshot helpers fall back to `npx playwright` (slower, less reliable). /design:smoke and several critics need agent-browser for full coverage.",
+      "usedBy": [
+        "commands/screenshot.md",
+        "commands/new.md",
+        "commands/edit.md",
+        "commands/smoke.md",
+        "dev-server/bin/screenshot.sh",
+        "dev-server/bin/smoke.sh",
+        "agents/design-critic.md",
+        "agents/graphic-design-critic.md",
+        "agents/a11y-critic.md"
+      ],
+      "docsUrl": "https://github.com/anthropics/agent-browser"
+    },
+    {
+      "id": "playwright",
+      "type": "cli",
+      "hardness": "soft",
+      "check": {
+        "command": "npx --no-install playwright --version",
+        "expectExit": 0
+      },
+      "install": {
+        "preferred": "npm i -g playwright && npx playwright install chromium"
+      },
+      "autoInstall": false,
+      "fallbackBehavior": "Screenshot scripts use playwright as a fallback when agent-browser is missing. Without either, screenshot helpers will fail.",
+      "usedBy": ["dev-server/bin/_screenshot-playwright.mjs", "dev-server/bin/screenshot.sh"],
+      "docsUrl": "https://playwright.dev"
+    },
+    {
+      "id": "maude",
+      "type": "cli",
+      "hardness": "soft",
+      "check": {
+        "command": "maude --version",
+        "expectExit": 0
+      },
+      "install": {
+        "preferred": "npm i -g @1agh/maude"
+      },
+      "autoInstall": false,
+      "fallbackBehavior": "Slash commands still work; `maude` CLI provides faster scaffolding (init / config / design serve) without going through Claude.",
+      "usedBy": ["commands/init.md", "skills/design/SKILL.md"],
+      "docsUrl": "https://github.com/1aGh/maude"
+    },
+    {
+      "id": "jq",
+      "type": "system-tool",
+      "hardness": "soft",
+      "check": {
+        "command": "jq --version",
+        "expectExit": 0
+      },
+      "install": {
+        "darwin": "brew install jq",
+        "linux": "apt-get install -y jq || dnf install -y jq",
+        "win32": "winget install jqlang.jq"
+      },
+      "autoInstall": false,
+      "fallbackBehavior": "Slash commands' bash blocks that read .ai/workflows.config.json via jq degrade to inline node one-liners; harder to read but functional.",
+      "usedBy": ["dev-server/bin/bootstrap-check.sh", "dev-server/bin/server-up.sh"]
+    },
+    {
+      "id": "askuserquestion-mcp",
+      "type": "mcp",
+      "hardness": "soft",
+      "check": {
+        "mcp": "AskUserQuestion",
+        "tool": "ask"
+      },
+      "fallbackBehavior": "Discovery + critic-panel rounds fall back to numbered-prose chat. Slower, fewer options per round, no preview side-pane.",
+      "usedBy": ["skills/design-system/SKILL.md", "commands/setup-ds.md", "commands/new.md"],
+      "docsUrl": "https://docs.claude.com/en/docs/claude-code"
+    }
+  ]
+}

package/plugins/design/dependencies.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "maude plugin — runtime dependency manifest",
+  "description": "Declares CLI binaries, MCP servers, and runtime packages the plugin's commands / agents / skills shell out to. Consumed by maude doctor (cli/commands/doctor.mjs) and preflight.sh / preflight.mjs. Schema is shared between plugins — each plugin ships its own dependencies.json + (symlink to) this schema.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "plugin", "dependencies"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "const": "1",
+      "description": "Manifest schema version. Bumped when the dependency entry shape changes incompatibly."
+    },
+    "plugin": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Plugin name (matches plugins/<plugin>/.claude-plugin/plugin.json `name`)."
+    },
+    "dependencies": {
+      "type": "array",
+      "minItems": 0,
+      "items": { "$ref": "#/$defs/Dependency" }
+    }
+  },
+  "$defs": {
+    "Dependency": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "type", "hardness", "check"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9._-]*$",
+          "description": "Unique identifier within the manifest. Lowercase, hyphenated."
+        },
+        "type": {
+          "type": "string",
+          "enum": ["cli", "mcp", "node-package", "bun-package", "system-tool"],
+          "description": "What kind of dependency. `cli` = on PATH; `mcp` = MCP server / tool; `node-package` / `bun-package` = installed via npm/bun; `system-tool` = OS-provided (curl, jq)."
+        },
+        "hardness": {
+          "type": "string",
+          "enum": ["hard", "soft"],
+          "description": "`hard` = missing blocks plugin use; `soft` = graceful degradation possible (fallback path, warning only)."
+        },
+        "check": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "How to detect presence. For CLI/system-tool/package: shell command + expected exit. For MCP: tool name to probe.",
+          "properties": {
+            "command": {
+              "type": "string",
+              "description": "Shell command executed via `bash -c`. Pipes allowed. Defaults to `<id> --version`."
+            },
+            "expectExit": {
+              "type": "integer",
+              "default": 0,
+              "description": "Expected exit code. Anything else = missing/broken."
+            },
+            "minVersion": {
+              "type": "string",
+              "description": "Minimum semver. Comparator extracts `vX.Y.Z` from check.command stdout."
+            },
+            "mcp": {
+              "type": "string",
+              "description": "MCP server name. For type=mcp only."
+            },
+            "tool": {
+              "type": "string",
+              "description": "Specific tool name on the MCP server. For type=mcp only."
+            }
+          }
+        },
+        "install": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "Install commands per platform. `preferred` is OS-agnostic / fallback; per-platform keys override.",
+          "properties": {
+            "preferred": { "type": "string" },
+            "darwin": { "type": "string" },
+            "linux": { "type": "string" },
+            "win32": { "type": "string" }
+          }
+        },
+        "autoInstall": {
+          "type": "boolean",
+          "default": false,
+          "description": "If true, `maude doctor --fix` may run install.preferred after per-dep confirmation prompt."
+        },
+        "fallbackBehavior": {
+          "type": "string",
+          "description": "What the plugin does when this soft dep is missing. Human-readable; surfaces in maude doctor's report."
+        },
+        "usedBy": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Repo-relative paths (or path globs) of plugin files that reference this dependency. Aids debugging — doctor surfaces this when explaining a miss."
+        },
+        "docsUrl": {
+          "type": "string",
+          "format": "uri",
+          "description": "Where to read more."
+        }
+      }
+    }
+  }
+}

package/plugins/design/dev-server/ai-banner.tsx

@@ -0,0 +1,188 @@
+/**
+ * @file       ai-banner.tsx — yellow "Claude is editing this canvas" banner
+ * @scope      plugins/design/dev-server/ai-banner.tsx
+ * @purpose    Mounted by canvas-shell. Subscribes to the inspector WS
+ *             `ai-activity` event for the canvas's own file path; shows a
+ *             non-modal yellow banner while AI work is in progress and clears
+ *             on explicit /end OR 30-second heartbeat-grace expiry.
+ *
+ * The banner is a soft notice, NOT a lock — the user can still type, click,
+ * drag annotations, etc. It exists so the user doesn't unknowingly fight a
+ * `/design:edit` that's about to rewrite their HTML.
+ */
+
+import { useEffect, useState } from 'react';
+
+function deriveFile(): string | null {
+  if (typeof window === 'undefined') return null;
+  try {
+    const p = window.location.pathname;
+    if (p === '/_canvas-shell.html' || p === '/_canvas-shell') {
+      const qs = new URLSearchParams(window.location.search);
+      const canvas = qs.get('canvas') ?? '';
+      const designRel = (qs.get('designRel') ?? '.design').replace(/^\/+|\/+$/g, '');
+      return canvas ? `${designRel}/${canvas}` : null;
+    }
+    return decodeURIComponent(p).replace(/^\//, '');
+  } catch {
+    return null;
+  }
+}
+
+const BANNER_CSS = `
+.dc-ai-banner {
+  position: fixed;
+  top: 14px;
+  left: 50%;
+  transform: translateX(-50%);
+  z-index: 10001;
+  padding: 8px 14px;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  background: var(--maude-hud-accent-tint, oklch(92% 0.040 55));
+  color: var(--fg-0, #111);
+  border: 1px solid var(--border-default, rgba(0,0,0,0.16));
+  border-radius: var(--radius-md, 4px);
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
+  font-family: var(--font-sans, system-ui, -apple-system, sans-serif);
+  font-weight: 500;
+  font-size: 12px;
+  line-height: 1.2;
+  letter-spacing: 0.01em;
+  pointer-events: none;
+  user-select: none;
+}
+.dc-ai-banner__dot {
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  background: var(--maude-hud-accent, oklch(56% 0.170 50));
+  flex: 0 0 auto;
+  animation: dc-ai-banner-pulse 1.4s ease-in-out infinite;
+}
+@keyframes dc-ai-banner-pulse {
+  0%, 100% { opacity: 1; transform: scale(1); }
+  50%      { opacity: 0.5; transform: scale(0.75); }
+}
+@media (prefers-reduced-motion: reduce) {
+  .dc-ai-banner__dot { animation: none; }
+}
+`.trim();
+
+function ensureBannerStyles(): void {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById('dc-ai-banner-css')) return;
+  const s = document.createElement('style');
+  s.id = 'dc-ai-banner-css';
+  s.textContent = BANNER_CSS;
+  document.head.appendChild(s);
+}
+
+interface AiEntry {
+  file: string;
+  author: string;
+  startedAt: number;
+  lastHeartbeat: number;
+}
+
+export function AiBanner(): JSX.Element | null {
+  ensureBannerStyles();
+  const [entry, setEntry] = useState<AiEntry | null>(null);
+  const file = deriveFile();
+
+  // Mount-time backfill — the bus only emits on changes, so a freshly opened
+  // tab needs to GET the snapshot to learn that an edit is already in flight.
+  useEffect(() => {
+    if (!file) return;
+    let cancelled = false;
+    fetch('/_api/ai')
+      .then((r) => r.json())
+      .then((j: { entries?: AiEntry[] }) => {
+        if (cancelled) return;
+        const hit = (j.entries ?? []).find((e) => e.file === file);
+        if (hit) setEntry(hit);
+      })
+      .catch(() => {
+        /* offline / restart — silently no-op */
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [file]);
+
+  // Subscribe to the parent shell's WS broadcast — when the inspector channel
+  // receives an `ai-activity` event for OUR file path, update local state.
+  // The shell relays via postMessage so we don't need our own WS connection
+  // (the iframe already piggybacks on the parent's inspector session).
+  //
+  // FALLBACK — when the canvas is opened standalone (export iframe, _shell.html
+  // direct URL), no parent WS exists. We open a thin reader-only inspector WS
+  // ourselves and watch for the matching event.
+  useEffect(() => {
+    if (!file) return;
+    if (typeof window === 'undefined') return;
+
+    // postMessage relay path — parent sends `ai-activity` events.
+    const onMessage = (e: MessageEvent) => {
+      const m = e.data as { dgn?: string; file?: string; entry?: AiEntry | null } | null;
+      if (!m || typeof m !== 'object') return;
+      if (m.dgn !== 'ai-activity') return;
+      if (m.file !== file) return;
+      setEntry(m.entry ?? null);
+    };
+    window.addEventListener('message', onMessage);
+
+    // Standalone fallback — if no parent is relaying, dial /_ws directly.
+    let standaloneWs: WebSocket | null = null;
+    let reconnect: ReturnType<typeof setTimeout> | null = null;
+    function connectStandalone() {
+      const proto = location.protocol === 'https:' ? 'wss:' : 'ws:';
+      const ws = new WebSocket(`${proto}//${location.host}/_ws`);
+      standaloneWs = ws;
+      ws.addEventListener('message', (ev) => {
+        try {
+          const data = typeof ev.data === 'string' ? ev.data : '';
+          if (!data) return;
+          const m = JSON.parse(data) as { type?: string; file?: string; entry?: AiEntry | null };
+          if (m.type !== 'ai-activity') return;
+          if (m.file !== file) return;
+          setEntry(m.entry ?? null);
+        } catch {
+          /* not a JSON frame (binary from collab WS) — ignore */
+        }
+      });
+      ws.addEventListener('close', () => {
+        standaloneWs = null;
+        reconnect = setTimeout(connectStandalone, 2000);
+      });
+      ws.addEventListener('error', () => {
+        /* close handler reconnects */
+      });
+    }
+    // Only open the standalone WS when we're not inside an iframe — the parent
+    // already drives the postMessage relay for embedded canvases.
+    if (window.parent === window) connectStandalone();
+
+    return () => {
+      window.removeEventListener('message', onMessage);
+      if (reconnect) clearTimeout(reconnect);
+      if (standaloneWs && standaloneWs.readyState === WebSocket.OPEN) {
+        try {
+          standaloneWs.close();
+        } catch {
+          /* ignore */
+        }
+      }
+    };
+  }, [file]);
+
+  if (!entry) return null;
+  return (
+    // biome-ignore lint/a11y/useSemanticElements: <output> is a form-result element; role="status" on a div is the canonical live-region banner pattern (APG).
+    <div className="dc-ai-banner" role="status" aria-live="polite">
+      <span className="dc-ai-banner__dot" aria-hidden="true" />
+      <span>{entry.author} is editing this canvas — your changes may conflict</span>
+    </div>
+  );
+}