storymaps 1.3.0 → 1.3.2

package/README.md

@@ -138,9 +138,10 @@ storymaps diff file1.yml file2.yml    # compare two local files
 ```bash
 storymaps status                      # progress overview of storymap.yml
 storymaps status other.yml            # progress overview of a specific file
+storymaps status storymaps.io/abc123  # progress overview of a map on the server, no file needed
 ```
 
-Progress overview: slices, status counts, and blocked stories.
+Progress overview: slices, status counts, and blocked stories. A link to a map inside a project works too.
 
 ### `log`
 
@@ -159,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`
 
@@ -181,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

@@ -99,7 +99,7 @@ program
 program
     .command('status')
     .description('Show a progress overview of the story map')
-    .argument('[file]', 'path to storymap file')
+    .argument('[target]', 'storymap file, or a map ID, domain/ID, or full URL')
     .option('-f, --file <path>', 'path to storymap file', 'storymap.yml')
     .action(statusCommand);
 
@@ -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/commands/status.js

@@ -5,6 +5,8 @@ import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import chalk from 'chalk';
 import jsyaml from 'js-yaml';
+import { resolveTarget } from '../util/identity.js';
+import { getMap, ApiError } from '../util/api.js';
 
 const STATUS_ICONS = {
     'done':        chalk.green('●'),
@@ -24,16 +26,34 @@ function pct(n, total) {
     return `${Math.round((n / total) * 100)}%`;
 }
 
-export async function statusCommand(target, opts) {
-    const filePath = resolve(target || opts.file || 'storymap.yml');
-
-    let content;
+// A local file, or else the map on the server when the target is a link or map ID
+async function loadContent(target, opts) {
+    const isUrl = target && /^https?:\/\//i.test(target);
+    const filePath = resolve((!isUrl && target) || opts.file || 'storymap.yml');
+    if (!isUrl) {
+        try {
+            return await readFile(filePath, 'utf-8');
+        } catch {
+            if (!target) {
+                console.error(chalk.red(`File not found: ${filePath}`));
+                process.exit(1);
+            }
+        }
+    }
+    const { id, baseUrl } = await resolveTarget(target, resolve(opts.file || 'storymap.yml'));
     try {
-        content = await readFile(filePath, 'utf-8');
-    } catch {
-        console.error(chalk.red(`File not found: ${filePath}`));
-        process.exit(1);
+        return (await getMap(baseUrl, id, 'yaml')).data;
+    } catch (err) {
+        if (err instanceof ApiError && err.status === 404 && !isUrl && !target.includes('/')) {
+            console.error(chalk.red(`No file or map found: ${target}`));
+            process.exit(1);
+        }
+        throw err;
     }
+}
+
+export async function statusCommand(target, opts) {
+    const content = await loadContent(target, opts);
 
     const map = jsyaml.load(content);
     if (!map || typeof map !== 'object') {

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