@maccesar/aiskills 1.12.0 → 1.16.0

package/skills/stitch-showcase/scripts/build_showcase.py

@@ -40,6 +40,7 @@ import parse_design_md
 import extract_text
 import detect_components
 import extract_catalog
+from slug_demangle import slug_to_title
 
 
 def _extract_source_zip(zip_path: Path) -> Path:
@@ -150,6 +151,9 @@ def build(source_dir: str, project_type: str = None, project_name: str = None) -
     # Generate catalog.html (always included)
     _generate_catalog(output_dir, assets_dir, metadata)
 
+    # Sanity-check the generated output — warnings only, never aborts.
+    _validate_showcase(output_dir, screens)
+
     print(f"\n🎉 Showcase ready: {output_dir}/index.html\n")
     return output_dir
 
@@ -344,6 +348,11 @@ def _prepare_source(source_dir: str, project_type: str, project_name: str) -> tu
         # Defer type detection — will resolve after screen extraction via _detect_type_from_screens()
         metadata["_type_pending"] = True
 
+    # Language: showcase.json wins over DESIGN.md if both present, else fall through.
+    if config.get("lang"):
+        metadata["lang"] = str(config["lang"])
+    metadata.setdefault("lang", "en")
+
     ptype = metadata.get("type", "unknown")
     if ptype != "unknown":
         print(f"📱 Type: {ptype} | Project: {metadata['project_name']}")
@@ -518,16 +527,21 @@ def _enrich_screens(screens_raw: list, metadata: dict, source: Path) -> list:
     for raw in screens_raw:
         slug = raw["slug"]
         design = design_screens.get(slug, {})
+        html_path = raw.get("html_path", "")
 
-        # Title
-        title = design.get("title") or _slug_to_title(slug)
+        # Title resolution order: explicit DESIGN.md → <title> HTML → demangled slug
+        title = (
+            design.get("title")
+            or _read_html_title_tag(html_path)
+            or slug_to_title(slug)
+        )
 
         # Description priority: DESIGN.md → individual .md → meta/h1/title/visible body text → ""
         desc = design.get("description") or ""
         if not desc:
             desc = _read_md_desc(slug, source)
         if not desc:
-            desc = _read_html_title(raw.get("html_path", ""))
+            desc = _read_html_title(html_path)
 
         enriched.append({
             "slug": slug,
@@ -540,6 +554,50 @@ def _enrich_screens(screens_raw: list, metadata: dict, source: Path) -> list:
     return enriched
 
 
+def _read_html_title_tag(html_path: str) -> str:
+    """
+    Read the <title> tag of an HTML file and return a usable screen title.
+
+    Skips generic placeholders (Untitled, index, etc.). Strips a leading
+    "Brand - " or "Brand | " prefix when the title contains a separator,
+    so "Lumiere Dining - Rústico & Artesanal" becomes "Rústico & Artesanal".
+    Decodes basic HTML entities (&amp;, &nbsp;…).
+    """
+    if not html_path:
+        return ""
+    try:
+        text = Path(html_path).read_text(encoding="utf-8", errors="ignore")
+    except OSError:
+        return ""
+
+    m = re.search(r"<title[^>]*>(.+?)</title>", text, re.IGNORECASE | re.DOTALL)
+    if not m:
+        return ""
+
+    val = re.sub(r"<[^>]+>", "", m.group(1)).strip()
+    for entity, char in [
+        ("&amp;", "&"), ("&lt;", "<"), ("&gt;", ">"),
+        ("&nbsp;", " "), ("&#39;", "'"), ("&quot;", '"'),
+    ]:
+        val = val.replace(entity, char)
+    val = re.sub(r"\s+", " ", val).strip()
+
+    if not val:
+        return ""
+    if re.match(r"^(untitled|index|screen|page|document|\d+)$", val, re.IGNORECASE):
+        return ""
+
+    # Strip a "Brand - " / "Brand | " / "Brand: " prefix and return the last segment.
+    for sep in (" - ", " — ", " | ", ": "):
+        if sep in val:
+            tail = val.split(sep)[-1].strip()
+            if tail:
+                val = tail
+                break
+
+    return val
+
+
 def _read_md_desc(slug: str, source: Path) -> str:
     """Look for an individual .md file with the screen description."""
     for md_file in source.glob("*.md"):
@@ -718,6 +776,23 @@ def _generate_viewer(output_dir: Path, ptype: str, metadata: dict, screens: list
 
     template = template_path.read_text(encoding="utf-8")
 
+    # Reorder screens to follow DESIGN.md section order (mirrors _build_sections_html)
+    # so prev/next navigation matches the visual order in index.html.
+    sections = metadata.get("sections", [])
+    if sections:
+        slug_to_screen = {s["slug"]: s for s in screens}
+        ordered = []
+        seen = set()
+        for section in sections:
+            for slug in section.get("slugs", []):
+                if slug in slug_to_screen and slug not in seen:
+                    ordered.append(slug_to_screen[slug])
+                    seen.add(slug)
+        for s in screens:
+            if s["slug"] not in seen:
+                ordered.append(s)
+        screens = ordered
+
     # Build screens JSON for prev/next navigation
     screens_data = [
         {"title": s["title"], "desc": s["description"], "html_file": s["html_file"]}
@@ -738,6 +813,7 @@ def _generate_viewer(output_dir: Path, ptype: str, metadata: dict, screens: list
     font_family = font or "system-ui"
 
     html = template
+    html = html.replace("{{HTML_LANG}}", metadata.get("lang", "en"))
     html = html.replace("{{PROJECT_NAME}}", escape(metadata["project_name"]))
     html = html.replace("{{SCREENS_JSON}}", json.dumps(screens_data, ensure_ascii=False))
     html = html.replace("{{DEFAULT_THEME}}", metadata.get("default_theme", "light"))
@@ -796,12 +872,13 @@ def _generate_index(output_dir: Path, ptype: str, metadata: dict, screens: list)
     )
 
     # New template variables
-    type_labels = {"mobile": "Mobile App", "web": "Web App"}
+    type_labels = {"mobile": "App Móvil", "web": "App Web"}
     type_label = type_labels.get(metadata.get("type", ""), "Showcase")
     project_desc = _project_description_html(metadata, filtered_screens)
     screens_intro = _screens_intro_text(metadata)
 
     html = template
+    html = html.replace("{{HTML_LANG}}", metadata.get("lang", "en"))
     html = html.replace("{{PROJECT_NAME}}", escape(metadata["project_name"]))
     html = html.replace("{{SCREEN_COUNT}}", str(len(filtered_screens)))
     html = html.replace("{{SCREENS_HTML}}", sections_html)
@@ -925,7 +1002,7 @@ def _design_system_html(ds_screen: dict | None, metadata: dict) -> str:
             f'style="font-family:\'{escape(font)}\',sans-serif">Aa</span>'
             f'<div>'
             f'<span class="text-sm font-medium text-gray-700 dark:text-gray-200">{escape(font)}</span>'
-            f'<span class="text-xs text-gray-400 dark:text-gray-500 ml-2">Primary typeface</span>'
+            f'<span class="text-xs text-gray-400 dark:text-gray-500 ml-2">Tipografía principal</span>'
             f'</div>'
             f'</div>'
         )
@@ -1292,10 +1369,73 @@ def _card_html(screen: dict, ptype: str) -> str:
         </a>"""
 
 
-def _slug_to_title(slug: str) -> str:
-    """01_splash_screen → 'Splash Screen' (strips numeric prefix)."""
-    s = re.sub(r"^[\d_]+", "", slug)
-    return s.replace("_", " ").replace("-", " ").title().strip() or slug.title()
+# ─── Post-build validation ───────────────────────────────────────────────────
+
+def _validate_showcase(output_dir: Path, screens: list) -> None:
+    """
+    Sanity-check the generated showcase. Prints warnings only — never aborts.
+
+    Checks:
+      1. JSON embedded in viewer.html (`var SCREENS = [...]`) parses.
+      2. Each screen has both `assets/<slug>.html` and `assets/<slug>.png`.
+      3. Local `src=` references (img / video / source) inside each screen
+         resolve on disk (URLs starting with http/https/data: are skipped).
+    """
+    assets_dir = output_dir / "assets"
+    issues: list[str] = []
+
+    # 1) Embedded SCREENS JSON in viewer.html
+    viewer_path = output_dir / "viewer.html"
+    if viewer_path.exists():
+        viewer_text = viewer_path.read_text(encoding="utf-8")
+        m = re.search(r"var\s+SCREENS\s*=\s*(\[.*?\]);", viewer_text, re.DOTALL)
+        if not m:
+            issues.append("viewer.html: no encontré `var SCREENS = [...]`")
+        else:
+            try:
+                json.loads(m.group(1))
+            except json.JSONDecodeError as e:
+                issues.append(f"viewer.html: SCREENS JSON inválido — {e}")
+
+    # 2) Per-screen assets
+    for s in screens:
+        slug = s["slug"]
+        if not (assets_dir / f"{slug}.html").exists():
+            issues.append(f"{slug}: falta assets/{slug}.html")
+        if not (assets_dir / f"{slug}.png").exists():
+            issues.append(f"{slug}: falta assets/{slug}.png")
+
+    # 3) Local img / video / source references inside each screen HTML
+    src_re = re.compile(
+        r"""<(?:img|video|source)\s[^>]*src=["']([^"']+)["']""",
+        re.IGNORECASE,
+    )
+    for s in screens:
+        slug = s["slug"]
+        html_path = assets_dir / f"{slug}.html"
+        if not html_path.exists():
+            continue
+        try:
+            text = html_path.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        for src in src_re.findall(text):
+            if src.startswith(("http://", "https://", "data:", "//")):
+                continue
+            ref = (html_path.parent / src).resolve()
+            if not ref.exists():
+                issues.append(f"{slug}: src inexistente '{src}'")
+
+    # 4) Report
+    print()
+    if not issues:
+        print(f"✅ {len(screens)}/{len(screens)} screens válidos")
+    else:
+        print(f"⚠ {len(issues)} problema(s) detectado(s):")
+        for issue in issues[:20]:
+            print(f"   - {issue}")
+        if len(issues) > 20:
+            print(f"   ...({len(issues) - 20} más)")
 
 
 def _project_slug(name: str) -> str:
@@ -1422,7 +1562,7 @@ def _init(source_dir: str, project_type: str, project_name: str) -> None:
         sys.exit(1)
 
     # Auto-group slugs for skeleton
-    fake_screens = [{"slug": s, "title": _slug_to_title(s), "description": ""} for s in slugs]
+    fake_screens = [{"slug": s, "title": slug_to_title(s), "description": ""} for s in slugs]
     groups = _auto_group_screens(fake_screens)
 
     pname = project_name or source.name.replace("_", " ").replace("-", " ").title()

package/skills/stitch-showcase/scripts/parse_design_md.py

@@ -3,13 +3,26 @@ parse_design_md.py — Extracts metadata from DESIGN.md for stitch-showcase.
 
 Usage:
     python parse_design_md.py /path/to/DESIGN.md
-    → prints JSON with project_name, type, colors, color_tokens, default_theme, font_family, screens, sections
+    → prints JSON with project_name, type, lang, colors, color_tokens, default_theme, font_family, screens, sections
 """
 import re
 import sys
 import json
 from pathlib import Path
 
+# Ensure sibling modules resolve when this file is invoked directly.
+sys.path.insert(0, str(Path(__file__).parent))
+from slug_demangle import slug_to_title
+
+
+SPANISH_STOPWORDS = {
+    "de", "el", "la", "los", "las", "para", "con", "por", "una", "uno",
+    "del", "que", "es", "se", "su", "sus", "como", "más", "muy", "este",
+    "esta", "estos", "estas", "pantalla", "pantallas", "aplicación",
+    "aplicacion", "usuario", "usuarios", "diseño", "diseno", "móvil",
+    "movil", "perfil", "configuración", "configuracion",
+}
+
 
 def parse(design_md_path: str) -> dict:
     path = Path(design_md_path)
@@ -17,6 +30,7 @@ def parse(design_md_path: str) -> dict:
         return {
             "project_name": "",
             "type": "unknown",
+            "lang": "en",
             "colors": {},
             "color_tokens": {},
             "default_theme": "light",
@@ -26,9 +40,17 @@ def parse(design_md_path: str) -> dict:
         }
 
     text = path.read_text(encoding="utf-8")
+    frontmatter = _parse_yaml_frontmatter(text)
+    lang = _extract_lang_override(text) or _detect_lang(text)
     colors = _extract_colors(text)
     color_tokens = _extract_color_tokens(text)
 
+    # Frontmatter fills in fields the Markdown body doesn't define.
+    if not colors and frontmatter.get("colors"):
+        colors = dict(frontmatter["colors"])
+    if not color_tokens and frontmatter.get("colors"):
+        color_tokens = _semantic_tokens_from_dict(frontmatter["colors"])
+
     # Determine default_theme from surface token
     surface_hex = color_tokens.get("surface") or color_tokens.get("background")
     if not surface_hex:
@@ -58,7 +80,7 @@ def parse(design_md_path: str) -> dict:
         # Apply titles/descriptions to screens already in the list
         for s in screens:
             slug = s["slug"]
-            if not s.get("title") or s["title"] == _slug_to_title(slug):
+            if not s.get("title") or s["title"] == slug_to_title(slug):
                 if slug in section_titles:
                     s["title"] = section_titles[slug]
             if not s.get("description") and slug in section_descs:
@@ -69,29 +91,145 @@ def parse(design_md_path: str) -> dict:
                 if slug not in existing_slugs:
                     screens.append({
                         "slug": slug,
-                        "title": section_titles.get(slug) or _slug_to_title(slug),
+                        "title": section_titles.get(slug) or slug_to_title(slug),
                         "description": section_descs.get(slug, ""),
                     })
                     existing_slugs.add(slug)
 
+    project_name = _extract_project_name(text) or frontmatter.get("name", "")
+    font_family = _extract_typography(text) or frontmatter.get("font_family")
+
     return {
-        "project_name": _extract_project_name(text),
+        "project_name": project_name,
         "type": _detect_type(text),
+        "lang": lang,
         "colors": colors,
         "color_tokens": color_tokens,
         "default_theme": default_theme,
-        "font_family": _extract_typography(text),
+        "font_family": font_family,
         "screens": screens,
         "sections": sections,
     }
 
 
+def _parse_yaml_frontmatter(text: str) -> dict:
+    """
+    Parse a Stitch-style YAML frontmatter at the top of DESIGN.md.
+
+    Recognizes (everything else is ignored):
+      - top-level ``name:`` → ``"name"``
+      - ``colors:`` block with hex values → ``"colors"`` dict
+      - ``typography:`` block — returns the first ``fontFamily`` → ``"font_family"``
+
+    Returns an empty dict if no frontmatter delimiter is present.
+    """
+    m = re.match(r"^---\s*\n(.*?)\n---\s*\n", text, re.DOTALL)
+    if not m:
+        return {}
+    fm = m.group(1)
+    result: dict = {}
+
+    # name: <value>
+    name_m = re.search(r"^name:\s*(.+?)\s*$", fm, re.MULTILINE)
+    if name_m:
+        val = name_m.group(1).strip().strip("'\"")
+        if val:
+            result["name"] = val
+
+    # colors: block — collect indented "key: '#hex'" pairs until indentation drops.
+    colors_m = re.search(r"^colors:\s*\n((?:[ \t]+\S.*\n?)+)", fm, re.MULTILINE)
+    if colors_m:
+        colors: dict = {}
+        for line in colors_m.group(1).splitlines():
+            cm = re.match(
+                r"^\s+([a-z][a-z0-9\-]*):\s*['\"]?(#[0-9A-Fa-f]{3,8})['\"]?\s*$",
+                line,
+            )
+            if cm:
+                colors[cm.group(1).lower()] = "#" + cm.group(2).lstrip("#").upper()
+        if colors:
+            result["colors"] = colors
+
+    # typography: pick the first fontFamily declared anywhere in the block.
+    typo_m = re.search(r"fontFamily:\s*['\"]?([^'\"\n,]+)['\"]?", fm)
+    if typo_m:
+        font = typo_m.group(1).strip().rstrip(",;")
+        if font:
+            result["font_family"] = font
+
+    return result
+
+
+def _semantic_tokens_from_dict(colors: dict) -> dict:
+    """
+    Compute `accent` / `surface` semantic tokens from a flat color dict.
+
+    Mirrors the rules used by :func:`_extract_color_tokens`:
+      - ``accent``  → first key containing ``primary`` (not ``on-primary``)
+      - ``surface`` → first key named ``surface`` or containing ``background``/``bg``
+    """
+    tokens = dict(colors)
+    for name, val in colors.items():
+        if "primary" in name and not name.startswith("on-"):
+            tokens["accent"] = val
+            break
+    for name, val in colors.items():
+        if name == "surface" or "background" in name or name == "bg":
+            tokens["surface"] = val
+            break
+    return tokens
+
+
 def _extract_project_name(text: str) -> str:
     """First H1 heading in the document."""
     m = re.search(r"^#\s+(.+)$", text, re.MULTILINE)
     return m.group(1).strip() if m else ""
 
 
+def _extract_lang_override(text: str) -> str | None:
+    """
+    Explicit override via ``## Lang`` (or ``## Language``) section in DESIGN.md.
+
+    Expected format:
+        ## Lang
+        es
+
+    Returns a BCP-47-ish code (``es``, ``en``, ``pt-BR``…) or None if absent.
+    """
+    m = re.search(
+        r"^##\s+Lang(?:uage)?\s*\n\s*([A-Za-z]{2}(?:-[A-Za-z]{2,4})?)\s*$",
+        text, re.IGNORECASE | re.MULTILINE
+    )
+    if not m:
+        return None
+    raw = m.group(1)
+    # Normalize: language subtag lowercase, region subtag uppercase (BCP-47).
+    if "-" in raw:
+        lang, region = raw.split("-", 1)
+        return f"{lang.lower()}-{region.upper()}"
+    return raw.lower()
+
+
+def _detect_lang(text: str) -> str:
+    """
+    Heuristic language detection. Distinguishes Spanish from everything else.
+
+    Signals:
+      - Spanish-only accented characters (á é í ó ú ñ ü).
+      - Common Spanish stop words from SPANISH_STOPWORDS.
+
+    Returns 'es' when either signal is present, else 'en'.
+    """
+    if not text:
+        return "en"
+    lower = text.lower()
+    if re.search(r"[áéíóúñü]", lower):
+        return "es"
+    words = re.findall(r"[a-záéíóúñü]+", lower)
+    stop_hits = sum(1 for w in words if w in SPANISH_STOPWORDS)
+    return "es" if stop_hits >= 3 else "en"
+
+
 def _detect_type(text: str) -> str:
     """Returns 'mobile', 'web', or 'unknown'.
 
@@ -292,7 +430,7 @@ def _parse_table(text: str) -> list:
         cols = [c.strip() for c in line.split("|") if c.strip()]
         if len(cols) >= 2:
             slug = _to_slug(cols[0])
-            title = cols[1] if len(cols) > 1 else _slug_to_title(slug)
+            title = cols[1] if len(cols) > 1 else slug_to_title(slug)
             desc = cols[2] if len(cols) > 2 else ""
             rows.append({"slug": slug, "title": title, "description": desc})
 
@@ -324,7 +462,7 @@ def _parse_screen_list(text: str) -> list:
                 title = title_part.strip()
                 desc = desc_part.strip()
             else:
-                title = _slug_to_title(slug)
+                title = slug_to_title(slug)
                 desc = raw
             screens.append({"slug": slug, "title": title, "description": desc})
 
@@ -384,11 +522,6 @@ def _to_slug(s: str) -> str:
     return s
 
 
-def _slug_to_title(slug: str) -> str:
-    """splash_screen → 'Splash Screen'"""
-    return slug.replace("_", " ").replace("-", " ").title()
-
-
 if __name__ == "__main__":
     if len(sys.argv) < 2:
         print("Usage: python parse_design_md.py /path/to/DESIGN.md", file=sys.stderr)