diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..6ee64f0 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,24 @@ +# ext-template's own Dependabot config (not synced into extensions — +# the extensions get template/managed/.github/dependabot.yml instead). +# +# github-actions is enabled for both this repo's workflows and the +# managed workflow templates. A non-root `directory` makes Dependabot +# scan the YAML files directly inside it (dependabot-core +# github_actions/file_fetcher.rb: `workflows_dir = "."` for any +# directory other than "/"), and the unrendered templates parse as +# plain YAML because `{{PLACEHOLDER}}` is a valid flow mapping. A merged +# action bump here reaches every extension on its next bin/sync. +version: 2 +updates: + - package-ecosystem: github-actions + directories: + - / + - /template/managed/.github/workflows + schedule: + interval: weekly + day: monday + commit-message: + prefix: "chore(actions)" + groups: + actions: + patterns: ["*"] diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 31f8dca..0d53699 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -4,6 +4,11 @@ on: push: branches: [main] pull_request: + # Weekly, so a template that silently stopped rendering (a runner or + # shellcheck change) surfaces before the next sync needs it. + schedule: + - cron: '23 6 * * 1' + workflow_dispatch: env: FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true" @@ -18,7 +23,7 @@ jobs: - name: shellcheck run: | sudo apt-get update && sudo apt-get install -y shellcheck - shellcheck bin/render bin/sync bin/lib.sh + shellcheck bin/render bin/sync bin/lib.sh bin/upstream-check - name: Render smoke test # Render the example conf and assert (a) every expected file @@ -29,8 +34,9 @@ jobs: bin/render ext-template.conf.example /tmp/ext-example for f in Makefile build.rs about.toml about.hbs \ .github/workflows/ci.yml .github/workflows/release.yml \ - .github/workflows/docs.yml \ + .github/workflows/docs.yml .github/dependabot.yml \ Cargo.toml composer.json src/lib.rs src/error.rs \ + README.md PLAN.md CHANGELOG.md RELEASE.md \ .cargo/config.toml rust-toolchain.toml .ext-template.conf; do test -f "/tmp/ext-example/$f" || { echo "missing $f"; exit 1; } done @@ -41,7 +47,9 @@ jobs: import sys, yaml for p in ["/tmp/ext-example/.github/workflows/ci.yml", "/tmp/ext-example/.github/workflows/release.yml", - "/tmp/ext-example/.github/workflows/docs.yml"]: + "/tmp/ext-example/.github/workflows/docs.yml", + "/tmp/ext-example/.github/dependabot.yml", + ".github/dependabot.yml"]: yaml.safe_load(open(p)) print("yaml ok:", p) ' @@ -72,5 +80,5 @@ jobs: sed -i 's/^EXT_PHP_RS_PIN=.*/EXT_PHP_RS_PIN==9.9.9/' template/versions.conf bin/sync /tmp/ext-example grep -q 'ext-php-rs = "=9.9.9"' /tmp/ext-example/Cargo.toml - grep -rq '=9.9.9' /tmp/ext-example/rust-toolchain.toml && exit 1 || true + if grep -q '=9.9.9' /tmp/ext-example/rust-toolchain.toml; then exit 1; fi git checkout -- template/versions.conf diff --git a/.github/workflows/upstream-watch.yml b/.github/workflows/upstream-watch.yml new file mode 100644 index 0000000..a2ee00a --- /dev/null +++ b/.github/workflows/upstream-watch.yml @@ -0,0 +1,33 @@ +name: Upstream watch + +# Weekly check of the exactly-pinned crates Dependabot is told to ignore +# (template/upstream.conf): ext-php-rs and thiserror (owned by +# versions.conf) and each extension's primary upstream crate. One issue +# labelled `upstream` per lagging crate, kept current and closed when the +# pin catches up — so a bump is surfaced without an auto-PR that would +# skip the format and behaviour checks those bumps need. +# +# GitHub disables scheduled workflows in public repos after 60 days with +# no repository activity; Dependabot's weekly github-actions PRs on this +# repo are what keep it alive. + +on: + schedule: + - cron: '41 6 * * 1' # Mondays 06:41 UTC, after the extensions' CI + workflow_dispatch: + +permissions: + contents: read + issues: write + +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Compare pins against crates.io + env: + GH_TOKEN: ${{ github.token }} + GH_REPO: ${{ github.repository }} + run: bin/upstream-check --issues diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..51d69a0 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,49 @@ +# Changelog + +All notable changes to ext-template are documented here. The format is +based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). +Extensions pick changes up with `bin/sync`; the version records which +scaffold an extension was synced from. + +## [0.2.0] - 2026-10-29 + +### Added + +- Weekly scheduled CI and `workflow_dispatch` in the managed `ci.yml`. +- ZTS test legs (Linux, PHP 8.4 / 8.5), `continue-on-error` for now, + with a step that asserts the runner's `PHP_ZTS` matches the leg. +- Managed `.github/dependabot.yml`: grouped weekly cargo minor/patch, + ignoring the versions.conf pins and each extension's primary upstream + crate. +- ext-template's own Dependabot config for GitHub Actions, covering + `template/managed/.github/workflows`. +- `bin/upstream-check` + `template/upstream.conf` + the weekly + `upstream-watch` workflow: one `upstream` issue per exact pin that + falls behind crates.io. +- Seeds: README Status section, stack table and "Writing about this" + slot; PLAN.md as design notes; CHANGELOG.md. + +### Changed + +- `EXT_PHP_RS_PIN` `=0.15.13` → `=0.16.3`; `THISERROR_PIN` `=2.0.18` → + `=2.0.21`. +- `make stubs` writes to `target/` for a diff against the curated + stubs, and takes `STUBS_PRELOAD` for Linux. + +### Fixed + +- Linux CI and release builds on ubuntu-26.04 runners: bindgen's + libclang is pinned to libclang-dev's LLVM (the image mixes clang 20, + 21 and 22, which breaks ext-php-rs's bindings generation). +- `make stubs` passed a `--stubs` flag cargo-php never had. +- setup-php is unpinned (`@v2`) and the PHP 8.5 × macos-14 leg is back + (#1, July 2026), now synced into every extension. + +## [0.1.0] - 2026-06-12 + +First release: the `template/managed/` and `template/seed/` trees, +POSIX `bin/render` and `bin/sync`, per-repo `.ext-template.conf`, and +the `versions.conf` pin cascade. + +[0.2.0]: https://github.com/DisplaceTech/ext-template/compare/v0.1.0...v0.2.0 +[0.1.0]: https://github.com/DisplaceTech/ext-template/releases/tag/v0.1.0 diff --git a/README.md b/README.md index c16816f..8e9edab 100644 --- a/README.md +++ b/README.md @@ -26,8 +26,8 @@ extensions render from it and re-sync when it improves. | Tree | Files | Lifecycle | |---|---|---| -| `template/managed/` | Makefile, build.rs, about.toml/hbs, rust-toolchain.toml, CI/release/docs workflows | **Owned by the template.** Re-rendered into extensions by `bin/sync`; never hand-edit in a child repo. | -| `template/seed/` | Cargo.toml, composer.json, `.cargo/`, src skeleton, docs skeleton, PLAN/RELEASE | **Rendered once** at creation, then owned by the extension. Sync never touches them. | +| `template/managed/` | Makefile, build.rs, about.toml/hbs, rust-toolchain.toml, CI/release/docs workflows, `.github/dependabot.yml` | **Owned by the template.** Re-rendered into extensions by `bin/sync`; never hand-edit in a child repo. | +| `template/seed/` | Cargo.toml, composer.json, `.cargo/`, src skeleton, docs skeleton, README/PLAN/CHANGELOG/RELEASE | **Rendered once** at creation, then owned by the extension. Sync never touches them. | **Version bumps cascade.** `template/versions.conf` is the single source of truth for the Rust channel, the declared MSRV, and the crate @@ -68,6 +68,55 @@ git -C ../ext-infer diff # review — sync output is a proposal, not a comm Commit in the child as `chore: sync scaffold from ext-template@` so the provenance is greppable. +## Dependency updates and scheduled CI + +Naive Dependabot would fight `bin/sync`: a child-side PR bumping a +managed workflow or a versions.conf pin is reverted by the next sync. So +each kind of dependency has exactly one owner: + +| Dependency | Owner | How it moves | +| ---------- | ----- | ------------ | +| GitHub Actions (this repo's workflows **and** `template/managed/.github/workflows`) | ext-template's [`.github/dependabot.yml`](.github/dependabot.yml) | Weekly grouped PR here; merge, then `bin/sync` each extension. | +| `ext-php-rs`, `thiserror`, Rust channel | [`template/versions.conf`](template/versions.conf) | Deliberate bump here, cascaded by `bin/sync`; surfaced by the upstream watcher. | +| Each extension's primary upstream crate (`llama-cpp-2`, `turbovec`, `whisper-rs` and their `-sys` crates) | the extension's `Cargo.toml` | Deliberate, tested bump in the extension (format/behaviour checks per its RELEASE.md); surfaced by the upstream watcher. | +| Every other crate in an extension | the managed [`dependabot.yml`](template/managed/.github/dependabot.yml) synced into each child | Weekly grouped minor/patch cargo PR in the child; the classes above are ignored, and `github-actions` is not enabled there. | + +**Dependabot and the template path.** Dependabot scans a non-root +`directory` for workflow YAML directly (dependabot-core's +`github_actions/file_fetcher.rb` uses `workflows_dir = "."` for any +directory other than `/`), and the unrendered templates parse as YAML +(`{{PLACEHOLDER}}` is a valid flow mapping; checked with Ruby's +`YAML.safe_load`, the parser Dependabot uses), so action bumps for the +managed workflows land here once. + +**Upstream watcher.** [`bin/upstream-check`](bin/upstream-check) reads +[`template/upstream.conf`](template/upstream.conf) and compares each +exact pin Dependabot is told to ignore against crates.io's latest stable +release. The weekly [`upstream-watch`](.github/workflows/upstream-watch.yml) +workflow runs it with `--issues`: one `upstream`-labelled issue per +lagging crate in this repo, kept current as crates.io moves and closed +when the pin catches up. Run `bin/upstream-check` locally for a status +table. + +**Scheduled CI.** The managed `ci.yml` runs weekly (Mondays) and on +`workflow_dispatch`, so a green badge means "green this week". GitHub +disables scheduled workflows in public repos after 60 days with no +repository activity; the weekly Dependabot PRs, and merging them, are +what keep the schedules alive. If one goes dormant, re-enable it from +the Actions tab. + +**ZTS.** The managed CI matrix adds thread-safe PHP 8.4 and 8.5 legs on +Linux (setup-php `phpts: ts`), `continue-on-error` until they have a +track record. Release binaries stay NTS-only. + +## Stubs + +Committed stubs are curated (generics, `@throws`, prose), so +`make stubs` writes cargo-php's output to `target/` for a +signature diff instead of overwriting them. On Linux, cargo-php's +`dlopen()` needs PHP's embed library preloaded +(`make stubs STUBS_PRELOAD=/usr/lib/libphp8.4.so`); macOS needs nothing. + ## Placeholder convention Uppercase `{{LIKE_THIS}}`, substituted from `.ext-template.conf` — diff --git a/bin/upstream-check b/bin/upstream-check new file mode 100755 index 0000000..dd5544d --- /dev/null +++ b/bin/upstream-check @@ -0,0 +1,109 @@ +#!/bin/sh +# Report pinned upstream crates that have fallen behind crates.io. +# +# bin/upstream-check # print a status line per crate +# bin/upstream-check --issues # also open/update/close GitHub issues +# +# Reads template/upstream.conf. With --issues (the scheduled workflow), +# keeps exactly one open issue labelled `upstream` per lagging crate in +# the current repo (GH_REPO or the checkout's origin), updates its body +# when crates.io moves again, and closes it once the pin catches up. +# Needs curl and jq; --issues also needs an authenticated gh. +set -eu + +TEMPLATE_ROOT=$(CDPATH='' cd -- "$(dirname -- "$0")/.." && pwd) +CONF=$TEMPLATE_ROOT/template/upstream.conf +VERSIONS=$TEMPLATE_ROOT/template/versions.conf +UA="ext-template upstream-check (https://github.com/DisplaceTech/ext-template)" +LABEL=upstream + +ISSUES=0 +case "${1:-}" in + --issues) ISSUES=1 ;; + '') ;; + *) echo "usage: bin/upstream-check [--issues]" >&2; exit 2 ;; +esac + +# Print the exact version a Cargo.toml pins for crate $2, read from +# stdin-less file $1. Handles `crate = "=1.2.3"` and +# `crate = { version = "=1.2.3", ... }`. +cargo_pin() { + sed -n "s/^$2[[:space:]]*=[[:space:]]*\(.*\)$/\1/p" "$1" | head -1 | + sed -e 's/.*version[[:space:]]*=[[:space:]]*//' \ + -e 's/^"=\{0,1\}\([^"]*\)".*/\1/' +} + +latest_stable() { + curl -fsSL -A "$UA" "https://crates.io/api/v1/crates/$1" | + jq -r '.crate.max_stable_version' +} + +# True when $1 sorts strictly before $2 as a version. +older_than() { + [ "$1" != "$2" ] && + [ "$(printf '%s\n%s\n' "$1" "$2" | sort -V | head -1)" = "$1" ] +} + +ensure_label() { + gh label create "$LABEL" --color 0e8a16 \ + --description "A pinned upstream crate has a newer release" \ + >/dev/null 2>&1 || true +} + +# Number of the open upstream issue for crate $1, if any. +open_issue() { + gh issue list --label "$LABEL" --state open --limit 100 \ + --json number,title \ + --jq ".[] | select(.title | startswith(\"upstream: $1 \")) | .number" | + head -1 +} + +tmp=$(mktemp) +trap 'rm -f "$tmp"' EXIT +[ "$ISSUES" -eq 0 ] || ensure_label + +grep -v '^[[:space:]]*#' "$CONF" | grep -v '^[[:space:]]*$' | +while read -r source crate key; do + if [ "$source" = versions.conf ]; then + pinned=$(sed -n "s/^$key==\{0,1\}//p" "$VERSIONS" | head -1) + where="ext-template template/versions.conf ($key)" + else + curl -fsSL "https://raw.githubusercontent.com/$source/HEAD/Cargo.toml" -o "$tmp" + pinned=$(cargo_pin "$tmp" "$crate") + where="$source Cargo.toml" + fi + latest=$(latest_stable "$crate") + if [ -z "$pinned" ] || [ -z "$latest" ] || [ "$latest" = null ]; then + echo "error: could not resolve $crate (pinned='$pinned' latest='$latest')" >&2 + exit 1 + fi + + if older_than "$pinned" "$latest"; then + echo "BEHIND $crate =$pinned -> $latest ($where)" + else + echo "ok $crate =$pinned ($where)" + fi + + [ "$ISSUES" -eq 1 ] || continue + number=$(open_issue "$crate") + if older_than "$pinned" "$latest"; then + title="upstream: $crate $latest available (pinned =$pinned)" + body="\`$crate\` **$latest** is the latest stable release on crates.io; $where pins **=$pinned**. + +Upstream bumps are deliberate, tested events, not Dependabot PRs. Before bumping: + +- read the changelog between the two versions (https://crates.io/crates/$crate/versions); +- for ext-php-rs / thiserror: bump \`template/versions.conf\`, then \`bin/sync\` each extension and diff its regenerated stubs — any PHP signature change is a stop-and-decide; +- for a primary upstream crate: follow that extension's RELEASE.md upstream-bump procedure (format compatibility, behavioural re-verification, THIRD-PARTY-NOTICES). + +Opened by the scheduled upstream watcher (\`bin/upstream-check --issues\`); it updates this issue if crates.io moves again and closes it once the pin catches up." + if [ -n "$number" ]; then + gh issue edit "$number" --title "$title" --body "$body" >/dev/null + echo " updated #$number" + else + gh issue create --label "$LABEL" --title "$title" --body "$body" + fi + elif [ -n "$number" ]; then + gh issue close "$number" --comment "The pin is now =$pinned, which is current. Closing." + fi +done diff --git a/template/managed/.github/dependabot.yml b/template/managed/.github/dependabot.yml new file mode 100644 index 0000000..89b3d16 --- /dev/null +++ b/template/managed/.github/dependabot.yml @@ -0,0 +1,38 @@ +# Template-managed (ext-template): edit upstream in +# template/managed/.github/dependabot.yml, then bin/sync. See the +# "Dependency updates" section of ext-template's README for the design. +# +# Weekly, grouped minor/patch updates for the crates this extension owns. +# Three classes of dependency are deliberately excluded: +# +# - ext-php-rs, thiserror: their pins live in ext-template's +# template/versions.conf and cascade through bin/sync. A Dependabot PR +# here would be reverted by the next sync. +# - The primary upstream crate (llama-cpp-2 / turbovec / whisper-rs and +# their -sys crates): bumps are deliberate, tested events with format +# and behaviour checks. ext-template's scheduled upstream watcher opens +# an issue when one falls behind crates.io instead of a PR. +# - GitHub Actions: every workflow in this repo is template-managed. +# ext-template's own Dependabot config bumps action versions in +# template/managed/, and bin/sync carries them here. +version: 2 +updates: + - package-ecosystem: cargo + directory: / + schedule: + interval: weekly + day: monday + open-pull-requests-limit: 5 + commit-message: + prefix: "chore(deps)" + groups: + cargo-minor-patch: + update-types: [minor, patch] + ignore: + - dependency-name: ext-php-rs + - dependency-name: thiserror + - dependency-name: llama-cpp-2 + - dependency-name: llama-cpp-sys-2 + - dependency-name: turbovec + - dependency-name: whisper-rs + - dependency-name: whisper-rs-sys diff --git a/template/managed/.github/workflows/ci.yml b/template/managed/.github/workflows/ci.yml index 0719753..143817c 100644 --- a/template/managed/.github/workflows/ci.yml +++ b/template/managed/.github/workflows/ci.yml @@ -4,6 +4,15 @@ on: push: branches: [main] pull_request: + # Weekly run against fresh runners, toolchains, and setup-php so a green + # badge means "green this week", not "green at the last commit". + # GitHub disables scheduled workflows in public repos after 60 days with + # no repository activity; the weekly Dependabot PRs (and merging them) + # are what keep this schedule alive. If it ever goes dormant, re-enable + # it from the Actions tab or push any commit. + schedule: + - cron: '17 6 * * 1' # Mondays 06:17 UTC + workflow_dispatch: env: CARGO_TERM_COLOR: always @@ -31,6 +40,18 @@ jobs: run: | sudo apt-get update sudo apt-get install -y {{APT_DEPS}} + # Pin bindgen to the LLVM that libclang-dev installed. ubuntu-26.04 + # runners preinstall clang 20, 21 and 22; unpinned, clang-sys loads + # the newest libclang (22) while the builtin headers come from + # libclang-dev's LLVM (21), and clang 22 dropped x86 builtins those + # headers still call -> "Unable to generate bindings for PHP" + # (reproduced with ext-php-rs 0.15.13 and 0.16.3 alike). + v=$(dpkg-query -W -f='${Depends}' libclang-dev | grep -o 'libclang-[0-9]*-dev' | grep -o '[0-9]\+' | head -1) + echo "LIBCLANG_PATH=/usr/lib/llvm-$v/lib" >> "$GITHUB_ENV" + if [ -x "/usr/lib/llvm-$v/bin/clang" ]; then + echo "CLANG_PATH=/usr/lib/llvm-$v/bin/clang" >> "$GITHUB_ENV" + fi + echo "bindgen pinned to LLVM $v" - uses: shivammathur/setup-php@v2 with: @@ -48,9 +69,12 @@ jobs: - run: cargo clippy --all-targets -- -D warnings test: - name: test (PHP ${{ matrix.php }} / ${{ matrix.os }}) + name: test (PHP ${{ matrix.php }} ${{ matrix.ts }} / ${{ matrix.os }}) runs-on: ${{ matrix.os }} needs: lint + # ZTS legs are informational until they have a track record; NTS legs + # gate merges as before. + continue-on-error: ${{ matrix.ts == 'zts' }} strategy: fail-fast: false matrix: @@ -58,6 +82,12 @@ jobs: # 8.5 is the current stable; 8.4 is the most-deployed; 8.3 is # security-only through end of 2026 but still widely installed. php: ['8.3', '8.4', '8.5'] + ts: [nts] + include: + # Thread-safe PHP (FrankenPHP, Apache mpm_worker/event + mod_php, + # parallel). Linux only: setup-php's ZTS builds are Ubuntu-native. + - { os: ubuntu-latest, php: '8.4', ts: zts } + - { os: ubuntu-latest, php: '8.5', ts: zts } steps: - uses: actions/checkout@v4 @@ -66,6 +96,18 @@ jobs: run: | sudo apt-get update sudo apt-get install -y {{APT_DEPS}} + # Pin bindgen to the LLVM that libclang-dev installed. ubuntu-26.04 + # runners preinstall clang 20, 21 and 22; unpinned, clang-sys loads + # the newest libclang (22) while the builtin headers come from + # libclang-dev's LLVM (21), and clang 22 dropped x86 builtins those + # headers still call -> "Unable to generate bindings for PHP" + # (reproduced with ext-php-rs 0.15.13 and 0.16.3 alike). + v=$(dpkg-query -W -f='${Depends}' libclang-dev | grep -o 'libclang-[0-9]*-dev' | grep -o '[0-9]\+' | head -1) + echo "LIBCLANG_PATH=/usr/lib/llvm-$v/lib" >> "$GITHUB_ENV" + if [ -x "/usr/lib/llvm-$v/bin/clang" ]; then + echo "CLANG_PATH=/usr/lib/llvm-$v/bin/clang" >> "$GITHUB_ENV" + fi + echo "bindgen pinned to LLVM $v" - name: Install system deps (macOS) if: runner.os == 'macOS' @@ -77,6 +119,12 @@ jobs: php-version: ${{ matrix.php }} tools: none coverage: none + env: + phpts: ${{ matrix.ts == 'zts' && 'ts' || 'nts' }} + + - name: Confirm thread-safety mode + run: | + php -r 'echo "PHP ", PHP_VERSION, " ZTS=", var_export((bool) PHP_ZTS, true), "\n"; exit((PHP_ZTS ? "zts" : "nts") === "${{ matrix.ts }}" ? 0 : 1);' - name: Fetch run-tests.php run: | @@ -94,7 +142,7 @@ jobs: # fail to load into a PHP 8.4 process at runtime. - uses: Swatinem/rust-cache@v2 with: - key: php-${{ matrix.php }} + key: php-${{ matrix.php }}-${{ matrix.ts }} - name: Build run: cargo build --verbose diff --git a/template/managed/.github/workflows/release.yml b/template/managed/.github/workflows/release.yml index 521424e..e507d1e 100644 --- a/template/managed/.github/workflows/release.yml +++ b/template/managed/.github/workflows/release.yml @@ -23,9 +23,10 @@ name: Release # php_{{NAME}}-v0.1.0_php8.4-x86_64-linux-glibc-nts.tgz # php_{{NAME}}-v0.1.0_php8.3-arm64-linux-glibc-nts.tgz # -# (NTS-only for now; ZTS support is enabled in composer.json but no widely -# distributed ZTS PHP runner ships on the GitHub matrix yet — revisit when -# `shivammathur/setup-php` grows a TS option on the runners we use.) +# (NTS-only release binaries. ZTS is enabled in composer.json, so PIE +# builds from source on thread-safe PHP; ci.yml exercises ZTS on Linux via +# setup-php's `phpts: ts`. Shipping prebuilt -zts tarballs is a separate +# decision, made once those CI legs have a track record.) on: push: @@ -141,6 +142,18 @@ jobs: run: | sudo apt-get update sudo apt-get install -y {{APT_DEPS}} + # Pin bindgen to the LLVM that libclang-dev installed. ubuntu-26.04 + # runners preinstall clang 20, 21 and 22; unpinned, clang-sys loads + # the newest libclang (22) while the builtin headers come from + # libclang-dev's LLVM (21), and clang 22 dropped x86 builtins those + # headers still call -> "Unable to generate bindings for PHP" + # (reproduced with ext-php-rs 0.15.13 and 0.16.3 alike). + v=$(dpkg-query -W -f='${Depends}' libclang-dev | grep -o 'libclang-[0-9]*-dev' | grep -o '[0-9]\+' | head -1) + echo "LIBCLANG_PATH=/usr/lib/llvm-$v/lib" >> "$GITHUB_ENV" + if [ -x "/usr/lib/llvm-$v/bin/clang" ]; then + echo "CLANG_PATH=/usr/lib/llvm-$v/bin/clang" >> "$GITHUB_ENV" + fi + echo "bindgen pinned to LLVM $v" - name: Install system deps (macOS) if: runner.os == 'macOS' diff --git a/template/managed/Makefile b/template/managed/Makefile index effbc08..cf5545d 100644 --- a/template/managed/Makefile +++ b/template/managed/Makefile @@ -19,7 +19,7 @@ help: @echo " make clippy cargo clippy -- -D warnings" @echo " make fmt cargo fmt" @echo " make fmt-check cargo fmt --check" - @echo " make stubs Regenerate stubs/{{STUBS_FILE}}" + @echo " make stubs Generate target/{{STUBS_FILE}} to diff against stubs/" @echo " make install cargo php install (loads the extension into your PHP)" @echo " make uninstall cargo php remove" @echo " make clean cargo clean" @@ -83,8 +83,21 @@ test: build $(RUN_TESTS_PHP) TEST_PHP_ARGS="-n -d extension=$(EXT_PATH)" \ $(PHP) $(RUN_TESTS_PHP) -q --show-diff tests/phpt +# The committed stubs/{{STUBS_FILE}} is curated (generics, @throws, prose) +# on top of what cargo-php emits, so generation goes to target/ for a +# signature diff rather than overwriting it: +# +# make stubs && diff -u stubs/{{STUBS_FILE}} target/{{STUBS_FILE}} +# +# cargo-php dlopen()s the cdylib outside PHP. On Linux the Zend data +# symbols it references (e.g. spl_ce_RuntimeException) must resolve at +# load time, so preload PHP's embed SAPI library, e.g. +# make stubs STUBS_PRELOAD=/usr/lib/libphp8.4.so +# macOS resolves them lazily and needs nothing. +STUBS_PRELOAD ?= + stubs: check-cargo-php build - $(CARGO) php stubs --stubs stubs/{{STUBS_FILE}} + $(if $(STUBS_PRELOAD),LD_PRELOAD=$(STUBS_PRELOAD) )$(CARGO) php stubs --out target/{{STUBS_FILE}} install: check-cargo-php $(CARGO) php install --release $(CARGO_FLAGS) diff --git a/template/seed/CHANGELOG.md b/template/seed/CHANGELOG.md new file mode 100644 index 0000000..dbbe465 --- /dev/null +++ b/template/seed/CHANGELOG.md @@ -0,0 +1,8 @@ +# Changelog + +All notable changes to ext-{{NAME}} are documented here. The format is +based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and +this project adheres to [Semantic Versioning](https://semver.org/) +(pre-1.0: breaking changes bump the minor). + +## [Unreleased] diff --git a/template/seed/PLAN.md b/template/seed/PLAN.md index a526c63..6055651 100644 --- a/template/seed/PLAN.md +++ b/template/seed/PLAN.md @@ -1,20 +1,22 @@ -# ext-{{NAME}} — plan +# ext-{{NAME}} — design notes -Living document. Status / surface description lives in `README.md`; -how-to-cut-a-release lives in `RELEASE.md`. +Design notes and decision history: why the surface looks the way it +does, what was tried and rejected, and the constraints that bind future +work. It is not a to-do list. -## Status snapshot +- Status and surface: `README.md` +- What shipped, per release: `CHANGELOG.md` +- Remaining work: [`future` issues](https://github.com/DisplaceTech/ext-{{NAME}}/issues?q=is%3Aissue+is%3Aopen+label%3Afuture) + (one issue per idea, with the reasoning and any locked constraint) +- How to cut a release: `RELEASE.md` -| Surface | Status | -| --- | --- | -| Scaffold (ext-template) | rendered | +## Before building -## Releases +Propose the file tree, dependency list, and Rust-side ownership design +(umbrella CLAUDE.md ground rule 5) and get it approved before building +the surface. -| Version | Date | Notes | -| --- | --- | --- | +## Decisions -## Up next - -- [ ] Propose file tree + dependency list + Rust ownership design - (umbrella CLAUDE.md ground rule 5) before building. +| Date | Decision | Why | +| ---- | -------- | --- | diff --git a/template/seed/README.md b/template/seed/README.md index 355772b..485df13 100644 --- a/template/seed/README.md +++ b/template/seed/README.md @@ -2,6 +2,22 @@ {{DESCRIPTION}} +## Status + + + +Feature-complete for its scope. Maintained: dependency updates and +new-model support ship as patch/minor releases — see the +[CHANGELOG](CHANGELOG.md). Last verified: PHP 8.3/8.4/8.5, +` `, ``. + +Remaining ideas are tracked as +[`future` issues](https://github.com/DisplaceTech/ext-{{NAME}}/issues?q=is%3Aissue+is%3Aopen+label%3Afuture). +**Co-maintainers welcome** — if you run this in production and want a +say in where it goes, open an issue or a PR. + Scaffolded from [ext-template](https://github.com/DisplaceTech/ext-template); the files listed in its `template/managed/` tree are kept in sync with `bin/sync` — edit those upstream, not here. Everything else is this @@ -12,6 +28,23 @@ House conventions (quality bar, layout, release flow): reference. Every README in this family carries a **deliberately out of scope** section — write yours early. +## Part of a stack + +Transcribe → chunk → embed → search → answer, entirely on your hardware: + +| Stage | Package | What it does | +| ----- | ------- | ------------ | +| Transcribe | [ext-whisper](https://github.com/DisplaceTech/ext-whisper) | Speech-to-text over whisper.cpp | +| Chunk | [ai-toolkit](https://github.com/DisplaceTech/ai-toolkit) | Text chunkers and packed-vector math, pure PHP | +| Embed · rerank · answer | [ext-infer](https://github.com/DisplaceTech/ext-infer) | Local LLM chat, embeddings and reranking over llama.cpp | +| Search | [ext-turbovec](https://github.com/DisplaceTech/ext-turbovec) | Compressed in-memory vector search (TurboQuant) | +| Integrate | [ai-contracts](https://github.com/DisplaceTech/ai-contracts) | The interfaces frameworks code against | +| Reference app | [rag-over-markdown](https://github.com/DisplaceTech/rag-over-markdown) | The whole pipeline over a folder of markdown | + +## Writing about this + + + ## License MIT © Eric Mann / Displace Technologies. If release binaries statically diff --git a/template/seed/RELEASE.md b/template/seed/RELEASE.md index 780cb3a..6a1fd00 100644 --- a/template/seed/RELEASE.md +++ b/template/seed/RELEASE.md @@ -69,8 +69,10 @@ WHISPER_TEST_MODEL=$PWD/models/MODEL-FIXTURE make test # composer.json shape composer validate composer.json -# Optional: regenerate IDE stubs and diff against the committed copy -make stubs && git diff stubs/{{NAME}}.stubs.php +# Signature check: generate stubs from the build and diff against the +# curated copy (Linux: add STUBS_PRELOAD=/path/to/libphp8.x.so — see the +# Makefile). Any signature drift is a stop-and-decide. +make stubs && diff -u stubs/{{STUBS_FILE}} target/{{STUBS_FILE}} ``` If any of those fail, fix before tagging. The release workflow runs the diff --git a/template/upstream.conf b/template/upstream.conf new file mode 100644 index 0000000..9c08d6b --- /dev/null +++ b/template/upstream.conf @@ -0,0 +1,16 @@ +# Crates whose exact pins are bumped deliberately rather than by +# Dependabot. bin/upstream-check compares each pin against crates.io's +# latest stable release and opens (or updates) one ext-template issue per +# crate that has fallen behind; the issue closes itself once the pin +# catches up. +# +# +# source `versions.conf` reads the pin from template/versions.conf +# (via the KEY named in the third column); `owner/repo` reads it from +# that repo's Cargo.toml on its default branch. + +versions.conf ext-php-rs EXT_PHP_RS_PIN +versions.conf thiserror THISERROR_PIN +DisplaceTech/ext-infer llama-cpp-2 +DisplaceTech/ext-turbovec turbovec +DisplaceTech/ext-whisper whisper-rs diff --git a/template/versions.conf b/template/versions.conf index 6532027..cd4f56e 100644 --- a/template/versions.conf +++ b/template/versions.conf @@ -16,5 +16,5 @@ RUST_CHANNEL=1.89.0 RUST_VERSION=1.89 # Shared crate pins — exact (=x.y.z), upgrades are deliberate tested bumps. -EXT_PHP_RS_PIN==0.15.13 -THISERROR_PIN==2.0.18 +EXT_PHP_RS_PIN==0.16.3 +THISERROR_PIN==2.0.21