@zitadel/cli 0.0.0

package/dist/project-C3pSfbao.mjs

@@ -0,0 +1,588 @@
+import { Command, Flags } from "@oclif/core";
+import consola from "consola";
+import { readFile, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { ApiError } from "@zitadel/api/runtime/fetch";
+import { stringify } from "safe-stable-stringify";
+//#region src/lib/errors.ts
+/**
+* Maps each {@link ZitadelErrorCode} to the process exit code the CLI
+* returns. The table is the single source of truth for exit semantics so
+* scripts and CI can branch on stable, documented numbers.
+*/
+const EXIT_CODES = {
+	E_ALREADY_INIT: 0,
+	E_FRAMEWORK_NOT_DETECTED: 3,
+	E_UNSUPPORTED_PROJECT_SHAPE: 3,
+	E_NETWORK: 4,
+	E_AUTH: 1,
+	E_CONFLICT: 5,
+	E_VALIDATION: 3,
+	E_NOT_IMPLEMENTED: 2
+};
+/**
+* The CLI's single error type. Carries a {@link ZitadelErrorCode} so the
+* top-level handler can derive an exit code and structured output without
+* pattern-matching on messages. Throwing this anywhere guarantees the user
+* gets a categorised, hint-bearing failure instead of a raw stack trace.
+*/
+var ZitadelError = class extends Error {
+	code;
+	hint;
+	nextCommands;
+	details;
+	constructor(code, message, opts = {}) {
+		super(message);
+		this.name = "ZitadelError";
+		this.code = code;
+		this.hint = opts.hint;
+		this.nextCommands = opts.nextCommands;
+		this.details = opts.details;
+	}
+	get exitCode() {
+		return EXIT_CODES[this.code] ?? 1;
+	}
+};
+/**
+* Normalises any thrown value into a {@link ZitadelError}. Inspection is
+* ordered most-specific-first (already-normalised, then errno/filesystem,
+* network, Zod-like, generic `Error`, then a catch-all) so the most
+* actionable category and hint win. This is the boundary that lets the rest
+* of the CLI `throw` plain errors yet still produce consistent, categorised
+* output. The original error shape is preserved under `details` for
+* debugging without leaking it into the user-facing message.
+*/
+function toZitadelError(error) {
+	if (error instanceof ZitadelError) return error;
+	if (error instanceof ApiError) return new ZitadelError(error.status === 401 || error.status === 403 ? "E_AUTH" : error.status >= 500 ? "E_NETWORK" : "E_VALIDATION", error.message, { details: {
+		status: error.status,
+		url: error.url,
+		body: error.body
+	} });
+	if (isErrnoException(error)) {
+		const details = { original: pickErrorShape(error) };
+		if (error.code === "EACCES" || error.code === "EPERM") return new ZitadelError("E_AUTH", `Permission denied: ${error.message}`, {
+			hint: "Check file permissions or run with the right user.",
+			details
+		});
+		if (error.code === "EEXIST") return new ZitadelError("E_CONFLICT", error.message, {
+			hint: "A file already exists. Use --force to overwrite or remove it first.",
+			details
+		});
+		if (error.code === "ENOENT") return new ZitadelError("E_VALIDATION", error.message, {
+			hint: "A required file or directory is missing.",
+			details
+		});
+	}
+	if (isNetworkError(error)) return new ZitadelError("E_NETWORK", errorMessage(error), {
+		hint: "Check your connection, ZITADEL_API_BASE, or the configured server URL.",
+		details: { original: pickErrorShape(error) }
+	});
+	if (isZodLikeError(error)) return new ZitadelError("E_VALIDATION", errorMessage(error), { details: { issues: error.issues } });
+	if (error instanceof Error) return new ZitadelError("E_VALIDATION", error.message, { details: { original: pickErrorShape(error) } });
+	return new ZitadelError("E_VALIDATION", "Unknown error", { details: error });
+}
+function isErrnoException(error) {
+	return error instanceof Error && typeof error.code === "string";
+}
+function isNetworkError(error) {
+	if (!(error instanceof Error)) return false;
+	if (error.name === "TypeError" && /fetch failed|network|ECONNREFUSED|ENOTFOUND/i.test(error.message)) return true;
+	const cause = error.cause;
+	if (cause && typeof cause === "object" && "code" in cause) {
+		const code = String(cause.code);
+		return /^(ECONNREFUSED|ECONNRESET|ENOTFOUND|ETIMEDOUT|EAI_AGAIN|UND_ERR)/i.test(code);
+	}
+	return false;
+}
+function isZodLikeError(error) {
+	return typeof error === "object" && error !== null && "issues" in error && Array.isArray(error.issues);
+}
+function errorMessage(error) {
+	if (error instanceof Error) return error.message;
+	if (typeof error === "string") return error;
+	return String(error);
+}
+function pickErrorShape(error) {
+	return {
+		name: error.name,
+		message: error.message,
+		code: error.code
+	};
+}
+//#endregion
+//#region src/lib/json.ts
+/**
+* Serialise a value to pretty-printed JSON with object keys sorted at every
+* depth. Determinism is the point: managed files written by the CLI must be
+* byte-stable across runs so diffs stay clean and content hashes don't churn
+* when only key ordering would otherwise differ. Delegates the deterministic
+* sort to `safe-stable-stringify`, matching `JSON.stringify(value, null, 2)`
+* formatting. The `?? "null"` only applies to `undefined`/function inputs,
+* which the CLI never serialises.
+*/
+function stableStringify(value) {
+	return stringify(value, null, 2) ?? "null";
+}
+/**
+* Parse `contents` as JSON and assert the root is a plain object (not an
+* array or scalar). The CLI's config and secret files are always objects, so
+* this guards callers from the `JSON.parse` return type of `any` and produces
+* a `path`-qualified error message pointing at the offending file.
+*/
+function parseJsonObject(contents, path) {
+	const value = JSON.parse(contents);
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${path} must contain a JSON object`);
+	return value;
+}
+/**
+* Narrows an unknown value to a plain (non-array, non-null) object. Shared by
+* the commands and the file-writer that walk parsed JSON, so the predicate
+* isn't reimplemented per call site.
+*/
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+//#region src/lib/server.ts
+/**
+* Server URL used when nothing else resolves. Also surfaced in hints and
+* the interactive setup prompt as the suggested value, so it is exported
+* rather than kept private.
+*/
+const DEFAULT_SERVER = "https://api.zitadel.cloud";
+/**
+* Resolves which server the CLI should target, applying a fixed
+* precedence: explicit `--server` flag, then `ZITADEL_API_BASE`, then the
+* selected environment block in `zitadel.json`, then the config's
+* top-level `server`, falling back to {@link DEFAULT_SERVER}. Every
+* candidate is validated to a normalised origin; an invalid URL throws a
+* `ZitadelError` rather than silently falling through.
+*/
+async function resolveServer(input) {
+	if (input.serverFlag) return validate({
+		value: input.serverFlag,
+		origin: "flag"
+	});
+	const envValue = input.env.ZITADEL_API_BASE;
+	if (envValue) return validate({
+		value: envValue,
+		origin: "env"
+	});
+	const config = await readConfig(input.cwd);
+	if (config) {
+		const envBranch = readEnvServer(config, input.environment);
+		if (envBranch) return validate({
+			value: envBranch,
+			origin: "config-env"
+		});
+		if (typeof config.server === "string") return validate({
+			value: config.server,
+			origin: "config-top"
+		});
+	}
+	return {
+		value: DEFAULT_SERVER,
+		origin: "default"
+	};
+}
+function validate(resolved) {
+	try {
+		const url = new URL(resolved.value);
+		if (url.protocol !== "https:" && url.protocol !== "http:") throw new ZitadelError("E_VALIDATION", `Server URL must use http(s): ${resolved.value}`, { hint: `Set "server" in zitadel.json to a URL like ${DEFAULT_SERVER}.` });
+		return {
+			value: url.origin,
+			origin: resolved.origin
+		};
+	} catch (error) {
+		if (error instanceof ZitadelError) throw error;
+		throw new ZitadelError("E_VALIDATION", `Invalid server "${resolved.value}"`, {
+			hint: `Use a URL like ${DEFAULT_SERVER}.`,
+			details: { origin: resolved.origin }
+		});
+	}
+}
+async function readConfig(cwd) {
+	try {
+		return parseJsonObject(await readFile(join(cwd, "zitadel.json"), "utf8"), "zitadel.json");
+	} catch (error) {
+		if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") return;
+		throw error;
+	}
+}
+function readEnvServer(config, environment) {
+	if (!environment) return;
+	const envs = config.environments;
+	if (!isObject(envs)) return;
+	const branch = envs[environment];
+	if (!isObject(branch)) return;
+	return typeof branch.server === "string" ? branch.server : void 0;
+}
+//#endregion
+//#region src/lib/paths.ts
+/**
+* Resolve the working directory the CLI should operate against, defaulting to
+* the process CWD when no `--cwd` override is given. Always returns an
+* absolute path so downstream `join`/`readFile` calls are unaffected by later
+* `process.chdir` or relative-path ambiguity.
+*/
+function resolveCwd(cwd) {
+	return resolve(cwd ?? process.cwd());
+}
+/**
+* Sentinel comment stamped at the top of every file the CLI generates and
+* owns. Commands like `doctor` and `eject` look for this marker to decide
+* whether a file is safe to touch; the trailing `v1` lets the format evolve
+* without mistaking newer managed files for hand-edited ones.
+*/
+const MANAGED_MARKER = "// zitadel-cli: managed-file v1";
+//#endregion
+//#region src/lib/oclif/base.ts
+/**
+* Base class for every oclif command. Owns the global flags, builds the
+* {@link GlobalOptions} context (including server `source` resolution) the
+* subclass's `run` reads via `this.meta`, and turns the {@link CommandResult}
+* it returns into the JSON envelope (oclif serialises it natively in `--json`
+* mode) or human-facing text. Errors are translated into the failure envelope
+* and the mapped process exit code. Subclasses stay thin: parse flags, call
+* {@link toMeta}, do their work, and `return this.emit(...)`. The agent
+* contract (ADR 004) is preserved — oclif only replaces parsing, dispatch,
+* help, and JSON emission.
+*/
+var BaseCommand = class extends Command {
+	/** Opt into oclif's native `--json` flag and JSON serialisation of the result. */
+	static enableJsonFlag = true;
+	/** Flags shared by every command, inherited via oclif `baseFlags`. */
+	static baseFlags = {
+		cwd: Flags.string({
+			char: "c",
+			description: "Project directory to operate on."
+		}),
+		server: Flags.string({
+			char: "s",
+			description: "Override the resolved server URL."
+		}),
+		"non-interactive": Flags.boolean({
+			char: "n",
+			description: "Disable prompts. Required when scripting or running as an agent."
+		}),
+		force: Flags.boolean({
+			char: "f",
+			description: "Overwrite protected files on conflict."
+		}),
+		"dry-run": Flags.boolean({ description: "Preview without mutating files or the platform." }),
+		verbose: Flags.boolean({ description: "Verbose logging." }),
+		debug: Flags.boolean({ description: "Debug logging." })
+	};
+	/** Resolved context for the current invocation; set by {@link toMeta}. */
+	meta = this.fallbackMeta();
+	/**
+	* Builds {@link GlobalOptions} from parsed flags, resolving the server
+	* `source` by the documented precedence and storing the result on
+	* `this.meta` so the error handler can render a complete envelope.
+	*/
+	async toMeta(flags) {
+		const cwd = resolveCwd(typeof flags.cwd === "string" ? flags.cwd : void 0);
+		const serverFlag = typeof flags.server === "string" ? flags.server : void 0;
+		const environment = typeof flags.environment === "string" ? flags.environment : "development";
+		const source = await resolveServer({
+			cwd,
+			env: process.env,
+			serverFlag,
+			environment
+		});
+		const json = this.jsonEnabled();
+		const isTTY = Boolean(process.stdout.isTTY && process.stdin.isTTY);
+		const verbose = Boolean(flags.verbose);
+		const debug = Boolean(flags.debug);
+		consola.level = json ? -999 : debug ? 4 : 3;
+		consola.options.formatOptions = {
+			...consola.options.formatOptions,
+			date: false,
+			colors: true,
+			compact: true
+		};
+		this.meta = {
+			cwd,
+			nonInteractive: Boolean(flags["non-interactive"]) || !isTTY || json,
+			dryRun: Boolean(flags["dry-run"]),
+			force: Boolean(flags.force),
+			command: this.id ?? "(default)",
+			cliVersion: this.config.version,
+			source: source.value,
+			serverFlag,
+			verbose,
+			debug,
+			env: process.env,
+			isTTY
+		};
+		return this.meta;
+	}
+	/**
+	* Final step of every command: in human mode it prints the rendered result
+	* (oclif suppresses {@link Command.log} under `--json`); it returns the
+	* envelope so oclif's `--json` path serialises it.
+	*/
+	emit(result) {
+		this.log(renderPretty(result, this.meta));
+		return toEnvelope(result, this.meta);
+	}
+	/**
+	* Renders any thrown error as the failure envelope and exits with its code.
+	* A flag-parse error fires before {@link toMeta} runs, so the local `meta`
+	* here refreshes `command` from the now-resolved command id to keep the
+	* envelope's `command` field accurate.
+	*/
+	async catch(error) {
+		const meta = {
+			...this.meta,
+			command: this.id ?? this.meta.command
+		};
+		const zitadelError = toZitadelError(error);
+		if (this.jsonEnabled()) this.logJson(toErrorEnvelope(zitadelError, meta));
+		else this.logToStderr(renderError(zitadelError));
+		return this.exit(zitadelError.exitCode);
+	}
+	/**
+	* Context used before {@link toMeta} runs, so an error thrown during flag
+	* parsing still renders a complete envelope. Version comes from oclif's
+	* resolved {@link Command.config}.
+	*/
+	fallbackMeta() {
+		return {
+			cwd: resolveCwd(void 0),
+			nonInteractive: false,
+			dryRun: false,
+			force: false,
+			command: "(default)",
+			cliVersion: this.config.version,
+			source: "",
+			verbose: false,
+			debug: false,
+			env: process.env,
+			isTTY: Boolean(process.stdout.isTTY && process.stdin.isTTY)
+		};
+	}
+};
+/** Wraps a {@link CommandResult} with the invocation metadata into the final envelope. */
+function toEnvelope(result, meta) {
+	const base = {
+		cli_version: meta.cliVersion,
+		command: meta.command,
+		source: meta.source
+	};
+	if (result.status === "ok") return {
+		...base,
+		status: "ok",
+		data: result.data,
+		warnings: result.warnings ? [...result.warnings] : []
+	};
+	return {
+		...base,
+		status: "skipped",
+		reason: result.reason,
+		data: result.data,
+		next_commands: result.nextCommands ? [...result.nextCommands] : void 0
+	};
+}
+/** Builds the failure envelope from a {@link ZitadelError} and the invocation metadata. */
+function toErrorEnvelope(error, meta) {
+	return {
+		status: "error",
+		cli_version: meta.cliVersion,
+		command: meta.command,
+		source: meta.source,
+		code: error.code,
+		message: error.message,
+		hint: error.hint,
+		next_commands: error.nextCommands,
+		details: error.details
+	};
+}
+/**
+* Renders a {@link CommandResult} as human-facing text for non-JSON mode. A
+* command may supply a bespoke `pretty` string (e.g. the `apply` plan diff);
+* otherwise success payloads are summarised by {@link formatData} and skips are
+* shown with their reason and follow-up commands.
+*/
+function renderPretty(result, meta) {
+	if (result.pretty !== void 0) return result.pretty;
+	if (result.status === "ok") return formatData(result.data, result.warnings ? [...result.warnings] : [], meta);
+	const lines = [`Skipped: ${result.reason}${suffixBlock(meta)}`];
+	if (result.nextCommands && result.nextCommands.length > 0) {
+		lines.push("Next:");
+		for (const cmd of result.nextCommands) lines.push(`  $ ${cmd}`);
+	}
+	return lines.join("\n");
+}
+/**
+* Renders a {@link ZitadelError} as a human-readable block for stderr: the
+* coded message, an optional hint, and any suggested next commands.
+*/
+function renderError(error) {
+	const lines = [`Error ${error.code}: ${error.message}`];
+	if (error.hint) lines.push(error.hint);
+	if (error.nextCommands && error.nextCommands.length > 0) {
+		lines.push("Next:");
+		for (const cmd of error.nextCommands) lines.push(`  $ ${cmd}`);
+	}
+	return lines.join("\n");
+}
+function formatData(data, warnings, opts) {
+	if (typeof data === "string") {
+		const suffix = sourceSuffix(opts);
+		return suffix ? `${data}\n${suffix}` : data;
+	}
+	const lines = [];
+	const titleLine = isObject(data) && typeof data.title === "string" ? String(data.title) : "Zitadel command completed.";
+	lines.push(titleLine);
+	const suffix = sourceSuffix(opts);
+	if (suffix) lines.push(suffix);
+	if (isObject(data)) {
+		renderKnownSections(lines, data);
+		if (Array.isArray(data.next_actions) && data.next_actions.length > 0) {
+			lines.push("");
+			lines.push("Next:");
+			for (const action of data.next_actions) lines.push(`  ${String(action)}`);
+		}
+		if (Array.isArray(data.next_commands) && data.next_commands.length > 0) {
+			if (!Array.isArray(data.next_actions) || data.next_actions.length === 0) {
+				lines.push("");
+				lines.push("Next:");
+			}
+			for (const cmd of data.next_commands) lines.push(`  $ ${String(cmd)}`);
+		}
+	}
+	for (const warning of warnings) lines.push(`Warning: ${warning}`);
+	return lines.join("\n");
+}
+function renderKnownSections(lines, data) {
+	if (isObject(data.project)) {
+		const project = data.project;
+		const segments = [];
+		if (typeof project.project_id === "string") segments.push(`project=${project.project_id}`);
+		if (typeof project.lifecycle === "string") segments.push(`lifecycle=${project.lifecycle}`);
+		if (typeof project.issuer === "string") segments.push(`issuer=${project.issuer}`);
+		if (segments.length > 0) lines.push(`Project: ${segments.join("  ")}`);
+	}
+	if (typeof data.framework === "string") lines.push(`framework=${data.framework}`);
+	if (Array.isArray(data.files_written) || Array.isArray(data.files_skipped)) {
+		const written = Array.isArray(data.files_written) ? data.files_written.length : 0;
+		const skippedCount = Array.isArray(data.files_skipped) ? data.files_skipped.length : 0;
+		lines.push(`Files: ${written} written, ${skippedCount} unchanged`);
+	}
+	if (isObject(data.apply)) {
+		const apply = data.apply;
+		const bits = [];
+		if (typeof apply.config_version === "number") bits.push(`v${apply.config_version}`);
+		if (typeof apply.hash === "string") bits.push(`hash=${String(apply.hash).slice(0, 12)}`);
+		if (typeof apply.environment === "string") bits.push(`env=${apply.environment}`);
+		if (bits.length > 0) lines.push(`Apply: ${bits.join("  ")}`);
+	}
+	if (Array.isArray(data.checks) && data.checks.length > 0) {
+		lines.push("Checks:");
+		for (const check of data.checks) {
+			if (!isObject(check)) continue;
+			const status = check.status === "pass" ? "ok" : "fail";
+			lines.push(`  [${status}] ${String(check.name ?? "check")}: ${String(check.message ?? "")}`);
+		}
+	}
+}
+function sourceSuffix(opts) {
+	try {
+		const url = new URL(opts.source);
+		if (url.host === "api.zitadel.cloud") return "";
+		return `(server: ${url.host})`;
+	} catch {
+		return "";
+	}
+}
+function suffixBlock(opts) {
+	const suffix = sourceSuffix(opts);
+	return suffix ? ` ${suffix}` : "";
+}
+//#endregion
+//#region src/lib/project.ts
+/**
+* Reports whether `cwd` has already been initialized, i.e. a committed
+* `zitadel.json` exists. Used to decide whether setup should run or skip.
+*/
+async function hasZitadelConfig(cwd) {
+	return exists(join(cwd, "zitadel.json"));
+}
+/**
+* Reports whether local secret material (`.zitadel/secret`) is present. Gates
+* commands that need credentials, and signals that secrets were already pulled.
+*/
+async function hasZitadelSecret(cwd) {
+	return exists(join(cwd, ".zitadel/secret"));
+}
+async function exists(path) {
+	try {
+		await stat(path);
+		return true;
+	} catch (error) {
+		if (isNotFound(error)) return false;
+		throw error;
+	}
+}
+/**
+* Reads and parses `zitadel.json` into a plain object. Translates a missing
+* file into an actionable `E_VALIDATION` error pointing at `zitadel setup`;
+* other errors (e.g. malformed JSON) propagate unchanged.
+*/
+async function readZitadelConfig(cwd) {
+	try {
+		return parseJsonObject(await readFile(join(cwd, "zitadel.json"), "utf8"), "zitadel.json");
+	} catch (error) {
+		if (isNotFound(error)) throw new ZitadelError("E_VALIDATION", "zitadel.json was not found", {
+			hint: "Run `zitadel setup` first.",
+			nextCommands: ["zitadel setup"]
+		});
+		throw error;
+	}
+}
+/**
+* Reads, parses, and structurally validates `.zitadel/secret`, returning it
+* as a {@link ZitadelSecret}. A missing file becomes an actionable
+* `E_VALIDATION` error pointing at `zitadel setup` / `zitadel doctor --fix`;
+* a present-but-incomplete file throws so callers never proceed with partial
+* credentials.
+*/
+async function readZitadelSecret(cwd) {
+	try {
+		const secret = parseJsonObject(await readFile(join(cwd, ".zitadel/secret"), "utf8"), ".zitadel/secret");
+		if (typeof secret.project_id !== "string" || typeof secret.project_secret !== "string" || typeof secret.preview_secret !== "string" || !Array.isArray(secret.preview_origins)) throw new Error(".zitadel/secret is missing required fields");
+		return secret;
+	} catch (error) {
+		if (isNotFound(error)) throw new ZitadelError("E_VALIDATION", ".zitadel/secret was not found", {
+			hint: "Run `zitadel setup` first, or restore the project secret with `zitadel doctor --fix`.",
+			nextCommands: ["zitadel setup", "zitadel doctor --fix"]
+		});
+		throw error;
+	}
+}
+/**
+* Reads the configured renderer id from a parsed `zitadel.json`, normalising the
+* legacy `default` alias to `react` and falling back to `react` when unset. The
+* value is validated downstream by `getRenderer`, so callers need not re-check.
+*/
+function readRendererId(config) {
+	const branding = isObject(config.branding) ? config.branding : void 0;
+	const value = branding && typeof branding.renderer === "string" ? branding.renderer : "react";
+	return value === "default" ? "react" : value;
+}
+/** Reads `environments.development.issuer` from a parsed `zitadel.json`, if present. */
+function readDevelopmentIssuer(config) {
+	if (isObject(config.environments) && isObject(config.environments.development)) {
+		const issuer = config.environments.development.issuer;
+		return typeof issuer === "string" ? issuer : void 0;
+	}
+}
+function isNotFound(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+//#endregion
+export { readZitadelConfig as a, MANAGED_MARKER as c, parseJsonObject as d, stableStringify as f, readRendererId as i, DEFAULT_SERVER as l, hasZitadelSecret as n, readZitadelSecret as o, ZitadelError as p, readDevelopmentIssuer as r, BaseCommand as s, hasZitadelConfig as t, isObject as u };
+
+//# sourceMappingURL=project-C3pSfbao.mjs.map