@unlimitechcloud/devlink 1.0.2

package/docs/maintenance/prune.md

@@ -0,0 +1,159 @@
+# Prune Command
+
+Removes orphaned packages from the store.
+
+## Usage
+
+```bash
+devlink prune [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-n, --namespace <name>` | Only prune in specific namespace |
+| `--dry-run` | Show what would be removed without removing |
+| `--repo <path>` | Use custom repo path |
+
+## Description
+
+The `prune` command removes packages that exist on disk but are not in the registry. These "orphaned" packages can occur when:
+
+- A publish operation was interrupted
+- Files were manually added to the store
+- The registry was corrupted or restored from backup
+
+## Examples
+
+### Prune All Orphans
+
+```bash
+devlink prune
+```
+
+Output:
+```
+🧹 Pruning orphaned packages...
+
+Removed:
+  ✓ global/@scope/orphan@1.0.0
+  ✓ feature-v2/@scope/old-pkg@2.0.0
+
+Pruned 2 package(s), freed 15.2 MB
+```
+
+### Dry Run
+
+Preview what would be removed:
+
+```bash
+devlink prune --dry-run
+```
+
+Output:
+```
+🧹 Pruning orphaned packages (dry run)...
+
+Would remove:
+  - global/@scope/orphan@1.0.0 (5.1 MB)
+  - feature-v2/@scope/old-pkg@2.0.0 (10.1 MB)
+
+Would prune 2 package(s), free 15.2 MB
+
+Run without --dry-run to actually remove
+```
+
+### Prune Specific Namespace
+
+```bash
+devlink prune -n feature-v2
+```
+
+Output:
+```
+🧹 Pruning orphaned packages in 'feature-v2'...
+
+Removed:
+  ✓ feature-v2/@scope/old-pkg@2.0.0
+
+Pruned 1 package(s), freed 10.1 MB
+```
+
+### No Orphans Found
+
+```bash
+devlink prune
+```
+
+Output:
+```
+🧹 Pruning orphaned packages...
+
+No orphaned packages found.
+Store is clean ✓
+```
+
+## Difference from Verify --fix
+
+| Command | What it does |
+|---------|--------------|
+| `verify --fix` | Fixes both registry orphans AND disk orphans |
+| `prune` | Only removes disk orphans |
+
+Use `verify --fix` for comprehensive cleanup, or `prune` when you specifically want to clean disk orphans.
+
+## Use Cases
+
+### Regular Maintenance
+
+Run periodically to keep the store clean:
+
+```bash
+devlink prune --dry-run  # Check first
+devlink prune            # Then clean
+```
+
+### After Failed Operations
+
+If a publish was interrupted:
+
+```bash
+devlink prune
+```
+
+### Before Backup
+
+Clean up before backing up the store:
+
+```bash
+devlink prune
+tar -czf devlink-backup.tar.gz ~/.devlink
+```
+
+### Disk Space Recovery
+
+Find and remove orphaned packages to free space:
+
+```bash
+devlink prune --dry-run  # See how much space would be freed
+devlink prune            # Actually free the space
+```
+
+## Safety
+
+The `prune` command only removes packages that are NOT in the registry. Packages that are properly registered will never be removed.
+
+To be extra safe, always use `--dry-run` first:
+
+```bash
+devlink prune --dry-run
+# Review the output
+devlink prune
+```
+
+## See Also
+
+- [Verify Command](verify.md) - Check and fix store integrity
+- [Remove Command](remove.md) - Explicitly remove packages
+- [Store Structure](../store/structure.md) - Understanding the store layout

package/docs/maintenance/remove.md

@@ -0,0 +1,174 @@
+# Remove Command
+
+Removes packages, versions, or namespaces from the store.
+
+## Usage
+
+```bash
+devlink remove <target> [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `<target>` | What to remove (see Target Types) |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-n, --namespace <name>` | Target namespace (required for packages) |
+| `--repo <path>` | Use custom repo path |
+
+## Target Types
+
+### Specific Version
+
+Remove a single version of a package:
+
+```bash
+devlink remove @scope/core@1.0.0 -n global
+```
+
+### Entire Package
+
+Remove all versions of a package:
+
+```bash
+devlink remove @scope/core -n global
+```
+
+### Namespace
+
+Remove an entire namespace and all packages within:
+
+```bash
+devlink remove feature-v2
+```
+
+## Examples
+
+### Remove Specific Version
+
+```bash
+devlink remove @scope/core@1.0.0 -n global
+```
+
+Output:
+```
+✓ Removed @scope/core@1.0.0 from namespace 'global'
+```
+
+### Remove All Versions
+
+```bash
+devlink remove @scope/core -n global
+```
+
+Output:
+```
+✓ Removed package '@scope/core' from namespace 'global'
+```
+
+### Remove Namespace
+
+```bash
+devlink remove feature-v2
+```
+
+Output:
+```
+✓ Removed namespace 'feature-v2'
+```
+
+## Restrictions
+
+### Cannot Remove Global Namespace
+
+The `global` namespace is reserved and cannot be deleted:
+
+```bash
+devlink remove global
+```
+
+Output:
+```
+Error: Cannot delete reserved namespace 'global'
+```
+
+### Namespace Required for Packages
+
+When removing packages, you must specify the namespace:
+
+```bash
+# Error: namespace required
+devlink remove @scope/core
+
+# Correct
+devlink remove @scope/core -n global
+```
+
+## What Gets Removed
+
+### Version Removal
+
+- Package files from disk
+- Version entry from registry
+- If last version, package entry is also removed
+
+### Package Removal
+
+- All version directories
+- Package directory
+- Package entry from registry
+
+### Namespace Removal
+
+- All packages in the namespace
+- Namespace directory
+- Namespace entry from registry
+
+## Consumer Impact
+
+Removing packages does NOT automatically update consumers. Projects that have installed the removed package will:
+
+- Keep their existing symlinks (may become broken)
+- Need to reinstall with a different version/namespace
+
+To check affected consumers before removing:
+
+```bash
+devlink consumers -p @scope/core -n global
+```
+
+## Use Cases
+
+### Clean Up Old Versions
+
+```bash
+# Keep only latest version
+devlink remove @scope/core@1.0.0 -n global
+devlink remove @scope/core@1.1.0 -n global
+# 2.0.0 remains
+```
+
+### Remove Feature Branch Namespace
+
+After merging a feature branch:
+
+```bash
+devlink remove feature-auth-v2
+```
+
+### Remove Accidentally Published Package
+
+```bash
+devlink remove @scope/wrong-pkg -n global
+```
+
+## See Also
+
+- [Prune Command](prune.md) - Remove orphaned packages
+- [Verify Command](verify.md) - Check store integrity
+- [Namespaces](../store/namespaces.md) - Understanding namespaces

package/docs/maintenance/verify.md

@@ -0,0 +1,174 @@
+# Verify Command
+
+Verifies the integrity of the DevLink store.
+
+## Usage
+
+```bash
+devlink verify [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--fix` | Automatically fix issues found |
+| `--repo <path>` | Use custom repo path |
+
+## Description
+
+The `verify` command checks for inconsistencies between:
+
+- The registry (`registry.json`)
+- The actual files on disk
+
+## Checks Performed
+
+### Orphans in Registry
+
+Entries in the registry that don't have corresponding files on disk.
+
+**Cause**: Files were manually deleted or corrupted.
+
+**Fix**: Remove the registry entry.
+
+### Orphans on Disk
+
+Files on disk that don't have corresponding registry entries.
+
+**Cause**: Publish was interrupted, or files were manually added.
+
+**Fix**: Remove the orphaned files.
+
+### Signature Mismatches
+
+Package content doesn't match the recorded signature.
+
+**Cause**: Files were modified after publishing.
+
+**Fix**: Recalculate and update signature.
+
+## Examples
+
+### Check Store Integrity
+
+```bash
+devlink verify
+```
+
+Output (healthy store):
+```
+🔍 Verifying store integrity...
+
+global/
+  ✓ @scope/core@1.0.0
+  ✓ @scope/core@2.0.0
+  ✓ @scope/utils@1.0.0
+
+feature-v2/
+  ✓ @scope/core@1.0.0
+
+─────────────────────────────────
+Summary:
+  ✓ Valid:                4
+  ✗ Orphans in registry:  0
+  ⚠ Orphans on disk:      0
+
+Store is healthy ✓
+```
+
+### Store with Issues
+
+```bash
+devlink verify
+```
+
+Output:
+```
+🔍 Verifying store integrity...
+
+global/
+  ✓ @scope/core@1.0.0
+  ✗ @scope/data@1.0.0 - In registry, not on disk
+  ✓ @scope/utils@1.0.0
+  ⚠ @scope/orphan@1.0.0 - On disk, not in registry
+
+─────────────────────────────────
+Summary:
+  ✓ Valid:                2
+  ✗ Orphans in registry:  1
+  ⚠ Orphans on disk:      1
+
+Run 'devlink verify --fix' to repair
+```
+
+### Auto-Fix Issues
+
+```bash
+devlink verify --fix
+```
+
+Output:
+```
+🔍 Verifying and fixing store...
+
+Fixing orphans in registry:
+  ✓ Removed @scope/data@1.0.0 from registry
+
+Fixing orphans on disk:
+  ✓ Removed @scope/orphan@1.0.0 from disk
+
+─────────────────────────────────
+Fixed 2 issue(s)
+Store is now healthy ✓
+```
+
+## When to Use
+
+### After System Crash
+
+If DevLink or your system crashed during an operation:
+
+```bash
+devlink verify --fix
+```
+
+### Periodic Maintenance
+
+Run periodically to ensure store health:
+
+```bash
+devlink verify
+```
+
+### Before Important Operations
+
+Verify before publishing critical packages:
+
+```bash
+devlink verify
+devlink publish
+```
+
+### After Manual File Operations
+
+If you manually modified files in the store:
+
+```bash
+devlink verify --fix
+```
+
+## Lock Requirement
+
+| Mode | Requires Lock |
+|------|---------------|
+| `verify` | No |
+| `verify --fix` | Yes |
+
+The `--fix` flag modifies the store, so it requires an exclusive lock.
+
+## See Also
+
+- [Prune Command](prune.md) - Remove orphaned packages
+- [Store Structure](../store/structure.md) - Understanding the store layout
+- [File Locking](../store/locking.md) - How locking works

package/docs/publishing/publish.md

@@ -0,0 +1,146 @@
+# Publish Command
+
+Publishes a package from the current directory to the DevLink store.
+
+## Usage
+
+```bash
+devlink publish [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-n, --namespace <name>` | Target namespace (default: `global`) |
+| `--repo <path>` | Use custom repo path |
+
+## Description
+
+The `publish` command:
+
+1. Reads `package.json` from the current directory
+2. Validates that `name` and `version` fields exist
+3. Copies files to the store based on the `files` field
+4. Generates a content signature (MD5 hash)
+5. Updates the registry with package metadata
+
+## Package Requirements
+
+Your `package.json` must have:
+
+```json
+{
+  "name": "@scope/my-package",
+  "version": "1.0.0",
+  "files": ["dist", "lib"]
+}
+```
+
+- **name**: Package name (scoped or unscoped)
+- **version**: Semantic version
+- **files**: Array of files/directories to include
+
+## Examples
+
+### Publish to Global
+
+```bash
+cd my-package
+devlink publish
+```
+
+Output:
+```
+📦 @scope/my-package@1.0.0 published to global
+   Signature: 6761ca1fefdde1b6e9ea372e7d6931e4
+   Files: 15
+   Path: ~/.devlink/namespaces/global/@scope/my-package/1.0.0
+```
+
+### Publish to Custom Namespace
+
+```bash
+devlink publish -n feature-v2
+```
+
+### Publish to Custom Repo
+
+```bash
+devlink publish --repo /path/to/repo
+```
+
+### Publish Multiple Versions
+
+```bash
+# Publish v1
+devlink publish
+
+# Update version in package.json to 2.0.0
+devlink publish  # Both versions coexist
+```
+
+## What Gets Published
+
+Files are selected based on the `files` field in `package.json`:
+
+```json
+{
+  "files": ["dist", "lib", "README.md"]
+}
+```
+
+Always included:
+- `package.json`
+
+The following are typically excluded:
+- `node_modules/`
+- `.git/`
+- Test files
+- Source files (unless specified)
+
+## Signature
+
+Each published version gets a signature file (`devlink.sig`) containing an MD5 hash of the package contents. This is used for:
+
+- Integrity verification
+- Change detection
+- Consumer updates (push command)
+
+## Overwriting Versions
+
+Publishing the same version again overwrites the existing content:
+
+```bash
+# First publish
+devlink publish  # @scope/pkg@1.0.0
+
+# Make changes, publish again
+devlink publish  # Overwrites @scope/pkg@1.0.0
+```
+
+The signature will change if the content changed.
+
+## Errors
+
+### Missing package.json
+
+```
+Error: package.json not found
+```
+
+Ensure you're in a directory with a valid `package.json`.
+
+### Missing name or version
+
+```
+Error: package.json must have name and version fields
+```
+
+Add the required fields to your `package.json`.
+
+## See Also
+
+- [Push Command](push.md) - Publish and update consumers
+- [Store Structure](../store/structure.md) - Where packages are stored
+- [Namespaces](../store/namespaces.md) - Understanding namespaces