vstack 1.3.5__tar.gz → 2.0.0__tar.gz

{vstack-1.3.5 → vstack-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vstack
-Version: 1.3.5
+Version: 2.0.0
 Summary: VS Code-native AI engineering workflow system for microservices, libraries, and backend systems.
 License-Expression: MIT
 License-File: LICENSE
@@ -25,18 +25,18 @@ Project-URL: Repository, https://github.com/eschaar/vstack
 Project-URL: Security, https://github.com/eschaar/vstack/blob/main/SECURITY.md
 Description-Content-Type: text/markdown
 
-# vstack
+<p align="center">
+	<img src="https://raw.githubusercontent.com/eschaar/vstack/main/assets/branding/vstack.png" alt="vstack" width="260">
+</p>
 
-[![PyPI version](https://img.shields.io/pypi/v/vstack?color=0B8A6F)](https://pypi.org/project/vstack/)
+[![PyPI version](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpypi.org%2Fpypi%2Fvstack%2Fjson&query=%24.info.version&label=PyPI&color=0B8A6F&cacheSeconds=300)](https://pypi.org/project/vstack/)
 [![Python version](https://img.shields.io/badge/python-3.11--3.14-0B8A6F)](https://github.com/eschaar/vstack/blob/main/pyproject.toml)
-[![Verify status](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/verify.yml?branch=main&label=verify&color=1D6FA5)](https://github.com/eschaar/vstack/actions/workflows/verify.yml)
-[![Security checks](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/security.yml?branch=main&label=security&color=B15E00)](https://github.com/eschaar/vstack/actions/workflows/security.yml)
+[![Verify status](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/verify.yml?label=verify&color=1D6FA5)](https://github.com/eschaar/vstack/actions/workflows/verify.yml)
+[![Security checks](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/security.yml?label=security&color=B15E00)](https://github.com/eschaar/vstack/actions/workflows/security.yml)
 [![Runtime: stdlib only](https://img.shields.io/badge/runtime-stdlib%20only-5B6C8F)](https://github.com/eschaar/vstack/blob/main/pyproject.toml)
 [![License: MIT](https://img.shields.io/github/license/eschaar/vstack?color=5F7A1F)](https://github.com/eschaar/vstack/blob/main/LICENSE)
 [![GitHub Discussions](https://img.shields.io/badge/discussions-ask%20%26%20share-blueviolet?logo=github)](https://github.com/eschaar/vstack/discussions)
 
-![vstack logo](https://raw.githubusercontent.com/eschaar/vstack/main/assets/branding/vstack.png)
-
 The VS Code-native AI workflow system for backend engineering.
 
 vstack installs structured agents, skills, instructions, and prompts into `.github/` so GitHub Copilot Agent Mode can run repeatable backend workflows with clear role boundaries.
@@ -89,7 +89,9 @@ Expected result:
 vstack --version
 vstack validate
 vstack install --target /path/to/your/project
-vstack verify --target /path/to/your/project
+vstack manifest verify --target /path/to/your/project
+vstack manifest status --target /path/to/your/project
+vstack manifest upgrade --target /path/to/your/project
 ```
 
 ## Common usage patterns
@@ -106,6 +108,8 @@ Profile-wide install (optional defaults for all projects):
 vstack install --global
 ```
 
+By default, `vstack install` preserves existing unmanaged files and local edits to tracked files by comparing the current file contents with the SHA-256 checksum recorded in `vstack.json`. Use `--adopt-name <artifact-name>` to start tracking one existing unmanaged file without overwriting it. `vstack uninstall` also preserves locally modified tracked files unless you explicitly pass `--force` or `--force-name <artifact-name>`. Use `vstack manifest status --target ...` (or `vstack status --target ...`) to see what still matches the manifest. If a legacy manifest schema is detected, run `vstack manifest upgrade --target ...` first.
+
 ## Fast troubleshooting
 
 - Command not found after install: ensure your `pipx` binary path is in `PATH`

{vstack-1.3.5 → vstack-2.0.0}/README-pypi.md

@@ -1,15 +1,15 @@
-# vstack
+<p align="center">
+	<img src="https://raw.githubusercontent.com/eschaar/vstack/main/assets/branding/vstack.png" alt="vstack" width="260">
+</p>
 
-[![PyPI version](https://img.shields.io/pypi/v/vstack?color=0B8A6F)](https://pypi.org/project/vstack/)
+[![PyPI version](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpypi.org%2Fpypi%2Fvstack%2Fjson&query=%24.info.version&label=PyPI&color=0B8A6F&cacheSeconds=300)](https://pypi.org/project/vstack/)
 [![Python version](https://img.shields.io/badge/python-3.11--3.14-0B8A6F)](https://github.com/eschaar/vstack/blob/main/pyproject.toml)
-[![Verify status](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/verify.yml?branch=main&label=verify&color=1D6FA5)](https://github.com/eschaar/vstack/actions/workflows/verify.yml)
-[![Security checks](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/security.yml?branch=main&label=security&color=B15E00)](https://github.com/eschaar/vstack/actions/workflows/security.yml)
+[![Verify status](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/verify.yml?label=verify&color=1D6FA5)](https://github.com/eschaar/vstack/actions/workflows/verify.yml)
+[![Security checks](https://img.shields.io/github/actions/workflow/status/eschaar/vstack/security.yml?label=security&color=B15E00)](https://github.com/eschaar/vstack/actions/workflows/security.yml)
 [![Runtime: stdlib only](https://img.shields.io/badge/runtime-stdlib%20only-5B6C8F)](https://github.com/eschaar/vstack/blob/main/pyproject.toml)
 [![License: MIT](https://img.shields.io/github/license/eschaar/vstack?color=5F7A1F)](https://github.com/eschaar/vstack/blob/main/LICENSE)
 [![GitHub Discussions](https://img.shields.io/badge/discussions-ask%20%26%20share-blueviolet?logo=github)](https://github.com/eschaar/vstack/discussions)
 
-![vstack logo](https://raw.githubusercontent.com/eschaar/vstack/main/assets/branding/vstack.png)
-
 The VS Code-native AI workflow system for backend engineering.
 
 vstack installs structured agents, skills, instructions, and prompts into `.github/` so GitHub Copilot Agent Mode can run repeatable backend workflows with clear role boundaries.
@@ -62,7 +62,9 @@ Expected result:
 vstack --version
 vstack validate
 vstack install --target /path/to/your/project
-vstack verify --target /path/to/your/project
+vstack manifest verify --target /path/to/your/project
+vstack manifest status --target /path/to/your/project
+vstack manifest upgrade --target /path/to/your/project
 ```
 
 ## Common usage patterns
@@ -79,6 +81,8 @@ Profile-wide install (optional defaults for all projects):
 vstack install --global
 ```
 
+By default, `vstack install` preserves existing unmanaged files and local edits to tracked files by comparing the current file contents with the SHA-256 checksum recorded in `vstack.json`. Use `--adopt-name <artifact-name>` to start tracking one existing unmanaged file without overwriting it. `vstack uninstall` also preserves locally modified tracked files unless you explicitly pass `--force` or `--force-name <artifact-name>`. Use `vstack manifest status --target ...` (or `vstack status --target ...`) to see what still matches the manifest. If a legacy manifest schema is detected, run `vstack manifest upgrade --target ...` first.
+
 ## Fast troubleshooting
 
 - Command not found after install: ensure your `pipx` binary path is in `PATH`

{vstack-1.3.5 → vstack-2.0.0}/pyproject.toml

@@ -32,7 +32,7 @@ classifiers = [
     "Topic :: Software Development :: Build Tools",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
-version = "1.3.5"
+version = "2.0.0"
 
 [project.urls]
 Homepage = "https://github.com/eschaar/vstack"

vstack-2.0.0/src/vstack/cli/base.py

@@ -0,0 +1,35 @@
+"""Base command contract for CLI command handlers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from argparse import Namespace
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class CommandContext:
+    """Runtime context passed to every CLI command handler."""
+
+    args: Namespace
+    install_dir: Path | None
+    only: list[str] | None
+
+    def require_install_dir(self, command_name: str) -> Path:
+        """Return install_dir or raise when the command requires one."""
+        if self.install_dir is None:
+            raise ValueError(f"{command_name} requires install_dir")
+        return self.install_dir
+
+
+class BaseCommand(ABC):
+    """Abstract base class for top-level CLI command handlers."""
+
+    @abstractmethod
+    def run(
+        self,
+        *,
+        context: CommandContext,
+    ) -> int:
+        """Execute the command and return a process-style status code."""

vstack-2.0.0/src/vstack/cli/catalog.py

@@ -0,0 +1,146 @@
+"""Central command catalogs shared by parser, registry, and interface."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from vstack.cli.base import BaseCommand
+from vstack.cli.install import InstallCommand
+from vstack.cli.manifest import ManifestCommand
+from vstack.cli.status import StatusCommand
+from vstack.cli.uninstall import UninstallCommand
+from vstack.cli.validate import ValidateCommand
+from vstack.cli.verify import VerifyCommand
+
+if TYPE_CHECKING:
+    from vstack.cli.service import CommandService
+
+
+@dataclass(frozen=True)
+class TopLevelCommandConfig:
+    """Configuration for one top-level CLI command."""
+
+    command_factory: Callable[[CommandService], BaseCommand]
+    help_text: str
+    requires_install_dir: bool
+    resolve_only_for_scope: bool
+    include_scope_group: bool
+    include_only_option: bool
+    scope_help: str | None = None
+    only_help: str | None = None
+    include_status_output_options: bool = False
+
+
+@dataclass(frozen=True)
+class ManifestSubcommandConfig:
+    """Configuration for one ``vstack manifest <action>`` subcommand."""
+
+    help_text: str
+    scope_help: str
+    include_only_option: bool
+    only_help: str | None = None
+    include_status_output_options: bool = False
+
+
+TOP_LEVEL_COMMAND_ORDER: tuple[str, ...] = (
+    "validate",
+    "verify",
+    "status",
+    "manifest",
+    "install",
+    "uninstall",
+)
+
+
+COMMAND_CATALOG: dict[str, TopLevelCommandConfig] = {
+    "validate": TopLevelCommandConfig(
+        command_factory=ValidateCommand,
+        help_text="Validate source templates only; does not inspect installed files",
+        requires_install_dir=False,
+        resolve_only_for_scope=False,
+        include_scope_group=False,
+        include_only_option=True,
+        only_help="Validate only these artifact types, e.g. --only skill agent",
+    ),
+    "verify": TopLevelCommandConfig(
+        command_factory=VerifyCommand,
+        help_text="Validate source templates and installed output against the manifest",
+        requires_install_dir=True,
+        resolve_only_for_scope=True,
+        include_scope_group=True,
+        include_only_option=True,
+        scope_help="Verify output in <dir>/.github/",
+        only_help="Verify only these artifact types, e.g. --only agent prompt",
+    ),
+    "status": TopLevelCommandConfig(
+        command_factory=StatusCommand,
+        help_text="Inspect installed artifacts against vstack.json checksums and manifest ownership",
+        requires_install_dir=True,
+        resolve_only_for_scope=True,
+        include_scope_group=True,
+        include_only_option=True,
+        scope_help="Inspect output in <dir>/.github/",
+        only_help="Inspect only these artifact types, e.g. --only skill agent",
+        include_status_output_options=True,
+    ),
+    "manifest": TopLevelCommandConfig(
+        command_factory=ManifestCommand,
+        help_text="Manage manifest lifecycle (upgrade, status, verify)",
+        requires_install_dir=True,
+        resolve_only_for_scope=True,
+        include_scope_group=False,
+        include_only_option=False,
+    ),
+    "install": TopLevelCommandConfig(
+        command_factory=InstallCommand,
+        help_text="Generate and install artifacts (--only to filter types)",
+        requires_install_dir=True,
+        resolve_only_for_scope=True,
+        include_scope_group=True,
+        include_only_option=True,
+        scope_help="Install into <dir>/.github/",
+        only_help="Install only these artifact types, e.g. --only skill agent",
+    ),
+    "uninstall": TopLevelCommandConfig(
+        command_factory=UninstallCommand,
+        help_text="Safely remove vstack-managed files tracked in the manifest",
+        requires_install_dir=True,
+        resolve_only_for_scope=True,
+        include_scope_group=True,
+        include_only_option=True,
+        scope_help="Uninstall from <dir>/.github/",
+        only_help="Uninstall only these artifact types, e.g. --only skill agent",
+    ),
+}
+
+
+MANIFEST_SUBCOMMAND_ORDER: tuple[str, ...] = (
+    "upgrade",
+    "status",
+    "verify",
+)
+
+
+MANIFEST_SUBCOMMAND_CATALOG: dict[str, ManifestSubcommandConfig] = {
+    "upgrade": ManifestSubcommandConfig(
+        help_text="Upgrade legacy vstack.json schema to current version",
+        scope_help="Upgrade manifest in <dir>/.github/",
+        include_only_option=False,
+        only_help=None,
+    ),
+    "status": ManifestSubcommandConfig(
+        help_text="Inspect installed artifacts against vstack.json checksums and manifest ownership",
+        scope_help="Inspect output in <dir>/.github/",
+        include_only_option=True,
+        only_help="Inspect only these artifact types, e.g. --only skill agent",
+        include_status_output_options=True,
+    ),
+    "verify": ManifestSubcommandConfig(
+        help_text="Verify installed output against manifest ownership and checksums",
+        scope_help="Verify output in <dir>/.github/",
+        include_only_option=True,
+        only_help="Verify only these artifact types, e.g. --only agent prompt",
+    ),
+}

vstack-2.0.0/src/vstack/cli/constants.py

@@ -0,0 +1,82 @@
+"""Canonical CLI artifact names."""
+
+from __future__ import annotations
+
+from vstack.agents.config import AGENT_TYPE
+from vstack.instructions.config import INSTRUCTION_TYPE
+from vstack.prompts.config import PROMPT_TYPE
+from vstack.skills.config import SKILL_TYPE
+
+EXPECTED_CANONICAL_NAMES = [
+    "vision",
+    "architecture",
+    "requirements",
+    "adr",
+    "design",
+    "consult",
+    "concise",
+    "code-review",
+    "release-notes",
+    "pr",
+    "verify",
+    "inspect",
+    "security",
+    "debug",
+    "performance",
+    "analyse",
+    "explore",
+    "docs",
+    "guardrails",
+    "container",
+    "cicd",
+    "migrate",
+    "openapi",
+    "refactor",
+    "onboard",
+    "dependency",
+    "incident",
+]
+
+
+class Colors:
+    """ANSI colour codes used in CLI output."""
+
+    RED = "\033[31m"
+    GREEN = "\033[32m"
+    YELLOW = "\033[33m"
+    CYAN = "\033[36m"
+    BLUE = "\033[34m"
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+    RESET = "\033[0m"
+
+
+KNOWN_TYPES = [SKILL_TYPE, AGENT_TYPE, INSTRUCTION_TYPE, PROMPT_TYPE]
+KNOWN_TYPE_NAMES = [type_config.type_name for type_config in KNOWN_TYPES]
+GLOBAL_SUPPORTED_TYPE_NAMES = [
+    AGENT_TYPE.type_name,
+    INSTRUCTION_TYPE.type_name,
+    PROMPT_TYPE.type_name,
+    SKILL_TYPE.type_name,
+]
+
+
+class ArtifactState:
+    """Canonical artifact control states returned by CLI state checks."""
+
+    MANAGED = "managed"
+    MANAGED_LEGACY = "managed-legacy"
+    MODIFIED = "modified"
+    MISSING = "missing"
+    UNTRACKED = "untracked"
+    ABSENT = "absent"
+    UNKNOWN = "unknown"
+
+
+# Names that must exist for each artifact type (used in verify --source).
+EXPECTED_INPUT_NAMES: dict[str, list[str]] = {
+    "skill": EXPECTED_CANONICAL_NAMES,
+    "agent": ["architect", "designer", "engineer", "product", "release", "tester"],
+    "instruction": ["git", "python"],
+    "prompt": ["code-review"],
+}

vstack-2.0.0/src/vstack/cli/helpers.py

@@ -0,0 +1,8 @@
+"""Shared internal helpers for CLI command handlers."""
+
+from __future__ import annotations
+
+
+def normalize_targeted_names(names: list[str] | None) -> set[str]:
+    """Normalize targeted artifact names for force/adopt operations."""
+    return {name.strip() for name in names or [] if name.strip()}