bsmnt 0.5.0 → 0.6.0

package/src/agent-skills/manage-env/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: manage-env
+description: >-
+  Use when adding or changing an environment variable in a project that uses our
+  dotenvx setup. Decides secret vs trivial config: trivial/`NEXT_PUBLIC_*` the
+  agent handles fully, but for a secret the agent only wires the key in code
+  (process.env, validation schema, types) and hands the value-setting to the
+  human — it never types a secret value into a command. Triggers on "add an env
+  var", "new environment variable", "set an API key/token/secret", "put X in
+  .env", "encrypt env", or editing any `.env*` file.
+---
+
+# Add or change an environment variable
+
+This project uses **dotenvx**. Env files:
+
+- `.env` — shared / development, committed **encrypted**
+- `.env.preview`, `.env.production` — per-environment overrides, committed encrypted (created on demand)
+- `.env.local` — plaintext, gitignored (personal local overrides)
+- `.env.keys` — private keys, gitignored (backed up in the team password manager)
+
+Scripts run `dotenvx run -f .env.$VERCEL_ENV -f .env -- …`, so the env-specific
+file overrides `.env`. A **gitleaks** pre-commit hook + CI scan are the real
+enforcement — this skill just makes the right choice the default.
+
+## 1. Secret or trivial config?
+
+- **Secret** — API keys, tokens, DB URLs, anything you'd rotate if it leaked.
+- **Trivial** — public base URLs, feature flags, anything `NEXT_PUBLIC_*` (it
+  ships to the browser anyway). Plaintext is fine; encrypting buys nothing.
+
+## 2a. Secret → never put the value in a command
+
+A raw secret in a command (`env:set KEY <value>`) leaks the plaintext into the
+tool call and the conversation context. So split the work:
+
+- **Agent — code wiring only, never the value.** Read it via `process.env.KEY`,
+  add it to the env validation schema / types if the project has one, and add a
+  placeholder line to `.env.example`. Document the key name and where it's used.
+- **Human — owns the value.** Either run `bun run env:set KEY <value>` yourself
+  (`--preview` / `--prod` for per-environment), or set it directly in the Vercel
+  environment. `env:set` encrypts in place and adds the matching
+  `DOTENV_PRIVATE_KEY*` to `.env.keys`.
+- **Verify (agent):** only via `git diff` showing `KEY=encrypted:…`. Never run
+  `env:view` on a secret — it prints the decrypted value into context.
+- Each `DOTENV_PRIVATE_KEY*` must exist on the matching Vercel environment and as a
+  CI secret, or it won't decrypt there.
+- **Edge runtime caveat.** dotenvx only decrypts in the Node runtime (via
+  `instrumentation.ts`). A secret read in `middleware.ts` or a `runtime = "edge"`
+  route is **not** decrypted from `.env` — it must be set directly as a Vercel env
+  var. The encrypted `.env` covers Node functions + build, not the edge.
+
+## 2b. Trivial config → plaintext
+
+Add it plaintext — no encryption — with `bun run env:set KEY value --plain`, or
+just append a line to the file:
+
+```bash
+NEXT_PUBLIC_FOO=bar
+```
+
+gitleaks ignores non-secret plaintext, so it won't fail the scan.
+
+## Rule
+
+Never commit a real secret in plaintext. If one lands there, bulk-encrypt it in
+place with `bun run env:encrypt-all` (no value typed).

package/src/modules/features/cms/sanity/files/app/blog/[slug]/page.tsx

@@ -6,6 +6,9 @@ import {
 	ALL_ARTICLES_QUERY,
 	ARTICLE_QUERY,
 } from "@/lib/integrations/sanity/queries";
+import { urlForImage } from "@/lib/integrations/sanity/utils/image";
+import { buildPageJsonLd } from "@/lib/integrations/sanity/utils/page-json-ld";
+import { generateArticleJsonLd, JsonLd } from "@/lib/utils/json-ld";
 
 export async function generateStaticParams() {
 	if (!client) return [];
@@ -30,28 +33,52 @@ export default async function BlogArticlePage({ params }: Props) {
 
 	if (!article) return notFound();
 
+	const articleUrl = `/blog/${slug}`;
+	const articleImage = article.featuredImage
+		? urlForImage(article.featuredImage).url()
+		: article.metadata?.image
+			? urlForImage(article.metadata.image).url()
+			: undefined;
+	const pageJsonLd = buildPageJsonLd(article.metadata?.jsonLd);
+
 	return (
-		<article className="container mx-auto px-4 py-8 max-w-4xl">
-			<header className="mb-8">
-				<h1 className="text-4xl font-bold mb-4">{article.title}</h1>
-				{article.excerpt && (
-					<p className="text-lg text-gray-600">{article.excerpt}</p>
-				)}
-				<div className="flex gap-4 mt-4 text-sm text-gray-500">
-					{article.author && <span>By {article.author}</span>}
-					{article.publishedAt && (
-						<time dateTime={article.publishedAt}>
-							{new Date(article.publishedAt).toLocaleDateString()}
-						</time>
+		<>
+			<JsonLd
+				data={generateArticleJsonLd({
+					title: article.metadata?.title || article.title || "",
+					url: articleUrl,
+					description: article.metadata?.description || article.excerpt,
+					image: articleImage,
+					datePublished: article.publishedAt,
+					dateModified: article._updatedAt,
+					authorName: article.author,
+				})}
+			/>
+			{pageJsonLd.map(({ key, data }) => (
+				<JsonLd key={key} data={data} />
+			))}
+			<article className="container mx-auto px-4 py-8 max-w-4xl">
+				<header className="mb-8">
+					<h1 className="text-4xl font-bold mb-4">{article.title}</h1>
+					{article.excerpt && (
+						<p className="text-lg text-gray-600">{article.excerpt}</p>
 					)}
-				</div>
-			</header>
-
-			{article.content && (
-				<div className="prose max-w-none">
-					<RichText content={article.content} />
-				</div>
-			)}
-		</article>
+					<div className="flex gap-4 mt-4 text-sm text-gray-500">
+						{article.author && <span>By {article.author}</span>}
+						{article.publishedAt && (
+							<time dateTime={article.publishedAt}>
+								{new Date(article.publishedAt).toLocaleDateString()}
+							</time>
+						)}
+					</div>
+				</header>
+
+				{article.content && (
+					<div className="prose max-w-none">
+						<RichText content={article.content} />
+					</div>
+				)}
+			</article>
+		</>
 	);
 }

package/src/modules/features/cms/sanity/files/components/sanity/structured-data.tsx

@@ -0,0 +1,83 @@
+import { stegaClean } from "next-sanity";
+import { sanityFetch } from "@/lib/integrations/sanity/live";
+import { STRUCTURED_DATA_QUERY } from "@/lib/integrations/sanity/queries";
+import {
+	generateOrganizationJsonLd,
+	generateWebSiteJsonLd,
+	JsonLd,
+} from "@/lib/utils/json-ld";
+
+type StructuredDataResult = {
+	name?: string | null;
+	legalName?: string | null;
+	description?: string | null;
+	url?: string | null;
+	logo?: string | null;
+	sameAs?: (string | null)[] | null;
+	contactPoint?: {
+		email?: string | null;
+		telephone?: string | null;
+		contactType?: string | null;
+	} | null;
+	address?: {
+		streetAddress?: string | null;
+		locality?: string | null;
+		region?: string | null;
+		postalCode?: string | null;
+		country?: string | null;
+	} | null;
+} | null;
+
+const nonEmpty = (value: unknown): string | undefined => {
+	const cleaned = stegaClean(value);
+	return typeof cleaned === "string" && cleaned.trim() !== ""
+		? cleaned
+		: undefined;
+};
+
+/**
+ * Site-wide Organization + WebSite JSON-LD from the Structured Data
+ * singleton, with the static app values as fallback.
+ */
+export async function SanityStructuredData({
+	fallbackName,
+	fallbackDescription,
+	fallbackLogo,
+}: {
+	fallbackName: string;
+	fallbackDescription?: string;
+	fallbackLogo?: string;
+}) {
+	const { data } = await sanityFetch({ query: STRUCTURED_DATA_QUERY });
+	// Deep-clean stega artifacts up front so nested objects (contactPoint,
+	// address) never leak visual-editing markers into the emitted JSON-LD.
+	const structuredData = stegaClean(data as unknown as StructuredDataResult);
+
+	const name = nonEmpty(structuredData?.name) ?? fallbackName;
+	const description =
+		nonEmpty(structuredData?.description) ?? fallbackDescription;
+	const url = nonEmpty(structuredData?.url);
+	const logo = nonEmpty(structuredData?.logo) ?? fallbackLogo;
+
+	const sameAs = (structuredData?.sameAs ?? [])
+		.map(nonEmpty)
+		.filter((value): value is string => Boolean(value));
+
+	return (
+		<>
+			<JsonLd data={generateWebSiteJsonLd({ name, url, description })} />
+			<JsonLd
+				data={generateOrganizationJsonLd({
+					name,
+					url,
+					logo,
+					description,
+					legalName: nonEmpty(structuredData?.legalName),
+					sameAs: sameAs.length ? sameAs : undefined,
+					contactPoint: structuredData?.contactPoint,
+					address: structuredData?.address,
+				})}
+			/>
+		</>
+	);
+}

package/src/modules/features/cms/sanity/files/lib/integrations/sanity/queries.ts

@@ -64,3 +64,17 @@ export const ARTICLE_BY_ID_QUERY = defineQuery(`
     _updatedAt
   }
 `);
+
+// Site-wide structured data (JSON-LD Organization + WebSite identity)
+export const STRUCTURED_DATA_QUERY = defineQuery(`
+  *[_type == "structuredData"][0]{
+    name,
+    legalName,
+    description,
+    url,
+    "logo": logo.asset->url,
+    sameAs,
+    contactPoint,
+    address
+  }
+`);

package/src/modules/features/cms/sanity/files/lib/integrations/sanity/sanity.config.ts

@@ -16,6 +16,10 @@ import { apiVersion, dataset, previewURL, projectId } from "./env";
 import { schema } from "./schemas";
 import { structure } from "./structure";
 
+// Document types pinned to a single editable document.
+const SINGLETON_TYPES = new Set(["structuredData"]);
+const SINGLETON_ACTIONS = new Set(["publish", "discardChanges", "restore"]);
+
 // Helper function for URL resolution
 function resolveHref(documentType?: string, slug?: string): string | undefined {
 	switch (documentType) {
@@ -77,15 +81,27 @@ export default defineConfig({
 		media(),
 	],
 	document: {
-		actions: (prev) => {
+		actions: (prev, context) => {
 			const isProd = process.env.NODE_ENV === "production";
-			if (!isProd) return prev;
 
-			return prev.map((action) =>
+			// Singletons can't be created or deleted from the document pane.
+			const filtered = SINGLETON_TYPES.has(context.schemaType)
+				? prev.filter(
+						(action) =>
+							action.action !== undefined &&
+							SINGLETON_ACTIONS.has(action.action),
+					)
+				: prev;
+
+			if (!isProd) return filtered;
+
+			return filtered.map((action) =>
 				action.action === "publish"
 					? createConfirmPublishAction(action)
 					: action,
 			);
 		},
+		newDocumentOptions: (prev) =>
+			prev.filter((option) => !SINGLETON_TYPES.has(option.templateId)),
 	},
 });

package/src/modules/features/cms/sanity/files/lib/integrations/sanity/sanity.types.ts

@@ -130,6 +130,7 @@ export type Metadata = {
 		_type: "image";
 	};
 	noIndex?: boolean;
+	jsonLd?: Array<{ _key: string; _type: string; [key: string]: unknown }>;
 };
 
 export type RichText = Array<

package/src/modules/features/cms/sanity/files/lib/integrations/sanity/schemas/index.ts

@@ -13,9 +13,34 @@ import { link } from "./link";
 import { metadata } from "./metadata";
 import { navigation } from "./navigation";
 import { richText } from "./richText";
+import { structuredData } from "./structured-data";
+import {
+	customJsonLd,
+	eventJsonLd,
+	faqJsonLd,
+	itemListJsonLd,
+	jobPostingJsonLd,
+	softwareApplicationJsonLd,
+	videoJsonLd,
+} from "./structured-data-blocks";
 
 // Re-export all schemas for convenience
-export { article, example, link, metadata, navigation, richText };
+export {
+	article,
+	customJsonLd,
+	eventJsonLd,
+	example,
+	faqJsonLd,
+	itemListJsonLd,
+	jobPostingJsonLd,
+	link,
+	metadata,
+	navigation,
+	richText,
+	softwareApplicationJsonLd,
+	structuredData,
+	videoJsonLd,
+};
 
 // Schema collection for Sanity configuration
 export const schema: { types: SchemaTypeDefinition[] } = {
@@ -25,11 +50,21 @@ export const schema: { types: SchemaTypeDefinition[] } = {
 		metadata,
 		richText,
 
+		// Page-level JSON-LD blocks (selectable in metadata)
+		faqJsonLd,
+		eventJsonLd,
+		videoJsonLd,
+		jobPostingJsonLd,
+		softwareApplicationJsonLd,
+		itemListJsonLd,
+		customJsonLd,
+
 		// Document types (content pages)
 		article,
 		example,
 
 		// Singleton types (one-off content)
 		navigation,
+		structuredData,
 	],
 };

package/src/modules/features/cms/sanity/files/lib/integrations/sanity/schemas/metadata.ts

@@ -1,4 +1,5 @@
-import { defineField, defineType } from "sanity";
+import { defineArrayMember, defineField, defineType } from "sanity";
+import { pageJsonLdMembers } from "./structured-data-blocks";
 
 export const metadata = defineType({
 	name: "metadata",
@@ -64,5 +65,15 @@ export const metadata = defineType({
 			description: "Prevent search engines from indexing this page",
 			initialValue: false,
 		}),
+		defineField({
+			name: "jsonLd",
+			title: "Structured Data (JSON-LD)",
+			type: "array",
+			description:
+				"Page-level schema.org structured data emitted as JSON-LD. Pick a predefined type, or add a Custom JSON-LD block for anything not listed.",
+			of: pageJsonLdMembers.map((member) =>
+				defineArrayMember({ type: member.name }),
+			),
+		}),
 	],
 });