storymaps 1.3.1 → 1.3.3

package/README.md

@@ -38,6 +38,16 @@ npm install
 npm link
 ```
 
+## Use with AI Coding Agents
+
+A story map makes a good specification for an AI coding agent: the YAML lists every step of the journey and the cards under each one, slice by slice. **Build with AI** on storymaps.io writes the command for you:
+
+```bash
+npx storymaps pull --force storymaps.io/abc123 && claude "The storymap file @storymap.yml describes a product plan in user story map format. Use it as a structured specification. Your task: build a functional prototype of the features listed in the 'MVP' slice."
+```
+
+From there you steer the agent a slice or a feature at a time ("now build search from the V1 slice"). When a feature has been through QA, set its cards to `status: done` in `storymap.yml` and `storymaps push`, so the map shows the progress to everyone else. Pull again before the next round to pick up changes made in the browser.
+
 ## Quick Start
 
 ```bash
@@ -160,17 +170,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 +222,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`
 
@@ -287,16 +327,6 @@ Cards support: `name`, `body`, `color`, `status` (done / in-progress / planned /
 
 Slices support: `name`, `stories`, `goal` (up to 200 characters), `targetDate` (`YYYY-MM-DD`), and `collapsed` with `closedReason` (complete / closed).
 
-## Use with AI Coding Agents
-
-A story map makes a good specification for an AI coding agent: the YAML lists every step of the journey and the cards under each one, slice by slice. **Build with AI** on storymaps.io writes the command for you:
-
-```bash
-npx storymaps pull --force storymaps.io/abc123 && claude "The storymap file @storymap.yml describes a product plan in user story map format. Use it as a structured specification. Your task: build a functional prototype of the features listed in the 'MVP' slice."
-```
-
-From there you steer the agent a slice or a feature at a time ("now build search from the V1 slice"). When a feature has been through QA, set its cards to `status: done` in `storymap.yml` and `storymaps push`, so the map shows the progress to everyone else. Pull again before the next round to pick up changes made in the browser.
-
 ## Self-Hosting
 
 The CLI works with any storymaps.io instance:

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.3",
   "description": "CLI tool for storymaps.io - import, export, validate, and manage user story maps from the terminal",
   "type": "module",
   "bin": {