@indigoai-us/hq-cli 5.101.7 → 5.103.0

package/dist/commands/integrations-core.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Shared primitives for the `hq integrations` command group.
+ *
+ * Split out of `integrations.ts` when the group grew past "use a connected
+ * app" into the full lifecycle (browse → connect → govern → disconnect). Every
+ * verb module imports its error taxonomy, HTTP guards, and connection
+ * resolution from here, so the classification rules that decide what reaches
+ * Sentry live in exactly one place. `integrations.ts` re-exports this module's
+ * public surface, so existing importers keep working unchanged.
+ */
+/** Write policy on a connection — mirrors hq-pro's `WritePolicy`. */
+export type WritePolicy = "auto-allow" | "confirm" | "deny";
+/** Who a grant points at — mirrors hq-pro's `AclGranteeType`. */
+export type GranteeType = "person" | "group" | "email" | "company-wide";
+/** Grant strength — mirrors hq-pro's `AclPermission`. */
+export type Permission = "read" | "write" | "admin";
+export interface WriteAllowlistEntry {
+    granteeType: GranteeType;
+    granteeId: string;
+    permission: Permission;
+    grantedBy?: string;
+    grantedAt?: string;
+}
+export interface WriteAllowlistGrant {
+    toolName: string;
+    entries: WriteAllowlistEntry[];
+    updatedAt?: string;
+}
+/**
+ * The factory installation joined onto a connection. `id` is the handle
+ * `hq integrations disconnect` needs — hq-pro's uninstall route keys on the
+ * INSTALLATION id, not the connection id.
+ */
+export interface FactoryInstallation {
+    id: string;
+    displayName?: string;
+    domain?: string;
+    status?: string;
+    surface?: {
+        kind?: string;
+        name?: string;
+        url?: string;
+        authStatus?: string;
+        docs?: string;
+    };
+    trust?: {
+        lifecycleState?: string;
+        trustClaim?: string;
+        lastVerifiedAt?: string;
+    };
+    installedAt?: string;
+}
+/**
+ * One row of `GET /v1/integrations/admin`. Every field past `status` is
+ * optional on purpose: hq-pro redacts grant identities for non-managers and
+ * older deploys omit the newer access/installation joins entirely, so a
+ * missing field means UNKNOWN and must never be rendered as a value.
+ */
+export interface AdminConnection {
+    id: string;
+    provider: string;
+    status: string;
+    scopes?: string[];
+    createdBy?: string;
+    createdByName?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
+    writePolicy?: WritePolicy;
+    writePolicyUpdatedAt?: string | null;
+    writeAllowlist?: WriteAllowlistGrant[];
+    access?: {
+        mode?: string;
+        grantCount?: number;
+    };
+    installation?: FactoryInstallation | null;
+}
+export interface AdminAuditEvent {
+    timestamp: string;
+    memberOrAgent: string;
+    memberOrAgentName?: string;
+    toolName: string;
+    outcome: string;
+    connectionId?: string;
+    provider?: string;
+    reason?: string;
+    queueId?: string;
+}
+export interface AdminSurface {
+    companyUid: string;
+    factoryEnabled?: boolean;
+    viewer: {
+        personUid: string;
+        role: string;
+        canManageGovernance: boolean;
+        canManageIntegrations?: boolean;
+    };
+    connections: AdminConnection[];
+    audit: AdminAuditEvent[];
+}
+interface GatewayMessage {
+    result?: unknown;
+    error?: {
+        code?: number;
+        message?: string;
+    };
+}
+export declare class IntegrationsCliError extends Error {
+    /**
+     * True when the error is the caller's request/state/permission (a client 4xx
+     * or a local input/usage error) rather than an hq-cli defect. Expected errors
+     * are printed to the user but skipped for Sentry capture (HQ-CLI-6). Defaults
+     * to false so an unclassified error still reaches Sentry.
+     */
+    readonly expected: boolean;
+    /**
+     * hq-pro's machine code for the failure (e.g. `INTEGRATION_FACTORY_
+     * OAUTH_REQUIRED`), when the response carried one. Branch on THIS, never on
+     * the human message — the copy is free to change, the code is the contract.
+     */
+    readonly code?: string;
+    /** HTTP status the failure came back with, when it came from a response. */
+    readonly status?: number;
+    constructor(message: string, opts?: {
+        expected?: boolean;
+        code?: string;
+        status?: number;
+    });
+}
+/**
+ * A client 4xx is the caller's request/state/permission (bad params, stale
+ * queueId, a non-owner approving) — expected and user-facing, not a bug. A 5xx
+ * (or a 2xx protocol violation) is a genuine server/unknown fault worth a Sentry
+ * crash report.
+ */
+export declare function isClientError(status: number): boolean;
+/**
+ * Statuses that mean HQ's integration gateway (or the third-party provider
+ * behind it) could not serve this request right now — an UPSTREAM AVAILABILITY
+ * event, not an hq-cli defect and not something the caller did wrong.
+ *
+ * HQ-CLI-F: the 500/503s in Sentry correlate request-for-request with the
+ * hq-pro `IntegrationMcpFunction` Lambda hitting its 30s timeout while waiting
+ * on a provider (CloudWatch `integration_mcp_audit event=provider_error`, and
+ * the same spikes counted in the AWS/Lambda `Errors` metric). The event is
+ * already recorded first-party, in the project that owns the fix; mirroring it
+ * into hq-cli's tracker is duplicate, unactionable noise. 429 is included
+ * because a rate-limited call is the same "retry in a moment" outcome (it was
+ * already `expected` via `isClientError`; only its wording changes here).
+ */
+export declare function isUpstreamUnavailable(status: number): boolean;
+/** Actionable wording for an upstream-availability status. */
+export declare function upstreamUnavailableMessage(status: number): string;
+/**
+ * Shared non-2xx guard for every integration-gateway call site. Raises the
+ * expected, actionable upstream-availability error when the status says the
+ * service is down or throttling; returns otherwise so the caller keeps its own
+ * status-specific message and `expected` classification unchanged.
+ */
+export declare function raiseIfUpstreamUnavailable(res: Response): void;
+export declare function raiseIfUnauthorized(res: Response): void;
+/**
+ * Single non-2xx funnel for the REST (non-JSON-RPC) integration routes. Applies
+ * the auth and upstream-availability guards in order, then raises the server's
+ * own `error` text — or `fallback` when the body carried none — with the right
+ * `expected` classification. Every factory/admin call site goes through this so
+ * one route cannot quietly drift into reporting its 4xx as crashes.
+ */
+export declare function raiseForResponse(res: Response, fallback: string): Promise<never>;
+/** "factory:linear" → "linear"; mirrors hq-pro's factoryToolPrefix. */
+export declare function toolPrefixForProvider(provider: string): string;
+/** "factory:linear" → "linear", for display and for `--provider` echoes. */
+export declare function bareProvider(provider: string): string;
+/**
+ * Read the whole admin surface: connections with their governance state, the
+ * viewer's role, and the recent audit feed. Several verbs need more than the
+ * connection list, so this is the primitive and `fetchConnections` is the thin
+ * projection over it.
+ */
+export declare function fetchAdminSurface(token: string, companyUid: string): Promise<AdminSurface>;
+export declare function fetchConnections(token: string, companyUid: string): Promise<AdminConnection[]>;
+/**
+ * Resolve one connection by `--connection acct_…` or `--provider linear`
+ * (matches `factory:<slug>` and bare provider ids, case-insensitive). Errors
+ * list what IS connected so the fix is one command away.
+ */
+export declare function selectConnection(connections: AdminConnection[], opts: {
+    connection?: string;
+    provider?: string;
+}): AdminConnection;
+/**
+ * Resolve a connection the caller named positionally OR through the
+ * `--provider` / `--connection` flags. Every management verb takes an optional
+ * `<app>` argument for ergonomics (`hq integrations policy linear …`), which is
+ * matched exactly like `--provider` unless it looks like a connection id.
+ */
+export declare function resolveConnection(token: string, companyUid: string, app: string | undefined, opts: {
+    provider?: string;
+    connection?: string;
+}): Promise<AdminConnection>;
+export declare function callGateway(token: string, params: Record<string, unknown>): Promise<GatewayMessage>;
+/**
+ * Gateway results arrive MCP-style: `{ content: [{ type: "text", text }] }`
+ * where `text` is the provider's JSON. Unwrap to the inner payload; fall back
+ * to the raw result when the shape differs.
+ */
+export declare function unwrapGatewayResult(result: unknown): unknown;
+interface QueuedOutcome {
+    queuedForApproval: true;
+    queueId: string;
+    connectionId: string;
+    expiresAt?: string;
+}
+export declare function queuedOutcome(payload: unknown): QueuedOutcome | null;
+export declare function printJson(value: unknown): void;
+export {};
+//# sourceMappingURL=integrations-core.d.ts.map

package/dist/commands/integrations-core.js

@@ -0,0 +1,320 @@
+/**
+ * Shared primitives for the `hq integrations` command group.
+ *
+ * Split out of `integrations.ts` when the group grew past "use a connected
+ * app" into the full lifecycle (browse → connect → govern → disconnect). Every
+ * verb module imports its error taxonomy, HTTP guards, and connection
+ * resolution from here, so the classification rules that decide what reaches
+ * Sentry live in exactly one place. `integrations.ts` re-exports this module's
+ * public surface, so existing importers keep working unchanged.
+ */
+import { randomUUID } from "node:crypto";
+import { vaultApiFetch } from "../utils/vault-api.js";
+import { AuthError } from "../utils/auth-error.js";
+import { redactErrorText } from "../utils/redact-error-text.js";
+export class IntegrationsCliError extends Error {
+    /**
+     * True when the error is the caller's request/state/permission (a client 4xx
+     * or a local input/usage error) rather than an hq-cli defect. Expected errors
+     * are printed to the user but skipped for Sentry capture (HQ-CLI-6). Defaults
+     * to false so an unclassified error still reaches Sentry.
+     */
+    expected;
+    /**
+     * hq-pro's machine code for the failure (e.g. `INTEGRATION_FACTORY_
+     * OAUTH_REQUIRED`), when the response carried one. Branch on THIS, never on
+     * the human message — the copy is free to change, the code is the contract.
+     */
+    code;
+    /** HTTP status the failure came back with, when it came from a response. */
+    status;
+    constructor(message, opts = {}) {
+        super(message);
+        this.name = "IntegrationsCliError";
+        this.expected = opts.expected ?? false;
+        if (opts.code)
+            this.code = opts.code;
+        if (opts.status !== undefined)
+            this.status = opts.status;
+    }
+}
+/**
+ * A client 4xx is the caller's request/state/permission (bad params, stale
+ * queueId, a non-owner approving) — expected and user-facing, not a bug. A 5xx
+ * (or a 2xx protocol violation) is a genuine server/unknown fault worth a Sentry
+ * crash report.
+ */
+export function isClientError(status) {
+    return status >= 400 && status < 500;
+}
+/**
+ * Statuses that mean HQ's integration gateway (or the third-party provider
+ * behind it) could not serve this request right now — an UPSTREAM AVAILABILITY
+ * event, not an hq-cli defect and not something the caller did wrong.
+ *
+ * HQ-CLI-F: the 500/503s in Sentry correlate request-for-request with the
+ * hq-pro `IntegrationMcpFunction` Lambda hitting its 30s timeout while waiting
+ * on a provider (CloudWatch `integration_mcp_audit event=provider_error`, and
+ * the same spikes counted in the AWS/Lambda `Errors` metric). The event is
+ * already recorded first-party, in the project that owns the fix; mirroring it
+ * into hq-cli's tracker is duplicate, unactionable noise. 429 is included
+ * because a rate-limited call is the same "retry in a moment" outcome (it was
+ * already `expected` via `isClientError`; only its wording changes here).
+ */
+export function isUpstreamUnavailable(status) {
+    return status === 429 || status === 500 || status === 502 || status === 503 || status === 504;
+}
+/** Actionable wording for an upstream-availability status. */
+export function upstreamUnavailableMessage(status) {
+    return status === 429
+        ? `HQ's integration gateway is rate-limiting this request (HTTP 429). Wait a moment and retry.`
+        : `HQ's integration gateway is temporarily unavailable (HTTP ${status}). ` +
+            `This is a service-side hiccup, not a problem with your command — retry in a moment.`;
+}
+/**
+ * Shared non-2xx guard for every integration-gateway call site. Raises the
+ * expected, actionable upstream-availability error when the status says the
+ * service is down or throttling; returns otherwise so the caller keeps its own
+ * status-specific message and `expected` classification unchanged.
+ */
+export function raiseIfUpstreamUnavailable(res) {
+    if (isUpstreamUnavailable(res.status)) {
+        throw new IntegrationsCliError(upstreamUnavailableMessage(res.status), {
+            expected: true,
+        });
+    }
+}
+// The integration gateway answers `POST /v1/integrations/mcp` JSON-RPC-style: a
+// transport failure is a non-2xx HTTP status, but a GOVERNED refusal arrives as
+// HTTP 200 carrying a JSON-RPC `error` object (mirrors hq-pro's
+// integration-mcp/server.ts error mapping). These caller-side codes are the
+// JSON-RPC analog of a client 4xx — the caller's request/state/permission,
+// expected and actionable, not an hq-cli defect — so they are printed to the
+// user and skipped for Sentry capture (HQ-CLI-B):
+//   -32003 UNAUTHORIZED   — connection-level access denial, e.g. the
+//                           "You do not have access to this integration. Ask its
+//                           owner to share it with you." (IntegrationAccessDenied)
+//                           that flooded Sentry, plus ConnectionNotFound / a
+//                           read-only share rejecting a write.
+//   -32602 INVALID_PARAMS — an unknown tool or unsupported provider for the
+//                           connection (a bad request the caller can correct).
+//   -32050 PROVIDER_ERROR  — a THIRD-PARTY provider fault, surfaced verbatim.
+//                           hq-pro mints this code for EVERY provider fault
+//                           and for nothing else: `integration-mcp/server.ts`
+//                           maps an `IntegrationMcpError` with status
+//                           'provider_error' to -32050, raised by
+//                           `integration-mcp/dispatch.ts` for ProviderTimeout,
+//                           ProviderRateLimited, ProviderParseError,
+//                           ProviderWriteUnknown and TokenRefreshFailed.
+//                           NOTE the remote server's OWN JSON-RPC code is
+//                           embedded in the message TEXT ("Remote MCP request
+//                           failed (-32602): …"); the wire code hq-cli sees is
+//                           always -32050, so the codes above never match it.
+//                           Every occurrence is already recorded first-party
+//                           in hq-pro — `integration_mcp_audit
+//                           event=provider_error` with reason/provider/tool,
+//                           an `integration_mcp_health_signal` metric, and
+//                           hq-pro's own Sentry project — so hq-cli reporting
+//                           it again is duplicate noise in the wrong tracker,
+//                           filed against a codebase that cannot fix it
+//                           (HQ-CLI-F). Should hq-pro ever reuse -32050 for
+//                           an hq-pro-side fault, the mapping site named above
+//                           is where that change is traceable; -32603 below
+//                           remains the code for hq-pro's own faults.
+// Everything else stays unexpected so a genuine fault still reaches Sentry:
+// INTERNAL_ERROR (-32603), CONFLICT (-32009, which the gateway also raises for
+// a confirm queue being unavailable or an owner notification failing — real
+// backend faults worth a report), METHOD_NOT_FOUND / PARSE_ERROR, and any
+// absent or unrecognized code.
+const EXPECTED_GATEWAY_ERROR_CODES = new Set([-32003, -32602, -32050]);
+function isExpectedGatewayError(code) {
+    return code != null && EXPECTED_GATEWAY_ERROR_CODES.has(code);
+}
+// A 401 from ANY integration-gateway vault call means the caller's HQ session
+// is expired or missing — an expected auth state fixed by `hq login`, not an
+// hq-cli defect. Raise the same typed AuthError the vault company-resolution
+// paths use (HQ-CLI-8) so the top-level handler prints one actionable message
+// and skips Sentry, instead of surfacing the opaque, unactionable
+// "Integration gateway request failed (HTTP 401)" that shipped as a fatal from
+// `callGateway` (HQ-CLI-9). Non-401 statuses keep their existing behavior:
+// other 4xx stay expected client errors, 5xx still report.
+export function raiseIfUnauthorized(res) {
+    if (res.status === 401)
+        throw new AuthError();
+}
+/**
+ * Single non-2xx funnel for the REST (non-JSON-RPC) integration routes. Applies
+ * the auth and upstream-availability guards in order, then raises the server's
+ * own `error` text — or `fallback` when the body carried none — with the right
+ * `expected` classification. Every factory/admin call site goes through this so
+ * one route cannot quietly drift into reporting its 4xx as crashes.
+ */
+export async function raiseForResponse(res, fallback) {
+    raiseIfUnauthorized(res);
+    raiseIfUpstreamUnavailable(res);
+    const body = (await res.json().catch(() => ({})));
+    // hq-pro mints this error text, so it is untrusted input to a message we
+    // print verbatim — scrub credentials out before it can reach a terminal or a
+    // Sentry crash report (same reasoning as the gateway path below).
+    const detail = redactErrorText(body.error ?? "");
+    throw new IntegrationsCliError(detail || `${fallback} (HTTP ${res.status})`, {
+        expected: isClientError(res.status),
+        status: res.status,
+        ...(body.code ? { code: body.code } : {}),
+    });
+}
+/** "factory:linear" → "linear"; mirrors hq-pro's factoryToolPrefix. */
+export function toolPrefixForProvider(provider) {
+    return provider
+        .replace(/^factory:/, "")
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, ".");
+}
+/** "factory:linear" → "linear", for display and for `--provider` echoes. */
+export function bareProvider(provider) {
+    return provider.replace(/^factory:/, "");
+}
+/**
+ * Read the whole admin surface: connections with their governance state, the
+ * viewer's role, and the recent audit feed. Several verbs need more than the
+ * connection list, so this is the primitive and `fetchConnections` is the thin
+ * projection over it.
+ */
+export async function fetchAdminSurface(token, companyUid) {
+    const res = await vaultApiFetch({
+        token,
+        path: "/v1/integrations/admin",
+        query: { companyUid },
+    });
+    if (!res.ok)
+        await raiseForResponse(res, "Failed to list integrations");
+    const data = (await res.json());
+    return {
+        companyUid: data.companyUid ?? companyUid,
+        ...(data.factoryEnabled !== undefined ? { factoryEnabled: data.factoryEnabled } : {}),
+        viewer: data.viewer ?? {
+            personUid: "",
+            role: "member",
+            canManageGovernance: false,
+        },
+        connections: data.connections ?? [],
+        audit: data.audit ?? [],
+    };
+}
+export async function fetchConnections(token, companyUid) {
+    return (await fetchAdminSurface(token, companyUid)).connections;
+}
+/**
+ * Resolve one connection by `--connection acct_…` or `--provider linear`
+ * (matches `factory:<slug>` and bare provider ids, case-insensitive). Errors
+ * list what IS connected so the fix is one command away.
+ */
+export function selectConnection(connections, opts) {
+    const active = connections.filter((c) => c.status !== "revoked");
+    if (opts.connection) {
+        const match = connections.find((c) => c.id === opts.connection);
+        if (!match) {
+            throw new IntegrationsCliError(`No connection '${opts.connection}'. Run \`hq integrations list\` to see connected apps.`, { expected: true });
+        }
+        return match;
+    }
+    if (opts.provider) {
+        const want = opts.provider.trim().toLowerCase();
+        const match = active.find((c) => {
+            const bare = bareProvider(c.provider).toLowerCase();
+            return bare === want || c.provider.toLowerCase() === want;
+        });
+        if (!match) {
+            const available = active.map((c) => bareProvider(c.provider)).join(", ");
+            throw new IntegrationsCliError(`No connected app matches '${opts.provider}'.` +
+                (available ? ` Connected: ${available}.` : " Nothing is connected yet — connect apps with `hq integrations connect <app>`."), { expected: true });
+        }
+        return match;
+    }
+    if (active.length === 1)
+        return active[0];
+    if (active.length === 0) {
+        throw new IntegrationsCliError("No connected apps yet. Connect one with `hq integrations connect <app>`, then retry.", { expected: true });
+    }
+    throw new IntegrationsCliError(`Multiple apps are connected — pick one with --provider:\n` +
+        active.map((c) => `  --provider ${bareProvider(c.provider)}`).join("\n"), { expected: true });
+}
+/**
+ * Resolve a connection the caller named positionally OR through the
+ * `--provider` / `--connection` flags. Every management verb takes an optional
+ * `<app>` argument for ergonomics (`hq integrations policy linear …`), which is
+ * matched exactly like `--provider` unless it looks like a connection id.
+ */
+export async function resolveConnection(token, companyUid, app, opts) {
+    const connections = await fetchConnections(token, companyUid);
+    if (app && !opts.provider && !opts.connection) {
+        return selectConnection(connections, app.startsWith("acct_") ? { connection: app } : { provider: app });
+    }
+    return selectConnection(connections, opts);
+}
+export async function callGateway(token, params) {
+    const res = await vaultApiFetch({
+        token,
+        path: "/v1/integrations/mcp",
+        method: "POST",
+        body: {
+            jsonrpc: "2.0",
+            id: `hq-cli-${randomUUID()}`,
+            method: "tools/call",
+            params,
+        },
+    });
+    const message = (await res.json().catch(() => null));
+    if (!res.ok || !message) {
+        raiseIfUnauthorized(res);
+        raiseIfUpstreamUnavailable(res);
+        throw new IntegrationsCliError(`Integration gateway request failed (HTTP ${res.status}).`, { expected: isClientError(res.status) });
+    }
+    if (message.error) {
+        // The gateway's error text is minted UPSTREAM (hq-pro, the integration
+        // factory, and beyond it the third-party provider), so it is untrusted:
+        // scrub credentials and bound the length here, at the throw site, because
+        // an `expected` error is printed straight from `err.message` by the
+        // top-level handler and never passes through `unexpectedCliErrorMessage`.
+        // The chain is idempotent, so the unexpected path scrubbing again is a
+        // no-op. This preserves PR #298's user-visible diagnostic; it only makes
+        // it safe on the newly-expected path.
+        throw new IntegrationsCliError(redactErrorText(message.error.message ?? "") ||
+            "Integration gateway returned an error.", { expected: isExpectedGatewayError(message.error.code) });
+    }
+    return message;
+}
+/**
+ * Gateway results arrive MCP-style: `{ content: [{ type: "text", text }] }`
+ * where `text` is the provider's JSON. Unwrap to the inner payload; fall back
+ * to the raw result when the shape differs.
+ */
+export function unwrapGatewayResult(result) {
+    if (result && typeof result === "object" && Array.isArray(result.content)) {
+        const content = result.content;
+        const text = content.find((c) => c.type === "text")?.text;
+        if (typeof text === "string") {
+            try {
+                return JSON.parse(text);
+            }
+            catch {
+                return text;
+            }
+        }
+    }
+    return result;
+}
+export function queuedOutcome(payload) {
+    if (payload &&
+        typeof payload === "object" &&
+        payload.queuedForApproval === true &&
+        typeof payload.queueId === "string") {
+        return payload;
+    }
+    return null;
+}
+export function printJson(value) {
+    console.log(JSON.stringify(value, null, 2));
+}
+//# sourceMappingURL=integrations-core.js.map

package/dist/commands/integrations-manage.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `hq integrations show | policy | grants | grant | ungrant | access | share |
+ * unshare | audit | pending | disconnect`.
+ *
+ * The govern-and-remove half of the lifecycle. Two different permission
+ * surfaces live here and are easy to confuse, so they get separate verbs:
+ *
+ *   ACCESS  (`access` / `share` / `unshare`) — who inside the company may use
+ *           the connection at all. Managed by the connection's creator or a
+ *           company admin.
+ *   GRANTS  (`grants` / `grant` / `ungrant`) — which of those people may call
+ *           a specific WRITE tool without an approval round trip. Owner-only,
+ *           and layered under the connection's write policy.
+ */
+import { Command } from "commander";
+import { type GranteeType, type Permission, type WriteAllowlistGrant } from "./integrations-core.js";
+interface Principal {
+    granteeType: GranteeType;
+    granteeId?: string;
+}
+/**
+ * Parse a grantee from the one string a person would actually type.
+ *
+ * Accepts an explicit `person:`/`group:`/`email:` prefix, the word `everyone`,
+ * a bare email address, or a bare uid. Refuses anything ambiguous rather than
+ * guessing — a misparsed principal silently grants access to the wrong party.
+ */
+export declare function parsePrincipal(raw: string): Principal;
+export declare function registerManageCommands(integrations: Command): void;
+/** Order-insensitive identity of an allowlist, for change detection. */
+export declare function allowlistFingerprint(grants: WriteAllowlistGrant[]): string;
+/**
+ * Add (or upgrade) one grantee's permission on one tool, returning the FULL
+ * allowlist to send back. Exported for tests: the merge is the part that would
+ * silently destroy other people's grants if it drifted.
+ */
+export declare function mergeGrant(current: WriteAllowlistGrant[], toolName: string, entry: {
+    granteeType: GranteeType;
+    granteeId: string;
+    permission: Permission;
+}): WriteAllowlistGrant[];
+/**
+ * Remove one grantee from one tool, returning the FULL allowlist to send back,
+ * or `null` when the grant was not there (so the caller can say "nothing to
+ * remove" instead of issuing a no-op write). A tool left with no entries is
+ * dropped entirely rather than persisted as an empty rule.
+ */
+export declare function removeGrant(current: WriteAllowlistGrant[], toolName: string, principal: Principal): WriteAllowlistGrant[] | null;
+export {};
+//# sourceMappingURL=integrations-manage.d.ts.map