context-gatekeeper 0.3.0

package/dist/scripts/cli/detect.js

@@ -0,0 +1,131 @@
+/**
+ * Agent config-file path detection.
+ *
+ * Each supported MCP agent has its own global config path (and most also
+ * support a project-local override). This module maps agent names to the
+ * absolute path of the config file the agent will actually read, taking
+ * the current platform into account.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+function appDataWindows() {
+    return process.env.APPDATA ?? join(homedir(), 'AppData', 'Roaming');
+}
+/**
+ * Path specs for each agent's *global* config file.
+ * Project-level paths (workspace-local) are resolved by the caller.
+ */
+const GLOBAL_PATHS = {
+    cursor: {
+        win: () => join(homedir(), '.cursor', 'mcp.json'),
+        posix: () => join(homedir(), '.cursor', 'mcp.json'),
+    },
+    'claude-desktop': {
+        win: () => join(appDataWindows(), 'Claude', 'claude_desktop_config.json'),
+        posix: () => join(homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'),
+    },
+    cline: {
+        win: () => join(homedir(), '.vscode', 'mcp.json'),
+        posix: () => join(homedir(), '.vscode', 'mcp.json'),
+    },
+    continue: {
+        win: () => join(appDataWindows(), 'continue', 'config.json'),
+        posix: () => join(homedir(), '.continue', 'config.json'),
+    },
+    'claude-code': {
+        win: () => join(homedir(), '.mcp.json'),
+        posix: () => join(homedir(), '.mcp.json'),
+    },
+};
+function pickGlobalPath(agent) {
+    const spec = GLOBAL_PATHS[agent];
+    return process.platform === 'win32' ? spec.win() : spec.posix();
+}
+function pickProjectPath(agent, cwd) {
+    // Claude Desktop is global-only.
+    if (agent === 'claude-desktop')
+        return null;
+    switch (agent) {
+        case 'cursor':
+            return join(cwd, '.cursor', 'mcp.json');
+        case 'cline':
+            return join(cwd, '.vscode', 'mcp.json');
+        case 'continue':
+            return join(cwd, '.continue', 'config.json');
+        case 'claude-code':
+            return join(cwd, '.mcp.json');
+    }
+}
+export const SUPPORTED_AGENTS = [
+    'cursor',
+    'claude-desktop',
+    'cline',
+    'continue',
+    'claude-code',
+];
+export function isValidAgent(name) {
+    return SUPPORTED_AGENTS.includes(name);
+}
+/**
+ * Detect where the agent's config file lives. Prefers project-level when
+ * `scope === 'project'`, otherwise global. If `scope` is omitted, returns
+ * the path that exists (or would be written), preferring project-level.
+ */
+export function detectAgent(agent, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const scope = options.scope ?? 'global';
+    const configPath = scope === 'project'
+        ? pickProjectPath(agent, cwd) ?? pickGlobalPath(agent)
+        : pickGlobalPath(agent);
+    const exists = existsSync(configPath);
+    const installed = exists && configContainsGatekeeper(configPath);
+    return { agent, scope, configPath, exists, installed };
+}
+/**
+ * Probe all supported agents for their detection state.
+ */
+export function detectAll(options = {}) {
+    return SUPPORTED_AGENTS.map((a) => detectAgent(a, options));
+}
+/**
+ * Filter a list of detections to those whose config file currently exists.
+ * Used by `--all` to skip agents that are not installed on this machine.
+ */
+export function filterDetected(detections) {
+    return detections.filter((d) => d.exists);
+}
+/**
+ * Cheap heuristic check: read the file and see if "context-gatekeeper"
+ * appears as a key in the `mcpServers` map or as an entry in
+ * `experimental.modelContextProtocolServers`.
+ */
+function configContainsGatekeeper(filePath) {
+    let raw;
+    try {
+        raw = readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return false;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return false;
+    const obj = parsed;
+    const servers = obj.mcpServers;
+    if (servers && typeof servers === 'object' && 'context-gatekeeper' in servers) {
+        return true;
+    }
+    const exp = obj.experimental;
+    if (exp?.modelContextProtocolServers?.some((s) => s.name === 'context-gatekeeper')) {
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=detect.js.map

package/dist/scripts/cli/detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["detect.ts"],"names":[],"mappings":"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"}

package/dist/scripts/cli/detect.ts

@@ -0,0 +1,162 @@
+/**
+ * Agent config-file path detection.
+ *
+ * Each supported MCP agent has its own global config path (and most also
+ * support a project-local override). This module maps agent names to the
+ * absolute path of the config file the agent will actually read, taking
+ * the current platform into account.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+export type AgentName = 'cursor' | 'claude-desktop' | 'cline' | 'continue' | 'claude-code';
+
+export type Scope = 'global' | 'project';
+
+export interface AgentDetection {
+  agent: AgentName;
+  scope: Scope;
+  configPath: string;
+  exists: boolean;
+  /** True if the config file already references context-gatekeeper. */
+  installed: boolean;
+}
+
+interface PathSpec {
+  win: () => string;
+  posix: () => string;
+}
+
+function appDataWindows(): string {
+  return process.env.APPDATA ?? join(homedir(), 'AppData', 'Roaming');
+}
+
+/**
+ * Path specs for each agent's *global* config file.
+ * Project-level paths (workspace-local) are resolved by the caller.
+ */
+const GLOBAL_PATHS: Record<AgentName, PathSpec> = {
+  cursor: {
+    win: () => join(homedir(), '.cursor', 'mcp.json'),
+    posix: () => join(homedir(), '.cursor', 'mcp.json'),
+  },
+  'claude-desktop': {
+    win: () => join(appDataWindows(), 'Claude', 'claude_desktop_config.json'),
+    posix: () => join(homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'),
+  },
+  cline: {
+    win: () => join(homedir(), '.vscode', 'mcp.json'),
+    posix: () => join(homedir(), '.vscode', 'mcp.json'),
+  },
+  continue: {
+    win: () => join(appDataWindows(), 'continue', 'config.json'),
+    posix: () => join(homedir(), '.continue', 'config.json'),
+  },
+  'claude-code': {
+    win: () => join(homedir(), '.mcp.json'),
+    posix: () => join(homedir(), '.mcp.json'),
+  },
+};
+
+function pickGlobalPath(agent: AgentName): string {
+  const spec = GLOBAL_PATHS[agent];
+  return process.platform === 'win32' ? spec.win() : spec.posix();
+}
+
+function pickProjectPath(agent: AgentName, cwd: string): string | null {
+  // Claude Desktop is global-only.
+  if (agent === 'claude-desktop') return null;
+  switch (agent) {
+    case 'cursor':
+      return join(cwd, '.cursor', 'mcp.json');
+    case 'cline':
+      return join(cwd, '.vscode', 'mcp.json');
+    case 'continue':
+      return join(cwd, '.continue', 'config.json');
+    case 'claude-code':
+      return join(cwd, '.mcp.json');
+  }
+}
+
+export const SUPPORTED_AGENTS: AgentName[] = [
+  'cursor',
+  'claude-desktop',
+  'cline',
+  'continue',
+  'claude-code',
+];
+
+export function isValidAgent(name: string): name is AgentName {
+  return (SUPPORTED_AGENTS as string[]).includes(name);
+}
+
+/**
+ * Detect where the agent's config file lives. Prefers project-level when
+ * `scope === 'project'`, otherwise global. If `scope` is omitted, returns
+ * the path that exists (or would be written), preferring project-level.
+ */
+export function detectAgent(
+  agent: AgentName,
+  options: { scope?: Scope; cwd?: string } = {},
+): AgentDetection {
+  const cwd = options.cwd ?? process.cwd();
+  const scope: Scope = options.scope ?? 'global';
+
+  const configPath =
+    scope === 'project'
+      ? pickProjectPath(agent, cwd) ?? pickGlobalPath(agent)
+      : pickGlobalPath(agent);
+
+  const exists = existsSync(configPath);
+  const installed = exists && configContainsGatekeeper(configPath);
+
+  return { agent, scope, configPath, exists, installed };
+}
+
+/**
+ * Probe all supported agents for their detection state.
+ */
+export function detectAll(options: { scope?: Scope; cwd?: string } = {}): AgentDetection[] {
+  return SUPPORTED_AGENTS.map((a) => detectAgent(a, options));
+}
+
+/**
+ * Filter a list of detections to those whose config file currently exists.
+ * Used by `--all` to skip agents that are not installed on this machine.
+ */
+export function filterDetected(detections: AgentDetection[]): AgentDetection[] {
+  return detections.filter((d) => d.exists);
+}
+
+/**
+ * Cheap heuristic check: read the file and see if "context-gatekeeper"
+ * appears as a key in the `mcpServers` map or as an entry in
+ * `experimental.modelContextProtocolServers`.
+ */
+function configContainsGatekeeper(filePath: string): boolean {
+  let raw: string;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch {
+    return false;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return false;
+  }
+  if (!parsed || typeof parsed !== 'object') return false;
+  const obj = parsed as Record<string, unknown>;
+  const servers = obj.mcpServers as Record<string, unknown> | undefined;
+  if (servers && typeof servers === 'object' && 'context-gatekeeper' in servers) {
+    return true;
+  }
+  const exp = obj.experimental as { modelContextProtocolServers?: Array<{ name?: string }> } | undefined;
+  if (exp?.modelContextProtocolServers?.some((s) => s.name === 'context-gatekeeper')) {
+    return true;
+  }
+  return false;
+}

package/dist/scripts/cli/install.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Install (merge) the context-gatekeeper MCP entry into an agent's config
+ * file. Reads the existing JSON (if any), merges in the new entry under
+ * the right location, and atomically writes the result back.
+ */
+import { AgentName, Scope } from './detect.ts';
+export interface InstallResult {
+    agent: AgentName;
+    configPath: string;
+    scope: Scope;
+    status: 'installed' | 'updated' | 'skipped' | 'error';
+    message?: string;
+}
+/**
+ * Install context-gatekeeper into a single agent's config file.
+ * Returns a status record the caller can present to the user.
+ */
+export declare function installAgent(agent: AgentName, options?: {
+    scope?: Scope;
+    cwd?: string;
+    force?: boolean;
+}): InstallResult;
+/**
+ * Install across multiple agents. If `agents` is empty, installs into all
+ * agents whose config file already exists on disk.
+ */
+export declare function installAgents(agents: AgentName[], options?: {
+    scope?: Scope;
+    cwd?: string;
+}): InstallResult[];
+//# sourceMappingURL=install.d.ts.map

package/dist/scripts/cli/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["install.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,SAAS,EAAe,KAAK,EAAoC,MAAM,aAAa,CAAC;AAG9F,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,SAAS,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAmFD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAC7D,aAAa,CAiCf;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,EAAE,EACnB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5C,aAAa,EAAE,CAMjB"}

package/dist/scripts/cli/install.js

@@ -0,0 +1,125 @@
+/**
+ * Install (merge) the context-gatekeeper MCP entry into an agent's config
+ * file. Reads the existing JSON (if any), merges in the new entry under
+ * the right location, and atomically writes the result back.
+ */
+import { readFileSync, writeFileSync, mkdirSync, renameSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { detectAgent, SUPPORTED_AGENTS } from './detect.ts';
+import { buildConfigBlock, GATEKEEPER_KEY } from './config-gen.ts';
+function readJsonOrEmpty(filePath) {
+    if (!existsSync(filePath))
+        return {};
+    try {
+        const raw = readFileSync(filePath, 'utf8');
+        const trimmed = raw.trim();
+        if (trimmed.length === 0)
+            return {};
+        const parsed = JSON.parse(trimmed);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error(`Expected JSON object at ${filePath}, got ${typeof parsed}`);
+        }
+        return parsed;
+    }
+    catch (err) {
+        throw new Error(`Failed to parse ${filePath}: ${err.message}`);
+    }
+}
+function atomicWriteJson(filePath, value) {
+    const dir = dirname(filePath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', 'utf8');
+    renameSync(tmp, filePath);
+}
+/**
+ * For the four agents that use the `mcpServers` shape, merge our entry
+ * under the `context-gatekeeper` key without touching other entries.
+ */
+function mergeMcpServersShape(existing, block) {
+    const existingServers = existing.mcpServers ?? {};
+    const newServers = block.mcpServers ?? {};
+    const hadExisting = GATEKEEPER_KEY in existingServers;
+    const mergedServers = { ...existingServers, ...newServers };
+    return {
+        merged: { ...existing, mcpServers: mergedServers },
+        hadExisting,
+    };
+}
+/**
+ * Continue uses an array under `experimental.modelContextProtocolServers`,
+ * identified by each entry's `name` field.
+ */
+function mergeContinueShape(existing, block) {
+    const exp = existing.experimental ?? {};
+    const arr = exp.modelContextProtocolServers ?? [];
+    const newArr = block.experimental?.modelContextProtocolServers ?? [];
+    const newEntry = newArr[0];
+    const hadExisting = arr.some((e) => e.name === newEntry?.name);
+    const filtered = arr.filter((e) => e.name !== newEntry?.name);
+    filtered.push(newEntry);
+    return {
+        merged: {
+            ...existing,
+            experimental: { ...exp, modelContextProtocolServers: filtered },
+        },
+        hadExisting,
+    };
+}
+function mergeIntoExisting(agent, existing) {
+    const block = buildConfigBlock(agent);
+    if (agent === 'continue')
+        return mergeContinueShape(existing, block);
+    return mergeMcpServersShape(existing, block);
+}
+/**
+ * Install context-gatekeeper into a single agent's config file.
+ * Returns a status record the caller can present to the user.
+ */
+export function installAgent(agent, options = {}) {
+    // Claude Desktop has no project-level config; skip with a clear message
+    // instead of silently falling back to the global path (which would
+    // surprise the user when they thought they were writing to the project).
+    if (options.scope === 'project' && agent === 'claude-desktop') {
+        return {
+            agent,
+            configPath: '(project scope not supported)',
+            scope: 'global',
+            status: 'skipped',
+            message: 'Claude Desktop is global-only; omit --local to install',
+        };
+    }
+    const detection = detectAgent(agent, options);
+    try {
+        const existing = readJsonOrEmpty(detection.configPath);
+        const { merged, hadExisting } = mergeIntoExisting(agent, existing);
+        atomicWriteJson(detection.configPath, merged);
+        return {
+            agent,
+            configPath: detection.configPath,
+            scope: detection.scope,
+            status: hadExisting ? 'updated' : 'installed',
+        };
+    }
+    catch (err) {
+        return {
+            agent,
+            configPath: detection.configPath,
+            scope: detection.scope,
+            status: 'error',
+            message: err.message,
+        };
+    }
+}
+/**
+ * Install across multiple agents. If `agents` is empty, installs into all
+ * agents whose config file already exists on disk.
+ */
+export function installAgents(agents, options = {}) {
+    const targets = agents.length > 0
+        ? agents.map((a) => detectAgent(a, options))
+        : SUPPORTED_AGENTS.map((a) => detectAgent(a, options)).filter((d) => d.exists);
+    return targets.map((d) => installAgent(d.agent, options));
+}
+//# sourceMappingURL=install.js.map

package/dist/scripts/cli/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["install.ts"],"names":[],"mappings":"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"}

package/dist/scripts/cli/install.ts

@@ -0,0 +1,157 @@
+/**
+ * Install (merge) the context-gatekeeper MCP entry into an agent's config
+ * file. Reads the existing JSON (if any), merges in the new entry under
+ * the right location, and atomically writes the result back.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, renameSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+import { AgentName, detectAgent, Scope, AgentDetection, SUPPORTED_AGENTS } from './detect.ts';
+import { buildConfigBlock, GATEKEEPER_KEY } from './config-gen.ts';
+
+export interface InstallResult {
+  agent: AgentName;
+  configPath: string;
+  scope: Scope;
+  status: 'installed' | 'updated' | 'skipped' | 'error';
+  message?: string;
+}
+
+function readJsonOrEmpty(filePath: string): Record<string, unknown> {
+  if (!existsSync(filePath)) return {};
+  try {
+    const raw = readFileSync(filePath, 'utf8');
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) return {};
+    const parsed = JSON.parse(trimmed);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error(`Expected JSON object at ${filePath}, got ${typeof parsed}`);
+    }
+    return parsed as Record<string, unknown>;
+  } catch (err) {
+    throw new Error(`Failed to parse ${filePath}: ${(err as Error).message}`);
+  }
+}
+
+function atomicWriteJson(filePath: string, value: unknown): void {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', 'utf8');
+  renameSync(tmp, filePath);
+}
+
+/**
+ * For the four agents that use the `mcpServers` shape, merge our entry
+ * under the `context-gatekeeper` key without touching other entries.
+ */
+function mergeMcpServersShape(
+  existing: Record<string, unknown>,
+  block: Record<string, unknown>,
+): { merged: Record<string, unknown>; hadExisting: boolean } {
+  const existingServers =
+    (existing.mcpServers as Record<string, unknown> | undefined) ?? {};
+  const newServers =
+    (block.mcpServers as Record<string, unknown> | undefined) ?? {};
+  const hadExisting = GATEKEEPER_KEY in existingServers;
+  const mergedServers = { ...existingServers, ...newServers };
+  return {
+    merged: { ...existing, mcpServers: mergedServers },
+    hadExisting,
+  };
+}
+
+/**
+ * Continue uses an array under `experimental.modelContextProtocolServers`,
+ * identified by each entry's `name` field.
+ */
+function mergeContinueShape(
+  existing: Record<string, unknown>,
+  block: Record<string, unknown>,
+): { merged: Record<string, unknown>; hadExisting: boolean } {
+  const exp = (existing.experimental as Record<string, unknown> | undefined) ?? {};
+  const arr =
+    (exp.modelContextProtocolServers as Array<Record<string, unknown>> | undefined) ?? [];
+  const newArr =
+    ((block.experimental as Record<string, unknown> | undefined)?.modelContextProtocolServers as
+      | Array<Record<string, unknown>>
+      | undefined) ?? [];
+  const newEntry = newArr[0];
+  const hadExisting = arr.some((e) => e.name === newEntry?.name);
+  const filtered = arr.filter((e) => e.name !== newEntry?.name);
+  filtered.push(newEntry);
+  return {
+    merged: {
+      ...existing,
+      experimental: { ...exp, modelContextProtocolServers: filtered },
+    },
+    hadExisting,
+  };
+}
+
+function mergeIntoExisting(
+  agent: AgentName,
+  existing: Record<string, unknown>,
+): { merged: Record<string, unknown>; hadExisting: boolean } {
+  const block = buildConfigBlock(agent) as Record<string, unknown>;
+  if (agent === 'continue') return mergeContinueShape(existing, block);
+  return mergeMcpServersShape(existing, block);
+}
+
+/**
+ * Install context-gatekeeper into a single agent's config file.
+ * Returns a status record the caller can present to the user.
+ */
+export function installAgent(
+  agent: AgentName,
+  options: { scope?: Scope; cwd?: string; force?: boolean } = {},
+): InstallResult {
+  // Claude Desktop has no project-level config; skip with a clear message
+  // instead of silently falling back to the global path (which would
+  // surprise the user when they thought they were writing to the project).
+  if (options.scope === 'project' && agent === 'claude-desktop') {
+    return {
+      agent,
+      configPath: '(project scope not supported)',
+      scope: 'global',
+      status: 'skipped',
+      message: 'Claude Desktop is global-only; omit --local to install',
+    };
+  }
+  const detection = detectAgent(agent, options);
+  try {
+    const existing = readJsonOrEmpty(detection.configPath);
+    const { merged, hadExisting } = mergeIntoExisting(agent, existing);
+    atomicWriteJson(detection.configPath, merged);
+    return {
+      agent,
+      configPath: detection.configPath,
+      scope: detection.scope,
+      status: hadExisting ? 'updated' : 'installed',
+    };
+  } catch (err) {
+    return {
+      agent,
+      configPath: detection.configPath,
+      scope: detection.scope,
+      status: 'error',
+      message: (err as Error).message,
+    };
+  }
+}
+
+/**
+ * Install across multiple agents. If `agents` is empty, installs into all
+ * agents whose config file already exists on disk.
+ */
+export function installAgents(
+  agents: AgentName[],
+  options: { scope?: Scope; cwd?: string } = {},
+): InstallResult[] {
+  const targets: AgentDetection[] =
+    agents.length > 0
+      ? agents.map((a) => detectAgent(a, options))
+      : SUPPORTED_AGENTS.map((a) => detectAgent(a, options)).filter((d) => d.exists);
+  return targets.map((d) => installAgent(d.agent, options));
+}

package/dist/scripts/cli/status.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Print a status table showing which supported agents have a config
+ * file on disk and whether context-gatekeeper is already wired into it.
+ */
+import { AgentDetection } from './detect.ts';
+export declare function renderStatusTable(detections: AgentDetection[]): string;
+export declare function printStatus(detections?: AgentDetection[]): void;
+//# sourceMappingURL=status.d.ts.map

package/dist/scripts/cli/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["status.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAa,cAAc,EAA+B,MAAM,aAAa,CAAC;AAIrF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,cAAc,EAAE,GAAG,MAAM,CAqBtE;AAOD,wBAAgB,WAAW,CAAC,UAAU,GAAE,cAAc,EAAgB,GAAG,IAAI,CAU5E"}

package/dist/scripts/cli/status.js

@@ -0,0 +1,39 @@
+/**
+ * Print a status table showing which supported agents have a config
+ * file on disk and whether context-gatekeeper is already wired into it.
+ */
+import { detectAll, SUPPORTED_AGENTS } from './detect.ts';
+const PAD = (s, n) => String(s).padEnd(n);
+export function renderStatusTable(detections) {
+    const headers = ['Agent', 'Scope', 'Config Path', 'Status'];
+    const rows = detections.map((d) => [
+        d.agent,
+        d.scope,
+        d.configPath,
+        describe(d),
+    ]);
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => String(r[i]).length)));
+    const sep = widths.map((w) => '-'.repeat(w)).join('  ');
+    const out = [];
+    out.push(headers.map((h, i) => PAD(h, widths[i])).join('  '));
+    out.push(sep);
+    for (const r of rows) {
+        out.push(r.map((cell, i) => PAD(cell, widths[i])).join('  '));
+    }
+    return out.join('\n');
+}
+function describe(d) {
+    if (!d.exists)
+        return 'not detected';
+    return d.installed ? 'installed' : 'available';
+}
+export function printStatus(detections = detectAll()) {
+    // Sort for predictable output: known agent order.
+    const order = new Map(SUPPORTED_AGENTS.map((a, i) => [a, i]));
+    const sorted = [...detections].sort((a, b) => (order.get(a.agent) ?? 99) - (order.get(b.agent) ?? 99));
+    console.log(renderStatusTable(sorted));
+    const installed = sorted.filter((d) => d.installed).length;
+    const available = sorted.filter((d) => d.exists && !d.installed).length;
+    console.log(`\n${installed} installed, ${available} available, ${sorted.length - installed - available} not detected`);
+}
+//# sourceMappingURL=status.js.map