@design-ai/cli 4.55.0

package/tools/migrations/bump-last-updated.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""Bulk-bump `last_updated` to the current month for given files.
+
+Use after a quarterly stability review when files are still accurate
+but the date is stale.
+
+Usage:
+  python3 tools/migrations/bump-last-updated.py knowledge/foo.md knowledge/bar.md
+  python3 tools/migrations/bump-last-updated.py --dry-run knowledge/*.md
+  python3 tools/migrations/bump-last-updated.py --today 2026-12 knowledge/foo.md
+
+Idempotent: if the file is already at the target date, it's skipped.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import date
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def find_frontmatter_bounds(text: str) -> tuple[int, int] | None:
+    lines = text.splitlines()
+    cursor = 0
+    while cursor < len(lines):
+        s = lines[cursor].strip()
+        if s.startswith("<!--") and s.endswith("-->"):
+            cursor += 1
+            continue
+        if s == "":
+            cursor += 1
+            continue
+        break
+    if cursor >= len(lines) or lines[cursor].strip() != "---":
+        return None
+    start = cursor + 1
+    for i in range(start, len(lines)):
+        if lines[i].strip() == "---":
+            return (start, i)
+    return None
+
+
+def parse_today(value: str | None) -> date:
+    if not value:
+        return date.today()
+    # Allow YYYY-MM or YYYY-MM-DD
+    try:
+        return date.fromisoformat(value)
+    except ValueError:
+        # Try YYYY-MM
+        parts = value.split("-")
+        if len(parts) == 2:
+            return date(int(parts[0]), int(parts[1]), 1)
+        raise
+
+
+def bump_last_updated(text: str, target: date) -> tuple[str, bool]:
+    bounds = find_frontmatter_bounds(text)
+    if bounds is None:
+        return text, False
+    start, end = bounds
+    lines = text.splitlines(keepends=True)
+    target_str = target.strftime("%Y-%m")
+
+    changed = False
+    for i in range(start, end):
+        line = lines[i]
+        stripped = line.lstrip()
+        if stripped.startswith("last_updated:"):
+            indent = line[: len(line) - len(stripped)]
+            new_line = f"{indent}last_updated: {target_str}\n"
+            if line != new_line:
+                lines[i] = new_line
+                changed = True
+            break  # only one last_updated per file
+
+    return "".join(lines), changed
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--today", help="Override today (YYYY-MM or YYYY-MM-DD); for testing")
+    parser.add_argument("files", nargs="+", type=Path)
+    args = parser.parse_args()
+
+    target = parse_today(args.today)
+    target_str = target.strftime("%Y-%m")
+
+    bumped: list[Path] = []
+    unchanged: list[Path] = []
+    skipped: list[tuple[Path, str]] = []
+
+    for raw in args.files:
+        path = raw if raw.is_absolute() else ROOT / raw
+        if not path.exists():
+            skipped.append((path, "not found"))
+            continue
+
+        text = path.read_text(encoding="utf-8")
+        new_text, changed = bump_last_updated(text, target)
+
+        if not changed:
+            unchanged.append(path)
+            continue
+
+        if args.dry_run:
+            print(f"  [dry-run] would bump {path.relative_to(ROOT)} → {target_str}")
+            bumped.append(path)
+            continue
+
+        tmp = path.with_suffix(path.suffix + ".tmp")
+        tmp.write_text(new_text, encoding="utf-8")
+        tmp.replace(path)
+        print(f"  ✓ {path.relative_to(ROOT)} → {target_str}")
+        bumped.append(path)
+
+    print()
+    print(f"Bumped: {len(bumped)}")
+    print(f"Unchanged: {len(unchanged)}")
+    if skipped:
+        print(f"Skipped: {len(skipped)}")
+        for p, reason in skipped:
+            print(f"  - {p}: {reason}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/tools/migrations/promote-stability.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""Bulk-promote (or demote) stability level for knowledge files.
+
+Updates `stability:` in YAML frontmatter for the given files. Idempotent:
+re-running with the same target is a no-op. Atomic per-file: writes a
+temp file then renames.
+
+Usage:
+  # Promote experimental → stable
+  python3 tools/migrations/promote-stability.py --from experimental --to stable \
+    knowledge/foo.md knowledge/bar.md
+
+  # Promote beta → stable
+  python3 tools/migrations/promote-stability.py --from beta --to stable knowledge/qux.md
+
+  # Demote stable → deprecated
+  python3 tools/migrations/promote-stability.py --from stable --to deprecated knowledge/old.md
+
+  # Dry-run
+  python3 tools/migrations/promote-stability.py --from beta --to stable \
+    --dry-run knowledge/*.md
+
+The --from value is enforced: if a file's current stability doesn't match,
+it's skipped with a warning. Use --force to override (rare).
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from datetime import date
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+STABILITY_VALUES = {"stable", "beta", "experimental", "deprecated"}
+
+
+def find_frontmatter_bounds(text: str) -> tuple[int, int] | None:
+    lines = text.splitlines()
+    cursor = 0
+    while cursor < len(lines):
+        s = lines[cursor].strip()
+        if s.startswith("<!--") and s.endswith("-->"):
+            cursor += 1
+            continue
+        if s == "":
+            cursor += 1
+            continue
+        break
+    if cursor >= len(lines) or lines[cursor].strip() != "---":
+        return None
+    start = cursor + 1
+    for i in range(start, len(lines)):
+        if lines[i].strip() == "---":
+            return (start, i)
+    return None
+
+
+def get_stability(text: str) -> str | None:
+    bounds = find_frontmatter_bounds(text)
+    if bounds is None:
+        return None
+    start, end = bounds
+    for line in text.splitlines()[start:end]:
+        if line.lstrip().startswith("stability:"):
+            return line.split(":", 1)[1].strip().strip("'\"")
+    return None
+
+
+def update_stability(text: str, new_value: str, today: date | None = None) -> tuple[str, bool]:
+    """Return (new_text, changed). Bumps last_updated to today if changed."""
+    bounds = find_frontmatter_bounds(text)
+    if bounds is None:
+        return text, False
+
+    start, end = bounds
+    lines = text.splitlines(keepends=True)
+
+    changed = False
+    for i in range(start, end):
+        line = lines[i]
+        stripped = line.lstrip()
+        if stripped.startswith("stability:"):
+            indent = line[: len(line) - len(stripped)]
+            new_line = f"{indent}stability: {new_value}\n"
+            if line != new_line:
+                lines[i] = new_line
+                changed = True
+        if stripped.startswith("last_updated:"):
+            indent = line[: len(line) - len(stripped)]
+            target = today or date.today()
+            new_line = f"{indent}last_updated: {target.strftime('%Y-%m')}\n"
+            if line != new_line:
+                lines[i] = new_line
+                # Bumping last_updated alone shouldn't claim "changed"
+                # if stability didn't move — but we always pair them when promoting.
+
+    return "".join(lines), changed
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--from", dest="from_level", required=True, choices=sorted(STABILITY_VALUES))
+    parser.add_argument("--to", dest="to_level", required=True, choices=sorted(STABILITY_VALUES))
+    parser.add_argument("--force", action="store_true", help="Skip the --from check")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--today", help="Override today (YYYY-MM-DD); for testing")
+    parser.add_argument("files", nargs="+", type=Path)
+    args = parser.parse_args()
+
+    if args.from_level == args.to_level:
+        print(f"--from and --to are the same ({args.from_level}). Nothing to do.", file=sys.stderr)
+        sys.exit(2)
+
+    today = date.fromisoformat(args.today) if args.today else date.today()
+
+    promoted: list[Path] = []
+    skipped: list[tuple[Path, str]] = []
+    not_found: list[Path] = []
+
+    for raw in args.files:
+        path = raw if raw.is_absolute() else ROOT / raw
+        if not path.exists():
+            not_found.append(path)
+            continue
+
+        text = path.read_text(encoding="utf-8")
+        current = get_stability(text)
+
+        if current is None:
+            skipped.append((path, "no stability key"))
+            continue
+
+        if current != args.from_level and not args.force:
+            skipped.append((path, f"current={current}, expected={args.from_level}"))
+            continue
+
+        new_text, changed = update_stability(text, args.to_level, today=today)
+
+        if not changed:
+            skipped.append((path, "already at target"))
+            continue
+
+        if args.dry_run:
+            print(f"  [dry-run] would update {path.relative_to(ROOT)}: {current} → {args.to_level}")
+            promoted.append(path)
+            continue
+
+        # Atomic write
+        tmp = path.with_suffix(path.suffix + ".tmp")
+        tmp.write_text(new_text, encoding="utf-8")
+        tmp.replace(path)
+        print(f"  ✓ {path.relative_to(ROOT)}: {current} → {args.to_level}")
+        promoted.append(path)
+
+    print()
+    print(f"Promoted: {len(promoted)}")
+    print(f"Skipped: {len(skipped)}")
+    if skipped:
+        for p, reason in skipped[:10]:
+            print(f"  - {p.relative_to(ROOT)}: {reason}")
+        if len(skipped) > 10:
+            print(f"  ... and {len(skipped) - 10} more")
+    if not_found:
+        print(f"Not found: {len(not_found)}")
+        for p in not_found:
+            print(f"  - {p}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/tools/preview/README.md

@@ -0,0 +1,58 @@
+# Preview tools
+
+Tools that turn design-ai's structured outputs (markdown specs, JSON tokens) into something humans can visually inspect.
+
+## render-tokens.py
+
+Extracts color tokens from a markdown file and renders an interactive HTML preview with:
+
+- Light + dark mode token swatches
+- WCAG contrast matrix
+- Light/dark theme toggle
+- Live component previews (Button, Input, Alert, Card) using the actual tokens
+
+### Usage
+
+```bash
+# Generate alongside the source file (default)
+python3 tools/preview/render-tokens.py examples/palette-saas-violet.md
+# → examples/palette-saas-violet.preview.html
+
+# Specify output
+python3 tools/preview/render-tokens.py examples/palette-saas-violet.md /tmp/preview.html
+
+# Open in browser
+open examples/palette-saas-violet.preview.html
+```
+
+### What it accepts
+
+- `examples/palette-*.md` — palette specs
+- `examples/dogfood-*.md` — full system bootstraps
+- Any markdown file containing CSS code blocks with `--token-name: value;` declarations
+
+### What it extracts
+
+- Token names matching `--<name>: <value>;` in code blocks
+- Light tokens from blocks scoped to `:root`
+- Dark tokens from blocks scoped to `.dark`
+- Hex values from each token (for swatches and contrast computation)
+
+### Output is gitignored
+
+`*.preview.html` is in `.gitignore`. Each user regenerates locally for review. The markdown source is the authoritative artifact.
+
+### When to use
+
+- After running `/palette-from-brand` or `/design-from-brief` — visual sanity check before sharing the design.
+- During `/iterate` — see before/after by generating two previews.
+- Before handoff — give engineering a visual reference alongside the markdown spec.
+
+### Limitations
+
+- HTML/CSS only. No real React components.
+- Doesn't render OKLCH literally (uses hex extracted from the file).
+- Only shows the components hard-coded in the template. Customizing requires editing `render-tokens.py`.
+- Doesn't validate API claims (only color values).
+
+For richer previews — e.g., rendering all 19 component specs as live React components — that's a Phase 4 item (HTML preview generator + Storybook export).