storymaps 1.3.4 → 1.4.1

package/lib/commands/validate.js

@@ -1,11 +1,40 @@
 // Storymaps CLI — AGPL-3.0 — see LICENCE for details
 // storymaps validate — validate a storymap file
 
+import { existsSync, statSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
 import chalk from 'chalk';
 import { readStorymap } from '../util/file.js';
 import { validateYaml } from '../core/yaml.js';
 
 export async function validateCommand(file) {
+    // A folder, such as storymaps: every map file in it
+    if (existsSync(file) && statSync(file).isDirectory()) {
+        const names = (await readdir(file)).filter(n => /\.ya?ml$/i.test(n)).sort();
+        let bad = 0;
+        for (const name of names) {
+            const path = join(file, name);
+            let result;
+            try {
+                result = validateYaml(await readStorymap(path));
+            } catch (err) {
+                result = { valid: false, errors: [err.message], warnings: [] };
+            }
+            if (result.valid) {
+                console.log(`  ${name}  ${chalk.green('valid')}${result.warnings.length ? chalk.yellow(`, ${result.warnings.length} warning${result.warnings.length === 1 ? '' : 's'}`) : ''}`);
+            } else {
+                bad++;
+                console.log(`  ${name}  ${chalk.red('not valid')}`);
+                for (const err of result.errors) console.error(chalk.red(`    - ${err}`));
+            }
+            for (const warn of result.warnings) console.warn(chalk.yellow(`    - ${warn}`));
+        }
+        if (!names.length) console.log(chalk.dim(`No map files in ${file}.`));
+        else if (!bad) console.log(chalk.green(`All ${names.length} maps are valid.`));
+        process.exit(bad ? 1 : 0);
+    }
+
     let data;
     try {
         data = await readStorymap(file);

package/lib/core/yaml.js

@@ -88,6 +88,9 @@ export function jsonToYamlObj(data) {
     const result = {};
     result.name = data.name || '';
     if (data.id) result.id = data.id;
+    // The project a map was fetched through, if any: a description of the map, like id and site,
+    // so loading the YAML back into a map ignores it
+    if (data.project) result.project = data.project;
     if (data.site) result.site = data.site;
     if (data.locked != null) result.locked = data.locked;
 
@@ -198,9 +201,24 @@ export function jsonToYamlObj(data) {
 // Import: YAML string → JSON (compatible with deserializeV1)
 // ============================================================================
 
+// YAML aliases let a few hundred bytes stand for millions of values (an "alias bomb"), which
+// would run the server out of memory once read. Count the values, an alias each time it is
+// used, and stop well above the size of any real story map.
+const MAX_YAML_VALUES = 1_000_000;
+const checkYamlSize = (root) => {
+    let count = 0;
+    const stack = [root];
+    while (stack.length) {
+        const value = stack.pop();
+        if (++count > MAX_YAML_VALUES) throw new Error('YAML is too large');
+        if (value && typeof value === 'object') for (const child of Object.values(value)) stack.push(child);
+    }
+};
+
 export function importFromYaml(yamlString) {
     const obj = jsyaml.load(yamlString);
     if (!obj || typeof obj !== 'object') throw new Error('Invalid YAML');
+    checkYamlSize(obj);
     const validation = validateYaml(obj);
     if (!validation.valid) {
         const err = new Error(validation.errors.join('\n'));
@@ -220,6 +238,11 @@ export function validateYaml(obj) {
         return { valid: false, errors, warnings };
     }
 
+    // Same characters the server allows in a project ID
+    if (obj.project != null && !(typeof obj.project === 'string' && /^[a-zA-Z0-9_-]{1,64}$/.test(obj.project))) {
+        errors.push('"project" must be a project ID, such as the part after /p/ in a project link');
+    }
+
     const stepNames = [];
     obj.steps.forEach((step, i) => {
         if (step === 'spacer') return;

package/lib/util/api.js

@@ -32,24 +32,31 @@ async function handleResponse(res) {
     const body = errorMessage(await res.text().catch(() => ''));
     switch (res.status) {
         case 404: throw new ApiError('Map not found', 404);
-        case 409: throw new ApiError(body || 'Conflict — the remote map has changed. Pull first or use --force.', 409, { conflict: true });
-        case 423: throw new ApiError('Map is locked', 423);
-        case 429: throw new ApiError('Rate limited — please wait and try again', 429);
+        case 409: throw new ApiError(body || 'Conflict: the remote map has changed. Pull first or use --force.', 409, { conflict: true });
+        case 410: throw new ApiError('This map was deleted', 410);
+        case 412: throw new ApiError(body || 'A map already has this ID', 412);
+        case 423: throw new ApiError(body && body !== 'Map is locked' ? body : 'Map is locked', 423);
+        case 429: throw new ApiError('Rate limited. Please wait and try again.', 429);
         default: throw new ApiError(body || `Request failed (${res.status})`, res.status);
     }
 }
 
-export async function getMap(baseUrl, id, format = 'yaml') {
-    const res = await request(`${baseUrl}/api/maps/${id}?format=${format}`);
+// With a project, the map comes with a project key, and only if it's in that project
+export async function getMap(baseUrl, id, format = 'yaml', { project } = {}) {
+    const query = project ? `&project=${encodeURIComponent(project)}` : '';
+    const res = await request(`${baseUrl}/api/maps/${id}?format=${format}${query}`);
+    if (project && res.status === 404) throw new ApiError('That map is not in this project', 404);
     await handleResponse(res);
     const etag = res.headers.get('etag');
     const data = format === 'json' ? await res.json() : await res.text();
     return { data, etag };
 }
 
-export async function putMap(baseUrl, id, body, { etag, contentType = 'text/yaml', lockPasswordHash, restoredBackup } = {}) {
+// createOnly makes the map only if no map has the ID, answering 412 otherwise
+export async function putMap(baseUrl, id, body, { etag, contentType = 'text/yaml', lockPasswordHash, restoredBackup, createOnly } = {}) {
     const headers = { 'Content-Type': contentType };
     if (etag) headers['If-Match'] = etag;
+    if (createOnly) headers['If-None-Match'] = '*';
     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;
@@ -150,4 +157,69 @@ export async function createBackup(baseUrl, id, note = '', { lockPasswordHash }
     return res.json();
 }
 
+// Whether a map is on the server: true, false, or 'deleted'
+export async function mapExists(baseUrl, id) {
+    const res = await request(`${baseUrl}/api/maps/${id}/meta`);
+    if (res.status === 410) return 'deleted';
+    if (res.status === 404) return false;
+    await handleResponse(res);
+    return true;
+}
+
+// Projects
+
+const postJson = async (url, body) => {
+    const res = await request(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    if (res.status === 404) {
+        const message = errorMessage(await res.text().catch(() => ''));
+        throw new ApiError(message || 'Project not found', 404);
+    }
+    if (res.status === 403) {
+        const message = errorMessage(await res.text().catch(() => ''));
+        throw new ApiError(message === 'Forbidden'
+            ? 'This server does not take project changes from the CLI yet. Make the change in the app, or update the server'
+            : message || 'Incorrect password', 403);
+    }
+    if (res.status === 400 || res.status === 409 || res.status === 423) {
+        const message = errorMessage(await res.text().catch(() => ''));
+        throw new ApiError(message, res.status);
+    }
+    await handleResponse(res);
+    return res.json();
+};
+
+// The project's name, whether it's locked, and its maps in tab order. A locked map says whether it
+// uses the project password ('project') or its own ('map'); the server compares, never the CLI.
+export async function getProject(baseUrl, projectId) {
+    const res = await request(`${baseUrl}/api/projects/${encodeURIComponent(projectId)}`);
+    if (res.status === 404) throw new ApiError('Project not found', 404);
+    await handleResponse(res);
+    return (await res.json()).project;
+}
+
+export async function createProject(baseUrl, mapIds, name) {
+    return (await postJson(`${baseUrl}/api/projects`, { mapIds, ...(name ? { name } : {}) })).project;
+}
+
+export async function addProjectMap(baseUrl, projectId, mapId, lockPasswordHash) {
+    return (await postJson(`${baseUrl}/api/projects/${encodeURIComponent(projectId)}/maps`, { mapId, ...(lockPasswordHash ? { lockPasswordHash } : {}) })).project;
+}
+
+// Checks the project password, answering 403 when it's wrong
+export async function checkProjectPassword(baseUrl, projectId, passwordHash) {
+    return (await postJson(`${baseUrl}/api/projects/${encodeURIComponent(projectId)}/unlock`, { passwordHash })).project;
+}
+
+export async function lockProject(baseUrl, projectId, passwordHash, lockMaps) {
+    return postJson(`${baseUrl}/api/projects/${encodeURIComponent(projectId)}/lock`, { passwordHash, lockMaps: !!lockMaps });
+}
+
+export async function removeProjectLock(baseUrl, projectId, passwordHash, removeMaps) {
+    return (await postJson(`${baseUrl}/api/projects/${encodeURIComponent(projectId)}/lock/remove`, { passwordHash, removeMaps: !!removeMaps })).project;
+}
+
 export { ApiError };

package/lib/util/file.js

@@ -32,6 +32,21 @@ export async function writeCache(mapId, updates) {
     await writeFile(cachePathFor(mapId), JSON.stringify(cache), 'utf-8');
 }
 
+// The ETag of the map as each file last pulled or pushed it, by the file's full path. Two copies of
+// one map on the same computer each keep their own, so a push from an older copy stops with a
+// conflict instead of overwriting what the other pushed. Versions up to 1.3.4 kept one ETag per map;
+// it's still read for files pulled with them, and no longer written.
+export async function readEtag(mapId, filePath) {
+    const cache = await readCache(mapId);
+    return cache.files?.[filePath] ?? cache.etag;
+}
+
+export async function writeEtag(mapId, filePath, etag) {
+    if (!etag) return;
+    const cache = await readCache(mapId);
+    await writeCache(mapId, { files: { ...cache.files, [filePath]: etag } });
+}
+
 
 export function detectFormat(filePath) {
     const ext = extname(filePath).toLowerCase();

package/lib/util/full-diff.js

@@ -0,0 +1,42 @@
+// Storymaps CLI — AGPL-3.0 — see LICENCE for details
+// The line-by-line diff that storymaps diff --full prints
+
+import chalk from 'chalk';
+
+// Prints the changed lines of a diffLines result, with three lines around each change
+export function printFullDiff(changes) {
+    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);
+
+
+    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;
+    }
+}

package/lib/util/identity.js

@@ -9,26 +9,47 @@ const DEFAULT_SITE = 'storymaps.io';
 function siteToBaseUrl(site) {
     if (!site) return `https://${DEFAULT_SITE}`;
     if (site === 'localhost') return 'http://localhost:3000';
+    // A local server on another port says so, such as localhost:3312
+    if (/^(localhost|127\.0\.0\.1)(:\d+)?$/.test(site)) return `http://${site}`;
     return `https://${site}`;
 }
 
-export async function resolveTarget(arg, localFilePath = 'storymap.yml') {
-    // Full URL: https://storymaps.io/abc123
-    if (arg && /^https?:\/\//i.test(arg)) {
+export { siteToBaseUrl };
+
+// A link or domain/path, as a URL and its server, or null for a bare ID or file name
+function parseLink(arg) {
+    if (!arg) return null;
+    if (/^https?:\/\//i.test(arg)) {
         const url = new URL(arg);
-        const id = url.pathname.split('/').filter(Boolean).pop();
-        if (!id) throw new Error(`Could not extract map ID from URL: ${arg}`);
-        const baseUrl = `${url.protocol}//${url.host}`;
-        return { id, baseUrl };
+        return { url, baseUrl: `${url.protocol}//${url.host}` };
     }
-
-    // domain/id: storymaps.io/abc123
-    if (arg && arg.includes('/')) {
+    if (arg.includes('/') && !/\.(ya?ml|json)$/i.test(arg)) {
         const url = new URL(`https://${arg}`);
-        const id = url.pathname.split('/').filter(Boolean).pop();
+        return { url, baseUrl: siteToBaseUrl(url.hostname) };
+    }
+    return null;
+}
+
+// A project link: storymaps.io/p/<project> or storymaps.io/p/<project>/<map>.
+// Returns { projectId, mapId (or null), baseUrl }, or null when the target isn't a project link.
+export function parseProjectLink(arg) {
+    const link = parseLink(arg);
+    if (!link) return null;
+    const parts = link.url.pathname.split('/').filter(Boolean);
+    if (parts[0] !== 'p' || parts.length < 2 || parts.length > 3) return null;
+    return { projectId: parts[1], mapId: parts[2] || null, baseUrl: link.baseUrl };
+}
+
+export async function resolveTarget(arg, localFilePath = 'storymap.yml') {
+    const link = parseLink(arg);
+    if (link) {
+        const project = parseProjectLink(arg);
+        if (project && !project.mapId) {
+            throw new Error(`That's a link to a whole project, not one map. Add the map to the link, such as ${arg.replace(/\/+$/, '')}/<map ID>, or run this in the project's folder.`);
+        }
+        const id = project ? project.mapId : link.url.pathname.split('/').filter(Boolean).pop();
         if (!id) throw new Error(`Could not extract map ID from: ${arg}`);
-        const baseUrl = siteToBaseUrl(url.hostname);
-        return { id, baseUrl };
+        return { id, baseUrl: link.baseUrl, ...(project ? { projectId: project.projectId } : {}) };
     }
 
     // Bare ID or no arg — read local file for site context

package/lib/util/passwords.js

@@ -0,0 +1,101 @@
+// Storymaps CLI — AGPL-3.0 — see LICENCE for details
+// Passwords for a project and the maps in it, each checked with the server before anything is sent
+//
+// A password is tried in this order: remembered on this computer after an unlock, then
+// STORYMAPS_PASSWORD, then typed in a terminal. Across a whole project, STORYMAPS_PASSWORD is only
+// tried on the project and the maps locked with its password: a map with its own lock is never
+// sent a guess that would count against the limit on wrong passwords.
+
+import chalk from 'chalk';
+import { readCache, writeCache } from './file.js';
+import { askPassword, envPasswordHash, isInteractive, StopError, PASSWORD_ENV } from './prompt.js';
+import { checkProjectPassword, unlockMap, ApiError } from './api.js';
+
+const projectKey = (projectId) => `project-${projectId}`;
+
+export async function rememberProjectPassword(projectId, hash) {
+    await writeCache(projectKey(projectId), { hash });
+}
+
+export async function forgetProjectPassword(projectId) {
+    await writeCache(projectKey(projectId), { hash: null });
+}
+
+const wrongPassword = (err) => err instanceof ApiError && err.status === 403;
+
+async function projectPasswordWorks(baseUrl, projectId, hash) {
+    try {
+        await checkProjectPassword(baseUrl, projectId, hash);
+        return true;
+    } catch (err) {
+        if (wrongPassword(err)) return false;
+        throw err;
+    }
+}
+
+async function mapPasswordWorks(baseUrl, mapId, hash) {
+    try {
+        await unlockMap(baseUrl, mapId, hash);
+        return true;
+    } catch (err) {
+        if (wrongPassword(err)) return false;
+        throw err;
+    }
+}
+
+// The project password, or null when the project isn't locked. reason is what the password is
+// for, such as "Storymaps.io is locked. Enter its password to add Roadmap".
+export async function projectPassword(baseUrl, project, reason) {
+    if (!project.locked) return null;
+    const saved = (await readCache(projectKey(project.id))).hash;
+    if (saved && await projectPasswordWorks(baseUrl, project.id, saved)) return saved;
+
+    const fromEnv = envPasswordHash();
+    if (fromEnv) {
+        if (await projectPasswordWorks(baseUrl, project.id, fromEnv)) return fromEnv;
+        throw new StopError(`${PASSWORD_ENV} isn't the password for ${project.name}. Nothing was changed.`);
+    }
+    if (!isInteractive()) {
+        throw new StopError(`${reason.replace(/\. Enter its password.*$/, '')}, and there's no terminal to type its password in. Nothing was changed. Run storymaps project unlock --maps in a terminal first, or set ${PASSWORD_ENV} for this command.`);
+    }
+    console.log(chalk.yellow(`${reason}.`));
+    const hash = await askPassword({ allowEnv: false });
+    if (!await projectPasswordWorks(baseUrl, project.id, hash)) throw new StopError('Incorrect password. Nothing was changed.');
+    return hash;
+}
+
+// The password of a map with its own lock, across a whole project: remembered, or typed
+export async function ownMapPassword(baseUrl, map, file) {
+    const saved = (await readCache(map.id)).hash;
+    if (saved && await mapPasswordWorks(baseUrl, map.id, saved)) return saved;
+    const unlockHint = file ? `storymaps unlock -f ${file}` : `storymaps unlock ${map.id}`;
+    if (!isInteractive()) {
+        throw new StopError(`${map.name} has its own lock, and there's no terminal to type its password in. Nothing was changed. Run ${unlockHint} in a terminal first.`);
+    }
+    console.log(chalk.yellow(`${map.name} has its own lock.`));
+    const hash = await askPassword({ allowEnv: false });
+    if (!await mapPasswordWorks(baseUrl, map.id, hash)) throw new StopError(`Incorrect password for ${map.name}. Nothing was changed.`);
+    return hash;
+}
+
+// The password for one map, outside a whole-project command: remembered, STORYMAPS_PASSWORD, or typed
+export async function singleMapPassword(baseUrl, mapId) {
+    const saved = (await readCache(mapId)).hash;
+    if (saved && await mapPasswordWorks(baseUrl, mapId, saved)) return saved;
+    const fromEnv = envPasswordHash();
+    if (fromEnv) {
+        if (await mapPasswordWorks(baseUrl, mapId, fromEnv)) return fromEnv;
+        throw new StopError(`${PASSWORD_ENV} isn't the password for this map. Nothing was changed.`);
+    }
+    if (!isInteractive()) {
+        throw new StopError(`This map is locked, and there's no terminal to type its password in. Nothing was changed. Run storymaps unlock in a terminal first, or set ${PASSWORD_ENV} for this command.`);
+    }
+    console.log(chalk.yellow('Map is locked.'));
+    const hash = await askPassword({ allowEnv: false });
+    if (!await mapPasswordWorks(baseUrl, mapId, hash)) throw new StopError('Incorrect password. Nothing was changed.');
+    return hash;
+}
+
+// Lists names as "A", "A and B", or "A, B and C"
+export const listNames = (names) => names.length <= 1 ? (names[0] || '')
+    : `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;

package/lib/util/project.js

@@ -0,0 +1,215 @@
+// Storymaps CLI — AGPL-3.0 — see LICENCE for details
+// Project folders: a folder of map files that share a project key
+//
+// A project lives in one folder, storymaps/ by default, so a repo gets one new folder rather than
+// a file per map. Each file is an ordinary map file named by its map ID, such as
+// storymaps/1g2pt83x.yml, so renaming a map in the app never puts a file out of step. There's no
+// separate project file: the project name and tab order come from the server each time.
+//
+// The CLI never moves, renames or deletes a file, 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.
+
+import { existsSync, statSync } from 'node:fs';
+import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { join, resolve, relative, extname, basename } from 'node:path';
+import { homedir } from 'node:os';
+import chalk from 'chalk';
+import jsyaml from 'js-yaml';
+import { siteToBaseUrl } from './identity.js';
+import { StopError } from './prompt.js';
+
+export const PROJECT_DIR = 'storymaps';
+const MAP_FILE = /\.ya?ml$/i;
+
+// A path as it reads from where the command was run, such as storymaps/1g2pt83x.yml
+export const shortPath = (path) => relative(process.cwd(), path) || '.';
+
+export const mapFilePath = (dir, mapId) => join(dir, `${mapId}.yml`);
+
+// The map files in a folder that say which project they're in
+export async function readProjectFiles(dir) {
+    let names;
+    try {
+        names = await readdir(dir);
+    } catch {
+        return [];
+    }
+    const files = [];
+    for (const name of names.sort()) {
+        if (!MAP_FILE.test(name)) continue;
+        const path = resolve(dir, name);
+        let content, obj;
+        try {
+            content = await readFile(path, 'utf-8');
+            obj = jsyaml.load(content);
+        } catch (err) {
+            // A file that names a project but can't be read is reported, never quietly skipped
+            if (content && /^project:/m.test(content)) files.push({ path, name, content, broken: err.message.split('\n')[0] });
+            continue;
+        }
+        if (!obj || typeof obj !== 'object' || !obj.project) continue;
+        files.push({ path, name, content, obj, id: obj.id ? String(obj.id) : null, project: String(obj.project), site: obj.site });
+    }
+    return files;
+}
+
+// The folder a project is pulled or started in, when --dir doesn't say: the current folder if
+// it's already a project folder (named storymaps, or holding project files), so running a
+// command from inside storymaps/ never makes storymaps/storymaps/; otherwise storymaps/ in it.
+export async function defaultProjectDir(dir) {
+    if (dir) return resolve(dir);
+    const cwd = process.cwd();
+    if (existsSync(join(cwd, PROJECT_DIR))) return join(cwd, PROJECT_DIR);
+    if (basename(cwd) === PROJECT_DIR || (await readProjectFiles(cwd)).length) return cwd;
+    return join(cwd, PROJECT_DIR);
+}
+
+// The project folder a command works on, or null when it works on one map. A project in reach
+// wins: the folder named with --dir, storymaps/ inside the current folder, or project files in the
+// current folder itself, so commands work from a repo root or from inside storymaps/. With no
+// project in reach, storymap.yml means one map, exactly as before projects. -f always means one map.
+export async function findProjectFolder(opts = {}) {
+    if (opts.file) return null;
+    const candidates = opts.dir ? [opts.dir] : [PROJECT_DIR, '.'];
+    for (const candidate of candidates) {
+        const dir = resolve(candidate);
+        if (!existsSync(dir) || !statSync(dir).isDirectory()) continue;
+        const files = await readProjectFiles(dir);
+        if (!files.length) continue;
+        const projects = [...new Set(files.filter(f => !f.broken).map(f => f.project))];
+        if (!projects.length) throw new StopError(`${files.map(f => f.name).join(', ')} in ${shortPath(dir)} can't be read: ${files[0].broken}`);
+        if (projects.length > 1) {
+            throw new StopError(`${shortPath(dir)} has maps from ${projects.length} projects: ${projects.join(', ')}. Use --dir for a folder with one project, or -f for one map.`);
+        }
+        const site = files.find(f => f.site)?.site;
+        // A storymap.yml beside the project is still one -f away; say so, so it isn't missed
+        const single = resolve('storymap.yml');
+        if (!opts.dir && !opts.quiet && existsSync(single) && !files.some(f => f.path === single)) {
+            console.log(chalk.dim(`Using the project in ${candidate === '.' ? 'this folder' : `${candidate}/`}. Add -f storymap.yml for the map in storymap.yml.`));
+        }
+        return { dir, files, projectId: projects[0], baseUrl: siteToBaseUrl(site), site };
+    }
+    // A folder named with --dir is never quietly passed over, so a typo can't look like it worked
+    if (opts.dir) {
+        const dir = resolve(opts.dir);
+        if (!existsSync(dir)) throw new StopError(`There's no folder called ${opts.dir}.`);
+        throw new StopError(`${opts.dir} has no map files from a project. Pull a project into it with storymaps pull storymaps.io/p/<project> --dir ${opts.dir}.`);
+    }
+    return null;
+}
+
+// Puts project: <id> straight after id: (or name:) in a file's text, replacing any it has
+export function setProjectKey(content, projectId) {
+    const without = removeProjectKey(content);
+    if (/^id:\s.*$/m.test(without)) return without.replace(/^(id:\s.*)$/m, `$1\nproject: ${projectId}`);
+    if (/^name:\s.*$/m.test(without)) return without.replace(/^(name:\s.*)$/m, `$1\nproject: ${projectId}`);
+    return `project: ${projectId}\n${without}`;
+}
+
+export function removeProjectKey(content) {
+    return content.replace(/^project:[^\n]*\n?/m, '');
+}
+
+// Puts id: <id> straight after name:, replacing any it has
+export function setIdKey(content, id) {
+    const without = content.replace(/^id:[^\n]*\n?/m, '');
+    if (/^name:\s.*$/m.test(without)) return without.replace(/^(name:\s.*)$/m, `$1\nid: ${id}`);
+    return `id: ${id}\n${without}`;
+}
+
+// Puts site: <site> after project: (or id:), unless the file already says its site
+export function setSiteKey(content, site) {
+    if (!site || /^site:\s/m.test(content)) return content;
+    for (const key of ['project', 'id', 'name']) {
+        const re = new RegExp(`^(${key}:\\s.*)$`, 'm');
+        if (re.test(content)) return content.replace(re, `$1\nsite: ${site}`);
+    }
+    return `site: ${site}\n${content}`;
+}
+
+// The site a server's address stands for in a map file, such as storymaps.io or localhost:3312
+export const siteOfBaseUrl = (baseUrl) => {
+    const url = new URL(baseUrl);
+    return url.host === 'localhost:3000' ? 'localhost' : url.host;
+};
+
+// Sets locked: true or false in a map file after the CLI locks or unlocks its map, so the file
+// says what the map is now. Only that line changes; the conflict check doesn't cover it.
+export async function setLockedInFile(path, locked) {
+    let content;
+    try {
+        content = await readFile(path, 'utf-8');
+    } catch {
+        return;
+    }
+    if (!/^locked:\s/m.test(content)) return;
+    const updated = content.replace(/^locked:\s.*$/m, `locked: ${locked}`);
+    if (updated !== content) await writeFile(path, updated, 'utf-8');
+}
+
+// After a project lock changes, the files in the folder for the maps whose lock changed
+export async function updateLockedInFolder(dir, before, after) {
+    if (!dir) return;
+    const files = await readProjectFiles(dir);
+    for (const map of after.maps) {
+        const was = !!before.maps.find(m => m.id === map.id)?.lock;
+        const now = !!map.lock;
+        if (was === now) continue;
+        const file = files.find(f => f.id === map.id);
+        if (file) await setLockedInFile(file.path, now);
+    }
+}
+
+export async function writeMapFile(path, content) {
+    await mkdir(resolve(path, '..'), { recursive: true });
+    await writeFile(path, content, 'utf-8');
+}
+
+export const isMapFile = (path) => MAP_FILE.test(extname(path) ? path : '');
+
+// The CLI's own notes, kept in ~/.storymaps next to the conflict-check data, never in the repo:
+//   newMaps: files written by project add for a map not yet on the server, so push knows to create
+//            it, and can tell it from a map that was deleted
+//   drafts:  files project add started a map from, so push passes over them with a reminder
+const NOTES = join(homedir(), '.storymaps', 'projects.json');
+
+async function readNotes() {
+    try {
+        const notes = JSON.parse(await readFile(NOTES, 'utf-8'));
+        return { newMaps: notes.newMaps || {}, drafts: notes.drafts || {} };
+    } catch {
+        return { newMaps: {}, drafts: {} };
+    }
+}
+
+async function writeNotes(notes) {
+    await mkdir(join(homedir(), '.storymaps'), { recursive: true });
+    await writeFile(NOTES, JSON.stringify(notes), 'utf-8');
+}
+
+export async function noteNewMap(path, id) {
+    const notes = await readNotes();
+    notes.newMaps[resolve(path)] = { id };
+    await writeNotes(notes);
+}
+
+export async function isNewMap(path, id) {
+    return (await readNotes()).newMaps[resolve(path)]?.id === id;
+}
+
+export async function forgetNewMap(path) {
+    const notes = await readNotes();
+    delete notes.newMaps[resolve(path)];
+    await writeNotes(notes);
+}
+
+export async function noteDraft(draftPath, newPath) {
+    const notes = await readNotes();
+    notes.drafts[resolve(draftPath)] = { file: resolve(newPath) };
+    await writeNotes(notes);
+}
+
+// The file a draft became, or null
+export async function draftOf(path) {
+    return (await readNotes()).drafts[resolve(path)]?.file || null;
+}