kizlo 0.13.0 → 0.14.0

package/dist/cli/presets/template.js

@@ -38,10 +38,18 @@ import fs from "node:fs";
 *   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(),
-	appDir: z.string(),
-	alias: z.string()
+/**
+* The template's wiring config — how Kizlo addresses the files it lays down, rewritten to the project's
+* own layout on apply (used by both `create` and `init`, unlike the init-only preconditions). The
+* template writes its files against its own {@link configSchema.shape.kizloPath} and
+* {@link configSchema.shape.alias}; on apply the Kizlo dir is retargeted to the project's chosen location,
+* every alias import to the project's import style, and every other `src/`-rooted path to the project's
+* `src/` convention (kept when the project uses `src/`, stripped when it doesn't).
+*/
+const configSchema = z.object({
+	apiPath: z.string().optional(),
+	alias: z.string(),
+	kizloPath: z.string()
 });
 const fileSchema = z.object({
 	kind: z.literal("file"),
@@ -65,12 +73,131 @@ const patchSchema = z.object({
 	})).default([]),
 	note: z.string().optional()
 });
-const bootstrapSchema = z.object({
-	initializer: z.string(),
-	flags: z.array(z.string()).default([])
+/**
+* The `command` half of {@link createSchema}: the full invocation that scaffolds the base app with the
+* framework's own CLI, written exactly as it would be typed — e.g. `{{pm}} create next-app@latest {{name}}
+* --ts …`. The CLI imposes no shape: it tokenizes the string, substitutes the tokens below, and runs the
+* argv verbatim, so a template can use any invocation (a `create-*` initializer, `{{pm}} dlx <cli> create`,
+* a subcommand after the package spec) without the CLI knowing anything framework-specific. The template is
+* fully authoritative, which means it also owns any package-manager quirks (npm's `--` separator, yarn's
+* `@latest` handling).
+*
+* The core tokens substituted before the command runs:
+* - `{{pm}}` — the chosen package manager (`pnpm`/`npm`/`yarn`/`bun`).
+* - `{{name}}` — the project name (or path) the user gave.
+* - `{{dlx}}` — the manager's run-a-package command (`pnpm dlx`/`npx`/`yarn dlx`/`bunx`), for a CLI that
+*   isn't a `create-*` package (e.g. `{{dlx}} @tanstack/cli@latest create {{name}}`); a `create-*`
+*   package invokes more simply as `{{pm}} create <initializer> {{name}}`.
+*
+* Beyond those, a `{{<token>}}` for every prompt in the same `create` block (see {@link promptSchema}) is
+* substituted with the CLI fragment the user's answer maps to — the mechanism that lets a template
+* surface a real framework choice (which linter, turbopack on/off) instead of hard-coding the flag.
+* A fragment may be empty (contributes nothing) or several flags; each is spliced in as plain text and
+* re-tokenized, so the CLI still learns nothing framework-specific.
+*
+* The command must produce a project whose shape matches {@link configSchema} (directory layout,
+* import alias) so the wiring lands where the manifest expects. Simple single/double quotes group a
+* token that contains spaces; there is no shell expansion.
+*/
+const commandSchema = z.string();
+/**
+* A prompt the template asks during `create`, its answer mapped to a fragment of the {@link commandSchema}
+* command via the prompt's `{{token}}`. This is how a template exposes a framework CLI choice it would
+* otherwise have to hard-code (which linter, turbopack on/off, a custom import alias) without the Kizlo
+* CLI knowing anything framework-specific: the manifest owns both the question and the flag it produces.
+*
+* Three shapes, discriminated on `kind`:
+* - `select` — a single choice from {@link promptOptionSchema} options; the chosen option's `arg` is the
+*   fragment. `default` names the option value pre-selected (and used non-interactively); absent → the
+*   first option.
+* - `confirm` — a yes/no; `arg` is the fragment when yes, `argFalse` when no. `default` is the answer used
+*   non-interactively.
+* - `text` — free input spliced into `arg` at its `{{value}}` placeholder; the value is shell-quoted so it
+*   stays a single argv token. Empty input quotes to nothing, so with the default `{{value}}` arg it
+*   contributes nothing (a wrapping arg like `--flag {{value}}` still emits the flag). `default` is the
+*   value used non-interactively.
+*
+* Every prompt owns a unique `token` that must not shadow a core token (`pm`/`name`/`dlx`); the bootstrap
+* schema rejects collisions and duplicates.
+*/
+const promptOptionSchema = z.object({
+	label: z.string(),
+	value: z.string(),
+	arg: z.string().default("")
+});
+const selectPromptSchema = z.object({
+	kind: z.literal("select"),
+	token: z.string(),
+	message: z.string(),
+	default: z.string().optional(),
+	options: z.array(promptOptionSchema).min(1)
+});
+const confirmPromptSchema = z.object({
+	kind: z.literal("confirm"),
+	token: z.string(),
+	message: z.string(),
+	default: z.boolean().default(true),
+	arg: z.string().default(""),
+	argFalse: z.string().default("")
+});
+const textPromptSchema = z.object({
+	kind: z.literal("text"),
+	token: z.string(),
+	message: z.string(),
+	placeholder: z.string().optional(),
+	default: z.string().optional(),
+	arg: z.string().default("{{value}}")
+});
+const promptSchema = z.discriminatedUnion("kind", [
+	selectPromptSchema,
+	confirmPromptSchema,
+	textPromptSchema
+]);
+/** The core bootstrap tokens a prompt token must never shadow. */
+const RESERVED_TOKENS = new Set([
+	"pm",
+	"name",
+	"dlx"
+]);
+/**
+* How `create` scaffolds the base app: the framework CLI `command` to run, plus the `prompts` whose answers
+* fill its `{{token}}` placeholders — kept together because a prompt is meaningless without the command it
+* customizes. Absent on templates that only `init` supports; `create` refuses a template whose manifest
+* declares no `create` block. A `superRefine` rejects a prompt `token` that shadows a core token
+* (`pm`/`name`/`dlx`) or repeats another prompt's, so a mis-authored manifest fails loudly at parse time.
+*/
+const createSchema = z.object({
+	command: commandSchema,
+	prompts: z.array(promptSchema).default([])
+}).superRefine((create, ctx) => {
+	const seen = /* @__PURE__ */ new Set();
+	for (const prompt of create.prompts) {
+		if (RESERVED_TOKENS.has(prompt.token)) ctx.addIssue({
+			code: "custom",
+			message: `Prompt token "${prompt.token}" is reserved (pm/name/dlx).`,
+			path: ["prompts"]
+		});
+		if (seen.has(prompt.token)) ctx.addIssue({
+			code: "custom",
+			message: `Duplicate prompt token "${prompt.token}".`,
+			path: ["prompts"]
+		});
+		seen.add(prompt.token);
+	}
 });
 const changeSchema = z.discriminatedUnion("kind", [fileSchema, patchSchema]);
 /**
+* The changes a template lays down, split by the one question that decides whether a command may safely
+* apply them — *where is this safe to land?* No command reads another's section: `base` is additive and
+* safe on any project (both commands apply it), `create` overwrites framework-scaffolded files (only
+* `create`), `init` patches files the user owns (only `init`). See the section doc above and {@link changesFor}.
+*/
+const changesSchema = z.object({
+	base: z.array(changeSchema).default([]),
+	create: z.array(changeSchema).default([]),
+	init: z.array(changeSchema).default([])
+});
+/**
 * The `.env` key names the scaffold writes and the pinned runtime later reads — the one part of the
 * wiring contract that can drift when the scaffold-time CLI and the pinned runtime disagree. Declared
 * here as data so the scaffold writes whatever names the pinned runtime expects. Semantic slots only;
@@ -95,21 +222,6 @@ const envSchema = z.object({
 /** A package name → version-range map, package.json's own vocabulary. */
 const depsSchema = z.record(z.string(), z.string());
 /**
-* The package names whose presence in a project's dependencies identify this framework — how `init`
-* recognizes which template to apply to an existing project (e.g. `["next"]`, `["astro"]`). Detection is
-* data, so a community template declares its own signal and needs no CLI change. See {@link detectTemplate}.
-*/
-const detectSchema = z.object({ dependencies: z.array(z.string()).default([]) });
-/**
-* An `init` precondition on the project's shape: at least one of `anyDir` must exist in the project,
-* else `init` stops with `message`. Replaces framework-specific `if` branches — e.g. Next.js needs an
-* `app` or `src/app` directory (the App Router), which the Pages Router lacks. Dormant when absent.
-*/
-const requiresSchema = z.object({
-	anyDir: z.array(z.string()),
-	message: z.string()
-});
-/**
 * A post-setup manual step `init` prints after wiring — the piece Kizlo can't auto-wire into a file the
 * user owns (e.g. Astro's SEO tags render through a `.astro` component, not a patchable export). `create`
 * owns files whole, so it never prints these. `body` may carry one token, `{{importPrefix}}`, substituted
@@ -119,24 +231,95 @@ const noteSchema = z.object({
 	title: z.string(),
 	body: z.string()
 });
+/**
+* A single precondition `init` checks against the project before applying — data in place of the old
+* framework-specific `if` branches, so a community template declares its own without a CLI change.
+* Discriminated on `kind`:
+*
+* - `dep` — package(s) in the project's dependencies. Doubles as the framework *detection* signal (see
+*   {@link detectTemplates}): a template's match score is how many of its `dep` `values` the project has,
+*   read across every candidate template before one is chosen.
+* - `dir` — director(ies) in the project tree, e.g. Next's `app`/`src/app` App Router (the Pages Router
+*   lacks it).
+*
+* `match` decides whether `any` (default) or `all` of `values` must be present; `message` is the abort
+* text shown when the requirement is unmet, defaulting to `""` → a generated fallback. See {@link unmetRequirement}.
+*/
+const requiresFields = {
+	values: z.array(z.string()).min(1),
+	match: z.enum(["any", "all"]).default("any"),
+	message: z.string().default("")
+};
+const requiresDepSchema = z.object({
+	kind: z.literal("dep"),
+	...requiresFields
+});
+const requiresDirSchema = z.object({
+	kind: z.literal("dir"),
+	...requiresFields
+});
+const requirementSchema = z.discriminatedUnion("kind", [requiresDepSchema, requiresDirSchema]);
+/** Everything the `init` command needs of the project: the preconditions it checks and the steps it prints. */
+const initSchema = z.object({
+	requires: z.array(requirementSchema).default([]),
+	notes: z.array(noteSchema).default([])
+});
 const manifestSchema = z.object({
-	framework: z.string(),
+	id: z.string(),
 	name: z.string().optional(),
 	env: envSchema.optional(),
 	dependencies: depsSchema.optional(),
 	devDependencies: depsSchema.optional(),
 	minCli: z.string().optional(),
-	apiPath: z.string().optional(),
-	detect: detectSchema.optional(),
-	requires: requiresSchema.optional(),
-	notes: z.array(noteSchema).default([]),
-	bootstrap: bootstrapSchema.optional(),
-	conventions: conventionsSchema,
-	base: z.array(changeSchema).default([]),
-	create: z.array(changeSchema).default([]),
-	init: z.array(changeSchema).default([])
+	config: configSchema,
+	init: initSchema.default({
+		requires: [],
+		notes: []
+	}),
+	create: createSchema.optional(),
+	changes: changesSchema.default({
+		base: [],
+		create: [],
+		init: []
+	})
 });
 /**
+* Wrap a text prompt's answer so it survives {@link tokenizeCommand} as exactly one argv token: an empty
+* value stays empty (contributes nothing), otherwise it's double-quoted with any inner `"` escaped. This is
+* what lets a free-text value with spaces (`--import-alias "my alias"`) splice cleanly into the bootstrap
+* command without the tokenizer splitting it.
+*/
+function quoteValue(value) {
+	if (value === "") return "";
+	return `"${value.replaceAll("\"", "\\\"")}"`;
+}
+/**
+* The CLI fragment a prompt answer maps to — the single place answer→flag translation lives, shared by the
+* interactive collector and the non-interactive default path. `answer` is the chosen option `value`
+* (select), the boolean (confirm), or the raw input (text). Returns the fragment spliced into the bootstrap
+* command for this prompt's `{{token}}`; a select answer with no matching option (a stale `default`) yields
+* the first option's fragment.
+*/
+function promptFragment(prompt, answer) {
+	switch (prompt.kind) {
+		case "select": return (prompt.options.find((opt) => opt.value === answer) ?? prompt.options[0])?.arg ?? "";
+		case "confirm": return answer ? prompt.arg : prompt.argFalse;
+		case "text": return prompt.arg.replaceAll("{{value}}", quoteValue(String(answer)));
+	}
+}
+/**
+* The answer used non-interactively (`--yes`, non-TTY) — the prompt's declared default, or the first
+* option / empty string when none is set. Returns both the answer (for the choices summary) and the
+* {@link promptFragment} it maps to, so the caller shows a value and splices a flag from one call.
+*/
+function resolvePromptDefault(prompt) {
+	const answer = prompt.kind === "confirm" ? prompt.default : prompt.kind === "select" ? prompt.default ?? prompt.options[0]?.value ?? "" : prompt.default ?? "";
+	return {
+		answer,
+		arg: promptFragment(prompt, answer)
+	};
+}
+/**
 * Render a manual-step note for display, substituting the `{{importPrefix}}` token with the project's
 * source-root import prefix — the configured alias (normalized to a trailing slash, e.g. `@/`) when one
 * is set, else the relative `../`. Reproduces the old `alias ? "@/…" : "../…"` behavior exactly, so a
@@ -227,9 +410,26 @@ function minCliError(manifest) {
 * section: init's opt-in examples are the additive ones in `base`, never create's homepage overwrite.
 */
 function changesFor(manifest, command, opts = {}) {
-	const changes = [...manifest.base, ...manifest[command]];
+	const changes = [...manifest.changes.base, ...manifest.changes[command]];
 	return opts.includeExamples ? changes : changes.filter((change) => !isExample(change));
 }
+/**
+* The first `init` precondition the project fails, as a ready-to-print abort message, or `undefined` when
+* every requirement passes. `deps` is the project's merged dependencies; `dirExists` tests a
+* project-relative directory. A `dep` requirement checks membership in `deps`, a `dir` requirement checks
+* the tree, each honoring its `match` (`any`/`all`). An unmet requirement yields its own `message`, or a
+* generated fallback when it declares none (the common case for `dep` entries, which detection filters
+* out first). See {@link requirementSchema}.
+*/
+function unmetRequirement(requires, deps, dirExists) {
+	for (const req of requires) {
+		const has = req.kind === "dep" ? (value) => value in deps : dirExists;
+		if (req.match === "all" ? req.values.every(has) : req.values.some(has)) continue;
+		if (req.message) return req.message;
+		const noun = req.kind === "dep" ? "package" : "directory";
+		return `Kizlo needs ${req.match === "all" ? "all of" : "one of"} these ${noun}s: ${req.values.join(", ")}.`;
+	}
+}
 /** The whole-file changes in a resolved change list. */
 function fileEntries(changes) {
 	return changes.filter((change) => change.kind === "file");
@@ -253,11 +453,11 @@ function escapeRegExp(value) {
 * `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(/\/+$/, "");
+function templateAliasBase(templateDir, config) {
+	const alias = config.alias.replace(/\/+$/, "");
 	const mapping = readTsconfigPaths(templateDir)?.[`${alias}/*`]?.[0];
 	if (mapping) return mapping.replace(/^\.\//, "").replace(/\/\*$/, "").replace(/\/+$/, "");
-	return conventions.kizloDir.startsWith("src/") ? "src" : "";
+	return config.kizloPath.startsWith("src/") ? "src" : "";
 }
 /**
 * Rewrite every template-alias import in a file to the project's chosen import style — the one place that
@@ -269,23 +469,28 @@ function templateAliasBase(templateDir, conventions) {
 * 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(/\/+$/, "");
+function rewriteAliasImports(body, fromDir, base, config, ctx) {
+	const alias = config.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);
+		const targetRel = adaptTemplatePath(base ? `${base}/${rest}` : rest, config, ctx);
 		return `${quote}${ctx.importFrom(targetRel, fromDir)}${quote}`;
 	});
 }
 /**
-* Adapt a template path prefix (`src/app/...`, `src/lib/kizlo/...`) to the project's real directories.
-* Only the leading convention dir is swapped; the rest of the path is preserved verbatim.
+* Adapt a template path to the project's real layout. The Kizlo home dir is retargeted to wherever the
+* user put it (`config.kizloPath` → `ctx.kizloPath`). Every other path is `src/`-rooted as authored, so it
+* only needs to match the project's `src/` convention: a project that keeps source under `src/` gets it
+* verbatim, one that doesn't gets the leading `src/` stripped (so `src/app/...` lands at `app/...`, config
+* files at the root are untouched). This makes the one project-wide decision — `src/` or not — instead of
+* tracking a per-framework route directory.
 */
-function adaptTemplatePath(relPath, conventions, ctx) {
+function adaptTemplatePath(relPath, config, ctx) {
 	const normalized = relPath.split(path.sep).join("/");
-	if (normalized === conventions.appDir || normalized.startsWith(`${conventions.appDir}/`)) return `${ctx.appDir}${normalized.slice(conventions.appDir.length)}`;
-	if (normalized === conventions.kizloDir || normalized.startsWith(`${conventions.kizloDir}/`)) return `${ctx.kizloDir}${normalized.slice(conventions.kizloDir.length)}`;
+	const { kizloPath } = config;
+	if (normalized === kizloPath || normalized.startsWith(`${kizloPath}/`)) return `${ctx.kizloPath}${normalized.slice(kizloPath.length)}`;
+	if (!ctx.hasSrcDir && normalized.startsWith("src/")) return normalized.slice(4);
 	return normalized;
 }
 /**
@@ -296,12 +501,12 @@ function adaptTemplatePath(relPath, conventions, ctx) {
 * 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) {
+function adaptFile(templateDir, entry, config, 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 contents = rewriteAliasImports(body, path.posix.dirname(relPath), templateAliasBase(templateDir, conventions), conventions, ctx);
+	const relPath = adaptTemplatePath(entry.path, config, ctx);
+	const contents = rewriteAliasImports(body, path.posix.dirname(relPath), templateAliasBase(templateDir, config), config, ctx);
 	return {
 		label: ROLE_LABELS[entry.role] ?? entry.role,
 		relPath,
@@ -309,8 +514,8 @@ function adaptFile(templateDir, entry, conventions, ctx) {
 	};
 }
 /** Adapt a patch's path prefix and server-import specifier to the project's real directories. */
-function resolvePatch(entry, conventions, ctx) {
-	const relPath = adaptTemplatePath(entry.path, conventions, ctx);
+function resolvePatch(entry, config, ctx) {
+	const relPath = adaptTemplatePath(entry.path, config, ctx);
 	const fromDir = path.posix.dirname(relPath);
 	const imports = entry.imports.map((imp) => ({
 		module: imp.module.replaceAll("{{serverImport}}", ctx.serverImport(fromDir)),
@@ -327,4 +532,4 @@ function resolvePatch(entry, conventions, ctx) {
 }
 
 //#endregion
-export { adaptFile, changesFor, fileEntries, isOlderVersion, minCliError, patchEntries, readManifest, renderNote, resolveDependencies, resolvePatch };
+export { adaptFile, changesFor, fileEntries, isOlderVersion, minCliError, patchEntries, promptFragment, readManifest, renderNote, resolveDependencies, resolvePatch, resolvePromptDefault, unmetRequirement };