@1agh/maude 0.30.0 → 0.32.0

package/apps/studio/participants-chrome.tsx

@@ -139,6 +139,35 @@ const CHROME_CSS = `
   white-space: normal;
   max-width: 200px;
 }
+/* Phase 30 / DDR-120 — soft editing-presence. A peer (or a bridged agent)
+   actively editing this canvas gets a gently-pulsing ring + a ✎ marker in the
+   peer's OWN identity hue (--dc-edit-ring, set inline from peer.color) so the
+   agent pulses violet, not the indigo accent. A heads-up, never a lock. */
+.dc-participant--editing { animation: dc-participant-edit-pulse 1.8s ease-in-out infinite; }
+@keyframes dc-participant-edit-pulse {
+  0%, 100% { box-shadow: 0 1px 2px rgba(0,0,0,0.08), 0 0 0 2px var(--dc-edit-ring, var(--maude-hud-accent, oklch(56% 0.170 50))); }
+  50% { box-shadow: 0 1px 2px rgba(0,0,0,0.08), 0 0 0 4px color-mix(in oklab, var(--dc-edit-ring, var(--maude-hud-accent, oklch(56% 0.170 50))) 45%, transparent); }
+}
+.dc-participant-edit-marker {
+  position: absolute;
+  right: -3px;
+  top: -3px;
+  width: 13px;
+  height: 13px;
+  border-radius: 50%;
+  background: var(--maude-chrome-bg-0, #fff);
+  color: var(--dc-edit-ring, var(--maude-hud-accent, oklch(56% 0.170 50)));
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 8px;
+  line-height: 1;
+  box-shadow: 0 0 0 1px rgba(0,0,0,0.14);
+  pointer-events: none;
+}
+@media (prefers-reduced-motion: reduce) {
+  .dc-participant--editing { animation: none; box-shadow: 0 1px 2px rgba(0,0,0,0.08), 0 0 0 2px var(--dc-edit-ring, var(--maude-hud-accent, oklch(56% 0.170 50))); }
+}
 `.trim();
 
 function ensureChromeStyles(): void {
@@ -150,6 +179,17 @@ function ensureChromeStyles(): void {
   document.head.appendChild(s);
 }
 
+/**
+ * Phase 30 / DDR-120 — true when a foreign peer is THIS machine's own
+ * server-side editing echo: a peer carrying my own name with editing set but
+ * no cursor/selection. That's the room's projection of my own agent/inspector
+ * edit (which I already see via the local ai-activity avatar), so I skip it. A
+ * remote peer never matches (different name), so they still get the heads-up.
+ */
+function isOwnEditingEcho(peer: ForeignAwareness, myName: string | undefined): boolean {
+  return peer.name === myName && !!peer.editing && !peer.cursor && !peer.selection;
+}
+
 function initialsFor(name: string): string {
   const cleaned = name.trim();
   if (!cleaned) return '?';
@@ -169,6 +209,7 @@ interface AvatarProps {
 function Avatar({ peer, isFollowing, onToggleFollow }: AvatarProps): JSX.Element {
   const [open, setOpen] = useState(false);
   const rootRef = useRef<HTMLDivElement | null>(null);
+  const editing = !!peer.editing;
 
   useEffect(() => {
     if (!open) return;
@@ -180,11 +221,16 @@ function Avatar({ peer, isFollowing, onToggleFollow }: AvatarProps): JSX.Element
     return () => document.removeEventListener('mousedown', onDocClick);
   }, [open]);
 
+  const cls = `dc-participant${isFollowing ? ' dc-participant--following' : ''}${editing ? ' dc-participant--editing' : ''}`;
+  // `--dc-edit-ring` drives the editing pulse/marker off the peer's own hue.
+  const style = (
+    editing ? { background: peer.color, '--dc-edit-ring': peer.color } : { background: peer.color }
+  ) as React.CSSProperties;
   return (
     <div
       ref={rootRef}
-      className={`dc-participant${isFollowing ? ' dc-participant--following' : ''}`}
-      style={{ background: peer.color }}
+      className={cls}
+      style={style}
       onClick={() => setOpen((v) => !v)}
       onKeyDown={(e) => {
         if (e.key === 'Enter' || e.key === ' ') {
@@ -194,14 +240,20 @@ function Avatar({ peer, isFollowing, onToggleFollow }: AvatarProps): JSX.Element
       }}
       role="button"
       tabIndex={0}
-      title={peer.name}
-      aria-label={peer.name}
+      title={editing ? `${peer.name} — editing this canvas` : peer.name}
+      aria-label={editing ? `${peer.name}, editing this canvas` : peer.name}
       aria-expanded={open}
     >
       {initialsFor(peer.name)}
+      {editing && (
+        <span className="dc-participant-edit-marker" aria-hidden="true">
+          ✎
+        </span>
+      )}
       {open && (
         <div className="dc-participant-popover" onClick={(e) => e.stopPropagation()}>
           <div className="dc-participant-popover__name">{peer.name}</div>
+          {editing && <div className="dc-participant-popover__sub">Editing this canvas</div>}
           <button
             type="button"
             className={`dc-participant-popover__btn${isFollowing ? ' dc-participant-popover__btn--stop' : ''}`}
@@ -318,13 +370,21 @@ export function ParticipantsChrome(): JSX.Element | null {
     controller.setViewport(v);
   }, [controller, followTarget, peers]);
 
-  // Render whenever there's a human peer OR an active agent (so an agent shows
-  // even with no human collaborators connected).
-  if (peers.length === 0 && !agent) return null;
+  // Phase 30 / DDR-120 — drop the authoring machine's own server-side editing
+  // echo: a foreign peer carrying MY name with editing set but no cursor/
+  // selection is the room's projection of my own agent/inspector edit, which I
+  // already see via the local ai-activity avatar. A remote peer never matches
+  // (different name), so they still get the "X is editing" heads-up.
+  const myName = collab?.myName;
+  const visiblePeers = peers.filter((p) => !isOwnEditingEcho(p, myName));
+
+  // Render whenever there's a visible human peer OR an active agent (so an agent
+  // shows even with no human collaborators connected).
+  if (visiblePeers.length === 0 && !agent) return null;
 
   return (
     <div className="dc-participants" aria-label="Active collaborators">
-      {peers.map((p) => (
+      {visiblePeers.map((p) => (
         <Avatar
           key={p.clientID}
           peer={p}
@@ -337,4 +397,4 @@ export function ParticipantsChrome(): JSX.Element | null {
   );
 }
 
-export { initialsFor };
+export { initialsFor, isOwnEditingEcho };

package/apps/studio/paths.ts

@@ -82,6 +82,18 @@ function isDevServerDir(dir: string): boolean {
 }
 
 function resolveDevServerRoot(): string {
+  // (0) Explicit override. Used when the runtime can't be found by walk-up — e.g.
+  // the Tauri desktop bundle (DDR-106) ships apps/studio/ as an app resource and
+  // sets MAUDE_DEV_SERVER_ROOT to it, because the sidecar binary sits alone in
+  // Maude.app/Contents/MacOS/ with no apps/studio/ up-tree (the bundle ships the
+  // full source, so `http.ts` is present at the resource root).
+  const override = process.env.MAUDE_DEV_SERVER_ROOT;
+  // Require the same `http.ts` anchor walk-up uses (not merely a `dist/` dir) so a
+  // planted dist-only directory can't hijack the runtime root (security review F4).
+  if (override && !isVirtualBunfsPath(override) && isDevServerDir(override)) {
+    return override;
+  }
+
   // (1) Dev mode: import.meta.url is a real file:// path AND lands in the
   // dev-server dir. Common case for `bun run server.ts`, tests, etc.
   const importDir = getImportMetaDir();

package/apps/studio/readiness.ts

@@ -0,0 +1,220 @@
+// First-open AI-editing readiness probe (DDR-128). Backs `GET /_api/preflight`.
+//
+// Read-only: it reports which pieces of the AI-editing chain are present — the
+// `claude` CLI, the `maude` CLI, the maude marketplace + plugins registered in the
+// paired Claude Code, and the optional `agent-browser` — with per-item remediation.
+// It NEVER installs, links, or mutates anything (DDR-128 detect-and-guide posture).
+//
+// PATH accuracy: in the packaged `.app` the sidecar's PATH is corrected at the Rust
+// boundary (apps/desktop/.../sidecar.rs, DDR-128), so `Bun.which` is accurate here;
+// `resolveOnPath` keeps a login-shell fallback as defense-in-depth for an unusual
+// shell config the Rust resolution missed. Under `maude design serve` the terminal
+// PATH is already correct.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+import { resolveClaudePath } from './acp/probe.ts';
+
+export type ReadinessStatus = 'present' | 'missing' | 'unknown';
+
+export interface ReadinessItem {
+  id: 'claude' | 'maude' | 'plugins' | 'agent-browser';
+  /** Short human label for the row. */
+  label: string;
+  /** Required items gate `ready`; optional ones never block it. */
+  required: boolean;
+  status: ReadinessStatus;
+  /** One-line current-state description. */
+  detail: string;
+  /** Copy-paste-able fix, present only when the item is not satisfied. */
+  remediation?: string;
+}
+
+export interface ReadinessReport {
+  /** True when every REQUIRED item is `present`. */
+  ready: boolean;
+  items: ReadinessItem[];
+}
+
+/**
+ * Resolve a binary on PATH. `Bun.which` first (accurate once the sidecar PATH is
+ * Rust-corrected, and always correct under a terminal launch); a login-shell
+ * fallback recovers a binary the app env can't see when the Rust resolution missed.
+ * Unix-only fallback (Windows GUI apps inherit the user PATH). Returns an absolute
+ * path or null. `bin` is always a hardcoded literal — never user input.
+ *
+ * Async + `Bun.spawn` (not `spawnSync`): the fallback shells out for up to 5 s, so a
+ * synchronous spawn would block the single-threaded dev-server event loop for the
+ * whole probe — a real freeze on a fresh machine where the binary is missing
+ * (DDR-128 hardening, ethical-hacker F1). Awaiting yields the loop; the 5 s kill
+ * bounds a misconfigured rc.
+ */
+export async function resolveOnPath(bin: string): Promise<string | null> {
+  const direct = Bun.which(bin);
+  if (direct) return direct;
+  if (process.platform === 'win32') return null;
+  try {
+    const shell = process.env.SHELL || '/bin/sh';
+    const proc = Bun.spawn([shell, '-ilc', `command -v ${bin} 2>/dev/null`], {
+      stdin: 'ignore',
+      stdout: 'pipe',
+      stderr: 'ignore',
+    });
+    const killer = setTimeout(() => {
+      try {
+        proc.kill(9);
+      } catch {
+        /* already gone */
+      }
+    }, 5000);
+    let out: string;
+    try {
+      out = await new Response(proc.stdout).text();
+    } finally {
+      clearTimeout(killer);
+    }
+    // Instant-prompt frameworks (powerlevel10k) can print to stdout on interactive
+    // start, so take the last line that is an absolute path to a real file.
+    const hit = out
+      .split('\n')
+      .map((l) => l.trim())
+      .reverse()
+      .find((l) => l.startsWith('/') && existsSync(l));
+    return hit ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Claude Code's config dir — relocatable via `CLAUDE_CONFIG_DIR` (its own contract). */
+function claudeConfigDir(): string {
+  return process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude');
+}
+
+function readJson<T = unknown>(path: string): T | null {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as T;
+  } catch {
+    return null;
+  }
+}
+
+interface PluginScan {
+  /** 'unknown' when the registry couldn't be read (Claude Code's internal contract). */
+  status: 'present' | 'unknown';
+  marketplace: boolean;
+  design: boolean;
+  flow: boolean;
+}
+
+/**
+ * Read-only scan of Claude Code's plugin registry for the maude marketplace
+ * (`repo: 1aGh/maude`) and the `design@maude` / `flow@maude` plugins. `readFileSync`
+ * follows symlinks (a dev's `~/.claude` is symlinked into Dotfiles). Never writes,
+ * never throws — an unrecognized layout yields `status: 'unknown'`.
+ */
+function scanPlugins(): PluginScan {
+  const dir = claudeConfigDir();
+  const markets = readJson<Record<string, { source?: { repo?: string } }>>(
+    join(dir, 'plugins', 'known_marketplaces.json')
+  );
+  const installed = readJson<{ plugins?: Record<string, unknown> }>(
+    join(dir, 'plugins', 'installed_plugins.json')
+  );
+  if (!markets && !installed) {
+    return { status: 'unknown', marketplace: false, design: false, flow: false };
+  }
+  const marketplace =
+    !!markets &&
+    Object.values(markets).some(
+      (m) => String(m?.source?.repo ?? '').toLowerCase() === '1agh/maude'
+    );
+  const plugins = installed?.plugins ?? {};
+  const has = (key: string): boolean => {
+    const v = plugins[key];
+    return Array.isArray(v) ? v.length > 0 : !!v;
+  };
+  return { status: 'present', marketplace, design: has('design@maude'), flow: has('flow@maude') };
+}
+
+/**
+ * Side-effect-free readiness report. The three binary probes run concurrently so a
+ * fresh machine (where the login-shell fallback fires) resolves in ~one shell round
+ * trip, not three sequential ones. The backing route gates cross-origin callers
+ * (DDR-128 hardening) so this can't be turned into a spawn-storm from a drive-by page.
+ */
+export async function probeReadiness(): Promise<ReadinessReport> {
+  const [claude, maude, agentBrowser] = await Promise.all([
+    (async () => resolveClaudePath() ?? (await resolveOnPath('claude')))(),
+    resolveOnPath('maude'),
+    resolveOnPath('agent-browser'),
+  ]);
+
+  const items: ReadinessItem[] = [];
+
+  items.push({
+    id: 'claude',
+    label: 'Claude Code (the `claude` CLI)',
+    required: true,
+    status: claude ? 'present' : 'missing',
+    detail: claude
+      ? 'Installed — AI editing drives it on your own Pro/Max subscription.'
+      : 'Not found on PATH.',
+    remediation: claude
+      ? undefined
+      : 'Install Claude Code, then run `claude` and `/login` once. AI editing runs on your own Pro/Max subscription — never API billing.',
+  });
+
+  items.push({
+    id: 'maude',
+    label: 'maude CLI',
+    required: true,
+    status: maude ? 'present' : 'missing',
+    detail: maude ? 'On PATH — `/design:edit` can reach its helpers.' : 'Not found on PATH.',
+    remediation: maude
+      ? undefined
+      : 'Install it: `npm i -g @1agh/maude`. `/design:edit` shells out to `maude design …`, so it must be on PATH.',
+  });
+
+  const scan = scanPlugins();
+  const pluginsPresent = scan.design && scan.flow;
+  const pluginStatus: ReadinessStatus =
+    scan.status === 'unknown' ? 'unknown' : pluginsPresent ? 'present' : 'missing';
+  const missing = [!scan.design && 'design@maude', !scan.flow && 'flow@maude']
+    .filter(Boolean)
+    .join(' + ');
+  items.push({
+    id: 'plugins',
+    label: 'Maude plugins in Claude Code',
+    required: true,
+    status: pluginStatus,
+    detail:
+      scan.status === 'unknown'
+        ? "Couldn't read Claude Code's plugin registry — check it manually."
+        : pluginsPresent
+          ? 'design@maude + flow@maude are installed.'
+          : `Missing: ${missing}${scan.marketplace ? '' : ' (and the maude marketplace)'}.`,
+    remediation:
+      pluginStatus === 'present'
+        ? undefined
+        : 'In Claude Code: `/plugin marketplace add 1aGh/maude`, then `/plugin install design@maude` and `/plugin install flow@maude`.',
+  });
+
+  items.push({
+    id: 'agent-browser',
+    label: 'agent-browser (optional)',
+    required: false,
+    status: agentBrowser ? 'present' : 'missing',
+    detail: agentBrowser
+      ? 'Installed — screenshot evidence during edits.'
+      : 'Optional — richer screenshot evidence during edits.',
+    remediation: agentBrowser
+      ? undefined
+      : 'Optional. Install `agent-browser` for screenshot evidence during `/design:edit`.',
+  });
+
+  const ready = items.filter((i) => i.required).every((i) => i.status === 'present');
+  return { ready, items };
+}

package/apps/studio/scaffold-design.ts

@@ -0,0 +1,57 @@
+// scaffold-design.ts — write a minimal, BOOTABLE `.design/` into a folder (Phase 28).
+//
+// Used by two native-app flows: "New project" (create a GitHub repo → init a local
+// project) and the "open a repo with no Maude design system" fallback ("set it up?").
+// It deliberately scaffolds only the MINIMUM the dev-server needs to boot (per
+// context.ts the only hard requirement is a `.design/` dir; config needs just
+// `name` + `designRoot`). A real design system is still created by /design:setup-ds
+// (agent-driven) — this just gets the project to open instead of crash-looping.
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+const CONFIG_SCHEMA =
+  'https://raw.githubusercontent.com/1aGh/maude/main/apps/studio/config.schema.json';
+
+/** Whether `dir` is already a Maude project (has `.design/config.json`). */
+export function hasDesign(dir: string): boolean {
+  return existsSync(join(dir, '.design', 'config.json'));
+}
+
+export interface ScaffoldResult {
+  ok: boolean;
+  error?: string;
+}
+
+/** Scaffold a minimal bootable `.design/` (no design system yet). Refuses to
+ *  clobber an existing project. `name` is the human project label. */
+export function scaffoldDesign(dir: string, name?: string): ScaffoldResult {
+  const designDir = join(dir, '.design');
+  const configPath = join(designDir, 'config.json');
+  if (existsSync(configPath)) {
+    return { ok: false, error: 'This folder is already a Maude project.' };
+  }
+  const projectName = (name && name.trim()) || basename(dir) || 'Untitled';
+  try {
+    mkdirSync(join(designDir, 'ui'), { recursive: true });
+    mkdirSync(join(designDir, 'system'), { recursive: true });
+    const config = {
+      $schema: CONFIG_SCHEMA,
+      name: projectName,
+      designRoot: '.design',
+      canvasGroups: [
+        { label: 'Design system', path: 'system' },
+        { label: 'UI kit', path: 'ui' },
+      ],
+      designSystems: [],
+      completenessProfile: 'standard',
+    };
+    writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+    // Keep the empty group dirs in git so a fresh clone still has the structure.
+    writeFileSync(join(designDir, 'ui', '.gitkeep'), '', 'utf8');
+    writeFileSync(join(designDir, 'system', '.gitkeep'), '', 'utf8');
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : 'Could not set up the project.' };
+  }
+}

package/apps/studio/server.ts

@@ -16,14 +16,17 @@
 
 import { spawn } from 'node:child_process';
 
+import { createAcp } from './acp/index.ts';
 import { createActivity } from './activity.ts';
 import { createApi } from './api.ts';
 import { bootSelfHeal } from './boot-self-heal.ts';
-import { createAiActivity } from './collab/ai-activity.ts';
+import { createCanvasListWatch } from './canvas-list-watch.ts';
+import { type AiActivityEntry, createAiActivity } from './collab/ai-activity.ts';
 import { createGitLifecycle } from './collab/git-lifecycle.ts';
 import { createCollab } from './collab/index.ts';
 import { createContext } from './context.ts';
 import { createFsWatch } from './fs-watch.ts';
+import { createGitWatch } from './git/watch.ts';
 import { createHttp } from './http.ts';
 import { createInspect } from './inspect.ts';
 import { startHeapWatch } from './mem.ts';
@@ -77,11 +80,28 @@ await inspect.load();
 
 collab = createCollab(ctx, api);
 const aiActivity = createAiActivity(ctx);
+
+// Phase 30 — bridge agent `ai-activity` onto the per-canvas room awareness so a
+// remote peer sees "X is editing" cross-machine. The `ai-activity` bus event is
+// loopback-only (inspector WS); awareness is the one channel that crosses the
+// hub. Soft heads-up — projected onto the room's own awareness slot, cleared
+// when the activity ends/expires. No-op when no room is live for the slug.
+ctx.bus.on('ai-activity', (payload: { file: string; entry: AiActivityEntry | null }) => {
+  if (!collab) return;
+  const slug = api.fileSlug(payload.file);
+  collab.registry.setAgentEditing(
+    slug,
+    payload.entry ? { name: payload.entry.author, since: payload.entry.startedAt } : null
+  );
+});
 const gitLifecycle = createGitLifecycle(ctx, collab.registry);
 // Phase 13 / DDR-029 — fs-watch-driven canvas activity overlay. Subscribes to
 // `fs:any` and emits `activity:change`; ws.ts forwards it to canvas iframes.
 const activity = createActivity(ctx);
-const ws = createWs(ctx, api, inspect, collab, activity);
+// Phase 31 (DDR-123) — ACP chat bridge manager. Owns one claude-agent-acp
+// subprocess per /_ws/acp socket; main-origin + loopback only (wired below).
+const acp = createAcp(ctx);
+const ws = createWs(ctx, api, inspect, collab, activity, acp);
 const http = createHttp(ctx, api, inspect, aiActivity);
 const fsWatch = createFsWatch(ctx);
 
@@ -141,6 +161,26 @@ function startServer(port: number): BunServer {
         return new Response('Upgrade failed', { status: 400 });
       }
 
+      // Phase 31 (DDR-123) — ACP chat bridge WS. Main origin ONLY (this server,
+      // never startCanvasServer) and loopback-guarded like collab: the bridge
+      // spawns the user's `claude` and can drive file edits, so the untrusted
+      // canvas origin and remote hosts must never reach it. Checked BEFORE the
+      // generic `/_ws` inspector branch since `/_ws/acp`.startsWith('/_ws').
+      if (pathname === '/_ws/acp') {
+        if (!isLoopbackHost(req.headers.get('host'))) {
+          return new Response('ACP chat is loopback-only', { status: 403 });
+        }
+        const ok = srv.upgrade(req, {
+          data: {
+            id: crypto.randomUUID(),
+            remote: req.headers.get('x-forwarded-for') ?? '127.0.0.1',
+            kind: 'acp',
+          },
+        });
+        if (ok) return undefined as unknown as Response;
+        return new Response('Upgrade failed', { status: 400 });
+      }
+
       // Legacy inspector WS — JSON frames, designer-facing live tab state.
       if (pathname.startsWith('/_ws')) {
         const ok = srv.upgrade(req, {
@@ -339,6 +379,19 @@ await Bun.write(
 fsWatch.start();
 startHeapWatch();
 
+// Phase 27 Task 5 (E2) — live dirty-state. Subscribes to `fs:any` (after
+// fsWatch.start so it sees every event) and broadcasts `git-status` to the shell
+// on each versionable change. No-op for a non-git project (gitStatus → repo:false).
+const gitWatch = createGitWatch(ctx);
+
+// Phase 31 follow-up — external-canvas list watcher. Subscribes to `fs:any` and
+// emits `canvas-list-update` when a canvas file appears/disappears on disk from
+// OUTSIDE the dev-server (ACP agent `/design:new`, agent Write, git checkout),
+// so the browser file tree refreshes without a reload — the symmetric
+// counterpart to api.ts's create/delete emit. RCA:
+// `.ai/logs/rca/issue-acp-new-canvas-not-in-filetree.md`.
+const canvasListWatch = createCanvasListWatch(ctx);
+
 // Phase 9 Task 4 — bidirectional sync agent. No-op when the project isn't
 // linked to a hub (`.design/config.json` has no `linkedHub` field). Kicked
 // off after fsWatch so the agent's bus subscription receives every fs event.
@@ -371,6 +424,16 @@ if (!process.env.NO_OPEN) {
 async function shutdown() {
   console.log('\n  Stopping…');
   fsWatch.stop();
+  try {
+    gitWatch.stop();
+  } catch {
+    /* timer cleanup is best-effort */
+  }
+  try {
+    canvasListWatch.stop();
+  } catch {
+    /* timer cleanup is best-effort */
+  }
   try {
     activity.stop();
   } catch {