#!/usr/bin/env python3 from __future__ import annotations import argparse import json import re import sys import zipfile import struct from pathlib import Path from tempfile import TemporaryDirectory VERSION = "0.5.0" MARKER = "MEMORY_KEEPER_V4_2026-09-17" REQUIRED_SKILLS = { "using-memory-keeper", "maintaining-project-memory", "auditing-persistent-state", "organizing-persistent-files", "repairing-memory-state", "recovering-persistent-work", "verifying-persistent-work", "maintaining-memory-keeper", } FORBIDDEN_PARTS = {"__pycache__"} FORBIDDEN_SUFFIXES = {".pyc", ".pyo", ".tmp"} OPENAI_CATEGORIES = { "Productivity", "Creativity", "Developer Tools", "Business & Operations", "Data & Analytics", "Communication", "Education & Research", "Security", "Finance", "Healthcare", "Travel", "Entertainment", "Other", } def _openai_interface(manifest: dict, codex: dict) -> dict: ext = manifest.get("extensions") if isinstance(ext, dict): oa = ext.get("com.openai") if isinstance(oa, dict): iface = oa.get("interface") if isinstance(iface, dict): return iface iface = codex.get("interface") if isinstance(codex, dict) else None return iface if isinstance(iface, dict) else {} def _png_dimensions(path: Path) -> tuple[int, int] | None: try: data = path.read_bytes()[:24] except OSError: return None if len(data) < 24 or data[:8] != b"\x89PNG\r\n\x1a\n" or data[12:16] != b"IHDR": return None return struct.unpack(">II", data[16:24]) def lint_openai_directory_metadata(plugin: Path, manifest: dict, codex: dict, errors: list[str]) -> None: author = manifest.get("author") if not isinstance(author, dict) or not isinstance(author.get("name"), str) or not author["name"].strip(): fail(errors, "author.name missing") iface = _openai_interface(manifest, codex) if not iface: fail(errors, "OpenAI interface missing") return def req_text(key: str, max_len: int, *, label: str | None = None) -> None: value = iface.get(key) label = label or key if not isinstance(value, str) or not value.strip(): fail(errors, f"{label} missing") elif "\n" in value or "\r" in value: fail(errors, f"{label} must be one line") elif len(value) > max_len: fail(errors, f"{label} exceeds {max_len} characters") req_text("displayName", 30) req_text("shortDescription", 30) req_text("developerName", 80) long_description = iface.get("longDescription") if not isinstance(long_description, str) or not long_description.strip(): fail(errors, "longDescription missing") elif len(long_description) > 4000: fail(errors, "longDescription exceeds 4000 characters") category = iface.get("category") if category is not None and category not in OPENAI_CATEGORIES: fail(errors, f"unsupported OpenAI category: {category}") capabilities = iface.get("capabilities", []) if not isinstance(capabilities, list): fail(errors, "capabilities must be a list") else: if len(capabilities) > 20: fail(errors, "capabilities has more than 20 entries") for value in capabilities: if not isinstance(value, str) or not value.strip() or "\n" in value or "\r" in value or len(value) > 120: fail(errors, "capability entry is invalid") prompts = iface.get("defaultPrompt", []) if not isinstance(prompts, list): fail(errors, "defaultPrompt must be a list") else: if len(prompts) > 3: fail(errors, "defaultPrompt has more than 3 entries") normalized: list[str] = [] for prompt in prompts: if not isinstance(prompt, str) or not prompt.strip() or "\n" in prompt or "\r" in prompt or len(prompt) > 128: fail(errors, "defaultPrompt entry is invalid") continue if re.search(r"(^|\s)@\S+", prompt): fail(errors, "defaultPrompt contains @mention") normalized.append(" ".join(prompt.split())) if len(normalized) != len(set(normalized)): fail(errors, "defaultPrompt contains duplicates") brand = iface.get("brandColor") if brand is not None and (not isinstance(brand, str) or not re.fullmatch(r"#[0-9A-Fa-f]{6}", brand)): fail(errors, "brandColor must be #RRGGBB") for key in ("composerIcon", "logo"): rel = iface.get(key) if not isinstance(rel, str) or not rel.strip(): fail(errors, f"{key} missing") continue if not rel.startswith("./") or ".." in Path(rel).parts: fail(errors, f"{key} path is invalid") continue asset = plugin / rel[2:] if not asset.is_file(): fail(errors, f"{key} file missing: {rel}") continue if asset.stat().st_size > 5 * 1024 * 1024: fail(errors, f"{key} exceeds 5 MiB") if asset.suffix.lower() == ".png": dims = _png_dimensions(asset) if dims is None: fail(errors, f"{key} PNG is unreadable") else: w, h = dims if w != h: fail(errors, f"{key} image is not square") if w < 48 or w > 4096: fail(errors, f"{key} dimensions outside 48..4096") def fail(errors: list[str], msg: str) -> None: errors.append(msg) def find_plugin_root(root: Path) -> Path | None: if (root / "plugin.json").is_file() and (root / "skills").is_dir(): return root nested = root / "plugins" / "memory-keeper" if (nested / "plugin.json").is_file(): return nested matches = [p for p in root.rglob("plugin.json") if p.parent.name == "memory-keeper" or (p.parent / "skills").is_dir()] return matches[0].parent if len(matches) == 1 else None def lint_tree(root: Path) -> list[str]: errors: list[str] = [] plugin = find_plugin_root(root) skills_root = (plugin / "skills") if plugin else (root / "skills") fallback_bundle = plugin is None and skills_root.is_dir() if not plugin and not fallback_bundle: return ["cannot resolve Memory Keeper plugin root or skills fallback bundle"] for p in root.rglob("*"): if any(part in FORBIDDEN_PARTS for part in p.parts): fail(errors, f"forbidden cache path: {p.relative_to(root)}") if p.is_file() and (p.suffix.lower() in FORBIDDEN_SUFFIXES or p.name.endswith("~")): fail(errors, f"forbidden generated/temp file: {p.relative_to(root)}") if p.is_file() and p.suffix.lower() == ".zip" and p != root: fail(errors, f"nested release ZIP is forbidden: {p.relative_to(root)}") if plugin: try: manifest = json.loads((plugin / "plugin.json").read_text(encoding="utf-8")) codex = json.loads((plugin / ".codex-plugin" / "plugin.json").read_text(encoding="utf-8")) except Exception as exc: return errors + [f"manifest parse failure: {exc}"] if manifest.get("version") != VERSION: fail(errors, f"plugin.json version != {VERSION}") if codex.get("version") != VERSION: fail(errors, f".codex-plugin/plugin.json version != {VERSION}") lint_openai_directory_metadata(plugin, manifest, codex, errors) corpus_manifest = json.dumps(manifest).lower() + json.dumps(codex).lower() if "mcp" in corpus_manifest: fail(errors, "MCP declaration found in skills-only plugin") skills = { p.name for p in skills_root.iterdir() if p.is_dir() and (p / "SKILL.md").is_file() } if skills != REQUIRED_SKILLS: fail(errors, f"skill set mismatch: {sorted(skills)}") for name in REQUIRED_SKILLS: path = skills_root / name / "SKILL.md" if not path.is_file(): fail(errors, f"missing required skill: {name}") continue content = path.read_text(encoding="utf-8", errors="replace") if not re.search(rf"(?m)^name:\s*{re.escape(name)}\s*$", content): fail(errors, f"skill frontmatter name mismatch: {name}") m = re.search(r"(?m)^description:\s*(.+)$", content) if not m or not m.group(1).strip('"').startswith("Use when"): fail(errors, f"skill description is not trigger-shaped: {name}") docs = [] for name in ("README.md", "MEMORY_KEEPER_SPEC.md", "MEMOIRE_GLOBALE.md", "SUBMISSION.md", "INSTALL.md"): candidates = [root / name] + ([plugin / name] if plugin else []) for c in candidates: if c.is_file(): docs.append(c.read_text(encoding="utf-8", errors="replace")) break corpus = "\n".join(docs) if docs and VERSION not in corpus: fail(errors, f"documentation missing version {VERSION}") if docs and MARKER not in corpus: fail(errors, f"documentation missing marker {MARKER}") marker_re = re.compile(r"MEMORY_KEEPER_V\d+_\d{4}-\d{2}-\d{2}") for text_path in root.rglob("*"): if not text_path.is_file() or text_path.suffix.lower() not in {".md", ".json", ".py"}: continue try: text = text_path.read_text(encoding="utf-8", errors="replace") except OSError as exc: fail(errors, f"cannot inspect text file {text_path.relative_to(root)}: {exc}") continue for found in marker_re.findall(text): if found != MARKER: fail(errors, f"stale diagnostic marker {found}: {text_path.relative_to(root)}") return sorted(set(errors)) def lint_zip(path: Path) -> list[str]: try: with TemporaryDirectory(prefix="mk-lint-") as td: base = Path(td).resolve() with zipfile.ZipFile(path) as zf: for member in zf.infolist(): target = (base / member.filename).resolve() try: target.relative_to(base) except ValueError: return [f"unsafe ZIP member path: {member.filename}"] zf.extractall(td) return lint_tree(base) except (zipfile.BadZipFile, OSError) as exc: return [f"cannot read ZIP: {exc}"] def main() -> int: ap = argparse.ArgumentParser(description="Lint Memory Keeper package/source tree") ap.add_argument("path") args = ap.parse_args() path = Path(args.path).resolve() errors = lint_zip(path) if path.is_file() and path.suffix.lower() == ".zip" else lint_tree(path) if errors: print("Memory Keeper package lint: FAIL") for e in errors: print("ERROR:", e) return 1 print("Memory Keeper package lint: PASS") return 0 if __name__ == "__main__": raise SystemExit(main())