150 lines
7.1 KiB
PHP
150 lines
7.1 KiB
PHP
<?php
|
|
// docs/ai-capabilities.md: everything an AI (Claude Code, OpenCode, the IDE's assistant) has at hand in a JumPHP project,
|
|
// generated from the sources so it never goes stale: bin/jumphp php . tools/ai-capabilities.php > docs/ai-capabilities.md
|
|
// - the MCP servers and every tool they give (the IDE's, the debugger's, the notifications', the playground's)
|
|
// - the engine extensions (extensions/*/composer.json)
|
|
// - every public class of the engine (engine/src), with the first line of its documentation
|
|
// - the commands of bin/jumphp (its help)
|
|
|
|
$root = dirname(__DIR__);
|
|
chdir($root);
|
|
|
|
/** the first sentence of a docblock */
|
|
function firstLine(string $doc): string
|
|
{
|
|
$text = trim((string)preg_replace(['#^/\*\*|\*/$#', '#^\s*\* ?#m'], '', $doc));
|
|
$text = (string)preg_replace('/\s+/', ' ', explode("\n\n", $text)[0]);
|
|
$text = (string)preg_replace('/@\w+.*$/', '', $text);
|
|
if (preg_match('/^(.{20,}?[.:])(\s|$)/u', $text, $m)) {
|
|
$text = $m[1];
|
|
}
|
|
return mb_strimwidth(trim($text), 0, 220, '…');
|
|
}
|
|
|
|
function short(string $description): string
|
|
{
|
|
$d = (string)preg_replace('/\s+/', ' ', $description);
|
|
return preg_match('/^(.{30,}?\.)(\s|$)/u', $d, $m) ? $m[1] : mb_strimwidth($d, 0, 220, '…');
|
|
}
|
|
|
|
$out = [];
|
|
$out[] = '# What an AI has at hand in a JumPHP project';
|
|
$out[] = '';
|
|
$out[] = '<!-- Generated by tools/ai-capabilities.php (bin/jumphp php . tools/ai-capabilities.php > docs/ai-capabilities.md): do not edit by hand. -->';
|
|
$out[] = '';
|
|
$out[] = 'AGENTS.md is the contract (how to make a game, the rules). This page is the inventory: every tool an AI can call, every';
|
|
$out[] = 'engine extension, every class of the engine and every command, so nothing that exists is written again. Read the part you';
|
|
$out[] = 'need; the sources and docs/ say the details.';
|
|
$out[] = '';
|
|
|
|
// 1. MCP servers ------------------------------------------------------------------------------------------------------
|
|
$out[] = '## 1. MCP servers and their tools';
|
|
$out[] = '';
|
|
$out[] = '| Server | How it is connected | What for |';
|
|
$out[] = '|---|---|---|';
|
|
$out[] = '| `jumphp-ide` | automatically, for the Claude / OpenCode of the JumPHP IDE | drive the IDE: files, runs, debugger, profiler, Cryo, A/B tests, terminal |';
|
|
$out[] = '| `jumphp-debug` | `claude mcp add jumphp-debug -- bin/jumphp debug` | the step debugger from a terminal\'s Claude Code |';
|
|
$out[] = '| `jumphp-notify` | `claude mcp add jumphp-notify -- bin/jumphp notify:mcp` | push notifications of an application (the owner\'s token) |';
|
|
$out[] = '| `jumphp` | `claude mcp add --transport http --scope user jumphp https://jumphp.net/mcp --header "Authorization: Bearer jph_…"` | the playground: projects, publishing, tests, private files, notes, todos |';
|
|
$out[] = '| plugins | IDE plugins add tools (`mcp__jumphp-ide__plugin_<id>_<name>`) | see docs/ide-plugins.md |';
|
|
$out[] = '';
|
|
|
|
$out[] = '### jumphp-ide (the IDE)';
|
|
$out[] = '';
|
|
require $root . '/games/ide/vendor/autoload.php';
|
|
if (class_exists(\JumPHP\Ide\Agent\AgentTools::class)) {
|
|
foreach (\JumPHP\Ide\Agent\AgentTools::all() as $tool) {
|
|
$out[] = '- `' . $tool['name'] . '`: ' . short($tool['description']);
|
|
}
|
|
} else {
|
|
$out[] = '(run `bin/jumphp install ide` to list them)';
|
|
}
|
|
$out[] = '';
|
|
|
|
$out[] = '### jumphp-debug (bin/jumphp debug)';
|
|
$out[] = '';
|
|
$debug = (string)@file_get_contents('tools/debug-mcp.php');
|
|
preg_match_all("/^ '([a-z_]+)' => \['((?:[^'\\\\]|\\\\.)*)'/m", $debug, $m, PREG_SET_ORDER);
|
|
foreach ($m as $tool) {
|
|
$out[] = '- `' . $tool[1] . '`: ' . short(stripslashes($tool[2]));
|
|
}
|
|
$out[] = '';
|
|
|
|
$out[] = '### jumphp-notify (bin/jumphp notify:mcp)';
|
|
$out[] = '';
|
|
$notify = (string)@file_get_contents('extensions/notification/src/Tools/McpServer.php');
|
|
preg_match_all("/\\\$tool\('([a-z_]+)', '((?:[^'\\\\]|\\\\.)*)'/", $notify, $m, PREG_SET_ORDER);
|
|
foreach ($m as $tool) {
|
|
$out[] = '- `' . $tool[1] . '`: ' . short(stripslashes($tool[2]));
|
|
}
|
|
$out[] = '';
|
|
|
|
$out[] = '### jumphp (the playground, https://jumphp.net/mcp)';
|
|
$out[] = '';
|
|
$out[] = 'whoami, list_categories, list_projects, create_project, get_project, update_project, sync_project, import_project,';
|
|
$out[] = 'list_private_files, upload_private_files, remove_private_files, list_games, list_game_files, read_game_file, run_tests,';
|
|
$out[] = 'get_test_run, get_notes, save_note, delete_note, list_todos, add_todos, update_todos, list_feedback, moderate_feedback,';
|
|
$out[] = 'list_crash_reports, get_crash_report, delete_crash_report, notify_send, notify_stats, notify_history (AGENTS.md section 14).';
|
|
$out[] = '';
|
|
|
|
// 2. extensions -------------------------------------------------------------------------------------------------------
|
|
$out[] = '## 2. Engine extensions (Composer packages, `bin/jumphp extension:add <game> jumphp/<id>`)';
|
|
$out[] = '';
|
|
foreach (glob('extensions/*/composer.json') ?: [] as $file) {
|
|
$json = json_decode((string)file_get_contents($file), true) ?: [];
|
|
$extra = $json['extra']['jumphp'] ?? [];
|
|
$id = basename(dirname($file));
|
|
$line = '- **' . ($json['name'] ?? "jumphp/$id") . '** (`extensions/' . $id . '`): ' . ($extra['summary'] ?? $json['description'] ?? '');
|
|
if (!empty($extra['services'])) {
|
|
$line .= ' Services: `' . implode('`, `', $extra['services']) . '`.';
|
|
}
|
|
if (is_dir("games/$id-demo")) {
|
|
$line .= " Example game: `games/$id-demo`.";
|
|
}
|
|
$out[] = $line;
|
|
foreach (array_slice((array)($extra['features'] ?? []), 0, 8) as $feature) {
|
|
$out[] = ' - ' . (is_array($feature) ? ($feature['title'] ?? json_encode($feature)) : $feature);
|
|
}
|
|
}
|
|
$out[] = '';
|
|
|
|
// 3. engine classes ---------------------------------------------------------------------------------------------------
|
|
$out[] = '## 3. The engine, class by class (`engine/src`, namespace `JumPHP\\`)';
|
|
$out[] = '';
|
|
$byDir = [];
|
|
$it = new RecursiveIteratorIterator(new RecursiveDirectoryIterator('engine/src', FilesystemIterator::SKIP_DOTS));
|
|
foreach ($it as $f) {
|
|
if ($f->getExtension() !== 'php') {
|
|
continue;
|
|
}
|
|
$code = (string)file_get_contents($f->getPathname());
|
|
if (!preg_match('/^(?:(\/\*\*(?:(?!\*\/).)*\*\/)\s*)?(?:#\[[^\]]*\]\s*)*(?:final |abstract |readonly )*(class|interface|trait|enum) (\w+)/ms', $code, $m)) {
|
|
continue;
|
|
}
|
|
$rel = substr($f->getPathname(), strlen('engine/src/'));
|
|
$dir = str_contains($rel, '/') ? dirname($rel) : '(root)';
|
|
$byDir[$dir][] = [$m[2], $m[3], $m[1] !== '' ? firstLine($m[1]) : ''];
|
|
}
|
|
ksort($byDir);
|
|
foreach ($byDir as $dir => $classes) {
|
|
$out[] = "### $dir";
|
|
$out[] = '';
|
|
usort($classes, fn ($a, $b) => strcmp($a[1], $b[1]));
|
|
foreach ($classes as [$kind, $name, $doc]) {
|
|
$out[] = '- `' . $name . '`' . ($kind !== 'class' ? " ($kind)" : '') . ($doc !== '' ? ': ' . $doc : '');
|
|
}
|
|
$out[] = '';
|
|
}
|
|
|
|
// 4. commands ---------------------------------------------------------------------------------------------------------
|
|
$out[] = '## 4. bin/jumphp commands';
|
|
$out[] = '';
|
|
$bin = (string)file_get_contents('bin/jumphp');
|
|
if (preg_match("/usage\(\) \{\n cat <<'EOF'\n(.*?)\nEOF/s", $bin, $m)) {
|
|
$out[] = '```';
|
|
$out[] = rtrim($m[1]);
|
|
$out[] = '```';
|
|
}
|
|
$out[] = '';
|
|
|
|
echo implode("\n", $out), "\n";
|