How to Check System Health with Archify's Doctor Command

Run node bin/archify.mjs doctor (or archify doctor when installed globally) to validate your Node.js version, core HTML templates, runtime scripts, and schema validators before authoring architecture diagrams.

Archify is a zero‑dependency architecture diagramming tool distributed as a runnable ZIP. Before you generate diagrams, you should verify that all runtime assets are present and compatible. The doctor command, implemented in archify/bin/archify.mjs, performs a comprehensive health check of your environment and exits with a non‑zero status if any critical component is missing or incompatible.

What the Doctor Command Validates

The health check executes eleven distinct validations, each targeting a specific runtime requirement. According to the source code in archify/bin/archify.mjs (lines 1219–1355), the command verifies the following:

• Node.js version (lines 1221–1225): Ensures the runtime is Node ≥ 18 by parsing process.version.
• Core HTML template (lines 1229–1234): Checks that the base page template used for every rendered artifact exists via fs.existsSync(template).
• Example renderer (lines 1236–1241): Validates the bundled example diagram renderer is present.
• Live preview runtime (lines 1243–1248): Confirms the lightweight preview server script exists for the preview command.
• Visual‑check runtime (lines 1250–1255): Verifies the runner that validates rendered HTML for containment and capture capabilities.
• Output‑path safety runtime (lines 1257–1262): Ensures the guard against writing files outside the package directory is functional.
• Scenario recipe guide (lines 1264–1269): Checks for the collection of pre‑written scenario recipes.
• Progressive authoring references (lines 1271–1279): Validates three authoring‑references files that define Archify’s contracts.
• Architecture compare runtime (lines 1283–1292): Confirms the delta script and two example JSON fixtures exist for the compare command.
• Standalone schema validators (lines 1294–1312): Dynamically imports generated validators to ensure each diagram type exports a validation function.
• Per‑type assets (lines 1314–1334): Loops over the TYPES array (architecture, workflow, sequence, dataflow, lifecycle) to verify each has a renderer script, JSON schema, and sample source file.

How to Run the System Health Check

You can invoke the doctor command from the repository root or via a global installation.

Basic local usage:

node bin/archify.mjs doctor

When installed globally via npx skills add tt-a1i/archify -g:

archify doctor

Both entry points execute the same validation sequence defined in archify.mjs.

Interpreting the Output and Exit Codes

When all checks pass, the command prints a succinct report and exits with code 0:

Archify doctor

[ok] Node.js v18.17.0 (requires >=18)
[ok] Core template
[ok] Example renderer
[ok] Live preview runtime
[ok] Visual-check runtime
[ok] Output path safety runtime
[ok] Scenario recipe guide
[ok] Progressive authoring references
[ok] Architecture compare runtime and proof fixtures
[ok] Standalone schema validators
[ok] architecture renderer, schema, and example
[ok] workflow renderer, schema, and example
[ok] sequence renderer, schema, and example
[ok] dataflow renderer, schema, and example
[ok] lifecycle renderer, schema, and example

Archify is ready.

If any check fails, doctor reports the specific failure and exits with code 1:

[unsupported] Node.js v16.14.0 (requires >=18)

Archify is not ready: Node.js 18 or newer is required; 3 required files missing.

This non‑zero exit code makes the command suitable for CI/CD pipelines:

node bin/archify.mjs doctor && echo "Deployment ready" || echo "Health check failed"

Why the Doctor Command Matters Architecturally

The doctor command serves as deterministic gating for downstream operations. Because Archify is distributed as a zero‑dependency ZIP that may be unpacked on any OS, the command guarantees a complete, runnable set of runtimes before processing. It prevents confusing "partial‑runtime" errors in commands like validate, deliver, and compare by failing early when assets such as the output‑path safety runtime or standalone validators are missing. The exit‑code semantics also align with the repository’s smoke‑test strategy described in archify/test/cli.test.mjs, allowing automated pipelines to enforce that a released ZIP is fully functional before deployment.

Summary

• Run node bin/archify.mjs doctor (or archify doctor) to validate system health before authoring.
• The command checks Node.js ≥ 18, core templates, runtime scripts, schema validators, and per‑diagram assets in archify/bin/archify.mjs.
• It exits with code 0 on success and code 1 on failure, making it CI/CD friendly.
• Use it to prevent downstream errors by verifying the authoring references and safety runtimes required by the preview and compare commands.

Frequently Asked Questions

What Node.js version does Archify require?

Archify requires Node.js version 18 or newer. The doctor command checks this at lines 1221–1225 in archify/bin/archify.mjs by parsing the major version from process.version. If you run Node 16 or earlier, the command reports [unsupported] and exits with an error.

Can I use the doctor command in CI/CD pipelines?

Yes. The command is designed for automation. It returns exit code 0 when all checks pass and a non‑zero code when any check fails, allowing build scripts to gate deployments on a healthy Archify installation. The smoke tests in archify/test/cli.test.mjs (lines 82–103) enforce this behavior across releases.

What does the "standalone schema validators" check verify?

This check (lines 1294–1312) dynamically imports the generated validator modules for each diagram type and confirms they export a validation function. It ensures that the validators match the declared diagram types (architecture, workflow, sequence, dataflow, lifecycle) as defined in the authoring‑contract.md reference file.

Where is the doctor command implemented in the source code?

The entire health‑check logic resides in archify/bin/archify.mjs between lines 1219 and 1355. This block contains the sequential validation logic, the dynamic imports for validators, and the formatted console output that reports [ok] or [unsupported] for each component.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}