its-magic 0.1.2-9 → 0.1.3-0

package/template/scripts/release_changelog_validate.py

@@ -0,0 +1,134 @@
+#!/usr/bin/env python3
+"""
+Validate release changelog / version-doc consistency (US-0100 / DEC-0085).
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import sys
+
+_SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+_REPO_ROOT = os.path.normpath(os.path.join(_SCRIPT_DIR, ".."))
+if _REPO_ROOT not in sys.path:
+    sys.path.insert(0, _REPO_ROOT)
+if _SCRIPT_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPT_DIR)
+
+import release_changelog_lib as rcl  # noqa: E402
+
+REMEDIATION = {
+    rcl.RELEASE_CHANGELOG_VERSION_MISSING: "Set explicit semver on queue row or pass valid --semver.",
+    rcl.RELEASE_CHANGELOG_DUPLICATE_VERSION: "Resolve fingerprint mismatch; do not reuse semver for different work items.",
+    rcl.RELEASE_CHANGELOG_WORK_ITEM_GAP: "Run derive/build_version_doc or complete sprint notes + backlog refs.",
+    rcl.RELEASE_CHANGELOG_ORDER_INVALID: "Reorder CHANGELOG.md semver sections newest-first.",
+    rcl.RELEASE_CHANGELOG_UNRELEASED_MISSING: "Add mandatory ## [Unreleased] header at top of CHANGELOG.md.",
+    rcl.RELEASE_CHANGELOG_QUEUE_DRIFT: "Re-run bind_queue_release_version or reconcile queue release_version.",
+    rcl.RELEASE_CHANGELOG_VERSION_DOC_MISSING: "Run build_version_doc or release_changelog_backfill before gh -F attach.",
+    rcl.RELEASE_CHANGELOG_SPRINT_ORPHAN: "Include released sprint in semver doc or [Unreleased] via backfill.",
+    rcl.RELEASE_CHANGELOG_BACKFILL_AMBIGUOUS: "Fix manifest collision; one semver intent per coalesce group.",
+    rcl.RELEASE_CHANGELOG_IDEMPOTENCY_VIOLATION: "Remove duplicate work-item bullets for same version; re-run derive.",
+}
+
+
+def _emit(code: str, detail: str = "") -> None:
+    msg = code if not detail else f"{code}: {detail}"
+    print(msg, file=sys.stderr)
+    rem = REMEDIATION.get(code, "See docs/engineering/runbook.md § Version-scoped release docs.")
+    print(f"Remediation: {rem}", file=sys.stderr)
+
+
+def validate(repo_root: str, enforce: bool) -> int:
+    errors: list[str] = []
+    cl_path = rcl.changelog_path(repo_root)
+    if not os.path.isfile(cl_path):
+        errors.append(rcl.RELEASE_CHANGELOG_UNRELEASED_MISSING)
+    else:
+        text = rcl.read_utf8(cl_path)
+        if "## [Unreleased]" not in text:
+            errors.append(rcl.RELEASE_CHANGELOG_UNRELEASED_MISSING)
+        # semver order newest-first (skip Unreleased)
+        versions: list[str] = []
+        for m in re.finditer(r"^##\s+\[(.+?)\]", text, re.MULTILINE):
+            v = m.group(1)
+            if v.lower() == "unreleased":
+                continue
+            try:
+                versions.append(rcl.normalize_semver(v))
+            except rcl.ReleaseChangelogError:
+                errors.append(rcl.RELEASE_CHANGELOG_VERSION_MISSING)
+        # Simple order check: compare as strings after normalization (pre-release aware minimal)
+        if len(versions) > 1:
+            for i in range(len(versions) - 1):
+                if versions[i] < versions[i + 1]:
+                    errors.append(rcl.RELEASE_CHANGELOG_ORDER_INVALID)
+                    break
+
+    rows = rcl.parse_queue_rows(repo_root)
+    for row in rows:
+        if row.status != "released":
+            continue
+        rv = row.release_version.strip()
+        if not rv:
+            continue
+        try:
+            norm = rcl.normalize_semver(rv)
+        except rcl.ReleaseChangelogError:
+            errors.append(rcl.RELEASE_CHANGELOG_VERSION_MISSING)
+            continue
+        vdoc = rcl.version_doc_path(repo_root, norm)
+        if not os.path.isfile(vdoc):
+            errors.append(rcl.RELEASE_CHANGELOG_VERSION_DOC_MISSING)
+        section = rcl.extract_changelog_section(norm, repo_root)
+        if section is None:
+            errors.append(rcl.RELEASE_CHANGELOG_VERSION_MISSING)
+        # work item gap: story_refs should appear in version doc
+        if os.path.isfile(vdoc):
+            doc_text = rcl.read_utf8(vdoc)
+            for token in re.split(r"[,;\s]+", row.story_refs):
+                token = token.strip()
+                if token and token not in doc_text:
+                    errors.append(rcl.RELEASE_CHANGELOG_WORK_ITEM_GAP)
+
+    # queue drift: coalesce groups vs bound semver
+    groups = rcl.coalesce_sprints_by_semver(rows, repo_root)
+    for semver, sids in groups.items():
+        for sid in sids:
+            row = next((r for r in rows if r.sprint_id == sid), None)
+            if row and row.release_version.strip():
+                try:
+                    if rcl.normalize_semver(row.release_version) != semver:
+                        errors.append(rcl.RELEASE_CHANGELOG_QUEUE_DRIFT)
+                except rcl.ReleaseChangelogError:
+                    errors.append(rcl.RELEASE_CHANGELOG_QUEUE_DRIFT)
+
+    seen_errors = sorted(set(errors))
+    for code in seen_errors:
+        _emit(code)
+    if seen_errors and enforce:
+        return 1
+    if not seen_errors:
+        print("[RELEASE_CHANGELOG_VALIDATE_OK]")
+        return 0
+    if not enforce:
+        print("[RELEASE_CHANGELOG_VALIDATE_WARN]")
+        return 0
+    return 1
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--repo", default=_REPO_ROOT, help="Repository root")
+    parser.add_argument(
+        "--enforce",
+        action="store_true",
+        help="Exit non-zero on any fail code (release gate / release-all.sh).",
+    )
+    args = parser.parse_args()
+    return validate(os.path.abspath(args.repo), args.enforce)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/template/scripts/remote_config_summary.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""
+Summarize .cursor/remote.json for operators (US-0084 / US-0064 alignment).
+
+Stdout: non-secret labels and env-reference names only (no key material).
+Stderr: errors and skip reasons.
+
+Exit codes:
+  0 OK or REMOTE_EXECUTION=0 skip (DEC-0070)
+  1 usage / CLI error
+  2 config missing or unreadable
+  3 invalid JSON
+  4 schema / contract mismatch vs runbook remote.json contract
+  5 reserved (unused; DEC-0070 maps REMOTE_EXECUTION=0 to 0)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+ENV_VAR_NAME = re.compile(r"^[A-Z][A-Z0-9_]*$")
+ALLOWED_TYPES = frozenset({"docker", "ssh", "vm"})
+AUTH_MODES = frozenset({"none", "env"})
+
+
+def _truthy_remote_execution(raw: str | None) -> bool:
+    if raw is None:
+        return False
+    return raw.strip() in {"1", "true", "TRUE", "yes", "YES", "on", "ON"}
+
+
+def _parse_args(argv: list[str]) -> tuple[argparse.Namespace, list[str]]:
+    p = argparse.ArgumentParser(description=__doc__.split("\n\n")[0], add_help=True)
+    p.add_argument(
+        "--config",
+        default=None,
+        help="Path to remote JSON (default: REMOTE_CONFIG env or .cursor/remote.json)",
+    )
+    return p.parse_known_args(argv)
+
+
+def _config_path(explicit: str | None) -> Path:
+    if explicit:
+        return Path(explicit).expanduser()
+    env = os.environ.get("REMOTE_CONFIG")
+    if env:
+        return Path(env).expanduser()
+    return Path(".cursor/remote.json")
+
+
+def _validate_env_ref(name: str, value: Any, prefix: str) -> str | None:
+    if not isinstance(value, str):
+        return f"{prefix}: {name} must be a string env-reference name"
+    if not ENV_VAR_NAME.match(value):
+        return f"{prefix}: {name} must look like an env var name (A-Z_0-9)"
+    return None
+
+
+def validate_and_summarize(path: Path, data: dict[str, Any]) -> tuple[list[str], list[str]]:
+    """Return (stdout_lines, error_messages)."""
+    errs: list[str] = []
+    out: list[str] = []
+    out.append(f"remote_config={path.as_posix()}")
+
+    if not isinstance(data.get("version"), int):
+        errs.append("[REMOTE_CONFIG_ERROR] root.version: expected integer")
+    if not isinstance(data.get("defaultTarget"), str) or not data["defaultTarget"]:
+        errs.append("[REMOTE_CONFIG_ERROR] root.defaultTarget: expected non-empty string")
+    targets = data.get("targets")
+    if not isinstance(targets, list) or not targets:
+        errs.append("[REMOTE_CONFIG_ERROR] root.targets: expected non-empty array")
+
+    if errs:
+        return out, errs
+
+    by_id: dict[str, dict[str, Any]] = {}
+    for i, t in enumerate(targets):
+        prefix = f"targets[{i}]"
+        if not isinstance(t, dict):
+            errs.append(f"[REMOTE_CONFIG_ERROR] {prefix}: expected object")
+            continue
+        tid = t.get("id")
+        if not isinstance(tid, str) or not tid:
+            errs.append(f"[REMOTE_CONFIG_ERROR] {prefix}.id: expected non-empty string")
+        ttype = t.get("type")
+        if ttype not in ALLOWED_TYPES:
+            errs.append(
+                f"[REMOTE_CONFIG_ERROR] {prefix}.type: expected one of {sorted(ALLOWED_TYPES)}"
+            )
+        if not isinstance(t.get("enabled"), bool):
+            errs.append(f"[REMOTE_CONFIG_ERROR] {prefix}.enabled: expected boolean")
+        if not isinstance(t.get("host"), str) or not t["host"]:
+            errs.append(f"[REMOTE_CONFIG_ERROR] {prefix}.host: expected non-empty string")
+        port = t.get("port")
+        if not isinstance(port, int) or not (1 <= port <= 65535):
+            errs.append(f"[REMOTE_CONFIG_ERROR] {prefix}.port: expected integer 1..65535")
+        if not isinstance(t.get("workspaceRoot"), str) or not t["workspaceRoot"]:
+            errs.append(
+                f"[REMOTE_CONFIG_ERROR] {prefix}.workspaceRoot: expected non-empty string"
+            )
+        auth = t.get("auth")
+        if auth is not None:
+            if not isinstance(auth, dict):
+                errs.append(f"[REMOTE_CONFIG_ERROR] {prefix}.auth: expected object")
+            else:
+                mode = auth.get("mode")
+                if mode not in AUTH_MODES:
+                    errs.append(
+                        f"[REMOTE_CONFIG_ERROR] {prefix}.auth.mode: expected one of {sorted(AUTH_MODES)}"
+                    )
+                elif mode == "env":
+                    env_keys = (
+                        "tokenEnv",
+                        "passwordEnv",
+                        "privateKeyPathEnv",
+                        "usernameEnv",
+                    )
+                    any_ref = False
+                    for k in env_keys:
+                        if k not in auth:
+                            continue
+                        any_ref = True
+                        err = _validate_env_ref(k, auth[k], f"{prefix}.auth")
+                        if err:
+                            errs.append(f"[REMOTE_CONFIG_ERROR] {err}")
+                    if not any_ref:
+                        errs.append(
+                            f"[REMOTE_CONFIG_ERROR] {prefix}.auth: mode=env requires at least one *Env field"
+                        )
+        if isinstance(tid, str) and tid:
+            by_id[tid] = t
+
+    default = data["defaultTarget"]
+    if default not in by_id:
+        errs.append(
+            f"[REMOTE_CONFIG_ERROR] defaultTarget={default!r} not found in targets[].id"
+        )
+    elif not by_id[default].get("enabled"):
+        errs.append(
+            f"[REMOTE_CONFIG_ERROR] defaultTarget={default!r} must reference an enabled target"
+        )
+
+    if errs:
+        return out, errs
+
+    out.append(f"defaultTarget={data['defaultTarget']}")
+    for t in targets:
+        assert isinstance(t, dict)
+        tid = t["id"]
+        parts = [
+            f"id={tid}",
+            f"type={t['type']}",
+            f"enabled={t['enabled']!s}",
+            f"host={t['host']}",
+            f"port={t['port']}",
+            f"workspaceRoot={t['workspaceRoot']}",
+        ]
+        auth = t.get("auth")
+        if isinstance(auth, dict):
+            parts.append(f"auth.mode={auth.get('mode')}")
+            for k in (
+                "tokenEnv",
+                "passwordEnv",
+                "privateKeyPathEnv",
+                "usernameEnv",
+            ):
+                if k in auth and isinstance(auth[k], str):
+                    parts.append(f"auth.{k}={auth[k]}")
+        out.append("target:" + " ".join(parts))
+
+    return out, []
+
+
+def main(argv: list[str] | None = None) -> int:
+    args, rest = _parse_args(argv or sys.argv[1:])
+    if rest:
+        print(
+            f"[REMOTE_CONFIG_SUMMARY] unknown arguments: {' '.join(rest)}",
+            file=sys.stderr,
+        )
+        return 1
+    if not _truthy_remote_execution(os.environ.get("REMOTE_EXECUTION")):
+        print(
+            "[REMOTE_CONFIG_SUMMARY] REMOTE_EXECUTION!=1: skip validation/summary "
+            "(zero overhead; DEC-0070 / US-0084).",
+            file=sys.stderr,
+        )
+        return 0
+
+    path = _config_path(args.config)
+    if not path.is_file():
+        print(
+            f"[REMOTE_CONFIG_ERROR] {path}: file missing or unreadable. "
+            "Fix: create config or set REMOTE_EXECUTION=0.",
+            file=sys.stderr,
+        )
+        return 2
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except OSError as e:
+        print(
+            f"[REMOTE_CONFIG_ERROR] {path}: read failed ({e}). Fix: permissions/path.",
+            file=sys.stderr,
+        )
+        return 2
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as e:
+        print(
+            f"[REMOTE_CONFIG_ERROR] {path}: invalid JSON ({e}). Fix: syntax.",
+            file=sys.stderr,
+        )
+        return 3
+    if not isinstance(data, dict):
+        print(
+            f"[REMOTE_CONFIG_ERROR] {path}: expected JSON object at root.",
+            file=sys.stderr,
+        )
+        return 4
+
+    lines, errs = validate_and_summarize(path, data)
+    if errs:
+        for line in errs:
+            print(line, file=sys.stderr)
+        print(
+            f"[REMOTE_CONFIG_ERROR] {path}: contract check failed. "
+            "Fix: align with docs/engineering/runbook.md remote contract (US-0084).",
+            file=sys.stderr,
+        )
+        return 4
+    for line in lines:
+        print(line)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/template/scripts/sync_push_gates.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+"""
+Shared sync / push eligibility evaluation for validate-and-push (merged scratchpad).
+
+Imports installer.merge_scratchpad_layers / validate_merged_scratchpad only — no
+duplicate DEC-0055 precedence logic. Emits machine-readable JSON on stdout; reason
+codes only (no planning-shaped tokens) on stderr for errors.
+"""
+
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import List, Tuple
+
+# Repo root (parent of scripts/)
+_ROOT = Path(__file__).resolve().parent.parent
+if str(_ROOT) not in sys.path:
+    sys.path.insert(0, str(_ROOT))
+
+import installer  # noqa: E402
+
+_VALID_MODES = frozenset(
+    {"disabled", "manual", "by_phase", "by_milestone", "custom_phase_list"}
+)
+
+def _parse_csv(val: str) -> List[str]:
+    if not val or not val.strip():
+        return []
+    return [p.strip() for p in val.split(",") if p.strip()]
+
+
+def _merge_and_validate(root: str) -> Tuple[dict, List[str]]:
+    ok, diags = installer.validate_merged_scratchpad(root)
+    if not ok:
+        return {}, diags
+    merged, _paths = installer.merge_scratchpad_layers(root)
+    return merged, []
+
+
+def eval_policy(root: str, _branch: str) -> Tuple[bool, str, List[str]]:
+    """
+    Pre-test gate: merged scratchpad validation + SYNC_POLICY_MODE + ALLOW_AUTO_PUSH
+    + custom_phase_list boundary (SYNC_PHASE_BOUNDARY env).
+    Returns (ok, reason_code, scratchpad_diagnostics).
+    """
+    merged, diags = _merge_and_validate(root)
+    if diags:
+        return False, "SCRATCHPAD_MERGE_ERROR", diags
+
+    mode = (merged.get("SYNC_POLICY_MODE") or "").strip().lower()
+    if not mode or mode not in _VALID_MODES:
+        mode = "manual"
+    if mode == "disabled":
+        return False, "SYNC_DISABLED", []
+    if mode == "manual":
+        return False, "MANUAL_MODE_NO_AUTO", []
+
+    allow = (merged.get("ALLOW_AUTO_PUSH") or "").strip()
+    if allow != "1":
+        return False, "AUTO_PUSH_NOT_ENABLED", []
+
+    if mode == "custom_phase_list":
+        phases = [p.strip().lower() for p in _parse_csv(merged.get("SYNC_CUSTOM_PHASES", ""))]
+        boundary = (os.environ.get("SYNC_PHASE_BOUNDARY") or "").strip().lower()
+        if not boundary:
+            return False, "SYNC_TRIGGER_NOT_ELIGIBLE", []
+        if not phases or boundary not in phases:
+            return False, "SYNC_TRIGGER_NOT_ELIGIBLE", []
+
+    # by_phase / by_milestone: invocation counts as eligible boundary (DEC-0058 §4).
+    return True, "", []
+
+
+def _branch_allowed(branch: str, allowlist_csv: str) -> bool:
+    patterns = _parse_csv(allowlist_csv)
+    if not patterns:
+        return False
+    for pat in patterns:
+        if fnmatch.fnmatchcase(branch, pat):
+            return True
+        if branch == pat:
+            return True
+    return False
+
+
+def _scan_qa_findings_blocking(repo: Path) -> bool:
+    """True if blocking markers found (DEC-0058 §6)."""
+    sprints = repo / "sprints"
+    if not sprints.is_dir():
+        return False
+    for p in sorted(sprints.iterdir()):
+        if not p.is_dir() or len(p.name) != 5 or not p.name.startswith("S"):
+            continue
+        if not p.name[1:].isdigit():
+            continue
+        qf = p / "qa-findings.md"
+        if not qf.is_file():
+            continue
+        text = qf.read_text(encoding="utf-8", errors="replace")
+        if "BLOCKING_QA_FINDINGS" in text:
+            return True
+        in_blocking = False
+        for line in text.splitlines():
+            if re.match(r"^##\s+blocking\s*$", line, re.IGNORECASE):
+                in_blocking = True
+                continue
+            if re.match(r"^##\s+\S", line):
+                in_blocking = False
+            if in_blocking and re.search(r"^-\s+\[\s+\]", line):
+                return True
+            if re.search(r"^-\s+\[\s+\]", line) and re.search(
+                r"BLOCKING|FAIL", line, re.IGNORECASE
+            ):
+                return True
+    return False
+
+
+def _count_sprint_qa_findings(repo: Path) -> int:
+    n = 0
+    sprints = repo / "sprints"
+    if not sprints.is_dir():
+        return 0
+    for p in sprints.iterdir():
+        if not p.is_dir() or len(p.name) != 5 or not p.name.startswith("S"):
+            continue
+        if not p.name[1:].isdigit():
+            continue
+        if (p / "qa-findings.md").is_file():
+            n += 1
+    return n
+
+
+def eval_post_test(root: str, branch: str) -> Tuple[bool, str, List[str]]:
+    """
+    After tests: branch allowlist + PRE_QA + BLOCKING_QA_FINDINGS scan.
+    """
+    merged, diags = _merge_and_validate(root)
+    if diags:
+        return False, "SCRATCHPAD_MERGE_ERROR", diags
+
+    allow_csv = merged.get("AUTO_PUSH_BRANCH_ALLOWLIST") or ""
+    if not _branch_allowed(branch, allow_csv):
+        return False, "BRANCH_NOT_ALLOWLISTED", []
+
+    b = branch.strip()
+    if b not in ("main", "master"):
+        if _count_sprint_qa_findings(Path(root)) == 0:
+            return False, "PRE_QA_AUTOPUSH_FORBIDDEN", []
+
+    if _scan_qa_findings_blocking(Path(root)):
+        return False, "BLOCKING_QA_FINDINGS", []
+
+    return True, "", []
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Sync/push gate evaluation for validate-and-push.")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_pol = sub.add_parser("policy", help="Pre-test merged scratchpad + sync policy gate.")
+    p_pol.add_argument("--root", required=True)
+    p_pol.add_argument("--branch", required=True)
+
+    p_post = sub.add_parser("post", help="Post-test allowlist + QA scan gate.")
+    p_post.add_argument("--root", required=True)
+    p_post.add_argument("--branch", required=True)
+
+    args = parser.parse_args()
+    root = os.path.abspath(args.root)
+
+    if args.cmd == "policy":
+        ok, reason, diags = eval_policy(root, args.branch)
+        if diags:
+            for d in diags:
+                print(d, file=sys.stderr)
+            print(json.dumps({"ok": False, "reason_code": "SCRATCHPAD_MERGE_ERROR"}))
+            return 2
+        print(json.dumps({"ok": ok, "reason_code": reason or None}))
+        return 0 if ok else 2
+
+    ok, reason, pdiags = eval_post_test(root, args.branch)
+    if pdiags:
+        for d in pdiags:
+            print(d, file=sys.stderr)
+        print(json.dumps({"ok": False, "reason_code": "SCRATCHPAD_MERGE_ERROR"}))
+        return 2
+    print(json.dumps({"ok": ok, "reason_code": reason or None}))
+    return 0 if ok else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/template/scripts/token_cost_compare.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""Compare two token-cost run JSON records for AC-2 (same run_class_hash, 50% cache read)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+_SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+if _SCRIPT_DIR not in sys.path:
+    sys.path.insert(0, _SCRIPT_DIR)
+
+import token_cost_lib  # noqa: E402
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description=__doc__)
+    p.add_argument("baseline", type=Path, help="JSON file with run_class_hash + totals")
+    p.add_argument("target", type=Path, help="JSON file with run_class_hash + totals")
+    p.add_argument(
+        "--reduction-fraction",
+        type=float,
+        default=0.5,
+        help="Required fractional reduction in cache_read_tokens (default 0.5)",
+    )
+    args = p.parse_args()
+    base = json.loads(args.baseline.read_text(encoding="utf-8"))
+    tgt = json.loads(args.target.read_text(encoding="utf-8"))
+    ok, msg = token_cost_lib.compare_cache_read_reduction(
+        base, tgt, reduction_fraction=args.reduction_fraction
+    )
+    print(msg)
+    return 0 if ok else 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())