Skip to content

Free, open source blog writer for Claude Code. Researches current sources, writes answer-first posts for Google and AI answers, has an independent reviewer score each one out of 100 and ships only after five delivery gates. 32 skills, 30 /blog commands, 5 agents. Active development at AI-Marketing-Hub/claude-blog; public releases ship here.

17.7 KB
Raw Blame
#!/usr/bin/env python3
"""Validate a prepared public claude-blog release worktree.

This read-only check prevents private raw URLs, private marketplace slugs, and
membership-only install instructions from leaking into the public mirror.
Run it against the prepared public worktree, never as a validator for the
private source tree.
"""

from __future__ import annotations

import argparse
import json
import re
import sys
from pathlib import Path

PUBLIC_REPOSITORY = "https://github.com/AgriciDaniel/claude-blog"
PUBLIC_VERSION = "2.3.2"
PUBLIC_PLUGIN_IDENTIFIER = "claude-blog"
PUBLIC_SLUG = f"{PUBLIC_PLUGIN_IDENTIFIER}@agricidaniel-blog"
PUBLIC_OWNER = "AgriciDaniel"
PUBLIC_OWNER_URL = "https://github.com/AgriciDaniel"
PUBLIC_MARKETPLACE = "agricidaniel-blog"
# Blog Studio is served from the blog-studio branch of this repository, pinned
# to a commit, because Claude Desktop refuses a plugin folder that holds a
# nested .claude-plugin/plugin.json. The check below reads the entry only; it
# never contacts the network.
STUDIO_PLUGIN = "blog-studio"
STUDIO_SOURCE = {
    "source": "git-subdir",
    "url": "AgriciDaniel/claude-blog",
    "path": "plugins/blog-studio",
    "ref": "blog-studio",
}
STUDIO_HOMEPAGE = f"{PUBLIC_REPOSITORY}/tree/blog-studio/plugins/blog-studio"
COMMIT_SHA_RE = re.compile(r"[0-9a-f]{40}")
PUBLIC_RAW_INSTALL_SH = (
    "https://raw.githubusercontent.com/AgriciDaniel/claude-blog/main/install.sh"
)
PUBLIC_RAW_INSTALL_PS1 = (
    "https://raw.githubusercontent.com/AgriciDaniel/claude-blog/main/install.ps1"
)
PUBLIC_PINNED_INSTALL_SH = (
    f"https://raw.githubusercontent.com/AgriciDaniel/claude-blog/"
    f"v{PUBLIC_VERSION}/install.sh"
)
PUBLIC_DISCUSSIONS = f"{PUBLIC_REPOSITORY}/discussions"
PUBLIC_SECURITY_ADVISORY = f"{PUBLIC_REPOSITORY}/security/advisories/new"
PUBLIC_DOCUMENTATION = f"{PUBLIC_REPOSITORY}/tree/main/docs"
SECURITY_CHECKOUT_GUIDANCE = "git checkout <commit-sha-or-release-tag>"
PREOWNERSHIP_INSTALLER_PIN_RE = re.compile(
    r"(?:git checkout\s+|CLAUDE_BLOG_REF\s*=\s*[\"']?|/claude-blog/)v2\.2\.0(?:/install\.(?:sh|ps1))?\b"
)
SURFACES = (
    "README.md",
    "CLAUDE.md",
    "CITATION.cff",
    "pyproject.toml",
    ".claude-plugin/plugin.json",
    ".claude-plugin/marketplace.json",
    ".github/ISSUE_TEMPLATE/config.yml",
    ".github/SECURITY.md",
    "install.sh",
    "install.ps1",
    "uninstall.sh",
    "uninstall.ps1",
    "skills/blog/SKILL.md",
)
FORBIDDEN_PATTERNS = {
    "private_raw_url": re.compile(
        r"raw\.githubusercontent\.com/AI-Marketing-Hub/claude-blog",
        re.IGNORECASE,
    ),
    "private_repository_url": re.compile(
        r"github\.com/AI-Marketing-Hub/claude-blog",
        re.IGNORECASE,
    ),
    "private_marketplace_slug": re.compile(
        r"claude-blog@ai-marketing-hub-claude-blog",
        re.IGNORECASE,
    ),
    "obsolete_public_slug": re.compile(
        r"claude-blog@agricidaniel-claude-blog",
        re.IGNORECASE,
    ),
    "private_auth_instruction": re.compile(
        r"(?:authenticated\s+`?gh auth login`?|GitHub PAT).{0,100}"
        r"(?:AI-Marketing-Hub|private|org)",
        re.IGNORECASE | re.DOTALL,
    ),
    "private_membership_instruction": re.compile(
        r"(?:requires?\s+(?:an?\s+)?(?:Pro\s+)?membership|"
        r"account\s+is\s+not\s+in\s+the\s+org)",
        re.IGNORECASE,
    ),
}
RAW_INSTALLER_RE = re.compile(
    r"https://raw\.githubusercontent\.com/[^/\s]+/[^/\s]+/"
    r"[^/\s]+/install\.(?:sh|ps1)",
    re.IGNORECASE,
)


def validate(root: Path) -> dict:
    root = root.resolve()
    errors: list[dict] = []
    contents: dict[str, str] = {}
    for relative in SURFACES:
        path = root / relative
        if not path.is_file():
            errors.append({"kind": "missing_release_surface", "file": relative})
            continue
        contents[relative] = path.read_text(encoding="utf-8")

    docs_dir = root / "docs"
    if docs_dir.is_dir():
        for path in docs_dir.rglob("*.md"):
            relative = path.relative_to(root).as_posix()
            contents.setdefault(relative, path.read_text(encoding="utf-8"))
            if path.name.startswith("PUBLIC-BACKLOG-TRIAGE-"):
                errors.append({"kind": "private_triage_note", "file": relative})

    # Inspect maintained execution and instruction surfaces as well as the
    # canonical release metadata. Historical raw captures and test fixtures
    # are evidence, and are intentionally outside this distribution check.
    for directory, patterns in {
        "skills": ("*.md", "*.py", "*.json", "*.txt"),
        "agents": ("*.md",),
        "scripts": ("*.py", "*.ps1"),
        "data": ("*.json",),
        ".github/workflows": ("*.yml", "*.yaml"),
    }.items():
        for pattern in patterns:
            for path in (root / directory).rglob(pattern):
                if path.is_symlink() or any(part in {".venv", "__pycache__"} for part in path.parts):
                    continue
                relative = path.relative_to(root).as_posix()
                contents.setdefault(relative, path.read_text(encoding="utf-8"))

    for relative, text in contents.items():
        if relative == "scripts/validate_public_release.py":
            # The detector's own forbidden-pattern definitions contain the
            # strings they must reject elsewhere. Keep scanning its runtime
            # code, excluding only this declarative pattern table.
            text = re.sub(
                r"(?ms)^FORBIDDEN_PATTERNS = \{.*?(?=^RAW_INSTALLER_RE =)",
                "", text,
            )
        for kind, pattern in FORBIDDEN_PATTERNS.items():
            if kind == "private_repository_url" and relative.startswith("docs/"):
                # Attribution and migration history may legitimately mention
                # the private repository. Canonical distribution surfaces may
                # not identify it as the public package.
                continue
            if pattern.search(text):
                errors.append({"kind": kind, "file": relative})

    readme = contents.get("README.md", "")
    if PUBLIC_SLUG not in readme:
        errors.append(
            {
                "kind": "missing_public_marketplace_slug",
                "file": "README.md",
                "expected": PUBLIC_SLUG,
            }
        )
    if PUBLIC_REPOSITORY not in readme:
        errors.append(
            {
                "kind": "missing_public_repository_url",
                "file": "README.md",
                "expected": PUBLIC_REPOSITORY,
            }
        )
    for expected in (PUBLIC_RAW_INSTALL_SH, PUBLIC_RAW_INSTALL_PS1):
        if expected not in readme:
            errors.append(
                {
                    "kind": "missing_exact_public_raw_installer",
                    "file": "README.md",
                    "expected": expected,
                }
            )

    version_fragments = {
        "README.md": (
            "git checkout <commit-sha-or-release-tag>",
            "CLAUDE_BLOG_REF=<commit-sha-or-release-tag>",
        ),
        "CLAUDE.md": ("CLAUDE_BLOG_REF=<commit-sha-or-release-tag>",),
        "CITATION.cff": (f"version: {PUBLIC_VERSION}",),
        "pyproject.toml": (f'version = "{PUBLIC_VERSION}"',),
        ".claude-plugin/plugin.json": (f'"version": "{PUBLIC_VERSION}"',),
        "install.sh": (f'CLAUDE_BLOG_VERSION="{PUBLIC_VERSION}"',),
        "install.ps1": (f'$ClaudeBlogVersion = "{PUBLIC_VERSION}"',),
        "skills/blog/SKILL.md": (f'version: "{PUBLIC_VERSION}"',),
    }
    for relative, expected_fragments in version_fragments.items():
        text = contents.get(relative, "")
        for expected in expected_fragments:
            if expected not in text:
                errors.append(
                    {
                        "kind": "invalid_public_release_version",
                        "file": relative,
                        "expected": expected,
                    }
                )

    # v2.2.0 predates the ownership-aware installer, and its uninstall.sh runs
    # an unguarded recursive delete. Install documentation must not pin to it.
    for relative in ("README.md", "CLAUDE.md", "docs/INSTALLATION.md", ".github/SECURITY.md"):
        for match in PREOWNERSHIP_INSTALLER_PIN_RE.finditer(contents.get(relative, "")):
            errors.append(
                {
                    "kind": "unsafe_preownership_installer_pin",
                    "file": relative,
                    "actual": match.group(0),
                }
            )

    citation = contents.get("CITATION.cff", "")
    # SECURITY.md must give the same pin-a-reviewed-ref guidance as the README
    # and must never tell users to run the v2.2.0 installer (checked above).
    security = contents.get(".github/SECURITY.md", "")
    if SECURITY_CHECKOUT_GUIDANCE not in security:
        errors.append(
            {
                "kind": "invalid_public_security_guidance",
                "file": ".github/SECURITY.md",
                "expected": SECURITY_CHECKOUT_GUIDANCE,
            }
        )

    expected_citation_repository = f'repository-code: "{PUBLIC_REPOSITORY}"'
    if expected_citation_repository not in citation:
        errors.append(
            {
                "kind": "invalid_public_citation_repository",
                "file": "CITATION.cff",
                "expected": expected_citation_repository,
            }
        )

    issue_config = contents.get(".github/ISSUE_TEMPLATE/config.yml", "")
    for expected in (
        PUBLIC_DISCUSSIONS,
        PUBLIC_SECURITY_ADVISORY,
        PUBLIC_DOCUMENTATION,
    ):
        if expected not in issue_config:
            errors.append(
                {
                    "kind": "invalid_public_issue_routing",
                    "file": ".github/ISSUE_TEMPLATE/config.yml",
                    "expected": expected,
                }
            )

    expected_installer_urls = {
        "install.sh": PUBLIC_RAW_INSTALL_SH,
        "install.ps1": PUBLIC_RAW_INSTALL_PS1,
    }
    for relative, expected in expected_installer_urls.items():
        text = contents.get(relative, "")
        if expected not in text:
            errors.append(
                {
                    "kind": "missing_exact_public_raw_installer",
                    "file": relative,
                    "expected": expected,
                }
            )
        if "AgriciDaniel/claude-blog" not in text:
            errors.append(
                {
                    "kind": "invalid_public_installer_owner",
                    "file": relative,
                    "expected": "AgriciDaniel/claude-blog",
                }
            )

    for relative, text in contents.items():
        for found in RAW_INSTALLER_RE.findall(text):
            if found not in {
                PUBLIC_RAW_INSTALL_SH,
                PUBLIC_RAW_INSTALL_PS1,
                PUBLIC_PINNED_INSTALL_SH,
            }:
                errors.append(
                    {
                        "kind": "wrong_public_raw_installer_url",
                        "file": relative,
                        "actual": found,
                    }
                )

    pyproject = contents.get("pyproject.toml", "")
    canonical_fields = ("homepage", "repository", "issues", "documentation", "changelog")
    for field in canonical_fields:
        pattern = re.compile(
            rf"^{field}\s*=\s*[\"']{re.escape(PUBLIC_REPOSITORY)}(?:[^\"']*)[\"']",
            re.MULTILINE,
        )
        if not pattern.search(pyproject):
            errors.append(
                {
                    "kind": "invalid_public_canonical",
                    "file": "pyproject.toml",
                    "field": field,
                }
            )

    plugin_text = contents.get(".claude-plugin/plugin.json", "")
    try:
        plugin = json.loads(plugin_text)
    except json.JSONDecodeError:
        errors.append(
            {"kind": "invalid_json", "file": ".claude-plugin/plugin.json"}
        )
    else:
        expected_plugin = {
            "name": PUBLIC_PLUGIN_IDENTIFIER,
            "homepage": PUBLIC_REPOSITORY,
            "repository": PUBLIC_REPOSITORY,
        }
        for field, expected in expected_plugin.items():
            if plugin.get(field) != expected:
                errors.append(
                    {
                        "kind": "invalid_public_plugin_ownership",
                        "file": ".claude-plugin/plugin.json",
                        "field": field,
                        "expected": expected,
                    }
                )
        author = plugin.get("author")
        if not isinstance(author, dict) or author.get("name") != PUBLIC_OWNER:
            errors.append(
                {
                    "kind": "invalid_public_plugin_ownership",
                    "file": ".claude-plugin/plugin.json",
                    "field": "author.name",
                    "expected": PUBLIC_OWNER,
                }
            )
        if not isinstance(author, dict) or author.get("url") != PUBLIC_OWNER_URL:
            errors.append(
                {
                    "kind": "invalid_public_plugin_ownership",
                    "file": ".claude-plugin/plugin.json",
                    "field": "author.url",
                    "expected": PUBLIC_OWNER_URL,
                }
            )

    marketplace_text = contents.get(".claude-plugin/marketplace.json", "")
    try:
        marketplace = json.loads(marketplace_text)
        if not isinstance(marketplace, dict):
            raise ValueError("marketplace must be an object")
    except ValueError:  # JSONDecodeError is a ValueError
        errors.append(
            {"kind": "invalid_json", "file": ".claude-plugin/marketplace.json"}
        )
    else:
        owner = marketplace.get("owner")
        plugins = marketplace.get("plugins")
        if marketplace.get("name") != PUBLIC_MARKETPLACE:
            errors.append(
                {
                    "kind": "invalid_public_marketplace_ownership",
                    "file": ".claude-plugin/marketplace.json",
                    "field": "name",
                    "expected": PUBLIC_MARKETPLACE,
                }
            )
        if not isinstance(owner, dict) or owner.get("name") != PUBLIC_OWNER:
            errors.append(
                {
                    "kind": "invalid_public_marketplace_ownership",
                    "file": ".claude-plugin/marketplace.json",
                    "field": "owner.name",
                    "expected": PUBLIC_OWNER,
                }
            )
        if (
            not isinstance(plugins, list)
            or not any(
                isinstance(entry, dict)
                and entry.get("name") == PUBLIC_PLUGIN_IDENTIFIER
                and entry.get("source") == "./"
                for entry in plugins
            )
        ):
            errors.append(
                {
                    "kind": "invalid_public_marketplace_plugin",
                    "file": ".claude-plugin/marketplace.json",
                }
            )
        entries = [entry for entry in plugins if isinstance(entry, dict)] if isinstance(plugins, list) else []
        # Only claude-blog may live inside the plugin root; any other local
        # source would put a second plugin.json inside the claude-blog folder.
        for entry in entries:
            if entry.get("name") != PUBLIC_PLUGIN_IDENTIFIER and not isinstance(entry.get("source"), dict):
                errors.append(
                    {
                        "kind": "local_companion_source",
                        "file": ".claude-plugin/marketplace.json",
                        "plugin": str(entry.get("name")),
                    }
                )
        studio_entries = [entry for entry in entries if entry.get("name") == STUDIO_PLUGIN]
        if studio_entries:
            studio = studio_entries[0]
            source = studio.get("source")
            if (
                len(studio_entries) != 1
                or not isinstance(source, dict)
                or set(source) != {*STUDIO_SOURCE, "sha"}
                or any(source.get(key) != value for key, value in STUDIO_SOURCE.items())
                or not isinstance(source.get("sha"), str)
                or not COMMIT_SHA_RE.fullmatch(source["sha"])
                or not isinstance(studio.get("version"), str)
                or studio.get("homepage") != STUDIO_HOMEPAGE
            ):
                errors.append(
                    {
                        "kind": "invalid_studio_distribution",
                        "file": ".claude-plugin/marketplace.json",
                        "plugin": STUDIO_PLUGIN,
                    }
                )

    root_manifest = root / ".claude-plugin" / "plugin.json"
    for manifest in sorted(root.rglob("plugin.json")):
        relative_parts = set(manifest.relative_to(root).parts)
        if (
            manifest.parent.name == ".claude-plugin"
            and manifest != root_manifest
            and not {".git", ".venv", "node_modules"} & relative_parts
        ):
            errors.append(
                {
                    "kind": "nested_plugin_manifest",
                    "file": manifest.relative_to(root).as_posix(),
                }
            )

    return {
        "status": "pass" if not errors else "fail",
        "root": str(root),
        "errors": errors,
        "summary": {"errors": len(errors), "surfaces_checked": len(contents)},
    }


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        description="Validate a prepared public claude-blog release worktree."
    )
    parser.add_argument("--root", type=Path, required=True)
    parser.add_argument("--compact", action="store_true", help="Emit compact JSON.")
    args = parser.parse_args(argv)
    report = validate(args.root)
    print(json.dumps(report, indent=None if args.compact else 2, sort_keys=True))
    return 0 if report["status"] == "pass" else 1


if __name__ == "__main__":
    sys.exit(main())