@founderhq/next-blog 0.9.0

package/README.md

@@ -0,0 +1,169 @@
+# @founderhq/next-blog
+
+Next.js App Router SEO helpers, editable blog templates, and installer for
+FounderHQ-compatible Payload blogs.
+
+## Install
+
+```sh
+npx @founderhq/next-blog@next init
+```
+
+The installer is conservative:
+
+- dry-run preview first, then asks whether to apply
+- supports `--dry-run` for preview-only runs
+- supports `--yes` for non-interactive apply after plan generation
+- supports `--env-mode write|print` to choose runtime env handling
+- refuses dirty git by default
+- prints a diff preview before writing
+- uses dedicated Payload env vars
+- asks for database and site env values
+- supports Next App Router automatically and non-Next projects with a
+  framework-neutral manual integration plan
+- always writes safe examples to `.env.example` on apply
+- lets you either write runtime env values to `.env` and `.env.local`, or
+  print them for copy-paste into your own env setup
+- installs only the selected Payload database and storage adapters
+- asks before running migrations and validates env first
+- aborts with manual instructions for unsupported project shapes, existing
+  Payload configs, unsupported Next config filenames, and generated file path
+  collisions
+- copies editable blog UI into your app instead of forcing package-owned visual
+  components
+
+Supported v1 databases:
+
+- Postgres through `@payloadcms/db-postgres`
+- local SQLite through `@payloadcms/db-sqlite`
+- Turso/libSQL through `@payloadcms/db-sqlite`
+
+MongoDB is intentionally manual/advanced in v1.
+
+Supported installer storage choices:
+
+- local
+- S3
+- R2
+- Vercel Blob
+- Azure Blob
+- Google Cloud Storage
+- UploadThing
+- custom/manual
+
+The custom/manual choice generates a no-op `founderhq-blog.storage.ts` so
+migrations and the admin app can boot before the customer adds their adapter.
+Edit that file before production uploads.
+
+Payload uses dedicated env vars and never reuses an app `DATABASE_URL`
+silently:
+
+- `PAYLOAD_DATABASE_URL`
+- `PAYLOAD_DATABASE_AUTH_TOKEN`
+- `PAYLOAD_SECRET`
+- `NEXT_PUBLIC_SITE_NAME`
+- `NEXT_PUBLIC_SITE_URL`
+- `NEXT_PUBLIC_BLOG_ROUTE_PREFIX`
+
+The v1 installer requires a non-root blog route prefix such as `/blog` or
+`/insights`. Root-mounted blogs can be wired manually after install if a client
+needs the blog to own `/`.
+
+## Install model
+
+The package uses a hybrid model:
+
+- `@founderhq/payload-cms-kit` owns Payload collections, fields, blocks, hooks,
+  and rich text behavior.
+- `@founderhq/next-blog/server` owns portable server helpers for fetching,
+  normalization, metadata, JSON-LD, RSS, sitemaps, redirects, and search.
+- `npx @founderhq/next-blog init` copies editable UI templates into the target
+  project, similar to the shadcn open-code model.
+
+Fresh installs generate files like:
+
+- `src/components/blog/blog-components.tsx`
+- `src/components/blog/blog.css`
+- `src/app/blog/page.tsx`
+- `src/app/blog/page/[page]/page.tsx`
+- `src/app/blog/[slug]/page.tsx`
+- `src/app/blog/search/page.tsx`
+- `src/app/blog/authors/page.tsx`
+- `src/app/blog/authors/[slug]/page.tsx`
+- `src/app/blog/authors/[slug]/page/[page]/page.tsx`
+- `src/app/blog/categories/page.tsx`
+- `src/app/blog/categories/[slug]/page.tsx`
+- `src/app/blog/categories/[slug]/page/[page]/page.tsx`
+- `src/app/blog/tags/page.tsx`
+- `src/app/blog/tags/[slug]/page.tsx`
+- `src/app/blog/tags/[slug]/page/[page]/page.tsx`
+- `src/app/blog/rss.xml/route.ts`
+- `src/app/sitemaps/blog-posts.xml/route.ts`
+- `src/app/sitemaps/blog-authors.xml/route.ts`
+- `src/app/sitemaps/blog-categories.xml/route.ts`
+- `src/app/sitemaps/blog-tags.xml/route.ts`
+- `src/app/sitemap.xml/route.ts` when no root sitemap exists
+- `src/app/robots.ts` when no robots route/file exists
+
+Customers should edit the generated component and CSS files to match their
+site. The package remains the maintained source for CMS and SEO primitives.
+
+If a project already has `payload.config.*`, the v1 installer refuses to
+overwrite it. Add `@founderhq/payload-cms-kit` manually through
+`founderHQBlogPlugin()` or the collection/global factories so existing Payload
+collections, plugins, access rules, and storage settings stay intact.
+
+For non-Next projects, the CLI does not generate public framework routes. It
+creates `payload.config.ts`, storage config, framework-neutral blog data
+helpers, env/scripts, and `FOUNDERHQ_BLOG_INTEGRATION.md` with the exact route,
+RSS, robots, and sitemap contract to implement in that framework.
+
+## Sitemaps
+
+Fresh installs create this structure:
+
+- `/sitemap.xml` as a sitemap index
+- `/sitemaps/blog-posts.xml` for blog index pagination and article URLs
+- `/sitemaps/blog-authors.xml` for the author directory, author pages, and
+  author archive pagination
+- `/sitemaps/blog-categories.xml` for the category directory, category pages,
+  and category archive pagination
+- `/sitemaps/blog-tags.xml` for the tag directory, tag pages, and tag archive
+  pagination
+
+If the target app already has a simple `app/sitemap.ts`, the installer patches
+that metadata sitemap to include indexable blog URLs directly, because Next
+metadata sitemaps emit URL sets rather than sitemap indexes. If the target has
+a static `public/sitemap.xml` that is already a sitemap index, the installer
+adds the blog child sitemap links. If the existing sitemap is a custom route
+handler or a static URL set that cannot be patched safely, the installer still
+creates `/sitemaps/blog-*.xml` routes and prints manual merge instructions.
+
+The generated blog sitemap excludes posts marked `noindex` and posts with an
+external canonical URL.
+
+## Other SEO Routes
+
+Fresh installs generate a `robots.ts` route pointing crawlers at `/sitemap.xml`.
+If a project already has static `public/robots.txt`, the installer appends a
+missing `Sitemap:` line. Existing app robots metadata routes are not force
+patched; the installer warns if one does not appear to include a sitemap.
+
+Generated blog routes include canonical metadata for the blog index, `noindex`
+metadata for search results, JSON-LD for articles, RSS, manual redirect support,
+previous-slug redirects from Payload slug history, and canonical metadata for
+author, category, tag, and paginated archive routes.
+
+## Runtime helpers
+
+```ts
+import { buildArticleJsonLd, buildRssXml } from "@founderhq/next-blog/server";
+```
+
+The server helpers normalize Payload REST documents into renderable articles,
+including stored Lexical HTML, heading IDs, TOC items, JSON-LD, RSS, sitemap
+entries, robots config, redirects, and adapter-neutral search.
+
+The package still exports `@founderhq/next-blog/components` and
+`@founderhq/next-blog/styles.css` for compatibility, but new installs use local
+editable templates.

package/dist/cli/core.d.ts

@@ -0,0 +1,61 @@
+export type DbChoice = "postgres" | "sqlite-local" | "turso";
+export type StorageChoice = "local" | "s3" | "r2" | "vercel-blob" | "azure" | "gcs" | "uploadthing" | "custom";
+export type MigrationChoice = "skip" | "scripts" | "run";
+export type InitOptions = {
+    projectRoot: string;
+    db: DbChoice;
+    storage: StorageChoice;
+    adminPath?: string;
+    routePrefix?: string;
+    postgresSchema?: string;
+    migration?: MigrationChoice;
+    env?: Partial<Record<string, string>>;
+};
+export type FileChange = {
+    path: string;
+    kind: "create" | "update";
+    content: string;
+};
+export type InstallPlan = {
+    appDir: string;
+    dependencies: Record<string, string>;
+    devDependencies: Record<string, string>;
+    env: Record<string, string>;
+    changes: FileChange[];
+    scripts: Record<string, string>;
+    installCommand: string | null;
+    migrationCommand: string | null;
+    warnings: string[];
+};
+export type PackageJsonDependencyShape = Record<string, unknown> & {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+};
+export declare function choiceFromValue<const T extends readonly string[]>(value: string | undefined, name: string, choices: T): T[number] | undefined;
+export declare const STORAGE_DEPENDENCIES: {
+    local: {};
+    s3: {
+        "@payloadcms/storage-s3": string;
+    };
+    r2: {
+        "@payloadcms/storage-r2": string;
+    };
+    "vercel-blob": {
+        "@payloadcms/storage-vercel-blob": string;
+    };
+    azure: {
+        "@payloadcms/storage-azure": string;
+    };
+    gcs: {
+        "@payloadcms/storage-gcs": string;
+    };
+    uploadthing: {
+        "@payloadcms/storage-uploadthing": string;
+    };
+    custom: {};
+};
+export declare function mergeMissingPackageEntries(pkg: PackageJsonDependencyShape, dependencies: Record<string, string>, devDependencies: Record<string, string>): PackageJsonDependencyShape;
+export declare function missingMigrationEnv(plan: Pick<InstallPlan, "env">, env?: NodeJS.ProcessEnv): string[];
+export declare function detectAppDir(projectRoot: string): string | null;
+export declare function createInstallPlan(options: InitOptions): InstallPlan;
+//# sourceMappingURL=core.d.ts.map

package/dist/cli/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/cli/core.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,cAAc,GAAG,OAAO,CAAC;AAC7D,MAAM,MAAM,aAAa,GACrB,OAAO,GACP,IAAI,GACJ,IAAI,GACJ,aAAa,GACb,OAAO,GACP,KAAK,GACL,aAAa,GACb,QAAQ,CAAC;AACb,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,KAAK,CAAC;AAEzD,MAAM,MAAM,WAAW,GAAG;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,QAAQ,CAAC;IACb,OAAO,EAAE,aAAa,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,GAAG,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C,CAAC;AAEF,wBAAgB,eAAe,CAAC,KAAK,CAAC,CAAC,SAAS,SAAS,MAAM,EAAE,EAC/D,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,CAAC,yBAKX;AAiED,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;CASwB,CAAC;AA4E1D,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,0BAA0B,EAC/B,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,8BA2BxC;AAaD,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,EAC9B,GAAG,GAAE,MAAM,CAAC,UAAwB,YAKrC;AAED,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,iBAM/C;AAqjDD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW,CAgfnE"}