@tpsdev-ai/flair 0.53.0 → 0.54.2

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/engine-version.js

@@ -19,6 +19,7 @@
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { homedir } from "node:os";
+import { fetchDeclaredDependencies } from "./lib/npm-registry.js";
 /** Filename of the engine-version stamp inside the data directory. */
 export const ENGINE_VERSION_STAMP = "engine-version.txt";
 /** Root directory for pre-upgrade snapshots (~/.flair/upgrade-snapshots). */
@@ -47,11 +48,18 @@ export function readInstalledHarperVersion(packageRoot) {
  */
 export async function fetchDeclaredHarperVersion(flairVersion) {
     try {
-        const res = await fetch(`https://registry.npmjs.org/@tpsdev-ai/flair/${flairVersion}`, { signal: AbortSignal.timeout(5000) });
-        if (!res.ok)
+        // flair#1688: resolve the configured registry rather than assuming npmjs —
+        // the engine-version decision must look at the same package the upgrade
+        // will actually install. flair#1692: the same scheme allowlist, redirect
+        // refusal, npm transport, and non-default-registry handling apply.
+        const result = await fetchDeclaredDependencies("@tpsdev-ai/flair", flairVersion, { timeoutMs: 5000 });
+        if (result.kind === "refused") {
+            console.error(result.message);
             return null;
-        const data = await res.json();
-        return data.dependencies?.harper ?? data.dependencies?.["@harperfast/harper"] ?? null;
+        }
+        if (result.kind !== "ok")
+            return null;
+        return result.dependencies?.harper ?? result.dependencies?.["@harperfast/harper"] ?? null;
     }
     catch {
         return null;

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);
+    }
+}

package/dist/fabric-upgrade.js

@@ -30,6 +30,7 @@ import { mkdtempSync, rmSync, writeFileSync, readFileSync, existsSync } from "no
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { createRequire } from "node:module";
+import { createRegistryNoticePrinter, fetchDeclaredDependencies, fetchLatestVersion } from "./lib/npm-registry.js";
 /**
  * Minimum harper version whose component packager works when the
  * package root is under node_modules (flair#513 — the empty-tarball fix landed
@@ -154,30 +155,44 @@ export function buildDeployablePackageJson(flairVersion, pin) {
     return pkg;
 }
 // ─── Default (real) dependency implementations ──────────────────────────────
-const REGISTRY = "https://registry.npmjs.org";
+// flair#1692: one printer per process, so a Fabric upgrade names the registry
+// (and source) it stages from without repeating the line per lookup.
+const noticeRegistry = createRegistryNoticePrinter();
 async function defaultFetchLatestFlairVersion() {
-    const res = await fetch(`${REGISTRY}/${FLAIR_PKG}/latest`, {
-        signal: AbortSignal.timeout(10_000),
-    });
-    if (!res.ok) {
-        throw new Error(`npm registry returned ${res.status} for ${FLAIR_PKG}/latest`);
+    // flair#1688: the configured registry (scoped `@tpsdev-ai:registry`,
+    // project/user/global .npmrc, env `npm_config_registry`), not a hardcoded
+    // host — a Fabric upgrade must stage the package from the mirror the
+    // operator configured, or fail rather than silently use the public one.
+    // flair#1692: the value is validated as strict semver before it is used as
+    // `dependencies` in the staged package.json (npm accepts `pkg@<url>` as a
+    // remote-tarball spec, so an unvalidated value is an arbitrary-install
+    // primitive).
+    const result = await fetchLatestVersion(FLAIR_PKG, { timeoutMs: 10_000, onRegistry: noticeRegistry });
+    if (result.kind === "ok")
+        return result.version;
+    if (result.kind === "refused")
+        throw new Error(result.message);
+    if (result.kind === "invalid") {
+        throw new Error(`npm registry returned a non-semver latest version (${JSON.stringify(result.value)}) for ${FLAIR_PKG} ` +
+            `from ${result.registry.url} (source: ${result.registry.source}) — refusing to use it`);
     }
-    const data = (await res.json());
-    if (!data.version)
-        throw new Error(`No version in registry response for ${FLAIR_PKG}`);
-    return data.version;
+    throw new Error(`Could not determine ${FLAIR_PKG}/latest: ${result.message}`);
 }
 async function defaultFetchDeclaredHarperVersion(flairVersion) {
-    const res = await fetch(`${REGISTRY}/${FLAIR_PKG}/${flairVersion}`, {
-        signal: AbortSignal.timeout(10_000),
+    const result = await fetchDeclaredDependencies(FLAIR_PKG, flairVersion, {
+        timeoutMs: 10_000,
+        onRegistry: noticeRegistry,
     });
-    if (!res.ok)
+    if (result.kind === "refused") {
+        console.error(result.message);
+        return null;
+    }
+    if (result.kind !== "ok")
         return null;
-    const data = (await res.json());
     // Either package name (flair#870) — pre-rename flair versions declare the
     // scoped one, and those are precisely the versions that may need an override.
     for (const name of HARPER_PKG_NAMES) {
-        const declared = data.dependencies?.[name];
+        const declared = result.dependencies?.[name];
         if (declared)
             return declared;
     }