kizlo 0.12.0 → 0.13.0

package/dist/cli/commands/_setup.js

@@ -1,7 +1,7 @@
 import { LOCAL_DIR_REL } from "../wp/constants.js";
 import { composeStop, createStack, dockerHint, dockerStatus } from "../wp/docker.js";
-import { DEFAULT_ENV_KEYS, ensureGitignored, envGroups, envKeysPresent, mergeEnv, pickStackPort, writeFileIfAbsent } from "../utils.js";
-import { DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, resolveStackName } from "../daemon/config.js";
+import { DEFAULT_ENV_KEYS, availablePackageManagers, detectInvokingPackageManager, ensureGitignored, envGroups, envKeysPresent, mergeEnv, pickStackPort, writeFileIfAbsent } from "../utils.js";
+import { DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, resolveStackName, stackProject } from "../daemon/config.js";
 import { createAdminAppPassword } from "../wp/bootstrap.js";
 import { bootstrapDev } from "../wp/dev.js";
 import { removeProjectContainers } from "../wp/session.js";
@@ -100,6 +100,32 @@ function orCancel(value) {
 	}
 	return value;
 }
+/** Package managers the CLI can wire getting-started steps for, in display order. */
+const PACKAGE_MANAGERS = [
+	"pnpm",
+	"npm",
+	"yarn",
+	"bun"
+];
+/**
+* Ask which package manager to use, offering only those installed on the host. The pre-selected default
+* is the manager that invoked this CLI when it's available (a hint, not a decision — `npx` reports
+* `npm`, so it can be wrong, which is exactly why we ask rather than commit to it), else the first
+* installed. `create` asks up front; `init` asks only when it couldn't detect one from the project.
+*/
+async function selectPackageManager(message) {
+	const installed = availablePackageManagers(PACKAGE_MANAGERS);
+	const invoking = detectInvokingPackageManager();
+	const initialValue = invoking && installed.includes(invoking) ? invoking : installed[0];
+	return orCancel(await p.select({
+		message,
+		options: installed.map((id) => ({
+			value: id,
+			label: id
+		})),
+		initialValue
+	}));
+}
 /** Appends the API path to the base URL so the client and route handler agree. */
 function withApiPath(baseUrl, apiPath) {
 	try {
@@ -174,15 +200,23 @@ async function collectConnectionInteractively(apiPath, opts = {}) {
 	const mode = orCancel(await p.select({
 		message: "WordPress connection",
 		initialValue: "local",
-		options: [{
-			value: "local",
-			label: "Set up local WordPress",
-			hint: "runs in Docker, for dev and test"
-		}, {
-			value: "remote",
-			label: "Use my own WordPress",
-			hint: "connect to your existing WordPress"
-		}]
+		options: [
+			{
+				value: "local",
+				label: "Set up local WordPress",
+				hint: "runs in Docker, for dev and test"
+			},
+			{
+				value: "remote",
+				label: "Use my own WordPress",
+				hint: "connect to your existing WordPress"
+			},
+			{
+				value: "skip",
+				label: "Skip for now",
+				hint: "fill in the connection in .env later"
+			}
+		]
 	}));
 	if (mode === "local") {
 		const status = await dockerStatus();
@@ -209,8 +243,9 @@ async function collectConnectionInteractively(apiPath, opts = {}) {
 			validate: validate(requiredString)
 		}));
 	}
+	if (mode === "skip") p.log.info("Skipping WordPress setup — the connection keys are written to .env empty for you to fill in later.");
 	return {
-		mode,
+		mode: mode === "local" ? "local" : "remote",
 		baseUrl,
 		siteUrl,
 		siteSecret,
@@ -238,7 +273,7 @@ function collectConnectionFromEnv(envKeys) {
 function devConfigFor(cwd) {
 	return {
 		configDir: cwd,
-		project: `${resolveStackName(cwd)}-dev`,
+		project: stackProject(resolveStackName(cwd), "dev"),
 		port: DEFAULT_DEV_PORT,
 		portExplicit: false,
 		dbPort: DEFAULT_DEV_DB_PORT,
@@ -412,4 +447,4 @@ function nextStepsNote(conn, prefix = "") {
 }
 
 //#endregion
-export { collectConnectionFromEnv, collectConnectionInteractively, dirPath, nextStepsLines, nextStepsNote, orCancel, pickAppPort, readEnvExample, resolveEnvKeys, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv };
+export { collectConnectionFromEnv, collectConnectionInteractively, dirPath, nextStepsLines, nextStepsNote, orCancel, pickAppPort, readEnvExample, resolveEnvKeys, selectPackageManager, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv };

package/dist/cli/commands/_wiring.js

@@ -1,39 +1,44 @@
-import { resolveModuleImport, writeFileIfAbsent } from "../utils.js";
-import { applyPatchToSource, patchChanged, renderPatchCode } from "../presets/patch.js";
-import { findRootLayout, resolvePatch } from "../presets/template.js";
+import { aliasWithSlash, resolveModuleImport, writeFileIfAbsent } from "../utils.js";
+import { resolvePatch } from "../presets/template.js";
 import { orCancel } from "./_setup.js";
 import { CONTRACT_BARREL } from "../daemon/generate.js";
+import { applyPatchToSource, patchChanged, renderPatchCode, resolvePatchTargetPath } from "../presets/patch.js";
 import path from "node:path";
 import fs from "node:fs";
 import * as p from "@clack/prompts";
 
 //#region src/cli/commands/_wiring.ts
-/** The kizlo.config.ts a scaffolded project gets: the Kizlo directory, an optional import alias, and —
+/** The kizlo.config.ts a scaffolded project gets: the Kizlo directory, the import-alias preference, and —
 *  when local WordPress is chosen — `dev.local` + `test.local` so `kizlo dev` and `kizlo test` boot the
-*  fixed `.kizlo/local` install. */
+*  fixed `.kizlo/local` install. The alias is always written — `""` for relative imports included — so it
+*  records a made decision a later `kizlo init` reads back instead of prompting for it again. The alias
+*  is written in its canonical `@/` form (never a bare `@`) so it reads like the imports it produces. */
 function kizloConfigTemplate(dir, alias, localWordPress = false) {
 	return `import { defineConfig } from "kizlo/config"
 
 export default defineConfig({
-	dir: "${dir}",${alias ? `\n\talias: "${alias}",` : ""}${localWordPress ? `\n\tdev: { local: true },\n\ttest: { local: true },` : ""}
+	dir: "${dir}",${`\n\talias: "${aliasWithSlash(alias)}",`}${localWordPress ? `\n\tdev: { local: true },\n\ttest: { local: true },` : ""}
 })
 `;
 }
 /**
 * Build the {@link ScaffoldContext} that adapts a template's conventions (paths and imports) to a real
 * project. `dirRel` is the Kizlo home directory, `appDir` the App Router directory, and `alias` the
-* import-alias prefix (empty for relative imports). The server-entry import is resolved per calling
-* file so each scaffolded file references the server through the right specifier.
+* import-alias prefix (empty for relative imports). Imports are resolved per calling file so each
+* scaffolded file references its targets through the right specifier — `importFrom` for any project
+* path (used to retarget every template-alias import), `serverImport` the server-entry shorthand.
 */
 function buildScaffoldContext(cwd, { dirRel, appDir, alias, clientUrl }) {
 	const serverDirRel = path.join(dirRel, "server");
+	const importFrom = (targetRel, fromDir) => resolveModuleImport(cwd, targetRel, fromDir, alias);
 	return {
 		kizloDir: dirRel,
 		serverDirName: path.basename(serverDirRel),
 		serverEntryPath: path.join(serverDirRel, "index.ts"),
 		clientPath: path.join(dirRel, "client.ts"),
 		appDir,
-		serverImport: (fromDir) => resolveModuleImport(cwd, serverDirRel, fromDir, alias),
+		serverImport: (fromDir) => importFrom(serverDirRel, fromDir),
+		importFrom,
 		clientUrl
 	};
 }
@@ -73,17 +78,24 @@ function writeGeneratedContract(cwd, serverDirRel) {
 	writeFileIfAbsent(path.join(cwd, generatedDirRel, "index.ts"), CONTRACT_BARREL);
 }
 /**
-* Merge Kizlo wiring into files the project already owns (the root layout's SEO exports). Never
-* aborts: the target is resolved by identity (the layout that renders `<html>`), and on any doubt —
-* not found, not parseable — the resolved payload is printed at the end with placement instructions
-* rather than written to a guessed-at file. A confident apply is an idempotent upsert: it replaces
-* our exports if present, adds them if not.
+* Apply every patch a template declares, merging Kizlo wiring into files the project already owns
+* (today: the root layout and home page SEO exports — but the loop is role-agnostic, so a new patch
+* needs no change here). Never aborts: the target is the exact path the template declares (extension-
+* probed so a JS project's `.js`/`.jsx` is found), and on any doubt — the file isn't at that path, or
+* won't parse — the resolved payload is printed at the end with placement instructions rather than
+* written to a guessed-at file. We never scan the tree to find a stand-in. A confident apply is an
+* idempotent upsert: it replaces our exports if present, adds them if not.
 */
-function applyLayoutPatches(cwd, patches, conventions, scaffold) {
+function applyProjectPatches(cwd, patches, conventions, scaffold) {
 	const manualSteps = [];
 	for (const entry of patches) {
 		const resolved = resolvePatch(entry, conventions, scaffold);
-		const target = findRootLayout(cwd, scaffold.appDir, resolved.relPath);
+		if (resolved.mode === "note") {
+			manualSteps.push(resolved);
+			p.log.info(`Update your ${resolved.label} to finish wiring Kizlo — see the change to make below`);
+			continue;
+		}
+		const target = resolvePatchTargetPath(cwd, resolved.relPath);
 		if (!target) {
 			manualSteps.push(resolved);
 			p.log.info(`Couldn't find your ${resolved.label} to wire Kizlo into — see the code to add below`);
@@ -105,8 +117,19 @@ function applyLayoutPatches(cwd, patches, conventions, scaffold) {
 			p.log.success(`Wired Kizlo into your ${resolved.label} (${relTarget})`);
 		} else p.log.info(`Your ${resolved.label} is already wired (${relTarget})`);
 	}
-	for (const resolved of manualSteps) p.note(renderPatchCode(resolved), `Add these to your ${resolved.label} (the layout that renders <html>)`);
+	for (const resolved of manualSteps) printManualStep(resolved.mode === "note" ? `Update your ${resolved.label} (${resolved.relPath})` : `Add these to your ${resolved.label} (${resolved.relPath})`, renderPatchCode(resolved));
+}
+/**
+* Print a manual-step code block the user copies into a file. Deliberately avoids `p.note`: clack
+* draws a `│`/`─` box around the body, so selecting the block in a terminal drags those border
+* characters into the clipboard alongside the code. We print the heading through clack for the usual
+* voice, then the code verbatim with no gutter so a terminal selection yields exactly the source.
+*/
+function printManualStep(heading, code) {
+	p.log.step(heading);
+	const body = code.endsWith("\n") ? code.slice(0, -1) : code;
+	process.stdout.write(`\n${body}\n\n`);
 }
 
 //#endregion
-export { applyLayoutPatches, buildScaffoldContext, kizloConfigTemplate, reportScaffold, scaffoldFile, writeGeneratedContract };
+export { applyProjectPatches, buildScaffoldContext, kizloConfigTemplate, printManualStep, reportScaffold, scaffoldFile, writeGeneratedContract };

package/dist/cli/commands/create.js

@@ -1,8 +1,8 @@
-import { availablePackageManagers, detectInvokingPackageManager, ensureGitignored, frameworkCreateArgs, installArgs, runCommandAsync, runCommandCaptured } from "../utils.js";
+import { approveBuildsCommand, ensureGitignored, frameworkCreateArgs, initGitRepository, installArgs, isCommandAvailable, isGitRepository, runCommandCaptured, runCommandCapturedAsync } from "../utils.js";
 import { fetchRegistry, listTemplates, resolveRegistry } from "../presets/source.js";
 import { adaptFile, changesFor, fileEntries, minCliError, patchEntries, readManifest, resolveDependencies } from "../presets/template.js";
-import { collectConnectionInteractively, nextStepsLines, orCancel, pickAppPort, readEnvExample, resolveEnvKeys, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv } from "./_setup.js";
-import { applyLayoutPatches, buildScaffoldContext, kizloConfigTemplate, reportScaffold, scaffoldFile, writeGeneratedContract } from "./_wiring.js";
+import { collectConnectionInteractively, nextStepsLines, orCancel, pickAppPort, readEnvExample, resolveEnvKeys, selectPackageManager, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv } from "./_setup.js";
+import { applyProjectPatches, buildScaffoldContext, kizloConfigTemplate, reportScaffold, scaffoldFile, writeGeneratedContract } from "./_wiring.js";
 import z from "zod/v4";
 import path from "node:path";
 import fs from "node:fs";
@@ -34,13 +34,6 @@ const projectNameSchema = z.string().trim().min(1, "Required").refine((value) =>
 	return base.length > 0 && base !== "." && base !== ".." && /^[A-Za-z0-9._-]+$/.test(base);
 }, "The app folder (last path segment) can only contain letters, numbers, dots, and dashes");
 const projectName = validate(projectNameSchema);
-/** Package managers `create` can wire the getting-started steps for, in display order. */
-const PACKAGE_MANAGERS = [
-	"pnpm",
-	"npm",
-	"yarn",
-	"bun"
-];
 /**
 * Pin Kizlo's dependencies in the freshly bootstrapped `package.json`. The template is authoritative
 * for the versions (its manifest's `dependencies`/`devDependencies`, stamped at release), falling back
@@ -88,7 +81,7 @@ function bootstrapArgs(manifest, pm, name) {
 * `kizlo` dependency, write `kizlo.config.ts`, scaffold the manifest's files (core wiring from `base`
 * and `create` always, the `example`-flagged demo pages only when `includeExamples`),
 * seed the generated contract, and ignore `.env` and the `.kizlo/` working dir (which holds the local WordPress install). On a fresh app Kizlo owns the layout, so `create`
-* writes it whole (already SEO-wired) rather than patching — `applyLayoutPatches` runs over `create`'s
+* writes it whole (already SEO-wired) rather than patching — `applyProjectPatches` runs over `create`'s
 * patches, which are none today. The target directory layout comes straight from the manifest's
 * conventions, which the bootstrap flags are chosen to match, so files land where they expect. Fresh
 * files are written with `force`, silently replacing the framework defaults.
@@ -115,7 +108,7 @@ async function applyManifestWiring(dir, templateDir, manifest, opts) {
 	writeGeneratedContract(dir, path.join(kizloDir, "server"));
 	ensureGitignored(dir, ".env");
 	ensureGitignored(dir, ".kizlo/");
-	applyLayoutPatches(dir, patchEntries(changes), manifest.conventions, scaffold);
+	applyProjectPatches(dir, patchEntries(changes), manifest.conventions, scaffold);
 }
 const create = defineCommand({
 	meta: {
@@ -195,17 +188,7 @@ const create = defineCommand({
 		}
 		const dir = path.resolve(cwd, name);
 		if (fs.existsSync(dir)) return cancelFrom(`${name} already exists — pick a different name or remove it.`);
-		const installed = availablePackageManagers(PACKAGE_MANAGERS);
-		const invokingPm = detectInvokingPackageManager();
-		const defaultPm = invokingPm && installed.includes(invokingPm) ? invokingPm : installed[0];
-		const pm = orCancel(await p.select({
-			message: "Package manager",
-			options: installed.map((id) => ({
-				value: id,
-				label: id
-			})),
-			initialValue: defaultPm
-		}));
+		const pm = await selectPackageManager("Package manager");
 		const conn = await collectConnectionInteractively(manifest.apiPath, { baseUrl: `http://localhost:${await pickAppPort()}` });
 		if (manifest.apiPath && conn.baseUrl) conn.baseUrl = withApiPath(conn.baseUrl, manifest.apiPath);
 		const includeExamples = orCancel(await p.confirm({
@@ -233,13 +216,16 @@ const create = defineCommand({
 		}
 		fetchedRegistry.cleanup();
 		let depsInstalled = false;
+		let approveBuilds;
 		if (orCancel(await p.confirm({
 			message: "Install dependencies now?",
 			initialValue: true
 		}))) {
 			const is = p.spinner();
 			is.start(`Installing dependencies with ${pm}`);
-			depsInstalled = await runCommandAsync(installArgs(pm), dir, "ignore");
+			const install = await runCommandCapturedAsync(installArgs(pm), dir);
+			depsInstalled = install.ok;
+			if (depsInstalled) approveBuilds = approveBuildsCommand(pm, install.output);
 			is.stop(depsInstalled ? "Installed dependencies" : "Could not install dependencies");
 			if (!depsInstalled) p.log.warn(`Install them yourself: cd ${name} && ${installArgs(pm).join(" ")}`);
 		}
@@ -250,9 +236,19 @@ const create = defineCommand({
 			exampleTemplate
 		});
 		await syncRemote(conn);
+		if (isCommandAvailable("git") && !isGitRepository(dir) && orCancel(await p.confirm({
+			message: "Initialize a git repository?",
+			initialValue: true
+		}))) {
+			const gs = p.spinner();
+			gs.start("Initializing git repository");
+			const ok = initGitRepository(dir);
+			gs.stop(ok ? "Initialized git repository" : "Could not initialize git repository");
+		}
 		p.note([
 			`cd ${name}`,
 			...depsInstalled ? [] : [`${pm} install`],
+			...approveBuilds ? [approveBuilds] : [],
 			``,
 			...nextStepsLines(conn)
 		].join("\n"), "Next steps");

package/dist/cli/commands/init.js

@@ -1,8 +1,8 @@
-import { addDependencyArgs, detectImportAlias, detectPackageManager, ensureGitignored, getVersion, loadEnvFiles, runCommandAsync } from "../utils.js";
+import { addDependencyArgs, aliasWithSlash, detectImportAlias, detectInvokingPackageManager, detectPackageManager, ensureGitignored, getVersion, loadEnvFiles, persistPackageManagerField, readPersistedAlias, runCommandAsync } from "../utils.js";
 import { DEFAULT_REGISTRY, detectTemplates, fetchRegistry, isSingleTemplate, listTemplates, resolveRegistry } from "../presets/source.js";
 import { adaptFile, changesFor, fileEntries, isOlderVersion, minCliError, patchEntries, readManifest, renderNote, resolveDependencies } from "../presets/template.js";
-import { collectConnectionFromEnv, collectConnectionInteractively, dirPath, nextStepsNote, orCancel, readEnvExample, resolveEnvKeys, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv } from "./_setup.js";
-import { applyLayoutPatches, buildScaffoldContext, kizloConfigTemplate, reportScaffold, scaffoldFile, writeGeneratedContract } from "./_wiring.js";
+import { collectConnectionFromEnv, collectConnectionInteractively, dirPath, nextStepsNote, orCancel, readEnvExample, resolveEnvKeys, selectPackageManager, setupLocalWordPress, syncRemote, validate, withApiPath, writeEnv } from "./_setup.js";
+import { applyProjectPatches, buildScaffoldContext, kizloConfigTemplate, printManualStep, reportScaffold, scaffoldFile, writeGeneratedContract } from "./_wiring.js";
 import path from "node:path";
 import fs from "node:fs";
 import { defineCommand } from "citty";
@@ -12,10 +12,6 @@ import * as p from "@clack/prompts";
 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(/\/+$/, "")}/` : "";
-}
 /** Whether two URLs share an origin (scheme + host + port); false when either can't be parsed. */
 function sameOrigin(a, b) {
 	try {
@@ -42,14 +38,24 @@ function detectAppDir(cwd, hasSrcDir, templateAppDir) {
 	if (fs.existsSync(path.join(cwd, "app"))) return "app";
 	return hasSrcDir ? "src/app" : "app";
 }
+/**
+* The import alias settled without asking — the explicit `--alias` flag, else the alias a previous init
+* persisted in kizlo.config. `undefined` when neither is set: the choice hasn't been made, so it must be
+* prompted for (interactive) or defaulted to relative imports (`--yes`). Detection never enters here — a
+* tsconfig alias is only ever a prompt *hint*, since relative imports always work and a detected alias
+* isn't a guarantee (a project may have several, or map one Kizlo's dir isn't under).
+*/
+function decidedAlias(flagAlias, persistedAlias) {
+	return flagAlias ?? persistedAlias;
+}
 async function collectInteractively(ctx) {
 	const dir = orCancel(await p.text({
 		message: "Kizlo directory",
 		initialValue: defaultDir(ctx.hasSrcDir),
 		validate: validate(dirPath)
 	}));
-	let alias = "";
-	if (ctx.apiPath) {
+	let alias = decidedAlias(ctx.flagAlias, ctx.persistedAlias);
+	if (alias === void 0) if (ctx.apiPath) {
 		const serverDir = path.join(dir.replace(/^\.\//, "").replace(/\/+$/, ""), "server");
 		const detected = detectImportAlias(ctx.cwd, serverDir)?.prefix;
 		alias = orCancel(await p.text({
@@ -57,7 +63,7 @@ async function collectInteractively(ctx) {
 			placeholder: "@/",
 			initialValue: detected ? `${detected}/` : ""
 		})).trim();
-	}
+	} else alias = "";
 	return {
 		...await collectConnectionInteractively(ctx.apiPath),
 		dir,
@@ -65,9 +71,11 @@ async function collectInteractively(ctx) {
 	};
 }
 /**
-* 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.
+* 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. The alias is the `--alias` flag, else the
+* one persisted from a prior run, else relative imports — never silent tsconfig detection, since `--yes`
+* can't confirm it and relative imports always work. Never fails — `--yes` always scaffolds a fillable
+* project.
 */
 function collectFromEnv(ctx) {
 	const conn = collectConnectionFromEnv(ctx.envKeys);
@@ -75,28 +83,49 @@ function collectFromEnv(ctx) {
 	return {
 		...conn,
 		dir,
-		alias: ctx.apiPath ? aliasWithSlash(detectImportAlias(ctx.cwd, path.join(dir, "server"))?.prefix) : ""
+		alias: decidedAlias(ctx.flagAlias, ctx.persistedAlias) ?? ""
 	};
 }
 function readPkg(pkgPath) {
 	return JSON.parse(fs.readFileSync(pkgPath, "utf8"));
 }
 /**
-* The template is authoritative for the pinned versions: it declares `dependencies`/`devDependencies`
-* in its manifest (stamped at release), falling back to the running CLI's version for `kizlo` in-repo
-* before the first stamp. For each declared package the project already has at an older release, upgrade
-* it up to the template's pin and say so — a deliberate pin is never changed silently. Never downgrades,
-* and never adds a package the project doesn't already have (a missing `kizlo` is installed separately).
+* Bring the project's dependencies in line with the template's pins. The template is authoritative for
+* the versions: it declares `dependencies`/`devDependencies` in its manifest (stamped at release),
+* falling back to the running CLI's version for `kizlo` in-repo before the first stamp. For each declared
+* package:
+*
+* - missing from the project — install it at the template's pin, as a dev dependency when the template
+*   declares it there. `create` records the template's whole dependency set into the fresh app before
+*   installing; `init` layers onto an existing project, so packages the template needs but the project
+*   lacks (e.g. Astro's `@astrojs/node` adapter) must be added here or the app won't run.
+* - present at an older release — upgrade it up to the pin and say so; a deliberate newer pin is never
+*   changed silently, and nothing is ever downgraded.
+*
+* A *missing* `kizlo` is installed on its own earlier (with its own messaging), so it's skipped here;
+* an existing older `kizlo` still gets the upgrade path.
 */
 async function alignDependencies(cwd, pm, pkg, manifest) {
 	const { dependencies, devDependencies } = resolveDependencies(manifest);
-	for (const [name, want] of [...Object.entries(dependencies), ...Object.entries(devDependencies)]) {
+	const declared = [...Object.entries(dependencies).map(([name, want]) => ({
+		name,
+		want,
+		dev: false
+	})), ...Object.entries(devDependencies).map(([name, want]) => ({
+		name,
+		want,
+		dev: true
+	}))];
+	for (const { name, want, dev } of declared) {
 		const have = pkg.dependencies?.[name] ?? pkg.devDependencies?.[name];
-		if (!have || !isOlderVersion(have, want)) continue;
+		if (name === "kizlo" && !have) continue;
+		if (have && !isOlderVersion(have, want)) continue;
+		const args = addDependencyArgs(pm, `${name}@${want}`, { dev });
 		const s = p.spinner();
-		s.start(`Upgrading ${name} from ${have} to ${want}`);
-		const ok = await runCommandAsync(addDependencyArgs(pm, `${name}@${want}`), cwd, "ignore");
-		s.stop(ok ? `Upgraded ${name} to ${want}` : `Could not upgrade ${name} automatically — install ${name}@${want} yourself`);
+		s.start(have ? `Upgrading ${name} from ${have} to ${want}` : `Installing ${name}@${want}`);
+		const ok = await runCommandAsync(args, cwd, "ignore");
+		if (have) s.stop(ok ? `Upgraded ${name} to ${want}` : `Could not upgrade ${name} automatically — install ${name}@${want} yourself`);
+		else s.stop(ok ? `Installed ${name}@${want}` : `Could not install ${name} automatically — run \`${args.join(" ")}\` yourself`);
 	}
 }
 const init = defineCommand({
@@ -145,7 +174,9 @@ const init = defineCommand({
 			process.exit(1);
 		}
 		const pkg = readPkg(pkgPath);
-		const pm = detectPackageManager(cwd);
+		const detectedPm = detectPackageManager(cwd);
+		const pm = detectedPm ?? (yes ? detectInvokingPackageManager() ?? "npm" : await selectPackageManager("Couldn't detect this project's package manager — which should Kizlo use?"));
+		if (!detectedPm && !yes) persistPackageManagerField(cwd, pm);
 		const hasKizlo = Boolean(pkg.dependencies?.kizlo) || Boolean(pkg.devDependencies?.kizlo);
 		const hasSrcDir = fs.existsSync(path.join(cwd, "src"));
 		if (yes) loadEnvFiles(cwd);
@@ -221,17 +252,18 @@ const init = defineCommand({
 			if (manifest.requires && !manifest.requires.anyDir.some((rel) => fs.existsSync(path.join(cwd, rel)))) cancelFrom(manifest.requires.message);
 			const apiPath = manifest.apiPath;
 			const envKeys = resolveEnvKeys(manifest);
-			const setup = yes ? collectFromEnv({
+			const flagAlias = args.alias !== void 0 ? String(args.alias).trim() : void 0;
+			const aliasCtx = {
 				cwd,
 				hasSrcDir,
 				apiPath,
+				persistedAlias: readPersistedAlias(cwd),
+				flagAlias
+			};
+			const setup = yes ? collectFromEnv({
+				...aliasCtx,
 				envKeys
-			}) : await collectInteractively({
-				cwd,
-				hasSrcDir,
-				apiPath
-			});
-			if (args.alias !== void 0) setup.alias = String(args.alias).trim();
+			}) : await collectInteractively(aliasCtx);
 			setup.alias = aliasWithSlash(setup.alias);
 			const includeExamples = yes ? true : orCancel(await p.confirm({
 				message: "Add example pages?",
@@ -281,10 +313,10 @@ const init = defineCommand({
 			const gitignore = ensureGitignored(cwd, ".env");
 			ensureGitignored(cwd, ".kizlo/");
 			for (const { file, result } of scaffolded) reportScaffold(file, result, yes);
-			applyLayoutPatches(cwd, patchEntries(changesFor(manifest, "init")), manifest.conventions, scaffold);
+			applyProjectPatches(cwd, patchEntries(changesFor(manifest, "init")), manifest.conventions, scaffold);
 			for (const note of manifest.notes ?? []) {
 				const rendered = renderNote(note, setup.alias);
-				p.note(rendered.body, rendered.title);
+				printManualStep(rendered.title, rendered.body);
 			}
 			if (gitignore !== "present") p.log.success(`${gitignore === "created" ? "Created" : "Updated"} .gitignore (ignoring .env)`);
 			nextStepsNote(setup);

package/dist/cli/daemon/config.js

@@ -105,6 +105,14 @@ function resolveStackName(configDir, configName) {
 	return sanitizeProjectName(pkgName ?? path.basename(configDir));
 }
 /**
+* Compose project id for a stack: `kizlo-<name>-<kind>`. The leading `kizlo-` is what
+* lets every stack this tool starts be filtered together in Docker (e.g.
+* `docker ps --filter name=kizlo-`), independent of each project's own name.
+*/
+function stackProject(baseName, kind) {
+	return `kizlo-${baseName}-${kind}`;
+}
+/**
 * Resolve the `test` block from `kizlo.config.*` into concrete values for the
 * `test` command, applying defaults (port 8889, auto-detected package manager)
 * and anchoring the credentials artifact to the config directory.
@@ -116,13 +124,13 @@ async function resolveTestConfig(cwd) {
 	return {
 		configDir,
 		local: Boolean(test.local),
-		project: `${resolveStackName(configDir, fileConfig?.name)}-test`,
+		project: stackProject(resolveStackName(configDir, fileConfig?.name), "test"),
 		command: test.command,
 		port: test.port ?? DEFAULT_TEST_PORT,
 		portExplicit: test.port !== void 0,
 		fixtures: test.fixtures ?? [],
 		credentialsPath: credentialsPath(cwd),
-		packageManager: test.packageManager ?? detectPackageManager(configDir)
+		packageManager: test.packageManager ?? detectPackageManager(configDir) ?? "npm"
 	};
 }
 /**
@@ -148,7 +156,7 @@ async function resolveDevConfig(cwd) {
 	const dev = fileConfig?.dev ?? {};
 	return {
 		configDir,
-		project: `${resolveStackName(configDir, fileConfig?.name)}-dev`,
+		project: stackProject(resolveStackName(configDir, fileConfig?.name), "dev"),
 		port: dev.port ?? DEFAULT_DEV_PORT,
 		portExplicit: dev.port !== void 0,
 		dbPort: dev.dbPort ?? DEFAULT_DEV_DB_PORT,
@@ -160,4 +168,4 @@ async function resolveDevConfig(cwd) {
 }
 
 //#endregion
-export { CONFIG_FILES, DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, resolveConfig, resolveDevConfig, resolveStackName, resolveTestConfig, usesLocalWordPress };
+export { CONFIG_FILES, DEFAULT_DEV_DB_PORT, DEFAULT_DEV_PORT, resolveConfig, resolveDevConfig, resolveStackName, resolveTestConfig, stackProject, usesLocalWordPress };

package/dist/cli/presets/patch.js

@@ -47,6 +47,36 @@ function staticCounterpart(name) {
 function sameExpr(a, b) {
 	return a.replace(/\s+/g, "") === b.replace(/\s+/g, "");
 }
+/** The module's statement list (magicast's `$ast` is a `Program`, but tolerate a `File` wrapper too). */
+function programBody(mod) {
+	const ast = mod.$ast;
+	return (ast.type === "File" ? ast.program : ast).body;
+}
+/** The name of an `export const <name> = …` statement, or undefined for any other node. */
+function exportedConstName(node) {
+	if (node.type !== "ExportNamedDeclaration") return void 0;
+	const decl = node.declaration;
+	if (decl?.type !== "VariableDeclaration") return void 0;
+	const id = decl.declarations?.[0]?.id;
+	return id?.type === "Identifier" ? id.name : void 0;
+}
+/**
+* Move the just-inserted exports (named in `names`) up to sit right after the import block, so wiring
+* lands near the top of the file instead of appended below the component. magicast always appends a new
+* export to the end of the program; this re-splices those nodes in after the last import, preserving
+* their declared order. Exports we replaced in place are untouched — only nodes we added this run move.
+*/
+function hoistExportsAfterImports(mod, names) {
+	const body = programBody(mod);
+	const moved = [];
+	for (const name of names) {
+		const idx = body.findIndex((node) => exportedConstName(node) === name);
+		if (idx !== -1) moved.push(body.splice(idx, 1)[0]);
+	}
+	let insertAt = 0;
+	for (let i = 0; i < body.length; i++) if (body[i]?.type === "ImportDeclaration") insertAt = i + 1;
+	body.splice(insertAt, 0, ...moved);
+}
 /**
 * Merge a resolved patch into `source` by parsing it with magicast (a real TS/JS/JSX parser via Babel,
 * so declarations are bounded exactly — never by a text heuristic). Missing imports are added; each
@@ -57,6 +87,10 @@ function sameExpr(a, b) {
 * export body isn't meant to be hand-customized. Idempotent: an export already equal to ours is left
 * untouched, so re-running never churns the file.
 *
+* magicast appends new exports to the end of the file; we then hoist the ones we added this run up to
+* sit right after the import block, so wiring reads near the top instead of below the component. Exports
+* replaced in place keep their position — only nodes newly inserted this run move.
+*
 * Throws if the target cannot be parsed or regenerated. Callers must NOT swallow that — a file we
 * can't parse is one we must not guess at, so wiring falls back to a printed instruction instead.
 */
@@ -71,6 +105,7 @@ function applyPatchToSource(source, patch) {
 		addedExports: [],
 		replacedExports: []
 	};
+	const insertedNames = [];
 	for (const imp of patch.imports) for (const name of imp.names) {
 		if (mod.imports.$items.some((item) => item.from === imp.module && item.imported === name)) continue;
 		mod.imports.$append({
@@ -92,11 +127,14 @@ function applyPatchToSource(source, patch) {
 			delete mod.exports[counterpart];
 			mod.exports[exp.name] = builders.raw(exp.value);
 			changes.replacedExports.push(exp.name);
+			insertedNames.push(exp.name);
 			continue;
 		}
 		mod.exports[exp.name] = builders.raw(exp.value);
 		changes.addedExports.push(exp.name);
+		insertedNames.push(exp.name);
 	}
+	if (insertedNames.length) hoistExportsAfterImports(mod, insertedNames);
 	return {
 		text: generateCode(mod, { format }).code,
 		changes
@@ -105,9 +143,11 @@ function applyPatchToSource(source, patch) {
 /**
 * Render a resolved patch as source the user can paste in, for the printed fallback when the target
 * can't be resolved or parsed. The same declared payload the confident apply upserts, so what we tell
-* the user to add never drifts from what we would have written.
+* the user to add never drifts from what we would have written. A `note`-mode patch carries its own
+* verbatim body (its change isn't an import/`export const`), so that is printed as-is when present.
 */
 function renderPatchCode(patch) {
+	if (patch.note) return patch.note.endsWith("\n") ? patch.note : `${patch.note}\n`;
 	const imports = patch.imports.map((imp) => `import { ${imp.names.join(", ")} } from "${imp.module}"`);
 	const exports = patch.exports.map((exp) => `export const ${exp.name} = ${exp.value}`);
 	return `${[

package/dist/cli/presets/template.js

@@ -1,5 +1,4 @@
-import { getVersion } from "../utils.js";
-import { resolvePatchTargetPath } from "./patch.js";
+import { getVersion, readTsconfigPaths } from "../utils.js";
 import z from "zod/v4";
 import path from "node:path";
 import fs from "node:fs";
@@ -35,7 +34,9 @@ import fs from "node:fs";
 *   overwrite policy.
 * - `patch` — a partial injection into a file the framework owns (the root layout's SEO exports):
 *   it adds or replaces individual modules (imports/exports) inside the file, never the whole file.
-*   Both commands try a confident apply, otherwise print the payload with placement instructions.
+*   Both commands try a confident apply, otherwise print the payload with placement instructions. A
+*   patch may instead set `mode: "note"` to always print its instructions rather than edit the file —
+*   for a change too shaped-unlike an import/export to auto-merge (Astro's `defineConfig` output/adapter).
 */
 const conventionsSchema = z.object({
 	kizloDir: z.string(),
@@ -53,14 +54,16 @@ const patchSchema = z.object({
 	role: z.string(),
 	label: z.string(),
 	path: z.string(),
+	mode: z.enum(["apply", "note"]).default("apply"),
 	imports: z.array(z.object({
 		module: z.string(),
 		names: z.array(z.string())
-	})),
+	})).default([]),
 	exports: z.array(z.object({
 		name: z.string(),
 		value: z.string()
-	}))
+	})).default([]),
+	note: z.string().optional()
 });
 const bootstrapSchema = z.object({
 	initializer: z.string(),
@@ -239,10 +242,41 @@ function patchEntries(changes) {
 function isExample(change) {
 	return change.kind === "file" && change.example === true;
 }
-/** The specifier the template's files use to reach the server entry, e.g. `@/lib/kizlo/server`. */
-function serverImportSpecifier(conventions) {
-	const withoutSrc = conventions.kizloDir.replace(/^src\//, "");
-	return `${conventions.alias.replace(/\/+$/, "")}/${withoutSrc}/server`;
+/** Escape a string so its characters are matched literally inside a RegExp. */
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* The directory the template's alias resolves to — the maintainer's own preference, read straight from
+* the template's tsconfig `paths` (e.g. `@/* → ./src/*` yields `src`). This is the root stripped to turn
+* an alias import back into a real template path before it's remapped to the project. Falls back to the
+* `src`/root heuristic when the template declares no matching alias, staying consistent with the rest of
+* the alias handling.
+*/
+function templateAliasBase(templateDir, conventions) {
+	const alias = conventions.alias.replace(/\/+$/, "");
+	const mapping = readTsconfigPaths(templateDir)?.[`${alias}/*`]?.[0];
+	if (mapping) return mapping.replace(/^\.\//, "").replace(/\/\*$/, "").replace(/\/+$/, "");
+	return conventions.kizloDir.startsWith("src/") ? "src" : "";
+}
+/**
+* Rewrite every template-alias import in a file to the project's chosen import style — the one place that
+* translates the maintainer's import preference into the user's. A template writes its cross-file imports
+* against its own alias (`@/layouts/Layout.astro`, `@/lib/kizlo/server`), rooted at the directory its
+* tsconfig maps the alias to (`base`). On apply each such specifier is resolved back to the imported
+* file's real location in the project (via {@link adaptTemplatePath}, so a relocated Kizlo dir is honored)
+* and re-emitted through the project's alias — or a relative import when the user wants no alias at all.
+* Only quoted specifiers that begin with the template alias are touched, so an unrelated string can't be
+* corrupted. Subsumes the server-entry import: it is simply the alias import that lands in the Kizlo dir.
+*/
+function rewriteAliasImports(body, fromDir, base, conventions, ctx) {
+	const alias = conventions.alias.replace(/\/+$/, "");
+	if (!alias) return body;
+	const pattern = new RegExp(`(["'])${escapeRegExp(alias)}/([^"']+)\\1`, "g");
+	return body.replace(pattern, (_match, quote, rest) => {
+		const targetRel = adaptTemplatePath(base ? `${base}/${rest}` : rest, conventions, ctx);
+		return `${quote}${ctx.importFrom(targetRel, fromDir)}${quote}`;
+	});
 }
 /**
 * Adapt a template path prefix (`src/app/...`, `src/lib/kizlo/...`) to the project's real directories.
@@ -256,19 +290,18 @@ function adaptTemplatePath(relPath, conventions, ctx) {
 }
 /**
 * Turn a `file` manifest entry into the {@link ScaffoldFile} init writes: read the template's real
-* file, rewrite its path prefix to the project's directories, and swap the server-entry import
-* specifier for the one resolved at the file's new location (tsconfig alias or relative). The swap is
-* surgical — it replaces the exact specifier the template uses, not a loose directory substring — so
-* an unrelated occurrence can't be corrupted. This is the job the old build-time extractor did; it
-* moves to runtime and stays as precise.
+* file, rewrite its path prefix to the project's directories, and retarget every template-alias import
+* (the server entry plus any sibling like Astro's `@/layouts/Layout.astro`) to the specifier resolved
+* at the file's new location — the project's alias or a relative import. Only the exact alias specifiers
+* the template uses are rewritten, not a loose directory substring, so an unrelated occurrence can't be
+* corrupted. This is the job the old build-time extractor did; it moves to runtime and stays as precise.
 */
 function adaptFile(templateDir, entry, conventions, ctx) {
 	const abs = path.join(templateDir, entry.path);
 	if (!fs.existsSync(abs)) throw new Error(`Template file "${entry.path}" is listed in the manifest but does not exist in the template.`);
 	const body = fs.readFileSync(abs, "utf8");
 	const relPath = adaptTemplatePath(entry.path, conventions, ctx);
-	const fromDir = path.posix.dirname(relPath);
-	const contents = body.split(serverImportSpecifier(conventions)).join(ctx.serverImport(fromDir));
+	const contents = rewriteAliasImports(body, path.posix.dirname(relPath), templateAliasBase(templateDir, conventions), conventions, ctx);
 	return {
 		label: ROLE_LABELS[entry.role] ?? entry.role,
 		relPath,
@@ -286,43 +319,12 @@ function resolvePatch(entry, conventions, ctx) {
 	return {
 		label: entry.label,
 		relPath,
+		mode: entry.mode,
 		imports,
-		exports: entry.exports
+		exports: entry.exports,
+		note: entry.note
 	};
 }
-const LAYOUT_FILE = /^layout\.(tsx|jsx|ts|js|mjs|cjs)$/;
-/** A root layout is the one that renders `<html>` — its identity, not its path. */
-const RENDERS_HTML = /<html[\s/>]/;
-/** Every file under `dir`, recursively (files only). Missing dir yields nothing. */
-function walk(dir) {
-	if (!fs.existsSync(dir)) return [];
-	const out = [];
-	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-		const full = path.join(dir, entry.name);
-		if (entry.isDirectory()) out.push(...walk(full));
-		else out.push(full);
-	}
-	return out;
-}
-/**
-* Resolve the root layout by identity, not path. Try the manifest hint first; if it exists and
-* renders `<html>`, use it. Otherwise scan the App Router directory for a layout that renders `<html>`
-* and use it only when there is exactly one. On zero, many, or an unreadable file, return undefined so
-* the caller prints the wiring for the user to place. Never guesses.
-*/
-function findRootLayout(cwd, appDir, hintRelPath) {
-	const hint = resolvePatchTargetPath(cwd, hintRelPath);
-	if (hint && rendersHtml(hint)) return hint;
-	const matches = walk(path.join(cwd, appDir)).filter((file) => LAYOUT_FILE.test(path.basename(file)) && rendersHtml(file));
-	return matches.length === 1 ? matches[0] : void 0;
-}
-function rendersHtml(file) {
-	try {
-		return RENDERS_HTML.test(fs.readFileSync(file, "utf8"));
-	} catch {
-		return false;
-	}
-}
 
 //#endregion
-export { adaptFile, changesFor, fileEntries, findRootLayout, isOlderVersion, minCliError, patchEntries, readManifest, renderNote, resolveDependencies, resolvePatch };
+export { adaptFile, changesFor, fileEntries, isOlderVersion, minCliError, patchEntries, readManifest, renderNote, resolveDependencies, resolvePatch };

package/dist/cli/utils.js

@@ -45,6 +45,30 @@ function readTsconfigPaths(cwd) {
 	}
 	return json.compilerOptions?.paths;
 }
+/**
+* The kizlo.config file names, in resolution order. Mirrors `CONFIG_FILES` in daemon/config — kept here
+* to avoid an import cycle, since daemon/config already depends on this module.
+*/
+const KIZLO_CONFIG_FILES = [
+	"kizlo.config.ts",
+	"kizlo.config.js",
+	"kizlo.config.mjs"
+];
+/**
+* The import alias a previous `kizlo init` recorded in kizlo.config — the persisted preference a re-run
+* reuses so it never asks again. Returns the prefix (`""` for the deliberate relative-imports choice),
+* or `undefined` when there's no config or it declares no `alias` at all (the choice was never made, so
+* the caller must prompt or default). A light text scan of the generated file, so setup never has to
+* import the TS config — or resolve `kizlo` — just to read one field back.
+*/
+function readPersistedAlias(cwd) {
+	for (const name of KIZLO_CONFIG_FILES) {
+		const file = path.join(cwd, name);
+		if (!fs.existsSync(file)) continue;
+		const match = fs.readFileSync(file, "utf8").match(/\balias\s*:\s*["']([^"']*)["']/);
+		return match ? match[1] : void 0;
+	}
+}
 function relativeImport(targetRel, fromDirRel) {
 	const rel = path.relative(fromDirRel, targetRel).split(path.sep).join("/");
 	return rel.startsWith(".") ? rel : `./${rel}`;
@@ -71,6 +95,14 @@ function detectImportAlias(cwd, targetRel) {
 	}
 }
 /**
+* Normalize an alias prefix to the canonical `@/` form — the way an import alias is actually written and
+* declared in tsconfig `paths` (`@/*`), so the persisted preference reads like the imports it produces.
+* A trailing slash is enforced (`@` → `@/`); empty stays empty, the recorded "relative imports" choice.
+*/
+function aliasWithSlash(alias) {
+	return alias ? `${alias.replace(/\/+$/, "")}/` : "";
+}
+/**
 * 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.
@@ -101,11 +133,62 @@ function getVersion() {
 	const pkgPath = path.resolve(here, "../../package.json");
 	return JSON.parse(fs.readFileSync(pkgPath, "utf8")).version;
 }
+/**
+* The manager a project pins via package.json's corepack `packageManager` field (e.g. `"pnpm@9.0.0"`
+* → `pnpm`). Declared intent that's present *before* the first install, so it's a reliable signal on a
+* freshly bootstrapped project that has no lockfile yet. Undefined when the field is absent, unparseable,
+* or names an unsupported manager.
+*/
+function packageManagerField(cwd) {
+	try {
+		const name = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8")).packageManager?.split("@")[0];
+		return name === "pnpm" || name === "yarn" || name === "bun" || name === "npm" ? name : void 0;
+	} catch {
+		return;
+	}
+}
+/**
+* The package manager a project uses, from evidence in the project itself — a lockfile (the strongest
+* signal, it reflects an actual install), else package.json's corepack `packageManager` field (declared
+* intent, present before the first install). Returns `undefined` when neither is present rather than
+* guessing: the invoking manager is unreliable (`npx` reports `npm` whatever the user really uses), and a
+* missing lockfile can just mean a freshly bootstrapped project in a monorepo. Callers that can't proceed
+* without one should ask the user (see `selectPackageManager`) instead of defaulting.
+*/
 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";
+	return packageManagerField(cwd);
+}
+/** The installed version of `pm`, from `pm --version` (e.g. `"9.0.0"`). Undefined when it can't be run. */
+function packageManagerVersion(pm) {
+	const result = spawnSync(pm, ["--version"], {
+		encoding: "utf8",
+		shell: process.platform === "win32"
+	});
+	if (result.error || result.status !== 0) return void 0;
+	const version = result.stdout.trim();
+	return version.length > 0 ? version : void 0;
+}
+/**
+* Record `pm` as package.json's corepack `packageManager` field so a later `detectPackageManager` settles on
+* it instead of asking again — the fix for a project that gave no signal and had to be prompted for. Stamps
+* the installed version (`pm --version`) to keep the field corepack-valid, dropping it only when the version
+* can't be read. Leaves an existing field untouched, preserves the file's indentation, and swallows any
+* read/write failure: persisting the choice is a convenience, not worth failing the command over.
+*/
+function persistPackageManagerField(cwd, pm) {
+	const pkgPath = path.join(cwd, "package.json");
+	try {
+		const raw = fs.readFileSync(pkgPath, "utf8");
+		const pkg = JSON.parse(raw);
+		if (pkg.packageManager) return;
+		const version = packageManagerVersion(pm);
+		pkg.packageManager = version ? `${pm}@${version}` : pm;
+		const indent = raw.match(/\n([ \t]+)/)?.[1] ?? "	";
+		fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, indent)}\n`);
+	} catch {}
 }
 /**
 * The package manager that invoked the current process, read from `npm_config_user_agent`
@@ -132,23 +215,40 @@ function isCommandAvailable(command) {
 function availablePackageManagers(order) {
 	return order.filter((pm) => isCommandAvailable(pm));
 }
-function addDependencyArgs(pm, pkg) {
-	if (pm === "npm") return [
+/**
+* The argv to add a single package with `pm`, e.g. `pnpm add kizlo`. `dev: true` installs it as a
+* dev dependency — npm spells that `--save-dev`, every other supported manager `--dev`.
+*/
+function addDependencyArgs(pm, pkg, opts = {}) {
+	const base = pm === "npm" ? [
 		"npm",
 		"install",
 		pkg
-	];
-	return [
+	] : [
 		pm,
 		"add",
 		pkg
 	];
+	if (!opts.dev) return base;
+	return [...base, pm === "npm" ? "--save-dev" : "--dev"];
 }
 /** The argv to install a project's dependencies with `pm` — every supported manager spells it `<pm> install`. */
 function installArgs(pm) {
 	return [pm, "install"];
 }
 /**
+* pnpm (v10+) and bun refuse to run dependencies' build/lifecycle scripts on install by default, leaving
+* those packages unbuilt — pnpm prints an `Ignored build scripts:` warning, bun a `Blocked N postinstall`
+* one. The install still exits 0, so nothing else flags it. Scan an install's captured output for that
+* warning and, when present, return the command that runs the blocked scripts (`pnpm approve-builds` /
+* `bun pm trust --all`) so the caller can surface it as a follow-up step. Undefined when the output shows
+* none, or the manager runs scripts on install anyway (npm, yarn) so there's nothing to approve.
+*/
+function approveBuildsCommand(pm, output) {
+	if (pm === "pnpm" && /ignored build scripts/i.test(output)) return "pnpm approve-builds";
+	if (pm === "bun" && /blocked \d+ postinstall/i.test(output)) return "bun pm trust --all";
+}
+/**
 * The argv to run a framework's `create-*` initializer through a package manager, e.g.
 * `pnpm create next-app@latest my-app --ts …`. The mechanics differ per manager: npm forwards
 * flags to the initializer only after a `--` separator, and `yarn create` resolves the latest
@@ -180,6 +280,15 @@ function frameworkCreateArgs(pm, initializer, name, flags) {
 		];
 	}
 }
+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;
+}
 /**
 * Async sibling of {@link runCommand}: runs a command without blocking the event loop, so a clack
 * spinner can keep animating while it works (a synchronous `spawnSync` would freeze it on the first
@@ -219,6 +328,40 @@ function runCommandCaptured(args, cwd) {
 		output: `${result.stdout ?? ""}${result.stderr ?? ""}`.trim()
 	};
 }
+/**
+* Async sibling of {@link runCommandCaptured}: captures a command's combined output without blocking the
+* event loop, so a clack spinner keeps animating while it runs (the synchronous `runCommandCaptured` would
+* freeze it on the first frame). Resolves whether it exited cleanly plus the trimmed stdout+stderr; a
+* spawn error (binary off PATH) resolves `{ ok: false, output: "" }`.
+*/
+function runCommandCapturedAsync(args, cwd) {
+	const [command, ...rest] = args;
+	if (!command) return Promise.resolve({
+		ok: false,
+		output: ""
+	});
+	return new Promise((resolve$1) => {
+		const child = spawn(command, rest, {
+			cwd,
+			shell: process.platform === "win32"
+		});
+		let output = "";
+		child.stdout?.on("data", (chunk) => {
+			output += chunk;
+		});
+		child.stderr?.on("data", (chunk) => {
+			output += chunk;
+		});
+		child.on("error", () => resolve$1({
+			ok: false,
+			output: ""
+		}));
+		child.on("close", (code) => resolve$1({
+			ok: code === 0,
+			output: output.trim()
+		}));
+	});
+}
 function writeFileIfAbsent(filePath, contents) {
 	if (fs.existsSync(filePath)) return false;
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
@@ -333,6 +476,42 @@ function mergeEnv(existing, values, overwriteKeys, groups) {
 		kept
 	};
 }
+/**
+* Whether `dir` already sits inside a git work tree — true when the framework CLI ran `git init`, or
+* when scaffolding into a subfolder of an existing repo (e.g. a monorepo). Used to skip offering
+* `git init` where a repo is already present rather than nesting one. A missing `git` binary (spawn
+* error) reads as "not a repo".
+*/
+function isGitRepository(dir) {
+	const result = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
+		cwd: dir,
+		stdio: "ignore",
+		shell: process.platform === "win32"
+	});
+	return !result.error && result.status === 0;
+}
+/**
+* Initialize a git repository in `dir` with an initial commit. Best-effort: returns whether the repo
+* was created (`git init` succeeded). The commit is attempted but not required — it needs a configured
+* `user.name`/`user.email` a bare machine may lack, and a repo with staged-but-uncommitted files is
+* still a usable starting point. Returns false when `git` isn't installed.
+*/
+function initGitRepository(dir) {
+	if (!isCommandAvailable("git")) return false;
+	if (!runCommand(["git", "init"], dir, "ignore")) return false;
+	runCommand([
+		"git",
+		"add",
+		"-A"
+	], dir, "ignore");
+	runCommand([
+		"git",
+		"commit",
+		"-m",
+		"Initial commit"
+	], dir, "ignore");
+	return true;
+}
 function ensureGitignored(cwd, entry) {
 	const gitignorePath = path.join(cwd, ".gitignore");
 	const existed = fs.existsSync(gitignorePath);
@@ -376,4 +555,4 @@ function groupDefault(subCommandNames, run) {
 }
 
 //#endregion
-export { DEFAULT_ENV_KEYS, 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, aliasWithSlash, approveBuildsCommand, availablePackageManagers, detectImportAlias, detectInvokingPackageManager, detectPackageManager, ensureGitignored, envGroups, envKeysPresent, frameworkCreateArgs, getVersion, groupDefault, initGitRepository, installArgs, isCommandAvailable, isGitRepository, loadEnvFiles, mergeEnv, persistPackageManagerField, pickStackPort, readPersistedAlias, readTsconfigPaths, resolveModuleImport, runCommandAsync, runCommandCaptured, runCommandCapturedAsync, withSpinner, writeFileIfAbsent };

package/dist/cli/wp/stack.js

@@ -8,7 +8,7 @@ function localMounts(fixtures) {
 	return fixtures.flatMap((fixture) => fixture.plugins ?? []).filter(isLocalPlugin).map((plugin) => plugin.path);
 }
 /**
-* The test stack: the base compose file under a `<name>-test` project, plus a generated
+* The test stack: the base compose file under a `kizlo-<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 local WordPress.
 */
@@ -37,7 +37,7 @@ function detectHostUser() {
 }
 /**
 * 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
+* `kizlo-<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) {

package/dist/config.d.ts

@@ -63,12 +63,13 @@ interface KizloGlobalConfig {
    */
   dir?: string;
   /**
-   * Import alias prefix for generated imports (e.g. `@`). Detected from
-   * tsconfig at init; omit (or empty) to use relative imports.
+   * Import alias prefix for generated imports (e.g. `@`). Recorded by `kizlo init`
+   * from your `--alias` flag or its prompt, so later runs reuse it instead of asking
+   * again; an empty string (`""`) is the recorded choice to use relative imports.
    */
   alias?: string;
   /**
-   * Base name for the local Docker stacks (`<name>-dev`, `<name>-test`). Defaults
+   * Base name for the local Docker stacks (`kizlo-<name>-dev`, `kizlo-<name>-test`). Defaults
    * to the sanitized `package.json` name, falling back to the config dir basename.
    */
   name?: string;

package/dist/context.js

@@ -6,7 +6,7 @@ import { WordPressService } from "./wordpress/service.js";
 import { EmailService } from "./email/service.js";
 import { SettingsService } from "./settings/service.js";
 import { PLUGIN_VERSION_HEADER, base64Decode, isPluginVersionSupported, pluginUpdateMessage, tryCatchSync } from "@kizlo/shared";
-import { serialize } from "cookie";
+import { stringifySetCookie } from "cookie";
 
 //#region src/context.ts
 var Context = class {
@@ -93,13 +93,19 @@ var Context = class {
 			},
 			setAll: async (cookies) => {
 				cookies.forEach((cookie) => {
-					headers.append("Set-Cookie", serialize(cookie.name, cookie.value, cookie.options));
+					headers.append("Set-Cookie", stringifySetCookie({
+						...cookie.options,
+						name: cookie.name,
+						value: cookie.value
+					}));
 				});
 			},
 			deleteAll: async (cookies) => {
 				cookies.forEach((cookie) => {
-					headers.append("Set-Cookie", serialize(cookie.name, "", {
+					headers.append("Set-Cookie", stringifySetCookie({
 						...cookie.options,
+						name: cookie.name,
+						value: "",
 						maxAge: 0,
 						expires: /* @__PURE__ */ new Date(0)
 					}));

package/dist/integrations/nextjs/metadata.d.ts

@@ -13,6 +13,12 @@ declare function createRootMetadata(client: S2SClient<[]>): () => Promise<Metada
  * is set, both are emitted with `prefers-color-scheme` media queries.
  */
 declare function createRootViewport(client: S2SClient<[]>): () => Promise<Viewport>;
+/**
+ * Home `generateMetadata` for `app/page.tsx`, resolving the homepage SEO head from WordPress.
+ * A factory (rather than the inline call the `create` template shows) so `init` can wire it into
+ * an existing home page as a single `export const generateMetadata = createHomeMetadata(client)`.
+ */
+declare function createHomeMetadata(client: S2SClient<[]>): () => Promise<Metadata>;
 declare function createPageMetadata(head: SeoHead): Metadata;
 //#endregion
-export { createPageMetadata, createRootMetadata, createRootViewport };
+export { createHomeMetadata, createPageMetadata, createRootMetadata, createRootViewport };

package/dist/integrations/nextjs/metadata.js

@@ -49,6 +49,17 @@ function toNextIcon(icon) {
 		sizes: icon.sizes
 	};
 }
+/**
+* Home `generateMetadata` for `app/page.tsx`, resolving the homepage SEO head from WordPress.
+* A factory (rather than the inline call the `create` template shows) so `init` can wire it into
+* an existing home page as a single `export const generateMetadata = createHomeMetadata(client)`.
+*/
+function createHomeMetadata(client) {
+	return async function generateMetadata() {
+		const { head } = await client.seo.homepage.call();
+		return createPageMetadata(head);
+	};
+}
 function createPageMetadata(head) {
 	return {
 		title: { absolute: head.title },
@@ -90,4 +101,4 @@ function createPageMetadata(head) {
 }
 
 //#endregion
-export { createPageMetadata, createRootMetadata, createRootViewport };
+export { createHomeMetadata, createPageMetadata, createRootMetadata, createRootViewport };

package/dist/nextjs/server.d.ts

@@ -4,8 +4,8 @@ import { createSitemapRedirectRoute } from "../seo/sitemap.js";
 import { NextRevalidateOptions, RevalidatePathFn, RevalidateTagFn, RevalidateTarget, nextRevalidation } from "../integrations/nextjs/revalidate.js";
 import { KizloServerOptions, createKizlo } from "../integrations/nextjs/kizlo.server.js";
 import { MANIFEST_CACHE_TAG, createManifestRoute } from "../integrations/nextjs/manifest.js";
-import { createPageMetadata, createRootMetadata, createRootViewport } from "../integrations/nextjs/metadata.js";
+import { createHomeMetadata, createPageMetadata, createRootMetadata, createRootViewport } from "../integrations/nextjs/metadata.js";
 import { ROBOTS_CACHE_TAG, createRobotsRoute } from "../integrations/nextjs/robots.js";
 import { SITEMAP_CACHE_TAG, SITEMAP_ROUTE, createSitemapRoute } from "../integrations/nextjs/sitemap.js";
 import { createCachedTextRoute, createNextCookiesInterface, getServerBaseUrl } from "../integrations/nextjs/utils.js";
-export { KizloServerOptions, MANIFEST_CACHE_TAG, NextRevalidateOptions, ROBOTS_CACHE_TAG, RevalidatePathFn, RevalidateTagFn, RevalidateTarget, SITEMAP_CACHE_TAG, SITEMAP_ROUTE, WEB_MANIFEST_ROUTE, createCachedTextRoute, createKizlo, createManifestRoute, createNextCookiesInterface, createPageMetadata, createRobotsRoute, createRootMetadata, createRootViewport, createSitemapRedirectRoute, createSitemapRoute, getServerBaseUrl, nextRevalidation, renderJsonLd };
+export { KizloServerOptions, MANIFEST_CACHE_TAG, NextRevalidateOptions, ROBOTS_CACHE_TAG, RevalidatePathFn, RevalidateTagFn, RevalidateTarget, SITEMAP_CACHE_TAG, SITEMAP_ROUTE, WEB_MANIFEST_ROUTE, createCachedTextRoute, createHomeMetadata, createKizlo, createManifestRoute, createNextCookiesInterface, createPageMetadata, createRobotsRoute, createRootMetadata, createRootViewport, createSitemapRedirectRoute, createSitemapRoute, getServerBaseUrl, nextRevalidation, renderJsonLd };

package/dist/nextjs/server.js

@@ -7,6 +7,6 @@ import { SITEMAP_CACHE_TAG, SITEMAP_ROUTE, createSitemapRoute } from "../integra
 import { nextRevalidation } from "../integrations/nextjs/revalidate.js";
 import { createKizlo } from "../integrations/nextjs/kizlo.server.js";
 import { MANIFEST_CACHE_TAG, createManifestRoute } from "../integrations/nextjs/manifest.js";
-import { createPageMetadata, createRootMetadata, createRootViewport } from "../integrations/nextjs/metadata.js";
+import { createHomeMetadata, createPageMetadata, createRootMetadata, createRootViewport } from "../integrations/nextjs/metadata.js";
 
-export { MANIFEST_CACHE_TAG, ROBOTS_CACHE_TAG, SITEMAP_CACHE_TAG, SITEMAP_ROUTE, WEB_MANIFEST_ROUTE, createCachedTextRoute, createKizlo, createManifestRoute, createNextCookiesInterface, createPageMetadata, createRobotsRoute, createRootMetadata, createRootViewport, createSitemapRedirectRoute, createSitemapRoute, getServerBaseUrl, nextRevalidation, renderJsonLd };
+export { MANIFEST_CACHE_TAG, ROBOTS_CACHE_TAG, SITEMAP_CACHE_TAG, SITEMAP_ROUTE, WEB_MANIFEST_ROUTE, createCachedTextRoute, createHomeMetadata, createKizlo, createManifestRoute, createNextCookiesInterface, createPageMetadata, createRobotsRoute, createRootMetadata, createRootViewport, createSitemapRedirectRoute, createSitemapRoute, getServerBaseUrl, nextRevalidation, renderJsonLd };

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.12.0";
+var version = "0.13.0";
 
 //#endregion
 export { version };

package/dist/router.d.ts

@@ -179,7 +179,7 @@ declare const ROUTER_MAP: {
         include?: string | number | (string | number)[] | undefined;
         offset?: string | number | undefined;
         order?: "asc" | "desc" | undefined;
-        orderby?: "date" | "id" | "slug" | "parent" | "title" | "author" | "include" | "modified" | "relevance" | "include_slugs" | undefined;
+        orderby?: "id" | "date" | "slug" | "parent" | "title" | "author" | "include" | "modified" | "relevance" | "include_slugs" | undefined;
         searchColumns?: ("post_title" | "post_content" | "post_excerpt")[] | undefined;
         slug?: string | string[] | undefined;
         taxRelation?: "AND" | "OR" | undefined;
@@ -507,7 +507,7 @@ declare const ROUTER_MAP: {
         include?: string | number | (string | number)[] | undefined;
         offset?: string | number | undefined;
         order?: "asc" | "desc" | undefined;
-        orderby?: "date" | "id" | "slug" | "parent" | "title" | "author" | "include" | "modified" | "relevance" | "include_slugs" | "menu_order" | undefined;
+        orderby?: "id" | "date" | "slug" | "parent" | "title" | "author" | "include" | "modified" | "relevance" | "include_slugs" | "menu_order" | undefined;
         searchColumns?: ("post_title" | "post_content" | "post_excerpt")[] | undefined;
         slug?: string | string[] | undefined;
         parent?: string | number | (string | number)[] | undefined;
@@ -1186,7 +1186,7 @@ declare const ROUTER_MAP: {
           include?: string | number | (string | number)[] | undefined;
           offset?: string | number | undefined;
           order?: "asc" | "desc" | undefined;
-          orderby?: "date" | "id" | "slug" | "parent" | "title" | "author" | "include" | "relevance" | "include_slugs" | "menu_order" | undefined;
+          orderby?: "id" | "date" | "slug" | "parent" | "title" | "author" | "include" | "relevance" | "include_slugs" | "menu_order" | undefined;
           searchColumns?: ("post_title" | "post_content" | "post_excerpt")[] | undefined;
           slug?: string | string[] | undefined;
           taxRelation?: "AND" | "OR" | undefined;
@@ -1265,7 +1265,7 @@ declare const ROUTER_MAP: {
           include?: string | number | (string | number)[] | undefined;
           offset?: string | number | undefined;
           order?: "asc" | "desc" | undefined;
-          orderby?: "date" | "id" | "slug" | "parent" | "title" | "author" | "include" | "relevance" | "include_slugs" | "menu_order" | undefined;
+          orderby?: "id" | "date" | "slug" | "parent" | "title" | "author" | "include" | "relevance" | "include_slugs" | "menu_order" | undefined;
           searchColumns?: ("post_title" | "post_content" | "post_excerpt")[] | undefined;
           slug?: string | string[] | undefined;
           taxRelation?: "AND" | "OR" | undefined;
@@ -1414,7 +1414,7 @@ declare const ROUTER_MAP: {
         include?: string | number | (string | number)[] | undefined;
         offset?: string | number | undefined;
         order?: "asc" | "desc" | undefined;
-        orderby?: "date" | "id" | "parent" | "post" | "include" | undefined;
+        orderby?: "id" | "date" | "parent" | "post" | "include" | undefined;
         parent?: string | number | (string | number)[] | undefined;
         parentExclude?: string | number | (string | number)[] | undefined;
         post?: string | number | (string | number)[] | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kizlo",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "type": "module",
   "description": "A headless WordPress framework for TypeScript.",
   "keywords": [
@@ -97,7 +97,7 @@
     "chokidar": "^5.0.0",
     "citty": "^0.1.6",
     "consola": "^3.2.3",
-    "cookie": "^1.0.2",
+    "cookie": "^2.0.1",
     "get-port": "^7.2.0",
     "giget": "^3.0.0",
     "jiti": "^2.7.0",