From f25e65efe47fa180fe476a5da271ff5a566c6311 Mon Sep 17 00:00:00 2001 From: Eric Rodriguez Date: Thu, 9 Jul 2026 18:35:55 +0200 Subject: [PATCH] docs: ship Homebrew/Scoop, add a task index, and polish for usefulness MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Distribution (now live): - Homebrew (wavyx/homebrew-tap Formula/pdcli.rb) and Scoop (wavyx/scoop-pdcli bucket/pdcli.json) are published for 0.22.0. brew install verified end-to-end incl --jq (the formula wires JQ_PATH to the Homebrew jq). distribution.mdx flipped from "coming soon" to working. - release.yml gains a `dist` job that regenerates + pushes both files to the tap repos on each stable release, gated on a TAP_TOKEN PAT secret (no-ops without it). gen-dist.mjs uses formula_opt_bin (brew audit clean). Usefulness / engagement: - New start/tasks.mdx — a "Which command do I use?" job-to-command index (the biggest discoverability gap across 154 commands); wired into the sidebar, Start-here reordered Installation → Quickstart → Distribution. - agents.mdx: the capability tour is now scannable grouped subsections (read / write-safely / react / sync / MCP) instead of one long paragraph. - mcp.mdx: a "verify it is running" note and a real payoff vignette. - troubleshooting.mdx: the npm-11 jq-binary trap, plus 429 and 400/422 entries and an exit-codes link. - analytics.mdx: an orientation table (command → question) + gotcha asides. - Home.astro: self-hosted demo.svg (was a raw.githubusercontent hotlink) and clickable AI-agents card / MCP terminal → docs. - ci.mdx dedups the workflow with github-actions.mdx; config/api/custom- fields/contributing quick-wins. Claude-Session: https://claude.ai/code/session_018dRMUUj9vpKp3tqKQFsvE9 --- .github/workflows/release.yml | 49 +++++++++++ packaging/README.md | 12 ++- scripts/gen-dist.mjs | 2 +- website/astro.config.mjs | 3 +- website/public/demo.svg | 19 ++++ website/src/components/Home.astro | 66 +++++++++----- website/src/content/docs/automation/ci.mdx | 29 +++---- website/src/content/docs/contributing.mdx | 7 ++ website/src/content/docs/guides/analytics.mdx | 34 ++++++++ website/src/content/docs/guides/api.mdx | 4 +- .../src/content/docs/guides/configuration.mdx | 2 + .../src/content/docs/guides/custom-fields.mdx | 2 +- website/src/content/docs/guides/mcp.mdx | 34 ++++++++ .../docs/reference/troubleshooting.mdx | 46 ++++++++++ website/src/content/docs/start/agents.mdx | 85 +++++++++++------- .../src/content/docs/start/distribution.mdx | 29 ++----- website/src/content/docs/start/tasks.mdx | 86 +++++++++++++++++++ 17 files changed, 412 insertions(+), 97 deletions(-) create mode 100644 website/public/demo.svg create mode 100644 website/src/content/docs/start/tasks.mdx diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 606a03d..f61295e 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -128,3 +128,52 @@ jobs: tags: | ghcr.io/${{ github.repository }}:${{ steps.ver.outputs.v }} ${{ steps.ver.outputs.latest }} + + dist: + name: Publish Homebrew + Scoop + needs: release # regenerate from the just-published npm tarball + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + - uses: actions/setup-node@v5 + with: + node-version: 22 + + # Regenerate the formula + manifest from the published tarball (sha256). + - name: Generate dist files + id: gen + run: | + V=$(node -p "require('./package.json').version") + echo "v=$V" >> "$GITHUB_OUTPUT" + node scripts/gen-dist.mjs "$V" + + # Cross-repo push needs a PAT (the default GITHUB_TOKEN is scoped to this + # repo). Add a fine-grained TAP_TOKEN secret with contents:write on + # wavyx/homebrew-tap and wavyx/scoop-pdcli to enable auto-publish; without + # it this step no-ops so the release never fails on a missing secret. + # Prereleases are skipped (they must not move the stable formula/manifest). + - name: Push to tap repos + env: + TAP_TOKEN: ${{ secrets.TAP_TOKEN }} + V: ${{ steps.gen.outputs.v }} + run: | + case "$V" in *-*) echo "prerelease $V — skipping tap publish"; exit 0 ;; esac + if [ -z "$TAP_TOKEN" ]; then + echo "No TAP_TOKEN secret — skipping Homebrew/Scoop publish." + echo "Run 'node scripts/gen-dist.mjs $V' and push manually, or add the PAT." + exit 0 + fi + git config --global user.name "pdcli-release" + git config --global user.email "release@wavyx.dev" + push_file() { + repo="$1"; src="$2"; dest="$3" + tmp=$(mktemp -d) + git clone --depth 1 "https://x-access-token:${TAP_TOKEN}@github.com/${repo}.git" "$tmp" + mkdir -p "$(dirname "$tmp/$dest")" + cp "$src" "$tmp/$dest" + git -C "$tmp" add "$dest" + git -C "$tmp" commit -m "pdcli $V" || { echo "no change for $repo"; return 0; } + git -C "$tmp" push + } + push_file wavyx/homebrew-tap packaging/homebrew/pdcli.rb Formula/pdcli.rb + push_file wavyx/scoop-pdcli packaging/scoop/pdcli.json bucket/pdcli.json diff --git a/packaging/README.md b/packaging/README.md index b1f4d2f..ac96cd8 100644 --- a/packaging/README.md +++ b/packaging/README.md @@ -25,9 +25,15 @@ This downloads the npm tarball, computes its sha256, and writes: Both generated files are git-ignored here — they live in their own repos. -> Auto-bumping these on every release would need a cross-repo token (PAT); for -> now it's a one-line manual step. The Docker image and npm publish are fully -> automated in `.github/workflows/release.yml`. +## Automation + +The `dist` job in `.github/workflows/release.yml` regenerates both files from the +just-published tarball and pushes them to the tap repos on every stable release — +**as long as a `TAP_TOKEN` secret exists**. It must be a fine-grained PAT with +`contents:write` on `wavyx/homebrew-tap` and `wavyx/scoop-pdcli`. Without the +secret the job no-ops (the release never fails), and you publish with the manual +`node scripts/gen-dist.mjs ` step above. npm publish and the Docker image +are always automated. ## Container security caveat (env-var tokens) diff --git a/scripts/gen-dist.mjs b/scripts/gen-dist.mjs index 289848f..2453772 100644 --- a/scripts/gen-dist.mjs +++ b/scripts/gen-dist.mjs @@ -29,7 +29,7 @@ export function renderHomebrewFormula({ url, sha256 }) { # Homebrew build sandbox blocks network, so point node-jq at the Homebrew jq # instead (node-jq honors $JQ_PATH at runtime). (bin/"pdcli").write_env_script libexec/"bin/pdcli", - JQ_PATH: Formula["jq"].opt_bin/"jq" + JQ_PATH: formula_opt_bin("jq")/"jq" end test do diff --git a/website/astro.config.mjs b/website/astro.config.mjs index 4f5dca7..41f23e3 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -94,8 +94,9 @@ export default defineConfig({ label: 'Start here', items: [ { label: 'Installation', slug: 'start/installation' }, - { label: 'Distribution (all channels)', slug: 'start/distribution' }, { label: 'Quickstart', slug: 'start/quickstart' }, + { label: 'Which command do I use?', slug: 'start/tasks' }, + { label: 'Distribution (all channels)', slug: 'start/distribution' }, ], }, { diff --git a/website/public/demo.svg b/website/public/demo.svg new file mode 100644 index 0000000..4ce1945 --- /dev/null +++ b/website/public/demo.svg @@ -0,0 +1,19 @@ + + + + + + +zsh · ~/acme +❯ pdcli pipeline health┌ SALES PIPELINE ───────────────── Q2 ┐Qualified 18 deals €142,000Contact 11 deals € 98,500Proposal 7 deals € 76,200Negotiation 4 deals € 51,000─────────────────────────────────────weighted forecast €221,480win rate 32% · avg cycle 24d❯ pdcli deal update 4821 --status won✓ Acme renewal → Won · activity logged❯ pdcli audit┌ DATA HYGIENE ──────────── 11 checks ┐● 3 duplicate deals● 5 deals stale > 30 days○ 8 missing a next step─────────────────────────────────────3 must-fix · audit --strict gates CI + diff --git a/website/src/components/Home.astro b/website/src/components/Home.astro index a758848..679d958 100644 --- a/website/src/components/Home.astro +++ b/website/src/components/Home.astro @@ -48,7 +48,7 @@ const steps: [string, string, string, string][] = [ ], ]; -const features: { t: string; b: string; d: string }[] = [ +const features: { t: string; b: string; d: string; href?: string }[] = [ { t: 'Backup & data export', b: 'Stream your entire account to JSON with pdcli backup --resume, or export any resource to CSV. Resumable, scriptable, and perfect for archives or migrations.', @@ -63,6 +63,7 @@ const features: { t: string; b: string; d: string }[] = [ t: 'Built for AI agents', b: 'Runs as an MCP server — pdcli mcp serve — read-only by default, giving Claude and other hosts a safe, typed tool surface. For shell-driven agents there is also self-documenting --help, clean JSON, and deterministic exit codes.', d: '', + href: 'start/agents/', }, { t: 'Scriptable by design', @@ -170,6 +171,20 @@ const showcaseTerm = `$ pdcli