kizlo 0.9.1 → 0.11.0

package/dist/cli/presets/template.js

@@ -1,3 +1,4 @@
+import { getVersion } from "../utils.js";
 import { resolvePatchTargetPath } from "./patch.js";
 import z from "zod/v4";
 import path from "node:path";
@@ -7,17 +8,25 @@ import fs from "node:fs";
 /**
 * The template's `template.json`. It is the single declaration of what Kizlo lays onto a project and
 * how — the same engine drives both `create` (onto a fresh app the framework CLI just bootstrapped)
-* and `init` (onto the user's existing project). Changes are grouped into three sections so a command
-* only ever applies what is safe for it:
+* and `init` (onto the user's existing project). Changes are grouped into three sections by the one
+* question that decides whether a command may safely apply them — *where is this safe to land?* — and
+* no command ever reads another command's section:
 *
-* - `base` — applied by both commands: the Kizlo plumbing (server entry, client, routes). Every
-*   change here must be safe on an existing project, so it is limited to files Kizlo owns, which
-*   never collide with the user's pages.
-* - `create` — applied only by `create`, onto a freshly bootstrapped app it may freely overwrite:
-*   the root layout (written whole, already SEO-wired) and its styles as core wiring, plus the demo
-*   pages flagged `example`, which are written only when the user asks for example pages.
-* - `init` — applied only by `init`, onto the user's existing project. The root-layout SEO wiring
-*   lands here as a `patch` so it merges into the layout the user already owns instead of replacing it.
+* - `base` — safe on any project: additive, Kizlo-owned paths that never collide with the user's own
+*   files (the server entry, client, routes, and additive demo pages like a new blog route). Applied
+*   by both commands.
+* - `create` — safe only on a freshly bootstrapped app `create` may freely overwrite: the files the
+*   framework CLI already scaffolded, like the root layout (written whole, SEO-wired) and the homepage
+*   showcase. Applied only by `create`, never `init` — overwriting these on a real project would
+*   clobber the user's work.
+* - `init` — the non-destructive counterpart for the user's existing project: the root-layout SEO
+*   wiring lands here as a `patch` that merges into the layout the user already owns.
+*
+* Cutting across all three is the orthogonal `example` flag: opt-in demo content, applied only when the
+* user answers yes to "Add example pages?". A cross-cutting example (e.g. a blog) files each of its
+* pieces in the section that matches its safety — the additive new route in `base`, the homepage
+* showcase that overwrites an app-owned file in `create` — so `init` picks up only the additive half and
+* never touches a file the user owns, while `create` gets the whole demo. See {@link changesFor}.
 *
 * Each section is a list of changes, every one a member of a small closed set — deliberately no
 * "patch an arbitrary source file" kind, so a dangerous strategy is unrepresentable:
@@ -58,9 +67,36 @@ const bootstrapSchema = z.object({
 	flags: z.array(z.string()).default([])
 });
 const changeSchema = z.discriminatedUnion("kind", [fileSchema, patchSchema]);
+/**
+* The `.env` key names the scaffold writes and the pinned runtime later reads — the one part of the
+* wiring contract that can drift when the scaffold-time CLI and the pinned runtime disagree. Declared
+* here as data so the scaffold writes whatever names the pinned runtime expects. Semantic slots only;
+* the CLI still fills each value (generate a secret, provision Docker, prompt for a remote URL).
+*/
+const envSchema = z.object({
+	baseUrl: z.string(),
+	remote: z.object({
+		siteSecret: z.string(),
+		wpUrl: z.string(),
+		wpUsername: z.string(),
+		wpPassword: z.string()
+	}),
+	local: z.object({
+		connect: z.string(),
+		siteSecret: z.string(),
+		wpUrl: z.string(),
+		wpUsername: z.string(),
+		wpPassword: z.string()
+	})
+});
+/** A package name → version-range map, package.json's own vocabulary. */
+const depsSchema = z.record(z.string(), z.string());
 const manifestSchema = z.object({
 	framework: z.string(),
-	kizloVersion: z.string().optional(),
+	env: envSchema.optional(),
+	dependencies: depsSchema.optional(),
+	devDependencies: depsSchema.optional(),
+	minCli: z.string().optional(),
 	bootstrap: bootstrapSchema.optional(),
 	conventions: conventionsSchema,
 	base: z.array(changeSchema).default([]),
@@ -88,12 +124,62 @@ function readManifest(templateDir) {
 	return manifestSchema.parse(JSON.parse(fs.readFileSync(manifestPath, "utf8")));
 }
 /**
-* The changes a command applies: the shared `base` set plus the command's own section. `create` gets
-* `base + create` (plumbing plus the demo pages); `init` gets `base + init` (plumbing plus any
-* init-only surgical patches). `base` is applied first so a later section can override it.
+* The dependencies a scaffolded project should pin, from the manifest. `kizlo` is always present —
+* every project needs it — so it falls back to the running CLI's version in-repo before the first
+* stamped release; any other declared package is taken verbatim (a template only lists packages it has
+* a version for). Framework packages release in lockstep with `kizlo`, so a stamped manifest carries
+* them all at the same released version.
+*/
+function resolveDependencies(manifest) {
+	return {
+		dependencies: {
+			kizlo: `^${getVersion()}`,
+			...manifest.dependencies
+		},
+		devDependencies: { ...manifest.devDependencies }
+	};
+}
+/** A bare `x.y.z` from a version spec (range prefix and pre-release/build metadata dropped); undefined if none. */
+function coerceVersion(spec) {
+	const match = /(\d+)\.(\d+)\.(\d+)/.exec(spec);
+	return match ? [
+		Number(match[1]),
+		Number(match[2]),
+		Number(match[3])
+	] : void 0;
+}
+/** Whether `have` is a strictly older release than `want`; false when either can't be compared. */
+function isOlderVersion(have, want) {
+	const a = coerceVersion(have);
+	const b = coerceVersion(want);
+	if (!a || !b) return false;
+	for (let i = 0; i < 3; i++) if (a[i] !== b[i]) return a[i] < b[i];
+	return false;
+}
+/**
+* The loud-failure backstop: an error message when the running CLI is too old to apply this manifest,
+* or `undefined` when it's fine. Dormant by design — a manifest with no `minCli` never fails, so the
+* check is inert until a structural change bumps the floor. The first CLI-incompatible manifest change
+* sets `minCli`; from then on older CLIs (that already ship this check) stop with a clear message
+* instead of silently under-wiring the project.
+*/
+function minCliError(manifest) {
+	if (!manifest.minCli) return void 0;
+	const running = getVersion();
+	if (!isOlderVersion(running, manifest.minCli)) return void 0;
+	return `This template needs the kizlo CLI >= ${manifest.minCli} (you have ${running}). Run \`npx kizlo@latest\` and try again.`;
+}
+/**
+* The changes a command applies: the shared `base` set plus the command's own section (`base` first, so
+* a later section can override it). Section placement is the *safety* axis — `base` is additive and safe
+* on any project, `create`/`init` carry the fresh-app-vs-existing-project halves — while the `example`
+* flag is the orthogonal *opt-in* axis. Example changes are dropped unless `includeExamples`, so the same
+* call serves both "core wiring only" and "plus the demo pages", and each command only ever sees its own
+* section: init's opt-in examples are the additive ones in `base`, never create's homepage overwrite.
 */
-function changesFor(manifest, command) {
-	return [...manifest.base, ...manifest[command]];
+function changesFor(manifest, command, opts = {}) {
+	const changes = [...manifest.base, ...manifest[command]];
+	return opts.includeExamples ? changes : changes.filter((change) => !isExample(change));
 }
 /** The whole-file changes in a resolved change list. */
 function fileEntries(changes) {
@@ -103,7 +189,7 @@ function fileEntries(changes) {
 function patchEntries(changes) {
 	return changes.filter((change) => change.kind === "patch");
 }
-/** Whether a change is opt-in demo content — written by `create` only when example pages are requested. */
+/** Whether a change is opt-in demo content — applied only when example pages are requested. */
 function isExample(change) {
 	return change.kind === "file" && change.example === true;
 }
@@ -193,4 +279,4 @@ function rendersHtml(file) {
 }
 
 //#endregion
-export { adaptFile, changesFor, fileEntries, findRootLayout, isExample, patchEntries, readManifest, resolvePatch };
+export { adaptFile, changesFor, fileEntries, findRootLayout, isOlderVersion, minCliError, patchEntries, readManifest, resolveDependencies, resolvePatch };

package/dist/cli/utils.js

@@ -229,37 +229,59 @@ function envKeysPresent(contents, keys) {
 	return keys.filter((key) => new RegExp(`^\\s*${key}\\s*=`, "m").test(contents));
 }
 /**
+* The built-in key names, used by the generic `base` preset (no template, no separately-pinned
+* runtime) and as the fallback when a template's manifest declares no `env` section (in-repo before the
+* first stamped release). Real templates carry their own `env`, so this is the standard `KIZLO_*` set.
+*/
+const DEFAULT_ENV_KEYS = {
+	baseUrl: "KIZLO_API_URL",
+	remote: {
+		siteSecret: "KIZLO_WP_SECRET",
+		wpUrl: "KIZLO_WP_URL",
+		wpUsername: "KIZLO_WP_USERNAME",
+		wpPassword: "KIZLO_WP_APP_PASSWORD"
+	},
+	local: {
+		connect: "KIZLO_CONNECT",
+		siteSecret: "KIZLO_LOCAL_WP_SECRET",
+		wpUrl: "KIZLO_LOCAL_WP_URL",
+		wpUsername: "KIZLO_LOCAL_WP_USERNAME",
+		wpPassword: "KIZLO_LOCAL_WP_APP_PASSWORD"
+	}
+};
+/**
 * The grouped `.env` layout shared by `init` and `dev`, so both write the same sectioned file:
-* a target switch, the backend URL, then the production and dev connection blocks. `baseUrlEnvKey`
-* varies per preset (e.g. `NEXT_PUBLIC_KIZLO_BACKEND_URL`), so it's threaded in. Only sections whose
-* keys are actually being appended get a header, so a remote/prod run skips the dev block and vice versa.
+* a connect switch, the API URL, then the remote and local connection blocks. The key names come from
+* the resolved {@link EnvKeys} (the template's `env` contract), so the sections stay labelled correctly
+* whatever a template calls them. Only sections whose keys are actually being appended get a header, so
+* a remote run skips the local block and vice versa.
 */
-function envGroups(baseUrlEnvKey) {
+function envGroups(envKeys) {
 	return [
 		{
-			comment: "Kizlo Target (dev | prod)",
-			keys: ["KIZLO_TARGET"]
+			comment: "Kizlo Connect (local | remote)",
+			keys: [envKeys.local.connect]
 		},
 		{
-			comment: "Kizlo Backend URL",
-			keys: [baseUrlEnvKey]
+			comment: "Kizlo API URL",
+			keys: [envKeys.baseUrl]
 		},
 		{
-			comment: "Kizlo Production Env",
+			comment: "Kizlo Remote",
 			keys: [
-				"KIZLO_SITE_SECRET",
-				"KIZLO_WORDPRESS_URL",
-				"KIZLO_WORDPRESS_USERNAME",
-				"KIZLO_WORDPRESS_APPLICATION_PASSWORD"
+				envKeys.remote.siteSecret,
+				envKeys.remote.wpUrl,
+				envKeys.remote.wpUsername,
+				envKeys.remote.wpPassword
 			]
 		},
 		{
-			comment: "Kizlo Development Env",
+			comment: "Kizlo Local",
 			keys: [
-				"KIZLO_DEV_SITE_SECRET",
-				"KIZLO_DEV_WORDPRESS_URL",
-				"KIZLO_DEV_WORDPRESS_USERNAME",
-				"KIZLO_DEV_WORDPRESS_APPLICATION_PASSWORD"
+				envKeys.local.siteSecret,
+				envKeys.local.wpUrl,
+				envKeys.local.wpUsername,
+				envKeys.local.wpPassword
 			]
 		}
 	];
@@ -354,4 +376,4 @@ function groupDefault(subCommandNames, run) {
 }
 
 //#endregion
-export { addDependencyArgs, availablePackageManagers, detectImportAlias, detectInvokingPackageManager, detectPackageManager, ensureGitignored, envGroups, envKeysPresent, frameworkCreateArgs, getVersion, groupDefault, installArgs, loadEnvFiles, mergeEnv, pickStackPort, resolveModuleImport, runCommandAsync, runCommandCaptured, withSpinner, writeFileIfAbsent };
+export { DEFAULT_ENV_KEYS, addDependencyArgs, availablePackageManagers, detectImportAlias, detectInvokingPackageManager, detectPackageManager, ensureGitignored, envGroups, envKeysPresent, frameworkCreateArgs, getVersion, groupDefault, installArgs, loadEnvFiles, mergeEnv, pickStackPort, resolveModuleImport, runCommandAsync, runCommandCaptured, withSpinner, writeFileIfAbsent };

package/dist/cli/wp/compose/override.js

@@ -3,10 +3,10 @@ import { basename, dirname, isAbsolute, resolve } from "node:path";
 import { mkdirSync, writeFileSync } from "node:fs";
 
 //#region src/cli/wp/compose/override.ts
-/** Generated dev override location, relative to the config root. */
-const OVERRIDE_REL = ".kizlo/docker-compose.dev.override.yml";
+/** Generated local WordPress override location, relative to the config root. */
+const OVERRIDE_REL = ".kizlo/compose.local.yml";
 /** Generated test override location (plugin mounts only), relative to the config root. */
-const TEST_OVERRIDE_REL = ".kizlo/docker-compose.test.override.yml";
+const TEST_OVERRIDE_REL = ".kizlo/compose.test.yml";
 const WP_ROOT = "/var/www/html";
 const PLUGINS_DIR = `${WP_ROOT}/wp-content/plugins`;
 /** Where the dev OPcache config is dropped so the container's PHP picks it up. */

package/dist/cli/wp/compose/override.test.ts

@@ -20,7 +20,7 @@ describe("writeDevOverride", () => {
 
 	test("bind-mounts the whole install on both services and creates the host dir", () => {
 		const file = writeDevOverride(dir, { wordpressDir, mounts: [] })
-		expect(file).toBe(path.join(dir, ".kizlo", "docker-compose.dev.override.yml"))
+		expect(file).toBe(path.join(dir, ".kizlo", "compose.local.yml"))
 		expect(fs.existsSync(wordpressDir)).toBe(true)
 
 		const body = fs.readFileSync(file, "utf8")
@@ -89,7 +89,7 @@ describe("writeTestOverride", () => {
 
 	test("mounts local plugin dirs by basename on both services", () => {
 		const file = writeTestOverride(dir, ["plugins/kizlo-woocommerce"])
-		expect(file).toBe(path.join(dir, ".kizlo", "docker-compose.test.override.yml"))
+		expect(file).toBe(path.join(dir, ".kizlo", "compose.test.yml"))
 
 		const body = fs.readFileSync(file, "utf8")
 		const pluginBind = `- "${path.join(dir, "plugins/kizlo-woocommerce")}:/var/www/html/wp-content/plugins/kizlo-woocommerce"`

package/dist/cli/wp/compose/override.ts

@@ -2,10 +2,10 @@ import { mkdirSync, writeFileSync } from "node:fs"
 import { basename, dirname, isAbsolute, resolve } from "node:path"
 import { OPCACHE_INI, REMAP_ENTRYPOINT } from "../constants"
 
-/** Generated dev override location, relative to the config root. */
-const OVERRIDE_REL = ".kizlo/docker-compose.dev.override.yml"
+/** Generated local WordPress override location, relative to the config root. */
+const OVERRIDE_REL = ".kizlo/compose.local.yml"
 /** Generated test override location (plugin mounts only), relative to the config root. */
-const TEST_OVERRIDE_REL = ".kizlo/docker-compose.test.override.yml"
+const TEST_OVERRIDE_REL = ".kizlo/compose.test.yml"
 
 const WP_ROOT = "/var/www/html"
 const PLUGINS_DIR = `${WP_ROOT}/wp-content/plugins`

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

@@ -12,13 +12,19 @@ declare function githubRelease(repo: string, tag: string): string;
 declare function kizloRelease(slug: string): string;
 /** The docker-compose file shipped alongside this module (in both `src/` and `dist/`). */
 declare const COMPOSE_FILE: string;
-/** Dev PHP OPcache config, shipped alongside this module and bind-mounted into the dev stack. */
+/** PHP OPcache config, shipped alongside this module and bind-mounted into the local WordPress. */
 declare const OPCACHE_INI: string;
 /** Linux-only entrypoint that retags www-data to the host user (see the script for why). */
 declare const REMAP_ENTRYPOINT: string;
 declare const CONFIG_FILES: string[];
-/** Credentials artifact location, relative to the config root. */
-declare const CREDENTIALS_REL = ".kizlo/test-credentials.json";
+/** Test connection artifact location, relative to the config root. */
+declare const CREDENTIALS_REL = ".kizlo/test.json";
+/**
+ * Fixed folder the local WordPress install lives in, relative to the config root. The whole install
+ * (core, themes, uploads, plugins) is bind-mounted here; `kizlo dev reset` wipes it. It sits under
+ * `.kizlo/` — the single gitignored working dir — so there's no folder to choose or configure.
+ */
+declare const LOCAL_DIR_REL = ".kizlo/local";
 /**
  * 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
@@ -32,4 +38,4 @@ declare const DEFAULT_PLUGINS: PluginSource[];
 declare const TEST_ADMIN: Omit<TestAdminUser, "id" | "applicationPassword">;
 declare const TEST_USER: Omit<TestUser, "id">;
 //#endregion
-export { COMPOSE_FILE, CONFIG_FILES, CREDENTIALS_REL, DEFAULT_PLUGINS, DEFAULT_PORT, OPCACHE_INI, REMAP_ENTRYPOINT, SEED_MARKER_OPTION, SEED_VERSION, TEST_ADMIN, TEST_USER, githubRelease, kizloRelease };
+export { COMPOSE_FILE, CONFIG_FILES, CREDENTIALS_REL, DEFAULT_PLUGINS, DEFAULT_PORT, LOCAL_DIR_REL, OPCACHE_INI, REMAP_ENTRYPOINT, SEED_MARKER_OPTION, SEED_VERSION, TEST_ADMIN, TEST_USER, githubRelease, kizloRelease };

package/dist/cli/wp/constants.js

@@ -18,7 +18,7 @@ function kizloRelease(slug) {
 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");
-/** Dev PHP OPcache config, shipped alongside this module and bind-mounted into the dev stack. */
+/** PHP OPcache config, shipped alongside this module and bind-mounted into the local WordPress. */
 const OPCACHE_INI = resolve(HERE, "compose/opcache.ini");
 /** Linux-only entrypoint that retags www-data to the host user (see the script for why). */
 const REMAP_ENTRYPOINT = resolve(HERE, "compose/remap-entrypoint.sh");
@@ -27,8 +27,14 @@ const CONFIG_FILES = [
 	"kizlo.config.js",
 	"kizlo.config.mjs"
 ];
-/** Credentials artifact location, relative to the config root. */
-const CREDENTIALS_REL = ".kizlo/test-credentials.json";
+/** Test connection artifact location, relative to the config root. */
+const CREDENTIALS_REL = ".kizlo/test.json";
+/**
+* Fixed folder the local WordPress install lives in, relative to the config root. The whole install
+* (core, themes, uploads, plugins) is bind-mounted here; `kizlo dev reset` wipes it. It sits under
+* `.kizlo/` — the single gitignored working dir — so there's no folder to choose or configure.
+*/
+const LOCAL_DIR_REL = ".kizlo/local";
 /**
 * 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
@@ -59,4 +65,4 @@ const TEST_USER = {
 };
 
 //#endregion
-export { COMPOSE_FILE, CONFIG_FILES, CREDENTIALS_REL, DEFAULT_PLUGINS, DEFAULT_PORT, OPCACHE_INI, REMAP_ENTRYPOINT, SEED_MARKER_OPTION, SEED_VERSION, TEST_ADMIN, TEST_USER, githubRelease, kizloRelease };
+export { COMPOSE_FILE, CONFIG_FILES, CREDENTIALS_REL, DEFAULT_PLUGINS, DEFAULT_PORT, LOCAL_DIR_REL, OPCACHE_INI, REMAP_ENTRYPOINT, SEED_MARKER_OPTION, SEED_VERSION, TEST_ADMIN, TEST_USER, githubRelease, kizloRelease };

package/dist/cli/wp/dev.js

@@ -3,9 +3,8 @@ import { DEFAULT_PLUGINS, TEST_ADMIN } from "./constants.js";
 import { compose, composePull, composeUp, wpCli } from "./docker.js";
 import { ensurePlugins } from "./utils.js";
 import { createAdminAppPassword, seedUsers } from "./bootstrap.js";
-import { prepareByo } from "./byo.js";
 import { join } from "node:path";
-import { existsSync, rmSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { networkInterfaces } from "node:os";
 import { randomBytes } from "node:crypto";
 
@@ -19,7 +18,7 @@ function lanAddress() {
 	for (const ifaces of Object.values(networkInterfaces())) for (const iface of ifaces ?? []) if (iface.family === "IPv4" && !iface.internal) return iface.address;
 }
 /**
-* The URL the dev stack is provisioned at. We prefer the router-assigned LAN address over `localhost`
+* The URL local WordPress is provisioned at. We prefer the router-assigned LAN address over `localhost`
 * so it's reachable from off the host (the app in a container or on another device). Serving WordPress
 * under the request host is already handled by the container's `WORDPRESS_CONFIG_EXTRA` (it derives
 * `WP_HOME`/`WP_SITEURL` from `HTTP_HOST` per request), so this is only the address we write into `.env`
@@ -29,7 +28,7 @@ function devUrl(port) {
 	return `http://${lanAddress() ?? "localhost"}:${port}`;
 }
 /**
-* Seed `dev.fixtures` into a freshly installed dev stack, reusing the test seeding
+* Seed `dev.fixtures` into freshly installed local WordPress, reusing the test seeding
 * primitives: seed the default subscriber so `ctx.userId` exists, then run each `seed`
 * over REST. Plugins are already active (`bootstrapDev` ensures them before seeding).
 * The application password is minted only to drive seeding here — it's never printed
@@ -61,22 +60,18 @@ async function seedDevFixtures(cfg, url) {
 	return seeded;
 }
 /**
-* Boot the dev stack via docker + wp-cli. A fresh stack is provisioned one of two ways:
-* a default `wp core install`, or — when `dev.byo` points at an archive — hydrated from
-* that existing site (files + database). Either way it then sets permalinks and ensures
-* the `dev.fixtures` plugins (installed sources + bind-mounted locals). An already-provisioned
-* stack is left untouched (idempotent reruns).
+* Boot local WordPress via docker + wp-cli. A fresh install is provisioned with a default
+* `wp core install`, then sets permalinks and ensures the `dev.fixtures` plugins (installed
+* sources + bind-mounted locals). An already-provisioned install is left untouched
+* (idempotent reruns).
 *
-* Credentials are an output, not a stored file: a default fresh install mints a random
-* admin password and returns it once (to log into wp-admin); a BYO install uses the
-* imported site's own users. No application password is minted — that's a test-stack
-* concern.
+* Credentials are an output, not a stored file: a fresh install mints a random admin
+* password and returns it once (to log into wp-admin). No application password is minted —
+* that's a test concern.
 */
 async function bootstrapDev(cfg) {
 	const url = devUrl(cfg.port);
-	const fresh = !existsSync(join(cfg.wordpressDir, "wp-includes", "version.php"));
-	const byo = fresh && cfg.byo ? await prepareByo(cfg.byo, cfg.wordpressDir, cfg.configDir) : void 0;
-	if (fresh && !byo) await composePull(["wordpress", "wp-cli"]).catch(() => void 0);
+	if (!existsSync(join(cfg.wordpressDir, "wp-includes", "version.php"))) await composePull(["wordpress", "wp-cli"]).catch(() => void 0);
 	await composeUp();
 	const installed = (await compose([
 		"exec",
@@ -87,46 +82,7 @@ async function bootstrapDev(cfg) {
 		"is-installed"
 	])).code === 0;
 	let password;
-	let imported = false;
-	if (!installed && byo) {
-		imported = true;
-		if (byo.prefix !== "wp_") await wpCli([
-			"config",
-			"set",
-			"table_prefix",
-			byo.prefix,
-			"--type=variable"
-		]);
-		const imp = await compose([
-			"exec",
-			"-T",
-			"mysql",
-			"mysql",
-			"-uwordpress",
-			"-pwppass",
-			"wordpress"
-		], { inputFile: byo.sqlPath });
-		if (imp.code !== 0) throw new Error(`importing dev.byo database failed:\n${imp.stderr || imp.stdout}`);
-		rmSync(byo.sqlPath, { force: true });
-		const oldUrl = await wpCli([
-			"option",
-			"get",
-			"siteurl"
-		]).catch(() => "");
-		if (oldUrl && oldUrl !== url) await wpCli([
-			"search-replace",
-			oldUrl,
-			url,
-			"--all-tables",
-			"--skip-columns=guid",
-			"--report-changed-only"
-		]);
-		await wpCli([
-			"rewrite",
-			"flush",
-			"--hard"
-		]);
-	} else if (!installed) {
+	if (!installed) {
 		password = generatePassword();
 		await wpCli([
 			"core",
@@ -146,13 +102,12 @@ async function bootstrapDev(cfg) {
 		]);
 	}
 	await ensurePlugins([...DEFAULT_PLUGINS, ...cfg.fixtures.flatMap((fixture) => fixture.plugins ?? [])]);
-	const seeded = !installed && !byo && cfg.fixtures.length ? await seedDevFixtures(cfg, url) : 0;
+	const seeded = !installed && cfg.fixtures.length ? await seedDevFixtures(cfg, url) : 0;
 	const appPassword = password ? await createAdminAppPassword("kizlo-dev") : void 0;
 	return {
 		url,
 		username: TEST_ADMIN.username,
 		dbPort: cfg.dbPort,
-		imported,
 		seeded,
 		appPassword,
 		secrets: password ? { password } : void 0

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

@@ -41,10 +41,22 @@ interface RunResult {
   stderr: string;
 }
 /**
- * Whether the Docker daemon is reachable. `docker version` contacts the server (not just
- * the client), so a non-zero exit means the daemon is down or Docker isn't installed —
- * the early check before a command that needs a stack (e.g. `init`'s local setup).
+ * Docker's readiness in three states, so callers can tell "not installed" from "installed but not
+ * running" and say the right thing:
+ * - `missing` — the `docker` binary isn't on PATH (`docker --version` errors).
+ * - `stopped` — the client is installed but the daemon is unreachable (`docker version` fails).
+ * - `running` — the daemon answered, so a stack can boot.
  */
+type DockerStatus = "missing" | "stopped" | "running";
+/**
+ * Probe Docker in two steps: `docker --version` only touches the client (is it installed?), then
+ * `docker version` contacts the server (is the daemon up?). Used before any command that needs local
+ * WordPress, so the caller can distinguish an install problem from a "start Docker" problem.
+ */
+declare function dockerStatus(): Promise<DockerStatus>;
+/** The one-line fix to print when Docker isn't ready — install it, or start the daemon. */
+declare function dockerHint(status: "missing" | "stopped"): string;
+/** Whether the Docker daemon is reachable — the early check before a command that needs a stack. */
 declare function dockerAvailable(): Promise<boolean>;
 /** Build a stack-bound docker helper and mark it active for the bare helpers below. */
 declare function createStack(stack: Stack): DockerStack;
@@ -65,4 +77,4 @@ declare const composeStop: (opts?: {
 /** Run a wp-cli command against the active stack's warm `wp-cli` container. */
 declare const wpCli: (args: string[]) => Promise<string>;
 //#endregion
-export { DockerStack, RunResult, Stack, compose, composeDown, composePull, composeStop, composeUp, createStack, dockerAvailable, wpCli };
+export { DockerStack, DockerStatus, RunResult, Stack, compose, composeDown, composePull, composeStop, composeUp, createStack, dockerAvailable, dockerHint, dockerStatus, wpCli };

package/dist/cli/wp/docker.js

@@ -33,17 +33,30 @@ function run(cmd, args, env, opts) {
 	});
 }
 /**
-* Whether the Docker daemon is reachable. `docker version` contacts the server (not just
-* the client), so a non-zero exit means the daemon is down or Docker isn't installed —
-* the early check before a command that needs a stack (e.g. `init`'s local setup).
+* Probe Docker in two steps: `docker --version` only touches the client (is it installed?), then
+* `docker version` contacts the server (is the daemon up?). Used before any command that needs local
+* WordPress, so the caller can distinguish an install problem from a "start Docker" problem.
 */
-async function dockerAvailable() {
+async function dockerStatus() {
+	try {
+		if ((await run("docker", ["--version"], process.env)).code !== 0) return "missing";
+	} catch {
+		return "missing";
+	}
 	try {
-		return (await run("docker", ["version"], process.env)).code === 0;
+		return (await run("docker", ["version"], process.env)).code === 0 ? "running" : "stopped";
 	} catch {
-		return false;
+		return "stopped";
 	}
 }
+/** The one-line fix to print when Docker isn't ready — install it, or start the daemon. */
+function dockerHint(status) {
+	return status === "missing" ? "Docker isn't installed. Install it from https://docs.docker.com/get-docker/, then re-run." : "Docker is installed but not running. Start Docker (Docker Desktop, or `sudo systemctl start docker`) and re-run.";
+}
+/** Whether the Docker daemon is reachable — the early check before a command that needs a stack. */
+async function dockerAvailable() {
+	return await dockerStatus() === "running";
+}
 function bind(stack) {
 	const base = [
 		"compose",
@@ -131,4 +144,4 @@ const composeStop = (opts) => activeStack().composeStop(opts);
 const wpCli = (args) => activeStack().wpCli(args);
 
 //#endregion
-export { compose, composeDown, composePull, composeStop, composeUp, createStack, dockerAvailable, wpCli };
+export { compose, composeDown, composePull, composeStop, composeUp, createStack, dockerAvailable, dockerHint, dockerStatus, wpCli };

package/dist/cli/wp/settings.js

@@ -1,5 +1,6 @@
 import { WP_KIZLO_BASE } from "../../wordpress/constants.js";
 import { WordPressService } from "../../wordpress/service.js";
+import { PLUGIN_VERSION_HEADER } from "@kizlo/shared";
 
 //#region src/cli/wp/settings.ts
 /** Loopback hosts that, from inside the dev Docker stack, must be rewritten to reach the host. */
@@ -18,7 +19,7 @@ function originOf(url) {
 	}
 }
 /**
-* Rewrite a loopback host to `host.docker.internal` so the dockerized WordPress dev stack can reach a
+* Rewrite a loopback host to `host.docker.internal` so the dockerized local WordPress can reach a
 * Kizlo server on the host (the container's own `localhost` is not the host). Non-loopback hosts (real
 * deployments) and unparseable URLs are returned unchanged.
 */
@@ -52,11 +53,16 @@ async function syncSiteSettings(credentials, settings) {
 		base: WP_KIZLO_BASE,
 		body
 	});
+	const pluginVersion = response.headers.get(PLUGIN_VERSION_HEADER);
 	if (response.error) return {
 		ok: false,
-		error: describeError(response.status, response.error)
+		error: describeError(response.status, response.error),
+		pluginVersion
+	};
+	return {
+		ok: true,
+		pluginVersion
 	};
-	return { ok: true };
 }
 /**
 * A short, log-friendly summary of a failed request. A transport failure has no HTTP status (`0`), so

package/dist/cli/wp/setup.js

@@ -8,7 +8,7 @@ import { mkdirSync, writeFileSync } from "node:fs";
 /**
 * Phase 2 — after bootstrap, build a `SeedContext` and run each `Fixture.seed`
 * over REST, collecting namespaced fixtures, then write the credentials artifact
-* at `<config-dir>/.kizlo/test-credentials.json`. Returns a teardown that runs
+* at `<config-dir>/.kizlo/test.json`. Returns a teardown that runs
 * each fixture's `cleanup`.
 */
 async function runSeeds(config) {

package/dist/cli/wp/stack.js

@@ -10,7 +10,7 @@ function localMounts(fixtures) {
 /**
 * The test stack: the base compose file under a `<name>-test` project, plus a generated
 * mount override when any fixture carries a local (`{ path }`) plugin — so the same
-* fixtures bind-mount their live plugin source here exactly as in the dev stack.
+* fixtures bind-mount their live plugin source here exactly as in local WordPress.
 */
 function testStack(cfg) {
 	const mounts = localMounts(cfg.fixtures);
@@ -36,9 +36,9 @@ function detectHostUser() {
 	};
 }
 /**
-* The dev stack: the base compose file plus the generated mount override, under a
-* `<name>-dev` project. Building the stack (re)writes the override so it always
-* matches the current `dev.path` and the `dev.fixtures` local plugins.
+* Local WordPress: the base compose file plus the generated mount override, under a
+* `<name>-dev` project. Building it (re)writes the override so it always matches the
+* install folder (`.kizlo/local`) and the `dev.fixtures` local plugins.
 */
 function devStack(cfg) {
 	const override = writeDevOverride(cfg.configDir, {

package/dist/comment/schema.js

@@ -1,5 +1,5 @@
-import { ListMetadata, ListOrder, Media } from "../shared/schema.js";
-import { NumberLike, arrayable } from "@kizlo/shared";
+import { ListMetadata, ListOrder } from "../shared/schema.js";
+import { Media, NumberLike, arrayable } from "@kizlo/shared";
 import z from "zod/v4";
 
 //#region src/comment/schema.ts