Chrome Extensions (MV3) skill for Codex

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Chrome Extensions (MV3)"
  short_description: "Manifest V3 extensions that survive the service worker"
  default_prompt: "$chrome-extensions Build a Chrome extension that saves highlighted text from any page to a side panel"

#!/usr/bin/env python3
"""Lint a Chrome extension's manifest.json for Manifest V3 mistakes.

Usage: python3 check_manifest.py <extension-dir-or-manifest.json>

Checks MV3 structure, MV2 leftovers, permission placement and breadth, file references
and Chrome Web Store length limits. Prints ERROR/WARN lines; exits 1 if any ERROR.
Standard library only. Point it at the built output folder (dist/) when using a bundler.
"""
from __future__ import annotations

import json
import os
import re
import sys

BROAD_HOSTS = {"<all_urls>", "*://*/*", "http://*/*", "https://*/*"}
SENSITIVE = {
    "tabs": "exposes URL/title of every tab; activeTab is often enough",
    "history": "full browsing history",
    "cookies": "cookie access for granted hosts",
    "webRequest": "observes all traffic for granted hosts; prefer declarativeNetRequest",
    "debugger": "full control of pages; triggers a prominent warning",
    "downloads": "download management",
    "management": "can list and disable other extensions",
    "nativeMessaging": "talks to native apps",
    "clipboardRead": "reads clipboard",
}
MV2_ONLY_KEYS = {
    "browser_action": "use 'action'",
    "page_action": "use 'action'",
}
VERSION_RE = re.compile(r"^\d{1,5}(\.\d{1,5}){0,3}$")


def main(argv: list[str]) -> int:
    if len(argv) != 1:
        print(__doc__.strip(), file=sys.stderr)
        return 2
    target = argv[0]
    path = os.path.join(target, "manifest.json") if os.path.isdir(target) else target
    root = os.path.dirname(os.path.abspath(path))
    try:
        with open(path, encoding="utf-8") as fh:
            m = json.load(fh)
    except FileNotFoundError:
        print(f"ERROR no manifest at {path}")
        return 1
    except json.JSONDecodeError as exc:
        print(f"ERROR manifest.json is not valid JSON (comments are not allowed): {exc}")
        return 1

    errors: list[str] = []
    warns: list[str] = []
    err = errors.append
    warn = warns.append

    def must_exist(rel: str, what: str) -> None:
        if not isinstance(rel, str):
            return
        if re.match(r"^[a-z]+://", rel):
            err(f"{what} '{rel}' is a remote URL; MV3 forbids remotely hosted code")
            return
        if not os.path.exists(os.path.join(root, rel.lstrip("/"))):
            err(f"{what} '{rel}' does not exist relative to manifest.json")

    if m.get("manifest_version") != 3:
        err(f"manifest_version is {m.get('manifest_version')!r}, expected 3")
    for key in ("name", "version"):
        if not m.get(key):
            err(f"missing required key '{key}'")
    version = str(m.get("version", ""))
    if version and not VERSION_RE.match(version):
        err(f"version '{version}' must be 1-4 dot-separated integers (no -beta suffixes; use version_name)")
    elif version and any(int(p) > 65535 for p in version.split(".")):
        err(f"version '{version}' has a part above 65535")
    name = m.get("name", "")
    if isinstance(name, str) and not name.startswith("__MSG_") and len(name) > 75:
        err(f"name is {len(name)} chars; the limit is 75")
    desc = m.get("description", "")
    if not desc:
        warn("no description; the Chrome Web Store requires one")
    elif isinstance(desc, str) and not desc.startswith("__MSG_") and len(desc) > 132:
        err(f"description is {len(desc)} chars; the limit is 132")

    for key, hint in MV2_ONLY_KEYS.items():
        if key in m:
            err(f"'{key}' is Manifest V2; {hint}")

    bg = m.get("background")
    if isinstance(bg, dict):
        if "persistent" in bg:
            err("background.persistent is MV2; MV3 service workers are always event-driven")
        if "scripts" in bg or "page" in bg:
            if "service_worker" in bg:
                warn("background has both scripts and service_worker; Chrome uses service_worker, Firefox uses scripts")
            else:
                err("background.scripts/page are not supported by Chrome MV3; use background.service_worker")
        if "service_worker" in bg:
            must_exist(bg["service_worker"], "background.service_worker")

    action = m.get("action", {}) or {}
    if "default_popup" in action:
        must_exist(action["default_popup"], "action.default_popup")
    icon_sets = [m.get("icons", {}), action.get("default_icon", {}) if isinstance(action.get("default_icon"), dict) else {}]
    for icons in icon_sets:
        for size, rel in (icons or {}).items():
            must_exist(rel, f"icon {size}")
    if not m.get("icons"):
        warn("no top-level icons; provide at least 16, 48 and 128")
    for key in ("options_page",):
        if key in m:
            must_exist(m[key], key)
    if isinstance(m.get("options_ui"), dict):
        must_exist(m["options_ui"].get("page"), "options_ui.page")
    if isinstance(m.get("side_panel"), dict):
        must_exist(m["side_panel"].get("default_path"), "side_panel.default_path")
        if "sidePanel" not in m.get("permissions", []):
            err("side_panel is declared but the 'sidePanel' permission is missing")

    perms = m.get("permissions", []) or []
    hosts = m.get("host_permissions", []) or []
    for p in perms:
        if "://" in p or p == "<all_urls>":
            err(f"permission '{p}' is a host pattern; move it to host_permissions")
        if p == "webRequestBlocking":
            err("webRequestBlocking is not available to normal MV3 extensions; use declarativeNetRequest")
        if p in SENSITIVE:
            warn(f"permission '{p}': {SENSITIVE[p]}")
    if "scripting" in perms and not hosts and "activeTab" not in perms:
        warn("'scripting' without host_permissions or activeTab cannot inject anywhere")
    for h in hosts + (m.get("optional_host_permissions", []) or []):
        if h in BROAD_HOSTS:
            warn(f"broad host permission '{h}': triggers in-depth review; prefer specific hosts, activeTab or optional_host_permissions")

    for i, cs in enumerate(m.get("content_scripts", []) or []):
        if not cs.get("matches"):
            err(f"content_scripts[{i}] has no 'matches'")
        for kind in ("js", "css"):
            for rel in cs.get(kind, []) or []:
                must_exist(rel, f"content_scripts[{i}].{kind}")
        for pat in cs.get("matches", []):
            if pat in BROAD_HOSTS:
                warn(f"content_scripts[{i}] runs on '{pat}'; consider narrowing or injecting on demand")

    war = m.get("web_accessible_resources")
    if war is not None:
        if not isinstance(war, list) or any(not isinstance(x, dict) for x in war):
            err("web_accessible_resources must be a list of objects with 'resources' and 'matches' (MV3 format)")
        else:
            for i, entry in enumerate(war):
                if not entry.get("matches") and not entry.get("extension_ids"):
                    err(f"web_accessible_resources[{i}] needs 'matches' or 'extension_ids'")

    csp = m.get("content_security_policy")
    if csp is not None:
        if isinstance(csp, str):
            err("content_security_policy must be an object ({extension_pages: ...}) in MV3")
        elif isinstance(csp, dict):
            pages = csp.get("extension_pages", "")
            if "unsafe-eval" in pages.replace("wasm-unsafe-eval", "") or re.search(r"https?://", pages):
                err("extension_pages CSP may not allow unsafe-eval or remote script sources in MV3")

    for line in errors:
        print(f"ERROR {line}")
    for line in warns:
        print(f"WARN  {line}")
    print(f"\n{len(errors)} error(s), {len(warns)} warning(s) in {path}")
    return 1 if errors else 0


if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))