Skip to content

feat: jspod install <app> — one-command Solid app installs - #40

Merged
melvincarvalho merged 1 commit into
gh-pagesfrom
issue-36-install-subcommand
May 17, 2026
Merged

feat: jspod install <app> — one-command Solid app installs#40
melvincarvalho merged 1 commit into
gh-pagesfrom
issue-36-install-subcommand

Conversation

@melvincarvalho

Copy link
Copy Markdown
Contributor

Fixes #36.

What

`jspod install ` replaces the multi-step git-push recipe new users had to copy-paste. Defaults to `github.com/solid-apps/` as the source; one command per app or batch by listing several.

```bash
jspod install chrome # one
jspod install vellum win98 pdf # several
jspod install # curated set: chrome vellum win98 pdf hub
jspod install --pod http://other.pod chrome
jspod install --help
```

How it hides the sharp edges

The manual recipe had three friction points that all bite new users on first use:

  1. Shallow clones get rejected. `git push` from a `--depth=1` clone fails with `shallow update not allowed`. The install does a full clone.
  2. HEAD/branch mismatch. `updateInstead` (which extracts the working tree) only fires when the push targets the branch HEAD points at on the server. JSS 0.0.197+ auto-inits with HEAD=main, but older versions honor the operator's `init.defaultBranch` (often `gh-pages` for GitHub-Pages-heavy users). The install pushes both `HEAD:main` and `HEAD:gh-pages` — whichever matches HEAD extracts; the other just creates a ref. Idempotent on re-run.
  3. Already-bundled apps (pilot). jspod ships pilot at `/public/apps/pilot/` skip-if-exists. Auto-init refuses the push because the path is non-empty. The install translates the cryptic `repository not found` into a friendly `⊘ pilot: skipped` rather than scaring the user.

Verified end-to-end

  • `jspod install pilot` → `⊘ skipped (path already in use)`, exit 0
  • `jspod install alarm` on the running pod (JSS 0.0.196, init.defaultBranch=gh-pages) → `✓ alarm → http://localhost:5444/public/apps/alarm/\`, `index.html` reachable (200) with real content
  • `jspod install --help` shows the subcommand-specific help
  • `jspod --help` mentions `install` so users discover it

Diff

  • `index.js`: +155 LoC (subcommand dispatch, `runInstall`, `printInstallHelp`, main `--help` updated)
  • `README.md`: +14 LoC ("Install Solid apps" section)

Follow-ups (separate issues)

Replaces the multi-step git-push recipe with a single subcommand.
Hides the three sharp edges new users hit on the manual path:

- Full clone (no --depth=1, which gets rejected by git-receive)
- Dual-push (HEAD:main and HEAD:gh-pages) so updateInstead fires
  on any JSS version regardless of init.defaultBranch
- Friendly skip for already-bundled paths like pilot (404 → "skipped")

Defaults to solid-apps/<name> as the source (registry override is
a follow-up, #25/#24). Authenticates via /idp/credentials with me/me
unless overridden via --user / --password / JSS_SINGLE_USER_PASSWORD.

  jspod install chrome
  jspod install vellum win98 pdf
  jspod install                       # curated set
  jspod install --pod http://other.pod chrome

Fixes #36
@melvincarvalho
melvincarvalho merged commit 3ad4870 into gh-pages May 17, 2026
@melvincarvalho
melvincarvalho deleted the issue-36-install-subcommand branch May 17, 2026 10:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add jspod install <app> subcommand

1 participant