worldwatch 0.1.0__tar.gz

worldwatch-0.1.0/.claude/settings.json

@@ -0,0 +1,21 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git add *)",
+      "Bash(git commit -m ' *)",
+      "Bash(git push *)",
+      "Bash(git checkout *)",
+      "Bash(curl -s https://api.github.com/repos/ethersphere/bee/releases/latest)",
+      "Bash(curl *)",
+      "Bash(jq)",
+      "Bash(npm --version)",
+      "Bash(swarm-cli *)",
+      "Bash(node *)",
+      "Bash(echo *)",
+      "Bash(bee version *)",
+      "Edit(.claude/skills/*)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:docs.ethswarm.org)"
+    ]
+  }
+}

worldwatch-0.1.0/.claude/skills/swarm/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: swarm
+description: Primary Swarm entry point — detects whether Bee is installed and running, routes to setup/troubleshoot if not, and otherwise shows the full skill menu and routes the developer to the right workflow (storage, website, app, access control, messaging). Use at the start of any Swarm task or when unsure where to begin.
+user-invocable: true
+---
+
+# Swarm Entry Point
+
+The starting point for building on Swarm. This skill detects whether Bee is installed and running, routes the user to setup or troubleshooting if needed, and once a node is ready, shows the full menu of skills and routes the user to the right one.
+
+## Formatting
+
+When presenting to the user, use consistent labels before each code block:
+- **Run in your terminal:** — a command the user should execute
+- **Expected output:** — example of what a successful result looks like
+- **Save as `filename`:** — file contents the user should write to disk
+
+Add a `---` horizontal rule before each labeled code block to visually separate it from surrounding text.
+
+---
+
+## Step 1 — Check if Bee is running
+
+**Say "Checking your Bee node…"**, then probe the default API endpoint directly — don't use swarm-cli here (it may not be installed yet), and don't pause for confirmation (read-only check):
+
+```bash
+curl -s http://localhost:1633/status | jq .beeMode
+```
+
+If it returns a `beeMode` value (`ultra-light`, `light`, or `full`), Bee is running → go to **Step 3** with that value.
+
+If the request fails or returns no output, continue to Step 2.
+
+## Step 2 — Check if Bee is installed
+
+Silently look for a Bee binary in common locations. Run these checks without showing the commands to the user:
+
+**All platforms:**
+```bash
+bee version
+```
+
+**Windows (PowerShell):**
+```powershell
+where.exe bee
+Get-Command bee -ErrorAction SilentlyContinue
+Test-Path "$env:APPDATA\bee\bee.exe"
+Test-Path "$env:LOCALAPPDATA\bee\bee.exe"
+Test-Path "$env:PROGRAMFILES\bee\bee.exe"
+Test-Path "$env:PROGRAMFILES(x86)\bee\bee.exe"
+Test-Path "$env:USERPROFILE\.bee\bee.exe"
+Get-Service bee -ErrorAction SilentlyContinue
+```
+
+**Linux/macOS:**
+```bash
+ls /usr/local/bin/bee /usr/bin/bee ~/.bee/bin/bee 2>/dev/null
+systemctl status bee 2>/dev/null
+brew list bee 2>/dev/null
+```
+
+### Route based on findings
+
+**Bee found but not responding at localhost:1633:**
+
+Tell the user:
+> "I detected a Bee installation on your system, but I'm not getting a response from the default endpoint at `http://localhost:1633`. Please start your Bee node and then run `/swarm` again — or, if your node is running on a non-default endpoint, let me know the address and I'll use that instead."
+
+- If they provide a different endpoint: use it in place of `localhost:1633` for all subsequent checks and pass it along to any skill you route to.
+- If they start their node and re-run `/swarm`: continue from Step 1.
+- If they need help or can't get it running: route to `/swarm-troubleshoot`.
+
+**Bee not found anywhere:**
+
+Tell the user Bee doesn't appear to be installed, and let them choose `/swarm-setup-bee-interactive` (guided, step-by-step with verification) or `/swarm-setup-bee` (reference, all steps at once) to set up their node. Briefly explain the difference between the two.
+
+## Step 3 — Bee is running
+
+Use the `beeMode` value from Step 1 — no extra command needed:
+
+- **ultra-light:** Tell the user their node is running in ultra-light mode and uploads won't work. Ask if they want to upgrade to light mode — if yes, route to `/swarm-setup-bee-interactive`. Otherwise, show the menu below (downloads still work).
+- **light or full:** Tell the user their node is ready, then show the menu below and ask what they want to build.
+
+## Step 4 — Show the menu
+
+```
+Welcome! Here's what I can help you with:
+
+🐝 Setup & Infrastructure
+  /swarm-setup-bee-interactive — Install and run a Bee node, step-by-step with verification
+  /swarm-setup-bee             — Install and run a Bee node (reference, all steps at once)
+  /swarm-stamps                — Buy or manage postage stamps (required for uploads)
+  /swarm-troubleshoot          — Diagnose node, connectivity, or upload issues
+
+📦 Store & Retrieve
+  /swarm-upload-download  — Upload and download data, files, or directories
+  /swarm-host-website     — Deploy a website to Swarm (with optional ENS)
+
+🔧 Build
+  /swarm-build-app        — Scaffold a Swarm dApp or add bee-js to your project
+  /swarm-feed             — Create updateable content at a fixed address
+  /swarm-blog             — Build a blog with posts, feeds, and a permanent URL
+
+🔒 Advanced
+  /swarm-act              — Encrypt data with per-account access control
+  /swarm-messaging        — Real-time messaging (GSOC or PSS)
+
+📚 Questions
+  /swarm-docs             — Answer Swarm concepts from the authoritative docs
+```
+
+### Then route
+
+"What are you looking to build?" and route based on their answer:
+
+| They say... | Route to |
+|---|---|
+| "I'm new" / "getting started" / "first time" | `/swarm-setup-bee-interactive` (guided) or `/swarm-setup-bee` (reference) |
+| "upload" / "store data" / "download" | `/swarm-upload-download` |
+| "deploy a website" / "host a site" | `/swarm-host-website` |
+| "build an app" / "scaffold" / "dApp" | `/swarm-build-app` |
+| "feed" / "dynamic content" / "update without changing URL" | `/swarm-feed` |
+| "blog" / "posts" / "publish articles" | `/swarm-blog` |
+| "stamp" / "storage" / "how much does it cost" | `/swarm-stamps` |
+| "encrypt" / "private" / "access control" | `/swarm-act` |
+| "chat" / "messaging" / "real-time" / "notifications" | `/swarm-messaging` |
+| "how does X work" / "explain" / concept question | `/swarm-docs` |
+| "not working" / "error" / "can't connect" | `/swarm-troubleshoot` |
+| "no code" / "just deploy" | Suggest Beeport (beeport.ethswarm.org) — no node needed |
+
+### Quick path check
+
+If still unclear where they are in their journey:
+
+1. **Do you have a Bee node running?** No → `/swarm-setup-bee-interactive` (guided) or `/swarm-setup-bee` (reference)
+2. **Do you have a postage stamp?** No → `/swarm-stamps`
+3. **What do you want to build?** → route to the right skill

worldwatch-0.1.0/.claude/skills/swarm-act/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: swarm-act
+description: Guide to Swarm ACT encryption and access control: create grantees, upload protected data, grant/revoke access, and troubleshoot not-found/history issues.
+user-invocable: true
+---
+
+# Access Control (ACT)
+
+Guide a developer through encrypting data on Swarm and controlling who can read it. ACT (Access Control Trie) lets you define per-account read permissions using Ethereum public keys.
+
+## Formatting
+
+When presenting to the user, use consistent labels before each code block:
+- **Run in your terminal:** — a command the user should execute
+- **Expected output:** — example of what a successful result looks like
+- **Save as `filename`:** — file contents the user should write to disk
+
+Add a `---` horizontal rule before each labeled code block to visually separate it from surrounding text.
+
+---
+
+## Before Starting (run immediately)
+
+Run these checks now and **narrate each one in a short line** — say what you're checking, run it (don't paste the command), then report the result. Don't pause for confirmation; these are read-only checks.
+
+1. **Say "Checking your Bee node…"**, then run:
+   ```bash
+   curl -s http://localhost:1633/status | jq .beeMode
+   ```
+   Reachable → "✓ Node is up." | Fails → "✗ No Bee node running." and offer to walk through `/swarm-setup-bee-interactive`.
+
+2. **Say "Checking for a usable postage stamp…"**, then run:
+   ```bash
+   curl -s http://localhost:1633/stamps | jq '.stamps[] | select(.usable==true) | {batchID, depth, batchTTL}'
+   ```
+   Found → "✓ Found a usable stamp." and proceed. | None → "✗ No usable stamp." and route to `/swarm-stamps`.
+
+## What to Ask
+
+1. **What data are you protecting?** (files, website, app data)
+2. **Who should have access?** (specific Ethereum public keys)
+3. **swarm-cli or bee-js?**
+
+## Prerequisites
+
+- For swarm-cli: `npm install -g @ethersphere/swarm-cli`
+- For bee-js: `npm install @ethersphere/bee-js`
+
+## How ACT Works
+
+- Data is uploaded encrypted — only authorized accounts can decrypt
+- Access is controlled via a **grantee list** of Ethereum public keys
+- The publisher manages the list: add or revoke access at any time
+- Unauthorized download attempts return "not found" — the data is invisible without access
+- The publisher always has access
+
+## Via swarm-cli
+
+### Upload with ACT
+
+```bash
+swarm-cli upload test.txt --act --stamp <BATCH_ID>
+```
+
+First upload — omit `--act-history-address` to create a new history. The response returns:
+- Encrypted Swarm reference
+- History reference
+
+> **Warning:** Save the history reference securely. Losing it means **permanent, irrecoverable loss** of access to your encrypted data. There is no recovery mechanism.
+
+For subsequent uploads to the same history:
+
+```bash
+swarm-cli upload test.txt --act --stamp <BATCH_ID> --act-history-address <HISTORY_REF>
+```
+
+### Download with ACT
+
+```bash
+swarm-cli download <SWARM_HASH> output.txt \
+  --act \
+  --act-history-address <HISTORY_REF> \
+  --act-publisher <PUBLIC_KEY>
+```
+
+- `--act-publisher` — the uploader's public key (needed for decryption). Get it from `swarm-cli addresses` → "Public Key:" field.
+- `--act-timestamp` — optional, defaults to current time. Use to access a specific version.
+
+**Without the ACT flags, the download will fail with "not found".**
+
+### Create a grantee list
+
+Create a JSON file with the public keys of accounts that should have access:
+
+```json
+{
+  "grantees": [
+    "03ec55e9fb2aefb8600f69142abaad79311516c232b28919d66efb4d41bce15bfa",
+    "03fdcab22b455ce08a481d929a4cb9f447752545818eded1ad1785c51581e822c6"
+  ]
+}
+```
+
+```bash
+swarm-cli grantee create grantees.json --stamp <BATCH_ID>
+```
+
+Returns a grantee reference and history reference — save both.
+
+### Update access (add/revoke)
+
+Create a patch JSON:
+
+```json
+{
+  "add": ["03fdcab22b455ce08a481d929a4cb9f447752545818eded1ad1785c51581e822c6"],
+  "revoke": ["03ec55e9fb2aefb8600f69142abaad79311516c232b28919d66efb4d41bce15bfa"]
+}
+```
+
+```bash
+swarm-cli grantee patch grantees-patch.json \
+  --reference <GRANTEE_REF> \
+  --history <GRANTEE_HISTORY_REF> \
+  --stamp <BATCH_ID>
+```
+
+**Note:** Wait at least 1 second between grantee list updates — updating within the same second causes an error.
+
+### View grantee list
+
+```bash
+swarm-cli grantee get <GRANTEE_REF>
+```
+
+## Via bee-js
+
+### Upload with ACT
+
+```javascript
+import { Bee } from '@ethersphere/bee-js'
+
+const bee = new Bee('http://localhost:1633')
+
+// Upload a file with ACT encryption enabled
+const result = await bee.uploadFile(batchId, 'Secret data', 'secret.txt', {
+  act: true
+})
+
+const historyAddress = result.historyAddress.getOrThrow()
+console.log('Encrypted reference:', result.reference.toHex())
+console.log('History address:', historyAddress.toHex())
+// WARNING: Save both — losing the history address means permanent loss of access to encrypted data
+```
+
+### Download with ACT
+
+```javascript
+import { Bee } from '@ethersphere/bee-js'
+
+const bee = new Bee('http://localhost:1633')
+
+// Get the publisher's public key (share this with grantees):
+const publisherAddresses = await bee.getNodeAddresses()
+const publisherPublicKey = publisherAddresses.publicKey  // not pssPublicKey
+
+const file = await bee.downloadFile(encryptedReference, 'secret.txt', {
+  actHistoryAddress: historyAddress,
+  actPublisher: publisherPublicKey
+})
+
+console.log('Decrypted:', file.data.toUtf8())
+// Without ACT parameters, this returns "not found"
+```
+
+> **swarm-cli quirk:** in testing, `swarm-cli download <ref> --act --act-history-address <hist> --act-publisher <pk>` can return 404 even with correct values, while the equivalent Bee HTTP API call (same headers) returns 200. If the CLI download fails, retry via the API or bee-js.
+
+### Manage grantees
+
+```javascript
+import { Bee } from '@ethersphere/bee-js'
+
+const bee = new Bee('http://localhost:1633')
+
+// Create grantee list
+const granteeResult = await bee.createGrantees(batchId, [
+  '03ec55e9fb2aefb8600f69142abaad79311516c232b28919d66efb4d41bce15bfa'
+])
+const granteeReference = granteeResult.ref
+const historyReference = granteeResult.historyref
+console.log('Grantee ref:', granteeReference.toHex())
+console.log('History ref:', historyReference.toHex())
+
+// Get current grantees
+const granteesResult = await bee.getGrantees(granteeReference)
+console.log('Grantees:', granteesResult.grantees.map(k => k.toCompressedHex()))
+
+// Update access — add and revoke
+await bee.patchGrantees(batchId, granteeReference, historyReference, {
+  add: ['03fdcab22b455ce08a481d929a4cb9f447752545818eded1ad1785c51581e822c6'],
+  revoke: ['03ec55e9fb2aefb8600f69142abaad79311516c232b28919d66efb4d41bce15bfa']
+})
+```
+
+## Use Cases
+
+- **Private file sharing** — share documents with specific accounts
+- **Paid content** — grant access after payment
+- **Subscriber-only access** — manage a grantee list for subscribers
+- **Team collaboration** — restrict project data to team members
+
+## Important Notes
+
+- Grantees are identified by their **Ethereum public keys** (compressed, 33 bytes hex)
+- Only the publisher (uploader) can manage the grantee list
+- Revoking access prevents future decryption but doesn't delete already-downloaded data
+- Invalid history addresses return "not found" errors
+- Wait at least 1 second between grantee list updates
+
+## If Something Goes Wrong
+
+| Error | Fix |
+|-------|-----|
+| "not found" on download | Missing ACT flags, wrong history address, or access revoked |
+| "act: invalid history" | Wrong history address — double-check reference |
+| "stamp not usable" | Wait 2-3 minutes after buying |
+| 1-second update error | Wait at least 1 second between grantee list updates |
+| Other errors | Route to `/swarm-troubleshoot` |
+
+## Conceptual Questions
+
+For any conceptual or technical question not covered by the steps above, invoke `/swarm-docs` to find the relevant authoritative source rather than answering from prior knowledge.
+
+## Reference
+
+- ACT guide: https://docs.ethswarm.org/docs/develop/act
+- ACT concepts: https://docs.ethswarm.org/docs/concepts/access-control
+- bee-js docs: https://bee-js.ethswarm.org/docs/
+- swarm-cli: https://github.com/ethersphere/swarm-cli
+