diff --git a/.agents/skills/php-forge-debug b/.agents/skills/php-forge-debug
new file mode 120000
index 0000000..1feab5f
--- /dev/null
+++ b/.agents/skills/php-forge-debug
@@ -0,0 +1 @@
+../../skills/php-forge-debug
\ No newline at end of file
diff --git a/.claude/skills/php-forge-debug b/.claude/skills/php-forge-debug
new file mode 120000
index 0000000..1feab5f
--- /dev/null
+++ b/.claude/skills/php-forge-debug
@@ -0,0 +1 @@
+../../skills/php-forge-debug
\ No newline at end of file
diff --git a/.gitattributes b/.gitattributes
index 2360366..65346ef 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -22,21 +22,41 @@
*.ttf binary
# Exclude files from the archive
+.agents export-ignore
+.claude export-ignore
+.env export-ignore
+.env.* export-ignore
+.env.example export-ignore
+/.codex export-ignore
+/.config export-ignore
/.editorconfig export-ignore
/.gitattributes export-ignore
/.github export-ignore
/.gitignore export-ignore
+/.nvmrc export-ignore
+/.phpunit.cache export-ignore
+/.prettierignore export-ignore
+/.prettierrc.json export-ignore
+/.stryker-tmp export-ignore
/.styleci.yml export-ignore
+/.vscode export-ignore
+/artifacts export-ignore
+/code_coverage export-ignore
/codeception.yml export-ignore
/composer-require-checker.json export-ignore
+/composer.lock export-ignore
/docs export-ignore
/ecs.php export-ignore
/infection.json* export-ignore
+/internal export-ignore
+/node_modules export-ignore
/phpstan*.neon* export-ignore
/phpunit.xml.dist export-ignore
/rector.php export-ignore
+/reports export-ignore
/runtime export-ignore
/tests export-ignore
+/vendor export-ignore
# Avoid merge conflicts in CHANGELOG
# https://about.gitlab.com/2015/02/10/gitlab-reduced-merge-conflicts-by-90-percent-with-changelog-placeholders/
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index f39234e..f62f871 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -17,7 +17,7 @@ permissions:
jobs:
phpunit:
- uses: php-forge/actions/.github/workflows/phpunit.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0
+ uses: php-forge/actions/.github/workflows/phpunit.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2
with:
php-version: '["8.3","8.4","8.5"]'
secrets:
diff --git a/.github/workflows/dependency-check.yml b/.github/workflows/dependency-check.yml
index 543f666..75d0bc0 100644
--- a/.github/workflows/dependency-check.yml
+++ b/.github/workflows/dependency-check.yml
@@ -17,4 +17,4 @@ permissions:
jobs:
composer-require-checker:
- uses: php-forge/actions/.github/workflows/composer-require-checker.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0
+ uses: php-forge/actions/.github/workflows/composer-require-checker.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2
diff --git a/.github/workflows/ecs.yml b/.github/workflows/ecs.yml
index a446051..a2a78fd 100644
--- a/.github/workflows/ecs.yml
+++ b/.github/workflows/ecs.yml
@@ -17,4 +17,4 @@ permissions:
jobs:
easy-coding-standard:
- uses: php-forge/actions/.github/workflows/ecs.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0
+ uses: php-forge/actions/.github/workflows/ecs.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2
diff --git a/.github/workflows/mutation.yml b/.github/workflows/mutation.yml
index ee275be..1ca945f 100644
--- a/.github/workflows/mutation.yml
+++ b/.github/workflows/mutation.yml
@@ -17,7 +17,7 @@ permissions:
jobs:
mutation:
- uses: php-forge/actions/.github/workflows/infection.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0
+ uses: php-forge/actions/.github/workflows/infection.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2
with:
phpstan: true
secrets:
diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml
index 765cdfc..46cb8d5 100644
--- a/.github/workflows/quality.yml
+++ b/.github/workflows/quality.yml
@@ -10,7 +10,7 @@ permissions:
jobs:
quality:
- uses: php-forge/actions/.github/workflows/quality.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0
+ uses: php-forge/actions/.github/workflows/quality.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2
permissions:
contents: read
with:
diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml
new file mode 100644
index 0000000..0640a44
--- /dev/null
+++ b/.github/workflows/scorecard.yml
@@ -0,0 +1,23 @@
+---
+on:
+ branch_protection_rule:
+ push:
+ branches:
+ - main
+ schedule:
+ - cron: "30 1 * * 6"
+
+name: scorecard
+
+permissions:
+ contents: read
+
+jobs:
+ scorecard:
+ uses: php-forge/actions/.github/workflows/scorecard.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2
+ permissions:
+ contents: read # Required to check out the repository.
+ id-token: write # Required to sign published results with the GitHub OIDC token.
+ security-events: write # Required to upload SARIF results to code scanning.
+ with:
+ publish-results: true
diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml
index b3b632c..29b8119 100644
--- a/.github/workflows/security.yml
+++ b/.github/workflows/security.yml
@@ -10,7 +10,7 @@ permissions:
jobs:
security:
- uses: php-forge/actions/.github/workflows/security.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0
+ uses: php-forge/actions/.github/workflows/security.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2
permissions:
contents: read
with:
diff --git a/.github/workflows/static.yml b/.github/workflows/static.yml
index 97bd4cf..455657f 100644
--- a/.github/workflows/static.yml
+++ b/.github/workflows/static.yml
@@ -17,4 +17,4 @@ permissions:
jobs:
phpstan:
- uses: php-forge/actions/.github/workflows/phpstan.yml@a574dbe95fc370db1b7b5ea546cd5ff5b70304d6 # v3.0.0
+ uses: php-forge/actions/.github/workflows/phpstan.yml@4aaec87a6fdc921e51a554912ceb07dacf18916f # v3.0.2
diff --git a/.gitignore b/.gitignore
index a2389e2..8e270f3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,8 @@
-# AI agents (if present)
-.codex
-.claude
+# agents (if present)
+.agents
+
+# artifacts (if present)
+artifacts
# codecoverage (if present)
code_coverage
@@ -11,11 +13,7 @@ c3.php
# composer
composer.lock
-# local notes and scaffold drafts (if present)
-examples/
-internal/
-
-# gitHub copilot config (if present)
+# GitHub Copilot config (if present)
.github/agents/**
.github/copilot-instructions.md
.github/copilot/**
@@ -23,6 +21,16 @@ internal/
.github/prompts/**
.github/skills/**
+# Local AI agent, editor, and GitHub CLI config (if present)
+.claude
+.codex
+.config/gh
+
+# Local environment files
+.env
+.env.*
+!.env.example
+
# mac ds_store (if present)
.DS_Store
@@ -31,19 +39,26 @@ nbproject
# node_modules (if present)
node_modules
-package-lock.json
-!src/assets/package-lock.json
-
-# phpactor (if present)
-.phpactor.*
# phpstorm project (if present)
.idea
+# phpactor (if present)
+.phpactor.*
+
# phpunit (if present)
.phpunit.cache
.phpunit.result.cache
+# private maintainer files (if present)
+/internal/
+
+# report (if present)
+reports
+
+# stryker (if present)
+.stryker-tmp
+
# vagrant (if present)
.vagrant
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a74c436..56cfba6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## 0.4.2 Under development
+- docs: add the `php-forge-debug` skill with AI assistance guidance; add Security and Built with AI sections; update `README.md` badges.
+
## 0.4.1 September 26, 2026
- feat(panel-view): add `hero()` for `HeroBlock`, the header naming the subject a panel describes with its status badge and metric row; update `README.md`.
diff --git a/README.md b/README.md
index c922b11..d9075d3 100644
--- a/README.md
+++ b/README.md
@@ -12,15 +12,15 @@
+
+
+
-
-
-
@@ -281,7 +281,20 @@ $html = match (true) { ## Documentation -- [Testing guide](docs/testing.md) +- 🧪 [Testing guide](https://github.com/php-forge/debug/blob/main/docs/testing.md) + +## AI assistance + +AI agents: read the [documentation index](https://yii2-framework.github.io/docs/llms.txt) and fetch the Markdown version +of a page by appending `index.md` to its URL. The +[AI agents guide](https://github.com/yii2-framework/docs/blob/main/src/content/docs/project/ai-agents.md) covers skill +installation, client setup and verification. + +- 🤖 [`php-forge-debug` skill](https://github.com/php-forge/debug/blob/main/docs/agents.md): portable collectors, + declarative panels built with `PanelView`, and the presentation value objects a host renders. + +See the [repository guides](#documentation), the [skill source](skills/php-forge-debug/SKILL.md), the source PHPDoc and +the [changelog](CHANGELOG.md). ## Package information @@ -292,9 +305,19 @@ $html = match (true) { ## Code quality -[](https://codecov.io/gh/php-forge/debug) [](https://github.com/php-forge/debug/actions/workflows/quality.yml) -[](https://github.styleci.io/repos/php-forge/debug?branch=main) +[](https://github.styleci.io/repos/1363905740?branch=main) + +## Security + +[](https://scorecard.dev/viewer/?uri=github.com/php-forge/debug) +[](https://github.com/php-forge/debug/actions/workflows/security.yml) + +## Built with AI + +[](https://claude.com/claude-code) +[](https://openai.com/codex) +[](https://www.coderabbit.ai) ## Social networks diff --git a/composer.json b/composer.json index ed9b75b..5871eb5 100644 --- a/composer.json +++ b/composer.json @@ -37,6 +37,9 @@ "extra": { "branch-alias": { "dev-main": "0.5.x-dev" + }, + "skills": { + "source": "skills" } }, "config": { @@ -50,7 +53,7 @@ "check-dependencies": "./vendor/bin/composer-require-checker check", "ecs": "./vendor/bin/ecs --fix", "mutation": "./vendor/bin/infection --threads=4 --ignore-msi-with-no-mutations --min-msi=100 --min-covered-msi=100", - "mutation-static": "./vendor/bin/infection --threads=4 --ignore-msi-with-no-mutations --min-msi=100 --min-covered-msi=100 --static-analysis-tool=phpstan --static-analysis-tool-options='--memory-limit=-1'", + "mutation-static": "php -d memory_limit=-1 ./vendor/bin/infection --initial-tests-php-options='-d memory_limit=-1' --test-framework-extra-args='-d memory_limit=-1' --threads=4 --ignore-msi-with-no-mutations --min-msi=100 --min-covered-msi=100 --static-analysis-tool=phpstan --static-analysis-tool-options='--memory-limit=-1'", "rector": "./vendor/bin/rector process", "static": "./vendor/bin/phpstan --memory-limit=-1", "tests": "./vendor/bin/phpunit" diff --git a/docs/agents.md b/docs/agents.md new file mode 100644 index 0000000..fc149d4 --- /dev/null +++ b/docs/agents.md @@ -0,0 +1,61 @@ +# AI assistance + +Use the package-owned [php-forge-debug](../skills/php-forge-debug/SKILL.md) skill for implementing PHP Forge portable diagnostic collectors and declarative panels. The canonical source is `skills/`; checkout discovery links in `.agents/skills/` and `.claude/skills/` point to that same source. + +## Install in an application + +### Automatic Composer installation + +Composer is the primary distribution path. `extra.skills.source` declares the bundle; installing the package alone does +not register its skill at the application root. In a consumer already configured for `llm/skills`, explicitly trust +`php-forge/debug` and use that installed synchronizer's documented setup. Do not enable plugins or broaden trust by +copying an example. With verified auto-sync enabled, installation/update can synchronize the bundle: + +```bash +composer install +composer skills:show +``` + +Otherwise run `composer skills:update` explicitly and inspect `composer skills:show`. Composer exit zero is not proof +of client activation. + +### Optional npx installation + +An optional pinned installer can use a local checkout or an installed package that contains the bundle: + +```bash +npx skills@1.7.2 add /absolute/path/to/debug --list +npx skills@1.7.2 add /absolute/path/to/debug --skill php-forge-debug --agent claude-code codex opencode +``` + +Keep project scope. Inspect a remote source with `--list` before claiming an unpublished skill is available there. +Copied installations must be refreshed after upgrades. The complete skill directory is the unit of installation. + +## Discover and invoke + +Open a fresh client session at the checkout or consumer root. Codex discovers `.agents/skills/php-forge-debug/` and supports +`$php-forge-debug` or its skill picker. Claude Code uses `.claude/skills/php-forge-debug/` and `/php-forge-debug`. For OpenCode, verify the +installed client's native skill tool and shared paths. Do not assume one client's invocation syntax works in another. + +## Example prompts + +Explicit Codex invocation: + +```text +$php-forge-debug +Implement a minimal collector and matching panel using the installed contracts. Verify null versus empty capture and that startup/shutdown prevent one request from leaking into the next. +``` + +For natural selection, repeat the task without the first line. Record whether the client loads this skill rather than +a global same-named copy. As an unrelated negative control, ask it to explain HTTP 301 versus 302 without inspecting the +repository or loading package skills. + +## Verify the result + +Capture the native load/tool evidence and selected source path, then execute the generated task checks against the +installed package. Cover the normal operation, the described boundary case and a failure/unsupported input. Inspect +generated code before executing it; use disposable fixtures for writes. Run the package's actual non-mutating checks +and report runtime versions, warnings and unavailable dependencies. Listing, manually reading the skill, or supplying +its body in a prompt does not prove native activation or functional execution. + +[Back to README](../README.md) diff --git a/skills/php-forge-debug/SKILL.md b/skills/php-forge-debug/SKILL.md new file mode 100644 index 0000000..01dff6a --- /dev/null +++ b/skills/php-forge-debug/SKILL.md @@ -0,0 +1,47 @@ +--- +name: php-forge-debug +description: Implement portable diagnostic collectors and declarative panels with the php-forge/debug contracts (CollectorInterface, Panel, PanelView and the Presenter value objects). Use when writing or reviewing a collector or panel that a host such as php-forge/debug-core renders. Not for the debugger engine, host wiring, storage, toolbar rendering or frontend code, which live in the host packages. +license: BSD-3-Clause +--- + +# Use php-forge/debug + +## Resolve the package + +The package requires PHP 8.3 or later. Choose APIs from the installed source: the Composer archive excludes `docs/`, so +in `vendor/php-forge/debug` the PHPDoc in `src/` is the reference for the installed version. A lockfile or branch alias +alone does not prove which files are installed. Installing this skill does not install dependencies or authorize +mutations. + +## Package contracts + +This package supplies contracts and presentation models, not a debugger engine or automatic activation. +`CollectorInterface` coordinates `startup()`, `capture()`, `shutdown()` and a stable `id()`. A null capture means absence; +an empty array remains a capture. The host validates JSON serializability before persistence, and nested values must +survive strict JSON encoding within 500 levels. Providers must omit secrets before returning data. + +Read `Panel`, `PanelView` and the selected `Presenter` value objects before constructing a panel. Keep the collector +and panel identifiers aligned. Test repeated request lifecycles and released state. Debugger integrations are for local +development, not production; installing these contracts does not make an application safe to expose diagnostics. + +Intended behavior that can look like a defect: + +- `Panel::id()`, `name()` and `icon()` are final and throw `InvalidArgumentException` when the `ID`, `TITLE` or `ICON` + constant is empty. Declare the constants; do not override the accessors. The host may override the title and icon. +- `Panel::present()` builds the view from the stored capture only. Do not query live services or the container there. +- `PanelView` is a `final readonly` class created with `PanelView::create()`. Every content method returns a new view, + so discarding the return value loses the block. +- Inline content accepts scalars, `null` and `Presenter\Inline` values. `null`, `true` and `false` render as the text + `null`, `true` and `false`; arrays and objects are rejected with `InvalidArgumentException`. Use `PanelView::value()` + to display structured data. +- Table rows must be lists whose width matches the headers; a keyed or short row is rejected. +- `PanelView::link()` accepts only relative targets and the `http`, `https` and `mailto` schemes, and rejects targets + with control characters or surrounding spaces. This blocks executable targets built from captured values; do not + relax it. + +## Verify the task + +Run the relevant existing package checks and independent assertions for the selected operation. In this package's +checkout, `composer tests`, `composer static` and `composer check-dependencies` only read; `composer ecs` and +`composer rector` rewrite files. Use isolated synthetic inputs for side-effecting behavior. Report the PHP version and +missing dependencies. diff --git a/skills/php-forge-debug/agents/openai.yaml b/skills/php-forge-debug/agents/openai.yaml new file mode 100644 index 0000000..f5b6d58 --- /dev/null +++ b/skills/php-forge-debug/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "PHP Forge Debug" + short_description: "Build portable debug collectors and panels" + default_prompt: "Use $php-forge-debug to implement a collector and its matching declarative panel."