create-nextblock 0.2.78 → 0.8.0

package/templates/nextblock-template/docs/04-DATABASE-AND-AUTH.md

@@ -0,0 +1,252 @@
+# 04 Database and Auth
+
+## Source of Truth
+
+The database and auth implementation is spread across:
+
+- `libs/db/src/lib/supabase/*`
+- `libs/db/src/lib/package-validation.ts`
+- `libs/db/src/supabase/config.toml`
+- `libs/db/src/supabase/migrations/*`
+- `apps/nextblock/app/auth/callback/route.ts`
+- `apps/nextblock/app/cms/*`
+
+When documentation and a migration disagree, the migration folder is the final
+authority for schema, triggers, grants, and policies.
+
+## Supabase Client Surfaces
+
+`libs/db/src/server.ts` currently exports:
+
+- `createClient()`: request-scoped server client using auth cookies
+- `getProfileWithRoleServerSide()`
+- `getActiveLanguagesServerSide()`
+- `getServiceRoleSupabaseClient()`
+- `getSsgSupabaseClient()`
+- package activation helpers such as `verifyPackageOnline()`
+
+Practical usage in the app is split by trust level:
+
+- normal server routes and components use `createClient()`
+- public static-ish reads often use `getSsgSupabaseClient()`
+- admin or system workflows use `getServiceRoleSupabaseClient()`
+
+## Auth Flow
+
+### Session exchange
+
+`app/auth/callback/route.ts` handles Supabase auth callback exchanges:
+
+1. read the `code` query parameter
+2. exchange it for a session with `supabase.auth.exchangeCodeForSession()`
+3. load the user's profile and role
+4. redirect through `resolvePostAuthRedirect()`
+
+### Profile creation
+
+The first-user and profile bootstrap logic lives in the database, not in React
+code.
+
+`00000000000005_setup_functions_and_triggers.sql` defines:
+
+- `handle_new_user()`
+- `on_auth_user_created` trigger on `auth.users`
+
+That trigger:
+
+- creates the first local admin automatically
+- creates later users as `USER`
+- inserts or updates `profiles`
+- copies selected metadata such as `full_name`, avatar URL, and GitHub username
+
+### CMS authorization
+
+The CMS shell in `app/cms/CmsClientLayout.tsx` currently expects:
+
+- an authenticated user
+- a resolved profile role of `ADMIN` or `WRITER`
+
+Writers and admins can enter the CMS. Admin-only navigation is used for
+settings such as payments, shipping, users, and some branding/config surfaces.
+
+### No live app middleware file
+
+There is a generic Supabase middleware helper in `libs/db/src/lib/supabase`,
+but there is no live `apps/nextblock/middleware.ts` file in the current app.
+Document the callback, layout, and RLS model as the active auth path rather
+than assuming middleware-based route protection is in use.
+
+## Schema Overview
+
+### Core platform tables
+
+Defined primarily in `00000000000001_setup_cms_core.sql`:
+
+- `site_settings`
+- `profiles`
+- `user_addresses`
+- `languages`
+- `media`
+- `translations`
+- `logos`
+
+### Content tables
+
+Defined primarily in `00000000000002_setup_content_tables.sql`:
+
+- `posts`
+- `pages`
+- `blocks`
+- `navigation_items`
+- `page_revisions`
+- `post_revisions`
+
+### Commerce tables
+
+Defined across `00000000000003` and `00000000000004`:
+
+- `products`
+- `product_media`
+- `product_attributes`
+- `product_attribute_terms`
+- `product_variants`
+- `inventory_items`
+- `variant_attribute_mapping`
+- `package_activations`
+- `freemius_plans`
+- `freemius_pricing`
+- `orders`
+- `order_items`
+- `shipping_zones`
+- `shipping_zone_locations`
+- `shipping_zone_methods`
+- `tax_rates`
+- `currencies`
+
+### Post-baseline tables
+
+Added after the squashed baseline by later migrations:
+
+- `categories` and `product_categories` — catalog organization
+  (migration `00000000000019`; translated via `00000000000020`)
+- `custom_block_definitions` — data-driven custom block registry
+  (migration `00000000000023`; see [10-CUSTOM-BLOCKS.md](./10-CUSTOM-BLOCKS.md))
+- `ucp_cart_sessions` — persisted cart sessions (migration `00000000000024`)
+- a `blocks` JSONB column plus `product_id` link for block-based product
+  descriptions (migration `00000000000017`)
+
+## Row Level Security Patterns
+
+`00000000000006_setup_rls_and_grants.sql` is the consolidated RLS file.
+
+The high-level access model is:
+
+- public read access for languages, media, translations, published content, and
+  several storefront commerce tables
+- authenticated self-service access for user addresses and customer-owned
+  orders
+- `ADMIN` or `WRITER` write access for most CMS authoring tables
+- `ADMIN`-only write access for higher-risk configuration surfaces
+- `service_role` full access where background jobs or system syncs need it
+
+Commerce-specific policy highlights include:
+
+- public read access for products, product media, product attributes, variants,
+  shipping zones, shipping methods, tax rates, and active currencies
+- customer-scoped read access for `orders` and `order_items`
+- service-role management access for orders, order items, inventory, taxes, and
+  currencies
+
+## Migration Structure
+
+### Current reality
+
+The current padded migration sequence in
+`libs/db/src/supabase/migrations` runs from:
+
+- `00000000000000`
+- through `00000000000024`
+
+The first files (`00000000000000` through `00000000000016`) are squashed,
+grouped baseline domains. Everything from `00000000000017` onward is an
+append-only forward migration added after the baseline.
+
+These files are already squashed and grouped. Several of them preserve older
+logical migration boundaries through embedded comment headers, so you will see
+historical section numbers inside a smaller set of physical files.
+
+### Production migration policy
+
+NextBlock has live Supabase data. Treat migrations as append-only for any
+production or shared database change.
+
+- Do not edit, recycle, squash, reorder, or delete migration files that may
+  already be recorded in a shared or production Supabase project.
+- Add a new forward-only `.sql` file under
+  `libs/db/src/supabase/migrations` for each new schema/data change.
+- Keep migrations non-destructive by default. Avoid dropping or rewriting data
+  that may include orders, users, payments, or customer records.
+- Run `npm run db:migrate:check` before `npm run db:migrate`.
+- If an existing database lists old baseline files such as
+  `00000000000000_setup_foundation_and_enums.sql` as pending, do not replay
+  them. Use `npm run db:migrate:repair-history:check`, then
+  `npm run db:migrate:repair-history`, then rerun
+  `npm run db:migrate:check`.
+- Use `npm run db:migrate:fresh` only for a brand-new empty database.
+
+### Category map
+
+| Migration file | Domain | What it covers |
+| :-- | :-- | :-- |
+| `00000000000000_setup_foundation_and_enums.sql` | Core | Shared enums and schema-level foundation |
+| `00000000000001_setup_cms_core.sql` | Core, CMS | settings, profiles, languages, media, translations, logos |
+| `00000000000002_setup_content_tables.sql` | CMS | pages, posts, blocks, navigation, revisions |
+| `00000000000003_setup_catalog_and_licensing.sql` | Commerce | catalog, variants, inventory cache tables, package activations, Freemius sync tables |
+| `00000000000004_setup_fulfillment_shipping_taxes_and_currencies.sql` | Fulfillment, Commerce | orders, shipping, taxes, currencies, price-map sync functions |
+| `00000000000005_setup_functions_and_triggers.sql` | Core, CMS, Fulfillment | auth/profile bootstrap, timestamps, invoice functions, inventory deduction, product upsert helpers |
+| `00000000000006_setup_rls_and_grants.sql` | Security | grants, RLS enablement, policies |
+| `00000000000007_setup_indexes.sql` | Core, CMS, Commerce | performance indexes across authoring and commerce tables |
+| `00000000000008_seed_platform_defaults.sql` | Seeds | baseline site settings, default languages, default currencies |
+| `00000000000009_seed_translations.sql` | Seeds | translation catalog |
+| `00000000000010_seed_content_scaffold.sql` | Seeds, CMS | starter content, scaffold pages, seeded copy |
+| `00000000000011_setup_cortex_ai_settings.sql` | AI, Settings | Cortex AI settings and provider defaults |
+| `00000000000012_setup_commerce_coupons.sql` | Commerce | coupon tables and related commerce constraints |
+| `00000000000013_setup_cortex_ai_db_mutation_audit.sql` | AI, Audit | Cortex AI database mutation audit support |
+| `00000000000014_setup_content_drafts.sql` | CMS, Editor | visual-editing content draft tables |
+| `00000000000015_setup_product_drafts.sql` | Commerce, Editor | product draft workflow support |
+| `00000000000016_add_feature_image_to_pages.sql` | CMS | optional page feature image media relationship |
+| `00000000000017_add_product_blocks.sql` | Commerce, Editor | block-based product descriptions (`blocks` JSONB column and `product_id` link) |
+| `00000000000018_setup_bot_protection_settings.sql` | CMS, Security | Turnstile/reCAPTCHA bot-protection settings for forms; sensitive site-settings key protection |
+| `00000000000019_add_product_categories.sql` | Commerce | `categories` and `product_categories` junction tables |
+| `00000000000020_add_category_translations.sql` | Commerce, i18n | `name_translations` / `description_translations` on categories |
+| `00000000000021_migrate_hero_blocks_to_sections.sql` | CMS, Editor | data migration converting legacy `hero` blocks into `section` blocks (`is_hero`) |
+| `00000000000022_seed_cortex_ai_guide_post.sql` | Seeds, AI | seeds the Cortex AI guide post |
+| `00000000000023_setup_custom_block_definitions.sql` | CMS, Editor | `custom_block_definitions` registry, validation functions, `duplicate_block_definition` RPC, and RLS (see [10-CUSTOM-BLOCKS.md](./10-CUSTOM-BLOCKS.md)) |
+| `00000000000024_setup_ucp_cart_sessions.sql` | Commerce | `ucp_cart_sessions` table and update trigger for persisted carts |
+
+### How to read the folder
+
+Read the migrations in lexical order from `00000000000000` upward.
+
+That sequence is the cleanest under-the-hood blueprint for:
+
+- which tables exist
+- what triggers and functions are available
+- what security rules are enforced
+- what default content and configuration are seeded
+
+If you need to understand whether the platform really supports something, check
+the migration file first, then trace the corresponding route or library code.
+
+## Important Site Settings in Active Use
+
+These keys are actively referenced by the current codebase:
+
+- `enabled_payment_providers`
+- `ecommerce_inventory_settings`
+- `invoice_settings`
+- `footer_copyright`
+- `is_admin_created`
+
+There are many more seeded settings, but these are the most important ones for
+understanding current runtime behavior.

package/templates/nextblock-template/docs/05-DEVELOPER-GUIDE.md

@@ -0,0 +1,238 @@
+# 05 Developer Guide
+
+## Local Setup
+
+The root developer workflow is defined by the workspace `package.json` and the
+setup helper in `tools/scripts/setup.mjs`.
+
+### Prerequisites
+
+`npm run setup` is interactive and asks for credentials from three services, so
+create them first:
+
+1. **Supabase project** (https://supabase.com/dashboard) — Reference ID
+   (Project Settings → General), connection string (Connect → Direct connection →
+   URI), anon + service_role keys (Project Settings → API Keys), and a Personal
+   Access Token (Account → Access Tokens → Generate new token).
+2. **Cloudflare R2 bucket** (https://dash.cloudflare.com → R2) — create a bucket,
+   enable its Public Development URL (Bucket → Settings → General), and create an
+   Account API token (R2 → Manage API Tokens) with Object Read & Write. Copy the
+   Access Key ID and Secret Access Key (the secret is shown only once).
+3. **SMTP credentials** (SMTP2GO works very well) — required so Supabase can send
+   the confirmation email the first admin needs to sign in.
+
+### Run it
+
+```bash
+npm install
+npm run setup
+npx nx serve nextblock
+```
+
+What `npm run setup` does:
+
+- creates `.env.local` from `.env.exemple` if needed
+- prompts for Supabase, Cloudflare R2, and SMTP details (all required)
+- writes `NEXT_PUBLIC_URL` and auto-generates `CRON_SECRET`,
+  `DRAFT_MODE_SECRET`, and `REVALIDATE_SECRET_TOKEN`
+- links the local Supabase CLI workdir to your project (`npm run db:link`)
+- applies the full schema baseline to the new database
+  (`npm run db:migrate:fresh`)
+- syncs hosted Supabase Auth — custom SMTP and branded email templates
+  (`npm run configure:supabase-auth`)
+
+If you skip `npm run setup`, the misspelled root sample file `.env.exemple` is
+the reference template for manual environment setup.
+
+### First login
+
+`npx nx serve nextblock` serves the app at **http://localhost:4200** (the
+`@nx/next:server` default port). Open `/sign-up` and register: the **first**
+account to sign up is automatically promoted to **ADMIN** by a database trigger
+(`handle_new_user`). Email confirmation is enabled by default, so click the
+confirmation link (delivered through the SMTP you configured) — or confirm the
+user manually in Supabase → Authentication → Users. After signing in you land in
+the CMS at `/cms/dashboard`. Every later sign-up gets the `USER` role.
+
+## Common Commands
+
+### App and library workflows
+
+- `npx nx serve nextblock`: start the main app in development
+- `npm run lint`: run Nx lint targets across the workspace
+- `npm run nx:lint:nextblock`: lint the main app only
+- `npm run nx:lint:create-nextblock`: lint the CLI app only
+- `npm run all-builds`: build workspace projects except the template output
+
+### Database workflows
+
+- `npm run db:link`: link the Supabase CLI to the target project
+- `npm run db:migrate:check`: preview pending remote migrations without
+  applying them
+- `npm run db:migrate`: apply pending migration files only; this is the
+  production-safe path for live databases
+- `npm run db:migrate:fresh`: apply the full migration baseline to a
+  brand-new empty database
+- `npm run db:migrate:repair-history:check`: preview the migration-history
+  baseline repair for an existing database whose schema is already present
+- `npm run db:migrate:repair-history`: mark historical baseline migrations as
+  applied without running their SQL
+- `npm run db:push`: alias for `npm run db:migrate`
+- `npm run db:push:sandbox`: legacy sandbox bootstrap path that pushes
+  migrations with `--include-all`, pushes Supabase config, seeds sandbox
+  images, and deploys the migration-ingest function
+- `npm run db:reset`: reset the local/linked Supabase database from the db
+  workdir
+- `npm run db:types`: regenerate typed Supabase definitions
+- `npm run db:backup`
+- `npm run db:restore`
+- `npm run deploy:supabase`
+
+### Sandbox and automation workflows
+
+- `npm run generate:sandbox`: regenerate the checked-in sandbox reset payload
+- `npm run sandbox:reset`: call the app's sandbox reset cron route locally
+- `npm run stripe`: forward Stripe events to the local webhook route
+
+## Environment Expectations
+
+The exact set of env vars depends on which surfaces you use, but the current
+repo expects at least:
+
+- `NEXT_PUBLIC_SUPABASE_URL`
+- `NEXT_PUBLIC_SUPABASE_ANON_KEY`
+- `SUPABASE_SERVICE_ROLE_KEY`
+- `SUPABASE_PROJECT_ID` for Supabase CLI migration tooling
+- `SUPABASE_ACCESS_TOKEN` for Supabase CLI linking
+- `POSTGRES_URL` or `DATABASE_URL` for SQL fallback paths and db tooling
+- `NEXT_PUBLIC_URL` — written by `npm run setup`
+- `CRON_SECRET`, `DRAFT_MODE_SECRET`, `REVALIDATE_SECRET_TOKEN` — auto-generated
+  by `npm run setup`
+
+Captured by `npm run setup` and needed for a complete CMS:
+
+- R2 credentials for media storage. The app builds and serves without them, but
+  uploads, image processing, and full-site backups return 500 until R2 is set.
+- SMTP credentials for hosted auth email — required to deliver the first admin's
+  sign-up confirmation on hosted Supabase.
+
+Optional, per feature:
+
+- Stripe keys for physical-product checkout
+- Freemius keys for digital-product checkout and product sync
+
+## Running the Main App
+
+The canonical application is `apps/nextblock`.
+
+Useful targets:
+
+- `nx serve nextblock`
+- `nx build nextblock`
+- `nx lint nextblock`
+
+The CMS and public site share the same Next.js app, so one dev server covers:
+
+- public pages and posts
+- CMS routes
+- checkout routes
+- webhook routes
+- cron routes
+
+## Database and Migration Workflow
+
+The migration source of truth is:
+
+`libs/db/src/supabase/migrations`
+
+Normal contributor workflow:
+
+1. update code and migrations together
+2. run `npm run db:migrate:check`
+3. run `npm run db:migrate` against the intended Supabase project
+4. regenerate db types if the schema changed
+5. verify the app routes or server actions against the new shape
+
+Production rule:
+
+- NextBlock now has live data. New production/shared database changes must be
+  append-only, forward-only, and non-destructive by default.
+- Do not edit migration files that have already been applied to production.
+- Add a new forward-only `.sql` file under
+  `libs/db/src/supabase/migrations` for each production schema/data change.
+- Use `npm run db:migrate:check` before `npm run db:migrate`.
+- If `db:migrate:check` lists historical baseline migrations such as
+  `00000000000000_setup_foundation_and_enums.sql` on an existing production database, do
+  not run `db:migrate` yet. Run `npm run db:migrate:repair-history:check`,
+  then `npm run db:migrate:repair-history`, then check again. The expected
+  result after repair is that only new unapplied migrations remain.
+- Do not use `npm run db:reset`, `npm run sandbox:reset`,
+  `npm run db:migrate:fresh`, or `npm run db:push:sandbox` against production.
+
+Fresh local and sandbox rebuilds may still use the reset/bootstrap flow when
+the target database is disposable.
+
+The migration-only script:
+
+- loads `.env.local` and `.env`
+- links the Supabase CLI to `SUPABASE_PROJECT_ID`
+- uses `SUPABASE_DB_PASSWORD`, `POSTGRES_PASSWORD`, `POSTGRES_URL`, or
+  `DATABASE_URL` for the database password
+- runs `supabase db push` without `--include-all`
+- never runs a reset, seed script, function deploy, or config push
+
+Because the migration set started as a squashed baseline, contributors should
+treat the existing baseline files as grouped domains. New production changes
+after the baseline should be appended as new migrations.
+
+## Sandbox Reset Operations
+
+The sandbox automation is code-driven.
+
+`npm run generate:sandbox`:
+
+- reads the migration folder
+- concatenates the SQL in lexical order
+- writes the generated payload to
+  `apps/nextblock/app/api/cron/reset-sandbox/sandboxResetSql.ts`
+
+`npm run sandbox:reset`:
+
+- loads `.env.local`
+- refuses to run unless `NEXT_PUBLIC_IS_SANDBOX=true`
+- reads `NEXT_PUBLIC_URL` and `CRON_SECRET`
+- calls `GET /api/cron/reset-sandbox`
+
+The cron route then:
+
+- returns 404 immediately unless `NEXT_PUBLIC_IS_SANDBOX=true`
+- executes the generated reset SQL
+- reseeds media assets
+- reseeds commerce content
+- triggers Freemius sync helpers for sandbox data
+
+## Deployment Notes
+
+The repo currently assumes:
+
+- the app is deployed as a Next.js application
+- Supabase remains the database/auth backend
+- cron routes are protected with `Authorization: Bearer ${CRON_SECRET}`
+- package activation and several system workflows require working server-side
+  environment variables, not only public client keys
+
+If you are configuring hosted Supabase auth email settings, use:
+
+```bash
+npm run configure:supabase-auth
+```
+
+## Current Repo Notes
+
+Two repo facts are worth keeping in mind while contributing:
+
+- the workspace import path is `@nextblock-cms/ecommerce`, but the current
+  `libs/ecommerce/package.json` name is still `@nextblock-cms/ecom`
+- a standalone `npx nx run ecommerce:build --skip-nx-cache` check is currently
+  not green, so use app-level validation and targeted tracing until that build
+  target is repaired

package/templates/nextblock-template/docs/06-CLI-AND-SCAFFOLDING.md

@@ -0,0 +1,125 @@
+# 06 CLI and Scaffolding
+
+## Purpose
+
+`apps/create-nextblock` is the onboarding surface for developers who want a
+standalone NextBlock project without cloning the full monorepo.
+
+The CLI does two main jobs:
+
+- scaffold a package-based project from the current app template
+- activate premium ecommerce routes and dependencies in generated projects
+
+## Source Application vs Template Output
+
+The canonical application is still `apps/nextblock`.
+
+The scaffold template under
+`apps/create-nextblock/templates/nextblock-template` is copied output, not the
+authoritative source. The sync pipeline refreshes that template by copying the
+source app and applying a series of post-copy adjustments.
+
+That means contributor workflow should be:
+
+1. change the source app or shared libraries
+2. update root docs and README entrypoints
+3. run the template sync when you want the generated project to catch up
+
+## CLI Entry Points
+
+`apps/create-nextblock/bin/create-nextblock.js` currently defines:
+
+- `create [project-directory]`
+- `activate [module]`
+
+The default create flow is what powers:
+
+```bash
+npm create nextblock@latest
+```
+
+## What the Create Flow Actually Does
+
+When the CLI creates a project it currently:
+
+1. prompts for a project name unless `--yes` is used
+2. copies `templates/nextblock-template` into the new directory
+3. removes backup artifacts
+4. applies client component and provider adjustments
+5. normalizes block-editor and UI imports
+6. generates UI proxy modules
+7. copies editor utility shims when needed
+8. ensures `.gitignore`, `.env.example`, layout files, and config files are in
+   the expected generated-project shape
+9. rewrites `package.json` away from workspace dependencies and toward published
+   packages
+10. writes a project-level `.npmrc` for public package resolution
+11. optionally installs dependencies
+12. optionally runs the generated-project setup wizard
+13. initializes git
+
+## Package Version Sources
+
+The CLI resolves published package versions from the local monorepo package
+metadata for:
+
+- `@nextblock-cms/ui`
+- `@nextblock-cms/utils`
+- `@nextblock-cms/db`
+- `@nextblock-cms/editor`
+- `@nextblock-cms/sdk`
+
+The ecommerce module is special because activation installs the alias:
+
+```bash
+@nextblock-cms/ecommerce@npm:@nextblock-cms/ecom@latest
+```
+
+That alias matches the current package-name discrepancy documented elsewhere.
+
+## Template Sync Workflow
+
+`apps/create-nextblock/scripts/sync-template.js` is the authoritative source for
+template generation inside the monorepo.
+
+It currently:
+
+- copies `apps/nextblock` into `templates/nextblock-template`
+- skips `node_modules`, `.next`, backups, and other generated folders
+- copies the root `docs/` folder into the template docs directory
+- copies `.env.example` or `.env.exemple`
+- rewrites imports for packaged library consumption
+- removes the copied `project.json`
+- syncs package versions
+- normalizes global styles and UI proxy files
+
+This is why the root docs and root/app README surfaces matter first: the
+template inherits from them later through the sync step.
+
+## Premium Ecommerce Activation
+
+The `activate ecommerce` command does more than add a dependency. It also
+injects route wrappers and supporting files into the generated project so the
+premium module appears as a coherent extension rather than a bare npm install.
+
+The injected surfaces include wrappers for routes such as:
+
+- `/cms/orders`
+- `/cms/products`
+- `/cms/payments`
+- `/checkout/success`
+- `/api/checkout`
+
+Those wrappers use `verifyPackageOnline()` so premium routes stay aligned with
+package activation state.
+
+## Publishing and Release Notes
+
+Inside the monorepo, CLI release work is still tied to the source workspace:
+
+- library builds and publishes happen from the workspace
+- template sync happens before CLI packaging
+- the CLI package itself is versioned in `apps/create-nextblock/package.json`
+
+If a generated project looks stale, check the sync script and template output
+before assuming the source app is missing the feature.