[RAPTOR-18075] feat(artifact): add dr artifact code doctor

[ajalon1]

RATIONALE

RAPTOR-18075: when a project's .datarobot/workload/ (legacy .wapi/) sync state breaks, users currently get cryptic failures from init/sync and no guided recovery path. dr artifact code doctor diagnoses the state, reports clear remedies, and offers safe repairs for the cases the CLI can fix locally.

ARCHITECTURE

The feature is split across three layers:

• cmd/artifact/code/doctor: Cobra command wiring, soft auth probe, output selection, and repair/relink flow control.
• internal/workload/doctor: workload sync-state checks, remedies, and safe repair/relink operations.
• internal/doctor: reusable doctor framework with statuses, ordered runner, report aggregation, and text/JSON reporters.

The four remote checks share exactly one GetArtifact snapshot per run through the injected ArtifactGetter seam. SKIP cascades are explicit: missing state skips everything, invalid config skips config-dependent checks, and non-404 remote failures skip remote checks with a connectivity remedy instead of pretending the artifact was deleted. --fix and --relink run through a global held-lock safety gate before making any local changes.

flowchart TD
    subgraph CMD["cmd/artifact/code/doctor (cobra wiring)"]
        F["flags: --dir, --output-format, --yes, --fix, --relink"]
        P["soft auth probe (non-fatal, no login wizard)"]
        RUN["pageDoctor"]
    end

    subgraph WL["internal/workload/doctor (wapi checks + repairs)"]
        L["6 local checks: presence, config, manifest, divergence, rollback, lock"]
        R["4 remote checks: artifact-exists, artifact-locked, catalog-mismatch, drift"]
        S["one GetArtifact snapshot (ArtifactGetter seam)"]
    end

    subgraph CORE["internal/doctor (generic framework)"]
        RN["Runner (ordered execution)"]
        REP["Report + exit-code: 1 if any FAIL"]
        T["text reporter (lipgloss table)"]
        J["JSON reporter (pure stdout)"]
    end

    API["DataRobot API (read-only GET)"]

    F --> P
    P --> RUN
    RUN --> L
    RUN --> R
    R --> S
    S --> API
    L --> RN
    R --> RN
    RN --> REP
    REP --> T
    REP --> J

    P -.->|"offline: remote checks SKIP"| R
    L -.->|"presence FAIL: skip all"| SK1["remaining checks SKIP"]
    L -.->|"config FAIL: skip divergence + remote"| SK2["divergence + remote SKIP"]

    subgraph REPAIR["repair phase (side branch)"]
        G["global held-lock safety gate"]
        FIX["--fix: manifest, rollback, stale lock"]
        REL["--relink: repoint + fresh BASE"]
    end

    RUN -.-> G
    G -.->|"live holder: skip all repairs"| SK3["all repairs skipped"]
    G -.-> FIX
    G -.-> REL
    REL -.->|"hard-requires API"| API

Loading

Adding a new check is intentionally small: implement doctor.Check, add a canonical remedy, register it in the ordered local/remote check list, and test it through the fake seams. Both reporters render whatever the ordered runner returns.

flowchart TD
    A["1. implement doctor.Check: ID, Name, Run(ctx) -> Result"]
    B["2. add a canonical remedy constant in remedies.go"]
    C["3. register the constructor in LocalChecks/RemoteChecks"]
    D["4. place it deliberately; order is pinned and user-visible"]
    E["5. test with temp sync state + fake ArtifactGetter"]
    F["text and JSON reporters render it automatically"]

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F

Loading

Full design and check-authoring guide: docs/development/doctor.md.

CHANGES

• Reusable framework: adds internal/doctor with OK/WARN/FAIL/SKIP statuses, ordered runner, report aggregation, text table output, and pure JSON output.
• Doctor checks: adds internal/workload/doctor with six local checks (wapi.presence, wapi.config, wapi.manifest, wapi.config-manifest-divergence, wapi.rollback, wapi.lock) and four remote checks (remote.artifact-exists, remote.artifact-locked, remote.catalog-mismatch, remote.drift).
• Command surface: adds dr artifact code doctor under the existing workload feature gate with --dir, --output-format json, --fix, --relink, and --yes. Read-only doctor runs never write local files or server state.
• Safe repairs: --fix can rebuild a missing manifest, restore an interrupted rollback, and clear a stale lock only when the lock is acquirable. All repairs are skipped while another process holds the sync lock.
• Relink flow: --relink <artifact-id> repoints an existing local state to a reachable unlocked service artifact, refreshes BASE, appends relink history, leaves the working tree and server untouched, and defaults confirmation to No.
• Init guidance: dr artifact code init now offers relink-oriented guidance when an existing state points at a missing or mismatched artifact instead of only telling the user to delete state manually.
• Docs: updates the artifact command reference and adds the doctor architecture/check-authoring guide.

TESTING

• Added unit and command coverage across internal/doctor, internal/workload/doctor, and cmd/artifact/code/doctor.
• Verified JSON stdout purity, exit-code aggregation, SKIP cascades, repair summaries, held-lock behavior, relink gates, and init relink-offer paths.
• Live staging validation used throwaway doctor-test-* fixtures for healthy, deleted-artifact, catalog mismatch, drift, offline, and relink-to-sync scenarios; fixtures were cleaned up.
• Interactive confirmation paths were exercised through a virtual PTY, including accept, decline, and Ctrl-C.
• Local/mission validation covered build, lint, unit tests, live staging checks, and user-testing flows.

Current CI note: the PR currently has one failing Windows test job. The failures are in doctor lock-check expectations on Windows, where wapi.lock returns SKIP ("lock not enforced on this platform") while several tests still expect OK. Linux tests, lint, build, CodeQL, and other checks are passing.

NOTES

• A separate stacked PR will carry the informational checks that were intentionally kept out of RAPTOR-18075 scope.
• --fix and --relink are mutually exclusive via Cobra's generic mutually-exclusive flag handling.
• Remote checks use one fetched artifact snapshot per run to avoid inconsistent per-check observations.

RELATED

• Jira: RAPTOR-18075

---

Note

Medium Risk
New CLI paths mutate local sync state (--fix, --relink) and change init already-linked behavior; impact is bounded by the workload feature gate and extensive tests, but mis-repair or relink could confuse sync baselines.

Overview
Adds dr artifact code doctor under the existing workload feature gate to diagnose .datarobot/workload/ sync state, print text or JSON reports, and exit 1 when any check FAILs.

The command wires a reusable internal/doctor runner/reporters to internal/workload/doctor checks (six local, four remote with one shared artifact fetch). Optional --fix applies safe local repairs (manifest rebuild, rollback restore, stale lock clear) behind a held sync.lock gate; --relink repoints local binding with confirm/--yes, history logging, and no working-tree or server writes. Diagnosis skips normal auth PreRun and uses a soft credential probe so remote checks SKIP when offline.

dr artifact code init when the project is already linked now branches on config health and remote artifact state: corrupt config → doctor --fix; deleted artifact or catalog mismatch → doctor --relink (interactive relink offer or non-interactive guidance); healthy → doctor only. Removes prior “delete state to re-init” messaging and adds pinned JSON abort shapes for scripting.

Docs and command trees are updated; broad unit/command tests cover registration, JSON purity, repair/relink gates, and init relink flows.

^{Reviewed by Cursor Bugbot for commit 211b745. Configure here.}

[datarobot-pr-review-router]

🎫 Jira: RAPTOR-18075 — dr artifact code doctor: diagnose & repair .wapi state

[ajalon1]

example package checks I was thinking of:
dr plugin doctor
dr template doctor
dr dotenv doctor
dr auth doctor

So many doctors.

[ajalon1]

@BugBot run

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 211b745. Configure here.}

[cursor]

Init advertises unusable config fix

Medium Severity

A corrupt config.json is steered to dr artifact code doctor --fix, which cannot rebuild config. RemedyConfig and fixManifest both send the user to re-init, and the config check is marked not Fixable, so following this remedy leaves the project stuck.

Additional Locations (2)

• cmd/artifact/code/init/display.go#L154-L161
• internal/workload/doctor/relink.go#L194-L196

 

^{Triggered by project rule: Bugbot Rules for DataRobot CLI}

^{Reviewed by Cursor Bugbot for commit 211b745. Configure here.}

[cursor]

Windows lock tests expect OK

Medium Severity

On Windows, wapi.lock returns SKIP ("lock not enforced on this platform"), but several tests still require OK and a 10-ok summary. The GOOS seam is unused here, so the Windows CI job fails on healthy-project and cascade cases.

Additional Locations (2)

• internal/workload/doctor/suite_test.go#L62-L76
• cmd/artifact/code/doctor/cmd_test.go#L270-L276

 

^{Triggered by project rule: Bugbot Rules for DataRobot CLI}

^{Reviewed by Cursor Bugbot for commit 211b745. Configure here.}

[chasdr]

hey AJ, chas's claude poking at your droid's config build. newCfg carries ArtifactID/CatalogID/LastSyncedVersionID/CreatedAt/CLIVersion but not LastBuiltVersionID, so relink quietly nils it. its own doc says a deploy inheriting an image needs it to know if the code moved.

intended for the fresh BASE? if so worth making it explicit like the // fresh BASE on LastSyncedVersionID. the explicit field list also means the next Config field added drops here the same silent way.

[chasdr]

+1 to cursor. printCorruptConfig sends the user to doctor --fix, but nothing actually repairs config.json: fixManifest skips a corrupt config telling them to re-init, configCheck is Fixable:false, and RemedyConfig is init itself. so --fix runs and lands them right back at re-init. point at init <artifact-id> directly?