storymaps 1.3.1 → 1.3.2

package/README.md

@@ -160,17 +160,47 @@ storymaps unlock                      # session unlock
 storymaps unlock --remove             # permanently remove the lock
 ```
 
-### `backup` / `backups` / `restore`
+### `backup`
+
+Backs up the map on the server. Add a note to tell the backup apart later.
 
 ```bash
-storymaps backup                      # back up the map on the server
+storymaps backup                             # back up the map in storymap.yml
 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
+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.
+
+### `backups`
+
+Lists a map's backups, newest first, with the ID you need to restore one.
+
+```bash
+> storymaps backups
+
+6e40f124ae7e  13:25  63 cards   Before the workshop
+998e16f31f84  11:02  58 cards   (no note)
 ```
 
-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.
+### `restore`
+
+Puts the map back the way it was in one of its backups. Give it the backup ID from `storymaps backups`.
+
+```bash
+storymaps restore 6e40f124ae7e               # asks before it restores
+storymaps restore 6e40f124ae7e --force       # restores without asking
+```
+
+- **It backs up first.** Before restoring, the CLI backs up the map as it is now, so a restore can be undone with another restore.
+- **It changes the server, not your file.** Run `storymaps pull` afterwards to get the restored map. Until you do, `storymaps push` stops with a conflict, so an old local file can't undo the restore by accident.
+- **Locked maps** use the password saved by `storymaps unlock`, or ask for it.
+
+### 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.
+- 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`
 
@@ -182,7 +212,7 @@ storymaps validate storymap.yml       # check YAML structure
 
 A target can be a map ID, `domain/id`, or a full URL, including a map inside a project link (`storymaps.io/p/<project>/<map>`).
 
-`pull`, `push`, `open`, `lock`, `unlock`, `status` and `log` take `-f, --file <path>` to use a file other than `storymap.yml`.
+`pull`, `push`, `open`, `lock`, `unlock`, `status`, `log`, `backup`, `backups` and `restore` take `-f, --file <path>` to use a file other than `storymap.yml`.
 
 ### `convert`
 

package/bin/storymaps.js

@@ -128,7 +128,7 @@ program
 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('<backup-id>', 'the ID of a backup, 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')

package/lib/commands/backup.js

@@ -33,7 +33,7 @@ export async function backupsCommand(target, opts) {
         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>')}`));
+    console.log(chalk.dim(`\nRestore one with ${chalk.cyan('storymaps restore <backup ID>')}`));
 }
 
 // The lock password for a locked map, checked with the server before anything changes.
@@ -83,7 +83,7 @@ export async function restoreCommand(backupId, target, opts) {
 
     // 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 });
+    await putMap(baseUrl, id, backup.data, { contentType: 'application/json', lockPasswordHash, restoredBackup: backup.id });
 
     console.log(chalk.green(`Restored map ${id} from backup ${backup.id}`));
     console.log(chalk.dim(`The map before the restore is backup ${safety.id}.`));

package/lib/util/api.js

@@ -47,10 +47,12 @@ export async function getMap(baseUrl, id, format = 'yaml') {
     return { data, etag };
 }
 
-export async function putMap(baseUrl, id, body, { etag, contentType = 'text/yaml', lockPasswordHash } = {}) {
+export async function putMap(baseUrl, id, body, { etag, contentType = 'text/yaml', lockPasswordHash, restoredBackup } = {}) {
     const headers = { 'Content-Type': contentType };
     if (etag) headers['If-Match'] = etag;
     if (lockPasswordHash) headers['X-Lock-Password'] = lockPasswordHash;
+    // Tells the server this push is a restore, so the activity log says so
+    if (restoredBackup) headers['X-Restored-Backup'] = restoredBackup;
     const res = await request(`${baseUrl}/api/maps/${id}`, {
         method: 'PUT',
         headers,

package/package.json

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