pi-harness-runtime 0.9.4 → 0.9.6

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/django-plugin/test/analyzer.test.ts

@@ -0,0 +1,195 @@
+/**
+ * Django Plugin Tests (RFC-0064)
+ */
+
+import { describe, it, expect, afterEach } from "bun:test";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+import { analyzeDjango } from "../src/analyzer.js";
+
+const roots: string[] = [];
+
+async function mkdtemp(): Promise<string> {
+	const d = await fs.mkdtemp(path.join(os.tmpdir(), "django-plugin-"));
+	roots.push(d);
+	return d;
+}
+
+afterEach(async () => {
+	for (const d of roots) {
+		try {
+			await fs.rm(d, { recursive: true, force: true });
+		} catch {
+			/* ignore */
+		}
+	}
+	roots.length = 0;
+});
+
+describe("analyzeDjango", () => {
+	it("returns null for non-django workspace", async () => {
+		const dir = await mkdtemp();
+		await fs.writeFile(path.join(dir, "package.json"), "{}", "utf-8");
+		expect(await analyzeDjango(dir)).toBeNull();
+	});
+
+	it("detects django workspace via manage.py", async () => {
+		const dir = await mkdtemp();
+		await fs.writeFile(
+			path.join(dir, "manage.py"),
+			"#!/usr/bin/env python",
+			"utf-8",
+		);
+		await fs.writeFile(
+			path.join(dir, "requirements.txt"),
+			"django>=4.0\ndjangorestframework",
+			"utf-8",
+		);
+		const result = await analyzeDjango(dir);
+		expect(result).not.toBeNull();
+		expect(result!.framework.id).toBe("django");
+	});
+
+	it("detects django workspace via settings.py", async () => {
+		const dir = await mkdtemp();
+		await fs.writeFile(path.join(dir, "settings.py"), "DEBUG = True", "utf-8");
+		await fs.writeFile(
+			path.join(dir, "requirements.txt"),
+			"django>=4.0",
+			"utf-8",
+		);
+		const result = await analyzeDjango(dir);
+		expect(result).not.toBeNull();
+	});
+
+	it("extracts version from requirements.txt", async () => {
+		const dir = await mkdtemp();
+		await fs.writeFile(
+			path.join(dir, "manage.py"),
+			"#!/usr/bin/env python",
+			"utf-8",
+		);
+		await fs.writeFile(
+			path.join(dir, "requirements.txt"),
+			"django==4.2.10\ndjangorestframework==3.14.0",
+			"utf-8",
+		);
+		const result = await analyzeDjango(dir);
+		expect(result!.version).toBe("4.2.10");
+	});
+
+	it("parses INSTALLED_APPS from settings.py", async () => {
+		const dir = await mkdtemp();
+		await fs.writeFile(
+			path.join(dir, "settings.py"),
+			`
+INSTALLED_APPS = [
+    'django.contrib.admin',
+    'django.contrib.auth',
+    'rest_framework',
+    'myapp.core',
+]
+MIDDLEWARE = [
+    'django.middleware.security.SecurityMiddleware',
+    'django.contrib.sessions.middleware.SessionMiddleware',
+    'django.middleware.common.CommonMiddleware',
+]
+`.trim(),
+			"utf-8",
+		);
+		await fs.writeFile(
+			path.join(dir, "requirements.txt"),
+			"django>=4.0",
+			"utf-8",
+		);
+		const result = await analyzeDjango(dir);
+		expect(result!.middleware).toContain(
+			"django.middleware.security.SecurityMiddleware",
+		);
+	});
+
+	it("detects Django REST Framework", async () => {
+		const dir = await mkdtemp();
+		await fs.writeFile(
+			path.join(dir, "settings.py"),
+			`
+INSTALLED_APPS = [
+    'django.contrib.admin',
+    'rest_framework',
+]
+`.trim(),
+			"utf-8",
+		);
+		await fs.writeFile(
+			path.join(dir, "requirements.txt"),
+			"django>=4.0\ndjangorestframework",
+			"utf-8",
+		);
+		const result = await analyzeDjango(dir);
+		expect(result!.drfEnabled).toBe(true);
+	});
+
+	it("counts model classes in app models.py", async () => {
+		const dir = await mkdtemp();
+		await fs.mkdir(path.join(dir, "myapp"), { recursive: true });
+		await fs.writeFile(
+			path.join(dir, "settings.py"),
+			"INSTALLED_APPS = []",
+			"utf-8",
+		);
+		await fs.writeFile(
+			path.join(dir, "requirements.txt"),
+			"django>=4.0",
+			"utf-8",
+		);
+		await fs.writeFile(
+			path.join(dir, "myapp", "models.py"),
+			`
+from django.db import models
+
+class Customer(models.Model):
+    name = models.CharField(max_length=100)
+
+class Order(models.Model):
+    customer = models.ForeignKey(Customer, on_delete=models.CASCADE)
+`,
+			"utf-8",
+		);
+		const result = await analyzeDjango(dir);
+		const myApp = result!.apps.find((a) => a.name === "myapp");
+		expect(myApp).toBeDefined();
+		// Conservative: at least 2 classes detected
+		expect(myApp!.modelCount).toBeGreaterThanOrEqual(2);
+	});
+
+	it("finds management commands", async () => {
+		const dir = await mkdtemp();
+		await fs.mkdir(path.join(dir, "myapp", "management", "commands"), {
+			recursive: true,
+		});
+		await fs.writeFile(
+			path.join(dir, "settings.py"),
+			"INSTALLED_APPS = []",
+			"utf-8",
+		);
+		await fs.writeFile(
+			path.join(dir, "requirements.txt"),
+			"django>=4.0",
+			"utf-8",
+		);
+		await fs.writeFile(
+			path.join(dir, "myapp", "management", "commands", "send_email.py"),
+			"# management command",
+			"utf-8",
+		);
+		await fs.writeFile(
+			path.join(dir, "myapp", "management", "commands", "cleanup.py"),
+			"# cleanup",
+			"utf-8",
+		);
+		const result = await analyzeDjango(dir);
+		expect(result!.managementCommands).toContain("send_email");
+		expect(result!.managementCommands).toContain("cleanup");
+	});
+});

package/packages/django-plugin/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "references": [
+    { "path": "../framework-plugin-sdk" },
+    { "path": "../framework-detector" }
+  ]
+}

package/packages/doc-generator/dist/detector.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Doc Generator — Project Detection (RFC-0014)
+ */
+import type { ProjectDetection } from "./types.js";
+/** Detect project type from a list of file paths. */
+export declare function detectProjectType(filePaths: string[]): ProjectDetection;
+/** Parse signals from a directory listing. */
+export declare function parseSignals(entries: string[]): string[];
+//# sourceMappingURL=detector.d.ts.map

package/packages/doc-generator/dist/detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detector.d.ts","sourceRoot":"","sources":["../src/detector.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAe,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAiEhE,qDAAqD;AACrD,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,gBAAgB,CAqCvE;AAED,8CAA8C;AAC9C,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAExD"}

package/packages/doc-generator/dist/detector.js

@@ -0,0 +1,98 @@
+/**
+ * Doc Generator — Project Detection (RFC-0014)
+ */
+const SIGNALS = {
+    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 = {
+    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 = {
+    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) {
+    const scores = {
+        frappe_erpnext: 0,
+        frappe_spa: 0,
+        nextjs: 0,
+        react_vite: 0,
+        django: 0,
+        laravel: 0,
+        generic_web: 0,
+        unknown: 0,
+    };
+    const signals = [];
+    for (const filePath of filePaths) {
+        for (const [pType, pSignals] of Object.entries(SIGNALS)) {
+            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] : "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) {
+    return entries.filter((e) => /[./]/.test(e));
+}
+//# sourceMappingURL=detector.js.map

package/packages/doc-generator/dist/detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detector.js","sourceRoot":"","sources":["../src/detector.ts"],"names":[],"mappings":"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"}

package/packages/doc-generator/dist/docs.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Doc Generator — Documentation Generation (RFC-0014)
+ */
+import type { DetectedSymbol, GeneratedDocs, SourceFile } from "./types.js";
+/** Detect exported symbols in a source file. */
+export declare function detectSymbols(source: SourceFile): DetectedSymbol[];
+/** Generate documentation for a list of source files. */
+export declare function generateDocs(sources: SourceFile[], projectSignals: string[]): GeneratedDocs;
+//# sourceMappingURL=docs.d.ts.map

package/packages/doc-generator/dist/docs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.d.ts","sourceRoot":"","sources":["../src/docs.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACX,cAAc,EACd,aAAa,EAEb,UAAU,EACV,MAAM,YAAY,CAAC;AAGpB,gDAAgD;AAChD,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,cAAc,EAAE,CAoElE;AA+BD,yDAAyD;AACzD,wBAAgB,YAAY,CAC3B,OAAO,EAAE,UAAU,EAAE,EACrB,cAAc,EAAE,MAAM,EAAE,GACtB,aAAa,CAyCf"}

package/packages/doc-generator/dist/docs.js

@@ -0,0 +1,132 @@
+/**
+ * Doc Generator — Documentation Generation (RFC-0014)
+ */
+import { detectProjectType } from "./detector.js";
+/** Detect exported symbols in a source file. */
+export function detectSymbols(source) {
+    const symbols = [];
+    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, index) {
+    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) {
+    const counts = {};
+    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) {
+    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, projectSignals) {
+    const detection = detectProjectType(projectSignals);
+    const allSymbols = sources.flatMap(detectSymbols);
+    const sections = [
+        {
+            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,
+    };
+}
+//# sourceMappingURL=docs.js.map

package/packages/doc-generator/dist/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../src/docs.ts"],"names":[],"mappings":"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"}

package/packages/doc-generator/dist/index.d.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";
+//# sourceMappingURL=index.d.ts.map

package/packages/doc-generator/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACxD,mBAAmB,YAAY,CAAC"}

package/packages/doc-generator/dist/index.js

@@ -0,0 +1,6 @@
+/**
+ * Doc Generator — Main Entry (RFC-0014)
+ */
+export { detectProjectType, parseSignals } from "./detector.js";
+export { detectSymbols, generateDocs } from "./docs.js";
+//# sourceMappingURL=index.js.map

package/packages/doc-generator/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC"}

package/packages/doc-generator/dist/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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";
+//# sourceMappingURL=types.d.ts.map

package/packages/doc-generator/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,WAAW,GACpB,gBAAgB,GAChB,YAAY,GACZ,QAAQ,GACR,YAAY,GACZ,QAAQ,GACR,SAAS,GACT,aAAa,GACb,SAAS,CAAC;AAEb,MAAM,WAAW,gBAAgB;IAChC,WAAW,EAAE,WAAW,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,uBAAuB,EAAE,MAAM,CAAC;IAChC,sBAAsB,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,GAAG,OAAO,GAAG,WAAW,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,WAAW,EAAE,WAAW,CAAC;CACzB;AAED,MAAM,WAAW,UAAU;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,YAAY,GACrB,mBAAmB,GACnB,iBAAiB,GACjB,gBAAgB,GAChB,WAAW,GACX,mBAAmB,GACnB,iBAAiB,GACjB,eAAe,CAAC"}

package/packages/doc-generator/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Doc Generator Types (RFC-0014)
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/packages/doc-generator/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/packages/doc-generator/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@pi-harness/doc-generator",
+  "version": "0.9.6",
+  "description": "Auto-Doc Generator — generate documentation from source code (RFC-0014)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "bun-types": "^1.0.0"
+  }
+}