kizlo 0.1.1 → 0.2.1

package/README.md

@@ -41,7 +41,7 @@ Kizlo is a framework-agnostic toolkit for headless WordPress, built for a stack
 Set up Kizlo in your project:
 
 ```bash
-npx kizlo init
+npx kizlo@latest init
 ```
 
 Watch your extensions and regenerate the contract during development:

package/dist/adapters/auth.d.ts

@@ -2,17 +2,26 @@ import { Promisify } from "@kizlo/shared";
 
 //#region src/adapters/auth.d.ts
 interface AuthUser {
+  /** The WordPress user id this caller maps to. */
   id: number;
+  /** The user's email, if known. */
   email?: string;
+  /** The user's phone number, if known. */
   phone?: string;
+  /** The user's first name. */
   firstName: string;
+  /** The user's last name. */
   lastName: string;
 }
+type AuthGetUser = (request: Request | null) => Promisify<AuthUser | null>;
 interface AuthAdapter {
-  getUser(request: Request | null): Promisify<AuthUser | null>;
+  /** Resolve the authenticated user from the request, or `null` when there is no session. Receives `null` for server-side (non-HTTP) invocations. */
+  getUser: AuthGetUser;
 }
+/** Author a custom auth adapter, typed against the {@link AuthAdapter} contract. */
+declare function createAuthAdapter(adapter: AuthAdapter): AuthAdapter;
 declare function authMock(options?: {
   mockUserId?: number;
 }): AuthAdapter;
 //#endregion
-export { AuthAdapter, AuthUser, authMock };
+export { AuthAdapter, AuthGetUser, AuthUser, authMock, createAuthAdapter };

package/dist/adapters/auth.js

@@ -1,4 +1,8 @@
 //#region src/adapters/auth.ts
+/** Author a custom auth adapter, typed against the {@link AuthAdapter} contract. */
+function createAuthAdapter(adapter) {
+	return adapter;
+}
 function authMock(options) {
 	return { getUser() {
 		return {
@@ -12,4 +16,4 @@ function authMock(options) {
 }
 
 //#endregion
-export { authMock };
+export { authMock, createAuthAdapter };

package/dist/adapters/captcha.d.ts

@@ -3,6 +3,8 @@ type CaptchaAdapter = (input: {
   token: string;
   ip: string;
 }) => Promise<boolean>;
+/** Author a custom captcha adapter — types your verify function against the {@link CaptchaAdapter} contract. */
+declare function createCaptchaAdapter(adapter: CaptchaAdapter): CaptchaAdapter;
 declare function recaptcha(opts: {
   secret: string;
   minScore?: number;
@@ -25,4 +27,4 @@ declare function altcha(opts: {
   hmacKey: string;
 }): CaptchaAdapter;
 //#endregion
-export { CaptchaAdapter, altcha, arkose, friendlyCaptcha, hcaptcha, recaptcha, turnstile };
+export { CaptchaAdapter, altcha, arkose, createCaptchaAdapter, friendlyCaptcha, hcaptcha, recaptcha, turnstile };

package/dist/adapters/captcha.js

@@ -1,4 +1,8 @@
 //#region src/adapters/captcha.ts
+/** Author a custom captcha adapter — types your verify function against the {@link CaptchaAdapter} contract. */
+function createCaptchaAdapter(adapter) {
+	return adapter;
+}
 function recaptcha(opts) {
 	return async ({ token, ip }) => {
 		const data = await (await fetch("https://www.google.com/recaptcha/api/siteverify", {
@@ -83,4 +87,4 @@ function altcha(opts) {
 }
 
 //#endregion
-export { altcha, arkose, friendlyCaptcha, hcaptcha, recaptcha, turnstile };
+export { altcha, arkose, createCaptchaAdapter, friendlyCaptcha, hcaptcha, recaptcha, turnstile };

package/dist/adapters/cookies.d.ts

@@ -0,0 +1,7 @@
+import { CookiesAdapter } from "../shared/types.js";
+
+//#region src/adapters/cookies.d.ts
+/** Author a custom cookies adapter, typed against the {@link CookiesAdapter} contract. */
+declare function createCookiesAdapter(adapter: CookiesAdapter): CookiesAdapter;
+//#endregion
+export { createCookiesAdapter };

package/dist/adapters/cookies.js

@@ -0,0 +1,8 @@
+//#region src/adapters/cookies.ts
+/** Author a custom cookies adapter, typed against the {@link CookiesAdapter} contract. */
+function createCookiesAdapter(adapter) {
+	return adapter;
+}
+
+//#endregion
+export { createCookiesAdapter };

package/dist/adapters/geo.d.ts

@@ -2,17 +2,28 @@ import { Promisify } from "@kizlo/shared";
 
 //#region src/adapters/geo.d.ts
 interface ConnInfo {
+  /** Client IP address, or `null` if unavailable. */
   ip: string | null;
+  /** ISO country code, or `null`. */
   country: string | null;
+  /** City name, or `null`. */
   city: string | null;
+  /** Region/state, or `null`. */
   state: string | null;
+  /** Postal code, or `null`. */
   postcode: string | null;
+  /** IANA timezone, or `null`. */
   timezone: string | null;
+  /** The request's `User-Agent`, or `null`. */
   userAgent: string | null;
 }
+type GeoGetConnInfo = (request: Request | null) => Promisify<ConnInfo>;
 interface GeoAdapter {
-  getConnInfo(request: Request | null): Promisify<ConnInfo>;
+  /** Resolve connection info (IP, geo, user agent) from the request. Return the shape with `null` fields when unknown — never throw. Receives `null` server-side. */
+  getConnInfo: GeoGetConnInfo;
 }
+/** Author a custom geo adapter, typed against the {@link GeoAdapter} contract. */
+declare function createGeoAdapter(adapter: GeoAdapter): GeoAdapter;
 declare function geoMock(values?: Partial<ConnInfo>): GeoAdapter;
 //#endregion
-export { ConnInfo, GeoAdapter, geoMock };
+export { ConnInfo, GeoAdapter, GeoGetConnInfo, createGeoAdapter, geoMock };

package/dist/adapters/geo.js

@@ -1,4 +1,8 @@
 //#region src/adapters/geo.ts
+/** Author a custom geo adapter, typed against the {@link GeoAdapter} contract. */
+function createGeoAdapter(adapter) {
+	return adapter;
+}
 function geoMock(values) {
 	return { getConnInfo(request) {
 		return {
@@ -15,4 +19,4 @@ function geoMock(values) {
 }
 
 //#endregion
-export { geoMock };
+export { createGeoAdapter, geoMock };

package/dist/adapters/logger.d.ts

@@ -4,13 +4,20 @@ import { LiteralUnion } from "@kizlo/shared";
 type LogLevel = "debug" | "info" | "warn" | "error";
 type Environment = LiteralUnion<"development" | "production" | "test", string>;
 interface LogPayload {
+  /** Severity of the record: `debug`, `info`, `warn`, or `error`. */
   level: LogLevel;
+  /** The log message. */
   message: string;
+  /** When the record was created. */
   timestamp: Date;
+  /** Structured fields attached to the call, if any. */
   context?: Record<string, unknown>;
+  /** The associated error, present on `error`-level records that pass one. */
   error?: Error;
 }
 type LoggerAdapter = (payload: LogPayload) => void | Promise<void>;
+/** Author a custom logger adapter — types your handler against the {@link LoggerAdapter} contract. */
+declare function createLoggerAdapter(adapter: LoggerAdapter): LoggerAdapter;
 interface Logger {
   debug(message: string, context?: Record<string, unknown>): void;
   info(message: string, context?: Record<string, unknown>): void;
@@ -28,4 +35,4 @@ interface ConsoleLogAdapterOptions {
 declare function consoleLog(opts?: ConsoleLogAdapterOptions): LoggerAdapter;
 declare const noopAdapter: LoggerAdapter;
 //#endregion
-export { ConsoleLogAdapterOptions, Environment, LogLevel, LogPayload, Logger, LoggerAdapter, consoleLog, noopAdapter };
+export { ConsoleLogAdapterOptions, Environment, LogLevel, LogPayload, Logger, LoggerAdapter, consoleLog, createLoggerAdapter, noopAdapter };

package/dist/adapters/logger.js

@@ -1,4 +1,8 @@
 //#region src/adapters/logger.ts
+/** Author a custom logger adapter — types your handler against the {@link LoggerAdapter} contract. */
+function createLoggerAdapter(adapter) {
+	return adapter;
+}
 function consoleLog(opts = {}) {
 	const levelsOpt = opts.levels ?? true;
 	const allowed = levelsOpt === true ? null : new Set(levelsOpt === false ? [] : levelsOpt);
@@ -27,4 +31,4 @@ function consoleLog(opts = {}) {
 const noopAdapter = () => {};
 
 //#endregion
-export { consoleLog, noopAdapter };
+export { consoleLog, createLoggerAdapter, noopAdapter };

package/dist/cli/banner.js

@@ -11,6 +11,17 @@ const KIZLO_TAGLINE = "Headless WordPress toolkit for TypeScript";
 function colorSupported() {
 	return Boolean(process.stdout.isTTY) && process.env.NO_COLOR === void 0 && process.env.TERM !== "dumb";
 }
+/** The CLI's shared ANSI palette (empty strings when color is unsupported). */
+function palette() {
+	const on = colorSupported();
+	return {
+		cyan: on ? "\x1B[38;5;44m" : "",
+		green: on ? "\x1B[32m" : "",
+		bold: on ? "\x1B[1m" : "",
+		dim: on ? "\x1B[2m" : "",
+		reset: on ? "\x1B[0m" : ""
+	};
+}
 function printBanner(version) {
 	const color = colorSupported();
 	const cyan = color ? "\x1B[38;5;44m" : "";
@@ -23,4 +34,4 @@ function printBanner(version) {
 }
 
 //#endregion
-export { printBanner };
+export { palette, printBanner };

package/dist/cli/commands/dev.js

@@ -1,36 +1,218 @@
 import { createStack } from "../wp/docker.js";
-import { ensureGitignored, groupDefault, withSpinner } from "../utils.js";
-import { log } from "../daemon/logger.js";
+import { ensureGitignored, envGroups, getVersion, groupDefault, mergeEnv, pickStackPort, withSpinner } from "../utils.js";
+import { palette, printBanner } from "../banner.js";
 import { resolveDevConfig } from "../daemon/config.js";
+import { startWatcher } from "../daemon/watch.js";
 import { bootstrapDev } from "../wp/dev.js";
+import { reapOrphans, registerSession, removeProjectContainers, spawnWatchdog, unregisterSession } from "../wp/session.js";
+import { syncSiteSettings } from "../wp/settings.js";
 import { devStack } from "../wp/stack.js";
-import { rmSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { defineCommand } from "citty";
+import { networkInterfaces } from "node:os";
 
 //#region src/cli/commands/dev.ts
-async function resolve(cwd) {
+async function resolve$1(cwd) {
 	const cfg = await resolveDevConfig(cwd);
 	return {
 		cfg,
 		stack: createStack(devStack(cfg))
 	};
 }
-/** Print the connection summary. On a fresh install, show the one-time wp-admin password. */
+/** A dim, untagged one-liner (no consola timestamp) for the clean dev output. */
+function note(text) {
+	const { dim, reset } = palette();
+	process.stdout.write(`   ${dim}${text}${reset}\n`);
+}
+/** First non-internal IPv4 address, for the LAN-reachable "Network" URL (undefined when offline). */
+function lanAddress() {
+	for (const ifaces of Object.values(networkInterfaces())) for (const iface of ifaces ?? []) if (iface.family === "IPv4" && !iface.internal) return iface.address;
+}
+/**
+* Print the connection summary as an aligned, Next.js-style block. Shows the wp-admin
+* URL on localhost ("Local") and — when a LAN address exists — on the network, so the
+* stack can be opened from other devices. On a fresh install, also show the one-time
+* wp-admin password (it's never stored, so this is the only chance to see it).
+*/
 function printSummary(info) {
-	log.success(`WordPress dev stack ready at ${info.url}`);
-	if (info.secrets) {
-		log.info(`wp-admin: ${info.url}/wp-admin  (user: ${info.username} / pass: ${info.secrets.password})`);
-		log.info("Save the password now — it's shown only once and isn't stored on disk.");
-	} else if (info.imported) log.info(`wp-admin: ${info.url}/wp-admin — log in with your imported site's own credentials`);
-	else log.info(`wp-admin: ${info.url}/wp-admin  (user: ${info.username}) — password unchanged from first install`);
-	log.info(`database: 127.0.0.1:${info.dbPort}  (db: wordpress, user: wordpress, pass: wppass)`);
-	if (info.seeded > 0) log.info(`seeded:   ${info.seeded} fixture${info.seeded === 1 ? "" : "s"}`);
+	const { cyan, dim, reset } = palette();
+	const port = new URL(info.url).port;
+	const lan = lanAddress();
+	const rows = [["WP Local", `${info.url}/wp-admin`]];
+	if (lan) rows.push(["WP Network", `http://${lan}:${port}/wp-admin`]);
+	rows.push(["Database Connection", `127.0.0.1:${info.dbPort}`]);
+	const width = Math.max(...rows.map(([label]) => label.length)) + 1;
+	const lines = ["", ...rows.map(([label, value]) => `   ${dim}- ${`${label}:`.padEnd(width)}${reset} ${cyan}${value}${reset}`)];
+	if (info.secrets) lines.push("", `   ${dim}admin login:${reset} ${info.username} / ${info.secrets.password}`, `   ${dim}save the password now — it's shown only once${reset}`);
+	else if (info.imported) lines.push("", `   ${dim}log in with your imported site's own credentials${reset}`);
+	if (info.seeded > 0) lines.push(`   ${dim}seeded ${info.seeded} fixture${info.seeded === 1 ? "" : "s"}${reset}`);
+	process.stdout.write(`${lines.join("\n")}\n`);
+}
+/**
+* Dev connection keys a fresh dev install must rewrite (the rest of `.env` is untouched). The
+* production `KIZLO_WORDPRESS_*` / `KIZLO_SITE_SECRET` keys live under their own names and are never
+* touched by `kizlo dev`, so pointing them at a real site survives booting the local stack.
+*/
+const WP_ENV_KEYS = [
+	"KIZLO_DEV_WORDPRESS_URL",
+	"KIZLO_DEV_WORDPRESS_USERNAME",
+	"KIZLO_DEV_WORDPRESS_APPLICATION_PASSWORD"
+];
+/** Read a key's value from raw `.env` content (first match, trimmed); undefined when absent or empty. */
+function readEnvValue(content, key) {
+	return content.match(new RegExp(`^\\s*${key}\\s*=\\s*(.*)$`, "m"))?.[1]?.trim() || void 0;
+}
+/**
+* The Kizlo backend URL from `.env` — the one key ending in `KIZLO_BACKEND_URL` (`KIZLO_BACKEND_URL`,
+* or a framework-prefixed `NEXT_PUBLIC_KIZLO_BACKEND_URL`). It's the handler mount the plugin delivers
+* webhook events to; its origin is the site's canonical URL. User-managed (init writes it), so dev
+* only reads it. Undefined before `kizlo init` has populated `.env`.
+*/
+function readBaseUrl(content) {
+	return content.match(/^\s*[A-Z_]*KIZLO_BACKEND_URL\s*=\s*(.*)$/m)?.[1]?.trim() || void 0;
+}
+/**
+* Rewrite the dev WordPress connection in `.env` after a fresh install. A reset (or first boot)
+* wipes the database, so the previous application password — and possibly the port — no longer
+* match; without this the app keeps the stale credentials and REST auth fails. Only the three
+* connection keys are overwritten; everything else in `.env` is preserved, and the file is created
+* if absent. Gated by the caller on a minted `appPassword`, so a warm resume never churns it.
+*
+* `KIZLO_TARGET=dev` and `KIZLO_DEV_SITE_SECRET` are written too but kept out of the overwrite set, so a
+* value the user already set is preserved — booting the dev stack only fills them when absent. The
+* resolved dev secret (the existing one, or a freshly minted one) and the Kizlo server base URL are
+* returned so the caller can sync them into the plugin.
+*/
+function updateWpEnv(cfg, info) {
+	if (!info.appPassword) return void 0;
+	const envPath = join(cfg.configDir, ".env");
+	const existing = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
+	const siteSecret = readEnvValue(existing, "KIZLO_DEV_SITE_SECRET") ?? randomBytes(32).toString("hex");
+	const { content } = mergeEnv(existing, {
+		KIZLO_DEV_WORDPRESS_URL: info.url,
+		KIZLO_DEV_WORDPRESS_USERNAME: info.username,
+		KIZLO_DEV_WORDPRESS_APPLICATION_PASSWORD: info.appPassword,
+		KIZLO_DEV_SITE_SECRET: siteSecret,
+		KIZLO_TARGET: "dev"
+	}, new Set(WP_ENV_KEYS), envGroups("KIZLO_BACKEND_URL"));
+	writeFileSync(envPath, content);
+	return {
+		siteSecret,
+		baseUrl: readBaseUrl(existing)
+	};
+}
+/**
+* Arm the foreground teardown — call this *before* the containers start, so a cancel at
+* any point (even mid-startup, with mysql up but wordpress still booting) stops whatever
+* already came up. The teardown is owned by a detached **watchdog** process, not by this
+* one: containers belong to the Docker daemon, not our process tree, so — unlike a
+* `next dev` child server — nothing stops them automatically when we die. A dying process
+* also can't be trusted to finish async work (a closed terminal breaks its stdout
+* mid-write), so this process does no docker work on the way out. It only needs to
+* *exit*; the watchdog, watching our PID from its own session, stops the stack the moment
+* we're gone — by Ctrl+C, SIGTERM, a closed tab, SIGKILL, or a crash alike.
+*
+* We trigger that exit two ways, because neither alone is enough: signal handlers (for
+* Ctrl+C / `kill`), and an stdin/TTY-close watch (for a closed terminal, whose SIGHUP
+* an `npm`/`pnpm` wrapper silently swallows — leaving us orphaned but alive otherwise).
+*/
+function armForegroundTeardown(cfg) {
+	registerSession(cfg.project);
+	spawnWatchdog(cfg.project);
+	let exiting = false;
+	const shutdown = (reason) => {
+		if (exiting) return;
+		exiting = true;
+		unregisterSession(cfg.project);
+		try {
+			note(`Stopping dev stack (${reason})…`);
+		} catch {}
+		process.exit(0);
+	};
+	for (const signal of [
+		"SIGINT",
+		"SIGTERM",
+		"SIGHUP"
+	]) process.on(signal, () => shutdown(signal));
+	if (process.stdin.isTTY) {
+		process.stdin.resume();
+		for (const event of [
+			"end",
+			"close",
+			"error"
+		]) process.stdin.on(event, () => shutdown("terminal closed"));
+	}
+}
+/**
+* Boot the stack and run in the foreground until exit — the shared path behind bare
+* `kizlo dev` and `kizlo dev reset`. Arms teardown first (so a mid-startup cancel still
+* stops partial containers), shows a timed spinner, prints the summary + stop hint, then
+* parks. A referenced timer holds the event loop open — an unresolved promise alone would
+* not, so without it Node would empty its loop and exit straight after printing.
+*/
+async function startForeground(cfg) {
+	await removeProjectContainers(cfg.project);
+	const port = await pickStackPort(cfg.port, {
+		fixed: cfg.portExplicit,
+		configKey: "dev.port"
+	});
+	const dbPort = await pickStackPort(cfg.dbPort, {
+		fixed: cfg.dbPortExplicit,
+		host: "127.0.0.1",
+		configKey: "dev.dbPort"
+	});
+	const ready = {
+		...cfg,
+		port,
+		dbPort
+	};
+	createStack(devStack(ready));
+	if (port !== cfg.port) note(`Port ${cfg.port} is in use — serving on ${port} instead.`);
+	if (dbPort !== cfg.dbPort) note(`Database port ${cfg.dbPort} is in use — using ${dbPort} instead.`);
+	armForegroundTeardown(ready);
+	const start = Date.now();
+	const creds = await withSpinner("Starting WordPress dev stack", () => bootstrapDev(ready));
+	if (creds.appPassword) {
+		const env = updateWpEnv(ready, creds);
+		note("Updated .env with the new WordPress credentials");
+		if (env) {
+			const sync = await syncSiteSettings({
+				url: creds.url,
+				username: creds.username,
+				password: creds.appPassword
+			}, {
+				secret: env.siteSecret,
+				backendUrl: env.baseUrl,
+				containerized: true
+			});
+			if (!sync.ok) note(`Could not sync the site settings to WordPress (${sync.error}) — make sure the kizlo plugin is active, then set them from the Kizlo settings.`);
+		}
+	}
+	printSummary(creds);
+	const { green, dim, bold, reset } = palette();
+	const ms = Date.now() - start;
+	const took = ms < 1e3 ? `${ms}ms` : `${(ms / 1e3).toFixed(1)}s`;
+	process.stdout.write(`\n   ${dim}Press ${reset}${bold}Ctrl+C${reset}${dim} (or close the terminal) to stop the development stack${reset}\n`);
+	process.stdout.write(`\n ${green}✓${reset} Ready in ${took}\n\n`);
+	const stopWatcher = await startWatcher(ready.configDir);
+	if (stopWatcher) process.on("exit", stopWatcher);
+	setInterval(() => {}, 1 << 30);
+	await new Promise(() => {});
 }
-/** Start (or resume) the dev stack and print the connection summary. Backs bare `kizlo dev`. */
+/**
+* Start (or resume) the dev stack. Backs bare `kizlo dev`. Always runs in the foreground
+* and stops the stack on exit, so it never outlives the session — the subcommands
+* (`stop`/`down`/`reset`) manage everything else.
+*/
 async function bringUp() {
-	const { cfg } = await resolve(process.cwd());
+	printBanner(getVersion());
+	const reaped = await reapOrphans();
+	if (reaped.length) note(`Stopped ${reaped.length} orphaned dev stack${reaped.length === 1 ? "" : "s"}: ${reaped.join(", ")}`);
+	const cfg = await resolveDevConfig(process.cwd());
 	if (!cfg.wordpressPath.startsWith("..")) ensureGitignored(cfg.configDir, cfg.wordpressPath);
-	printSummary(await withSpinner("Starting WordPress dev stack", () => bootstrapDev(cfg), "WordPress dev stack ready"));
+	await startForeground(cfg);
 }
 const subCommands = {
 	stop: defineCommand({
@@ -39,7 +221,7 @@ const subCommands = {
 			description: "Stop the dev stack, keeping the database volume"
 		},
 		async run() {
-			const { stack } = await resolve(process.cwd());
+			const { stack } = await resolve$1(process.cwd());
 			await withSpinner("Stopping WordPress dev stack", () => stack.composeStop(), "Stack stopped (volumes kept)");
 		}
 	}),
@@ -49,7 +231,7 @@ const subCommands = {
 			description: "Stop and remove the dev stack containers (keeps the database and files)"
 		},
 		async run() {
-			const { stack } = await resolve(process.cwd());
+			const { stack } = await resolve$1(process.cwd());
 			await withSpinner("Removing WordPress dev stack", () => stack.composeDown(), "Stack removed (database and files kept)");
 		}
 	}),
@@ -59,13 +241,14 @@ const subCommands = {
 			description: "Wipe the database and the install folder, then rebuild fresh"
 		},
 		async run() {
-			const { cfg, stack } = await resolve(process.cwd());
+			printBanner(getVersion());
+			const { cfg, stack } = await resolve$1(process.cwd());
 			await withSpinner("Wiping WordPress dev stack", () => stack.composeDown({ volumes: true }), "Stack wiped");
 			rmSync(cfg.wordpressDir, {
 				recursive: true,
 				force: true
 			});
-			printSummary(await withSpinner("Starting WordPress dev stack", () => bootstrapDev(cfg), "WordPress dev stack ready"));
+			await startForeground(cfg);
 		}
 	})
 };