@event4u/agent-config 1.9.1

package/scripts/install_anthropic_key.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# Interactive Anthropic-API-key installer for scripts/skill_trigger_eval.py.
+#
+# Reads the key with `read -s` so it never echoes to the terminal and
+# never lands in shell history or scrollback. Writes atomically to
+# ~/.config/agent-config/anthropic.key with mode 0600.
+#
+# Contract — companion to scripts/skill_trigger_eval.py:
+#   - File path:  $HOME/.config/agent-config/anthropic.key
+#   - File mode:  0600 (owner read/write only)
+#   - Key format: must start with `sk-ant-`
+#   - No --force, no --yes, no env-var bypass. Piped stdin is rejected.
+#
+# The runner re-checks all of the above at every live invocation and
+# refuses to run if the file drifts from this contract.
+
+set -euo pipefail
+
+TARGET_DIR="${HOME}/.config/agent-config"
+TARGET_FILE="${TARGET_DIR}/anthropic.key"
+
+# ── controlling-terminal requirement ─────────────────────────────────────
+# We read from /dev/tty directly (fd 3), not from stdin. This is the
+# stricter and more portable contract:
+#   - works under `task`, `script`, `sudo`, anything that reattaches stdin
+#   - forces every character to come from the user's real keyboard, so a
+#     pipe or redirected file cannot smuggle the key into the process
+#   - exits cleanly if there is no controlling terminal at all (e.g. CI,
+#     cron, agent automation)
+if ! exec 3</dev/tty 2>/dev/null; then
+    echo "❌  install_anthropic_key.sh requires a controlling terminal." >&2
+    echo "    /dev/tty not available \u2014 refusing to run under automation." >&2
+    exit 2
+fi
+
+# ── overwrite confirmation ───────────────────────────────────────────────
+if [[ -e "${TARGET_FILE}" ]]; then
+    echo "⚠️   ${TARGET_FILE} already exists."
+    printf "Overwrite? [type 'yes' to replace, anything else aborts]: "
+    read -r -u 3 answer
+    if [[ "${answer}" != "yes" ]]; then
+        echo "Aborted. Existing key untouched."
+        exit 0
+    fi
+fi
+
+# ── read key (no echo, no history) ───────────────────────────────────────
+echo "Paste your Anthropic API key (input is hidden, no echo)."
+echo "The key should start with 'sk-ant-'."
+printf "Key: "
+# -s = silent (no echo), read from fd 3 = /dev/tty, not stdin.
+read -r -s -u 3 API_KEY
+echo
+
+if [[ -z "${API_KEY}" ]]; then
+    echo "❌  Empty input — no file written." >&2
+    exit 2
+fi
+
+if [[ "${API_KEY}" != sk-ant-* ]]; then
+    echo "❌  Input does not look like an Anthropic key (missing 'sk-ant-' prefix)." >&2
+    echo "    No file written." >&2
+    exit 2
+fi
+
+# ── create config dir with 0700, atomic write with 0600 ──────────────────
+mkdir -p "${TARGET_DIR}"
+chmod 0700 "${TARGET_DIR}"
+
+TMP_FILE="$(mktemp "${TARGET_DIR}/.anthropic.key.XXXXXX")"
+cleanup() { rm -f "${TMP_FILE}"; }
+trap cleanup EXIT
+
+# chmod the tmpfile BEFORE writing the key, so there is no window where
+# the key sits on disk with group/other-readable permissions.
+chmod 0600 "${TMP_FILE}"
+printf '%s\n' "${API_KEY}" > "${TMP_FILE}"
+mv "${TMP_FILE}" "${TARGET_FILE}"
+trap - EXIT
+
+# Clear the variable and the `mv` positional argument — defence in depth
+# against a crash handler that dumps the process environment.
+API_KEY=""
+
+# ── verify mode post-write (portable stat: BSD on macOS, GNU on Linux) ───
+if ACTUAL_MODE=$(stat -f '%Lp' "${TARGET_FILE}" 2>/dev/null); then
+    :  # macOS / BSD
+else
+    ACTUAL_MODE=$(stat -c '%a' "${TARGET_FILE}")
+fi
+
+if [[ "${ACTUAL_MODE}" != "600" ]]; then
+    echo "❌  Permissions verification failed: ${TARGET_FILE} has mode ${ACTUAL_MODE}, expected 600." >&2
+    echo "    Delete and reinstall:  rm ${TARGET_FILE} && $0" >&2
+    exit 3
+fi
+
+echo "✅  Key installed: ${TARGET_FILE} (mode 0600)."
+echo "    Verify:  ls -la ${TARGET_FILE}"
+echo "    Rotate:  rerun this script (you'll be prompted to overwrite)."
+echo "    Remove:  rm ${TARGET_FILE}"

package/scripts/inventory_frontmatter.py

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""
+Inventory frontmatter keys across all agent artefacts.
+
+Reads .agent-src.uncompressed/{skills,rules,commands,personas}, parses the
+YAML frontmatter of every file, and prints per-type:
+
+- total file count
+- every key observed, with count and percentage
+- sample values (up to 3) per key
+
+Output is Markdown on stdout, intended to be captured into
+`agents/docs/frontmatter-contract.md` as raw material for Phase 1 of the
+frontmatter-schema roadmap.
+
+Stdlib-only. No PyYAML — we do a simple line-based parse sufficient for
+our frontmatter shapes (flat keys, inline lists, block lists, one nested
+`execution:` block).
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from collections import Counter, defaultdict
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SRC = ROOT / ".agent-src.uncompressed"
+
+FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)
+
+
+def extract_frontmatter(text: str) -> str | None:
+    match = FRONTMATTER_RE.search(text)
+    return match.group(1) if match else None
+
+
+def parse_frontmatter_keys(fm: str) -> dict[str, str]:
+    """Return a flat {key: raw_value_string} for a frontmatter block.
+
+    For nested blocks (e.g. `execution:`), the nested keys are flattened
+    with a dot notation: `execution.type`, `execution.handler`, etc.
+    Inline lists (`personas: [a, b]`) and block lists (`- a\n- b`) are
+    rendered as their raw value.
+    """
+    result: dict[str, str] = {}
+    lines = fm.splitlines()
+    i = 0
+    current_nested: str | None = None
+    current_list_key: str | None = None
+    list_buffer: list[str] = []
+
+    def flush_list() -> None:
+        nonlocal current_list_key, list_buffer
+        if current_list_key is not None:
+            result[current_list_key] = "[" + ", ".join(list_buffer) + "]"
+        current_list_key = None
+        list_buffer = []
+
+    while i < len(lines):
+        line = lines[i]
+        stripped = line.strip()
+
+        if not stripped or stripped.startswith("#"):
+            i += 1
+            continue
+
+        # Top-level key (no leading whitespace)
+        if line and not line[0].isspace():
+            flush_list()
+            current_nested = None
+            m = re.match(r"^([\w-]+):\s*(.*?)\s*$", line)
+            if m:
+                key, value = m.group(1), m.group(2)
+                if value == "" or value == "|":
+                    # Could start a nested block OR a list. Look ahead.
+                    nxt = lines[i + 1].strip() if i + 1 < len(lines) else ""
+                    if nxt.startswith("- "):
+                        current_list_key = key
+                    else:
+                        current_nested = key
+                        result[key] = "{nested}"
+                else:
+                    result[key] = value
+        # Nested (indented) key
+        elif current_nested is not None:
+            m = re.match(r"^\s+([\w-]+):\s*(.*?)\s*$", line)
+            if m:
+                key, value = m.group(1), m.group(2)
+                result[f"{current_nested}.{key}"] = value or "{nested}"
+        # Block list item
+        elif current_list_key is not None and stripped.startswith("- "):
+            list_buffer.append(stripped[2:].strip())
+
+        i += 1
+
+    flush_list()
+    return result
+
+
+def gather_files(artefact_dir: Path, pattern: str) -> list[Path]:
+    if not artefact_dir.exists():
+        return []
+    files = [f for f in artefact_dir.rglob(pattern) if not f.is_symlink()]
+    return sorted(files)
+
+
+def inventory_type(name: str, files: list[Path]) -> None:
+    total = len(files)
+    print(f"### {name} — {total} files\n")
+    if total == 0:
+        print("_(no files)_\n")
+        return
+
+    key_counts: Counter[str] = Counter()
+    key_value_counts: dict[str, Counter[str]] = defaultdict(Counter)
+
+    for f in files:
+        text = f.read_text(encoding="utf-8")
+        fm = extract_frontmatter(text)
+        if fm is None:
+            continue
+        parsed = parse_frontmatter_keys(fm)
+        for k, v in parsed.items():
+            key_counts[k] += 1
+            # Record distinct values for enum detection; truncate to keep
+            # the table readable and strip surrounding quotes.
+            normalized = v.strip('"').strip("'")[:80] if v else "{empty}"
+            key_value_counts[k][normalized] += 1
+
+    print("| key | count | % | status | distinct values (count) |")
+    print("|---|---:|---:|---|---|")
+    for key, count in sorted(key_counts.items(), key=lambda kv: (-kv[1], kv[0])):
+        pct = count * 100 // total
+        status = "required" if pct >= 95 else "optional"
+        values = key_value_counts[key]
+        if len(values) <= 8:
+            rendered = " · ".join(f"`{val}` ({n})" for val, n in values.most_common())
+        else:
+            top = values.most_common(5)
+            rendered = " · ".join(f"`{val}` ({n})" for val, n in top)
+            rendered += f" · … +{len(values) - 5} more"
+        print(f"| `{key}` | {count} | {pct}% | {status} | {rendered} |")
+    print()
+
+
+def main() -> int:
+    print("# Frontmatter inventory (generated)\n")
+    print("Generated by `scripts/inventory_frontmatter.py`. Raw material for")
+    print("Phase 1 of the frontmatter-schema roadmap. Do not edit by hand.\n")
+
+    inventory_type("skills", gather_files(SRC / "skills", "SKILL.md"))
+    inventory_type("rules", gather_files(SRC / "rules", "*.md"))
+    inventory_type("commands", gather_files(SRC / "commands", "*.md"))
+    inventory_type("personas", [
+        f for f in gather_files(SRC / "personas", "*.md")
+        if f.name.lower() != "readme.md"
+    ])
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_marketplace.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""
+Lint .claude-plugin/marketplace.json for the event4u/agent-config package.
+
+Validates the Claude Code Plugin Marketplace manifest against the canonical
+shape used by anthropics/skills:
+
+  - Required top-level fields: name, owner, metadata, plugins
+  - owner must have name + email
+  - metadata must have description + version
+  - metadata.version must match package.json (single source of truth)
+  - every plugins[].skills[] entry must exist on disk and carry a SKILL.md
+
+Exit codes: 0 = clean, 1 = problems found, 3 = internal error.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(".")
+MARKETPLACE = ROOT / ".claude-plugin" / "marketplace.json"
+PACKAGE_JSON = ROOT / "package.json"
+
+
+def fail(errors: list[str]) -> int:
+    print("❌  marketplace.json has problems:")
+    for e in errors:
+        print(f"  - {e}")
+    return 1
+
+
+def require_key(obj: dict, key: str, where: str, errors: list[str]) -> bool:
+    if key not in obj:
+        errors.append(f"missing key `{key}` in {where}")
+        return False
+    return True
+
+
+def main() -> int:
+    if not MARKETPLACE.exists():
+        print(f"❌  {MARKETPLACE} not found")
+        return 1
+
+    try:
+        data = json.loads(MARKETPLACE.read_text())
+    except json.JSONDecodeError as e:
+        print(f"❌  {MARKETPLACE} is not valid JSON: {e}")
+        return 1
+
+    errors: list[str] = []
+
+    # Top-level required fields
+    for k in ("name", "owner", "metadata", "plugins"):
+        require_key(data, k, "marketplace root", errors)
+
+    # Owner
+    owner = data.get("owner", {})
+    if isinstance(owner, dict):
+        for k in ("name", "email"):
+            require_key(owner, k, "owner", errors)
+    else:
+        errors.append("`owner` must be an object")
+
+    # Metadata + version sync
+    metadata = data.get("metadata", {})
+    if isinstance(metadata, dict):
+        for k in ("description", "version"):
+            require_key(metadata, k, "metadata", errors)
+        mp_version = metadata.get("version")
+        if mp_version and PACKAGE_JSON.exists():
+            pkg = json.loads(PACKAGE_JSON.read_text())
+            pkg_version = pkg.get("version")
+            if pkg_version and mp_version != pkg_version:
+                errors.append(
+                    f"metadata.version `{mp_version}` does not match "
+                    f"package.json version `{pkg_version}`"
+                )
+    else:
+        errors.append("`metadata` must be an object")
+
+    # Plugins
+    plugins = data.get("plugins", [])
+    if not isinstance(plugins, list) or not plugins:
+        errors.append("`plugins` must be a non-empty array")
+        plugins = []
+
+    for idx, plugin in enumerate(plugins):
+        where = f"plugins[{idx}]"
+        if not isinstance(plugin, dict):
+            errors.append(f"{where} must be an object")
+            continue
+        for k in ("name", "description", "source", "skills"):
+            require_key(plugin, k, where, errors)
+
+        skills = plugin.get("skills", [])
+        if not isinstance(skills, list):
+            errors.append(f"{where}.skills must be an array")
+            continue
+
+        seen: set[str] = set()
+        for s_idx, path in enumerate(skills):
+            entry = f"{where}.skills[{s_idx}]"
+            if not isinstance(path, str):
+                errors.append(f"{entry} must be a string")
+                continue
+            if path in seen:
+                errors.append(f"{entry} is a duplicate: `{path}`")
+            seen.add(path)
+
+            # Resolve path relative to repo root (strip leading "./" only,
+            # NOT every "." and "/" character)
+            rel = path.removeprefix("./")
+            skill_dir = ROOT / rel
+            if not skill_dir.exists():
+                errors.append(f"{entry} path does not exist: `{path}`")
+                continue
+            skill_md = skill_dir / "SKILL.md"
+            if not skill_md.exists():
+                errors.append(f"{entry} has no SKILL.md: `{path}`")
+
+    if errors:
+        return fail(errors)
+
+    plugin_count = len(plugins)
+    skill_count = sum(len(p.get("skills", [])) for p in plugins if isinstance(p, dict))
+    print(
+        f"✅  marketplace.json ({plugin_count} plugin"
+        f"{'s' if plugin_count != 1 else ''}, {skill_count} skills total)"
+    )
+    print("  No issues found.")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as exc:  # pragma: no cover
+        print(f"❌  internal error: {exc}", file=sys.stderr)
+        sys.exit(3)

package/scripts/lint_regression.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""Detect lint regressions between the current branch and a baseline (default: main).
+
+Runs skill_linter.py --all --format json on both the baseline and current branch,
+then compares results to find:
+- New failures (file did not fail before, fails now)
+- Status downgrades (pass → warn, warn → fail, pass → fail)
+- New issues (issue codes that appeared on existing files)
+- Status upgrades (fail → warn, warn → pass, fail → pass) — shown as improvements
+
+Usage:
+    python3 scripts/lint_regression.py [--baseline main] [--format text|json|markdown]
+
+Requires: git, python3, scripts/skill_linter.py
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+
+def run_linter_json(ref: str | None, repo_root: Path) -> dict:
+    """Run the linter and return parsed JSON. If ref is None, run on working tree."""
+    env_cmd = []
+    if ref:
+        # Run linter at a specific git ref using git stash + checkout
+        # Instead, use git show to avoid checkout — run on working tree after git stash
+        pass
+
+    cmd = [sys.executable, str(repo_root / "scripts" / "skill_linter.py"), "--all", "--format", "json",
+           "--repo-root", str(repo_root)]
+
+    if ref:
+        # Strategy: create a temp worktree at the ref, run linter there, clean up
+        with tempfile.TemporaryDirectory(prefix="lint-baseline-") as tmpdir:
+            subprocess.run(
+                ["git", "-C", str(repo_root), "worktree", "add", "--detach", tmpdir, ref],
+                capture_output=True, check=True
+            )
+            try:
+                result = subprocess.run(
+                    [sys.executable, str(repo_root / "scripts" / "skill_linter.py"),
+                     "--all", "--format", "json", "--repo-root", tmpdir],
+                    capture_output=True, text=True, cwd=tmpdir
+                )
+                return json.loads(result.stdout) if result.stdout.strip() else {"results": [], "summary": {}}
+            finally:
+                subprocess.run(
+                    ["git", "-C", str(repo_root), "worktree", "remove", "--force", tmpdir],
+                    capture_output=True
+                )
+    else:
+        result = subprocess.run(cmd, capture_output=True, text=True, cwd=str(repo_root))
+        return json.loads(result.stdout) if result.stdout.strip() else {"results": [], "summary": {}}
+
+
+def build_status_map(data: dict) -> dict[str, dict]:
+    """Build {file: {status, issue_codes}} from linter JSON output."""
+    result = {}
+    for entry in data.get("results", []):
+        f = entry["file"]
+        codes = {i["code"] for i in entry.get("issues", [])}
+        result[f] = {"status": entry["status"], "codes": codes}
+    return result
+
+
+STATUS_ORDER = {"pass": 0, "pass_with_warnings": 1, "fail": 2}
+
+
+def compare(baseline: dict[str, dict], current: dict[str, dict]) -> dict:
+    """Compare baseline and current lint results."""
+    regressions = []
+    improvements = []
+    new_files = []
+
+    all_files = sorted(set(baseline.keys()) | set(current.keys()))
+
+    for f in all_files:
+        base = baseline.get(f)
+        curr = current.get(f)
+
+        if curr and not base:
+            if curr["status"] != "pass":
+                new_files.append({"file": f, "status": curr["status"], "codes": sorted(curr["codes"])})
+            continue
+
+        if base and not curr:
+            continue  # File removed — not a regression
+
+        base_order = STATUS_ORDER.get(base["status"], 0)
+        curr_order = STATUS_ORDER.get(curr["status"], 0)
+
+        if curr_order > base_order:
+            new_codes = curr["codes"] - base["codes"]
+            regressions.append({
+                "file": f,
+                "was": base["status"],
+                "now": curr["status"],
+                "new_codes": sorted(new_codes),
+            })
+        elif curr_order < base_order:
+            removed_codes = base["codes"] - curr["codes"]
+            improvements.append({
+                "file": f,
+                "was": base["status"],
+                "now": curr["status"],
+                "removed_codes": sorted(removed_codes),
+            })
+
+    return {"regressions": regressions, "improvements": improvements, "new_files": new_files}
+
+
+def format_text(delta: dict) -> str:
+    lines = ["=== Lint Regression Report ===", ""]
+
+    if not delta["regressions"] and not delta["new_files"]:
+        lines.append("✅  No regressions detected.")
+    else:
+        if delta["regressions"]:
+            lines.append(f"❌  {len(delta['regressions'])} regression(s):")
+            for r in delta["regressions"]:
+                codes = ", ".join(r["new_codes"]) if r["new_codes"] else "(same codes, stricter)"
+                lines.append(f"  {r['file']}: {r['was']} → {r['now']}  [{codes}]")
+            lines.append("")
+
+        if delta["new_files"]:
+            lines.append(f"⚠️  {len(delta['new_files'])} new file(s) with issues:")
+            for nf in delta["new_files"]:
+                lines.append(f"  {nf['file']}: {nf['status']}  [{', '.join(nf['codes'])}]")
+            lines.append("")
+
+    if delta["improvements"]:
+        lines.append(f"✅  {len(delta['improvements'])} improvement(s):")
+        for imp in delta["improvements"]:
+            lines.append(f"  {imp['file']}: {imp['was']} → {imp['now']}")
+
+    return "\n".join(lines)
+
+
+def format_markdown(delta: dict) -> str:
+    lines = ["## 📊 Lint Regression Report", ""]
+
+    if not delta["regressions"] and not delta["new_files"]:
+        lines.append("✅ No regressions detected.")
+    else:
+        if delta["regressions"]:
+            n = len(delta["regressions"])
+            lines.extend([
+                "<details>",
+                f"<summary>❌ {n} Regression{'s' if n != 1 else ''}</summary>",
+                "",
+                "| File | Was | Now | New Issues |",
+                "|---|---|---|---|",
+            ])
+            for r in delta["regressions"]:
+                codes = ", ".join(r["new_codes"]) if r["new_codes"] else "—"
+                lines.append(f"| `{r['file']}` | {r['was']} | {r['now']} | {codes} |")
+            lines.extend(["", "</details>", ""])
+
+        if delta["new_files"]:
+            n = len(delta["new_files"])
+            lines.extend([
+                "<details>",
+                f"<summary>⚠️ {n} New file{'s' if n != 1 else ''} with issues</summary>",
+                "",
+                "| File | Status | Issues |",
+                "|---|---|---|",
+            ])
+            for nf in delta["new_files"]:
+                lines.append(f"| `{nf['file']}` | {nf['status']} | {', '.join(nf['codes'])} |")
+            lines.extend(["", "</details>", ""])
+
+    if delta["improvements"]:
+        n = len(delta["improvements"])
+        lines.extend([
+            "<details>",
+            f"<summary>✅ {n} Improvement{'s' if n != 1 else ''}</summary>",
+            "",
+            "| File | Was | Now |",
+            "|---|---|---|",
+        ])
+        for imp in delta["improvements"]:
+            lines.append(f"| `{imp['file']}` | {imp['was']} | {imp['now']} |")
+        lines.extend(["", "</details>"])
+
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Detect lint regressions between branches.")
+    parser.add_argument("--baseline", default="main", help="Git ref to compare against (default: main)")
+    parser.add_argument("--format", choices=["text", "json", "markdown"], default="text",
+                        help="Output format (default: text)")
+    parser.add_argument("--repo-root", default=".", help="Repository root")
+    args = parser.parse_args()
+
+    root = Path(args.repo_root).resolve()
+
+    print(f"Collecting baseline ({args.baseline})...", file=sys.stderr)
+    try:
+        baseline_data = run_linter_json(args.baseline, root)
+    except subprocess.CalledProcessError:
+        print(f"Error: could not create worktree for '{args.baseline}'. "
+              f"Does the ref exist?", file=sys.stderr)
+        return 2
+
+    print("Collecting current branch...", file=sys.stderr)
+    current_data = run_linter_json(None, root)
+
+    baseline_map = build_status_map(baseline_data)
+    current_map = build_status_map(current_data)
+
+    delta = compare(baseline_map, current_map)
+
+    if args.format == "json":
+        print(json.dumps(delta, indent=2))
+    elif args.format == "markdown":
+        print(format_markdown(delta))
+    else:
+        print(format_text(delta))
+
+    # Exit 1 if regressions found
+    return 1 if delta["regressions"] or delta["new_files"] else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())