forge-workflow 0.0.9 → 0.1.0-beta.2

package/lib/smart-status/scoring.js

@@ -0,0 +1,191 @@
+'use strict';
+
+function roundToTwo(value) {
+	return Math.round(value * 100) / 100;
+}
+
+function normalizePriorityNumber(priority) {
+	if (priority === undefined || priority === null) {
+		return 2;
+	}
+
+	if (typeof priority === 'string') {
+		switch (priority) {
+			case 'P0':
+				return 0;
+			case 'P1':
+				return 1;
+			case 'P2':
+				return 2;
+			case 'P3':
+				return 3;
+			case 'P4':
+				return 4;
+			default:
+				return 5;
+		}
+	}
+
+	return priority;
+}
+
+function getPriorityWeight(priority) {
+	switch (normalizePriorityNumber(priority)) {
+		case 0:
+			return 5;
+		case 1:
+			return 4;
+		case 2:
+			return 3;
+		case 3:
+			return 2;
+		case 4:
+			return 1;
+		default:
+			return 1;
+	}
+}
+
+function getTypeWeight(type = 'task') {
+	const normalizedType = type ?? 'task';
+	if (normalizedType === 'bug') {
+		return 1.2;
+	}
+	if (normalizedType === 'feature') {
+		return 1;
+	}
+	if (normalizedType === 'task') {
+		return 0.8;
+	}
+	return 1;
+}
+
+function getStatusBoost(status) {
+	if (status === 'in_progress') {
+		return 1.5;
+	}
+	if (status === 'open') {
+		return 1;
+	}
+	return 1;
+}
+
+function parseUpdatedAtLikeShell(updatedAt) {
+	if (!updatedAt) {
+		return null;
+	}
+
+	const normalized = `${String(updatedAt).slice(0, 19)}Z`;
+	const timestamp = Date.parse(normalized);
+	return Number.isFinite(timestamp) ? timestamp : null;
+}
+
+function getStalenessBoost(updatedAt, now = Date.now()) {
+	const timestamp = parseUpdatedAtLikeShell(updatedAt);
+	if (timestamp === null) {
+		return 1;
+	}
+
+	const days = (now - timestamp) / 86400000;
+	if (days >= 30) {
+		return 1.5;
+	}
+	if (days >= 14) {
+		return 1.2;
+	}
+	if (days >= 7) {
+		return 1.1;
+	}
+	return 1;
+}
+
+function buildDependentsMap(issues) {
+	const dependentsMap = new Map();
+
+	for (const issue of issues) {
+		for (const dependency of issue.dependencies ?? []) {
+			// The Kernel emits `dependencies` as bare id strings; the legacy shape
+			// used `{ depends_on_id }` objects. Accept both so the reverse-graph is
+			// reconstructable even when an issue arrives without a `dependents` array.
+			const dependencyId = typeof dependency === 'string'
+				? dependency
+				: dependency?.depends_on_id;
+			if (!dependencyId) {
+				continue;
+			}
+			if (!dependentsMap.has(dependencyId)) {
+				dependentsMap.set(dependencyId, []);
+			}
+			dependentsMap.get(dependencyId).push(issue.id);
+		}
+	}
+
+	return dependentsMap;
+}
+
+function getEpicProximity(issue, epicStats) {
+	if (!issue.parent_id || !epicStats?.[issue.parent_id]) {
+		return 1;
+	}
+
+	const stats = epicStats[issue.parent_id];
+	if (stats.total <= 0) {
+		return 1;
+	}
+
+	return 1 + ((stats.closed / stats.total) * 0.5);
+}
+
+function scoreIssues(issues, options = {}) {
+	const epicStats = options.epicStats ?? {};
+	const now = options.now ?? Date.now();
+	const dependentsMap = buildDependentsMap(issues);
+
+	return [...issues]
+		.map((issue) => {
+			const priorityWeight = getPriorityWeight(issue.priority);
+			// Prefer an explicit count, then the Kernel's authoritative `dependents`
+			// reverse-graph array, then the locally-reconstructed map (legacy shape).
+			const directDependents = issue.dependent_count
+				?? (Array.isArray(issue.dependents) ? issue.dependents.length : undefined)
+				?? dependentsMap.get(issue.id)?.length
+				?? 0;
+			const unblockChain = Math.max(directDependents + 1, 1);
+			const typeWeight = getTypeWeight(issue.type);
+			const statusBoost = getStatusBoost(issue.status);
+			const epicProximity = getEpicProximity(issue, epicStats);
+			const stalenessBoost = getStalenessBoost(issue.updated_at, now);
+			// The Kernel supplies `dependents` directly (reverse graph); fall back to
+			// the reconstructed map only for the legacy { depends_on_id } shape.
+			const dependents = Array.isArray(issue.dependents)
+				? issue.dependents
+				: (dependentsMap.get(issue.id) ?? []);
+			const score = priorityWeight
+				* unblockChain
+				* typeWeight
+				* statusBoost
+				* epicProximity
+				* stalenessBoost;
+
+			return {
+				...issue,
+				score: roundToTwo(score),
+				priority_weight: priorityWeight,
+				unblock_chain: unblockChain,
+				type_weight: typeWeight,
+				status_boost: statusBoost,
+				epic_proximity: roundToTwo(epicProximity),
+				staleness_boost: stalenessBoost,
+				dependents,
+			};
+		})
+		.sort((left, right) => right.score - left.score);
+}
+
+module.exports = {
+	getPriorityWeight,
+	getStalenessBoost,
+	getStatusBoost,
+	getTypeWeight,
+	scoreIssues,
+};

package/lib/status/beads-snapshot.js

@@ -0,0 +1,145 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { secureExecFileSync } = require('../shell-utils.js');
+
+function getGitConfig(projectRoot, key) {
+	try {
+		return secureExecFileSync('git', ['config', key], {
+			encoding: 'utf8',
+			cwd: projectRoot,
+			stdio: ['pipe', 'pipe', 'pipe'],
+		}).trim();
+	} catch (_error) {
+		return '';
+	}
+}
+
+function getDeveloperIdentity(projectRoot) {
+	return {
+		email: getGitConfig(projectRoot, 'user.email'),
+		name: getGitConfig(projectRoot, 'user.name'),
+	};
+}
+
+function normalizeEmail(value) {
+	return typeof value === 'string' ? value.trim().toLowerCase() : '';
+}
+
+function readIssues(projectRoot) {
+	const issuesPath = path.join(projectRoot, '.beads', 'issues.jsonl');
+	if (!fs.existsSync(issuesPath)) {
+		return [];
+	}
+
+	const raw = fs.readFileSync(issuesPath, 'utf8');
+	const latestById = new Map();
+
+	for (const line of raw.split(/\r?\n/)) {
+		if (!line.trim()) {
+			continue;
+		}
+
+		try {
+			const issue = JSON.parse(line);
+			if (issue && issue.id) {
+				latestById.set(issue.id, issue);
+			}
+		} catch (_error) {
+			// Ignore malformed rows so one bad append does not break status.
+		}
+	}
+
+	return Array.from(latestById.values());
+}
+
+function isAssignedToDeveloper(issue, developer) {
+	if (!issue || !developer) {
+		return false;
+	}
+
+	if (issue.owner) {
+		const developerEmail = normalizeEmail(developer.email);
+		return developerEmail !== '' && normalizeEmail(issue.owner) === developerEmail;
+	}
+
+	return developer.name !== '' && issue.created_by === developer.name;
+}
+
+const DEFAULT_STALE_AFTER_DAYS = 14;
+
+function parseTimestampOrZero(value) {
+	if (!value) {
+		return 0;
+	}
+
+	const parsed = Date.parse(value);
+	return Number.isNaN(parsed) ? 0 : parsed;
+}
+
+function sortByUpdatedAtDesc(left, right) {
+	const leftTime = parseTimestampOrZero(left.updated_at);
+	const rightTime = parseTimestampOrZero(right.updated_at);
+	return rightTime - leftTime;
+}
+
+function hasUnresolvedDependencies(issue) {
+	return Number(issue.dependency_count || 0) > 0;
+}
+
+function isOpenIssue(issue) {
+	return issue.status === 'open' || issue.status === 'in_progress';
+}
+
+function isStale(issue, now, staleAfterDays) {
+	if (!isOpenIssue(issue)) {
+		return false;
+	}
+
+	const updatedAt = parseTimestampOrZero(issue.updated_at);
+	if (updatedAt === 0) {
+		return false;
+	}
+
+	const staleMs = staleAfterDays * 24 * 60 * 60 * 1000;
+	return now.getTime() - updatedAt >= staleMs;
+}
+
+function readBeadsSnapshot(projectRoot, options = {}) {
+	const developer = getDeveloperIdentity(projectRoot);
+	const issues = readIssues(projectRoot);
+	const parsedNow = options.now instanceof Date
+		? options.now
+		: (typeof options.now === 'string' ? new Date(options.now) : null);
+	const now = parsedNow instanceof Date && !Number.isNaN(parsedNow.getTime())
+		? parsedNow
+		: new Date();
+	const parsedStaleAfterDays = Number(options.staleAfterDays);
+	const staleAfterDays = Number.isFinite(parsedStaleAfterDays)
+		? parsedStaleAfterDays
+		: DEFAULT_STALE_AFTER_DAYS;
+
+	return {
+		developer,
+		issues,
+		active: issues.filter(issue => issue.status === 'in_progress').sort(sortByUpdatedAtDesc),
+		activeAssigned: issues.filter(issue => issue.status === 'in_progress' && isAssignedToDeveloper(issue, developer)),
+		ready: issues.filter(issue => issue.status === 'open' && !hasUnresolvedDependencies(issue)),
+		blocked: issues.filter(issue => isOpenIssue(issue) && hasUnresolvedDependencies(issue)).sort(sortByUpdatedAtDesc),
+		stale: issues.filter(issue => isStale(issue, now, staleAfterDays)).sort(sortByUpdatedAtDesc),
+		recentCompleted: issues.filter(issue => issue.status === 'closed').sort(sortByUpdatedAtDesc),
+		limits: [
+			'Uses local Beads issues.jsonl only.',
+			'Does not read GitHub review, CI, project, or sync freshness state.',
+		],
+	};
+}
+
+module.exports = {
+	getDeveloperIdentity,
+	isAssignedToDeveloper,
+	readBeadsSnapshot,
+	hasUnresolvedDependencies,
+	isStale,
+};

package/lib/status/presenter.js

@@ -0,0 +1,216 @@
+'use strict';
+
+const {
+	STAGE_LABELS,
+	getStageWorkflow,
+	getWorkflowPath,
+} = require('../workflow/stages');
+
+const DEFAULT_SECTION_LIMIT = 5;
+
+// One-line "why you are at this stage", keyed by the LAST completed stage. Lets the
+// one-glance view answer "why here?" without the agent re-deriving it from raw state.
+const WHY_BY_LAST_COMPLETED = Object.freeze({
+	plan: 'planning is done; implementation not started.',
+	dev: 'implementation landed; not yet validated.',
+	validate: 'validation passed; PR not yet created.',
+	ship: 'PR is open; review not yet complete.',
+	review: 'review addressed; awaiting merge/verify.',
+	verify: 'post-merge verification complete.',
+});
+
+function buildSection(title, items, options = {}) {
+	const lines = ['', title];
+	if (!items || items.length === 0) {
+		lines.push('  none', '');
+		return lines;
+	}
+
+	const limit = options.limit ?? null;
+	const visibleItems = limit ? items.slice(0, limit) : items;
+	lines.push(...visibleItems.map(item => `  ${item}`));
+
+	if (limit && items.length > limit) {
+		lines.push(`  ...and ${items.length - limit} more`);
+	}
+
+	lines.push('');
+	return lines;
+}
+
+function toIssueSummary(issue) {
+	return {
+		id: issue.id,
+		title: issue.title || '(untitled)',
+		status: issue.status || null,
+		owner: issue.owner || null,
+		dependency_count: Number(issue.dependency_count || 0),
+		updated_at: issue.updated_at || null,
+	};
+}
+
+function formatIssue(issue, options = {}) {
+	const status = options.includeStatus && issue.status ? ` [${issue.status}]` : '';
+	return `${issue.id} ${issue.title || '(untitled)'}${status}`;
+}
+
+// Shared Run-now / Next-after-this lines. Owned here so BOTH the one-glance
+// "You are here" block and status.js's authoritative stage format render them
+// identically. `noneWhenMissing` prints an explicit "none" for terminal stages
+// (the one-glance view wants it; the authoritative format omits it, as before).
+function formatRunNextLines(workflowResult, { noneWhenMissing = false } = {}) {
+	const lines = [`Run now: /${workflowResult.runCommand}`];
+	if (workflowResult.nextCommand) {
+		lines.push(`Next after this: /${workflowResult.nextCommand}`);
+	} else if (noneWhenMissing) {
+		lines.push('Next after this: none');
+	}
+	return lines;
+}
+
+// Canonical "Stage N of M — Label (classification workflow)" heading. N/M come from
+// the per-classification path in lib/workflow/stages.js, so non-stages (Research,
+// Merge, pre-merge, "Fresh Start") never get a number.
+function formatStageHeading(workflowResult) {
+	const classification = workflowResult.workflowState?.workflowDecisions?.classification || null;
+	const stageId = workflowResult.stageId;
+	const label = STAGE_LABELS[stageId] || workflowResult.stageName || stageId;
+	const workflow = getStageWorkflow(stageId, classification);
+	const path = getWorkflowPath(classification);
+
+	if (workflow && path.length > 0) {
+		return `Stage ${workflow.order} of ${path.length} — ${label} (${classification} workflow)`;
+	}
+	return `Stage — ${label}${classification ? ` (${classification} workflow)` : ''}`;
+}
+
+function deriveWhy(workflowResult) {
+	const completed = workflowResult.workflowState?.completedStages || [];
+	const last = completed.length > 0 ? completed[completed.length - 1] : null;
+	return (last && WHY_BY_LAST_COMPLETED[last]) || 'just getting started.';
+}
+
+// The "You are here" block: the first thing a user or agent reads. When there is no
+// active workflow, fall back to a STATE-AWARE next step rather than a dead end.
+function buildYouAreHere(workflowResult, snapshot) {
+	const lines = ['You are here'];
+
+	if (!workflowResult) {
+		const topReady = (snapshot.ready || [])[0];
+		if (topReady) {
+			lines.push(`  No active workflow. Next: forge claim ${topReady.id}, then /plan (or /dev for a small fix).`);
+		} else {
+			lines.push('  No active workflow and no ready issues. Next: /plan "<describe the feature>" to start one.');
+		}
+		return lines;
+	}
+
+	lines.push(`  ${formatStageHeading(workflowResult)}`);
+	for (const line of formatRunNextLines(workflowResult, { noneWhenMissing: true })) {
+		lines.push(`  ${line}`);
+	}
+	lines.push(`  Why: ${deriveWhy(workflowResult)}`);
+	return lines;
+}
+
+// Zero-arg `forge status`: a top-down one-glance view. Order matters — orientation
+// first (You are here), then Context, then your work. Blocked/Stale/Recent
+// completions are detail, shown only with `--full`.
+function formatZeroArgStatus({ context, snapshot, workflowResult = null, full = false }) {
+	const worktree = context.inWorktree ? 'worktree' : 'main';
+	const contextLine = `${context.branch} — ${worktree}, ${context.workingTree.summary}`;
+
+	const activeIssues = snapshot.activeAssigned || [];
+	const readyCount = (snapshot.ready || []).length;
+	const workLines = [];
+	if (activeIssues.length > 0) {
+		for (const issue of activeIssues) {
+			workLines.push(`Active: ${formatIssue(issue, { includeStatus: true })}`);
+		}
+	} else {
+		workLines.push('Active: none');
+	}
+	workLines.push(readyCount > 0 ? `Ready: ${readyCount} more (forge issue ready)` : 'Ready: none');
+
+	const blocks = [
+		buildYouAreHere(workflowResult, snapshot).join('\n'),
+		['Context', `  ${contextLine}`].join('\n'),
+		['Your work', ...workLines.map(line => `  ${line}`)].join('\n'),
+		'New here? forge docs setup | forge --help',
+	];
+
+	if (full) {
+		blocks.push(
+			buildSection('Blocked', (snapshot.blocked || []).map(issue => formatIssue(issue, { includeStatus: true })), { limit: DEFAULT_SECTION_LIMIT }).join('\n').trim(),
+			buildSection('Stale', (snapshot.stale || []).map(issue => formatIssue(issue, { includeStatus: true })), { limit: DEFAULT_SECTION_LIMIT }).join('\n').trim(),
+			buildSection('Parked', (snapshot.parked || []).map(issue => formatIssue(issue, { includeStatus: true })), { limit: DEFAULT_SECTION_LIMIT }).join('\n').trim(),
+			buildSection('Recent Completions', (snapshot.recentCompleted || []).map(issue => formatIssue(issue)), { limit: DEFAULT_SECTION_LIMIT }).join('\n').trim(),
+		);
+	}
+
+	return blocks.join('\n\n');
+}
+
+function buildPersonalStatusJson({ context, snapshot, workflowResult = null }) {
+	return {
+		context,
+		personal: {
+			activeAssigned: (snapshot.activeAssigned || []).map(toIssueSummary),
+			ready: (snapshot.ready || []).map(toIssueSummary),
+			blocked: (snapshot.blocked || []).map(toIssueSummary),
+			stale: (snapshot.stale || []).map(toIssueSummary),
+			parked: (snapshot.parked || []).map(toIssueSummary),
+			recentCompleted: (snapshot.recentCompleted || []).map(toIssueSummary),
+		},
+		workflow: workflowResult ? {
+			stageId: workflowResult.stageId,
+			stageName: workflowResult.stageName,
+			runCommand: workflowResult.runCommand,
+			nextCommand: workflowResult.nextCommand,
+			nextStages: workflowResult.nextStages,
+		} : null,
+		limits: snapshot.limits || [],
+	};
+}
+
+function formatBoard({ context, snapshot }) {
+	return [
+		'',
+		'Team Runtime Board',
+		`Source: local Beads runtime state`,
+		`Branch: ${context.branch}`,
+		`Working tree: ${context.workingTree.summary}`,
+		'',
+		...buildSection('Active', (snapshot.active || []).map(issue => formatIssue(issue, { includeStatus: true })), { limit: DEFAULT_SECTION_LIMIT }),
+		...buildSection('Ready', (snapshot.ready || []).map(issue => formatIssue(issue)), { limit: DEFAULT_SECTION_LIMIT }),
+		...buildSection('Blocked', (snapshot.blocked || []).map(issue => formatIssue(issue, { includeStatus: true })), { limit: DEFAULT_SECTION_LIMIT }),
+		...buildSection('Stale', (snapshot.stale || []).map(issue => formatIssue(issue, { includeStatus: true })), { limit: DEFAULT_SECTION_LIMIT }),
+		...buildSection('Parked', (snapshot.parked || []).map(issue => formatIssue(issue, { includeStatus: true })), { limit: DEFAULT_SECTION_LIMIT }),
+		...buildSection('Recent Completions', (snapshot.recentCompleted || []).map(issue => formatIssue(issue)), { limit: DEFAULT_SECTION_LIMIT }),
+		...buildSection('Limits', snapshot.limits || []),
+	].join('\n');
+}
+
+function buildBoardJson({ context, snapshot }) {
+	return {
+		context,
+		board: {
+			active: (snapshot.active || []).map(toIssueSummary),
+			ready: (snapshot.ready || []).map(toIssueSummary),
+			blocked: (snapshot.blocked || []).map(toIssueSummary),
+			stale: (snapshot.stale || []).map(toIssueSummary),
+			parked: (snapshot.parked || []).map(toIssueSummary),
+			recentCompleted: (snapshot.recentCompleted || []).map(toIssueSummary),
+		},
+		limits: snapshot.limits || [],
+	};
+}
+
+module.exports = {
+	buildBoardJson,
+	buildPersonalStatusJson,
+	formatBoard,
+	formatRunNextLines,
+	formatZeroArgStatus,
+	toIssueSummary,
+};