feat: improve astro:env config error

.changeset/curvy-readers-invent.md

@@ -0,0 +1,5 @@
+---
+'astro': patch
+---
+
+Improves the config error for invalid combinations of `context` and `access` properties under `env.schema`

packages/astro/src/env/schema.ts

@@ -75,11 +75,28 @@ const SecretServerEnvFieldMetadata = z.object({
 	context: z.literal('server'),
 	access: z.literal('secret'),
 });
-const EnvFieldMetadata = z.union([
+const _EnvFieldMetadata = z.union([
 	PublicClientEnvFieldMetadata,
 	PublicServerEnvFieldMetadata,
 	SecretServerEnvFieldMetadata,
 ]);
+const EnvFieldMetadata = z.custom<z.input<typeof _EnvFieldMetadata>>().superRefine((data, ctx) => {
+	const result = _EnvFieldMetadata.safeParse(data);
+	if (result.success) {
+		return;
+	}
+	for (const issue of result.error.issues) {
+		if (issue.code === z.ZodIssueCode.invalid_union) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				message: `**Invalid combination** of "access" and "context" options:\n  Secret client variables are not supported. Please review the configuration of \`env.schema.${ctx.path.at(-1)}\`.\n  Learn more at https://docs.astro.build/en/guides/environment-variables/#variable-types`,
+				path: ['context', 'access'],
+			});
+		} else {
+			ctx.addIssue(issue);
+		}
+	}
+});
 
 const EnvSchemaKey = z
 	.string()

packages/astro/test/units/config/config-validate.test.js

@@ -406,5 +406,25 @@ describe('Config Validation', () => {
 				'A valid variable name cannot start with a number.',
 			);
 		});
+
+		it('Should provide a useful error for access/context invalid combinations', async () => {
+			const configError = await validateConfig(
+				{
+					env: {
+						schema: {
+							BAR: envField.string({ access: 'secret', context: 'client' }),
+						},
+					},
+				},
+				process.cwd(),
+			).catch((err) => err);
+			assert.equal(configError instanceof z.ZodError, true);
+			assert.equal(
+				configError.errors[0].message.includes(
+					'**Invalid combination** of "access" and "context" options',
+				),
+				true,
+			);
+		});
 	});
 });