storymaps 1.2.4 → 1.2.6

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/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/lib/core/constants.js

@@ -21,6 +21,28 @@ export const isValidUrl = (url) => {
     }
 };
 
+// Slice goal and target date are optional. The date is stored as YYYY-MM-DD; YAML can parse an
+// unquoted date as a Date, so accept that too. Anything else is dropped.
+export const SLICE_GOAL_MAX_LENGTH = 200;
+
+export const normalizeSliceGoal = (value) =>
+    typeof value === 'string' ? value.trim().slice(0, SLICE_GOAL_MAX_LENGTH) : '';
+
+export const normalizeSliceDate = (value) => {
+    if (value instanceof Date && !isNaN(value)) return value.toISOString().slice(0, 10);
+    if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return '';
+    return isNaN(new Date(`${value}T00:00:00Z`)) ? '' : value;
+};
+
+// Copies a slice's goal and target date from one object to another, leaving out empty values
+export const copySliceDetails = (from, to) => {
+    const goal = normalizeSliceGoal(from.goal);
+    const targetDate = normalizeSliceDate(from.targetDate);
+    if (goal) to.goal = goal;
+    if (targetDate) to.targetDate = targetDate;
+    return to;
+};
+
 export const CARD_COLORS = {
     red: '#fca5a5',
     rose: '#fecdd3',

package/lib/core/yaml.js

@@ -2,7 +2,7 @@
 // YAML ↔ JSON transform + validation
 
 import jsyaml from 'js-yaml';
-import { generateId } from './constants.js';
+import { generateId, copySliceDetails } from './constants.js';
 
 const DEFAULT_STEP_COLOR = '#86efac';
 const DEFAULT_STORY_COLOR = '#fef08a';
@@ -54,10 +54,12 @@ export function jsonToYamlObj(data) {
         partialSlugMap[pm.id] = slugify(pm.name) || pm.id;
     });
 
-    // Classify each step
-    const stepTypes = steps.map(step => {
+    // Classify each step. A hidden step with a name or cards is written as a normal step so its
+    // cards survive (only empty, unnamed hidden steps are spacers).
+    const hasCards = (i) => !!(usersArr[i]?.length || activitiesArr[i]?.length || slices.some(s => s.stories?.[i]?.length));
+    const stepTypes = steps.map((step, i) => {
         if (step.partialMapId) return 'partial';
-        if (step.hidden) return 'spacer';
+        if (step.hidden && !step.name && !hasCards(i)) return 'spacer';
         return 'step';
     });
 
@@ -70,41 +72,17 @@ export function jsonToYamlObj(data) {
     });
     const duplicateNames = new Set(Object.keys(nameCounts).filter(n => nameCounts[n] > 1));
 
-    // Resolve names — namespace duplicates with nearest activity/user
+    // Number duplicate names (Confirm[0], Confirm[1]) so cards point at the right step.
+    // Import strips the number, so the names come back unchanged.
+    const counters = {};
     const resolvedNames = steps.map((step, i) => {
         if (stepTypes[i] !== 'step') return null;
         const name = step.name || '';
         if (!duplicateNames.has(name)) return name;
-        for (let j = i; j >= 0; j--) {
-            if (activitiesArr[j]?.length) return `${activitiesArr[j][0].name}: ${name}`;
-        }
-        for (let j = i; j >= 0; j--) {
-            if (usersArr[j]?.length) return `${usersArr[j][0].name}: ${name}`;
-        }
-        return name;
-    });
-
-    // Second pass: add :[N] suffix to any still-duplicate resolved names
-    const resolvedCounts = {};
-    resolvedNames.forEach(n => {
-        if (n != null) resolvedCounts[n] = (resolvedCounts[n] || 0) + 1;
+        const idx = counters[name] || 0;
+        counters[name] = idx + 1;
+        return `${name}[${idx}]`;
     });
-    const stillDuplicate = new Set(Object.keys(resolvedCounts).filter(n => resolvedCounts[n] > 1));
-    if (stillDuplicate.size) {
-        const counters = {};
-        for (let i = 0; i < resolvedNames.length; i++) {
-            const n = resolvedNames[i];
-            if (n == null || !stillDuplicate.has(n)) continue;
-            const idx = counters[n] || 0;
-            counters[n] = idx + 1;
-            const colonPos = n.indexOf(': ');
-            if (colonPos >= 0) {
-                resolvedNames[i] = n.slice(0, colonPos + 1) + `[${idx}]` + n.slice(colonPos + 1);
-            } else {
-                resolvedNames[i] = `${n}[${idx}]`;
-            }
-        }
-    }
 
     // Build YAML object
     const result = {};
@@ -177,14 +155,14 @@ export function jsonToYamlObj(data) {
         const hasExtra = (step.color && step.color !== DEFAULT_STEP_COLOR)
             || step.body || step.url || step.status || step.points != null || step.tags?.length;
         if (!hasExtra) return name;
-        const obj = { name };
-        if (step.color && step.color !== DEFAULT_STEP_COLOR) obj.color = step.color;
-        if (step.body) obj.body = step.body;
-        if (step.url) obj.url = step.url;
-        if (step.status) obj.status = step.status;
-        if (step.points != null) obj.points = step.points;
-        if (step.tags?.length) obj.tags = [...step.tags];
-        return obj;
+        const s = { name };
+        if (step.color && step.color !== DEFAULT_STEP_COLOR) s.color = step.color;
+        if (step.body) s.body = step.body;
+        if (step.url) s.url = step.url;
+        if (step.status) s.status = step.status;
+        if (step.points != null) s.points = step.points;
+        if (step.tags?.length) s.tags = step.tags;
+        return s;
     });
 
     // Legend
@@ -196,6 +174,7 @@ export function jsonToYamlObj(data) {
             const obj = { name: slice.name || '' };
             if (slice.collapsed) obj.collapsed = true;
             if (slice.closedReason) obj.closedReason = slice.closedReason;
+            copySliceDetails(slice, obj);
             const stories = {};
             (slice.stories || []).forEach((cards, i) => {
                 if (!cards?.length) return;
@@ -273,6 +252,7 @@ export function validateYaml(obj) {
         const label = slice.name || `#${si}`;
         if (slice.stories) {
             for (const [stepName, cards] of Object.entries(slice.stories)) {
+                if (!stepName) continue;
                 if (!stepNameSet.has(stepName)) {
                     errors.push(`Slice "${label}" references unknown step "${stepName}"`);
                 }
@@ -336,7 +316,7 @@ export function yamlObjToJson(obj) {
             if (step.url) s.url = step.url;
             if (step.status) s.status = step.status;
             if (step.points != null) s.points = step.points;
-            if (step.tags?.length) s.tags = [...step.tags];
+            if (step.tags?.length) s.tags = step.tags;
         }
         jsonSteps.push(s);
     });
@@ -368,6 +348,7 @@ export function yamlObjToJson(obj) {
         const s = { name: slice.name || '', stories };
         if (slice.collapsed) s.collapsed = true;
         if (slice.closedReason) s.closedReason = slice.closedReason;
+        copySliceDetails(slice, s);
         return s;
     });
 
@@ -426,7 +407,8 @@ export function yamlObjToJson(obj) {
     };
 
     if (obj.legend?.length) result.legend = obj.legend;
-    if (obj.notes) result.notes = obj.notes;
+    // Keep empty notes so a push with notes: "" clears them (no notes key leaves them alone)
+    if (typeof obj.notes === 'string') result.notes = obj.notes;
     if (jsonPartialMaps.length) result.partialMaps = jsonPartialMaps;
     if (obj.backups?.length) result.backups = obj.backups;
     return result;
@@ -446,6 +428,10 @@ function backboneToYaml(positionalArr, namesByIndex) {
             const obj = { name: card.name };
             if (card.body) obj.body = card.body;
             if (card.color) obj.color = card.color;
+            if (card.status) obj.status = card.status;
+            if (card.points != null) obj.points = card.points;
+            if (card.tags?.length) obj.tags = [...card.tags];
+            if (card.url) obj.url = card.url;
             obj.step = stepName;
             result.push(obj);
         });

package/lib/util/api.js

@@ -10,9 +10,18 @@ class ApiError extends Error {
     }
 }
 
+// The server sends errors as JSON ({"error": "..."}), so show just the message
+function errorMessage(body) {
+    try {
+        return JSON.parse(body).error || body;
+    } catch {
+        return body;
+    }
+}
+
 async function handleResponse(res) {
     if (res.ok) return;
-    const body = await res.text().catch(() => '');
+    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 });

package/lib/util/summary.js

@@ -3,6 +3,7 @@
 
 import chalk from 'chalk';
 import jsyaml from 'js-yaml';
+import { normalizeSliceGoal, normalizeSliceDate } from '../core/constants.js';
 
 // Fields compared on cards and steps that exist on both sides
 const FIELDS = ['body', 'color', 'url', 'status', 'points', 'tags'];
@@ -187,6 +188,16 @@ export function changeSummary(oldYaml, newYaml) {
             const state = !slice.collapsed ? 'reopened' : slice.closedReason === 'closed' ? 'closed' : 'completed';
             lines.push(chalk.yellow(`  ~ slice: ${oneLine(slice.name)} ${state}`));
         }
+        const [oldGoal, newGoal] = [normalizeSliceGoal(before.goal), normalizeSliceGoal(slice.goal)];
+        if (oldGoal !== newGoal) {
+            const change = !oldGoal ? 'set' : !newGoal ? 'removed' : 'changed';
+            lines.push(chalk.yellow(`  ~ slice: ${oneLine(slice.name)} goal ${change}`));
+        }
+        const [oldDate, newDate] = [normalizeSliceDate(before.targetDate), normalizeSliceDate(slice.targetDate)];
+        if (oldDate !== newDate) {
+            const change = !oldDate ? `set to ${newDate}` : !newDate ? 'removed' : `moved to ${newDate}`;
+            lines.push(chalk.yellow(`  ~ slice: ${oneLine(slice.name)} target date ${change}`));
+        }
     }
 
     // Cards: users, activities and stories in every slice

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "storymaps",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "CLI tool for storymaps.io - import, export, validate, and manage user story maps from the terminal",
   "type": "module",
   "bin": {
     "storymaps": "./bin/storymaps.js"
   },
+  "scripts": {
+    "test": "node --test 'test/unit/**/*.test.js'",
+    "test:integration": "node --test 'test/integration/**/*.test.js'"
+  },
   "keywords": [
     "story-mapping",
     "user-story",