@plitzi/cli 0.37.1 → 0.37.2

package/CHANGELOG.md

@@ -1,5 +1,150 @@
 # @plitzi/cli
 
+## 0.37.2
+
+### Patch Changes
+
+- ## Authoring and agents
+  - **A step's params are templates in full.** Only a bare name (`{{ post.slug }}`) used to be recognised, so a
+    condition or a loop in a `setState` or a webhook body was handed on as its own text — a flag set to
+    `{% if … %}1{% endif %}` stored the template, a non-empty string every later check read as true. Any `{{ }}` or
+    `{% %}` in a param is now evaluated; what it resolves to is data and is not evaluated again.
+  - **Twig tests work.** `x is defined`, `is empty`, `is null`, `is iterable`, `is even`, `is odd` (and `is not …`) used
+    to be read as comparisons with a variable of that name — `x is defined` answered true exactly when `x` was not
+    defined. Anything else on the right of `is` still compares.
+  - **A group takes an access chain.** `(rows|find('id', 3)).title` read the whole row; the key after the parenthesis
+    was never parsed.
+  - **An expression that chose to be empty renders empty** under `keepEmptyTokens`. A kept token is for a name still
+    waiting for a value; `{{ on ? 'active' : '' }}` said "nothing" on purpose, and handing back its text made the
+    empty branch a non-empty string.
+  - **Checkbox params written as text are booleans.** `dateConverter({ isUnix: 'false' })` read `'false'` as yes and
+    gave an ISO date back raw. Every utility's checkbox params are normalised before its callback runs.
+  - **`condition-starts-visible`** warns about a visibility computed from data on an element that starts on screen: it
+    is drawn until its provider answers and then hidden — an empty state or a "get started" card flashing past on
+    every load. `visible: false` makes it wait hidden. The export reads a visibility binding back in its place, so a
+    space whose condition is not its last binding round-trips unchanged.
+  - **A source named by its short id inside a binding's template is refused** with the full name, as it already was in
+    a flow: `{{ stats.total }}` resolved to nothing and the element showed its empty branch.
+  - **`activeOn(class, pageIds)`** marks a menu's current entry from `navigation.currentPageId` — one binding for a menu
+    kept in a layout. `variantFrom` now says `append: 'true'`, which is what it did.
+  - **Two elements with one id** name where the first one was written. **`template-never-resolved`** warns about a
+    condition left in an attribute, which only resolves `{{ name|filter }}` tokens.
+  - **The authoring skill is a folder**: `SKILL.md` plus references for layouts, data and visibility, templates,
+    flows, structure, testing and a review checklist. `plitzi create` copies all of it, and writes an `AGENTS.md`
+    (imported by `CLAUDE.md`) pointing any agent at it.
+
+  - **A new space starts on a page worth keeping.** The space `POST /spaces` and `plitzi create` both begin from is
+    redesigned: a top bar with the theme switch, a hero with two calls to action, and six guides — each a card linking to
+    its page of the docs (`https://plitzi.com/docs/…`). Every link used to be `#`, and one promised a course that does
+    not exist. The palette is a set of light/dark tokens in Geist, the guides are one list mapped to one card, and the
+    bands of the page share a `shell` class — the page is written the way the authoring skill asks a space to be.
+  - **The copy `plitzi create` writes passes its own project's lint.** An import of the package that would not fit
+    120 columns is wrapped one name per line, as the project's formatter would wrap it.
+
+  ## Server actions and scheduled jobs
+
+  **Scheduled jobs across replicas, out of the box, on the database a deployment already runs.** The scheduler and the
+  workers were already the package's; where the jobs wait was left to each deployment to write — and a queue is the part
+  that is easiest to get subtly wrong. Two helpers now build the adapters over a store the deployment owns, without the
+  package opening a connection or keeping data of its own:
+
+  - `@plitzi/sdk-server/mongo` — `createMongoJobQueue({ db })` and `createMongoKv({ db })`, over a `Db` (or a getter for a
+    client that reconnects). Creates the indexes its queries need; `mongodb` is an optional peer, used for its types.
+  - `@plitzi/sdk-server/mysql` — `createMysqlJobQueue({ pool })` and `createMysqlKv({ pool })`, over a `mysql2` pool.
+    Each job is claimed by a single-row compare-and-set, so replicas claiming at once never deadlock. Creates its three
+    tables on first use, or hands them to your own migrations through `mysqlJobSchemaStatements()`.
+
+  Every instant is the database server's, never a replica's. The in-process queue and both helpers pass one contract test
+  suite: exactly-once enqueue, atomic claims, leases that lapse and are reaped, heartbeats, settlements ignored from a
+  worker that lost its claim, refunded hand-backs, schedules advanced by compare-and-set, operator retry and cancel.
+
+  **`closeOnSignals(server, { afterClose })`** closes the server on SIGTERM/SIGINT and exits only once it has — so a
+  deploy finishes the jobs a replica is running and leaves the waiting ones for the next. A second signal exits at once.
+  Opt-in: a host with its own signal handling calls `server.close()` itself. Projects from `plitzi create` use it.
+
+  **A replica that is told to stop finishes the jobs it is running — and only those.** `server.close()` (and the job
+  worker's `stop()`) now waits for every running job to end however long past its lease that is, and keeps renewing
+  their claims while it waits. It used to stop renewing the moment the drain began and give up at the lease: a job longer
+  than its lease was taken over by another replica and run a second time while the first was still finishing it, and the
+  process exited in the middle of it. What is still waiting is not touched — it stays in the shared queue for the replica
+  that is staying or the one the deploy starts — and a job claimed in the instant the stop arrived is handed back with its
+  attempt refunded, never started. A run is bounded by its own timeout, which is the number an orchestrator's grace period
+  has to cover.
+
+  - **An every-minute schedule fired every other minute.** After producing a fire, the scheduler asked for the next
+    one from `lateness + 1 minute`, and `cronNextFire` rounds up to a whole minute — so a sweep that ran even a second
+    late (with the default 15-second sweep, nearly all of them) skipped the minute it should have produced. It now asks
+    from the minute after the one the sweep ran in. Only expressions with consecutive-minute fires were affected;
+    hourly and daily schedules were not.
+  - **A job that gives up says which step failed and why.** Its `error` and the failed attempt in its history used to
+    read "the flow ended failed" for every failure there is; they now read `step "<id>" failed: <message>`, taken from
+    the run's outline — already redacted of every credential the run resolved, so nothing reaches the job that the
+    run history would not show.
+  - **`apiContainer` takes `refreshSeconds`**: it asks again on its own every N seconds, for a page showing something
+    still moving — a queue, a feed, a status board. It is the same refresh `performQuery` runs, so it works for both
+    runtimes (a browser request is sent again; a server provider asks for its own RSC slice again). It pauses while
+    the tab is hidden and never starts a refresh while the last one is in flight. `0`, the default, never does. Before
+    this a live server provider needed a plugin element of its own to call `useRscRefresh` on a timer: `onApiSuccess`
+    never fires for a server provider, so there was no way to author the loop. The builder shows it as "Refresh every
+    (s)" for either runtime.
+  - **`onApiSuccess` / `onApiError` fire for a server provider.** The declaration offered them for every
+    `apiContainer`, but they were decided from the browser request alone — which a `runtime: 'server'` provider never
+    makes — so a flow wired to them never ran. They now fire when the provider's slice arrives (or the payload arrives
+    without it), and again on each refresh, the same as a browser refetch. A payload resolved for another page fires
+    neither. **A space that wired a flow to one of them will now see it run.**
+  - **The theme toggle shows one icon by default.** It renders both — which one is right depends on stored state, and
+    markup that depended on it would differ between the server and the browser — and until now every space had to copy
+    ten lines of `customCss` to hide the other; one that did not showed a sun and a moon side by side. The SDK's base
+    layer now shows the icon of the scheme in use, and a space's own rule still wins.
+  - **`variantFrom(cls, source)`** in `@plitzi/sdk-authoring` binds which of a CLASS's variants an element wears to a
+    value in the data — a status pill that is amber while a job waits and green once it is done. Written by hand the
+    variant key is the trap: it names the selector the variants belong to, and the element's type (`text.base`) is a
+    different selector from its class (`statusPill.base`), so the element rendered with no variant and nothing
+    reported it. The helper takes the key from the class declaration.
+  - **`authorSpace` refuses a flow template that reads a source by its short name.** A binding completes the prefix
+    (`jobRows.item.id` → `list_jobRows.item.id`), so the short form is the one an author learns first; a step's params
+    are read as written, and there it resolved to nothing — a row's button posted an empty id and every layer below
+    reported success. The error names the full source. A root that is a step of the same flow is left alone.
+  - New example, [`05-with-server-actions/05-schedules`](../examples/05-with-server-actions/05-schedules): scheduled and
+    delayed jobs on a self-hosted server, with the `ActionJobQueue` and `kv` seams written out in full over one SQLite
+    file, two replicas sharing it, failover when one is killed, and a board that watches it happen.
+
+  ## Rendering, data and styles
+  - **A server element inside a layout is resolved.** `collectServerElements` walked the page alone, so a
+    `runtime: 'server'` provider in a layout — a dashboard's sidebar, a section's header — was never resolved: the RSC
+    payload came back empty and the element rendered with nothing. It now walks the page and every shell in its layout
+    chain.
+  - **The twig `date` filter reads an epoch.** `new Date("1790143200000")` is Invalid Date, so an epoch in milliseconds
+    handed over as text — how an attribute passes one — formatted as nothing. A number, or a string of digits, is now
+    read as milliseconds.
+  - **An action is called by its name, not by its trigger kind.** `actionName` took the first trigger's title, and a
+    trigger nobody named is titled with its kind — so every rendered action in a workspace read "render" and every clock
+    "schedule". A title that only repeats the kind is no longer a name, and `defineAction` titles each trigger with the
+    action's name.
+  - **`variant` on an element that wears a class is that class's variant** when the class declares it and the type does
+    not. Keyed by the type, `text({ class: avatar, variant: 'violet' })` named `text--violet`, a selector nothing wears,
+    and rendered with no variant at all. Exporting a document back to authoring reads the same key back into `variant`.
+  - **`variantFrom` takes `{ slot, template }`**, where `template` turns a value into a variant name for data that does
+    not already speak in them — `"{{ source == 'code' ? 'on' : '' }}"`. The third argument was the slot name alone.
+  - **Entry declarations no longer alternate with `export {}`.** In `@plitzi/sdk-server` and `@plitzi/sdk-mcp` a repeated
+    `build:dev` left some `dist/<entry>.d.ts` as a ten-byte `export {}`, and consumers saw "has no exported member". The
+    cause was `insertTypesEntry` writing a types entry over the real declaration of the same path; it is gone.
+  - **Signing in keeps what a guest was doing.** `runtimeStatePersist` reset `runtime.state` whenever its owner changed,
+    and a guest becoming a user is a change — so a sign-in screen that remembered where to send somebody (`?redirect=`)
+    forgot it the moment the session arrived, and the sign-in ended on the fallback page instead. Only a change FROM an
+    account resets now: one account's state still never reaches the next, and a guest has no account to protect.
+
+  **A value with functions inside functions is written as it was given, and fast.** A CSS value was split into layers
+  at commas by a pattern that could only see one level of parentheses, so `var(--bg, light-dark(#fff, #111))` was cut at
+  its inner comma and half a function went on into the stylesheet. The half was then tokenised by an expression that
+  nested one quantifier inside another and backtracked exponentially on it — nearly two seconds for thirty characters,
+  on every generation of that selector's cache. Both are now one linear scan that splits only outside parentheses and
+  quotes. Generated caches keep the spacing the value was written with inside functions (`repeat(3, minmax(0, 1fr))`,
+  `color-mix(in oklab, oklch(…) 50%, transparent)`), where they used to drop it after the first comma.
+
+- Updated dependencies
+  - @plitzi/sdk-authoring@0.37.2
+
 ## 0.37.1
 
 ### Patch Changes

package/README.md

@@ -8,28 +8,35 @@ npx @plitzi/cli create my-site
 
 ## `create`
 
-Scaffolds a project that renders a Plitzi space, installs it, and leaves it ready to start. Two decisions shape
-it and nothing else does:
+Scaffolds a project that renders a Plitzi space, installs it, and leaves it ready to start. Three choices shape it —
+the package manager, `--mode` and `--source` — and they are the person's to make, so `create` never makes them alone:
+
+- **At a terminal**, anything not passed is asked for, with the likely answer offered as the default.
+- **With nobody at the terminal** — an agent, CI — it stops before writing anything and prints the flags still
+  missing, so the agent asks the person rather than guessing. `--yes` takes the defaults (`server`, `local`, the
+  invoking package manager) for a script that genuinely means them.
 
 | | `--source local` | `--source cloud` |
 |---|---|---|
-| **`--mode server`** (default) | A page server of your own, rendering a space that lives in the project. No account. | A page server of your own, rendering the live space out of Plitzi. |
+| **`--mode server`** | A page server of your own, rendering a space that lives in the project. No account. | A page server of your own, rendering the live space out of Plitzi. |
 | **`--mode client`** | Vite + the SDK in the browser. No server at all, no account. | The SDK fetches the space from Plitzi with the public render key. |
 
 ```bash
-plitzi create my-site                          # server + local: the default, and the one that needs nothing
-plitzi create my-site --mode client            # browser-rendered, Vite, hot module replacement
-plitzi create my-site --source cloud --key …   # read the live space out of Plitzi
-plitzi create . --force --no-install           # write into a directory that has work in it, install nothing
-plitzi create my-site --package-manager yarn   # run it with npx, work in it with yarn
+plitzi create my-site                                                 # asks the three choices
+plitzi create my-site --package-manager npm --mode server --source local
+plitzi create my-site --package-manager pnpm --mode client --source local   # Vite, hot module replacement
+plitzi create my-site --package-manager yarn --mode server --source cloud --key …   # the live space
+plitzi create my-site --yes                                           # server + local + the invoking manager
+plitzi create . --force --no-install --yes                            # into a directory that has work in it
 ```
 
 ## The package manager
 
 `--package-manager npm|yarn|pnpm` says which one the project is written for: what it installs with, and what
-every command in its README and its Playwright config names. Omitted, it is taken from the one that invoked the
-CLI — so `yarn dlx` and `pnpm dlx` get their own commands back — but that is a guess about the *invocation*, and
-running `npx` once to scaffold a project you then work in with Yarn is exactly the case it gets wrong.
+every command in its README and its Playwright config names. The one that invoked the CLI is only offered as the
+default when it is asked for — `yarn dlx` and `pnpm dlx` get their own name suggested — because it is a guess about
+the *invocation*: running `npx` once to scaffold a project you then work in with Yarn is exactly the case it gets
+wrong.
 
 A Yarn project also gets a `.yarnrc.yml` pinning `nodeLinker: node-modules`. Yarn 4 installs Plug'n'Play by
 default and a server-mode project cannot start under it — `node --import tsx` dies resolving its own entry — so

package/dist/index.js

@@ -2,11 +2,11 @@
 import { Option, program } from "commander";
 import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
-import path from "node:path";
+import path, { dirname, join, relative, sep } from "node:path";
 import readline from "node:readline/promises";
 import chalk from "chalk";
 import { createRequire } from "node:module";
-import { readFileSync } from "node:fs";
+import { readFileSync, readdirSync } from "node:fs";
 import { blankSpaceSource } from "@plitzi/sdk-authoring";
 //#region src/scaffold/client.ts
 /**
@@ -666,9 +666,56 @@ ${spaceSection(answers)}
 ## The skills
 
 \`.claude/skills/\` carries Plitzi's authoring skill, so an agent working in this repository knows how a space is
-put together before it touches one. It is read by Claude Code automatically; nothing to wire.
+put together before it touches one. Claude Code reads it automatically; \`AGENTS.md\` points any other agent at it.
 `;
 /**
+* What any agent opening the project reads first, whichever agent it is.
+*
+* The skill in \`.claude/skills/\` is found by Claude Code on its own; other agents look for \`AGENTS.md\`. So this
+* file carries the commands, where the space is, and the rules that go wrong most — and points at the skill for the
+* rest. \`CLAUDE.md\` imports it, so both kinds of agent start from the same page.
+*/
+var agentsFile = (answers) => {
+	const code = (value) => `\`${value}\``;
+	const run = (script) => code(runCommand(answers.packageManager, script));
+	const local = answers.source === "local";
+	const where = local ? `The space is ${code("src/space.ts")}, declared with ${code("@plitzi/sdk-authoring")}. Edit that; never the JSON it produces.` : "The space lives in Plitzi and is edited in the builder (or by an agent over MCP); this project serves it.";
+	const commands = [
+		`| ${code(installCommand(answers.packageManager))} | install |`,
+		`| ${run("start")} | serve it |`,
+		...local ? [`| ${run("author")} | author the space and print its warnings |`] : [],
+		`| ${run("visual")} | open the page in a browser and check it rendered |`
+	];
+	const zeroWarnings = local ? `Zero warnings from ${run("author")}.` : "Zero warnings from authoring.";
+	return `# ${answers.name} — notes for agents
+
+A Plitzi space, rendered ${answers.mode === "server" ? "by the server in this project (SSR + RSC)" : "in the browser by a Vite app"}.
+${where}
+
+## Commands
+
+| | |
+| --- | --- |
+${commands.join("\n")}
+
+## Before anything else
+
+Read ${code(".claude/skills/plitzi-authoring/SKILL.md")} — how a space is written, and the references it links to for
+layouts, data, templates and flows. The types of ${code("@plitzi/sdk-authoring")} document every factory and field.
+
+## The rules that go wrong most
+
+- Never write schema/style JSON by hand; author it. A refusal names the fix — fix the declaration.
+- ${zeroWarnings}
+- Chrome shared by pages is a layout; a look used twice is a class; a repeated block is a function or a ${code("map")}.
+- Ids are one namespace for the whole space: name what is referred to, prefix ids made by a helper.
+- Elements are visible by default. One the logic REVEALS starts hidden (${code("visible")}, or ${code("visible: false")} plus a computed binding) so nothing flashes while loading; one a flag HIDES stays shown while the flag is unset.
+- Inside a template a source is spelled in full (${code("apiContainer_stats")}); an attribute only resolves ${code("{{ name|filter }}")}.
+- Colours are tokens with light and dark values; times carry an explicit zone and say it.
+- Go through ${code(".claude/skills/plitzi-authoring/reference/review-checklist.md")} before calling a change done.
+`;
+};
+/**
 * The credential, and the prefix it has to carry.
 *
 * Vite only exposes variables named `VITE_*` to the browser, which is a safety rail rather than a formality: a
@@ -697,6 +744,8 @@ var projectFiles = (answers) => ({
 	"tsconfig.json": tsconfig(answers),
 	".gitignore": gitignore(answers),
 	"README.md": readme(answers),
+	"AGENTS.md": agentsFile(answers),
+	"CLAUDE.md": "@AGENTS.md\n",
 	...answers.source === "cloud" ? { ".env": envFile(answers) } : {}
 });
 //#endregion
@@ -811,7 +860,7 @@ const plugins = {
 const pluginNames = Object.keys(plugins);`;
 var localMain = () => `import path from 'node:path';
 
-import { consoleLogger, createJsonAdapters, createServer } from '@plitzi/sdk-server';
+import { closeOnSignals, consoleLogger, createJsonAdapters, createServer } from '@plitzi/sdk-server';
 
 import { authorSpace } from '@plitzi/sdk-authoring';
 
@@ -823,9 +872,15 @@ const PORT = Number(process.env.PORT ?? 8080);
  * The space, held in this project.
  *
  * \`authorSpace\` turns the declaration in \`src/space.ts\` into the two documents a renderer wants. It runs at
- * boot, so saving that file and letting \`--watch\` restart it is the whole edit loop.
+ * boot, so saving that file and letting \`--watch\` restart it is the whole edit loop — and its warnings are printed
+ * here for the same reason: this restart is the output somebody editing the space is actually watching.
  */
-const offlineData = authorSpace(space);
+const { schema, style, warnings } = authorSpace(space);
+const offlineData = { schema, style };
+
+for (const warning of warnings) {
+  console.warn(\`[author] \${warning.message}\`);
+}
 
 ${PLUGINS}
 
@@ -849,10 +904,17 @@ const server = createServer({
 
 server.listen(PORT, '127.0.0.1');
 console.log(\`pages on http://127.0.0.1:\${PORT}/\`);
+
+/**
+ * A deploy, a restart or ^C closes the server instead of dropping it: requests in flight are answered, and once the
+ * space runs scheduled actions, the jobs this server is running finish first — what is still waiting stays in the
+ * queue for whichever server runs next. A second ^C exits at once.
+ */
+closeOnSignals(server);
 `;
 var cloudMain = () => `import path from 'node:path';
 
-import { consoleLogger, createCloudAdapters, createServer } from '@plitzi/sdk-server';
+import { closeOnSignals, consoleLogger, createCloudAdapters, createServer } from '@plitzi/sdk-server';
 
 const PORT = Number(process.env.PORT ?? 8080);
 
@@ -899,6 +961,13 @@ const server = createServer({
 
 server.listen(PORT, '127.0.0.1');
 console.log(\`pages on http://127.0.0.1:\${PORT}/\`);
+
+/**
+ * A deploy, a restart or ^C closes the server instead of dropping it: requests in flight are answered, and once the
+ * space runs scheduled actions, the jobs this server is running finish first — what is still waiting stays in the
+ * queue for whichever server runs next. A second ^C exits at once.
+ */
+closeOnSignals(server);
 `;
 var serverFiles = (answers) => ({ "src/main.ts": answers.source === "cloud" ? cloudMain() : localMain() });
 //#endregion
@@ -928,10 +997,23 @@ var SKILLS = [{
 * however present it is on disk.
 */
 var skillPath = (packageName, skill) => require.resolve(`${packageName}/skills/${skill}/SKILL.md`);
+/**
+* Every file under a skill's folder, by its path inside it.
+*
+* A skill is a folder, not a file: \`SKILL.md\` is the short part an agent reads first, and the references it links to
+* sit beside it and are opened when the task needs them. Copying \`SKILL.md\` alone left every one of those links
+* pointing at nothing.
+*/
+var filesUnder = (root, folder = root) => readdirSync(folder, { withFileTypes: true }).flatMap((entry) => {
+	const path = join(folder, entry.name);
+	if (entry.isDirectory()) return filesUnder(root, path);
+	return entry.isFile() ? [[relative(root, path).split(sep).join("/"), readFileSync(path, "utf-8")]] : [];
+});
 var skillFiles = () => {
 	const files = {};
 	for (const skill of SKILLS) try {
-		files[`.claude/skills/${skill.name}/SKILL.md`] = readFileSync(skillPath(skill.package, skill.name), "utf-8");
+		const root = dirname(skillPath(skill.package, skill.name));
+		for (const [path, content] of filesUnder(root)) files[`.claude/skills/${skill.name}/${path}`] = content;
 	} catch {
 		continue;
 	}
@@ -1121,6 +1203,8 @@ var scaffold = (answers) => ({
 });
 //#endregion
 //#region src/commands/create.ts
+var MODES = ["server", "client"];
+var SOURCES = ["local", "cloud"];
 /** A directory that does not exist yet is as empty as one can be, which is the answer this question wants. */
 var isEmpty = async (target) => {
 	try {
@@ -1142,7 +1226,6 @@ var nearestExisting = async (target) => {
 	while (!await isDirectory(dir) && path.dirname(dir) !== dir) dir = path.dirname(dir);
 	return dir;
 };
-var oneOf = (value, allowed, fallback) => allowed.includes(value) ? value : fallback;
 /**
 * What a first install is most likely refused over, and what to do about it.
 *
@@ -1164,6 +1247,75 @@ var install = (manager, cwd) => new Promise((resolve) => {
 	child.on("error", () => resolve(false));
 	child.on("close", (code) => resolve(code === 0));
 });
+/** One choice at the terminal: Enter takes the default, anything off the list is refused rather than guessed at. */
+var ask = async (rl, question) => {
+	const reply = (await rl.question(`\n${question.help}\n${question.flag} (${question.choices.join("/")}) [${question.fallback}] > `)).trim();
+	const chosen = question.choices.find((choice) => choice === (reply || question.fallback));
+	if (!chosen) console.error(chalk.red(`"${reply}" is not one of ${question.choices.join(", ")}.`));
+	return chosen;
+};
+var resolveDecisions = async (options) => {
+	const detected = detectPackageManager();
+	const packageManager = {
+		flag: "--package-manager",
+		choices: PACKAGE_MANAGERS,
+		help: `The package manager the project will be worked in (this was run through ${detected}).`,
+		given: PACKAGE_MANAGERS.find((manager) => manager === options.packageManager),
+		fallback: detected
+	};
+	const mode = {
+		flag: "--mode",
+		choices: MODES,
+		help: "server: SSR + RSC on a Node tier. client: browser only.",
+		given: MODES.find((candidate) => candidate === options.mode),
+		fallback: "server"
+	};
+	const source = {
+		flag: "--source",
+		choices: SOURCES,
+		help: "local: the space travels in the project. cloud: read it from Plitzi.",
+		given: SOURCES.find((candidate) => candidate === options.source),
+		fallback: "local"
+	};
+	const missing = [
+		packageManager,
+		mode,
+		source
+	].filter((question) => question.given === void 0);
+	if (missing.length === 0 || options.yes) return {
+		packageManager: packageManager.given ?? packageManager.fallback,
+		mode: mode.given ?? mode.fallback,
+		source: source.given ?? source.fallback
+	};
+	if (!process.stdin.isTTY || !process.stdout.isTTY) {
+		console.error(chalk.red("\nplitzi create needs these decided by whoever the project is for. Ask them; do not assume:"));
+		for (const question of missing) console.error(`  ${`${question.flag} ${question.choices.join("|")}`.padEnd(36)} ${chalk.dim(question.help)}`);
+		const defaults = missing.map((question) => `${question.flag} ${question.fallback}`).join(" ");
+		console.error(chalk.dim(`\nThen run it again with those flags — or with --yes to take ${defaults}.`));
+		process.exitCode = 1;
+		return;
+	}
+	const rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	try {
+		const manager = packageManager.given ?? await ask(rl, packageManager);
+		const tier = manager && (mode.given ?? await ask(rl, mode));
+		const origin = tier && (source.given ?? await ask(rl, source));
+		if (!manager || !tier || !origin) {
+			process.exitCode = 1;
+			return;
+		}
+		return {
+			packageManager: manager,
+			mode: tier,
+			source: origin
+		};
+	} finally {
+		rl.close();
+	}
+};
 var askForKey = async (mode) => {
 	const rl = readline.createInterface({
 		input: process.stdin,
@@ -1184,17 +1336,9 @@ var create = async (directory, options) => {
 		process.exitCode = 1;
 		return;
 	}
-	const mode = oneOf(options.mode, ["server", "client"], "server");
-	const source = oneOf(options.source, ["local", "cloud"], "local");
-	/**
-	* Asked for first, detected second.
-	*
-	* The invoking agent is a good guess and a bad rule: reaching for `npx` to run a scaffold once and then working
-	* in the project with Yarn is an ordinary thing to do, and the guess writes a README, a Playwright config, a
-	* `.gitignore` and an install into that project which all name the wrong one. `--package-manager` is how
-	* somebody says which one they will actually be using.
-	*/
-	const packageManager = oneOf(options.packageManager, PACKAGE_MANAGERS, detectPackageManager());
+	const decisions = await resolveDecisions(options);
+	if (!decisions) return;
+	const { packageManager, mode, source } = decisions;
 	const key = source === "cloud" ? options.key ?? await askForKey(mode) : "";
 	if (source === "cloud" && !key) {
 		console.error(chalk.red("\nNo key. Mint one under Credentials in the builder, then run this again."));
@@ -1256,6 +1400,6 @@ var create = async (directory, options) => {
 * write three files correctly before they could tell whether any of it worked.
 */
 program.name("plitzi").description("Plitzi command line");
-program.command("create").argument("[directory]", "Where to write the project. Defaults to the current directory.").description("Scaffold a project that renders a Plitzi space").option("-m, --mode <mode>", "server (SSR + RSC on a Node tier) or client (browser only)", "server").option("-s, --source <source>", "local (the space travels in the project) or cloud (read it from Plitzi)", "local").option("-k, --key <key>", "Cloud only: the space key (asked for when omitted)").option("-e, --environment <environment>", "Which version to serve: main, or a published environment", "main").addOption(new Option("-p, --package-manager <manager>", "The package manager the project is written for. Defaults to the one that invoked this.").choices([...PACKAGE_MANAGERS])).option("--no-install", "Write the files without installing dependencies").option("-f, --force", "Write into a directory that is not empty").action(create);
+program.command("create").argument("[directory]", "Where to write the project. Defaults to the current directory.").description("Scaffold a project that renders a Plitzi space").addOption(new Option("-m, --mode <mode>", "server (SSR + RSC on a Node tier) or client (browser only)").choices(["server", "client"])).addOption(new Option("-s, --source <source>", "local (the space travels in the project) or cloud (read it from Plitzi)").choices(["local", "cloud"])).option("-k, --key <key>", "Cloud only: the space key (asked for when omitted)").option("-e, --environment <environment>", "Which version to serve: main, or a published environment", "main").addOption(new Option("-p, --package-manager <manager>", "The package manager the project is written for. Asked for when left out.").choices([...PACKAGE_MANAGERS])).option("--no-install", "Write the files without installing dependencies").option("-f, --force", "Write into a directory that is not empty").option("-y, --yes", "Take the defaults for any choice not passed (server, local, the invoking package manager)").action(create);
 program.parse(process.argv);
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plitzi/cli",
-  "version": "0.37.1",
+  "version": "0.37.2",
   "license": "AGPL-3.0",
   "description": "Command line for Plitzi: scaffold a server that renders a space you own.",
   "files": [
@@ -16,12 +16,12 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@plitzi/sdk-authoring": "0.37.1",
+    "@plitzi/sdk-authoring": "0.37.2",
     "chalk": "^6.0.0",
     "commander": "^15.0.0"
   },
   "devDependencies": {
-    "@types/node": "^26.6.1",
+    "@types/node": "^26.6.2",
     "eslint": "^9.39.5",
     "eslint-plugin-import": "^2.32.0",
     "typescript": "^6.0.3",