bsmnt 0.5.0 → 0.6.0

package/src/modules/features/env/dotenvx/files/setup-env.mjs

@@ -0,0 +1,67 @@
+// Restore .env.keys (dotenvx private decryption keys) from 1Password via `op`.
+// Store either the full .env.keys contents (recommended — covers every
+// environment) or just the DOTENV_PRIVATE_KEY value in a 1Password item field;
+// the reference lives in the committed .env (DOTENV_PRIVATE_KEY_OP_REF):
+//
+//   DOTENV_PRIVATE_KEY_OP_REF="op://Development/<item>/<field>" bun run env:setup
+//
+// `--auto` (run from the preinstall hook) is for onboarding: it never fails
+// `bun install` — it skips when .env.keys already exists, in CI, or when the
+// reference / `op` CLI is missing.
+
+import { spawnSync } from "node:child_process";
+import { existsSync, writeFileSync } from "node:fs";
+
+const AUTO = process.argv.includes("--auto");
+
+// In --auto mode any unmet precondition exits 0 so the install never breaks.
+const stop = (msg) => {
+  console.error(msg);
+  process.exit(AUTO ? 0 : 1);
+};
+
+// Onboarding skips: nothing to do, or the wrong place to do it.
+if (AUTO && existsSync(".env.keys")) process.exit(0);
+if (AUTO && (process.env.CI || process.env.VERCEL)) process.exit(0);
+
+const OP_REF = process.env.DOTENV_PRIVATE_KEY_OP_REF;
+if (!OP_REF) {
+  stop(
+    "✗ set DOTENV_PRIVATE_KEY_OP_REF to the 1Password reference for .env.keys\n" +
+      '  e.g. DOTENV_PRIVATE_KEY_OP_REF="op://Development/<item>/<field>" bun run env:setup',
+  );
+}
+
+const res = spawnSync("op", ["read", OP_REF], { encoding: "utf8" });
+
+if (res.error) {
+  const why =
+    res.error.code === "ENOENT"
+      ? "install the 1Password CLI (`op`) and sign in — https://developer.1password.com/docs/cli/get-started/"
+      : res.error.message;
+  stop(`✗ failed to run \`op\`: ${why}`);
+}
+
+if (res.status !== 0) {
+  stop(`✗ \`op read\` failed:\n${res.stderr.trim()}`);
+}
+
+const HEADER = `#/------------------!DOTENV_PRIVATE_KEYS!-------------------/
+#/ private decryption keys. DO NOT commit to source control /
+#/     [how it works](https://dotenvx.com/encryption)       /
+#/          ⛨ ARMORED KEYS: \`dotenvx armor up\`              /
+#/----------------------------------------------------------/
+
+# .env
+`;
+
+const value = res.stdout.trim();
+
+// op may hold the full .env.keys file or just the bare private key. Pass full
+// contents through; wrap a bare key in the standard .env.keys format.
+const contents = value.includes("DOTENV_PRIVATE_KEY")
+  ? `${value}\n`
+  : `${HEADER}DOTENV_PRIVATE_KEY=${value}\n`;
+
+writeFileSync(".env.keys", contents);
+console.info("✓ wrote .env.keys from 1Password");

package/src/modules/features/env/dotenvx/files/vercelignore

@@ -0,0 +1,4 @@
+# Never upload the private keys or local env files on `vercel deploy`.
+# (Encrypted .env / .env.production / .env.preview ARE uploaded — they're safe.)
+.env.keys
+.env*.local

package/src/modules/features/env/dotenvx/files/write-env.mjs

@@ -0,0 +1,47 @@
+// Add or (re)encrypt env values without remembering the dotenvx flags.
+//
+//   bun run env:set KEY value          # encrypt one value into .env
+//   bun run env:set KEY value --plain  # store it plaintext (e.g. NEXT_PUBLIC_*)
+//   bun run env:set KEY value --prod   # target .env.production (--preview too)
+//   bun run env:encrypt-all            # bulk-encrypt every plaintext value in .env
+//   bun run env:encrypt-all --prod     # bulk-encrypt .env.production
+
+import { spawnSync } from "node:child_process";
+
+const [mode, ...rest] = process.argv.slice(2);
+
+// --prod / --preview pick the per-environment file; default is the shared .env.
+const ENV_FLAGS = new Set(["--prod", "--production", "--preview"]);
+const file =
+  rest.includes("--prod") || rest.includes("--production")
+    ? ".env.production"
+    : rest.includes("--preview")
+      ? ".env.preview"
+      : ".env";
+
+// On bulk encrypt, keep browser-public NEXT_PUBLIC_* and the 1Password pointer
+// plaintext (same exclusions the scaffold uses).
+const EXCLUDE = ["--exclude-key", "DOTENV_PRIVATE_KEY_OP_REF", "NEXT_PUBLIC_*"];
+
+function run(args) {
+  // `dotenvx` resolves from node_modules/.bin when run via `bun run`.
+  const res = spawnSync("dotenvx", args, { stdio: "inherit" });
+  process.exit(res.status ?? 1);
+}
+
+if (mode === "encrypt") {
+  run(["encrypt", "-f", file, ...EXCLUDE]);
+} else if (mode === "set") {
+  // Forward KEY, value and any dotenvx flags (e.g. --plain) straight through.
+  const passthrough = rest.filter((arg) => !ENV_FLAGS.has(arg));
+  if (passthrough.filter((arg) => !arg.startsWith("-")).length < 2) {
+    console.error(
+      "Usage: bun run env:set KEY value [--plain] [--preview|--prod]",
+    );
+    process.exit(1);
+  }
+  run(["set", ...passthrough, "-f", file]);
+} else {
+  console.error(`Unknown env command: ${mode ?? "(none)"} (use set | encrypt)`);
+  process.exit(1);
+}

package/src/templates/next-default/.env.example

@@ -1,11 +1,19 @@
 # ============================================
 # Basement Next Starter - Environment Variables
 # ============================================
-# Copy this file to .env.local and fill in the values
-# Run: cp .env.example .env.local
+# This project uses dotenvx (https://dotenvx.com): the committed `.env` holds
+# shared values, with secrets encrypted there. The private keys live in
+# `.env.keys` (gitignored) — restore them with `bun run env:setup`.
 #
-# Only configure the integrations you need.
-# Remove unused sections to keep your env file clean.
+# Add or change a variable in `.env` (not .env.local):
+#   - Secret (API key, token, …):  bun run env:set KEY value   (--preview / --prod)
+#   - Trivial / NEXT_PUBLIC_*:      bun run env:set KEY value --plain
+#   - Bulk-encrypt a file edited by hand:  bun run env:encrypt-all  (--preview / --prod)
+#
+# Edge runtime (middleware, `runtime = "edge"`): dotenvx can't decrypt there.
+# Set any secret those read directly in Vercel's env vars, not here.
+#
+# This file just documents the available variables; real values live in `.env`.
 # ============================================
 
 
@@ -16,7 +24,7 @@
 # Base URL for your site (used for SEO, canonical URLs, etc.)
 # Development: http://localhost:3000
 # Production: https://your-domain.com
-NEXT_PUBLIC_BASE_URL="http://localhost:3000"
+NEXT_PUBLIC_BASE_URL=""
 
 # Draft mode secret for preview functionality
 # Generate a random string: openssl rand -base64 32
@@ -32,7 +40,7 @@ DRAFT_MODE_TOKEN=""
 
 # Required for Sanity
 NEXT_PUBLIC_SANITY_PROJECT_ID=""
-NEXT_PUBLIC_SANITY_DATASET="production"
+NEXT_PUBLIC_SANITY_DATASET=""
 NEXT_PUBLIC_SANITY_API_READ_TOKEN=""
 
 # Optional - for server-side mutations and visual editing

package/src/templates/next-default/.github/workflows/ci.yml

@@ -46,8 +46,29 @@ jobs:
       - name: Lint
         run: bun run lint
 
+      # dotenvx needs the private key to decrypt secrets at build time. It's
+      # pulled from 1Password via an org-wide service-account token + the op-ref
+      # committed in .env. Optional: builds pass without it (only plaintext /
+      # NEXT_PUBLIC_* is read), and a per-repo DOTENV_PRIVATE_KEY secret still
+      # works as a fallback.
+      - name: Install 1Password CLI
+        if: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN != '' }}
+        uses: 1password/install-cli-action@v1
+
       - name: Build
-        run: bun run build
+        env:
+          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
+          DOTENV_PRIVATE_KEY: ${{ secrets.DOTENV_PRIVATE_KEY }}
+        run: |
+          if [ -n "$OP_SERVICE_ACCOUNT_TOKEN" ]; then
+            ref="$(grep -m1 '^DOTENV_PRIVATE_KEY_OP_REF=' .env | cut -d= -f2-)"
+            if [ -n "$ref" ]; then
+              DOTENV_PRIVATE_KEY="$(op read "$ref")"
+              echo "::add-mask::$DOTENV_PRIVATE_KEY"
+              export DOTENV_PRIVATE_KEY
+            fi
+          fi
+          bun run build
 
       # Runs your tests if any exist; a fresh project with none passes cleanly.
       - name: Test

package/src/templates/next-default/.vscode/extensions.json

@@ -10,6 +10,9 @@
     // Sanity CMS (GROQ syntax + validation)
     "sanity-io.vscode-sanity",
 
+    // Env (dotenvx — view decrypted .env values inline)
+    "dotenv.dotenvx-vscode",
+
     // DX Enhancements
     "yoavbls.pretty-ts-errors"
   ]

package/src/templates/next-default/README.md

@@ -22,6 +22,35 @@ bun dev
 | `bun format` | Format the codebase |
 | `bun typecheck` | Run TypeScript |
 | `bun analyze` | Analyze the Next.js bundle |
+| `bun env:set KEY value` | Encrypt one value into `.env` (`--plain`, `--preview`/`--prod`) |
+| `bun env:encrypt-all` | Bulk-encrypt every plaintext value in a file (`--preview`/`--prod`) |
+| `bun env:setup` | Restore `.env.keys` from 1Password |
+| `bun env:view` | Print the decrypted `.env` (`--preview` / `--prod`) |
+| `bun env:setup-remote` | Push private keys to GitHub / Vercel (`github`/`vercel`, or pick) |
+| `bun env:save` | Save the private key to 1Password (Development vault) |
+
+## Environment variables
+
+Secrets are encrypted at rest with [dotenvx](https://dotenvx.com): the committed `.env` holds encrypted values, the private keys live in `.env.keys` (gitignored), and dev/build run through `dotenvx run` so values decrypt automatically.
+
+**First run.** `bun install` restores `.env.keys` from 1Password (via `DOTENV_PRIVATE_KEY_OP_REF` in `.env`), or run `bun run env:setup`. Needs 1Password access + the `op` CLI:
+
+- macOS: `brew install --cask 1password-cli`
+- Windows: `winget install 1password-cli`
+- Linux / other: [1Password CLI docs](https://developer.1password.com/docs/cli/get-started/)
+
+**Add or change a variable** (in `.env`):
+
+- Secret: `bun run env:set KEY value` (`--preview`/`--prod` to target an environment)
+- Public / `NEXT_PUBLIC_*`: `bun run env:set KEY value --plain`
+- Bulk-encrypt a hand-edited file: `bun run env:encrypt-all`
+- Inspect: `bun run env:view` (`--preview`/`--prod`)
+
+**Per environment.** Scripts load `.env.$VERCEL_ENV` over `.env`. After adding a per-env file, push its key with `bun run env:setup-remote vercel` — `instrumentation.ts` uses it to decrypt at runtime.
+
+**Edge runtime.** dotenvx decrypts only in the Node runtime; secrets read in `middleware.ts` or a `runtime = "edge"` route must be set as plain Vercel env vars.
+
+A gitleaks pre-commit hook + CI scan block committed plaintext secrets (install: `brew install gitleaks`).
 
 ## Project Structure
 
@@ -60,6 +89,8 @@ The workflow takes its runtime versions from your manifests, so there's a single
 
 It also caches Bun's install cache between runs, and the test step is a no-op until you add real test files.
 
+The build decrypts the committed `.env` with the dotenvx private key, pulled from 1Password: set an **org-level** `OP_SERVICE_ACCOUNT_TOKEN` (a read-only [service account](https://developer.1password.com/docs/service-accounts/) scoped to the `Development` vault) — one secret for every repo — and CI reads the key via the op-ref committed in `.env`. A per-repo `DOTENV_PRIVATE_KEY` secret (`bun run env:setup-remote github`) works as a fallback; builds pass without either (only plaintext / `NEXT_PUBLIC_*` is read).
+
 ### Branch protection
 
 To block merges when CI fails, enable branch protection on `main`:

package/src/templates/next-default/lib/utils/json-ld.tsx

@@ -1,9 +1,15 @@
 import type {
   Article,
   BreadcrumbList,
+  Event as EventSchema,
+  FAQPage,
+  ItemList,
+  JobPosting,
   Organization,
   SearchAction,
+  SoftwareApplication,
   Thing,
+  VideoObject,
   WebPage,
   WebSite,
   WithContext,
@@ -41,10 +47,10 @@ export function JsonLd<T extends Thing>({ data }: { data: WithContext<T> }) {
 
 interface WebSiteJsonLdOptions {
   name: string
-  url?: string
-  description?: string
+  url?: string | undefined
+  description?: string | undefined
   /** URL to site-wide search (e.g. "/search?q={search_term_string}") */
-  searchUrl?: string
+  searchUrl?: string | undefined
 }
 
 export function generateWebSiteJsonLd(
@@ -70,21 +76,69 @@ export function generateWebSiteJsonLd(
   }
 }
 
+interface OrganizationContactPoint {
+  email?: string | null
+  telephone?: string | null
+  contactType?: string | null
+}
+
+interface OrganizationAddress {
+  streetAddress?: string | null
+  locality?: string | null
+  region?: string | null
+  postalCode?: string | null
+  country?: string | null
+}
+
 interface OrganizationJsonLdOptions {
   name: string
-  url?: string
-  logo?: string
-  description?: string
-  sameAs?: string[]
+  url?: string | undefined
+  logo?: string | undefined
+  description?: string | undefined
+  sameAs?: string[] | undefined
+  legalName?: string | undefined
+  contactPoint?: OrganizationContactPoint | null | undefined
+  address?: OrganizationAddress | null | undefined
 }
 
 export function generateOrganizationJsonLd(
   options: OrganizationJsonLdOptions
 ): WithContext<Organization> {
-  const { name, url, logo, description, sameAs } = options
+  const { name, url, logo, description, sameAs, legalName, contactPoint, address } =
+    options
   const resolvedUrl = resolveUrl(url)
   const resolvedLogo = resolveUrl(logo)
 
+  const contactPointNode =
+    contactPoint &&
+    (contactPoint.email || contactPoint.telephone || contactPoint.contactType)
+      ? {
+          "@type": "ContactPoint" as const,
+          ...(contactPoint.email && { email: contactPoint.email }),
+          ...(contactPoint.telephone && { telephone: contactPoint.telephone }),
+          ...(contactPoint.contactType && {
+            contactType: contactPoint.contactType,
+          }),
+        }
+      : undefined
+
+  const addressNode =
+    address &&
+    (address.streetAddress ||
+      address.locality ||
+      address.region ||
+      address.postalCode ||
+      address.country)
+      ? {
+          "@type": "PostalAddress" as const,
+          ...(address.streetAddress && { streetAddress: address.streetAddress }),
+          ...(address.locality && { addressLocality: address.locality }),
+          ...(address.region && { addressRegion: address.region }),
+          ...(address.postalCode && { postalCode: address.postalCode }),
+          ...(address.country && { addressCountry: address.country }),
+        }
+      : undefined
+
   return {
     "@context": "https://schema.org",
     "@type": "Organization",
@@ -92,17 +146,20 @@ export function generateOrganizationJsonLd(
     ...(resolvedUrl && { url: resolvedUrl }),
     ...(resolvedLogo && { logo: resolvedLogo }),
     ...(description && { description }),
-    ...(sameAs && { sameAs }),
+    ...(legalName && { legalName }),
+    ...(sameAs?.length && { sameAs }),
+    ...(contactPointNode && { contactPoint: contactPointNode }),
+    ...(addressNode && { address: addressNode }),
   }
 }
 
 interface WebPageJsonLdOptions {
   title: string
-  url?: string
-  description?: string
-  image?: string
-  datePublished?: string
-  dateModified?: string
+  url?: string | undefined
+  description?: string | undefined
+  image?: string | undefined
+  datePublished?: string | undefined
+  dateModified?: string | undefined
 }
 
 export function generateWebPageJsonLd(
@@ -127,13 +184,13 @@ export function generateWebPageJsonLd(
 
 interface ArticleJsonLdOptions {
   title: string
-  url?: string
-  description?: string
-  image?: string
-  datePublished?: string
-  dateModified?: string
-  authorName?: string
-  authorUrl?: string
+  url?: string | undefined
+  description?: string | undefined
+  image?: string | undefined
+  datePublished?: string | undefined
+  dateModified?: string | undefined
+  authorName?: string | undefined
+  authorUrl?: string | undefined
 }
 
 export function generateArticleJsonLd(
@@ -194,3 +251,252 @@ export function generateBreadcrumbJsonLd(
     }),
   }
 }
+
+// Page-level generators for the schema.org blocks editors attach via
+// `metadata.jsonLd`. Plain options keep them CMS-independent.
+
+export interface FaqJsonLdItem {
+  question: string
+  answer: string
+}
+
+export function generateFaqJsonLd(
+  items: FaqJsonLdItem[]
+): WithContext<FAQPage> {
+  return {
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    mainEntity: items.map((item) => ({
+      "@type": "Question" as const,
+      name: item.question,
+      acceptedAnswer: {
+        "@type": "Answer" as const,
+        text: item.answer,
+      },
+    })),
+  }
+}
+
+export interface JobPostingJsonLdOptions {
+  title: string
+  description: string
+  datePosted: string
+  validThrough?: string | undefined
+  employmentType?: string | undefined
+  organizationName?: string | undefined
+  organizationUrl?: string | undefined
+  remote?: boolean | undefined
+  locality?: string | undefined
+  region?: string | undefined
+  country?: string | undefined
+}
+
+export function generateJobPostingJsonLd(
+  options: JobPostingJsonLdOptions
+): WithContext<JobPosting> {
+  const {
+    title,
+    description,
+    datePosted,
+    validThrough,
+    employmentType,
+    organizationName,
+    organizationUrl,
+    remote,
+    locality,
+    region,
+    country,
+  } = options
+  const orgUrl = organizationUrl ? resolveUrl(organizationUrl) : undefined
+
+  const hiringOrganization = organizationName
+    ? {
+        "@type": "Organization" as const,
+        name: organizationName,
+        ...(orgUrl && { url: orgUrl }),
+      }
+    : undefined
+
+  const jobLocation =
+    locality || region || country
+      ? {
+          "@type": "Place" as const,
+          address: {
+            "@type": "PostalAddress" as const,
+            ...(locality && { addressLocality: locality }),
+            ...(region && { addressRegion: region }),
+            ...(country && { addressCountry: country }),
+          },
+        }
+      : undefined
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "JobPosting",
+    title,
+    description,
+    datePosted,
+    ...(validThrough && { validThrough }),
+    ...(employmentType && { employmentType }),
+    ...(hiringOrganization && { hiringOrganization }),
+    ...(remote && { jobLocationType: "TELECOMMUTE" }),
+    ...(jobLocation && { jobLocation }),
+  }
+}
+
+export interface SoftwareApplicationJsonLdOptions {
+  name: string
+  description?: string | undefined
+  applicationCategory?: string | undefined
+  operatingSystem?: string | undefined
+  price?: number | undefined
+  currency?: string | undefined
+  url?: string | undefined
+  image?: string | undefined
+}
+
+export function generateSoftwareApplicationJsonLd(
+  options: SoftwareApplicationJsonLdOptions
+): WithContext<SoftwareApplication> {
+  const {
+    name,
+    description,
+    applicationCategory,
+    operatingSystem,
+    price,
+    currency,
+    url,
+    image,
+  } = options
+  const resolvedUrl = url ? resolveUrl(url) : undefined
+  const resolvedImage = image ? resolveUrl(image) : undefined
+
+  const offers =
+    typeof price === "number"
+      ? {
+          "@type": "Offer" as const,
+          price: price.toString(),
+          ...(currency && { priceCurrency: currency }),
+        }
+      : undefined
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "SoftwareApplication",
+    name,
+    ...(description && { description }),
+    ...(applicationCategory && { applicationCategory }),
+    ...(operatingSystem && { operatingSystem }),
+    ...(resolvedUrl && { url: resolvedUrl }),
+    ...(resolvedImage && { image: resolvedImage }),
+    ...(offers && { offers }),
+  }
+}
+
+export interface ItemListEntry {
+  name: string
+  url?: string | undefined
+}
+
+export interface ItemListJsonLdOptions {
+  name?: string | undefined
+  items: ItemListEntry[]
+}
+
+export function generateItemListJsonLd(
+  options: ItemListJsonLdOptions
+): WithContext<ItemList> {
+  const { name, items } = options
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "ItemList",
+    ...(name && { name }),
+    itemListElement: items.map((item, index) => {
+      const itemUrl = item.url ? resolveUrl(item.url) : undefined
+      return {
+        "@type": "ListItem" as const,
+        position: index + 1,
+        name: item.name,
+        ...(itemUrl && { url: itemUrl }),
+      }
+    }),
+  }
+}
+
+export interface EventJsonLdOptions {
+  name: string
+  description?: string | undefined
+  startDate: string
+  endDate?: string | undefined
+  locationName?: string | undefined
+  locationAddress?: string | undefined
+  url?: string | undefined
+  image?: string | undefined
+}
+
+export function generateEventJsonLd(
+  options: EventJsonLdOptions
+): WithContext<EventSchema> {
+  const {
+    name,
+    description,
+    startDate,
+    endDate,
+    locationName,
+    locationAddress,
+    url,
+    image,
+  } = options
+  const resolvedUrl = resolveUrl(url)
+  const resolvedImage = resolveUrl(image)
+
+  const location =
+    locationName || locationAddress
+      ? {
+          "@type": "Place" as const,
+          ...(locationName && { name: locationName }),
+          ...(locationAddress && { address: locationAddress }),
+        }
+      : undefined
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "Event",
+    name,
+    startDate,
+    ...(endDate && { endDate }),
+    ...(description && { description }),
+    ...(resolvedUrl && { url: resolvedUrl }),
+    ...(resolvedImage && { image: resolvedImage }),
+    ...(location && { location }),
+  }
+}
+
+export interface VideoJsonLdOptions {
+  name: string
+  description: string
+  thumbnail: string
+  uploadDate: string
+  contentUrl?: string | undefined
+  embedUrl?: string | undefined
+}
+
+export function generateVideoJsonLd(
+  options: VideoJsonLdOptions
+): WithContext<VideoObject> {
+  const { name, description, thumbnail, uploadDate, contentUrl, embedUrl } =
+    options
+  const resolvedThumbnail = resolveUrl(thumbnail) ?? thumbnail
+
+  return {
+    "@context": "https://schema.org",
+    "@type": "VideoObject",
+    name,
+    description,
+    thumbnailUrl: resolvedThumbnail,
+    uploadDate,
+    ...(contentUrl && { contentUrl }),
+    ...(embedUrl && { embedUrl }),
+  }
+}

package/src/templates/next-default/next.config.ts

@@ -5,6 +5,12 @@ const nextConfig: NextConfig = {
   reactStrictMode: true,
   reactCompiler: true,
   typedRoutes: true,
+  // Bundle the committed encrypted env files into serverless functions so
+  // instrumentation.ts can decrypt them at runtime. .env.keys is never listed
+  // (and is git/vercel-ignored); missing files are skipped.
+  outputFileTracingIncludes: {
+    "/**": ["./.env", "./.env.production", "./.env.preview"],
+  },
   turbopack: {
     rules: {
       "*.svg": {