create-nextblock 0.10.9 → 0.11.1

package/package.json

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

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

@@ -0,0 +1,117 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Check, ExternalLink, Github, Loader2 } from 'lucide-react';
+import { Button } from '@nextblock-cms/ui';
+import { startGithubConnect, pollGithubConnect } from './github-connect-actions';
+
+type Phase = 'idle' | 'starting' | 'awaiting' | 'installed' | 'error';
+
+/**
+ * One-click "Connect GitHub" via the OAuth device flow. On authorization, the server
+ * installs the upstream-sync workflow into the repo (the file Vercel's clone strips).
+ * No PAT, no env config — the public client id is baked into the app.
+ */
+export default function ConnectGitHubButton() {
+  const [phase, setPhase] = useState<Phase>('idle');
+  const [userCode, setUserCode] = useState('');
+  const [verificationUri, setVerificationUri] = useState('https://github.com/login/device');
+  const [error, setError] = useState('');
+
+  // Cancel any in-flight polling when the component unmounts.
+  const activeRef = useRef(false);
+  useEffect(() => {
+    activeRef.current = true;
+    return () => {
+      activeRef.current = false;
+    };
+  }, []);
+
+  const poll = useCallback(async (intervalMs: number) => {
+    if (!activeRef.current) return;
+    const result = await pollGithubConnect();
+    if (!activeRef.current) return;
+
+    if (result.status === 'installed') {
+      setPhase('installed');
+      return;
+    }
+    if (result.status === 'error') {
+      setError(result.error);
+      setPhase('error');
+      return;
+    }
+    // pending — back off a little on slow_down, then poll again.
+    const next = result.slowDown ? intervalMs + 5000 : intervalMs;
+    setTimeout(() => void poll(next), next);
+  }, []);
+
+  const connect = useCallback(async () => {
+    setError('');
+    setPhase('starting');
+    const res = await startGithubConnect();
+    if (!activeRef.current) return;
+    if (!res.ok || !res.userCode) {
+      setError(res.error ?? 'Could not start GitHub connect.');
+      setPhase('error');
+      return;
+    }
+    setUserCode(res.userCode);
+    if (res.verificationUri) setVerificationUri(res.verificationUri);
+    setPhase('awaiting');
+    const intervalMs = Math.max((res.interval ?? 5) + 1, 5) * 1000;
+    setTimeout(() => void poll(intervalMs), intervalMs);
+  }, [poll]);
+
+  if (phase === 'installed') {
+    return (
+      <div className="flex items-center gap-1.5 text-sm font-medium text-emerald-600 dark:text-emerald-400">
+        <Check className="h-4 w-4" />
+        Connected — installing…
+      </div>
+    );
+  }
+
+  if (phase === 'awaiting') {
+    return (
+      <div className="flex flex-col items-end gap-1.5 text-right">
+        <Button asChild size="sm" variant="outline">
+          <a href={verificationUri} target="_blank" rel="noopener noreferrer">
+            Authorize on GitHub
+            <ExternalLink className="ml-1 h-3.5 w-3.5" />
+          </a>
+        </Button>
+        <p className="text-xs text-muted-foreground">
+          Enter code{' '}
+          <span className="font-mono font-semibold tracking-wider text-foreground">{userCode}</span>
+        </p>
+        <p className="flex items-center gap-1 text-xs text-muted-foreground">
+          <Loader2 className="h-3 w-3 animate-spin" />
+          Waiting for authorization…
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex flex-col items-end gap-1">
+      <Button
+        size="sm"
+        variant="outline"
+        onClick={() => void connect()}
+        disabled={phase === 'starting'}
+        className="shrink-0"
+      >
+        {phase === 'starting' ? (
+          <Loader2 className="mr-1 h-3.5 w-3.5 animate-spin" />
+        ) : (
+          <Github className="mr-1 h-3.5 w-3.5" />
+        )}
+        {phase === 'starting' ? 'Starting…' : 'Connect GitHub'}
+      </Button>
+      {phase === 'error' && (
+        <p className="max-w-[16rem] text-right text-xs text-red-600 dark:text-red-400">{error}</p>
+      )}
+    </div>
+  );
+}

package/templates/nextblock-template/app/cms/components/github-connect-actions.ts

@@ -0,0 +1,98 @@
+'use server';
+
+import { cookies } from 'next/headers';
+import { revalidatePath } from 'next/cache';
+import { createClient } from '@nextblock-cms/db/server';
+import {
+  startDeviceFlow,
+  pollDeviceFlowOnce,
+  installSyncWorkflow,
+} from '../../../lib/updates/github-device';
+
+const DEVICE_COOKIE = 'nb_gh_device';
+
+/** ADMIN gate, mirroring the rest of the CMS server entry points. */
+async function isAdmin(): Promise<boolean> {
+  const supabase = createClient();
+  const {
+    data: { user },
+  } = await supabase.auth.getUser();
+  if (!user) return false;
+  const { data: profile, error } = await supabase
+    .from('profiles')
+    .select('role')
+    .eq('id', user.id)
+    .single();
+  return !error && profile?.role === 'ADMIN';
+}
+
+export interface StartConnectResult {
+  ok: boolean;
+  userCode?: string;
+  verificationUri?: string;
+  interval?: number;
+  expiresIn?: number;
+  error?: string;
+}
+
+/** Begin the device flow; stash the device code in an httpOnly cookie for polling. */
+export async function startGithubConnect(): Promise<StartConnectResult> {
+  if (!(await isAdmin())) return { ok: false, error: 'Administrator role required.' };
+
+  try {
+    const flow = await startDeviceFlow();
+    const store = await cookies();
+    store.set(DEVICE_COOKIE, flow.deviceCode, {
+      httpOnly: true,
+      secure: process.env.NODE_ENV === 'production',
+      sameSite: 'lax',
+      path: '/cms',
+      maxAge: flow.expiresIn,
+    });
+    return {
+      ok: true,
+      userCode: flow.userCode,
+      verificationUri: flow.verificationUri,
+      interval: flow.interval,
+      expiresIn: flow.expiresIn,
+    };
+  } catch (caught) {
+    return { ok: false, error: caught instanceof Error ? caught.message : 'Could not start GitHub connect.' };
+  }
+}
+
+export type PollConnectResult =
+  | { status: 'installed'; htmlUrl?: string }
+  | { status: 'pending'; slowDown?: boolean }
+  | { status: 'error'; error: string };
+
+/** Poll once; on authorization, install the workflow and clear the device cookie. */
+export async function pollGithubConnect(): Promise<PollConnectResult> {
+  if (!(await isAdmin())) return { status: 'error', error: 'Administrator role required.' };
+
+  const store = await cookies();
+  const deviceCode = store.get(DEVICE_COOKIE)?.value;
+  if (!deviceCode) {
+    return { status: 'error', error: 'Connect session expired — start again.' };
+  }
+
+  const poll = await pollDeviceFlowOnce(deviceCode);
+
+  if (poll.status === 'pending') return { status: 'pending', slowDown: poll.slowDown };
+
+  if (poll.status === 'authorized') {
+    const install = await installSyncWorkflow(poll.token);
+    store.delete({ name: DEVICE_COOKIE, path: '/cms' });
+    if (install.ok) {
+      revalidatePath('/cms', 'layout');
+      return { status: 'installed', htmlUrl: install.htmlUrl };
+    }
+    return { status: 'error', error: install.error ?? 'Could not install the workflow.' };
+  }
+
+  // expired / denied / error — clear the session.
+  store.delete({ name: DEVICE_COOKIE, path: '/cms' });
+  if (poll.status === 'expired') return { status: 'error', error: 'Authorization timed out — start again.' };
+  if (poll.status === 'denied') return { status: 'error', error: 'Authorization was declined.' };
+  return { status: 'error', error: poll.error };
+}

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

@@ -12,6 +12,7 @@ import {
 } from '@nextblock-cms/ui';
 import { ArrowRight, CheckCircle2, Circle, X } from 'lucide-react';
 import type { OnboardingStatus } from '../../../../lib/onboarding/status';
+import ConnectGitHubButton from '../../components/ConnectGitHubButton';
 
 export default function DashboardOnboarding({
   status,
@@ -102,19 +103,23 @@ export default function DashboardOnboarding({
                 <p className="text-xs text-muted-foreground">{step.description}</p>
               </div>
               {!step.done && step.key !== 'admin' && (
-                <Button asChild variant="outline" size="sm" className="shrink-0">
-                  {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>
+                step.connectGithub ? (
+                  <ConnectGitHubButton />
+                ) : (
+                  <Button asChild variant="outline" size="sm" className="shrink-0">
+                    {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/docs/12-VERCEL-DEPLOYMENT.md

@@ -159,11 +159,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).
+**Automatic updates.** The 1-click deploy creates a **new repository you own** (a copy —
+*not* a GitHub fork) and ships a daily upstream-sync GitHub Action. Because it's your own
+repo, **Actions are enabled by default — there's nothing to turn on**; the workflow runs
+once it's on your **default branch**, and the dashboard onboarding step completes
+automatically when GitHub registers it. We recommend keeping the repo **public** (fully
+zero-config); a **private** repo additionally needs a `NEXTBLOCK_GITHUB_TOKEN` env var for
+the in-CMS conflict banner. (Only a *manually-created GitHub fork* has Actions disabled
+until you enable them on the Actions tab.) 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

@@ -28,15 +28,44 @@ workflow**). Each run:
    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.
+### One-click install (Connect GitHub)
+
+Vercel's 1-click deploy creates your repo through an integration whose token lacks the
+GitHub **`workflow`** scope, so GitHub **strips `.github/workflows/`** from the copy — your
+new repo won't have the sync workflow even though the template ships it. To fix that with no
+token to create, the dashboard onboarding step shows a **Connect GitHub** button:
+
+1. Click **Connect GitHub** — a short code appears.
+2. Click **Authorize on GitHub**, enter the code, approve.
+3. NextBlock installs `.github/workflows/nextblock-sync.yml` into your repo for you, and the
+   step turns green.
+
+This uses GitHub's **device flow** — no token to create, no per-site callback, nothing to
+configure (the public client id ships with NextBlock). The authorization requests the
+`repo` + `workflow` scopes because GitHub requires them to write a workflow file; NextBlock
+uses the grant once to install the file and does **not** store it. Revoke it anytime at
+GitHub → **Settings → Applications**.
+
+### Do you need to enable GitHub Actions?
+
+It depends on how the repository was created:
+
+- **Vercel 1-click deploy** creates a **new repository you own** (a copy, *not* a GitHub
+  fork). GitHub **enables Actions by default** on repos you own — **there's nothing to turn
+  on**. The sync workflow runs automatically once it lands on your repo's **default branch**.
+- **A manual GitHub _fork_** (the "Fork" button) has Actions **disabled** by default. Enable
+  them once: your repo → **Actions** tab → **"I understand my workflows, go ahead and enable
+  them."**
+
+> **Seeing GitHub's "Get started with Actions / choose a workflow" page?** That only means
+> your Actions tab is **empty** — `.github/workflows/nextblock-sync.yml` isn't on your
+> **default branch** yet (scheduled workflows only run from the default branch). Once it is,
+> the tab shows **NextBlock Upstream Sync** with a **Run workflow** button. There is no
+> separate "enable" button on an owned repo because Actions are already on.
+
+The dashboard onboarding step ("Automatic updates (GitHub Actions)") links to **Settings →
+Actions** — where you can confirm Actions are allowed — and completes itself once GitHub
+reports the sync workflow as active.
 
 ### No GitHub secrets required (public forks)
 

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

@@ -7,7 +7,8 @@ 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';
+import { selfActionsSettingsUrl } from '../updates/repo-identity';
+import { isGithubConnectAvailable } from '../updates/github-device';
 
 export type OnboardingStep = {
   key: string;
@@ -18,6 +19,8 @@ export type OnboardingStep = {
   optional: boolean;
   /** When true, render the CTA as an external link (new tab) instead of an in-app route. */
   isExternal?: boolean;
+  /** When true, render the device-flow "Connect GitHub" control instead of a link. */
+  connectGithub?: boolean;
 };
 
 export type OnboardingStatus = {
@@ -180,18 +183,22 @@ export async function getOnboardingStatus(opts: {
     } catch {
       actionsActive = false;
     }
+    const canConnect = !actionsActive && isGithubConnectAvailable();
     steps.push({
       key: 'github-actions',
-      title: 'Enable automatic updates (GitHub Actions)',
+      title: '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.',
+        ? 'The daily upstream-sync workflow is active for your repository.'
+        : canConnect
+          ? 'Connect GitHub to install the upstream-sync workflow into your repo — Vercel’s 1-click deploy can’t copy it automatically.'
+          : 'Vercel deploys have GitHub Actions on by default — this completes once GitHub registers the sync workflow on your default branch. A manually forked repo needs Actions enabled under Settings → Actions.',
       href:
-        selfActionsUrl() ??
-        'https://docs.github.com/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/disabling-and-enabling-a-workflow',
+        selfActionsSettingsUrl() ??
+        'https://github.com/nextblock-cms/nextblock/blob/HEAD/docs/13-STAYING-UP-TO-DATE.md',
       done: actionsActive,
       optional: true,
       isExternal: true,
+      connectGithub: canConnect,
     });
   }
 

package/templates/nextblock-template/lib/updates/check-upstream.ts

@@ -264,10 +264,13 @@ export async function checkForSyncConflicts(): Promise<SyncConflictResult> {
     fetchError = caught instanceof Error ? caught.message : 'Could not reach the GitHub issues API.';
   }
 
-  // 2) Has the sync workflow ever run? (drives the onboarding "Actions enabled" state)
+  // 2) Is the sync workflow present AND enabled? (drives the onboarding "Actions" step)
+  // We check the workflow's `state` rather than whether it has *run*: a healthy Vercel
+  // deploy has Actions enabled by default, so the workflow is 'active' immediately — no
+  // need to wait up to 24h for the first daily cron before the step completes.
   let actionsActive = false;
   try {
-    const wfUrl = `https://api.github.com/repos/${self.owner}/${self.repo}/actions/workflows/nextblock-sync.yml/runs?per_page=1`;
+    const wfUrl = `https://api.github.com/repos/${self.owner}/${self.repo}/actions/workflows/nextblock-sync.yml`;
     const res = await fetch(wfUrl, {
       headers: githubHeaders(),
       signal: AbortSignal.timeout(15_000),
@@ -275,7 +278,7 @@ export async function checkForSyncConflicts(): Promise<SyncConflictResult> {
     });
     if (res.ok) {
       const data = await res.json();
-      actionsActive = (data?.total_count ?? 0) > 0;
+      actionsActive = data?.state === 'active';
     }
   } catch {
     /* best-effort */

package/templates/nextblock-template/lib/updates/github-device.ts

@@ -0,0 +1,206 @@
+import 'server-only';
+// GitHub OAuth Device Flow — the one auth model that works across every NextBlock install
+// domain without a per-site callback URL or a user-created PAT. Powers the onboarding
+// "Connect GitHub" button, which installs the upstream-sync workflow into the user's repo
+// (Vercel's 1-click clone strips .github/workflows because its token lacks the `workflow`
+// scope, so the file must be added with a token that has it — which Connect obtains).
+//
+// The Client ID is PUBLIC (device flow uses no client secret), so it's baked in as the
+// default for every install; NEXTBLOCK_GITHUB_CLIENT_ID overrides it for self-run forks.
+import { resolveSelfRepo } from './repo-identity';
+
+// Shared NextBlock OAuth App (org: nextblock-cms), Device Flow enabled. Public value.
+const DEFAULT_GITHUB_CLIENT_ID = 'Ov23liVYp5Tpmq7CUnGf';
+const UPSTREAM_REPO = 'nextblock-cms/nextblock';
+const WORKFLOW_PATH = '.github/workflows/nextblock-sync.yml';
+// Writing a workflow file requires `workflow`; `repo` covers contents on private repos.
+const SCOPES = 'repo workflow';
+
+const DEVICE_CODE_URL = 'https://github.com/login/device/code';
+const TOKEN_URL = 'https://github.com/login/oauth/access_token';
+
+export function getGithubClientId(): string {
+  return process.env.NEXTBLOCK_GITHUB_CLIENT_ID?.trim() || DEFAULT_GITHUB_CLIENT_ID;
+}
+
+/** Connect is offered only when we know the repo and have a client id to authorize with. */
+export function isGithubConnectAvailable(): boolean {
+  return Boolean(getGithubClientId()) && resolveSelfRepo() !== null;
+}
+
+function apiHeaders(token?: string): Record<string, string> {
+  const headers: Record<string, string> = {
+    Accept: 'application/vnd.github+json',
+    'X-GitHub-Api-Version': '2022-11-28',
+    'User-Agent': 'nextblock-update-checker',
+  };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  return headers;
+}
+
+export interface DeviceFlowStart {
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  interval: number;
+  expiresIn: number;
+}
+
+/** Begin the device flow. Throws on a hard failure (the caller surfaces the message). */
+export async function startDeviceFlow(): Promise<DeviceFlowStart> {
+  const res = await fetch(DEVICE_CODE_URL, {
+    method: 'POST',
+    headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+    body: JSON.stringify({ client_id: getGithubClientId(), scope: SCOPES }),
+    signal: AbortSignal.timeout(15_000),
+    cache: 'no-store',
+  });
+  if (!res.ok) {
+    throw new Error(`GitHub device-code request failed (HTTP ${res.status}).`);
+  }
+  const data = await res.json();
+  if (data.error || !data.device_code) {
+    throw new Error(
+      data.error_description || data.error || 'GitHub did not return a device code.',
+    );
+  }
+  return {
+    deviceCode: data.device_code,
+    userCode: data.user_code,
+    verificationUri: data.verification_uri,
+    interval: typeof data.interval === 'number' ? data.interval : 5,
+    expiresIn: typeof data.expires_in === 'number' ? data.expires_in : 900,
+  };
+}
+
+export type DevicePollResult =
+  | { status: 'authorized'; token: string }
+  | { status: 'pending'; slowDown?: boolean }
+  | { status: 'expired' }
+  | { status: 'denied' }
+  | { status: 'error'; error: string };
+
+/** Poll once for the user's authorization. Never throws. */
+export async function pollDeviceFlowOnce(deviceCode: string): Promise<DevicePollResult> {
+  try {
+    const res = await fetch(TOKEN_URL, {
+      method: 'POST',
+      headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        client_id: getGithubClientId(),
+        device_code: deviceCode,
+        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+      }),
+      signal: AbortSignal.timeout(15_000),
+      cache: 'no-store',
+    });
+    const data = await res.json();
+    if (data.access_token) return { status: 'authorized', token: data.access_token };
+    switch (data.error) {
+      case 'authorization_pending':
+        return { status: 'pending' };
+      case 'slow_down':
+        return { status: 'pending', slowDown: true };
+      case 'expired_token':
+        return { status: 'expired' };
+      case 'access_denied':
+        return { status: 'denied' };
+      default:
+        return { status: 'error', error: data.error_description || data.error || 'Unknown error.' };
+    }
+  } catch (caught) {
+    return {
+      status: 'error',
+      error: caught instanceof Error ? caught.message : 'Could not reach GitHub.',
+    };
+  }
+}
+
+export interface InstallResult {
+  ok: boolean;
+  htmlUrl?: string;
+  error?: string;
+}
+
+/**
+ * Install (or update) the upstream-sync workflow in the connected repo, using the
+ * canonical file from the upstream repo so it never drifts. Never throws.
+ */
+export async function installSyncWorkflow(token: string): Promise<InstallResult> {
+  const self = resolveSelfRepo();
+  if (!self) return { ok: false, error: 'Could not determine this deployment’s GitHub repository.' };
+
+  try {
+    // 1) Default branch of the target repo.
+    const repoRes = await fetch(`https://api.github.com/repos/${self.owner}/${self.repo}`, {
+      headers: apiHeaders(token),
+      signal: AbortSignal.timeout(15_000),
+      cache: 'no-store',
+    });
+    if (!repoRes.ok) {
+      return { ok: false, error: `Could not read the repository (HTTP ${repoRes.status}).` };
+    }
+    const repo = await repoRes.json();
+    const branch: string = repo.default_branch || 'main';
+
+    // 2) Canonical workflow content from upstream (base64), passed straight through.
+    const upstreamRes = await fetch(
+      `https://api.github.com/repos/${UPSTREAM_REPO}/contents/${WORKFLOW_PATH}`,
+      { headers: apiHeaders(token), signal: AbortSignal.timeout(15_000), cache: 'no-store' },
+    );
+    if (!upstreamRes.ok) {
+      return { ok: false, error: `Could not read the upstream workflow (HTTP ${upstreamRes.status}).` };
+    }
+    const upstream = await upstreamRes.json();
+    const contentBase64 = typeof upstream.content === 'string' ? upstream.content.replace(/\s/g, '') : '';
+    if (!contentBase64) return { ok: false, error: 'Upstream workflow content was empty.' };
+
+    // 3) Existing file sha (if the path already exists on the target branch).
+    let sha: string | undefined;
+    const existingRes = await fetch(
+      `https://api.github.com/repos/${self.owner}/${self.repo}/contents/${WORKFLOW_PATH}?ref=${encodeURIComponent(branch)}`,
+      { headers: apiHeaders(token), signal: AbortSignal.timeout(15_000), cache: 'no-store' },
+    );
+    if (existingRes.ok) {
+      const existing = await existingRes.json();
+      if (existing && typeof existing.sha === 'string') sha = existing.sha;
+    }
+
+    // 4) Create/update the workflow file.
+    const putRes = await fetch(
+      `https://api.github.com/repos/${self.owner}/${self.repo}/contents/${WORKFLOW_PATH}`,
+      {
+        method: 'PUT',
+        headers: { ...apiHeaders(token), 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          message: 'ci: add NextBlock upstream-sync workflow',
+          content: contentBase64,
+          branch,
+          ...(sha ? { sha } : {}),
+        }),
+        signal: AbortSignal.timeout(20_000),
+        cache: 'no-store',
+      },
+    );
+    if (!putRes.ok) {
+      let detail = `HTTP ${putRes.status}`;
+      try {
+        const body = await putRes.json();
+        if (body?.message) detail = body.message;
+      } catch {
+        /* ignore */
+      }
+      return { ok: false, error: `Could not install the workflow: ${detail}.` };
+    }
+
+    return {
+      ok: true,
+      htmlUrl: `https://github.com/${self.owner}/${self.repo}/actions`,
+    };
+  } catch (caught) {
+    return {
+      ok: false,
+      error: caught instanceof Error ? caught.message : 'Could not install the workflow.',
+    };
+  }
+}

package/templates/nextblock-template/lib/updates/repo-identity.ts

@@ -39,8 +39,18 @@ export function resolveSelfRepo(): SelfRepo | null {
   return null;
 }
 
-/** The fork's GitHub Actions tab, for the onboarding "enable Actions" reminder. */
+/** The repo's GitHub Actions tab (shows the sync workflow + a "Run workflow" button). */
 export function selfActionsUrl(): string | null {
   const self = resolveSelfRepo();
   return self ? `https://github.com/${self.owner}/${self.repo}/actions` : null;
 }
+
+/**
+ * Settings -> Actions -> General. The authoritative enable/permissions page — always
+ * renders a clear UI (unlike /actions, which redirects to the confusing "choose a
+ * workflow" chooser when no workflow has run yet). Used by the onboarding reminder.
+ */
+export function selfActionsSettingsUrl(): string | null {
+  const self = resolveSelfRepo();
+  return self ? `https://github.com/${self.owner}/${self.repo}/settings/actions` : null;
+}

package/templates/nextblock-template/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextblock-cms/template",
-  "version": "0.10.9",
+  "version": "0.11.1",
   "private": true,
   "scripts": {
     "dev": "next dev",