@zitadel/cli 0.1.0-alpha.1 → 0.1.0-alpha.10

package/dist/commands/setup.mjs

@@ -1,14 +1,180 @@
-import { T as ZitadelError, r as DEFAULT_SERVER, t as BaseCommand } from "../oclif-DSPO9Sck.mjs";
-import { n as RENDERER_IDS, r as issuerFromPort, t as createOrca } from "../orca-DOxshV9n.mjs";
-import { n as hasZitadelSecret, t as hasZitadelConfig } from "../project-Dwb9WVAT.mjs";
-import { Flags } from "@oclif/core";
+import { D as toZitadelError, E as ZitadelError, b as publicCliCommand, n as DEFAULT_SERVER, t as BaseCommand } from "../oclif-B7lBzh3R.mjs";
+import { i as issuerFromPort, n as inspectScaffoldTarget, r as RENDERER_IDS, t as createOrca } from "../orca-BoTFU8SI.mjs";
+import { n as hasZitadelSecret, t as hasZitadelConfig } from "../project-Cd0L3PtM.mjs";
+import { t as listListeningPorts } from "../ports-B09RjuHx.mjs";
 import { cancel, confirm, intro, isCancel, outro, select, spinner, text } from "@clack/prompts";
+import { Flags } from "@oclif/core";
+import { createZitadelClient } from "@zitadel/api/client";
 import { consola as consola$1 } from "consola";
-import { readFile, stat } from "node:fs/promises";
 import { basename, join } from "node:path";
-import { execFile } from "node:child_process";
-import { createZitadelClient } from "@zitadel/api/client";
+import { readFile, stat } from "node:fs/promises";
+import { spawn } from "node:child_process";
 import pc from "picocolors";
+//#region src/lib/package-manager.ts
+async function detectPackageManager(cwd) {
+	const declared = await packageManagerFromManifest(cwd);
+	if (declared) return declared;
+	if (await exists(join(cwd, "pnpm-lock.yaml"))) return "pnpm";
+	if (await exists(join(cwd, "yarn.lock"))) return "yarn";
+	if (await exists(join(cwd, "bun.lock"))) return "bun";
+	if (await exists(join(cwd, "bun.lockb"))) return "bun";
+	if (await exists(join(cwd, "package-lock.json"))) return "npm";
+	return "npm";
+}
+function installCommandFor(packageManager) {
+	return command(packageManager, ["install"]);
+}
+function devCommandFor(packageManager) {
+	switch (packageManager) {
+		case "npm": return command("npm", ["run", "dev"]);
+		case "pnpm": return command("pnpm", ["dev"]);
+		case "yarn": return command("yarn", ["dev"]);
+		case "bun": return command("bun", ["run", "dev"]);
+	}
+}
+async function runPackageCommand(packageCommand, options) {
+	await new Promise((resolve, reject) => {
+		const child = spawn(packageCommand.command, packageCommand.args, {
+			cwd: options.cwd,
+			env: options.env ?? process.env,
+			stdio: options.redirectStdoutToStderr ? [
+				"ignore",
+				"pipe",
+				"pipe"
+			] : "inherit"
+		});
+		if (options.redirectStdoutToStderr) {
+			child.stdout?.on("data", (chunk) => process.stderr.write(chunk));
+			child.stderr?.on("data", (chunk) => process.stderr.write(chunk));
+		}
+		child.on("error", reject);
+		child.on("close", (code, signal) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			const detail = signal ? `signal ${signal}` : `exit ${String(code ?? 1)}`;
+			const error = /* @__PURE__ */ new Error(`${packageCommand.display} failed with ${detail}`);
+			Object.assign(error, {
+				code: code ?? 1,
+				signal
+			});
+			reject(error);
+		});
+	});
+}
+function command(packageManager, args) {
+	return {
+		command: packageManager,
+		args,
+		display: [packageManager, ...args].join(" ")
+	};
+}
+async function packageManagerFromManifest(cwd) {
+	try {
+		const raw = await readFile(join(cwd, "package.json"), "utf8");
+		const parsed = JSON.parse(raw);
+		return typeof parsed.packageManager === "string" ? packageManagerFromString(parsed.packageManager) : void 0;
+	} catch {
+		return;
+	}
+}
+function packageManagerFromString(value) {
+	const name = value.split("@")[0];
+	return name === "npm" || name === "pnpm" || name === "yarn" || name === "bun" ? name : void 0;
+}
+async function exists(path) {
+	try {
+		await stat(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/commands/setup/install.ts
+async function installDependenciesForSetup(input) {
+	const packageManager = await detectPackageManager(input.cwd);
+	const installCommand = installCommandFor(packageManager);
+	const devCommand = devCommandFor(packageManager);
+	if (!(input.scaffoldedFramework || input.depsAdded.length > 0)) return outcome({
+		install: {
+			status: "not-needed",
+			package_manager: packageManager,
+			command: installCommand.display,
+			reason: "no-dependency-changes"
+		},
+		devCommand: devCommand.display,
+		issuer: input.issuer,
+		includeInstallCommand: false
+	});
+	if (input.dryRun || input.skipInstall) return outcome({
+		install: {
+			status: "skipped",
+			package_manager: packageManager,
+			command: installCommand.display,
+			reason: input.dryRun ? "dry-run" : "skip-install"
+		},
+		devCommand: devCommand.display,
+		issuer: input.issuer,
+		includeInstallCommand: true
+	});
+	consola$1.start(`Installing dependencies with ${installCommand.display}`);
+	try {
+		await (input.run ?? runPackageCommand)(installCommand, {
+			cwd: input.cwd,
+			env: input.env,
+			redirectStdoutToStderr: input.json
+		});
+	} catch (error) {
+		throw installFailed(error, installCommand, devCommand, input.cwd);
+	}
+	consola$1.success("Installed dependencies");
+	return outcome({
+		install: {
+			status: "completed",
+			package_manager: packageManager,
+			command: installCommand.display
+		},
+		devCommand: devCommand.display,
+		issuer: input.issuer,
+		includeInstallCommand: false
+	});
+}
+function outcome(input) {
+	const startAction = `Start your project: ${input.devCommand} (then open ${input.issuer})`;
+	const verifyAction = "Verify auth in the browser: register a user, log out, log in again with the same user, and confirm /profile shows Signed in.";
+	return {
+		install: input.install,
+		devCommand: input.devCommand,
+		nextActions: input.includeInstallCommand ? [
+			`Install dependencies: ${input.install.command}`,
+			startAction,
+			verifyAction
+		] : [startAction, verifyAction],
+		nextCommands: input.includeInstallCommand ? [input.install.command, input.devCommand] : [input.devCommand]
+	};
+}
+function installFailed(error, installCommand, devCommand, 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: [installCommand.display],
+		details: {
+			command: installCommand.display,
+			cwd,
+			original: errorShape(error)
+		}
+	});
+}
+function errorShape(error) {
+	if (error instanceof Error) return {
+		name: error.name,
+		message: error.message,
+		code: error.code
+	};
+	return { message: String(error) };
+}
+//#endregion
 //#region src/commands/setup/prompts/cancel.ts
 /**
 * Converts a clack cancellation (Ctrl-C) into a thrown `E_VALIDATION` rather
@@ -28,7 +194,8 @@ function bail(value) {
 * becomes the issuer URL (`http://localhost:<port>`) via `issuerFromPort`.
 */
 var DevPortPrompt = class {
-	async ask(answers, _ctx) {
+	async ask(answers, ctx) {
+		if (ctx.devPortFromFlag) return answers;
 		const value = await text({
 			message: "Dev server port",
 			placeholder: String(answers.devPort),
@@ -64,79 +231,6 @@ var FrameworkConfirmPrompt = class {
 	}
 };
 //#endregion
-//#region src/lib/prober/ports.ts
-/**
-* Enumerate TCP ports currently in LISTEN state on the loopback interface
-* (`127.0.0.1`, `::1`, or the wildcard `*`). Spawns `lsof -iTCP -sTCP:LISTEN
-* -P -n -F n` and parses its machine-readable output. Returns the unique,
-* numerically-sorted list of ports.
-*
-* Never throws. Returns `[]` whenever lsof is unavailable (e.g. Windows,
-* unusual PATH), the spawn errors, exits non-zero, or the call exceeds
-* `timeoutMs` (default 1000ms). The caller treats an empty list the same as
-* "no listeners worth probing."
-*/
-async function listListeningPorts(opts) {
-	const timeoutMs = opts?.timeoutMs ?? 1e3;
-	try {
-		return parseLsofPorts(await runLsof(timeoutMs));
-	} catch {
-		return [];
-	}
-}
-/**
-* Spawn `lsof` with the canned argv and resolve to its stdout. Hand-rolled
-* rather than `util.promisify(execFile)` because the latter resolves with a
-* `{stdout, stderr}` object via its custom-promisify symbol — a heavier shape
-* to mock and worse to read at the call site, where we only ever want stdout.
-*/
-function runLsof(timeoutMs) {
-	return new Promise((resolve, reject) => {
-		execFile("lsof", [
-			"-iTCP",
-			"-sTCP:LISTEN",
-			"-P",
-			"-n",
-			"-F",
-			"n"
-		], {
-			timeout: timeoutMs,
-			encoding: "utf8"
-		}, (err, stdout) => {
-			if (err) {
-				reject(err);
-				return;
-			}
-			resolve(stdout);
-		});
-	});
-}
-/**
-* Parse the `n` records emitted by `lsof -F n`. Each record is a single line
-* `n<address>` where `<address>` ends in `:<port>` (e.g. `n*:8080`,
-* `n127.0.0.1:3000`, `n[::1]:5050`). Only loopback/wildcard hosts are kept;
-* external interface bindings are ignored.
-*/
-function parseLsofPorts(stdout) {
-	const ports = /* @__PURE__ */ new Set();
-	for (const line of stdout.split(/\r?\n/)) {
-		if (!line.startsWith("n")) continue;
-		const address = line.slice(1);
-		const colon = address.lastIndexOf(":");
-		if (colon < 0) continue;
-		const host = address.slice(0, colon);
-		const portStr = address.slice(colon + 1);
-		if (!isLoopback(host)) continue;
-		const port = Number.parseInt(portStr, 10);
-		if (Number.isFinite(port) && port > 0 && port < 65536) ports.add(port);
-	}
-	return [...ports].sort((a, b) => a - b);
-}
-/** Recognised loopback host strings as emitted by `lsof -F n`. */
-function isLoopback(host) {
-	return host === "*" || host === "127.0.0.1" || host === "[::1]" || host === "::1";
-}
-//#endregion
 //#region src/lib/prober/http.ts
 /**
 * Fetch `url` with a per-call timeout and pass the resulting `Response` to
@@ -346,9 +440,8 @@ const url = (s) => pc.cyan(s);
 const id = (s) => pc.yellow(s);
 /**
 * Reads the project root to identify the framework version, TS presence,
-* and which package manager the user runs. Returns the worst-case
-* (`"unknown"` PM, no version) on any error so summary rendering can
-* always proceed.
+* and which package manager the user runs. Returns safe defaults (npm
+* fallback, no version) on any error so summary rendering can always proceed.
 */
 async function detectProjectFacts(cwd, frameworkId) {
 	const facts = {
@@ -371,16 +464,9 @@ function formatFrameworkLine(facts) {
 	const pretty = prettyFramework(facts.framework);
 	segments.push(facts.frameworkVersion ? `${pretty} ${facts.frameworkVersion}` : pretty);
 	if (facts.typescript) segments.push("TypeScript");
-	if (facts.packageManager !== "unknown") segments.push(facts.packageManager);
+	segments.push(facts.packageManager);
 	return segments.join(` ${pc.dim("·")} `);
 }
-async function detectPackageManager(cwd) {
-	if (await fileExists(join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-	if (await fileExists(join(cwd, "yarn.lock"))) return "yarn";
-	if (await fileExists(join(cwd, "bun.lockb"))) return "bun";
-	if (await fileExists(join(cwd, "package-lock.json"))) return "npm";
-	return "unknown";
-}
 async function fileExists(p) {
 	try {
 		await stat(p);
@@ -435,7 +521,7 @@ const FRAMEWORK_OPTIONS = createOrca().availableFrameworks().map((framework) =>
 */
 var Setup = class Setup extends BaseCommand {
 	static description = "Create a Zitadel project and scaffold local auth.";
-	static examples = ["<%= config.bin %> setup --framework next"];
+	static examples = ["<%= config.bin %> setup --framework next", "<%= config.bin %> setup --framework react --dev-port 3000"];
 	static flags = {
 		framework: Flags.string({
 			description: "Framework to target.",
@@ -444,11 +530,17 @@ var Setup = class Setup extends BaseCommand {
 		renderer: Flags.string({
 			description: "Renderer (default: react).",
 			options: [...RENDERER_IDS]
-		})
+		}),
+		"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." }),
+		"skip-install": Flags.boolean({ description: "Do not install dependencies after setup updates package.json." })
 	};
 	async run() {
 		const { flags } = await this.parse(Setup);
-		await this.toMeta(flags);
+		try {
+			await this.toMeta(flags);
+		} catch (error) {
+			throw localSetupHint(error, flags.framework, this.config.version);
+		}
 		const { cwd, nonInteractive, dryRun, force } = this.meta;
 		if (await hasZitadelConfig(cwd)) return this.emit({
 			status: "skipped",
@@ -463,13 +555,24 @@ var Setup = class Setup extends BaseCommand {
 			framework = await orca.detect(cwd, flags.framework);
 			consola$1.success(`Detected ${framework.id}${framework.devPort ? ` (dev port ${framework.devPort})` : ""}`);
 		} catch (error) {
-			if (error instanceof ZitadelError && error.code === "E_FRAMEWORK_NOT_DETECTED" && await orca.isEmpty(cwd)) {
-				consola$1.info("Empty directory — scaffolding a fresh project");
+			if (error instanceof ZitadelError && error.code === "E_FRAMEWORK_NOT_DETECTED") {
+				const target = await inspectScaffoldTarget(cwd);
+				if (!target.scaffoldable) throw frameworkDetectionWithScaffoldTarget(error, cwd, target);
+				consola$1.info("Fresh app directory — scaffolding a fresh project");
 				framework = await orca.scaffold(cwd, await resolveScaffoldFramework(flags.framework, nonInteractive, orca));
 				scaffoldedFramework = true;
 				consola$1.success(`Scaffolded ${framework.id} skeleton`);
 			} else throw error;
 		}
+		if (flags["dev-port"] !== void 0) {
+			const devPort = flags["dev-port"];
+			if (!Number.isInteger(devPort) || devPort < 1 || devPort > 65535) throw new ZitadelError("E_VALIDATION", `--dev-port must be an integer in 1..65535, got ${devPort}`);
+			framework = {
+				...framework,
+				devPort,
+				url: issuerFromPort(devPort)
+			};
+		}
 		let answers = {
 			server: this.meta.source,
 			devPort: framework.devPort
@@ -478,15 +581,21 @@ var Setup = class Setup extends BaseCommand {
 			intro("Zitadel setup");
 			const promptCtx = {
 				framework,
-				serverFlag: this.meta.serverFlag
+				serverFlag: this.meta.serverFlag,
+				devPortFromFlag: flags["dev-port"] !== void 0
 			};
 			for (const prompt of SETUP_PROMPTS) answers = await prompt.ask(answers, promptCtx);
 			outro("Configuration captured");
 		}
 		const issuer = issuerFromPort(answers.devPort);
+		framework = {
+			...framework,
+			devPort: answers.devPort,
+			url: issuer
+		};
 		consola$1.start(`Creating project on ${answers.server}${dryRun ? " (dry run)" : ""}`);
 		const unauthClient = createZitadelClient({ baseUrl: answers.server });
-		const project = dryRun ? dryRunProject() : await unauthClient.createProject({ previewOrigins: [] });
+		const project = dryRun ? dryRunProject(issuer) : await createProjectWithLocalHint(unauthClient, answers.server, this.meta.cliVersion, issuer, framework.id);
 		consola$1.success(`Created project ${project.id}`);
 		const ctx = {
 			framework,
@@ -494,7 +603,8 @@ var Setup = class Setup extends BaseCommand {
 			project,
 			issuer,
 			server: answers.server,
-			cliVersion: this.meta.cliVersion
+			cliVersion: this.meta.cliVersion,
+			scaffoldedFramework
 		};
 		consola$1.start(`Patching project files${dryRun ? " (dry run)" : ""}`);
 		const result = await orca.patcherFor(framework.id).patch(ctx, {
@@ -508,6 +618,16 @@ var Setup = class Setup extends BaseCommand {
 		}
 		for (const file of result.filesSkipped) consola$1.info(`Left ${relativeDisplay(cwd, file)} unchanged (already matches target)`);
 		consola$1.success(`Patched ${result.filesWritten.length} file${result.filesWritten.length === 1 ? "" : "s"}` + (result.filesSkipped.length > 0 ? ` (${result.filesSkipped.length} unchanged)` : ""));
+		const installOutcome = await installDependenciesForSetup({
+			cwd,
+			depsAdded: result.depsAdded,
+			dryRun,
+			env: this.meta.env,
+			issuer,
+			json: this.jsonEnabled(),
+			scaffoldedFramework,
+			skipInstall: Boolean(flags["skip-install"])
+		});
 		const writtenRel = result.filesWritten.map((file) => relativeDisplay(cwd, file));
 		if (!this.jsonEnabled()) {
 			const sections = buildSummary({
@@ -523,7 +643,7 @@ var Setup = class Setup extends BaseCommand {
 				message: [
 					renderSummary(sections),
 					"",
-					`Open your app on ${url(`${issuer}/login`)} and register your first user.`
+					installOutcome.nextActions.join("\n")
 				].join("\n"),
 				style: {
 					padding: 1,
@@ -545,12 +665,23 @@ var Setup = class Setup extends BaseCommand {
 				server: answers.server,
 				files_written: result.filesWritten.map((file) => relativeDisplay(cwd, file)),
 				files_skipped: result.filesSkipped.map((file) => relativeDisplay(cwd, file)),
-				next_actions: [`Start your project: npm install && npm run dev (then open ${issuer}/login)`],
-				next_commands: ["npm install", "npm run dev"]
+				install: installOutcome.install,
+				next_actions: installOutcome.nextActions,
+				next_commands: installOutcome.nextCommands
 			}
 		});
 	}
 };
+function frameworkDetectionWithScaffoldTarget(error, cwd, target) {
+	return new ZitadelError(error.code, "Could not detect a supported app framework, and this directory is not a fresh scaffold target", {
+		hint: `${target.reason ?? "Directory is not empty."} Run setup from an empty directory to scaffold a new app, or run setup from an existing supported app project.`,
+		details: {
+			cwd,
+			entries: target.entries,
+			reason: target.reason
+		}
+	});
+}
 /**
 * Resolves which framework to scaffold into an empty directory: the explicit
 * `--framework`, else PickFrameworkPrompt, else a hard error in non-interactive
@@ -558,19 +689,44 @@ var Setup = class Setup extends BaseCommand {
 */
 async function resolveScaffoldFramework(framework, nonInteractive, orca) {
 	if (framework) return framework;
-	if (nonInteractive) throw new ZitadelError("E_FRAMEWORK_NOT_DETECTED", "Empty directory — pass --framework", { hint: "Example: --framework next" });
+	if (nonInteractive) throw new ZitadelError("E_FRAMEWORK_NOT_DETECTED", "Empty directory — pass --framework", { hint: "Run without --json/--non-interactive to choose from a prompt, or pass --framework for scripted setup." });
 	return new PickFrameworkPrompt().ask(orca.availableFrameworks());
 }
 /** A deterministic stand-in project for `--dry-run`, so no remote call is made. */
-function dryRunProject() {
+function dryRunProject(issuer) {
 	return {
 		id: "dry-run-0000",
 		projectSecret: "sk_proj_dry_run_full",
 		previewSecret: "sk_proj_dry_run_preview",
-		previewOrigins: [],
+		previewOrigins: [issuer],
 		createdAt: "2026-04-21T14:03:11.000Z"
 	};
 }
+async function createProjectWithLocalHint(client, server, cliVersion, issuer, framework) {
+	try {
+		return await client.createProject({ previewOrigins: [issuer] });
+	} catch (error) {
+		const normalized = toZitadelError(error);
+		throw new ZitadelError(normalized.code, normalized.message, {
+			hint: `${normalized.hint ? `${normalized.hint} ` : ""}If you meant to use a local Zitadel server, start it first and retry setup with --framework ${framework} --server local.`,
+			nextCommands: [publicCliCommand("start", cliVersion), publicCliCommand(`setup --framework ${framework} --server local`, cliVersion)],
+			details: {
+				server,
+				original: normalized.details
+			}
+		});
+	}
+}
+function localSetupHint(error, framework, cliVersion) {
+	const normalized = toZitadelError(error);
+	if (normalized.code !== "E_LOCAL_SERVER_NOT_RUNNING") return error;
+	const setupCommand = framework ? `setup --framework ${framework} --server local` : "setup --server local";
+	return new ZitadelError(normalized.code, normalized.message, {
+		hint: `${normalized.hint ? `${normalized.hint} ` : ""}Start local Zitadel first, then rerun setup. After setup succeeds, follow its next_commands to start the app and verify registration, logout, and login in the browser.`,
+		nextCommands: [publicCliCommand("start", cliVersion), publicCliCommand(setupCommand, cliVersion)],
+		details: normalized.details
+	});
+}
 /** Renders an absolute path relative to `cwd` for human-readable output. */
 function relativeDisplay(cwd, path) {
 	return path.startsWith(cwd) ? path.slice(cwd.length + 1) : path;
@@ -622,10 +778,12 @@ const SENTENCE_BY_PATH = {
 	".env.example": { subject: "the .env example template" },
 	".env.local": { subject: "the local development environment variables" },
 	".zitadel/state.json": { subject: "the empty sync state file" },
+	"app/page.tsx": { subject: "the auth home page" },
 	"app/login/page.tsx": { subject: "the login page" },
 	"app/register/page.tsx": { subject: "the registration page" },
 	"app/profile/page.tsx": { subject: "the profile page" },
 	"middleware.ts": { subject: "the Next.js middleware" },
+	"proxy.ts": { subject: "the Next.js proxy" },
 	"custom-elements.d.ts": { subject: "the web-component type declarations" },
 	"package.json": { subject: "package.json with the SDK dependency" }
 };
@@ -649,9 +807,11 @@ function buildSummary(opts) {
 		secondary: path(fileNameOf(packageJsonHit))
 	});
 	for (const [label, suffix] of [
+		["Home page", "app/page.tsx"],
 		["Login page", "app/login/page.tsx"],
 		["Register page", "app/register/page.tsx"],
 		["Profile page", "app/profile/page.tsx"],
+		["Request proxy", "proxy.ts"],
 		["Middleware", "middleware.ts"],
 		["Env vars", ".env.local"]
 	]) {