storymaps 1.2.5 → 1.2.7

package/README.md

@@ -257,6 +257,8 @@ slices:
 
 Cards support: `name`, `body`, `color`, `status` (done / in-progress / planned / blocked), `points`, `tags`, and `url`.
 
+Slices support: `name`, `stories`, `goal` (up to 200 characters), `targetDate` (`YYYY-MM-DD`), and `collapsed` with `closedReason` (complete / closed).
+
 ## Self-Hosting
 
 The CLI works with any storymaps.io instance:
@@ -267,6 +269,36 @@ storymaps init --site storymaps.yourcompany.com
 
 See the [main project README](https://github.com/jackgleeson/storymaps.io#self-hosting) for setup instructions.
 
+## Development
+
+```bash
+npm install
+npm test
+```
+
+`npm test` runs the unit tests in `test/unit` with Node's built-in test runner (Node 22 or later). They cover the YAML format, the API client, the change summary, and how a target resolves to a map, with no server needed. CI runs them on Node 22 and 24 for every push to `main` and every pull request.
+
+To try a change against a local storymaps.io server, run the CLI from the repo, for example `node bin/storymaps.js pull localhost/<map-id>`.
+
+### Releasing
+
+1. Commit your changes on `main`.
+2. Bump the version in `package.json` and commit it as "Bump version to x.y.z". Use a patch for fixes and a minor version for new features.
+3. Tag the commit and push both:
+   ```bash
+   git tag vx.y.z
+   git push origin main vx.y.z
+   ```
+4. Check you're logged in to npm, then publish:
+   ```bash
+   npm whoami        # if this fails, run npm login
+   npm pack --dry-run   # optional: list what will be published
+   npm publish
+   ```
+5. Confirm the new version is live with `npm view storymaps version`.
+
+Only `bin/`, `lib/`, the README and the licence are published (see `files` in `package.json`).
+
 ## Licence
 
 AGPL-3.0 - see [LICENCE](LICENCE) for details.

package/lib/commands/diff.js

@@ -29,14 +29,17 @@ export async function diffCommand(source, target, opts) {
     const sourcePath = resolve(source || 'storymap.yml');
     const sourceYaml = await readAndNormalise(sourcePath);
 
-    let targetYaml;
-    let targetLabel;
+    // Show changes from old to new. Two local files go from the first to the second. Against the
+    // remote, the local file is the new side, so the diff shows what a push would change.
+    let oldYaml, newYaml, oldLabel, newLabel;
 
     if (target) {
         // Two local files
         const targetPath = resolve(target);
-        targetYaml = await readAndNormalise(targetPath);
-        targetLabel = targetPath;
+        oldYaml = sourceYaml;
+        newYaml = await readAndNormalise(targetPath);
+        oldLabel = sourcePath;
+        newLabel = targetPath;
     } else {
         // Local vs remote
         const { id, baseUrl } = await resolveTarget(undefined, sourcePath);
@@ -44,11 +47,13 @@ export async function diffCommand(source, target, opts) {
         // Normalise remote YAML the same way
         const obj = jsyaml.load(data);
         const json = yamlObjToJson(obj);
-        targetYaml = exportToYaml(json);
-        targetLabel = `${baseUrl}/${id}`;
+        oldYaml = exportToYaml(json);
+        newYaml = sourceYaml;
+        oldLabel = `remote: ${baseUrl}/${id}`;
+        newLabel = `local: ${sourcePath}`;
     }
 
-    const changes = diffLines(sourceYaml, targetYaml);
+    const changes = diffLines(oldYaml, newYaml);
     const hasChanges = changes.some(c => c.added || c.removed);
 
     if (!hasChanges) {
@@ -57,7 +62,7 @@ export async function diffCommand(source, target, opts) {
     }
 
     if (!opts.full) {
-        printChangeSummary(sourceYaml, targetYaml);
+        printChangeSummary(oldYaml, newYaml);
         console.log(chalk.dim(`\nRun ${chalk.cyan('storymaps diff --full')} for the full file diff.`));
         return;
     }
@@ -65,25 +70,25 @@ export async function diffCommand(source, target, opts) {
     // --full: show line-level diff
     const CONTEXT = 3;
     const lines = [];
-    let srcLine = 1;
-    let dstLine = 1;
+    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, src: null, dst: dstLine++ });
+                lines.push({ tag: '+', text, oldNum: null, newNum: newLine++ });
             } else if (part.removed) {
-                lines.push({ tag: '-', text, src: srcLine++, dst: null });
+                lines.push({ tag: '-', text, oldNum: oldLine++, newNum: null });
             } else {
-                lines.push({ tag: ' ', text, src: srcLine++, dst: dstLine++ });
+                lines.push({ tag: ' ', text, oldNum: oldLine++, newNum: newLine++ });
             }
         }
     }
 
-    const width = String(Math.max(srcLine, dstLine)).length;
+    const width = String(Math.max(oldLine, newLine)).length;
     const pad = n => n === null ? ' '.repeat(width) : String(n).padStart(width);
 
-    console.log(chalk.bold(`--- local: ${sourcePath}`));
-    console.log(chalk.bold(`+++ remote: ${targetLabel}`));
+    console.log(chalk.bold(`--- ${oldLabel}`));
+    console.log(chalk.bold(`+++ ${newLabel}`));
 
     let lastPrinted = -1;
     for (let i = 0; i < lines.length; i++) {
@@ -92,8 +97,8 @@ export async function diffCommand(source, target, opts) {
         if (lastPrinted !== -1 && i - lastPrinted > 1) {
             console.log(chalk.dim(`${'·'.repeat(width * 2 + 5)}`));
         }
-        const { tag, text, src, dst } = lines[i];
-        const num = chalk.dim(`${pad(src)} ${pad(dst)}`);
+        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}`)}`);

package/lib/commands/init.js

@@ -36,11 +36,6 @@ slices:
     stories:
       New Step:
         - name: New Task or Detail
-notes: >-
-  Thanks for trying Storymaps.io! If you find it useful, please consider starring the open-source repo:
-  https://github.com/jackgleeson/storymaps.io
-
-  Have a great day!
 `;
 }
 
@@ -83,7 +78,8 @@ export async function initCommand(opts) {
     try {
         const { 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})\n`));
+        console.log(chalk.green(`Created storymap.yml (map ID: ${id})`));
+        console.log(`${chalk.cyan(`${baseUrl}/${id}`)}\n`);
     } catch {
         console.log(chalk.green('Created storymap.yml\n'));
         console.log(chalk.dim('Tip: run "storymaps push" to upload the map when you\'re ready to sync.\n'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "storymaps",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "description": "CLI tool for storymaps.io - import, export, validate, and manage user story maps from the terminal",
   "type": "module",
   "bin": {