@zitadel/cli 0.2.0 → 0.3.0

package/dist/index.mjs

@@ -1,9 +1,9 @@
-import { $ as flagText, $t as normalizePublicCliCommands, At as variableInventoryCells, B as reportSecretOutcome, Bt as loadOrCreateIdentity, C as passwordPolicyFile, Ct as parseVariableValue, D as BRANDING_DIR, Dt as toVariableRows, E as readJsonDirEntries, Et as toVariableRow, F as readSchemaFiles, Ft as buildUserAgent, G as ENABLE_FLAG_KEYS, Gt as portableSuggestions, H as republishCommands, Ht as envEnabled, I as selectSchema, It as installUserAgent, J as SETUP_FLAG_NAMES, Jt as unscopedCommand, K as ENABLE_FLAG_NAMES, Kt as projectCommand, L as SCHEMAS_DIR, Lt as processUserAgentFacts, M as enabledMethods, Mt as variableScope, N as methodsOf, Nt as reportWarning, Ot as valuesOfKind, P as readFlowFiles, Pt as takeReportedWarnings, Q as customFlagValues, Qt as normalizePublicCliCommand, R as publishClientId, Rt as hostAgent, S as parsePasswordMinLength, St as assertVariableName, T as readJsonDir, Tt as toInventoryRows, U as storeClientSecret, Ut as asEnvironmentSelector, V as republishArgs, Vt as resolveConsent, W as askConnectionEndpoints, Wt as inShell, X as customExample, Xt as isTrainVersion, Y as checkGivenCustomFlags, Yt as isPortableShellWord, Z as customFlagText, Zt as maskPublicCliVersion, _ as servesPrimary, _n as stopListeningForInterrupt, _t as storedCustomSettings, a as serverLogAction, an as collectPages, at as applySsoToSchema, b as PASSWORD_POLICY_PATH, bn as isMissingEndpoint, bt as offeredSignInMethods, c as wrapForBox, cn as setTopLevelJsonKey, ct as ssoEditRefusal, d as validateStep, dn as createZitadelClient, dt as IDPS_DIR, en as normalizePublicCliJson, et as givenCustomFlags, f as headSha, fn as escapeControlCharacters, ft as checkCustomSlug, g as rollbackDeployment, gn as listenForInterrupt, gt as refuseChangedIssuer, h as listLiveDeployments, hn as interruptSignal, ht as readConnectionFiles, i as exploreAllCommands, in as sdkVersionForCli, it as applySsoToFlow, j as authMethods, jt as variableReadScope, k as CommandGroups, kt as variableCells, l as DEPLOY_ARGS, ln as stableStringify, lt as ssoProvidersRefusal, m as createDeployment, mn as sanitizeResponse, mt as planConnection, n as brandingGuidanceAction, nn as optionArgs, nt as selectionFromFlags, o as verifyLoginAction, on as isObject, ot as removeSsoFromFlow, p as worktreeIsDirty, pn as sanitizeRejection, pt as credentialVariablesOf, q as SETUP_FLAG_KEYS, qt as shellCommand, r as customizeAndPublishActions, rn as publicCliCommand, rt as ssoEnableArgs, s as renderBoxActions, sn as parseJsonObject, st as removeSsoFromSchema, t as showSkillsHint, tn as normalizePublicCliProse, tt as loopbackIssuerWarning, u as diffStep, un as REQUEST_TIMEOUT_MS$1, ut as CONNECTION_SCHEMA_REF, v as buildBundle, vn as ZitadelError, vt as FLOWS_DIR, w as toPolicyWireBody, wt as readStdin, x as POLICIES_DIR, xn as toZitadelError, xt as VARIABLE_TYPES, yn as isErrno$2, yt as checkFlow, z as reportClientIdOutcome, zt as ciProvider } from "./skills-hint-CBoak9HL.mjs";
+import { $ as checkGivenCustomFlags, $t as isPortableShellWord, A as readJsonDirEntries, At as toVariableRow, B as selectSchema, Bt as installUserAgent, C as isPolicyTestFile, Cn as isErrno$2, Ct as checkFlow, D as policyFileName, Dt as parseVariableValue, E as policyFileIssues, Et as assertVariableName, F as authMethods, Ft as variableReadScope, G as republishArgs, Gt as resolveConsent, H as publishClientId, Ht as hostAgent, I as enabledMethods, It as variableScope, J as askConnectionEndpoints, Jt as inShell, K as republishCommands, Kt as envEnabled, L as methodsOf, Lt as reportWarning, Mt as valuesOfKind, N as CommandGroups, Nt as variableCells, O as toPolicyWireBody, Ot as readStdin, Pt as variableInventoryCells, Q as SETUP_FLAG_NAMES, Qt as unscopedCommand, R as readFlowFiles, Rt as takeReportedWarnings, S as POLICY_TEST_SUFFIX, Sn as ZitadelError, St as FLOWS_DIR, T as passwordPolicyFile, Tn as toZitadelError, Tt as VARIABLE_TYPES, U as reportClientIdOutcome, Ut as ciProvider, V as SCHEMAS_DIR, Vt as processUserAgentFacts, W as reportSecretOutcome, Wt as loadOrCreateIdentity, X as ENABLE_FLAG_NAMES, Xt as projectCommand, Y as ENABLE_FLAG_KEYS, Yt as portableSuggestions, Z as SETUP_FLAG_KEYS, Zt as shellCommand, _ as servesPrimary, _n as sanitizeRejection, _t as credentialVariablesOf, a as serverLogAction, an as normalizePublicCliProse, at as loopbackIssuerWarning, b as PASSWORD_POLICY_PATH, bn as listenForInterrupt, bt as refuseChangedIssuer, c as wrapForBox, cn as sdkVersionForCli, ct as applySsoToFlow, d as validateStep, dn as parseJsonObject, dt as removeSsoFromSchema, en as isTrainVersion, et as customExample, f as headSha, fn as setTopLevelJsonKey, ft as ssoEditRefusal, g as rollbackDeployment, gn as escapeControlCharacters, gt as checkCustomSlug, h as listLiveDeployments, hn as createZitadelClient, ht as IDPS_DIR, i as exploreAllCommands, in as normalizePublicCliJson, it as givenCustomFlags, j as BRANDING_DIR, jt as toVariableRows, k as readJsonDir, kt as toInventoryRows, l as DEPLOY_ARGS, ln as collectPages, lt as applySsoToSchema, m as createDeployment, mn as REQUEST_TIMEOUT_MS$1, mt as CONNECTION_SCHEMA_REF, n as brandingGuidanceAction, nn as normalizePublicCliCommand, nt as customFlagValues, o as verifyLoginAction, on as optionArgs, ot as selectionFromFlags, p as worktreeIsDirty, pn as stableStringify, pt as ssoProvidersRefusal, q as storeClientSecret, qt as asEnvironmentSelector, r as customizeAndPublishActions, rn as normalizePublicCliCommands, rt as flagText, s as renderBoxActions, sn as publicCliCommand, st as ssoEnableArgs, t as showSkillsHint, tn as maskPublicCliVersion, tt as customFlagText, u as diffStep, un as isObject, ut as removeSsoFromFlow, v as buildBundle, vn as sanitizeResponse, vt as planConnection, w as parsePasswordMinLength, wn as isMissingEndpoint, wt as offeredSignInMethods, x as POLICIES_DIR, xn as stopListeningForInterrupt, xt as storedCustomSettings, yn as interruptSignal, yt as readConnectionFiles, z as readSchemaFiles, zt as buildUserAgent } from "./skills-hint-N1H5-ny1.mjs";
 import { createRequire } from "node:module";
 import { Args, Command, Flags } from "@oclif/core";
 import consola$1, { consola } from "consola";
 import { ApiError, CSRF_HEADER, request } from "@zitadel/api/runtime/fetch";
-import { access, chmod, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { access, chmod, lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
 import { text } from "node:stream/consumers";
 import * as schemas from "@zitadel/api/generated/endpoints/zitadelNextGen.zod";
 import { CreateGrantBody, CreateIdpBody, CreateTeamBody, CreateUserBody, GetBrandingByIdResponse, GetFlowDefinitionResponse, GetGrantResponse, GetIdpByIdResponse, GetPolicyResponse, GetProjectResponse, GetReleaseByIdResponse, GetSchemaByIdResponse, GetSessionResponse, GetTeamResponse, GetUserByIDResponse, ListBrandingResponse, ListEventsResponse, ListFlowDefinitionsResponse, ListPoliciesResponse, ListReleasesResponse, ListSchemasResponse, PatchProjectBody, PatchUserByIDBody, PublishPolicyBody, QueryGrantsBody, QueryGrantsResponse, QueryIdpsBody, QueryIdpsResponse, QueryProjectsBody, QueryProjectsResponse, QuerySessionsBody, QuerySessionsResponse, QueryTeamsBody, QueryTeamsResponse, QueryUsersBody, QueryUsersResponse, UpdateTeamBody, getClaimStatusQueryChallengeIdRegExp } from "@zitadel/api/generated/endpoints/zitadelNextGen.zod";
@@ -13,7 +13,7 @@ import { execFile, spawn, spawnSync } from "node:child_process";
 import { basename, delimiter, dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
 import { constants, existsSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { isDeepStrictEqual, parseEnv } from "node:util";
+import { isDeepStrictEqual, parseEnv, promisify } from "node:util";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { StringDecoder } from "node:string_decoder";
 import { resolveServerBinary, serverBinaryPath } from "@zitadel/server/binary";
@@ -22,7 +22,7 @@ import pc from "picocolors";
 import { DEFAULT_SERVER, DEFAULT_SERVER as DEFAULT_SERVER$1 } from "@zitadel/config/server";
 import mixpanelLib from "mixpanel";
 import { cancel, confirm, intro, isCancel, log, multiselect, note, outro, password, select, spinner, text as text$1 } from "@clack/prompts";
-import { policyConfigSchema, schemaConfigSchema } from "@zitadel/config/schemas";
+import { RECOMMENDED_PASSWORD_MIN_LENGTH, policyConfigSchema, policyTestFileSchema, schemaConfigSchema } from "@zitadel/config/schemas";
 import { CUSTOM_PROVIDER, DEFAULT_SCOPES, IDP_PROVIDERS, RESERVED_SLUGS, credentialVariables, idpProvider, isVariableReference, parseClientId, parseClientSecret, parseConnectionSlug, parseDisplayName, parseIssuer, parseScopes, providerOf, selectionName, validated } from "@zitadel/config/idp";
 import { BRANDING_DESIGNS, DEFAULT_BRANDING_CONFIG_PATH, DEFAULT_BRANDING_DESIGN, DEFAULT_BRANDING_TEMPLATE_PATH, DEFAULT_FLOW_CONFIG_PATH, DEFAULT_FLOW_SCHEMA_URI, DEFAULT_SCHEMA_CONFIG_PATH, DEFAULT_SETUP_PRESET, DEFAULT_SETUP_USE_CASE, SETUP_PRESETS, SETUP_USE_CASES, brandingReadmeContent, flowsReadmeContent, getDefaultBrandingConfig, getDefaultHumanUserSchema, getDefaultLoginFlow, policiesReadmeContent, schemasReadmeContent } from "@zitadel/config/defaults";
 import { BRANDING_FILE_SCHEMA_REF, META_SCHEMA_DIR, PROJECT_FILE_SCHEMA_REF, metaSchemaFiles } from "@zitadel/config/meta-schemas";
@@ -4316,19 +4316,36 @@ const CLI_COMMAND_STARTED = "cli_command_started";
 const CLI_COMMAND_COMPLETED = "cli_command_completed";
 const CLI_COMMAND_FAILED = "cli_command_failed";
 /**
-* The properties the Vercel Web Analytics copy of a lifecycle event keeps, in
-* priority order, the header first: the intake takes 8.
+* The one dimension of its own a command's Vercel Web Analytics copy keeps, by
+* command id; the rest go to Mixpanel only.
 */
-const VERCEL_EVENT_KEYS = [
-	"surface",
-	"cli_version",
-	"server_kind",
-	"command",
-	"status",
-	"reason",
-	"host_agent",
-	"non_interactive"
-];
+const VERCEL_COMMAND_DIMENSIONS = /* @__PURE__ */ new Map([
+	["setup", "framework"],
+	["claim", "claim_outcome"],
+	["doctor", "failed_checks"],
+	["api", "operation"],
+	["start", "runtime"]
+]);
+/**
+* The properties the Vercel Web Analytics copy of `command`'s lifecycle events
+* keeps, in priority order, the header first: the intake takes 8. The
+* command's own dimension ranks after `host_agent`, so on a failed run, where
+* `reason` fills the eighth place, it takes `non_interactive`'s.
+*/
+function vercelEventKeys(command) {
+	const dimension = VERCEL_COMMAND_DIMENSIONS.get(command);
+	return [
+		"surface",
+		"cli_version",
+		"server_kind",
+		"command",
+		"status",
+		"reason",
+		"host_agent",
+		...dimension === void 0 ? [] : [dimension],
+		"non_interactive"
+	];
+}
 const FIRST_RUN_NOTICE = "Zitadel CLI collects anonymous usage analytics to help improve the tool. No personal data, project details, server URLs, or file contents are ever collected. Opt out any time with DO_NOT_TRACK=1, ZITADEL_TELEMETRY=0, or the --no-telemetry flag.";
 /**
 * Process-stable device facts shared by both the event bag and the user
@@ -4647,7 +4664,7 @@ var BaseCommand = class extends Command {
 			env: process.env,
 			flag,
 			debug: this.meta.debug,
-			vercelKeys: VERCEL_EVENT_KEYS
+			vercelKeys: vercelEventKeys(this.meta.command)
 		});
 		if (!this.telemetry.enabled) return;
 		this.telemetry.track(CLI_COMMAND_STARTED, commandEventProperties(this.meta, this.telemetryInvocationId, this.telemetryProps));
@@ -5420,7 +5437,7 @@ async function resolveEnvironment(input) {
 		})).value } : void 0
 	}];
 	if (input.envFile) {
-		const values = await readEnvFile(resolve(input.cwd, input.envFile));
+		const values = await readEnvFile(resolve(input.envFile));
 		if (values === void 0) throw new ZitadelError("E_VALIDATION", `--env-file ${input.envFile} was not found`);
 		sources.push({
 			source: `--env-file ${input.envFile}`,
@@ -5603,7 +5620,7 @@ const environmentFlags = {
 		char: "e",
 		description: "Environment to run against, e.g. production. Defaults to ZITADEL_ENV, then the hosting platform's build (VERCEL_ENV, or Netlify's CONTEXT), then development."
 	}),
-	"env-file": nonBlankString({ description: "Read ZITADEL_* values from this file ahead of the process environment. Cannot be combined with --env." })
+	"env-file": nonBlankString({ description: "Read ZITADEL_* values from this file ahead of the process environment. A relative path is read from the current directory, not from --cwd. Cannot be combined with --env." })
 };
 /**
 * The flags the `preview` command adds on top of the environment ones: which
@@ -5642,6 +5659,16 @@ function environmentSelectorSuffix(input) {
 	if (input.cwd !== void 0) parts.push(shellOption("--cwd", input.cwd));
 	return asEnvironmentSelector(parts.length === 0 ? "" : ` ${parts.join(" ")}`);
 }
+/**
+* A file in the project directory, as `--env-file` names it: relative to the
+* shell's directory, so a run with `--cwd` puts that directory in front. Node
+* reads `--env-file` from anywhere on the command line before the CLI starts,
+* from the shell's directory, and exits when the file is not there; a path
+* relative to `--cwd` would stop the suggested command before it runs.
+*/
+function projectEnvFile(cwd, file) {
+	return cwd === void 0 ? file : posix.join(cwd, file);
+}
 //#endregion
 //#region src/lib/oclif/environment-command.ts
 /**
@@ -7555,16 +7582,23 @@ async function revokeRelease(client, projectId, releaseId) {
 //#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. 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.
+* 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;
-		await step.run(ctx);
+		const reported = await step.run(ctx);
+		if (reported) report = {
+			...report,
+			...reported
+		};
 	}
+	return report;
 }
 //#endregion
 //#region src/lib/release/origins.ts
@@ -7676,6 +7710,310 @@ function isErrno$1(error, code) {
 	return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 //#endregion
+//#region src/lib/policies/tests.ts
+/**
+* Policy tests (#1445): `.zitadel/policies/<operation>.test.json` files hold
+* cases `zitadel policies test` evaluates on the server
+* (`POST /policies/evaluate`). The CLI never evaluates a policy itself; it
+* picks the config to evaluate, sends each case and compares the decision.
+*
+* The config comes from the sibling policy file, or with `--release` from the
+* revision a release pins. Neither present means no policy: the cases are
+* evaluated with `{}`, which is what the server enforces then (only its own
+* guards), so a case that expects a refusal shows what would get through.
+*
+* **Dependency rule.** No upward imports (`commands/`, `release/`).
+*/
+/** The name a test file must have: its operation, beside the operation's policy file. */
+function policyTestFileName(operation) {
+	return `${operation}${POLICY_TEST_SUFFIX}`;
+}
+/**
+* What is wrong with a policy test file, each as a line naming the file, or
+* none: it must parse against the strict `policyTestFileSchema` and be named
+* after its operation, as a policy file is.
+*/
+function policyTestFileIssues(data, file) {
+	const result = policyTestFileSchema.safeParse(data);
+	if (!result.success) return result.error.issues.map((issue) => `${file}: ${issue.path.join(".") || "(root)"} ${issue.message}`);
+	const expected = policyTestFileName(result.data.operation);
+	if (file.split("/").at(-1) !== expected) return [`${file} tests the ${result.data.operation} policy, so it must be named ${expected}`];
+	return [];
+}
+/**
+* The test files in `.zitadel/policies/`, checked, and the problems found.
+* `operations` narrows them to those operations' files, by name and before
+* anything is parsed, so a broken test file of another operation never
+* blocks the ones asked for. One without a test file is a problem, so a typo
+* in the filter never passes silently.
+*/
+async function readPolicyTests(cwd, operations = []) {
+	const wanted = new Set(operations.map(policyTestFileName));
+	const entries = await readJsonDirEntries(join(cwd, POLICIES_DIR), { skip: (name) => !isPolicyTestFile(name) || wanted.size > 0 && !wanted.has(name) });
+	const suites = [];
+	const issues = [];
+	for (const entry of entries) {
+		const file = `${POLICIES_DIR}/${entry.name}`;
+		const problems = policyTestFileIssues(entry.body, file);
+		if (problems.length > 0) {
+			issues.push(...problems);
+			continue;
+		}
+		suites.push({
+			file,
+			test: policyTestFileSchema.parse(entry.body)
+		});
+	}
+	for (const operation of operations) {
+		const file = policyTestFileName(operation);
+		if (!entries.some((entry) => entry.name === file)) issues.push(`${POLICIES_DIR}/${file} does not exist`);
+	}
+	return {
+		suites,
+		issues
+	};
+}
+/**
+* The policies in `.zitadel/policies/`, by operation, and the problems found.
+* A policy file that fails its own check is a problem rather than "no
+* policy": testing `{}` in its place would report on a policy nobody wrote.
+* `operations` narrows them to those operations' files, by name and before
+* anything is parsed, as {@link readPolicyTests} does.
+*/
+async function policiesFromFiles(cwd, operations = []) {
+	const wanted = new Set(operations.map(policyFileName));
+	const entries = await readJsonDirEntries(join(cwd, POLICIES_DIR), { skip: (name) => isPolicyTestFile(name) || wanted.size > 0 && !wanted.has(name) });
+	const policies = /* @__PURE__ */ new Map();
+	const issues = [];
+	for (const entry of entries) {
+		const file = `${POLICIES_DIR}/${entry.name}`;
+		const problems = policyFileIssues(entry.body, file);
+		if (problems.length > 0) {
+			issues.push(...problems);
+			continue;
+		}
+		const { operation, config } = entry.body;
+		policies.set(operation, {
+			config,
+			source: { file }
+		});
+	}
+	return {
+		policies,
+		issues
+	};
+}
+/**
+* The policies a release pins, by operation, read as the revisions it pins.
+* Whether it is revoked and whether it pins a flow come along: neither stops
+* the test, but both mean its sign-ins do not use these policies.
+*/
+async function policiesFromRelease(client, projectId, releaseId) {
+	const release = await client.getReleaseById(releaseId, { project_id: projectId });
+	const pinned = release.pointers.filter((pointer) => pointer.kind === "policy");
+	const revisions = await Promise.all(pinned.map((pointer) => client.getPolicyRevision(pointer.revision_id, { project_id: projectId })));
+	return {
+		policies: new Map(pinned.map((pointer, index) => [pointer.handle, {
+			config: revisions[index]?.config,
+			source: { revision_id: pointer.revision_id }
+		}])),
+		revoked: release.revoked_at !== null,
+		pinsFlow: release.pointers.some((pointer) => pointer.kind === "flow_definition")
+	};
+}
+/**
+* Whether a decision is what a case expects: `allowed` always, `code` when
+* given, and `violations` when given as exactly that set of rule names, so a
+* rule that fails unexpectedly fails the case too.
+*/
+function caseHolds(expected, actual) {
+	if (expected.allowed !== actual.allowed) return false;
+	if (expected.code !== void 0 && expected.code !== actual.code) return false;
+	if (expected.violations !== void 0) {
+		const got = Object.keys(actual.violations ?? {}).sort();
+		const want = [...new Set(expected.violations)].sort();
+		return got.length === want.length && got.every((name, index) => name === want[index]);
+	}
+	return true;
+}
+/** How many evaluate requests a run keeps in flight at once. */
+const EVALUATE_CONCURRENCY = 8;
+/** `fn` over `items` with at most `limit` calls in flight, results in item order. */
+async function mapBounded(items, limit, fn) {
+	const out = new Array(items.length);
+	let next = 0;
+	const worker = async () => {
+		while (next < items.length) {
+			const index = next++;
+			out[index] = await fn(items[index]);
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+	return out;
+}
+/**
+* Evaluates every case of every suite against its operation's policy, or `{}`
+* when there is none: one request per case, a few in flight at once, the
+* results in file and case order.
+*/
+async function runPolicyTests(client, projectId, suites, policies) {
+	const outcomes = await mapBounded(suites.flatMap(({ test }, suite) => test.cases.map((testCase) => ({
+		suite,
+		operation: test.operation,
+		testCase
+	}))), EVALUATE_CONCURRENCY, async ({ suite, operation, testCase }) => {
+		const actual = await client.evaluatePolicy({
+			operation,
+			config: policies.get(operation)?.config ?? {},
+			input: testCase.input,
+			...testCase.facts === void 0 ? {} : { facts: testCase.facts }
+		}, { project_id: projectId });
+		return {
+			suite,
+			result: {
+				name: testCase.name,
+				passed: caseHolds(testCase.expect, actual),
+				expected: testCase.expect,
+				actual
+			}
+		};
+	});
+	return suites.map(({ file, test }, suite) => ({
+		operation: test.operation,
+		file,
+		policy: policies.get(test.operation)?.source ?? null,
+		cases: outcomes.filter((outcome) => outcome.suite === suite).map(({ result }) => result)
+	}));
+}
+/**
+* A decision in words: `allowed`, or refused with its code and its rules,
+* each when known, so a mismatch in either shows on the line.
+*/
+function describeDecision(decision) {
+	if (decision.allowed) return "allowed";
+	const rules = decision.violations?.length ? decision.violations.join(", ") : void 0;
+	const reason = [decision.code, rules].filter((part) => part !== void 0).join(": ");
+	return reason === "" ? "refused" : `refused (${reason})`;
+}
+/** Where a suite's policy came from, as its heading names it. */
+function describePolicy(policy, release) {
+	if (policy === null) return release === void 0 ? "no policy file, nothing enforced" : `release ${release} pins no policy, nothing enforced`;
+	if ("file" in policy) return policy.file;
+	return `release ${release}, revision ${policy.revision_id}`;
+}
+/**
+* The results for a terminal: each test file under a heading naming the
+* policy it ran against, a line per case, and on a failed case what was
+* expected and what the server decided; then the totals.
+*/
+function renderPolicyTestResults(results, release) {
+	const lines = [];
+	let passed = 0;
+	let failed = 0;
+	for (const result of results) {
+		lines.push(`${result.operation}  (${describePolicy(result.policy, release)})`);
+		for (const testCase of result.cases) {
+			if (testCase.passed) {
+				passed++;
+				lines.push(`  ✓ ${testCase.name}`);
+				continue;
+			}
+			failed++;
+			const actual = describeDecision({
+				allowed: testCase.actual.allowed,
+				code: testCase.actual.code,
+				violations: Object.keys(testCase.actual.violations ?? {})
+			});
+			lines.push(`  ✗ ${testCase.name}: expected ${describeDecision(testCase.expected)}, got ${actual}`);
+		}
+	}
+	lines.push("", failed === 0 ? `${passed} passed` : `${passed} passed, ${failed} failed`);
+	return lines.join("\n");
+}
+//#endregion
+//#region src/commands/policies/test.ts
+/**
+* `zitadel policies test` — evaluate the cases in
+* `.zitadel/policies/<operation>.test.json` on the server (#1445).
+*
+* Against the sibling policy files by default, or with `--release` against
+* the revisions a built release pins. The server evaluates every case with
+* the live operation's own check (`POST /policies/evaluate`); nothing is read
+* from or written to the project's policies. A failing case fails the
+* command with `E_VALIDATION`, carrying the full results.
+*/
+var PoliciesTest = class PoliciesTest extends EnvironmentCommand {
+	static description = "Run the test cases in .zitadel/policies/ against the policies";
+	static group = CommandGroups.configuration;
+	static examples = [
+		"<%= config.bin %> policies test",
+		"<%= config.bin %> policies test auth.factor.password.set",
+		"<%= config.bin %> policies test --release rel_01KXB7C2M4N7F0N9WD3P2E4YM7",
+		"<%= config.bin %> policies test --json"
+	];
+	static args = { operation: Args.string({
+		required: false,
+		description: "Test only this operation's policy, such as auth.factor.password.set."
+	}) };
+	static flags = { release: Flags.string({ description: "Test the policies a release pins (rel_…) instead of the files in .zitadel/policies/." }) };
+	async run() {
+		const { args, flags } = await this.parse(PoliciesTest);
+		await this.toMeta(flags);
+		const { cwd } = this.meta;
+		const operations = args.operation === void 0 ? [] : [args.operation];
+		const { suites, issues } = await readPolicyTests(cwd, operations);
+		if (issues.length > 0) throw new ZitadelError("E_VALIDATION", "The policy test files are not valid", {
+			details: { issues },
+			hint: issues.join("\n")
+		});
+		if (suites.length === 0) return this.emit({
+			status: "skipped",
+			reason: "no-policy-tests",
+			pretty: `No policy test files in ${POLICIES_DIR}/. Add <operation>.test.json beside a policy; ${POLICIES_DIR}/README.md shows one.`
+		});
+		const { client, projectId } = await this.connect();
+		let policies;
+		if (flags.release === void 0) {
+			const fromFiles = await policiesFromFiles(cwd, operations);
+			if (fromFiles.issues.length > 0) throw new ZitadelError("E_VALIDATION", "The policy files are not valid", {
+				details: { issues: fromFiles.issues },
+				hint: fromFiles.issues.join("\n")
+			});
+			policies = fromFiles.policies;
+		} else {
+			const fromRelease = await policiesFromRelease(client, projectId, flags.release);
+			if (fromRelease.revoked) reportWarning(`Release ${flags.release} is revoked, so no origin serves its policies.`);
+			if (!fromRelease.pinsFlow) reportWarning(`Release ${flags.release} pins no flow, so sign-ins served it use the newest policy revisions, not the ones tested here.`);
+			policies = fromRelease.policies;
+		}
+		const results = await runPolicyTests(client, projectId, suites, policies);
+		const cases = results.flatMap((result) => result.cases);
+		const failed = cases.filter((testCase) => !testCase.passed).length;
+		this.recordTelemetry({
+			policy_source: flags.release === void 0 ? "files" : "release",
+			case_count: cases.length,
+			failed_count: failed
+		});
+		const data = {
+			source: flags.release === void 0 ? "files" : "release",
+			...flags.release === void 0 ? {} : { release_id: flags.release },
+			operations: results,
+			passed: cases.length - failed,
+			failed
+		};
+		const pretty = renderPolicyTestResults(results, flags.release);
+		if (failed > 0) throw new ZitadelError("E_VALIDATION", `${failed} of ${cases.length} policy test cases failed`, {
+			details: data,
+			hint: pretty
+		});
+		return this.emit({
+			status: "ok",
+			data,
+			pretty
+		});
+	}
+};
+//#endregion
 //#region src/lib/browser.ts
 /**
 * Openers tried in order on Linux and the BSDs. `xdg-open` is the standard and
@@ -8706,7 +9044,7 @@ var Deploy = class Deploy extends EnvironmentCommand {
 		}
 		const { bundle, resourceCount, brandingSources, idpFiles, policyFiles } = await buildBundle(cwd);
 		this.recordTelemetry({ resources: resourceCount });
-		await runSteps([validateStep, diffStep], {
+		const reported = await runSteps([validateStep, diffStep], {
 			cwd,
 			client,
 			projectId,
@@ -8726,7 +9064,8 @@ var Deploy = class Deploy extends EnvironmentCommand {
 			data: {
 				dry_run: true,
 				resources: resourceCount,
-				targets: ["primary"]
+				targets: ["primary"],
+				...reported
 			},
 			pretty: `Validated ${resourceCount} resource${resourceCount === 1 ? "" : "s"}. Nothing was deployed (dry run).`
 		});
@@ -8773,6 +9112,7 @@ var Deploy = class Deploy extends EnvironmentCommand {
 				deployment_id: deployment.id,
 				resources: resourceCount,
 				origins: servedOrigins,
+				...reported,
 				...nextCommandsData([this.suggest("deployment list")])
 			},
 			pretty: [
@@ -10274,6 +10614,8 @@ ${themingParagraph}
 
 ${sessionStateParagraph}
 
+After sign-in the login goes to the path in its page's \`?next=\` parameter, ahead of \`post-sign-in-url\`, so a visitor a protected route sent to sign in lands back on that route; a page of your own can read \`next\` to tell them why they must sign in. Set \`force-post-sign-in-url\` (SDK wrappers: \`forcePostSignInUrl\`) on a login whose page uses \`next\` for something else.
+
 Machine-readable dialect (read these before authoring flow or schema edits):
 
 - \`zitadel.json\` carries \`"$schema": "./.zitadel/meta/project.json"\`, the schema of the project configuration.
@@ -15697,9 +16039,13 @@ var Orca = class {
 			details: { entries: target.entries }
 		});
 		assertNpmSafeScaffoldDirectoryName(cwd);
+		const created = await mkdir(cwd, { recursive: true });
 		const before = await listEntries(cwd);
 		const stash = await stashScaffoldDir(cwd, target.entries);
-		const undo = () => undoScaffold(cwd, before, stash);
+		const undo = () => created === void 0 ? undoScaffold(cwd, before, stash) : rm(created, {
+			recursive: true,
+			force: true
+		});
 		let facts;
 		try {
 			await this.scaffolderFor(framework).scaffold(cwd, framework);
@@ -15788,7 +16134,7 @@ function createOrca() {
 	return new Orca(detectors, scaffolders, patchers);
 }
 async function inspectScaffoldTarget(cwd) {
-	const names = [...await readdir(cwd)].sort();
+	const names = [...await scaffoldTargetEntries(cwd)].sort();
 	const others = [];
 	for (const name of names) if (!await isLocalRuntimeEntry(cwd, name)) others.push(name);
 	if (others.length === 0) return {
@@ -15802,6 +16148,35 @@ async function inspectScaffoldTarget(cwd) {
 	};
 }
 /**
+* The entries of a scaffold target, or none when it does not exist yet: the
+* scaffold creates it, as a framework's own generator creates `my-app`, so a
+* `--cwd` naming the new app's directory works before that directory does.
+*/
+async function scaffoldTargetEntries(cwd) {
+	try {
+		return await readdir(cwd);
+	} catch (error) {
+		if (isErrno$2(error, "ENOENT")) return [];
+		throw error;
+	}
+}
+/**
+* Refuses a project directory that is a file, or lies under one, before
+* anything reads inside it. One that does not exist yet passes: a scaffold
+* creates it.
+*/
+async function assertDirectoryOrMissing(cwd) {
+	let isDirectory;
+	try {
+		isDirectory = (await stat(cwd)).isDirectory();
+	} catch (error) {
+		if (isErrno$2(error, "ENOENT")) return;
+		if (!isErrno$2(error, "ENOTDIR")) throw error;
+		isDirectory = false;
+	}
+	if (!isDirectory) throw new ZitadelError("E_VALIDATION", `${cwd} is not a directory`, { hint: "Point --cwd at the app's directory, or at one that does not exist yet for setup to create." });
+}
+/**
 * Whether `name` in `cwd` is one of the entries `zitadel start` writes
 * (`ensureLocalState`): a `.zitadel` that holds nothing but the local runtime,
 * or a `.gitignore` that holds nothing but the line ignoring it. Either may be
@@ -16557,6 +16932,54 @@ function devCommandFor(packageManager) {
 		case "bun": return command("bun", ["run", "dev"]);
 	}
 }
+/**
+* The flag that runs a package manager in another directory, and whether a
+* relative directory may be given to it: npm's `--prefix` and pnpm's `--dir`
+* read one from the shell's directory, while bun documents `--cwd` as an
+* absolute path and Yarn 2+ has mishandled relative ones, so those two get the
+* resolved directory.
+*/
+const DIRECTORY_FLAG = {
+	npm: {
+		flag: "--prefix",
+		relative: true
+	},
+	pnpm: {
+		flag: "--dir",
+		relative: true
+	},
+	yarn: {
+		flag: "--cwd",
+		relative: false
+	},
+	bun: {
+		flag: "--cwd",
+		relative: false
+	}
+};
+/**
+* `packageCommand` as suggested from the shell's directory when the project is
+* elsewhere (`npm --prefix app run dev`), for a run given `--cwd`. Each
+* suggested command runs in a shell of its own, so a `cd` in front of one would
+* not carry over to the next.
+*
+* @param typed - `--cwd` as typed; `undefined` leaves the command as it is.
+* @param resolved - The same directory, absolute.
+*/
+function inDirectory(packageCommand, typed, resolved) {
+	if (typed === void 0) return packageCommand;
+	const { flag, relative } = DIRECTORY_FLAG[packageCommand.command];
+	const dir = relative ? typed : resolved;
+	return {
+		command: packageCommand.command,
+		args: [...optionArgs(flag, dir), ...packageCommand.args],
+		display: [
+			packageCommand.command,
+			shellOption(flag, dir),
+			...packageCommand.args
+		].join(" ")
+	};
+}
 async function runPackageCommand(packageCommand, options) {
 	await new Promise((resolve, reject) => {
 		const child = spawn(packageCommand.command, packageCommand.args, {
@@ -17108,6 +17531,7 @@ var Doctor = class Doctor extends BaseCommand {
 		const { cwd, dryRun } = this.meta;
 		const nearest = await readNearestRuntimeMetadata(cwd);
 		const existingRuntime = nearest?.runtime;
+		const parentRuntimeDir = nearest !== void 0 && nearest.dir !== cwd ? nearest.dir : void 0;
 		const runtimeBackend = resolveRuntimeBackend$1({
 			runtime: flags.runtime,
 			image: flags.image,
@@ -17115,7 +17539,7 @@ var Doctor = class Doctor extends BaseCommand {
 			existingRuntime
 		});
 		const image = flags.image ?? this.meta.env.ZITADEL_LOCAL_IMAGE ?? defaultLocalServerImageForCliVersion(this.meta.cliVersion);
-		const runtimeChecks = hostedServer === void 0 ? await runLocalRuntimeChecks(nearest?.dir ?? cwd, existingRuntime, runtimeBackend, image, port, this.localServers()) : [];
+		const runtimeChecks = hostedServer === void 0 ? await runLocalRuntimeChecks(nearest?.dir ?? cwd, existingRuntime, runtimeBackend, image, port, this.localServers(), parentRuntimeDir) : [];
 		const hasConfig = await hasZitadelConfig(cwd);
 		const ctx = {
 			cwd,
@@ -17165,7 +17589,7 @@ var Doctor = class Doctor extends BaseCommand {
 		}).then((environment) => environment.values.ZITADEL_PROJECT_ID?.value === projectId, () => false);
 		const claimSelector = await namesProject(join(cwd, ".env.development.local"), Promise.resolve(projectId)) ? environmentSelectorSuffix({
 			cwd: cwdFlag,
-			envFile: ".env.development.local",
+			envFile: projectEnvFile(cwdFlag, ".env.development.local"),
 			server: projectServer
 		}) : bareResolves ? environmentSelectorSuffix({
 			cwd: cwdFlag,
@@ -17195,7 +17619,7 @@ var Doctor = class Doctor extends BaseCommand {
 			...warningAdvice ? nextCommandsData(warningAdvice.nextCommands) : {}
 		};
 		if (failed.length > 0) {
-			const advice = failureAdvice(failed, image, port, this.meta.cliVersion, selector, nearest !== void 0 && nearest.dir !== cwd ? nearest.dir : void 0);
+			const advice = failureAdvice(failed, image, port, this.meta.cliVersion, selector, parentRuntimeDir, cwdFlag);
 			const code = failed.some((check) => check.name === "port") ? "E_PORT_IN_USE" : failed.find((check) => check.code !== void 0)?.code ?? "E_VALIDATION";
 			throw new ZitadelError(code, "Zitadel doctor found issues", {
 				hint: advice.hint,
@@ -17213,7 +17637,7 @@ var Doctor = class Doctor extends BaseCommand {
 		});
 	}
 };
-function failureAdvice(failed, image, port, cliVersion, selector, runtimeDir) {
+function failureAdvice(failed, image, port, cliVersion, selector, runtimeDir, cwdFlag) {
 	const failedNames = new Set(failed.map((check) => check.name));
 	if (failedNames.has("server-binary")) return {
 		hint: "The Zitadel server npm package is not available. Reinstall the CLI package, then retry.",
@@ -17249,15 +17673,28 @@ function failureAdvice(failed, image, port, cliVersion, selector, runtimeDir) {
 		};
 	}
 	if (failedNames.has("runtime")) {
-		const at = runtimeDir === void 0 ? [] : ["--cwd", runtimeDir];
-		const suggestedArgs = [["start", ...at], [
-			"reset",
-			"--force",
-			...at
-		]];
-		const nextCommands = portableSuggestions(suggestedArgs, cliVersion);
+		const suggestedArgs = runtimeDir === void 0 ? [["start"], ["reset", "--force"]] : [
+			[
+				"start",
+				"--cwd",
+				runtimeDir
+			],
+			cwdFlag === void 0 ? ["start"] : [
+				"start",
+				"--cwd",
+				cwdFlag
+			],
+			[
+				"reset",
+				"--force",
+				"--cwd",
+				runtimeDir
+			]
+		];
+		const nextCommands = suggestedArgs.flatMap((args) => portableSuggestions([args], cliVersion));
+		const quotingNote = nextCommands.length < suggestedArgs.length ? ` The runtime is in ${runtimeDir ?? "the working directory"}, a directory that needs shell quoting, so the commands that name it are left out; run \`zitadel doctor --json\` and use details.suggested_args for the exact arguments.` : "";
 		return {
-			hint: "Existing local runtime metadata was found, but the local Zitadel server is not healthy. Start it again or reset stale local data." + (nextCommands.length === 0 ? ` The runtime is in ${runtimeDir ?? "the working directory"}, a directory that needs shell quoting, so no command is printed; run \`zitadel doctor --json\` and use details.suggested_args for the exact arguments.` : ""),
+			hint: runtimeDir === void 0 ? "Existing local runtime metadata was found, but the local Zitadel server is not healthy. Start it again or reset stale local data." + quotingNote : `This folder has no Zitadel server of its own, so doctor checked the one in the parent folder, ${runtimeDir}, and found a problem with it. To keep using it, fix it or start it again. To give this folder its own server, run start here instead. Resetting deletes the local data in ${runtimeDir}, not in this folder.${quotingNote}`,
 			nextCommands,
 			suggestedArgs
 		};
@@ -17388,7 +17825,7 @@ async function hostedServerWithoutLocalRuntime(cwd, flags) {
 * holding its `.zitadel/local` state, or the current directory when no server
 * was started yet).
 */
-async function runLocalRuntimeChecks(runtimeDir, runtime, runtimeBackend, image, port, servers) {
+async function runLocalRuntimeChecks(runtimeDir, runtime, runtimeBackend, image, port, servers, inheritedFrom) {
 	const managedRuntimeCheck = await checkManagedRuntimeProcesses(runtime, servers);
 	if (runtimeBackend === "binary") return [
 		await check("server-binary", "Server npm package is available", async () => {
@@ -17399,7 +17836,7 @@ async function runLocalRuntimeChecks(runtimeDir, runtime, runtimeBackend, image,
 			return probe.checkedPath === probe.targetPath ? `${probe.targetPath} is writable` : `${probe.targetPath} can be created (${probe.checkedPath} is writable)`;
 		}, "warn"),
 		await check("port", `Port ${String(port)} is available`, () => checkPortAvailability(runtime, port)),
-		await checkRuntime(runtime, runtimeBackend),
+		await checkRuntime(runtime, runtimeBackend, inheritedFrom),
 		managedRuntimeCheck
 	];
 	const docker = await check("docker-cli", "Docker is reachable", async () => {
@@ -17430,7 +17867,7 @@ async function runLocalRuntimeChecks(runtimeDir, runtime, runtimeBackend, image,
 			return probe.checkedPath === probe.targetPath ? `${probe.targetPath} is writable` : `${probe.targetPath} can be created (${probe.checkedPath} is writable)`;
 		}, "warn"),
 		await check("port", `Port ${String(port)} is available`, () => checkPortAvailability(runtime, port)),
-		await checkRuntime(runtime, runtimeBackend),
+		await checkRuntime(runtime, runtimeBackend, inheritedFrom),
 		managedRuntimeCheck
 	];
 }
@@ -17488,12 +17925,12 @@ function additionalManagedRuntimeProcesses(processes, runtime) {
 	if (runtime?.backend !== "binary") return processes;
 	return processes.filter((processInfo) => processInfo.pid !== runtime.pid && processInfo.ppid !== runtime.pid);
 }
-async function checkRuntime(runtime, runtimeBackend) {
+async function checkRuntime(runtime, runtimeBackend, inheritedFrom) {
 	return check("runtime", "Existing local runtime is healthy", async () => {
 		if (!runtime) return "No existing runtime metadata";
 		if (runtime.backend !== runtimeBackend) throw new Error(`Existing local runtime uses ${runtime.backend}; run start --runtime ${runtimeBackend} to switch backends.`);
 		if (!await checkLocalServerHealth(runtime.server_url)) throw new Error(`${runtime.server_url} is not ready: /readyz did not answer ok`);
-		return `${runtime.server_url} is healthy`;
+		return inheritedFrom === void 0 ? `${runtime.server_url} is healthy` : `${runtime.server_url} is healthy (server started in the parent folder ${inheritedFrom})`;
 	});
 }
 function formatListeners(listeners) {
@@ -18007,9 +18444,10 @@ var EnvAdd = class EnvAdd extends Promptable(BaseCommand) {
 			]
 		};
 		const writtenKeys = new Set(Object.keys(values));
+		const cwdFlag = typeof flags.cwd === "string" ? flags.cwd : void 0;
 		const newEnvironment = environmentSelectorSuffix({
-			envFile: file,
-			...typeof flags.cwd === "string" ? { cwd: flags.cwd } : {}
+			envFile: projectEnvFile(cwdFlag, file),
+			...cwdFlag === void 0 ? {} : { cwd: cwdFlag }
 		});
 		const needsOrigin = flags.project !== void 0;
 		const createdProject = !needsOrigin;
@@ -20335,6 +20773,14 @@ const RESOURCES = {
 					field: "schema",
 					operations: FILTER_OPERATIONS
 				},
+				{
+					field: "schema_object_type",
+					operations: [
+						"equals",
+						"not_equals",
+						"contains"
+					]
+				},
 				{
 					field: "status",
 					operations: FILTER_OPERATIONS
@@ -21305,6 +21751,8 @@ async function installDependenciesForSetup(input) {
 	const packageManager = await detectPackageManager(input.cwd);
 	const installCommand = installCommandFor(packageManager);
 	const devCommand = devCommandFor(packageManager);
+	const shownInstall = inDirectory(installCommand, input.cwdFlag, input.cwd).display;
+	const shownDev = inDirectory(devCommand, input.cwdFlag, input.cwd).display;
 	if (!(input.scaffoldedFramework || input.depsAdded.length > 0)) return outcome({
 		install: {
 			status: "not-needed",
@@ -21312,7 +21760,8 @@ async function installDependenciesForSetup(input) {
 			command: installCommand.display,
 			reason: "no-dependency-changes"
 		},
-		devCommand: devCommand.display,
+		devCommand: shownDev,
+		installCommand: shownInstall,
 		cliVersion: input.cliVersion,
 		issuer: input.issuer,
 		selector: input.selector,
@@ -21325,7 +21774,8 @@ async function installDependenciesForSetup(input) {
 			command: installCommand.display,
 			reason: input.dryRun ? "dry-run" : "skip-install"
 		},
-		devCommand: devCommand.display,
+		devCommand: shownDev,
+		installCommand: shownInstall,
 		cliVersion: input.cliVersion,
 		issuer: input.issuer,
 		selector: input.selector,
@@ -21339,7 +21789,7 @@ async function installDependenciesForSetup(input) {
 			redirectStdoutToStderr: input.json
 		});
 	} catch (error) {
-		throw installFailed(error, installCommand, devCommand, input.cwd);
+		throw installFailed(error, installCommand, devCommand, shownInstall, input.cwd);
 	}
 	consola.success("Installed dependencies");
 	return outcome({
@@ -21348,7 +21798,8 @@ async function installDependenciesForSetup(input) {
 			package_manager: packageManager,
 			command: installCommand.display
 		},
-		devCommand: devCommand.display,
+		devCommand: shownDev,
+		installCommand: shownInstall,
 		cliVersion: input.cliVersion,
 		issuer: input.issuer,
 		selector: input.selector,
@@ -21359,14 +21810,14 @@ function outcome(input) {
 	const planCommand = projectCommand("deploy --dry-run", input.selector, input.cliVersion);
 	const statusCommand = projectCommand("status", input.selector, input.cliVersion);
 	const verifyActions = [
-		...input.includeInstallCommand ? [`Install dependencies: ${input.install.command}`] : [],
+		...input.includeInstallCommand ? [`Install dependencies: ${input.installCommand}`] : [],
 		`Start your project: ${input.devCommand} (then open ${input.issuer}/login)`,
 		verifyLoginAction()
 	];
 	const boxActions = [
 		...input.includeInstallCommand ? [{
 			text: "Install dependencies:",
-			command: input.install.command
+			command: input.installCommand
 		}] : [],
 		{
 			text: `Start your project (then open ${input.issuer}/login):`,
@@ -21385,16 +21836,16 @@ function outcome(input) {
 		boxActions,
 		nextActions: [...verifyActions, ...customizeAndPublishActions(input.cliVersion, input.selector)],
 		nextCommands: input.includeInstallCommand ? [
-			shellCommand(input.install.command),
+			shellCommand(input.installCommand),
 			shellCommand(input.devCommand),
 			planCommand
 		] : [shellCommand(input.devCommand), planCommand]
 	};
 }
-function installFailed(error, installCommand, devCommand, cwd) {
+function installFailed(error, installCommand, devCommand, shownInstall, cwd) {
 	return new ZitadelError("E_VALIDATION", `Dependency install failed: ${installCommand.display}`, {
 		hint: `Run ${installCommand.display} in ${cwd}, then start the app with ${devCommand.display}.`,
-		nextCommands: [shellCommand(installCommand.display)],
+		nextCommands: [shellCommand(shownInstall)],
 		details: {
 			command: installCommand.display,
 			cwd,
@@ -21411,6 +21862,328 @@ function errorShape(error) {
 	return { message: String(error) };
 }
 //#endregion
+//#region src/commands/setup/initial-commit.ts
+const run = promisify(execFile);
+/**
+* The subject of the commit setup makes. Conventional-commit style, like every
+* other commit this repository's tooling writes, and with no trailer of any
+* kind: the commit belongs to the developer, not to the tool that made it.
+*/
+const INITIAL_COMMIT_SUBJECT = "chore: scaffold the project with zitadel setup";
+/**
+* Paths that must never be committed, whatever `.gitignore` happens to say.
+*
+* `.zitadel/local/` holds the local admin credential and the server's data
+* directory. Only the `.gitignore` line `start` appends keeps it out, so a
+* project missing that line would otherwise commit the credential.
+*/
+function isSecretPath(path) {
+	const name = path.split("/").pop() ?? path;
+	if (path === ".zitadel/secret" || path.endsWith("/.zitadel/secret")) return true;
+	if (isLocalRuntimePath(path)) return true;
+	return name.startsWith(".env") && name !== ".env.example";
+}
+/**
+* Paths the CLI writes itself, which therefore do not count as the
+* developer's uncommitted work. Matched against a path already made relative
+* to the project directory, never the repository root: in a monorepo the two
+* differ, and comparing the wrong one refuses every subdirectory project.
+*
+* Just the two `start` leaves behind: the `.zitadel/local/` it writes and the
+* `.gitignore` line that ignores it. It runs immediately before `setup` on the
+* documented golden path, so counting those would refuse every project that
+* has ever been started. Nothing else under `.zitadel/` is exempt: a
+* connection in `.zitadel/idps/` or a policy file is the developer's, and an
+* uncommitted edit there must not be committed under setup's subject.
+*/
+function isCliOwned(path) {
+	return path === ".gitignore" || path.endsWith("/.gitignore") || isLocalRuntimePath(path);
+}
+/**
+* `.zitadel/local/` at any depth, not only at the project root: a nested app
+* inside the project directory has its own, holding its own admin credential.
+*/
+function isLocalRuntimePath(path) {
+	return /(^|\/)\.zitadel\/local(\/|$)/.test(path);
+}
+/**
+* Run git in `cwd`, returning its stdout.
+*
+* `core.quotePath=false` stops git C-quoting any path holding a non-ASCII byte
+* or a space (`"caf\303\251.txt"`). A quoted path is not the path: it matches
+* no pathspec and no suffix test, so a secret under such a name would be
+* neither recognised nor unstaged.
+*/
+async function git(cwd, args, env) {
+	const { stdout } = await run("git", [
+		"-c",
+		"core.quotePath=false",
+		...args
+	], {
+		cwd,
+		maxBuffer: 16777216,
+		...env ? { env: {
+			...process.env,
+			...env
+		} } : {}
+	});
+	return stdout;
+}
+/**
+* Whether `cwd` already sits inside a git repository.
+*
+* Only git's own "not a git repository" counts as no. Every other failure — a
+* dubious-ownership refusal, a permission error, a broken `HOME` — is raised,
+* because answering "no" to one of those would skip the clean-tree check and
+* then `git init` a second repository nested inside the first.
+*/
+async function insideRepository(cwd) {
+	try {
+		await git(cwd, ["rev-parse", "--git-dir"]);
+		return true;
+	} catch (error) {
+		const message = messageOf(error).toLowerCase();
+		if (message.includes("not a git repository") || message.includes("enoent")) return false;
+		throw error;
+	}
+}
+/**
+* Where the project sits inside its repository (`apps/web/`, or `""` at the
+* root). `git status` reports paths from the repository root whatever
+* directory it runs in, so this is what turns one into a project-relative path.
+*/
+async function projectPrefix(cwd) {
+	return (await git(cwd, ["rev-parse", "--show-prefix"])).trim();
+}
+/**
+* Whether the developer has an identity of their own for git to commit with,
+* from config or from `GIT_AUTHOR_*`/`GIT_COMMITTER_*`/`EMAIL`.
+*
+* Without one git does not fail: it guesses from the username and hostname and
+* commits anyway. `user.useConfigOnly` is what turns that guess back into an
+* error, so asking under it is the way to tell a real identity from a guessed
+* one. Nothing is passed to the commit either way — an identity this invented
+* would be a worse author than the one git derives from the machine.
+*/
+async function hasOwnIdentity(cwd) {
+	try {
+		await git(cwd, [
+			"-c",
+			"user.useConfigOnly=true",
+			"var",
+			"GIT_AUTHOR_IDENT"
+		]);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Whether git can produce any identity at all, its own guess included.
+*
+* A bare CI container has no configured identity and often no passwd entry or
+* hostname to guess from, and there git refuses to commit. Only then is an
+* identity supplied, because no commit means no `git_sha` and the next deploy
+* has nothing to diff against.
+*/
+async function canBuildIdentity(cwd) {
+	try {
+		await git(cwd, ["var", "GIT_AUTHOR_IDENT"]);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Last resort, used only where git can build no identity of its own.
+*
+* Passed as environment variables rather than `-c user.*`, because an
+* inherited `GIT_AUTHOR_NAME=` (empty, as some runners leave it) outranks
+* `-c` and git then refuses with "empty ident name". The environment beats
+* both the config and whatever was inherited.
+*/
+const FALLBACK_IDENTITY = {
+	GIT_AUTHOR_NAME: "Zitadel Setup",
+	GIT_AUTHOR_EMAIL: "setup@zitadel.local",
+	GIT_COMMITTER_NAME: "Zitadel Setup",
+	GIT_COMMITTER_EMAIL: "setup@zitadel.local"
+};
+/**
+* Everything git considers a change under the project directory, untracked
+* files included. An untracked file counts: setup stages the whole project, so
+* one left lying about would be swept into setup's commit.
+*
+* Scoped to `.` so that in a monorepo a sibling package's work-in-progress —
+* which `git add` here would never touch — does not refuse the setup.
+*/
+async function changes(cwd) {
+	const fields = (await git(cwd, [
+		"status",
+		"--porcelain",
+		"-z",
+		"--untracked-files=all",
+		"--",
+		"."
+	])).split("\0");
+	const found = [];
+	for (let index = 0; index < fields.length; index += 1) {
+		const entry = fields[index];
+		if (entry === void 0 || entry === "") continue;
+		const status = entry.slice(0, 2);
+		if (status.includes("R") || status.includes("C")) index += 1;
+		found.push({
+			path: entry.slice(3),
+			untracked: status === "??"
+		});
+	}
+	return found;
+}
+/** The paths staged in `cwd`, relative to it and never quoted. */
+async function stagedPaths(cwd, env) {
+	return (await git(cwd, [
+		"diff",
+		"--cached",
+		"-z",
+		"--name-only",
+		"--no-renames",
+		"--relative"
+	], env)).split("\0").filter((path) => path !== "");
+}
+/**
+* Refuse a project whose repository has anything uncommitted, before setup
+* writes a single file.
+*
+* Setup commits what it wrote so the first release records a real commit, and
+* the honest way to know what it wrote is that the tree was clean beforehand:
+* then everything uncommitted afterwards is setup's own work and nothing of
+* the developer's is swept in. A dirty tree makes that impossible to tell
+* apart, and committing someone's work-in-progress under setup's name is worse
+* than any diff it would buy. Checked up front rather than at commit time, so
+* a refusal costs nothing and leaves no half-made project behind.
+*/
+async function assertCleanWorktree(cwd) {
+	if (!await insideRepository(cwd)) return;
+	let dirty;
+	try {
+		const prefix = await projectPrefix(cwd);
+		dirty = (await changes(cwd)).map((change) => ({
+			...change,
+			path: change.path.startsWith(prefix) ? change.path.slice(prefix.length) : change.path
+		})).filter((change) => !isCliOwned(change.path));
+	} catch (error) {
+		throw new ZitadelError("E_CONFLICT", `Could not tell whether the git working tree is clean: ${messageOf(error)}`, { hint: "Setup commits the files it writes, and will not do that without knowing the tree started clean. Fix what git is reporting, then run setup again, or pass --no-git to set up without touching version control." });
+	}
+	if (dirty.length === 0) return;
+	const modified = dirty.filter((change) => !change.untracked).map((change) => change.path);
+	const untracked = dirty.filter((change) => change.untracked).map((change) => change.path);
+	const parts = [modified.length > 0 ? `${modified.length} uncommitted change${plural(modified)}` : void 0, untracked.length > 0 ? `${untracked.length} untracked file${plural(untracked)}` : void 0].filter((part) => part !== void 0);
+	throw new ZitadelError("E_CONFLICT", `The git working tree has ${parts.join(" and ")}`, {
+		hint: "Setup commits the project directory so the first release records a commit, and it will not do that while there is work it did not write, which would be committed under setup's name. Run `git status` to see them, commit or stash them, then run setup again. If you have just scaffolded the app yourself, committing it first is the expected step. To set up without touching version control at all, pass --no-git.",
+		details: {
+			modified,
+			untracked
+		}
+	});
+}
+/** `s` unless the list holds exactly one entry. */
+function plural(list) {
+	return list.length === 1 ? "" : "s";
+}
+/**
+* Give the scaffolded project a git repository with one commit, so the release
+* setup builds next records a real `git_sha` and the deploy after it can diff
+* against this commit instead of reporting that no diff is available.
+*
+* A repository is created only when there is none; an existing one is used as
+* it stands, never nested inside. Either way the commit covers the project
+* directory, which is safe because {@link assertCleanWorktree} has already
+* refused a repository with anything uncommitted: everything there is to commit
+* by this point is what setup itself wrote.
+*
+* Nothing here prompts, so it behaves the same interactively and in CI, and no
+* failure is fatal: the worst case is the first release carrying no commit,
+* which is what happened before this existed.
+*/
+async function ensureInitialCommit(cwd) {
+	let scratch;
+	try {
+		const existing = await insideRepository(cwd);
+		if (!existing) await git(cwd, ["init", "--quiet"]);
+		scratch = await mkdtemp(join(tmpdir(), "zitadel-commit-"));
+		const index = { GIT_INDEX_FILE: join(scratch, "index") };
+		if (existing) await git(cwd, ["read-tree", "HEAD"], index).catch(() => void 0);
+		await git(cwd, [
+			"add",
+			"--all",
+			"--",
+			"."
+		], index);
+		const paths = await stagedPaths(cwd, index);
+		const secrets = paths.filter(isSecretPath);
+		if (secrets.length > 0) await git(cwd, [
+			"reset",
+			"--quiet",
+			"--",
+			...secrets
+		], index);
+		const stillStaged = (await stagedPaths(cwd, index)).filter(isSecretPath);
+		if (stillStaged.length > 0) return {
+			kind: "unavailable",
+			reason: `${stillStaged[0]} could not be kept out of the commit, so nothing was committed`
+		};
+		if (paths.length === secrets.length) return {
+			kind: "unavailable",
+			reason: "there was nothing to commit"
+		};
+		const guessedIdentity = !await hasOwnIdentity(cwd);
+		const invented = !await canBuildIdentity(cwd);
+		await git(cwd, [
+			"-c",
+			"commit.gpgsign=false",
+			"commit",
+			"--quiet",
+			"--no-verify",
+			`--message=${INITIAL_COMMIT_SUBJECT}`
+		], {
+			...index,
+			...invented ? FALLBACK_IDENTITY : {}
+		});
+		const sha = await headSha(cwd);
+		if (sha === null) return {
+			kind: "unavailable",
+			reason: "the commit left no HEAD to record"
+		};
+		await git(cwd, [
+			"reset",
+			"--quiet",
+			"--",
+			"."
+		]).catch(() => void 0);
+		return {
+			kind: existing ? "committed" : "created",
+			sha,
+			guessedIdentity,
+			invented
+		};
+	} catch (error) {
+		return {
+			kind: "unavailable",
+			reason: messageOf(error)
+		};
+	} finally {
+		if (scratch) await rm(scratch, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/** git's own stderr where it has one, so the warning names the real cause. */
+function messageOf(error) {
+	const stderr = typeof error === "object" && error !== null ? error.stderr : void 0;
+	if (typeof stderr === "string" && stderr.trim() !== "") return stderr.trim().split("\n")[0] ?? stderr.trim();
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
 //#region src/commands/setup/move-dev-port.ts
 /**
 * Moves an app setup already patched to another dev port, in one step: the
@@ -21588,27 +22361,28 @@ var FrameworkConfirmPrompt = class {
 var PasswordPolicyPrompt = class {
 	async ask(answers, ctx) {
 		if (ctx.passwordMinLengthFromFlag) return answers;
+		const options = [
+			{
+				value: RECOMMENDED_PASSWORD_MIN_LENGTH,
+				label: `${RECOMMENDED_PASSWORD_MIN_LENGTH} characters — recommended`,
+				hint: "NIST minimum for password-only sign-in"
+			},
+			{
+				value: 8,
+				label: "8 characters",
+				hint: "NIST minimum with a second factor"
+			},
+			{
+				value: null,
+				label: "No minimum"
+			}
+		];
 		const passwordMinLength = await ctx.input({
 			kind: "select",
 			name: "minimum password length",
 			message: "Which minimum length should passwords have? You can change it later.",
-			initialValue: 15,
-			options: [
-				{
-					value: 15,
-					label: `15 characters — recommended`,
-					hint: "NIST minimum for password-only sign-in"
-				},
-				{
-					value: 8,
-					label: "8 characters",
-					hint: "NIST minimum with a second factor"
-				},
-				{
-					value: null,
-					label: "No minimum"
-				}
-			]
+			initialValue: RECOMMENDED_PASSWORD_MIN_LENGTH,
+			options
 		});
 		return {
 			...answers,
@@ -22146,7 +22920,7 @@ function signInSummary(answers) {
 	return [
 		answers.preset === "passkey-first" ? "Sign-in starts with a passkey, with email and password as the fallback." : "Sign-in starts with email and password.",
 		"Password and passkey are enabled in the user schema.",
-		answers.passwordMinLength === null ? "Passwords have no minimum length." : `Passwords need at least ${answers.passwordMinLength ?? 15} characters.`,
+		answers.passwordMinLength === null ? "Passwords have no minimum length." : `Passwords need at least ${answers.passwordMinLength ?? RECOMMENDED_PASSWORD_MIN_LENGTH} characters.`,
 		providers.length === 0 ? "No external providers will be added." : `External providers: ${providers.join(", ")}.`
 	].join("\n");
 }
@@ -22180,7 +22954,7 @@ const RENDERER_FLAG_DESCRIPTION = UNAVAILABLE_RENDERER_IDS.length === 0 ? "Rende
 */
 function recoverySelector(cwd) {
 	return environmentSelectorSuffix({
-		envFile: ".env.development.local",
+		envFile: projectEnvFile(cwd, ".env.development.local"),
 		cwd
 	});
 }
@@ -22190,7 +22964,7 @@ function recoverySelector(cwd) {
 */
 function localRecoverySelector(cwd) {
 	return environmentSelectorSuffix({
-		envFile: ".env.development.local",
+		envFile: projectEnvFile(cwd, ".env.development.local"),
 		server: "local",
 		cwd
 	});
@@ -22228,6 +23002,11 @@ var Setup = class Setup extends Promptable(BaseCommand) {
 		}),
 		"dev-port": Flags.integer({ description: "Dev-server port; also the issuer origin registered with Zitadel. Defaults to the detected port. Use distinct ports to run several scaffolded apps side by side. In an app already set up, moves it to this port: the dev script, ZITADEL_ISSUER and the allowed origin." }),
 		"skip-install": Flags.boolean({ description: "Do not install dependencies after setup updates package.json." }),
+		git: Flags.boolean({
+			allowNo: true,
+			default: true,
+			description: "Commit the project setup writes, initialising a repository first when there is none, so a release records the commit it was built from. Refuses a repository that already has uncommitted work. Use --no-git to leave version control alone."
+		}),
 		preset: Flags.string({
 			description: "Sign-in preset for the scaffolded schema and login flow (default: password-first).",
 			options: [...SETUP_PRESETS]
@@ -22262,6 +23041,7 @@ var Setup = class Setup extends Promptable(BaseCommand) {
 			throw localSetupHint(error, retryOptionsFromFlags(flags), this.config.version);
 		}
 		const { cwd, nonInteractive, dryRun, force } = this.meta;
+		await assertDirectoryOrMissing(cwd);
 		if (await hasZitadelConfig(cwd)) {
 			if (flags["dev-port"] !== void 0) return this.moveToDevPort(cwd, assertDevPort(flags["dev-port"]), dryRun);
 			return this.emit({
@@ -22270,6 +23050,7 @@ var Setup = class Setup extends Promptable(BaseCommand) {
 			});
 		}
 		if (await hasZitadelSecret(cwd)) throw new ZitadelError("E_CONFLICT", ".zitadel/secret exists without zitadel.json", { hint: "Move the secret aside or restore zitadel.json before running setup." });
+		if (flags.git !== false) await assertCleanWorktree(cwd);
 		await assertLocalServerVersion(cwd, this.meta.source, retryOptionsFromFlags(flags), this.config.version);
 		const wizardInput = (question) => input(question, {
 			interactive: !nonInteractive,
@@ -22539,6 +23320,7 @@ var Setup = class Setup extends Promptable(BaseCommand) {
 		const installOutcome = await installDependenciesForSetup({
 			cliVersion: this.meta.cliVersion,
 			cwd,
+			...flags.cwd === void 0 ? {} : { cwdFlag: flags.cwd },
 			depsAdded: result.depsAdded,
 			dryRun,
 			env: this.meta.env,
@@ -22552,6 +23334,7 @@ var Setup = class Setup extends Promptable(BaseCommand) {
 			step: "dependencies_installed",
 			package_manager: installOutcome.install.package_manager
 		});
+		const commit = await this.makeInitialCommit(cwd, dryRun, flags.git !== false);
 		const writtenRel = allFilesWritten.map((file) => relativeDisplayPath(cwd, file));
 		let ownedByLocalAdmin;
 		const isLocal = serverKind.value(answers.server) === "local";
@@ -22593,7 +23376,7 @@ var Setup = class Setup extends Promptable(BaseCommand) {
 			boxActions: [],
 			commands: []
 		};
-		const consoleCommand = unscopedCommand("console", this.meta.cliVersion);
+		const consoleCommand = this.suggestUnscoped("console");
 		const consoleStep = ownedByLocalAdmin ? {
 			actions: [`Manage the project in the local console as ${ownedByLocalAdmin.email}: ${consoleCommand}`],
 			boxActions: [{
@@ -22660,6 +23443,10 @@ var Setup = class Setup extends Promptable(BaseCommand) {
 				})),
 				files_skipped: result.filesSkipped.map((file) => relativeDisplayPath(cwd, file)),
 				install: installOutcome.install,
+				git: {
+					initialized: commit.kind === "created",
+					commit: commit.kind === "created" || commit.kind === "committed" ? commit.sha : null
+				},
 				sso: answers.sso.map((answer) => {
 					const slug = providerOf(answer.selection).slug;
 					const outcome = ssoOutcomes.get(slug);
@@ -22707,6 +23494,26 @@ var Setup = class Setup extends Promptable(BaseCommand) {
 		});
 	}
 	/**
+	* Put the scaffolded project under version control, unless it already is or
+	* `--no-git` said not to. Narrated but never fatal: without the commit the
+	* first release simply records no provenance, which is what setup did before.
+	*/
+	async makeInitialCommit(cwd, dryRun, enabled) {
+		if (!enabled) return { kind: "skipped" };
+		if (dryRun) {
+			consola.info("Would initialise a git repository and commit the scaffolded project (dry run)");
+			return { kind: "skipped" };
+		}
+		const outcome = await ensureInitialCommit(cwd);
+		if (outcome.kind === "created" || outcome.kind === "committed") {
+			consola.success(`Committed the project as ${outcome.sha.slice(0, 7)}`);
+			if (outcome.invented) reportWarning("git could build no author identity on this machine, so the commit was made as Zitadel Setup <setup@zitadel.local>. Set user.name and user.email, then run `git commit --amend --reset-author` to put your own name on it.");
+			else if (outcome.guessedIdentity) reportWarning("This machine has no git user.name/user.email, so git guessed the author from your username and hostname. Set your identity and run `git commit --amend --reset-author` to put your own name on the commit.");
+		}
+		if (outcome.kind === "unavailable") reportWarning(`Could not commit the scaffolded project (${outcome.reason}); the first release records no commit, so the next deploy cannot show a diff.`);
+		return outcome;
+	}
+	/**
 	* `setup --dev-port <n>` on an app setup already patched: moves the app to
 	* the new port (see {@link moveDevPort}) instead of skipping the directory.
 	*/
@@ -23380,7 +24187,7 @@ var Start = class Start extends BaseCommand {
 					api: serverUrl,
 					console: `${serverUrl}/ui/console/`
 				},
-				...nextCommandsData([unscopedCommand("start", this.meta.cliVersion)])
+				...nextCommandsData([this.suggestUnscoped("start")])
 			}
 		});
 		await ensureLocalState(this.meta.cwd);
@@ -23406,7 +24213,7 @@ var Start = class Start extends BaseCommand {
 		};
 		return this.emit({
 			status: "ok",
-			data: readyData(runtime, alreadyRunning, this.meta.cliVersion)
+			data: readyData(runtime, alreadyRunning, this.meta.cliVersion, this.suggestUnscoped("setup --server local"))
 		});
 	}
 };
@@ -23420,7 +24227,7 @@ function platformBootstrapEnabled(env) {
 	const pinned = env.NEXTGEN_PLATFORM_PROJECT_ID;
 	return !pinned || pinned === "proj_platform";
 }
-function readyData(metadata, alreadyRunning, cliVersion) {
+function readyData(metadata, alreadyRunning, cliVersion, setupCommand) {
 	return {
 		title: alreadyRunning ? "Local Zitadel server is already running." : "Local Zitadel server is ready.",
 		runtime: {
@@ -23448,7 +24255,7 @@ function readyData(metadata, alreadyRunning, cliVersion) {
 			"Setup asks for a framework and sign-in method, creates or updates your app, and installs its dependencies.",
 			serverLogAction(cliVersion)
 		],
-		...nextCommandsData([unscopedCommand("setup --server local", cliVersion)])
+		...nextCommandsData([setupCommand])
 	};
 }
 function validatePort(port) {
@@ -24156,6 +24963,7 @@ const COMMANDS = {
 	"origin:add": OriginAdd,
 	"origin:list": OriginList,
 	"origin:rm": OriginRm,
+	"policies:test": PoliciesTest,
 	"preview:list": PreviewList,
 	"preview:rm": PreviewRm,
 	"release:create": ReleaseCreate,