@maccesar/aiskills 1.7.0

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

@@ -0,0 +1,397 @@
+"""
+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
+"""
+import re
+import sys
+import json
+from pathlib import Path
+
+
+def parse(design_md_path: str) -> dict:
+    path = Path(design_md_path)
+    if not path.exists():
+        return {
+            "project_name": "",
+            "type": "unknown",
+            "colors": {},
+            "color_tokens": {},
+            "default_theme": "light",
+            "font_family": None,
+            "screens": [],
+            "sections": [],
+        }
+
+    text = path.read_text(encoding="utf-8")
+    colors = _extract_colors(text)
+    color_tokens = _extract_color_tokens(text)
+
+    # Determine default_theme from surface token
+    surface_hex = color_tokens.get("surface") or color_tokens.get("background")
+    if not surface_hex:
+        # fall back to colors dict
+        for key in ("surface", "background", "bg"):
+            if key in colors:
+                surface_hex = colors[key]
+                break
+    default_theme = _surface_default_theme(surface_hex) if surface_hex else "light"
+
+    screens = _extract_screens(text)
+    sections = _extract_sections(text)
+
+    # Merge inline titles and descriptions from sections into the screens list.
+    # Sections can contain "- slug: Title | Description" or "- slug: description"
+    # entries that _extract_screens misses when slugs are only listed under ### headers.
+    section_titles = {}
+    section_descs = {}
+    for sec in sections:
+        for slug, title in sec.get("titles", {}).items():
+            section_titles[slug] = title
+        for slug, desc in sec.get("descriptions", {}).items():
+            section_descs[slug] = desc
+
+    if section_titles or section_descs:
+        existing_slugs = {s["slug"] for s in screens}
+        # 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 slug in section_titles:
+                    s["title"] = section_titles[slug]
+            if not s.get("description") and slug in section_descs:
+                s["description"] = section_descs[slug]
+        # Add slugs that only appear inside sections (not in the flat screen list)
+        for sec in sections:
+            for slug in sec["slugs"]:
+                if slug not in existing_slugs:
+                    screens.append({
+                        "slug": slug,
+                        "title": section_titles.get(slug) or _slug_to_title(slug),
+                        "description": section_descs.get(slug, ""),
+                    })
+                    existing_slugs.add(slug)
+
+    return {
+        "project_name": _extract_project_name(text),
+        "type": _detect_type(text),
+        "colors": colors,
+        "color_tokens": color_tokens,
+        "default_theme": default_theme,
+        "font_family": _extract_typography(text),
+        "screens": screens,
+        "sections": sections,
+    }
+
+
+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 _detect_type(text: str) -> str:
+    """Returns 'mobile', 'web', or 'unknown'.
+
+    Priority:
+    1. Explicit ``## Type`` section with 'mobile' or 'web' on the next line
+    2. Keyword scoring across the full document
+    """
+    # 1. Explicit ## Type section — authoritative if present
+    m = re.search(r"^##\s+Type\s*\n\s*(\S+)", text, re.MULTILINE | re.IGNORECASE)
+    if m:
+        val = m.group(1).strip().lower()
+        if val in ("mobile", "web"):
+            return val
+
+    # 2. Keyword scoring fallback
+    lower = text.lower()
+    mobile_keywords = ["móvil", "movil", "mobile", "ios", "android", "app móvil", "aplicación móvil"]
+    web_keywords = ["web", "dashboard", "escritorio", "desktop", "browser", "navegador"]
+
+    mobile_score = sum(1 for kw in mobile_keywords if kw in lower)
+    web_score = sum(1 for kw in web_keywords if kw in lower)
+
+    if mobile_score > web_score:
+        return "mobile"
+    if web_score > mobile_score:
+        return "web"
+    return "unknown"
+
+
+def _extract_colors(text: str) -> dict:
+    """Extract name:value pairs from the colors section."""
+    colors = {}
+    color_section = re.search(
+        r"##\s+(?:Colores?|Colors?)\s*\n(.*?)(?=\n##|\Z)",
+        text, re.IGNORECASE | re.DOTALL
+    )
+    if not color_section:
+        return colors
+
+    for line in color_section.group(1).splitlines():
+        # Formats: "- Primary: #FDD900" or "Primary: #FDD900"
+        m = re.search(r"[-*]?\s*(.+?):\s*(#[0-9A-Fa-f]{3,8}|rgb\(.+?\)|[a-z]+)\s*$", line, re.IGNORECASE)
+        if m:
+            key = m.group(1).strip().lower()
+            val = m.group(2).strip()
+            colors[key] = val
+
+    return colors
+
+
+def _extract_color_tokens(text: str) -> dict:
+    """
+    Extract semantic color tokens in Stitch DESIGN.md format.
+
+    Matches: `token-name` (#XXXXXX) or token-name (#XXXXXX)
+    Returns dict with semantic roles:
+      accent  → first token containing 'primary' (not 'on-primary')
+      surface → first token named 'surface' or containing 'background'/'bg'
+      + all raw tokens by name
+    """
+    tokens = {}
+
+    # Match backtick-wrapped: `token-name` (#XXXXXX)
+    for m in re.finditer(r"`([a-z][a-z0-9\-]+)`\s*\(#([0-9A-Fa-f]{6})\)", text, re.IGNORECASE):
+        tokens[m.group(1).lower()] = "#" + m.group(2).upper()
+
+    # Match bare: token-name (#XXXXXX)  (only if not already captured)
+    for m in re.finditer(r"\b([a-z][a-z0-9\-]+)\s*\(#([0-9A-Fa-f]{6})\)", text, re.IGNORECASE):
+        key = m.group(1).lower()
+        if key not in tokens:
+            tokens[key] = "#" + m.group(2).upper()
+
+    # Build semantic roles
+    result = dict(tokens)  # copy all raw tokens
+
+    # accent: first 'primary' token that isn't 'on-primary'
+    for name, val in tokens.items():
+        if "primary" in name and not name.startswith("on-"):
+            result["accent"] = val
+            break
+
+    # surface: 'surface' or 'background'/'bg'
+    for name, val in tokens.items():
+        if name == "surface" or "background" in name or name == "bg":
+            result["surface"] = val
+            break
+
+    return result
+
+
+def _surface_default_theme(surface_hex: str) -> str:
+    """
+    Determine showcase default theme from app surface color luminance.
+
+    Dark app surface → use light showcase (for contrast).
+    Light app surface → use dark showcase (for contrast).
+    """
+    hex_clean = surface_hex.lstrip("#")
+    if len(hex_clean) != 6:
+        return "light"
+    try:
+        r = int(hex_clean[0:2], 16)
+        g = int(hex_clean[2:4], 16)
+        b = int(hex_clean[4:6], 16)
+    except ValueError:
+        return "light"
+
+    luminance = 0.299 * r + 0.587 * g + 0.114 * b
+    if luminance < 100:
+        return "light"   # dark app → light showcase
+    if luminance > 155:
+        return "dark"    # light app → dark showcase
+    return "light"
+
+
+def _extract_typography(text: str) -> str | None:
+    """
+    Extract primary font family name from the Typography section of DESIGN.md.
+
+    Returns font name (e.g. 'Inter') or None if not found.
+    """
+    # Look for ## Typography or ## N. Typography section
+    typo_section = re.search(
+        r"##\s+(?:\d+\.\s+)?Typography\s*\n(.*?)(?=\n##|\Z)",
+        text, re.IGNORECASE | re.DOTALL
+    )
+
+    UI_LABELS = {"display", "headline", "title", "body", "label", "bold", "regular", "medium", "semibold"}
+
+    if typo_section:
+        section_text = typo_section.group(1)
+        # Look for bold text **FontName** in first few lines
+        for line in section_text.splitlines()[:6]:
+            m = re.search(r"\*\*([A-Z][a-zA-Z\s\+]+)\*\*", line)
+            if m:
+                candidate = m.group(1).strip()
+                words = candidate.split()
+                # Font names are 1-3 words, not UI labels
+                if 1 <= len(words) <= 3 and words[0].lower() not in UI_LABELS:
+                    return candidate
+
+        # Broader search in full section
+        for m in re.finditer(r"\*\*([A-Z][a-zA-Z\s\+]+)\*\*", section_text):
+            candidate = m.group(1).strip()
+            words = candidate.split()
+            if 1 <= len(words) <= 3 and words[0].lower() not in UI_LABELS:
+                return candidate
+
+    # Fallback: search entire doc for font-family
+    m = re.search(r"font-family:\s*[\"']?([A-Z][a-zA-Z\s]+)[\"']?", text)
+    if m:
+        candidate = m.group(1).strip().rstrip(",;")
+        if candidate:
+            return candidate
+
+    return None
+
+
+def _extract_screens(text: str) -> list:
+    """
+    Extract screen list with slug, title, description.
+
+    Supported formats:
+    1. Markdown table: | slug | title | description |
+    2. Numbered list:  1. splash_screen - Description
+    3. Bullet list:    - splash_screen — Description
+    4. Simple pair:    splash_screen: Description
+    """
+    # Attempt 1: markdown table
+    table_screens = _parse_table(text)
+    if table_screens:
+        return table_screens
+
+    # Attempt 2: numbered or bullet list inside a Screens section
+    list_screens = _parse_screen_list(text)
+    if list_screens:
+        return list_screens
+
+    return []
+
+
+def _parse_table(text: str) -> list:
+    """Parse markdown table with slug/title/description columns."""
+    section = re.search(
+        r"##\s+(?:Pantallas?|Screens?)\s*\n(.*?)(?=\n##|\Z)",
+        text, re.IGNORECASE | re.DOTALL
+    )
+    if not section:
+        return []
+
+    section_text = section.group(1)
+    rows = []
+
+    for line in section_text.splitlines():
+        # Table rows must START with | (not bullet lines with "Title | Desc" format)
+        if not re.match(r"^\s*\|", line) or re.match(r"^\s*\|[-\s|]+\|\s*$", line):
+            continue
+        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)
+            desc = cols[2] if len(cols) > 2 else ""
+            rows.append({"slug": slug, "title": title, "description": desc})
+
+    # Skip header row if it contains "slug", "screen", etc.
+    if rows and rows[0]["slug"] in ("slug", "pantalla", "screen", "nombre", "name"):
+        rows = rows[1:]
+
+    return rows
+
+
+def _parse_screen_list(text: str) -> list:
+    """Parse numbered or bullet lists of screens."""
+    section = re.search(
+        r"##\s+(?:Pantallas?|Screens?)\s*\n(.*?)(?=\n##|\Z)",
+        text, re.IGNORECASE | re.DOTALL
+    )
+    if not section:
+        return []
+
+    screens = []
+    for line in section.group(1).splitlines():
+        # "1. slug_name - Description" or "- slug_name — Description" or "- slug: Title | Description"
+        m = re.match(r"^\s*(?:\d+\.|[-*])\s+([a-zA-Z0-9_\-]+)\s*[-—:]\s*(.+)$", line)
+        if m:
+            slug = _to_slug(m.group(1))
+            raw = m.group(2).strip()
+            if " | " in raw:
+                title_part, desc_part = raw.split(" | ", 1)
+                title = title_part.strip()
+                desc = desc_part.strip()
+            else:
+                title = _slug_to_title(slug)
+                desc = raw
+            screens.append({"slug": slug, "title": title, "description": desc})
+
+    return screens
+
+
+def _extract_sections(text: str) -> list:
+    """
+    Extract sections with their screen slugs if defined in DESIGN.md.
+
+    Expected format:
+    ### Onboarding
+    - splash_screen
+    - login
+    """
+    sections = []
+    section_block = re.search(
+        r"##\s+(?:Pantallas?|Screens?)\s*\n(.*?)(?=\n##\s+(?!#)|\Z)",
+        text, re.IGNORECASE | re.DOTALL
+    )
+    if not section_block:
+        return []
+
+    content = section_block.group(1)
+    current_section = None
+
+    for line in content.splitlines():
+        h3 = re.match(r"^###\s+(.+)$", line)
+        if h3:
+            current_section = {"name": h3.group(1).strip(), "slugs": []}
+            sections.append(current_section)
+            continue
+
+        if current_section:
+            m = re.match(r"^\s*[-*\d.]+\s*([a-zA-Z0-9_\-]+)\s*(?:[-—:]\s*(.+))?$", line)
+            if m:
+                slug = _to_slug(m.group(1))
+                current_section["slugs"].append(slug)
+                if m.group(2):
+                    raw = m.group(2).strip()
+                    # Support "Title | Description" format for mangled slugs
+                    if " | " in raw:
+                        title_part, desc_part = raw.split(" | ", 1)
+                        current_section.setdefault("titles", {})[slug] = title_part.strip()
+                        current_section.setdefault("descriptions", {})[slug] = desc_part.strip()
+                    else:
+                        current_section.setdefault("descriptions", {})[slug] = raw
+
+    return sections
+
+
+def _to_slug(s: str) -> str:
+    """Normalize to snake_case slug."""
+    s = s.strip().lower()
+    s = re.sub(r"[\s\-]+", "_", s)
+    s = re.sub(r"[^a-z0-9_]", "", s)
+    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)
+        sys.exit(1)
+    result = parse(sys.argv[1])
+    print(json.dumps(result, ensure_ascii=False, indent=2))

package/skills/vscode-extension-dev/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: vscode-extension-dev
+description: >
+  Guide for building VS Code extensions from scratch. Use when the user is creating,
+  scaffolding, designing, debugging, testing, bundling, or publishing a VS Code extension.
+  Covers all major API patterns: TreeView, QuickPick, Webview, StatusBar, commands,
+  configuration, SecretStorage, progress indicators, and esbuild bundling.
+when_to_use: >
+  - User wants to create a new VS Code extension
+  - User asks about VS Code extension APIs (TreeView, Webview, QuickPick, etc.)
+  - User needs help with package.json contributes, activationEvents, or keybindings
+  - User is debugging extension activation, disposables, or memory leaks
+  - User asks about bundling extensions with esbuild or webpack
+  - User wants to publish an extension to the VS Code Marketplace or Open VSX
+  - User asks about Webview CSP, nonce, or postMessage communication
+  - User asks about SecretStorage or credential management in extensions
+  - User needs help with extension testing (@vscode/test-electron)
+source: "VS Code Extension API documentation (https://code.visualstudio.com/api)"
+anti_hallucination_note: >
+  ALL guidance in this skill comes from the official VS Code Extension API docs
+  and established community patterns. Do NOT invent API methods, event names,
+  or configuration keys. If unsure whether an API exists, say so explicitly.
+  Always verify imports come from the 'vscode' module.
+---
+
+# VS Code Extension Development Skill
+
+You are a VS Code extension development advisor. Base ALL guidance on the reference files below — not training data.
+
+## How to Use This Skill
+
+1. Read the relevant reference file(s) before answering
+2. Base ALL code on the reference content — not training data
+3. Use real TypeScript imports and correct `vscode` API signatures
+4. Do not invent API methods, events, or configuration keys not in the references
+
+## Scaffolding Workflow
+
+1. **Generate project**: `npx --package yo --package generator-code -- yo code`
+2. **Choose template**: TypeScript extension (recommended)
+3. **Choose bundler**: esbuild (recommended) or webpack
+4. **Project structure** created — see `references/architecture.md` for layout
+5. **Configure** `package.json` — see `references/package-json-schema.md`
+6. **Implement** — see `references/api-patterns.md` for working examples
+7. **Test** — see `references/architecture.md` for testing strategy
+8. **Publish** — see `references/publishing.md` for full workflow
+
+## UI Component Decision Matrix
+
+| Need                              | Use                  | Why                                            |
+| --------------------------------- | -------------------- | ---------------------------------------------- |
+| Hierarchical data in sidebar      | TreeView             | Native tree with expand/collapse, icons, badges |
+| Quick selection from a list       | QuickPick            | Modal list with filtering, multi-select         |
+| Rich HTML interface               | Webview Panel        | Full HTML/CSS/JS, but heavier and needs CSP     |
+| Persistent status info            | StatusBarItem        | Always visible, clickable, lightweight          |
+| Simple text input                 | InputBox             | Single-line input with validation               |
+| File/folder selection             | showOpenDialog       | Native OS file picker                           |
+| Background task progress          | withProgress         | Notification or status bar progress             |
+
+## Key Patterns
+
+### Lazy Activation
+- Use `activationEvents` in `package.json` to defer activation
+- Since VS Code 1.74+, commands in `contributes.commands` auto-generate `onCommand:` events
+- Prefer specific events (`onLanguage:python`, `onView:myTreeView`) over `*`
+- See `references/package-json-schema.md` for full activationEvents reference
+
+### Disposable Management
+- Push ALL subscriptions to `context.subscriptions` in `activate()`
+- Use `deactivate()` only for async cleanup (closing connections, stopping servers)
+- Never rely on garbage collection — always dispose explicitly
+- See `references/api-patterns.md` for the cleanup pattern
+
+### withProgress for Async Operations
+- Use `ProgressLocation.Notification` for user-facing tasks
+- Use `ProgressLocation.Window` for status bar progress
+- Support cancellation via `CancellationToken`
+- See `references/api-patterns.md` for working examples
+
+### SecretStorage for Credentials
+- Use `context.secrets` (SecretStorage API) — never store tokens in settings
+- Fires `onDidChange` event when secrets change
+- See `references/api-patterns.md` for the credential manager pattern
+
+### Webview CSP and PostMessage
+- Always set a Content Security Policy with nonce
+- Use `webview.asWebviewUri()` for local resources
+- Bidirectional communication via `postMessage` / `onDidReceiveMessage`
+- See `references/api-patterns.md` for the full Webview pattern
+
+### esbuild Bundling
+- Bundle extension into a single file for faster activation
+- Mark `vscode` as external (it's provided by the runtime)
+- See `references/package-json-schema.md` for scripts configuration
+
+## Reference Files
+
+| File                                | Topics                                                              |
+| ----------------------------------- | ------------------------------------------------------------------- |
+| `references/package-json-schema.md` | contributes, activationEvents, engines, scripts, devDependencies    |
+| `references/api-patterns.md`        | TreeView, Webview, QuickPick, StatusBar, SecretStorage, withProgress |
+| `references/architecture.md`        | Project structure, layered architecture, testing strategy            |
+| `references/publishing.md`          | vsce, .vscodeignore, CI/CD, Open VSX, versioning                    |
+
+## Anti-Patterns to Avoid
+
+- Using `*` activation event in production (activates on every VS Code start)
+- Storing secrets in `configuration` instead of `SecretStorage`
+- Forgetting to dispose subscriptions (causes memory leaks)
+- Missing CSP in Webviews (security vulnerability)
+- Bundling `node_modules` instead of using esbuild/webpack
+- Using synchronous file I/O in the extension host (blocks the UI)
+- Registering commands without corresponding `contributes.commands` entries
+- Hardcoding `vscode.workspace.rootPath` (deprecated — use `workspaceFolders`)