@ponharu/pkgflare 0.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing
+
+Bug reports, documentation improvements, and focused pull requests are welcome. For changes to registry behavior or product scope, open an issue describing the use case and proposed behavior before building a large change. Use [SECURITY.md](./SECURITY.md) for suspected vulnerabilities.
+
+## Local setup
+
+Install Node.js 22 or later and the Bun version declared in `package.json`, then run:
+
+```sh
+bun install --frozen-lockfile
+bun run check
+bun run test
+```
+
+Tests use local Cloudflare bindings and do not need deployment credentials. Use synthetic packages and credentials in examples and fixtures.
+
+## Making a change
+
+Read the [specification](./docs/specification.md) and [architecture](./docs/architecture.md) for the behavior the implementation must preserve. Keep changes focused and update the relevant documentation when behavior changes. Add regression coverage for bug fixes and boundary cases, especially parsing, authorization, concurrent publishing, and deployment recovery.
+
+Run `bun run format` and `bun run check` before submitting. Choose further verification based on the affected behavior:
+
+| Command                 | Coverage                                                                                    |
+| ----------------------- | ------------------------------------------------------------------------------------------- |
+| `bun run test`          | Unit tests and Worker integration tests with local D1/R2                                    |
+| `bun run test:e2e`      | Real npm/Bun publish, npm dist-tags, and cold-cache installs with npm/pnpm/Yarn Classic/Bun |
+| `bun run test:package`  | Packed package installed in a temporary project, CLI help, and Wrangler deployment dry-run  |
+| `bun run test:coverage` | Unit and Worker coverage reports                                                            |
+
+The client and packaging checks require network access to install dependencies; they do not deploy to Cloudflare. CI runs check, test, E2E, and package verification. Local tests do not establish real-account permissions or production capacity.
+
+## Database and packaging changes
+
+Add a new numbered SQL migration for schema changes. Never rewrite a released migration, and keep the previously deployed Worker working after migration if deploying its replacement fails. Cover migration copying and retry behavior when changing the CLI.
+
+The npm artifact must include its runtime, type declarations, migrations, and linked user documentation. Run the package check when changing build outputs or published files. Keep environment-specific paths, credentials, and private registry URLs out of artifacts and lockfiles.
+
+## Pull requests
+
+Explain the problem, the resulting behavior, and how you verified it. Call out compatibility or migration implications. Include sanitized reproduction steps for bugs; do not attach private packages, deployment credentials, or token values.
+
+## Releases
+
+Pull request titles use Conventional Commits and are checked by `semantic-pr.yml`. Use squash merges so the checked title becomes the commit subject on `main`. `fix:` produces a patch release, `feat:` a minor release, and `!` or a `BREAKING CHANGE:` footer a major release. Documentation and maintenance commits do not normally trigger a release.
+
+On each push to `main`, `release.yml` calls `test.yml` for checks, unit/Worker tests, client compatibility, and package verification. Only after they pass does semantic-release determine the next version, publish to npm, and create a Git tag and GitHub Release. It does not commit version updates or a changelog back to the repository. Release notes live in GitHub Releases.
+
+The npm package uses Trusted Publishing. In the npm settings for `@ponharu/pkgflare`, authorize GitHub owner `ponharu`, repository `pkgflare`, and workflow filename `release.yml`, with direct publishing allowed. The calling workflow is `release.yml`; `test.yml` is only the reusable verification workflow. No GitHub Environment is configured. Complete package ownership and trusted-publisher setup on npm before relying on automatic publication; see [npm's setup instructions](https://docs.npmjs.com/trusted-publishers/).
+
+The release job uses GitHub-hosted runners, Node.js 24, and the locked semantic-release npm plugin with OIDC support. `id-token: write` supplies npm authentication, while `GITHUB_TOKEN` creates tags and GitHub Releases. No long-lived npm publish token is required. Issue/PR release comments and labels are disabled.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ponharu
+
+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,212 @@
+# pkgflare
+
+Deploy a scoped private npm registry to your own Cloudflare account.
+
+`pkgflare` packages a Cloudflare Worker, D1 migrations, R2 bindings, authentication, and deployment tooling. Package authors and consumers continue to use standard npm-compatible clients; package data and registry infrastructure stay in the Cloudflare account you control.
+
+## What it provides
+
+- Standard scoped package publish and install endpoints
+- Immutable tarballs in R2
+- Package metadata and mutable dist-tags in D1
+- Read and publish tokens stored as Cloudflare Secrets
+- Repeatable deployment through one `pkgflare deploy` command
+- npm-compatible metadata and tarball responses tested with npm, pnpm, Yarn Classic, and Bun
+
+It intentionally does not provide a web UI, npmjs.org proxy, user database, team model, or a hosted registry service.
+
+## Requirements
+
+- Node.js 22 or later
+- A Cloudflare account with Workers, D1, and R2 available
+- Wrangler authentication, either through `wrangler login` or supported environment credentials
+
+## Set up a registry
+
+### 1. Create the deployment project
+
+Use a dedicated, private repository to keep your deployment configuration and state:
+
+```sh
+mkdir acme-registry
+cd acme-registry
+npm init -y
+npm install --save-dev @ponharu/pkgflare
+npx pkgflare init
+npx wrangler login
+```
+
+Edit the generated `pkgflare.config.ts`:
+
+```ts
+import { defineConfig } from "@ponharu/pkgflare";
+
+export default defineConfig({
+  name: "acme-registry",
+  // Use your Cloudflare account ID, not a zone ID.
+  accountId: "0123456789abcdef0123456789abcdef",
+  scopes: ["@acme"],
+  auth: {
+    provider: "secrets",
+    tokens: [
+      { binding: "PKGFLARE_READ_TOKEN", permissions: ["read"] },
+      { binding: "PKGFLARE_PUBLISH_TOKEN", permissions: ["publish"] },
+    ],
+  },
+});
+```
+
+Replace the account ID, deployment name, and scope with your own. `accountId` can be omitted when Wrangler can resolve exactly one account. The default endpoint uses `workers.dev`. An optional `hostname: "packages.example.com"` configures a [custom domain](./docs/operations.md#cloudflare-authentication-and-domains).
+
+### 2. Deploy and register tokens
+
+```sh
+npx pkgflare deploy
+```
+
+The command creates the D1 database and R2 bucket, applies migrations, deploys the Worker, and prints its URL and Secret registration commands. Requests require a registered token before they can succeed.
+
+Generate two different tokens by running this command twice, and save them in your password manager:
+
+```sh
+npx pkgflare token generate
+```
+
+Register the read token, then the publish token. Paste each value at Wrangler's prompt:
+
+```sh
+npx wrangler secret put PKGFLARE_READ_TOKEN --config .pkgflare/wrangler.json
+npx wrangler secret put PKGFLARE_PUBLISH_TOKEN --config .pkgflare/wrangler.json
+```
+
+Keep token values out of source files and Git. Commit the deployment configuration, lockfile, and generated state files to your private deployment repository as described in [deployment state](./docs/operations.md#deployment-state).
+
+### 3. Publish your first package
+
+In a separate directory for the package you want to publish, create `.npmrc` with the URL printed by deploy. Replace the example hostname on **both** lines:
+
+```ini
+@acme:registry=https://acme-registry.example.workers.dev
+//acme-registry.example.workers.dev/:_authToken=${NPM_TOKEN}
+```
+
+Set `NPM_TOKEN` in your shell to the **publish** token. For example, in Bash or Zsh, this prompts without displaying the token or putting its value in shell history:
+
+```sh
+printf 'Publish token: '
+read -r -s NPM_TOKEN
+printf '\n'
+export NPM_TOKEN
+```
+
+For a minimal example package, create `package.json` and `index.js` in that directory:
+
+```json
+{
+  "name": "@acme/example",
+  "version": "1.0.0",
+  "type": "module",
+  "exports": "./index.js",
+  "files": ["index.js"]
+}
+```
+
+```js
+export const greeting = "Hello from pkgflare";
+```
+
+Publish and inspect it:
+
+```sh
+npm publish
+npm view @acme/example
+```
+
+Use an allowed scope and a new version for each publish. Do not set `"private": true` in the package manifest: npm uses that field to prevent publishing to any registry.
+
+### 4. Install from a consumer project
+
+In another project, copy the scope-specific `.npmrc` above. Set `NPM_TOKEN` to the **read** token using the same prompt, then run:
+
+```sh
+npm install @acme/example
+```
+
+The `.npmrc` contains an environment variable reference and can be committed; the token value must stay in your shell environment or CI secret store. Public dependencies continue to use the client's default registry.
+
+## Compatibility and permissions
+
+| Operation                       | Supported clients            |
+| ------------------------------- | ---------------------------- |
+| Publish                         | npm, Bun                     |
+| Metadata and install            | npm, pnpm, Yarn Classic, Bun |
+| List, add, and remove dist-tags | npm                          |
+
+Yarn Berry and other clients are outside the tested compatibility baseline. pkgflare does not implement `npm login`, `npm adduser`, `npm unpublish`, `npm deprecate`, search, or the npm audit API. It is a scoped private registry, not a complete replacement for the public npm service.
+
+A read token can read every package in the registry. A publish token can also publish packages and change dist-tags across all configured scopes. Permissions are not restricted per package or scope; use separate registry deployments when readers or publishers need different trust boundaries.
+
+Versions are immutable. To promote or roll back an existing version, use the publish token with `npm dist-tag`:
+
+```sh
+npm dist-tag add @acme/example@1.1.0 latest
+npm dist-tag add @acme/example@1.0.0 latest
+```
+
+The first command assumes `1.1.0` has already been published. Moving a tag affects future tag-based resolution; it does not rewrite consumers' lockfiles or remove a version.
+
+## CLI
+
+```text
+pkgflare deploy [--config <path>] [--secrets-file <path>] [--adopt-existing]
+pkgflare init
+pkgflare token generate
+```
+
+`token generate` creates a cryptographically random token locally and prints it once. pkgflare does not store, distribute, list, or revoke tokens.
+
+## Publish consistency
+
+A package version is immutable, while dist-tags remain mutable for promotion and rollback. pkgflare incrementally parses the standard npm publish document, decodes its Base64 attachment into fixed-size R2 multipart chunks, and calculates SHA-1 and SHA-512 without holding the complete tarball in Worker memory. A unique attempt object is published in D1 only after R2 completes; D1's package-and-version constraint chooses the sole winner of concurrent publishes.
+
+If a D1 result is uncertain, pkgflare reads the version back before deciding whether the attempt succeeded or conflicted. An interrupted attempt can leave an unreachable R2 object, but it is never returned by metadata or install requests. Automatic orphan collection is not part of the initial release.
+
+pkgflare does not add a tarball-size ceiling. The complete Base64-encoded npm publish request remains subject to Cloudflare's request-body and Worker CPU limits. Those limits are governed separately and can vary with the account and Workers usage model. Non-attachment JSON metadata is limited to 1 MiB, JSON nesting is limited to 128 levels, and tarball downloads are streamed from R2 with immutable caching and byte ranges. See [Cloudflare limits](https://developers.cloudflare.com/workers/platform/limits/) when choosing your deployment plan.
+
+## Rotate tokens
+
+To rotate a token without interrupting existing clients:
+
+1. Add a new Secret binding to the config while retaining the old binding, then deploy.
+2. Register the new Secret and switch clients to it.
+3. Remove the old binding from the config and deploy again.
+4. Delete the old Cloudflare Secret.
+
+Missing configured Secret bindings are ignored as long as another configured token grants access. Secret values and Authorization headers are never logged.
+
+## Updates and migrations
+
+Updating the npm package and running `pkgflare deploy` copies every packaged migration, applies pending migrations, and then deploys the new Worker. Migrations are append-only and must remain compatible with the previously deployed Worker so that a failed deployment can be retried without taking the Registry offline.
+
+See [operations](./docs/operations.md) for CI credentials, deployment recovery, backups, and troubleshooting. The complete behavior and failure contracts are described in [the specification](./docs/specification.md).
+
+## Development
+
+```sh
+bun install
+bun run check
+bun run format
+bun run test
+bun run test:e2e
+bun run build
+```
+
+The integration suite runs the Worker with local D1 and R2 bindings through Cloudflare's Vitest integration. It does not require Cloudflare credentials. See [CONTRIBUTING.md](./CONTRIBUTING.md) for the development workflow and [architecture](./docs/architecture.md) for design decisions and invariants.
+
+## Security
+
+Please report vulnerabilities using the process in [SECURITY.md](./SECURITY.md). Do not include tokens, authorization headers, Cloudflare credentials, or private package contents in public issues.
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,13 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please use GitHub's private vulnerability reporting feature for this repository. Do not open a public issue for a suspected vulnerability.
+
+Include the affected version, impact, reproduction steps, and any suggested mitigation. Remove registry tokens, authorization headers, Cloudflare credentials, account identifiers, and private package contents from the report unless they are essential to reproduce the issue.
+
+You should receive an acknowledgement within seven days. A fix and disclosure schedule will be coordinated after the report is validated.
+
+## Deployment responsibility
+
+pkgflare deploys into the user's Cloudflare account. Users are responsible for generating, storing, distributing, rotating, and revoking their registry tokens, and for limiting Cloudflare credentials to the permissions needed for deployment.