From c3b14b9b712ef78de4858ff63115e352944defac Mon Sep 17 00:00:00 2001 From: Eason WaveKat Date: Sat, 23 May 2026 16:31:16 +1200 Subject: [PATCH 1/4] feat(sync-docs): enable wavekat-voice docs Pulls voice docs from the private wavekat-voice repo's docs/site/ into /docs/voice/, surfacing the provider setup guides the desktop client's onboarding picker links to via help_url. Requirements / coordination: - The Cloudflare Pages build env must set GITHUB_TOKEN (fine-grained PAT with read access to wavekat-voice). Without it, the build fails at sync time with a clear error from scripts/sync-docs.js. - The sync pins to the latest semver tag on wavekat-voice; new docs only show up on wavekat.com after a release is cut. Merge AFTER wavekat-voice ships v0.0.13 (or whichever release first contains the rewritten docs/site/), otherwise the build publishes the outdated v0.0.12 stubs that describe the prior Docker product. Co-Authored-By: Claude Opus 4.7 (1M context) --- scripts/sync-docs.js | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/scripts/sync-docs.js b/scripts/sync-docs.js index 8f13b4f..5444883 100644 --- a/scripts/sync-docs.js +++ b/scripts/sync-docs.js @@ -35,13 +35,12 @@ const tmpDir = join(root, ".sync-docs-tmp"); // Edit this list as new product docs come online. `docsPath` is the path // inside each product repo where publishable docs live (relative to repo // root). Default is "docs/site" — keeps repo /docs/ free for internal -// planning. wavekat-voice (when re-enabled) uses "docs" since it predates -// the convention. +// planning. const sources = [ - { slug: "cli", repo: "wavekat/wavekat-cli", docsPath: "docs/site", private: false }, + { slug: "cli", repo: "wavekat/wavekat-cli", docsPath: "docs/site", private: false }, + { slug: "voice", repo: "wavekat/wavekat-voice", docsPath: "docs/site", private: true }, // { slug: "vad", repo: "wavekat/wavekat-vad", docsPath: "docs/site", private: false }, // { slug: "turn", repo: "wavekat/wavekat-turn", docsPath: "docs/site", private: false }, - // { slug: "voice", repo: "wavekat/wavekat-voice", docsPath: "docs", private: true }, // { slug: "lab", repo: "wavekat/wavekat-lab", docsPath: "docs/site", private: false }, // { slug: "core", repo: "wavekat/wavekat-core", docsPath: "docs/site", private: false }, // { slug: "tts", repo: "wavekat/wavekat-tts", docsPath: "docs/site", private: false }, From e3c757177309b4cd2d68070e2f03d6757d32a752 Mon Sep 17 00:00:00 2001 From: Eason WaveKat Date: Sat, 23 May 2026 16:51:41 +1200 Subject: [PATCH 2/4] ci: pass SYNC_DOCS_TOKEN to cf:build for private docs sync The sync-docs step clones wavekat-voice (private), which fails under the default GITHUB_TOKEN since that token is scoped to this repo only. Wire a fine-grained PAT secret through ci/preview/release workflows. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/ci.yml | 2 ++ .github/workflows/preview.yml | 2 ++ .github/workflows/release.yml | 2 ++ 3 files changed, 6 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3b04d7b..dcfbdf8 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -21,3 +21,5 @@ jobs: - run: npm ci - run: npm run cf:build + env: + GITHUB_TOKEN: ${{ secrets.SYNC_DOCS_TOKEN }} diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml index 4dea37c..641ebce 100644 --- a/.github/workflows/preview.yml +++ b/.github/workflows/preview.yml @@ -24,6 +24,8 @@ jobs: - run: npm ci - run: npm run cf:build + env: + GITHUB_TOKEN: ${{ secrets.SYNC_DOCS_TOKEN }} - name: Deploy preview id: deploy diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 5fd5da2..30927cf 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -36,6 +36,8 @@ jobs: - run: npm ci - run: npm run cf:build + env: + GITHUB_TOKEN: ${{ secrets.SYNC_DOCS_TOKEN }} - run: npm run cf:deploy env: From ec9302bc1e0c6027a00e3a5a7d559176ffd01e08 Mon Sep 17 00:00:00 2001 From: Eason WaveKat Date: Sat, 23 May 2026 17:01:23 +1200 Subject: [PATCH 3/4] ci: debug step to diagnose SYNC_DOCS_TOKEN reach MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Token works locally via gh api but git ls-remote in CI returns "Repository not found" — investigating whether the env var reaches the process or a runner-level credential helper is shadowing the URL-embedded token. Will be reverted once the cause is identified. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/ci.yml | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index dcfbdf8..eb003c1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -20,6 +20,17 @@ jobs: - run: npm ci + - name: Debug token reach + env: + GITHUB_TOKEN: ${{ secrets.SYNC_DOCS_TOKEN }} + run: | + echo "token set: ${GITHUB_TOKEN:+yes}, length: ${#GITHUB_TOKEN}" + echo "--- global git config ---" + git config --global --list || true + echo "--- ls-remote with URL token ---" + git ls-remote --tags --refs "https://x-access-token:${GITHUB_TOKEN}@github.com/wavekat/wavekat-voice.git" | head -5 \ + || echo "ls-remote FAILED" + - run: npm run cf:build env: GITHUB_TOKEN: ${{ secrets.SYNC_DOCS_TOKEN }} From a2a67cbb82baedb9813838be9fc14b43554d4fcc Mon Sep 17 00:00:00 2001 From: Eason WaveKat Date: Sat, 23 May 2026 17:24:41 +1200 Subject: [PATCH 4/4] ci: rename token env to SYNC_DOCS_TOKEN (no GITHUB_TOKEN shadow) The cf:build step previously overrode GITHUB_TOKEN with the docs PAT, which is confusing to read and shadows the default Actions token. Pass the secret through under its own name end-to-end and have sync-docs.js read SYNC_DOCS_TOKEN directly. Also drops the debug step now that the PAT is verified working. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/ci.yml | 13 +------------ .github/workflows/preview.yml | 2 +- .github/workflows/release.yml | 2 +- scripts/sync-docs.js | 12 ++++++------ 4 files changed, 9 insertions(+), 20 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index eb003c1..3ff4df8 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -20,17 +20,6 @@ jobs: - run: npm ci - - name: Debug token reach - env: - GITHUB_TOKEN: ${{ secrets.SYNC_DOCS_TOKEN }} - run: | - echo "token set: ${GITHUB_TOKEN:+yes}, length: ${#GITHUB_TOKEN}" - echo "--- global git config ---" - git config --global --list || true - echo "--- ls-remote with URL token ---" - git ls-remote --tags --refs "https://x-access-token:${GITHUB_TOKEN}@github.com/wavekat/wavekat-voice.git" | head -5 \ - || echo "ls-remote FAILED" - - run: npm run cf:build env: - GITHUB_TOKEN: ${{ secrets.SYNC_DOCS_TOKEN }} + SYNC_DOCS_TOKEN: ${{ secrets.SYNC_DOCS_TOKEN }} diff --git a/.github/workflows/preview.yml b/.github/workflows/preview.yml index 641ebce..99bc9cd 100644 --- a/.github/workflows/preview.yml +++ b/.github/workflows/preview.yml @@ -25,7 +25,7 @@ jobs: - run: npm run cf:build env: - GITHUB_TOKEN: ${{ secrets.SYNC_DOCS_TOKEN }} + SYNC_DOCS_TOKEN: ${{ secrets.SYNC_DOCS_TOKEN }} - name: Deploy preview id: deploy diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 30927cf..2b10351 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -37,7 +37,7 @@ jobs: - run: npm run cf:build env: - GITHUB_TOKEN: ${{ secrets.SYNC_DOCS_TOKEN }} + SYNC_DOCS_TOKEN: ${{ secrets.SYNC_DOCS_TOKEN }} - run: npm run cf:deploy env: diff --git a/scripts/sync-docs.js b/scripts/sync-docs.js index 5444883..425e2ea 100644 --- a/scripts/sync-docs.js +++ b/scripts/sync-docs.js @@ -19,9 +19,9 @@ // instead of cloning (no GitHub token required). Falls // through to clone if a local copy is missing. // -// Auth note: cloning private repos on Cloudflare Pages requires GITHUB_TOKEN -// to be set in the Pages environment to a fine-grained PAT with read access -// to the relevant repos. +// Auth note: cloning private repos requires SYNC_DOCS_TOKEN to be set to a +// fine-grained PAT with read access to the relevant repos. In CI it's +// passed in from the SYNC_DOCS_TOKEN repo secret. import { existsSync, mkdirSync, rmSync, cpSync, writeFileSync } from "fs"; import { execSync } from "child_process"; @@ -52,12 +52,12 @@ const enabled = process.env.SYNC_DOCS === "1"; const localBase = process.env.WAVEKAT_LOCAL_REPOS; function repoUrl({ repo, private: isPrivate }) { - const token = process.env.GITHUB_TOKEN; + const token = process.env.SYNC_DOCS_TOKEN; if (isPrivate) { if (!token) { throw new Error( - `GITHUB_TOKEN required to clone private repo ${repo}. ` + - `Set it in the Cloudflare Pages environment (fine-grained PAT, read access).` + `SYNC_DOCS_TOKEN required to clone private repo ${repo}. ` + + `Set it to a fine-grained PAT with read access to the repo.` ); } return `https://x-access-token:${token}@github.com/${repo}.git`;