@yugabytedb/meko-mcp 2.1.0 → 2.3.0

package/lib/clients/opencode.mjs

@@ -0,0 +1,532 @@
+import {
+  chmodSync,
+  closeSync,
+  copyFileSync,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  readlinkSync,
+  renameSync,
+  rmdirSync,
+  rmSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { spawnSync } from "node:child_process";
+import { dirname, join, resolve } from "node:path";
+import {
+  getCaptureRoot,
+  getOpenCodeHookEnvPath,
+  getOpenCodeHooksInstallRoot,
+  getOpenCodeMekoRoot,
+  getOpenCodePluginPath,
+  getOpenCodeSkillsDir,
+  readJsonFile,
+} from "../config.mjs";
+import {
+  MEKO_MCP_USER_AGENT,
+  getInstallerVersion,
+  installStableTree,
+  isDanglingSymlink,
+  isPackagedInstall,
+  markerIsStale,
+  readInstallerMarker,
+  removePath,
+  resolveHooksRoot,
+  resolveOpenCodePluginSource,
+  resolveSkillSource,
+  symlinkOrCopy,
+  writeInstallerMarker,
+} from "./common.mjs";
+import {
+  isSupportedOpenCodeVersion,
+  probeOpenCode,
+} from "../migrate/adapters/opencode.mjs";
+const SKILLS = [{ name: "meko-mcp-tools" }];
+const MANAGED_MARKER = "Managed by meko installer";
+const OPENCODE_INSTALL_URL = "https://opencode.ai/docs/cli/";
+export function createOpenCodeAdapter(customPaths = {}) {
+  const resolveHooksRootPath = customPaths.resolveHooksRoot ?? resolveHooksRoot;
+  const resolveSkillSourcePath = customPaths.resolveSkillSource ?? resolveSkillSource;
+  const resolvePluginSourcePath = customPaths.resolveOpenCodePluginSource ?? resolveOpenCodePluginSource;
+  const packagedInstallDetector = customPaths.isPackagedInstall ?? isPackagedInstall;
+  const probe = customPaths.probeOpenCode ?? probeOpenCode;
+  const readResolvedConfig =
+    customPaths.readResolvedConfig ?? defaultReadResolvedConfig;
+  const paths = {
+    getPluginPath: customPaths.getPluginPath ?? getOpenCodePluginPath,
+    getMekoRoot: customPaths.getMekoRoot ?? getOpenCodeMekoRoot,
+    getHookEnvPath: customPaths.getHookEnvPath ?? getOpenCodeHookEnvPath,
+    getHooksInstallRoot: customPaths.getHooksInstallRoot ?? getOpenCodeHooksInstallRoot,
+    getSkillsDir: customPaths.getSkillsDir ?? getOpenCodeSkillsDir,
+    getCaptureRoot: customPaths.getCaptureRoot ?? getCaptureRoot,
+  };
+  return {
+    id: "opencode",
+    displayName: "OpenCode",
+    settingsPath(scope, projectRoot) {
+      return paths.getPluginPath(scope, projectRoot);
+    },
+    async detectPrerequisites({ verbose, log, dryRun = false } = { verbose: false, log: console }) {
+      const found = probe();
+      if (!found?.found) {
+        if (dryRun) {
+          log.dim?.("  OpenCode is not on PATH; continuing because this is a dry run.");
+          return { found: false, path: null, version: null };
+        }
+        throw new Error(
+          `OpenCode not found on PATH. Install OpenCode CLI/TUI 1.18.x (${OPENCODE_INSTALL_URL}).`,
+        );
+      }
+      if (!isSupportedOpenCodeVersion(found.version)) {
+        throw new Error(
+          `Unsupported OpenCode version "${found.version || "unknown"}". ` +
+          "This installer supports OpenCode CLI/TUI 1.18.x only.",
+        );
+      }
+      if (verbose) {
+        log.dim?.(`  OpenCode: ${found.path} (${found.version})`);
+      }
+      return found;
+    },
+    isInstalled() {
+      return Boolean(probe()?.found);
+    },
+    detectExisting(_name, { scope, projectRoot }) {
+      const pluginPath = paths.getPluginPath(scope, projectRoot);
+      const markerPath = join(paths.getHooksInstallRoot(scope, projectRoot), ".meko-installer");
+      const found = existsSync(pluginPath) && existsSync(markerPath);
+      return {
+        found,
+        status: found ? "Plugin overlay installed" : "",
+      };
+    },
+    removeRegistration(_name, { scope, projectRoot }) {
+      const pluginPath = paths.getPluginPath(scope, projectRoot);
+      if (existsSync(pluginPath) && isManagedPlugin(pluginPath)) {
+        rmSync(pluginPath, { force: true });
+        return { removed: true };
+      }
+      return { removed: false, present: existsSync(pluginPath) };
+    },
+    registerServer({ name, url, apiKey, dryRun, log, scope, projectRoot }) {
+      const pluginPath = paths.getPluginPath(scope, projectRoot);
+      const mekoRoot = paths.getMekoRoot(scope, projectRoot);
+      if (dryRun) {
+        log.dim(`  Would install OpenCode plugin overlay at ${pluginPath}`);
+        log.dim(`  Would write private environment at ${paths.getHookEnvPath(scope, projectRoot)}`);
+        log.dim(`    mcp.${name}.url = ${url}`);
+        log.dim(`    mcp.${name}.type = remote`);
+        log.dim(`    mcp.${name}.oauth = false`);
+        if (apiKey) log.dim("    mcp.<name>.headers.Authorization = <set>");
+        return;
+      }
+      if (existsSync(pluginPath) && !isManagedPlugin(pluginPath)) {
+        log.warn?.(
+          `  OpenCode plugin at ${pluginPath} has no installer marker — leaving it untouched.`,
+        );
+        return;
+      }
+      mkdirSync(dirname(pluginPath), { recursive: true });
+      mkdirSync(mekoRoot, { recursive: true });
+      const tmpPlugin = `${pluginPath}.tmp`;
+      copyFileSync(resolvePluginSourcePath(), tmpPlugin);
+      renameSync(tmpPlugin, pluginPath);
+      const envPath = paths.getHookEnvPath(scope, projectRoot);
+      writePrivateHookEnv(envPath, {
+        MEKO_MCP_URL: url,
+        MEKO_API_KEY: apiKey || "",
+        MEKO_MCP_SERVER_NAME: name,
+        MEKO_MCP_USER_AGENT: MEKO_MCP_USER_AGENT,
+        MEKO_HOOK_CLIENT: "opencode",
+        MEKO_NODE_EXECUTABLE: process.execPath,
+        MEKO_WATERMARK_DIR: savedWatermarkDir(envPath) || paths.getCaptureRoot(),
+      });
+    },
+    setHookEnvironment({ url, apiKey, dryRun, log, scope, projectRoot, name }) {
+      const handlersRoot = paths.getHooksInstallRoot(scope, projectRoot);
+      if (dryRun) {
+        log.dim(`  Would copy capture runtime to ${handlersRoot}`);
+        log.dim(`  Would write private environment at ${paths.getHookEnvPath(scope, projectRoot)}`);
+        const legacyPreview = join(paths.getMekoRoot(scope, projectRoot), "snapshots");
+        const previewOwned = shouldMigrateLegacySnapshots(handlersRoot);
+        if (existsSync(legacyPreview) && previewOwned) {
+          log.dim(`  Would migrate legacy staged snapshots from ${legacyPreview}`);
+        }
+        return;
+      }
+      const envPath = paths.getHookEnvPath(scope, projectRoot);
+      const captureRoot = savedWatermarkDir(envPath) || paths.getCaptureRoot();
+      const legacyDir = join(paths.getMekoRoot(scope, projectRoot), "snapshots");
+      const runtimeOwned = shouldMigrateLegacySnapshots(handlersRoot);
+      if (runtimeOwned) {
+        migrateLegacyOpenCodeSnapshots({
+          legacyDir,
+          durableDir: join(captureRoot, "opencode-snapshots"),
+          log,
+        });
+      } else if (existsSync(legacyDir)) {
+        log.dim?.(`  Skipping legacy snapshot migration: ${handlersRoot} is user-managed.`);
+      }
+      if (existsSync(handlersRoot) && !readInstallerMarker(handlersRoot)) {
+        log.dim?.(`  Skipping OpenCode capture install: ${handlersRoot} is user-managed.`);
+        return;
+      }
+      installStableTree(resolveHooksRootPath(), handlersRoot);
+      writeInstallerMarker(handlersRoot);
+      writePrivateHookEnv(envPath, {
+        MEKO_MCP_URL: url,
+        MEKO_API_KEY: apiKey || "",
+        MEKO_MCP_SERVER_NAME: resolveHookServerName(name, envPath),
+        MEKO_MCP_USER_AGENT: MEKO_MCP_USER_AGENT,
+        MEKO_HOOK_CLIENT: "opencode",
+        MEKO_NODE_EXECUTABLE: process.execPath,
+        MEKO_WATERMARK_DIR: captureRoot,
+      });
+    },
+    installSkills({ dryRun, log, scope, projectRoot }) {
+      const skillDir = paths.getSkillsDir(scope, projectRoot);
+      const currentVersion = getInstallerVersion();
+      if (dryRun) {
+        log.dim(`  Would install skills into ${skillDir}`);
+        return { marketplace: "skipped", skills: "dry-run" };
+      }
+      mkdirSync(skillDir, { recursive: true });
+      for (const skill of SKILLS) {
+        const source = resolveSkillSourcePath(skill.name);
+        const destination = join(skillDir, skill.name);
+        if (existsSync(destination)) {
+          if (isOwnSymlink(destination, source)) continue;
+          const marker = readInstallerMarker(destination);
+          if (!marker) {
+            log.dim(`  Skipping ${destination}: no .meko-installer marker (user-managed).`);
+            continue;
+          }
+          if (markerIsStale(destination, currentVersion)) {
+            removePath(destination);
+          } else {
+            continue;
+          }
+        } else if (isDanglingSymlink(destination)) {
+          removePath(destination);
+        }
+        const strategy = symlinkOrCopy(source, destination, {
+          preferCopy: packagedInstallDetector(),
+        });
+        if (strategy === "copy") writeInstallerMarker(destination);
+      }
+      return { marketplace: "skipped", skills: "ok" };
+    },
+    uninstall({ name, scope, projectRoot }) {
+      const results = [];
+      let captureRoot = paths.getCaptureRoot();
+      try {
+        const plugin = this.removeRegistration(name, { scope, projectRoot });
+        results.push({
+          key: "plugin",
+          ok: true,
+          message: plugin?.removed
+            ? "OpenCode plugin overlay removed."
+            : plugin?.present
+              ? "Plugin left in place because it is not installer-owned."
+              : "OpenCode plugin overlay not present.",
+        });
+      } catch (err) {
+        results.push({ key: "plugin", ok: false, message: `Could not remove plugin: ${err.message}` });
+      }
+      const envPath = paths.getHookEnvPath(scope, projectRoot);
+      try {
+        const saved = savedWatermarkDir(envPath);
+        if (saved) captureRoot = saved;
+        if (existsSync(envPath)) {
+          writePrivateHookEnv(envPath, { MEKO_WATERMARK_DIR: captureRoot });
+        }
+        results.push({ key: "credentials", ok: true, message: "OpenCode API key removed." });
+      } catch (err) {
+        results.push({ key: "credentials", ok: false, message: `Could not remove credentials: ${err.message}` });
+      }
+      try {
+        const handlersRoot = paths.getHooksInstallRoot(scope, projectRoot);
+        const runtimeOwned = Boolean(readInstallerMarker(handlersRoot));
+        let kept = 0;
+        if (runtimeOwned) {
+          const legacyDir = join(paths.getMekoRoot(scope, projectRoot), "snapshots");
+          if (existsSync(legacyDir)) {
+            const migrated = migrateLegacyOpenCodeSnapshots({
+              legacyDir,
+              durableDir: join(captureRoot, "opencode-snapshots"),
+              log: { dim() {}, warn() {} },
+            });
+            kept = Number(migrated?.kept || 0);
+          }
+        }
+        if (kept > 0) {
+          results.push({
+            key: "runtime",
+            ok: false,
+            message: `Could not migrate ${kept} legacy snapshot(s); left installer runtime in place.`,
+          });
+        } else {
+          if (runtimeOwned && existsSync(handlersRoot)) {
+            rmSync(handlersRoot, { recursive: true, force: true });
+          }
+          results.push({
+            key: "runtime",
+            ok: true,
+            message: runtimeOwned
+              ? "Installer-owned runtime removed; durable capture data (snapshots, journals, outboxes, quarantine) preserved."
+              : "Runtime left in place because it is not installer-owned; durable capture data preserved.",
+          });
+        }
+      } catch (err) {
+        results.push({ key: "runtime", ok: false, message: `Could not remove runtime: ${err.message}` });
+      }
+      try {
+        uninstallOpenCodeSkills({ scope, projectRoot, paths, resolveSkillSourcePath });
+        results.push({ key: "skills", ok: true, message: "OpenCode skills cleaned up." });
+      } catch (err) {
+        results.push({ key: "skills", ok: false, message: `Could not remove skills: ${err.message}` });
+      }
+      return results;
+    },
+    async validateConfig({ serverName, scope, projectRoot, log }) {
+      const pluginPath = paths.getPluginPath(scope, projectRoot);
+      const envPath = paths.getHookEnvPath(scope, projectRoot);
+      if (!existsSync(pluginPath)) {
+        return { ok: false, message: `OpenCode plugin not found at ${pluginPath}. Restart OpenCode after install.` };
+      }
+      if (!isManagedPlugin(pluginPath)) {
+        return { ok: false, message: `OpenCode plugin at ${pluginPath} is not installer-managed.` };
+      }
+      const env = readJsonFile(envPath);
+      if (!env?.MEKO_MCP_URL) {
+        return { ok: false, message: `Missing MEKO_MCP_URL in ${envPath}.` };
+      }
+      const resolvedName = env.MEKO_MCP_SERVER_NAME || serverName;
+      if (resolvedName !== serverName) {
+        log?.warn?.(`  OpenCode env server name ${resolvedName} differs from requested ${serverName}.`);
+      }
+      if (!env.MEKO_MCP_USER_AGENT) {
+        return { ok: false, message: "OpenCode environment is missing MEKO_MCP_USER_AGENT." };
+      }
+      if (
+        typeof env.MEKO_NODE_EXECUTABLE !== "string" ||
+        !env.MEKO_NODE_EXECUTABLE ||
+        !existsSync(env.MEKO_NODE_EXECUTABLE)
+      ) {
+        return {
+          ok: false,
+          message:
+            "OpenCode environment is missing a valid stable Node executable; reinstall Meko.",
+        };
+      }
+      const found = probe();
+      if (!found?.found) {
+        return { ok: false, message: "OpenCode is not available on PATH for resolved-config validation." };
+      }
+      if (!isSupportedOpenCodeVersion(found.version)) {
+        return {
+          ok: false,
+          message:
+            `Unsupported OpenCode version "${found.version || "unknown"}"; ` +
+            "supported versions are 1.18.x.",
+        };
+      }
+      let resolved;
+      try {
+        resolved = await Promise.resolve(readResolvedConfig({
+          bin: found.path || "opencode",
+          cwd: scope === "project" ? projectRoot : undefined,
+        }));
+      } catch (err) {
+        return {
+          ok: false,
+          message: `Could not read OpenCode resolved configuration: ${err.message}`,
+        };
+      }
+      const entry = resolved?.mcp?.[resolvedName];
+      const hasAuthorization = Object.keys(entry?.headers || {}).some(
+        (key) => key.toLowerCase() === "authorization",
+      );
+      const hasUserAgent = Object.keys(entry?.headers || {}).some(
+        (key) => key.toLowerCase() === "user-agent",
+      );
+      if (
+        !entry ||
+        entry.type !== "remote" ||
+        entry.url !== env.MEKO_MCP_URL ||
+        entry.enabled !== true ||
+        entry.oauth !== false ||
+        !hasUserAgent ||
+        (env.MEKO_API_KEY && !hasAuthorization)
+      ) {
+        return {
+          ok: false,
+          message:
+            `OpenCode resolved configuration does not contain the complete ` +
+            `"${resolvedName}" Meko MCP overlay.`,
+        };
+      }
+      return {
+        ok: true,
+        message: `OpenCode resolved the Meko MCP overlay for "${resolvedName}".`,
+      };
+    },
+  };
+}
+function defaultReadResolvedConfig({ bin, cwd }) {
+  const result = spawnSync(bin, ["debug", "config"], {
+    cwd,
+    encoding: "utf8",
+    maxBuffer: 16 * 1024 * 1024,
+    timeout: 10_000,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(`opencode debug config failed with exit code ${result.status}`);
+  }
+  try {
+    return JSON.parse(String(result.stdout || ""));
+  } catch (err) {
+    throw new Error(`invalid JSON from opencode debug config: ${err.message}`);
+  }
+}
+function isManagedPlugin(pluginPath) {
+  try {
+    const text = readFileSync(pluginPath, "utf8");
+    return text.includes(MANAGED_MARKER);
+  } catch {
+    return false;
+  }
+}
+function resolveHookServerName(name, envPath) {
+  if (typeof name === "string" && name.trim()) return name.trim();
+  try {
+    const existing = JSON.parse(readFileSync(envPath, "utf8"));
+    if (typeof existing.MEKO_MCP_SERVER_NAME === "string" && existing.MEKO_MCP_SERVER_NAME.trim()) {
+      return existing.MEKO_MCP_SERVER_NAME.trim();
+    }
+  } catch {
+    // first write or unreadable env
+  }
+  return "meko";
+}
+function writePrivateHookEnv(filePath, value) {
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+  chmodSync(filePath, 0o600);
+}
+function savedWatermarkDir(envPath) {
+  try {
+    const v = JSON.parse(readFileSync(envPath, "utf8")).MEKO_WATERMARK_DIR;
+    if (typeof v === "string" && v) return v;
+  } catch {}
+  return null;
+}
+function isOwnSymlink(destination, source) {
+  try {
+    if (!lstatSync(destination).isSymbolicLink()) return false;
+    return resolve(readlinkSync(destination)) === resolve(source);
+  } catch {
+    return false;
+  }
+}
+/** Migrate leftover `meko/snapshots` if handlers are gone (#307 uninstall) or installer-owned. */
+function shouldMigrateLegacySnapshots(handlersRoot) {
+  if (!existsSync(handlersRoot)) return true;
+  return Boolean(readInstallerMarker(handlersRoot));
+}
+/** Move leftover `meko/snapshots/*.json` into the durable capture root. */
+export function migrateLegacyOpenCodeSnapshots({ legacyDir, durableDir, log = console } = {}) {
+  if (!legacyDir || !existsSync(legacyDir)) return { migrated: 0, kept: 0 };
+  let entries;
+  try {
+    entries = readdirSync(legacyDir).filter((name) => name.endsWith(".json"));
+  } catch {
+    return { migrated: 0, kept: 0 };
+  }
+  if (entries.length === 0) {
+    try { rmdirSync(legacyDir); } catch { /* best effort */ }
+    return { migrated: 0, kept: 0 };
+  }
+  mkdirSync(durableDir, { recursive: true, mode: 0o700 });
+  let migrated = 0;
+  let kept = 0;
+  for (const name of entries) {
+    const source = join(legacyDir, name);
+    let target = join(durableDir, name);
+    let suffix = 0;
+    const base = name.endsWith(".json") ? name.slice(0, -".json".length) : name;
+    if (existsSync(target)) {
+      try {
+        if (
+          lstatSync(source).size === lstatSync(target).size &&
+          readFileSync(source).equals(readFileSync(target))
+        ) {
+          unlinkSync(source);
+          migrated += 1;
+          continue;
+        }
+      } catch { /* unique name below */ }
+      while (existsSync(target)) {
+        suffix += 1;
+        target = join(durableDir, `${base}.legacy.${suffix}.json`);
+      }
+    }
+    try {
+      renameSync(source, target);
+      try { chmodSync(target, 0o600); } catch { /* best effort */ }
+      migrated += 1;
+      continue;
+    } catch (err) {
+      if (!err || err.code !== "EXDEV") {
+        log?.warn?.(`  Could not migrate ${source}: ${err.message}`);
+        kept += 1;
+        continue;
+      }
+    }
+    const tmp = `${target}.tmp`;
+    try {
+      copyFileSync(source, tmp);
+      try { chmodSync(tmp, 0o600); } catch { /* best effort */ }
+      const fd = openSync(tmp, "r+");
+      try { fsyncSync(fd); } finally { closeSync(fd); }
+      renameSync(tmp, target);
+      migrated += 1;
+      try { unlinkSync(source); } catch { /* dest is in place; leftover source is a duplicate */ }
+    } catch (err) {
+      try { unlinkSync(tmp); } catch { /* nothing to clean */ }
+      log?.warn?.(`  Could not migrate ${source}: ${err.message}`);
+      kept += 1;
+    }
+  }
+  try {
+    const remaining = readdirSync(legacyDir);
+    if (remaining.length === 0) rmdirSync(legacyDir);
+  } catch { /* best effort */ }
+  if (migrated > 0) {
+    log?.dim?.(`  Migrated ${migrated} legacy OpenCode snapshot(s) to ${durableDir}.`);
+  }
+  if (kept > 0) {
+    log?.warn?.(`  Left ${kept} legacy OpenCode snapshot(s) at ${legacyDir}; will retry next install.`);
+  }
+  return { migrated, kept };
+}
+
+function uninstallOpenCodeSkills({ scope, projectRoot, paths, resolveSkillSourcePath }) {
+  const skillDir = paths.getSkillsDir(scope, projectRoot);
+  for (const skill of SKILLS) {
+    const destination = join(skillDir, skill.name);
+    const source = resolveSkillSourcePath(skill.name);
+    if (
+      existsSync(destination) &&
+      (readInstallerMarker(destination) || isOwnSymlink(destination, source))
+    ) {
+      removePath(destination);
+    }
+  }
+}

package/lib/config.mjs

@@ -8,7 +8,7 @@
  */
 
 import { readFileSync, writeFileSync, copyFileSync, mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { homedir } from "node:os";
 
 // ---------------------------------------------------------------------------
@@ -96,6 +96,163 @@ export function getClaudeCompatSettingsPath(scope, projectRoot) {
   return getClaudeCodeSettingsPath();
 }
 
+/**
+ * Root of Kiro's global config tree.
+ *
+ * Kiro documents $KIRO_HOME as the override every global surface resolves
+ * against (agents, skills, steering, settings, sessions), so honoring it here
+ * keeps all Kiro path helpers consistent with the IDE and `kiro-cli`.
+ * @returns {string}
+ */
+function getKiroHome() {
+  return process.env.KIRO_HOME || join(homedir(), ".kiro");
+}
+
+/**
+ * Root of OpenCode's config tree. Honors $OPENCODE_CONFIG_DIR when set
+ * (OpenCode 1.18.x resolves plugins/skills against this root).
+ * @returns {string}
+ */
+function getOpenCodeHome() {
+  return process.env.OPENCODE_CONFIG_DIR || join(homedir(), ".config", "opencode");
+}
+
+/** Installer-owned plugin path for the selected scope. */
+export function getOpenCodePluginPath(scope, projectRoot) {
+  if (scope === "project") {
+    return join(projectRoot, ".opencode", "plugins", "meko.js");
+  }
+  return join(getOpenCodeHome(), "plugins", "meko.js");
+}
+
+/** Stable runtime directory copied by the installer. */
+export function getOpenCodeMekoRoot(scope, projectRoot) {
+  if (scope === "project") {
+    return join(projectRoot, ".opencode", "meko");
+  }
+  return join(getOpenCodeHome(), "meko");
+}
+
+/** Private hook/capture environment (mode 0600). */
+export function getOpenCodeHookEnvPath(scope, projectRoot) {
+  return join(getOpenCodeMekoRoot(scope, projectRoot), "opencode-hook-env.json");
+}
+
+/** OpenCode skills directory for the selected scope. */
+export function getOpenCodeSkillsDir(scope, projectRoot) {
+  if (scope === "project") {
+    return join(projectRoot, ".opencode", "skills");
+  }
+  return join(getOpenCodeHome(), "skills");
+}
+
+/** Hooks-handlers copy root under the installer-owned runtime. */
+export function getOpenCodeHooksInstallRoot(scope, projectRoot) {
+  return join(getOpenCodeMekoRoot(scope, projectRoot), "hooks-handlers");
+}
+
+/**
+ * Resolve the durable Capture v2 watermark root used to store staged
+ * snapshots, journals, outboxes, quarantine, and recovery metadata. Mirrors
+ * `watermarkDir()` in `skills/hooks-handlers/lib/capture-state.js`. Kept in
+ * lockstep so hooks and installer agree on where durable state lives.
+ *
+ * MEKO-635: OpenCode staged snapshots and journals live under this root, not
+ * under the installer-owned OpenCode Meko root. Uninstall preserves them.
+ * First install honors `MEKO_WATERMARK_DIR`; later installs reuse the env-file
+ * root (uninstall leaves a watermark-only env so reinstall can resume).
+ *
+ * @returns {string} Absolute path
+ */
+export function getCaptureRoot() {
+  const configured = process.env.MEKO_WATERMARK_DIR;
+  if (configured && String(configured).length > 0) {
+    // MEKO-635: persist an absolute path so the installer, plugin, and handler
+    // all agree on it even when their cwds differ.
+    const value = String(configured);
+    return isAbsolute(value) ? value : resolve(value);
+  }
+  return join(homedir(), ".claude", "meko-capture");
+}
+
+/**
+ * Return path to Kiro's MCP config file.
+ *
+ * Kiro merges MCP scopes agent -> project -> global, and both the IDE and
+ * `kiro-cli` read the same files, so one pair of paths covers both surfaces.
+ * @param {"user"|"project"} scope
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+export function getKiroMcpPath(scope, projectRoot) {
+  if (scope === "project") {
+    return join(projectRoot, ".kiro", "settings", "mcp.json");
+  }
+  return join(getKiroHome(), "settings", "mcp.json");
+}
+
+/** Return the directory containing standalone Kiro hook definitions. */
+export function getKiroHooksDir(scope, projectRoot) {
+  if (scope === "project") {
+    return join(projectRoot, ".kiro", "hooks");
+  }
+  return join(getKiroHome(), "hooks");
+}
+
+/** Return the installer-owned, legacy CLI 2.x managed-agent path. */
+export function getKiroManagedAgentPath(scope, projectRoot) {
+  if (scope === "project") {
+    return join(projectRoot, ".kiro", "agents", "meko-default.json");
+  }
+  return join(getKiroHome(), "agents", "meko-default.json");
+}
+
+/**
+ * Return Kiro's CLI settings path for the selected installer scope.
+ * CLI 2.x stores dotted setting names as top-level JSON keys.
+ */
+export function getKiroCliSettingsPath(scope, projectRoot) {
+  if (scope === "project") {
+    return join(projectRoot, ".kiro", "settings", "cli.json");
+  }
+  return join(getKiroHome(), "settings", "cli.json");
+}
+
+/**
+ * Return path to the Meko-owned Kiro steering file.
+ *
+ * Kiro reads every file in `steering/` on each interaction, which makes it the
+ * analogue of Codex's AGENTS.md: the place to state behavior the agent must
+ * follow. Because steering is a *directory*, we own `meko.md` outright instead
+ * of upserting a fenced block into a file the user also edits.
+ * @param {"user"|"project"} scope
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+export function getKiroSteeringPath(scope, projectRoot) {
+  if (scope === "project") {
+    return join(projectRoot, ".kiro", "steering", "meko.md");
+  }
+  return join(getKiroHome(), "steering", "meko.md");
+}
+
+/**
+ * Return path to Kiro's skills directory.
+ *
+ * Kiro implements the Agent Skills standard (SKILL.md + name/description
+ * frontmatter), which is the same format our skills already ship in, so they
+ * install by copy with no transformation.
+ * @param {"user"|"project"} scope
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+export function getKiroSkillsDir(scope, projectRoot) {
+  if (scope === "project") {
+    return join(projectRoot, ".kiro", "skills");
+  }
+  return join(getKiroHome(), "skills");
+}
+
 /**
  * Return path to Codex's user-level config (TOML).
  * Honors $CODEX_HOME if set, else defaults to ~/.codex/config.toml.