@forumone/create-throughline 0.0.1 → 0.2.1

package/dist/templates/base/.env.example

@@ -0,0 +1,43 @@
+# --- Required ---
+DATABASE_URI=postgres://user:pass@host/dbname
+PAYLOAD_SECRET=generate-with-openssl-rand-base64-48
+NEXT_PUBLIC_SERVER_URL=http://localhost:3000
+
+# --- Inngest ---
+# Leave blank in local dev; use the inngest dev server (npx inngest-cli dev).
+# Set both in production after creating an Inngest app.
+INNGEST_EVENT_KEY=
+INNGEST_SIGNING_KEY=
+
+# --- Resend (for approval + form notification emails) ---
+RESEND_API_KEY=
+EMAIL_FROM_ADDRESS=notifications@example.com
+EMAIL_FROM_NAME={{projectName}}
+EMAIL_REPLY_TO=
+
+# --- Approval tokens ---
+# Generate: openssl rand -base64 48
+APPROVAL_TOKEN_SECRET=
+
+# --- Forms ---
+# Generate: openssl rand -base64 48
+FORMS_IP_HASH_SECRET=
+
+# --- MCP server keys ---
+# Each key is generated in the Payload admin (API Keys collection) after
+# first deploy and pasted back here for local dev.
+COMPONENT_SERVER_API_KEY=
+PUBLISHING_SERVER_API_KEY=
+APPROVALS_SERVER_API_KEY=
+AUDIT_SERVER_API_KEY=
+FORMS_SERVER_API_KEY=
+INTEGRATIONS_SERVER_API_KEY=
+
+# System API key used by scheduled workflows that talk back to the
+# Publishing MCP server (executes scheduled publishes).
+PUBLISHING_SYSTEM_API_KEY=
+
+# --- Optional: storage ---
+# Vercel Blob token if deploying to Vercel; remove this and the storage
+# adapter from payload.config.ts if you're using a different provider.
+BLOB_READ_WRITE_TOKEN=

package/dist/templates/base/README.md

@@ -0,0 +1,96 @@
+# {{projectName}}
+
+Generated by [`@forumone/create-throughline`](https://github.com/forumone/throughline/tree/main/packages/create-throughline).
+
+This is a Throughline project: a Payload CMS application wired with the Throughline plugin suite (audit, components, publishing, approvals, audit-query, integrations, email, forms) plus an Inngest endpoint that runs the workflow functions.
+
+## Prerequisites
+
+- Node.js >= 20.9
+- pnpm >= 10
+- A Postgres database (Neon / Supabase / self-hosted)
+- An [Inngest](https://inngest.com) account (free tier is fine for development)
+- A [Resend](https://resend.com) API key for transactional email
+
+## First-time setup
+
+```bash
+# 1. Install deps (skip if you let the scaffolder do it)
+pnpm install
+
+# 2. Copy the env template
+cp .env.example .env.local
+
+# 3. Generate secrets (run each three times for the three secret slots)
+openssl rand -base64 48
+
+# 4. Edit .env.local and fill in:
+#    - DATABASE_URI                — your Postgres connection string
+#    - PAYLOAD_SECRET               — generated above
+#    - APPROVAL_TOKEN_SECRET        — generated above
+#    - FORMS_IP_HASH_SECRET         — generated above
+#    - RESEND_API_KEY               — from Resend dashboard
+#    - INNGEST_EVENT_KEY/SIGNING    — from Inngest (optional in local dev)
+
+# 5. Start the dev server
+pnpm dev
+
+# 6. Visit http://localhost:3000/admin and create your first user.
+```
+
+## After admin signup
+
+1. In the Payload admin, open the **API Keys** collection and create one key per MCP server (Component, Publishing, Approvals, Audit, Forms, Integrations). Paste each key into `.env.local` (`COMPONENT_SERVER_API_KEY`, etc.) and restart `pnpm dev`.
+
+2. **Plug the MCP servers into Claude (or your MCP client).** The endpoints are:
+
+   ```
+   /api/components/mcp
+   /api/publishing/mcp
+   /api/approvals/mcp
+   /api/audit/mcp
+   /api/forms/mcp
+   /api/integrations/mcp
+   ```
+
+   Authenticate with the corresponding API key from `.env.local`.
+
+3. **Replace the example `pages` collection** in `apps/web/src/payload.config.ts` with your real content model. Keep the `policy` group on collections that should require approval — that field shape is what the approvals plugin reads.
+
+4. **Implement the user/group resolvers** in `payload.config.ts`. The scaffold ships with stub functions that return empty arrays so the app compiles; the approvals plugin won't actually work until they're real.
+
+## Development
+
+- `pnpm dev` — start Next.js + Payload in dev mode
+- `pnpm build` — production build
+- `pnpm typecheck` — TypeScript check across the monorepo
+- `pnpm lint` — ESLint
+- `pnpm test` — run all package tests
+
+## Project layout
+
+```
+{{projectName}}/
+├── apps/
+│   └── web/                  # Next.js + Payload host
+├── packages/
+│   ├── design-system/        # UI components consumed by Components MCP
+│   ├── content/              # Reusable collections + blocks (optional)
+│   └── brand/                # Brand tokens / email theme (optional)
+├── .env.example
+├── pnpm-workspace.yaml
+├── turbo.json
+└── tsconfig.json
+```
+
+## Documentation
+
+Throughline docs: https://github.com/forumone/throughline
+
+Payload docs: https://payloadcms.com/docs
+
+Inngest docs: https://www.inngest.com/docs
+
+## License
+
+UNLICENSED — generated project. Add your own license file before publishing.

package/dist/templates/base/apps/web/next-env.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/dist/templates/base/apps/web/next.config.mjs

@@ -0,0 +1,10 @@
+import { withPayload } from '@payloadcms/next/withPayload'
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  experimental: {
+    reactCompiler: false,
+  },
+}
+
+export default withPayload(nextConfig)

package/dist/templates/base/apps/web/package.json.template

@@ -0,0 +1,42 @@
+{
+  "name": "{{#if packageScope}}@{{packageScope}}/web{{else}}{{projectName}}-web{{/if}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "clean": "rm -rf .next .turbo",
+    "typecheck": "tsc --noEmit",
+    "payload": "payload"
+  },
+  "dependencies": {
+    "@forumone/throughline-approvals": "^0.2.0",
+    "@forumone/throughline-audit": "^0.2.0",
+    "@forumone/throughline-components": "^0.2.0",
+    "@forumone/throughline-core": "^0.2.0",
+    "@forumone/throughline-email": "^0.2.0",
+    "@forumone/throughline-forms": "^0.2.0",
+    "@forumone/throughline-integrations": "^0.2.0",
+    "@forumone/throughline-publishing": "^0.2.0",
+    "@forumone/throughline-workflows": "^0.2.0",
+    {{#if useReferenceDs}}"@forumone/throughline-reference-ds": "^0.2.0",
+    {{/if}}"@payloadcms/db-postgres": "^3.83.0",
+    "@payloadcms/next": "^3.83.0",
+    "@payloadcms/plugin-form-builder": "3.83.0",
+    "@payloadcms/richtext-lexical": "^3.83.0",
+    "graphql": "^16.8.1",
+    "inngest": "^4.2.0",
+    "next": "^16.2.4",
+    "payload": "^3.83.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "typescript": "^5.6.0"
+  }
+}

package/dist/templates/base/apps/web/src/app/(frontend)/layout.tsx

@@ -0,0 +1,22 @@
+import type { ReactNode } from 'react'
+
+export const metadata = {
+  title: '{{projectName}}',
+  description: 'Powered by Payload CMS + Throughline',
+}
+
+export default function FrontendLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body
+        style={{
+          fontFamily: 'system-ui, -apple-system, sans-serif',
+          margin: 0,
+          padding: 0,
+        }}
+      >
+        {children}
+      </body>
+    </html>
+  )
+}

package/dist/templates/base/apps/web/src/app/(frontend)/page.tsx

@@ -0,0 +1,18 @@
+export default function HomePage() {
+  return (
+    <main style={{ padding: '4rem 2rem', maxWidth: 720, margin: '0 auto' }}>
+      <h1>{{projectName}}</h1>
+      <p>
+        This is a placeholder home page generated by{' '}
+        <code>@forumone/create-throughline</code>.
+      </p>
+      <p>
+        Visit{' '}
+        <a href="/admin">
+          <code>/admin</code>
+        </a>{' '}
+        to set up your first user, then replace this page with your real frontend.
+      </p>
+    </main>
+  )
+}

package/dist/templates/base/apps/web/src/app/(payload)/admin/[[...segments]]/not-found.tsx

@@ -0,0 +1,12 @@
+import configPromise from '@payload-config'
+import { NotFoundPage } from '@payloadcms/next/views'
+import { importMap } from '../importMap.js'
+
+type Args = {
+  params: Promise<{ segments: string[] }>
+  searchParams: Promise<Record<string, string | string[]>>
+}
+
+export default function NotFound({ params, searchParams }: Args) {
+  return NotFoundPage({ config: configPromise, importMap, params, searchParams })
+}

package/dist/templates/base/apps/web/src/app/(payload)/admin/[[...segments]]/page.tsx

@@ -0,0 +1,16 @@
+import type { Metadata } from 'next'
+import configPromise from '@payload-config'
+import { generatePageMetadata, RootPage } from '@payloadcms/next/views'
+import { importMap } from '../importMap.js'
+
+type Args = {
+  params: Promise<{ segments: string[] }>
+  searchParams: Promise<Record<string, string | string[]>>
+}
+
+export const generateMetadata = ({ params, searchParams }: Args): Promise<Metadata> =>
+  generatePageMetadata({ config: configPromise, params, searchParams })
+
+export default function Page({ params, searchParams }: Args) {
+  return RootPage({ config: configPromise, importMap, params, searchParams })
+}

package/dist/templates/base/apps/web/src/app/(payload)/admin/importMap.js

@@ -0,0 +1,6 @@
+// This file is regenerated by `pnpm payload generate:importmap`. The
+// initial export below is a stub so the app compiles before the first
+// generation; payload will rewrite it on first run / when richtext
+// features are added.
+/** @type import('payload').ImportMap */
+export const importMap = {}

package/dist/templates/base/apps/web/src/app/(payload)/api/[...slug]/route.ts

@@ -0,0 +1,16 @@
+import configPromise from '@payload-config'
+import {
+  REST_DELETE,
+  REST_GET,
+  REST_OPTIONS,
+  REST_PATCH,
+  REST_POST,
+  REST_PUT,
+} from '@payloadcms/next/routes'
+
+export const DELETE = REST_DELETE(configPromise)
+export const GET = REST_GET(configPromise)
+export const OPTIONS = REST_OPTIONS(configPromise)
+export const PATCH = REST_PATCH(configPromise)
+export const POST = REST_POST(configPromise)
+export const PUT = REST_PUT(configPromise)

package/dist/templates/base/apps/web/src/app/(payload)/layout.tsx

@@ -0,0 +1,23 @@
+import type { ServerFunctionClient } from 'payload'
+import configPromise from '@payload-config'
+import { handleServerFunctions, RootLayout } from '@payloadcms/next/layouts'
+import React from 'react'
+import { importMap } from './admin/importMap.js'
+import '@payloadcms/next/css'
+
+const serverFunction: ServerFunctionClient = async function (args) {
+  'use server'
+  return handleServerFunctions({
+    ...args,
+    config: configPromise,
+    importMap,
+  })
+}
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <RootLayout config={configPromise} importMap={importMap} serverFunction={serverFunction}>
+      {children}
+    </RootLayout>
+  )
+}

package/dist/templates/base/apps/web/src/app/api/inngest/route.ts.template

@@ -0,0 +1,56 @@
+import { serve } from 'inngest/next'
+import { getPayload } from 'payload'
+import config from '@/payload.config'
+import { createInngestClient } from '@forumone/throughline-core'
+import {
+  createAuditEventEchoFunction,
+  createExecuteScheduledPublishesFunction,
+  createExpireStaleApprovalsFunction,
+  createHealthcheckFunction,
+  createPayloadReachableCheck,
+  createRevalidateOnPublishFunction,
+} from '@forumone/throughline-workflows'
+import { getEmailFunctions } from '@forumone/throughline-email'
+import { getFormsFunctions } from '@forumone/throughline-forms'
+import {
+  getIntegrationContext,
+  getIntegrationRegistry,
+} from '@forumone/throughline-integrations'
+
+const inngest = createInngestClient({ id: '{{projectName}}' })
+const payload = await getPayload({ config })
+
+const emailFunctions = getEmailFunctions(payload) ?? []
+const formsFunctions = getFormsFunctions(payload) ?? []
+const integrationRegistry = getIntegrationRegistry(payload)
+const integrationContext = getIntegrationContext(payload)
+const integrationFunctions =
+  integrationRegistry && integrationContext
+    ? integrationRegistry
+        .list()
+        .flatMap((integration) => integration.createFunctions(integrationContext))
+    : []
+
+export const { GET, POST, PUT } = serve({
+  client: inngest,
+  functions: [
+    createRevalidateOnPublishFunction({ inngest, payload }),
+    createExecuteScheduledPublishesFunction({
+      inngest,
+      payload,
+      collections: [{ slug: 'pages' }],
+      publishingServerUrl: process.env.NEXT_PUBLIC_SERVER_URL!,
+      systemApiKey: process.env.PUBLISHING_SYSTEM_API_KEY!,
+    }),
+    createExpireStaleApprovalsFunction({ inngest, payload }),
+    createAuditEventEchoFunction({ inngest }),
+    createHealthcheckFunction({
+      inngest,
+      payload,
+      checks: [createPayloadReachableCheck({ payload })],
+    }),
+    ...emailFunctions,
+    ...formsFunctions,
+    ...integrationFunctions,
+  ],
+})

package/dist/templates/base/apps/web/src/payload.config.ts.template

@@ -0,0 +1,164 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { buildConfig } from 'payload'
+import type { CollectionConfig } from 'payload'
+import { postgresAdapter } from '@payloadcms/db-postgres'
+import { lexicalEditor } from '@payloadcms/richtext-lexical'
+import {
+  auditPlugin,
+  createApiKeysCollection,
+  createInngestClient,
+} from '@forumone/throughline-core'
+import { componentsPlugin } from '@forumone/throughline-components'
+import { publishingPlugin } from '@forumone/throughline-publishing'
+import { approvalsPlugin } from '@forumone/throughline-approvals'
+import { auditQueryPlugin } from '@forumone/throughline-audit'
+import { integrationsPlugin } from '@forumone/throughline-integrations'
+import { emailPlugin } from '@forumone/throughline-email'
+import { formsPlugin } from '@forumone/throughline-forms'
+{{#if useReferenceDs}}import referenceManifest from '@forumone/throughline-reference-ds/manifest' with { type: 'json' }
+{{/if}}
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+const inngest = createInngestClient({ id: '{{projectName}}' })
+
+// Users collection — extend with your own fields and SSO/auth provider.
+const Users: CollectionConfig = {
+  slug: 'users',
+  auth: true,
+  admin: { useAsTitle: 'email' },
+  fields: [
+    { name: 'name', type: 'text' },
+    {
+      name: 'roles',
+      type: 'select',
+      hasMany: true,
+      defaultValue: ['admin'],
+      options: ['admin', 'editor', 'approver', 'form-admin'],
+    },
+    {
+      name: 'groups',
+      type: 'select',
+      hasMany: true,
+      options: ['editorial', 'legal', 'communications', 'senior'],
+    },
+  ],
+}
+
+// Example Pages collection. Replace this with your real content model;
+// keep the `policy` group on collections that should require approval —
+// the approvals plugin reads that field shape.
+const Pages: CollectionConfig = {
+  slug: 'pages',
+  admin: { useAsTitle: 'title' },
+  versions: { drafts: true },
+  fields: [
+    { name: 'title', type: 'text', required: true },
+    { name: 'slug', type: 'text', required: true, unique: true },
+    {
+      name: 'seo',
+      type: 'group',
+      fields: [
+        { name: 'title', type: 'text' },
+        { name: 'description', type: 'textarea' },
+      ],
+    },
+    {
+      name: 'policy',
+      type: 'group',
+      fields: [
+        { name: 'requiresApproval', type: 'checkbox', defaultValue: false },
+        {
+          name: 'approverGroups',
+          type: 'select',
+          hasMany: true,
+          options: ['editorial', 'legal', 'communications', 'senior'],
+        },
+        { name: 'embargoedUntil', type: 'date' },
+      ],
+    },
+    { name: 'publishedAt', type: 'date' },
+    { name: 'scheduledPublishAt', type: 'date' },
+  ],
+}
+
+export default buildConfig({
+  admin: { user: 'users' },
+  editor: lexicalEditor(),
+  db: postgresAdapter({
+    pool: { connectionString: process.env.DATABASE_URI! },
+  }),
+  collections: [Users, Pages, createApiKeysCollection()],
+  secret: process.env.PAYLOAD_SECRET!,
+  typescript: {
+    outputFile: path.resolve(__dirname, 'payload-types.ts'),
+  },
+  plugins: [
+    // Order matters: audit first (so other plugins can write to it),
+    // then content plugins, then notification/forms/integrations.
+    auditPlugin({ inngest }),
+
+    componentsPlugin({
+      {{#if useReferenceDs}}manifest: { type: 'object', manifest: referenceManifest },
+      {{else}}// TODO: point at your design system manifest
+      manifest: { type: 'url', url: 'https://your-design-system.example.com/manifest.json' },
+      {{/if}}matching: { strategy: 'tfidf' },
+    }),
+
+    publishingPlugin({
+      collections: [{ slug: 'pages' }],
+      inngest,
+      // Lazy-resolve approvals at call time so plugin order doesn't matter.
+      approvalResolver: {
+        getActiveApproval: async () => null, // TODO: wire to approvals plugin
+      },
+    }),
+
+    approvalsPlugin({
+      inngest,
+      groups: [
+        { slug: 'editorial', name: 'Editorial' },
+        { slug: 'legal', name: 'Legal' },
+        { slug: 'communications', name: 'Communications' },
+        { slug: 'senior', name: 'Senior leadership' },
+      ],
+      groupResolver: {
+        // TODO: replace with your actual user/group lookup (DB query, SSO, etc.)
+        async resolveUsers(_groupSlugs) {
+          return []
+        },
+      },
+    }),
+
+    auditQueryPlugin(),
+
+    emailPlugin({
+      inngest,
+      // TODO: replace with your real user lookups
+      resolveApprover: async (_userId) => null,
+      resolveRequester: async (_userId) => null,
+      buildActionUrl: ({ token, action }) =>
+        `${process.env.NEXT_PUBLIC_SERVER_URL}/api/approvals/decision?token=${token}&action=${action}`,
+      tokens: { brandName: '{{projectName}}' },
+    }),
+
+    formsPlugin({
+      inngest,
+      ipHashSecret: process.env.FORMS_IP_HASH_SECRET!,
+      // TODO: list every place a form is allowed to send to. The plugin
+      // refuses to deliver to destinations that aren't in this list.
+      allowedDestinations: [
+        // {
+        //   type: 'email',
+        //   value: 'team@example.com',
+        //   label: 'Main inbox',
+        //   description: 'General contact form destination',
+        // },
+      ],
+    }),
+
+    integrationsPlugin({ inngest }),
+  ],
+})

package/dist/templates/base/apps/web/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "preserve",
+    "allowJs": true,
+    "noEmit": true,
+    "incremental": true,
+    "isolatedModules": true,
+    "plugins": [{ "name": "next" }],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts"
+  ],
+  "exclude": ["node_modules", ".next"]
+}

package/dist/templates/base/package.json.template

@@ -0,0 +1,23 @@
+{
+  "name": "{{projectName}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "turbo run build",
+    "dev": "turbo run dev",
+    "lint": "turbo run lint",
+    "typecheck": "turbo run typecheck",
+    "test": "turbo run test",
+    "format": "prettier --write ."
+  },
+  "devDependencies": {
+    "prettier": "^3.4.0",
+    "turbo": "^2.3.0",
+    "typescript": "^5.6.0"
+  },
+  "packageManager": "pnpm@10.33.0",
+  "engines": {
+    "node": ">=20.9.0",
+    "pnpm": ">=10.0.0"
+  }
+}

package/dist/templates/base/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+packages:
+  - apps/*
+  - packages/*

package/dist/templates/base/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true
+  }
+}

package/dist/templates/base/turbo.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://turborepo.com/schema.json",
+  "ui": "stream",
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**", ".next/**", "!.next/cache/**"],
+      "env": ["NODE_ENV"]
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    },
+    "lint": {
+      "dependsOn": ["^build"]
+    },
+    "typecheck": {
+      "dependsOn": ["^build"]
+    },
+    "test": {
+      "dependsOn": ["^build"]
+    },
+    "clean": {
+      "cache": false
+    }
+  }
+}

package/dist/templates/with-reference-ds/packages/design-system/package.json.template

@@ -0,0 +1,18 @@
+{
+  "name": "{{#if packageScope}}@{{packageScope}}/design-system{{else}}{{projectName}}-design-system{{/if}}",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./manifest": "./src/manifest.ts"
+  },
+  "dependencies": {
+    "@forumone/throughline-reference-ds": "^0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}

package/dist/templates/with-reference-ds/packages/design-system/src/index.ts

@@ -0,0 +1,6 @@
+// Re-export the Throughline reference design system. Wrap or override
+// individual components here when you start building your own brand layer
+// (e.g. swap colors, replace Hero, add new components). When you have
+// enough custom work to stand alone, drop the reference DS dependency
+// and replace this file with your own component exports.
+export * from '@forumone/throughline-reference-ds'