@1agh/maude 0.60.2 → 0.60.3

package/cli/lib/gitignore-drift.mjs

@@ -0,0 +1,149 @@
+// Is this repo's .gitignore telling git to drop content Maude calls VERSIONED?
+//
+// THE FAILURE THIS DETECTS. DDR-115 splits the design root in two: per-machine
+// runtime state is ignored, and durable project content (`*.tsx`,
+// `*.meta.json`, `*.annotations.svg`, `system/**`, `config.json`) is committed.
+// `gitignore-block.mjs` encodes that — the versioned paths are "deliberately
+// absent" from the block it writes. But that block lives between
+// `# maude:begin` / `# maude:end` markers and `applyBlock` only ever replaces
+// what is BETWEEN them, so a rule sitting OUTSIDE the markers is invisible to
+// it, forever.
+//
+// Observed in a real project (Brno Alligators, 2026-08-13): a hand-authored
+// pre-markers block carried `.design/*.annotations.svg`, copied from a v1.0
+// planning document that predates the DDR-115 correction. Consequence: not one
+// annotation sidecar had ever been committed. The draw layer was live in both
+// UIs and absent from every clone, every backup and every PR — and nothing
+// anywhere said so, because each half was behaving exactly as written. Maude
+// believed the file was versioned; git had been told otherwise years earlier.
+//
+// WHY DETECTION AND NOT SILENT SURGERY. The obvious "fix" is to make the block
+// writer delete offending lines. It must not: those lines are OUTSIDE our
+// markers, which is precisely the region the writer promises never to touch
+// ("anything the user authored outside the markers is untouched"). A tool that
+// quietly edits a person's hand-written gitignore on every `maude design link`
+// is a worse bug than the one it closes. So this module only ever REPORTS, and
+// removal is an explicit `maude doctor --fix` — the surface whose whole contract
+// is that it is never silent.
+
+/**
+ * Design-root-relative patterns that name VERSIONED content.
+ *
+ * Kept as literal shapes rather than a glob engine on purpose: this decides
+ * whether to propose deleting a line from somebody's `.gitignore`, and a clever
+ * matcher that is right 95 % of the time is not good enough for that. Every
+ * entry here is a rule that CANNOT be legitimate under DDR-115 — matching one is
+ * proof of drift, not a heuristic. Mirrors the "deliberately absent" list in
+ * `gitignore-block.mjs` and the taxonomy in `apps/studio/git/service.ts`.
+ */
+const VERSIONED_PATTERNS = [
+  { pattern: '*.annotations.svg', what: 'canvas draw layers (annotations)' },
+  { pattern: '*.meta.json', what: 'canvas sidecars (layout, artboards, tags)' },
+  { pattern: '*.tsx', what: 'canvas bodies' },
+  { pattern: 'config.json', what: 'the project design config' },
+  { pattern: 'system', what: 'the design system' },
+  { pattern: 'system/', what: 'the design system' },
+  { pattern: 'system/**', what: 'the design system' },
+];
+
+/** One `.gitignore` line that ignores versioned content. */
+/**
+ * @typedef {object} GitignoreDrift
+ * @property {number} line     1-indexed line number in `.gitignore`
+ * @property {string} text     the offending line, verbatim
+ * @property {string} pattern  the design-root-relative shape it matched
+ * @property {string} what     plain-language name of what it drops
+ */
+
+/**
+ * Find rules that ignore VERSIONED design content.
+ *
+ * SCOPED TO THE DESIGN ROOT. Only lines that explicitly name the design root
+ * (`.design/*.annotations.svg`) are considered. A bare `*.tsx` at the repo root
+ * is a decision about a whole codebase — very possibly deliberate, and never
+ * ours to second-guess from here.
+ *
+ * NEGATIONS ARE NOT DRIFT. A `!` line RE-INCLUDES a path; it is the fix, not the
+ * fault. Comments and blank lines are skipped.
+ *
+ * Lines INSIDE the `# maude:begin` / `# maude:end` markers are skipped too: that
+ * region is generated, so anything wrong there is a bug in the generator and is
+ * corrected by re-running it, not by editing a person's file.
+ *
+ * @param {string} contents  raw `.gitignore` text ('' when absent)
+ * @param {string} designRel design root relative to the repo root
+ * @returns {GitignoreDrift[]}
+ */
+export function findGitignoreDrift(contents, designRel = '.design') {
+  const root = String(designRel ?? '.design')
+    .replace(/^\.\//, '')
+    .replace(/^\/+|\/+$/g, '');
+  if (!root) return [];
+  /** @type {GitignoreDrift[]} */
+  const out = [];
+  let inBlock = false;
+  const lines = String(contents ?? '').split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const text = raw.trim();
+    if (text === '# maude:begin') {
+      inBlock = true;
+      continue;
+    }
+    if (text === '# maude:end') {
+      inBlock = false;
+      continue;
+    }
+    if (inBlock || !text || text.startsWith('#') || text.startsWith('!')) continue;
+    // Anchor and trailing-slash forms are the same rule to git.
+    const body = text.replace(/^\/+/, '').replace(/\/+$/, '');
+    if (body === root) continue; // ignoring the WHOLE design root is a choice, not drift
+    if (!body.startsWith(`${root}/`)) continue;
+    // Normalise BOTH sides the same way, or the comparison silently never
+    // matches: `system/**` was stripped to `system` on the pattern side only, so
+    // a real `.design/system/**` rule — a shape this module lists as versioned —
+    // was reported clean. A detector that quietly covers less than it claims is
+    // worse than one that covers less openly.
+    const norm = (s) => s.replace(/\/+$/, '').replace(/\/\*\*$/, '');
+    const rel = norm(body.slice(root.length + 1));
+    const hit = VERSIONED_PATTERNS.find((p) => rel === norm(p.pattern));
+    if (hit) out.push({ line: i + 1, text, pattern: hit.pattern, what: hit.what });
+  }
+  return out;
+}
+
+/**
+ * Remove the drifting lines, and only those.
+ *
+ * Deletes whole lines by NUMBER, taken from a `findGitignoreDrift` run over the
+ * same text — never by re-matching, so what is removed is exactly what was
+ * reported to the person who approved it. Everything else, including their
+ * comments and their blank lines, survives byte-for-byte.
+ *
+ * @param {string} contents
+ * @param {GitignoreDrift[]} drift
+ * @returns {string}
+ */
+export function removeGitignoreDrift(contents, drift) {
+  if (!drift?.length) return contents;
+  const drop = new Set(drift.map((d) => d.line));
+  return String(contents ?? '')
+    .split('\n')
+    .filter((_, i) => !drop.has(i + 1))
+    .join('\n');
+}
+
+/**
+ * One line per finding, for the report.
+ *
+ * Names the CONSEQUENCE, not the rule: "your annotations are never committed"
+ * is what the person needs to hear. The rule is already on screen.
+ *
+ * @param {GitignoreDrift[]} drift
+ * @returns {string[]}
+ */
+export function describeGitignoreDrift(drift) {
+  return (drift ?? []).map(
+    (d) => `.gitignore:${d.line}  ${d.text}  — drops ${d.what} from git (DDR-115 says versioned)`
+  );
+}

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

@@ -0,0 +1,156 @@
+// Gitignore drift — the check that catches git dropping VERSIONED design work.
+//
+// The case that produced this file, verbatim from a real project: a
+// hand-authored pre-markers block carrying `.design/*.annotations.svg`, copied
+// from a v1.0 planning document that predates the DDR-115 correction. Not one
+// annotation sidecar had ever been committed. Both UIs rendered the draw layer;
+// no clone, backup or PR contained it; nothing said so.
+//
+// What is pinned here is mostly the NEGATIVE space. A detector that proposes
+// deleting lines from somebody's hand-written `.gitignore` is only as good as
+// its refusals, so most of these tests assert what it must NOT flag.
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import {
+  describeGitignoreDrift,
+  findGitignoreDrift,
+  removeGitignoreDrift,
+} from './gitignore-drift.mjs';
+
+test('finds the real-world case: annotations ignored outside the markers', () => {
+  const gitignore = [
+    'node_modules/',
+    '',
+    '# design plugin dev-server runtime state',
+    '.design/_active.json',
+    '.design/_history/',
+    '.design/*.annotations.svg',
+    '.design/_chat/',
+  ].join('\n');
+  const drift = findGitignoreDrift(gitignore, '.design');
+  assert.equal(drift.length, 1);
+  assert.equal(drift[0].line, 6);
+  assert.equal(drift[0].text, '.design/*.annotations.svg');
+  assert.match(drift[0].what, /annotations/);
+});
+
+test('the runtime-state block is NOT drift — those paths are ignored by design', () => {
+  // Every line the block writer itself emits must come back clean, or the check
+  // would tell people to un-ignore their own `_history/` on every run.
+  const gitignore = [
+    '.design/_server.json',
+    '.design/_active.json',
+    '.design/_active.*.json',
+    '.design/_sync.json',
+    '.design/_history/',
+    '.design/_trash/',
+    '.design/_comments/',
+    '.design/_canvas-state/',
+    '.design/_untrusted/',
+    '.design/assets/',
+  ].join('\n');
+  assert.deepEqual(findGitignoreDrift(gitignore, '.design'), []);
+});
+
+test('lines INSIDE the maude block are skipped — a generator bug is fixed by the generator', () => {
+  const gitignore = [
+    '# maude:begin',
+    '.design/*.annotations.svg',
+    '# maude:end',
+    '.design/_history/',
+  ].join('\n');
+  assert.deepEqual(findGitignoreDrift(gitignore, '.design'), []);
+});
+
+test('a negation is the fix, not the fault', () => {
+  const gitignore = ['.design/', '!.design/*.annotations.svg'].join('\n');
+  assert.deepEqual(findGitignoreDrift(gitignore, '.design'), []);
+});
+
+test('comments and blank lines are not rules', () => {
+  const gitignore = ['', '# .design/*.annotations.svg', '   ', '#.design/*.tsx'].join('\n');
+  assert.deepEqual(findGitignoreDrift(gitignore, '.design'), []);
+});
+
+test('ignoring the WHOLE design root is a choice we do not second-guess', () => {
+  // Somebody who ignores `.design/` outright has decided their design work is
+  // not in this repo. That is coherent; flagging it would be nagging.
+  for (const line of ['.design', '.design/', '/.design/']) {
+    assert.deepEqual(findGitignoreDrift(line, '.design'), [], line);
+  }
+});
+
+test('a repo-wide rule is out of scope — it is a decision about a whole codebase', () => {
+  // `*.tsx` at the repo root is very possibly deliberate and is not ours to
+  // reinterpret from inside a design-tool diagnostic.
+  const gitignore = ['*.tsx', 'config.json', '*.meta.json'].join('\n');
+  assert.deepEqual(findGitignoreDrift(gitignore, '.design'), []);
+});
+
+test('a non-default design root is honoured', () => {
+  const gitignore = ['design/*.annotations.svg', '.design/*.annotations.svg'].join('\n');
+  const drift = findGitignoreDrift(gitignore, 'design');
+  assert.equal(drift.length, 1);
+  assert.equal(drift[0].line, 1);
+});
+
+test('anchors and trailing slashes are the same rule to git', () => {
+  const drift = findGitignoreDrift('/.design/system/', '.design');
+  assert.equal(drift.length, 1);
+  assert.match(drift[0].what, /design system/);
+});
+
+test('every versioned shape is covered, none of the runtime ones', () => {
+  const versioned = [
+    '.design/*.annotations.svg',
+    '.design/*.meta.json',
+    '.design/*.tsx',
+    '.design/config.json',
+    '.design/system/',
+    // The glob form. Both sides of the comparison must be normalised the same
+    // way — normalising only the pattern made this shape report clean while the
+    // module listed it as covered.
+    '.design/system/**',
+  ];
+  assert.equal(findGitignoreDrift(versioned.join('\n'), '.design').length, versioned.length);
+});
+
+test('removal deletes exactly the reported lines, byte-for-byte otherwise', () => {
+  const gitignore = [
+    'node_modules/',
+    '',
+    '# my own comment',
+    '.design/*.annotations.svg',
+    '.design/_history/',
+  ].join('\n');
+  const drift = findGitignoreDrift(gitignore, '.design');
+  const next = removeGitignoreDrift(gitignore, drift);
+  assert.equal(
+    next,
+    ['node_modules/', '', '# my own comment', '.design/_history/'].join('\n'),
+    'the user comment and the blank line survive'
+  );
+  // And the result is clean on a re-run — the fix converges.
+  assert.deepEqual(findGitignoreDrift(next, '.design'), []);
+});
+
+test('removal with no drift is a byte-identical no-op', () => {
+  const gitignore = 'node_modules/\n.design/_history/\n';
+  assert.equal(removeGitignoreDrift(gitignore, []), gitignore);
+  assert.equal(removeGitignoreDrift(gitignore, undefined), gitignore);
+});
+
+test('an absent or empty gitignore is not drift', () => {
+  assert.deepEqual(findGitignoreDrift('', '.design'), []);
+  assert.deepEqual(findGitignoreDrift(undefined, '.design'), []);
+});
+
+test('the description names the consequence, not just the rule', () => {
+  const drift = findGitignoreDrift('.design/*.annotations.svg', '.design');
+  const [line] = describeGitignoreDrift(drift);
+  assert.match(line, /\.gitignore:1/);
+  assert.match(line, /drops/);
+  assert.match(line, /DDR-115/);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1agh/maude",
-  "version": "0.60.2",
+  "version": "0.60.3",
   "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": {
@@ -54,13 +54,13 @@
     "test:e2e:desktop:parity:cloud": "pnpm --filter @maude/desktop-e2e e2e:parity:cloud"
   },
   "optionalDependencies": {
-    "@1agh/maude-darwin-arm64": "0.60.2",
-    "@1agh/maude-darwin-x64": "0.60.2",
-    "@1agh/maude-linux-arm64": "0.60.2",
-    "@1agh/maude-linux-arm64-musl": "0.60.2",
-    "@1agh/maude-linux-x64": "0.60.2",
-    "@1agh/maude-linux-x64-musl": "0.60.2",
-    "@1agh/maude-win32-x64": "0.60.2"
+    "@1agh/maude-darwin-arm64": "0.60.3",
+    "@1agh/maude-darwin-x64": "0.60.3",
+    "@1agh/maude-linux-arm64": "0.60.3",
+    "@1agh/maude-linux-arm64-musl": "0.60.3",
+    "@1agh/maude-linux-x64": "0.60.3",
+    "@1agh/maude-linux-x64-musl": "0.60.3",
+    "@1agh/maude-win32-x64": "0.60.3"
   },
   "files": [
     "cli",