feat: Add package pinning command (pin/unpin)

[AshokThangavel]

Feature: Package Pinning (pin/unpin) Implementation

This Pull Request introduces package pinning functionality. This feature allows users to lock an installed module's version, preventing accidental or automatic upgrades, downgrades, or removal until explicitly unpinned.

1. Overview

This feature enhances IPM's stability and dependency management by implementing a mechanism to lock installed modules. This ensures production or critical modules remain fixed at a specific version, protecting them from core IPM modification commands.

The implementation relies on a new persistent storage class to track pinned modules.

2. New Commands: pin and unpin

2.1. pin Command

Marks a specific, installed module as pinned to prevent future modification operations.

Usage Examples:

zpm:USER>pin web-fslog
Module web-fslog is now pinned

zpm:USER>pin web-fslog
ERROR! Module web-fslog already pinned

zpm:USER>pin test-package
ERROR! Module test-package not found

2.2. unpin Command

Removes the pinned status from an installed module, allowing future ZPM operations (install, reinstall,uninstall, update) to proceed normally.

Usage Examples:

zpm:USER>unpin web-fslog
Module web-fslog is now unpinned

zpm:USER>unpin web-fslog
ERROR! Module web-fsog not currently pinned.

---

3. Architectural and Visibility Changes

3.1. Storage Mechanism

A new independent storage class, %IPM.Storage.PinnedModule, was created to manage the list of all modules marked as pinned, their version, and their current status.

3.2. Visibility and Discovery

• list command: The status -Pinned is appended to the version number for easy identification (e.g., web-fslog 1.0.0-Pinned).
• list -p modifier: A new modifier, -p (or --pinned), was implemented. This allows users to quickly list and audit only the modules that are currently pinned.

---

4. Operational Blocking (Integrity Check)

The pinning status is checked at the codebase level within the execution logic for all modification commands. If a module is pinned, the command is blocked and a specific error is returned.

Command	Status when Pinned	Example Output
install	BLOCKED	ERROR! The module web-fslog is pinned unable to install
reinstall	BLOCKED	ERROR! The module web-fslog is pinned unable to reinstall
uninstall	BLOCKED	ERROR! The module web-fslog is pinned unable to uninstall
update	BLOCKED	ERROR! The module web-fslog is pinned unable to update

Verification Trace for Blocking

The following sequence confirms the blocking mechanism when a module is pinned:

zpm:USER>pin web-fslog
Module web-fslog is now pinned

zpm:USER>install web-fslog
ERROR! The module web-fslog is pinned unable to install

zpm:USER>reinstall web-fslog
ERROR! The module web-fslog is pinned unable to reinstall

zpm:USER>uninstall web-fslog
ERROR! The module web-fslog is pinned unable to uninstall

Verification Trace for Unlocking

The following sequence confirms that the unpin command correctly restores the ability to modify the package:

zpm:USER>unpin web-fslog
Module web-fslog is now unpinned

zpm:USER>reinstall web-fslog
Reinstalling web-fslog 1.0.0 (Unpinning restored functionality)

---

5. Unit Testing Results

Integration and unit tests were created to validate the entire lifecycle of the pin feature and its interaction with core ZPM commands. All 20 assertions passed.

#	Action Status	Description
1-2	Passed	Successfully installed the test module (web-fslog).
3-4	Passed	Successfully pinned the installed module.
5-6	Passed	Blocked pinning the already pinned module (AssertStatusNotOK).
7-8	Passed	Blocked install command on the pinned module (AssertStatusNotOK).
9-10	Passed	Blocked reinstall command on the pinned module (AssertStatusNotOK).
11-12	Passed	Blocked uninstall command on the pinned module (AssertStatusNotOK).
13-14	Passed	Blocked update command on the pinned module (AssertStatusNotOK).
15-16	Passed	Successfully unpinned the module.
17-18	Passed	Successfully uninstalled the module after being unpinned.
19-20	Passed	Blocked unpin command on a module that was already unpinned (AssertStatusNotOK).

Resolves #968

[AshokThangavel]

As per discussion #968

1. Dependency Protection Strategy

The pin command defaults to protecting dependencies, thereby preserving the integrity of the pinned module, and introduces a -shallow flag to override this behavior.

Command	Action	Rationale / Use Case
pin ModuleA (Default)	Pins Module A and Implicitly Protects all dependencies (Module B, C, etc.).	Maximum Stability. This is the safest default, ensuring that the critical dependencies required by Module A cannot be accidentally uninstalled or updated, preventing side effects in production environments.
pin ModuleA -shallow	Pins ONLY Module A. Dependencies remain unprotected.	Developer Control. This addresses the scenario where a developer needs to actively update or debug a dependency (like Module B) while still keeping the main package (Module A) pinned against accidental modification.

2. Implementation Details

A. Implicit Protection Logic (Default)

When a module is implicitly protected (Module B is protected by Pinned Module A), the core IPM modification commands (install, update, uninstall) will be blocked on Module B, citing that it is a dependency of a pinned package.

B. Unpinning Logic

The protection on a dependency (Module B) will only be lifted when the last pinned module that relies on it (Module A) is unpinned.