storymaps 1.1.0 → 1.1.2

package/README.md

@@ -1,8 +1,8 @@
 # Storymaps CLI
 
-The Storymaps CLI turns your storymaps.io map diagrams into YAML files you can version-control in git, diff in pull requests, and sync with the [storymaps.io](https://storymaps.io) server or your self-hosted instance all from your terminal. Built by developers for developers. 
+Turn your [storymaps.io](https://storymaps.io) diagrams into YAML files you can version-control, diff in pull requests, and sync with the server - all from your terminal.
 
-Story maps aren't just cards on a screen, they're structured data. The CLI lets you import the structure behind the diagram, edit it as code, and convert back and forth between your repo and the browser.
+Story maps are structured data. The CLI lets you export the structure behind the diagram, edit it as code, and push changes back to the browser.
 
 ```diff
 # What a story map change looks like in a pull request
@@ -36,7 +36,7 @@ npm link
 
 ```bash
 storymaps init                        # create a new storymap.yml
-storymaps open                        # view it in the browser
+storymaps open                        # open it in the browser
 ```
 
 Or pull an existing map:
@@ -45,15 +45,17 @@ Or pull an existing map:
 storymaps pull storymaps.io/abc123    # download as YAML
 ```
 
-Edit the YAML in your editor, then push it back:
+Edit the YAML, then push it back:
 
 ```bash
 storymaps diff                        # see what changed
-storymaps push                        # upload to the server
+storymaps push                        # sync to the server
 ```
 
 ## Status
 
+See the project status in a snapshot: 
+
 ```bash
 > storymaps status
 
@@ -77,7 +79,7 @@ Blocked
   ● Scan QR code
 ```
 
-Non-task cards (notes, questions) are excluded from stats counts based on the legend.
+Non-task cards (notes, questions) are excluded from counts based on the legend.
 
 ## Commands
 
@@ -93,7 +95,7 @@ Creates `storymap.yml` and registers it on the server. If you're offline, the fi
 ### `open`
 
 ```bash
-storymaps open                        # opens local storymap.yml in the web UI to work with
+storymaps open                        # open local storymap.yml in the browser
 storymaps open storymaps.io/abc123    # open a specific remote map
 ```
 
@@ -104,32 +106,37 @@ storymaps pull                        # uses id/site from storymap.yml
 storymaps pull storymaps.io/abc123    # pull a specific map
 ```
 
-Shows a change summary before overwriting.
+Shows a summary of changes before overwriting.
 
 ### `push`
 
 ```bash
-storymaps push                       # push local changes to the server
+storymaps push                        # push local changes to the server
 ```
 
-If the file has no `id`, a new map is created automatically. Conflicts are detected using ETags - if the remote 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. Locked maps prompt for the password.
 
 ### `diff`
 
 ```bash
-storymaps diff                        # summary vs remote
-storymaps diff --full                 # line-by-line diff
+storymaps diff                        # summary of changes vs remote
+storymaps diff --full                 # full line-by-line diff
 storymaps diff file1.yml file2.yml    # compare two local files
 ```
 
 ### `status`
 
-Progress overview - slices, status counts, blocked stories.
+```bash
+storymaps status                      # progress overview of storymap.yml
+storymaps status other.yml            # progress overview of a specific file
+```
+
+Progress overview: slices, status counts, and blocked stories.
 
 ### `lock` / `unlock`
 
 ```bash
-storymaps lock
+storymaps lock                        # lock the map with a password
 storymaps unlock                      # session unlock
 storymaps unlock --remove             # permanently remove the lock
 ```
@@ -137,29 +144,16 @@ storymaps unlock --remove             # permanently remove the lock
 ### `validate`
 
 ```bash
-storymaps validate storymap.yml
+storymaps validate storymap.yml       # check YAML structure
 ```
 
 ### `convert`
 
 ```bash
-storymaps convert storymap.yml --to json
-storymaps convert storymap.json --to yaml --out storymap.yml
-```
-
-### `import`
-
-Import tasks from an external project tracker into a storymap. Currently supports Phabricator.
-
-```bash
-storymaps import --from phabricator --tag my-project
-storymaps import --from phab --tag my-project --site localhost
-storymaps import --from phab --tag my-project --status open,in-progress
+storymaps convert storymap.yml --to json                    # YAML to JSON
+storymaps convert storymap.json --to yaml --out storymap.yml # JSON to YAML
 ```
 
-Epics (tasks tagged with `Epic` in Phabricator) become steps with their subtasks as cards. Standalone tasks are grouped into backlog columns. The map is registered on the server automatically.
-
-On first run you'll be prompted for your Phabricator instance URL and Conduit API token. Credentials are saved to `~/.storymaps/credentials.json`.
 
 ## YAML Format
 
@@ -266,4 +260,4 @@ See the [main project README](https://github.com/jackgleeson/userstorymaps#self-
 
 ## Licence
 
-AGPL-3.0 - see [LICENCE](LICENCE) for details.
+AGPL-3.0 - see [LICENCE](LICENCE) for details.

package/bin/storymaps.js

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 // Storymaps CLI — AGPL-3.0 — see LICENCE for details
 
+import { readFileSync } from 'node:fs';
 import chalk from 'chalk';
 import { Command } from 'commander';
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
 import { initCommand } from '../lib/commands/init.js';
 import { validateCommand } from '../lib/commands/validate.js';
 import { convertCommand } from '../lib/commands/convert.js';
@@ -13,14 +16,14 @@ import { openCommand } from '../lib/commands/open.js';
 import { lockCommand } from '../lib/commands/lock.js';
 import { unlockCommand } from '../lib/commands/unlock.js';
 import { statusCommand } from '../lib/commands/status.js';
-import { importCommand } from '../lib/commands/import.js';
+
 
 const program = new Command();
 
 program
     .name('storymaps')
     .description('CLI companion for storymaps.io — manage user story maps from the terminal')
-    .version('0.0.1')
+    .version(pkg.version)
     .showHelpAfterError()
     .addHelpText('after', '\nRun storymaps <command> --help for details on a specific command.');
 
@@ -98,15 +101,6 @@ program
     .option('-f, --file <path>', 'path to storymap file', 'storymap.yml')
     .action(statusCommand);
 
-program
-    .command('import')
-    .description('Import tasks from an external tool into a storymap')
-    .requiredOption('--from <source>', 'source platform (phabricator)')
-    .requiredOption('--tag <slug>', 'project tag/slug to import from')
-    .option('--status <statuses>', 'comma-separated statuses to import', 'open,in-progress,stalled,resolved')
-    .option('--output <path>', 'output file path', 'storymap.yml')
-    .option('-s, --site <site>', 'target site (e.g. localhost, storymaps.io)')
-    .action(importCommand);
 
 program.parseAsync().catch(err => {
     const message = err.name === 'ExitPromptError' ? 'Cancelled.'

package/lib/util/file.js

@@ -9,7 +9,6 @@ import { exportToYaml } from '../core/yaml.js';
 
 const STORYMAPS_DIR = join(homedir(), '.storymaps');
 const CACHE_DIR = join(STORYMAPS_DIR, 'caches');
-const CREDENTIALS_PATH = join(STORYMAPS_DIR, 'credentials.json');
 
 function cachePathFor(mapId) {
     return join(CACHE_DIR, `${mapId}.json`);
@@ -33,24 +32,6 @@ export async function writeCache(mapId, updates) {
     await writeFile(cachePathFor(mapId), JSON.stringify(cache), 'utf-8');
 }
 
-export async function readCredentials(platform) {
-    try {
-        const all = JSON.parse(await readFile(CREDENTIALS_PATH, 'utf-8'));
-        return all[platform] || null;
-    } catch {
-        return null;
-    }
-}
-
-export async function writeCredentials(platform, credentials) {
-    await mkdir(STORYMAPS_DIR, { recursive: true });
-    let all = {};
-    try {
-        all = JSON.parse(await readFile(CREDENTIALS_PATH, 'utf-8'));
-    } catch { /* first write */ }
-    all[platform] = credentials;
-    await writeFile(CREDENTIALS_PATH, JSON.stringify(all, null, 2) + '\n', 'utf-8');
-}
 
 export function detectFormat(filePath) {
     const ext = extname(filePath).toLowerCase();

package/package.json

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

package/lib/commands/import.js

@@ -1,249 +0,0 @@
-// Storymaps CLI — AGPL-3.0 — see LICENCE for details
-// storymaps import — import tasks from an external tool into a storymap
-
-import { existsSync } from 'node:fs';
-import { resolve } from 'node:path';
-import chalk from 'chalk';
-import { input, password, confirm } from '@inquirer/prompts';
-import { readCredentials, writeCredentials, writeStorymap } from '../util/file.js';
-import { dumpYaml } from '../core/yaml.js';
-import { postMap } from '../util/api.js';
-import {
-    findProject,
-    findEpicTagPhid,
-    fetchTasks,
-    fetchTasksByPhids,
-    fetchSubtaskEdges,
-    CLI_TO_PHAB_STATUS,
-    PHAB_TO_STORYMAP_STATUS,
-} from '../util/phabricator.js';
-
-const CARDS_PER_COLUMN = 10;
-
-async function promptCredentials(defaultUrl) {
-    const url = await input({
-        message: 'Phabricator instance URL:',
-        default: defaultUrl,
-        theme: { prefix: '>' },
-        validate: v => v.startsWith('http') || 'Must be a full URL (https://...)',
-    });
-    console.log();
-    console.log(chalk.dim('  To get your API token:'));
-    console.log(chalk.dim('  1. Click your profile picture in Phabricator'));
-    console.log(chalk.dim('  2. Go to Settings'));
-    console.log(chalk.dim('  3. Click "Conduit API Tokens"'));
-    console.log(chalk.dim('  4. Click "Generate Token"'));
-    console.log();
-    const token = await password({
-        message: 'API token:',
-        mask: '*',
-        theme: { prefix: '>' },
-    });
-    return { url: url.replace(/\/+$/, ''), token };
-}
-
-async function getCredentials() {
-    const saved = await readCredentials('phabricator');
-    if (saved?.url && saved?.token) {
-        console.log(chalk.dim(`Using saved Phabricator credentials (${saved.url})`));
-        return saved;
-    }
-    const creds = await promptCredentials(saved?.url);
-    await writeCredentials('phabricator', creds);
-    console.log(chalk.dim('Credentials saved to ~/.storymaps/credentials.json'));
-    return creds;
-}
-
-function buildYamlObj(projectName, epics, standalones, baseUrl, site) {
-    const steps = [];
-    const importedStories = {};
-    const backlogStories = {};
-
-    // Epic steps + stories
-    for (const epic of epics) {
-        const step = { name: epic.name };
-        if (epic.description) step.body = epic.description;
-        step.url = `${baseUrl}/T${epic.id}`;
-        if (epic.points != null) step.points = epic.points;
-        steps.push(step);
-        importedStories[epic.name] = epic.children.map(task => taskToCard(task, baseUrl));
-    }
-
-    // Backlog columns
-    const numColumns = Math.max(1, Math.ceil(standalones.length / CARDS_PER_COLUMN));
-    for (let col = 0; col < numColumns; col++) {
-        const stepName = String(col + 1);
-        steps.push(stepName);
-        const chunk = standalones.slice(col * CARDS_PER_COLUMN, (col + 1) * CARDS_PER_COLUMN);
-        if (chunk.length) {
-            backlogStories[stepName] = chunk.map(task => taskToCard(task, baseUrl));
-        }
-    }
-
-    const slices = [];
-    if (Object.keys(importedStories).length) {
-        slices.push({ name: 'Imported', stories: importedStories });
-    }
-    if (Object.keys(backlogStories).length) {
-        slices.push({ name: 'Backlog', stories: backlogStories });
-    }
-
-    const obj = { name: projectName, id: undefined, site, steps, slices };
-    return obj;
-}
-
-function taskToCard(task, baseUrl) {
-    const card = { name: task.name };
-    const status = PHAB_TO_STORYMAP_STATUS[task.status];
-    if (status) card.status = status;
-    if (task.description) card.body = task.description;
-    if (task.points != null) card.points = task.points;
-    card.url = `${baseUrl}/T${task.id}`;
-    return card;
-}
-
-export async function importCommand(opts) {
-    const source = opts.from === 'phab' ? 'phabricator' : opts.from;
-    if (source !== 'phabricator') {
-        console.error(chalk.red(`Unsupported source: ${source}. Supported: phabricator (or phab)`));
-        process.exit(1);
-    }
-
-    const tag = opts.tag;
-    if (!tag) {
-        console.error(chalk.red('--tag is required'));
-        process.exit(1);
-    }
-
-    const outputPath = resolve(opts.output || 'storymap.yml');
-    const statusList = (opts.status || 'open,in-progress,stalled,resolved').split(',').map(s => s.trim());
-
-    // Validate status names
-    for (const s of statusList) {
-        if (!CLI_TO_PHAB_STATUS[s]) {
-            console.error(chalk.red(`Unknown status: ${s}. Valid: ${Object.keys(CLI_TO_PHAB_STATUS).join(', ')}`));
-            process.exit(1);
-        }
-    }
-
-    const phabStatuses = statusList.map(s => CLI_TO_PHAB_STATUS[s]);
-
-    // Credentials
-    let { url: baseUrl, token } = await getCredentials();
-
-    // Resolve project (retry on auth error)
-    console.log(chalk.dim(`Looking up project "${tag}"...`));
-    let project;
-    try {
-        project = await findProject(baseUrl, token, tag);
-    } catch (err) {
-        if (err.message.includes('ERR-INVALID-AUTH') || err.message.includes('ERR-CONDUIT-CORE')) {
-            console.error(chalk.red(err.message));
-            console.log();
-            const creds = await promptCredentials(baseUrl);
-            baseUrl = creds.url;
-            token = creds.token;
-            try {
-                project = await findProject(baseUrl, token, tag);
-                await writeCredentials('phabricator', creds);
-                console.log(chalk.dim('Credentials saved to ~/.storymaps/credentials.json'));
-            } catch (retryErr) {
-                console.error(chalk.red(retryErr.message));
-                process.exit(1);
-            }
-        } else {
-            console.error(chalk.red(err.message));
-            process.exit(1);
-        }
-    }
-    console.log(`Project: ${chalk.cyan(project.name)}`);
-
-    // Fetch tasks and resolve epic tag
-    console.log(chalk.dim('Fetching tasks...'));
-    let tasks, epicPhid;
-    try {
-        [tasks, epicPhid] = await Promise.all([
-            fetchTasks(baseUrl, token, project.phid, phabStatuses),
-            findEpicTagPhid(baseUrl, token),
-        ]);
-    } catch (err) {
-        console.error(chalk.red(`Failed to fetch tasks: ${err.message}`));
-        process.exit(1);
-    }
-
-    if (!tasks.length) {
-        console.log(chalk.yellow('No tasks found.'));
-        return;
-    }
-
-    // Identify epics by the Epic project tag
-    const epicTasks = epicPhid ? tasks.filter(t => t.projectPhids.includes(epicPhid)) : [];
-    const epicPhids = new Set(epicTasks.map(t => t.phid));
-
-    // Fetch subtasks for epics
-    let edges = [];
-    if (epicTasks.length) {
-        console.log(chalk.dim('Fetching subtasks...'));
-        try {
-            edges = await fetchSubtaskEdges(baseUrl, token, epicTasks.map(t => t.phid));
-        } catch (err) {
-            console.error(chalk.red(`Failed to fetch subtasks: ${err.message}`));
-            process.exit(1);
-        }
-    }
-
-    // Build epic → children map, fetching any subtasks not in the project
-    const taskByPhid = new Map(tasks.map(t => [t.phid, t]));
-    const childPhids = new Set(edges.map(e => e.destinationPHID));
-    const missingPhids = [...childPhids].filter(phid => !taskByPhid.has(phid));
-    if (missingPhids.length) {
-        const missing = await fetchTasksByPhids(baseUrl, token, missingPhids);
-        for (const t of missing) taskByPhid.set(t.phid, t);
-    }
-
-    const epics = epicTasks.map(epic => {
-        const childTaskPhids = edges
-            .filter(e => e.sourcePHID === epic.phid)
-            .map(e => e.destinationPHID);
-        const children = childTaskPhids.map(phid => taskByPhid.get(phid)).filter(Boolean);
-        return { ...epic, children };
-    });
-
-    // Standalone = not an epic, not a child of an epic
-    const standalones = tasks.filter(t => !epicPhids.has(t.phid) && !childPhids.has(t.phid));
-
-    const subtaskCount = epics.reduce((sum, e) => sum + e.children.length, 0);
-    console.log(`  ${epics.length} epics, ${subtaskCount} subtasks`);
-    console.log(`  ${standalones.length} standalone tasks`);
-
-    // Build YAML and register on storymaps server
-    const site = opts.site || 'storymaps.io';
-    const siteBaseUrl = site === 'localhost' ? 'http://localhost:3000' : `https://${site}`;
-    const yamlObj = buildYamlObj(project.name, epics, standalones, baseUrl, site);
-    let yamlString = dumpYaml(yamlObj);
-    try {
-        const { id } = await postMap(siteBaseUrl, yamlString, 'text/yaml');
-        yamlObj.id = id;
-        yamlString = dumpYaml(yamlObj);
-        console.log(chalk.dim(`  Registered on ${site} (id: ${id})`));
-    } catch {
-        console.log(chalk.dim(`  Could not reach ${site} - run "storymaps push" later to register`));
-    }
-
-    // Write
-    if (existsSync(outputPath)) {
-        const overwrite = await confirm({
-            message: `${outputPath} already exists. Overwrite?`,
-            default: false,
-            theme: { prefix: '>' },
-        });
-        if (!overwrite) {
-            console.log('Aborted.');
-            return;
-        }
-    }
-
-    await writeStorymap(outputPath, yamlString);
-    console.log(chalk.green(`Wrote ${outputPath}`));
-    console.log(chalk.dim(`  ${tasks.length} tasks, ${epics.length} epics, ${standalones.length} standalone`));
-}

package/lib/util/phabricator.js

@@ -1,155 +0,0 @@
-// Storymaps CLI — AGPL-3.0 — see LICENCE for details
-// Phabricator Conduit API client
-
-// CLI status name → Phabricator Conduit status value
-export const CLI_TO_PHAB_STATUS = {
-    'open': 'open',
-    'in-progress': 'progress',
-    'stalled': 'stalled',
-    'resolved': 'resolved',
-};
-
-// Phabricator Conduit status value → storymap YAML status
-export const PHAB_TO_STORYMAP_STATUS = {
-    'open': 'planned',
-    'progress': 'in-progress',
-    'stalled': 'blocked',
-    'resolved': 'done',
-};
-
-async function conduit(baseUrl, method, token, params = {}) {
-    const url = `${baseUrl.replace(/\/+$/, '')}/api/${method}`;
-    const args = ['curl', '-s', '-X', 'POST', url, '-d', `api.token=${token}`];
-    for (const [key, value] of Object.entries(params)) {
-        args.push('-d', `${key}=${value}`);
-    }
-    const { execFile } = await import('node:child_process');
-    const { promisify } = await import('node:util');
-    const exec = promisify(execFile);
-    const { stdout } = await exec(args[0], args.slice(1));
-    const json = JSON.parse(stdout);
-    if (json.error_code) {
-        throw new Error(`Conduit ${method}: [${json.error_code}] ${json.error_info}`);
-    }
-    return json.result;
-}
-
-/**
- * Resolve a project slug to its PHID and name.
- */
-export async function findProject(baseUrl, token, slug) {
-    const result = await conduit(baseUrl, 'project.search', token, {
-        'constraints[slugs][0]': slug,
-    });
-    const project = result.data?.[0];
-    if (!project) {
-        throw new Error(`Project not found: ${slug}`);
-    }
-    return { phid: project.phid, name: project.fields.name };
-}
-
-/**
- * Find the PHID of the "Epic" project tag. Returns null if not found.
- */
-export async function findEpicTagPhid(baseUrl, token) {
-    const result = await conduit(baseUrl, 'project.search', token, {
-        'constraints[slugs][0]': 'epic',
-    });
-    return result.data?.[0]?.phid || null;
-}
-
-/**
- * Fetch all tasks in a project matching the given statuses.
- * Handles cursor-based pagination. Calls onPage(tasks, total) per page.
- */
-export async function fetchTasks(baseUrl, token, projectPhid, statuses, { onPage } = {}) {
-    const all = [];
-    let after = null;
-    for (;;) {
-        const params = {
-            'constraints[projects][0]': projectPhid,
-            'attachments[projects]': '1',
-            'order': 'newest',
-        };
-        statuses.forEach((s, i) => {
-            params[`constraints[statuses][${i}]`] = s;
-        });
-        if (after) params['after'] = after;
-
-        const result = await conduit(baseUrl, 'maniphest.search', token, params);
-        const tasks = (result.data || []).map(t => ({
-            id: t.id,
-            phid: t.phid,
-            name: t.fields.name,
-            description: t.fields.description?.raw || '',
-            status: t.fields.status?.value || 'open',
-            points: t.fields.points != null ? Number(t.fields.points) : null,
-            projectPhids: t.attachments?.projects?.projectPHIDs || [],
-        }));
-        all.push(...tasks);
-        if (onPage) onPage(tasks, all.length);
-
-        after = result.cursor?.after;
-        if (!after) break;
-    }
-    return all;
-}
-
-/**
- * Fetch tasks by their PHIDs. Returns the same shape as fetchTasks.
- */
-export async function fetchTasksByPhids(baseUrl, token, phids) {
-    const BATCH = 100;
-    const all = [];
-    for (let i = 0; i < phids.length; i += BATCH) {
-        const batch = phids.slice(i, i + BATCH);
-        const params = {};
-        batch.forEach((phid, j) => {
-            params[`constraints[phids][${j}]`] = phid;
-        });
-        const result = await conduit(baseUrl, 'maniphest.search', token, params);
-        const tasks = (result.data || []).map(t => ({
-            id: t.id,
-            phid: t.phid,
-            name: t.fields.name,
-            description: t.fields.description?.raw || '',
-            status: t.fields.status?.value || 'open',
-            points: t.fields.points != null ? Number(t.fields.points) : null,
-            projectPhids: [],
-        }));
-        all.push(...tasks);
-    }
-    return all;
-}
-
-/**
- * Fetch subtask edges for a set of task PHIDs.
- * Returns [{ sourcePHID, destinationPHID }] where source is parent, destination is child.
- * Handles pagination and batches in chunks of 100.
- */
-export async function fetchSubtaskEdges(baseUrl, token, taskPhids) {
-    const BATCH = 100;
-    const all = [];
-    for (let i = 0; i < taskPhids.length; i += BATCH) {
-        const batch = taskPhids.slice(i, i + BATCH);
-        let after = null;
-        for (;;) {
-            const params = { 'types[0]': 'task.subtask' };
-            batch.forEach((phid, j) => {
-                params[`sourcePHIDs[${j}]`] = phid;
-            });
-            if (after) params['after'] = after;
-
-            const result = await conduit(baseUrl, 'edge.search', token, params);
-            const edges = (result.data || []).map(e => ({
-                sourcePHID: e.sourcePHID,
-                destinationPHID: e.destinationPHID,
-            }));
-            all.push(...edges);
-
-            after = result.cursor?.after;
-            if (!after) break;
-        }
-    }
-    return all;
-}