@vltpkg/vsr 0.0.0-26

package/DEPLOY.md

@@ -0,0 +1,163 @@
+# VSR Deploy Command
+
+The VSR CLI now includes a `deploy` subcommand that allows you to
+deploy your VSR instance to Cloudflare Workers using configuration
+from your `vlt.json` file.
+
+## Usage
+
+```bash
+# Deploy to default environment (dev)
+vsr deploy
+
+# Deploy to specific environment
+vsr deploy --env=prod
+
+# Preview deployment without actually deploying
+vsr deploy --dry-run
+
+# Override specific resource names
+vsr deploy --env=staging --db-name=my-custom-db --bucket-name=my-custom-bucket
+```
+
+## Configuration
+
+Add a `deploy` section to your `vlt.json` file under the `registry`
+key:
+
+```json
+{
+  "registry": {
+    "deploy": {
+      "sentry": {
+        "dsn": "https://your-default-sentry-dsn@sentry.io/project-id",
+        "sampleRate": 1.0,
+        "tracesSampleRate": 0.1
+      },
+      "environments": {
+        "dev": {
+          "databaseName": "vsr-dev-database",
+          "bucketName": "vsr-dev-bucket",
+          "queueName": "vsr-dev-cache-refresh-queue",
+          "sentry": {
+            "environment": "development"
+          },
+          "vars": {
+            "CUSTOM_VAR": "dev-value"
+          }
+        },
+        "prod": {
+          "databaseName": "vsr-prod-database",
+          "bucketName": "vsr-prod-bucket",
+          "queueName": "vsr-prod-cache-refresh-queue",
+          "sentry": {
+            "environment": "production",
+            "dsn": "https://your-prod-sentry-dsn@sentry.io/project-id",
+            "sampleRate": 0.1,
+            "tracesSampleRate": 0.01
+          },
+          "vars": {
+            "API_BASE_URL": "https://api.example.com"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Configuration Options
+
+### Global Deploy Settings
+
+- `sentry.dsn`: Default Sentry DSN for error reporting
+- `sentry.sampleRate`: Default error sample rate (0.0 to 1.0)
+- `sentry.tracesSampleRate`: Default performance traces sample rate
+  (0.0 to 1.0)
+
+### Environment-Specific Settings
+
+Each environment can override any global setting and specify:
+
+- `databaseName`: D1 database name for this environment
+- `bucketName`: R2 bucket name for this environment
+- `queueName`: Queue name for cache refresh operations
+- `sentry`: Environment-specific Sentry configuration
+- `vars`: Custom environment variables to pass to the Worker
+
+### CLI Options
+
+- `--env=<string>`: Environment to deploy to (defaults to "dev")
+- `--db-name=<string>`: Override D1 database name
+- `--bucket-name=<string>`: Override R2 bucket name
+- `--queue-name=<string>`: Override queue name
+- `--dry-run`: Show what would be deployed without actually deploying
+
+## Precedence
+
+Configuration values are resolved in the following order (highest
+precedence first):
+
+1. CLI arguments (`--db-name`, `--bucket-name`, etc.)
+2. Environment-specific config (`environments.prod.databaseName`)
+3. Default values
+
+## Examples
+
+### Basic Deployment
+
+```bash
+# Deploy to development environment
+vsr deploy --env=dev
+
+# Deploy to production
+vsr deploy --env=prod
+```
+
+### Custom Resource Names
+
+```bash
+# Override database and bucket names
+vsr deploy --env=staging --db-name=my-staging-db --bucket-name=my-staging-bucket
+```
+
+### Preview Deployment
+
+```bash
+# See what would be deployed without actually deploying
+vsr deploy --env=prod --dry-run
+```
+
+### Using Custom Config File
+
+```bash
+# Use a specific vlt.json file
+vsr deploy --config=/path/to/custom-vlt.json --env=prod
+```
+
+## Generated Wrangler Command
+
+The deploy command generates a `wrangler deploy` command with the
+appropriate bindings and variables. For example:
+
+```bash
+wrangler deploy dist/index.js \
+  --name vsr-prod \
+  --compatibility-date 2024-09-23 \
+  --var SENTRY_DSN:https://your-sentry-dsn@sentry.io/project-id \
+  --var SENTRY_ENVIRONMENT:production \
+  --var ARG_DEBUG:false \
+  --var ARG_TELEMETRY:true \
+  --var ARG_DAEMON:true \
+  --d1 DB=vsr-prod-database \
+  --r2 BUCKET=vsr-prod-bucket \
+  --queue-producer CACHE_REFRESH_QUEUE=vsr-prod-cache-refresh-queue \
+  --queue-consumer vsr-prod-cache-refresh-queue
+```
+
+## Prerequisites
+
+- Wrangler CLI must be installed and authenticated
+- Cloudflare Workers account with appropriate permissions
+- D1 databases, R2 buckets, and queues must exist (or be created by
+  Wrangler)

package/LICENSE

@@ -0,0 +1,119 @@
+# Functional Source License, Version 1.1, MIT Future License
+
+## Abbreviation
+
+FSL-1.1-MIT
+
+## Notice
+
+Copyright 2025 vlt technology Inc.
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available
+under these Terms and Conditions, as indicated by our inclusion of
+these Terms and Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the
+right to use, copy, modify, create derivative works, publicly perform,
+publicly display and redistribute the Software for any Permitted
+Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A
+Competing Use means making the Software available to others in a
+commercial product or service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the
+   Software that exists as of the date we make the Software available;
+   or
+
+3. offers the same or substantially similar functionality as the
+   Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a
+   licensee using the Software in accordance with these Terms and
+   Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily
+infringe our patents, the license grant above includes a license under
+our patents. If you make a claim against any party that the Software
+infringes or contributes to the infringement of any patent, then your
+patent license to the Software ends immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and
+derivatives of the Software.
+
+If you redistribute any copies, modifications or derivatives of the
+Software, you must include a copy of or a link to these Terms and
+Conditions and not remove any copyright notices provided in or with
+the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS
+FOR A PARTICULAR PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR
+RELATED TO THE SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR
+CONSEQUENTIAL DAMAGES, EVEN IF WE HAVE BEEN INFORMED OF THEIR
+POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the
+origin of the Software, you have no right under these Terms and
+Conditions to use our trademarks, trade names, service marks or
+product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the
+Software under the MIT license that is effective on the second
+anniversary of the date we make the Software available. On or after
+that date, you may use the Software under the MIT license, in which
+case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,314 @@
+# **vlt** serverless registry (`vsr`)
+
+> A modern, npm-compatible serverless registry that's fast, secure,
+> and ridiculously easy to deploy.
+
+`vsr` is a minimal yet powerful npm-compatible registry that
+replicates core npm features while adding cutting-edge capabilities.
+Built for the modern web, it runs seamlessly on Cloudflare's global
+edge network.
+
+<img src="https://github.com/user-attachments/assets/e76c6f8a-a078-4787-963c-8ec95a879731" alt="vsr api screenshot" />
+
+## 🚀 Quick Start
+
+### Local Development
+
+Get up and running in seconds:
+
+```bash
+# Try it locally
+npx @vltpkg/vsr
+
+# Or install globally
+npm install -g @vltpkg/vsr
+vsr
+```
+
+**Boom!** 💥 Your registry is live at `http://localhost:1337`
+
+### Deploy to Production
+
+Deploy to Cloudflare Workers with one command:
+
+```bash
+# Deploy to production
+vsr deploy --env=prod
+
+# Or preview what would be deployed
+vsr deploy --dry-run --env=prod
+```
+
+**That's it!** 🎉 Your registry is now running globally on
+Cloudflare's edge network.
+
+## ✨ Why Choose VSR?
+
+- **⚡ Blazing Fast**: Edge-optimized with global CDN distribution
+- **🔐 Secure by Default**: Package integrity validation and granular
+  access control
+- **💰 Cost Effective**: Generous free tier on Cloudflare (100k
+  requests/day)
+- **🛠 npm Compatible**: Drop-in replacement for existing workflows
+- **📦 Zero Config**: Works out of the box, configure when you need to
+- **🌍 Global Scale**: Deploy worldwide in under 5 minutes
+
+## 🎯 Perfect For
+
+- **Teams** who need private package management
+- **Organizations** requiring granular access control
+- **Developers** wanting fast, reliable package hosting
+- **Companies** needing npm-compatible enterprise solutions
+
+## 🏃‍♂️ Getting Started
+
+### Local Development
+
+```bash
+# Start with defaults (port 1337)
+vsr
+
+# Or explicitly use dev command
+vsr dev
+
+# Custom port
+vsr --port 3000
+
+# Enable debug mode
+vsr --debug
+
+# Use config file
+vsr --config ./vlt.json
+```
+
+### Production Deployment
+
+Deploy to Cloudflare Workers in under 5 minutes:
+
+#### Option 1: Using VSR Deploy Command (Recommended)
+
+```bash
+# Clone and setup
+git clone https://github.com/vltpkg/vsr.git
+cd vsr
+vlt install
+
+# Deploy to development environment
+vsr deploy
+
+# Deploy to production
+vsr deploy --env=prod
+
+# Preview deployment configuration
+vsr deploy --dry-run --env=prod
+```
+
+#### Option 2: Using Wrangler Directly
+
+```bash
+# Clone and setup
+git clone https://github.com/vltpkg/vsr.git
+cd vsr
+vlt install
+
+# Deploy to production
+wrangler deploy
+```
+
+The VSR deploy command offers better configuration management,
+environment-specific settings, and integration with your `vlt.json`
+configuration.
+
+**Coming Soon**: One-click Cloudflare deployment button! 🎉
+
+<img src="https://github.com/user-attachments/assets/528deda2-4c20-44c9-b057-f07c2e2e3c71" alt="Deploy to Cloudflare Workers" width="200" />
+
+## ⚙️ Configuration
+
+VSR is designed to work with zero configuration, but when you need
+more control:
+
+### Commands
+
+| Command  | Description                        |
+| -------- | ---------------------------------- |
+| `dev`    | Start development server (default) |
+| `deploy` | Deploy to Cloudflare Workers       |
+
+### CLI Options
+
+| Option     | Alias | Default | Description             |
+| ---------- | ----- | ------- | ----------------------- |
+| `--port`   | `-p`  | `1337`  | Server port             |
+| `--config` | `-c`  | -       | Config file path        |
+| `--debug`  | `-d`  | `false` | Debug mode              |
+| `--daemon` | -     | `true`  | Local filesystem daemon |
+| `--help`   | `-h`  | -       | Show help               |
+
+### Deploy Options
+
+| Option          | Default | Description                    |
+| --------------- | ------- | ------------------------------ |
+| `--env`         | `dev`   | Environment (dev/staging/prod) |
+| `--db-name`     | -       | Override D1 database name      |
+| `--bucket-name` | -       | Override R2 bucket name        |
+| `--queue-name`  | -       | Override queue name            |
+| `--dry-run`     | `false` | Preview deployment             |
+
+### Advanced Configuration
+
+Create a `vlt.json` file for shared configuration between VLT and VSR:
+
+```json
+{
+  "registry": {
+    "port": 4000,
+    "debug": true,
+    "telemetry": false,
+    "deploy": {
+      "sentry": {
+        "dsn": "https://your-sentry-dsn@sentry.io/project-id"
+      },
+      "environments": {
+        "prod": {
+          "databaseName": "vsr-prod-database",
+          "bucketName": "vsr-prod-bucket",
+          "queueName": "vsr-prod-cache-refresh-queue",
+          "sentry": {
+            "environment": "production"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+📚 **[Learn More About Configuration →](info/CONFIGURATION.md)**  
+🚀 **[Deployment Guide →](DEPLOY.md)**
+
+## 🌟 Key Features
+
+### Core Registry Features
+
+- ✅ **npm-compatible API** - Drop-in replacement
+- ✅ **Semver range resolution** - Smart version handling
+- ✅ **Scoped packages** - Full `@scope/package` support
+- ✅ **Dist-tag management** - Version tagging and lifecycle
+- ✅ **Search & discovery** - Find packages fast
+
+### Security & Access Control
+
+- 🔐 **[Granular access tokens](info/GRANULAR_ACCESS_TOKENS.md)** -
+  Fine-grained permissions
+- 🛡️ **Package integrity validation** - Tamper detection
+- 🔒 **Manifest confusion protection** - Security by design
+
+### Performance & Reliability
+
+- ⚡ **Edge-optimized responses** - Global performance
+- 📦 **Minimal JSON responses** - Faster installs
+- 🔄 **Background data refresh** - Always up-to-date
+- 🌐 **Upstream proxying** - Seamless package access
+
+### Developer Experience
+
+- 📖 **Interactive API docs** - Built-in Scalar documentation
+- 🛠️ **Rich CLI interface** - Powerful command-line tools
+- ⚙️ **Flexible configuration** - Adapt to your workflow
+
+## 📊 How It Compares
+
+VSR stands out in the registry landscape:
+
+- **vs npm**: Private, customizable, edge-deployed
+- **vs Verdaccio**: Serverless, zero-maintenance, global scale
+- **vs GitHub Packages**: More flexible, better performance
+- **vs Enterprise solutions**: Open source, cost-effective
+
+📈 **[See Detailed Comparisons →](info/COMPARISONS.md)**
+
+## 💻 Requirements
+
+### Production
+
+- **Cloudflare Account** (free tier available)
+  - Workers: 100k requests/day
+  - D1 Database: 5GB storage + 5M reads/day
+  - R2 Storage: 10GB + 10M reads/day
+
+### Development
+
+- Node.js (latest LTS)
+- VLT package manager
+- Git
+
+## 🔗 API Access
+
+Once running, access your registry:
+
+- **Registry API**: `http://localhost:1337`
+- **Interactive Docs**: `http://localhost:1337/-/docs`
+- **Filesystem Daemon**: `http://localhost:3000` (if enabled)
+
+The API includes complete npm compatibility plus enhanced features
+like URL-encoded semver ranges and optimized install responses.
+
+## 🛣️ What's Next?
+
+We're actively developing exciting features:
+
+- 🌐 **Web UI** for package management
+- 👥 **User management** with web authentication
+- 🏢 **Enterprise features** and integrations
+- 📊 **Analytics & insights** dashboard
+
+🗺️ **[View Full Roadmap →](info/ROADMAP.md)**
+
+## 🤝 Contributing
+
+We welcome contributions! VSR is built with modern tools and follows
+best practices:
+
+- **TypeScript** for type safety
+- **Comprehensive testing** with 100% coverage
+- **Clean architecture** with separated concerns
+- **Detailed documentation** and examples
+
+🔧 **[Contributing Guide →](info/CONTRIBUTING.md)**
+
+## 📚 Documentation
+
+- **[Configuration Guide](info/CONFIGURATION.md)** - Advanced setup
+  and options
+- **[Deployment Guide](DEPLOY.md)** - Deploy to Cloudflare Workers
+- **[Access Control](info/GRANULAR_ACCESS_TOKENS.md)** - Security and
+  permissions
+- **[Testing Guide](info/TESTING.md)** - Running and writing tests
+- **[Project Structure](info/PROJECT_STRUCTURE.md)** - Codebase
+  overview
+- **[Database Setup](info/DATABASE_SETUP.md)** - Storage configuration
+
+## 💬 Support
+
+Need help? We've got you covered:
+
+- 📖 **Documentation** - Comprehensive guides and examples
+- 🐛 **Issues** - Report bugs and request features
+- 💬 **Discussions** - Community support and questions
+
+🆘 **[Get Support →](info/USER_SUPPORT.md)**
+
+## 📄 License
+
+VSR is licensed under the
+**[Functional Source License](https://fsl.software)**
+([FSL-1.1-MIT](LICENSE.md)) - free for most use cases, with commercial
+restrictions that convert to MIT after two years.
+
+---
+
+**Ready to revolutionize your package management?** 🚀  
+[Get started](#-quick-start) •
+[Deploy to production](#production-deployment) •
+[Join the community](info/USER_SUPPORT.md)