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.
Python agent-skillsaiai-citationsai-contentai-marketingai-marketing-hubblogblog-writingclaude-codeclaude-code-skillclaude-pluginclaude-skillcontent-creationcontent-optimizationcontent-strategyeeatgeomultilingualopen-sourceseo
#!/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())