clinkx 1.1.1 → 1.2.0

package/scripts/provider-doctor-core.mjs

@@ -0,0 +1,380 @@
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { probeProvider } from "./provider-doctor-probe.mjs";
+
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const VERSION_TIMEOUT_MS = 10_000;
+const MAX_TEXT = 200;
+const MAX_CAPTURE = 4096;
+const MIN_SCRUB_LENGTH = 6;
+const BASELINE_ENV = new Set(["PATH", "HOME", "USER", "LANG", "TMPDIR"]);
+
+export class DoctorInputError extends Error {}
+
+async function loadModules(withProbe) {
+  const dist = (path) => import(pathToFileURL(join(PACKAGE_ROOT, path)).href);
+  const [registry, env, redaction, workflowsConfig, resolver, diagnostics, handler] = await Promise.all([
+    dist("dist/registry.js"),
+    dist("dist/env.js"),
+    dist("dist/elaris/redact.js"),
+    dist("clinkx-workflows/dist/config.js"),
+    dist("clinkx-workflows/dist/context-mode-resolver.js"),
+    dist("dist/context-builder/diagnostics.js"),
+    withProbe ? dist("dist/handler.js") : Promise.resolve(undefined),
+  ]);
+  return {
+    AdapterRegistry: registry.AdapterRegistry,
+    buildEnv: env.buildEnv,
+    redactSecrets: env.redactSecrets,
+    redactCredentials: (text) => redaction.redactWithOptions(text, {}),
+    preflightEnabled: () => process.env["CLINKX_WORKFLOWS_CONTEXT_PREFLIGHT_ENABLED"]?.trim().toLowerCase() !== "false",
+    getClinkxHome: workflowsConfig.getClinkxHome,
+    getChildConfigPath: workflowsConfig.getChildConfigPath,
+    getDefaultCurator: workflowsConfig.getWorkflowsContextDefaultCurator,
+    getContextDefault: workflowsConfig.getWorkflowsContextDefault,
+    defaultFullDelegateProviders: resolver.defaultFullDelegateProviders,
+    sanitizeDiagnosticText: diagnostics.sanitizeDiagnosticText,
+    handleClink: handler?.handleClink,
+  };
+}
+
+function createCleaner(m) {
+  const hostSecrets = Object.entries(m.redactSecrets({ ...process.env }))
+    .filter(([, value]) => value === "[REDACTED]")
+    .map(([key]) => process.env[key] ?? "");
+
+  return (text, adapter) => {
+    const values = new Set(hostSecrets);
+    if (adapter !== undefined) {
+      for (const [key, value] of Object.entries(m.buildEnv(adapter))) {
+        if (!BASELINE_ENV.has(key)) values.add(value);
+      }
+    }
+    let scrubbed = String(text);
+    for (const value of [...values].filter((v) => v.length >= MIN_SCRUB_LENGTH).sort((a, b) => b.length - a.length)) {
+      scrubbed = scrubbed.split(value).join("[redacted-env]");
+    }
+    const sanitized = m.sanitizeDiagnosticText(m.redactCredentials(scrubbed));
+    return sanitized.length > MAX_TEXT ? `${sanitized.slice(0, MAX_TEXT - 3)}...` : sanitized;
+  };
+}
+
+function firstLine(text) {
+  return text.split(/\r?\n/).map((line) => line.trim()).find((line) => line !== "") ?? "";
+}
+
+async function cleanupVersionProbe(child) {
+  if (child?.pid === undefined) return true;
+  const target = process.platform === "win32" ? child.pid : -child.pid;
+  child.stdout?.destroy();
+  child.stderr?.destroy();
+  try {
+    process.kill(target, "SIGKILL");
+  } catch (error) {
+    if (error?.code === "ESRCH") return true;
+    return false;
+  }
+  for (let attempt = 0; attempt <= 40; attempt += 1) {
+    try {
+      process.kill(target, 0);
+    } catch (error) {
+      return error?.code === "ESRCH";
+    }
+    if (attempt < 40) await new Promise((resolveWait) => setTimeout(resolveWait, 25));
+  }
+  return false;
+}
+
+function checkExecutable(adapter, m, clean, signal) {
+  signal.throwIfAborted();
+  const command = adapter.backend === "app_server"
+    ? adapter.app_server?.command ?? adapter.command
+    : adapter.command;
+  return new Promise((resolveCheck, rejectCheck) => {
+    let finishing = false;
+    let child;
+    let stdout = "";
+    let stderr = "";
+    const finish = async (result) => {
+      if (finishing) return;
+      finishing = true;
+      clearTimeout(timer);
+      const cleanupOk = await cleanupVersionProbe(child);
+      signal.removeEventListener("abort", abort);
+      if (signal.aborted) {
+        rejectCheck(signal.reason);
+      } else {
+        resolveCheck(cleanupOk ? result : {
+          executable: "ok", version: "unknown", cleanup_failed: true,
+          reason: clean("version probe process cleanup could not be confirmed within 1 s", adapter),
+        });
+      }
+    };
+    const abort = () => { void finish({ executable: "ok", version: "unknown" }); };
+    const missing = (error) => {
+      const why = error?.code === "ENOENT"
+        ? `command "${command}" not found`
+        : error?.code === "EACCES"
+          ? `command "${command}" is not executable`
+          : `command "${command}" could not be spawned (${error?.code ?? "error"})`;
+      return { executable: "missing", version: "unknown", reason: clean(why, adapter) };
+    };
+    const timer = setTimeout(() => { void finish({ executable: "ok", version: "unknown" }); }, VERSION_TIMEOUT_MS);
+    try {
+      child = spawn(command, ["--version"], {
+        shell: false,
+        detached: true,
+        cwd: process.cwd(),
+        env: m.buildEnv(adapter),
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch (error) {
+      void finish(missing(error));
+      return;
+    }
+    signal.addEventListener("abort", abort, { once: true });
+    if (signal.aborted) { abort(); return; }
+    child.stdout.setEncoding("utf8").on("data", (chunk) => {
+      if (stdout.length < MAX_CAPTURE) stdout += chunk.slice(0, MAX_CAPTURE - stdout.length);
+    });
+    child.stderr.setEncoding("utf8").on("data", (chunk) => {
+      if (stderr.length < MAX_CAPTURE) stderr += chunk.slice(0, MAX_CAPTURE - stderr.length);
+    });
+    child.once("error", (error) => { void finish(missing(error)); });
+    child.once("close", (code) => {
+      const raw = code === 0 ? firstLine(stdout) || firstLine(stderr) : "";
+      void finish({ executable: "ok", version: raw === "" ? "unknown" : clean(raw, adapter) });
+    });
+  });
+}
+
+function blankLine(adapter, extra) {
+  return {
+    adapter,
+    backend: null,
+    roles: [],
+    config: "invalid",
+    executable: "not_run",
+    version: "unknown",
+    auth: "not_run",
+    startup_required: [],
+    ...extra,
+  };
+}
+
+async function inspectRegistry(registry, required, probes, m, clean, tag, signal) {
+  const lines = [];
+  const blocked = [];
+  const adapters = registry.getAdapterNames().map((name) => registry.resolveAdapter(name));
+  const checks = await Promise.allSettled(adapters.map((adapter) => checkExecutable(adapter, m, clean, signal)));
+  signal.throwIfAborted();
+  const executables = checks.map((check) => {
+    if (check.status === "rejected") throw check.reason;
+    return check.value;
+  });
+
+  for (const [index, adapter] of adapters.entries()) {
+    signal.throwIfAborted();
+    const need = required.get(adapter.name);
+    const exe = executables[index];
+    const line = {
+      adapter: adapter.name,
+      backend: adapter.backend,
+      roles: Object.keys(adapter.roles).sort(),
+      config: "ok",
+      executable: exe.executable,
+      version: exe.version,
+      auth: "not_run",
+      startup_required: need?.labels ?? [],
+      ...tag,
+    };
+    const reasons = [];
+    if (exe.cleanup_failed) reasons.push(exe.reason);
+    if (need !== undefined) {
+      const startup = `startup ${need.labels.join("+")}`;
+      for (const [role, labels] of need.roles) {
+        if (adapter.roles[role] == null) reasons.push(`startup ${labels.join("+")} requires role "${role}"`);
+      }
+      if (adapter.backend === "app_server") reasons.push(`${startup} cannot use backend app_server`);
+      if (reasons.length > 0) line.config = "invalid";
+      if (exe.executable !== "ok") reasons.push(`${startup} executable missing: ${exe.reason}`);
+    } else if (exe.executable !== "ok") {
+      line.reason = exe.reason;
+    }
+
+    if (probes.includes(adapter.name) && !exe.cleanup_failed) {
+      if (exe.executable !== "ok") {
+        reasons.push("probe requested but the executable is missing");
+      } else if (adapter.roles.default == null) {
+        reasons.push('probe requires role "default", which this adapter does not define');
+      } else {
+        const probe = await probeProvider(adapter, registry, m, clean, { signal });
+        signal.throwIfAborted();
+        line.auth = probe.auth;
+        if (probe.auth !== "ok") reasons.push(`probe failed: ${probe.reason}`);
+      }
+    }
+
+    if (reasons.length > 0) {
+      line.reason = reasons.join("; ");
+      blocked.push({ adapter: adapter.name, reason: line.reason });
+    }
+    lines.push(line);
+  }
+
+  for (const [name, need] of required) {
+    if (adapters.some((adapter) => adapter.name === name)) continue;
+    const reason = `startup ${need.labels.join("+")} adapter is not configured`;
+    lines.push(blankLine(name, { startup_required: need.labels, reason, ...tag }));
+    blocked.push({ adapter: name, reason });
+  }
+  return { lines, blocked };
+}
+
+function configFiles(path) {
+  try {
+    if (!statSync(path).isDirectory()) return [path];
+    return readdirSync(path).filter((file) => file.endsWith(".json")).sort().map((file) => join(path, file));
+  } catch {
+    return [];
+  }
+}
+
+function jsonFilesInDirectory(dir) {
+  if (!existsSync(dir)) return [];
+  try {
+    return readdirSync(dir).filter((file) => file.endsWith(".json")).sort().map((file) => join(dir, file));
+  } catch {
+    return [];
+  }
+}
+
+// Mirrors discoverConfigPaths() in src/registry.ts; a CLINKX_HOME error has already failed AdapterRegistry.load() with its own message.
+function standardConfigFiles(getClinkxHome) {
+  const envPath = process.env["CLINKX_CONFIG_PATH"];
+  if (envPath != null && envPath !== "") return configFiles(envPath);
+  const xdgHome = process.env["XDG_CONFIG_HOME"] ?? join(homedir(), ".config");
+  let homeTier = [];
+  try {
+    homeTier = [join(getClinkxHome(), "adapters")];
+  } catch {
+    homeTier = [];
+  }
+  return [...homeTier, join(xdgHome, "clinkx", "adapters"), join(PACKAGE_ROOT, "conf", "adapters")]
+    .flatMap(jsonFilesInDirectory);
+}
+
+function jsonErrorLocation(message, raw) {
+  const lineColumn = /line (\d+) column (\d+)/.exec(message);
+  if (lineColumn !== null) return ` at ${lineColumn[1]}:${lineColumn[2]}`;
+  const position = /at position (\d+)/.exec(message);
+  if (position === null) return "";
+  const before = raw.slice(0, Number(position[1]));
+  return ` at ${before.split("\n").length}:${before.length - before.lastIndexOf("\n")}`;
+}
+
+// V8's JSON.parse message quotes the text around the error, which can be part of a secret value.
+function describeLoadError(error, files) {
+  if (!(error instanceof SyntaxError)) return error instanceof Error ? error.message : String(error);
+  for (const file of files) {
+    let raw = "";
+    try {
+      raw = readFileSync(file, "utf8");
+      JSON.parse(raw);
+    } catch (parseError) {
+      if (parseError instanceof SyntaxError) {
+        return `JSON syntax error in ${basename(file)}${jsonErrorLocation(parseError.message, raw)}`;
+      }
+    }
+  }
+  return "JSON syntax error in an adapter config file";
+}
+
+export async function runDoctor(probes, signal) {
+  signal.throwIfAborted();
+  if (!Array.isArray(probes) || probes.some((name) => typeof name !== "string" || name.trim() === "" || name !== name.trim()) || new Set(probes).size !== probes.length) {
+    throw new DoctorInputError("probes must be an array of unique nonempty adapter names");
+  }
+  const m = await loadModules(probes.length > 0);
+  signal.throwIfAborted();
+  const clean = createCleaner(m);
+  const lines = [];
+  const blocked = [];
+  const fail = (adapter, raw, extra = {}) => {
+    const reason = clean(raw);
+    lines.push(blankLine(adapter, { reason, ...extra }));
+    blocked.push({ adapter, reason });
+  };
+
+  let standard;
+  try {
+    standard = m.AdapterRegistry.load();
+  } catch (error) {
+    fail(null, `adapter registry failed to load: ${describeLoadError(error, standardConfigFiles(m.getClinkxHome))}`);
+  }
+
+  const childPath = m.getChildConfigPath();
+  let child;
+  if (childPath !== undefined) {
+    try {
+      child = m.AdapterRegistry.loadFromPath(childPath);
+    } catch (error) {
+      fail(null, `CLINKX_WORKFLOWS_CHILD_CONFIG_PATH registry failed to load: ${describeLoadError(error, configFiles(childPath))}`, { registry: "workflow_child" });
+    }
+  }
+
+  if (standard !== undefined) {
+    for (const name of probes) {
+      let adapter;
+      try {
+        adapter = standard.resolveAdapter(name);
+      } catch {
+        throw new DoctorInputError(`probe ${name}: no such adapter (available: ${standard.getAdapterNames().join(", ") || "none"})`);
+      }
+      if (adapter.backend === "app_server") {
+        throw new DoctorInputError(`probe ${name}: app_server adapters cannot be probed through the clink pipeline`);
+      }
+    }
+  }
+
+  const required = new Map();
+  if (m.preflightEnabled()) {
+    try {
+      m.getContextDefault();
+      for (const provider of m.defaultFullDelegateProviders(m.getDefaultCurator())) {
+        const entry = required.get(provider.cli_name) ?? { labels: [], roles: new Map() };
+        entry.labels.push(provider.label);
+        entry.roles.set(provider.role, [...(entry.roles.get(provider.role) ?? []), provider.label]);
+        required.set(provider.cli_name, entry);
+      }
+    } catch (error) {
+      fail(null, error instanceof Error ? error.message : String(error));
+    }
+  }
+
+  const contextRegistry = childPath === undefined ? standard : child;
+  if (standard !== undefined) {
+    const result = await inspectRegistry(
+      standard,
+      contextRegistry === standard ? required : new Map(),
+      probes,
+      m,
+      clean,
+      {},
+      signal,
+    );
+    lines.push(...result.lines);
+    blocked.push(...result.blocked);
+  }
+  if (child !== undefined) {
+    const result = await inspectRegistry(child, required, [], m, clean, { registry: "workflow_child" }, signal);
+    lines.push(...result.lines);
+    blocked.push(...result.blocked);
+  }
+
+  signal.throwIfAborted();
+  return { version: 1, adapters: lines, verdict: blocked.length === 0 ? "ready" : "blocked", blocked };
+}

package/scripts/provider-doctor-probe.mjs

@@ -0,0 +1,34 @@
+const PROBE_TIMEOUT_MS = 120_000;
+
+export async function probeProvider(adapter, registry, m, clean, { signal, deadlineMs = PROBE_TIMEOUT_MS }) {
+  const deadline = new AbortController();
+  const timer = setTimeout(() => deadline.abort(new DOMException("Probe deadline exceeded", "TimeoutError")), deadlineMs);
+  const probeSignal = AbortSignal.any([signal, deadline.signal]);
+  const timedOut = () => ({ auth: "failed", reason: `probe exceeded ${deadlineMs / 1_000} s deadline` });
+  try {
+    const result = await m.handleClink(
+      { prompt: "Reply with OK", cli_name: adapter.name, role: "default", timeout_seconds: PROBE_TIMEOUT_MS / 1_000, debug: true },
+      { registry, signal: probeSignal },
+    );
+    if (deadline.signal.aborted) return timedOut();
+    const text = result.content[0]?.text ?? "";
+    if (result.isError === true) return { auth: "failed", reason: clean(text, adapter) };
+    // Consume only host completion/provenance fields; never publish the debug block.
+    let completion;
+    try { completion = JSON.parse(result.content.at(-1)?.text ?? "")._debug; } catch {}
+    const validatedResultFile = completion?.parse_source === "result_contract" && completion?.result_contract_status === "ok";
+    if (completion?.exit_code !== 0 || completion?.termination_reason !== "none"
+      || (!(completion?.stdout_bytes > 0) && !validatedResultFile) || typeof completion?.parse_source !== "string"
+      || completion.parse_source === "stderr_fallback") {
+      return { auth: "failed", reason: "probe did not produce successful result evidence" };
+    }
+    if (text.trim() === "") return { auth: "failed", reason: "probe returned an empty response" };
+    if (text.trim() !== "OK") return { auth: "failed", reason: "probe did not return exactly OK" };
+    return { auth: "ok" };
+  } catch (error) {
+    if (deadline.signal.aborted) return timedOut();
+    return { auth: "failed", reason: clean(error instanceof Error ? error.message : String(error), adapter) };
+  } finally {
+    clearTimeout(timer);
+  }
+}