@powerhousedao/registry 6.0.0-dev.105 → 6.0.0-dev.106

package/{dist/cdn-cache/@powerhousedao/vetra/6.0.0-dev.59/LICENSE → LICENSE}

@@ -658,4 +658,4 @@ specific requirements.
   You should also get your employer (if you work as a programmer) or school,
 if any, to sign a "copyright disclaimer" for the program, if necessary.
 For more information on this, and how to apply and follow the GNU AGPL, see
-<https://www.gnu.org/licenses/>.
+<https://www.gnu.org/licenses/>.

package/README.md

@@ -1,52 +1,124 @@
 # @powerhousedao/registry
 
-Express-based server that serves Powerhouse packages (ESM bundles) for dynamic loading via `import()` in browsers and Node.js.
+Powerhouse package registry built on Verdaccio. Serves as both an npm registry and a CDN for Powerhouse package bundles (ESM) for dynamic `import()` in browsers and Node.js.
 
-## Quick Start
+## API
 
-### CLI
+### Packages
 
-```sh
-# Serve packages from a directory
-ph-registry ./path/to/packages 3000
+#### `GET /packages`
 
-# Or with environment variables
-REGISTRY_DIR=./packages PORT=3000 ph-registry
+Returns a JSON array of all discovered packages. Supports filtering by document type:
 
-# Or run directly
-node dist/src/run.js ./path/to/packages 3000
 ```
+GET /packages?documentType=powerhouse/package
+```
+
+#### `GET /packages/by-document-type?type=<documentType>`
+
+Returns an array of package names that contain the specified document type.
+
+#### `GET /packages/<packageName>`
+
+Returns info for a single package (supports scoped names like `@powerhousedao/vetra`).
+
+### CDN
+
+#### `GET /-/cdn/<packageName>/<filePath>`
 
-Arguments:
+Serves files from the CDN cache. On first request, fetches and extracts the tarball from Verdaccio. Looks for files in the package root, then `cdn/`, `dist/cdn/`, and `dist/` subdirectories.
 
-- `dir` (positional, 1st) -- directory to serve packages from (default: `.`, env: `REGISTRY_DIR`)
-- `port` (positional, 2nd) -- port to listen on (default: `8080`, env: `PORT`)
+### Publish Notifications
 
-### Library
+When a package is published, the registry can notify subscribers in real time via Server-Sent Events (SSE) and webhooks.
+
+#### SSE — `GET /-/events`
+
+Opens a persistent SSE connection. The server sends:
+
+- `connected` event on initial connection
+- `publish` event whenever a package is published, with payload:
+
+```json
+{ "packageName": "@scope/pkg", "version": "1.0.0" }
+```
+
+Example (browser):
 
 ```ts
-import express from "express";
-import { createRegistryRouter } from "@powerhousedao/registry";
+const source = new EventSource("http://localhost:8080/-/events");
+source.addEventListener("publish", (e) => {
+  const { packageName, version } = JSON.parse(e.data);
+  console.log(`${packageName}@${version} published`);
+});
+```
+
+#### Webhooks
+
+Webhooks are persisted to disk and survive restarts. Predefined webhooks can also be provided via configuration.
 
-const app = express();
-app.use(createRegistryRouter("./packages"));
-app.listen(3000);
+##### `GET /-/webhooks`
+
+Returns all registered webhooks (predefined + dynamic).
+
+##### `POST /-/webhooks`
+
+Registers a new webhook. Body:
+
+```json
+{ "endpoint": "https://example.com/hook", "headers": { "X-Token": "secret" } }
 ```
 
-## API
+`headers` is optional. Returns `201` on success. Duplicate endpoints are ignored.
 
-### `createPowerhouseRouter(config)`
+##### `DELETE /-/webhooks`
 
-Creates an Express `Router` that serves packages.
+Removes a dynamic webhook. Body:
 
-### `GET /packages`
+```json
+{ "endpoint": "https://example.com/hook" }
+```
+
+Returns `204` on success, `404` if not found. Predefined webhooks cannot be removed.
 
-Returns a JSON array of all discovered packages.
+When a package is published, each webhook receives a POST with:
+
+```json
+{ "packageName": "@scope/pkg", "version": "1.0.0" }
+```
 
-### `GET /packages/by-document-type?type=<documentType>`
+### npm Protocol
 
-Returns package names that contain the specified document type.
+All standard npm registry operations (publish, install, etc.) are handled by Verdaccio.
 
-### `GET /-/cdn/<packageName>/<filePath>`
+## Publishing Packages
+
+```sh
+npm publish --registry http://localhost:8080/
+```
+
+On publish, the CDN cache for that package is automatically invalidated and the new version is extracted immediately.
+
+## CLI
+
+```sh
+ph-registry --port 8080 --storage-dir ./storage --cdn-cache-dir ./cdn-cache
+```
 
-Serves files from the CDN cache for a package.
+Options:
+
+| Option | Env Variable | Default | Description |
+|---|---|---|---|
+| `--port` | `PORT` | `8080` | Port to listen on |
+| `--storage-dir` | `REGISTRY_STORAGE` | `./storage` | Verdaccio storage directory |
+| `--cdn-cache-dir` | `REGISTRY_CDN_CACHE` | `./cdn-cache` | CDN cache directory |
+| `--uplink` | `REGISTRY_UPLINK` | — | Upstream npm registry URL |
+| `--web-enabled` | `REGISTRY_WEB` | `true` | Enable Verdaccio web UI |
+| `--webhook` | `REGISTRY_WEBHOOKS` | — | Comma-separated webhook URLs to notify on publish |
+| `--s3-bucket` | `S3_BUCKET` | — | S3 bucket for storage |
+| `--s3-endpoint` | `S3_ENDPOINT` | — | S3 endpoint URL |
+| `--s3-region` | `S3_REGION` | — | S3 region |
+| `--s3-access-key-id` | `S3_ACCESS_KEY_ID` | — | S3 access key |
+| `--s3-secret-access-key` | `S3_SECRET_ACCESS_KEY` | — | S3 secret key |
+| `--s3-key-prefix` | `S3_KEY_PREFIX` | — | S3 key prefix |
+| `--s3-force-path-style` | `S3_FORCE_PATH_STYLE` | `true` | Force S3 path-style URLs |

package/dist/cli.d.mts

@@ -0,0 +1,41 @@
+import * as cmd_ts_dist_cjs_argparser_js0 from "cmd-ts/dist/cjs/argparser.js";
+import * as cmd_ts_dist_cjs_helpdoc_js0 from "cmd-ts/dist/cjs/helpdoc.js";
+import * as cmd_ts_dist_cjs_runner_js0 from "cmd-ts/dist/cjs/runner.js";
+
+//#region cli.d.ts
+declare const registryCommand: Partial<cmd_ts_dist_cjs_argparser_js0.Register> & {
+  parse(context: cmd_ts_dist_cjs_argparser_js0.ParseContext): Promise<cmd_ts_dist_cjs_argparser_js0.ParsingResult<{
+    port: number;
+    storageDir: string;
+    cdnCacheDir: string;
+    uplink: string | undefined;
+    s3Bucket: string | undefined;
+    s3Endpoint: string | undefined;
+    s3Region: string | undefined;
+    s3AccessKeyId: string | undefined;
+    s3SecretAccessKey: string | undefined;
+    s3KeyPrefix: string | undefined;
+    s3ForcePathStyle: boolean;
+    webEnabled: boolean;
+    webhooks: string | undefined;
+  }>>;
+} & cmd_ts_dist_cjs_helpdoc_js0.PrintHelp & cmd_ts_dist_cjs_helpdoc_js0.ProvidesHelp & cmd_ts_dist_cjs_helpdoc_js0.Named & Partial<cmd_ts_dist_cjs_helpdoc_js0.Versioned> & cmd_ts_dist_cjs_argparser_js0.Register & cmd_ts_dist_cjs_runner_js0.Handling<{
+  port: number;
+  storageDir: string;
+  cdnCacheDir: string;
+  uplink: string | undefined;
+  s3Bucket: string | undefined;
+  s3Endpoint: string | undefined;
+  s3Region: string | undefined;
+  s3AccessKeyId: string | undefined;
+  s3SecretAccessKey: string | undefined;
+  s3KeyPrefix: string | undefined;
+  s3ForcePathStyle: boolean;
+  webEnabled: boolean;
+  webhooks: string | undefined;
+}, Promise<void>> & {
+  run(context: cmd_ts_dist_cjs_argparser_js0.ParseContext): Promise<cmd_ts_dist_cjs_argparser_js0.ParsingResult<Promise<void>>>;
+} & Partial<cmd_ts_dist_cjs_helpdoc_js0.Versioned & cmd_ts_dist_cjs_helpdoc_js0.Descriptive & cmd_ts_dist_cjs_helpdoc_js0.Aliased>;
+//#endregion
+export { registryCommand };
+//# sourceMappingURL=cli.d.mts.map

package/dist/cli.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.mts","names":[],"sources":["../cli.ts"],"mappings":";;;;;cAiBa,eAAA,EAAe,OAAA,CA8F1B,6BAAA,CA9F0B,QAAA;iBAAA,6BAAA,CAAA,YAAA"}