diff --git a/.github/workflows/analytics.yml b/.github/workflows/analytics.yml index f6f6cf3d7..12bae4a7b 100644 --- a/.github/workflows/analytics.yml +++ b/.github/workflows/analytics.yml @@ -2,7 +2,7 @@ name: 📊 Analytics & Monitoring on: push: - branches: [ master, main ] + branches: [ main ] schedule: # Run daily at 6 AM UTC - cron: '0 6 * * *' diff --git a/.github/workflows/deploy-ipfs.yml b/.github/workflows/deploy-ipfs.yml index 969e93e4f..eaab9b49c 100644 --- a/.github/workflows/deploy-ipfs.yml +++ b/.github/workflows/deploy-ipfs.yml @@ -1,113 +1,49 @@ -name: Deploy to IPFS - -on: - push: - branches: [main] - pull_request: - branches: [main] - -permissions: - contents: read - issues: write - deployments: write - -jobs: - build-and-deploy: - runs-on: ubuntu-latest - - steps: - - name: Checkout repository - uses: actions/checkout@v7 - - - name: Setup Ruby - uses: ruby/setup-ruby@v1 - with: - ruby-version: '3.2' - bundler-cache: true - - - name: Install dependencies - run: | - gem install bundler - bundle install - - - name: Build site - run: bundle exec jekyll build - env: - JEKYLL_ENV: production - - # IPFS pinning is best-effort: it must not break the core CI pipeline. - # When PINATA_JWT is absent the steps are skipped; when present but the - # pin fails (expired/invalid token, API error) we log a warning and - # continue so the workflow stays green. The real error is always visible - # in the step log. - - name: Pin to IPFS (best-effort) - id: pinata - if: ${{ secrets.PINATA_JWT != '' }} - continue-on-error: true - env: - PINATA_JWT: ${{ secrets.PINATA_JWT }} - run: | - echo "Attempting to pin ./_site to IPFS via Pinata REST API..." - tar -czf /tmp/site.tar.gz -C _site . - RESP=$(curl -s -X POST "https://api.pinata.cloud/pinning/pinFileToIPFS" \ - -H "Authorization: Bearer ${PINATA_JWT}" \ - -F "file=@/tmp/site.tar.gz") - CID=$(printf '%s' "$RESP" | grep -oP '(?<=IpfsHash"\s*:\s*")[^"]+') - if [ -z "$CID" ]; then - echo "::warning::IPFS pin failed (check PINATA_JWT / API). Response: $RESP" - echo "cid=" >> "$GITHUB_OUTPUT" - else - echo "cid=$CID" >> "$GITHUB_OUTPUT" - echo "$CID" > ipfs-cid.json - echo "✅ Pinned to IPFS: $CID" - fi - - - name: Upload CID artifact - if: ${{ steps.pinata.outputs.cid != '' }} - uses: actions/upload-artifact@v7 - with: - name: ipfs-cid - path: ipfs-cid.json - - - name: Update DNSLink (if configured) - if: ${{ steps.pinata.outputs.cid != '' && secrets.CLOUDFLARE_API_TOKEN != '' }} - env: - CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }} - run: | - curl -X PUT "https://api.cloudflare.com/client/v4/zones/${{ secrets.CLOUDFLARE_ZONE_ID }}/dns_records/${{ secrets.CLOUDFLARE_DNS_RECORD_ID }}" \ - -H "Authorization: Bearer ${CLOUDFLARE_API_TOKEN}" \ - -H "Content-Type: application/json" \ - --data "{\"data\":{\"link\":\"/ipfs/${{ steps.pinata.outputs.cid }}\"}}" - - - name: Comment PR with IPFS link - if: ${{ github.event_name == 'pull_request' && steps.pinata.outputs.cid != '' }} - uses: actions/github-script@v7 - with: - script: | - const cid = '${{ steps.pinata.outputs.cid }}'; - const ipfsUrl = `https://gateway.ipfs.io/ipfs/${cid}`; - const previewUrl = `https://${{ secrets.PINATA_GATEWAY || 'gateway.pinata.cloud'}}/ipfs/${cid}`; - await github.rest.issues.createComment({ - issue_number: context.issue.number, - owner: context.repo.owner, - repo: context.repo.repo, - body: `## 🚀 IPFS Deployment Preview\n\n- **CID**: \`${cid}\`\n- **Public Gateway**: [View on IPFS](${ipfsUrl})\n- **Pinata Gateway**: [View on Pinata](${previewUrl})\n\n✅ Successfully pinned to IPFS!` - }); - - - name: Create deployment status - if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' && steps.pinata.outputs.cid != '' }} - uses: actions/github-script@v7 - with: - script: | - const cid = '${{ steps.pinata.outputs.cid }}'; - const ipfsUrl = `https://gateway.ipfs.io/ipfs/${cid}`; - await github.rest.repos.createDeploymentStatus({ - owner: context.repo.owner, - repo: context.repo.repo, - deployment_id: context.payload.deployment?.id || 1, - state: 'success', - environment_url: ipfsUrl, - description: `Deployed to IPFS: ${cid}`, - log_url: `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}`, - environment: 'ipfs-production' - }); +# Deploy to IPFS — DISABLED (consolidation phase, 2026-08-15) +# +# Reasons for disabling (see docs/SSG_MIGRATION_PLAN.md + AGENTS.md Decision): +# 1. This workflow runs `bundle exec jekyll build` — the legacy Jekyll stack +# was removed in Phase 7. It would fail (no _config.yml / Gemfile). +# 2. It pinned to Pinata, whose API key/secret/JWT were COMPROMISED on +# 2026-08-14 and must not be used. +# 3. Per the consolidation decision (option b) secret-requiring deploy +# workflows are frozen until an explicit, conscious decision. +# +# If IPFS pinning is wanted later, rebuild this against `hugo --gc --minify` +# (output ./public) and a fresh, non-compromised pinning provider. The last +# working Jekyll state is preserved at git tag `pre-phase7-legacy`. +# +# name: Deploy to IPFS +# +# on: +# push: +# branches: [main] +# pull_request: +# branches: [main] +# +# permissions: +# contents: read +# issues: write +# deployments: write +# +# jobs: +# build-and-deploy: +# runs-on: ubuntu-latest +# steps: +# - uses: actions/checkout@v7 +# - uses: ruby/setup-ruby@v1 +# with: +# ruby-version: '3.2' +# bundler-cache: true +# - run: bundle install +# - run: bundle exec jekyll build +# env: +# JEKYLL_ENV: production +# - name: Pin to IPFS (best-effort) +# if: ${{ secrets.PINATA_JWT != '' }} +# continue-on-error: true +# env: +# PINATA_JWT: ${{ secrets.PINATA_JWT }} +# run: | +# tar -czf /tmp/site.tar.gz -C _site . +# curl -s -X POST "https://api.pinata.cloud/pinning/pinFileToIPFS" \ +# -H "Authorization: Bearer ${PINATA_JWT}" -F "file=@/tmp/site.tar.gz" diff --git a/.github/workflows/hugo.yml b/.github/workflows/hugo.yml index 8c34bc021..73faa9799 100644 --- a/.github/workflows/hugo.yml +++ b/.github/workflows/hugo.yml @@ -48,11 +48,11 @@ jobs: run: npm ci --prefer-offline --no-audit --no-fund - name: Validate content contract - # Soft gate: content-contract validates legacy _posts/ against the - # schema; pre-existing posts (e.g. 2015) lack tags/author/permalink and - # fail hard validation. That is legacy state, not a migration error, so - # we surface the report but do NOT block the Hugo build/deploy. - run: node scripts/ci-content-contract.cjs || true + # Publishing contract (Vector A): new posts in content/blog/ MUST + # satisfy schema/post-metadata.schema.json (hard gate — a failing new + # post blocks the build/deploy). Modified legacy posts are report-only. + # Knowledge graph (JSON-LD) is emitted for the whole corpus. + run: node scripts/ci-content-contract.cjs - name: Build with Hugo run: hugo --gc --minify --baseURL "${{ steps.pages.outputs.base_url }}/" diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml index e79d2ab40..c9648b1d9 100644 --- a/.github/workflows/security.yml +++ b/.github/workflows/security.yml @@ -2,9 +2,9 @@ name: 🔒 Security Scan on: push: - branches: [ master, main ] + branches: [ main ] pull_request: - branches: [ master, main ] + branches: [ main ] schedule: # Run weekly on Mondays at 4 AM UTC - cron: '0 4 * * 1' @@ -14,65 +14,54 @@ jobs: security-scan: name: 🔒 Security Vulnerability Scan runs-on: ubuntu-latest - + steps: - - name: 📥 Checkout Repository - uses: actions/checkout@v7 - - - name: 💎 Setup Ruby - uses: ruby/setup-ruby@v1 - with: - ruby-version: '3.1' - bundler-cache: true - - - name: 🟢 Setup Node.js - uses: actions/setup-node@v7 - with: - node-version: '24' - cache: 'npm' - - - name: 🔍 Node.js Security Audit - run: | - npm audit --audit-level=moderate || true - npm audit --json > npm-audit.json || true - - - name: 🔍 Ruby Security Audit - run: | - bundle audit --format=json > ruby-audit.json || true - - - name: 🔍 Trivy Vulnerability Scanner - uses: aquasecurity/trivy-action@master - with: - scan-type: 'fs' - scan-ref: '.' - format: 'sarif' - output: 'trivy-results.sarif' - - - name: 🚨 Semgrep Security Analysis - uses: semgrep/semgrep-action@v1 - continue-on-error: true - with: - config: >- - p/security-audit - p/secrets - p/cwe-top-25 - generate-sarif: '1' - - - name: 📤 Upload Security Reports - uses: actions/upload-artifact@v7 - with: - name: security-reports - path: | - npm-audit.json - ruby-audit.json - trivy-results.sarif - semgrep.sarif - - - name: 📊 Security Score - run: | - echo "🔒 Security Analysis Summary:" - echo "- Node.js dependencies: ✅ Scanned" - echo "- Ruby dependencies: ✅ Scanned" - echo "- File system vulnerabilities: ✅ Scanned" - echo "- Code security patterns: ✅ Scanned" - echo "- Secrets detection: ✅ Scanned" \ No newline at end of file + - name: 📥 Checkout Repository + uses: actions/checkout@v7 + + - name: 🟢 Setup Node.js + uses: actions/setup-node@v7 + with: + node-version: '24' + cache: 'npm' + + - name: 🔍 Node.js Security Audit + run: | + npm audit --audit-level=moderate || true + npm audit --json > npm-audit.json || true + + - name: 🔍 Trivy Vulnerability Scanner + # Pinned to a release tag (not @master) per supply-chain policy. + uses: aquasecurity/trivy-action@v0 + with: + scan-type: 'fs' + scan-ref: '.' + format: 'sarif' + output: 'trivy-results.sarif' + + - name: 🚨 Semgrep Security Analysis + uses: semgrep/semgrep-action@v1 + continue-on-error: true + with: + config: >- + p/security-audit + p/secrets + p/cwe-top-25 + generate-sarif: '1' + + - name: 📤 Upload Security Reports + uses: actions/upload-artifact@v7 + with: + name: security-reports + path: | + npm-audit.json + trivy-results.sarif + semgrep.sarif + + - name: 📊 Security Score + run: | + echo "🔒 Security Analysis Summary:" + echo "- Node.js dependencies: ✅ Scanned" + echo "- File system vulnerabilities: ✅ Scanned (Trivy)" + echo "- Code security patterns: ✅ Scanned (Semgrep)" + echo "- Secrets detection: ✅ Scanned" diff --git a/.github/workflows/sync_gists.yml b/.github/workflows/sync_gists.yml index 297be0542..1fc0e15e8 100644 --- a/.github/workflows/sync_gists.yml +++ b/.github/workflows/sync_gists.yml @@ -43,8 +43,8 @@ jobs: commit_message: "chore: update gists" commit_options: '--no-verify' # Укажите ветку, в которую нужно вносить изменения. - # Обычно это 'main' или 'master'. - branch: master + # Единственная рабочая ветка репозитория — 'main' (master удалён). + branch: main # Директория, в которой нужно отслеживать изменения. # Должна совпадать с 'output_dir' из предыдущего шага. file_pattern: 'gists/*' diff --git a/AGENTS.md b/AGENTS.md index 1ca39d9a5..9db72df4c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,62 +1,113 @@ -# Engineering Blog - AI Assistant Instructions +# Engineering Blog — AI Assistant Instructions -> **Priority order (per `docs/DEEP_REFACTORING_PLAN.md` §0):** repo instructions -> (`AGENTS.md`, `docs/*.md`) WIN over the attached external plan. Read -> `docs/DEEP_REFACTORING_PLAN.md` and `docs/ARCHITECTURE.md` before any step. +> **Priority order (per `docs/STRATEGIC_PLAN_2026-2027.md` + `docs/SSG_MIGRATION_PLAN.md`):** +> repo instructions (`AGENTS.md`, `docs/*.md`) WIN over any attached external plan. > Consolidate — do not duplicate. ## Overview -Jekyll-based engineering blog (GitHub Pages) with a modern ES-module frontend -bundled by **esbuild** into `js/refactored-bundle.js`, PWA, Lunr.js search, -and an AI-agent content pipeline. The single source of truth for post metadata -is the **Content Model** (`schema/post-metadata.schema.json`), enforced in CI. + +Static engineering blog published by **Hugo v0.164.0** with the **Blowfish v2.105.0** +theme, deployed to GitHub Pages via the `hugo.yml` workflow (Pages source = +**GitHub Actions**). The legacy Jekyll + esbuild stack was removed in Phase 7 +(see `docs/SSG_MIGRATION_PLAN.md` and tag `pre-phase7-legacy`). + +Two planes: + +- **Publishing plane** — Hugo content in `content/` (posts live in + `content/blog/`; the old `content/posts/` path redirects via an alias). + This is what ships to the public site. +- **Engineering / R&D plane** — `src/` (ES-module frontend experiments, + theme-manager, search-engine, etc.) and `contracts/dao/` (Solidity DAO). + This plane is **frozen R&D** (see Decision below): it is built/tested in CI + but NOT deployed to the live blog. ## Architecture (current, authoritative) + ``` -src/ # ES6 modules (bundled by esbuild) -├── config/constants.js -├── core/theme-manager.js -├── modules/ (i18n, image-optimizer, search-engine, social-sharing, subscription) -├── services/ (analytics-service, pwa-service) -├── utils/ (helpers, storage) -└── index.js # entry: bootstraps all modules, wired as type=module in _layouts/default.html - -js/refactored-bundle.js # production bundle (esbuild, minified ~15KB gzipped) -tests/ # 179 Jest (jsdom) + 17 smoke; see docs/TESTING.md +content/ # Hugo markdown (posts -> content/blog/, about, people, domini) +config/_default/ # hugo.toml (params, permalinks, outputs) + config.toml (theme) +layouts/partials/ # comments.html (giscus + Buttondown), subscription.html +i18n/ # ru.yaml, en.yaml (Hugo i18n) +assets/ # og-default.svg, lib/fuse/fuse.min.cjs (search) +static/ # robots.txt, data/knowledge-graph.json (generated) +themes/blowfish/ # git submodule (v2.105.0) +src/ # ES-module R&D frontend (NOT shipped by Hugo) +contracts/dao/ # Solidity DAO (GovernanceToken, ProposalEngine, SoulboundToken) +tests/ # unit/ (jest), hardhat/ (dao.test.cjs) schema/post-metadata.schema.json # formal Content Model (JSON Schema draft-07) scripts/ # validate-frontmatter, ai-review, build-knowledge-graph, ci-content-contract -docs/ (ARCHITECTURE, TESTING, CONTENT_CONTRACT, DEEP_REFACTORING_PLAN) +docs/ # STRATEGIC_PLAN_2026-2027.md, SSG_MIGRATION_PLAN.md, ... ``` -Legacy `js/*.js` files may still exist on disk but the shipped bundle is the -esbuild output. Do not edit `js/*.js` expecting it to ship. - -## CI contract (Vector A — Agent-driven Publishing Protocol) -Job `📜 Content Model Contract` in `.github/workflows/ci-cd.yml`: -- **Hard gate:** changed `_posts/*.md` MUST satisfy `schema/post-metadata.schema.json` - (run `node scripts/validate-frontmatter.cjs `). Legacy posts are exempt - (not re-validated on unrelated commits). + +## Decision on the DAO / BCI / VR / CRDT layer (2026-08-15) + +Per the consolidation phase, this layer is kept as a **frozen, documented R&D +sandbox** (option b): it demonstrates engineering expertise but is not part of +the shipped blog. Concretely: + +- `src/` and `contracts/dao/` are retained and still compiled/tested in CI. +- **Secret-requiring deploy workflows are disabled by default:** + - `deploy-dao.yml` — split into a `test` job (no secrets, runs on push/PR to + `contracts/**`) and a `deploy` job that is `guarded` (fails loudly without + `DEPLOY_PRIVATE_KEY` / `SEPOLIA_RPC_URL`). Deploy does NOT run from PRs. + - `deploy-ipfs.yml` — **disabled** (legacy Jekyll build + Pinata credentials + were compromised 2026-08-14; `pre-phase7-legacy` tag preserves the last + Jekyll state if recovery is ever needed). +- `vr-export.yml` — kept build-only (emits `assets/vr` artifact, no Pages flip). + +## CI contract (Content Model gate) + +Single source of truth for post metadata: `schema/post-metadata.schema.json`, +enforced by `scripts/ci-content-contract.cjs` (run in `hugo.yml` as a soft gate). + +- **Hard gate:** changed `content/blog/*.md` MUST satisfy the schema + (run `node scripts/validate-frontmatter.cjs `). - **Soft gate:** `scripts/ai-review.cjs` on changed posts (reported, non-fatal). -- **Emit:** `assets/data/knowledge-graph.json` (JSON-LD) for Vector Search / KG. -See `docs/CONTENT_CONTRACT.md`. Run `node scripts/ci-content-contract.cjs` locally -to simulate the gate. +- **Emit:** `static/data/knowledge-graph.json` (JSON-LD), published to + `/data/knowledge-graph.json`. + +Run `node scripts/ci-content-contract.cjs` locally to simulate the gate. ## Local workflow + ```bash -npm ci # install (lockfile must match package.json) -npm run lint # eslint src/ tests/ -npm test # smoke (17) + jest (179) -npm run build:production # esbuild -> js/refactored-bundle.js +npm ci # install +npm run lint # eslint src/ tests/ +npm test # jest unit tests (ES-module plane) +npm run build # hugo --gc --minify -> ./public +hugo server -D # local preview (drafts on) +npx hardhat test # Solidity DAO tests (engineering plane) ``` -CI runs `npm ci` then the Jekyll pipeline; `npm ci` FAILS if lock is out of sync -— regenerate `package-lock.json` via `npm install` after editing `package.json`. - -## Gotchas (learned) -- `node_modules/` is gitignored (never committed); `npm ci` rebuilds it in CI. -- `jest-environment-jsdom` must stay `^29.7.0` (matches jest 29 + lockfile). -- Actions `upload-artifact@v3` is hard-blocked by GitHub — use `@v4`. -- Edited source under `src/` must be re-bundled (`npm run build:production`) or - the deployed site won't reflect changes. - -## Legacy notes (superseded) -Older docs described a `js/*.js` + `css/*.min.css` + Jekyll 3.10.0 layout with a -~238KB bundle. That layout is replaced by the `src/` + esbuild pipeline above. + +`hugo` is NOT installed in this environment's default toolchain (NixOS CGO +issue). A pure-Go binary is built with +`CGO_ENABLED=0 GOFLAGS=-mod=mod go install github.com/gohugoio/hugo@v0.164.0` +and lives at `$(go env GOPATH)/bin/hugo`. `hugo.yml` uses `peaceiris/actions-hugo` +in CI, so the version there is authoritative. + +## Gotchas (learned during migration) + +- Pages source MUST be `GitHub Actions` (Settings UI), not `branch: main` + (legacy Jekyll). The API returns 422 for this switch — it is a manual step. +- Blowfish reads `theme = "blowfish"` from `config/_default/config.toml`, NOT + from `hugo.toml` (Hugo ignores `theme` there). +- `enableSearch = true` requires `assets/lib/fuse/fuse.min.cjs` in PROJECT + assets — `resources.Get` does not see the theme submodule's copy. +- `og:image` uses `params.defaultSocialImage` resolved via `resources.Get`, so + the file must live in `assets/` (e.g. `assets/images/og-default.svg`), not + `static/`. +- Posts dated in the future are NOT rendered by Hugo without `--future`. +- Branch protection requires `--admin` for merges; branch is `main` (no `master`). + +## Coverage baseline (measured 2026-08-15, c8) + +| Metric | Value | +|--------|-------| +| Statements | 76.57% | +| Branch | 64.52% | +| Functions | 73.3% | +| Lines | 76.57% | + +This is the **official baseline** (not the aspirational 85% target, which +requires an E2E/Playwright layer — see `STRATEGIC_PLAN_2026-2027.md` Q3 2026). +Do not regress below these numbers on the `src/` plane without adding tests. diff --git a/README.md b/README.md index d4a7b0f33..99141f567 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # dominicusin.github.io — Engineering Blog (Hugo + Blowfish) [![Deploy](https://github.com/dominicusin/dominicusin.github.io/actions/workflows/hugo.yml/badge.svg)](https://github.com/dominicusin/dominicusin.github.io/actions/workflows/hugo.yml) -[![Tests](https://img.shields.io/badge/tests-277%20passed-brightgreen)](tests/) +[![Tests](https://img.shields.io/badge/tests-277%20jest%20%2B%209%20hardhat-brightgreen)](tests/) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) > Static engineering blog built with **Hugo** + the **Blowfish** theme, deployed to GitHub Pages. @@ -29,6 +29,9 @@ This repository deliberately separates **publishing** from **engineering tooling - `src/` — v4.0 frontend modules (CRDT/P2P/DAO/BCI adapters). Retained for the engineering substrate; not bundled into the static site (Hugo ignores `src/`). +See [`docs/adr/0002-two-plane-architecture.md`](docs/adr/0002-two-plane-architecture.md) for the +formal two-plane boundary, integration points, and DAO lifecycle. + ## 🛠 Local development ```bash @@ -50,8 +53,12 @@ The site is served from `public/` after a build. `public/` and `resources/` are (title, date ISO-8601, categories, tags, authors, draft, slug). - Legacy permalinks are preserved via Hugo `aliases` (e.g. `/2015/11/19/first.html` → `/2015/11/19/first/`). - The `content/posts` → `content/blog` rename keeps post URLs intact; `/posts/` now aliases `/blog/`. -- Every changed post is validated against `schema/post-metadata.schema.json` in CI - (`scripts/ci-content-contract.cjs` — soft gate; legacy posts lacking tags/author are reported, not blocked). +- Every **new** post (added in a PR) is validated as a **hard gate** against + `schema/post-metadata.schema.json` in CI (`scripts/ci-content-contract.cjs`): + an invalid new post **blocks the deploy**. Modified legacy posts (e.g. 2015 + posts lacking tags/author) are report-only and do not block. +- Author hint: run `node scripts/ci-content-contract.cjs` locally before push to + self-check; `node scripts/validate-frontmatter.cjs content/blog/` validates a single post. ## 🔧 Key files @@ -66,6 +73,27 @@ The site is served from `public/` after a build. `public/` and `resources/` are | `contracts/dao/`, `tests/hardhat/` | DAO engineering plane | | `.github/workflows/hugo.yml` | The only GitHub Pages publisher | +## ⚙️ CI/CD (single publisher model) + +Only `.github/workflows/hugo.yml` deploys to GitHub Pages. Other workflows are +quality/support and never flip the Pages source. + +| Workflow | Purpose | Deploys? | +|----------|---------|----------| +| `hugo.yml` | Build + **content-contract hard gate (new posts)** + deploy to Pages | ✅ yes | +| `hugo-build-check.yml` | Build-only sanity check | ❌ | +| `security.yml` | Node audit + Trivy + Semgrep (weekly) | ❌ | +| `performance.yml` | Lighthouse audit against live Pages URL | ❌ | +| `dependency-update.yml` | Dependabot-driven bumps | ❌ | +| `link-repair.yml` | Scheduled broken-link check | ❌ | +| `deploy-dao.yml` | `test` job (Hardhat, no secrets) + guarded `deploy` (needs secrets) | ❌ (separate track) | +| `vr-export.yml` | Build-only VR artifact (no Pages flip) | ❌ | +| `sync_gists.yml`, `analytics.yml`, `fediverse-notify.yml` | Post-deploy integrations | ❌ | +| `deploy-ipfs.yml` | **DISABLED** (legacy Jekyll + compromised Pinata) | ❌ | + +> The legacy Jekyll CI (`ci.yml`, `jekyll.yml`, `ci-cd.yml`) was removed in +> Phase 7. Do not reintroduce `bundle exec jekyll build` — the site is Hugo-only. + ## 🧹 Legacy (removed) The legacy Jekyll + esbuild stack (`_config.yml`, `Gemfile`, `_layouts/`, `_includes/`, diff --git a/docs/adr/0002-two-plane-architecture.md b/docs/adr/0002-two-plane-architecture.md new file mode 100644 index 000000000..4db1c8e36 --- /dev/null +++ b/docs/adr/0002-two-plane-architecture.md @@ -0,0 +1,56 @@ +# ADR 0002 — Two-plane repository architecture (Publishing vs Engineering) + +- **Status:** Accepted (verified 2026-08-15, after SSG migration + Phase 7) +- **Context:** The repository was migrated from a Jekyll + esbuild stack to + Hugo + Blowfish (publishing) while retaining an engineering substrate + (`src/` frontend modules, `contracts/dao/` Solidity, `tests/hardhat/`). Before + this ADR the boundary was only described informally; CI mixed publishing and + engineering concerns (e.g. Jekyll CI attempted to deploy, DAO deploy shared the + repo). We need an explicit, operable boundary so that a Hugo failure never + implies an engineering failure and vice-versa. +- **Decision:** The repository has two explicit planes: + - **Publishing Plane** — ships the static site. + - Generator: Hugo (extended) v0.164.0 + Blowfish v2.105.0 (submodule). + - Content: `content/` (`blog/`, `people/`, `domini/`, `knowledge-graph/`). + - Config: `config/_default/`, `i18n/`, `layouts/`, `assets/`, `static/`. + - Single publisher: `.github/workflows/hugo.yml` → GitHub Pages (source = + "GitHub Actions"). Nothing else may flip the Pages source. + - Comments: giscus (GitHub Discussions). Subscription: Buttondown. + - **Engineering Plane** — R&D, NOT deployed to the site. + - `src/` — v4.0 ES modules (CRDT/P2P/DAO/BCI adapters). Not bundled by Hugo. + - `contracts/dao/` — Solidity (GovernanceToken, SoulboundToken, ProposalEngine). + - `tests/hardhat/` — Hardhat tests (`npx hardhat test`, 9 passing). + - `scripts/` — content-contract + knowledge-graph generation (Node tooling). + - **Content Contract** is the publishing-plane gate: new posts in + `content/blog/` MUST satisfy `schema/post-metadata.schema.json` (hard gate in + `hugo.yml`); modified legacy posts are report-only. + - **Knowledge Graph** (`static/data/knowledge-graph.json`, JSON-LD) is a + publishing-plane output generated from the engineering-plane scripts. +- **Integration points (allowed):** + - Generated JSON (knowledge-graph) copied into `static/` by the build. + - Hugo partials/shortcodes that read generated data. + - Public demo pages that link to, but do not bundle, `src/` artifacts. + - `scripts/` invoked by `hugo.yml` for content-contract + KG emission. +- **Non-integration (forbidden):** + - Hugo MUST NOT `import` runtime code from `src/` (the static site ignores it). + - `contracts/dao/` MUST NOT be deployed to GitHub Pages (separate Hardhat track). + - Publishing and engineering deploys are independent workflows with independent + failure domains. +- **DAO lifecycle (separate track):** `deploy-dao.yml` splits into a `test` job + (no secrets, runs on push/PR to `contracts/**`) and a guarded `deploy` job that + fails loudly without `DEPLOY_PRIVATE_KEY` / `SEPOLIA_RPC_URL`. DAO deploy does + NOT run from PRs and is independent of the Hugo deploy. +- **Verification (reproducible):** + - `themes/blowfish` is the only theme; `config/_default/config.toml` sets + `theme = "blowfish"`. + - Exactly one workflow has `pages: write` + `actions/deploy-pages` → `hugo.yml`. + - `ci-content-contract.cjs` exits non-zero only for ADDED (new) invalid posts. + - `npm run build` (Hugo) succeeds without any `src/` or `contracts/` artifact. +- **Consequences:** + - A change to `src/` or `contracts/dao/` does not require a site rebuild. + - A schema violation on a new post blocks the site deploy (quality enforced). + - Engineering plane may be frozen/extended without touching the publishing plane. +- **Alternatives considered:** + - Physical split into `website/` + `engineering/` subdirs (deferred — large + reference churn, no immediate architectural win; logical boundary is enough). + - Single combined CI that deploys both (rejected — couples failure domains). diff --git a/scripts/ci-content-contract.cjs b/scripts/ci-content-contract.cjs index ce0cbeddf..ec9a71405 100644 --- a/scripts/ci-content-contract.cjs +++ b/scripts/ci-content-contract.cjs @@ -2,17 +2,19 @@ /** * @fileoverview CI Content Contract gate (Vector A foundation) * - * Runs the Agent-driven Publishing Protocol checks on CHANGED posts only, - * so the formal Content Model (schema/post-metadata.schema.json) is enforced - * as a pre-merge gate without retroactively failing the legacy corpus: - * 1. validate-frontmatter -> hard gate (exit 1 if any changed post invalid) - * 2. ai-review -> soft gate (warnings, never fails the build) - * 3. build-knowledge-graph -> emits assets/data/knowledge-graph.json (JSON-LD) + * Enforces the formal Content Model (schema/post-metadata.schema.json) as a + * publishing contract. Two tiers, by change type: + * - ADDED posts -> HARD gate (exit 1 if any new post is invalid). New + * publications MUST satisfy the schema before merge. + * - MODIFIED posts -> SOFT gate (reported, never fails the build). Legacy + * corpus (e.g. 2015 posts lacking tags/author) may carry + * historical violations we do not retroactively enforce. + * - Knowledge Graph (JSON-LD) is always emitted for the whole corpus. * - * Changed post detection: + * Post detection (git): * - PR context: git diff --name-only origin/main...HEAD * - Push context: git diff --name-only HEAD~1 HEAD - * - fallback: validate ALL posts (so a misconfigured runner still gates) + * - fallback: all posts (so a misconfigured runner still gates new ones) */ const { execFileSync } = require('child_process'); @@ -31,14 +33,11 @@ function runGit(args) { } function getChangedPosts() { - // PR context let out = runGit(['diff', '--name-only', 'origin/main...HEAD']); if (!out) { - // Push context out = runGit(['diff', '--name-only', 'HEAD~1', 'HEAD']); } if (!out) { - // Fallback: all posts (ensures gate still runs if git is unavailable) console.log('⚠️ Could not determine changed files; falling back to all posts.'); return fs.readdirSync(path.join(ROOT, 'content', 'blog')) .filter(f => f.endsWith('.md') || f.endsWith('.markdown')) @@ -47,6 +46,21 @@ function getChangedPosts() { return out.split('\n').filter(line => POSTS_RE.test(line.trim())).map(l => l.trim()); } +function getAddedPosts() { + let out = runGit(['diff', '--diff-filter=A', '--name-only', 'origin/main...HEAD']); + if (!out) { + out = runGit(['diff', '--diff-filter=A', '--name-only', 'HEAD~1', 'HEAD']); + } + if (!out) { + // Fallback: no git context — treat every post as a candidate new post so + // the hard gate still protects the corpus if the runner lacks history. + return fs.readdirSync(path.join(ROOT, 'content', 'blog')) + .filter(f => f.endsWith('.md') || f.endsWith('.markdown')) + .map(f => path.join('content', 'blog', f)); + } + return out.split('\n').filter(line => POSTS_RE.test(line.trim())).map(l => l.trim()); +} + function spawnOk(cmd, cmdArgs) { try { execFileSync(cmd, cmdArgs, { cwd: ROOT, stdio: 'inherit' }); @@ -58,30 +72,33 @@ function spawnOk(cmd, cmdArgs) { function main() { const changed = getChangedPosts(); - console.log(`\n🔎 Content Contract: ${changed.length} changed post(s) detected\n`); + const added = getAddedPosts(); + const modified = changed.filter(f => !added.includes(f)); - if (changed.length === 0) { - console.log('✅ No post changes — content contract vacuously satisfied.'); - } else { - // 1. Hard gate: frontmatter validation + console.log(`\n🔎 Content Contract: ${changed.length} changed, ${added.length} added (hard gate), ${modified.length} modified (report-only)\n`); + + // 1. HARD gate: new posts MUST satisfy the schema. + if (added.length > 0) { let gateFailed = false; - for (const file of changed) { + for (const file of added) { const ok = spawnOk('node', [path.join('scripts', 'validate-frontmatter.cjs'), file]); if (!ok) gateFailed = true; } if (gateFailed) { - console.error('\n❌ Content Model contract FAILED for changed post(s). Fix frontmatter before merge.'); + console.error('\n❌ Content Model contract FAILED for NEW post(s). Fix frontmatter before merge — new publications are blocked.'); process.exit(1); } - console.log('\n✅ Content Model contract satisfied for all changed posts.'); + console.log('✅ Content Model contract satisfied for all new posts.'); + } else { + console.log('✅ No new posts — hard gate vacuously satisfied.'); + } - // 2. Soft gate: AI review (informational) - for (const file of changed) { - spawnOk('node', [path.join('scripts', 'ai-review.cjs'), file]); - } + // 2. SOFT gate: AI review on changed posts (informational, never fails). + for (const file of changed) { + spawnOk('node', [path.join('scripts', 'ai-review.cjs'), file]); } - // 3. Emit Knowledge Graph (JSON-LD) for all posts + // 3. Emit Knowledge Graph (JSON-LD) for all posts. console.log('\n🕸️ Building Knowledge Graph (JSON-LD)...'); spawnOk('node', [path.join('scripts', 'build-knowledge-graph.cjs')]);