knowledge.js

// knowledge.js – Pythia's runtime knowledge base: known failure signatures and
// their plain-English fixes. /api/diagnose checks here first (instant, free);
// only an unrecognized error spends an AI call, and the AI gets this list as
// context so it diagnoses like we do. Add entries as the field teaches us new
// ways to break; every support incident should end with a line in this file.
export const KNOWLEDGE = [
  { match: /%2520|syntax error in URL/i,
    title: "Table names with spaces hit an encoding mismatch",
    fix: "Servers differ in how many times they decode URLs, and this one got a name encoded the wrong number of times. Pythia detects this and retries with the other encoding automatically - when that works, the sync log says so in plain English. Sync again; if the SAME table still fails the same way, tell us - do not rename anything in FileMaker on Pythia's account." },
  { match: /401|authentication failed|invalid.*credential/i,
    title: "FileMaker rejected the login",
    fix: "The username or password is wrong, or the account is inactive. Check both in Settings under FileMaker connection, then Test connection." },
  { match: /fmodata|privilege|not authorized|403/i,
    title: "The account lacks OData access",
    fix: "In FileMaker, the account's privilege set needs the fmodata extended privilege (and fmrest for the Data API fallback) in this file." },
  { match: /ENOTFOUND|EAI_AGAIN|getaddrinfo/i,
    title: "Server address not found",
    fix: "The server name doesn't resolve. Check the address in Settings (just the host, no https:// prefix) and your network/VPN." },
  { match: /ECONNREFUSED|502|503|OData engine/i,
    title: "OData on your FileMaker Server is not answering",
    fix: "The FileMaker Server machine is up but its OData layer did not respond to this request. Pythia works through the Data API meanwhile and keeps retrying; this usually clears on its own. No restart of anything is needed." },
  { match: /timeout|aborted|ETIMEDOUT/i,
    title: "This request took too long",
    fix: "When one table times out while others sync fine, the table's rows are expensive to serve (usually unstored calculations evaluated per record) - the server itself is up. Pythia shrinks its page size automatically; try the sync again. If EVERY request times out, the server or network is the issue." },
  { match: /rejects \$select|falling back to full-row/i,
    title: "This server can't do column-level pulls",
    fix: "Harmless: Pythia falls back to full-row pulls automatically. Syncs are a bit heavier but correct." },
  { match: /conflicting lock|set lock/i,
    title: "The optimized data file was busy",
    fix: "Two operations hit the local database at once. Pythia queues and retries; if it persists, wait for the current sync to finish." },
  { match: /Runtime Error.*HTML|HTML error page/i,
    title: "The web server returned an error page instead of data",
    fix: "Usually a malformed URL (table name encoding) or the OData engine crashing on this request. Re-run the sync; if one table keeps failing, uncheck it and tell us its name." },
  { match: /no databases visible|No file reachable/i,
    title: "The login works but sees no files",
    fix: "The account must exist in each database file with the fmodata extended privilege. Files without it simply don't appear." },
];

export function kbLookup(text) {
  return KNOWLEDGE.find((k) => k.match.test(String(text))) || null;
}