storymaps 1.3.5 → 1.4.1

package/lib/commands/project.js

@@ -0,0 +1,291 @@
+// Storymaps CLI — AGPL-3.0 — see LICENCE for details
+// storymaps project init, add, lock and unlock: the commands that change a project itself.
+// Renaming a project, and reordering, removing and deleting its maps, stay in the app.
+
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import chalk from 'chalk';
+import jsyaml from 'js-yaml';
+import { importFromYaml } from '../core/yaml.js';
+import { generateId } from '../core/constants.js';
+import {
+    getMap, postMap, getProject, createProject, addProjectMap, mapExists, lockProject,
+    removeProjectLock, checkProjectPassword, ApiError,
+} from '../util/api.js';
+import { writeEtag, writeCache } from '../util/file.js';
+import { resolveTarget, parseProjectLink, siteToBaseUrl } from '../util/identity.js';
+import {
+    PROJECT_DIR, defaultProjectDir, findProjectFolder, readProjectFiles, mapFilePath, shortPath, setIdKey, setProjectKey,
+    writeMapFile, noteNewMap, noteDraft, setSiteKey, siteOfBaseUrl, updateLockedInFolder,
+} from '../util/project.js';
+import { projectPassword, rememberProjectPassword, forgetProjectPassword, listNames } from '../util/passwords.js';
+import { askPassword, choose, ask, StopError, PASSWORD_ENV } from '../util/prompt.js';
+import { projectLink, reportLock } from './project-sync.js';
+import { template } from './init.js';
+
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+const NEW_MAP_WAIT = 61_000;
+
+// Makes a map on the server, waiting a minute if the limit of 10 new maps a minute is reached
+async function createMap(baseUrl, content) {
+    try {
+        return (await postMap(baseUrl, content, 'text/yaml')).id;
+    } catch (err) {
+        if (!(err instanceof ApiError && err.status === 429)) throw err;
+        console.log(chalk.dim('The server makes 10 new maps a minute, so this waits a minute...'));
+        await new Promise(r => setTimeout(r, NEW_MAP_WAIT));
+        return (await postMap(baseUrl, content, 'text/yaml')).id;
+    }
+}
+
+// Writes a map in the project to the folder, as the server exports it with its project key
+async function writeFromServer(baseUrl, projectId, mapId, dir) {
+    const path = mapFilePath(dir, mapId);
+    const { data, etag } = await getMap(baseUrl, mapId, 'yaml', { project: projectId });
+    await writeMapFile(path, data);
+    await writeEtag(mapId, path, etag);
+    return path;
+}
+
+const readMapFile = async (file) => {
+    const content = await readFile(resolve(file), 'utf-8');
+    importFromYaml(content);
+    return { content, obj: jsyaml.load(content) };
+};
+
+// ---------------------------------------------------------------------------------------------
+// project init
+
+// Starts a project with a first map, or with a map from each file, written to storymaps/ by ID.
+// The original files are left alone. Needs a connection, as the server makes projects.
+export async function projectInitCommand(files, opts) {
+    const dir = await defaultProjectDir(opts.dir);
+    const existing = await readProjectFiles(dir);
+    if (existing.length) {
+        throw new StopError(`${shortPath(dir)} already holds a project, ${existing[0].project}. Use --dir for the new one.`);
+    }
+    const baseUrl = siteToBaseUrl(opts.site);
+    const sources = [];
+    for (const file of files) {
+        try {
+            sources.push({ file, ...(await readMapFile(file)) });
+        } catch (err) {
+            throw new StopError(`${file} isn't a valid map:\n${err.message}\nNothing was created.`);
+        }
+    }
+    if (!sources.length) sources.push({ content: template(opts.site), obj: { name: 'My Story Map' } });
+
+    // A project needs at least one map, so the maps come first
+    const ids = [];
+    for (const source of sources) ids.push(await createMap(baseUrl, source.content.replace(/^id:[^\n]*\n?/m, '').replace(/^project:[^\n]*\n?/m, '')));
+    const project = await createProject(baseUrl, ids, opts.name);
+
+    console.log(chalk.green(`Created project ${project.name}: ${projectLink(baseUrl, project.id)}`));
+    const width = Math.max(...project.maps.map(m => m.name.length));
+    for (const map of project.maps) console.log(`  ${map.name.padEnd(width)}  ${projectLink(baseUrl, project.id, map.id)}`);
+    const written = [];
+    for (const id of ids) written.push(shortPath(await writeFromServer(baseUrl, project.id, id, dir)));
+    console.log(`Wrote ${listNames(written)}`);
+    if (files.length) console.log(chalk.dim(`${listNames(files)} ${files.length === 1 ? 'is' : 'are'} unchanged. Delete ${files.length === 1 ? 'it' : 'them'} when you're ready.`));
+}
+
+// ---------------------------------------------------------------------------------------------
+// project add
+
+// The project to add to: the project folder, or --project when there isn't one yet
+async function projectToChange(opts) {
+    if (opts.project) {
+        const link = parseProjectLink(opts.project);
+        const projectId = link ? link.projectId : opts.project;
+        const baseUrl = link ? link.baseUrl : siteToBaseUrl();
+        return { projectId, baseUrl, dir: await defaultProjectDir(opts.dir) };
+    }
+    const ctx = await findProjectFolder({ dir: opts.dir, quiet: true });
+    if (!ctx?.projectId) {
+        throw new StopError('There\'s no project here. Run this in a project folder, or say which project with --project storymaps.io/p/<project>.');
+    }
+    return ctx;
+}
+
+const isOffline = (err) => err instanceof TypeError || err?.cause?.code === 'ENOTFOUND' || err?.cause?.code === 'ECONNREFUSED' || err?.code === 'ENOTFOUND';
+
+// Adds a new blank map, a new map from a file that isn't on storymaps.io, or an existing map,
+// by its file, link or ID. 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.
+export async function projectAddCommand(source, opts) {
+    const { projectId, baseUrl, dir } = await projectToChange(opts);
+
+    // What's being added
+    let existingId = null, content = null, name = opts.name || 'My Story Map', draft = null;
+    if (source && /\.ya?ml$/i.test(source)) {
+        let read;
+        try {
+            read = await readMapFile(source);
+        } catch (err) {
+            throw new StopError(`${source} isn't a valid map:\n${err.message}`);
+        }
+        name = read.obj.name || name;
+        const id = read.obj.id ? String(read.obj.id) : null;
+        const exists = id ? await mapExists(baseUrl, id).catch(err => { if (isOffline(err)) return null; throw err; }) : false;
+        if (exists === true) existingId = id;
+        else {
+            content = read.content;
+            draft = resolve(source);
+        }
+    } else if (source) {
+        existingId = (await resolveTarget(source)).id;
+    } else {
+        content = template().replace(/^name: My Story Map$/m, jsyaml.dump({ name }).trim());
+    }
+
+    let project;
+    try {
+        project = await getProject(baseUrl, projectId);
+    } catch (err) {
+        if (existingId || !isOffline(err)) throw err;
+        return addOffline({ baseUrl, projectId, dir, content, name, draft });
+    }
+    if (existingId) name = (await getMap(baseUrl, existingId, 'json')).data.name || 'this map';
+    const hash = await projectPassword(baseUrl, project, `${project.name} is locked. Enter its password to add ${name}`);
+
+    let id = existingId;
+    if (!id) {
+        const body = content.replace(/^id:[^\n]*\n?/m, '').replace(/^project:[^\n]*\n?/m, '');
+        id = await createMap(baseUrl, body);
+        console.log(chalk.green(`Created ${name}: ${projectLink(baseUrl, projectId, id)}`));
+    }
+    const after = await addProjectMap(baseUrl, projectId, id, hash || undefined);
+    const map = after.maps.find(m => m.id === id);
+    console.log(chalk.green(`Added ${map?.name || name} to ${project.name}.`));
+    reportLock(map?.name || name, map);
+    const path = await writeFromServer(baseUrl, projectId, id, dir);
+    console.log(`Wrote ${shortPath(path)}`);
+    if (draft) {
+        await noteDraft(draft, path);
+        console.log(chalk.dim(`${shortPath(draft)} is unchanged. Delete it when you're ready.`));
+    } else if (source && /\.ya?ml$/i.test(source)) {
+        console.log(chalk.dim(`${shortPath(resolve(source))} is unchanged. Delete it when you're ready.`));
+    }
+}
+
+// With no connection: the CLI makes the ID and writes the file; the next push creates the map
+async function addOffline({ baseUrl, projectId, dir, content, name, draft }) {
+    const id = generateId();
+    const path = mapFilePath(dir, id);
+    await writeMapFile(path, setSiteKey(setProjectKey(setIdKey(content, id), projectId), siteOfBaseUrl(baseUrl)));
+    await noteNewMap(path, id);
+    if (draft) await noteDraft(draft, path);
+    console.log(`Wrote ${shortPath(path)}`);
+    console.log(chalk.yellow(`You're offline, so ${name} will be created and added to the project on your next push.`));
+    if (draft) console.log(chalk.dim(`${shortPath(draft)} is unchanged. Delete it when you're ready.`));
+    return { baseUrl };
+}
+
+// ---------------------------------------------------------------------------------------------
+// project lock
+
+// The same two choices as the app: the project, or the project and its maps that aren't locked
+export async function projectLockCommand(opts) {
+    const { projectId, baseUrl, dir } = await projectToChange(opts);
+    const project = await getProject(baseUrl, projectId);
+    const unlocked = project.maps.filter(m => !m.lock);
+    const keeping = project.maps.filter(m => m.lock === 'map').map(m => m.name);
+    const keepNote = keeping.length ? `${listNames(keeping)} ${keeping.length === 1 ? 'keeps its own lock.' : 'keep their own locks.'}` : '';
+
+    if (project.locked) {
+        if (!opts.maps) {
+            console.log(`${project.name} is already locked.` + (unlocked.length ? chalk.dim(` To lock its ${plural(unlocked.length, 'unlocked map')} too, run storymaps project lock --maps`) : ''));
+            return;
+        }
+        if (!unlocked.length) {
+            console.log(chalk.dim(`${project.name} and its maps are already locked.`));
+            return;
+        }
+        if (!process.env[PASSWORD_ENV]) console.log(chalk.yellow(`${project.name} is already locked. Enter its password to lock its unlocked maps.`));
+        const hash = await askPassword({ noPasswordMessage: `${project.name} is locked, and there's no terminal to type its password in. Set ${PASSWORD_ENV} for this command.` });
+        const result = await lockProject(baseUrl, projectId, hash, true);
+        await updateLockedInFolder(dir, project, result.project);
+        const nowLocked = result.project.maps.filter(m => m.lock === 'project' && unlocked.some(u => u.id === m.id)).map(m => m.name);
+        console.log(chalk.green(`Locked ${listNames(nowLocked)} with the project password.`) + chalk.dim(' Every other map was already locked.'));
+        return;
+    }
+
+    const withMaps = opts.maps || await choose({
+        message: 'What should the password lock?',
+        yes: opts.yes,
+        defaultValue: false,
+        choices: [
+            { name: 'The project', value: false, description: 'Nobody can rename the project, or add, remove or reorder its maps, without the password. What\'s on each map can still be edited.' },
+            ...(unlocked.length ? [{
+                name: `The project and its ${plural(unlocked.length, keeping.length ? 'unlocked map' : 'map')}`,
+                value: true,
+                description: `Nobody can edit ${unlocked.length === 1 ? 'that map' : 'those maps'} without the password either, and ${unlocked.length === 1 ? 'it' : 'each one'} can be unlocked on its own later. ${keepNote}`.trim(),
+            }] : []),
+        ],
+    });
+    const hash = await askPassword({ confirmTwice: true, noPasswordMessage: `Locking needs a password, and there's no terminal to type it in. Set ${PASSWORD_ENV} for this command.` });
+    const result = await lockProject(baseUrl, projectId, hash, withMaps);
+    await updateLockedInFolder(dir, project, result.project);
+    await rememberProjectPassword(projectId, hash);
+    // Said from the labels after locking: a map locked before with this same password now counts
+    // as locked with the project password, not with its own
+    const lockedMaps = withMaps ? result.project.maps.filter(m => m.lock === 'project' && unlocked.some(u => u.id === m.id)).length : 0;
+    const ownAfter = result.project.maps.filter(m => m.lock === 'map').map(m => m.name);
+    const ownNote = ownAfter.length ? `${listNames(ownAfter)} ${ownAfter.length === 1 ? 'keeps its own lock.' : 'keep their own locks.'}` : '';
+    console.log(chalk.green(`Locked ${project.name}${lockedMaps ? ` and its ${plural(lockedMaps, keeping.length ? 'unlocked map' : 'map')}` : ''}.`) + (ownNote ? chalk.dim(` ${ownNote}`) : ''));
+}
+
+// ---------------------------------------------------------------------------------------------
+// project unlock
+
+// On this computer, as entering the password in the app does, or for everyone with --remove.
+// Both ask about the maps that use the project password, defaulting to no as the app does.
+export async function projectUnlockCommand(opts) {
+    const { projectId, baseUrl, dir } = await projectToChange(opts);
+    const project = await getProject(baseUrl, projectId);
+    if (!project.locked) {
+        console.log(chalk.dim(`${project.name} isn't locked.`));
+        return;
+    }
+    const shared = project.maps.filter(m => m.lock === 'project');
+    const own = project.maps.filter(m => m.lock === 'map');
+
+    if (opts.remove) {
+        console.log(chalk.yellow(`Anyone with the link will be able to change the name, maps and order of ${project.name}, and delete it.`));
+        const hash = await askPassword({ noPasswordMessage: `Removing the lock needs the ${project.name} password, and there's no terminal to type it in. Set ${PASSWORD_ENV} for this command.` });
+        const removeMaps = shared.length ? (opts.maps || await ask({ message: `Also remove the lock from ${plural(shared.length, 'map')}? ${shared.length === 1 ? 'It has' : 'They have'} a project lock.`, yes: opts.yes })) : false;
+        try {
+            const after = await removeProjectLock(baseUrl, projectId, hash, removeMaps);
+            await updateLockedInFolder(dir, project, after);
+        } catch (err) {
+            if (err instanceof ApiError && err.status === 403) throw new StopError('Incorrect password. Nothing was changed.');
+            throw err;
+        }
+        await forgetProjectPassword(projectId);
+        if (removeMaps) for (const map of shared) await writeCache(map.id, { hash: null });
+        console.log(removeMaps
+            ? chalk.green(`Removed the lock from ${project.name} and ${plural(shared.length, 'map')}.`)
+            : chalk.green(`Removed the lock from ${project.name}.`) + (shared.length ? chalk.dim(' Its maps keep their locks.') : ''));
+        return;
+    }
+
+    const hash = await askPassword({ noPasswordMessage: `Unlocking needs the ${project.name} password, and there's no terminal to type it in. Set ${PASSWORD_ENV} for this command.` });
+    try {
+        await checkProjectPassword(baseUrl, projectId, hash);
+    } catch (err) {
+        if (err instanceof ApiError && err.status === 403) throw new StopError('Incorrect password.');
+        throw err;
+    }
+    await rememberProjectPassword(projectId, hash);
+    const withMaps = shared.length ? (opts.maps || await ask({ message: `Also unlock the ${plural(shared.length, 'map')} locked with the project password, on this computer?`, yes: opts.yes })) : false;
+    if (withMaps) {
+        for (const map of shared) await writeCache(map.id, { hash });
+        console.log(chalk.green(`Unlocked ${project.name} and ${plural(shared.length, 'map')} on this computer.`));
+    } else {
+        console.log(chalk.green(`Unlocked ${project.name} on this computer.`) + (shared.length ? chalk.dim(' Its maps stay locked. Add --maps to unlock them too.') : ''));
+    }
+    for (const map of own) {
+        const file = shortPath(mapFilePath(dir, map.id));
+        console.log(chalk.dim(`${map.name} is still locked. To unlock it, run`) + ` ${chalk.cyan(`storymaps unlock -f ${file}`)}`);
+    }
+}

package/lib/commands/pull.js

@@ -1,17 +1,19 @@
 // Storymaps CLI — AGPL-3.0 — see LICENCE for details
-// storymaps pull — download a map from the remote server
+// storymaps pull — download a map, or a whole project, from the remote server
 
 import { readFile, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { confirm } from '@inquirer/prompts';
 import chalk from 'chalk';
 import jsyaml from 'js-yaml';
 import { exportToYaml, yamlObjToJson } from '../core/yaml.js';
 import { detectFormat, writeEtag } from '../util/file.js';
-import { resolveTarget } from '../util/identity.js';
-import { getMap } from '../util/api.js';
+import { resolveTarget, parseProjectLink } from '../util/identity.js';
+import { getMap, getProject } from '../util/api.js';
 import { printChangeSummary } from '../util/summary.js';
+import { findProjectFolder, readProjectFiles, defaultProjectDir, shortPath } from '../util/project.js';
+import { choose, guard, isInteractive } from '../util/prompt.js';
+import { pullProject, projectLink } from './project-sync.js';
 
 function normalise(content, format) {
     if (format === 'json') {
@@ -22,6 +24,52 @@ function normalise(content, format) {
 }
 
 export async function pullCommand(target, opts) {
+    // A project link: the whole project, or one map of it
+    const link = parseProjectLink(target);
+    if (link && !opts.file) {
+        const dir = await defaultProjectDir(opts.dir);
+        if (!link.mapId) {
+            await pullProject({ baseUrl: link.baseUrl, projectId: link.projectId, dir, force: opts.force });
+            return;
+        }
+        // The app's address bar always shows a map inside its project, so a map link is what most
+        // people paste. The first time, ask which they meant; once the folder holds the project,
+        // a map link pulls just that map.
+        const held = (await readProjectFiles(dir)).some(f => f.project === link.projectId);
+        if (!held) {
+            const project = await getProject(link.baseUrl, link.projectId);
+            const map = project.maps.find(m => m.id === link.mapId);
+            const name = map?.name || link.mapId;
+            const asking = isInteractive() && !opts.yes;
+            if (asking) console.log(`${name} is one of ${project.maps.length} maps in ${project.name}.`);
+            const whole = await choose({
+                message: 'Pull:',
+                yes: opts.yes,
+                defaultValue: false,
+                choices: [
+                    { name: `Just ${name}`, value: false },
+                    { name: `The whole project (${project.maps.length} maps)`, value: true },
+                ],
+            });
+            await pullProject({ baseUrl: link.baseUrl, projectId: link.projectId, dir, force: opts.force, ...(whole ? {} : { mapId: link.mapId }) });
+            if (!whole && !asking && project.maps.length > 1) {
+                console.log(chalk.dim(`${name} is one of ${project.maps.length} maps in ${project.name}. To pull them all, run`) + ` ${chalk.cyan(`storymaps pull ${projectLink(link.baseUrl, link.projectId).replace(/^https:\/\//, '')}`)}`);
+            }
+            return;
+        }
+        await pullProject({ baseUrl: link.baseUrl, projectId: link.projectId, dir, force: opts.force, mapId: link.mapId });
+        return;
+    }
+
+    // No target in a project folder: refresh every map
+    if (!target) {
+        const ctx = await findProjectFolder(opts);
+        if (ctx?.projectId) {
+            await pullProject({ baseUrl: ctx.baseUrl, projectId: ctx.projectId, dir: ctx.dir, force: opts.force });
+            return;
+        }
+    }
+
     const filePath = resolve(opts.file || 'storymap.yml');
     const { id, baseUrl } = await resolveTarget(target, filePath);
 
@@ -50,16 +98,10 @@ export async function pullCommand(target, opts) {
             // Continue even if summary fails
         }
 
-        if (!opts.force) {
-            const overwrite = await confirm({
-                message: 'Apply changes?',
-                default: true,
-                theme: { prefix: '>' },
-            });
-            if (!overwrite) {
-                console.log('Aborted.');
-                return;
-            }
+        const overwrite = await guard({ message: 'Apply changes?', force: opts.force, stopMessage: `${shortPath(filePath)} was left as it is.` });
+        if (!overwrite) {
+            console.log('Aborted.');
+            return;
         }
     }
 

package/lib/commands/push.js

@@ -1,17 +1,18 @@
 // Storymaps CLI — AGPL-3.0 — see LICENCE for details
 // storymaps push — upload a local map to the remote server
 
-import { createHash } from 'node:crypto';
 import { readFile, writeFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import chalk from 'chalk';
-import { password } from '@inquirer/prompts';
 import jsyaml from 'js-yaml';
 import { exportToYaml, importFromYaml, yamlObjToJson } from '../core/yaml.js';
 import { printChangeSummary } from '../util/summary.js';
-import { resolveTarget } from '../util/identity.js';
+import { resolveTarget, siteToBaseUrl } from '../util/identity.js';
 import { getMap, putMap, postMap, ApiError } from '../util/api.js';
 import { detectFormat, readCache, readEtag, writeEtag } from '../util/file.js';
+import { findProjectFolder } from '../util/project.js';
+import { askPassword, isInteractive, PASSWORD_ENV } from '../util/prompt.js';
+import { pushProject } from './project-sync.js';
 
 // The map as it is on the server now is what this file matches, so a later push from it stops if
 // the map changes in the meantime
@@ -22,13 +23,17 @@ async function rememberEtag(baseUrl, id, filePath) {
     } catch { /* non-fatal */ }
 }
 
-function siteToBaseUrl(site) {
-    if (!site) return 'https://storymaps.io';
-    if (site === 'localhost') return 'http://localhost:3000';
-    return `https://${site}`;
-}
 
 export async function pushCommand(target, opts) {
+    // No target or -f in a project folder: every map in the project
+    if (!target) {
+        const ctx = await findProjectFolder(opts);
+        if (ctx?.projectId) {
+            await pushProject(ctx, { force: opts.force });
+            return;
+        }
+    }
+
     const filePath = resolve(opts.file || 'storymap.yml');
 
     let content;
@@ -101,9 +106,8 @@ export async function pushCommand(target, opts) {
             process.exit(1);
         }
         if (err instanceof ApiError && err.status === 423) {
-            console.log(chalk.yellow('Map is locked.'));
-            const pw = await password({ theme: { prefix: '>' }, message: 'Password:' });
-            lockPasswordHash = createHash('sha256').update(pw).digest('hex');
+            if (!process.env[PASSWORD_ENV] && isInteractive()) console.log(chalk.yellow('Map is locked.'));
+            lockPasswordHash = await askPassword({ noPasswordMessage: `This map is locked, and there's no terminal to type its password in. Nothing was pushed. Run storymaps unlock in a terminal first, or set ${PASSWORD_ENV} for this command.` });
             try {
                 await putMap(baseUrl, id, content, { etag, contentType, lockPasswordHash });
             } catch (retryErr) {
@@ -121,6 +125,8 @@ export async function pushCommand(target, opts) {
     // Refresh this file's ETag so the next push from it is also protected
     await rememberEtag(baseUrl, id, filePath);
 
-    const url = `${baseUrl}/${id}`;
+    // A map in a project shows at its project link
+    const project = format === 'yaml' ? jsyaml.load(content)?.project : JSON.parse(content).project;
+    const url = project ? `${baseUrl}/p/${project}/${id}` : `${baseUrl}/${id}`;
     console.log(chalk.green(`Pushed to ${url}`));
 }

package/lib/commands/status.js

@@ -5,7 +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 { resolveTarget, parseProjectLink } from '../util/identity.js';
+import { findProjectFolder } from '../util/project.js';
 import { getMap, ApiError } from '../util/api.js';
 
 const STATUS_ICONS = {
@@ -52,7 +53,43 @@ async function loadContent(target, opts) {
     }
 }
 
+// Task cards across every slice, and how many are done. Cards in a legend colour not labelled as
+// a task, such as notes and questions, aren't counted.
+export function storyCounts(map) {
+    const nonTaskColors = new Set((map.legend || []).filter(e => !/task/i.test(e.label || '')).map(e => e.color));
+    let done = 0, total = 0;
+    for (const slice of map.slices || []) {
+        for (const cards of Object.values(slice.stories || {})) {
+            if (!Array.isArray(cards)) continue;
+            for (const card of cards) {
+                if (card.color && nonTaskColors.has(card.color)) continue;
+                total++;
+                if (card.status === 'done') done++;
+            }
+        }
+    }
+    return { done, total };
+}
+
+export { bar, pct };
+
 export async function statusCommand(target, opts) {
+    // A project: one line per map and a total, from the folder or, for a project link, the server
+    const link = parseProjectLink(target);
+    if (link && !link.mapId) {
+        const { statusProject } = await import('./project-sync.js');
+        await statusProject({ baseUrl: link.baseUrl, projectId: link.projectId, files: null });
+        return;
+    }
+    if (!target) {
+        const ctx = await findProjectFolder(opts);
+        if (ctx?.projectId) {
+            const { statusProject } = await import('./project-sync.js');
+            await statusProject(ctx);
+            return;
+        }
+    }
+
     const content = await loadContent(target, opts);
 
     const map = jsyaml.load(content);

package/lib/commands/unlock.js

@@ -1,35 +1,50 @@
 // Storymaps CLI — AGPL-3.0 — see LICENCE for details
-// storymaps unlock — session unlock or permanently remove a map lock
+// storymaps unlock — unlock one map on this computer, or remove its lock.
+// Unlocking a whole project is storymaps project unlock.
 
-import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
-import { password } from '@inquirer/prompts';
 import chalk from 'chalk';
+import jsyaml from 'js-yaml';
 import { resolveTarget } from '../util/identity.js';
-import { unlockMap, removeLock } from '../util/api.js';
+import { unlockMap, removeLock, ApiError } from '../util/api.js';
 import { writeCache } from '../util/file.js';
+import { findProjectFolder, setLockedInFile } from '../util/project.js';
+import { askPassword, StopError, PASSWORD_ENV } from '../util/prompt.js';
 
 export async function unlockCommand(target, opts) {
+    if (!target && !opts.file && await findProjectFolder(opts)) {
+        throw new StopError('Name a map with -f. To unlock the whole project, run storymaps project unlock');
+    }
     const filePath = resolve(opts.file || 'storymap.yml');
     let id, baseUrl;
     try {
         ({ id, baseUrl } = await resolveTarget(target, filePath));
-    } catch {
-        console.error(chalk.red('No map ID found. Run "storymaps push" to create it on the server, or pass one directly: storymaps unlock <id>'));
-        process.exitCode = 1;
-        return;
+    } catch (err) {
+        if (/whole project/.test(err.message)) throw new StopError(`${err.message.split('.')[0]}. To unlock the whole project, run storymaps project unlock`);
+        throw new StopError('No map ID found. Run "storymaps push" to create it on the server, or pass one directly: storymaps unlock <id>');
+    }
+    let name = id;
+    if (!target) {
+        try {
+            name = jsyaml.load(await readFile(filePath, 'utf-8'))?.name || id;
+        } catch { /* no file */ }
     }
 
-    const pw = await password({ theme: { prefix: '>' }, message: 'Password:' });
-    const passwordHash = createHash('sha256').update(pw).digest('hex');
-
-    if (opts.remove) {
-        await removeLock(baseUrl, id, passwordHash);
-        await writeCache(id, { hash: null });
-        console.log(chalk.green(`Lock removed from map ${id}.`));
-    } else {
-        await unlockMap(baseUrl, id, passwordHash);
-        await writeCache(id, { hash: passwordHash });
-        console.log(chalk.green(`Map ${id} unlocked.`));
+    const passwordHash = await askPassword({ noPasswordMessage: `Unlocking needs the password, and there's no terminal to type it in. Set ${PASSWORD_ENV} for this command.` });
+    try {
+        if (opts.remove) {
+            await removeLock(baseUrl, id, passwordHash);
+            if (!target) await setLockedInFile(filePath, false);
+            await writeCache(id, { hash: null });
+            console.log(chalk.green(`Removed the lock from ${name}.`));
+        } else {
+            await unlockMap(baseUrl, id, passwordHash);
+            await writeCache(id, { hash: passwordHash });
+            console.log(chalk.green(`Unlocked ${name} on this computer.`));
+        }
+    } catch (err) {
+        if (err instanceof ApiError && err.status === 403) throw new StopError('Incorrect password.');
+        throw err;
     }
 }

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;
 
@@ -235,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;