@pennant/mcp 1.0.0

package/README.md

@@ -0,0 +1,78 @@
+# @pennant/mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for [Pennant](https://flypennant.com). It lets an AI assistant read your flags, explain why a flag is on or off for a user, change flags, and add a Pennant SDK to a codebase.
+
+The server signs in to your console as a Pennant user, so that user's role, project access, and production approvals apply to everything the assistant does.
+
+## Set up
+
+Create a Pennant user for the assistant. Give it the **viewer** role to start, or **editor** if it should change flags. Then add the server to your client.
+
+### Claude Code
+
+```bash
+claude mcp add pennant \
+  -e PENNANT_URL=https://flags.example.com \
+  -e PENNANT_EMAIL=assistant@example.com \
+  -e PENNANT_PASSWORD=... \
+  -- npx -y @pennant/mcp
+```
+
+### Claude Desktop, Cursor, VS Code, and other clients
+
+```json
+{
+  "mcpServers": {
+    "pennant": {
+      "command": "npx",
+      "args": ["-y", "@pennant/mcp"],
+      "env": {
+        "PENNANT_URL": "https://flags.example.com",
+        "PENNANT_EMAIL": "assistant@example.com",
+        "PENNANT_PASSWORD": "..."
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Variable             | Required | Meaning                                                                                 |
+| -------------------- | -------- | --------------------------------------------------------------------------------------- |
+| `PENNANT_URL`        | yes      | Public URL of your Pennant console.                                                     |
+| `PENNANT_EMAIL`      | yes      | Pennant user the server signs in as.                                                    |
+| `PENNANT_PASSWORD`   | yes      | That user's password. Single sign-on accounts need a local password for the server.     |
+| `PENNANT_PROJECT`    | no       | Project used when a tool does not name one. Defaults to `default`.                      |
+| `PENNANT_CLIENT_KEY` | no       | Project client key. Lets `explain_flag` confirm results, including percentage rollouts. |
+| `PENNANT_READ_ONLY`  | no       | Set to `1` to leave out every tool that changes flags.                                  |
+
+## Tools
+
+| Tool                | What it does                                                                               |
+| ------------------- | ------------------------------------------------------------------------------------------ |
+| `list_projects`     | Projects the user can open.                                                                |
+| `list_environments` | A project's environments.                                                                  |
+| `list_flags`        | Flags with type, tags, parent, and on/off per environment. Filter by tag.                  |
+| `get_flag`          | One flag's full configuration.                                                             |
+| `list_segments`     | Saved audiences and their constraints.                                                     |
+| `explain_flag`      | Why a flag is on or off for a user, step by step, in the order the server checks.          |
+| `detect_stack`      | Reads `package.json`, `pyproject.toml`, `go.mod`, or `Cargo.toml` and picks the right SDK. |
+| `sdk_setup`         | Install command, environment variables, and a first flag check, pointed at your console.   |
+| `create_flag`       | Creates a flag. It starts off in every environment.                                        |
+| `set_flag_enabled`  | Switches a flag on or off in one environment.                                              |
+| `update_targeting`  | Changes strategy, constraints, variants, or segments in one environment.                   |
+| `archive_flag`      | Archives or restores a flag.                                                               |
+
+When a project requires approval for production, `set_flag_enabled` and `update_targeting` open a change request instead of applying the change. An admin approves it in the console.
+
+## Try it
+
+- "Add Pennant to this app and put the new search page behind a flag called `new-search`."
+- "Why is `checkout-v2` off for user `u-123` in production?"
+- "Roll `new-search` out to 10% of users in development."
+- "Which flags tagged `checkout` are still off in production?"
+
+## Skills
+
+The [`skills/`](../skills) folder has agent skills that pair with this server: adding the SDK, wrapping a feature in a flag, and cleaning up a flag after rollout.

package/dist/config.d.ts

@@ -0,0 +1,16 @@
+type McpConfig = {
+    /** Public URL of the Pennant console, such as https://flags.example.com. */
+    url: string;
+    email: string;
+    password: string;
+    /** Project used when a tool call does not name one. */
+    project: string;
+    /** Optional project client key. Lets explain_flag confirm results against the live evaluate API. */
+    clientKey?: string;
+    /** When true, tools that change flags are not registered. */
+    readOnly: boolean;
+};
+type Env = Record<string, string | undefined>;
+declare function readConfig(env?: Env): McpConfig | string;
+export { readConfig };
+export type { McpConfig };

package/dist/config.js

@@ -0,0 +1,29 @@
+function readConfig(env = process.env) {
+    const url = env.PENNANT_URL?.trim();
+    const email = env.PENNANT_EMAIL?.trim();
+    const password = env.PENNANT_PASSWORD;
+    const missing = [
+        url ? null : "PENNANT_URL",
+        email ? null : "PENNANT_EMAIL",
+        password ? null : "PENNANT_PASSWORD",
+    ].filter(Boolean);
+    if (missing.length > 0)
+        return `Set ${missing.join(", ")} for the Pennant MCP server.`;
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return "PENNANT_URL must be a full URL, such as https://flags.example.com.";
+    }
+    return {
+        url: parsed.origin,
+        email: email,
+        password: password,
+        project: env.PENNANT_PROJECT?.trim() || "default",
+        clientKey: env.PENNANT_CLIENT_KEY?.trim() || undefined,
+        readOnly: env.PENNANT_READ_ONLY === "1" || env.PENNANT_READ_ONLY === "true",
+    };
+}
+export { readConfig };
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAeA,SAAS,UAAU,CAAC,MAAW,OAAO,CAAC,GAAG;IACxC,MAAM,GAAG,GAAG,GAAG,CAAC,WAAW,EAAE,IAAI,EAAE,CAAA;IACnC,MAAM,KAAK,GAAG,GAAG,CAAC,aAAa,EAAE,IAAI,EAAE,CAAA;IACvC,MAAM,QAAQ,GAAG,GAAG,CAAC,gBAAgB,CAAA;IACrC,MAAM,OAAO,GAAG;QACd,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa;QAC1B,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,eAAe;QAC9B,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,kBAAkB;KACrC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IACjB,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,OAAO,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,8BAA8B,CAAA;IAEtF,IAAI,MAAW,CAAA;IACf,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,GAAI,CAAC,CAAA;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,oEAAoE,CAAA;IAC7E,CAAC;IAED,OAAO;QACL,GAAG,EAAE,MAAM,CAAC,MAAM;QAClB,KAAK,EAAE,KAAM;QACb,QAAQ,EAAE,QAAS;QACnB,OAAO,EAAE,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,IAAI,SAAS;QACjD,SAAS,EAAE,GAAG,CAAC,kBAAkB,EAAE,IAAI,EAAE,IAAI,SAAS;QACtD,QAAQ,EAAE,GAAG,CAAC,iBAAiB,KAAK,GAAG,IAAI,GAAG,CAAC,iBAAiB,KAAK,MAAM;KAC5E,CAAA;AACH,CAAC;AAED,OAAO,EAAE,UAAU,EAAE,CAAA"}

package/dist/console-client.d.ts

@@ -0,0 +1,55 @@
+import type { EnvironmentConfig, EvaluationContext, Flag, FlagResult, FlagType, ProjectSummary, Segment, Strategy } from "./types.ts";
+type ClientOptions = {
+    url: string;
+    email: string;
+    password: string;
+    clientKey?: string;
+    fetch?: typeof fetch;
+};
+type ChangeRequest = {
+    id: string;
+    flagKey: string;
+    environment: string;
+    status: string;
+};
+type ToggleResult = {
+    mode: "direct";
+    flag: Flag;
+} | {
+    mode: "change-request";
+    changeRequest: ChangeRequest;
+    flag: Flag;
+};
+declare class ConsoleError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+/**
+ * Talks to the Pennant console as a signed-in user, so roles, project membership,
+ * and production approvals apply exactly as they do in the browser.
+ */
+declare function createConsoleClient(options: ClientOptions): {
+    hasClientKey: boolean;
+    evaluate: (environment: string, context: EvaluationContext, project?: string) => Promise<Record<string, FlagResult> | null>;
+    listProjects(): Promise<ProjectSummary[]>;
+    listEnvironments(project: string): Promise<string[]>;
+    listFlags(project: string, includeArchived?: boolean): Promise<Flag[]>;
+    getFlag(project: string, key: string): Promise<Flag>;
+    listSegments(project: string): Promise<Segment[]>;
+    createFlag(project: string, input: {
+        key: string;
+        name: string;
+        description?: string;
+        type?: FlagType;
+        strategy?: Strategy;
+    }): Promise<Flag>;
+    updateFlag(project: string, key: string, patch: Record<string, unknown>): Promise<Flag>;
+    setEnabled(project: string, key: string, environment: string, enabled: boolean): Promise<ToggleResult>;
+    approvalRequired(project: string): Promise<boolean>;
+    proposeProductionChange(project: string, flagKey: string, proposed: EnvironmentConfig): Promise<{
+        changeRequest: ChangeRequest;
+    }>;
+};
+type ConsoleClient = ReturnType<typeof createConsoleClient>;
+export { ConsoleError, createConsoleClient };
+export type { ChangeRequest, ConsoleClient, ToggleResult };

package/dist/console-client.js

@@ -0,0 +1,128 @@
+class ConsoleError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * Talks to the Pennant console as a signed-in user, so roles, project membership,
+ * and production approvals apply exactly as they do in the browser.
+ */
+function createConsoleClient(options) {
+    const fetchImpl = options.fetch ?? fetch;
+    let cookie = null;
+    async function signIn() {
+        const response = await fetchImpl(`${options.url}/api/auth/sign-in`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Origin: options.url },
+            body: JSON.stringify({ email: options.email, password: options.password }),
+        });
+        if (!response.ok) {
+            throw new ConsoleError(response.status, await errorText(response, "Sign-in failed."));
+        }
+        const setCookie = response.headers.get("set-cookie");
+        const session = setCookie?.split(";")[0];
+        if (!session)
+            throw new ConsoleError(500, "Sign-in did not return a session.");
+        cookie = session;
+    }
+    async function request(method, path, project, body) {
+        const url = new URL(`${options.url}${path}`);
+        if (project)
+            url.searchParams.set("project", project);
+        for (let attempt = 0; attempt < 2; attempt++) {
+            if (!cookie)
+                await signIn();
+            const response = await fetchImpl(url, {
+                method,
+                headers: {
+                    Cookie: cookie,
+                    Origin: options.url,
+                    ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+                },
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+            // An expired session gets one fresh sign-in.
+            if (response.status === 401 && attempt === 0) {
+                cookie = null;
+                continue;
+            }
+            if (!response.ok) {
+                throw new ConsoleError(response.status, await errorText(response, `${method} ${path} failed.`));
+            }
+            return (await response.json());
+        }
+        throw new ConsoleError(401, "Sign-in required.");
+    }
+    async function evaluate(environment, context, project) {
+        if (!options.clientKey)
+            return null;
+        const response = await fetchImpl(`${options.url}/api/client/evaluate`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${options.clientKey}`, "Content-Type": "application/json" },
+            body: JSON.stringify({ environment, context, ...(project ? { project } : {}) }),
+        });
+        if (!response.ok) {
+            throw new ConsoleError(response.status, await errorText(response, "Evaluate failed."));
+        }
+        const body = (await response.json());
+        return body.flags ?? {};
+    }
+    return {
+        hasClientKey: Boolean(options.clientKey),
+        evaluate,
+        async listProjects() {
+            return (await request("GET", "/api/admin/projects")).projects;
+        },
+        async listEnvironments(project) {
+            return (await request("GET", "/api/admin/environments", project))
+                .environments;
+        },
+        async listFlags(project, includeArchived = false) {
+            const path = includeArchived ? "/api/admin/flags?archived=1" : "/api/admin/flags";
+            return (await request("GET", path, project)).flags;
+        },
+        async getFlag(project, key) {
+            return (await request("GET", `/api/admin/flags/${encodeURIComponent(key)}`, project)).flag;
+        },
+        async listSegments(project) {
+            return (await request("GET", "/api/admin/segments", project))
+                .segments;
+        },
+        async createFlag(project, input) {
+            return (await request("POST", "/api/admin/flags", project, input)).flag;
+        },
+        async updateFlag(project, key, patch) {
+            return (await request("PATCH", `/api/admin/flags/${encodeURIComponent(key)}`, project, patch)).flag;
+        },
+        async setEnabled(project, key, environment, enabled) {
+            return request("POST", `/api/admin/flags/${encodeURIComponent(key)}/toggle`, project, {
+                environment,
+                enabled,
+            });
+        },
+        async approvalRequired(project) {
+            const body = await request("GET", "/api/admin/change-requests", project);
+            return body.requireApprovalForProduction;
+        },
+        async proposeProductionChange(project, flagKey, proposed) {
+            return request("POST", "/api/admin/change-requests", project, {
+                flagKey,
+                environment: "production",
+                proposed,
+            });
+        },
+    };
+}
+async function errorText(response, fallback) {
+    try {
+        const body = (await response.json());
+        return typeof body.error === "string" ? body.error : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+export { ConsoleError, createConsoleClient };
+//# sourceMappingURL=console-client.js.map

package/dist/console-client.js.map

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

package/dist/explain.d.ts

@@ -0,0 +1,21 @@
+import type { EvaluationContext, Flag, FlagResult, Segment, Strategy } from "./types.ts";
+type Explanation = {
+    /** null when only the server knows, which is a gradual rollout without a live result. */
+    enabled: boolean | null;
+    reason: string;
+    /** Every rule that was checked, in the order the server checks them. */
+    steps: string[];
+};
+declare function describeStrategy(strategy: Strategy): string;
+/**
+ * Explains a flag for one context, in the same order the server evaluates:
+ * archive, environment switch, constraints, segments, parent flag, strategy.
+ * `live` holds evaluate results from the server, when a client key is configured.
+ */
+declare function explainFlag(flag: Flag, environment: string, context: EvaluationContext, lookups: {
+    flags: Map<string, Flag>;
+    segments: Map<string, Segment>;
+    live?: Record<string, FlagResult>;
+}, visiting?: Set<string>): Explanation;
+export { describeStrategy, explainFlag };
+export type { Explanation };

package/dist/explain.js

@@ -0,0 +1,168 @@
+function contextValue(context, name) {
+    if (name === "userId")
+        return context.userId;
+    if (name === "sessionId")
+        return context.sessionId;
+    if (name === "remoteAddress")
+        return context.remoteAddress;
+    if (name === "hostname")
+        return context.hostname;
+    return context.properties?.[name];
+}
+function constraintPasses(constraint, context) {
+    const value = contextValue(context, constraint.contextName);
+    if (constraint.operator === "IN")
+        return value !== undefined && constraint.values.includes(value);
+    return value === undefined || !constraint.values.includes(value);
+}
+function describeConstraint(constraint) {
+    const verb = constraint.operator === "IN" ? "is one of" : "is not one of";
+    return `${constraint.contextName} ${verb} ${constraint.values.join(", ")}`;
+}
+function describeStrategy(strategy) {
+    switch (strategy.type) {
+        case "everyone":
+            return "everyone";
+        case "gradual":
+            return `a ${strategy.percentage}% gradual rollout`;
+        case "allowlist":
+            return `an allowlist of ${strategy.userIds.length} user id${strategy.userIds.length === 1 ? "" : "s"}`;
+        case "remoteAddress":
+            return `an IP allowlist of ${strategy.addresses.length} address${strategy.addresses.length === 1 ? "" : "es"}`;
+        case "hostname":
+            return `a hostname list (${strategy.hostnames.join(", ")})`;
+    }
+}
+/** Decides the strategy where it is knowable without the server's rollout bucket. */
+function strategyResult(strategy, context, live) {
+    switch (strategy.type) {
+        case "everyone":
+            return { on: true, why: "The strategy is everyone." };
+        case "gradual": {
+            if (!context.userId)
+                return { on: false, why: "Gradual rollouts need a userId, and the context has none." };
+            if (strategy.percentage <= 0)
+                return { on: false, why: "The rollout is at 0%." };
+            if (strategy.percentage >= 100)
+                return { on: true, why: "The rollout is at 100%." };
+            if (live) {
+                return {
+                    on: live.enabled,
+                    why: live.enabled
+                        ? `${context.userId} falls inside the ${strategy.percentage}% rollout.`
+                        : `${context.userId} falls outside the ${strategy.percentage}% rollout.`,
+                };
+            }
+            return {
+                on: null,
+                why: `Whether ${context.userId} is inside the ${strategy.percentage}% rollout is decided by the server. Set PENNANT_CLIENT_KEY to check it live.`,
+            };
+        }
+        case "allowlist": {
+            const listed = Boolean(context.userId && strategy.userIds.includes(context.userId));
+            return {
+                on: listed,
+                why: listed
+                    ? `${context.userId} is on the allowlist.`
+                    : "The userId is not on the allowlist.",
+            };
+        }
+        case "remoteAddress": {
+            const listed = Boolean(context.remoteAddress && strategy.addresses.includes(context.remoteAddress));
+            return {
+                on: listed,
+                why: listed
+                    ? "The remoteAddress is allowed."
+                    : "The remoteAddress is not in the allowed list.",
+            };
+        }
+        case "hostname": {
+            const listed = Boolean(context.hostname && strategy.hostnames.includes(context.hostname));
+            return {
+                on: listed,
+                why: listed ? "The hostname is allowed." : "The hostname is not in the allowed list.",
+            };
+        }
+    }
+}
+/**
+ * Explains a flag for one context, in the same order the server evaluates:
+ * archive, environment switch, constraints, segments, parent flag, strategy.
+ * `live` holds evaluate results from the server, when a client key is configured.
+ */
+function explainFlag(flag, environment, context, lookups, visiting = new Set()) {
+    const steps = [];
+    let parentUncertain = false;
+    const off = (reason) => ({
+        enabled: false,
+        reason,
+        steps: [...steps, reason],
+    });
+    if (flag.archived)
+        return off(`${flag.key} is archived, so it is never sent to apps.`);
+    const config = flag.environments[environment];
+    if (!config)
+        return off(`${flag.key} has no settings for the ${environment} environment.`);
+    if (!config.enabled)
+        return off(`${flag.key} is switched off in ${environment}.`);
+    steps.push(`${flag.key} is switched on in ${environment}.`);
+    for (const constraint of config.constraints ?? []) {
+        if (!constraintPasses(constraint, context)) {
+            return off(`The constraint "${describeConstraint(constraint)}" does not match this context.`);
+        }
+        steps.push(`Constraint "${describeConstraint(constraint)}" matches.`);
+    }
+    for (const id of config.segmentIds ?? []) {
+        const segment = lookups.segments.get(id);
+        if (!segment)
+            return off(`Segment ${id} no longer exists, so the flag stays off.`);
+        const failed = segment.constraints.find((constraint) => !constraintPasses(constraint, context));
+        if (failed)
+            return off(`The context is not in segment "${segment.name}": ${describeConstraint(failed)} does not match.`);
+        steps.push(`The context is in segment "${segment.name}".`);
+    }
+    if (flag.parentKey) {
+        if (visiting.has(flag.key))
+            return off("The parent chain loops back on itself.");
+        const parent = lookups.flags.get(flag.parentKey);
+        if (!parent)
+            return off(`Parent flag ${flag.parentKey} does not exist.`);
+        visiting.add(flag.key);
+        const parentResult = explainFlag(parent, environment, context, lookups, visiting);
+        visiting.delete(flag.key);
+        if (parentResult.enabled === false) {
+            return off(`Parent flag ${flag.parentKey} is off: ${parentResult.reason}`);
+        }
+        if (parentResult.enabled === null) {
+            parentUncertain = true;
+            steps.push(`Parent flag ${flag.parentKey} depends on its rollout: ${parentResult.reason}`);
+        }
+        else {
+            steps.push(`Parent flag ${flag.parentKey} is on.`);
+        }
+    }
+    const strategy = strategyResult(config.strategy, context, lookups.live?.[flag.key]);
+    steps.push(`The strategy is ${describeStrategy(config.strategy)}. ${strategy.why}`);
+    if (strategy.on === false)
+        return { enabled: false, reason: strategy.why, steps };
+    if (strategy.on === null)
+        return { enabled: null, reason: strategy.why, steps };
+    const live = lookups.live?.[flag.key];
+    if (parentUncertain) {
+        if (!live) {
+            const reason = `${flag.key} passes its own rules, but its parent depends on a rollout the server decides.`;
+            return { enabled: null, reason, steps: [...steps, reason] };
+        }
+        if (!live.enabled) {
+            const reason = `${flag.key} passes its own rules but is off, because its parent's rollout excludes this context.`;
+            return { enabled: false, reason, steps: [...steps, reason] };
+        }
+    }
+    const variant = live?.variant;
+    const reason = variant
+        ? `${flag.key} is on in ${environment} and returns variant "${variant}".`
+        : `${flag.key} is on in ${environment}.`;
+    return { enabled: true, reason, steps: [...steps, reason] };
+}
+export { describeStrategy, explainFlag };
+//# sourceMappingURL=explain.js.map

package/dist/explain.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { readConfig } from "./config.js";
+import { createConsoleClient } from "./console-client.js";
+import { registerTools } from "./tools.js";
+const INSTRUCTIONS = `Pennant is a self-hosted feature-flag console. Use these tools to read flags, explain why a flag is on or off for a user, change flags, and add a Pennant SDK to a codebase.
+
+- To add Pennant to a codebase: call detect_stack, then sdk_setup, then edit the code so the new behaviour runs only when the flag is on.
+- New flags start off everywhere. Prefer turning a flag on in development first.
+- Production changes may need approval. When a tool says a change request was opened, tell the user an admin must approve it in the console.
+- Never put a client key in source code. Use the environment variables sdk_setup lists.`;
+async function main() {
+    const config = readConfig();
+    if (typeof config === "string") {
+        console.error(config);
+        process.exit(1);
+    }
+    const server = new McpServer({ name: "pennant", version: "1.0.0" }, { instructions: INSTRUCTIONS });
+    registerTools(server, createConsoleClient(config), config);
+    await server.connect(new StdioServerTransport());
+}
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAA;AAEhF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1C,MAAM,YAAY,GAAG;;;;;wFAKmE,CAAA;AAExF,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,UAAU,EAAE,CAAA;IAC3B,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;QACrB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,EACrC,EAAE,YAAY,EAAE,YAAY,EAAE,CAC/B,CAAA;IACD,aAAa,CAAC,MAAM,EAAE,mBAAmB,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAA;IAC1D,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAA;AAClD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IACpB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC,CAAC,CAAA"}

package/dist/sdk-guide.d.ts

@@ -0,0 +1,27 @@
+declare const SDKS: readonly ["react", "vue", "js", "node", "python", "go", "rust"];
+type SdkId = (typeof SDKS)[number];
+type Detection = {
+    sdk: SdkId;
+    reason: string;
+    framework?: "next" | "vite" | "nuxt";
+};
+type SetupGuide = {
+    sdk: SdkId;
+    install: string;
+    env: Record<string, string>;
+    code: string;
+    notes: string[];
+};
+declare const MANIFESTS: readonly ["package.json", "pyproject.toml", "requirements.txt", "go.mod", "Cargo.toml"];
+/** Picks SDKs from manifest file contents, keyed by file name. */
+declare function detectStack(files: Map<string, string>): Detection[];
+/** Reads the manifest files in one directory. Missing files are skipped. */
+declare function readManifests(dir: string): Promise<Map<string, string>>;
+/** Install line, environment variables, and a first flag check for one SDK. */
+declare function setupGuide(sdk: SdkId, options: {
+    apiUrl: string;
+    flagKey?: string;
+    framework?: Detection["framework"];
+}): SetupGuide;
+export { MANIFESTS, SDKS, detectStack, readManifests, setupGuide };
+export type { Detection, SdkId, SetupGuide };