@blogic-cz/agent-tools 0.14.13 → 0.14.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogic-cz/agent-tools",
-  "version": "0.14.13",
+  "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

@@ -243,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"]
@@ -538,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": [
@@ -584,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,
@@ -94,6 +95,9 @@ 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),

package/src/config/types.ts

@@ -1,3 +1,5 @@
+import { Schema } from "effect";
+
 /** Azure DevOps profile configuration */
 export type AzureConfig = {
   organization: string;
@@ -83,10 +85,16 @@ 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;

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,7 +1,7 @@
 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";
@@ -23,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"]);
@@ -32,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";
 
@@ -40,6 +46,7 @@ export function resolveDbAccessMode(
     host,
     needsTunnel: hasKubectlConfig && !isLocalEnvironment && isLocalHost,
     allowMutations: isLocalEnvironment,
+    allowedMutations: isLocalEnvironment ? ["insert", "update", "delete"] : allowedMutations,
   };
 }
 
@@ -640,6 +647,7 @@ export class DbService extends Context.Service<
             env,
             envConfig.host,
             dbConfig.kubectl !== undefined,
+            dbConfig.allowedMutations?.[env] ?? [],
           );
 
           return {
@@ -651,6 +659,7 @@ export class DbService extends Context.Service<
             port: envConfig.port,
             needsTunnel: accessMode.needsTunnel,
             allowMutations: accessMode.allowMutations,
+            allowedMutations: accessMode.allowedMutations,
           };
         };
 
@@ -663,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 = {