Preset icons sized by glyph, and environments secrets in the CLI

apps/desktop/src/renderer/routes/_authenticated/settings/environments/utils/env-file/env-file.ts

@@ -1,41 +1,12 @@
-// Parser grammar from dotenv (BSD-2-Clause), which cannot be imported here:
-// its module root pulls in fs, path, os and crypto.
-const LINE =
-	/(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/gm;
+import { parseEnvContent } from "@superset/shared/env-file";
+
+export { type EnvEntry, parseEnvContent } from "@superset/shared/env-file";
 
 const INVALID = {
 	ok: false as const,
 	error: "Please upload a valid .env file.",
 };
 
-export interface EnvEntry {
-	key: string;
-	value: string;
-}
-
-export function parseEnvContent(content: string): EnvEntry[] {
-	const entries: EnvEntry[] = [];
-	const normalised = content.replace(/\r\n?/gm, "\n");
-
-	LINE.lastIndex = 0;
-	let match = LINE.exec(normalised);
-	while (match !== null) {
-		const key = match[1];
-		let value = (match[2] ?? "").trim();
-		const quote = value[0];
-
-		value = value.replace(/^(['"`])([\s\S]*)\1$/gm, "$2");
-		if (quote === '"') {
-			value = value.replace(/\\n/g, "\n").replace(/\\r/g, "\r");
-		}
-
-		entries.push({ key, value });
-		match = LINE.exec(normalised);
-	}
-
-	return entries;
-}
-
 export function validateEnvContent(
 	text: string,
 ): { ok: true } | { ok: false; error: string } {

apps/docs/AGENTS.md

@@ -0,0 +1,13 @@
+# Docs site
+
+Everything under `content/` is published at docs.superset.sh, so it documents
+only what a customer can run today.
+
+- **CLI reference (`content/docs/cli/cli-reference.mdx`) lists public commands
+  only.** A command or group with `audience: "internal"` in its `command.ts` or
+  `meta.ts` under `packages/cli/src/commands/` does not appear here, however
+  useful it is to us; the desktop's help and `superset --help` are where an
+  internal command is discovered. Check the audience before adding an entry,
+  and remove the entry in the same change that makes a command internal.
+- Features behind a flag or an allowlist (cloud workspaces and everything under
+  `environments`, for example) stay out until they ship to everyone.

apps/docs/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

apps/docs/content/docs/cli/cli-reference.mdx

@@ -1327,22 +1327,6 @@ Delete a page and every version. Interactive terminals ask for confirmation
 unless `--yes` is passed; non-interactive input does not prompt.
 </Command>
 
----
-
-### environments
-
-<Command name="superset environments list">
-List the active organization's cloud environments, including their IDs, names,
-and repositories. Human-readable output marks unusable environments. JSON
-returns the environment array, including entries that cannot start a workspace.
-
-```bash
-superset environments list --json
-```
-</Command>
-
----
-
 ### mcp
 
 Use tools from connected plugins. This is separate from the

packages/cli/src/commands/environments/secrets/delete/command.ts

@@ -0,0 +1,33 @@
+import { CLIError, positional, string } from "@superset/cli-framework";
+import { command } from "../../../../lib/command";
+import { resolveEnvironment } from "../../../../lib/environments";
+
+export default command({
+	description: "Delete a variable from an environment",
+	args: [positional("name").required().desc("Variable name")],
+	options: {
+		environment: string().desc(
+			"Environment (id or name); required when the organization has several",
+		),
+	},
+	run: async ({ ctx, args, options }) => {
+		const organizationId = ctx.config.organizationId;
+		if (!organizationId) {
+			throw new CLIError("No active organization", "Run: superset auth login");
+		}
+		const environment = await resolveEnvironment(
+			ctx.api,
+			organizationId,
+			options.environment,
+		);
+		const key = args.name as string;
+		await ctx.api.environment.secrets.remove.mutate({
+			environmentId: environment.id,
+			key,
+		});
+		return {
+			data: { environment: environment.name, key },
+			message: `Deleted ${key} from ${environment.name}`,
+		};
+	},
+});

packages/cli/src/commands/environments/secrets/list/command.ts

@@ -0,0 +1,43 @@
+import { CLIError, string, table } from "@superset/cli-framework";
+import { command } from "../../../../lib/command";
+import { resolveEnvironment } from "../../../../lib/environments";
+
+export default command({
+	description: "List an environment's variables; values are never shown",
+	options: {
+		environment: string().desc(
+			"Environment (id or name); required when the organization has several",
+		),
+	},
+	display: (data) =>
+		table(
+			(data as { secrets: Record<string, unknown>[] }).secrets ?? [],
+			["key", "visibility", "updatedAt"],
+			["NAME", "VISIBILITY", "UPDATED"],
+			[48, 10, 24],
+		),
+	run: async ({ ctx, options }) => {
+		const organizationId = ctx.config.organizationId;
+		if (!organizationId) {
+			throw new CLIError("No active organization", "Run: superset auth login");
+		}
+		const environment = await resolveEnvironment(
+			ctx.api,
+			organizationId,
+			options.environment,
+		);
+		const rows = await ctx.api.environment.secrets.list.query({
+			environmentId: environment.id,
+		});
+		return {
+			data: {
+				environment: { id: environment.id, name: environment.name },
+				secrets: rows.map((row) => ({
+					key: row.key,
+					visibility: row.sensitive ? "secret" : "visible",
+					updatedAt: row.updatedAt.toISOString(),
+				})),
+			},
+		};
+	},
+});

packages/cli/src/commands/environments/secrets/meta.ts

@@ -0,0 +1,4 @@
+export default {
+	sandbox: false,
+	description: "Manage the variables an environment gives its cloud workspaces",
+};

packages/cli/src/commands/environments/secrets/set/command.ts

@@ -0,0 +1,88 @@
+import { readFileSync } from "node:fs";
+import { boolean, CLIError, positional, string } from "@superset/cli-framework";
+import { parseEnvContent } from "@superset/shared/env-file";
+import { command } from "../../../../lib/command";
+import { resolveEnvironment } from "../../../../lib/environments";
+
+async function readStdin(): Promise<string> {
+	const chunks: Buffer[] = [];
+	for await (const chunk of process.stdin) {
+		chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+	}
+	return Buffer.concat(chunks).toString("utf-8");
+}
+
+export default command({
+	description:
+		"Set a variable on an environment, from --body, stdin, or a .env file",
+	args: [
+		positional("name").desc("Variable name; omit when passing --env-file"),
+	],
+	options: {
+		body: string().alias("b").desc("The value; read from stdin when omitted"),
+		envFile: string()
+			.alias("f")
+			.desc("Set every variable in a .env file instead of one name"),
+		visible: boolean().desc(
+			"Store it readable in settings instead of as a secret",
+		),
+		environment: string().desc(
+			"Environment (id or name); required when the organization has several",
+		),
+	},
+	run: async ({ ctx, args, options }) => {
+		const organizationId = ctx.config.organizationId;
+		if (!organizationId) {
+			throw new CLIError("No active organization", "Run: superset auth login");
+		}
+		const name = args.name as string | undefined;
+		if (options.envFile && (name || options.body)) {
+			throw new CLIError("Pass either --env-file or a name with a value");
+		}
+		if (!options.envFile && !name) {
+			throw new CLIError(
+				"Provide a variable name, or --env-file to set several",
+			);
+		}
+
+		let entries: Array<{ key: string; value: string }>;
+		if (options.envFile) {
+			entries = parseEnvContent(readFileSync(options.envFile, "utf-8"));
+			if (entries.length === 0) {
+				throw new CLIError(`No variables found in ${options.envFile}`);
+			}
+		} else {
+			const value =
+				options.body ?? (process.stdin.isTTY ? undefined : await readStdin());
+			if (value === undefined) {
+				throw new CLIError(
+					"No value given",
+					`Pass --body, or pipe it: printf '%s' "$VALUE" | superset environments secrets set ${name}`,
+				);
+			}
+			entries = [{ key: name as string, value }];
+		}
+
+		const environment = await resolveEnvironment(
+			ctx.api,
+			organizationId,
+			options.environment,
+		);
+		for (const entry of entries) {
+			await ctx.api.environment.secrets.set.mutate({
+				environmentId: environment.id,
+				key: entry.key,
+				value: entry.value,
+				sensitive: !options.visible,
+			});
+		}
+		const keys = entries.map((entry) => entry.key);
+		return {
+			data: { environment: environment.name, keys },
+			message:
+				keys.length === 1
+					? `Set ${keys[0]} on ${environment.name}`
+					: `Set ${keys.length} variables on ${environment.name}: ${keys.join(", ")}`,
+		};
+	},
+});

packages/cli/src/lib/environments/index.ts

@@ -0,0 +1 @@
+export { resolveEnvironment } from "./resolveEnvironment";

packages/cli/src/lib/environments/resolveEnvironment.ts

@@ -0,0 +1,46 @@
+import { CLIError } from "@superset/cli-framework";
+import type { ApiClient } from "../api-client";
+
+export interface ResolvedEnvironment {
+	id: string;
+	name: string;
+}
+
+/**
+ * The environment a command acts on, by id or name. Nothing requested is
+ * only unambiguous when the organization has one environment.
+ */
+export async function resolveEnvironment(
+	api: ApiClient,
+	organizationId: string,
+	requested: string | undefined,
+): Promise<ResolvedEnvironment> {
+	const environments = await api.environment.list.query({ organizationId });
+	if (environments.length === 0) {
+		throw new CLIError(
+			"No environments in this organization",
+			"Create one in Settings → Environments",
+		);
+	}
+	const [only] = environments;
+	if (requested === undefined) {
+		if (only && environments.length === 1) return only;
+		throw new CLIError(
+			"Several environments in this organization",
+			`Pass --environment with one of: ${environments.map((environment) => environment.name).join(", ")}`,
+		);
+	}
+	const wanted = requested.trim().toLowerCase();
+	const selected = environments.find(
+		(environment) =>
+			environment.id.toLowerCase() === wanted ||
+			environment.name.toLowerCase() === wanted,
+	);
+	if (!selected) {
+		throw new CLIError(
+			`No environment "${requested}" in this organization`,
+			`Environments: ${environments.map((environment) => environment.name).join(", ")}`,
+		);
+	}
+	return selected;
+}

packages/shared/package.json

@@ -28,6 +28,10 @@
 			"types": "./src/automation-matching/index.ts",
 			"default": "./src/automation-matching/index.ts"
 		},
+		"./env-file": {
+			"types": "./src/env-file.ts",
+			"default": "./src/env-file.ts"
+		},
 		"./environment-secrets": {
 			"types": "./src/environment-secrets.ts",
 			"default": "./src/environment-secrets.ts"

packages/shared/src/env-file.ts

@@ -0,0 +1,33 @@
+// Parser grammar from dotenv (BSD-2-Clause), which cannot be imported in the
+// renderer: its module root pulls in fs, path, os and crypto.
+const LINE =
+	/(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/gm;
+
+export interface EnvEntry {
+	key: string;
+	value: string;
+}
+
+export function parseEnvContent(content: string): EnvEntry[] {
+	const entries: EnvEntry[] = [];
+	const normalised = content.replace(/\r\n?/gm, "\n");
+
+	LINE.lastIndex = 0;
+	let match = LINE.exec(normalised);
+	while (match !== null) {
+		const [, key, rawValue] = match;
+		match = LINE.exec(normalised);
+		if (!key) continue;
+		let value = (rawValue ?? "").trim();
+		const quote = value[0];
+
+		value = value.replace(/^(['"`])([\s\S]*)\1$/gm, "$2");
+		if (quote === '"') {
+			value = value.replace(/\\n/g, "\n").replace(/\\r/g, "\r");
+		}
+
+		entries.push({ key, value });
+	}
+
+	return entries;
+}