feat: Add `apify actors doctor` for local Actor project diagnostics

[kuntal1461]

Problem

Actor project configuration issues that are locally detectable are not surfaced until apify actors push, a cloud build, or Actor startup. Examples:

• .actor/actor.json is missing, contains malformed JSON, or fails canonical Actor schema validation
• The Actor name violates Apify naming rules
• Referenced input, output, dataset, or KVS schema files are missing, malformed, or structurally invalid
• The project still uses the deprecated apify.json format

apify validate-schema handles schema validation in isolation, but there is no single command that checks Actor project health end-to-end: configuration presence, JSON parsing, canonical schema conformance, name validity, and schema integrity together.

The current workflow is:

develop locally → apify actors push → upload → cloud build → issue surfaced

Some of those failures are locally detectable and could be caught before deployment.

Proposal

I would like to propose a new subcommand:

apify actors doctor

An offline, read-only Actor project diagnostic command that runs a self-contained pre-flight check on the project in the current directory.

Conceptual output:

  ✓ .actor/actor.json found.
  ✓ .actor/actor.json is valid.
  ✓ Actor name "my-actor" is valid.
  ✗ Input schema is invalid: ...
  ✗ Output schema reference is missing at .actor/output.json.

2 errors

The intended workflow:

develop locally → apify actors doctor → fix issues → apify actors push

Proposed V1 scope

Check	Description
Actor config present	.actor/actor.json exists; deprecated apify.json is detected
JSON parsing	actor.json is valid JSON
Canonical schema	actor.json passes the canonical Actor schema (@apify/json_schemas)
Actor name	Name passes existing Apify naming constraints
Input schema	Referenced input / inputSchema file exists, parses, and is valid per @apify/input_schema
Output schema	Referenced output / outputSchema file exists, parses, and is valid
Dataset schemas	Referenced storages.dataset / storages.datasets.* files exist, parse, and are valid
KVS schema	Referenced storages.keyValueStore file exists, parses, and is valid

All checks reuse existing canonical Apify validators rather than introducing a parallel set of CLI-specific rules. Actor configuration evolves over time — a duplicate ruleset would drift.

Design constraints for V1

• Offline: no network calls, no Apify API, no authentication required
• Read-only: does not migrate, modify, or generate any files
• Aggregate: independent validations are collected and reported together in a single run
• Safe short-circuit: if actor.json cannot be parsed, checks that access its fields are skipped

Exit behavior

exit 0          → no blocking errors (warnings alone do not fail)
exit non-zero   → one or more errors, following existing CLI validation exit-code conventions

Why a separate doctor command?

Rather than implicitly adding checks to actors push:

• Does not change any existing deployment workflow
• Usable without credentials — before login, in CI, in a fresh checkout
• Can be adopted incrementally with low regression risk to existing push workflows

If maintainers later find the checks valuable, the underlying logic could be reused inside actors push, but that is not proposed here.

Relationship with validate-schema

apify validate-schema validates schemas in isolation. apify actors doctor is a project-level pre-flight: configuration presence, JSON validity, Actor schema conformance, name validity, and then schema validation for each referenced file. Both commands should share the same underlying validators.

Out of scope for V1

• Docker build simulation or runtime execution
• Dependency linting (package.json, lock file, Node/Python version checks)
• Cloud health or authentication checks
• Heuristic checks without a canonical backing rule — these create false positives for multi-language Actors
• JSON output or machine-readable format
• Integration into actors push

Trade-offs

High-confidence checks over maximum coverage. Doctor reports fewer things more reliably. Passing doctor does not guarantee a successful cloud build — only that locally-checkable configuration is sound.

Offline over cloud simulation. Fast and deterministic. Issues only detectable at platform build time are not covered by V1.

Separate command over implicit push checks. Low regression risk to existing push workflows; the trade-off is that developers must run doctor explicitly.

Existing validators over custom rules. Low long-term maintenance cost; the trade-off is that doctor is limited by what canonical libraries expose locally.

Acceptance criteria

• apify actors doctor is available as a subcommand under actors
• Valid Actor projects exit 0 with a passing summary
• actor.json presence, JSON parsing, and canonical schema errors are reported distinctly
• Non-object actor.json values (null, [], strings, numbers) produce a clean diagnostic and do not crash
• Actor name is validated against existing Apify rules
• Legacy apify.json is detected without mutating the project; when both apify.json and .actor/actor.json exist, .actor/actor.json remains the source of truth
• input / inputSchema, output / outputSchema, storages.dataset / storages.datasets, and storages.keyValueStore forms are all recognized
• Missing, malformed, and structurally-invalid referenced schemas each produce a distinct diagnostic
• All independent errors are collected in a single run
• Warnings alone produce exit 0; any error produces exit non-zero
• No network calls are made and no files are modified
• actors push behavior is unchanged

[l2ysho]

Thx for contribution @kuntal1461. In general this is good idea, but I think we would like to explore it more internally. This is not our main focus right now so we may iterate the issue idea or close. cc @patrikbraborec

[kuntal1461]

Thanks for the feedback, @l2ysho! Totally understand — happy to wait while you explore it internally. If you'd like any changes or want to revisit the approach later, feel free to ping me. Looking forward to hearing what direction you decide to take!

[patrikbraborec]

Hi @kuntal1461, thanks for the issue and idea. I will get to it during next week, and will let you know!