vstack 0.0.0__py3-none-any.whl

vstack/cli/manifest.py

@@ -0,0 +1,166 @@
+"""vstack manifest — reads and writes ``vstack.json``.
+
+The manifest tracks every artifact installed by ``vstack install`` so that
+``vstack uninstall`` can remove exactly those files without touching anything
+the user placed there manually.
+
+Format::
+
+    {
+      "vstack_version": "…",
+      "installed_at":   "…",
+      "artifacts": {
+        "skills": [{"name": "vision", "version": "1.0.1", "file": "skills/vision/SKILL.md"}],
+                "agents": [{"name": "engineer", "file": "agents/engineer.agent.md"}],
+                "instructions": [{"name": "python", "file": "instructions/python.instructions.md"}],
+                "prompts": [{"name": "code-review", "file": "prompts/code-review.prompt.md"}]
+      }
+    }
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from vstack.constants import MANIFEST_FILENAME
+
+
+@dataclass
+class ArtifactEntry:
+    """Represent a single installed artifact entry in ``vstack.json``."""
+
+    name: str
+    file: str
+    version: str | None = None
+
+
+@dataclass
+class Manifest:
+    """Represent the parsed install manifest stored in ``vstack.json``."""
+
+    vstack_version: str
+    installed_at: str
+    artifacts: dict[str, list[ArtifactEntry]] = field(default_factory=dict)
+
+    # ── Accessors ─────────────────────────────────────────────────────────────
+
+    def entries_for(self, type_name: str) -> list[ArtifactEntry]:
+        """Return manifest entries for a single artifact type key.
+
+        Args:
+            type_name: Manifest artifact key such as ``"skills"``.
+        """
+        return self.artifacts.get(type_name, [])
+
+    def names_for(self, type_name: str) -> list[str]:
+        """Return artifact names for a single manifest type key.
+
+        Args:
+            type_name: Manifest artifact key such as ``"skills"``.
+        """
+        return [e.name for e in self.entries_for(type_name)]
+
+    def files_for(self, type_name: str) -> list[str]:
+        """Return relative output file paths for a manifest type key.
+
+        Args:
+            type_name: Manifest artifact key such as ``"skills"``.
+        """
+        return [e.file for e in self.entries_for(type_name)]
+
+    # ── Serialisation ─────────────────────────────────────────────────────────
+
+    def to_dict(self) -> dict:
+        """Serialize the manifest into JSON-compatible primitives.
+
+        Returns:
+            A nested dictionary structure suitable for ``json.dumps``.
+        """
+        return {
+            "vstack_version": self.vstack_version,
+            "installed_at": self.installed_at,
+            "artifacts": {
+                type_name: [
+                    {
+                        "name": e.name,
+                        "file": e.file,
+                        **({} if e.version is None else {"version": e.version}),
+                    }
+                    for e in entries
+                ]
+                for type_name, entries in self.artifacts.items()
+            },
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Manifest:
+        """Create a :class:`Manifest` from parsed JSON data.
+
+        Args:
+            data: Parsed JSON object read from ``vstack.json``.
+
+        Returns:
+            A normalized in-memory manifest representation.
+        """
+        artifacts: dict[str, list[ArtifactEntry]] = {}
+        for type_name, entries in data.get("artifacts", {}).items():
+            artifacts[type_name] = [
+                ArtifactEntry(
+                    name=e["name"],
+                    file=e["file"],
+                    version=e.get("version"),
+                )
+                for e in entries
+                if isinstance(e, dict) and "name" in e
+            ]
+        return cls(
+            vstack_version=data.get("vstack_version", ""),
+            installed_at=data.get("installed_at", ""),
+            artifacts=artifacts,
+        )
+
+
+class ManifestFile:
+    """Read and write the ``vstack.json`` manifest inside an install root."""
+
+    def __init__(self, parent_dir: Path) -> None:
+        """Create a manifest accessor rooted at the provided install directory.
+
+        Args:
+            parent_dir: Install root that contains or will contain
+                ``vstack.json``.
+        """
+        self.path = parent_dir / MANIFEST_FILENAME
+
+    def exists(self) -> bool:
+        """Return ``True`` when the manifest file exists on disk."""
+        return self.path.exists()
+
+    def read(self) -> Manifest | None:
+        """Parse the manifest file from disk.
+
+        Returns:
+            The parsed manifest, or ``None`` when the file is missing or
+            cannot be decoded safely.
+        """
+        if not self.path.exists():
+            return None
+        try:
+            data = json.loads(self.path.read_text(encoding="utf-8"))
+            return Manifest.from_dict(data)
+        except (json.JSONDecodeError, KeyError):
+            return None
+
+    def write(self, manifest: Manifest) -> None:
+        """Write a manifest to disk in stable, human-readable JSON format.
+
+        Args:
+            manifest: Manifest data to persist.
+        """
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(
+            json.dumps(manifest.to_dict(), indent=2, ensure_ascii=False) + "\n",
+            encoding="utf-8",
+        )

vstack/cli/parser.py

@@ -0,0 +1,156 @@
+"""CLI argument parser and install target resolution."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from vstack.constants import VERSION
+
+
+class CommandLineParser:
+    """Create the vstack command-line parser and resolve install targets."""
+
+    def vscode_user_dir(self) -> Path | None:
+        """Return the first detected VS Code user data directory.
+
+        Returns:
+            The detected VS Code or VS Code Server user directory, or ``None``
+            when no known location exists on the current machine.
+        """
+        candidates = [
+            Path.home() / ".vscode-server" / "data" / "User",
+            Path.home() / ".config" / "Code" / "User",
+            Path.home() / "Library" / "Application Support" / "Code" / "User",
+            Path.home() / "AppData" / "Roaming" / "Code" / "User",
+        ]
+        return next((p for p in candidates if p.exists()), None)
+
+    def resolve_targets(self, args: argparse.Namespace) -> Path:
+        """Resolve the install root directory from parsed CLI arguments.
+
+        Args:
+            args: Parsed ``argparse`` namespace for an install-like command.
+
+        Returns:
+            The effective install root directory.
+
+        Raises:
+            SystemExit: If ``--global`` cannot be resolved or the explicit
+                ``--target`` directory does not exist.
+        """
+        if getattr(args, "use_global", False):
+            user_dir = self.vscode_user_dir()
+            if user_dir is None:
+                print(
+                    "ERROR: Could not detect VS Code user data directory.\n"
+                    "Specify manually with:  vstack install --target ~/.config/Code/User",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+            return user_dir
+
+        if getattr(args, "target", None):
+            target = Path(args.target).expanduser().resolve()
+            if not target.exists():
+                print(f"ERROR: target directory does not exist: {target}", file=sys.stderr)
+                sys.exit(1)
+            return target / ".github"
+
+        # default: current working directory
+        return Path.cwd() / ".github"
+
+    def build(self) -> argparse.ArgumentParser:
+        """Create and configure the top-level ``argparse`` parser for vstack.
+
+        Returns:
+            A fully configured parser with all supported subcommands and flags.
+        """
+        parser = argparse.ArgumentParser(
+            prog="vstack",
+            description="Manage vstack skill generation and installation.",
+        )
+        parser.add_argument("--version", action="version", version=f"vstack {VERSION}")
+        sub = parser.add_subparsers(dest="command", metavar="<command>")
+        sub.required = True
+
+        p_validate = sub.add_parser(
+            "validate", help="Render templates in memory, report unresolved tokens"
+        )
+        p_validate.add_argument(
+            "--only",
+            nargs="+",
+            metavar="<type>",
+            help="Validate only these artifact types, e.g. --only skill agent",
+        )
+
+        p = sub.add_parser("verify", help="Validate source templates and/or installed output")
+        group = p.add_mutually_exclusive_group()
+        group.add_argument("--target", metavar="<dir>", help="Install into <dir>/.github/")
+        group.add_argument(
+            "--global",
+            dest="use_global",
+            action="store_true",
+            help="VS Code user profile (agents/prompts/instructions/skills)",
+        )
+        p.add_argument(
+            "--only",
+            nargs="+",
+            metavar="<type>",
+            help="Verify only these artifact types, e.g. --only agent prompt",
+        )
+        p.add_argument(
+            "--no-source",
+            dest="source",
+            action="store_false",
+            default=True,
+            help="Skip source template checks",
+        )
+        p.add_argument(
+            "--no-output",
+            dest="output",
+            action="store_false",
+            default=True,
+            help="Skip installed output checks",
+        )
+
+        for cmd, help_text in [
+            ("install", "Generate and install artifacts (--only to filter types)"),
+            ("uninstall", "Remove vstack-managed files"),
+        ]:
+            p = sub.add_parser(cmd, help=help_text)
+            group = p.add_mutually_exclusive_group()
+            group.add_argument("--target", metavar="<dir>", help="Install into <dir>/.github/")
+            group.add_argument(
+                "--global",
+                dest="use_global",
+                action="store_true",
+                help="VS Code user profile (agents/prompts/instructions/skills)",
+            )
+            if cmd == "install":
+                p.add_argument(
+                    "--only",
+                    nargs="+",
+                    metavar="<type>",
+                    help="Install only these artifact types, e.g. --only skill agent",
+                )
+                mode = p.add_mutually_exclusive_group()
+                mode.add_argument(
+                    "--force",
+                    action="store_true",
+                    help="Overwrite existing artifacts unconditionally",
+                )
+                mode.add_argument(
+                    "--update",
+                    action="store_true",
+                    help="Install only when a newer version is available",
+                )
+                p.add_argument(
+                    "--dry-run",
+                    dest="dry_run",
+                    action="store_true",
+                    help="Show what would be installed without writing files",
+                )
+
+        return parser

vstack/constants.py

@@ -0,0 +1,84 @@
+"""Project-wide constants and version helpers."""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+from importlib.resources import files
+from pathlib import Path
+
+# Package root — works both in editable installs and after pip install
+_PACKAGE_ROOT = files("vstack")
+
+TEMPLATES_ROOT = Path(str(_PACKAGE_ROOT / "_templates"))
+
+_SEMVER_TAG_RE = re.compile(r"^\d+\.\d+\.\d+$")
+
+
+def _version_tuple(tag: str) -> tuple[int, int, int]:
+    major, minor, patch = tag.split(".")
+    return int(major), int(minor), int(patch)
+
+
+def _vstack_repo_root() -> Path | None:
+    """Return the root of the vstack source checkout, or None if not in one.
+
+    Walks up from the package directory looking for a .git directory.
+    Returns None when invoked outside the vstack source tree, preventing
+    accidental version reads from the user's working directory.
+    """
+    candidate = Path(str(_PACKAGE_ROOT)).resolve()
+    for parent in [candidate, *candidate.parents]:
+        if (parent / ".git").exists():
+            # Confirm this is the vstack repo, not an arbitrary repo that
+            # happens to contain the installed package somewhere inside it.
+            if (parent / "src" / "vstack").exists():
+                return parent
+            break
+    return None
+
+
+def _head_semver_tag() -> str | None:
+    """Return the highest plain semver tag pointing at HEAD, if available.
+
+    Only runs git inside the vstack source checkout to prevent picking up
+    tags from whatever repository the user is working in.
+    """
+    repo_root = _vstack_repo_root()
+    if repo_root is None:
+        return None
+    try:
+        out = subprocess.check_output(
+            ["git", "-C", str(repo_root), "tag", "--points-at", "HEAD"],
+            stderr=subprocess.DEVNULL,
+            text=True,
+        )
+    except (FileNotFoundError, subprocess.CalledProcessError):
+        return None
+
+    tags = [line.strip() for line in out.splitlines() if _SEMVER_TAG_RE.fullmatch(line.strip())]
+    if not tags:
+        return None
+    return max(tags, key=_version_tuple)
+
+
+def _resolve_version() -> str:
+    """Resolve the package version from git tags, package metadata, or fallback."""
+    version = _head_semver_tag() or ""
+    if version:
+        return version
+
+    try:
+        # Reads from installed package metadata, populated by build-time versioning.
+        return _pkg_version("vstack")
+    except PackageNotFoundError:
+        # Fallback: uninstalled source tree or shallow clone without any git tag.
+        return "0.0.0"
+
+
+# Prefer an exact semver tag on HEAD for source checkouts.
+VERSION = _resolve_version()
+
+MANIFEST_FILENAME = "vstack.json"

vstack/frontmatter/__init__.py

@@ -0,0 +1,8 @@
+"""vstack.frontmatter — YAML frontmatter parsing, building, and schema validation."""
+
+from vstack.frontmatter.parser import FrontmatterContent as FrontmatterContent
+from vstack.frontmatter.parser import FrontmatterParser as FrontmatterParser
+from vstack.frontmatter.schema import FieldSpec as FieldSpec
+from vstack.frontmatter.schema import FieldType as FieldType
+from vstack.frontmatter.schema import FrontmatterSchema as FrontmatterSchema
+from vstack.frontmatter.serializer import FrontmatterSerializer as FrontmatterSerializer

vstack/frontmatter/parser.py

@@ -0,0 +1,272 @@
+"""YAML frontmatter parser — no external dependencies.
+
+Supports:
+- String scalars (quoted and unquoted)
+- Inline lists  ``[a, b, c]``
+- Block lists   ``\n  - item``
+- Block sequences of mappings (object-lists)  ``\n  - key: val\n    key2: val2``
+- Block scalars ``|``
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+_FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---\n(.*)", re.DOTALL)
+
+
+@dataclass
+class FrontmatterContent:
+    """Result of parsing a document that may contain YAML frontmatter.
+
+    Attributes:
+        metadata: Parsed key/value pairs from the ``---`` block.
+                  Empty dict when no frontmatter was found.
+        content:  The body text after the closing ``---``.
+                  Equals the original input when no frontmatter was found.
+    """
+
+    metadata: dict = field(default_factory=dict)
+    content: str = ""
+
+    # ── Convenience accessors ─────────────────────────────────────────────────
+
+    def get(self, key: str, default: object = None) -> object:
+        """Return *key* from metadata, falling back to *default*."""
+        return self.metadata.get(key, default)
+
+    def __contains__(self, key: object) -> bool:
+        """Return ``True`` when *key* exists in parsed metadata."""
+        return key in self.metadata
+
+    def __getitem__(self, key: str) -> object:
+        """Provide dict-style indexing for metadata lookups."""
+        return self.metadata[key]
+
+    def __bool__(self) -> bool:
+        """Return ``True`` when parsed metadata is non-empty."""
+        return bool(self.metadata)
+
+
+class FrontmatterParser:
+    """Parse the repository's supported subset of YAML frontmatter."""
+
+    @staticmethod
+    def _is_current_object_list_item(meta: dict, current_key: str) -> bool:
+        """Return ``True`` when ``current_key`` points to the active object-list item."""
+        return (
+            bool(current_key)
+            and isinstance(meta.get(current_key), list)
+            and bool(meta[current_key])
+            and isinstance(meta[current_key][-1], dict)
+        )
+
+    @staticmethod
+    def _flush_object_block_scalar(
+        *,
+        meta: dict,
+        current_key: str,
+        object_scalar_field: str,
+        object_block_lines: list[str],
+    ) -> None:
+        """Flush buffered block-scalar content into the active object-list item."""
+        text = " ".join(b for b in object_block_lines if b).strip()
+        if FrontmatterParser._is_current_object_list_item(meta, current_key):
+            meta[current_key][-1][object_scalar_field] = text
+
+    @staticmethod
+    def _flush_raw_block(*, meta: dict, current_key: str, raw_lines: list[str]) -> None:
+        """Flush buffered raw block content into the current top-level key."""
+        meta[current_key] = "\n".join(raw_lines).rstrip()
+
+    @staticmethod
+    def _flush_block_scalar(*, meta: dict, current_key: str, block_lines: list[str]) -> None:
+        """Flush a buffered top-level block scalar into the current key."""
+        meta[current_key] = " ".join(b for b in block_lines if b).strip()
+
+    @staticmethod
+    def parse(content: str) -> FrontmatterContent:
+        """Split YAML frontmatter from body content.
+
+        Returns a :class:`FrontmatterContent` instance.  When no frontmatter
+        block is present, ``metadata`` is empty and ``content`` equals the
+        original input.
+        """
+        match = _FRONTMATTER_RE.match(content)
+        if not match:
+            return FrontmatterContent(metadata={}, content=content)
+        meta = FrontmatterParser._parse_yaml_block(match.group(1))
+        return FrontmatterContent(metadata=meta, content=match.group(2))
+
+    @staticmethod
+    def parse_yaml(raw: str) -> dict:
+        """Parse a raw YAML string without frontmatter delimiters.
+
+        Args:
+            raw: YAML content without surrounding ``---`` delimiters.
+
+        Returns:
+            A parsed metadata dictionary.
+        """
+        return FrontmatterParser._parse_yaml_block(raw)
+
+    # ── Internal ──────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _parse_scalar(val: str) -> str:
+        """Strip surrounding quotes from a YAML scalar string."""
+        return val.strip().strip("\"'")
+
+    @staticmethod
+    def _parse_yaml_block(raw: str) -> dict:
+        """Parse a minimal YAML subset (no external dependencies).
+
+        Supports: string values, inline lists ``[a, b]``,
+        block lists ``\n  - item``, block scalars ``|``,
+        block sequences of mappings (object-lists):
+        ``\n  - key: val\n    key2: val2``, and
+        raw mapping blocks where the value is indented non-list YAML content:
+        ``\n  server:\n    type: local`` (used for ``mcp-servers``, ``hooks``, etc.).
+        """
+        meta: dict = {}
+        current_key = ""
+        in_block_scalar = False
+        block_lines: list[str] = []
+        in_raw_block = False
+        raw_lines: list[str] = []
+        in_object_block_scalar = False
+        object_scalar_field = ""
+        object_block_lines: list[str] = []
+
+        for line in raw.split("\n"):
+            if line.strip().startswith("#"):
+                continue
+
+            if in_object_block_scalar:
+                if line.startswith("      ") or line == "":
+                    object_block_lines.append(line.strip())
+                    continue
+                else:
+                    FrontmatterParser._flush_object_block_scalar(
+                        meta=meta,
+                        current_key=current_key,
+                        object_scalar_field=object_scalar_field,
+                        object_block_lines=object_block_lines,
+                    )
+                    in_object_block_scalar = False
+                    object_scalar_field = ""
+                    object_block_lines = []
+
+            # ── Raw block accumulation ────────────────────────────────────────
+            if in_raw_block:
+                if line == "" or line.startswith(" "):
+                    raw_lines.append(line)
+                    continue
+                else:
+                    # Non-indented line closes the raw block; fall through to process it
+                    FrontmatterParser._flush_raw_block(
+                        meta=meta,
+                        current_key=current_key,
+                        raw_lines=raw_lines,
+                    )
+                    in_raw_block = False
+                    raw_lines = []
+
+            if in_block_scalar:
+                if line.startswith("  ") or line == "":
+                    block_lines.append(line.strip())
+                    continue
+                else:
+                    FrontmatterParser._flush_block_scalar(
+                        meta=meta,
+                        current_key=current_key,
+                        block_lines=block_lines,
+                    )
+                    in_block_scalar = False
+                    block_lines = []
+
+            # 4-space key: continuation of an object-list item
+            obj_kv = re.match(r"^    ([a-zA-Z_-]+):\s*(.*)$", line)
+            if obj_kv and FrontmatterParser._is_current_object_list_item(meta, current_key):
+                obj_key = obj_kv.group(1)
+                obj_val = obj_kv.group(2).strip()
+                if obj_val in ("|", "|-", "|+", ">", ">-", ">+"):
+                    in_object_block_scalar = True
+                    object_scalar_field = obj_key
+                    object_block_lines = []
+                    meta[current_key][-1][obj_key] = ""
+                else:
+                    meta[current_key][-1][obj_key] = FrontmatterParser._parse_scalar(obj_val)
+                continue
+
+            # Raw block trigger: 2-space non-list indented line when the current key
+            # has an empty provisional value (set by a bare ``key:`` with no value).
+            if (
+                line.startswith("  ")
+                and not line.startswith("  - ")
+                and current_key
+                and meta.get(current_key) == []
+            ):
+                in_raw_block = True
+                raw_lines = [line]
+                meta[current_key] = ""  # clear empty-list placeholder
+                continue
+
+            # 2-space list item
+            list_match = re.match(r"^  - (.+)$", line)
+            if list_match and current_key:
+                item_str = list_match.group(1).strip()
+                item_kv = re.match(r"^([a-zA-Z_-]+):\s*(.*)$", item_str)
+                if item_kv:
+                    # Object-list item — first key bootstraps the dict
+                    if not isinstance(meta.get(current_key), list):
+                        meta[current_key] = []
+                    meta[current_key].append(
+                        {item_kv.group(1): FrontmatterParser._parse_scalar(item_kv.group(2))}
+                    )
+                else:
+                    if not isinstance(meta.get(current_key), list):
+                        meta[current_key] = []
+                    meta[current_key].append(item_str.strip("\"'"))
+                continue
+
+            kv = re.match(r"^([a-zA-Z_-]+):\s*(.*)$", line)
+            if kv:
+                current_key = kv.group(1)
+                val = kv.group(2).strip()
+                if val.startswith("[") and val.endswith("]"):
+                    meta[current_key] = [
+                        v.strip().strip("\"'") for v in val[1:-1].split(",") if v.strip()
+                    ]
+                elif val in ("|", "|-", "|+", ">", ">-", ">+"):
+                    in_block_scalar = True
+                    block_lines = []
+                    meta[current_key] = ""
+                elif val == "":
+                    meta[current_key] = []  # provisional: may become a raw block
+                else:
+                    meta[current_key] = val.strip("\"'")
+
+        if in_object_block_scalar:
+            if object_scalar_field:
+                FrontmatterParser._flush_object_block_scalar(
+                    meta=meta,
+                    current_key=current_key,
+                    object_scalar_field=object_scalar_field,
+                    object_block_lines=object_block_lines,
+                )
+        if in_raw_block and raw_lines:
+            FrontmatterParser._flush_raw_block(
+                meta=meta,
+                current_key=current_key,
+                raw_lines=raw_lines,
+            )
+        if in_block_scalar and block_lines:
+            FrontmatterParser._flush_block_scalar(
+                meta=meta,
+                current_key=current_key,
+                block_lines=block_lines,
+            )
+
+        return meta