javascript-solid-server 0.0.198 → 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 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
@@ -316,12 +316,13 @@ program
316
316
  * resolution, NIP-98 auth, curated default sets, and --bundle.
317
317
  */
318
318
  program
319
- .command('install <names...>')
320
- .description('Install a Solid app from github.com/solid-apps/<name> into a running pod')
319
+ .command('install [names...]')
320
+ .description('Install a Solid app (or a bundle of apps) into a running pod')
321
321
  .option('--pod <url>', 'Target pod URL', 'http://localhost:4443')
322
322
  .option('--user <name>', 'Username for IDP auth', 'me')
323
323
  .option('--password <pw>', 'Password (default: $JSS_SINGLE_USER_PASSWORD or "me")')
324
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')
325
326
  .action(async (names, options) => {
326
327
  try {
327
328
  const { runInstall } = await import('../src/cli/install.js');
@@ -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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "javascript-solid-server",
3
- "version": "0.0.198",
3
+ "version": "0.0.199",
4
4
  "description": "A minimal, fast Solid server",
5
5
  "main": "src/index.js",
6
6
  "type": "module",
@@ -25,8 +25,8 @@
25
25
  */
26
26
 
27
27
  import { spawnSync } from 'child_process';
28
- import { existsSync } from 'fs';
29
- import { join } from 'path';
28
+ import { existsSync, readFileSync } from 'fs';
29
+ import { join, isAbsolute } from 'path';
30
30
  import { nip98Token } from '../nostr/event.js';
31
31
 
32
32
  // ANSI helpers — keep zero-dep so this works in any embedded usage.
@@ -87,6 +87,111 @@ function parseAppSpec(input) {
87
87
  return { source, name, ref };
88
88
  }
89
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
+
90
195
  /**
91
196
  * Fetch a bearer token from the pod's IDP, or null if the pod runs
92
197
  * with `--public` (no auth required for writes).
@@ -207,20 +312,41 @@ export async function runInstall(names, options) {
207
312
  const password = options.password || process.env.JSS_SINGLE_USER_PASSWORD || 'me';
208
313
  const nostrPrivkey = options.nostrPrivkey || process.env.NOSTR_PRIVKEY || null;
209
314
 
210
- if (!names || names.length === 0) {
211
- throw new Error('expected at least one app name. Try: `jss install chrome`');
212
- }
213
-
214
315
  // Validate Nostr privkey if supplied (64 lowercase-hex chars).
215
316
  if (nostrPrivkey && !/^[0-9a-f]{64}$/i.test(nostrPrivkey)) {
216
317
  console.error(red('✗ --nostr-privkey must be 64 hex chars'));
217
318
  throw new Error('invalid --nostr-privkey');
218
319
  }
219
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
+
220
346
  // Validate every spec up front so we report invalid names before
221
347
  // doing any network work.
222
348
  const specs = [];
223
- for (const n of names) {
349
+ for (const n of allNames) {
224
350
  const spec = parseAppSpec(n);
225
351
  if (spec.error) {
226
352
  console.error(red(`✗ ${n}: ${spec.error}`));
@@ -229,7 +355,15 @@ export async function runInstall(names, options) {
229
355
  specs.push(spec);
230
356
  }
231
357
 
232
- console.log(bold(`\nInstalling ${specs.length} app${specs.length === 1 ? '' : 's'} → `) + green(pod));
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
+ }
233
367
  if (nostrPrivkey) console.log(dim(' (signing with Nostr privkey — NIP-98)'));
234
368
  console.log('');
235
369