@posthog/wizard 2.36.0 → 2.38.0

package/dist/wizard-tools-CGrE1O_b.js

@@ -0,0 +1,1107 @@
+import { f as skillTmpPath, s as logToFile } from "./debug-CgdI7Rd-.js";
+import { t as analytics } from "./analytics-CvIK_07d.js";
+import * as fs$1 from "fs";
+import fs from "fs";
+import * as path$1 from "path";
+import path from "path";
+import { z } from "zod";
+import { execFileSync } from "child_process";
+import { randomUUID } from "crypto";
+//#region src/utils/atomic-ledger.ts
+/**
+* Small shared primitives for on-disk ledgers: an atomic JSON writer and a
+* single-chain async mutex. Used by the audit tools and by the orchestrator
+* queue. Lifted here so both share one implementation.
+*/
+/**
+* Atomically write JSON: write to a `.tmp` file then rename over the target. The
+* rename bumps the file's mtime in one step, which is what a file watcher polls.
+*/
+function writeJsonAtomic(targetPath, data) {
+	const tmpPath = `${targetPath}.tmp`;
+	fs$1.writeFileSync(tmpPath, JSON.stringify(data, null, 2), "utf8");
+	fs$1.renameSync(tmpPath, targetPath);
+}
+/**
+* A single async mutex. Serializes read-modify-write cycles so concurrent callers
+* (parallel task agents, audit tool calls) never interleave a mutation.
+*/
+function makeMutex() {
+	let chain = Promise.resolve();
+	return async function run(fn) {
+		const next = chain.then(() => fn());
+		chain = next.catch(() => void 0);
+		return next;
+	};
+}
+//#endregion
+//#region src/lib/programs/audit/types.ts
+/** Single source of truth for status glyph + color across audit views. */
+const AUDIT_SEVERITY_STYLE = {
+	pending: {
+		glyph: "◌",
+		color: "gray"
+	},
+	pass: {
+		glyph: "✔",
+		color: "green"
+	},
+	error: {
+		glyph: "✘",
+		color: "red"
+	},
+	warning: {
+		glyph: "⚠",
+		color: "yellow"
+	},
+	suggestion: {
+		glyph: "•",
+		color: "cyan"
+	}
+};
+const AUDIT_CHECKS_FILE = ".posthog-audit-checks.json";
+const AUDIT_REPORT_FILE = "posthog-audit-report.md";
+const AUDIT_CHECKS_KEY = "auditChecks";
+function getAuditChecks(session) {
+	const raw = session.frameworkContext[AUDIT_CHECKS_KEY];
+	return Array.isArray(raw) ? raw : [];
+}
+/**
+* Read the audit checks ledger off disk. Validation lives at write time —
+* every writer (`audit_seed_checks` / `audit_add_checks` / `audit_resolve_checks`
+* MCP tools, `seedAuditLedger`) zod-parses entries before the atomic write,
+* so by the time the file watcher fires we trust the shape and only guard
+* against the file not being a JSON array (corrupted / hand-edited / not yet
+* seeded).
+*/
+function coerceAuditChecks(parsed) {
+	return Array.isArray(parsed) ? parsed : [];
+}
+//#endregion
+//#region src/lib/wizard-ask-bridge.ts
+/**
+* WizardAskBridge — host-side promise broker for the `wizard_ask` MCP tool.
+*
+* The `wizard_ask` tool needs to (a) read information from the wizard
+* session (the active skill id, used as the analytics `source`) and
+* (b) drive the TUI overlay. Wiring `wizard-tools.ts` directly to either
+* would couple our pure-data MCP server to the runtime UI layer.
+*
+* The bridge is the seam: `wizard-tools.ts` depends on this interface,
+* and `agent-runner.ts` constructs an implementation that knows about
+* both the session and `getUI()`.
+*/
+/** Sentinel returned for unanswered fields on cancellation or timeout. */
+const CANCELLED_SENTINEL = "__cancelled__";
+function buildCancelledAnswers(questions) {
+	const out = {};
+	for (const q of questions) out[q.id] = CANCELLED_SENTINEL;
+	return out;
+}
+function isFullyCancelled(answers) {
+	const values = Object.values(answers);
+	if (values.length === 0) return false;
+	return values.every((v) => v === CANCELLED_SENTINEL);
+}
+function createWizardAskBridge(opts) {
+	const timeoutMs = opts.timeoutMs ?? 3e5;
+	return { async request({ questions }) {
+		const pending = {
+			id: randomUUID(),
+			questions,
+			source: opts.getSource(),
+			richLinks: opts.richLinks ?? false
+		};
+		const startedAt = Date.now();
+		let timer;
+		const timeoutPromise = new Promise((resolve) => {
+			timer = setTimeout(() => {
+				resolve(buildCancelledAnswers(questions));
+			}, timeoutMs);
+		});
+		try {
+			const answers = await Promise.race([opts.showQuestion(pending), timeoutPromise]);
+			const durationMs = Date.now() - startedAt;
+			if (isFullyCancelled(answers)) analytics.wizardCapture("wizard_ask cancelled", {
+				source: pending.source,
+				question_count: questions.length,
+				duration_ms: durationMs,
+				timed_out: durationMs >= timeoutMs
+			});
+			else analytics.wizardCapture("wizard_ask answered", {
+				source: pending.source,
+				question_count: questions.length,
+				duration_ms: durationMs
+			});
+			return answers;
+		} finally {
+			if (timer) clearTimeout(timer);
+		}
+	} };
+}
+//#endregion
+//#region src/lib/secret-vault.ts
+/**
+* Session-scoped secret vault.
+*
+* Tools that handle sensitive values (personal API keys pasted by the user
+* or minted by the wizard, OAuth tokens, etc.) store them here and return
+* an opaque `secret:<uuid>` ref to the agent. The agent passes the ref
+* around to subsequent tools — `set_env_values` resolves it host-side
+* before writing — but the raw value never enters the LLM conversation.
+*
+* The vault is created once per `createWizardToolsServer` call and lives
+* for the duration of a single wizard run. There is no persistence and
+* no cross-session sharing; refs minted in one run cannot be resolved in
+* another.
+*/
+const REF_PREFIX = "secret:";
+function createSecretVault() {
+	const store = /* @__PURE__ */ new Map();
+	return {
+		put(value, meta) {
+			const ref = `${REF_PREFIX}${randomUUID()}`;
+			store.set(ref, {
+				value,
+				meta: {
+					ref,
+					label: meta.label,
+					source: meta.source,
+					createdAt: Date.now()
+				}
+			});
+			return ref;
+		},
+		get(ref) {
+			return store.get(ref)?.value;
+		},
+		has(ref) {
+			return store.has(ref);
+		},
+		list() {
+			return [...store.values()].map((s) => s.meta);
+		},
+		clear() {
+			store.clear();
+		}
+	};
+}
+//#endregion
+//#region src/lib/agent/runner/sequence/orchestrator/queue.ts
+/**
+* The orchestrator task queue.
+*
+* In memory, synchronous, single-owner: one Node process drives the run, so
+* there is no locking. The queue imposes no execution policy — `nextRunnable`
+* returns every pending task whose dependencies are satisfied, and how many of
+* those run at once is decided by the task graph, not the queue.
+*
+* Every transition rewrites `<installDir>/.posthog-wizard-cache/queue.json`, a
+* small file holding the whole queue, handoffs included. It is the run's log
+* and the report's source. The whole cache folder is run-scoped and wiped when
+* the run ends.
+*/
+const TaskStatus = {
+	Pending: "pending",
+	Running: "running",
+	Done: "done",
+	Skipped: "skipped",
+	Failed: "failed"
+};
+const QUEUE_DIR_NAME = ".posthog-wizard-cache";
+const DEFAULT_MAX_ATTEMPTS = 2;
+function nowIso() {
+	return (/* @__PURE__ */ new Date()).toISOString();
+}
+/** Dropped in the cache folder so an orphaned copy explains itself. */
+const DELETE_ME_FILE = ".DELETE-ME.md";
+const DELETE_ME_BODY = `# Safe to delete
+
+This folder contains run artifacts from the PostHog Wizard. This should have
+been deleted if the Wizard has finished running. If this wasn't deleted for
+some reason, you can safely delete the entire \`${QUEUE_DIR_NAME}/\` folder.
+`;
+var QueueStore = class {
+	tasks = [];
+	onTransition;
+	runId;
+	queuePath;
+	constructor(installDir, runId, opts) {
+		this.onTransition = opts?.onTransition;
+		this.runId = runId;
+		const dir = path$1.join(installDir, QUEUE_DIR_NAME);
+		this.queuePath = path$1.join(dir, "queue.json");
+		fs$1.mkdirSync(dir, { recursive: true });
+		fs$1.writeFileSync(path$1.join(dir, DELETE_ME_FILE), DELETE_ME_BODY);
+	}
+	list() {
+		return this.tasks;
+	}
+	get(id) {
+		return this.tasks.find((t) => t.id === id);
+	}
+	/**
+	* Every pending task whose dependencies are all satisfied (`done` or
+	* `skipped`). A skipped dependency does not block downstream work.
+	*/
+	nextRunnable() {
+		const doneIds = new Set(this.tasks.filter((t) => t.status === TaskStatus.Done || t.status === TaskStatus.Skipped).map((t) => t.id));
+		return this.tasks.filter((t) => t.status === TaskStatus.Pending && t.dependsOn.every((d) => doneIds.has(d)));
+	}
+	/**
+	* True when no task is running and none can be started. Either everything
+	* is terminal, or the only pending tasks are blocked by a failed dependency.
+	*/
+	isDrained() {
+		if (this.tasks.some((t) => t.status === TaskStatus.Running)) return false;
+		return this.nextRunnable().length === 0;
+	}
+	summary() {
+		const counts = {
+			[TaskStatus.Pending]: 0,
+			[TaskStatus.Running]: 0,
+			[TaskStatus.Done]: 0,
+			[TaskStatus.Skipped]: 0,
+			[TaskStatus.Failed]: 0
+		};
+		for (const t of this.tasks) counts[t.status] += 1;
+		return {
+			...counts,
+			total: this.tasks.length
+		};
+	}
+	readHandoff(id) {
+		return this.get(id)?.handoff ?? null;
+	}
+	/** Handoffs of completed tasks of a given type, oldest first. */
+	readHandoffsByType(type) {
+		return this.tasks.filter((t) => t.type === type && t.handoff).map((t) => t.handoff);
+	}
+	enqueue(input) {
+		const task = {
+			id: randomUUID(),
+			type: input.type,
+			label: input.label,
+			status: TaskStatus.Pending,
+			dependsOn: input.dependsOn ?? [],
+			inputs: input.inputs ?? {},
+			model: input.model,
+			attempts: 0,
+			maxAttempts: input.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
+			enqueuedBy: input.enqueuedBy ?? "orchestrator",
+			createdAt: nowIso()
+		};
+		this.tasks.push(task);
+		this.reflect();
+		this.notify("enqueue", task);
+		return task;
+	}
+	start(id) {
+		const t = this.require(id);
+		t.status = TaskStatus.Running;
+		t.startedAt = nowIso();
+		t.attempts += 1;
+		this.reflect();
+		this.notify("start", t);
+		return t;
+	}
+	complete(id, handoff) {
+		return this.finish(id, TaskStatus.Done, handoff);
+	}
+	/** Terminal: the agent could not do the task. Not done, not failed. */
+	skip(id, handoff) {
+		return this.finish(id, TaskStatus.Skipped, handoff);
+	}
+	fail(id, error, handoff) {
+		const t = this.require(id);
+		t.error = error;
+		return this.finish(id, TaskStatus.Failed, handoff);
+	}
+	/** Put a failed/running task back to pending for a retry within the run. */
+	requeue(id) {
+		const t = this.require(id);
+		t.status = TaskStatus.Pending;
+		t.startedAt = void 0;
+		t.finishedAt = void 0;
+		this.reflect();
+		this.notify("requeue", t);
+		return t;
+	}
+	finish(id, status, handoff) {
+		const t = this.require(id);
+		if (handoff) t.handoff = handoff;
+		t.status = status;
+		t.finishedAt = nowIso();
+		this.reflect();
+		this.notify(status === TaskStatus.Done ? "complete" : status === TaskStatus.Skipped ? "skip" : "fail", t);
+		return t;
+	}
+	reflect() {
+		const file = {
+			version: 1,
+			runId: this.runId,
+			tasks: this.tasks
+		};
+		writeJsonAtomic(this.queuePath, file);
+	}
+	notify(event, task) {
+		try {
+			this.onTransition?.(event, task);
+		} catch (error) {
+			analytics.captureException(error instanceof Error ? error : new Error(String(error)), {
+				step: "orchestrator_queue_listener",
+				event
+			});
+		}
+	}
+	require(id) {
+		const t = this.get(id);
+		if (!t) throw new Error(`No task ${id} in the queue`);
+		return t;
+	}
+};
+//#endregion
+//#region src/lib/agent/runner/sequence/orchestrator/queue-tools.ts
+/**
+* Orchestrator MCP tools, registered into the existing `wizard-tools` server when
+* a queue is present. They let the orchestrator agent and task agents grow the
+* queue, report completion with a structured handoff, and read prior handoffs.
+*
+* The guard logic and the apply functions are plain, exported, and unit-tested.
+* `buildOrchestratorTools` wraps them in the SDK `tool()` shape.
+*/
+function stableStringify(value) {
+	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	return `{${Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+}
+function dedupKey(type, inputs) {
+	return `${type}::${stableStringify(inputs)}`;
+}
+/**
+* A backstop on total queue size. Tasks can enqueue tasks, so a misbehaving
+* type could grow the queue without bound. Keeping the graph small is the job
+* of good agent and skill design, not this number — it only stops a runaway.
+* The real flow is ~9 tasks, so this sits well clear of it.
+*/
+const MAX_QUEUE_TASKS = 30;
+/**
+* Validate an enqueue. Structural checks only — a real type, real dependencies,
+* not a literal duplicate, and not past the runaway backstop. How much runs,
+* and in what shape, is the task graph's business, not a knob's.
+*/
+function checkEnqueueGuards(ctx, args) {
+	const tasks = ctx.store.list();
+	if (tasks.length >= MAX_QUEUE_TASKS) return {
+		ok: false,
+		guard: "queue-full",
+		message: `The queue already holds ${tasks.length} tasks (cap ${MAX_QUEUE_TASKS}). Refine the existing tasks rather than adding more.`
+	};
+	if (!ctx.validTypes.includes(args.type)) return {
+		ok: false,
+		guard: "unknown-type",
+		message: `Unknown task type "${args.type}". Valid types: ${ctx.validTypes.join(", ")}.`
+	};
+	for (const dep of args.dependsOn ?? []) if (!ctx.store.get(dep)) return {
+		ok: false,
+		guard: "unknown-dep",
+		message: `Dependency "${dep}" is not a known task id.`
+	};
+	const key = dedupKey(args.type, args.inputs ?? {});
+	if (tasks.some((t) => t.status !== TaskStatus.Failed && dedupKey(t.type, t.inputs) === key)) return {
+		ok: false,
+		guard: "dedup",
+		message: `A "${args.type}" task with these inputs already exists.`
+	};
+	return { ok: true };
+}
+function applyEnqueue(ctx, args) {
+	const guard = checkEnqueueGuards(ctx, args);
+	if (!guard.ok) return guard;
+	return {
+		ok: true,
+		task: ctx.store.enqueue({
+			type: args.type,
+			label: args.label,
+			inputs: args.inputs ?? {},
+			dependsOn: args.dependsOn ?? [],
+			model: args.model,
+			enqueuedBy: ctx.currentTaskId ?? "orchestrator"
+		})
+	};
+}
+function applyComplete(ctx, args) {
+	const id = ctx.currentTaskId;
+	if (!id) return {
+		ok: false,
+		message: "complete_task can only be called by a running task agent."
+	};
+	if (args.status === TaskStatus.Failed) ctx.store.fail(id, {
+		type: "self-reported",
+		message: args.handoff.forNextAgent
+	}, args.handoff);
+	else if (args.status === TaskStatus.Skipped) ctx.store.skip(id, args.handoff);
+	else ctx.store.complete(id, args.handoff);
+	return { ok: true };
+}
+function applyReadHandoffs(ctx, args) {
+	if (args.taskId) {
+		const h = ctx.store.readHandoff(args.taskId);
+		return h ? [h] : [];
+	}
+	if (args.type) return ctx.store.readHandoffsByType(args.type);
+	const currentId = ctx.currentTaskId;
+	const current = currentId ? ctx.store.get(currentId) : void 0;
+	if (!current) return [];
+	return current.dependsOn.map((depId) => ctx.store.readHandoff(depId)).filter((h) => h !== null);
+}
+const HANDOFF_SHAPE = {
+	goals: z.string().describe("What this task was asked to achieve."),
+	did: z.string().describe("What you actually did."),
+	forNextAgent: z.string().describe("What the next agent should know."),
+	filesTouched: z.array(z.string()).optional(),
+	conflict: z.string().optional().describe("A one-line summary of any conflict you could not cleanly resolve (e.g. a dependency or build conflict). Put full detail in your work; this line is surfaced to the user.")
+};
+function textResult(text, isError = false) {
+	return {
+		isError,
+		content: [{
+			type: "text",
+			text
+		}]
+	};
+}
+/**
+* Build the orchestrator tools in the SDK `tool()` shape. Called from
+* createWizardToolsServer only when a queue context is present.
+*/
+function buildOrchestratorTools(tool, ctx) {
+	return [
+		tool("enqueue_task", "Add a task to the orchestrator queue. Use it to seed work and to enqueue follow-up work you discover. Keep tasks small and discrete.", {
+			type: z.string().describe(`The task type. One of: ${ctx.validTypes.join(", ")}.`),
+			label: z.string().optional().describe("A short label for the UI — the action in a few words (e.g. \"Add the PostHog SDK\", \"Initialize PostHog\"). Leave out file names, class names, and other specifics."),
+			inputs: z.record(z.unknown()).optional(),
+			dependsOn: z.array(z.string()).optional().describe("Task ids that must be done before this task runs."),
+			model: z.string().optional(),
+			reason: z.string().describe("One line on why this task is needed.")
+		}, ((args) => {
+			const res = applyEnqueue(ctx, args);
+			if (!res.ok) {
+				analytics.wizardCapture("orchestrator guard tripped", {
+					guard: res.guard,
+					type: args.type
+				});
+				return textResult(res.message, true);
+			}
+			return textResult(JSON.stringify({ id: res.task.id }));
+		})),
+		tool("complete_task", "Report the outcome of your task. Always call this exactly once when you finish, with a structured handoff for the next agent. Use status 'skipped' when the task does not apply to this project and you cannot do it (say why in the handoff) — not 'done'.", {
+			status: z.enum([
+				"done",
+				"failed",
+				"skipped"
+			]),
+			handoff: z.object(HANDOFF_SHAPE)
+		}, ((args) => {
+			const res = applyComplete(ctx, args);
+			if (!res.ok) return textResult(res.message, true);
+			return textResult("ok");
+		})),
+		tool("read_handoffs", "Read structured handoffs from earlier tasks. With no argument, returns the handoffs of your dependencies.", {
+			type: z.string().optional(),
+			taskId: z.string().optional()
+		}, ((args) => {
+			const handoffs = applyReadHandoffs(ctx, args);
+			return textResult(JSON.stringify(handoffs, null, 2));
+		}))
+	];
+}
+//#endregion
+//#region src/lib/wizard-tools.ts
+/**
+* Unified in-process MCP server for the PostHog wizard.
+*
+* Provides tools that run locally (secret values never leave the machine):
+* - check_env_keys: Check which env var keys exist in a .env file
+* - set_env_values: Create/update env vars in a .env file
+* - detect_package_manager: Detect the project's package manager(s)
+* - load_skill_menu / install_skill: Skill installation
+* - audit_seed_checks / audit_add_checks / audit_resolve_checks: Audit ledger ownership
+*/
+let _sdkModule = null;
+async function getSDKModule() {
+	if (!_sdkModule) _sdkModule = await import("@anthropic-ai/claude-agent-sdk");
+	return _sdkModule;
+}
+/**
+* Fetch the skill menu from the skills server.
+* Returns parsed data on success, `null` on failure.
+*/
+async function fetchSkillMenu(skillsBaseUrl) {
+	try {
+		const menuUrl = `${skillsBaseUrl}/skill-menu.json`;
+		logToFile(`fetchSkillMenu: fetching from ${menuUrl}`);
+		const resp = await fetch(menuUrl);
+		if (resp.ok) {
+			const data = await resp.json();
+			logToFile(`fetchSkillMenu: loaded (${Object.keys(data.categories).length} categories)`);
+			return data;
+		}
+		logToFile(`fetchSkillMenu: failed with HTTP ${resp.status}`);
+		return null;
+	} catch (err) {
+		logToFile(`fetchSkillMenu: error: ${err.message}`);
+		return null;
+	}
+}
+/**
+* Download and extract a skill.
+* By default installs to `<installDir>/.claude/skills/<id>/`.
+* Pass `skillsRoot` to override the base directory (e.g. `.posthog/skills`).
+*/
+function downloadSkill(skillEntry, installDir, skillsRoot) {
+	const skillDir = skillsRoot ? path.join(installDir, skillsRoot, skillEntry.id) : path.join(installDir, ".claude", "skills", skillEntry.id);
+	const tmpFile = skillTmpPath(skillEntry.id);
+	try {
+		fs.mkdirSync(skillDir, { recursive: true });
+		execFileSync("curl", [
+			"-sL",
+			skillEntry.downloadUrl,
+			"-o",
+			tmpFile
+		], { timeout: 3e4 });
+		execFileSync("unzip", [
+			"-o",
+			tmpFile,
+			"-d",
+			skillDir
+		], { timeout: 3e4 });
+		fs.writeFileSync(path.join(skillDir, ".posthog-wizard"), "");
+		try {
+			fs.unlinkSync(tmpFile);
+		} catch {}
+		logToFile(`downloadSkill: installed ${skillEntry.id} from ${skillEntry.downloadUrl}`);
+		return { success: true };
+	} catch (err) {
+		logToFile(`downloadSkill: error: ${err.message}`);
+		return {
+			success: false,
+			error: err.message
+		};
+	}
+}
+/**
+* High-level "install a skill by ID" helper. Fetches the skill menu,
+* finds the skill, downloads and extracts it. Programs should use this
+* instead of composing fetchSkillMenu + downloadSkill themselves.
+*/
+async function installSkillById(skillId, installDir, skillsBaseUrl, skillsRoot) {
+	const menu = await fetchSkillMenu(skillsBaseUrl);
+	if (!menu) return { kind: "menu-fetch-failed" };
+	const skill = Object.values(menu.categories).flat().find((s) => s.id === skillId);
+	if (!skill) return {
+		kind: "skill-not-found",
+		skillId
+	};
+	const result = downloadSkill(skill, installDir, skillsRoot);
+	if (!result.success) return {
+		kind: "download-failed",
+		message: result.error ?? "unknown"
+	};
+	return {
+		kind: "ok",
+		path: skillsRoot ? `${skillsRoot}/${skillId}` : `.claude/skills/${skillId}`
+	};
+}
+/**
+* Pure decision function for the wizard_ask caps. Returns whether the
+* upcoming call should proceed and, if not, the error message to surface
+* to the agent. Extracted so the policy can be unit-tested without
+* spinning up an MCP server.
+*
+* The adjacency nudge fires exactly once per run (the caller records it
+* via `adjacencyNudged`) — flows that legitimately need several
+* sequential, answer-dependent asks then proceed up to `maxQuestions`.
+* Without the flag the rejected call would never advance the counter and
+* every later call would be rejected, making caps above the threshold
+* unreachable.
+*/
+function evaluateAskCap(callCount, maxQuestions, adjacencyNudged = false) {
+	if (callCount >= maxQuestions) return {
+		kind: "capped",
+		reason: "max_questions",
+		message: `Error: wizard_ask cap reached (${maxQuestions} calls in this run). Proceed with sensible defaults using the answers you already have, or emit [ABORT] requirements-incomplete.`
+	};
+	if (!adjacencyNudged && callCount >= 3) return {
+		kind: "capped",
+		reason: "adjacency",
+		message: `Error: too many wizard_ask calls in a row (${callCount} so far). Batch the remaining questions into a single call — the schema accepts up to 8 questions per invocation. If the remaining questions truly depend on earlier answers, ask again and they will go through.`
+	};
+	return { kind: "ok" };
+}
+/**
+* Resolve filePath relative to workingDirectory, rejecting path traversal.
+*/
+function resolveEnvPath(workingDirectory, filePath) {
+	const resolved = path.resolve(workingDirectory, filePath);
+	if (!resolved.startsWith(workingDirectory + path.sep) && resolved !== workingDirectory) throw new Error(`Path traversal rejected: "${filePath}" resolves outside working directory`);
+	return resolved;
+}
+/**
+* Ensure the given env file basename is covered by .gitignore in the working directory.
+* Creates .gitignore if it doesn't exist; appends the entry if missing.
+*/
+function ensureGitignoreCoverage(workingDirectory, envFileName) {
+	const gitignorePath = path.join(workingDirectory, ".gitignore");
+	if (fs.existsSync(gitignorePath)) {
+		const content = fs.readFileSync(gitignorePath, "utf8");
+		if (content.split("\n").some((line) => line.trim() === envFileName)) return;
+		const newContent = content.endsWith("\n") ? `${content}${envFileName}\n` : `${content}\n${envFileName}\n`;
+		fs.writeFileSync(gitignorePath, newContent, "utf8");
+	} else fs.writeFileSync(gitignorePath, `${envFileName}\n`, "utf8");
+}
+/**
+* Parse a .env file's content and return the set of defined key names.
+*/
+function parseEnvKeys(content) {
+	const keys = /* @__PURE__ */ new Set();
+	for (const line of content.split("\n")) {
+		const match = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/);
+		if (match) keys.add(match[1]);
+	}
+	return keys;
+}
+/**
+* Merge key-value pairs into existing .env content.
+* Updates existing keys in-place, appends new keys at the end.
+*/
+function mergeEnvValues(content, values) {
+	let result = content;
+	const updatedKeys = /* @__PURE__ */ new Set();
+	for (const [key, value] of Object.entries(values)) {
+		const regex = new RegExp(`^(\\s*${key}\\s*=).*$`, "m");
+		if (regex.test(result)) {
+			result = result.replace(regex, `$1${value}`);
+			updatedKeys.add(key);
+		}
+	}
+	const newKeys = Object.entries(values).filter(([key]) => !updatedKeys.has(key));
+	if (newKeys.length > 0) {
+		if (result.length > 0 && !result.endsWith("\n")) result += "\n";
+		for (const [key, value] of newKeys) result += `${key}=${value}\n`;
+	}
+	return result;
+}
+const AUDIT_STATUSES = [
+	"pending",
+	"pass",
+	"error",
+	"warning",
+	"suggestion"
+];
+const auditCheckSchema = z.object({
+	id: z.string().min(1),
+	area: z.string().min(1),
+	label: z.string().min(1),
+	status: z.enum(AUDIT_STATUSES),
+	file: z.string().optional(),
+	details: z.string().optional()
+});
+const auditUpdateSchema = z.object({
+	id: z.string().min(1),
+	status: z.enum(AUDIT_STATUSES),
+	file: z.string().optional(),
+	details: z.string().optional()
+});
+/** Atomically write the audit ledger. Thin typed wrapper over writeJsonAtomic. */
+function writeLedgerAtomic(targetPath, checks) {
+	writeJsonAtomic(targetPath, checks);
+}
+/**
+* Apply a batch of patches to the ledger by id. Returns the new array and the
+* list of update ids that didn't match any existing check.
+*/
+function applyAuditUpdates(current, updates) {
+	const byId = new Map(current.map((c) => [c.id, c]));
+	const unknown = [];
+	for (const u of updates) {
+		const existing = byId.get(u.id);
+		if (!existing) {
+			unknown.push(u.id);
+			continue;
+		}
+		byId.set(u.id, {
+			...existing,
+			status: u.status,
+			...u.file !== void 0 ? { file: u.file } : {},
+			...u.details !== void 0 ? { details: u.details } : {}
+		});
+	}
+	return {
+		next: current.map((c) => byId.get(c.id) ?? c),
+		unknown
+	};
+}
+/**
+* Append new checks to a seeded ledger. Duplicate ids are reported without
+* mutating the current ledger, including duplicates inside the additions.
+*/
+function applyAuditAdditions(current, additions) {
+	const existingIds = new Set(current.map((c) => c.id));
+	const additionIds = /* @__PURE__ */ new Set();
+	const duplicates = [];
+	for (const check of additions) {
+		if (existingIds.has(check.id) || additionIds.has(check.id)) {
+			duplicates.push(check.id);
+			continue;
+		}
+		additionIds.add(check.id);
+	}
+	if (duplicates.length > 0) return {
+		next: current,
+		duplicates
+	};
+	return {
+		next: [...current, ...additions],
+		duplicates: []
+	};
+}
+function readLedger(targetPath) {
+	if (!fs.existsSync(targetPath)) return [];
+	try {
+		return coerceAuditChecks(JSON.parse(fs.readFileSync(targetPath, "utf8")));
+	} catch {
+		return [];
+	}
+}
+function appendAuditChecksToLedger(targetPath, additions) {
+	if (!fs.existsSync(targetPath)) return {
+		ok: false,
+		reason: "missing-ledger"
+	};
+	const { next, duplicates } = applyAuditAdditions(readLedger(targetPath), additions);
+	if (duplicates.length > 0) return {
+		ok: false,
+		reason: "duplicate-ids",
+		ids: duplicates
+	};
+	writeLedgerAtomic(targetPath, next);
+	return {
+		ok: true,
+		added: additions.length
+	};
+}
+const SERVER_NAME = "wizard-tools";
+/**
+* Create the unified in-process MCP server with all wizard tools.
+* Must be called asynchronously because the SDK is an ESM module loaded via dynamic import.
+*/
+async function createWizardToolsServer(options) {
+	const { workingDirectory, detectPackageManager, skillsBaseUrl, askBridge, askMaxQuestions = 10, secretVault = createSecretVault(), orchestrator } = options;
+	const { tool, createSdkMcpServer } = await getSDKModule();
+	let askCallCount = 0;
+	let askAdjacencyNudged = false;
+	let cachedSkillMenu = {};
+	let categoryNames = ["integration"];
+	const menu = await fetchSkillMenu(skillsBaseUrl);
+	if (menu) cachedSkillMenu = menu.categories;
+	const keys = Object.keys(cachedSkillMenu);
+	if (keys.length > 0) categoryNames = keys;
+	const checkEnvKeys = tool("check_env_keys", "Check which environment variable keys are present or missing in a .env file. Never reveals values.", {
+		filePath: z.string().describe("Path to the .env file, relative to the project root"),
+		keys: z.array(z.string()).describe("Environment variable key names to check")
+	}, (args) => {
+		const resolved = resolveEnvPath(workingDirectory, args.filePath);
+		logToFile(`check_env_keys: ${resolved}, keys: ${args.keys.join(", ")}`);
+		const existingKeys = fs.existsSync(resolved) ? parseEnvKeys(fs.readFileSync(resolved, "utf8")) : /* @__PURE__ */ new Set();
+		const results = {};
+		for (const key of args.keys) results[key] = existingKeys.has(key) ? "present" : "missing";
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(results, null, 2)
+		}] };
+	});
+	const setEnvValues = tool("set_env_values", "Create or update environment variable keys in a .env file. Creates the file if it does not exist. Ensures .gitignore coverage. Each value can be either a literal string or a secret reference of the form `{ \"secretRef\": \"secret:...\" }` returned by another tool (e.g. wizard_ask). Secret references are resolved locally — the actual value is written to the file but never returned to the agent.", {
+		filePath: z.string().describe("Path to the .env file, relative to the project root"),
+		values: z.record(z.string(), z.union([z.string(), z.object({ secretRef: z.string() })])).describe("Key → (literal string OR { secretRef } pointing to a vaulted secret)")
+	}, (args) => {
+		const forbidden = Object.keys(args.values).find((k) => k.toUpperCase() === "POSTHOG_KEY");
+		if (forbidden) return {
+			content: [{
+				type: "text",
+				text: `Error: "${forbidden}" is not a valid PostHog env var name. Use the project-specific key name from your framework's integration guide (e.g. NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN).`
+			}],
+			isError: true
+		};
+		const resolvedValues = {};
+		const resolvedRefKeys = [];
+		for (const [key, val] of Object.entries(args.values)) if (typeof val === "string") resolvedValues[key] = val;
+		else {
+			const secret = secretVault.get(val.secretRef);
+			if (secret === void 0) return {
+				content: [{
+					type: "text",
+					text: `Error: secret reference "${val.secretRef}" for key "${key}" is not known to the vault. The ref may have expired, been minted in a different run, or been mistyped.`
+				}],
+				isError: true
+			};
+			resolvedValues[key] = secret;
+			resolvedRefKeys.push(key);
+		}
+		const resolved = resolveEnvPath(workingDirectory, args.filePath);
+		logToFile(`set_env_values: ${resolved}, keys: ${Object.keys(resolvedValues).join(", ")}${resolvedRefKeys.length > 0 ? ` (secret refs: ${resolvedRefKeys.join(", ")})` : ""}`);
+		const content = mergeEnvValues(fs.existsSync(resolved) ? fs.readFileSync(resolved, "utf8") : "", resolvedValues);
+		const dir = path.dirname(resolved);
+		if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+		fs.writeFileSync(resolved, content, "utf8");
+		ensureGitignoreCoverage(workingDirectory, path.basename(resolved));
+		return { content: [{
+			type: "text",
+			text: `Updated ${Object.keys(args.values).length} key(s) in ${args.filePath}`
+		}] };
+	});
+	const detectPM = tool("detect_package_manager", "Detect which package manager(s) the project uses. Returns the name, install command, and run command for each detected package manager. Call this before running any install commands.", {}, async () => {
+		logToFile(`detect_package_manager: scanning ${workingDirectory}`);
+		const result = await detectPackageManager(workingDirectory);
+		logToFile(`detect_package_manager: detected ${result.detected.length} package manager(s)`);
+		return { content: [{
+			type: "text",
+			text: JSON.stringify(result, null, 2)
+		}] };
+	});
+	const loadSkillMenu = tool("load_skill_menu", "Load available PostHog skills for a category. Returns skill IDs and names. Call this first, then use install_skill with the chosen ID.", { category: z.enum(categoryNames).describe("Skill category") }, (args) => {
+		const skills = cachedSkillMenu[args.category];
+		if (!skills || skills.length === 0) return {
+			content: [{
+				type: "text",
+				text: `No skills found for category "${args.category}".`
+			}],
+			isError: true
+		};
+		const menuText = skills.map((s) => `- ${s.id}: ${s.name}`).join("\n");
+		logToFile(`load_skill_menu: returning ${skills.length} skills for "${args.category}"`);
+		return { content: [{
+			type: "text",
+			text: menuText
+		}] };
+	});
+	const installSkill = tool("install_skill", "Download and install a PostHog skill by ID. Call load_skill_menu first to see available skills. Extracts the skill to .claude/skills/<skillId>/.", { skillId: z.string().describe("Skill ID from the skill menu (e.g., \"integration-nextjs-app-router\")") }, (args) => {
+		if (!/^[a-z0-9][a-z0-9_-]*$/.test(args.skillId)) return {
+			content: [{
+				type: "text",
+				text: "Error: skillId must be lowercase alphanumeric with hyphens."
+			}],
+			isError: true
+		};
+		const skill = Object.values(cachedSkillMenu).flat().find((s) => s.id === args.skillId);
+		if (!skill) return {
+			content: [{
+				type: "text",
+				text: `Error: skill "${args.skillId}" not found. Use load_skill_menu to see available skills.`
+			}],
+			isError: true
+		};
+		const result = downloadSkill(skill, workingDirectory);
+		if (result.success) return { content: [{
+			type: "text",
+			text: `Skill installed to .claude/skills/${args.skillId}/`
+		}] };
+		else return {
+			content: [{
+				type: "text",
+				text: `Error installing skill: ${result.error}`
+			}],
+			isError: true
+		};
+	});
+	const auditLedgerPath = path.join(workingDirectory, AUDIT_CHECKS_FILE);
+	const auditMutex = makeMutex();
+	const auditSeedChecks = tool("audit_seed_checks", "Seed the audit ledger at .posthog-audit-checks.json with the full set of pending checks. Call this once at the start of the audit. Atomically replaces any existing ledger.", { checks: z.array(auditCheckSchema).describe("Full pending checklist to write to the ledger") }, async (args) => {
+		return auditMutex(() => {
+			writeLedgerAtomic(auditLedgerPath, args.checks);
+			logToFile(`audit_seed_checks: wrote ${args.checks.length} entries`);
+			return { content: [{
+				type: "text",
+				text: `Seeded ${args.checks.length} audit checks.`
+			}] };
+		});
+	});
+	const auditAddChecks = tool("audit_add_checks", "Append one or more pending checks to the existing audit ledger at .posthog-audit-checks.json. Call audit_seed_checks first. Atomically rejects duplicate ids without changing the ledger.", { checks: z.array(auditCheckSchema).min(1).describe("Additional checks to append to the existing ledger") }, async (args) => {
+		return auditMutex(() => {
+			const result = appendAuditChecksToLedger(auditLedgerPath, args.checks);
+			if (!result.ok) {
+				if (result.reason === "missing-ledger") return {
+					content: [{
+						type: "text",
+						text: "Error: audit ledger does not exist. Run audit_seed_checks first."
+					}],
+					isError: true
+				};
+				return {
+					content: [{
+						type: "text",
+						text: `Error: duplicate check id(s): ${result.ids.join(", ")}. Check ids must be unique.`
+					}],
+					isError: true
+				};
+			}
+			logToFile(`audit_add_checks: added ${result.added} entries`);
+			return { content: [{
+				type: "text",
+				text: `Added ${result.added} audit check(s).`
+			}] };
+		});
+	});
+	const auditResolveChecks = tool("audit_resolve_checks", "Resolve one or more audit checks by id. Patches each entry's status (and optional file/details) and writes the ledger back atomically. Concurrent calls serialize.", { updates: z.array(auditUpdateSchema).min(1).describe("Patches to apply, keyed by check id") }, async (args) => {
+		return auditMutex(() => {
+			const { next, unknown } = applyAuditUpdates(readLedger(auditLedgerPath), args.updates);
+			if (unknown.length > 0) return {
+				content: [{
+					type: "text",
+					text: `Error: unknown check id(s): ${unknown.join(", ")}. Run audit_seed_checks first or check the id.`
+				}],
+				isError: true
+			};
+			writeLedgerAtomic(auditLedgerPath, next);
+			logToFile(`audit_resolve_checks: applied ${args.updates.length} update(s)`);
+			return { content: [{
+				type: "text",
+				text: `Resolved ${args.updates.length} check(s).`
+			}] };
+		});
+	});
+	const askQuestionSchema = z.object({
+		id: z.string().min(1).describe("Stable key for the answer in the response map"),
+		prompt: z.string().min(1).describe("Question text shown to the user"),
+		kind: z.enum([
+			"single",
+			"multi",
+			"text"
+		]).describe("'single' = pick one option, 'multi' = pick any, 'text' = free-form single-line answer"),
+		options: z.array(z.object({
+			label: z.string(),
+			value: z.string(),
+			description: z.string().optional().describe("Optional secondary line shown dimmed and wrapped beneath the label (multi-select only). Use when a choice needs more than a title — e.g. what a custom scout watches and what makes it speak up.")
+		})).optional().describe("Required for kind=single|multi; ignored for kind=text"),
+		required: z.boolean().optional().describe("Defaults to true"),
+		sensitive: z.boolean().optional().describe("Only valid for kind='text'. When true, the user's answer is stored in the wizard's secret vault and returned to you as { secretRef: 'secret:...' } instead of the raw string. Use for API keys, tokens, and any other secret the user types in. The secretRef is only resolved by wizard-tools that accept it (e.g. set_env_values) — it is NOT resolved when passed to other MCP tools (e.g. PostHog data-warehouse tools), which will reject it. For a secret that must reach another tool, write it to the env with set_env_values first, or use that tool's own credential-reference flow.")
+	});
+	return createSdkMcpServer({
+		name: SERVER_NAME,
+		version: "1.0.0",
+		tools: [
+			checkEnvKeys,
+			setEnvValues,
+			detectPM,
+			loadSkillMenu,
+			installSkill,
+			auditSeedChecks,
+			auditAddChecks,
+			auditResolveChecks,
+			tool("wizard_ask", "Ask the user one or more structured questions and wait for their answers. Use this whenever you would otherwise inline a question in your text output. Batch related questions into a single call (up to 8) rather than asking one at a time; sequential calls are fine when later questions genuinely depend on earlier answers. A fully cancelled or timed-out response does NOT count against the per-run cap — treat it as \"the user declined\" and fall back gracefully (e.g. hand over a deep link) without worrying about a wasted call.", { questions: z.array(askQuestionSchema).min(1).max(8) }, async (args) => {
+				if (!askBridge) return {
+					content: [{
+						type: "text",
+						text: "Error: wizard_ask is not available in this environment (CI / non-interactive). Proceed with sensible defaults or emit [ABORT] requirements-incomplete."
+					}],
+					isError: true
+				};
+				const capDecision = evaluateAskCap(askCallCount, askMaxQuestions, askAdjacencyNudged);
+				if (capDecision.kind === "capped") {
+					if (capDecision.reason === "adjacency") askAdjacencyNudged = true;
+					analytics.wizardCapture("wizard_ask capped", {
+						reason: capDecision.reason,
+						call_count: askCallCount,
+						max_questions: askMaxQuestions
+					});
+					return {
+						content: [{
+							type: "text",
+							text: capDecision.message
+						}],
+						isError: true
+					};
+				}
+				for (const q of args.questions) {
+					if ((q.kind === "single" || q.kind === "multi") && (!q.options || q.options.length === 0)) return {
+						content: [{
+							type: "text",
+							text: `Error: question "${q.id}" has kind="${q.kind}" but no options. Provide at least one { label, value } option, or change kind to "text".`
+						}],
+						isError: true
+					};
+					if (q.sensitive && q.kind !== "text") return {
+						content: [{
+							type: "text",
+							text: `Error: question "${q.id}" sets sensitive=true but kind="${q.kind}". Only kind="text" answers can be vaulted as secrets.`
+						}],
+						isError: true
+					};
+				}
+				const ids = /* @__PURE__ */ new Set();
+				for (const q of args.questions) {
+					if (ids.has(q.id)) return {
+						content: [{
+							type: "text",
+							text: `Error: duplicate question id "${q.id}". Each question must have a unique id.`
+						}],
+						isError: true
+					};
+					ids.add(q.id);
+				}
+				askCallCount += 1;
+				try {
+					const answers = await askBridge.request({ questions: args.questions });
+					if (isFullyCancelled(answers)) askCallCount -= 1;
+					const sensitiveById = new Map(args.questions.filter((q) => q.sensitive).map((q) => [q.id, q.prompt]));
+					const sanitised = {};
+					for (const [id, answer] of Object.entries(answers)) {
+						const label = sensitiveById.get(id);
+						if (label !== void 0 && typeof answer === "string" && answer !== "__cancelled__") {
+							const ref = secretVault.put(answer, {
+								label,
+								source: "wizard_ask"
+							});
+							sanitised[id] = { secretRef: ref };
+							logToFile(`wizard_ask: vaulted answer for "${id}" as ${ref}`);
+						} else sanitised[id] = answer;
+					}
+					logToFile(`wizard_ask: resolved ${Object.keys(answers).length} answer(s) for ${args.questions.length} question(s)`);
+					return { content: [{
+						type: "text",
+						text: JSON.stringify({ answers: sanitised }, null, 2)
+					}] };
+				} catch (err) {
+					logToFile(`wizard_ask: error: ${err?.message ?? err}`);
+					return {
+						content: [{
+							type: "text",
+							text: `Error: wizard_ask failed: ${err?.message ?? String(err)}`
+						}],
+						isError: true
+					};
+				}
+			}),
+			...orchestrator ? buildOrchestratorTools(tool, orchestrator) : []
+		]
+	});
+}
+/** Tool names exposed by the wizard-tools server, keyed for selective use. */
+const WIZARD_TOOL_NAMES = {
+	checkEnvKeys: `mcp__${SERVER_NAME}__check_env_keys`,
+	setEnvValues: `mcp__${SERVER_NAME}__set_env_values`,
+	detectPackageManager: `mcp__${SERVER_NAME}__detect_package_manager`,
+	loadSkillMenu: `mcp__${SERVER_NAME}__load_skill_menu`,
+	installSkill: `mcp__${SERVER_NAME}__install_skill`,
+	auditSeedChecks: `mcp__${SERVER_NAME}__audit_seed_checks`,
+	auditAddChecks: `mcp__${SERVER_NAME}__audit_add_checks`,
+	auditResolveChecks: `mcp__${SERVER_NAME}__audit_resolve_checks`,
+	wizardAsk: `mcp__${SERVER_NAME}__wizard_ask`,
+	enqueueTask: `mcp__${SERVER_NAME}__enqueue_task`,
+	completeTask: `mcp__${SERVER_NAME}__complete_task`,
+	readHandoffs: `mcp__${SERVER_NAME}__read_handoffs`
+};
+//#endregion
+export { coerceAuditChecks as _, installSkillById as a, resolveEnvPath as c, TaskStatus as d, createWizardAskBridge as f, AUDIT_SEVERITY_STYLE as g, AUDIT_REPORT_FILE as h, fetchSkillMenu as i, QUEUE_DIR_NAME as l, AUDIT_CHECKS_KEY as m, createWizardToolsServer as n, mergeEnvValues as o, AUDIT_CHECKS_FILE as p, downloadSkill as r, parseEnvKeys as s, WIZARD_TOOL_NAMES as t, QueueStore as u, getAuditChecks as v };
+
+//# sourceMappingURL=wizard-tools-CGrE1O_b.js.map