Skip to content
Python
22.4 KB
Raw Blame
/** The `.codebuddy-plugin` install shape, as WorkBuddy actually loads it.
 *
 * Every other host this installer supports takes one entry in one config file.
 * A plugin is different in kind: it is a self-contained directory the host
 * copies, plus one key in each of three registries the host owns. That is why
 * this dialect exists as its own module — the unit of install is a tree, not a
 * line.
 *
 * The shape below was read out of WorkBuddy 5.5.0's own bundle
 * (`/Applications/WorkBuddy.app/Contents/Resources/app.asar`, whose comments
 * ship unminified) rather than from documentation, because two of the three
 * registries are not mentioned in any docs and one of them is the difference
 * between "installed" and "loaded":
 *
 * - `plugins/known_marketplaces.json` → `[name].installLocation` is the
 *   authoritative marketplace root (`resolveMarketplaceRoot`).
 * - `<marketplaceRoot>/.codebuddy-plugin/marketplace.json` → the entry whose
 *   `name` matches, with the plugin directory at `marketplaceRoot + source`
 *   (`resolvePluginSourceFromManifest`). This copy is what skills load from.
 * - `plugins/installed_plugins.json` → the cache snapshot MCP servers load
 *   from. `computePluginMcpConfigs` says so in as many words: "marketplace
 *   source is not used as a fallback".
 * - `settings.json` → `enabledPlugins["<plugin>@<marketplace>"]` must be
 *   `true`. Without it the plugin is installed and never projected: the host
 *   builds its server set from the enabled ids, and ours is not one of the
 *   five in `DEFAULT_ENABLED_PLUGIN_IDS`. This is the file that makes the
 *   difference between an install that looks healthy and one that works.
 */

import { createHash } from "node:crypto";
import { failOpenHookCommand, quoteCaptureCommand } from "./capture-hooks.js";

const MARKETPLACE_MANIFEST = ".codebuddy-plugin/marketplace.json";
const PLUGIN_MANIFEST = ".codebuddy-plugin/plugin.json";
export const PLUGIN_HOOKS = "hooks/hooks.json";

/** Where a plugin-format host keeps the trees and registries recall touches. */
export interface CodebuddyPluginTarget {
  marketplaceName: string;
  pluginName: string;
  /** The skill directory hosts list by name. Kept apart from `pluginName`,
   * which registries key installs by and so cannot change under them. */
  skillName: string;
  /** Named in `installed_plugins.json` and used as the cache directory name.
   *
   * Fixed rather than derived from content: the host re-reads both copies off
   * disk, so a new directory per build would only leave old ones to collect.
   */
  version: string;
  /** `<hostDir>/plugins/marketplaces/<marketplaceName>` — ours outright. */
  marketplaceRoot: string;
  /** `<hostDir>/plugins/cache/<marketplaceName>` — ours outright, and the
   * highest directory of the cache copy that belongs to us, so it is what
   * uninstall removes. */
  cacheRoot: string;
  /** `<cacheRoot>/<pluginName>/<version>` — the snapshot MCP loads from. */
  installRoot: string;
  knownMarketplacesPath: string;
  installedPluginsPath: string;
  settingsPath: string;
}

/** `<plugin>@<marketplace>`, the id both registries key on. */
export function pluginId(target: CodebuddyPluginTarget): string {
  return `${target.pluginName}@${target.marketplaceName}`;
}

/** One shared file the host owns, and the single key in it that is ours.
 *
 * `seed` is only used when the file has to be created: `installed_plugins.json`
 * carries a schema version beside its map, and a file holding just our key
 * would be a file the host cannot read.
 */
export interface PluginRegistry {
  path: string;
  keyPath: string[];
  seed: Record<string, unknown>;
}

export function pluginRegistries(
  target: CodebuddyPluginTarget,
): PluginRegistry[] {
  return [
    {
      path: target.knownMarketplacesPath,
      keyPath: [target.marketplaceName],
      seed: {},
    },
    {
      path: target.installedPluginsPath,
      keyPath: ["plugins", pluginId(target)],
      seed: { version: 2, plugins: {} },
    },
    {
      path: target.settingsPath,
      keyPath: ["enabledPlugins", pluginId(target)],
      seed: {},
    },
  ];
}

/** The values our three registry keys hold when recall is installed.
 *
 * No `installedAt` or `lastUpdated`, though the host writes both on its own
 * installs. They are optional everywhere they are read — `installLocation` is
 * the only field `resolveMarketplaceRoot` looks at, and
 * `selectDaemonPluginCacheRecord` requires `installPath`, `version` and
 * `scope`, using the timestamps only to order several records of one plugin.
 * A timestamp made up at plan time would also make two plans of the same
 * install differ, which would spend the user's approval on nothing: the
 * preview fingerprint covers the exact bytes. When we installed is recorded in
 * our own journal, where it is true and where nobody else has to parse it.
 */
export function registryEntry(
  target: CodebuddyPluginTarget,
  registry: PluginRegistry,
): unknown {
  if (registry.path === target.knownMarketplacesPath) {
    return {
      type: "directory",
      source: { source: "directory", path: target.marketplaceRoot },
      installLocation: target.marketplaceRoot,
      description: `Marketplace from ${target.marketplaceRoot}`,
      autoUpdate: false,
    };
  }
  if (registry.path === target.installedPluginsPath) {
    // An array of one: the host stores several records per plugin so a managed
    // and a user install can coexist, and reads the highest-priority one.
    return [
      {
        scope: "user",
        installPath: target.installRoot,
        version: target.version,
      },
    ];
  }
  return true;
}

/** Whether a registry key holds an entry this installer wrote.
 *
 * Recognition is by the paths it points at rather than by a marker key of ours:
 * these are the host's own documents and an unknown field in them is a change
 * we would have to defend. Anything claiming our marketplace name while
 * pointing somewhere else is somebody else's, and refused.
 */
export function isManagedRegistryEntry(
  target: CodebuddyPluginTarget,
  registry: PluginRegistry,
  value: unknown,
): boolean {
  if (registry.path === target.knownMarketplacesPath) {
    if (!isRecord(value)) return false;
    return (
      value.type === "directory" &&
      value.installLocation === target.marketplaceRoot
    );
  }
  if (registry.path === target.installedPluginsPath) {
    const records = Array.isArray(value) ? value : [value];
    return (
      records.length > 0 &&
      records.every(
        (record) =>
          isRecord(record) && record.installPath === target.installRoot,
      )
    );
  }
  // Enablement is a bare boolean, so there is nothing in it to own. Either
  // value is the user's to have set, and both are restored verbatim.
  return typeof value === "boolean";
}

/** The files of the plugin tree, relative to the root they are written under.
 *
 * The marketplace copy and the cache copy differ by one file: only the
 * marketplace has the manifest listing its plugins. Everything else is the same
 * bytes in both, because the host reads skills from the marketplace copy and
 * MCP servers from the cache copy, and the two disagreeing would mean the model
 * is told about a tool that is configured differently.
 */
export interface PluginFile {
  relativePath: string;
  content: string;
}

/** What the recall injection hook needs to reach the broker as this install. */
export interface InjectionHookRuntime {
  runtimeCommand: string;
  recallCliPath: string;
  discoveryPath: string;
  credentialFile?: string;
  dataDir?: string;
  /** Core binary handed the prompt on UserPromptSubmit, so capture needs no
   * hook of its own. */
  captureCommand?: string;
}

export interface PluginContents {
  skill: string;
  server: unknown;
  cliCommand?: string;
  dataDir?: string;
  /** Absent when the runtime ships no recall command; then nothing is injected. */
  injection?: InjectionHookRuntime;
}

export function marketplaceTree(
  target: CodebuddyPluginTarget,
  contents: PluginContents,
): PluginFile[] {
  return [
    {
      relativePath: MARKETPLACE_MANIFEST,
      content: json({
        name: target.marketplaceName,
        description: "MemHub recall",
        plugins: [
          {
            name: target.pluginName,
            source: `./plugins/${target.pluginName}`,
            // `codebuddy plugin validate` warns when this is missing, even
            // though the plugin's own manifest carries it too. Its absence is
            // the only thing the host's own validator objected to.
            version: target.version,
            description: PLUGIN_DESCRIPTION,
          },
        ],
      }),
    },
    ...pluginTree(target, contents).map((file) => ({
      relativePath: `plugins/${target.pluginName}/${file.relativePath}`,
      content: file.content,
    })),
  ];
}

const PLUGIN_DESCRIPTION =
  "Recall confirmed memories from the local MemHub app";

function hostCli(explicit?: string): string {
  if (explicit !== undefined && explicit !== "") return explicit;
  throw new Error("workbuddy_hook_command_missing");
}

function captureHook(
  cliCommand?: string,
  dataDir?: string,
): {
  hooks: Array<{ type: "command"; command: string; timeout: number }>;
} {
  return {
    hooks: [
      {
        type: "command",
        command: failOpenHookCommand(
          hostCli(cliCommand),
          "capture workbuddy",
          "silent",
          dataDir,
        ),
        timeout: 10,
      },
    ],
  };
}

/** Run the recall command's injection mode the way the MCP entry is run.
 *
 * Same runtime, same `ELECTRON_RUN_AS_NODE`, same discovery and credential
 * file as the plugin's MCP server, so turning one-click insert off revokes
 * both at once. A failure prints nothing: `{"continue": true}` would be read
 * back into the turn as text, because the host keeps raw stdout.
 *
 * The entry writes straight to the hook's stdout. It prints one complete
 * reply or nothing, so there is nothing to hold back and reprint.
 */
export function injectionHookCommand(runtime: InjectionHookRuntime): string {
  const environment = [
    'ELECTRON_RUN_AS_NODE="1"',
    `ONE_MEMORY_BROKER_DISCOVERY=${quoteCaptureCommand(runtime.discoveryPath)}`,
    ...(runtime.credentialFile
      ? [
          `ONE_MEMORY_HOST_CREDENTIAL_FILE=${quoteCaptureCommand(runtime.credentialFile)}`,
        ]
      : []),
    ...(runtime.dataDir
      ? [`ONE_MEMORY_DATA_DIR=${quoteCaptureCommand(runtime.dataDir)}`]
      : []),
    ...(runtime.captureCommand
      ? [
          `ONE_MEMORY_CAPTURE_COMMAND=${quoteCaptureCommand(runtime.captureCommand)}`,
        ]
      : []),
  ].join(" ");
  const invocation = `${environment} ${quoteCaptureCommand(runtime.runtimeCommand)} ${quoteCaptureCommand(runtime.recallCliPath)} --inject workbuddy`;
  // stderr is silent unless the operator explicitly asks for delivery
  // diagnosis. The entry only writes a broker error code under that switch.
  const script = `if [ "\${ONE_MEMORY_DEBUG_DELIVERY:-}" = "1" ]; then ${invocation}; else ${invocation} 2>/dev/null; fi; exit 0`;
  return `sh -c ${quoteCaptureCommand(script)}`;
}

/** The host treats running past this as a blocked send. The entry enforces a
 * single process-start deadline below four seconds, including cold start. */
function injectionHook(runtime: InjectionHookRuntime): {
  hooks: Array<{ type: "command"; command: string; timeout: number }>;
} {
  return {
    hooks: [
      {
        type: "command",
        command: injectionHookCommand(runtime),
        timeout: 50,
      },
    ],
  };
}

/** The hook file both plugin copies carry.
 *
 * One hook per event speaks. WorkBuddy shallow-merges the `hookSpecificOutput`
 * of every hook on an event, later ones overwriting earlier ones, so two of
 * ours each carrying `additionalContext` would lose one of them. The
 * injection hook runs on SessionStart too, where it recalls only after a
 * compaction.
 *
 * The host runs every hook on an event at once and blocks the send when any
 * outlives its timeout, so UserPromptSubmit capture is handed to the same
 * entry, which starts it and does not wait for it.
 */
export function pluginHooksFile(
  contents: Pick<PluginContents, "cliCommand" | "dataDir" | "injection">,
): string {
  const capture = captureHook(contents.cliCommand, contents.dataDir);
  if (!contents.injection) {
    return json({
      hooks: { UserPromptSubmit: [capture], Stop: [capture] },
    });
  }
  const context = injectionHook({
    ...contents.injection,
    captureCommand: hostCli(contents.cliCommand),
  });
  return json({
    hooks: {
      SessionStart: [context],
      UserPromptSubmit: [context],
      Stop: [capture],
    },
  });
}

export function pluginTree(
  target: CodebuddyPluginTarget,
  contents: PluginContents,
): PluginFile[] {
  return [
    {
      relativePath: PLUGIN_MANIFEST,
      content: json({
        name: target.pluginName,
        version: target.version,
        description: PLUGIN_DESCRIPTION,
        // Declared explicitly although the host also finds `skills/` on its
        // own (`find-skills` ships no such field and its skill still loads).
        // Being explicit is what keeps the tree readable to a person deciding
        // whether to trust it.
        skills: [`./skills/${target.skillName}`],
        // Absolute paths, not `${CODEBUDDY_PLUGIN_ROOT}`. The host does expand
        // that variable, but our MCP entry ships in the One Memory bundle
        // rather than in the plugin, so there is nothing under the plugin root
        // to point at. This is the same entry the other nine hosts get.
        mcpServers: { "one-memory": contents.server },
        // WorkBuddy 5.5.6 consumes additionalContext on SessionStart and
        // UserPromptSubmit. Stop only runs capture: it prints nothing and does
        // not return continueRequest, so it does not start another turn.
        hooks: "./hooks/hooks.json",
      }),
    },
    {
      relativePath: PLUGIN_HOOKS,
      content: pluginHooksFile(contents),
    },
    {
      relativePath: `skills/${target.skillName}/SKILL.md`,
      content: contents.skill,
    },
  ];
}

/** Host bookkeeping inside the cache copy that no plan of ours can ever list.
 *
 * WorkBuddy marks a cached plugin version as in use by creating one
 * `.in_use/<pid>` file beside the manifest for every live process, and sweeps
 * the expired ones on its own schedule (`.last_inuse_sweep` at the plugins
 * root). Those files belong to the host and are written after we installed, so
 * they are absent from every plan by construction — including the re-plan an
 * install does against the file as it stands now.
 *
 * Measured on a real machine: three `.in_use/<pid>` files under
 * `plugins/cache/one-memory/one-memory-recall/1.0.0/`, one per running
 * WorkBuddy process. Because the install and uninstall guards both require
 * every file under a tree to be planned, WorkBuddy could not be re-linked or
 * installed at all while WorkBuddy was open: the desktop reported only its
 * generic "could not read the connection change preview".
 *
 * A leading dot is how the host names bookkeeping it owns: `.in_use/` here,
 * and `.staging-<pid>-<ts>-<rand>/` while it writes a cache entry. Neither is
 * a name a person gives a skill. Nothing else inside the cache copy is
 * excused, so an edited SKILL.md still stops an install.
 */
export function isPluginCacheBookkeeping(
  target: CodebuddyPluginTarget,
  filePath: string,
): boolean {
  const prefix = target.cacheRoot.endsWith("/")
    ? target.cacheRoot
    : `${target.cacheRoot}/`;
  if (!filePath.startsWith(prefix)) return false;
  return filePath
    .slice(prefix.length)
    .split("/")
    .some(
      (segment) =>
        segment.startsWith(".") && segment !== "." && segment !== "..",
    );
}

/** Read the one entry that is ours, without disturbing the rest.
 *
 * `undefined` means the key is absent, which is different from a key holding
 * `null`: the first is a file we have never touched, the second is a value we
 * would have to put back.
 */
export function readRegistryEntry(
  raw: string | null,
  registry: PluginRegistry,
  label: string,
): unknown {
  if (raw === null) return undefined;
  let node: unknown = parseRegistry(raw, registry.path, label);
  for (const key of registry.keyPath) {
    if (!isRecord(node)) return undefined;
    node = node[key];
  }
  return node;
}

export function putRegistryEntry(
  raw: string | null,
  registry: PluginRegistry,
  label: string,
  value: unknown,
): string {
  const document =
    raw === null
      ? structuredClone(registry.seed)
      : parseRegistry(raw, registry.path, label);
  assignAtPath(document, registry.keyPath, value, registry.path, label);
  return serializeRegistry(document, raw);
}

/** The registry with our key gone, or holding what it held before us.
 *
 * Whether the file should exist at all is not decided here but by whether it
 * existed before we installed, which the journal records — the same rule the
 * other dialects follow, and for the same reason: a host that ships an empty
 * registry is entitled to get an empty registry back.
 */
export function removeRegistryEntry(
  raw: string | null,
  registry: PluginRegistry,
  label: string,
  reinstate: unknown,
): string {
  const document =
    raw === null
      ? structuredClone(registry.seed)
      : parseRegistry(raw, registry.path, label);
  if (reinstate !== undefined) {
    assignAtPath(document, registry.keyPath, reinstate, registry.path, label);
    return serializeRegistry(document, raw);
  }
  let node: unknown = document;
  for (const key of registry.keyPath.slice(0, -1)) {
    if (!isRecord(node)) return serializeRegistry(document, raw);
    node = node[key];
  }
  if (isRecord(node))
    delete node[registry.keyPath[registry.keyPath.length - 1]];
  return serializeRegistry(document, raw);
}

/** A stable digest of the one value that is ours.
 *
 * Ownership of a shared registry file is the value at our key, not the bytes
 * of the file the host and every other plugin also write to. Comparing the
 * whole file made uninstall refuse whenever anything else in it moved — a
 * plugin installed since, a key reordered, two spaces where there was one.
 * Issue #29 could not be uninstalled at all because of that.
 *
 * `null` means the key is absent, which is a different fact from a key holding
 * `null` and must stay distinguishable.
 */
export function registryManagedDigest(value: unknown): string | null {
  if (value === undefined) return null;
  return createHash("sha256")
    .update(canonicalJson(value), "utf8")
    .digest("hex");
}

/** JSON with object keys sorted, so formatting cannot change a digest. */
export function canonicalJson(value: unknown): string {
  if (value === null || typeof value !== "object")
    return JSON.stringify(value) ?? "null";
  if (Array.isArray(value))
    return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
  const record = value as Record<string, unknown>;
  return `{${Object.keys(record)
    .sort()
    .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
    .join(",")}}`;
}

/** The document with our key removed, as canonical JSON.
 *
 * Comparing this against what the file held before we installed is how a
 * registry can be handed back byte for byte when nothing else has moved, and
 * merged rather than reverted when something has.
 */
export function registryWithoutOurs(
  raw: string,
  registry: PluginRegistry,
  label: string,
): string {
  const document = parseRegistry(raw, registry.path, label);
  const withoutOurs = structuredClone(document);
  let node: unknown = withoutOurs;
  for (const key of registry.keyPath.slice(0, -1)) {
    if (isRecord(node)) node = node[key];
  }
  if (isRecord(node))
    delete node[registry.keyPath[registry.keyPath.length - 1]];
  return canonicalJson(withoutOurs);
}

/** Whether our key is the only thing in the file beyond the seed.
 *
 * Only then may a file we created be deleted outright on uninstall. Anything
 * else in it — a key the user or another plugin added after we installed —
 * means removing our key and leaving the file, rather than deleting work that
 * was never ours.
 */
export function registryHoldsOnlyOurs(
  raw: string,
  registry: PluginRegistry,
  label: string,
): boolean {
  return (
    registryWithoutOurs(raw, registry, label) === canonicalJson(registry.seed)
  );
}

function parseRegistry(
  raw: string,
  registryPath: string,
  label: string,
): Record<string, unknown> {
  let value: unknown;
  try {
    value = JSON.parse(raw);
  } catch (error) {
    // The host reads `settings.json` with a JSONC parser, so comments in it
    // would be legal for it and unreadable to us. Refusing loses nothing;
    // parsing it as JSON5 and writing back plain JSON would silently delete
    // whatever the user wrote in those comments.
    throw new Error(
      `${label} ${basename(registryPath)} is not valid JSON; no files were changed`,
      { cause: error },
    );
  }
  if (!isRecord(value)) {
    throw new Error(
      `${label} ${basename(registryPath)} must contain a JSON object`,
    );
  }
  return value;
}

/** Re-serialise a registry the way the host writes it.
 *
 * Two spaces and no closing newline: that is what WorkBuddy 5.5.0 leaves on
 * disk for all three files, verified by re-serialising them and comparing
 * bytes. Matching it is what lets uninstall be byte-exact rather than merely
 * equivalent, which for a file holding 49 other plugins is worth having.
 */
function serializeRegistry(
  document: Record<string, unknown>,
  raw: string | null,
): string {
  const text = JSON.stringify(document, null, 2);
  return raw?.endsWith("\n") ? `${text}\n` : text;
}

function assignAtPath(
  document: Record<string, unknown>,
  keyPath: string[],
  value: unknown,
  registryPath: string,
  label: string,
): void {
  let node = document;
  for (const key of keyPath.slice(0, -1)) {
    const existing = node[key];
    // Anything here that is not an object belongs to the host and is not ours
    // to reinterpret; refusing beats silently replacing it.
    if (existing !== undefined && !isRecord(existing)) {
      throw new Error(
        `${label} ${basename(registryPath)} has a non-object at ${keyPath.join(".")}; no files were changed`,
      );
    }
    node[key] = { ...(existing ?? {}) };
    node = node[key] as Record<string, unknown>;
  }
  node[keyPath[keyPath.length - 1]] = value;
}

function json(value: unknown): string {
  return JSON.stringify(value, null, 2);
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
}

function basename(target: string): string {
  return target.slice(target.lastIndexOf("/") + 1);
}