Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/rtcoder/devdoctor


https://github.com/rtcoder/devdoctor

Last synced: about 1 month ago
JSON representation

Awesome Lists containing this project

README 

          
# DevDoctor



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, Terraform/IaC, Kubernetes/Helm, .NET, C/C++, generic web, and CI problems before they turn into manual debugging sessions.



Current version: `1.40.0`



## Installation



DevDoctor requires PHP 8.5 or newer.



```bash

composer install

php devdoctor list

```



DevDoctor currently runs from the project checkout:



```bash

php devdoctor 

```



Build a local PHAR:



```bash

php devdoctor app:build devdoctor.phar --build-version=1.40.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:



```bash

composer global require rtcoder/devdoctor

devdoctor --version

```



Install locally in a project:



```bash

composer require --dev rtcoder/devdoctor

vendor/bin/devdoctor ci

```



## Commands



```text

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

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:



```bash

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

```



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



```bash

--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`:



```bash

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

```



## Examples



```bash

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 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 ` | `kill -TERM ` | `taskkill /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 |

| 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.

- 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`, `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 |

| 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.



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



```bash

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

```



## Table Output



```text

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



```json

{

    "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:



```bash

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:



```bash

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`, `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.



```bash

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` | Security-oriented strict profile |



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:



```yaml

- uses: rtcoder/devdoctor@v1.40.0

  with:

    version: v1.40.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:



```bash

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:



```yaml

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:



```bash

php devdoctor env --config=devdoctor.yml

php devdoctor ci --config=devdoctor.yml

```



Generate an initial configuration with the interactive wizard:



```bash

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



```text

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/v1/devdoctor-output.schema.json).

- [schemas/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](docs/issue-codes.html) catalog and the machine-readable [schemas/v1/issue-codes.json](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/](docs/index.html), including installation, command reference, config, scenarios, output formats, baseline, safety, contracts, [issue codes](docs/issue-codes.html), release verification, [changelog](docs/changelog.html), 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`:



```bash

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 `, 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:



```text

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:



```bash

sha256sum --check devdoctor.phar.sha256

```



Verify every executable release asset with the combined checksum file:



```bash

sha256sum --check devdoctor.sha256

```



Verify the keyless signature with Cosign:



```bash

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:



```bash

brew tap rtcoder/tap

brew install devdoctor

```



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.40.0` or `v1.40.0`. The workflow downloads `devdoctor.phar.sha256` from the GitHub Release and updates `Formula/devdoctor.rb` in `rtcoder/homebrew-tap`.



## Development



Update release version pins with:



```bash

./bump-version 1.40.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.



```bash

composer validate --strict

php devdoctor test

./vendor/bin/pint --test

php devdoctor app:build devdoctor.phar --build-version=1.40.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](ROADMAP.md) for the implementation roadmap and later distribution work.