Add CI checks, FAQ, and banner fix

Author: wang422003

.github/workflows/validate.yml

@@ -0,0 +1,23 @@
+name: Validate Skill
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Validate skill metadata and scripts
+        run: python3 scripts/validate_skill.py
+
+      - name: Smoke-test installer
+        run: python3 scripts/install_skill.py --dest /tmp/codex-thread-rescue-install

README.md

@@ -89,6 +89,36 @@ python3 scripts/repair_codex_desktop_threads.py --cwd /absolute/path/to/project
 - The visibility check relies on `codex app-server`.
 - On non-macOS setups, skip `--restart-desktop` and relaunch Desktop manually if needed.
 
+## Repository checks
+
+Run the same basic validation locally that GitHub Actions runs on every push and pull request:
+
+```bash
+python3 scripts/validate_skill.py
+```
+
+## FAQ
+
+### I installed the repo, but the skill still does not show up in Codex Desktop
+
+Make sure the installed folder is exactly `~/.codex/skills/codex--thread-rescue--skill`, then restart Codex Desktop. If you cloned the repo somewhere else first, run `python3 scripts/install_skill.py` from the repo root to copy the skill into the right place.
+
+### Why do old threads exist on disk but not in the left sidebar?
+
+This usually means Desktop visibility is filtering them out even though the thread rows still exist in `state_5.sqlite`. The most common causes are stale global state pins, missing workspace hints, or provider-filtered visibility.
+
+### Is it safe to run?
+
+Yes, the default mode is read-only. Use `--print-json` or a plain dry run first, then only add `--apply` if the summary matches what you expect. Before any write, the repair script creates timestamped backups.
+
+### Do I need to use the script manually every time?
+
+No. Once the repo is installed as a skill, you can ask Codex directly with a prompt like `Use $codex--thread-rescue--skill to restore missing local Codex Desktop threads for /absolute/path/to/project.`
+
+### Does this work outside macOS?
+
+Mostly yes for diagnosis and repairs, but the Desktop restart helper is macOS-oriented. On other systems, skip `--restart-desktop` and relaunch the app yourself if needed.
+
 ## Notes
 
 - The script is read-only unless `--apply` is provided.

assets/codex-thread-rescue-banner.svg

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+
+FRONTMATTER_PATTERN = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)
+FIELD_PATTERN = re.compile(r"^([A-Za-z0-9_]+):\s*(.+?)\s*$")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Validate the packaged Codex skill metadata and smoke-test bundled scripts.",
+    )
+    parser.add_argument(
+        "--repo-root",
+        default=str(Path(__file__).resolve().parents[1]),
+        help="Skill repository root. Defaults to the parent of this script.",
+    )
+    return parser.parse_args()
+
+
+def fail(message: str) -> None:
+    print(f"[FAIL] {message}")
+    raise SystemExit(1)
+
+
+def parse_skill_frontmatter(skill_path: Path) -> dict[str, str]:
+    content = skill_path.read_text()
+    match = FRONTMATTER_PATTERN.match(content)
+    if not match:
+        fail(f"{skill_path} is missing a valid YAML-style frontmatter block")
+
+    result: dict[str, str] = {}
+    for line in match.group(1).splitlines():
+        if ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        result[key.strip()] = value.strip()
+    return result
+
+
+def parse_openai_yaml(yaml_path: Path) -> dict[str, dict[str, str]]:
+    sections: dict[str, dict[str, str]] = {}
+    current_section: str | None = None
+
+    for raw_line in yaml_path.read_text().splitlines():
+        if not raw_line.strip():
+            continue
+        if not raw_line.startswith(" "):
+            if not raw_line.endswith(":"):
+                fail(f"{yaml_path} has an invalid top-level line: {raw_line}")
+            current_section = raw_line[:-1]
+            sections[current_section] = {}
+            continue
+
+        if current_section is None:
+            fail(f"{yaml_path} has indented fields before a top-level section")
+
+        match = FIELD_PATTERN.match(raw_line.strip())
+        if not match:
+            fail(f"{yaml_path} has an invalid field line: {raw_line}")
+        key, value = match.groups()
+        if value.startswith('"') and value.endswith('"'):
+            value = value[1:-1]
+        sections[current_section][key] = value
+
+    return sections
+
+
+def require_file(path: Path) -> None:
+    if not path.is_file():
+        fail(f"Required file is missing: {path}")
+
+
+def run_help(command: list[str], cwd: Path) -> None:
+    result = subprocess.run(command, cwd=str(cwd), capture_output=True, text=True)
+    if result.returncode != 0:
+        details = result.stderr.strip() or result.stdout.strip()
+        fail(f"Command failed: {' '.join(command)}\n{details}")
+
+
+def main() -> int:
+    args = parse_args()
+    repo_root = Path(args.repo_root).resolve()
+
+    skill_path = repo_root / "SKILL.md"
+    readme_path = repo_root / "README.md"
+    openai_path = repo_root / "agents" / "openai.yaml"
+    install_script = repo_root / "scripts" / "install_skill.py"
+    repair_script = repo_root / "scripts" / "repair_codex_desktop_threads.py"
+    banner_path = repo_root / "assets" / "codex-thread-rescue-banner.svg"
+    icon_path = repo_root / "assets" / "codex-thread-rescue-icon.svg"
+    logo_path = repo_root / "assets" / "codex-thread-rescue-logo.svg"
+
+    for path in [skill_path, readme_path, openai_path, install_script, repair_script, banner_path, icon_path, logo_path]:
+        require_file(path)
+
+    frontmatter = parse_skill_frontmatter(skill_path)
+    if frontmatter.get("name") != "codex--thread-rescue--skill":
+        fail("SKILL.md frontmatter name must be codex--thread-rescue--skill")
+    if "description" not in frontmatter or len(frontmatter["description"]) < 40:
+        fail("SKILL.md frontmatter description is missing or too short")
+
+    readme_text = readme_path.read_text()
+    for needle in [
+        "$codex--thread-rescue--skill",
+        "scripts/install_skill.py",
+        "## FAQ",
+        "## Quick start",
+    ]:
+        if needle not in readme_text:
+            fail(f"README.md is missing expected content: {needle}")
+
+    sections = parse_openai_yaml(openai_path)
+    interface = sections.get("interface", {})
+    policy = sections.get("policy", {})
+
+    required_interface = {
+        "display_name": "Codex Thread Rescue",
+        "short_description": "Bring back missing Codex Desktop threads",
+        "icon_small": "./assets/codex-thread-rescue-icon.svg",
+        "icon_large": "./assets/codex-thread-rescue-logo.svg",
+        "brand_color": "#7FF2C4",
+    }
+    for key, expected in required_interface.items():
+        if interface.get(key) != expected:
+            fail(f"agents/openai.yaml interface.{key} must be {expected!r}")
+
+    default_prompt = interface.get("default_prompt", "")
+    if "$codex--thread-rescue--skill" not in default_prompt:
+        fail("agents/openai.yaml default_prompt must mention $codex--thread-rescue--skill")
+    if policy.get("allow_implicit_invocation") != "true":
+        fail("agents/openai.yaml policy.allow_implicit_invocation must be true")
+
+    run_help(["python3", str(install_script), "--help"], repo_root)
+    run_help(["python3", str(repair_script), "--help"], repo_root)
+
+    print("[OK] Skill metadata and bundled scripts validated successfully.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())