@ag-eco/agentplate-cli 0.13.0

package/src/tools/sprout/commands/prime.ts

@@ -0,0 +1,399 @@
+import { join } from "node:path";
+import type { Command } from "commander";
+import { findSproutDir } from "../config.ts";
+import { outputJson } from "../output.ts";
+
+const PRIME_FILE = "PRIME.md";
+
+export interface PrimeCommand {
+	command: string;
+	description: string;
+}
+
+export interface PrimeCommandGroup {
+	name: string;
+	commands: PrimeCommand[];
+	notes?: string[];
+}
+
+export interface PrimeWorkflow {
+	name: string;
+	commands: string[];
+}
+
+export interface PrimeSectionsFull {
+	mode: "full";
+	title: string;
+	contextRecovery: string;
+	closeProtocol: {
+		warning: string;
+		steps: string[];
+		footer: string;
+	};
+	rules: string[];
+	commandGroups: PrimeCommandGroup[];
+	workflows: PrimeWorkflow[];
+}
+
+export interface PrimeSectionsCompact {
+	mode: "compact";
+	title: string;
+	commands: PrimeCommand[];
+	planningNote: string;
+	closingNote: string;
+}
+
+export type PrimeSections = PrimeSectionsFull | PrimeSectionsCompact;
+
+const FULL_SECTIONS: PrimeSectionsFull = {
+	mode: "full",
+	title: "Sprout Workflow Context",
+	contextRecovery: "Run `sr prime` after compaction, clear, or new session",
+	closeProtocol: {
+		warning: 'Before saying "done" or "complete", you MUST run this checklist:',
+		steps: [
+			"Close completed issues:    sr close <id1> <id2> ...",
+			'File issues for remaining:  sr create --title "..."',
+			"Run quality gates:          bun test && bun run lint && bun run typecheck",
+			"Sync and push:              sr sync && git push",
+			'Verify:                     git status (must show "up to date with origin")',
+		],
+		footer: "**NEVER skip this.** Work is not done until pushed.",
+	},
+	rules: [
+		"**Default**: Use sprout for ALL task tracking (`sr create`, `sr ready`, `sr close`)",
+		"**Prohibited**: Do NOT use TodoWrite, TaskCreate, or markdown files for task tracking",
+		"**Workflow**: Create issues BEFORE writing code, mark in_progress when starting",
+		"Git workflow: run `sr sync` at session end",
+	],
+	commandGroups: [
+		{
+			name: "Finding Work",
+			commands: [
+				{ command: "sr ready", description: "Show issues ready to work (no blockers)" },
+				{ command: "sr list --status=open", description: "All open issues" },
+				{ command: "sr list --status=in_progress", description: "Your active work" },
+				{
+					command: "sr show <id> [<id2> ...]",
+					description:
+						"Detailed issue view; multi-id shows each separated by a divider (`--json` returns `issues: [...]`)",
+				},
+			],
+		},
+		{
+			name: "Creating & Updating",
+			commands: [
+				{
+					command: 'sr create --title="..." --type=task|bug|feature|epic --priority=2',
+					description: "New issue\n  - Priority: 0-4 or P0-P4 (0=critical, 2=medium, 4=backlog)",
+				},
+				{ command: "sr update <id> --status=in_progress", description: "Claim work" },
+				{ command: "sr update <id> --assignee=username", description: "Assign to someone" },
+				{ command: "sr close <id>", description: "Mark complete" },
+				{ command: "sr close <id1> <id2> ...", description: "Close multiple issues at once" },
+			],
+		},
+		{
+			name: "Dependencies & Blocking",
+			commands: [
+				{ command: "sr dep add <issue> <depends-on>", description: "Add dependency" },
+				{ command: "sr dep remove <issue> <depends-on>", description: "Remove dependency" },
+				{ command: "sr blocked", description: "Show all blocked issues" },
+			],
+		},
+		{
+			name: "Labels",
+			commands: [
+				{ command: "sr label add <id> bug ui", description: "Add labels to an issue" },
+				{ command: "sr label remove <id> bug", description: "Remove labels" },
+				{ command: "sr label list <id>", description: "List labels on an issue" },
+				{ command: "sr label list-all", description: "Show all labels in project" },
+				{
+					command: "sr list --label=bug",
+					description: "Filter by label (AND, comma-separated)",
+				},
+				{ command: "sr list --label-any=bug,ui", description: "Filter by label (OR)" },
+				{ command: "sr list --unlabeled", description: "Issues with no labels" },
+				{ command: 'sr create --title="..." --labels=bug,ui', description: "Create with labels" },
+			],
+		},
+		{
+			name: "Sync & Project Health",
+			commands: [
+				{ command: "sr sync", description: "Stage and commit .sprout/ changes" },
+				{ command: "sr sync --status", description: "Check without committing" },
+				{ command: "sr stats", description: "Project statistics" },
+				{ command: "sr doctor", description: "Check for data integrity issues" },
+			],
+		},
+		{
+			name: "Planning",
+			notes: [
+				'Use `sr plan` when work is large or ambiguous enough to benefit from structured decomposition. The plan spawns one child seed per step; `step.blocks` uses forward semantics (step i with `blocks: [j]` means step i blocks step j). Each step accepts an optional `labels: string[]` field (normalized lowercase/trim/dedup) that flows to the spawned child or merges additively into an adopted seed — useful for tagging agent-spawned children (e.g. `"labels": ["nightwatch"]`) without follow-up `sr label add` calls. For small, well-scoped tasks, just `sr create` directly.',
+			],
+			commands: [
+				{
+					command: "sr plan templates",
+					description: "List built-in templates (`feature`, `bug`, `refactor`) plus custom ones",
+				},
+				{
+					command: "sr plan prompt <seed-id>",
+					description: "Emit prompt JSON for the LLM to fill",
+				},
+				{
+					command: "sr plan submit <seed-id> --plan <file>",
+					description: "Validate + spawn children",
+				},
+				{ command: "sr plan show <pl-id>", description: "Sections, children, nested sub-plans" },
+				{
+					command: "sr plan create <seed-id>",
+					description:
+						"Adopt-only plan (zero spawned children); populate via 'sr plan adopt' + 'sr plan reorder'",
+				},
+				{
+					command: "sr plan adopt <pl-id> <seed-id...> [--step|--at|--before|--after]",
+					description:
+						"Adopt existing sprout into a plan; --at/--before/--after control children position",
+				},
+				{
+					command: "sr plan reorder <pl-id> <seed-id...>",
+					description: "Set the exact plan.children order (permutation of current children)",
+				},
+				{
+					command:
+						"sr plan edit <id> [--name|--section <n> <t>|--step <i> --title/--priority/--type]",
+					description:
+						"In-place field edits; bumps revision. Structural changes still need --overwrite.",
+				},
+				{
+					command: "sr plan outcome <pl-id> --result success|partial|failure",
+					description: "Storage-only outcome",
+				},
+				{
+					command: "sr plan review <pl-id> --by <name>",
+					description: "Optional reviewer (informational)",
+				},
+			],
+		},
+	],
+	workflows: [
+		{
+			name: "Starting work",
+			commands: [
+				"sr ready                              # Find available work",
+				"sr show <id>                          # Review issue details",
+				"sr update <id> --status=in_progress   # Claim it",
+			],
+		},
+		{
+			name: "Completing work",
+			commands: [
+				"sr close <id1> <id2> ...    # Close all completed issues at once",
+				"sr sync                     # Stage + commit .sprout/",
+				"git push                    # Push to remote",
+			],
+		},
+		{
+			name: "Creating dependent work",
+			commands: [
+				'sr create --title="Implement feature X" --type=feature',
+				'sr create --title="Write tests for X" --type=task',
+				"sr dep add <test-id> <feature-id>   # Tests depend on feature",
+			],
+		},
+	],
+};
+
+const COMPACT_SECTIONS: PrimeSectionsCompact = {
+	mode: "compact",
+	title: "Sprout Quick Reference",
+	commands: [
+		{ command: "sr ready", description: "Find unblocked work" },
+		{ command: "sr show <id> [id...]", description: "View one or more issues" },
+		{ command: 'sr create --title "..."', description: "Create issue (--type, --priority)" },
+		{ command: "sr update <id> --status in_progress", description: "Claim work" },
+		{ command: "sr close <id>", description: "Complete work" },
+		{ command: "sr dep add <a> <b>", description: "a depends on b" },
+		{ command: "sr blocked", description: "Show blocked issues" },
+		{ command: "sr label add <id> <l...>", description: "Add labels" },
+		{ command: "sr list --label=bug", description: "Filter by label" },
+		{
+			command: "sr plan prompt <seed>",
+			description: "Plan large/ambiguous work; spawns child sprout",
+		},
+		{ command: "sr plan submit <seed> --plan <file>", description: "Submit + spawn children" },
+		{ command: "sr sync", description: "Stage + commit .sprout/" },
+	],
+	planningNote:
+		"**Planning:** Use `sr plan` for ambiguous or large work — built-in templates: `feature`, `bug`, `refactor`.",
+	closingNote: "**Before finishing:** `sr close <ids> && sr sync && git push`",
+};
+
+function renderFull(s: PrimeSectionsFull): string {
+	const lines: string[] = [];
+	lines.push(`# ${s.title}`);
+	lines.push("");
+	lines.push(`> **Context Recovery**: ${s.contextRecovery}`);
+	lines.push("");
+
+	lines.push("# Session Close Protocol");
+	lines.push("");
+	lines.push(`**CRITICAL**: ${s.closeProtocol.warning}`);
+	lines.push("");
+	lines.push("```");
+	s.closeProtocol.steps.forEach((step, i) => {
+		lines.push(`[ ] ${i + 1}. ${step}`);
+	});
+	lines.push("```");
+	lines.push("");
+	lines.push(s.closeProtocol.footer);
+	lines.push("");
+
+	lines.push("## Core Rules");
+	for (const rule of s.rules) {
+		lines.push(`- ${rule}`);
+	}
+	lines.push("");
+
+	lines.push("## Essential Commands");
+	lines.push("");
+	for (const group of s.commandGroups) {
+		lines.push(`### ${group.name}`);
+		if (group.notes) {
+			for (const note of group.notes) {
+				lines.push(note);
+				lines.push("");
+			}
+		}
+		for (const cmd of group.commands) {
+			lines.push(`- \`${cmd.command}\` — ${cmd.description}`);
+		}
+		lines.push("");
+	}
+
+	lines.push("## Common Workflows");
+	lines.push("");
+	for (const wf of s.workflows) {
+		lines.push(`**${wf.name}:**`);
+		lines.push("```bash");
+		for (const c of wf.commands) {
+			lines.push(c);
+		}
+		lines.push("```");
+		lines.push("");
+	}
+
+	return `${lines.join("\n")}`;
+}
+
+function renderCompact(s: PrimeSectionsCompact): string {
+	const lines: string[] = [];
+	lines.push(`# ${s.title}`);
+	lines.push("");
+	lines.push("```");
+	// Align descriptions at a fixed column for readability.
+	const pad = 26;
+	for (const c of s.commands) {
+		const cmd = c.command.length >= pad ? `${c.command} ` : c.command.padEnd(pad);
+		lines.push(`${cmd}# ${c.description}`);
+	}
+	lines.push("```");
+	lines.push("");
+	lines.push(s.planningNote);
+	lines.push("");
+	lines.push(s.closingNote);
+	lines.push("");
+	return lines.join("\n");
+}
+
+export function buildFullSections(): PrimeSectionsFull {
+	return FULL_SECTIONS;
+}
+
+export function buildCompactSections(): PrimeSectionsCompact {
+	return COMPACT_SECTIONS;
+}
+
+export function renderPrimeSections(sections: PrimeSections): string {
+	return sections.mode === "compact" ? renderCompact(sections) : renderFull(sections);
+}
+
+function defaultPrimeContent(compact: boolean): string {
+	return renderPrimeSections(compact ? COMPACT_SECTIONS : FULL_SECTIONS);
+}
+
+export async function run(args: string[]): Promise<void> {
+	const jsonMode = args.includes("--json");
+	const compact = args.includes("--compact");
+	const exportMode = args.includes("--export");
+
+	// --export always outputs the default template
+	if (exportMode) {
+		const sections = compact ? COMPACT_SECTIONS : FULL_SECTIONS;
+		const content = renderPrimeSections(sections);
+		if (jsonMode) {
+			await outputJson({ success: true, command: "prime", sections, content });
+		} else {
+			process.stdout.write(content);
+		}
+		return;
+	}
+
+	// Try to find sprout dir for custom PRIME.md
+	let customContent: string | null = null;
+	try {
+		const sproutDir = await findSproutDir();
+		const customFile = Bun.file(join(sproutDir, PRIME_FILE));
+		if (await customFile.exists()) {
+			customContent = await customFile.text();
+		}
+	} catch {
+		// No sprout dir — that's fine, use default
+	}
+
+	if (customContent !== null) {
+		// Custom PRIME.md is opaque — we can't structurally parse it, so omit sections.
+		if (jsonMode) {
+			await outputJson({
+				success: true,
+				command: "prime",
+				sections: null,
+				content: customContent,
+			});
+		} else {
+			process.stdout.write(customContent);
+		}
+		return;
+	}
+
+	const sections = compact ? COMPACT_SECTIONS : FULL_SECTIONS;
+	const content = renderPrimeSections(sections);
+	if (jsonMode) {
+		await outputJson({ success: true, command: "prime", sections, content });
+	} else {
+		process.stdout.write(content);
+	}
+}
+
+export function register(program: Command): void {
+	program
+		.command("prime")
+		.description("Output AI agent context")
+		.option("--compact", "Condensed quick-reference output")
+		.option("--export", "Output the default template")
+		.option("--json", "Output as JSON")
+		.action(async (opts: { compact?: boolean; export?: boolean; json?: boolean }) => {
+			const args: string[] = [];
+			if (opts.compact) args.push("--compact");
+			if (opts.export) args.push("--export");
+			if (opts.json) args.push("--json");
+			await run(args);
+		});
+}
+
+// Internal exports for testing.
+export const _internal = {
+	defaultPrimeContent,
+	FULL_SECTIONS,
+	COMPACT_SECTIONS,
+};

package/src/tools/sprout/commands/ready.ts

@@ -0,0 +1,245 @@
+import type { Command } from "commander";
+import { findSproutDir } from "../config.ts";
+import { applyIssueFilters, filterOptionsFromFlags, parseLimitFlag } from "../filter.ts";
+import { resolveFormat, stripAnsi, VALID_FORMATS } from "../format.ts";
+import {
+	formatIssueOneLine,
+	formatIssueOneLineCompact,
+	outputJson,
+	printIssueOneLine,
+} from "../output.ts";
+import {
+	isPlanDraftBlocking,
+	issueJsonWithPlan,
+	loadPlanContext,
+	planForIssue,
+	planLineSuffix,
+} from "../plan-context.ts";
+import { isSortMode, sortIssues, VALID_SORT_MODES } from "../sort.ts";
+import { readIssues } from "../store.ts";
+import type { Issue, Plan } from "../types.ts";
+
+// pl-c195 step 4: opt-in schedule filter. Two well-known extension keys:
+//   extensions.queued === true     → not ready yet (intentionally parked)
+//   extensions.scheduledFor: ISO8601 in the future → not ready yet
+// Malformed/past values fall through to ready as if the keys weren't set.
+function isScheduledOut(issue: Issue, now: number): boolean {
+	const ext = issue.extensions;
+	if (!ext) return false;
+	if (ext.queued === true) return true;
+	const sched = ext.scheduledFor;
+	if (typeof sched === "string") {
+		const t = Date.parse(sched);
+		if (!Number.isNaN(t) && t > now) return true;
+	}
+	return false;
+}
+
+function parseArgs(args: string[]): Record<string, string | boolean> {
+	const flags: Record<string, string | boolean> = {};
+	let i = 0;
+	while (i < args.length) {
+		const arg = args[i];
+		if (!arg) {
+			i++;
+			continue;
+		}
+		if (arg.startsWith("--")) {
+			const key = arg.slice(2);
+			const eqIdx = key.indexOf("=");
+			if (eqIdx !== -1) {
+				flags[key.slice(0, eqIdx)] = key.slice(eqIdx + 1);
+				i++;
+			} else {
+				const next = args[i + 1];
+				if (next !== undefined && !next.startsWith("--")) {
+					flags[key] = next;
+					i += 2;
+				} else {
+					flags[key] = true;
+					i++;
+				}
+			}
+		} else {
+			i++;
+		}
+	}
+	return flags;
+}
+
+export async function run(args: string[], sproutDir?: string): Promise<void> {
+	const fmt = resolveFormat(args);
+	const jsonMode = fmt.mode === "json";
+	if (fmt.error) {
+		if (jsonMode) {
+			await outputJson({ success: false, command: "ready", error: fmt.error });
+		} else {
+			console.error(fmt.error);
+		}
+		process.exitCode = 1;
+		return;
+	}
+	const flags = parseArgs(args);
+	let limit: number;
+	try {
+		limit = parseLimitFlag(flags.limit);
+	} catch (e) {
+		const msg = (e as Error).message;
+		if (jsonMode) {
+			await outputJson({ success: false, command: "ready", error: msg });
+		} else {
+			console.error(msg);
+		}
+		process.exitCode = 1;
+		return;
+	}
+
+	const dir = sproutDir ?? (await findSproutDir());
+	const issues = await readIssues(dir);
+	const planCtx = await loadPlanContext(dir);
+
+	const closedIds = new Set(issues.filter((i: Issue) => i.status === "closed").map((i) => i.id));
+
+	let ready = issues.filter((i: Issue) => {
+		if (i.status !== "open") return false;
+		// PLAN_SPEC.md:342 — sprout with requires_plan are excluded until their
+		// own sub-plan reaches `approved`. Lookup by seed-id since plan_id is
+		// not set on the spawned child until its sub-plan submit succeeds.
+		if (i.requires_plan === true) {
+			const sub = planCtx.plansBySeed.get(i.id);
+			if (!sub || sub.status === "draft") return false;
+			// approved/active/done: fall through to standard blocker check.
+		} else if (isPlanDraftBlocking(planForIssue(planCtx, i))) {
+			// Planning is the highest-priority work: surface sprout with a draft
+			// plan even if they would otherwise be blocked. (PLAN_SPEC.md:154)
+			return true;
+		}
+		const blockers = i.blockedBy ?? [];
+		return blockers.every((bid) => closedIds.has(bid));
+	});
+
+	ready = applyIssueFilters(ready, filterOptionsFromFlags(flags));
+
+	if (flags["respect-schedule"] === true) {
+		const nowMs = Date.now();
+		ready = ready.filter((i) => !isScheduledOut(i, nowMs));
+	}
+
+	const sortFlag = typeof flags.sort === "string" ? flags.sort : "priority";
+	if (!isSortMode(sortFlag)) {
+		const msg = `Invalid --sort value: ${sortFlag}. Valid: ${VALID_SORT_MODES.join("|")}`;
+		if (jsonMode) {
+			await outputJson({ success: false, command: "ready", error: msg });
+		} else {
+			console.error(msg);
+		}
+		process.exitCode = 1;
+		return;
+	}
+	ready = sortIssues(ready, sortFlag);
+
+	ready = ready.slice(0, limit);
+
+	const annotate = (issue: Issue): { issue: Issue; plan?: Plan } => ({
+		issue,
+		plan: planForIssue(planCtx, issue),
+	});
+
+	switch (fmt.mode) {
+		case "json": {
+			const issuesWithPlan = ready.map((i) => issueJsonWithPlan(i, planForIssue(planCtx, i)));
+			await outputJson({
+				success: true,
+				command: "ready",
+				issues: issuesWithPlan,
+				count: ready.length,
+			});
+			return;
+		}
+		case "ids":
+			for (const issue of ready) console.log(issue.id);
+			return;
+		case "compact":
+			for (const issue of ready) console.log(formatIssueOneLineCompact(issue, closedIds));
+			return;
+		case "plain":
+			if (ready.length === 0) {
+				console.log("No ready issues.");
+				return;
+			}
+			for (const issue of ready) {
+				const { plan } = annotate(issue);
+				console.log(stripAnsi(formatIssueOneLine(issue, closedIds) + planLineSuffix(plan)));
+			}
+			console.log(`\n${ready.length} ready issue(s)`);
+			return;
+		default:
+			if (ready.length === 0) {
+				console.log("No ready issues.");
+				return;
+			}
+			for (const issue of ready) {
+				const { plan } = annotate(issue);
+				const suffix = planLineSuffix(plan);
+				if (suffix) {
+					process.stdout.write(`${formatIssueOneLine(issue, closedIds)}${suffix}\n`);
+				} else {
+					printIssueOneLine(issue, closedIds);
+				}
+			}
+			console.log(`\n${ready.length} ready issue(s)`);
+			return;
+	}
+}
+
+export function register(program: Command): void {
+	program
+		.command("ready")
+		.description("Show open issues with no unresolved blockers")
+		.option("--type <type>", "Filter by type (task|bug|feature|epic)")
+		.option("--assignee <name>", "Filter by assignee")
+		.option("--label <labels>", "Filter: must have ALL labels (comma-separated, AND)")
+		.option("--label-any <labels>", "Filter: must have any label (comma-separated, OR)")
+		.option("--unlabeled", "Filter: issues with no labels")
+		.option("--priority <levels>", "Filter by priority (comma-separated, e.g. 0,1 or P0,P1)")
+		.option("--priority-max <n>", "Filter to priority <= n (e.g. --priority-max 1 = P0+P1)")
+		.option("--limit <n>", "Max issues to show", "50")
+		.option("--sort <mode>", "Sort order (priority|created|updated|id)", "priority")
+		.option("--format <mode>", `Output format (${VALID_FORMATS.join("|")})`)
+		.option("--json", "Output as JSON (alias for --format json)")
+		.option(
+			"--respect-schedule",
+			"Exclude issues with extensions.queued=true or future extensions.scheduledFor",
+		)
+		.action(
+			async (opts: {
+				type?: string;
+				assignee?: string;
+				label?: string;
+				labelAny?: string;
+				unlabeled?: boolean;
+				priority?: string;
+				priorityMax?: string;
+				limit?: string;
+				sort?: string;
+				format?: string;
+				json?: boolean;
+				respectSchedule?: boolean;
+			}) => {
+				const args: string[] = [];
+				if (opts.type) args.push("--type", opts.type);
+				if (opts.assignee) args.push("--assignee", opts.assignee);
+				if (opts.label) args.push("--label", opts.label);
+				if (opts.labelAny) args.push("--label-any", opts.labelAny);
+				if (opts.unlabeled) args.push("--unlabeled");
+				if (opts.priority) args.push("--priority", opts.priority);
+				if (opts.priorityMax) args.push("--priority-max", opts.priorityMax);
+				if (opts.limit) args.push("--limit", opts.limit);
+				if (opts.sort) args.push("--sort", opts.sort);
+				if (opts.format) args.push("--format", opts.format);
+				if (opts.json) args.push("--json");
+				if (opts.respectSchedule) args.push("--respect-schedule");
+				await run(args);
+			},
+		);
+}