@blogic-cz/agent-tools 0.14.12 → 0.14.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogic-cz/agent-tools",
-  "version": "0.14.12",
+  "version": "0.14.14",
   "description": "CLI tools for AI coding agent workflows — GitHub, database, Kubernetes, Azure DevOps, logs, sessions, and audit",
   "keywords": [
     "agent",

package/schemas/agent-tools.schema.json

@@ -123,6 +123,10 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
+        "kubeconfig": {
+          "description": "Optional kubeconfig path. Supports ${ENV_VAR} templates.",
+          "type": "string"
+        },
         "clusterId": {
           "description": "Cluster identifier.",
           "type": "string"
@@ -202,6 +206,10 @@
           "type": "object",
           "additionalProperties": false,
           "properties": {
+            "kubeconfig": {
+              "description": "Optional kubeconfig path. Supports ${ENV_VAR} templates.",
+              "type": "string"
+            },
             "context": {
               "description": "Kubectl context name.",
               "type": "string"
@@ -235,6 +243,16 @@
         "vpn": {
           "type": "string",
           "description": "Convenience sugar for a VPN prerequisite key. Runtime normalizes this to prerequisites."
+        },
+        "allowedMutations": {
+          "description": "Explicitly allowed SQL mutation operations per environment. Non-local environments default to read-only.",
+          "type": "object",
+          "additionalProperties": {
+            "type": "array",
+            "items": {
+              "$ref": "#/definitions/DbMutationOperation"
+            }
+          }
         }
       },
       "required": ["environments"]
@@ -530,6 +548,11 @@
         }
       },
       "required": ["name"]
+    },
+    "DbMutationOperation": {
+      "description": "SQL mutation operation that can be explicitly allowed for a database environment.",
+      "type": "string",
+      "enum": ["insert", "update", "delete"]
     }
   },
   "examples": [
@@ -576,7 +599,10 @@
             "namespace": "system"
           },
           "tunnelTimeoutMs": 5000,
-          "remotePort": 5432
+          "remotePort": 5432,
+          "allowedMutations": {
+            "test": ["insert"]
+          }
         }
       },
       "logs": {

package/src/config/index.ts

@@ -3,6 +3,7 @@ export type {
   AzureConfig,
   K8sConfig,
   DbEnvConfig,
+  DbMutationOperation,
   DatabaseConfig,
   ObservabilityConfig,
   ObservabilityEnvTarget,
@@ -13,6 +14,8 @@ export type {
   GitHubRepoConfig,
 } from "./types";
 
+export { DbMutationOperationSchema } from "./types";
+
 export {
   ConfigService,
   ConfigServiceLayer,

package/src/config/loader.ts

@@ -3,6 +3,7 @@ import { dirname } from "node:path";
 import { Context, Data, Effect, Layer, Schema } from "effect";
 
 import type { AgentToolsConfig, GitHubRepoConfig } from "./types";
+import { DbMutationOperationSchema } from "./types";
 
 const CliToolOverrideSchema = Schema.Struct({
   tool: Schema.String,
@@ -75,6 +76,7 @@ const AzureConfigSchema = Schema.Struct({
 });
 
 const K8sConfigSchema = Schema.Struct({
+  kubeconfig: Schema.optionalKey(Schema.String),
   clusterId: Schema.String,
   namespaces: Schema.Record(Schema.String, Schema.String),
   timeoutMs: Schema.optionalKey(Schema.Number),
@@ -93,8 +95,12 @@ const DbEnvConfigSchema = Schema.Struct({
 
 const DatabaseConfigSchema = Schema.Struct({
   environments: Schema.Record(Schema.String, DbEnvConfigSchema),
+  allowedMutations: Schema.optionalKey(
+    Schema.Record(Schema.String, Schema.Array(DbMutationOperationSchema)),
+  ),
   kubectl: Schema.optionalKey(
     Schema.Struct({
+      kubeconfig: Schema.optionalKey(Schema.String),
       context: Schema.String,
       namespace: Schema.String,
       service: Schema.optionalKey(Schema.String),

package/src/config/types.ts

@@ -1,3 +1,5 @@
+import { Schema } from "effect";
+
 /** Azure DevOps profile configuration */
 export type AzureConfig = {
   organization: string;
@@ -63,6 +65,8 @@ export type ProfilePrerequisites = {
 
 /** Kubernetes cluster profile configuration */
 export type K8sConfig = ProfilePrerequisites & {
+  /** Optional kubeconfig path. Supports ${ENV_VAR} templates. */
+  kubeconfig?: string;
   clusterId: string;
   /** Named namespaces, e.g. { test: "my-app-test", prod: "my-app-prod" } */
   namespaces: Record<string, string>;
@@ -81,11 +85,19 @@ export type DbEnvConfig = {
   passwordEnvVar?: string;
 };
 
+/** SQL mutation operation that can be explicitly allowed for a database environment. */
+export const DbMutationOperationSchema = Schema.Literals(["insert", "update", "delete"]);
+export type DbMutationOperation = Schema.Schema.Type<typeof DbMutationOperationSchema>;
+
 /** Database profile configuration */
 export type DatabaseConfig = ProfilePrerequisites & {
   /** Named database environments, e.g. { local: {...}, test: {...}, prod: {...} } */
   environments: Record<string, DbEnvConfig>;
+  /** Explicitly allowed SQL mutation operations per environment. Non-local environments default to read-only. */
+  allowedMutations?: Record<string, readonly DbMutationOperation[]>;
   kubectl?: {
+    /** Optional kubeconfig path. Supports ${ENV_VAR} templates. */
+    kubeconfig?: string;
     context: string;
     namespace: string;
     service?: string;

package/src/db-tool/security.ts

@@ -1,4 +1,4 @@
-import type { SchemaErrorInfo } from "./types";
+import type { DbMutationOperation, SchemaErrorInfo } from "./types";
 
 const MUTATION_PATTERNS = [
   /^\s*UPDATE\s+/i,
@@ -10,6 +10,12 @@ const MUTATION_PATTERNS = [
   /^\s*CREATE\s+/i,
 ];
 
+const ALLOWABLE_MUTATION_PATTERNS: Array<[DbMutationOperation, RegExp]> = [
+  ["insert", /^\s*INSERT\s+/i],
+  ["update", /^\s*UPDATE\s+/i],
+  ["delete", /^\s*DELETE\s+/i],
+];
+
 const TABLE_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)?$/;
 
 /**
@@ -78,6 +84,11 @@ export function isMutationQuery(sql: string): boolean {
   return MUTATION_PATTERNS.some((pattern) => pattern.test(stripped));
 }
 
+export function getAllowedMutationOperation(sql: string): DbMutationOperation | undefined {
+  const stripped = stripSqlComments(sql);
+  return ALLOWABLE_MUTATION_PATTERNS.find(([, pattern]) => pattern.test(stripped))?.[0];
+}
+
 export function isValidTableName(tableName: string): boolean {
   return TABLE_NAME_PATTERN.test(tableName);
 }

package/src/db-tool/service.ts

@@ -1,10 +1,11 @@
 import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
 import { Clock, Context, Duration, Effect, Layer, Ref, Stream } from "effect";
 
-import type { DbConfig, QueryResult, SchemaMode } from "./types";
+import type { DbConfig, DbMutationOperation, QueryResult, SchemaMode } from "./types";
 
 import { ConfigService } from "#config";
 import { isPrerequisiteRunError } from "#shared/prerequisites/errors";
+import { resolveEnvTemplate } from "#shared/env-template";
 import { runWithProfilePrerequisites } from "#shared/prerequisites/runtime";
 import { DbConfigService, DbConfigServiceLayer, TUNNEL_CHECK_INTERVAL_MS } from "./config-service";
 import {
@@ -22,7 +23,12 @@ import {
   parseTableReference,
   SYSTEM_SCHEMAS_SQL,
 } from "./schema";
-import { detectSchemaError, isValidTableName, isMutationQuery } from "./security";
+import {
+  detectSchemaError,
+  getAllowedMutationOperation,
+  isValidTableName,
+  isMutationQuery,
+} from "./security";
 import { transformQueryResult } from "./transformers";
 
 const LOCALHOST_HOSTS = new Set(["localhost", "127.0.0.1"]);
@@ -31,7 +37,8 @@ export function resolveDbAccessMode(
   env: string,
   host: string,
   hasKubectlConfig: boolean,
-): Pick<DbConfig, "allowMutations" | "host" | "needsTunnel"> {
+  allowedMutations: readonly DbMutationOperation[] = [],
+): Pick<DbConfig, "allowMutations" | "allowedMutations" | "host" | "needsTunnel"> {
   const isLocalHost = LOCALHOST_HOSTS.has(host);
   const isLocalEnvironment = env === "local";
 
@@ -39,6 +46,7 @@ export function resolveDbAccessMode(
     host,
     needsTunnel: hasKubectlConfig && !isLocalEnvironment && isLocalHost,
     allowMutations: isLocalEnvironment,
+    allowedMutations: isLocalEnvironment ? ["insert", "update", "delete"] : allowedMutations,
   };
 }
 
@@ -75,6 +83,7 @@ export class DbService extends Context.Service<
           };
         }
 
+        const kubectlKubeconfig = dbConfig.kubectl?.kubeconfig;
         const kubectlContext = dbConfig.kubectl?.context;
         const kubectlNamespace = dbConfig.kubectl?.namespace;
         const kubectlService = dbConfig.kubectl?.service ?? "postgresql";
@@ -262,6 +271,24 @@ export class DbService extends Context.Service<
             }
           });
 
+        const resolveKubeconfig = Effect.fn("DbService.resolveKubeconfig")(function* (
+          port: number,
+        ) {
+          if (!kubectlKubeconfig) {
+            return undefined;
+          }
+
+          return yield* resolveEnvTemplate(kubectlKubeconfig).pipe(
+            Effect.mapError(
+              ({ envVar }) =>
+                new DbTunnelError({
+                  message: `Environment variable ${envVar} (required for kubeconfig) is not set.`,
+                  port,
+                }),
+            ),
+          );
+        });
+
         const startTunnelProcess = (config: DbConfig) =>
           Effect.gen(function* () {
             if (!kubectlContext || !kubectlNamespace) {
@@ -274,10 +301,14 @@ export class DbService extends Context.Service<
               );
             }
 
+            const kubeconfig = yield* resolveKubeconfig(config.port);
+            const kubeconfigArgs = kubeconfig ? ["--kubeconfig", kubeconfig] : [];
+
             const proc = yield* executor.spawn(
               ChildProcess.make(
                 "kubectl",
                 [
+                  ...kubeconfigArgs,
                   "port-forward",
                   "--context",
                   kubectlContext,
@@ -616,6 +647,7 @@ export class DbService extends Context.Service<
             env,
             envConfig.host,
             dbConfig.kubectl !== undefined,
+            dbConfig.allowedMutations?.[env] ?? [],
           );
 
           return {
@@ -627,6 +659,7 @@ export class DbService extends Context.Service<
             port: envConfig.port,
             needsTunnel: accessMode.needsTunnel,
             allowMutations: accessMode.allowMutations,
+            allowedMutations: accessMode.allowedMutations,
           };
         };
 
@@ -639,12 +672,22 @@ export class DbService extends Context.Service<
           const resolvedConfig = yield* resolveDbConfig(config, env);
           const password = yield* resolvePassword(resolvedConfig, env);
           const mutation = isMutationQuery(sql);
-
-          if (mutation && !resolvedConfig.allowMutations) {
+          const mutationOperation = mutation ? getAllowedMutationOperation(sql) : undefined;
+          const mutationAllowed =
+            !mutation ||
+            resolvedConfig.allowMutations ||
+            (mutationOperation !== undefined &&
+              resolvedConfig.allowedMutations.includes(mutationOperation));
+
+          if (!mutationAllowed) {
+            const allowed =
+              resolvedConfig.allowedMutations.length > 0
+                ? resolvedConfig.allowedMutations.join(", ")
+                : "none";
             return yield* new DbMutationBlockedError({
-              message:
-                "Mutation queries (UPDATE, INSERT, DELETE, etc.) are not allowed on this environment. Use a local environment for mutations.",
+              message: `Mutation queries are not allowed on environment ${env}. Allowed mutation operations: ${allowed}.`,
               environment: env,
+              hint: 'Configure database.<profile>.allowedMutations.<env> with explicit operations such as ["insert"] if this environment should allow controlled mutations.',
             });
           }
 

package/src/db-tool/types.ts

@@ -1,4 +1,7 @@
+import type { DbMutationOperation } from "#config";
 import type { Environment, OutputFormat } from "#shared";
+
+export type { DbMutationOperation };
 export type { Environment, OutputFormat };
 
 export type SchemaMode = "tables" | "columns" | "full" | "relationships";
@@ -12,6 +15,7 @@ export type DbConfig = {
   port: number;
   needsTunnel: boolean;
   allowMutations: boolean;
+  allowedMutations: readonly DbMutationOperation[];
 };
 
 export type QueryResult = {

package/src/k8s-tool/service.ts

@@ -11,7 +11,8 @@ import {
 } from "./errors";
 import { ConfigService, getToolConfig } from "#config";
 import type { K8sConfig } from "#config";
-import { collectProcessOutput } from "#shared/exec";
+import { collectProcessOutput, quoteShellArg } from "#shared/exec";
+import { resolveEnvTemplate } from "#shared/env-template";
 import { isPrerequisiteRunError } from "#shared/prerequisites/errors";
 import { runWithProfilePrerequisites } from "#shared/prerequisites/runtime";
 import { isKubectlCommandAllowed } from "./security";
@@ -63,6 +64,28 @@ export class K8sService extends Context.Service<
             return k8sConfig;
           });
 
+        const resolveKubeconfig = Effect.fn("K8sService.resolveKubeconfig")(function* (
+          k8sConfig: K8sConfig,
+        ) {
+          const kubeconfig = k8sConfig.kubeconfig;
+          if (!kubeconfig) {
+            return undefined;
+          }
+
+          return yield* resolveEnvTemplate(kubeconfig).pipe(
+            Effect.mapError(
+              ({ envVar }) =>
+                new K8sContextError({
+                  message: `Environment variable ${envVar} (required for kubeconfig) is not set.`,
+                  clusterId: k8sConfig.clusterId,
+                }),
+            ),
+          );
+        });
+
+        const withKubeconfig = (command: string, kubeconfig: string | undefined) =>
+          kubeconfig ? `KUBECONFIG=${quoteShellArg(kubeconfig)} ${command}` : command;
+
         // Cache context by selected profile/cluster instead of a single default profile.
         const contextRef = yield* Ref.make<Record<string, string>>({});
 
@@ -128,14 +151,18 @@ export class K8sService extends Context.Service<
           k8sConfig: K8sConfig,
         ) {
           const timeoutMs = k8sConfig.timeoutMs ?? 60000;
-          const cacheKey = profile ?? `cluster:${k8sConfig.clusterId}`;
+          const kubeconfig = yield* resolveKubeconfig(k8sConfig);
+          const cacheKey = profile ?? `cluster:${k8sConfig.clusterId}:${kubeconfig ?? "default"}`;
           const cached = yield* Ref.get(contextRef);
           const cachedContext = cached[cacheKey];
           if (cachedContext !== undefined) {
-            return cachedContext;
+            return { context: cachedContext, kubeconfig };
           }
 
-          const jqCommand = `kubectl config view -o json | jq -r '.contexts[] | select(.context.cluster == "${k8sConfig.clusterId}") | .name' | head -1`;
+          const jqCommand = withKubeconfig(
+            `kubectl config view -o json | jq -r '.contexts[] | select(.context.cluster == "${k8sConfig.clusterId}") | .name' | head -1`,
+            kubeconfig,
+          );
 
           const contextResultOption = yield* runShellCommand(jqCommand, timeoutMs);
 
@@ -155,10 +182,13 @@ export class K8sService extends Context.Service<
               ...contexts,
               [cacheKey]: resolvedContextValue,
             }));
-            return resolvedContextValue;
+            return { context: resolvedContextValue, kubeconfig };
           }
 
-          const fallbackCommand = `kubectl config view -o json | jq -r '.contexts[] as $ctx | .clusters[] | select(.name == $ctx.context.cluster and (.cluster.server | contains("${k8sConfig.clusterId}"))) | $ctx.name' | head -1`;
+          const fallbackCommand = withKubeconfig(
+            `kubectl config view -o json | jq -r '.contexts[] as $ctx | .clusters[] | select(.name == $ctx.context.cluster and (.cluster.server | contains("${k8sConfig.clusterId}"))) | $ctx.name' | head -1`,
+            kubeconfig,
+          );
 
           const fallbackResultOption = yield* runShellCommand(fallbackCommand, timeoutMs);
 
@@ -178,7 +208,7 @@ export class K8sService extends Context.Service<
               ...contexts,
               [cacheKey]: resolvedContextValue,
             }));
-            return resolvedContextValue;
+            return { context: resolvedContextValue, kubeconfig };
           }
 
           return yield* new K8sContextError({
@@ -198,8 +228,8 @@ export class K8sService extends Context.Service<
             k8sConfig,
             runPrerequisiteCommand,
             Effect.gen(function* () {
-              const context = yield* resolveContext(profile, k8sConfig);
-              const fullCommand = `kubectl --context ${context} ${cmd}`;
+              const { context, kubeconfig } = yield* resolveContext(profile, k8sConfig);
+              const fullCommand = withKubeconfig(`kubectl --context ${context} ${cmd}`, kubeconfig);
 
               const resultOption = yield* runShellCommand(fullCommand, timeoutMs);
 
@@ -282,8 +312,8 @@ export class K8sService extends Context.Service<
           const startTime = Date.now();
           if (dryRun) {
             const k8sConfig = yield* requireK8sConfig(profile);
-            const context = yield* resolveContext(profile, k8sConfig);
-            const fullCommand = `kubectl --context ${context} ${cmd}`;
+            const { context, kubeconfig } = yield* resolveContext(profile, k8sConfig);
+            const fullCommand = withKubeconfig(`kubectl --context ${context} ${cmd}`, kubeconfig);
             return {
               success: true,
               command: fullCommand,

package/src/shared/env-template.ts

@@ -0,0 +1,38 @@
+import { Effect, Schema } from "effect";
+
+const envTemplateRegex = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+export class EnvTemplateError extends Schema.TaggedErrorClass<EnvTemplateError>()(
+  "@agent-tools/EnvTemplateError",
+  { envVar: Schema.String },
+) {}
+
+export const resolveEnvTemplate = Effect.fn("resolveEnvTemplate")(function* (value: string) {
+  let resolved = "";
+  let lastIndex = 0;
+  const env = globalThis.Bun?.env ?? process.env;
+
+  for (const match of value.matchAll(envTemplateRegex)) {
+    const fullMatch = match[0];
+    const envVar = match[1];
+    const index = match.index;
+    if (index === undefined) {
+      continue;
+    }
+
+    resolved += value.slice(lastIndex, index);
+    const fromEnv = env[envVar];
+    if (fromEnv === undefined) {
+      return yield* new EnvTemplateError({ envVar });
+    }
+
+    resolved += fromEnv;
+    lastIndex = index + fullMatch.length;
+  }
+
+  if (lastIndex === 0) {
+    return value;
+  }
+
+  return resolved + value.slice(lastIndex);
+});

package/src/shared/exec.ts

@@ -67,3 +67,5 @@ export const execEffect = (
       ),
     ),
   );
+
+export const quoteShellArg = (value: string) => `'${value.replaceAll("'", "'\\''")}'`;