@soloworks/smking-wizard 0.1.0

package/dist/bin.mjs

@@ -0,0 +1,1916 @@
+#!/usr/bin/env node
+import { createElement, useEffect } from "react";
+import { Box, Text, render, useApp, useInput } from "ink";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { create } from "zustand";
+import { appendFileSync, existsSync, promises, readFileSync, writeFileSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Spinner } from "@inkjs/ui";
+import { createServer } from "node:http";
+import { createHash, randomBytes } from "node:crypto";
+import open from "open";
+import Anthropic from "@anthropic-ai/sdk";
+import { join, relative, resolve } from "node:path";
+
+//#region src/ui/store.ts
+const DEFAULT_FLAGS = {
+	allowProd: false,
+	allowDirty: false,
+	dryRun: false,
+	debug: false
+};
+/**
+* Cap progress history at 50 lines. Past that, oldest entries drop
+* — keeps the in-memory log bounded for long agent loops and the
+* TUI render fast (we don't want to re-render 500 progress lines).
+*/
+const MAX_PROGRESS_LINES = 50;
+const useWizardStore = create((set) => ({
+	cliFlags: DEFAULT_FLAGS,
+	setCliFlags: (cliFlags) => set({ cliFlags }),
+	screen: "welcome",
+	setScreen: (screen) => set({ screen }),
+	oauthUrl: null,
+	setOauthUrl: (oauthUrl) => set({ oauthUrl }),
+	oauth: null,
+	setOauth: (oauth) => set({ oauth }),
+	agentStatus: "idle",
+	setAgentStatus: (agentStatus) => set({ agentStatus }),
+	agentProgress: [],
+	pushProgress: (text) => set((s) => {
+		const next = [...s.agentProgress, text];
+		if (next.length > MAX_PROGRESS_LINES) next.splice(0, next.length - MAX_PROGRESS_LINES);
+		return { agentProgress: next };
+	}),
+	agentSummary: null,
+	setAgentSummary: (agentSummary) => set({ agentSummary }),
+	fatal: null,
+	setFatal: (fatal) => set({
+		fatal,
+		screen: "error"
+	})
+}));
+
+//#endregion
+//#region ../shared/src/constants/oauth.ts
+const TOKEN_EXPIRY = {
+	ACCESS_TOKEN: 1440 * 60,
+	REFRESH_TOKEN: 2160 * 60 * 60,
+	AUTH_CODE: 600,
+	WIZARD_ACCESS_TOKEN: 1800
+};
+const WIZARD_SCOPES = ["wizard:install", "wizard:llm"];
+/**
+* Localhost callback ports the @soloworks/smking-wizard CLI tries in order. Six
+* ports give us headroom when the user already has a dev server on one
+* — wizard falls through on `EADDRINUSE`. Mirrors PostHog wizard's
+* `OAUTH_PORTS` for the same reason.
+*/
+const WIZARD_OAUTH_PORTS = [
+	8239,
+	8238,
+	8240,
+	8237,
+	8236,
+	8235
+];
+
+//#endregion
+//#region src/constants.ts
+/**
+* Re-export the constants the SaaS already pins so the wizard CLI
+* and the backend stay in sync — changing a port list in one place
+* silently breaking the other would be a nasty bug, so we centralise.
+*/
+const OAUTH_PORTS = WIZARD_OAUTH_PORTS;
+const SCOPES = WIZARD_SCOPES;
+/**
+* smking SaaS origin the wizard talks to. Defaults to the current
+* Vercel production deployment; override via `SMKING_SAAS_URL` for
+* local dev (e.g. `http://localhost:3001`) or staging. Trailing slash
+* is stripped to make URL concatenation safe.
+*
+* Once a custom domain (e.g. `smking.com`) is wired up to the Vercel
+* project, swap the default here in the same commit that updates DNS.
+*/
+const SAAS_URL = (process.env.SMKING_SAAS_URL ?? "https://smking-alone.vercel.app").replace(/\/$/, "");
+/**
+* Public OAuth client_id registered on the SaaS for the wizard. Must
+* match `WIZARD_OAUTH_CLIENT_ID` env var on the SaaS side, which
+* `validateClientCredentials` checks. Public client — no secret.
+*/
+const WIZARD_CLIENT_ID = process.env.SMKING_WIZARD_CLIENT_ID ?? "smking_wizard_v1";
+/**
+* How long the wizard waits for the OAuth browser flow to complete
+* before giving up. 6 minutes covers slow logins, MFA prompts, and
+* SSH users who have to manually copy the URL to a different browser.
+*/
+const OAUTH_TIMEOUT_MS = 360 * 1e3;
+/**
+* PKCE code verifier length (RFC 7636 §4.1 says 43-128 chars). 96
+* is a comfortable middle that still fits a URL nicely if anyone
+* needs to copy/paste it for debugging.
+*/
+const PKCE_VERIFIER_LENGTH = 96;
+/**
+* Read from package.json at build time. tsdown inlines it.
+*/
+const WIZARD_VERSION = "0.1.0";
+/**
+* Minimum Node version. ink 6 needs Node 18.0.0, but we set 20.10
+* to align with the SaaS's `engines` and to get fetch / native test
+* runner stability.
+*/
+const MIN_NODE_MAJOR = 20;
+const MIN_NODE_MINOR = 10;
+
+//#endregion
+//#region src/guards/production-check.ts
+function checkProduction(flags = {}) {
+	if (flags.allowProd) return { ok: true };
+	const signals = [];
+	if (process.env.NODE_ENV === "production") signals.push("NODE_ENV=production");
+	if (process.env.VERCEL_ENV === "production") signals.push("VERCEL_ENV=production");
+	if (process.env.RAILWAY_ENVIRONMENT === "production") signals.push("RAILWAY_ENVIRONMENT=production");
+	if (process.env.FLY_APP_NAME) signals.push("FLY_APP_NAME set (running on fly.io)");
+	if (existsSync("/.dockerenv")) signals.push("/.dockerenv present (inside Docker container)");
+	if (existsSync("/var/www") && signals.length > 0) signals.push("/var/www present");
+	if (signals.length === 0) return { ok: true };
+	return {
+		ok: false,
+		reason: `Refusing to run on a production-like environment. Signals detected:\n  - ${signals.join("\n  - ")}\n\nRun the wizard on your local dev machine, then deploy normally. If you genuinely need to run here, pass --allow-prod.`,
+		override: "--allow-prod"
+	};
+}
+
+//#endregion
+//#region src/guards/git-status-check.ts
+/**
+* Require a clean git working tree before wizard runs. Two reasons:
+*
+*  1. **Predictable diff.** After wizard finishes, `git diff` shows
+*     exactly what wizard did and nothing else — the customer can
+*     review one cohesive change. Mixed in with prior uncommitted
+*     work, the wizard's edits are hard to isolate.
+*
+*  2. **Easy rollback.** If wizard does something wrong, `git
+*     restore .` cleanly reverts to the pre-wizard state. With
+*     uncommitted work mixed in, that command also wipes the
+*     customer's own work.
+*
+* Override via `--allow-dirty` for users who know what they're
+* doing. Repos without git (rare for a real project) pass the
+* guard since there's nothing to dirty.
+*/
+function checkGitStatus(flags = {}, cwd = process.cwd()) {
+	if (flags.allowDirty) return { ok: true };
+	const result = spawnSync("git", ["status", "--porcelain"], {
+		cwd,
+		encoding: "utf-8"
+	});
+	if (result.error || result.status !== 0) return { ok: true };
+	const dirty = result.stdout.trim();
+	if (dirty === "") return { ok: true };
+	const lines = dirty.split("\n");
+	return {
+		ok: false,
+		reason: `Working tree has uncommitted changes. Wizard wants a clean slate so its diff is unambiguous.\n\nUncommitted files:\n${lines.slice(0, 10).join("\n")}${lines.length > 10 ? `\n  ... and ${lines.length - 10} more files` : ""}\n\nCommit, stash, or discard them first. If you really need to run on a dirty tree, pass --allow-dirty.`,
+		override: "--allow-dirty"
+	};
+}
+
+//#endregion
+//#region src/ui/screens/welcome-screen.tsx
+/**
+* First thing the user sees. Trust signals up front — what the
+* wizard will do and what it will NEVER do. Press enter to continue.
+*
+* On Enter the screen also runs sync guards (production-env refuse
+* + git-status-must-be-clean) before advancing. Either guard failing
+* routes to the error screen with an actionable override hint.
+*/
+function WelcomeScreen() {
+	const setScreen = useWizardStore((s) => s.setScreen);
+	const setFatal = useWizardStore((s) => s.setFatal);
+	const cliFlags = useWizardStore((s) => s.cliFlags);
+	useInput((_, key) => {
+		if (!key.return) return;
+		const prodCheck = checkProduction({ allowProd: cliFlags.allowProd });
+		if (!prodCheck.ok) {
+			setFatal(prodCheck.reason);
+			return;
+		}
+		const gitCheck = checkGitStatus({ allowDirty: cliFlags.allowDirty });
+		if (!gitCheck.ok) {
+			setFatal(gitCheck.reason);
+			return;
+		}
+		setScreen("oauth");
+	});
+	return /* @__PURE__ */ jsxs(Box, {
+		flexDirection: "column",
+		gap: 1,
+		children: [
+			/* @__PURE__ */ jsxs(Box, { children: [/* @__PURE__ */ jsx(Text, {
+				bold: true,
+				color: "cyan",
+				children: "🪄 smking install wizard"
+			}), /* @__PURE__ */ jsxs(Text, {
+				color: "gray",
+				children: [" v", WIZARD_VERSION]
+			})] }),
+			/* @__PURE__ */ jsx(Text, { children: "This will install the smking SDK for your project (Laravel or Next.js), configure your environment, and verify the install with a doctor check." }),
+			/* @__PURE__ */ jsxs(Box, {
+				flexDirection: "column",
+				children: [
+					/* @__PURE__ */ jsx(Text, {
+						bold: true,
+						children: "This wizard will:"
+					}),
+					/* @__PURE__ */ jsx(Text, {
+						color: "green",
+						children: " ✓ Open your browser to log in to smking"
+					}),
+					/* @__PURE__ */ jsx(Text, {
+						color: "green",
+						children: " ✓ Detect your framework (Laravel / Next.js)"
+					}),
+					/* @__PURE__ */ jsx(Text, {
+						color: "green",
+						children: " ✓ Install the smking SDK package"
+					}),
+					/* @__PURE__ */ jsx(Text, {
+						color: "green",
+						children: " ✓ Write SMKING_API_KEY + SMKING_BASE_URL to your .env"
+					}),
+					/* @__PURE__ */ jsx(Text, {
+						color: "green",
+						children: " ✓ Run doctor to verify the install"
+					})
+				]
+			}),
+			/* @__PURE__ */ jsxs(Box, {
+				flexDirection: "column",
+				children: [
+					/* @__PURE__ */ jsx(Text, {
+						bold: true,
+						children: "This wizard will NEVER:"
+					}),
+					/* @__PURE__ */ jsx(Text, {
+						color: "red",
+						children: " ✗ Commit or push to git (you review the diff yourself)"
+					}),
+					/* @__PURE__ */ jsx(Text, {
+						color: "red",
+						children: " ✗ Read or upload your .env values to any server"
+					}),
+					/* @__PURE__ */ jsx(Text, {
+						color: "red",
+						children: " ✗ Run destructive commands (rm, drop, migrate:fresh, etc.)"
+					}),
+					/* @__PURE__ */ jsx(Text, {
+						color: "red",
+						children: " ✗ Modify env variables other than SMKING_*"
+					}),
+					/* @__PURE__ */ jsx(Text, {
+						color: "red",
+						children: " ✗ Install packages other than the smking SDK"
+					})
+				]
+			}),
+			/* @__PURE__ */ jsx(Box, {
+				marginTop: 1,
+				children: /* @__PURE__ */ jsx(Text, {
+					color: "cyan",
+					children: "Press Enter to continue · Ctrl-C to abort"
+				})
+			})
+		]
+	});
+}
+
+//#endregion
+//#region src/oauth.ts
+/**
+* Generate a PKCE code verifier per RFC 7636 §4.1. Cryptographically
+* random base64url string in [43, 128] chars.
+*/
+function generateCodeVerifier() {
+	return base64UrlEncode(randomBytes(Math.ceil(PKCE_VERIFIER_LENGTH * 6 / 8))).slice(0, PKCE_VERIFIER_LENGTH);
+}
+/**
+* S256 challenge: BASE64URL(SHA256(verifier)).
+*/
+function generateCodeChallenge(verifier) {
+	return base64UrlEncode(createHash("sha256").update(verifier).digest());
+}
+function base64UrlEncode(buf) {
+	return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function generateState() {
+	return randomBytes(16).toString("hex");
+}
+/**
+* Try each port in OAUTH_PORTS until one binds, then run `handle` on
+* the first matching `/callback` request. Rejects on timeout or if
+* all ports are occupied.
+*
+* Returns the port number it bound to (so the redirect_uri can be
+* built to match) and a promise that resolves with the OAuth code +
+* state when the callback fires.
+*/
+async function startCallbackServer(expectedState, signal) {
+	let resolver;
+	let rejecter;
+	const result = new Promise((res, rej) => {
+		resolver = res;
+		rejecter = rej;
+	});
+	const handler = (req, res) => {
+		if (!req.url) {
+			res.writeHead(404);
+			res.end();
+			return;
+		}
+		const url = new URL(req.url, "http://localhost");
+		if (url.pathname !== "/callback") {
+			res.writeHead(404);
+			res.end();
+			return;
+		}
+		const code = url.searchParams.get("code");
+		const state = url.searchParams.get("state");
+		const error = url.searchParams.get("error");
+		if (error) {
+			res.writeHead(400, { "content-type": "text/html; charset=utf-8" });
+			res.end(renderErrorPage(error));
+			rejecter(/* @__PURE__ */ new Error(`OAuth error: ${error}`));
+			return;
+		}
+		if (!code || !state) {
+			res.writeHead(400, { "content-type": "text/html; charset=utf-8" });
+			res.end(renderErrorPage("missing code or state"));
+			rejecter(/* @__PURE__ */ new Error("OAuth callback missing code or state"));
+			return;
+		}
+		if (state !== expectedState) {
+			res.writeHead(400, { "content-type": "text/html; charset=utf-8" });
+			res.end(renderErrorPage("state mismatch"));
+			rejecter(/* @__PURE__ */ new Error("OAuth state mismatch — possible CSRF"));
+			return;
+		}
+		res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+		res.end(renderSuccessPage());
+		resolver({ code });
+	};
+	for (const port of OAUTH_PORTS) {
+		const server = createServer(handler);
+		try {
+			await new Promise((res, rej) => {
+				server.once("error", rej);
+				server.listen(port, "127.0.0.1", () => res());
+			});
+			signal.addEventListener("abort", () => {
+				server.close();
+				rejecter(/* @__PURE__ */ new Error("OAuth aborted"));
+			});
+			result.finally(() => server.close()).catch(() => {});
+			return {
+				port,
+				result
+			};
+		} catch (err) {
+			server.close();
+			if (err instanceof Error && "code" in err && err.code === "EADDRINUSE") continue;
+			throw err;
+		}
+	}
+	throw new Error(`All OAuth ports occupied: ${OAUTH_PORTS.join(", ")}. Close other dev servers and retry.`);
+}
+/**
+* Build the SaaS authorize URL. The SaaS authorize page expects:
+*   client_id, redirect_uri, state, site_url, scope, response_type,
+*   code_challenge, code_challenge_method
+*
+* `site_url` is the customer's project URL — used by the SaaS to
+* find-or-create the site row and tag the OAuth token to it. For
+* the wizard, we send the current working directory's git remote
+* (or a placeholder when none exists; SaaS uses it for display only).
+*/
+function buildAuthorizeUrl(opts) {
+	return `${SAAS_URL}/oauth/authorize?${new URLSearchParams({
+		client_id: WIZARD_CLIENT_ID,
+		redirect_uri: `http://localhost:${opts.port}/callback`,
+		state: opts.state,
+		site_url: opts.siteUrl,
+		scope: SCOPES.join(" "),
+		response_type: "code",
+		code_challenge: opts.codeChallenge,
+		code_challenge_method: "S256"
+	}).toString()}`;
+}
+/**
+* Exchange the authorization code for an access token. Public client
+* — no client_secret, code_verifier proves possession instead.
+*/
+async function exchangeCodeForToken(opts) {
+	const response = await fetch(`${SAAS_URL}/api/oauth/token`, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({
+			grant_type: "authorization_code",
+			code: opts.code,
+			redirect_uri: `http://localhost:${opts.port}/callback`,
+			client_id: WIZARD_CLIENT_ID,
+			code_verifier: opts.codeVerifier,
+			site_url: opts.siteUrl
+		})
+	});
+	if (!response.ok) {
+		const text = await response.text().catch(() => "");
+		throw new Error(`Token exchange failed: HTTP ${response.status} — ${text.slice(0, 200)}`);
+	}
+	const data = await response.json();
+	if (!data.access_token || !data.refresh_token) throw new Error("Token response missing access_token or refresh_token");
+	return {
+		accessToken: data.access_token,
+		refreshToken: data.refresh_token,
+		expiresIn: data.expires_in ?? 1800,
+		siteId: data.site_id ?? null
+	};
+}
+/**
+* Top-level OAuth orchestrator. Caller passes a `siteUrl` (typically
+* `git remote get-url origin` output or a placeholder) and an
+* `onUrlReady` callback so the TUI can display the URL for SSH
+* fallback at the same time the browser is opened.
+*
+* Returns the token bundle on success; throws on timeout, state
+* mismatch, or token exchange failure.
+*/
+async function performOAuthFlow(opts) {
+	const verifier = generateCodeVerifier();
+	const challenge = generateCodeChallenge(verifier);
+	const state = generateState();
+	const controller = new AbortController();
+	const timeoutHandle = setTimeout(() => controller.abort(), OAUTH_TIMEOUT_MS);
+	try {
+		const { port, result } = await startCallbackServer(state, controller.signal);
+		const authorizeUrl = buildAuthorizeUrl({
+			port,
+			state,
+			codeChallenge: challenge,
+			siteUrl: opts.siteUrl
+		});
+		opts.onUrlReady(authorizeUrl);
+		open(authorizeUrl).catch(() => {});
+		const { code } = await result;
+		return await exchangeCodeForToken({
+			code,
+			codeVerifier: verifier,
+			port,
+			siteUrl: opts.siteUrl
+		});
+	} finally {
+		clearTimeout(timeoutHandle);
+	}
+}
+function renderSuccessPage() {
+	return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<title>smking — connected</title>
+<style>
+  body { font: 14px/1.5 -apple-system, "Helvetica Neue", sans-serif; max-width: 480px; margin: 80px auto; padding: 0 24px; color: #222; }
+  h1 { font-size: 24px; }
+  .hint { color: #666; }
+</style>
+</head>
+<body>
+<h1>✅ Connected to smking</h1>
+<p>You can close this tab and return to your terminal.</p>
+<p class="hint">smking install wizard is now finishing setup.</p>
+<script>setTimeout(() => window.close(), 1500);<\/script>
+</body>
+</html>`;
+}
+function renderErrorPage(error) {
+	return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<title>smking — error</title>
+<style>
+  body { font: 14px/1.5 -apple-system, "Helvetica Neue", sans-serif; max-width: 480px; margin: 80px auto; padding: 0 24px; color: #222; }
+  h1 { font-size: 24px; color: #c00; }
+  code { background: #f4f4f4; padding: 2px 6px; border-radius: 3px; }
+</style>
+</head>
+<body>
+<h1>❌ smking OAuth failed</h1>
+<p>Error: <code>${escapeHtml(error)}</code></p>
+<p>Return to your terminal and re-run <code>npx @soloworks/smking-wizard</code>.</p>
+</body>
+</html>`;
+}
+function escapeHtml(input) {
+	return input.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+//#endregion
+//#region src/ui/screens/oauth-screen.tsx
+/**
+* OAuth screen — kicks off the browser flow on mount and waits for
+* the localhost callback. Displays the authorize URL in the TUI as
+* a fallback for SSH users who don't have a graphical browser
+* (mirroring PostHog's pattern).
+*
+* Lifecycle:
+*  1. mount → performOAuthFlow() starts
+*  2. callback server emits URL via onUrlReady → store.setOauthUrl
+*  3. user logs in + redirects to localhost → callback fires
+*  4. OAuth tokens stored → setScreen("done")
+*  5. any error → setFatal() → screen routes to "error"
+*/
+function OAuthScreen() {
+	const oauthUrl = useWizardStore((s) => s.oauthUrl);
+	const setOauthUrl = useWizardStore((s) => s.setOauthUrl);
+	const setOauth = useWizardStore((s) => s.setOauth);
+	const setScreen = useWizardStore((s) => s.setScreen);
+	const setFatal = useWizardStore((s) => s.setFatal);
+	useEffect(() => {
+		let cancelled = false;
+		performOAuthFlow({
+			siteUrl: process.cwd(),
+			onUrlReady: (url) => {
+				if (!cancelled) setOauthUrl(url);
+			}
+		}).then((tokens) => {
+			if (cancelled) return;
+			setOauth(tokens);
+			setScreen("run");
+		}).catch((err) => {
+			if (cancelled) return;
+			setFatal(`OAuth failed: ${err instanceof Error ? err.message : String(err)}`);
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, []);
+	return /* @__PURE__ */ jsxs(Box, {
+		flexDirection: "column",
+		gap: 1,
+		children: [
+			/* @__PURE__ */ jsx(Box, { children: /* @__PURE__ */ jsx(Spinner, { label: "Waiting for browser login…" }) }),
+			oauthUrl ? /* @__PURE__ */ jsxs(Box, {
+				flexDirection: "column",
+				marginTop: 1,
+				children: [/* @__PURE__ */ jsx(Text, {
+					color: "gray",
+					children: "If your browser didn't open, paste this URL into a browser:"
+				}), /* @__PURE__ */ jsx(Box, {
+					marginTop: 1,
+					children: /* @__PURE__ */ jsx(Text, {
+						color: "cyan",
+						children: oauthUrl
+					})
+				})]
+			}) : /* @__PURE__ */ jsx(Text, {
+				color: "gray",
+				children: "Generating PKCE challenge…"
+			}),
+			/* @__PURE__ */ jsx(Box, {
+				marginTop: 1,
+				children: /* @__PURE__ */ jsx(Text, {
+					color: "gray",
+					children: "Timeout: 6 minutes · Ctrl-C to abort"
+				})
+			})
+		]
+	});
+}
+
+//#endregion
+//#region src/agent/commandments.ts
+/**
+* System-prompt rules appended to whatever Claude's default coding
+* agent persona provides. Kept deliberately short — 11 numbered
+* rules, no preamble, no explanation. The install prompt itself
+* carries the framework-specific instructions; commandments cover
+* what's true regardless of framework.
+*
+* Each rule maps to one of the wizard's safety guards or design
+* decisions documented in the implementation plan. Don't add prose
+* paragraphs here — every word costs every wizard run a token.
+*/
+const COMMANDMENTS = `# Wizard agent commandments
+
+You are the install agent inside @soloworks/smking-wizard. The user's project is open in the cwd. Follow these rules without exception:
+
+1. Use only the dedicated tools listed below. You have NO Bash, NO general Read/Write/Edit. The available tools are: \`detect_framework\`, \`detect_package_manager\`, \`install_package\`, \`set_env\`, \`run_doctor\`, \`read_project_file\`, \`run_artisan\` (Laravel only), and \`report_failure\`. If a step seems to need a different tool, that step is out of scope.
+
+2. Start by calling \`detect_framework\`. If it returns \`unknown\`, call \`report_failure\` with the evidence string and stop — do not guess.
+
+3. After detecting framework, call \`install_package\` once with the detected framework.
+
+4. After \`install_package\` succeeds, call \`set_env\` with SMKING_API_KEY and SMKING_BASE_URL extracted from the install prompt the user gave you. Both must match the values in the prompt verbatim.
+
+5. After \`set_env\`, call \`run_doctor\`. Parse the JSON result.
+
+6. If \`run_doctor\` returns \`ok: true\`, you are done. Output a one-line confirmation and stop.
+
+7. If \`run_doctor\` returns \`ok: false\`, identify which check failed and try to fix it BEFORE giving up. Diagnose first, retry second:
+   - For Laravel cache/config-stale symptoms (API reachable: fail but env is set correctly; doctor flips red right after \`set_env\`): try \`run_artisan(command="config:clear")\` then \`run_artisan(command="cache:clear")\`, then re-run \`run_doctor\`. This solves a common stale-config scenario.
+   - For "X-Smking-Status: server_error" / circuit-breaker symptoms: try \`run_artisan(command="smking:cache:purge")\`, then re-run \`run_doctor\`.
+   - For unknown failures, use \`read_project_file\` to inspect \`composer.json\` (version pin), \`app/Http/Kernel.php\` (middleware register state), or \`.env\` (actual values). The content often reveals the root cause and tells you whether a retry has any chance.
+   - Only retry \`install_package\` or \`set_env\` when the inspected state confirms those are the layer to fix.
+   - Maximum THREE retries for the same failing check across ALL fix attempts combined (not three retries per fix type).
+
+8. After three failed retries on the same check — or when \`read_project_file\` reveals an unfixable condition (Laravel version too old, custom Kernel, missing PHP extension) — call \`report_failure\` with the failed check list, environment details, the raw doctor output, AND any relevant content from \`read_project_file\` that explains the root cause. Then stop.
+
+9. NEVER attempt to use git, edit files outside the wizard tools, run shell commands, or install packages other than smking SDKs. The wizard tools are the complete surface.
+
+10. NEVER include API keys, secrets, or token values in your text response. If you need to mention them, refer by name (e.g. "SMKING_API_KEY") not by value.
+
+11. Be terse. The user sees a TUI with a spinner — every paragraph you emit is a paragraph they have to wait through. One sentence per major action is enough.`;
+
+//#endregion
+//#region src/agent/prompt.ts
+/**
+* Fetch the install prompt for the detected framework from the
+* smking SaaS. The prompt content lives in
+* `apps/web/src/features/aeo/lib/install-prompts/{laravel,nextjs}.ts`
+* and has the customer's `publicApiKey` and `baseUrl` already
+* substituted server-side — wizard never receives a raw key
+* separately from the prompt itself.
+*
+* The agent reads this markdown as its initial user message, then
+* walks through the steps using the wizard's dedicated tools.
+*/
+async function fetchInstallPrompt(opts) {
+	if (opts.framework !== "laravel" && opts.framework !== "nextjs") throw new Error(`fetchInstallPrompt called with unsupported framework: ${opts.framework}`);
+	const url = new URL(`${SAAS_URL}/api/v1/wizard/install-prompt`);
+	url.searchParams.set("framework", opts.framework);
+	const response = await fetch(url, { headers: {
+		authorization: `Bearer ${opts.oauthToken}`,
+		accept: "text/markdown"
+	} });
+	if (!response.ok) {
+		const text = await response.text().catch(() => "");
+		throw new Error(`Failed to fetch install prompt: HTTP ${response.status} — ${text.slice(0, 200)}`);
+	}
+	return response.text();
+}
+
+//#endregion
+//#region src/detection/framework.ts
+function detectFramework(cwd = process.cwd()) {
+	const artisanPath = join(cwd, "artisan");
+	if (existsSync(artisanPath)) return {
+		framework: "laravel",
+		evidence: `artisan present at ${artisanPath}`
+	};
+	const pkgPath = join(cwd, "package.json");
+	if (existsSync(pkgPath)) {
+		let pkg;
+		try {
+			pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+		} catch {
+			return {
+				framework: "unknown",
+				evidence: "package.json present but unparseable"
+			};
+		}
+		if (!!pkg.dependencies?.["next"] || !!pkg.devDependencies?.["next"]) {
+			const appDir = ["app", "src/app"].find((d) => existsSync(join(cwd, d)));
+			if (!appDir) return {
+				framework: "unknown",
+				evidence: "Next.js detected but no app/ or src/app/ — wizard only supports App Router"
+			};
+			return {
+				framework: "nextjs",
+				evidence: `next in package.json + ${appDir}/ directory`,
+				appDir
+			};
+		}
+	}
+	return {
+		framework: "unknown",
+		evidence: "no `artisan` (Laravel) and no `package.json` with `next` (Next.js) found in cwd"
+	};
+}
+
+//#endregion
+//#region src/detection/package-manager.ts
+const LOCKFILES = [
+	{
+		name: "pnpm-lock.yaml",
+		pm: "pnpm"
+	},
+	{
+		name: "bun.lockb",
+		pm: "bun"
+	},
+	{
+		name: "bun.lock",
+		pm: "bun"
+	},
+	{
+		name: "yarn.lock",
+		pm: "yarn"
+	},
+	{
+		name: "package-lock.json",
+		pm: "npm"
+	}
+];
+function detectNodePackageManager(cwd = process.cwd()) {
+	for (const { name, pm } of LOCKFILES) if (existsSync(join(cwd, name))) return {
+		packageManager: pm,
+		lockfile: name
+	};
+	return {
+		packageManager: "npm",
+		lockfile: null
+	};
+}
+
+//#endregion
+//#region src/lib/exec.ts
+function run(cmd, args, opts = {}) {
+	return new Promise((resolve$1, reject) => {
+		const proc = spawn(cmd, args, {
+			cwd: opts.cwd ?? process.cwd(),
+			env: {
+				...process.env,
+				...opts.env
+			},
+			stdio: [
+				"ignore",
+				"pipe",
+				"pipe"
+			]
+		});
+		let stdout = "";
+		let stderr = "";
+		proc.stdout?.on("data", (chunk) => {
+			stdout += chunk.toString();
+		});
+		proc.stderr?.on("data", (chunk) => {
+			stderr += chunk.toString();
+		});
+		let timer;
+		if (opts.timeoutMs) timer = setTimeout(() => {
+			proc.kill("SIGTERM");
+		}, opts.timeoutMs);
+		proc.on("error", (err) => {
+			if (timer) clearTimeout(timer);
+			reject(err);
+		});
+		proc.on("close", (code) => {
+			if (timer) clearTimeout(timer);
+			resolve$1({
+				stdout,
+				stderr,
+				code: code ?? 1
+			});
+		});
+	});
+}
+
+//#endregion
+//#region src/lib/env-file.ts
+function setEnvKeys(envPath, updates) {
+	const lines = (existsSync(envPath) ? readFileSync(envPath, "utf-8") : "").split("\n");
+	const changed = [];
+	const unchanged = [];
+	for (const [key, value] of Object.entries(updates)) {
+		const idx = lines.findIndex((line) => {
+			const trimmed = line.trim();
+			if (!trimmed || trimmed.startsWith("#")) return false;
+			return trimmed.startsWith(`${key}=`);
+		});
+		if (idx >= 0) {
+			const currentLine = lines[idx];
+			if (currentLine.slice(currentLine.indexOf("=") + 1).replace(/^["']|["']$/g, "") === value) {
+				unchanged.push(key);
+				continue;
+			}
+			lines[idx] = `${key}=${value}`;
+			changed.push(key);
+		} else {
+			if (!lines.some((l) => l.includes("Added by @soloworks/smking-wizard"))) {
+				if (lines.at(-1)?.trim() !== "") lines.push("");
+				lines.push("# Added by @soloworks/smking-wizard");
+			}
+			lines.push(`${key}=${value}`);
+			changed.push(key);
+		}
+	}
+	if (changed.length > 0) writeFileSync(envPath, lines.join("\n"), "utf-8");
+	return {
+		changed,
+		unchanged
+	};
+}
+
+//#endregion
+//#region src/lib/registry.ts
+/**
+* Live registry queries for the latest published smking SDK versions.
+*
+* Why this exists: hardcoding a version (`"smking/laravel:^0.10"`) in
+* the installer goes stale the moment we ship a new minor — every
+* wizard `npx` run would then install the *previous* major.minor line
+* even though packagist already has a newer one. Querying the registry
+* at install time means the wizard always proposes the freshest stable
+* release without us re-cutting a wizard build.
+*
+* Failure mode: network down / registry returning 500 / unparseable
+* response → callers fall back to bare `composer require <pkg>` (no
+* constraint). That still installs the latest version compatible with
+* the customer's existing `composer.json` — not ideal if they're
+* pinned to an old `^0.X`, but never breaks the install.
+*/
+const REGISTRY_TIMEOUT_MS = 5e3;
+/**
+* Convert `"0.10.1"` → `"^0.10"`. Pins major.minor so consumers get
+* the latest patch in this line automatically. For composer 0.x:
+* `^0.10` resolves to `>=0.10.0 <0.11.0`. For npm same semantics.
+*/
+function toCaretRange(version) {
+	const match = version.match(/^(\d+)\.(\d+)/);
+	if (!match) throw new Error(`unparseable version string: ${version}`);
+	return `^${match[1]}.${match[2]}`;
+}
+/**
+* `https://repo.packagist.org/p2/<name>.json` returns the metadata
+* with `packages.<name>` as a newest-first array of `{version, ...}`.
+* We pick the first entry matching a clean semver tag (no `-rc`,
+* `-dev`, `-alpha`).
+*/
+async function getLatestPackagistVersion(packageName) {
+	const url = `https://repo.packagist.org/p2/${packageName}.json`;
+	const res = await fetch(url, {
+		signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS),
+		headers: { accept: "application/json" }
+	});
+	if (!res.ok) throw new Error(`packagist ${packageName} HTTP ${res.status}`);
+	const stable = ((await res.json()).packages?.[packageName] ?? []).find((v) => {
+		const ver = v.version ?? "";
+		return /^v?\d+\.\d+\.\d+$/.test(ver);
+	});
+	if (!stable?.version) throw new Error(`packagist ${packageName}: no stable version found`);
+	const version = stable.version.replace(/^v/, "");
+	return {
+		version,
+		caretRange: toCaretRange(version),
+		source: "packagist"
+	};
+}
+/**
+* npm root metadata returns `dist-tags.latest` — the version the
+* publisher tagged as the default for `npm install <name>` (with no
+* version specifier). This is what we want for "install the freshest
+* stable line"; explicit prerelease tags like `next` / `beta` are
+* intentionally ignored.
+*/
+async function getLatestNpmVersion(packageName) {
+	const url = `https://registry.npmjs.org/${packageName.replace("/", "%2F")}`;
+	const res = await fetch(url, {
+		signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS),
+		headers: { accept: "application/json" }
+	});
+	if (!res.ok) throw new Error(`npm ${packageName} HTTP ${res.status}`);
+	const latest = (await res.json())["dist-tags"]?.latest;
+	if (!latest) throw new Error(`npm ${packageName}: no latest tag`);
+	return {
+		version: latest,
+		caretRange: toCaretRange(latest),
+		source: "npm"
+	};
+}
+
+//#endregion
+//#region src/installers/laravel.ts
+async function installLaravel(ctx) {
+	const steps = [];
+	let constraint = "smking/laravel";
+	let bumpedTo = null;
+	try {
+		const latest = await getLatestPackagistVersion("smking/laravel");
+		constraint = `smking/laravel:${latest.caretRange}`;
+		bumpedTo = latest.version;
+	} catch {}
+	const composerResult = await run("composer", ["require", constraint], {
+		cwd: ctx.cwd,
+		timeoutMs: 18e4
+	});
+	if (composerResult.code !== 0) {
+		steps.push({
+			name: `composer require ${constraint}`,
+			status: "failed",
+			detail: composerResult.stderr.slice(0, 500)
+		});
+		return {
+			ok: false,
+			steps
+		};
+	}
+	const alreadyInstalled = composerResult.stdout.includes("is already in the composer.json");
+	steps.push({
+		name: `composer require ${constraint}`,
+		status: alreadyInstalled ? "skipped" : "done",
+		detail: bumpedTo ? `latest packagist: v${bumpedTo} (caret bumped)` : "registry query failed — installed at existing constraint"
+	});
+	const publishResult = await run("php", [
+		"artisan",
+		"vendor:publish",
+		"--tag=smking-config"
+	], {
+		cwd: ctx.cwd,
+		timeoutMs: 6e4
+	});
+	if (publishResult.code !== 0) {
+		steps.push({
+			name: "php artisan vendor:publish --tag=smking-config",
+			status: "failed",
+			detail: publishResult.stderr.slice(0, 500)
+		});
+		return {
+			ok: false,
+			steps
+		};
+	}
+	steps.push({
+		name: "php artisan vendor:publish --tag=smking-config",
+		status: "done"
+	});
+	if (ctx.apiKey && ctx.baseUrl && !ctx.apiKey.startsWith("<") && !ctx.baseUrl.startsWith("<")) {
+		const envChange = setEnvKeys(join(ctx.cwd, ".env"), {
+			SMKING_API_KEY: ctx.apiKey,
+			SMKING_BASE_URL: ctx.baseUrl
+		});
+		steps.push({
+			name: "Write SMKING_API_KEY + SMKING_BASE_URL to .env",
+			status: envChange.changed.length > 0 ? "done" : "skipped",
+			detail: envChange.changed.length > 0 ? `wrote: ${envChange.changed.join(", ")}` : `already set: ${envChange.unchanged.join(", ")}`
+		});
+	} else steps.push({
+		name: "Write SMKING_API_KEY + SMKING_BASE_URL to .env",
+		status: "skipped",
+		detail: "env handled by separate set_env step (wizard agent path)"
+	});
+	const clearResult = await run("php", ["artisan", "config:clear"], {
+		cwd: ctx.cwd,
+		timeoutMs: 3e4
+	});
+	if (clearResult.code !== 0) steps.push({
+		name: "php artisan config:clear",
+		status: "failed",
+		detail: clearResult.stderr.slice(0, 500)
+	});
+	else steps.push({
+		name: "php artisan config:clear",
+		status: "done"
+	});
+	return {
+		ok: true,
+		steps
+	};
+}
+
+//#endregion
+//#region src/installers/nextjs.ts
+const PM_ADD_ARGS = {
+	pnpm: ["add"],
+	bun: ["add"],
+	yarn: ["add"],
+	npm: ["install"]
+};
+async function installNextjs(ctx) {
+	const steps = [];
+	let packageSpec = "@soloworks/smking-next";
+	let bumpedTo = null;
+	try {
+		const latest = await getLatestNpmVersion("@soloworks/smking-next");
+		packageSpec = `@soloworks/smking-next@${latest.caretRange}`;
+		bumpedTo = latest.version;
+	} catch {}
+	const addArgs = [...PM_ADD_ARGS[ctx.packageManager], packageSpec];
+	const installResult = await run(ctx.packageManager, addArgs, {
+		cwd: ctx.cwd,
+		timeoutMs: 18e4
+	});
+	if (installResult.code !== 0) {
+		steps.push({
+			name: `${ctx.packageManager} ${addArgs.join(" ")}`,
+			status: "failed",
+			detail: installResult.stderr.slice(0, 500)
+		});
+		return {
+			ok: false,
+			steps
+		};
+	}
+	steps.push({
+		name: `${ctx.packageManager} ${addArgs.join(" ")}`,
+		status: "done",
+		detail: bumpedTo ? `latest npm: v${bumpedTo} (caret bumped)` : "registry query failed — installed at existing constraint"
+	});
+	if (!(ctx.apiKey && ctx.baseUrl && !ctx.apiKey.startsWith("<") && !ctx.baseUrl.startsWith("<"))) steps.push({
+		name: "Write SMKING_API_KEY + SMKING_BASE_URL to .env.local",
+		status: "skipped",
+		detail: "env handled by separate set_env step (wizard agent path)"
+	});
+	else {
+		const envChange = setEnvKeys(join(ctx.cwd, ".env.local"), {
+			SMKING_API_KEY: ctx.apiKey,
+			SMKING_BASE_URL: ctx.baseUrl
+		});
+		steps.push({
+			name: "Write SMKING_API_KEY + SMKING_BASE_URL to .env.local",
+			status: envChange.changed.length > 0 ? "done" : "skipped",
+			detail: envChange.changed.length > 0 ? `wrote: ${envChange.changed.join(", ")}` : `already set: ${envChange.unchanged.join(", ")}`
+		});
+	}
+	const layoutResult = addSmkingAEOToLayout(ctx.cwd, ctx.appDir);
+	steps.push(layoutResult);
+	if (layoutResult.status === "failed") return {
+		ok: false,
+		steps
+	};
+	return {
+		ok: true,
+		steps
+	};
+}
+/**
+* Find `<appDir>/layout.tsx` (or .jsx/.ts/.js), inject SmkingAEO
+* import + render. Idempotent: if `SmkingAEO` substring is already
+* present, returns skipped without re-editing.
+*
+* Uses targeted string manipulation rather than full AST parsing
+* because:
+*   - The edit shape is fixed (import + JSX inside <body>)
+*   - Layout files are conventional Next.js boilerplate; the
+*     vanilla case covers 95% of customers
+*   - Edge cases (custom layouts, no <body>) gracefully degrade
+*     to "manual instructions in error message"
+*
+* AST parsing (magicast / recast) is an option we may revisit if
+* field reports show this is too fragile.
+*/
+function addSmkingAEOToLayout(cwd, appDir) {
+	const layoutPath = [
+		join(cwd, appDir, "layout.tsx"),
+		join(cwd, appDir, "layout.jsx"),
+		join(cwd, appDir, "layout.ts"),
+		join(cwd, appDir, "layout.js")
+	].find((p) => existsSync(p));
+	if (!layoutPath) return {
+		name: "Inject <SmkingAEO /> into root layout",
+		status: "failed",
+		detail: `no layout file found under ${appDir}/ — add <SmkingAEO apiKey={process.env.SMKING_API_KEY!} /> to your root layout manually`
+	};
+	const content = readFileSync(layoutPath, "utf-8");
+	if (content.includes("SmkingAEO")) return {
+		name: "Inject <SmkingAEO /> into root layout",
+		status: "skipped",
+		detail: `${layoutPath} already references SmkingAEO`
+	};
+	const importMatches = [...content.matchAll(/^import\s+[^;]+;?\s*$/gm)];
+	if (importMatches.length === 0) return {
+		name: "Inject <SmkingAEO /> into root layout",
+		status: "failed",
+		detail: `${layoutPath} has no import statements — add SmkingAEO manually`
+	};
+	const lastImport = importMatches[importMatches.length - 1];
+	const lastImportEnd = lastImport.index + lastImport[0].length;
+	let updated = content.slice(0, lastImportEnd) + "\nimport { SmkingAEO } from \"@soloworks/smking-next\";" + content.slice(lastImportEnd);
+	const bodyMatch = updated.match(/<body([^>]*)>/);
+	if (!bodyMatch || bodyMatch.index === void 0) return {
+		name: "Inject <SmkingAEO /> into root layout",
+		status: "failed",
+		detail: `${layoutPath} has no <body> tag — add SmkingAEO manually inside <body>`
+	};
+	const bodyEnd = bodyMatch.index + bodyMatch[0].length;
+	updated = updated.slice(0, bodyEnd) + "\n        <SmkingAEO apiKey={process.env.SMKING_API_KEY!} />" + updated.slice(bodyEnd);
+	writeFileSync(layoutPath, updated, "utf-8");
+	return {
+		name: "Inject <SmkingAEO /> into root layout",
+		status: "done",
+		detail: `wrote import + render to ${layoutPath}`
+	};
+}
+
+//#endregion
+//#region src/agent/tools.ts
+function asResult(value) {
+	return JSON.stringify(value);
+}
+function stepIcon(status) {
+	return status === "done" ? "✓" : status === "skipped" ? "⊝" : "✗";
+}
+function buildWizardTools(ctx) {
+	const pushProgress = (text) => useWizardStore.getState().pushProgress(text);
+	return [
+		{
+			name: "detect_framework",
+			description: "Detect whether the current project is Laravel or Next.js. Returns { framework, evidence, appDir? }. Always call this first before any install steps.",
+			input_schema: {
+				type: "object",
+				properties: {}
+			},
+			run: async () => {
+				pushProgress("Detecting framework…");
+				const result = detectFramework(ctx.cwd);
+				pushProgress(result.framework === "unknown" ? `Framework: unknown (${result.evidence})` : `Framework: ${result.framework}`);
+				return asResult(result);
+			}
+		},
+		{
+			name: "detect_package_manager",
+			description: "Detect the Node package manager from the project's lockfile (pnpm / bun / yarn / npm). Returns { packageManager, lockfile }.",
+			input_schema: {
+				type: "object",
+				properties: {}
+			},
+			run: async () => {
+				const result = detectNodePackageManager(ctx.cwd);
+				pushProgress(`Package manager: ${result.packageManager}${result.lockfile ? ` (${result.lockfile})` : " (no lockfile, assuming npm)"}`);
+				return asResult(result);
+			}
+		},
+		{
+			name: "install_package",
+			description: "Install the smking SDK for the detected framework. Runs composer require + vendor:publish + config:clear (Laravel), or pnpm/npm/yarn/bun add + edit layout.tsx (Next.js). Idempotent — already-installed steps return 'skipped'. Returns { ok, steps[] }.",
+			input_schema: {
+				type: "object",
+				properties: { framework: {
+					type: "string",
+					enum: ["laravel", "nextjs"],
+					description: "Framework to install for (must match detect_framework result)"
+				} },
+				required: ["framework"]
+			},
+			run: async (input) => {
+				const { framework } = input;
+				pushProgress(`Installing smking SDK for ${framework}…`);
+				if (framework === "laravel") {
+					const result$1 = await installLaravel({
+						apiKey: "<set-by-set_env>",
+						baseUrl: "<set-by-set_env>",
+						cwd: ctx.cwd
+					});
+					for (const step of result$1.steps) pushProgress(`  ${stepIcon(step.status)} ${step.name}`);
+					return asResult(result$1);
+				}
+				const detection = detectFramework(ctx.cwd);
+				if (detection.framework !== "nextjs" || !detection.appDir) return asResult({
+					ok: false,
+					steps: [{
+						name: "install_nextjs",
+						status: "failed",
+						detail: "framework re-detection returned non-nextjs — call detect_framework first and confirm"
+					}]
+				});
+				const pmDetection = detectNodePackageManager(ctx.cwd);
+				const result = await installNextjs({
+					apiKey: "<set-by-set_env>",
+					baseUrl: "<set-by-set_env>",
+					cwd: ctx.cwd,
+					packageManager: pmDetection.packageManager,
+					appDir: detection.appDir
+				});
+				for (const step of result.steps) pushProgress(`  ${stepIcon(step.status)} ${step.name}`);
+				return asResult(result);
+			}
+		},
+		{
+			name: "set_env",
+			description: "Write SMKING_API_KEY and/or SMKING_BASE_URL to the project's env file (.env for Laravel, .env.local for Next.js). Other keys are rejected. Idempotent.",
+			input_schema: {
+				type: "object",
+				properties: {
+					SMKING_API_KEY: {
+						type: "string",
+						description: "Publishable site API key (starts with pk_)"
+					},
+					SMKING_BASE_URL: {
+						type: "string",
+						description: "smking SaaS base URL (e.g. https://smking.com)"
+					}
+				}
+			},
+			run: async (input) => {
+				pushProgress("Setting env values…");
+				const typed = input;
+				const allowedKeys = new Set(["SMKING_API_KEY", "SMKING_BASE_URL"]);
+				const updates = {};
+				for (const [k, v] of Object.entries(typed)) {
+					if (!allowedKeys.has(k) || typeof v !== "string") continue;
+					updates[k] = v;
+				}
+				if (Object.keys(updates).length === 0) return asResult({ error: "set_env called with no valid keys. Allowed: SMKING_API_KEY, SMKING_BASE_URL." });
+				const envFile = detectFramework(ctx.cwd).framework === "nextjs" ? ".env.local" : ".env";
+				const result = setEnvKeys(join(ctx.cwd, envFile), updates);
+				pushProgress(`Env: changed=[${result.changed.join(", ")}] unchanged=[${result.unchanged.join(", ")}]`);
+				return asResult({
+					envFile,
+					...result
+				});
+			}
+		},
+		{
+			name: "run_doctor",
+			description: "Run the smking doctor self-check (php artisan smking:doctor --json for Laravel, smking-next doctor --json for Next.js). Returns structured JSON: { checks: [{name, status, detail}], summary: {passed, failed, info, ok} }.",
+			input_schema: {
+				type: "object",
+				properties: {}
+			},
+			run: async () => {
+				pushProgress("Running smking:doctor…");
+				const framework = detectFramework(ctx.cwd).framework;
+				let cmd;
+				let args;
+				if (framework === "laravel") {
+					cmd = "php";
+					args = [
+						"artisan",
+						"smking:doctor",
+						"--json"
+					];
+				} else if (framework === "nextjs") {
+					const pm = detectNodePackageManager(ctx.cwd).packageManager;
+					if (pm === "pnpm") {
+						cmd = "pnpm";
+						args = [
+							"exec",
+							"smking-next",
+							"doctor",
+							"--json"
+						];
+					} else if (pm === "bun") {
+						cmd = "bunx";
+						args = [
+							"smking-next",
+							"doctor",
+							"--json"
+						];
+					} else if (pm === "yarn") {
+						cmd = "yarn";
+						args = [
+							"smking-next",
+							"doctor",
+							"--json"
+						];
+					} else {
+						cmd = "npx";
+						args = [
+							"smking-next",
+							"doctor",
+							"--json"
+						];
+					}
+				} else return asResult({
+					ok: false,
+					error: `Cannot run doctor — framework is ${framework}`
+				});
+				const result = await run(cmd, args, {
+					cwd: ctx.cwd,
+					timeoutMs: 6e4
+				});
+				try {
+					const parsed = JSON.parse(result.stdout);
+					const failed = parsed.summary?.failed ?? 0;
+					pushProgress(`Doctor: ${parsed.summary?.passed ?? 0} pass · ${failed} fail · ${parsed.summary?.info ?? 0} info`);
+					return asResult(parsed);
+				} catch {
+					return asResult({
+						ok: false,
+						error: `Doctor output was not JSON (exit code ${result.code})`,
+						stdout: result.stdout.slice(0, 1e3),
+						stderr: result.stderr.slice(0, 1e3)
+					});
+				}
+			}
+		},
+		{
+			name: "read_project_file",
+			description: "Read a project file (relative path inside cwd) so you can inspect its content when debugging an install or doctor failure. Use this BEFORE concluding a problem is unfixable — composer.json reveals constraint pins, Kernel.php reveals middleware register state, .env reveals what's actually set. Allowed file types: json, php, ts, tsx, js, jsx, env, conf, yaml, yml, md, lock, htaccess. Returns { path, content, bytes } or { error }.",
+			input_schema: {
+				type: "object",
+				properties: { path: {
+					type: "string",
+					description: "Project-relative path, e.g. `composer.json`, `app/Http/Kernel.php`, `.env`, `app/layout.tsx`. No absolute paths, no `..`."
+				} },
+				required: ["path"]
+			},
+			run: async (input) => {
+				const { path } = input;
+				pushProgress(`Reading ${path}…`);
+				if (path.startsWith("/") || path.includes("..")) return asResult({ error: "absolute paths and `..` traversal are not allowed" });
+				const absPath = resolve(ctx.cwd, path);
+				const rel = relative(ctx.cwd, absPath);
+				if (rel.startsWith("..") || resolve(rel) === resolve("")) return asResult({ error: "resolved path escapes cwd" });
+				const allowedExt = /\.(json|php|ts|tsx|js|jsx|env|conf|yaml|yml|md|lock|htaccess)$/i;
+				const basename = path.split("/").pop() ?? "";
+				const allowedBasename = new Set([
+					".env",
+					".env.local",
+					".env.production",
+					".env.example",
+					".htaccess"
+				]);
+				if (!allowedExt.test(basename) && !allowedBasename.has(basename)) return asResult({ error: `file extension not allowed: ${basename}` });
+				try {
+					const content = await promises.readFile(absPath, "utf-8");
+					const truncated = content.length > 5e4 ? content.slice(0, 5e4) + "\n... [truncated at 50KB]" : content;
+					pushProgress(`  read ${path} (${content.length} bytes)`);
+					return asResult({
+						path,
+						content: truncated,
+						bytes: content.length
+					});
+				} catch (err) {
+					return asResult({ error: err instanceof Error ? err.message : String(err) });
+				}
+			}
+		},
+		{
+			name: "run_artisan",
+			description: "Run a Laravel artisan command from a fixed allowlist. Use for cache/config recovery (cache:clear, config:clear), SDK-specific inspection (smking:status, smking:cache:purge), or route confirmation (route:list). Not for arbitrary fixes — if you need a command not in the allowlist, call report_failure instead. Returns { exitCode, stdout, stderr }.",
+			input_schema: {
+				type: "object",
+				properties: {
+					command: {
+						type: "string",
+						enum: [
+							"smking:doctor",
+							"smking:cache:purge",
+							"smking:status",
+							"smking:publish-robots",
+							"config:clear",
+							"config:cache",
+							"cache:clear",
+							"route:list"
+						],
+						description: "Artisan command name (no `php artisan` prefix). Must be one of the allowlist values."
+					},
+					args: {
+						type: "array",
+						items: { type: "string" },
+						description: "Optional CLI flags. Allowed forms: `--json`, `--force`, `--tag=<value>`, `--path=<value>`, `--key=<value>`. Other flags are rejected."
+					}
+				},
+				required: ["command"]
+			},
+			run: async (input) => {
+				const { command, args = [] } = input;
+				const framework = detectFramework(ctx.cwd).framework;
+				if (framework !== "laravel") return asResult({ error: `run_artisan only works in Laravel projects (detected: ${framework})` });
+				if (!new Set([
+					"smking:doctor",
+					"smking:cache:purge",
+					"smking:status",
+					"smking:publish-robots",
+					"config:clear",
+					"config:cache",
+					"cache:clear",
+					"route:list"
+				]).has(command)) return asResult({ error: `command not in allowlist: ${command}` });
+				const PLAIN_FLAGS = new Set(["--json", "--force"]);
+				const PARAMETRIC = /^--(tag|path|key)=[\w/.:_\-+]+$/;
+				for (const arg of args) if (!PLAIN_FLAGS.has(arg) && !PARAMETRIC.test(arg)) return asResult({ error: `disallowed flag: ${arg}` });
+				pushProgress(`php artisan ${command} ${args.join(" ")}`.trim());
+				const result = await run("php", [
+					"artisan",
+					command,
+					...args
+				], {
+					cwd: ctx.cwd,
+					timeoutMs: 6e4
+				});
+				return asResult({
+					command,
+					args,
+					exitCode: result.code,
+					stdout: result.stdout.slice(0, 5e3),
+					stderr: result.stderr.slice(0, 2e3)
+				});
+			}
+		},
+		{
+			name: "report_failure",
+			description: "Report an unfixable install failure to smking support. Call this only after retrying the same failing check 3 times. Posts to smking dashboard. Returns { ticketId }.",
+			input_schema: {
+				type: "object",
+				properties: {
+					failed_checks: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {
+								name: { type: "string" },
+								status: {
+									type: "string",
+									enum: [
+										"pass",
+										"fail",
+										"info"
+									]
+								},
+								detail: { type: "string" }
+							},
+							required: [
+								"name",
+								"status",
+								"detail"
+							]
+						},
+						minItems: 1
+					},
+					environment: {
+						type: "object",
+						additionalProperties: { type: "string" }
+					},
+					raw_output: { type: "string" }
+				},
+				required: [
+					"failed_checks",
+					"environment",
+					"raw_output"
+				]
+			},
+			run: async (input) => {
+				pushProgress("Reporting failure to smking support…");
+				const typed = input;
+				const framework = detectFramework(ctx.cwd).framework;
+				const response = await fetch(`${SAAS_URL}/api/v1/doctor-reports`, {
+					method: "POST",
+					headers: {
+						authorization: `Bearer ${ctx.oauthToken}`,
+						"content-type": "application/json"
+					},
+					body: JSON.stringify({
+						framework,
+						failed_checks: typed.failed_checks,
+						environment: typed.environment,
+						raw_output: typed.raw_output
+					})
+				});
+				if (!response.ok) {
+					const text = await response.text().catch(() => "");
+					return asResult({
+						ok: false,
+						error: `report_failure HTTP ${response.status}: ${text.slice(0, 200)}`
+					});
+				}
+				const data = await response.json();
+				pushProgress(`Reported · ticket ${data.ticketId ?? "(no id)"}`);
+				return asResult(data);
+			}
+		}
+	];
+}
+
+//#endregion
+//#region src/agent/runtime.ts
+/**
+* File-based debug logger. ink TUI takes over stdout/stderr so
+* `console.log` is invisible during a wizard run. Writing to
+* `/tmp/smking-wizard.log` gives us a tail-able stream of what's
+* happening inside the agent loop.
+*/
+const DEBUG_LOG = "/tmp/smking-wizard.log";
+function debugLog(msg, data) {
+	try {
+		const stamp = (/* @__PURE__ */ new Date()).toISOString();
+		appendFileSync(DEBUG_LOG, data ? `${stamp} ${msg} ${JSON.stringify(data, null, 2)}\n` : `${stamp} ${msg}\n`);
+	} catch {}
+}
+const MAX_ITERATIONS = 30;
+async function runAgent(ctx) {
+	debugLog("=== runAgent starting ===", {
+		cwd: ctx.cwd,
+		siteId: ctx.siteId,
+		saasUrl: SAAS_URL
+	});
+	const detection = detectFramework(ctx.cwd);
+	debugLog("framework detection result", detection);
+	if (detection.framework === "unknown") return {
+		ok: false,
+		message: `Unable to detect framework in ${ctx.cwd}. ${detection.evidence}`
+	};
+	const client = new Anthropic({
+		baseURL: `${SAAS_URL}/api/v1/wizard/gateway`,
+		authToken: ctx.oauthToken,
+		maxRetries: 0
+	});
+	debugLog("fetching install prompt", { framework: detection.framework });
+	const installPrompt = await fetchInstallPrompt({
+		framework: detection.framework,
+		oauthToken: ctx.oauthToken
+	});
+	debugLog("install prompt fetched", { length: installPrompt.length });
+	const toolDefs = buildWizardTools(ctx);
+	debugLog("tools built", {
+		count: toolDefs.length,
+		names: toolDefs.map((t) => t.name)
+	});
+	const tools = toolDefs.map((t) => ({
+		name: t.name,
+		description: t.description,
+		input_schema: t.input_schema
+	}));
+	const handlers = new Map(toolDefs.map((t) => [t.name, t.run]));
+	const messages = [{
+		role: "user",
+		content: installPrompt
+	}];
+	try {
+		let lastTextSummary = "";
+		let doctorPassed = false;
+		let reportedFailure = false;
+		for (let iteration = 0; iteration < MAX_ITERATIONS; iteration++) {
+			debugLog(`iteration ${iteration} — calling messages.create`);
+			const apiCallPromise = client.messages.create({
+				model: "claude-opus-4-7",
+				max_tokens: 16e3,
+				thinking: { type: "adaptive" },
+				system: [{
+					type: "text",
+					text: COMMANDMENTS,
+					cache_control: { type: "ephemeral" }
+				}],
+				tools,
+				messages
+			});
+			const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error("messages.create timed out after 60s")), 6e4));
+			const response = await Promise.race([apiCallPromise, timeoutPromise]);
+			debugLog(`iteration ${iteration} — response received`, {
+				stop_reason: response.stop_reason,
+				content_block_types: response.content.map((c) => c.type),
+				usage: response.usage
+			});
+			messages.push({
+				role: "assistant",
+				content: response.content
+			});
+			const texts = response.content.filter((c) => c.type === "text").map((c) => c.text).join("\n").trim();
+			if (texts) lastTextSummary = texts;
+			if (response.stop_reason === "end_turn") {
+				debugLog("end_turn reached — agent done");
+				break;
+			}
+			if (response.stop_reason !== "tool_use") {
+				debugLog("non-tool_use stop_reason — exiting loop", { stop_reason: response.stop_reason });
+				return {
+					ok: false,
+					message: `Agent stopped unexpectedly (${response.stop_reason}): ${lastTextSummary || "no text emitted"}`
+				};
+			}
+			const toolResults = [];
+			for (const block of response.content) {
+				if (block.type !== "tool_use") continue;
+				const handler = handlers.get(block.name);
+				if (!handler) {
+					debugLog("unknown tool called", { name: block.name });
+					toolResults.push({
+						type: "tool_result",
+						tool_use_id: block.id,
+						content: JSON.stringify({ error: `Unknown tool: ${block.name}. Available tools: ${[...handlers.keys()].join(", ")}` }),
+						is_error: true
+					});
+					continue;
+				}
+				debugLog("calling tool handler", {
+					name: block.name,
+					input: block.input
+				});
+				try {
+					const result = await handler(block.input);
+					debugLog("tool handler returned", {
+						name: block.name,
+						resultLength: result.length
+					});
+					if (block.name === "run_doctor") try {
+						if (JSON.parse(result).summary?.ok === true) doctorPassed = true;
+					} catch {}
+					else if (block.name === "report_failure") reportedFailure = true;
+					toolResults.push({
+						type: "tool_result",
+						tool_use_id: block.id,
+						content: result
+					});
+				} catch (err) {
+					const msg = err instanceof Error ? err.message : String(err);
+					debugLog("tool handler threw", {
+						name: block.name,
+						error: msg
+					});
+					toolResults.push({
+						type: "tool_result",
+						tool_use_id: block.id,
+						content: JSON.stringify({ error: msg }),
+						is_error: true
+					});
+				}
+			}
+			messages.push({
+				role: "user",
+				content: toolResults
+			});
+		}
+		const ok = doctorPassed && !reportedFailure;
+		debugLog("loop exited — returning summary", {
+			ok,
+			doctorPassed,
+			reportedFailure,
+			summary: lastTextSummary
+		});
+		return {
+			ok,
+			message: lastTextSummary || (ok ? "Wizard completed." : "Wizard ended without a successful doctor run.")
+		};
+	} catch (err) {
+		debugLog("agent loop threw", {
+			error: err instanceof Error ? err.message : String(err),
+			stack: err instanceof Error ? err.stack : void 0
+		});
+		return {
+			ok: false,
+			message: err instanceof Error ? err.message : `Agent loop failed: ${String(err)}`
+		};
+	}
+}
+
+//#endregion
+//#region src/ui/screens/run-screen.tsx
+/**
+* Live agent screen. Mounts → kicks off the install agent loop →
+* routes to done/error based on result. Renders the rolling
+* progress log + a spinner showing the latest action.
+*
+* Progress entries come from `pushProgress` calls inside each
+* wizard tool's `run` handler. The log is capped at 50 lines in
+* the store; we render the latest 12 to fit in a typical terminal
+* without scrolling.
+*/
+function RunScreen() {
+	const oauth = useWizardStore((s) => s.oauth);
+	const agentStatus = useWizardStore((s) => s.agentStatus);
+	const agentProgress = useWizardStore((s) => s.agentProgress);
+	const setAgentStatus = useWizardStore((s) => s.setAgentStatus);
+	const setAgentSummary = useWizardStore((s) => s.setAgentSummary);
+	const setScreen = useWizardStore((s) => s.setScreen);
+	const setFatal = useWizardStore((s) => s.setFatal);
+	useEffect(() => {
+		if (agentStatus !== "idle") return;
+		if (!oauth) {
+			setFatal("Reached run screen without OAuth tokens — restart wizard.");
+			return;
+		}
+		let cancelled = false;
+		setAgentStatus("running");
+		runAgent({
+			cwd: process.cwd(),
+			oauthToken: oauth.accessToken,
+			siteId: oauth.siteId
+		}).then((result) => {
+			if (cancelled) return;
+			setAgentSummary(result.message);
+			if (result.ok) {
+				setAgentStatus("succeeded");
+				setScreen("done");
+			} else {
+				setAgentStatus("failed");
+				setFatal(result.message);
+			}
+		}).catch((err) => {
+			if (cancelled) return;
+			const msg = err instanceof Error ? err.message : String(err);
+			setAgentStatus("failed");
+			setFatal(`Agent crashed: ${msg}`);
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, []);
+	const visibleLines = agentProgress.slice(-12);
+	return /* @__PURE__ */ jsxs(Box, {
+		flexDirection: "column",
+		gap: 1,
+		children: [
+			/* @__PURE__ */ jsx(Box, { children: /* @__PURE__ */ jsx(Spinner, { label: agentProgress[agentProgress.length - 1] ?? "Starting agent…" }) }),
+			visibleLines.length > 1 ? /* @__PURE__ */ jsx(Box, {
+				flexDirection: "column",
+				marginTop: 1,
+				children: visibleLines.slice(0, -1).map((line, idx) => /* @__PURE__ */ jsx(Text, {
+					color: "gray",
+					children: line
+				}, idx))
+			}) : null,
+			/* @__PURE__ */ jsx(Box, {
+				marginTop: 1,
+				children: /* @__PURE__ */ jsx(Text, {
+					color: "gray",
+					children: "Ctrl-C to abort"
+				})
+			})
+		]
+	});
+}
+
+//#endregion
+//#region src/ui/screens/done-screen.tsx
+/**
+* Terminal state after a successful wizard run. Reached when
+* `runAgent` returns `ok: true` — meaning `run_doctor` returned
+* `summary.ok === true` AND `report_failure` was never called
+* (see runtime.ts for the gate).
+*
+* Shows the agent's own summary message so the customer sees what
+* actually got installed / verified, not a generic "connected".
+*
+* Press any key to exit. Auto-exits after 15s — longer than the
+* error-screen's 8s because customers need time to read the
+* pass/fail breakdown and notice any info-level recommendations.
+*/
+function DoneScreen() {
+	const { exit } = useApp();
+	const oauth = useWizardStore((s) => s.oauth);
+	const agentSummary = useWizardStore((s) => s.agentSummary);
+	useInput(() => {
+		exit();
+	});
+	useEffect(() => {
+		const timer = setTimeout(() => exit(), 15e3);
+		return () => clearTimeout(timer);
+	}, [exit]);
+	return /* @__PURE__ */ jsxs(Box, {
+		flexDirection: "column",
+		gap: 1,
+		children: [
+			/* @__PURE__ */ jsx(Text, {
+				bold: true,
+				color: "green",
+				children: "✅ smking installed"
+			}),
+			agentSummary ? /* @__PURE__ */ jsx(Text, { children: agentSummary }) : null,
+			oauth?.siteId ? /* @__PURE__ */ jsxs(Text, {
+				color: "gray",
+				children: [
+					"Site: ",
+					oauth.siteId,
+					" · token expires in",
+					" ",
+					Math.round(oauth.expiresIn / 60),
+					" minutes"
+				]
+			}) : null,
+			/* @__PURE__ */ jsx(Box, {
+				marginTop: 1,
+				children: /* @__PURE__ */ jsx(Text, {
+					color: "gray",
+					children: "Press any key to exit (auto-exit in 15s)."
+				})
+			})
+		]
+	});
+}
+
+//#endregion
+//#region src/ui/screens/error-screen.tsx
+/**
+* Fatal-error terminal screen. Any `setFatal()` call from anywhere
+* in the wizard routes here. Shows the error message and exits 1
+* on key press / auto-exit so callers can detect failure.
+*/
+function ErrorScreen() {
+	const { exit } = useApp();
+	const fatal = useWizardStore((s) => s.fatal);
+	useInput(() => {
+		exit(new Error(fatal ?? "wizard failed"));
+	});
+	useEffect(() => {
+		const timer = setTimeout(() => exit(new Error(fatal ?? "wizard failed")), 8e3);
+		return () => clearTimeout(timer);
+	}, [exit, fatal]);
+	return /* @__PURE__ */ jsxs(Box, {
+		flexDirection: "column",
+		gap: 1,
+		children: [
+			/* @__PURE__ */ jsx(Text, {
+				bold: true,
+				color: "red",
+				children: "❌ Wizard failed"
+			}),
+			/* @__PURE__ */ jsx(Text, { children: fatal ?? "Unknown error" }),
+			/* @__PURE__ */ jsx(Box, {
+				marginTop: 1,
+				children: /* @__PURE__ */ jsxs(Text, {
+					color: "gray",
+					children: [
+						"Press any key to exit (auto-exit in 8s). Re-run",
+						" ",
+						/* @__PURE__ */ jsx(Text, {
+							color: "cyan",
+							children: "npx @soloworks/smking-wizard"
+						}),
+						" after fixing the issue."
+					]
+				})
+			})
+		]
+	});
+}
+
+//#endregion
+//#region src/ui/app.tsx
+/**
+* Root component. Routes by `store.screen` and renders the matching
+* full-screen view. Each screen owns its own lifecycle (useEffect)
+* — App.tsx itself is a switch, nothing more.
+*/
+function App() {
+	const screen = useWizardStore((s) => s.screen);
+	return /* @__PURE__ */ jsxs(Box, {
+		flexDirection: "column",
+		paddingX: 1,
+		paddingY: 1,
+		children: [
+			screen === "welcome" && /* @__PURE__ */ jsx(WelcomeScreen, {}),
+			screen === "oauth" && /* @__PURE__ */ jsx(OAuthScreen, {}),
+			screen === "run" && /* @__PURE__ */ jsx(RunScreen, {}),
+			screen === "done" && /* @__PURE__ */ jsx(DoneScreen, {}),
+			screen === "error" && /* @__PURE__ */ jsx(ErrorScreen, {})
+		]
+	});
+}
+
+//#endregion
+//#region src/bin.ts
+/**
+* `npx @soloworks/smking-wizard` entry point.
+*
+* Phase 3 scope: parse args, check Node version, render the ink TUI.
+* Phase 4+ adds framework detection / installer dispatch / agent
+* loop — those plug into the TUI via the zustand store, not via new
+* command-line subcommands. The wizard is single-command on purpose
+* (PostHog model): one `npx @soloworks/smking-wizard` does everything.
+*/
+function checkNodeVersion() {
+	const [maj, min] = process.versions.node.split(".").map(Number);
+	if (maj < MIN_NODE_MAJOR || maj === MIN_NODE_MAJOR && min < MIN_NODE_MINOR) {
+		process.stderr.write(`smking wizard requires Node ${MIN_NODE_MAJOR}.${MIN_NODE_MINOR}+. You have ${process.versions.node}.\n`);
+		process.exit(1);
+	}
+}
+async function main() {
+	checkNodeVersion();
+	const argv = await yargs(hideBin(process.argv)).scriptName("smking-wizard").usage("$0 [options]").option("debug", {
+		type: "boolean",
+		default: false,
+		describe: "Enable verbose debug output"
+	}).option("dry-run", {
+		type: "boolean",
+		default: false,
+		describe: "Print intended changes without writing files (Phase 4+)"
+	}).option("allow-prod", {
+		type: "boolean",
+		default: false,
+		describe: "Override the production-environment refusal (use only if you know why)"
+	}).option("allow-dirty", {
+		type: "boolean",
+		default: false,
+		describe: "Override the git-status-must-be-clean check (use only if you know why)"
+	}).version(WIZARD_VERSION).help().strict().parse();
+	if (argv.debug) process.env.SMKING_WIZARD_DEBUG = "1";
+	useWizardStore.getState().setCliFlags({
+		allowProd: !!argv["allow-prod"],
+		allowDirty: !!argv["allow-dirty"],
+		dryRun: !!argv["dry-run"],
+		debug: !!argv.debug
+	});
+	const { waitUntilExit } = render(createElement(App));
+	try {
+		await waitUntilExit();
+		return 0;
+	} catch (err) {
+		process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+		return 1;
+	}
+}
+main().then((code) => process.exit(code), (err) => {
+	process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+	process.exit(1);
+});
+
+//#endregion
+export {  };
+//# sourceMappingURL=bin.mjs.map