rahman-resources 1.9.2 → 1.10.0

package/lib/slice-schema.json

@@ -135,6 +135,11 @@
               "reason": { "type": "string" }
             }
           }
+        },
+        "sharedFiles": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Repo-root shared files (relative to project root) this slice imports — the CLI copies them alongside the slice on add."
         }
       }
     },

package/lib/starter/_env.example

@@ -1,11 +1,20 @@
-# Convex (self-hosted or cloud)
+# Convex (self-hosted or cloud) — set BOTH in your host (e.g. Vercel).
 NEXT_PUBLIC_CONVEX_URL=
+# Production deploy key from Convex. Lets the build push functions+schema to
+# Convex (build:auto) and auto-provision the auth keys below.
+CONVEX_DEPLOY_KEY=
 
-# @convex-dev/auth — required for auth signing
+# @convex-dev/auth — required for auth signing. AUTO-SET during build by
+# scripts/setup-auth.mjs when CONVEX_DEPLOY_KEY is present (you usually don't
+# touch these). Listed here for local dev / manual fallback.
 JWKS=
 JWT_PRIVATE_KEY=
 SITE_URL=http://localhost:3000
 
+# In-app update channel (optional) — set on your Convex deployment to enable the
+# admin "Rebuild now" button. Create at Vercel -> Settings -> Git -> Deploy Hooks.
+VERCEL_DEPLOY_HOOK_URL=
+
 # Server actions encryption (multi-instance — pin once, share across instances)
 NEXT_SERVER_ACTIONS_ENCRYPTION_KEY=
 

package/lib/starter/_package.json

@@ -10,11 +10,14 @@
     "lint": "next lint",
     "typecheck": "tsc --noEmit",
     "convex:dev": "convex dev",
-    "convex:codegen": "convex dev --once"
+    "convex:codegen": "convex dev --once",
+    "build:auto": "if [ -n \"$CONVEX_DEPLOY_KEY\" ]; then node scripts/setup-auth.mjs && convex deploy --cmd 'next build'; else next build; fi",
+    "smoke": "node scripts/smoke-test.mjs"
   },
   "dependencies": {
     "@auth/core": "^0.37.0",
     "@convex-dev/auth": "^0.0.84",
+    "jose": "^5.9.6",
     "@radix-ui/react-label": "^2.1.0",
     "@radix-ui/react-slot": "^1.1.0",
     "class-variance-authority": "^0.7.1",

package/lib/starter/components/convex-provider.tsx

@@ -10,15 +10,18 @@
 // work even when the client hasn't established its WS yet.
 
 import { ConvexAuthProvider } from "@convex-dev/auth/react";
-import { ConvexReactClient } from "convex/react";
+import { ConvexReactClient, ConvexProvider } from "convex/react";
 import { ConvexHttpClient } from "convex/browser";
 import { useEffect, useState, type ReactNode } from "react";
 
 export function ConvexClientProvider({ children }: { children: ReactNode }) {
   const [mounted, setMounted] = useState(false);
   const [convex] = useState(() => {
-    const url = process.env.NEXT_PUBLIC_CONVEX_URL;
-    if (!url) return null;
+    // Always construct a client so `useQuery` ALWAYS has a ConvexProvider above
+    // it and can never throw "Could not find Convex client". If the env var is
+    // missing (misconfig), fall back to a non-connecting placeholder — queries
+    // stay in the loading state instead of crashing the page.
+    const url = process.env.NEXT_PUBLIC_CONVEX_URL || "https://placeholder.convex.cloud";
     const client = new ConvexReactClient(url);
     const http = new ConvexHttpClient(url);
     const orig = client.action.bind(client);
@@ -32,6 +35,13 @@ export function ConvexClientProvider({ children }: { children: ReactNode }) {
   });
 
   useEffect(() => setMounted(true), []);
-  if (!mounted || !convex) return <>{children}</>;
-  return <ConvexAuthProvider client={convex}>{children}</ConvexAuthProvider>;
+  // Outer ConvexProvider ALWAYS supplies the client, so `useQuery` can never
+  // throw "Could not find Convex client" — during SSR/prerender, during the
+  // mount transition, or under the auth provider. ConvexAuthProvider nests
+  // client-side only (it errors during static prerender).
+  return (
+    <ConvexProvider client={convex}>
+      {mounted ? <ConvexAuthProvider client={convex}>{children}</ConvexAuthProvider> : children}
+    </ConvexProvider>
+  );
 }

package/lib/starter/convex/schema.ts

@@ -4,6 +4,25 @@ import { v } from "convex/values";
 
 export default defineSchema({
   ...authTables,
+
+  // Singleton site config — owner identity + branding, written by the admin
+  // Settings UI / onboarding, read by the public site. One row. Part of the
+  // headless-core engine (type: lib/headless-core/settings.ts).
+  siteSettings: defineTable({
+    siteName: v.optional(v.string()),
+    tagline: v.optional(v.string()),
+    ownerName: v.optional(v.string()),
+    contactEmail: v.optional(v.string()),
+    brandColor: v.optional(v.string()),
+    themeDefault: v.optional(v.string()), // "light" | "dark" | "system"
+    logoUrl: v.optional(v.string()),
+    faviconUrl: v.optional(v.string()),
+    socials: v.optional(v.string()), // JSON string
+    seoDescription: v.optional(v.string()),
+    analyticsId: v.optional(v.string()),
+    onboardedAt: v.optional(v.number()),
+  }),
+
   // Add app tables here. Example:
   // notes: defineTable({
   //   userId: v.id("users"),

package/lib/starter/convex/settings.ts

@@ -0,0 +1,51 @@
+import { v, ConvexError } from "convex/values";
+import { mutation, query } from "./_generated/server";
+import { getAuthUserId } from "@convex-dev/auth/server";
+
+// Public read of site config — used by the public site (title/favicon/brand) and
+// the admin Settings UI. One singleton row.
+export const get = query({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.db.query("siteSettings").first();
+  },
+});
+
+const FIELDS = {
+  siteName: v.optional(v.string()),
+  tagline: v.optional(v.string()),
+  ownerName: v.optional(v.string()),
+  contactEmail: v.optional(v.string()),
+  brandColor: v.optional(v.string()),
+  themeDefault: v.optional(v.string()),
+  logoUrl: v.optional(v.string()),
+  faviconUrl: v.optional(v.string()),
+  socials: v.optional(v.string()),
+  seoDescription: v.optional(v.string()),
+  analyticsId: v.optional(v.string()),
+  // set true on the final onboarding step so the wizard never shows again
+  markOnboarded: v.optional(v.boolean()),
+};
+
+// Upsert the singleton settings row. Admin-only.
+export const upsert = mutation({
+  args: FIELDS,
+  handler: async (ctx, args) => {
+    const userId = await getAuthUserId(ctx);
+    if (!userId) throw new ConvexError("Harus login sebagai admin.");
+
+    const { markOnboarded, ...fields } = args;
+    const patch: Record<string, unknown> = {};
+    for (const [k, val] of Object.entries(fields)) {
+      if (val !== undefined) patch[k] = val;
+    }
+    if (markOnboarded) patch.onboardedAt = Date.now();
+
+    const existing = await ctx.db.query("siteSettings").first();
+    if (existing) {
+      await ctx.db.patch(existing._id, patch);
+      return existing._id;
+    }
+    return ctx.db.insert("siteSettings", patch);
+  },
+});

package/lib/starter/convex/setup.ts

@@ -0,0 +1,22 @@
+import { query } from "./_generated/server";
+
+// Onboarding state for the admin UI. Public (no PII) so the login form and the
+// dashboard setup banner can adapt before/after sign-in. Part of headless-core.
+export const status = query({
+  args: {},
+  handler: async (ctx) => {
+    const owner = await ctx.db.query("users").first();
+    const settings = await ctx.db.query("siteSettings").first();
+    const keyConfigured = !!process.env.ADMIN_SIGNUP_KEY;
+    const ownerClaimed = !!owner;
+    return {
+      ownerClaimed,
+      // Onboarding wizard is done once the owner finishes it (onboardedAt set).
+      onboarded: !!settings?.onboardedAt,
+      // Signup is open if no owner has claimed yet, or a key is configured (invites).
+      signupOpen: !ownerClaimed || keyConfigured,
+      // The "Setup key" field is only needed when a key is configured.
+      signupKeyRequired: keyConfigured,
+    };
+  },
+});

package/lib/starter/convex/update.ts

@@ -0,0 +1,47 @@
+import { action } from "./_generated/server";
+import { getAuthUserId } from "@convex-dev/auth/server";
+
+// In-app update channel (headless-core). A clone can't "git pull" itself, but it
+// CAN tell the owner when the upstream template shipped a newer version and (if
+// they wired a Vercel deploy hook) rebuild on demand. Version comparison happens
+// client-side (the app imports CORE_VERSION); these actions only do what the
+// browser can't: fetch the upstream manifest, and POST the deploy hook.
+
+// Upstream manifest on the template's default branch. Hardcoded (not client-
+// supplied) so this can't be pointed at an arbitrary URL. EDIT the slug to your
+// own repo if you fork away from the template.
+const UPSTREAM_VERSION_URL =
+  "https://raw.githubusercontent.com/rahmanef63/template-__APP_SLUG__/main/version.json";
+
+export const fetchUpstreamVersion = action({
+  args: {},
+  handler: async () => {
+    try {
+      const res = await fetch(UPSTREAM_VERSION_URL, { cache: "no-store" } as RequestInit);
+      if (!res.ok) return null;
+      const json = (await res.json()) as { version?: string; core?: string; channel?: string };
+      if (!json?.version) return null;
+      return { version: json.version, core: json.core ?? json.version, channel: json.channel ?? "stable" };
+    } catch {
+      return null;
+    }
+  },
+});
+
+// Rebuild the live site by hitting a Vercel Deploy Hook the owner pasted into
+// Convex env (VERCEL_DEPLOY_HOOK_URL). Admin-gated. No-ops cleanly if unset.
+export const triggerDeploy = action({
+  args: {},
+  handler: async (ctx) => {
+    const userId = await getAuthUserId(ctx);
+    if (!userId) return { ok: false as const, reason: "unauthorized" as const };
+    const hook = process.env.VERCEL_DEPLOY_HOOK_URL;
+    if (!hook) return { ok: false as const, reason: "no-hook" as const };
+    try {
+      const res = await fetch(hook, { method: "POST" });
+      return { ok: res.ok, reason: res.ok ? ("triggered" as const) : ("hook-failed" as const) };
+    } catch {
+      return { ok: false as const, reason: "hook-failed" as const };
+    }
+  },
+});

package/lib/starter/lib/headless-core/index.ts

@@ -0,0 +1,5 @@
+// headless-core — the engine every scaffold inherits: version/update plumbing +
+// the site-settings contract. Kept inside the app (not a separate npm package)
+// so a clone stays a single self-contained unit.
+export * from "./version";
+export * from "./settings";

package/lib/starter/lib/headless-core/settings.ts

@@ -0,0 +1,20 @@
+// The site-settings contract — the shape the onboarding/admin Settings UI writes
+// and the public surfaces read. Mirrors the Convex `siteSettings` singleton (all
+// optional; one row). Centralised so every surface shares one definition.
+export type SiteSettings = {
+  siteName?: string;
+  tagline?: string;
+  ownerName?: string;
+  contactEmail?: string;
+  brandColor?: string;
+  themeDefault?: string; // "light" | "dark" | "system"
+  logoUrl?: string;
+  faviconUrl?: string;
+  socials?: string; // JSON string
+  seoDescription?: string;
+  analyticsId?: string;
+  onboardedAt?: number;
+};
+
+// The editable subset (everything except the server-managed onboardedAt).
+export type SiteSettingsInput = Omit<SiteSettings, "onboardedAt">;

package/lib/starter/lib/headless-core/version.ts

@@ -0,0 +1,31 @@
+// Single source of version truth for this app + its headless core.
+//
+// `version.json` (repo root) is the machine-readable manifest the in-app update
+// channel reads on BOTH sides: the running app imports CORE_VERSION here, and
+// the upstream check fetches the raw version.json from GitHub to compare.
+//
+// Bump rule: edit version.json (this file imports it — one number to change).
+import manifest from "@/version.json";
+
+export const CORE_VERSION: string = manifest.core;
+export const TEMPLATE_VERSION: string = manifest.version;
+export const RELEASE_CHANNEL: string = manifest.channel;
+
+// Upstream repo this clone updates from. Defaults to the template repo the CLI
+// scaffolded from; EDIT these to YOUR repo so "check for updates" points at the
+// source you actually pull from (or leave as-is if you track the template).
+export const UPSTREAM_OWNER = "rahmanef63";
+export const UPSTREAM_REPO = "template-__APP_SLUG__";
+export const UPSTREAM_REPO_URL = `https://github.com/${UPSTREAM_OWNER}/${UPSTREAM_REPO}`;
+export const UPSTREAM_VERSION_URL = `https://raw.githubusercontent.com/${UPSTREAM_OWNER}/${UPSTREAM_REPO}/main/version.json`;
+
+/** semver-ish compare: returns >0 if a>b, <0 if a<b, 0 if equal. Tolerates "1.2.3". */
+export function compareVersions(a: string, b: string): number {
+  const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (d !== 0) return d > 0 ? 1 : -1;
+  }
+  return 0;
+}

package/lib/starter/scripts/setup-auth.mjs

@@ -0,0 +1,53 @@
+// Build-time auth bootstrap — so a cloner NEVER touches Convex env for login.
+// Runs only when CONVEX_DEPLOY_KEY is present (i.e. a real clone build); the
+// deploy key lets us set the deployment's env. Idempotent: generates the
+// @convex-dev/auth JWT keys once and skips if they already exist (so sessions
+// aren't invalidated on every deploy).
+import { execFileSync } from "node:child_process";
+
+if (!process.env.CONVEX_DEPLOY_KEY) {
+  console.log("[setup-auth] no CONVEX_DEPLOY_KEY — skipping (demo/local).");
+  process.exit(0);
+}
+
+const npx = (args, capture = false) =>
+  execFileSync("npx", args, {
+    encoding: "utf8",
+    stdio: capture ? ["ignore", "pipe", "ignore"] : "inherit",
+  });
+
+function envGet(name) {
+  try {
+    return npx(["convex", "env", "get", name], true).trim();
+  } catch {
+    return "";
+  }
+}
+
+if (envGet("JWT_PRIVATE_KEY")) {
+  console.log("[setup-auth] JWT keys already set — skip.");
+  process.exit(0);
+}
+
+console.log("[setup-auth] generating auth keys…");
+// Same format as `npx @convex-dev/auth` (jose RS256, newlines → spaces).
+const { generateKeyPair, exportPKCS8, exportJWK } = await import("jose");
+const keys = await generateKeyPair("RS256", { extractable: true });
+const privateKey = (await exportPKCS8(keys.privateKey)).trimEnd().replace(/\n/g, " ");
+const jwk = await exportJWK(keys.publicKey);
+const jwks = JSON.stringify({ keys: [{ use: "sig", ...jwk }] });
+
+const site =
+  process.env.SITE_URL ||
+  (process.env.VERCEL_PROJECT_PRODUCTION_URL
+    ? `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`
+    : process.env.VERCEL_URL
+      ? `https://${process.env.VERCEL_URL}`
+      : "");
+
+// NAME=value form: the value starts with "-----BEGIN", which the CLI would else
+// parse as a flag.
+npx(["convex", "env", "set", `JWT_PRIVATE_KEY=${privateKey}`]);
+npx(["convex", "env", "set", `JWKS=${jwks}`]);
+if (site) npx(["convex", "env", "set", `SITE_URL=${site}`]);
+console.log("[setup-auth] auth keys provisioned ✔");

package/lib/starter/scripts/smoke-test.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// Clone smoke-test — verifies a fresh clone has everything needed to deploy.
+// Runs LOCALLY (or in a pre-push hook) — no GitHub Actions cloud minutes.
+//
+//   node scripts/smoke-test.mjs            # full (invariants + tsc + build)
+//   node scripts/smoke-test.mjs --no-build # skip next build (fast)
+import { existsSync, readFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+
+const noBuild = process.argv.includes("--no-build");
+let failed = 0;
+const ok = (m) => console.log(`  \x1b[32m✓\x1b[0m ${m}`);
+const bad = (m) => { console.log(`  \x1b[31m✗ ${m}\x1b[0m`); failed++; };
+
+console.log("\n● Required files");
+const required = [
+  "version.json",
+  "vercel.json",
+  "package.json",
+  ".env.example",
+  "convex/auth.ts",
+  "convex/schema.ts",
+  "convex/settings.ts",
+  "convex/setup.ts",
+  "scripts/setup-auth.mjs",
+  "lib/headless-core/version.ts",
+];
+for (const f of required) (existsSync(f) ? ok(f) : bad(`missing ${f}`));
+
+console.log("\n● Manifest + scripts");
+try {
+  const v = JSON.parse(readFileSync("version.json", "utf8"));
+  v.version && v.core ? ok(`version.json (v${v.version})`) : bad("version.json missing version/core");
+} catch { bad("version.json invalid JSON"); }
+try {
+  const pkg = JSON.parse(readFileSync("package.json", "utf8"));
+  pkg.scripts?.["build:auto"] ? ok("package.json build:auto present") : bad("package.json missing build:auto");
+} catch { bad("package.json invalid"); }
+try {
+  const vc = JSON.parse(readFileSync("vercel.json", "utf8"));
+  /build:auto/.test(vc.buildCommand ?? "") ? ok("vercel.json buildCommand -> build:auto") : bad("vercel.json buildCommand wrong");
+} catch { bad("vercel.json invalid"); }
+
+console.log("\n● Env documentation");
+try {
+  const env = readFileSync(".env.example", "utf8");
+  for (const k of ["NEXT_PUBLIC_CONVEX_URL", "CONVEX_DEPLOY_KEY"])
+    (env.includes(k) ? ok(`.env.example documents ${k}`) : bad(`.env.example missing ${k}`));
+} catch { bad(".env.example unreadable"); }
+
+function run(label, cmd) {
+  process.stdout.write(`\n● ${label}\n`);
+  try {
+    execSync(cmd, { stdio: "pipe" });
+    ok(`${label} passed`);
+  } catch (e) {
+    bad(`${label} failed`);
+    const out = (e.stdout?.toString() || "") + (e.stderr?.toString() || "");
+    console.log(out.split("\n").slice(-25).join("\n"));
+  }
+}
+
+run("Typecheck", "npx tsc --noEmit");
+if (!noBuild) run("Build", "npm run build");
+
+console.log(`\n${failed === 0 ? "\x1b[32mSMOKE PASS\x1b[0m" : `\x1b[31mSMOKE FAIL — ${failed} issue(s)\x1b[0m`}\n`);
+process.exit(failed === 0 ? 0 : 1);

package/lib/starter/vercel.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "buildCommand": "npm run build:auto"
+}

package/lib/starter/version.json

@@ -0,0 +1,5 @@
+{
+  "version": "1.0.0",
+  "core": "1.0.0",
+  "channel": "stable"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rahman-resources",
-  "version": "1.9.2",
+  "version": "1.10.0",
   "description": "Rahman Resources (rr) — shadcn-style installer for vertical slices. `npx resources add <slug>` copies slice into your project's `slices/<slug>/`. You own the files.",
   "type": "module",
   "license": "MIT",