create-nextblock 0.10.7 → 0.10.8

package/bin/create-nextblock.js

@@ -747,6 +747,10 @@ async function runSetupWizard(projectDir, projectName) {
     'CRON_SECRET=': `CRON_SECRET=${cronSecret}`,
     'DRAFT_MODE_SECRET=': `DRAFT_MODE_SECRET=${draftSecret}`,
     'REVALIDATE_SECRET_TOKEN=': `REVALIDATE_SECRET_TOKEN=${revalidateSecret}`,
+    // Build-time migration hook gate for standalone installs (Milestone 4): on a
+    // production build with POSTGRES_URL set, pending migrations are applied before
+    // `next build`. Skips gracefully when the DB is unreachable.
+    'NEXTBLOCK_BUILD_MIGRATE=': 'NEXTBLOCK_BUILD_MIGRATE=1',
     // The R2 public URL is consumed under two names (next/image remotePatterns + CSP, and
     // media URL resolution) — write the same value to both, matching setup.mjs.
     'NEXT_PUBLIC_R2_PUBLIC_URL=': `NEXT_PUBLIC_R2_PUBLIC_URL=${r2.publicBaseUrl}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-nextblock",
-  "version": "0.10.7",
+  "version": "0.10.8",
   "description": "",
   "main": "index.js",
   "bin": {

package/templates/nextblock-template/app/api/cms/check-updates/route.ts

@@ -0,0 +1,44 @@
+import { NextResponse } from 'next/server';
+import { createClient } from '@nextblock-cms/db/server';
+import { refreshUpstreamStatus } from '../../../../lib/updates/check-upstream';
+
+// Node runtime: the update checker reads the filesystem (.git / workflow detection) and
+// uses the service-role client. force-dynamic so it never gets statically cached.
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+
+/** Authenticated ADMIN gate, mirroring lib/full-backup/server.ts. */
+async function requireAdmin(): Promise<string | null> {
+  const supabase = createClient();
+  const {
+    data: { user },
+  } = await supabase.auth.getUser();
+  if (!user) return 'Not authenticated.';
+
+  const { data: profile, error } = await supabase
+    .from('profiles')
+    .select('role')
+    .eq('id', user.id)
+    .single();
+  if (error || profile?.role !== 'ADMIN') return 'Administrator role required.';
+  return null;
+}
+
+/**
+ * Admin-triggered upstream update check (Track B). Polls the GitHub Releases API,
+ * compares versions, and — on a standalone install — records a runtime_update_available
+ * alert. Returns the comparison either way so an admin "Check for updates" control can
+ * show the result inline.
+ */
+export async function POST() {
+  const denied = await requireAdmin();
+  if (denied) {
+    return NextResponse.json({ ok: false, error: denied }, { status: 401 });
+  }
+
+  const { update, conflicts, snapshot } = await refreshUpstreamStatus();
+  // The check itself succeeded as an operation even if a network call failed; surface any
+  // soft error in the body rather than 500ing the admin action.
+  const ok = update.ok && conflicts.ok;
+  return NextResponse.json({ ok, update, conflicts, snapshot }, { status: ok ? 200 : 502 });
+}

package/templates/nextblock-template/app/api/cron/reset-sandbox/sandboxResetSql.ts

@@ -8180,6 +8180,81 @@ $$;
 ALTER FUNCTION public.duplicate_block_definition(uuid) SECURITY INVOKER;
 
 
+-- >>> FROM: 00000000000036_setup_system_alerts.sql <<<
+-- System notification layer for the automated upstream-update architecture.
+--
+-- \`system_alerts\` is the single sink that every update track writes into:
+--   * Track A (the .github/workflows/nextblock-sync.yml GitHub Action) inserts a
+--     'merge_conflict' row via the Supabase REST API when an upstream merge can't be
+--     auto-resolved, so the CMS dashboard can point an operator at GitHub to sort it.
+--   * Track B (the runtime update engine, app/api/cms/check-updates) inserts a
+--     'runtime_update_available' row for non-git installs (npm create / local / Docker)
+--     with a download link to the latest verified release tarball.
+-- The dashboard banner (cms/layout.tsx -> SystemAlertsBanner) renders unresolved rows.
+--
+-- Writers always use the service-role key (REST API / getServiceRoleSupabaseClient),
+-- which bypasses RLS; RLS below only governs who can READ/RESOLVE from the dashboard.
+
+create table if not exists public.system_alerts (
+  id uuid primary key default gen_random_uuid(),
+  -- The notification kind. Constrained to the two tracks this system emits; widen the
+  -- CHECK in a later migration if new alert kinds are added.
+  alert_type text not null check (alert_type in ('merge_conflict', 'runtime_update_available')),
+  title text not null,
+  message text not null,
+  -- Structured context for deep-linking the banner CTA, e.g.
+  --   merge_conflict           -> { "repo": "owner/name", "branch": "...", "action_url": "https://github.com/owner/name/branches" }
+  --   runtime_update_available -> { "latest_version": "0.11.0", "download_url": "https://github.com/.../v0.11.0.tar.gz" }
+  metadata jsonb not null default '{}'::jsonb,
+  is_resolved boolean not null default false,
+  resolved_at timestamptz,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+
+comment on table public.system_alerts is 'System notifications for the automated upstream-update architecture (merge conflicts, runtime updates available). Written by service-role; read by ADMINs.';
+comment on column public.system_alerts.alert_type is 'One of: merge_conflict, runtime_update_available.';
+comment on column public.system_alerts.metadata is 'Structured deep-link context for the dashboard banner CTA (repo/branch/action_url or latest_version/download_url).';
+comment on column public.system_alerts.is_resolved is 'When true the alert is hidden from the dashboard banner.';
+
+-- Banner query: unresolved alerts, newest first.
+create index if not exists idx_system_alerts_unresolved
+  on public.system_alerts (is_resolved, created_at desc);
+
+-- Keep updated_at fresh on every mutation (same helper used across the schema).
+drop trigger if exists trg_system_alerts_updated_at on public.system_alerts;
+create trigger trg_system_alerts_updated_at
+  before update on public.system_alerts
+  for each row
+  execute function public.set_current_timestamp_updated_at();
+
+alter table public.system_alerts enable row level security;
+
+-- Only authenticated ADMINs may view alerts in the dashboard. WRITERs and the public
+-- anon role get zero rows (RLS default-deny: no policy applies to them).
+drop policy if exists system_alerts_select_admin on public.system_alerts;
+create policy system_alerts_select_admin
+  on public.system_alerts
+  for select
+  to authenticated
+  using ((select public.get_current_user_role()) = 'ADMIN');
+
+-- ADMINs may resolve (dismiss) alerts from the dashboard. Inserts are service-role only
+-- (RLS-bypassing), so there is intentionally no INSERT policy.
+drop policy if exists system_alerts_update_admin on public.system_alerts;
+create policy system_alerts_update_admin
+  on public.system_alerts
+  for update
+  to authenticated
+  using ((select public.get_current_user_role()) = 'ADMIN')
+  with check ((select public.get_current_user_role()) = 'ADMIN');
+
+-- Base table privileges (RLS still filters rows on top of these). Mirrors the grant
+-- model the rest of the schema uses; service_role keeps full access for the writers.
+grant select, update on public.system_alerts to authenticated;
+grant all on public.system_alerts to service_role;
+
+
   -- Step D: Anchor preserved profiles
   INSERT INTO public.profiles (id, updated_at, full_name, avatar_url, website, role)
   SELECT preserved_user.id, NULL, NULL, NULL, NULL, 'ADMIN'

package/templates/nextblock-template/app/cms/CmsClientLayout.tsx

@@ -12,6 +12,7 @@ import {
   ShieldCheck, Cookie, LineChart, Mail, UserPlus, SlidersHorizontal,
 } from "lucide-react"
 import TwoFactorReminderBanner from "./components/TwoFactorReminderBanner"
+import SystemAlertsBanner, { type SystemAlertItem } from "./components/SystemAlertsBanner"
 import { Button } from "@nextblock-cms/ui"
 import { Avatar, AvatarFallback, AvatarImage } from "@nextblock-cms/ui"
 import { cn } from "@nextblock-cms/utils"
@@ -117,11 +118,13 @@ export default function CmsClientLayout({
   isCortexAiActive = false,
   isEcommerceActive = false,
   showTwoFactorReminder = false,
+  systemAlerts = [],
 }: {
   children: ReactNode,
   isCortexAiActive?: boolean,
   isEcommerceActive?: boolean,
   showTwoFactorReminder?: boolean,
+  systemAlerts?: SystemAlertItem[],
 }) {
   const isSandbox = process.env.NEXT_PUBLIC_IS_SANDBOX === 'true';
   const { user, profile, role, isLoading, isAdmin, isWriter } = useAuth();
@@ -498,6 +501,7 @@ export default function CmsClientLayout({
         </header>
         <main className="flex-1 min-h-0 w-full overflow-y-auto overscroll-contain px-6 pt-6 pb-20 scroll-pb-24 md:pb-24">
             {showTwoFactorReminder && <TwoFactorReminderBanner />}
+            <SystemAlertsBanner alerts={systemAlerts} />
             {children}
         </main>
       </div>

package/templates/nextblock-template/app/cms/components/SystemAlertsBanner.tsx

@@ -0,0 +1,112 @@
+'use client';
+
+import { useState, useTransition } from 'react';
+import { AlertTriangle, ArrowUpCircle, ExternalLink, X } from 'lucide-react';
+import { Button } from '@nextblock-cms/ui';
+import { resolveSystemAlert } from './system-alerts-actions';
+
+export interface SystemAlertItem {
+  id: string;
+  alert_type: string;
+  title: string;
+  message: string;
+  metadata: Record<string, unknown> | null;
+}
+
+function readString(metadata: Record<string, unknown> | null, key: string): string | undefined {
+  const value = metadata?.[key];
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+/**
+ * Dashboard banner for unresolved system_alerts. High-visibility, developer-facing:
+ *   - merge_conflict           -> amber, links to GitHub to resolve the sync (Track A).
+ *   - runtime_update_available -> indigo, links to the release download (Track B).
+ * Dismissing persists is_resolved=true (ADMIN-only via RLS) and hides the alert.
+ */
+export default function SystemAlertsBanner({ alerts }: { alerts: SystemAlertItem[] }) {
+  const [dismissed, setDismissed] = useState<Set<string>>(new Set());
+  const [isPending, startTransition] = useTransition();
+
+  const visible = alerts.filter((a) => !dismissed.has(a.id));
+  if (visible.length === 0) return null;
+
+  const dismiss = (id: string) => {
+    setDismissed((prev) => new Set(prev).add(id));
+    startTransition(() => {
+      void resolveSystemAlert(id);
+    });
+  };
+
+  return (
+    <div className="mb-6 flex flex-col gap-3">
+      {visible.map((alert) => {
+        const isConflict = alert.alert_type === 'merge_conflict';
+        const Icon = isConflict ? AlertTriangle : ArrowUpCircle;
+
+        const tone = isConflict
+          ? 'border-amber-300 bg-amber-50 text-amber-900 dark:border-amber-700/60 dark:bg-amber-900/20 dark:text-amber-200'
+          : 'border-indigo-300 bg-indigo-50 text-indigo-900 dark:border-indigo-700/60 dark:bg-indigo-900/20 dark:text-indigo-200';
+        const ctaBorder = isConflict
+          ? 'border-amber-400 dark:border-amber-600'
+          : 'border-indigo-400 dark:border-indigo-600';
+
+        // Track A (conflict) deep-links to GitHub; Track B (update) to the download.
+        const primaryHref = isConflict
+          ? readString(alert.metadata, 'action_url')
+          : readString(alert.metadata, 'download_url');
+        const primaryLabel = isConflict ? 'Resolve on GitHub' : 'Download latest';
+        const secondaryHref = isConflict
+          ? readString(alert.metadata, 'run_url')
+          : readString(alert.metadata, 'html_url');
+        const secondaryLabel = isConflict ? 'View workflow run' : 'Release notes';
+
+        return (
+          <div
+            key={alert.id}
+            className={`flex items-start gap-3 rounded-lg border px-4 py-3 ${tone}`}
+            role="alert"
+          >
+            <Icon className="mt-0.5 h-5 w-5 shrink-0" />
+            <div className="min-w-0 flex-1">
+              <p className="text-sm font-medium">{alert.title}</p>
+              <p className="text-xs opacity-90">{alert.message}</p>
+              {(primaryHref || secondaryHref) && (
+                <div className="mt-2 flex flex-wrap items-center gap-2">
+                  {primaryHref && (
+                    <Button asChild size="sm" variant="outline" className={ctaBorder}>
+                      <a href={primaryHref} target="_blank" rel="noopener noreferrer">
+                        {primaryLabel}
+                        <ExternalLink className="ml-1.5 h-3.5 w-3.5" />
+                      </a>
+                    </Button>
+                  )}
+                  {secondaryHref && (
+                    <a
+                      href={secondaryHref}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      className="text-xs font-medium underline underline-offset-2 opacity-80 hover:opacity-100"
+                    >
+                      {secondaryLabel}
+                    </a>
+                  )}
+                </div>
+              )}
+            </div>
+            <Button
+              variant="ghost"
+              size="icon"
+              onClick={() => dismiss(alert.id)}
+              disabled={isPending}
+              aria-label="Dismiss alert"
+              className="h-8 w-8 shrink-0"
+            >
+              <X className="h-4 w-4" />
+            </Button>
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/templates/nextblock-template/app/cms/components/system-alerts-actions.ts

@@ -0,0 +1,31 @@
+'use server';
+
+import { revalidatePath } from 'next/cache';
+import { createClient } from '@nextblock-cms/db/server';
+
+/**
+ * Mark a system alert resolved (dismiss it from the dashboard banner). Runs as the
+ * signed-in user; the system_alerts UPDATE RLS policy restricts this to ADMINs, so a
+ * non-admin caller simply updates zero rows. Inserts are service-role only.
+ */
+export async function resolveSystemAlert(
+  id: string,
+): Promise<{ ok: boolean; error?: string }> {
+  if (!id) return { ok: false, error: 'Missing alert id.' };
+
+  const supabase = createClient();
+  const {
+    data: { user },
+  } = await supabase.auth.getUser();
+  if (!user) return { ok: false, error: 'Not authenticated.' };
+
+  const { error } = await supabase
+    .from('system_alerts')
+    .update({ is_resolved: true, resolved_at: new Date().toISOString() })
+    .eq('id', id);
+
+  if (error) return { ok: false, error: error.message };
+
+  revalidatePath('/cms', 'layout');
+  return { ok: true };
+}

package/templates/nextblock-template/app/cms/dashboard/components/DashboardOnboarding.tsx

@@ -103,10 +103,17 @@ export default function DashboardOnboarding({
               </div>
               {!step.done && step.key !== 'admin' && (
                 <Button asChild variant="outline" size="sm" className="shrink-0">
-                  <Link href={step.href}>
-                    Set up
-                    <ArrowRight className="ml-1 h-3.5 w-3.5" />
-                  </Link>
+                  {step.isExternal ? (
+                    <a href={step.href} target="_blank" rel="noopener noreferrer">
+                      Set up
+                      <ArrowRight className="ml-1 h-3.5 w-3.5" />
+                    </a>
+                  ) : (
+                    <Link href={step.href}>
+                      Set up
+                      <ArrowRight className="ml-1 h-3.5 w-3.5" />
+                    </Link>
+                  )}
                 </Button>
               )}
             </li>

package/templates/nextblock-template/app/cms/layout.tsx

@@ -1,8 +1,39 @@
 import 'katex/dist/katex.min.css';
 import { redirect } from 'next/navigation';
+import { after } from 'next/server';
 import CmsClientLayout from "./CmsClientLayout";
-import { verifyPackageOnline } from '@nextblock-cms/db/server';
+import { verifyPackageOnline, createClient } from '@nextblock-cms/db/server';
 import { evaluateTwoFactor, getStaffTwoFactorReminder } from '../../lib/auth/twoFactor';
+import { maybeRefreshUpstreamStatus } from '../../lib/updates/check-upstream';
+import type { SystemAlertItem } from './components/SystemAlertsBanner';
+
+/**
+ * Unresolved system alerts for the dashboard banner. Runs as the signed-in user, so the
+ * system_alerts SELECT RLS policy returns rows only for ADMINs (WRITERs get an empty
+ * list). Best-effort: any failure (e.g. the table not yet migrated) yields no banner.
+ */
+async function getUnresolvedSystemAlerts(): Promise<SystemAlertItem[]> {
+  try {
+    const supabase = createClient();
+    const { data, error } = await supabase
+      .from('system_alerts')
+      .select('id, alert_type, title, message, metadata')
+      .eq('is_resolved', false)
+      .in('alert_type', ['merge_conflict', 'runtime_update_available'])
+      .order('created_at', { ascending: false })
+      .limit(20);
+    if (error || !data) return [];
+    return data.map((a) => ({
+      id: a.id,
+      alert_type: a.alert_type,
+      title: a.title,
+      message: a.message,
+      metadata: (a.metadata ?? null) as Record<string, unknown> | null,
+    }));
+  } catch {
+    return [];
+  }
+}
 
 export default async function CmsLayout({
   children,
@@ -16,17 +47,25 @@ export default async function CmsLayout({
     redirect('/two-factor?redirect_to=/cms/dashboard');
   }
 
-  const [isEcommerceActive, isCortexAiActive, showTwoFactorReminder] = await Promise.all([
-    verifyPackageOnline('ecommerce'),
-    verifyPackageOnline('cortex-ai'),
-    getStaffTwoFactorReminder(),
-  ]);
+  const [isEcommerceActive, isCortexAiActive, showTwoFactorReminder, systemAlerts] =
+    await Promise.all([
+      verifyPackageOnline('ecommerce'),
+      verifyPackageOnline('cortex-ai'),
+      getStaffTwoFactorReminder(),
+      getUnresolvedSystemAlerts(),
+    ]);
+
+  // After the response, refresh upstream update/conflict status in the background
+  // (throttled to ~6h, see maybeRefreshUpstreamStatus). This keeps the banner current
+  // without a cron — so it works on Vercel Hobby (limited crons) and self-hosted alike.
+  after(() => maybeRefreshUpstreamStatus());
 
   return (
     <CmsClientLayout
       isCortexAiActive={isCortexAiActive}
       isEcommerceActive={isEcommerceActive}
       showTwoFactorReminder={showTwoFactorReminder}
+      systemAlerts={systemAlerts}
     >
       {children}
     </CmsClientLayout>

package/templates/nextblock-template/docs/12-VERCEL-DEPLOYMENT.md

@@ -158,3 +158,12 @@ see it scheduled.
 
 Visit the deployment URL — it redirects to `/setup` until the first admin exists.
 Complete the wizard, then sign in at `/cms/dashboard`.
+
+**Turn on automatic updates.** The 1-click deploy forks NextBlock into your Git provider
+and ships a daily upstream-sync GitHub Action — but GitHub **disables Actions on a fresh
+fork** until you enable them once (your repo → **Actions** tab → *"I understand my
+workflows, go ahead and enable them."*). The dashboard onboarding checklist reminds you and
+links straight there. We recommend a **public** fork (fully zero-config); a **private**
+fork additionally needs a `NEXTBLOCK_GITHUB_TOKEN` env var for the in-CMS conflict banner.
+Full details — both tracks, conflict handling, and build-time migrations — are in
+[docs/13](./13-STAYING-UP-TO-DATE.md).

package/templates/nextblock-template/docs/13-STAYING-UP-TO-DATE.md

@@ -0,0 +1,115 @@
+# 13 · Staying Up to Date (Automated Upstream Updates)
+
+NextBlock keeps your instance in sync with the upstream project
+(`nextblock-cms/nextblock`) with **as little manual work as possible**. How updates
+arrive depends on how you deployed, and the system auto-detects which path applies:
+
+| Install type | Track | How updates arrive |
+| :--- | :--- | :--- |
+| Vercel 1-click / GitHub fork (git-backed) | **A** | A daily GitHub Action merges upstream and pushes to your deploy branch (→ Vercel CD). |
+| `npm create nextblock` / local clone / Docker image (standalone) | **B** | The CMS checks GitHub Releases and shows a "download the new version" banner. |
+
+Both tracks surface their status in the CMS through a dashboard banner backed by the
+`system_alerts` table (migration `00000000000036`). Reads are ADMIN-only (RLS).
+
+---
+
+## Track A — Git-backed installs (Vercel 1-click, GitHub forks)
+
+The workflow lives at [`.github/workflows/nextblock-sync.yml`](../.github/workflows/nextblock-sync.yml).
+It runs **daily at 00:00 UTC** and on demand (**Actions → NextBlock Upstream Sync → Run
+workflow**). Each run:
+
+1. Merges the upstream release branch into your deploy branch.
+2. **Clean merge** → commits and pushes to your branch, which triggers a normal Vercel
+   deployment. Any open conflict issue is auto-closed.
+3. **Conflict** → aborts the merge and opens (or updates) a GitHub Issue labeled
+   `nextblock-sync-conflict`. The CMS mirrors that issue into an **amber banner** on the
+   dashboard with a link to resolve it. Once you resolve and **close the issue**, the
+   banner clears automatically.
+
+### One-time step: enable GitHub Actions
+
+GitHub **disables Actions on a freshly-forked repo** until you turn them on once:
+
+> Your repo → **Actions** tab → **"I understand my workflows, go ahead and enable them."**
+
+The dashboard onboarding checklist reminds you of this ("Enable automatic updates
+(GitHub Actions)") and links straight to your repo's Actions tab. The step marks itself
+done once the workflow has run at least once.
+
+### No GitHub secrets required (public forks)
+
+The conflict signal uses the **`GITHUB_TOKEN` that GitHub provides to every workflow
+automatically** — you do **not** add any Supabase secret to GitHub. The app writes the
+dashboard alert itself using the Supabase key it already has, and reads your repo's
+conflict issues over the public GitHub API.
+
+> **We recommend forking to a _public_ repository** — it's fully zero-config.
+
+### Private forks
+
+If your fork is **private**, the public GitHub API can't read its issues, so add **one**
+environment variable to your deployment (Vercel project → Settings → Environment
+Variables, or your `.env`):
+
+| Variable | Value |
+| :--- | :--- |
+| `NEXTBLOCK_GITHUB_TOKEN` | A GitHub token with **read access to issues** on your fork (a fine-grained PAT scoped to the repo, or a classic token with `repo`). |
+
+With that set, the dashboard conflict banner works on private forks too. (The workflow
+itself still needs no extra secret — `GITHUB_TOKEN` covers it either way.)
+
+### How the dashboard stays current (no cron)
+
+The CMS refreshes update/conflict status **in the background after a dashboard page
+loads** (throttled to ~6 hours), so it works on Vercel's Hobby plan without consuming a
+cron slot. Admins can also force a check immediately:
+
+```
+POST /api/cms/check-updates      # admin-only; returns the version + conflict status
+```
+
+---
+
+## Track B — Standalone installs (npm create / local / Docker)
+
+These installs aren't wired to a GitHub Action, so NextBlock checks the **GitHub Releases
+API** and, when a newer release exists, records a `runtime_update_available` alert — an
+**indigo banner** on the dashboard with a direct **download link** to the release tarball.
+Updating is manual by design: download the archive, replace your files, and update
+dependencies (`npm install`). The same admin check endpoint above triggers a check on
+demand.
+
+---
+
+## Schema stays in step with deploys (build-time migrations)
+
+So a new version's code never runs against an old schema, a build-time hook
+([`apps/nextblock/tools/build-migrate.mjs`](../apps/nextblock/tools/build-migrate.mjs))
+applies pending, forward-only migrations **before** `next build`:
+
+- **Vercel:** runs automatically when `VERCEL_ENV=production`; **preview/development
+  builds are skipped** so they never touch live data.
+- **Standalone / local / Docker:** gated on `NEXTBLOCK_BUILD_MIGRATE=1`, which the
+  `/setup` wizard and the create/Docker setup scripts write into your env automatically.
+
+It is **non-destructive and never breaks the build** — if the database is unreachable it
+logs a warning and continues. Migrations are tracked in `supabase_migrations.schema_migrations`,
+identically to the Supabase CLI.
+
+> **Edge case:** if your project's migration history is empty/inconsistent, the hook skips
+> rather than risk misapplying. Run `npm run db:migrate:repair-history` then
+> `npm run db:migrate` once to reconcile (see [docs/04](./04-DATABASE-AND-AUTH.md)).
+
+---
+
+## Quick reference
+
+| You want… | Do this |
+| :--- | :--- |
+| Fully hands-off updates | Fork **public**, deploy on Vercel, **enable Actions** once. |
+| Conflict banners on a **private** fork | Also set `NEXTBLOCK_GITHUB_TOKEN`. |
+| To update a **standalone** install | Watch for the dashboard banner → download → replace → `npm install`. |
+| To force an update check now | Dashboard (admin) → it polls in the background; or `POST /api/cms/check-updates`. |
+| To resolve a sync conflict | Open the linked GitHub issue, merge upstream locally, fix, push, close the issue. |

package/templates/nextblock-template/lib/onboarding/status.ts

@@ -5,6 +5,9 @@ import { createClient } from '@nextblock-cms/db/server';
 import { getStoreConfigStatus } from '@nextblock-cms/ecommerce/server';
 import { getEmailPublicSettings } from '../config/email-settings';
 import { getPrivacySettings } from '../privacy/settings';
+import { detectChannel } from '../setup/env-status';
+import { getSystemConfiguration } from '../setup/system-config';
+import { selfActionsUrl } from '../updates/repo-identity';
 
 export type OnboardingStep = {
   key: string;
@@ -13,6 +16,8 @@ export type OnboardingStep = {
   href: string;
   done: boolean;
   optional: boolean;
+  /** When true, render the CTA as an external link (new tab) instead of an in-app route. */
+  isExternal?: boolean;
 };
 
 export type OnboardingStatus = {
@@ -161,6 +166,35 @@ export async function getOnboardingStatus(opts: {
     });
   }
 
+  // Git-backed (Vercel 1-click / fork) installs: remind the operator to enable GitHub
+  // Actions so the upstream sync workflow can run. "done" flips once the background poll
+  // (maybeRefreshUpstreamStatus) has seen the workflow run at least once.
+  if (detectChannel() === 'vercel') {
+    let actionsActive = false;
+    try {
+      const config = await getSystemConfiguration();
+      const upstream = config.settings?.['upstream_status'] as
+        | { actions_active?: boolean }
+        | undefined;
+      actionsActive = upstream?.actions_active === true;
+    } catch {
+      actionsActive = false;
+    }
+    steps.push({
+      key: 'github-actions',
+      title: 'Enable automatic updates (GitHub Actions)',
+      description: actionsActive
+        ? 'Automated upstream sync is active for your repository.'
+        : 'Turn on GitHub Actions in your forked repo so NextBlock can merge upstream updates for you.',
+      href:
+        selfActionsUrl() ??
+        'https://docs.github.com/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/disabling-and-enabling-a-workflow',
+      done: actionsActive,
+      optional: true,
+      isExternal: true,
+    });
+  }
+
   const completed = steps.filter((s) => s.done).length;
 
   return {

package/templates/nextblock-template/lib/setup/actions.ts

@@ -182,6 +182,10 @@ export async function saveSupabaseConnection(input: ConnectionInput): Promise<Ac
     NEXT_PUBLIC_SUPABASE_URL: supabaseUrl,
     NEXT_PUBLIC_SUPABASE_ANON_KEY: anonKey,
     SUPABASE_SERVICE_ROLE_KEY: serviceRoleKey,
+    // Enable the build-time migration hook for this install (Milestone 4). On Vercel
+    // VERCEL_ENV gates it instead; off-Vercel (local / Docker / standalone) production
+    // builds read this flag. Only written to a local-writable .env (no-op on Vercel).
+    NEXTBLOCK_BUILD_MIGRATE: '1',
   };
   if (input.siteUrl?.trim()) values.NEXT_PUBLIC_URL = input.siteUrl.trim();
   if (input.postgresUrl?.trim()) values.POSTGRES_URL = input.postgresUrl.trim();