Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
9.7 KB
Raw Blame
/**
 * `o2b install --friction` — the operator surface of the friction matrix.
 *
 * The verb's other modes are covered by `install-verb.test.ts`; this file
 * covers the comparison mode and the two properties it exists for: the
 * table is derived from the live registry, and the DIFF form names only
 * the dimensions the two hosts answer differently. A diff that reprints
 * the dimensions they share is a table, so the silence is asserted
 * against the matrix itself rather than against a copied list.
 */

import { describe, expect, test, beforeEach, afterEach, setDefaultTimeout } from "bun:test";
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";

import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";
import { runCli as baseRunCli, type RunCliOptions, type RunResult } from "../helpers/run-cli.ts";
import { INSTALL_EXIT } from "../../src/cli/install/install.ts";
import { FRICTION_DIMENSIONS } from "../../src/core/install/friction.ts";
import { INSTALL_TARGET_IDS } from "../../src/core/runtime/host-facts.ts";

// The adapters resolve the target home at module-load time, so each call
// needs a fresh process to honour this file's per-case temp HOME.
function runCli(args: ReadonlyArray<string>, opts: RunCliOptions = {}): Promise<RunResult> {
  return baseRunCli(args, { ...opts, subprocess: true });
}

setDefaultTimeout(CLI_SPAWN_BUDGET_MS);

let vault: string;
let home: string;
let configPath: string;

beforeEach(() => {
  vault = mkdtempSync(join(tmpdir(), "osb-friction-cli-v-"));
  home = mkdtempSync(join(tmpdir(), "osb-friction-cli-h-"));
  configPath = join(home, "config.yaml");
  writeFileSync(configPath, `vault: "${vault}"\nagent_name: "claude-vps"\ntimezone: "UTC"\n`);
});

afterEach(() => {
  for (const p of [vault, home]) {
    try {
      rmSync(p, { recursive: true, force: true });
    } catch {
      // temp cleanup is best-effort
    }
  }
});

function envBase(extra: Record<string, string> = {}) {
  return {
    HOME: home,
    OPEN_SECOND_BRAIN_CONFIG: configPath,
    VAULT_DIR: vault,
    VAULT_AGENT_NAME: "claude-vps",
    VAULT_TIMEZONE: "UTC",
    ...extra,
  };
}

/**
 * The identifier tokens of `text`, split on everything an id cannot hold.
 *
 * Plain containment let a SHORTER id ride on a longer one:
 * `"copilot-cli".includes("pi")` is true, so "every registered target is
 * listed" held for a table that had dropped the `pi` row entirely, and the
 * refusal message satisfied all ten names while offering nine. A token set
 * answers the question the assertion means to ask.
 */
function tokensOf(text: string): ReadonlySet<string> {
  return new Set(text.split(/[^A-Za-z0-9_-]+/).filter((token) => token.length > 0));
}

interface FrictionCellJson {
  readonly dimension: string;
  readonly value: string;
  readonly detail: string | null;
}

interface FrictionTargetJson {
  readonly target: string;
  readonly label: string;
  readonly cells: ReadonlyArray<FrictionCellJson>;
}

interface FrictionJson {
  readonly schema_version: number;
  readonly friction: {
    readonly dimensions: ReadonlyArray<string>;
    readonly targets: ReadonlyArray<FrictionTargetJson>;
  };
}

interface FrictionDiffJson {
  readonly schema_version: number;
  readonly friction_diff: {
    readonly base: string;
    readonly compare: string;
    readonly shared: number;
    readonly differing: ReadonlyArray<{
      readonly dimension: string;
      readonly base_value: string;
      readonly compare_value: string;
    }>;
  };
}

async function frictionJson(extra: ReadonlyArray<string> = []): Promise<FrictionJson> {
  const r = await runCli(["install", "--friction", "--json", ...extra], { env: envBase() });
  expect(`exit ${r.returncode}\n${r.stderr}`).toBe("exit 0\n");
  return JSON.parse(r.stdout) as FrictionJson;
}

describe("o2b install --friction — the matrix", () => {
  test("the human table carries every registered target and every dimension", async () => {
    const r = await runCli(["install", "--friction"], { env: envBase() });
    expect(r.returncode).toBe(INSTALL_EXIT.ok);
    const printed = tokensOf(r.stdout);
    for (const target of INSTALL_TARGET_IDS) {
      expect(`${target} listed: ${printed.has(target)}`).toBe(`${target} listed: true`);
    }
    for (const dimension of FRICTION_DIMENSIONS) {
      expect(`${dimension} listed: ${printed.has(dimension)}`).toBe(`${dimension} listed: true`);
    }
  });

  test("--json is machine-readable and versioned", async () => {
    const payload = await frictionJson();
    expect(payload.schema_version).toBe(1);
    expect(payload.friction.dimensions).toEqual([...FRICTION_DIMENSIONS]);
    expect(payload.friction.targets.map((t) => t.target).toSorted()).toEqual(
      [...INSTALL_TARGET_IDS].toSorted(),
    );
    for (const target of payload.friction.targets) {
      expect(target.cells.map((c) => c.dimension)).toEqual([...FRICTION_DIMENSIONS]);
    }
  });

  test("--target narrows the matrix to one host", async () => {
    const payload = await frictionJson(["--target", "cursor"]);
    expect(payload.friction.targets.map((t) => t.target)).toEqual(["cursor"]);
  });

  test("an unknown --target is refused by name, with the known list", async () => {
    const r = await runCli(["install", "--friction", "--target", "claude-code"], {
      env: envBase(),
    });
    expect(r.returncode).toBe(INSTALL_EXIT.usage);
    expect(r.stderr).toContain("claude-code");
    const offered = tokensOf(r.stderr);
    for (const target of INSTALL_TARGET_IDS) {
      expect(`${target} offered: ${offered.has(target)}`).toBe(`${target} offered: true`);
    }
  });
});

describe("o2b install --friction --base <a> --compare <b> — the diff", () => {
  test("it names every dimension the two answer differently and no other", async () => {
    const matrix = await frictionJson();
    const row = (target: string): ReadonlyArray<FrictionCellJson> =>
      matrix.friction.targets.find((t) => t.target === target)!.cells;
    const r = await runCli(
      ["install", "--friction", "--base", "cursor", "--compare", "pi", "--json"],
      { env: envBase() },
    );
    expect(`exit ${r.returncode}\n${r.stderr}`).toBe("exit 0\n");
    const diff = (JSON.parse(r.stdout) as FrictionDiffJson).friction_diff;
    const named = new Set(diff.differing.map((d) => d.dimension));
    const wrong: string[] = [];
    for (const dimension of FRICTION_DIMENSIONS) {
      const base = row("cursor").find((c) => c.dimension === dimension)!;
      const compare = row("pi").find((c) => c.dimension === dimension)!;
      if ((base.value !== compare.value) !== named.has(dimension)) wrong.push(dimension);
    }
    expect(wrong.join(", ")).toBe("");
    expect(diff.differing.length).toBeGreaterThan(0);
    expect(diff.differing.length + diff.shared).toBe(FRICTION_DIMENSIONS.length);
  });

  test("the human diff prints the differing dimensions and says how many it withheld", async () => {
    const r = await runCli(["install", "--friction", "--base", "cursor", "--compare", "pi"], {
      env: envBase(),
    });
    expect(r.returncode).toBe(INSTALL_EXIT.ok);
    // `pi` as a whole token: `copilot-cli` contains it as a substring, so
    // plain containment would have accepted a diff that never named it.
    const printed = tokensOf(r.stdout);
    expect(`cursor: ${printed.has("cursor")}, pi: ${printed.has("pi")}`).toBe(
      "cursor: true, pi: true",
    );
    expect(r.stdout).toContain("differ");
  });

  test("--base without --compare is a usage error naming the missing flag", async () => {
    const r = await runCli(["install", "--friction", "--base", "cursor"], { env: envBase() });
    expect(r.returncode).toBe(INSTALL_EXIT.usage);
    expect(r.stderr).toContain("--compare");
  });

  test("an unknown --compare is refused by name", async () => {
    const r = await runCli(
      ["install", "--friction", "--base", "cursor", "--compare", "claude-code"],
      { env: envBase() },
    );
    expect(r.returncode).toBe(INSTALL_EXIT.usage);
    expect(r.stderr).toContain("claude-code");
  });

  test("--target alongside --base/--compare is refused rather than silently ignored", async () => {
    const r = await runCli(
      ["install", "--friction", "--target", "cursor", "--base", "cursor", "--compare", "pi"],
      { env: envBase() },
    );
    expect(r.returncode).toBe(INSTALL_EXIT.usage);
    expect(r.stderr).toContain("--target");
  });
});

describe("the flags the friction mode added are advertised", () => {
  test("help --json declares every flag o2b install parses", async () => {
    const r = await runCli(["help", "--json"], { env: envBase() });
    expect(r.returncode).toBe(0);
    const manifest = JSON.parse(r.stdout) as {
      commands: ReadonlyArray<{
        name: string;
        flags?: ReadonlyArray<{ name: string; inherited?: boolean }>;
      }>;
    };
    const install = manifest.commands.find((c) => c.name === "install");
    // `--json` is inherited by every verb and stated once in the help
    // header, so parity is asserted over the flags this verb DECLARES.
    const declared = (install?.flags ?? [])
      .filter((f) => f.inherited !== true)
      .map((f) => f.name)
      .toSorted();
    expect(declared).toEqual(
      [
        "apply",
        "base",
        "check",
        "compare",
        "config",
        "dry-run",
        "force",
        "format",
        "friction",
        // Declared by the verb itself (the consent refusal names --json),
        // for the reason `yes` is: help --json must model the whole
        // surface the parser takes.
        "json",
        "out",
        "target",
        "vault",
        // The apply lane's consent flag (t_b6bcd984): parsed by the
        // verb since its consent ladder landed, so help --json must
        // declare it like the rest instead of hiding the remedy.
        "yes",
      ].toSorted(),
    );
  });
});