@tpsdev-ai/flair 0.4.0 → 0.4.2

package/dist/cli.js

@@ -19,7 +19,12 @@ function defaultDataDir() {
     return join(homedir(), ".flair", "data");
 }
 function configPath() {
-    return join(homedir(), ".flair", "config.yaml");
+    // Check both .yaml and .yml extensions
+    const yamlPath = join(homedir(), ".flair", "config.yaml");
+    const ymlPath = join(homedir(), ".flair", "config.yml");
+    if (existsSync(ymlPath) && !existsSync(yamlPath))
+        return ymlPath;
+    return yamlPath;
 }
 function readPortFromConfig() {
     try {
@@ -415,7 +420,7 @@ agent
     .command("add <id>")
     .description("Register a new agent in a running Flair instance")
     .option("--name <name>", "Display name (defaults to id)")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--port <port>", "Harper HTTP port")
     .option("--admin-pass <pass>", "Admin password for registration")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys")
     .option("--ops-port <port>", "Harper operations API port")
@@ -465,7 +470,7 @@ agent
 agent
     .command("rotate-key <id>")
     .description("Rotate an agent's Ed25519 keypair")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--port <port>", "Harper HTTP port")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys")
@@ -543,7 +548,7 @@ agent
     .command("remove <id>")
     .description("Remove an agent and all its data from Flair")
     .option("--keep-keys", "Do not delete key files from disk")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--port <port>", "Harper HTTP port")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys")
@@ -655,7 +660,7 @@ program
     .command("grant <from-agent> <to-agent>")
     .description("Grant an agent read access to another agent's memories")
     .option("--scope <scope>", "Grant scope: read or search", "read")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--port <port>", "Harper HTTP port")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys (for from-agent Ed25519 auth)")
@@ -704,7 +709,7 @@ program
 program
     .command("revoke <from-agent> <to-agent>")
     .description("Revoke a memory grant between two agents")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--port <port>", "Harper HTTP port")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
     .action(async (fromAgent, toAgent, opts) => {
@@ -1185,36 +1190,258 @@ program
     if (failed > 0)
         process.exit(1);
 });
-// ─── Legacy identity/memory/soul commands (preserved) ────────────────────────
-const identity = program.command("identity").description("Legacy identity commands");
-identity.command("register")
-    .requiredOption("--id <id>")
-    .requiredOption("--name <name>")
-    .option("--role <role>")
-    .action(async (opts) => {
-    const kp = nacl.sign.keyPair();
-    const now = new Date().toISOString();
-    const agentRecord = await api("POST", "/Agent", {
-        id: opts.id, name: opts.name, role: opts.role,
-        publicKey: b64(kp.publicKey), createdAt: now, updatedAt: now,
-    });
-    console.log(JSON.stringify({ agent: agentRecord, privateKey: b64(kp.secretKey) }, null, 2));
-});
-identity.command("show").argument("<id>").action(async (id) => console.log(JSON.stringify(await api("GET", `/Agent/${id}`), null, 2)));
-identity.command("list").action(async () => console.log(JSON.stringify(await api("GET", "/Agent"), null, 2)));
-identity.command("add-integration")
-    .requiredOption("--agent <agentId>")
-    .requiredOption("--platform <platform>")
-    .requiredOption("--encrypted-credential <ciphertext>")
+// ─── flair doctor ─────────────────────────────────────────────────────────────
+program
+    .command("doctor")
+    .description("Diagnose common Flair problems and suggest fixes")
+    .option("--port <port>", "Harper HTTP port")
+    .option("--fix", "Automatically fix issues where possible")
+    .option("--dry-run", "Show what --fix would do without making changes")
     .action(async (opts) => {
-    const now = new Date().toISOString();
-    const out = await api("POST", "/Integration", {
-        id: `${opts.agent}:${opts.platform}`, agentId: opts.agent,
-        platform: opts.platform, encryptedCredential: opts.encryptedCredential,
-        createdAt: now, updatedAt: now,
-    });
-    console.log(JSON.stringify(out, null, 2));
+    const port = opts.port ? Number(opts.port) : (readPortFromConfig() ?? DEFAULT_PORT);
+    const autoFix = opts.fix ?? false;
+    const dryRun = opts.dryRun ?? false;
+    if (dryRun && !autoFix) {
+        console.log("  ℹ️  --dry-run only has effect with --fix\n");
+    }
+    let effectivePort = port;
+    let baseUrl = `http://127.0.0.1:${port}`;
+    let issues = 0;
+    let harperResponding = false;
+    console.log("\n🩺 Flair Doctor\n");
+    // Helper: try to reach Harper on a given port
+    async function probePort(p) {
+        try {
+            const res = await fetch(`http://127.0.0.1:${p}/Health`, { signal: AbortSignal.timeout(3000) });
+            return res.status > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    // Helper: discover what port a Harper PID is listening on
+    async function discoverPortFromPid(pid) {
+        // Defense-in-depth: caller already validates, but re-check here
+        if (!/^\d+$/.test(pid))
+            return null;
+        try {
+            const { execSync } = await import("node:child_process");
+            const out = execSync(`lsof -aPi -p ${pid} -sTCP:LISTEN -Fn 2>/dev/null || true`, { encoding: "utf-8" });
+            const match = out.match(/:(\d+)$/m);
+            if (match)
+                return Number(match[1]);
+        }
+        catch { /* ignore */ }
+        return null;
+    }
+    // 1. Port check — is something listening?
+    // First, check PID file so we can cross-reference
+    const dataDir0 = defaultDataDir();
+    const pidFile0 = join(dataDir0, "hdb.pid");
+    let pidAlive = false;
+    let pidValue = "";
+    if (existsSync(pidFile0)) {
+        const rawPid = (await import("node:fs")).readFileSync(pidFile0, "utf-8").trim();
+        // Strict integer validation — PID must be purely numeric to prevent injection
+        if (/^\d+$/.test(rawPid)) {
+            pidValue = rawPid;
+            try {
+                process.kill(Number(pidValue), 0);
+                pidAlive = true;
+            }
+            catch { /* dead */ }
+        }
+        else {
+            console.log(`  ⚠️  PID file contains non-numeric value: ${pidFile0} — skipping`);
+        }
+    }
+    if (await probePort(port)) {
+        console.log(`  ✅ Harper responding on port ${port}`);
+        harperResponding = true;
+    }
+    else {
+        // Port didn't respond — but if PID is alive, try to find the real port
+        let discoveredPort = null;
+        if (pidAlive) {
+            discoveredPort = await discoverPortFromPid(pidValue);
+            if (discoveredPort && discoveredPort !== port && await probePort(discoveredPort)) {
+                console.log(`  ⚠️  Harper not on expected port ${port}, but responding on port ${discoveredPort} (PID ${pidValue})`);
+                console.log(`     Your config says port ${port} but Harper is actually running on ${discoveredPort}`);
+                if (autoFix) {
+                    if (dryRun) {
+                        console.log(`     Would update config to port ${discoveredPort}`);
+                    }
+                    else {
+                        writeConfig(discoveredPort);
+                        console.log(`     ✅ Updated config to port ${discoveredPort}`);
+                    }
+                }
+                else {
+                    console.log(`     Fix: flair doctor --fix (updates config to match running port)`);
+                }
+                effectivePort = discoveredPort;
+                baseUrl = `http://127.0.0.1:${discoveredPort}`;
+                harperResponding = true;
+                issues++;
+            }
+            else {
+                console.log(`  ❌ Harper process alive (PID ${pidValue}) but not responding on any detected port`);
+                console.log(`     Fix: flair restart`);
+                issues++;
+            }
+        }
+        else {
+            // No live PID — Harper genuinely isn't running
+            // Check if something else grabbed the port
+            try {
+                const { execSync } = await import("node:child_process");
+                const lsof = execSync(`lsof -ti :${port}`, { encoding: "utf-8" }).trim();
+                if (lsof) {
+                    console.log(`  ❌ Nothing responding on port ${port} (port occupied by PID ${lsof})`);
+                    console.log(`     Fix: kill ${lsof} && flair restart`);
+                }
+                else {
+                    console.log(`  ❌ Harper is not running`);
+                    console.log(`     Fix: flair restart`);
+                }
+            }
+            catch {
+                console.log(`  ❌ Harper is not running`);
+                if (autoFix) {
+                    if (dryRun) {
+                        console.log(`     Would run: flair restart`);
+                    }
+                    else {
+                        console.log(`     Attempting restart...`);
+                        try {
+                            const { execSync } = await import("node:child_process");
+                            execSync(`${process.argv[0]} ${process.argv[1]} restart --port ${port}`, { stdio: "inherit" });
+                            console.log(`     ✅ Restart attempted`);
+                        }
+                        catch {
+                            console.log(`     ❌ Restart failed — try: flair init --agent-id <your-agent>`);
+                        }
+                    }
+                }
+                else {
+                    console.log(`     Fix: flair restart`);
+                }
+            }
+            issues++;
+        }
+    }
+    // 2. Keys directory
+    const keysDir = defaultKeysDir();
+    if (existsSync(keysDir)) {
+        const keyFiles = (await import("node:fs")).readdirSync(keysDir).filter((f) => f.endsWith(".key"));
+        if (keyFiles.length > 0) {
+            console.log(`  ✅ Keys found: ${keyFiles.length} agent(s) in ${keysDir}`);
+        }
+        else {
+            console.log(`  ❌ Keys directory exists but no .key files found`);
+            console.log(`     Fix: flair init --agent-id <your-agent>`);
+            issues++;
+        }
+    }
+    else {
+        console.log(`  ❌ Keys directory missing: ${keysDir}`);
+        console.log(`     Fix: flair init --agent-id <your-agent>`);
+        issues++;
+    }
+    // 3. Config file
+    const cfgPath = configPath();
+    if (existsSync(cfgPath)) {
+        const savedPort = readPortFromConfig();
+        console.log(`  ✅ Config: ${cfgPath} (port: ${savedPort ?? "default"})`);
+    }
+    else {
+        console.log(`  ⚠️  No config file at ${cfgPath} — using defaults`);
+    }
+    // 4. Embeddings check (only if Harper is responding)
+    if (harperResponding) {
+        try {
+            const testRes = await fetch(`${baseUrl}/SemanticSearch`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ q: "test", limit: 1 }),
+                signal: AbortSignal.timeout(10000),
+            });
+            if (testRes.ok) {
+                const data = await testRes.json();
+                if (data._warning) {
+                    console.log(`  ⚠️  Embeddings: keyword-only (${data._warning})`);
+                    console.log(`     Semantic search quality is degraded`);
+                    console.log(`     Check: ls ~/.npm-global/lib/node_modules/@tpsdev-ai/flair/models/`);
+                    issues++;
+                }
+                else {
+                    console.log(`  ✅ Embeddings: semantic search operational`);
+                }
+            }
+            else if (testRes.status === 401) {
+                console.log(`  ⚠️  Embeddings: cannot verify (auth required for SemanticSearch)`);
+            }
+        }
+        catch { /* fetch error, already flagged */ }
+    }
+    // 5. Stale PID file (skip if already reported in port check)
+    const dataDir = defaultDataDir();
+    const pidFile = join(dataDir, "hdb.pid");
+    if (existsSync(pidFile)) {
+        const pidContent = (await import("node:fs")).readFileSync(pidFile, "utf-8").trim();
+        try {
+            process.kill(Number(pidContent), 0);
+            if (harperResponding) {
+                console.log(`  ✅ PID file: ${pidFile} (process ${pidContent} is alive)`);
+            }
+            // If not responding, we already reported the issue in step 1
+        }
+        catch {
+            console.log(`  ❌ Stale PID file: ${pidFile} (process ${pidContent} is dead)`);
+            if (autoFix) {
+                if (dryRun) {
+                    console.log(`     Would remove: ${pidFile}`);
+                }
+                else {
+                    (await import("node:fs")).unlinkSync(pidFile);
+                    console.log(`     ✅ Removed stale PID file`);
+                }
+            }
+            else {
+                console.log(`     Fix: rm ${pidFile} && flair restart`);
+            }
+            issues++;
+        }
+    }
+    // 6. Data directory
+    if (existsSync(dataDir)) {
+        console.log(`  ✅ Data directory: ${dataDir}`);
+    }
+    else {
+        // Check ~/harper/ (common alternative)
+        const altDir = join(homedir(), "harper");
+        if (existsSync(altDir)) {
+            console.log(`  ⚠️  Data at ~/harper/ (not ~/.flair/data) — old install location`);
+        }
+        else {
+            console.log(`  ❌ No data directory found`);
+            console.log(`     Fix: flair init --agent-id <your-agent>`);
+            issues++;
+        }
+    }
+    // Summary
+    console.log("");
+    if (issues === 0) {
+        console.log("  🟢 No issues found");
+    }
+    else {
+        console.log(`  🔴 ${issues} issue${issues > 1 ? "s" : ""} found — see fixes above`);
+    }
+    console.log("");
+    if (issues > 0)
+        process.exit(1);
 });
+// ─── Memory and Soul commands ────────────────────────────────────────────────
 const memory = program.command("memory").description("Manage agent memories");
 memory.command("add").requiredOption("--agent <id>").requiredOption("--content <text>")
     .option("--durability <d>", "standard").option("--tags <csv>")
@@ -1240,7 +1467,7 @@ program
     .description("Search memories by meaning (shortcut for memory search)")
     .requiredOption("--agent <id>", "Agent ID")
     .option("--limit <n>", "Max results", "5")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--port <port>", "Harper HTTP port")
     .option("--url <url>", "Flair base URL (overrides --port)")
     .option("--key <path>", "Ed25519 private key path")
     .action(async (query, opts) => {
@@ -1285,7 +1512,7 @@ program
     .description("Cold-start context: get soul + recent memories as formatted text")
     .requiredOption("--agent <id>", "Agent ID")
     .option("--max-tokens <n>", "Maximum tokens in output", "4000")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--port <port>", "Harper HTTP port")
     .option("--url <url>", "Flair base URL (overrides --port)")
     .option("--key <path>", "Ed25519 private key path")
     .action(async (opts) => {
@@ -1335,7 +1562,7 @@ program
     .description("Export agents, memories, and souls to a JSON archive")
     .option("--output <path>", "Output file path (default: ~/.flair/backups/flair-backup-<timestamp>.json)")
     .option("--agents <ids>", "Comma-separated agent IDs to include (default: all)")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--port <port>", "Harper HTTP port")
     .option("--url <url>", "Flair base URL (overrides --port)")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
     .action(async (opts) => {
@@ -1414,7 +1641,7 @@ program
     .description("Import a Flair backup archive")
     .option("--merge", "Add/update records without deleting existing (default)")
     .option("--replace", "Delete all existing data for backed-up agents first, then import")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--port <port>", "Harper HTTP port")
     .option("--url <url>", "Flair base URL (overrides --port)")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
     .option("--dry-run", "Show what would be imported without making changes")
@@ -1531,7 +1758,7 @@ program
     .description("Export a single agent's identity (soul + memories) to a portable file")
     .option("--output <path>", "Output file path")
     .option("--include-key", "Include private key in export (UNENCRYPTED — keep the output file secure)")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--port <port>", "Harper HTTP port")
     .option("--url <url>", "Flair base URL (overrides --port)")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
     .option("--keys-dir <dir>", "Keys directory", defaultKeysDir())
@@ -1617,7 +1844,7 @@ program
 program
     .command("import <path>")
     .description("Import an agent from an export file into this Flair instance")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    .option("--port <port>", "Harper HTTP port")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--url <url>", "Flair base URL (overrides --port)")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
@@ -1741,11 +1968,11 @@ program
 // ─── flair migrate-keys ───────────────────────────────────────────────────────
 program
     .command("migrate-keys")
-    .description("Migrate agent keys from legacy path (~/.tps/secrets/flair/) to ~/.flair/keys/")
-    .option("--from <dir>", "Legacy keys directory", join(homedir(), ".tps", "secrets", "flair"))
+    .description("Migrate agent keys from old path (~/.tps/secrets/flair/) to ~/.flair/keys/")
+    .option("--from <dir>", "Old keys directory", join(homedir(), ".tps", "secrets", "flair"))
     .option("--to <dir>", "New keys directory", defaultKeysDir())
     .option("--dry-run", "Show what would be migrated without copying")
-    .option("--port <port>", "Harper HTTP port (for agent list)", String(DEFAULT_PORT))
+    .option("--port <port>", "Harper HTTP port")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env)")
     .action(async (opts) => {
@@ -1755,7 +1982,7 @@ program
     const opsPort = opts.opsPort ? Number(opts.opsPort) : Number(opts.port) + 1;
     const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
     if (!existsSync(fromDir)) {
-        console.log(`Legacy keys directory not found: ${fromDir}`);
+        console.log(`Old keys directory not found: ${fromDir}`);
         console.log("Nothing to migrate.");
         process.exit(0);
     }
@@ -1797,7 +2024,7 @@ program
     else {
         console.log(`\n✅ Migration complete: ${migrated} migrated, ${skipped} skipped`);
         if (migrated > 0) {
-            console.log(`\nLegacy keys preserved at ${fromDir} (delete manually when confirmed working).`);
+            console.log(`\nOld keys preserved at ${fromDir} (delete manually when confirmed working).`);
             // Optionally verify keys match Flair records
             if (adminPass) {
                 console.log("\nVerifying migrated keys against Flair...");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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",