@tpsdev-ai/flair 0.48.0 → 0.50.0

package/dist/install/clients.js

@@ -1,9 +1,12 @@
 // ─── Client Detection & Wiring ──────────────────────────────────────────────────────
 //
-// Detects locally installed MCP clients and wires them to Flair.
-// Each client has:
-//   - detect(): boolean - returns true if client is installed
-//   - wire(options: { agentId: string; flairUrl: string }): { ok: boolean; message: string }
+// Detects locally installed clients and wires them to Flair. Most are MCP
+// clients (kind: "mcp" — wired via an mcpServers block/TOML table running
+// @tpsdev-ai/flair-mcp); pi is a native-extension host (kind:
+// "native-extension" — wired via pi's own settings.json `packages` key,
+// flair#1342). Each client has:
+//   - detection: `bin` on PATH, optionally widened by a declared detect() override
+//   - wire(env): { 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
@@ -17,7 +20,7 @@
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { mcpServerSpec } from "../lib/mcp-spec.js";
+import { flairCliVersion, isResolvedVersion, mcpServerSpec } from "../lib/mcp-spec.js";
 /**
  * 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
@@ -263,6 +266,282 @@ function geminiConfigPath() {
 function codexConfigPath() {
     return join(resolveHome(), ".codex", "config.toml");
 }
+// ---- pi (native extension — NOT an MCP client) ------------------------------------
+//
+// pi has no MCP client support (packages/pi-flair/README "Design Decision"), so
+// Flair ships @tpsdev-ai/pi-flair as a NATIVE pi extension. Wiring pi therefore
+// means editing pi's OWN settings, not writing an mcpServers block (flair#1342):
+//
+//   ~/.pi/agent/settings.json          (user scope; pi's getSettingsPath() —
+//                                       agent dir overridable via the
+//                                       PI_CODING_AGENT_DIR env var, honored here)
+//   <project>/.pi/settings.json        (project scope)
+//
+// Two settings keys matter, and confusing them is the flair#1346 field failure:
+//
+//   "packages"    — package SOURCES (`npm:`, `git:`, local paths, or
+//                   { source, ...filters } objects). pi parses these through
+//                   parseSource() and AUTO-INSTALLS a missing/mismatched npm
+//                   package at resource collection (package-manager.js
+//                   resolvePackageSources), honoring an exact `@<version>` pin.
+//                   This is where npm:@tpsdev-ai/pi-flair belongs.
+//   "extensions"  — local FILE PATHS only. An `npm:` spec here is treated as a
+//                   path, fails existsSync, and is dropped WITHOUT ERROR — the
+//                   user believes they are wired and pi registers zero tools.
+//                   (Verified against pi 0.84.2's package-manager.js: the
+//                   extensions override list feeds resolvePathFromBase/
+//                   collectFilesFromPaths, never parseSource.)
+//
+// pi-flair reads FLAIR_AGENT_ID / FLAIR_URL / FLAIR_KEY_PATH from the process
+// environment of the pi that loads it — pi settings carry NO per-package env
+// block, so wiring here cannot pin an agent identity the way the MCP clients'
+// env blocks do. Wire messages say so instead of pretending.
+/** The npm package pi loads as its Flair extension. */
+export const PI_FLAIR_PACKAGE = "@tpsdev-ai/pi-flair";
+/**
+ * pi-flair's own DEFAULT_FLAIR_URL (packages/pi-flair/src/index.ts). Duplicated
+ * as a value rather than imported — the CLI does not depend on the pi-flair
+ * workspace package — by the same convention as doctor-client's
+ * FLAIR_CLIENT_DEFAULT_URL; a unit test (pi-client.test.ts) asserts this
+ * literal matches pi-flair's source so the two cannot drift silently.
+ */
+export const PI_FLAIR_DEFAULT_URL = "http://127.0.0.1:19926";
+/**
+ * The `packages` entry a wired pi gets. PINNED for the same reason as
+ * mcpServerSpec (flair#907): pi re-resolves an unpinned npm source to latest
+ * when (re)installing, and pi-flair ships in version lockstep with the CLI.
+ * Falls back to the bare spec when the CLI cannot read its own version — the
+ * same condition and caller-owed warning as mcpServerSpec.
+ */
+export function piFlairSpec(version = flairCliVersion()) {
+    return isResolvedVersion(version)
+        ? `npm:${PI_FLAIR_PACKAGE}@${version}`
+        : `npm:${PI_FLAIR_PACKAGE}`;
+}
+/** pi's agent config dir: $PI_CODING_AGENT_DIR, else ~/.pi/agent (pi config.js). */
+function piAgentDir() {
+    const envDir = process.env.PI_CODING_AGENT_DIR;
+    if (envDir)
+        return envDir;
+    return join(resolveHome(), ".pi", "agent");
+}
+/** pi user-scope settings: <agent dir>/settings.json. */
+export function piSettingsPath() {
+    return join(piAgentDir(), "settings.json");
+}
+/** A pi `packages` array entry is a source string or `{ source, ...filters }`. */
+export function piPackageEntrySource(entry) {
+    if (typeof entry === "string")
+        return entry;
+    if (entry && typeof entry === "object" && typeof entry.source === "string") {
+        return entry.source;
+    }
+    return null;
+}
+/** Does this source string name the pi-flair package as an npm source
+ *  (bare `npm:@tpsdev-ai/pi-flair` or any `npm:@tpsdev-ai/pi-flair@<spec>`)? */
+export function isPiFlairNpmSource(source) {
+    if (typeof source !== "string" || !source.startsWith("npm:"))
+        return false;
+    const spec = source.slice("npm:".length).trim();
+    return spec === PI_FLAIR_PACKAGE || spec.startsWith(`${PI_FLAIR_PACKAGE}@`);
+}
+/** The version text of a pinned pi-flair npm source, or null when bare. */
+export function extractPiFlairPin(source) {
+    if (!isPiFlairNpmSource(source))
+        return null;
+    const spec = source.slice("npm:".length).trim();
+    const version = spec.slice(`${PI_FLAIR_PACKAGE}@`.length);
+    return spec.startsWith(`${PI_FLAIR_PACKAGE}@`) && version ? version : null;
+}
+/**
+ * Does this `extensions` entry point at pi-flair BY PATH (the documented
+ * pre-0.49 workaround: a local path to the installed dist/index.js)? A
+ * substring heuristic on the package/directory name — the entry is user-
+ * written free text, so this is deliberately loose in the direction of
+ * REPORTING (doctor names the entry it matched); it never gates anything
+ * destructive.
+ */
+export function isPiFlairExtensionPath(entry) {
+    if (typeof entry !== "string" || entry.startsWith("npm:") || entry.startsWith("git:"))
+        return false;
+    return entry.includes("pi-flair");
+}
+export function scanPiSettings(raw) {
+    const empty = { parsed: false, pinnedVersion: null, extensionFilePaths: [], misconfiguredNpmUnderExtensions: [] };
+    if (!raw || !raw.trim())
+        return empty;
+    let config;
+    try {
+        config = JSON.parse(raw);
+    }
+    catch {
+        return empty;
+    }
+    if (!config || typeof config !== "object" || Array.isArray(config))
+        return empty;
+    const cfg = config;
+    let packagesSpec;
+    let pinnedVersion = null;
+    if (Array.isArray(cfg.packages)) {
+        for (const entry of cfg.packages) {
+            const source = piPackageEntrySource(entry);
+            if (source && isPiFlairNpmSource(source)) {
+                packagesSpec = source;
+                pinnedVersion = extractPiFlairPin(source);
+                break;
+            }
+        }
+    }
+    const extensionFilePaths = [];
+    const misconfiguredNpmUnderExtensions = [];
+    if (Array.isArray(cfg.extensions)) {
+        for (const entry of cfg.extensions) {
+            if (typeof entry !== "string")
+                continue;
+            if (isPiFlairNpmSource(entry))
+                misconfiguredNpmUnderExtensions.push(entry);
+            else if (isPiFlairExtensionPath(entry))
+                extensionFilePaths.push(entry);
+        }
+    }
+    return { parsed: true, packagesSpec, pinnedVersion, extensionFilePaths, misconfiguredNpmUnderExtensions };
+}
+/**
+ * Resolve a pi `extensions` path entry the way pi's loader will: `~/` against
+ * the home dir, a relative path against the settings file's own base dir, an
+ * absolute path as-is. `baseDir` is the directory pi treats as the scope's
+ * base (user scope: the agent dir).
+ */
+export function resolvePiExtensionPath(entry, homeDir, baseDir) {
+    if (entry.startsWith("~/") || entry === "~")
+        return join(homeDir, entry.slice(1));
+    if (entry.startsWith("/"))
+        return entry;
+    return join(baseDir, entry);
+}
+/** Pretty-printed minimal settings snippet for copy-paste fallbacks. */
+function piJsonSnippet() {
+    return JSON.stringify({ packages: [piFlairSpec()] }, null, 2);
+}
+/**
+ * Wire pi by editing ~/.pi/agent/settings.json `packages` (flair#1342) — the
+ * same merge/idempotence/preservation contract as wireJsonMcp: sibling keys
+ * and entries survive byte-identical, a current entry is a no-op, a stale pin
+ * is refreshed, and ok:true means the file was actually written (or already
+ * correct). Two pi-specific rules on top:
+ *
+ *   • an `npm:` pi-flair spec under `extensions` is MOVED to `packages` — that
+ *     misplacement is silently ignored by pi (flair#1346), so leaving it while
+ *     adding a packages entry would preserve a decoy;
+ *   • an existing FILE-PATH `extensions` entry that resolves to a real file is
+ *     honored as already-wired (the documented pre-0.49 workaround) — the user
+ *     may deliberately be running a local build, so it is reported, not
+ *     rewritten.
+ *
+ * `env` is used for the launch-environment hint only: pi settings have no
+ * per-package env block, so FLAIR_AGENT_ID/FLAIR_URL must be exported by
+ * whatever shell launches pi — the message says so rather than implying the
+ * wiring carried them.
+ */
+function _wirePi(env) {
+    const path = piSettingsPath();
+    const home = resolveHome();
+    const display = path.startsWith(home) ? "~" + path.slice(home.length) : path;
+    const spec = piFlairSpec();
+    const envHint = `pi settings carry no env — export FLAIR_AGENT_ID=${env.FLAIR_AGENT_ID} in the shell that launches pi`;
+    try {
+        let config = {};
+        if (existsSync(path)) {
+            const raw = readFileSync(path, "utf-8").trim();
+            if (raw)
+                config = JSON.parse(raw);
+        }
+        if (!config || typeof config !== "object" || Array.isArray(config)) {
+            throw new Error("settings.json is not a JSON object");
+        }
+        if (config.packages !== undefined && !Array.isArray(config.packages)) {
+            throw new Error(`"packages" exists but is not an array — not rewriting it`);
+        }
+        if (config.extensions !== undefined && !Array.isArray(config.extensions)) {
+            throw new Error(`"extensions" exists but is not an array — not rewriting it`);
+        }
+        // The #1346 trap: npm: pi-flair specs under `extensions`. Collect + drop.
+        let movedFromExtensions = false;
+        if (Array.isArray(config.extensions)) {
+            const kept = config.extensions.filter((e) => !(typeof e === "string" && isPiFlairNpmSource(e)));
+            movedFromExtensions = kept.length !== config.extensions.length;
+            if (movedFromExtensions)
+                config.extensions = kept;
+        }
+        // Existing packages entry?
+        let entryIndex = -1;
+        let entrySource = null;
+        if (Array.isArray(config.packages)) {
+            for (let i = 0; i < config.packages.length; i++) {
+                const source = piPackageEntrySource(config.packages[i]);
+                if (source && isPiFlairNpmSource(source)) {
+                    entryIndex = i;
+                    entrySource = source;
+                    break;
+                }
+            }
+        }
+        if (!movedFromExtensions && entrySource === spec) {
+            return { ok: true, message: `pi: already wired in ${display} (${spec})` };
+        }
+        if (!movedFromExtensions && entryIndex === -1) {
+            // No packages entry and nothing misplaced — honor a working file-path
+            // extensions entry (pre-0.49 workaround) instead of double-wiring.
+            const scan = scanPiSettings(JSON.stringify(config));
+            const workingPath = scan.extensionFilePaths.find((p) => existsSync(resolvePiExtensionPath(p, home, piAgentDir())));
+            if (workingPath) {
+                return {
+                    ok: true,
+                    message: `pi: already wired via a file-path extension in ${display} (${workingPath}) — ` +
+                        `the pre-0.49 workaround; the canonical form is a "packages" entry: ${spec}`,
+                };
+            }
+        }
+        config.packages = Array.isArray(config.packages) ? config.packages : [];
+        let action;
+        if (entryIndex >= 0) {
+            const entry = config.packages[entryIndex];
+            if (typeof entry === "string")
+                config.packages[entryIndex] = spec;
+            else
+                entry.source = spec; // object entry: refresh source, keep filters
+            action = movedFromExtensions
+                ? `moved ${PI_FLAIR_PACKAGE} out of "extensions" and refreshed the "packages" pin in`
+                : "refreshed pin in";
+        }
+        else if (movedFromExtensions) {
+            config.packages.push(spec);
+            action = `moved ${PI_FLAIR_PACKAGE} from "extensions" to "packages" in`;
+        }
+        else {
+            config.packages.push(spec);
+            action = "wired";
+        }
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(config, null, 2) + "\n");
+        const trapNote = movedFromExtensions
+            ? ` — pi silently ignores npm: specs under "extensions" (flair#1346)`
+            : "";
+        return {
+            ok: true,
+            message: `pi: ${action} ${display} (${spec} — pi installs the package on next launch; ${envHint})${trapNote}`,
+        };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            message: `pi: manual wiring needed (could not update ${display}: ${reason}).\n` +
+                `   Add this to ${display} (${envHint}):\n${indent(piJsonSnippet())}`,
+        };
+    }
+}
 /**
  * Antigravity CLI (`agy`) + Antigravity 2.0 IDE + SDK: they share ONE central
  * MCP config at ~/.gemini/config/mcp_config.json on every OS (flair#1209).
@@ -298,6 +577,11 @@ export function clientConfigPath(id) {
             return cursorConfigPath();
         case "antigravity":
             return antigravityConfigPath();
+        case "pi":
+            // NOT an MCP config: pi's own settings.json, where the pi-flair
+            // native-extension wiring lives (flair#1342). readClientMcpBlock over
+            // this file correctly reports "no MCP block" — pi never has one.
+            return piSettingsPath();
     }
 }
 // ---- Internal wiring functions --------------------------------------------------
@@ -374,24 +658,28 @@ export const ALL_CLIENTS = [
         id: "claude-code",
         label: "Claude Code",
         bin: "claude",
+        kind: "mcp",
         wire: _wireClaudeCode,
     },
     {
         id: "codex",
         label: "Codex",
         bin: "codex",
+        kind: "mcp",
         wire: _wireCodex,
     },
     {
         id: "gemini",
         label: "Gemini",
         bin: "gemini",
+        kind: "mcp",
         wire: _wireGemini,
     },
     {
         id: "cursor",
         label: "Cursor",
         bin: "cursor",
+        kind: "mcp",
         wire: _wireCursor,
     },
     {
@@ -399,8 +687,23 @@ export const ALL_CLIENTS = [
         label: "Antigravity",
         // Google's Antigravity CLI — the executable is `agy` (flair#1209).
         bin: "agy",
+        kind: "mcp",
         wire: _wireAntigravity,
     },
+    {
+        id: "pi",
+        label: "pi",
+        bin: "pi",
+        // NOT an MCP client — pi loads @tpsdev-ai/pi-flair as a native extension
+        // via its settings.json `packages` key (flair#1342). Consumers doing
+        // MCP-shaped work must filter on `kind`.
+        kind: "native-extension",
+        // pi is also detected by its settings file: a configured pi whose binary
+        // isn't on THIS shell's PATH (version manager, launchd context) is still
+        // a pi whose wiring is worth checking/fixing. Pure fs check, both legs.
+        detect: () => detectBin("pi") || existsSync(piSettingsPath()),
+        wire: _wirePi,
+    },
 ];
 /**
  * The summary `flair init` prints LAST.
@@ -455,14 +758,17 @@ export function renderWiringSummary(results, opts = {}) {
     return lines;
 }
 /**
- * Detect every known client. One rule (`bin` on PATH) applied uniformly, so a
- * client added to ALL_CLIENTS is detected by declaring its executable — there is
- * no per-client branch here to forget to extend.
+ * Detect every known client. One rule (`bin` on PATH) applied uniformly — a
+ * client added to ALL_CLIENTS is detected by declaring its executable, with no
+ * per-client branch here to forget to extend. A client may widen that with a
+ * declared `detect` override (still a pure fs check — pi adds its settings
+ * file as a second signal, flair#1342); the override lives on the registry
+ * entry, so this function stays branch-free.
  */
 export function detectClients() {
     return ALL_CLIENTS.map((client) => ({
         ...client,
-        detected: detectBin(client.bin),
+        detected: client.detect ? client.detect() : detectBin(client.bin),
     }));
 }
 export function wireClaudeCode(env) {
@@ -480,3 +786,6 @@ export function wireCursor(env) {
 export function wireAntigravity(env) {
     return _wireAntigravity(env);
 }
+export function wirePi(env) {
+    return _wirePi(env);
+}

package/dist/lib/auth-resolve.js

@@ -119,6 +119,34 @@ export function readAdminPassFileSecure(path) {
 export function defaultAdminPassPath() {
     return join(homedir(), ".flair", "admin-pass");
 }
+/** The admin username Harper's bootstrap creates and every Basic-auth path
+ * historically hardcoded. Kept as the default; overridable per call via
+ * `resolveAdminUser` (flair#1345). */
+export const DEFAULT_ADMIN_USER = "admin";
+/**
+ * Resolve the admin USERNAME for Basic auth against a Flair/Harper instance
+ * (flair#1345).
+ *
+ * Precedence: explicit value (an `--admin-user` flag) → `FLAIR_ADMIN_USER`
+ * env → `"admin"`. Always returns a usable name — unlike the password there
+ * is no "missing" state, because `admin` is the correct answer for every
+ * instance `flair init` ever bootstrapped.
+ *
+ * Why it exists: with `authorizeLocal: false` (the #604/#610 hardening) the
+ * CLI must send real Basic admin auth, and on an instance whose superuser is
+ * not named `admin` there was no way to say so — `--admin-pass` existed,
+ * the username didn't. A wrong username and a wrong password produce the
+ * SAME 401 "Login failed" from Harper, so this also feeds the 401 hint text
+ * (see opsAuth401Hint in src/cli.ts).
+ *
+ * Unlike the admin PASSWORD (see resolveLocalAdminPass's remote-target
+ * guard), the env leg is honored for remote targets too: a username is not a
+ * secret — sending the wrong one to a third-party host leaks nothing and
+ * fails closed with a 401.
+ */
+export function resolveAdminUser(explicit) {
+    return explicit || process.env.FLAIR_ADMIN_USER || DEFAULT_ADMIN_USER;
+}
 export function defaultKeysDir() {
     return join(homedir(), ".flair", "keys");
 }
@@ -400,10 +428,13 @@ export async function tryAgentKeyFloor(baseUrl, method, path, body, keysDir) {
 export async function authedRequest(method, path, body, opts) {
     const isLocal = opts.isLocal ?? isLocalBase(opts.baseUrl);
     const keysDir = opts.keysDir ?? defaultKeysDir();
+    // One username for every Basic tier: flag > FLAIR_ADMIN_USER env > "admin"
+    // (flair#1345 — these three sites used to hardcode the literal `admin`).
+    const adminUser = resolveAdminUser(opts.adminUser);
     let authHeader;
     // Tier 1: explicit — caller-resolved flag material always wins.
     if (opts.explicitAdminPass) {
-        authHeader = `Basic ${Buffer.from(`admin:${opts.explicitAdminPass}`).toString("base64")}`;
+        authHeader = `Basic ${Buffer.from(`${adminUser}:${opts.explicitAdminPass}`).toString("base64")}`;
     }
     else if (opts.explicitKeyPath && opts.agentId) {
         try {
@@ -421,7 +452,7 @@ export async function authedRequest(method, path, body, opts) {
         }
         else if (process.env.FLAIR_ADMIN_PASS || process.env.HDB_ADMIN_PASSWORD) {
             const adminPass = process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD;
-            authHeader = `Basic ${Buffer.from(`admin:${adminPass}`).toString("base64")}`;
+            authHeader = `Basic ${Buffer.from(`${adminUser}:${adminPass}`).toString("base64")}`;
         }
     }
     // Tier 3: a PINNED agent identity — sign specifically as this agent via
@@ -444,7 +475,7 @@ export async function authedRequest(method, path, body, opts) {
         try {
             const filePass = resolveLocalAdminPass(undefined, !isLocal);
             if (filePass) {
-                authHeader = `Basic ${Buffer.from(`admin:${filePass}`).toString("base64")}`;
+                authHeader = `Basic ${Buffer.from(`${adminUser}:${filePass}`).toString("base64")}`;
             }
         }
         catch (err) {