@iamnishankhan/opencode-kit-grok 1.0.0

package/kit/.opencode/skills/geo-fundamentals/scripts/geo_checker.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+"""
+GEO Checker - Generative Engine Optimization Audit
+Checks PUBLIC WEB CONTENT for AI citation readiness.
+
+PURPOSE:
+    - Analyze pages that will be INDEXED by AI engines (ChatGPT, Perplexity, etc.)
+    - Check for structured data, author info, dates, FAQ sections
+    - Help content rank in AI-generated answers
+
+WHAT IT CHECKS:
+    - HTML files (actual web pages)
+    - JSX/TSX files (React page components)
+    - NOT markdown files (those are developer docs, not public content)
+
+Usage:
+    python geo_checker.py <project_path>
+"""
+from __future__ import annotations
+import sys
+import re
+import json
+from pathlib import Path
+
+# Fix Windows console encoding
+try:
+    sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+    sys.stderr.reconfigure(encoding='utf-8', errors='replace')
+except AttributeError:
+    pass
+
+
+# Directories that never represent public source content.
+SKIP_DIRS = {
+    "node_modules", ".next", "dist", "build", ".git", ".github",
+    ".agents", "__pycache__", ".vscode", ".idea", "coverage",
+    "test", "tests", "__tests__", "spec", "public", "components",
+}
+
+PAGE_SUFFIXES = {".html", ".htm", ".jsx", ".tsx"}
+ARTICLE_SEGMENTS = {"blog", "blogs", "article", "articles", "post", "posts", "news"}
+
+
+def _lower_parts(file_path: Path) -> list[str]:
+    return [part.lower() for part in file_path.parts]
+
+
+def is_page_file(file_path: Path) -> bool:
+    """Return True only for route entry points, not layouts or components."""
+    if file_path.suffix.lower() not in PAGE_SUFFIXES:
+        return False
+    parts = _lower_parts(file_path)
+    if any(part in SKIP_DIRS for part in parts):
+        return False
+    if file_path.suffix.lower() in {".html", ".htm"}:
+        return True
+
+    name = file_path.stem.lower()
+    if name.endswith((".test", ".spec")) or name.startswith(("test_", "spec_")):
+        return False
+
+    # Next.js App Router: only page.tsx/page.jsx is a public route entry.
+    if "app" in parts:
+        return name == "page"
+
+    # Next.js Pages Router: each source file is a route except framework/API files.
+    if "pages" in parts:
+        pages_index = parts.index("pages")
+        route_parts = parts[pages_index + 1 :]
+        if "api" in route_parts or name.startswith("_"):
+            return False
+        return True
+
+    # Other routers commonly use explicit page/index route entries.
+    return "routes" in parts and name in {"page", "index"}
+
+
+def find_web_pages(project_path: Path) -> list[Path]:
+    """Find public-facing route source files deterministically."""
+    files = []
+    for suffix in PAGE_SUFFIXES:
+        for file_path in project_path.rglob(f"*{suffix}"):
+            if is_page_file(file_path):
+                files.append(file_path)
+    return sorted(set(files), key=lambda item: item.as_posix())[:100]
+
+
+def _read_route_content(file_path: Path) -> str:
+    """Read a route and its directly imported local content modules.
+
+    Next.js route entries often delegate all visible markup to content.tsx or
+    localized MDX files. Static analysis must follow those imports or it scores
+    a thin wrapper instead of the page users and crawlers receive.
+    """
+    content = file_path.read_text(encoding="utf-8", errors="ignore")
+    import_paths = re.findall(r"(?:import|from)\s+(?:[^'\"]+?\s+from\s+)?['\"](\.{1,2}/[^'\"]+)['\"]", content)
+    extensions = ("", ".tsx", ".ts", ".jsx", ".js", ".mdx", ".md")
+    seen = {file_path.resolve()}
+    resolved_imports = []
+    for import_path in import_paths:
+        base = (file_path.parent / import_path).resolve()
+        candidates = [Path(f"{base}{extension}") for extension in extensions]
+        candidates.extend(base / f"index{extension}" for extension in extensions[1:])
+        for candidate in candidates:
+            if not candidate.is_file() or candidate.resolve() in seen:
+                continue
+            seen.add(candidate.resolve())
+            resolved_imports.append(candidate)
+            break
+
+    # A localized wrapper renders one locale at a time. Analyze the canonical
+    # English source rather than concatenating four mutually exclusive H1s.
+    canonical_locale = [item for item in resolved_imports if ".en." in item.name.lower()]
+    selected = canonical_locale or resolved_imports
+    chunks = [content]
+    chunks.extend(item.read_text(encoding="utf-8", errors="ignore") for item in selected)
+    return "\n".join(chunks)
+
+
+def check_page(file_path: Path, project_path: Path | None = None) -> dict:
+    """Score a route source file without requiring article metadata on product docs."""
+    try:
+        content = _read_route_content(file_path)
+    except Exception as exc:
+        return {"file": str(file_path), "passed": [], "issues": [f"Error: {exc}"], "score": 0}
+
+    issues = []
+    passed = []
+    optional_points = 0
+    lower_content = content.lower()
+    parts = set(_lower_parts(file_path))
+    is_article = bool(parts & ARTICLE_SEGMENTS)
+    is_root_landing = file_path.parent.name.lower() == "app"
+
+    heading_content = re.sub(r"```.*?```", "", content, flags=re.S)
+    heading_content = re.sub(r"`(?:\.|[^`])*`", "", heading_content, flags=re.S)
+    h1_count = len(re.findall(r"<h1[^>]*>", heading_content, re.I))
+    h1_count += len(re.findall(r"^#\s+\S", heading_content, re.M))
+    h2_count = len(re.findall(r"<h2[^>]*>", heading_content, re.I))
+    h2_count += len(re.findall(r"^##\s+\S", heading_content, re.M))
+    required_total = 1 if is_root_landing else 2
+    required_passed = 0
+
+    if h1_count == 1:
+        passed.append("Single H1 heading (clear topic)")
+        required_passed += 1
+    elif h1_count == 0:
+        issues.append("No H1 heading - page topic unclear")
+    else:
+        issues.append(f"Multiple H1 headings ({h1_count}) - confusing for AI")
+
+    if not is_root_landing:
+        repeated_heading = h2_count >= 1 and ".map(" in content
+        if h2_count >= 2 or repeated_heading:
+            detail = "dynamic repeated" if repeated_heading and h2_count < 2 else str(h2_count)
+            passed.append(f"{detail} H2 subheadings (good structure)")
+            required_passed += 1
+        else:
+            issues.append("Add at least two H2 subheadings for scannable content")
+
+    if "application/ld+json" in lower_content:
+        passed.append("JSON-LD structured data found")
+        optional_points += 10
+    if re.search(r'"@type"\s*:\s*"(Organization|Person|Brand|Article|FAQPage)"', content, re.I):
+        passed.append("Recognizable schema entity found")
+        optional_points += 5
+
+    author_patterns = ("author", "byline", "written-by", "contributor", 'rel="author"')
+    has_author = any(pattern in lower_content for pattern in author_patterns)
+    date_patterns = ("datepublished", "datemodified", "datetime=", "pubdate", "article:published")
+    has_date = any(pattern in lower_content for pattern in date_patterns)
+    if is_article:
+        required_total += 2
+        if has_author:
+            passed.append("Author attribution found")
+            required_passed += 1
+        else:
+            issues.append("Article has no author attribution")
+        if has_date:
+            passed.append("Publication date found")
+            required_passed += 1
+        else:
+            issues.append("Article has no publication date")
+    else:
+        optional_points += 3 if has_author else 0
+        optional_points += 3 if has_date else 0
+
+    optional_checks = (
+        (r"<details|faq|frequently.?asked|\"FAQPage\"", "FAQ section detected", 5),
+        (r"<(ul|ol)[^>]*>", "Structured list content found", 5),
+        (r"<table[^>]*>", "Comparison table found", 5),
+        (r"\d+%|according to|data\s+(shows|reveals)|\d+x\s+(faster|better|more)", "Data-backed claims found", 5),
+        (r"is defined as|refers to|means that|in short,|simply put,|<dfn", "Direct-answer phrasing found", 5),
+    )
+    for pattern, label, points in optional_checks:
+        if re.search(pattern, content, re.I):
+            passed.append(label)
+            optional_points += points
+
+    base_score = (required_passed / required_total * 70) if required_total else 70
+    score = min(100, round(base_score + min(optional_points, 30)))
+    display = file_path.relative_to(project_path).as_posix() if project_path else file_path.as_posix()
+    return {"file": display, "passed": passed, "issues": issues, "score": score}
+
+
+def main():
+    target = sys.argv[1] if len(sys.argv) > 1 else "."
+    target_path = Path(target).resolve()
+    
+    print("\n" + "=" * 60)
+    print("  GEO CHECKER - AI Citation Readiness Audit")
+    print("=" * 60)
+    print(f"Project: {target_path}")
+    print("-" * 60)
+    
+    # Find web pages only
+    pages = find_web_pages(target_path)
+    
+    if not pages:
+        print("\n[!] No public web pages found.")
+        print("    Looking for: HTML, JSX, TSX files in pages/app directories")
+        print("    Skipping: docs, tests, config files, node_modules")
+        output = {"script": "geo_checker", "pages_found": 0, "passed": True}
+        print("\n" + json.dumps(output, indent=2))
+        sys.exit(0)
+    
+    print(f"Found {len(pages)} public pages to analyze\n")
+    
+    # Check each page
+    results = []
+    for page in pages:
+        result = check_page(page, target_path)
+        results.append(result)
+    
+    # Print results
+    for result in results:
+        status = "[OK]" if result['score'] >= 60 else "[!]"
+        print(f"{status} {result['file']}: {result['score']}%")
+        if result['issues'] and result['score'] < 60:
+            for issue in result['issues'][:2]:  # Show max 2 issues
+                print(f"    - {issue}")
+    
+    # Average score
+    avg_score = sum(r['score'] for r in results) / len(results) if results else 0
+    
+    print("\n" + "=" * 60)
+    print(f"AVERAGE GEO SCORE: {avg_score:.0f}%")
+    print("=" * 60)
+    
+    if avg_score >= 80:
+        print("[OK] Excellent - Content well-optimized for AI citations")
+    elif avg_score >= 60:
+        print("[OK] Good - Some improvements recommended")
+    elif avg_score >= 40:
+        print("[!] Needs work - Add structured elements")
+    else:
+        print("[X] Poor - Content needs GEO optimization")
+    
+    # JSON output
+    output = {
+        "script": "geo_checker",
+        "project": str(target_path),
+        "pages_checked": len(results),
+        "average_score": round(avg_score),
+        "passed": avg_score >= 60
+    }
+    print("\n" + json.dumps(output, indent=2))
+    
+    sys.exit(0 if avg_score >= 60 else 1)
+
+
+if __name__ == "__main__":
+    main()

package/kit/.opencode/skills/i18n-localization/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: i18n-localization
+description: Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.
+compatibility: opencode
+metadata:
+  when_to_use: "\"When internationalizing an app, managing translations, detecting hardcoded strings, or adding RTL support.\""
+  version: "1.0.0"
+---
+# i18n & Localization
+
+> Internationalization (i18n) and Localization (L10n) best practices.
+
+---
+
+## 1. Core Concepts
+
+| Term | Meaning |
+|------|---------|
+| **i18n** | Internationalization - making app translatable |
+| **L10n** | Localization - actual translations |
+| **Locale** | Language + Region (en-US, tr-TR) |
+| **RTL** | Right-to-left languages (Arabic, Hebrew) |
+
+---
+
+## 2. When to Use i18n
+
+| Project Type | i18n Needed? |
+|--------------|--------------|
+| Public web app | ✅ Yes |
+| SaaS product | ✅ Yes |
+| Internal tool | ⚠️ Maybe |
+| Single-region app | ⚠️ Consider future |
+| Personal project | ❌ Optional |
+
+---
+
+## 3. Implementation Patterns
+
+### React (react-i18next)
+
+```tsx
+import { useTranslation } from 'react-i18next';
+
+function Welcome() {
+  const { t } = useTranslation();
+  return <h1>{t('welcome.title')}</h1>;
+}
+```
+
+### Next.js (next-intl)
+
+```tsx
+import { useTranslations } from 'next-intl';
+
+export default function Page() {
+  const t = useTranslations('Home');
+  return <h1>{t('title')}</h1>;
+}
+```
+
+### Python (gettext)
+
+```python
+from gettext import gettext as _
+
+print(_("Welcome to our app"))
+```
+
+---
+
+## 4. File Structure
+
+```
+locales/
+├── en/
+│   ├── common.json
+│   ├── auth.json
+│   └── errors.json
+├── tr/
+│   ├── common.json
+│   ├── auth.json
+│   └── errors.json
+└── ar/          # RTL
+    └── ...
+```
+
+---
+
+## 5. Best Practices
+
+### DO ✅
+
+- Use translation keys, not raw text
+- Namespace translations by feature
+- Support pluralization
+- Handle date/number formats per locale
+- Plan for RTL from the start
+- Use ICU message format for complex strings
+
+### DON'T ❌
+
+- Hardcode strings in components
+- Concatenate translated strings
+- Assume text length (German is 30% longer)
+- Forget about RTL layout
+- Mix languages in same file
+
+---
+
+## 6. Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| Missing translation | Fallback to default language |
+| Hardcoded strings | Use linter/checker script |
+| Date format | Use Intl.DateTimeFormat |
+| Number format | Use Intl.NumberFormat |
+| Pluralization | Use ICU message format |
+
+---
+
+## 7. RTL Support
+
+```css
+/* CSS Logical Properties */
+.container {
+  margin-inline-start: 1rem;  /* Not margin-left */
+  padding-inline-end: 1rem;   /* Not padding-right */
+}
+
+[dir="rtl"] .icon {
+  transform: scaleX(-1);
+}
+```
+
+---
+
+## 8. Checklist
+
+Before shipping:
+
+- [ ] All user-facing strings use translation keys
+- [ ] Locale files exist for all supported languages
+- [ ] Date/number formatting uses Intl API
+- [ ] RTL layout tested (if applicable)
+- [ ] Fallback language configured
+- [ ] No hardcoded strings in components
+
+---
+
+## Script
+
+| Script | Purpose | Command |
+|--------|---------|---------|
+| `.opencode/scripts/i18n_checker.py` | Detect hardcoded strings & missing translations | `python .opencode/scripts/i18n_checker.py <project_path>` |

package/kit/.opencode/skills/i18n-localization/scripts/i18n_checker.py

@@ -0,0 +1,223 @@
+#!/usr/bin/env python3
+"""Audit locale completeness and likely user-facing hard-coded strings."""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+SKIP_DIRS = {"node_modules", ".git", ".agents", ".agent", "dist", "build", "__pycache__", ".venv", "venv", ".next", "tests", "test", "spec", "specs"}
+CODE_TYPES = {".tsx": "jsx", ".jsx": "jsx", ".ts": "jsx", ".js": "jsx", ".vue": "vue", ".py": "python"}
+I18N_PATTERNS = (
+    re.compile(r"\buseTranslation\s*\("),
+    re.compile(r"\buseTranslations\s*\("),
+    re.compile(r"(?<![\w$])t\s*\(\s*[\"']"),
+    re.compile(r"\$t\s*\("),
+    re.compile(r"\bgettext\s*\("),
+    re.compile(r"(?<!\w)_\s*\(\s*[\"']"),
+    re.compile(r"\bFormattedMessage\b"),
+    re.compile(r"\bi18n\."),
+)
+HARDCODED_PATTERNS = {
+    "jsx": (
+        re.compile(r">\s*([A-Z][A-Za-z][A-Za-z\s!?.,'-]{2,80})\s*</"),
+        re.compile(r"(?:title|placeholder|label|alt|aria-label)=[\"']([A-Z][A-Za-z\s!?.,'-]{2,80})[\"']"),
+    ),
+    "vue": (
+        re.compile(r">\s*([A-Z][A-Za-z][A-Za-z\s!?.,'-]{2,80})\s*</"),
+        re.compile(r"(?:title|placeholder|label|alt|aria-label)=[\"']([A-Z][A-Za-z\s!?.,'-]{2,80})[\"']"),
+    ),
+    "python": (
+        re.compile(r"\bflash\s*\(\s*[\"']([A-Z][^\"']{4,100})[\"']"),
+    ),
+}
+
+
+def is_skipped(path: Path, root: Path) -> bool:
+    try:
+        rel = path.relative_to(root)
+    except ValueError:
+        rel = path
+    return any(part in SKIP_DIRS for part in rel.parts)
+
+
+def find_locale_files(root: Path) -> list[Path]:
+    patterns = (
+        "**/locales/**/*.json", "**/translations/**/*.json", "**/lang/**/*.json",
+        "**/i18n/**/*.json", "**/messages/*.json", "**/*.po",
+    )
+    found: set[Path] = set()
+    for pattern in patterns:
+        for path in root.glob(pattern):
+            if path.is_file() and not is_skipped(path, root):
+                found.add(path)
+    return sorted(found)
+
+
+def flatten_keys(value: Any, prefix: str = "") -> set[str]:
+    keys: set[str] = set()
+    if not isinstance(value, dict):
+        return keys
+    for key, child in value.items():
+        name = f"{prefix}.{key}" if prefix else str(key)
+        if isinstance(child, dict):
+            keys.update(flatten_keys(child, name))
+        else:
+            keys.add(name)
+    return keys
+
+
+def check_locale_completeness(locale_files: list[Path], root: Path) -> dict[str, Any]:
+    if not locale_files:
+        return {"status": "not_applicable", "files": 0, "languages": [], "issues": [], "notes": ["No locale files found."]}
+
+    locales: dict[str, dict[str, set[str]]] = {}
+    issues: list[dict[str, str]] = []
+    for path in locale_files:
+        if path.suffix == ".po":
+            continue
+        try:
+            content = json.loads(path.read_text("utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            issues.append({"severity": "high", "file": path.relative_to(root).as_posix(), "issue": f"Invalid locale JSON: {exc}"})
+            continue
+        language = path.parent.name
+        locales.setdefault(language, {})[path.stem] = flatten_keys(content)
+
+    languages = sorted(locales)
+    if len(languages) >= 2:
+        base = languages[0]
+        namespaces = set().union(*(set(locales[lang]) for lang in languages))
+        for namespace in sorted(namespaces):
+            base_keys = locales[base].get(namespace, set())
+            for language in languages[1:]:
+                keys = locales[language].get(namespace, set())
+                missing = sorted(base_keys - keys)
+                extra = sorted(keys - base_keys)
+                if missing:
+                    issues.append({"severity": "high", "file": f"{language}/{namespace}", "issue": f"Missing {len(missing)} key(s): {', '.join(missing[:8])}"})
+                if extra:
+                    issues.append({"severity": "medium", "file": f"{language}/{namespace}", "issue": f"Has {len(extra)} extra key(s)"})
+
+    return {"status": "checked", "files": len(locale_files), "languages": languages, "issues": issues, "notes": []}
+
+
+def iter_code_files(root: Path):
+    for path in root.rglob("*"):
+        if path.is_file() and path.suffix.lower() in CODE_TYPES and not is_skipped(path, root):
+            yield path
+
+
+def project_uses_i18n(root: Path, code_files: list[Path], locale_files: list[Path]) -> bool:
+    if locale_files:
+        return True
+    package = root / "package.json"
+    if package.is_file():
+        try:
+            text = package.read_text("utf-8").lower()
+            if any(name in text for name in ("i18next", "next-intl", "react-intl", "vue-i18n", "@lingui")):
+                return True
+        except OSError:
+            pass
+    for path in code_files[:200]:
+        try:
+            content = path.read_text("utf-8", errors="ignore")
+        except OSError:
+            continue
+        if any(pattern.search(content) for pattern in I18N_PATTERNS):
+            return True
+    return False
+
+
+def check_hardcoded_strings(root: Path, code_files: list[Path], enforce: bool) -> dict[str, Any]:
+    if not enforce:
+        return {"status": "not_applicable", "files_checked": 0, "files_using_i18n": 0, "issues": [], "notes": ["No i18n framework or locale files detected."]}
+
+    issues: list[dict[str, Any]] = []
+    files_using_i18n = 0
+    checked = 0
+    for path in code_files[:500]:
+        try:
+            content = path.read_text("utf-8", errors="ignore")
+        except OSError:
+            continue
+        checked += 1
+        has_i18n = any(pattern.search(content) for pattern in I18N_PATTERNS)
+        if has_i18n:
+            files_using_i18n += 1
+        if has_i18n:
+            continue
+        file_type = CODE_TYPES[path.suffix.lower()]
+        for pattern in HARDCODED_PATTERNS[file_type]:
+            for match in pattern.finditer(content):
+                value = match.group(1).strip()
+                if value.lower().startswith(("http", "error", "warning")):
+                    continue
+                line = content.count("\n", 0, match.start()) + 1
+                issues.append({
+                    "severity": "medium",
+                    "file": path.relative_to(root).as_posix(),
+                    "line": line,
+                    "issue": "Likely user-facing hard-coded string",
+                    "text": value[:100],
+                })
+                if len(issues) >= 100:
+                    break
+            if len(issues) >= 100:
+                break
+        if len(issues) >= 100:
+            break
+    return {"status": "checked", "files_checked": checked, "files_using_i18n": files_using_i18n, "issues": issues, "notes": []}
+
+
+def audit(root: Path, strict: bool = False) -> dict[str, Any]:
+    locale_files = find_locale_files(root)
+    code_files = list(iter_code_files(root))
+    enforce = strict or project_uses_i18n(root, code_files, locale_files)
+    locale = check_locale_completeness(locale_files, root)
+    code = check_hardcoded_strings(root, code_files, enforce)
+    findings = locale["issues"] + code["issues"]
+    high = sum(item["severity"] == "high" for item in findings)
+    medium = sum(item["severity"] == "medium" for item in findings)
+    return {
+        "project": str(root),
+        "applicable": enforce,
+        "locale_check": locale,
+        "code_check": code,
+        "summary": {"total": len(findings), "high": high, "medium": medium, "passed": high == 0},
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Check locale completeness and likely hard-coded UI strings")
+    parser.add_argument("project", nargs="?", default=".")
+    parser.add_argument("--strict", action="store_true", help="Scan hard-coded strings even when no i18n setup is detected")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args()
+    root = Path(args.project).resolve()
+    if not root.is_dir():
+        parser.error(f"Project directory does not exist: {root}")
+    report = audit(root, args.strict)
+    if args.as_json:
+        print(json.dumps(report, indent=2, ensure_ascii=False))
+    else:
+        print(f"i18n Audit: {root}")
+        if not report["applicable"]:
+            print("[SKIP] No i18n framework or locale files detected.")
+        else:
+            locale = report["locale_check"]
+            code = report["code_check"]
+            print(f"Locale files: {locale['files']} | Languages: {', '.join(locale['languages']) or 'unknown'}")
+            print(f"Code files checked: {code['files_checked']} | Files using i18n: {code['files_using_i18n']}")
+            for item in (locale["issues"] + code["issues"])[:30]:
+                line = f":{item['line']}" if "line" in item else ""
+                print(f"[{item['severity'].upper()}] {item['file']}{line} - {item['issue']}")
+            print("[PASS] No blocking i18n issues." if report["summary"]["passed"] else "[FAIL] Blocking i18n issues found.")
+    return 0 if report["summary"]["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())