backlog.md 0.1.0

package/cli/index.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("./cli.js");

package/docs/npm-publishing.md

@@ -0,0 +1,69 @@
+# NPM Publishing Setup
+
+This guide explains how to set up npm publishing for the Backlog.md project.
+
+## Prerequisites
+
+1. An npm account with publish permissions for the `@backlog.md` package
+2. Repository admin access to configure GitHub secrets
+
+## Setting up the NPM Token
+
+### 1. Generate an npm Access Token
+
+1. Log in to [npmjs.com](https://www.npmjs.com)
+2. Click on your profile picture → Access Tokens
+3. Click "Generate New Token"
+4. Choose "Automation" token type (recommended for CI/CD)
+5. Name it something like "backlog-md-github-actions"
+6. Copy the generated token (it starts with `npm_`)
+
+### 2. Add the Token to GitHub Secrets
+
+1. Go to the GitHub repository settings
+2. Navigate to Settings → Secrets and variables → Actions
+3. Click "New repository secret"
+4. Name: `NPM_TOKEN`
+5. Value: Paste your npm token
+6. Click "Add secret"
+
+## How Publishing Works
+
+The GitHub Actions workflow (`/.github/workflows/ci.yml`) automatically publishes to npm when:
+
+1. A new git tag is pushed that matches the pattern `v*.*.*` (e.g., `v1.0.0`)
+2. The build and tests pass successfully
+
+The workflow:
+- Uses `actions/setup-node@v4` to configure npm authentication
+- Sets the registry URL to `https://registry.npmjs.org`
+- Uses the `NPM_TOKEN` secret for authentication
+- Runs `npm publish --access public` to publish the package
+
+## Troubleshooting
+
+### Error: ENEEDAUTH
+
+If you see this error, it means the `NPM_TOKEN` secret is either:
+- Not configured in GitHub
+- Invalid or expired
+- Missing the required publish permissions
+
+### Error: 403 Forbidden
+
+This usually means:
+- The token doesn't have permission to publish to the package
+- The package name is already taken by another user
+- You're not listed as a maintainer of the package
+
+## Manual Publishing (Not Recommended)
+
+If you need to publish manually:
+
+```bash
+npm login
+bun run build
+npm publish --access public
+```
+
+Always prefer using the automated workflow to ensure consistency.

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "backlog.md",
+	"version": "0.1.0",
+	"module": "src/index.ts",
+	"type": "module",
+	"bin": {
+		"backlog": "cli/index.js"
+	},
+	"dependencies": {
+		"commander": "14.0.0",
+		"gray-matter": "4.0.3",
+		"blessed": "0.1.81"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "1.9.4",
+		"@types/bun": "1.2.15",
+		"husky": "9.1.7",
+		"lint-staged": "16.1.0"
+	},
+	"scripts": {
+		"test": "bun test",
+		"format": "biome format --write .",
+		"lint": "biome lint --write .",
+		"check": "biome check .",
+		"prepare": "husky",
+		"build": "node scripts/build.js",
+		"build:js": "bun build src/cli.ts --outdir cli --target node",
+		"build:exe": "bun build src/cli.ts --compile --outfile cli/backlog",
+		"cli": "bun src/cli.ts"
+	},
+	"lint-staged": {
+		"*.{ts,js,json}": ["biome check --write --files-ignore-unknown=true"],
+		"src/**/*.{ts,js}": ["biome check --write --files-ignore-unknown=true"]
+	},
+	"author": "Alex Gavrilescu (https://github.com/MrLesk)",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/MrLesk/Backlog.md.git"
+	},
+	"bugs": {
+		"url": "https://github.com/MrLesk/Backlog.md/issues"
+	},
+	"homepage": "https://backlog.md",
+	"keywords": ["cli", "markdown", "kanban", "task", "project-management", "backlog", "agents"],
+	"license": "MIT",
+	"trustedDependencies": ["@biomejs/biome"]
+}

package/readme.md

@@ -0,0 +1,97 @@
+<h1 align="center">Backlog.md</h1>
+<p align="center">✏️ Markdown‑native Task Manager &amp; Kanban visualizer for any Git repository</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/backlog.md">
+    <img src="https://badgen.net/npm/v/backlog.md?icon=npm&label=npm">
+  </a>
+  <a href="https://bun.sh">
+    <img src="https://badgen.net/badge/bun/add%20backlog.md/black?icon=bun">
+  </a>
+  <a href="LICENSE"><img src="https://badgen.net/github/license/your-org/backlog.md"></a>
+</p>
+
+---
+
+> **Backlog.md** turns any folder with a Git repo into a **self‑contained project board**  
+> powered by plain Markdown files and a zero‑config CLI.
+
+* 100 % offline‑friendly – your backlog lives *inside* your repository  
+* Works on **macOS, Linux and Windows** (Node ≥ 18 / Bun ≥ 1.0)  
+* Completely free & open‑source (MIT)
+
+---
+
+### Quick install
+
+```bash
+# global – Node
+npm i -g backlog.md
+
+# global – Bun
+bun add -g backlog.md
+```
+
+> Prefer per‑project installs? `npm i -D backlog.md` → `npx backlog …`
+
+---
+
+### Five‑minute tour
+
+```bash
+# 1. Bootstrap a repo + backlog
+backlog init hello-world
+
+# 2. Capture work
+backlog task create "Render markdown as kanban"
+
+# 3. See where you stand
+backlog board view
+```
+
+All data is saved under `.backlog` folder as human‑readable Markdown (`task‑12 - Fix typo.md`).
+
+---
+
+## CLI reference (essentials)
+
+| Action      | Example                                              |
+|-------------|------------------------------------------------------|
+| Create task | `backlog task create "Add OAuth"`                    |
+| Create sub task | `backlog task create --parent 14 "Add Google auth"`|
+| List tasks  | `backlog task list [-s <status>] [-a <assignee>`     |
+| View detail | `backlog task 7`                                     |
+| Edit        | `backlog task edit 7 -a @sara -l auth,backend`       |
+| Archive     | `backlog task archive 7`                             |
+| Draft flow  | `backlog draft create "Spike GraphQL"` → `backlog draft promote 3.1` |
+| Demote to draft| `backlog task demote <id>` |
+| Kanban      | `backlog board view`            |
+
+Full help: `backlog --help`
+
+---
+
+## Configuration
+
+Backlog.md merges the following layers (highest → lowest):
+
+1. CLI flags  
+2. `.backlog/config.yml` (per‑project)  
+3. `~/.backlog/user` (per‑user)  
+4. Built‑ins  
+
+Key options:
+
+| Key               | Purpose            | Default                       |
+|-------------------|--------------------|-------------------------------|
+| `default_assignee`| Pre‑fill assignee  | `[]`                          |
+| `default_status`  | First column       | `To Do`                       |
+| `statuses`        | Board columns      | `[To Do, In Progress, Done]`  |
+| `date_format`     | ISO or locale      | `yyyy-mm-dd`                  |
+
+---
+
+
+## License
+
+Backlog.md is released under the **MIT License** – do anything, just give credit. See [LICENSE](LICENSE).

package/scripts/build.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import { chmod, mkdir, writeFile } from "node:fs/promises";
+import { platform } from "node:os";
+import { dirname, join } from "node:path";
+
+const isWindows = platform() === "win32";
+const outDir = "cli";
+const indexFile = join(outDir, "index.js");
+const executableName = isWindows ? "backlog.exe" : "backlog";
+const executablePath = join(outDir, executableName);
+
+async function runCommand(command, args) {
+	return new Promise((resolve, reject) => {
+		const child = spawn(command, args, {
+			stdio: "inherit",
+			shell: isWindows,
+		});
+
+		child.on("close", (code) => {
+			if (code === 0) {
+				resolve();
+			} else {
+				reject(new Error(`Command failed with exit code ${code}`));
+			}
+		});
+
+		child.on("error", reject);
+	});
+}
+
+async function build() {
+	try {
+		console.log("Building CLI...");
+
+		// Ensure output directory exists
+		await mkdir(dirname(indexFile), { recursive: true });
+
+		// Build JavaScript bundle
+		console.log("Building JavaScript bundle...");
+		await runCommand("bun", ["build", "src/cli.ts", "--outdir", outDir, "--target", "node"]);
+
+		// Create index.js wrapper
+		console.log("Creating index.js wrapper...");
+		const indexContent = isWindows ? 'import("./cli.js");' : '#!/usr/bin/env node\nimport("./cli.js");';
+
+		await writeFile(indexFile, indexContent);
+
+		// Make executable on Unix systems
+		if (!isWindows) {
+			await chmod(indexFile, "755");
+		}
+
+		// Build compiled executable
+		console.log("Building compiled executable...");
+		await runCommand("bun", ["build", "src/cli.ts", "--compile", "--outfile", executablePath]);
+
+		// Make executable on Unix systems
+		if (!isWindows) {
+			await chmod(executablePath, "755");
+		}
+
+		console.log("Build completed successfully!");
+		console.log(`Executable: ${executablePath}`);
+		console.log(`JS Bundle: ${indexFile}`);
+	} catch (error) {
+		console.error("Build failed:", error.message);
+		process.exit(1);
+	}
+}
+
+build();

package/src/agent-instructions.ts

@@ -0,0 +1,54 @@
+import { dirname, isAbsolute, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { AGENT_GUIDELINES, CLAUDE_GUIDELINES, CURSOR_GUIDELINES, README_GUIDELINES } from "./constants/index.ts";
+import type { GitOperations } from "./git/operations.ts";
+
+export type AgentInstructionFile = "AGENTS.md" | "CLAUDE.md" | ".cursorrules" | "readme.md";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+async function loadContent(textOrPath: string): Promise<string> {
+	if (textOrPath.includes("\n")) return textOrPath;
+	try {
+		const path = isAbsolute(textOrPath) ? textOrPath : join(__dirname, textOrPath);
+		return await Bun.file(path).text();
+	} catch {
+		return textOrPath;
+	}
+}
+
+export async function addAgentInstructions(
+	projectRoot: string,
+	git?: GitOperations,
+	files: AgentInstructionFile[] = ["AGENTS.md", "CLAUDE.md", ".cursorrules"],
+): Promise<void> {
+	const mapping: Record<AgentInstructionFile, string> = {
+		"AGENTS.md": AGENT_GUIDELINES,
+		"CLAUDE.md": CLAUDE_GUIDELINES,
+		".cursorrules": CURSOR_GUIDELINES,
+		"readme.md": README_GUIDELINES,
+	};
+
+	const paths: string[] = [];
+	for (const name of files) {
+		const content = await loadContent(mapping[name]);
+		const filePath = join(projectRoot, name);
+		let existing = "";
+		try {
+			existing = await Bun.file(filePath).text();
+			if (!existing.endsWith("\n")) existing += "\n";
+			existing += content;
+		} catch {
+			existing = content;
+		}
+		await Bun.write(filePath, existing);
+		paths.push(filePath);
+	}
+
+	if (git && paths.length > 0) {
+		await git.addFiles(paths);
+		await git.commitChanges("Add AI agent instructions");
+	}
+}
+
+export { loadContent as _loadAgentGuideline };

package/src/board.ts

@@ -0,0 +1,263 @@
+export interface BoardOptions {
+	statuses?: string[];
+}
+
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import type { Task } from "./types/index.ts";
+
+export type BoardLayout = "horizontal" | "vertical";
+export type BoardFormat = "terminal" | "markdown";
+
+interface DisplayTask {
+	id: string;
+	title: string;
+}
+
+export function idSegments(id: string): number[] {
+	const normalized = id.startsWith("task-") ? id.slice(5) : id;
+	return normalized.split(".").map((part) => Number.parseInt(part, 10));
+}
+
+export function compareIds(a: Task, b: Task): number {
+	const segA = idSegments(a.id);
+	const segB = idSegments(b.id);
+	const len = Math.max(segA.length, segB.length);
+	for (let i = 0; i < len; i++) {
+		const diff = (segA[i] ?? 0) - (segB[i] ?? 0);
+		if (diff !== 0) return diff;
+	}
+	return 0;
+}
+
+function wrapText(text: string, maxWidth: number): string[] {
+	if (text.length <= maxWidth) return [text];
+
+	const words = text.split(" ");
+	const lines: string[] = [];
+	let currentLine = "";
+
+	for (const word of words) {
+		if (currentLine.length + word.length + 1 <= maxWidth) {
+			currentLine += (currentLine ? " " : "") + word;
+		} else {
+			if (currentLine) lines.push(currentLine);
+			currentLine = word;
+		}
+	}
+
+	if (currentLine) lines.push(currentLine);
+	return lines;
+}
+
+export function generateKanbanBoard(
+	tasks: Task[],
+	statuses: string[] = [],
+	layout: BoardLayout = "horizontal",
+	maxColumnWidth = 20,
+	format: BoardFormat = "terminal",
+): string {
+	const groups = new Map<string, Task[]>();
+	for (const task of tasks) {
+		const status = task.status || "";
+		const list = groups.get(status) || [];
+		list.push(task);
+		groups.set(status, list);
+	}
+
+	// Map for quick lookup by id
+	const byId = new Map<string, Task>(tasks.map((t) => [t.id, t]));
+
+	// Only show statuses that have tasks (filter out empty groups)
+	const ordered =
+		tasks.length > 0
+			? [
+					...statuses.filter((s) => groups.has(s) && (groups.get(s)?.length ?? 0) > 0),
+					...Array.from(groups.keys()).filter((s) => !statuses.includes(s) && (groups.get(s)?.length ?? 0) > 0),
+				]
+			: [];
+
+	const columns: DisplayTask[][] = ordered.map((status) => {
+		const items = groups.get(status) || [];
+		const top: Task[] = [];
+		const children = new Map<string, Task[]>();
+
+		// Use compareIds for sorting instead of localeCompare
+		for (const t of items.sort(compareIds)) {
+			const parent = t.parentTaskId ? byId.get(t.parentTaskId) : undefined;
+			if (parent && parent.status === t.status) {
+				const list = children.get(parent.id) || [];
+				list.push(t);
+				children.set(parent.id, list);
+			} else {
+				top.push(t);
+			}
+		}
+
+		const result: DisplayTask[] = [];
+		for (const t of top) {
+			result.push({ id: t.id, title: t.title });
+			const subs = children.get(t.id) || [];
+			subs.sort(compareIds);
+
+			for (const [subIdx, s] of subs.entries()) {
+				const isLastSub = subIdx === subs.length - 1;
+				const prefix = isLastSub ? "  └─" : "  |—";
+				result.push({ id: `${prefix} ${s.id}`, title: `     ${s.title}` });
+			}
+		}
+
+		return result;
+	});
+
+	if (layout === "vertical") {
+		const rows: string[] = [];
+		for (const [idx, status] of ordered.entries()) {
+			const header = status || "No Status";
+			rows.push(header);
+			rows.push("-".repeat(header.length));
+			const tasksInStatus = columns[idx];
+			for (const task of tasksInStatus) {
+				rows.push(task.id);
+				rows.push(task.title);
+				rows.push("");
+			}
+			if (tasksInStatus.length === 0) {
+				rows.push("");
+			}
+		}
+		return rows.join("\n").trimEnd();
+	}
+
+	// Return empty string if no columns to show
+	if (ordered.length === 0) {
+		return "";
+	}
+
+	const colWidths = ordered.map((status, idx) => {
+		const header = status || "No Status";
+		let width = Math.min(Math.max(header.length, 8), maxColumnWidth); // Minimum 8, max maxColumnWidth
+		for (const t of columns[idx]) {
+			// Check both task ID and title lengths separately
+			const idLength = t.id.length;
+			const titleLength = t.title.length;
+			const maxTaskWidth = Math.max(idLength, titleLength);
+			if (maxTaskWidth > width && width < maxColumnWidth) {
+				width = Math.min(maxTaskWidth, maxColumnWidth);
+			}
+		}
+		return width;
+	});
+
+	// For markdown format, we need simpler output without text wrapping
+	if (format === "markdown") {
+		const headerRow = `| ${ordered.map((status) => status || "No Status").join(" | ")} |`;
+		const separatorRow = `| ${ordered.map(() => "---").join(" | ")} |`;
+
+		const maxTasks = Math.max(...columns.map((c) => c.length), 0);
+		const rows = [headerRow, separatorRow];
+
+		for (let taskIdx = 0; taskIdx < maxTasks; taskIdx++) {
+			const row = ordered.map((_, cIdx) => {
+				const task = columns[cIdx][taskIdx];
+				if (!task) return "";
+				// For markdown, combine ID and title in one cell
+				return `${task.id}: ${task.title}`;
+			});
+			rows.push(`| ${row.join(" | ")} |`);
+		}
+
+		return rows.join("\n");
+	}
+
+	// Terminal format with text wrapping
+	const pad = (text: string, width: number): string => text.padEnd(width, " ");
+
+	const headerRow = ordered.map((status, i) => pad(status || "No Status", colWidths[i])).join(" | ");
+	const separatorRow = ordered.map((_, i) => "-".repeat(colWidths[i])).join("-|-");
+
+	// Prepare wrapped tasks for each column
+	const wrappedTasks = ordered.map((_, cIdx) => {
+		return columns[cIdx].map((task) => ({
+			idLines: wrapText(task.id, colWidths[cIdx]),
+			titleLines: wrapText(task.title, colWidths[cIdx]),
+		}));
+	});
+
+	const maxTasks = Math.max(...columns.map((c) => c.length), 0);
+	const rows = [headerRow, separatorRow];
+
+	for (let taskIdx = 0; taskIdx < maxTasks; taskIdx++) {
+		// Get the maximum number of lines needed for this task across all columns
+		let maxTaskLines = 0;
+		for (let cIdx = 0; cIdx < ordered.length; cIdx++) {
+			if (wrappedTasks[cIdx][taskIdx]) {
+				const taskLines = wrappedTasks[cIdx][taskIdx].idLines.length + wrappedTasks[cIdx][taskIdx].titleLines.length;
+				maxTaskLines = Math.max(maxTaskLines, taskLines);
+			}
+		}
+
+		// Render each line for this task
+		for (let lineIdx = 0; lineIdx < maxTaskLines; lineIdx++) {
+			const lineRow = ordered
+				.map((_, cIdx) => {
+					const wrappedTask = wrappedTasks[cIdx][taskIdx];
+					if (!wrappedTask) return pad("", colWidths[cIdx]);
+
+					const idLineCount = wrappedTask.idLines.length;
+					let text = "";
+
+					if (lineIdx < idLineCount) {
+						// Show ID lines first
+						text = wrappedTask.idLines[lineIdx];
+					} else {
+						// Then show title lines
+						const titleLineIdx = lineIdx - idLineCount;
+						if (titleLineIdx < wrappedTask.titleLines.length) {
+							text = wrappedTask.titleLines[titleLineIdx];
+						}
+					}
+
+					return pad(text, colWidths[cIdx]);
+				})
+				.join(" | ");
+			rows.push(lineRow);
+		}
+
+		// Add empty row between tasks for better separation (except after last task)
+		// Skip empty row if next task is a subtask (to keep parent and child together)
+		if (taskIdx < maxTasks - 1) {
+			const emptyRow = ordered.map((_, cIdx) => pad("", colWidths[cIdx])).join(" | ");
+			rows.push(emptyRow);
+		}
+	}
+
+	return rows.join("\n");
+}
+
+export async function exportKanbanBoardToFile(
+	tasks: Task[],
+	statuses: string[],
+	filePath: string,
+	maxColumnWidth = 20,
+	addTitle = false,
+): Promise<void> {
+	const board = generateKanbanBoard(tasks, statuses, "horizontal", maxColumnWidth, "markdown");
+
+	let existing = "";
+	try {
+		existing = await Bun.file(filePath).text();
+	} catch {
+		await mkdir(dirname(filePath), { recursive: true });
+	}
+
+	// Add proper spacing and title for readme export
+	let boardContent = board;
+	if (addTitle && filePath.toLowerCase().includes("readme")) {
+		boardContent = `\n\n## Project Board\n\n${board}`;
+	}
+
+	const needsNewline = existing && !existing.endsWith("\n");
+	const content = `${existing}${needsNewline ? "\n" : ""}${boardContent}\n`;
+	await Bun.write(filePath, content);
+}