@tonycodes-ui/mortar 0.0.0-stage → 0.11.0

package/TESTING.md

@@ -0,0 +1,83 @@
+# Component test contract
+
+Mortar tests observable behaviour, not a line-coverage percentage. Everything here runs locally without a service account. CI requires the same checks against a production playground build.
+
+```sh
+npm ci
+npm run check
+npx playwright install chromium
+npm run test:browser
+npm run test:visual
+```
+
+`npm run check` never rewrites the catalogue: drift fails M007 (a source or preview fingerprint changed) or M008 (the catalogue no longer matches the manifests). Review the change that caused it, then run `npm run catalog`. It regenerates catalog.json and prints which components' fingerprints and contracts changed, so you can confirm the list matches what you meant to change. Formatting source after regeneration requires regenerating again. Never regenerate first: that accepts drift without looking at it.
+
+Each browser command builds the playground before serving it. CI sets `MORTAR_PLAYGROUND_PREBUILT=1` so both suites serve the `playground-dist` that `npm run check` already built; set it locally to skip the rebuild when that build is current.
+
+`npm test` builds `dist` and runs the node tests. They import the built package, so a single file run with `node --test` refuses a `dist` older than `src` (tests/support/render.mjs).
+
+## Manifests and the catalogue
+
+Manifests hold only the hand-written contract. `npm run catalog` generates the rest into catalog.json, so a shared change never rewrites every manifest:
+
+- `version`: the package version, on the catalogue and on every entry.
+- `integrity`: separate source and preview hashes of the local import closures; source identity also includes shared styles. They identify changes, not approval or a security signature.
+- `contract.propTypes`: for every prop the component itself declares (inherited DOM attributes are omitted), `{ type, required, default? }` from the TypeScript checker. Literal unions and aliases such as `Tone` are expanded and sorted. `contract.props` stays the human-readable description; `tests/manifest-props.test.mjs` fails when a declared prop is undocumented, a documented prop does not exist, or a documented union or prop kind differs from TypeScript.
+- `capabilities`: `theme` and the kit for every component, `keyboard` when it has a registered interaction probe and `responsive` for the composite profile, plus what the manifest declares from the closed vocabulary in `scripts/test-contract.mjs` (`action`, `input`, `validation`, `form`, `navigation`, `status`, `summary`, `table`, and `keyboard` or `responsive` where they are not already derived). Declaring a derived or unknown capability fails M006.
+- `provenance`: `{ kitId, exampleId }`, derived from `kitId`.
+
+`contract.dependencies` stays hand-written but must list exactly the catalogue components the source renders, following local helpers and contexts that require a provider (M010).
+
+Catalogue shape changes for consumers that read only catalog.json, such as agent tooling and indexers: `contract.propTypes` is new; `contract.states` is removed (it was the same five labels on every component; tested scenarios are `testing.states`); `provenance.sourceDigest` is removed (it was never read); `capabilities` is now complete and ordered (`theme`, kit, then vocabulary order). Every other field keeps its meaning.
+
+## Every component
+
+Each manifest has a `testing` contract. `target` identifies actual rendered component content inside the preview root, not the catalogue controls. Overlay targets initially identify their opener; the mandatory overlay probe then requires an open dialog. The playground resolves the manifest's exact preview path. A missing component, empty fixture, fallback notice, console error or JavaScript exception fails the harness.
+
+Modal's contract, for example:
+
+```json
+{
+  "testing": {
+    "profile": "overlay",
+    "target": ".m-button",
+    "probe": "dialog",
+    "states": []
+  }
+}
+```
+
+| Profile   | Required execution                                                                                             |
+| --------- | -------------------------------------------------------------------------------------------------------------- |
+| display   | Actual component rendering and scoped plus whole-page axe checks, light and dark                               |
+| control   | Display checks plus a registered behaviour probe                                                               |
+| overlay   | Display checks plus keyboard/pointer opening, open-dialog axe, focus containment and return, dismissal         |
+| composite | Display checks plus mobile/desktop page-overflow checks; registered navigation/behaviour probe when applicable |
+
+Profiles are reviewed classifications, not an automatic proof that an API has no other states. All public component exports have profiles. The registered probe mapping in `scripts/test-contract.mjs` prevents existing interactive components being downgraded to display-only coverage. A new interactive export needs a probe in that mapping and a corresponding implementation in `tests/support/probes.mjs`. Probe implementations contain real assertions of visible state, input values, callbacks or focus; a prose promise or a test name is insufficient.
+
+State fixtures exercise the scenarios a manifest declares in `testing.states`, chosen from the closed list in `scripts/test-contract.mjs`: `disabled`, `loading`, `error`, `empty`, `long`, `success`, `surface`, `inverse`, `coming-soon`, `duplicate-links`, `heading-3`, `scope-container` and `controlled`. ConfirmDialog, for example, declares `loading` and `long`. Every state has a registered browser assertion (`tests/support/states.mjs`, checked by `tests/test-contract.test.mjs`); a declared state without one fails. SignInPanel maps its submitting status to the loading fixture; the suite checks disabled submission, validation errors and an accessible success announcement. Inverse sections additionally check pressed-button and selected-icon contrast for both brands and appearances. New or changed public states must be added to the manifest, fixture and test assertions in the same PR. Existing state coverage is deliberately incremental: it is not a claim of exhaustive coverage of every optional prop. Bug fixes require a reproducing regression test. Reviewers should check state omissions and classifications as carefully as implementation code.
+
+The full browser command validates successful evidence for every expected component/theme/state. Missing, skipped, duplicated, failed or incomplete records fail the run, and `test-results/component-contract.json` records the result. Negative tests exercise the validator and preview failures. A contributor able to rewrite the harness could falsify evidence; the report is not a security boundary. Harness, policy, profile and workflow changes need explicit maintainer review.
+
+For focused development use `npx playwright test tests/browser/components.spec.mjs --grep Button`. This intentionally does not claim complete-contract coverage; the full command remains mandatory before merge. CI uses the Playwright-pinned browser. `UI_TEST_CHROME` is a local diagnostic override, not the canonical visual environment.
+
+ThemeProvider tests check brand, density, light/dark/system changes centrally. The default component sweep covers light/dark, and representative controls/shells exercise green. We do not cross every prop, theme, density and screen size. Global styles and tokens still run the full suite; no dependency graph currently skips required tests.
+
+## Visual baselines
+
+Sixteen comparisons cover AppShell, DocsShell, PlanComparison and the open ConfirmDialog at 390/1280px in light/dark. Baselines are platform-specific, with CI pinned to Ubuntu 24.04 and the lockfile's Playwright browser. Screenshots wait for fonts and disable animation. They allow a small pixel tolerance, not arbitrary layout changes.
+
+Missing baselines fail. Required CI never updates or approves them. A separate read-only workflow renders Linux candidates into an artifact directory, outside the accepted baseline tree. Its success is not a quality gate or approval. To propose new baselines on the matching platform:
+
+```sh
+npm run test:visual -- --update-snapshots=all
+```
+
+Review expected/actual/diff artifacts and commit only intentional changes. Initial and changed baseline images are proposals until the maintainer reviews them in the PR. Changes to this command's baseline files do not replace behavioural or accessibility evidence. AI may assist visual review but cannot waive a failed check or authorize merging.
+
+GitHub uploads runnable playground, browser evidence, contract report and visual diff artifacts. Inspect mobile/desktop, keyboard/focus and meaningful states; axe and screenshots do not establish complete accessibility or design quality.
+
+## Solo-maintainer review
+
+Required CI is the automatic merge gate. The repository does not require a second GitHub reviewer: the owner reviews and authorizes merging. Agents may prepare PRs and evidence, but cannot approve themselves or merge without explicit owner instruction. Baseline changes, waivers, policy changes, API removals and release publication remain maintainer decisions. No waiver mechanism is implemented in this test contract; missing obligations fail.

package/baseline-policy.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 1,
+  "version": "1.4.0",
+  "rules": {
+    "M001": "Exports require unique manifests and preview fixtures",
+    "M002": "Source and preview paths stay inside the repository",
+    "M003": "Dependencies reference known component IDs",
+    "M004": "Shared components cannot depend on hosted services",
+    "M005": "Component implementations use semantic colour tokens; only src/tokens.css defines colours",
+    "M006": "Every component has an executable test profile, supported probe and closed-vocabulary capabilities",
+    "M007": "Source and preview import-closure fingerprints must match; generated fields stay out of manifests",
+    "M008": "Committed catalogue matches the manifests",
+    "M009": "Brands declare only the --m-brand-* contract, and every appearance resolves the accent pair and its inverse",
+    "M010": "Manifest dependencies match the catalogue components the source renders"
+  }
+}

package/bin/mortar.mjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+// mortar: the open, local agent tooling for the Mortar UI kit. An MCP server
+// (`mortar mcp`) and a CLI over the installed package's catalogue and docs.
+// No network, no account, no runtime dependencies.
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { loadData, GUIDES, PACKAGE_ROOT } from "../cli/data.mjs";
+import { searchComponents } from "../cli/search.mjs";
+import { componentDetail, buildPacket } from "../cli/packet.mjs";
+import { auditApp, RULES } from "../cli/audit.mjs";
+
+const HELP = `mortar — local agent tooling for the Mortar UI kit (@tonycodes-ui/mortar)
+
+Usage:
+  mortar mcp                         Run the MCP server on stdio (for coding agents)
+  mortar search <query> [--kit K] [--category C] [--limit N]
+                                     Find components by purpose or name
+  mortar component <Name>            A component's contract, props and example
+  mortar packet <Name...> [--brief "text"]
+                                     A build packet: components, dependencies,
+                                     imports, CSS and theme setup, principles,
+                                     page templates
+  mortar audit [path]                Read-only audit of an app's Mortar usage
+                                     (exits 1 when it finds errors)
+  mortar guide <topic>               Print a guide: ${Object.keys(GUIDES).join(", ")}
+  mortar kits                        Kits, categories and components
+  mortar skill                       Print the agent skill (skills/mortar/SKILL.md)
+
+Options:
+  --json                             Machine-readable output
+  -h, --help                         Show this help
+  -v, --version                      Show the installed Mortar version
+
+Add the MCP server to Claude Code:
+  claude mcp add mortar -- npx -y @tonycodes-ui/mortar mcp
+
+Everything runs locally against the installed package. No account or network.`;
+
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--") {
+      positional.push(...argv.slice(i + 1));
+      break;
+    }
+    if (a.startsWith("--")) {
+      const [key, inline] = a.slice(2).split(/=(.*)/s);
+      if (["json", "help", "version"].includes(key)) flags[key] = true;
+      else flags[key] = inline ?? argv[++i];
+    } else if (a === "-h") flags.help = true;
+    else if (a === "-v") flags.version = true;
+    else positional.push(a);
+  }
+  return { positional, flags };
+}
+
+const out = (text) => process.stdout.write(text + "\n");
+const json = (value) => out(JSON.stringify(value, null, 2));
+const fail = (message) => {
+  process.stderr.write(`mortar: ${message}\n`);
+  process.exitCode = 2;
+};
+const indent = (text, by = "  ") =>
+  String(text)
+    .split("\n")
+    .map((l) => (l ? by + l : l))
+    .join("\n");
+
+function printComponent(c) {
+  out(
+    `${c.name} — ${c.kitTitle}${c.categoryTitle ? " › " + c.categoryTitle : ""}`,
+  );
+  out(c.description);
+  out("");
+  out(c.import);
+  out(`Marker: ${c.marker}`);
+  if (c.usage) out(`\nUsage: ${c.usage}`);
+  if (c.avoid) out(`Avoid: ${c.avoid}`);
+  if (c.accessibility) out(`Accessibility: ${c.accessibility}`);
+  out("\nProps:");
+  for (const p of c.props)
+    out(
+      `  ${p.name}${p.required ? "" : "?"}: ${p.type}${p.default !== undefined ? ` = ${p.default}` : ""}`,
+    );
+  if (c.acceptsHtmlAttributes)
+    out("  …and the HTML attributes of its root element");
+  if (c.dependencies.length) out(`\nRenders: ${c.dependencies.join(", ")}`);
+  if (c.testing?.states?.length)
+    out(`Tested states: ${c.testing.states.join(", ")}`);
+  if (c.templates.length) out(`Page templates: ${c.templates.join(", ")}`);
+  if (c.example) out(`\nExample:\n\n${indent(c.example)}`);
+}
+
+async function main() {
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+  const [command, ...rest] = positional;
+  if (flags.version) {
+    out(
+      JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"))
+        .version,
+    );
+    return;
+  }
+  if (flags.help || !command || command === "help") {
+    out(HELP);
+    return;
+  }
+  if (command === "mcp") {
+    const { serve } = await import("../cli/mcp.mjs");
+    await serve();
+    return;
+  }
+  const data = await loadData();
+  switch (command) {
+    case "search": {
+      const query = rest.join(" ");
+      if (!query)
+        return fail("search needs a query, e.g. mortar search sign in");
+      const results = searchComponents(data, {
+        query,
+        kit: flags.kit,
+        category: flags.category,
+        limit: flags.limit ? Number(flags.limit) : 10,
+      }).map(({ matched, ...r }) => r);
+      if (flags.json) return json(results);
+      if (!results.length) return out(`No components match "${query}".`);
+      const width = Math.max(...results.map((r) => r.name.length));
+      for (const r of results)
+        out(
+          `${r.name.padEnd(width)}  ${r.kit}${r.category ? " › " + r.category : ""}\n${" ".repeat(width + 2)}${r.description}`,
+        );
+      return;
+    }
+    case "component": {
+      if (!rest[0])
+        return fail("component needs a name, e.g. mortar component Button");
+      const c = data.find(rest[0]);
+      if (!c) {
+        const near = searchComponents(data, { query: rest[0], limit: 5 }).map(
+          (r) => r.name,
+        );
+        return fail(
+          `no component named "${rest[0]}".${near.length ? ` Try: ${near.join(", ")}` : ""}`,
+        );
+      }
+      const detail = componentDetail(data, c);
+      return flags.json ? json(detail) : printComponent(detail);
+    }
+    case "packet": {
+      if (!rest.length && !flags.brief)
+        return fail('packet needs component names or --brief "…"');
+      const packet = buildPacket(data, {
+        components: rest,
+        brief: flags.brief,
+      });
+      if (flags.json) return json(packet);
+      out(`Build packet — ${packet.package} ${packet.version}`);
+      for (const u of packet.unknown ?? [])
+        out(
+          `Unknown component ${u.name}${u.suggestions.length ? ` (did you mean ${u.suggestions.join(", ")}?)` : ""}`,
+        );
+      out(`\nInstall:\n  ${packet.install}`);
+      out(
+        `\nCSS (${packet.css.where}):\n${indent(packet.css.code)}\n  ${packet.css.notes}`,
+      );
+      out(`\nTheme:\n${indent(packet.themeProvider.code)}`);
+      out(`\nImport:\n  ${packet.import}`);
+      out("\nComponents:");
+      for (const c of packet.components) {
+        out(`  ${c.name} — ${c.description}`);
+        for (const why of c.why ?? []) out(`    why: ${why}`);
+        const required = c.props.filter((p) => p.required).map((p) => p.name);
+        if (required.length) out(`    required props: ${required.join(", ")}`);
+      }
+      if (packet.dependencies.components.length)
+        out(
+          `\nRendered inside them: ${packet.dependencies.components.map((d) => d.name).join(", ")}`,
+        );
+      if (packet.templates.length) {
+        out("\nPage templates that compose them (playground):");
+        for (const t of packet.templates)
+          out(`  ${t.id} — ${t.title}: ${t.description}`);
+      }
+      out("\nPrinciples:");
+      for (const p of packet.principles)
+        out(`  ${p.number}. ${p.id} — ${p.instruction}`);
+      out(
+        `\nGuides: ${packet.guides.map((g) => `mortar guide ${g}`).join(", ")}`,
+      );
+      out(
+        `Full contracts and examples: mortar packet ${packet.components.map((c) => c.name).join(" ")} --json`,
+      );
+      return;
+    }
+    case "audit": {
+      let report;
+      try {
+        report = await auditApp(rest[0] ?? ".", { data });
+      } catch (error) {
+        return fail(error.message);
+      }
+      if (flags.json) json(report);
+      else {
+        out(
+          `Mortar audit of ${report.root}\n${report.mortar.range ? `package.json: ${report.mortar.range}, ` : ""}installed: ${report.mortar.installed ?? "none"}, checked against ${report.mortar.checkedAgainst}\n`,
+        );
+        for (const f of report.findings) {
+          out(
+            `${f.file}${f.line ? ":" + f.line : ""}  ${f.severity}  ${f.rule}`,
+          );
+          out(`  ${f.message}`);
+          if (f.fix) out(`  fix: ${f.fix}`);
+        }
+        const s = report.summary;
+        out(
+          `\n${s.error} error${s.error === 1 ? "" : "s"}, ${s.warning} warning${s.warning === 1 ? "" : "s"}, ${s.info} info in ${s.files} files.`,
+        );
+      }
+      if (report.summary.error) process.exitCode = 1;
+      return;
+    }
+    case "guide": {
+      const topic = rest[0];
+      if (!GUIDES[topic])
+        return fail(`guide needs a topic: ${Object.keys(GUIDES).join(", ")}`);
+      const text = data.guide(topic);
+      return text ? out(text) : fail(`the ${topic} guide is not installed`);
+    }
+    case "kits": {
+      if (flags.json) return json(data.agent.taxonomy.kits);
+      for (const k of data.agent.taxonomy.kits) {
+        out(`${k.title} (${k.id}) — ${k.description}`);
+        for (const c of k.categories)
+          out(`  ${c.title} (${c.id}): ${c.components.join(", ")}`);
+      }
+      return;
+    }
+    case "skill": {
+      const file = join(PACKAGE_ROOT, "skills", "mortar", "SKILL.md");
+      return existsSync(file)
+        ? out(readFileSync(file, "utf8").trimEnd())
+        : fail("skill not installed");
+    }
+    case "rules":
+      for (const [id, text] of Object.entries(RULES))
+        out(`${id.padEnd(24)} ${text}`);
+      return;
+    default:
+      return fail(`unknown command "${command}". Run mortar --help.`);
+  }
+}
+
+main().catch((error) => {
+  process.stderr.write(`mortar: ${error?.stack ?? error}\n`);
+  process.exitCode = 2;
+});