@unlimitechcloud/devlink 1.0.2

package/docs/publishing/push.md

@@ -0,0 +1,146 @@
+# Push Command
+
+Publishes a package and automatically updates all consumer projects.
+
+## Usage
+
+```bash
+devlink push [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-n, --namespace <name>` | Target namespace (default: `global`) |
+| `--repo <path>` | Use custom repo path |
+
+## Description
+
+The `push` command combines publishing with automatic consumer updates:
+
+1. Publishes the package (same as `devlink publish`)
+2. Finds all projects that have installed this package
+3. Re-links the package in each consumer project
+4. Updates signatures in `installations.json`
+5. Updates `devlink.lock` files in consumer projects
+
+This is the recommended command during active development.
+
+## Example
+
+```bash
+cd my-sdk/packages/core
+devlink push
+```
+
+Output:
+```
+📦 @scope/core@1.0.0 published to global
+   Signature: abc123new
+
+🔄 Pushing to 2 project(s):
+   ✓ /home/user/project-a
+   ✓ /home/user/project-b
+```
+
+## How It Works
+
+### 1. Publish Phase
+
+Same as `devlink publish`:
+- Copies files to store
+- Updates registry
+- Generates new signature
+
+### 2. Find Consumers
+
+Searches `installations.json` for projects that:
+- Have installed this package
+- From the same namespace
+- With the same version
+
+### 3. Update Consumers
+
+For each consumer project:
+- Verifies project still exists
+- Re-creates symlink in `node_modules`
+- Updates signature in `installations.json`
+- Updates `devlink.lock` file
+
+## Consumer Tracking
+
+Projects become "consumers" when they run `devlink install`. The installation is recorded in `installations.json`:
+
+```json
+{
+  "projects": {
+    "/home/user/project-a": {
+      "packages": {
+        "@scope/core": {
+          "version": "1.0.0",
+          "namespace": "global",
+          "signature": "old-signature"
+        }
+      }
+    }
+  }
+}
+```
+
+After `push`, the signature is updated to match the new content.
+
+## Use Cases
+
+### Active Development
+
+When developing a library used by multiple projects:
+
+```bash
+# Make changes to library
+vim src/index.ts
+
+# Build
+npm run build
+
+# Push to all consumers
+devlink push
+```
+
+All consumer projects immediately get the updated code.
+
+### Feature Branch Development
+
+```bash
+# Publish to feature namespace
+devlink push -n feature-v2
+
+# Only consumers using feature-v2 namespace are updated
+```
+
+## Dead Projects
+
+If a consumer project no longer exists (deleted), `push` will:
+- Skip that project
+- Show a warning
+- Continue with other projects
+
+To clean up dead projects:
+
+```bash
+devlink consumers --prune
+```
+
+## Comparison with Publish
+
+| Aspect | `publish` | `push` |
+|--------|-----------|--------|
+| Publishes package | ✓ | ✓ |
+| Updates consumers | ✗ | ✓ |
+| Use case | Initial publish | Active development |
+
+## See Also
+
+- [Publish Command](publish.md) - Publishing without consumer updates
+- [Consumers Command](../inspection/consumers.md) - Managing consumer projects
+- [Install Command](../installation/install.md) - How projects become consumers

package/docs/store/locking.md

@@ -0,0 +1,118 @@
+# File Locking
+
+DevLink uses file locking to serialize write operations and prevent store corruption when multiple processes access the store simultaneously.
+
+## How It Works
+
+When a command needs to modify the store, it:
+
+1. Attempts to acquire an exclusive lock
+2. If lock is held by another process, waits and retries
+3. Executes the operation
+4. Releases the lock
+
+## Lock File
+
+The lock is implemented as a file at `{store}/.lock`:
+
+```json
+{
+  "pid": 12345,
+  "acquired": "2026-02-12T10:00:00Z",
+  "command": "devlink publish"
+}
+```
+
+## Operations Requiring Lock
+
+| Command | Requires Lock | Reason |
+|---------|---------------|--------|
+| `publish` | ✓ | Modifies registry.json, writes files |
+| `push` | ✓ | Modifies registry.json, installations.json |
+| `install` | ✓ | Modifies installations.json |
+| `remove` | ✓ | Modifies registry.json, deletes files |
+| `verify --fix` | ✓ | Modifies registry.json |
+| `prune` | ✓ | Modifies registry.json, deletes files |
+| `consumers --prune` | ✓ | Modifies installations.json |
+| `list` | ✗ | Read-only |
+| `resolve` | ✗ | Read-only |
+| `verify` | ✗ | Read-only |
+| `consumers` | ✗ | Read-only |
+
+## Lock Parameters
+
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| Timeout | 30 seconds | Maximum wait time for lock |
+| Retry interval | 100ms | Time between retry attempts |
+| Stale detection | 10 seconds | Lock considered stale if process is dead |
+
+## Stale Lock Detection
+
+If a process crashes while holding the lock, DevLink detects this by:
+
+1. Reading the PID from the lock file
+2. Checking if that process is still running
+3. If process is dead, removing the stale lock
+
+This prevents deadlocks from crashed processes.
+
+## Concurrent Access Example
+
+```
+Terminal A: devlink publish          Terminal B: devlink push
+─────────────────────────────        ─────────────────────────
+
+1. Acquire lock ✓                    1. Acquire lock
+                                        ⏳ Store locked by PID 1234
+2. Read registry.json
+3. Copy files                        2. Retry (100ms)
+4. Update registry.json                 ⏳ Still locked
+5. Release lock ✓
+                                     3. Acquire lock ✓
+                                     4. Continue operation...
+                                     5. Release lock ✓
+```
+
+## Troubleshooting
+
+### Lock Timeout
+
+If you see "Lock timeout" errors:
+
+1. Check if another DevLink process is running
+2. Check for stale lock files (process crashed)
+3. Manually remove `.lock` file if necessary
+
+```bash
+# Check lock file
+cat ~/.devlink/.lock
+
+# Remove stale lock (use with caution)
+rm ~/.devlink/.lock
+```
+
+### Multiple Repos
+
+Each repo has its own lock file, so operations on different repos don't block each other:
+
+```bash
+# These can run simultaneously
+devlink --repo /repo-a publish &
+devlink --repo /repo-b publish &
+```
+
+## Implementation Details
+
+The lock uses atomic file operations:
+
+1. Create lock file with `O_EXCL` flag (fails if exists)
+2. Write lock info (PID, timestamp, command)
+3. On release, delete lock file
+
+This ensures only one process can hold the lock at a time.
+
+## See Also
+
+- [Store Structure](structure.md) - Lock file location
+- [Verify Command](../maintenance/verify.md) - Check store integrity

package/docs/store/namespaces.md

@@ -0,0 +1,141 @@
+# Namespaces
+
+Namespaces provide isolated contexts for packages, allowing multiple versions or variants of the same package to coexist.
+
+## Concept
+
+A namespace is a logical container for packages. Each namespace is independent, meaning:
+
+- The same package@version can exist in multiple namespaces with different content
+- Projects can choose which namespaces to search when resolving packages
+- Feature branches can have their own namespace without affecting stable packages
+
+## The Global Namespace
+
+The `global` namespace is special:
+
+- **Reserved**: Cannot be deleted
+- **Default**: Used when no namespace is specified
+- **Fallback**: Typically the last namespace in precedence order
+
+```bash
+# These are equivalent
+devlink publish
+devlink publish -n global
+```
+
+## Creating Namespaces
+
+Namespaces are created automatically when you publish to them:
+
+```bash
+# Creates 'feature-v2' namespace if it doesn't exist
+devlink publish -n feature-v2
+```
+
+## Use Cases
+
+### Feature Branch Development
+
+Isolate experimental changes without affecting stable packages:
+
+```bash
+# Developer working on v2 API
+cd my-sdk
+devlink publish -n sdk-v2
+
+# Consumer project uses sdk-v2 first, falls back to global
+# devlink.config.mjs:
+# namespaces: ["sdk-v2", "global"]
+```
+
+### Team Isolation
+
+Different teams can have their own namespaces:
+
+```bash
+devlink publish -n team-frontend
+devlink publish -n team-backend
+```
+
+### Version Testing
+
+Test new versions before promoting to global:
+
+```bash
+# Publish beta to testing namespace
+devlink publish -n testing
+
+# After validation, publish to global
+devlink publish -n global
+```
+
+## Namespace Precedence
+
+When resolving packages, namespaces are searched in order:
+
+```javascript
+// devlink.config.mjs
+export default {
+  dev: () => ({
+    manager: "store",
+    namespaces: ["feature-v2", "global"],
+  }),
+};
+```
+
+Resolution order:
+1. Search in `feature-v2`
+2. If not found, search in `global`
+3. If not found anywhere, error
+
+### Example
+
+```
+Store contents:
+  global/@scope/core@1.0.0
+  global/@scope/utils@1.0.0
+  feature-v2/@scope/core@1.0.0  (different code)
+
+With namespaces: ["feature-v2", "global"]
+
+Resolving @scope/core@1.0.0:
+  → Found in feature-v2 ✓
+
+Resolving @scope/utils@1.0.0:
+  → Not in feature-v2
+  → Found in global ✓
+```
+
+## Listing Namespaces
+
+```bash
+# List all packages grouped by namespace
+devlink list
+
+# List specific namespaces
+devlink list -n global,feature-v2
+```
+
+## Removing Namespaces
+
+```bash
+# Remove entire namespace (and all packages within)
+devlink remove feature-v2
+
+# Note: Cannot remove 'global' namespace
+devlink remove global  # Error!
+```
+
+## Best Practices
+
+1. **Use descriptive names**: `feature-auth-v2`, `team-mobile`, `release-candidate`
+2. **Clean up old namespaces**: Remove namespaces when feature branches are merged
+3. **Keep global stable**: Only publish tested packages to global
+4. **Document namespace usage**: Let team members know which namespaces to use
+
+## See Also
+
+- [Store Structure](structure.md) - How namespaces are stored on disk
+- [Resolve Command](../inspection/resolve.md) - Debug namespace resolution
+- [Configuration](../installation/configuration.md) - Configure namespace precedence

package/docs/store/structure.md

@@ -0,0 +1,163 @@
+# Store Structure
+
+The DevLink store is a centralized repository for locally published packages.
+
+## Default Location
+
+By default, the store is located at:
+
+- **Linux/macOS**: `~/.devlink/`
+- **Windows**: `%LOCALAPPDATA%\DevLink\`
+
+## Custom Location
+
+You can use a custom location via:
+
+```bash
+# Command line flag
+devlink --repo /path/to/repo list
+
+# Environment variable
+export DEVLINK_REPO=/path/to/repo
+devlink list
+```
+
+This allows maintaining multiple independent stores for different projects or teams.
+
+## Directory Structure
+
+```
+~/.devlink/                          # Store root
+├── .lock                            # Lock file for write serialization
+├── registry.json                    # Package index (metadata)
+├── installations.json               # Consumer project tracking
+└── namespaces/                      # Package storage
+    ├── global/                      # Default namespace (reserved)
+    │   ├── @scope/                  # Scoped packages
+    │   │   └── package-name/
+    │   │       ├── 1.0.0/           # Version directory
+    │   │       │   ├── package.json
+    │   │       │   ├── devlink.sig  # Content signature
+    │   │       │   └── dist/        # Package files
+    │   │       └── 2.0.0/
+    │   └── simple-package/          # Non-scoped packages
+    │       └── 1.0.0/
+    └── feature-branch/              # Custom namespace
+        └── @scope/
+            └── package-name/
+                └── 1.0.0/
+```
+
+## Files
+
+### registry.json
+
+The registry is an index of all published packages. It contains metadata but not the actual package files.
+
+```json
+{
+  "version": "1.0.0",
+  "namespaces": {
+    "global": {
+      "created": "2026-02-12T10:00:00Z",
+      "packages": {
+        "@scope/package": {
+          "versions": {
+            "1.0.0": {
+              "signature": "6761ca1fefdde1b6e9ea372e7d6931e4",
+              "published": "2026-02-12T10:00:00Z",
+              "files": 15
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### installations.json
+
+Tracks which projects have installed packages from the store. Used by the `push` command to update consumers.
+
+```json
+{
+  "version": "1.0.0",
+  "projects": {
+    "/home/user/my-project": {
+      "registered": "2026-02-12T10:00:00Z",
+      "packages": {
+        "@scope/package": {
+          "version": "1.0.0",
+          "namespace": "global",
+          "signature": "6761ca1f...",
+          "installedAt": "2026-02-12T10:05:00Z"
+        }
+      }
+    }
+  }
+}
+```
+
+### .lock
+
+A lock file used to serialize write operations. Contains information about the process holding the lock.
+
+```json
+{
+  "pid": 12345,
+  "acquired": "2026-02-12T10:00:00Z",
+  "command": "devlink publish"
+}
+```
+
+### devlink.sig
+
+Each published package version contains a signature file with an MD5 hash of the package contents. Used for integrity verification.
+
+## Package Storage
+
+Packages are stored in a hierarchical structure:
+
+```
+namespaces/{namespace}/{package-name}/{version}/
+```
+
+For scoped packages:
+```
+namespaces/{namespace}/@{scope}/{package-name}/{version}/
+```
+
+Each version directory contains:
+- `package.json` - Package manifest
+- `devlink.sig` - Content signature
+- All files specified in the package's `files` field
+
+## Multiple Versions
+
+Multiple versions of the same package can coexist:
+
+```
+namespaces/global/@scope/core/
+├── 1.0.0/
+├── 1.1.0/
+└── 2.0.0/
+```
+
+## Multiple Namespaces
+
+The same package can exist in different namespaces with different content:
+
+```
+namespaces/
+├── global/
+│   └── @scope/core/1.0.0/    # Stable version
+└── feature-v2/
+    └── @scope/core/1.0.0/    # Development version (different code)
+```
+
+## See Also
+
+- [Namespaces](namespaces.md) - Understanding namespace isolation
+- [File Locking](locking.md) - Concurrency control
+- [Publish Command](../publishing/publish.md) - Publishing packages

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@unlimitechcloud/devlink",
+  "version": "1.0.2",
+  "description": "Local package development and linking tool with namespace support",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "devlink": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "AGENTS.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unlimitechcloud/devlink.git"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run build",
+    "publish:local": "node dist/cli.js publish"
+  },
+  "keywords": [
+    "npm",
+    "link",
+    "local",
+    "development",
+    "monorepo",
+    "packages",
+    "dependencies"
+  ],
+  "author": "UnlimitechCloud",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "dependencies": {
+    "cli-color": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}