README

Developer diagnostics for humans.

DevDoctor is a read-only CLI for catching common local, repository, environment, cache, HTTP URL, database, queue, Docker, Composer, Git, Node/frontend, Flutter/Dart, native mobile, monorepos, Python, Ruby/Rails, Go, Rust, Java/JVM, MCP agent config, Terraform/IaC, Kubernetes/Helm, .NET, C/C++, generic web, and CI problems before they turn into manual debugging sessions.

Current version: 1.48.0

Installation

DevDoctor requires PHP 8.5 or newer.

composer install
php devdoctor list

DevDoctor currently runs from the project checkout:

php devdoctor <command>

Build a local PHAR:

php devdoctor app:build devdoctor.phar --build-version=1.48.0 --no-interaction
php builds/devdoctor.phar --version

Tagged releases publish both the PHAR and PHPacker standalone binaries for Linux, macOS, and Windows. The standalone binaries bundle a PHP runtime, so users do not need PHP installed just to run DevDoctor.

Install as a Composer package:

composer global require rtcoder/devdoctor
devdoctor --version

Install locally in a project:

composer require --dev rtcoder/devdoctor
vendor/bin/devdoctor ci

Commands

env        Check dotenv files and DevDoctor env rules
cache     Check framework and tool cache health
http      Check HTTP URL configuration
ports      Check local development port conflicts
composer   Check Composer project health
deps       Check Composer and Node dependency health
db         Check database environment configuration
queue      Check queue environment configuration
php        Check PHP runtime and platform health
node       Check Node.js project and package manager health
frontend   Check frontend project presets and build readiness
flutter    Check Flutter and Dart pubspec, lockfile, SDK constraints, dependency sources, and platform markers
mobile     Check native Android and iOS project markers, wrappers, debug flags, and lockfiles
monorepo   Check monorepo tooling, workspace lockfiles, and root package scripts
python     Check Python manifests and dependency manager health
ruby       Check Ruby and Rails manifests, lockfiles, versions, credentials, and dependency sources
go         Check Go module and workspace health
rust       Check Rust Cargo manifest and workspace health
java       Check Java/JVM Maven, Gradle, Ant, and Spring health
mcp        Check MCP server configuration files, secret hygiene, remote URLs, env references, supply-chain pins, and risky commands without starting servers
iac        Check Terraform, OpenTofu, and Terragrunt manifests, locks, modules, and secret hygiene
kube       Check Kubernetes manifests and Helm charts, locks, images, services, and secret hygiene
dotnet     Check .NET solution, project, SDK, lockfile, and NuGet health
cpp        Check C/C++ build files, dependency managers, and portability risks
web        Check generic web entry files, assets, public config, and server hints
laravel    Check Laravel application health
symfony    Check Symfony application env, runtime directories, recipes, and Composer scripts
security   Check project security posture
git        Check Git repository hygiene
docker     Check Docker and Docker Compose project health
health     Run a broad local project health check
doctor     Alias for health
ci         Run CI-safe DevDoctor diagnostics
presets    Detect supported project framework and tooling presets
inventory  Show detected presets and available modules
commands   List DevDoctor commands and documentation metadata
version    Show the current DevDoctor version
explain    Explain DevDoctor issue codes and hints
policy     Show DevDoctor safety and compatibility policy
support-bundle Print a redacted support bundle without writing files
self-update Check for a newer DevDoctor release and show or run the safest update command
init       Generate an initial devdoctor.yml configuration

All public commands support the shared options:

--path=. --format=table --ci --strict

Diagnostic commands also support output shaping without changing the underlying exit code:

--only=error,warning
--summary-only
--no-hints

Supported diagnostic output formats are table, json, and sarif.

Laravel Zero already defines a global --env option, so DevDoctor exposes the env-file selector as --env-file:

php devdoctor env --env-file=.env.local --example=.env.example

Examples

php devdoctor env
php devdoctor env --format=json --strict
php devdoctor env --only=error,warning --no-hints
php devdoctor health --summary-only
php devdoctor cache
php devdoctor cache --max-size=1024
php devdoctor http
php devdoctor http --url=https://example.test
php devdoctor ports --common
php devdoctor ports --port=3000 --port=5173
php devdoctor php
php devdoctor php --ci --minimum-memory=256
php devdoctor node
php devdoctor frontend
php devdoctor flutter
php devdoctor mobile
php devdoctor monorepo
php devdoctor python
php devdoctor ruby
php devdoctor go
php devdoctor rust
php devdoctor java
php devdoctor mcp
php devdoctor mcp --config=.cursor/mcp.json
php devdoctor mcp --disallow-remote --allow-command=node,npx --deny-command=docker
php devdoctor iac
php devdoctor kube
php devdoctor dotnet
php devdoctor cpp
php devdoctor web
php devdoctor laravel
php devdoctor symfony
php devdoctor security
php devdoctor composer
php devdoctor deps
php devdoctor inventory --format=json
php devdoctor commands --format=json
php devdoctor version --format=json
php devdoctor explain DD_ENV_FILE_MISSING --format=json
php devdoctor policy --format=json
php devdoctor support-bundle
php devdoctor self-update
php devdoctor db
php devdoctor db --connect
php devdoctor queue
php devdoctor git --require-clean --scan-large-files
php devdoctor docker --compose-file=docker-compose.yml
php devdoctor health
php devdoctor health --include-ports
php devdoctor doctor --summary-only
php devdoctor ci --modules=env,php,node,laravel,composer,db,git,docker --no-fail-on-warnings
php devdoctor presets --format=json
php devdoctor init --dry-run

ports uses platform-specific read-only providers: lsof on macOS/Linux, ss as a Linux fallback, and netstat -ano on Windows. If no supported provider is available, DevDoctor reports DD_PORT_PROVIDER_UNAVAILABLE instead of failing unexpectedly.

Platform Support

DevDoctor targets Linux, macOS, and Windows:

Capability	Linux	macOS	Windows
Command discovery	Native executable lookup	Native executable lookup	Native executable lookup
Port listeners	`lsof`, then `ss`	`lsof`	`netstat -ano`
Process suggestion	`kill -TERM <pid>`	`kill -TERM <pid>`	`taskkill /PID <pid>`
Cache diagnostics	Supported	Supported	Supported
HTTP URL diagnostics	Supported	Supported	Supported
PHP runtime diagnostics	Supported	Supported	Supported
Node.js project diagnostics	Supported	Supported	Supported
Frontend project diagnostics	Supported	Supported	Supported
Python project diagnostics	Supported	Supported	Supported
Ruby/Rails diagnostics	Supported	Supported	Supported
Go module diagnostics	Supported	Supported	Supported
Rust Cargo diagnostics	Supported	Supported	Supported
Java/JVM diagnostics	Supported	Supported	Supported
MCP configuration diagnostics	Supported	Supported	Supported
Terraform/IaC diagnostics	Supported	Supported	Supported
.NET diagnostics	Supported	Supported	Supported
C/C++ diagnostics	Supported	Supported	Supported
Generic web diagnostics	Supported	Supported	Supported
Laravel application diagnostics	Supported	Supported	Supported
Symfony application diagnostics	Supported	Supported	Supported
Security posture diagnostics	Supported	Supported	Supported
Database configuration diagnostics	Supported	Supported	Supported
Database connection diagnostics	Supported when the matching PDO driver is installed	Supported when the matching PDO driver is installed	Supported when the matching PDO driver is installed
Queue configuration diagnostics	Supported	Supported	Supported
Composer, Git, Docker	Supported when their executables are installed	Supported when their executables are installed	Supported when their executables are installed

Platform-specific commands are only suggested. DevDoctor never terminates a process automatically.

Diagnostic Details

Compose interpolation understands required references such as ${VAR} and ${VAR?message}.
Compose references with defaults such as ${VAR:-default} and ${VAR-default} do not produce missing-variable warnings.
Git reports DD_GIT_BINARY_MISSING when Git is unavailable instead of treating the path as a non-repository.
Windows port diagnostics use tasklist when available to resolve a PID to a process name.
Cache diagnostics inspect known Laravel, Symfony, and Node cache directories, size thresholds, writability, and Laravel cache artifacts without deleting anything.
HTTP diagnostics validate configured APP_URL, FRONTEND_URL, API_URL, and explicit --url values without making network requests.
PHP diagnostics compare the active CLI runtime with composer.json, required ext-* packages, memory_limit, loaded php.ini, and Xdebug state in CI.
Node.js diagnostics inspect package.json, npm/Yarn/pnpm/Bun lockfiles, stale lockfiles, node_modules, engines.node, .nvmrc, .node-version, and risky package scripts.
Frontend diagnostics inspect Vite, Next.js, Nuxt, Astro, React, Vue, Svelte, Angular, and generic static frontend evidence without running builds.
Flutter diagnostics inspect pubspec.yaml, pubspec.lock, Dart SDK constraints, local path/Git dependency sources, and Flutter platform markers without running flutter pub get or builds.
Mobile diagnostics inspect native Android/iOS markers, Gradle wrappers, Android debug flags, CocoaPods locks, and iOS debug entitlements without running Gradle, Xcode, or CocoaPods.
Monorepo diagnostics inspect Nx, Turbo, Lerna, pnpm workspaces, Rush, Bazel, Pants, workspace lockfiles, and root package scripts without running orchestrators or package managers.
Utility commands expose project inventory, issue-code explanations, safety policy, and redacted support bundles without modifying project files.
Python diagnostics inspect pyproject.toml, requirements*.txt, Pipfile, poetry.lock, uv.lock, and Conda files without installing packages.
Ruby diagnostics inspect Gemfile, Gemfile.lock, .ruby-version, Rails credentials, config/database.yml, and risky gem sources without running Bundler or Rails.
Go diagnostics inspect go.mod, go.sum, go.work, local replace directives, toolchain declarations, and vendor metadata without running go mod tidy or downloading modules.
Rust diagnostics inspect Cargo.toml, Cargo.lock, workspaces, rust-toolchain.toml, local path/git dependencies, and release profile settings without running Cargo.
Java diagnostics inspect Maven, Gradle, Ant, wrappers, Java version declarations, risky build scripts, and Spring production debug flags without running builds or dependency resolution.
MCP diagnostics inspect .mcp.json, mcp.json, .agents/mcp.json, .claude/mcp.json, .cline/mcp.json, .codex/mcp.json, .continue/mcp.json, .continue/config.json, .cursor/mcp.json, .roo/mcp.json, .vscode/mcp.json, and .windsurf/mcp.json for stdio, sse, and http server definitions, inline secrets, missing env references, insecure remote URLs, unpinned package runners, mutable Docker image tags, optional project policies, and risky shell command patterns without starting servers or making network requests.
MCP project policy flags let you report remote transports with --disallow-remote, restrict stdio commands with --allow-command=node,npx, or block specific commands with --deny-command=docker.
IaC diagnostics inspect Terraform, OpenTofu, and Terragrunt files, provider lockfiles, provider version constraints, remote module refs, backend/provider secrets, and secret-like variable defaults without running init, plan, or network access.
Kubernetes diagnostics inspect manifests, Helm charts, values files, image tags, service exposure, hostPath mounts, and privileged containers without running kubectl, helm, or cluster queries.
.NET diagnostics inspect .sln, project files, global.json, NuGet.config, packages.lock.json, target frameworks, and restore lock mode without running dotnet restore, build, or test.
C/C++ diagnostics inspect CMake, Make, Meson, Autotools, vcpkg, Conan, compile command metadata, in-source build artifacts, compiler flags, generator assumptions, and shell portability risks without compiling code.
Generic web diagnostics inspect static entry files, obvious asset references, public config files, web server config hints, and conflicting local port declarations without running a build.
Laravel diagnostics inspect .env, APP_KEY, production debug mode, APP_URL, runtime directories, and config cache state.
Symfony diagnostics inspect .env/.env.local, APP_SECRET, production debug mode, runtime cache/log directories, Symfony Flex recipe drift, and Symfony Composer script risks without running bin/console.
Database diagnostics inspect DB_CONNECTION, required database keys, valid ports, SQLite file paths, and optional read-only PDO connectivity with --connect.
Queue diagnostics inspect QUEUE_CONNECTION, common async driver requirements, and production environments that still use the synchronous queue driver.
Security diagnostics inspect env example secrets, hard-coded secret patterns, risky Composer and package scripts, Docker privileged mode, Docker socket mounts, and .env ignore gaps.
Health aggregates local project diagnostics across presets, env, cache, http, php, node, laravel, composer, db, queue, git, docker, and security; it adds frontend, flutter, mobile, monorepo, python, ruby, go, rust, java, mcp, iac, kube, dotnet, cpp, web, and symfony automatically when matching presets are detected. Add --include-ports to include common local port checks.
Composer reports DD_COMPOSER_LOCK_OUTDATED when composer.lock is older than composer.json.
Process execution uses argument arrays and supports project paths containing spaces.

Project Presets

The presets command detects supported project stacks from files and declared dependencies without running project tools:

Preset	Detection evidence
Laravel	`laravel/framework` or `artisan`
Symfony	`symfony/framework-bundle` or `bin/console`
Node.js	`package.json`
Frontend	frontend package dependencies, `index.html`, or common app entry files
Vite	`vite` dependency or a `vite.config.*` file
Next.js	`next` dependency
Nuxt	`nuxt` dependency
Astro	`astro` dependency
Flutter / Dart	`pubspec.yaml`, `pubspec.lock`, `.metadata`, or Flutter SDK dependency
Mobile native	Android manifests/build files, `Podfile`, `Podfile.lock`, or Xcode project markers
Monorepo	`nx.json`, `turbo.json`, `lerna.json`, `pnpm-workspace.yaml`, `rush.json`, Bazel, Pants, or package workspaces
Python	`pyproject.toml`, `requirements*.txt`, `Pipfile`, `uv.lock`, or Conda files
pip / Poetry / Pipenv / uv / Conda	their lockfiles or manifests
Ruby / Rails	`Gemfile`, `.ruby-version`, `config/application.rb`, or `bin/rails`
Go	`go.mod` or `go.work`
Rust	`Cargo.toml`, `Cargo.lock`, or `rust-toolchain.toml`
Java/JVM	Maven, Gradle, or Ant build files
Maven / Gradle / Ant / Spring	wrapper/build files or Spring Boot references
MCP	`.mcp.json`, `mcp.json`, `.agents/mcp.json`, `.claude/mcp.json`, `.cline/mcp.json`, `.codex/mcp.json`, `.continue/mcp.json`, `.continue/config.json`, `.cursor/mcp.json`, `.roo/mcp.json`, `.vscode/mcp.json`, or `.windsurf/mcp.json`
IaC / Terraform	`.tf`, `.tfvars`, `.terraform.lock.hcl`, `tofu.lock.hcl`, or `terragrunt.hcl`
Kubernetes / Helm	Kubernetes manifests, `Chart.yaml`, `Chart.lock`, `helmfile.yaml`, `kustomization.yaml`, or `values.yaml`
C/C++	CMake, Make, Meson, Autotools, vcpkg, or Conan files
CMake	`CMakeLists.txt`
.NET	solution/project files, `global.json`, or `NuGet.config`
Generic web	static entry files, web server config, or frontend evidence
Docker Compose	A supported Compose file

v1.24.0 ships devdoctor iac with static diagnostics for Terraform, OpenTofu, and Terragrunt manifests, provider lockfiles, broad provider constraints, unpinned remote modules, and secret-like IaC values.

v1.25.0 ships devdoctor kube with static diagnostics for Kubernetes manifests and Helm charts. It checks Helm dependency locks, literal secrets in values files, mutable image tags, privileged containers, hostPath mounts, and NodePort service exposure without running kubectl or helm.

v1.26.0 ships devdoctor flutter with static diagnostics for Flutter and Dart projects. It checks pubspec lockfiles, Dart SDK constraints, path/Git dependencies, and platform markers without running Flutter commands or builds.

v1.27.0 ships devdoctor mobile with static diagnostics for native Android and iOS projects. It checks Gradle wrapper presence, Android debuggable manifests, CocoaPods lockfiles, and iOS debug entitlements without running platform build tools.

v1.28.0 ships devdoctor monorepo with static diagnostics for workspace tooling. It checks mixed orchestration tools, missing workspace lockfiles, and risky root scripts without running monorepo commands.

v1.29.0 ships utility commands: inventory, explain, policy, and support-bundle. They help inspect detected stacks, understand issue codes, review DevDoctor safety policy, and print redacted support context without writing files.

v1.30.0 ships documentation automation and a richer documentation site. The issue code catalog is generated from schemas/v1/issue-codes.json, includes filtering and copy controls, and the docs include scenario guides for Laravel, frontend, monorepo, and CI baseline rollout.

v1.31.0 adds documentation navigation polish with active navigation, breadcrumbs, copy buttons for command snippets, and additional scenario guides for Python, Kubernetes/Helm, Terraform/IaC, Symfony, and mobile projects.

v1.32.0 adds machine-readable documentation metadata with docs/manifest.json and docs/commands.json so tools can consume page and command references without scraping HTML.

v1.33.0 adds CLI discoverability with devdoctor commands and devdoctor explain --module=..., making command metadata and issue-code hints available without leaving the terminal.

v1.34.0 adds CI policy profiles: local, ci, strict-ci, and security, with documented defaults for warning handling, strict mode, and module selection.

v1.35.0 adds --baseline-report for CI baselines, showing active, suppressed, and resolved fingerprint counts without hiding findings.

v1.36.0 adds a manual Update Homebrew Tap workflow for publishing or repairing the Homebrew formula for an existing release after HOMEBREW_TAP_TOKEN is configured.

v1.37.0 adds update checks for interactive table output and devdoctor self-update, which reports the current version, the latest release, and the safest update command for the detected installation method.

v1.38.0 polishes the composite GitHub Action metadata for GitHub Marketplace publishing, including branding, clearer input descriptions, and updated pinned examples.

v1.38.1 renames the Marketplace Action to DevDoctor CI Diagnostics so GitHub accepts the listing with a unique Action name.

v1.38.2 changes the Marketplace Action branding color to blue.

v1.39.0 adds the repository bump-version helper so release pins can be updated from one command instead of hand-editing every file.

v1.40.0 adds devdoctor version for script-friendly version checks with table and JSON output.

v1.41.0 changes the generated Homebrew formula to install standalone binaries instead of the PHAR, so devdoctor does not depend on the local PHP version.

v1.41.1 fixes the release artifact test on Windows by checking the bump-version PHP shebang instead of POSIX executable permissions.

v1.42.0 adds devdoctor mcp for read-only Model Context Protocol configuration diagnostics across .mcp.json, mcp.json, .cursor/mcp.json, and .vscode/mcp.json.

v1.43.0 expands MCP diagnostics with .agents/.codex config discovery, inline secret checks, env reference checks, insecure remote URL checks, and risky stdio command detection.

v1.44.0 expands MCP client config discovery for Claude, Cline, Continue, Roo, Windsurf, and nested mcp.servers style project files.

v1.45.0 adds MCP supply-chain checks for unpinned package-runner targets and mutable Docker image tags in stdio server definitions.

v1.46.0 adds MCP project policy flags for disallowing remote servers and enforcing stdio command allow/deny lists.

v1.47.0 includes MCP diagnostics in the security CI profile so agent config risks are covered by security-oriented runs.

v1.48.0 expands command documentation with every available CLI option per command and a roomier one-command-per-row layout.

Preset detection is informational and can be included in CI explicitly:

php devdoctor ci --modules=presets,env,php,node,laravel,composer,git,docker

Table Output

DevDoctor

Module     Status   Errors Warnings  Info
env        warning       0        1     0

Warnings
  [DD_ENV_MISSING_IN_ENV] .env.example:2 QUEUE_CONNECTION QUEUE_CONNECTION exists in .env.example but is missing in .env
    Hint: Add the key to the environment file or ignore it explicitly when it is optional.

Actionable findings may include a hint and a suggested command. Suggested commands are never executed by DevDoctor. Commands that can change system state, such as terminating a process, are marked as destructive in JSON output.

JSON Output

{
    "tool": "devdoctor",
    "schema_version": "1.0",
    "status": "warning",
    "summary": {
        "errors": 0,
        "warnings": 1,
        "info": 0,
        "suppressed": 0
    },
    "modules": [
        {
            "name": "env",
            "status": "warning",
            "summary": {
                "errors": 0,
                "warnings": 1,
                "info": 0,
                "suppressed": 0
            },
            "issues": [
                {
                    "code": "DD_ENV_MISSING_IN_ENV",
                    "severity": "warning",
                    "message": "QUEUE_CONNECTION exists in .env.example but is missing in .env",
                    "module": "env",
                    "file": ".env.example",
                    "key": "QUEUE_CONNECTION",
                    "hint": "Add the key to the environment file or ignore it explicitly when it is optional.",
                    "suppressed": false
                }
            ]
        }
    ]
}

SARIF Output

Use SARIF 2.1.0 for code scanning integrations:

php devdoctor ci --format=sarif > devdoctor.sarif

Each result maps the issue code to a SARIF rule id, includes relative file locations when available, and carries a stable devdoctorFingerprint/v1 based on code, module, file, and key. Hints and fix descriptions are included as metadata; suggested commands are never executed.

Health

The health command is a local, broad project overview. It uses the same output formats as other diagnostics and keeps ports opt-in to avoid machine-specific noise:

php devdoctor health --format=json
php devdoctor health --include-ports
php devdoctor health --modules=env,security --exclude=security

Unknown health modules return exit code 3.

CI

The CI aggregator runs env, php, node, laravel, composer, git, and docker by default. It adds frontend, flutter, mobile, monorepo, python, ruby, go, rust, java, mcp, iac, kube, dotnet, cpp, web, and symfony automatically when matching presets are detected. ports and security are excluded by default because they can depend on local machine state or intentionally present local files.

php devdoctor ci --format=json
php devdoctor ci --profile=local
php devdoctor ci --profile=strict-ci
php devdoctor ci --profile=security
php devdoctor ci --modules=env,php,node,laravel,composer --exclude=composer
php devdoctor ci --modules=security --no-fail-on-warnings
php devdoctor ci --no-fail-on-warnings

CI profiles provide documented defaults:

Profile	Modules	Behavior
`local`	`env,php,node,frontend,composer,git,docker` plus detected ecosystems	Does not fail on warnings by default
`ci`	`env,php,node,laravel,composer,git,docker` plus detected ecosystems	Current default behavior
`strict-ci`	`ci` modules plus `security`	Enables strict mode and fails on warnings
`security`	`env,git,docker,security,mcp`	Security-oriented strict profile including MCP agent config checks

Unknown modules and unknown profiles return exit code 3. Selected modules are always included in JSON output.

The repository CI workflow runs tests on Linux, macOS, and Windows with PHP 8.5. It also builds and smoke-tests the PHAR and a PHPacker standalone Linux binary.

GitHub Action

The composite GitHub Action downloads a pinned release PHAR, verifies its SHA-256 checksum, and runs CI diagnostics:

- uses: rtcoder/devdoctor@v1.48.0
  with:
    version: v1.48.0
    format: sarif

The Action metadata is prepared for GitHub Marketplace publishing with branding and explicit input descriptions. Always pin both the Action ref and the version input. The Action does not use latest.

Baselines

Baselines let an existing project acknowledge current warnings and errors while continuing to fail CI for new findings:

php devdoctor ci --write-baseline=devdoctor-baseline.json
php devdoctor ci --baseline=devdoctor-baseline.json
php devdoctor ci --baseline=devdoctor-baseline.json --baseline-report

Baseline fingerprints use issue code, module, normalized file path, and key. They do not depend on messages or line numbers. Suppressed findings remain visible in table, JSON, and SARIF output, but they do not affect status or exit code. Only warnings and errors are written. Use --baseline-report to show active, suppressed, and resolved fingerprint counts. Use --force to intentionally replace an existing baseline after review.

Configuration

DevDoctor reads devdoctor.yml for env rules:

modules:
  env:
    files:
      env: .env
      example: .env.example
    ignore:
      missing_in_env:
        - OPTIONAL_TOKEN
      missing_in_example:
        - LOCAL_ONLY_KEY
    rules:
      APP_KEY:
        required: true
      APP_DEBUG:
        type: bool
        forbidden_when:
          APP_ENV: production
      CACHE_DRIVER:
        allowed:
          - file
          - redis
      REDIS_URL:
        required_when:
          CACHE_DRIVER: redis

Use a different config file with:

php devdoctor env --config=devdoctor.yml
php devdoctor ci --config=devdoctor.yml

Generate an initial configuration with the interactive wizard:

php devdoctor init
php devdoctor init --dry-run
php devdoctor init --config=config/devdoctor.yml

The wizard detects supported env files and project presets, previews the YAML, and writes only after confirmation. It never copies environment values into the generated file. Existing files require --force and a second confirmation. In CI or --no-interaction mode, use --dry-run.

Exit Codes

0 = no issues
1 = warnings only
2 = errors found
3 = invalid DevDoctor config
4 = required input / dependency missing
5 = internal error / unexpected exception

Stable Contracts

JSON output includes schema_version and follows the stable v1 schema at schemas/v1/devdoctor-output.schema.json.
schemas/devdoctor-output.schema.json remains an alias for the latest schema.
Issue identifiers are documented in the human-readable docs/issue-codes.html catalog and the machine-readable schemas/v1/issue-codes.json.
Automation should match issue codes rather than human-readable messages.
Schema v1 will not receive breaking changes during v1.x. Existing issue codes will not be removed or repurposed without deprecation, and new codes may be added.
The version recorded in composer.json under extra.devdoctor.version matches the Git release tag.

Documentation

Full static documentation lives in docs/, including installation, command reference, config, scenarios, output formats, baseline, safety, contracts, issue codes, release verification, changelog, and pinned CI examples for GitHub Actions, GitLab CI, and Bitbucket Pipelines.

Regenerate the human-readable issue code catalog after changing schemas/v1/issue-codes.json:

php scripts/build-docs.php
php scripts/build-docs.php --check

Safety

DevDoctor is read-only by default:

It does not rewrite .env, Compose, Composer, Git, or project files.
It does not run composer install, composer update, Composer scripts, or internet-dependent audits.
It does not run docker compose up, start, stop, rm, or prune.
Hints and suggested commands are informational only and are never executed.
Port diagnostics may suggest kill -TERM <pid>, but never execute it.
Basic diagnostics do not require telemetry or internet access.

Release Verification

Tagged releases publish devdoctor.phar, PHPacker standalone binaries, SHA-256 checksums, Cosign signatures, and Sigstore certificates.

Standalone release assets:

devdoctor-linux-x64
devdoctor-linux-arm64
devdoctor-macos-x64
devdoctor-macos-arm64
devdoctor-windows-x64.exe

Verify the PHAR checksum before running a downloaded PHAR:

sha256sum --check devdoctor.phar.sha256

Verify every executable release asset with the combined checksum file:

sha256sum --check devdoctor.sha256

Verify the keyless signature with Cosign:

cosign verify-blob \
  --certificate devdoctor.phar.pem \
  --signature devdoctor.phar.sig \
  --certificate-identity-regexp 'https://github.com/rtcoder/devdoctor/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  devdoctor.phar

Homebrew

DevDoctor is available from the rtcoder/tap Homebrew tap:

brew tap rtcoder/tap
brew install devdoctor

The Homebrew formula installs the platform-specific standalone release binary for macOS or Linux. It does not execute the PHAR through the local php binary, so devdoctor --version works even when the system php points at an older runtime.

The release workflow can update rtcoder/homebrew-tap after each tag when the repository secret HOMEBREW_TAP_TOKEN is configured with write access to the tap.

If the token was added after a release, run the Update Homebrew Tap workflow manually from GitHub Actions and pass the release version, for example 1.48.0 or v1.48.0. The workflow downloads devdoctor.sha256 from the GitHub Release and updates Formula/devdoctor.rb in rtcoder/homebrew-tap.

Development

Update release version pins with:

./bump-version 1.48.0

The helper updates extra.devdoctor.version, Action examples, documentation pins, CI examples, pinned test expectations, and composer.lock. Use --no-lock only when you intentionally want to skip the Composer lock refresh.

composer validate --strict
php devdoctor test
./vendor/bin/pint --test
php devdoctor app:build devdoctor.phar --build-version=1.48.0 --no-interaction
php builds/devdoctor.phar --version
./vendor/bin/phpacker build --src=./builds/devdoctor.phar --dest=./builds/standalone --php=8.5 linux x64
./builds/standalone/linux/linux-x64 --version

Roadmap

See ROADMAP.md for the implementation roadmap and later distribution work.

rtcoder/devdoctor

包简介

关键字：

README 文档