@useorgx/openclaw-plugin 0.3.0 → 0.3.1

package/dist/index.js

@@ -18,9 +18,63 @@ import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
 import { clearPersistedApiKey, loadAuthStore, resolveInstallationId, saveAuthStore, } from "./auth-store.js";
-import { appendToOutbox, readOutbox, replaceOutbox } from "./outbox.js";
+import { clearPersistedSnapshot, readPersistedSnapshot, writePersistedSnapshot, } from "./snapshot-store.js";
+import { appendToOutbox, readOutbox, readOutboxSummary, replaceOutbox, } from "./outbox.js";
 export { OrgXClient } from "./api.js";
+const DEFAULT_BASE_URL = "https://www.useorgx.com";
 const DEFAULT_DOCS_URL = "https://orgx.mintlify.site/guides/openclaw-plugin-setup";
+function isUserScopedApiKey(apiKey) {
+    return apiKey.trim().toLowerCase().startsWith("oxk_");
+}
+function resolveRuntimeUserId(apiKey, candidates) {
+    if (isUserScopedApiKey(apiKey)) {
+        return "";
+    }
+    for (const candidate of candidates) {
+        if (typeof candidate === "string") {
+            const trimmed = candidate.trim();
+            if (trimmed.length > 0)
+                return trimmed;
+        }
+    }
+    return "";
+}
+function normalizeHost(value) {
+    return value.trim().toLowerCase().replace(/^\[|\]$/g, "");
+}
+function isLoopbackHostname(hostname) {
+    const normalized = normalizeHost(hostname);
+    return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1";
+}
+function normalizeBaseUrl(raw) {
+    const candidate = raw?.trim() ?? "";
+    if (!candidate) {
+        return DEFAULT_BASE_URL;
+    }
+    try {
+        const parsed = new URL(candidate);
+        if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+            return DEFAULT_BASE_URL;
+        }
+        // Do not allow credential-bearing URLs.
+        if (parsed.username || parsed.password) {
+            return DEFAULT_BASE_URL;
+        }
+        // Plain HTTP is only allowed for local loopback development.
+        if (parsed.protocol === "http:" && !isLoopbackHostname(parsed.hostname)) {
+            return DEFAULT_BASE_URL;
+        }
+        parsed.search = "";
+        parsed.hash = "";
+        const normalizedPath = parsed.pathname.replace(/\/+$/, "");
+        parsed.pathname = normalizedPath;
+        const normalized = parsed.toString().replace(/\/+$/, "");
+        return normalized.length > 0 ? normalized : DEFAULT_BASE_URL;
+    }
+    catch {
+        return DEFAULT_BASE_URL;
+    }
+}
 function readLegacyEnvValue(keyPattern) {
     try {
         const envPath = join(homedir(), "Code", "orgx", "orgx", ".env.local");
@@ -72,7 +126,10 @@ function resolveApiKey(pluginConf, persistedApiKey) {
     if (openclaw.apiKey) {
         return { value: openclaw.apiKey, source: "openclaw-config-file" };
     }
-    const legacy = readLegacyEnvValue(/^ORGX_(?:API_KEY|SERVICE_KEY)=["']?([^"'\n]+)["']?$/m);
+    // For local dev convenience we read `ORGX_API_KEY` from `~/Code/orgx/orgx/.env.local`.
+    // Do not auto-consume `ORGX_SERVICE_KEY` because service keys often require `X-Orgx-User-Id`,
+    // and the dashboard/client flows are intended to run on user-scoped keys (`oxk_...`).
+    const legacy = readLegacyEnvValue(/^ORGX_API_KEY=["']?([^"'\n]+)["']?$/m);
     if (legacy) {
         return { value: legacy, source: "legacy-dev" };
     }
@@ -92,8 +149,14 @@ function resolvePluginVersion() {
 }
 function resolveDocsUrl(baseUrl) {
     const normalized = baseUrl.replace(/\/+$/, "");
-    if (normalized.includes("localhost") || normalized.includes("127.0.0.1")) {
-        return `${normalized}/docs/mintlify/guides/openclaw-plugin-setup`;
+    try {
+        const parsed = new URL(normalized);
+        if (isLoopbackHostname(parsed.hostname)) {
+            return `${normalized}/docs/mintlify/guides/openclaw-plugin-setup`;
+        }
+    }
+    catch {
+        return DEFAULT_DOCS_URL;
     }
     return DEFAULT_DOCS_URL;
 }
@@ -103,15 +166,14 @@ function resolveConfig(api, input) {
     const apiKeyResolution = resolveApiKey(pluginConf, input.persistedApiKey);
     const apiKey = apiKeyResolution.value;
     // Resolve user ID for X-Orgx-User-Id header
-    const userId = pluginConf.userId?.trim() ||
-        process.env.ORGX_USER_ID?.trim() ||
-        input.persistedUserId?.trim() ||
-        openclaw.userId ||
-        readLegacyEnvValue(/^ORGX_USER_ID=["']?([^"'\n]+)["']?$/m);
-    const baseUrl = pluginConf.baseUrl ||
-        process.env.ORGX_BASE_URL ||
-        openclaw.baseUrl ||
-        "https://www.useorgx.com";
+    const userId = resolveRuntimeUserId(apiKey, [
+        pluginConf.userId,
+        process.env.ORGX_USER_ID,
+        input.persistedUserId,
+        openclaw.userId,
+        readLegacyEnvValue(/^ORGX_USER_ID=["']?([^"'\n]+)["']?$/m),
+    ]);
+    const baseUrl = normalizeBaseUrl(pluginConf.baseUrl || process.env.ORGX_BASE_URL || openclaw.baseUrl || DEFAULT_BASE_URL);
     return {
         apiKey,
         userId,
@@ -168,6 +230,22 @@ function formatSnapshot(snap) {
         lines.push(`_Last synced: ${snap.syncedAt}_`);
     return lines.join("\n");
 }
+function apiKeySourceLabel(source) {
+    switch (source) {
+        case "config":
+            return "Plugin Config";
+        case "environment":
+            return "Environment";
+        case "persisted":
+            return "Persisted Store";
+        case "openclaw-config-file":
+            return "OpenClaw Config";
+        case "legacy-dev":
+            return "Legacy Dev Env";
+        default:
+            return "Not configured";
+    }
+}
 function pickNonEmptyString(...values) {
     for (const value of values) {
         if (typeof value !== "string")
@@ -206,6 +284,24 @@ function toReportingPhase(phase, progressPct) {
 // =============================================================================
 let cachedSnapshot = null;
 let lastSnapshotAt = 0;
+function updateCachedSnapshot(snapshot) {
+    cachedSnapshot = snapshot;
+    lastSnapshotAt = Date.now();
+    try {
+        writePersistedSnapshot(snapshot);
+    }
+    catch {
+        // best effort
+    }
+}
+function hydrateCachedSnapshot() {
+    const persisted = readPersistedSnapshot();
+    if (!persisted?.snapshot)
+        return;
+    cachedSnapshot = persisted.snapshot;
+    const ts = Date.parse(persisted.updatedAt);
+    lastSnapshotAt = Number.isFinite(ts) ? ts : 0;
+}
 // =============================================================================
 // PLUGIN ENTRY — DEFAULT EXPORT
 // =============================================================================
@@ -230,6 +326,7 @@ export default function register(api) {
     if (!config.apiKey) {
         api.log?.warn?.("[orgx] No API key. Set plugins.entries.orgx.config.apiKey, ORGX_API_KEY env, or ~/Code/orgx/orgx/.env.local");
     }
+    hydrateCachedSnapshot();
     const client = new OrgXClient(config.apiKey, config.baseUrl, config.userId);
     let onboardingState = {
         status: config.apiKey ? "connected" : "idle",
@@ -355,9 +452,7 @@ export default function register(api) {
         const nextApiKey = input.apiKey.trim();
         config.apiKey = nextApiKey;
         config.apiKeySource = "persisted";
-        if (typeof input.userId === "string" && input.userId.trim().length > 0) {
-            config.userId = input.userId.trim();
-        }
+        config.userId = resolveRuntimeUserId(nextApiKey, [input.userId, config.userId]);
         client.setCredentials({
             apiKey: config.apiKey,
             userId: config.userId,
@@ -385,6 +480,154 @@ export default function register(api) {
     let syncInFlight = null;
     let syncServiceRunning = false;
     const outboxQueues = ["progress", "decisions", "artifacts"];
+    let outboxReplayState = {
+        status: "idle",
+        lastReplayAttemptAt: null,
+        lastReplaySuccessAt: null,
+        lastReplayFailureAt: null,
+        lastReplayError: null,
+    };
+    async function buildHealthReport(input = {}) {
+        const generatedAt = new Date().toISOString();
+        const probeRemote = input.probeRemote === true;
+        const outbox = await readOutboxSummary();
+        const checks = [];
+        const hasApiKey = Boolean(config.apiKey);
+        if (hasApiKey) {
+            checks.push({
+                id: "api_key",
+                status: "pass",
+                message: `API key detected (${apiKeySourceLabel(config.apiKeySource)}).`,
+            });
+        }
+        else {
+            checks.push({
+                id: "api_key",
+                status: "fail",
+                message: "API key missing. Connect OrgX in onboarding or set ORGX_API_KEY.",
+            });
+        }
+        if (syncServiceRunning) {
+            checks.push({
+                id: "sync_service",
+                status: "pass",
+                message: "Background sync service is running.",
+            });
+        }
+        else {
+            checks.push({
+                id: "sync_service",
+                status: "warn",
+                message: "Background sync service is not running.",
+            });
+        }
+        if (outbox.pendingTotal > 0) {
+            checks.push({
+                id: "outbox",
+                status: "warn",
+                message: `Outbox has ${outbox.pendingTotal} queued event(s).`,
+            });
+        }
+        else {
+            checks.push({
+                id: "outbox",
+                status: "pass",
+                message: "Outbox is empty.",
+            });
+        }
+        let remoteReachable = null;
+        let remoteLatencyMs = null;
+        let remoteError = null;
+        if (probeRemote) {
+            if (!hasApiKey) {
+                checks.push({
+                    id: "remote_probe",
+                    status: "warn",
+                    message: "Skipped remote probe because API key is missing.",
+                });
+            }
+            else {
+                const startedAt = Date.now();
+                try {
+                    await client.getOrgSnapshot();
+                    remoteReachable = true;
+                    remoteLatencyMs = Date.now() - startedAt;
+                    checks.push({
+                        id: "remote_probe",
+                        status: "pass",
+                        message: `OrgX API reachable (${remoteLatencyMs}ms).`,
+                    });
+                }
+                catch (err) {
+                    remoteReachable = false;
+                    remoteLatencyMs = Date.now() - startedAt;
+                    remoteError = toErrorMessage(err);
+                    checks.push({
+                        id: "remote_probe",
+                        status: "fail",
+                        message: `OrgX API probe failed: ${remoteError}`,
+                    });
+                }
+            }
+        }
+        if (onboardingState.status === "error") {
+            checks.push({
+                id: "onboarding_state",
+                status: "warn",
+                message: onboardingState.lastError
+                    ? `Onboarding reports an error: ${onboardingState.lastError}`
+                    : "Onboarding reports an error state.",
+            });
+        }
+        const hasFail = checks.some((check) => check.status === "fail");
+        const hasWarn = checks.some((check) => check.status === "warn");
+        const status = hasFail
+            ? "error"
+            : hasWarn
+                ? "degraded"
+                : "ok";
+        return {
+            ok: status !== "error",
+            status,
+            generatedAt,
+            checks,
+            plugin: {
+                version: config.pluginVersion,
+                installationId: config.installationId,
+                enabled: config.enabled,
+                dashboardEnabled: config.dashboardEnabled,
+                baseUrl: config.baseUrl,
+            },
+            auth: {
+                hasApiKey,
+                keySource: config.apiKeySource,
+                userIdConfigured: Boolean(config.userId && config.userId.trim().length > 0),
+                onboardingStatus: onboardingState.status,
+            },
+            sync: {
+                serviceRunning: syncServiceRunning,
+                inFlight: syncInFlight !== null,
+                lastSnapshotAt: lastSnapshotAt > 0 ? new Date(lastSnapshotAt).toISOString() : null,
+            },
+            outbox: {
+                pendingTotal: outbox.pendingTotal,
+                pendingByQueue: outbox.pendingByQueue,
+                oldestEventAt: outbox.oldestEventAt,
+                newestEventAt: outbox.newestEventAt,
+                replayStatus: outboxReplayState.status,
+                lastReplayAttemptAt: outboxReplayState.lastReplayAttemptAt,
+                lastReplaySuccessAt: outboxReplayState.lastReplaySuccessAt,
+                lastReplayFailureAt: outboxReplayState.lastReplayFailureAt,
+                lastReplayError: outboxReplayState.lastReplayError,
+            },
+            remote: {
+                enabled: probeRemote,
+                reachable: remoteReachable,
+                latencyMs: remoteLatencyMs,
+                error: remoteError,
+            },
+        };
+    }
     function pickStringField(payload, key) {
         const value = payload[key];
         return typeof value === "string" && value.trim().length > 0
@@ -516,6 +759,15 @@ export default function register(api) {
         }
     }
     async function flushOutboxQueues() {
+        const attemptAt = new Date().toISOString();
+        outboxReplayState = {
+            ...outboxReplayState,
+            status: "running",
+            lastReplayAttemptAt: attemptAt,
+            lastReplayError: null,
+        };
+        let hadReplayFailure = false;
+        let lastReplayError = null;
         for (const queue of outboxQueues) {
             const pending = await readOutbox(queue);
             if (pending.length === 0) {
@@ -527,11 +779,13 @@ export default function register(api) {
                     await replayOutboxEvent(event);
                 }
                 catch (err) {
+                    hadReplayFailure = true;
+                    lastReplayError = toErrorMessage(err);
                     remaining.push(event);
                     api.log?.warn?.("[orgx] Outbox replay failed", {
                         queue,
                         eventId: event.id,
-                        error: toErrorMessage(err),
+                        error: lastReplayError,
                     });
                 }
             }
@@ -545,6 +799,22 @@ export default function register(api) {
                 });
             }
         }
+        if (hadReplayFailure) {
+            outboxReplayState = {
+                ...outboxReplayState,
+                status: "error",
+                lastReplayFailureAt: new Date().toISOString(),
+                lastReplayError,
+            };
+        }
+        else {
+            outboxReplayState = {
+                ...outboxReplayState,
+                status: "success",
+                lastReplaySuccessAt: new Date().toISOString(),
+                lastReplayError: null,
+            };
+        }
     }
     async function doSync() {
         if (syncInFlight) {
@@ -561,8 +831,7 @@ export default function register(api) {
                 return;
             }
             try {
-                cachedSnapshot = await client.getOrgSnapshot();
-                lastSnapshotAt = Date.now();
+                updateCachedSnapshot(await client.getOrgSnapshot());
                 updateOnboardingState({
                     status: "connected",
                     hasApiKey: true,
@@ -760,17 +1029,16 @@ export default function register(api) {
             lastError: null,
             nextAction: "enter_manual_key",
         });
-        const probeClient = new OrgXClient(nextKey, config.baseUrl, input.userId?.trim() || config.userId);
+        const probeClient = new OrgXClient(nextKey, config.baseUrl, resolveRuntimeUserId(nextKey, [input.userId, config.userId]));
         const snapshot = await probeClient.getOrgSnapshot();
         setRuntimeApiKey({
             apiKey: nextKey,
             source: "manual",
-            userId: input.userId?.trim() || null,
+            userId: resolveRuntimeUserId(nextKey, [input.userId, config.userId]) || null,
             workspaceName: onboardingState.workspaceName,
             keyPrefix: null,
         });
-        cachedSnapshot = snapshot;
-        lastSnapshotAt = Date.now();
+        updateCachedSnapshot(snapshot);
         return updateOnboardingState({
             status: "connected",
             hasApiKey: true,
@@ -788,8 +1056,10 @@ export default function register(api) {
         }
         clearPairingState();
         clearPersistedApiKey();
+        clearPersistedSnapshot();
         config.apiKey = "";
-        client.setCredentials({ apiKey: "" });
+        config.userId = "";
+        client.setCredentials({ apiKey: "", userId: "" });
         cachedSnapshot = null;
         lastSnapshotAt = 0;
         return updateOnboardingState({
@@ -1841,6 +2111,58 @@ export default function register(api) {
                 process.exit(1);
             }
         });
+        cmd
+            .command("doctor")
+            .description("Run plugin diagnostics and connectivity checks")
+            .option("--json", "Print the report as JSON")
+            .option("--no-remote", "Skip remote OrgX API reachability probe")
+            .action(async (opts = {}) => {
+            try {
+                const report = await buildHealthReport({
+                    probeRemote: opts.remote !== false,
+                });
+                if (opts.json) {
+                    console.log(JSON.stringify(report, null, 2));
+                    if (!report.ok)
+                        process.exit(1);
+                    return;
+                }
+                console.log("OrgX Doctor");
+                console.log(`  Status: ${report.status.toUpperCase()}`);
+                console.log(`  Plugin: v${report.plugin.version}`);
+                console.log(`  Base URL: ${report.plugin.baseUrl}`);
+                console.log(`  API Key Source: ${apiKeySourceLabel(report.auth.keySource)}`);
+                console.log(`  Outbox Pending: ${report.outbox.pendingTotal}`);
+                console.log("");
+                console.log("Checks:");
+                for (const check of report.checks) {
+                    const prefix = check.status === "pass"
+                        ? "[PASS]"
+                        : check.status === "warn"
+                            ? "[WARN]"
+                            : "[FAIL]";
+                    console.log(`  ${prefix} ${check.message}`);
+                }
+                if (report.remote.enabled) {
+                    if (report.remote.reachable === true) {
+                        console.log(`  Remote probe latency: ${report.remote.latencyMs ?? "?"}ms`);
+                    }
+                    else if (report.remote.reachable === false) {
+                        console.log(`  Remote probe error: ${report.remote.error ?? "Unknown error"}`);
+                    }
+                    else {
+                        console.log("  Remote probe: skipped");
+                    }
+                }
+                if (!report.ok) {
+                    process.exit(1);
+                }
+            }
+            catch (err) {
+                console.error(`Doctor failed: ${err instanceof Error ? err.message : err}`);
+                process.exit(1);
+            }
+        });
     }, { commands: ["orgx"] });
     // ---------------------------------------------------------------------------
     // 4. HTTP Handler — Dashboard + API proxy
@@ -1851,6 +2173,8 @@ export default function register(api) {
         getStatus: getPairingStatus,
         submitManualKey,
         disconnect: disconnectOnboarding,
+    }, {
+        getHealth: async (input = {}) => buildHealthReport({ probeRemote: input.probeRemote === true }),
     });
     api.registerHttpHandler(httpHandler);
     api.log?.info?.("[orgx] Plugin registered", {