storymaps 1.3.4 → 1.4.1

package/README.md

@@ -48,6 +48,15 @@ npx storymaps pull --force storymaps.io/abc123 && claude "The storymap file @sto
 
 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.
 
+For a [project](#projects) of several maps, pull the whole project, so the agent gets every map as one specification in `storymaps/`:
+
+```bash
+storymaps pull storymaps.io/p/k8f2m9xq        # every map, into storymaps/
+storymaps project unlock --maps               # if it's locked: once, in your terminal
+```
+
+Unlocking once remembers the password on this computer, so the agent can push without ever seeing it. Agents should pass `--yes` to take default answers, as some agent tools run commands in a terminal where a question would wait. In CI, give the password with `STORYMAPS_PASSWORD` instead.
+
 ## Quick Start
 
 ```bash
@@ -69,6 +78,82 @@ storymaps diff                        # see what changed
 storymaps push                        # sync to the server
 ```
 
+## Projects
+
+A project groups several story maps, such as one per team or per part of a product. The CLI keeps a whole project in one `storymaps/` folder, one file per map, named by map ID so renaming a map in the app never puts a file out of step:
+
+```bash
+storymaps pull storymaps.io/p/k8f2m9xq       # every map in the project, into storymaps/
+storymaps status                              # one line per map, and a total
+storymaps push                                # checks every map first, then pushes the ones that changed
+```
+
+```
+my-repo/
+└── storymaps/
+    ├── 1g2pt83x.yml      CLI
+    ├── wtuzo7nw.yml      Web App
+    └── 8166fkm0.yml      MCP Server
+```
+
+Each file says which project it's in, straight after its `id`:
+
+```yaml
+name: CLI
+id: 1g2pt83x
+project: k8f2m9xq
+site: storymaps.io
+```
+
+- **One rule.** `storymaps <command>` works on maps: one map with `-f` or a link, or every map in the project folder without one. `storymaps project <command>` changes the project itself.
+- **A link to one map in a project** asks the first time whether you want just that map or the whole project, since the app's address bar always shows a map inside its project.
+- **Push checks everything before it sends anything**: every file, every conflict and every password. A project never ends up half pushed. A file this computer never pulled, such as one from a fresh clone, stops push until you pull.
+- **The CLI never moves, renames or deletes your files**, so a map open in an editor never looks deleted. The one exception is a map started offline whose ID turns out to be taken by another map: it gets a fresh ID, and its file is renamed to match.
+- **A map removed from the project in the app** keeps its file, and pull takes its `project` key out. Push never adds a map back by accident.
+- **A project in reach wins**: `storymaps/` below you, or project files in the current folder, so commands work from the repo root. A `storymap.yml` beside a project is one `-f storymap.yml` away, and the command says so. A folder with only `storymap.yml` works exactly as before.
+
+### `project init`
+
+```bash
+storymaps project init --name "Coffee shop"                          # a new project with a first map
+storymaps project init --name "Coffee shop" ordering.yml loyalty.yml # a map from each file
+```
+
+The files you start from are left as they are, for you to delete.
+
+### `project add`
+
+```bash
+storymaps project add --name "Roadmap"        # a new map, even offline
+storymaps project add storymap.yml            # a map from outside the project
+storymaps project add storymaps.io/abc123     # an existing map, by link or ID
+storymaps project add --project storymaps.io/p/k8f2m9xq   # with no project folder yet
+```
+
+Online, the map is created and added straight away. Offline, the CLI makes the map ID and the next `push` creates the map and adds it.
+
+### `project lock` / `project unlock`
+
+```bash
+storymaps project lock                 # the project, or the project and its maps: the same two choices as the app
+storymaps project lock --maps          # include the maps that aren't locked yet, without asking
+storymaps project unlock               # on this computer
+storymaps project unlock --maps        # and the maps that use the project password
+storymaps project unlock --remove      # for everyone
+```
+
+A map with its own password keeps it. Renaming a project, and reordering, removing and deleting its maps, stay in the app.
+
+### Questions, scripts and agents
+
+The CLI only asks a question in a terminal. `-y, --yes` takes the default answers, and `--force` answers the questions that guard against overwriting or removing something. With no terminal and no flag, a question about how much to do takes its default and says so, and a guard stops and names the flag.
+
+Passwords are never flags. They're typed, remembered on this computer after `storymaps unlock` or `storymaps project unlock --maps`, or taken from the `STORYMAPS_PASSWORD` environment variable, for scripts and CI:
+
+```bash
+STORYMAPS_PASSWORD="$RELEASE_PASSWORD" storymaps project lock --maps
+```
+
 ## Status
 
 See the project status in a snapshot: 
@@ -98,6 +183,24 @@ Blocked
 
 Non-task cards (notes, questions) are excluded from counts based on the legend.
 
+In a project folder, `status` shows one line per map, in tab order, with its file and its lock, and a total:
+
+```bash
+> storymaps status
+
+Coffee shop
+https://storymaps.io/p/k8f2m9xq
+project locked
+
+  Ordering   rq4m8z2c.yml  ████████████████░░░░ 12/15 (80%)  locked
+  Loyalty    bt7k1w9e.yml  ██████░░░░░░░░░░░░░░  4/13 (31%)  locked
+  Barista    hx2p6n0d.yml  ░░░░░░░░░░░░░░░░░░░░  0/9  (0%)   own lock
+
+  Total                    ███████░░░░░░░░░░░░░ 16/37 stories (43%)
+```
+
+`locked` is a map locked with the project password, and `own lock` a map with its own password.
+
 ## Commands
 
 ### `init`
@@ -141,6 +244,7 @@ If the file has no `id`, a new map is created on the server. Conflicts are detec
 storymaps diff                        # summary of changes vs remote
 storymaps diff --full                 # full line-by-line diff
 storymaps diff file1.yml file2.yml    # compare two local files
+storymaps diff storymaps.io/abc123    # the local file of that map, compared with the server
 ```
 
 ### `status`
@@ -225,7 +329,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`, `log`, `backup`, `backups` and `restore` 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`. In a project folder, `pull`, `push`, `status`, `diff`, `open`, `backup` and `backups` work on every map without `-f`, and take `--dir <folder>` for a project folder other than `storymaps`. `validate storymaps` checks every map file in the folder, and `restore` finds which map a backup ID belongs to.
 
 ### `convert`
 

package/bin/storymaps.js

@@ -18,17 +18,21 @@ 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';
+import { projectInitCommand, projectAddCommand, projectLockCommand, projectUnlockCommand } from '../lib/commands/project.js';
 
 
 const program = new Command();
 
 program
     .name('storymaps')
-    .description('CLI companion for storymaps.io — manage user story maps from the terminal')
+    .description('CLI companion for storymaps.io: manage user story maps from the terminal')
     .version(pkg.version)
     .showHelpAfterError()
     .addHelpText('after', '\nRun storymaps <command> --help for details on a specific command.');
 
+const FILE_HELP = 'one map\'s file (default: storymap.yml, or every map in a project folder)';
+const DIR_HELP = 'the project folder (default: storymaps)';
+
 program
     .command('init')
     .description('Create a new storymap.yml in the current directory')
@@ -37,8 +41,8 @@ program
 
 program
     .command('validate')
-    .description('Validate a storymap YAML or JSON file')
-    .argument('<file>', 'path to storymap file')
+    .description('Validate a storymap YAML or JSON file, or every map file in a folder')
+    .argument('<file>', 'path to a storymap file, or a folder such as storymaps')
     .action(validateCommand);
 
 program
@@ -52,77 +56,85 @@ program
 
 program
     .command('pull')
-    .description('Download a map from the remote server')
-    .argument('[target]', 'map ID, domain/ID, or full URL')
-    .option('-f, --file <path>', 'local file path', 'storymap.yml')
-    .option('--force', 'overwrite local file without prompting')
+    .description('Download a map, or a whole project, from the remote server')
+    .argument('[target]', 'map ID, domain/ID, full URL, or a project link such as storymaps.io/p/<project>')
+    .option('-f, --file <path>', FILE_HELP)
+    .option('--dir <folder>', DIR_HELP)
+    .option('--force', 'overwrite local files without asking')
+    .option('-y, --yes', 'take the default answers, such as just the map for a link to a map in a project')
     .action(pullCommand);
 
 program
     .command('push')
-    .description('Upload a local map to the remote server')
+    .description('Upload a local map, or every map in a project folder, to the remote server')
     .argument('[target]', 'map ID, domain/ID, or full URL')
-    .option('-f, --file <path>', 'local file path', 'storymap.yml')
+    .option('-f, --file <path>', FILE_HELP)
+    .option('--dir <folder>', DIR_HELP)
     .option('--force', 'skip conflict check and overwrite remote')
     .action(pushCommand);
 
 program
     .command('diff')
-    .description('Compare a local file against the remote or another local file')
-    .argument('[source]', 'local file to compare (default: storymap.yml)')
+    .description('Compare a local file against the remote or another local file, or every map in a project folder')
+    .argument('[source]', 'local file to compare, or a map link or ID to compare its local file (default: storymap.yml)')
     .argument('[target]', 'second local file (omit to compare against remote)')
     .option('--full', 'show the full file instead of just changed regions')
+    .option('--dir <folder>', DIR_HELP)
     .action(diffCommand);
 
 program
     .command('open')
-    .description('Open a map in the default browser')
+    .description('Open a map, or a project, in the default browser')
     .argument('[target]', 'map ID, domain/ID, or full URL')
-    .option('-f, --file <path>', 'local file path', 'storymap.yml')
+    .option('-f, --file <path>', FILE_HELP)
+    .option('--dir <folder>', DIR_HELP)
     .action(openCommand);
 
 program
     .command('lock')
-    .description('Password-protect a map')
+    .description('Password-protect a map. For a whole project, use storymaps project lock')
     .argument('[target]', 'map ID, domain/ID, or full URL')
-    .option('-f, --file <path>', 'local file path', 'storymap.yml')
+    .option('-f, --file <path>', 'local file path (default: storymap.yml)')
     .action(lockCommand);
 
 program
     .command('unlock')
-    .description('Unlock a password-protected map')
+    .description('Unlock a password-protected map. For a whole project, use storymaps project unlock')
     .argument('[target]', 'map ID, domain/ID, or full URL')
-    .option('-f, --file <path>', 'local file path', 'storymap.yml')
+    .option('-f, --file <path>', 'local file path (default: storymap.yml)')
     .option('--remove', 'permanently remove the lock instead of session unlock')
     .action(unlockCommand);
 
 program
     .command('status')
-    .description('Show a progress overview of the story map')
-    .argument('[target]', 'storymap file, or a map ID, domain/ID, or full URL')
-    .option('-f, --file <path>', 'path to storymap file', 'storymap.yml')
+    .description('Show a progress overview of the story map, or of every map in a project')
+    .argument('[target]', 'storymap file, a map ID, domain/ID, full URL, or a project link')
+    .option('-f, --file <path>', FILE_HELP)
+    .option('--dir <folder>', DIR_HELP)
     .action(statusCommand);
 
 program
     .command('log')
     .description('Show activity log for a map')
     .argument('[target]', 'map ID, domain/ID, or full URL')
-    .option('-f, --file <path>', 'local file path', 'storymap.yml')
+    .option('-f, --file <path>', 'local file path (default: storymap.yml)')
     .action(logCommand);
 
 program
     .command('backup')
-    .description('Back up a map on the server')
+    .description('Back up a map, or every map in a project folder, on the server')
     .argument('[target]', 'map ID, domain/ID, or full URL')
-    .option('-f, --file <path>', 'local file path', 'storymap.yml')
+    .option('-f, --file <path>', FILE_HELP)
+    .option('--dir <folder>', DIR_HELP)
     .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')
+    .description('List the backups of a map, newest first, or the newest backup of each map in a project')
     .argument('[target]', 'map ID, domain/ID, or full URL')
-    .option('-f, --file <path>', 'local file path', 'storymap.yml')
+    .option('-f, --file <path>', FILE_HELP)
+    .option('--dir <folder>', DIR_HELP)
     .action(backupsCommand);
 
 program
@@ -130,13 +142,64 @@ program
     .description('Restore a map from one of its backups, after backing up the map as it is now')
     .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('-f, --file <path>', 'local file path (default: storymap.yml, or the map the backup belongs to in a project folder)')
+    .option('--dir <folder>', DIR_HELP)
     .option('--force', 'restore without asking first')
     .action(restoreCommand);
 
+// Commands that change a project itself. The other commands work on its maps.
+const project = program
+    .command('project')
+    .description('Start a project, add maps to it, or lock and unlock it');
+
+project
+    .command('init')
+    .description('Start a project with a first map, or with a map from each file, in storymaps/')
+    .argument('[files...]', 'map files to start the project from; they are left as they are')
+    .option('--name <name>', 'the project name (default: Untitled project)')
+    .option('--dir <folder>', DIR_HELP)
+    .option('-s, --site <site>', 'target site (e.g. localhost, storymaps.io)')
+    .action(projectInitCommand);
+
+project
+    .command('add')
+    .description('Add a map to the project: a new map, a map from a file, or an existing map')
+    .argument('[map]', 'a map file, or an existing map by ID or link (default: a new blank map)')
+    .option('--name <name>', 'the name of a new map (default: My Story Map)')
+    .option('--dir <folder>', DIR_HELP)
+    .option('--project <link>', 'the project, by link or ID, when there is no project folder yet')
+    .action(projectAddCommand);
+
+project
+    .command('lock')
+    .description('Lock the project, or the project and its maps')
+    .option('--maps', 'lock the maps that are not locked too, without asking')
+    .option('-y, --yes', 'take the default answer: the project alone')
+    .option('--dir <folder>', DIR_HELP)
+    .option('--project <link>', 'the project, by link or ID, when there is no project folder')
+    .action(projectLockCommand);
+
+project
+    .command('unlock')
+    .description('Unlock the project on this computer, or remove its lock for everyone')
+    .option('--remove', 'remove the lock for everyone')
+    .option('--maps', 'also unlock, or with --remove remove the lock from, the maps that use the project password')
+    .option('-y, --yes', 'take the default answers: the project only, and the map locks kept')
+    .option('--dir <folder>', DIR_HELP)
+    .option('--project <link>', 'the project, by link or ID, when there is no project folder')
+    .action(projectUnlockCommand);
+
 program.parseAsync().catch(err => {
     const message = err.name === 'ExitPromptError' ? 'Cancelled.'
+        // fetch says only "fetch failed" when the server can't be reached
+        : err.message === 'fetch failed' ? `Couldn't reach the server${err.cause?.code ? ` (${err.cause.code})` : ''}. Check your connection, or the site in the map file, and try again.`
         : err.message || String(err);
+    // A stop the CLI chose says what to do in its own words
+    if (err.name === 'StopError') {
+        console.error(chalk.red(message.split('\n')[0]) + (message.includes('\n') ? `\n${message.split('\n').slice(1).join('\n')}` : ''));
+        process.exitCode = 1;
+        return;
+    }
     console.error(chalk.red(message));
     process.exitCode = 1;
 });

package/lib/commands/backup.js

@@ -1,18 +1,27 @@
 // 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 { createBackup, listBackups, getBackup, getLockStatus, putMap } from '../util/api.js';
 import { formatTime } from '../util/time.js';
+import { findProjectFolder, shortPath } from '../util/project.js';
+import { singleMapPassword } from '../util/passwords.js';
+import { guard } from '../util/prompt.js';
+import { backupProject, backupsProject, findBackupMap } from './project-sync.js';
 
 const cards = (n) => `${n} card${n === 1 ? '' : 's'}`;
 
 export async function backupCommand(target, opts) {
+    // No -f in a project folder: every map, with the same note
+    if (!target) {
+        const ctx = await findProjectFolder(opts);
+        if (ctx?.projectId) {
+            await backupProject(ctx, opts);
+            return;
+        }
+    }
     const { id, baseUrl } = await resolveTarget(target, resolve(opts.file || 'storymap.yml'));
     const lockPasswordHash = await lockPassword(baseUrl, id);
     const backup = await createBackup(baseUrl, id, opts.message || '', { lockPasswordHash });
@@ -24,6 +33,14 @@ export async function backupCommand(target, opts) {
 }
 
 export async function backupsCommand(target, opts) {
+    // No -f in a project folder: the newest backup of each map
+    if (!target) {
+        const ctx = await findProjectFolder(opts);
+        if (ctx?.projectId) {
+            await backupsProject(ctx);
+            return;
+        }
+    }
     const { id, baseUrl } = await resolveTarget(target, resolve(opts.file || 'storymap.yml'));
     const backups = await listBackups(baseUrl, id);
 
@@ -41,47 +58,30 @@ export async function backupsCommand(target, opts) {
     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.
-// The saved one from storymaps unlock is tried first.
+// The lock password for a locked map, checked with the server before anything changes:
+// remembered after storymaps unlock, STORYMAPS_PASSWORD, or typed
 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;
+    return singleMapPassword(baseUrl, id);
 }
 
 export async function restoreCommand(backupId, target, opts) {
-    const filePath = resolve(opts.file || 'storymap.yml');
+    // In a project folder, a backup ID belongs to one map, so the CLI finds which
+    let filePath = resolve(opts.file || 'storymap.yml');
+    if (!target && !opts.file) {
+        const ctx = await findProjectFolder(opts);
+        if (ctx?.projectId) filePath = (await findBackupMap(ctx, backupId)).path;
+    }
     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 ok = await guard({ message: 'Restore this backup? The map is backed up first.', force: opts.force, stopMessage: 'Nothing was restored.' });
+    if (!ok) {
+        console.log('Aborted.');
+        return;
     }
 
     const lockPasswordHash = await lockPassword(baseUrl, id);
@@ -93,5 +93,7 @@ export async function restoreCommand(backupId, target, opts) {
     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.`);
+    // The local file isn't overwritten, as it may have changes not pushed yet
+    const into = target ? 'your local file' : shortPath(filePath);
+    console.log(`Run ${chalk.cyan('storymaps pull')} to bring the restored map into ${into}.`);
 }

package/lib/commands/diff.js

@@ -2,15 +2,20 @@
 // storymaps diff — compare local file vs remote or two local files
 
 import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import chalk from 'chalk';
 import { diffLines } from 'diff';
 import jsyaml from 'js-yaml';
 import { exportToYaml, yamlObjToJson } from '../core/yaml.js';
 import { detectFormat } from '../util/file.js';
-import { resolveTarget } from '../util/identity.js';
+import { resolveTarget, parseProjectLink } from '../util/identity.js';
+import { StopError } from '../util/prompt.js';
 import { getMap } from '../util/api.js';
 import { printChangeSummary } from '../util/summary.js';
+import { printFullDiff } from '../util/full-diff.js';
+import { findProjectFolder } from '../util/project.js';
+import { diffProject } from './project-sync.js';
 
 async function readAndNormalise(filePath) {
     const content = await readFile(filePath, 'utf-8');
@@ -25,8 +30,52 @@ async function readAndNormalise(filePath) {
     return exportToYaml(json);
 }
 
+// The local file of the map a link or ID names: its file in the project folder, or storymap.yml
+// when that's the map. A bare project link diffs the whole project folder. Returns null when
+// it has already printed the result or said why it can't.
+async function localFileFor(source, opts) {
+    const link = parseProjectLink(source);
+    const ctx = await findProjectFolder({ dir: opts.dir }).catch(() => null);
+    if (link && !link.mapId) {
+        if (ctx?.projectId === link.projectId) {
+            await diffProject(ctx, { full: opts.full });
+            return null;
+        }
+        throw new StopError(`There's no folder here for that project. Run ${chalk.cyan(`storymaps pull ${source}`)} first.`);
+    }
+    let id;
+    try {
+        ({ id } = await resolveTarget(source));
+    } catch {
+        throw new StopError(`File not found: ${source}`);
+    }
+    const inFolder = ctx?.files.find(f => f.id === id);
+    if (inFolder) return inFolder.path;
+    const single = resolve('storymap.yml');
+    if (existsSync(single)) {
+        try {
+            if (String(jsyaml.load(await readFile(single, 'utf-8'))?.id) === id) return single;
+        } catch { /* not readable, so not this map */ }
+    }
+    throw new StopError(`There's no local file for that map here. Run ${chalk.cyan(`storymaps pull ${source}`)} to get one.`);
+}
+
 export async function diffCommand(source, target, opts) {
-    const sourcePath = resolve(source || 'storymap.yml');
+    // No files named in a project folder: every map against the server
+    if (!source) {
+        const ctx = await findProjectFolder({ dir: opts.dir });
+        if (ctx?.projectId) {
+            await diffProject(ctx, { full: opts.full });
+            return;
+        }
+    }
+
+    // A link or map ID rather than a file: that map's local file, compared with the server
+    let sourcePath = resolve(source || 'storymap.yml');
+    if (source && !target && !existsSync(sourcePath)) {
+        sourcePath = await localFileFor(source, opts);
+        if (!sourcePath) return;
+    }
     const sourceYaml = await readAndNormalise(sourcePath);
 
     // Show changes from old to new. Two local files go from the first to the second. Against the
@@ -49,7 +98,12 @@ export async function diffCommand(source, target, opts) {
         const json = yamlObjToJson(obj);
         oldYaml = exportToYaml(json);
         newYaml = sourceYaml;
-        oldLabel = `remote: ${baseUrl}/${id}`;
+        // A map in a project shows its project link
+        let project;
+        try {
+            project = jsyaml.load(await readFile(sourcePath, 'utf-8'))?.project;
+        } catch { /* JSON or unreadable: the plain link will do */ }
+        oldLabel = `remote: ${project ? `${baseUrl}/p/${project}/${id}` : `${baseUrl}/${id}`}`;
         newLabel = `local: ${sourcePath}`;
     }
 
@@ -67,41 +121,7 @@ export async function diffCommand(source, target, opts) {
         return;
     }
 
-    // --full: show line-level diff
-    const CONTEXT = 3;
-    const lines = [];
-    let oldLine = 1;
-    let newLine = 1;
-    for (const part of changes) {
-        for (const text of part.value.replace(/\n$/, '').split('\n')) {
-            if (part.added) {
-                lines.push({ tag: '+', text, oldNum: null, newNum: newLine++ });
-            } else if (part.removed) {
-                lines.push({ tag: '-', text, oldNum: oldLine++, newNum: null });
-            } else {
-                lines.push({ tag: ' ', text, oldNum: oldLine++, newNum: newLine++ });
-            }
-        }
-    }
-
-    const width = String(Math.max(oldLine, newLine)).length;
-    const pad = n => n === null ? ' '.repeat(width) : String(n).padStart(width);
-
     console.log(chalk.bold(`--- ${oldLabel}`));
     console.log(chalk.bold(`+++ ${newLabel}`));
-
-    let lastPrinted = -1;
-    for (let i = 0; i < lines.length; i++) {
-        const nearby = lines.slice(Math.max(0, i - CONTEXT), i + CONTEXT + 1);
-        if (!nearby.some(l => l.tag !== ' ')) continue;
-        if (lastPrinted !== -1 && i - lastPrinted > 1) {
-            console.log(chalk.dim(`${'·'.repeat(width * 2 + 5)}`));
-        }
-        const { tag, text, oldNum, newNum } = lines[i];
-        const num = chalk.dim(`${pad(oldNum)} ${pad(newNum)}`);
-        if (tag === '+') console.log(`${num} ${chalk.green(`+ ${text}`)}`);
-        else if (tag === '-') console.log(`${num} ${chalk.red(`- ${text}`)}`);
-        else console.log(`${num} ${chalk.dim(`  ${text}`)}`);
-        lastPrinted = i;
-    }
+    printFullDiff(changes);
 }

package/lib/commands/init.js

@@ -6,9 +6,10 @@ import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { confirm } from '@inquirer/prompts';
 import chalk from 'chalk';
-import { postMap } from '../util/api.js';
+import { getMap, postMap } from '../util/api.js';
+import { writeEtag } from '../util/file.js';
 
-function template(site) {
+export function template(site) {
     const siteLine = site ? `site: ${site}\n` : '';
     return `\
 name: My Story Map
@@ -75,8 +76,9 @@ export async function initCommand(opts) {
         : `https://${site}`;
 
     let output = template(site);
+    let id = null;
     try {
-        const { id } = await postMap(baseUrl, output, 'text/yaml');
+        ({ id } = await postMap(baseUrl, output, 'text/yaml'));
         output = output.replace(/^(name: My Story Map\n)/, `$1id: ${id}\n`);
         console.log(chalk.green(`Created storymap.yml (map ID: ${id})`));
         console.log(`${chalk.cyan(`${baseUrl}/${id}`)}\n`);
@@ -86,5 +88,12 @@ export async function initCommand(opts) {
     }
 
     await writeFile(filePath, output, 'utf-8');
+    // The file matches the new map, so the first push from it stops if the map changes in the browser first
+    if (id) {
+        try {
+            const { etag } = await getMap(baseUrl, id);
+            await writeEtag(id, filePath, etag);
+        } catch { /* non-fatal */ }
+    }
     console.log(highlightYaml(output));
 }