@vltpkg/vsr 0.0.0-26

package/config.ts

@@ -0,0 +1,221 @@
+// get openapi schema
+import wranglerJson from './wrangler.json' with { type: 'json' }
+import packageJson from './package.json' with { type: 'json' }
+import { apiBody } from './src/utils/docs.ts'
+import type {
+  OriginConfig,
+  CookieOptions,
+  ApiDocsConfig,
+} from './types.ts'
+
+export const YEAR = new Date().getFullYear()
+
+export const WRANGLER_CONFIG = wranglerJson.dev
+
+export const PORT = WRANGLER_CONFIG.port || (1337 as number)
+
+export const TELEMETRY_ENABLED = true as boolean
+
+export const HELP_ENABLED = false as boolean
+
+// Sentry configuration for error reporting (when telemetry is enabled)
+export const SENTRY_CONFIG = {
+  dsn: 'https://909b085eb764c00250ad312660c2fdf1@o4506397716054016.ingest.us.sentry.io/4509492612300800',
+  sendDefaultPii: true,
+  environment: 'development', // Will be overridden by environment variable
+  sampleRate: 1.0,
+  tracesSampleRate: 0.1, // Lower sample rate for performance traces
+}
+
+export const DEBUG_ENABLED = false as boolean
+
+export const API_DOCS_ENABLED = true as boolean
+
+export const DAEMON_ENABLED = true as boolean
+
+export const DAEMON_PORT = 3000 as number
+
+// Runtime configuration is now handled by configMiddleware
+// which enriches c.env with computed values like DAEMON_ENABLED, TELEMETRY_ENABLED, etc.
+
+export const DAEMON_URL = `http://localhost:${DAEMON_PORT}`
+
+export const VERSION: string = packageJson.version
+
+export const URL = `http://localhost:${PORT}`
+
+export const REDIRECT_URI = `${URL}/-/auth/callback`
+
+// how to handle packages requests
+export const ORIGIN_CONFIG: OriginConfig = {
+  default: 'local',
+  upstreams: {
+    local: {
+      type: 'local',
+      url: URL,
+      allowPublish: true,
+    },
+    npm: {
+      type: 'npm',
+      url: 'https://registry.npmjs.org',
+    },
+  },
+}
+
+// Reserved route prefixes that cannot be used as upstream names
+export const RESERVED_ROUTES: string[] = [
+  '-',
+  'user',
+  'docs',
+  'search',
+  'tokens',
+  'auth',
+  'ping',
+  'package',
+  'v1',
+  'api',
+  'admin',
+  '*', // Reserved for hash-based routes
+]
+
+// Backward compatibility - maintain old PROXY behavior
+export const PROXY: boolean =
+  Object.keys(ORIGIN_CONFIG.upstreams).length > 1
+
+export const PROXY_URL: string | undefined =
+  ORIGIN_CONFIG.upstreams[ORIGIN_CONFIG.default]?.url
+
+// the time in seconds to cache the registry
+export const REQUEST_TIMEOUT: number = 60 * 1000
+
+// cookie options
+export const COOKIE_OPTIONS: CookieOptions = {
+  path: '/',
+  httpOnly: true,
+  secure: true,
+  sameSite: 'strict',
+}
+
+// OpenAPI Docs
+export const OPEN_API_CONFIG = {
+  openapi: '3.1.0',
+  info: {
+    title: 'vlt serverless registry',
+    version: VERSION,
+    description: 'The vlt serverless registry API',
+  },
+  tags: [
+    {
+      name: 'Health Check',
+      description: 'Registry health and status endpoints',
+    },
+    {
+      name: 'Authentication',
+      description: 'User authentication and token management',
+    },
+    {
+      name: 'Packages',
+      description: 'Package publishing, downloading, and management',
+    },
+    {
+      name: 'Dist-Tags',
+      description: 'Package version tagging and lifecycle management',
+    },
+    {
+      name: 'Access Control',
+      description:
+        'Package access permissions and collaborator management',
+    },
+    {
+      name: 'Search',
+      description: 'Package discovery and search functionality',
+    },
+    {
+      name: 'Security',
+      description: 'Security auditing and vulnerability scanning',
+    },
+    {
+      name: 'Dashboard',
+      description: 'Registry dashboard and administration',
+    },
+    {
+      name: 'Static Assets',
+      description: 'Static file serving and web assets',
+    },
+    {
+      name: 'NPM Compatibility',
+      description: 'Legacy npm client compatibility redirects',
+    },
+  ],
+}
+
+// the docs configuration for the API reference
+export const SCALAR_API_CONFIG: ApiDocsConfig = {
+  metaData: {
+    title: 'vlt serverless registry',
+  },
+  hideModels: false,
+  hideDownloadButton: false,
+  darkMode: false,
+  favicon: '/public/images/favicon/favicon.svg',
+  defaultHttpClient: {
+    targetKey: 'curl',
+    clientKey: 'fetch',
+  },
+  authentication: {
+    http: {
+      bearer: {
+        token: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
+      },
+      basic: {
+        username: 'user',
+        password: 'pass',
+      },
+    },
+  },
+  hiddenClients: {
+    python: true,
+    c: true,
+    go: true,
+    java: true,
+    ruby: true,
+    shell: ['httpie', 'wget', 'fetch'],
+    clojure: true,
+    csharp: true,
+    kotlin: true,
+    objc: true,
+    swift: true,
+    r: true,
+    powershell: false,
+    ocaml: true,
+    curl: false,
+    http: true,
+    php: true,
+    node: ['request', 'unirest'],
+    javascript: ['xhr', 'jquery'],
+  },
+  spec: {
+    content: {
+      openapi: OPEN_API_CONFIG.openapi,
+      servers: [
+        {
+          url: URL,
+          description: 'localhost',
+        },
+      ],
+      info: {
+        title: 'vlt serverless registry',
+        version: VERSION,
+        license: {
+          identifier: 'FSL-1.1-MIT',
+          name: 'Functional Source License, Version 1.1, MIT Future License',
+          url: 'https://fsl.software/FSL-1.1-MIT.template.md',
+        },
+        description: apiBody({ YEAR }),
+      },
+      // Include tag ordering and descriptions
+      tags: OPEN_API_CONFIG.tags,
+    },
+  },
+  customCss: `@import '${URL}/public/styles/styles.css';`,
+}

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!