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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zktx.io
+
+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

@@ -1,35 +1,105 @@
+<p align="center">
+	<img src="https://raw.githubusercontent.com/zktx-io/walrus-sites-preview/main/Walrus_Logotype_Black.png" alt="Walrus" width="360" />
+</p>
+
 # Walrus Sites Preview
 
-Preview Walrus Sites already deployed on testnet or mainnet locally using a familiar
-npm → localhost workflow — without setting up a portal.
+Preview Walrus Sites already deployed on testnet or mainnet through a familiar
+**npm → localhost** workflow.
+
+Walrus Sites Preview is a small CLI for opening a current deployment locally
+during design review, QA, planning review, or stakeholder feedback. It is meant
+to sit alongside existing Walrus portal and deployment workflows, not replace
+them.
+
+A developer can share one command, and teammates can review the deployed site on
+`localhost` using the same kind of browser workflow they use for regular web
+projects.
+
+---
+
+## Demo Video
+
+A short demo showing how to preview a deployed Walrus Site locally:
+
+https://github.com/user-attachments/assets/c28c033a-92c5-4ee9-82e0-1406319842c7
+
+The preview URL used in the demo is `http://localhost:3000`.
+
+---
+
+## Quickstart (one-liner)
+
+Preview a deployed Walrus Site in a single command.
+
+For mainnet:
+
+```sh
+npx @zktx.io/walrus-sites-preview 0xYOUR_SITE_OBJECT_ID
+```
+
+For testnet:
+
+```sh
+npx @zktx.io/walrus-sites-preview -testnet 0xYOUR_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.
+Then open:
+
+```text
+http://localhost:3000
+```
+
+You can also add `--open` to open the browser automatically:
+
+```sh
+npx @zktx.io/walrus-sites-preview 0xYOUR_SITE_OBJECT_ID --open
+```
 
 ---
 
 ## 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.
+Walrus portals remain the right place for production access, integration
+testing, and portal-specific behavior. This CLI covers a narrower case: quickly
+checking an already deployed site during an internal review cycle.
+
+In that situation, teams often need a simple browser URL for the current
+deployment while keeping the existing deployment pipeline unchanged. Provide a
+site object ID, and this CLI fetches the resources and serves a local preview.
 
-This CLI removes that friction.
-Give it a site object ID, and it serves the site locally.
+The goal is to make review handoff simpler while preserving the established
+Walrus workflow.
 
 ---
 
 ## 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
+- Fetches resources via Sui RPC and the Walrus aggregator
+- Serves the site locally (for example, `http://localhost:3000`)
+- Provides a local review path that can sit alongside portal-based workflows
+- Supports preview, debugging, QA, and review workflows
+
+This is **not** a production hosting solution and does not replace Walrus portals.
 
-This is not a production hosting solution and does not replace portals.
+---
+
+## Who this is for
+
+- Developers who want a quick local preview of an already deployed Walrus Site
+- Web designers reviewing visual changes from a testnet deployment
+- Planners, PMs, and QA reviewers checking an in-progress site before release
+- Teams that want a lightweight local review command for deployed Walrus Sites
+
+For many internal review sessions, a reviewer can start with the command and the
+site object ID. Wallets and deployment keys are not part of the preview flow.
 
 ---
 
 ## Requirements
 
-- Node.js 18+
+- Node.js 18 or later
 
 ---
 
@@ -39,17 +109,20 @@ This is not a production hosting solution and does not replace portals.
 npm i -D @zktx.io/walrus-sites-preview
 ```
 
+> Note: This package is published as a scoped npm package:
+> `@zktx.io/walrus-sites-preview`
+
 ---
 
-## Quick Start
+## Quick Start (npm scripts)
 
-Add an npm script to your project:
+Add an npm script to your project so teammates can run a familiar command:
 
 ```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:testnet": "walrus-sites-preview -testnet 0xYOUR_SITE_OBJECT_ID -port 3000",
+		"preview:mainnet": "walrus-sites-preview 0xYOUR_SITE_OBJECT_ID -port 3000"
 	}
 }
 ```
@@ -62,23 +135,65 @@ npm run preview:testnet
 
 Then open:
 
-`http://localhost:3000`
+```text
+http://localhost:3000
+```
 
 You can inspect the resolved configuration at:
 
-`http://localhost:3000/__config`
+```text
+http://localhost:3000/__config
+```
+
+---
+
+## How to get a Site Object ID
+
+`walrus-sites-preview` requires a **Walrus Site Object ID**.
+
+When a site is deployed to Walrus Sites — whether via the official site-builder CLI or a CI workflow — the **Site Object ID is printed in the deployment output**.
+
+Look for a line similar to:
+
+```text
+Site object ID: 0x...
+```
+
+or:
+
+```text
+"site_obj_id": "0x..."
+```
+
+Copy this value and pass it to the preview command.
+
+For detailed deployment guides, see:
+
+- Publishing a Walrus Site (official docs):
+  [https://docs.wal.app/docs/sites/getting-started/publishing-your-first-site](https://docs.wal.app/docs/sites/getting-started/publishing-your-first-site)
+- Deploying via GitHub Actions (walrus-sites-provenance):
+  [https://github.com/marketplace/actions/walrus-sites-provenance](https://github.com/marketplace/actions/walrus-sites-provenance)
+
+> This tool does not deploy or update sites.
+> It only previews already deployed Walrus Sites.
 
 ---
 
 ## Configuration
 
-You can optionally create a `config.json` next to your `package.json`.
+You may optionally create a `config.json` next to your `package.json`.
+
+CLI flags always override file-based configuration.
 
-CLI flags always override file-based config.
+When using `-testnet` or `-mainnet`, the following values are filled automatically:
 
-If you use `-testnet` or `-mainnet`, the required RPC and aggregator URLs are filled automatically.
+- `rpcUrlList`
+- `aggregatorUrl`
+- `sitePackage`
 
-`config.json` supports:
+The positional one-liner defaults to mainnet. Pass `-testnet` for testnet sites.
+
+### Supported fields
 
 - `siteObjectId` (required)
 - `rpcUrlList` (required unless using `-testnet` / `-mainnet`)
@@ -87,7 +202,7 @@ If you use `-testnet` or `-mainnet`, the required RPC and aggregator URLs are fi
 - `network` (optional, informational)
 - `host`, `port` (via CLI flags)
 
-Example:
+### Example
 
 ```json
 {
@@ -99,7 +214,11 @@ Example:
 }
 ```
 
-To pass arguments dynamically:
+---
+
+## Passing arguments dynamically
+
+Install the package:
 
 ```sh
 npm i -D @zktx.io/walrus-sites-preview
@@ -110,7 +229,7 @@ Add a pass-through script:
 ```json
 {
 	"scripts": {
-		"preview": "preview"
+		"preview": "walrus-sites-preview"
 	}
 }
 ```
@@ -118,7 +237,7 @@ Add a pass-through script:
 Then run:
 
 ```sh
-npm run preview -- -testnet -id 0xYOUR_SITE_OBJECT_ID -port 3000
+npm run preview -- -testnet 0xYOUR_SITE_OBJECT_ID -port 3000
 ```
 
 ---
@@ -127,9 +246,19 @@ npm run preview -- -testnet -id 0xYOUR_SITE_OBJECT_ID -port 3000
 
 This package vendors and adapts parts of the Walrus Sites portal source code.
 
-Where `dist` comes from (portal build):
+The vendored portal worker code is currently aligned with the upstream
+`portal/worker` package version `2.9.0`.
 
-- Source repo: https://github.com/MystenLabs/walrus-sites/tree/main/portal
+Origin of the bundled `dist` assets (portal build):
+
+- Source repository:
+  [https://github.com/MystenLabs/walrus-sites/tree/main/portal](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)
+- Included sources:
+    - `./portal-worker/src` (service worker TypeScript)
+    - `./portal-worker/static` (static assets)
+
+## License
+
+MIT