frontmatter-guard 0.1.0__tar.gz

frontmatter_guard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hao li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

frontmatter_guard-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: frontmatter-guard
+Version: 0.1.0
+Summary: Semantic linter for Claude Code skill/plugin frontmatter — catches silent key typos official validators miss
+Author: hao li
+License: MIT
+Project-URL: Homepage, https://github.com/hahahahahahahahah6/frontmatter-guard
+Keywords: claude-code,frontmatter,linter,skills,plugins,developer-tools
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# frontmatter-guard
+
+A semantic linter for Claude Code skill/plugin frontmatter. Catches the silent
+mistakes the official validator waves through.
+
+## The problem
+
+`claude plugin validate` checks that your plugin is structurally compatible.
+It does **not** check that your frontmatter keys actually mean anything. I
+found this out the embarrassing way: I had written `effort: high` in a command
+frontmatter, expecting it to constrain the model. `claude plugin validate`
+passed it without a word. In reality `effort` is not a Claude Code frontmatter
+key at all — it is a Codex concept — so my setting silently fell back to the
+session default and I had no idea.
+
+Misspelled keys and misspelled hook events fail the same silent way:
+`PreToolUs` never fires, `licence` never licenses anything, and nothing ever
+tells you.
+
+frontmatter-guard closes that gap: it knows the real key vocabulary and the
+real hook event list, and it tells you — with `file:line`, a rule name, and a
+fix suggestion — when something you wrote does nothing.
+
+## Install
+
+```bash
+pip install frontmatter-guard
+```
+
+Zero dependencies. Python 3.9+. Works anywhere, including pre-commit and CI.
+
+## Quickstart
+
+```bash
+# lint one file or a whole directory
+frontmatter-guard check SKILL.md
+frontmatter-guard check .claude/ --strict
+
+# machine-readable output for CI
+frontmatter-guard check . --format json
+```
+
+Example output:
+
+```
+commands/deploy.md:4: error [unknown-key] Unknown key 'effort'.
+    fix: Remove the key -- unknown keys are silently ignored, so it currently does nothing.
+commands/deploy.md:5: error [unknown-key] Unknown key 'licence'. Did you mean 'license'?
+    fix: Rename 'licence' to 'license'. Unknown keys are silently ignored, so fix the typo or remove the key.
+commands/deploy.md:7: error [unknown-hook-event] Unknown hook event 'PreToolUs'. Did you mean 'PreToolUse'?
+    fix: Rename 'PreToolUs' to 'PreToolUse'. Unknown hook events never fire.
+frontmatter-guard: 3 error(s), 0 warning(s) in 1 file(s)
+```
+
+Exit codes are CI-ready: exit `1` when any error-level finding exists (or any
+warning under `--strict`); exit `0` when clean; exit `2` on usage errors.
+
+## Rules
+
+| Rule | Severity | What it catches |
+|------|----------|-----------------|
+| `unknown-key` | error | Top-level key not in the known skill/plugin vocabulary. Suggests the closest real key via difflib ("Did you mean 'license'?"). |
+| `unknown-hook-event` | error | Hook event name not in Claude Code's event list (`PreToolUse`, `PostToolUse`, `SessionStart`, …). Unknown events never fire. |
+| `missing-required` | error | `name` or `description` absent or empty. |
+| `bad-version` | warning | `version` that isn't semver-ish (`1.2.3`, `v0.1`, `2.0.0-beta`). |
+| `bad-type` | warning | Value of the wrong type (`hooks:` as a string, `name:` as a number, …). |
+| `parse-warning` | warning | Frontmatter uses YAML beyond the supported subset — the file is still linted, not crashed. |
+
+Scans `*.md` frontmatter (`---` fences) and `plugin.json` files. The built-in
+YAML parser is stdlib-only and covers the shapes frontmatter actually uses:
+scalars, block maps/sequences, inline flow collections, literal blocks.
+Anything fancier gets a warning, never an exception.
+
+## How it differs
+
+- **vs `claude plugin validate` (official):** the official validator checks
+  compatibility and structure — "will this plugin load?" frontmatter-guard
+  checks semantic strictness — "does everything you wrote actually do
+  something?" Unknown keys sail through the official check silently; they
+  fail here.
+- **vs damson/skill-lint:** that project is a CI action doing structural
+  checks on skills. frontmatter-guard is a local, stdlib-only CLI doing
+  *semantic* checks (typo suggestions, event-name validation, type/format
+  checks). Use it in pre-commit for instant feedback *and* in CI for
+  enforcement — same command, both places.
+
+## CI integration
+
+GitHub Actions:
+
+```yaml
+- name: Lint skill/plugin frontmatter
+  run: |
+    pip install frontmatter-guard
+    frontmatter-guard check . --strict
+```
+
+pre-commit:
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: frontmatter-guard
+        name: frontmatter-guard
+        entry: frontmatter-guard check
+        language: system
+        types: [markdown]
+        args: [--strict]
+```
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests   # 34 tests, stdlib only
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

frontmatter_guard-0.1.0/README.md

@@ -0,0 +1,120 @@
+# frontmatter-guard
+
+A semantic linter for Claude Code skill/plugin frontmatter. Catches the silent
+mistakes the official validator waves through.
+
+## The problem
+
+`claude plugin validate` checks that your plugin is structurally compatible.
+It does **not** check that your frontmatter keys actually mean anything. I
+found this out the embarrassing way: I had written `effort: high` in a command
+frontmatter, expecting it to constrain the model. `claude plugin validate`
+passed it without a word. In reality `effort` is not a Claude Code frontmatter
+key at all — it is a Codex concept — so my setting silently fell back to the
+session default and I had no idea.
+
+Misspelled keys and misspelled hook events fail the same silent way:
+`PreToolUs` never fires, `licence` never licenses anything, and nothing ever
+tells you.
+
+frontmatter-guard closes that gap: it knows the real key vocabulary and the
+real hook event list, and it tells you — with `file:line`, a rule name, and a
+fix suggestion — when something you wrote does nothing.
+
+## Install
+
+```bash
+pip install frontmatter-guard
+```
+
+Zero dependencies. Python 3.9+. Works anywhere, including pre-commit and CI.
+
+## Quickstart
+
+```bash
+# lint one file or a whole directory
+frontmatter-guard check SKILL.md
+frontmatter-guard check .claude/ --strict
+
+# machine-readable output for CI
+frontmatter-guard check . --format json
+```
+
+Example output:
+
+```
+commands/deploy.md:4: error [unknown-key] Unknown key 'effort'.
+    fix: Remove the key -- unknown keys are silently ignored, so it currently does nothing.
+commands/deploy.md:5: error [unknown-key] Unknown key 'licence'. Did you mean 'license'?
+    fix: Rename 'licence' to 'license'. Unknown keys are silently ignored, so fix the typo or remove the key.
+commands/deploy.md:7: error [unknown-hook-event] Unknown hook event 'PreToolUs'. Did you mean 'PreToolUse'?
+    fix: Rename 'PreToolUs' to 'PreToolUse'. Unknown hook events never fire.
+frontmatter-guard: 3 error(s), 0 warning(s) in 1 file(s)
+```
+
+Exit codes are CI-ready: exit `1` when any error-level finding exists (or any
+warning under `--strict`); exit `0` when clean; exit `2` on usage errors.
+
+## Rules
+
+| Rule | Severity | What it catches |
+|------|----------|-----------------|
+| `unknown-key` | error | Top-level key not in the known skill/plugin vocabulary. Suggests the closest real key via difflib ("Did you mean 'license'?"). |
+| `unknown-hook-event` | error | Hook event name not in Claude Code's event list (`PreToolUse`, `PostToolUse`, `SessionStart`, …). Unknown events never fire. |
+| `missing-required` | error | `name` or `description` absent or empty. |
+| `bad-version` | warning | `version` that isn't semver-ish (`1.2.3`, `v0.1`, `2.0.0-beta`). |
+| `bad-type` | warning | Value of the wrong type (`hooks:` as a string, `name:` as a number, …). |
+| `parse-warning` | warning | Frontmatter uses YAML beyond the supported subset — the file is still linted, not crashed. |
+
+Scans `*.md` frontmatter (`---` fences) and `plugin.json` files. The built-in
+YAML parser is stdlib-only and covers the shapes frontmatter actually uses:
+scalars, block maps/sequences, inline flow collections, literal blocks.
+Anything fancier gets a warning, never an exception.
+
+## How it differs
+
+- **vs `claude plugin validate` (official):** the official validator checks
+  compatibility and structure — "will this plugin load?" frontmatter-guard
+  checks semantic strictness — "does everything you wrote actually do
+  something?" Unknown keys sail through the official check silently; they
+  fail here.
+- **vs damson/skill-lint:** that project is a CI action doing structural
+  checks on skills. frontmatter-guard is a local, stdlib-only CLI doing
+  *semantic* checks (typo suggestions, event-name validation, type/format
+  checks). Use it in pre-commit for instant feedback *and* in CI for
+  enforcement — same command, both places.
+
+## CI integration
+
+GitHub Actions:
+
+```yaml
+- name: Lint skill/plugin frontmatter
+  run: |
+    pip install frontmatter-guard
+    frontmatter-guard check . --strict
+```
+
+pre-commit:
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: frontmatter-guard
+        name: frontmatter-guard
+        entry: frontmatter-guard check
+        language: system
+        types: [markdown]
+        args: [--strict]
+```
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests   # 34 tests, stdlib only
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

frontmatter_guard-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "frontmatter-guard"
+version = "0.1.0"
+description = "Semantic linter for Claude Code skill/plugin frontmatter — catches silent key typos official validators miss"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "hao li" }]
+keywords = ["claude-code", "frontmatter", "linter", "skills", "plugins", "developer-tools"]
+
+[project.scripts]
+frontmatter-guard = "frontmatter_guard.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/hahahahahahahahah6/frontmatter-guard"
+
+[tool.setuptools.packages.find]
+where = ["src"]

frontmatter_guard-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

frontmatter_guard-0.1.0/src/frontmatter_guard/__init__.py

@@ -0,0 +1,5 @@
+"""frontmatter-guard: semantic linter for Claude Code skill/plugin frontmatter."""
+
+__version__ = "0.1.0"
+
+from .schema import lint_frontmatter  # noqa: F401

frontmatter_guard-0.1.0/src/frontmatter_guard/__main__.py

@@ -0,0 +1,5 @@
+"""Allow `python -m frontmatter_guard`."""
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

frontmatter_guard-0.1.0/src/frontmatter_guard/cli.py

@@ -0,0 +1,201 @@
+"""Command-line interface for frontmatter-guard."""
+
+import argparse
+import json
+import os
+import sys
+
+from . import __version__
+from .schema import (
+    SEVERITY_ERROR,
+    SEVERITY_WARNING,
+    extract_md_frontmatter,
+    lint_frontmatter,
+)
+
+SCAN_EXTENSIONS = (".md",)
+SCAN_FILENAMES = ("plugin.json",)
+
+
+def iter_target_files(path):
+    """Yield (path) for every scannable file under path."""
+    if os.path.isfile(path):
+        yield path
+        return
+    for root, dirs, files in os.walk(path):
+        dirs[:] = [d for d in dirs
+                   if d not in (".git", "__pycache__", "node_modules",
+                                ".venv", "venv", "dist", "build")]
+        for name in sorted(files):
+            full = os.path.join(root, name)
+            if name.endswith(SCAN_EXTENSIONS) or name in SCAN_FILENAMES:
+                yield full
+
+
+def lint_file(path):
+    """Lint one file. Returns a list of finding dicts."""
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            text = handle.read()
+    except (OSError, UnicodeDecodeError) as exc:
+        return [{
+            "file": path,
+            "line": 1,
+            "rule": "unreadable",
+            "severity": SEVERITY_ERROR,
+            "message": "Could not read file: %s" % exc,
+            "fix": "Check file permissions and encoding (UTF-8 expected).",
+        }]
+
+    findings = []
+    name = os.path.basename(path)
+
+    if name.endswith(".md"):
+        extracted = extract_md_frontmatter(text)
+        if extracted is None:
+            if name == "SKILL.md":
+                findings.append({
+                    "file": path,
+                    "line": 1,
+                    "rule": "no-frontmatter",
+                    "severity": SEVERITY_WARNING,
+                    "message": "SKILL.md has no frontmatter block.",
+                    "fix": "Add a --- fenced frontmatter block with at "
+                           "least name and description.",
+                })
+            return findings
+        data, key_lines, start_line, parse_warnings = extracted
+        for warning in parse_warnings:
+            findings.append({
+                "file": path,
+                "line": start_line,
+                "rule": "parse-warning",
+                "severity": SEVERITY_WARNING,
+                "message": "Frontmatter YAML: %s." % warning,
+                "fix": "Simplify the frontmatter to plain key: value pairs, "
+                       "lists and nested maps.",
+            })
+        findings.extend(lint_frontmatter(data, key_lines, path, start_line))
+        return findings
+
+    # plugin.json and friends: JSON object, same key vocabulary
+    try:
+        data = json.loads(text)
+    except ValueError as exc:
+        return [{
+            "file": path,
+            "line": 1,
+            "rule": "parse-warning",
+            "severity": SEVERITY_ERROR,
+            "message": "Invalid JSON: %s" % exc,
+            "fix": "Fix the JSON syntax.",
+        }]
+    if not isinstance(data, dict):
+        return [{
+            "file": path,
+            "line": 1,
+            "rule": "bad-type",
+            "severity": SEVERITY_ERROR,
+            "message": "Top-level JSON value must be an object.",
+            "fix": "Make the top level a JSON object with plugin keys.",
+        }]
+    key_lines = {key: 1 for key in data}
+    return lint_frontmatter(data, key_lines, path, start_line=1)
+
+
+def check_targets(targets):
+    findings = []
+    files = []
+    for target in targets:
+        if not os.path.exists(target):
+            return None, ["no such file or directory: %s" % target]
+        for path in iter_target_files(target):
+            files.append(path)
+            findings.extend(lint_file(path))
+    return (files, findings), []
+
+
+def format_text(files, findings):
+    out = []
+    for finding in findings:
+        out.append("%s:%s: %s [%s] %s"
+                   % (finding["file"], finding["line"],
+                      finding["severity"], finding["rule"],
+                      finding["message"]))
+        if finding.get("fix"):
+            out.append("    fix: %s" % finding["fix"])
+    errors = sum(1 for f in findings if f["severity"] == SEVERITY_ERROR)
+    warnings = sum(1 for f in findings if f["severity"] == SEVERITY_WARNING)
+    out.append("frontmatter-guard: %d error(s), %d warning(s) in %d file(s)"
+               % (errors, warnings, len(files)))
+    return "\n".join(out)
+
+
+def format_json(files, findings):
+    errors = sum(1 for f in findings if f["severity"] == SEVERITY_ERROR)
+    warnings = sum(1 for f in findings if f["severity"] == SEVERITY_WARNING)
+    return json.dumps({
+        "tool": "frontmatter-guard",
+        "version": __version__,
+        "files": files,
+        "findings": findings,
+        "summary": {
+            "files": len(files),
+            "errors": errors,
+            "warnings": warnings,
+        },
+    }, indent=2)
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="frontmatter-guard",
+        description="Semantic linter for Claude Code skill/plugin "
+                    "frontmatter.")
+    parser.add_argument("--version", action="version",
+                        version="frontmatter-guard %s" % __version__)
+    sub = parser.add_subparsers(dest="command")
+    check = sub.add_parser("check", help="Lint frontmatter in a file or "
+                                         "directory.")
+    check.add_argument("targets", nargs="+",
+                       help="File(s) or directorie(s) to scan.")
+    check.add_argument("--format", choices=("text", "json"), default="text",
+                       help="Output format (default: text).")
+    check.add_argument("--strict", action="store_true",
+                       help="Treat warnings as failures (exit 1).")
+    return parser
+
+
+def main(argv=None):
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command != "check":
+        parser.print_help()
+        return 2
+
+    result, errors = check_targets(args.targets)
+    if result is None:
+        for error in errors:
+            print("frontmatter-guard: error: %s" % error, file=sys.stderr)
+        return 2
+    files, findings = result
+
+    if args.format == "json":
+        print(format_json(files, findings))
+    else:
+        print(format_text(files, findings))
+
+    error_count = sum(1 for f in findings
+                      if f["severity"] == SEVERITY_ERROR)
+    warning_count = sum(1 for f in findings
+                        if f["severity"] == SEVERITY_WARNING)
+    if error_count > 0:
+        return 1
+    if args.strict and warning_count > 0:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())