kizlo 0.12.1 → 0.13.0

package/dist/cli/commands/_setup.js

@@ -1,6 +1,6 @@
 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_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";
@@ -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,
@@ -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,4 +1,4 @@
-import { resolveModuleImport, writeFileIfAbsent } from "../utils.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";
@@ -8,32 +8,37 @@ 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
 	};
 }
@@ -85,6 +90,11 @@ function applyProjectPatches(cwd, patches, conventions, scaffold) {
 	const manualSteps = [];
 	for (const entry of patches) {
 		const resolved = resolvePatch(entry, conventions, scaffold);
+		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);
@@ -107,8 +117,19 @@ function applyProjectPatches(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} (${resolved.relPath})`);
+	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 { applyProjectPatches, buildScaffoldContext, kizloConfigTemplate, reportScaffold, scaffoldFile, writeGeneratedContract };
+export { applyProjectPatches, buildScaffoldContext, kizloConfigTemplate, printManualStep, reportScaffold, scaffoldFile, writeGeneratedContract };

package/dist/cli/commands/create.js

@@ -1,7 +1,7 @@
-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 { 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";
@@ -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
@@ -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 { applyProjectPatches, 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?",
@@ -284,7 +316,7 @@ const init = defineCommand({
 			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

@@ -130,7 +130,7 @@ async function resolveTestConfig(cwd) {
 		portExplicit: test.port !== void 0,
 		fixtures: test.fixtures ?? [],
 		credentialsPath: credentialsPath(cwd),
-		packageManager: test.packageManager ?? detectPackageManager(configDir)
+		packageManager: test.packageManager ?? detectPackageManager(configDir) ?? "npm"
 	};
 }
 /**

package/dist/cli/presets/patch.js

@@ -143,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,4 +1,4 @@
-import { getVersion } from "../utils.js";
+import { getVersion, readTsconfigPaths } from "../utils.js";
 import z from "zod/v4";
 import path from "node:path";
 import fs from "node:fs";
@@ -34,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(),
@@ -52,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(),
@@ -238,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.
@@ -255,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,
@@ -285,8 +319,10 @@ function resolvePatch(entry, conventions, ctx) {
 	return {
 		label: entry.label,
 		relPath,
+		mode: entry.mode,
 		imports,
-		exports: entry.exports
+		exports: entry.exports,
+		note: entry.note
 	};
 }
 

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/config.d.ts

@@ -63,8 +63,9 @@ 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;
   /**

package/dist/package.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kizlo",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "type": "module",
   "description": "A headless WordPress framework for TypeScript.",
   "keywords": [