storymaps 1.2.9 → 1.3.0

package/README.md

@@ -159,6 +159,18 @@ storymaps unlock                      # session unlock
 storymaps unlock --remove             # permanently remove the lock
 ```
 
+### `backup` / `backups` / `restore`
+
+```bash
+storymaps backup                      # back up the map on the server
+storymaps backup -m "Before the workshop"    # with a note
+storymaps backups                     # list the backups, newest first
+storymaps restore 7ed8450a830a        # restore one, after backing up the map as it is now
+storymaps restore 7ed8450a830a --force       # restore without asking first
+```
+
+These are the same backups as **Menu → Backups** in the app, and the server keeps the newest 8 of each map. A restore changes the map on the server, not your local file, so run `storymaps pull` afterwards. Until you do, `storymaps push` stops with a conflict, so an old local file can't undo the restore. On a locked map, restore asks for the password, or uses the one saved by `storymaps unlock`. A self-hosted server needs updating before the CLI can make backups on it.
+
 ### `validate`
 
 ```bash

package/bin/storymaps.js

@@ -17,6 +17,7 @@ import { lockCommand } from '../lib/commands/lock.js';
 import { unlockCommand } from '../lib/commands/unlock.js';
 import { statusCommand } from '../lib/commands/status.js';
 import { logCommand } from '../lib/commands/log.js';
+import { backupCommand, backupsCommand, restoreCommand } from '../lib/commands/backup.js';
 
 
 const program = new Command();
@@ -109,6 +110,30 @@ program
     .option('-f, --file <path>', 'local file path', 'storymap.yml')
     .action(logCommand);
 
+program
+    .command('backup')
+    .description('Back up a map on the server')
+    .argument('[target]', 'map ID, domain/ID, or full URL')
+    .option('-f, --file <path>', 'local file path', 'storymap.yml')
+    .option('-m, --message <note>', 'a note to tell the backup apart')
+    .action(backupCommand);
+
+program
+    .command('backups')
+    .description('List the backups of a map, newest first')
+    .argument('[target]', 'map ID, domain/ID, or full URL')
+    .option('-f, --file <path>', 'local file path', 'storymap.yml')
+    .action(backupsCommand);
+
+program
+    .command('restore')
+    .description('Restore a map from one of its backups, after backing up the map as it is now')
+    .argument('<backup>', 'backup ID, from storymaps backups')
+    .argument('[target]', 'map ID, domain/ID, or full URL')
+    .option('-f, --file <path>', 'local file path', 'storymap.yml')
+    .option('--force', 'restore without asking first')
+    .action(restoreCommand);
+
 program.parseAsync().catch(err => {
     const message = err.name === 'ExitPromptError' ? 'Cancelled.'
         : err.message || String(err);

package/lib/commands/backup.js

@@ -0,0 +1,92 @@
+// Storymaps CLI — AGPL-3.0 — see LICENCE for details
+// storymaps backup, backups and restore - make, list and restore backups of a map on the server
+
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import chalk from 'chalk';
+import { confirm, password } from '@inquirer/prompts';
+import { resolveTarget } from '../util/identity.js';
+import { createBackup, listBackups, getBackup, getLockStatus, unlockMap, putMap, ApiError } from '../util/api.js';
+import { readCache, writeCache } from '../util/file.js';
+import { formatTime } from '../util/time.js';
+
+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 || '');
+    console.log(chalk.green(`Backed up map ${id} as ${backup.id} (${cards(backup.cardCount)})`));
+}
+
+export async function backupsCommand(target, opts) {
+    const { id, baseUrl } = await resolveTarget(target, resolve(opts.file || 'storymap.yml'));
+    const backups = await listBackups(baseUrl, id);
+
+    if (backups.length === 0) {
+        console.log(chalk.dim(`No backups yet. Run ${chalk.cyan('storymaps backup')} to make one.`));
+        return;
+    }
+
+    // Newest first, like the log
+    for (const b of [...backups].reverse()) {
+        const note = b.note || chalk.dim('(no note)');
+        const imported = b.imported ? chalk.dim('  imported') : '';
+        console.log(`${chalk.cyan(b.id)}  ${chalk.dim(formatTime(b.timestamp))}  ${cards(b.cardCount).padEnd(9)}  ${note}${imported}`);
+    }
+    console.log(chalk.dim(`\nRestore one with ${chalk.cyan('storymaps restore <backup>')}`));
+}
+
+// The lock password for a locked map, checked with the server before anything changes.
+// The saved one from storymaps unlock is tried first.
+async function lockPassword(baseUrl, id) {
+    const { isLocked } = await getLockStatus(baseUrl, id);
+    if (!isLocked) return undefined;
+
+    const saved = (await readCache(id)).hash;
+    if (saved) {
+        try {
+            await unlockMap(baseUrl, id, saved);
+            return saved;
+        } catch (err) {
+            if (!(err instanceof ApiError && err.status === 403)) throw err;
+        }
+    }
+
+    console.log(chalk.yellow('Map is locked.'));
+    const pw = await password({ theme: { prefix: '>' }, message: 'Password:' });
+    const hash = createHash('sha256').update(pw).digest('hex');
+    await unlockMap(baseUrl, id, hash);
+    await writeCache(id, { hash });
+    return hash;
+}
+
+export async function restoreCommand(backupId, target, opts) {
+    const filePath = resolve(opts.file || 'storymap.yml');
+    const { id, baseUrl } = await resolveTarget(target, filePath);
+    const backup = await getBackup(baseUrl, id, backupId);
+    const note = backup.note ? `, "${backup.note}"` : '';
+    console.log(`Backup ${backup.id} from ${formatTime(backup.timestamp)}: ${backup.mapName || 'Untitled'}, ${cards(backup.cardCount)}${note}`);
+
+    if (!opts.force) {
+        const ok = await confirm({
+            message: 'Restore this backup? The map is backed up first.',
+            default: true,
+            theme: { prefix: '>' },
+        });
+        if (!ok) {
+            console.log('Aborted.');
+            return;
+        }
+    }
+
+    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');
+    await putMap(baseUrl, id, backup.data, { contentType: 'application/json', lockPasswordHash });
+
+    console.log(chalk.green(`Restored map ${id} from backup ${backup.id}`));
+    console.log(chalk.dim(`The map before the restore is backup ${safety.id}.`));
+    // The saved ETag is left alone, so a push from an old local file stops with a conflict
+    console.log(`Run ${chalk.cyan('storymaps pull')} to bring the restored map into your local file.`);
+}

package/lib/commands/log.js

@@ -5,16 +5,7 @@ import { resolve } from 'node:path';
 import chalk from 'chalk';
 import { resolveTarget } from '../util/identity.js';
 import { getLog } from '../util/api.js';
-
-function formatTime(ts) {
-    const d = new Date(ts);
-    const now = new Date();
-    const pad = (n) => String(n).padStart(2, '0');
-    const time = `${pad(d.getHours())}:${pad(d.getMinutes())}`;
-
-    if (d.toDateString() === now.toDateString()) return time;
-    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${time}`;
-}
+import { formatTime } from '../util/time.js';
 
 function sourceLabel(entry) {
     if (entry.src === 'cli') return '>_';

package/lib/util/api.js

@@ -120,4 +120,29 @@ export async function getLog(baseUrl, id) {
     return res.json();
 }
 
+export async function listBackups(baseUrl, id) {
+    const res = await request(`${baseUrl}/api/backups/${id}`);
+    await handleResponse(res);
+    return res.json();
+}
+
+export async function getBackup(baseUrl, id, backupId) {
+    const res = await request(`${baseUrl}/api/backups/${id}/${encodeURIComponent(backupId)}`);
+    if (res.status === 404) throw new ApiError(`Backup not found: ${backupId}`, 404);
+    await handleResponse(res);
+    return res.json();
+}
+
+export async function createBackup(baseUrl, id, note = '') {
+    const res = await request(`${baseUrl}/api/backups/${id}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ note }),
+    });
+    // Servers from before the CLI could make backups turn the request away
+    if (res.status === 403) throw new ApiError('This server does not take backups from the CLI yet. Make the backup in the app, or update the server', 403);
+    await handleResponse(res);
+    return res.json();
+}
+
 export { ApiError };

package/lib/util/time.js

@@ -0,0 +1,12 @@
+// Storymaps CLI — AGPL-3.0 — see LICENCE for details
+// Short local times: HH:MM for today, YYYY-MM-DD HH:MM for other days
+
+export function formatTime(ts) {
+    const d = new Date(ts);
+    const now = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    const time = `${pad(d.getHours())}:${pad(d.getMinutes())}`;
+
+    if (d.toDateString() === now.toDateString()) return time;
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${time}`;
+}

package/package.json

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