fix: no seeding or token secret in --no-auth mode; atomic no-clobber; jss 0.0.212

Review follow-ups on top of the skip-if-exists seeding fix:

- Gate seedPodFiles() and the token secret on options.auth. In
  --no-auth mode jspod runs JSS with --public, where WAC is bypassed
  (seeded .acl files are never consulted) and a publicly served tree
  must not be written into — the same rationale as JSS's public-mode
  landing-page seeding skip (JSS#578).
- Use COPYFILE_EXCL so the no-clobber guarantee holds even against a
  concurrent writer (Copilot review).
- Update docs.html, which still described the old overwrite-every-start
  behaviour (Copilot review).
- Bump javascript-solid-server to >=0.0.212 <0.0.213 to pick up the
  public-mode seeding skip (JSS#578) and the WAC sidecar fix (JSS#580).

Author: melvincarvalho

docs.html

@@ -52,13 +52,13 @@ <h2 id="layout">File layout (<code>pod-data/</code>)</h2>
 <p>jspod creates <code>pod-data/</code> in the current working directory on first start (or wherever you pass via <code>--root</code>). Everything the pod is, including identities and signing keys, lives under that single tree.</p>
 
 <pre class="tree"><span class="label">pod-data/</span>             <span class="note">your pod root</span>
-├── <span class="label">index.html</span>        <span class="note">welcome page — jspod overwrites every start</span>
+├── <span class="label">index.html</span>        <span class="note">welcome page — jspod-seeded, skip-if-exists</span>
 ├── <span class="label">index.html.acl</span>    <span class="note">public-read for the landing page (JSS-managed)</span>
-├── <span class="label">signin.html</span>       <span class="note">jspod's sign-in app — overwritten every start</span>
+├── <span class="label">signin.html</span>       <span class="note">jspod's sign-in app — seeded, skip-if-exists</span>
 ├── <span class="label">signin.html.acl</span>   <span class="note">public-read</span>
-├── <span class="label">account.html</span>      <span class="note">post-sign-in dashboard — overwritten every start</span>
+├── <span class="label">account.html</span>      <span class="note">post-sign-in dashboard — seeded, skip-if-exists</span>
 ├── <span class="label">account.html.acl</span>  <span class="note">public-read</span>
-├── <span class="label">docs.html</span>         <span class="note">this page — overwritten every start</span>
+├── <span class="label">docs.html</span>         <span class="note">this page — seeded, skip-if-exists</span>
 ├── <span class="label">docs.html.acl</span>     <span class="note">public-read</span>
 ├── <span class="label">profile/</span>
 │   └── <span class="label">card.jsonld</span>   <span class="note">your WebID profile (JSS-seeded)</span>
@@ -73,7 +73,7 @@ <h2 id="layout">File layout (<code>pod-data/</code>)</h2>
 └── <span class="label">.token-secret</span>     <span class="note">JWT signing secret (auto-generated, mode 0600)</span></pre>
 
 <div class="callout">
-<strong>Overwrite warning.</strong> <code>index.html</code>, <code>signin.html</code>, <code>account.html</code>, and <code>docs.html</code> are owned by jspod and overwritten on every <em>start</em>. Edits won't survive a restart. To customize, fork jspod or run JSS directly instead. The <code>public/links.jsonld</code> and <code>public/apps/pilot/</code> bundles are <em>skip-if-exists</em>, so user edits there <em>do</em> survive.
+<strong>Seeding.</strong> <code>index.html</code>, <code>signin.html</code>, <code>account.html</code>, and <code>docs.html</code> are seeded by jspod on first start and never overwritten — edits survive restarts, same as <code>public/links.jsonld</code> and <code>public/apps/pilot/</code>. The trade-off: upgrading jspod won't refresh a page you already have; delete the file and restart to re-seed the current stock copy. In <code>--no-auth</code> mode nothing is seeded at all — the served directory is left untouched.
 </div>
 
 <h2 id="idp">Where the IDP data lives</h2>
@@ -91,12 +91,7 @@ <h2 id="idp">Where the IDP data lives</h2>
 <p>The account record contains a bcrypt hash of the password — not the plaintext. The signing keys are sensitive (anyone with these can mint valid tokens against your pod). JSS manages file modes on these; jspod doesn't touch them.</p>
 
 <h2 id="customize">Customize the landing page</h2>
-<p>The default landing page (<code>pod-data/index.html</code>) is owned by jspod. Edits to it are overwritten on the next start. To genuinely customize, the options are, in increasing order of effort:</p>
-<ul>
-<li>Fork jspod (clone the repo, edit <code>welcome.html</code>, run <code>./index.js</code> from the fork). All overwrites use <em>your</em> templates.</li>
-<li>Run JSS directly with your own <code>pod-data/index.html</code> pre-seeded. JSS does skip-if-exists for its own seed, so your file wins. You lose jspod's account dashboard / signin app / data browser, but you can copy any of them out of the npm package and adapt.</li>
-<li>Track <a href="https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/459">JSS#459</a> for a future <code>--landing-page &lt;file&gt;</code> option that would make this cleaner.</li>
-</ul>
+<p>The default landing page (<code>pod-data/index.html</code>) is seeded on first start only — just edit it, and your version survives restarts. To return to the stock page, delete <code>pod-data/index.html</code> and restart. To change the template used for <em>new</em> pods, fork jspod and edit <code>welcome.html</code>.</p>
 
 <h2 id="auth-ladder">Auth ladder</h2>
 <p>jspod ships you onto rung 1 (default <code>me</code>/<code>me</code>) and makes climbing visible. The dashboard at <code>/account.html</code> exposes a Change password form (rung 2). Passkey support (rung 3) is on the roadmap. See <a href="https://github.com/JavaScriptSolidServer/jspod/issues/6">jspod#6</a> for the full ladder framing.</p>

lib/start.js

@@ -16,7 +16,7 @@ import { dirname, join, delimiter } from 'path';
 import chalk from 'chalk';
 import {
   existsSync, mkdirSync, readFileSync, writeFileSync,
-  chmodSync, statSync, copyFileSync, cpSync
+  chmodSync, statSync, copyFileSync, cpSync, constants as fsConstants
 } from 'fs';
 import { randomBytes } from 'crypto';
 import { createServer } from 'net';
@@ -130,6 +130,17 @@ function shouldAutoOpen() {
   return true;
 }
 
+// Copy src → dst only if dst does not already exist. COPYFILE_EXCL makes
+// the no-clobber guarantee atomic: a dst created between check and copy
+// surfaces as EEXIST (ignored) instead of being overwritten.
+function copyIfAbsent(src, dst) {
+  try {
+    copyFileSync(src, dst, fsConstants.COPYFILE_EXCL);
+  } catch (e) {
+    if (e.code !== 'EEXIST') throw e;
+  }
+}
+
 // Seed jspod-owned pages into the running pod's root once JSS has
 // finished its init. All seeding is skip-if-exists, matching JSS's own
 // root-landing-page seeding: a pod owner who edits index.html (or any
@@ -147,13 +158,13 @@ function seedPodFiles(root) {
       // welcome.html maps onto index.html; everything else is a passthrough
       const destName = name === 'welcome.html' ? 'index.html' : name;
       const dst = join(root, destName);
-      if (existsSync(src) && !existsSync(dst)) copyFileSync(src, dst);
+      if (existsSync(src)) copyIfAbsent(src, dst);
     }
 
     const linksSrc = join(PACKAGE_ROOT, 'links.jsonld');
     const linksDst = join(root, 'public', 'links.jsonld');
-    if (existsSync(linksSrc) && !existsSync(linksDst)) {
-      copyFileSync(linksSrc, linksDst);
+    if (existsSync(linksSrc)) {
+      copyIfAbsent(linksSrc, linksDst);
     }
 
     const appsSrc = join(PACKAGE_ROOT, 'apps');
@@ -227,7 +238,10 @@ export async function start(userOptions = {}) {
   }
   options.port = freePort;
 
-  const tokenSecret = resolveTokenSecret(options.root);
+  // No token secret in --no-auth mode: JSS runs --public there (auth is
+  // bypassed, so no tokens are ever minted) and persisting the secret
+  // would write <root>/.token-secret into a publicly served tree.
+  const tokenSecret = options.auth ? resolveTokenSecret(options.root) : null;
 
   // The data browser URL is a version-pinned jsdelivr asset so the
   // running pod always loads the matching browser code for this jspod.
@@ -283,7 +297,7 @@ export async function start(userOptions = {}) {
     env: {
       ...process.env,
       PATH: `${join(PACKAGE_ROOT, 'node_modules', '.bin')}${delimiter}${process.env.PATH}`,
-      TOKEN_SECRET: tokenSecret,
+      ...(tokenSecret ? { TOKEN_SECRET: tokenSecret } : {}),
       NODE_ENV: process.env.NODE_ENV || 'development'
     }
   });
@@ -309,26 +323,32 @@ export async function start(userOptions = {}) {
     // Post-readiness: seed pod files and (optionally) bootstrap the
     // default app bundle on first run. Failures here are best-effort
     // — the pod is already running.
-    const { appsDirExisted } = seedPodFiles(options.root);
-    if (!appsDirExisted && options.bootstrap && options.auth) {
-      console.log(chalk.bold.white(`\n📦 First run — installing the `) +
-                  chalk.yellow('default') +
-                  chalk.bold.white(` bundle...\n`));
-      const podUrl = url.replace(/\/$/, '');
-      const installChild = spawn(
-        process.execPath,
-        [CLI_SCRIPT, 'install', '--pod', podUrl, '--bundle', 'default'],
-        { stdio: 'inherit' }
-      );
-      installChild.on('exit', (code) => {
-        if (code !== 0) {
-          console.error(chalk.red(`\n✗ Bootstrap exited with code ${code}.`));
-          console.error(chalk.dim('  Install apps manually with `jspod install`.'));
-        }
-      });
-      installChild.on('error', (e) => {
-        console.error(chalk.red(`\n✗ Bootstrap failed to start: ${e.message}`));
-      });
+    // No seeding in --no-auth mode: jspod runs JSS with --public there,
+    // where WAC is bypassed (the seeded .acl files would never be
+    // consulted) and a publicly served tree must not be written into —
+    // the same rationale as JSS's own public-mode seeding skip (JSS#578).
+    if (options.auth) {
+      const { appsDirExisted } = seedPodFiles(options.root);
+      if (!appsDirExisted && options.bootstrap) {
+        console.log(chalk.bold.white(`\n📦 First run — installing the `) +
+                    chalk.yellow('default') +
+                    chalk.bold.white(` bundle...\n`));
+        const podUrl = url.replace(/\/$/, '');
+        const installChild = spawn(
+          process.execPath,
+          [CLI_SCRIPT, 'install', '--pod', podUrl, '--bundle', 'default'],
+          { stdio: 'inherit' }
+        );
+        installChild.on('exit', (code) => {
+          if (code !== 0) {
+            console.error(chalk.red(`\n✗ Bootstrap exited with code ${code}.`));
+            console.error(chalk.dim('  Install apps manually with `jspod install`.'));
+          }
+        });
+        installChild.on('error', (e) => {
+          console.error(chalk.red(`\n✗ Bootstrap failed to start: ${e.message}`));
+        });
+      }
     }
     if (options.open && shouldAutoOpen()) {
       console.log(chalk.green(`\n🌐 Opening ${url} in your browser...`));

package.json

@@ -60,6 +60,6 @@
   },
   "dependencies": {
     "chalk": "^5.6.2",
-    "javascript-solid-server": ">=0.0.208 <0.0.211"
+    "javascript-solid-server": ">=0.0.212 <0.0.213"
   }
 }