From 1ea1775bfacc9acd065dc971c9f8d5dafe4e0900 Mon Sep 17 00:00:00 2001 From: Michael Vlach Date: Fri, 17 Apr 2026 23:42:33 +0200 Subject: [PATCH 1/4] Add AGENTS.md, clean PHP openapi, update pnpm Add AGENTS.md documenting repository components, available commands and package names for Rust, TypeScript and PHP. In agdb_api/php/ci.sh, remove leftover .openapi-generator/ directory during the openapi task to clean generated artifacts. Update pnpm-workspace.yaml to remove the agdb_web_next package from the workspace packages list. --- AGENTS.md | 56 +++++++++++++++++++++++++++++++++++++++++++++ agdb_api/php/ci.sh | 1 + pnpm-workspace.yaml | 1 - 3 files changed, 57 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..c6c93d26 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,56 @@ +# AGENTS.md + +The Agnesoft Graph Database (aka agdb) is a graph database. Main components of the repository are `agdb` rust package that is the database itself. The `agdb_server` is the server version of the database itself using `agdb`. API client packages are available for Rust, TypeScript and PHP and the OpenAPI spec which is located under `agdb_server/openapi.json`. + +# Available commands + +- Rust: `cargo --all-features -r -p ` +- TypeScript: `pnpm run --filter ` +- PHP: `cd agdb_api/php/ && ./ci.sh ` +- OpenAPI & API refresh: `cargo run -r -p agdb_ci`. Only run when agdb_server/src/api.rs or agdb_server/openapi.json change. + +## Rust + +- build +- test +- clippy + +## TypeScript + +- build +- format +- test +- test:e2e +- lint + +## PHP + +- coverage +- analysis +- format + +# Available + +All packages are 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 diff --git a/agdb_api/php/ci.sh b/agdb_api/php/ci.sh index fba673d0..45eef653 100755 --- a/agdb_api/php/ci.sh +++ b/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" diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 785b5bb2..92f9d03d 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -1,7 +1,6 @@ packages: - agdb_studio/** - agdb_api/** - - agdb_web_next/** - agdb_web/** - examples/** From 787e2aeaa2caba52db55550e3f05c1d577ffde92 Mon Sep 17 00:00:00 2001 From: Michael Vlach Date: Sat, 18 Apr 2026 00:02:25 +0200 Subject: [PATCH 2/4] Update AGENTS.md --- AGENTS.md | 48 +++++++++++++++++++++++++----------------------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c6c93d26..b016d9db 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,39 +1,41 @@ # AGENTS.md -The Agnesoft Graph Database (aka agdb) is a graph database. Main components of the repository are `agdb` rust package that is the database itself. The `agdb_server` is the server version of the database itself using `agdb`. API client packages are available for Rust, TypeScript and PHP and the OpenAPI spec which is located under `agdb_server/openapi.json`. +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`. # Available commands -- Rust: `cargo --all-features -r -p ` -- TypeScript: `pnpm run --filter ` -- PHP: `cd agdb_api/php/ && ./ci.sh ` -- OpenAPI & API refresh: `cargo run -r -p agdb_ci`. Only run when agdb_server/src/api.rs or agdb_server/openapi.json change. +- 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 change. -## Rust +## Rust -- build -- test -- clippy +- Build package: `cargo build -r --all-features -p ` +- Build all: `cargo build -r --all-features` +- Format `cargo fmt` +- Test package: `cargo test -r --all-features -p ` +- Test all: `cargp test -r --all-features` +- Test debug: `cargo test --all-features -p ` +- Lint package: `cargo clippy --all-features -p ` +- Lint all: `cargo clippy --all-features` -## TypeScript +## TypeScript -- build -- format -- test -- test:e2e -- lint +- Build: `pnpm run build --filter ` +- Format: `pnpm run format --filter ` +- Test: `pnpm run test --filter ` +- Run e2e tests: `pnpm run test:e2e --filter ` +- Lint: `pnpm run lint --filter ` -## PHP +## PHP -- coverage -- analysis -- format +- Test: `cd agdb_api/php/ && ./ci.sh coverage` +- Lint: `cd agdb_api/php/ && ./ci.sh analyse` +- Format: `cd agdb_api/php/ && ./ci.sh format` -# Available +# Available packages -All packages are exact names of packages directly usable in the available commands. +The packages are curated lists of main packages. They contain exact names of packages directly usable in the available commands. -## Rust +## Rust - agdb - agdb_benchmarks @@ -48,7 +50,7 @@ All packages are exact names of packages directly usable in the available comman - examples_server_client - examples_user_types -## TypeScript +## TypeScript - agdb_studio - @agnesoft/agdb_api From 2d85669cddaf666de9c0171f6a74ced746760623 Mon Sep 17 00:00:00 2001 From: Michael Vlach Date: Sat, 18 Apr 2026 00:16:30 +0200 Subject: [PATCH 3/4] Simplify llvm-cov usage and update docs Remove strict coverage gating and filename-ignore options from CI llvm-cov invocations, switching the agdb and agdb_server workflow steps to only use --show-missing-lines. Update the coverage workflow invocation to produce lcov output via cargo llvm-cov. Also apply small editorial fixes to AGENTS.md: clarify wording, fix a typo (cargp -> cargo), adjust formatting lines, and add a note about running cargo llvm-cov for package coverage. --- .github/workflows/agdb.yaml | 2 +- .github/workflows/agdb_server.yaml | 2 +- .github/workflows/coverage.yaml | 2 +- AGENTS.md | 9 +++++---- 4 files changed, 8 insertions(+), 7 deletions(-) diff --git a/.github/workflows/agdb.yaml b/.github/workflows/agdb.yaml index d38e629a..fe9828f6 100644 --- a/.github/workflows/agdb.yaml +++ b/.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: diff --git a/.github/workflows/agdb_server.yaml b/.github/workflows/agdb_server.yaml index 8e8f9e80..c8cff7ac 100644 --- a/.github/workflows/agdb_server.yaml +++ b/.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 diff --git a/.github/workflows/coverage.yaml b/.github/workflows/coverage.yaml index 308f2acf..4b245694 100644 --- a/.github/workflows/coverage.yaml +++ b/.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 diff --git a/AGENTS.md b/AGENTS.md index b016d9db..0f763dbd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,15 +4,16 @@ The Agnesoft Graph Database (aka agdb) is a graph database. The main components # 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 change. +- 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 ` - Build all: `cargo build -r --all-features` -- Format `cargo fmt` +- Format: `cargo fmt` - Test package: `cargo test -r --all-features -p ` -- Test all: `cargp test -r --all-features` +- Test package with coverage: `cargo llvm-cov -p --show-missing-lines` +- Test all: `cargo test -r --all-features` - Test debug: `cargo test --all-features -p ` - Lint package: `cargo clippy --all-features -p ` - Lint all: `cargo clippy --all-features` @@ -27,7 +28,7 @@ The Agnesoft Graph Database (aka agdb) is a graph database. The main components ## PHP -- Test: `cd agdb_api/php/ && ./ci.sh coverage` +- 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` From e2915367b78f1af71344a3c2213260e2bd83e968 Mon Sep 17 00:00:00 2001 From: Michael Vlach Date: Sat, 18 Apr 2026 00:36:24 +0200 Subject: [PATCH 4/4] Add PHP Composer setup skill and update AGENTS.md Add a new .github/skills/php-composer-setup/SKILL.md that documents installing and verifying PHP and Composer across Windows, Linux, and macOS, outlines verification and repository check commands (for agdb_api/php), and provides usage examples. Update AGENTS.md to include a Setup section with installation hints for Rust, pnpm, PHP/Composer (referencing the new skill), and Playwright, and add TypeScript dependency install/update commands. --- .github/skills/php-composer-setup/SKILL.md | 124 +++++++++++++++++++++ AGENTS.md | 9 ++ 2 files changed, 133 insertions(+) create mode 100644 .github/skills/php-composer-setup/SKILL.md diff --git a/.github/skills/php-composer-setup/SKILL.md b/.github/skills/php-composer-setup/SKILL.md new file mode 100644 index 00000000..3760d931 --- /dev/null +++ b/.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` diff --git a/AGENTS.md b/AGENTS.md index 0f763dbd..237a7aa0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,13 @@ 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. @@ -20,6 +27,8 @@ The Agnesoft Graph Database (aka agdb) is a graph database. The main components ## TypeScript +- Install dependencies: `pnpm i --frozen-lockfile` +- Update dependencies: `pnpm i` - Build: `pnpm run build --filter ` - Format: `pnpm run format --filter ` - Test: `pnpm run test --filter `