pi-harness-runtime 0.10.11 → 0.10.12

package/packages/django-plugin/src/analyzer.ts

@@ -0,0 +1,284 @@
+/**
+ * Django Analyzer (RFC-0064)
+ *
+ * Deep analysis of Django workspaces via filesystem inspection.
+ */
+
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { DjangoAnalysis, DjangoApp, ConfigFile } from "./types.js";
+
+// --- Detection ---------------------------------------------------------------
+
+function isDjangoWorkspace(root: string): boolean {
+	return (
+		existsSync(join(root, "manage.py")) ||
+		(existsSync(join(root, "settings.py")) &&
+			existsSync(join(root, "requirements.txt"))) ||
+		(existsSync(join(root, "requirements.txt")) &&
+			existsSync(join(root, "manage.py")))
+	);
+}
+
+// --- Version ----------------------------------------------------------------
+
+async function detectVersion(root: string): Promise<string | undefined> {
+	try {
+		const content = await readFile(join(root, "requirements.txt"), "utf-8");
+		const match = content.match(/Django[=<>~!^]*((\d+)\.\d+(?:\.\d+)?)/i);
+		if (match) return match[1];
+	} catch {
+		/* ignore */
+	}
+
+	// Check setup.py or pyproject.toml
+	for (const cfg of ["setup.py", "pyproject.toml"]) {
+		const cfgPath = join(root, cfg);
+		if (existsSync(cfgPath)) {
+			try {
+				const content = await readFile(cfgPath, "utf-8");
+				const match = content.match(/django[=<>~!^\s]*(\d+\.\d+(?:\.\d+)?)/i);
+				if (match) return match[1];
+			} catch {
+				/* ignore */
+			}
+		}
+	}
+	return undefined;
+}
+
+// --- Settings Parser ---------------------------------------------------------
+
+async function parseSettings(root: string): Promise<{
+	installedApps: string[];
+	middleware: string[];
+}> {
+	const installedApps: string[] = [];
+	const middleware: string[] = [];
+
+	const candidates = [
+		join(root, "settings.py"),
+		join(root, "core", "settings.py"),
+		join(root, "config", "settings.py"),
+	];
+
+	for (const settingsPath of candidates) {
+		if (!existsSync(settingsPath)) continue;
+		try {
+			const content = await readFile(settingsPath, "utf-8");
+
+			// Parse INSTALLED_APPS = [ ... ]
+			const installedMatch = content.match(
+				/INSTALLED_APPS\s*=\s*\[([\s\S]*?)\]/m,
+			);
+			if (installedMatch) {
+				const listContent = installedMatch[1];
+				// Match quoted strings and identifiers
+				const appMatches = listContent.matchAll(
+					/(?:^|\s|,)\s*['"]?([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)['"]?/g,
+				);
+				for (const m of appMatches) {
+					const app = m[1].trim();
+					if (app && !app.startsWith("#")) {
+						installedApps.push(app);
+					}
+				}
+			}
+
+			// Parse MIDDLEWARE = [ ... ]
+			const middlewareMatch = content.match(/MIDDLEWARE\s*=\s*\[([\s\S]*?)\]/m);
+			if (middlewareMatch) {
+				const listContent = middlewareMatch[1];
+				const mwMatches = listContent.matchAll(
+					/(?:^|\s|,)\s*['"]?([a-zA-Z_][a-zA-Z0-9_.]*)['"]?/g,
+				);
+				for (const m of mwMatches) {
+					const mw = m[1].trim();
+					if (mw && !mw.startsWith("#")) {
+						middleware.push(mw);
+					}
+				}
+			}
+
+			if (installedApps.length > 0) break;
+		} catch {
+			// ignore
+		}
+	}
+
+	return { installedApps, middleware };
+}
+
+// --- Django App Scanner -----------------------------------------------------
+
+async function scanDjangoApps(root: string): Promise<DjangoApp[]> {
+	const apps: DjangoApp[] = [];
+
+	// Django project apps can be:
+	// 1. Top-level directories with models.py
+	// 2. Apps in an "apps/" directory
+	const searchDirs = [root, join(root, "apps")];
+
+	const seen = new Set<string>();
+
+	for (const searchDir of searchDirs) {
+		if (!existsSync(searchDir)) continue;
+		let entries: string[] = [];
+		try {
+			entries = await readdir(searchDir);
+		} catch {
+			continue;
+		}
+
+		for (const entry of entries) {
+			if (entry.startsWith(".") || entry.startsWith("_")) continue;
+			const appPath = join(searchDir, entry);
+			let isDir = false;
+			try {
+				isDir = (
+					await import("node:fs/promises").then((m) => m.stat(appPath))
+				).isDirectory();
+			} catch {
+				continue;
+			}
+			if (!isDir) continue;
+			if (seen.has(entry)) continue;
+			seen.add(entry);
+
+			const modelsPath = join(appPath, "models.py");
+			const adminPath = join(appPath, "admin.py");
+			const migrationsDir = join(appPath, "migrations");
+
+			let modelCount = 0;
+			if (existsSync(modelsPath)) {
+				try {
+					const modelsContent = await readFile(modelsPath, "utf-8");
+					// Count class definitions that inherit from models.Model
+					const match1 = modelsContent.match(
+						/^class\s+\w+\s*\([^)]*models?\.[Mm]odel[^)]*\)/gm,
+					);
+					modelCount = (match1 ?? []).length;
+					// Also count class definitions (conservative)
+					const match2 = modelsContent.match(/class\s+\w+\s*\(/g);
+					modelCount = Math.max(modelCount, (match2 ?? []).length);
+				} catch {
+					// ignore
+				}
+			}
+
+			apps.push({
+				name: entry,
+				path: appPath,
+				modelCount,
+				hasAdmin: existsSync(adminPath),
+				hasMigrations: existsSync(migrationsDir),
+			});
+		}
+	}
+
+	return apps;
+}
+
+// --- Management Commands ----------------------------------------------------
+
+async function findManagementCommands(root: string): Promise<string[]> {
+	const commands: string[] = [];
+
+	// Simple recursive scan for management/commands directories
+	const searchDirs: string[] = [];
+	try {
+		const entries = await readdir(root);
+		for (const entry of entries) {
+			if (entry.startsWith(".")) continue;
+			const managementDir = join(root, entry, "management", "commands");
+			if (existsSync(managementDir)) {
+				searchDirs.push(managementDir);
+			}
+			const appsMgmt = join(root, "apps", entry, "management", "commands");
+			if (existsSync(appsMgmt)) {
+				searchDirs.push(appsMgmt);
+			}
+		}
+	} catch {
+		// ignore
+	}
+
+	for (const cmdDir of searchDirs) {
+		try {
+			const cmdEntries = await readdir(cmdDir);
+			for (const cmd of cmdEntries) {
+				if (cmd.startsWith("_") || !cmd.endsWith(".py")) continue;
+				commands.push(cmd.replace(/\.py$/, ""));
+			}
+		} catch {
+			// ignore
+		}
+	}
+
+	return [...new Set(commands)];
+}
+
+// --- Requirements -----------------------------------------------------------
+
+async function parseRequirements(root: string): Promise<string[]> {
+	const reqPath = join(root, "requirements.txt");
+	if (!existsSync(reqPath)) return [];
+
+	try {
+		const content = await readFile(reqPath, "utf-8");
+		return content
+			.split("\n")
+			.map((l) => l.trim())
+			.filter((l) => l && !l.startsWith("#") && !l.startsWith("-"))
+			.map((l) => l.split(/[=<>~!^]/)[0].trim());
+	} catch {
+		return [];
+	}
+}
+
+// --- Main Analyzer ---------------------------------------------------------
+
+export async function analyzeDjango(
+	root: string,
+): Promise<DjangoAnalysis | null> {
+	if (!isDjangoWorkspace(root)) return null;
+
+	const [version, settings, requirements] = await Promise.all([
+		detectVersion(root),
+		parseSettings(root),
+		parseRequirements(root),
+	]);
+
+	const apps = await scanDjangoApps(root);
+	const managementCommands = await findManagementCommands(root);
+	const drfEnabled =
+		requirements.some((r) => r.toLowerCase().includes("djangorestframework")) ||
+		settings.installedApps.some((a) => a.includes("rest_framework"));
+
+	// Config files
+	const configs: ConfigFile[] = [];
+	for (const cfg of ["settings.py", "urls.py", "wsgi.py", "manage.py"]) {
+		const p = join(root, cfg);
+		if (existsSync(p)) {
+			configs.push({ name: cfg, path: p });
+		}
+	}
+
+	return {
+		framework: {
+			id: "django",
+			name: "Django",
+			category: "fullstack",
+			description: "Python web framework for perfectionists with deadlines",
+			tags: ["python", "fullstack", "orm"],
+		},
+		version,
+		apps,
+		managementCommands,
+		middleware: settings.middleware,
+		drfEnabled,
+		requirements,
+		configs,
+	};
+}

package/packages/django-plugin/src/index.ts

@@ -0,0 +1,39 @@
+/**
+ * Django Plugin — Main Entry (RFC-0064)
+ */
+
+import type { FrameworkExtension } from "../../framework-plugin-sdk/src/types.js";
+import { analyzeDjango } from "./analyzer.js";
+
+export type { DjangoAnalysis, DjangoApp, ConfigFile } from "./types.js";
+
+export async function analyzeDjangoWorkspace(
+	root: string,
+): Promise<import("./types.js").DjangoAnalysis | null> {
+	return analyzeDjango(root);
+}
+
+export function createDjangoPlugin(): FrameworkExtension {
+	return {
+		capability: "framework",
+		name: "Django Framework Plugin",
+		detector: {
+			detect: async (root: unknown): Promise<unknown> => {
+				const r = root as string;
+				const { existsSync } = await import("node:fs");
+				return (
+					existsSync(`${r}/manage.py`) ||
+					(existsSync(`${r}/settings.py`) &&
+						existsSync(`${r}/requirements.txt`))
+				);
+			},
+			signals: [
+				{ type: "file", pattern: "manage.py", weight: 0.6 },
+				{ type: "file", pattern: "settings.py", weight: 0.4 },
+				{ type: "package", pattern: "django", weight: 0.5 },
+				{ type: "directory", pattern: "migrations", weight: 0.3 },
+			],
+		},
+		config: {},
+	};
+}

package/packages/django-plugin/src/types.ts

@@ -0,0 +1,35 @@
+/**
+ * Django Plugin — Types (RFC-0064)
+ */
+
+export interface DjangoAnalysis {
+	framework: FrameworkInfo;
+	version?: string;
+	apps: DjangoApp[];
+	managementCommands: string[];
+	middleware: string[];
+	drfEnabled: boolean;
+	requirements: string[];
+	configs: ConfigFile[];
+}
+
+export interface FrameworkInfo {
+	id: string;
+	name: string;
+	category: string;
+	description: string;
+	tags: string[];
+}
+
+export interface DjangoApp {
+	name: string;
+	path: string;
+	modelCount: number;
+	hasAdmin: boolean;
+	hasMigrations: boolean;
+}
+
+export interface ConfigFile {
+	name: string;
+	path: string;
+}

package/packages/doc-generator/src/detector.ts

@@ -0,0 +1,113 @@
+/**
+ * Doc Generator — Project Detection (RFC-0014)
+ */
+
+import type { ProjectType, ProjectDetection } from "./types.js";
+
+const SIGNALS: Record<
+	ProjectType,
+	Array<{ pattern: RegExp; weight: number }>
+> = {
+	frappe_erpnext: [
+		{ pattern: /frappe-bench|hooks\.py/, weight: 0.3 },
+		{ pattern: /doctype[/\\]/, weight: 0.4 },
+		{ pattern: /\bapps\/[^/]+\/[^/]+\.py\b/, weight: 0.2 },
+	],
+	frappe_spa: [
+		{ pattern: /frappe-bench\/apps\/[^/]+\/frontend/, weight: 0.4 },
+		{ pattern: /vite\.config\./, weight: 0.3 },
+		{ pattern: /frappe\.call|frappe\.ui\./, weight: 0.3 },
+	],
+	nextjs: [
+		{ pattern: /next\.config\./, weight: 0.4 },
+		{ pattern: /\/(app|pages)\/[^/]+\.(tsx|jsx|ts|js)/, weight: 0.3 },
+		{ pattern: /"next"|'next'/, weight: 0.2 },
+	],
+	react_vite: [
+		{ pattern: /vite\.config\.(ts|js|mjs)/, weight: 0.4 },
+		{ pattern: /src\/main\.(tsx|jsx)/, weight: 0.3 },
+		{ pattern: /index\.html/, weight: 0.2 },
+	],
+	django: [
+		{ pattern: /manage\.py/, weight: 0.4 },
+		{ pattern: /settings\.py/, weight: 0.3 },
+		{ pattern: /models?\.py/, weight: 0.2 },
+	],
+	laravel: [
+		{ pattern: /artisan/, weight: 0.4 },
+		{ pattern: /database\/seeders/, weight: 0.3 },
+		{ pattern: /composer\.json/, weight: 0.2 },
+	],
+	generic_web: [
+		{ pattern: /package\.json/, weight: 0.2 },
+		{ pattern: /index\.(html?|js|ts)/, weight: 0.2 },
+	],
+	unknown: [],
+};
+
+const SEED_STRATEGIES: Record<ProjectType, string> = {
+	frappe_erpnext: "frappe_doc_insert",
+	frappe_spa: "frappe_fixtures",
+	nextjs: "nextjs_factory",
+	react_vite: "vite_seed",
+	django: "django_migrations",
+	laravel: "laravel_seeders",
+	generic_web: "generic_faker",
+	unknown: "generic_faker",
+};
+
+const E2E_STRATEGIES: Record<ProjectType, string> = {
+	frappe_erpnext: "bench_site_browser_flow",
+	frappe_spa: "api_plus_spa_flow",
+	nextjs: "nextjs_dev_server_flow",
+	react_vite: "vite_dev_server_flow",
+	django: "django_test_client_flow",
+	laravel: "laravel_dusk_flow",
+	generic_web: "playwright_generic_flow",
+	unknown: "playwright_generic_flow",
+};
+
+/** Detect project type from a list of file paths. */
+export function detectProjectType(filePaths: string[]): ProjectDetection {
+	const scores: Record<ProjectType, number> = {
+		frappe_erpnext: 0,
+		frappe_spa: 0,
+		nextjs: 0,
+		react_vite: 0,
+		django: 0,
+		laravel: 0,
+		generic_web: 0,
+		unknown: 0,
+	};
+	const signals: string[] = [];
+
+	for (const filePath of filePaths) {
+		for (const [pType, pSignals] of Object.entries(SIGNALS) as [
+			ProjectType,
+			typeof SIGNALS.frappe_erpnext,
+		][]) {
+			for (const { pattern, weight } of pSignals) {
+				if (pattern.test(filePath)) {
+					scores[pType] += weight;
+					signals.push(filePath);
+				}
+			}
+		}
+	}
+
+	const best = Object.entries(scores).sort((a, b) => b[1] - a[1])[0];
+	const projectType = best[1] > 0 ? (best[0] as ProjectType) : "unknown";
+
+	return {
+		projectType,
+		confidence: Math.min(best[1], 1),
+		signals: [...new Set(signals)],
+		recommendedSeedStrategy: SEED_STRATEGIES[projectType],
+		recommendedE2EStrategy: E2E_STRATEGIES[projectType],
+	};
+}
+
+/** Parse signals from a directory listing. */
+export function parseSignals(entries: string[]): string[] {
+	return entries.filter((e) => /[./]/.test(e));
+}

package/packages/doc-generator/src/docs.ts

@@ -0,0 +1,158 @@
+/**
+ * Doc Generator — Documentation Generation (RFC-0014)
+ */
+
+import type {
+	DetectedSymbol,
+	GeneratedDocs,
+	DocSection,
+	SourceFile,
+} from "./types.js";
+import { detectProjectType } from "./detector.js";
+
+/** Detect exported symbols in a source file. */
+export function detectSymbols(source: SourceFile): DetectedSymbol[] {
+	const symbols: DetectedSymbol[] = [];
+	const lines = source.content.split("\n");
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		const trimmed = line.trim();
+
+		const fnMatch = trimmed.match(
+			/^(?:async\s+)?(?:export\s+)?function\s+(\w+)\s*\(([^)]*)\)/,
+		);
+		if (fnMatch) {
+			symbols.push({
+				name: fnMatch[1],
+				kind: "function",
+				signature: `${fnMatch[1]}(${fnMatch[2]})`,
+				docComment: getDocComment(lines, i),
+				file: source.path,
+				line: i + 1,
+			});
+		}
+
+		const classMatch = trimmed.match(/^(?:export\s+)?class\s+(\w+)/);
+		if (classMatch) {
+			symbols.push({
+				name: classMatch[1],
+				kind: "class",
+				docComment: getDocComment(lines, i),
+				file: source.path,
+				line: i + 1,
+			});
+		}
+
+		const ifaceMatch = trimmed.match(/^export\s+interface\s+(\w+)/);
+		if (ifaceMatch) {
+			symbols.push({
+				name: ifaceMatch[1],
+				kind: "interface",
+				docComment: getDocComment(lines, i),
+				file: source.path,
+				line: i + 1,
+			});
+		}
+
+		const typeMatch = trimmed.match(/^export\s+type\s+(\w+)/);
+		if (typeMatch) {
+			symbols.push({
+				name: typeMatch[1],
+				kind: "type",
+				docComment: getDocComment(lines, i),
+				file: source.path,
+				line: i + 1,
+			});
+		}
+
+		const constMatch = trimmed.match(/^export\s+const\s+(\w+)/);
+		if (constMatch) {
+			symbols.push({
+				name: constMatch[1],
+				kind: "constant",
+				docComment: getDocComment(lines, i),
+				file: source.path,
+				line: i + 1,
+			});
+		}
+	}
+
+	return symbols;
+}
+
+function getDocComment(lines: string[], index: number): string | undefined {
+	for (let j = Math.max(0, index - 5); j < index; j++) {
+		const prev = lines[j].trim();
+		if (prev.startsWith("/**") || prev.startsWith("///")) {
+			const endIdx = lines
+				.slice(j + 1, index)
+				.findIndex((l) => l.includes("*/"));
+			if (endIdx >= 0) {
+				const doc = lines.slice(j, j + endIdx + 2).join("\n");
+				return doc.replace(/\/\*\*|\*\/|[\s*]/g, "").trim();
+			}
+		}
+	}
+	return undefined;
+}
+
+function summarizeSymbols(symbols: DetectedSymbol[]): string {
+	const counts: Record<string, number> = {};
+	for (const s of symbols) counts[s.kind] = (counts[s.kind] ?? 0) + 1;
+	return Object.entries(counts)
+		.map(([k, v]) => `${v} ${k}(s)`)
+		.join(", ");
+}
+
+function formatSymbol(s: DetectedSymbol): string {
+	const sig = s.signature ? `${s.name}${s.signature}` : s.name;
+	return `- ${sig} (${s.file}:${s.line})`;
+}
+
+/** Generate documentation for a list of source files. */
+export function generateDocs(
+	sources: SourceFile[],
+	projectSignals: string[],
+): GeneratedDocs {
+	const detection = detectProjectType(projectSignals);
+	const allSymbols = sources.flatMap(detectSymbols);
+
+	const sections: DocSection[] = [
+		{
+			heading: "Overview",
+			level: 1,
+			content: `Project type: ${detection.projectType} (confidence: ${(detection.confidence * 100).toFixed(0)}%)\nSignals: ${detection.signals.join(", ") || "none"}`,
+		},
+		{
+			heading: "Exports",
+			level: 1,
+			content: `Total exports: ${allSymbols.length}\n${summarizeSymbols(allSymbols)}`,
+		},
+		{
+			heading: "Functions",
+			level: 2,
+			content:
+				allSymbols
+					.filter((s) => s.kind === "function")
+					.map(formatSymbol)
+					.join("\n") || "No functions found.",
+		},
+		{
+			heading: "Types & Interfaces",
+			level: 2,
+			content:
+				allSymbols
+					.filter((s) => s.kind === "type" || s.kind === "interface")
+					.map(formatSymbol)
+					.join("\n") || "No types found.",
+		},
+	];
+
+	return {
+		title: "Generated Documentation",
+		sections,
+		symbols: allSymbols,
+		projectType: detection.projectType,
+	};
+}

package/packages/doc-generator/src/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Doc Generator — Main Entry (RFC-0014)
+ */
+
+export { detectProjectType, parseSignals } from "./detector.js";
+export { detectSymbols, generateDocs } from "./docs.js";
+export type * from "./types.js";

package/packages/doc-generator/src/types.ts

@@ -0,0 +1,58 @@
+/**
+ * Doc Generator Types (RFC-0014)
+ */
+
+export interface SourceFile {
+	path: string;
+	content: string;
+	language: string;
+}
+
+export type ProjectType =
+	| "frappe_erpnext"
+	| "frappe_spa"
+	| "nextjs"
+	| "react_vite"
+	| "django"
+	| "laravel"
+	| "generic_web"
+	| "unknown";
+
+export interface ProjectDetection {
+	projectType: ProjectType;
+	confidence: number;
+	signals: string[];
+	recommendedSeedStrategy: string;
+	recommendedE2EStrategy: string;
+}
+
+export interface DetectedSymbol {
+	name: string;
+	kind: "function" | "class" | "interface" | "type" | "constant" | "variable";
+	signature?: string;
+	docComment?: string;
+	file: string;
+	line: number;
+}
+
+export interface GeneratedDocs {
+	title: string;
+	sections: DocSection[];
+	symbols: DetectedSymbol[];
+	projectType: ProjectType;
+}
+
+export interface DocSection {
+	heading: string;
+	level: 1 | 2 | 3;
+	content: string;
+}
+
+export type SeedStrategy =
+	| "frappe_doc_insert"
+	| "frappe_fixtures"
+	| "nextjs_factory"
+	| "vite_seed"
+	| "django_migrations"
+	| "laravel_seeders"
+	| "generic_faker";