@tpsdev-ai/flair 0.53.0 → 0.54.1

package/dist/commands/workspace.js

@@ -0,0 +1,114 @@
+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;
+}
+function resolveBaseUrl(opts) {
+    return cli.resolveBaseUrl(opts);
+}
+function resolveSigningAgentId(opts, command) {
+    return cli.resolveSigningAgentId(opts, command);
+}
+function parseEntitiesOptionOrExit(csv) {
+    return cli.parseEntitiesOptionOrExit(csv);
+}
+// ─── flair workspace ─────────────────────────────────────────────────────────
+//
+// Coordination write surface (Kris #510). `workspace set` writes the
+// agent's OWN WorkspaceState via a signed PUT /WorkspaceState/{id}. Identity
+// is asserted by including agentId in the body — the server never trusts it
+// blindly, it 403s any mismatch against the Ed25519 signature's agentId
+// (WorkspaceState.put(), resources/WorkspaceState.ts), so this is a
+// self-declaration the server verifies 1:1, not attribution-from-body.
+//
+// (flair#679, measured against a real spawned Harper): table-backed resources
+// only accept writes via PUT /<Table>/<id> — a bare POST /WorkspaceState 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). WorkspaceState.ts DOES define a post() method, 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(),
+// unlike post(), does NOT default createdAt/timestamp/agentId — the CLI
+// supplies them all explicitly below.
+export const MAX_WORKSPACE_FIELD_LENGTH = 2000;
+/** Register the `flair workspace` command group (flair#1635). */
+export function register(program) {
+    const ENTITIES_OPTION_DESCRIPTION = cli.ENTITIES_OPTION_DESCRIPTION;
+    const workspace = program.command("workspace").description("Manage agent workspace state (The Office Space)");
+    workspace
+        .command("set")
+        .description("Set your agent's current workspace state (PUT /WorkspaceState/{id})")
+        .requiredOption("--ref <ref>", "Workspace ref (branch, worktree, or task ref)")
+        .option("--label <text>", "Human-readable label for this workspace")
+        .option("--provider <name>", "Provider/runtime (e.g. claude-code, openclaw)", "cli")
+        .option("--task <id>", "Task/issue id this workspace is attached to")
+        .option("--phase <phase>", "Current phase (e.g. design, implement, review)")
+        .option("--summary <text>", "Short summary of current workspace state")
+        .option("--entities <csv>", ENTITIES_OPTION_DESCRIPTION)
+        .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, "workspace set");
+        if (!agentId) {
+            console.error("Error: agent ID required. Pass --agent <id> or set FLAIR_AGENT_ID environment variable.");
+            process.exit(1);
+        }
+        // Validate field lengths (free text → cap to bound the write).
+        for (const [name, val] of [["ref", opts.ref], ["label", opts.label], ["summary", opts.summary]]) {
+            if (val && String(val).length > MAX_WORKSPACE_FIELD_LENGTH) {
+                console.error(`Error: --${name} exceeds ${MAX_WORKSPACE_FIELD_LENGTH} character limit (got ${String(val).length}).`);
+                process.exit(1);
+            }
+        }
+        // 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 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);
+        }
+        const baseUrl = resolveBaseUrl(opts).replace(/\/$/, "");
+        // Deterministic id (agentId:ref) — re-running `workspace set` for the same
+        // ref overwrites the same record, which is intentional (one row per
+        // agent+ref, not an append log).
+        const id = `${agentId}:${opts.ref}`;
+        const auth = buildEd25519Auth(agentId, "PUT", `/WorkspaceState/${id}`, keyPath);
+        // agentId IS included in the body now — WorkspaceState.put() (unlike
+        // post()) does not auto-attribute from the signature, it 403s any
+        // mismatch. This is a self-declaration the server verifies against the
+        // signature, not a forgeable claim.
+        const now = new Date().toISOString();
+        const body = {
+            id,
+            agentId,
+            ref: opts.ref,
+            provider: opts.provider ?? "cli",
+            timestamp: now,
+            createdAt: now,
+        };
+        if (opts.label)
+            body.label = opts.label;
+        if (opts.task)
+            body.taskId = opts.task;
+        if (opts.phase)
+            body.phase = opts.phase;
+        if (opts.summary)
+            body.summary = opts.summary;
+        if (entities && entities.length > 0)
+            body.entities = entities;
+        const res = await fetch(`${baseUrl}/WorkspaceState/${id}`, {
+            method: "PUT",
+            headers: { "Content-Type": "application/json", Authorization: auth },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            console.error(`Error: PUT /WorkspaceState/${id} failed (${res.status}): ${text}`);
+            process.exit(1);
+        }
+        console.log(`✓ Workspace state updated for '${agentId}': ref=${opts.ref}${opts.phase ? `, phase=${opts.phase}` : ""}`);
+    });
+}

package/dist/deploy.js

@@ -6,6 +6,8 @@ import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { COMPONENT_ENV_FILENAME, PUBLIC_URL_KEY, isLoopbackUrl, planComponentEnv, publicUrlRemedy, } from "./component-env.js";
 import { awaitOriginQuiescent, awaitReplicationConvergence, defaultConvergenceDeps, parseReplicationFailure, } from "./replication-convergence.js";
+import { DEFAULT_STAMP_VERIFY_TIMEOUT_MS, verifyStampMigrationConverged } from "./stamp-migration-verify.js";
+import { FABRIC_NPM_INSTALL_COMMAND } from "./fabric-npm-install.js";
 // Files that must be PRESENT for a deploy root to be usable at all — a
 // preflight sanity check, not the payload definition.
 //
@@ -218,6 +220,12 @@ export function buildHarperDeployArgs(opts, url, project) {
         `replicated=${opts.replicated !== false}`,
         `deployment_timeout=${deploymentTimeoutMs}`,
         `install_timeout=${installTimeoutMs}`,
+        // flair#886: Harper's default `npm install` writes every tarball into
+        // the node's `~/.npm/_cacache` and never evicts it. This command runs
+        // the same install against a disposable cache and deletes it after
+        // (see src/fabric-npm-install.ts). One argv element so Harper's
+        // `key=value` parser keeps the spaces inside the value.
+        `install_command=${FABRIC_NPM_INSTALL_COMMAND}`,
     ];
     // --ignore-replication-errors escape hatch. Only appended when
     // set — omitted entirely otherwise, so this is a no-op for every existing
@@ -929,6 +937,22 @@ export async function deploy(opts) {
             timeoutMs: opts.verifyTimeoutMs ?? DEFAULT_VERIFY_TIMEOUT_MS,
             onProgress: opts.onProgress,
         });
+        // flair#1073: route verify proves the component is serving. It does not
+        // prove embedding-stamp re-embedded pre-flip rows. `upgrade --target`
+        // was reporting success while a Fabric corpus stayed split for days.
+        // Same --no-verify escape hatch; needs Basic admin (token-only skips).
+        if (opts.fabricUser && opts.fabricPassword) {
+            await verifyStampMigrationConverged({
+                baseUrl: url,
+                fabricUser: opts.fabricUser,
+                fabricPassword: opts.fabricPassword,
+                timeoutMs: opts.verifyTimeoutMs ?? DEFAULT_STAMP_VERIFY_TIMEOUT_MS,
+                onProgress: opts.onProgress,
+            });
+        }
+        else {
+            opts.onProgress?.("skipping embedding-stamp convergence check — needs --fabric-user/--fabric-password (token-only auth cannot read /HealthDetail)");
+        }
         // Only meaningful for a target that is not loopback: a local Harper SHOULD
         // advertise loopback, and asserting otherwise there would be wrong.
         if (publicUrl) {

package/dist/fabric-npm-install.js

@@ -0,0 +1,87 @@
+/**
+ * fabric-npm-install.ts — node-side `npm install` for Fabric deploys (flair#886).
+ *
+ * Harper's default component install writes every fetched tarball into the
+ * node's `~/.npm/_cacache` and never evicts it. A month of `flair deploy` /
+ * `flair upgrade --target` therefore leaves a growing cache on the hub —
+ * hundreds of MB per install once `node-llama-cpp` prebuilds are in the
+ * tree — while `get_components` and `system_information` never show it.
+ *
+ * This file is the `install_command` those two CLI paths pass to
+ * `harper deploy`. It runs `npm install` against a disposable cache
+ * directory and deletes that directory afterwards, so cache lifetime
+ * matches the deploy rather than the node.
+ *
+ * Harper splits `install_command` on spaces and spawns without a shell
+ * (`Application.installApplication`), so the command must be a single
+ * executable plus a path — no `sh -c`, no `&& rm`. The flags after
+ * `install` match Harper's own default when `install.command` is unset
+ * (`--force --ignore-scripts`); a custom command replaces that default
+ * entirely, and dropping either flag would change what the node runs.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+/** Path Harper runs, relative to the extracted component directory. */
+export const FABRIC_NPM_INSTALL_ENTRY = "dist/fabric-npm-install.js";
+/**
+ * Passed as `install_command=…` to `harper deploy`. Harper's
+ * `buildRequest` JSON-parses values that look like JSON; this string
+ * does not, so it stays a string. `split(" ")` must yield exactly
+ * `["node", FABRIC_NPM_INSTALL_ENTRY]`.
+ */
+export const FABRIC_NPM_INSTALL_COMMAND = `node ${FABRIC_NPM_INSTALL_ENTRY}`;
+/** Harper's default argv when `install.command` is unset, plus `--cache`. */
+export const FABRIC_NPM_INSTALL_ARGS_BEFORE_CACHE = [
+    "install",
+    "--force",
+    "--ignore-scripts",
+];
+/**
+ * Run `npm install` with `--cache` pointed at a fresh temp directory,
+ * then remove that directory on success or failure.
+ *
+ * Returns npm's exit status. Throws only when the spawn itself fails
+ * to start (ENOENT on `npm`, etc.) — the same split `fabric-upgrade`'s
+ * local staging install uses.
+ */
+export function installWithEphemeralNpmCache(deps = {}) {
+    const spawn = deps.spawn ??
+        ((command, args, opts) => spawnSync(command, args, opts));
+    const mkdtemp = deps.mkdtemp ?? ((prefix) => mkdtempSync(prefix));
+    const rm = deps.rm ?? ((path) => rmSync(path, { recursive: true, force: true }));
+    const cwd = deps.cwd ?? process.cwd();
+    const tmp = deps.tmpdir ?? tmpdir();
+    const cacheDir = mkdtemp(join(tmp, "flair-npm-"));
+    try {
+        const result = spawn("npm", [...FABRIC_NPM_INSTALL_ARGS_BEFORE_CACHE, "--cache", cacheDir], { cwd, stdio: "inherit" });
+        if (result.error)
+            throw result.error;
+        return result.status ?? 1;
+    }
+    finally {
+        rm(cacheDir);
+    }
+}
+function invokedAsMain() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return import.meta.url === pathToFileURL(resolve(entry)).href;
+    }
+    catch {
+        return false;
+    }
+}
+if (invokedAsMain()) {
+    try {
+        process.exit(installWithEphemeralNpmCache());
+    }
+    catch (err) {
+        console.error(err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+}