Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

feat(cli): wire doctor preflight checks

Yuting Zhong118287c2c6bf
diff --git a/README.md b/README.md
index 366c277c..e3b63b79 100644
--- a/README.md
+++ b/README.md
@@ -39,12 +39,19 @@ The UI opens in your browser. Sidebar is project-scoped; create one to start.
```
notfair-cmo Launch local server + open UI (default)
notfair-cmo start Same as above
-notfair-cmo doctor Verify OpenClaw, gateway, data dir, LLM key
+notfair-cmo doctor Run preflight checks (see below)
notfair-cmo --version
notfair-cmo --help
```
Options on `start`: `--port <n>`, `--no-open`, `--data-dir <path>`.
+Options on `doctor`: `--port <n>`, `--data-dir <path>`.
+
+`doctor` verifies, in order: Node ≥20, OpenClaw on PATH, OpenClaw gateway
+reachable on loopback, an LLM provider configured per `agents.defaults.model`
+(from your OpenClaw config), your data dir is writable, and the preferred port
+is free (probes 3000 → +5). Exits 0 if all checks pass; 1 otherwise, with a
+`Fix:` line under each failure naming the exact command to run.
## What happens when you create a project
diff --git a/bin/cli.mjs b/bin/cli.mjs
index dd664358..cc171e82 100755
--- a/bin/cli.mjs
+++ b/bin/cli.mjs
@@ -4,11 +4,18 @@
// for the CLI surface. The Next.js app itself is built and shipped under .next/standalone.
import { spawn } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, cpSync } from "node:fs";
+import {
+ existsSync,
+ mkdirSync,
+ readFileSync,
+ cpSync,
+ writeFileSync,
+ unlinkSync,
+} from "node:fs";
import { homedir } from "node:os";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
-import { createServer } from "node:net";
+import { createServer, Socket } from "node:net";
import { Command } from "commander";
import open from "open";
@@ -79,57 +86,49 @@ program
program
.command("doctor")
- .description("Verify OpenClaw is installed and reachable.")
- .action(async () => {
- let allOk = true;
-
- process.stdout.write("Checking OpenClaw on PATH... ");
- const oc = await runCheck("openclaw", ["--version"]);
- if (oc.ok) {
- console.log(`ok (${oc.stdout.trim()})`);
- } else {
- console.log("MISSING");
- console.log(" Install: https://docs.openclaw.ai/install");
- allOk = false;
- }
+ .description("Verify this machine is ready to run notfair-cmo.")
+ .option("--data-dir <dir>", "Override data directory", DATA_DIR)
+ .option("-p, --port <port>", "Preferred port for the server", "3000")
+ .action(async (opts) => {
+ const results = [];
- if (oc.ok) {
- process.stdout.write("Checking OpenClaw gateway health... ");
- const health = await runCheck("openclaw", ["health"]);
- if (health.ok) {
- console.log("ok");
- } else {
- console.log("UNREACHABLE");
- console.log(" Start it with: openclaw gateway");
- allOk = false;
- }
+ const node = checkNodeVersion();
+ results.push(node);
+
+ let openclaw;
+ if (node.ok) {
+ openclaw = await checkOpenclawInstalled();
+ } else {
+ openclaw = skipped("OpenClaw installed", "node version too old");
}
+ results.push(openclaw);
- process.stdout.write("Checking data dir is writable... ");
- try {
- ensureDataDir(DATA_DIR);
- console.log(`ok (${DATA_DIR})`);
- } catch (err) {
- console.log("FAILED");
- console.log(` ${err instanceof Error ? err.message : String(err)}`);
- allOk = false;
+ let gateway;
+ if (openclaw.ok) {
+ gateway = await checkOpenclawGateway();
+ } else {
+ gateway = skipped("OpenClaw gateway reachable", "openclaw not installed");
}
+ results.push(gateway);
- process.stdout.write("Checking for an LLM API key... ");
- const hasKey = !!(
- process.env.OPENAI_API_KEY ||
- process.env.ANTHROPIC_API_KEY ||
- process.env.GOOGLE_GENERATIVE_AI_API_KEY
- );
- if (hasKey) {
- console.log("ok");
+ let llm;
+ if (openclaw.ok) {
+ llm = await checkLLMProvider();
} else {
- console.log("MISSING");
- console.log(" Set one of: OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY");
- allOk = false;
+ llm = skipped("LLM provider configured", "openclaw not installed");
}
+ results.push(llm);
+
+ const dataDir = checkDataDir(opts.dataDir);
+ results.push(dataDir);
+
+ const port = await checkPortAvailable(Number.parseInt(opts.port, 10));
+ results.push(port);
- process.exit(allOk ? 0 : 1);
+ printResults(results);
+
+ const failed = results.filter((r) => r.status === "fail").length;
+ process.exit(failed === 0 ? 0 : 1);
});
program
@@ -176,7 +175,7 @@ function ensureDataDir(dir) {
}
}
-function findFreePort(start, maxTries = 10) {
+function findFreePort(start, maxTries = 5) {
return new Promise((resolve, reject) => {
let attempt = 0;
const tryPort = (port) => {
@@ -198,24 +197,317 @@ function findFreePort(start, maxTries = 10) {
});
}
-function runCheck(cmd, args) {
+function runCheck(cmd, args, timeoutMs = 5000) {
return new Promise((resolve) => {
let stdout = "";
let stderr = "";
- const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+ let settled = false;
+ const finish = (value) => {
+ if (settled) return;
+ settled = true;
+ resolve(value);
+ };
+ let child;
+ try {
+ child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+ } catch (err) {
+ finish({ ok: false, stdout: "", stderr: err instanceof Error ? err.message : String(err) });
+ return;
+ }
child.stdout.on("data", (c) => {
stdout += c.toString();
});
child.stderr.on("data", (c) => {
stderr += c.toString();
});
- child.on("error", () => resolve({ ok: false, stdout: "", stderr: "" }));
+ child.on("error", () => finish({ ok: false, stdout: "", stderr: "" }));
child.on("close", (code) => {
- resolve({ ok: code === 0, stdout, stderr });
+ finish({ ok: code === 0, stdout, stderr });
});
setTimeout(() => {
- child.kill("SIGTERM");
- resolve({ ok: false, stdout, stderr: "timed out" });
- }, 5000);
+ if (!settled) {
+ child.kill("SIGTERM");
+ finish({ ok: false, stdout, stderr: "timed out" });
+ }
+ }, timeoutMs).unref?.();
});
}
+
+// --- doctor helpers ---
+
+const COLORS = {
+ reset: "\x1b[0m",
+ green: "\x1b[32m",
+ red: "\x1b[31m",
+ yellow: "\x1b[33m",
+ dim: "\x1b[2m",
+ bold: "\x1b[1m",
+};
+
+function useColor() {
+ if (process.env.NO_COLOR) return false;
+ return process.stdout.isTTY === true;
+}
+
+function color(name, text) {
+ if (!useColor()) return text;
+ return `${COLORS[name]}${text}${COLORS.reset}`;
+}
+
+function pass(name, detail) {
+ return { name, status: "pass", ok: true, detail };
+}
+function fail(name, detail, fix) {
+ return { name, status: "fail", ok: false, detail, fix };
+}
+function skipped(name, detail) {
+ return { name, status: "skip", ok: false, detail };
+}
+
+function checkNodeVersion() {
+ const raw = process.versions.node;
+ const major = Number.parseInt(raw.split(".")[0], 10);
+ if (Number.isNaN(major)) {
+ return fail("Node version", `unrecognized: ${raw}`, "Install Node 20+ (24 recommended) — https://nodejs.org");
+ }
+ if (major < 20) {
+ return fail(
+ "Node version",
+ `v${raw} (need ≥20)`,
+ "Install Node 20+ (24 recommended) — https://nodejs.org, or use nvm: nvm install 24",
+ );
+ }
+ const note = major >= 24 ? "" : " — 24 recommended";
+ return pass("Node version", `v${raw}${note}`);
+}
+
+async function checkOpenclawInstalled() {
+ const r = await runCheck("openclaw", ["--version"]);
+ if (!r.ok) {
+ return fail(
+ "OpenClaw installed",
+ "not on PATH",
+ "Install OpenClaw — https://docs.openclaw.ai/install",
+ );
+ }
+ return pass("OpenClaw installed", r.stdout.trim().split("\n")[0] || "ok");
+}
+
+async function checkOpenclawGateway() {
+ const portR = await runCheck("openclaw", ["config", "get", "gateway.port"]);
+ const port = portR.ok ? Number.parseInt(portR.stdout.trim(), 10) : NaN;
+ const targetPort = Number.isFinite(port) ? port : 18789;
+
+ const health = await runCheck("openclaw", ["health"]);
+ if (health.ok) {
+ return pass("OpenClaw gateway", `reachable on ws://127.0.0.1:${targetPort}`);
+ }
+
+ const wsReachable = await pingLoopback(targetPort);
+ if (wsReachable) {
+ return pass("OpenClaw gateway", `reachable on ws://127.0.0.1:${targetPort}`);
+ }
+ return fail(
+ "OpenClaw gateway",
+ `not reachable on ws://127.0.0.1:${targetPort}`,
+ "Start it with: openclaw gateway",
+ );
+}
+
+function pingLoopback(port) {
+ return new Promise((resolve) => {
+ const socket = new Socket();
+ let done = false;
+ const finish = (ok) => {
+ if (done) return;
+ done = true;
+ try {
+ socket.destroy();
+ } catch {}
+ resolve(ok);
+ };
+ socket.setTimeout(1500);
+ socket.once("connect", () => finish(true));
+ socket.once("timeout", () => finish(false));
+ socket.once("error", () => finish(false));
+ try {
+ socket.connect(port, "127.0.0.1");
+ } catch {
+ finish(false);
+ }
+ });
+}
+
+async function checkLLMProvider() {
+ const modelR = await runCheck("openclaw", ["config", "get", "agents.defaults.model"]);
+ if (!modelR.ok) {
+ return fail(
+ "LLM provider configured",
+ "could not read agents.defaults.model from OpenClaw config",
+ "Configure a default model: openclaw configure --section models",
+ );
+ }
+
+ let chainCfg;
+ try {
+ chainCfg = JSON.parse(modelR.stdout);
+ } catch {
+ return fail(
+ "LLM provider configured",
+ "agents.defaults.model is not valid JSON",
+ "Re-run interactive setup: openclaw configure --section models",
+ );
+ }
+
+ const primary = typeof chainCfg?.primary === "string" ? chainCfg.primary : null;
+ const fallbacks = Array.isArray(chainCfg?.fallbacks)
+ ? chainCfg.fallbacks.filter((m) => typeof m === "string")
+ : [];
+ const chain = [primary, ...fallbacks].filter(Boolean);
+ if (chain.length === 0) {
+ return fail(
+ "LLM provider configured",
+ "no models in agents.defaults.model chain",
+ "Set a primary model: openclaw configure --section models",
+ );
+ }
+
+ const providers = chain.map((m) => m.split("/")[0]).filter(Boolean);
+ const uniqueProviders = Array.from(new Set(providers));
+
+ const providersR = await runCheck("openclaw", ["config", "get", "models.providers"]);
+ let providerCfg = {};
+ if (providersR.ok) {
+ try {
+ providerCfg = JSON.parse(providersR.stdout) ?? {};
+ } catch {
+ providerCfg = {};
+ }
+ }
+
+ const configured = uniqueProviders.filter((p) => {
+ const entry = providerCfg[p];
+ if (entry && typeof entry === "object") {
+ const hasKey =
+ typeof entry.apiKey === "string" && entry.apiKey.length > 0 && !entry.apiKey.startsWith("__");
+ const hasBaseUrl = typeof entry.baseUrl === "string" && entry.baseUrl.length > 0;
+ if (hasKey || hasBaseUrl) return true;
+ }
+ return providerHasEnvKey(p);
+ });
+
+ if (configured.length === 0) {
+ return fail(
+ "LLM provider configured",
+ `none of [${uniqueProviders.join(", ")}] are configured`,
+ `Configure a provider: openclaw configure --section models (chain: ${chain.join(" → ")})`,
+ );
+ }
+
+ const primaryProvider = providers[0];
+ const primaryReady = configured.includes(primaryProvider);
+ const detail = primaryReady
+ ? `${primaryProvider} (primary: ${primary})`
+ : `${configured[0]} (fallback; primary ${primaryProvider} not configured)`;
+ return pass("LLM provider configured", detail);
+}
+
+function providerHasEnvKey(provider) {
+ const candidates = {
+ openai: ["OPENAI_API_KEY"],
+ anthropic: ["ANTHROPIC_API_KEY"],
+ google: ["GOOGLE_GENERATIVE_AI_API_KEY", "GEMINI_API_KEY"],
+ gemini: ["GEMINI_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY"],
+ deepseek: ["DEEPSEEK_API_KEY"],
+ mistral: ["MISTRAL_API_KEY"],
+ groq: ["GROQ_API_KEY"],
+ xai: ["XAI_API_KEY"],
+ };
+ const vars = candidates[provider] ?? [`${provider.toUpperCase()}_API_KEY`];
+ return vars.some((v) => !!process.env[v]);
+}
+
+function checkDataDir(dir) {
+ const overrideEnv = process.env.NOTFAIR_CMO_DATA_DIR;
+ const source = overrideEnv ? "NOTFAIR_CMO_DATA_DIR" : dir === DATA_DIR ? "default" : "--data-dir";
+ try {
+ ensureDataDir(dir);
+ const probe = join(dir, ".doctor-write-probe");
+ writeFileSync(probe, String(Date.now()));
+ unlinkSync(probe);
+ return pass("Data dir writable", `${dir} (${source})`);
+ } catch (err) {
+ const message = err instanceof Error ? err.message : String(err);
+ return fail(
+ "Data dir writable",
+ `${dir}: ${message}`,
+ "Pass --data-dir <path> or set NOTFAIR_CMO_DATA_DIR to a writable directory",
+ );
+ }
+}
+
+async function checkPortAvailable(preferred) {
+ if (!Number.isFinite(preferred) || preferred <= 0) {
+ return fail(
+ "Port available",
+ `invalid preferred port: ${preferred}`,
+ "Pass --port <n> with a valid TCP port (1-65535)",
+ );
+ }
+ try {
+ const port = await findFreePort(preferred, 5);
+ const detail =
+ port === preferred ? `${preferred}` : `${port} (preferred ${preferred} was busy)`;
+ return pass("Port available", detail);
+ } catch {
+ return fail(
+ "Port available",
+ `none free in ${preferred}–${preferred + 5}`,
+ `Pass --port <n> with a free port (ports ${preferred}–${preferred + 5} are all in use)`,
+ );
+ }
+}
+
+function printResults(results) {
+ const nameWidth = Math.max(...results.map((r) => r.name.length));
+ for (const r of results) {
+ const pad = " ".repeat(nameWidth - r.name.length);
+ const icon =
+ r.status === "pass"
+ ? color("green", "✓")
+ : r.status === "fail"
+ ? color("red", "✗")
+ : color("yellow", "-");
+ const label =
+ r.status === "pass"
+ ? color("green", r.name)
+ : r.status === "fail"
+ ? color("red", r.name)
+ : color("yellow", r.name);
+ const detail = r.detail ? ` ${color("dim", r.detail)}` : "";
+ console.log(`${icon} ${label}${pad}${detail}`);
+ if (r.status === "fail" && r.fix) {
+ console.log(` ${color("bold", "Fix:")} ${r.fix}`);
+ }
+ if (r.status === "skip" && r.detail) {
+ // detail already printed above; no extra line
+ }
+ }
+ console.log("");
+ const failed = results.filter((r) => r.status === "fail").length;
+ const skipped = results.filter((r) => r.status === "skip").length;
+ if (failed === 0 && skipped === 0) {
+ console.log(color("green", "All checks passed. You're ready to run notfair-cmo."));
+ } else if (failed === 0) {
+ console.log(
+ color("yellow", `Passed, with ${skipped} check${skipped === 1 ? "" : "s"} skipped.`),
+ );
+ } else {
+ console.log(
+ color(
+ "red",
+ `${failed} check${failed === 1 ? "" : "s"} failed${skipped ? `, ${skipped} skipped` : ""}.`,
+ ),
+ );
+ }
+}