pi-readme 1.0.0

package/README.md

@@ -0,0 +1,72 @@
+# pi-readme
+
+> Pi-native README generator and linter for pi.dev packages — auto-generate and validate README.md files.
+
+[![npm version](https://img.shields.io/npm/v/pi-readme)](https://www.npmjs.com/package/pi-readme)
+
+## Installation
+
+```bash
+pi install npm:pi-readme
+```
+
+## What It Does
+
+Auto-generates and validates README.md files for pi.dev packages. Reads your package.json, extension tools, and CHANGELOG.md to create a pi-native README with proper install commands, tools documentation, and peer dependencies.
+
+**Keywords:** pi-package, pi, readme, documentation, generator, linter
+
+## Tools
+
+### `readme_generate`
+
+Generate a README.md for a pi.dev package from package.json metadata, extension tools, and changelog. Creates a pi-native README with proper install commands, tools documentation, and peer dependencies.
+
+**Parameters:**
+- `path` (string, optional) — Path to the package directory (defaults to cwd)
+- `template_overrides` (Record<string, string>, optional) — Optional overrides for template sections
+
+**Example:**
+```
+Use the readme_generate tool with path="./my-pi-package"
+```
+
+### `readme_lint`
+
+Validate a README.md against pi.dev best practices. Checks for install commands, proper `pi install npm:` format, description, tools section, license, heading hierarchy, and pi-package keyword.
+
+**Parameters:**
+- `readme_path` (string, optional) — Path to the README.md file (defaults to ./README.md)
+- `package_path` (string, optional) — Path to the package directory (defaults to cwd)
+
+**Example:**
+```
+Use the readme_lint tool to check your README
+```
+
+## Commands
+
+### `/readme generate [path]`
+
+Generate README for a pi.dev package.
+
+### `/readme lint [path]`
+
+Validate README against pi.dev standards.
+
+## Peer Dependencies
+
+- `@earendil-works/pi-coding-agent` >=0.74.0
+- `typebox` >=1.0.0
+
+**Version:** 1.0.0
+
+## Resources
+
+- [npm](https://www.npmjs.com/package/pi-readme)
+- [GitHub](https://github.com/ZachDreamZ/pi-readme)
+- [pi.dev](https://pi.dev/packages/pi-readme)
+
+## License
+
+MIT

package/extensions/index.ts

@@ -0,0 +1,452 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+// ── Types ──
+
+interface PackageJson {
+	name?: string;
+	description?: string;
+	version?: string;
+	keywords?: string[];
+	license?: string;
+	peerDependencies?: Record<string, string>;
+	dependencies?: Record<string, string>;
+}
+
+interface LintIssue {
+	severity: "error" | "warning" | "info";
+	line: number | null;
+	rule: string;
+	message: string;
+	fix: string;
+}
+
+interface ToolInfo {
+	name: string;
+	description: string;
+	parameters?: string[];
+}
+
+// ── Helpers ──
+
+function readPackageJson(pkgPath: string): PackageJson | null {
+	const full = resolve(pkgPath, "package.json");
+	if (!existsSync(full)) return null;
+	try {
+		return JSON.parse(readFileSync(full, "utf-8"));
+	} catch {
+		return null;
+	}
+}
+
+function readChangelogVersion(pkgPath: string): string | null {
+	const clPath = resolve(pkgPath, "CHANGELOG.md");
+	if (!existsSync(clPath)) return null;
+	try {
+		const content = readFileSync(clPath, "utf-8");
+		const match = content.match(/^##\s*\[?(\d+\.\d+\.\d+[^\]\s]*)\]?/m);
+		return match ? match[1] : null;
+	} catch {
+		return null;
+	}
+}
+
+function extractToolsFromExtension(pkgPath: string): ToolInfo[] {
+	const extPaths = [
+		resolve(pkgPath, "extensions", "index.ts"),
+		resolve(pkgPath, "src", "extension.ts"),
+		resolve(pkgPath, "extension.ts"),
+	];
+
+	for (const extPath of extPaths) {
+		if (!existsSync(extPath)) continue;
+		try {
+			const content = readFileSync(extPath, "utf-8");
+			const tools: ToolInfo[] = [];
+
+			const toolRegex =
+				/registerTool\(\s*\{[\s\S]*?name:\s*["']([^"']+)["'][\s\S]*?description:\s*["']([^"']+)["']/g;
+			let match: RegExpExecArray | null = toolRegex.exec(content);
+			while (match !== null) {
+				const paramRegex = new RegExp(
+					`name:\\s*["']${match[1]}["'][\\s\\S]*?parameters:\\s*Type\\.Object\\(\\{([^}]*)\\}`,
+					"m",
+				);
+				const paramMatch = content.match(paramRegex);
+				const params: string[] = [];
+				if (paramMatch) {
+					const paramNames = paramMatch[1].match(/(\w+)\s*:/g);
+					if (paramNames) {
+						params.push(
+							...paramNames.map((p: string) => p.replace(":", "").trim()),
+						);
+					}
+				}
+				tools.push({
+					name: match[1],
+					description: match[2],
+					parameters: params.length > 0 ? params : undefined,
+				});
+				match = toolRegex.exec(content);
+			}
+			if (tools.length > 0) return tools;
+		} catch {}
+	}
+	return [];
+}
+
+function generateReadmeContent(
+	pkg: PackageJson,
+	tools: ToolInfo[],
+	version: string | null,
+): string {
+	const name = pkg.name || "pi-package";
+	const desc = pkg.description || "A pi.dev package";
+	const ver = version || pkg.version || "1.0.0";
+	const license = pkg.license || "MIT";
+	const peerDeps = pkg.peerDependencies || {};
+	const keywords = pkg.keywords || [];
+
+	const lines: string[] = [];
+
+	lines.push(`# ${name}`);
+	lines.push("");
+	lines.push(`> ${desc}`);
+	lines.push("");
+	lines.push(
+		`[![npm version](https://img.shields.io/npm/v/${name})](https://www.npmjs.com/package/${name})`,
+	);
+	lines.push("");
+	lines.push("## Installation");
+	lines.push("");
+	lines.push("```bash");
+	lines.push(`pi install npm:${name}`);
+	lines.push("```");
+	lines.push("");
+	lines.push("## What It Does");
+	lines.push("");
+	lines.push(desc);
+	if (keywords.length > 0) {
+		lines.push("");
+		lines.push(`**Keywords:** ${keywords.join(", ")}`);
+	}
+	lines.push("");
+
+	if (tools.length > 0) {
+		lines.push("## Tools");
+		lines.push("");
+		for (const tool of tools) {
+			lines.push(`### \`${tool.name}\``);
+			lines.push("");
+			lines.push(tool.description);
+			lines.push("");
+			if (tool.parameters && tool.parameters.length > 0) {
+				lines.push("**Parameters:**");
+				for (const param of tool.parameters) {
+					lines.push(`- \`${param}\``);
+				}
+				lines.push("");
+			}
+			lines.push("**Example:**");
+			lines.push("```");
+			lines.push(`Use the ${tool.name} tool`);
+			lines.push("```");
+			lines.push("");
+		}
+	}
+
+	const depKeys = Object.keys(peerDeps);
+	if (depKeys.length > 0) {
+		lines.push("## Peer Dependencies");
+		lines.push("");
+		for (const dep of depKeys) {
+			lines.push(`- \`${dep}\` ${peerDeps[dep]}`);
+		}
+		lines.push("");
+	}
+
+	lines.push(`**Version:** ${ver}`);
+	lines.push("");
+	lines.push("## Resources");
+	lines.push("");
+	lines.push(`- [npm](https://www.npmjs.com/package/${name})`);
+	lines.push(`- [GitHub](https://github.com/ZachDreamZ/${name})`);
+	lines.push(`- [pi.dev](https://pi.dev/packages/${name})`);
+	lines.push("");
+	lines.push("## License");
+	lines.push("");
+	lines.push(license);
+	lines.push("");
+
+	return lines.join("\n");
+}
+
+// ── Lint Rules ──
+
+function lintReadme(readmePath: string, pkgPath: string): LintIssue[] {
+	const issues: LintIssue[] = [];
+
+	if (!existsSync(readmePath)) {
+		issues.push({
+			severity: "error",
+			line: null,
+			rule: "pi-readme/missing-file",
+			message: "README.md file not found",
+			fix: "Create a README.md file",
+		});
+		return issues;
+	}
+
+	const content = readFileSync(readmePath, "utf-8");
+	const lines = content.split("\n");
+
+	// Check: has title (# heading)
+	const hasTitle = lines.some((l) => /^#\s+\S/.test(l));
+	if (!hasTitle) {
+		issues.push({
+			severity: "error",
+			line: 1,
+			rule: "pi-readme/missing-title",
+			message: "README must start with a # title",
+			fix: "Add a '# package-name' heading at the top",
+		});
+	}
+
+	// Check: has description (blockquote)
+	const hasDescription = lines.some((l) => /^>\s+\S/.test(l));
+	if (!hasDescription) {
+		const titleLine = lines.findIndex((l) => /^#\s+\S/.test(l));
+		issues.push({
+			severity: "error",
+			line: titleLine >= 0 ? titleLine + 2 : 3,
+			rule: "pi-readme/missing-description",
+			message: "README must have a description (blockquote after title)",
+			fix: "Add a > blockquote description after the # title",
+		});
+	}
+
+	// Check: has install section
+	const installSectionIdx = lines.findIndex((l) => /^##\s+Install/i.test(l));
+	if (installSectionIdx < 0) {
+		issues.push({
+			severity: "error",
+			line: null,
+			rule: "pi-readme/missing-install",
+			message: "README must include an installation section",
+			fix: "Add an '## Installation' section with `pi install npm:<package-name>`",
+		});
+	} else {
+		const sectionEnd = lines.findIndex(
+			(l, i) => i > installSectionIdx && /^##\s/.test(l),
+		);
+		const installSection = lines
+			.slice(installSectionIdx, sectionEnd >= 0 ? sectionEnd : lines.length)
+			.join("\n");
+
+		const hasPiFormat = /pi\s+install\s+npm:/.test(installSection);
+		const hasNpmInstall = /npm\s+install\s+/.test(installSection);
+		const hasYarnAdd = /yarn\s+add\s+/.test(installSection);
+
+		if (!hasPiFormat && (hasNpmInstall || hasYarnAdd || !hasPiFormat)) {
+			const codeBlockLine =
+				installSectionIdx +
+				lines.slice(installSectionIdx).findIndex((l) => /```/.test(l));
+			issues.push({
+				severity: "error",
+				line: codeBlockLine >= 0 ? codeBlockLine + 1 : installSectionIdx + 1,
+				rule: "pi-readme/wrong-install-format",
+				message: "Install command must use `pi install npm:` format",
+				fix: "Use `pi install npm:<package-name>` instead of npm/yarn/pnpm install",
+			});
+		}
+	}
+
+	// Check: has tools section
+	const hasToolsSection = lines.some((l) => /^##\s+Tools/i.test(l));
+	if (!hasToolsSection) {
+		issues.push({
+			severity: "warning",
+			line: null,
+			rule: "pi-readme/missing-tools-section",
+			message: "README should document available tools",
+			fix: "Add a '## Tools' section listing each tool with description",
+		});
+	}
+
+	// Check: has license section
+	const hasLicenseSection = lines.some((l) => /^##\s+License/i.test(l));
+	if (!hasLicenseSection) {
+		issues.push({
+			severity: "warning",
+			line: null,
+			rule: "pi-readme/missing-license",
+			message: "README should mention the license",
+			fix: "Add a '## License' section",
+		});
+	}
+
+	// Check: heading hierarchy
+	let lastLevel = 0;
+	for (let i = 0; i < lines.length; i++) {
+		const match = lines[i].match(/^(#{1,6})\s/);
+		if (match) {
+			const level = match[1].length;
+			if (level > lastLevel + 1 && lastLevel > 0) {
+				issues.push({
+					severity: "warning",
+					line: i + 1,
+					rule: "pi-readme/heading-hierarchy",
+					message: `Heading levels should not skip (found h${level} after h${lastLevel})`,
+					fix: "Use sequential heading levels: # → ## → ###",
+				});
+			}
+			lastLevel = level;
+		}
+	}
+
+	// Check: package.json has pi-package keyword
+	const pkg = readPackageJson(pkgPath);
+	if (pkg && (!pkg.keywords || !pkg.keywords.includes("pi-package"))) {
+		issues.push({
+			severity: "info",
+			line: null,
+			rule: "pi-readme/missing-pi-keyword",
+			message: "Consider adding 'pi-package' to package.json keywords",
+			fix: 'Add "pi-package" to the keywords array in package.json',
+		});
+	}
+
+	const severityOrder = { error: 0, warning: 1, info: 2 };
+	issues.sort((a, b) => severityOrder[a.severity] - severityOrder[b.severity]);
+
+	return issues;
+}
+
+// ── Extension Registration ──
+
+export default function register(pi: ExtensionAPI): void {
+	// Tool 1: readme_generate
+	pi.registerTool({
+		name: "readme_generate",
+		label: "Generate README",
+		description:
+			"Generate a README.md for a pi.dev package from package.json metadata, extension tools, and changelog. Creates a pi-native README with proper install commands, tools documentation, and peer dependencies.",
+		parameters: Type.Object({
+			path: Type.Optional(
+				Type.String({
+					description:
+						"Path to the package directory (defaults to current working directory)",
+				}),
+			),
+			template_overrides: Type.Optional(
+				Type.Record(Type.String(), Type.String(), {
+					description:
+						"Optional overrides for template sections (e.g., {description: 'Custom desc'})",
+				}),
+			),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			const pkgPath = resolve(params.path || ".");
+			const pkg = readPackageJson(pkgPath);
+
+			if (!pkg) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Error: No package.json found at ${pkgPath}`,
+						},
+					],
+					details: {
+						success: false,
+						error: `No package.json found at ${pkgPath}`,
+					},
+				};
+			}
+
+			const tools = extractToolsFromExtension(pkgPath);
+			const version = readChangelogVersion(pkgPath);
+
+			let readme = generateReadmeContent(pkg, tools, version);
+
+			if (params.template_overrides) {
+				for (const [key, value] of Object.entries(params.template_overrides)) {
+					if (key === "description") {
+						readme = readme.replace(/^> .+$/m, `> ${value}`);
+					}
+				}
+			}
+
+			return {
+				content: [{ type: "text", text: readme }],
+				details: {
+					success: true,
+					metadata: {
+						name: pkg.name,
+						version: version || pkg.version,
+						tools_found: tools.length,
+						tool_names: tools.map((t) => t.name),
+						peer_deps: Object.keys(pkg.peerDependencies || {}),
+					},
+				},
+			};
+		},
+	});
+
+	// Tool 2: readme_lint
+	pi.registerTool({
+		name: "readme_lint",
+		label: "Lint README",
+		description:
+			"Validate a README.md against pi.dev best practices. Checks for install commands, proper `pi install npm:` format, description, tools section, license, heading hierarchy, and pi-package keyword. Returns issues with severity, line numbers, and fix suggestions.",
+		parameters: Type.Object({
+			readme_path: Type.Optional(
+				Type.String({
+					description: "Path to the README.md file (defaults to ./README.md)",
+				}),
+			),
+			package_path: Type.Optional(
+				Type.String({
+					description:
+						"Path to the package directory for reading package.json (defaults to cwd)",
+				}),
+			),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			const pkgPath = resolve(params.package_path || ".");
+			const readmePath = resolve(
+				params.readme_path || join(pkgPath, "README.md"),
+			);
+
+			const issues = lintReadme(readmePath, pkgPath);
+
+			const errors = issues.filter((i) => i.severity === "error").length;
+			const warnings = issues.filter((i) => i.severity === "warning").length;
+			const infos = issues.filter((i) => i.severity === "info").length;
+
+			const summary = `${issues.length} issue(s): ${errors} error(s), ${warnings} warning(s), ${infos} info`;
+
+			const issueLines = issues.map(
+				(i) =>
+					`[${i.severity.toUpperCase()}] ${i.line ? `Line ${i.line}: ` : ""}${i.message} — Fix: ${i.fix}`,
+			);
+
+			return {
+				content: [
+					{
+						type: "text",
+						text: `${summary}\n\n${issueLines.join("\n") || "No issues found."}`,
+					},
+				],
+				details: {
+					success: errors === 0,
+					summary,
+					issues,
+					stats: { errors, warnings, infos, total: issues.length },
+				},
+			};
+		},
+	});
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "pi-readme",
+  "version": "1.0.0",
+  "description": "Pi-native README generator and linter for pi.dev packages — auto-generate and validate README.md files",
+  "type": "module",
+  "main": "extensions/index.ts",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "readme",
+    "documentation",
+    "generator",
+    "linter"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.74.0",
+    "typebox": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@earendil-works/pi-coding-agent": "*",
+    "@types/node": "^26.0.1",
+    "typebox": "*",
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "biome check ."
+  }
+}

package/tests/readme.test.ts

@@ -0,0 +1,148 @@
+import {
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { beforeEach, describe, expect, it } from "vitest";
+
+const TEST_DIR = resolve(tmpdir(), `pi-readme-test-${Date.now()}`);
+
+function setupDir() {
+	if (existsSync(TEST_DIR)) rmSync(TEST_DIR, { recursive: true });
+	mkdirSync(TEST_DIR, { recursive: true });
+}
+
+function writeTestPkg(overrides: Record<string, unknown> = {}) {
+	const pkg = {
+		name: "test-pi-package",
+		description: "A test package for pi.dev",
+		version: "1.0.0",
+		keywords: ["pi-package", "pi", "test"],
+		license: "MIT",
+		peerDependencies: {
+			"@earendil-works/pi-coding-agent": ">=0.74.0",
+			typebox: ">=1.0.0",
+		},
+		...overrides,
+	};
+	writeFileSync(join(TEST_DIR, "package.json"), JSON.stringify(pkg, null, 2));
+	return pkg;
+}
+
+function writeTestReadme(content: string) {
+	writeFileSync(join(TEST_DIR, "README.md"), content);
+}
+
+describe("readme_generate logic", () => {
+	beforeEach(setupDir);
+
+	it("generates README with all sections from package.json", () => {
+		writeTestPkg();
+		const pkg = JSON.parse(
+			readFileSync(join(TEST_DIR, "package.json"), "utf-8"),
+		);
+		expect(pkg.name).toBe("test-pi-package");
+		expect(pkg.description).toBe("A test package for pi.dev");
+		expect(pkg.keywords).toContain("pi-package");
+		expect(pkg.peerDependencies).toHaveProperty(
+			"@earendil-works/pi-coding-agent",
+		);
+	});
+
+	it("handles missing package.json gracefully", () => {
+		const path = join(TEST_DIR, "package.json");
+		expect(existsSync(path)).toBe(false);
+	});
+});
+
+describe("readme_lint logic", () => {
+	beforeEach(setupDir);
+
+	it("detects missing README", () => {
+		writeTestPkg();
+		expect(existsSync(join(TEST_DIR, "README.md"))).toBe(false);
+	});
+
+	it("detects missing install section", () => {
+		writeTestPkg();
+		writeTestReadme(
+			"# test-pi-package\n> A test package\n\n## Tools\n### tool1\nDesc",
+		);
+		const content = readFileSync(join(TEST_DIR, "README.md"), "utf-8");
+		expect(content).not.toMatch(/## Install/i);
+	});
+
+	it("detects wrong install format (npm install instead of pi install)", () => {
+		writeTestPkg();
+		writeTestReadme(
+			"# test-pi-package\n> A test package\n\n## Installation\n\n```bash\nnpm install test-pi-package\n```",
+		);
+		const content = readFileSync(join(TEST_DIR, "README.md"), "utf-8");
+		expect(content).toMatch(/npm install/);
+		expect(content).not.toMatch(/pi install npm:/);
+	});
+
+	it("passes for correct pi install format", () => {
+		writeTestPkg();
+		writeTestReadme(
+			"# test-pi-package\n> A test package\n\n## Installation\n\n```bash\npi install npm:test-pi-package\n```\n\n## Tools\n\n### tool1\nDesc\n\n## License\nMIT",
+		);
+		const content = readFileSync(join(TEST_DIR, "README.md"), "utf-8");
+		expect(content).toMatch(/pi install npm:test-pi-package/);
+		expect(content).toMatch(/## Tools/);
+		expect(content).toMatch(/## License/);
+	});
+
+	it("detects missing description blockquote", () => {
+		writeTestPkg();
+		writeTestReadme(
+			"# test-pi-package\n\n## Installation\n\n```bash\npi install npm:test-pi-package\n```",
+		);
+		const content = readFileSync(join(TEST_DIR, "README.md"), "utf-8");
+		expect(content).not.toMatch(/^>\s/m);
+	});
+
+	it("detects heading hierarchy skip", () => {
+		writeTestPkg();
+		writeTestReadme(
+			"# test-pi-package\n> Desc\n\n### Skipped heading\n\n## Installation\n\n```bash\npi install npm:test-pi-package\n```",
+		);
+		const lines = readFileSync(join(TEST_DIR, "README.md"), "utf-8").split(
+			"\n",
+		);
+		const h1 = lines.findIndex((l: string) => /^#\s/.test(l));
+		const h3 = lines.findIndex((l: string) => /^###\s/.test(l));
+		expect(h1).toBeGreaterThanOrEqual(0);
+		expect(h3).toBeGreaterThanOrEqual(0);
+	});
+
+	it("detects missing tools section", () => {
+		writeTestPkg();
+		writeTestReadme(
+			"# test-pi-package\n> Desc\n\n## Installation\n\n```bash\npi install npm:test-pi-package\n```\n\n## License\nMIT",
+		);
+		const content = readFileSync(join(TEST_DIR, "README.md"), "utf-8");
+		expect(content).not.toMatch(/## Tools/i);
+	});
+
+	it("detects missing license section", () => {
+		writeTestPkg();
+		writeTestReadme(
+			"# test-pi-package\n> Desc\n\n## Installation\n\n```bash\npi install npm:test-pi-package\n```\n\n## Tools\n### tool1\nDesc",
+		);
+		const content = readFileSync(join(TEST_DIR, "README.md"), "utf-8");
+		expect(content).not.toMatch(/## License/i);
+	});
+
+	it("detects missing pi-package keyword in package.json", () => {
+		writeTestPkg({ keywords: ["test"] });
+		const pkg = JSON.parse(
+			readFileSync(join(TEST_DIR, "package.json"), "utf-8"),
+		);
+		expect(pkg.keywords).not.toContain("pi-package");
+	});
+});

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "outDir": "dist",
+    "rootDir": ".",
+    "declaration": true,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "lib": ["ES2022"],
+    "types": ["node"]
+  },
+  "include": ["extensions/**/*.ts", "tests/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}