@1agh/maude 0.23.0 → 0.25.0

package/cli/lib/gitignore-block.mjs

@@ -0,0 +1,90 @@
+// Maude design-runtime .gitignore block — Phase 9 Task 9 (gitignore strategy).
+//
+// Single `full` strategy in v1.1 (DDR-056): canvases + their JSON snapshots
+// stay in git (cold backup, PR-reviewable .html diffs, bootstrap-from-clone),
+// while regenerable per-machine runtime state is ignored — even in linked mode.
+//
+// The rules live between `# maude:begin` / `# maude:end` markers so the writer
+// is idempotent: re-running replaces the block in place (never duplicates), and
+// anything the user authored outside the markers is untouched. `maude design
+// unlink` deliberately leaves the block — the rules are harmless in solo mode
+// (the ignored files just don't get created).
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+export const BEGIN_MARKER = '# maude:begin';
+export const END_MARKER = '# maude:end';
+
+/**
+ * The runtime paths Maude ignores under the design root, relative to repo root.
+ * `designRel` defaults to `.design` (the only design root in v1.1 defaults).
+ */
+export function buildBlock(designRel = '.design') {
+  const root = designRel.replace(/\/+$/, '');
+  const lines = [
+    BEGIN_MARKER,
+    '# Maude design plugin runtime — gitignored even in linked mode (DDR-056).',
+    `${root}/_state/`, // binary CRDT logs (regenerable from hub)
+    `${root}/_server.json`,
+    `${root}/_server.log`,
+    `${root}/_active.json`,
+    `${root}/_sync.json`, // linked-mode offline/sync status (Task 8)
+    `${root}/_history/`,
+    `${root}/_canvas-state/`, // per-machine canvas undo/redo + scratch state
+    `${root}/_chat/`, // ACP transcripts (per-machine)
+    END_MARKER,
+  ];
+  return `${lines.join('\n')}\n`;
+}
+
+/** True when the file already contains a maude-managed block. */
+export function hasBlock(contents) {
+  return contents.includes(BEGIN_MARKER) && contents.includes(END_MARKER);
+}
+
+/**
+ * Replace the existing maude block in `contents`, or append a fresh one.
+ * Pure — returns the new file text. Preserves everything outside the markers.
+ */
+export function applyBlock(contents, block) {
+  if (!hasBlock(contents)) {
+    // Append with a single blank-line separator (avoid leading newline on an
+    // empty file; avoid double-blank when the file already ends in a newline).
+    if (contents.length === 0) return block;
+    const sep = contents.endsWith('\n') ? '\n' : '\n\n';
+    return `${contents}${sep}${block}`;
+  }
+  const begin = contents.indexOf(BEGIN_MARKER);
+  const endIdx = contents.indexOf(END_MARKER);
+  const after = endIdx + END_MARKER.length;
+  // Consume one trailing newline after END so we don't accumulate blank lines.
+  const tail = contents.slice(after).replace(/^\n/, '');
+  const head = contents.slice(0, begin);
+  return `${head}${block}${tail ? `\n${tail}` : ''}`;
+}
+
+/**
+ * Write (or refresh) the maude block in `<repoRoot>/.gitignore`.
+ *
+ * @param {string} repoRoot
+ * @param {{ designRel?: string, dryRun?: boolean }} [opts]
+ * @returns {{ action: 'created' | 'updated' | 'unchanged', path: string }}
+ */
+export function writeGitignoreBlock(repoRoot, { designRel = '.design', dryRun = false } = {}) {
+  const path = resolve(repoRoot, '.gitignore');
+  const existed = existsSync(path);
+  const current = existed ? readFileSync(path, 'utf8') : '';
+  const block = buildBlock(designRel);
+  const next = applyBlock(current, block);
+
+  let action;
+  if (!existed) action = 'created';
+  else if (next === current) action = 'unchanged';
+  else action = 'updated';
+
+  if (!dryRun && next !== current) {
+    writeFileSync(path, next, 'utf8');
+  }
+  return { action, path };
+}

package/cli/lib/gitignore-block.test.mjs

@@ -0,0 +1,123 @@
+// gitignore-block helper tests — Phase 9 Task 9 (DDR-056).
+
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+
+import {
+  BEGIN_MARKER,
+  END_MARKER,
+  applyBlock,
+  buildBlock,
+  hasBlock,
+  writeGitignoreBlock,
+} from './gitignore-block.mjs';
+
+function withRepo(fn) {
+  const dir = mkdtempSync(join(tmpdir(), 'maude-gitignore-'));
+  try {
+    return fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test('buildBlock includes the runtime paths and is marker-wrapped', () => {
+  const block = buildBlock('.design');
+  assert.ok(block.startsWith(BEGIN_MARKER));
+  assert.ok(block.trimEnd().endsWith(END_MARKER));
+  for (const p of [
+    '.design/_state/',
+    '.design/_server.json',
+    '.design/_active.json',
+    '.design/_sync.json',
+    '.design/_history/',
+    '.design/_chat/',
+  ]) {
+    assert.ok(block.includes(p), `missing ${p}`);
+  }
+  // Committed artifacts must NOT be ignored.
+  assert.ok(!block.includes('.design/config.json'));
+  assert.ok(!/\.design\/\*\.html/.test(block));
+});
+
+test('buildBlock honors a custom design root', () => {
+  const block = buildBlock('design');
+  assert.ok(block.includes('design/_server.json'));
+  assert.ok(!block.includes('.design/_server.json'));
+});
+
+test('writeGitignoreBlock creates .gitignore when absent', () => {
+  withRepo((dir) => {
+    const { action, path } = writeGitignoreBlock(dir);
+    assert.equal(action, 'created');
+    const text = readFileSync(path, 'utf8');
+    assert.ok(hasBlock(text));
+  });
+});
+
+test('writeGitignoreBlock is idempotent — second run is unchanged', () => {
+  withRepo((dir) => {
+    writeGitignoreBlock(dir);
+    const first = readFileSync(join(dir, '.gitignore'), 'utf8');
+    const { action } = writeGitignoreBlock(dir);
+    const second = readFileSync(join(dir, '.gitignore'), 'utf8');
+    assert.equal(action, 'unchanged');
+    assert.equal(first, second);
+    // Exactly one block — no duplication.
+    assert.equal(first.split(BEGIN_MARKER).length - 1, 1);
+  });
+});
+
+test('writeGitignoreBlock preserves user content outside the markers', () => {
+  withRepo((dir) => {
+    const userContent = 'node_modules/\n*.log\n.env\n';
+    writeFileSync(join(dir, '.gitignore'), userContent);
+    writeGitignoreBlock(dir);
+    const text = readFileSync(join(dir, '.gitignore'), 'utf8');
+    assert.ok(text.includes('node_modules/'));
+    assert.ok(text.includes('.env'));
+    assert.ok(hasBlock(text));
+  });
+});
+
+test('writeGitignoreBlock updates an existing block in place (no duplication)', () => {
+  withRepo((dir) => {
+    // Seed a stale block with a different design root.
+    const stale = `keep-me\n${buildBlock('olddesign')}trailing\n`;
+    writeFileSync(join(dir, '.gitignore'), stale);
+    const { action } = writeGitignoreBlock(dir, { designRel: '.design' });
+    assert.equal(action, 'updated');
+    const text = readFileSync(join(dir, '.gitignore'), 'utf8');
+    assert.equal(text.split(BEGIN_MARKER).length - 1, 1, 'still exactly one block');
+    assert.ok(text.includes('.design/_server.json'));
+    assert.ok(!text.includes('olddesign/_server.json'));
+    assert.ok(text.includes('keep-me'));
+    assert.ok(text.includes('trailing'));
+  });
+});
+
+test('writeGitignoreBlock --dry-run does not touch disk', () => {
+  withRepo((dir) => {
+    const { action } = writeGitignoreBlock(dir, { dryRun: true });
+    assert.equal(action, 'created');
+    // File was not actually written.
+    assert.throws(() => readFileSync(join(dir, '.gitignore'), 'utf8'));
+  });
+});
+
+test('applyBlock appends to a file lacking a trailing newline cleanly', () => {
+  const out = applyBlock('a\nb', buildBlock('.design'));
+  assert.ok(out.includes('a\nb'));
+  assert.ok(hasBlock(out));
+  // No run-together: marker starts on its own line.
+  assert.ok(out.includes(`\n${BEGIN_MARKER}`));
+});
+
+test('hasBlock detects both markers', () => {
+  assert.ok(hasBlock(`x\n${BEGIN_MARKER}\ny\n${END_MARKER}\n`));
+  assert.ok(!hasBlock('just user content'));
+  assert.ok(!hasBlock(BEGIN_MARKER)); // begin without end
+});

package/cli/lib/plugin-cli-reachability.test.mjs

@@ -0,0 +1,56 @@
+// DDR-061 + DDR-062 regression guard.
+//
+// DDR-061: a plugin must NEVER invoke a `cli/lib/*.mjs` module by a relative
+// path unconditionally: in a marketplace install the plugin is copied alone into
+// `cache/<marketplace>/<plugin>/<version>/`, so the sibling `cli/` does not
+// exist and the call crashes with MODULE_NOT_FOUND. The reachable contract is
+// the on-PATH `maude` binary (a declared plugin dependency).
+//
+// So any plugin file that runs `node … cli/lib/<x>.mjs` is only allowed when the
+// SAME file also offers a `command -v maude` fallback (the sibling-first /
+// maude-fallback pattern). This test fails loudly if a new straggler lands.
+//
+// DDR-062: plugin MARKDOWN must reach the dev-server bash helpers through
+// `maude design <verb>`, never `bash "$CLAUDE_PLUGIN_ROOT/dev-server/bin/<x>.sh"`.
+// The marketplace never copies the dev-server beside a plugin, and a flow
+// command's $CLAUDE_PLUGIN_ROOT points at plugins/flow (no dev-server/ at all).
+// Prose mentions of the path are fine; INVOCATIONS (bash/sh/exec/$( prefixed)
+// are banned.
+
+import assert from 'node:assert/strict';
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { test } from 'node:test';
+
+test('no plugin runs `node cli/lib/*.mjs` without an on-PATH maude fallback', () => {
+  const out = execSync(
+    String.raw`grep -rlE 'node[^\n]*cli/lib/[a-z0-9_-]+\.mjs' plugins/ || true`,
+    {
+      encoding: 'utf8',
+    }
+  );
+  const files = out.trim().split('\n').filter(Boolean);
+  const offenders = files.filter((f) => !/command -v maude/.test(readFileSync(f, 'utf8')));
+  assert.deepEqual(
+    offenders,
+    [],
+    `These plugin files invoke a relative cli/lib module with no \`command -v maude\` fallback — they will crash in a marketplace install (DDR-061). Route through \`maude <subcommand>\` or guard with a sibling-exists check + maude fallback:\n  ${offenders.join('\n  ')}`
+  );
+});
+
+test('no plugin markdown invokes a $CLAUDE_PLUGIN_ROOT/dev-server/bin/*.sh helper (DDR-062)', () => {
+  // INVOCATION = the bin path preceded by bash / sh / exec, or inside a $(…)
+  // command substitution. Prose mentions of the path (backtick-wrapped, no verb)
+  // are exempt — they don't run anything. Matches both the $CLAUDE_PLUGIN_ROOT
+  // form and the repo-relative `plugins/<x>/dev-server/bin/` form.
+  const pattern = String.raw`(bash|sh|exec) +"?(\$\{?CLAUDE_PLUGIN_ROOT\}?|plugins/[a-z]+)/dev-server/bin/[A-Za-z0-9_-]+\.sh|\$\("?\$?\{?CLAUDE_PLUGIN_ROOT\}?/dev-server/bin/[A-Za-z0-9_-]+\.sh`;
+  const out = execSync(`grep -rnE '${pattern}' plugins --include='*.md' || true`, {
+    encoding: 'utf8',
+  });
+  const hits = out.trim().split('\n').filter(Boolean);
+  assert.deepEqual(
+    hits,
+    [],
+    `These plugin markdown lines INVOKE a dev-server bin helper directly — they break in marketplace installs (the dev-server is never copied beside a plugin) and in flow commands (whose $CLAUDE_PLUGIN_ROOT has no dev-server/). Route through \`maude design <verb>\` instead (DDR-062):\n  ${hits.join('\n  ')}`
+  );
+});

package/cli/lib/preflight.mjs

@@ -12,7 +12,7 @@
 // because every consumer wants the same table format.
 
 import { spawnSync } from 'node:child_process';
-import { readFile } from 'node:fs/promises';
+import { readFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 
 const SEM_RE = /(\d+)\.(\d+)\.(\d+)/;
@@ -172,10 +172,11 @@ function colorFor(g) {
 // ─── CLI entry — `node cli/lib/preflight.mjs --plugin design --json` ──────
 
 function parseFlags(args) {
-  const out = { plugin: null, mode: 'text' };
+  const out = { plugin: null, mode: 'text', cache: null };
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === '--plugin') out.plugin = args[++i];
+    else if (a === '--cache') out.cache = args[++i];
     else if (a === '--json') out.mode = 'json';
     else if (a === '--shell-export') out.mode = 'shell-export';
     else if (a === '--quiet') out.mode = 'quiet';
@@ -184,17 +185,46 @@ function parseFlags(args) {
   return out;
 }
 
-function manifestPathForPlugin(pluginName) {
-  return resolve(`plugins/${pluginName}/dependencies.json`);
+// Cross-command short-circuit cache (Phase A, Task A15). Written after a
+// successful check so sibling commands within the freshness window skip the
+// whole preflight. Path is caller-supplied (design → <designRoot>/_preflight.json,
+// flow → .ai/state/_preflight.json) because this lib runs with cwd = the maude
+// package root when shelled from preflight.sh, not the target repo.
+async function writeCache(cachePath, env) {
+  const payload = {
+    checked: new Date().toISOString(),
+    plugin: env.plugin,
+    all_hard_pass: env.summary.allHardPass,
+    soft_warnings: env.results
+      .filter((r) => r.hardness === 'soft' && r.status === 'missing')
+      .map((r) => r.id),
+  };
+  try {
+    await writeFile(resolve(cachePath), `${JSON.stringify(payload, null, 2)}\n`);
+  } catch {
+    // Cache is a best-effort optimization; a write failure (read-only FS,
+    // missing parent dir) must never break the preflight itself.
+  }
+}
+
+function manifestPathForPlugin(pluginName, pkgRoot = process.cwd()) {
+  return resolve(pkgRoot, 'plugins', pluginName, 'dependencies.json');
 }
 
-async function main(argv) {
-  const flags = parseFlags(argv.slice(2));
+// Shared runnable for both the `maude preflight` command and the direct
+// `node cli/lib/preflight.mjs` entry. `pkgRoot` is where `plugins/<x>/
+// dependencies.json` lives (the maude package root) — resolved independently
+// of the caller's cwd, so the command works from any target repo. (DDR-061:
+// the marketplace install has no sibling cli/, so callers reach this through
+// the on-PATH `maude` binary, which passes its own package root as pkgRoot.)
+export async function runPreflight({ args, pkgRoot = process.cwd() }) {
+  const flags = parseFlags(args);
   if (!flags.plugin) {
-    process.stderr.write('preflight.mjs: pass --plugin <design|flow>\n');
+    process.stderr.write('preflight: pass --plugin <design|flow>\n');
     process.exit(2);
   }
-  const env = await checkAll(manifestPathForPlugin(flags.plugin));
+  const env = await checkAll(manifestPathForPlugin(flags.plugin, pkgRoot));
+  if (flags.cache) await writeCache(flags.cache, env);
   if (flags.mode === 'json') {
     process.stdout.write(`${JSON.stringify(env, null, 2)}\n`);
   } else if (flags.mode === 'shell-export') {
@@ -223,9 +253,10 @@ async function main(argv) {
   process.exit(env.summary.allHardPass ? 0 : 1);
 }
 
-// Entry guard — only run main() when invoked directly.
+// Entry guard — only run when invoked directly (`node cli/lib/preflight.mjs`).
+// The package root is the cwd here (preflight.sh `cd`s to it before exec).
 if (import.meta.url === `file://${process.argv[1]}`) {
-  main(process.argv).catch((err) => {
+  runPreflight({ args: process.argv.slice(2), pkgRoot: process.cwd() }).catch((err) => {
     process.stderr.write(`preflight: ${err.message}\n`);
     process.exit(1);
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1agh/maude",
-  "version": "0.23.0",
+  "version": "0.25.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 && bash plugins/design/dev-server/bin/check-runtime-bundles.sh"
   },
   "optionalDependencies": {
-    "@1agh/maude-darwin-arm64": "0.23.0",
-    "@1agh/maude-darwin-x64": "0.23.0",
-    "@1agh/maude-linux-arm64": "0.23.0",
-    "@1agh/maude-linux-arm64-musl": "0.23.0",
-    "@1agh/maude-linux-x64": "0.23.0",
-    "@1agh/maude-linux-x64-musl": "0.23.0",
-    "@1agh/maude-win32-x64": "0.23.0"
+    "@1agh/maude-darwin-arm64": "0.25.0",
+    "@1agh/maude-darwin-x64": "0.25.0",
+    "@1agh/maude-linux-arm64": "0.25.0",
+    "@1agh/maude-linux-arm64-musl": "0.25.0",
+    "@1agh/maude-linux-x64": "0.25.0",
+    "@1agh/maude-linux-x64-musl": "0.25.0",
+    "@1agh/maude-win32-x64": "0.25.0"
   },
   "files": [
     "cli",

package/plugins/design/dependencies.json

@@ -94,10 +94,38 @@
         "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"],
+      "fallbackBehavior": "Screenshot scripts use playwright as a fallback when agent-browser is missing. The rendered export formats (PNG/PDF/SVG/HTML/PPTX/Canva) require it outright. NOTE: the `--version` check above only proves the npm package resolves — the Chromium BINARY is a separate install (`npx playwright install chromium`). If it's missing, exports fail at runtime with an actionable message from dev-server/bin/_pw-launch.mjs; screenshot helpers fall back to agent-browser.",
+      "usedBy": [
+        "dev-server/bin/_pw-launch.mjs",
+        "dev-server/bin/_screenshot-playwright.mjs",
+        "dev-server/bin/_png-playwright.mjs",
+        "dev-server/bin/_pdf-playwright.mjs",
+        "dev-server/bin/_svg-playwright.mjs",
+        "dev-server/bin/_html-playwright.mjs",
+        "dev-server/bin/_pptx-playwright.mjs",
+        "dev-server/bin/_enumerate-artboards-playwright.mjs",
+        "dev-server/bin/screenshot.sh"
+      ],
       "docsUrl": "https://playwright.dev"
     },
+    {
+      "id": "svg2pptx",
+      "type": "cli",
+      "hardness": "soft",
+      "check": {
+        "command": "svg2pptx --version",
+        "expectExit": 0
+      },
+      "install": {
+        "preferred": "pip install svg2pptx",
+        "darwin": "pipx install svg2pptx || python3 -m pip install svg2pptx",
+        "linux": "pipx install svg2pptx || python3 -m pip install svg2pptx"
+      },
+      "autoInstall": false,
+      "fallbackBehavior": "PPTX/Canva export uses svg2pptx (Python) to emit NATIVE, editable PowerPoint shapes + text boxes from the artboard SVG — editable in PowerPoint / Keynote / Canva. Without it (or python3), export falls back to a non-editable PNG-per-slide deck (faithful, universal, Canva-safe). Set MAUDE_SVG2PPTX to a custom svg2pptx executable (e.g. a venv path, or `python3 -m svg2pptx`) when it isn't on PATH. See DDR-069.",
+      "usedBy": ["dev-server/exporters/pptx.ts"],
+      "docsUrl": "https://github.com/benouinirachid/svg2pptx"
+    },
     {
       "id": "maude",
       "type": "cli",

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

@@ -41,8 +41,8 @@ const BANNER_CSS = `
   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));
+  color: var(--maude-chrome-fg-0, #111);
+  border: 1px solid var(--maude-chrome-border, 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);