@plutocms/core 0.47.0 → 0.48.0

package/modules/pluto-github/runtime/shared/client-rules.ts

@@ -43,3 +43,19 @@ export function showBuildStatus(
 ): boolean {
   return config?.storage === 'github' && config.skipDeploy === false
 }
+
+/**
+ * Whether an item is on the public site: a type with no status, or an item with the published
+ * value. A missing status counts as the default. The edit form hides the build status for a draft
+ * that was never public in the page: its saves skip the deploy.
+ */
+export function isPublicItem(
+  type: Pick<PlutoContentType, 'status'> | undefined,
+  item: Record<string, unknown>
+): boolean {
+  if (!type?.status) {
+    return true
+  }
+  const value = item[type.status.column ?? 'status'] ?? type.status.default
+  return value === (type.status.publishedValue || 'published')
+}

package/modules/pluto-github/runtime/shared/deploy.ts

@@ -0,0 +1,43 @@
+import type { PackageManager } from './pages-workflow'
+
+/** The state of GitHub Pages for the repo, read with the GitHub CLI of this computer. */
+export interface PlutoPagesState {
+  /** `on`: Pages is on. `off`: GitHub answered 404. `unknown`: the CLI could not tell. */
+  state: 'on' | 'off' | 'unknown'
+  url?: string
+  /** `workflow`: the site comes from an Action. `legacy`: from a branch. */
+  source?: 'workflow' | 'legacy'
+  /** Why the state is unknown: no `gh`, `gh` not signed in, or another failure. */
+  reason?: 'no-gh' | 'signed-out' | 'error'
+}
+
+/** The answer of `GET /api/_pluto/github/deploy/status`. */
+export interface PlutoDeployStatus {
+  repo: string
+  branch: string
+  /** True for local mode on this computer: the page can write the workflow and run `gh`. */
+  local: boolean
+  packageManager: PackageManager
+  workflow: {
+    path: string
+    /** Local mode only: the file is in the project. */
+    exists?: boolean
+    /** Local mode only: the file is the one that Pluto writes now. */
+    current?: boolean
+    /** The workflow to copy, for a setup by hand. */
+    text: string
+  }
+  /** Local mode only. */
+  pages?: PlutoPagesState
+  /** The default address of the Pages site. */
+  pagesUrl: string
+}
+
+/** The answer of `POST /api/_pluto/github/deploy/pages`. */
+export interface PlutoPagesSetupResult {
+  status: PlutoDeployStatus
+  /** The workflow was written and committed. */
+  committed: boolean
+  /** Pages was turned on (or was on already) with the Actions source. */
+  pagesOn: boolean
+}

package/modules/pluto-github/runtime/shared/pages-workflow.ts

@@ -0,0 +1,138 @@
+/** The path of the GitHub Pages workflow that the Deploy page writes. */
+export const PAGES_WORKFLOW_PATH = '.github/workflows/pluto-pages.yml'
+
+export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun'
+
+/** The lock file of each package manager, in the order the check reads them. */
+const LOCK_FILES: [string, PackageManager][] = [
+  ['bun.lock', 'bun'],
+  ['bun.lockb', 'bun'],
+  ['pnpm-lock.yaml', 'pnpm'],
+  ['yarn.lock', 'yarn'],
+  ['package-lock.json', 'npm'],
+]
+
+/** The package manager of a project, from the files at its root. Default npm. */
+export function detectPackageManager(files: readonly string[]): PackageManager {
+  const names = new Set(files)
+  return LOCK_FILES.find(([file]) => names.has(file))?.[1] ?? 'npm'
+}
+
+/** A GitHub Actions expression: `${{ <expression> }}` in the workflow. */
+function actionsExpression(expression: string): string {
+  return ['$', '{{ ', expression, ' }}'].join('')
+}
+
+/** The setup and install steps of each package manager, and the build command, as YAML lines. */
+function buildSteps(manager: PackageManager): {
+  setup: string[]
+  build: string
+} {
+  const node = [
+    '      - uses: actions/setup-node@v4',
+    '        with:',
+    '          node-version: 22',
+  ]
+  switch (manager) {
+    case 'bun':
+      return {
+        setup: [
+          '      - uses: oven-sh/setup-bun@v2',
+          '      - run: bun install --frozen-lockfile',
+        ],
+        build: 'bunx nuxt build --preset github_pages',
+      }
+    case 'pnpm':
+      return {
+        setup: [
+          '      - uses: pnpm/action-setup@v4',
+          ...node,
+          '          cache: pnpm',
+          '      - run: pnpm install --frozen-lockfile',
+        ],
+        build: 'pnpm exec nuxt build --preset github_pages',
+      }
+    case 'yarn':
+      return {
+        setup: [
+          ...node,
+          '          cache: yarn',
+          '      - run: yarn install --frozen-lockfile',
+        ],
+        build: 'yarn nuxt build --preset github_pages',
+      }
+    default:
+      return {
+        setup: [...node, '          cache: npm', '      - run: npm ci'],
+        build: 'npx nuxt build --preset github_pages',
+      }
+  }
+}
+
+/**
+ * The GitHub Actions workflow that builds the site as static files and deploys it to GitHub
+ * Pages, on each push to the content branch. The build reads the Markdown of the checkout, so it
+ * needs no secret. `PLUTO_BASE_URL` gets the sub path of a project site (`/<repo>`), or nothing
+ * for a user site or a custom domain.
+ */
+export function renderPagesWorkflow(options: {
+  branch: string
+  packageManager: PackageManager
+}): string {
+  const { setup, build } = buildSteps(options.packageManager)
+  return [
+    '# Builds the site as static files and deploys it to GitHub Pages, on each push.',
+    '# Pluto wrote this file. The build reads the Markdown of the repo: it needs no secret.',
+    'name: Deploy to GitHub Pages',
+    '',
+    'on:',
+    '  push:',
+    `    branches: [${JSON.stringify(options.branch)}]`,
+    '  workflow_dispatch:',
+    '',
+    'permissions:',
+    '  contents: read',
+    '  pages: write',
+    '  id-token: write',
+    '',
+    'concurrency:',
+    '  group: pages',
+    '  cancel-in-progress: true',
+    '',
+    'jobs:',
+    '  build:',
+    '    runs-on: ubuntu-latest',
+    '    steps:',
+    '      - uses: actions/checkout@v4',
+    '      - id: pages',
+    '        uses: actions/configure-pages@v5',
+    ...setup,
+    `      - run: ${build}`,
+    '        env:',
+    '          # A project site lives under /<repo>. A user site or a custom domain has no path.',
+    `          PLUTO_BASE_URL: ${actionsExpression('steps.pages.outputs.base_path')}`,
+    '      - uses: actions/upload-pages-artifact@v3',
+    '        with:',
+    '          path: .output/public',
+    '',
+    '  deploy:',
+    '    needs: build',
+    '    runs-on: ubuntu-latest',
+    '    environment:',
+    '      name: github-pages',
+    `      url: ${actionsExpression('steps.deployment.outputs.page_url')}`,
+    '    steps:',
+    '      - id: deployment',
+    '        uses: actions/deploy-pages@v4',
+    '',
+  ].join('\n')
+}
+
+/** The default address of a GitHub Pages site: `https://<owner>.github.io/<repo>/`. */
+export function defaultPagesUrl(repo: string): string {
+  const [owner = '', name = ''] = repo.split('/')
+  const host = `${owner.toLowerCase()}.github.io`
+  return name.toLowerCase() === host
+    ? `https://${host}/`
+    : `https://${host}/${name}/`
+}

package/modules/pluto-github/runtime/shared/repo-users.ts

@@ -0,0 +1,97 @@
+/** The GitHub role of a user who can sign in: admin, maintain, or write (push). */
+export type PlutoGithubRepoRole = 'admin' | 'maintain' | 'write'
+
+/** One person with write access to the content repo. */
+export interface PlutoGithubRepoUser {
+  id: number
+  login: string
+  avatarUrl: string
+  /** The GitHub profile. */
+  url: string
+  role: PlutoGithubRepoRole
+  /** False when `ALLOWED_USERS` is set and does not have this login. */
+  canSignIn: boolean
+}
+
+/**
+ * The answer of `GET /api/_pluto/github/users`. `users` is empty with a `reason` when the list
+ * cannot load: `no-repo` (no repo is known), `no-app` (local mode with no GitHub App and no read
+ * token, so there is no token to ask GitHub) or `app-error` (local mode: the App gave no token; it
+ * is not installed on the repo, or its key is wrong).
+ */
+export interface PlutoGithubUsersResponse {
+  repo: string
+  users: PlutoGithubRepoUser[]
+  /** True when `ALLOWED_USERS` limits the sign-in. */
+  restricted: boolean
+  reason?: 'no-repo' | 'no-app' | 'app-error'
+}
+
+/** The parts of a GitHub collaborator that Pluto reads. */
+export interface GithubCollaborator {
+  id: number
+  login: string
+  avatar_url?: string
+  html_url?: string
+  role_name?: string
+  permissions?: {
+    admin?: boolean
+    maintain?: boolean
+    push?: boolean
+  }
+}
+
+/** The role of a collaborator, or `null` when it cannot push (triage, read). */
+export function repoRoleOf(
+  collaborator: GithubCollaborator
+): PlutoGithubRepoRole | null {
+  const permissions = collaborator.permissions ?? {}
+  if (permissions.admin || collaborator.role_name === 'admin') {
+    return 'admin'
+  }
+  if (permissions.maintain || collaborator.role_name === 'maintain') {
+    return 'maintain'
+  }
+  if (permissions.push || collaborator.role_name === 'write') {
+    return 'write'
+  }
+  return null
+}
+
+const ROLE_ORDER: Record<PlutoGithubRepoRole, number> = {
+  admin: 0,
+  maintain: 1,
+  write: 2,
+}
+
+/**
+ * Turns the collaborators into the users of the page: only the ones who can push, admins first,
+ * then by login. `allowedUsers` holds lowercase logins; empty means every user can sign in.
+ */
+export function toRepoUsers(
+  collaborators: GithubCollaborator[],
+  allowedUsers: readonly string[]
+): PlutoGithubRepoUser[] {
+  const users: PlutoGithubRepoUser[] = []
+  for (const collaborator of collaborators) {
+    const role = repoRoleOf(collaborator)
+    if (!role) {
+      continue
+    }
+    users.push({
+      id: collaborator.id,
+      login: collaborator.login,
+      avatarUrl: collaborator.avatar_url ?? '',
+      url: collaborator.html_url ?? `https://github.com/${collaborator.login}`,
+      role,
+      canSignIn:
+        allowedUsers.length === 0 ||
+        allowedUsers.includes(collaborator.login.toLowerCase()),
+    })
+  }
+  return users.sort(
+    (a, b) =>
+      ROLE_ORDER[a.role] - ROLE_ORDER[b.role] ||
+      a.login.localeCompare(b.login, 'en', { sensitivity: 'base' })
+  )
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plutocms/core",
   "type": "module",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "description": "The base layer every Pluto app extends: the admin, the content model, and the Git CMS",
   "author": "Victor Ribeiro",
   "license": "MIT",

package/shared/types/github.d.ts

@@ -40,6 +40,8 @@ declare module '@nuxt/schema' {
       postType: boolean
       /** True when a save adds `[skip ci]`. The build status item shows only when this is false. */
       skipDeploy: boolean
+      /** A static build (`nuxt generate`, `github_pages`): no server, so no session request. */
+      static: boolean
     }
   }
 }

package/shared/types/registry.ts

@@ -355,6 +355,26 @@ export interface PlutoSiteInfo extends PlutoEntry {
   url?: () => string | null | undefined
 }
 
+/**
+ * The backend that stores the content: a Git repo or a database. The admin navbar shows the
+ * last registered one as a badge, with a popover. See the admin-shell skill.
+ */
+export interface PlutoBackendInfo extends PlutoEntry {
+  /** `git`: Markdown files in a Git repo. `database`: rows in a database. */
+  kind: 'git' | 'database'
+  /** A translation key or literal: the name in the badge ("GitHub", "Supabase"). */
+  label: string
+  icon?: string
+  /** A number on the badge, for example the commits that are not pushed. 0 shows none. */
+  count?: () => number | null | undefined
+  /** A translation key or literal: the text next to the count ("{count} to push"). */
+  countLabel?: string
+  /** The body of the popover. Use an async component. */
+  details?: Component
+  /** Called when the popover opens, for example to read the state again. */
+  onOpen?: () => void
+}
+
 export interface PlutoExtension {
   /** Layer name. Use the package's $meta.name, e.g. 'supabase-blog'. */
   id: string
@@ -373,6 +393,7 @@ export interface PlutoExtension {
   accountMenu?: PlutoAccountMenuItem[]
   adminBanners?: PlutoAdminBanner[]
   site?: PlutoSiteInfo
+  backend?: PlutoBackendInfo
   contentTypes?: PlutoContentTypeEntry[]
   contentFieldWidgets?: PlutoContentFieldWidget[]
   contentActions?: PlutoContentAction[]
@@ -409,6 +430,7 @@ export interface PlutoRegistry {
   accountMenu: PlutoRegistryBucket<PlutoAccountMenuItem>
   adminBanners: PlutoRegistryBucket<PlutoAdminBanner>
   siteInfo: PlutoRegistryBucket<PlutoSiteInfo>
+  backend: PlutoRegistryBucket<PlutoBackendInfo>
   contentTypes: PlutoRegistryBucket<PlutoContentTypeEntry>
   contentFieldWidgets: PlutoRegistryBucket<PlutoContentFieldWidget>
   contentActions: PlutoRegistryBucket<PlutoContentAction>

package/shared/utils/html-base.ts

@@ -0,0 +1,23 @@
+/**
+ * Puts the base path of the app before each site path (`/media/...`, `/posts/...`) in the `src`
+ * and `href` attributes of sanitized HTML. A site under a sub path, such as a project site of
+ * GitHub Pages (`/<repo>/`), needs it: the body of a post holds plain site paths, and the browser
+ * reads them from the root of the host.
+ *
+ * It changes nothing when the base is `/`, for a URL with a scheme or a protocol-relative URL
+ * (`//host`), for a relative path, an anchor or a query, and for a path that already starts with
+ * the base. The HTML comes from the public API, so each attribute value is in double quotes.
+ */
+export function withBaseInHtml(html: string, baseURL: string): string {
+  if (!html || !baseURL || baseURL === '/') {
+    return html
+  }
+  const base = baseURL.endsWith('/') ? baseURL : `${baseURL}/`
+  return html.replace(
+    /(\s(?:src|href)=")(\/[^"]*)"/g,
+    (match, attribute: string, path: string) =>
+      path.startsWith('//') || path.startsWith(base)
+        ? match
+        : `${attribute}${base}${path.slice(1)}"`
+  )
+}