kizlo 0.11.0 → 0.12.1

package/dist/cli/commands/init.js

@@ -1,9 +1,8 @@
 import { addDependencyArgs, detectImportAlias, detectPackageManager, ensureGitignored, getVersion, loadEnvFiles, runCommandAsync } from "../utils.js";
-import { PRESETS, detectPreset, getPreset } from "../presets/index.js";
-import { fetchTemplate } from "../presets/source.js";
-import { adaptFile, changesFor, fileEntries, isOlderVersion, minCliError, patchEntries, readManifest, resolveDependencies } from "../presets/template.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 { applyProjectPatches, buildScaffoldContext, kizloConfigTemplate, reportScaffold, scaffoldFile, writeGeneratedContract } from "./_wiring.js";
 import path from "node:path";
 import fs from "node:fs";
 import { defineCommand } from "citty";
@@ -25,7 +24,20 @@ function sameOrigin(a, b) {
 		return false;
 	}
 }
-function detectAppDir(cwd, hasSrcDir) {
+/**
+* The framework's route directory in the user's project. When a template is present its
+* `conventions.appDir` (e.g. `src/app` for Next, `src/pages` for Astro) is the expected layout; we
+* probe that path and its no-`src` variant so a project that keeps routes at the top level is still
+* found, falling back to whether the project has a `src` dir. With no known template appDir we keep the
+* App Router default.
+*/
+function detectAppDir(cwd, hasSrcDir, templateAppDir) {
+	if (templateAppDir) {
+		const withoutSrc = templateAppDir.replace(/^src\//, "");
+		if (fs.existsSync(path.join(cwd, templateAppDir))) return templateAppDir;
+		if (fs.existsSync(path.join(cwd, withoutSrc))) return withoutSrc;
+		return hasSrcDir ? templateAppDir : withoutSrc;
+	}
 	if (fs.existsSync(path.join(cwd, "src", "app"))) return "src/app";
 	if (fs.existsSync(path.join(cwd, "app"))) return "app";
 	return hasSrcDir ? "src/app" : "app";
@@ -37,7 +49,7 @@ async function collectInteractively(ctx) {
 		validate: validate(dirPath)
 	}));
 	let alias = "";
-	if (ctx.preset.apiPath) {
+	if (ctx.apiPath) {
 		const serverDir = path.join(dir.replace(/^\.\//, "").replace(/\/+$/, ""), "server");
 		const detected = detectImportAlias(ctx.cwd, serverDir)?.prefix;
 		alias = orCancel(await p.text({
@@ -47,7 +59,7 @@ async function collectInteractively(ctx) {
 		})).trim();
 	}
 	return {
-		...await collectConnectionInteractively(ctx.preset),
+		...await collectConnectionInteractively(ctx.apiPath),
 		dir,
 		alias
 	};
@@ -63,7 +75,7 @@ function collectFromEnv(ctx) {
 	return {
 		...conn,
 		dir,
-		alias: ctx.preset.apiPath ? aliasWithSlash(detectImportAlias(ctx.cwd, path.join(dir, "server"))?.prefix) : ""
+		alias: ctx.apiPath ? aliasWithSlash(detectImportAlias(ctx.cwd, path.join(dir, "server"))?.prefix) : ""
 	};
 }
 function readPkg(pkgPath) {
@@ -105,13 +117,13 @@ const init = defineCommand({
 			description: "Overwrite existing .env values and server entry without asking",
 			default: false
 		},
-		preset: {
-			type: "string",
-			description: `Force a setup preset (${PRESETS.map((preset) => preset.id).join(", ")})`
-		},
 		alias: {
 			type: "string",
 			description: "Import alias prefix for generated imports (e.g. @); blank for relative"
+		},
+		source: {
+			type: "string",
+			description: "Where to wire from — a local dir or giget source, either a registry of templates or a single template (default: Kizlo's GitHub templates)"
 		}
 	},
 	async run({ args }) {
@@ -136,73 +148,109 @@ const init = defineCommand({
 		const pm = detectPackageManager(cwd);
 		const hasKizlo = Boolean(pkg.dependencies?.kizlo) || Boolean(pkg.devDependencies?.kizlo);
 		const hasSrcDir = fs.existsSync(path.join(cwd, "src"));
-		const initCtx = {
-			cwd,
-			pkg,
-			pm,
-			hasSrcDir
-		};
-		let preset;
-		if (args.preset) {
-			const chosen = getPreset(String(args.preset));
-			if (!chosen) {
-				p.cancel(`Unknown preset "${args.preset}". Available: ${PRESETS.map((pr) => pr.id).join(", ")}`);
-				process.exit(1);
-			}
-			preset = chosen;
-		} else {
-			preset = detectPreset(initCtx);
-			if (preset.id !== "base") p.log.success(`${preset.label} detected`);
-		}
-		if (preset.template === "nextjs" && !fs.existsSync(path.join(cwd, "app")) && !fs.existsSync(path.join(cwd, "src/app"))) {
-			p.cancel("Kizlo needs the Next.js App Router — no `app` or `src/app` directory found. The Pages Router isn't supported.");
-			process.exit(1);
-		}
 		if (yes) loadEnvFiles(cwd);
-		let manifest;
-		let fetched;
-		if (preset.template) {
-			fetched = await fetchTemplate(preset.template);
-			manifest = readManifest(fetched.dir);
-			const minErr = minCliError(manifest);
-			if (minErr) {
-				fetched.cleanup();
-				p.cancel(minErr);
-				process.exit(1);
-			}
+		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 envKeys = resolveEnvKeys(preset, manifest);
+		const cancelFrom = (message) => {
+			fetchedRegistry.cleanup();
+			p.cancel(message);
+			process.exit(1);
+		};
 		try {
+			const entries = listTemplates(fetchedRegistry.dir);
+			if (entries.length === 0) cancelFrom(`No templates found in ${registry.source}. Each template needs a template.json.`);
+			const projectDeps = {
+				...pkg.dependencies,
+				...pkg.devDependencies
+			};
+			let entry;
+			if (isSingleTemplate(fetchedRegistry.dir)) {
+				const [only] = entries;
+				entry = only;
+				if (only && detectTemplates(entries, projectDeps).length === 0) {
+					p.log.warn(`The ${only.label} template doesn't match this project's dependencies — detection may be off on either side.`);
+					if (!(yes || orCancel(await p.confirm({
+						message: `Apply ${only.label} anyway?`,
+						initialValue: false
+					})))) cancelFrom("Cancelled. Point --source at a template that matches this project, or omit it to auto-detect.");
+				}
+			} else {
+				const matched = detectTemplates(entries, projectDeps);
+				const [first] = matched;
+				if (matched.length === 0) {
+					p.log.warn(`Couldn't find a template matching this project's framework ${registry.source === DEFAULT_REGISTRY ? "in Kizlo templates" : `at your provided source ${registry.source}`}.`);
+					if (yes) cancelFrom(`Re-run with --source pointing at the single template you want, or run without --yes to pick one manually.`);
+					if (!orCancel(await p.confirm({
+						message: "Pick a template manually anyway?",
+						initialValue: false
+					}))) cancelFrom("Cancelled.");
+					const id = orCancel(await p.select({
+						message: "Choose a template to apply",
+						options: entries.map((e) => ({
+							value: e.id,
+							label: e.label
+						}))
+					}));
+					entry = entries.find((e) => e.id === id);
+				} else if (matched.length === 1 && first) {
+					entry = first;
+					p.log.success(`${first.label} detected`);
+				} else {
+					const ids = matched.map((e) => e.id).join(", ");
+					if (yes) cancelFrom(`Multiple templates match this project (${ids}). Re-run with --source pointing at the single template you want.`);
+					const id = orCancel(await p.select({
+						message: "Multiple templates match this project — pick one",
+						options: matched.map((e) => ({
+							value: e.id,
+							label: e.label
+						}))
+					}));
+					entry = matched.find((e) => e.id === id);
+				}
+			}
+			if (!entry) return cancelFrom("No template selected.");
+			const manifest = readManifest(entry.dir);
+			const minErr = minCliError(manifest);
+			if (minErr) cancelFrom(minErr);
+			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({
 				cwd,
 				hasSrcDir,
-				preset,
+				apiPath,
 				envKeys
 			}) : await collectInteractively({
 				cwd,
 				hasSrcDir,
-				preset
+				apiPath
 			});
 			if (args.alias !== void 0) setup.alias = String(args.alias).trim();
 			setup.alias = aliasWithSlash(setup.alias);
-			const includeExamples = manifest && fetched ? yes ? true : orCancel(await p.confirm({
+			const includeExamples = yes ? true : orCancel(await p.confirm({
 				message: "Add example pages?",
 				initialValue: true
-			})) : false;
+			}));
 			if (!hasKizlo) {
-				const spec = `kizlo@${manifest?.dependencies?.kizlo ?? `^${getVersion()}`}`;
+				const spec = `kizlo@${manifest.dependencies?.kizlo ?? `^${getVersion()}`}`;
 				const s = p.spinner();
 				s.start(`Installing kizlo with ${pm}`);
 				const ok = await runCommandAsync(addDependencyArgs(pm, spec), cwd, "ignore");
 				s.stop(ok ? "Installed kizlo" : "Could not install kizlo automatically");
 				if (!ok) p.log.warn(`Install it yourself: ${addDependencyArgs(pm, spec).join(" ")}`);
 			}
-			if (preset.apiPath && setup.baseUrl) setup.baseUrl = withApiPath(setup.baseUrl, preset.apiPath);
+			if (apiPath && setup.baseUrl) setup.baseUrl = withApiPath(setup.baseUrl, apiPath);
 			await setupLocalWordPress(cwd, setup);
 			await writeEnv(cwd, envKeys, setup, {
 				force,
 				yes,
-				exampleTemplate: fetched ? readEnvExample(fetched.dir) : void 0
+				exampleTemplate: readEnvExample(entry.dir)
 			});
 			await syncRemote(setup);
 			const dirRel = setup.dir.replace(/^\.\//, "").replace(/\/+$/, "");
@@ -210,7 +258,7 @@ const init = defineCommand({
 			const clientUrl = setup.siteUrl && !sameOrigin(setup.siteUrl, setup.baseUrl) ? setup.baseUrl : void 0;
 			const scaffold = buildScaffoldContext(cwd, {
 				dirRel,
-				appDir: detectAppDir(cwd, hasSrcDir),
+				appDir: detectAppDir(cwd, hasSrcDir, manifest.conventions.appDir),
 				alias: setup.alias,
 				clientUrl
 			});
@@ -219,10 +267,8 @@ const init = defineCommand({
 				relPath: "kizlo.config.ts",
 				contents: kizloConfigTemplate(dirRel, setup.alias, setup.mode === "local")
 			}];
-			if (manifest && fetched) {
-				await alignDependencies(cwd, pm, pkg, manifest);
-				for (const entry of fileEntries(changesFor(manifest, "init", { includeExamples }))) files.push(adaptFile(fetched.dir, entry, manifest.conventions, scaffold));
-			} else if (preset.scaffolds) files.push(...preset.scaffolds(scaffold));
+			await alignDependencies(cwd, pm, pkg, manifest);
+			for (const fileEntry of fileEntries(changesFor(manifest, "init", { includeExamples }))) files.push(adaptFile(entry.dir, fileEntry, manifest.conventions, scaffold));
 			const scaffolded = [];
 			for (const file of files) scaffolded.push({
 				file,
@@ -235,12 +281,16 @@ const init = defineCommand({
 			const gitignore = ensureGitignored(cwd, ".env");
 			ensureGitignored(cwd, ".kizlo/");
 			for (const { file, result } of scaffolded) reportScaffold(file, result, yes);
-			if (manifest) 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);
+			}
 			if (gitignore !== "present") p.log.success(`${gitignore === "created" ? "Created" : "Updated"} .gitignore (ignoring .env)`);
 			nextStepsNote(setup);
 			p.outro("Kizlo is ready 🎉");
 		} finally {
-			fetched?.cleanup();
+			fetchedRegistry.cleanup();
 		}
 	}
 });

package/dist/cli/daemon/config.js

@@ -2,10 +2,10 @@ import { LOCAL_DIR_REL } from "../wp/constants.js";
 import { credentialsPath, findConfigDir } from "../wp/utils.js";
 import { log } from "./logger.js";
 import { detectPackageManager } from "../utils.js";
+import { importIgnoringVirtualModules } from "./jiti.js";
 import z from "zod/v4";
 import path from "node:path";
 import fs from "node:fs";
-import { createJiti } from "jiti";
 
 //#region src/cli/daemon/config.ts
 const fixtureSchema = z.custom((value) => typeof value === "object" && value !== null && typeof value.name === "string", { message: "must be a fixture object with a string `name` (use defineFixture)" });
@@ -41,15 +41,12 @@ const CONFIG_FILES = [
 const DEFAULT_DEV_PORT = 8080;
 const DEFAULT_DEV_DB_PORT = 3307;
 const DEFAULT_TEST_PORT = 8889;
-function defaultDir(cwd) {
-	return fs.existsSync(path.join(cwd, "src")) ? "src/lib/kizlo" : "lib/kizlo";
-}
 async function loadConfigFile(cwd) {
 	const file = CONFIG_FILES.map((name) => path.join(cwd, name)).find((p) => fs.existsSync(p));
 	if (!file) return void 0;
 	let raw;
 	try {
-		const mod = await createJiti(cwd, { moduleCache: false }).import(file);
+		const mod = await importIgnoringVirtualModules(cwd, file);
 		raw = mod.default ?? mod;
 	} catch (error) {
 		log.error(`Could not load ${path.basename(file)}:`, error);
@@ -62,9 +59,18 @@ async function loadConfigFile(cwd) {
 	}
 	return result.data;
 }
+/**
+* Resolve the Kizlo server layout from an explicit `dir` — the `--dir` flag or `dir` in
+* `kizlo.config.*`. Returns `undefined` when neither is set: there's no Kizlo server to
+* generate a contract from, so callers skip generation and (for `dev`) run local WordPress
+* alone. There's intentionally no default path — a missing `dir` means "no server", not
+* "look under `lib/kizlo`".
+*/
 async function resolveConfig(cwd, flags) {
 	const fileConfig = await loadConfigFile(cwd);
-	const dir = (flags?.dir ?? fileConfig?.dir ?? defaultDir(cwd)).replace(/^\.\//, "").replace(/\/+$/, "");
+	const raw = flags?.dir ?? fileConfig?.dir;
+	if (!raw) return void 0;
+	const dir = raw.replace(/^\.\//, "").replace(/\/+$/, "");
 	const serverDir = path.join(dir, "server");
 	const generatedDir = path.join(serverDir, "generated");
 	return {
@@ -99,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.
@@ -110,7 +124,7 @@ 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,
@@ -142,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,
@@ -154,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/daemon/generate.js

@@ -1,8 +1,8 @@
 import { generateContract } from "../../shared/contract.js";
 import { loadEnvFiles } from "../utils.js";
+import { importIgnoringVirtualModules } from "./jiti.js";
 import path from "node:path";
 import fs from "node:fs";
-import { createJiti } from "jiti";
 
 //#region src/cli/daemon/generate.ts
 /** The generated contract barrel — also written as a stub by `kizlo init`. */
@@ -25,9 +25,8 @@ function atomicWrite(file, data) {
 */
 async function generateOnce(cfg) {
 	loadEnvFiles(cfg.cwd);
-	const jiti = createJiti(cfg.cwd, { moduleCache: false });
 	const entry = path.resolve(cfg.cwd, cfg.serverEntry);
-	const { router } = await jiti.import(entry);
+	const { router } = await importIgnoringVirtualModules(cfg.cwd, entry);
 	if (!router) return false;
 	const contract = JSON.stringify(await generateContract(router));
 	fs.mkdirSync(path.resolve(cfg.cwd, cfg.generatedDir), { recursive: true });

package/dist/cli/daemon/jiti.js

@@ -0,0 +1,101 @@
+import { CONTRACT_GENERATION_ENV } from "../../shared/constants.js";
+import path from "node:path";
+import fs from "node:fs";
+import { createJiti } from "jiti";
+
+//#region src/cli/daemon/jiti.ts
+/**
+* Loads a TypeScript module through jiti while tolerating framework virtual modules
+* (`astro:env/server`, `virtual:*`, `#imports`, `$env/*`, …). These are synthesized by the
+* framework's bundler at build time and don't exist on disk, so jiti can't resolve them — but
+* contract generation only needs the module's exported *shape*, never the runtime values a
+* virtual module carries. We discover them from the project's own source rather than maintaining
+* a per-framework list: import, and whenever jiti reports a missing module, stub it and retry.
+*
+* A virtual module is distinguished from a genuinely missing dependency by the one property that
+* always holds — a virtual module is never a declared dependency, so a bare specifier whose
+* package isn't in `package.json` is treated as virtual, while a declared-but-unresolvable
+* dependency is surfaced as the real error it is.
+*/
+async function importIgnoringVirtualModules(cwd, entry) {
+	const deps = declaredDeps(cwd);
+	const virtualModules = {};
+	const previousGenerationFlag = process.env[CONTRACT_GENERATION_ENV];
+	process.env[CONTRACT_GENERATION_ENV] = "1";
+	try {
+		return await importLoop(cwd, entry, deps, virtualModules);
+	} finally {
+		if (previousGenerationFlag === void 0) delete process.env[CONTRACT_GENERATION_ENV];
+		else process.env[CONTRACT_GENERATION_ENV] = previousGenerationFlag;
+	}
+}
+async function importLoop(cwd, entry, deps, virtualModules) {
+	for (;;) {
+		const jiti = createJiti(cwd, {
+			moduleCache: false,
+			tsconfigPaths: true,
+			virtualModules
+		});
+		try {
+			return await jiti.import(entry);
+		} catch (error) {
+			const spec = missingSpecifier(error);
+			if (!spec || !isBareSpecifier(spec) || spec in virtualModules || deps.has(packageNameOf(spec))) throw error;
+			virtualModules[spec] = makeVirtualStub();
+		}
+	}
+}
+/**
+* A no-op module namespace that satisfies any import shape (named, default, nested, callable),
+* so a virtual module can be stubbed without knowing what it exports. The `has` trap is required:
+* without it jiti's `interopDefault` sees a truthy `.default` and routes named lookups down a path
+* that misses.
+*
+* Every export — named, default, nested, callable — is a no-op, so contract generation only ever
+* reads the module's shape, never a real value a virtual module would carry at runtime.
+*/
+function makeVirtualStub() {
+	const stub = new Proxy(() => {}, {
+		apply: () => void 0,
+		has: (_t, prop) => typeof prop === "string" && prop !== "then",
+		get: (_t, prop) => {
+			if (prop === "__esModule") return true;
+			if (prop === "then") return void 0;
+			if (typeof prop === "symbol") return void 0;
+			return stub;
+		}
+	});
+	return stub;
+}
+/** Names of every declared dependency; empty when `package.json` is absent or unreadable. */
+function declaredDeps(cwd) {
+	try {
+		const pkg = JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8"));
+		return new Set([
+			...Object.keys(pkg.dependencies ?? {}),
+			...Object.keys(pkg.devDependencies ?? {}),
+			...Object.keys(pkg.peerDependencies ?? {}),
+			...Object.keys(pkg.optionalDependencies ?? {})
+		]);
+	} catch {
+		return /* @__PURE__ */ new Set();
+	}
+}
+/** The specifier jiti/Node reported unresolvable, or undefined when the error isn't a resolution failure. */
+function missingSpecifier(error) {
+	const err = error;
+	if (err?.code !== "MODULE_NOT_FOUND" && err?.code !== "ERR_MODULE_NOT_FOUND") return void 0;
+	return /Cannot find module '([^']+)'/.exec(err.message ?? "")?.[1];
+}
+/** Virtual specifiers are always bare; a missing relative/absolute path is a real bug, not a virtual module. */
+function isBareSpecifier(spec) {
+	return !spec.startsWith(".") && !spec.startsWith("/");
+}
+/** Package name of a bare specifier: `@scope/x/sub` → `@scope/x`, `astro:env/server` → `astro:env`. */
+function packageNameOf(spec) {
+	const parts = spec.split("/");
+	return spec.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0] ?? spec;
+}
+
+//#endregion
+export { importIgnoringVirtualModules };

package/dist/cli/daemon/watch.js

@@ -37,9 +37,9 @@ async function watch(cfg) {
 * Acquire the single-instance lock, generate the contract once, and start the file
 * watcher. Returns a synchronous `stop()` that closes the watcher and releases the
 * lock — or `undefined` when another watcher already holds the lock (a framework dev
-* script, or a second `kizlo dev`), in which case the caller carries on without
-* watching. Used by `kizlo dev`, both when it boots a local stack and when it runs
-* the watcher alone, so a single terminal covers the whole dev loop.
+* script, or a second `kizlo dev`), or when no server `dir` is configured, in which case
+* the caller carries on without watching. Used by `kizlo dev`, both when it boots a local
+* stack and when it runs the watcher alone, so a single terminal covers the whole dev loop.
 */
 async function startWatcher(cwd, opts) {
 	const lock = lockPath(cwd);
@@ -48,6 +48,10 @@ async function startWatcher(cwd, opts) {
 		return;
 	}
 	const cfg = await resolveConfig(cwd, { dir: opts?.dir });
+	if (!cfg) {
+		log.info("skipping the contract generation.");
+		return;
+	}
 	acquire(lock);
 	try {
 		if (await generateOnce(cfg)) log.success("Contract generated");

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