@delorenj/pjangler 1.2.21 → 1.2.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delorenj/pjangler",
-  "version": "1.2.21",
+  "version": "1.2.25",
   "description": "Project subsystem bootstrapper CLI",
   "type": "module",
   "main": "dist/index.js",
@@ -20,14 +20,18 @@
   },
   "scripts": {
     "build": "esbuild src/index.ts src/mcp-server.ts --bundle --packages=external --platform=node --format=esm --outdir=dist",
+    "check:audit:prod": "npm audit --omit=dev",
+    "check:lock": "node scripts/check-package-lock-parity.mjs",
+    "check:submodules": "node scripts/check-submodule-contract.mjs",
+    "check:tracked-secrets": "node scripts/check-tracked-secrets.mjs",
     "start": "node dist/index.js",
     "mcp": "node dist/mcp-server.js",
     "typecheck": "tsc --noEmit",
-    "test": "node tests/parity-migrate-regressions.mjs && node tests/mcp-catalog-regressions.mjs && node tests/mcp-server-regressions.mjs && node tests/project-registry-regressions.mjs && node tests/pg-registry-regressions.mjs",
+    "test": "npm run check:lock && npm run check:submodules && npm run check:tracked-secrets && node tests/release-regressions.mjs && node tests/submodule-contract-regressions.mjs && node tests/secret-publication-gate-regressions.mjs && node tests/bmad-version-surface-regressions.mjs && node tests/bmad-transaction-regressions.mjs && node tests/parity-migrate-regressions.mjs && node tests/pjan-43-regressions.mjs && node tests/skillex-init-regressions.mjs && node tests/fleet-shared-bloodbank-regressions.mjs && node tests/mcp-catalog-regressions.mjs && node tests/mcp-server-regressions.mjs && node tests/project-registry-regressions.mjs && node tests/pg-registry-regressions.mjs",
     "migrate:up": "node-pg-migrate --migrations-dir migrations up",
     "migrate:down": "node-pg-migrate --migrations-dir migrations down",
     "migrate:create": "node-pg-migrate --migrations-dir migrations create",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run check:lock && npm run check:submodules -- --remote --recursive --archive --npm && npm run build && npm run check:tracked-secrets"
   },
   "keywords": [
     "cli",
@@ -52,5 +56,12 @@
     "esbuild": "^0.25.0",
     "node-pg-migrate": "^8.0.0",
     "typescript": "^5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/delorenj/pjangler.git"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
   }
 }

package/templates/commonproject/copier.yml

@@ -119,5 +119,8 @@ _tasks:
   - "printf '\\n# Secrets + per-dev agent-hook/skill overrides (see .agents/local.example.json)\\n.env\\n.env.*\\n!.env.op\\n.agents/local.json\\n.kimi-code/\\n.lastagent\\n**/.claude/settings.local.json\\n' >> .gitignore"
   - "ln -sf AGENTS.md CLAUDE.md"
   - "ln -sf AGENTS.md GEMINI.md"
+  # Materialize the pinned Skillex BMAD manifest + symlink topology without
+  # copying pack content or disturbing project-specific, non-BMAD skills.
+  - "python3 .mise/scripts/provision-bmad-skills.py"
   # Stamp the repo's absolute path into .project.json (the SOT) post-render.
   - "python3 -c \"import json,os,pathlib; p=pathlib.Path('.project.json'); d=json.loads(p.read_text()); d['repo_path']=os.getcwd(); p.write_text(json.dumps(d,indent=2)+chr(10))\""

package/templates/commonproject/template/.mise/scripts/provision-bmad-skills.py

@@ -0,0 +1,480 @@
+#!/usr/bin/env python3
+"""Provision project BMAD skills from the pinned Skillex pack."""
+
+from __future__ import annotations
+
+import json
+import hashlib
+import os
+import shutil
+import stat
+import tempfile
+import tomllib
+from pathlib import Path
+from typing import Callable
+from urllib.parse import unquote, urlparse
+
+
+BMAD_PACK_VERSION = "6.10.1-next.31"
+BMAD_PACK_CHECKSUMS_SHA256 = "a8bc005612ac60e3ec775fff5a11eafe38be6acdae96efa3d770b48322cb3224"
+BMAD_PACK_SKILL_COUNT = 76
+BMAD_PACK_PAYLOAD_FILES = 1072
+SKILLS_SCHEMA = "https://raw.githubusercontent.com/skillex/schemas/main/skills.schema.json"
+SKILLS_REGISTRY = "https://github.com/delorenj/skillex.git"
+
+
+def pack_root() -> Path:
+    override = os.environ.get("PJ_BMAD_PACK_ROOT", "").strip()
+    return (
+        Path(override).expanduser()
+        if override
+        else Path.home() / "code" / "skillex" / "packs" / "bmad" / BMAD_PACK_VERSION
+    ).absolute()
+
+
+def read_regular_file(path: Path) -> bytes:
+    descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
+    try:
+        if not stat.S_ISREG(os.fstat(descriptor).st_mode):
+            raise ValueError(f"BMAD pack entry is not a regular file: {path}")
+        with os.fdopen(os.dup(descriptor), "rb") as handle:
+            return handle.read()
+    finally:
+        os.close(descriptor)
+
+
+def safe_checksum_path(value: str) -> Path:
+    path = Path(value)
+    if not value or "\\" in value or path.is_absolute() or any(part in {"", ".", ".."} for part in path.parts):
+        raise ValueError(f"Unsafe BMAD checksum path: {value!r}")
+    return path
+
+
+def walk_regular_tree(root: Path) -> tuple[dict[str, bytes], set[str]]:
+    files: dict[str, bytes] = {}
+    directories: set[str] = set()
+
+    def visit(directory: Path) -> None:
+        for entry in sorted(os.scandir(directory), key=lambda item: item.name):
+            path = Path(entry.path)
+            mode = entry.stat(follow_symlinks=False).st_mode
+            if stat.S_ISLNK(mode):
+                raise ValueError(f"BMAD pack may not contain symlinks: {path}")
+            if stat.S_ISDIR(mode):
+                directories.add(path.relative_to(root).as_posix())
+                visit(path)
+            elif stat.S_ISREG(mode):
+                files[path.relative_to(root).as_posix()] = read_regular_file(path)
+            else:
+                raise ValueError(f"BMAD pack may contain only regular files/directories: {path}")
+
+    visit(root)
+    return files, directories
+
+
+def validate_trusted_pack(root: Path) -> list[Path]:
+    mode = root.lstat().st_mode
+    if stat.S_ISLNK(mode) or not stat.S_ISDIR(mode):
+        raise ValueError(f"BMAD pack root must be a real directory: {root}")
+
+    checksum_bytes = read_regular_file(root / "SHA256SUMS")
+    if hashlib.sha256(checksum_bytes).hexdigest() != BMAD_PACK_CHECKSUMS_SHA256:
+        raise ValueError(
+            f"BMAD pack checksum manifest is not the trusted {BMAD_PACK_VERSION} manifest"
+        )
+    expected: dict[str, str] = {}
+    for line in checksum_bytes.decode("utf-8").splitlines():
+        digest, separator, value = line.partition("  ")
+        if separator != "  " or len(digest) != 64 or any(char not in "0123456789abcdef" for char in digest):
+            raise ValueError(f"Invalid BMAD SHA256SUMS entry: {line}")
+        relative = safe_checksum_path(value).as_posix()
+        if relative in expected:
+            raise ValueError(f"Duplicate BMAD SHA256SUMS entry: {relative}")
+        expected[relative] = digest
+
+    actual, directories = walk_regular_tree(root)
+    actual.pop("SHA256SUMS", None)
+    missing = sorted(set(expected) - set(actual))
+    extra = sorted(set(actual) - set(expected))
+    if missing or extra:
+        raise ValueError(f"BMAD checksum coverage mismatch; missing={missing} extra={extra}")
+    for relative, digest in expected.items():
+        if hashlib.sha256(actual[relative]).hexdigest() != digest:
+            raise ValueError(f"BMAD pack digest mismatch: {relative}")
+    for directory in directories:
+        if not any(relative.startswith(f"{directory}/") for relative in actual):
+            raise ValueError(
+                f"BMAD pack contains an unauthenticated empty directory: {directory}"
+            )
+
+    metadata = tomllib.loads(actual["pack.toml"].decode("utf-8"))
+    pack = metadata.get("pack", {})
+    source = metadata.get("source", {})
+    freeform = metadata.get("freeform", {})
+    policy = metadata.get("policy", {})
+    if (
+        pack.get("name") != "bmad"
+        or pack.get("version") != BMAD_PACK_VERSION
+        or source.get("upstream") != "bmad-method"
+        or source.get("upstream_version") != BMAD_PACK_VERSION
+        or source.get("rendered_from") != ".agent/skills"
+        or policy.get("immutable") is not True
+        or policy.get("project_projection") != "symlink"
+    ):
+        raise ValueError(f"BMAD pack.toml does not declare the trusted {BMAD_PACK_VERSION} contract")
+    skill_names = freeform.get("skills")
+    payload_files = source.get("payload_files")
+    if (
+        not isinstance(skill_names, list)
+        or not all(isinstance(name, str) for name in skill_names)
+        or len(skill_names) != BMAD_PACK_SKILL_COUNT
+        or len(set(skill_names)) != len(skill_names)
+    ):
+        raise ValueError(f"BMAD pack.toml must declare exactly {BMAD_PACK_SKILL_COUNT} unique skills")
+    if payload_files != BMAD_PACK_PAYLOAD_FILES:
+        raise ValueError(f"BMAD pack.toml must declare exactly {BMAD_PACK_PAYLOAD_FILES} payload files")
+    for name in skill_names:
+        if not name.startswith("bmad-"):
+            raise ValueError(f"Unsafe BMAD skill identity: {name!r}")
+        validate_skill_name(name)
+
+    top_level_directories = sorted(
+        entry.name for entry in os.scandir(root) if stat.S_ISDIR(entry.stat(follow_symlinks=False).st_mode)
+    )
+    if top_level_directories != sorted(skill_names):
+        raise ValueError("BMAD pack directory inventory differs from authenticated pack.toml skills")
+    for name in skill_names:
+        skill_md = root / name / "SKILL.md"
+        if not stat.S_ISREG(skill_md.lstat().st_mode):
+            raise ValueError(f"BMAD skill is missing a regular SKILL.md: {name}")
+    skill_set = set(skill_names)
+    payload_count = sum(1 for relative in actual if relative.split("/", 1)[0] in skill_set)
+    if payload_count != payload_files:
+        raise ValueError(f"BMAD payload inventory mismatch: {payload_count} != {payload_files}")
+    return [root / name for name in skill_names]
+
+
+def load_manifest(path: Path) -> dict:
+    if not path.exists():
+        return {}
+    value = json.loads(path.read_text())
+    if not isinstance(value, dict):
+        raise ValueError(f"{path} must contain a JSON object")
+    return value
+
+
+def manifest_entry_name(value: object) -> str | None:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, dict):
+        name = value.get("name")
+        return name if isinstance(name, str) else None
+    return None
+
+
+def is_pack_managed_manifest_entry(
+    value: object, expected_names: set[str], root: Path
+) -> bool:
+    name = manifest_entry_name(value)
+    if name is None:
+        return False
+    if name in expected_names:
+        return True
+    if not isinstance(value, dict):
+        return False
+    source = value.get("source")
+    if not isinstance(source, str):
+        return False
+    try:
+        parsed = urlparse(source)
+        if parsed.scheme != "file" or parsed.netloc not in {"", "localhost"}:
+            return False
+        source_path = Path(os.path.abspath(unquote(parsed.path)))
+        source_path.relative_to(root)
+    except (OSError, ValueError):
+        return False
+    return source_path.name == name
+
+
+def validate_skill_name(name: str) -> str:
+    if not name or name in {".", ".."} or Path(name).is_absolute():
+        raise ValueError(f"Unsafe BMAD skill name: {name!r}")
+    if "/" in name or "\\" in name or Path(name).name != name:
+        raise ValueError(f"BMAD skill name must be one path component: {name!r}")
+    return name
+
+
+def preflight_project_directory(project_root: Path, target: Path) -> None:
+    try:
+        relative = target.absolute().relative_to(project_root)
+    except ValueError as error:
+        raise ValueError(f"Project destination escapes {project_root}: {target}") from error
+    if len(relative.parts) > 2:
+        raise ValueError(f"Unexpected project skill destination depth: {target}")
+    current = project_root
+    for part in relative.parts:
+        current = current / part
+        if not current.exists() and not current.is_symlink():
+            break
+        if current.is_symlink():
+            raise ValueError(f"Refusing symlinked project skill directory: {current}")
+        if not current.is_dir():
+            raise ValueError(f"Project skill parent is not a directory: {current}")
+
+
+def prepare_project_skill_dirs(project_root: Path) -> tuple[Path, Path]:
+    agents_dir = project_root / ".agents"
+    skills_dir = agents_dir / "skills"
+    # Validate the complete existing chain before creating or mutating anything.
+    preflight_project_directory(project_root, agents_dir)
+    preflight_project_directory(project_root, skills_dir)
+    agents_dir.mkdir(exist_ok=True)
+    skills_dir.mkdir(exist_ok=True)
+    for path in (agents_dir, skills_dir):
+        if path.is_symlink() or not path.is_dir():
+            raise ValueError(f"Unsafe project skill directory: {path}")
+        resolved = path.resolve(strict=True)
+        resolved.relative_to(project_root)
+    return agents_dir, skills_dir
+
+
+def lexical_link_target(link: Path) -> Path | None:
+    if not link.is_symlink():
+        return None
+    target = Path(os.readlink(link))
+    return (target if target.is_absolute() else link.parent / target).absolute()
+
+
+def remove_entry(path: Path) -> None:
+    try:
+        mode = path.lstat().st_mode
+    except FileNotFoundError:
+        return
+    if stat.S_ISDIR(mode) and not stat.S_ISLNK(mode):
+        shutil.rmtree(path)
+    else:
+        path.unlink()
+
+
+def atomic_write(path: Path, content: bytes, mode: int) -> None:
+    descriptor, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    temporary = Path(temporary_name)
+    try:
+        with os.fdopen(descriptor, "wb") as handle:
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+        temporary.chmod(mode)
+        os.replace(temporary, path)
+    finally:
+        if temporary.exists():
+            temporary.unlink()
+
+
+def provision(
+    *,
+    after_preflight: Callable[[], None] | None = None,
+    create_link: Callable[[Path, Path, int], None] | None = None,
+    after_apply: Callable[[Path, Path], None] | None = None,
+) -> int:
+    root = pack_root()
+    pack_skills = validate_trusted_pack(root)
+    if after_preflight is not None:
+        after_preflight()
+
+    project_root = Path.cwd().resolve(strict=True)
+    agents_path = project_root / ".agents"
+    skills_path = agents_path / "skills"
+    agents_existed = agents_path.exists() or agents_path.is_symlink()
+    skills_existed = skills_path.exists() or skills_path.is_symlink()
+    preflight_project_directory(project_root, agents_path)
+    preflight_project_directory(project_root, skills_path)
+    manifest_path = agents_path / "skills.json"
+    if manifest_path.is_symlink():
+        raise ValueError(f"Refusing symlinked skills manifest: {manifest_path}")
+    if manifest_path.exists() and not manifest_path.is_file():
+        raise ValueError(f"Skills manifest is not a regular file: {manifest_path}")
+    manifest_existed = manifest_path.exists()
+    manifest_bytes = read_regular_file(manifest_path) if manifest_existed else None
+    manifest_mode = stat.S_IMODE(manifest_path.lstat().st_mode) if manifest_existed else 0o644
+    manifest = json.loads(manifest_bytes) if manifest_bytes is not None else {}
+    if not isinstance(manifest, dict):
+        raise ValueError(f"{manifest_path} must contain a JSON object")
+    existing = manifest.get("skills", [])
+    if not isinstance(existing, list):
+        raise ValueError(f"{manifest_path} skills must be an array")
+    agents_dir, skills_dir = prepare_project_skill_dirs(project_root)
+
+    manifest["$schema"] = SKILLS_SCHEMA
+    manifest["inherit_global"] = True
+    manifest["registry"] = SKILLS_REGISTRY
+    expected = {path.name: path for path in pack_skills}
+    expected_names = set(expected)
+    managed_manifest_names = {
+        name
+        for entry in existing
+        if is_pack_managed_manifest_entry(entry, expected_names, root)
+        if (name := manifest_entry_name(entry)) is not None
+    }
+    manifest["skills"] = [
+        *[
+            entry
+            for entry in existing
+            if not is_pack_managed_manifest_entry(entry, expected_names, root)
+        ],
+        *[{"name": path.name, "source": path.as_uri()} for path in pack_skills],
+    ]
+    next_manifest = (json.dumps(manifest, indent=2) + "\n").encode("utf-8")
+    affected: list[str] = []
+    stale_managed_names: set[str] = set()
+    original_correct_links: dict[str, str] = {}
+    for entry in skills_dir.iterdir():
+        if entry.parent.resolve(strict=True) != skills_dir.resolve(strict=True):
+            raise ValueError(f"BMAD skill entry escapes skills directory: {entry}")
+        validate_skill_name(entry.name)
+        link_target = lexical_link_target(entry)
+        try:
+            link_targets_pack = link_target is not None and link_target.is_relative_to(root)
+        except OSError:
+            link_targets_pack = False
+        if (
+            entry.name not in expected
+            and entry.name not in managed_manifest_names
+            and not link_targets_pack
+        ):
+            continue
+        target = expected.get(entry.name)
+        if target is not None and link_target == target:
+            original_correct_links[entry.name] = os.readlink(entry)
+        else:
+            affected.append(entry.name)
+            if target is None:
+                stale_managed_names.add(entry.name)
+    for name, target in expected.items():
+        link = skills_dir / validate_skill_name(name)
+        if link.parent.resolve(strict=True) != skills_dir.resolve(strict=True):
+            raise ValueError(f"BMAD skill destination escapes skills directory: {link}")
+        if lexical_link_target(link) != target and name not in affected:
+            affected.append(name)
+
+    manifest_changed = manifest_bytes != next_manifest
+    if not affected and not manifest_changed:
+        validate_trusted_pack(root)
+        return 0
+
+    transaction = Path(tempfile.mkdtemp(prefix=".bmad-transaction-", dir=agents_dir))
+    backup = transaction / "entries"
+    backup.mkdir()
+    moved: list[str] = []
+    created: list[str] = []
+
+    def rollback() -> None:
+        errors: list[str] = []
+        try:
+            for name in affected:
+                remove_entry(skills_dir / validate_skill_name(name))
+            for name in original_correct_links:
+                remove_entry(skills_dir / validate_skill_name(name))
+        except OSError as error:
+            errors.append(f"remove applied projection: {error}")
+        for name in reversed(moved):
+            try:
+                os.replace(backup / name, skills_dir / name)
+            except OSError as error:
+                errors.append(f"restore {name}: {error}")
+        for name, raw_target in original_correct_links.items():
+            try:
+                (skills_dir / name).symlink_to(raw_target, target_is_directory=True)
+            except OSError as error:
+                errors.append(f"restore {name}: {error}")
+        try:
+            if manifest_bytes is None:
+                remove_entry(manifest_path)
+            else:
+                atomic_write(manifest_path, manifest_bytes, manifest_mode)
+        except OSError as error:
+            errors.append(f"restore manifest: {error}")
+        shutil.rmtree(transaction, ignore_errors=True)
+        try:
+            if not skills_existed and skills_dir.exists() and not any(skills_dir.iterdir()):
+                skills_dir.rmdir()
+            if not agents_existed and agents_dir.exists() and not any(agents_dir.iterdir()):
+                agents_dir.rmdir()
+        except OSError as error:
+            errors.append(f"remove created directories: {error}")
+        if errors:
+            raise RuntimeError("BMAD rollback was incomplete: " + "; ".join(errors))
+
+    link_creator = create_link or (
+        lambda target, link, _index: link.symlink_to(target, target_is_directory=True)
+    )
+    try:
+        for name in affected:
+            entry = skills_dir / name
+            if entry.exists() or entry.is_symlink():
+                os.replace(entry, backup / name)
+                moved.append(name)
+        for index, (name, target) in enumerate(expected.items(), start=1):
+            link = skills_dir / name
+            if lexical_link_target(link) == target:
+                continue
+            link_creator(target, link, index)
+            created.append(name)
+        if manifest_changed:
+            atomic_write(manifest_path, next_manifest, manifest_mode)
+        postflight = validate_trusted_pack(root)
+        if [path.name for path in postflight] != list(expected):
+            raise ValueError("BMAD pack inventory changed after preflight")
+        if after_apply is not None:
+            after_apply(manifest_path, skills_dir)
+        for name in stale_managed_names:
+            entry = skills_dir / name
+            if entry.exists() or entry.is_symlink():
+                raise ValueError(f"Applied BMAD projection retained stale managed entry: {name}")
+        for name, target in expected.items():
+            if lexical_link_target(skills_dir / name) != target:
+                raise ValueError(f"Applied BMAD projection link differs from plan: {name}")
+        final_mode = manifest_path.lstat().st_mode
+        if (
+            not stat.S_ISREG(final_mode)
+            or read_regular_file(manifest_path) != next_manifest
+            or stat.S_IMODE(final_mode) != manifest_mode
+        ):
+            raise ValueError("Applied BMAD skills manifest differs from planned bytes or mode")
+        final_manifest = json.loads(read_regular_file(manifest_path))
+        if (
+            not isinstance(final_manifest, dict)
+            or final_manifest.get("$schema") != SKILLS_SCHEMA
+            or final_manifest.get("inherit_global") is not True
+            or final_manifest.get("registry") != SKILLS_REGISTRY
+            or not isinstance(final_manifest.get("skills"), list)
+        ):
+            raise ValueError("Applied BMAD skills manifest schema differs from plan")
+    except Exception as error:
+        try:
+            rollback()
+        except Exception as rollback_error:
+            raise RuntimeError(f"BMAD provisioning failed ({error}); {rollback_error}") from error
+        raise
+
+    shutil.rmtree(transaction)
+    return len(affected)
+
+
+def main() -> None:
+    try:
+        changed = provision()
+    except (FileNotFoundError, OSError, ValueError, RuntimeError) as error:
+        raise SystemExit(
+            f"BMAD Skillex pack {BMAD_PACK_VERSION} provisioning failed: {error}; "
+            "set PJ_BMAD_PACK_ROOT to the installed canonical pack"
+        ) from error
+
+    print(
+        f"bmad-skills: {BMAD_PACK_SKILL_COUNT} skills from pack "
+        f"{BMAD_PACK_VERSION}; {changed} symlink(s) updated"
+    )
+
+
+if __name__ == "__main__":
+    main()