@trucore/openclaw-atf 0.1.1 → 0.2.0

package/src/doctor.mjs

@@ -0,0 +1,207 @@
+/**
+ * doctor.mjs — Integration doctor / readiness check for ATF OpenClaw plugin
+ *
+ * Answers:
+ *   - Is the plugin loaded under the canonical ID?
+ *   - Is the ATF CLI available?
+ *   - Is the ATF API reachable?
+ *   - Which backend is preferred / effective?
+ *   - Are expected native tools registered?
+ *   - Are there configuration warnings?
+ *   - What should the operator do next?
+ *
+ * Exports:
+ *   - runDoctor(cfg, registeredToolNames)  → DoctorReport
+ *   - EXPECTED_TOOLS                       → canonical tool list
+ *   - DOCTOR_STATUS                        → status enum
+ *
+ * Uses ONLY built-in Node modules + sibling backend.mjs. No external deps.
+ */
+
+import {
+  resolveBackend,
+  probeCliAvailable,
+  probeApiAvailable,
+  BACKEND_STATUS,
+} from "./backend.mjs";
+
+import {
+  validateConfig,
+  CANONICAL_PLUGIN_ID,
+} from "./config.mjs";
+
+// Import constants at module level — avoids circular dependency since
+// index.mjs imports doctor.mjs lazily (dynamic import inside handler).
+// At call-time, index.mjs is already fully initialized.
+
+// Canonical plugin identity — duplicated from index.mjs to avoid circular
+// import at module level. Kept in sync by version consistency tests.
+const PLUGIN_ID = "trucore-atf";
+const PLUGIN_VERSION = "0.2.0";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Canonical set of expected native tools in this plugin version. */
+export const EXPECTED_TOOLS = Object.freeze([
+  "atf_health",
+  "atf_discover",
+  "atf_bootstrap_plan",
+  "atf_bootstrap_execute_safe",
+  "atf_protect_intent",
+  "atf_verify_receipt",
+  "atf_report_savings",
+  "atf_integration_doctor",
+  "atf_bot_preflight",
+  "atf_tx_explain",
+  "atf_billing_info",
+  "atf_adoption_advisor",
+  "atf_billing_claim",
+]);
+
+/** Doctor overall status — stable finite set. */
+export const DOCTOR_STATUS = Object.freeze({
+  OK: "ok",
+  DEGRADED: "degraded",
+  MISCONFIGURED: "misconfigured",
+  UNAVAILABLE: "unavailable",
+});
+
+// ---------------------------------------------------------------------------
+// Doctor report
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} DoctorReport
+ * @property {string} plugin_id
+ * @property {string} plugin_version
+ * @property {boolean} plugin_loaded
+ * @property {boolean} lifecycle_exports_present
+ * @property {boolean} cli_available
+ * @property {boolean} api_available
+ * @property {string} preferred_backend
+ * @property {string} effective_backend
+ * @property {boolean} fallback_occurred
+ * @property {string|null} fallback_reason
+ * @property {string[]} native_tools_expected
+ * @property {string[]} native_tools_available
+ * @property {string[]} native_tools_missing
+ * @property {string} status
+ * @property {string[]} warnings
+ * @property {string[]} remediation
+ * @property {object} config_validation
+ */
+
+/**
+ * Run the integration doctor check.
+ *
+ * @param {Record<string, unknown>} cfg  Resolved plugin config.
+ * @param {string[]} registeredToolNames  Names of tools currently registered.
+ * @param {Record<string, unknown>} [rawUserConfig]  Original user config (pre-resolve) for validation.
+ * @returns {Promise<DoctorReport>}
+ */
+export async function runDoctor(cfg, registeredToolNames = [], rawUserConfig) {
+  // 1. Probe backends
+  const cli = await probeCliAvailable(cfg?.atfCli ?? "atf");
+  const api = await probeApiAvailable(cfg?.atfBaseUrl);
+  const backend = await resolveBackend(cfg, { cli, api });
+
+  // 2. Check tool registration
+  const registeredSet = new Set(registeredToolNames);
+  const toolsMissing = EXPECTED_TOOLS.filter((t) => !registeredSet.has(t));
+  const toolsAvailable = EXPECTED_TOOLS.filter((t) => registeredSet.has(t));
+
+  // 3. Lifecycle exports presence
+  const lifecyclePresent = true; // verified by ES import resolution
+
+  // 4. Config validation
+  const configResult = validateConfig(rawUserConfig ?? cfg);
+
+  // 5. Build warnings + remediation
+  /** @type {string[]} */
+  const warnings = [...backend.warnings];
+  /** @type {string[]} */
+  const remediation = [];
+
+  // Merge config validation warnings/errors into doctor output
+  if (!configResult.valid) {
+    for (const err of configResult.errors) {
+      warnings.push(`Config error: ${err}`);
+    }
+    for (const rem of configResult.remediation) {
+      remediation.push(rem);
+    }
+  }
+  for (const w of configResult.warnings) {
+    warnings.push(`Config warning: ${w}`);
+  }
+
+  if (!cli.available) {
+    remediation.push("Install ATF CLI: npm install -g @trucore/atf");
+  }
+  if (cfg?.prefer === "api" && !cfg?.atfBaseUrl) {
+    remediation.push(
+      "Set atfBaseUrl in plugin config (e.g. 'https://api.trucore.xyz').",
+    );
+  }
+  if (cfg?.prefer === "api" && cfg?.atfBaseUrl && !api.available) {
+    remediation.push(
+      `Check ATF API at ${cfg.atfBaseUrl}/health — currently unreachable.`,
+    );
+  }
+  if (toolsMissing.length > 0) {
+    warnings.push(
+      `Missing tools: ${toolsMissing.join(", ")}. ` +
+      "Ensure the plugin loaded without errors.",
+    );
+    remediation.push(
+      "Restart the OpenClaw gateway and check logs for [trucore-atf] warnings.",
+    );
+  }
+
+  // 6. Determine overall status
+  let status = DOCTOR_STATUS.OK;
+  if (!configResult.valid) {
+    status = DOCTOR_STATUS.MISCONFIGURED;
+  } else if (backend.status === BACKEND_STATUS.UNAVAILABLE) {
+    status = DOCTOR_STATUS.UNAVAILABLE;
+  } else if (backend.status === BACKEND_STATUS.MISCONFIGURED) {
+    status = DOCTOR_STATUS.MISCONFIGURED;
+  } else if (
+    backend.status === BACKEND_STATUS.DEGRADED ||
+    toolsMissing.length > 0
+  ) {
+    status = DOCTOR_STATUS.DEGRADED;
+  }
+
+  // 7. Add "what to do next" if healthy
+  if (status === DOCTOR_STATUS.OK && remediation.length === 0) {
+    remediation.push("Integration is healthy. No action required.");
+  }
+
+  return {
+    plugin_id: PLUGIN_ID,
+    plugin_version: PLUGIN_VERSION,
+    plugin_loaded: true,
+    lifecycle_exports_present: lifecyclePresent,
+    cli_available: cli.available,
+    api_available: api.available,
+    preferred_backend: backend.preferred_backend,
+    effective_backend: backend.effective_backend,
+    fallback_occurred: backend.fallback_occurred,
+    fallback_reason: backend.fallback_reason,
+    native_tools_expected: [...EXPECTED_TOOLS],
+    native_tools_available: toolsAvailable,
+    native_tools_missing: toolsMissing,
+    status,
+    warnings,
+    remediation,
+    config_validation: {
+      valid: configResult.valid,
+      errors: configResult.errors,
+      warnings: configResult.warnings,
+      unsupported_keys: configResult.unsupported_keys,
+    },
+  };
+}