freeharness 0.4.1 → 0.4.2

package/dist/cli/plugin-validate.js

@@ -20,6 +20,44 @@ export const HOOK_EVENTS = new Set([
 /** Plugin names are kebab-case (marketplace and `claude plugin install <name>@<market>`). */
 const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const SEMVER = /^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/;
+const PLUGIN_ROOT_TOKEN = "${CLAUDE_PLUGIN_ROOT}";
+/**
+ * The first unsafe `${CLAUDE_PLUGIN_ROOT}` use in a shell-form command: `unquoted` outside a
+ * double-quoted span (bare, the shell splits it on a plugin path with spaces; single-quoted, the
+ * shell never expands it), `escaped` behind a backslash-escaped dollar in or out of double quotes
+ * (the shell never expands it). Tracks quote state left to right, honoring backslash escapes
+ * outside single quotes (so `\"` opens no span); no shell grammar beyond that.
+ * @param command Shell command string.
+ * @returns The hazard of the first unsafe occurrence, or undefined when every use is safe.
+ */
+export function pluginRootHazard(command) {
+    let inDouble = false;
+    let inSingle = false;
+    for (let i = 0; i < command.length; i++) {
+        const c = command[i];
+        if (!inSingle && c === "\\") {
+            if (command.startsWith(PLUGIN_ROOT_TOKEN, i + 1))
+                return "escaped";
+            i++;
+            continue;
+        }
+        if (!inSingle && c === '"') {
+            inDouble = !inDouble;
+            continue;
+        }
+        if (!inDouble && c === "'") {
+            inSingle = !inSingle;
+            continue;
+        }
+        if (!inDouble && command.startsWith(PLUGIN_ROOT_TOKEN, i))
+            return "unquoted";
+    }
+    return undefined;
+}
+const PLUGIN_ROOT_HAZARD_TEXT = {
+    unquoted: "outside double quotes",
+    escaped: "behind an escaped dollar",
+};
 /**
  * Reads and parses a JSON file; a parse failure becomes one error.
  * @param file Path.
@@ -170,6 +208,8 @@ export function validatePluginDir(dir, opts = {}) {
                             errors.push(`hooks/hooks.json: ${event}[${i}].hooks[${j}].command missing`);
                         if (hook.timeout !== undefined && typeof hook.timeout !== "number")
                             errors.push(`hooks/hooks.json: ${event}[${i}].hooks[${j}].timeout must be a number`);
+                        if (hook.onFailure !== undefined && hook.onFailure !== "block" && hook.onFailure !== "continue")
+                            errors.push(`hooks/hooks.json: ${event}[${i}].hooks[${j}].onFailure must be block|continue`);
                         if (typeof hook.command === "string") {
                             for (const m of hook.command.matchAll(/\$\{CLAUDE_PLUGIN_ROOT\}\/([^\s"']+)/g)) {
                                 const target = path.join(root, m[1]);
@@ -178,6 +218,9 @@ export function validatePluginDir(dir, opts = {}) {
                             }
                             if (!hook.command.includes("${CLAUDE_PLUGIN_ROOT}") && /(^|\s)\/\S+/.test(hook.command))
                                 warnings.push(`hooks/hooks.json: ${event}[${i}].hooks[${j}] uses an absolute path instead of \${CLAUDE_PLUGIN_ROOT}`);
+                            const hazard = hook.type === "command" ? pluginRootHazard(hook.command) : undefined;
+                            if (hazard)
+                                warnings.push(`hooks/hooks.json: ${event}[${i}].hooks[${j}] uses \${CLAUDE_PLUGIN_ROOT} ${PLUGIN_ROOT_HAZARD_TEXT[hazard]}`);
                         }
                     });
                 });

package/dist/cli/uninstall.d.ts

@@ -1,6 +1,6 @@
 import type { Scope } from "@freeharness/core";
 /** Command substrings that identify the hook entries FreeHarness writes into settings.json. */
-export declare const OUR_HOOK_MARKERS: readonly ["freeharness-session-start", "freeharness-memory-guard", "freeharness-config-guard", "freeharness-repeat-tool", "freeharness-security-guidance", "freeharness-cost-tracker", "freeharness-output-pruner", "freeharness-context-monitor", "freeharness-precompact", "freeharness-auto-memory", "freeharness-converge"];
+export declare const OUR_HOOK_MARKERS: readonly ["freeharness-session-start", "freeharness-memory-guard", "freeharness-config-guard", "freeharness-repeat-tool", "freeharness-security-guidance", "freeharness-cost-tracker", "freeharness-output-pruner", "freeharness-context-monitor", "freeharness-precompact", "freeharness-auto-memory", "freeharness-converge", "freeharness-sdd-context", "freeharness-reload-context"];
 /** What an uninstall pass would (or did) do. */
 export interface UninstallPlan {
     manifest: string;

package/dist/cli/uninstall.js

@@ -8,7 +8,7 @@ import { manifestPath, readManifest } from "../infra/manifest.js";
 import { dataDir } from "../adapters/memory/doctor.js";
 import { PLUGIN_KEY, UPSTREAM_PLUGIN_NAME } from "../adapters/memory/vendored.js";
 /** Command substrings that identify the hook entries FreeHarness writes into settings.json. */
-export const OUR_HOOK_MARKERS = ["freeharness-session-start", "freeharness-memory-guard", "freeharness-config-guard", "freeharness-repeat-tool", "freeharness-security-guidance", "freeharness-cost-tracker", "freeharness-output-pruner", "freeharness-context-monitor", "freeharness-precompact", "freeharness-auto-memory", "freeharness-converge"];
+export const OUR_HOOK_MARKERS = ["freeharness-session-start", "freeharness-memory-guard", "freeharness-config-guard", "freeharness-repeat-tool", "freeharness-security-guidance", "freeharness-cost-tracker", "freeharness-output-pruner", "freeharness-context-monitor", "freeharness-precompact", "freeharness-auto-memory", "freeharness-converge", "freeharness-sdd-context", "freeharness-reload-context"];
 /**
  * Tells whether a hook entry is one FreeHarness wrote.
  * @param e A settings.json hook entry.
@@ -107,7 +107,7 @@ export function uninstallScope(scope, projectRoot, dryRun) {
             continue;
         }
         if (p.startsWith(pluginsDir) || (p + path.sep).startsWith(memData)) {
-            plan.kept.push({ path: p, reason: `claude-mem plugin/data: left alone (use \`claude plugin uninstall ${PLUGIN_KEY}\`)` });
+            plan.kept.push({ path: p, reason: `memory plugin/data: left alone (use \`claude plugin uninstall ${PLUGIN_KEY}\`)` });
             continue;
         }
         if (!fs.existsSync(p)) {

package/dist/cli/upstream-launchers.d.ts

@@ -0,0 +1,49 @@
+import type { CleanupItem } from "./cleanup.js";
+/** Client configs under HOME that may launch the upstream MCP server, with the key holding their servers. */
+export declare const UPSTREAM_LAUNCHER_FILES: ReadonlyArray<{
+    rel: string;
+    key: "mcpServers" | "mcp";
+}>;
+/** The upstream marketplace clone under the Claude Code config dir; Claude Code re-installs the upstream plugin from it. */
+export declare const UPSTREAM_MARKETPLACE_DIR: string;
+/** Registrations of the upstream marketplace, relative to the Claude Code config dir. */
+export declare const UPSTREAM_MARKETPLACE_KEYS: ReadonlyArray<{
+    rel: string;
+    keyPath: string[];
+}>;
+/** A free-mem path wins over every upstream sign, so our own MCP server is never edited away. */
+export declare function isUpstreamMcpEntry(name: string, entry: unknown): boolean;
+/** Server names come from files other programs write and reach the terminal through the plan lines. */
+export declare function launcherText(s: string): string;
+/** The copy path names the file it restores; a file outside HOME has none, so it is refused rather than edited without a copy. */
+export declare function configCopyArchive(file: string, home: string, archiveRoot: string): {
+    destination: string;
+    refused?: string;
+};
+export interface LauncherScope {
+    home: string;
+    /** The Claude Code config dir. */
+    cfg: string;
+    archiveRoot: string;
+    /** Set while the upstream plugin is enabled: removing its marketplace then breaks a live install. */
+    marketplaceRefusal?: string;
+}
+/** The launcher memory items of the fixed list; reads only. */
+export declare function planUpstreamLaunchers(scope: LauncherScope): {
+    items: CleanupItem[];
+    notes: string[];
+};
+/** Why a planned marketplace move must not run now; the destination stays in its own inbox so it never lands over other archive content. */
+export declare function marketplaceRefusal(source: string, dest: string, archiveRoot: string | undefined): string | undefined;
+/** A launcher line in a file cleanup never writes; `text` is the raw line, kept off the terminal. */
+export interface ReportOnlyMatch {
+    file: string;
+    line: number;
+    text: string;
+}
+/** No TOML parser may be added and an rc edit can break the owner's shell, so these are only named, never edited. */
+export declare const REPORT_ONLY_FILES: readonly string[];
+/** Upstream launchers in the Codex config and the shell rc files under `home`; reads only and never throws. */
+export declare function scanReportOnly(home: string): ReportOnlyMatch[];
+/** Pass 2 re-check per launcher item, so a value rewritten since pass 1 is left as the other program wrote it. */
+export declare function launcherStillMatches(item: CleanupItem): ((value: unknown) => boolean) | undefined;

package/dist/cli/upstream-launchers.js

@@ -0,0 +1,287 @@
+// Another MCP client restarting the upstream worker on free-mem's port survives every reboot, so
+// cleanup must reach those launchers; it reaches them only through this fixed file list and one
+// fixed entry rule, since discovery could edit a config nobody asked it to touch.
+import fs from "node:fs";
+import path from "node:path";
+import { UPSTREAM_MARKETPLACE_OWNER, UPSTREAM_PLUGIN_NAME } from "../adapters/memory/vendored.js";
+import { freeDestination } from "./hard-cleanup.js";
+/** Client configs under HOME that may launch the upstream MCP server, with the key holding their servers. */
+export const UPSTREAM_LAUNCHER_FILES = [
+    { rel: path.join(".gemini", "config", "mcp_config.json"), key: "mcpServers" },
+    { rel: path.join(".gemini", "antigravity", "mcp_config.json"), key: "mcpServers" },
+    { rel: path.join(".gemini", "antigravity-ide", "mcp_config.json"), key: "mcpServers" },
+    { rel: path.join(".gemini", "antigravity-backup", "mcp_config.json"), key: "mcpServers" },
+    { rel: path.join(".gemini", "settings.json"), key: "mcpServers" },
+    { rel: path.join("Library", "Application Support", "Claude", "claude_desktop_config.json"), key: "mcpServers" },
+    { rel: path.join(".cursor", "mcp.json"), key: "mcpServers" },
+    { rel: path.join(".config", "opencode", "opencode.json"), key: "mcp" },
+];
+/** The upstream marketplace clone under the Claude Code config dir; Claude Code re-installs the upstream plugin from it. */
+export const UPSTREAM_MARKETPLACE_DIR = path.join("plugins", "marketplaces", UPSTREAM_MARKETPLACE_OWNER);
+/** Registrations of the upstream marketplace, relative to the Claude Code config dir. */
+export const UPSTREAM_MARKETPLACE_KEYS = [
+    { rel: path.join("plugins", "known_marketplaces.json"), keyPath: [UPSTREAM_MARKETPLACE_OWNER] },
+    { rel: "settings.json", keyPath: ["extraKnownMarketplaces", UPSTREAM_MARKETPLACE_OWNER] },
+];
+const OURS = ["plugins/cache/freeharness", "plugins/marketplaces/freeharness"];
+const PACKAGE_TOKEN = new RegExp(`(^|[\\s/@])${UPSTREAM_PLUGIN_NAME}($|[\\s/@])`);
+const ANSI_SEQUENCE = /\u001b\[[0-?]*[ -/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g;
+const UNPRINTABLE = /[\u0000-\u001f\u007f-\u009f\p{Cf}\p{Zl}\p{Zp}]|[\ud800-\udfff]/gu;
+const NAME_MAX = 64;
+function isPlainObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function strings(v) {
+    if (typeof v === "string")
+        return [v];
+    return Array.isArray(v) ? v.filter((s) => typeof s === "string") : [];
+}
+/** A free-mem path wins over every upstream sign, so our own MCP server is never edited away. */
+export function isUpstreamMcpEntry(name, entry) {
+    if (!isPlainObject(entry))
+        return false;
+    const args = Array.isArray(entry.args) ? strings(entry.args) : [];
+    const text = [...strings(entry.command), ...args].join(" ").replace(/\\/g, "/");
+    if (OURS.some((p) => text.includes(p)))
+        return false;
+    return name === UPSTREAM_PLUGIN_NAME || text.includes(UPSTREAM_MARKETPLACE_OWNER) || text.includes(`${UPSTREAM_PLUGIN_NAME}@`) || PACKAGE_TOKEN.test(text);
+}
+/** Server names come from files other programs write and reach the terminal through the plan lines. */
+export function launcherText(s) {
+    return Array.from(s.replace(ANSI_SEQUENCE, "").replace(UNPRINTABLE, "")).slice(0, NAME_MAX).join("");
+}
+/** The copy path names the file it restores; a file outside HOME has none, so it is refused rather than edited without a copy. */
+export function configCopyArchive(file, home, archiveRoot) {
+    const inbox = path.join(archiveRoot, "configs");
+    const rel = path.relative(home, file);
+    if (rel === "" || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+        return { destination: inbox, refused: `is outside the home dir, so its pre-edit copy has no place under ${inbox}` };
+    }
+    return { destination: path.join(inbox, rel) };
+}
+/** Only a regular file (or a link to one) is read; non-blocking, so a FIFO swapped in after the check cannot hang the plan. */
+function readJsonObject(file) {
+    let fd;
+    try {
+        if (!fs.statSync(file).isFile())
+            return { state: "absent" };
+        fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
+        if (!fs.fstatSync(fd).isFile())
+            return { state: "absent" };
+        const root = JSON.parse(fs.readFileSync(fd, "utf8"));
+        return isPlainObject(root) ? { state: "object", root } : { state: "invalid", why: "not a JSON object" };
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return { state: "absent" };
+        return { state: "invalid", why: e instanceof SyntaxError ? "not valid JSON" : `unreadable (${code ?? "error"})` };
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+function hasKeyPath(root, keyPath) {
+    let node = root;
+    for (const key of keyPath) {
+        if (!isPlainObject(node) || !Object.prototype.hasOwnProperty.call(node, key))
+            return false;
+        node = node[key];
+    }
+    return true;
+}
+function isRealDir(p) {
+    try {
+        return fs.lstatSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** The launcher memory items of the fixed list; reads only. */
+export function planUpstreamLaunchers(scope) {
+    const items = [];
+    const notes = [];
+    const configs = path.join(scope.archiveRoot, "configs");
+    for (const { rel, key } of UPSTREAM_LAUNCHER_FILES) {
+        const file = path.join(scope.home, rel);
+        const read = readJsonObject(file);
+        if (read.state === "absent")
+            continue;
+        if (read.state === "invalid") {
+            notes.push(`${file}: ${read.why}; its upstream ${UPSTREAM_PLUGIN_NAME} launchers are not checked`);
+            continue;
+        }
+        if (!Object.prototype.hasOwnProperty.call(read.root, key))
+            continue;
+        const servers = read.root[key];
+        if (!isPlainObject(servers)) {
+            notes.push(`${file}: "${key}" is not an object; its upstream ${UPSTREAM_PLUGIN_NAME} launchers are not checked`);
+            continue;
+        }
+        for (const [name, entry] of Object.entries(servers)) {
+            if (!isUpstreamMcpEntry(name, entry))
+                continue;
+            const reason = `upstream ${UPSTREAM_PLUGIN_NAME} MCP server "${launcherText(name)}" (another client starts the upstream worker)`;
+            items.push({ kind: "json-key", target: file, reason, group: "memory", keyPath: [key, name], archiveDest: path.join(configs, rel), launcher: "mcp" });
+        }
+    }
+    const refused = scope.marketplaceRefusal;
+    const market = path.join(scope.cfg, UPSTREAM_MARKETPLACE_DIR);
+    if (isRealDir(market)) {
+        const archiveDest = freeDestination(path.join(scope.archiveRoot, "plugins", "marketplaces", UPSTREAM_MARKETPLACE_OWNER));
+        items.push({ kind: "dir", target: market, reason: `upstream ${UPSTREAM_MARKETPLACE_OWNER} marketplace clone (the upstream plugin installs from it)`, group: "memory", archiveDest, launcher: "marketplace", refused });
+    }
+    for (const { rel, keyPath } of UPSTREAM_MARKETPLACE_KEYS) {
+        const file = path.join(scope.cfg, rel);
+        const read = readJsonObject(file);
+        if (read.state !== "object" || !hasKeyPath(read.root, keyPath))
+            continue;
+        const copy = configCopyArchive(file, scope.home, scope.archiveRoot);
+        items.push({ kind: "json-key", target: file, reason: `upstream ${UPSTREAM_MARKETPLACE_OWNER} marketplace registration`, group: "memory", keyPath, archiveDest: copy.destination, launcher: "marketplace", refused: refused ?? copy.refused });
+    }
+    return { items, notes };
+}
+/** Why a planned marketplace move must not run now; the destination stays in its own inbox so it never lands over other archive content. */
+export function marketplaceRefusal(source, dest, archiveRoot) {
+    if (archiveRoot === undefined)
+        return "no archive root in the plan";
+    const inbox = path.join(archiveRoot, "plugins", "marketplaces");
+    const rel = path.relative(inbox, dest);
+    if (rel === "" || rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel))
+        return `destination ${dest} is outside ${inbox}`;
+    // A link or file put there since pass 1 is not the clone the plan listed.
+    try {
+        if (!fs.lstatSync(source).isDirectory())
+            return "is no longer a directory";
+    }
+    catch {
+        // gone: the move reports it
+    }
+    return undefined;
+}
+const CODEX_CONFIG = path.join(".codex", "config.toml");
+/** No TOML parser may be added and an rc edit can break the owner's shell, so these are only named, never edited. */
+export const REPORT_ONLY_FILES = [CODEX_CONFIG, ".zshrc", ".zprofile", ".bashrc", ".bash_profile", ".profile"];
+const REPORT_ONLY_MAX_BYTES = 1024 * 1024;
+const TOML_SERVER_HEADER = /^\s*\[\s*mcp_servers\s*\.\s*(?:"((?:[^"\\]|\\.)*)"|([A-Za-z0-9_-]+))\s*\]\s*(?:#.*)?$/;
+const TOML_KEY = /^\s*(command|args)\s*=/;
+const TOML_STRING = /"((?:[^"\\]|\\.)*)"|'([^']*)'/g;
+// Shell words end at quotes, `=`, `;` and the like, so the package token is bounded by anything a file name cannot hold.
+const RC_PACKAGE_TOKEN = new RegExp(`(^|[^A-Za-z0-9_.-])${UPSTREAM_PLUGIN_NAME}($|[^A-Za-z0-9_.-])`);
+const RC_RUNNER = /(^|[^A-Za-z0-9_.-])(npx|bunx|node)(\s|$)/g;
+const WORKER_SCRIPT = "worker-service.cjs";
+/** The text of a small regular file (or the file a link names), or undefined; a FIFO or an oversized file is never read through. */
+function readSmallText(file) {
+    let fd;
+    try {
+        if (!fs.statSync(file).isFile())
+            return undefined;
+        fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
+        const st = fs.fstatSync(fd);
+        if (!st.isFile() || st.size > REPORT_ONLY_MAX_BYTES)
+            return undefined;
+        // Bounded read: a file grown since fstat is skipped rather than read past the cap.
+        const buf = Buffer.alloc(REPORT_ONLY_MAX_BYTES + 1);
+        let total = 0;
+        for (let n = 1; n > 0 && total < buf.length; total += n)
+            n = fs.readSync(fd, buf, total, buf.length - total, null);
+        return total > REPORT_ONLY_MAX_BYTES ? undefined : buf.subarray(0, total).toString("utf8");
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // the scan never throws
+            }
+        }
+    }
+}
+function tomlStrings(line) {
+    return Array.from(line.matchAll(TOML_STRING), (m) => (m[1] !== undefined ? m[1].replace(/\\(.)/g, "$1") : m[2] ?? ""));
+}
+function withoutTomlStrings(line) {
+    return line.replace(TOML_STRING, "");
+}
+/** A line scan, not a parse: only `[mcp_servers.<name>]` tables and their `command`/`args` values are read. */
+function scanCodexTables(lines) {
+    const hits = [];
+    let table;
+    let inArgs = false;
+    const close = () => {
+        if (table && isUpstreamMcpEntry(table.name, { command: table.command.join(" "), args: table.args }))
+            hits.push(table.header);
+        table = undefined;
+        inArgs = false;
+    };
+    lines.forEach((line, i) => {
+        if (line.trimStart().startsWith("[")) {
+            close();
+            const header = TOML_SERVER_HEADER.exec(line);
+            if (header)
+                table = { name: header[1] !== undefined ? header[1].replace(/\\(.)/g, "$1") : header[2] ?? "", header: i + 1, command: [], args: [] };
+            return;
+        }
+        if (!table)
+            return;
+        if (inArgs) {
+            table.args.push(...tomlStrings(line));
+            if (withoutTomlStrings(line).includes("]"))
+                inArgs = false;
+            return;
+        }
+        const key = TOML_KEY.exec(line);
+        if (!key)
+            return;
+        const value = line.slice(key[0].length);
+        if (key[1] === "command") {
+            table.command.push(...tomlStrings(value));
+            return;
+        }
+        table.args.push(...tomlStrings(value));
+        const bare = withoutTomlStrings(value);
+        inArgs = bare.includes("[") && !bare.includes("]");
+    });
+    close();
+    return hits;
+}
+/** The owner decides about a commented line, so a leading `#` does not hide a match. */
+function isRcLauncherLine(line) {
+    if (line.includes(WORKER_SCRIPT) && (line.includes(UPSTREAM_MARKETPLACE_OWNER) || RC_PACKAGE_TOKEN.test(line)))
+        return true;
+    for (const runner of line.matchAll(RC_RUNNER)) {
+        if (RC_PACKAGE_TOKEN.test(line.slice((runner.index ?? 0) + runner[0].length)))
+            return true;
+    }
+    return false;
+}
+/** Upstream launchers in the Codex config and the shell rc files under `home`; reads only and never throws. */
+export function scanReportOnly(home) {
+    const out = [];
+    for (const rel of REPORT_ONLY_FILES) {
+        const file = path.join(home, rel);
+        const text = readSmallText(file);
+        if (text === undefined)
+            continue;
+        const lines = text.split("\n").map((l) => (l.endsWith("\r") ? l.slice(0, -1) : l));
+        const hits = rel === CODEX_CONFIG ? scanCodexTables(lines) : lines.flatMap((l, i) => (isRcLauncherLine(l) ? [i + 1] : []));
+        for (const line of hits)
+            out.push({ file, line, text: lines[line - 1] ?? "" });
+    }
+    return out;
+}
+/** Pass 2 re-check per launcher item, so a value rewritten since pass 1 is left as the other program wrote it. */
+export function launcherStillMatches(item) {
+    const name = item.keyPath?.[item.keyPath.length - 1];
+    if (item.launcher === "mcp" && name !== undefined)
+        return (value) => isUpstreamMcpEntry(name, value);
+    if (item.launcher === "marketplace")
+        return (value) => value !== undefined;
+    return undefined;
+}