@zktx.io/walrus-sites-preview 0.0.2 → 0.0.3

package/README.md

@@ -1,95 +1,135 @@
-# Walrus Sites Preview (CLI)
+# Walrus Sites Preview
 
-Installable CLI to preview Walrus Sites locally:
+Preview Walrus Sites already deployed on testnet or mainnet locally using a familiar
+npm → localhost workflow — without setting up a portal.
 
-- **site mode**: fetch resources via Sui RPC + Walrus aggregator for a given site object ID
+This tool is for developers who want to quickly preview or debug a deployed Walrus Site in a simple, local-style environment.
+
+---
+
+## Why this exists
+
+Previewing a Walrus Site on testnet usually requires setting up a portal, which can be difficult for beginners and unnecessary for quick debugging.
+
+This CLI removes that friction.
+Give it a site object ID, and it serves the site locally.
+
+---
+
+## What it does
+
+- Loads a Walrus Site using a site object ID
+- Fetches resources via Sui RPC + Walrus aggregator
+- Serves the site locally (e.g. `http://localhost:3000`)
+- Focused purely on developer preview and debugging
+
+This is not a production hosting solution and does not replace portals.
+
+---
 
 ## Requirements
 
 - Node.js 18+
 
-## Install (as dev dependency)
+---
+
+## Install
 
 ```sh
 npm i -D @zktx.io/walrus-sites-preview
 ```
 
-## Run (via npm script)
+---
 
-Add this to your project:
+## Quick Start
+
+Add an npm script to your project:
 
 ```json
 {
 	"scripts": {
 		"preview:testnet": "preview -testnet -id 0xYOUR_SITE_OBJECT_ID -port 3000",
-		"preview:mainnet": "preview -mainnet -id 0xYOUR_SITE_OBJECT_ID -port 3000",
-		"preview": "preview"
+		"preview:mainnet": "preview -mainnet -id 0xYOUR_SITE_OBJECT_ID -port 3000"
 	}
 }
 ```
 
-Then run:
+Run:
 
 ```sh
 npm run preview:testnet
 ```
 
-This starts a local server at `http://localhost:3000`.
+Then open:
 
-You can inspect the effective config at `http://localhost:3000/__config`.
+`http://localhost:3000`
 
-If you prefer a file-based config, create `config.json` next to your `package.json` and pass overrides as needed (the CLI flags win).
+You can inspect the resolved configuration at:
 
-To pass arguments dynamically, use `--`:
+`http://localhost:3000/__config`
 
-```sh
-npm run preview -- -testnet -id 0xYOUR_SITE_OBJECT_ID -port 3000
-```
-
-## Where `dist` comes from (portal build)
+---
 
-This section is for maintainers of this package. Consumers don’t need to build `dist/` manually (it ships in the npm package).
+## Configuration
 
-- Vendored from the walrus-sites portal codebase:
-    - Source repo: https://github.com/MystenLabs/walrus-sites/tree/main/portal
-        - `portal/worker` → `./portal-worker`
-        - `portal/common` → `./portal-common`
-- Source: `./portal-worker/src` (service worker TS) and `./portal-worker/static` (static assets)
-- Shared libs: `./portal-common/lib/src` (shared implementation used by the worker)
-- Build configs: `./webpack.config.*.cjs` (kept in this repo, not published)
-- Build command:
+You can optionally create a `config.json` next to your `package.json`.
 
-```sh
-npm install
-npm run build
-```
+CLI flags always override file-based config.
 
-## Publish
+If you use `-testnet` or `-mainnet`, the required RPC and aggregator URLs are filled automatically.
 
-This package is set up to publish with `dist/` included. `npm pack` / `npm publish` runs `prepack`, which rebuilds `dist/` via `npm run build`.
+`config.json` supports:
 
-## Maintainers: static mode
+- `siteObjectId` (required)
+- `rpcUrlList` (required unless using `-testnet` / `-mainnet`)
+- `aggregatorUrl` (required unless using `-testnet` / `-mainnet`)
+- `sitePackage` (required unless using `-testnet` / `-mainnet`)
+- `network` (optional, informational)
+- `host`, `port` (via CLI flags)
 
-If you only want to serve a local static folder as a SPA:
+Example:
 
-```sh
-npx preview --mode static --dist ./dist -port 3000
+```json
+{
+	"network": "testnet",
+	"rpcUrlList": ["https://fullnode.testnet.sui.io"],
+	"aggregatorUrl": "https://aggregator.walrus-testnet.walrus.space",
+	"sitePackage": "0x...",
+	"siteObjectId": "0x..."
+}
 ```
 
-If your `dist` lives somewhere else:
+To pass arguments dynamically:
 
 ```sh
-npx preview --mode static --dist /absolute/path/to/dist
+npm i -D @zktx.io/walrus-sites-preview
 ```
 
-## Options
+Add a pass-through script:
 
-```sh
-npx preview -port 8090 --open
+```json
+{
+	"scripts": {
+		"preview": "preview"
+	}
+}
 ```
 
-Override site config without editing `config.json`:
+Then run:
 
 ```sh
-npx preview --site-object-id 0x... --rpc https://fullnode.mainnet.sui.io --aggregator https://aggregator.walrus-mainnet.walrus.space --site-package 0x...
+npm run preview -- -testnet -id 0xYOUR_SITE_OBJECT_ID -port 3000
 ```
+
+---
+
+## Source attribution
+
+This package vendors and adapts parts of the Walrus Sites portal source code.
+
+Where `dist` comes from (portal build):
+
+- Source repo: https://github.com/MystenLabs/walrus-sites/tree/main/portal
+- `portal/worker` → `./portal-worker`
+- `portal/common` → `./portal-common`
+- Source: `./portal-worker/src` (service worker TypeScript) and `./portal-worker/static` (static assets)

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@zktx.io/walrus-sites-preview",
 	"description": "Local preview CLI for Walrus Sites (fetch from Sui + Walrus, or serve bundled static portal dist).",
-	"version": "0.0.2",
+	"version": "0.0.3",
 	"type": "module",
 	"bin": {
 		"preview": "preview.mjs"

package/preview.mjs

@@ -194,7 +194,9 @@ function contentType(filePath) {
 function safeResolve(rootDir, urlPath) {
 	const rel = urlPath.replace(/^\/+/, "");
 	const resolved = path.resolve(rootDir, rel);
-	if (!resolved.startsWith(rootDir + path.sep) && resolved !== rootDir) return null;
+	const normalizedRoot = path.normalize(rootDir + path.sep);
+	const normalizedResolved = path.normalize(resolved + path.sep);
+	if (!normalizedResolved.startsWith(normalizedRoot)) return null;
 	return resolved;
 }
 
@@ -403,9 +405,10 @@ async function createSiteHandler(siteConfig) {
 		if (message.includes("ERR_MODULE_NOT_FOUND") || message.includes("Cannot find package")) {
 			throw new Error(
 				[
-					"Missing npm dependencies for site mode.",
-					"Run `npm install` in this package (requires network access).",
-					`Or run static mode: \`${CLI_NAME} --mode static\``,
+					"Failed to load @mysten/sui dependencies for site mode.",
+					"If you're running from this repo, run `npm install` here first.",
+					"If you're using the published package, reinstall it in your project: `npm i -D @zktx.io/walrus-sites-preview`.",
+					"Then run the command again.",
 				].join("\n"),
 			);
 		}