@gitkraken/agent-tools 0.0.0-stage → 0.1.1

package/dist/hooks/templates.js

@@ -0,0 +1,278 @@
+import{joinPath as e}from"../config.js";import{removeTracked as t,writeFileTracked as n}from"../file-change.js";import{HookConfigError as r}from"./errors.js";const i=`// gk-managed:`;function a(t,n){return e(t===`opencode`?e(n.paths.configHome,`opencode`,`plugins`):e(n.paths.piAgentDir||e(n.paths.home,`.pi`,`agent`),`extensions`),`gk-hooks.js`)}function o(e){return e?.split(`
+`,1)[0].startsWith(i)??!1}function s(e){if(!o(e))return;let t=e.split(`
+`,1)[0];try{let e=JSON.parse(t.slice(14));if(e&&typeof e==`object`&&Array.isArray(e.events)){let t=e;return{events:t.events.filter(e=>typeof e==`string`),executable:typeof t.executable==`string`?t.executable:``,hostMajor:typeof t.hostMajor==`number`?t.hostMajor:0}}}catch{}}function c(e,t,n,r){let a={events:t,executable:n,version:e===`opencode`?5:1};e===`opencode`&&r&&(a.hostMajor=r);let o=e===`opencode`?`import { spawn } from "node:child_process";
+
+const EVENTS = new Set({{.EventsJSON}});
+const EXECUTABLE = {{.ExecJSON}};
+const HOST = {{.HostJSON}};
+const MAX_HOOK_INPUT_BYTES = {{.MaxInputBytesJSON}};
+
+function getString(value) {
+  return typeof value === "string" && value.length > 0 ? value : "";
+}
+
+// extractToolName is the one piece of the relay every host must supply: only
+// the host knows where its payloads carry a tool name. The default below
+// returns null so a host that forgets it still forwards events with
+// tool_name: null, instead of throwing inside runHook's catch-all and
+// silently forwarding nothing at all. Hosts override it with
+// {{define "extractToolName"}} — see hook_pi.js.tmpl and
+// hook_opencode.js.tmpl.
+function extractToolName(payload) {
+  return (
+    getString(payload?.input?.tool) ||
+    getString(payload?.event?.properties?.part?.tool) ||
+    getString(payload?.event?.properties?.tool) ||
+    // v2's tool.hook("execute.before"/"execute.after") callbacks pass { event },
+    // where event.tool is the tool name directly (e.g. "read").
+    getString(payload?.event?.tool) ||
+    ""
+  );
+}
+
+const V1_ONLY_EVENTS = new Set({{.V1OnlyEventsJSON}});
+const V2_EVENT_ALIASES = new Map(Object.entries({{.V2EventAliasesJSON}}));
+
+function extractSessionID(event) {
+  return (
+    getString(event?.properties?.sessionID) ||
+    getString(event?.properties?.sessionId) ||
+    getString(event?.properties?.session_id) ||
+    // A message or part names its session in its own sessionID; its id names
+    // the message or part. Only a session's own info carries the session id
+    // as id, so that fallback comes after every explicit session field.
+    getString(event?.properties?.info?.sessionID) ||
+    getString(event?.properties?.part?.sessionID) ||
+    getString(event?.properties?.info?.id) ||
+    getString(event?.properties?.id) ||
+    getString(event?.sessionID) ||
+    getString(event?.sessionId) ||
+    getString(event?.session_id) ||
+    // v2's event bus nests the id under \`data\` instead of \`properties\`. The
+    // event's own top-level id is never a fallback: on v2 it names the event,
+    // and relaying it would report a session that does not exist.
+    getString(event?.data?.sessionID)
+  );
+}
+
+
+
+// server is the OpenCode v1 plugin entrypoint (returns a Hooks object). v1
+// calls this directly off the default export below.
+const server = async (ctx) => {
+  // No process.cwd() fallback: that is the host's launch directory, which the
+  // relay cannot tell apart from a real per-session cwd and would use to
+  // attribute the session to the wrong repo. Each hook below drops its event
+  // instead when cwd is empty, so the spawn is skipped entirely rather than
+  // paid for and discarded by the relay's own missing-cwd guard.
+  const cwd = getString(ctx.directory) || getString(ctx.worktree);
+  const hooks = {};
+
+  // General event hook — forwards native dot names as-is.
+  hooks.event = async ({ event }) => {
+    if (!cwd) return;
+    const type = event?.type ?? "";
+    if (type === "tool.execute.before" || type === "tool.execute.after") return;
+    const sessionID = extractSessionID(event);
+    if (!sessionID) return;
+    runHook(type, sessionID, cwd, { event });
+  };
+
+  // Dedicated tool hooks — provide structured sessionID and tool name.
+  if (EVENTS.has("tool.execute.before")) {
+    hooks["tool.execute.before"] = async (input, output) => {
+      if (!cwd) return;
+      const sessionID =
+        getString(input?.sessionID) || getString(input?.sessionId) || getString(input?.session_id);
+      if (!sessionID) return;
+      runHook("tool.execute.before", sessionID, cwd, { input, output });
+    };
+  }
+  if (EVENTS.has("tool.execute.after")) {
+    hooks["tool.execute.after"] = async (input, output) => {
+      if (!cwd) return;
+      const sessionID =
+        getString(input?.sessionID) || getString(input?.sessionId) || getString(input?.session_id);
+      if (!sessionID) return;
+      runHook("tool.execute.after", sessionID, cwd, { input, output });
+    };
+  }
+
+  return hooks;
+};
+
+// setup is the OpenCode v2 plugin entrypoint. v2 replaced the returned-Hooks
+// shape with named registration APIs (ctx.tool.hook, ctx.event.subscribe). It
+// dropped the v1 names ctx.directory/ctx.worktree, but the directory itself is
+// still on the context as ctx.location.directory, so that is the base cwd.
+const setup = async (ctx) => {
+  // Per-session directories arrive only on the subset of events that carry a
+  // location, and the subscription only yields from plugin load onward, so a
+  // session predating this plugin instance (server restart, resumed session)
+  // never populates the cache. Treat the cache as an override on top of the
+  // context directory rather than the only source, and never guess: with no
+  // directory at all, send "" so the relay drops the event instead of
+  // attributing the session to the host's launch directory.
+  const baseCwd =
+    getString(ctx?.location?.directory) || getString(ctx?.directory) || getString(ctx?.worktree);
+  // session.deleted is an explicit, rare user action, so eviction on it alone
+  // would let a host left running for days accumulate one entry per session it
+  // ever saw. Cap the map the way runner.go caps its cwd timeline and drop the
+  // oldest entry first (Map iterates in insertion order); a session evicted
+  // this way falls back to baseCwd, same as one that never carried a location.
+  const MAX_TRACKED_SESSIONS = 50;
+  const cwdBySession = new Map();
+  const rememberCwd = (sessionID, directory) => {
+    // Re-insert so a session still in use is treated as the newest entry.
+    cwdBySession.delete(sessionID);
+    cwdBySession.set(sessionID, directory);
+    while (cwdBySession.size > MAX_TRACKED_SESSIONS) {
+      cwdBySession.delete(cwdBySession.keys().next().value);
+    }
+  };
+  const resolveCwd = (sessionID) => (sessionID && cwdBySession.get(sessionID)) || baseCwd;
+
+  if (EVENTS.has("tool.execute.before")) {
+    await ctx.tool.hook("execute.before", (event) => {
+      const sessionID = getString(event?.sessionID);
+      if (!sessionID) return;
+      runHook("tool.execute.before", sessionID, resolveCwd(sessionID), { event });
+    });
+  }
+  if (EVENTS.has("tool.execute.after")) {
+    await ctx.tool.hook("execute.after", (event) => {
+      const sessionID = getString(event?.sessionID);
+      if (!sessionID) return;
+      runHook("tool.execute.after", sessionID, resolveCwd(sessionID), { event });
+    });
+  }
+
+  const controller = new AbortController();
+  (async () => {
+    try {
+      for await (const event of ctx.event.subscribe({ signal: controller.signal })) {
+        const sessionID = extractSessionID(event);
+        const directory =
+          getString(event?.location?.directory) || getString(event?.data?.location?.directory);
+        if (sessionID && directory) rememberCwd(sessionID, directory);
+
+        const type = event?.type ?? "";
+        if (type === "tool.execute.before" || type === "tool.execute.after") continue;
+        if (V1_ONLY_EVENTS.has(type)) continue;
+        // File edits, branch changes and todo updates can arrive without a
+        // session; there is no conversation to attribute them to.
+        if (!sessionID) continue;
+        runHook(type, sessionID, resolveCwd(sessionID), { event }, V2_EVENT_ALIASES.get(type));
+        // Evict regardless of whether session.deleted is in the installed
+        // EVENTS set, so an explicitly deleted session is released immediately
+        // rather than waiting to age out of the cap above.
+        if (type === "session.deleted") cwdBySession.delete(sessionID);
+      }
+    } catch (_) {
+      // Subscription tears down when the plugin is disposed; must never throw.
+    }
+  })();
+
+  return () => controller.abort();
+};
+
+// OpenCode v2 validates the default export as an object before reading setup;
+// callable objects fail that schema. v1.4+ reads server from this same shape.
+// Older v1 hosts cannot share one module shape with v2 and are unsupported by
+// this v2-capable template.
+export default { id: "gk-hooks", server, setup };
+`:`import { spawn } from "node:child_process";
+
+const EVENTS = new Set({{.EventsJSON}});
+const EXECUTABLE = {{.ExecJSON}};
+const HOST = {{.HostJSON}};
+const MAX_HOOK_INPUT_BYTES = {{.MaxInputBytesJSON}};
+
+function getString(value) {
+  return typeof value === "string" && value.length > 0 ? value : "";
+}
+
+// extractToolName is the one piece of the relay every host must supply: only
+// the host knows where its payloads carry a tool name. The default below
+// returns null so a host that forgets it still forwards events with
+// tool_name: null, instead of throwing inside runHook's catch-all and
+// silently forwarding nothing at all. Hosts override it with
+// {{define "extractToolName"}} — see hook_pi.js.tmpl and
+// hook_opencode.js.tmpl.
+function extractToolName(payload) {
+  return getString(payload?.event?.toolName);
+}
+
+
+
+function sessionIdOf(ctx) {
+  return getString(ctx?.sessionManager?.getSessionId?.());
+}
+
+export default function (pi) {
+  for (const name of EVENTS) {
+    pi.on(name, async (event, ctx) => {
+      // A reload is not a session ending; forwarding it would kill a live session.
+      if (name === "session_shutdown" && event?.reason === "reload") return;
+      // No process.cwd() fallback: that is pi's launch directory, which the
+      // relay cannot tell apart from a real per-session cwd and would use to
+      // attribute the session to the wrong repo. Dropping the event lets the
+      // relay's missing-cwd guard stay meaningful.
+      const cwd = getString(ctx?.cwd);
+      if (!cwd) return;
+      runHook(name, sessionIdOf(ctx), cwd, { event });
+    });
+  }
+}
+`,s={EventsJSON:JSON.stringify(t),ExecJSON:JSON.stringify(n),HostJSON:JSON.stringify(e),MaxInputBytesJSON:`1048576`,V1OnlyEventsJSON:JSON.stringify([`session.updated`,`session.error`]),V2EventAliasesJSON:JSON.stringify({"session.execution.failed":[`session.error`],"session.status":[`session.updated`]})},c=e===`opencode`?`
+
+const V1_ONLY_EVENTS`:`
+
+
+
+function sessionIdOf`,l=o.indexOf(c);if(l<0)throw Error(`missing ${e} relay insertion point`);let u=o.slice(0,l)+`
+
+function buildHookInput(eventName, sessionID, cwd, payload) {
+  const toolName = extractToolName(payload);
+  const hookInput = {
+    hook_event_name: eventName,
+    session_id: sessionID || "",
+    cwd,
+    tool_name: toolName || null,
+    source: null,
+    model: null,
+    reason: null,
+    agent_id: null,
+    agent_type: null,
+    hook_payload: payload || null,
+  };
+
+  const serializedInput = JSON.stringify(hookInput);
+  const payloadBytes = Buffer.byteLength(serializedInput, "utf8");
+  if (payloadBytes <= MAX_HOOK_INPUT_BYTES) {
+    return serializedInput;
+  }
+
+  return JSON.stringify({
+    ...hookInput,
+    hook_payload: { truncated: true, originalBytes: payloadBytes },
+  });
+}
+
+function runHook(eventName, sessionID, cwd, payload, aliases = []) {
+  if (!EVENTS.has(eventName) && !aliases.some((alias) => EVENTS.has(alias))) return;
+  try {
+    const input = buildHookInput(eventName, sessionID, cwd, payload);
+    const child = spawn(EXECUTABLE, ["ai", "hook", "run", "--host", HOST], {
+      stdio: ["pipe", "ignore", "ignore"],
+      windowsHide: true,
+    });
+    child.on("error", () => {});
+    child.stdin.on("error", () => {});
+    child.stdin.end(input);
+    child.unref();
+  } catch (_) {
+    // Hooks must never block the host
+  }
+}`+o.slice(l);return i+JSON.stringify(a)+`
+`+u.replace(/{{\.(\w+)}}/g,(e,t)=>s[t]??``)}async function l(n,r,i){let s=a(n,r),c=s.slice(0,s.lastIndexOf(`/`));for(let n of await r.fs.readDir(c)??[]){if(n===`gk-hooks.js`||!n.startsWith(`gk-hooks.`))continue;let a=e(c,n);o(await r.fs.readFile(a))&&await t(r.fs,a,i)}}async function u(e,t){let i=a(e.host,t);if(e.blockingEvents?.length)throw new r(`blocking-unsupported`,`${e.host} does not support blocking hooks`,i);let u=await t.fs.readFile(i),d=s(u);if(u!==null&&!o(u))throw new r(`unmanaged-file`,`${i} already exists and was not written by GitKraken`,i);let f=[...new Set([...d?.events??[],...e.events??[]])].sort(),p=e.host===`opencode`?t.openCodeMajor??0:0,m=[];return await n(t.fs,i,c(e.host,f,e.executablePath.replace(/\\/g,`/`),p),m,{mode:384}),await l(e.host,t,m),{host:e.host,path:i,events:[...e.events??[]],blockingEvents:[],files:m}}async function d(e,r,i){let o=a(e,i),u=[],d=await i.fs.readFile(o),f=s(d),p=[],m=[];f&&(p=f.events.filter(e=>(r??f.events).includes(e)),m=f.events.filter(e=>!p.includes(e)).sort(),m.length?await n(i.fs,o,c(e,m,f.executable,f.hostMajor),u,{mode:384}):await t(i.fs,o,u)),await l(e,i,u);let h={host:e,path:o,removedEvents:p,remainingEvents:m,files:u};return p.length||(h.reason=d===null?`file-missing`:`not-installed`),h}export{u as installMarkerHooks,d as uninstallMarkerHooks};

package/dist/hooks/writers.d.ts

@@ -0,0 +1,18 @@
+import { AgentHostConfig } from "../config.js";
+import { HookHost } from "./events.js";
+import { HookInstallResult, HookUninstallResult } from "./results.js";
+
+//#region src/hooks/writers.d.ts
+type JsonHookHost = Extract<HookHost, 'cursor' | 'codex' | 'copilot' | 'antigravity' | 'augment' | 'grok'>;
+interface HookWriteRequest {
+  host: HookHost;
+  executablePath: string;
+  events?: readonly string[];
+  blockingEvents?: readonly string[];
+}
+declare function command(executablePath: string, host: HookHost, config: AgentHostConfig, blocking: boolean): string;
+/** Merges only GitKraken-owned hooks, preserving unrelated entries and document keys. */
+declare function installJsonHooks(request: HookWriteRequest, config: AgentHostConfig): Promise<HookInstallResult>;
+declare function uninstallJsonHooks(host: JsonHookHost, config: AgentHostConfig, events?: readonly string[]): Promise<HookUninstallResult>;
+//#endregion
+export { HookWriteRequest, command, installJsonHooks, uninstallJsonHooks };

package/dist/hooks/writers.js

@@ -0,0 +1 @@
+import{joinPath as e}from"../config.js";import{removeTracked as t,writeFileTracked as n}from"../file-change.js";import{HookConfigError as r}from"./errors.js";import{eventManifest as i}from"./events.js";const a={cursor:{path:t=>e(t.paths.home,`.cursor`,`hooks.json`),key:`hooks`,version:!0,matcher:!1},codex:{path:t=>e(t.paths.home,`.codex`,`hooks.json`),key:`hooks`,version:!1,matcher:!0},copilot:{path:t=>e(t.paths.home,`.copilot`,`hooks`,`gitkraken-hooks.json`),key:`hooks`,version:!0,matcher:!1},antigravity:{path:t=>e(t.paths.home,`.gemini`,`config`,`hooks.json`),key:`gitkraken`,version:!1,matcher:!1},augment:{path:t=>e(t.paths.home,`.augment`,`settings.json`),key:`hooks`,version:!1,matcher:!0,neverDelete:!0},grok:{path:t=>e(t.paths.grokHome??e(t.paths.home,`.grok`),`hooks`,`gitkraken-hooks.json`),key:`hooks`,version:!1,matcher:!0}};function o(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function s(e){return typeof e==`string`&&e.includes(` ai hook run --host `)}function c(e,t,n,r){return`${n.platform===`win32`&&`windowsShell`in i[t]&&i[t].windowsShell===`powershell`?`& `:``}"${e.replaceAll(`\\`,`/`)}" ai hook run --host ${t}${r?` --blocking`:``}`}function l(e){let t=i[e.host],n=e.events?.length||e.blockingEvents?.length?e.events??[]:t.events.filter(e=>!t.skippedDefaultEvents.includes(e)),a=e.blockingEvents??[];for(let i of[...n,...a])if(!t.events.includes(i))throw new r(`invalid-event`,`${i} is not valid for ${e.host}`);return[n,a]}function u(e,t){return e===`antigravity`?t===`PreToolUse`||t===`PostToolUse`:a[e].matcher}function d(e,t,n){if(!Array.isArray(e)||!e.every(o))throw new r(`wrong-shape`,`${n} has the wrong event shape`,n);if(t&&e.some(e=>`command`in e||`hooks`in e&&(!Array.isArray(e.hooks)||!e.hooks.every(o))))throw new r(`wrong-shape`,`${n} has the wrong matcher shape`,n);if(!t&&e.some(e=>`hooks`in e))throw new r(`wrong-shape`,`${n} has the wrong flat shape`,n)}function f(e,t){return Array.isArray(e)?e.some(e=>t&&o(e)&&Array.isArray(e.hooks)?e.hooks.some(e=>o(e)&&s(e.command)):o(e)&&s(e.command)):!1}function p(e,t){return Object.keys(t).filter(n=>f(t[n],u(e,n)))}function m(e,t){return t?e.flatMap(e=>{if(!Array.isArray(e.hooks))return[e];let t=e.hooks.filter(e=>!o(e)||!s(e.command));return t.length===e.hooks.length?[e]:t.length?[{...e,hooks:t}]:[]}):e.filter(e=>!s(e.command))}function h(e,t,n,r,a){let o=86400*(`blockingTimeoutMultiplier`in i[n]?Number(i[n].blockingTimeoutMultiplier):1),c={type:`command`,command:r,...a?{timeout:o}:{}};if(!t)return[...m(e,!1),c];let l=m(e,!0),u=l.find(e=>!e.matcher&&Array.isArray(e.hooks)&&e.hooks.length>0);u||(u=n===`augment`?{hooks:[]}:{matcher:``,hooks:[]},l.push(u));let d=Array.isArray(u.hooks)?u.hooks:[];return u.hooks=[...d.filter(e=>!s(e.command)),c],l}function g(e,t){let n;try{n=JSON.parse(e.replace(/^\uFEFF/,``))}catch{throw new r(`invalid-json`,`Invalid JSON at ${t}`,t)}if(!o(n))throw new r(`wrong-shape`,`Invalid hooks document at ${t}`,t);return n}function _(e,t,n){let i=e[t];if(i!=null){if(!o(i))throw new r(`wrong-shape`,`Invalid hooks wrapper at ${n}`,n);return i}}async function v(e,t){if(!(e.host in a))throw new r(`unsupported-host`,`No JSON writer for ${e.host}`);let o=e.host,s=a[o],f=s.path(t),p=await t.fs.readFile(f),v=p?.trim()?g(p,f):{},y={..._(v,s.key,f)};for(let[e,t]of Object.entries(y))d(t,u(o,e),f);let[b,x]=l(e);for(let[n,r]of[[b,!1],[x,!0]])for(let i of n){let n=u(o,i);y[i]=h(y[i]??[],n,o,c(e.executablePath,o,t,r),r)}if(`legacyEvents`in i[o])for(let e of i[o].legacyEvents){let t=y[e];if(t){let n=m(t,u(o,e));n.length?y[e]=n:delete y[e]}}Object.keys(y).length?v[s.key]=y:delete v[s.key],s.version&&v.version==null&&(v.version=1);let S=[];return await n(t.fs,f,`${JSON.stringify(v,null,2)}\n`,S),{host:o,path:f,events:[...b],blockingEvents:[...x],files:S}}async function y(e,r,o){let s=a[e],c=s.path(r),l=[],f=(t,n=[])=>({host:e,path:c,removedEvents:[],remainingEvents:n,files:l,reason:t}),h=await r.fs.readFile(c);if(h===null)return f(`file-missing`);if(!h.trim())return f(`not-installed`);let v=g(h,c),y=_(v,s.key,c);if(!y)return f(`not-installed`);let b={...y};for(let[t,n]of Object.entries(b))d(n,u(e,t),c);let x=[],S=o?.length?o:i[e].events;for(let t of[...S,...`legacyEvents`in i[e]?i[e].legacyEvents:[]]){let n=b[t];if(!n)continue;let r=m(n,u(e,t));JSON.stringify(r)!==JSON.stringify(n)&&(x.push(t),r.length?b[t]=r:delete b[t])}let C=p(e,b);if(!x.length)return f(`not-installed`,C);Object.keys(b).length?v[s.key]=b:delete v[s.key];let w=Object.keys(v).some(e=>e!==s.key&&!(e===`version`&&s.version&&v.version===1));return!Object.keys(b).length&&!w&&!s.neverDelete?await t(r.fs,c,l):await n(r.fs,c,`${JSON.stringify(v,null,2)}\n`,l),{host:e,path:c,removedEvents:x,remainingEvents:C,files:l}}export{c as command,v as installJsonHooks,y as uninstallJsonHooks};

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { AgentHostConfig, AgentHostPaths, AgentOrigin, joinPath } from "./config.js";
+import { HookHost, eventManifest } from "./hooks/events.js";
+import { Client, ClientDetection, ClientDetectionSource, ClientInstallation, ClientNotDetectedReason, ClientType, allClients, antigravityLegacyPath, clientCommand, clientConfigPath, clientConfigPaths, clientDisplayName, clientExecutablePath, clientJSONPath, clientType, clientsForHost, detectClient, getClientInstallation, hostIdentity, hostOf, isInstallable, isLegacy, isSupported, legacyClientIds } from "./mcp/clients.js";
+import { Agent, HookCapability, listAgents, mcpNamesForHook, resolveHookClient } from "./agents.js";
+import { FileChange, FileChangeKind } from "./file-change.js";
+import { HookInstallResult, HookUninstallResult } from "./hooks/results.js";
+import { HookConfigError, HookConfigErrorCode } from "./hooks/errors.js";
+import { HookWriteRequest, installJsonHooks, uninstallJsonHooks } from "./hooks/writers.js";
+import { InstallHooksRequest, installHooks, uninstallHooks } from "./hooks/install.js";
+import { McpConfigEntry, generateConfigEntry } from "./mcp/config-entry.js";
+import { McpInstallRequest, McpInstallResult, McpInstallState, McpInstallStateReason, McpInstallStatus, inspectMcpInstall, installMcp } from "./mcp/installer.js";
+import { getMcpCliInstallCommand } from "./mcp/cli-install-command.js";
+import { McpUninstallFileResult, McpUninstallRequest, McpUninstallResult, uninstallMcp } from "./mcp/uninstaller.js";
+import { SKILL_MANIFEST_FILE_NAME, SKILL_MANIFEST_SCHEMA_VERSION, SkillManifest } from "./skills/manifest.js";
+import { SkillAgent, allSkillAgents, isSkillAgentSupported, skillDir } from "./skills/skill-dirs.js";
+import { SkillConflictError, SkillFiles, SkillInstallAction, SkillInstallOptions, SkillInstallResult, SkillOperation, SkillReason, SkillState, SkillStatus, SkillUninstallAction, SkillUninstallOptions, SkillUninstallResult, SkillUnsupportedManifestError, inspectSkillStatus, installSkill, uninstallSkill } from "./skills/install.js";
+export { type Agent, type AgentHostConfig, type AgentHostPaths, type AgentOrigin, type Client, type ClientDetection, type ClientDetectionSource, type ClientInstallation, type ClientNotDetectedReason, type ClientType, type FileChange, type FileChangeKind, type HookCapability, HookConfigError, type HookConfigErrorCode, type HookHost, type HookInstallResult, type HookUninstallResult, type HookWriteRequest, type InstallHooksRequest, type McpConfigEntry, type McpInstallRequest, type McpInstallResult, type McpInstallState, type McpInstallStateReason, type McpInstallStatus, type McpUninstallFileResult, type McpUninstallRequest, type McpUninstallResult, SKILL_MANIFEST_FILE_NAME, SKILL_MANIFEST_SCHEMA_VERSION, type SkillAgent, SkillConflictError, type SkillFiles, type SkillInstallAction, type SkillInstallOptions, type SkillInstallResult, type SkillManifest, type SkillOperation, type SkillReason, type SkillState, type SkillStatus, type SkillUninstallAction, type SkillUninstallOptions, type SkillUninstallResult, SkillUnsupportedManifestError, allClients, allSkillAgents, antigravityLegacyPath, clientCommand, clientConfigPath, clientConfigPaths, clientDisplayName, clientExecutablePath, clientJSONPath, clientType, clientsForHost, detectClient, eventManifest, generateConfigEntry, getClientInstallation, getMcpCliInstallCommand, hostIdentity, hostOf, inspectMcpInstall, inspectSkillStatus, installHooks, installJsonHooks, installMcp, installSkill, isInstallable, isLegacy, isSkillAgentSupported, isSupported, joinPath, legacyClientIds, listAgents, mcpNamesForHook, resolveHookClient, skillDir, uninstallHooks, uninstallJsonHooks, uninstallMcp, uninstallSkill };

package/dist/index.js

@@ -0,0 +1 @@
+import{joinPath as e}from"./config.js";import{allClients as t,antigravityLegacyPath as n,clientCommand as r,clientConfigPath as i,clientConfigPaths as a,clientDisplayName as o,clientExecutablePath as s,clientJSONPath as c,clientType as l,clientsForHost as u,detectClient as d,getClientInstallation as f,hostIdentity as p,hostOf as m,isInstallable as h,isLegacy as g,isSupported as _,legacyClientIds as v}from"./mcp/clients.js";import{listAgents as y,mcpNamesForHook as b,resolveHookClient as x}from"./agents.js";import{HookConfigError as S}from"./hooks/errors.js";import{eventManifest as C}from"./hooks/events.js";import{installJsonHooks as w,uninstallJsonHooks as T}from"./hooks/writers.js";import{installHooks as E,uninstallHooks as D}from"./hooks/install.js";import{generateConfigEntry as O}from"./mcp/config-entry.js";import{inspectMcpInstall as k,installMcp as A}from"./mcp/installer.js";import{getMcpCliInstallCommand as j}from"./mcp/cli-install-command.js";import{uninstallMcp as M}from"./mcp/uninstaller.js";import{SKILL_MANIFEST_FILE_NAME as N,SKILL_MANIFEST_SCHEMA_VERSION as P}from"./skills/manifest.js";import{allSkillAgents as F,isSkillAgentSupported as I,skillDir as L}from"./skills/skill-dirs.js";import{SkillConflictError as R,SkillUnsupportedManifestError as z,inspectSkillStatus as B,installSkill as V,uninstallSkill as H}from"./skills/install.js";export{S as HookConfigError,N as SKILL_MANIFEST_FILE_NAME,P as SKILL_MANIFEST_SCHEMA_VERSION,R as SkillConflictError,z as SkillUnsupportedManifestError,t as allClients,F as allSkillAgents,n as antigravityLegacyPath,r as clientCommand,i as clientConfigPath,a as clientConfigPaths,o as clientDisplayName,s as clientExecutablePath,c as clientJSONPath,l as clientType,u as clientsForHost,d as detectClient,C as eventManifest,O as generateConfigEntry,f as getClientInstallation,j as getMcpCliInstallCommand,p as hostIdentity,m as hostOf,k as inspectMcpInstall,B as inspectSkillStatus,E as installHooks,w as installJsonHooks,A as installMcp,V as installSkill,h as isInstallable,g as isLegacy,I as isSkillAgentSupported,_ as isSupported,e as joinPath,v as legacyClientIds,y as listAgents,b as mcpNamesForHook,x as resolveHookClient,L as skillDir,D as uninstallHooks,T as uninstallJsonHooks,M as uninstallMcp,H as uninstallSkill};

package/dist/mcp/cli-install-command.d.ts

@@ -0,0 +1,27 @@
+import { AgentHostConfig } from "../config.js";
+import { McpInstallRequest } from "./installer.js";
+
+//#region src/mcp/cli-install-command.d.ts
+/**
+ * Returns the argv of the client's own CLI shortcut for installing the
+ * GitKraken MCP server, or `undefined` when the host should go straight to
+ * {@link installMcp}. The host runs the argv and falls back to
+ * {@link installMcp} on failure, preserving Go's order (`installVSCode`,
+ * `installClaudeCLI`, `installCodex`, …).
+ *
+ * `undefined` when the client has no shortcut, and also when the shortcut
+ * would not do the job:
+ * - `request.configPath` is set, because no shortcut can target a specific file.
+ * - Cursor: gkcli ignores the outcome of `cursor --add-mcp` and always writes
+ *   `~/.cursor/mcp.json`, so the direct write is the install.
+ * - Codex, when its config still holds the legacy `['mcp_servers.GitKraken']`
+ *   table: `codex mcp add` would leave it behind, so the direct write must
+ *   replace it.
+ *
+ * Excludes gkcli's GitLens deep-link URL scheme (`vscode:mcp/install?…`,
+ * `cursor://…`), which is a browser-launch side effect outside this
+ * library's scope.
+ */
+declare function getMcpCliInstallCommand(request: McpInstallRequest, config: AgentHostConfig): Promise<string[] | undefined>;
+//#endregion
+export { getMcpCliInstallCommand };

package/dist/mcp/cli-install-command.js

@@ -0,0 +1 @@
+import{inspectMcpInstall as e}from"./installer.js";function t(e,t,n){return JSON.stringify({command:t,type:`stdio`,name:e,args:[...n]})}async function n(n,r){if(n.configPath)return;let{client:i,executablePath:a,args:o}=n;switch(i){case`vscode`:return[`code`,`--add-mcp`,t(`GitKraken`,a,o)];case`vscode-insiders`:return[`code-insiders`,`--add-mcp`,t(`GitKraken`,a,o)];case`claude-cli`:return[`claude`,`mcp`,`add`,`GitKraken`,`-s`,`user`,`--`,a,...o];case`trae`:return[`trae`,`--add-mcp`,t(``,a,o)];case`codex`:{let{reason:t}=await e(n,r);return t===`legacy-location`?void 0:[`codex`,`mcp`,`add`,`GitKraken`,a,...o]}default:return}}export{n as getMcpCliInstallCommand};

package/dist/mcp/clients.d.ts

@@ -0,0 +1,87 @@
+import { AgentHostConfig } from "../config.js";
+
+//#region src/mcp/clients.d.ts
+/**
+ * The 16 MCP client ids gkcli knows about. `gemini` is legacy: retained only
+ * so an uninstall can clear a stale GitKraken entry, and excluded from
+ * {@link allClients}.
+ */
+type Client = 'vscode' | 'vscode-insiders' | 'claude' | 'claude-cli' | 'antigravity' | 'antigravity-cli' | 'windsurf' | 'cursor' | 'zed' | 'trae' | 'copilot' | 'codex' | 'gemini' | 'kiro' | 'jetbrains-copilot' | 'opencode';
+/**
+ * How a client runs. Installing into a GUI client may launch its window (VS
+ * Code and Cursor are configured through their own binary); callers that must
+ * not disturb the desktop select `'cli'` clients.
+ */
+type ClientType = 'cli' | 'gui';
+declare const OPEN_CODE_V1_JSON_PATH = "/mcp/GitKraken";
+declare const OPEN_CODE_V2_JSON_PATH = "/mcp/servers/GitKraken";
+/** Every location an OpenCode GitKraken entry may live at: v2 is written, v1 is only recognised and cleaned up. */
+declare const OPEN_CODE_JSON_PATHS: readonly string[];
+declare function isSupported(client: string): boolean;
+/** Whether `client` is retained only for uninstall cleanup (currently only `gemini`). */
+declare function isLegacy(client: Client): boolean;
+/** Safe default for any client-name input: a supported, non-legacy client. */
+declare function isInstallable(client: Client): boolean;
+declare function clientType(client: Client): ClientType | 'unknown';
+declare function clientDisplayName(client: Client): string;
+declare function clientCommand(client: Client): string | undefined;
+/** Every non-legacy client id, in registry order. */
+declare function allClients(): Client[];
+/** Every legacy client id, e.g. `gemini`. */
+declare function legacyClientIds(): Client[];
+/** The `--host=` value the installer bakes into a client's generated args. Rows sharing a host must emit the same value. */
+declare function hostIdentity(client: Client): string;
+/** The client whose configuration surface `client` shares (itself, for every row but the Antigravity pair). */
+declare function hostOf(client: Client): Client;
+/** Every non-legacy row sharing `host`'s configuration surface, `host` itself included, in registry order. */
+declare function clientsForHost(host: Client): Client[];
+/** The JSON pointer (or, for Codex, dotted TOML table key) `installMcp` writes a client's GitKraken entry at. */
+declare function clientJSONPath(client: Client): string;
+/** The single config file path this client's GitKraken entry is written to. */
+declare function clientConfigPath(client: Client, config: AgentHostConfig): Promise<string | undefined>;
+/**
+ * Every config file a client's GitKraken entry may live in: write-and-delete
+ * authority. `uninstallMcp` clears the entry from every path.
+ */
+declare function clientConfigPaths(client: Client, config: AgentHostConfig): Promise<string[]>;
+/** The pre-shared-config location Antigravity's IDE used to read; uninstall still covers it for back-compat. */
+declare function antigravityLegacyPath(config: AgentHostConfig): string;
+/**
+ * The resolved path to the client's binary on `PATH`, or `undefined`. Go's
+ * `exec.LookPath` reads `PATH` and stats candidate directories directly; this
+ * library never reads the environment, so the host injects the lookup.
+ */
+declare function clientExecutablePath(client: Client, config: AgentHostConfig): string | undefined;
+/** How {@link detectClient} found a client. */
+type ClientDetectionSource = 'executable' | 'config-file' | 'config-dir';
+/** Why {@link detectClient} did not find a client. `shared-host-row` is a row such as `antigravity-cli`, which has no config signal of its own and no binary on `PATH`. */
+type ClientNotDetectedReason = 'not-found' | 'shared-host-row';
+interface ClientDetection {
+  client: Client;
+  detected: boolean;
+  /** Set when `detected`. */
+  source?: ClientDetectionSource;
+  /** The client's binary on `PATH`, when `resolveExecutable` found it. */
+  executablePath?: string;
+  /** The config file or directory that matched. */
+  path?: string;
+  /** Set when not `detected`. */
+  reason?: ClientNotDetectedReason;
+  /** Every config file or directory probed, in order. */
+  checkedPaths: string[];
+}
+/**
+ * Whether the client's binary or config directory is present, and how it was
+ * found. Mirrors Go's `mcp.Client.IsDetected`.
+ */
+declare function detectClient(client: Client, config: AgentHostConfig): Promise<ClientDetection>;
+interface ClientInstallation {
+  client: Client;
+  installed: boolean;
+  /** The config files that carry a GitKraken entry, so a host can tell when the entry sits in a legacy file. */
+  paths: string[];
+}
+/** Which of the client's config files already carry a GitKraken entry. Mirrors Go's `mcp.Client.IsInstalled`. */
+declare function getClientInstallation(client: Client, config: AgentHostConfig): Promise<ClientInstallation>;
+//#endregion
+export { Client, ClientDetection, ClientDetectionSource, ClientInstallation, ClientNotDetectedReason, ClientType, OPEN_CODE_JSON_PATHS, OPEN_CODE_V1_JSON_PATH, OPEN_CODE_V2_JSON_PATH, allClients, antigravityLegacyPath, clientCommand, clientConfigPath, clientConfigPaths, clientDisplayName, clientExecutablePath, clientJSONPath, clientType, clientsForHost, detectClient, getClientInstallation, hostIdentity, hostOf, isInstallable, isLegacy, isSupported, legacyClientIds };

package/dist/mcp/clients.js

@@ -0,0 +1 @@
+import{joinPath as e}from"../config.js";import{findAtPointer as t}from"./jsonc-edit.js";import{parseTomlSafe as n,tomlDottedPath as r,tomlLiteralKey as i}from"./toml-read.js";const a=`/mcp/GitKraken`,o=`/mcp/servers/GitKraken`,s=[o,a];function c(t,...n){return e(t.paths.home,...n)}function l(e){return e.platform===`linux`?e.paths.configHome:e.paths.appSupport}function u(t){return e(t.paths.configHome,`opencode`)}const d=[{id:`vscode`,displayName:`VS Code`,clientType:`gui`,command:`code`,jsonPath:`/servers/GitKraken`,pathFn:t=>e(l(t),`Code`,`User`,`mcp.json`),legacy:!1},{id:`vscode-insiders`,displayName:`VS Code Insiders`,clientType:`gui`,command:`code-insiders`,jsonPath:`/servers/GitKraken`,pathFn:t=>e(l(t),`Code - Insiders`,`User`,`mcp.json`),legacy:!1},{id:`claude`,displayName:`Claude Desktop`,clientType:`gui`,command:`claude`,jsonPath:`/mcpServers/GitKraken`,pathFn:t=>e(l(t),`Claude`,`claude_desktop_config.json`),legacy:!1},{id:`claude-cli`,displayName:`Claude Code`,clientType:`cli`,command:`claude`,jsonPath:`/mcpServers/GitKraken`,pathFn:t=>t.paths.claudeConfigDir?e(t.paths.claudeConfigDir,`.claude.json`):c(t,`.claude.json`),legacy:!1},{id:`antigravity`,displayName:`Antigravity`,clientType:`gui`,command:`antigravity`,jsonPath:`/mcpServers/GitKraken`,pathFn:e=>c(e,`.gemini`,`config`,`mcp_config.json`),legacy:!1,host:`antigravity`},{id:`antigravity-cli`,displayName:`Antigravity CLI`,clientType:`cli`,command:`agy`,jsonPath:`/mcpServers/GitKraken`,pathFn:e=>c(e,`.gemini`,`config`,`mcp_config.json`),legacy:!1,host:`antigravity`},{id:`windsurf`,displayName:`Windsurf`,clientType:`gui`,command:`windsurf`,jsonPath:`/mcpServers/GitKraken`,pathFn:e=>c(e,`.codeium`,`windsurf`,`mcp_config.json`),legacy:!1},{id:`cursor`,displayName:`Cursor`,clientType:`gui`,command:`cursor`,jsonPath:`/mcpServers/GitKraken`,pathFn:e=>c(e,`.cursor`,`mcp.json`),legacy:!1},{id:`zed`,displayName:`Zed`,clientType:`gui`,command:`zed`,jsonPath:`/context_servers/GitKraken`,pathFn:t=>t.platform===`win32`?e(t.paths.appSupport,`Zed`,`settings.json`):t.platform===`darwin`?c(t,`.config`,`zed`,`settings.json`):e(t.paths.configHome,`zed`,`settings.json`),legacy:!1},{id:`trae`,displayName:`Trae`,clientType:`gui`,command:`trae`,jsonPath:`/mcpServers/GitKraken`,pathFn:t=>e(l(t),`Trae`,`User`,`mcp.json`),legacy:!1},{id:`copilot`,displayName:`GitHub Copilot CLI`,clientType:`cli`,command:`copilot`,jsonPath:`/mcpServers/GitKraken`,pathFn:e=>c(e,`.copilot`,`mcp-config.json`),legacy:!1},{id:`codex`,displayName:`Codex`,clientType:`cli`,command:`codex`,jsonPath:`mcp_servers.GitKraken`,pathFn:e=>c(e,`.codex`,`config.toml`),legacy:!1},{id:`gemini`,displayName:`Gemini CLI`,clientType:`cli`,command:`gemini`,jsonPath:`/mcpServers/GitKraken`,pathFn:e=>c(e,`.gemini`,`settings.json`),legacy:!0},{id:`kiro`,displayName:`Kiro`,clientType:`gui`,command:`kiro`,jsonPath:`/mcpServers/GitKraken`,pathFn:e=>c(e,`.kiro`,`settings`,`mcp.json`),legacy:!1},{id:`jetbrains-copilot`,displayName:`JetBrains Copilot`,clientType:`gui`,jsonPath:`/servers/GitKraken`,pathFn:t=>t.platform===`win32`?e(t.paths.localAppData??e(t.paths.home,`AppData`,`Local`),`github-copilot`,`intellij`,`mcp.json`):e(t.paths.configHome,`github-copilot`,`intellij`,`mcp.json`),legacy:!1},{id:`opencode`,displayName:`OpenCode`,clientType:`cli`,command:`opencode`,jsonPath:o,pathFn:t=>e(u(t),`opencode.json`),legacy:!1}];function f(e){return d.find(t=>t.id===e)}function p(e){return f(e)!==void 0}function m(e){return f(e)?.legacy===!0}function h(e){let t=f(e);return t!==void 0&&!t.legacy}function g(e){return f(e)?.clientType??`unknown`}function _(e){return f(e)?.displayName??e}function v(e){return f(e)?.command}function y(){return d.filter(e=>!e.legacy).map(e=>e.id)}function b(){return d.filter(e=>e.legacy).map(e=>e.id)}function x(e){return(f(e)?.host??e).toLowerCase()}function S(e){return f(e)?.host??e}function C(e){return d.filter(t=>!t.legacy&&(t.host??t.id)===e).map(e=>e.id)}function w(e){return f(e)?.jsonPath??``}async function T(t){let n=u(t),r=e(n,`opencode.jsonc`);return await t.fs.readFile(r)===null?e(n,`opencode.json`):r}async function E(e,t){let n=f(e);if(n)return e===`opencode`?T(t):n.pathFn(t)}async function D(e,t){let n=await E(e,t),r=n?[n]:[];return e===`antigravity`&&r.push(c(t,`.gemini`,`antigravity`,`mcp_config.json`)),r}function O(e){return c(e,`.gemini`,`antigravity`,`mcp_config.json`)}function k(e,t){let n=v(e);if(!(!n||!t.resolveExecutable))return t.resolveExecutable(n)}function A(e,t){let n=f(e);return n?.host?C(n.host).some(n=>n!==e&&k(n,t)!==void 0):!1}async function j(e,t){if(!t)return;let n=t.lastIndexOf(`/`),r=n>0?t.slice(0,n):``;if(r)return r===e.paths.home.replace(/\/+$/,``)?{matched:await e.fs.readFile(t)!==null,source:`config-file`,path:t}:{matched:await e.fs.readDir(r)!==null,source:`config-dir`,path:r}}async function M(e,t,n,r){for(let i of t){let t=await j(n,i);if(t&&(r.push(t.path),t.matched))return{client:e,detected:!0,source:t.source,path:t.path,checkedPaths:r}}return{client:e,detected:!1,reason:`not-found`,checkedPaths:r}}async function N(e,t){let n=k(e,t),r=[];if(n!==void 0)return{client:e,detected:!0,source:`executable`,executablePath:n,checkedPaths:r};let i=f(e);if(i?.host&&i.host!==e)return{client:e,detected:!1,reason:`shared-host-row`,checkedPaths:r};if(e===`antigravity`){let n=i?.pathFn(t);return n&&!A(e,t)&&(r.push(n),await t.fs.readFile(n)!==null)?{client:e,detected:!0,source:`config-file`,path:n,checkedPaths:r}:M(e,[O(t)],t,r)}return M(e,await D(e,t),t,r)}async function P(e,t){let n=[];for(let r of await D(e,t))await F(e,r,t)&&n.push(r);return{client:e,installed:n.length>0,paths:n}}async function F(e,a,o){let c=await o.fs.readFile(a);if(c===null||c.trim()===``)return!1;if(e===`codex`){let e=n(c);if(!e)return!1;let t=w(`codex`);return i(e,t)!==void 0||r(e,t)!==void 0}return(e===`opencode`?s:[w(e)]).some(e=>t(c,e)!==void 0)}export{s as OPEN_CODE_JSON_PATHS,a as OPEN_CODE_V1_JSON_PATH,o as OPEN_CODE_V2_JSON_PATH,y as allClients,O as antigravityLegacyPath,v as clientCommand,E as clientConfigPath,D as clientConfigPaths,_ as clientDisplayName,k as clientExecutablePath,w as clientJSONPath,g as clientType,C as clientsForHost,N as detectClient,P as getClientInstallation,x as hostIdentity,S as hostOf,h as isInstallable,m as isLegacy,p as isSupported,b as legacyClientIds};

package/dist/mcp/config-entry.d.ts

@@ -0,0 +1,13 @@
+import { Client } from "./clients.js";
+
+//#region src/mcp/config-entry.d.ts
+/** The shape of an entry `installMcp` writes: keys vary per client family (see {@link generateConfigEntry}). */
+type McpConfigEntry = Record<string, unknown>;
+/**
+ * Builds the entry a client's GitKraken MCP server config carries. Port of
+ * gkcli's `installer.generateConfigs`/`installConfig`: four shapes dispatched
+ * by client family. OpenCode always gets its v2 shape.
+ */
+declare function generateConfigEntry(client: Client, executablePath: string, args: readonly string[]): McpConfigEntry;
+//#endregion
+export { McpConfigEntry, generateConfigEntry };

package/dist/mcp/config-entry.js

@@ -0,0 +1 @@
+function e(e,t,n){switch(e){case`zed`:return{source:`custom`,enabled:!0,command:t,args:[...n]};case`copilot`:return{type:`local`,command:t,tools:[`*`],args:[...n]};case`opencode`:return{type:`local`,command:[t,...n],disabled:!1};default:return{type:`stdio`,command:t,args:[...n]}}}export{e as generateConfigEntry};

package/dist/mcp/index.d.ts

@@ -0,0 +1,6 @@
+import { Client, ClientDetection, ClientDetectionSource, ClientInstallation, ClientNotDetectedReason, ClientType, allClients, antigravityLegacyPath, clientCommand, clientConfigPath, clientConfigPaths, clientDisplayName, clientExecutablePath, clientJSONPath, clientType, clientsForHost, detectClient, getClientInstallation, hostIdentity, hostOf, isInstallable, isLegacy, isSupported, legacyClientIds } from "./clients.js";
+import { McpConfigEntry, generateConfigEntry } from "./config-entry.js";
+import { McpInstallRequest, McpInstallResult, McpInstallState, McpInstallStateReason, McpInstallStatus, inspectMcpInstall, installMcp } from "./installer.js";
+import { getMcpCliInstallCommand } from "./cli-install-command.js";
+import { McpUninstallFileResult, McpUninstallRequest, McpUninstallResult, uninstallMcp } from "./uninstaller.js";
+export { type Client, type ClientDetection, type ClientDetectionSource, type ClientInstallation, type ClientNotDetectedReason, type ClientType, type McpConfigEntry, type McpInstallRequest, type McpInstallResult, type McpInstallState, type McpInstallStateReason, type McpInstallStatus, type McpUninstallFileResult, type McpUninstallRequest, type McpUninstallResult, allClients, antigravityLegacyPath, clientCommand, clientConfigPath, clientConfigPaths, clientDisplayName, clientExecutablePath, clientJSONPath, clientType, clientsForHost, detectClient, generateConfigEntry, getClientInstallation, getMcpCliInstallCommand, hostIdentity, hostOf, inspectMcpInstall, installMcp, isInstallable, isLegacy, isSupported, legacyClientIds, uninstallMcp };

package/dist/mcp/index.js

@@ -0,0 +1 @@
+import{allClients as e,antigravityLegacyPath as t,clientCommand as n,clientConfigPath as r,clientConfigPaths as i,clientDisplayName as a,clientExecutablePath as o,clientJSONPath as s,clientType as c,clientsForHost as l,detectClient as u,getClientInstallation as d,hostIdentity as f,hostOf as p,isInstallable as m,isLegacy as h,isSupported as g,legacyClientIds as _}from"./clients.js";import{generateConfigEntry as v}from"./config-entry.js";import{inspectMcpInstall as y,installMcp as b}from"./installer.js";import{getMcpCliInstallCommand as x}from"./cli-install-command.js";import{uninstallMcp as S}from"./uninstaller.js";export{e as allClients,t as antigravityLegacyPath,n as clientCommand,r as clientConfigPath,i as clientConfigPaths,a as clientDisplayName,o as clientExecutablePath,s as clientJSONPath,c as clientType,l as clientsForHost,u as detectClient,v as generateConfigEntry,d as getClientInstallation,x as getMcpCliInstallCommand,f as hostIdentity,p as hostOf,y as inspectMcpInstall,b as installMcp,m as isInstallable,h as isLegacy,g as isSupported,_ as legacyClientIds,S as uninstallMcp};

package/dist/mcp/installer.d.ts

@@ -0,0 +1,69 @@
+import { AgentHostConfig } from "../config.js";
+import { Client } from "./clients.js";
+import { McpConfigEntry } from "./config-entry.js";
+
+//#region src/mcp/installer.d.ts
+interface McpInstallRequest {
+  client: Client;
+  executablePath: string;
+  /** The full MCP server argv the host computed (e.g. `['mcp', '--host=cursor']`); this library never derives it. */
+  args: readonly string[];
+  /**
+   * Targets this path instead of the client's resolved config path. Lets a
+   * host aim at a specific file, such as a workspace-scoped config.
+   */
+  configPath?: string;
+}
+/** How the client's config compares to what `installMcp` would write. */
+type McpInstallState = 'missing' | 'drifted' | 'current';
+/** Why {@link inspectMcpInstall} reported its state. Absent when the state is `current`. */
+type McpInstallStateReason = /** `missing`: the client's config file does not exist. */'file-missing' /** `missing`: the config file does not parse, so no entry can be read. */ | 'invalid-config' /** `missing`: the config has no GitKraken entry. */ | 'no-entry' /** `missing`: the GitKraken key exists but is not an object. */ | 'entry-not-object' /** `missing`: the client id is unknown or uninstall-only, so it has no config to inspect. */ | 'unsupported-client' /** `drifted`: the entry sits where an older install wrote it (Codex's literal-key table, OpenCode's v1 shape). */ | 'legacy-location' /** `drifted`: the entry lacks `command` or `args`. */ | 'pinned-key-missing' /** `drifted`: a key `installMcp` writes holds a different value. */ | 'value-mismatch';
+interface McpInstallStatus {
+  client: Client;
+  state: McpInstallState;
+  /** The config file inspected; empty when the client has none. */
+  path: string;
+  /** Where the entry was looked up, or found when it is a legacy location. */
+  location: string;
+  reason?: McpInstallStateReason;
+  /** The key that differs, for `pinned-key-missing` and `value-mismatch`. */
+  key?: string;
+  /** The entry on disk, when one exists. A host can read it to carry user-added args forward before reinstalling. */
+  entry?: Record<string, unknown>;
+}
+interface McpInstallResult {
+  client: Client;
+  /** The config file written. */
+  path: string;
+  change: 'created' | 'updated' | 'unchanged';
+  format: 'json' | 'toml';
+  /** A JSON pointer, or the Codex dotted TOML table key. */
+  location: string;
+  /** The entry written, or already present when `change` is `unchanged`. */
+  entry: McpConfigEntry;
+  /** Stale locations pruned from the file, such as OpenCode's v1 pointer; empty otherwise. */
+  removedLocations: string[];
+}
+/**
+ * Writes the GitKraken entry in the shape each client reads. The shapes are
+ * compatible with entries gkcli writes, so either tool recognises and repairs
+ * the other's. A re-run that finds the entry already in place writes nothing.
+ * Port of gkcli's installer.
+ *
+ * OpenCode gets its v2 shape and any v1 entry is pruned, which a v1-only
+ * OpenCode will no longer read. Run the client's own CLI shortcut first when
+ * it has one (see {@link getMcpCliInstallCommand}); this is the direct
+ * config-file write.
+ *
+ * Throws, without writing, for a client that is unknown or uninstall-only and
+ * for an existing config file that does not parse.
+ */
+declare function installMcp(request: McpInstallRequest, config: AgentHostConfig): Promise<McpInstallResult>;
+/**
+ * Reports whether the client's config already holds an entry equivalent to
+ * the one `installMcp` would write, and if not, why. Mirrors Go's
+ * `installer.State`.
+ */
+declare function inspectMcpInstall(request: McpInstallRequest, config: AgentHostConfig): Promise<McpInstallStatus>;
+//#endregion
+export { McpInstallRequest, McpInstallResult, McpInstallState, McpInstallStateReason, McpInstallStatus, inspectMcpInstall, installMcp };

package/dist/mcp/installer.js

@@ -0,0 +1,3 @@
+import{addAtPointer as e,findAtPointer as t,isValidJsonc as n,removeAtPointerAndEmptyParent as r}from"./jsonc-edit.js";import{assertValidToml as i,parseTomlSafe as a,tomlDottedPath as o,tomlLiteralKey as s}from"./toml-read.js";import{OPEN_CODE_V1_JSON_PATH as c,clientConfigPath as l,clientJSONPath as u,isInstallable as d}from"./clients.js";import{writeFileTracked as f}from"../file-change.js";import{generateConfigEntry as p}from"./config-entry.js";import{tomlSemanticEqual as m,withoutCodexEntry as h}from"./toml-safety.js";import{removeBlock as g,replaceOrAppendBlock as _}from"./toml-splice.js";import{stringify as v}from"smol-toml";const y=[`command`,`args`];async function b(n,i){let{client:a}=n,o=d(a)?n.configPath??await l(a,i):void 0;if(!o)throw Error(`unsupported client: ${a}`);let s=p(a,n.executablePath,n.args);if(a===`codex`)return x(n,i,o,s);let m=await i.fs.readFile(o),h=m===null||m.trim()===``?`{}`:m,g=u(a),_=t(h,g),v=m!==null&&C(_)&&k(_,s,{client:a,path:o,location:g}).state===`current`,y=v?h:e(h,g,s,o),b=[];if(a===`opencode`){let e=r(v?h:y,c,o);e.removed&&(y=e.text,b.push(c))}return{client:a,path:o,change:v&&b.length===0?`unchanged`:await f(i.fs,o,y,[],{mode:420}),format:`json`,location:g,entry:v?_:s,removedLocations:b}}async function x(e,t,n,r){let c=await t.fs.readFile(n);c!==null&&c.trim()!==``&&i(c,n);let l=u(`codex`),d=c??``,p=a(d),v=o(p,l),y=s(p,l);if(c!==null&&y===void 0&&C(v)&&k(v,r,{client:e.client,path:n,location:l}).state===`current`)return{client:e.client,path:n,change:`unchanged`,format:`toml`,location:l,entry:v,removedLocations:[]};let b,x,w=[];if(y!==void 0){if(!C(y)||v!==void 0&&!C(v))throw Error(`cannot safely migrate Codex MCP entry in ${n}: ambiguous legacy and nested tables`);let e=C(v)&&v.env!==void 0?v.env:y.env;if(e!==void 0&&!C(e))throw Error(`cannot safely migrate Codex MCP entry in ${n}: legacy env is not a table`);if(Object.entries(y).some(([e,t])=>e!==`env`&&C(t))||e&&Object.values(e).some(C))throw Error(`cannot safely migrate Codex MCP entry in ${n}: unsupported legacy subtable`);x=e;let t=g(d,l).text;b=_(v===void 0?t:g(t,l).text,l,S(l,r,e)),w.push(`["${l}"]`)}else b=_(d,l,S(l,r));let T=a(b),E=o(T,l);if(!C(E)||k(E,r,{client:e.client,path:n,location:l}).state!==`current`||s(T,l)!==void 0||y!==void 0&&!m(E.env,x)||!m(h(T),h(p)))throw Error(`cannot safely update Codex MCP entry in ${n}: unsupported TOML representation`);let D=await f(t.fs,n,b,[],{mode:384});return{client:e.client,path:n,change:D,format:`toml`,location:l,entry:E,removedLocations:w}}function S(e,t,n){let r=v(t),i=r.endsWith(`
+`)?r:`${r}\n`,a=n===void 0?``:v(n);return`[${e}]\n${i}${n===void 0?``:`\n[${e}.env]\n${a.endsWith(`
+`)?a:`${a}\n`}`}`}function C(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function w(e,t){return{...e,state:`missing`,reason:t}}function T(e,t){return{...e,state:`drifted`,reason:`legacy-location`,...C(t)&&{entry:t}}}async function E(e,r){let{client:i}=e,a=u(i),o=d(i)?e.configPath??await l(i,r):void 0;if(!o)return w({client:i,path:``,location:a},`unsupported-client`);let s={client:i,path:o,location:a},c=await r.fs.readFile(o);if(c===null)return w(s,`file-missing`);let f=p(i,e.executablePath,e.args);if(i===`codex`)return D(c,f,s);if(c.trim()===``)return w(s,`no-entry`);if(!n(c))return w(s,`invalid-config`);if(i===`opencode`)return O(c,f,s);let m=t(c,a);return m===void 0?w(s,`no-entry`):C(m)?k(m,f,s):w(s,`entry-not-object`)}function D(e,t,n){if(e.trim()===``)return w(n,`no-entry`);let r=a(e);if(!r)return w(n,`invalid-config`);let i=s(r,n.location);if(i!==void 0)return T(n,i);let c=o(r,n.location);return c===void 0?w(n,`no-entry`):C(c)?k(c,t,n):w(n,`entry-not-object`)}function O(e,n,r){let i=t(e,r.location),a=t(e,c),o={...r,location:c};if(i===void 0)return a===void 0?w(r,`no-entry`):T(o,a);if(!C(i))return w(r,`entry-not-object`);let s=k(i,n,r);return s.state===`current`&&a!==void 0?T(o,a):s}function k(e,t,n){for(let[r,i]of Object.entries(t)){if(!(r in e)){if(y.includes(r))return{...n,state:`drifted`,reason:`pinned-key-missing`,key:r,entry:e};continue}if(!A(e[r],i))return{...n,state:`drifted`,reason:`value-mismatch`,key:r,entry:e}}return{...n,state:`current`,entry:e}}function A(e,t){if(e===t)return!0;if(typeof e!=typeof t||e===null||t===null||typeof e!=`object`)return!1;if(Array.isArray(e)||Array.isArray(t))return!Array.isArray(e)||!Array.isArray(t)||e.length!==t.length?!1:e.every((e,n)=>A(e,t[n]));let n=Object.keys(e),r=Object.keys(t);return n.length===r.length?n.every(n=>A(e[n],t[n])):!1}export{E as inspectMcpInstall,b as installMcp};

package/dist/mcp/jsonc-edit.d.ts

@@ -0,0 +1,41 @@
+//#region src/mcp/jsonc-edit.d.ts
+/** Whether `text` is valid JSONC: comments, a trailing comma and a leading UTF-8 BOM are all fine. */
+declare function isValidJsonc(text: string): boolean;
+/** Reads the value at `pointer` in JSONC `text`, or `undefined` when absent or the document is unparsable. */
+declare function findAtPointer(text: string, pointer: string): unknown;
+/**
+ * Adds `value` at `pointer`, creating any missing parent objects along the
+ * way (mirrors gkcli's `installer.writeConfig`, which patches in each
+ * missing parent as `{}` before adding the leaf so a JSON-patch "add" never
+ * fails on a missing container). Comment-preserving: only the edited range
+ * is touched. `sourcePath` names `text`'s file for the error thrown when it
+ * isn't valid JSONC; no edit is made in that case.
+ */
+declare function addAtPointer(text: string, pointer: string, value: unknown, sourcePath: string): string;
+/**
+ * Removes the value at `pointer`, leaving its parent container in place even
+ * if that empties it. Mirrors gkcli's `uninstaller.writeConfig`, the shape
+ * every plain client's `UninstallMCP` uses. `sourcePath` names `text`'s file
+ * for the error thrown when it isn't valid JSONC; no edit is made in that case.
+ *
+ * Returns `removed: false` when there was nothing at `pointer` to begin with.
+ */
+declare function removeAtPointer(text: string, pointer: string, sourcePath: string): {
+  text: string;
+  removed: boolean;
+};
+/**
+ * Removes the value at `pointer`, and then its parent container when that
+ * removal left it an empty object. Mirrors gkcli's
+ * `uninstaller.removeJSONPointer`, used only for OpenCode: v1 reads every key
+ * under `/mcp` as a server definition, so an empty `servers` husk would parse
+ * as one with no command. `sourcePath` is as for {@link removeAtPointer}.
+ *
+ * Returns `removed: false` when there was nothing at `pointer` to begin with.
+ */
+declare function removeAtPointerAndEmptyParent(text: string, pointer: string, sourcePath: string): {
+  text: string;
+  removed: boolean;
+};
+//#endregion
+export { addAtPointer, findAtPointer, isValidJsonc, removeAtPointer, removeAtPointerAndEmptyParent };