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

[ajalon1]

RATIONALE

RAPTOR-18075: when a project's .datarobot/workload/ (legacy .wapi/) sync state breaks — deleted artifact, interrupted sync/rollback, stale lock, catalog mismatch — users get cryptic failures from init/sync and no recovery path short of deleting state by hand. dr artifact code doctor diagnoses the state read-only and offers safe, gated repairs.

ARCHITECTURE

The feature is layered in three packages: the command layer wires Cobra flags and the soft auth probe, the workload layer owns the wapi-specific checks and repairs, and the generic framework layer owns the ordered runner, the reporters, and exit-code aggregation. The four remote checks share exactly one GetArtifact per run through the injected ArtifactGetter seam; SKIP cascades (presence FAIL skips all; config FAIL skips divergence + remote) are honest per-run observations. The --fix/--relink repair phase is a side branch gated by a global held-lock safety check.

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["runDoctor"]
    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, 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 five small steps; both reporters pick it up automatically because they render whatever the ordered Runner returns. Check order is pinned and user-visible, and remedies are canonical strings owned by internal/workload/doctor.

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 the check-list composition (LocalChecks/RemoteChecks)"]
    D["4. place it at a deliberate position — order is pinned and user-visible"]
    E["5. write tests with the fake seams: initProject temp state, ArtifactGetterFunc"]
    F["both reporters render it automatically"]

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

Loading

Full doc with the check-authoring guide and details on the SKIP cascades, repair semantics, and output contract: docs/development/doctor.md on this branch.

CHANGES

• internal/doctor (new): generic, state-agnostic doctor framework — OK/WARN/FAIL/SKIP statuses, ordered runner, text (lipgloss table) + JSON reporters. Reusable for a future top-level dr doctor.
• internal/workload/doctor (new): 6 local checks (wapi.presence, wapi.config, wapi.manifest, wapi.config-manifest-divergence, wapi.rollback, wapi.lock with a non-creating probe) + 4 remote checks (remote.artifact-exists, remote.artifact-locked, remote.catalog-mismatch, remote.drift) sharing exactly one GetArtifact per run. Sensible SKIP cascades; non-404 remote failures report SKIP with a connectivity remedy, never "deleted".
• cmd/artifact/code/doctor (new): command wiring under the existing workload feature gate; soft auth probe (never launches the login wizard, never writes drconfig.yaml); --output-format json with stdout kept pure JSON; exit 1 iff any check FAILs.
• --fix: safe auto-repairs — rebuild manifest from config, restore interrupted rollback (.rollback/ → working tree), clear a stale lock only if acquirable — all behind a global gate that skips every repair while a live process holds the sync lock. Reports per-repair actions[] and re-runs the full check suite so output/exit code reflect the post-fix state.
• --relink <new-artifact-id>: in-place repoint with a fresh sync BASE — aborts byte-identical on held lock / unreachable API / 404 / locked / non-service target / not-linked; confirm prompt defaults to No; rewrites config.json (new artifactId + catalogId, lastSyncedVersionId=null), resets manifest.json, appends a {op:relink, from, to, ts} history entry; working tree and server untouched. --fix and --relink are mutually exclusive.

TESTING

• ~80 new unit/command tests across the three packages, all race-clean; task lint green on linux/darwin/windows.
• Verified live against staging with throwaway doctor-test-* fixtures: healthy (never-synced), deleted-artifact 404 → FAIL + relink remedy, catalog mismatch, drift, offline (unreachable endpoint → remote SKIP, exit 0), full relink flow ending with sync targeting the new artifact, and interactive confirm accept/decline/Ctrl-C via a virtual PTY. All fixtures deleted.

TODO

• init change: when a project is already linked to a gone/mismatched artifact, offer doctor --relink in place of the current "Delete … to re-init." advice (in progress on this branch)
• demo video

NOTES

• Draft while the remaining init change lands. A separate stacked PR will carry five additional informational checks (legacy .wapi/ migration hint, .drignore presence, history.log parse health, no-codeRef hint, orphaned .checkouts/) so this diff stays scoped to RAPTOR-18075.
• Read-only doctor runs perform zero local writes and zero server writes (verified by checksum/updatedAt evidence).

RELATED

• JIRA: RAPTOR-18075

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