@ag-eco/agentplate-cli 0.13.0

package/src/tools/sprout/index.ts

@@ -0,0 +1,204 @@
+#!/usr/bin/env bun
+import chalk from "chalk";
+import { Command, Help } from "commander";
+import { brand, muted, setQuiet } from "./output.ts";
+import { VERSION } from "./version.ts";
+
+export { VERSION };
+
+// Apply quiet mode early so it affects all output during command execution
+const rawArgs = process.argv.slice(2);
+if (rawArgs.includes("--quiet") || rawArgs.includes("-q")) {
+	setQuiet(true);
+}
+
+const program = new Command();
+
+program
+	.name("sr")
+	.description("sprout — git-native issue tracker")
+	.version(VERSION, "-v, --version", "Print version")
+	.option("-q, --quiet", "Suppress non-error output")
+	.option("--verbose", "Extra diagnostic output")
+	.option("--timing", "Show command execution time")
+	.addHelpCommand(false)
+	.configureHelp({
+		formatHelp(cmd: Command, helper: Help): string {
+			if (cmd.parent) {
+				return Help.prototype.formatHelp.call(helper, cmd, helper);
+			}
+			const header = `${brand(chalk.bold("sprout"))} ${muted(`v${VERSION}`)} — Git-native issue tracking\n\nUsage: sr <command> [options]`;
+
+			const cmdLines: string[] = ["\nCommands:"];
+			for (const sub of cmd.commands) {
+				const name = sub.name();
+				const argStr = sub.registeredArguments
+					.map((a) => (a.required ? `<${a.name()}>` : `[${a.name()}]`))
+					.join(" ");
+				const rawEntry = argStr ? `${name} ${argStr}` : name;
+				const colored = argStr ? `${chalk.green(name)} ${chalk.dim(argStr)}` : chalk.green(name);
+				const pad = " ".repeat(Math.max(18 - rawEntry.length, 2));
+				cmdLines.push(`  ${colored}${pad}${sub.description()}`);
+			}
+
+			const opts: [string, string][] = [
+				["-h, --help", "Show help"],
+				["-v, --version", "Print version"],
+				["--format <mode>", "Output format (markdown|compact|plain|ids|json)"],
+				["--json", "Alias for --format json"],
+				["-q, --quiet", "Suppress non-error output"],
+				["--verbose", "Extra diagnostic output"],
+				["--timing", "Show command execution time"],
+			];
+			const optLines: string[] = ["\nOptions:"];
+			for (const [flag, desc] of opts) {
+				const pad = " ".repeat(Math.max(18 - flag.length, 2));
+				optLines.push(`  ${chalk.dim(flag)}${pad}${desc}`);
+			}
+
+			const footer = `\nRun '${chalk.dim("sr")} <command> --help' for command-specific help.`;
+
+			return `${[header, ...cmdLines, ...optLines, footer].join("\n")}\n`;
+		},
+	});
+
+// --timing: measure command execution time
+let timingStart = 0;
+program.hook("preAction", () => {
+	if (program.opts().timing) {
+		timingStart = performance.now();
+	}
+});
+program.hook("postAction", () => {
+	if (program.opts().timing) {
+		const elapsed = performance.now() - timingStart;
+		const formatted =
+			elapsed < 1000 ? `${Math.round(elapsed)}ms` : `${(elapsed / 1000).toFixed(2)}s`;
+		process.stderr.write(`${muted(`⏱ ${formatted}`)}\n`);
+	}
+});
+
+// Lazy-load and register all commands
+async function registerAll(): Promise<void> {
+	const mods = await Promise.all([
+		import("./commands/init.ts"),
+		import("./commands/create.ts"),
+		import("./commands/show.ts"),
+		import("./commands/list.ts"),
+		import("./commands/ready.ts"),
+		import("./commands/search.ts"),
+		import("./commands/update.ts"),
+		import("./commands/close.ts"),
+		import("./commands/dep.ts"),
+		import("./commands/label.ts"),
+		import("./commands/blocked.ts"),
+		import("./commands/stats.ts"),
+		import("./commands/sync.ts"),
+		import("./commands/doctor.ts"),
+		import("./commands/tpl.ts"),
+		import("./commands/migrate.ts"),
+		import("./commands/prime.ts"),
+		import("./commands/onboard.ts"),
+		import("./commands/upgrade.ts"),
+		import("./commands/completions.ts"),
+		import("./commands/block.ts"),
+		import("./commands/unblock.ts"),
+		import("./commands/plan.ts"),
+		import("./commands/config.ts"),
+	]);
+
+	for (const mod of mods) {
+		mod.register(program);
+	}
+}
+
+function levenshtein(a: string, b: string): number {
+	const m = a.length;
+	const n = b.length;
+	if (m === 0) return n;
+	if (n === 0) return m;
+	let prev: number[] = Array.from({ length: n + 1 }, (_, j) => j);
+	for (let i = 1; i <= m; i++) {
+		const curr: number[] = [i];
+		for (let j = 1; j <= n; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+			const left = curr[j - 1] ?? 0;
+			const up = prev[j] ?? 0;
+			const diag = prev[j - 1] ?? 0;
+			curr.push(Math.min(left + 1, up + 1, diag + cost));
+		}
+		prev = curr;
+	}
+	return prev[n] ?? 0;
+}
+
+async function main(): Promise<void> {
+	// Handle --version --json before Commander processes the flag
+	if ((rawArgs.includes("-v") || rawArgs.includes("--version")) && rawArgs.includes("--json")) {
+		const platform = `${process.platform}-${process.arch}`;
+		console.log(
+			JSON.stringify({ name: "@ag-eco/sprout-cli", version: VERSION, runtime: "bun", platform }),
+		);
+		process.exitCode = 0;
+		return;
+	}
+
+	await registerAll();
+
+	// Check for unknown commands before parsing
+	const firstArg = process.argv[2];
+	if (firstArg && !firstArg.startsWith("-")) {
+		const knownNames = program.commands.map((c) => c.name());
+		if (!knownNames.includes(firstArg)) {
+			let best = "";
+			let bestDist = Number.POSITIVE_INFINITY;
+			for (const name of knownNames) {
+				const d = levenshtein(firstArg, name);
+				if (d < bestDist) {
+					bestDist = d;
+					best = name;
+				}
+			}
+			const suggestion = bestDist <= 2 ? best : "";
+			const errMsg = suggestion
+				? `Unknown command: ${firstArg}. Did you mean ${suggestion}?`
+				: `Unknown command: ${firstArg}`;
+			if (jsonMode) {
+				const payload: Record<string, unknown> = {
+					success: false,
+					command: firstArg,
+					error: errMsg,
+				};
+				if (suggestion) payload.suggestion = suggestion;
+				await Bun.write(Bun.stdout, `${JSON.stringify(payload)}\n`);
+			} else {
+				process.stderr.write(`${errMsg}\n`);
+			}
+			process.exitCode = 1;
+			return;
+		}
+	}
+
+	await program.parseAsync(process.argv);
+}
+
+const jsonMode = process.argv.includes("--json");
+
+main().catch(async (err: unknown) => {
+	const msg = err instanceof Error ? err.message : String(err);
+	const cmd = process.argv[2];
+	// Route the structured error (with stack) through pino for observability.
+	// Lazy-imported so the happy path never constructs a logger; silent at the
+	// default `info` level and surfaces under SPROUT_DEBUG=1.
+	const { log } = await import("./log.ts");
+	log.debug({ err, cmd }, "command failed");
+	if (jsonMode) {
+		await Bun.write(
+			Bun.stdout,
+			`${JSON.stringify({ success: false, command: cmd, error: msg })}\n`,
+		);
+	} else {
+		console.error(chalk.red(`Error: ${msg}`));
+	}
+	process.exitCode = 1;
+});

package/src/tools/sprout/log.ts

@@ -0,0 +1,76 @@
+/**
+ * Structured logging for the sprout CLI (pino).
+ *
+ * This is the observability channel — diagnostic/debug output that survives as
+ * machine-parseable NDJSON in CI and non-TTY contexts, and renders prettily in
+ * an interactive shell. It is NOT the user-output channel: deliberate,
+ * chalk-formatted CLI prints live in `src/output.ts` and must stay there.
+ *
+ * Level resolution lives inside `createLog()` (never read at module top) so
+ * tests can override `process.env` and re-create a logger deterministically:
+ *   - explicit `SPROUT_LOG_LEVEL` wins,
+ *   - `SPROUT_DEBUG === "1"` flips the default to `debug`,
+ *   - otherwise `info`.
+ *
+ * Sensitive values are scrubbed via pino `redact` with `remove: true` (the key
+ * is dropped, not masked) before any line reaches stdout.
+ */
+
+import pino from "pino";
+
+export type Logger = pino.Logger;
+
+export interface CreateLogOptions {
+	level?: pino.Level;
+	/** Force pretty (true) or NDJSON (false). Defaults to TTY auto-detection. */
+	pretty?: boolean;
+	/** Custom sink — bypasses the pretty transport (used by tests). */
+	destination?: pino.DestinationStream;
+}
+
+// Paths whose values never belong in logs. Bare keys cover top-level fields;
+// `*.<key>` wildcards cover one level of nesting (e.g. `req.token`). Mirrors
+// burrow's redact policy. Documented in AGENTS.md (redact policy).
+export const REDACT_PATHS: readonly string[] = [
+	"password",
+	"token",
+	"apiKey",
+	"secret",
+	"authorization",
+	"*.password",
+	"*.token",
+	"*.apiKey",
+	"*.secret",
+	"*.authorization",
+	"headers.cookie",
+	"headers.authorization",
+];
+
+function resolveLevel(): pino.Level {
+	const explicit = process.env.SPROUT_LOG_LEVEL as pino.Level | undefined;
+	if (explicit) return explicit;
+	if (process.env.SPROUT_DEBUG === "1") return "debug";
+	return "info";
+}
+
+export function createLog(options: CreateLogOptions = {}): Logger {
+	const level = options.level ?? resolveLevel();
+	const pretty = options.pretty ?? process.stdout.isTTY === true;
+
+	const base: pino.LoggerOptions = {
+		level,
+		redact: { paths: [...REDACT_PATHS], remove: true },
+	};
+
+	if (pretty && !options.destination) {
+		base.transport = {
+			target: "pino-pretty",
+			options: { colorize: true, translateTime: "SYS:HH:MM:ss.l" },
+		};
+		return pino(base);
+	}
+
+	return options.destination ? pino(base, options.destination) : pino(base);
+}
+
+export const log: Logger = createLog();

package/src/tools/sprout/markers.ts

@@ -0,0 +1,22 @@
+export const START_MARKER = "<!-- sprout:start -->";
+export const END_MARKER = "<!-- sprout:end -->";
+
+export function hasMarkerSection(content: string): boolean {
+	return content.includes(START_MARKER) && content.includes(END_MARKER);
+}
+
+export function replaceMarkerSection(content: string, newSection: string): string | null {
+	const startIdx = content.indexOf(START_MARKER);
+	const endIdx = content.indexOf(END_MARKER);
+	if (startIdx === -1 || endIdx === -1) return null;
+	// Markers present but out of order (END before START) means the file was
+	// hand-edited into a broken state. Refuse rather than emit garbage.
+	if (endIdx < startIdx) return null;
+	const before = content.slice(0, startIdx);
+	const after = content.slice(endIdx + END_MARKER.length);
+	return before + wrapInMarkers(newSection) + after;
+}
+
+export function wrapInMarkers(section: string): string {
+	return `${START_MARKER}\n${section}\n${END_MARKER}`;
+}

package/src/tools/sprout/output.ts

@@ -0,0 +1,121 @@
+import chalk from "chalk";
+import { stripAnsi } from "./format.ts";
+import type { Issue } from "./types.ts";
+import { PRIORITY_LABELS } from "./types.ts";
+
+// Forest palette
+export const brand = chalk.rgb(124, 179, 66);
+export const accent = chalk.rgb(255, 183, 77);
+export const muted = chalk.rgb(120, 120, 110);
+
+let _quiet = false;
+
+export function setQuiet(v: boolean): void {
+	_quiet = v;
+}
+
+export async function outputJson(data: unknown): Promise<void> {
+	await Bun.write(Bun.stdout, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+export function printSuccess(msg: string): void {
+	if (_quiet) return;
+	console.log(`${brand("✓")} ${brand(msg)}`);
+}
+
+export function printError(msg: string): void {
+	console.error(`${chalk.red("✗")} ${msg}`);
+}
+
+export function printWarning(msg: string): void {
+	if (_quiet) return;
+	console.error(`${chalk.yellow("!")} ${msg}`);
+}
+
+// An issue is *effectively* blocked when at least one entry in `blockedBy`
+// references a still-open issue. When `closedBlockerIds` is omitted, fall back
+// to the legacy length-based heuristic for callers that haven't threaded the
+// set through yet.
+function isEffectivelyBlocked(issue: Issue, closedBlockerIds?: Set<string>): boolean {
+	const blockers = issue.blockedBy ?? [];
+	if (blockers.length === 0) return false;
+	if (!closedBlockerIds) return true;
+	return blockers.some((bid) => !closedBlockerIds.has(bid));
+}
+
+export function formatIssueOneLine(issue: Issue, closedBlockerIds?: Set<string>): string {
+	const isBlocked = isEffectivelyBlocked(issue, closedBlockerIds);
+	const statusIcon =
+		issue.status === "closed"
+			? muted("x")
+			: issue.status === "in_progress"
+				? chalk.cyan(">")
+				: isBlocked
+					? chalk.yellow("!")
+					: brand("-");
+	const priorityLabel = PRIORITY_LABELS[issue.priority] ?? String(issue.priority);
+	const assignee = issue.assignee ? ` · ${muted(`@${issue.assignee}`)}` : "";
+	const blocked = isBlocked ? ` ${chalk.yellow("[blocked]")}` : "";
+	const labelStr = issue.labels?.length ? ` ${muted(`{${issue.labels.join(", ")}}`)}` : "";
+	return `${statusIcon} ${accent.bold(issue.id)} · ${issue.title}   ${muted(`[${priorityLabel} · ${issue.type}]`)}${assignee}${blocked}${labelStr}`;
+}
+
+export function formatIssueOneLineCompact(issue: Issue, closedBlockerIds?: Set<string>): string {
+	const priorityLabel = PRIORITY_LABELS[issue.priority] ?? String(issue.priority);
+	const isBlocked = isEffectivelyBlocked(issue, closedBlockerIds);
+	const status = isBlocked ? "blocked" : issue.status;
+	return `${issue.id} ${priorityLabel} ${status} ${issue.title}`;
+}
+
+export function printIssueOneLine(issue: Issue, closedBlockerIds?: Set<string>): void {
+	if (_quiet) return;
+	console.log(formatIssueOneLine(issue, closedBlockerIds));
+}
+
+// Render Issue.extensions as a single "Extensions: key=value ..." line.
+// Each value is JSON-encoded so the rendering round-trips unambiguously
+// (strings stay quoted; objects/arrays/null print as JSON literals).
+// Returns null when extensions is missing or has no own keys.
+export function formatExtensionsLine(ext: Record<string, unknown> | undefined): string | null {
+	if (!ext) return null;
+	const keys = Object.keys(ext);
+	if (keys.length === 0) return null;
+	const pairs = keys.map((k) => `${accent(k)}=${muted(JSON.stringify(ext[k]))}`);
+	return `Extensions: ${pairs.join(" ")}`;
+}
+
+export function formatIssueFull(issue: Issue): string {
+	const statusColor =
+		issue.status === "closed" ? muted : issue.status === "in_progress" ? chalk.cyan : brand;
+	const priorityLabel = PRIORITY_LABELS[issue.priority] ?? String(issue.priority);
+
+	const lines: string[] = [];
+	lines.push(`${accent.bold(issue.id)}  ${statusColor(issue.status)}`);
+	lines.push(`Title:    ${issue.title}`);
+	lines.push(`Type:     ${muted(issue.type)}   Priority: ${muted(priorityLabel)}`);
+	if (issue.assignee) lines.push(`Assignee: ${issue.assignee}`);
+	if (issue.labels?.length)
+		lines.push(`Labels:   ${issue.labels.map((l) => accent(l)).join(", ")}`);
+	const extLine = formatExtensionsLine(issue.extensions);
+	if (extLine) lines.push(extLine);
+	if (issue.description) lines.push(`\n${issue.description}`);
+	if (issue.blockedBy?.length)
+		lines.push(`Blocked by: ${issue.blockedBy.map((id) => accent(id)).join(", ")}`);
+	if (issue.blocks?.length)
+		lines.push(`Blocks:     ${issue.blocks.map((id) => accent(id)).join(", ")}`);
+	if (issue.convoy) lines.push(`Convoy:   ${muted(issue.convoy)}`);
+	if (issue.closeReason) lines.push(`Reason:   ${issue.closeReason}`);
+	lines.push(`Created:  ${muted(issue.createdAt)}`);
+	lines.push(`Updated:  ${muted(issue.updatedAt)}`);
+	if (issue.closedAt) lines.push(`Closed:   ${muted(issue.closedAt)}`);
+	return lines.join("\n");
+}
+
+export function printIssueFull(issue: Issue): void {
+	if (_quiet) return;
+	console.log(formatIssueFull(issue));
+}
+
+export function plain(s: string): string {
+	return stripAnsi(s);
+}

package/src/tools/sprout/plan-backref.ts

@@ -0,0 +1,93 @@
+// sprout-76af: child sprout spawned by `sr plan submit` carry a backref block in
+// description so an agent picking one up cold has the framing the plan author
+// already wrote down — without having to navigate plan_id → parent → plan.
+
+export const BACKREF_START = "<!-- sprout:plan-backref:start -->";
+export const BACKREF_END = "<!-- sprout:plan-backref:end -->";
+
+const APPROACH_EXCERPT_MAX = 240;
+
+export interface BackrefArgs {
+	// 0-based step index in plan.sections.steps. Omit for loose adoptions
+	// (sr plan adopt without --step) where the seed has no step anchor.
+	stepIndex?: number;
+	planId: string;
+	parentSeedId: string;
+	parentSeedTitle: string;
+	templateName: string;
+	approach: unknown;
+}
+
+export function buildPlanBackref(args: BackrefArgs): string {
+	const lines: string[] = [];
+	if (args.stepIndex !== undefined) {
+		lines.push(`Step ${args.stepIndex + 1} of plan ${args.planId}.`);
+	} else {
+		lines.push(`Adopted into plan ${args.planId}.`);
+	}
+	lines.push("");
+	lines.push(`Parent seed: ${args.parentSeedId} — ${args.parentSeedTitle}`);
+	lines.push(`Plan template: ${args.templateName}`);
+	const excerpt = approachExcerpt(args.approach);
+	if (excerpt) lines.push(`Plan approach: ${excerpt}`);
+	lines.push("");
+	lines.push(
+		`Run \`sr plan show ${args.planId}\` for the full plan (context, alternatives, sibling steps, acceptance criteria).`,
+	);
+	const body = lines.join("\n");
+	return `${BACKREF_START}\n${body}\n${BACKREF_END}`;
+}
+
+// Replace the marker section if present; otherwise, prepend a fresh section in
+// front of the existing description so manual notes survive plan overwrite.
+export function applyPlanBackref(existing: string | undefined, args: BackrefArgs): string {
+	const block = buildPlanBackref(args);
+	const prior = existing ?? "";
+	if (hasBackrefMarkers(prior)) {
+		return replaceBackrefSection(prior, block);
+	}
+	if (prior.trim().length === 0) return block;
+	return `${block}\n\n${prior}`;
+}
+
+// Inverse of applyPlanBackref: strip the marker-delimited block so a released
+// seed loses its plan framing. Manual notes wrapping the block are preserved;
+// whitespace at the new boundary is collapsed. Returns undefined when nothing
+// but the block remained, so the caller can drop the field entirely.
+export function stripPlanBackref(existing: string | undefined): string | undefined {
+	if (existing === undefined) return undefined;
+	if (!hasBackrefMarkers(existing)) return existing;
+	const startIdx = existing.indexOf(BACKREF_START);
+	const endIdx = existing.indexOf(BACKREF_END);
+	if (startIdx === -1 || endIdx === -1) return existing;
+	const before = existing.slice(0, startIdx).replace(/\s*$/, "");
+	const after = existing.slice(endIdx + BACKREF_END.length).replace(/^\s*/, "");
+	if (before.length === 0 && after.length === 0) return undefined;
+	if (before.length === 0) return after;
+	if (after.length === 0) return before;
+	return `${before}\n\n${after}`;
+}
+
+function hasBackrefMarkers(s: string): boolean {
+	return s.includes(BACKREF_START) && s.includes(BACKREF_END);
+}
+
+function replaceBackrefSection(existing: string, block: string): string {
+	const startIdx = existing.indexOf(BACKREF_START);
+	const endIdx = existing.indexOf(BACKREF_END);
+	if (startIdx === -1 || endIdx === -1) return block;
+	const before = existing.slice(0, startIdx);
+	const after = existing.slice(endIdx + BACKREF_END.length);
+	return `${before}${block}${after}`;
+}
+
+function approachExcerpt(value: unknown): string {
+	if (typeof value !== "string") return "";
+	const collapsed = value.replace(/\s+/g, " ").trim();
+	if (collapsed.length === 0) return "";
+	if (collapsed.length <= APPROACH_EXCERPT_MAX) return collapsed;
+	const slice = collapsed.slice(0, APPROACH_EXCERPT_MAX);
+	const lastSpace = slice.lastIndexOf(" ");
+	const cut = lastSpace > APPROACH_EXCERPT_MAX / 2 ? slice.slice(0, lastSpace) : slice;
+	return `${cut.trimEnd()}…`;
+}

package/src/tools/sprout/plan-context.ts

@@ -0,0 +1,81 @@
+// Shared plan-awareness helpers for ready/show/list integration
+// (PLAN_SPEC.md:154-156). Each consumer reads plans + issues once and uses
+// these helpers to look up plan state and render hints/summaries.
+
+import { accent, muted } from "./output.ts";
+import { readPlans } from "./store.ts";
+import type { Issue, Plan } from "./types.ts";
+
+export interface PlanContext {
+	plansById: Map<string, Plan>;
+	plansBySeed: Map<string, Plan>;
+}
+
+export async function loadPlanContext(sproutDir: string): Promise<PlanContext> {
+	const plans = await readPlans(sproutDir);
+	const plansById = new Map(plans.map((p) => [p.id, p]));
+	const plansBySeed = new Map<string, Plan>();
+	for (const p of plans) {
+		// If multiple plans exist for the same seed (would only happen via prior
+		// drafts), prefer the most-recently-updated one for surfacing.
+		const existing = plansBySeed.get(p.seed);
+		if (!existing || existing.updatedAt < p.updatedAt) plansBySeed.set(p.seed, p);
+	}
+	return { plansById, plansBySeed };
+}
+
+export function planForIssue(ctx: PlanContext, issue: Issue): Plan | undefined {
+	if (!issue.plan_id) return undefined;
+	return ctx.plansById.get(issue.plan_id);
+}
+
+// Human-readable suffix appended to one-line issue formatting in list/ready.
+export function planLineSuffix(plan: Plan | undefined): string {
+	if (!plan) return "";
+	if (plan.status === "draft") {
+		return ` ${accent("[plan in draft — run sr plan submit]")}`;
+	}
+	return ` ${muted(`[plan ${plan.status}]`)}`;
+}
+
+// Returns true if `sr ready` should surface this seed regardless of normal
+// blocker checks. Planning takes precedence over implementation when a seed
+// has a draft plan attached.
+export function isPlanDraftBlocking(plan: Plan | undefined): boolean {
+	return plan?.status === "draft";
+}
+
+export interface ChildSummary {
+	id: string;
+	title: string;
+	status: string;
+	adopted: boolean;
+}
+
+// Shared --json shape used by list/ready/search/blocked when surfacing an
+// issue that has a plan attached. Returns the issue unchanged when there is
+// no plan, so the JSON payload remains a strict superset (no key churn for
+// plan-less issues).
+export function issueJsonWithPlan(
+	issue: Issue,
+	plan: Plan | undefined,
+): Issue & {
+	plan_status?: string;
+	plan_children?: string[];
+} {
+	if (!plan) return issue;
+	return { ...issue, plan_status: plan.status, plan_children: plan.children };
+}
+
+export function summarisePlanChildren(plan: Plan, issues: Issue[]): ChildSummary[] {
+	const adoptedSet = new Set(plan.adoptedChildren ?? []);
+	return plan.children.map((id) => {
+		const issue = issues.find((i) => i.id === id);
+		return {
+			id,
+			title: issue?.title ?? "(missing)",
+			status: issue?.status ?? "missing",
+			adopted: adoptedSet.has(id),
+		};
+	});
+}