Context

Sub-issue / focus of #24 (generalize app installation). Most Solid apps live in git repos on GitHub; making git the first-class install source is the highest-leverage move.

We already have git as a dependency of the user workflow (the project repo lives there, contributors push there). Reusing it for app distribution is natural.

Proposed CLI shapes

jspod install solid-apps/penny                # GitHub shorthand → clone default branch
jspod install solid-apps/penny#v2.0           # specific tag / branch / commit
jspod install https://github.com/foo/bar      # full GitHub URL (same as above)
jspod install https://gitlab.com/foo/bar.git  # any git URL
jspod install pilot --upgrade                 # re-fetch a previously-installed app

Implementation sketch

• Resolve the source to a git URL + ref (defaulting to HEAD of the default branch)
• Shallow clone (--depth 1) into pod-data/public/apps/<name>/
• Strip .git/ after clone (keep the install footprint small; the source URL + ref is recorded in a manifest.json for future updates)
• --upgrade re-fetches the same ref (or a newer one if a tag/branch moves)
• Refuse install if target dir exists and isn't a jspod-managed app (presence of manifest.json is the marker)

Manifest written on install

{
  "name": "penny",
  "source": "git",
  "url": "https://github.com/solid-apps/penny",
  "ref": "v2.0",
  "installedAt": "2026-05-16T..."
}

Reused for jspod install <name> --upgrade and for the /apps.html landing page (#24's Stage 1).

Dependencies

• git available in PATH. Cheap to detect; clear error if missing ("install git, or use tarball source").
• No new npm deps if we shell out to git. Adding simple-git or isomorphic-git if pure-Node is desired (~few hundred KB).

Open questions

1. What goes in the cloned tree? The whole repo, or only dist/ / build/ if present? Most Solid apps publish their built bundle to the repo root or to gh-pages; first cut should fetch the default branch root and let the user clean up.
2. Should we honour a package.json "jspod" field for app-author hints (e.g. "install from dist/")?
3. Update strategy: pin to a ref, or always pull HEAD? Pinning is safer; HEAD is nicer for "stay current" users.

References

• jspod#24 — parent issue (generalize app installation, multiple source types)
• JSS#463 — protocol-level apps surface
• JSS issue (filed alongside this one) — git as a recognized app source upstream