create-wordjs 1.14.1 → 2.1.0

package/README.md

@@ -31,11 +31,12 @@ That single command takes you from nothing to the browser install wizard:
    clickable URL:
 
    ```
-   → https://localhost:3000/install?token=…
+   → https://localhost:3000/install#token=…
    ```
 
-Open the URL, pick your database (SQLite — zero config — or PostgreSQL), create your admin
-account, and you're in.
+Open the URL, pick your database, create your admin account, and you're in. The wizard offers
+**SQLite** (zero config, the default), **PostgreSQL** and **MySQL/MariaDB** — all three are certified
+in CI — plus a pure-JS *SQLite (legacy / WASM)* fallback for hosts where the native binary can't load.
 
 ## Requirements
 
@@ -46,9 +47,12 @@ account, and you're in.
 | Option | Description |
 | --- | --- |
 | `--zip <path-or-url>` | Use a local release ZIP (or a direct ZIP URL) instead of querying the GitHub API. Handy offline or when rate-limited. |
-| `--version <tag>` | Install a specific release (e.g. `--version v1.0.0`) instead of the latest. |
+| `--version <tag>` | Install a specific release (e.g. `--version v2.1.0`) instead of the latest. |
 | `--http` | Serve plain HTTP instead of self-signed HTTPS (sets `WORDJS_HTTP=1`). |
 | `--no-start` | Scaffold and install dependencies only — start the server yourself later. |
+| `--yes`, `-y` | Skip the confirmation prompt (required when `upgrade` runs non-interactively). |
+| `--force` | (`upgrade`) Re-apply even if the site is already on the target version. |
+| `--no-install` | (`upgrade`) Swap the code only; skip `npm run release:install`. |
 | `-h`, `--help` | Show usage. |
 
 Separate-mode options:
@@ -68,8 +72,10 @@ Separate-mode options:
 cd .. && npx create-wordjs@latest upgrade my-site      # or run it from inside: npx create-wordjs@latest upgrade .
 ```
 
-Downloads the newest release and replaces the app code while **preserving your data**: the SQLite
-database, `uploads/`, `wordjs-config.json`, gateway secrets and any user-installed plugins survive.
+Downloads the newest release and replaces the app code while **preserving your data**: the database
+directory (`backend/data`), `backend/uploads/`, `wordjs-config.json`, `.env`, gateway secrets
+(`gateway/gateway-config.json`) and any user-installed plugins survive. It asks for confirmation
+before touching an existing install — on a non-interactive shell it refuses unless you pass `--yes`.
 Restart the server afterwards (schema migrations run automatically on the next start).
 
 ## Separate mode (multi-machine)
@@ -95,9 +101,11 @@ npx create-wordjs@latest join frontend --gateway 10.0.0.1 --token <t> --ca-hash
 ```
 
 Each `join` downloads the release, enrolls against the gateway (the token authorizes exactly one
-certificate signing; it is burned afterwards), then starts the service, which registers with the
-gateway over mTLS. Browse `https://<gateway>:3000` when all three are up. `join` machines need
-`openssl` on the PATH. Full details, port matrix and the manual (source-checkout) procedure:
+certificate signing; it is burned afterwards, and the ones `gateway` printed also expire after 120
+minutes — mint more on the gateway with `node scripts/cluster.js token <backend|frontend>`, which
+defaults to a 60-minute TTL and takes `--ttl <minutes>`), then starts the service, which registers
+with the gateway over mTLS. Browse `https://<gateway>:3000` when all three are up. `join` machines
+need `openssl` on the PATH. Full details, port matrix and the manual (source-checkout) procedure:
 [documentation/separate-mode.md](https://github.com/jaimemartinez/wordjs/blob/main/documentation/separate-mode.md).
 
 ## Good to know
@@ -111,14 +119,16 @@ gateway over mTLS. Browse `https://<gateway>:3000` when all three are up. `join`
 - **GitHub rate limit / offline**: the release lookup uses the unauthenticated GitHub API. If it
   is rate-limited or you're offline, download `wordjs-v*.zip` from the
   [releases page](https://github.com/jaimemartinez/wordjs/releases) and run
-  `npx create-wordjs@latest my-site --zip ./wordjs-v1.0.0.zip`.
+  `npx create-wordjs@latest my-site --zip ./wordjs-v2.1.0.zip`.
 - **Existing directories**: the target directory must not exist (or must be empty) — the tool
   refuses to overwrite anything.
 
 ## What gets created
 
 A ready-to-run WordJS bundle: backend (pre-compiled to `dist/`), frontend (pre-built `.next`),
-gateway, bundled plugins and themes. Secrets (JWT, DB password, install token) are generated
+gateway, the bundled plugins and the four bundled themes (`circuito`, `default`, `gaceta`,
+`vergel`). Marketplace plugins are **not** in the bundle — they ship as separate release assets and
+are installed from the admin. Secrets (JWT, DB password, install token) are generated
 locally during install — nothing sensitive ships in the bundle. See `INSTALL.md` inside the
 scaffolded directory for the manual steps and `documentation/deployment.md` for production
 deployment.

package/index.js

@@ -10,7 +10,7 @@
  *   1. Downloads the latest pre-compiled WordJS release ZIP from GitHub (no build step needed).
  *   2. Extracts it into <dir> and installs the runtime dependencies (npm run release:install).
  *   3. Generates a one-time install token and starts the server (npm run start:mono) with it,
- *      printing a clickable https://localhost:3000/install?token=… URL — the browser install
+ *      printing a clickable https://localhost:3000/install#token=… URL — the browser install
  *      wizard takes it from there (pick SQLite/PostgreSQL, create your admin, done).
  *
  * Plain Node, no TypeScript. Only runtime dependency: adm-zip (ZIP extraction).
@@ -49,7 +49,7 @@ Usage:
 
 Options:
   --zip <path-or-url>   Use a local release ZIP (or a direct ZIP URL) instead of asking GitHub.
-  --version <tag>       Install/upgrade to a specific release tag (e.g. v1.0.0) instead of the latest.
+  --version <tag>       Install/upgrade to a specific release tag (e.g. v2.1.0) instead of the latest.
   --http                Serve plain HTTP instead of self-signed HTTPS (sets WORDJS_HTTP=1). (create)
   --no-start            Scaffold + install dependencies only; don't start the server.
   --yes, -y             Skip the confirmation prompt (required when upgrading non-interactively).
@@ -65,7 +65,7 @@ Options:
 
 Examples:
   npx create-wordjs@latest my-site
-  npx create-wordjs@latest my-site --version v1.0.0
+  npx create-wordjs@latest my-site --version v2.1.0
   npx create-wordjs@latest upgrade                     # from inside your site directory
   npx create-wordjs@latest upgrade ./my-site --yes
 
@@ -103,7 +103,7 @@ function parseArgs(argv) {
         const a = argv[i];
         if (a === '-h' || a === '--help') { console.log(HELP); process.exit(0); }
         else if (a === '--zip') { opts.zip = argv[++i] || fail('--zip needs a value (path or URL to a wordjs-*.zip).'); }
-        else if (a === '--version') { opts.version = argv[++i] || fail('--version needs a value (a release tag, e.g. v1.0.0).'); }
+        else if (a === '--version') { opts.version = argv[++i] || fail('--version needs a value (a release tag, e.g. v2.1.0).'); }
         else if (a === '--http') opts.http = true;
         else if (a === '--no-start') opts.start = false;
         else if (a === '--yes' || a === '-y') opts.yes = true;
@@ -130,7 +130,7 @@ function parseArgs(argv) {
         else if (opts.mode === 'join') opts.dir = opts.role ? `wordjs-${opts.role}` : 'wordjs-node';
         else fail('Please specify a directory for your new site.', 'Example: npx create-wordjs@latest my-site');
     }
-    if (opts.version && /^\d/.test(opts.version)) opts.version = 'v' + opts.version;   // accept "1.0.0" for "v1.0.0"
+    if (opts.version && /^\d/.test(opts.version)) opts.version = 'v' + opts.version;   // accept "2.1.0" for "v2.1.0"
     return opts;
 }
 
@@ -181,6 +181,41 @@ async function githubJson(url) {
     try { return JSON.parse(body); } catch { fail('GitHub returned an unparsable response.', 'Try again, or use --zip <path-to-zip>.'); }
 }
 
+// NAME THE ASSET WE WANT; DO NOT TAKE THE FIRST ONE THAT LOOKS RIGHT.
+//
+// The core bundle is not alone on the release: the same release carries all 31 marketplace plugin
+// zips, and `wordjs-*.zip` is a shape, not an identity. A plugin slug beginning with `wordjs-` would
+// sort ahead of the bundle in the assets array and this installer would download a plugin and try to
+// boot it as a site. Nothing today collides, which is exactly when it is cheap to fix.
+//
+// release.yml names the bundle after the tag (`wordjs-v2.0.0.zip`), so ask for that by name. The
+// loose match survives only as a fallback — for older releases, and so a rename in the workflow
+// degrades gracefully instead of failing hard.
+//
+// BUT THE FALLBACK IS THE OLD RULE, so it cannot be allowed to guess. Taking the first loose match
+// would reinstate exactly the bug the exact match was added to fix, on every path where the
+// tag-named asset is absent (a workflow_dispatch build, a rename, any earlier release). The loose
+// shape is therefore used ONLY when it is unambiguous: exactly one candidate. Two or more means we
+// would be choosing which file is the site, and choosing wrong installs a plugin as a site — so we
+// refuse and say so, and `--zip` is right there. Fail closed, never guess.
+//
+// Exported (below) so it can be exercised directly: it is the one piece of release resolution that is
+// pure, and testing it through the network call would mean testing a copy of it instead.
+function pickBundleAsset(assets, tagName) {
+    const list = Array.isArray(assets) ? assets : [];
+    const wanted = `wordjs-${tagName}.zip`.toLowerCase();
+    const exact = list.find((a) => String(a && a.name || '').toLowerCase() === wanted);
+    if (exact) return exact;
+    const loose = looseBundleCandidates(list);
+    return loose.length === 1 ? loose[0] : null;
+}
+
+/** Every asset matching the loose `wordjs-*.zip` shape — used to explain an ambiguous refusal. */
+function looseBundleCandidates(assets) {
+    const list = Array.isArray(assets) ? assets : [];
+    return list.filter((a) => /^wordjs-.*\.zip$/i.test(a && a.name || ''));
+}
+
 async function resolveReleaseAsset(tag) {
     const url = tag
         ? `https://api.github.com/repos/${REPO}/releases/tags/${encodeURIComponent(tag)}`
@@ -190,8 +225,17 @@ async function resolveReleaseAsset(tag) {
         fail(tag ? `No release found for tag "${tag}".` : `No releases found for ${REPO}.`,
             `See https://github.com/${REPO}/releases for available versions, or pass --zip <path-or-url>.`);
     }
-    const asset = (release.assets || []).find((a) => /^wordjs-.*\.zip$/i.test(a.name || ''));
-    if (!asset) fail(`Release ${release.tag_name} has no wordjs-*.zip asset.`, 'Pass --zip <path-or-url> instead.');
+    const asset = pickBundleAsset(release.assets, release.tag_name);
+    if (!asset) {
+        // Say WHICH of the two refusals this is: "there is no bundle" and "there are several and I
+        // will not guess" need different answers from whoever is reading.
+        const candidates = looseBundleCandidates(release.assets).map((a) => a.name);
+        if (candidates.length > 1) {
+            fail(`Release ${release.tag_name} has no asset named wordjs-${release.tag_name}.zip, and ${candidates.length} others match wordjs-*.zip: ${candidates.join(', ')}.`,
+                'Refusing to guess which one is the site bundle — pass --zip <path-or-url> with the one you want.');
+        }
+        fail(`Release ${release.tag_name} has no wordjs-*.zip asset.`, 'Pass --zip <path-or-url> instead.');
+    }
     return { name: asset.name, url: asset.browser_download_url, tag: release.tag_name };
 }
 
@@ -685,7 +729,7 @@ async function main() {
         console.log(`      cd ${opts.dir}`);
         console.log(`      npm run start:mono${opts.http ? '        (with WORDJS_HTTP=1 in the environment for plain HTTP)' : ''}`);
         console.log('');
-        console.log(`   The console will print your one-time install URL (${proto}://localhost:3000/install?token=…).`);
+        console.log(`   The console will print your one-time install URL (${proto}://localhost:3000/install#token=…).`);
         console.log(line + '\n');
         return;
     }
@@ -699,7 +743,12 @@ async function main() {
     console.log(`\n${line}`);
     console.log('✅ WordJS is ready — finish setup in your browser:');
     console.log('');
-    console.log(`   → ${proto}://localhost:3000/install?token=${token}`);
+    // The token rides in the URL FRAGMENT, not a `?token=` query string: a fragment is never sent to
+    // any server, so this bootstrap secret stays out of access/proxy logs and out of the `Referer` of
+    // every sub-resource the install page loads. The wizard reads `#token=` (and still accepts a
+    // legacy `?token=`) and scrubs it from the address bar. Keep in sync with the backend's own
+    // banner in backend/src/core/install-token.ts.
+    console.log(`   → ${proto}://localhost:3000/install#token=${token}`);
     console.log('');
     console.log('   • The server is starting below — give it ~15–30 seconds, then open the URL.');
     if (!opts.http) {
@@ -730,4 +779,9 @@ async function main() {
     child.on('exit', (code) => process.exit(code == null ? 0 : code));
 }
 
-main().catch((e) => fail(e && e.message ? e.message : String(e)));
+// Run only when invoked as the CLI, so the pure helpers above can be required and exercised.
+if (require.main === module) {
+    main().catch((e) => fail(e && e.message ? e.message : String(e)));
+}
+
+module.exports = { pickBundleAsset };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "create-wordjs",
-    "version": "1.14.1",
+    "version": "2.1.0",
     "description": "Create a WordJS site with one command — the self-hosted CMS where third-party plugins run in an OS-isolated process with per-capability permission grants. SSR/SEO out of the box, SQLite by default, no PHP.",
     "license": "MIT",
     "author": "Jaime Martinez (https://github.com/jaimemartinez)",
@@ -46,6 +46,9 @@
         "access": "public"
     },
     "dependencies": {
-        "adm-zip": "^0.5.16"
+        "adm-zip": "^0.6.0"
+    },
+    "scripts": {
+        "test": "node --test test/*.test.js"
     }
 }