@tpsdev-ai/flair 0.33.0 → 0.35.0

package/dist/engine-version.js

@@ -0,0 +1,239 @@
+// engine-version.ts — Harper engine version tracking (flair#1047)
+//
+// Two concerns, one module:
+//
+// 1. STORE STAMP — flair records the engine version that last wrote the data
+//    directory. At boot, if the store was written by a NEWER engine than the
+//    one running, flair refuses to start and says so: which version wrote the
+//    store, which is running now, and what to do about it.
+//
+// 2. VERSION READ — read the Harper version installed alongside this flair
+//    package, and (when a target flair version is known) the Harper version
+//    that target declares. Used by the upgrade path to decide whether the
+//    engine version is changing and a pre-upgrade snapshot is therefore
+//    mandatory.
+//
+// The stamp is a single-line file in the data directory. It must survive the
+// data directory being moved and must not require a Harper query to read — if
+// the engine cannot boot, we still need to read it.
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+/** 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). */
+export const UPGRADE_SNAPSHOT_ROOT = resolve(homedir(), ".flair", "upgrade-snapshots");
+/** Read the Harper version installed alongside this flair package. */
+export function readInstalledHarperVersion(packageRoot) {
+    for (const name of ["harper", "@harperfast/harper"]) {
+        const pkgPath = join(packageRoot, "node_modules", ...name.split("/"), "package.json");
+        if (!existsSync(pkgPath))
+            continue;
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+            if (pkg.version)
+                return pkg.version;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * Fetch the Harper version that a given @tpsdev-ai/flair version declares as
+ * a dependency. Returns null when the lookup fails (network, unparseable, etc.)
+ * — callers treat null as "cannot determine, assume it might change."
+ */
+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)
+            return null;
+        const data = await res.json();
+        return data.dependencies?.harper ?? data.dependencies?.["@harperfast/harper"] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Store stamp ─────────────────────────────────────────────────────────────
+/** Write the engine version stamp into the data directory. */
+export function writeEngineVersionStamp(dataDir, version) {
+    writeFileSync(join(dataDir, ENGINE_VERSION_STAMP), `${version}\n`, "utf-8");
+}
+/** Read the engine version stamp from the data directory, or null if absent. */
+export function readEngineVersionStamp(dataDir) {
+    const stampPath = join(dataDir, ENGINE_VERSION_STAMP);
+    if (!existsSync(stampPath))
+        return null;
+    try {
+        return readFileSync(stampPath, "utf-8").trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check whether the running engine is OLDER than the engine that last wrote
+ * the store. Returns null when the check passes (no stamp, or stamp ≤ running),
+ * or an error message when the store is newer.
+ *
+ * The error must be actionable: actor, state, remedy.
+ */
+export function checkEngineVersionBackwards(dataDir, runningVersion) {
+    const stamp = readEngineVersionStamp(dataDir);
+    if (!stamp)
+        return null; // no stamp — nothing to compare (pre-stamp install)
+    const parsed = compareVersions(stamp, runningVersion);
+    if (parsed === null) {
+        // Genuinely unparseable — cannot determine ordering. Refuse with a
+        // message that does NOT claim one is newer than the other.
+        return [
+            `This Flair install is running Harper ${runningVersion}, but the data directory at`,
+            `  ${dataDir}`,
+            `was last written by Harper ${stamp}.`,
+            ``,
+            `The engine version stamp could not be compared to the running version.`,
+            `An older Harper cannot safely read a store written by a newer one.`,
+            ``,
+            ...buildRecoveryLines(),
+        ].join("\n");
+    }
+    if (parsed > 0) {
+        // stamp > running — backwards boot, refuse.
+        return [
+            `This Flair install is running Harper ${runningVersion}, but the data directory at`,
+            `  ${dataDir}`,
+            `was last written by Harper ${stamp} — a newer engine version.`,
+            ``,
+            `An older Harper cannot safely read a store written by a newer one.`,
+            `The data may appear intact but can be silently unreadable.`,
+            ``,
+            ...buildRecoveryLines(),
+        ].join("\n");
+    }
+    return null; // running >= stamp — allowed
+}
+// ─── Version comparison (flair#1047) ─────────────────────────────────────────
+/**
+ * Compare two semver-like version strings.
+ * Returns negative when a < b, positive when a > b, zero when equal,
+ * or null when either version is genuinely unparseable (not N.N.N at all).
+ *
+ * Pre-release ordering follows semver: a version WITH a pre-release tag is
+ * LOWER than the same core without one (5.2.0-rc1 < 5.2.0). When both have
+ * pre-releases, identifiers are compared dot by dot — numeric parts
+ * numerically, the rest as strings.
+ */
+function compareVersions(a, b) {
+    const pa = parseVersion(a);
+    const pb = parseVersion(b);
+    if (!pa || !pb)
+        return null;
+    // Compare major.minor.patch (and any additional numeric components) numerically.
+    const coreLen = Math.max(pa.core.length, pb.core.length);
+    for (let i = 0; i < coreLen; i++) {
+        const ac = pa.core[i] ?? 0;
+        const bc = pb.core[i] ?? 0;
+        if (ac !== bc)
+            return ac - bc;
+    }
+    // Cores are equal — compare pre-release tags.
+    if (pa.pre === null && pb.pre === null)
+        return 0;
+    if (pa.pre === null)
+        return 1; // a has no pre-release → a > b
+    if (pb.pre === null)
+        return -1; // b has no pre-release → a < b
+    // Both have pre-releases — compare identifiers dot by dot.
+    const len = Math.max(pa.pre.length, pb.pre.length);
+    for (let i = 0; i < len; i++) {
+        const ai = pa.pre[i];
+        const bi = pb.pre[i];
+        if (ai === undefined)
+            return -1; // fewer identifiers → lower
+        if (bi === undefined)
+            return 1;
+        const an = Number(ai);
+        const bn = Number(bi);
+        const aIsNum = !isNaN(an);
+        const bIsNum = !isNaN(bn);
+        if (aIsNum && bIsNum) {
+            if (an !== bn)
+                return an - bn;
+        }
+        else if (aIsNum) {
+            return -1; // numeric < string
+        }
+        else if (bIsNum) {
+            return 1;
+        }
+        else {
+            if (ai !== bi)
+                return ai < bi ? -1 : 1;
+        }
+    }
+    return 0;
+}
+function parseVersion(v) {
+    // Split off pre-release: everything after the first hyphen.
+    const hyphenIdx = v.indexOf("-");
+    const coreStr = hyphenIdx === -1 ? v : v.slice(0, hyphenIdx);
+    const preStr = hyphenIdx === -1 ? null : v.slice(hyphenIdx + 1);
+    const coreParts = coreStr.split(".");
+    if (coreParts.length < 3)
+        return null; // not at least N.N.N
+    const core = coreParts.map(Number);
+    if (core.some(isNaN))
+        return null; // non-numeric core component
+    const pre = preStr ? preStr.split(".") : null;
+    return { core, pre };
+}
+/**
+ * Build the recovery lines for a backwards-boot refusal message.
+ * Inspects the snapshot directory so the operator gets a runnable command
+ * (or a clear "nothing to restore" message) instead of a literal placeholder.
+ */
+export function buildRecoveryLines(snapshotDir) {
+    const effectiveSnapshotDir = snapshotDir ?? UPGRADE_SNAPSHOT_ROOT;
+    const snapshots = readSnapshotFiles(effectiveSnapshotDir);
+    if (snapshots.length === 0) {
+        return [
+            `To recover:`,
+            `  No pre-upgrade snapshot was found.`,
+            `  1. Reinstall the newer version:  npm install -g @tpsdev-ai/flair@latest`,
+            `  2. Or restore from a flair backup export (if you have one).`,
+            ``,
+            `This check only helps from the release that ships it onward — it cannot`,
+            `rescue a downgrade to a build that predates the stamp.`,
+        ];
+    }
+    const newest = snapshots[0];
+    const lines = [`To recover:`];
+    if (snapshots.length > 1) {
+        lines.push(`  1. Reinstall the newer version:  npm install -g @tpsdev-ai/flair@latest`, `  2. Or restore from the newest pre-upgrade snapshot:`, `     flair snapshot restore ${newest.path}`, ``, `     (To see all snapshots:  flair snapshot list)`);
+    }
+    else {
+        lines.push(`  1. Reinstall the newer version:  npm install -g @tpsdev-ai/flair@latest`, `  2. Or restore from the pre-upgrade snapshot:`, `     flair snapshot restore ${newest.path}`);
+    }
+    lines.push(``, `This check only helps from the release that ships it onward — it cannot`, `rescue a downgrade to a build that predates the stamp.`);
+    return lines;
+}
+/** Read snapshot files (.tar.gz), newest first. Lexical sort = chronological, because the
+    filename carries an ISO 8601 timestamp (see upgradeSnapshotFileName). If that format ever
+    changes, this sort must be revisited. */
+function readSnapshotFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    try {
+        return readdirSync(dir)
+            .filter((f) => f.startsWith("flair-data-") && f.endsWith(".tar.gz"))
+            .sort() // alphabetical = chronological (flair-data-<timestamp>.tar.gz)
+            .reverse() // newest first
+            .map((f) => ({ name: f, path: join(dir, f) }));
+    }
+    catch {
+        return [];
+    }
+}

package/dist/hook-install.js

@@ -41,14 +41,20 @@
 //      FlairClient's plain global `fetch`, no rejectUnauthorized/NODE_TLS_*
 //      bypass anywhere — test/unit/hook-install.test.ts asserts that
 //      statically).
-//   5. Silent-fast degradation — also owned by session-start-hook.ts (hard
-//      timeout, no-op-on-any-failure); this module only writes the pointer
-//      to it.
+//   5. Silent-fast degradation — SPLIT, deliberately, since flair#1007.
+//      session-start-hook.ts owns it once the binary is running (hard
+//      timeout, no-op-on-any-failure). It cannot own the case where the
+//      binary never runs at all — an orphaned global install after a Node
+//      runtime change — because in that case its guard is behind the door it
+//      is meant to guard. That half is owned by the command string this
+//      module writes, which is built by doctor-client.ts's
+//      buildSessionStartHookCommand (see its section doc for the shell
+//      analysis and why the wrapper is `sh -c`, not a bare fragment).
 //   6. Size-budgeted payload — also owned by session-start-hook.ts, which
 //      reuses bootstrap's own maxTokens machinery.
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { SESSION_START_HOOK_MARKER } from "./doctor-client.js";
+import { SESSION_START_HOOK_MARKER, buildSessionStartHookCommand, hookCommandIsSilenced, isHookCommandValueSafe, } from "./doctor-client.js";
 // ── harness registry ────────────────────────────────────────────────────────
 /** v1 supports exactly one harness. The flag/type exist so a second harness
  *  is an additive registry entry, not a rewrite (Kern's #719 verdict: "a
@@ -77,9 +83,16 @@ export function hookBackupPath(settingsPath) {
 /** The exact `command` string written into the SessionStart hook entry.
  *  Always carries both FLAIR_AGENT_ID and FLAIR_URL (see module doc above)
  *  and always contains SESSION_START_HOOK_MARKER verbatim, so doctor's
- *  existing checkSessionStartHook recognizes it unchanged. */
+ *  existing checkSessionStartHook recognizes it unchanged.
+ *
+ *  Since flair#1007 this is a thin wrapper over doctor-client.ts's
+ *  buildSessionStartHookCommand — ONE builder for every path that writes this
+ *  string (`flair hook install`, `flair doctor --fix`, `flair init`'s hint),
+ *  so the invocation's failure behaviour is defined and tested in one place
+ *  instead of drifting across three literals. Throws when agentId/flairUrl
+ *  cannot be represented safely; installHook() checks first and reports. */
 export function buildHookCommand(agentId, flairUrl) {
-    return `FLAIR_AGENT_ID=${agentId} FLAIR_URL=${flairUrl} npx -y @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`;
+    return buildSessionStartHookCommand(agentId, flairUrl);
 }
 /** Best-effort recovery of the agentId/flairUrl a previously-wired hook
  *  command carries — used by `flair hook status`. Pure string scan, never
@@ -194,6 +207,19 @@ export function installHook(opts) {
     const { homeDir, harness, agentId, flairUrl } = opts;
     const dryRun = !!opts.dryRun;
     const path = hookSettingsPath(homeDir, harness);
+    // The command is a single-quoted shell argument (flair#1007) and quoting
+    // rules are not uniform across the shells a harness might use, so unsafe
+    // values are REFUSED rather than escaped — checked before anything is
+    // backed up or written, so a bad input never half-mutates the file.
+    for (const [label, value] of [["agent id", agentId], ["Flair URL", flairUrl]]) {
+        if (!isHookCommandValueSafe(value)) {
+            return {
+                ok: false, path, harness, dryRun,
+                message: `${label} '${value}' contains characters that cannot be safely written into a shell hook command (allowed: letters, digits, . _ : / -) — refusing to write it`,
+                backupPath: null, delta: null,
+            };
+        }
+    }
     if (dryRun) {
         const read = readSettingsFile(path);
         if (read.parseError) {
@@ -309,16 +335,20 @@ export function hookStatus(homeDir, harness) {
     const path = hookSettingsPath(homeDir, harness);
     const read = readSettingsFile(path);
     if (read.parseError) {
-        return { harness, path, wired: false, correctShape: false, parseError: read.parseError };
+        return { harness, path, wired: false, correctShape: false, silenced: false, parseError: read.parseError };
     }
     const config = read.parsed ?? {};
     const existing = findHookEntry(config);
     if (!existing) {
-        return { harness, path, wired: false, correctShape: false, parseError: null };
+        return { harness, path, wired: false, correctShape: false, silenced: false, parseError: null };
     }
     const hookEntry = config.hooks.SessionStart[existing.groupIndex].hooks[existing.hookIndex];
     const command = typeof hookEntry?.command === "string" ? hookEntry.command : "";
     const correctShape = hookEntry?.type === "command" && command.includes(`npx -y @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`);
     const env = parseHookCommandEnv(command);
-    return { harness, path, wired: true, correctShape, agentId: env.agentId, flairUrl: env.flairUrl, command, parseError: null };
+    return {
+        harness, path, wired: true, correctShape,
+        silenced: hookCommandIsSilenced(command),
+        agentId: env.agentId, flairUrl: env.flairUrl, command, parseError: null,
+    };
 }

package/dist/lib/auth-resolve.js

@@ -197,9 +197,92 @@ export function buildEd25519Auth(agentId, method, path, keyPath) {
     const sig = nodeCryptoSign(null, Buffer.from(payload), privKey).toString("base64");
     return `TPS-Ed25519 ${agentId}:${ts}:${nonce}:${sig}`;
 }
-/** Authenticated fetch against Flair using Ed25519. */
+/**
+ * Classify a throw from `buildEd25519Auth`.
+ *
+ * Keyed on the STRUCTURED `code` property rather than on message text,
+ * because the message is not stable across crypto backends. Probed directly
+ * on the same 60-byte malformed input:
+ *
+ *   Node (OpenSSL)   ERR_OSSL_UNSUPPORTED       error:1E08010C:DECODER routines::unsupported
+ *                    ERR_OSSL_ASN1_WRONG_TAG    error:068000A8:asn1 encoding routines::wrong tag
+ *   Bun (BoringSSL)  ERR_OSSL_NO_START_LINE     error:0900006e:PEM routines:...:NO_START_LINE
+ *                    ERR_OSSL_WRONG_TAG         error:0c0000be:ASN.1 encoding routines:...:WRONG_TAG
+ *
+ * The first line is the error in flair#1023, and matching it alone would have
+ * left the tests (bun) and the shipped CLI (node) classifying differently.
+ * So the rule is the `ERR_OSSL_` family as a whole — sound here because
+ * buildEd25519Auth does no I/O beyond reading the file: any crypto-backend
+ * error it raises is about the key, never about the instance. Message text is
+ * a secondary signal only, for a backend that reports no code we recognise.
+ */
+export function classifyKeyLoadFailure(err) {
+    const code = typeof err?.code === "string" ? err.code : "";
+    if (code === "ENOENT")
+        return "not-found";
+    if (code === "EACCES" || code === "EPERM" || code === "EISDIR")
+        return "unreadable";
+    if (code.startsWith("ERR_OSSL"))
+        return "decode";
+    const message = err instanceof Error ? err.message : String(err ?? "");
+    // `asn\.?1` because the two backends punctuate it differently:
+    // "asn1 encoding routines" (OpenSSL) vs "ASN.1 encoding routines" (BoringSSL).
+    if (/DECODER routines|asn\.?1 encoding routines|PEM routines/i.test(message))
+        return "decode";
+    return "unknown";
+}
+/** A signing key could not be loaded — distinct from the instance being down. */
+export class KeyLoadError extends Error {
+    /** The file we tried to read. Known at the point of failure; used to be discarded. */
+    keyPath;
+    kind;
+    /** The underlying error's message, preserved verbatim for the operator. */
+    underlying;
+    constructor(keyPath, kind, underlying) {
+        super(describeKeyLoadFailure(keyPath, kind, underlying));
+        this.name = "KeyLoadError";
+        this.keyPath = keyPath;
+        this.kind = kind;
+        this.underlying = underlying;
+    }
+    static from(keyPath, err) {
+        const underlying = err instanceof Error ? err.message : String(err ?? "");
+        return new KeyLoadError(keyPath, classifyKeyLoadFailure(err), underlying);
+    }
+}
+/**
+ * One line an operator can act on: what we were doing, which file, and — only
+ * when it has actually been established — why. The "unknown" arm deliberately
+ * states no cause and shows the raw error instead (flair#1023 requirement 1).
+ */
+export function describeKeyLoadFailure(keyPath, kind, underlying) {
+    switch (kind) {
+        case "not-found":
+            return `signing key ${keyPath} does not exist`;
+        case "unreadable":
+            return `signing key ${keyPath} could not be read (${underlying})`;
+        case "decode":
+            return `signing key ${keyPath} could not be parsed as an Ed25519 private key (${underlying})`;
+        case "unknown":
+            // No cause is asserted — we genuinely do not know one.
+            return `signing key ${keyPath} could not be loaded: ${underlying}`;
+    }
+}
+/**
+ * Authenticated fetch against Flair using Ed25519.
+ *
+ * Throws {@link KeyLoadError} if the key could not be loaded — a failure that
+ * provably happened BEFORE any byte hit the network, so no caller need guess
+ * whether the instance is reachable. Anything else thrown here is transport.
+ */
 export async function authFetch(baseUrl, agentId, keyPath, method, path, body) {
-    const auth = buildEd25519Auth(agentId, method, path, keyPath);
+    let auth;
+    try {
+        auth = buildEd25519Auth(agentId, method, path, keyPath);
+    }
+    catch (err) {
+        throw KeyLoadError.from(keyPath, err);
+    }
     const headers = { Authorization: auth };
     if (body !== undefined)
         headers["Content-Type"] = "application/json";