create-keboola-app 0.0.0

package/README.md

@@ -0,0 +1,79 @@
+# create-keboola-app
+
+Scaffold a Keboola-shaped frontend app: Vite, React 19, TanStack Router/Query/Form, Zustand,
+`@keboola/design` with `@keboola/brand-registry`, oxlint/oxfmt, vitest.
+
+```bash
+npm create keboola-app
+```
+
+Interactive by default. Fully flag-driven for agents and CI:
+
+```bash
+npm create keboola-app -- --name my-app --blocks kpi,grid --yes --json
+```
+
+## Options
+
+| Flag                  | Meaning                                                                             |
+| --------------------- | ----------------------------------------------------------------------------------- |
+| `--name <kebab-name>` | App directory and package name. Required unless prompted.                           |
+| `--blocks <a,b,c>`    | Comma-separated block ids, or `all`, or `none`. Default: all.                       |
+| `--yes`               | Never prompt. Missing input is an error, not a question.                            |
+| `--json`              | Print the machine-readable result on stdout; logs go to stderr.                     |
+| `--workspace`         | Emit into `apps/<name>` of a Keboola monorepo checkout instead of a standalone app. |
+
+## Blocks
+
+| Block       | What you get                                                                           |
+| ----------- | -------------------------------------------------------------------------------------- |
+| `kpi`       | A KPI card row on the overview.                                                        |
+| `chart`     | A token-themed line chart card on the overview.                                        |
+| `grid`      | An editable per-row budget grid (TanStack Table + design `Table`).                     |
+| `crud`      | A list → detail → form slice over `/tokens`, exercising router params, Query and Form. |
+| `assistant` | A docked assistant rail, a page composer and an explain-on-selection floater.          |
+
+Every block is independent — none imports another, so any combination compiles. Blocks are
+additive: pick what you need rather than taking everything and deleting, since an unpicked
+block costs no files and pulls none of its npm dependencies.
+
+Blocks join the shell through three files the generator writes rather than patches:
+`src/nav.ts` (the nav tuple), `src/overview-sections.tsx` (the ordered section registry) and
+`src/store.ts` (the shell slice plus the selected block slices). Add a section to a generated
+app by editing those, not the app chrome.
+
+## Naming
+
+`--name` must match `^[a-z][a-z0-9-]*[a-z0-9]$` — kebab-case, starting with a letter and not
+ending in `-`. It becomes the directory name, the package name, and the prefix on the store's
+devtools and `localStorage` keys, so two apps served from one origin never clobber each other's
+saved preferences. If the target directory already exists, the CLI refuses rather than
+overwriting.
+
+## After scaffolding
+
+```bash
+cd my-app && pnpm install && pnpm dev
+```
+
+Read `AGENTS.md` in the generated app, then
+`node_modules/@keboola/design/AGENTS.md` — the contract for the version you actually installed.
+
+`gate:ui` is emitted but deliberately not wired into `test`: it scores the rendered route with
+`@keboola/ui-gen-bench`, which needs a model key, and a first run that fails for a missing
+credential is a worse welcome than an opt-in gate.
+
+## Inside a Keboola monorepo checkout
+
+`--workspace` targets a pnpm monorepo root instead of the current directory. It emits
+`apps/<name>` as `@keboola/<name>`, resolves the `@keboola/*` dependencies from the workspace
+rather than the registry, inherits the repo root's `engines`, and registers the new workspace in
+the repo-level `knip.json`. The repo's own `scaffold:app` script is a wrapper over exactly that.
+
+## How the template is built
+
+There is no committed copy of the template in this package. Its `build` script extracts the
+shell and every block out of the monorepo's reference app, rewriting workspace dependency
+ranges into published ones, dropping monorepo-only scripts, and replacing the app's identity
+with `__APP_NAME__` / `__APP_TITLE__` placeholders. One copy in git, so the reference app and
+the published template cannot drift.

package/dist/blocks-DYU5Ke29.js

@@ -0,0 +1,147 @@
+//#region src/blocks.ts
+const BLOCK_IDS = [
+	"kpi",
+	"chart",
+	"grid",
+	"crud",
+	"assistant"
+];
+const isBlockId = (value) => BLOCK_IDS.includes(value);
+const BLOCKS = {
+	kpi: {
+		id: "kpi",
+		label: "KPI cards",
+		summary: "A row of stat cards on the overview, reflowing on the content column width.",
+		files: [
+			"src/components/KpiCard.test.tsx",
+			"src/components/KpiCard.tsx",
+			"src/sections/kpi.tsx"
+		],
+		deps: [],
+		glue: ["src/overview-sections.tsx"],
+		brief: "KPI cards",
+		route: null
+	},
+	chart: {
+		id: "chart",
+		label: "Line chart",
+		summary: "A token-themed line chart card; series colours are `--chart-N` palette slots.",
+		files: [
+			"src/recipes/Chart.test.tsx",
+			"src/recipes/Chart.tsx",
+			"src/sections/chart.tsx"
+		],
+		deps: [],
+		glue: ["src/overview-sections.tsx"],
+		brief: "a revenue chart",
+		route: null
+	},
+	grid: {
+		id: "grid",
+		label: "Editable grid",
+		summary: "An editable per-row budget grid: TanStack Table for the model, design `Table` for chrome.",
+		files: [
+			"src/recipes/DataGrid.test.tsx",
+			"src/recipes/DataGrid.tsx",
+			"src/sections/grid.tsx"
+		],
+		deps: ["@tanstack/react-table"],
+		glue: ["src/overview-sections.tsx"],
+		brief: "an editable financial grid",
+		route: null
+	},
+	crud: {
+		id: "crud",
+		label: "CRUD slice",
+		summary: "List → detail → form over `/tokens`: router params, Query and Form in one flow.",
+		files: [
+			"src/routes/tokens/-fixtures.test.ts",
+			"src/routes/tokens/-fixtures.ts",
+			"src/routes/tokens/-hooks.ts",
+			"src/routes/tokens/-index.test.tsx",
+			"src/routes/tokens/-nav.ts",
+			"src/routes/tokens/-types.ts",
+			"src/routes/tokens/$id.tsx",
+			"src/routes/tokens/index.tsx",
+			"src/routes/tokens/new.tsx"
+		],
+		deps: ["@tanstack/react-form", "zod"],
+		glue: ["src/nav.ts"],
+		brief: "a list page reachable from the rail",
+		route: "/tokens"
+	},
+	assistant: {
+		id: "assistant",
+		label: "Assistant rail",
+		summary: "A docked assistant rail, a page composer and explain-on-selection, sharing one transcript.",
+		files: [
+			"src/components/AssistantPanel.test.tsx",
+			"src/components/AssistantPanel.tsx",
+			"src/components/AssistantToggle.tsx",
+			"src/components/HomePrompt.tsx",
+			"src/components/SelectionFloater.test.tsx",
+			"src/components/SelectionFloater.tsx",
+			"src/slices/assistant.ts"
+		],
+		deps: [],
+		glue: ["src/store.ts"],
+		brief: "a prompt input and a docked assistant rail",
+		route: null
+	}
+};
+/** Files every emitted app carries, whatever the selection. */
+const SHELL_FILES = [
+	"index.html",
+	"oxlint.config.ts",
+	"package.json",
+	"public/favicon.svg",
+	"src/components/AppChrome.tsx",
+	"src/components/ColorModeToggle.tsx",
+	"src/components/SidebarModeMenu.test.tsx",
+	"src/components/SidebarModeMenu.tsx",
+	"src/index.css",
+	"src/main.tsx",
+	"src/nav.test.ts",
+	"src/nav.ts",
+	"src/overview-sections.test.tsx",
+	"src/overview-sections.tsx",
+	"src/routes/-fixtures.ts",
+	"src/routes/-hooks.ts",
+	"src/routes/-index.test.tsx",
+	"src/routes/__root.tsx",
+	"src/routes/index.tsx",
+	"src/slices/shell.ts",
+	"src/store.test.tsx",
+	"src/store.ts",
+	"src/test-setup.ts",
+	"src/vite-env.d.ts",
+	"templates/agent-safety/README.md",
+	"templates/agent-safety/aiexclude",
+	"templates/agent-safety/claude-code.settings.json",
+	"templates/agent-safety/cursorignore",
+	"tsconfig.json",
+	"vercel.json",
+	"vite.config.ts",
+	"vitest.config.ts"
+];
+/**
+* Tracked boilerplate files the template deliberately does not carry.
+*
+* - `AGENTS.md`, `README.md`, `.gitignore` — replaced by this package's `templates/`, because
+*   the boilerplate's versions point at monorepo paths.
+* - `turbo.json` — there is no turbo outside the monorepo.
+* - `src/routeTree.gen.ts` — regenerated per selection by the CLI; the committed one lists
+*   routes a shell-only app does not have.
+*/
+const NOT_IN_TEMPLATE = [
+	".gitignore",
+	"AGENTS.md",
+	"README.md",
+	"src/routeTree.gen.ts",
+	"turbo.json"
+];
+const OWNER = new Map([...SHELL_FILES.map((file) => [file, "shell"]), ...BLOCK_IDS.flatMap((id) => BLOCKS[id].files.map((file) => [file, id]))]);
+/** The block that owns `path`, `'shell'`, or `null` when nothing claims it. */
+const ownerOf = (path) => NOT_IN_TEMPLATE.includes(path) ? "shell" : OWNER.get(path) ?? null;
+//#endregion
+export { isBlockId as a, SHELL_FILES as i, BLOCK_IDS as n, ownerOf as o, NOT_IN_TEMPLATE as r, BLOCKS as t };

package/dist/cli.js

@@ -0,0 +1,451 @@
+#!/usr/bin/env node
+import { a as isBlockId, n as BLOCK_IDS, o as ownerOf, t as BLOCKS } from "./blocks-DYU5Ke29.js";
+import { a as substitute, i as renderRegions, n as assertNoMarkers, r as blockIdOf } from "./regions-B3r5LhXl.js";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { argv, cwd, exit, stderr, stdin, stdout } from "node:process";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+//#region src/args.ts
+/**
+* Accepted app names: kebab-case, starting with a letter, not ending in `-`.
+*
+* - The name becomes a directory, a package name and a `localStorage` key prefix, so it has to
+*   be valid in all three.
+*/
+const KEBAB_NAME_RE = /^[a-z][a-z0-9-]*[a-z0-9]$/;
+const VALUE_FLAGS = /* @__PURE__ */ new Set(["--name", "--blocks"]);
+const BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
+	"--yes",
+	"--json",
+	"--workspace",
+	"--help",
+	"-h"
+]);
+const HELP = `create-keboola-app — scaffold a Keboola-shaped frontend app
+
+Usage:
+  npm create keboola-app
+  npm create keboola-app -- --name <kebab-name> [--blocks <ids>] [--yes] [--json]
+
+Options:
+  --name <kebab-name>  App directory and package name. A bare positional works too.
+  --blocks <ids>       Comma-separated block ids, or \`all\`, or \`none\`. Default: all.
+  --yes                Never prompt. Missing input is an error, not a question.
+  --json               Print the result as JSON on stdout; logs go to stderr.
+  --workspace          Emit into apps/<name> of a Keboola monorepo checkout.
+  --help               Show this.
+
+Blocks:
+${BLOCK_IDS.map((id) => `  ${id.padEnd(10)} ${BLOCKS[id].summary}`).join("\n")}
+
+Blocks are independent: none imports another, so any combination compiles.
+`;
+const parseBlocks = (raw, errors) => {
+	if (raw === "all") return BLOCK_IDS;
+	if (raw === "none" || raw.trim() === "") return [];
+	const ids = raw.split(",").map((id) => id.trim());
+	const seen = /* @__PURE__ */ new Set();
+	const blocks = [];
+	for (const id of ids) {
+		if (!isBlockId(id)) {
+			errors.push(`Unknown block \`${id}\`. Valid blocks: ${BLOCK_IDS.join(", ")} (or \`all\`, or \`none\`).`);
+			continue;
+		}
+		if (seen.has(id)) {
+			errors.push(`Block \`${id}\` is listed twice in --blocks.`);
+			continue;
+		}
+		seen.add(id);
+		blocks.push(id);
+	}
+	return errors.length > 0 ? null : blocks;
+};
+const parseArgs = (argv) => {
+	const errors = [];
+	argv = argv.filter((arg) => arg !== "--");
+	const options = {
+		help: argv.includes("--help") || argv.includes("-h"),
+		name: null,
+		blocks: null,
+		yes: false,
+		json: false,
+		workspace: false
+	};
+	if (options.help) return {
+		ok: true,
+		options
+	};
+	let rawBlocks = null;
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i] ?? "";
+		if (VALUE_FLAGS.has(arg)) {
+			const value = argv[i + 1];
+			if (value === void 0 || value.startsWith("--")) {
+				errors.push(`${arg} needs a value.`);
+				continue;
+			}
+			if (arg === "--name") options.name = value;
+			else rawBlocks = value;
+			i += 1;
+			continue;
+		}
+		if (BOOLEAN_FLAGS.has(arg)) {
+			if (arg === "--yes") options.yes = true;
+			if (arg === "--json") options.json = true;
+			if (arg === "--workspace") options.workspace = true;
+			continue;
+		}
+		if (arg.startsWith("-")) {
+			errors.push(`Unknown flag \`${arg}\`. Run with --help for the full list.`);
+			continue;
+		}
+		if (options.name === null) options.name = arg;
+		else errors.push(`Unexpected argument \`${arg}\`. The app name is given once.`);
+	}
+	if (rawBlocks !== null) options.blocks = parseBlocks(rawBlocks, errors);
+	if (options.name !== null && !KEBAB_NAME_RE.test(options.name)) errors.push(`Invalid name \`${options.name}\`. Expected a kebab-case identifier of two or more characters: lower-case letters, digits and single dashes, starting with a letter and not ending in a dash. Examples: catalog, data-explorer.`);
+	return errors.length > 0 ? {
+		ok: false,
+		errors
+	} : {
+		ok: true,
+		options
+	};
+};
+//#endregion
+//#region src/scaffold.ts
+/** Template files that describe the template rather than belong to the app. */
+const TEMPLATE_METADATA = /* @__PURE__ */ new Set(["workspace-deps.json", "package.json"]);
+/** Files this package's `templates/` contributes, which the boilerplate manifest does not claim. */
+const TEMPLATE_DOCS = /* @__PURE__ */ new Set([
+	"README.md",
+	"AGENTS.md",
+	"_gitignore",
+	"_env.example",
+	"_oxfmtrc.json"
+]);
+const titleCase = (kebab) => kebab.split("-").map((part) => part === "" ? part : `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`).join(" ");
+const evalCommand = (route, brief) => `npx --yes @keboola/ui-gen-bench eval --serve dist --route ${route} --brief "${brief}" --min-score 90`;
+/**
+* The emitted `gate:ui` script: one `ui-gen-bench eval` per scored route.
+*
+* - The overview's brief names the blocks that are actually on the page, because the score's
+*   brief-conformance axis marks down a page for missing what the brief promises.
+* - A block with a `route` adds a second invocation for it.
+* - Not wired into `test`: it needs a model key, and a first run that fails on a missing
+*   credential is a worse welcome than an opt-in gate.
+*/
+const gateUiScript = (appTitle, blocks) => {
+	const clauses = blocks.filter((id) => BLOCKS[id].route === null).map((id) => BLOCKS[id].brief);
+	const overview = [
+		`${appTitle} overview route: on-brand @keboola/design shell with a full-width header`,
+		...clauses,
+		"no runtime or a11y errors"
+	].join(", ");
+	const extras = blocks.filter((id) => BLOCKS[id].route !== null).map((id) => evalCommand(BLOCKS[id].route ?? "/", `${appTitle} ${BLOCKS[id].brief}: on-brand @keboola/design shell, searchable table, no runtime or a11y errors`));
+	return [evalCommand("/", overview), ...extras].join(" && ");
+};
+const walk = (root, dir, out) => {
+	for (const entry of readdirSync(dir)) {
+		const path = join(dir, entry);
+		if (statSync(path).isDirectory()) walk(root, path, out);
+		else out.push(relative(root, path).split(sep).join("/"));
+	}
+};
+/**
+* `_gitignore` → `.gitignore`: npm strips a real `.gitignore` out of every tarball.
+*
+* - Applied only to `TEMPLATE_DOCS`, the files this package's `templates/` contributes. The
+*   rule exists for them and nothing else.
+* - Not a bare "basename starts with `_`" rule: TanStack's root route is `src/routes/__root.tsx`,
+*   which such a rule renames to `.root.tsx` — the route tree then has no root and the emitted
+*   app fails to generate one.
+*/
+const outputPath = (file) => {
+	const name = basename(file);
+	if (!TEMPLATE_DOCS.has(file) || !name.startsWith("_")) return file;
+	return join(dirname(file), `.${name.slice(1)}`).split(sep).join("/");
+};
+const decideFor = (selected) => (regionId) => {
+	if (regionId === "internal") return "drop";
+	const id = blockIdOf(regionId);
+	if (id === null || !isBlockId(id)) throw new Error(`unknown region id "${regionId}" in the template`);
+	return selected.has(id) ? "keep-without-markers" : "drop";
+};
+const writeManifest = (opts) => {
+	const { templateDir, targetDir, appName, blocks, workspace, engines, packageName } = opts;
+	const manifest = JSON.parse(readFileSync(join(templateDir, "package.json"), "utf8"));
+	const workspaceDeps = JSON.parse(readFileSync(join(templateDir, "workspace-deps.json"), "utf8"));
+	const pkg = manifest;
+	const selected = new Set(blocks);
+	const droppedDeps = new Set(BLOCK_IDS.filter((id) => !selected.has(id)).flatMap((id) => BLOCKS[id].deps));
+	const restore = new Set(workspaceDeps);
+	const resolveGroup = (group) => Object.fromEntries(Object.entries(group).filter(([name]) => !droppedDeps.has(name)).map(([name, range]) => [name, workspace && restore.has(name) ? "workspace:^" : range]));
+	pkg.name = packageName;
+	if (engines !== void 0) pkg.engines = { ...engines };
+	pkg.dependencies = resolveGroup(pkg.dependencies);
+	pkg.devDependencies = resolveGroup(pkg.devDependencies);
+	pkg.scripts = {
+		...pkg.scripts,
+		"gate:ui": gateUiScript(titleCase(appName), blocks),
+		...workspace ? {
+			"knip:check": `pnpm --dir ../.. exec knip --workspace apps/${appName}`,
+			"knip:fix": `pnpm --dir ../.. exec knip --workspace apps/${appName} --fix-type types,exports,files`
+		} : {}
+	};
+	writeFileSync(join(targetDir, "package.json"), `${JSON.stringify(pkg, null, 2)}\n`);
+};
+const scaffold = (opts) => {
+	const { templateDir, targetDir, appName, blocks, workspace } = opts;
+	if (existsSync(targetDir)) throw new Error(`${targetDir} already exists. Choose another name or remove the directory first.`);
+	const selected = new Set(blocks);
+	const decide = decideFor(selected);
+	const vars = {
+		APP_NAME: appName,
+		APP_TITLE: titleCase(appName)
+	};
+	const templateFiles = [];
+	walk(templateDir, templateDir, templateFiles);
+	mkdirSync(targetDir, { recursive: true });
+	const written = [];
+	for (const file of templateFiles.sort()) {
+		if (TEMPLATE_METADATA.has(file)) continue;
+		const owner = ownerOf(file);
+		if (owner === null && !TEMPLATE_DOCS.has(file)) throw new Error(`${file} is in the template but no block or the shell claims it — update src/blocks.ts`);
+		if (owner !== null && owner !== "shell" && !selected.has(owner)) continue;
+		const out = join(targetDir, outputPath(file));
+		mkdirSync(dirname(out), { recursive: true });
+		const buffer = readFileSync(join(templateDir, file));
+		if (buffer.subarray(0, 8e3).includes(0)) writeFileSync(out, buffer);
+		else {
+			const rendered = substitute(renderRegions(buffer.toString("utf8"), decide), vars);
+			assertNoMarkers(outputPath(file), rendered);
+			writeFileSync(out, rendered);
+		}
+		written.push(outputPath(file));
+	}
+	const packageName = workspace ? `@keboola/${appName}` : appName;
+	writeManifest({
+		...opts,
+		packageName
+	});
+	written.push("package.json");
+	return {
+		path: targetDir,
+		appName,
+		packageName,
+		blocks,
+		files: written.sort()
+	};
+};
+//#endregion
+//#region src/cli.ts
+const TEMPLATE_DIR = fileURLToPath(new URL("./template/", import.meta.url));
+/**
+* What to do when there is nobody to ask.
+*
+* - A missing `--name` is an error: there is no sane default for it, and a prompt an agent
+*   cannot answer is worse than a non-zero exit.
+* - A missing `--blocks` defaults to every block, which is the shape `apps/boilerplate` has and
+*   the most useful thing to hand someone who did not choose.
+*/
+const resolveNonInteractive = (options) => {
+	if (options.name === null) return {
+		ok: false,
+		errors: ["No app name, and no terminal to prompt on. Pass --name <kebab-name> (or a bare positional)."]
+	};
+	return {
+		ok: true,
+		name: options.name,
+		blocks: options.blocks ?? BLOCK_IDS
+	};
+};
+const nextSteps = (result, workspace) => workspace ? [
+	"pnpm install",
+	`pnpm dev --filter=${result.packageName}`,
+	`pnpm lint --filter=${result.packageName} && pnpm type-check --filter=${result.packageName} && pnpm test --filter=${result.packageName}`,
+	`Read apps/${result.appName}/AGENTS.md, then node_modules/@keboola/design/AGENTS.md.`
+] : [
+	`cd ${result.appName}`,
+	"pnpm install",
+	"pnpm dev",
+	"Read AGENTS.md, then node_modules/@keboola/design/AGENTS.md."
+];
+/**
+* Writes `src/routeTree.gen.ts` for the routes that were actually copied.
+*
+* - Same code path the Vite plugin takes, so the tree matches what `pnpm dev` would write.
+* - Run now rather than left to the first build, so the emitted app type-checks before it is
+*   ever built.
+* - A failure is fatal: an app whose `pnpm type-check` fails on a missing route tree is not a
+*   deliverable, and the message says how to recover.
+*/
+const generateRouteTree = async (appDir) => {
+	try {
+		const { Generator, getConfig } = await import("@tanstack/router-generator");
+		await new Generator({
+			config: getConfig({
+				quoteStyle: "single",
+				semicolons: true
+			}, appDir),
+			root: appDir
+		}).run();
+	} catch (error) {
+		throw new Error(`Could not generate src/routeTree.gen.ts in ${appDir}: ${error instanceof Error ? error.message : String(error)}\n  The app is otherwise complete — run \`pnpm install && pnpm build\` in it (the Vite plugin writes the file), or remove the directory and try again.`);
+	}
+};
+/**
+* Adds the new app to the monorepo's knip config.
+*
+* - knip keys its per-workspace entry and project globs by path, so an unregistered app
+*   inherits knip's defaults and reports its postcss config as unused.
+* - The boilerplate's block is copied as-is: every scaffolded app has the same `src/` layout.
+*/
+const registerKnipWorkspace = (repoRoot, appName) => {
+	const knipPath = join(repoRoot, "knip.json");
+	if (!existsSync(knipPath)) return;
+	const config = JSON.parse(readFileSync(knipPath, "utf8"));
+	const workspaces = Reflect.get(config, "workspaces");
+	if (typeof workspaces !== "object" || workspaces === null) return;
+	const source = Reflect.get(workspaces, "apps/boilerplate");
+	if (source === void 0) return;
+	Reflect.set(workspaces, `apps/${appName}`, JSON.parse(JSON.stringify(source)));
+	writeFileSync(knipPath, `${JSON.stringify(config, null, 2)}\n`);
+};
+/**
+* The monorepo root's own `engines`, for the emitted app to inherit under `--workspace`.
+*
+* - syncpack (`pnpm deps:check`) compares `engines.node` across every workspace, so an app
+*   carrying the template's standalone floor makes the whole repo's check red.
+* - `undefined` when the root declares none — `scaffold` then keeps the template's value.
+*/
+const monorepoEngines = (root) => {
+	const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+	const engines = Reflect.get(manifest, "engines");
+	if (typeof engines !== "object" || engines === null) return void 0;
+	return Object.fromEntries(Object.entries(engines).filter((entry) => typeof entry[1] === "string"));
+};
+const promptFor = async (options) => {
+	const rl = createInterface({
+		input: stdin,
+		output: stdout
+	});
+	try {
+		let name = options.name;
+		while (name === null || !KEBAB_NAME_RE.test(name)) {
+			if (name !== null) stdout.write(`  \`${name}\` is not a kebab-case name.\n`);
+			name = (await rl.question("App name (kebab-case): ")).trim();
+		}
+		if (options.blocks !== null) return {
+			name,
+			blocks: options.blocks
+		};
+		stdout.write("\nBlocks (blank for all):\n");
+		for (const id of BLOCK_IDS) stdout.write(`  ${id.padEnd(10)} ${BLOCKS[id].summary}\n`);
+		const answer = (await rl.question("\nComma-separated ids, or `none`: ")).trim();
+		if (answer === "") return {
+			name,
+			blocks: BLOCK_IDS
+		};
+		if (answer === "none") return {
+			name,
+			blocks: []
+		};
+		const ids = answer.split(",").map((id) => id.trim());
+		const unknown = ids.filter((id) => !isBlockId(id));
+		if (unknown.length > 0) throw new Error(`Unknown block(s): ${unknown.join(", ")}. Valid blocks: ${BLOCK_IDS.join(", ")}.`);
+		return {
+			name,
+			blocks: ids.filter(isBlockId)
+		};
+	} finally {
+		rl.close();
+	}
+};
+const main = async () => {
+	const parsed = parseArgs(argv.slice(2));
+	if (!parsed.ok) {
+		for (const error of parsed.errors) stderr.write(`✗ ${error}\n`);
+		stderr.write("  Run with --help for the full flag list.\n");
+		exit(1);
+	}
+	const { options } = parsed;
+	if (options.help) {
+		stdout.write(HELP);
+		return;
+	}
+	const log = (line) => {
+		(options.json ? stderr : stdout).write(`${line}\n`);
+	};
+	const interactive = !options.yes && stdin.isTTY === true;
+	let name;
+	let blocks;
+	if (interactive) ({name, blocks} = await promptFor(options));
+	else {
+		const resolved = resolveNonInteractive(options);
+		if (!resolved.ok) {
+			for (const error of resolved.errors) stderr.write(`✗ ${error}\n`);
+			exit(1);
+		}
+		({name, blocks} = resolved);
+	}
+	const root = cwd();
+	if (options.workspace && !existsSync(join(root, "pnpm-workspace.yaml"))) {
+		stderr.write("✗ --workspace expects the current directory to be a pnpm monorepo root (no pnpm-workspace.yaml here).\n");
+		exit(1);
+	}
+	const targetDir = options.workspace ? resolve(root, "apps", name) : resolve(root, name);
+	const result = scaffold({
+		templateDir: TEMPLATE_DIR,
+		targetDir,
+		appName: name,
+		blocks,
+		workspace: options.workspace,
+		engines: options.workspace ? monorepoEngines(root) : void 0
+	});
+	await generateRouteTree(targetDir);
+	if (options.workspace) registerKnipWorkspace(root, name);
+	const steps = nextSteps(result, options.workspace);
+	if (options.json) stdout.write(`${JSON.stringify({
+		path: result.path,
+		appName: result.appName,
+		packageName: result.packageName,
+		blocks: result.blocks,
+		files: result.files.length,
+		nextSteps: steps
+	}, null, 2)}\n`);
+	log(`✓ ${result.packageName} — ${result.files.length} files, blocks: ${blocks.join(", ") || "none"}`);
+	log("");
+	log("Next steps");
+	steps.forEach((step, index) => log(`  ${index + 1}. ${step}`));
+};
+/**
+* Whether this module is the process entry point.
+*
+* - `realpathSync` on both sides, because the installed `bin` is a symlink: npm and pnpm invoke
+*   `node_modules/.bin/create-keboola-app`, so `argv[1]` is the link, not `dist/cli.js`. An
+*   `endsWith('cli.js')` check — which is enough for `extract.ts` and `sanitize.ts`, both
+*   invoked by path — would answer `false` for every real install.
+* - Guarded at all so importing the module does not run it: `cli.test.ts` imports
+*   `resolveNonInteractive` and `nextSteps`, and an unguarded `main()` would scaffold, then
+*   `exit(1)` out of the test worker.
+*/
+const isEntryPoint = () => {
+	const entry = argv[1];
+	if (entry === void 0) return false;
+	try {
+		return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+	} catch (error) {
+		stderr.write(`! could not resolve the entry point, not running: ${String(error)}\n`);
+		return false;
+	}
+};
+if (isEntryPoint()) try {
+	await main();
+} catch (error) {
+	stderr.write(`✗ ${error instanceof Error ? error.message : String(error)}\n`);
+	exit(1);
+}
+//#endregion
+export { nextSteps, resolveNonInteractive };