storymaps 1.2.8 → 1.3.0

package/README.md

@@ -23,6 +23,12 @@ Story maps are structured data. The CLI lets you export the structure behind the
 npm install -g storymaps
 ```
 
+Or run it without installing, the way the Build with AI command on storymaps.io does:
+
+```bash
+npx storymaps pull storymaps.io/abc123
+```
+
 Or clone and link locally:
 
 ```bash
@@ -43,6 +49,7 @@ Or pull an existing map:
 
 ```bash
 storymaps pull storymaps.io/abc123    # download as YAML
+storymaps pull storymaps.io/p/k8f2m9xq/abc123    # a map inside a project link works too
 ```
 
 Edit the YAML, then push it back:
@@ -104,17 +111,19 @@ storymaps open storymaps.io/abc123    # open a specific remote map
 ```bash
 storymaps pull                        # uses id/site from storymap.yml
 storymaps pull storymaps.io/abc123    # pull a specific map
+storymaps pull --force                # overwrite the local file without asking
 ```
 
-Shows a summary of changes before overwriting.
+Shows a summary of changes and asks before overwriting the local file, unless you pass `--force`.
 
 ### `push`
 
 ```bash
 storymaps push                        # push local changes to the server
+storymaps push --force                # skip the conflict check and overwrite the server copy
 ```
 
-If the file has no `id`, a new map is created on the server. Conflicts are detected using ETags. If the remote has changed since your last pull, you'll be prompted to pull first. Locked maps prompt for the password.
+If the file has no `id`, a new map is created on the server. Conflicts are detected using ETags. If the remote has changed since your last pull, you'll be prompted to pull first; `--force` pushes anyway and replaces whatever changed on the server. Locked maps prompt for the password.
 
 ### `diff`
 
@@ -150,12 +159,30 @@ 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
 storymaps validate storymap.yml       # check YAML structure
 ```
 
+### Options
+
+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`.
+
 ### `convert`
 
 ```bash
@@ -259,6 +286,16 @@ 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:
@@ -269,6 +306,8 @@ storymaps init --site storymaps.yourcompany.com
 
 See the [main project README](https://github.com/jackgleeson/storymaps.io#self-hosting) for setup instructions.
 
+Every request names the CLI and its version in the User-Agent header (`storymaps-cli/<version>`), so CLI use shows up as such in your server logs.
+
 ## Development
 
 ```bash
@@ -283,7 +322,7 @@ To try a change against a local storymaps.io server, run the CLI from the repo,
 ### Releasing
 
 1. Commit your changes on `main`.
-2. Bump the version in `package.json` and commit it as "Bump version to x.y.z". Use a patch for fixes and a minor version for new features.
+2. Bump the version in `package.json` and in both places near the top of `package-lock.json`, and commit it as "Bump version to x.y.z". Use a patch for fixes and a minor version for new features.
 3. Tag the commit and push both:
    ```bash
    git tag vx.y.z

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