storymaps 1.0.0 → 1.1.0

package/README.md

@@ -143,10 +143,24 @@ storymaps validate storymap.yml
 ### `convert`
 
 ```bash
-storymaps convert storymap.yml --to json 
+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
+```
+
+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
 
 ```yaml

package/bin/storymaps.js

@@ -13,6 +13,7 @@ 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();
 
@@ -97,6 +98,16 @@ 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.'
         : err.message || String(err);

package/lib/commands/import.js

@@ -0,0 +1,249 @@
+// 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/commands/open.js

@@ -12,7 +12,7 @@ export async function openCommand(target, opts) {
     try {
         ({ id, baseUrl } = await resolveTarget(target, filePath));
     } catch {
-        console.error(chalk.red('No map ID found. Run "storymaps new" first to reserve an ID, or pass one directly: storymaps open <id>'));
+        console.error(chalk.red('No map ID found. Run "storymaps push" to create it on the server, or pass one directly: storymaps open <id>'));
         process.exitCode = 1;
         return;
     }

package/lib/core/yaml.js

@@ -174,8 +174,15 @@ export function jsonToYamlObj(data) {
         if (stepTypes[i] === 'spacer') return 'spacer';
         if (stepTypes[i] === 'partial') return { partial: partialSlugMap[step.partialMapId] };
         const name = resolvedNames[i];
-        if (step.color && step.color !== DEFAULT_STEP_COLOR) return { name, color: step.color };
-        return name;
+        const hasExtra = (step.color && step.color !== DEFAULT_STEP_COLOR)
+            || step.url || step.body || step.points != null;
+        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.points != null) obj.points = step.points;
+        return obj;
     });
 
     // Legend
@@ -321,7 +328,13 @@ export function yamlObjToJson(obj) {
         const displayName = rawName.replace(/:\[\d+\]\s*/, ': ').replace(/\[\d+\]$/, '');
         const color = typeof step === 'string' ? DEFAULT_STEP_COLOR : (step.color || DEFAULT_STEP_COLOR);
         stepNameToIndex[rawName] = jsonSteps.length;
-        jsonSteps.push({ name: displayName, color });
+        const s = { name: displayName, color };
+        if (typeof step === 'object' && step !== null) {
+            if (step.url) s.url = step.url;
+            if (step.body) s.body = step.body;
+            if (step.points != null) s.points = step.points;
+        }
+        jsonSteps.push(s);
     });
 
     const n = jsonSteps.length;

package/lib/util/file.js

@@ -7,7 +7,9 @@ import { dirname, basename, join, extname } from 'node:path';
 import jsyaml from 'js-yaml';
 import { exportToYaml } from '../core/yaml.js';
 
-const CACHE_DIR = join(homedir(), '.storymaps', 'caches');
+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`);
@@ -31,6 +33,25 @@ 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();
     if (ext === '.json') return 'json';

package/lib/util/phabricator.js

@@ -0,0 +1,155 @@
+// 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;
+}

package/package.json

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