[ci] Add AGENTS.md, PHP AI skill and remove coverage guards #1767

.github/skills/php-composer-setup/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: php-composer-setup
+description: Install PHP and Composer, verify they are available in PATH, and confirm the PHP tooling required by this repository works. Use this when PHP or Composer are missing, or when commands under agdb_api/php fail because the environment is not set up.
+argument-hint: "[windows|linux|macos] [optional package manager or version]"
+disable-model-invocation: true
+---
+
+# PHP and Composer Setup
+
+Use this skill when the workspace needs PHP and Composer installed or verified before running commands in `agdb_api/php`.
+
+Repository context:
+
+- The PHP API client lives in `agdb_api/php`.
+- Common PHP validation commands in this repository are:
+  - `cd agdb_api/php/ && ./ci.sh coverage`
+  - `cd agdb_api/php/ && ./ci.sh analyse`
+  - `cd agdb_api/php/ && ./ci.sh format`
+
+## Goals
+
+1. Detect whether PHP and Composer are already installed.
+2. Install missing tools using the most appropriate package manager for the current OS.
+3. Verify that both tools are available in `PATH`.
+4. Confirm that the repository's PHP tooling can run.
+
+## General procedure
+
+1. Detect the operating system and check whether `php` and `composer` are already available.
+2. Prefer the native package manager for the OS.
+3. Do not reinstall tools that are already working unless the user explicitly asks for a version change.
+4. If installation updates `PATH`, tell the user a new terminal might be required and re-run verification.
+5. After installation, verify both binaries before attempting repository commands.
+6. If a command requires elevated privileges, explain that clearly before running it.
+
+## Verification commands
+
+Run these first:
+
+- `php --version`
+- `composer --version`
+
+If both succeed, move directly to repository verification.
+
+## Windows
+
+Preferred package manager order:
+
+1. `winget`
+2. `choco`
+
+Suggested commands:
+
+- Check for `winget`: `winget --version`
+- Install PHP with winget: `winget install --id PHP.PHP.8.4 --source winget`
+- Install Composer with winget: `winget install --id Composer.Composer --source winget`
+- Install PHP with Chocolatey: `choco install php`
+- Install Composer with Chocolatey: `choco install composer`
+
+If the exact winget package ID changes, search for it with:
+
+- `winget search php`
+- `winget search composer`
+
+After installation, re-run:
+
+- `php --version`
+- `composer --version`
+
+If the current shell still does not see the binaries, open a new terminal and verify again.
+
+## Linux
+
+Prefer the system package manager. Typical commands include:
+
+- Debian or Ubuntu: `sudo apt update && sudo apt install -y php-cli composer`
+- Fedora: `sudo dnf install -y php-cli composer`
+- Arch: `sudo pacman -Sy php composer`
+
+After installation, re-run:
+
+- `php --version`
+- `composer --version`
+
+## macOS
+
+Prefer Homebrew if available:
+
+- Check for Homebrew: `brew --version`
+- Install PHP: `brew install php`
+- Install Composer: `brew install composer`
+
+After installation, re-run:
+
+- `php --version`
+- `composer --version`
+
+## Repository verification
+
+Once PHP and Composer are available, verify the repository setup with the least expensive relevant command first.
+
+Recommended order:
+
+1. `cd agdb_api/php/ && ./ci.sh format`
+2. `cd agdb_api/php/ && ./ci.sh analyse`
+3. `cd agdb_api/php/ && ./ci.sh coverage`
+
+Choose the command that best matches the user's goal. If the user only asked for installation, stop after binary verification unless they want a repo-level check.
+
+## Operating rules
+
+- Prefer detection before installation.
+- Prefer non-destructive verification before long-running checks.
+- Report exact installation blockers instead of guessing.
+- If package installation is not possible in the current environment, tell the user what command they need to run locally.
+- When verification fails, distinguish between missing system tools and repository-level PHP dependency problems.
+
+## Example invocations
+
+- `/php-composer-setup windows`
+- `/php-composer-setup windows using winget`
+- `/php-composer-setup verify php tooling for agdb_api/php`
+- `/php-composer-setup linux`
+- `/php-composer-setup macos with Homebrew`

.github/workflows/agdb.yaml

@@ -20,7 +20,7 @@ jobs:
       - run: cargo clippy -p agdb --all-targets --all-features -- -D warnings
       - uses: taiki-e/install-action@cargo-llvm-cov
       - run: rustup component add llvm-tools-preview
-      - run: cargo llvm-cov -p agdb --all-features --ignore-filename-regex "agdb_derive" --fail-uncovered-functions 99 --fail-uncovered-lines 500 --show-missing-lines
+      - run: cargo llvm-cov -p agdb --all-features --show-missing-lines
 
   # merge with the main job once --doctests is stabilized: https://github.com/taiki-e/cargo-llvm-cov/issues/2
   agdb_doctests:

.github/workflows/agdb_server.yaml

@@ -23,7 +23,7 @@ jobs:
       - run: cargo clippy -p agdb_server -p agdb_api --all-targets --all-features -- -D warnings
       - uses: taiki-e/install-action@cargo-llvm-cov
       - run: rustup component add llvm-tools-preview
-      - run: cargo llvm-cov -p agdb_server -p agdb_api --all-features --ignore-filename-regex "agdb(.|..)src|agdb_derive" --fail-uncovered-functions 63 --fail-uncovered-lines 282 --show-missing-lines
+      - run: cargo llvm-cov -p agdb_server -p agdb_api --show-missing-lines
 
   agdb_server_image:
     runs-on: ubuntu-latest

.github/workflows/coverage.yaml

@@ -27,7 +27,7 @@ jobs:
       - uses: taiki-e/install-action@cargo-llvm-cov
       - run: rustup component add llvm-tools-preview
       - run: npm i -g pnpm
-      - run: cargo llvm-cov -p agdb -p agdb_api -p agdb_server --all-features --ignore-filename-regex "agdb(_derive|_benchmarks)|api.rs" --lcov --output-path lcov.info
+      - run: cargo llvm-cov -p agdb -p agdb_api -p agdb_server --all-features--lcov --output-path lcov.info
       - run: pnpm i --frozen-lockfile
       - run: pnpm run test
       - run: composer config --global use-parent-dir true

AGENTS.md

@@ -0,0 +1,68 @@
+# AGENTS.md
+
+The Agnesoft Graph Database (aka agdb) is a graph database. The main components of this repository are `agdb` (rust package) that is the database itself. The `agdb_server` (rust package) is the server version of the database. API client packages are available for Rust, TypeScript, and PHP. The OpenAPI specification is located at `agdb_server/openapi.json`.
+
+# Setup
+
+- Install Rust: `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`
+- Install pnpm: `npm i -g pnpm`. This assumes `npm` is installed & available.
+- Install PHP and Composer. Only needed for PHP API client. Use the `php-composer-setup` skill in `.github/skills/php-composer-setup/SKILL.md`.
+- Install playwright: `pnpm exec playwright install`. Only for TypeScript e2e tests.
+
+# Available commands
+
+- OpenAPI, API refresh and version bump: `cargo run -r -p agdb_ci`. Run when agdb_server/src/api.rs, agdb_server/openapi.json or Version file changes.
+
+## Rust
+
+- Build package: `cargo build -r --all-features -p <package>`
+- Build all: `cargo build -r --all-features`
+- Format: `cargo fmt`
+- Test package: `cargo test -r --all-features -p <package>`
+- Test package with coverage: `cargo llvm-cov -p <package> --show-missing-lines`
+- Test all: `cargo test -r --all-features`
+- Test debug: `cargo test --all-features -p <package>`
+- Lint package: `cargo clippy --all-features -p <package>`
+- Lint all: `cargo clippy --all-features`
+
+## TypeScript
+
+- Install dependencies: `pnpm i --frozen-lockfile`
+- Update dependencies: `pnpm i`
+- Build: `pnpm run build --filter <package>`
+- Format: `pnpm run format --filter <package>`
+- Test: `pnpm run test --filter <package>`
+- Run e2e tests: `pnpm run test:e2e --filter <package>`
+- Lint: `pnpm run lint --filter <package>`
+
+## PHP
+
+- Test with coverage: `cd agdb_api/php/ && ./ci.sh coverage`
+- Lint: `cd agdb_api/php/ && ./ci.sh analyse`
+- Format: `cd agdb_api/php/ && ./ci.sh format`
+
+# Available packages
+
+The packages are curated lists of main packages. They contain exact names of packages directly usable in the available commands.
+
+## Rust
+
+- agdb
+- agdb_benchmarks
+- agdb_ci
+- agdb_derive
+- agdb_server
+- agdb_api
+- examples_app_db
+- examples_indexes
+- examples_joins
+- examples_schema_migration
+- examples_server_client
+- examples_user_types
+
+## TypeScript
+
+- agdb_studio
+- @agnesoft/agdb_api
+- agdb_web
+- examples_server_client

agdb_api/php/ci.sh

@@ -61,6 +61,7 @@ function format() {
 function openapi() {
     rm -rf lib/
     rm -rf docs/
+    rm -rf .openapi-generator/
 
     echo "OSTYPE: $OSTYPE"
 

pnpm-workspace.yaml

@@ -1,7 +1,6 @@
 packages:
   - agdb_studio/**
   - agdb_api/**
-  - agdb_web_next/**
   - agdb_web/**
   - examples/**