javascript-solid-server 0.0.197 → 0.0.199
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -0
- package/bin/jss.js +26 -0
- package/docs/app-install.md +193 -0
- package/package.json +1 -1
- package/src/cli/install.js +417 -0
package/README.md
CHANGED
|
@@ -105,6 +105,7 @@ Full options: [docs/configuration.md](docs/configuration.md)
|
|
|
105
105
|
| Mashlib / SolidOS UI | [docs/mashlib.md](docs/mashlib.md) |
|
|
106
106
|
| WebSocket Notifications | [docs/notifications.md](docs/notifications.md) |
|
|
107
107
|
| Git Support | [docs/git-support.md](docs/git-support.md) |
|
|
108
|
+
| Installing Apps | [docs/app-install.md](docs/app-install.md) |
|
|
108
109
|
| Nostr Relay | [docs/nostr.md](docs/nostr.md) |
|
|
109
110
|
| ActivityPub & Mastodon API | [docs/activitypub.md](docs/activitypub.md) |
|
|
110
111
|
| remoteStorage | [docs/remotestorage.md](docs/remotestorage.md) |
|
package/bin/jss.js
CHANGED
|
@@ -307,6 +307,32 @@ program
|
|
|
307
307
|
}
|
|
308
308
|
});
|
|
309
309
|
|
|
310
|
+
/**
|
|
311
|
+
* Install command — install a Solid app from the default registry
|
|
312
|
+
* (`github.com/solid-apps/<name>`) into a running pod.
|
|
313
|
+
*
|
|
314
|
+
* Phase 1 of #464 / scoped in #478. Hardcodes the default registry;
|
|
315
|
+
* later phases add <org>/<repo>, full URLs, refs, renames, did:nostr
|
|
316
|
+
* resolution, NIP-98 auth, curated default sets, and --bundle.
|
|
317
|
+
*/
|
|
318
|
+
program
|
|
319
|
+
.command('install [names...]')
|
|
320
|
+
.description('Install a Solid app (or a bundle of apps) into a running pod')
|
|
321
|
+
.option('--pod <url>', 'Target pod URL', 'http://localhost:4443')
|
|
322
|
+
.option('--user <name>', 'Username for IDP auth', 'me')
|
|
323
|
+
.option('--password <pw>', 'Password (default: $JSS_SINGLE_USER_PASSWORD or "me")')
|
|
324
|
+
.option('--nostr-privkey <hex>', 'Sign install pushes with NIP-98 using this 64-char hex Nostr privkey instead of fetching a bearer token (default: $NOSTR_PRIVKEY)')
|
|
325
|
+
.option('--bundle <source>', 'Install everything in a bundle (JSON-LD doc). Source: bare name → solid-apps/bundles, <org>/<repo>, https://..., or a local path')
|
|
326
|
+
.action(async (names, options) => {
|
|
327
|
+
try {
|
|
328
|
+
const { runInstall } = await import('../src/cli/install.js');
|
|
329
|
+
await runInstall(names, options);
|
|
330
|
+
} catch (err) {
|
|
331
|
+
// runInstall prints its own per-app error lines; we just exit non-zero.
|
|
332
|
+
process.exit(1);
|
|
333
|
+
}
|
|
334
|
+
});
|
|
335
|
+
|
|
310
336
|
/**
|
|
311
337
|
* Init command - interactive configuration
|
|
312
338
|
*/
|
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
# Installing Apps
|
|
2
|
+
|
|
3
|
+
JSS ships a built-in `install` subcommand that pulls a Solid app from a git repo and pushes it into your running pod at `/public/apps/<name>/`. One command, no clone-and-push dance, no token plumbing — the hard parts (git auto-init, ACL-gated push, working-tree extraction via `updateInstead`) are handled by the same git HTTP backend JSS already uses.
|
|
4
|
+
|
|
5
|
+
## Quick start
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
jss start --provision-keys & # pod running on http://localhost:4443
|
|
9
|
+
jss install chrome # installs solid-apps/chrome → /public/apps/chrome/
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
Open `http://localhost:4443/public/apps/chrome/` in a browser. That's it.
|
|
13
|
+
|
|
14
|
+
## App specs
|
|
15
|
+
|
|
16
|
+
The argument to `install` accepts five forms:
|
|
17
|
+
|
|
18
|
+
| Input | Resolves to | Pod path |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| `chrome` | `github.com/solid-apps/chrome` (default registry) | `/public/apps/chrome/` |
|
|
21
|
+
| `JavaScriptSolidServer/git` | `github.com/JavaScriptSolidServer/git` | `/public/apps/git/` |
|
|
22
|
+
| `https://github.com/foo/bar` | as-is | `/public/apps/bar/` |
|
|
23
|
+
| `chrome#v1` | `github.com/solid-apps/chrome` at ref `v1` | `/public/apps/chrome/` |
|
|
24
|
+
| `litecut/litecut.github.io=litecut` | `github.com/litecut/litecut.github.io`, renamed | `/public/apps/litecut/` |
|
|
25
|
+
|
|
26
|
+
Two optional suffixes apply to any form:
|
|
27
|
+
|
|
28
|
+
- **`#<branch-or-tag>`** — pin a ref. Uses `git clone --branch <ref>` under the hood.
|
|
29
|
+
- **`=<name>`** — override the pod-path name. Useful when the repo's last segment isn't what you want under `/public/apps/`.
|
|
30
|
+
|
|
31
|
+
Multiple specs in one command:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
jss install chrome vellum pdf hub
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Each is installed independently; per-app `✓` / `⊘` / `✗` status, exit non-zero if any failed.
|
|
38
|
+
|
|
39
|
+
## Authentication
|
|
40
|
+
|
|
41
|
+
The install needs write access on the target pod. Two paths:
|
|
42
|
+
|
|
43
|
+
### Bearer token (default)
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
jss install chrome --user me --password me
|
|
47
|
+
# or via env (keeps the secret out of shell history):
|
|
48
|
+
JSS_SINGLE_USER_PASSWORD=secret jss install chrome
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
`POST <pod>/idp/credentials` returns a token, which is sent as `Authorization: Bearer ...` on each push.
|
|
52
|
+
|
|
53
|
+
If the pod runs in `--public` mode (no IDP), no token is fetched; writes are unauthenticated.
|
|
54
|
+
|
|
55
|
+
### Nostr (NIP-98)
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
jss install chrome --nostr-privkey <64-hex>
|
|
59
|
+
# or via env:
|
|
60
|
+
NOSTR_PRIVKEY=<64-hex> jss install chrome
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Each push is signed with a NIP-98 event (Schnorr signature on a `kind: 27235` Nostr event). JSS verifies the signature, derives a `did:nostr:<pubkey>` identity, and runs WAC against that.
|
|
64
|
+
|
|
65
|
+
Pairs naturally with `--provision-keys`: the privkey JSS auto-generates at `<pod>/private/privkey.jsonld` is the natural source.
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
jss start --provision-keys &
|
|
69
|
+
PRIVKEY=$(jq -r .secretKeyMultibase pod-data/private/privkey.jsonld | sed 's/^f8126//')
|
|
70
|
+
NOSTR_PRIVKEY=$PRIVKEY jss install chrome
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
The target ACL must grant the corresponding pubkey:
|
|
74
|
+
|
|
75
|
+
```turtle
|
|
76
|
+
<#owner> a acl:Authorization;
|
|
77
|
+
acl:agent <did:nostr:59427bb1...>;
|
|
78
|
+
acl:accessTo <./>;
|
|
79
|
+
acl:default <./>;
|
|
80
|
+
acl:mode acl:Read, acl:Write, acl:Control.
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
This is typically already true on a `--provision-keys` pod — JSS seeds the owner ACL to grant the provisioned key.
|
|
84
|
+
|
|
85
|
+
## Targeting a different pod
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
jss install chrome --pod http://192.168.1.10:5544
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Default is `http://localhost:4443`. Auth flags apply against the chosen pod.
|
|
92
|
+
|
|
93
|
+
## Bundles
|
|
94
|
+
|
|
95
|
+
`--bundle <source>` installs a set of apps from a JSON-LD manifest. Same auth, same target, same per-app status.
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
jss install --bundle starter # solid-apps/bundles/HEAD/starter.jsonld
|
|
99
|
+
jss install --bundle media chrome # bundle + ad-hoc additions
|
|
100
|
+
jss install --bundle ./my-stack.jsonld # local file
|
|
101
|
+
jss install --bundle https://my.pod/bundles/dev.jsonld
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### Source resolution
|
|
105
|
+
|
|
106
|
+
| Input | Resolves to |
|
|
107
|
+
|---|---|
|
|
108
|
+
| `--bundle starter` | `https://raw.githubusercontent.com/solid-apps/bundles/HEAD/starter.jsonld` |
|
|
109
|
+
| `--bundle <org>/<repo>` | `https://raw.githubusercontent.com/<org>/<repo>/HEAD/bundle.jsonld` |
|
|
110
|
+
| `--bundle https://...` | fetch as-is |
|
|
111
|
+
| `--bundle ./path.jsonld` | local filesystem (absolute paths supported) |
|
|
112
|
+
|
|
113
|
+
`/HEAD/` resolves to the repo's default branch — works for both `gh-pages`-default repos (solid-apps convention) and `main`-default repos.
|
|
114
|
+
|
|
115
|
+
### Bundle format
|
|
116
|
+
|
|
117
|
+
JSON-LD `schema:ItemList`:
|
|
118
|
+
|
|
119
|
+
```json
|
|
120
|
+
{
|
|
121
|
+
"@context": { "schema": "https://schema.org/", "app": "urn:jss:app:" },
|
|
122
|
+
"@id": "#bundle",
|
|
123
|
+
"@type": "schema:ItemList",
|
|
124
|
+
"schema:name": "Starter",
|
|
125
|
+
"schema:description": "Minimal pleasant first-run set",
|
|
126
|
+
"schema:itemListElement": [
|
|
127
|
+
"chrome",
|
|
128
|
+
"vellum",
|
|
129
|
+
{ "app:spec": "litecut/litecut.github.io=litecut", "app:label": "Litecut" }
|
|
130
|
+
]
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Each item is either:
|
|
135
|
+
|
|
136
|
+
- A **bare string** — any spec `jss install` accepts
|
|
137
|
+
- An **object** — required `app:spec`, optional `app:label` / `app:description` for UI tooling
|
|
138
|
+
|
|
139
|
+
### Curated bundles
|
|
140
|
+
|
|
141
|
+
The [`solid-apps/bundles`](https://github.com/solid-apps/bundles) repo hosts ready-made bundles:
|
|
142
|
+
|
|
143
|
+
| Bundle | Apps |
|
|
144
|
+
|---|---|
|
|
145
|
+
| `starter` | chrome, vellum, pdf, alarm |
|
|
146
|
+
| `all` | chrome, vellum, win98, pdf, hub, alarm, playlist |
|
|
147
|
+
| `media` | playlist, pdf |
|
|
148
|
+
| `productivity` | vellum, hub, win98 |
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
jss install --bundle starter
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### Sharing custom bundles
|
|
155
|
+
|
|
156
|
+
Bundles are JSON-LD documents — they live anywhere a JSON-LD doc can. Host yours on your pod, in a GitHub repo, or any static server:
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
jss install --bundle https://my.pod/bundles/dev-stack.jsonld
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
ACL-gated, version-controlled (if in git), pointable from a single URL.
|
|
163
|
+
|
|
164
|
+
## How it works
|
|
165
|
+
|
|
166
|
+
Under the hood, `jss install <name>` is:
|
|
167
|
+
|
|
168
|
+
1. **Resolve** the spec to a source URL (`github.com/solid-apps/chrome` for bare names).
|
|
169
|
+
2. **Authenticate.** Fetch a bearer token from `<pod>/idp/credentials`, OR build a NIP-98 signed event if `--nostr-privkey` is set. Skipped entirely if the pod is in `--public` mode.
|
|
170
|
+
3. **Clone** the repo to a temp directory. Full clone — no `--depth`, because shallow pushes are rejected by `git-receive-pack`.
|
|
171
|
+
4. **Dual push** to `<pod>/public/apps/<name>` on both `HEAD:main` and `HEAD:gh-pages`. JSS auto-inits the destination repo, and whichever ref matches the server-side HEAD triggers `receive.denyCurrentBranch updateInstead` to extract the working tree onto disk where JSS serves it as static resources. The other ref is a harmless stranded reference.
|
|
172
|
+
5. **Clean up** the temp directory.
|
|
173
|
+
|
|
174
|
+
Idempotent on re-run. Skip-on-existing-non-repo paths (e.g. jspod's bundled `pilot`) report a friendly `⊘ skipped` instead of an error.
|
|
175
|
+
|
|
176
|
+
## Troubleshooting
|
|
177
|
+
|
|
178
|
+
| Symptom | Cause | Fix |
|
|
179
|
+
|---|---|---|
|
|
180
|
+
| `✗ <name>: invalid app name "..."` | Spec doesn't match the validation regex | Check the spec; review the [App specs](#app-specs) table |
|
|
181
|
+
| `✗ <name>: clone failed: Repository not found` | The repo doesn't exist at the resolved URL | Verify the source — `github.com/solid-apps/<name>` for bare names |
|
|
182
|
+
| `✗ <name>: push failed: shallow update not allowed` | A manual clone-and-push used `--depth=1` (the install itself never does this) | Remove `--depth` from the clone |
|
|
183
|
+
| `✗ <name>: push failed: HTTP 401` | Auth failed | Check `--user` / `--password`; for Nostr, check that the ACL grants the pubkey |
|
|
184
|
+
| `✗ <name>: push failed: HTTP 413` | Body exceeds JSS's `bodyLimit` (10 MB) | Tracked as [JSS#474](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/474). Workaround: install a smaller repo or push a no-history snapshot |
|
|
185
|
+
| Working tree empty (`/public/apps/<name>/index.html` returns 404) | Server-side HEAD doesn't match the pushed branch | JSS 0.0.197+ pins `-b main` on auto-init; upgrade if you see this |
|
|
186
|
+
| `⊘ <name>: skipped (path already in use)` | The target path has content but no `.git/` (e.g. jspod's bundled `pilot`) | Expected — JSS refuses to clobber non-repo content |
|
|
187
|
+
|
|
188
|
+
## See also
|
|
189
|
+
|
|
190
|
+
- [Git Support](./git-support.md) — the substrate that powers `install`
|
|
191
|
+
- [`jss install` source](../src/cli/install.js)
|
|
192
|
+
- [solid-apps/bundles](https://github.com/solid-apps/bundles) — curated bundle repo
|
|
193
|
+
- [Phased plan (JSS#464)](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/464) — design roadmap; Phases 3 (`--did`) and 5 (curated no-arg default) still ahead
|
package/package.json
CHANGED
|
@@ -0,0 +1,417 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `jss install <name>` — install a Solid app into a running pod.
|
|
3
|
+
*
|
|
4
|
+
* Phase 1 of #464 (see #478 for the scoped issue). Hardcodes the
|
|
5
|
+
* default registry to `github.com/solid-apps/<name>`. Later phases
|
|
6
|
+
* add `<org>/<repo>` shorthand, full URLs, `#<ref>` pinning,
|
|
7
|
+
* `=<name>` rename, `--did` resolution, `--nostr-privkey` NIP-98
|
|
8
|
+
* auth, a curated default set, and `--bundle`.
|
|
9
|
+
*
|
|
10
|
+
* The install is a thin shell over the auto-init + updateInstead +
|
|
11
|
+
* regular-repo machinery already in `src/handlers/git.js`:
|
|
12
|
+
*
|
|
13
|
+
* 1. POST <pod>/idp/credentials with the supplied creds → bearer token
|
|
14
|
+
* 2. `git clone <source> /tmp/<name>` (full clone — shallow pushes
|
|
15
|
+
* are rejected by JSS git-receive)
|
|
16
|
+
* 3. Push the clone to `<pod>/public/apps/<name>` with the bearer
|
|
17
|
+
* header, on BOTH `HEAD:main` and `HEAD:gh-pages` so it works
|
|
18
|
+
* regardless of the operator's `init.defaultBranch`. Whichever
|
|
19
|
+
* matches server-side HEAD triggers `updateInstead` and extracts
|
|
20
|
+
* the working tree; the other creates a stranded ref.
|
|
21
|
+
*
|
|
22
|
+
* Idempotent on re-run (existing repo at the path accepts the push
|
|
23
|
+
* normally). Skip-on-existing-non-repo translates auto-init's
|
|
24
|
+
* "won't init a non-empty path" 404 into a friendly message.
|
|
25
|
+
*/
|
|
26
|
+
|
|
27
|
+
import { spawnSync } from 'child_process';
|
|
28
|
+
import { existsSync, readFileSync } from 'fs';
|
|
29
|
+
import { join, isAbsolute } from 'path';
|
|
30
|
+
import { nip98Token } from '../nostr/event.js';
|
|
31
|
+
|
|
32
|
+
// ANSI helpers — keep zero-dep so this works in any embedded usage.
|
|
33
|
+
const c = (n) => (s) => `\x1b[${n}m${s}\x1b[0m`;
|
|
34
|
+
const green = c(32);
|
|
35
|
+
const yellow = c(33);
|
|
36
|
+
const red = c(31);
|
|
37
|
+
const dim = c(2);
|
|
38
|
+
const bold = c(1);
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Parse an app spec. Accepts (Phase 2 of #464):
|
|
42
|
+
* - bare name → github.com/solid-apps/<name> (default registry)
|
|
43
|
+
* - "<org>/<repo>" → github.com/<org>/<repo>
|
|
44
|
+
* - "https://..." full URL → as-is (must point at a git repo)
|
|
45
|
+
* Each form may carry an optional "#<ref>" suffix to pin a tag or branch:
|
|
46
|
+
* chrome#v1.2 / solid-apps/chrome#main / https://...#v2
|
|
47
|
+
* And an optional "=<name>" suffix to override the pod-path name:
|
|
48
|
+
* litecut/litecut.github.io=litecut
|
|
49
|
+
*/
|
|
50
|
+
function parseAppSpec(input) {
|
|
51
|
+
// Pull off the rename suffix first, then the ref suffix.
|
|
52
|
+
let base = input;
|
|
53
|
+
let renameName = null;
|
|
54
|
+
const eqIx = base.lastIndexOf('=');
|
|
55
|
+
if (eqIx > 0) {
|
|
56
|
+
renameName = base.slice(eqIx + 1);
|
|
57
|
+
base = base.slice(0, eqIx);
|
|
58
|
+
}
|
|
59
|
+
let ref = null;
|
|
60
|
+
const hashIx = base.lastIndexOf('#');
|
|
61
|
+
if (hashIx > 0) {
|
|
62
|
+
ref = base.slice(hashIx + 1) || null;
|
|
63
|
+
base = base.slice(0, hashIx);
|
|
64
|
+
}
|
|
65
|
+
let source, name;
|
|
66
|
+
if (/^https?:\/\//.test(base)) {
|
|
67
|
+
source = base.replace(/\.git$/, '').replace(/\/$/, '');
|
|
68
|
+
name = source.split('/').pop();
|
|
69
|
+
} else if (base.includes('/')) {
|
|
70
|
+
const cleaned = base.replace(/\.git$/, '').replace(/^\/+|\/+$/g, '');
|
|
71
|
+
if (cleaned.split('/').length !== 2) {
|
|
72
|
+
return { error: 'expected <org>/<repo> shorthand' };
|
|
73
|
+
}
|
|
74
|
+
source = `https://github.com/${cleaned}`;
|
|
75
|
+
name = cleaned.split('/').pop();
|
|
76
|
+
} else {
|
|
77
|
+
source = `https://github.com/solid-apps/${base}`;
|
|
78
|
+
name = base;
|
|
79
|
+
}
|
|
80
|
+
if (renameName) name = renameName;
|
|
81
|
+
if (!/^[a-z0-9][a-z0-9_.-]*$/i.test(name)) {
|
|
82
|
+
return { error: `invalid pod-path name "${name}"` };
|
|
83
|
+
}
|
|
84
|
+
if (ref && !/^[a-z0-9][a-z0-9_./-]*$/i.test(ref)) {
|
|
85
|
+
return { error: `invalid ref "${ref}"` };
|
|
86
|
+
}
|
|
87
|
+
return { source, name, ref };
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* Resolve a `--bundle` source string to either a fully-qualified URL
|
|
92
|
+
* or an absolute local-file path.
|
|
93
|
+
*
|
|
94
|
+
* --bundle media → github.com/solid-apps/bundles/HEAD/media.jsonld
|
|
95
|
+
* --bundle <org>/<repo> → github.com/<org>/<repo>/HEAD/bundle.jsonld
|
|
96
|
+
* --bundle https://... → as-is (must end in a JSON-LD doc)
|
|
97
|
+
* --bundle ./path or /abs/path → absolute local-file path
|
|
98
|
+
*
|
|
99
|
+
* Returns { url } or { path } or { error }.
|
|
100
|
+
*/
|
|
101
|
+
function resolveBundleSource(input) {
|
|
102
|
+
if (!input || typeof input !== 'string') {
|
|
103
|
+
return { error: 'bundle source is required' };
|
|
104
|
+
}
|
|
105
|
+
if (/^https?:\/\//.test(input)) {
|
|
106
|
+
return { url: input };
|
|
107
|
+
}
|
|
108
|
+
if (input.startsWith('./') || input.startsWith('../') || isAbsolute(input) || input.startsWith('~/')) {
|
|
109
|
+
const path = input.startsWith('~/')
|
|
110
|
+
? join(process.env.HOME || '', input.slice(2))
|
|
111
|
+
: (isAbsolute(input) ? input : join(process.cwd(), input));
|
|
112
|
+
return { path };
|
|
113
|
+
}
|
|
114
|
+
// Bare names + <org>/<repo> shorthand. We hit raw.githubusercontent.com
|
|
115
|
+
// so the response is the raw JSON-LD body (no HTML wrapper).
|
|
116
|
+
if (input.includes('/')) {
|
|
117
|
+
const cleaned = input.replace(/\.git$/, '').replace(/^\/+|\/+$/g, '');
|
|
118
|
+
if (cleaned.split('/').length !== 2) {
|
|
119
|
+
return { error: 'expected <org>/<repo> shorthand for bundle source' };
|
|
120
|
+
}
|
|
121
|
+
return { url: `https://raw.githubusercontent.com/${cleaned}/HEAD/bundle.jsonld` };
|
|
122
|
+
}
|
|
123
|
+
if (!/^[a-z0-9][a-z0-9_.-]*$/i.test(input)) {
|
|
124
|
+
return { error: `invalid bundle name "${input}"` };
|
|
125
|
+
}
|
|
126
|
+
return { url: `https://raw.githubusercontent.com/solid-apps/bundles/HEAD/${input}.jsonld` };
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* Fetch + parse a bundle into a normalized list of app-spec strings.
|
|
131
|
+
*
|
|
132
|
+
* Returns { name, description, items } or { error }.
|
|
133
|
+
*
|
|
134
|
+
* Items are normalized: each becomes the string-form spec the caller
|
|
135
|
+
* feeds to `parseAppSpec`. Object items with `app:spec` are unwrapped
|
|
136
|
+
* to their spec string; the optional label/description are ignored
|
|
137
|
+
* by the install path (they're for UI tooling that consumes bundles).
|
|
138
|
+
*/
|
|
139
|
+
async function loadBundle(resolved) {
|
|
140
|
+
let body;
|
|
141
|
+
try {
|
|
142
|
+
if (resolved.path) {
|
|
143
|
+
if (!existsSync(resolved.path)) {
|
|
144
|
+
return { error: `bundle file not found: ${resolved.path}` };
|
|
145
|
+
}
|
|
146
|
+
body = readFileSync(resolved.path, 'utf8');
|
|
147
|
+
} else {
|
|
148
|
+
const r = await fetch(resolved.url);
|
|
149
|
+
if (!r.ok) return { error: `bundle fetch failed: HTTP ${r.status} on ${resolved.url}` };
|
|
150
|
+
body = await r.text();
|
|
151
|
+
}
|
|
152
|
+
} catch (e) {
|
|
153
|
+
return { error: `could not read bundle: ${e.message}` };
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
let doc;
|
|
157
|
+
try {
|
|
158
|
+
doc = JSON.parse(body);
|
|
159
|
+
} catch (e) {
|
|
160
|
+
return { error: `bundle is not valid JSON: ${e.message}` };
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
// Items live under `schema:itemListElement` (preferred) or the
|
|
164
|
+
// un-prefixed `itemListElement` (common when @context aliases it).
|
|
165
|
+
const rawItems = doc['schema:itemListElement']
|
|
166
|
+
?? doc['itemListElement']
|
|
167
|
+
?? doc['items'] // also accept a loose `items` key for hand-written bundles
|
|
168
|
+
?? null;
|
|
169
|
+
if (!Array.isArray(rawItems) || rawItems.length === 0) {
|
|
170
|
+
return { error: 'bundle has no items (expected schema:itemListElement array)' };
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
const items = [];
|
|
174
|
+
for (const it of rawItems) {
|
|
175
|
+
if (typeof it === 'string') {
|
|
176
|
+
items.push(it);
|
|
177
|
+
} else if (it && typeof it === 'object') {
|
|
178
|
+
const spec = it['app:spec'] || it['spec'] || it['urn:jss:app:spec'];
|
|
179
|
+
if (typeof spec !== 'string') {
|
|
180
|
+
return { error: `bundle item missing app:spec: ${JSON.stringify(it).slice(0, 100)}` };
|
|
181
|
+
}
|
|
182
|
+
items.push(spec);
|
|
183
|
+
} else {
|
|
184
|
+
return { error: `bundle item must be a string or object, got: ${typeof it}` };
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
return {
|
|
189
|
+
name: doc['schema:name'] || doc.name || null,
|
|
190
|
+
description: doc['schema:description'] || doc.description || null,
|
|
191
|
+
items
|
|
192
|
+
};
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
/**
|
|
196
|
+
* Fetch a bearer token from the pod's IDP, or null if the pod runs
|
|
197
|
+
* with `--public` (no auth required for writes).
|
|
198
|
+
*/
|
|
199
|
+
async function fetchToken({ pod, user, password }) {
|
|
200
|
+
// First check whether the pod accepts unauthenticated writes — if so,
|
|
201
|
+
// we don't need a token. Probe with HEAD on /public/ (which any pod
|
|
202
|
+
// exposes); if writes there require auth, we'll need the token.
|
|
203
|
+
// For Phase 1 we just always try to fetch a token; if the IDP isn't
|
|
204
|
+
// running, we fall through with a clear error.
|
|
205
|
+
try {
|
|
206
|
+
const r = await fetch(`${pod}/idp/credentials`, {
|
|
207
|
+
method: 'POST',
|
|
208
|
+
headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
|
|
209
|
+
body: new URLSearchParams({ username: user, password })
|
|
210
|
+
});
|
|
211
|
+
if (r.status === 404) {
|
|
212
|
+
// No IDP — pod is likely in --public mode. Proceed without a token.
|
|
213
|
+
return null;
|
|
214
|
+
}
|
|
215
|
+
if (!r.ok) throw new Error(`HTTP ${r.status}`);
|
|
216
|
+
const j = await r.json();
|
|
217
|
+
if (!j.access_token) throw new Error('no access_token in response');
|
|
218
|
+
return j.access_token;
|
|
219
|
+
} catch (e) {
|
|
220
|
+
throw new Error(`Could not authenticate against ${pod}: ${e.message}`);
|
|
221
|
+
}
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
/**
|
|
225
|
+
* Install one app spec to one pod. Returns a status object the caller
|
|
226
|
+
* uses for per-app output + exit-code aggregation.
|
|
227
|
+
*/
|
|
228
|
+
async function installOne({ spec, pod, token, nostrPrivkey }) {
|
|
229
|
+
const { source, name, ref } = spec;
|
|
230
|
+
const dest = `${pod}/public/apps/${name}`;
|
|
231
|
+
const tmp = join('/tmp', `jss-install-${name}-${process.pid}`);
|
|
232
|
+
|
|
233
|
+
// Clean any stale tmp from a prior failed run.
|
|
234
|
+
if (existsSync(tmp)) spawnSync('rm', ['-rf', tmp], { stdio: 'ignore' });
|
|
235
|
+
|
|
236
|
+
// Clone (no --depth: shallow pushes are rejected by JSS git-receive).
|
|
237
|
+
// --branch picks a tag or branch when pinned (e.g. `foo/bar#v2`).
|
|
238
|
+
const cloneArgs = ['clone', '--quiet'];
|
|
239
|
+
if (ref) cloneArgs.push('--branch', ref);
|
|
240
|
+
cloneArgs.push(source, tmp);
|
|
241
|
+
const clone = spawnSync('git', cloneArgs, {
|
|
242
|
+
stdio: ['ignore', 'pipe', 'pipe']
|
|
243
|
+
});
|
|
244
|
+
if (clone.status !== 0) {
|
|
245
|
+
const err = clone.stderr?.toString?.().trim() || '';
|
|
246
|
+
return { name, status: 'failed', reason: `clone failed${err ? `: ${err.slice(0, 300)}` : ''}` };
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
// Build the Authorization header for the push. NIP-98 (Phase 4)
|
|
250
|
+
// signs a Nostr event with the user's Schnorr key — no IDP creds
|
|
251
|
+
// needed; JSS verifies via src/auth/token.js and returns a
|
|
252
|
+
// did:nostr:<hex> identity for ACL matching.
|
|
253
|
+
//
|
|
254
|
+
// Git makes BOTH an advertise GET (`info/refs?service=git-receive-pack`)
|
|
255
|
+
// and a receive POST (`git-receive-pack`) on the same http.extraHeader.
|
|
256
|
+
// JSS is lenient for git clients (src/auth/nostr.js): it accepts a
|
|
257
|
+
// NIP-98 event whose `u` is a prefix of the request URL, and whose
|
|
258
|
+
// `method` is `*` as a wildcard. Sign the base URL with method `*`
|
|
259
|
+
// so the same event passes auth on both requests.
|
|
260
|
+
const authHeader = () => {
|
|
261
|
+
if (nostrPrivkey) {
|
|
262
|
+
const b64 = nip98Token(dest, '*', nostrPrivkey);
|
|
263
|
+
return `Authorization: Nostr ${b64}`;
|
|
264
|
+
}
|
|
265
|
+
if (token) return `Authorization: Bearer ${token}`;
|
|
266
|
+
return null;
|
|
267
|
+
};
|
|
268
|
+
|
|
269
|
+
// Dual push: HEAD:main and HEAD:gh-pages. Whichever matches server-
|
|
270
|
+
// side HEAD triggers updateInstead and extracts the working tree.
|
|
271
|
+
// The other just creates a stranded ref (harmless). Idempotent.
|
|
272
|
+
// Each push gets a freshly-signed NIP-98 event (the signature is
|
|
273
|
+
// tied to a specific u + method + timestamp window).
|
|
274
|
+
const pushArgs = (branch) => {
|
|
275
|
+
const args = ['-C', tmp];
|
|
276
|
+
const auth = authHeader();
|
|
277
|
+
if (auth) args.push('-c', `http.extraHeader=${auth}`);
|
|
278
|
+
args.push('push', dest, `HEAD:${branch}`);
|
|
279
|
+
return args;
|
|
280
|
+
};
|
|
281
|
+
|
|
282
|
+
const pushMain = spawnSync('git', pushArgs('main'), { stdio: ['ignore', 'pipe', 'pipe'] });
|
|
283
|
+
const errMain = pushMain.stderr?.toString?.() || '';
|
|
284
|
+
|
|
285
|
+
// Auto-init refuses on a non-empty target dir → 404 / "not found".
|
|
286
|
+
// Distinguish "path already in use" from real errors.
|
|
287
|
+
if (pushMain.status !== 0 && (errMain.includes('not found') || errMain.includes('404'))) {
|
|
288
|
+
spawnSync('rm', ['-rf', tmp], { stdio: 'ignore' });
|
|
289
|
+
return { name, status: 'skipped', reason: 'path already in use' };
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
const pushPages = spawnSync('git', pushArgs('gh-pages'), { stdio: ['ignore', 'pipe', 'pipe'] });
|
|
293
|
+
|
|
294
|
+
if (pushMain.status !== 0 && pushPages.status !== 0) {
|
|
295
|
+
const err = (errMain + '\n' + (pushPages.stderr?.toString?.() || '')).trim();
|
|
296
|
+
spawnSync('rm', ['-rf', tmp], { stdio: 'ignore' });
|
|
297
|
+
return { name, status: 'failed', reason: `push failed: ${err.slice(0, 400)}` };
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
spawnSync('rm', ['-rf', tmp], { stdio: 'ignore' });
|
|
301
|
+
return { name, status: 'installed', dest: `${dest}/` };
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
/**
|
|
305
|
+
* Public entry point. Called from bin/jss.js's `install` subcommand
|
|
306
|
+
* action. Throws to signal a non-zero exit; returns normally for
|
|
307
|
+
* partial success (per-app errors are reported but don't fail-fast).
|
|
308
|
+
*/
|
|
309
|
+
export async function runInstall(names, options) {
|
|
310
|
+
const pod = (options.pod || 'http://localhost:4443').replace(/\/$/, '');
|
|
311
|
+
const user = options.user || 'me';
|
|
312
|
+
const password = options.password || process.env.JSS_SINGLE_USER_PASSWORD || 'me';
|
|
313
|
+
const nostrPrivkey = options.nostrPrivkey || process.env.NOSTR_PRIVKEY || null;
|
|
314
|
+
|
|
315
|
+
// Validate Nostr privkey if supplied (64 lowercase-hex chars).
|
|
316
|
+
if (nostrPrivkey && !/^[0-9a-f]{64}$/i.test(nostrPrivkey)) {
|
|
317
|
+
console.error(red('✗ --nostr-privkey must be 64 hex chars'));
|
|
318
|
+
throw new Error('invalid --nostr-privkey');
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
// Bundle mode: resolve, fetch, parse, then concatenate items with
|
|
322
|
+
// any positional ad-hoc apps. `--bundle <src> chrome` installs the
|
|
323
|
+
// bundle + chrome; same auth + target flags apply to all.
|
|
324
|
+
let bundleMeta = null;
|
|
325
|
+
let allNames = [...(names || [])];
|
|
326
|
+
if (options.bundle) {
|
|
327
|
+
const resolved = resolveBundleSource(options.bundle);
|
|
328
|
+
if (resolved.error) {
|
|
329
|
+
console.error(red(`✗ --bundle: ${resolved.error}`));
|
|
330
|
+
throw new Error(resolved.error);
|
|
331
|
+
}
|
|
332
|
+
const bundle = await loadBundle(resolved);
|
|
333
|
+
if (bundle.error) {
|
|
334
|
+
console.error(red(`✗ --bundle: ${bundle.error}`));
|
|
335
|
+
throw new Error(bundle.error);
|
|
336
|
+
}
|
|
337
|
+
bundleMeta = { name: bundle.name, description: bundle.description, count: bundle.items.length };
|
|
338
|
+
// Bundle items go first; positional names appended afterwards.
|
|
339
|
+
allNames = [...bundle.items, ...allNames];
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
if (allNames.length === 0) {
|
|
343
|
+
throw new Error('expected at least one app name or a --bundle. Try: `jss install chrome`');
|
|
344
|
+
}
|
|
345
|
+
|
|
346
|
+
// Validate every spec up front so we report invalid names before
|
|
347
|
+
// doing any network work.
|
|
348
|
+
const specs = [];
|
|
349
|
+
for (const n of allNames) {
|
|
350
|
+
const spec = parseAppSpec(n);
|
|
351
|
+
if (spec.error) {
|
|
352
|
+
console.error(red(`✗ ${n}: ${spec.error}`));
|
|
353
|
+
throw new Error(`invalid app spec: ${n}`);
|
|
354
|
+
}
|
|
355
|
+
specs.push(spec);
|
|
356
|
+
}
|
|
357
|
+
|
|
358
|
+
if (bundleMeta) {
|
|
359
|
+
const label = bundleMeta.name
|
|
360
|
+
? `bundle "${bundleMeta.name}"`
|
|
361
|
+
: 'bundle';
|
|
362
|
+
console.log(bold(`\nInstalling ${specs.length} app${specs.length === 1 ? '' : 's'} from ${label} → `) + green(pod));
|
|
363
|
+
if (bundleMeta.description) console.log(dim(` ${bundleMeta.description}`));
|
|
364
|
+
} else {
|
|
365
|
+
console.log(bold(`\nInstalling ${specs.length} app${specs.length === 1 ? '' : 's'} → `) + green(pod));
|
|
366
|
+
}
|
|
367
|
+
if (nostrPrivkey) console.log(dim(' (signing with Nostr privkey — NIP-98)'));
|
|
368
|
+
console.log('');
|
|
369
|
+
|
|
370
|
+
// With --nostr-privkey we sign each push as NIP-98; no bearer token
|
|
371
|
+
// needed. Otherwise fetch the bearer token from the pod's IDP.
|
|
372
|
+
let token = null;
|
|
373
|
+
if (!nostrPrivkey) try {
|
|
374
|
+
token = await fetchToken({ pod, user, password });
|
|
375
|
+
} catch (e) {
|
|
376
|
+
console.error(red(`✗ ${e.message}`));
|
|
377
|
+
console.error(dim(' Is the pod running? Try: `jss start`'));
|
|
378
|
+
throw e;
|
|
379
|
+
}
|
|
380
|
+
|
|
381
|
+
// Decode hex privkey once for installOne (nip98Token wants bytes).
|
|
382
|
+
const privkeyBytes = nostrPrivkey
|
|
383
|
+
? Uint8Array.from(Buffer.from(nostrPrivkey, 'hex'))
|
|
384
|
+
: null;
|
|
385
|
+
|
|
386
|
+
let okCount = 0;
|
|
387
|
+
let failCount = 0;
|
|
388
|
+
for (const spec of specs) {
|
|
389
|
+
const result = await installOne({ spec, pod, token, nostrPrivkey: privkeyBytes });
|
|
390
|
+
switch (result.status) {
|
|
391
|
+
case 'installed':
|
|
392
|
+
console.log(green(`✓ ${result.name}`) + dim(` → ${result.dest}`));
|
|
393
|
+
okCount++;
|
|
394
|
+
break;
|
|
395
|
+
case 'skipped':
|
|
396
|
+
console.log(yellow(`⊘ ${result.name}`) + dim(`: skipped (${result.reason})`));
|
|
397
|
+
break;
|
|
398
|
+
case 'failed':
|
|
399
|
+
console.error(red(`✗ ${result.name}: ${result.reason.split(':')[0]}`));
|
|
400
|
+
if (result.reason.includes(':')) {
|
|
401
|
+
console.error(dim(` ${result.reason.slice(result.reason.indexOf(':') + 1).trim()}`));
|
|
402
|
+
}
|
|
403
|
+
failCount++;
|
|
404
|
+
break;
|
|
405
|
+
}
|
|
406
|
+
}
|
|
407
|
+
|
|
408
|
+
console.log('');
|
|
409
|
+
console.log(bold(`${okCount}/${specs.length} installed.`));
|
|
410
|
+
if (okCount > 0) {
|
|
411
|
+
console.log(dim('Open in browser: ') + `${pod}/public/apps/`);
|
|
412
|
+
}
|
|
413
|
+
|
|
414
|
+
if (failCount > 0) {
|
|
415
|
+
throw new Error(`${failCount} of ${specs.length} install(s) failed`);
|
|
416
|
+
}
|
|
417
|
+
}
|