@tpsdev-ai/flair 0.53.0 → 0.54.2

package/dist/commands/migrate-harness-memory.js

@@ -0,0 +1,270 @@
+import { authFetch, resolveAdminUser } from "../lib/auth-resolve.js";
+import { load as parseYaml } from "js-yaml";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, sep } from "node:path";
+let cli;
+/** Bind the cli-locals this module depends on. */
+export function bindCli(fns) {
+    cli = fns;
+}
+function resolveHttpPort(...args) {
+    return cli.resolveHttpPort(...args);
+}
+function resolveMemoryDir(target, agentId) {
+    switch (target) {
+        case "claude-code": {
+            const cwd = process.cwd();
+            const encodedCwd = encodeURIComponent(cwd).replace(/%2F/g, "/");
+            const memoryDir = join(homedir(), ".claude", "projects", encodedCwd, "memory");
+            const resolved = resolve(memoryDir);
+            const expectedRoot = join(homedir(), ".claude", "projects");
+            if (!resolved.startsWith(expectedRoot + sep)) {
+                throw new Error(`Memory dir must be within ${expectedRoot}, got ${resolved}`);
+            }
+            return resolved;
+        }
+        case "openclaw": {
+            const cwd = process.cwd();
+            const encodedCwd = encodeURIComponent(cwd).replace(/%2F/g, "/");
+            const memoryDir = join(homedir(), ".openclaw", "projects", encodedCwd, "memory");
+            const resolved = resolve(memoryDir);
+            const expectedRoot = join(homedir(), ".openclaw", "projects");
+            if (!resolved.startsWith(expectedRoot + sep)) {
+                throw new Error(`Memory dir must be within ${expectedRoot}, got ${resolved}`);
+            }
+            return resolved;
+        }
+        case "pi": {
+            const cwd = process.cwd();
+            const encodedCwd = encodeURIComponent(cwd).replace(/%2F/g, "/");
+            const memoryDir = join(homedir(), ".pi", "projects", encodedCwd, "memory");
+            const resolved = resolve(memoryDir);
+            const expectedRoot = join(homedir(), ".pi", "projects");
+            if (!resolved.startsWith(expectedRoot + sep)) {
+                throw new Error(`Memory dir must be within ${expectedRoot}, got ${resolved}`);
+            }
+            return resolved;
+        }
+        default:
+            throw new Error(`Unknown target: ${target}. Valid: claude-code, openclaw, pi`);
+    }
+}
+/** Parse a memory file with YAML frontmatter. */
+function parseMemoryFile(filePath) {
+    const raw = readFileSync(filePath, "utf-8");
+    const lines = raw.split("\n");
+    if (!lines[0].startsWith("---")) {
+        return { meta: {}, body: raw };
+    }
+    let endIdx = 1;
+    while (endIdx < lines.length && !lines[endIdx].startsWith("---")) {
+        endIdx++;
+    }
+    const frontmatterLines = lines.slice(1, endIdx);
+    const bodyLines = lines.slice(endIdx + 1);
+    const yamlContent = frontmatterLines.join("\n");
+    const meta = parseYaml(yamlContent) || {};
+    return {
+        meta: {
+            name: meta.name,
+            description: meta.description,
+            type: meta.type,
+            tags: Array.isArray(meta.tags) ? meta.tags : (meta.tags ? [meta.tags] : []),
+        },
+        body: bodyLines.join("\n").trim(),
+    };
+}
+/** Map memory type to durability. */
+function mapDurability(type) {
+    switch (type) {
+        case "feedback":
+        case "reference":
+            return "permanent";
+        case "project":
+        case "user":
+            return "persistent";
+        default:
+            return "standard";
+    }
+}
+/** Extract keywords from filename for tags. */
+function extractKeywordsFromFilename(filename) {
+    const base = filename.replace(/\.md$/, "");
+    const withoutType = base.replace(/^(feedback|project|reference|user)_/, "");
+    const parts = withoutType.split(/[_-]+/).map(p => p.toLowerCase());
+    const stopwords = new Set(["the", "and", "for", "with", "about", "on", "in", "to", "of", "a", "an"]);
+    return parts.filter(p => p.length > 2 && !stopwords.has(p));
+}
+export function register(program) {
+    // ─── flair migrate-harness-memory ───────────────────────────────────────────
+    /** Resolve the memory directory path for a target harness. */
+    program
+        .command("migrate-harness-memory")
+        .description("Migrate harness-local memories to Flair")
+        .requiredOption("--target <target>", "Target harness: claude-code, openclaw, pi")
+        .requiredOption("--agent <id>", "Agent ID to write memories under")
+        .option("--dry-run", "Show what would be migrated without writing")
+        .action(async (opts) => {
+        const target = opts.target;
+        const agentId = opts.agent;
+        const dryRun = !!opts.dryRun;
+        let memoryDir;
+        try {
+            memoryDir = resolveMemoryDir(target, agentId);
+        }
+        catch (e) {
+            console.error(`Error resolving memory directory: ${e.message}`);
+            process.exit(1);
+        }
+        if (!existsSync(memoryDir)) {
+            console.error(`Error: Memory directory not found: ${memoryDir}`);
+            process.exit(1);
+        }
+        const migratedDir = join(memoryDir, ".migrated");
+        if (!dryRun) {
+            mkdirSync(migratedDir, { recursive: true, mode: 0o700 });
+        }
+        console.log(`Migrating memories from ${memoryDir} to Flair (agentId=${agentId})`);
+        if (dryRun)
+            console.log("  (DRY RUN - no files will be modified)");
+        const files = readdirSync(memoryDir, { withFileTypes: true })
+            .filter(d => d.isFile() && d.name.endsWith(".md") && d.name !== "MEMORY.md")
+            .map(d => d.name)
+            .sort();
+        if (files.length === 0) {
+            console.log("No memory files found.");
+            return;
+        }
+        console.log(`Found ${files.length} memory file(s) to migrate.`);
+        let successCount = 0;
+        let skipCount = 0;
+        let failCount = 0;
+        for (const filename of files) {
+            const sourcePath = join(memoryDir, filename);
+            const migratedPath = join(migratedDir, filename);
+            if (existsSync(migratedPath)) {
+                console.log(`  ${filename}: already migrated, skipping`);
+                skipCount++;
+                continue;
+            }
+            console.log(`  Processing: ${filename}...`);
+            let parsed;
+            try {
+                parsed = parseMemoryFile(sourcePath);
+            }
+            catch (e) {
+                console.error(`    Failed to parse: ${e.message}`);
+                failCount++;
+                continue;
+            }
+            let type = parsed.meta.type;
+            if (!type) {
+                if (filename.startsWith("feedback_"))
+                    type = "feedback";
+                else if (filename.startsWith("project_"))
+                    type = "project";
+                else if (filename.startsWith("reference_"))
+                    type = "reference";
+                else
+                    type = "session";
+            }
+            const durability = mapDurability(type);
+            const tags = [...(parsed.meta.tags || [])];
+            const filenameTags = extractKeywordsFromFilename(filename);
+            for (const t of filenameTags) {
+                if (!tags.includes(t))
+                    tags.push(t);
+            }
+            tags.push(type);
+            const content = parsed.body;
+            console.log(`    Type: ${type}, Durability: ${durability}`);
+            console.log(`    Tags: ${tags.join(", ")}`);
+            console.log(`    Content preview: ${content.slice(0, 100)}${content.length > 100 ? "..." : ""}`);
+            if (!dryRun) {
+                console.log(`    Writing to Flair...`);
+                try {
+                    const httpUrl = `http://127.0.0.1:${resolveHttpPort({})}`;
+                    const agentKeyId = `${agentId}.key`;
+                    const keysDir = join(homedir(), ".flair", "keys");
+                    const keyPath = join(keysDir, agentKeyId);
+                    let authSuccess = false;
+                    if (existsSync(keyPath)) {
+                        const memoryId = `${agentId}-${randomUUID()}`;
+                        const body = {
+                            id: memoryId,
+                            agentId: agentId,
+                            content: content,
+                            type: type,
+                            durability: durability,
+                            tags: tags,
+                            createdAt: new Date().toISOString(),
+                        };
+                        const memoryPath = `/Memory/${memoryId}`;
+                        const res = await authFetch(httpUrl, agentId, keyPath, "PUT", memoryPath, body);
+                        if (res.ok) {
+                            authSuccess = true;
+                            console.log(`    Write to Flair successful (Ed25519 auth)`);
+                        }
+                    }
+                    if (!authSuccess) {
+                        const adminPass = process.env.FLAIR_ADMIN_PASS || process.env.HDB_ADMIN_PASSWORD || "";
+                        if (adminPass) {
+                            const memoryId = `${agentId}-${randomUUID()}`;
+                            const body = {
+                                id: memoryId,
+                                agentId: agentId,
+                                content: content,
+                                type: type,
+                                durability: durability,
+                                tags: tags,
+                                createdAt: new Date().toISOString(),
+                            };
+                            const memoryPath = `/Memory/${memoryId}`;
+                            const auth = `Basic ${Buffer.from(`${resolveAdminUser(undefined)}:${adminPass}`).toString("base64")}`;
+                            const res = await fetch(`${httpUrl}${memoryPath}`, {
+                                method: "PUT",
+                                headers: {
+                                    Authorization: auth,
+                                    "Content-Type": "application/json",
+                                },
+                                body: JSON.stringify(body),
+                                signal: AbortSignal.timeout(10000),
+                            });
+                            if (res.ok) {
+                                console.log(`    Write to Flair successful (Basic auth)`);
+                            }
+                            else {
+                                const text = await res.text();
+                                throw new Error(`HTTP ${res.status}: ${text}`);
+                            }
+                        }
+                        else {
+                            throw new Error("No authentication method available");
+                        }
+                    }
+                    renameSync(sourcePath, migratedPath);
+                    console.log(`    Moved to .migrated/${filename}`);
+                }
+                catch (e) {
+                    console.error(`    Failed: ${e.message}`);
+                    failCount++;
+                    continue;
+                }
+            }
+            else {
+                console.log(`    [dry-run] Would write to Flair and move to .migrated/${filename}`);
+            }
+            successCount++;
+        }
+        console.log(`\nMigration complete:`);
+        console.log(`  Processed: ${files.length}`);
+        console.log(`  Successful: ${successCount}`);
+        console.log(`  Skipped: ${skipCount}`);
+        console.log(`  Failed: ${failCount}`);
+        if (failCount > 0) {
+            process.exit(1);
+        }
+    });
+}

package/dist/commands/orgevent.js

@@ -0,0 +1,138 @@
+import { buildEd25519Auth, resolveKeyPath } from "../lib/auth-resolve.js";
+import { randomUUID } from "node:crypto";
+let cli;
+/** Bind the cli-locals this module depends on. */
+export function bindCli(fns) {
+    cli = fns;
+}
+function parseEntitiesOptionOrExit(...args) {
+    return cli.parseEntitiesOptionOrExit(...args);
+}
+function resolveBaseUrl(...args) {
+    return cli.resolveBaseUrl(...args);
+}
+function resolveSigningAgentId(...args) {
+    return cli.resolveSigningAgentId(...args);
+}
+export const MAX_ORGEVENT_SUMMARY_LENGTH = 500;
+export const MAX_ORGEVENT_DETAIL_LENGTH = 8000;
+/**
+ * The ONE write shape behind `flair orgevent` — signed PUT /OrgEvent/{id} —
+ * extracted so `flair quality --emit` (flair-quality Slice 2) reuses the
+ * exact same call, rather than hand-rolling a second one. Everything below
+ * mirrors what the `orgevent` command's action used to do inline: id
+ * convention (`${agentId}-${randomUUID()}`, matching flair-client's
+ * Memory.write()), the same Ed25519 signing (buildEd25519Auth), the same
+ * length guards (MAX_ORGEVENT_SUMMARY_LENGTH/MAX_ORGEVENT_DETAIL_LENGTH) so
+ * every caller — CLI flag or programmatic — gets them, and the same
+ * authorId self-declaration OrgEvent.put() verifies server-side against the
+ * signature (see the module doc above `orgevent`). Never throws — every
+ * failure mode (missing key, oversized field, non-2xx response) returns
+ * `{ ok: false, error }` for the caller to surface however fits its own UX.
+ */
+export async function publishOrgEvent(params) {
+    if (params.summary.length > MAX_ORGEVENT_SUMMARY_LENGTH) {
+        return { ok: false, error: `summary exceeds ${MAX_ORGEVENT_SUMMARY_LENGTH} character limit (got ${params.summary.length})` };
+    }
+    if (params.detail && params.detail.length > MAX_ORGEVENT_DETAIL_LENGTH) {
+        return { ok: false, error: `detail exceeds ${MAX_ORGEVENT_DETAIL_LENGTH} character limit (got ${params.detail.length})` };
+    }
+    const keyPath = resolveKeyPath(params.agentId);
+    if (!keyPath) {
+        return { ok: false, error: `private key not found for agent '${params.agentId}'. Check ~/.flair/keys/ or set FLAIR_KEY_DIR.` };
+    }
+    const id = `${params.agentId}-${randomUUID()}`;
+    const auth = buildEd25519Auth(params.agentId, "PUT", `/OrgEvent/${id}`, keyPath);
+    const body = {
+        id,
+        authorId: params.agentId,
+        kind: params.kind,
+        summary: params.summary,
+        createdAt: new Date().toISOString(),
+    };
+    if (params.detail)
+        body.detail = params.detail;
+    if (params.scope)
+        body.scope = params.scope;
+    if (params.targetIds && params.targetIds.length > 0)
+        body.targetIds = params.targetIds;
+    if (params.entities && params.entities.length > 0)
+        body.entities = params.entities;
+    const res = await fetch(`${params.baseUrl}/OrgEvent/${id}`, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json", Authorization: auth },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        return { ok: false, error: `PUT /OrgEvent/${id} failed (${res.status}): ${text}` };
+    }
+    const data = await res.json().catch(() => null);
+    return { ok: true, id: data?.id ?? id };
+}
+export function register(program) {
+    const ENTITIES_OPTION_DESCRIPTION = cli.ENTITIES_OPTION_DESCRIPTION;
+    // ─── flair orgevent ──────────────────────────────────────────────────────────
+    //
+    // Coordination write surface (Kris #510). `orgevent` publishes an
+    // OrgEvent ATTRIBUTED to the authenticated agent via a signed PUT
+    // /OrgEvent/{id}. authorId is asserted in the body but self-verified server
+    // side: OrgEvent.put() (resources/OrgEvent.ts) 403s any authorId that doesn't
+    // match the Ed25519 signature's agentId, so an agent still cannot forge
+    // another agent's events — the difference from post() is that put() checks-
+    // and-rejects a mismatch rather than silently overwriting it.
+    //
+    // (flair#679, measured against a real spawned Harper): table-backed resources
+    // only accept writes via PUT /<Table>/<id> — a bare POST /OrgEvent 405s
+    // ("does not have a post method implemented to handle HTTP method POST"),
+    // same restriction documented in resources/Memory.ts and already fixed for
+    // `soul set` (#498). OrgEvent.ts DOES define a post() method that
+    // auto-generates id/createdAt, but Harper's REST layer never routes a real
+    // HTTP POST to it — post() is only reachable via in-process resource
+    // instantiation, never the wire. put() does NOT default id/createdAt, so the
+    // CLI generates and supplies them itself (id convention mirrors flair-client's
+    // Memory.write(): `${agentId}-${randomUUID()}`).
+    program
+        .command("orgevent")
+        .description("Publish an org-wide coordination event attributed to your agent (PUT /OrgEvent/{id})")
+        .requiredOption("--kind <kind>", "Event kind (e.g. coord.claim, coord.release, status)")
+        .requiredOption("--summary <text>", "Short summary of the event")
+        .option("--detail <text>", "Longer detail payload")
+        .option("--scope <scope>", "Scope of the event (e.g. an agent id, repo, or 'org')")
+        .option("--target <agentId>", "Recipient agent id (repeatable)", (val, acc) => { acc.push(val); return acc; }, [])
+        .option("--entities <csv>", ENTITIES_OPTION_DESCRIPTION)
+        .option("--agent <id>", "Agent ID (env: FLAIR_AGENT_ID)")
+        .option("--port <port>", "Harper HTTP port")
+        .option("--target-url <url>", "Remote Flair URL (env: FLAIR_TARGET)")
+        .action(async (opts) => {
+        const { agentId } = resolveSigningAgentId(opts, "orgevent");
+        if (!agentId) {
+            console.error("Error: agent ID required. Pass --agent <id> or set FLAIR_AGENT_ID environment variable.");
+            process.exit(1);
+        }
+        // orgevent reuses --target for recipients, so the remote-URL override is
+        // --target-url here (env FLAIR_TARGET still honored via resolveBaseUrl).
+        const baseUrl = resolveBaseUrl({ target: opts.targetUrl, port: opts.port }).replace(/\/$/, "");
+        const targetIds = Array.isArray(opts.target) && opts.target.length > 0 ? opts.target : undefined;
+        // flair#1288: validate --entities before any key/network work; exits 1
+        // with the canonical format-and-type-set message on any malformed value.
+        const entities = opts.entities ? parseEntitiesOptionOrExit(String(opts.entities)) : undefined;
+        const result = await publishOrgEvent({
+            agentId,
+            baseUrl,
+            kind: opts.kind,
+            summary: opts.summary,
+            detail: opts.detail,
+            scope: opts.scope,
+            targetIds,
+            entities,
+        });
+        if (!result.ok) {
+            console.error(`Error: ${result.error}`);
+            process.exit(1);
+        }
+        const targets = targetIds ? ` → ${targetIds.join(", ")}` : "";
+        console.log(`✓ OrgEvent published as '${agentId}': kind=${opts.kind}${targets}`);
+        console.log(`  id: ${result.id}`);
+    });
+}

package/dist/commands/presence.js

@@ -0,0 +1,76 @@
+import { resolveKeyPath, buildEd25519Auth } from "../lib/auth-resolve.js";
+let cli;
+/** Bind shared CLI helpers. cli.ts calls this immediately before register(program). */
+export function bindCli(fns) {
+    cli = fns;
+}
+const resolveBaseUrl = (opts) => cli.resolveBaseUrl(opts);
+const resolveSigningAgentId = (opts, command) => cli.resolveSigningAgentId(opts, command);
+// ─── flair presence ─────────────────────────────────────────────────────────
+export const VALID_PRESENCE_ACTIVITIES = ["coding", "reviewing", "planning", "debugging", "idle"];
+export const MAX_TASK_LENGTH = 120;
+/** Register the `flair presence` command group (flair#1633). */
+export function register(program) {
+    const presence = program.command("presence").description("Manage agent presence (The Office Space)");
+    presence
+        .command("set")
+        .description("Set your agent's current activity and task (POST /Presence)")
+        .option("--activity <activity>", `Activity type (${VALID_PRESENCE_ACTIVITIES.join("|")})`)
+        .option("--task <text>", "Short description of what you're working on")
+        .option("--agent <id>", "Agent ID (env: FLAIR_AGENT_ID)")
+        .option("--port <port>", "Harper HTTP port")
+        .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
+        .action(async (opts) => {
+        const { agentId } = resolveSigningAgentId(opts, "presence set");
+        if (!agentId) {
+            console.error("Error: agent ID required. Pass --agent <id> or set FLAIR_AGENT_ID environment variable.");
+            process.exit(1);
+        }
+        // Validate activity
+        if (!opts.activity) {
+            console.error("Error: --activity is required.");
+            process.exit(1);
+        }
+        const activity = opts.activity;
+        if (!VALID_PRESENCE_ACTIVITIES.includes(activity)) {
+            console.error(`Error: invalid activity '${activity}'. Must be one of: ${VALID_PRESENCE_ACTIVITIES.join(", ")}`);
+            process.exit(1);
+        }
+        // Validate task length
+        const task = opts.task ?? undefined;
+        if (task && task.length > MAX_TASK_LENGTH) {
+            console.error(`Error: --task exceeds ${MAX_TASK_LENGTH} character limit (got ${task.length}).`);
+            process.exit(1);
+        }
+        // Resolve key path
+        const keyPath = resolveKeyPath(agentId);
+        if (!keyPath) {
+            console.error(`Error: private key not found for agent '${agentId}'. Check ~/.flair/keys/ or set FLAIR_KEY_DIR.`);
+            process.exit(1);
+        }
+        // Build auth + POST
+        const baseUrl = resolveBaseUrl(opts).replace(/\/$/, "");
+        const auth = buildEd25519Auth(agentId, "POST", "/Presence", keyPath);
+        const body = { activity };
+        if (task)
+            body.currentTask = task;
+        const res = await fetch(`${baseUrl}/Presence`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: auth,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            console.error(`Error: POST /Presence failed (${res.status}): ${text}`);
+            process.exit(1);
+        }
+        const data = await res.json().catch(() => null);
+        console.log(`✓ Presence updated for '${agentId}': activity=${activity}${task ? `, task="${task}"` : ""}`);
+        if (data?.presenceStatus) {
+            console.log(`  Status: ${data.presenceStatus}`);
+        }
+    });
+}