@ag-eco/agentplate-cli 0.13.0

package/src/tools/sprout/store.ts

@@ -0,0 +1,172 @@
+import { randomBytes } from "node:crypto";
+import { closeSync, openSync, renameSync, statSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import type { Issue, Plan, Template } from "./types.ts";
+import {
+	ISSUES_FILE,
+	LOCK_RETRY_MS,
+	LOCK_STALE_MS,
+	LOCK_TIMEOUT_MS,
+	PLANS_FILE,
+	TEMPLATES_FILE,
+} from "./types.ts";
+
+function lockFilePath(dataFilePath: string): string {
+	return `${dataFilePath}.lock`;
+}
+
+async function acquireLock(dataFilePath: string): Promise<void> {
+	const lock = lockFilePath(dataFilePath);
+	const start = Date.now();
+	while (true) {
+		try {
+			const fd = openSync(lock, "wx");
+			closeSync(fd);
+			return;
+		} catch (err: unknown) {
+			const nodeErr = err as NodeJS.ErrnoException;
+			if (nodeErr.code !== "EEXIST") throw err;
+			// Check if stale
+			try {
+				const st = statSync(lock);
+				if (Date.now() - st.mtimeMs > LOCK_STALE_MS) {
+					unlinkSync(lock);
+					continue;
+				}
+			} catch {
+				continue;
+			}
+			if (Date.now() - start > LOCK_TIMEOUT_MS) {
+				throw new Error(`Timeout acquiring lock for ${dataFilePath}`);
+			}
+			await sleep(LOCK_RETRY_MS + Math.floor(Math.random() * LOCK_RETRY_MS));
+		}
+	}
+}
+
+function releaseLock(dataFilePath: string): void {
+	try {
+		unlinkSync(lockFilePath(dataFilePath));
+	} catch {
+		// best-effort
+	}
+}
+
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export async function withLock<T>(dataFilePath: string, fn: () => Promise<T>): Promise<T> {
+	await acquireLock(dataFilePath);
+	try {
+		return await fn();
+	} finally {
+		releaseLock(dataFilePath);
+	}
+}
+
+function parseJsonl<T>(content: string): T[] {
+	const results: T[] = [];
+	for (const line of content.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		try {
+			results.push(JSON.parse(trimmed) as T);
+		} catch {
+			// skip malformed lines
+		}
+	}
+	return results;
+}
+
+function deduplicateById<T extends { id: string }>(items: T[]): T[] {
+	const map = new Map<string, T>();
+	for (const item of items) {
+		map.set(item.id, item); // last occurrence wins
+	}
+	return Array.from(map.values());
+}
+
+export async function readIssues(sproutDir: string): Promise<Issue[]> {
+	const file = Bun.file(join(sproutDir, ISSUES_FILE));
+	if (!(await file.exists())) return [];
+	const content = await file.text();
+	return deduplicateById(parseJsonl<Issue>(content));
+}
+
+export async function writeIssues(sproutDir: string, issues: Issue[]): Promise<void> {
+	const filePath = join(sproutDir, ISSUES_FILE);
+	const tmpPath = `${filePath}.tmp.${randomBytes(4).toString("hex")}`;
+	const content = `${issues.map((i) => JSON.stringify(i)).join("\n")}\n`;
+	await Bun.write(tmpPath, content);
+	renameSync(tmpPath, filePath);
+}
+
+export async function appendIssue(sproutDir: string, issue: Issue): Promise<void> {
+	const filePath = join(sproutDir, ISSUES_FILE);
+	const tmpPath = `${filePath}.tmp.${randomBytes(4).toString("hex")}`;
+	const file = Bun.file(filePath);
+	const existing = (await file.exists()) ? await file.text() : "";
+	await Bun.write(tmpPath, `${existing + JSON.stringify(issue)}\n`);
+	renameSync(tmpPath, filePath);
+}
+
+export async function readTemplates(sproutDir: string): Promise<Template[]> {
+	const file = Bun.file(join(sproutDir, TEMPLATES_FILE));
+	if (!(await file.exists())) return [];
+	const content = await file.text();
+	return deduplicateById(parseJsonl<Template>(content));
+}
+
+export async function writeTemplates(sproutDir: string, templates: Template[]): Promise<void> {
+	const filePath = join(sproutDir, TEMPLATES_FILE);
+	const tmpPath = `${filePath}.tmp.${randomBytes(4).toString("hex")}`;
+	const content = `${templates.map((t) => JSON.stringify(t)).join("\n")}\n`;
+	await Bun.write(tmpPath, content);
+	renameSync(tmpPath, filePath);
+}
+
+export async function appendTemplate(sproutDir: string, template: Template): Promise<void> {
+	const filePath = join(sproutDir, TEMPLATES_FILE);
+	const tmpPath = `${filePath}.tmp.${randomBytes(4).toString("hex")}`;
+	const file = Bun.file(filePath);
+	const existing = (await file.exists()) ? await file.text() : "";
+	await Bun.write(tmpPath, `${existing + JSON.stringify(template)}\n`);
+	renameSync(tmpPath, filePath);
+}
+
+export function issuesPath(sproutDir: string): string {
+	return join(sproutDir, ISSUES_FILE);
+}
+
+export function templatesPath(sproutDir: string): string {
+	return join(sproutDir, TEMPLATES_FILE);
+}
+
+export function plansPath(sproutDir: string): string {
+	return join(sproutDir, PLANS_FILE);
+}
+
+export async function readPlans(sproutDir: string): Promise<Plan[]> {
+	const file = Bun.file(join(sproutDir, PLANS_FILE));
+	if (!(await file.exists())) return [];
+	const content = await file.text();
+	return deduplicateById(parseJsonl<Plan>(content));
+}
+
+export async function writePlans(sproutDir: string, plans: Plan[]): Promise<void> {
+	const filePath = join(sproutDir, PLANS_FILE);
+	const tmpPath = `${filePath}.tmp.${randomBytes(4).toString("hex")}`;
+	const content = `${plans.map((p) => JSON.stringify(p)).join("\n")}\n`;
+	await Bun.write(tmpPath, content);
+	renameSync(tmpPath, filePath);
+}
+
+export async function appendPlan(sproutDir: string, plan: Plan): Promise<void> {
+	const filePath = join(sproutDir, PLANS_FILE);
+	const tmpPath = `${filePath}.tmp.${randomBytes(4).toString("hex")}`;
+	const file = Bun.file(filePath);
+	const existing = (await file.exists()) ? await file.text() : "";
+	await Bun.write(tmpPath, `${existing + JSON.stringify(plan)}\n`);
+	renameSync(tmpPath, filePath);
+}

package/src/tools/sprout/types.ts

@@ -0,0 +1,118 @@
+export interface Issue {
+	id: string;
+	title: string;
+	status: "open" | "in_progress" | "closed";
+	type: "task" | "bug" | "feature" | "epic";
+	priority: number;
+	assignee?: string;
+	description?: string;
+	closeReason?: string;
+	blocks?: string[];
+	blockedBy?: string[];
+	labels?: string[];
+	convoy?: string;
+	plan_id?: string;
+	plan_step_index?: number;
+	requires_plan?: boolean;
+	extensions?: Record<string, unknown>;
+	createdAt: string;
+	updatedAt: string;
+	closedAt?: string;
+}
+
+export type PlanStatus = "draft" | "approved" | "active" | "done";
+export type PlanOutcome = "success" | "partial" | "failure";
+
+export interface Plan {
+	id: string;
+	seed: string;
+	template: string;
+	name?: string;
+	status: PlanStatus;
+	revision: number;
+	sections: Record<string, unknown>;
+	children: string[];
+	// Subset of `children` that were attached via adoption (existing_seed at
+	// submit time, or `sr plan adopt` post-submit) rather than fresh-spawned by
+	// the plan. Drives the "(adopted)" tag in `sr plan show` human output and
+	// is preserved across overwrites for children that survive the rewrite.
+	adoptedChildren?: string[];
+	outcome?: PlanOutcome;
+	outcomeNote?: string;
+	reviewedBy?: string;
+	createdAt: string;
+	updatedAt: string;
+}
+
+export interface TemplateStep {
+	title: string;
+	type?: string;
+	priority?: number;
+	plan_template?: string;
+}
+
+export interface Template {
+	id: string;
+	name: string;
+	steps: TemplateStep[];
+}
+
+export interface Config {
+	project: string;
+	version: string;
+	max_plan_depth?: number;
+}
+
+// PLAN_SPEC.md:430 — display-only depth limit for `sr plan show` recursion.
+export const DEFAULT_MAX_PLAN_DEPTH = 3;
+
+// Plan template config — what `plan_templates:` in config.yaml resolves to.
+// Compiled into AJV schema by src/plan-schema.ts (Phase 2 task sprout-6bd8).
+export type SectionKindLiteral = "text" | "list" | "steps";
+
+export interface SectionSpec {
+	required: boolean;
+	kind: SectionKindLiteral | Record<string, SectionSpec>;
+	prompt: string;
+	min_length?: number;
+	min?: number;
+	item?: "text" | Record<string, SectionSpec>;
+	loam_source?: string;
+}
+
+export interface PlanTemplate {
+	name: string;
+	description?: string;
+	sections: Record<string, SectionSpec>;
+}
+
+export const SECTION_KINDS: readonly SectionKindLiteral[] = ["text", "list", "steps"] as const;
+
+export interface ConvoyStatus {
+	templateId: string;
+	total: number;
+	completed: number;
+	inProgress: number;
+	blocked: number;
+	issues: string[];
+}
+
+export const SPROUT_DIR_NAME = ".sprout";
+export const ISSUES_FILE = "issues.jsonl";
+export const TEMPLATES_FILE = "templates.jsonl";
+export const PLANS_FILE = "plans.jsonl";
+export const CONFIG_FILE = "config.yaml";
+export const LOCK_STALE_MS = 30_000;
+export const LOCK_RETRY_MS = 100;
+export const LOCK_TIMEOUT_MS = 30_000;
+
+export const VALID_TYPES = ["task", "bug", "feature", "epic"] as const;
+export const VALID_STATUSES = ["open", "in_progress", "closed"] as const;
+
+export const PRIORITY_LABELS: Record<number, string> = {
+	0: "Critical",
+	1: "High",
+	2: "Medium",
+	3: "Low",
+	4: "Backlog",
+};

package/src/tools/sprout/validation.ts

@@ -0,0 +1,119 @@
+// AJV-based plan validation primitives.
+//
+// This is the ONLY module that imports `ajv`, keeping the runtime-dep boundary
+// tight (CLAUDE.md "Dependencies"). All later `sr plan` commands (submit,
+// validate) consume `compileSchema` and `formatErrors` from here.
+//
+// API choice: `compileSchema` returns a `ValidatorFn` that runs the formatter
+// under the hood. `formatErrors` is also exported so callers that already hold
+// raw AJV errors can render them without recompiling a schema.
+//
+// Code-name convention (PLAN_SPEC.md:180–195): AJV `keyword` maps 1:1 onto the
+// spec `code`, EXCEPT `minItems` normalizes to `min` to match the spec's
+// `sections.steps` example. `minLength` stays as-is.
+
+import Ajv, { type ErrorObject } from "ajv";
+
+export interface ErrorEntry {
+	path: string;
+	code: string;
+	fix: string;
+}
+
+export interface PartialStateDiff {
+	errors: ErrorEntry[];
+	current: unknown;
+}
+
+export type ValidatorFn = (
+	data: unknown,
+) => { valid: true } | { valid: false; diff: PartialStateDiff };
+
+export function compileSchema(schema: object): ValidatorFn {
+	const ajv = new Ajv({ allErrors: true, strict: true });
+	const validate = ajv.compile(schema);
+	return (data) => {
+		if (validate(data)) return { valid: true };
+		return { valid: false, diff: formatErrors(validate.errors ?? [], data) };
+	};
+}
+
+export function formatErrors(errs: ErrorObject[], submitted: unknown): PartialStateDiff {
+	return {
+		errors: errs.map((err) => toEntry(err, submitted)),
+		current: submitted,
+	};
+}
+
+function toEntry(err: ErrorObject, submitted: unknown): ErrorEntry {
+	const path = pathFor(err);
+	return {
+		path,
+		code: codeFor(err),
+		fix: fixFor(err, path, submitted),
+	};
+}
+
+function pathFor(err: ErrorObject): string {
+	const base = err.instancePath.replace(/^\//, "").replace(/\//g, ".");
+	if (err.keyword === "required") {
+		const prop = (err.params as { missingProperty?: string }).missingProperty;
+		if (prop) return base ? `${base}.${prop}` : prop;
+	}
+	return base;
+}
+
+function codeFor(err: ErrorObject): string {
+	if (err.keyword === "minItems") return "min";
+	return err.keyword;
+}
+
+function fixFor(err: ErrorObject, path: string, submitted: unknown): string {
+	const params = err.params as Record<string, unknown>;
+	switch (err.keyword) {
+		case "required": {
+			const prop = params.missingProperty as string | undefined;
+			return prop ? `add a '${prop}' field` : "add the missing required field";
+		}
+		case "minItems": {
+			const limit = Number(params.limit ?? 0);
+			const arr = valueAt(submitted, err.instancePath);
+			const got = Array.isArray(arr) ? arr.length : 0;
+			const need = Math.max(limit - got, 1);
+			const noun = need === 1 ? "entry" : "entries";
+			return `add at least ${need} more ${noun}`;
+		}
+		case "minLength": {
+			const limit = Number(params.limit ?? 0);
+			const where = path || "value";
+			return `expand '${where}' to at least ${limit} characters`;
+		}
+		case "type": {
+			const expected = params.type as string | string[] | undefined;
+			const expectedStr = Array.isArray(expected) ? expected.join(" or ") : expected;
+			const where = path || "value";
+			return expectedStr ? `'${where}' must be a ${expectedStr}` : `'${where}' has wrong type`;
+		}
+		default: {
+			const detail = Object.entries(params)
+				.map(([k, v]) => `${k}=${String(v)}`)
+				.join(", ");
+			const where = path ? `'${path}': ` : "";
+			return detail ? `${where}${err.keyword} (${detail})` : `${where}${err.keyword}`;
+		}
+	}
+}
+
+function valueAt(data: unknown, instancePath: string): unknown {
+	if (!instancePath) return data;
+	const parts = instancePath.split("/").filter(Boolean);
+	let cur: unknown = data;
+	for (const p of parts) {
+		if (cur && typeof cur === "object") {
+			cur = (cur as Record<string, unknown>)[p];
+		} else {
+			return undefined;
+		}
+	}
+	return cur;
+}

package/src/tools/sprout/version.ts

@@ -0,0 +1 @@
+export { VERSION } from "../../version.ts";