@unlimitechcloud/devlink 1.0.2

package/docs/inspection/resolve.md

@@ -0,0 +1,172 @@
+# Resolve Command
+
+Debug package resolution by showing where packages would be found.
+
+## Usage
+
+```bash
+devlink resolve <pkg@version> [...] [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `<pkg@version>` | Package spec(s) to resolve |
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-n, --namespaces <list>` | Namespace precedence (comma-separated) |
+| `--flat` | Use flat output format |
+| `--repo <path>` | Use custom repo path |
+
+## Description
+
+The `resolve` command shows:
+
+- Which namespace a package would be resolved from
+- The full path to the package
+- The package signature
+- Which namespaces were searched
+
+This is useful for debugging resolution issues before running `install`.
+
+## Examples
+
+### Resolve Single Package
+
+```bash
+devlink resolve @scope/core@1.0.0
+```
+
+Output:
+```
+Resolving with precedence: global
+
+@scope/core@1.0.0
+  ✓ Found in: global
+  Path: ~/.devlink/namespaces/global/@scope/core/1.0.0
+  Signature: 6761ca1fefdde1b6e9ea372e7d6931e4
+
+Summary: 1/1 resolved
+```
+
+### Resolve with Namespace Precedence
+
+```bash
+devlink resolve @scope/core@1.0.0 -n feature-v2,global
+```
+
+Output:
+```
+Resolving with precedence: feature-v2 → global
+
+@scope/core@1.0.0
+  ✓ Found in: feature-v2
+  Path: ~/.devlink/namespaces/feature-v2/@scope/core/1.0.0
+  Signature: different123456
+
+Summary: 1/1 resolved
+```
+
+### Resolve Multiple Packages
+
+```bash
+devlink resolve @scope/core@1.0.0 @scope/utils@2.0.0 -n feature-v2,global
+```
+
+Output:
+```
+Resolving with precedence: feature-v2 → global
+
+@scope/core@1.0.0
+  ✓ Found in: feature-v2
+  Path: ~/.devlink/namespaces/feature-v2/@scope/core/1.0.0
+  Signature: abc123
+
+@scope/utils@2.0.0
+  ⊘ Not in: feature-v2
+  ✓ Found in: global
+  Path: ~/.devlink/namespaces/global/@scope/utils/2.0.0
+  Signature: def456
+
+Summary: 2/2 resolved
+```
+
+### Package Not Found
+
+```bash
+devlink resolve @scope/missing@1.0.0 -n feature-v2,global
+```
+
+Output:
+```
+Resolving with precedence: feature-v2 → global
+
+@scope/missing@1.0.0
+  ⊘ Not in: feature-v2
+  ⊘ Not in: global
+  ✗ Not found in any namespace
+
+Summary: 0/1 resolved
+```
+
+### Flat Output
+
+```bash
+devlink resolve @scope/core@1.0.0 @scope/utils@2.0.0 --flat
+```
+
+Output:
+```
+✓ @scope/core@1.0.0        global     6761ca1f
+✓ @scope/utils@2.0.0       global     a1b2c3d4
+```
+
+## Use Cases
+
+### Debug Installation Issues
+
+Before running `install`, verify packages can be resolved:
+
+```bash
+# Check all packages from your config
+devlink resolve @scope/core@1.0.0 @scope/utils@1.0.0 -n feature-v2,global
+```
+
+### Verify Namespace Precedence
+
+Check which namespace would be used:
+
+```bash
+# Same package in multiple namespaces
+devlink resolve @scope/core@1.0.0 -n feature-v2,global
+# Shows: Found in feature-v2
+
+devlink resolve @scope/core@1.0.0 -n global,feature-v2
+# Shows: Found in global (different precedence)
+```
+
+### Check Package Availability
+
+Verify a package was published correctly:
+
+```bash
+devlink resolve @scope/new-pkg@1.0.0
+```
+
+## Resolution Algorithm
+
+1. Parse package spec (`name@version`)
+2. For each namespace in order:
+   - Check if `namespace/name/version` exists in registry
+   - If found, return path and signature
+3. If not found in any namespace, report as not found
+
+## See Also
+
+- [List Command](list.md) - See all packages in the store
+- [Namespaces](../store/namespaces.md) - Understanding namespace precedence
+- [Install Command](../installation/install.md) - How resolution is used during install

package/docs/installation/configuration.md

@@ -0,0 +1,238 @@
+# Configuration
+
+DevLink uses a configuration file to define which packages to manage and how to resolve them.
+
+## Config File
+
+Create `devlink.config.mjs` in your project root:
+
+```javascript
+export default {
+  packages: { /* ... */ },
+  dev: () => ({ /* ... */ }),
+  prod: () => ({ /* ... */ }),
+  detectMode: (ctx) => { /* ... */ },
+};
+```
+
+### Supported File Names
+
+In order of priority:
+1. `devlink.config.mjs`
+2. `devlink.config.js`
+3. `devlink.config.cjs`
+
+## Configuration Options
+
+### packages
+
+Defines which packages to manage and their versions per mode.
+
+```javascript
+packages: {
+  "@scope/core": { dev: "1.0.0", prod: "1.0.0" },
+  "@scope/utils": { dev: "2.0.0", prod: "1.5.0" },
+  "simple-pkg": { dev: "1.0.0" },  // prod defaults to dev version
+}
+```
+
+### dev
+
+Configuration for development mode.
+
+```javascript
+dev: (ctx) => ({
+  manager: "store",           // Use DevLink store
+  namespaces: ["feature", "global"],  // Namespace precedence
+})
+```
+
+### prod
+
+Configuration for production mode.
+
+```javascript
+prod: (ctx) => ({
+  manager: "npm",             // Use npm
+  args: ["--no-save"],        // Additional npm arguments
+})
+```
+
+### detectMode
+
+Function to determine which mode to use.
+
+```javascript
+detectMode: (ctx) => {
+  // ctx.env - Environment variables
+  // ctx.args - Command line arguments
+  // ctx.cwd - Current working directory
+  
+  if (ctx.env.NODE_ENV === "development") return "dev";
+  if (ctx.env.SST_LOCAL === "true") return "dev";
+  if (ctx.args.includes("--dev")) return "dev";
+  return "prod";
+}
+```
+
+## Context Object
+
+The `ctx` object passed to functions contains:
+
+```typescript
+interface Context {
+  env: Record<string, string>;  // process.env
+  args: string[];               // Command line arguments
+  cwd: string;                  // Current working directory
+}
+```
+
+## Manager Types
+
+### store
+
+Uses the DevLink store to resolve packages:
+
+```javascript
+{
+  manager: "store",
+  namespaces: ["feature-v2", "global"],
+}
+```
+
+### npm
+
+Uses npm to install packages:
+
+```javascript
+{
+  manager: "npm",
+  args: ["--no-save", "--legacy-peer-deps"],
+}
+```
+
+## Complete Example
+
+```javascript
+import { fileURLToPath } from "url";
+import { dirname } from "path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export default {
+  // Packages to manage
+  packages: {
+    "@myorg/core": { dev: "1.0.0", prod: "1.0.0" },
+    "@myorg/utils": { dev: "1.0.0", prod: "1.0.0" },
+    "@myorg/http": { dev: "1.0.0", prod: "1.0.0" },
+  },
+
+  // Development mode: use local store
+  dev: (ctx) => ({
+    manager: "store",
+    namespaces: getNamespaces(ctx),
+  }),
+
+  // Production mode: use npm
+  prod: (ctx) => ({
+    manager: "npm",
+    args: ["--no-save"],
+  }),
+
+  // Mode detection
+  detectMode: (ctx) => {
+    // SST local development
+    if (ctx.env.SST_LOCAL === "true") return "dev";
+    
+    // Explicit flags
+    if (ctx.args.includes("--dev")) return "dev";
+    if (ctx.args.includes("--prod")) return "prod";
+    
+    // Environment variable
+    if (ctx.env.NODE_ENV === "development") return "dev";
+    
+    return "prod";
+  },
+};
+
+// Helper to determine namespaces based on context
+function getNamespaces(ctx) {
+  // Use feature namespace if specified
+  if (ctx.env.DEVLINK_NAMESPACE) {
+    return [ctx.env.DEVLINK_NAMESPACE, "global"];
+  }
+  
+  // Default to global only
+  return ["global"];
+}
+```
+
+## Namespace Override
+
+The `-n` flag overrides configured namespaces:
+
+```bash
+# Uses namespaces from config
+devlink install
+
+# Overrides to use feature-v2 first
+devlink install -n feature-v2,global
+```
+
+## Mode Override
+
+The `--dev` and `--prod` flags override mode detection:
+
+```bash
+# Uses detectMode function
+devlink install
+
+# Forces dev mode
+devlink install --dev
+
+# Forces prod mode
+devlink install --prod
+```
+
+## Tips
+
+### Dynamic Namespaces
+
+Use environment variables for flexible namespace configuration:
+
+```javascript
+dev: (ctx) => ({
+  manager: "store",
+  namespaces: ctx.env.FEATURE_BRANCH 
+    ? [ctx.env.FEATURE_BRANCH, "global"]
+    : ["global"],
+})
+```
+
+### Version Pinning
+
+Pin exact versions for reproducibility:
+
+```javascript
+packages: {
+  "@scope/core": { dev: "1.2.3", prod: "1.2.3" },
+}
+```
+
+### Different Dev/Prod Versions
+
+Use different versions for development and production:
+
+```javascript
+packages: {
+  "@scope/core": { 
+    dev: "2.0.0-beta.1",  // Latest beta for development
+    prod: "1.5.0",         // Stable for production
+  },
+}
+```
+
+## See Also
+
+- [Install Command](install.md) - Using the configuration
+- [Namespaces](../store/namespaces.md) - Understanding namespace precedence

package/docs/installation/install.md

@@ -0,0 +1,184 @@
+# Install Command
+
+Installs packages from the DevLink store into a project.
+
+## Usage
+
+```bash
+devlink install [options]
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `-n, --namespaces <list>` | Override namespace precedence (comma-separated) |
+| `-c, --config <path>` | Path to config file |
+| `--dev` | Force dev mode |
+| `--prod` | Force prod mode |
+| `--repo <path>` | Use custom repo path |
+
+## Description
+
+The `install` command:
+
+1. Reads `devlink.config.mjs` from the project
+2. Determines the mode (dev or prod)
+3. Resolves packages using namespace precedence
+4. Creates symlinks in `node_modules`
+5. Registers the project as a consumer
+6. Creates/updates `devlink.lock`
+
+## Configuration File
+
+Create `devlink.config.mjs` in your project root:
+
+```javascript
+export default {
+  packages: {
+    "@scope/core": { dev: "1.0.0", prod: "1.0.0" },
+    "@scope/utils": { dev: "2.0.0", prod: "1.5.0" },
+  },
+
+  dev: () => ({
+    manager: "store",
+    namespaces: ["feature-v2", "global"],
+  }),
+
+  prod: () => ({
+    manager: "npm",
+    args: ["--no-save"],
+  }),
+
+  detectMode: (ctx) => {
+    if (ctx.env.NODE_ENV === "development") return "dev";
+    if (ctx.args.includes("--dev")) return "dev";
+    return "prod";
+  },
+};
+```
+
+See [Configuration](configuration.md) for full reference.
+
+## Examples
+
+### Basic Install
+
+```bash
+cd my-project
+devlink install
+```
+
+### Force Dev Mode
+
+```bash
+devlink install --dev
+```
+
+### Override Namespaces
+
+```bash
+devlink install -n feature-v2,global
+```
+
+### Custom Config Path
+
+```bash
+devlink install -c ./config/devlink.config.mjs
+```
+
+## Resolution Process
+
+For each package in the config:
+
+1. Get version for current mode (dev/prod)
+2. Search namespaces in order
+3. Find first match
+4. Create symlink to store location
+
+Example:
+```
+Config: @scope/core@1.0.0
+Namespaces: ["feature-v2", "global"]
+
+1. Search feature-v2/@scope/core/1.0.0 → Not found
+2. Search global/@scope/core/1.0.0 → Found!
+3. Symlink: node_modules/@scope/core → ~/.devlink/namespaces/global/@scope/core/1.0.0
+```
+
+## Lock File
+
+After installation, `devlink.lock` is created/updated:
+
+```json
+{
+  "packages": {
+    "@scope/core": {
+      "version": "1.0.0",
+      "namespace": "global",
+      "signature": "6761ca1f...",
+      "resolved": "~/.devlink/namespaces/global/@scope/core/1.0.0"
+    }
+  }
+}
+```
+
+This file:
+- Records exact resolution for reproducibility
+- Tracks signatures for change detection
+- Should be committed to version control
+
+## Consumer Registration
+
+Installing registers your project in `installations.json`, enabling:
+
+- `devlink push` to update your project
+- `devlink consumers` to list your project
+
+## Modes
+
+### Dev Mode
+
+Uses packages from the DevLink store:
+
+```javascript
+dev: () => ({
+  manager: "store",
+  namespaces: ["feature-v2", "global"],
+})
+```
+
+### Prod Mode
+
+Uses npm to install packages:
+
+```javascript
+prod: () => ({
+  manager: "npm",
+  args: ["--no-save"],
+})
+```
+
+## Errors
+
+### Package Not Found
+
+```
+Error: @scope/core@1.0.0 not found in namespaces: feature-v2, global
+```
+
+The package hasn't been published to any of the configured namespaces.
+
+### Config Not Found
+
+```
+Error: devlink.config.mjs not found
+```
+
+Create a configuration file in your project root.
+
+## See Also
+
+- [Configuration](configuration.md) - Full config file reference
+- [Namespaces](../store/namespaces.md) - Understanding namespace precedence
+- [Push Command](../publishing/push.md) - How push updates consumers