@ag-eco/agentplate-cli 0.13.0

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

@@ -0,0 +1,207 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { Command } from "commander";
+import { findSproutDir, projectRootFromSproutDir } from "../config.ts";
+import { hasMarkerSection, replaceMarkerSection, wrapInMarkers } from "../markers.ts";
+import { outputJson, printError, printSuccess } from "../output.ts";
+import { VERSION } from "../version.ts";
+
+// Schema version drives outdated-snippet detection. Bump when the snippet body changes
+// in a way agents should re-render. Independent of the package version so patch releases
+// don't mark every existing snippet as outdated.
+const ONBOARD_SCHEMA = 7;
+const SCHEMA_MARKER = `<!-- sprout-onboard-schema:${String(ONBOARD_SCHEMA)} -->`;
+const VERSION_MARKER = `<!-- sprout-onboard:v${VERSION} -->`;
+const LEGACY_VERSION_MARKER_PREFIX = "<!-- sprout-onboard-v:";
+
+const CANDIDATE_FILES = ["CLAUDE.md", ".claude/CLAUDE.md", "AGENTS.md"] as const;
+
+function onboardSnippet(): string {
+	return `## Issue Tracking (Sprout)
+${VERSION_MARKER}
+${SCHEMA_MARKER}
+
+This project uses [Sprout](https://github.com/jayminwest/sprout) v${VERSION} for git-native issue tracking.
+
+**At the start of every session**, run:
+\`\`\`
+sr prime
+\`\`\`
+
+This injects session context: rules, command reference, and workflows. Pass \`--format json|compact|markdown|plain|ids\` on any command for agent-friendly output.
+
+**Quick reference:**
+- \`sr ready\` — Find unblocked work
+- \`sr search <query>\` — Full-text search across titles + descriptions
+- \`sr create --title "..." --type task --priority 2\` — Create issue
+- \`sr update <id> --status in_progress\` — Claim work
+- \`sr close <id>\` — Complete work
+- \`sr dep add <id> <depends-on>\` — Add dependency between issues
+- \`sr sync\` — Sync with git (run before pushing)
+
+### Planning
+Use \`sr plan\` when work is large or ambiguous enough that an LLM benefits from structured decomposition. Submit spawns one child seed per step; \`step.blocks\` uses forward semantics (step i with \`blocks: [j]\` means step i blocks step j, and step j gets step i's id in its \`blockedBy\`).
+
+- \`sr plan templates\` — List built-ins (\`feature\`, \`bug\`, \`refactor\`) plus custom templates
+- \`sr plan prompt <seed-id>\` — Emit a structured prompt the LLM fills in
+- \`sr plan submit <seed-id> --plan <file>\` — Validate + spawn child sprout
+- \`sr plan show <pl-id>\` — View sections, children, sub-plans
+- \`sr plan edit <id> [--name | --section <name> <text> | --step <i> --title/--priority/--type]\` — In-place field edits; bumps revision
+- \`sr plan outcome <pl-id> --result success|partial|failure\` — Record outcome (storage-only)
+- \`sr plan review <pl-id> --by <name>\` — Record reviewer (informational)
+
+### Before You Finish
+1. Close completed issues: \`sr close <id>\`
+2. File issues for remaining work: \`sr create --title "..."\`
+3. Sync and push: \`sr sync && git push\``;
+}
+
+function findTargetFile(projectRoot: string): string | null {
+	for (const candidate of CANDIDATE_FILES) {
+		const fullPath = join(projectRoot, candidate);
+		if (existsSync(fullPath)) {
+			return fullPath;
+		}
+	}
+	return null;
+}
+
+function detectStatus(content: string): "missing" | "current" | "outdated" {
+	if (!hasMarkerSection(content)) return "missing";
+	// Legacy snippets used `sprout-onboard-v:N`. Always treat them as outdated so
+	// the next run upgrades them to the new schema/version markers.
+	if (content.includes(LEGACY_VERSION_MARKER_PREFIX)) return "outdated";
+	if (content.includes(SCHEMA_MARKER)) return "current";
+	return "outdated";
+}
+
+export async function run(args: string[]): Promise<void> {
+	const jsonMode = args.includes("--json");
+	const stdoutMode = args.includes("--stdout");
+	const checkMode = args.includes("--check");
+
+	const sproutDir = await findSproutDir();
+	const projectRoot = projectRootFromSproutDir(sproutDir);
+
+	const targetPath = findTargetFile(projectRoot);
+	const snippet = onboardSnippet();
+
+	// --check mode: report status only
+	if (checkMode) {
+		if (!targetPath) {
+			if (jsonMode) {
+				await outputJson({ success: true, command: "onboard", status: "missing", file: null });
+			} else {
+				console.log("Status: missing (no CLAUDE.md found)");
+			}
+			return;
+		}
+		const content = await Bun.file(targetPath).text();
+		const status = detectStatus(content);
+		if (jsonMode) {
+			await outputJson({ success: true, command: "onboard", status, file: targetPath });
+		} else {
+			console.log(`Status: ${status} (${targetPath})`);
+		}
+		return;
+	}
+
+	// --stdout mode: print what would be written
+	if (stdoutMode) {
+		process.stdout.write(wrapInMarkers(snippet));
+		process.stdout.write("\n");
+		return;
+	}
+
+	// Default mode: write to file
+	const filePath = targetPath ?? join(projectRoot, "CLAUDE.md");
+	const fileExists = existsSync(filePath);
+	const wrappedSnippet = wrapInMarkers(snippet);
+
+	if (!fileExists) {
+		await Bun.write(filePath, `${wrappedSnippet}\n`);
+		if (jsonMode) {
+			await outputJson({ success: true, command: "onboard", action: "created", file: filePath });
+		} else {
+			printSuccess(`Created ${filePath} with sprout section`);
+		}
+		return;
+	}
+
+	const content = await Bun.file(filePath).text();
+	const status = detectStatus(content);
+
+	if (status === "current") {
+		if (jsonMode) {
+			await outputJson({
+				success: true,
+				command: "onboard",
+				action: "unchanged",
+				file: filePath,
+			});
+		} else {
+			printSuccess("Sprout section is already up to date");
+		}
+		return;
+	}
+
+	if (status === "outdated") {
+		const updated = replaceMarkerSection(content, snippet);
+		if (!updated) {
+			// Defensive: detectStatus saw markers but replaceMarkerSection refused
+			// (e.g. markers out of order, truncated, or duplicated). Surface this
+			// instead of silently no-op'ing — agents need to know their snippet is stale.
+			const msg = `Found sprout markers in ${filePath} but could not replace the section (markers may be malformed, out of order, or duplicated). Fix the file manually or remove the sprout:start/sprout:end block and re-run.`;
+			if (jsonMode) {
+				await outputJson({
+					success: false,
+					command: "onboard",
+					action: "failed",
+					file: filePath,
+					error: msg,
+				});
+			} else {
+				printError(msg);
+			}
+			process.exitCode = 1;
+			return;
+		}
+		await Bun.write(filePath, updated);
+		if (jsonMode) {
+			await outputJson({
+				success: true,
+				command: "onboard",
+				action: "updated",
+				file: filePath,
+			});
+		} else {
+			printSuccess(`Updated sprout section in ${filePath}`);
+		}
+		return;
+	}
+
+	// status === "missing": append
+	const separator = content.endsWith("\n") ? "\n" : "\n\n";
+	await Bun.write(filePath, `${content}${separator}${wrappedSnippet}\n`);
+	if (jsonMode) {
+		await outputJson({ success: true, command: "onboard", action: "appended", file: filePath });
+	} else {
+		printSuccess(`Added sprout section to ${filePath}`);
+	}
+}
+
+export function register(program: Command): void {
+	program
+		.command("onboard")
+		.description("Add sprout section to CLAUDE.md / AGENTS.md")
+		.option("--stdout", "Print what would be written to stdout")
+		.option("--check", "Check status without modifying files")
+		.option("--json", "Output as JSON")
+		.action(async (opts: { stdout?: boolean; check?: boolean; json?: boolean }) => {
+			const args: string[] = [];
+			if (opts.stdout) args.push("--stdout");
+			if (opts.check) args.push("--check");
+			if (opts.json) args.push("--json");
+			await run(args);
+		});
+}

package/src/tools/sprout/commands/plan-show.ts

@@ -0,0 +1,278 @@
+import { findSproutDir, loadPlanTemplates, maxPlanDepth, readConfig } from "../config.ts";
+import { accent, brand, muted, outputJson } from "../output.ts";
+import { type ChildSummary, summarisePlanChildren } from "../plan-context.ts";
+import { readIssues, readPlans } from "../store.ts";
+import type { Issue, Plan, PlanTemplate, SectionSpec } from "../types.ts";
+
+interface PlanTreeNode {
+	plan: Plan;
+	children: ChildSummary[];
+	children_plans: PlanTreeEntry[];
+}
+
+interface PlanTreeTruncation {
+	plan_id: string;
+	truncated: true;
+	hint: string;
+}
+
+type PlanTreeEntry = PlanTreeNode | PlanTreeTruncation;
+
+function buildPlansBySeed(plans: Plan[]): Map<string, Plan> {
+	const out = new Map<string, Plan>();
+	for (const p of plans) {
+		const existing = out.get(p.seed);
+		if (!existing || existing.updatedAt < p.updatedAt) out.set(p.seed, p);
+	}
+	return out;
+}
+
+function truncationHint(planId: string): string {
+	return `depth limit reached — use \`sr plan show ${planId}\` to drill in`;
+}
+
+// PLAN_SPEC.md:340, 425, 430 — recurse through nested plans up to max_plan_depth.
+// Depth is 1-indexed: the root plan is at depth 1, nested plans start at 2.
+function buildPlanTree(
+	plan: Plan,
+	issues: Issue[],
+	plansBySeed: Map<string, Plan>,
+	depth: number,
+	maxDepth: number,
+): PlanTreeNode {
+	const childrenSummary = summarisePlanChildren(plan, issues);
+	const childrenPlans: PlanTreeEntry[] = [];
+	for (const childId of plan.children) {
+		const sub = plansBySeed.get(childId);
+		if (!sub) continue;
+		const nextDepth = depth + 1;
+		if (nextDepth > maxDepth) {
+			childrenPlans.push({
+				plan_id: sub.id,
+				truncated: true,
+				hint: truncationHint(sub.id),
+			});
+		} else {
+			childrenPlans.push(buildPlanTree(sub, issues, plansBySeed, nextDepth, maxDepth));
+		}
+	}
+	return { plan, children: childrenSummary, children_plans: childrenPlans };
+}
+
+function renderPlanSections(plan: Plan, template: PlanTemplate | undefined): void {
+	console.log(brand("Sections:"));
+	const order = ["context", "approach", "alternatives", "steps", "risks", "acceptance"];
+	const knownKeys = new Set(order);
+	const orderedKeys = [
+		...order.filter((k) => k in plan.sections),
+		...Object.keys(plan.sections).filter((k) => !knownKeys.has(k)),
+	];
+	for (const key of orderedKeys) {
+		const value = plan.sections[key];
+		const spec = template?.sections[key];
+		console.log(`  ${accent.bold(key)}`);
+		if (value === undefined || value === null) {
+			console.log(muted("    (empty)"));
+			continue;
+		}
+		if (typeof value === "string") {
+			for (const line of value.split("\n")) console.log(`    ${line}`);
+			continue;
+		}
+		if (Array.isArray(value)) {
+			if (value.length === 0) {
+				console.log(muted("    (none)"));
+				continue;
+			}
+			renderListSection(value, spec);
+			continue;
+		}
+		console.log(`    ${JSON.stringify(value)}`);
+	}
+}
+
+function renderListSection(entries: unknown[], spec: SectionSpec | undefined): void {
+	const kind = spec?.kind;
+	const itemSpec = spec?.item;
+	entries.forEach((entry, i) => {
+		const marker = `    ${i + 1}.`;
+		if (typeof entry === "string") {
+			console.log(`${marker} ${entry}`);
+			return;
+		}
+		if (kind === "steps" && isPlainRecord(entry)) {
+			renderStepEntry(marker, entry);
+			return;
+		}
+		if (kind === "list" && isPlainRecord(entry) && isItemSchema(itemSpec)) {
+			renderListEntry(marker, entry, itemSpec);
+			return;
+		}
+		console.log(`${marker} ${JSON.stringify(entry)}`);
+	});
+}
+
+function renderStepEntry(marker: string, entry: Record<string, unknown>): void {
+	const title = typeof entry.title === "string" ? entry.title : JSON.stringify(entry);
+	console.log(`${marker} ${title}`);
+	const subIndent = " ".repeat(marker.length + 1);
+	const blocks = entry.blocks;
+	if (Array.isArray(blocks) && blocks.length > 0) {
+		// blocks values are stored 1-based (sprout-185f), so render verbatim.
+		const labels = blocks
+			.map((b) => (typeof b === "number" ? String(b) : JSON.stringify(b)))
+			.join(", ");
+		console.log(`${subIndent}${muted(`blocks: ${labels}`)}`);
+	}
+	if (entry.requires_plan === true) {
+		console.log(`${subIndent}${muted("requires_plan: true")}`);
+	}
+	if (typeof entry.plan_template === "string" && entry.plan_template.length > 0) {
+		console.log(`${subIndent}${muted(`plan_template: ${entry.plan_template}`)}`);
+	}
+}
+
+function renderListEntry(
+	marker: string,
+	entry: Record<string, unknown>,
+	itemSpec: Record<string, SectionSpec>,
+): void {
+	const subIndent = " ".repeat(marker.length + 1);
+	const fieldNames = Object.keys(itemSpec);
+	let firstLineWritten = false;
+	for (const field of fieldNames) {
+		const fv = entry[field];
+		if (fv === undefined || fv === null || fv === "") continue;
+		const rendered = typeof fv === "string" ? fv : JSON.stringify(fv);
+		if (!firstLineWritten) {
+			console.log(`${marker} ${field}: ${rendered}`);
+			firstLineWritten = true;
+		} else {
+			console.log(`${subIndent}${field}: ${rendered}`);
+		}
+	}
+	if (!firstLineWritten) {
+		console.log(`${marker} ${JSON.stringify(entry)}`);
+	}
+}
+
+function isPlainRecord(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function isItemSchema(item: SectionSpec["item"]): item is Record<string, SectionSpec> {
+	return typeof item === "object" && item !== null;
+}
+
+function renderNestedPlanHuman(entry: PlanTreeEntry, indent: string): void {
+	if ("truncated" in entry) {
+		console.log(`${indent}${muted(entry.hint)}`);
+		return;
+	}
+	const { plan, children, children_plans } = entry;
+	const nameLabel = plan.name ? `  ${plan.name}` : "";
+	console.log(
+		`${indent}${brand("Sub-plan:")} ${accent.bold(plan.id)}${nameLabel}  ${muted(`[${plan.status}]`)}  ${muted(`rev ${plan.revision}`)}  ${muted(`seed=${plan.seed}`)}`,
+	);
+	console.log(`${indent}${muted(`Children (${children.length}):`)}`);
+	const childIndent = `${indent}  `;
+	if (children.length === 0) {
+		console.log(`${childIndent}${muted("(none)")}`);
+	} else {
+		for (const c of children) {
+			const tag = c.adopted ? ` ${muted("(adopted)")}` : "";
+			console.log(`${childIndent}${accent(c.id)}  ${muted(`[${c.status}]`)}  ${c.title}${tag}`);
+		}
+	}
+	for (const sub of children_plans) {
+		console.log("");
+		renderNestedPlanHuman(sub, childIndent);
+	}
+}
+
+// Accept either a plan id (pl-xxxx) or a seed id; sprout resolve through
+// seed.plan_id (PLAN_SPEC contract: "the seed knows its plan"). The shared
+// helper keeps show/validate/outcome/review consistent so an agent that has a
+// seed id in hand never has to round-trip through `sr plan list` for the
+// pl-xxxx token.
+export async function resolvePlanIdArg(arg: string, dir: string): Promise<string> {
+	if (arg.startsWith("pl-")) return arg;
+	const issues = await readIssues(dir);
+	const seed = issues.find((i) => i.id === arg);
+	if (!seed) {
+		throw new Error(`Plan not found: ${arg}. Run 'sr plan list' to see available plans.`);
+	}
+	if (!seed.plan_id) {
+		throw new Error(
+			`Seed ${arg} has no plan. Submit one with 'sr plan submit ${arg} --plan <file>'.`,
+		);
+	}
+	return seed.plan_id;
+}
+
+export async function runShow(idArg: string, jsonMode: boolean): Promise<void> {
+	const dir = await findSproutDir();
+	const planId = await resolvePlanIdArg(idArg, dir);
+	const config = await readConfig(dir);
+	const maxDepth = maxPlanDepth(config);
+	const plans = await readPlans(dir);
+	const plan = plans.find((p) => p.id === planId);
+	if (!plan) {
+		throw new Error(`Plan not found: ${planId}. Run 'sr plan list' to see available plans.`);
+	}
+	const issues = await readIssues(dir);
+	const plansBySeed = buildPlansBySeed(plans);
+	const tree = buildPlanTree(plan, issues, plansBySeed, 1, maxDepth);
+	const templates = await loadPlanTemplates(dir);
+	const template = templates[plan.template];
+
+	if (jsonMode) {
+		await outputJson({
+			success: true,
+			command: "plan show",
+			plan,
+			children: tree.children,
+			children_plans: tree.children_plans,
+		});
+		return;
+	}
+
+	console.log(`${accent.bold(plan.id)}  ${brand(plan.status)}  ${muted(`rev ${plan.revision}`)}`);
+	if (plan.name) console.log(`Name:     ${plan.name}`);
+	console.log(`Seed:     ${accent(plan.seed)}`);
+	console.log(`Template: ${plan.template}`);
+	console.log(`Created:  ${muted(plan.createdAt)}`);
+	console.log(`Updated:  ${muted(plan.updatedAt)}`);
+	if (plan.outcome) {
+		const note = plan.outcomeNote ? ` — ${plan.outcomeNote}` : "";
+		console.log(`Outcome:  ${plan.outcome}${note}`);
+	}
+	// PLAN_SPEC.md:404-413 — review hint is purely cosmetic and only relevant
+	// while a plan is awaiting work or in flight.
+	const reviewActionable = plan.status === "approved" || plan.status === "active";
+	if (!plan.reviewedBy && reviewActionable) {
+		console.log(muted("Review suggested (no reviewer recorded yet)"));
+	}
+	if (plan.reviewedBy) {
+		console.log(`Reviewed: ${plan.reviewedBy}`);
+	}
+
+	console.log("");
+	renderPlanSections(plan, template);
+
+	console.log("");
+	console.log(brand(`Children (${tree.children.length}):`));
+	if (tree.children.length === 0) {
+		console.log(muted("  (none)"));
+	} else {
+		for (const c of tree.children) {
+			const tag = c.adopted ? ` ${muted("(adopted)")}` : "";
+			console.log(`  ${accent(c.id)}  ${muted(`[${c.status}]`)}  ${c.title}${tag}`);
+		}
+	}
+
+	for (const sub of tree.children_plans) {
+		console.log("");
+		renderNestedPlanHuman(sub, "  ");
+	}
+}