@tpsdev-ai/flair 0.20.0 → 0.20.1

package/dist/cli.js

@@ -6648,6 +6648,11 @@ program
     .option("--no-restart", "Do not restart the component after deploy (default: restart=true)")
     .option("--dry-run", "Resolve package, validate args, skip the deploy call")
     .option("--package-root <dir>", "Override package root (mainly for testing)")
+    .option("--deployment-timeout <ms>", "Milliseconds harper waits for cluster-wide peer replication (env: FABRIC_DEPLOYMENT_TIMEOUT; default: 600000 — harper's own 120s default is too short for Fabric)")
+    .option("--install-timeout <ms>", "Milliseconds harper waits for package install (env: FABRIC_INSTALL_TIMEOUT; default: 600000)")
+    .option("--no-verify", "Skip post-deploy served-API verification (default: verify — on by design, so the CLI can't report success on an empty/broken deploy)")
+    .option("--verify-timeout <ms>", "Milliseconds to wait for the served API to settle after harper's post-deploy restart before verifying (default: 300000)")
+    .option("--verify-resource <name>", "Resource to verify is serving after deploy (repeatable; default: derived from the deployed package's dist/resources)", (val, prev) => [...prev, val], [])
     .action(async (opts) => {
     const green = (s) => `\x1b[32m${s}\x1b[0m`;
     const red = (s) => `\x1b[31m${s}\x1b[0m`;
@@ -6665,6 +6670,12 @@ program
         restart: opts.restart !== false,
         dryRun: opts.dryRun ?? false,
         packageRoot: opts.packageRoot,
+        deploymentTimeoutMs: Number(opts.deploymentTimeout ?? process.env.FABRIC_DEPLOYMENT_TIMEOUT ?? 600_000),
+        installTimeoutMs: Number(opts.installTimeout ?? process.env.FABRIC_INSTALL_TIMEOUT ?? 600_000),
+        verify: opts.verify !== false,
+        verifyResources: opts.verifyResource?.length ? opts.verifyResource : undefined,
+        verifyTimeoutMs: Number(opts.verifyTimeout ?? 300_000),
+        onProgress: (msg) => console.log(dim(`  ${msg}`)),
     };
     const errors = validateDeployOptions(deployOpts);
     if (errors.length) {
@@ -6689,7 +6700,7 @@ program
             console.log(dim(`  package root: ${result.packageRoot}`));
             return;
         }
-        console.log(`\n${green("✓")} Flair ${result.version} deployed`);
+        console.log(`\n${green("✓")} Flair ${result.version} deployed${deployOpts.verify ? " and verified serving" : ""}`);
         console.log(`\n  URL:     ${result.url}`);
         console.log(`  Project: ${result.project}`);
         console.log(`\nNext steps:`);
@@ -6703,6 +6714,12 @@ program
         if (hint?.includes("401") || hint?.includes("unauthoriz")) {
             console.error(dim("  hint: check Fabric Studio → Cluster Settings → Admin for the admin password"));
         }
+        if (hint?.includes("component is not serving")) {
+            console.error(dim("  hint: harper reported success but the served API disagrees — check the Fabric Studio component logs for the real deploy error, then retry"));
+        }
+        if (hint?.includes("did not settle")) {
+            console.error(dim("  hint: Harper may still be restarting — check Fabric Studio, or retry with a longer --verify-timeout"));
+        }
         process.exit(1);
     }
 });

package/dist/deploy.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { dirname, join, resolve } from "node:path";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 // Files that must be present in a Flair package for deployment.
@@ -11,6 +11,23 @@ export const REQUIRED_PACKAGE_FILES = [
     "ui",
     "config.yaml",
 ];
+// harper's own deploy CLI defaults to a 120s peer-replication timeout that's
+// too short for Fabric — the CLI aborts mid-replicate with no override,
+// which is exactly the incident this module now guards against. 10 minutes
+// gives cluster-wide replication + install room to actually finish.
+export const DEFAULT_DEPLOYMENT_TIMEOUT_MS = 600_000;
+export const DEFAULT_INSTALL_TIMEOUT_MS = 600_000;
+// Post-deploy verification: how long we'll wait for the served API to come
+// back up after harper's restart, how often we poll while waiting, and how
+// many consecutive reachable responses count as "settled" (a single
+// reachable probe right after restart can be a fluke mid-flap).
+export const DEFAULT_VERIFY_TIMEOUT_MS = 300_000;
+export const VERIFY_POLL_INTERVAL_MS = 15_000;
+export const VERIFY_SETTLE_STREAK = 3;
+// Fallback when dist/resources can't be scanned (e.g. an unusual package
+// layout via --package-root). Memory is Flair's original, always-present
+// resource — a reasonable single thing to check when derivation fails.
+export const FALLBACK_VERIFY_RESOURCE = "Memory";
 export function validateOptions(opts) {
     const errors = [];
     if (!opts.target) {
@@ -81,6 +98,65 @@ export function validatePackageLayout(packageRoot) {
             missing.join(", "));
     }
 }
+// Derive the list of served, table-backed REST resources from the compiled
+// package — no hardcoded resource list. Flair's jsResource files (dist/resources/*.js)
+// contain both real Resource classes (routable, GET-able) and plain helper
+// modules (embeddings, auth, scoring, etc). We only ship dist/ in the
+// published package (resources/*.ts source is not in package.json's `files`),
+// so this scans the COMPILED output, matching the convention every current
+// table-backed resource follows:
+//
+//   export class <Name> extends databases.<db>.<Name> { ... }
+//
+// i.e. the exported class name equals the filename equals the underlying
+// table name (Memory.js -> `export class Memory extends databases.flair.Memory`,
+// same for Agent, Soul, MemoryGrant, Credential, OrgEvent, etc). Helper
+// modules are lowercase-first (agent-auth.js, embeddings-provider.js, ...)
+// and never match, so they're skipped without needing a denylist. Files
+// that export a resource extending a *generic* `Resource` base (AgentCard,
+// WorkspaceLatest, action-style endpoints) are deliberately excluded here —
+// they're action/command endpoints, not GET-able collections, and asserting
+// non-404 on them would be the wrong check.
+// Literal regex (no interpolation — satisfies semgrep detect-non-literal-regexp):
+// matches `export class <Name> extends databases.<db>.<Name>` where the `\1`
+// backreference forces the class name and the table name to be identical.
+// Capture group 1 is the resource name; the caller matches it against the filename.
+const EXPORTED_TABLE_CLASS_RE = /export class (\w+) extends databases\.[A-Za-z_$][\w$]*\.\1\b/g;
+export function deriveVerifyResources(packageRoot) {
+    const resourcesDir = join(packageRoot, "dist", "resources");
+    let entries;
+    try {
+        entries = readdirSync(resourcesDir);
+    }
+    catch {
+        return [FALLBACK_VERIFY_RESOURCE];
+    }
+    const names = [];
+    for (const entry of entries) {
+        if (!entry.endsWith(".js"))
+            continue;
+        const base = entry.slice(0, -3);
+        if (!/^[A-Z]/.test(base))
+            continue; // helper modules are camelCase/lowercase
+        let src;
+        try {
+            src = readFileSync(join(resourcesDir, entry), "utf8");
+        }
+        catch {
+            continue;
+        }
+        // The file serves a table resource iff it exports a class whose name matches
+        // its filename (base) and extends databases.<db>.<sameName>.
+        for (const m of src.matchAll(EXPORTED_TABLE_CLASS_RE)) {
+            if (m[1] === base) {
+                names.push(base);
+                break;
+            }
+        }
+    }
+    names.sort();
+    return names.length ? names : [FALLBACK_VERIFY_RESOURCE];
+}
 function resolveHarperBin(packageRoot) {
     const local = join(packageRoot, "node_modules/@harperfast/harper/dist/bin/harper.js");
     if (existsSync(local))
@@ -105,6 +181,22 @@ function resolveHarperBin(packageRoot) {
     throw new Error("Could not locate Harper CLI binary (@harperfast/harper). " +
         "Flair deploy requires Harper to be installed alongside Flair.");
 }
+// Pure arg-array builder — separated from spawnHarper so the timeout
+// passthrough (and the rest of the arg shape) is unit-testable without
+// mocking child_process / actually spawning harper.
+export function buildHarperDeployArgs(opts, url, project) {
+    const deploymentTimeoutMs = opts.deploymentTimeoutMs ?? DEFAULT_DEPLOYMENT_TIMEOUT_MS;
+    const installTimeoutMs = opts.installTimeoutMs ?? DEFAULT_INSTALL_TIMEOUT_MS;
+    return [
+        "deploy",
+        `target=${url}`,
+        `project=${project}`,
+        `restart=${opts.restart !== false}`,
+        `replicated=${opts.replicated !== false}`,
+        `deployment_timeout=${deploymentTimeoutMs}`,
+        `install_timeout=${installTimeoutMs}`,
+    ];
+}
 function spawnHarper(bin, args, cwd, env) {
     return new Promise((resolveP, rejectP) => {
         const p = spawn(process.execPath, [bin, ...args], {
@@ -121,6 +213,85 @@ function spawnHarper(bin, args, cwd, env) {
         });
     });
 }
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+// A single reachability probe against the served (REST) base URL. Harper
+// restarts the process after every deploy, so the endpoint FLAPS for a bit —
+// connection refused / reset / DNS blips are all EXPECTED right after
+// restart, not a failure signal by themselves. Any HTTP response at all
+// (regardless of status code — a 404 on `/` is normal) proves the process
+// is back up and terminating TLS/HTTP again; that's all "reachable" means
+// here. Resource-level 404s are a separate, later check.
+async function probeReachable(baseUrl, fetchImpl) {
+    try {
+        await fetchImpl(baseUrl, { method: "GET", signal: AbortSignal.timeout(10_000) });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function pollUntilSettled(baseUrl, timeoutMs, pollIntervalMs, settleStreak, fetchImpl, onProgress) {
+    const deadline = Date.now() + timeoutMs;
+    let streak = 0;
+    let attempt = 0;
+    for (;;) {
+        attempt++;
+        const reachable = await probeReachable(baseUrl, fetchImpl);
+        streak = reachable ? streak + 1 : 0;
+        if (!reachable) {
+            onProgress?.(`waiting for ${baseUrl} to come back up after restart (attempt ${attempt})...`);
+        }
+        if (streak >= settleStreak)
+            return;
+        if (Date.now() >= deadline) {
+            throw new Error(`deploy verification: ${baseUrl} did not settle within ${timeoutMs}ms after restart ` +
+                `(Harper never came back up, or is unusually slow to restart post-deploy)`);
+        }
+        await sleep(pollIntervalMs);
+    }
+}
+async function verifyResourcesServing(baseUrl, resources, fetchImpl) {
+    const base = baseUrl.replace(/\/+$/, "");
+    const notServing = [];
+    for (const name of resources) {
+        const path = `${base}/${name}`;
+        let status;
+        try {
+            const res = await fetchImpl(path, { method: "GET", signal: AbortSignal.timeout(10_000) });
+            status = res.status;
+        }
+        catch (err) {
+            throw new Error(`deploy verification: request to ${path} failed even after the endpoint settled: ${err?.message ?? err}`);
+        }
+        // 404 = the resource genuinely isn't being served (this is the incident:
+        // harper reported "Successfully deployed" while the component was empty).
+        // 401 = auth-gated, which means the resource IS being served correctly.
+        // 200 = served + accessible. Both count as pass.
+        if (status === 404)
+            notServing.push(name);
+    }
+    if (notServing.length) {
+        const list = notServing.map((n) => `/${n}`).join(", ");
+        throw new Error(`deploy reported success but ${list} return${notServing.length === 1 ? "s" : ""} 404 — ` +
+            `component is not serving; likely deployed the wrong package root`);
+    }
+}
+// The tool must not be able to lie. harper's deploy CLI can print
+// "Successfully deployed" for an empty component — the only way to know the
+// deploy actually worked is to curl the served API and check it isn't 404.
+// This polls the served base URL (443, NOT the :9925 ops API deploy talks
+// to) until it settles after harper's post-deploy restart, then asserts the
+// derived resource(s) respond non-404.
+export async function verifyDeployServing(o) {
+    const { baseUrl, resources, timeoutMs = DEFAULT_VERIFY_TIMEOUT_MS, pollIntervalMs = VERIFY_POLL_INTERVAL_MS, settleStreak = VERIFY_SETTLE_STREAK, fetchImpl = fetch, onProgress, } = o;
+    onProgress?.(`verifying ${baseUrl} is actually serving (not just reported deployed)...`);
+    await pollUntilSettled(baseUrl, timeoutMs, pollIntervalMs, settleStreak, fetchImpl, onProgress);
+    onProgress?.(`settled — checking ${resources.map((r) => `/${r}`).join(", ")}...`);
+    await verifyResourcesServing(baseUrl, resources, fetchImpl);
+    onProgress?.(`served API verified non-404 for ${resources.length} resource(s)`);
+}
 export async function deploy(opts) {
     const errors = validateOptions(opts);
     if (errors.length) {
@@ -141,13 +312,7 @@ export async function deploy(opts) {
             "Pass --fabric-user + --fabric-password instead.");
     }
     const harperBin = resolveHarperBin(packageRoot);
-    const args = [
-        "deploy",
-        `target=${url}`,
-        `project=${project}`,
-        `restart=${opts.restart !== false}`,
-        `replicated=${opts.replicated !== false}`,
-    ];
+    const args = buildHarperDeployArgs(opts, url, project);
     // Credentials go via env, not argv, so they don't appear in `ps` output
     // for the lifetime of the Harper child process. Harper's cliOperations
     // reads CLI_TARGET_USERNAME / CLI_TARGET_PASSWORD as env fallbacks.
@@ -157,5 +322,20 @@ export async function deploy(opts) {
         CLI_TARGET_PASSWORD: opts.fabricPassword,
     };
     await spawnHarper(harperBin, args, packageRoot, childEnv);
+    // harper can print "Successfully deployed" for a component that isn't
+    // actually serving anything (the incident this closes: an empty deploy,
+    // reported success, /Memory 404ing in prod). Verify by curling the served
+    // API — on by default, escape hatch via --no-verify.
+    if (opts.verify !== false) {
+        const resources = opts.verifyResources?.length
+            ? opts.verifyResources
+            : deriveVerifyResources(packageRoot);
+        await verifyDeployServing({
+            baseUrl: url,
+            resources,
+            timeoutMs: opts.verifyTimeoutMs ?? DEFAULT_VERIFY_TIMEOUT_MS,
+            onProgress: opts.onProgress,
+        });
+    }
     return { url, project, version, packageRoot, dryRun: false };
 }

package/package.json

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