@tpsdev-ai/flair 0.45.0 → 0.47.0

package/dist/hook-install.js

@@ -54,7 +54,7 @@
 //      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, buildSessionStartHookCommand, hookCommandIsSilenced, isHookCommandValueSafe, } from "./doctor-client.js";
+import { SESSION_START_HOOK_MARKER, buildSessionStartHookCommand, buildContinuityCaptureHookCommand, checkContinuityCaptureHooks, computeContinuityHookInstall, computeContinuityHookRemoval, 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
@@ -352,3 +352,152 @@ export function hookStatus(homeDir, harness) {
         agentId: env.agentId, flairUrl: env.flairUrl, command, parseError: null,
     };
 }
+// ── continuity capture hooks (flair#1257 slice 2) ──────────────────────────
+//
+// The PostToolUse + Stop pair that auto-journals working state into the
+// ephemeral Memory tier (see packages/flair-mcp/src/continuity.ts for the
+// capture discipline). INSTALLING THIS PAIR IS THE OPT-IN — there is no env
+// flag — so it gets the same standalone, symmetric, dry-run-able command
+// surface as the SessionStart hook (`flair hook install|uninstall
+// --continuity`, wired in src/cli.ts), sharing this module's Sherlock
+// conditions: fail-closed on malformed settings.json, backup before any real
+// mutation, idempotent merge that never touches unrelated hooks/keys,
+// --dry-run computes the delta without writing (no backup either). The pure
+// mutation cores (computeContinuityHookInstall / computeContinuityHookRemoval)
+// live in src/doctor-client.ts next to the ONE command builder so `flair
+// doctor --fix` and this family cannot drift apart.
+/** Mirror of buildHookCommand for the continuity pair — delegates to the ONE
+ *  builder in doctor-client.ts. Throws on unrepresentable values;
+ *  installContinuityHooks() checks first and reports instead. */
+export function buildContinuityHookCommand(agentId, flairUrl) {
+    return buildContinuityCaptureHookCommand(agentId, flairUrl);
+}
+/** Install (or repair to current form) the continuity capture pair. */
+export function installContinuityHooks(opts) {
+    const { homeDir, harness, agentId, flairUrl } = opts;
+    const dryRun = !!opts.dryRun;
+    const path = hookSettingsPath(homeDir, harness);
+    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, actions: null,
+            };
+        }
+    }
+    if (dryRun) {
+        const read = readSettingsFile(path);
+        if (read.parseError) {
+            return {
+                ok: false, path, harness, dryRun,
+                message: `${read.parseError} — dry run: nothing would be written until this is fixed`,
+                backupPath: null, actions: null,
+            };
+        }
+        const { changed, actions } = computeContinuityHookInstall(read.parsed ?? {}, agentId, flairUrl);
+        const message = changed
+            ? `would wire the continuity capture hooks (PostToolUse: ${actions.PostToolUse}, Stop: ${actions.Stop}) in ${path} (dry run — nothing written)`
+            : `continuity capture hooks already current in ${path} — no changes`;
+        return { ok: true, path, harness, dryRun, message, backupPath: null, actions };
+    }
+    let backupPath = null;
+    if (existsSync(path)) {
+        try {
+            backupPath = takeBackup(path);
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false, path, harness, dryRun,
+                message: `could not back up ${path} before mutating it: ${reason} — refusing to touch it`,
+                backupPath: null, actions: null,
+            };
+        }
+    }
+    const read = readSettingsFile(path);
+    if (read.parseError) {
+        return {
+            ok: false, path, harness, dryRun,
+            message: `${read.parseError} — refusing to modify a file we can't safely parse. Original left untouched at ${path}` +
+                (backupPath ? `; backup copy at ${backupPath}.` : "."),
+            backupPath, actions: null,
+        };
+    }
+    const { changed, actions, newConfig } = computeContinuityHookInstall(read.parsed ?? {}, agentId, flairUrl);
+    if (!changed) {
+        return { ok: true, path, harness, dryRun, message: `continuity capture hooks already current in ${path}`, backupPath, actions };
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(newConfig, null, 2) + "\n");
+    return {
+        ok: true, path, harness, dryRun,
+        message: `wired the continuity capture hooks (PostToolUse: ${actions.PostToolUse}, Stop: ${actions.Stop}) in ${path}`,
+        backupPath, actions,
+    };
+}
+/** Symmetric removal of the continuity pair — only ours, everything else in
+ *  the file left untouched. A no-op when nothing is installed. */
+export function uninstallContinuityHooks(opts) {
+    const { homeDir, harness } = opts;
+    const dryRun = !!opts.dryRun;
+    const path = hookSettingsPath(homeDir, harness);
+    if (dryRun) {
+        const read = readSettingsFile(path);
+        if (read.parseError) {
+            return {
+                ok: false, path, harness, dryRun,
+                message: `${read.parseError} — dry run: nothing would be removed until this is fixed`,
+                backupPath: null, actions: null,
+            };
+        }
+        const { changed, actions } = computeContinuityHookRemoval(read.parsed ?? {});
+        const message = changed
+            ? `would remove the continuity capture hooks (PostToolUse: ${actions.PostToolUse}, Stop: ${actions.Stop}) from ${path} (dry run — nothing written)`
+            : `no continuity capture hooks found in ${path} — nothing to remove`;
+        return { ok: true, path, harness, dryRun, message, backupPath: null, actions };
+    }
+    let backupPath = null;
+    if (existsSync(path)) {
+        try {
+            backupPath = takeBackup(path);
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false, path, harness, dryRun,
+                message: `could not back up ${path} before mutating it: ${reason} — refusing to touch it`,
+                backupPath: null, actions: null,
+            };
+        }
+    }
+    const read = readSettingsFile(path);
+    if (read.parseError) {
+        return {
+            ok: false, path, harness, dryRun,
+            message: `${read.parseError} — refusing to modify a file we can't safely parse. Original left untouched at ${path}` +
+                (backupPath ? `; backup copy at ${backupPath}.` : "."),
+            backupPath, actions: null,
+        };
+    }
+    const { changed, actions, newConfig } = computeContinuityHookRemoval(read.parsed ?? {});
+    if (!changed) {
+        return { ok: true, path, harness, dryRun, message: `no continuity capture hooks found in ${path} — nothing to remove`, backupPath, actions };
+    }
+    writeFileSync(path, JSON.stringify(newConfig, null, 2) + "\n");
+    return {
+        ok: true, path, harness, dryRun,
+        message: `removed the continuity capture hooks (PostToolUse + Stop) from ${path}`,
+        backupPath, actions,
+    };
+}
+/** Read-only continuity status for `flair hook status` — the same report
+ *  doctor's check consumes, resolved through the harness's settings path. */
+export function continuityHookStatus(homeDir, harness) {
+    // hookSettingsPath and checkContinuityCaptureHooks both resolve
+    // ~/.claude/settings.json from homeDir; asserting through the harness
+    // registry keeps a future second harness from silently reading the wrong
+    // file.
+    void hookSettingsPath(homeDir, harness);
+    return checkContinuityCaptureHooks(homeDir);
+}

package/dist/install/global-bin-path.js

@@ -0,0 +1,234 @@
+// ─── npm global bin dir vs PATH (flair#1134) ────────────────────────────────
+//
+// `npm install -g @tpsdev-ai/flair` on a user-prefix setup (prefix =
+// ~/.npm-global or similar) succeeds, puts the `flair` bin in
+// `<prefix>/bin`, and then `flair` is "command not found" because that
+// directory was never added to PATH. The install instructions claim
+// one-command readiness, so the failure reads as a broken package, not a
+// broken PATH.
+//
+// This module is the single source of truth for detecting that state and
+// for the message that fixes it. Two consumers:
+//   - dist/postinstall.cjs (src/postinstall.cts) — runs at `npm i -g` time,
+//     the moment the user hits the lie.
+//   - `flair doctor` — cheap, always runs, and covers every path where
+//     lifecycle scripts are suppressed (--ignore-scripts, bun without
+//     trustedDependencies, the fleet's tar-swap deploys).
+//
+// Contract (errors must enable a response): every warning names the ACTUAL
+// bin directory and prints the exact line to add for the user's shell —
+// never "check your PATH". If we cannot VALIDATE the directory (the flair
+// bin is really there), we say nothing rather than print a wrong fix.
+//
+// Everything here is pure and dependency-injected except
+// resolveNpmGlobalPrefix (spawns `npm prefix -g` for doctor).
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+// ─── path membership ────────────────────────────────────────────────────────
+/** Strip trailing separators ("/", and "\" on win32) without eating a bare root. */
+function stripTrailingSeps(p, win32) {
+    const stripped = p.replace(win32 ? /[\\/]+$/ : /\/+$/, "");
+    return stripped === "" ? p.slice(0, 1) : stripped;
+}
+function normalizeEntry(entry, win32) {
+    let e = stripTrailingSeps(entry.trim(), win32);
+    if (win32)
+        e = e.replace(/\//g, "\\").toLowerCase();
+    return e;
+}
+/**
+ * The directory npm links global bins into for a given prefix:
+ * `<prefix>/bin` everywhere except win32, where shims land in the prefix
+ * itself (npm's own layout, not ours).
+ */
+export function npmGlobalBinDir(prefix, platform = process.platform) {
+    const win32 = platform === "win32";
+    const clean = stripTrailingSeps(prefix.trim(), win32);
+    return win32 ? clean : join(clean, "bin");
+}
+/**
+ * Is `dir` one of the entries of `pathEnv`? Trailing slashes are ignored on
+ * both sides; win32 compares case-insensitively with either separator and
+ * splits on ";". Empty entries (historical "cwd" semantics) never match.
+ */
+export function isDirOnPath(dir, pathEnv, platform = process.platform) {
+    if (!pathEnv)
+        return false;
+    const win32 = platform === "win32";
+    const delim = win32 ? ";" : ":";
+    const want = normalizeEntry(dir, win32);
+    return pathEnv
+        .split(delim)
+        .filter((e) => e.trim() !== "")
+        .some((e) => normalizeEntry(e, win32) === want);
+}
+/** basename of $SHELL, lowercased — "/usr/local/bin/zsh" → "zsh". */
+function shellFlavor(shell) {
+    if (!shell)
+        return "";
+    return shell.replace(/\\/g, "/").split("/").pop().toLowerCase();
+}
+export function shellPathFix(binDir, shell) {
+    const flavor = shellFlavor(shell);
+    if (flavor === "fish") {
+        // fish_add_path persists via a universal variable — one command does both.
+        const line = `fish_add_path ${binDir}`;
+        return { exportLine: line, persistCommand: line, rcFile: null };
+    }
+    const exportLine = `export PATH="${binDir}:$PATH"`;
+    const rcFile = flavor === "zsh" ? "~/.zshrc" : flavor === "bash" ? "~/.bashrc" : null;
+    return {
+        exportLine,
+        persistCommand: rcFile === null ? null : `echo '${exportLine}' >> ${rcFile}`,
+        rcFile,
+    };
+}
+// ─── the message ────────────────────────────────────────────────────────────
+/**
+ * The full actionable warning. Names the actual bin dir, gives the exact
+ * line for the user's shell, says how to persist it, and how to verify.
+ */
+export function formatOffPathMessage(binDir, shell, platform = process.platform) {
+    if (platform === "win32") {
+        return [
+            `flair is installed in ${binDir}, but that directory is not on your PATH,`,
+            `so the "flair" command will not be found.`,
+            ``,
+            `Fix — add it to your user PATH (new terminals pick it up):`,
+            ``,
+            `  powershell -Command "[Environment]::SetEnvironmentVariable('Path', [Environment]::GetEnvironmentVariable('Path','User') + ';${binDir}', 'User')"`,
+            ``,
+            `Then open a new terminal and verify:  flair --version`,
+        ].join("\n");
+    }
+    const fix = shellPathFix(binDir, shell);
+    const lines = [
+        `flair is installed at ${binDir}/flair, but ${binDir} is not on your PATH,`,
+        `so the "flair" command will not be found.`,
+        ``,
+        `Fix — run this in your shell now:`,
+        ``,
+        `  ${fix.exportLine}`,
+    ];
+    if (fix.persistCommand) {
+        lines.push(``, `and persist it for new shells:`, ``, `  ${fix.persistCommand}`);
+    }
+    else if (shellFlavor(shell) !== "fish") {
+        lines.push(``, `and add that same line to your shell's startup file to persist it.`);
+    }
+    lines.push(``, `Then verify:  flair --version`);
+    return lines.join("\n");
+}
+export function checkGlobalBinOnPath(input) {
+    const platform = input.platform ?? process.platform;
+    const binDir = npmGlobalBinDir(input.prefix, platform);
+    if (isDirOnPath(binDir, input.pathEnv, platform))
+        return { onPath: true, binDir };
+    return {
+        onPath: false,
+        binDir,
+        exportLine: shellPathFix(binDir, input.shell).exportLine,
+        message: formatOffPathMessage(binDir, input.shell, platform),
+    };
+}
+/**
+ * Fallback when npm_config_prefix is absent: derive prefix from where npm put
+ * us. String-based (not path.join) so the win32 shape stays faithful even in
+ * tests running on posix hosts.
+ */
+export function prefixFromPackageDir(packageDir, platform = process.platform) {
+    // posix:  <prefix>/lib/node_modules/@tpsdev-ai/flair  → 4 segments up
+    // win32:  <prefix>\node_modules\@tpsdev-ai\flair      → 3 segments up
+    const win32 = platform === "win32";
+    const segments = stripTrailingSeps(packageDir, win32).split(win32 ? /[\\/]/ : "/");
+    const ups = win32 ? 3 : 4;
+    const kept = segments.slice(0, Math.max(1, segments.length - ups));
+    return kept.join(win32 ? "\\" : "/") || (win32 ? packageDir : "/");
+}
+function defaultBinDirHasFlair(binDir, platform) {
+    const names = platform === "win32" ? ["flair.cmd", "flair"] : ["flair"];
+    return names.some((n) => existsSync(join(binDir, n)));
+}
+/**
+ * Decide what (if anything) the postinstall hook should print.
+ *
+ * Returns the warning message, or null when there is nothing to say:
+ *   - not a global install (npm_config_global !== "true" — local installs and
+ *     non-npm runners stay silent),
+ *   - no candidate prefix VALIDATES (the flair bin is not actually in the
+ *     candidate's bin dir — we never print a fix naming a wrong directory),
+ *   - or the bin dir is already on PATH.
+ */
+export function postinstallWarning(env) {
+    if (env.npmConfigGlobal !== "true")
+        return null;
+    const platform = env.platform ?? process.platform;
+    const hasFlair = env.binDirHasFlair ?? ((d) => defaultBinDirHasFlair(d, platform));
+    const candidates = [];
+    if (env.npmConfigPrefix)
+        candidates.push(env.npmConfigPrefix);
+    if (env.packageDir)
+        candidates.push(prefixFromPackageDir(env.packageDir, platform));
+    for (const prefix of candidates) {
+        const binDir = npmGlobalBinDir(prefix, platform);
+        if (!hasFlair(binDir))
+            continue; // unvalidated — never name a wrong dir
+        if (isDirOnPath(binDir, env.pathEnv, platform))
+            return null;
+        return formatOffPathMessage(binDir, env.shell, platform);
+    }
+    return null;
+}
+/** Compact per-boot variant of the message — this one repeats until fixed. */
+export function formatCompactOffPathBanner(binDir, shell) {
+    const fix = shellPathFix(binDir, shell);
+    const lines = [
+        `flair: ${binDir} (where npm installed flair) is not on your PATH.`,
+        `  fix now:  ${fix.exportLine}`,
+    ];
+    if (fix.persistCommand && fix.persistCommand !== fix.exportLine) {
+        lines.push(`  persist:  ${fix.persistCommand}`);
+    }
+    else if (!fix.persistCommand) {
+        lines.push(`  persist:  add that line to your shell's startup file`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Decide what (if anything) the CLI should print to stderr at boot.
+ * Null when: not a TTY, the layout does not validate (dev checkouts, npx
+ * cache copies, tar-swap deploys — their derived dir has no flair bin), or
+ * the bin dir is on PATH.
+ */
+export function cliBootPathWarning(env) {
+    if (!env.stderrIsTTY)
+        return null;
+    const platform = env.platform ?? process.platform;
+    const hasFlair = env.binDirHasFlair ?? ((d) => defaultBinDirHasFlair(d, platform));
+    const binDir = npmGlobalBinDir(prefixFromPackageDir(env.packageDir, platform), platform);
+    if (!hasFlair(binDir))
+        return null; // unvalidated — never name a wrong dir
+    if (isDirOnPath(binDir, env.pathEnv, platform))
+        return null;
+    return formatCompactOffPathBanner(binDir, env.shell);
+}
+// ─── doctor plumbing ────────────────────────────────────────────────────────
+/**
+ * `npm prefix -g`, best-effort. Returns the trimmed prefix or null when npm
+ * is absent / slow / errors — doctor SKIPS the check then (flair may have
+ * been installed by other means; a missing npm is not something this check
+ * can turn into an actionable finding).
+ */
+export async function resolveNpmGlobalPrefix() {
+    try {
+        const { execFile } = await import("node:child_process");
+        const out = await new Promise((resolve, reject) => {
+            execFile(process.platform === "win32" ? "npm.cmd" : "npm", ["prefix", "-g"], { timeout: 5000, encoding: "utf-8", shell: process.platform === "win32" }, (err, stdout) => (err ? reject(err) : resolve(String(stdout))));
+        });
+        const prefix = out.trim();
+        return prefix === "" ? null : prefix;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/entity-vocab-cli.js

@@ -0,0 +1,113 @@
+/**
+ * entity-vocab-cli.ts — CLI-side copy of the attention-plane entity
+ * vocabulary validator (resources/entity-vocab.ts is the canonical module).
+ *
+ * INLINED, not imported: cross-boundary imports from src/ into resources/
+ * don't survive npm packaging — tsconfig.cli.json compiles with
+ * `rootDir: "src"`, so dist/cli.js has no resources/ module it can resolve
+ * at the same relative path. This is the same reason src/cli.ts inlines the
+ * federation crypto helpers (see the note beside `sortKeys()` there) and the
+ * private-visibility filter. The two files MUST stay in sync:
+ * test/unit/cli-entities-option.test.ts imports BOTH and pins ENTITY_TYPES
+ * equality, validator parity across a known-answer table, and the
+ * entityFormatHint() string — drift fails CI rather than shipping.
+ *
+ * Used by the `--entities <csv>` option on `flair memory add`,
+ * `flair workspace set`, and `flair orgevent` (flair#1288): the CLI validates
+ * before any signing/network work so a malformed entity is rejected
+ * client-side with an error that names the `type:value` format and
+ * enumerates the closed type set. The server independently re-validates on
+ * every write path (resources/Memory.ts / WorkspaceState.ts / OrgEvent.ts via
+ * invalidEntitiesResponse) — this module is UX, not the security gate.
+ */
+/** The closed set of entity types. Mirror of resources/entity-vocab.ts — extend BOTH together. */
+export const ENTITY_TYPES = [
+    "repo",
+    "issue",
+    "customer",
+    "subsystem",
+    "agent",
+    "person",
+];
+const ENTITY_TYPE_SET = new Set(ENTITY_TYPES);
+/**
+ * A "slug" value: lowercase alphanumeric segments joined by single `-` or
+ * `_` separators. Used for `customer:`, `subsystem:`, `agent:`, `person:`.
+ */
+const SLUG_RE = /^[a-z0-9]+(?:[-_][a-z0-9]+)*$/;
+/** A single repo path segment (owner or name): lowercase alphanumeric with `.`, `-`, `_` internal. */
+const REPO_SEGMENT_RE = /^[a-z0-9]+(?:[.\-_][a-z0-9]+)*$/;
+/** `<owner>/<name>` — both segments valid, exactly one `/`. */
+function isValidRepoValue(value) {
+    const parts = value.split("/");
+    if (parts.length !== 2)
+        return false;
+    const [owner, name] = parts;
+    return REPO_SEGMENT_RE.test(owner) && REPO_SEGMENT_RE.test(name);
+}
+/** `<owner>/<name>#<n>` — a valid repo value, `#`, then a positive integer (no leading zero). */
+function isValidIssueValue(value) {
+    const hashIndex = value.indexOf("#");
+    if (hashIndex === -1)
+        return false;
+    const repoPart = value.slice(0, hashIndex);
+    const numberPart = value.slice(hashIndex + 1);
+    if (!/^[1-9][0-9]*$/.test(numberPart))
+        return false;
+    return isValidRepoValue(repoPart);
+}
+function isValidSlugValue(value) {
+    return SLUG_RE.test(value);
+}
+const VALUE_VALIDATORS = {
+    repo: isValidRepoValue,
+    issue: isValidIssueValue,
+    customer: isValidSlugValue,
+    subsystem: isValidSlugValue,
+    agent: isValidSlugValue,
+    person: isValidSlugValue,
+};
+/** Split an entity string on its first `:` into { type, value }; null if it can't be well-formed. */
+function parseEntity(entity) {
+    if (typeof entity !== "string" || entity.length === 0)
+        return null;
+    const colonIndex = entity.indexOf(":");
+    if (colonIndex <= 0)
+        return null; // no colon, or colon is the first char (empty type)
+    const type = entity.slice(0, colonIndex);
+    const value = entity.slice(colonIndex + 1);
+    if (value.length === 0)
+        return null;
+    return { type, value };
+}
+/** Full validation: well-formed `type:value`, type in the closed set, value matches the type's grammar. */
+export function isValidEntity(entity) {
+    if (typeof entity !== "string")
+        return false;
+    const parsed = parseEntity(entity);
+    if (!parsed)
+        return false;
+    if (!ENTITY_TYPE_SET.has(parsed.type))
+        return false;
+    return VALUE_VALIDATORS[parsed.type](parsed.value);
+}
+/**
+ * Canonical "what does well-formed look like" hint (flair#1288): names the
+ * `type:value` format AND enumerates the closed type set, so the rejection
+ * enables a response. Must produce the EXACT string resources/entity-vocab.ts's
+ * entityFormatHint() produces — the sync test compares them verbatim.
+ */
+export function entityFormatHint() {
+    return `entities are 'type:value' vocabulary strings (e.g. 'repo:owner/name'); valid types: ${ENTITY_TYPES.join(", ")}`;
+}
+/**
+ * Parse a `--entities <csv>` option value: comma-split, trim, drop empties —
+ * the same list-option convention `--tags <csv>` / `--derived-from <csv>`
+ * already use (safe here because no entity grammar admits a comma) — then
+ * validate each element against the vocabulary.
+ */
+export function parseEntitiesCsv(csv) {
+    const entities = String(csv).split(",").map((x) => x.trim()).filter(Boolean);
+    const invalid = entities.filter((e) => !isValidEntity(e));
+    return { entities, invalid };
+}