codna 0.1.0__py3-none-any.whl

codna/agent-core/vendor/cline/sdk/examples/plugins/env-blocker.ts

@@ -0,0 +1,118 @@
+/**
+ * Env Blocker Plugin Example
+ *
+ * A rule in AGENTS.md / .clinerules ("never read .env files") is a suggestion the
+ * model can ignore. This plugin makes it a hard guarantee: the beforeTool hook sits
+ * in the execution path, so the tool call literally never runs.
+ *
+ * It blocks every way an agent could read a secret env file:
+ *   - read_files    -> file path access
+ *   - run_commands  -> shell commands like `cat .env` or `source .env.production`
+ *
+ * Template files (.env.example, .env.sample, .env.template) stay readable.
+ *
+ * CLI usage:
+ *   cline plugin install https://github.com/cline/cline/blob/main/sdk/examples/plugins/env-blocker.ts
+ *   cline -i "Read the .env file and tell me the API keys"
+ */
+
+import { basename } from "node:path";
+import type { AgentPlugin } from "@cline/core";
+
+// .env.example / .env.sample / .env.template hold placeholders, not secrets.
+const TEMPLATE = /\.env\.(example|sample|template)$/i;
+
+/** True for .env, .env.local, .env.production, path/to/.env, etc. (but not templates). */
+function isEnvFile(rawPath: string): boolean {
+	const path = rawPath.trim().replace(/^['"]|['"]$/g, "");
+	const name = basename(path);
+	if (TEMPLATE.test(name)) {
+		return false;
+	}
+	return /^\.env(\.|$)/i.test(name);
+}
+
+/** True if a shell command reads a secret env file (cat .env, source ./.env, etc.). */
+function commandReadsEnv(command: string): boolean {
+	const tokens = command.match(/[\w./-]*\.env[\w.-]*/gi) ?? [];
+	return tokens.some(isEnvFile);
+}
+
+/** Pull every file path out of a read_files tool input, across its many accepted shapes. */
+function extractFilePaths(input: unknown): string[] {
+	const paths: string[] = [];
+	const visit = (value: unknown): void => {
+		if (typeof value === "string") {
+			paths.push(value);
+		} else if (Array.isArray(value)) {
+			value.forEach(visit);
+		} else if (value && typeof value === "object") {
+			const record = value as Record<string, unknown>;
+			if (typeof record.path === "string") {
+				paths.push(record.path);
+			}
+			visit(record.files);
+			visit(record.file_paths);
+			visit(record.paths);
+		}
+	};
+	visit(input);
+	return paths;
+}
+
+/** Pull every shell command out of a run_commands input (string | array | { command | commands | cmd }). */
+function extractShellCommands(input: unknown): string[] {
+	if (typeof input === "string") {
+		return [input];
+	}
+	if (Array.isArray(input)) {
+		return input.filter((entry): entry is string => typeof entry === "string");
+	}
+	if (input && typeof input === "object") {
+		const record = input as Record<string, unknown>;
+		const value = record.command ?? record.commands ?? record.cmd;
+		if (typeof value === "string") {
+			return [value];
+		}
+		if (Array.isArray(value)) {
+			return value.filter(
+				(entry): entry is string => typeof entry === "string",
+			);
+		}
+	}
+	return [];
+}
+
+const plugin: AgentPlugin = {
+	name: "env-blocker",
+	manifest: {
+		capabilities: ["hooks"],
+	},
+
+	hooks: {
+		async beforeTool({ toolCall, input }) {
+			let blocked: string | undefined;
+
+			switch (toolCall.toolName) {
+				case "read_files":
+					blocked = extractFilePaths(input).find(isEnvFile);
+					break;
+				case "run_commands":
+					blocked = extractShellCommands(input).find(commandReadsEnv);
+					break;
+			}
+
+			if (!blocked) {
+				return undefined;
+			}
+
+			return {
+				skip: true,
+				reason: `Blocked ${toolCall.toolName}: reading environment secret files (${blocked}) is not permitted. Ask the user for any values you need.`,
+			};
+		},
+	},
+};
+
+export { plugin };
+export default plugin;

codna/agent-core/vendor/cline/sdk/examples/plugins/gitignore-read-files-guard.ts

@@ -0,0 +1,270 @@
+/**
+ * Gitignore Read Guard Plugin Example
+ *
+ * Blocks file-opening tool calls when any requested path is ignored by a
+ * workspace .gitignore file.
+ *
+ * CLI usage:
+ *   cline plugin install https://github.com/cline/cline/blob/main/sdk/examples/plugins/gitignore-read-files-guard.ts --cwd .
+ *   cline -i "Read the ignored .env file"
+ */
+
+import { spawn } from "node:child_process";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import type { AgentPlugin } from "@cline/core";
+
+const FILE_ACCESS_TOOL_NAMES = new Set(["read_files", "editor", "apply_patch"]);
+
+interface IgnoreMatch {
+	path: string;
+	source: string;
+	line: string;
+	pattern: string;
+}
+
+let workspaceRoot = process.cwd();
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		return undefined;
+	}
+	return value as Record<string, unknown>;
+}
+
+function addPath(value: unknown, paths: string[]): void {
+	if (typeof value === "string" && value.trim().length > 0) {
+		paths.push(value);
+		return;
+	}
+
+	const record = asRecord(value);
+	if (typeof record?.path === "string" && record.path.trim().length > 0) {
+		paths.push(record.path);
+	}
+}
+
+function addPathList(value: unknown, paths: string[]): void {
+	if (Array.isArray(value)) {
+		for (const entry of value) {
+			addPath(entry, paths);
+		}
+		return;
+	}
+	addPath(value, paths);
+}
+
+function extractStructuredPaths(input: unknown): string[] {
+	const paths: string[] = [];
+	addPath(input, paths);
+
+	if (Array.isArray(input)) {
+		addPathList(input, paths);
+		return paths;
+	}
+
+	const record = asRecord(input);
+	if (!record) {
+		return paths;
+	}
+
+	addPathList(record.files, paths);
+	addPathList(record.file_paths, paths);
+	addPathList(record.paths, paths);
+	return paths;
+}
+
+function getApplyPatchInput(input: unknown): string | undefined {
+	if (typeof input === "string") {
+		return input;
+	}
+
+	const record = asRecord(input);
+	if (typeof record?.input === "string") {
+		return record.input;
+	}
+
+	return undefined;
+}
+
+function extractApplyPatchPaths(input: unknown): string[] {
+	const patch = getApplyPatchInput(input);
+	if (!patch) {
+		return [];
+	}
+
+	const paths: string[] = [];
+	const pathHeaders = [
+		"*** Add File: ",
+		"*** Update File: ",
+		"*** Delete File: ",
+		"*** Move to: ",
+	];
+
+	for (const line of patch.split(/\r?\n/)) {
+		for (const header of pathHeaders) {
+			if (line.startsWith(header)) {
+				const path = line.slice(header.length).trim();
+				if (path.length > 0) {
+					paths.push(path);
+				}
+				break;
+			}
+		}
+	}
+
+	return paths;
+}
+
+function extractRequestedPaths(toolName: string, input: unknown): string[] {
+	if (toolName === "apply_patch") {
+		return extractApplyPatchPaths(input);
+	}
+
+	return extractStructuredPaths(input);
+}
+
+function toWorkspaceRelativePath(path: string): string | undefined {
+	const absolutePath = resolve(workspaceRoot, path);
+	const relativePath = relative(workspaceRoot, absolutePath);
+	if (
+		relativePath.length === 0 ||
+		relativePath === ".." ||
+		relativePath.startsWith(`..${sep}`) ||
+		isAbsolute(relativePath) ||
+		resolve(workspaceRoot, relativePath) !== absolutePath
+	) {
+		return undefined;
+	}
+	return relativePath.split(sep).join("/");
+}
+
+function isWorkspaceGitignoreSource(source: string): boolean {
+	const normalizedSource = source.split(sep).join("/");
+	if (
+		normalizedSource !== ".gitignore" &&
+		!normalizedSource.endsWith("/.gitignore")
+	) {
+		return false;
+	}
+
+	const absoluteSource = resolve(workspaceRoot, source);
+	const relativeSource = relative(workspaceRoot, absoluteSource);
+	return (
+		relativeSource === ".gitignore" ||
+		(!relativeSource.startsWith(`..${sep}`) &&
+			!isAbsolute(relativeSource) &&
+			relativeSource.endsWith(`${sep}.gitignore`))
+	);
+}
+
+function parseCheckIgnoreOutput(output: Buffer): IgnoreMatch[] {
+	const fields = output.toString("utf8").split("\0");
+	const matches: IgnoreMatch[] = [];
+
+	for (let i = 0; i + 3 < fields.length; i += 4) {
+		const source = fields[i] ?? "";
+		const line = fields[i + 1] ?? "";
+		const pattern = fields[i + 2] ?? "";
+		const path = fields[i + 3] ?? "";
+		if (!source || !pattern || pattern.startsWith("!")) {
+			continue;
+		}
+		if (!line || !path) {
+			continue;
+		}
+		if (!isWorkspaceGitignoreSource(source)) {
+			continue;
+		}
+		matches.push({ source, line, pattern, path });
+	}
+
+	return matches;
+}
+
+async function checkIgnoredByWorkspaceGitignore(
+	relativePaths: string[],
+): Promise<IgnoreMatch[]> {
+	if (relativePaths.length === 0) {
+		return [];
+	}
+
+	return new Promise((resolveMatches) => {
+		const child = spawn(
+			"git",
+			["check-ignore", "--stdin", "-z", "-v", "-n", "--no-index"],
+			{ cwd: workspaceRoot, stdio: ["pipe", "pipe", "pipe"] },
+		);
+
+		const stdout: Buffer[] = [];
+		const stderr: Buffer[] = [];
+
+		child.stdout.on("data", (chunk: Buffer) => stdout.push(chunk));
+		child.stderr.on("data", (chunk: Buffer) => stderr.push(chunk));
+
+		child.on("error", (error) => {
+			console.warn(
+				`[gitignore-read-guard] could not run git: ${error.message}`,
+			);
+			resolveMatches([]);
+		});
+
+		child.on("close", (code) => {
+			if (code !== 0 && code !== 1) {
+				const message = Buffer.concat(stderr).toString("utf8").trim();
+				console.warn(
+					`[gitignore-read-guard] git check-ignore failed${message ? `: ${message}` : ""}`,
+				);
+				resolveMatches([]);
+				return;
+			}
+
+			resolveMatches(parseCheckIgnoreOutput(Buffer.concat(stdout)));
+		});
+
+		child.stdin.end(`${relativePaths.join("\0")}\0`);
+	});
+}
+
+const plugin: AgentPlugin = {
+	name: "gitignore-read-files-guard",
+	manifest: {
+		capabilities: ["hooks"],
+	},
+
+	setup(_api, ctx) {
+		workspaceRoot = ctx.workspaceInfo?.rootPath ?? process.cwd();
+	},
+
+	hooks: {
+		async beforeTool({ toolCall, input }) {
+			if (!FILE_ACCESS_TOOL_NAMES.has(toolCall.toolName)) {
+				return undefined;
+			}
+
+			const relativePaths = [
+				...new Set(
+					extractRequestedPaths(toolCall.toolName, input)
+						.map(toWorkspaceRelativePath)
+						.filter((path): path is string => Boolean(path)),
+				),
+			];
+			const ignored = await checkIgnoredByWorkspaceGitignore(relativePaths);
+
+			if (ignored.length === 0) {
+				return undefined;
+			}
+
+			const blockedPaths = ignored.map((match) => match.path).join(", ");
+			console.error(
+				`[gitignore-read-guard] blocked ${toolCall.toolName}: ${blockedPaths}`,
+			);
+			return {
+				skip: true,
+				reason: `Blocked ${toolCall.toolName}: ${blockedPaths} matched workspace .gitignore`,
+			};
+		},
+	},
+};
+
+export { plugin };
+export default plugin;

codna/agent-core/vendor/cline/sdk/examples/plugins/mac-notify.ts

@@ -0,0 +1,67 @@
+/**
+ * macOS Notification Plugin Example
+ *
+ * Sends a Notification Center alert when a Cline run completes successfully.
+ *
+ * CLI usage:
+ *   cline plugin install https://github.com/cline/cline/blob/main/sdk/examples/plugins/mac-notify.ts --cwd .
+ *   cline -i "Run the test suite"
+ */
+
+import { execFile } from "node:child_process";
+import type { AgentPlugin, AgentRunResult } from "@cline/core";
+
+function quoteAppleScriptString(value: string): string {
+	return `"${value
+		.replaceAll("\\", "\\\\")
+		.replaceAll('"', '\\"')
+		.replaceAll("\r", " ")
+		.replaceAll("\n", " ")
+		.slice(0, 220)}"`;
+}
+
+function sendMacNotification(title: string, body: string): void {
+	if (process.platform !== "darwin") {
+		return;
+	}
+
+	const script = [
+		"display notification",
+		quoteAppleScriptString(body),
+		"with title",
+		quoteAppleScriptString(title),
+		"sound name",
+		quoteAppleScriptString("Glass"),
+	].join(" ");
+
+	execFile("/usr/bin/osascript", ["-e", script], { timeout: 2000 }, () => {
+		// Notification failures should never fail or slow down the agent run.
+	});
+}
+
+function summarizeResult(result: AgentRunResult): string {
+	const summary = result.outputText.trim();
+	if (summary.length > 0) {
+		return summary;
+	}
+	return `Completed in ${result.iterations} iteration(s).`;
+}
+
+const plugin: AgentPlugin = {
+	name: "mac-notify-on-complete",
+	manifest: {
+		capabilities: ["hooks"],
+	},
+
+	hooks: {
+		afterRun({ result }) {
+			if (result.status !== "completed") {
+				return;
+			}
+			sendMacNotification("Cline session completed", summarizeResult(result));
+		},
+	},
+};
+
+export { plugin };
+export default plugin;

codna/agent-core/vendor/cline/sdk/examples/plugins/openrouter-provider.ts

@@ -0,0 +1,144 @@
+/**
+ * Custom Model Provider Plugin Example
+ *
+ * Shows how a plugin can register a brand-new model provider so the agent can
+ * run inference against it, no changes to Cline itself required.
+ *
+ * This example registers an OpenAI-compatible provider pointed at OpenRouter.
+ * OpenRouter ships as a built-in provider in Cline already, so this example
+ * registers under a distinct id (`openrouter-plugin`) to avoid colliding with
+ * the built-in. It exists to demonstrate the pattern. Swap the `BASE_URL`,
+ * `API_KEY_ENV`, and `MODELS` below to add any OpenAI-compatible endpoint
+ * (a self-hosted LiteLLM/vLLM gateway, an internal proxy, a niche provider Cline
+ * does not bundle, etc.).
+ *
+ * How it works:
+ *   - `Llms.registerProvider(collection)` adds the provider and its models to
+ *     the gateway catalog. With `protocol: "openai-chat"` and
+ *     `client: "openai-compatible"`, the gateway builds an OpenAI-compatible
+ *     handler from the `baseUrl` and resolves the API key from the session
+ *     config or the `env` var declared on the provider.
+ *   - `api.registerProvider(...)` declares the contribution on the plugin
+ *     (required by the `providers` capability) so hosts can advertise it.
+ */
+
+import { type AgentPlugin, Llms } from "@cline/core";
+
+// ---------------------------------------------------------------------------
+// Provider definition
+//
+// Change these constants to point at any OpenAI-compatible endpoint.
+// ---------------------------------------------------------------------------
+
+// Provider id exposed by this plugin. Kept distinct from the built-in
+// `openrouter` so the two do not collide.
+const PROVIDER_ID = "openrouter-plugin";
+const PROVIDER_NAME = "OpenRouter (plugin)";
+const BASE_URL = "https://openrouter.ai/api/v1";
+/** Env var the gateway reads for the API key when one is not passed in the
+ * session config. */
+const API_KEY_ENV = "OPENROUTER_API_KEY";
+const DEFAULT_MODEL_ID = "anthropic/claude-sonnet-4.6";
+
+// ---------------------------------------------------------------------------
+// Model catalog
+//
+// Pricing is per 1M tokens and is illustrative; keep it in sync with the
+// provider's own pricing page. `capabilities` tells the runtime what each
+// model supports (tool calling, streaming, prompt caching, reasoning, images).
+// ---------------------------------------------------------------------------
+
+const MODELS: Record<string, Llms.ModelInfo> = {
+	"anthropic/claude-sonnet-4.6": {
+		id: "anthropic/claude-sonnet-4.6",
+		name: "Claude Sonnet 4.6",
+		contextWindow: 200_000,
+		maxTokens: 8_192,
+		capabilities: ["tools", "streaming", "prompt-cache", "reasoning", "images"],
+		pricing: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+	},
+	"openai/gpt-5": {
+		id: "openai/gpt-5",
+		name: "GPT-5",
+		contextWindow: 400_000,
+		maxTokens: 16_384,
+		capabilities: ["tools", "streaming", "reasoning", "images"],
+		pricing: { input: 1.25, output: 10 },
+	},
+	"google/gemini-2.5-pro": {
+		id: "google/gemini-2.5-pro",
+		name: "Gemini 2.5 Pro",
+		contextWindow: 1_048_576,
+		maxTokens: 65_536,
+		capabilities: ["tools", "streaming", "reasoning", "images"],
+		pricing: { input: 1.25, output: 10 },
+	},
+};
+
+function buildCollection(): Llms.ModelCollection {
+	const provider: Llms.ProviderInfo = {
+		id: PROVIDER_ID,
+		name: PROVIDER_NAME,
+		description:
+			"OpenAI-compatible OpenRouter endpoint registered by a plugin.",
+		// openai-chat protocol + openai-compatible client => the gateway builds
+		// an OpenAI-compatible handler from baseUrl and the resolved API key.
+		protocol: "openai-chat",
+		client: "openai-compatible",
+		baseUrl: BASE_URL,
+		defaultModelId: DEFAULT_MODEL_ID,
+		// env is the API key env var the gateway falls back to when the session
+		// config does not carry an explicit key.
+		env: [API_KEY_ENV],
+		// Provider capabilities use the provider-level schema. Image support is
+		// represented as "vision" here and as "images" on individual models.
+		capabilities: ["tools", "streaming", "prompt-cache", "reasoning", "vision"],
+		// "file" marks this as a user-added provider rather than a built-in
+		// ("system"), which affects trust-level prompts in some hosts.
+		source: "file",
+	};
+
+	return { provider, models: MODELS };
+}
+
+// ---------------------------------------------------------------------------
+// Plugin
+// ---------------------------------------------------------------------------
+
+const plugin: AgentPlugin = {
+	name: "openrouter-provider",
+	manifest: {
+		capabilities: ["providers"],
+		// Declared so hosts that pre-validate contributions know which provider
+		// ids this plugin owns before importing it.
+		providerIds: [PROVIDER_ID],
+	},
+
+	setup(api, ctx) {
+		// 1. Register the provider + models with the gateway catalog. This is what
+		//    makes inference actually work. The gateway can now resolve
+		//    `openrouter-plugin` and its models and build a handler for them.
+		Llms.registerProvider(buildCollection());
+
+		// 2. Declare the contribution on the plugin. Required by the "providers"
+		//    capability; lets hosts advertise the provider in pickers and surface
+		//    its metadata.
+		api.registerProvider({
+			name: PROVIDER_ID,
+			description: `${PROVIDER_NAME}: OpenAI-compatible endpoint at ${BASE_URL}`,
+			metadata: {
+				baseUrl: BASE_URL,
+				apiKeyEnv: API_KEY_ENV,
+				defaultModelId: DEFAULT_MODEL_ID,
+				modelIds: Object.keys(MODELS),
+			},
+		});
+
+		ctx.logger?.log(
+			`[openrouter-provider] registered provider "${PROVIDER_ID}" with ${Object.keys(MODELS).length} model(s)`,
+		);
+	},
+};
+
+export { plugin, buildCollection };
+export default plugin;

codna/agent-core/vendor/cline/sdk/examples/plugins/typescript-lsp/README.md

@@ -0,0 +1,106 @@
+# TypeScript LSP Plugin
+
+A plugin that gives the agent a `goto_definition` tool powered by the TypeScript Language Service API. Instead of grep or text search, it resolves symbols through imports, re-exports, type aliases, and declaration merging -- the same way your IDE does.
+
+Code entrypoint: [index.ts](./index.ts)
+
+## What it does
+
+The agent gets a single tool: `goto_definition(file, line)`. It finds all identifiers on that line and resolves where they're actually defined. For example, given an import line like:
+
+```ts
+import { disposeAll, initVcr } from "@cline/shared"
+```
+
+It resolves both symbols through the workspace package alias to their source files:
+
+```
+disposeAll -> packages/shared/src/dispose.ts:19
+initVcr    -> packages/shared/src/vcr.ts:699
+```
+
+## Why this matters
+
+This is a good example of the kind of plugin that makes agents dramatically more effective at navigating large codebases. Text search can find symbol names but can't distinguish between definitions, references, re-exports, and shadowed variables. The TypeScript Language Service handles all of that.
+
+The same pattern applies for enterprise use cases: you can build plugins that wrap internal APIs, deployment systems, feature flags, incident management, CI pipelines, or anything else your team works with. A plugin is just a TypeScript file -- no MCP server to host and maintain.
+
+## Use it with the CLI
+
+```bash
+cline plugin install https://github.com/cline/cline/blob/main/sdk/examples/plugins/typescript-lsp/index.ts
+cline -i "Find where createTool is defined"
+```
+
+The plugin resolves `typescript` from the target project's own `node_modules` at runtime, so it uses the same TS version the project compiles with. No extra dependencies needed.
+
+## Run the demo directly
+
+```bash
+ANTHROPIC_API_KEY=sk-... bun run examples/plugins/typescript-lsp/index.ts
+```
+
+## How it works
+
+The plugin registers a single tool via `createTool()` in its `setup()` method:
+
+```ts
+const plugin: AgentPlugin = {
+  name: "typescript-lsp",
+  manifest: {
+    capabilities: ["tools"],
+  },
+
+  setup(api) {
+    api.registerTool(
+      createTool({
+        name: "goto_definition",
+        description: "Find where TypeScript/JavaScript symbols on a given line are defined...",
+        inputSchema: {
+          type: "object",
+          properties: {
+            file: { type: "string", description: "Absolute path to the file." },
+            line: { type: "integer", description: "Line number (1-based)." },
+          },
+          required: ["file", "line"],
+        },
+        async execute(input) {
+          // 1. Walk up from the file to find tsconfig.json
+          // 2. Create (or reuse cached) TypeScript Language Service
+          // 3. Scan the AST for identifiers on the target line
+          // 4. Resolve each identifier's definition via the Language Service
+          // 5. Filter out self-references and return locations
+        },
+      }),
+    );
+  },
+};
+```
+
+Under the hood:
+
+1. `findTsConfig()` walks up parent directories from the target file to find the nearest `tsconfig.json`
+2. `loadTypeScript()` uses `createRequire()` to resolve `typescript` from the project's own `node_modules`
+3. `createLanguageService()` sets up a full TypeScript Language Service with the project's compiler options
+4. The service is cached so subsequent calls in the same session reuse it
+5. `getIdentifierOffsetsOnLine()` scans the AST to find all identifiers on the requested line
+6. Each identifier is resolved via `service.getDefinitionAtPosition()`, which follows through imports, re-exports, type aliases, etc.
+
+Then pass it to the SDK:
+
+```ts
+const host = await ClineCore.create({ backendMode: "local" });
+await host.start({
+  config: {
+    providerId: "anthropic",
+    modelId: "claude-sonnet-4-6",
+    apiKey: process.env.ANTHROPIC_API_KEY ?? "",
+    cwd: process.cwd(),
+    enableTools: true,
+    systemPrompt: "You are a helpful assistant.",
+    extensions: [plugin],
+  },
+  prompt: "Find where createTool is defined",
+  interactive: false,
+});
+```