# pkgdrop

A private npm-style package registry with:

- a web UI for browsing/publishing metadata
- a CLI (`pkgdrop`) for auth, publish, install, search, and delete flows
- a Node-deployable server build via TanStack Start + Nitro

## Overview

This project lets you publish tarballs to a local/private registry namespace and consume them with standard package managers.

High-level stack:

- **Frontend/SSR**: TanStack Start (React, TanStack Router, TanStack Query)
- **API/runtime**: Hono app mounted with TanStack Start server handler
- **Build/deploy**: Vite + Nitro (`node-server` preset)
- **Data**: Drizzle ORM with SQLite/libSQL

## Core Features

- Registry endpoints for package metadata + tarballs
- Dist-tags and versioned tarball redirects
- Upload validation (size limits, uploader whitelist)
- Browser UI for package browsing and package detail pages
- CLI flows:
  - `login`, `logout`, `browser-login`, `mock-login`
  - `publish` (single package or glob)
  - `install` (version/tag aware)
  - `search`
  - `remove`

## Quick Start

```bash
pnpm install
pnpm db:push
pnpm dev
```

Open the app at `http://localhost:5173`.

## Scripts

- `pnpm dev` - start development server
- `pnpm build` - production build
- `pnpm start` - run Node server from `.output/server/index.mjs`
- `pnpm typecheck` - run TypeScript checks
- `pnpm lint` - run oxlint
- `pnpm format` - run oxfmt
- `pnpm test` - run Vitest test suite
- `pnpm cli -- <args>` - run CLI from source
- `pnpm db:push` - apply schema to database
- `pnpm db:studio` - open Drizzle Studio

## CLI Usage

When installed globally/in PATH, use `pkgdrop`.

Common commands:

- `pkgdrop login`
- `pkgdrop publish .`
- `pkgdrop install <username>/<package[@version|@tag]>`
- `pkgdrop remove <package[@version]>`

Install example:

```bash
pkgdrop install BlankParticle/some-package@latest
```

## Environment Variables

- `DATABASE_URL` - database connection string (default: `file:./data/registry.db`)
- `MAX_UPLOAD_SIZE_MB` - max tarball upload size in MB (default: `10`)
- `UPLOADER_WHITELIST` - comma-separated GitHub usernames allowed to publish
- `USE_MOCK_GITHUB_AUTH` - enable mock auth mode for local/dev flows

CLI-related variables are also supported in local workflows:

- `PREVIEW_PKG_API_URL`
- `PREVIEW_PKG_REGISTRY_URL`

## Testing

Run all tests:

```bash
pnpm test
```

Integration coverage is centered in `tests/integration/registry-workflows.test.ts` and exercises publish/install/remove flows end-to-end.

## Local Fixture Packages

Generate synthetic packages for manual testing:

```bash
pnpm tsx scripts/make-test-package.ts
```

Generated test package output should live under `test-packages/` (gitignored).