magento/magento2-phpstorm-plugin/magento-inspect

Magento Inspect

Use this skill for Magento or Adobe Commerce configuration, CLI/runtime discovery, and compatibility analysis in an opened JetBrains IDE project.

• For source configuration lookups, use magento_inspect with the preferred flow below.
• For project command discovery or n98-magerun2 metadata, use the CLI workflow below. Filesystem discovery alone does not require a running container.
• For backward compatibility or upgrade analysis, use magento_compatibility with the compatibility workflow below.

CLI Environment and n98-magerun2

Read this workflow when the task needs shell commands, runtime inspection, or magerun integration. Source-only lookups need no CLI probes.

Select the project runtime

1. Call describe_magento_cli_environment for the intended IDE project. Check the configured Magento root, preferred CLI directory, and each script's selection and working directory.
2. Use the preferred script beside the nearest Docker Compose configuration inside the project. For a project with Compose at its root and Magento in src/, ./bin/magento comes first; ./src/bin/magento is a fallback. Without an in-project Compose directory, use the Magento directory. Do not search arbitrary parent directories or infer ownership from proximity.
3. Run the returned example syntax from its reported working directory. A displayed project-relative path such as ./src/bin/magento may have an invocation of ./bin/magento with cwd set to src/; do not prepend src/ again. Keep source edits under the configured Magento root. Examples illustrate invocation syntax, not a request to execute the sample operation.
4. For DDEV, read the parsed project YAML settings and ordered overrides, their source files, execPrefix, and cwd. Append the intended container command and its arguments to execPrefix. It carries the configured project name and working_dir.web; cwd is on the host. docroot is the web document root, while composer_root controls ddev composer. Discovery works without Magerun and does not prove the container or a command is available. Check configuration.status and coverage before using the prefix.
5. Use a fallback only when fresh discovery shows the preferred script is absent or no longer eligible. A failed command, stopped container, or missing dependency does not justify changing runtimes. Report the selected runtime and failure; resolve it within the user's task.

If a DDEV command needs interactive permissions, suggest running the CLI environment’s terminalGuidance.command in PhpStorm’s Terminal (IDE console) from terminalGuidance.cwd. This checks PHP through the configured DDEV invocation so the user can handle permission prompts. The IDE process also needs access to DDEV and Docker. Retry the intended operation after access is resolved.

Discover installed magerun commands

Use magento_magerun with typed arguments; it does not take parametersJson.

1. Start with mode: "status". With no project-local Magerun candidate, Magerun uses the shared DDEV CLI environment and looks for magerun2 inside the container. It reads files and cached metadata without starting a process. Check projectRoot, magentoRoot, selected, and invocation. detected means a candidate was found; cached means metadata was previously verified. Neither proves that the runtime is available now. A filename such as magerun or n98-magerun does not establish Magento 2 compatibility.
2. If the task needs available commands, use mode: "commands" with a focused search and a small limit (1–100). This verifies n98-magerun2 and reads the installed catalogue, including custom commands. Follow nextOffset only as needed, keeping search and limit unchanged; nextOffset: null ends pagination. Do not invent capabilities from a version number or a remembered command list.
3. For a relevant returned name or alias, use mode: "command_help" with command set to that exact name. Read its returned arguments and options. Do not put shell syntax or command arguments in command.

Example arguments to magento_magerun for finding system-information support:

{"mode":"status"}

{"mode":"commands","search":"sys:info","offset":0,"limit":10}

If the catalogue contains sys:info, inspect its definition:

{"mode":"command_help","command":"sys:info"}

These modes inspect metadata; they do not execute sys:info or another application command. When the user's task requires execution, append the verified command and arguments to invocation.argv, preserving argument boundaries and invocation.cwd. The returned invocation can use php or a container launcher. Do not substitute a global binary, add a host --root-dir to a container invocation, or run sourceWrapper directly: a wrapper can contain installation/download steps that the metadata tool deliberately bypasses.

Reuse cached metadata while searching, paging, and reading help. It expires after five minutes and is invalidated by relevant local file changes. Use refresh: true when runtime/container contents changed or the user requests a fresh check; do not refresh every page. status with refresh only clears the cache; commands with refresh probes again.

Read status and message in the JSON text, even when MCP isError is absent or false. Successful metadata operations report status: "ok"; detection uses detected or cached. For not_found, invalid_configuration, missing_launcher, missing_installation, runtime_unavailable, unsupported_wrapper, or incompatible_tool, report the blocker without downloading tools, starting services, or trying an alternative runtime merely to obtain metadata. For unknown_command, check the installed catalogue and refresh only if it may have changed. Correct invalid_request arguments before retrying; other probe failures require inspecting the returned message. Host routing/type failures may be plain text or JSON-RPC errors rather than magerun JSON.

Native magerun MCP configuration

Use mode: "mcp_config" only when the task calls for native magerun MCP integration. The tool checks the installed server command and its filter support. With no include, it selects a small set of available inspection commands. If explicit filters are needed, use narrow, space-separated patterns in include and optional exclude, based on the installed catalogue.

For an installation that exposes sys:info, example arguments are:

{"mode":"mcp_config","include":"sys:info"}

Preserve the returned configuration command, argument array, cwd, and environment in a client that supports them. serverStarted: false and configurationWritten: false mean the tool only generated settings; report that distinction. Applying settings or starting the server is a separate action within the user's requested scope. If native MCP or filtering is unavailable, explain the limitation rather than guessing a server command or removing filters.

Compatibility Analysis

magento_compatibility requires the JetBrains PHP plugin.

For an upgrade check with a known scope, prefer mode: "upgrade" with the intended projectPath and exactly one moduleName or path. Omit targetVersion only when the user wants the next published feature release; provide the exact version otherwise. This preset defaults ignoreCurrentVersion and explainSuppressed to true, freezes the detected baseline and selected target, and returns the full scope/filter options in each nextCall. Follow nextStep/nextCall through preparation, readiness and analysis without reconstructing requests. outcome: "no_newer_release" means discovery found no newer feature release and no scan started. Verify project identity before continuing. Use the individual modes below when inspecting readiness, catalogs, or all target findings.