frappe-builder 1.1.0-dev.8 → 1.1.0-dev.9

package/dist/cli.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { t as loadCredentials } from "./loader-DC2PlJU7.mjs";
+import { n as setSessionsDir, t as db } from "./db-Cx_EyUEu.mjs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { mkdirSync } from "node:fs";
+//#region src/cli.ts
+/**
+* src/cli.ts — standalone binary entry point for frappe-builder
+*
+* Built with: bun build --compile --minify src/cli.ts --outfile frappe-builder
+* ESM top-level await is supported by bun compile.
+*
+* Extension load order is critical — do NOT reorder imports.
+* frappe-session must reconstruct state before FSM guard or tools activate.
+*/
+const cmd = process.argv[2];
+if (cmd === "init") {
+	const { runInit } = await import("./init-ChmHonBN.mjs");
+	await runInit();
+	process.exit(0);
+}
+if (cmd === "--help" || cmd === "-h") {
+	console.log(`
+Usage: frappe-builder [command]
+
+Commands:
+  init    Configure frappe-builder for this project (run once per project)
+  (none)  Start a frappe-builder session
+
+Options:
+  --help, -h   Show this help message
+`);
+	process.exit(0);
+}
+const SESSION_LOG_DIR = join(homedir(), ".frappe-builder", "sessions");
+mkdirSync(SESSION_LOG_DIR, { recursive: true });
+setSessionsDir(SESSION_LOG_DIR);
+process.on("SIGINT", () => {
+	try {
+		db.close();
+	} catch {}
+	process.exit(0);
+});
+process.on("SIGTERM", () => {
+	try {
+		db.close();
+	} catch {}
+	process.exit(0);
+});
+try {
+	loadCredentials(process.cwd());
+} catch (err) {
+	console.error(err.message);
+	process.exit(1);
+}
+await import("./frappe-session-BfFveYq1.mjs");
+await import("./frappe-state-k--gX3wq.mjs");
+await import("./frappe-workflow-VId2tr9e.mjs");
+await import("./frappe-tools-Dwz0eEQ-.mjs");
+await import("./frappe-gates-c4HHJp-4.mjs");
+await import("./frappe-ui-htmQgO8t.mjs");
+//#endregion
+export {};

package/dist/coverage-check-DLGO_qwW.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import { execa } from "execa";
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+//#region gates/coverage-check.ts
+/**
+* gates/coverage-check.ts — Async coverage gate (NOT a pure function).
+* Runs `bench run-tests --coverage` via execa and parses the result.
+*
+* NOT wired via frappe-gates.ts — integrated directly in completeComponent().
+* Triggers when the final component is completed in `testing` phase. (FR29)
+*/
+var coverage_check_exports = /* @__PURE__ */ __exportAll({ coverageCheck: () => coverageCheck });
+function parseCoverage(stdout) {
+	const match = stdout.match(/^TOTAL\s+\d+\s+\d+\s+(\d+)%/m);
+	return match ? parseInt(match[1], 10) : 0;
+}
+async function coverageCheck(_context) {
+	try {
+		const { stdout } = await execa("bench", ["run-tests", "--coverage"], {
+			cwd: process.env.FRAPPE_BENCH_PATH ?? process.cwd(),
+			reject: false,
+			timeout: 12e4
+		});
+		const coverage = parseCoverage(stdout ?? "");
+		if (coverage < 70) return {
+			passed: false,
+			coverage,
+			required: "70%"
+		};
+		return {
+			passed: true,
+			coverage
+		};
+	} catch (err) {
+		return {
+			passed: false,
+			coverage: 0,
+			required: "70%",
+			error: err.message
+		};
+	}
+}
+//#endregion
+export { __exportAll as n, coverage_check_exports as t };

package/dist/db-Cx_EyUEu.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import "node:os";
+import "node:path";
+import { mkdirSync } from "node:fs";
+import Database from "better-sqlite3";
+//#region state/schema.ts
+/**
+* Runs all CREATE TABLE IF NOT EXISTS statements against the provided database.
+* Safe to call multiple times — idempotent by design.
+*/
+function initSchema(db) {
+	db.exec(`
+    CREATE TABLE IF NOT EXISTS features (
+      feature_id     TEXT PRIMARY KEY,
+      name           TEXT NOT NULL,
+      mode           TEXT NOT NULL DEFAULT 'full' CHECK (mode IN ('full', 'quick')),
+      current_phase  TEXT NOT NULL DEFAULT 'idle',
+      created_at     TEXT NOT NULL,
+      updated_at     TEXT,
+      progress_done  INTEGER DEFAULT 0,
+      progress_total INTEGER DEFAULT 0
+    );
+
+    CREATE TABLE IF NOT EXISTS components (
+      component_id TEXT NOT NULL,
+      feature_id   TEXT NOT NULL,
+      status       TEXT NOT NULL DEFAULT 'in-progress',
+      completed_at TEXT,
+      PRIMARY KEY (feature_id, component_id),
+      FOREIGN KEY (feature_id) REFERENCES features(feature_id)
+    );
+
+    CREATE TABLE IF NOT EXISTS sessions (
+      session_id    TEXT PRIMARY KEY,
+      project_id    TEXT NOT NULL,
+      current_phase TEXT NOT NULL DEFAULT 'idle',
+      site_path     TEXT,
+      feature_id    TEXT,
+      last_tool     TEXT,
+      started_at    TEXT NOT NULL,
+      ended_at      TEXT,
+      is_active     INTEGER NOT NULL DEFAULT 1
+    );
+  `);
+}
+/**
+* Overrides the sessions directory — intended for test use only.
+* Pass null to reset to the default ~/.frappe-builder/sessions path.
+*/
+function setSessionsDir(dir) {}
+//#endregion
+//#region state/db.ts
+mkdirSync(".fb", { recursive: true });
+/** Singleton SQLite connection — the only Database instance in the codebase. */
+let db = new Database(".fb/state.db");
+initSchema(db);
+//#endregion
+export { setSessionsDir as n, db as t };

package/dist/frappe-gates-c4HHJp-4.mjs

@@ -0,0 +1,349 @@
+#!/usr/bin/env node
+import { n as __exportAll, t as coverage_check_exports } from "./coverage-check-DLGO_qwW.mjs";
+import "./db-Cx_EyUEu.mjs";
+import path from "node:path";
+//#region gates/frappe-native-check.ts
+const NON_NATIVE_PATTERNS = [
+	{
+		pattern: /import\s+axios/,
+		label: "axios (use frappe.call)"
+	},
+	{
+		pattern: /require\(['"]axios['"]\)/,
+		label: "axios (use frappe.call)"
+	},
+	{
+		pattern: /import\s+requests/,
+		label: "requests (use frappe.call)"
+	},
+	{
+		pattern: /from\s+requests\s+import/,
+		label: "requests (use frappe.call)"
+	},
+	{
+		pattern: /cursor\.execute\s*\(/,
+		label: "raw SQL cursor (use frappe.db.sql or ORM)"
+	},
+	{
+		pattern: /pymysql|psycopg2|sqlite3\.connect/,
+		label: "direct DB driver (use Frappe ORM)"
+	},
+	{
+		pattern: /mongoose|sequelize|typeorm/i,
+		label: "external ORM (use Frappe DocType)"
+	},
+	{
+		pattern: /jwt\.sign|jsonwebtoken/,
+		label: "JWT auth (use frappe.whitelist + session)"
+	},
+	{
+		pattern: /passport\.authenticate/,
+		label: "passport auth (use Frappe auth)"
+	},
+	{
+		pattern: /import\s+pandas/,
+		label: "pandas (use Frappe Script Report)"
+	},
+	{
+		pattern: /import\s+numpy/,
+		label: "numpy (use Frappe computation)"
+	},
+	{
+		pattern: /fs\.writeFileSync|fs\.readFileSync/,
+		label: "raw fs (use frappe.get_file_url or File DocType)"
+	},
+	{
+		pattern: /express\(\)|fastapi|flask\.Flask/,
+		label: "external web framework (use Frappe whitelist)"
+	}
+];
+/**
+* Scans `content` for non-Frappe-native patterns.
+*
+* - No detected patterns → { passed: true }
+* - Detected + no justification → { passed: false, requiresJustification: true, ... }
+* - Detected + justification provided → { passed: true, result: "override", ... }
+*/
+function checkFrappeNative(content, justification) {
+	const detectedPatterns = NON_NATIVE_PATTERNS.filter(({ pattern }) => pattern.test(content)).map(({ label }) => label);
+	if (detectedPatterns.length === 0) return { passed: true };
+	if (justification) return {
+		passed: true,
+		result: "override",
+		justification,
+		detectedPatterns
+	};
+	return {
+		passed: false,
+		requiresJustification: true,
+		message: "This uses a non-Frappe-native approach. Justification required to proceed.",
+		detectedPatterns
+	};
+}
+//#endregion
+//#region gates/permission-check.ts
+var permission_check_exports = /* @__PURE__ */ __exportAll({ permissionCheck: () => permissionCheck });
+const PERMISSION_PATTERNS = [
+	/frappe\.has_permission\s*\(/,
+	/frappe\.only_for\s*\(/,
+	/frappe\.check_permission\s*\(/,
+	/frappe\.has_role\s*\(/,
+	/frappe\.session\.user/
+];
+function getLineNumber(code, offset) {
+	return code.slice(0, offset).split("\n").length;
+}
+function extractFunctionBody(code, defStart) {
+	const bodyStart = code.indexOf("\n", defStart) + 1;
+	const nextTopLevel = /\n(?=def |class |@)/g;
+	nextTopLevel.lastIndex = bodyStart;
+	const match = nextTopLevel.exec(code);
+	return match ? code.slice(bodyStart, match.index) : code.slice(bodyStart);
+}
+function hasPermissionCheck(body) {
+	return PERMISSION_PATTERNS.some((p) => p.test(body));
+}
+function permissionCheck(code, context) {
+	if (!context.file.endsWith(".py")) return { passed: true };
+	const WHITELIST_DECORATOR = /@frappe\.whitelist\([^)]*\)\s*\ndef\s+(\w+)/g;
+	const violations = [];
+	let match;
+	while ((match = WHITELIST_DECORATOR.exec(code)) !== null) {
+		const decoratorOffset = match.index;
+		const methodName = match[1];
+		const line = getLineNumber(code, decoratorOffset);
+		if (!hasPermissionCheck(extractFunctionBody(code, code.indexOf("\ndef ", decoratorOffset) + 1))) violations.push({
+			method: methodName,
+			line,
+			reason: "missing permission check"
+		});
+	}
+	if (violations.length > 0) return {
+		passed: false,
+		violations
+	};
+	return { passed: true };
+}
+//#endregion
+//#region gates/query-check.ts
+var query_check_exports = /* @__PURE__ */ __exportAll({ queryCheck: () => queryCheck });
+const SQL_KEYWORD = /\b(SELECT|INSERT|UPDATE|DELETE|FROM|WHERE)\b/i;
+const INJECTION_PATTERNS = [
+	{
+		pattern: /f["'].*\{[^}]+\}.*["']/,
+		label: "f-string interpolation"
+	},
+	{
+		pattern: /["']\s*\+\s*\w/,
+		label: "string concatenation (+)"
+	},
+	{
+		pattern: /["']\s*%\s*\w/,
+		label: "%-format interpolation"
+	}
+];
+const REASON$1 = "SQL string concatenation detected — use parameterised queries";
+function queryCheck(code, context) {
+	if (!context.file.endsWith(".py")) return { passed: true };
+	const lines = code.split("\n");
+	const violations = [];
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		if (!SQL_KEYWORD.test(line)) continue;
+		for (const { pattern, label } of INJECTION_PATTERNS) if (pattern.test(line)) {
+			violations.push({
+				line: i + 1,
+				pattern: label,
+				reason: REASON$1
+			});
+			break;
+		}
+	}
+	return violations.length > 0 ? {
+		passed: false,
+		violations
+	} : { passed: true };
+}
+//#endregion
+//#region gates/server-side-check.ts
+var server_side_check_exports = /* @__PURE__ */ __exportAll({ serverSideCheck: () => serverSideCheck });
+const BUSINESS_LOGIC_PATTERNS = [
+	{
+		pattern: /frm\.doc\.\w+\s*=\s*frm\.doc\.\w+\s*[*\/+\-]\s*frm\.doc\.\w+/,
+		label: "client-side financial calculation"
+	},
+	{
+		pattern: /frappe\.session\.user\s*[=!]={1,2}\s*["']/,
+		label: "client-side permission decision (user identity)"
+	},
+	{
+		pattern: /frappe\.user\.has_role\s*\(/,
+		label: "client-side permission decision (role check)"
+	},
+	{
+		pattern: /frappe\.user_roles\b/,
+		label: "client-side permission decision (user_roles)"
+	},
+	{
+		pattern: /frappe\.db\.(get_value|get_list|set_value|insert|delete_doc)\s*\(/,
+		label: "direct DB access from client-side (use frappe.call instead)"
+	}
+];
+const REASON = "business logic must be server-side";
+function isTestFile(file) {
+	return file.includes("/test/") || file.includes(".test.") || file.includes(".spec.");
+}
+function serverSideCheck(code, context) {
+	if (!context.file.endsWith(".js") && !context.file.endsWith(".ts")) return { passed: true };
+	if (isTestFile(context.file)) return { passed: true };
+	const lines = code.split("\n");
+	const violations = [];
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		for (const { pattern, label } of BUSINESS_LOGIC_PATTERNS) if (pattern.test(line)) {
+			violations.push({
+				line: i + 1,
+				pattern: label,
+				reason: REASON
+			});
+			break;
+		}
+	}
+	return violations.length > 0 ? {
+		passed: false,
+		violations
+	} : { passed: true };
+}
+//#endregion
+//#region gates/style-check.ts
+var style_check_exports = /* @__PURE__ */ __exportAll({ styleCheck: () => styleCheck });
+const DEF_LINE = /^([^\S\n]*)def\s+(\w+)\s*\([^)]*\)\s*:/gm;
+const NON_DESCRIPTIVE = /^(\s*)(x|y|z|data|temp|tmp|val|var|foo|bar|test|obj|res|ret)\s*=/gm;
+const SQL_STRING = /frappe\.db\.sql\s*\(\s*["'`]{1,3}([\s\S]*?)["'`]{1,3}/g;
+const CAMEL_IDENTIFIER = /\b([a-z][a-zA-Z0-9]*[A-Z][a-zA-Z0-9]*)\b/g;
+const STUB_BODY = /^\s*(pass|return|return None|super\(\)\.__init__\(.*?\))\s*$/;
+function lineNumber(code, index) {
+	return code.slice(0, index).split("\n").length;
+}
+function hasDocstring(code, defStart) {
+	const bodyStart = code.indexOf("\n", defStart) + 1;
+	const bodyTrimmed = code.slice(bodyStart).trimStart();
+	return bodyTrimmed.startsWith("\"\"\"") || bodyTrimmed.startsWith("'''");
+}
+function isStubBody(code, defStart) {
+	const newline = code.indexOf("\n", defStart);
+	if (newline === -1) return true;
+	const nextNewline = code.indexOf("\n", newline + 1);
+	const bodyLine = nextNewline === -1 ? code.slice(newline + 1) : code.slice(newline + 1, nextNewline);
+	return STUB_BODY.test(bodyLine);
+}
+function checkPython(code, violations) {
+	let m;
+	DEF_LINE.lastIndex = 0;
+	while ((m = DEF_LINE.exec(code)) !== null) {
+		const fnName = m[2];
+		const defStart = m.index;
+		if (!hasDocstring(code, defStart) && !isStubBody(code, defStart)) violations.push({
+			function: fnName,
+			line: lineNumber(code, defStart),
+			reason: "missing docstring"
+		});
+	}
+	NON_DESCRIPTIVE.lastIndex = 0;
+	while ((m = NON_DESCRIPTIVE.exec(code)) !== null) {
+		const varName = m[2];
+		violations.push({
+			line: lineNumber(code, m.index),
+			variable: varName,
+			reason: "non-descriptive variable name"
+		});
+	}
+	SQL_STRING.lastIndex = 0;
+	while ((m = SQL_STRING.exec(code)) !== null) {
+		const sqlContent = m[1];
+		const sqlStart = m.index;
+		CAMEL_IDENTIFIER.lastIndex = 0;
+		let cm;
+		while ((cm = CAMEL_IDENTIFIER.exec(sqlContent)) !== null) violations.push({
+			line: lineNumber(code, sqlStart),
+			column: cm[1],
+			reason: "SQL column must be snake_case"
+		});
+	}
+}
+function checkFilename(context, violations) {
+	const basename = path.basename(context.file).replace(/\.(test|spec)\.(ts|js)$/, "").replace(/\.(ts|js)$/, "");
+	if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(basename)) violations.push({
+		file: context.file,
+		reason: "TypeScript filename must be kebab-case"
+	});
+}
+function styleCheck(code, context) {
+	const violations = [];
+	const ext = path.extname(context.file);
+	if (ext === ".py") checkPython(code, violations);
+	else if (ext === ".ts" || ext === ".js") checkFilename(context, violations);
+	if (violations.length > 0) return {
+		passed: false,
+		violations
+	};
+	return { passed: true };
+}
+//#endregion
+//#region extensions/frappe-gates.ts
+function nativeAdapter(code, _context) {
+	const r = checkFrappeNative(code);
+	if (r.passed) return { passed: true };
+	return {
+		passed: false,
+		violations: [{
+			reason: r.message,
+			detectedPatterns: r.detectedPatterns
+		}]
+	};
+}
+function tryLoadGate(mod, exportName, gateName) {
+	const fn = mod[exportName];
+	if (typeof fn === "function") return {
+		name: gateName,
+		fn
+	};
+	console.warn(`[GATE WARNING: ${gateName} gate not yet implemented — skipping]`);
+	return null;
+}
+const GATE_REGISTRY = [{
+	name: "frappe_native",
+	fn: nativeAdapter
+}];
+for (const [mod, exportName, gateName] of [
+	[
+		permission_check_exports,
+		"permissionCheck",
+		"permission_check"
+	],
+	[
+		query_check_exports,
+		"queryCheck",
+		"query_check"
+	],
+	[
+		server_side_check_exports,
+		"serverSideCheck",
+		"server_side_check"
+	],
+	[
+		coverage_check_exports,
+		"coverageCheck",
+		"coverage_check"
+	],
+	[
+		style_check_exports,
+		"styleCheck",
+		"style_check"
+	]
+]) {
+	const entry = tryLoadGate(mod, exportName, gateName);
+	if (entry) GATE_REGISTRY.push(entry);
+}
+//#endregion
+export {};

package/dist/frappe-session-BfFveYq1.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import "./db-Cx_EyUEu.mjs";
+import "./fsm-DkLob1CA.mjs";
+import "./frappe-session-BzM5oUCb.mjs";
+export {};

package/dist/frappe-session-BzM5oUCb.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import "node:os";
+import "node:path";
+import "node:fs";
+export {};

package/dist/frappe-state-k--gX3wq.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import "./loader-DC2PlJU7.mjs";
+import "./db-Cx_EyUEu.mjs";
+import "./fsm-DkLob1CA.mjs";
+import "./frappe-session-BzM5oUCb.mjs";
+export {};

package/dist/frappe-tools-Dwz0eEQ-.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import "./coverage-check-DLGO_qwW.mjs";
+import "./loader-DC2PlJU7.mjs";
+import "./db-Cx_EyUEu.mjs";
+import "./fsm-DkLob1CA.mjs";
+import "./frappe-session-BzM5oUCb.mjs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import "node:fs";
+import "execa";
+join(join(homedir(), ".frappe-builder"), "allowed-commands.json");
+//#endregion
+export {};

package/dist/frappe-ui-htmQgO8t.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import "./db-Cx_EyUEu.mjs";
+export {};

package/dist/frappe-workflow-VId2tr9e.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import "./db-Cx_EyUEu.mjs";
+import "./fsm-DkLob1CA.mjs";
+export {};

package/dist/fsm-DkLob1CA.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import "robot3";
+export {};

package/dist/init-ChmHonBN.mjs

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { createInterface } from "node:readline";
+//#region src/init.ts
+/**
+* src/init.ts — interactive setup wizard for frappe-builder
+*
+* Handles: global config (~/.frappe-builder/config.json),
+*          project config (.frappe-builder-config.json),
+*          and .gitignore patching.
+*
+* No imports from state/, extensions/, or gates/.
+* Uses Node.js built-ins only — no external prompt libraries.
+*/
+let cancelled = false;
+process.on("SIGINT", () => {
+	cancelled = true;
+});
+function promptLine(question) {
+	return new Promise((resolve) => {
+		if (cancelled) {
+			resolve("");
+			return;
+		}
+		const rl = createInterface({
+			input: process.stdin,
+			output: process.stdout
+		});
+		rl.question(question, (answer) => {
+			rl.close();
+			resolve(answer);
+		});
+	});
+}
+async function promptYN(question) {
+	const answer = await promptLine(question + " (y/N): ");
+	return answer.trim().toLowerCase() === "y" || answer.trim().toLowerCase() === "yes";
+}
+function writeAtomic(filePath, content) {
+	const tmp = filePath + ".tmp";
+	writeFileSync(tmp, content, "utf-8");
+	renameSync(tmp, filePath);
+}
+/** Patches .gitignore to include the exact entry if not already present. */
+function patchGitignore(projectRoot, entry) {
+	const gitignorePath = join(projectRoot, ".gitignore");
+	if (!existsSync(gitignorePath)) {
+		writeFileSync(gitignorePath, entry + "\n", "utf-8");
+		return "created";
+	}
+	const content = readFileSync(gitignorePath, "utf-8");
+	if (content.split("\n").includes(entry)) return "already-present";
+	writeFileSync(gitignorePath, content.endsWith("\n") ? content + entry + "\n" : content + "\n" + entry + "\n", "utf-8");
+	return "patched";
+}
+async function runInit(opts = {}) {
+	const projectRoot = opts.projectRoot ?? process.cwd();
+	const globalConfigDir = join(homedir(), ".frappe-builder");
+	const globalConfigPath = join(globalConfigDir, "config.json");
+	const projectConfigPath = join(projectRoot, ".frappe-builder-config.json");
+	console.log("\n=== frappe-builder Setup ===\n");
+	console.log(`[Global config: ${globalConfigPath}]`);
+	let globalConfig = {};
+	let globalAction = "written";
+	if (existsSync(globalConfigPath)) {
+		try {
+			globalConfig = JSON.parse(readFileSync(globalConfigPath, "utf-8"));
+		} catch {}
+		if (!cancelled) {
+			const overwrite = await promptYN(`Overwrite existing ${globalConfigPath}?`);
+			if (cancelled) {
+				printCancelled();
+				return;
+			}
+			if (!overwrite) {
+				globalAction = "skipped";
+				console.log("  Keeping existing global config.\n");
+			}
+		}
+	}
+	if (!cancelled && globalAction === "written") {
+		const llmKey = await promptLine("LLM API key (leave blank to skip): ");
+		if (cancelled) {
+			printCancelled();
+			return;
+		}
+		globalConfig.llm_api_key = llmKey.trim();
+	}
+	console.log(`\n[Project config: ${projectConfigPath}]`);
+	let projectConfig = {};
+	let projectAction = "written";
+	if (existsSync(projectConfigPath)) {
+		try {
+			projectConfig = JSON.parse(readFileSync(projectConfigPath, "utf-8"));
+		} catch {}
+		if (!cancelled) {
+			const overwrite = await promptYN(`Overwrite existing ${projectConfigPath}?`);
+			if (cancelled) {
+				printCancelled();
+				return;
+			}
+			if (!overwrite) {
+				projectAction = "skipped";
+				console.log("  Keeping existing project config.\n");
+			}
+		}
+	}
+	if (!cancelled && projectAction === "written") {
+		const siteUrl = await promptLine("Frappe site URL (e.g. http://site1.localhost): ");
+		if (cancelled) {
+			printCancelled();
+			return;
+		}
+		const apiKey = await promptLine("Frappe API key: ");
+		if (cancelled) {
+			printCancelled();
+			return;
+		}
+		const apiSecret = await promptLine("Frappe API secret: ");
+		if (cancelled) {
+			printCancelled();
+			return;
+		}
+		projectConfig = {
+			site_url: siteUrl.trim(),
+			api_key: apiKey.trim(),
+			api_secret: apiSecret.trim()
+		};
+	}
+	const written = [];
+	const skipped = [];
+	if (globalAction === "written") {
+		mkdirSync(globalConfigDir, { recursive: true });
+		writeAtomic(globalConfigPath, JSON.stringify(globalConfig, null, 2) + "\n");
+		written.push(`~/.frappe-builder/config.json`);
+	} else skipped.push(`~/.frappe-builder/config.json`);
+	if (projectAction === "written") {
+		writeAtomic(projectConfigPath, JSON.stringify(projectConfig, null, 2) + "\n");
+		written.push(`.frappe-builder-config.json`);
+	} else skipped.push(`.frappe-builder-config.json`);
+	const gitignoreResult = patchGitignore(projectRoot, ".frappe-builder-config.json");
+	if (gitignoreResult === "patched") written.push(".gitignore (patched)");
+	else if (gitignoreResult === "created") written.push(".gitignore (created)");
+	else skipped.push(".gitignore (entry already present)");
+	console.log("\nFiles written:");
+	for (const f of written) console.log(`  ✓ ${f}`);
+	if (skipped.length > 0) {
+		console.log("Skipped:");
+		for (const f of skipped) console.log(`  - ${f}`);
+	}
+	console.log("\nReady. Run: frappe-builder\n");
+}
+function printCancelled() {
+	console.log("\nSetup cancelled. No files were written.\n");
+}
+//#endregion
+export { runInit };

package/dist/loader-DC2PlJU7.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+//#region config/loader.ts
+/** Always ~/.frappe-builder/sessions/ — never the project directory (NFR9). */
+const SESSION_LOG_DIR = join(homedir(), ".frappe-builder", "sessions");
+const GITIGNORE_ERROR = "Site credentials file is not gitignored. Add .frappe-builder-config.json to .gitignore before proceeding.";
+/**
+* Validates that {projectRoot}/.gitignore lists .frappe-builder-config.json.
+* Throws with the exact AC error message if missing or absent.
+*/
+function validateGitignore(projectRoot) {
+	const gitignorePath = join(projectRoot, ".gitignore");
+	if (!existsSync(gitignorePath)) throw new Error(GITIGNORE_ERROR);
+	if (!readFileSync(gitignorePath, "utf8").split("\n").map((l) => l.trim()).includes(".frappe-builder-config.json")) throw new Error(GITIGNORE_ERROR);
+}
+/**
+* Reads LLM API keys from ~/.frappe-builder/config.json (user-global, never project).
+* Creates ~/.frappe-builder/ on first run. Returns empty defaults if file absent.
+*/
+function loadGlobalConfig() {
+	const configDir = join(homedir(), ".frappe-builder");
+	mkdirSync(configDir, { recursive: true });
+	const configPath = join(configDir, "config.json");
+	if (!existsSync(configPath)) return { llm_api_key: "" };
+	try {
+		return JSON.parse(readFileSync(configPath, "utf8"));
+	} catch {
+		return { llm_api_key: "" };
+	}
+}
+/**
+* Reads Frappe site credentials from {projectRoot}/.frappe-builder-config.json.
+* Returns empty defaults if file absent (caller should surface a warning).
+*/
+function loadProjectConfig(projectRoot) {
+	const configPath = join(projectRoot, ".frappe-builder-config.json");
+	if (!existsSync(configPath)) return {
+		site_url: "",
+		api_key: "",
+		api_secret: ""
+	};
+	try {
+		return JSON.parse(readFileSync(configPath, "utf8"));
+	} catch {
+		return {
+			site_url: "",
+			api_key: "",
+			api_secret: ""
+		};
+	}
+}
+/**
+* Full credential loader: validates gitignore, loads global + project configs.
+* Throws if .frappe-builder-config.json is not gitignored.
+* API keys are only ever read from ~/.frappe-builder/ — never from projectRoot.
+*/
+function loadCredentials(projectRoot) {
+	validateGitignore(projectRoot);
+	return {
+		global: loadGlobalConfig(),
+		project: loadProjectConfig(projectRoot),
+		sessionLogDir: SESSION_LOG_DIR
+	};
+}
+//#endregion
+export { loadCredentials as t };

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "frappe-builder",
-  "version": "1.1.0-dev.8",
+  "version": "1.1.0-dev.9",
   "description": "Frappe-native AI co-pilot for building and customising Frappe/ERPNext applications",
   "type": "module",
+  "bin": {
+    "frappe-builder": "./dist/cli.mjs"
+  },
   "pi": {
     "_note": "TODO: verify 'pi' field schema against @mariozechner/pi-agent-core docs — no schema found in installed package. Reference schema below is a best-guess pending confirmation.",
     "extensions": [

package/tsdown.config.ts

@@ -3,4 +3,5 @@ import { defineConfig } from "tsdown";
 export default defineConfig({
   entry: ["src/cli.ts"],
   format: "esm",
+  banner: { js: "#!/usr/bin/env node" },
 });