@unlimitechcloud/devlink 1.0.2

package/dist/types.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Types - Definiciones de tipos para DevLink
+ */
+/**
+ * Registry principal del store
+ */
+export interface Registry {
+    version: string;
+    namespaces: Record<string, NamespaceEntry>;
+}
+/**
+ * Entrada de un namespace en el registry
+ */
+export interface NamespaceEntry {
+    created: string;
+    packages: Record<string, PackageEntry>;
+}
+/**
+ * Entrada de un paquete en el registry
+ */
+export interface PackageEntry {
+    versions: Record<string, VersionEntry>;
+}
+/**
+ * Entrada de una versión en el registry
+ */
+export interface VersionEntry {
+    signature: string;
+    published: string;
+    files: number;
+}
+/**
+ * Tracking de instalaciones
+ */
+export interface Installations {
+    version: string;
+    projects: Record<string, ProjectEntry>;
+}
+/**
+ * Entrada de un proyecto en installations
+ */
+export interface ProjectEntry {
+    registered: string;
+    packages: Record<string, InstalledPackage>;
+}
+/**
+ * Información de un paquete instalado en un proyecto
+ */
+export interface InstalledPackage {
+    version: string;
+    namespace: string;
+    signature: string;
+    installedAt: string;
+}
+/**
+ * Información del lock file
+ */
+export interface LockInfo {
+    pid: number;
+    acquired: string;
+    command: string;
+}
+/**
+ * Opciones para adquirir lock
+ */
+export interface LockOptions {
+    timeout: number;
+    retryInterval: number;
+    stale: number;
+}
+/**
+ * Handle de un lock adquirido
+ */
+export interface LockHandle {
+    fd: number;
+    release: () => Promise<void>;
+}
+/**
+ * Resultado de resolución de un paquete
+ */
+export interface ResolutionResult {
+    package: string;
+    version: string;
+    found: boolean;
+    namespace?: string;
+    path?: string;
+    signature?: string;
+    searchedNamespaces: string[];
+}
+/**
+ * Contexto disponible para las factories
+ */
+export interface FactoryContext {
+    env: NodeJS.ProcessEnv;
+    args: string[];
+    cwd: string;
+    packages: Record<string, PackageVersions>;
+}
+/**
+ * Versiones por modo para un paquete
+ */
+export interface PackageVersions {
+    dev?: string;
+    prod?: string;
+}
+/**
+ * Información de un paquete resuelto para instalación
+ */
+export interface ResolvedPackage {
+    name: string;
+    version: string;
+    qname: string;
+    namespace?: string;
+    path?: string;
+    signature?: string;
+}
+/**
+ * Configuración de modo retornada por factory
+ */
+export interface ModeConfig {
+    manager: "store" | "npm";
+    namespaces?: string[];
+    args?: string[];
+    /** @deprecated Use namespaces instead */
+    storeFolder?: string;
+    beforeAll?: () => Promise<void> | void;
+    afterAll?: () => Promise<void> | void;
+    beforeEach?: (pkg: ResolvedPackage) => Promise<void> | void;
+    afterEach?: (pkg: ResolvedPackage) => Promise<void> | void;
+}
+/**
+ * Factory de modo
+ */
+export type ModeFactory = (ctx: FactoryContext) => ModeConfig;
+/**
+ * Configuración completa del archivo devlink.config.mjs
+ */
+export interface DevLinkConfig {
+    packages: Record<string, PackageVersions>;
+    dev: ModeFactory;
+    prod: ModeFactory;
+    detectMode?: (ctx: FactoryContext) => "dev" | "prod";
+}
+/**
+ * Manifest de un paquete (package.json)
+ */
+export interface PackageManifest {
+    name: string;
+    version: string;
+    private?: boolean;
+    files?: string[];
+    main?: string;
+    bin?: string | Record<string, string>;
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    scripts?: Record<string, string>;
+}
+/**
+ * Información de un paquete publicado
+ */
+export interface StoredPackage {
+    name: string;
+    version: string;
+    namespace: string;
+    signature: string;
+    path: string;
+    files: number;
+}
+/**
+ * Resultado de publicación
+ */
+export interface PublishResult {
+    name: string;
+    version: string;
+    namespace: string;
+    signature: string;
+    path: string;
+    files: number;
+}
+/**
+ * Resultado de push
+ */
+export interface PushResult extends PublishResult {
+    updatedProjects: string[];
+    skippedProjects: string[];
+}
+/**
+ * Entrada en el lockfile del proyecto
+ */
+export interface LockfileEntry {
+    version: string;
+    signature: string;
+    namespace?: string;
+}
+/**
+ * Lockfile de un proyecto cliente
+ */
+export interface Lockfile {
+    packages: Record<string, LockfileEntry>;
+}
+/**
+ * Argumentos parseados del CLI
+ */
+export interface ParsedArgs {
+    command: string;
+    positional: string[];
+    flags: {
+        namespace?: string;
+        namespaces?: string[];
+        packages?: string[];
+        flat?: boolean;
+        fix?: boolean;
+        dryRun?: boolean;
+        dev?: boolean;
+        prod?: boolean;
+        prune?: boolean;
+        all?: boolean;
+        help?: boolean;
+    };
+}
+/**
+ * Consumer info para comando consumers
+ */
+export interface ConsumerInfo {
+    projectPath: string;
+    registered: string;
+    packages: {
+        name: string;
+        version: string;
+        namespace: string;
+        signature: string;
+    }[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Types - Definiciones de tipos para DevLink
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/docs/README.md

@@ -0,0 +1,68 @@
+# DevLink Documentation
+
+Complete documentation for DevLink v2 - Local package development tool with namespaces.
+
+## Documentation Index
+
+### Getting Started
+- [Quick Start](../README.md) - Installation and basic usage
+- [Configuration](installation/configuration.md) - Project configuration with devlink.config.mjs
+
+### Store & Repository
+- [Store Structure](store/structure.md) - How the DevLink store is organized
+- [Namespaces](store/namespaces.md) - Isolated package contexts
+- [File Locking](store/locking.md) - Concurrency and serialization
+
+### Publishing Packages
+- [Publish Command](publishing/publish.md) - Publishing packages to the store
+- [Push Command](publishing/push.md) - Publishing and updating consumers
+
+### Installing Packages
+- [Install Command](installation/install.md) - Installing packages from the store
+- [Configuration](installation/configuration.md) - devlink.config.mjs reference
+
+### Inspecting the Store
+- [List Command](inspection/list.md) - Listing packages in the store
+- [Resolve Command](inspection/resolve.md) - Debugging package resolution
+- [Consumers Command](inspection/consumers.md) - Tracking consumer projects
+
+### Maintenance
+- [Remove Command](maintenance/remove.md) - Removing packages and namespaces
+- [Verify Command](maintenance/verify.md) - Verifying store integrity
+- [Prune Command](maintenance/prune.md) - Cleaning up orphaned packages
+
+### Technical Reference
+- [Design Document](DESIGN-namespaces.md) - Technical design and architecture
+- [Agent Guide](../AGENTS.md) - Comprehensive guide for AI agents
+
+## Quick Reference
+
+### Global Options
+
+All commands support these options:
+
+| Option | Description |
+|--------|-------------|
+| `--repo <path>` | Use custom repo path instead of `~/.devlink` |
+| `-h, --help` | Show help |
+| `-v, --version` | Show version |
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `DEVLINK_REPO` | Custom repo path (alternative to `--repo`) |
+
+### Commands Overview
+
+| Command | Description | Requires Lock |
+|---------|-------------|---------------|
+| `publish` | Publish package to store | ✓ |
+| `push` | Publish and update consumers | ✓ |
+| `install` | Install packages from store | ✓ |
+| `list` | List packages in store | ✗ |
+| `resolve` | Debug package resolution | ✗ |
+| `consumers` | List consumer projects | ✗ |
+| `remove` | Remove packages/namespaces | ✓ |
+| `verify` | Verify store integrity | ✗/✓ |
+| `prune` | Remove orphaned packages | ✓ |

package/docs/inspection/consumers.md

@@ -0,0 +1,178 @@
+# Consumers Command
+
+Lists projects that have installed packages from the DevLink store.
+
+## Usage
+
+```bash
+devlink consumers [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-p, --package <name>` | Filter by package name |
+| `-n, --namespace <name>` | Filter by namespace |
+| `--prune` | Remove projects that no longer exist |
+| `--flat` | Use flat output format |
+| `--repo <path>` | Use custom repo path |
+
+## Description
+
+The `consumers` command shows which projects have installed packages from the store. This information is tracked in `installations.json` and is used by the `push` command to update consumers.
+
+## Examples
+
+### List All Consumers
+
+```bash
+devlink consumers
+```
+
+Output:
+```
+📦 Consumer Projects
+
+/home/user/project-a
+├── @scope/core@1.0.0 (global)
+├── @scope/utils@1.0.0 (global)
+└── Registered: 2026-02-12T10:00:00Z
+
+/home/user/project-b
+├── @scope/core@1.0.0 (feature-v2)
+└── Registered: 2026-02-12T11:00:00Z
+
+Total: 2 projects, 3 installations
+```
+
+### Filter by Package
+
+```bash
+devlink consumers -p @scope/core
+```
+
+Shows only projects that have installed `@scope/core`.
+
+### Filter by Namespace
+
+```bash
+devlink consumers -n feature-v2
+```
+
+Shows only projects using packages from the `feature-v2` namespace.
+
+### Flat Output
+
+```bash
+devlink consumers --flat
+```
+
+Output:
+```
+/home/user/project-a  @scope/core@1.0.0      global
+/home/user/project-a  @scope/utils@1.0.0     global
+/home/user/project-b  @scope/core@1.0.0      feature-v2
+```
+
+### Prune Dead Projects
+
+Remove projects that no longer exist on disk:
+
+```bash
+devlink consumers --prune
+```
+
+Output:
+```
+🧹 Pruning dead projects...
+
+Removed: /home/user/deleted-project
+  - @scope/core@1.0.0 (global)
+
+Pruned 1 project(s)
+```
+
+## Consumer Tracking
+
+Projects become consumers when they run `devlink install`. The installation is recorded with:
+
+- Project path
+- Installed packages
+- Package versions
+- Source namespaces
+- Package signatures
+- Installation timestamp
+
+## Use Cases
+
+### Before Publishing Breaking Changes
+
+Check who would be affected:
+
+```bash
+devlink consumers -p @scope/core
+```
+
+### Verify Push Targets
+
+See which projects will be updated by `push`:
+
+```bash
+# Publish to feature-v2
+devlink publish -n feature-v2
+
+# Check who uses feature-v2
+devlink consumers -n feature-v2
+```
+
+### Clean Up Stale Data
+
+Remove references to deleted projects:
+
+```bash
+devlink consumers --prune
+```
+
+### Audit Package Usage
+
+See all projects using a specific package:
+
+```bash
+devlink consumers -p @scope/core --flat | wc -l
+```
+
+## Data Location
+
+Consumer data is stored in `~/.devlink/installations.json`:
+
+```json
+{
+  "version": "1.0.0",
+  "projects": {
+    "/home/user/project-a": {
+      "registered": "2026-02-12T10:00:00Z",
+      "packages": {
+        "@scope/core": {
+          "version": "1.0.0",
+          "namespace": "global",
+          "signature": "6761ca1f...",
+          "installedAt": "2026-02-12T10:05:00Z"
+        }
+      }
+    }
+  }
+}
+```
+
+## Notes
+
+- The `--prune` flag requires a lock (modifies `installations.json`)
+- Projects are automatically registered during `devlink install`
+- Projects are not automatically unregistered when deleted
+
+## See Also
+
+- [Push Command](../publishing/push.md) - How push uses consumer data
+- [Install Command](../installation/install.md) - How projects become consumers
+- [Store Structure](../store/structure.md) - Where consumer data is stored

package/docs/inspection/list.md

@@ -0,0 +1,182 @@
+# List Command
+
+Lists packages in the DevLink store.
+
+## Usage
+
+```bash
+devlink list [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-n, --namespaces <list>` | Filter by namespaces (comma-separated) |
+| `-p, --packages [list]` | Group by package, optionally filter |
+| `--flat` | Use flat output format (default: tree) |
+| `--repo <path>` | Use custom repo path |
+
+## Output Formats
+
+### Tree Format (Default)
+
+Hierarchical view with visual tree structure:
+
+```bash
+devlink list
+```
+
+```
+📦 DevLink Store
+
+global/
+├── @scope/
+│   ├── core/
+│   │   ├── 1.0.0  (6761ca1f)
+│   │   └── 2.0.0  (a1b2c3d4)
+│   └── utils/
+│       └── 1.0.0  (b2c3d4e5)
+└── simple-pkg/
+    └── 1.0.0  (c3d4e5f6)
+
+feature-v2/
+└── @scope/
+    └── core/
+        └── 1.0.0  (different1)
+```
+
+### Flat Format
+
+One line per package, suitable for scripting:
+
+```bash
+devlink list --flat
+```
+
+```
+global  @scope/core@1.0.0      6761ca1f
+global  @scope/core@2.0.0      a1b2c3d4
+global  @scope/utils@1.0.0     b2c3d4e5
+global  simple-pkg@1.0.0       c3d4e5f6
+feature-v2  @scope/core@1.0.0  different1
+```
+
+## Grouping
+
+### By Namespace (Default)
+
+Packages grouped under their namespace:
+
+```bash
+devlink list
+```
+
+### By Package
+
+Packages grouped by name, showing which namespaces contain them:
+
+```bash
+devlink list -p
+```
+
+```
+📦 DevLink Store (by package)
+
+@scope/
+├── core/
+│   ├── global/
+│   │   ├── 1.0.0  (6761ca1f)
+│   │   └── 2.0.0  (a1b2c3d4)
+│   └── feature-v2/
+│       └── 1.0.0  (different1)
+└── utils/
+    └── global/
+        └── 1.0.0  (b2c3d4e5)
+```
+
+## Filtering
+
+### Filter by Namespace
+
+```bash
+# Single namespace
+devlink list -n global
+
+# Multiple namespaces
+devlink list -n global,feature-v2
+```
+
+### Filter by Package
+
+```bash
+# Specific packages
+devlink list -p @scope/core,@scope/utils
+
+# By scope (all packages in scope)
+devlink list -p @scope
+```
+
+### Combined Filters
+
+```bash
+# Packages in specific namespace
+devlink list -n global -p @scope/core
+```
+
+## Examples
+
+### List Everything
+
+```bash
+devlink list
+```
+
+### List Only Global Namespace
+
+```bash
+devlink list -n global
+```
+
+### List Packages by a Scope
+
+```bash
+devlink list -p @myorg
+```
+
+### Flat Output for Scripting
+
+```bash
+# Count packages
+devlink list --flat | wc -l
+
+# Find specific package
+devlink list --flat | grep "@scope/core"
+
+# List all versions of a package
+devlink list --flat | grep "@scope/core@"
+```
+
+### Compare Namespaces
+
+```bash
+# See what's in feature branch vs global
+devlink list -n feature-v2
+devlink list -n global
+```
+
+## Empty Store
+
+If the store is empty or has no packages:
+
+```
+📦 DevLink Store
+
+└── global/
+```
+
+## See Also
+
+- [Resolve Command](resolve.md) - Debug package resolution
+- [Store Structure](../store/structure.md) - Understanding the store layout
+- [Namespaces](../store/namespaces.md) - Understanding namespaces