@boldare/askdare 0.0.0-stage → 0.1.0-rc.0

package/dist/cli.js

@@ -0,0 +1,1461 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { parseArgs, parseEnv } from "node:util";
+import { appendFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { z } from "zod";
+import { EncryptJWT, errors, jwtDecrypt, jwtVerify } from "jose";
+import { execFile } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { createHash, randomBytes } from "node:crypto";
+import OpenAI, { NotFoundError, toFile } from "openai";
+// src/protocol/doctor.ts
+const check = z.object({
+	status: z.enum([
+		"ok",
+		"warn",
+		"fail"
+	]),
+	title: z.string().max(500),
+	fix: z.string().max(500).optional()
+});
+const doctorReportSchema = z.object({
+	development: z.boolean(),
+	sharedLimits: z.boolean(),
+	gallery: z.boolean(),
+	bots: z.array(z.object({
+		id: z.string().max(48),
+		checks: z.array(check).max(20),
+		turnTimeoutMs: z.number().int().positive().optional()
+	})).max(50)
+});
+// src/security/identity.ts
+const MIN_SECRET_LENGTH$1 = 32;
+const MIN_DISTINCT_CHARACTERS$1 = 12;
+/** Longest allowed gap between `iat` and `exp`. */
+const MAX_LIFETIME_SECONDS = 86400;
+/** Identities travel inside access tokens, which the widget sends with every request. */
+const MAX_IDENTITY_BYTES = 2048;
+const MAX_CLAIMS = 20;
+const REGISTERED = /* @__PURE__ */ new Set([
+	"iss",
+	"sub",
+	"aud",
+	"exp",
+	"nbf",
+	"iat",
+	"jti",
+	"name",
+	"email"
+]);
+const encoder$1 = new TextEncoder();
+/**
+* Display names are often edited by the users themselves and may end up in instructions: one
+* line, no control characters.
+*/
+const oneLine = (text) => text.normalize("NFKC").replace(/\p{Cc}+/gu, " ").replace(/\s+/g, " ").trim();
+/** The identity part of a JWT payload, or undefined when a claim has the wrong shape. */
+function identityFromClaims(payload) {
+	const { sub } = payload;
+	if (typeof sub !== "string" || sub.length === 0 || sub.length > 256) return void 0;
+	const field = (value) => typeof value === "string" ? oneLine(value) || void 0 : value ?? void 0;
+	const name = field(payload["name"]);
+	const email = field(payload["email"]);
+	if (name !== void 0 && (typeof name !== "string" || name.length > 200)) return void 0;
+	if (email !== void 0 && (typeof email !== "string" || email.length > 320)) return void 0;
+	const claims = {};
+	for (const [key, value] of Object.entries(payload)) {
+		if (REGISTERED.has(key)) continue;
+		if (key.length > 64) return void 0;
+		if (typeof value === "string" || typeof value === "boolean") claims[key] = value;
+		else if (typeof value === "number" && Number.isFinite(value)) claims[key] = value;
+	}
+	if (Object.keys(claims).length > MAX_CLAIMS) return void 0;
+	return {
+		id: sub,
+		...name === void 0 ? {} : { name },
+		...email === void 0 ? {} : { email },
+		claims
+	};
+}
+/**
+* Checks identity JWTs from the site's backend: HS256 with IDENTITY_SECRET, the bot as audience,
+* a bounded lifetime (ADR-0009).
+*/
+function createIdentityVerifier(options) {
+	const { secret } = options;
+	if (secret.length < MIN_SECRET_LENGTH$1 || new Set(secret).size < MIN_DISTINCT_CHARACTERS$1) throw new TypeError(`[askdare] IDENTITY_SECRET must be at least ${MIN_SECRET_LENGTH$1} random characters. Generate one with: node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"`);
+	if (secret === options.chatSecret) throw new TypeError("[askdare] IDENTITY_SECRET must differ from CHAT_SECRET.");
+	const key = encoder$1.encode(secret);
+	const now = options.now ?? (() => Math.floor(Date.now() / 1e3));
+	const hmac = crypto.subtle.importKey("raw", key, {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	return {
+		async key(botId, identity) {
+			const mac = await crypto.subtle.sign("HMAC", await hmac, encoder$1.encode(`askdare identity key v1\n${botId}\n${identity.id}`));
+			return Array.from(new Uint8Array(mac).slice(0, 16), (byte) => byte.toString(16).padStart(2, "0")).join("");
+		},
+		async verify(token, botId) {
+			let payload;
+			try {
+				({payload} = await jwtVerify(token, key, {
+					algorithms: ["HS256"],
+					audience: botId,
+					requiredClaims: [
+						"sub",
+						"iat",
+						"exp"
+					],
+					maxTokenAge: MAX_LIFETIME_SECONDS,
+					currentDate: /* @__PURE__ */ new Date(now() * 1e3),
+					clockTolerance: 30
+				}));
+			} catch (error) {
+				if (error instanceof errors.JWTExpired) return {
+					ok: false,
+					reason: "expired"
+				};
+				if (error instanceof errors.JWSSignatureVerificationFailed) return {
+					ok: false,
+					reason: "signature"
+				};
+				if (error instanceof errors.JWTClaimValidationFailed && error.claim === "aud") return {
+					ok: false,
+					reason: "audience"
+				};
+				if (error instanceof errors.JWTClaimValidationFailed && error.claim === "iat") return {
+					ok: false,
+					reason: "lifetime"
+				};
+				return {
+					ok: false,
+					reason: "malformed"
+				};
+			}
+			const { iat, exp } = payload;
+			if (typeof iat !== "number" || typeof exp !== "number" || exp <= iat || exp - iat > MAX_LIFETIME_SECONDS) return {
+				ok: false,
+				reason: "lifetime"
+			};
+			const identity = identityFromClaims(payload);
+			if (!identity) return {
+				ok: false,
+				reason: "claims"
+			};
+			if (encoder$1.encode(JSON.stringify(identity)).length > MAX_IDENTITY_BYTES) return {
+				ok: false,
+				reason: "too_large"
+			};
+			if (exp <= now()) return {
+				ok: false,
+				reason: "expired"
+			};
+			return {
+				ok: true,
+				verified: {
+					identity,
+					expiresAt: Math.min(exp, now() + MAX_LIFETIME_SECONDS)
+				}
+			};
+		}
+	};
+}
+// src/errors.ts
+const HTTP_STATUS = {
+	invalid_input: 400,
+	unauthorized: 401,
+	session_expired: 401,
+	not_found: 404,
+	content_blocked: 422,
+	rate_limited: 429,
+	budget_exceeded: 429,
+	internal_error: 500,
+	upstream_error: 502,
+	bot_unavailable: 503,
+	timeout: 504
+};
+const DEFAULT_MESSAGES = {
+	invalid_input: "The request was invalid.",
+	unauthorized: "Authentication is required.",
+	session_expired: "Your session has expired. Please try again.",
+	not_found: "Not found.",
+	content_blocked: "This message cannot be processed.",
+	rate_limited: "Too many messages. Please wait a moment.",
+	budget_exceeded: "The assistant is unavailable for the rest of the day.",
+	internal_error: "Something went wrong. Please try again.",
+	upstream_error: "The assistant is temporarily unavailable. Please try again.",
+	bot_unavailable: "The assistant is currently unavailable.",
+	timeout: "The assistant took too long to respond. Please try again."
+};
+/** An error with a stable, client-safe code. Anything else that escapes becomes `internal_error`. */
+var AskdareError = class extends Error {
+	name = "AskdareError";
+	code;
+	status;
+	retryAfterMs;
+	key;
+	params;
+	constructor(code, options = {}) {
+		super(options.message ?? DEFAULT_MESSAGES[code], { cause: options.cause });
+		this.code = code;
+		this.status = HTTP_STATUS[code];
+		this.retryAfterMs = options.retryAfterMs;
+		this.key = options.key ?? (options.message === void 0 ? `error.${code}` : void 0);
+		this.params = options.params;
+	}
+};
+// src/security/tokens.ts
+const ISSUER = "askdare";
+const ACCESS_TYP = "askdare-access+jwt";
+const RESUME_TYP = "askdare-resume+jwt";
+const ATTACHMENT_TYP = "askdare-attachment+jwt";
+const DOCTOR_TYP = "askdare-doctor+jwt";
+const DOCTOR_AUDIENCE = "askdare-doctor";
+const DOCTOR_TTL_SECONDS = 120;
+const MIN_SECRET_LENGTH = 32;
+const MIN_DISTINCT_CHARACTERS = 12;
+const VISITOR_ID = /^v_[0-9a-f]{32}$/;
+const CONVERSATION_ID = /^conv_[A-Za-z0-9_-]{1,128}$/;
+const FILE_ID = /^file-[A-Za-z0-9_-]{1,128}$/;
+/** How long after expiry an access token still identifies its visitor for a renewal. */
+const RENEWAL_GRACE_SECONDS = 3600;
+const encoder = new TextEncoder();
+async function deriveKey(secret, name) {
+	if (secret.length < MIN_SECRET_LENGTH || new Set(secret).size < MIN_DISTINCT_CHARACTERS) throw new TypeError(`[askdare] ${name} must be at least ${MIN_SECRET_LENGTH} random characters. Generate one with: node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"`);
+	const material = await crypto.subtle.importKey("raw", encoder.encode(secret), "HKDF", false, ["deriveBits"]);
+	const derive = async (info, bits) => new Uint8Array(await crypto.subtle.deriveBits({
+		name: "HKDF",
+		hash: "SHA-256",
+		salt: encoder.encode(ISSUER),
+		info: encoder.encode(info)
+	}, material, bits));
+	return {
+		kid: Array.from(await derive("askdare kid v1", 64), (byte) => byte.toString(16).padStart(2, "0")).join(""),
+		key: await derive("askdare token encryption v1", 256),
+		pseudonymKey: await derive("askdare pseudonym v1", 256)
+	};
+}
+/** The identity an access token carries, while it lasts. Our own encrypted claim: no re-check needed. */
+function identityOf(payload, now) {
+	const { idn, ixp } = payload;
+	if (typeof idn !== "object" || idn === null || typeof ixp !== "number" || ixp <= now) return;
+	return {
+		identity: idn,
+		expiresAt: ixp
+	};
+}
+async function createTokenService(options) {
+	const current = await deriveKey(options.secret, "CHAT_SECRET");
+	const keys = /* @__PURE__ */ new Map([[current.kid, current.key]]);
+	for (const secret of options.previousSecrets ?? []) {
+		const previous = await deriveKey(secret, "CHAT_SECRET_PREVIOUS");
+		keys.set(previous.kid, previous.key);
+	}
+	const now = options.now ?? (() => Math.floor(Date.now() / 1e3));
+	const accessTtl = options.accessTtlSeconds ?? 900;
+	const resumeTtl = options.resumeTtlSeconds ?? 2592e3;
+	const attachmentTtl = options.attachmentTtlSeconds ?? 3600;
+	const pseudonymKey = await crypto.subtle.importKey("raw", current.pseudonymKey, {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	async function issue(typ, botId, subject, ttl, claims = {}) {
+		const issuedAt = now();
+		const expiresAt = issuedAt + ttl;
+		return {
+			token: await new EncryptJWT(claims).setProtectedHeader({
+				alg: "dir",
+				enc: "A256GCM",
+				typ,
+				kid: current.kid
+			}).setIssuer(ISSUER).setAudience(botId).setSubject(subject).setIssuedAt(issuedAt).setExpirationTime(expiresAt).encrypt(current.key),
+			expiresAt
+		};
+	}
+	async function verify(token, typ, botId, clockTolerance = 0) {
+		const resolveKey = (header) => {
+			const key = header.kid === void 0 ? void 0 : keys.get(header.kid);
+			if (!key) throw new errors.JWEDecryptionFailed();
+			return key;
+		};
+		return jwtDecrypt(token, resolveKey, {
+			requiredClaims: [
+				"exp",
+				"iat",
+				"sub"
+			],
+			issuer: ISSUER,
+			audience: botId,
+			typ,
+			keyManagementAlgorithms: ["dir"],
+			contentEncryptionAlgorithms: ["A256GCM"],
+			currentDate: /* @__PURE__ */ new Date(now() * 1e3),
+			clockTolerance
+		});
+	}
+	return {
+		issueAccess: (botId, visitorId, identity) => issue(ACCESS_TYP, botId, visitorId, identity ? Math.max(1, Math.min(accessTtl, identity.expiresAt - now())) : accessTtl, identity ? {
+			idn: { ...identity.identity },
+			ixp: identity.expiresAt
+		} : {}),
+		async verifyAccess(token, botId) {
+			try {
+				const { payload } = await verify(token, ACCESS_TYP, botId);
+				if (typeof payload.sub !== "string" || !VISITOR_ID.test(payload.sub)) throw new AskdareError("unauthorized");
+				return {
+					visitorId: payload.sub,
+					identity: identityOf(payload, now())
+				};
+			} catch (error) {
+				if (error instanceof errors.JWTExpired) throw new AskdareError("session_expired", { cause: error });
+				throw new AskdareError("unauthorized", { cause: error });
+			}
+		},
+		async verifyRenewal(token, botId) {
+			try {
+				const { payload } = await verify(token, ACCESS_TYP, botId, RENEWAL_GRACE_SECONDS);
+				if (typeof payload.sub !== "string" || !VISITOR_ID.test(payload.sub)) throw new AskdareError("unauthorized");
+				return {
+					visitorId: payload.sub,
+					identity: identityOf(payload, now())
+				};
+			} catch (error) {
+				throw new AskdareError("unauthorized", { cause: error });
+			}
+		},
+		async pseudonym(value) {
+			const digest = await crypto.subtle.sign("HMAC", pseudonymKey, encoder.encode(value));
+			return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+		},
+		issueResume: (botId, grant) => issue(RESUME_TYP, botId, grant.visitorId, resumeTtl, {
+			cid: grant.conversationId,
+			...grant.identityKey ? { ids: grant.identityKey } : {}
+		}),
+		async verifyResume(token, botId) {
+			try {
+				const { payload } = await verify(token, RESUME_TYP, botId);
+				const { cid, ids } = payload;
+				if (typeof payload.sub !== "string" || !VISITOR_ID.test(payload.sub) || typeof cid !== "string" || !CONVERSATION_ID.test(cid) || ids !== void 0 && typeof ids !== "string") throw new AskdareError("not_found");
+				return {
+					visitorId: payload.sub,
+					conversationId: cid,
+					...ids === void 0 ? {} : { identityKey: ids }
+				};
+			} catch (error) {
+				throw new AskdareError("not_found", { cause: error });
+			}
+		},
+		issueAttachment: (botId, grant) => issue(ATTACHMENT_TYP, botId, grant.visitorId, attachmentTtl, {
+			fid: grant.fileId,
+			knd: grant.kind,
+			est: grant.tokens
+		}),
+		async verifyAttachment(token, botId) {
+			const invalid = (cause) => new AskdareError("invalid_input", {
+				message: "An attachment expired or is invalid. Please attach it again.",
+				key: "error.attachmentExpired",
+				cause
+			});
+			let payload;
+			try {
+				({payload} = await verify(token, ATTACHMENT_TYP, botId));
+			} catch (error) {
+				throw invalid(error);
+			}
+			const { fid, knd, est } = payload;
+			if (typeof payload.sub !== "string" || !VISITOR_ID.test(payload.sub) || typeof fid !== "string" || !FILE_ID.test(fid) || knd !== "image" && knd !== "pdf" || typeof est !== "number" || !Number.isSafeInteger(est) || est < 0) throw invalid();
+			return {
+				visitorId: payload.sub,
+				fileId: fid,
+				kind: knd,
+				tokens: est
+			};
+		},
+		issueDoctor: () => issue(DOCTOR_TYP, DOCTOR_AUDIENCE, "doctor", DOCTOR_TTL_SECONDS),
+		async verifyDoctor(token) {
+			try {
+				await verify(token, DOCTOR_TYP, DOCTOR_AUDIENCE);
+			} catch {
+				throw new AskdareError("unauthorized");
+			}
+		}
+	};
+}
+// src/cli/project.ts
+const LOCKFILES = [
+	["pnpm-lock.yaml", "pnpm"],
+	["yarn.lock", "yarn"],
+	["bun.lock", "bun"],
+	["bun.lockb", "bun"],
+	["package-lock.json", "npm"]
+];
+/** Walks up from `start` (a monorepo keeps its lockfile and .gitignore at the top). */
+function findUp(start, test) {
+	for (let dir = start;; dir = dirname(dir)) {
+		if (test(dir)) return dir;
+		if (dirname(dir) === dir || existsSync(join(dir, ".git"))) return void 0;
+	}
+}
+async function readProject(root) {
+	let dependencies;
+	try {
+		const json = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
+		dependencies = {
+			...json.devDependencies,
+			...json.dependencies
+		};
+	} catch {
+		dependencies = void 0;
+	}
+	const appDir = [join(root, "app"), join(root, "src", "app")].find((dir) => existsSync(dir));
+	let packageManager = "npm";
+	findUp(root, (dir) => {
+		const lock = LOCKFILES.find(([file]) => existsSync(join(dir, file)));
+		if (lock) packageManager = lock[1];
+		return lock !== void 0;
+	});
+	return {
+		root,
+		dependencies,
+		appDir,
+		typescript: existsSync(join(root, "tsconfig.json")),
+		packageManager
+	};
+}
+/** The version installed in `node_modules`; undefined when the package isn't installed. */
+function installedVersion(project, name) {
+	let version;
+	findUp(project.root, (dir) => {
+		try {
+			const manifest = readFileSync(join(dir, "node_modules", name, "package.json"), "utf8");
+			version = JSON.parse(manifest).version;
+			return true;
+		} catch {
+			return false;
+		}
+	});
+	return version;
+}
+/** Whether a version (or range like `^4.1.0`) is at least `major.minor`; undefined if unreadable. */
+function atLeast(version, major, minor = 0) {
+	const match = /(\d+)(?:\.(\d+))?/.exec(version ?? "");
+	if (match?.[1] === void 0) return void 0;
+	const [have, haveMinor] = [Number(match[1]), Number(match[2] ?? 0)];
+	return have > major || have === major && haveMinor >= minor;
+}
+function majorOf(version) {
+	const match = /(\d+)/.exec(version ?? "");
+	return match?.[1] === void 0 ? void 0 : Number(match[1]);
+}
+/** The catch-all route file for a base path, e.g. `app/api/chat/[...path]/route.ts`. */
+function routeDir(project, basePath) {
+	return project.appDir && join(project.appDir, ...basePath.split("/").filter(Boolean), "[...path]");
+}
+function findFile(dir, name) {
+	if (dir === void 0) return void 0;
+	return [
+		"ts",
+		"tsx",
+		"js",
+		"jsx",
+		"mjs"
+	].map((extension) => join(dir, `${name}.${extension}`)).find((file) => existsSync(file));
+}
+/** A path relative to the project, with forward slashes, for messages. */
+function shown(project, file) {
+	return relative(project.root, file).split(sep).join("/");
+}
+function runScript(project, script) {
+	return project.packageManager === "npm" ? `npm run ${script}` : `${project.packageManager} ${script}`;
+}
+function addCommand(project, packages) {
+	return `${project.packageManager === "npm" ? "npm install" : `${project.packageManager} add`} ${packages.join(" ")}`;
+}
+/**
+* Environment as `next dev` sees it: the shell, then `.env.development.local`, `.env.local`,
+* `.env.development` and `.env`. An explicit `envFile` wins over the shell instead: it is what
+* the user asked to check. Read without changing `process.env`.
+*/
+async function readEnv(root, envFile, shell = process.env) {
+	const files = envFile ? [envFile] : [
+		".env.development.local",
+		".env.local",
+		".env.development",
+		".env"
+	];
+	const loaded = [];
+	const env = {};
+	for (const file of files.toReversed()) {
+		let text;
+		try {
+			text = await readFile(resolve(root, file), "utf8");
+		} catch (error) {
+			if (envFile) throw error;
+			continue;
+		}
+		Object.assign(env, parseEnv(text));
+		loaded.unshift(file);
+	}
+	return {
+		env: envFile ? {
+			...shell,
+			...env
+		} : {
+			...env,
+			...shell
+		},
+		files: loaded
+	};
+}
+/** Whether git ignores `name`, a file in `root`: git's own answer, or 'unknown' without git. */
+function gitCheckIgnore(root, name) {
+	return new Promise((done) => {
+		execFile("git", [
+			"check-ignore",
+			"-q",
+			"--",
+			name
+		], {
+			cwd: root,
+			timeout: 5e3
+		}, (error) => {
+			if (error === null) done(true);
+			else done(error.code === 1 ? false : "unknown");
+		});
+	});
+}
+const GLOB_ONLY = /^[^/?[\]\\]+$/;
+/**
+* Whether git ignores `name`, a file in `root`. Asks git; outside a repository (or without git)
+* reads the project's own .gitignore, and answers no whenever a line is beyond a simple glob.
+*/
+async function gitIgnores(root, name) {
+	const verdict = await gitCheckIgnore(root, name);
+	if (verdict !== "unknown") return verdict;
+	let text;
+	try {
+		text = await readFile(join(root, ".gitignore"), "utf8");
+	} catch {
+		return false;
+	}
+	let ignored = false;
+	for (const line of text.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		const negated = trimmed.startsWith("!");
+		const pattern = (negated ? trimmed.slice(1) : trimmed).replace(/^\//, "");
+		if (pattern.includes("/") && !pattern.startsWith("**/")) continue;
+		if (!GLOB_ONLY.test(pattern)) {
+			if (negated) return false;
+			continue;
+		}
+		if (new RegExp(`^${pattern.replace(/[.+^${}()|]/g, "\\$&").replaceAll("*", "[^/]*")}$`).test(name)) ignored = !negated;
+	}
+	return ignored;
+}
+// src/cli/doctor.ts
+const ok = (title) => ({
+	status: "ok",
+	title
+});
+const warn = (title, fix) => ({
+	status: "warn",
+	title,
+	fix
+});
+const fail = (title, fix) => ({
+	status: "fail",
+	title,
+	fix
+});
+const PROXY_FIX = "Exclude askdare's routes in proxy.ts, e.g. matcher: ['/((?!api/chat|_next/static|_next/image).*)'].";
+function versions(project) {
+	const checks = [];
+	const node = majorOf(process.versions.node) ?? 0;
+	checks.push(node >= 22 ? ok(`Node ${process.versions.node}`) : fail(`Node ${process.versions.node} is too old.`, "Use Node 22 or later."));
+	const wanted = [
+		[
+			"next",
+			16,
+			0,
+			"Next.js 16"
+		],
+		[
+			"react",
+			19,
+			0,
+			"React 19"
+		],
+		[
+			"zod",
+			4,
+			1,
+			"zod 4.1 or later"
+		],
+		[
+			"@boldare/askdare",
+			0,
+			0,
+			"@boldare/askdare"
+		]
+	];
+	const found = [];
+	for (const [name, major, minor, label] of wanted) {
+		const version = installedVersion(project, name);
+		if (version === void 0) checks.push(fail(`${name} is not installed.`, project.dependencies?.[name] ? `Run ${project.packageManager} install.` : `askdare needs ${label}: ${addCommand(project, [name])}`));
+		else if (!atLeast(version, major, minor)) checks.push(fail(`${name} ${version} is too old.`, `askdare needs ${label}.`));
+		else found.push(`${name} ${version}`);
+	}
+	if (found.length > 0) checks.splice(1, 0, ok(found.join(", ")));
+	return checks;
+}
+async function files(project, basePath) {
+	if (project.appDir === void 0) return [fail("No app/ or src/app/ folder.", "askdare needs the App Router.")];
+	const checks = [];
+	const route = findFile(routeDir(project, basePath), "route");
+	if (route === void 0) checks.push(fail(`No route at ${shown(project, join(routeDir(project, basePath) ?? "", "route.ts"))}.`, "Run `npx @boldare/askdare init`, or pass --base-path if you mounted askdare elsewhere."));
+	else {
+		const text = await readFile(route, "utf8");
+		const maxDuration = /export\s+const\s+maxDuration\s*=\s*(\d[\d_]*)/.exec(text)?.[1];
+		if (!text.includes("createChatHandler")) checks.push(fail(`${shown(project, route)} doesn't call createChatHandler.`));
+		else if (/export\s+const\s+runtime\s*=\s*['"]edge['"]/.test(text)) checks.push(fail(`${shown(project, route)} uses the Edge runtime.`, "askdare runs on Node.js only; remove `runtime`."));
+		else if (maxDuration === void 0) checks.push(warn(`${shown(project, route)} has no literal maxDuration.`, "Add `export const maxDuration = 300;` so long answers aren’t cut off on Vercel."));
+		else checks.push(ok(`${shown(project, route)} (maxDuration ${maxDuration.replaceAll("_", "")} s)`));
+	}
+	const middleware = [project.root, join(project.root, "src")].map((dir) => findFile(dir, "middleware")).find(Boolean);
+	if (middleware) checks.push(warn(`${shown(project, middleware)} is deprecated in Next.js 16.`, "Rename it to proxy.ts; the live checks below show whether it blocks askdare."));
+	return checks;
+}
+/** `remote`: checking a deployed app, whose own key and model the live checks cover. */
+async function environment(project, env, envFiles, remote) {
+	const checks = [];
+	if (!remote) checks.push(env["OPENAI_API_KEY"] ? ok("OPENAI_API_KEY is set.") : fail("OPENAI_API_KEY is not set.", "Add the key of a dedicated OpenAI project to .env.local."));
+	const secret = env["CHAT_SECRET"];
+	const previous = (env["CHAT_SECRET_PREVIOUS"] ?? "").split(",").map((value) => value.trim()).filter(Boolean);
+	if (!secret) checks.push(fail("CHAT_SECRET is not set.", `Generate one: node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"`));
+	else try {
+		await createTokenService({
+			secret,
+			previousSecrets: previous
+		});
+		checks.push(ok(previous.length > 0 ? "CHAT_SECRET and CHAT_SECRET_PREVIOUS are strong." : "CHAT_SECRET is strong."));
+	} catch (error) {
+		checks.push(fail(error.message.replace("[askdare] ", "")));
+	}
+	const identitySecret = env["IDENTITY_SECRET"];
+	if (identitySecret) try {
+		createIdentityVerifier({
+			secret: identitySecret,
+			chatSecret: secret
+		});
+		checks.push(ok("IDENTITY_SECRET is strong and differs from CHAT_SECRET."));
+	} catch (error) {
+		checks.push(fail(error.message.replace("[askdare] ", "")));
+	}
+	const config = findFile(project.root, "askdare.config");
+	const usesModelVariable = env["ASKDARE_MODEL"] !== void 0 || config !== void 0 && (await readFile(config, "utf8")).includes("ASKDARE_MODEL");
+	if (!remote && usesModelVariable && !env["ASKDARE_MODEL"]) checks.push(fail(env["ASKDARE_MODEL"] === void 0 ? "ASKDARE_MODEL is not set." : "ASKDARE_MODEL is empty.", "Set it to a current OpenAI model your project may use, here and in every environment of your host (on Vercel: Production and Preview). Without a model the app fails to start."));
+	for (const file of envFiles) {
+		const name = relative(project.root, resolve(project.root, file));
+		if (name.startsWith("..") || isAbsolute(name) || await gitIgnores(project.root, name)) continue;
+		const values = parseEnv(await readFile(join(project.root, name), "utf8"));
+		if (values["OPENAI_API_KEY"] || values["CHAT_SECRET"]) checks.push(fail(`${name} holds secrets but is not in .gitignore.`, `Add \`${name.endsWith(".local") ? ".env*.local" : ".env*"}\` to .gitignore before you commit.`));
+	}
+	return checks;
+}
+async function request(fetcher, url, init = {}) {
+	try {
+		return await fetcher(url, {
+			redirect: "manual",
+			signal: AbortSignal.timeout(12e4),
+			...init
+		});
+	} catch {
+		return fail(`Could not reach ${url}.`);
+	}
+}
+function redirectOrMissing(response, url) {
+	if (response.status >= 300 && response.status < 400) return fail(`${url} redirects to ${response.headers.get("location") ?? "another page"}.`, PROXY_FIX);
+}
+/** What the browser needs from widget.js and the chat page; things in front of askdare can break it. */
+async function headers(fetcher, base, botId, origin) {
+	const checks = [];
+	const loaderUrl = `${base}/widget.js?bot=${botId}`;
+	const loader = await request(fetcher, loaderUrl);
+	if (!(loader instanceof Response)) return [loader];
+	const embedUrl = `${base}/embed/${botId}`;
+	const embed = await request(fetcher, embedUrl);
+	if (!(embed instanceof Response)) return [embed];
+	const loaderProblem = redirectOrMissing(loader, loaderUrl);
+	if (loaderProblem) checks.push(loaderProblem);
+	else if (!loader.ok || !(loader.headers.get("content-type") ?? "").includes("javascript")) checks.push(fail(`${loaderUrl} answered HTTP ${loader.status} instead of the script.`, PROXY_FIX));
+	else checks.push(ok("widget.js loads."));
+	const embedProblem = redirectOrMissing(embed, embedUrl);
+	if (embedProblem) checks.push(embedProblem);
+	else if (!embed.ok) checks.push(fail(`${embedUrl} answered HTTP ${embed.status}.`, PROXY_FIX));
+	else {
+		const ancestors = [...(embed.headers.get("content-security-policy") ?? "").matchAll(/frame-ancestors\s+([^;,]*)/g)].map((match) => match[1]?.trim());
+		const fix = "Leave /api/chat out of the headers() in next.config and of proxy.ts.";
+		if (origin !== void 0 && ancestors.length === 1) {
+			const allowed = (ancestors[0] ?? "").split(/\s+/);
+			const self = new URL(base).origin === origin;
+			checks.push(self || allowed.includes(origin) ? ok(`${origin} may embed the chat.`) : fail(`${origin} may not embed the chat: it isn't in the bot's security.allowedOrigins.`, `Add '${origin}' to security.allowedOrigins of bot "${botId}" and deploy.`));
+		}
+		if (embed.headers.has("x-frame-options")) checks.push(fail("X-Frame-Options on the chat page stops sites from embedding it.", fix));
+		else if (ancestors.length !== 1) checks.push(fail(ancestors.length === 0 ? "The chat page lost its frame-ancestors policy." : "A second Content-Security-Policy on the chat page overrides who may embed it.", fix));
+		else checks.push(ok(`Sites that may embed the chat: ${ancestors[0]}`));
+	}
+	if (loader.headers.has("set-cookie") || embed.headers.has("set-cookie")) checks.push(warn("Something sets cookies on askdare's responses.", "askdare uses no cookies; leave /api/chat out of the code that sets them."));
+	await Promise.all([loader.body?.cancel(), embed.body?.cancel()]);
+	return checks;
+}
+/** The literal `maxDuration` of the askdare route, in seconds, if the file has one. */
+async function maxDurationOf(project, basePath) {
+	const route = findFile(routeDir(project, basePath), "route");
+	if (!route) return void 0;
+	const value = /export\s+const\s+maxDuration\s*=\s*(\d[\d_]*)/.exec(await readFile(route, "utf8"))?.[1];
+	return value === void 0 ? void 0 : Number(value.replaceAll("_", ""));
+}
+/**
+* A bot whose answers may run longer than the route may: the platform ends the function first and
+* the answer is cut off. 15 s of headroom for the history read and the stream's end.
+*/
+function timeout(bot, routeSeconds) {
+	if (bot.turnTimeoutMs === void 0 || routeSeconds === void 0) return [];
+	const needed = Math.ceil(bot.turnTimeoutMs / 1e3) + 15;
+	return needed > routeSeconds ? [warn(`An answer may take up to ${Math.ceil(bot.turnTimeoutMs / 1e3)} s, but the route's maxDuration is ${routeSeconds} s.`, `Raise maxDuration to at least ${needed}, or lower limits.turnTimeoutMs.`)] : [];
+}
+async function live(options, project, env) {
+	const base = `${options.url.replace(/\/+$/, "")}${options.basePath}`;
+	const fetcher = options.fetch ?? fetch;
+	const title = `App at ${options.url}`;
+	const start = `Start the app (${runScript(project, "dev")}) or pass --url with where it runs.`;
+	let token;
+	try {
+		token = (await (await createTokenService({ secret: env["CHAT_SECRET"] ?? "" })).issueDoctor()).token;
+	} catch {
+		return [{
+			title,
+			checks: [warn("Skipped: the live checks need CHAT_SECRET.")]
+		}];
+	}
+	const response = await request(fetcher, `${base}/doctor`, {
+		method: "POST",
+		headers: { authorization: `Bearer ${token}` }
+	});
+	if (!(response instanceof Response)) return [{
+		title,
+		checks: [{
+			...response,
+			fix: start
+		}]
+	}];
+	const problem = redirectOrMissing(response, `${base}/doctor`);
+	if (problem) return [{
+		title,
+		checks: [problem]
+	}];
+	const json = await response.json().catch(() => void 0);
+	if (!response.ok) {
+		const code = json?.error?.code;
+		return [{
+			title,
+			checks: [response.status === 404 && code === void 0 ? fail(`No askdare route at ${base}.`, "Check --url and --base-path, and the route file.") : code === "unauthorized" ? fail("The app rejected the doctor's token: its CHAT_SECRET differs from yours.", "Run doctor with the CHAT_SECRET of that app, e.g. --env-file .env.production.local.") : code === "not_found" ? fail("This app's askdare has no doctor endpoint.", "Update @boldare/askdare.") : code === "bot_unavailable" ? fail("The app is switched off (ASKDARE_DISABLED) or has no CHAT_SECRET where it runs.") : code === "rate_limited" ? fail("Too many doctor runs at once or this minute.", "Try again in a minute.") : fail(`${base}/doctor answered HTTP ${response.status}.`, "Check the app’s logs.")]
+		}];
+	}
+	const parsed = doctorReportSchema.safeParse(json);
+	if (!parsed.success) return [{
+		title,
+		checks: [fail(`${base}/doctor did not answer like askdare.`, PROXY_FIX)]
+	}];
+	const report = parsed.data;
+	const app = [ok(report.development ? "Reachable (development)." : "Reachable (production).")];
+	if (!report.development && report.gallery) app.push(warn("The state gallery is on.", "Turn `gallery` off in production."));
+	if (!report.development && !report.sharedLimits) app.push(warn("Rate limits and budgets are kept in memory, per instance.", "Fine for one server; with more (Vercel, several dynos) use @boldare/askdare-upstash."));
+	const sections = [{
+		title,
+		checks: app
+	}];
+	const routeSeconds = await maxDurationOf(project, options.basePath);
+	for (const bot of report.bots) sections.push({
+		title: `Bot "${bot.id}"`,
+		checks: [
+			...bot.checks,
+			...await headers(fetcher, base, bot.id, options.origin),
+			...timeout(bot, routeSeconds)
+		]
+	});
+	return sections;
+}
+const MARK = {
+	ok: "✓",
+	warn: "!",
+	fail: "✗"
+};
+/** localhost and loopback addresses: the app runs on this machine, with the env files here. */
+function isLocal(url) {
+	return /^(localhost|127\.0\.0\.1|\[::1\])$|\.localhost$/.test(new URL(url).hostname);
+}
+/** `askdare doctor`: checks the project, its environment and the running app. Returns failures. */
+async function doctor(options) {
+	const project = await readProject(options.root);
+	const { env, files: envFiles } = await readEnv(options.root, options.envFile, options.shell);
+	const sections = [
+		{
+			title: "Project",
+			checks: [...versions(project), ...await files(project, options.basePath)]
+		},
+		{
+			title: `Environment (${envFiles.join(", ") || "shell only"})`,
+			checks: await environment(project, env, envFiles, !isLocal(options.url))
+		},
+		...await live(options, project, env)
+	];
+	options.print("askdare doctor");
+	for (const section of sections) {
+		options.print(`\n${section.title}`);
+		for (const check of section.checks) {
+			options.print(`  ${MARK[check.status]} ${check.title}`);
+			if (check.fix) options.print(`    → ${check.fix}`);
+		}
+	}
+	const all = sections.flatMap((section) => section.checks);
+	const failures = all.filter((check) => check.status === "fail").length;
+	const warnings = all.filter((check) => check.status === "warn").length;
+	const plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+	options.print(failures + warnings === 0 ? "\nAll good." : `\n${plural(failures, "problem")}, ${plural(warnings, "warning")}.`);
+	return failures;
+}
+// src/cli/init.ts
+var InitError = class extends Error {};
+const BOT_ID = /^[a-z0-9][a-z0-9-]{0,47}$/;
+function configTemplate(botId) {
+	return `import { defineBot } from '@boldare/askdare';
+
+export const bots = [
+  defineBot({
+    id: '${botId}',
+    // Required: a current OpenAI model your project may use. Set ASKDARE_MODEL in .env.local.
+    model: process.env.ASKDARE_MODEL ?? '',
+    instructions: ({ locale }) =>
+      [
+        'You are the assistant on our website. Answer briefly and politely.',
+        'If you do not know something, say so.',
+        \`Reply in the language of the visitor's message; default to \${locale}.\`,
+      ].join(' '),
+    security: {
+      // Other sites that may embed the chat, e.g. ['https://www.example.com'].
+      allowedOrigins: [],
+    },
+    widget: {
+      locale: 'auto',
+      greeting: 'Hi! How can I help?',
+      theme: 'aura', // aura, halo, sage or care
+    },
+    // Knowledge base, tools, attachments, voice and limits: see node_modules/@boldare/askdare/docs.
+  }),
+];
+`;
+}
+function routeTemplate(configImport) {
+	return `import { createChatHandler } from '@boldare/askdare/next';
+import { bots } from '${configImport}';
+
+// Must be a literal in this file; keep it above the bots' turn timeout (120 s by default).
+export const maxDuration = 300;
+
+export const { GET, POST, DELETE } = createChatHandler({ bots });
+`;
+}
+async function readText(file) {
+	try {
+		return await readFile(file, "utf8");
+	} catch {
+		return "";
+	}
+}
+/**
+* Adds the variables `.env.local` and `.env` don't mention yet; never changes existing lines.
+* Returns what it added and the variables that are still empty.
+*/
+async function addEnv(project, model) {
+	const file = join(project.root, ".env.local");
+	const current = await readText(file);
+	const known = {
+		...parseEnv(await readText(join(project.root, ".env"))),
+		...parseEnv(current)
+	};
+	const variables = [
+		[
+			"OPENAI_API_KEY",
+			"Key from a dedicated OpenAI project with a hard spend limit.",
+			""
+		],
+		[
+			"CHAT_SECRET",
+			"Signs visitor sessions. Generated by askdare init; use a different one in production.",
+			randomBytes(32).toString("base64url")
+		],
+		[
+			"ASKDARE_MODEL",
+			"A current OpenAI model your project may use.",
+			model ?? ""
+		]
+	];
+	const lines = [];
+	const added = [];
+	const values = { ...known };
+	for (const [name, comment, value] of variables) {
+		if (Object.hasOwn(known, name)) continue;
+		lines.push(`# ${comment}`, `${name}=${value}`);
+		added.push(name === "CHAT_SECRET" ? "CHAT_SECRET (generated)" : name);
+		values[name] = value;
+	}
+	const empty = variables.map(([name]) => name).filter((name) => values[name] === "");
+	if (lines.length === 0) return {
+		added,
+		empty
+	};
+	const separator = current === "" || current.endsWith("\n\n") ? "" : current.endsWith("\n") ? "\n" : "\n\n";
+	await appendFile(file, `${separator}# askdare\n${lines.join("\n")}\n`, { mode: 384 });
+	return {
+		added,
+		empty
+	};
+}
+/** The chat script as `next/script`: loaded after hydration, so React never sees it in the body. */
+const scriptTag = (botId) => `<Script src="/api/chat/widget.js?bot=${botId}" strategy="afterInteractive" />`;
+const SCRIPT_IMPORT = "import Script from 'next/script';";
+/** Adds the `next/script` import after the layout's last import (or at the top). */
+function withScriptImport(text) {
+	if (/from\s+['"]next\/script['"]/.test(text)) return text;
+	const imports = [...text.matchAll(/^import[^;]*;/gm)];
+	const last = imports[imports.length - 1];
+	if (last === void 0) return `${SCRIPT_IMPORT}\n\n${text}`;
+	const end = last.index + last[0].length;
+	return `${text.slice(0, end)}\n${SCRIPT_IMPORT}${text.slice(end)}`;
+}
+/** Puts the loader before `</body>` of the root layout, if there is exactly one. */
+async function addScript(project, botId) {
+	const layout = findFile(project.appDir, "layout");
+	if (layout === void 0) return "manual";
+	const text = await readFile(layout, "utf8");
+	if (text.includes("/api/chat/widget.js")) return "present";
+	const matches = [...text.matchAll(/^([ \t]*)(.*?)<\/body>/gm)];
+	if (matches.length !== 1 || matches[0] === void 0) return "manual";
+	const [match] = matches;
+	const script = scriptTag(botId);
+	const at = match.index + match[0].length - 7;
+	const tag = match[2] === "" ? `  ${script}\n${match[1]}` : script;
+	await writeFile(layout, withScriptImport(`${text.slice(0, at)}${tag}${text.slice(at)}`));
+	return "added";
+}
+const AGENT_RULES = `<!-- BEGIN:askdare-agent-rules -->
+
+## Website chat (askdare)
+
+The chat uses \`@boldare/askdare\`. Before changing \`askdare.config.*\`, the \`api/chat\` route or the chat script, read \`node_modules/@boldare/askdare/llms.txt\` and the guide it points to; they match the installed version. After a change, run \`npx @boldare/askdare doctor\`.
+
+<!-- END:askdare-agent-rules -->
+`;
+/** Points AI coding agents at the docs in the package, next to the block Next.js writes. */
+async function addAgentRules(project) {
+	const file = join(project.root, "AGENTS.md");
+	const text = await readText(file);
+	if (text.includes("BEGIN:askdare-agent-rules")) return false;
+	await writeFile(file, text === "" ? AGENT_RULES : `${text.trimEnd()}\n\n${AGENT_RULES}`);
+	return true;
+}
+/**
+* `askdare init`: the route, a bot config, `.env.local`, the script tag and a note for AI coding
+* agents. Never overwrites what is there.
+*/
+async function init(options) {
+	const { print, botId } = options;
+	if (!BOT_ID.test(botId)) throw new InitError("The bot ID may only use a-z, 0-9 and hyphens, up to 48 characters, and must not start with a hyphen.");
+	const project = await readProject(options.root);
+	if (project.dependencies === void 0) throw new InitError("No package.json here. Run init in the folder of your Next.js app.");
+	if (project.dependencies["next"] === void 0) throw new InitError("This is not a Next.js app (no \"next\" dependency). Create one first.");
+	if (project.appDir === void 0) throw new InitError("askdare needs the App Router, but there is no app/ or src/app/ folder.");
+	print("askdare init\n");
+	const extension = project.typescript ? "ts" : "js";
+	const existingConfig = findFile(project.root, "askdare.config");
+	const config = existingConfig ?? join(project.root, `askdare.config.${extension}`);
+	if (existingConfig) print(`  = ${shown(project, config)} (kept)`);
+	else {
+		await writeFile(config, configTemplate(botId));
+		print(`  + ${shown(project, config)}`);
+	}
+	const dir = routeDir(project, "/api/chat") ?? "";
+	const existingRoute = findFile(dir, "route");
+	if (existingRoute) print(`  = ${shown(project, existingRoute)} (kept)`);
+	else {
+		const route = join(dir, `route.${extension}`);
+		const configImport = relative(dir, config.replace(/\.[cm]?[jt]sx?$/, "")).split(sep).join("/");
+		await mkdir(dirname(route), { recursive: true });
+		await writeFile(route, routeTemplate(configImport));
+		print(`  + ${shown(project, route)}`);
+	}
+	if (!(await Promise.all([".env.local", ".env.production.local"].map((file) => gitIgnores(project.root, file)))).every(Boolean)) {
+		await appendFile(join(project.root, ".gitignore"), "\n# local secrets\n.env*.local\n");
+		print("  + .gitignore: .env*.local");
+	}
+	const { added, empty } = await addEnv(project, options.model);
+	print(added.length > 0 ? `  + .env.local: ${added.join(", ")}` : "  = .env.local (kept)");
+	const script = await addScript(project, botId);
+	const layout = findFile(project.appDir, "layout");
+	if (script === "added" && layout) print(`  + ${shown(project, layout)}: the chat script`);
+	if (script === "present" && layout) print(`  = ${shown(project, layout)} (already loads the chat)`);
+	if (await addAgentRules(project)) print("  + AGENTS.md: where AI coding agents find the askdare docs");
+	const steps = [];
+	const missing = ["@boldare/askdare", "zod"].filter((name) => !project.dependencies?.[name]);
+	if (missing.length > 0) steps.push(`Install: ${addCommand(project, missing)}`);
+	if ((majorOf(project.dependencies["zod"]) ?? 4) < 4) steps.push(`askdare needs zod 4: ${addCommand(project, ["zod@^4.1"])}`);
+	if (empty.length > 0) steps.push(`In .env.local, set ${empty.join(", ")}.`);
+	if (script === "manual") steps.push(`Load the chat on your pages, e.g. in the root layout's <body>:\n       ${SCRIPT_IMPORT}\n       ${scriptTag(botId)}`);
+	steps.push(`Start the app (${runScript(project, "dev")}), then check it: npx @boldare/askdare doctor`);
+	steps.push(`To embed the chat on another site, add that site to allowedOrigins and paste:\n       <script src="https://<your app>/api/chat/widget.js?bot=${botId}" async><\/script>`);
+	print("\nNext:");
+	steps.forEach((step, index) => {
+		print(`  ${index + 1}. ${step}`);
+	});
+}
+// src/openai/knowledge-sync.ts
+/** File types OpenAI file search indexes that make sense for a website knowledge base. */
+const SUPPORTED = /* @__PURE__ */ new Set([
+	".md",
+	".mdx",
+	".txt",
+	".pdf",
+	".docx",
+	".pptx",
+	".html",
+	".htm",
+	".json"
+]);
+/** File search only knows these spellings, so such files are uploaded under the known one. */
+const UPLOAD_EXTENSIONS = {
+	".mdx": ".md",
+	".htm": ".html"
+};
+/** Optional per-file titles and URLs, for files without front matter (PDFs, Word…). */
+const MANIFEST = "askdare.kb.json";
+const MAX_ATTRIBUTE = 512;
+function frontMatter(text) {
+	const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+	if (!match?.[1]) return {};
+	const meta = {};
+	for (const line of match[1].split(/\r?\n/)) {
+		const field = /^(title|url):\s*(.+?)\s*$/.exec(line);
+		if (field?.[1] && field[2]) meta[field[1]] = field[2].replace(/^(['"])(.*)\1$/, "$2");
+	}
+	return meta;
+}
+function checkUrl(url, path) {
+	if (url === void 0) return void 0;
+	if (!/^https?:\/\/\S+$/i.test(url) || url.length > MAX_ATTRIBUTE) throw new Error(`${path}: url must be an http(s) URL up to ${MAX_ATTRIBUTE} characters.`);
+	return url;
+}
+/** Reads every supported file under `root`, with its hash and the title/URL to cite it by. */
+async function scanDirectory(root) {
+	let manifest = {};
+	try {
+		manifest = JSON.parse(await readFile(join(root, MANIFEST), "utf8"));
+	} catch (error) {
+		if (error.code !== "ENOENT") throw new Error(`${MANIFEST} is not valid JSON.`, { cause: error });
+	}
+	const documents = [];
+	const skipped = [];
+	const walk = async (dir) => {
+		for (const entry of await readdir(dir, { withFileTypes: true })) {
+			if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+			const absolutePath = join(dir, entry.name);
+			if (entry.isDirectory()) {
+				await walk(absolutePath);
+				continue;
+			}
+			const path = relative(root, absolutePath).split(sep).join("/");
+			if (path === "askdare.kb.json") continue;
+			if (!entry.isFile() || !SUPPORTED.has(extname(entry.name).toLowerCase())) {
+				skipped.push(path);
+				continue;
+			}
+			if (path.length > MAX_ATTRIBUTE) throw new Error(`${path}: path is longer than ${MAX_ATTRIBUTE}.`);
+			const content = await readFile(absolutePath);
+			const meta = {
+				.../\.mdx?$/i.test(path) ? frontMatter(content.toString("utf8")) : {},
+				...manifest[path]
+			};
+			documents.push({
+				path,
+				absolutePath,
+				sha256: createHash("sha256").update(content).digest("hex"),
+				title: (meta.title ?? basename(path, extname(path))).slice(0, MAX_ATTRIBUTE),
+				url: checkUrl(meta.url, path)
+			});
+		}
+	};
+	await walk(root);
+	documents.sort((a, b) => a.path.localeCompare(b.path));
+	return {
+		documents,
+		skipped
+	};
+}
+/** Compares the folder with the store. Pure, so the diff is easy to test and to show as a dry run. */
+function planSync(local, remote) {
+	const managed = remote.filter((file) => file.path !== void 0 && file.sha256 !== void 0);
+	const byPath = /* @__PURE__ */ new Map();
+	for (const file of managed) byPath.set(file.path ?? "", [...byPath.get(file.path ?? "") ?? [], file]);
+	const upload = [];
+	const retag = [];
+	const remove = [];
+	let unchanged = 0;
+	for (const document of local) {
+		const copies = byPath.get(document.path) ?? [];
+		byPath.delete(document.path);
+		const keep = copies.find((copy) => copy.sha256 === document.sha256 && copy.status === "completed");
+		remove.push(...copies.filter((copy) => copy !== keep));
+		if (!keep) upload.push(document);
+		else if (keep.title !== document.title || keep.url !== document.url) retag.push({
+			document,
+			fileId: keep.fileId
+		});
+		else unchanged += 1;
+	}
+	for (const leftovers of byPath.values()) remove.push(...leftovers);
+	return {
+		upload,
+		retag,
+		remove,
+		unchanged,
+		unmanaged: remote.length - managed.length
+	};
+}
+const attributesOf = (document) => ({
+	path: document.path,
+	sha256: document.sha256,
+	title: document.title,
+	...document.url ? { url: document.url } : {}
+});
+const text = (value) => typeof value === "string" ? value : void 0;
+async function inBatches(items, size, run) {
+	for (let index = 0; index < items.length; index += size) await Promise.all(items.slice(index, index + size).map(run));
+}
+/**
+* Makes a vector store mirror a local folder. The store is the source of truth: each file carries
+* its path and content hash as attributes, so re-running is a no-op and nothing is stored locally.
+*/
+async function syncKnowledge(client, options) {
+	const log = options.log ?? (() => {});
+	const { documents, skipped } = await scanDirectory(options.root);
+	let vectorStoreId = options.vectorStoreId;
+	let created = false;
+	const remote = [];
+	if (vectorStoreId) for await (const file of client.vectorStores.files.list(vectorStoreId, { limit: 100 })) remote.push({
+		fileId: file.id,
+		status: file.status,
+		path: text(file.attributes?.["path"]),
+		sha256: text(file.attributes?.["sha256"]),
+		title: text(file.attributes?.["title"]),
+		url: text(file.attributes?.["url"])
+	});
+	const plan = planSync(documents, remote);
+	if (options.dryRun) return {
+		vectorStoreId,
+		created,
+		plan,
+		skipped,
+		failed: []
+	};
+	if (!vectorStoreId) {
+		vectorStoreId = (await client.vectorStores.create({ name: options.name ?? "askdare knowledge" })).id;
+		created = true;
+		log(`Created vector store ${vectorStoreId}.`);
+	}
+	const storeId = vectorStoreId;
+	const failed = [];
+	await inBatches(plan.upload, 4, async (document) => {
+		const extension = extname(document.path);
+		const name = `${basename(document.path, extension)}${UPLOAD_EXTENSIONS[extension.toLowerCase()] ?? extension}`;
+		let fileId;
+		try {
+			fileId = (await client.files.create({
+				file: await toFile(await readFile(document.absolutePath), name),
+				purpose: "assistants"
+			})).id;
+			const attached = await client.vectorStores.files.createAndPoll(storeId, {
+				file_id: fileId,
+				attributes: attributesOf(document)
+			});
+			if (attached.status === "completed") {
+				log(`+ ${document.path}`);
+				return;
+			}
+			failed.push({
+				path: document.path,
+				reason: attached.last_error?.message ?? attached.status
+			});
+		} catch (error) {
+			failed.push({
+				path: document.path,
+				reason: error instanceof Error ? error.message : String(error)
+			});
+		}
+		if (fileId) {
+			const id = fileId;
+			await client.vectorStores.files.delete(id, { vector_store_id: storeId }).catch(() => {});
+			await client.files.delete(id).catch(() => {});
+		}
+	});
+	await inBatches(plan.retag, 4, async ({ document, fileId }) => {
+		await client.vectorStores.files.update(fileId, {
+			vector_store_id: storeId,
+			attributes: attributesOf(document)
+		});
+		log(`~ ${document.path}`);
+	});
+	await inBatches(plan.remove, 4, async (file) => {
+		for (const remove of [() => client.vectorStores.files.delete(file.fileId, { vector_store_id: storeId }), () => client.files.delete(file.fileId)]) try {
+			await remove();
+		} catch (error) {
+			if (!(error instanceof NotFoundError)) throw error;
+		}
+		log(`- ${file.path ?? file.fileId}`);
+	});
+	return {
+		vectorStoreId: storeId,
+		created,
+		plan,
+		skipped,
+		failed
+	};
+}
+/** Entry point for the CLI, which may not import `openai` itself (ADR-0002). */
+function syncKnowledgeFolder(apiKey, options) {
+	return syncKnowledge(new OpenAI({
+		apiKey,
+		maxRetries: 3,
+		timeout: 12e4
+	}), options);
+}
+// src/cli/usage.ts
+/** A mistake in the command line: printed with the usage text. */
+var UsageError = class extends Error {};
+// src/cli/kb-sync.ts
+const KB_USAGE = `Usage: npx @boldare/askdare kb sync <folder> [options]
+
+Makes an OpenAI vector store mirror a folder of documents
+(.md, .mdx, .txt, .pdf, .docx, .pptx, .html, .htm, .json). Re-running is a no-op.
+Titles and URLs for citations come from markdown front matter or askdare.kb.json.
+
+Options:
+  --store <vs_…>     Vector store to sync (default: $KB_VECTOR_STORE_ID; created when absent)
+  --name <name>      Name for a newly created store
+  --env-file <path>  Load environment variables from this file
+                     (default: .env.local and .env in the current folder, when present)
+  --dry-run          Show what would change without changing anything
+  -h, --help         Show this help
+
+Needs OPENAI_API_KEY in the environment.
+`;
+const STORE_ID = /^vs_[A-Za-z0-9_-]+$/;
+function report(result, dryRun) {
+	const { plan } = result;
+	console.log(`${dryRun ? "Would sync" : "Synced"}: ${plan.upload.length} added, ${plan.retag.length} retagged, ${plan.remove.length} removed, ${plan.unchanged} unchanged.`);
+	if (dryRun) {
+		for (const document of plan.upload) console.log(`  + ${document.path}`);
+		for (const { document } of plan.retag) console.log(`  ~ ${document.path}`);
+		for (const file of plan.remove) console.log(`  - ${file.path ?? file.fileId}`);
+	}
+	if (result.skipped.length > 0) console.log(`Skipped (unsupported type): ${result.skipped.join(", ")}`);
+	if (plan.unmanaged > 0) console.log(`Left alone: ${plan.unmanaged} file(s) in the store not uploaded by askdare.`);
+	for (const failure of result.failed) console.error(`Failed: ${failure.path} (${failure.reason})`);
+	if (result.created) {
+		console.log("\nAdd the new store to your environment (for example .env.local):");
+		console.log(`  KB_VECTOR_STORE_ID=${result.vectorStoreId}`);
+	}
+}
+async function kbSync(args) {
+	const { values, positionals } = parseArgs({
+		args: [...args],
+		allowPositionals: true,
+		options: {
+			store: { type: "string" },
+			name: { type: "string" },
+			"env-file": { type: "string" },
+			"dry-run": {
+				type: "boolean",
+				default: false
+			},
+			help: {
+				type: "boolean",
+				short: "h",
+				default: false
+			}
+		}
+	});
+	if (values.help) {
+		console.log(KB_USAGE);
+		return 0;
+	}
+	if (positionals.length !== 1) throw new UsageError("Expected exactly one folder.");
+	const envFiles = values["env-file"] ? [values["env-file"]] : [".env.local", ".env"].filter((file) => existsSync(file));
+	for (const file of envFiles) process.loadEnvFile(file);
+	if (envFiles.length > 0) console.log(`Loaded ${envFiles.join(", ")}.`);
+	const apiKey = process.env["OPENAI_API_KEY"];
+	if (!apiKey) throw new UsageError("OPENAI_API_KEY is not set.");
+	const vectorStoreId = values.store ?? (process.env["KB_VECTOR_STORE_ID"] || void 0);
+	if (vectorStoreId !== void 0 && !STORE_ID.test(vectorStoreId)) throw new UsageError("The vector store ID must look like vs_….");
+	const dryRun = values["dry-run"];
+	const result = await syncKnowledgeFolder(apiKey, {
+		root: resolve(positionals[0] ?? "."),
+		vectorStoreId,
+		...values.name ? { name: values.name } : {},
+		dryRun,
+		log: (line) => console.log(line)
+	});
+	report(result, dryRun);
+	return result.failed.length > 0 ? 1 : 0;
+}
+// src/cli/index.ts
+const USAGE = `Usage: npx @boldare/askdare <command> [options]
+
+Commands:
+  init               Add askdare to the Next.js app in this folder: a route, a bot
+                     config, .env.local and the chat script. Never overwrites files.
+    --bot <id>         Bot ID (default: support)
+    --model <id>       OpenAI model to put in .env.local as ASKDARE_MODEL
+
+  doctor             Check the project, its environment and the running app: the
+                     OpenAI key, models, vector store, permissions and headers.
+    --url <url>        Where the app runs (default: http://localhost:3000)
+    --base-path <p>    Path of the askdare route (default: /api/chat)
+    --env-file <path>  Read CHAT_SECRET and the rest from this file
+                       (default: .env.development.local, .env.local,
+                       .env.development and .env, as next dev reads them)
+    --origin <url>     Check that this site may embed the chat (the bot's
+                       security.allowedOrigins), e.g. https://www.example.com
+
+  kb sync <folder>   Make an OpenAI vector store mirror a folder of documents.
+                     See: npx @boldare/askdare kb sync --help
+
+  -v, --version      Show the installed version
+  -h, --help         Show this help
+`;
+/** The package's own version: the CLI ships next to its package.json (dist/cli.js). */
+function version() {
+	return createRequire(import.meta.url)("../package.json").version;
+}
+async function runInit(args) {
+	const { values } = parseArgs({
+		args: [...args],
+		options: {
+			bot: {
+				type: "string",
+				default: "support"
+			},
+			model: { type: "string" },
+			help: {
+				type: "boolean",
+				short: "h",
+				default: false
+			}
+		}
+	});
+	if (values.help) {
+		console.log(USAGE);
+		return 0;
+	}
+	try {
+		await init({
+			root: process.cwd(),
+			botId: values.bot,
+			model: values.model,
+			print: (line) => console.log(line)
+		});
+	} catch (error) {
+		if (error instanceof InitError) {
+			console.error(`askdare init: ${error.message}`);
+			return 1;
+		}
+		throw error;
+	}
+	return 0;
+}
+async function runDoctor(args) {
+	const { values } = parseArgs({
+		args: [...args],
+		options: {
+			url: {
+				type: "string",
+				default: "http://localhost:3000"
+			},
+			"base-path": {
+				type: "string",
+				default: "/api/chat"
+			},
+			"env-file": { type: "string" },
+			origin: { type: "string" },
+			help: {
+				type: "boolean",
+				short: "h",
+				default: false
+			}
+		}
+	});
+	if (values.help) {
+		console.log(USAGE);
+		return 0;
+	}
+	let target;
+	try {
+		target = new URL(values.url);
+	} catch {
+		throw new UsageError("--url must be a URL such as https://your-app.example.com.");
+	}
+	if (target.protocol !== "https:" && !(target.protocol === "http:" && isLocal(values.url))) throw new UsageError("--url must use https (plain http only for localhost).");
+	if (!/^(\/[a-zA-Z0-9._~-]+)+$/.test(values["base-path"])) throw new UsageError("--base-path must look like /api/chat.");
+	let origin;
+	if (values.origin !== void 0) try {
+		origin = new URL(values.origin).origin;
+	} catch {
+		throw new UsageError("--origin must be a URL such as https://www.example.com.");
+	}
+	return await doctor({
+		root: process.cwd(),
+		url: values.url,
+		basePath: values["base-path"],
+		envFile: values["env-file"],
+		origin,
+		print: (line) => console.log(line)
+	}) > 0 ? 1 : 0;
+}
+async function main(argv) {
+	const [command, ...rest] = argv;
+	if (command === "init") return runInit(rest);
+	if (command === "doctor") return runDoctor(rest);
+	if (command === "kb" && rest[0] === "sync") return kbSync(rest.slice(1));
+	if (command === "-v" || command === "--version") {
+		console.log(version());
+		return 0;
+	}
+	if (command === void 0 || command === "-h" || command === "--help") {
+		console.log(USAGE);
+		return 0;
+	}
+	throw new UsageError(`Unknown command "${argv.join(" ")}".`);
+}
+main(process.argv.slice(2)).then((code) => {
+	process.exitCode = code;
+}, (error) => {
+	const parseError = error.code?.toString().startsWith("ERR_PARSE_ARGS");
+	if (error instanceof UsageError || parseError) {
+		const usage = process.argv[2] === "kb" ? KB_USAGE : USAGE;
+		console.error(`${error.message}\n\n${usage}`);
+	} else console.error(`askdare: ${error instanceof Error ? error.message : String(error)}`);
+	process.exitCode = 1;
+});
+export {};