pmtiles-swarm 0.66.0 → 0.67.0

package/CHANGELOG.md

@@ -4,6 +4,37 @@
 ### ✨ Features and improvements
 - _...Add new stuff here..._
 
+### 🐞 Bug fixes
+- _...Add new stuff here..._
+
+## 0.67.0
+### ✨ Features and improvements
+- **An exported archive is dated, and the filename is its own field.** Both the archive's name and
+  the file it lands in now carry the date by default, and both can be changed — separately. They
+  answer different questions: `Terrain-20260822.pmtiles` is what somebody finds on disk,
+  `Terrain 20260822` is what a map client shows, and tying one to the other only guarantees that
+  one of them is wrong whenever they should differ.
+
+  A filename given by hand is reduced to a single path segment before it is used, because it is
+  joined to a save path and a filename is exactly the kind of field somebody puts a slash in.
+  `../../etc/passwd` is tested.
+
+  The description starts empty and stays empty unless something is typed. It used to be
+  prefilled from the recipe, which is a different thing — a recipe describes how tiles are
+  combined, an archive describes what it is, and only the person exporting it knows that. The
+  server no longer falls back to the recipe either: filling in a field the dialog showed as
+  blank is a worse surprise than having no description. The date is recorded there regardless,
+  because a name can be changed to anything and then nothing else says when the archive was
+  made.
+
+  This corrects something 0.64.0 asserted and this project does not do. The name was left undated
+  on the reasoning that `/latest/<category>/` follows a rebuild by name. It does not: it resolves a
+  category and takes the newest by date, and nothing here looks an archive up by name at all — the
+  only name comparison in the codebase refuses two archives the same *file* path. The
+  documentation said so as well, and now says what is true.
+
+
+
 ### 🐞 Bug fixes
 - _...Add new stuff here..._
 

package/docs/tile-stacks.md

@@ -698,14 +698,26 @@ resolves to whichever build is current, so the same recipe over a rebuilt source
 is a different bake — and a checkpoint that could not tell would resume across
 the change and produce an archive that is half one map and half another.
 
-The file is dated: `Terrain-20260822.pmtiles`. The archive's **name** is not.
-A rebuild here keeps its name and mints a new infohash, which is what lets
-`/latest/<category>/` follow it; dating the name would make every build a
-different map. The date goes in `description` instead, so an archive read out of
-context still says what produced it and when.
+Both the file and the archive's name are dated, and both can be changed —
+separately, because they answer different questions. `Terrain-20260822.pmtiles`
+is what somebody finds on disk; `Terrain 20260822` is what a map client shows.
+Tying one to the other only guarantees that one of them is wrong whenever they
+should differ.
+
+An earlier version of this document said the name had to stay undated so
+`/latest/<category>/` could follow a rebuild. That was wrong. `/latest/`
+resolves a category and takes the newest by date; nothing in this project looks
+an archive up by name at all, and the only name comparison there is refuses two
+archives the same _file_ path. A dated name is free, and it answers the question
+somebody holding two builds actually has.
 
 `name` is always written, because these archives get converted to mbtiles by
-other tools and a nameless metadata block is not valid there.
+other tools and a nameless metadata block is not valid there. The date also goes
+in `description`, so an archive read out of context says what produced it.
+
+A chosen filename is reduced to one path segment before it is used. That is not
+politeness — the name is joined to a save path, and a filename is exactly the
+kind of field somebody puts a slash in.
 
 ### What a baked archive says about itself
 
@@ -739,10 +751,11 @@ a name this node does not know, or a path it cannot write, is the caller's
 mistake and they can fix it, but only if they are told now rather than an hour
 later.
 
-**What it is called** defaults to the stack's title and can be changed, as can
-the description. The dialog shows the filename as the name is typed, because a
-name is not a filename — the same sanitising the server does, and a preview that
-promised something else would be worse than no preview.
+**What it is called** is two fields, both dated by default and both editable:
+the archive's name, and the filename. The dialog says what a filename will
+actually become where sanitising would change it, using the same rule the server
+applies — a field that shows one filename while the server writes another is
+worse than a field that shows nothing.
 
 A bake has two halves and they are watched in two places, deliberately. Merging
 is about a stack, so it is reported on the stack — tiles written, tiles skipped,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmtiles-swarm",
-  "version": "0.66.0",
+  "version": "0.67.0",
   "description": "BitTorrent distribution for PMTiles map archives: create torrents, watch folders, publish and subscribe to RSS feeds, and seed through qBittorrent or an embedded client",
   "type": "module",
   "main": "src/index.js",

package/src/bake-jobs.js

@@ -3,6 +3,7 @@ import {
   assertBakeable,
   bakeRevision,
   bakeStack,
+  bakedArchiveName,
   bakedName,
   mergeTileFor,
 } from './bake.js';
@@ -120,9 +121,15 @@ export class BakeManager {
     const publishDir =
       options.publishDir ?? (await this.#savePath(options)) ?? undefined;
 
-    // What the archive will be called, which the caller may have chosen. The
-    // file follows it; the date is what keeps successive builds apart.
-    const archiveName = options.name?.trim() || resolved.stack.title || stackId;
+    // Both dated by default and both overridable, separately: the archive's
+    // name is what a map client shows, and the filename is what somebody finds
+    // on disk. Tying them together only means one of the two is wrong whenever
+    // they should differ.
+    const when = new Date();
+    const archiveName = bakedArchiveName(resolved, {
+      name: options.name,
+      when,
+    });
 
     const job = {
       stackId,
@@ -138,7 +145,7 @@ export class BakeManager {
       finishedAt: null,
       error: null,
       infoHash: null,
-      name: bakedName(resolved, { when: new Date(), name: archiveName }),
+      name: bakedName(resolved, { filename: options.filename, when }),
       publishDir,
     };
     this.#jobs.set(stackId, job);
@@ -273,7 +280,10 @@ export class BakeManager {
       pauseMs: this.#config.stacks?.bakePauseMs ?? 0,
       metadata: {
         name: job.archiveName,
-        description: options.description ?? resolved.stack.description,
+        // Only what was asked for. Falling back to the recipe's own
+        // description would fill in a field the dialog showed as empty, which
+        // is a worse surprise than having no description at all.
+        description: options.description,
         attribution: resolved.stack.attribution,
         encoding: resolved.stack.output?.encoding,
         encodingFactors: resolved.stack.output,

package/src/bake.js

@@ -228,23 +228,45 @@ function stamp(when = new Date()) {
 /**
  * What to call the file a bake writes.
  *
- * Dated, because successive bakes of one stack are successive builds of one
- * map and two files cannot share a path. The archive's *name* is not dated --
- * see `bakedMetadata` -- so a rebuild keeps its identity the way every other
- * rebuild here does.
+ * Dated by default, because successive bakes of one stack are successive builds
+ * of one map and two files cannot share a path.
  *
- * Follows the name it is given, so renaming an export in the dialog renames the
- * file too. A name and a filename that disagree is a small thing that costs an
- * afternoon the first time somebody goes looking on disk.
+ * A caller may name it instead, and what they ask for is reduced to a single
+ * path segment before it is used. That is not politeness: this name is joined
+ * to a directory, and a filename is exactly the kind of field somebody puts a
+ * slash in.
  * @param {object} resolved - The resolved stack.
- * @param {object} [options] - `name` to override the stack's, `when`, `suffix`.
- * @returns {string} - A filename.
+ * @param {object} [options] - `filename` to choose one outright, and `when`.
+ * @returns {string} - A filename, always ending `.pmtiles`.
  */
 export function bakedName(resolved, options = {}) {
-  const title = options.name ?? resolved.stack.title ?? resolved.stack.id;
+  const requested = String(options.filename ?? '').trim();
+  if (requested) {
+    const stem = safeSegment(requested.replace(/\.pmtiles$/i, ''));
+    if (stem) return `${stem}.pmtiles`;
+  }
+
+  const title = resolved.stack.title ?? resolved.stack.id;
   const slug = safeSegment(title) || 'stack';
-  const tail = options.suffix ? `-${options.suffix}` : '';
-  return `${slug}-${stamp(options.when)}${tail}.pmtiles`;
+  return `${slug}-${stamp(options.when)}.pmtiles`;
+}
+
+/**
+ * What to call the archive itself.
+ *
+ * Dated too, and separately from the file. Nothing in this project looks an
+ * archive up by name -- `/latest/<category>/` follows a category and takes the
+ * newest by date -- so a dated name costs nothing and says which build you are
+ * looking at, which is the question somebody holding two of them has.
+ * @param {object} resolved - The resolved stack.
+ * @param {object} [options] - `name` to choose one outright, and `when`.
+ * @returns {string} - The name.
+ */
+export function bakedArchiveName(resolved, options = {}) {
+  const explicit = String(options.name ?? '').trim();
+  if (explicit) return explicit;
+  const title = resolved.stack.title ?? resolved.stack.id;
+  return `${title} ${stamp(options.when)}`;
 }
 
 /**

package/src/web/index.html

@@ -661,19 +661,28 @@
 
         <div class="field">
           <label for="bake-name">Name</label>
-          <input id="bake-name" placeholder="Terrain" />
+          <input id="bake-name" placeholder="Terrain 20260101" />
           <div class="sub">
-            What the archive is called, and what a rebuild of it keeps — so
-            leave the date out of it. The file gets one:
-            <code id="bake-filename"></code>
+            What the archive calls itself, and what a map client shows. Dated by
+            default, because two builds of one map are easier to tell apart that
+            way — nothing here looks an archive up by name, so it is free to say
+            whatever is useful.
           </div>
         </div>
 
+        <div class="field">
+          <label for="bake-file">Filename</label>
+          <input id="bake-file" placeholder="Terrain-20260101.pmtiles" />
+          <div class="sub" id="bake-filename"></div>
+        </div>
+
         <div class="field">
           <label for="bake-description">Description</label>
-          <input id="bake-description" placeholder="Bathymetry under terrain" />
+          <input id="bake-description" placeholder="" />
           <div class="sub">
-            Optional. The date this was baked is added to whatever is here.
+            Optional, and empty by default — what a stack merges is the
+            operator's business and not something to guess at. The date this was
+            baked is recorded here whether or not anything else is.
           </div>
         </div>
 
@@ -7742,10 +7751,17 @@ Every piece is hashed against the ` +
        * @returns {Promise<void>} - Resolves once it is asked for or dismissed.
        */
       async function openBakeDialog(id, stack) {
+        const title = stack?.title ?? id;
+        const day = new Date().toISOString().slice(0, 10).replaceAll('-', '');
+
         $('bake-stack').textContent = id;
         $('bake-error').textContent = '';
-        $('bake-name').value = stack?.title ?? id;
-        $('bake-description').value = stack?.description ?? '';
+        $('bake-name').value = `${title} ${day}`;
+        $('bake-file').value = `${bakeSlug(title)}-${day}.pmtiles`;
+        // Blank rather than the stack's own description. A recipe describes
+        // how tiles are combined; an archive describes what it is, and only
+        // the person exporting it knows that.
+        $('bake-description').value = '';
         $('bake-categories').value = (stack?.categories ?? []).join(', ');
         showBakeFilename();
         $('bake-location').innerHTML = locationPicker('bake-loc');
@@ -7754,28 +7770,46 @@ Every piece is hashed against the ` +
       }
 
       /**
-       * Shows what the file will be called, as the name is typed.
+       * A name reduced to something usable as one path segment.
+       *
+       * The same rules `safeSegment` applies on the server, and a test holds
+       * the two together — a field that shows one filename while the server
+       * writes another is worse than a field that shows nothing.
+       * @param {string} typed - What somebody entered.
+       * @returns {string} - A safe segment, never empty.
+       */
+      function bakeSlug(typed) {
+        const slug = typed
+          .replace(/[/\\<>:"|?*\u0000-\u001f\u007f -]/g, '-')
+          .replace(/-{2,}/g, '-')
+          .replace(/^[.\s-]+/, '')
+          .replace(/[.\s-]+$/, '')
+          .slice(0, 120)
+          .replace(/[.\s-]+$/, '');
+        return slug || 'stack';
+      }
+
+      /**
+       * Says what the file will actually be called, where that differs.
        *
-       * The same rules the server applies, because a name is not a filename:
-       * separators and the characters Windows refuses become dashes, and the
-       * date is appended so successive builds do not collide. Seeing that
-       * before pressing the button beats finding it on disk afterwards.
+       * A filename is exactly the kind of field somebody puts a slash in, and
+       * the server reduces it to one path segment before joining it to a
+       * directory. Saying so here means it is not a surprise.
        * @returns {void}
        */
       function showBakeFilename() {
-        const typed = $('bake-name').value.trim() || $('bake-stack').textContent;
-        const slug =
-          typed
-            .replace(/[/\\<>:"|?*\u0000-\u001f\u007f -]/g, '-')
-            .replace(/-{2,}/g, '-')
-            .replace(/^[.\s-]+/, '')
-            .replace(/[.\s-]+$/, '')
-            .slice(0, 120) || 'stack';
-        const day = new Date().toISOString().slice(0, 10).replaceAll('-', '');
-        $('bake-filename').textContent = `${slug}-${day}.pmtiles`;
+        const typed = $('bake-file').value.trim();
+        const note = $('bake-filename');
+        if (!typed) {
+          note.textContent = 'Left empty, it is named after the stack and dated.';
+          return;
+        }
+        const settled = `${bakeSlug(typed.replace(/\.pmtiles$/i, ''))}.pmtiles`;
+        note.textContent =
+          settled === typed ? '' : `Saved as ${settled}`;
       }
 
-      $('bake-name').addEventListener('input', showBakeFilename);
+      $('bake-file').addEventListener('input', showBakeFilename);
 
       $('bake-form').addEventListener('submit', async (event) => {
         if (event.submitter?.value === 'cancel') return;
@@ -7787,6 +7821,7 @@ Every piece is hashed against the ` +
           .map((one) => one.trim())
           .filter(Boolean);
         const name = $('bake-name').value.trim();
+        const filename = $('bake-file').value.trim();
         const description = $('bake-description').value.trim();
 
         try {
@@ -7796,6 +7831,7 @@ Every piece is hashed against the ` +
               ...chosenLocation('bake-loc'),
               ...(categories.length > 0 ? { categories } : {}),
               ...(name ? { name } : {}),
+              ...(filename ? { filename } : {}),
               ...(description ? { description } : {}),
             },
           });