@tpsdev-ai/flair 0.15.0 → 0.16.0

package/dist/install/clients.js

@@ -5,9 +5,28 @@
 //   - detect(): boolean - returns true if client is installed
 //   - wire(options: { agentId: string; flairUrl: string }): { ok: boolean; message: string }
 //
+// Wiring contract (FIX 4 — onboarding dogfood round 1):
+//   "wired" MUST mean a config file was actually written. A wire function returns
+//   { ok: true } ONLY when it merged the Flair MCP server into the client's real
+//   config file. If it cannot (unknown path, write error), it returns
+//   { ok: false } with the correct per-OS snippet to paste — never a vague
+//   "manual wiring required" while elsewhere the run claims the client is wired.
+//   All paths are resolved cross-platform (Linux included) via standard
+//   per-client locations under $HOME / $XDG_CONFIG_HOME.
 // ---- Detection helpers ----------------------------------------------------------
 import { spawnSync } from "node:child_process";
-import { accessSync, constants } from "node:fs";
+import { accessSync, constants, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/**
+ * Resolve the user's home dir. Prefer the live HOME/USERPROFILE env over
+ * os.homedir(), which caches the value at process start and so ignores a
+ * runtime HOME override — same convention as src/cli.ts ("so tests can
+ * override"). Production behavior is unchanged (HOME is set on every OS).
+ */
+function resolveHome() {
+    return process.env.HOME || process.env.USERPROFILE || homedir();
+}
 /**
  * Check if a command exists in PATH (cross-platform alternative to `which`).
  * Does not spawn a child process — pure filesystem check.
@@ -85,94 +104,126 @@ function cursorDetect() {
         return false;
     }
 }
-// ---- Internal wiring functions --------------------------------------------------
-function _wireClaudeCode(env) {
+// ---- Shared config shapes -------------------------------------------------------
+/** The standard MCP stdio server entry every client (except Codex TOML) uses. */
+function flairMcpEntry(env) {
     return {
-        ok: false,
-        message: `Manual wiring required for Claude Code:\n` +
-            `1. Locate Claude Code's settings file (usually ~/Library/Application Support/Claude/settings.json on macOS or %APPDATA%/Claude/settings.json on Windows)\n` +
-            `2. Add or update the "mcpServers" section:\n` +
-            `   {\n` +
-            `     "mcpServers": {\n` +
-            `       "flair": {\n` +
-            `         "command": "npx",\n` +
-            `         "args": ["-y", "@tpsdev-ai/flair-mcp"],\n` +
-            `         "env": {\n` +
-            `           "FLAIR_AGENT_ID": "${env.FLAIR_AGENT_ID}",\n` +
-            `           "FLAIR_URL": "${env.FLAIR_URL}"\n` +
-            `         }\n` +
-            `       }\n` +
-            `     }\n` +
-            `   }\n` +
-            `3. Restart Claude Code\n` +
-            `Note: This is a manual step - the Flair CLI cannot automatically modify Claude Code's settings due to security restrictions.`,
+        command: "npx",
+        args: ["-y", "@tpsdev-ai/flair-mcp"],
+        env: { FLAIR_AGENT_ID: env.FLAIR_AGENT_ID, FLAIR_URL: env.FLAIR_URL },
     };
 }
+/** Pretty-printed JSON `mcpServers.flair` snippet for copy-paste fallbacks. */
+function jsonSnippet(env) {
+    return JSON.stringify({ mcpServers: { flair: flairMcpEntry(env) } }, null, 2);
+}
+/** TOML `[mcp_servers.flair]` snippet (Codex format). */
+function tomlSnippet(env) {
+    return [
+        `[mcp_servers.flair]`,
+        `command = "npx"`,
+        `args = ["-y", "@tpsdev-ai/flair-mcp"]`,
+        ``,
+        `[mcp_servers.flair.env]`,
+        `FLAIR_AGENT_ID = "${env.FLAIR_AGENT_ID}"`,
+        `FLAIR_URL = "${env.FLAIR_URL}"`,
+    ].join("\n");
+}
+/**
+ * Merge the Flair MCP server into a JSON config file with an `mcpServers` map.
+ * Creates the file (and parent dir) if absent; preserves existing servers and
+ * any other top-level keys. Returns ok:true only when the file was written.
+ */
+function wireJsonMcp(configPath, label, env) {
+    const home = resolveHome();
+    const display = configPath.startsWith(home) ? "~" + configPath.slice(home.length) : configPath;
+    try {
+        let config = {};
+        if (existsSync(configPath)) {
+            const raw = readFileSync(configPath, "utf-8").trim();
+            if (raw)
+                config = JSON.parse(raw);
+        }
+        config.mcpServers = config.mcpServers || {};
+        const existing = config.mcpServers.flair;
+        if (existing && existing.env?.FLAIR_URL === env.FLAIR_URL && existing.env?.FLAIR_AGENT_ID === env.FLAIR_AGENT_ID) {
+            return { ok: true, message: `${label}: already wired in ${display}` };
+        }
+        config.mcpServers.flair = flairMcpEntry(env);
+        mkdirSync(dirname(configPath), { recursive: true });
+        writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+        return { ok: true, message: `${label}: wired ${display} (restart ${label} to pick it up)` };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            message: `${label}: manual wiring needed (could not write ${display}: ${reason}).\n` +
+                `   Add this to ${display}:\n${indent(jsonSnippet(env))}`,
+        };
+    }
+}
+function indent(s) {
+    return s.split("\n").map((l) => `     ${l}`).join("\n");
+}
+// ---- Per-client config paths (cross-platform, Linux included) --------------------
+/** Cursor: ~/.cursor/mcp.json on every OS. */
+function cursorConfigPath() {
+    return join(resolveHome(), ".cursor", "mcp.json");
+}
+/** Gemini CLI: ~/.gemini/settings.json on every OS. */
+function geminiConfigPath() {
+    return join(resolveHome(), ".gemini", "settings.json");
+}
+/** Codex CLI: ~/.codex/config.toml on every OS. */
+function codexConfigPath() {
+    return join(resolveHome(), ".codex", "config.toml");
+}
+// ---- Internal wiring functions --------------------------------------------------
+//
+// Claude Code wiring lives inline in src/cli.ts (it writes ~/.claude.json, the
+// one client the CLI safely edits, cross-platform). _wireClaudeCode here is the
+// fallback used when something calls the array form; it returns the snippet for
+// ~/.claude.json so the message is unambiguous and correct on every OS.
+function _wireClaudeCode(env) {
+    // The real auto-wire is inline in cli.ts. If reached via the array, point at
+    // the correct cross-platform path (~/.claude.json — same on macOS/Linux/Win)
+    // and give the exact snippet. Never emit macOS-only paths here.
+    return wireJsonMcp(join(resolveHome(), ".claude.json"), "Claude Code", env);
+}
 function _wireCodex(env) {
-    return {
-        ok: false,
-        message: `Manual wiring required for Codex:\n` +
-            `1. Locate Codex's configuration (check ~/.codex/config or similar)\n` +
-            `2. Add the Flair MCP server configuration:\n` +
-            `   {\n` +
-            `     "mcpServers": {\n` +
-            `       "flair": {\n` +
-            `         "command": "npx",\n` +
-            `         "args": ["-y", "@tpsdev-ai/flair-mcp"],\n` +
-            `         "env": {\n` +
-            `           "FLAIR_AGENT_ID": "${env.FLAIR_AGENT_ID}",\n` +
-            `           "FLAIR_URL": "${env.FLAIR_URL}"\n` +
-            `         }\n` +
-            `       }\n` +
-            `     }\n` +
-            `   }\n` +
-            `3. Restart Codex\n` +
-            `Note: This is a manual step - the Flair CLI cannot automatically modify Codex's configuration due to security restrictions.`,
-    };
+    // Codex uses TOML with a [mcp_servers.flair] table. We don't carry a TOML
+    // parser, and blind text-appending risks corrupting/duplicating an existing
+    // table — so we only auto-write when the file does NOT yet exist (clean
+    // create), otherwise emit the exact TOML block to paste.
+    const path = codexConfigPath();
+    const display = "~/.codex/config.toml";
+    try {
+        if (existsSync(path)) {
+            return {
+                ok: false,
+                message: `Codex: manual wiring needed — ${display} already exists.\n` +
+                    `   Add this block to ${display}:\n${indent(tomlSnippet(env))}`,
+            };
+        }
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, tomlSnippet(env) + "\n");
+        return { ok: true, message: `Codex: wired ${display} (restart Codex to pick it up)` };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            message: `Codex: manual wiring needed (could not write ${display}: ${reason}).\n` +
+                `   Add this block to ${display}:\n${indent(tomlSnippet(env))}`,
+        };
+    }
 }
 function _wireGemini(env) {
-    return {
-        ok: false,
-        message: `Manual wiring required for Gemini:\n` +
-            `1. Locate Gemini's configuration (check ~/.gemini/config or similar)\n` +
-            `2. Add the Flair MCP server configuration:\n` +
-            `   {\n` +
-            `     "mcpServers": {\n` +
-            `       "flair": {\n` +
-            `         "command": "npx",\n` +
-            `         "args": ["-y", "@tpsdev-ai/flair-mcp"],\n` +
-            `         "env": {\n` +
-            `           "FLAIR_AGENT_ID": "${env.FLAIR_AGENT_ID}",\n` +
-            `           "FLAIR_URL": "${env.FLAIR_URL}"\n` +
-            `         }\n` +
-            `       }\n` +
-            `     }\n` +
-            `   }\n` +
-            `3. Restart Gemini\n` +
-            `Note: This is a manual step - the Flair CLI cannot automatically modify Gemini's configuration due to security restrictions.`,
-    };
+    return wireJsonMcp(geminiConfigPath(), "Gemini", env);
 }
 function _wireCursor(env) {
-    return {
-        ok: false,
-        message: `Manual wiring required for Cursor:\n` +
-            `1. Locate Cursor's settings file (usually ~/.cursor/settings.json)\n` +
-            `2. Add or update the "mcpServers" section:\n` +
-            `   {\n` +
-            `     "mcpServers": {\n` +
-            `       "flair": {\n` +
-            `         "command": "npx",\n` +
-            `         "args": ["-y", "@tpsdev-ai/flair-mcp"],\n` +
-            `         "env": {\n` +
-            `           "FLAIR_AGENT_ID": "${env.FLAIR_AGENT_ID}",\n` +
-            `           "FLAIR_URL": "${env.FLAIR_URL}"\n` +
-            `         }\n` +
-            `       }\n` +
-            `     }\n` +
-            `   }\n` +
-            `3. Restart Cursor\n` +
-            `Note: This is a manual step - the Flair CLI cannot automatically modify Cursor's settings due to security restrictions.`,
-    };
+    return wireJsonMcp(cursorConfigPath(), "Cursor", env);
 }
 // ---- Exported detection & wiring array ------------------------------------------
 export const ALL_CLIENTS = [

package/dist/resources/embeddings-provider.js

@@ -9,6 +9,39 @@
  * the VM linker entirely.
  */
 import { join } from "node:path";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+/**
+ * Resolve the directory the embeddings model lives in / downloads into.
+ *
+ * Resolution order (everything writable, never the read-only package dir):
+ *   1. FLAIR_MODELS_DIR        — explicit operator/docker override.
+ *   2. <ROOTPATH>/models       — Harper's data dir (Flair passes ROOTPATH =
+ *                                ~/.flair/data when it spawns Harper). User-
+ *                                owned and writable even on sudo-global installs.
+ *   3. <cwd>/models            — ONLY if a model already lives there. Backward
+ *                                compat for existing writable installs that
+ *                                downloaded into the package dir before this fix;
+ *                                never used as a download target on fresh installs.
+ *   4. ~/.flair/data/models    — last-resort default when ROOTPATH is unset.
+ *
+ * The chosen dir is always writable, so the embeddings engine can download the
+ * model on first use without hitting EACCES on a root-owned package dir.
+ */
+export function resolveModelsDir() {
+    const override = process.env.FLAIR_MODELS_DIR;
+    if (override)
+        return override;
+    const rootPath = process.env.ROOTPATH;
+    if (rootPath)
+        return join(rootPath, "models");
+    // Backward compat: a prior (writable) install may have the model cached in
+    // the package dir. Reuse it rather than re-downloading — but only if present.
+    const cwdModels = join(process.cwd(), "models");
+    if (existsSync(cwdModels))
+        return cwdModels;
+    return join(homedir(), ".flair", "data", "models");
+}
 let _state = "uninitialized";
 let _initError;
 let _warnedOnce = false;
@@ -29,19 +62,21 @@ async function ensureInit() {
         return;
     }
     catch {
-        // Not initialized — init with modelsDir pointing to where Harper's
-        // plugin loader downloaded the model (process.cwd() is the app dir).
+        // Not initialized — init with modelsDir pointing at a USER-WRITABLE
+        // location. On a sudo/root-owned global install the Flair package dir
+        // (process.cwd()) is root-owned, so a model download into <cwd>/models
+        // fails with EACCES and semantic search silently dies (ops-am0v). The
+        // model — and everything else Flair writes — must live under ~/.flair.
+        //
         // NOTE: import.meta.dirname and __dirname are both undefined in Harper v5's
-        // VM sandbox / worker threads, so we use process.cwd() which points to the
-        // Flair application directory.
+        // VM sandbox / worker threads, so we resolve from env + process.cwd().
         try {
             if (!_hfe) {
                 _hfe = await import("harper-fabric-embeddings");
             }
-            const modelsDir = join(process.cwd(), "models");
+            const modelsDir = resolveModelsDir();
             // Find the native addon binary explicitly to avoid __dirname-dependent
             // discovery in @node-llama-cpp which fails in Harper's VM sandbox.
-            const { existsSync } = await import("node:fs");
             const platforms = ["linux-x64", "mac-arm64-metal", "mac-arm64", "win-x64"];
             let addonPath;
             for (const platform of platforms) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
   "license": "Apache-2.0",
@@ -55,13 +55,13 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@harperfast/harper": "5.0.21",
-    "@types/js-yaml": "^4.0.9",
+    "@harperfast/harper": "5.1.14",
+    "@types/js-yaml": "4.0.9",
     "commander": "14.0.3",
     "harper-fabric-embeddings": "0.2.3",
-    "jose": "^6.2.2",
-    "js-yaml": "^4.1.1",
-    "tar": "^7.5.13",
+    "jose": "6.2.2",
+    "js-yaml": "4.1.1",
+    "tar": "7.5.13",
     "tweetnacl": "1.0.3"
   },
   "optionalDependencies": {
@@ -74,9 +74,9 @@
     "@node-llama-cpp/win-x64": "3.18.1"
   },
   "devDependencies": {
-    "@playwright/test": "^1.59.1",
+    "@playwright/test": "1.59.1",
     "@types/node": "24.11.0",
-    "@types/tar": "^7.0.87",
+    "@types/tar": "7.0.87",
     "bun-types": "1.3.11",
     "typescript": "5.9.3"
   },