vstack 2.0.3__tar.gz → 2.1.0__tar.gz

{vstack-2.0.3 → vstack-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vstack
-Version: 2.0.3
+Version: 2.1.0
 Summary: VS Code-native AI engineering workflow system for microservices, libraries, and backend systems.
 License-Expression: MIT
 License-File: LICENSE
@@ -108,7 +108,15 @@ 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.
+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 <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 <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.
+
+If you already have agents, skills, or other files in `.github/`, run a dry-run first to see what would be preserved before committing:
+
+```bash
+vstack install --dry-run --target /path/to/your/project
+```
+
+The summary lists preserved files as `type/name` selectors (e.g. `agent/engineer`). Resolve each conflict with `--force-name type/name` to overwrite, `--adopt-name type/name` to take ownership without overwriting, or `--force` to overwrite everything.
 
 ## Fast troubleshooting
 

{vstack-2.0.3 → vstack-2.1.0}/README-pypi.md

@@ -81,7 +81,15 @@ 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.
+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 <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 <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.
+
+If you already have agents, skills, or other files in `.github/`, run a dry-run first to see what would be preserved before committing:
+
+```bash
+vstack install --dry-run --target /path/to/your/project
+```
+
+The summary lists preserved files as `type/name` selectors (e.g. `agent/engineer`). Resolve each conflict with `--force-name type/name` to overwrite, `--adopt-name type/name` to take ownership without overwriting, or `--force` to overwrite everything.
 
 ## Fast troubleshooting
 

{vstack-2.0.3 → vstack-2.1.0}/pyproject.toml

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

{vstack-2.0.3 → vstack-2.1.0}/src/vstack/artifacts/protocol.py

@@ -15,9 +15,12 @@ from vstack.models import ValidationResult
 
 
 class ArtifactGenerator(Protocol):
-    """Structural protocol satisfied by :class:`~vstack.skills.generator.SkillGenerator`
-    and :class:`~vstack.agents.generator.AgentGenerator` (and future generators for
-    prompts, instructions, etc.).
+    """Structural protocol satisfied by all artifact generators.
+
+    Implemented by :class:`~vstack.skills.generator.SkillGenerator`,
+    :class:`~vstack.agents.generator.AgentGenerator`,
+    :class:`~vstack.instructions.generator.InstructionGenerator`, and
+    :class:`~vstack.prompts.generator.PromptGenerator`.
     """
 
     def generate(self, output_dir: Path) -> ArtifactResult:

{vstack-2.0.3 → vstack-2.1.0}/src/vstack/cli/install.py

@@ -128,22 +128,21 @@ class InstallCommand(BaseCommand):
         """Print install/update/skip output line for one artifact."""
         if action == "adopt":
             print(
-                f"  {colors.CYAN}≈{colors.RESET}  {rel}"
+                f"  {prefix}{colors.CYAN}≈{colors.RESET}  {rel}"
                 f"  {colors.DIM}adopted — {reason}{colors.RESET}"
             )
             return
 
         if action == "preserve":
-            force_hint = " Use --force or --force-name for this artifact."
             print(
-                f"  {colors.YELLOW}↷{colors.RESET}  {rel}"
-                f"  {colors.DIM}preserved — {reason}.{force_hint}{colors.RESET}"
+                f"  {prefix}{colors.YELLOW}↷{colors.RESET}  {rel}"
+                f"  {colors.DIM}preserved — {reason}{colors.RESET}"
             )
             return
 
         if action == "skip":
             print(
-                f"  {colors.YELLOW}↷{colors.RESET}  {rel}"
+                f"  {prefix}{colors.YELLOW}↷{colors.RESET}  {rel}"
                 f"  {colors.DIM}skipped — already v{existing_version}{colors.RESET}"
             )
             return
@@ -245,16 +244,24 @@ class InstallCommand(BaseCommand):
         existing_entries,
         new_entries,
         checksum_algorithm: str,
-    ) -> None:
-        """Apply install decision flow for one rendered artifact."""
+    ) -> str:
+        """Apply install decision flow for one rendered artifact and return the action taken."""
         out_file = out_dir / gen.output_path(artifact.name)
         new_version = (artifact.frontmatter or {}).get("version") or VERSION
         key = f"{gen.config.type_name}/{artifact.name}"
         existing_entry = existing_entries.get(key)
         existing_version = existing_entry.version if existing_entry is not None else None
         rel = service.label(out_file)
-        force_name = artifact.name in targeted_force_names or rel in targeted_force_names
-        adopt_name = artifact.name in targeted_adopt_names or rel in targeted_adopt_names
+        force_name = (
+            artifact.name in targeted_force_names
+            or key in targeted_force_names
+            or rel in targeted_force_names
+        )
+        adopt_name = (
+            artifact.name in targeted_adopt_names
+            or key in targeted_adopt_names
+            or rel in targeted_adopt_names
+        )
         adopted_values: tuple[str | None, str] | None = None
 
         if artifact.unresolved:
@@ -306,7 +313,7 @@ class InstallCommand(BaseCommand):
                 checksum=content_hash(artifact.content),
                 checksum_algorithm=checksum_algorithm,
             )
-            return
+            return action
 
         if action == "adopt" and adopted_values is not None:
             adopted_version, adopted_checksum = adopted_values
@@ -318,7 +325,7 @@ class InstallCommand(BaseCommand):
                 checksum=adopted_checksum,
                 checksum_algorithm=checksum_algorithm,
             )
-            return
+            return action
 
         if existing_entry is not None:
             preserve_existing_entry(
@@ -326,6 +333,7 @@ class InstallCommand(BaseCommand):
                 manifest_key=gen.config.manifest_key,
                 existing_entry=existing_entry,
             )
+        return action
 
     @staticmethod
     def _write_manifest(
@@ -347,6 +355,57 @@ class InstallCommand(BaseCommand):
         manifest_file.write(manifest)
         print(f"  {colors.DIM}wrote  {service.label(manifest_file.path)}{colors.RESET}")
 
+    @staticmethod
+    def _print_summary(
+        *,
+        colors,
+        action_counts: dict[str, int],
+        preserved_selectors: list[str],
+        dry_run: bool,
+    ) -> None:
+        """Print a readable summary and conflict guidance after an install run."""
+        installed = action_counts.get("install", 0)
+        updated = action_counts.get("update", 0)
+        preserved = action_counts.get("preserve", 0)
+        skipped = action_counts.get("skip", 0)
+        adopted = action_counts.get("adopt", 0)
+
+        install_label = "installed"
+        summary_title = "Summary (dry-run)" if dry_run else "Summary"
+        total = installed + updated + preserved + skipped + adopted
+
+        print()
+        print(f"  {colors.BOLD}{summary_title}{colors.RESET}")
+        print(f"    total processed : {colors.BOLD}{total}{colors.RESET}")
+        print(f"    {install_label:<15}: {colors.BOLD}{installed}{colors.RESET}")
+        print(f"    updated         : {colors.BOLD}{updated}{colors.RESET}")
+        print(f"    preserved       : {colors.BOLD}{preserved}{colors.RESET}")
+        print(f"    skipped         : {colors.BOLD}{skipped}{colors.RESET}")
+        print(f"    adopted         : {colors.BOLD}{adopted}{colors.RESET}")
+
+        if preserved:
+            noun = "file" if preserved == 1 else "files"
+            selectors_suffix = " Preserved selectors:" if preserved_selectors else ""
+            print()
+            print(
+                f"  {colors.YELLOW}⚠{colors.RESET}  "
+                f"{preserved} {noun} preserved — existing files were not overwritten."
+                f"{selectors_suffix}"
+            )
+            if preserved_selectors:
+                for selector in sorted(preserved_selectors):
+                    print(f"     - {selector}")
+            print("  Next steps:")
+            print(f"     {colors.DIM}--force{colors.RESET}               overwrite all")
+            print(
+                f"     {colors.DIM}--force-name <name|type/name>{colors.RESET} "
+                "overwrite one artifact"
+            )
+            print(
+                f"     {colors.DIM}--adopt-name <name|type/name>{colors.RESET} "
+                "take ownership without overwriting"
+            )
+
     @staticmethod
     def execute(
         service: CommandService,
@@ -377,13 +436,15 @@ class InstallCommand(BaseCommand):
 
         prefix = f"{colors.DIM}[dry-run]{colors.RESET} " if dry_run else ""
         all_ok = True
+        action_counts: dict[str, int] = {}
+        preserved_selectors: set[str] = set()
 
         for gen in gens:
             out_dir = install_dir / gen.config.output_subdir
             artifacts = gen.render_all()
 
             for artifact in artifacts:
-                InstallCommand._install_single_artifact(
+                artifact_action = InstallCommand._install_single_artifact(
                     service=service,
                     gen=gen,
                     artifact=artifact,
@@ -399,6 +460,9 @@ class InstallCommand(BaseCommand):
                     new_entries=new_entries,
                     checksum_algorithm=checksum_algorithm,
                 )
+                action_counts[artifact_action] = action_counts.get(artifact_action, 0) + 1
+                if artifact_action == "preserve":
+                    preserved_selectors.add(f"{gen.config.type_name}/{artifact.name}")
 
             # Verify source for unresolvable issues.
             verify_result = gen.verify_input()
@@ -407,6 +471,13 @@ class InstallCommand(BaseCommand):
                     print(f"  ERROR [{gen.config.type_name}]: {msg.message}", file=sys.stderr)
                     all_ok = False
 
+        InstallCommand._print_summary(
+            colors=colors,
+            action_counts=action_counts,
+            preserved_selectors=sorted(preserved_selectors),
+            dry_run=dry_run,
+        )
+
         if not dry_run:
             InstallCommand._write_manifest(
                 service=service,

{vstack-2.0.3 → vstack-2.1.0}/src/vstack/cli/parser.py

@@ -177,17 +177,24 @@ class CommandLineParser:
             "--force-name",
             dest="force_names",
             action="append",
-            metavar="<artifact-name>",
-            help="Force install one named artifact without overwriting everything",
+            metavar="<name|type/name>",
+            help=(
+                "Force install one named artifact without overwriting everything. "
+                "Accepts a plain name (e.g. engineer) or a type/name selector "
+                "(e.g. agent/engineer) to disambiguate when multiple artifact types "
+                "share the same name. Repeat to target multiple artifacts."
+            ),
         )
         parser.add_argument(
             "--adopt-name",
             action="append",
             default=None,
-            metavar="NAME",
+            metavar="<name|type/name>",
             help=(
                 "Adopt only the named existing unmanaged artifact into the manifest without overwriting it. "
-                "Repeat this option to target multiple names."
+                "Accepts a plain name (e.g. engineer) or a type/name selector "
+                "(e.g. agent/engineer) to disambiguate when multiple artifact types "
+                "share the same name. Repeat to target multiple artifacts."
             ),
         )
         parser.add_argument(

{vstack-2.0.3 → vstack-2.1.0}/src/vstack/cli/service.py

@@ -1,13 +1,16 @@
-"""All vstack CLI commands as instance methods on :class:`CommandService`.
-
-The CLI is entirely type-generic: it iterates over
-:data:`~vstack.artifacts.type_config.KNOWN_TYPES` for validate, install, and
-verify instead of hard-coding skill-specific and agent-specific logic.
-
-All commands that touch the install root accept a single ``install_dir``
-(either workspace ``.github/`` or the VS Code user profile directory)
-rather than separate ``skills_dir`` / ``agents_dir`` parameters — per-type
-sub-directories are derived from
+"""Shared coordinator for vstack CLI command handlers.
+
+:class:`CommandService` wires artifact-type generators and manifest access
+into the services that individual :class:`~vstack.cli.base.BaseCommand`
+subclasses use when executing.  Commands live in their own modules
+(``install``, ``verify``, ``uninstall``, ``validate``, ``manifest``,
+``status``) and receive a :class:`~vstack.cli.base.CommandContext` at
+dispatch time.
+
+The service is type-generic: it iterates over
+:data:`~vstack.artifacts.type_config.KNOWN_TYPES` rather than hard-coding
+skill-specific or agent-specific logic.  Per-type sub-directories are
+derived from
 :attr:`~vstack.artifacts.type_config.ArtifactTypeConfig.output_subdir`.
 """