@zitadel/cli 0.2.0 → 0.4.0

package/dist/{skills-hint-CBoak9HL.mjs → skills-hint-C8oe8cCo.mjs}

@@ -1,19 +1,19 @@
+import { Args, Flags } from "@oclif/core";
 import consola$1, { consola } from "consola";
 import { ApiError, NetworkError, apiErrorCode, apiErrorMessage } from "@zitadel/api/runtime/fetch";
 import { createZitadelClient } from "@zitadel/api/client";
 import { stringify } from "safe-stable-stringify";
-import { copyFile, mkdtemp, readFile, readdir, rm } from "node:fs/promises";
-import { PublishPolicyBody, publishPolicyBodyOneConfigMinLengthMax } from "@zitadel/api/generated/endpoints/zitadelNextGen.zod";
+import { copyFile, lstat, mkdtemp, readFile, readdir, realpath, rm, stat, utimes, writeFile } from "node:fs/promises";
+import { BuildReleaseBody, PublishPolicyBody, publishPolicyBodyOneConfigMinLengthMax } from "@zitadel/api/generated/endpoints/zitadelNextGen.zod";
 import { randomUUID } from "node:crypto";
 import { execFile } from "node:child_process";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir, release, tmpdir } from "node:os";
-import { promisify } from "node:util";
 import { BlockList, isIP } from "node:net";
 import pc from "picocolors";
 import { Agent, getGlobalDispatcher, setGlobalDispatcher } from "undici";
-import { brandingConfigSchema, flowConfigSchema, idpConnectionConfigSchema, policyConfigSchema, schemaConfigSchema } from "@zitadel/config/schemas";
+import { RECOMMENDED_PASSWORD_MIN_LENGTH, brandingConfigSchema, flowConfigSchema, idpConnectionConfigSchema, policyConfigSchema, schemaConfigSchema } from "@zitadel/config/schemas";
 import { PURPOSE_FLIP_TARGETS, validateFlowDefinition, validateProject } from "@zitadel/config/validate";
 import { CUSTOM_PROVIDER, IDP_PROVIDERS, RESERVED_SLUGS, credentialVariables, idpProvider, isLoopbackIssuer, isVariableReference, missingEndpoints, parseConnectionSlug, parseDisplayName, parseIssuer, parseProviderSelection, parseScopes, referencedVariable, selectionName } from "@zitadel/config/idp";
 import { SETUP_PRESETS, getDefaultLoginFlow } from "@zitadel/config/defaults";
@@ -66,6 +66,12 @@ var ZitadelError = class extends Error {
 		return EXIT_CODES[this.code] ?? 1;
 	}
 };
+/** What to do about a request that got no usable response, by its reason. */
+const NETWORK_HINTS = {
+	unreachable: "Check your connection and the server URL (ZITADEL_URL or --server).",
+	timeout: "The server accepted the connection but did not answer in time. Check that it is healthy, then retry.",
+	unreadable: "The server answered, but its response could not be read. Check any proxy between you and the server, then retry."
+};
 /**
 * Normalises any thrown value into a {@link ZitadelError}. Inspection is
 * ordered most-specific-first (already-normalised, HTTP status, then
@@ -87,7 +93,7 @@ function toZitadelError(error) {
 		};
 		if (error.status === 404) {
 			if (apiErrorCode(error) === "req.not_found") return new ZitadelError("E_NOT_FOUND", `${error.url} has no such endpoint on this Zitadel server`, {
-				hint: "The server and this CLI are different versions. Run the CLI release that matches the server, or upgrade the server.",
+				hint: "The server and this CLI are different versions; a server from before the API moved under /api/v1 answers every call so. Run the CLI release that matches the server, or upgrade the server.",
 				details
 			});
 			return new ZitadelError("E_NOT_FOUND", !isPlatformErrorEnvelope(error.body) ? `${apiErrorMessage(error)} — ${error.url} has no such endpoint; is this a Zitadel platform API?` : apiErrorMessage(error), { details });
@@ -117,7 +123,7 @@ function toZitadelError(error) {
 		});
 	}
 	if (error instanceof NetworkError) return new ZitadelError("E_NETWORK", error.message, {
-		hint: error.reason === "timeout" ? "The server accepted the connection but did not answer in time. Check that it is healthy, then retry." : "Check your connection and the server URL (ZITADEL_URL or --server).",
+		hint: NETWORK_HINTS[error.reason],
 		details: {
 			url: error.url,
 			reason: error.reason
@@ -354,20 +360,13 @@ function sanitizeRejection(error) {
 * `timeoutMs`.
 */
 function createZitadelClient$1(opts, sanitize = {}) {
-	const onResolve = sanitize.verbatim ? (value) => value : sanitizeResponse;
-	const client = createZitadelClient({
+	return createZitadelClient({
 		signal: interruptSignal(),
 		timeoutMs: REQUEST_TIMEOUT_MS,
-		...opts
+		...opts,
+		...sanitize.verbatim ? {} : { onResponse: sanitizeResponse },
+		onError: sanitizeRejection
 	});
-	return new Proxy(client, { get(target, prop, receiver) {
-		const value = Reflect.get(target, prop, receiver);
-		if (typeof value !== "function") return value;
-		return (...args) => {
-			const result = value(...args);
-			return result instanceof Promise ? result.then(onResolve, sanitizeRejection) : result;
-		};
-	} });
 }
 //#endregion
 //#region src/lib/json.ts
@@ -562,51 +561,6 @@ function isObject$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 //#endregion
-//#region src/lib/oclif/crud/paging.ts
-/** The list commands' own: `--all`, and `--limit` with `--page-token`. */
-const LIST_FLAGS = {
-	all: "--all",
-	onePage: "--limit and --page-token"
-};
-/**
-* Walk a cursor-paginated endpoint. `request` performs one page; the
-* response must carry the items under `items` and, while more remain, a
-* the cursor property `nextPageToken` names. With `all` the pages are drained
-* in order and `next`
-* is `null`; otherwise one page is fetched and `next` is its token. `flags`
-* names the caller's own flags in the errors.
-*/
-const collectPages = async (request, { items, all, token, nextPageToken, flags = LIST_FLAGS }) => {
-	const collected = [];
-	const seen = /* @__PURE__ */ new Set();
-	let cursor = token;
-	for (;;) {
-		const response = await request(cursor);
-		const page = items === void 0 ? response : isObject$1(response) ? response[items] : void 0;
-		if (!Array.isArray(page)) throw new ZitadelError("E_VALIDATION", items === void 0 ? "Unexpected list response: expected an array" : `Unexpected list response: missing "${items}" array`, { details: { response } });
-		collected.push(...page);
-		const cursor_ = isObject$1(response) ? response[nextPageToken] : void 0;
-		const next = typeof cursor_ === "string" ? cursor_ || null : null;
-		if (!all) return {
-			items: collected,
-			next
-		};
-		if (!next) return {
-			items: collected,
-			next: null
-		};
-		if (seen.has(next)) throw new ZitadelError("E_VALIDATION", `The server repeated a page cursor, so ${flags.all} would never finish`, {
-			hint: `Fetch one page at a time with ${flags.onePage}, and report the repeated cursor.`,
-			details: {
-				cursor: next,
-				pages_fetched: seen.size + 1
-			}
-		});
-		seen.add(next);
-		cursor = next;
-	}
-};
-//#endregion
 //#region src/lib/public-cli.ts
 const CLI_PACKAGE_NAME = "@zitadel/cli";
 function npmDistTagForCliVersion(cliVersion) {
@@ -775,6 +729,41 @@ function inShell(command, shell) {
 	return `${shell.before ?? ""}${command}${shell.after ?? ""}`;
 }
 //#endregion
+//#region src/lib/oclif/flags.ts
+/**
+* Refuse a value that is present but holds nothing.
+*
+* `required: true` is no help: it asks whether a token arrived in argv, and an
+* empty one satisfies it. The way this happens is the shell, not a typo —
+* `--client-id "$CLIENT_ID"` with the variable unset sends exactly that, the
+* expansion dropping the value while the quotes keep the word, so argv carries
+* `["--client-id", ""]`. Unquoted, the word vanishes and oclif refuses with
+* "expects a value"; quoted, nothing complained and the empty string travelled
+* on as if it were a real answer.
+*
+* Refusing during parse rather than in each command puts it at the same point
+* oclif's own refusal lands, so both spellings of a missing value fail the same
+* way, and the value that reaches `run` is already trimmed.
+*/
+function refuseBlank(input, label, message) {
+	const value = input.trim();
+	if (value === "") throw new ZitadelError("E_VALIDATION", message, {
+		hint: `Pass a value for ${label}, or omit it entirely.`,
+		details: { argument: label }
+	});
+	return value;
+}
+/**
+* A string flag whose value must not be blank. See {@link refuseBlank}.
+*
+* Not for a flag that writes a field value: an empty string is a legitimate
+* thing to store, so the generated resource flags in `crud/fields.ts` keep
+* plain `Flags.string`.
+*/
+const nonBlankString = Flags.custom({ parse: async (input, _command, flag) => refuseBlank(input, `--${flag.name}`, "the value is empty") });
+/** A positional argument whose value must not be blank. See {@link refuseBlank}. */
+const nonBlankArg = Args.custom({ parse: async (input, _command, arg) => refuseBlank(input, arg.name, `${arg.name} was given an empty value`) });
+//#endregion
 //#region src/lib/telemetry/dimensions/env-flag.ts
 const DISABLED_VALUES$1 = /* @__PURE__ */ new Set([
 	"",
@@ -1111,6 +1100,69 @@ function takeReportedWarnings() {
 	return reported.splice(0);
 }
 //#endregion
+//#region src/lib/oclif/crud/table.ts
+/**
+* The machine form of a list: one record per line, fields separated by tabs,
+* no header and no padding, so `cut -f2` and `awk -F'\t'` work. This is what a
+* piped run emits — the aligned table is for a terminal, where nothing is
+* parsing it. Tabs and newlines inside a value would break the record, so they
+* are escaped rather than passed through.
+*/
+const renderRows = (columns, items) => items.map((item) => columns.map((column) => readCell(column, item).replaceAll("	", "\\t").replaceAll("\n", "\\n")).join("	")).join("\n");
+/**
+* Render `items` as an aligned text table, one column per dot-path in
+* `columns`, headed by each path's last segment. Nested paths resolve
+* through objects; missing values render empty; non-strings render as JSON.
+*/
+const renderTable = (columns, items) => {
+	const headers = columns.map((column) => column.split(".").at(-1) ?? column);
+	const rows = items.map((item) => columns.map((column) => readCell(column, item)));
+	const widths = rows.reduce((current, row) => current.map((width, i) => Math.max(width, row[i]?.length ?? 0)), headers.map((header) => header.length));
+	const line = (cells) => cells.map((cell, i) => cell.padEnd(widths[i] ?? 0)).join("  ").trimEnd();
+	return [
+		line(headers),
+		line(widths.map((width) => "-".repeat(width))),
+		...rows.map(line)
+	].join("\n");
+};
+/**
+* The whole terminal rendering of a list, so no command re-derives the
+* plain/TTY/empty/footer logic (and so none forgets `--plain`): a pipe (or
+* `--plain`) gets tab-separated rows with no header and nothing when empty, so
+* `cut`/`awk`/`wc -l` work; a terminal gets the aligned table, a blank line, a
+* `${n} ${singular|plural}` count, and any `footer` lines. Pair it with
+* `listData()` for the JSON envelope.
+*/
+const renderList = (columns, rows, opts) => {
+	if (opts.plain) return renderRows(columns, rows);
+	if (rows.length === 0) return opts.empty;
+	const count = `${rows.length} ${rows.length === 1 ? opts.singular : opts.plural ?? `${opts.singular}s`}`;
+	return [
+		renderTable(columns, rows),
+		"",
+		count,
+		...opts.footer ?? []
+	].join("\n");
+};
+/** One cell: a dot-path resolved through objects, rendered as text. */
+const readCell = (column, item) => {
+	const value = column.split(".").reduce((current, key) => isObject$1(current) ? current[key] : void 0, item);
+	return value == null ? "" : typeof value === "string" ? value : JSON.stringify(value);
+};
+/**
+* One record for a person: the heading first, then a labelled field per line.
+* Nested paths are labelled by their last segment, so `metadata.status` reads
+* as `status`. It is the terminal rendering of `get`; a pipe (and `--json`)
+* still receives the whole object, since a script wants the record, not a view
+* of it.
+*/
+const renderDetail = (heading, fields, item) => {
+	const rows = fields.map((field) => [field.split(".").at(-1) ?? field, readCell(field, item)]).filter(([, value]) => value !== "");
+	const width = Math.max(0, ...rows.map(([label]) => label.length));
+	const body = rows.map(([label, value]) => `${label.padEnd(width)}  ${value}`);
+	return [...heading ? [heading, ""] : [], ...body].join("\n");
+};
+//#endregion
 //#region src/lib/variables.ts
 /** The scope a variable write or delete addresses, from the project and `--preview`. */
 function variableScope(projectId, preview) {
@@ -1158,6 +1210,14 @@ function toVariableRows(values) {
 }
 /** Stands in for a secret's value, which the platform never discloses. */
 const SECRET_MARKER = "(secret)";
+/**
+* The variables a deployment froze, as `deployment get` shows them: the
+* `variable resolve` table, indented under a heading.
+*/
+function frozenVariables(rows) {
+	if (rows.length === 0) return "  variables  none";
+	return ["  variables", ...renderTable(["name", "value"], variableCells(rows)).split("\n").map((line) => `    ${line}`)].join("\n");
+}
 /** Stands in for a kind the name holds no value for at all. */
 const NO_VALUE = "-";
 /**
@@ -2004,24 +2064,29 @@ function stepNamed(flow, name) {
 * replacing it, so enabling a second one later keeps the first.
 */
 function applySsoToSchema(schema, slug) {
-	const document = clone(schema);
-	const methods = isObject(document["x-auth-methods"]) ? { ...document["x-auth-methods"] } : {};
+	const copy = clone(schema);
+	const current = "x-auth-methods" in copy ? copy["x-auth-methods"] : void 0;
+	const methods = isObject(current) ? current : {};
 	const existing = isObject(methods.sso) ? methods.sso : void 0;
-	const providers = Array.isArray(existing?.providers) ? [...existing.providers] : [];
+	const providers = Array.isArray(existing?.providers) ? existing.providers : [];
 	if (existing?.enabled === true && providers.includes(slug)) return {
 		document: schema,
 		changed: false,
 		skipped: []
 	};
 	if (!providers.includes(slug)) providers.push(slug);
-	methods.sso = {
-		...existing,
-		enabled: true,
-		providers
-	};
-	document["x-auth-methods"] = methods;
 	return {
-		document,
+		document: {
+			...copy,
+			"x-auth-methods": {
+				...methods,
+				sso: {
+					...existing,
+					enabled: true,
+					providers
+				}
+			}
+		},
 		changed: true,
 		skipped: []
 	};
@@ -3232,9 +3297,11 @@ async function readJsonDir(absDir) {
 }
 /**
 * {@link readJsonDir}, keeping each body's file name — for callers that report
-* a problem against the file it came from.
+* a problem against the file it came from. `skip` leaves out files by name
+* before they are read, so a file the caller does not own (a policy test file
+* beside the policies) can never fail it.
 */
-async function readJsonDirEntries(absDir) {
+async function readJsonDirEntries(absDir, { skip } = {}) {
 	let entries;
 	try {
 		entries = await readdir(absDir);
@@ -3243,7 +3310,7 @@ async function readJsonDirEntries(absDir) {
 		throw error;
 	}
 	const result = [];
-	for (const entry of entries.filter((name) => name.endsWith(".json")).sort()) {
+	for (const entry of entries.filter((name) => name.endsWith(".json") && !skip?.(name)).sort()) {
 		const abs = join(absDir, entry);
 		let raw;
 		try {
@@ -3288,6 +3355,15 @@ function toPolicyWireBody(file) {
 		config: file.config
 	};
 }
+/**
+* The suffix of a policy test file (`<operation>.test.json`), which sits
+* beside the policies but is never deployed: `zitadel policies test` runs it.
+*/
+const POLICY_TEST_SUFFIX = ".test.json";
+/** Whether a file in `.zitadel/policies/` is a test file rather than a policy. */
+function isPolicyTestFile(name) {
+	return name.endsWith(POLICY_TEST_SUFFIX);
+}
 /** The name a policy file must have: its operation, so one file holds one operation's policy. */
 function policyFileName(operation) {
 	return `${operation}.json`;
@@ -3317,7 +3393,7 @@ const PASSWORD_POLICY_PATH = `${POLICIES_DIR}/${policyFileName(PASSWORD_POLICY_O
 * empty `config`, which enforces nothing, for an explicit "none".
 */
 function passwordPolicyFile(minLength) {
-	const value = minLength === void 0 ? 15 : minLength;
+	const value = minLength === void 0 ? RECOMMENDED_PASSWORD_MIN_LENGTH : minLength;
 	return {
 		$schema: POLICY_FILE_SCHEMA_REF,
 		operation: PASSWORD_POLICY_OPERATION,
@@ -3367,7 +3443,7 @@ async function buildBundle(cwd) {
 	const flow_definitions = (await readJsonDir(join(cwd, FLOWS_DIR))).map(stripSchema);
 	const idpEntries = await readJsonDirEntries(join(cwd, IDPS_DIR));
 	const idps = idpEntries.map((entry) => stripSchema(entry.body));
-	const policyEntries = await readJsonDirEntries(join(cwd, POLICIES_DIR));
+	const policyEntries = await readJsonDirEntries(join(cwd, POLICIES_DIR), { skip: isPolicyTestFile });
 	const policies = policyEntries.map((entry) => stripSchema(entry.body));
 	const brandingSources = (await readJsonDir(join(cwd, BRANDING_DIR))).map((descriptor) => ({ ...descriptor }));
 	if (brandingSources.length > 1) throw new ZitadelError("E_VALIDATION", `A release carries at most one branding, but .zitadel/branding/ holds ${brandingSources.length}`, { hint: "A project has a single branding; keep one descriptor under .zitadel/branding/." });
@@ -3391,31 +3467,44 @@ async function buildBundle(cwd) {
 	};
 }
 //#endregion
-//#region src/lib/release/deployment.ts
+//#region src/lib/release/release.ts
 /**
-* Every live deployment of the project, newest first, drained across pages: one
-* live preview per open pull request can push the primary origins' deployment
-* off the first page, and a guard, a baseline or a rollback read from that page
-* alone would quietly miss it.
+* Build a release from the `.zitadel/` bundle (`POST /releases/build`). The
+* server reuses the revisions that already match and allocates the rest, and
+* dedupes on content: re-posting the same bundle returns the release that
+* already carries it. (`POST /releases` pins pre-existing revision ids and is
+* not a CLI flow.)
 */
-async function listLiveDeployments(client, projectId, options = {}) {
-	const { items } = await collectPages((token) => client.listDeployments({
-		project_id: projectId,
-		live: true,
-		...options.origin === void 0 ? {} : { origin: options.origin },
-		...options.withRelease ? { expand: ["release"] } : {},
-		...token === void 0 ? {} : { page_token: token }
-	}), {
-		items: "deployments",
-		all: true,
-		nextPageToken: "next_page_token"
-	});
-	return items;
+async function createReleaseFromBundle(client, projectId, bundle, source) {
+	const body = {
+		bundle,
+		...source.message === void 0 ? {} : { message: source.message },
+		...source.gitSha === null ? {} : { git_sha: source.gitSha },
+		git_dirty: source.gitDirty
+	};
+	assertBuildReleaseBody(body);
+	return client.buildRelease(body, { project_id: projectId });
+}
+/** Refuses a body `POST /releases/build` does not take, naming each field it refuses. */
+function assertBuildReleaseBody(body) {
+	const checked = BuildReleaseBody.safeParse(body);
+	if (!checked.success) {
+		const issues = checked.error.issues;
+		const noun = issues.length === 1 ? "issue" : "issues";
+		throw new ZitadelError("E_VALIDATION", `The release body does not match what the API takes, so nothing was sent (${issues.length} ${noun}):\n` + issues.map((issue) => `  - ${issue.path.join(".") || "(root)"} ${issue.message}`).join("\n"), { details: { issues } });
+	}
+}
+/** Revoke a release so its content is never served again. Idempotent. */
+async function revokeRelease(client, projectId, releaseId) {
+	return client.revokeRelease(releaseId, { project_id: projectId });
 }
+//#endregion
+//#region src/lib/release/deployment.ts
 /**
 * Whether a deployment serves a primary origin. A preview deployment's targets
 * carry an expiry; it is never the baseline, the guard or the thing a bare
-* rollback undoes.
+* rollback undoes. Look for it across every page (`listDeployments.all`): one
+* live preview per open pull request can push it off the first.
 */
 function servesPrimary(deployment) {
 	return deployment.targets.some((target) => target.expires_at == null);
@@ -3450,8 +3539,1148 @@ async function rollbackDeployment(client, projectId, deploymentId, options) {
 	return client.rollbackDeployment(deploymentId, { project_id: projectId }, Object.keys(body).length === 0 ? void 0 : body);
 }
 //#endregion
+//#region src/lib/git/errors.ts
+/**
+* A git operation that failed, with a message ready to show the developer.
+*
+* What the module throws when git fails. The message is git's own (all of
+* its stderr, which often says how to fix the failure), or one of the
+* module's when git said nothing useful: output over 16 MB, a call that timed
+* out. The temporary staging area's file-system calls can still fail with
+* Node's own errors. Whether a failure is fatal is the caller's choice.
+*/
+var RepositoryError = class extends Error {
+	/** Creates the error from its message. */
+	constructor(message) {
+		super(message);
+		this.name = "RepositoryError";
+	}
+	/**
+	* The one line of the message that says why git failed, for a one-line warning; never empty.
+	*
+	* git writes `warning:` and `hint:` lines before and after the line that
+	* gives the reason, so the first `fatal:` or `error:` line is taken, then
+	* the first line, then a fixed phrase when git said nothing.
+	*/
+	headline() {
+		const lines = this.message.split("\n").map((line) => line.trim()).filter((line) => line !== "");
+		const reason = lines.find((line) => line.startsWith("fatal:") || line.startsWith("error:"));
+		if (reason !== void 0) return reason;
+		return lines[0] ?? "git gave no reason";
+	}
+};
+/**
+* git could not be started: there is none on `PATH`, or the directory to run it in does not exist.
+*
+* Its own type because callers treat it differently from git failing:
+* {@link Repository.open} answers "no repository" for it, where any other
+* failure is thrown.
+*/
+var GitDidNotStartError = class extends RepositoryError {
+	/** Creates the error from the message Node gave. */
+	constructor(message) {
+		super(message);
+		this.name = "GitDidNotStartError";
+	}
+};
+//#endregion
+//#region src/lib/git/git.ts
+/**
+* What one git call returned, and ways to read it.
+*
+* A call returns one only when it succeeded or exited with a code the caller
+* allowed; anything else is thrown by {@link Git.run}. Reading lives here so
+* every caller reads git's output the same way: `paths()` for `-z` lists,
+* `text()` for one value, `reason()` for why it failed.
+*/
+var GitResult = class {
+	exitCode;
+	stdout;
+	stderr;
+	/** Wraps what one call returned. */
+	constructor(exitCode, stdout, stderr) {
+		this.exitCode = exitCode;
+		this.stdout = stdout;
+		this.stderr = stderr;
+	}
+	/** Whether git exited 0. */
+	succeeded() {
+		return this.exitCode === 0;
+	}
+	/** What git printed, without its final line break. */
+	text() {
+		return this.stdout.replace(/\n$/, "");
+	}
+	/** The NUL-separated paths git printed, for a `-z` command. */
+	paths() {
+		return this.stdout.split("\0").filter((path) => path !== "");
+	}
+	/**
+	* Everything git wrote to stderr, its own reason for failing; empty when it wrote none.
+	*
+	* All of it, not the first line: git's later lines often say how to fix the
+	* failure, as a refusal over ownership names the `safe.directory` command.
+	*/
+	reason() {
+		return this.stderr.trim();
+	}
+};
+/**
+* The git command line, run in one directory with one environment.
+*
+* The one place the CLI starts git. Every call goes through {@link run},
+* which makes it safe the same way (see there), so no caller can forget a
+* setting. It knows nothing about repositories or Zitadel: it runs git and
+* reads its answer. `with` gives the same git with more environment, which is
+* how a temporary staging area, a fallback author or an English locale is
+* applied to one call.
+*/
+var Git = class Git {
+	/** The directory git runs in. */
+	dir;
+	env;
+	/** Runs git in `dir`, with `env` added to its environment. */
+	constructor(dir, env = {}) {
+		this.dir = dir;
+		this.env = env;
+	}
+	/** The same git, with `env` added to its environment. */
+	with(env) {
+		return new Git(this.dir, {
+			...this.env,
+			...env
+		});
+	}
+	/**
+	* Runs git with `args`; throws a {@link RepositoryError} for an exit code other than 0 or `allow`.
+	*
+	* Every call is made safe the same way:
+	* - `GIT_LITERAL_PATHSPECS`, `GIT_GLOB_PATHSPECS`, `GIT_NOGLOB_PATHSPECS`
+	*   and `GIT_ICASE_PATHSPECS` are dropped from the inherited environment.
+	*   They change what every path given to git matches, and the literal one
+	*   turns off the `:(exclude)` a commit uses to keep a secret out.
+	* - `GIT_TERMINAL_PROMPT=0`, so git never waits on a prompt.
+	* - Output is capped at 16 MB and a call at five minutes, so a stuck or
+	*   runaway git cannot hang the CLI.
+	*
+	* `GIT_DIR`, `GIT_WORK_TREE` and `GIT_INDEX_FILE` are honoured, as git
+	* itself does: a build that keeps `.git` elsewhere names it this way. No
+	* flag is set that git passes on to hooks, so a hook that runs during a
+	* commit sees the developer's own settings: a path is made literal where it
+	* is given ({@link Git.literal}), and the locale is set to English only for
+	* the one call whose wording is read.
+	*
+	* Output is read as UTF-8 unless `encoding` says otherwise; `latin1` keeps
+	* every byte as one character, for a path list that must go back to git
+	* unchanged.
+	*
+	* An allowed exit code is an answer, not a failure. Only a git that ran and
+	* exited has one, so no allow list can mistake a missing git for an answer;
+	* that throws {@link GitDidNotStartError}. Every other failure carries git's
+	* own message, or Node's when git wrote nothing.
+	*/
+	run(args, allow = [], encoding = "utf8") {
+		const inherited = { ...process.env };
+		for (const name of [
+			"GIT_LITERAL_PATHSPECS",
+			"GIT_GLOB_PATHSPECS",
+			"GIT_NOGLOB_PATHSPECS",
+			"GIT_ICASE_PATHSPECS"
+		]) delete inherited[name];
+		const env = {
+			...inherited,
+			GIT_TERMINAL_PROMPT: "0",
+			...this.env
+		};
+		return new Promise((resolveResult, reject) => {
+			execFile("git", [...args], {
+				cwd: this.dir,
+				env,
+				encoding,
+				maxBuffer: 16777216,
+				timeout: 3e5
+			}, (error, stdout, stderr) => {
+				const failure = error;
+				if (failure === null) {
+					resolveResult(new GitResult(0, stdout, stderr));
+					return;
+				}
+				if (typeof failure.code === "number") {
+					const result = new GitResult(failure.code, stdout, stderr);
+					if (allow.includes(failure.code)) resolveResult(result);
+					else reject(new RepositoryError(result.reason() || failure.message));
+				} else if (failure.code === "ENOENT") reject(new GitDidNotStartError(failure.message));
+				else if (failure.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") reject(new RepositoryError("git printed more than 16 MB"));
+				else if (failure.killed) reject(new RepositoryError("git did not finish in time"));
+				else reject(new RepositoryError(stderr.trim() || failure.message));
+			});
+		});
+	}
+	/**
+	* Every file staged under the directory, relative to it.
+	*
+	* `--relative` both limits the list to the directory and names each path
+	* from it, as a path filter expects. `--no-renames` lists both ends of a
+	* rename, so neither escapes a check.
+	*/
+	async stagedFiles() {
+		return (await this.run([
+			"diff",
+			"--cached",
+			"-z",
+			"--name-only",
+			"--no-renames",
+			"--relative"
+		])).paths();
+	}
+	/**
+	* `path` as a pathspec that matches only itself, so `app/[id].tsx` does not also match `app/i.tsx`.
+	*
+	* Set per path rather than with `--literal-pathspecs`, which git would pass
+	* on to every hook it runs as `GIT_LITERAL_PATHSPECS`.
+	*/
+	static literal(path) {
+		return `:(literal)${path}`;
+	}
+	/** Whether `path`, relative to the directory, names something that exists. */
+	exists(path) {
+		return path !== "" && existsSync(resolve(this.dir, path));
+	}
+};
+//#endregion
+//#region src/lib/git/author-identity.ts
+/**
+* Where the author's name on a commit would come from.
+*
+* Three cases: the developer has an identity of their own (config or
+* `GIT_AUTHOR_*`), git can only guess one from the username and hostname, or
+* git cannot build one at all, as on a bare CI runner. Only the last needs an
+* author supplied, since an invented author is worse than git's own guess;
+* the caller is told which it was, so it can say so. Applying an author to a
+* commit is {@link StagingArea.commit}'s job.
+*/
+var AuthorIdentity = class AuthorIdentity {
+	/** Where the author's name comes from. */
+	source;
+	/** The identity from `source`. */
+	constructor(source) {
+		this.source = source;
+	}
+	/**
+	* Where the author git would commit with in `git`'s directory comes from.
+	*
+	* Without an identity of the developer's own, git guesses one from the
+	* username and hostname and commits anyway; `user.useConfigOnly` turns that
+	* guess back into an error, which tells a real identity from a guessed one.
+	*/
+	static async of(git) {
+		if ((await git.run([
+			"-c",
+			"user.useConfigOnly=true",
+			"var",
+			"GIT_AUTHOR_IDENT"
+		], [128])).succeeded()) return new AuthorIdentity("yours");
+		if ((await git.run(["var", "GIT_AUTHOR_IDENT"], [128])).succeeded()) return new AuthorIdentity("guessed");
+		return new AuthorIdentity("fallback");
+	}
+};
+//#endregion
+//#region src/lib/git/checks/head-is-on-a-branch.ts
+/**
+* HEAD is a branch, so a commit is not lost on a detached HEAD.
+*
+* A commit on a detached HEAD belongs to no branch, and the developer's next
+* checkout leaves it behind. A branch with no commit yet, as in a repository
+* just created, counts as a branch.
+*/
+var HeadIsOnABranch = class {
+	/** Why a commit here would be lost, or null. */
+	async problem(git) {
+		if ((await git.run([
+			"symbolic-ref",
+			"--quiet",
+			"HEAD"
+		], [1])).succeeded()) return null;
+		return "HEAD is detached, so the commit would be on no branch";
+	}
+};
+//#endregion
+//#region src/lib/git/checks/no-operation-under-way.ts
+/**
+* No merge, rebase, cherry-pick, revert or bisect is under way, so a commit lands where meant.
+*
+* Mid-merge, a commit would conclude the merge with the developer's
+* half-resolved work; mid-rebase or cherry-pick, it would be woven into a
+* history being rewritten; mid-bisect, it would land on whichever commit is
+* being tested.
+*/
+var NoOperationUnderWay = class {
+	/**
+	* "a merge is in progress" and the like, or null.
+	*
+	* Each operation keeps a marker file in the git directory while it is under
+	* way. `--git-path` finds each one for this worktree, which in a linked
+	* worktree is not under `.git/`.
+	*/
+	async problem(git) {
+		const operations = [
+			{
+				marker: "MERGE_HEAD",
+				name: "a merge"
+			},
+			{
+				marker: "rebase-merge",
+				name: "a rebase"
+			},
+			{
+				marker: "rebase-apply",
+				name: "a rebase"
+			},
+			{
+				marker: "CHERRY_PICK_HEAD",
+				name: "a cherry-pick"
+			},
+			{
+				marker: "REVERT_HEAD",
+				name: "a revert"
+			},
+			{
+				marker: "BISECT_LOG",
+				name: "a bisect"
+			}
+		];
+		const args = operations.flatMap((operation) => ["--git-path", operation.marker]);
+		const paths = (await git.run(["rev-parse", ...args])).text().split("\n");
+		const found = operations.find((_, index) => git.exists(paths[index] ?? ""));
+		if (found === void 0) return null;
+		return `${found.name} is in progress`;
+	}
+};
+//#endregion
+//#region src/lib/git/checks/nothing-excluded-is-staged.ts
+/**
+* No staged file is one `except` matches.
+*
+* The last guard before a commit. {@link StagingArea.addAll} already leaves
+* excluded files out, but a file committed once cannot be taken out of
+* history, so what is about to be committed is checked rather than trusted.
+*/
+var NothingExcludedIsStaged = class {
+	except;
+	/** Checks against `except`. */
+	constructor(except) {
+		this.except = except;
+	}
+	/** Which excluded file is still staged, or null. */
+	async problem(git) {
+		const leaked = (await git.stagedFiles()).find(this.except);
+		if (leaked === void 0) return null;
+		return `${leaked} could not be kept out of the commit, so nothing was committed`;
+	}
+};
+//#endregion
+//#region src/lib/git/checks/something-is-staged.ts
+/**
+* Something is staged, so a commit has something to record.
+*
+* When everything was excluded, or nothing changed, the answer is "there was
+* nothing to commit" rather than an empty commit or git's own refusal.
+*/
+var SomethingIsStaged = class {
+	/** That nothing is staged, or null. */
+	async problem(git) {
+		if ((await git.stagedFiles()).length > 0) return null;
+		return "there was nothing to commit";
+	}
+};
+//#endregion
+//#region src/lib/git/operations/current-commit.ts
+/**
+* The commit the repository is at, or null before its first commit.
+*
+* A repository with no commit yet is an answer, null, not a failure.
+*/
+var CurrentCommit = class {
+	/** Nothing to check. */
+	checks() {
+		return [];
+	}
+	/** Never refused. */
+	refused() {
+		return null;
+	}
+	/** Asks git for HEAD's commit. */
+	async run(git) {
+		const result = await git.run([
+			"rev-parse",
+			"--verify",
+			"--quiet",
+			"HEAD^{commit}"
+		], [1]);
+		if (!result.succeeded()) return null;
+		return result.text();
+	}
+};
+//#endregion
+//#region src/lib/git/staging-area.ts
+/**
+* A temporary staging area (`GIT_INDEX_FILE`), so a commit or a diff is put
+* together without touching the developer's own, which may hold staged work
+* of theirs, another package's included.
+*
+* Made with {@link temporary}, which removes it however the work ends. A
+* commit starts it at the last commit ({@link startFromHead}); a diff starts
+* it from a copy of the developer's ({@link startFromDevelopers}). Its methods
+* are the steps an operation takes, so the operation reads as a list of them.
+*/
+var StagingArea = class StagingArea {
+	/** git, pointed at this staging area. */
+	git;
+	index;
+	/** The staging area kept in `index`. */
+	constructor(git, index) {
+		this.index = index;
+		this.git = git.with({ GIT_INDEX_FILE: index });
+	}
+	/**
+	* Runs `work` with a new staging area for `git`'s directory, removed afterwards.
+	*
+	* A failure to remove it is dropped: by then the work is done, and a commit
+	* that landed must not be reported as failed because a temporary file was
+	* briefly held open (as Windows Defender does).
+	*/
+	static async temporary(git, work) {
+		const scratch = await mkdtemp(join(tmpdir(), "git-staging-"));
+		try {
+			return await work(new StagingArea(git, join(scratch, "index")));
+		} finally {
+			await rm(scratch, {
+				recursive: true,
+				force: true
+			}).catch(() => void 0);
+		}
+	}
+	/**
+	* Starts at the last commit, keeping what the developer's staging area knows about each file; empty before one.
+	*
+	* It starts as a copy of `developers`' staging area and is then reset to
+	* the last commit with `read-tree -m`, which keeps each entry's flags and
+	* file timestamps where the content is unchanged. The flags matter: a file
+	* the developer marked `skip-worktree` or `assume-unchanged` (a local
+	* config with real credentials, or the files outside a sparse checkout)
+	* keeps its mark, so its local state is never staged. The timestamps spare
+	* git from hashing every file again. Another package's staged work is
+	* dropped by the reset, so the commit carries the rest of the repository as
+	* last committed.
+	*/
+	async startFromHead(developers) {
+		await this.startFromDevelopers(developers);
+		const head = await new CurrentCommit().run(this.git);
+		if (head === null) await this.git.run(["read-tree", "--empty"]);
+		else await this.git.run([
+			"read-tree",
+			"-m",
+			head
+		]);
+	}
+	/**
+	* Starts as a copy of the developer's staging area, keeping its timestamps.
+	*
+	* A copy rather than an empty one, so a tracked file that `.gitignore` now
+	* matches still diffs. The timestamps matter: git trusts an entry only for a
+	* file older than the index, so a copy stamped now hid an edit made in the
+	* same second as the developer's last `git add`. A fresh repository has no
+	* index yet, and the copy then starts empty.
+	*/
+	async startFromDevelopers(developers) {
+		const index = resolve(developers.dir, (await developers.run([
+			"rev-parse",
+			"--git-path",
+			"index"
+		])).text());
+		if (existsSync(index)) {
+			await copyFile(index, this.index);
+			const { atime, mtime } = await stat(index);
+			await utimes(this.index, atime, mtime);
+		}
+	}
+	/**
+	* Stages everything under the directory but what `except` matches, as `git add --all -- .` would.
+	*
+	* The changed and untracked files are listed first to find the ones
+	* `except` matches, and those are then left out of a single
+	* `git add --all -- .` with `:(exclude)`. An excluded file is never read, so
+	* its content is never written to the object store, where it would sit as
+	* a loose object until git cleans it up. Staging stays `git add --all -- .`
+	* in every other way: a file that vanishes meanwhile, a tracked file in an
+	* ignored directory and a sparse checkout all behave as they do for the
+	* developer, and matching stays linear however many files there are. A
+	* file that is already tracked and excluded keeps what the last commit has.
+	*
+	* The pathspecs go through a file beside the staging area, read and written
+	* byte for byte: a name that is not valid UTF-8, which Linux allows, would
+	* otherwise come back changed and match nothing. `except` sees each name as
+	* UTF-8.
+	*
+	* Exit 1 is accepted: git gives it when everything `.` matches is a file the
+	* developer marked `skip-worktree`, having staged nothing, which is the
+	* right result. A real failure, such as a file that cannot be read, exits
+	* 128. Whether anything was staged is for the caller to check.
+	*/
+	async addAll(except) {
+		const excluded = (await this.git.run([
+			"ls-files",
+			"-z",
+			"--modified",
+			"--deleted",
+			"--others",
+			"--exclude-standard",
+			"--",
+			"."
+		], [], "latin1")).paths().filter((path) => except(Buffer.from(path, "latin1").toString("utf8"))).map((path) => `:(exclude,literal)${path}`);
+		const list = join(dirname(this.index), "paths");
+		await writeFile(list, Buffer.from([".", ...excluded].join("\0"), "latin1"));
+		await this.git.run([
+			"add",
+			"--all",
+			`--pathspec-from-file=${list}`,
+			"--pathspec-file-nul"
+		], [1]);
+	}
+	/**
+	* Marks the untracked files among `paths` "intent to add", so a diff shows them as added.
+	*
+	* Intent to add records the file without its content, so nothing is written
+	* to the object store. Only paths that exist are passed: `git add` refuses
+	* the whole call when one matches nothing. An ignored path makes it mark the
+	* rest and exit 1, which is accepted. Each path is taken literally
+	* ({@link Git.literal}), so `app/[id].tsx` marks only itself.
+	*/
+	async markAsAdded(paths) {
+		const present = paths.filter((path) => this.git.exists(path)).map(Git.literal);
+		if (present.length > 0) await this.git.run([
+			"add",
+			"--intent-to-add",
+			"--",
+			...present
+		], [1]);
+	}
+	/** The first problem any of `checks` finds with what is staged, or null. */
+	async problem(checks) {
+		for (const check of checks) {
+			const problem = await check.problem(this.git);
+			if (problem !== null) return problem;
+		}
+		return null;
+	}
+	/**
+	* Commits what is staged with `message`, naming `author` as author and committer when given.
+	*
+	* Without `author`, git names whoever it would. An author is set through
+	* the environment rather than `-c user.*`: an inherited empty
+	* `GIT_AUTHOR_NAME=`, as some CI runners leave it, outranks `-c`, and git
+	* would refuse the commit with "empty ident name".
+	*
+	* Signing is turned off, so a configured key cannot block on a passphrase
+	* prompt. `--no-verify` skips the pre-commit and commit-msg hooks, which a
+	* scaffolded app's linter would otherwise fail; post-commit hooks still run,
+	* as they always did.
+	*/
+	async commit(message, author) {
+		const commit = [
+			"-c",
+			"commit.gpgsign=false",
+			"commit",
+			"--quiet",
+			"--no-verify",
+			`--message=${message}`
+		];
+		if (author === null) await this.git.run(commit);
+		else await this.git.with({
+			GIT_AUTHOR_NAME: author.name,
+			GIT_AUTHOR_EMAIL: author.email,
+			GIT_COMMITTER_NAME: author.name,
+			GIT_COMMITTER_EMAIL: author.email
+		}).run(commit);
+	}
+};
+//#endregion
+//#region src/lib/git/operations/commit-all.ts
+/**
+* Commits everything under the directory but `options.except`.
+*
+* The commit is built in a temporary staging area that starts from the last
+* commit, never in the developer's own: theirs may hold another package's
+* staged work, which would be swept in. It carries the developer's per-file
+* flags, so a file they told git to leave alone stays out of the commit. A pathspec is no way round that,
+* since `git commit -- .` commits the working tree and ignores the staging
+* area, so an excluded file that is already tracked would go in anyway.
+*
+* Expects nothing uncommitted of the developer's under the directory: once
+* committed, their staging area there is reset to the new commit, or they
+* would see the commit's files staged for deletion.
+*/
+var CommitAll = class {
+	message;
+	options;
+	/** Commits with `message`, as `options` say. */
+	constructor(message, options) {
+		this.message = message;
+		this.options = options;
+	}
+	/**
+	* Nothing is under way that the commit would land in the middle of.
+	*
+	* Mid-merge, a commit would record a merge with the wrong parents; mid-rebase
+	* or on a detached HEAD, it would sit on no branch and be lost.
+	*/
+	checks() {
+		return [new NoOperationUnderWay(), new HeadIsOnABranch()];
+	}
+	/** Nothing committed, for `problem`. */
+	refused(problem) {
+		return {
+			committed: false,
+			reason: problem
+		};
+	}
+	/**
+	* Stages everything but the excluded files, checks, and commits.
+	*
+	* The caller's fallback author is named only where git cannot build an
+	* identity at all; a commit with no author would leave nothing to diff a
+	* later deploy against.
+	*
+	* What is about to be committed is checked rather than trusted, since a
+	* file committed once cannot be taken out of history. The reset of the
+	* developer's staging area afterwards is best effort, since the commit has
+	* already landed.
+	*
+	* A commit can land and git still fail afterwards: a post-commit hook that
+	* errors, or one that runs past the five-minute limit. So when the commit
+	* fails, HEAD is read again, and a HEAD that moved means the commit was made
+	* and is reported as made.
+	*/
+	async run(git) {
+		const identity = await AuthorIdentity.of(git);
+		const before = await new CurrentCommit().run(git);
+		return StagingArea.temporary(git, async (staging) => {
+			await staging.startFromHead(git);
+			await staging.addAll(this.options.except);
+			const problem = await staging.problem([new NothingExcludedIsStaged(this.options.except), new SomethingIsStaged()]);
+			if (problem !== null) return this.refused(problem);
+			try {
+				if (identity.source === "fallback") await staging.commit(this.message, this.options.authorIfGitHasNone);
+				else await staging.commit(this.message, null);
+			} catch (error) {
+				if (await new CurrentCommit().run(git) === before) throw error;
+			}
+			const sha = await new CurrentCommit().run(git);
+			if (sha === null) throw new RepositoryError("the commit left no HEAD to record");
+			await git.run([
+				"reset",
+				"--quiet",
+				"--",
+				"."
+			]).catch(() => void 0);
+			return {
+				committed: true,
+				sha,
+				author: identity.source
+			};
+		});
+	}
+};
+//#endregion
+//#region src/lib/git/operations/current-subject.ts
+/**
+* The subject line of the commit the repository is at, or null before its first commit.
+*
+* `--no-show-signature` overrides a developer's `log.showSignature`, which
+* would otherwise put gpg's lines ahead of the subject on a signed commit. A
+* repository with no commit yet makes `git log` exit 128, which is an answer,
+* null, not a failure.
+*/
+var CurrentSubject = class {
+	/** Nothing to check. */
+	checks() {
+		return [];
+	}
+	/** Never refused. */
+	refused() {
+		return null;
+	}
+	/** Asks git for HEAD's subject. */
+	async run(git) {
+		const result = await git.run([
+			"log",
+			"-1",
+			"--no-show-signature",
+			"--format=%s"
+		], [128]);
+		if (!result.succeeded()) return null;
+		return result.text() || null;
+	}
+};
+//#endregion
+//#region src/lib/git/change.ts
+/**
+* One changed file, as `git diff --raw -z` lists it: where it is, what
+* happened to it, and where it came from when it was renamed or copied.
+*
+* Read from git's raw list rather than from the patch's `diff --git` headers:
+* the list is NUL-separated and never quoted, while a header quotes a path
+* holding a space or a non-ASCII byte and cannot be split reliably.
+* {@link DiffFilesSince} pairs each change with its part of the patch.
+*/
+var Change = class Change {
+	path;
+	status;
+	/** Where a renamed or copied file came from. */
+	previousPath;
+	/** A change of `status` to `path`, from `previousPath` for a rename or a copy. */
+	constructor(path, status, previousPath) {
+		this.path = path;
+		this.status = status;
+		this.previousPath = previousPath;
+	}
+	/**
+	* Every change in the NUL-separated `fields` of a `--raw -z` list, in its order.
+	*
+	* Each entry is `:<modes> <ids> <letter>[<score>]`, then the path, or for a
+	* rename or a copy where it came from and where it went. The entries are
+	* read in order rather than by looking for a `:`, since a path may start
+	* with one. M, T (a type change) and U (unmerged) all count as modified.
+	*/
+	static listedIn(fields) {
+		const statuses = {
+			A: "added",
+			D: "deleted",
+			R: "renamed",
+			C: "copied"
+		};
+		const unread = fields.values();
+		const changes = [];
+		for (const entry of unread) {
+			const status = statuses[entry.charAt(entry.lastIndexOf(" ") + 1)] ?? "modified";
+			const first = unread.next().value ?? "";
+			if (status === "renamed" || status === "copied") changes.push(new Change(unread.next().value ?? "", status, first));
+			else changes.push(new Change(first, status));
+		}
+		return changes;
+	}
+	/** This change, as a diff reports it, with `patch` as its part of the diff. */
+	diffedWith(patch) {
+		if (this.previousPath === void 0) return {
+			path: this.path,
+			status: this.status,
+			patch
+		};
+		return {
+			path: this.path,
+			status: this.status,
+			previous_path: this.previousPath,
+			patch
+		};
+	}
+};
+//#endregion
+//#region src/lib/git/checks/commit-is-here.ts
+/**
+* `commit` is a commit in local history; a shallow clone may lack it.
+*
+* Checked before a diff, so a missing commit answers null ("no diff
+* available") rather than failing, and an empty diff is never mistaken for a
+* clean tree.
+*/
+var CommitIsHere = class {
+	commit;
+	/** Checks for `commit`. */
+	constructor(commit) {
+		this.commit = commit;
+	}
+	/**
+	* Why the commit cannot be used, or null.
+	*
+	* Only an object id, full or abbreviated, is handed to git; anything else
+	* could be read as an option or name a branch.
+	*/
+	async problem(git) {
+		if (!/^[0-9a-f]{4,64}$/i.test(this.commit)) return `${this.commit} is not a commit id`;
+		if ((await git.run([
+			"cat-file",
+			"-e",
+			`${this.commit}^{commit}`
+		], [1, 128])).succeeded()) return null;
+		return `${this.commit} is not in this repository's history`;
+	}
+};
+//#endregion
+//#region src/lib/git/operations/diff-since.ts
+/**
+* The diff of `paths` since `commit`, untracked files as added, as git prints it.
+*
+* One `git diff` over all of `paths`. Not one per file: a path matches
+* everything under it too, so a file replaced by a directory took in the
+* directory's files, and hundreds of files meant hundreds of processes, which
+* ran out of open files. Nothing is left out of the diff: the paths are the
+* caller's to choose, and whatever they name, a secret included, is shown.
+*/
+var DiffSince = class {
+	commit;
+	paths;
+	format;
+	/** Diffs `paths` since `commit`, coloured as `options` say, with `extra` added to git's format. */
+	constructor(commit, paths, options, extra = []) {
+		this.commit = commit;
+		this.paths = paths;
+		if (options.color) this.format = ["--color=always", ...extra];
+		else this.format = ["--no-color", ...extra];
+	}
+	/** The commit is in local history. */
+	checks() {
+		return [new CommitIsHere(this.commit)];
+	}
+	/** No diff: there is nothing to diff against. */
+	refused() {
+		return null;
+	}
+	/**
+	* Diffs in a copy of the developer's staging area with untracked files marked as added.
+	*
+	* `git diff` leaves untracked files out, but a new file is part of what a
+	* deploy publishes, so it is marked "intent to add" first, in a copy and
+	* never in the developer's own staging area. When that cannot be done the
+	* plain diff is given instead, which still shows every tracked change.
+	*
+	* `--no-ext-diff` keeps a configured external diff tool out, `--relative`
+	* names paths from the directory, and each path is taken literally
+	* ({@link Git.literal}), so `app/[id].tsx` does not also diff `app/i.tsx`.
+	*/
+	async run(git) {
+		const diff = [
+			"diff",
+			"--no-ext-diff",
+			"--relative",
+			...this.format,
+			this.commit,
+			"--",
+			...this.paths.map(Git.literal)
+		];
+		return StagingArea.temporary(git, async (staging) => {
+			try {
+				await staging.startFromDevelopers(git);
+				await staging.markAsAdded(this.paths);
+				return (await staging.git.run(diff)).stdout;
+			} catch {
+				return (await git.run(diff)).stdout;
+			}
+		});
+	}
+};
+//#endregion
+//#region src/lib/git/operations/diff-files-since.ts
+/**
+* The changed files under `paths` since `commit`, untracked files as added, each with its part of the diff.
+*
+* Built from the same single `git diff` as {@link DiffSince}, so joined back
+* together the patches are the diff a terminal shows. `--submodule=short`
+* keeps a submodule's part under a `diff --git` header, which
+* `diff.submodule=log` would replace with a `Submodule …` line that belongs
+* to no file; it is set here only, so the terminal diff stays as the
+* developer configured it.
+*/
+var DiffFilesSince = class {
+	diff;
+	/** Diffs `paths` since `commit`, uncoloured, with the list of changed files ahead of the patch. */
+	constructor(commit, paths) {
+		this.diff = new DiffSince(commit, paths, {}, [
+			"--raw",
+			"-z",
+			"--patch",
+			"--submodule=short"
+		]);
+	}
+	/** Those of the diff. */
+	checks() {
+		return this.diff.checks();
+	}
+	/** No diff: there is nothing to diff against. */
+	refused() {
+		return null;
+	}
+	/**
+	* Each listed file paired with its section of the patch.
+	*
+	* `--raw -z` lists every file's status and paths, unquoted, ahead of the
+	* patch; one more NUL ends the list. git writes the list and the patch from
+	* one list of files, in one order, so they pair one to one. The exception is
+	* a file whose type changed (a file replaced by a symlink): git shows it as
+	* two sections under one header, which are joined. The patch is split only
+	* where `diff --git` follows a newline. A file's content may mention it, and
+	* a file with old Mac line endings (a lone `\r`) has no newline before it,
+	* so its section stays whole.
+	*/
+	async run(git) {
+		const output = await this.diff.run(git);
+		const end = output.indexOf("\0\0");
+		if (end === -1) return [];
+		const patches = [];
+		for (const section of output.slice(end + 2).split(/(?<=\n)(?=diff --git )/)) {
+			const last = patches.at(-1);
+			if (last !== void 0 && last.slice(0, last.indexOf("\n")) === section.slice(0, section.indexOf("\n"))) patches[patches.length - 1] = last + section;
+			else patches.push(section);
+		}
+		return Change.listedIn(output.slice(0, end).split("\0")).map((change, index) => change.diffedWith(patches[index] ?? ""));
+	}
+};
+//#endregion
+//#region src/lib/git/operations/is-dirty.ts
+/**
+* Whether anything in the whole repository is uncommitted, not only under the directory.
+*
+* Any change anywhere in the repository counts, including outside the
+* directory the repository was opened on.
+*/
+var IsDirty = class {
+	/** Nothing to check. */
+	checks() {
+		return [];
+	}
+	/** Never refused. */
+	refused() {
+		return false;
+	}
+	/** Asks git whether `status` lists anything. */
+	async run(git) {
+		return (await git.run(["status", "--porcelain"])).stdout.trim() !== "";
+	}
+};
+//#endregion
+//#region src/lib/git/operations/ready-to-commit.ts
+/**
+* Why a commit here would land where it should not, or null when one would land on a branch as meant.
+*
+* The same checks {@link CommitAll} makes, asked on their own, so a caller
+* can refuse before it does any work rather than find out when it commits.
+*/
+var ReadyToCommit = class {
+	/** Nothing is under way, and HEAD is on a branch. */
+	checks() {
+		return [new NoOperationUnderWay(), new HeadIsOnABranch()];
+	}
+	/** The first problem a check found. */
+	refused(problem) {
+		return problem;
+	}
+	/** No problem: every check holds. */
+	async run() {
+		return null;
+	}
+};
+//#endregion
+//#region src/lib/git/operations/uncommitted-files.ts
+/**
+* The uncommitted files under the directory, untracked ones included, each file of an untracked directory listed.
+*
+* What a commit of the whole directory would sweep in. In a monorepo a
+* sibling package's work is not listed, since a commit here never touches
+* it. Each path is named from the directory, as the developer sees it.
+*/
+var UncommittedFiles = class {
+	/** Where the directory sits in the repository, e.g. `apps/web/`: what `status` puts before each path. */
+	prefix;
+	/** Lists the files under the directory at `prefix`. */
+	constructor(prefix) {
+		this.prefix = prefix;
+	}
+	/** Nothing to check. */
+	checks() {
+		return [];
+	}
+	/** Never refused. */
+	refused() {
+		return [];
+	}
+	/**
+	* Asks git for the status of the directory.
+	*
+	* `-- .` keeps a sibling package's work out. `--untracked-files=all` names
+	* each file of an untracked directory rather than the directory alone.
+	* `status` names paths from the repository root, so the prefix is taken off;
+	* a rename or a copy carries a second entry, where it came from, which is
+	* skipped.
+	*/
+	async run(git) {
+		const unread = (await git.run([
+			"status",
+			"--porcelain",
+			"-z",
+			"--untracked-files=all",
+			"--",
+			"."
+		])).paths().values();
+		const files = [];
+		for (const entry of unread) {
+			const path = entry.slice(3);
+			const untracked = entry.startsWith("??");
+			if (path.startsWith(this.prefix)) files.push({
+				path: path.slice(this.prefix.length),
+				untracked
+			});
+			else files.push({
+				path,
+				untracked
+			});
+			if (/^(R|C|.R|.C)/.test(entry)) unread.next();
+		}
+		return files;
+	}
+};
+//#endregion
+//#region src/lib/git/repository.ts
+/**
+* The git repository a directory is in, seen from that directory.
+*
+* In a monorepo the repository may start several levels up; everything here
+* is limited to the directory and names paths relative to it, except
+* {@link isDirty}, which looks at the whole repository. When git fails, a
+* method throws a `RepositoryError` carrying git's own message.
+*
+* Each method is one {@link Operation}: its checks run first, and the first
+* one that fails decides the answer through the operation's `refused`.
+*/
+var Repository = class Repository {
+	git;
+	/** Where the directory sits in the repository, e.g. `apps/web/`, or `""` at its root. */
+	prefix;
+	/** Creates the handle; use {@link Repository.open} or {@link Repository.create}. */
+	constructor(dir, prefix) {
+		this.git = new Git(dir);
+		this.prefix = prefix;
+	}
+	/**
+	* The repository `dir` is in, or null when it is in none, does not exist, or there is no git.
+	*
+	* Only those three mean "no repository". Any other failure, such as a
+	* refusal over ownership or a broken `HOME`, is thrown: answering "none"
+	* would let a caller `git init` a second repository inside the first, or
+	* skip a check that the tree is clean.
+	*
+	* `dir` is resolved to its real path first: git answers paths such as
+	* `--git-path MERGE_HEAD` relative to where it really runs, so through a
+	* symlink they would point somewhere else. git is asked in English here,
+	* since "not a git repository" is recognised by its wording.
+	*/
+	static async open(dir) {
+		if (!existsSync(dir)) return null;
+		const real = await realpath(dir);
+		const result = await new Git(real).with({ LC_ALL: "C" }).run(["rev-parse", "--show-prefix"], [128]).catch((error) => {
+			if (error instanceof GitDidNotStartError) return null;
+			throw error;
+		});
+		if (result === null) return null;
+		if (/^fatal: not a git repository/m.test(result.stderr)) return null;
+		if (!result.succeeded()) throw new RepositoryError(result.reason());
+		return new Repository(real, result.text());
+	}
+	/**
+	* What `question` answers about the repository `dir` is in, or `otherwise` when there is none or git cannot answer.
+	*
+	* For a caller that records what git can tell and must never fail because
+	* of it, such as one that notes a commit when there is one: every failure,
+	* a missing git included, becomes `otherwise`. A caller that needs to know
+	* why git failed uses {@link open} and the methods directly.
+	*/
+	static async answer(dir, question, otherwise) {
+		try {
+			const repository = await Repository.open(dir);
+			if (repository === null) return otherwise;
+			return await question(repository);
+		} catch {
+			return otherwise;
+		}
+	}
+	/**
+	* A new repository in `dir`; when git cannot make one, nothing is left behind.
+	*
+	* `git init` writes `.git` before it is done, so a failure partway (a full
+	* or read-only disk) leaves a half-made repository that every later git
+	* command would trip over. When `dir` had no `.git` before, a failed
+	* `git init` removes it again, so a caller gets either a working repository
+	* or an error, never something in between. The error is always git's: if
+	* the removal fails too, its own failure is dropped, since git's message
+	* names the real cause. This assumes nothing else creates a repository in
+	* `dir` at the same time.
+	*
+	* A `.git` counts as there before even when it is a symlink to something
+	* missing, so a developer's link to an unmounted volume is never removed.
+	*/
+	static async create(dir) {
+		const real = await realpath(dir);
+		const gitDir = join(real, ".git");
+		const hadOne = await lstat(gitDir).then(() => true, () => false);
+		try {
+			await new Git(real).run(["init", "--quiet"]);
+		} catch (error) {
+			if (!hadOne) await rm(gitDir, {
+				recursive: true,
+				force: true
+			}).catch(() => void 0);
+			throw error;
+		}
+		return new Repository(real, "");
+	}
+	/** The commit it is at, or null before its first commit. */
+	currentCommit() {
+		return this.perform(new CurrentCommit());
+	}
+	/** The subject line of the commit it is at, or null before its first commit. */
+	currentSubject() {
+		return this.perform(new CurrentSubject());
+	}
+	/** Whether anything in the whole repository is uncommitted. */
+	isDirty() {
+		return this.perform(new IsDirty());
+	}
+	/** The uncommitted files under the directory, untracked ones included. */
+	uncommittedFiles() {
+		return this.perform(new UncommittedFiles(this.prefix));
+	}
+	/** Why a commit here would land where it should not (an operation under way, a detached HEAD), or null. */
+	readyToCommit() {
+		return this.perform(new ReadyToCommit());
+	}
+	/**
+	* Commits everything under the directory but `options.except`; see {@link CommitAll}.
+	*
+	* Meant for a directory with nothing uncommitted of the developer's own:
+	* check {@link uncommittedFiles} first. Afterwards the developer's staging
+	* area under the directory is reset to the new commit, so anything they had
+	* staged there would be unstaged.
+	*/
+	commitAll(message, options) {
+		return this.perform(new CommitAll(message, options));
+	}
+	/** The diff of `paths` since `commit`, untracked files as added, or null when that commit is not here. */
+	diffSince(commit, paths, options) {
+		return this.perform(new DiffSince(commit, paths, options));
+	}
+	/** {@link diffSince}, uncoloured and split into one entry per changed file. */
+	diffFilesSince(commit, paths) {
+		return this.perform(new DiffFilesSince(commit, paths));
+	}
+	/** Runs `operation` once all its checks hold; what it returns when refused, otherwise. */
+	async perform(operation) {
+		for (const check of operation.checks()) {
+			const problem = await check.problem(this.git);
+			if (problem !== null) return operation.refused(problem);
+		}
+		return operation.run(this.git);
+	}
+};
+//#endregion
 //#region src/lib/release/git.ts
-const run = promisify(execFile);
 /**
 * The directories a release is built from, the only paths a deploy diffs. Not
 * the whole of `.zitadel/`: `state.json` and `meta/` are not published, and
@@ -3464,26 +4693,13 @@ const CONFIG_PATHS = [
 	".zitadel/branding/",
 	".zitadel/idps/"
 ];
-/** Run git in `cwd`, returning its stdout, or null when git cannot answer. */
-async function git(cwd, args, env) {
-	try {
-		const { stdout } = await run("git", args, {
-			cwd,
-			maxBuffer: 16777216,
-			...env ? { env: {
-				...process.env,
-				...env
-			} } : {}
-		});
-		return stdout;
-	} catch {
-		return null;
-	}
-}
 /** The current commit, or null when there is no repo or no commit yet. */
 async function headSha(cwd) {
-	const stdout = await git(cwd, ["rev-parse", "HEAD"]);
-	return stdout === null ? null : stdout.trim() || null;
+	return Repository.answer(cwd, (repository) => repository.currentCommit(), null);
+}
+/** The current commit's subject line, or null when there is no repo or no commit yet. */
+async function headSubject(cwd) {
+	return Repository.answer(cwd, (repository) => repository.currentSubject(), null);
 }
 /**
 * Whether the repository's working tree has any uncommitted change, anywhere —
@@ -3492,55 +4708,47 @@ async function headSha(cwd) {
 * the config depends on, say) makes that provenance just as inexact.
 */
 async function worktreeIsDirty(cwd) {
-	const stdout = await git(cwd, ["status", "--porcelain"]);
-	return stdout !== null && stdout.trim() !== "";
+	return Repository.answer(cwd, (repository) => repository.isDirty(), false);
 }
 /**
 * The coloured diff of `.zitadel/` against `sha`, or null when no diff can be
 * shown: git is missing, this is not a repo, or the commit is not in local
-* history (a shallow clone, say). A dead commit is told apart from a clean tree
-* by first checking the commit resolves.
+* history (a shallow clone, say).
 */
 async function diffConfigAgainst(cwd, sha, color, referenced = []) {
 	const paths = [...CONFIG_PATHS, ...referenced];
-	if (await git(cwd, [
-		"cat-file",
-		"-e",
-		`${sha}^{commit}`
-	]) === null) return null;
-	const diffArgs = [
-		"diff",
-		color ? "--color=always" : "--no-color",
-		sha,
-		"--",
-		...paths
-	];
-	const indexPath = (await git(cwd, [
-		"rev-parse",
-		"--git-path",
-		"index"
-	]))?.trim();
-	if (!indexPath) return git(cwd, diffArgs);
-	let scratch;
-	try {
-		scratch = await mkdtemp(join(tmpdir(), "zitadel-diff-"));
-		const tempIndex = join(scratch, "index");
-		await copyFile(resolve(cwd, indexPath), tempIndex).catch(() => void 0);
-		const env = { GIT_INDEX_FILE: tempIndex };
-		const present = paths.filter((path) => existsSync(join(cwd, path)));
-		if (present.length > 0) await git(cwd, [
-			"add",
-			"-N",
-			"--",
-			...present
-		], env);
-		return await git(cwd, diffArgs, env) ?? await git(cwd, diffArgs);
-	} finally {
-		if (scratch) await rm(scratch, {
-			recursive: true,
-			force: true
-		});
+	return Repository.answer(cwd, (repository) => repository.diffSince(sha, paths, { color }), null);
+}
+/**
+* {@link diffConfigAgainst}, uncoloured and split by file: joined back
+* together, the patches are the diff the terminal shows. Null when no diff can
+* be shown, for the same reasons.
+*/
+async function diffConfigFilesAgainst(cwd, sha, referenced = []) {
+	const paths = [...CONFIG_PATHS, ...referenced];
+	return Repository.answer(cwd, (repository) => repository.diffFilesSince(sha, paths), null);
+}
+//#endregion
+//#region src/lib/release/pipeline.ts
+/**
+* Run the before-release steps in order, skipping the ones that do not apply to
+* this publish or that write on a dry run, and return what they report, for the
+* command's `--json` data. The command creates the release and the deployment
+* itself, between and after the step groups: before-release steps → create
+* release → before-deploy steps → create deployment.
+*/
+async function runSteps(steps, ctx) {
+	let report = {};
+	for (const step of steps) {
+		if (!step.runsFor.includes(ctx.mode)) continue;
+		if (ctx.dryRun && step.writes) continue;
+		const reported = await step.run(ctx);
+		if (reported) report = {
+			...report,
+			...reported
+		};
 	}
+	return report;
 }
 //#endregion
 //#region src/lib/release/steps/asset-probe.ts
@@ -4150,6 +5358,97 @@ function assertEnvRefsResolve(ctx) {
 	if (missing.size > 0) throw new ZitadelError("E_VALIDATION", `Missing environment variables: ${[...missing].sort().join(", ")}`);
 }
 //#endregion
+//#region src/lib/release/initial-deploy.ts
+/**
+* Publish `.zitadel/` to a project nothing has been deployed to, the way
+* `deploy` does: build the bundle, validate it, create the release and deploy
+* it to every primary origin. `deploy`'s diff step is left out, because there
+* is no live release to diff against, and so is its optimistic guard, because
+* there is no deployment to race with.
+*/
+async function deployInitialRelease(input) {
+	const { bundle, brandingSources, idpFiles, policyFiles } = await buildBundle(input.cwd);
+	const ctx = {
+		cwd: input.cwd,
+		client: input.client,
+		projectId: input.projectId,
+		env: input.env,
+		mode: "deploy",
+		dryRun: false,
+		json: input.json,
+		color: input.color,
+		bundle,
+		brandingSources,
+		idpFiles,
+		policyFiles,
+		suggest: input.suggest
+	};
+	await runSteps([validateStep], ctx);
+	const release = await createReleaseFromBundle(input.client, input.projectId, bundle, {
+		message: input.message,
+		gitSha: await headSha(input.cwd),
+		gitDirty: await worktreeIsDirty(input.cwd)
+	});
+	const deployment = await createDeployment(input.client, input.projectId, {
+		releaseId: release.id,
+		targets: ["primary"],
+		message: input.message
+	});
+	return {
+		releaseId: release.id,
+		contentHash: release.content_hash,
+		deploymentId: deployment.id,
+		origins: deployment.targets.map((target) => target.origin)
+	};
+}
+//#endregion
+//#region src/lib/release/message.ts
+/** The longest message the server records on a release or a deployment, in code points. */
+const MESSAGE_MAX_LENGTH = 1024;
+/** `-m/--message`: refused when blank or longer than the server records. */
+function messageFlag(description) {
+	return Flags.custom({
+		char: "m",
+		description,
+		parse: async (input) => {
+			const value = refuseBlank(input, "--message", "the value is empty");
+			if (Array.from(value).length > MESSAGE_MAX_LENGTH) throw new ZitadelError("E_VALIDATION", `the message is longer than ${MESSAGE_MAX_LENGTH} characters`, {
+				hint: "Pass a shorter summary with -m.",
+				details: { argument: "--message" }
+			});
+			return value;
+		}
+	})();
+}
+/**
+* The message a deploy or preview records: `-m`, else what the build is of —
+* the pull request's title on GitHub, Vercel's commit message, or the subject
+* of the current commit when the worktree is clean.
+*/
+async function deployMessage(flag, cwd, env) {
+	if (flag !== void 0) return flag;
+	if (env.GITHUB_EVENT_NAME === "pull_request" || env.GITHUB_EVENT_NAME === "pull_request_target") return cut(await pullRequestTitle(env.GITHUB_EVENT_PATH));
+	const vercel = env.VERCEL_GIT_COMMIT_MESSAGE?.split("\n")[0];
+	if (vercel?.trim()) return cut(vercel);
+	if (await worktreeIsDirty(cwd)) return;
+	return cut(await headSubject(cwd) ?? void 0);
+}
+/** The title in a GitHub pull_request event payload, or undefined when it cannot be read. */
+async function pullRequestTitle(path) {
+	if (!path) return;
+	try {
+		const title = JSON.parse(await readFile(path, "utf8")).pull_request?.title;
+		return typeof title === "string" ? title : void 0;
+	} catch {
+		return;
+	}
+}
+/** Trimmed and cut to the server's limit by code points, or undefined when blank. */
+function cut(value) {
+	const trimmed = value?.trim();
+	return trimmed ? Array.from(trimmed).slice(0, MESSAGE_MAX_LENGTH).join("") : void 0;
+}
+//#endregion
 //#region src/lib/release/steps/diff.ts
 /**
 * Show what `.zitadel/` changed since the release the target serves now.
@@ -4159,48 +5458,61 @@ function assertEnvRefsResolve(ctx) {
 * library and no server fallback: when git is missing, this is not a repo, the
 * commit is not in local history, or the live release carries no `git_sha`, it
 * prints one line saying no diff is available and carries on. Colour is
-* suppressed under `--json`, `--no-color` and a non-terminal, and the whole
-* line is withheld under `--json` so the envelope travels alone on stdout.
+* suppressed under `--no-color` and a non-terminal. Under `--json` nothing is
+* printed, so the envelope travels alone on stdout: the diff, split by file, or
+* the line saying why there is none, is reported as `diff` instead.
 */
 const diffStep = {
 	name: "diff",
 	runsFor: ["deploy", "preview"],
 	async run(ctx) {
-		const note = (line) => {
-			if (!ctx.json) process.stdout.write(`${line}\n`);
-		};
-		const deployments = await listLiveDeployments(ctx.client, ctx.projectId, { withRelease: true });
+		const deployments = await ctx.client.listDeployments.all({
+			project_id: ctx.projectId,
+			live: true,
+			expand: ["release"]
+		});
 		const live = deployments.find(servesPrimary)?.release?.metadata;
 		const sha = live?.git_sha;
-		if (!sha) {
-			note("No diff available: nothing is deployed yet, or the live release has no commit.");
-			return;
-		}
-		if (live?.git_dirty) {
-			note(`No reliable diff available: the live release was built from an uncommitted tree at ${sha.slice(0, 12)}.`);
-			return;
-		}
+		if (!sha) return noDiff(ctx, null, "No diff available: nothing is deployed yet, or the live release has no commit.");
+		if (live?.git_dirty) return noDiff(ctx, sha, `No reliable diff available: the live release was built from an uncommitted tree at ${sha.slice(0, 12)}.`);
 		const releases = new Set(deployments.filter(servesPrimary).map((entry) => entry.release_id));
-		if (releases.size > 1) note(`The primary origins serve ${releases.size} different releases; the diff below is against the newest, ${sha.slice(0, 12)}.`);
+		const note = releases.size > 1 ? `The primary origins serve ${releases.size} different releases; the diff is against the newest, ${sha.slice(0, 12)}.` : void 0;
+		const unknown = `No diff available: ${sha.slice(0, 12)} is not in this repository's history.`;
 		const referenced = ctx.brandingSources.flatMap((descriptor) => brandingReferencePaths(ctx.cwd, descriptor));
-		const diff = await diffConfigAgainst(ctx.cwd, sha, ctx.color, referenced);
-		if (diff === null) {
-			note(`No diff available: ${sha.slice(0, 12)} is not in this repository's history.`);
-			return;
+		if (ctx.json) {
+			const files = await diffConfigFilesAgainst(ctx.cwd, sha, referenced);
+			if (files === null) return noDiff(ctx, sha, unknown);
+			return { diff: {
+				against: sha,
+				files,
+				...note === void 0 ? {} : { note }
+			} };
 		}
-		if (diff.trim() === "") {
-			note(`No changes to .zitadel/ since ${sha.slice(0, 12)}.`);
-			return;
-		}
-		if (!ctx.json) process.stdout.write(diff.endsWith("\n") ? diff : `${diff}\n`);
+		if (note !== void 0) process.stdout.write(`${note}\n`);
+		const diff = await diffConfigAgainst(ctx.cwd, sha, ctx.color, referenced);
+		if (diff === null) return noDiff(ctx, sha, unknown);
+		const shown = diff.trim() === "" ? `No changes to .zitadel/ since ${sha.slice(0, 12)}.` : diff;
+		process.stdout.write(shown.endsWith("\n") ? shown : `${shown}\n`);
 	}
 };
+/** No diff to show: the line saying why, printed, or reported under `--json`. */
+function noDiff(ctx, against, note) {
+	if (!ctx.json) {
+		process.stdout.write(`${note}\n`);
+		return;
+	}
+	return { diff: {
+		against,
+		files: null,
+		note
+	} };
+}
 //#endregion
 //#region src/lib/release/index.ts
 /**
-* The arguments of a suggested publish. `deploy` refuses to run without `-m` when
-* no one can be asked for a message, which is every agent and every `--json`
-* run, so a suggested deploy carries one for the reader to fill in.
+* The arguments of a suggested publish. A non-interactive `deploy` with no
+* message to fall back on refuses to run without `-m`, so a suggested deploy
+* carries one for the reader to fill in.
 */
 const DEPLOY_ARGS = "deploy -m '<what changed>'";
 //#endregion
@@ -4279,7 +5591,7 @@ function exploreAllCommands(cliVersion) {
 * the run was about.
 */
 function customizeAndPublishActions(cliVersion, selector) {
-	return ["Customize what you ask for and how people sign in: edit .zitadel/schemas/ to change the information you collect, and .zitadel/flows/ to change the sign-up/sign-in experience. Each folder has a README with examples.", `See your changes before they go live: ${projectCommand("deploy --dry-run", selector, cliVersion)} to preview, then ${projectCommand(DEPLOY_ARGS, selector, cliVersion)} to publish.`];
+	return ["Customize what you ask for and how people sign in: edit .zitadel/schemas/ to change the information you collect, and .zitadel/flows/ to change the sign-up/sign-in experience. Each folder has a README with examples.", `See your changes before they go live: ${projectCommand("deploy --dry-run", selector, cliVersion)} to preview, then ${projectCommand(DEPLOY_ARGS, selector, cliVersion)} to publish. The project serves only what is deployed, so an edit takes effect once you deploy it.`];
 }
 /**
 * How to change the login's look after setup. Setup never ejects a template
@@ -4294,11 +5606,10 @@ function brandingGuidanceAction(cliVersion) {
 //#endregion
 //#region src/lib/skills-hint.ts
 const SHOWN_FILE = "skills-hint.json";
-const INSTALL_COMMAND = "npx skills add zitadel/nextgen --full-depth";
 /**
 * Tell a developer who has AI coding agents installed how to give them the
 * Zitadel skills, once per machine and after the command's own next steps.
-* The CLI never installs anything itself: it names the command and the
+* The note adds nothing itself: it names `zitadel skills add` and the
 * developer runs it. Modelled on Wrangler's skills suggestion, minus the prompt.
 *
 * The marker lives in the user's CLI config directory (`telemetryConfigDir`),
@@ -4311,7 +5622,7 @@ const INSTALL_COMMAND = "npx skills add zitadel/nextgen --full-depth";
 * fail the command the user actually ran, and losing the race to create the marker
 * (`EEXIST`) just means another run is showing the note.
 */
-async function showSkillsHint({ env, interactive }) {
+async function showSkillsHint({ env, interactive, cliVersion }) {
 	try {
 		if (!interactive || isCI(env) || isOptedOut(env)) return;
 		const shownPath = join(telemetryConfigDir(env), SHOWN_FILE);
@@ -4323,9 +5634,9 @@ async function showSkillsHint({ env, interactive }) {
 			consola$1.log([
 				"",
 				"Using an AI coding agent?",
-				"Install Zitadel skills to help your agent work with Zitadel’s CLI and authentication integrations:",
+				"Add the Zitadel skills to your project to help your agent work with Zitadel’s CLI and authentication integrations:",
 				"",
-				`  ${command(INSTALL_COMMAND)}`,
+				`  ${command(publicCliCommand("skills add", cliVersion))}`,
 				"",
 				"Optional. You can continue without installing skills."
 			].join("\n"));
@@ -4343,6 +5654,6 @@ function isOptedOut(env) {
 	return value !== void 0 && value !== "" && value !== "0" && value !== "false";
 }
 //#endregion
-export { flagText as $, normalizePublicCliCommands as $t, compareInGroup as A, variableInventoryCells as At, reportSecretOutcome as B, loadOrCreateIdentity as Bt, passwordPolicyFile as C, parseVariableValue as Ct, BRANDING_DIR as D, toVariableRows as Dt, readJsonDirEntries as E, toVariableRow as Et, readSchemaFiles as F, buildUserAgent as Ft, ENABLE_FLAG_KEYS as G, portableSuggestions as Gt, republishCommands as H, envEnabled as Ht, selectSchema as I, installUserAgent as It, SETUP_FLAG_NAMES as J, unscopedCommand as Jt, ENABLE_FLAG_NAMES as K, projectCommand as Kt, SCHEMAS_DIR as L, processUserAgentFacts as Lt, enabledMethods as M, variableScope as Mt, methodsOf as N, reportWarning as Nt, COMMAND_GROUPS as O, valuesOfKind as Ot, readFlowFiles as P, takeReportedWarnings as Pt, customFlagValues as Q, normalizePublicCliCommand as Qt, publishClientId as R, hostAgent as Rt, parsePasswordMinLength as S, assertVariableName as St, readJsonDir as T, toInventoryRows as Tt, storeClientSecret as U, asEnvironmentSelector as Ut, republishArgs as V, resolveConsent as Vt, askConnectionEndpoints as W, inShell as Wt, customExample as X, isTrainVersion as Xt, checkGivenCustomFlags as Y, isPortableShellWord as Yt, customFlagText as Z, maskPublicCliVersion as Zt, servesPrimary as _, stopListeningForInterrupt as _n, storedCustomSettings as _t, serverLogAction as a, collectPages as an, applySsoToSchema as at, PASSWORD_POLICY_PATH as b, isMissingEndpoint as bn, offeredSignInMethods as bt, wrapForBox as c, setTopLevelJsonKey as cn, ssoEditRefusal as ct, validateStep as d, createZitadelClient$1 as dn, IDPS_DIR as dt, normalizePublicCliJson as en, givenCustomFlags as et, headSha as f, escapeControlCharacters as fn, checkCustomSlug as ft, rollbackDeployment as g, listenForInterrupt as gn, refuseChangedIssuer as gt, listLiveDeployments as h, interruptSignal as hn, readConnectionFiles as ht, exploreAllCommands as i, sdkVersionForCli as in, applySsoToFlow as it, authMethods as j, variableReadScope as jt, CommandGroups as k, variableCells as kt, DEPLOY_ARGS as l, stableStringify as ln, ssoProvidersRefusal as lt, createDeployment as m, sanitizeResponse as mn, planConnection as mt, brandingGuidanceAction as n, optionArgs as nn, selectionFromFlags as nt, verifyLoginAction as o, isObject$1 as on, removeSsoFromFlow as ot, worktreeIsDirty as p, sanitizeRejection as pn, credentialVariablesOf as pt, SETUP_FLAG_KEYS as q, shellCommand as qt, customizeAndPublishActions as r, publicCliCommand as rn, ssoEnableArgs as rt, renderBoxActions as s, parseJsonObject as sn, removeSsoFromSchema as st, showSkillsHint as t, normalizePublicCliProse as tn, loopbackIssuerWarning as tt, diffStep as u, REQUEST_TIMEOUT_MS as un, CONNECTION_SCHEMA_REF as ut, buildBundle as v, ZitadelError as vn, FLOWS_DIR as vt, toPolicyWireBody as w, readStdin as wt, POLICIES_DIR as x, toZitadelError as xn, VARIABLE_TYPES as xt, PASSWORD_POLICY_OPERATION as y, isErrno$1 as yn, checkFlow as yt, reportClientIdOutcome as z, ciProvider as zt };
+export { republishCommands as $, processUserAgentFacts as $t, isPolicyTestFile as A, sanitizeResponse as An, checkFlow as At, CommandGroups as B, valuesOfKind as Bt, createReleaseFromBundle as C, parseJsonObject as Cn, checkCustomSlug as Ct, PASSWORD_POLICY_PATH as D, createZitadelClient$1 as Dn, refuseChangedIssuer as Dt, PASSWORD_POLICY_OPERATION as E, REQUEST_TIMEOUT_MS as En, readConnectionFiles as Et, toPolicyWireBody as F, isErrno$1 as Fn, parseVariableValue as Ft, readFlowFiles as G, renderDetail as Gt, authMethods as H, variableInventoryCells as Ht, readJsonDir as I, isMissingEndpoint as In, readStdin as It, SCHEMAS_DIR as J, renderTable as Jt, readSchemaFiles as K, renderList as Kt, readJsonDirEntries as L, toZitadelError as Ln, toInventoryRows as Lt, passwordPolicyFile as M, listenForInterrupt as Mn, VARIABLE_TYPES as Mt, policyFileIssues as N, stopListeningForInterrupt as Nn, assertVariableName as Nt, POLICIES_DIR as O, escapeControlCharacters as On, storedCustomSettings as Ot, policyFileName as P, ZitadelError as Pn, frozenVariables as Pt, republishArgs as Q, installUserAgent as Qt, BRANDING_DIR as R, toVariableRow as Rt, servesPrimary as S, isObject$1 as Sn, IDPS_DIR as St, buildBundle as T, stableStringify as Tn, planConnection as Tt, enabledMethods as U, variableReadScope as Ut, compareInGroup as V, variableCells as Vt, methodsOf as W, variableScope as Wt, reportClientIdOutcome as X, takeReportedWarnings as Xt, publishClientId as Y, reportWarning as Yt, reportSecretOutcome as Z, buildUserAgent as Zt, worktreeIsDirty as _, normalizePublicCliJson as _n, removeSsoFromFlow as _t, serverLogAction as a, nonBlankArg as an, SETUP_FLAG_NAMES as at, createDeployment as b, publicCliCommand as bn, ssoProvidersRefusal as bt, wrapForBox as c, inShell as cn, customFlagText as ct, deployMessage as d, shellCommand as dn, givenCustomFlags as dt, hostAgent as en, storeClientSecret as et, messageFlag as f, unscopedCommand as fn, loopbackIssuerWarning as ft, headSha as g, normalizePublicCliCommands as gn, applySsoToSchema as gt, runSteps as h, maskPublicCliVersion as hn, applySsoToFlow as ht, exploreAllCommands as i, envEnabled as in, SETUP_FLAG_KEYS as it, parsePasswordMinLength as j, interruptSignal as jn, offeredSignInMethods as jt, POLICY_TEST_SUFFIX as k, sanitizeRejection as kn, FLOWS_DIR as kt, DEPLOY_ARGS as l, portableSuggestions as ln, customFlagValues as lt, validateStep as m, isTrainVersion as mn, ssoEnableArgs as mt, brandingGuidanceAction as n, loadOrCreateIdentity as nn, ENABLE_FLAG_KEYS as nt, verifyLoginAction as o, nonBlankString as on, checkGivenCustomFlags as ot, deployInitialRelease as p, isPortableShellWord as pn, selectionFromFlags as pt, selectSchema as q, renderRows as qt, customizeAndPublishActions as r, resolveConsent as rn, ENABLE_FLAG_NAMES as rt, renderBoxActions as s, asEnvironmentSelector as sn, customExample as st, showSkillsHint as t, ciProvider as tn, askConnectionEndpoints as tt, diffStep as u, projectCommand as un, flagText as ut, Repository as v, normalizePublicCliProse as vn, removeSsoFromSchema as vt, revokeRelease as w, setTopLevelJsonKey as wn, credentialVariablesOf as wt, rollbackDeployment as x, sdkVersionForCli as xn, CONNECTION_SCHEMA_REF as xt, RepositoryError as y, optionArgs as yn, ssoEditRefusal as yt, COMMAND_GROUPS as z, toVariableRows as zt };
 
-//# sourceMappingURL=skills-hint-CBoak9HL.mjs.map
+//# sourceMappingURL=skills-hint-C8oe8cCo.mjs.map