@rm-industries/create-forge 0.4.0-beta.0 → 0.4.0-beta.2

package/dist/template/.github/workflows/project.yml

@@ -0,0 +1,262 @@
+---
+name: Project Continuous Integration
+
+on: # yamllint disable-line rule:truthy
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  format:
+    name: Format
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Setup project
+        uses: ./.github/actions/setup-project
+        with:
+          node-version: '26.x'
+
+      - name: Check formatting
+        run: npm run format
+
+  spellcheck:
+    name: Spellcheck
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Setup project
+        uses: ./.github/actions/setup-project
+        with:
+          node-version: '26.x'
+
+      - name: Check spelling
+        run: npm run spellcheck
+
+  static-quality:
+    name: Static quality
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Setup project
+        uses: ./.github/actions/setup-project
+        with:
+          node-version: '26.x'
+
+      - name: Run remaining static quality checks
+        run: npm run quality:static:ci
+
+  unit-tests:
+    name: Unit tests and coverage
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Setup project
+        uses: ./.github/actions/setup-project
+        with:
+          node-version: '26.x'
+
+      - name: Run unit tests with coverage
+        run: npm run test:coverage
+
+      - name: Upload coverage report
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: unit-coverage
+          path: coverage
+          if-no-files-found: error
+          retention-days: 7
+
+  build:
+    name: Production build
+    needs:
+      - format
+      - spellcheck
+      - static-quality
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Setup project
+        uses: ./.github/actions/setup-project
+        with:
+          node-version: '26.x'
+
+      - name: Build project
+        run: npm run build
+
+      - name: Validate generated output
+        run: npm run validate:build
+
+      - name: Upload production build
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: site-build
+          path: dist
+          if-no-files-found: error
+          retention-days: 7
+
+      - name: Upload GitHub Pages artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5
+        with:
+          path: dist
+
+  browser-tests:
+    name: Browser and accessibility tests
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Setup project
+        uses: ./.github/actions/setup-project
+        with:
+          node-version: '26.x'
+
+      - name: Install Chromium
+        run: npx playwright install --with-deps chromium
+
+      - name: Run browser and accessibility tests
+        run: npm run test:e2e
+
+      - name: Upload browser failure evidence
+        if: failure()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: browser-test-failures
+          path: |
+            playwright-report
+            test-results
+          if-no-files-found: error
+          retention-days: 7
+
+  lighthouse:
+    name: Lighthouse budgets
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Setup project
+        uses: ./.github/actions/setup-project
+        with:
+          node-version: '26.x'
+
+      - name: Enforce Lighthouse budgets
+        run: npm run lighthouse:ci
+
+      - name: Upload Lighthouse reports
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: lighthouse-reports
+          path: .lighthouseci
+          include-hidden-files: true
+          if-no-files-found: error
+          retention-days: 7
+
+  project:
+    name: Project
+    needs:
+      - format
+      - spellcheck
+      - static-quality
+      - unit-tests
+      - build
+      - browser-tests
+      - lighthouse
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Confirm project checks
+        run: echo "All project checks passed."
+
+  deploy:
+    name: Deploy GitHub Pages
+    needs:
+      - build
+      - project
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+
+    permissions:
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5

package/dist/template/.github/workflows/security.yml

@@ -0,0 +1,70 @@
+---
+name: Security Analysis
+
+on: # yamllint disable-line rule:truthy
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+  schedule:
+    - cron: '__RM_INDUSTRIES_FORGE_TEMPLATE_V1_SECURITY_SCHEDULE_MINUTE__ 5 * * 1'
+
+permissions: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  code-analysis:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language:
+          - actions
+          - javascript-typescript
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
+        with:
+          build-mode: none
+          languages: ${{ matrix.language }}
+          queries: security-extended,security-and-quality
+
+      - name: Perform CodeQL analysis
+        uses: github/codeql-action/analyze@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
+
+  dependency-review:
+    name: Review dependencies
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+
+      - name: Review dependency changes
+        uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5
+        with:
+          fail-on-severity: high

package/dist/template/README.md

@@ -55,6 +55,56 @@ the individual scripts when working offline. CI may execute independent stages
 in parallel, but a project generated by the packed Forge initializer must pass
 the documented `npm run quality` command as a single ordered pipeline.
 
+## Continuous integration
+
+The generated `.github/workflows/project.yml` runs on pull requests targeting
+`main` and on pushes to `main`. It separates static quality, coverage-enforced
+unit tests, the validated production build, browser and accessibility tests,
+and Lighthouse budgets so failures identify the affected gate directly. The
+required `Project` result succeeds only after every release-blocking job passes.
+On pushes to `main`, that result unlocks a separate GitHub Pages deployment;
+pull requests never upload or deploy a Pages artifact. Deployment setup,
+project-site URLs, custom domains, and environment protections are documented in
+[`docs/github-pages.md`](docs/github-pages.md).
+
+The workflow installs dependencies with `npm ci`, caches npm downloads using
+the lockfile, cancels superseded runs on the same Git reference, and grants only
+read access to repository contents. Pull requests receive no secrets or write
+permissions. Coverage, production builds, Lighthouse reports, and browser
+failure evidence are retained for seven days. All third-party actions use
+immutable commit pins.
+
+Security automation is included alongside project CI. CodeQL analyzes the
+project's TypeScript and GitHub Actions on pull requests, pushes to `main`, and
+a weekly schedule. Dependency review rejects pull requests that introduce
+known high- or critical-severity vulnerabilities. A separate scheduled
+automation workflow validates workflow syntax and scans GitHub Actions with
+Zizmor. Zizmor uploads its findings to GitHub code scanning for review in the
+Security tab without failing the workflow solely because it found an issue.
+The job receives `security-events: write` only for that upload; all other access
+remains read-only. Repositories can make selected code-scanning severities
+merge-blocking later through their ruleset without changing the workflow.
+The `Automation` aggregate runs when `.github/**` changes and succeeds only after
+both workflow syntax and security validation pass. Because it is path-filtered,
+do not configure it as a globally required status check; review it whenever an
+automation change causes it to appear.
+
+Dependabot checks npm and GitHub Actions weekly. Minor and patch npm updates are
+grouped by production or development scope, while major updates remain separate
+for deliberate review. Updates use cooldown periods to avoid adopting newly
+released versions immediately. Because pre-1.0 Sveltia minor releases may be
+breaking, `@sveltia/cms` updates are kept separate from generic production
+dependency groups. Its pull requests must satisfy the compatibility line
+declared by `@rm-industries/content-model`; moving to a later minor requires a
+tested content-model release first. No version is ignored, security updates
+remain enabled, and every update must pass the complete project and security
+workflows before merging.
+
+GitHub chooses the Dependabot run times, distributing update checks across its
+available schedule. Forge derives distinct weekly CodeQL and workflow-validation
+minutes from the generated package name. This keeps generation reproducible
+while preventing every Forge project from starting scheduled work simultaneously.
+
 Playwright builds the site and runs Chromium against Astro's production preview,
 not the development server. Its browser coverage exercises desktop and mobile
 navigation, article listing/detail flows, article pagination, light and dark
@@ -99,6 +149,12 @@ configuration, shared layout, and reusable SEO head consume this single
 validated source. New pages should use `src/layouts/BaseLayout.astro` to inherit
 the document shell and canonical metadata.
 
+The canonical URL may include a pathname for a GitHub Pages project site, such
+as `https://owner.github.io/repository`. The Astro configuration derives its
+deployment base from that pathname, and shared URL helpers apply it to local
+navigation, metadata, supporting files, and assets. Root-hosted and custom-domain
+sites use an origin-only URL and therefore have no deployment prefix.
+
 The standalone source template uses `https://example.com` as a valid,
 non-production site origin. Projects created by Forge receive the values
 selected through the generator input contract.

package/dist/template/astro.config.ts

@@ -2,12 +2,16 @@ import sitemap from '@astrojs/sitemap';
 import tailwindcss from '@tailwindcss/vite';
 import { defineConfig } from 'astro/config';
 
+import { getDeploymentConfig } from './src/config/deployment';
 import { site } from './src/config/site';
 
+const deployment = getDeploymentConfig(site.url);
+
 export default defineConfig({
+  base: deployment.base,
   integrations: [sitemap()],
   output: 'static',
-  site: site.url,
+  site: deployment.site,
   trailingSlash: 'always',
   vite: {
     plugins: [tailwindcss()],

package/dist/template/cspell.config.ts

@@ -18,5 +18,6 @@ export default defineConfig({
     'Sveltia',
     'unreviewed',
     'WCAG',
+    'Zizmor',
   ],
 });

package/dist/template/docs/github-pages.md

@@ -0,0 +1,56 @@
+# GitHub Pages deployment
+
+The project workflow publishes the validated production build to GitHub Pages
+after every push to `main`. Pull requests build and test the site, but they do
+not upload a Pages artifact or run a deployment.
+
+## Enable deployment
+
+1. Open the repository's **Settings → Pages** page.
+2. Under **Build and deployment**, select **GitHub Actions** as the source.
+3. Open **Settings → Environments → github-pages** after its first appearance.
+4. Restrict deployment branches to `main`. Add required reviewers when the site
+   needs a manual production approval.
+
+The build job has read-only repository access. The separate deployment job is
+the only job granted `pages: write` and `id-token: write`, and it cannot begin
+until the complete `Project` quality gate succeeds.
+
+## Choose the public URL
+
+Set `url` in `src/config/site.ts` to the complete public address. Forge derives
+Astro's deployment base from this value, so canonical metadata, navigation,
+assets, the RSS feed, the web manifest, and CMS branding use the same path.
+
+For a project site, include the repository name:
+
+```ts
+url: 'https://owner.github.io/repository',
+```
+
+For an organization or user site, use the root address:
+
+```ts
+url: 'https://owner.github.io',
+```
+
+Run `npm run build && npm run validate:build` after changing the URL. Once the
+workflow succeeds on `main`, its deployment summary links to the published site.
+
+## Use a custom domain
+
+Set the site URL to the custom origin without a repository pathname:
+
+```ts
+url: 'https://www.example.com',
+```
+
+Add `public/CNAME` containing only the domain name, configure the same domain in
+**Settings → Pages**, and create the DNS records GitHub documents for the chosen
+domain. The template does not include a `CNAME` file because generated projects
+do not share a domain. Enable **Enforce HTTPS** after GitHub verifies the DNS
+configuration.
+
+Do not configure both a repository pathname and a custom domain. A custom domain
+is served from its root, while a project site uses the repository name as its
+base path.