@vltpkg/vsr 0.0.0-27 → 0.0.0-28

package/drizzle.config.js

@@ -0,0 +1,40 @@
+import { defineConfig } from 'drizzle-kit'
+import { join } from 'path'
+import { existsSync, readdirSync } from 'fs'
+
+// Find the actual SQLite database file in the miniflare-D1DatabaseObject directory
+const miniflareDir = join(
+  import.meta.dirname,
+  './local-store',
+  'v3',
+  'd1',
+  'miniflare-D1DatabaseObject',
+)
+
+if (!existsSync(miniflareDir)) {
+  throw new Error(
+    `Miniflare directory not found at ${miniflareDir}. Make sure to run \`pnpm run db:setup\` first.`,
+  )
+}
+// Look for the most recently modified SQLite file
+const file = readdirSync(miniflareDir, { withFileTypes: true })
+  .filter(file => file.isFile() && file.name.endsWith('.sqlite'))
+  .sort((a, b) => b.mtime.getTime() - a.mtime.getTime())
+  .map(file => join(file.parentPath, file.name))
+  .find(file => existsSync(file))
+
+if (!file) {
+  throw new Error(
+    `No SQLite file found in ${miniflareDir}. Make sure to run \`pnpm run db:setup\` first.`,
+  )
+}
+
+// For Drizzle Kit
+export default defineConfig({
+  schema: './src/db/schema.ts',
+  out: './src/db/migrations',
+  dialect: 'sqlite',
+  dbCredentials: {
+    url: file,
+  },
+})

package/info/COMPARISONS.md

@@ -0,0 +1,37 @@
+# Registry Comparisons
+
+| Feature                      |    **vsr**    |     **npm**     |   **GitHub**    | **Verdaccio** | **JSR** |    **jFrog**    |  **Sonatype**   | **Cloudsmith**  |  **Buildkite**  |     **Bit**     |
+| ---------------------------- | :-----------: | :-------------: | :-------------: | :-----------: | :-----: | :-------------: | :-------------: | :-------------: | :-------------: | :-------------: |
+| License                      | `FSL-1.1-MIT` | `Closed Source` | `Closed Source` |     `MIT`     |  `MIT`  | `Closed Source` | `Closed Source` | `Closed Source` | `Closed Source` | `Closed Source` |
+| Authored Language            | `JavaScript`  |  `JavaScript`   |   `Ruby`/`Go`   | `TypeScript`  | `Rust`  |       `-`       |       `-`       |       `-`       |       `-`       |       `-`       |
+| Publishing                   |      ✅       |       ✅        |       ✅        |      ✅       |   ✅    |       ✅        |       ✅        |       ✅        |       ✅        |       ✅        |
+| Installation                 |      ✅       |       ✅        |       ✅        |      ✅       |   ✴️    |       ✅        |       ✅        |       ✅        |       ✅        |       ✅        |
+| Search                       |      ✅       |       ✅        |       ✅        |      ✅       |   ✅    |       ✅        |       ✅        |       ✅        |       ✅        |       ✅        |
+| Scoped Packages              |      ✅       |       ✅        |       ✅        |      ✅       |   ✅    |       ✅        |       ✅        |       ✅        |       ✅        |       ✅        |
+| Unscoped Packages            |      ✅       |       ✅        |       ❌        |      ✅       |   ❌    |       ✅        |       ✅        |       ✅        |       ✅        |       ❌        |
+| Proxying Upstream Sources    |      ✅       |       ❌        |       ✴️        |      ✅       |   ❌    |       ✅        |       ✅        |       ✅        |       ✅        |       ❌        |
+| Hosted Instance              |      ✅       |       ✅        |       ✅        |      ❌       |   ❌    |       ✅        |       ✅        |       ✅        |       ✅        |       ✅        |
+| Hosted Instance Cost         |      `$`      |       `-`       |     `$$$$`      |      `-`      |   `-`   |     `$$$$`      |     `$$$$`      |     `$$$$`      |      `$$$`      |      `$$$`      |
+| Self-Hosted Instance         |      ✅       |       ❌        |       ✴️        |      ✅       |   ✅    |       ✅        |       ✅        |       ❌        |       ❌        |       ❌        |
+| Self-Hosted Instance Cost    |      🆓       |       `-`       |     `$$$$$`     |      `$`      |   `$`   |     `$$$$$`     |     `$$$$$`     |       `-`       |       `-`       |       `-`       |
+| Hosted Public Packages       |      ⏳       |       ✅        |       ❌        |      ❌       |   ✅    |       ❌        |       ❌        |       ❌        |       ❌        |       ✅        |
+| Hosted Private Packages      |      ⏳       |       ✅        |       ✅        |      ❌       |   ✅    |       ❌        |       ❌        |       ❌        |       ❌        |       ✅        |
+| Hosted Private Package Cost  |      `-`      |      `$$`       |       🆓        |      ❌       |   ❌    |       ❌        |       ❌        |       ❌        |       ❌        |       🆓        |
+| Granular Access/Permissions  |      ✅       |       ✴️        |       ❌        |      ✅       |   ❌    |       ✴️        |       ✴️        |       ✴️        |       ✴️        |       ❌        |
+| Manifest Validation          |      ✅       |       ✴️        |       ❌        |      ❌       |   ✴️    |       ✴️        |       ✴️        |       ❌        |       ❌        |       ❌        |
+| Audit                        |      🕤       |       ✴️        |       ❌        |      ✴️       |   ✴️    |       ✴️        |       ✴️        |       ✴️        |       ❌        |       ❌        |
+| Events/Hooks                 |      🕤       |       ❌        |       ✅        |      ❌       |   ❌    |       ✅        |       ✅        |       ✅        |       ❌        |       ❌        |
+| Plugins                      |      🕤       |       ❌        |       ❌        |      ✅       |   ❌    |       ✅        |       ✅        |       ✅        |       ❌        |       ❌        |
+| Multi-Cloud                  |      🕤       |       ❌        |       ❌        |      ✅       |   ✅    |       ❌        |       ❌        |       ❌        |       ❌        |       ❌        |
+| Documentation Generation     |      🕤       |       ❌        |       ❌        |      ❌       |   ✅    |       ❌        |       ❌        |       ❌        |       ❌        |       ✴️        |
+| Unpackaged Files/ESM Imports |      🕤       |       ❌        |       ❌        |      ❌       |   ✴️    |       ❌        |       ❌        |       ❌        |       ❌        |       ❌        |
+| Variant Support              |      🕤       |       ❌        |       ❌        |      ❌       |   ✴️    |       ❌        |       ❌        |       ❌        |       ❌        |       ❌        |
+
+#### Legend:
+
+- ✅ implemented
+- ✴️ supported with caveats
+- ⏳ in-progress
+- 🕤 planned
+- ❌ unsupported
+- `$` expense estimation (0-5)

package/info/CONFIGURATION.md

@@ -0,0 +1,143 @@
+# Configuration
+
+You can use `vsr` as a private local registry, a proxy registry, or
+both. If you want to publish into or consume from the local registry
+you can use `http://localhost:<port>`.
+
+To proxy requests to `npm` you can just add `npm` to the pathname (ex.
+`http://localhost:<port>/npm` will proxy all requests to `npmjs.org`)
+
+## CLI Configuration
+
+VSR supports both development and deployment commands with various
+configuration options:
+
+### Development Server (`vsr dev`)
+
+```bash
+# Start with defaults
+vsr dev
+
+# Custom configuration
+vsr dev --port 3000 --debug --config ./vlt.json
+```
+
+### Deployment (`vsr deploy`)
+
+```bash
+# Deploy to default environment (dev)
+vsr deploy
+
+# Deploy to specific environment
+vsr deploy --env=prod
+
+# Override resource names
+vsr deploy --env=staging --db-name=custom-db --bucket-name=custom-bucket
+
+# Preview deployment
+vsr deploy --dry-run --env=prod
+```
+
+## Configuration File (`vlt.json`)
+
+VSR can be configured using a `vlt.json` file that supports both
+development and deployment settings:
+
+### Development Configuration
+
+```json
+{
+  "registry": {
+    "port": 4000,
+    "debug": true,
+    "telemetry": false,
+    "daemon": true
+  }
+}
+```
+
+### Deployment Configuration
+
+```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"
+          }
+        },
+        "staging": {
+          "databaseName": "vsr-staging-database",
+          "bucketName": "vsr-staging-bucket",
+          "queueName": "vsr-staging-cache-refresh-queue",
+          "sentry": {
+            "environment": "staging"
+          }
+        },
+        "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"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+See the [Deployment Guide](../DEPLOY.md) for complete deployment
+configuration documentation.
+
+## Package Manager Integration
+
+##### For `vlt`:
+
+In your project or user-level `vlt.json` file add the relevant
+configuration.
+
+```json
+{
+  "registries": {
+    "npm": "http://localhost:1337/npm",
+    "local": "http://localhost:1337"
+  }
+}
+```
+
+##### For `npm`, `pnpm`, `yarn` & `bun`:
+
+To use `vsr` as your registry you must either pass a registry config
+through a client-specific flag (ex. `--registry=...` for `npm`) or
+define client-specific configuration which stores the reference to
+your registry (ex. `.npmrc` for `npm`). Access to the registry &
+packages is private by default although an `"admin"` user is created
+during setup locally (for development purposes) with a default auth
+token of `"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"`.
+
+```ini
+; .npmrc
+registry=http://localhost:1337
+//localhost:1337/:_authToken=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+```

package/info/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# VSR Contributing Docs
+
+### Getting Started
+
+#### Installing
+
+- `pnpm install`
+
+#### Building
+
+- `pnpm build` - will build all parts of the project
+- `pnpm build:dist` - will build dist directories
+- `pnpm build:assets` - will build & move static assets
+- `pnpm build:bin` - will build the bin script
+- `pnpm build:worker` - will build the worker
+
+#### Database Operations
+
+- `pnpm db:setup`
+- `pnpm db:drop`
+- `pnpm db:studio`
+- `pnpm db:generate`
+- `pnpm db:migrate`
+- `pnpm db:push`
+
+#### Serving
+
+- `pnpm serve:build` - will build & start the services
+- `pnpm serve:death` - will kill any hanging `wrangler` processes
+  (which can happen if you're developing with agents a lot)
+- Post-build you can also directly link/run the bin from
+  `./dist/bin/vsr.js`

package/info/DATABASE_SETUP.md

@@ -0,0 +1,108 @@
+# VSR Database Setup Guide
+
+This guide explains how to set up the local database for the vlt
+serverless registry.
+
+## Quick Setup
+
+For a fresh installation, run:
+
+```bash
+pnpm run db:setup
+```
+
+This command will:
+
+1. Create the initial database tables (`packages`, `tokens`,
+   `versions`)
+2. Apply all necessary schema migrations
+3. Insert a default admin token
+
+## Manual Setup
+
+If you need to set up the database manually:
+
+```bash
+# Create initial tables
+pnpm exec wrangler d1 execute vsr-local-database --file=src/db/migrations/0000_initial.sql --local --persist-to=local-store --no-remote
+
+# Apply schema updates (adds columns: last_updated, origin, upstream, cached_at)
+pnpm exec wrangler d1 execute vsr-local-database --file=src/db/migrations/0001_wealthy_magdalene.sql --local --persist-to=local-store --no-remote
+```
+
+## Database Schema
+
+The database includes three main tables:
+
+### `packages`
+
+- `name` (TEXT, PRIMARY KEY) - Package name (e.g., "lodash",
+  "@types/node")
+- `tags` (TEXT) - JSON string of dist-tags (e.g.,
+  `{"latest": "1.0.0"}`)
+- `last_updated` (TEXT) - ISO timestamp of last update
+- `origin` (TEXT) - Either "local" or "upstream"
+- `upstream` (TEXT) - Name of upstream registry (for cached packages)
+- `cached_at` (TEXT) - ISO timestamp when cached from upstream
+
+### `tokens`
+
+- `token` (TEXT, PRIMARY KEY) - Authentication token
+- `uuid` (TEXT) - User identifier
+- `scope` (TEXT) - JSON string of token permissions
+
+### `versions`
+
+- `spec` (TEXT, PRIMARY KEY) - Package version spec (e.g.,
+  "lodash@4.17.21")
+- `manifest` (TEXT) - JSON string of package.json manifest
+- `published_at` (TEXT) - ISO timestamp when version was published
+- `origin` (TEXT) - Either "local" or "upstream"
+- `upstream` (TEXT) - Name of upstream registry (for cached versions)
+- `cached_at` (TEXT) - ISO timestamp when cached from upstream
+
+## Common Issues
+
+### "no such table: packages"
+
+This error means the database hasn't been initialized. Run:
+
+```bash
+pnpm run db:setup
+```
+
+### "table packages has no column named last_updated"
+
+This means the initial migration ran but the schema update didn't.
+Run:
+
+```bash
+pnpm exec wrangler d1 execute vsr-local-database --file=src/db/migrations/0001_wealthy_magdalene.sql --local --persist-to=local-store --no-remote
+```
+
+### Reset Database
+
+To completely reset the database:
+
+```bash
+pnpm run db:drop
+pnpm run db:setup
+```
+
+## Database Location
+
+The local database is stored in:
+
+```
+./local-store/v3/d1/miniflare-D1DatabaseObject/
+```
+
+## Default Admin Token
+
+The setup creates a default admin token:
+
+- **Token**: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
+- **UUID**: `admin`
+- **Permissions**: Full read/write access to all packages and users
+
+⚠️ **Security Note**: Change this token in production environments!

package/info/GRANULAR_ACCESS_TOKENS.md

@@ -0,0 +1,160 @@
+# Granular Access Tokens
+
+All tokens are considered "granular access tokens" (GATs). Token
+entries in the database consist of 3 parts:
+
+- `token` the unique token value
+- `uuid` associative value representing a single user/scope
+- `scope` value representing the granular access/privileges
+
+#### `scope` as a JSON `Object`
+
+A `scope` contains an array of privileges that define both the type(s)
+of & access value(s) for a token.
+
+> [!NOTE] Tokens can be associated with multiple "types" of access
+
+- `type(s)`:
+  - `pkg:read` read associated packages
+  - `pkg:read+write` write associated packages (requires read access)
+  - `user:read` read associated user
+  - `user:read+write` write associated user (requires read access)
+- `value(s)`:
+  - `*` an ANY selector for `user:` or `pkg:` access types
+  - `~<user>` user selector for the `user:` access type
+  - `@<scope>/<pkg>` package specific selector for the `pkg:` access
+    type
+  - `@<scope>/*` glob scope selector for `pkg:` access types
+
+> [!NOTE]
+>
+> - user/org/team management via `@<scope>` is not supported at the
+>   moment
+
+### Granular Access Examples
+
+##### End-user/Subscriber Persona
+
+- specific package read access
+- individual user read+write access
+
+```json
+[
+  {
+    "values": ["@organization/package-name"],
+    "types": {
+      "pkg": {
+        "read": true
+      }
+    }
+  },
+  {
+    "values": ["~johnsmith"],
+    "types": {
+      "user": {
+        "read": true,
+        "write": true
+      }
+    }
+  }
+]
+```
+
+##### Team Member/Maintainer Persona
+
+- scoped package read+write access
+- individual user read+write access
+
+```json
+[
+  {
+    "values": ["@organization/*"],
+    "types": {
+      "pkg": {
+        "read": true
+      }
+    }
+  },
+  {
+    "values": ["~johnsmith"],
+    "types": {
+      "user": {
+        "read": true,
+        "write": true
+      }
+    }
+  }
+]
+```
+
+##### Package Publish CI Persona
+
+- organization scoped packages read+write access
+- individual user read+write access
+
+```json
+[
+  {
+    "values": ["@organization/package-name"],
+    "types": {
+      "pkg": {
+        "read": true
+      }
+    }
+  },
+  {
+    "values": ["~johnsmith"],
+    "types": {
+      "user": {
+        "read": true,
+        "write": true
+      }
+    }
+  }
+]
+```
+
+##### Organization Admin Persona
+
+- organization scoped package read+write access
+- organization users read+write access
+
+```json
+[
+  {
+    "values": ["@company/*"],
+    "types": {
+      "pkg": {
+        "read": true,
+        "write": true
+      },
+      "user": {
+        "read": true,
+        "write": true
+      }
+    }
+  }
+]
+```
+
+##### Registry Owner/Admin Persona
+
+```json
+[
+  {
+    "values": ["*"],
+    "types": {
+      "pkg": {
+        "read": true,
+        "write": true
+      },
+      {
+        "user": {
+          "read": true,
+          "write": true
+        }
+      }
+    }
+  }
+]
+```