kizlo 0.11.0 → 0.12.1

package/dist/astro/server.d.ts

@@ -0,0 +1,9 @@
+import { WEB_MANIFEST_ROUTE } from "../brand/manifest.js";
+import { renderJsonLd } from "../seo/utils.js";
+import { KizloServerOptions, createKizlo } from "../integrations/astro/kizlo.server.js";
+import { AstroRoute, AstroRouteContext, getServerBaseUrl } from "../integrations/astro/utils.js";
+import { createManifestRoute } from "../integrations/astro/manifest.js";
+import { PageHead, RootHead, ThemeColor, resolvePageHead, resolveRootHead } from "../integrations/astro/metadata.js";
+import { createRobotsRoute } from "../integrations/astro/robots.js";
+import { createSitemapRedirectRoute, createSitemapRoute } from "../integrations/astro/sitemap.js";
+export { AstroRoute, AstroRouteContext, KizloServerOptions, PageHead, RootHead, ThemeColor, WEB_MANIFEST_ROUTE, createKizlo, createManifestRoute, createRobotsRoute, createSitemapRedirectRoute, createSitemapRoute, getServerBaseUrl, renderJsonLd, resolvePageHead, resolveRootHead };

package/dist/astro/server.js

@@ -0,0 +1,10 @@
+import { WEB_MANIFEST_ROUTE } from "../brand/manifest.js";
+import { renderJsonLd } from "../seo/utils.js";
+import { getServerBaseUrl } from "../integrations/astro/utils.js";
+import { createKizlo } from "../integrations/astro/kizlo.server.js";
+import { createManifestRoute } from "../integrations/astro/manifest.js";
+import { resolvePageHead, resolveRootHead } from "../integrations/astro/metadata.js";
+import { createRobotsRoute } from "../integrations/astro/robots.js";
+import { createSitemapRedirectRoute, createSitemapRoute } from "../integrations/astro/sitemap.js";
+
+export { WEB_MANIFEST_ROUTE, createKizlo, createManifestRoute, createRobotsRoute, createSitemapRedirectRoute, createSitemapRoute, getServerBaseUrl, renderJsonLd, resolvePageHead, resolveRootHead };

package/dist/astro.d.ts

@@ -0,0 +1,2 @@
+import { KizloClientOptions, createKizloClient } from "./integrations/astro/kizlo.client.js";
+export { KizloClientOptions, createKizloClient };

package/dist/astro.js

@@ -0,0 +1,3 @@
+import { createKizloClient } from "./integrations/astro/kizlo.client.js";
+
+export { createKizloClient };

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_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";
@@ -17,13 +17,13 @@ import getPort, { portNumbers } from "get-port";
 
 //#region src/cli/commands/_setup.ts
 /**
-* The resolved `.env` key names the scaffold writes: the template's declared `env` when it has one,
-* else the preset's built-in `envKeys` (the generic `base` preset), else the {@link DEFAULT_ENV_KEYS}
-* fallback for an in-repo template before the first stamped release. Threaded into `managedEnv`,
-* `writeEnv`, and `collectConnectionFromEnv` so the scaffold writes the names the pinned runtime reads.
+* The resolved `.env` key names the scaffold writes: the template's declared `env` when it has one, else
+* the {@link DEFAULT_ENV_KEYS} fallback — for an in-repo template before the first stamped release, and
+* for the base no-template fallback (which has no manifest). Threaded into `managedEnv`, `writeEnv`, and
+* `collectConnectionFromEnv` so the scaffold writes the names the pinned runtime reads.
 */
-function resolveEnvKeys(preset, manifest) {
-	return manifest?.env ?? preset.envKeys ?? DEFAULT_ENV_KEYS;
+function resolveEnvKeys(manifest) {
+	return manifest?.env ?? DEFAULT_ENV_KEYS;
 }
 /** Remote connection keys — what a real deploy needs, and what `.env.example` always lists. */
 function remoteKeys(envKeys) {
@@ -135,11 +135,11 @@ function pickAppPort() {
 * `create` scaffolds a brand-new app that has no public URL yet, so it defaults to the local dev
 * origin and lets the user fill in production later.
 */
-async function collectConnectionInteractively(preset, opts = {}) {
+async function collectConnectionInteractively(apiPath, opts = {}) {
 	let siteUrl;
 	let baseUrl;
 	if (opts.baseUrl !== void 0) baseUrl = opts.baseUrl;
-	else if (preset.apiPath) baseUrl = orCancel(await p.text({
+	else if (apiPath) baseUrl = orCancel(await p.text({
 		message: "Public app URL",
 		placeholder: "https://your-app.com",
 		validate: validate(urlString)
@@ -238,7 +238,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,

package/dist/cli/commands/_wiring.js

@@ -1,8 +1,8 @@
 import { resolveModuleImport, writeFileIfAbsent } from "../utils.js";
-import { applyPatchToSource, patchChanged, renderPatchCode } from "../presets/patch.js";
-import { findRootLayout, resolvePatch } from "../presets/template.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";
@@ -73,17 +73,19 @@ 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);
+		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 +107,8 @@ 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) p.note(renderPatchCode(resolved), `Add these to your ${resolved.label} (${resolved.relPath})`);
 }
 
 //#endregion
-export { applyLayoutPatches, buildScaffoldContext, kizloConfigTemplate, reportScaffold, scaffoldFile, writeGeneratedContract };
+export { applyProjectPatches, buildScaffoldContext, kizloConfigTemplate, reportScaffold, scaffoldFile, writeGeneratedContract };

package/dist/cli/commands/create.js

@@ -1,9 +1,8 @@
 import { availablePackageManagers, detectInvokingPackageManager, ensureGitignored, frameworkCreateArgs, installArgs, runCommandAsync, runCommandCaptured } from "../utils.js";
-import { getPreset } from "../presets/index.js";
-import { fetchTemplate } from "../presets/source.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 { applyProjectPatches, buildScaffoldContext, kizloConfigTemplate, reportScaffold, scaffoldFile, writeGeneratedContract } from "./_wiring.js";
 import z from "zod/v4";
 import path from "node:path";
 import fs from "node:fs";
@@ -11,15 +10,30 @@ import { defineCommand } from "citty";
 import * as p from "@clack/prompts";
 
 //#region src/cli/commands/create.ts
+/** The final path segment of a project name — the app folder itself; everything before it is where it lands. */
+function folderSegment(value) {
+	const segments = value.replace(/\\/g, "/").split("/").filter(Boolean);
+	return segments[segments.length - 1] ?? "";
+}
 /**
-* The templates `create` can scaffold from. Each id is both the `templates/<id>` folder and the
-* preset that drives its WordPress setup and framework bootstrap.
+* Tidy the entered name/path for both the target dir and the display: trim, drop a leading `./`, and drop a
+* trailing separator, so `cd`, the spinner, and the warning lines read as `templates/my-app`, not
+* `./templates/my-app/`. Preserves `../` and absolute paths (only a leading `./` is redundant).
 */
-const TEMPLATES = ["nextjs"];
-function isTemplate(value) {
-	return TEMPLATES.includes(value);
+function normalizeProjectName(value) {
+	return value.trim().replace(/^\.\/+/, "").replace(/[/\\]+$/, "");
 }
-const projectName = validate(z.string().trim().min(1, "Required").refine((value) => !value.startsWith(".") && !value.includes("/") && !value.includes("\\"), "Enter a folder name (letters, numbers, dashes)"));
+/**
+* A project name may be a bare folder (`my-app`) or a path to scaffold somewhere other than the current
+* dir — relative (`apps/my-app`, `../my-app`) or absolute (`/srv/my-app`). Only the last segment is the
+* app folder, so that's what's validated as a name; the parent dirs (which may not exist yet) are created
+* by the framework's own CLI. `.`/`..` as the final segment, or a name with no real segment, is rejected.
+*/
+const projectNameSchema = z.string().trim().min(1, "Required").refine((value) => {
+	const base = folderSegment(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",
@@ -37,17 +51,25 @@ function recordDependencies(dir, manifest) {
 	const pkgPath = path.join(dir, "package.json");
 	const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
 	const { dependencies, devDependencies } = resolveDependencies(manifest);
-	pkg.dependencies = {
+	pkg.dependencies = sortDependencies({
 		...pkg.dependencies,
 		...dependencies
-	};
-	if (Object.keys(devDependencies).length) pkg.devDependencies = {
+	});
+	if (Object.keys(devDependencies).length) pkg.devDependencies = sortDependencies({
 		...pkg.devDependencies,
 		...devDependencies
-	};
+	});
 	fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, "	")}\n`);
 }
 /**
+* Alphabetize a dependency map by package name. The framework CLI writes its deps sorted, but merging
+* Kizlo's pins on top appends them out of order — sherif flags unsorted dependency keys, so re-sort the
+* whole map before writing.
+*/
+function sortDependencies(deps) {
+	return Object.fromEntries(Object.entries(deps).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+}
+/**
 * The argv `create` runs to bootstrap a fresh base app with the framework's own official CLI, built
 * from the template manifest's `bootstrap` (initializer + flags) — the template is the single source
 * of truth for the framework. The CLI owns only the package-manager mechanics: {@link frameworkCreateArgs}
@@ -66,7 +88,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.
@@ -93,7 +115,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: {
@@ -104,54 +126,75 @@ const create = defineCommand({
 		template: {
 			type: "positional",
 			required: false,
-			description: `Template to scaffold from (${TEMPLATES.join(", ")})`
+			description: "Template to scaffold from (discovered from the registry)"
 		},
 		name: {
 			type: "positional",
 			required: false,
-			description: "Project folder to create"
+			description: "Project folder to create — a bare name or a path (e.g. apps/my-app, ../my-app, /srv/my-app)"
+		},
+		source: {
+			type: "string",
+			description: "Where to scaffold from — a local dir or giget source, either a registry of templates or a single template (default: Kizlo's GitHub templates)"
 		}
 	},
 	async run({ args }) {
 		const cwd = process.cwd();
 		p.intro(`Let's create a new Kizlo application`);
+		const registry = resolveRegistry(args.source ? String(args.source) : void 0);
+		let fetchedRegistry;
+		try {
+			fetchedRegistry = await fetchRegistry(registry);
+		} catch (error) {
+			p.cancel(error instanceof Error ? error.message : String(error));
+			process.exit(1);
+		}
+		const templates = listTemplates(fetchedRegistry.dir);
+		if (templates.length === 0) {
+			fetchedRegistry.cleanup();
+			p.cancel(`No templates found in the registry (${registry.source}). Each template needs a template.json.`);
+			process.exit(1);
+		}
+		const cancelFrom = (message) => {
+			fetchedRegistry.cleanup();
+			p.cancel(message);
+			process.exit(1);
+		};
 		const requested = args.template;
-		let template;
+		let selected;
 		if (requested) {
-			if (!isTemplate(requested)) {
-				p.cancel(`Unknown template "${requested}". Available: ${TEMPLATES.join(", ")}`);
-				process.exit(1);
-			}
-			template = requested;
-		} else template = orCancel(await p.select({
-			message: "Template",
-			options: TEMPLATES.map((id) => ({
-				value: id,
-				label: id
-			}))
-		}));
-		const name = args.name ? String(args.name).trim() : orCancel(await p.text({
-			message: "Project name",
+			selected = templates.find((entry) => entry.id === requested);
+			if (!selected) return cancelFrom(`Unknown template "${requested}". Available: ${templates.map((entry) => entry.id).join(", ")}`);
+		} else {
+			const id = orCancel(await p.select({
+				message: "Template",
+				options: templates.map((entry) => ({
+					value: entry.id,
+					label: entry.label
+				}))
+			}));
+			selected = templates.find((entry) => entry.id === id);
+		}
+		if (!selected) return cancelFrom("No template selected.");
+		const template = selected.id;
+		const templateDir = selected.dir;
+		const label = selected.label;
+		const fail = cancelFrom;
+		const manifest = readManifest(templateDir);
+		const minErr = minCliError(manifest);
+		if (minErr) return fail(minErr);
+		const name = normalizeProjectName(args.name ? String(args.name) : orCancel(await p.text({
+			message: "What is your project named?",
 			placeholder: "my-app",
 			validate: projectName
-		}));
-		if (!args.name) {
-			const check = projectName(name);
-			if (check) {
-				p.cancel(check);
-				process.exit(1);
-			}
-		}
-		const dir = path.resolve(cwd, name);
-		if (fs.existsSync(dir)) {
-			p.cancel(`${name} already exists — pick a different name or remove it.`);
-			process.exit(1);
-		}
-		const preset = getPreset(template);
-		if (!preset) {
-			p.cancel(`No preset for template "${template}".`);
+		})));
+		const invalid = projectName(name);
+		if (invalid) {
+			p.cancel(invalid);
 			process.exit(1);
 		}
+		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];
@@ -163,45 +206,32 @@ const create = defineCommand({
 			})),
 			initialValue: defaultPm
 		}));
-		const conn = await collectConnectionInteractively(preset, { baseUrl: `http://localhost:${await pickAppPort()}` });
-		if (preset.apiPath && conn.baseUrl) conn.baseUrl = withApiPath(conn.baseUrl, preset.apiPath);
+		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({
 			message: "Add examples?",
 			initialValue: true
 		}));
-		const fetched = await fetchTemplate(template);
-		const fail = (message) => {
-			fetched.cleanup();
-			p.cancel(message);
-			process.exit(1);
-		};
-		const manifest = readManifest(fetched.dir);
-		const minErr = minCliError(manifest);
-		if (minErr) fail(minErr);
 		const bootstrap = bootstrapArgs(manifest, pm, name);
-		if (!bootstrap) {
-			fetched.cleanup();
-			p.cancel(`Template "${template}" can't be scaffolded — its manifest declares no framework bootstrap.`);
-			process.exit(1);
-		}
+		if (!bootstrap) return fail(`Template "${template}" can't be scaffolded — its manifest declares no framework bootstrap.`);
 		const s = p.spinner();
-		s.start(`Creating ${name} with the ${preset.label} CLI`);
+		s.start(`Creating ${name} with the ${label} CLI`);
 		const scaffold = runCommandCaptured(bootstrap, cwd);
-		s.stop(scaffold.ok ? `Created ${name} with the ${preset.label} CLI` : `${preset.label} setup failed`);
+		s.stop(scaffold.ok ? `Created ${name} with the ${label} CLI` : `${label} setup failed`);
 		if (!scaffold.ok) {
 			if (scaffold.output) p.log.error(scaffold.output);
-			fail(`${preset.label} setup failed — see the output above and try again.`);
+			fail(`${label} setup failed — see the output above and try again.`);
 		}
-		const exampleTemplate = readEnvExample(fetched.dir);
+		const exampleTemplate = readEnvExample(templateDir);
 		try {
-			await applyManifestWiring(dir, fetched.dir, manifest, {
+			await applyManifestWiring(dir, templateDir, manifest, {
 				includeExamples,
 				localDev: conn.mode === "local"
 			});
 		} catch (error) {
 			fail(error instanceof Error ? error.message : String(error));
 		}
-		fetched.cleanup();
+		fetchedRegistry.cleanup();
 		let depsInstalled = false;
 		if (orCancel(await p.confirm({
 			message: "Install dependencies now?",
@@ -214,7 +244,7 @@ const create = defineCommand({
 			if (!depsInstalled) p.log.warn(`Install them yourself: cd ${name} && ${installArgs(pm).join(" ")}`);
 		}
 		await setupLocalWordPress(dir, conn);
-		await writeEnv(dir, resolveEnvKeys(preset, manifest), conn, {
+		await writeEnv(dir, resolveEnvKeys(manifest), conn, {
 			force: true,
 			yes: false,
 			exampleTemplate

package/dist/cli/commands/generate.js

@@ -15,6 +15,10 @@ const generate = defineCommand({
 	} },
 	async run({ args }) {
 		const cfg = await resolveConfig(process.cwd(), { dir: args.dir });
+		if (!cfg) {
+			log.info("No Kizlo server directory configured, nothing to generate. Set `dir` in kizlo.config.ts or pass --dir.");
+			return;
+		}
 		let ok;
 		try {
 			ok = await generateOnce(cfg);