fix: seed pod files skip-if-exists so user edits survive restarts (#81)

* fix: seed pod files skip-if-exists so user edits survive restarts

seedPodFiles() copied welcome.html (as index.html), signin, account
and docs pages into the pod root unconditionally on every start,
silently clobbering any edits the pod owner had made to those files.

Seed them only when the destination does not exist, the same
skip-if-exists behaviour JSS uses for its root landing page (and the
same rule this function already applied to links.jsonld and apps/).

* 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).

* fix: non-clobbering apps dir copy; document --no-auth writes nothing

- cpSync the apps bundle with force:false + errorOnExist and treat a
  raced-into-existence dir as already seeded (Copilot review).
- docs.html: note .token-secret is not created with --no-auth.

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>
@@ -70,10 +70,10 @@ <h2 id="layout">File layout (<code>pod-data/</code>)</h2>
 ├── <span class="label">settings/</span>         <span class="note">prefs + type indexes (JSS-seeded)</span>
 ├── <span class="label">.acl</span>              <span class="note">root container ACL — owner read/write, no public default</span>
 ├── <span class="label">.idp/</span>             <span class="note">JSS internal identity storage (see below)</span>
-└── <span class="label">.token-secret</span>     <span class="note">JWT signing secret (auto-generated, mode 0600)</span></pre>
+└── <span class="label">.token-secret</span>     <span class="note">JWT signing secret (auto-generated, mode 0600; not created with --no-auth)</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 jspod writes nothing at all — no seeded pages and no <code>.token-secret</code> (auth is bypassed, so no tokens are ever minted).
 </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,36 +130,55 @@ 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. Same overwrite/skip-if-exists matrix as the
-// pre-refactor CLI implementation — unchanged behaviour.
+// 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
+// other seeded page) must not have it clobbered on the next start.
 function seedPodFiles(root) {
   try {
-    const overwrite = [
+    const seed = [
       'welcome.html',         // becomes pod-data/index.html
       'signin.html', 'signin.html.acl',
       'account.html', 'account.html.acl',
       'docs.html', 'docs.html.acl'
     ];
-    for (const name of overwrite) {
+    for (const name of seed) {
       const src = join(PACKAGE_ROOT, name);
       // 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)) 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');
     const appsDst = join(root, 'public', 'apps');
-    const appsDirExisted = existsSync(appsDst);
+    let appsDirExisted = existsSync(appsDst);
     if (existsSync(appsSrc) && !appsDirExisted) {
-      cpSync(appsSrc, appsDst, { recursive: true });
+      try {
+        cpSync(appsSrc, appsDst, { recursive: true, force: false, errorOnExist: true });
+      } catch (e) {
+        // Same atomicity rule as copyIfAbsent: a concurrently-created
+        // apps dir means it was already seeded, never overwrite it.
+        if (e.code !== 'ERR_FS_CP_EEXIST' && e.code !== 'EEXIST') throw e;
+        appsDirExisted = true;
+      }
     }
     return { appsDirExisted };
   } catch {
@@ -226,7 +245,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.
@@ -282,7 +304,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'
     }
   });
@@ -308,26 +330,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"
   }
 }