Generalize "installing apps" into a CLI command: jspod install <source> #24

Context

Pilot is now bundled at /public/apps/pilot/ (PR #20). That worked as a proof of concept that "apps live in pods" is the right pattern: same-origin sign-in, offline-safe, no external CDN dependency. Generalizing this — so jspod can install any Solid app, not just the one we bundle — is the natural next step.

Proposal

A new CLI subcommand:

jspod install <source> [--name <name>] [--force]

Fetches a Solid app's files and writes them to pod-data/public/apps/<name>/. After install:

• The app is reachable at http://localhost:5444/public/apps/<name>/
• It runs same-origin against the user's own pod (no Brave-shield issues)
• It's listed on the new /apps.html landing page (Stage 1 — separate but related, see below)

Sources to support

Honest order of leverage:

1. GitHub shorthand: jspod install solid-apps/penny → clones HEAD of default branch into public/apps/penny/. Most users discover Solid apps via GitHub.
2. Arbitrary git URL: jspod install https://github.com/org/app.git → shallow clone. Same flow as Friction removal: make first-run zero-friction from discovery to working pod #1 but explicit.
3. Tarball URL: jspod install https://example.org/app.tar.gz → fetch + extract. Works for any release artifact.
4. npm package: jspod install npm:some-solid-app → resolve via jsdelivr (same pattern jspod itself uses for solid-oidc + data-browser). Cleanest for versioned distribution.

Name resolution: --name overrides, else infer from the last URL segment (repo name, npm package name, tarball stem).

Update / remove

• Re-running jspod install <source> over an existing install: refuse unless --force (skip-if-exists like current bundled-apps behaviour).
• Remove: rm -rf pod-data/public/apps/<name>/. CLI sugar later if needed.

Manifest convention (Stage 1 — landing on first)

Each app SHOULD ship a manifest.json at its root:

{
  "name": "Pilot",
  "description": "Minimal Solid data browser",
  "version": "0.x",
  "homepage": "https://github.com/solid-apps/pilot",
  "icon": "favicon.png"
}

jspod's /apps.html (Stage 1, separate small PR) scans public/apps/*/manifest.json and renders a tile grid. Apps without a manifest still get a generic tile.

Phasing

1. Stage 1 — Apps landing page + manifest convention. ~1h. Pure pod-data, no new CLI.
2. Stage 2 — jspod install <source> for GitHub + tarball sources (cover most apps). Adds runtime deps for git or HTTP fetch.
3. Stage 3 — npm-resolved sources via jsdelivr.
4. Stage 4 — In-pod "app store" UI that calls the install logic.

Upstream angle

A related JSS issue is being filed about whether the protocol surface should know about installed apps (e.g. a /.well-known/apps endpoint or a Solid-native "App Index" analogous to the Type Index). jspod's install command can run perfectly well without JSS-side support — but if JSS adds an apps primitive, the install command can register against it.

References

• jspod PR feat: bundle Pilot at /public/apps/pilot/ (self-hosted Solid app) #20 — Pilot bundle proof of concept
• jspod#1 — friction-removal arc (apps-in-pod is squarely in this story)
• JSS issue (to be filed alongside this one) — protocol-level apps surface