storymaps 1.3.3 → 1.3.5

package/README.md

@@ -180,7 +180,9 @@ storymaps backup -m "Before the workshop"    # with a note
 storymaps backup storymaps.io/abc123         # back up a map you haven't pulled
 ```
 
-The backup shows in the map's activity log, and in **Menu → Backups** in the app.
+The backup shows in the map's activity log, and in **Menu → Backups** in the app. If the map hasn't changed since one of its backups, no new backup is made, and the CLI says which backup matches.
+
+**Locked maps** use the password saved by `storymaps unlock`, or ask for it.
 
 ### `backups`
 
@@ -209,7 +211,8 @@ storymaps restore 6e40f124ae7e --force       # restores without asking
 ### About backups
 
 - The CLI and the app share the same backups. A backup made in the app shows in `storymaps backups`, and one made with the CLI shows in the app.
-- The server keeps the newest 8 backups of each map.
+- The server keeps the newest 8 backups of each map. Backups are protected from deletion, but can be removed if needed by contacting us.
+- Making a backup of a locked map needs its password, so nobody else can push its backups out.
 - A self-hosted server needs updating before the CLI can make backups on it. An older one turns the request away, and the CLI says so.
 
 ### `validate`

package/bin/storymaps.js

@@ -24,7 +24,7 @@ const program = new Command();
 
 program
     .name('storymaps')
-    .description('CLI companion for storymaps.io — manage user story maps from the terminal')
+    .description('CLI companion for storymaps.io: manage user story maps from the terminal')
     .version(pkg.version)
     .showHelpAfterError()
     .addHelpText('after', '\nRun storymaps <command> --help for details on a specific command.');

package/lib/commands/backup.js

@@ -14,7 +14,12 @@ const cards = (n) => `${n} card${n === 1 ? '' : 's'}`;
 
 export async function backupCommand(target, opts) {
     const { id, baseUrl } = await resolveTarget(target, resolve(opts.file || 'storymap.yml'));
-    const backup = await createBackup(baseUrl, id, opts.message || '');
+    const lockPasswordHash = await lockPassword(baseUrl, id);
+    const backup = await createBackup(baseUrl, id, opts.message || '', { lockPasswordHash });
+    if (backup.unchanged) {
+        console.log(`No changes since backup ${chalk.cyan(backup.id)} from ${formatTime(backup.timestamp)}, so no new backup was made.`);
+        return;
+    }
     console.log(chalk.green(`Backed up map ${id} as ${backup.id} (${cards(backup.cardCount)})`));
 }
 
@@ -82,7 +87,7 @@ export async function restoreCommand(backupId, target, opts) {
     const lockPasswordHash = await lockPassword(baseUrl, id);
 
     // Like the app: a backup of the map as it is now, so the restore can be undone
-    const safety = await createBackup(baseUrl, id, 'Auto: before restore');
+    const safety = await createBackup(baseUrl, id, 'Auto: before restore', { lockPasswordHash });
     await putMap(baseUrl, id, backup.data, { contentType: 'application/json', lockPasswordHash, restoredBackup: backup.id });
 
     console.log(chalk.green(`Restored map ${id} from backup ${backup.id}`));

package/lib/commands/init.js

@@ -6,7 +6,8 @@ import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { confirm } from '@inquirer/prompts';
 import chalk from 'chalk';
-import { postMap } from '../util/api.js';
+import { getMap, postMap } from '../util/api.js';
+import { writeEtag } from '../util/file.js';
 
 function template(site) {
     const siteLine = site ? `site: ${site}\n` : '';
@@ -75,8 +76,9 @@ export async function initCommand(opts) {
         : `https://${site}`;
 
     let output = template(site);
+    let id = null;
     try {
-        const { id } = await postMap(baseUrl, output, 'text/yaml');
+        ({ id } = await postMap(baseUrl, output, 'text/yaml'));
         output = output.replace(/^(name: My Story Map\n)/, `$1id: ${id}\n`);
         console.log(chalk.green(`Created storymap.yml (map ID: ${id})`));
         console.log(`${chalk.cyan(`${baseUrl}/${id}`)}\n`);
@@ -86,5 +88,12 @@ export async function initCommand(opts) {
     }
 
     await writeFile(filePath, output, 'utf-8');
+    // The file matches the new map, so the first push from it stops if the map changes in the browser first
+    if (id) {
+        try {
+            const { etag } = await getMap(baseUrl, id);
+            await writeEtag(id, filePath, etag);
+        } catch { /* non-fatal */ }
+    }
     console.log(highlightYaml(output));
 }

package/lib/commands/lock.js

@@ -14,7 +14,7 @@ export async function lockCommand(target, opts) {
     try {
         ({ id, baseUrl } = await resolveTarget(target, filePath));
     } catch {
-        console.error(chalk.red('No map ID found. Run "storymaps new" first to reserve an ID, or pass one directly: storymaps lock <id>'));
+        console.error(chalk.red('No map ID found. Run "storymaps push" to create it on the server, or pass one directly: storymaps lock <id>'));
         process.exitCode = 1;
         return;
     }

package/lib/commands/pull.js

@@ -8,7 +8,7 @@ import { confirm } from '@inquirer/prompts';
 import chalk from 'chalk';
 import jsyaml from 'js-yaml';
 import { exportToYaml, yamlObjToJson } from '../core/yaml.js';
-import { detectFormat, writeCache } from '../util/file.js';
+import { detectFormat, writeEtag } from '../util/file.js';
 import { resolveTarget } from '../util/identity.js';
 import { getMap } from '../util/api.js';
 import { printChangeSummary } from '../util/summary.js';
@@ -32,7 +32,7 @@ export async function pullCommand(target, opts) {
 
         // Quick check: if raw content is identical, nothing to do
         if (oldContent === data) {
-            if (etag) await writeCache(id, { etag });
+            await writeEtag(id, filePath, etag);
             console.log(chalk.dim('Already up to date.'));
             return;
         }
@@ -64,8 +64,6 @@ export async function pullCommand(target, opts) {
     }
 
     await writeFile(filePath, data, 'utf-8');
-    if (etag) {
-        await writeCache(id, { etag });
-    }
+    await writeEtag(id, filePath, etag);
     console.log(chalk.green(`Pulled map ${id} → ${filePath}`));
 }

package/lib/commands/push.js

@@ -11,7 +11,16 @@ import { exportToYaml, importFromYaml, yamlObjToJson } from '../core/yaml.js';
 import { printChangeSummary } from '../util/summary.js';
 import { resolveTarget } from '../util/identity.js';
 import { getMap, putMap, postMap, ApiError } from '../util/api.js';
-import { detectFormat, readCache, writeCache } from '../util/file.js';
+import { detectFormat, readCache, readEtag, writeEtag } from '../util/file.js';
+
+// The map as it is on the server now is what this file matches, so a later push from it stops if
+// the map changes in the meantime
+async function rememberEtag(baseUrl, id, filePath) {
+    try {
+        const { etag } = await getMap(baseUrl, id);
+        await writeEtag(id, filePath, etag);
+    } catch { /* non-fatal */ }
+}
 
 function siteToBaseUrl(site) {
     if (!site) return 'https://storymaps.io';
@@ -48,7 +57,7 @@ export async function pushCommand(target, opts) {
     try {
         ({ id, baseUrl } = await resolveTarget(target, filePath));
     } catch {
-        // No ID in file — create a new map on the server
+        // No ID in the file: create a new map on the server
         const obj = jsyaml.load(content);
         baseUrl = siteToBaseUrl(obj?.site);
         const contentType = format === 'json' ? 'application/json' : 'text/yaml';
@@ -63,6 +72,7 @@ export async function pushCommand(target, opts) {
             updated = `id: ${id}\n${content}`;
         }
         await writeFile(filePath, updated, 'utf-8');
+        await rememberEtag(baseUrl, id, filePath);
 
         const url = `${baseUrl}/${id}`;
         console.log(chalk.green(`Created new map: ${url}`));
@@ -79,15 +89,14 @@ export async function pushCommand(target, opts) {
         if (remoteNorm !== localNorm) printChangeSummary(remoteNorm, localNorm);
     } catch { /* non-fatal */ }
 
-    const cache = await readCache(id);
-    let etag = opts.force ? undefined : cache.etag;
-    let lockPasswordHash = cache.hash;
+    let etag = opts.force ? undefined : await readEtag(id, filePath);
+    let lockPasswordHash = (await readCache(id)).hash;
 
     try {
         await putMap(baseUrl, id, content, { etag, contentType, lockPasswordHash });
     } catch (err) {
         if (err instanceof ApiError && err.conflict) {
-            console.error(chalk.red('Conflict — the remote map has changed since you last pulled.'));
+            console.error(chalk.red('Conflict: the remote map has changed since you last pulled.'));
             console.error(`Run ${chalk.cyan('storymaps pull')} to update, or use ${chalk.cyan('--force')} to overwrite.`);
             process.exit(1);
         }
@@ -109,13 +118,8 @@ export async function pushCommand(target, opts) {
         }
     }
 
-    // Refresh saved etag so the next push is also protected
-    try {
-        const remote = await getMap(baseUrl, id);
-        if (remote.etag) {
-            await writeCache(id, { etag: remote.etag });
-        }
-    } catch { /* non-fatal */ }
+    // Refresh this file's ETag so the next push from it is also protected
+    await rememberEtag(baseUrl, id, filePath);
 
     const url = `${baseUrl}/${id}`;
     console.log(chalk.green(`Pushed to ${url}`));

package/lib/commands/status.js

@@ -127,7 +127,7 @@ export async function statusCommand(target, opts) {
             const total = cards.length;
             const label = (slice.name || '(unnamed)').padEnd(maxName);
             if (total === 0) {
-                console.log(`  ${chalk.dim(label)}  — empty`);
+                console.log(`  ${chalk.dim(label)}  (empty)`);
                 continue;
             }
             const done = cards.filter(c => c.status === 'done').length;
@@ -162,7 +162,7 @@ export async function statusCommand(target, opts) {
     if (byStatus.blocked.length > 0) {
         console.log(chalk.red.bold('Blocked'));
         for (const story of byStatus.blocked) {
-            console.log(`  ${chalk.red('●')} ${story.name}${story.body ? chalk.dim(` — ${story.body.split('\n')[0]}`) : ''}`);
+            console.log(`  ${chalk.red('●')} ${story.name}${story.body ? chalk.dim(`: ${story.body.split('\n')[0]}`) : ''}`);
         }
         console.log();
     }

package/lib/commands/unlock.js

@@ -15,7 +15,7 @@ export async function unlockCommand(target, opts) {
     try {
         ({ id, baseUrl } = await resolveTarget(target, filePath));
     } catch {
-        console.error(chalk.red('No map ID found. Run "storymaps new" first to reserve an ID, or pass one directly: storymaps unlock <id>'));
+        console.error(chalk.red('No map ID found. Run "storymaps push" to create it on the server, or pass one directly: storymaps unlock <id>'));
         process.exitCode = 1;
         return;
     }

package/lib/core/yaml.js

@@ -198,9 +198,24 @@ export function jsonToYamlObj(data) {
 // Import: YAML string → JSON (compatible with deserializeV1)
 // ============================================================================
 
+// YAML aliases let a few hundred bytes stand for millions of values (an "alias bomb"), which
+// would run the server out of memory once read. Count the values, an alias each time it is
+// used, and stop well above the size of any real story map.
+const MAX_YAML_VALUES = 1_000_000;
+const checkYamlSize = (root) => {
+    let count = 0;
+    const stack = [root];
+    while (stack.length) {
+        const value = stack.pop();
+        if (++count > MAX_YAML_VALUES) throw new Error('YAML is too large');
+        if (value && typeof value === 'object') for (const child of Object.values(value)) stack.push(child);
+    }
+};
+
 export function importFromYaml(yamlString) {
     const obj = jsyaml.load(yamlString);
     if (!obj || typeof obj !== 'object') throw new Error('Invalid YAML');
+    checkYamlSize(obj);
     const validation = validateYaml(obj);
     if (!validation.valid) {
         const err = new Error(validation.errors.join('\n'));

package/lib/util/api.js

@@ -32,9 +32,9 @@ async function handleResponse(res) {
     const body = errorMessage(await res.text().catch(() => ''));
     switch (res.status) {
         case 404: throw new ApiError('Map not found', 404);
-        case 409: throw new ApiError(body || 'Conflict — the remote map has changed. Pull first or use --force.', 409, { conflict: true });
+        case 409: throw new ApiError(body || 'Conflict: the remote map has changed. Pull first or use --force.', 409, { conflict: true });
         case 423: throw new ApiError('Map is locked', 423);
-        case 429: throw new ApiError('Rate limited — please wait and try again', 429);
+        case 429: throw new ApiError('Rate limited. Please wait and try again.', 429);
         default: throw new ApiError(body || `Request failed (${res.status})`, res.status);
     }
 }
@@ -135,10 +135,13 @@ export async function getBackup(baseUrl, id, backupId) {
     return res.json();
 }
 
-export async function createBackup(baseUrl, id, note = '') {
+// Answers with the new backup, or with a kept backup marked unchanged when the map matches it
+export async function createBackup(baseUrl, id, note = '', { lockPasswordHash } = {}) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (lockPasswordHash) headers['X-Lock-Password'] = lockPasswordHash;
     const res = await request(`${baseUrl}/api/backups/${id}`, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
+        headers,
         body: JSON.stringify({ note }),
     });
     // Servers from before the CLI could make backups turn the request away

package/lib/util/file.js

@@ -32,6 +32,21 @@ export async function writeCache(mapId, updates) {
     await writeFile(cachePathFor(mapId), JSON.stringify(cache), 'utf-8');
 }
 
+// The ETag of the map as each file last pulled or pushed it, by the file's full path. Two copies of
+// one map on the same computer each keep their own, so a push from an older copy stops with a
+// conflict instead of overwriting what the other pushed. Versions up to 1.3.4 kept one ETag per map;
+// it's still read for files pulled with them, and no longer written.
+export async function readEtag(mapId, filePath) {
+    const cache = await readCache(mapId);
+    return cache.files?.[filePath] ?? cache.etag;
+}
+
+export async function writeEtag(mapId, filePath, etag) {
+    if (!etag) return;
+    const cache = await readCache(mapId);
+    await writeCache(mapId, { files: { ...cache.files, [filePath]: etag } });
+}
+
 
 export function detectFormat(filePath) {
     const ext = extname(filePath).toLowerCase();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "storymaps",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "description": "CLI tool for storymaps.io - import, export, validate, and manage user story maps from the terminal",
   "type": "module",
   "bin": {