storymaps 1.2.7 → 1.2.9

package/README.md

@@ -23,6 +23,12 @@ Story maps are structured data. The CLI lets you export the structure behind the
 npm install -g storymaps
 ```
 
+Or run it without installing, the way the Build with AI command on storymaps.io does:
+
+```bash
+npx storymaps pull storymaps.io/abc123
+```
+
 Or clone and link locally:
 
 ```bash
@@ -43,6 +49,7 @@ Or pull an existing map:
 
 ```bash
 storymaps pull storymaps.io/abc123    # download as YAML
+storymaps pull storymaps.io/p/k8f2m9xq/abc123    # a map inside a project link works too
 ```
 
 Edit the YAML, then push it back:
@@ -104,17 +111,19 @@ storymaps open storymaps.io/abc123    # open a specific remote map
 ```bash
 storymaps pull                        # uses id/site from storymap.yml
 storymaps pull storymaps.io/abc123    # pull a specific map
+storymaps pull --force                # overwrite the local file without asking
 ```
 
-Shows a summary of changes before overwriting.
+Shows a summary of changes and asks before overwriting the local file, unless you pass `--force`.
 
 ### `push`
 
 ```bash
 storymaps push                        # push local changes to the server
+storymaps push --force                # skip the conflict check and overwrite the server copy
 ```
 
-If the file has no `id`, a new map is created on the server. Conflicts are detected using ETags. If the remote has changed since your last pull, you'll be prompted to pull first. Locked maps prompt for the password.
+If the file has no `id`, a new map is created on the server. Conflicts are detected using ETags. If the remote has changed since your last pull, you'll be prompted to pull first; `--force` pushes anyway and replaces whatever changed on the server. Locked maps prompt for the password.
 
 ### `diff`
 
@@ -156,6 +165,12 @@ storymaps unlock --remove             # permanently remove the lock
 storymaps validate storymap.yml       # check YAML structure
 ```
 
+### Options
+
+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` and `log` take `-f, --file <path>` to use a file other than `storymap.yml`.
+
 ### `convert`
 
 ```bash
@@ -259,6 +274,16 @@ Cards support: `name`, `body`, `color`, `status` (done / in-progress / planned /
 
 Slices support: `name`, `stories`, `goal` (up to 200 characters), `targetDate` (`YYYY-MM-DD`), and `collapsed` with `closedReason` (complete / closed).
 
+## Use with AI Coding Agents
+
+A story map makes a good specification for an AI coding agent: the YAML lists every step of the journey and the cards under each one, slice by slice. **Build with AI** on storymaps.io writes the command for you:
+
+```bash
+npx storymaps pull --force storymaps.io/abc123 && claude "The storymap file @storymap.yml describes a product plan in user story map format. Use it as a structured specification. Your task: build a functional prototype of the features listed in the 'MVP' slice."
+```
+
+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.
+
 ## Self-Hosting
 
 The CLI works with any storymaps.io instance:
@@ -269,6 +294,8 @@ storymaps init --site storymaps.yourcompany.com
 
 See the [main project README](https://github.com/jackgleeson/storymaps.io#self-hosting) for setup instructions.
 
+Every request names the CLI and its version in the User-Agent header (`storymaps-cli/<version>`), so CLI use shows up as such in your server logs.
+
 ## Development
 
 ```bash
@@ -283,7 +310,7 @@ To try a change against a local storymaps.io server, run the CLI from the repo,
 ### 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.
+2. Bump the version in `package.json` and in both places near the top of `package-lock.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

package/lib/util/api.js

@@ -1,6 +1,14 @@
 // Storymaps CLI — AGPL-3.0 — see LICENCE for details
 // HTTP client for storymaps.io API (uses Node 18+ built-in fetch)
 
+import { readFileSync } from 'node:fs';
+
+// Every request names the CLI and its version, so the server can tell CLI use from other scripts
+const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf-8'));
+export const USER_AGENT = `storymaps-cli/${pkg.version}`;
+
+const request = (url, opts = {}) => fetch(url, { ...opts, headers: { 'User-Agent': USER_AGENT, ...opts.headers } });
+
 class ApiError extends Error {
     constructor(message, status, { conflict = false } = {}) {
         super(message);
@@ -32,7 +40,7 @@ async function handleResponse(res) {
 }
 
 export async function getMap(baseUrl, id, format = 'yaml') {
-    const res = await fetch(`${baseUrl}/api/maps/${id}?format=${format}`);
+    const res = await request(`${baseUrl}/api/maps/${id}?format=${format}`);
     await handleResponse(res);
     const etag = res.headers.get('etag');
     const data = format === 'json' ? await res.json() : await res.text();
@@ -43,7 +51,7 @@ export async function putMap(baseUrl, id, body, { etag, contentType = 'text/yaml
     const headers = { 'Content-Type': contentType };
     if (etag) headers['If-Match'] = etag;
     if (lockPasswordHash) headers['X-Lock-Password'] = lockPasswordHash;
-    const res = await fetch(`${baseUrl}/api/maps/${id}`, {
+    const res = await request(`${baseUrl}/api/maps/${id}`, {
         method: 'PUT',
         headers,
         body,
@@ -53,7 +61,7 @@ export async function putMap(baseUrl, id, body, { etag, contentType = 'text/yaml
 }
 
 export async function postMap(baseUrl, body, contentType = 'text/yaml') {
-    const res = await fetch(`${baseUrl}/api/maps`, {
+    const res = await request(`${baseUrl}/api/maps`, {
         method: 'POST',
         headers: { 'Content-Type': contentType },
         body,
@@ -63,19 +71,19 @@ export async function postMap(baseUrl, body, contentType = 'text/yaml') {
 }
 
 export async function getNewId(baseUrl) {
-    const res = await fetch(`${baseUrl}/api/maps/new-id`);
+    const res = await request(`${baseUrl}/api/maps/new-id`);
     await handleResponse(res);
     return res.json();
 }
 
 export async function getLockStatus(baseUrl, id) {
-    const res = await fetch(`${baseUrl}/api/lock/${id}`);
+    const res = await request(`${baseUrl}/api/lock/${id}`);
     await handleResponse(res);
     return res.json();
 }
 
 export async function lockMap(baseUrl, id, passwordHash) {
-    const res = await fetch(`${baseUrl}/api/lock/${id}`, {
+    const res = await request(`${baseUrl}/api/lock/${id}`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ passwordHash }),
@@ -85,7 +93,7 @@ export async function lockMap(baseUrl, id, passwordHash) {
 }
 
 export async function unlockMap(baseUrl, id, passwordHash) {
-    const res = await fetch(`${baseUrl}/api/lock/${id}/unlock`, {
+    const res = await request(`${baseUrl}/api/lock/${id}/unlock`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ passwordHash }),
@@ -96,7 +104,7 @@ export async function unlockMap(baseUrl, id, passwordHash) {
 }
 
 export async function removeLock(baseUrl, id, passwordHash) {
-    const res = await fetch(`${baseUrl}/api/lock/${id}/remove`, {
+    const res = await request(`${baseUrl}/api/lock/${id}/remove`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ passwordHash }),
@@ -107,7 +115,7 @@ export async function removeLock(baseUrl, id, passwordHash) {
 }
 
 export async function getLog(baseUrl, id) {
-    const res = await fetch(`${baseUrl}/api/maps/${id}/log`);
+    const res = await request(`${baseUrl}/api/maps/${id}/log`);
     await handleResponse(res);
     return res.json();
 }

package/package.json

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