create-sia-app 0.1.1

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+
+// src/prompts.ts
+import crypto from "crypto";
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+async function runPrompts() {
+  p.intro(pc.green("Create Sia App"));
+  const projectName = await p.text({
+    message: "What is your project name?",
+    placeholder: "my-sia-app",
+    validate(value) {
+      if (!value.trim()) return "Project name is required";
+      if (!/^[a-z0-9._-]+$/i.test(value.trim()))
+        return "Use only letters, numbers, dashes, dots, and underscores";
+    }
+  });
+  if (p.isCancel(projectName)) {
+    p.cancel("Cancelled.");
+    return null;
+  }
+  const keyChoice = await p.select({
+    message: "App key setup",
+    options: [
+      {
+        value: "generate",
+        label: "Generate a new app key",
+        hint: "Recommended"
+      },
+      { value: "existing", label: "Enter an existing app key" }
+    ]
+  });
+  if (p.isCancel(keyChoice)) {
+    p.cancel("Cancelled.");
+    return null;
+  }
+  let appKey;
+  if (keyChoice === "existing") {
+    const existingKey = await p.text({
+      message: "Enter your app key (64-char hex)",
+      validate(value) {
+        if (!/^[a-f0-9]{64}$/i.test(value.trim()))
+          return "App key must be a 64-character hex string";
+      }
+    });
+    if (p.isCancel(existingKey)) {
+      p.cancel("Cancelled.");
+      return null;
+    }
+    appKey = existingKey.trim();
+  } else {
+    appKey = crypto.randomBytes(32).toString("hex");
+    p.log.info(`Generated app key: ${pc.cyan(appKey)}`);
+  }
+  const indexerUrl = await p.text({
+    message: "Indexer URL",
+    initialValue: "https://app.sia.storage"
+  });
+  if (p.isCancel(indexerUrl)) {
+    p.cancel("Cancelled.");
+    return null;
+  }
+  const appDescription = await p.text({
+    message: "App description (optional)",
+    placeholder: "My decentralized storage app",
+    defaultValue: "A Sia storage app"
+  });
+  if (p.isCancel(appDescription)) {
+    p.cancel("Cancelled.");
+    return null;
+  }
+  return {
+    projectName: projectName.trim(),
+    appKey,
+    indexerUrl: indexerUrl.trim(),
+    appDescription: appDescription.trim() || "A Sia storage app"
+  };
+}
+
+// src/scaffold.ts
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import * as p2 from "@clack/prompts";
+import pc2 from "picocolors";
+var __dirname = path.dirname(fileURLToPath(import.meta.url));
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", ".git"]);
+var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([".wasm", ".png", ".jpg", ".ico", ".svg"]);
+function findTemplateDir() {
+  const published = path.resolve(__dirname, "..", "template");
+  if (fs.existsSync(published)) return published;
+  const local = path.resolve(__dirname, "..", "..", "..", "template");
+  if (fs.existsSync(local)) return local;
+  throw new Error("Could not find template directory");
+}
+function copyDir(src, dest, replacements) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (SKIP_DIRS.has(entry.name)) continue;
+    const srcPath = path.join(src, entry.name);
+    let destName = entry.name;
+    if (destName === "_gitignore") destName = ".gitignore";
+    const destPath = path.join(dest, destName);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath, replacements);
+    } else {
+      const ext = path.extname(entry.name).toLowerCase();
+      if (BINARY_EXTENSIONS.has(ext)) {
+        fs.copyFileSync(srcPath, destPath);
+      } else {
+        let content = fs.readFileSync(srcPath, "utf-8");
+        for (const [search, replace] of replacements) {
+          content = content.replaceAll(search, replace);
+        }
+        fs.writeFileSync(destPath, content);
+      }
+    }
+  }
+}
+function detectPackageManager() {
+  try {
+    execSync("bun --version", { stdio: "ignore" });
+    return "bun";
+  } catch {
+    return "npm";
+  }
+}
+async function scaffold(options) {
+  const { projectName, appKey, indexerUrl, appDescription } = options;
+  const targetDir = path.resolve(process.cwd(), projectName);
+  if (fs.existsSync(targetDir)) {
+    const entries = fs.readdirSync(targetDir);
+    if (entries.length > 0) {
+      p2.log.error(
+        `Directory ${pc2.red(projectName)} already exists and is not empty.`
+      );
+      process.exit(1);
+    }
+  }
+  const spinner2 = p2.spinner();
+  spinner2.start("Creating project...");
+  const templateDir = findTemplateDir();
+  const replacements = [
+    ["{{APP_NAME}}", projectName],
+    ["{{APP_KEY}}", appKey],
+    ["{{INDEXER_URL}}", indexerUrl],
+    ["{{APP_DESCRIPTION}}", appDescription]
+  ];
+  copyDir(templateDir, targetDir, replacements);
+  spinner2.message("Copied template files");
+  const pm = detectPackageManager();
+  spinner2.message(`Installing dependencies with ${pm}...`);
+  try {
+    execSync(`${pm} install`, { cwd: targetDir, stdio: "ignore" });
+    spinner2.stop("Project created successfully");
+  } catch {
+    spinner2.stop("Project created (install failed \u2014 run manually)");
+  }
+  p2.note(
+    [
+      `${pc2.green("cd")} ${projectName}`,
+      `${pc2.green(pm === "bun" ? "bun dev" : "npm run dev")}`
+    ].join("\n"),
+    "Next steps"
+  );
+  p2.outro(pc2.green("Happy building!"));
+}
+
+// src/index.ts
+async function main() {
+  const options = await runPrompts();
+  if (!options) process.exit(0);
+  await scaffold(options);
+}
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "create-sia-app",
+  "version": "0.1.1",
+  "type": "module",
+  "bin": {
+    "create-sia-app": "./dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "template/"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean && rm -rf ./template && cp -r ../../template ./template && rm -rf ./template/node_modules",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "release:patch": "npm version --no-git-tag-version patch && bun run release:push",
+    "release:minor": "npm version --no-git-tag-version minor && bun run release:push",
+    "release:major": "npm version --no-git-tag-version major && bun run release:push",
+    "release:push": "git add package.json && git commit -m \"v$(node -p 'require(\"./package.json\").version')\" && git tag v$(node -p 'require(\"./package.json\").version') && git push && git push --tags"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.10.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsup": "^8.4.0",
+    "typescript": "~5.9.3"
+  }
+}

package/template/CLAUDE.md

@@ -0,0 +1,160 @@
+# Sia Starter — AI Assistant Guide
+
+## Overview
+
+A starter template for building decentralized storage apps on the Sia network. Uses a WASM SDK compiled from Rust to handle encryption, uploads, downloads, and key management.
+
+**Tech stack:** React 19, TypeScript, Vite, Tailwind CSS 4, Zustand, WASM (Rust)
+
+## Architecture
+
+### Auth Flow State Machine
+
+The app uses a step-based auth flow managed by Zustand (`src/stores/auth.ts`):
+
+```
+loading → connect → approve → recovery → connected
+```
+
+- **loading**: WASM initializes, checks for stored app key
+- **connect**: User enters indexer URL, app requests connection
+- **approve**: User visits approval URL in another tab
+- **recovery**: User generates or enters 12-word recovery phrase
+- **connected**: SDK is ready, main app UI renders
+
+### WASM SDK
+
+The SDK (`indexd_wasm`) is a Rust-compiled WASM module that handles:
+- Encrypted file uploads/downloads (erasure coding + encryption)
+- Key derivation from recovery phrases (BIP-39)
+- Object pinning and metadata management
+- Connection auth with indexers
+
+Initialized via `src/lib/sdk.ts`, which wraps the WASM init and re-exports types.
+
+### Zustand Persistence
+
+Auth state persists to localStorage via Zustand's `persist` middleware. The storage key is `{app-name}-auth`. Persisted fields: `storedKeyHex`, `indexerUrl`, `performancePreset`.
+
+## Key Files
+
+| File | Description |
+|------|-------------|
+| `src/lib/sdk.ts` | WASM init + re-exports (AppKey, Builder, SDK, PinnedObject) |
+| `src/lib/constants.ts` | App key, indexer URL, app metadata |
+| `src/lib/hex.ts` | Hex encode/decode utilities |
+| `src/lib/format.ts` | FileMetadata type, formatBytes, formatDate |
+| `src/lib/wasm-env.ts` | `now()` stub for WASM chrono |
+| `src/stores/auth.ts` | Auth state machine + performance presets |
+| `src/components/auth/AuthFlow.tsx` | Auth orchestrator |
+| `src/components/auth/ConnectScreen.tsx` | Indexer connection + CORS fallback |
+| `src/components/auth/ApproveScreen.tsx` | Approval polling |
+| `src/components/auth/RecoveryScreen.tsx` | Recovery phrase generation/import |
+| `src/components/upload/UploadZone.tsx` | File upload dropzone + file list |
+| `src/components/DevNote.tsx` | Developer callout component (remove in production) |
+| `wasm/indexd_wasm/` | Pre-built WASM binary + JS glue + types |
+| `rust/sia-sdk-rs/` | Rust SDK source (cloned on install, gitignored) |
+
+## SDK Usage Patterns
+
+### Upload a file
+
+```ts
+const data = new Uint8Array(arrayBuffer)
+const pinnedObject = await sdk.uploadWithProgress(data, (current, total) => {
+  console.log(`${current}/${total} shards`)
+})
+pinnedObject.updateMetadata(new TextEncoder().encode(JSON.stringify({
+  name: 'file.txt',
+  type: 'text/plain',
+  size: data.byteLength,
+  hash: '...',
+})))
+await sdk.pinObject(pinnedObject)
+await sdk.updateObjectMetadata(pinnedObject)
+```
+
+### Download a file
+
+```ts
+const object = await sdk.object(objectId)
+const data = await sdk.downloadWithProgress(object, (current, total) => {
+  console.log(`${current}/${total} slabs`)
+})
+// data is Uint8Array
+```
+
+### List files
+
+```ts
+const events = await sdk.objectEvents(null, 100)
+for (const event of events) {
+  if (!event.deleted && event.object) {
+    const meta = JSON.parse(new TextDecoder().decode(event.object.metadata()))
+    console.log(meta.name, event.object.size())
+  }
+}
+```
+
+### Delete a file
+
+```ts
+await sdk.deleteObject(objectId)
+```
+
+### Share a file
+
+```ts
+const validUntil = Date.now() + 7 * 24 * 60 * 60 * 1000 // 7 days
+const shareUrl = sdk.shareObject(pinnedObject, validUntil)
+```
+
+### Download shared file
+
+```ts
+const object = await sdk.sharedObject(shareUrl)
+const data = await sdk.download(object)
+```
+
+## Customization
+
+### Change app key
+
+Edit `src/lib/constants.ts`. The app key is a 32-byte hex string that identifies your app to the indexer. Generate one with:
+
+```ts
+crypto.randomBytes(32).toString('hex')
+```
+
+### Replace the upload UI
+
+The post-auth UI is rendered in `src/App.tsx`. Replace `<UploadZone />` with your own component. The SDK is available via `useAuthStore((s) => s.sdk)`.
+
+### Add routes
+
+Install `react-router-dom` and wrap your app. The auth flow should gate all routes.
+
+### Change performance defaults
+
+Edit the `PRESETS` object in `src/stores/auth.ts`.
+
+## WASM / Rust Setup
+
+The `wasm/indexd_wasm/` directory contains pre-built WASM artifacts. The `rust/sia-sdk-rs/` directory is cloned automatically on `bun install` from [alexfreska/sia-sdk-rs](https://github.com/alexfreska/sia-sdk-rs) (branch `alex/wasm-experimental`). To rebuild:
+
+```bash
+cd rust/sia-sdk-rs
+cargo install wasm-pack
+wasm-pack build indexd_wasm --target web --out-dir pkg
+```
+
+Then copy the output to `wasm/indexd_wasm/`.
+
+## Common Commands
+
+```bash
+bun install     # Install dependencies
+bun dev         # Start dev server
+bun run build   # Production build
+bun run check   # Lint with Biome
+```

package/template/README.md

@@ -0,0 +1,102 @@
+# Sia Starter
+
+Build private, encrypted storage apps on the [Sia](https://sia.tech) network. Data is end-to-end encrypted in the browser and transferred directly to and from Sia hosts — no proxies, gateways, or portals. Nobody but the user can see their data.
+
+## Quick Start
+
+```bash
+bun install
+bun dev
+```
+
+Open [http://localhost:5173](http://localhost:5173) in your browser.
+
+## Why Sia
+
+- **Private by default** — All data is encrypted client-side before it leaves the browser. Encryption keys are derived from the user's recovery phrase and never shared.
+- **Direct host connections** — Uploads and downloads happen directly between the browser and Sia hosts over WebTransport. There is no middleman that can see or intercept data.
+- **No trusted third parties** — The indexer service handles payments and trustlessly repairs data so your app doesn't need to run 24/7, but it never sees the encrypted data shards. It can't read, modify, or withhold your files.
+- **Erasure coded** — Data is split into redundant shards across many hosts. Files survive even if individual hosts go offline.
+- **Decentralized** — Storage is provided by a global network of independent hosts competing on price and performance.
+
+## What This Template Includes
+
+- **Full auth flow** — connect to an indexer, approve the connection, set up a recovery phrase
+- **File upload** — drag & drop files, track upload progress, list uploaded files
+- **WASM SDK** — Rust-compiled SDK handles encryption, erasure coding, and direct host transfers in the browser
+- **Developer notes** — amber callout boxes throughout the UI explaining how everything works (remove them when you ship)
+
+## How It Works
+
+### Architecture
+
+```
+Browser (your app)
+  ├── encrypts data client-side
+  ├── erasure codes into shards
+  └── uploads/downloads shards directly to/from Sia hosts (WebTransport)
+
+Indexer service
+  ├── manages payments to hosts
+  ├── tracks which hosts store which shards
+  └── repairs data if hosts go offline
+  └── cannot see encrypted data
+```
+
+### Auth Flow
+
+1. **Connect** — Enter an indexer URL (default: `https://app.sia.storage`). The app sends your app metadata to request a connection.
+2. **Approve** — Visit the approval URL in another tab to authorize your app.
+3. **Recovery Phrase** — Generate a new 12-word phrase or enter an existing one. This deterministically derives all cryptographic keys.
+4. **Connected** — The SDK is ready. Your app key is saved to localStorage for future sessions.
+
+### Upload Flow
+
+Files are encrypted in the browser, erasure coded into shards, and uploaded directly to Sia hosts. The SDK handles all of this — your code just calls `sdk.upload(data)`. Metadata (filename, type, size) is also encrypted and pinned to the indexer.
+
+## Customization
+
+### App Key & Metadata
+
+Edit `src/lib/constants.ts` to set your app key, name, description, and indexer URL.
+
+### Replace the Upload UI
+
+The main post-auth component is `src/components/upload/UploadZone.tsx`. Replace it with your own UI — the SDK is available via:
+
+```tsx
+const sdk = useAuthStore((s) => s.sdk)
+```
+
+### Performance Presets
+
+Edit `src/stores/auth.ts` to change the `PRESETS` object for concurrent operation limits.
+
+## Tech Stack
+
+- [React](https://react.dev) 19
+- [TypeScript](https://www.typescriptlang.org)
+- [Vite](https://vite.dev)
+- [Tailwind CSS](https://tailwindcss.com) 4
+- [Zustand](https://zustand.docs.pmnd.rs) (state management)
+- [Biome](https://biomejs.dev) (linting & formatting)
+- [indexd_wasm](https://github.com/SiaFoundation/sia-sdk-rs) (Sia SDK, compiled from Rust to WASM)
+
+## Project Structure
+
+```
+src/
+├── lib/            # SDK wrapper, constants, utilities
+├── stores/         # Zustand auth store
+└── components/
+    ├── auth/       # Auth flow screens
+    ├── upload/     # Upload dropzone
+    └── DevNote.tsx # Developer callout (remove in production)
+wasm/               # Pre-built WASM binary
+rust/               # Rust SDK source (cloned on install)
+```
+
+## Learn More
+
+- [Sia Documentation](https://docs.sia.tech)
+- [Sia SDK (Rust)](https://github.com/SiaFoundation/sia-sdk-rs)

package/template/_gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+*.local
+.DS_Store
+rust/sia-sdk-rs/

package/template/biome.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.4.1/schema.json",
+  "vcs": {
+    "enabled": false,
+    "clientKind": "git",
+    "useIgnoreFile": false
+  },
+  "files": {
+    "ignoreUnknown": false,
+    "includes": ["src/**", "scripts/**", "vite.config.ts"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "suspicious": {
+        "noArrayIndexKey": "off"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "single",
+      "semicolons": "asNeeded"
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}

package/template/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{APP_NAME}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "{{APP_NAME}}",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "check": "biome check .",
+    "postinstall": "node scripts/setup-rust.js"
+  },
+  "dependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "zustand": "^5.0.11"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.0",
+    "@tailwindcss/vite": "^4.1.18",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "tailwindcss": "^4.1.18",
+    "typescript": "~5.9.3",
+    "vite": "^7.3.1",
+    "vite-plugin-top-level-await": "^1.6.0",
+    "vite-plugin-wasm": "^3.5.0"
+  }
+}

package/template/rust/README.md

@@ -0,0 +1,16 @@
+# Rust SDK Source
+
+The Rust SDK source (`sia-sdk-rs/`) is cloned automatically on `bun install` from [alexfreska/sia-sdk-rs](https://github.com/alexfreska/sia-sdk-rs) (branch `alex/wasm-experimental`).
+
+The pre-built WASM in `../wasm/` is what the app actually uses at runtime. The Rust source is only needed if you want to rebuild the WASM module.
+
+## Rebuilding WASM
+
+```bash
+cd sia-sdk-rs
+cargo install wasm-pack
+wasm-pack build indexd_wasm --target web --out-dir pkg
+cp indexd_wasm/pkg/indexd_wasm_bg.wasm ../../wasm/indexd_wasm/
+cp indexd_wasm/pkg/indexd_wasm.js ../../wasm/indexd_wasm/
+cp indexd_wasm/pkg/indexd_wasm.d.ts ../../wasm/indexd_wasm/
+```

package/template/rust/sia-sdk-rs/.changeset/added_cancel_function_to_cancel_inflight_packed_uploads.md

@@ -0,0 +1,6 @@
+---
+indexd: patch
+indexd_ffi: patch
+---
+
+# Added cancel function to cancel inflight packed uploads.

package/template/rust/sia-sdk-rs/.changeset/check_if_we_have_enough_hosts_prior_to_encoding_in_upload_slabs.md

@@ -0,0 +1,16 @@
+---
+sia_sdk: patch
+indexd: patch
+indexd_ffi: patch
+sia_sdk_derive: patch
+---
+
+# Check if we have enough hosts prior to encoding in upload_slabs
+
+#261 by @Alrighttt
+
+Fixes https://github.com/SiaFoundation/sia-sdk-rs/issues/251
+
+- Added an `available_for_upload` method that returns the amount of known hosts marked `good_for_upload`.
+- Added a check in `upload_slabs` that verifies we have enough good hosts prior to encoding any data. 
+- Adds a variant to `QueueError` for `upload_slabs`'s new failure case. This enables testing for this new case specifically.

package/template/rust/sia-sdk-rs/.changeset/fix_slab_length_in_packed_object.md

@@ -0,0 +1,5 @@
+---
+indexd_ffi: patch
+---
+
+# Fix slab length in packed object

package/template/rust/sia-sdk-rs/.changeset/fix_upload_racing_race_conditon.md

@@ -0,0 +1,13 @@
+---
+indexd: patch
+---
+
+# Fix upload racing race conditon
+
+#258 by @Alrighttt
+
+This fixes a race condition in the upload logic that could happen when the amount of healthy hosts is nearly the same as the amount of shards. This could happen when the racing mechanism was triggered prior to all of the initial shards being assigned a host. The slow hosts would be consumed from the HostQueue without completing the upload. This would cause a latter shard to hit a QueueError::NoMoreHosts error.
+
+This changes the upload behavior so that each shard has a host assigned before any upload begins.
+
+A `set_slow_hosts` method was added to the `MockRHP4Client` to allow easily testing these conditions. This mimics a similar mechanism from the Go SDK.

package/template/rust/sia-sdk-rs/.changeset/improved_parallelism_of_packed_uploads.md

@@ -0,0 +1,5 @@
+---
+indexd_ffi: patch
+---
+
+# Improved parallelism of packed uploads.

package/template/rust/sia-sdk-rs/.changeset/progress_callback_will_now_be_called_as_expected_for_packed_uploads.md

@@ -0,0 +1,5 @@
+---
+indexd_ffi: patch
+---
+
+# Progress callback will now be called as expected for packed uploads.

package/template/rust/sia-sdk-rs/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+- package-ecosystem: cargo
+  directory: "/"
+  schedule:
+    interval: weekly
+  groups:
+    all-dependencies:
+      patterns:
+        - "*"