scripts/bundle-jss.sh + doc fixes from spike

Verified the JSS launch args end-to-end on this dev box:

- Boot args: --single-user --port <p> --host 127.0.0.1 --root <path> --idp
- JSS_SINGLE_USER_PASSWORD env var seeds the IDP account on first run
- All four sentinel endpoints return 200: /, /idp,
  /.well-known/openid-configuration, /profile/card.jsonld
- Loopback bind confirmed (127.0.0.1 only)
- Pod tree (profile/, public/, private/, inbox/, settings/, .idp/) is
  created under --root and nothing leaks elsewhere

Doc fix-ups: the CLI flag is `--root`, not `--data-root` as initially
drafted; --host 127.0.0.1 is now part of the canonical mobile launch
line; ARCHITECTURE.md notes the spike-verified args and adds a
first-run-UX open question for the IDP password.

scripts/bundle-jss.sh produces assets/nodejs-project/ from the published
npm tarball (or `--source <dir>` for a local checkout). Aborts loudly
if any *.node or binding.gyp turn up. Bundle for v0.0.169: ~62 MB,
5444 files. Smoke-tested by booting JSS from the bundled tree before
committing.

Author: melvincarvalho

ARCHITECTURE.md

@@ -41,18 +41,21 @@ Ship a single-tap Android install that runs a personal Solid pod on the phone. T
 1. App `main()` → run Flutter app
 2. Flutter `initState` → call `NodejsMobile.startNodeProject()` with:
    - script: `bin/jss.js`
-   - args: `['start', '--single-user', '--port', '4443', '--data-root', <android-files-dir>/data]`
+   - args: `['start', '--single-user', '--port', '4443', '--host', '127.0.0.1', '--root', '<android-files-dir>/data', '--idp']`
+   - env: `JSS_SINGLE_USER_PASSWORD=<derived-or-prompted>` (only on first launch, to seed the IDP account)
 3. Node thread starts; JSS imports its modules; Fastify binds to `127.0.0.1:4443`
 4. Flutter listens for the "ready" message on the channel (or polls `GET /` until 200) and shows the WebView
 
 ## Data layout on device
 
-- `<android-files-dir>/data/` — JSS pod data (passed via `--data-root` and `DATA_ROOT` env)
-- `<android-files-dir>/data/.idp/` — IDP credentials, keys
-- `<android-files-dir>/.well-known/` — token store, etc.
+- `<android-files-dir>/data/` — JSS pod data (passed via `--root <path>` or `DATA_ROOT` env)
+- `<android-files-dir>/data/.idp/` — IDP credentials, keys (verified by spike: created on first boot)
+- `<android-files-dir>/data/.well-known/` — token store, etc. (when `--idp` is on)
 - `<cache-dir>/` — JSS notification queues, ephemeral state
 
-The pod's filesystem layout is unchanged from desktop JSS — we just point `--data-root` at app-private storage.
+The pod's filesystem layout is unchanged from desktop JSS — we just point `--root` at app-private storage. Verified by booting `jss start --single-user --port 4444 --root /tmp/foo --idp`: full pod tree (profile/, public/, private/, inbox/, settings/, .idp/) is created at the supplied path with nothing leaking to `~/.jss/` or the cwd.
+
+> **Spike note (2026-05-08):** the CLI flag is `-r, --root <path>`, not `--data-root` as initially drafted. The architecture docs and any future Dart launcher should use `--root`.
 
 ## Auth model on a single-user phone pod
 
@@ -78,10 +81,11 @@ The pod's filesystem layout is unchanged from desktop JSS — we just point `--d
 
 ## Open questions
 
-- Does `nodejs-mobile`'s most recent release ship Node ≥ 18? (verify before scaffold, but `engines.node: ">=18.0.0"` is JSS's floor)
+- Does `nodejs-mobile`'s most recent release ship Node ≥ 18? (`engines.node: ">=18.0.0"` is JSS's floor; spike on dev box ran Node 24 with one `oidc-provider` warning about preferring v22 LTS — runtime is *forgiving*, but we should pin the mobile target to whatever Node `nodejs-mobile` ships)
 - Memory ceiling on cheap Android devices (1 GB RAM)? `oidc-provider` is the heaviest dep; might need `--idp` off in a "lite" mode
 - How do we surface the WebID/pod URL outside the app? (Deep link? Share sheet? A "copy URL" button?)
 - Does the foreground-service notification need a stop action wired to a graceful Fastify shutdown? (yes — need to expose this via the plugin channel)
+- First-run UX: where do we surface the IDP password? Options: (a) auto-generate, store in Android Keystore, never show; (b) prompt user; (c) skip IDP entirely on phone (signed-in via did:nostr only)
 
 ## Build & release
 

README.md

@@ -40,7 +40,7 @@ See the [feasibility spike](https://github.com/JavaScriptSolidServer/JavaScriptS
 - [ ] Flutter project scaffold (`flutter create .`)
 - [ ] `nodejs-mobile-flutter` plugin wired in
 - [ ] JSS source bundled as `assets/nodejs-project/`
-- [ ] Boot `bin/jss.js start --single-user --port 4443` on app launch
+- [ ] Boot `bin/jss.js start --single-user --port 4443 --host 127.0.0.1 --root <files-dir>/data --idp` on app launch (CLI surface verified by [spike](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/366#issuecomment-4401585143))
 - [ ] WebView at `http://localhost:4443/`
 - [ ] Foreground service + persistent notification
 - [ ] APK build target (debug + release)

scripts/bundle-jss.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+#
+# bundle-jss.sh — populate assets/nodejs-project/ with a JSS bundle
+#
+# Pulls the published `javascript-solid-server` tarball from npm, installs
+# its production dependencies, and copies the result to assets/nodejs-project/.
+# That directory is then bundled into the APK as nodejs-mobile's project root.
+#
+# Usage:
+#   ./scripts/bundle-jss.sh                  # latest published version
+#   ./scripts/bundle-jss.sh 0.0.169          # a specific version
+#   ./scripts/bundle-jss.sh --source ../JavaScriptSolidServer
+#                                            # bundle from a local checkout (dev)
+#
+# Aborts if any *.node binaries or binding.gyp files turn up in the tree —
+# nodejs-mobile can't load native addons unless they're cross-compiled for
+# Android, and we explicitly want to keep the bundle pure-JS.
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+DEST="$REPO_ROOT/assets/nodejs-project"
+
+SOURCE_DIR=""
+VERSION="latest"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --source)
+      SOURCE_DIR="$2"
+      shift 2
+      ;;
+    -h|--help)
+      sed -n '2,15p' "$0"
+      exit 0
+      ;;
+    *)
+      VERSION="$1"
+      shift
+      ;;
+  esac
+done
+
+TMPDIR="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR"' EXIT
+
+if [[ -n "$SOURCE_DIR" ]]; then
+  if [[ ! -f "$SOURCE_DIR/package.json" ]]; then
+    echo "ERROR: --source path '$SOURCE_DIR' has no package.json" >&2
+    exit 1
+  fi
+  echo "==> Packing local source: $SOURCE_DIR"
+  ( cd "$SOURCE_DIR" && npm pack --pack-destination "$TMPDIR" >/dev/null )
+else
+  echo "==> Pulling javascript-solid-server@$VERSION from npm"
+  ( cd "$TMPDIR" && npm pack "javascript-solid-server@$VERSION" >/dev/null )
+fi
+
+cd "$TMPDIR"
+TARBALL="$(ls javascript-solid-server-*.tgz | head -1)"
+tar -xzf "$TARBALL"
+cd package
+
+echo "==> Installing production dependencies"
+npm install --omit=dev --no-package-lock --no-audit --no-fund >/dev/null
+
+echo "==> Sanity check: no native modules"
+NATIVE_HITS="$(find . \( -name "*.node" -o -name "binding.gyp" \) 2>/dev/null || true)"
+if [[ -n "$NATIVE_HITS" ]]; then
+  echo "ERROR: native modules detected — nodejs-mobile won't load these" >&2
+  echo "$NATIVE_HITS" >&2
+  exit 1
+fi
+
+PKG_VERSION="$(node -p "require('./package.json').version")"
+FILE_COUNT="$(find . -type f | wc -l | tr -d ' ')"
+SIZE="$(du -sh . | cut -f1)"
+
+echo "==> Copying to $DEST"
+mkdir -p "$DEST"
+rm -rf "${DEST:?}"/*
+cp -r bin src package.json node_modules "$DEST/"
+
+cat > "$DEST/.bundle-info" <<EOF
+javascript-solid-server@$PKG_VERSION
+bundled at $(date -u +%Y-%m-%dT%H:%M:%SZ)
+files: $FILE_COUNT
+size: $SIZE
+source: ${SOURCE_DIR:-npm:$VERSION}
+EOF
+
+echo
+echo "Done."
+echo "  Version: $PKG_VERSION"
+echo "  Files:   $FILE_COUNT"
+echo "  Size:    $SIZE"
+echo "  Path:    $DEST"