@uniweb/build 0.14.28 → 0.14.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.14.28",
+  "version": "0.14.29",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,8 +59,8 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.33.2",
     "yaml": "^2.5.0",
-    "@uniweb/theming": "0.1.8",
-    "@uniweb/content-writer": "0.2.6"
+    "@uniweb/content-writer": "0.2.6",
+    "@uniweb/theming": "0.1.8"
   },
   "optionalDependencies": {
     "@uniweb/runtime": "0.8.26",

package/src/hosts/ci-workflow.js

@@ -0,0 +1,136 @@
+/**
+ * Shared GitHub Actions scaffolding for host adapters' `initCi` hooks.
+ *
+ * Every scaffolded workflow does the same four things before it diverges:
+ * check out, set up the package manager, install, run `uniweb build
+ * --host=<name>`. Only the publish step is host-specific. These helpers
+ * own the shared prefix so each adapter's file stays readable and a fix
+ * to (say) the pnpm setup lands everywhere at once.
+ *
+ * Everything here returns YAML *fragments* at a known indentation (6
+ * spaces — the depth of a step under `jobs.<id>.steps`). Adapters compose
+ * them into a full document with a template literal.
+ */
+
+/**
+ * Checkout + package-manager setup + install, as workflow steps.
+ *
+ * @param {object} opts
+ * @param {'pnpm'|'npm'} [opts.packageManager]
+ * @param {string} [opts.nodeVersion]
+ * @param {string} [opts.pnpmVersion]
+ * @param {boolean} [opts.checkout] — Include the checkout step (default true).
+ * @returns {string} YAML fragment, no trailing newline.
+ */
+export function setupSteps({
+  packageManager = 'pnpm',
+  nodeVersion = '20',
+  pnpmVersion = '11',
+  checkout = true,
+} = {}) {
+  const lines = []
+  if (checkout) lines.push('      - uses: actions/checkout@v4')
+
+  if (packageManager === 'pnpm') {
+    lines.push('      - uses: pnpm/action-setup@v4')
+    lines.push('        with:')
+    lines.push(`          version: ${pnpmVersion}`)
+    lines.push('      - uses: actions/setup-node@v4')
+    lines.push('        with:')
+    lines.push(`          node-version: '${nodeVersion}'`)
+    lines.push('          cache: pnpm')
+    lines.push('      - run: pnpm install --frozen-lockfile')
+  } else {
+    lines.push('      - uses: actions/setup-node@v4')
+    lines.push('        with:')
+    lines.push(`          node-version: '${nodeVersion}'`)
+    lines.push('          cache: npm')
+    lines.push('      - run: npm ci')
+  }
+  return lines.join('\n')
+}
+
+/**
+ * The `uniweb build` invocation for a package manager + host.
+ *
+ * @param {object} opts
+ * @param {'pnpm'|'npm'} [opts.packageManager]
+ * @param {string} opts.host — Adapter name passed to --host.
+ * @returns {string}
+ */
+export function uniwebBuildCommand({ packageManager = 'pnpm', host }) {
+  const runner = packageManager === 'pnpm' ? 'pnpm exec' : 'npx'
+  return `${runner} uniweb build --host=${host}`
+}
+
+/**
+ * The push trigger. Both default-branch names are listed so the workflow
+ * fires whether the repo uses 'main' or 'master' — GHA only triggers on a
+ * branch that exists, so the unused name is a harmless no-op.
+ *
+ * @returns {string} YAML fragment for the `on:` block's push trigger.
+ */
+export function pushTrigger() {
+  return `on:
+  push:
+    # Both names are listed so the workflow fires whether the repo uses
+    # 'main' (GitHub's current default) or 'master'. GHA only triggers on
+    # a branch that exists, so the unused name is a harmless no-op. Users
+    # on a different default (trunk, develop) edit this list directly.
+    branches: [main, master]
+  workflow_dispatch:`
+}
+
+/**
+ * A step that comments the deploy URL on the pull request, replacing its
+ * own previous comment rather than stacking one per push.
+ *
+ * Uses `peter-evans/create-or-update-comment` via a find step, which
+ * needs no extra token beyond the default GITHUB_TOKEN with
+ * `pull-requests: write`.
+ *
+ * @param {object} opts
+ * @param {string} opts.urlExpression — GHA expression yielding the URL.
+ * @param {string} opts.hostLabel — Human host name for the comment body.
+ * @returns {string} YAML fragment.
+ */
+export function prCommentStep({ urlExpression, hostLabel }) {
+  return `      - name: Find previous preview comment
+        uses: peter-evans/find-comment@v3
+        id: fc
+        with:
+          issue-number: \${{ github.event.pull_request.number }}
+          comment-author: 'github-actions[bot]'
+          body-includes: '<!-- uniweb-preview -->'
+      - name: Comment the preview URL
+        uses: peter-evans/create-or-update-comment@v4
+        with:
+          comment-id: \${{ steps.fc.outputs.comment-id }}
+          issue-number: \${{ github.event.pull_request.number }}
+          edit-mode: replace
+          body: |
+            <!-- uniweb-preview -->
+            **Preview ready** — ${hostLabel}
+
+            ${urlExpression}
+
+            Built from \`\${{ github.event.pull_request.head.sha }}\`.`
+}
+
+/**
+ * Header comment block for a generated workflow.
+ *
+ * @param {object} opts
+ * @param {string} opts.title
+ * @param {string} opts.command — The `uniweb add ci …` line that made it.
+ * @param {string[]} [opts.notes] — Extra lines, each prefixed with '# '.
+ * @returns {string}
+ */
+export function workflowHeader({ title, command, notes = [] }) {
+  const lines = [`# ${title}`, `# Generated by \`${command}\`. Safe to edit.`]
+  if (notes.length) {
+    lines.push('#')
+    for (const n of notes) lines.push(n ? `# ${n}` : '#')
+  }
+  return lines.join('\n')
+}

package/src/hosts/cloudflare-pages.js

@@ -1,10 +1,13 @@
 /**
  * Cloudflare Pages host adapter
  *
- * Emits a `_redirects` file describing redirect/rewrite directives the
- * host evaluates at request time. This is the format Cloudflare Pages
- * uses and is also accepted unchanged by Netlify (the format originated
- * there and the two hosts are compatible at this layer).
+ * postBuild: emits a `_redirects` file describing redirect/rewrite
+ * directives the host evaluates at request time. This is the format
+ * Cloudflare Pages uses and is also accepted unchanged by Netlify (the
+ * format originated there and the two hosts are compatible at this
+ * layer) — `netlify.js` reuses `emitRedirectsFile` for exactly that
+ * reason. The two are separate adapters because they *deploy*
+ * differently, which is the line the registry header draws.
  *
  * Format: `source destination status`
  *   302 = redirect (browser URL changes)
@@ -15,12 +18,36 @@
  *
  * This is the framework's historical default postBuild output and remains
  * the default when no `--host` flag is passed to `uniweb build`.
+ *
+ * deploy: drives `wrangler pages deploy`. Needs a project name (from the
+ * deploy.yml target) and a Cloudflare API token + account id from the
+ * environment.
+ *
+ * initCi: emits a GitHub Actions workflow that builds and deploys on
+ * every push, plus (opt-in) a pull-request preview workflow.
  */
 
 import { readFile, writeFile } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 
+import { DeployError, spawnTool, readCredential, credentialHint } from './deploy-utils.js'
+import {
+  setupSteps,
+  uniwebBuildCommand,
+  pushTrigger,
+  prCommentStep,
+  workflowHeader,
+} from './ci-workflow.js'
+
+const WRANGLER_INSTALL = [
+  'Install wrangler (Cloudflare\'s CLI):',
+  '  npm install -g wrangler',
+  '  # or run it without installing: npx wrangler …',
+  '',
+  'Then authenticate with `wrangler login`, or set CLOUDFLARE_API_TOKEN.',
+].join('\n')
+
 /**
  * Build the `_redirects` body from per-locale page metadata.
  *
@@ -68,11 +95,245 @@ export async function emitRedirectsFile(distDir, localeConfigs, onProgress = ()
   return { written: true, count: entries.length }
 }
 
+/**
+ * Pull the deployment URL out of wrangler's output. Wrangler prints a
+ * line like "✨ Deployment complete! Take a peek over at https://….pages.dev".
+ * Best-effort — a miss just means we don't echo the URL.
+ */
+export function extractPagesUrl(stdout) {
+  const match = stdout.match(/https:\/\/[a-z0-9-]+\.[a-z0-9-]+\.pages\.dev\S*/i)
+    || stdout.match(/https:\/\/[a-z0-9-]+\.pages\.dev\S*/i)
+  return match ? match[0].replace(/[.,)]+$/, '') : null
+}
+
+function translateWranglerError(code, stderr) {
+  const out = stderr.trim()
+
+  if (/Authentication error|\[code: 10000\]|not authenticated/i.test(out)) {
+    return new DeployError(
+      'Cloudflare rejected the credentials.',
+      {
+        hint: credentialHint({
+          what: 'a Cloudflare API token with the "Cloudflare Pages — Edit" permission',
+          envVars: ['CLOUDFLARE_API_TOKEN', 'CLOUDFLARE_ACCOUNT_ID'],
+          docsUrl: 'Create one at https://dash.cloudflare.com/profile/api-tokens',
+        }),
+      }
+    )
+  }
+
+  if (/Project not found|could not find project/i.test(out)) {
+    return new DeployError(
+      'That Cloudflare Pages project does not exist.',
+      {
+        hint: [
+          'Create it once (either is fine):',
+          '  wrangler pages project create <name>',
+          '  # or via the dashboard: Workers & Pages → Create → Pages',
+          '',
+          'Then set `projectName` on the target in deploy.yml.',
+        ].join('\n'),
+      }
+    )
+  }
+
+  return null
+}
+
+async function deploy({ distDir, deployConfig = {}, env = process.env, log = () => {} }) {
+  const projectName = deployConfig.projectName || deployConfig.project
+  if (!projectName) {
+    throw new DeployError(
+      'Cloudflare Pages needs a project name.',
+      {
+        hint: [
+          'Add it to the target in deploy.yml:',
+          '',
+          '  targets:',
+          '    production:',
+          '      host: cloudflare-pages',
+          '      projectName: my-site',
+          '',
+          'The project must already exist — `wrangler pages project create my-site`.',
+        ].join('\n'),
+      }
+    )
+  }
+
+  const token = readCredential(deployConfig, env, null, 'CLOUDFLARE_API_TOKEN')
+  const accountId = readCredential(deployConfig, env, 'accountId', 'CLOUDFLARE_ACCOUNT_ID')
+
+  // wrangler can also use an interactive `wrangler login` session, so a
+  // missing token is not fatal — only warn when neither is present.
+  const subprocessEnv = { ...env }
+  if (accountId) subprocessEnv.CLOUDFLARE_ACCOUNT_ID = accountId
+  if (!token && !env.CLOUDFLARE_API_TOKEN) {
+    log('  No CLOUDFLARE_API_TOKEN set — falling back to your `wrangler login` session.')
+  }
+
+  const args = ['pages', 'deploy', distDir, `--project-name=${projectName}`]
+  if (deployConfig.branch) args.push(`--branch=${deployConfig.branch}`)
+  if (deployConfig.commitDirty !== false) args.push('--commit-dirty=true')
+
+  log(`\n→ Deploying to Cloudflare Pages project '${projectName}'`)
+  const { stdout } = await spawnTool('wrangler', args, {
+    env: subprocessEnv,
+    log,
+    install: WRANGLER_INSTALL,
+    translate: translateWranglerError,
+  })
+
+  const url = extractPagesUrl(stdout)
+  log('\n✓ Deploy complete.')
+  if (url) log(`  ${url}`)
+  return { url }
+}
+
+/**
+ * Scaffold GitHub Actions workflows for Cloudflare Pages.
+ *
+ * Cloudflare Pages can also build from a dashboard-connected repo, but a
+ * committed workflow is the reproducible option: the build runs with the
+ * project's own toolchain versions and the same `uniweb build` invocation
+ * a developer runs locally.
+ */
+async function initCi({
+  site,
+  packageManager = 'pnpm',
+  nodeVersion = '20',
+  pnpmVersion = '11',
+  domain = null,
+  projectName = null,
+  previews = true,
+}) {
+  const sitePath = site.path
+  const project = projectName || site.name
+  const build = uniwebBuildCommand({ packageManager, host: 'cloudflare-pages' })
+  const setup = setupSteps({ packageManager, nodeVersion, pnpmVersion })
+
+  const files = [{
+    path: '.github/workflows/deploy-cloudflare-pages.yml',
+    content: `${workflowHeader({
+      title: 'Deploy to Cloudflare Pages',
+      command: 'uniweb add ci --host=cloudflare-pages',
+      notes: [
+        'Requires two repository secrets (Settings → Secrets and variables → Actions):',
+        '  CLOUDFLARE_API_TOKEN   — token with the "Cloudflare Pages — Edit" permission',
+        '  CLOUDFLARE_ACCOUNT_ID  — found in the Cloudflare dashboard sidebar',
+      ],
+    })}
+
+name: Deploy to Cloudflare Pages
+
+${pushTrigger()}
+
+concurrency:
+  group: cloudflare-pages-production
+  cancel-in-progress: true
+
+jobs:
+  build-deploy:
+    runs-on: ubuntu-latest
+    steps:
+${setup}
+      - run: ${build}
+        working-directory: ${sitePath}
+      - name: Publish to Cloudflare Pages
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: \${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: \${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: pages deploy ${sitePath}/dist --project-name=${project} --branch=main
+`,
+  }]
+
+  if (previews) {
+    files.push({
+      path: '.github/workflows/preview-cloudflare-pages.yml',
+      content: `${workflowHeader({
+        title: 'Preview deploy for pull requests — Cloudflare Pages',
+        command: 'uniweb add ci --host=cloudflare-pages',
+        notes: [
+          'Each PR gets its own preview URL, posted as a comment on the PR.',
+          '',
+          'No teardown job: Cloudflare owns preview-deployment lifecycle and',
+          'retires them on its own schedule. A delete step here would need to',
+          'track deployment ids across runs for no real benefit.',
+        ],
+      })}
+
+name: Preview (Cloudflare Pages)
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: cloudflare-pages-preview-\${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    steps:
+${setup}
+      - run: ${build}
+        working-directory: ${sitePath}
+      - name: Publish preview
+        id: publish
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: \${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: \${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          command: pages deploy ${sitePath}/dist --project-name=${project} --branch=pr-\${{ github.event.pull_request.number }}
+${prCommentStep({
+  urlExpression: '${{ steps.publish.outputs.deployment-url }}',
+  hostLabel: 'Cloudflare Pages',
+})}
+`,
+    })
+  }
+
+  const targetConfig = { host: 'cloudflare-pages', projectName: project }
+  if (domain) targetConfig.domain = domain
+
+  const postInstructions = [
+    `Create the Pages project once: \`wrangler pages project create ${project}\``,
+    'Add two repository secrets under Settings → Secrets and variables → Actions:',
+    '  CLOUDFLARE_API_TOKEN   (Cloudflare Pages — Edit)',
+    '  CLOUDFLARE_ACCOUNT_ID',
+    'Commit and push the workflow — the deploy runs on every push to the default branch.',
+  ]
+  if (previews) {
+    postInstructions.push('Pull requests get their own preview URL, commented on the PR.')
+  }
+  if (domain) {
+    postInstructions.push(`Attach ${domain} in the Pages project's Custom domains tab.`)
+  }
+
+  return { files, postInstructions, targetConfig }
+}
+
 const adapter = {
   name: 'cloudflare-pages',
+  display: {
+    order: 20,
+    pushWith: 'wrangler',
+    title: 'Cloudflare Pages',
+    qualifier: 'free, CI on push',
+    summary: 'Unlimited-bandwidth static hosting on Cloudflare\'s CDN. Set up a workflow, or upload from here with wrangler.',
+    ci: true,
+    previews: true,
+  },
   async postBuild({ distDir, localeConfigs, onProgress }) {
     await emitRedirectsFile(distDir, localeConfigs, onProgress)
   },
+  deploy,
+  initCi,
 }
 
 export default adapter

package/src/hosts/deploy-utils.js

@@ -0,0 +1,151 @@
+/**
+ * Shared deploy-hook plumbing
+ *
+ * Every host adapter that ships a `deploy` hook drives a third-party CLI
+ * (`aws`, `wrangler`, `netlify`, `vercel`, `git`). They all need the same
+ * three things:
+ *
+ *   1. A structured error the CLI layer can render. `deploy.js` keys off
+ *      `err.name === 'DeployError'` to print `message` + an indented
+ *      `hint` block instead of a stack trace, so the class name is part
+ *      of the contract — don't rename it.
+ *   2. ENOENT translated into "here's how to install that tool", which is
+ *      the single most common failure for a first-time deploy.
+ *   3. A non-zero exit translated into something actionable. That part is
+ *      tool-specific, so `spawnTool` takes an optional `translate`
+ *      callback and falls back to a generic message carrying stderr.
+ *
+ * Adapters own their translations; this module owns the mechanics.
+ */
+
+import { spawn } from 'node:child_process'
+
+/**
+ * Error shape the CLI renders specially. `hint` is a pre-formatted
+ * multi-line block printed verbatim under the message.
+ */
+export class DeployError extends Error {
+  constructor(message, { hint } = {}) {
+    super(message)
+    this.name = 'DeployError'
+    this.hint = hint
+  }
+}
+
+/**
+ * Run a CLI tool, streaming stdout to `log` and capturing stderr for
+ * error translation.
+ *
+ * @param {string} cmd — Executable name, resolved on PATH.
+ * @param {string[]} args
+ * @param {object} opts
+ * @param {Record<string,string>} [opts.env]
+ * @param {(msg: string) => void} [opts.log]
+ * @param {string} [opts.cwd]
+ * @param {string} [opts.install] — Install instructions used to build the
+ *   ENOENT hint. Strongly recommended: a missing tool is the most common
+ *   first-run failure and a bare "command not found" is a dead end.
+ * @param {(code: number, stderr: string) => DeployError|null} [opts.translate]
+ *   Maps a non-zero exit to a specific DeployError. Return null to fall
+ *   through to the generic message.
+ * @param {boolean} [opts.quiet] — Capture stdout without echoing it.
+ * @returns {Promise<{stdout: string, stderr: string}>}
+ * @throws {DeployError}
+ */
+export function spawnTool(cmd, args, opts = {}) {
+  const { env, log = () => {}, cwd, install, translate, quiet = false } = opts
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(cmd, args, {
+      env,
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+
+    let stdout = ''
+    let stderr = ''
+
+    child.stdout.on('data', (chunk) => {
+      const s = chunk.toString()
+      stdout += s
+      if (!quiet) log(s.replace(/\n$/, ''))
+    })
+    child.stderr.on('data', (chunk) => { stderr += chunk.toString() })
+
+    child.on('error', (err) => {
+      if (err.code === 'ENOENT') {
+        reject(new DeployError(
+          `\`${cmd}\` is not installed or not on PATH.`,
+          { hint: install || `Install ${cmd} and make sure it's on your PATH, then retry.` }
+        ))
+        return
+      }
+      reject(err)
+    })
+
+    child.on('close', (code) => {
+      if (code === 0) {
+        resolve({ stdout, stderr })
+        return
+      }
+      const specific = translate ? translate(code, stderr) : null
+      if (specific) {
+        reject(specific)
+        return
+      }
+      const tail = stderr.trim() || stdout.trim()
+      reject(new DeployError(
+        `\`${cmd} ${args[0] ?? ''}\` failed (exit ${code}).`,
+        { hint: tail ? tail.split('\n').slice(-20).join('\n') : undefined }
+      ))
+    })
+  })
+}
+
+/**
+ * Read a credential from the resolved deploy target first, then the
+ * environment. Adapters accept tokens either way: `deploy.yml` is
+ * committed, so a token belongs in the environment — but the config path
+ * exists for values that are merely identifiers (account/site/project
+ * ids), which are safe to commit and tedious to re-export per shell.
+ *
+ * @param {object} deployConfig
+ * @param {Record<string,string>} env
+ * @param {string} configKey
+ * @param {string|string[]} envKeys — Checked in order.
+ * @returns {string|undefined}
+ */
+export function readCredential(deployConfig, env, configKey, envKeys) {
+  const fromConfig = deployConfig?.[configKey]
+  if (fromConfig) return String(fromConfig)
+  for (const key of [envKeys].flat()) {
+    if (env?.[key]) return env[key]
+  }
+  return undefined
+}
+
+/**
+ * Build the "set this and retry" hint for a missing credential. Kept in
+ * one place so every adapter phrases it the same way.
+ *
+ * @param {object} spec
+ * @param {string} spec.what — Human name, e.g. 'a Cloudflare API token'.
+ * @param {string[]} spec.envVars
+ * @param {string} [spec.configKey] — deploy.yml key, when committing the
+ *   value is safe (ids, not secrets).
+ * @param {string} [spec.docsUrl]
+ * @returns {string}
+ */
+export function credentialHint({ what, envVars, configKey, docsUrl }) {
+  const lines = [`Provide ${what}:`]
+  for (const v of envVars) lines.push(`  export ${v}=…`)
+  if (configKey) {
+    lines.push('')
+    lines.push(`Or set \`${configKey}\` on the target in deploy.yml (safe to commit — it's an id, not a secret).`)
+  }
+  if (docsUrl) {
+    lines.push('')
+    lines.push(docsUrl)
+  }
+  return lines.join('\n')
+}

package/src/hosts/generic-static.js

@@ -14,6 +14,18 @@
 
 const adapter = {
   name: 'generic-static',
+  display: {
+    order: 90,
+    title: 'Generic static host',
+    qualifier: 'no helper files',
+    summary: 'A plain dist/ with no host-specific output. Pick this for a self-managed nginx, Caddy, or any host that needs nothing extra.',
+    ci: false,
+    previews: false,
+    // Not a destination in its own right — it names an *artifact shape*,
+    // which is the `export --host` question, not "where should this go?".
+    // The deploy wizard offers "Somewhere else" instead, which exports.
+    wizard: false,
+  },
   async postBuild() {
     // Intentionally empty.
   },