bmad-kanban 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tthil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# bmad-kanban
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A read-only Kanban board for [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) projects. It runs locally, reads your project's BMAD files, and shows stories as cards in Backlog, Ready, In progress, Review and Done columns, with optional epic swimlanes. It updates live when files change.
+
+It never writes to your project. Remove a project from the sidebar and only the board's own list changes; your folder is not touched.
+
+## Usage
+
+Run it inside a BMAD project:
+
+```sh
+npx bmad-kanban
+```
+
+Or point it at a folder:
+
+```sh
+npx bmad-kanban ~/code/my-project
+```
+
+Options (`bmad-kanban --help`):
+
+- `--port N`: port to listen on (default 4310)
+- `--no-open`: do not open a browser
+- `[path]`: project folder (default: current directory)
+
+If a board is already running, the new project is added to it instead of starting a second server.
+
+Requirements: Node 22 or newer. `uv` is needed for full BMAD v7 fidelity (the board calls v7's own scripts through it). Without `uv` the board falls back to reading the files directly and shows a "reduced fidelity" notice.
+
+The project list is stored in a per-user config directory. Set `BMAD_KANBAN_CONFIG_DIR` to use a different one. Use the × next to a project in the sidebar to remove it from the list.
+
+## Supported layouts
+
+- **v6 sprint**: `sprint-status.yaml` plus story files in the implementation artifacts folder.
+- **v6 spec**: story files with a `status` in their frontmatter.
+- **v7**: initiatives and tickets (`tickets.toml` and story plan files).
+
+A project can have more than one layout (typically mid-migration). Each source gets its own sidebar entry and nothing is merged across them.
+
+## Columns
+
+| Column | v6 sprint | v6 spec (frontmatter) | v7 `status` |
+|---|---|---|---|
+| Backlog | `backlog`, no status | none, `draft`, `backlog` | none, `draft` |
+| Ready | `ready-for-dev` (+ legacy `drafted`) | `ready-for-dev` | `ready-for-dev` |
+| In progress | `in-progress` (+ legacy `contexted`) | `in-progress` | `in-progress`, `blocked` (red marker) |
+| Review | `review` | `review`, `in-review` | `in-review`, `built` |
+| Done | `done` | `done` | `done` |
+| (hidden) | none | none | `dropped`, behind a "show dropped" switch |
+
+An unknown status goes to Backlog with an "unknown status: X" badge.
+
+## Development
+
+```sh
+npm install
+npm test          # unit tests (vitest)
+npm run typecheck
+npm run build     # dist/cli.js and dist/web
+npm run test:e2e  # Playwright smoke test; run the build first
+```
+
+## Acknowledgements
+
+Inspired by [vscode-bmad-kanban](https://github.com/RianKhanafi/vscode-bmad-kanban) by RianKhanafi.
+
+## License
+
+MIT

package/dist/bmad/config.js

@@ -0,0 +1,107 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse as parseToml } from 'smol-toml';
+import { parse as parseYaml } from 'yaml';
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+export function findProjectRoot(start) {
+    let dir = path.resolve(start);
+    for (;;) {
+        try {
+            if (fs.statSync(path.join(dir, '_bmad')).isDirectory())
+                return dir;
+        }
+        catch {
+            // not here, keep walking up
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function readIf(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function deepMerge(a, b) {
+    const out = { ...a };
+    for (const [k, v] of Object.entries(b)) {
+        out[k] = isObj(v) && isObj(out[k]) ? deepMerge(out[k], v) : v;
+    }
+    return out;
+}
+function get(o, ...keys) {
+    let cur = o;
+    for (const k of keys) {
+        if (!isObj(cur) || !Object.hasOwn(cur, k))
+            return undefined;
+        cur = cur[k];
+    }
+    return cur;
+}
+const str = (v) => (typeof v === 'string' && v !== '' ? v : null);
+function readVersion(bmad) {
+    const text = readIf(path.join(bmad, '_config', 'manifest.yaml'));
+    if (text === null)
+        return null;
+    try {
+        const v = get(parseYaml(text), 'installation', 'version');
+        return typeof v === 'string' ? v : typeof v === 'number' ? String(v) : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function loadBmadConfig(root) {
+    const absRoot = path.resolve(root);
+    const bmad = path.join(absRoot, '_bmad');
+    const tomlFiles = ['config.toml', 'config.user.toml', 'custom/config.toml', 'custom/config.user.toml'];
+    let merged = {};
+    let anyToml = false;
+    for (const f of tomlFiles) {
+        const text = readIf(path.join(bmad, f));
+        if (text === null)
+            continue;
+        anyToml = true;
+        merged = deepMerge(merged, parseToml(text));
+    }
+    let outRaw, planRaw, implRaw, initRaw;
+    if (anyToml) {
+        outRaw = get(merged, 'core', 'output_folder');
+        initRaw = get(merged, 'core', 'active_initiative');
+        planRaw = get(merged, 'modules', 'bmm', 'planning_artifacts');
+        implRaw = get(merged, 'modules', 'bmm', 'implementation_artifacts');
+    }
+    else {
+        let y = {};
+        for (const f of ['core/config.yaml', 'bmm/config.yaml']) {
+            const text = readIf(path.join(bmad, f));
+            if (text === null)
+                continue;
+            const parsed = parseYaml(text);
+            if (isObj(parsed))
+                y = deepMerge(y, parsed);
+        }
+        outRaw = y.output_folder;
+        initRaw = y.active_initiative;
+        planRaw = y.planning_artifacts;
+        implRaw = y.implementation_artifacts;
+    }
+    const resolve = (v, fallback) => {
+        const s = str(v);
+        return s === null ? fallback : path.resolve(absRoot, s.split('{project-root}').join(absRoot));
+    };
+    const outputFolder = resolve(outRaw, path.join(absRoot, '_bmad-output'));
+    return {
+        root: absRoot,
+        outputFolder,
+        planningArtifacts: resolve(planRaw, path.join(outputFolder, 'planning-artifacts')),
+        implementationArtifacts: resolve(implRaw, path.join(outputFolder, 'implementation-artifacts')),
+        activeInitiative: str(initRaw),
+        version: readVersion(bmad),
+    };
+}

package/dist/bmad/frontmatter.js

@@ -0,0 +1,26 @@
+import { parse } from 'yaml';
+export class FrontmatterError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FrontmatterError';
+    }
+}
+const FM = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+export function readFrontmatter(text) {
+    const m = FM.exec(text);
+    if (!m)
+        return { data: {}, body: text };
+    let parsed;
+    try {
+        parsed = parse(m[1]);
+    }
+    catch (e) {
+        throw new FrontmatterError(`Invalid YAML frontmatter: ${e.message}`);
+    }
+    if (parsed == null)
+        parsed = {};
+    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new FrontmatterError('Frontmatter must be a YAML mapping');
+    }
+    return { data: parsed, body: text.slice(m[0].length) };
+}

package/dist/cli.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import openBrowser from 'open';
+import { findProjectRoot } from './bmad/config.js';
+import { findRunning, removeLock, writeLock } from './instance.js';
+import { configDir, Registry } from './registry.js';
+import { startServer } from './server/app.js';
+const defaultDeps = {
+    open: (url) => openBrowser(url),
+    startServer,
+    stdout: (s) => void process.stdout.write(s),
+    stderr: (s) => void process.stderr.write(s),
+};
+const HELP = `Usage: bmad-kanban [path] [--port N] [--no-open]
+
+Read-only Kanban board for BMAD Method projects.
+
+  path         project folder (default: current directory)
+  --port N     port to listen on (default: 4310)
+  --no-open    do not open a browser
+  --help       show this help
+  --version    show the version
+`;
+function version() {
+    const pkg = new URL('../package.json', import.meta.url);
+    return JSON.parse(fs.readFileSync(pkg, 'utf8')).version;
+}
+export async function main(argv, deps = {}) {
+    const d = { ...defaultDeps, ...deps };
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                port: { type: 'string' },
+                'no-open': { type: 'boolean' },
+                help: { type: 'boolean' },
+                version: { type: 'boolean' },
+            },
+        });
+    }
+    catch (e) {
+        d.stderr(`${e.message}\n${HELP}`);
+        return 1;
+    }
+    const { values, positionals } = parsed;
+    if (values.help)
+        return d.stdout(HELP), 0;
+    if (values.version)
+        return d.stdout(`${version()}\n`), 0;
+    const wanted = values.port === undefined ? 4310 : Number(values.port);
+    if (!Number.isInteger(wanted) || wanted < 0 || wanted > 65535) {
+        d.stderr(`Invalid port: ${values.port}\n`);
+        return 1;
+    }
+    if (positionals.length > 1) {
+        d.stderr(`Expected at most one path argument\n${HELP}`);
+        return 1;
+    }
+    const given = path.resolve(positionals[0] ?? process.cwd());
+    const root = findProjectRoot(given);
+    if (positionals[0] !== undefined && !root) {
+        d.stderr(`Not a BMAD project: ${given}\n`);
+        return 1;
+    }
+    const lockFile = path.join(configDir(), 'server.json');
+    let port = await findRunning(lockFile);
+    const reuse = port !== null;
+    if (port === null) {
+        const webRoot = fileURLToPath(new URL('./web/', import.meta.url));
+        const server = await d.startServer({ registry: new Registry(), port: wanted, webRoot });
+        port = server.port;
+        writeLock(lockFile, { port, pid: process.pid });
+        const cleanup = () => removeLock(lockFile, process.pid);
+        process.once('exit', cleanup);
+        for (const sig of ['SIGINT', 'SIGTERM']) {
+            process.once(sig, () => {
+                cleanup();
+                void server.close().finally(() => process.exit(0));
+            });
+        }
+    }
+    const base = `http://127.0.0.1:${port}/`;
+    let url = base;
+    let name = '';
+    if (root) {
+        const res = await fetch(`${base}api/projects`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ path: root }),
+        });
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok || !body.id) {
+            d.stderr(`Could not add project: ${body.error ?? res.statusText}\n`);
+            return 1;
+        }
+        url = `${base}?project=${body.id}`;
+        name = body.name ?? path.basename(root);
+    }
+    if (!values['no-open'])
+        await d.open(url);
+    if (reuse) {
+        d.stdout(`Opened ${name ? `${name} in` : ''}${name ? ' ' : ''}the running board at ${url}\n`);
+    }
+    else {
+        d.stdout(`BMAD Kanban running at ${base}\n`);
+    }
+    return 0;
+}
+const self = process.argv[1] ? fs.realpathSync(process.argv[1]) : '';
+if (self === fileURLToPath(import.meta.url)) {
+    main(process.argv.slice(2)).then((code) => {
+        if (code !== 0)
+            process.exit(code);
+    }, (e) => {
+        process.stderr.write(`${e.message}\n`);
+        process.exit(1);
+    });
+}

package/dist/instance.js

@@ -0,0 +1,63 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export function readLock(file) {
+    try {
+        const v = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (Number.isInteger(v?.port) && Number.isInteger(v?.pid))
+            return { port: v.port, pid: v.pid };
+    }
+    catch {
+        // missing or corrupt
+    }
+    return null;
+}
+export function writeLock(file, lock) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(lock));
+    fs.renameSync(tmp, file);
+}
+/** Remove the lock only if it still belongs to `pid`. */
+export function removeLock(file, pid) {
+    if (readLock(file)?.pid !== pid)
+        return;
+    try {
+        fs.rmSync(file, { force: true });
+    }
+    catch {
+        // best effort
+    }
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+async function answers(port) {
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/api/state`, { signal: AbortSignal.timeout(1000) });
+        await res.arrayBuffer();
+        return res.status === 200;
+    }
+    catch {
+        return false;
+    }
+}
+export async function findRunning(file) {
+    const lock = readLock(file);
+    if (!lock)
+        return null;
+    if (pidAlive(lock.pid) && (await answers(lock.port)))
+        return lock.port;
+    try {
+        fs.rmSync(file, { force: true });
+    }
+    catch {
+        // best effort
+    }
+    return null;
+}

package/dist/model.js

@@ -0,0 +1 @@
+export {};

package/dist/readers/detect.js

@@ -0,0 +1,204 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse as parseToml } from 'smol-toml';
+import { loadBmadConfig } from '../bmad/config.js';
+import { detectV6Sprint, readV6Sprint, v6SprintDetailPath } from './v6Sprint.js';
+import { findSpecFolders, readV6Spec, v6SpecDetailPath } from './v6Spec.js';
+import { listV7Folders, v7DetailPath, v7EntryText } from './v7Tree.js';
+import { readV7 } from './v7Script.js';
+export class UnknownSourceError extends Error {
+    constructor(sourceId) {
+        super(`Unknown source: ${sourceId}`);
+        this.name = 'UnknownSourceError';
+    }
+}
+export class UnknownStoryError extends Error {
+    constructor(storyKey) {
+        super(`Unknown story: ${storyKey}`);
+        this.name = 'UnknownStoryError';
+    }
+}
+const message = (e) => (e instanceof Error ? e.message : String(e));
+/** Child initiative slugs named by a parent's tickets.toml `[[initiative]]` tables. */
+function childSlugs(folder) {
+    try {
+        const doc = parseToml(fs.readFileSync(path.join(folder, 'tickets', 'tickets.toml'), 'utf8'));
+        const rows = Array.isArray(doc.initiative) ? doc.initiative : [];
+        return rows.flatMap((r) => (typeof r === 'object' && r !== null && typeof r.slug === 'string' ? [r.slug] : []));
+    }
+    catch {
+        return [];
+    }
+}
+function v7Kind(kind) {
+    return kind === 'parent' ? 'v7-parent' : kind === 'backlog' ? 'v7-backlog' : 'v7-initiative';
+}
+function v7Target(f) {
+    return f.kind === 'backlog'
+        ? { type: 'v7', id: 'v7-backlog', label: 'Backlog', path: f.path, folderKind: f.kind }
+        : { type: 'v7', id: `v7:${f.name}`, label: f.name, path: f.path, folderKind: f.kind };
+}
+function kindOf(t) {
+    return t.type === 'v7' ? v7Kind(t.folderKind) : t.type;
+}
+const liveCount = (b) => b.stories.filter((s) => s.column !== 'dropped').length;
+function resolveTarget(cfg, sourceId) {
+    if (sourceId === 'v6-sprint') {
+        return detectV6Sprint(cfg) ? { type: 'v6-sprint', id: sourceId, label: 'v6 sprint', path: cfg.implementationArtifacts } : null;
+    }
+    if (sourceId.startsWith('v6-spec:')) {
+        const name = sourceId.slice('v6-spec:'.length);
+        const folder = findSpecFolders(cfg).find((f) => path.basename(f) === name);
+        return folder === undefined ? null : { type: 'v6-spec', id: sourceId, label: name, path: folder };
+    }
+    const v7 = listV7Folders(cfg);
+    if (sourceId === 'v7-backlog') {
+        const f = v7.find((x) => x.kind === 'backlog');
+        return f === undefined ? null : v7Target(f);
+    }
+    if (sourceId.startsWith('v7:')) {
+        const name = sourceId.slice(3);
+        const f = v7.find((x) => x.kind !== 'backlog' && x.name === name);
+        return f === undefined ? null : v7Target(f);
+    }
+    return null;
+}
+async function loadBoard(cfg, t) {
+    if (t.type === 'v6-sprint')
+        return readV6Sprint(cfg, t.id);
+    if (t.type === 'v6-spec')
+        return readV6Spec(t.path, t.id);
+    return readV7(cfg, t.path, t.folderKind, t.id);
+}
+function refFor(t, board) {
+    const ref = {
+        id: t.id,
+        kind: kindOf(t),
+        label: t.type === 'v6-spec' && board !== null ? board.label : t.label,
+        path: t.path,
+        count: 0,
+    };
+    if (board === null)
+        return ref;
+    if (board.children !== undefined) {
+        ref.children = board.children.map((c) => ({
+            id: c.sourceId,
+            kind: c.kind,
+            label: c.label,
+            path: path.join(path.dirname(t.path), c.sourceId.slice(3)),
+            count: liveCount(c),
+        }));
+        ref.count = ref.children.reduce((n, c) => n + c.count, 0);
+    }
+    else {
+        ref.count = liveCount(board);
+    }
+    return ref;
+}
+async function refOf(cfg, t) {
+    try {
+        return refFor(t, await loadBoard(cfg, t));
+    }
+    catch {
+        return refFor(t, null);
+    }
+}
+export async function listSources(root) {
+    let cfg;
+    try {
+        cfg = loadBmadConfig(root);
+    }
+    catch (e) {
+        return { sources: [], defaultSourceId: null, tags: [], version: null, error: message(e) };
+    }
+    const targets = [];
+    if (detectV6Sprint(cfg))
+        targets.push(resolveTarget(cfg, 'v6-sprint'));
+    for (const f of findSpecFolders(cfg)) {
+        targets.push({ type: 'v6-spec', id: `v6-spec:${path.basename(f)}`, label: path.basename(f), path: f });
+    }
+    const folders = listV7Folders(cfg);
+    const children = new Set(folders.filter((f) => f.kind === 'parent').flatMap((f) => childSlugs(f.path)));
+    for (const f of folders) {
+        if (f.kind !== 'backlog' && f.kind !== 'parent' && children.has(f.name))
+            continue;
+        targets.push(v7Target(f));
+    }
+    const sources = await Promise.all(targets.map((t) => refOf(cfg, t)));
+    const flat = sources.flatMap((s) => [s, ...(s.children ?? [])]);
+    const active = cfg.activeInitiative === null ? undefined : flat.find((s) => s.id === `v7:${cfg.activeInitiative}`);
+    const tags = [];
+    if (sources.some((s) => s.kind.startsWith('v6')))
+        tags.push('v6');
+    if (sources.some((s) => s.kind.startsWith('v7')))
+        tags.push('v7');
+    return { sources, defaultSourceId: active?.id ?? sources[0]?.id ?? null, tags, version: cfg.version };
+}
+export async function readBoard(root, sourceId) {
+    let cfg;
+    try {
+        cfg = loadBmadConfig(root);
+    }
+    catch {
+        throw new UnknownSourceError(sourceId);
+    }
+    const t = resolveTarget(cfg, sourceId);
+    if (t === null)
+        throw new UnknownSourceError(sourceId);
+    try {
+        return await loadBoard(cfg, t);
+    }
+    catch (e) {
+        return {
+            sourceId,
+            kind: kindOf(t),
+            label: t.label,
+            epics: [],
+            stories: [],
+            notices: [{ level: 'error', text: `Could not read this board: ${message(e)}` }],
+        };
+    }
+}
+function inside(root, file) {
+    try {
+        const base = fs.realpathSync(root);
+        const real = fs.realpathSync(file);
+        return real === base || real.startsWith(base + path.sep);
+    }
+    catch {
+        return false;
+    }
+}
+export async function getStoryDetail(root, sourceId, storyKey) {
+    let cfg;
+    try {
+        cfg = loadBmadConfig(root);
+    }
+    catch {
+        throw new UnknownSourceError(sourceId);
+    }
+    const t = resolveTarget(cfg, sourceId);
+    if (t === null)
+        throw new UnknownSourceError(sourceId);
+    const file = t.type === 'v6-sprint'
+        ? v6SprintDetailPath(cfg, storyKey)
+        : t.type === 'v6-spec'
+            ? v6SpecDetailPath(t.path, storyKey)
+            : v7DetailPath(t.path, storyKey);
+    if (file === null) {
+        if (t.type === 'v7') {
+            const text = v7EntryText(t.path, storyKey);
+            if (text === null)
+                throw new UnknownStoryError(storyKey);
+            return { path: null, markdown: text };
+        }
+        // a story on the board whose file hasn't been written yet is not an error
+        const board = await loadBoard(cfg, t);
+        if (!board.stories.some((s) => s.key === storyKey))
+            throw new UnknownStoryError(storyKey);
+        return { path: null, markdown: '' };
+    }
+    if (!inside(cfg.root, file))
+        throw new UnknownStoryError(storyKey);
+    return { path: file, markdown: fs.readFileSync(file, 'utf8') };
+}