kizlo 0.1.0

package/dist/cli/commands/init.js

@@ -0,0 +1,313 @@
+import { addDependencyArgs, detectImportAlias, detectPackageManager, ensureGitignored, envKeysPresent, getVersion, loadEnvFiles, mergeEnv, resolveModuleImport, runCommand, writeFileIfAbsent } from "../utils.js";
+import { CONTRACT_BARREL } from "../daemon/generate.js";
+import { printBanner } from "../banner.js";
+import { PRESETS, detectPreset, getPreset } from "../presets/index.js";
+import z from "zod/v4";
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+import fs from "node:fs";
+import { defineCommand } from "citty";
+import * as p from "@clack/prompts";
+
+//#region src/cli/commands/init.ts
+const WP_ENV_KEYS = [
+	"SITE_SECRET",
+	"WORDPRESS_URL",
+	"WORDPRESS_USERNAME",
+	"WORDPRESS_APPLICATION_PASSWORD"
+];
+function envKeys(preset) {
+	return [preset.baseUrlEnvKey, ...WP_ENV_KEYS];
+}
+function defaultDir(hasSrcDir) {
+	return hasSrcDir ? "src/lib/kizlo" : "lib/kizlo";
+}
+/** Normalizes an alias prefix to the familiar `@/` form (or empty for relative). */
+function aliasWithSlash(alias) {
+	return alias ? `${alias.replace(/\/+$/, "")}/` : "";
+}
+function kizloConfigTemplate(dir, alias) {
+	return `import { defineConfig } from "kizlo/config"
+
+export default defineConfig({
+	dir: "${dir}",${alias ? `\n\talias: "${alias}",` : ""}
+})
+`;
+}
+/** Appends the API path to the base URL so the client and route handler agree. */
+function withApiPath(baseUrl, apiPath) {
+	try {
+		const url = new URL(baseUrl);
+		const current = url.pathname.replace(/\/+$/, "");
+		if (current.endsWith(apiPath)) return url.toString().replace(/\/+$/, "");
+		url.pathname = `${current}${apiPath}`;
+		return url.toString().replace(/\/+$/, "");
+	} catch {
+		return baseUrl;
+	}
+}
+function detectAppDir(cwd, hasSrcDir) {
+	if (fs.existsSync(path.join(cwd, "src", "app"))) return "src/app";
+	if (fs.existsSync(path.join(cwd, "app"))) return "app";
+	return hasSrcDir ? "src/app" : "app";
+}
+const requiredString = z.string().trim().min(1, "Required");
+const urlString = requiredString.pipe(z.url("Must be a valid URL (e.g. https://example.com)"));
+const dirPath = requiredString.refine((value) => !value.endsWith(".ts"), "Enter a directory, not a file");
+function validate(schema) {
+	return (value) => {
+		const result = schema.safeParse(value ?? "");
+		return result.success ? void 0 : result.error.issues[0]?.message;
+	};
+}
+function orCancel(value) {
+	if (p.isCancel(value)) {
+		p.cancel("Setup cancelled.");
+		process.exit(0);
+	}
+	return value;
+}
+async function collectInteractively(ctx) {
+	const baseUrl = orCancel(await p.text({
+		message: "Public server base URL",
+		placeholder: "https://your-app.com",
+		validate: validate(urlString)
+	}));
+	const siteSecret = orCancel(await p.select({
+		message: "SITE_SECRET (signing key)",
+		initialValue: "generate",
+		options: [{
+			value: "generate",
+			label: "Generate a secure secret automatically",
+			hint: "recommended"
+		}, {
+			value: "enter",
+			label: "Enter my own"
+		}]
+	})) === "enter" ? orCancel(await p.password({
+		message: "Enter SITE_SECRET",
+		validate: validate(requiredString)
+	})) : randomBytes(32).toString("hex");
+	const wpUrl = orCancel(await p.text({
+		message: "WordPress URL",
+		placeholder: "https://wp.your-app.com",
+		validate: validate(urlString)
+	}));
+	const wpUsername = orCancel(await p.text({
+		message: "WordPress username",
+		validate: validate(requiredString)
+	}));
+	const wpPassword = orCancel(await p.password({
+		message: "WordPress application password",
+		validate: validate(requiredString)
+	}));
+	const dir = orCancel(await p.text({
+		message: "Kizlo directory",
+		initialValue: defaultDir(ctx.hasSrcDir),
+		validate: validate(dirPath)
+	}));
+	let alias = "";
+	if (ctx.preset.routeHandler) {
+		const serverDir = path.join(dir.replace(/^\.\//, "").replace(/\/+$/, ""), "server");
+		const detected = detectImportAlias(ctx.cwd, serverDir)?.prefix;
+		alias = orCancel(await p.text({
+			message: "Import alias (blank for relative imports)",
+			placeholder: "@/",
+			initialValue: detected ? `${detected}/` : ""
+		})).trim();
+	}
+	return {
+		baseUrl,
+		siteSecret,
+		wpUrl,
+		wpUsername,
+		wpPassword,
+		dir,
+		alias
+	};
+}
+/**
+* Non-interactive setup: skip prompts and use defaults. Values present in the
+* environment are used; missing ones are left empty for the user to fill in
+* later. Never fails — `--yes` always scaffolds a fillable project.
+*/
+function collectFromEnv(ctx) {
+	const dir = defaultDir(ctx.hasSrcDir);
+	return {
+		baseUrl: process.env[ctx.preset.baseUrlEnvKey]?.trim() ?? "",
+		siteSecret: process.env.SITE_SECRET?.trim() || randomBytes(32).toString("hex"),
+		wpUrl: process.env.WORDPRESS_URL?.trim() ?? "",
+		wpUsername: process.env.WORDPRESS_USERNAME?.trim() ?? "",
+		wpPassword: process.env.WORDPRESS_APPLICATION_PASSWORD?.trim() ?? "",
+		dir,
+		alias: ctx.preset.routeHandler ? aliasWithSlash(detectImportAlias(ctx.cwd, path.join(dir, "server"))?.prefix) : ""
+	};
+}
+function readPkg(pkgPath) {
+	return JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+}
+const init = defineCommand({
+	meta: {
+		name: "init",
+		description: "Set up Kizlo in the current project"
+	},
+	args: {
+		yes: {
+			type: "boolean",
+			alias: "y",
+			description: "Skip prompts and scaffold with defaults (non-interactive)",
+			default: false
+		},
+		force: {
+			type: "boolean",
+			alias: "f",
+			description: "Overwrite existing .env values and server entry without asking",
+			default: false
+		},
+		preset: {
+			type: "string",
+			description: `Force a setup preset (${PRESETS.map((preset) => preset.id).join(", ")})`
+		},
+		alias: {
+			type: "string",
+			description: "Import alias prefix for generated imports (e.g. @); blank for relative"
+		}
+	},
+	async run({ args }) {
+		const yes = Boolean(args.yes);
+		const force = Boolean(args.force);
+		const cwd = process.cwd();
+		const pkgPath = path.join(cwd, "package.json");
+		if (!yes) printBanner(getVersion());
+		p.intro("kizlo init");
+		if (!fs.existsSync(pkgPath)) {
+			p.cancel("No package.json found — run `kizlo init` inside a project.");
+			process.exit(1);
+		}
+		const pkg = readPkg(pkgPath);
+		const pm = detectPackageManager(cwd);
+		const hasKizlo = Boolean(pkg.dependencies?.kizlo) || Boolean(pkg.devDependencies?.kizlo);
+		const hasSrcDir = fs.existsSync(path.join(cwd, "src"));
+		const initCtx = {
+			cwd,
+			pkg,
+			pm,
+			hasSrcDir
+		};
+		let preset;
+		if (args.preset) {
+			const chosen = getPreset(String(args.preset));
+			if (!chosen) {
+				p.cancel(`Unknown preset "${args.preset}". Available: ${PRESETS.map((pr) => pr.id).join(", ")}`);
+				process.exit(1);
+			}
+			preset = chosen;
+		} else {
+			preset = detectPreset(initCtx);
+			if (preset.id !== "base") p.log.success(`${preset.label} detected`);
+		}
+		if (yes) loadEnvFiles(cwd);
+		const setup = yes ? collectFromEnv({
+			cwd,
+			hasSrcDir,
+			preset
+		}) : await collectInteractively({
+			cwd,
+			hasSrcDir,
+			preset
+		});
+		if (args.alias !== void 0) setup.alias = String(args.alias).trim();
+		setup.alias = aliasWithSlash(setup.alias);
+		if (!hasKizlo) {
+			const s = p.spinner();
+			s.start(`Installing kizlo with ${pm}`);
+			const ok = runCommand(addDependencyArgs(pm, "kizlo"), cwd, "ignore");
+			s.stop(ok ? "Installed kizlo" : "Could not install kizlo automatically");
+			if (!ok) p.log.warn(`Install it yourself: ${addDependencyArgs(pm, "kizlo").join(" ")}`);
+		}
+		if (preset.apiPath && setup.baseUrl) setup.baseUrl = withApiPath(setup.baseUrl, preset.apiPath);
+		const keys = envKeys(preset);
+		const envValues = {
+			[preset.baseUrlEnvKey]: setup.baseUrl,
+			SITE_SECRET: setup.siteSecret,
+			WORDPRESS_URL: setup.wpUrl,
+			WORDPRESS_USERNAME: setup.wpUsername,
+			WORDPRESS_APPLICATION_PASSWORD: setup.wpPassword
+		};
+		const envPath = path.join(cwd, ".env");
+		const envExisted = fs.existsSync(envPath);
+		const existingEnv = envExisted ? fs.readFileSync(envPath, "utf8") : "";
+		const conflicts = envKeysPresent(existingEnv, keys);
+		let overwriteKeys = new Set(keys);
+		if (conflicts.length && !force) if (yes) {
+			overwriteKeys = /* @__PURE__ */ new Set();
+			p.log.info("Keeping existing .env values (pass --force to overwrite)");
+		} else {
+			p.log.warn("Some environment variables already exist in .env");
+			if (!orCancel(await p.confirm({
+				message: "Overwrite their existing values?",
+				initialValue: true
+			}))) overwriteKeys = /* @__PURE__ */ new Set();
+		}
+		const merge = mergeEnv(existingEnv, envValues, overwriteKeys);
+		fs.writeFileSync(envPath, merge.content);
+		const exampleCreated = writeFileIfAbsent(path.join(cwd, ".env.example"), `${keys.map((key) => `${key}=`).join("\n")}\n`);
+		const dirRel = setup.dir.replace(/^\.\//, "").replace(/\/+$/, "");
+		const configCreated = writeFileIfAbsent(path.join(cwd, "kizlo.config.ts"), kizloConfigTemplate(dirRel, setup.alias));
+		const serverDirRel = path.join(dirRel, "server");
+		const serverEntryRel = path.join(serverDirRel, "index.ts");
+		const serverPath = path.join(cwd, serverEntryRel);
+		const serverExisted = fs.existsSync(serverPath);
+		let wroteServer = !serverExisted || force;
+		if (serverExisted && !force && !yes) {
+			p.log.warn(`A Kizlo server instance already exists at ${serverEntryRel}`);
+			wroteServer = orCancel(await p.confirm({
+				message: "Overwrite it?",
+				initialValue: true
+			}));
+		}
+		if (wroteServer) {
+			fs.mkdirSync(path.dirname(serverPath), { recursive: true });
+			fs.writeFileSync(serverPath, preset.serverEntry());
+		}
+		const generatedDirRel = path.join(serverDirRel, "generated");
+		writeFileIfAbsent(path.join(cwd, generatedDirRel, "contract.json"), "{}\n");
+		writeFileIfAbsent(path.join(cwd, generatedDirRel, "index.ts"), CONTRACT_BARREL);
+		const scaffold = {
+			serverDirName: path.basename(serverDirRel),
+			appDir: detectAppDir(cwd, hasSrcDir),
+			serverImport: (fromDir) => resolveModuleImport(cwd, serverDirRel, fromDir, setup.alias)
+		};
+		const clientRel = path.join(dirRel, "client.ts");
+		const clientCreated = writeFileIfAbsent(path.join(cwd, clientRel), preset.clientEntry(scaffold));
+		let routeRel;
+		let routeCreated = false;
+		if (preset.routeHandler) {
+			const route = preset.routeHandler(scaffold);
+			routeRel = route.path;
+			routeCreated = writeFileIfAbsent(path.join(cwd, route.path), route.contents);
+		}
+		const gitignore = ensureGitignored(cwd, ".env");
+		if (!envExisted) p.log.success("Created .env");
+		else if (merge.updated.length || merge.added.length) p.log.success("Updated .env");
+		else p.log.info("Left .env unchanged");
+		p.log.success(exampleCreated ? "Created .env.example" : "Skipped .env.example (exists)");
+		p.log.success(configCreated ? "Created kizlo.config.ts" : "Skipped kizlo.config.ts (exists)");
+		if (wroteServer) p.log.success(`${serverExisted ? "Overwrote" : "Created"} Kizlo server instance (${serverEntryRel})`);
+		else p.log.info(`Kept existing Kizlo server instance (${serverEntryRel})${yes ? " — pass --force to overwrite" : ""}`);
+		p.log.success(clientCreated ? `Created browser client (${clientRel})` : "Skipped browser client (exists)");
+		if (routeRel) p.log.success(routeCreated ? `Created API route (${routeRel})` : "Skipped API route (exists)");
+		if (gitignore !== "present") p.log.success(`${gitignore === "created" ? "Created" : "Updated"} .gitignore (ignoring .env)`);
+		p.note([
+			`Watch your extensions and regenerate the contract during development:`,
+			`  npx kizlo watch`,
+			``,
+			`Generate the contract once for production builds:`,
+			`  npx kizlo generate`
+		].join("\n"), "Next steps");
+		p.outro("Kizlo is ready 🎉");
+	}
+});
+
+//#endregion
+export { init };

package/dist/cli/commands/test.js

@@ -0,0 +1,68 @@
+import { isSeeded } from "../wp/utils.js";
+import { composeDown, composeUp } from "../wp/docker.js";
+import { withSpinner } from "../utils.js";
+import { log } from "../daemon/logger.js";
+import { resolveTestConfig } from "../daemon/config.js";
+import { runSeeds } from "../wp/setup.js";
+import { spawn } from "node:child_process";
+import { defineCommand } from "citty";
+
+//#region src/cli/commands/test.ts
+/** `<pm> test` runs the project's own test script (bun needs `run` to skip its built-in runner). */
+function testCommand(pm) {
+	return pm === "bun" ? [
+		"bun",
+		"run",
+		"test"
+	] : [pm, "test"];
+}
+/** Spawn the test command, inheriting stdio, and resolve with its exit code. */
+function spawnTest(command, pm) {
+	const argv = command ? [command] : testCommand(pm);
+	const child = spawn(argv[0], argv.slice(1), {
+		stdio: "inherit",
+		shell: command !== void 0 || process.platform === "win32"
+	});
+	return new Promise((resolve, reject) => {
+		child.on("error", reject);
+		child.on("close", (code) => resolve(code ?? 0));
+	});
+}
+const test = defineCommand({
+	meta: {
+		name: "test",
+		description: "Boot the WordPress test stack (if needed), seed it, and run your tests against it"
+	},
+	args: {
+		teardown: {
+			type: "boolean",
+			description: "Tear down the test stack after tests finish (default: leave it running for fast reruns)"
+		},
+		reset: {
+			type: "boolean",
+			description: "Wipe the database and reseed before running"
+		}
+	},
+	async run({ args }) {
+		const cfg = await resolveTestConfig(process.cwd());
+		process.env.WP_PORT = String(cfg.port);
+		if (args.reset) await withSpinner("Wiping WordPress database", () => composeDown({ volumes: true }), "Database wiped");
+		await withSpinner("Starting WordPress test stack", composeUp, "WordPress test stack ready");
+		if (!await isSeeded()) await withSpinner("Seeding WordPress", () => runSeeds({
+			port: cfg.port,
+			fixtures: cfg.fixtures
+		}), "WordPress seeded");
+		log.info(cfg.command ? `Running: ${cfg.command}` : `Running: ${testCommand(cfg.packageManager).join(" ")}`);
+		let code = 1;
+		try {
+			code = await spawnTest(cfg.command, cfg.packageManager);
+		} finally {
+			if (args.teardown) await withSpinner("Tearing down WordPress test stack", () => composeDown(), "WordPress test stack stopped");
+			else log.info("Stack left running for fast reruns — `kizlo wp stop` to stop it, or rerun with --teardown.");
+		}
+		process.exit(code);
+	}
+});
+
+//#endregion
+export { test };

package/dist/cli/commands/watch.js

@@ -0,0 +1,53 @@
+import { getVersion } from "../utils.js";
+import { log } from "../daemon/logger.js";
+import { resolveConfig } from "../daemon/config.js";
+import { generateOnce } from "../daemon/generate.js";
+import { printBanner } from "../banner.js";
+import { acquire, isLocked, lockPath, release } from "../daemon/lock.js";
+import { watch as watch$1 } from "../daemon/watch.js";
+import { defineCommand } from "citty";
+
+//#region src/cli/commands/watch.ts
+const args = { dir: {
+	type: "string",
+	description: "Override the Kizlo directory (defaults to kizlo.config.ts)"
+} };
+async function run({ args: args$1 }) {
+	const cwd = process.cwd();
+	const lock = lockPath(cwd);
+	if (isLocked(lock)) {
+		log.info("Watcher already running — nothing to do.");
+		return;
+	}
+	printBanner(getVersion());
+	const cfg = await resolveConfig(cwd, { dir: args$1.dir });
+	acquire(lock);
+	const cleanup = () => release(lock);
+	process.on("exit", cleanup);
+	for (const signal of [
+		"SIGINT",
+		"SIGTERM",
+		"SIGHUP"
+	]) process.on(signal, () => {
+		cleanup();
+		process.exit(0);
+	});
+	try {
+		if (await generateOnce(cfg)) log.success("Contract generated");
+		else log.warn(`No Kizlo server found in ${cfg.serverEntry}`);
+	} catch (error) {
+		log.error("Failed to generate the Kizlo contract:", error);
+	}
+	await watch$1(cfg);
+}
+const watch = defineCommand({
+	meta: {
+		name: "watch",
+		description: "Watch your extensions and regenerate the Kizlo contract"
+	},
+	args,
+	run
+});
+
+//#endregion
+export { watch };

package/dist/cli/commands/wp.js

@@ -0,0 +1,66 @@
+import { isSeeded } from "../wp/utils.js";
+import { composeDown, composeStop, composeUp } from "../wp/docker.js";
+import { withSpinner } from "../utils.js";
+import { log } from "../daemon/logger.js";
+import { resolveTestConfig } from "../daemon/config.js";
+import { runSeeds } from "../wp/setup.js";
+import { defineCommand } from "citty";
+
+//#region src/cli/commands/wp.ts
+/** Boot the stack and seed it once (idempotent — skips seeding if already seeded). */
+async function bringUp(cwd) {
+	const cfg = await resolveTestConfig(cwd);
+	process.env.WP_PORT = String(cfg.port);
+	await withSpinner("Starting WordPress test stack", composeUp, "WordPress test stack ready");
+	if (await isSeeded()) {
+		log.info("Stack already seeded — skipping seed.");
+		return;
+	}
+	await withSpinner("Seeding WordPress", () => runSeeds({
+		port: cfg.port,
+		fixtures: cfg.fixtures
+	}), "WordPress seeded");
+	log.success(`Stack ready on http://localhost:${cfg.port} — credentials at ${cfg.credentialsPath}`);
+}
+const up = defineCommand({
+	meta: {
+		name: "up",
+		description: "Start the WordPress test stack and seed it if needed"
+	},
+	async run() {
+		await bringUp(process.cwd());
+	}
+});
+const reset = defineCommand({
+	meta: {
+		name: "reset",
+		description: "Wipe the database and reseed a fresh WordPress test stack"
+	},
+	async run() {
+		await withSpinner("Wiping WordPress database", () => composeDown({ volumes: true }), "Database wiped");
+		await bringUp(process.cwd());
+	}
+});
+const stop = defineCommand({
+	meta: {
+		name: "stop",
+		description: "Stop the WordPress test stack, keeping the database volume"
+	},
+	async run() {
+		await withSpinner("Stopping WordPress test stack", composeStop, "Stack stopped (volumes kept)");
+	}
+});
+const wp = defineCommand({
+	meta: {
+		name: "wp",
+		description: "Manage the WordPress test stack (advanced: up | reset | stop)"
+	},
+	subCommands: {
+		up,
+		reset,
+		stop
+	}
+});
+
+//#endregion
+export { wp };

package/dist/cli/daemon/config.js

@@ -0,0 +1,87 @@
+import { credentialsPath, findConfigDir } from "../wp/utils.js";
+import { detectPackageManager } from "../utils.js";
+import { log } from "./logger.js";
+import z from "zod/v4";
+import path from "node:path";
+import fs from "node:fs";
+import { createJiti } from "jiti";
+
+//#region src/cli/daemon/config.ts
+const fixtureSchema = z.custom((value) => typeof value === "object" && value !== null && typeof value.name === "string", { message: "must be a fixture object with a string `name` (use defineFixture)" });
+/** Runtime shape of `kizlo.config.*` — mirrors {@link KizloGlobalConfig}. */
+const configSchema = z.object({
+	dir: z.string().optional(),
+	alias: z.string().optional(),
+	test: z.object({
+		port: z.number().int().positive().optional(),
+		fixtures: z.array(fixtureSchema).optional(),
+		packageManager: z.enum([
+			"npm",
+			"pnpm",
+			"yarn",
+			"bun"
+		]).optional(),
+		command: z.string().optional()
+	}).optional()
+});
+const CONFIG_FILES = [
+	"kizlo.config.ts",
+	"kizlo.config.js",
+	"kizlo.config.mjs"
+];
+function defaultDir(cwd) {
+	return fs.existsSync(path.join(cwd, "src")) ? "src/lib/kizlo" : "lib/kizlo";
+}
+async function loadConfigFile(cwd) {
+	const file = CONFIG_FILES.map((name) => path.join(cwd, name)).find((p) => fs.existsSync(p));
+	if (!file) return void 0;
+	let raw;
+	try {
+		const mod = await createJiti(cwd, { moduleCache: false }).import(file);
+		raw = mod.default ?? mod;
+	} catch (error) {
+		log.error(`Could not load ${path.basename(file)}:`, error);
+		process.exit(1);
+	}
+	const result = configSchema.safeParse(raw);
+	if (!result.success) {
+		log.error(`Invalid ${path.basename(file)}:\n${z.prettifyError(result.error)}`);
+		process.exit(1);
+	}
+	return result.data;
+}
+async function resolveConfig(cwd, flags) {
+	const fileConfig = await loadConfigFile(cwd);
+	const dir = (flags?.dir ?? fileConfig?.dir ?? defaultDir(cwd)).replace(/^\.\//, "").replace(/\/+$/, "");
+	const serverDir = path.join(dir, "server");
+	const generatedDir = path.join(serverDir, "generated");
+	return {
+		cwd,
+		dir,
+		serverDir,
+		serverEntry: path.join(serverDir, "index.ts"),
+		generatedDir,
+		contractPath: path.join(generatedDir, "contract.json"),
+		barrelPath: path.join(generatedDir, "index.ts")
+	};
+}
+/**
+* Resolve the `test` block from `kizlo.config.*` into concrete values for the
+* `wp`/`test` commands, applying defaults (port 8080, auto-detected package
+* manager) and anchoring the credentials artifact to the config directory.
+*/
+async function resolveTestConfig(cwd) {
+	const configDir = findConfigDir(cwd);
+	const test = (await loadConfigFile(configDir))?.test ?? {};
+	return {
+		configDir,
+		command: test.command,
+		port: test.port ?? 8080,
+		fixtures: test.fixtures ?? [],
+		credentialsPath: credentialsPath(cwd),
+		packageManager: test.packageManager ?? detectPackageManager(configDir)
+	};
+}
+
+//#endregion
+export { resolveConfig, resolveTestConfig };

package/dist/cli/daemon/generate.js

@@ -0,0 +1,40 @@
+import { generateContract } from "../../shared/contract.js";
+import { loadEnvFiles } from "../utils.js";
+import path from "node:path";
+import fs from "node:fs";
+import { createJiti } from "jiti";
+
+//#region src/cli/daemon/generate.ts
+/** The generated contract barrel — also written as a stub by `kizlo init`. */
+const CONTRACT_BARREL = [
+	`import type { router } from ".."`,
+	`import contractJson from "./contract.json"`,
+	``,
+	`export const contract = contractJson as unknown as typeof router`,
+	``
+].join("\n");
+/** Write atomically: a reader never observes a half-written file. */
+function atomicWrite(file, data) {
+	const tmp = `${file}.${process.pid}.tmp`;
+	fs.writeFileSync(tmp, data);
+	fs.renameSync(tmp, file);
+}
+/**
+* Loads the Kizlo server, builds its contract, and writes `contract.json` and
+* the generated barrel. Returns false when the entry has no Kizlo server.
+*/
+async function generateOnce(cfg) {
+	loadEnvFiles(cfg.cwd);
+	const jiti = createJiti(cfg.cwd, { moduleCache: false });
+	const entry = path.resolve(cfg.cwd, cfg.serverEntry);
+	const { router } = await jiti.import(entry);
+	if (!router) return false;
+	const contract = JSON.stringify(await generateContract(router));
+	fs.mkdirSync(path.resolve(cfg.cwd, cfg.generatedDir), { recursive: true });
+	atomicWrite(path.resolve(cfg.cwd, cfg.contractPath), contract);
+	atomicWrite(path.resolve(cfg.cwd, cfg.barrelPath), CONTRACT_BARREL);
+	return true;
+}
+
+//#endregion
+export { CONTRACT_BARREL, generateOnce };

package/dist/cli/daemon/lock.js

@@ -0,0 +1,31 @@
+import path from "node:path";
+import fs from "node:fs";
+
+//#region src/cli/daemon/lock.ts
+function lockPath(cwd) {
+	return path.join(cwd, "node_modules/.cache/kizlo/dev.lock");
+}
+/** True when a live daemon already owns the lock. Stale locks are ignored. */
+function isLocked(file) {
+	if (!fs.existsSync(file)) return false;
+	const pid = Number(fs.readFileSync(file, "utf8").trim());
+	if (!pid) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function acquire(file) {
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	fs.writeFileSync(file, String(process.pid));
+}
+function release(file) {
+	try {
+		fs.rmSync(file, { force: true });
+	} catch {}
+}
+
+//#endregion
+export { acquire, isLocked, lockPath, release };

package/dist/cli/daemon/logger.js

@@ -0,0 +1,8 @@
+import { consola } from "consola";
+
+//#region src/cli/daemon/logger.ts
+/** Tagged logger for the daemon — every line is prefixed with `kizlo`. */
+const log = consola.withTag("kizlo");
+
+//#endregion
+export { log };