kizlo 0.1.0

package/dist/cli/daemon/watch.js

@@ -0,0 +1,37 @@
+import { log } from "./logger.js";
+import { generateOnce } from "./generate.js";
+import path from "node:path";
+import { FSWatcher } from "chokidar";
+
+//#region src/cli/daemon/watch.ts
+function debounce(fn, delay) {
+	let timer;
+	return ((...args) => {
+		clearTimeout(timer);
+		timer = setTimeout(() => void fn(...args), delay);
+	});
+}
+async function regenerate(cfg) {
+	try {
+		if (await generateOnce(cfg)) log.success("Contract updated");
+		else log.warn(`No Kizlo server found in ${cfg.serverEntry}`);
+	} catch (error) {
+		log.error("Failed to update the Kizlo contract:", error);
+	}
+}
+/** Watches the server directory and regenerates the contract on change. */
+async function watch(cfg) {
+	const watcher = new FSWatcher({
+		persistent: true,
+		ignoreInitial: true,
+		ignored: path.resolve(cfg.cwd, cfg.generatedDir)
+	});
+	const onChange = debounce(() => regenerate(cfg), 300);
+	watcher.add(path.resolve(cfg.cwd, cfg.serverDir));
+	watcher.on("ready", () => log.start("Watching for changes..."));
+	watcher.on("all", () => void onChange());
+	return watcher;
+}
+
+//#endregion
+export { watch };

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/cli/index.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { getVersion } from "./utils.js";
+import { defineCommand, runMain } from "citty";
+
+//#region src/cli/index.ts
+runMain(defineCommand({
+	meta: {
+		name: "kizlo",
+		version: getVersion(),
+		description: "Kizlo CLI — headless WordPress toolkit"
+	},
+	subCommands: {
+		init: () => import("./commands/init.js").then((m) => m.init),
+		watch: () => import("./commands/watch.js").then((m) => m.watch),
+		generate: () => import("./commands/generate.js").then((m) => m.generate),
+		wp: () => import("./commands/wp.js").then((m) => m.wp),
+		test: () => import("./commands/test.js").then((m) => m.test)
+	}
+}));
+
+//#endregion
+export {  };

package/dist/cli/presets/base.js

@@ -0,0 +1,23 @@
+//#region src/cli/presets/base.ts
+const base = {
+	id: "base",
+	label: "Generic (no framework detected)",
+	detect: () => 1,
+	baseUrlEnvKey: "SERVER_BASE_URL",
+	serverEntry() {
+		return `import { createKizlo } from "kizlo"
+
+export const { router, client, context, handler } = createKizlo()
+`;
+	},
+	clientEntry(ctx) {
+		return `import { createKizloClient } from "kizlo"
+import { contract } from "./${ctx.serverDirName}/generated"
+
+export const client = createKizloClient(contract)
+`;
+	}
+};
+
+//#endregion
+export { base };

package/dist/cli/presets/index.js

@@ -0,0 +1,16 @@
+import { base } from "./base.js";
+import { nextjs } from "./nextjs.js";
+
+//#region src/cli/presets/index.ts
+/** Framework presets, in declaration order. `base` always matches last. */
+const PRESETS = [nextjs, base];
+function getPreset(id) {
+	return PRESETS.find((preset) => preset.id === id);
+}
+/** Highest-scoring preset for the project; falls back to `base`. */
+function detectPreset(ctx) {
+	return PRESETS.reduce((best, preset) => preset.detect(ctx) > best.detect(ctx) ? preset : best);
+}
+
+//#endregion
+export { PRESETS, detectPreset, getPreset };

package/dist/cli/presets/nextjs.js

@@ -0,0 +1,39 @@
+//#region src/cli/presets/nextjs.ts
+const nextjs = {
+	id: "nextjs",
+	label: "Next.js",
+	detect(ctx) {
+		return {
+			...ctx.pkg.dependencies,
+			...ctx.pkg.devDependencies
+		}.next ? 100 : 0;
+	},
+	baseUrlEnvKey: "NEXT_PUBLIC_SERVER_BASE_URL",
+	apiPath: "/api/kizlo",
+	serverEntry() {
+		return `import { createKizlo } from "kizlo/nextjs/server"
+
+export const { router, client, context, handler } = createKizlo()
+`;
+	},
+	clientEntry(ctx) {
+		return `import { createKizloClient } from "kizlo/nextjs"
+import { contract } from "./${ctx.serverDirName}/generated"
+
+export const client = createKizloClient(contract)
+`;
+	},
+	routeHandler(ctx) {
+		const dir = `${ctx.appDir}/api/kizlo/[[...rest]]`;
+		return {
+			path: `${dir}/route.ts`,
+			contents: `import { handler } from "${ctx.serverImport(dir)}"
+
+export { handler as GET, handler as POST, handler as PUT, handler as PATCH, handler as DELETE, handler as OPTIONS }
+`
+		};
+	}
+};
+
+//#endregion
+export { nextjs };

package/dist/cli/utils.js

@@ -0,0 +1,182 @@
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import fs from "node:fs";
+import * as p from "@clack/prompts";
+
+//#region src/cli/utils.ts
+function stripJsonComments(source) {
+	return source.replace(/\\"|"(?:\\"|[^"])*"|(\/\/.*|\/\*[\s\S]*?\*\/)/g, (match, comment) => comment ? "" : match);
+}
+function readTsconfigPaths(cwd) {
+	const file = path.join(cwd, "tsconfig.json");
+	if (!fs.existsSync(file)) return void 0;
+	const raw = fs.readFileSync(file, "utf8");
+	let json;
+	try {
+		json = JSON.parse(raw);
+	} catch {
+		try {
+			json = JSON.parse(stripJsonComments(raw));
+		} catch {
+			return;
+		}
+	}
+	return json.compilerOptions?.paths;
+}
+function relativeImport(targetRel, fromDirRel) {
+	const rel = path.relative(fromDirRel, targetRel).split(path.sep).join("/");
+	return rel.startsWith(".") ? rel : `./${rel}`;
+}
+/**
+* Detects an import alias from tsconfig `paths` that covers `targetRel`, returning
+* `{ prefix, importPath }`. The prefix is what `init` persists to kizlo.config;
+* the import path is the full specifier. Returns undefined when no alias matches.
+*/
+function detectImportAlias(cwd, targetRel) {
+	const target = targetRel.split(path.sep).join("/").replace(/\/+$/, "");
+	for (const [alias, mappings] of Object.entries(readTsconfigPaths(cwd) ?? {})) {
+		if (!alias.endsWith("/*")) continue;
+		const prefix = alias.slice(0, -2);
+		for (const mapping of mappings ?? []) {
+			if (!mapping.endsWith("/*")) continue;
+			const base = mapping.slice(0, -2).replace(/^\.\//, "").replace(/^\.$/, "").replace(/\/+$/, "");
+			const baseSlash = base ? `${base}/` : "";
+			if (target === base || target.startsWith(baseSlash)) return {
+				prefix,
+				importPath: `${prefix}/${target.slice(baseSlash.length)}`
+			};
+		}
+	}
+}
+/**
+* Builds an import specifier for `targetRel` from `fromDirRel`. With an explicit
+* `alias` prefix (from kizlo.config), builds `<alias>/<target>`; an empty alias
+* forces a relative import. Without one, detects from tsconfig, else relative.
+*/
+function resolveModuleImport(cwd, targetRel, fromDirRel, alias) {
+	const target = targetRel.split(path.sep).join("/").replace(/\/+$/, "");
+	if (alias !== void 0) {
+		if (alias === "") return relativeImport(targetRel, fromDirRel);
+		const prefix = alias.replace(/\/+$/, "");
+		const base = detectImportAlias(cwd, targetRel);
+		return base && base.prefix === prefix ? base.importPath : `${prefix}/${target.replace(/^src\//, "")}`;
+	}
+	return detectImportAlias(cwd, targetRel)?.importPath ?? relativeImport(targetRel, fromDirRel);
+}
+/**
+* Loads the project's `.env` files into `process.env`. The single place env
+* values come from — shared by `init --yes` and the `kizlo watch`/`generate`
+* daemon so they always read the same source.
+*/
+function loadEnvFiles(cwd) {
+	for (const name of [".env", ".env.local"]) {
+		const file = path.join(cwd, name);
+		if (fs.existsSync(file)) process.loadEnvFile(file);
+	}
+}
+function getVersion() {
+	const here = path.dirname(fileURLToPath(import.meta.url));
+	const pkgPath = path.resolve(here, "../../package.json");
+	return JSON.parse(fs.readFileSync(pkgPath, "utf8")).version;
+}
+function detectPackageManager(cwd) {
+	if (fs.existsSync(path.join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+	if (fs.existsSync(path.join(cwd, "yarn.lock"))) return "yarn";
+	if (fs.existsSync(path.join(cwd, "bun.lockb")) || fs.existsSync(path.join(cwd, "bun.lock"))) return "bun";
+	return "npm";
+}
+function addDependencyArgs(pm, pkg) {
+	if (pm === "npm") return [
+		"npm",
+		"install",
+		pkg
+	];
+	return [
+		pm,
+		"add",
+		pkg
+	];
+}
+function runCommand(args, cwd, stdio = "inherit") {
+	const [command, ...rest] = args;
+	if (!command) return false;
+	return spawnSync(command, rest, {
+		cwd,
+		stdio,
+		shell: process.platform === "win32"
+	}).status === 0;
+}
+function writeFileIfAbsent(filePath, contents) {
+	if (fs.existsSync(filePath)) return false;
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	fs.writeFileSync(filePath, contents);
+	return true;
+}
+function envKeysPresent(contents, keys) {
+	return keys.filter((key) => new RegExp(`^\\s*${key}\\s*=`, "m").test(contents));
+}
+/**
+* Merges `values` into an existing .env body: other variables, comments and
+* blank lines are preserved. A managed key is rewritten only when listed in
+* `overwriteKeys`; otherwise its existing line is kept. Missing keys are appended.
+*/
+function mergeEnv(existing, values, overwriteKeys) {
+	const body = existing.replace(/\s*$/, "");
+	const lines = body.length ? body.split(/\r?\n/) : [];
+	const added = [];
+	const updated = [];
+	const kept = [];
+	const present = /* @__PURE__ */ new Set();
+	const next = lines.map((line) => {
+		const key = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=/)?.[1];
+		if (key && key in values) {
+			present.add(key);
+			if (overwriteKeys.has(key)) {
+				updated.push(key);
+				return `${key}=${values[key]}`;
+			}
+			kept.push(key);
+		}
+		return line;
+	});
+	for (const [key, value] of Object.entries(values)) if (!present.has(key)) {
+		added.push(key);
+		next.push(`${key}=${value}`);
+	}
+	return {
+		content: `${next.join("\n")}\n`,
+		added,
+		updated,
+		kept
+	};
+}
+function ensureGitignored(cwd, entry) {
+	const gitignorePath = path.join(cwd, ".gitignore");
+	const existed = fs.existsSync(gitignorePath);
+	const contents = existed ? fs.readFileSync(gitignorePath, "utf8") : "";
+	if (contents.split(/\r?\n/).some((line) => line.trim() === entry)) return "present";
+	const prefix = contents.length && !contents.endsWith("\n") ? `${contents}\n` : contents;
+	fs.writeFileSync(gitignorePath, `${prefix}${entry}\n`);
+	return existed ? "added" : "created";
+}
+/**
+* Run a slow async step behind a clack spinner. Shows `message` while `fn` runs,
+* stops with `done` (or `message`) on success, and stops with an error mark then
+* rethrows on failure so callers keep their existing try/finally control flow.
+*/
+async function withSpinner(message, fn, done) {
+	const s = p.spinner();
+	s.start(message);
+	try {
+		const result = await fn();
+		s.stop(done ?? message);
+		return result;
+	} catch (error) {
+		s.error(`${message} failed`);
+		throw error;
+	}
+}
+
+//#endregion
+export { addDependencyArgs, detectImportAlias, detectPackageManager, ensureGitignored, envKeysPresent, getVersion, loadEnvFiles, mergeEnv, resolveModuleImport, runCommand, withSpinner, writeFileIfAbsent };

package/dist/cli/wp/bootstrap.js

@@ -0,0 +1,114 @@
+import { ensurePlugin, resolvePluginSource } from "./utils.js";
+import { DEFAULT_PLUGINS, DEFAULT_PORT, SEED_MARKER_OPTION, SEED_VERSION, TEST_ADMIN, TEST_USER } from "./constants.js";
+import { compose, composeUp, wpCli } from "./docker.js";
+
+//#region src/cli/wp/bootstrap.ts
+async function seedUsers() {
+	const existing = await wpCli([
+		"user",
+		"get",
+		TEST_USER.username,
+		"--field=ID"
+	]).catch(() => "");
+	const id = existing ? existing : await wpCli([
+		"user",
+		"create",
+		TEST_USER.username,
+		TEST_USER.email,
+		`--role=${TEST_USER.role}`,
+		`--user_pass=${TEST_USER.password}`,
+		"--porcelain"
+	]);
+	if (!id) throw new Error("seed/users.json must include a user with username \"user\"");
+	return Number(id);
+}
+async function createAdminAppPassword() {
+	await compose([
+		"exec",
+		"-T",
+		"wp-cli",
+		"wp",
+		"user",
+		"application-password",
+		"delete",
+		TEST_ADMIN.username,
+		"--all"
+	]);
+	return wpCli([
+		"user",
+		"application-password",
+		"create",
+		TEST_ADMIN.username,
+		"harness",
+		"--porcelain"
+	]);
+}
+/**
+* Phase 1 — boot WordPress via docker + wp-cli: core install, plugins (kizlo core +
+* each fixture's plugin), the base users, the admin app password, and the seed
+* marker. Content (posts/menu) is left to fixtures. Returns everything needed to
+* construct the REST client in Phase 2.
+*/
+async function bootstrapWp(config) {
+	const port = config.port ?? DEFAULT_PORT;
+	const url = `http://localhost:${port}`;
+	process.env.WP_PORT = String(port);
+	await composeUp();
+	if ((await compose([
+		"exec",
+		"-T",
+		"wp-cli",
+		"wp",
+		"core",
+		"is-installed"
+	])).code !== 0) await wpCli([
+		"core",
+		"install",
+		`--url=${url}`,
+		"--title=Kizlo Test",
+		`--admin_user=${TEST_ADMIN.username}`,
+		`--admin_password=${TEST_ADMIN.password}`,
+		`--admin_email=${TEST_ADMIN.email}`,
+		"--skip-email"
+	]);
+	await wpCli([
+		"rewrite",
+		"structure",
+		"/%postname%/",
+		"--hard"
+	]);
+	for (const plugin of [...DEFAULT_PLUGINS, ...config.fixtures?.flatMap((a) => a.plugins ?? []) ?? []]) await ensurePlugin(...resolvePluginSource(plugin));
+	const adminId = Number(await wpCli([
+		"user",
+		"get",
+		TEST_ADMIN.username,
+		"--field=ID"
+	]));
+	const userId = await seedUsers();
+	const appPassword = await createAdminAppPassword();
+	await wpCli([
+		"option",
+		"update",
+		SEED_MARKER_OPTION,
+		SEED_VERSION,
+		"--autoload=no"
+	]);
+	return {
+		url,
+		users: {
+			admin: {
+				id: adminId,
+				...TEST_ADMIN,
+				applicationPassword: appPassword
+			},
+			user: {
+				id: userId,
+				...TEST_USER
+			}
+		},
+		fixtures: {}
+	};
+}
+
+//#endregion
+export { bootstrapWp };

package/dist/cli/wp/compose/docker-compose.yml

@@ -0,0 +1,73 @@
+name: kizlo-wp-test
+
+services:
+  mysql:
+    image: mysql:8
+    environment:
+      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-rootpass}
+      MYSQL_DATABASE: ${MYSQL_DATABASE:-wordpress}
+      MYSQL_USER: ${MYSQL_USER:-wordpress}
+      MYSQL_PASSWORD: ${MYSQL_PASSWORD:-wppass}
+    volumes:
+      - mysql_data:/var/lib/mysql
+    healthcheck:
+      test:
+        - CMD
+        - mysqladmin
+        - ping
+        - -h
+        - localhost
+        - -uroot
+        - -p${MYSQL_ROOT_PASSWORD:-rootpass}
+      interval: 5s
+      timeout: 5s
+      retries: 30
+      start_period: 20s
+
+  wordpress:
+    image: wordpress:latest
+    depends_on:
+      mysql:
+        condition: service_healthy
+    ports:
+      - "${WP_PORT:-8080}:80"
+    environment:
+      WORDPRESS_DB_HOST: mysql:3306
+      WORDPRESS_DB_NAME: ${MYSQL_DATABASE:-wordpress}
+      WORDPRESS_DB_USER: ${MYSQL_USER:-wordpress}
+      WORDPRESS_DB_PASSWORD: ${MYSQL_PASSWORD:-wppass}
+      WORDPRESS_CONFIG_EXTRA: |
+        define('WP_ENVIRONMENT_TYPE', 'local');
+    volumes:
+      - wp_data:/var/www/html
+    healthcheck:
+      # wp-login.php always returns 200 unauthenticated; /wp-json can be gated to 401
+      # by plugins, so it's not a reliable liveness probe.
+      test: ["CMD-SHELL", "curl -sf http://localhost/wp-login.php > /dev/null || exit 1"]
+      interval: 5s
+      timeout: 5s
+      retries: 60
+      start_period: 30s
+
+  wp-cli:
+    image: wordpress:cli
+    depends_on:
+      wordpress:
+        condition: service_healthy
+    user: "33:33"
+    volumes:
+      - wp_data:/var/www/html
+    environment:
+      WORDPRESS_DB_HOST: mysql:3306
+      WORDPRESS_DB_NAME: ${MYSQL_DATABASE:-wordpress}
+      WORDPRESS_DB_USER: ${MYSQL_USER:-wordpress}
+      WORDPRESS_DB_PASSWORD: ${MYSQL_PASSWORD:-wppass}
+      HOME: /tmp
+      WP_CLI_CACHE_DIR: /tmp/wp-cli-cache
+    # Kept warm (long-lived) so the harness can `docker compose exec wp-cli wp ...`
+    # instead of paying container-startup cost on every wp-cli call.
+    entrypoint: ["tail", "-f", "/dev/null"]
+
+volumes:
+  mysql_data:
+  wp_data:

package/dist/cli/wp/constants.js

@@ -0,0 +1,52 @@
+import { githubRelease } from "./utils.js";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+//#region src/cli/wp/constants.ts
+const DEFAULT_PORT = 8080;
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** The docker-compose file shipped alongside this module (in both `src/` and `dist/`). */
+const COMPOSE_FILE = resolve(HERE, "compose/docker-compose.yml");
+const CONFIG_FILES = [
+	"kizlo.config.ts",
+	"kizlo.config.js",
+	"kizlo.config.mjs"
+];
+/** Credentials artifact location, relative to the config root. */
+const CREDENTIALS_REL = ".kizlo/test-credentials.json";
+const COMPOSE = [
+	"compose",
+	"-f",
+	COMPOSE_FILE
+];
+/**
+* DB-side marker written as the final bootstrap step and checked by `isSeeded`.
+* It records that this database holds a completed bootstrap — independent of any
+* fixture content, which is optional and varies per consumer. Bump `SEED_VERSION`
+* to force a reseed when the bootstrap contract changes.
+*/
+const SEED_MARKER_OPTION = "kizlo_test_seeded";
+const SEED_VERSION = "1";
+/** The kizlo core WordPress plugin, always installed during bootstrap. */
+const DEFAULT_PLUGINS = [{
+	name: "kizlo",
+	source: githubRelease("kizlo-io/kizlo-wordpress", "kizlo-v1.0.0-beta.3")
+}];
+const TEST_ADMIN = {
+	firstName: "Admin",
+	lastName: "",
+	username: "admin",
+	password: "admin_pass",
+	email: "admin@example.com"
+};
+const TEST_USER = {
+	firstName: "User",
+	lastName: "",
+	username: "user",
+	email: "user@example.com",
+	password: "user_pass",
+	role: "subscriber"
+};
+
+//#endregion
+export { COMPOSE, CONFIG_FILES, CREDENTIALS_REL, DEFAULT_PLUGINS, DEFAULT_PORT, SEED_MARKER_OPTION, SEED_VERSION, TEST_ADMIN, TEST_USER };

package/dist/cli/wp/docker.d.ts

@@ -0,0 +1,24 @@
+//#region src/cli/wp/docker.d.ts
+interface RunResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+/** `docker compose <args>` against the harness compose file. */
+declare function compose(args: string[], opts?: {
+  input?: string;
+}): Promise<RunResult>;
+/** Bring services up detached and wait for health checks. */
+declare function composeUp(): Promise<void>;
+/** Tear everything down, optionally removing volumes. */
+declare function composeDown(opts?: {
+  volumes?: boolean;
+}): Promise<void>;
+/** `docker compose stop` — halt containers but keep volumes (DB intact). */
+declare function composeStop(): Promise<void>;
+/**
+ * Run a wp-cli command against the warm `wp-cli` container and return trimmed stdout.
+ */
+declare function wpCli(args: string[]): Promise<string>;
+//#endregion
+export { compose, composeDown, composeStop, composeUp, wpCli };

package/dist/cli/wp/docker.js

@@ -0,0 +1,69 @@
+import { COMPOSE } from "./constants.js";
+import { spawn } from "node:child_process";
+
+//#region src/cli/wp/docker.ts
+function run(cmd, args, opts) {
+	return new Promise((resolvePromise, reject) => {
+		const child = spawn(cmd, args, { stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		] });
+		let stdout = "";
+		let stderr = "";
+		child.stdout.on("data", (d) => {
+			stdout += d;
+		});
+		child.stderr.on("data", (d) => {
+			stderr += d;
+		});
+		child.on("error", reject);
+		child.on("close", (code) => resolvePromise({
+			code: code ?? 0,
+			stdout,
+			stderr
+		}));
+		if (opts?.input !== void 0) child.stdin.end(opts.input);
+		else child.stdin.end();
+	});
+}
+/** `docker compose <args>` against the harness compose file. */
+async function compose(args, opts) {
+	return run("docker", [...COMPOSE, ...args], opts);
+}
+/** Bring services up detached and wait for health checks. */
+async function composeUp() {
+	const res = await compose([
+		"up",
+		"-d",
+		"--wait"
+	]);
+	if (res.code !== 0) throw new Error(`docker compose up failed:\n${res.stderr}`);
+}
+/** Tear everything down, optionally removing volumes. */
+async function composeDown(opts) {
+	const args = ["down"];
+	if (opts?.volumes) args.push("-v");
+	await compose(args);
+}
+/** `docker compose stop` — halt containers but keep volumes (DB intact). */
+async function composeStop() {
+	await compose(["stop"]);
+}
+/**
+* Run a wp-cli command against the warm `wp-cli` container and return trimmed stdout.
+*/
+async function wpCli(args) {
+	const res = await compose([
+		"exec",
+		"-T",
+		"wp-cli",
+		"wp",
+		...args
+	]);
+	if (res.code !== 0) throw new Error(`wp ${args.join(" ")} failed:\n${res.stderr || res.stdout}`);
+	return res.stdout.replace(/\r/g, "").trim();
+}
+
+//#endregion
+export { compose, composeDown, composeStop, composeUp, wpCli };